# 多 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。照纪律执行即可。