tzt/projectAIpopular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7d11ae26449eb71dead57ec9fdc0b2ef13cb421a
projectAIpopular/实现方案_v4_模型池与工具智能体.md
T
tzt 7d11ae2644 feat(v3): T27 会话式智能体（多轮上下文/停止/对话式 UI，对齐 dsh 范式） 
- ToolLoop 增 history 参数（既往轮次折叠为对话上下文，近 6 轮）
- 会话制：AgentSession/SessionStore 持久化 agent_runs/sessions/{sid}.json，
  /agent/sessions CRUD + /agent 带 session_id（继承会话工作区与执行者配置，busy 并发控制）
- POST /agent/{id}/cancel：取消运行中任务
- AgentView 重构为对话式：会话列表 + 居中消息流（用户蓝气泡/助手白卡）+ 底部 composer
  （工作区/执行者/命令 chips，Enter 发送，运行中红色停止钮），工具过程折叠收纳
- 工具步数统计统一至事件写入层并透出 status.tool_calls
- fix(tests): 会话存储测试隔离，防测试数据泄漏进真实 sessions 目录
- 测试 +4，全量 281 passed
2026-09-01 22:30:26 +08:00

9.1 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 / edit_file / search_files / run_command， 路径关押在根目录内）与 ToolLoop（通用工具循环，轮数 + token 双护栏，逐事件回调）； gateway/agent.py 提供 OpenAI 兼容工具调用客户端与运行服务 （事件落盘 agent_runs/{id}/events.jsonl），/agent 端点 + SSE 实时推送。
  • 可选择工作目录（参考 deepseek-harness 的"打开文件夹"体验）：智能体可作用于 用户从磁盘上选择的任意项目目录（/agent/fs 目录浏览 + /agent/workspaces 最近列表）， 运行记录所用目录；run_command 默认关闭（allow_shell 开关），开启后在工作区内执行命令 （超时熔断 + 输出截断 + Windows CREATE_NO_WINDOW）。
  • 工程约束不变：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，必须仍位于工作区根内 （防 ../ 与绝对路径逃逸）；读取/写入/编辑均有长度与唯一性约束 （edit_file 的 old_string 必须唯一命中，歧义即拒绝）；search_files 跳过依赖/构建目录与 二进制大文件。工作区根本身可由用户选择（"打开文件夹"），关押相对所选根生效。
  • D5 智能体双护栏 + shell 默认关：轮数上限（agent.max_rounds，默认 8）+ token 熔断（agent.token_cap，默认 20000）；run_command 受 allow_shell 开关（默认关）， 开启后有 shell_timeout_s 超时与输出截断；触顶强制总结，不再给工具。
  • 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?, workspace?}，workspace 为所选工作目录
GET /agent/{id}/status /events /stream(SSE) 状态（含所用工作目录）/ 全量事件 / 实时流
GET /agent/workspace?path=&root=、GET /agent/file?path=&root= 工作区浏览/读取（root 指定所选目录）
GET /agent/fs?path= 目录选择器：浏览本地目录（只列子目录，空 path 列盘符）
GET /agent/workspaces、POST /agent/workspaces 当前+最近工作区 / 打开（可 create 新建）并设为当前

/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 测试 + 浏览器实测 ✅
T22 工具扩展（harness 风格）：edit_file 唯一替换 / search_files 跨文件搜索 / run_command（opt-in） ✅
T23 工作区选择：/agent/fs 目录浏览 + 最近工作区 + /agent 带 workspace + 状态记录目录 ✅
T24 前端：工作区选择栏（目录浏览器模态/最近/shell 开关）+ edit diff 卡 + 命令卡 ✅
T25 集成验证：选定真实目录跑"读→精确编辑→运行验证"全链路 + 274 测试全绿 ✅

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 调整）。

7. 增补：两级智能体（D7，T26）

  • 决策 D7（价位协作延伸到智能体形态）：POST /agent 支持 executor_pool_id—— 规划者（大模型：agent 角色或经典 Architect 设置）负责拆解指令与审查裁决； 执行者（本地小模型：llama_server/openai 池条目）负责工具轮；中间状态写 agent_runs/{id}/handoff.json（智能体版"交流文本"：instructions/acceptance/exchanges）。
  • 协议：规划者两阶段 JSON（plan: instructions+acceptance；review: verdict done|redo + reply_to_executor + final_answer），解析失败回喂重试一次再降级（对齐仓库 JSON 纪律）； redo 时裁决意见作为执行者下一轮指令，交接上限 agent.max_handoffs（默认 2）。
  • 护栏：规划者与执行者不得为同一池条目；执行轮 token 与整体 token_cap 共享预算； ToolLoop 内层循环 emit_final=False，终态事件由外层编排统一发出（防前端 SSE 提前收口）。
  • 事件：新增 phase（plan/execute/review，带模型名）与 message（planner/executor 正文） 两类事件，前端以阶段徽标 + 双色消息卡渲染。

8. 增补：会话式智能体（D8，T27）

  • 决策 D8（对齐 dsh 的会话范式）：智能体从"一次性任务"升级为多轮会话—— POST /agent/sessions 建会话（绑定工作区/执行者配置），后续任务带 session_id 递交，既往轮次折叠为对话历史注入模型（近 6 轮，每条截断 1500 字）； 轮次（任务/答复/工具步数/token）持久化到 agent_runs/sessions/{sid}.json。
  • 停止：POST /agent/{id}/cancel 取消运行中任务（asyncio cancel + 状态标记 cancelled_by_user）。
  • 前端：AgentView 重构为 dsh 式对话界面——左侧会话列表、居中消息流 （用户蓝气泡 / 助手白卡）、底部 composer（工作区/执行者/命令开关收为 chips， Enter 发送，运行中变红色停止钮）；工具过程折叠收纳，历史轮次仅显示步数摘要。
  • 工程：ToolLoop 增 history 参数；工具步数统一在事件写入层统计； 会话存储测试隔离（防泄漏进真实 agent_runs/sessions/）。
Reference in New Issue View Git Blame Copy Permalink