前端间距(老板反馈「卡片上下左右间距不一样」): - .page / .page-fill 由 (上下≠左右)改为 var(--pad-page)=四周 16px; 窄屏 12px 14px → 四周 12px - 新增间距阶梯令牌 --pad-page / --gap-lg / --gap-sm;grid2/grid3/grid-eq/kpis/set-grid/ m-grid 的 gap 统一走 --gap-lg;窄屏 kpis 10px → var(--gap-sm) - 新增 .page-col > * + * 通用规则:纵向堆叠的卡片自动有间距 版本号纪律(老板 2026-09-29 立): - VERSION 2.4.0 → 2.4.1,README 新增「版本号与发布纪律」专章(含每次改动都要加版本号、 唯一权威定义处为 main.py 的 VERSION、发布流程、上生产必推 CNB) 其他: - .gitignore 新增 design/ 规则(设计稿脚本与 PNG 约 11MB,历史上从未入库,保持不入库) - docs/agents-dev-plan.md 智能体功能开发计划(27 条决策,待开工)
28 KiB
智能体(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 白名单 |
|
| ㉑ | 会话列表实现 | 复用 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,网关这边不接管
- 显示 QwenPaw 侧该 profile 当前生效的提示词文件路径(
- 多智能体共用一份提示词时,页面要显式提示这一点,别让用户以为改了 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 · 技术验证(约 0.5h)★ 动手前先做
1. ✔ 已做:核实"请求级指定模型"不可行(见 ⑲)→ 方案已按甲案修正
2. ✔ 已做:确认 PUT/GET /api/providers/active 支持 scope=agent + agent_id
3. 待做:录一段**完整真实 SSE 事件流**(含工具调用)当 Step 2 的测试夹具
4. 待做:确认 X-Agent-Id 选 profile 的行为(新建 profile 后)
4b. ★ 待做:**QwenPaw 的 `input` 接不接受 `role: "system"` 的消息**(决定 `system_suffix` 的注入方式,见 ㉖)
· 接受 → 网关插入一条 system 消息(干净)
· 不接受 → 改成拼进首条 user 消息前缀(UI 标注)
5. 待做:确认 ai-gateway profile 的 active_model 指向哪个 provider/model
(建议指向网关自己的 wangjinding provider + 别名 wjd,
这样引擎调模型也过网关,计量闭环)
验收:5 项都有明确结论;SSE 夹具落盘。
Step 0 · 建 QwenPaw profile ai-gateway(约 1h)★ 新增
0. 备份:cp /root/.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 会触发配置重载。实测口径是"新增 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 → 推 CNB(项目硬性规矩)
文档: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 侧
- 改
/root/.qwenpaw/config.json(profiles 加一项) - 新增
/root/.qwenpaw/workspaces/ai-gateway/(骨架 + SOUL.md / AGENTS.md)
文档
- 改
README.md、CHANGELOG.md - 改
MEMORY.md(本项目记忆)