tzt
ce3ba44de3
- 路径参数 ID 白名单（runs/agent/sessions），杀灭 Windows 反斜杠穿越（..%5C 直读 .env） - artifacts 端点关押 + pipeline 工件名消毒（模型输出名剥路径成分） - /llama/download dest 关押 models/ 内 + URL 协议白名单（先于 HF 别名转换） - GET /config architect.api_key 打码（api_key_set + 前 6 位），PUT 空串=保留 - TrustedHostMiddleware 信任围栏（GATEWAY_TRUSTED_HOSTS 可覆盖）+ __main__ 默认 127.0.0.1 - review 抽样改 CSPRNG - 新增 tests/test_security_hardening.py（13 项，全部离线）
148 lines
7.5 KiB
Markdown
148 lines
7.5 KiB
Markdown
# 端云协同 LLM 协作系统（v2）
|
||
|
||
大模型（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 压缩摘要），便宜的一方（本地）多读多干。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
```powershell
|
||
# 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（运行时产物不入库）。
|