From 4c04a5ed0e77d33176aa26c12a026f7617832ff9 Mon Sep 17 00:00:00 2001 From: api-gateway Date: Tue, 29 Sep 2026 12:08:04 +0800 Subject: [PATCH] =?UTF-8?q?=E6=A0=B7=E5=BC=8F=E8=A7=84=E8=8C=83=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=EF=BC=9A=E7=89=88=E6=9C=AC=202.4.0=E2=86=922.4.1=20+?= =?UTF-8?q?=20=E9=A1=B5=E9=9D=A2=E5=9B=9B=E5=91=A8=E7=AD=89=E8=B7=9D=20+?= =?UTF-8?q?=20=E9=97=B4=E8=B7=9D=E8=B5=B0=E4=BB=A4=E7=89=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 前端间距(老板反馈「卡片上下左右间距不一样」): - .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 条决策,待开工) --- .gitignore | 7 + README.md | 39 ++++ app/main.py | 4 +- docs/agents-dev-plan.md | 475 ++++++++++++++++++++++++++++++++++++++++ frontend/src/style.css | 46 +++- 5 files changed, 558 insertions(+), 13 deletions(-) create mode 100644 docs/agents-dev-plan.md diff --git a/.gitignore b/.gitignore index 2a218fe..c69aa59 100644 --- a/.gitignore +++ b/.gitignore @@ -38,6 +38,13 @@ data/*.bak # 说明:data/gateway.yaml 不含明文 Key —— 三家供应商密钥统一在 .env(已被上面忽略), # 由 yaml 各供应商的 token_env 引用。只要 .env 不提交,密钥就不会进版本库。 +# ── 设计稿(不入库,历史上从未入库)────────────────────────────────── +# design/v1、v2、v3 是"出设计图"用的脚本 + 渲染出的 PNG(约 11MB)。 +# 它们与产品构建、网关运行完全无关,且 2026-09-13 曾被清理归档到 +# /root/.trash/<归档>/design/(cp -a 可恢复)。 +# 需要时本地恢复即可,不进版本库。 +design/ + # ── 依赖与构建产物(不入库,均可重新生成:npm ci && npm run build)── node_modules/ frontend/node_modules/ diff --git a/README.md b/README.md index 595b5bd..20e79d6 100644 --- a/README.md +++ b/README.md @@ -1360,6 +1360,45 @@ curl "http://localhost:8808/v1/videos/?model=agnes-video-2.5-flash&wai > 拉线上产物实测含胶囊计数与空结果提示(`Logs`)、新版卡片结构(`Videos`)与窄屏缩略拉伸规则(`Videos` CSS)。 > 注意:**重启会踢掉所有网页会话,需重新登录**。 +## 版本号与发布纪律(★ 硬性,2026-09-29 老板立) + +### 1. 每次改动都要把版本号往上加 + +| 改动规模 | 版本号动作 | 例 | +|---|---|---| +| 小改动(修 bug、调样式、小优化) | **加小版本号** | `2.4.0 → 2.4.1` | +| 较大改动 / 大版本 | **加大版本号** | `2.4.1 → 2.5.0` | + +**唯一权威定义处**:`app/main.py` 的 + +```python +VERSION = "2.4.0" # ← 只改这一处 +``` + +它已被 `FastAPI(version=...)`、`GET /`、`GET /healthz`、`POST /auth/login` 的 +`gateway_version` 共用(第三十三轮收敛为单一常量)——**不要再在别处硬编码版本号**。 + +> **别混淆**:`frontend/package.json` 的 `"version": "0.1.0"` 与设计稿脚本里的 `v2.4.0` +> (`design/design/v2/build.py`、`design/design/v3/agents.py`)是**独立的东西**,不随 app 版本走。 + +### 2. 发布流程(改完照这个顺序走) + +``` +改代码 → 跑测试(python tests/test_gateway.py 或 bash scripts/ci_check.sh) + → 纯前端:npm run build(dist 即线上目录) + 后端/代码:supervisorctl restart api-gateway:api-gateway_00 + → 真机验证(线上 healthz / 页面 / 接口) + → git commit + → 推 CNB(scripts/push_cnb.sh,仓库 Jidekin/api-gateway 分支 master) +``` + +**「只要上生产就必须推 CNB」** 是既有硬性规矩(老板 2026-09-24 原话:「只要项目重启上线生产的 +代码都要推送到 cnb 上」):保持"线上跑着的代码 = 仓库里的代码"。**凡是重启上线(后端 restart) +或 `npm run build` 覆盖 `frontend/dist` 的代码改动,验证通过后都必须推 CNB**;纯注释/配置靠 +`hot_reload` 生效的也照推。落地脚本 `scripts/push_cnb.sh`(一次性带 token 内嵌 URL;不带 token +退出 2 / 工作区不干净退出 3 / 推完核对远端=本地并复查 `.git/config` 无 token;**token 不内置进 +任何文件**)。仓库 `https://cnb.cool/Jidekin/api-gateway.git`、分支 `master`。 + ## 测试 ```bash diff --git a/app/main.py b/app/main.py index 2061cf1..10a3262 100644 --- a/app/main.py +++ b/app/main.py @@ -332,7 +332,9 @@ _docs_on = config.server.docs_enabled # 安全默认关(report: /docs、/ope # 本轮修复: 版本号收敛到单一常量。此前 "2.4.0" 硬编码在 FastAPI / / 导航 / /auth/login # 三处,/health 干脆没返回版本 —— 前端「网关版本」一直显示 v-。 -VERSION = "2.4.0" +# 2026-09-29: 2.4.0 → 2.4.1(前端间距规范统一:页面四周等距 + 卡片间距走令牌)。 +# ★ 版本号纪律:每次改动都要往上加,小改动加小版本号、大改动加大版本号(README 有专章)。 +VERSION = "2.4.1" app = FastAPI( title="API Gateway", diff --git a/docs/agents-dev-plan.md b/docs/agents-dev-plan.md new file mode 100644 index 0000000..6ccd406 --- /dev/null +++ b/docs/agents-dev-plan.md @@ -0,0 +1,475 @@ +# 智能体(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_`),不新开端点 | +| ㉒ | `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_`) + 不新开端点 —— 列表/新建/重命名/删除全用现成的那套(㉑) +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`(本项目记忆) diff --git a/frontend/src/style.css b/frontend/src/style.css index ee574ae..af33687 100644 --- a/frontend/src/style.css +++ b/frontend/src/style.css @@ -20,6 +20,19 @@ --radius: 12px; --radius-l: 16px; --gap: 14px; + + /* ── 间距阶梯(第三十七轮立:spacing scale)──────────────────────── + 目的:页面四周上下左右一致、卡片之间间距统一,别再各写各的数字。 + 用法: + --pad-page 页面四周留白(上下左右必须相同!) + --gap-lg 块与块之间(卡片、栅格行) + --gap 卡片内部小节之间 + --gap-sm 行内元素之间 + 旧写法 `padding: 16px 20px` 的横纵不等已全部替换为 --pad-page。 */ + --pad-page: 16px; + --gap-lg: 14px; /* 块与块之间(= --gap,等价别名,新代码统一用它) */ + --gap-sm: 8px; /* 行内元素之间 */ + --font: -apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", "Source Han Sans SC", sans-serif; @@ -344,26 +357,33 @@ body { .avatar.alt { background: var(--chart-b); color: #fff; } .gw-body { flex: 1; min-height: 0; overflow: auto; } -.page { padding: 16px 20px; } +/* 第三十七轮:页面四周一律 --pad-page(上下左右相同)。 + 旧写法是 `16px 20px` —— 上 16 左 20,卡片看着总像"左边空一点",已弃用。 */ +.page { padding: var(--pad-page); } /* 全高页(对话 / 图像 / 视频):自己不滚,由内部区域滚 */ .page-fill { - padding: 16px 20px; height: 100%; min-height: 0; + padding: var(--pad-page); height: 100%; min-height: 0; display: flex; flex-direction: column; } /* ── 卡片 / KPI ─────────────────────────────────────────────────────── */ +/* 第三十七轮:让"页面里纵向堆叠的卡片"自动有间距,不用每个页面手写 margin-top。 + 用法:把这类容器加 class="page-col"(或已有的栅格类)。 + 相邻卡片之间 = --gap-lg,横纵一致。 */ +.page-col > * + * { margin-top: var(--gap-lg); } + .card { background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); padding: 14px; min-width: 0; } -.card-h { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; } +.card-h { display: flex; align-items: center; gap: var(--gap-sm); margin-bottom: 10px; } .card-h b { font-size: 13.5px; } .card-h .sub { font-size: 11.5px; color: var(--muted-2); } .legend { margin-left: auto; display: flex; gap: 12px; font-size: 11.5px; color: var(--muted); } .legend i { width: 8px; height: 8px; border-radius: 3px; display: inline-block; margin-right: 5px; } .pager { display: flex; align-items: center; gap: 6px; margin-left: auto; font-size: 12px; color: var(--muted); } -.kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--gap); } +.kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--gap-lg); } .kpi { background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); padding: 13px 14px; min-width: 0; } .kpi .k { font-size: 12px; color: var(--muted); display: flex; align-items: center; gap: 6px; } .kpi .v { font-size: 24px; font-weight: 700; margin-top: 7px; font-variant-numeric: tabular-nums; letter-spacing: -.4px; } @@ -376,9 +396,10 @@ body { .spark i { width: 4px; border-radius: 2px; background: var(--primary); opacity: .32; display: block; } .spark i.hi { opacity: .9; } -.grid2 { display: grid; grid-template-columns: 1.55fr 1fr; gap: var(--gap); margin-top: var(--gap); } -.grid3 { display: grid; grid-template-columns: 1.35fr 1fr; gap: var(--gap); margin-top: var(--gap); } -.grid-eq { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap); margin-top: var(--gap); } +/* 栅格行:行间 = 块间距,列间 = 块间距(横纵一致) */ +.grid2 { display: grid; grid-template-columns: 1.55fr 1fr; gap: var(--gap-lg); margin-top: var(--gap-lg); } +.grid3 { display: grid; grid-template-columns: 1.35fr 1fr; gap: var(--gap-lg); margin-top: var(--gap-lg); } +.grid-eq { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-lg); margin-top: var(--gap-lg); } /* 供应商状态 / 路由链这类「名称 + 条 + 状态」的竖排列表 */ .pv { display: flex; flex-direction: column; gap: 9px; } @@ -412,7 +433,7 @@ body { .code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; letter-spacing: .2px; } /* ── 设置 / 用户页共用的行式布局与主题卡 ────────────────────────────── */ -.set-grid { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap); } +.set-grid { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-lg); } .set-row { display: flex; align-items: center; gap: 12px; padding: 10px 0; border-bottom: 1px solid var(--line-2); font-size: 13px; min-width: 0; @@ -592,7 +613,7 @@ body { .m-kpi { background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); padding: 11px 12px; } .m-kpi .k { font-size: 11.5px; color: var(--muted); } .m-kpi .v { font-size: 19px; font-weight: 700; margin-top: 5px; font-variant-numeric: tabular-nums; } -.m-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; } +.m-grid { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-lg); } /* 抽屉导航(el-drawer teleport 到 body,样式写在全局层) */ .nav-drawer .el-drawer__body { padding: 0; overflow: hidden; background: var(--surface); } @@ -621,9 +642,10 @@ body { /* ── 窄屏:只做全局兜底,结构切换(侧栏 → 抽屉 + 底部 Tab)在 JS 里 ──── 断点须与 src/lib/ui.ts 的 MOBILE_MAX=768 保持一致。 */ @media (max-width: 768px) { - .page { padding: 12px 14px; } - .page-fill { padding: 12px 14px; } - .kpis { grid-template-columns: 1fr 1fr; gap: 10px; } + /* 窄屏同样取等距的收窄值(12px 四周) */ + .page { padding: 12px; } + .page-fill { padding: 12px; } + .kpis { grid-template-columns: 1fr 1fr; gap: var(--gap-sm); } .kpi .v { font-size: 19px; } .grid2, .grid3, .grid-eq { grid-template-columns: 1fr; } .top { padding: 0 12px; }