多人协作开发
Infinite Canvas 的任务切分、代码归属、验证与交接规则
多人协作开发指南
本页是新协作者进入 Infinite Canvas 时的最短路径。具体执行约束以仓库根目录 AGENTS.md 为唯一真源；这里提供任务切分、代码归属和交接格式。
开始前
- 每台开发机只维护一个权威源码工作树；本项目维护者 Mac 上的真源是
/Users/mac/cypher/infinite-canvas，画布开发已冻结。其他贡献者可以使用自己的克隆路径，但不要同时维护相互分叉的副本。 - 阅读
AGENTS.md、docs/index.md、docs/plans/full-delivery-backlog.md，再读取与任务直接相关的领域文档。 外部贡献者还需要阅读根目录CONTRIBUTING.md和CLA.md。 - 运行
.agents/skills/infinite-canvas-collaboration/scripts/preflight.sh，确认分支、未提交文件、CodeGraph 和 AI 工作流配置。 修改协作规则、文档、CI 或 Skill 时，再运行.agents/skills/infinite-canvas-collaboration/scripts/audit_collaboration.py。 - 先用 CodeGraph 查询入口、调用链和影响范围，再读代码；不要先做全仓库文本扫描。
- 开始修改前写清楚：任务边界、负责目录、接口契约、最小验证、是否涉及数据库或生产。
远程任务必须遵循账号和传输边界：Kevin 阿里云 profile 只用于从服务器侧连接 ecs50，不在本地 Mac 调用；OSS 上传、下载和跨桶搬迁使用同区内网端点，凭据只通过运行环境传递，不进入日志、文档、Git diff 或交接记录。
代码归属
| 需求 | 默认归属 | 边界 |
|---|---|---|
| 页面、Canvas 交互、浏览器 BFF | web/ | Route Handler 只做入参、鉴权、服务调用和统一错误 |
| 模型与供应商兼容、任务提交/轮询 | proxy/ | 不承载视频数据集领域逻辑 |
| 转码、裁剪、拼接、智能尾帧 | media-worker/ | 不承载审核和数据集评分 |
| 探测、切镜、清洗、审核、导出 | video-dataset-engine/ | 保持独立迁移、领域服务和 Worker |
| 本地 Agent、工具队列和确认 | canvas-agent/ | 不直接耦合外部业务系统 |
| CM、DramaClaw、OpenCut、Priya Live、VFE 等外部系统 | 对应 BFF adapter 与 typed client | 保留路径/方法白名单、服务端鉴权、超时、请求 ID 和统一错误 envelope |
| ComfyUI 工作流和模型资产 | GPU 主机上的 comfy_admin 工作区 | 递归检查子图依赖；所有承载实例和全新浏览器上下文都要验收 |
| 部署、运行时验收、回滚 | deploy/、scripts/ | 本地只改代码；耗时和服务级验证放到 ecs110 隔离目录 |
跨层调用默认遵循：web route → web/src/lib/server/<domain> → web/src/services/api/<domain>；共享状态进入 store/hook，页面私有逻辑留在页面目录。
并行开发规则
- 每个任务只认一个负责人和一组负责文件；共享契约文件要明确串行修改人。
- 开始前记录基线完整 SHA；交接时记录实际 HEAD、相对基线的提交和未提交文件。
- 不覆盖、清理或暂存不属于当前任务的改动；发现重叠先缩小任务边界。
- 每个并行任务使用独立分支或 worktree；开始前登记负责人、目录范围和依赖的上游任务，结束后明确是否可删除该 worktree。
- 数据库、API envelope、模型 ID、工作流名称和生成参数都是跨任务契约，变更时同步迁移、文档和契约测试。
- “代码完成”“隔离验证完成”“推送完成”“生产验收完成”是四个不同状态，不混写。
验证矩阵
| 改动 | 最小验证 |
|---|---|
| Web 纯逻辑/组件 | 相关单测、类型检查；交互变更再做目标页面浏览器验收 |
| Route Handler/BFF | handler 单测、鉴权、错误 envelope、请求 ID、超时 |
| Proxy | 相关 pytest；模型/媒体变更补真实供应商或 GPU 探测 |
| Media Worker | 相关 pytest；媒体结果必须解码，视觉任务还要查看结果或关键帧 |
| VDE | 相关领域/API/Worker 测试；迁移必须在独立 PostgreSQL 验证 |
| Canvas Agent | bun test 的相关测试；确认队列与恢复行为按需做集成验证 |
| ComfyUI 工作流 | 递归依赖检查、全部承载实例、全新浏览器加载、捕获最终 app.queuePrompt() payload、同版本后端严格校验 |
| 生产发布 | 同一候选 SHA 在 ecs110 验证，推送后按完整 SHA 窄部署，再运行生产验收脚本 |
每轮修改通过最小验证后，执行 Open Code Review，只修复本轮直接相关的高置信度问题，然后重新验证和复审。
没有 ecs110、GPU 或生产权限的外部贡献者应在交接和 PR 中标记相关验证未执行，由维护者在合并或发布前补做；不通过共享服务器账号或生产凭据扩大权限。
提交 PR 时使用 .github/pull_request_template.md。PR CI 会检查 Web、Proxy、Media Worker、Video Dataset Engine、Canvas Agent 和文档站；CI 通过不替代真实供应商、GPU、浏览器或生产验收。
交接模板
### 任务
- 目标：
- 范围内：
- 范围外：
### Git
- 基线 SHA：
- 当前 HEAD：
- 分支：
- 提交：
- 未提交文件：
### 变更
- 代码路径：
- 契约/迁移：
- 文档：
### 验证
- 命令：
- 结果：
- 未执行及原因：
### 风险与后续
- 风险：
- 回滚：
- 下一位负责人和下一动作：事实与实时状态
长期事实写进 AGENTS.md、领域文档或项目 Skill；任务状态写进 todo.mdx / pending-test.mdx；生产 SHA、容器、队列、模型可用性和远端分支属于实时状态，交接前必须重新查询，不写成长期记忆。