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 依据）：

{
  "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
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 路由）

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 触顶后强制退出循环