张胜宇
9675df8453
- 分支内容对齐 qyqy_develop b6ec3aa，树完全一致（同步后 git diff 为空） - 覆盖本轮全部交付：客服 Agent 重构（安全路由 / 五出口 / 记忆与画像 / RAG 全链路） + 开发文档 62 份编号体系（D1.1 v1.17 索引） + 新增 D2.10-客服Agent端到端答辩文档-2026-09-21.html - 基线：e239eb7（2026-09-17 品牌口径统一快照），本提交为其直接后继
81 lines
3.3 KiB
Python
81 lines
3.3 KiB
Python
from typing import Any
|
||
|
||
from pydantic import BaseModel, ConfigDict, Field, field_validator
|
||
|
||
|
||
class AgentRunCreateRequest(BaseModel):
|
||
model_config = ConfigDict(extra="forbid")
|
||
|
||
agent_type: str
|
||
# 上限与前端输入框 `maxlength` = 8000 一致（`widget.js`）：前端截断只是体验，
|
||
# 真正的边界必须由服务端把关，否则绕过前端直发可把任意长度文本落库/送模型。
|
||
message: str = Field(min_length=1, max_length=8000)
|
||
# `ConversationSession.session_id` 是 `String(64)`：超长会话号在 MySQL 严格模式下
|
||
# 会在落库时才炸成 500，必须在入口用同宽约束拦成 422。
|
||
session_id: str = Field(min_length=1, max_length=64)
|
||
# 上限 64 不是随手取的：`RequestIdempotency.idempotency_key` 是 `String(64)`，
|
||
# 接口此前允许 128，65—128 字符的键会穿过校验、在插入时才炸成 500。
|
||
idempotency_key: str = Field(min_length=16, max_length=64)
|
||
|
||
@field_validator("message")
|
||
@classmethod
|
||
def message_must_not_be_blank(cls, value: str) -> str:
|
||
"""纯空白消息必须在**入口**拦掉，不能穿透到领域层。
|
||
|
||
`min_length=1` 只数字符：`" "` 长度是 3，能过入口校验；随后 `AgentRequest` 的
|
||
`message must not be blank` 会拒掉它 —— 但那抛的是**领域层**的
|
||
`pydantic.ValidationError`，不属于 FastAPI 的请求校验异常，会被兜底处理器变成
|
||
**500 Internal Server Error**（实测：`POST /api/v1/agent-runs` + `message=" "`
|
||
→ 500，而 `message` 超长 → 正常的 422 信封）。判据在入口补一份，错误形状与其余
|
||
参数错误一致（422 `AGENT_INPUT_INVALID`）。
|
||
"""
|
||
if not value.strip():
|
||
raise ValueError("message must not be blank")
|
||
return value
|
||
|
||
|
||
class AgentRunAcceptedResponse(BaseModel):
|
||
run_id: str
|
||
trace_id: str
|
||
status: str
|
||
status_url: str
|
||
events_url: str
|
||
|
||
|
||
class AgentRunAcceptedEnvelope(BaseModel):
|
||
"""`POST /api/v1/agent-runs` 的 202 响应（文档 §3.3 + §6.2）。
|
||
|
||
文档 §6.2 明确给出的是 `{data:{run_id,trace_id,status,status_url,events_url}, meta:{trace_id}}`
|
||
信封，§3.3 又规定"业务接口不得增加其他顶层字段"。此前这里返回的是平铺对象，接入方按
|
||
文档取 `data.run_id` 会拿到空值——这是接入者第一步就会踩到的契约偏差，因此补齐信封。
|
||
|
||
`data` 内的字段名与语义与改动前完全一致，客户端只是多读一层 `data`；
|
||
`meta.trace_id` 是**本次请求**的 trace，`data.trace_id` 是运行自身的 trace（两者通常相同）。
|
||
"""
|
||
|
||
data: AgentRunAcceptedResponse
|
||
meta: dict[str, str]
|
||
|
||
|
||
class AgentRunStatusResponse(BaseModel):
|
||
run_id: str
|
||
trace_id: str
|
||
status: str
|
||
agent_type: str
|
||
session_id: str
|
||
result: dict[str, Any] | None = None
|
||
error_code: str | None = None
|
||
created_at: str
|
||
completed_at: str | None = None
|
||
|
||
|
||
class AgentRunStatusEnvelope(BaseModel):
|
||
"""`GET /api/v1/agent-runs/{run_id}` 的成功响应（文档 §3.3 + §6.3）。
|
||
|
||
单资源信封只多一层 `{data, meta}`：`data` 里的字段名与语义**与改动前完全一致**，
|
||
客户端除多读一层 `data` 外不需要任何适配。
|
||
"""
|
||
|
||
data: AgentRunStatusResponse
|
||
meta: dict[str, str]
|