stc32g128k/开发规范.md

XAgent 项目协作流程（人工手动执行版）

平台造出来之前，我们先人工按这套方法在这个仓库里干活。正式的结构化定义在 .xagent/stages.json（文件夹模板）和 .xagent/graph.json（依赖与写锁账本），本文档是操作层面的"人手动怎么做"。

判脏已自动化：依赖关系（depends_on）由人声明，但"谁因为上游变了而过时（脏）"不再手工记 commit hash——运行 bash .xagent/check-dirty.sh 由 git 历史自动算出。

1. 七个环节 = docs/ 下七个目录

目录	环节	负责人设	类型
docs/10_requirements-overview/	总体需求	需求分析师	单文档
docs/20_requirements-detail/	细化需求	需求分析师	单文档
docs/30_architecture/	架构设计	架构师	单文档
docs/40_ui-design/	UI 设计	UI 设计师	单文档
docs/50_module-breakdown/	模块拆分	架构师	并行任务（一个模块一个文件）
docs/60_coding/ + src/**	编码实现	开发者	并行任务（一个模块一个文件 + 对应代码）
docs/70_testing/ + tests/**	测试	测试工程师	单文档 + 测试代码

任何目录下的任何文件，任何人、任何 AI，任何时间都可以改，没有"上一环节没做完就不能碰下一环节"的门禁——具体原则见 docs/10_requirements-overview/main.md 第 2 节。

2. 新建一份产出物，手动怎么做

1. 确定它属于哪个环节，放进对应目录；并行任务类目录（模块拆分、编码）里，每个模块/任务单独一个文件，文件名用模块名（例如 mod-auth.md）。
2. 打开 .xagent/stages.json，抄这个目录的 default_depends_on 作为这份文件依赖的起点，写进 .xagent/graph.json 的 files 里；并行任务类目录额外看 link_same_name_from，把同名的上游文件也加进 depends_on。只需填 depends_on 和 lock: null——不需要记任何 commit hash。
3. 找对应人设（见第 1 节表格）的 AI 一起起草内容——现在还没有 .xagent/roles/*.md 提示词文件，人工凭这份表格，手动跟 AI 说清楚"请用 XX 的视角帮我写"。
4. 人工审阅、编辑，确认后 git add + git commit。
5. 提交后跑 bash .xagent/check-dirty.sh 自检：新文件首次提交后即有基线，脚本据 git 历史自动判脏，无需手工登记。

3. 修改一份已有产出物，手动怎么做（写锁 + 脏检查）

现在没有软件强制加锁和自动判脏，这一步全靠人自觉遵守：

1. 占用（手动加锁）：开始改之前，把 .xagent/graph.json 里这份文件的 lock 字段填上 {"holder_type": "human"/"ai", "holder_id": "...", "acquired_at": "..."}，同时在群里说一声"我在改 XX"。别人看到 lock 非空，就不要同时改这份文件。
2. 改内容：跟对应人设的 AI 协作起草、人工审阅确认。
3. 释放（手动解锁）：改完提交后，把 lock 字段清成 null。
4. 自动判脏：改完提交后，跑 bash .xagent/check-dirty.sh。它会读 depends_on、用 git 历史列出"依赖你这份文件、且尚未跟进"的下游文件。把列出来的下游 @ 给相关负责人。
5. 被提醒的人复核后，把自己的文件改好并 git commit——提交即自动消脏，不用改任何 hash。（若确认上游变动对自己无影响，直接提交一次即可刷新基线。）

4. 现在靠人工代偿、以后平台要自动化的事情

现在怎么做（人工）	以后平台怎么做
手动填 graph.json 的 depends_on（仅依赖关系）	新建文件自动带入默认依赖
跑 check-dirty.sh 判脏（git 历史自动算，无需手记 hash）	实时自动判定，dirty 状态直接在界面标红
手动在 lock 字段占位、口头通知	编辑器里实时显示占用状态，防止误改
凭表格说明手动跟 AI 说"用 XX 视角"	按文件路径自动加载对应人设 prompt
讨论散落在群聊里	讨论侧栏跟对应产出物直接关联

5. 本项目当前进度

各项目自己维护这一节：按七环节结构列出 docs/ 下已完成、进行中、待补的产出物。新项目初始化时这一节为空，随开发推进逐步填写。