Files

T

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

2026-09-01 08:52:07 +08:00

5.4 KiB

Raw Blame History

实现方案 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 调整）。

5.4 KiB Raw Blame History Unescape Escape