张胜宇
3e24033f72
设计与依据：新增 D3.9-客服Agent智能路由与行情出口设计-2026-09-21.md（CS-ARCH-2026-024）
DEC-W27-1~12 全部批准并落地。
## 新增（3 个源文件 + 3 个测试文件）
- app/core/exit_codes.py：出口码注册表（E0/E1/E2a~E2e/E3/E4/E5a~E5c/E6/E8/CHAT/LOGIN/CONTACT）
+ NON_BUSINESS_EXIT_CODES 白名单（免责分档的判据面）
- app/service/fund_trend_service.py（E6）：summarize_trend() 纯函数 + query_fund_trend 工具
读 fin_nav_history；按净值日个数（5/20/60/120）给区间涨跌 / 区间高低 / 来源与区间
- tests/unit/{service,tools} 新增 45 条守卫单测（E6 出口 / L0 表层判定 / 工具配置）
## 改动（重点）
- customer_service.py：
· _route_surface()（L0-a 闲聊 / L0-b 行情 / L0-e 无信息量），位置在安全路由之后
· drop_yield_claims() 重写为「入口闸 × 槽位白名单」+ fail-closed
（旧黑名单会误删权重：A-06 业绩基准公式整行消失）
· allowed_tools 补 query_fund_trend —— 修掉发布被拒 422「配置超出 Agent 工具上限」
（该 422 是**子集**校验而非数量上限，根因即此项漏配）
· 25 处 CoreResult 全部补 exit_code（AST 守卫保证零遗漏）
- customer_service_rules.py：闲聊判定重写（业务实体边界 + 词表 + 特征串 + 语气词）
+ is_low_information_message() + is_contact_inquiry()
- governance.py：免责声明按 exit_code 分档（业务档完整 / 非业务档轻型）
- actor.py：VISITOR_PERMISSIONS 补 fund:quote:read（E6 对访客开放，DEC-W27-11）
- tools/：seed_compliance_baseline 新增 TPL_DISCLAIMER_LIGHT；publish 工具改为
「从生效版本派生原列表再追加」（_inherit_tools 取不到返回 None，防静默改窄）
## 实测
- 金标扩容 46 → 55（新增 Q 组行情 5 条 + C 组闲聊 4 条）
- M-1 55/55、M-4 55/55；M-5 与四项零容忍（M-7/M-8/M-9/M-10）全 0
- 原 46 条可比基线逐项不变（46/46）；M-6 9.1%（5 条全在转人工白名单内）
- 全量 pytest 2094 passed / 3 skipped；ruff 零新增（余 5 条与 HEAD 逐条对应）
- 配置版本 244（cs-tools-75813de45421）已发布并激活
## 文档
- 新增 D3.9（设计专册）；D1.1 §34 补「代码实施已同轮完成」并把旧表述作废
- D3.7：新增 Q 组判据表 + §6.4 第四次实测 + M-3/M-9 口径澄清
- D2.9：新增 §2.11（9 条新增用例的实测答复原文）+ 汇总表改双列口径
- D2.1：新增 v6.41 执行条目
- 权威副本（D:\桌面\金融\）→ 仓库镜像 全量比对一致（0 缺失 / 0 不一致）
## 诚实未做项
- 知识出口（E3/E4）侧的实体锚点闸门未做（故金标扩容 9 条而非 12 条，A-11~A-13 未成集）
- 阈值未重标（D3.9 §3.4 只给方法）；M-3 分母未改（仅明示口径）；
D1.1 §0 与 §4.0 历史计数偏移（差 1）仍沿用
67 lines
3.3 KiB
Python
67 lines
3.3 KiB
Python
"""访客（匿名）主体的**唯一构造点**与统一判定谓词。
|
||
|
||
为什么需要这个模块（`G-01` / `G-01b`）：
|
||
|
||
1. **构造点有两份**。访客三元组（角色 / 权限 / 数据范围）此前在
|
||
``app/core/security.py``（API 入口）与 ``app/worker/runtime.py``（Worker 执行路径）
|
||
各手写了一份。两份只要漂移一次，就会出现「API 认得访客、Worker 不认得」这类
|
||
只在异步链路才暴露的越权面，而且**没有测试能发现**——因为它不是同一个函数。
|
||
2. **判定散落各处**。``"visitor" in context.roles`` 这个判定此前出现在 6 个文件、
|
||
13 处。口径要改（例如以后加身份轴）就得改 13 个地方，漏一处就是一个缺口。
|
||
|
||
因此：构造只走 :func:`anonymous_context`，判定只走 :func:`is_visitor`。
|
||
两者的行为都与改造前**逐字一致**——本模块是重构，不是行为变更。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from app.core.contracts import RequestContext
|
||
|
||
#: 访客角色名。与 `app/core/knowledge_tier.TIERS_BY_SUBJECT` 的键同名同源（`G-03` 落点）。
|
||
VISITOR_ROLE = "visitor"
|
||
|
||
#: 受理事件里持久化的 actor 类型取值（`conversation_session` / 审计侧）。
|
||
VISITOR_ACTOR_TYPE = "visitor"
|
||
|
||
#: 访客角色元组。**唯一副本**：`security.py` 与 `runtime.py` 都从这里取。
|
||
VISITOR_ROLES: tuple[str, ...] = (VISITOR_ROLE,)
|
||
|
||
#: 访客仅可运行 Agent 与读取**公开数据**，**不含任何个人数据权限**。
|
||
#: 追加权限码属**权限决策**，必须单独评审并留痕，不得顺手扩能。
|
||
#:
|
||
#: `2026-09-21`（`W27` / `DEC-W27-11`）评审通过并留痕的**一次**扩张：
|
||
#: `fund:quote:read` —— `E6` 行情走势出口对访客开放。依据：净值与区间涨跌是
|
||
#: **公开事实**（`fin_nav_history` 的公共数据，与公开产品列表页同一数据源），
|
||
#: 读取它不需要任何个人数据，也不放宽任何档位（`INV-1`）。
|
||
#: 反向守卫：本元组**仍不得**出现 `customer:` / `profile:` / `memory:` /
|
||
#: `handover:` / `conversation:` 前缀（`tests/unit/api/test_frontend_boundaries.py` 钉死）。
|
||
VISITOR_PERMISSIONS: tuple[str, ...] = ("agent:run", "knowledge:query", "fund:quote:read")
|
||
|
||
#: 访客数据范围恒为 `public`（与知识侧档位 `{public}` 同一收敛方向）。
|
||
VISITOR_DATA_SCOPE = "public"
|
||
|
||
|
||
def anonymous_context(*, user_id: str, trace_id: str, portal: str = "api") -> RequestContext:
|
||
"""构造访客请求上下文。**访客上下文的唯一来源。**
|
||
|
||
`user_id` 是令牌 `sub`（数字串，由 `VisitorTokenIssuer` 生成），不是正式用户主键；
|
||
`portal` 默认 `api`，Worker 侧恢复上下文时同样用默认值，保证两侧逐字相等。
|
||
"""
|
||
return RequestContext(
|
||
user_id=str(user_id),
|
||
trace_id=str(trace_id),
|
||
roles=VISITOR_ROLES,
|
||
permissions=VISITOR_PERMISSIONS,
|
||
data_scope=VISITOR_DATA_SCOPE,
|
||
portal=portal,
|
||
)
|
||
|
||
|
||
def is_visitor(context: RequestContext) -> bool:
|
||
"""访客判定。**全仓唯一谓词**——不得再写 ``"visitor" in context.roles``。
|
||
|
||
保留在基类 / 依赖注入层调用（`G-01b` 的底线：判定位置与层级不变，
|
||
只是换成一个统一函数），因此这里**不读 Agent 声明位**、也不依赖任何配置。
|
||
"""
|
||
return VISITOR_ROLE in context.roles
|