docs(v3): T21 集成验证与文档收口

- 新增《实现方案_v4_模型池与工具智能体.md》（D1-D6 决策、接口清单、T16-T21、实验设计）
- 任务登记：v3 Web 应用化 T1-T6 + 模型池/智能体 T16-T21
- 进度记录：叙事泛化决策（价位轴收编端云轴）、端到端实测、论文下一步

任务拆解与执行计划.md

@@ -82,3 +82,34 @@ P0 完成后的能力：干净的后端抽象 + 可量化的评测 + 可追溯
 | T13 | E1 本地跑数完成（E2–E5 待 live 接入） | ✅ 完成 | T13 |
 | T14 | 文档收口（README v2 改写） | ✅ 完成 | T14 |
 | T15 | Pipeline 死锁修复（_deps_done 依赖过滤 + pending-empty break）+ /metrics SPA 路由冲突修复 | ✅ 完成 | T15 |
+
+---
+
+## 六、v3 任务登记（Web 应用化，见《实现方案_v3_Web应用化.md》）
+
+> 每任务一个 commit（`feat(v3): Tn 描述`）；`router_system` 核心不动（D3），229 项基线测试保持全绿。
+
+| T | 内容 | 状态 | commit |
+|---|------|------|--------|
+| T1 | 后端异步化（jobs.py + /chat 后台任务 + /runs/{id}/status） | ✅ 完成 | v3 基线 |
+| T2 | 后端 SSE（/runs/{id}/stream 监视 workspace.json） | ✅ 完成 | v3 基线 |
+| T3 | 前端脚手架（Vue3+Vite+TS，outDir=gateway/static） | ✅ 完成 | v3 基线 |
+| T4 | 对话页 + SSE 实时可视化 | ✅ 完成 | v3 基线 |
+| T5 | 协作过程页 + 检验队列页 + 指标页 | ✅ 完成 | v3 基线 |
+| T6 | llama-server 内置管理（/llama/* + 下载 SSE）+ 设置页整页滚动修复 | ✅ 完成 | v3 基线 |
+
+---
+
+## 七、模型池与工具智能体任务登记（T16–T21，见《实现方案_v4_模型池与工具智能体.md》）
+
+> 「端云」叙事泛化为多价位模型池（local/budget/premium 三档 + 角色指派），新增 zcode 式工具智能体。
+> `router_system` 保持零第三方依赖；全量测试 262 项全绿（基线 229 + 新增 33）。
+
+| T | 内容 | 状态 | commit |
+|---|------|------|--------|
+| T16 | 工具内核：WorkspaceTools（路径关押）+ ToolLoop（轮数/token 双护栏） | ✅ 完成 | T16 |
+| T17 | 模型池：PoolStore + /pool 端点 + 管线池解析 + 按模型成本分账（by_model） | ✅ 完成 | T17-T18 |
+| T18 | 智能体：OpenAI 兼容工具调用客户端 + AgentService + /agent 端点（SSE） | ✅ 完成 | T17-T18 |
+| T19 | 前端：API 层 + 设置页模型池 UI（角色指派/条目 CRUD/连通测试） | ✅ 完成 | T19-T20 |
+| T20 | 前端：智能体页 AgentView + 指标页分账卡 + SSE 终态去重 | ✅ 完成 | T19-T20 |
+| T21 | 集成验证：真跑 3 轮工具任务（write/list/read）+ 浏览器实测 + 262 测试全绿 | ✅ 完成 | T21 |

实现方案_v4_模型池与工具智能体.md

@@ -0,0 +1,83 @@
+# 实现方案 v4：模型池与工具智能体
+
+> 编写日期：2026-09（git 记录）
+> 状态：**当前权威增补方案**。在 v2（端云协同协作）/ v3（Web 应用化）基础上两个升级：
+> ①「端云」叙事泛化为**多价位模型池**；② 新增 **zcode 式工具智能体**（模型操作工作区文件）。
+> 前置：v3 已落地（异步 /chat + SSE + Vue SPA，262 项测试全绿）。
+
+---
+
+## 0. 一页速览
+
+- **模型池**：`gateway/model_pool.py` 维护多价位异构模型条目（`local / budget / premium` 三档，
+  每条目 = 端点 + 凭据 + 模型名 + 单价 $/1M tokens），`roles` 把条目指派给
+  architect / worker / agent 三个角色；留空 = 沿用经典单模型设置（向后兼容）。
+  `build_v2_pipeline` 池指派优先；`V2Stats` 新增按模型 token/成本分账（`by_model`）。
+- **工具智能体**：`router_system/tools.py`（纯标准库）提供 WorkspaceTools
+  （list_dir / read_file / write_file，路径关押在根目录内）与 ToolLoop（通用工具循环，
+  轮数 + token 双护栏，逐事件回调）；`gateway/agent.py` 提供 OpenAI 兼容工具调用客户端与
+  运行服务（事件落盘 `agent_runs/{id}/events.jsonl`），`/agent` 端点 + SSE 实时推送。
+- **工程约束不变**：`router_system` 零第三方依赖；测试全部封闭（httpx 注入/假实现）；
+  不上分布式中间件；金额护栏沿用 api_token_cap 思想（agent 有独立 token_cap）。
+
+## 1. 设计决策（D1–D6，不得推翻）
+
+- **D1 价位为主轴，位置为属性**：系统按"模型成本档位"组织协作，不按"端/云"位置。
+  本地 llama.cpp 是 local（零边际成本）档；云端按单价分 budget / premium。
+  「端云协同」成为两档部署特例，命题叙事不改、系统叙事升级。
+- **D2 池条目存配置不存权重**：云端模型只存端点/凭据/单价元数据；本地模型经
+  llama_manager 管理 .gguf。api_key 服务端持久化、接口打码返回（`api_key_set` + 前 6 位）。
+- **D3 角色指派可热切换**：`PUT /pool/roles` 后 `rebuild_pipeline()` 立即生效；
+  测试注入 `worker_cfg_override` 优先级最高（保测试封闭）。
+- **D4 工具被关押在根目录**：所有路径 join 后 resolve，必须仍位于工作区根内
+  （防 `../` 与绝对路径逃逸）；读取/写入/列表均有长度上限。
+- **D5 智能体双护栏**：轮数上限（settings.agent.max_rounds，默认 8）+
+  token 熔断（settings.agent.token_cap，默认 20000）；触顶强制总结，不再给工具。
+- **D6 事件文件为单一事实源**：智能体过程逐条追加 events.jsonl，SSE 生成器轮询增量推送
+  （晚加入者从头回放）；前端收到 final 即关闭连接并忽略后续回放，防止重复渲染。
+
+## 2. 接口清单（新增）
+
+| 端点 | 说明 |
+|---|---|
+| `GET /pool` | 池全量（roles + entries，key 打码） |
+| `POST /pool` | 新增/更新条目（api_key 留空 = 保留原值） |
+| `DELETE /pool/{id}` | 删除条目（角色指派联动清空） |
+| `PUT /pool/roles` | 角色指派（architect/worker/agent → 条目 id 或空串） |
+| `POST /pool/{id}/test`、`GET /pool/{id}/models` | 条目连通测试 / 模型列表探测 |
+| `POST /agent` | 提交智能体任务 `{task, pool_id?}`，立即返回 request_id |
+| `GET /agent/{id}/status` `/events` `/stream`(SSE) | 状态 / 全量事件 / 实时流 |
+| `GET /agent/workspace?path=`、`GET /agent/file?path=` | 工作区浏览/读取（越界 400） |
+
+`/config/models`、`/config/ping` 抽出共用 `_list_backend_models` / `_probe_backend`。
+
+## 3. 前端（v3 四页基础上）
+
+- 设置页新增「🗄️ 模型池」区块：三角色指派下拉、条目表格（档位徽标/单价/启用/测试/编辑/删除）、
+  内联添加表单（模型列表探测 datalist）。
+- 新增「🤖 智能体」页（`/agent`）：任务输入 + 模型选择（池条目）、工具调用时间轴
+  （round / tool_call / tool_result / usage / final）、左侧工作区文件浏览与预览。
+- 指标页新增「按模型分账」卡片（by_model 表格）。
+
+## 4. 任务登记（T16–T21，衔接 v2 表 T15 之后）
+
+| T | 内容 | 状态 |
+|---|------|------|
+| T16 | 工具内核 `router_system/tools.py` + `tests/test_tools.py`（11 项） | ✅ |
+| T17 | 模型池 `gateway/model_pool.py` + `/pool` 端点 + 管线池解析 + by_model 分账 + 测试 | ✅ |
+| T18 | 智能体 `gateway/agent.py` + `/agent` 端点（SSE）+ 测试（含越界/校验/池指派） | ✅ |
+| T19 | 前端 API 层 + 设置页模型池 UI | ✅ |
+| T20 | 智能体页 AgentView + 指标页分账卡 + SSE 终态去重 | ✅ |
+| T21 | 集成验证：真跑 3 轮工具任务（写/列/读）+ 全量 262 测试 + 浏览器实测 | ✅ |
+
+## 5. 实验设计建议（论文用）
+
+- **位置无关性**：同一 Worker 角色分别绑 local（llama.cpp）与 budget（低价 API），
+  跑同一数据集对比 token/成本/质量——证明架构"价位驱动"而非"位置驱动"。
+- **价位帕累托曲线**：agent/worker 角色在 local→budget→premium 间切换，
+  画成本–质量帕累托图（metrics 的 by_model 直接供数）。
+
+## 6. 运行时目录（均 gitignore）
+
+`config/model_pool.json`（池持久化）、`agent_runs/{id}/`（events.jsonl + status.json）、
+`agent_workspace/`（智能体默认工作区，可在设置 agent.workspace_dir 调整）。

毕业设计_进度记录.md

@@ -0,0 +1,108 @@
+# 毕业设计 · 进度记录
+
+> 本文件记录"端云协同 LLM 协作系统"作为**毕业设计**推进过程中的关键决策、产出与待办。
+> 对应仓库文档：`实现方案_v2_端云协同LLM协作系统.md`（系统权威方案）、`实现方案_v3_Web应用化.md`（Web 应用化设计）、`references/毕业论文_参考文献清单.md`（参考文献）。
+
+---
+
+## 一、本次推进的议题（按时间顺序）
+
+1. **毕业设计命题**：为"端云协同 LLM 协作系统"拟定可行的毕业论文命题。
+2. **参考文献核实与下载**：确认命题能否找到对应中英文文献，并落地下载。
+3. **Web 应用化技术选型**：确定"把整体项目做成 Web 应用"的技术栈与架构，并定稿设计方案。
+
+---
+
+## 二、关键决策记录
+
+### 2.1 命题方向（已定）
+- 对象：本科 · 计算机科学与技术；侧重 **端云协同架构**。
+- **推荐命题**：《基于端云协同的 LLM 服务成本优化系统设计与实现》（副标题：——以异构大小模型非对称协作为核心）。
+- 核心卖点：① 非对称协作（贵的大模型少读少写 / 便宜的小模型多读多干）；②「交流文本」协议（原创交接层）；③ 可量化的北极星指标（token 下降目标 ≥80%，实测 ~61% 含缓存计费）。
+- 定位判断：这是**系统/工程类**毕设，非新算法类；命题应落在"面向成本约束的协作机制设计与实现"，避免宣称"提出了新模型/新方法"。
+- 提醒：北极星指标在论文中勿写死"80%"，表述为"缓存计费下下降约 61%，结合前缀缓存复用目标 ≥80%"。
+
+### 2.2 参考文献（已落地）
+- 确认命题**文献充足**：已有英文路由/级联文献极强，另有"端云协同/大小模型协作"方向专门综述。
+- **外文已下载 5 篇**（`references/arxiv_papers/`，已验证有效 PDF）：
+  - 14 FrugalGPT (2305.05176)
+  - 15 Small Models in the LLM Era Survey (2409.06857)
+  - 16 Dynamic Model Routing & Cascading Survey (2603.04445)
+  - 17 Edge SLMs + Cloud LLMs Collaboration Survey (2507.16731) ← 与命题几乎同名
+  - 18 Collaborating Small and Large LLMs Survey (2510.13890)
+- **中文文献**：由**使用者本人走校园网知网下载**到 `research/`（如《Token级多模型并联协作推理_王建辉》《大小模型端云协同进化技术进展_王永威》《大语言模型时代的人工智能_陈光》等）；另有开放获取的《大语言模型算法演进综述_中兴通讯技术》存于 `references/cnki_open/`。
+- **提醒**：所有中文文献定稿前必须在知网逐条核对页码/作者/年份；外文 14–18 可放心引用。
+
+### 2.3 Web 应用化技术选型（已定）
+- **后端**：保持 **Python + FastAPI + uvicorn，不重写**（`router_system` 为纯标准库，229 项测试全绿）。
+- **前端**：**Vue 3 + Vite + TypeScript** SPA，四页面（对话 / 协作过程 / 检验队列 / 指标），构建产物输出到 `gateway/static`，FastAPI 单端口托管。
+- **实时化**：`POST /chat` 改异步（立即返回 `request_id`）+ 后台 asyncio 任务 + **SSE**（`/runs/{id}/stream`）实时可视化「交流文本」协作过程。
+- **关键约束（D3）**：SSE 通过**监视 `runs/{id}/workspace.json`** 实现，**不修改 `router_system/pipeline.py`**，保住测试全绿。
+- **避坑**：不上 Celery/Redis/微服务；asyncio + sqlite + 文件系统足够。
+- 完整设计见 **`实现方案_v3_Web应用化.md`**（含 D1–D9、SSE 协议、目录结构、T1–T6、验收标准）。
+
+---
+
+## 三、本次产出文件
+
+| 文件 | 说明 |
+|---|---|
+| `实现方案_v3_Web应用化.md` | Web 应用化权威设计方案（技术栈/架构/接口/步骤/验收） |
+| `references/毕业论文_参考文献清单.md` | 参考文献初稿清单（已下载 / 需知网下载 / 提醒） |
+| `references/arxiv_papers/14–18_*.pdf` | 5 篇新增外文文献（有效 PDF） |
+| `references/cnki_open/中_大语言模型算法演进综述_中兴通讯技术.pdf` | 1 篇开放获取中文 PDF |
+| `research/` 下多篇中文 PDF | 使用者自行从知网下载的中文文献 |
+
+> 说明：`git status` 中 `router_system/`、`scripts/`、`tests/` 等处的改动为**本会话之前已存在的历史修改**，非本次 Web 应用化产出。
+
+---
+
+## 四、待办 / 下一步
+
+1. **实施 Web 应用化**（按 `实现方案_v3_Web应用化.md` T1→T6）：
+   - T1 后端异步化（`jobs.py` + `/chat` 改异步 + `/runs/{id}/status`）
+   - T2 后端 SSE（`/runs/{id}/stream`）
+   - T3 前端 Vue3+Vite 脚手架（outDir=gateway/static）
+   - T4 对话页 + 交流文本实时可视化
+   - T5 检验队列页 + 指标页（ECharts）
+   - T6 集成部署 + 测试
+2. **收尾答辩材料**：补齐中文文献题录（知网核对）、论文各章节、E1 `--live` 真实链路数据。
+3. 将 v3 方案登记进 `任务拆解与执行计划.md`，并把 AGENTS.md 的"当前权威规划"指针同步到 v3。
+
+---
+
+*记录人：DSH Agent（2026）。*
+
+---
+
+## 五、2026-09-01 推进：模型池 + 工具智能体（叙事升级落地）
+
+### 5.1 关键决策
+- **叙事泛化（命题不变）**：把「端云分工」泛化为**按价位分工**——代码里角色轴
+  （Architect 决策 / Worker 实现）与位置轴本来就正交（ArchitectClient 走 OpenAI 兼容协议、
+  Worker 已有 mock/llama_server/openai 三后端），故"端云协同"收编为"多价位模型池"的两档特例。
+  命题标题、开题材料、文献锚点全部不动，系统叙事升级（答辩加分项）。
+- **术语**：对外表述用「多价位模型协作 / 分级调度 / 异构模型池」，**避免"融合"**
+  （会被理解为模型级 ensemble）。FrugalGPT（文献 14）为新叙事主锚点。
+- **新增智能体能力**：zcode 式工具调用——模型可 list_dir / read_file / write_file
+  操作**被关押在工作区内**的文件，过程 SSE 实时可视化。
+- 设计全文：`实现方案_v4_模型池与工具智能体.md`（D1–D6、接口清单、T16–T21、实验设计）。
+
+### 5.2 产出
+- 后端：`router_system/tools.py`（纯标准库工具内核）、`gateway/model_pool.py`（模型池）、
+  `gateway/agent.py`（智能体服务）、`/pool` + `/agent` 全套端点、V2Stats 按模型分账。
+- 前端：设置页「模型池」区块（角色指派/条目 CRUD/连通测试）、新「🤖 智能体」页
+  （工具时间轴 + 工作区文件浏览）、指标页「按模型分账」卡。
+- 顺手修复：SSE final 后重连回放导致的重复渲染；`/agent` 深链 SPA 路由。
+- **测试**：全量 262 passed（基线 229 + 新增 33：tools 11 / pool 10 / agent 6）。
+- **端到端实测**（DeepSeek 真跑 3 轮）：写 hello.py → 写 note.md+列目录 → 读 hello.py 审阅，
+  工具事件实时渲染、工作区真实落盘、路径越界被拒、token 计量正确。
+
+### 5.3 下一步
+1. 论文表述更新：系统架构图加入"模型池 + 价位轴"；补一节工具智能体与护栏设计。
+2. 实验 E-new（位置无关性）：同一 Worker 角色绑 local vs budget 跑同数据集，
+   证明"价位驱动而非位置驱动"——`bench_tokens.py` 改造可跑。
+3. Worker 步骤级工具化（可选增强）：协作管线内 Worker 也可用工具构建工件（opt-in 开关）。
+4. 中文文献知网核对仍待完成（定稿前必做）。
+
+*记录人：DSH Agent（2026）。*