前端间距(老板反馈「卡片上下左右间距不一样」): - .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 条决策,待开工)
476 lines
28 KiB
Markdown
476 lines
28 KiB
Markdown
# 智能体(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 · 技术验证(约 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 ~/.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 侧**
|
||
- 改 `~/.qwenpaw/config.json`(profiles 加一项)
|
||
- 新增 `<工作区>/`(骨架 + SOUL.md / AGENTS.md)
|
||
|
||
**文档**
|
||
- 改 `README.md`、`CHANGELOG.md`
|
||
- 改 `MEMORY.md`(本项目记忆)
|