AGENTS.md git:20260905.787dde7A

Immutable. This exact content is served forever at /api/v1/blob/d8089d3fae29a106.

# OpenCreator 项目级 Agent 规则

## 执行效率与最小充分验证铁律

### 总原则

- 铁律：验证范围必须与改动风险和实际影响范围匹配。不得把小型、局部、低风险修改默认升级为全量测试、完整构建、服务重启、端到端测试或桌面打包。
- 铁律：先完成最小范围的代码定位和修改，再执行能够证明本次改动正确的最小验证集。只有验证结果表明存在更大影响时，才允许逐级扩大范围。
- 铁律：不得因为仓库存在无关的历史失败、脏工作区或其他模块问题而主动扩大当前任务；与本次改动无关的问题只需记录，不得顺手排查或修复。
- 用户明确要求完整测试、构建、打包、发布或跨平台一致性验证时，按用户要求执行，不受下述默认分级限制。

### 风险分级

- P0 低风险修改：文案、样式微调、默认值、局部展示条件、测试断言等不改变 Runtime/API/持久化协议的改动。
  - 默认只执行相关文件检查、最接近的定向测试；TypeScript 代码按需执行对应包的 `typecheck`。
  - 默认不执行全量测试、生产构建、端到端测试、Desktop 打包或服务重启。
- P1 中风险修改：共享状态、业务逻辑、持久化行为、跨组件交互、Runtime 请求参数或公共组件改动。
  - 执行受影响模块的定向测试和对应包的 `typecheck`。
  - 仅在涉及编译边界、懒加载、资源产物或构建配置时执行生产构建。
  - 仅在真实交互无法由定向测试充分覆盖时增加浏览器验证。
- P2 高风险修改：Daemon/Runtime、协议、数据库迁移、进程管理、服务配置、构建打包、发布链路或明确的 Web/Desktop 一致性改动。
  - 执行相关集成测试、构建、服务重启和健康检查。
  - 只有任务涉及 Desktop 或交付包时才执行 Desktop 构建、打包及一致性门禁。

### 服务操作

- 前端源码在正在运行的 Vite 开发服务下能够热更新时，不得仅为使页面生效而重启 Web 服务。
- 只有服务端代码、启动配置、环境变量、进程依赖发生变化，热更新失败，服务未启动，或用户明确要求时，才停止或重启对应服务。
- 重启前先确认目标端口和进程命令；重启后只验证对应服务和直接依赖的健康状态，避免无关服务操作。

### 验证升级条件

- 定向测试失败且失败与本次改动相关。
- 改动触及共享公共层，无法通过局部测试覆盖主要调用方。
- 类型检查或构建结果暴露跨模块影响。
- 用户要求更高等级验证，或任务目标本身是发布、打包、全流程验收、跨平台一致性。

### 交付说明

- 完成时只报告实际执行的验证，不得用未执行的全量验证暗示项目整体无回归。
- 若最小验证集已覆盖本次改动，应及时交付，不得为了形式上的“更完整”继续运行低收益验证。

## `opencreator-bug-fix` 使用铁律

- 铁律：普通开发、代码修复、体验优化和用户直接提出的需求，不得默认启用或附加 `opencreator-bug-fix` 流程。
- 只有用户明确要求读取、处理或回写 OpenCreator 飞书 Bug 文档时，才允许使用 `opencreator-bug-fix`。
- 未得到上述明确要求时，禁止因为任务看起来像 Bug 而读取飞书文档、执行文档闭环或按该流程自动创建 Git commit；应直接按当前需求完成代码修改与必要验证。

## Creator 模板协作面板架构铁律

- 铁律：视频翻译、封面生成、图像生成、视频生成及后续所有 Creator 模板必须共用唯一的 `CreatorCollaborationPanel`；禁止为单个模板复制或新建一套完整的 Agent Panel。
- 通用 Panel 统一负责 Agent 消息、Activity 时间线、Stage 状态卡、真实进度、审批、Composer、权限以及任务终止和继续。模板 Workspace 不得自行维护第二套消息、审批、SSE 或 Stage 展示逻辑。
- 模板差异只能通过 `CreatorPanelAdapter`、配置、回调或局部 slot 表达。Adapter 只负责 Stage/Phase/字段文案、Activity 语义化、进度标准化、Composer 默认提示和模板上下文摘要，不得复制通用交互框架。
- Workspace 只向通用 Panel 提供当前步骤、业务上下文、问题状态和快捷操作。真正只属于某个模板的能力可以使用局部 slot，但不得借此复制完整 Panel。
- 通用 Panel 禁止读取 `krillinEventPayload` 或其他执行器私有字段。Runtime 对外进度统一为 `phase`、`percent`、`message`、`completed`、`failed`、`total`；旧字段兼容只能存在于对应 Adapter 或 Runtime normalizer。
- 纯界面状态不得写入用户可见的创作动态，包括步骤索引、最远步骤、工作区页签、结果页签和草稿版本等 UI-only 字段。Activity 必须先语义化、过滤并合并连续同类更新。
- 未知模板必须使用 fallback adapter，显示稳定的通用文案，不得直接暴露内部 Stage ID、执行器名称或原始事件字段。
- 新增 Creator 模板时必须同时增加 Adapter 测试、Activity 过滤与去重测试、Stage 状态测试和真实进度测试；禁止以创建独立 Panel 作为交付方式。

## Web / Desktop 一致性铁律门禁

### 核心定义

- 铁律：OpenCreator 以 `apps/web` 作为唯一的前端实现和主要开发环境，Desktop 必须直接使用同一套 Web 前端构建产物，不得维护第二套页面、组件、样式或通用交互逻辑。
- 铁律：在相同业务数据、相同用户偏好和相同前端内容区尺寸下，Web 与 Desktop 的通用界面、文案、布局、状态、交互结果和 Runtime 请求必须一致。
- “一致”指通用产品能力一致，不要求浏览器模拟操作系统窗口、系统目录选择器、菜单栏、托盘和原生通知等系统能力。
- 不能因为 Web 和 Desktop 共用 React 代码就默认二者已经一致；一致性必须通过自动化测试和实际打包 App 验证。

### 通用能力铁律

- 默认项目、项目创建、项目选择、项目配置、会话、任务、计划、权限、模型、附件、文件编辑和其他业务能力必须由 Web 与 Desktop 共用的 Daemon/API/Service 实现。
- 通用业务不得分别为 Browser Bridge 和 Desktop Bridge 实现两套逻辑。
- 首次启动无项目时，Web 与 Desktop 必须得到相同的默认项目和可直接输入的会话状态，不得一端自动创建项目、另一端要求用户手动创建。
- 创建空白项目必须走统一的 Runtime 项目接口；Desktop Bridge 不得单独承担通用项目创建逻辑。
- Desktop Bridge 只负责必须依赖操作系统或 Electron 的能力，例如选择现有目录、解析文件夹拖放路径、窗口生命周期、菜单栏、托盘和原生通知。

### 平台能力铁律

- 禁止在共享 UI 中使用 `hostBridge.kind` 随意分叉通用业务、页面结构或样式。
- 平台差异必须通过明确的 capability 或可选回调表达，例如 `canSelectDirectory`、`canControlWindow`。
- 组件只能在能力真实可用时显示对应入口。禁止显示按钮后在处理函数中静默 `return`，禁止出现 Web 可见但点击无反应、Desktop 可正常操作的伪一致状态。
- 禁止为了“看起来一致”给不支持的平台传入空函数、假成功结果或无实际作用的回调。
- 平台专属 UI 必须保持局部、可识别、可单独测试，不得改变通用页面的主体布局和核心工作流。
- 当前允许的平台专属能力仅包括：
  - 选择或更换本机现有文件夹。
  - 读取文件夹拖放的真实系统路径。
  - Electron 窗口关闭、隐藏、菜单栏和托盘行为。
  - 原生系统通知及其后台生命周期。
  - 其他经需求明确确认、确实无法由本地 Daemon 提供的系统能力。

### 内容视口铁律

- Web 与 Desktop 的视觉对比必须使用相同的前端内容区尺寸，不能直接使用浏览器窗口外框和 Electron 窗口外框尺寸比较。
- Desktop 创建窗口时应优先保证内容区尺寸稳定；涉及响应式布局时必须验证 Electron 标题栏、系统边框和缩放比例不会错误触发断点。
- 相同内容区尺寸下，通用页面的主要 DOM、可见文案、关键元素尺寸和截图必须一致。

### 构建产物铁律

- Desktop 打包前必须重新构建当前工作区的 Web，禁止复用无法证明来源的旧 `apps/web/dist`。
- Desktop 包中嵌入的 Web 文件必须与本次 `apps/web/dist` 完全一致。
- 桌面构建清单必须至少记录 Git commit、工作区 dirty 状态、Web 构建标识或哈希、平台、架构和构建时间。
- 打包校验必须比较 App 内嵌 Web 资源与本次 Web 构建产物；不一致时必须终止打包。
- 不得通过手工复制、替换 App 内资源或跳过 Web 构建来制作可交付 App。

### 必须执行的一致性测试

以下测试是相关功能完成前的强制门禁，不是可选建议：

1. 使用同一个 Fake Daemon、相同项目、相同会话、相同本地偏好和相同内容视口，分别以 Browser Bridge 和 Desktop Bridge 渲染应用。
2. 对比首页、项目选择器、创建项目、设置页、会话输入区和文件工作区的通用可见文案、按钮、状态、关键尺寸和操作结果。
3. 验证两端执行同一通用操作时调用相同 Runtime API，并产生相同持久化结果。
4. 验证 Web 首次启动会自动获得默认项目，输入框立即可用。
5. 验证 Browser Bridge 下不显示目录选择、目录更换、窗口关闭等不可用的 Desktop 原生入口。
6. 验证 Desktop Bridge 下原生入口真实调用对应 Bridge 能力，不得只验证按钮存在。
7. 运行实际打包 App E2E，验证 Preload Bridge、`opencreator-app://` 页面、Runtime 代理、默认项目、核心输入流程和原生能力。
8. 校验 `apps/web/dist` 与 App 内嵌 Web 目录文件列表和内容哈希完全一致。

### 修改时的强制判断

- 修改 `apps/web` 页面、状态、Service、Host Bridge、Daemon 项目逻辑、Desktop Preload、窗口逻辑、协议代理或打包脚本时，必须判断是否影响 Web/Desktop 一致性。
- 新功能开发前必须先归类：
  - 通用产品能力：只实现一次，由 Web 和 Daemon 共用。
  - 系统原生能力：通过 capability 隔离，并提供平台专属测试。
- 修复一端问题时必须检查另一端的相同流程，不得只验证最初报告问题的平台。
- 如果发现两端不一致，必须先确认它是经过明确设计的平台差异，还是能力判断、数据源、旧构建产物、视口或测试缺失造成的缺陷。
- 未经明确需求确认，不得把现有不一致直接解释为“平台差异”。

### 完成声明门禁

- 未通过类型检查、相关单元测试、Web/Desktop 一致性测试和实际打包 App 验证时，不得声称相关功能已经完成、两端已经一致或可以发布。
- 如果当前环境无法运行其中某项验证，必须明确说明未验证内容、原因和残余风险。
- 发现 Web 与 Desktop 通用行为回归、App 嵌入旧 Web 产物、无效平台入口或首次启动状态不一致时，必须阻止发布，不得降级为普通提示。