端云协同编程智能体系统（v2）

论文题目：《基于端云协同的编程智能体系统设计与实现》（Design and Implementation of a Programming Agent System Based on Device-Cloud Collaboration）

大模型（API，Architect）做任务分析/决策/终审 ＋ 本地小模型（llama.cpp，Worker）做实现/自验证， 两者通过**「交流文本」**（一份 schema 约束的结构化 JSON 共享工作区）交接，互不共享内部状态， 另有人工检验队列作为第三协作者。目标是：在端到端质量不降的前提下，把大模型 API token 消耗相对 「全量上下文」方案下降 ≥80%（北极星指标）。

v1 的 L0 专家系统内核保留为 legacy 路由（POST /chat/legacy）与离线降级模式，不删除；126 项 v1 测试保持全绿。

---

✨ 当前能力（2026-08-30 已落地）

• ✅ 交流文本协议（router_system/workspace.py）：schema 校验、锚点寻址（a://file#L12-18）、rollup 压缩、双渲染函数（Architect ≤1200 token / Worker ≤8K token）、状态机、前缀稳定性（T10）
• ✅ ArchitectClient（architect.py）：DeepSeek JSON 约束输出，失败回喂重写一次，token 计量，预算熔断
• ✅ WorkerLoop + 接地验证（worker.py / verifier.py）：实现→自验证（代码沙箱 > facts 对照 > 结构检查）→自修≤2→issue
• ✅ CollaborativePipeline 编排（pipeline.py）：快路径 → brief → 协作循环 → 终审 → 交付，双护栏熔断
• ✅ 运维层（runtime/）：三档硬件检测（gpu12/gpu8/cpu）+ llama-server 进程管理（启停/健康/重启）
• ✅ 网关 v2（gateway/api.py）：/chat（v2）、/chat/legacy（v1）、/runs/{id}/workspace、/runs/{id}/artifacts/{name}、/review/queue、POST /review/{id}、/metrics（含 v2 统计）
• ✅ 人工检验队列（review.py）：sqlite 队列、抽样 + safety 强制入队、verdict/correction 回写
• ✅ 打包分发（scripts/setup_runtime.py）：llama-server + GGUF 下载（断点续传/大小校验）
• ✅ E1 token 经济学实验（scripts/bench_tokens.py → research/v2_experiments/）
• ✅ Web 界面（gateway/static/index.html，FastAPI 托管，无构建）：对话 / 协作过程（交流文本可视化）/ 人工检验 / 指标 四视图
• ✅ 测试：229 项全绿（含 v1 legacy 126 项 + v2 新模块）

---

🏗️ 架构

用户 query
   │
   ▼
[快路径] Worker 直答 + 自验证通过？──是──▶ 直接返回（省 API 钱）
   │ 否
   ▼
[Architect·API·一次] brief（goal/constraints/acceptance/plan/tags）写入 交流文本
   │
   ▼
┌─────────── 协作循环（护栏：rounds_cap / api_token_cap 熔断）───────────┐
│  [Worker·本地] 读 brief+当前步 → 实现 → 接地验证 → 通过→progress；失败自修≤2→issue  │
│  [Architect·API·按需] 读 issues → decide → 修订 plan / 兜底代做                    │
└──────────────────────────────────────────────────────────────────────┘
   │ 全步 done
   ▼
[Architect·API·一次] final_review → done / 打回
   ▼
交付 + 入人工检验队列（抽样 / safety 强制）

核心经济学：贵的一方（API）少读少写（每次输入 ≤1200 token 压缩摘要），便宜的一方（本地）多读多干。

---

🚀 快速开始

# 1. 虚拟环境 + 依赖
C:\Python314\python.exe -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

# 2. 跑测试（v1 legacy 126 + v2 新模块 = 228）
.venv\Scripts\python.exe -m pytest tests -q

# 3. （可选）准备本地运行时：下载 llama-server 二进制 + GGUF 模型
.venv\Scripts\python.exe scripts/setup_runtime.py

# 4. 启动网关（v2 /chat 默认走 mock worker，无需 API key/模型即可演示）
.venv\Scripts\python.exe scripts/serve.py --port 8000
#   浏览器打开 http://127.0.0.1:8000/ 使用 Web 界面（对话 / 协作过程 / 人工检验 / 指标）

#   ⚠️ 安全默认值（T30）：网关默认只绑定 127.0.0.1 且只信任本机 Host
#   （网关能读写工作区文件/执行命令，不宜默认暴露局域网）。
#   如需局域网访问：--host 0.0.0.0 并设置环境变量 GATEWAY_TRUSTED_HOSTS
#   放行对应主机名（"*" = 放行全部，仅限可信网络）。

# 5. 调用
curl http://127.0.0.1:8000/health
curl -X POST http://127.0.0.1:8000/chat -H "Content-Type: application/json" -d '{"query":"用 Python 写一个快速排序"}'
curl -X POST http://127.0.0.1:8000/chat/legacy -H "Content-Type: application/json" -d '{"query":"基金定投的收益率怎么计算"}'
curl http://127.0.0.1:8000/metrics

# 6. E1 token 经济学实验（本地确定性测量）
.venv\Scripts\python.exe scripts/bench_tokens.py

无 API key / 无本地模型时，/chat 走快路径（mock Worker）或本地降级，不崩溃。

---

⚙️ 配置（config/config.yaml v2 段）

段	关键项	说明
runtime	binary / model / port / hw_profile / tiers	llama-server 二进制、GGUF、三档硬件模板
architect	model / base_url / api_key_env	大模型（默认 DeepSeek），DEEPSEEK_API_KEY
worker	backend(mock	llama_server) / max_fix_attempts
pipeline	fast_path / rounds_cap / api_token_cap / breach_policy	快路径、双护栏熔断、兜底策略
review	queue_db / sample_rate / force_tags	人工检验抽样

---

📂 目录结构（v2 新增）

├── router_system/
│   ├── workspace.py      ★ 交流文本协议（核心）
│   ├── architect.py        大模型客户端（brief/decide/final_review）
│   ├── worker.py           小模型实现/自验证循环
│   ├── verifier.py         接地验证（代码沙箱/facts/结构）
│   ├── pipeline.py         协作管线编排
│   ├── review.py           人工检验队列
│   └── v2stats.py          token 计量与聚合
├── runtime/                运维层（hw_profile / llama_server 进程管理）
├── gateway/api.py          v2 + v1 legacy 端点
├── scripts/
│   ├── setup_runtime.py    下载运行时/模型
│   └── bench_tokens.py     E1 实验
├── eval/v2_sample.json     实验数据集
└── research/v2_experiments/  E1 结果与实验规划

---

📊 指标（v2）

指标	值	说明
测试	228 passed	v1 legacy 126 + v2 新模块
E1 token 下降（A2 交流文本 vs A1 全量）	~61%（本地确定性测量）	真实缓存计费下目标 ≥80%（--live 待确认）
稳定前缀可命中	~99% 的 A2 输入	配合 --cache-reuse 进一步降成本
快路径 / 熔断 / 回合	/metrics v2 统计	V2Stats 实时聚合

---

🔜 下一步

1. --live 接入真实链路：安装 runtime（setup_runtime.py）+ 设置 DEEPSEEK_API_KEY，跑 E1 主实验确认 ≥80% 北极星（scripts/bench_tokens.py --live）。
2. E2–E5 跑数：端到端质量 / 协作健康度 / KV 量化曲线 / 验证器 P/R（见 research/v2_experiments/README.md）。
3. 用 RouterArena 协议化评测 v2 端到端质量。
4. 写 v2 论文（research/paper/）。

📌 环境备忘（T1）

• Windows 11 + Git Bash；venv 在 .venv（Python 3.14）。
• 测试命令：.venv/Scripts/python.exe -m pytest tests -q。
• bin/、models/、data/、runs/ 已 gitignore（运行时产物不入库）。