Files
xiaoyin-gateway/app/agents.py
T
api-gateway c0706d1846 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 全绿。
2026-09-29 13:22:12 +08:00

522 lines
21 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""智能体(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