# 03 · 执行协议（所有执行模型必读）

> 本协议约束每一个领取任务卡的模型。违反协议 = 交付无效，任务重派。

---

## 一、接单流程（强制顺序）

```text
1. 通读任务卡 → 确认「边界」段（哪些文件不许动）
2. 读项目根 README + 最近 2 份 PROGRESS/迭代报告（了解项目惯例与雷区）
3. 跑「基线测试」——确认开工前测试是绿的；有红的先记录，不背锅
4. 实施（最小变更原则）
5. 跑「验收命令」——全绿
6. 写 PROGRESS_<任务ID>.md 到项目根
7. 交付：代码 + PROGRESS + 关键命令输出摘要
```

**禁止跳步**：不读文档就动手、不跑基线就改代码、不跑验收就宣称完成——三者任一发生，交付直接打回。

---

## 二、PROGRESS 文件格式（交付凭证）

写到**项目根目录**，文件名 `PROGRESS_<任务ID>.md`：

```markdown
# PROGRESS — <任务ID> <任务名>

- 状态：done | partial | blocked
- 执行模型：<模型名>
- 日期：YYYY-MM-DD
- 分支/提交：<commit hash 或"未提交">

## 改动文件
- path/to/file1（新增/修改，一句话说明）
- path/to/file2

## 验收命令与结果
（粘贴关键输出，不要只写"通过"）

```bash
$ <命令>
<关键输出，最后一行是结论>
```

## 基线对照
- 开工前：<测试结果>
- 完工后：<测试结果>

## 遗留问题 / 下一模型注意事项
- ...
```

---

## 三、质量红线（硬性）

1. **不许伪造**：测试跑不绿就写 partial/blocked，附原始输出。伪造一次 = 该模型在该项目永久降级为 C 级。
2. **不许删测试**：既有测试只许更绿。删测试用例、跳过断言、注释掉失败用例 = 交付无效。
3. **不许夹带**：任务卡外的一律不做。看到顺手能修的 bug，写进 PROGRESS 的「遗留问题」，不顺手改。
4. **不许碰密钥**：`.env`、`~/.dsh/secrets`、`(服务器数据)` 目录——只读都不许，物理隔离。
5. **不许破坏契约**：改 API 响应结构/字段名必须保持向后兼容或双写过渡，并在 PROGRESS 说明。
6. **不许强推**：不执行 `git push --force`、不 rebase 他人提交、不 git reset 别人的改动。
7. **不许超时硬干**：预计超预算时，先交「阶段报告 + 断点说明」，让调度器续派，不许烂尾。

---

## 四、各项目雷区（前人踩过的坑，直接记）

### 可乐工具（chunyu）
- **vite 代理前缀匹配过宽**：`/api` 会连 `/api-docs` 一起劫持——改代理时必须用精确规则（见 C-01）。
- **生产 nginx 正则带尾斜杠**：`^/(api|user|...)/` 依然劫持子路径，改完前端要同步审查 `nginx-docker.conf`。
- 前端 67 页组件，路由引用散落各处——改路由名必须 grep 全量 `navigation(` 调用。
- 后端全异步（adrf）：新视图必须 async，不要写同步视图混挂。

### EnglishDrill
- **granian 孤儿 worker**：只杀父进程会留 worker 占端口，表现为"改了代码不生效"。用 `tools/devserver.ps1 restart`。
- **E2E 双模式**：`tests/e2e/run_e2e.py`（默认 ASGI 进程内 / `--http` 真实 granian）。隔离库 `backend/.tmp/e2e-db.sqlite3`，不碰开发库。
- **值收口层**：外部 id 必须走 `core/helpers.py` 的 `as_int` 等收口函数，禁止裸 `int()` 进 ORM（曾造成 44 处 5xx）。
- **stats 口径**：分类统计必须带 `is_deleted=False`，否则和 `/api/categories` 打架（BUG-2 教训）。
- 前端登录守卫在 `src/App.tsx:29`。

### dealerhub
- 460 passed / 4 skipped 是基线；4 个跳过是 PG 并发用例（D-02 处理）。
- 测试命令：`pytest`（在 `backend/`）；前端 `npm test` + `npm run build`。
- `makemigrations --check --dry-run` 必须干净。
- 演示数据重建：`seed_demo --reset`；改数据模型要同步改 seed。

### DSP
- 双端：Web（Vue3）+ Android；后端 Django + Channels。
- 转码依赖本地 ffmpeg；nginx 托管静态视频。
- 无 E2E 套件——S-01 会建；在此之前以 `backend/tests` 为准。

### DSH / 基础设施
- `~/.dsh/settings.yaml` 是**热配置**：改前备份（`.bak_<日期>`），改后 YAML 解析校验。插件曾覆盖式写入破坏能力声明（2026-09-08 事故）。
- 测试：`server/` 下 `pytest -q`，用独立测试库 `postgres_test`，conftest 拒绝在生产库跑。
- 探活：`GET /healthz`。

---

## 五、命令速查（执行模型常用）

```bash
# 可乐工具
cd chunyu_project && python manage.py runserver 8002        # 后端（开发）
cd chunyu_project_react && npm run dev                       # 前端 5173

# EnglishDrill
cd backend && python -m granian --interface asgi config.asgi:application --port 8756
python tests/e2e/run_e2e.py                                  # E2E（ASGI 模式）
python tests/e2e/run_e2e.py --http                           # E2E（真实 granian）

# dealerhub
cd backend && pytest -q
cd frontend && npm test && npm run build

# DSH
cd server && .venv/Scripts/python -m pytest -q
```

---

## 六、验收回执（规划者视角）

每个任务交付后，规划者按任务卡「验收标准」逐条核对：
1. 验收命令原始输出是否齐全、结论是否全绿；
2. 改动文件是否越界；
3. 基线是否未被破坏（对照开工前）；
4. PROGRESS 格式是否完整。

四查通过 → `done`；任一不过 → 打回并注明「哪条标准、缺什么证据」。

---

## 七、接力协议（Handoff Bundle / 断点续接）

> 由 I-04 落地。目的：**接手模型不重复问路、不重做已验证部分**。
> 工具：`PLANNING/tools/handoff_bundle.py`（只读，不改任何项目文件）

### 7.1 交接包标准（Handoff Bundle）

一份合格的交接包 = 六个部分，缺一即视为上下文不足，接手模型有权要求补充：

| # | 部分 | 内容 | 尺寸上限 |
|---|---|---|---|
| 0 | 接手须知 | 断点续接规则、密钥红线、交付定义 | 固定 |
| 1 | 任务卡全文 | 原文，硬约束的唯一来源 | 全文 |
| 2 | 作业规范 | 本协议 §一/§二/§三/§四 | 摘要 |
| 3 | 项目上下文 | README + 最近 2 份 PROGRESS | 90 行 / 70 行 |
| 4 | 相关源码清单 | 卡里点名过的路径 → 逐个核实存在性/大小/改动时间；未解析的给近似候选 | 自动 |
| 5 | 基线命令与输出 | 命令默认只列；`--run-baseline` 才真跑并抓取 | 每命令末 40 行 |

**生成命令**：

```bash
cd vscode/PLANNING
python tools/handoff_bundle.py C-01                     # 打到 stdout
python tools/handoff_bundle.py C-01 --out bundles/bundle-C-01.md
python tools/handoff_bundle.py C-01 --run-baseline      # 连基线输出一起抓（重型套件仍跳过）
python tools/handoff_bundle.py C-01 --run-baseline --include-heavy   # 连全量套件一起跑
```

基线命令登记在 `PLANNING/tools/project-baselines.json` —— **加新项目时补一条，不要改脚本**。

### 7.2 断点续接（上游交了 partial）

接手模型必须拿到并核对三件东西，缺一不接受续接：

1. **改动清单**：改了哪些文件 + 每个文件的 diff 摘要；
2. **测试状态**：哪些用例已绿、哪些仍红（附原始输出）；
3. **遗留问题**：上游 PROGRESS 的「遗留问题 / 下一模型注意事项」段。

处理顺序：

```text
读上游 PROGRESS → 复跑一遍上游声称已绿的验收命令（确认不是虚报）
→ 只从断点继续，不重做已验证部分
→ 完成后【更新】而非重写 PROGRESS_<ID>.md，追加自己的段落（标执行模型与日期）
```

**禁止**：推倒重来、丢弃上游已验证成果、把 partial 当 blocked 重新起一版。

### 7.3 调度器集成

`python tasks.py bundle C-01` 已内置轻量版交接包（卡 + 协议要点 + README + PROGRESS）；
需要源码清单与基线捕获时用 `tools/handoff_bundle.py`（本协议的完整实现）。

---

## 八、新模型入职 SOP（一页纸）

> 由 I-04 落地。工具：`PLANNING/evals/tools/run_eval.py`。全程 **30-40 分钟**。

```text
1. 前置：新模型网关可达 + 环境变量里有 key（key 只从环境变量读，工具不碰配置文件）
     PowerShell:  $env:DSH_API_KEY='<key>'
2. 自检题库（一次性，确认没被改坏）：
     cd vscode/PLANNING/evals && python tools/run_eval.py --audit
3. 跑评估（全新会话，逐题单发，不启用任何项目 skill 提示）：
     python tools/run_eval.py --model <新模型> --transport openai \
         --base-url <网关>/v1 --api-key-env DSH_API_KEY
   —— 或人工发题：python tools/run_eval.py --list-questions 逐条复制题面
4. 产出：evals/results/<模型>-<日期>.json / .md / .log.md
   自动项即时出分；人工项写入 .manual.template.json
5. 评委补判人工项 → 定稿等级：
     python tools/run_eval.py --manual results/<模型>-<日期>.manual.template.json
6. 成绩回填（**规划者执行，工具不自动写**）：
     - PLANNING/model-registry.json → 该模型 scores / grade / grade_basis / verified
     - PLANNING/01-模型分工矩阵.md → 对应行与派单范围
7. 首单观察：派一张低风险验证卡（推荐 D-02 或 I-01 辅助位），比对评估画像与真实交付
8. 合格 → 正式启用；不合格 → 降级/限场景，并在 registry 的 limits 里写明限制
```

**评估纪律（防作弊，见 `evals/README.md`）**：

- 题面文件里的「评分点」段**永不**发给被测模型（`--audit` 会硬校验题面不含评分点）；
- 每个模型一份独立的 dim4 fixture 副本，不污染原件；
- 单项超时按未完成计（runner 默认单题 600s，每维 ≤10 分钟）；
- 硬否决（dim5 <50% / dim4 伪造证据 / dim6 虚报验收）→ 直接 C 级，与总分无关。

**已登记规格缺陷（待规划者裁定，不由执行模型自行改）**：

- `SPEC-DEFECT-1`：`README.md §四` / `evals/README.md §四` / `evals/scoring.md §一` 称「满分 **36** 分」，
  但 `scoring.md` 维度表各行相加 = **42**，且与 16 道题面声明的分值合计一致。
  等级换算用百分比故不影响评级，但绝对总分口径需统一。
  `run_eval.py --audit` 会把它标为 `[KNOWN]` 而不是静默通过。