多 AI 协作规范#

本文档用于多个 AI、开发者或自动化代理同时维护同一工作树。目标是让每个参与者独立定位事实、控制改动边界，并把未完成状态无损交给下一位参与者。

1. 开始任务前#

每个参与者先执行只读检查：

git status --short
git diff --stat
rg --files

然后阅读 doc/README.md、doc/维护手册.md 以及任务相关的专项文档和测试。

默认所有既有未提交改动都属于其他参与者。不得用 checkout、reset、覆盖写入或批量格式化清除它们。

2. 任务拆分原则#

并行任务按所有权边界拆分，而不是随意分配文件。

适合并行：

独立测试与静态审计
不同业务子系统
文档与代码实现
普通版与绿色版的只读验证

不适合并行：

同时修改同一个大型文件
一方修改接口，另一方在不知道新契约时修改调用方
多方同时运行会重写源码或 tracked 文件的工具
未明确所有者的全仓格式化、重命名或删除

每个子任务声明目标、拥有的文件或模块、不可触碰范围、预期接口和验证命令。

3. 文件所有权#

一个文件同一时间只有一个写入所有者。
其他参与者可以只读检查，但不能同时编辑。
跨文件接口由接口所有者先给出最终签名和行为，再由调用方所有者迁移。
发现目标文件已有新改动时，重新读取并融合，不假设它仍与任务开始时相同。
删除文件前扫描静态引用，并检查动态导入、注册表、打包白名单和文档引用。

推荐任务声明：

任务：收敛音乐设置持久化
所有权：lib/script/music/**、相关测试
共享接口：config.general_user_settings.save_general_values
不触碰：工作台布局、游戏包格式
验收：音乐测试 + 全量 compileall

4. 事实与假设#

交接中区分：

已验证事实：附路径、符号或命令结果。
实现决策：说明选定方案和兼容边界。
未验证假设：明确标记，不得写成项目事实。

不要依赖聊天上下文保存关键结论。稳定结论写入代码、测试或维护文档，临时状态写入交接记录。

5. 改动规则#

手工修改保持最小范围，不顺手重构无关模块。
不修改用户数据、日志、缓存和大型资源。
不运行会重写 tracked 文件的格式化器，除非任务明确拥有这些文件。
默认配置与用户数据分离，禁止业务代码改写 config/config_*.py。
新增兼容层必须有明确调用方、移除条件和测试。
跨模块契约变化必须同步测试与文档。

6. 冲突处理#

遇到重叠改动时：

停止写入目标文件。
重新读取当前文件和 git diff。
判断两组改动能否按行为合并。
能合并则保留双方意图，并运行覆盖两者的测试。
无法判断产品意图时，将冲突、候选方案和影响交给主协调者。

禁止通过恢复旧版本解决冲突，这会丢失其他参与者的工作。

7. 验证分层#

每个参与者先运行负责模块的最小测试，主协调者负责最终全量验证。

参与者：语法检查 -> 模块测试 -> 接口引用扫描
主协调者：compileall -> 全量 unittest -> 打包 dry-run -> diff 审计

测试失败时记录首个真实失败和根因。不要把授权等待、字体警告或零匹配的 rg 退出码误判成代码失败。

8. 标准交接格式#

## 目标
一句话说明任务及完成标准。

## 已完成
- 行为变化及关键文件。

## 接口变化
- 新增、删除或改变的公开/内部接口。

## 验证
- `完整命令`：通过/失败，关键结果。

## 当前工作树
- 本任务修改文件。
- 开始前已存在、未触碰的改动。

## 剩余事项
- 尚未完成的具体步骤；没有则写“无”。

## 风险与假设
- 未验证的外部条件、资源缺失或兼容风险。

交接不得只写“基本完成”“剩下测试”等模糊状态。

9. 主协调者收尾#

汇总所有参与者的文件所有权与接口变化。
检查相互覆盖或重复实现。
搜索旧接口、旧路径和历史文档残留。
运行维护手册中的完整验证矩阵。
检查 git diff --check 和最终 git status --short。
在结果中区分本轮改动与任务开始前已有改动。
不自动提交，除非用户明确要求。