参考架构 (Reference Architecture) — Helios Assist
本文是 decision-workbook.md 参考答案的图化总装：三张图（数据面 / 控制面 / 退款流程时序）+ 逐层职责 + 失败路径 + 降级路径。它建立在模块 10 §10.6 的通用参考架构之上，把 Capstone 的 15 个决策落到具体组件。口径与模块 01–12 一致；易变事实标注「截至 2026-08-30」。
1. 数据面（Data Plane）——一次请求的完整路径
🎯 学习重点：按请求顺序解释认证、分诊、检索、编排、工具、审批、审计和响应。
flowchart TB
subgraph Users["用户层"]
U1[终端用户客户<br/>Web/App 聊天 · 峰值 200 会话/分]
U2[内部坐席/工程师<br/>工作台 · 20 会话/分]
end
subgraph Gateway["Application / API Gateway（D14）"]
GW[OIDC 认证 · 限流(token bucket) · 请求校验<br/>入口注入筛查(D09) · PII 出口脱敏]
end
subgraph Routing["分诊层 Routing（D06/D01）"]
RT[意图分类器 · Haiku 4.5 · 结构化输出<br/>不确定→保守走高档路径]
end
subgraph Paths["三条路径（D06）"]
L1["L1 单次调用+RAG（~60-70% 流量）<br/>Sonnet 5 · 一问一答"]
L2["L2 固定 workflow（~25-35%）<br/>提示链+程序化 gate"]
L3["L3 受控 agent（<10%）<br/>Opus 5 · 步数上限12 · 检查点"]
end
subgraph Orchestrator["Agent Orchestrator（编排层，无状态容器）"]
ORCH[会话编排 · 超时/重试预算(D13)<br/>成本路由 · 降级链驱动 · request-id 透传]
RETRIEVAL["Retrieval 检索层（D03）<br/>hybrid: embeddings+BM25 · RRF<br/>rerank Top-150→Top-20<br/>metadata pre-filter: tenant_id · valid_until"]
TOOLS["Tools 工具层（D04/D05/D07）<br/>direct API: 工单/订单(原生 tool use)<br/>服务端鉴权+参数校验+策略引擎"]
MCP["MCP Connector（D05）<br/>CRM server · 工具 allowlist<br/>描述视为不可信 · tool search 治理"]
APPROVAL["Approval Gate 审批门（D07/D08）<br/>退款>200/风险规则→人工卡片<br/>策略引擎 · 高危冻结非绕过"]
STATE["State 状态层<br/>会话存储(加密·受控) · 检查点<br/>夜间 Batches 作业(摘要/评估)"]
end
subgraph Reliability["可靠性控制面（D13）"]
CB{{熔断器 closed/open/half-open}}
DEG[降级链<br/>Sonnet→Haiku→模板+表单→人工]
ESC[Escalation Queue 升级队列]
end
subgraph Observability["可观测/审计面（D11）"]
LOGS[审计事件 append-only<br/>工具调用/审批/升级/策略依据]
METRICS[指标: deflection·升级率·成本<br/>groundedness·首字延迟·缓存命中]
TRACES[traces: request_id 贯穿]
end
subgraph Human["人工层（D08）"]
AGENT[坐席工作台<br/>结构化交接卡片: 摘要/已执行动作/证据/建议]
end
ANTHROPIC[Claude API<br/>统一出口代理: 超时/重试/熔断/usage 采集]
U1 --> GW
U2 --> GW
GW --> RT
RT --> L1 & L2 & L3
L1 & L2 & L3 --> ORCH
ORCH --> ANTHROPIC
ORCH --> RETRIEVAL
ORCH --> TOOLS
ORCH --> MCP
TOOLS --> APPROVAL
APPROVAL -- 批准 --> TOOLS
ORCH --> STATE
ORCH <--> CB
CB -. 开路:新会话进降级 .-> DEG
DEG --> ESC
ORCH -- 低置信/用户要求/预算耗尽 --> ESC
ESC --> AGENT
AGENT -- 处置回写: 采纳/改写/否决 --> STATE
GW & ORCH & APPROVAL -. 审计事件 .-> LOGS
ORCH -. usage/spans .-> TRACES --> METRICS
METRICS -. 异常告警 .-> ESC
读图五要点（与模块 10 §10.6 同骨架，Capstone 特有处加粗）：
- 用户永远不直连 Claude API：网关统一认证、限流、入口注入筛查、出口脱敏。
- 分诊在编排之前：三条路径的成本/延迟/可靠性画像完全不同（D01/D06 的经济学落点）。
- 审批门在工具层内：高危动作的「申请→审批→执行」是三段式，模型只发起第一段（D07 红线）。
- 降级链与熔断是横切组件：任何路径打穿都可走
降级 → 升级 的公共出口。
- 审计面覆盖全部决策点：工具调用、审批、升级、策略命中都是结构化事件（R9）。
2. 控制面（Control Plane）——配置、策略、评估、发布如何管理
🎯 学习重点：控制面必须让模型、prompt、阈值和工具策略可版本化、可灰度、可回滚。
flowchart LR
subgraph Sources["变更来源"]
DEV[工程/prompt/检索变更]
OPS[策略规则调整<br/>审批阈值/路由规则]
DATA[知识更新<br/>wiki 周更 / 政策季更]
end
subgraph Control["控制面"]
CONFIG[配置中心（D14）<br/>模型ID(pinned)·prompt版本·Top-K<br/>缓存断点·阈值·工具开关 — 全部版本化]
POLICY[策略引擎规则库（D07）<br/>审批触发/数据范围/风险信号]
INGEST[摄取管线（D03/D09）<br/>解析→分块→清洗(间接注入面)→<br/>上下文前缀→嵌入+BM25→元数据(tenant/valid_until)]
EVAL[评估管线（D10）<br/>golden 300+: 检索层 recall/MRR/权限<br/>端到端 groundedness/工具正确/注入拦截<br/>夜间 Batches 半价跑]
GATE{{发布门 Publish Gate<br/>groundedness≥95% · 工具≥98%<br/>注入拦截≥99% · 越权100%}}
CANARY[灰度发布（D14）<br/>1%→5%→25%→100% 稳定哈希分流<br/>指标分标签对比 · 异常自动回滚]
end
subgraph Feedback["反馈闭环"]
ONLINE[线上监控（D12/D13）<br/>deflection·升级率·每会话成本<br/>降级率·首字延迟·缓存命中]
AGENTFB[坐席回流（D08）<br/>采纳/改写/否决+原因]
REDTEAM[红队注入集<br/>+ 审批拒绝案例]
end
AUDIT[(审计存储<br/>配置版本·策略版本·发布记录)]
DEV --> CONFIG
OPS --> POLICY
DATA --> INGEST
CONFIG & POLICY & INGEST --> EVAL
EVAL --> GATE --> CANARY
CANARY -- 数据面各组件 --> CONFIG
ONLINE --> EVAL
AGENTFB --> EVAL
REDTEAM --> EVAL
CONFIG & POLICY & CANARY -. 版本留痕 .-> AUDIT
读图要点：
- 数据面的每个行为参数都由控制面版本化供给——「为什么这笔退款被批准」= 审计事件里的策略规则 ID + 当时的配置版本，可完整回放（R9）。
- 发布门是硬闸：任何影响行为的变更（模型/prompt/检索/策略）不过评估不发布；灰度期间继续分标签对比，回滚=配置回切（模块 10.5）。
- 三条反馈回路（线上指标、坐席处置、红队案例）都汇入评估管线——评估集是活资产，不是一次性测试（D10 数据飞轮）。
3. 退款请求：完整时序（含失败与升级路径）
🎯 学习重点：时序题要覆盖正常、拒绝、超时、重复调用和转人工，而不只 happy path。
sequenceDiagram
participant U as 用户
participant GW as 网关
participant RT as 路由(Haiku)
participant ORCH as 编排(Sonnet)
participant CL as Claude API
participant TL as 工具层/策略引擎
participant AG as 审批门→坐席
participant LOG as 审计
U->>GW: 「年付套餐我要退款」
GW->>GW: 认证·限流·注入筛查
GW->>RT: 分类(refund_request, conf .82)
RT->>ORCH: L2 固定 workflow
ORCH->>CL: step1 取上下文(政策块+订单)
CL-->>ORCH: tool_use: get_order(ORD-77)
ORCH->>TL: 执行(服务端以用户身份)
TL-->>ORCH: 订单 $480 年付 · 审计:GET_ORDER
ORCH->>CL: step2 tool_result→生成申请
CL-->>ORCH: tool_use: request_refund(480,"annual_cancel")
ORCH->>TL: 策略引擎: >200 → 审批门(冻结态)
TL->>LOG: REFUND_REQUESTED(policy=P12, 冻结)
TL->>AG: 审批卡片{订单/理由/政策引用/建议}
alt 坐席批准
AG->>TL: 批准(执行通道不在模型工具面)
TL->>LOG: APPROVED(坐席ID·依据)
TL-->>ORCH: 已执行 → 生成确认回复
ORCH-->>U: 退款确认 + 单号
else 坐席拒绝/要求补充
AG->>LOG: REJECTED/INFO_REQ(原因)
AG-->>U: 坐席直接接管(结构化交接)
end
Note over ORCH,CL: 失败路径: Claude 429/5xx → 预算内退避重试×2 → 熔断计数<br/>超时 → 取消走降级链(Sonnet→Haiku→模板+表单)<br/>订单API 5xx → 工具错误回传→模型改话术「已记录稍后处理」→ 仍失败则升级人工<br/>检索失败 → 无证据不回答, 直转人工(R2 优先于 R1)
这张时序图是验收测试的脚本：每一帧都应该能对应到 examples/capstone_skeleton.py 里的一个伪组件。
4. 逐层职责表
🎯 学习重点：每项职责只能有一个最终强制点，避免模型、网关和后端互相假设对方校验。
| 层 | 职责 | 不做什么（负面清单） | 主要决策 |
|---|
| 网关 | 认证/限流/校验/入口筛查/出口脱敏 | 不含业务逻辑、不调模型 | D09/D14 |
| 路由 | 意图分类（结构化输出），三路分发 | 不生成回答 | D01/D06 |
| 编排 | 会话状态机、预算、降级链、request-id | 不做权限判断（下沉策略引擎） | D06/D13 |
| Claude 客户端 | pinned ID、缓存断点、streaming、重试 | 不做业务重试逻辑（收编排预算管） | D01/D02/D12 |
| 检索层 | hybrid+rerank+pre-filter | 不做生成；不作废政策不进候选 | D03/D07 |
| 工具层 | 鉴权、参数校验、策略引擎、审计 | 不暴露执行通道给模型 | D04/D05/D07 |
| MCP Connector | CRM 工具发现/授权/熔断 | 不信任 server 描述文本 | D05 |
| 审批门 | 高危冻结、卡片、批准/拒绝 | 不自动放行（不存在「临时绕过」） | D07/D08 |
| 状态层 | 会话/检查点/队列/夜间批 | 不存明文 PII 于日志（指针引用） | D11/D12 |
| 审计面 | append-only 事件、版本留痕 | 不做分析（分析在观测面） | D11 |
| 人工层 | 审批、接管、处置回写 | 不读裸聊天记录（结构化交接） | D08 |
5. 失败路径与降级路径总表
🎯 学习重点：为每个依赖写明检测信号、自动动作、用户体验、升级条件与恢复方式。
| 故障点 | 检测 | 自动动作 | 用户感受 | 升级条件 |
|---|
| Claude 429 | 响应码+Retry-After | 预算内退避×2 | 多等几秒 | 预算耗尽→降级链 |
| Claude 5xx | 响应码 | 重试×2+熔断计数 | 略慢 | 熔断开→新会话模板+人工常显 |
| 首字超时 | 8s 计时 | 取消→降级下一级 | 「换个方式」 | 连续超时→升级 |
| 检索服务 | 健康检查/超时 | L1 直转人工（无证据不回答） | 「知识库暂不可用」 | 全量升级+值班 |
| 工具后端 5xx | 响应码 | 工具错误回传→模型换话术/工具 | 「已记录，稍后处理」 | 涉退款→人工 |
| MCP server 超时 | connector 超时 | 该 connector 熔断+功能受限提示 | 局部功能不可用 | 平台值班 |
| 审批门不可用 | 健康检查 | 高危动作排队冻结 | 「审批稍后处理」 | 积压阈值→告警 |
| 降级链全打穿 | 链末端标记 | 会话挂起入队+明确告知 | 顺畅转人工 | 按队列 SLA |
设计不变式：①无证据不回答；②高危宁可冻结不可绕过；③每次降级都是可观测事件。（与 D15 三原则一致）
6. 与通用参考架构的关系
🎯 学习重点：区分可复用平台能力与 Helios 场景特有的业务规则。
- 本图 = 模块 10 §10.6 通用骨架 + Capstone 决策实例化。通用图回答「生产级应用长什么样」，本文回答「Helios Assist 的每个框里放什么、为什么」。
- 教学边界：组件原理（缓存/熔断/hybrid 检索/…）分别在模块 03/07/10 讲透，本文只引用不重讲。
- 速查版（一页浓缩全部决策规则）：仓库根目录
../ARCHITECTURE_CHEATSHEET.md。
7. 来源
🎯 学习重点：用原始来源验证产品能力与易变事实，模块交叉引用只用于导航。
本文引用的官方锚点（均于 2026-08-30 访问核验，状态见 ../sources/sources-13-capstone.csv）：
- Building Effective Agents（workflow/agent 决策阶梯、客服案例）: https://www.anthropic.com/engineering/building-effective-agents
- Models overview（四档模型与定价）: https://platform.claude.com/docs/en/models/overview
- Prompt caching（缓存倍率与断点纪律）: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- Contextual Retrieval（hybrid 检索/阈值/metadata）: https://www.anthropic.com/engineering/contextual-retrieval
- Citations（主张溯源）: https://platform.claude.com/docs/en/build-with-claude/citations
- MCP Specification（工具不可信描述/授权治理）: https://modelcontextprotocol.io/specification/2026-07-28
- Mitigate jailbreaks（分层防线定位）: https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks
- API errors（错误分类）: https://platform.claude.com/docs/en/api/errors
- 评估文档（成功标准与评估建设）: https://platform.claude.com/docs/en/test-and-evaluate/develop-tests
📚 目录