AGENTS.md · git:20261104.d35fbbf · 2026-11-04 · sha256 b9692c962d9ecf8a
AGENTS.md git:20261104.d35fbbfA
Immutable. This exact content never changes and is served at /api/v1/blob/b9692c962d9ecf8a.
# OpenDirector 开发指导 ## 文档职责 本文适用于整个仓库,规定长期有效的产品方向、架构原则和发展路径,供开发者及代码 Agent 共同遵循。 本文描述目标和决策依据,不代表其中所有能力已经实现。不要在此记录完成状态、当前缺陷、临时兼容分支、commit 编号或测试通过数量。具体需求、实施任务、差异分析和验证证据分别保存在对应文档中;判断实现情况必须核对代码与测试。 ## 产品方向 OpenDirector 面向用户与 Agent 协同完成视频创作。**用户与 Agent 在相同业务条件和授权范围内具有等价的创作能力**,覆盖素材管理、内容生成、媒体编辑、候选采用、时间线编排和视频导出。两者共同操作同一个工程,产生的内容都能由另一方继续编辑。 Agent 是提高视频创作效率的核心入口。用户可以直接表达创作目标,由 Agent 通过 Agent Loop 拆解任务、选择能力、安排依赖、执行操作、观察实际结果并调整后续步骤,减少逐项操作、重复输入和人工等待。效率提升应在创作要求、质量和资源约束下评估,不以少做必要工作或降低交付范围代替。 画布、时间线和编辑面板承担用户交互、内容查看与直接修改的职责。业务能力独立于这些界面存在,用户通过 UI 调用,Agent 通过 tool use 或 function calling 调用;画布的展示结构不限定 Agent 的能力或操作步骤。保留一致的视觉设计、流畅的交互、完整的模型接入与高级编辑能力。 右侧 AI 助手聊天框是用户与 Agent 的对话协作入口。用户通过自然语言提出目标、引用素材、委托任务、反馈结果和调整要求;Agent 结合工程上下文调用业务能力,反馈进度、结果及需要用户决定的事项。执行产生的真实内容同步到工程和画布,用户可以直接修改后继续通过对话委托,形成“对话委托—执行反馈—直接编辑—继续协作”的闭环。 能力等价以可执行的业务操作、规则和可继续编辑的结果为依据,不要求工具逐个对应按钮或模拟鼠标手势。用户可以手动操作、委托 Agent 或交错协作;授权、锁定和验收要求持续生效,Agent 不因具备能力而自动获得超出授权的决定权。 **统一项目模式的核心是:同一业务能力,共享命令、校验、工程状态、执行依据和回执。** 接口数量、传输协议或界面形式不能单独证明已经实现统一。 画布连线表达生成参考,时间线表达视频编排。参考关系不自动执行上下游任务,也不等于把视频按连线顺序拼接;任务顺序由用户或 Agent 明确安排。 ## 核心设计原则 ### 1. 用户与 Agent 能力等价,共用业务服务 - 每项创作能力从契约设计开始同时考虑 UI 和 Agent 入口。纳入交付范围的业务操作应能由两种入口完成,不将 Agent 长期限制为只支持生成或少数便捷工具。 - 用户直接操作与右侧 AI 助手对话共享工程上下文。聊天中的创作要求由 Agent 通过业务服务执行,对话回复中的承诺必须与实际操作回执和结果一致。 - 核心业务规则放在领域与应用服务中。HTTP、UI 适配和 Agent 工具负责参数转换、调用与结果呈现。 - 内置 Agent 可以直接调用应用服务,外部调用者可以通过 HTTP 或工具协议接入;不同入口执行相同业务规则。 - 工具围绕创建配置、添加参考、提交生成、采用结果、编辑时间线等创作意图设计,不要求每个按钮对应一个工具。 - Agent 可以通过批量和组合能力高效完成多步创作,用户仍能检查并继续编辑其中的对象和结果。业务语义一致不要求操作步骤、创作策略或开放式生成结果完全相同。 - 组合操作继续调用基础能力,并遵守版本、锁定、资源和事务约束。不同操作粒度不能成为绕过校验的路径。 - Agent 的正式操作通过业务对象及稳定身份完成,不依赖模拟鼠标、React Flow 运行实例或特定面板保持打开。 ### 2. 工程是业务事实的权威来源 - 后端项目存储拥有持久化业务事实。浏览器保存可重建缓存、界面偏好及明确的临时草稿,不维护另一份可独立修改的完整工程。 - React Flow 节点和边是工程对象的展示投影。允许乐观交互和局部草稿,但正式结果必须依据服务端回执确认。 - 业务对象能够脱离可见画布存在。隐藏展示对象不删除逻辑来源、素材、参考或历史;重新显示应保留其身份和关联。 - 来源项目的只读查询不申请编辑会话,不切换当前项目;跨项目复用将所需素材登记到目标项目,不依赖来源页面或临时 URL。 - 沿用项目目录、文件锁、原子写入和可恢复提交的存储机制;运行协调和模型凭证与工程内容分离。 ### 3. 分离生成意图、执行事实和当前采用 - 生成配置与参考表达下一次创作意图。 - 已接受任务固定本次实际素材、模型、参数及输入快照,后续编辑不改写这些依据。 - 结果、候选和当前采用分别记录。成功生成不自动取得覆盖当前内容的权限;自动采用必须遵守明确策略和当前版本校验。 - 应用历史版本通过明确的业务操作恢复对应范围,保持旧执行记录不变;独立的参数恢复、结果切换和完整版本应用具有各自语义。 - 文件生成、技术检查和创作质量验收分别表达,不把工具成功当作用户已经审看或批准。 ### 4. 能力与规则保持一致 - 节点媒体类型、业务角色和操作能力分别建模。上传到已有节点时按操作意图校验,不能隐式转换节点类型。 - 来源身份、参考关系身份、素材身份及内容指纹各司其职;同名或相同内容不能证明两个逻辑来源相同。 - 参考支持跟随来源当前版本及固定素材版本,执行前解析为确定输入。正文引用和画布连线共同投影真实参考关系。 - 所有入口共用文件探测、素材准备和校验基础,并按本体替换、生成参考、主体槽位、时间线等业务意图区分规则。 - 模型、模式、类型、数量、实际字节、聚合预算、锁定、对象版本及文件可用性由后端最终校验。UI 预检用于即时反馈。 - UI 可用操作和拒绝原因应从共用能力契约派生,避免各节点、面板及 Agent 分别维护业务规则。 ### 5. 异步操作可追踪、可恢复 - 修改使用稳定操作身份及必要的对象版本。同 ID 同输入重放返回原回执,同 ID 不同输入拒绝执行。 - 对象、素材、回执和变更记录按明确提交边界协调恢复;不能把局部写入描述为完整成功。 - 查询、预览、修改和长任务分别建模。查询不产生创作或会话切换副作用;长任务返回可查询的接受记录。 - 取消请求、远端取消确认、任务中断、未知提交、恢复原任务和新建尝试保持不同语义。未知提交不能通过换 ID 自动重发。 - 撤销只修改允许回退的工程内容,不能撤销远端调用、费用或既有执行事实。 - 工具任务可以保留独立类型和执行台账,但必须参与统一的素材依赖、删除保护、来源查询和变更通知。 - 已登记但未发布到目标的素材或结果保留可解释状态,失败重试不得静默重复创建。 ### 6. 同步与交互相互配合 - UI、Agent 与后台完成的正式变更进入同一可恢复通知通道。事件提示变化,项目查询提供权威状态。 - 按受影响对象更新界面,处理重复、乱序和断线;无法补取时重新获取快照。 - 后台更新保留用户的选择、焦点、播放头和未提交输入。冲突通过重新读取、比较与明确处理解决,不能自动换版本覆盖。 - 拖动和缩放使用客户端临时状态,完成交互后提交布局;避免逐指针写盘、重复扫描大媒体或在渲染中执行完整历史读取。 - 业务保存与界面状态保存分别确认。视口或偏好保存失败不能改变已提交业务的事实。 ## 对象职责 | 对象 | 主要职责 | | --- | --- | | Project | 稳定工程身份、对象范围和存储生命周期 | | Asset | 素材内容、不可变内容身份、指纹、媒体事实和实际来源 | | GenerationSpec | 可编辑的提示词、模型、参数和生成意图 | | Reference | 来源、生成目标、用途、顺序和版本策略 | | CanvasItem | 展示对象、位置、尺寸、层级、分组和锁定 | | 编辑文档 | 主体、图层、媒体编辑及时间线等可继续编辑的结构 | | Job / 工具任务 | 一次执行的固定输入、状态、远端身份和结果依据 | | 结果版本与采用关系 | 候选归属、历史以及当前明确采用的结果 | | 会话与 Agent 运行记录 | 右侧 AI 助手对话、引用快照、操作关联和执行上下文 | | ViewState | 选择、视口、活动编辑器、播放头等客户端状态 | 对象名称可以随实现调整,职责边界不能因方便界面存取而合并。节点的公共交互通过共享组件、类型化契约及能力组合实现,各类型只扩展专属内容和行为。 ## 发展路径 以下为按依赖推进的长期路径,不是当前进度表。按能力逐项建设共用服务、UI 和 Agent 入口,逐项验证能力等价与创作效率;不以“先完成所有画布功能,再开放部分工具”作为长期产品分层。 ### 路径一:建立独立于交互方式的创作能力 围绕素材管理、引用、生成、编辑、采用、时间线编排、导出和工程重开,建立类型化业务对象、命令、查询与执行服务。同步明确稳定身份、版本、回执、来源、历史和恢复边界,能力可在不操作画布界面的情况下调用。 验收重点是业务闭环实际可用、保存完整、失败可恢复,以及模型、媒体和高级编辑能力得到保留。 ### 路径二:建设等价的用户与 Agent 入口 将共用能力分别接入画布、时间线和编辑面板,以及 Agent 工具;通过右侧 AI 助手聊天框连接用户目标与 Agent 执行。参数 Schema、能力说明、校验与错误语义复用或派生;UI 支持精确直接操作,工具支持按创作意图调用及组合操作。 验收重点是纳入交付范围的业务操作有等价入口,相同意图、输入与约束产生一致业务语义,不存在只能靠点击界面完成的必要创作步骤。 ### 路径三:形成可随时接续的协作闭环 用户与 Agent 查询和修改相同对象。Agent 产生的素材、配置、参考、候选和时间线均为真实工程内容,用户可以检查、修改并继续委托;Agent 在继续执行前读取相关的新状态,尊重用户修改与锁定。 接入右侧 AI 助手的会话、草稿、消息引用快照和 Agent 运行记录。用户可在对话中提出目标、反馈结果、调整要求并继续执行;收起聊天框保留会话和已接受任务,停止回复、停止后续编排和取消已提交任务分别表达。按照用户已有授权连续执行,只有超出授权范围或需要创作取舍时才请求决定,不为每次工具调用机械增加确认。 验收重点是直接操作与聊天委托可以交错接续,对话进度与真实工程一致,双方操作不会丢失内容、绕过锁定或错误采用结果,用户无需重新搭建 Agent 已经完成的工程。 ### 路径四:提高端到端视频创作效率 Agent 根据创作目标选择能力、安排任务依赖,在允许时批量或并行处理独立工作,观察实际结果并调整后续步骤。通过减少重复操作、等待期间的人工跟进和不必要的重做,提高从创作意图到可用视频的效率。组合编排复用基础操作,不另建脱离工程的素材图或执行状态。 导出等必要业务步骤提供 Agent 可调用的执行入口,并明确其在客户端或后台运行的条件。若需求包含关闭浏览器后自主导出最终视频,必须提供可被后台调用的渲染能力;保留浏览器合成时,应准确表达需要客户端参与的范围。不能将工具可修改时间线等同于已经具备后台渲染。 验收重点是输出真实满足创作要求、任务可恢复、结果和采用范围可解释,并在可比任务下衡量端到端耗时、人工介入次数、重复操作及资源消耗。工具调用成功或调用次数增加本身不能证明效率提高。 ## 实施与验证约束 - 以模块化单体、清晰服务边界和可恢复后台任务起步;没有实际需求时不扩展为微服务、独立消息队列或通用工作流平台。 - 保留 OpenDirector 的界面、模型协议、适配与调度能力及高级编辑体验。采用外部设计时,直接描述业务语义并按上述对象边界适配,不依赖其他仓库或复制耦合实现。 - 优先修复共用服务、契约或公共组件中的问题,再补充类型专属逻辑;避免只为某个入口增加绕过规则的特例。 - 新默认入口切换以完整创作闭环为门槛。过渡适配须有明确边界和退出条件,不能长期维护两份可修改的业务事实。 - 不默认建设旧数据迁移或兼容层。不支持的格式明确拒绝,保留原工程和凭证,不自动删除或覆盖。 - 验证覆盖实际输入、持久化对象、执行快照和输出,不能只检查界面出现节点、引用标签或连线。 - 能力验收同时覆盖用户入口与 Agent 入口,包括编辑、采用、时间线及导出;效率验收使用真实端到端任务,避免仅凭工具数量或局部演示宣称目标达成。 - 按改动风险选择测试:共用规则与类型边界、命令幂等与冲突、故障恢复、UI/Agent 等价操作,以及真实媒体编辑和导出的代表场景。 - 区分模拟模型、真实文件验证和真实服务调用。性能结论需要可比较的测量,完成说明应准确报告验证范围与限制。 - 制作台、完整剧作及全剧交付体系、额外模型能力或后台渲染引擎,均须由明确需求驱动,不因“统一项目”自动扩大范围。 - 新增或修改用户可见界面时同步提供中文与英文词条,不在组件内硬编码单一语言。业务值(如 `auto`、工具 id、节点类型)保持稳定,只在显示层翻译;Agent 回复语言跟随用户提问语言,不跟随界面语言。 ## 文档维护 架构原则及发展方向发生变化时更新本文,不在此维护实现进度。正式文档以 [文档入口与维护规范](docs/README.md) 为索引,并随代码通过 Git 一同交付。 - [统一项目架构](docs/architecture/unified-project.md) 描述对象、业务边界与执行语义。 - [发展路线](docs/development/roadmap.md) 描述能力依赖、交付范围与验收门槛。 - [验证指南](docs/development/validation.md) 描述可复现检查和证据要求。 - [中英双语界面](docs/development/i18n.md) 描述语言选择、词条组织、审校入口和检查方式。 当前任务、缺陷和执行进度使用 Issue、PR 及必要的专题记录维护。文档索引只引用纳入 Git 的文件;开发机本地材料和相邻仓库不能成为其他开发者的必读依赖。相关设计与能力直接在本仓库解释,避免以其他产品名称代替具体语义。