feat(agents): 新增「智能体」功能模块(路线 A)+ 版本 2.5.0
老板要求「在 ai 网关里做智能体 agent,新的一个菜单」,一期仅管理员、成熟后下发。 完整设计(27 条决策,4 轮评审)见 docs/agents-dev-plan.md。 架构(路线 A):界面与权限在网关,执行在 QwenPaw(独立 profile ai-gateway)。 网关当门面(鉴权/计量/灰度/审计),引擎提供工具能力(文件/命令/浏览器)。 Step -1 技术验证(实测,全部改变或确认了设计): - 请求级指定模型【无效】:传 model 被忽略,turn_usage 回 provider_id=opencode、 model_name=deepseek-v4.1-flash;AgentRequest 无 model 字段。模型是 profile 级。 → 甲案:所有智能体共用 ai-gateway 一个 profile ⇒ 共用同一模型,配置页模型栏只读。 - role:"system"【被接受且生效】:塞入「只用英文回答」后模型真的用英文 → params.system_suffix 走注入 system 消息。 - SSE 事件谱已录制 → tests/fixtures/sse-tool-flow.sse + docs/qwenpaw-agent-api-sse.md 后端: - app/agents.py:AgentStore(data/agents.yaml,600/原子写/mtime 热载)+ 严格校验 (slug 三重查重:模型 id/别名/QwenPaw profile;params 4 键白名单;suffix 限长 2000; max_agents=5 软上限,归档不计入;restore 可恢复) - app/adapters/qwenpaw_engine.py:OpenAI 形状 ↔ AgentScope Agent API + SSE 翻译器 (text 累积、delta:false 快照忽略、plugin_call→轨迹、call_id 配对 output、turn_usage→计量) - app/agents_routes.py:GET/POST/PUT/DELETE /agents、/restore、/chat(SSE)、/stop、 /runs、/sessions、/test + 新增 GET /auth/me(灰度通道,features.agents 后端权威); 权限唯一入口 can_use_agent();防自指(引擎模型不得指向 agent/*) - app/history.py:会话类别扩展支持 agent_<slug>(复用现有存储) - data/agents.yaml(配置,入库);data/agent_runs.json(运行时,gitignore) 前端: - views/Agents.vue(列表 + 对话/配置/运行记录)+ lib/agents.ts(SSE 解析) - 菜单核心组第 5 位 + 图标 bot;router meta.admin 双层守卫;i18n 中英对称 871/871 上线实测:真实对话跑通 —— 让智能体 read_file 读 /etc/hostname,前端正确显示 「执行了 1 步」+ 工具参数、正文、计量(wjd · 47196 tokens · 缓存 13696)、终态; 引擎调用经 wangjinding 过网关(计量闭环)。 测试 209 → 217 全过(新增 8 条,含用真实夹具验证 SSE 翻译器);ci_check 全绿。
This commit is contained in:
1 parent
bccb72bad5
commit
51c9af59c4
19 files changed
+3064
-26
No files matched your search
@@ -0,0 +1,320 @@
|
||||
"""QwenPaw 引擎适配器(第三十八轮 · 路线 A)。
|
||||
|
||||
把网关的对话请求转成 QwenPaw 的 **AgentScope Agent API** 形状,再把它的 SSE 事件流
|
||||
翻译回网关前端认识的形式。
|
||||
|
||||
协议事实全部来自实测 —— 见 `docs/qwenpaw-agent-api-sse.md` 与
|
||||
`tests/fixtures/sse-tool-flow.sse`。要点:
|
||||
|
||||
- `POST {base}/api/console/chat`,body `{input: [Message], session_id, stream: true}`
|
||||
- 头 `X-Agent-Id: <profile>` 选择 QwenPaw 侧用哪个智能体 profile
|
||||
- 回 SSE(前缀固定 `data: `,**没有 event: 行**)
|
||||
- 事件:`text` / `plugin_call` / `plugin_call_output` / `data` / `message` / `response` / `turn_usage`
|
||||
- `role: "system"` 的输入消息**被接受且生效**(实测)→ `system_suffix` 走这条
|
||||
- `model` 字段**被忽略**(实测)→ 模型是 profile 级,不在请求里指定
|
||||
|
||||
网关对前端的输出形状(自定义、简单):
|
||||
|
||||
```jsonc
|
||||
{"type": "text", "text": "增量"} // 正文增量
|
||||
{"type": "step", "id": "...", "name": "read_file", "args": {...}, "status": "running"}
|
||||
{"type": "step", "id": "...", "status": "done", "ms": 320, "output": "..."}
|
||||
{"type": "usage", "prompt": 1, "completion": 2, "cached": 0, "model": "wjd", "context_ratio": 0.02}
|
||||
{"type": "done", "status": "completed"}
|
||||
{"type": "error", "message": "..."}
|
||||
```
|
||||
|
||||
这样前端不必理解 AgentScope 的事件细节。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
from typing import Any, AsyncIterator
|
||||
|
||||
import httpx
|
||||
|
||||
log = logging.getLogger("api-gateway.agents")
|
||||
|
||||
#: 单轮对话的超时(秒)。引擎可能跑很久(多步工具),给足。
|
||||
DEFAULT_TIMEOUT = 300.0
|
||||
|
||||
#: 引擎不可达时的兜底文案。
|
||||
ENGINE_DOWN_MSG = "引擎不可达(QwenPaw 未运行或未就绪)"
|
||||
|
||||
|
||||
class EngineError(Exception):
|
||||
"""引擎层错误(映射为 502)。"""
|
||||
|
||||
|
||||
# ── 请求构造 ──────────────────────────────────────────────────────────
|
||||
def build_input(messages: list[dict[str, Any]], system_suffix: str = "") -> list[dict[str, Any]]:
|
||||
"""把网关侧的消息列表转成 AgentScope 的 `input`。
|
||||
|
||||
- 网关历史里的 role/文本 → `{role, content:[{type:"text", text}]}`
|
||||
- `system_suffix` → 在最前面插一条 **system 消息**(实测被接受且生效)
|
||||
- `system` 角色的历史消息也照传(引擎接受)
|
||||
"""
|
||||
out: list[dict[str, Any]] = []
|
||||
if system_suffix:
|
||||
out.append({
|
||||
"role": "system",
|
||||
"content": [{"type": "text", "text": system_suffix}],
|
||||
})
|
||||
for m in messages:
|
||||
role = (m.get("role") or "user").lower()
|
||||
if role not in ("user", "assistant", "system"):
|
||||
role = "user"
|
||||
content = m.get("content")
|
||||
# content 允许是字符串或 [{type:text,text}] 形状
|
||||
if isinstance(content, str):
|
||||
parts = [{"type": "text", "text": content}]
|
||||
elif isinstance(content, list):
|
||||
parts = []
|
||||
for c in content:
|
||||
if isinstance(c, str):
|
||||
parts.append({"type": "text", "text": c})
|
||||
elif isinstance(c, dict) and c.get("type") == "text":
|
||||
parts.append({"type": "text", "text": str(c.get("text") or "")})
|
||||
# 图片等一期不支持,静默跳过(计划「一期不做图片/附件」)
|
||||
else:
|
||||
parts = [{"type": "text", "text": str(content or "")}]
|
||||
out.append({"role": role, "content": parts})
|
||||
return out
|
||||
|
||||
|
||||
def build_body(messages: list[dict[str, Any]], session_id: str,
|
||||
system_suffix: str = "") -> dict[str, Any]:
|
||||
return {
|
||||
"input": build_input(messages, system_suffix),
|
||||
"session_id": session_id,
|
||||
"stream": True,
|
||||
}
|
||||
|
||||
|
||||
# ── SSE 解析与翻译 ────────────────────────────────────────────────────
|
||||
def parse_sse_line(line: str) -> dict[str, Any] | None:
|
||||
"""把一行 SSE 解析成事件 dict;非数据行返回 None。"""
|
||||
if not line.startswith("data:"):
|
||||
return None
|
||||
payload = line[5:].strip()
|
||||
if not payload or payload == "[DONE]":
|
||||
return None
|
||||
try:
|
||||
obj = json.loads(payload)
|
||||
except json.JSONDecodeError:
|
||||
log.debug("引擎 SSE 非 JSON 行(忽略):%.120s", payload)
|
||||
return None
|
||||
return obj if isinstance(obj, dict) else None
|
||||
|
||||
|
||||
class StreamTranslator:
|
||||
"""把引擎的事件序列翻译成网关前端的消息序列(有状态)。
|
||||
|
||||
状态:
|
||||
- `_text_buf`: 已累积的正文(用来在结束时兜底补全)
|
||||
- `_steps`: call_id → 步骤信息(配对 plugin_call / plugin_call_output)
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.text_parts: list[str] = []
|
||||
self.steps: dict[str, dict[str, Any]] = {}
|
||||
self.usage: dict[str, Any] | None = None
|
||||
self.final_status: str = "completed"
|
||||
self._step_started: dict[str, float] = {}
|
||||
|
||||
# ── 单事件 → 若干前端消息 ──
|
||||
def feed(self, ev: dict[str, Any], now: float | None = None) -> list[dict[str, Any]]:
|
||||
import time
|
||||
now = now or time.time()
|
||||
t = ev.get("type")
|
||||
out: list[dict[str, Any]] = []
|
||||
|
||||
if t == "text":
|
||||
# delta:true 是增量;delta:false 是整段快照 —— 忽略,否则会重复
|
||||
if ev.get("delta") is False:
|
||||
return out
|
||||
piece = ev.get("text")
|
||||
if isinstance(piece, str) and piece:
|
||||
self.text_parts.append(piece)
|
||||
out.append({"type": "text", "text": piece})
|
||||
return out
|
||||
|
||||
if t == "plugin_call":
|
||||
info = _extract_call(ev, key="arguments")
|
||||
if info:
|
||||
cid = info.get("call_id") or info.get("name") or "?"
|
||||
self.steps[cid] = info
|
||||
self._step_started[cid] = now
|
||||
out.append({
|
||||
"type": "step", "id": cid, "name": info.get("name"),
|
||||
"args": info.get("args"), "status": "running",
|
||||
})
|
||||
return out
|
||||
|
||||
if t == "plugin_call_output":
|
||||
info = _extract_call(ev, key="output")
|
||||
if info:
|
||||
cid = info.get("call_id") or info.get("name") or "?"
|
||||
started = self._step_started.pop(cid, None)
|
||||
ms = int((now - started) * 1000) if started else None
|
||||
if cid in self.steps:
|
||||
self.steps[cid]["status"] = "done"
|
||||
msg: dict[str, Any] = {"type": "step", "id": cid, "status": "done"}
|
||||
if ms is not None:
|
||||
msg["ms"] = ms
|
||||
if info.get("output") is not None:
|
||||
msg["output"] = _clip(info["output"])
|
||||
out.append(msg)
|
||||
return out
|
||||
|
||||
if t == "turn_usage":
|
||||
u = ev.get("usage") or {}
|
||||
self.usage = u
|
||||
ctx = ev.get("context_usage") or {}
|
||||
out.append({
|
||||
"type": "usage",
|
||||
"prompt": int(u.get("prompt_tokens") or 0),
|
||||
"completion": int(u.get("completion_tokens") or 0),
|
||||
"cached": int(u.get("cache_read_tokens") or 0),
|
||||
"model": u.get("model_name") or "",
|
||||
"provider": u.get("provider_id") or "",
|
||||
"context_ratio": ctx.get("context_usage_ratio"),
|
||||
})
|
||||
return out
|
||||
|
||||
if t == "response":
|
||||
st = ev.get("status")
|
||||
if st:
|
||||
self.final_status = st
|
||||
if st in ("failed", "cancelled"):
|
||||
out.append({"type": "done", "status": st})
|
||||
return out
|
||||
|
||||
# data / message 等其余事件:忽略(分片由快照覆盖)
|
||||
return out
|
||||
|
||||
def finish(self) -> list[dict[str, Any]]:
|
||||
"""流结束时收尾。"""
|
||||
out: list[dict[str, Any]] = []
|
||||
if self.final_status not in ("failed", "cancelled"):
|
||||
out.append({"type": "done", "status": self.final_status})
|
||||
elif self.final_status == "cancelled":
|
||||
out.append({"type": "done", "status": "cancelled"})
|
||||
return out
|
||||
|
||||
@property
|
||||
def text(self) -> str:
|
||||
return "".join(self.text_parts)
|
||||
|
||||
|
||||
def _extract_call(ev: dict[str, Any], *, key: str) -> dict[str, Any] | None:
|
||||
"""从 plugin_call / plugin_call_output 里取 {call_id, name, args|output}。
|
||||
|
||||
结构(实测):`content[0].data = {call_id, name, arguments|output}`
|
||||
注意 `arguments` 是 **JSON 字符串**,要二次解析。
|
||||
"""
|
||||
content = ev.get("content")
|
||||
if not isinstance(content, list):
|
||||
return None
|
||||
for c in content:
|
||||
if not isinstance(c, dict):
|
||||
continue
|
||||
data = c.get("data")
|
||||
if not isinstance(data, dict) or key not in data:
|
||||
continue
|
||||
info: dict[str, Any] = {
|
||||
"call_id": data.get("call_id"),
|
||||
"name": data.get("name"),
|
||||
}
|
||||
raw = data.get(key)
|
||||
if key == "arguments":
|
||||
info["args"] = _maybe_json(raw)
|
||||
else:
|
||||
info["output"] = raw
|
||||
return info
|
||||
return None
|
||||
|
||||
|
||||
def _maybe_json(v: Any) -> Any:
|
||||
"""`arguments` 是 JSON 字符串 → 解析成对象;解析不了就原样返回字符串。"""
|
||||
if not isinstance(v, str):
|
||||
return v
|
||||
try:
|
||||
return json.loads(v)
|
||||
except (json.JSONDecodeError, TypeError):
|
||||
return v
|
||||
|
||||
|
||||
def _clip(v: Any, limit: int = 4000) -> Any:
|
||||
"""工具输出可能很长 —— 转发给前端前裁一刀(避免 SSE 帧过大)。"""
|
||||
if isinstance(v, str) and len(v) > limit:
|
||||
return v[:limit] + "…(已截断)"
|
||||
return v
|
||||
|
||||
|
||||
# ── 调用引擎 ──────────────────────────────────────────────────────────
|
||||
async def stream_chat(base_url: str, agent_id: str, messages: list[dict[str, Any]],
|
||||
session_id: str, *, system_suffix: str = "",
|
||||
timeout: float = DEFAULT_TIMEOUT) -> AsyncIterator[dict[str, Any]]:
|
||||
"""打引擎并产出"已翻译"的前端消息。
|
||||
|
||||
用法:
|
||||
async for msg in stream_chat(...): # msg 就是 {type: text|step|usage|done|error}
|
||||
yield sse(msg)
|
||||
"""
|
||||
url = base_url.rstrip("/") + "/api/console/chat"
|
||||
body = build_body(messages, session_id, system_suffix)
|
||||
tr = StreamTranslator()
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"Accept": "text/event-stream",
|
||||
"X-Agent-Id": agent_id,
|
||||
}
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=10.0)) as client:
|
||||
async with client.stream("POST", url, headers=headers, json=body) as resp:
|
||||
if resp.status_code >= 400:
|
||||
raw = (await resp.aread()).decode("utf-8", "replace")[:300]
|
||||
yield {"type": "error",
|
||||
"message": f"引擎返回 {resp.status_code}:{raw}"}
|
||||
return
|
||||
async for line in resp.aiter_lines():
|
||||
ev = parse_sse_line(line)
|
||||
if ev is None:
|
||||
continue
|
||||
for msg in tr.feed(ev):
|
||||
yield msg
|
||||
for msg in tr.finish():
|
||||
yield msg
|
||||
except httpx.ConnectError:
|
||||
yield {"type": "error", "message": ENGINE_DOWN_MSG}
|
||||
except httpx.ReadTimeout:
|
||||
yield {"type": "error", "message": "引擎响应超时(本轮未完成)"}
|
||||
except httpx.RemoteProtocolError:
|
||||
# 引擎中途断开 —— 保留已收到的内容(前端自己累积着),只提示中断
|
||||
for msg in tr.finish():
|
||||
pass
|
||||
yield {"type": "error", "message": "引擎连接中断,本轮未完成"}
|
||||
except Exception as exc: # noqa: BLE001 —— 兜底,别让流把异常抛给客户端
|
||||
log.exception("引擎调用失败")
|
||||
yield {"type": "error", "message": f"引擎调用失败:{exc}"}
|
||||
|
||||
|
||||
async def check_engine(base_url: str, *, timeout: float = 5.0) -> tuple[bool, str]:
|
||||
"""探活:引擎是否可达。返回 (ok, 说明)。
|
||||
|
||||
不引 `/api/healthz`(那是 QwenPaw 的)—— 用最轻的请求确认端口活着。
|
||||
"""
|
||||
url = base_url.rstrip("/") + "/api/healthz"
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=timeout) as client:
|
||||
r = await client.get(url)
|
||||
if r.status_code < 500:
|
||||
return True, "就绪"
|
||||
return False, f"引擎异常(HTTP {r.status_code})"
|
||||
except httpx.ConnectError:
|
||||
return False, ENGINE_DOWN_MSG
|
||||
except Exception as exc: # noqa: BLE001
|
||||
return False, f"引擎不可达:{exc}"
|
||||
+521
@@ -0,0 +1,521 @@
|
||||
"""智能体(Agent)定义:存储 + 校验(第三十八轮,路线 A)。
|
||||
|
||||
背景与设计见 `docs/agents-dev-plan.md`。要点:
|
||||
|
||||
- **路线 A**:界面在网关,引擎是 QwenPaw(独立 profile `ai-gateway`)。
|
||||
- **甲案**:模型是 profile 级的(请求级指定无效,已实测),而所有智能体共用
|
||||
`ai-gateway` 一个 profile ⇒ **所有智能体共用同一个模型**。所以这里**不存 model**。
|
||||
- 智能体之间的区别只剩:名称/描述 + 参数(temperature/max_tokens/top_p/system_suffix)
|
||||
+ 各自的会话历史。
|
||||
- 提示词归 QwenPaw 管(决策②),这里**不存 system_prompt** 主提示词;
|
||||
`params.system_suffix` 只是一小条角色补充(网关侧注入)。
|
||||
|
||||
存储:`data/agents.yaml`(600、原子写、mtime 热载)。**配置无秘密,可入库**。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
import threading
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
# ── 常量 ──────────────────────────────────────────────────────────────
|
||||
DEFAULT_PATH = Path(__file__).resolve().parent.parent / "data" / "agents.yaml"
|
||||
|
||||
#: slug 规则:小写字母开头,允许小写字母/数字/连字符,2~32 位
|
||||
_SLUG_RE = re.compile(r"^[a-z][a-z0-9-]{1,31}$")
|
||||
|
||||
#: 智能体级参数白名单(决策 ㉗)。
|
||||
#: 只放"采样/长度类"和一小条角色后缀 —— 结构性键(model/messages/stream/tools)刻意排除,
|
||||
#: 防止用户从这儿绕过网关往上游塞结构。
|
||||
AGENT_PARAM_KEYS: frozenset[str] = frozenset({
|
||||
"temperature", "max_tokens", "top_p", "system_suffix",
|
||||
})
|
||||
|
||||
#: system_suffix 长度上限(字符)。它是"角色微调",不是主提示词通道 ——
|
||||
#: 要写长提示词请去 QwenPaw 建 profile(决策 ㉖ 的边界)。
|
||||
SYSTEM_SUFFIX_MAX = 2000
|
||||
|
||||
#: 未归档智能体的数量上限(决策 ⑫,软上限)。
|
||||
DEFAULT_MAX_AGENTS = 5
|
||||
|
||||
#: 允许的访问角色(二期下发用;一期固定 admin)。
|
||||
ALLOWED_ROLES = frozenset({"admin", "member"})
|
||||
|
||||
#: 允许的状态。
|
||||
ALLOWED_STATUS = frozenset({"draft", "published", "retired"})
|
||||
|
||||
#: 引擎类型(一期只有 qwenpaw 一种)。
|
||||
ENGINE_TYPES = frozenset({"qwenpaw"})
|
||||
|
||||
#: 默认引擎地址(QwenPaw 本机,免鉴权)。
|
||||
DEFAULT_ENGINE_URL = "http://127.0.0.1:8088"
|
||||
|
||||
#: 默认引擎 profile id。
|
||||
DEFAULT_ENGINE_AGENT = "ai-gateway"
|
||||
|
||||
|
||||
class AgentsError(ValueError):
|
||||
"""智能体配置校验失败(映射为 400)。"""
|
||||
|
||||
|
||||
def _now() -> str:
|
||||
return time.strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
|
||||
# ── 校验辅助 ──────────────────────────────────────────────────────────
|
||||
def _require_str(value: Any, where: str, *, maxlen: int = 200) -> str:
|
||||
if not isinstance(value, str):
|
||||
raise AgentsError(f"{where} 必须是字符串")
|
||||
v = value.strip()
|
||||
if not v:
|
||||
raise AgentsError(f"{where} 不能为空")
|
||||
if len(v) > maxlen:
|
||||
raise AgentsError(f"{where} 过长(上限 {maxlen} 字符)")
|
||||
return v
|
||||
|
||||
|
||||
def validate_slug(slug: Any) -> str:
|
||||
"""校验 slug 形态(唯一性由调用方另行校验)。"""
|
||||
if not isinstance(slug, str) or not _SLUG_RE.match(slug):
|
||||
raise AgentsError(
|
||||
"slug 只能是小写字母开头、由小写字母/数字/连字符组成,长度 2~32(如 code-review)"
|
||||
)
|
||||
return slug
|
||||
|
||||
|
||||
def validate_params(params: Any) -> dict[str, Any]:
|
||||
"""校验智能体级参数:只认白名单,类型不对就报错(不静默忽略)。"""
|
||||
if params is None:
|
||||
return {}
|
||||
if not isinstance(params, dict):
|
||||
raise AgentsError("params 必须是映射(键值对)")
|
||||
out: dict[str, Any] = {}
|
||||
for k, v in params.items():
|
||||
if k not in AGENT_PARAM_KEYS:
|
||||
raise AgentsError(
|
||||
f"params.{k} 不是允许的智能体参数(允许:{', '.join(sorted(AGENT_PARAM_KEYS))})"
|
||||
)
|
||||
if k == "system_suffix":
|
||||
if not isinstance(v, str):
|
||||
raise AgentsError("params.system_suffix 必须是字符串")
|
||||
if len(v) > SYSTEM_SUFFIX_MAX:
|
||||
raise AgentsError(
|
||||
f"params.system_suffix 过长(上限 {SYSTEM_SUFFIX_MAX} 字符)——"
|
||||
"它是角色补充,主提示词请到 QwenPaw 的 profile 里改"
|
||||
)
|
||||
out[k] = v.strip()
|
||||
continue
|
||||
# temperature / top_p:浮点;max_tokens:整数
|
||||
if isinstance(v, bool) or not isinstance(v, (int, float)):
|
||||
raise AgentsError(f"params.{k} 必须是数字")
|
||||
if k == "max_tokens":
|
||||
iv = int(v)
|
||||
if iv <= 0:
|
||||
raise AgentsError("params.max_tokens 必须大于 0")
|
||||
out[k] = iv
|
||||
else:
|
||||
fv = float(v)
|
||||
if k == "temperature" and not (0.0 <= fv <= 2.0):
|
||||
raise AgentsError("params.temperature 取值范围 0~2")
|
||||
if k == "top_p" and not (0.0 < fv <= 1.0):
|
||||
raise AgentsError("params.top_p 取值范围 (0, 1]")
|
||||
out[k] = fv
|
||||
return out
|
||||
|
||||
|
||||
# ── 数据模型 ──────────────────────────────────────────────────────────
|
||||
@dataclass
|
||||
class Agent:
|
||||
slug: str
|
||||
display_name: str
|
||||
description: str = ""
|
||||
params: dict[str, Any] = field(default_factory=dict)
|
||||
engine_type: str = "qwenpaw"
|
||||
engine_base_url: str = DEFAULT_ENGINE_URL
|
||||
engine_agent_id: str = DEFAULT_ENGINE_AGENT
|
||||
access_roles: list[str] = field(default_factory=lambda: ["admin"])
|
||||
access_users: list[str] = field(default_factory=list)
|
||||
status: str = "published"
|
||||
created_at: str = ""
|
||||
updated_at: str = ""
|
||||
|
||||
# ── 序列化 ──
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"slug": self.slug,
|
||||
"display_name": self.display_name,
|
||||
"description": self.description,
|
||||
"params": dict(self.params),
|
||||
"engine": {
|
||||
"type": self.engine_type,
|
||||
"base_url": self.engine_base_url,
|
||||
"agent_id": self.engine_agent_id,
|
||||
},
|
||||
"access": {"roles": list(self.access_roles), "users": list(self.access_users)},
|
||||
"status": self.status,
|
||||
"created_at": self.created_at,
|
||||
"updated_at": self.updated_at,
|
||||
}
|
||||
|
||||
def public_dict(self) -> dict[str, Any]:
|
||||
"""给前端列表/详情用的字段(含引擎实况位,由调用方补)。
|
||||
|
||||
注意:**不含** system_suffix 之外的敏感内容 —— 由路由层按角色再裁。
|
||||
"""
|
||||
d = self.to_dict()
|
||||
d["engine_type"] = self.engine_type
|
||||
d["access_scope"] = "admin" if self.access_roles == ["admin"] and not self.access_users else "custom"
|
||||
return d
|
||||
|
||||
|
||||
def _parse_agent(slug: str, raw: Any) -> Agent:
|
||||
"""从 YAML 的一段解析出一个 Agent(严格校验,报错就抛)。"""
|
||||
where = f"agents.{slug}"
|
||||
validate_slug(slug)
|
||||
if not isinstance(raw, dict):
|
||||
raise AgentsError(f"{where} 必须是一个映射")
|
||||
|
||||
# 不接受别名之外的未知键(防拼错后静默失效)
|
||||
known = {"display_name", "name", "description", "params", "engine",
|
||||
"access", "status", "created_at", "updated_at"}
|
||||
unknown = set(raw) - known
|
||||
if unknown:
|
||||
raise AgentsError(f"{where} 含未知字段:{', '.join(sorted(unknown))}")
|
||||
|
||||
display_name = _require_str(
|
||||
raw.get("display_name") or raw.get("name"), f"{where}.display_name", maxlen=60
|
||||
)
|
||||
description = raw.get("description") or ""
|
||||
if not isinstance(description, str):
|
||||
raise AgentsError(f"{where}.description 必须是字符串")
|
||||
description = description.strip()[:200]
|
||||
|
||||
params = validate_params(raw.get("params"))
|
||||
|
||||
eng = raw.get("engine") or {}
|
||||
if not isinstance(eng, dict):
|
||||
raise AgentsError(f"{where}.engine 必须是映射")
|
||||
etype = eng.get("type", "qwenpaw")
|
||||
if etype not in ENGINE_TYPES:
|
||||
raise AgentsError(
|
||||
f"{where}.engine.type 只支持 {'/'.join(sorted(ENGINE_TYPES))}(当前:{etype})"
|
||||
)
|
||||
base_url = _require_str(eng.get("base_url") or DEFAULT_ENGINE_URL,
|
||||
f"{where}.engine.base_url", maxlen=200)
|
||||
agent_id = _require_str(eng.get("agent_id") or DEFAULT_ENGINE_AGENT,
|
||||
f"{where}.engine.agent_id", maxlen=64)
|
||||
|
||||
acc = raw.get("access") or {}
|
||||
if not isinstance(acc, dict):
|
||||
raise AgentsError(f"{where}.access 必须是映射")
|
||||
roles = acc.get("roles") or ["admin"]
|
||||
users = acc.get("users") or []
|
||||
if not isinstance(roles, list) or not all(isinstance(r, str) for r in roles):
|
||||
raise AgentsError(f"{where}.access.roles 必须是字符串列表")
|
||||
bad = set(roles) - ALLOWED_ROLES
|
||||
if bad:
|
||||
raise AgentsError(
|
||||
f"{where}.access.roles 含非法角色:{', '.join(sorted(bad))}"
|
||||
f"(允许:{', '.join(sorted(ALLOWED_ROLES))})"
|
||||
)
|
||||
if not isinstance(users, list) or not all(isinstance(u, str) for u in users):
|
||||
raise AgentsError(f"{where}.access.users 必须是字符串列表")
|
||||
|
||||
status = raw.get("status", "published")
|
||||
if status not in ALLOWED_STATUS:
|
||||
raise AgentsError(
|
||||
f"{where}.status 非法:{status}(允许:{', '.join(sorted(ALLOWED_STATUS))})"
|
||||
)
|
||||
|
||||
return Agent(
|
||||
slug=slug,
|
||||
display_name=display_name,
|
||||
description=description,
|
||||
params=params,
|
||||
engine_type=etype,
|
||||
engine_base_url=base_url,
|
||||
engine_agent_id=agent_id,
|
||||
access_roles=list(roles),
|
||||
access_users=list(u.strip() for u in users if u.strip()),
|
||||
status=status,
|
||||
created_at=str(raw.get("created_at") or ""),
|
||||
updated_at=str(raw.get("updated_at") or ""),
|
||||
)
|
||||
|
||||
|
||||
# ── 存储 ──────────────────────────────────────────────────────────────
|
||||
class AgentStore:
|
||||
"""`data/agents.yaml` 的读写与校验。
|
||||
|
||||
- 原子写(临时文件 + rename)+ 备份(复用 settings.write_config 的语义)
|
||||
- mtime 热载:文件被改后自动重读,不必重启
|
||||
- 线程锁:读写都加锁,单进程够用
|
||||
"""
|
||||
|
||||
def __init__(self, path: str | Path | None = None) -> None:
|
||||
self.path = Path(path) if path else DEFAULT_PATH
|
||||
self._lock = threading.RLock()
|
||||
self._agents: dict[str, Agent] = {}
|
||||
self._max_agents: int = DEFAULT_MAX_AGENTS
|
||||
self._mtime: float = 0.0
|
||||
self._load()
|
||||
|
||||
# ── 读 ──
|
||||
def _load(self, *, force: bool = False) -> None:
|
||||
with self._lock:
|
||||
if not self.path.exists():
|
||||
self._agents, self._max_agents = {}, DEFAULT_MAX_AGENTS
|
||||
self._mtime = 0.0
|
||||
return
|
||||
mtime = self.path.stat().st_mtime
|
||||
if not force and mtime == self._mtime:
|
||||
return
|
||||
raw = yaml.safe_load(self.path.read_text(encoding="utf-8")) or {}
|
||||
if not isinstance(raw, dict):
|
||||
raise AgentsError("agents.yaml 顶层必须是映射")
|
||||
unknown = set(raw) - {"max_agents", "agents", "version"}
|
||||
if unknown:
|
||||
raise AgentsError(f"agents.yaml 含未知顶层键:{', '.join(sorted(unknown))}")
|
||||
mx = raw.get("max_agents", DEFAULT_MAX_AGENTS)
|
||||
if isinstance(mx, bool) or not isinstance(mx, int) or mx < 1:
|
||||
raise AgentsError("max_agents 必须是 ≥1 的整数")
|
||||
items = raw.get("agents") or {}
|
||||
if not isinstance(items, dict):
|
||||
raise AgentsError("agents 段必须是映射(slug → 定义)")
|
||||
agents: dict[str, Agent] = {}
|
||||
for slug, body in items.items():
|
||||
agents[str(slug)] = _parse_agent(str(slug), body)
|
||||
self._agents = agents
|
||||
self._max_agents = int(mx)
|
||||
self._mtime = mtime
|
||||
|
||||
def reload_if_changed(self) -> bool:
|
||||
"""文件变了就重读(供每请求或热载循环调用)。返回是否发生了重载。"""
|
||||
try:
|
||||
if self.path.exists() and self.path.stat().st_mtime != self._mtime:
|
||||
self._load(force=True)
|
||||
return True
|
||||
except FileNotFoundError:
|
||||
pass
|
||||
return False
|
||||
|
||||
# ── 查询 ──
|
||||
@property
|
||||
def max_agents(self) -> int:
|
||||
with self._lock:
|
||||
return self._max_agents
|
||||
|
||||
def list(self, *, include_retired: bool = False) -> list[Agent]:
|
||||
with self._lock:
|
||||
out = [a for a in self._agents.values()
|
||||
if include_retired or a.status != "retired"]
|
||||
out.sort(key=lambda a: (a.status == "retired", a.created_at or "", a.slug))
|
||||
return out
|
||||
|
||||
def get(self, slug: str) -> Agent | None:
|
||||
with self._lock:
|
||||
return self._agents.get(slug)
|
||||
|
||||
def active_count(self) -> int:
|
||||
with self._lock:
|
||||
return sum(1 for a in self._agents.values() if a.status != "retired")
|
||||
|
||||
def slug_conflicts(self, slug: str, *, model_ids: list[str] | None = None,
|
||||
alias_names: list[str] | None = None,
|
||||
profile_ids: list[str] | None = None) -> str | None:
|
||||
"""返回冲突说明;无冲突返回 None。
|
||||
|
||||
三重查重(计划 Step 1):不能撞已有智能体 slug、模型 id、别名、QwenPaw profile id ——
|
||||
因为智能体以后可能以 `agent/<slug>` 形式暴露给客户端,撞名会混。
|
||||
"""
|
||||
if slug in self._agents:
|
||||
return f"slug「{slug}」已被占用"
|
||||
if model_ids and slug in model_ids:
|
||||
return f"slug「{slug}」与模型 id 冲突"
|
||||
if alias_names and slug in alias_names:
|
||||
return f"slug「{slug}」与虚拟模型别名冲突"
|
||||
if profile_ids and slug in profile_ids:
|
||||
return f"slug「{slug}」与 QwenPaw 智能体 profile 冲突"
|
||||
return None
|
||||
|
||||
# ── 写 ──
|
||||
def _dump(self) -> str:
|
||||
"""渲染成 YAML 文本(顶层 max_agents + agents 段)。"""
|
||||
body: dict[str, Any] = {"max_agents": self._max_agents, "agents": {}}
|
||||
for slug in sorted(self._agents):
|
||||
a = self._agents[slug]
|
||||
body["agents"][slug] = {
|
||||
"display_name": a.display_name,
|
||||
"description": a.description,
|
||||
"params": dict(a.params),
|
||||
"engine": {
|
||||
"type": a.engine_type,
|
||||
"base_url": a.engine_base_url,
|
||||
"agent_id": a.engine_agent_id,
|
||||
},
|
||||
"access": {"roles": list(a.access_roles), "users": list(a.access_users)},
|
||||
"status": a.status,
|
||||
"created_at": a.created_at,
|
||||
"updated_at": a.updated_at,
|
||||
}
|
||||
head = (
|
||||
"# 智能体定义(第三十八轮 · 路线 A:界面在网关,引擎是 QwenPaw)\n"
|
||||
"#\n"
|
||||
"# 说明:\n"
|
||||
"# · 所有智能体共用 QwenPaw 的同一个 profile(engine.agent_id),\n"
|
||||
"# 也共用同一个模型 —— 模型是 profile 级设置(请求级指定无效,已实测)。\n"
|
||||
"# · 提示词主档归 QwenPaw 管(改 SOUL.md / AGENTS.md);\n"
|
||||
"# 这里的 params.system_suffix 只是一小条角色补充。\n"
|
||||
"# · 本文件不含秘密,可入版本库。\n"
|
||||
"# · 归档(status: retired)不计入 max_agents 上限。\n"
|
||||
)
|
||||
return head + yaml.safe_dump(body, allow_unicode=True, sort_keys=False, width=100)
|
||||
|
||||
def _write(self, text: str) -> None:
|
||||
"""原子写 + 备份(逐字节替换,权限 600)。"""
|
||||
p = self.path
|
||||
p.parent.mkdir(parents=True, exist_ok=True)
|
||||
if p.exists():
|
||||
try:
|
||||
import shutil
|
||||
shutil.copy2(p, p.with_name(p.name + ".bak"))
|
||||
except OSError:
|
||||
pass
|
||||
tmp = p.with_name(p.name + f".tmp{os.getpid()}")
|
||||
tmp.write_text(text, encoding="utf-8")
|
||||
os.chmod(tmp, 0o600)
|
||||
os.replace(tmp, p)
|
||||
self._mtime = p.stat().st_mtime
|
||||
|
||||
def _commit(self) -> None:
|
||||
self._write(self._dump())
|
||||
|
||||
def create(self, *, slug: str, display_name: str, description: str = "",
|
||||
params: dict[str, Any] | None = None,
|
||||
access_roles: list[str] | None = None,
|
||||
access_users: list[str] | None = None,
|
||||
engine_base_url: str | None = None,
|
||||
engine_agent_id: str | None = None,
|
||||
status: str = "published",
|
||||
model_ids: list[str] | None = None,
|
||||
alias_names: list[str] | None = None,
|
||||
profile_ids: list[str] | None = None) -> Agent:
|
||||
with self._lock:
|
||||
self._load() # 先取最新盘上状态
|
||||
validate_slug(slug)
|
||||
conflict = self.slug_conflicts(
|
||||
slug, model_ids=model_ids, alias_names=alias_names, profile_ids=profile_ids
|
||||
)
|
||||
if conflict:
|
||||
raise AgentsError(conflict)
|
||||
if self.active_count() >= self._max_agents:
|
||||
raise AgentsError(
|
||||
f"智能体数量已达上限({self._max_agents} 个)——请先归档不用的再新建"
|
||||
)
|
||||
a = _parse_agent(slug, {
|
||||
"display_name": display_name,
|
||||
"description": description,
|
||||
"params": params or {},
|
||||
"engine": {
|
||||
"type": "qwenpaw",
|
||||
"base_url": engine_base_url or DEFAULT_ENGINE_URL,
|
||||
"agent_id": engine_agent_id or DEFAULT_ENGINE_AGENT,
|
||||
},
|
||||
"access": {"roles": access_roles or ["admin"], "users": access_users or []},
|
||||
"status": status,
|
||||
"created_at": _now(),
|
||||
"updated_at": _now(),
|
||||
})
|
||||
self._agents[slug] = a
|
||||
self._commit()
|
||||
return a
|
||||
|
||||
#: 允许通过 update 改的字段(其余字段一期只读,见计划)
|
||||
UPDATABLE = frozenset({"display_name", "description", "params", "status"})
|
||||
|
||||
def update(self, slug: str, patch: dict[str, Any]) -> Agent:
|
||||
with self._lock:
|
||||
self._load()
|
||||
a = self._agents.get(slug)
|
||||
if a is None:
|
||||
raise AgentsError(f"智能体「{slug}」不存在")
|
||||
unknown = set(patch) - self.UPDATABLE
|
||||
if unknown:
|
||||
raise AgentsError(
|
||||
f"字段不可改:{', '.join(sorted(unknown))}"
|
||||
f"(一期可改:{', '.join(sorted(self.UPDATABLE))})"
|
||||
)
|
||||
# 逐项覆盖到"可被 _parse_agent 接受的形状"(不含 slug —— 它是键不是字段)
|
||||
merged: dict[str, Any] = {
|
||||
"display_name": patch.get("display_name", a.display_name),
|
||||
"description": patch.get("description", a.description),
|
||||
"params": patch.get("params", dict(a.params)),
|
||||
"engine": {
|
||||
"type": a.engine_type,
|
||||
"base_url": a.engine_base_url,
|
||||
"agent_id": a.engine_agent_id,
|
||||
},
|
||||
"access": {"roles": list(a.access_roles), "users": list(a.access_users)},
|
||||
"status": patch.get("status", a.status),
|
||||
"created_at": a.created_at,
|
||||
"updated_at": _now(),
|
||||
}
|
||||
new = _parse_agent(slug, merged)
|
||||
self._agents[slug] = new
|
||||
self._commit()
|
||||
return new
|
||||
|
||||
def retire(self, slug: str) -> Agent:
|
||||
"""归档(不物理删 —— 项目惯例:归档优于删除)。"""
|
||||
with self._lock:
|
||||
self._load()
|
||||
a = self._agents.get(slug)
|
||||
if a is None:
|
||||
raise AgentsError(f"智能体「{slug}」不存在")
|
||||
a.status = "retired"
|
||||
a.updated_at = _now()
|
||||
self._commit()
|
||||
return a
|
||||
|
||||
def restore(self, slug: str) -> Agent:
|
||||
"""从归档恢复(决策 ⑰)。"""
|
||||
with self._lock:
|
||||
self._load()
|
||||
a = self._agents.get(slug)
|
||||
if a is None:
|
||||
raise AgentsError(f"智能体「{slug}」不存在")
|
||||
if a.status != "retired":
|
||||
raise AgentsError(f"智能体「{slug}」未归档,无需恢复")
|
||||
if self.active_count() >= self._max_agents:
|
||||
raise AgentsError(f"智能体数量已达上限({self._max_agents}),无法恢复")
|
||||
a.status = "published"
|
||||
a.updated_at = _now()
|
||||
self._commit()
|
||||
return a
|
||||
|
||||
|
||||
#: 进程级单例(延迟到首次用时构造,方便测试换路径)
|
||||
_store: AgentStore | None = None
|
||||
_store_lock = threading.Lock()
|
||||
|
||||
|
||||
def get_store() -> AgentStore:
|
||||
global _store
|
||||
with _store_lock:
|
||||
if _store is None:
|
||||
_store = AgentStore(os.environ.get("GATEWAY_AGENTS_PATH"))
|
||||
return _store
|
||||
|
||||
|
||||
def set_store(store: AgentStore | None) -> None:
|
||||
"""测试用:替换/重置单例。"""
|
||||
global _store
|
||||
with _store_lock:
|
||||
_store = store
|
||||
@@ -0,0 +1,406 @@
|
||||
"""智能体路由 + 运行记录(第三十八轮 · 路线 A)。
|
||||
|
||||
设计见 `docs/agents-dev-plan.md`;SSE 协议见 `docs/qwenpaw-agent-api-sse.md`。
|
||||
|
||||
**为什么单开一个文件**:`main.py` 已经 3800+ 行。智能体是一块相对独立的特性,
|
||||
把端点实现放这里、由 `main.py` 装配(`install(app, deps)`),比继续往 main 里塞更清楚。
|
||||
|
||||
会话列表**复用** `/history/{kind}`(`kind = agent_<slug>`),见 `app/history.py`。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import threading
|
||||
import time
|
||||
from pathlib import Path
|
||||
from typing import Any, Callable, Awaitable
|
||||
|
||||
import httpx
|
||||
from fastapi import Depends, FastAPI, HTTPException, Request
|
||||
from fastapi.responses import StreamingResponse
|
||||
|
||||
from app.agents import (
|
||||
DEFAULT_ENGINE_AGENT,
|
||||
DEFAULT_ENGINE_URL,
|
||||
Agent,
|
||||
AgentStore,
|
||||
AgentsError,
|
||||
)
|
||||
from app.adapters.qwenpaw_engine import check_engine, stream_chat
|
||||
|
||||
log = logging.getLogger("api-gateway.agents")
|
||||
|
||||
QWENPAW_CONFIG = Path("/root/.qwenpaw/config.json")
|
||||
|
||||
|
||||
# ── 运行记录(data/agent_runs.json)────────────────────────────────────
|
||||
class AgentRuns:
|
||||
"""每轮对话一条记录 + 每智能体的汇总位。
|
||||
|
||||
结构:`{"<slug>": {"last_used_at": str, "total": int, "items": [...]}}`
|
||||
条目:`{at, account, rounds, tools, tokens, ms, status}`(新→旧)
|
||||
|
||||
写入失败只告警 —— 记录不该影响对话本身。
|
||||
"""
|
||||
|
||||
MAX_ITEMS = 200
|
||||
|
||||
def __init__(self, path: str | Path | None = None) -> None:
|
||||
self.path = Path(path) if path else \
|
||||
Path(__file__).resolve().parent.parent / "data" / "agent_runs.json"
|
||||
self._lock = threading.Lock()
|
||||
|
||||
def _read(self) -> dict:
|
||||
try:
|
||||
if self.path.exists():
|
||||
data = json.loads(self.path.read_text(encoding="utf-8"))
|
||||
return data if isinstance(data, dict) else {}
|
||||
except Exception: # noqa: BLE001
|
||||
log.warning("读 agent_runs.json 失败,按空处理")
|
||||
return {}
|
||||
|
||||
def _write(self, data: dict) -> None:
|
||||
try:
|
||||
tmp = self.path.with_name(self.path.name + f".tmp{os.getpid()}")
|
||||
tmp.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
|
||||
os.chmod(tmp, 0o600)
|
||||
os.replace(tmp, self.path)
|
||||
except Exception: # noqa: BLE001
|
||||
log.warning("写 agent_runs.json 失败(忽略)")
|
||||
|
||||
def load(self) -> dict:
|
||||
with self._lock:
|
||||
return self._read()
|
||||
|
||||
def record(self, slug: str, *, account: str, rounds: int, tools: int,
|
||||
tokens: int, ms: int, status: str) -> None:
|
||||
with self._lock:
|
||||
data = self._read()
|
||||
bucket = data.setdefault(slug, {"last_used_at": "", "total": 0, "items": []})
|
||||
bucket["last_used_at"] = time.strftime("%Y-%m-%d %H:%M:%S")
|
||||
bucket["total"] = int(bucket.get("total") or 0) + 1
|
||||
items = bucket.setdefault("items", [])
|
||||
items.insert(0, {
|
||||
"at": time.strftime("%Y-%m-%d %H:%M:%S"),
|
||||
"account": account, "rounds": rounds, "tools": tools,
|
||||
"tokens": tokens, "ms": ms, "status": status,
|
||||
})
|
||||
del items[self.MAX_ITEMS:]
|
||||
self._write(data)
|
||||
|
||||
|
||||
#: 模块级单例(main.py 装配时复用)
|
||||
agent_runs = AgentRuns()
|
||||
|
||||
#: 引擎实况缓存:{model, ready, checked_at}。列表页顺带刷新,避免每请求都打引擎。
|
||||
engine_live: dict[str, Any] = {"model": "", "ready": False, "checked_at": 0.0}
|
||||
ENGINE_LIVE_TTL = 20.0 # 秒;这段时间内不重复探
|
||||
|
||||
|
||||
# ── 小工具 ────────────────────────────────────────────────────────────
|
||||
def _qwenpaw_profile_ids() -> list[str]:
|
||||
"""QwenPaw 的 profile 清单(slug 不能与它们撞)。读不到就返回空(降级不阻塞)。"""
|
||||
try:
|
||||
if QWENPAW_CONFIG.exists():
|
||||
d = json.loads(QWENPAW_CONFIG.read_text(encoding="utf-8"))
|
||||
return list(((d.get("agents") or {}).get("profiles") or {}).keys())
|
||||
except Exception: # noqa: BLE001
|
||||
log.debug("读 QwenPaw profile 清单失败(slug 查重降级)")
|
||||
return []
|
||||
|
||||
|
||||
def _sse(obj: dict) -> str:
|
||||
return "data: " + json.dumps(obj, ensure_ascii=False) + "\n\n"
|
||||
|
||||
|
||||
async def refresh_engine_live(store: AgentStore, *, force: bool = False) -> None:
|
||||
"""刷新"引擎当前模型 + 是否就绪"(带 TTL,避免每请求都打引擎)。"""
|
||||
now = time.time()
|
||||
if not force and (now - float(engine_live.get("checked_at") or 0)) < ENGINE_LIVE_TTL:
|
||||
return
|
||||
agents = store.list()
|
||||
base = agents[0].engine_base_url if agents else DEFAULT_ENGINE_URL
|
||||
agent_id = agents[0].engine_agent_id if agents else DEFAULT_ENGINE_AGENT
|
||||
ok, _why = await check_engine(base)
|
||||
model = ""
|
||||
if ok:
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=8.0) as c:
|
||||
r = await c.get(
|
||||
base.rstrip("/") + "/api/providers/active",
|
||||
params={"scope": "agent", "agent_id": agent_id},
|
||||
headers={"X-Agent-Id": agent_id},
|
||||
)
|
||||
if r.status_code < 400:
|
||||
slot = (r.json() or {}).get("active_llm") or {}
|
||||
model = slot.get("model") or ""
|
||||
except Exception: # noqa: BLE001
|
||||
log.debug("读引擎 active_model 失败")
|
||||
engine_live.update({"model": model, "ready": ok, "checked_at": now})
|
||||
|
||||
|
||||
def can_use_agent(a: Agent, role: str) -> bool:
|
||||
"""能否看/用这个智能体 —— 细粒度判定的**唯一入口**(二期下发靠它)。"""
|
||||
if role == "admin":
|
||||
return True
|
||||
if "admin" in a.access_roles and not a.access_users:
|
||||
return False # 标了"仅管理员"的,member 不可见
|
||||
return role in a.access_roles
|
||||
|
||||
|
||||
def install(app: FastAPI, *, store: AgentStore,
|
||||
require_auth: Callable[..., Any],
|
||||
require_admin: Callable[[Request], str],
|
||||
json_body: Callable[[Request], Awaitable[dict]],
|
||||
model_index: Callable[[], tuple[list[str], list[str]]],
|
||||
history_get: Callable[[str, str], list[dict]],
|
||||
) -> None:
|
||||
"""把智能体端点挂到 app 上(依赖由 main.py 注入,避免循环 import)。"""
|
||||
|
||||
def _agent_or_404(slug: str) -> Agent:
|
||||
store.reload_if_changed()
|
||||
a = store.get(slug)
|
||||
if a is None or a.status == "retired":
|
||||
raise HTTPException(404, f"智能体「{slug}」不存在")
|
||||
return a
|
||||
|
||||
def _view(a: Agent) -> dict:
|
||||
d = a.public_dict()
|
||||
bucket = agent_runs.load().get(a.slug) or {}
|
||||
d["last_used_at"] = bucket.get("last_used_at") or ""
|
||||
d["run_total"] = int(bucket.get("total") or 0)
|
||||
d["session_count"] = 0 # 按需再算(避免列表页为每个智能体读一次 history)
|
||||
d["engine_model"] = engine_live.get("model", "")
|
||||
d["engine_ready"] = bool(engine_live.get("ready"))
|
||||
return d
|
||||
|
||||
# ── 列表 ──
|
||||
@app.get("/agents")
|
||||
async def agents_list(request: Request, include_retired: bool = False,
|
||||
_auth=Depends(require_auth)):
|
||||
store.reload_if_changed()
|
||||
role = request.state.role
|
||||
if role == "admin":
|
||||
await refresh_engine_live(store)
|
||||
items = [_view(a) for a in store.list(include_retired=include_retired)]
|
||||
else:
|
||||
# member 只见 4 个字段(决策 ⑦)
|
||||
items = [{"slug": a.slug, "display_name": a.display_name,
|
||||
"description": a.description, "status": a.status}
|
||||
for a in store.list(include_retired=include_retired)
|
||||
if can_use_agent(a, role)]
|
||||
agents = store.list()
|
||||
return {
|
||||
"agents": items,
|
||||
"max_agents": store.max_agents,
|
||||
"active": store.active_count(),
|
||||
"engine": {
|
||||
"model": engine_live.get("model", ""),
|
||||
"ready": bool(engine_live.get("ready")),
|
||||
"base_url": agents[0].engine_base_url if agents else DEFAULT_ENGINE_URL,
|
||||
"agent_id": agents[0].engine_agent_id if agents else DEFAULT_ENGINE_AGENT,
|
||||
},
|
||||
}
|
||||
|
||||
# ── 新建 / 修改 / 归档 / 恢复 ──
|
||||
@app.post("/agents")
|
||||
async def agents_create(request: Request, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
body = await json_body(request)
|
||||
ids, aliases = model_index()
|
||||
try:
|
||||
a = store.create(
|
||||
slug=body.get("slug", ""),
|
||||
display_name=body.get("display_name", ""),
|
||||
description=body.get("description", ""),
|
||||
params=body.get("params") or {},
|
||||
model_ids=ids, alias_names=aliases, profile_ids=_qwenpaw_profile_ids(),
|
||||
)
|
||||
except AgentsError as e:
|
||||
raise HTTPException(400, str(e))
|
||||
return {"status": "ok", "agent": _view(a)}
|
||||
|
||||
@app.put("/agents/{slug}")
|
||||
async def agents_update(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
body = await json_body(request)
|
||||
try:
|
||||
a = store.update(slug, body)
|
||||
except AgentsError as e:
|
||||
raise HTTPException(400, str(e))
|
||||
return {"status": "ok", "agent": _view(a)}
|
||||
|
||||
@app.delete("/agents/{slug}")
|
||||
async def agents_retire(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
try:
|
||||
a = store.retire(slug)
|
||||
except AgentsError as e:
|
||||
raise HTTPException(400, str(e))
|
||||
return {"status": "ok", "retired": True, "slug": a.slug}
|
||||
|
||||
@app.post("/agents/{slug}/restore")
|
||||
async def agents_restore(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
try:
|
||||
a = store.restore(slug)
|
||||
except AgentsError as e:
|
||||
raise HTTPException(400, str(e))
|
||||
return {"status": "ok", "agent": _view(a)}
|
||||
|
||||
# ── 运行记录 ──
|
||||
@app.get("/agents/{slug}/runs")
|
||||
async def agents_runs(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
_agent_or_404(slug)
|
||||
bucket = agent_runs.load().get(slug) or {}
|
||||
return {
|
||||
"slug": slug,
|
||||
"total": int(bucket.get("total") or 0),
|
||||
"last_used_at": bucket.get("last_used_at") or "",
|
||||
"items": bucket.get("items") or [],
|
||||
}
|
||||
|
||||
# ── 会话列表(复用 history 存储;agent_<slug>)──
|
||||
@app.get("/agents/{slug}/sessions")
|
||||
async def agents_sessions(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
a = _agent_or_404(slug)
|
||||
if not can_use_agent(a, request.state.role):
|
||||
raise HTTPException(403, "无权使用该智能体")
|
||||
try:
|
||||
items = history_get(request.state.account, f"agent_{slug}")
|
||||
except Exception as e: # noqa: BLE001
|
||||
raise HTTPException(400, str(e))
|
||||
return {"slug": slug, "kind": f"agent_{slug}", "items": items}
|
||||
|
||||
# ── 试跑(配置页那颗按钮)──
|
||||
@app.post("/agents/{slug}/test")
|
||||
async def agents_test(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
a = _agent_or_404(slug)
|
||||
started = time.time()
|
||||
ok, detail, done = True, "", False
|
||||
try:
|
||||
async for msg in stream_chat(
|
||||
a.engine_base_url, a.engine_agent_id,
|
||||
[{"role": "user", "content": "回复:ok"}],
|
||||
f"selftest-{a.slug}-{int(started)}",
|
||||
system_suffix="只回复 ok,不要任何多余内容。",
|
||||
timeout=90.0,
|
||||
):
|
||||
if msg.get("type") == "error":
|
||||
ok, detail = False, str(msg.get("message"))[:200]
|
||||
break
|
||||
if msg.get("type") == "done":
|
||||
done = True
|
||||
except Exception as exc: # noqa: BLE001
|
||||
ok, detail = False, str(exc)[:200]
|
||||
if ok and not done:
|
||||
ok, detail = False, "引擎无响应"
|
||||
return {"ok": ok, "ms": int((time.time() - started) * 1000), "detail": detail}
|
||||
|
||||
# ── 停止 ──
|
||||
@app.post("/agents/{slug}/stop")
|
||||
async def agents_stop(request: Request, slug: str, chat_id: str = "",
|
||||
_auth=Depends(require_auth)):
|
||||
require_admin(request)
|
||||
a = _agent_or_404(slug)
|
||||
if not chat_id:
|
||||
raise HTTPException(400, "缺少 chat_id")
|
||||
url = a.engine_base_url.rstrip("/") + "/api/console/chat/stop"
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=15.0) as c:
|
||||
r = await c.post(url, params={"chat_id": chat_id},
|
||||
headers={"X-Agent-Id": a.engine_agent_id})
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise HTTPException(502, f"停止失败:{exc}")
|
||||
return {"status": "ok", "engine_http": r.status_code}
|
||||
|
||||
# ── 对话(SSE)──
|
||||
@app.post("/agents/{slug}/chat")
|
||||
async def agents_chat(request: Request, slug: str, _auth=Depends(require_auth)):
|
||||
a = _agent_or_404(slug)
|
||||
if not can_use_agent(a, request.state.role):
|
||||
raise HTTPException(403, "无权使用该智能体")
|
||||
body = await json_body(request)
|
||||
messages = body.get("messages")
|
||||
if not isinstance(messages, list) or not messages:
|
||||
raise HTTPException(400, "messages 不能为空")
|
||||
session_id = str(body.get("session_id") or "").strip() \
|
||||
or f"agent-{slug}-{int(time.time())}"
|
||||
account = request.state.account
|
||||
|
||||
# 防自指:引擎的模型不能指向 agent/*(否则引擎→智能体→引擎 死循环)
|
||||
await refresh_engine_live(store)
|
||||
model_now = str(engine_live.get("model") or "")
|
||||
if model_now == "agent" or model_now.startswith("agent/"):
|
||||
raise HTTPException(
|
||||
400, "引擎当前模型指向了智能体自身(agent/*),会造成死循环,已拒绝"
|
||||
)
|
||||
|
||||
p = a.params or {}
|
||||
suffix = str(p.get("system_suffix") or "")
|
||||
# 第四十轮(计量打标):让日志能一眼看出"这次调用是网关的智能体发出的",
|
||||
# 与管理员在「对话」页直接聊区分开。明细(谁/哪个智能体/多少 token)落 agent_runs。
|
||||
log.info("agent chat: slug=%s account=%s session=%s rounds=%d",
|
||||
slug, account, session_id, rounds)
|
||||
started = time.time()
|
||||
rounds = len([m for m in messages if isinstance(m, dict) and m.get("role") == "user"])
|
||||
tool_count = 0
|
||||
total_tokens = 0
|
||||
status = "ok"
|
||||
|
||||
async def event_stream():
|
||||
nonlocal tool_count, total_tokens, status
|
||||
yield _sse({"type": "start", "slug": slug, "session_id": session_id})
|
||||
try:
|
||||
async for msg in stream_chat(
|
||||
a.engine_base_url, a.engine_agent_id, messages, session_id,
|
||||
system_suffix=suffix,
|
||||
):
|
||||
t = msg.get("type")
|
||||
if t == "step" and msg.get("status") == "done":
|
||||
tool_count += 1
|
||||
if t == "usage":
|
||||
total_tokens += int(msg.get("prompt") or 0) \
|
||||
+ int(msg.get("completion") or 0)
|
||||
if t == "error":
|
||||
status = "error"
|
||||
yield _sse(msg)
|
||||
finally:
|
||||
agent_runs.record(
|
||||
slug, account=account, rounds=rounds, tools=tool_count,
|
||||
tokens=total_tokens, ms=int((time.time() - started) * 1000),
|
||||
status=status,
|
||||
)
|
||||
|
||||
return StreamingResponse(
|
||||
event_stream(), media_type="text/event-stream",
|
||||
headers={"Cache-Control": "no-cache", "Connection": "keep-alive",
|
||||
"X-Accel-Buffering": "no"},
|
||||
)
|
||||
|
||||
# ── 身份 + 功能开关(灰度通道;前端唯一权威)──
|
||||
@app.get("/auth/me")
|
||||
async def auth_me(request: Request, _auth=Depends(require_auth)):
|
||||
store.reload_if_changed()
|
||||
role = request.state.role
|
||||
visible = [a.slug for a in store.list() if can_use_agent(a, role)]
|
||||
return {
|
||||
"account": request.state.account,
|
||||
"role": role,
|
||||
"features": {
|
||||
"agents": {
|
||||
"enabled": bool(visible),
|
||||
"can_manage": role == "admin",
|
||||
"visible": visible,
|
||||
},
|
||||
},
|
||||
"engine": {
|
||||
"model": engine_live.get("model", ""),
|
||||
"ready": bool(engine_live.get("ready")),
|
||||
},
|
||||
}
|
||||
+18
-3
@@ -25,9 +25,16 @@ from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import threading
|
||||
|
||||
KINDS = ("chat", "images", "videos")
|
||||
|
||||
# 第三十八轮:智能体会话复用本模块,类别形如 `agent_<slug>`(见 docs/agents-dev-plan.md ㉑)。
|
||||
# 理由:会话列表要的"新建 / 切换 / 重命名 / 删除 / 按账号隔离 / 容量裁剪"这里全都有,
|
||||
# 新开一套端点纯属重复。slug 形态已在 AgentStore 校验过(小写字母数字连字符)。
|
||||
AGENT_KIND_PREFIX = "agent_"
|
||||
_AGENT_KIND_RE = re.compile(r"^agent_[a-z][a-z0-9-]{1,31}$")
|
||||
# 各类别的容量按"内容天然体量"分开定:对话一条就是一整段多轮消息(正文可能很长),
|
||||
# 图像一条只有 URL + prompt,视频一条带一段上游 raw 回执 —— 一刀切会把对话正文截坏。
|
||||
LIMITS: dict[str, dict[str, int]] = {
|
||||
@@ -42,6 +49,9 @@ MAX_FILE_BYTES = 4 * 1024 * 1024 # 整份 history.json 的软上限
|
||||
|
||||
|
||||
def _lim(kind: str) -> dict[str, int]:
|
||||
# 智能体会话与普通对话体量相同(一整段多轮消息)→ 沿用 chat 的容量
|
||||
if kind.startswith(AGENT_KIND_PREFIX):
|
||||
return LIMITS["chat"]
|
||||
return LIMITS.get(kind, {"items": MAX_ITEMS, "item_bytes": MAX_ITEM_BYTES,
|
||||
"field_chars": MAX_FIELD_CHARS})
|
||||
|
||||
@@ -130,9 +140,14 @@ class HistoryStore:
|
||||
# ── 读写 ───────────────────────────────
|
||||
@staticmethod
|
||||
def _check_kind(kind: str) -> str:
|
||||
if kind not in KINDS:
|
||||
raise HistoryError(f"未知历史类别 {kind!r},可选:{'/'.join(KINDS)}")
|
||||
return kind
|
||||
if kind in KINDS:
|
||||
return kind
|
||||
# 智能体会话:agent_<slug>(第三十八轮)
|
||||
if _AGENT_KIND_RE.match(kind):
|
||||
return kind
|
||||
raise HistoryError(
|
||||
f"未知历史类别 {kind!r},可选:{'/'.join(KINDS)}、或 agent_<智能体 slug>"
|
||||
)
|
||||
|
||||
def get(self, account: str, kind: str) -> list[dict]:
|
||||
self._check_kind(kind)
|
||||
|
||||
+30
-2
@@ -57,6 +57,8 @@ from app.history import HistoryStore, HistoryError, MAX_ITEMS as HISTORY_CAP
|
||||
from app.feedback import FeedbackStore, FeedbackError, MAX_ENTRIES as FEEDBACK_CAP
|
||||
from app.video_owners import VideoOwnerStore
|
||||
from app import settings as gw_settings
|
||||
from app.agents import AgentStore, AgentsError
|
||||
from app import agents_routes
|
||||
|
||||
# 功能 8: 读取 .env(若存在),补充 token 等环境变量。
|
||||
# 项目根 .env:不覆盖真实 env(override=False);
|
||||
@@ -85,6 +87,8 @@ else:
|
||||
CONFIG_PATH = _PROJECT_ROOT / "data" / "gateway.yaml"
|
||||
|
||||
config: GatewayConfig = load_config(CONFIG_PATH)
|
||||
# 智能体(第三十八轮):定义存 data/agents.yaml(可入库),会话复用 history
|
||||
_agents_store = AgentStore(os.environ.get("GATEWAY_AGENTS_PATH"))
|
||||
_metrics = Metrics(enabled=config.server.metrics_enabled)
|
||||
_access = AccessLog(maxlen=config.observability.access_log_maxlen)
|
||||
_limiter = RateLimiter()
|
||||
@@ -332,9 +336,9 @@ _docs_on = config.server.docs_enabled # 安全默认关(report: /docs、/ope
|
||||
|
||||
# 本轮修复: 版本号收敛到单一常量。此前 "2.4.0" 硬编码在 FastAPI / / 导航 / /auth/login
|
||||
# 三处,/health 干脆没返回版本 —— 前端「网关版本」一直显示 v-。
|
||||
# 2026-09-29: 2.4.0 → 2.4.1(前端间距规范统一:页面四周等距 + 卡片间距走令牌)。
|
||||
# 2026-09-29: 2.4.0 → 2.4.1(前端间距规范统一);2.4.1 → 2.5.0(新增「智能体」功能模块)。
|
||||
# ★ 版本号纪律:每次改动都要往上加,小改动加小版本号、大改动加大版本号(README 有专章)。
|
||||
VERSION = "2.4.1"
|
||||
VERSION = "2.5.0"
|
||||
|
||||
app = FastAPI(
|
||||
title="API Gateway",
|
||||
@@ -3211,6 +3215,30 @@ def _require_admin(request: Request) -> str:
|
||||
return account
|
||||
|
||||
|
||||
# ── 智能体端点装配(第三十八轮)───────────────────────────────────────
|
||||
def _model_ids_and_aliases() -> tuple[list[str], list[str]]:
|
||||
"""模型 id 与别名清单(供智能体 slug 查重)。"""
|
||||
cfg = _cfg()
|
||||
ids: list[str] = []
|
||||
for p in (cfg.providers or {}).values():
|
||||
for m in (p.models or []):
|
||||
ids.append(m.id)
|
||||
return ids, list((cfg.aliases or {}).keys())
|
||||
|
||||
|
||||
# 注意:_require_admin / _json_object 定义在本文件更靠后的位置 —— 用 lambda 延迟解析,
|
||||
# 避免"install 时名字还不存在"。安装只发生在 import 期,但调用发生在请求期,安全。
|
||||
agents_routes.install(
|
||||
app,
|
||||
store=_agents_store,
|
||||
require_auth=require_auth,
|
||||
require_admin=lambda req: _require_admin(req),
|
||||
json_body=lambda req: _json_object(req),
|
||||
model_index=_model_ids_and_aliases,
|
||||
history_get=lambda account, kind: _history.get(account, kind),
|
||||
)
|
||||
|
||||
|
||||
@app.get("/auth/users")
|
||||
async def auth_list_users(request: Request, _auth=Depends(require_auth)):
|
||||
_require_admin(request)
|
||||
|
||||
Reference in new issue
Block a user