chore: T-P-1 工作区收敛——并行会话成果与历史未入库文件整理入库

- 入库历史遗漏源码/测试：router_system 9 模块（agent/executors/inference/knowledge/
  memory/planner/skills/trace）、tests 11 个测试文件、config/knowledge 领域知识
- 入库根目录方案文档（v2/v3/可行性×2）、references 文献（arxiv 14-18/cnki_open/
  参考文献清单）、research 论文素材（routerarena/paper/中文文献 PDF）
- 前端构建产物刷新（新 hash）；webapp 误写文档删除
- gitignore 增补：deepseek-harness、research/_refs、.mimosa/.zcode、网关日志/pid、
  临时调试脚本、tests/e2e/node_modules、AI代理功能开发/prefix
- 基线确认：318 passed

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

@@ -0,0 +1,444 @@
+# 实现方案 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 触顶后强制退出循环 |