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:
api-gateway committed 2026-09-29 13:22:12 +08:00
1 parent bccb72bad5
commit 51c9af59c4
19 files changed
+3064 -26

No files matched your search

+320
View File
@@ -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
View File
@@ -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
+406
View File
@@ -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
View File
@@ -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
View File
@@ -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)