228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
# 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]` 而不是静默通过。
|