52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
# 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/` 下已完成、进行中、待补的产出物。新项目初始化时这一节为空，随开发推进逐步填写。
|