Files
api-gateway b922b21b3f chore(cleanup): 清除 CNB 残留(远端 / 脚本 / 文档)
老板:「CNB 的都删了,代码,文档相关的都去掉」。

- scripts/push_cnb.sh 移除(归档 /root/.trash/2026-10-12-cnb-retire-cleanup/ + MANIFEST)
- scripts/push_gitea.sh 注释去掉 CNB 表述
- README 发布纪律段、docs/agents-dev-plan.md 的 CNB 表述改 Gitea
- 历史条目(CHANGELOG/MEMORY/日记)保留不改写;纯文档/配置清理,未升版本号
2026-10-12 14:35:10 +08:00

30 KiB
Raw Permalink Blame History

智能体(Agent)开发计划 · v1.6

路线 A:界面在网关,引擎是 QwenPaw 状态:计划中,未开工(等本计划确认) 版本:v1.6(2026-09-29)|上一版 v1.5


0. 已确认的决策(老板 2026-09-29 拍板)

# 决策 结论
① 引擎用哪个 profile 新建一个专用 profile ai-gateway(不复用 default,也不复用现有 3 个)
② 智能体的系统提示词归谁管 归 QwenPaw 管。网关不存提示词,配置页只读展示 + 说明去哪儿改
③ 会话存哪边 网关存(agent_sessions.json),QwenPaw 只用 session_id 续上下文
④ 建几个 profile 只建 ai-gateway 一个(不为每个智能体建 profile)
⑤ 智能体 ↔ profile 关系 一对多:多个智能体共用 ai-gateway 这一个 profile
⑥ 别名链自指校验 + 递归深度上限 加(无需再确认)
⑦ member 裁剪规则 按建议:member 只见 display_name/description/status(model 已于 ⑲ 移除)
⑧ /auth/me 上线顺序 按建议:后端先行,前端兼容 404
⑨ 智能体共用一套人格/记忆 接受("同一大脑、不同模型与参数",非不同角色)
⑩ ai-gateway 骨架是否继承私人内容 清掉,改写为干净的"网关智能体"版
⑪ 一期工具开关 全开(27 个,保证全能);页面加显眼提示
⑫ 智能体数量上限 软上限 5 个
⑬ 能力栏数据来源 不跨进程读 QwenPaw 配置;静态说明 + 跳转链接
⑭ 引擎调模型的 Key 与计量归属 新建专用 Key agent-engine;记引擎桶但打 source=qwenpaw + agent_slug + 用户账号
⑮ 引擎断线表现 红条 + 对话区禁用 + 保留已收内容;不自动续接(二期 reconnect)
⑯ agents.yaml 是否入版本库 入库(无秘密;但以后描述别写敏感内容)
⑰ 归档智能体的历史数据 保留;列表可筛「已归档」并支持恢复
⑱ 配置页「试跑」按钮 加(Step 3 +0.3h)
⑲ 模型归属(实测修正) 甲案:所有智能体共用同一个模型(因模型是 profile 级 + 共用一个 profile);配置页模型栏改只读 + 指路 QwenPaw
⑳ params 白名单 只 temperature + max_tokens → 已被 ㉗ 取代(扩为 4 键)
㉑ 会话列表实现 复用 history/{kind}(kind = agent_<slug>),不新开端点
㉒ features 与前端常量关系 features 是唯一权威;前端常量只作"后端无该字段时"的兜底(默认 false)
㉓ Step -1 技术验证 加(0.5h,动手前做)
㉔ §4 标题 改为「决策详情与取舍说明」
㉕ 接口字段表 补:列表项 / 详情项分别返回什么
㉖ 智能体个性方案 A + C:接受"智能体=参数+历史预设"(A);并用 system_suffix 补个性(C)
㉗ params 白名单 扩为 4 键:temperature / max_tokens / top_p / system_suffix

⑤ 带来的直接后果(老板已接受,见 §4 已定-A)

只建一个 profile + 决策 ②(提示词归 QwenPaw)⇒ 所有智能体共用同一份 SOUL.md / AGENTS.md ⇒ 智能体之间"人设"无法从提示词层区分,只能靠:模型 + 参数 + 各自独立的会话历史。

这不是缺陷,是"省资源"的代价。一期可以接受(你自己用,主要想试不同模型/参数/工作流); 若哪天需要"每个智能体真的是不同人设",就得回到"一智能体一 profile" —— 届时要重估内存。

⑲ 的展开:模型共用的实测依据(★ 方案级修正,2026-09-29 实测)

原设计错误:设计稿假设"每个智能体选自己的模型"。实测证明做不到:

实测 结果
打 /api/console/chat 传 model: "agnes-3.0-flash" ❌ 被忽略 —— SSE 末尾 turn_usage 明文回 provider_id=opencode, model_name=deepseek-v4.1-flash
源码 schemas.py:247 AgentRequest 只有 input / session_id / user_id / stream / metadata —— 没有 model 字段
模型怎么设? PUT /api/providers/active(body 含 scope:"agent" + agent_id)→ profile 级设置

推论:模型是 profile 级的,而所有智能体共用 ai-gateway 一个 profile(决策④⑤)⇒ 所有智能体必然用同一个模型。

甲案落地(老板已选):

项 做法
配置页「模型」栏 只读展示当前 ai-gateway 用的模型 + 「去 QwenPaw 修改」链接
数据源 GET /api/providers/active?scope=agent&agent_id=ai-gateway(读)
agents.yaml 的 model 字段 移除(不存在"每个智能体的模型"这回事)
智能体之间靠什么区分 名称 / 描述 / 参数(4 键,含 system_suffix 角色后缀) / 会话历史 / 访问范围

升级路径:哪天真要"不同智能体不同模型" → 给那个智能体单独建 profile(届时评估内存)。 明确不做:网关侧切 profile 模型(原方案乙)—— 有并发覆盖风险,一期不做。

㉖ 的展开:A + C —— 智能体靠什么有个性(2026-09-29 定)

甲案(⑲)把模型也统一了 ⇒ 智能体之间只剩"参数 + 会话历史"。为让"智能体"这个概念真正有用, 采用 A + C:

  • A(接受现状):智能体就是"同一套引擎 + 不同参数 + 各自独立的会话历史"的预设。
  • C(补个性):新增 params.system_suffix —— 网关在转发给引擎时,把它追加到会话的指令里。

system_suffix 怎么落地(关键设计)

因为 AgentRequest 没有 system 字段(只有 input/session_id/...),所以注入方式是:

方案 做法 评价
① 作为首条 user 消息前缀 把后缀拼进第一条消息文本 简单,但会污染对话记录、用户看得到
② 放进 metadata metadata: {system_suffix: "..."} 依赖引擎认不认,未知
③ 节点:AgentRequest 加 system 字段 给 QwenPaw 的 schema 加字段 改别人的代码,不推荐
④ ★ 网关侧每轮注入一条轻量指令 在 input 里插入一条极短的 system 角色消息 需实测 QwenPaw 是否接受 system 角色

→ Step -1 必须验证这一条(见下):QwenPaw 的 AgentRequest 接不接受 role: "system" 的消息。

  • 接受 → 用方案 ④(最干净)
  • 不接受 → 退到方案 ①(前缀拼进首条消息,UI 上明确标注"这是智能体的角色设定")

system_suffix 与决策②的关系(重要):

  • 决策② 说的是"智能体的主提示词归 QwenPaw 管"(SOUL.md 那种,一大段)
  • system_suffix 是一小条补充说明(如"回答只给结论,不要解释过程"),属于智能体级微调
  • 不冲突:主提示词在 QwenPaw,微调在网关。但 UI 要写清楚区别,避免两边打架。

一期不做(明确)

  • ❌ 完整的 per-agent system prompt(那就是建 profile 了)
  • ❌ 智能体级工具开关(profile 级)
  • ❌ 智能体级记忆

② 的展开:网关侧怎么表达"提示词在 QwenPaw"

  • agents.yaml 不存 system_prompt 字段(避免两套真相)。
  • 配置页「提示词」一栏改成只读展示 + 指引:
    • 显示 QwenPaw 侧该 profile 当前生效的提示词文件路径(SOUL.md / AGENTS.md)
    • 提供一个「打开 QwenPaw 设置」链接(http://127.0.0.1:8088)
    • 文案说明:要改提示词请去 QwenPaw,网关这边不接管
  • 多智能体共用一份提示词时,页面要显式提示这一点,别让用户以为改了 A 不影响 B。

③ 的展开:会话归属

  • 网关 data/agent_sessions.json 是唯一会话列表(列表 / 搜索 / 导出 / 重命名都在网关)。
  • 每次对话把网关的会话 id 映射成 QwenPaw 的 session_id 传过去,让它保持上下文。
  • 不在网关保存完整历史正文的副本(QwenPaw 侧自己也有);网关只存索引级信息(id / 标题 / 时间 / 轮次 / tokens / 归属账号 / engine session)→ 省空间、避免两份正文不一致。

1. 目标与范围

一句话:在网关加一个「智能体」菜单(仅管理员),能创建/管理若干智能体(共用 ai-gateway 这一个引擎 profile,也共用同一个模型),在页面里直接对话,工具执行过程可视化。

一期做什么(P0)

  • ✅ 新建 QwenPaw profile ai-gateway
  • ✅ data/agents.yaml:智能体定义(名称 / slug / 描述 / 参数 / 引擎 profile / 访问范围)
  • ✅ 后端 7 个端点(含新增 GET /auth/me 灰度通道)
  • ✅ 前端「智能体」页(列表 + 对话 + 配置 + 运行记录)
  • ✅ 工具执行轨迹可视化(设计稿的"执行了 3 步")
  • ✅ 计量:agent 维度 + source=qwenpaw 打标 + 引擎模型防自指(校验 ai-gateway 的 active_model 不指向 agent/*)
  • ✅ 灰度:features.agents 后端下发,一期只对 admin 开

一期不做(明确排除)

  • ❌ 图片/附件(Agent API 的图片支持要实测,二期)
  • ❌ 工具逐个勾选开关(一期继承 profile 的全局设置,页面只显示实际开关状态)
  • ❌ 给普通用户下发(结构预留,功能二期)
  • ❌ 断线自动重连(reconnect=true,二期)
  • ❌ 在网关里编辑提示词(决策 ② 已定:归 QwenPaw)
  • ❌ 多引擎(就是 QwenPaw 一套)

2. 开发步骤

Step -1 · 技术验证 ✅ 已完成(2026-09-29)

# 验证项 结论
1 请求级指定模型是否可行 ❌ 不可行 → 方案已按甲案修正(见 ⑲)
2 PUT/GET /api/providers/active 的 scope ✅ 支持 scope=agent + agent_id
3 SSE 事件谱 + 夹具 ✅ 已录制并落盘 → 见下
4 X-Agent-Id 选 profile ✅ 生效(实测带 X-Agent-Id: default 走 default 的会话/记忆)
4b input 接不接受 role:"system" ✅ 接受且真的生效 → system_suffix 用方案 ④(注入 system 消息)
5 ai-gateway 的 active_model 指向 ✅ 已确认为 wangjinding / wjd(引擎调用过网关,计量闭环成立)

产出物:

  • tests/fixtures/sse-tool-flow.sse —— 真实含工具调用的 SSE(14,900 字节 / 57 事件)
  • docs/qwenpaw-agent-api-sse.md —— 完整事件谱 + 适配器映射表(Step 2 实现依据)

事件谱要点(实测):text(36,正文增量,delta:true 累积 / delta:false 是快照要忽略) · plugin_call(工具调用,名在 content[0].data.name、参数是 JSON 字符串) · plugin_call_output(结果,在 data.output,用 call_id 配对) · data(分片,忽略) · response(终态,status: completed/failed/cancelled) · turn_usage(记 token/成本 的直接来源, 带 model_name 与缓存字段)。 顺序:文本 → 工具调用 → 工具结果 → 更多文本 → … → response → turn_usage(同一响应内穿插)。

另一条实测:GET /healthz 只回 {"status":"ok"} 不含版本 —— 验版本要读 GET / 的 version。

Step 0 · 建 QwenPaw profile ai-gateway ✅ 已完成(2026-09-29)

0. 备份:cp ~/.qwenpaw/config.json → config.json.bak-<日期>(记回滚方式)
1. 复制骨架:default 的 workspaces → workspaces/ai-gateway
2. 清私人内容:该 profile 的 SOUL.md / AGENTS.md 改写为"网关智能体"版本
   (不继承"小银"身份、老板的私人上下文、项目记忆)—— 见 §4 已定-B
3. config.json 的 agents.profiles 加一项:
     {id: "ai-gateway", workspace_dir: "/root/.qwenpaw/workspaces/ai-gateway", enabled: true}
4. 工具开关:一期全开(与 default 一致,保证"全能");二期下发前收窄
5. 权限:只监听 127.0.0.1(现状已是);确认 allow_no_auth_hosts 含 127.0.0.1/::1
6. 验证:curl 带 X-Agent-Id: ai-gateway 打 /api/console/chat 能收到流式
7. 回归:确认 default 与我当前会话**不受影响**(老板口径:新建不影响 default)
8. ★ 建引擎专用 API Key `agent-engine`(网页里建,供 ai-gateway profile 调模型用)
   · 写进 QwenPaw 的 provider 配置或环境;同时打 source=qwenpaw 计量标
   · Key 明文只落在需要它的地方(QwenPaw 侧 secret 目录 / 网关 data/.env),不入库

验收:X-Agent-Id: ai-gateway 跑通一轮对话;default 行为与之前一致。

实际完成情况(实测):

项 结果
备份 config.json.bak-20260929-agents
工作区 <工作区>/(全新空白,未复制 default 的任何私人文件)
提示词 新写 SOUL.md + AGENTS.md(网关智能体版);system_prompt_files: ["AGENTS.md","SOUL.md"](不含 PROFILE.md)
注册 config.json 的 agents.profiles + agent_order 均已加 ai-gateway
工具 ✅ 全开 27 个(决策⑪);approval_level: OFF
模型 active_model = {provider_id: "wangjinding", model: "wjd"}
引擎 Key 新建 agent-engine(label),明文暂存 /tmp/agent_engine_key(600),待写入 QwenPaw 配置
profile 可用性 ✅ 实测 X-Agent-Id: ai-gateway 跑通,"网关就绪"正常返回
模型指向 ✅ turn_usage 明证 provider_id: wangjinding / model_name: wjd → 引擎过网关,计量闭环
隔离验证 ✅ 问"你是谁/认识老板吗",答"没有个人身份、没有个人记忆…没有任何关于「老板」的信息",并实际检查了工作区记忆文件
default 是否受影响 ✅ 无影响(新建 profile 不动已有 profile)
注意:改 config.json 会触发配置重载。实测口径是"新增 profile 不影响已有 profile",
但仍要先备份;若发现 default 会话中断,立即回滚。

新增一个语义确认点:ai-gateway 这个 profile 是网关的公共引擎(所有智能体共用), 不是"某一个智能体"。命名上要避免以后误以为它对应某个具体智能体。

Step 1 · 数据层(约 2h)

新增 app/agents.py
  ├─ AgentStore:data/agents.yaml 读写(600 / 原子写 / mtime 热载 ≤15s / 备份)
  ├─ 校验(抛 ConfigError,不静默):
  │    · slug:小写连字符、唯一、不撞模型 id、不撞别名、不撞 profile id
  │    · engine.type 必须是 qwenpaw;engine.agent_id 必须存在
  │    · params 键必须在白名单内(temperature / max_tokens / top_p / system_suffix)否则报错(㉗)
  │    · system_suffix 长度上限(如 2000 字符)—— 防止塞一整段提示词绕过决策②
  │    · access.roles ⊆ {admin, member}
  │    · ★ 数量上限:未归档的智能体 ≤ max_agents(默认 5)→ 超了抛 ConfigError
  └─ 默认值:access.roles=["admin"] / status="published"
新增 data/agents.yaml(初始 1 个示例)

agents.yaml 字段表:

字段 类型 一期可改 说明
slug str 新建时可填 URL/接口用;唯一
display_name str ✅ 页面显示名
description str ✅ 一句话说明
model — — 已移除(见 ⑲:模型共用一个,不在智能体上配)
engine.type str ❌ 固定 qwenpaw
engine.base_url str ❌ http://127.0.0.1:8088
engine.agent_id str ❌ QwenPaw profile id(如 ai-gateway)
access.roles list ❌(二期开) 一期固定 ["admin"]
access.users list ❌(二期开) 灰度点名,一期空
status enum ✅ draft / published / retired
params obj ✅ 白名单 4 键:temperature / max_tokens / top_p / system_suffix;其他键报 ConfigError(㉗)
created_at / updated_at str 自动 审计

顶层配置(不属于单个智能体):

键 默认 说明
max_agents 5 未归档智能体数量上限(已定-D)

Step 2 · 后端端点 + 引擎适配器(约 4h)

GET /agents 返回字段(㉕):

层级 字段
列表项 slug / display_name / description / status / engine_type / access_scope(admin / users)/ session_count / last_used_at
详情项 列表项全部 + params / engine(base_url / agent_id)/ access(roles / users)/ created_at / updated_at
引擎实况(详情额外) engine_model(读 GET /api/providers/active?scope=agent&agent_id=... 拿当前模型)+ engine_ready(探活结果)
member 裁剪 只有 slug / display_name / description / status(⑦;无 model —— 已 ⑲ 移除)
GET    /agents                   列表(admin 全量;member 只回分派的角色)+ 裁剪字段:
                                 member 只见 display_name/description/status;
                                 不见 engine.base_url、access.users、运行记录(⑦ 已定)
POST   /agents                   新建        (_require_admin;超 max_agents 返 400)
PUT    /agents/{slug}            改(名称/描述/模型/params/status 可改)
DELETE /agents/{slug}            归档 retired(不物理删)
POST   /agents/{slug}/chat       对话 → 转发 /api/console/chat(SSE)
POST   /agents/{slug}/stop       停止 → /api/console/chat/stop
GET    /agents/{slug}/runs       运行记录
★ 会话列表:**复用现有 `GET|POST|DELETE /history/{kind}`**(kind = `agent_<slug>`)
   不新开端点 —— 列表/新建/重命名/删除全用现成的那套(㉑)
GET    /auth/me                  ★ 回 features{agents:{enabled, canManage, visible}}

引擎适配器(app/agents.py 或 app/adapters/qwenpaw_engine.py)四件事:

# 事项 说明
1 请求形状 OpenAI messages → AgentRequest{input:[Message], session_id, stream};带 X-Agent-Id
2 SSE 事件映射 MESSAGE→文本增量 / PLUGIN_CALL+OUTPUT→轨迹步骤 / REASONING→思考 / PROGRESS→进度 / RESULT→结束 / RunStatus.failed→错误
3 session_id 映射 网关会话 ↔ QwenPaw session_id
4 错误兜底 引擎不可达 → 502 + 明确文案(不静默)
5 system_suffix 注入 按 Step -1 第 4b 项的结论,把智能体的角色后缀注入请求(㉖)

引擎断线表现(已定 ⑮):

场景 表现
引擎不可达(QwenPaw 没跑) 对话区禁用 + 顶部红条「引擎不可达(QwenPaw 未运行)」+ 重试按钮
流式中引擎中断 末尾追加「⚠ 引擎连接中断,本轮未完成」+ 保留已收到的内容
引擎重启后 用户重新发消息即可(不自动续接,二期做 reconnect=true)

⚠️ 实施顺序:先做只映射文本的最小闭环(跑通端到端),再加轨迹。SSE 事件是最不确定的部分,别一上来就啃它。

Step 3 · 前端(约 5h)

views/Agents.vue            列表 + 详情三 Tab(对话/配置/运行记录)
components/AgentTrace.vue   ★ 执行轨迹("执行了 3 步")
lib/agents.ts               接口封装 + SSE 解析
router.ts                   /agents  meta.admin
lib/nav.ts                  核心组第 5 位 + icon: bot
components/Icon.vue         加 bot 图标
locales/zh.ts + en.ts       agents.* 键,zh/en 对称

实现细节(沿用设计稿):

  • 模型栏(⑲ 甲案):只读展示 ai-gateway 当前模型 + 「去 QwenPaw 修改」链接; 不做模型下拉(原设计稿的下拉删掉)
  • 配置页:名称/描述/模型/params 可改;引擎/工具/访问范围只读并给原因;提示词只读 + 指路 QwenPaw(决策 ②)
  • 对话页:左会话列表 + 右消息区 + 底部输入(流式中"停止"替换"发送")
  • 手机端:列表全宽 + 滑入详情
  • 数量上限:达 5 个时「新建」禁用 + 提示(已定-D)
  • 共用说明:新建弹窗与配置页显式说明"提示词与记忆共用"(已定-A)
  • 参数表单(㉗):temperature / max_tokens / top_p 三个数值 + system_suffix 多行输入 (标注"这段是智能体的角色补充,与 QwenPaw 的主提示词叠加生效")
  • 风险提示:对话页顶部常驻"可在服务器上执行操作"(已定-C)
  • features 权威(㉒):features.agents 后端下发说了算;前端常量仅"后端没这字段"时兜底(默认 false)
  • 能力栏:不列 27 项明细,改静态说明 + 「去 QwenPaw 查看」链接(已定 ⑬)
  • 试跑按钮:配置页改完模型/params 后点一下,发 1-token 请求验证连通,就地显示结果(已定 ⑱)
  • 归档管理:列表可筛「显示已归档」,归档项可「恢复」(已定 ⑰)

Step 4 · 计量与审计(约 1.5h)

metrics.py       agent 维度(按智能体统计)
usage 打标        source=qwenpaw(区分"个人使用"与"网关 agent 使用")
                  引擎调模型统一用 `agent-engine` Key → 记引擎桶,
                  但每条带 agent_slug + 调用者账号(明细靠网关自身记录,不依赖引擎)
data/agent_runs.json   每轮一条:时间/账号/智能体/轮次/工具数/tokens/耗时/状态
防自指(⑲ 后风险已转移,见下方说明):
                 ★ 现在没有 per-agent model 了 → 真正的风险变成:
                   **`ai-gateway` profile 的 active_model 不能指向 `agent/*`**
                   (否则引擎调模型 → 打到智能体 → 又调引擎 → 死循环)
                 ★ 校验点:Step -1 第 5 项确认 active_model 指向正常模型(如 wjd)
                 ★ 递归深度上限:同一请求内引擎调用 ≤ 3 层(超限 400 并写明原因)
                 ★ 保留别名链解析:若 active_model 是别名,解析目标后校验不是 agent/*

Step 5 · 测试与上线(约 2.5h)

tests/test_gateway.py   +12~15 条
   · agents.yaml 解析与校验(含 slug 查重、params 白名单、数量上限、非法枚举)
   · 引擎模型防自指(active_model 指向 agent/* 时应被拦)
   · 权限矩阵(admin 全量 / member 只读分派 / 无凭证 401)
   · SSE 事件映射(用录制的真实事件做夹具)
   · features 下发(一期 member 不可见)
   · 归档后不出现在列表
scripts/ci_check.sh     跑绿
回归 209 → 约 222 条全过
★ 上线顺序(⑧ 已定):**后端先行** —— 先发后端(含 GET /auth/me 与 features 下发),
   再 build 前端。前端 store/session.ts 要兼容"后端没有 /auth/me"(404 → 按 enabled:false)
上线:restart → 真机验证 → commit → 推 Gitea(项目硬性规矩)
文档:README + CHANGELOG 各记一轮

3. 总量

项 估量
Step -1(技术验证) 0.5h(4 项已做 2 项)
Step 0(profile) 1h
Step 1(数据层) 2h
Step 2(端点+适配器) 4.3h(含 system_suffix 注入)
Step 3(前端) 5h(含试跑 0.3h;模型栏改只读 -0.5h,净 5h)
Step 4(计量) 1.5h
Step 5(测试上线) 2.5h
合计 约 17.5h ≈ 2.5 个工作日

(v1.0 是 11~14h;v1.2 定"只建 1 个 profile + 一对多",估量维持 16h —— 省下的是 profile 数量, 但多了骨架清理、Step -1 技术验证、接口字段表、member 裁剪四处细节。)


4. 决策详情与取舍说明

已定-A ✅ 所有智能体共用一套"人格"(老板已接受):明确这是"同一大脑、不同入口",非不同角色

决策 ④⑤ 已定"只建 ai-gateway 一个 profile",因此:

智能体之间能区分的 不能区分的
✅ 绑定的模型(各选各的) ❌ 系统提示词(共用 SOUL.md)
✅ 参数(temperature / max_tokens / top_p / system_suffix) ❌ 记忆文件(共用一份 MEMORY.md)
✅ 会话历史(各自独立) ❌ 工具开关(共用 profile 级设置)
✅ 名称 / 描述 / 访问范围 ❌ 人格 / 语气 / 专长

建议的一期用法:把智能体理解为"同一双手、不同工具配置的入口"—— 比如「代码审查」= 同一个引擎 + qwen3.8-flash + 低温参数;「周报助手」= 同一个引擎 + agnes-3.0-flash。 别指望它们像两个人。

升级路径(记着,别忘):真要独立人格时 → 给那个智能体单独建 profile(agents.yaml 的 engine.agent_id 换一个新的), 届时评估内存(当前 2C/3.6G,QwenPaw 已占 852MB)。

老板已接受。 由此要求 UI 必须显式说明(否则以后会困惑"为什么两个智能体像一个人"):

位置 提示文案(示意)
新建智能体弹窗顶部 ⓘ 智能体共用同一个引擎(ai-gateway),模型与参数各自独立,但提示词与记忆共用
配置页「引擎」区 当前引擎 ai-gateway(所有智能体共用)· 提示词与记忆请到 QwenPaw 修改
智能体数量达上限时 已达上限 5 个(软上限);需要更多时先归档不用的

已定-B ✅ 清掉私人内容(老板已定):Step 0 第 2 步执行

已定:清掉私人内容。 ai-gateway 的 SOUL.md / AGENTS.md 要新写一份"网关智能体"版本,不继承:

必须清掉 说明
"小银"身份 / 老板称呼 / 私人作息 它将来要给普通用户用,不能暴露你的个人信息
项目记忆 / MEMORY.md 里的私人上下文 同上
AGENTS.md 里的"工具调用自律"等会话规则 那是为我(default)写的,与网关智能体无关

保留:通用的"如何工作"(不乱删文件、破坏性操作先问、trash > rm 等安全约定)—— 这些对任何 agent 都适用。

验收:向 ai-gateway 问"你是谁" / "老板是谁",不应答出我的身份或你的私人信息。

已定-C ✅ 一期工具全开(老板已定):页面必须给风险提示

已定:一期全开(27 个工具 + 审批 OFF + 沙箱关)→ 引擎能读写文件、跑命令、开浏览器。 这是"全能"的来源,也是最大的风险面。落地要求:

要求 位置
对话页顶部常驻风险提示 「该智能体可在服务器上读写文件、执行命令」
配置页「能力」区显示实际开关与状态 27 项工具的启用情况(只读)
README / MEMORY 记录此风险 避免以后忘记
二期下发普通用户前必须收窄 已列进风险登记(硬前置)

已定-D ✅ 智能体数量软上限 5 个(老板已定)

  • 达到 5 个时,「新建」按钮禁用 + 提示「已达上限,请先归档不用的智能体」
  • 已归档(retired)不计入上限
  • 上限值写进配置(agents.yaml 顶层 max_agents: 5),以后改一行即可

已定(无需再确认)

项 结论
会话是否存正文副本 只存索引(正文在 QwenPaw 侧)
智能体可选模型范围 只允许文本模型(图片/视频模型不在 agent 里用)
智能体数量上限 软上限 5(agents.yaml 的 max_agents: 5,归档不计入)
Step 0 何时做 老板答复:新建 ai-gateway 不影响他在用的 default → 可直接做(但改 config.json 仍需备份+记回滚)
删除语义 归档 retired,不物理删
版本号 2.4.0 → 2.5.0
能力栏数据来源 静态说明 + 跳转 QwenPaw(不跨进程读配置)
引擎专用 Key agent-engine(新建,落 data/.env,不入库)
agents.yaml 入版本库(配置无秘密)
归档智能体历史 保留 + 可恢复
「试跑」按钮 一期加

5. 风险登记

风险 影响 对策
SSE 事件映射复杂 Step 2 可能超时 先做文本最小闭环,轨迹后加
QwenPaw 重启断在途对话 用户体验 一期提示"引擎重连中";二期 reconnect=true
网关 ↔ 引擎循环调用 死循环烧钱 校验 ai-gateway 的 active_model 不指向 agent/*(Step -1 第 5 项确认)+ 递归上限 3 层
内存(2C/3.6G) 多 profile 撑爆 一期 1 个 profile;二期评估升配
改 QwenPaw config.json 影响你正在用的会话 改前备份;记回滚方式;实测口径=新增 profile 不影响 default
引擎权限暴露 安全 仅 127.0.0.1;一期只 admin;下发前必须收窄工具+提审批等级
agents.yaml 入库后描述含敏感内容 泄密 提交前扫一遍描述;敏感内容写进 data/.env 而非 yaml
「试跑」被滥点消耗额度 费用 试跑限制频率(如 5s 冷却)+ 只发 1-token
system_suffix 被当成"绕过决策②的提示词通道" 架构漂移 限长 2000 字符 + UI 明确它只是"微调";要长提示词请去建 profile

6. 涉及文件清单

后端

  • 新增 app/agents.py(存储 + 适配器)
  • 改 app/main.py(7 个端点 + _require_admin 复用)
  • 改 app/config.py(agents 相关新配置项,如 params 白名单、max_agents)
  • 改 app/metrics.py(agent 维度)
  • 新增 data/agents.yaml(入库,需确认 .gitignore 没拦它)、data/agent_sessions.json、data/agent_runs.json(后两个不入库,需加进 .gitignore)
  • 改 data/.env(新增 AGENT_ENGINE_KEY,不入库)

前端

  • 新增 views/Agents.vue、components/AgentTrace.vue、lib/agents.ts
  • 改 router.ts、lib/nav.ts、components/Icon.vue、locales/zh.ts、locales/en.ts

QwenPaw 侧

  • 改 ~/.qwenpaw/config.json(profiles 加一项)
  • 新增 <工作区>/(骨架 + SOUL.md / AGENTS.md)

文档

  • 改 README.md、CHANGELOG.md
  • 改 MEMORY.md(本项目记忆)