projectAIpopular/实现方案_v2_端云协同编程智能体系统.md

# 实现方案 v2：端云协同编程智能体系统（Agent 交接执行版）

> 编写日期：2026-08-30
> 状态：**当前权威规划**。方向上取代 v1《实现方案_多专业小模型+路由模型.md》与《任务拆解与执行计划.md》的路线；
> v1 的 L0 专家系统内核**不删除**，降级为离线降级模式与可解释基线（见 5.4）。
> 预期读者：负责实现的 AI Agent 或开发者。本文自包含。实现前必读：第 3 节（不得推翻的设计决策）、第 8 节（工程规约）。

---

## 0. 一页速览

**目标**：把仓库现有的 mock 原型升级为可安装、可演示、可量化的真实系统。

- **大模型（API，默认 DeepSeek）**：只做三件事——开局任务分析（brief）、中途疑难决策（decide）、最终审校（final review）。每次输入压缩到约 1K token 量级。
- **小模型（本地 llama.cpp，捆绑分发）**：默认 Qwen3.5-4B（Q4_K_M），负责实现与自验证。
- **协作媒介**：「交流文本」——一份 schema 约束的结构化 JSON 共享工作区（第 4 节）。两模型互不共享内部状态，只通过它交接（类比前后端通过 API 契约协作）。
- **人工检验**：第三个协作者，复用同一协议，异步队列，不阻塞响应路径。

**一句话流程**：
用户 query →（快路径）小模型直答＋自验证通过即返回 → 否则大模型写 brief → 小模型逐步实现（代码/文件类任务经受限工具集直接读写工作目录、运行命令与测试，类主流编码 agent 循环）＋自验证，失败自修 ≤2 次后写 issue → 大模型按 issue 决策（或兜底代做）→ 循环至满足验收标准 → 大模型终审 → 交付 / 人工检验队列。

**系统能力定位**：编程智能体（Coding Agent）——代码/文件类任务由 Worker 在独立工作目录中以受限工具集（read/write/edit/run）完成，产物即文件；问答类请求走快路径直答（不启用工具）。
**论文题目（已定）**：《基于端云协同的编程智能体系统设计与实现》
Design and Implementation of a Programming Agent System Based on Device-Cloud Collaboration
关键词：端云协同；编程智能体；大小模型协同；工具调用；级联升级

**北极星指标**：在端到端质量不低于纯小模型直答的前提下，大模型 token 消耗相对"全量上下文"方案下降 ≥80%（可实测，见第 9 节 E1）。

**核心经济学原则**：贵的一方（API）少读少写，便宜的一方（本地）多读多干。

---

## 1. 背景与现状

### 1.1 为什么从 v1 转向（决策记录）

1. **领域分类路线确认放弃**。规则分类器在 9 域平衡集上仅 74.4%、68.9% 请求触发升级
   （实测见 `research/routerarena/01_results_and_gap_analysis.md`）；原计划的"微调分类器"依赖训练数据与训练环境，不符合当前约束。
2. **v1 执行层是模板填充，系统实际不能回答问题**——必须接入真实模型。
3. **用户新约束**：本地运行时的长上下文能力、参数量尽可能少、长上下文下低内存占用、
   模型切换间最大 token 节约。由此设计出"交流文本"协议（第 4 节）。

### 1.2 现有资产盘点

| 文件/模块 | 处置 | 说明 |
|---|---|---|
| `router_system/memory.py`（WorkingMemory/TaskGraph） | **改造** | 黑板思想升级为持久化 workspace；TaskGraph 的依赖处理思路可参考，但 plan 改为简单列表+deps |
| `router_system/experts.py`（APIExpert） | **复用** | OpenAI 兼容客户端，llama-server 与 DeepSeek 都能接；需补超时、token 计量、messages 参数化 |
| `router_system/fallback.py`（APIFallback） | **复用** | 大模型兜底直连可用 |
| `router_system/judge.py`（RuleJudge 的 facts 核对） | **部分复用** | facts 对照逻辑迁入接地验证（5.1 T5）；LLMJudge 退役 |
| `router_system/trace.py`（TraceStore） | **复用** | 协作轨迹落点，每回合写入 |
| `router_system/cache.py` | **复用** | 快路径结果缓存 |
| `router_system/classifier.py`、`planner.py`、`config.yaml` 的 `domain_groups` | **退役出主链路** | 保留在 legacy 路由（`POST /chat/legacy`）与既有测试中 |
| `router_system/knowledge.py` + `config/knowledge/*.yaml` | **复用** | facts 表转作验证接地素材（不再用于分类） |
| `gateway/api.py` | **扩展** | 新增 `/runs`、`/review` 端点；`/chat` 切到新管线 |
| `scripts/eval.py`、`scripts/serve.py`、`scripts/demo.py` | **扩展/新增** | 新增 `scripts/setup_runtime.py`（下载运行时与模型）、`scripts/bench_tokens.py`（实验） |
| `research/routerarena/*`、`research/2026_papers_survey.md` | **保留** | 评测方法学与文献引用来源 |
| v1 测试套件（126 项） | **必须保持全绿** | legacy 路由不回归（见 D10） |

---

## 2. 架构总览

```
用户 query
   │
   ▼
[快路径] Worker 小模型直答 + 自验证通过？ ──是──▶ 直接返回（约 40-50% 请求）
   │ 否（或自评不确定）
   ▼
[Architect·API·一次] 任务分析 → 写 交流文本.brief（goal/constraints/acceptance/plan/tags）
   │
   ▼
┌──────────── 协作循环（护栏内，见 D6）────────────┐
│  [Worker·本地] 读 brief＋当前 step 相关上下文      │
│     → 实现（写工件 artifacts/）                    │
│     → 自验证（接地优先：跑代码/facts 对照/结构检查）  │
│     → 通过：写 progress；失败：自修 ≤2 次           │
│     → 仍失败：写 issue 条目（增量、带锚点）          │
│  [Architect·API·按需] 只读 issues＋锚点片段渲染      │
│     → 写 decisions / 修订 plan / 兜底代做该 step    │
└──────────────────────────────────────────────┘
   │ 所有 step done
   ▼
[Architect·API·一次] 终审（读 archive 摘要＋成品关键段）→ done / 打回修正
   │
   ▼
交付响应 + 入人工检验队列（抽样 / 强制规则：brief.tags 含 safety）
```

组件与职责：

| 组件 | 运行位置 | 职责 |
|---|---|---|
| `CollaborativePipeline`（编排） | 本进程 | 快路径判定、循环控制、预算熔断、状态机推进 |
| `ArchitectClient`（大模型） | DeepSeek API | brief / decide / final_review，全部 JSON Schema 约束输出 |
| `WorkerLoop`（小模型） | llama-server 子进程 | 工具化实现（受限工具集操控工作目录）、自验证、自修、写 progress/issue |
| `Workspace`（交流文本） | 磁盘 JSON | 唯一共享状态，schema 校验，锚点寻址，rollup 压缩 |
| `LlamaServerManager`（运维） | 本进程 | 子进程启停、健康检查、崩溃重启、三档硬件模板 |
| `ReviewQueue`（人工检验） | SQLite | 异步队列、审核端点、修正数据留存 |

---

## 3. 关键设计决策（实现时**不得擅自推翻**）

- **D1** llama.cpp 只捆绑上游官方 release 二进制（锁版本，放 `bin/`，gitignore），**禁止修改 llama.cpp 源码或自行编译**。
- **D2** 交流文本是**单一 JSON 文档**（`runs/<request_id>/workspace.json`），brief 写入后不可变且恒定位于文档前部（prefix cache 友好）；所有写入必须通过 schema 校验。
- **D3** 领域分类器退役出主链路；入口默认**快路径**（小模型先试，省 API 钱），brief 中的 `tags` 仅用于安全标记与验证接地，不做路由。
- **D4** 验证分层优先级：**可执行验证（跑代码/跑测试）> facts 对照 > 结构检查 > 模型自由判断（最后手段）**。
- **D5** 单 llama-server 实例单模型；默认 Qwen3.5-4B Q4_K_M；三档硬件模板（6.2）；验证器异构（换载 GLM 等）只作为**可选扩展**，MVP 不做。
- **D6** 预算护栏硬熔断：`rounds_cap`（协作循环回合上限）、`api_token_cap`（API token 上限）任一触顶即退出循环；熔断行为 = Architect 兜底代做（有 key）或本地降级提示（无 key）。
- **D7** Architect 的输入**永不包含工件全文**，只含 meta+issues+decisions+锚点片段，渲染目标 ≤1200 token（`Workspace.render_for_architect`）。
- **D8** Windows 优先；核心包 `router_system/` 保持零第三方依赖（纯标准库）；运维层/网关可用 httpx、fastapi、pydantic（均已在 requirements.txt）。
- **D9** 所有 LLM 结构化输出必须 JSON Schema 约束：llama-server 用 `response_format: json_schema`（或 GBNF），DeepSeek 用 `response_format: {"type": "json_object"}` + prompt 内嵌 schema；解析失败重试一次，仍失败走降级路径，禁止带病继续。
- **D10** v1 的 126 项测试保持全绿；legacy 路由（`POST /chat/legacy`）行为不变，保证离线可跑、测试封闭。
- **D11** 新模块的单元测试必须封闭可跑：API 调用用 `httpx.MockTransport` 注入假响应，**不依赖**真实 llama-server 或 API key。
- **D12** Worker 工具调用必须受限：工具集固定为 list/read/write/edit/run 五种；作用域仅限 `runs/<id>/` 工作目录内；每 step 工具调用次数上限（默认 20）；run 类命令强制超时并回收子进程；所有调用（含参数摘要与退出码）入 trace。Windows 沙箱以"目录限制＋超时＋进程回收"为准，不承诺禁网（作为 limitation 写明）。

---

## 4. 交流文本协议规范

### 4.1 存储布局

```
runs/<request_id>/
├── workspace.json        # 交流文本本体（唯一共享状态）
└── artifacts/            # Worker 工作目录：工具调用的作用域（实现产物即文件）
    ├── s1_main.py
    └── s2_tests.py
```

锚点寻址：`a://s2_tests.py#L12-18`，目标即工作目录内文件（Worker 用工具写入、Architect 按锚点取片段，编排层每个 issue 最多附带 30 行）。

### 4.2 Workspace JSON Schema

实现为 `router_system/workspace.py` 内嵌常量 `WORKSPACE_SCHEMA`（draft-07），要点如下（字段长度上限同时是 rollup 依据）：

```jsonc
{
  "version": "1.0",
  "request_id": "hex12",
  "query": "用户原始需求（写入后不可变）",
  "meta": {
    "status": "draft|in_progress|reviewing|escalated|done|failed",
    "round": 0,
    "budget": {"api_input_tokens": 0, "api_output_tokens": 0,
               "api_token_cap": 8000, "rounds_cap": 6}
  },
  "brief": {                              // Architect 写一次后锁定
    "goal": "≤500字",
    "constraints": ["≤8条"],
    "tags": ["code|math|legal|medical|finance|life|education|general|safety"],
    "acceptance": [{"id": "a1", "check": "验收标准描述", "machine_checkable": true}],
    "plan": [{"id": "s1", "task": "≤300字", "deps": ["s0"], "done_criteria": "可观察判据"}]  // ≤5 步
  },
  "progress": [ {"step": "s1", "status": "done|failed|blocked",
                 "summary": "≤200字", "artifact": "a://s1_main.py"} ],
  "issues": [ {"id": "i1", "step": "s2", "anchor": "a://s2_main.py#L12-18",
               "observed": "≤300字", "expected": "≤300字",
               "tried": "已尝试的修复，≤300字", "ask": "请求架构师裁决的问题"} ],
  "decisions": [ {"ref": "i1", "reply": "≤600字",
                  "patch_plan": [{"id": "s2", "task": "修订后的任务"}]} ],
  "archive": [ "s1: 快排实现20行，测试3/3通过（详情 artifacts/s1_main.py）" ]  // 每条 ≤160字
}
```

### 4.3 状态机

```
draft ──write brief──▶ in_progress ──所有 step done──▶ reviewing ──pass──▶ done
                          │  ▲                            └──fail──▶ in_progress（修正回合+1）
                 issue 上报│  │decision 下发 / 兜底代做
                          ▼  │
                 （回合数/budget 未触顶）
                          │ 触顶 rounds_cap 或 api_token_cap
                          ▼
                      escalated ──Architect 兜底代做──▶ reviewing
任何终态 ──▶ 入 ReviewQueue（抽样率或 safety 强制）
```

### 4.4 双方渲染规则（token 节约的核心实现）

- `render_for_architect(ws)`：meta＋query（截断 200 字）＋**全部 issues**＋最近 3 条 decisions＋最近回合的 progress 摘要＋每个 issue 的锚点片段（≤30 行）。**目标 ≤1200 token，超限先截断最旧 decisions。**
- `render_for_worker(ws, step_id)`：brief 全文＋该 step 定义＋依赖 step 的 archive 摘要行＋该 step 现有工件全文（若存在）＋验收标准。**目标 ≤8K token**（小模型长上下文"中间迷失"的补偿：重要信息前置、总量受控）。

### 4.5 rollup 压缩规则

- step 标记 done 后，Worker 顺手生成 ≤60 字摘要进 `archive`，工件本体只在 artifacts/ 落盘。
- workspace.json 主体超过 4K token 时，编排层强制压缩：将已 done 的 progress 条目折叠为 archive 行、截断已解决的 issues（保留 id 与结论行）。
- 归档**只减不删**：压缩前的原文不保留（可控成本换取协议简单），如需审计走 TraceStore。

### 4.6 校验与容错

- 所有写入（brief/progress/issues/decisions）先过 schema；失败 → 将原始输出与错误一并回喂该模型重写一次 → 仍失败由编排层做保守修复（截断超长字段、丢弃多余条目）并记录 trace 告警。

---

## 5. 组件设计与文件规划

### 5.1 新增模块（每个含中文 docstring、工厂函数、独立单测）

| 文件 | 职责与关键接口 | 对应任务 |
|---|---|---|
| `runtime/__init__.py` | 运维层包 | T2 |
| `runtime/hw_profile.py` | `detect() -> {"tier": "gpu12|gpu8|cpu", "ngl": int, "ctx": int, "kv_quant": str}`；探测 nvidia-smi/vulkaninfo/内存，失败回退 cpu 档 | T2 |
| `runtime/llama_server.py` | `LlamaServerManager`: `start()/stop()/ensure_alive()/endpoint()`；子进程管理、/health 轮询、指数退避重启、日志落 `runs/llama_server.log` | T2 |
| `router_system/workspace.py` | `Workspace`: `new/apply_brief/add_progress/add_issue/add_decision/rollup/render_for_architect/render_for_worker/validate/save`；内嵌 `WORKSPACE_SCHEMA` | T4 |
| `router_system/architect.py` | `ArchitectClient`: `brief(query)/decide(ws)/final_review(ws) -> dict`；httpx 调 DeepSeek，JSON 约束输出，token 计量回写 meta.budget | T3 |
| `router_system/worker.py` | `WorkerLoop`: `run_step(ws, step) -> StepOutcome`；受限工具循环（list/read/write/edit/run，D12 约束）实现→验证→自修≤2→issue；验证器按 D4 分层：code 域沙箱执行（run 工具跑测试，tempdir、超时）、facts 对照（复用 KnowledgeBase.facts）、结构检查 | T5 |
| `router_system/pipeline.py` | `CollaborativePipeline`: `run(query) -> RouterResult`；快路径→循环→熔断→兜底→终审→入审核队列；对接 TraceStore 与 Stats | T6 |
| `router_system/review.py` | `ReviewQueue`: SQLite（`data/review.sqlite3`）；`enqueue/get/list/submit(verdict, correction)` | T8 |
| `scripts/setup_runtime.py` | 下载 llama-server release（GitHub，提供镜像说明）与默认 GGUF（hf-mirror.com，断点续传、文件大小校验）到 `bin/`、`models/`（均 gitignore） | T11 |
| `scripts/bench_tokens.py` | E1 实验脚本（第 9 节） | T12 |

### 5.2 config/config.yaml v2（新增段，v1 段保留供 legacy 路由）

```yaml
runtime:
  llama_server:
    binary: bin/llama-server.exe        # 捆绑上游 release，不改源码（D1）
    model: models/qwen3.5-4b-q4_k_m.gguf
    port: 8901
    hw_profile: auto                    # auto | gpu12 | gpu8 | cpu
    extra_args: ["-fa", "-ctk", "q8_0", "-ctv", "q8_0", "--cache-reuse", "256"]
  tiers:                                # 三档硬件模板（保守默认，可手动覆盖）
    gpu12: {ngl: 99, ctx: 32768}
    gpu8:  {ngl: 14, ctx: 16384}
    cpu:   {ngl: 0,  ctx: 8192}

architect:                              # 大模型（API）
  model: deepseek-chat
  base_url: https://api.deepseek.com/v1
  api_key_env: DEEPSEEK_API_KEY
  temperature: 0.2
  timeout_s: 60

worker:                                 # 小模型（本地）
  backend: llama_server
  temperature: 0.3
  max_fix_attempts: 2
  per_step_timeout_s: 300

pipeline:
  fast_path: true
  rounds_cap: 6
  api_token_cap: 8000
  breach_policy: architect_do           # architect_do | local_only

review:
  queue_db: data/review.sqlite3
  sample_rate: 0.10                     # 随机抽样送审
  force_tags: [safety]                  # brief.tags 命中即强制送审
```

### 5.3 网关 API 变更（gateway/api.py）

| 端点 | 变更 |
|---|---|
| `POST /chat` | 切到 `CollaborativePipeline`；响应增加 `request_id`、`rounds_used`、`api_tokens`、`fast_path` 字段 |
| `POST /chat/legacy` | **新增**，原 v1 L0 行为原样保留（离线降级 + 测试封闭） |
| `GET /runs/{request_id}/workspace` | **新增**，返回交流文本（脱敏可选） |
| `GET /runs/{request_id}/artifacts/{name}` | **新增**，下载工件 |
| `GET /review/queue`、`POST /review/{id}` | **新增**，人工检验（verdict: approve/edit/reject ＋ correction 文本） |
| `GET /metrics` | 扩展：api tokens 累计、fast_path 命中率、回合数分布、熔断次数 |

### 5.4 退役/降级清单

- `classifier.py`、`planner.py`、`experts.py` 的 MockExpert/HFExpert、v1 `router.py`：整体归入 **legacy 路由**，由 `build_router()` 构造，仅 `POST /chat/legacy` 与既有测试使用；`domain_groups` 配置保留不动。
- `judge.py` 的 `LLMJudge` 类：标记 deprecated，不再被 v2 引用。
- 知识库 facts：`KnowledgeBase.facts(domain)` 保留，作为 Worker 接地验证素材；domain 来源改为 `brief.tags`。

---

## 6. 模型与运行时

### 6.1 选型结论（2026-08 时点；调研依据见 `research/2026_papers_survey.md` 与对话期检索记录）

| 角色 | 首选 | 备选 | 关键理由 |
|---|---|---|---|
| 本地 Worker（默认） | **Qwen3.5-4B Q4_K_M**（权重约 2.5GB，262K 上下文） | Qwen3.5-2B（低配）/ Qwen3.5-9B（高配） | IFEval 89.8（结构化输出可靠性=协议生命线）；官方端侧定位；GGUF 生态现成 |
| Architect | deepseek-chat（API） | 任意 OpenAI 兼容 | 便宜、支持 json_object、有上下文缓存计费优惠 |

已知注意项：Qwen3.5 小模型**加 few-shot 示例反而掉分**（社区实测 0.8B 零样本 67% → 单示例 33%），所有 prompt 写清晰零样本指令，禁止堆示例。

### 6.2 llama-server 启动模板（三档硬件）

```
# gpu12（≥12GB 显存）
llama-server -m models/qwen3.5-4b-q4_k_m.gguf --port 8901 -ngl 99 -c 32768 -fa -ctk q8_0 -ctv q8_0 --cache-reuse 256
# gpu8（≈8GB 显存）：-ngl 14 -c 16384
# cpu（无独显，≥16GB 内存）：-ngl 0 -c 8192（提示用户速度受限）
```

原则：`-c` 按需设定（不要拉满 262K，KV 预留会吃光内存）；KV 量化验证任务不用 q4（精度影响裁判）；`--cache-reuse` 配合"brief 恒定在前"的文档结构提高前缀命中率。

### 6.3 Architect API 约定

- 统一走 OpenAI 兼容 `/chat/completions`；`response_format: {"type": "json_object"}`，prompt 内嵌 schema 的紧凑描述。
- 每次调用记录 usage 到 `meta.budget` 与 Stats；触达 `api_token_cap` 前预留 500 token 余量，不足则直接熔断。
- DeepSeek 上下文缓存：brief 稳定前缀设计可命中 cache（价格更低），E1 实验单独统计 `prompt_cache_hit_tokens`。

### 6.4 模型/运行时下载（scripts/setup_runtime.py）

- GGUF：优先 `https://hf-mirror.com/...`（可用 env `HF_MIRROR` 覆盖），HTTP Range 断点续传，校验文件大小（±1MB）。
- llama-server：GitHub releases 拉 Windows Vulkan 版 zip（免 CUDA 工具链，N/A 卡通用）；解压 `llama-server.exe` 到 `bin/`；网络失败时打印手动下载指引后优雅退出。
- 完成后打印三档硬件检测结果与所选档位。

---

## 7. 任务分解（供 Agent 按序执行）

> 依赖链：T1 → T2 → (T3, T4) → T5 → T6 → (T7, T8, T9) → T10 → (T11, T12) → T13 → T14
> 每个任务一个 commit（`feat(v2): Tn 描述`），交付必须含测试。完成即在《任务拆解与执行计划.md》追加登记。

### 阶段 A：真实链路

- **T1 环境与基线确认**（0.5 天）
  确认 126 测试全绿；手动起一次 llama-server 跑通一次补全；DeepSeek API 冒烟（无 key 则记录跳过）。
  验收：README 追加"开发环境备忘"；发现的环境问题记录到本文件 11 节。
- **T2 运维层：hw_profile + llama_server 进程管理**（3 天）
  实现 5.1 两个模块；三档模板；健康检查/退避重启/优雅停止（Windows 进程语义注意）。
  验收：单测（MockTransport + 假二进制脚本）覆盖启停/崩溃重启/健康检查；真机手动验证三档参数生成正确。
- **T3 ArchitectClient**（2 天）
  brief/decide/final_review 三方法；JSON 约束输出＋失败重试一次＋降级；token 计量。
  验收：MockTransport 单测（正常/坏 JSON/超时/熔断四路径）；无 key 时构造报错信息明确。
- **T4 Workspace**（2 天）
  schema、校验、锚点寻址、双渲染函数（断言 token 预算）、rollup、持久化。
  验收：schema 单测（合法/非法样例 ≥10 组）；render_for_architect 输出对 3 组构造数据 ≤1200 token。

### 阶段 B：协作协议

- **T5 WorkerLoop + 工具循环 + 接地验证**（6 天）
  受限工具循环（D12：五工具、目录作用域、每 step ≤20 次调用、run 强制超时）→验证（D4 分层：run 工具跑测试 / facts 对照 / 结构检查）→自修≤2→issue。QA 快路径不启用工具（纯生成）。
  验收：单测覆盖"一次通过/自修成功/写 issue"三路径；工具循环单测（越界路径拒绝、超限熔断、超时回收）；端到端 demo：一个函数需求从 brief 到工作目录内产出可跑通的模块＋测试；facts 对照复用 knowledge YAML 现有数据出 3 个真实用例。
- **T6 CollaborativePipeline 编排**（3 天）
  快路径、循环状态机（4.3）、双护栏熔断、Architect 兜底代做、终审、TraceStore 对接。
  验收：端到端集成测试（全程 Mock：假 llama-server = httpx MockTransport + 假 Architect 同理）跑通"一次通过""带 issue 修复""熔断兜底"三个剧本。
- **T7 网关扩展**（1.5 天）：5.3 全部端点；`/chat` 切 v2，`/chat/legacy` 保留。
  验收：TestClient 测试新旧端点；legacy 测试全部原样通过。
- **T8 人工检验队列**（2 天）：ReviewQueue + 端点；抽样与 force_tags 规则。
  验收：单测入队/出队/修正回写；端到端测试中 safety tag 的请求必入队。
- **T9 token 计量与账单**（1 天）：每请求 API token 记账；/metrics 扩展。
  验收：E2E 测试断言 budget 回写正确；熔断在 cap=极小值的构造用例下触发。

### 阶段 C：整合

- **T10 rollup + prefix cache 调优**（2 天）：验证文档结构对 --cache-reuse 命中的影响；调 render 预算。
  验收：同一 10 步会话，第二轮起 prefill 时间显著下降（记录数字到实验目录）。
- **T11 打包分发**（3 天）：setup_runtime.py + 一键启动（`scripts/serve.py` 扩展为自动拉起 llama-server）+ 首启引导。
  验收：**干净 Windows 环境 20 分钟内从 clone 到对话成功**（写入验收清单）；无 API key 可走纯本地降级模式。

### 阶段 D：实验与论文

- **T12 实验脚本与数据集**（2 天）：`scripts/bench_tokens.py` + `eval/` 数据集（第 9 节）。
- **T13 跑数与报告**（4 天）：E1–E5 输出到 `research/v2_experiments/`（md + csv）。
- **T14 文档收口**（1 天）：README v2 改写（架构图、快速开始、指标表）。

---

## 8. 工程规约（Agent 必读）

1. **环境事实**：Windows 11 + Git Bash；venv 位于 `.venv`（Python 3.14）；测试命令
   `.venv/Scripts/python.exe -m pytest tests -q`（2026-08-30 基线：126 passed）。
2. **依赖纪律**：`router_system/` 新模块零第三方依赖（标准库 only）；`runtime/` 与网关可用
   httpx/fastapi/pydantic/uvicorn；确需新增依赖（如 psutil）→ 加到 requirements.txt 并在 PR 描述说明理由。
3. **测试封闭性**（D11）：一切 LLM 交互用 `httpx.MockTransport` 注入；沙箱执行用临时目录＋超时。
4. **Windows 兼容**：路径一律 `pathlib`；所有 CLI 出口 `sys.stdout.reconfigure(encoding="utf-8")`
   （先例见 `scripts/eval.py` 头部）；子进程用 `CREATE_NEW_PROCESS_GROUP`，终止用 terminate→kill 兜底。
5. **代码风格**：中文 docstring；`build_xxx(cfg)` 工厂函数；与现有文件排版一致；注释只写代码无法自明的约束。
6. **金额敏感**：任何 Architect 调用必须计量并受 `api_token_cap` 约束；禁止无熔断的重试循环。
7. **禁止事项**：不改 llama.cpp 源码；不在主链路重新引入领域分类；Architect 输入包含工件全文；跳过 schema 校验；为演示造假数据。
8. **文档同步**：每完成一个 T，在《任务拆解与执行计划.md》追加一行状态；架构级偏离（如有）必须先更新本文件再动代码。

---

## 9. 实验与评测设计（论文数据来源）

统一输出目录：`research/v2_experiments/`（每个实验一份 md 报告 + csv 原始数据）。

### E1 token 经济学（主实验）
- 50 任务（代码 20 / 数学 10 / 通用 20），四臂：
  A1 全量上下文（每轮把完整历史发 Architect）｜A2 交流文本协议｜A3 A2+rollup｜A4 A3+prefix cache。
- 指标：Architect input/output tokens、`prompt_cache_hit_tokens`、估算成本、回合数、最终质量分。
- 预期结论：A4 vs A1 的 Architect token 下降 ≥80%。

### E2 端到端质量（三臂）
- 100 任务：快路径 only / 完整协作管线 / 纯 Architect（大模型直答）。
- 判分：`machine_checkable` 项用断言；其余用 LLM rubric 评分＋10% 人工抽检。
- 数据集建议：HumanEval+ 子集、GSM8K 子集、C-Eval 子集、自建法律/医疗 QA 各 30 条（facts 库内可核对）。

### E3 协作健康度
- 升级率、回合数分布、issue 率、自修成功率、熔断次数（直接汇总 E1/E2 运行数据）。

### E4 KV 量化内存-精度曲线
- fp16 / q8_0 / q4_0 × 上下文 4K/16K/32K：进程内存（psutil RSS＋nvidia-smi 显存）× Worker 验证准确率（固定 50 题）。

### E5 验证器 P/R
- 对 100 个产物注入 50 处模板化缺陷，测接地验证的拦截率/误杀率；对照组=纯小模型自由判断（预期显著更差，支撑 D4）。

---

## 10. 里程碑排期（12 周）

| 周 | 阶段 | 内容 | 硬验收 |
|---|---|---|---|
| 1 | A | T1 + T2 开工 | 真实 llama-server 冒烟 |
| 2 | A | T2 完成 + T3 | 运维层单测全绿 |
| 3–4 | B | T4 + T5 | Workspace/Worker 单测全绿 |
| 5 | B | T6 | Mock 端到端三剧本通过 |
| 6 | B/C | T7 + T8 + T9 | 新旧端点共存，测试全绿 |
| 7 | C | T10 + T11 开工 | prefix cache 收益数据 |
| 8 | C | T11 完成 | 干净环境 20 分钟跑通 |
| 9–10 | D | T12 + T13 | E1 主实验出数 |
| 11–12 | D | T13 收尾 + T14 + 论文 | 实验报告 + README v2 |

---

## 11. 风险清单

| 风险 | 缓解 |
|---|---|
| 小模型长上下文"中间迷失" | 协议本身即补偿（重要前置＋总量受控）；render_for_worker ≤8K 硬约束 |
| llama.cpp 长上下文 prefill 慢（CPU 尤甚） | `--cache-reuse`＋brief 恒定前缀；`-c` 按需不拉满 |
| 协作死循环/踢皮球 | rounds_cap＋api_token_cap 硬熔断（D6），熔断即兜底代做 |
| 硬件多样性无法穷举测试 | 三档保守模板＋手动覆盖；超出范围提示"已按保守档运行" |
| 国内模型下载失败 | hf-mirror 镜像＋断点续传＋手动下载指引 |
| 用户无 API key | 本地降级模式：快路径＋本地兜底＋明确降级提示（v1 NoneFallback 思路） |
| 打包吃掉全部时间（时间黑洞） | 只承诺"干净 Windows 20 分钟跑通"；签名/自动更新/多平台一律不做 |
| schema 漂移导致协议断裂 | 所有写入过校验（4.6）；校验器有独立单测 |

---

## 12. 术语对照

| 术语 | 含义 |
|---|---|
| 交流文本 / Workspace | 两模型间的结构化 JSON 共享工作区（本协议核心） |
| brief | Architect 开局写入的任务分析（目标/约束/验收/计划） |
| issue / decision | Worker 上报的验证问题 / Architect 的裁决回复 |
| 锚点（anchor） | `a://文件#L行区间`，指向工件片段的引用（替代全文复制） |
| rollup | 已完成步骤压缩为 archive 摘要行的机制 |
| 快路径 | 小模型直答＋自验证通过即返回，不经 Architect |
| 熔断 | rounds_cap / api_token_cap 触顶后强制退出循环 |