收尾两批并行开发的文档回写与任务包
- Sprint 执行计划 v1.1：§1.1 补第一批交付实据；T9 SPIKE 结论回写 Sprint 1 表 （T-P0-16 通过 2.8ms；T-P0-12 有条件；T-P0-10 原型 6/6 + 真实照片重验前置）； Sprint 2 表标注 T-P2-01~06 交付；新增 §9 两批交付记录 - 开发任务拆解 v1.5：交付回写 + 新风险登记（RTMPose 域差异、BiRefNet 异步化） - 新增 开发任务包/：三批多 agent 并行的协作规程与 14 份任务契约 - 新增 前置开通清单-云资源与资质.md - 清理已用毕的评审报告（文档评审 2026-08-13、项目整体评审 2026-08-14）， README 中相应引用改为留痕表述
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# 多 Agent 并行开发·协作规程
|
||||
|
||||
> 版本：v1.2 ｜ 2026-08-14 ｜ 前两批（T1~T5、T6~T11）已全部合并；本版适用第三批 **T12~T14**
|
||||
> **每个 agent 开工前必须先读本文件，再读自己的任务文档。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 本轮架构决策（为什么这样切）
|
||||
|
||||
六个任务按**文件所有权**切分：每个文件只属于一个任务。协调者（主会话）已提前在 main 分支做了一个「协调提交」，把**所有共享文件的改动一次性做完**（kb 七表迁移、ORM 模型、配置项、错误码、路由注册、依赖、gitignore）。因此：
|
||||
|
||||
- **你不需要碰任何共享文件**。如果你的任务文档说某配置/错误码/表已就绪，它就真的已就绪——直接用。
|
||||
- 禁改清单见你的任务文档。**改了禁改文件 = 合并时被整体丢弃**。
|
||||
|
||||
## 2. 环境操作手册（Windows 宿主 + WSL 仓库）
|
||||
|
||||
你的工作目录是 WSL 里的一个 **git worktree**（不是主仓库）：
|
||||
|
||||
| 任务 | worktree 路径（WSL） | 分支 |
|
||||
| --- | --- | --- |
|
||||
| T12 | `/home/xsl/meida_backend-t12` | `task/t12-admin-console` |
|
||||
| T13 | `/home/xsl/meida_backend-t13` | `task/t13-golden-ci` |
|
||||
| T14 | `/home/xsl/meida_backend-t14` | `task/t14-retrieval-cache` |
|
||||
|
||||
- **读写文件**：用 Read / Write / Edit 工具，路径写成 UNC 形式：
|
||||
`\\wsl.localhost\Ubuntu-22.04\home\xsl\meida_backend-t6\packages\...`
|
||||
（Edit 前必须先 Read 目标文件。）
|
||||
- **跑命令**（测试/lint/git）：
|
||||
```
|
||||
MSYS_NO_PATHCONV=1 wsl.exe -d Ubuntu-22.04 -e bash -c "cd /home/xsl/meida_backend-t6 && .venv/bin/pytest -q"
|
||||
```
|
||||
注意：venv 在**你自己的 worktree 里**（`.venv/bin/...`），不要用主仓库的（本批已含全部所需依赖，用 `--extra dev` 同步）。
|
||||
- PG(55432)/Redis(56379) 容器已在跑，`.env` 已复制到你的 worktree。
|
||||
|
||||
## 3. 提交前必须全绿（在你的 worktree 里）
|
||||
|
||||
```bash
|
||||
.venv/bin/ruff check . && .venv/bin/ruff format --check .
|
||||
.venv/bin/mypy <你的任务文档里指定的包列表>
|
||||
.venv/bin/lint-imports
|
||||
.venv/bin/pytest -q # 单测（不连库）
|
||||
# 若你的任务允许集成测试：
|
||||
MEIDA_RUN_INTEGRATION=1 .venv/bin/pytest -m integration -q --no-cov
|
||||
```
|
||||
|
||||
全绿后提交（**只提交一次，不要多次碎提交**）：
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "<你的任务文档里给定的提交信息>"
|
||||
```
|
||||
|
||||
**禁止 `git push`。禁止改动 `.git/`、禁止切分支、禁止 rebase/merge。**
|
||||
|
||||
## 4. 硬性纪律（违反任何一条 = 返工）
|
||||
|
||||
1. **禁改文件**以任务文档为准。通用禁改：`pyproject.toml`、`uv.lock`、`migrations/**`、`packages/shared/models.py`、`packages/shared/config.py`、`packages/shared/errors.py`、`.env.example`、`apps/api/main.py`、`apps/api/deps.py`、`.github/**`、`Makefile`、`scripts/smoke.sh`、`deploy/**`、`packages/domain/**`、`packages/llm/**`、`packages/billing/**`、`packages/agent/**`、`packages/task/**`、`packages/analytics/**`、`packages/storage/**`（除非任务文档明确允许某文件）。
|
||||
2. **不加任何新依赖**（不 `uv add`，不手写 import 第三方新包）。需要的库协调者已装（含 `spike` extra）。
|
||||
3. **不连外网**：单测禁止真实 HTTP。mock 方式参考 `tests/unit/test_deepseek_provider.py`（respx）与 `tests/integration/test_vertical_slice.py`（FakeProvider）。**唯一例外：T9 的模型下载脚本**（见其任务文档）。
|
||||
4. **代码风格对齐现状**：中文 docstring/注释（解释"为什么"）、`from __future__ import annotations`、frozen+slots dataclass、结构化日志 `get_logger(__name__)`、错误一律走 `AppError(ErrorCode.X)`、响应一律 `ok(...)` 信封。
|
||||
5. **mypy strict** 适用于 `packages/domain`、`packages/llm`（如果你改这两处，标注必须完整）。其余包按现有宽松档，但新代码仍应写满类型标注。
|
||||
6. **ruff line-length 100**；格式化用 `ruff format`。
|
||||
7. 测试文件放 `tests/unit/test_<主题>.py`；集成测试放 `tests/integration/test_<主题>.py` **新文件**。**本批任何人不得编辑已有测试文件**（上批例外已用尽）。
|
||||
8. **不修改现有测试的断言语义**。
|
||||
9. 遇到与任务文档冲突的现实情况（比如文档说的符号不存在）：**不要自行扩大范围**，在提交信息里写明偏差与原因。
|
||||
|
||||
## 5. 完成定义（DoD）
|
||||
|
||||
1. 任务文档「验收标准」全部满足；
|
||||
2. §3 的检查全绿；
|
||||
3. 新增代码有对应测试（纯逻辑必须有单测；涉及 DB 的路径按任务文档要求补集成测试）；
|
||||
4. 提交信息按任务文档给定格式，正文用中文说明实现了什么、测了什么、有何偏差。
|
||||
|
||||
## 6. 冲突隔离原理（知其所以然）
|
||||
|
||||
- 本批 3 个分支最终由协调者**顺序合并**，每合一个跑一轮全量门禁（含 `make golden`——CI 防线 5c）；
|
||||
- 你分支里的每一个文件改动，理论上不应与其它任务重叠——这是"并行不踩坑"的根本保证；
|
||||
- 如果你觉得"必须"改一个禁改文件才能完成任务：停下来，在提交信息里说明需求，由协调者在合并阶段统一处理。
|
||||
- 前两批（11 任务）用同样的方案跑完：零合并冲突，单测 169→473。照纪律执行即可。
|
||||
Reference in New Issue
Block a user