模块 13 — Capstone 项目：Helios Assist

📚 重要英语词汇：模块 13 词汇表

这是全课程的收官项目。本模块不再教新知识——它给你一个企业级场景、一套约束和验收标准，让你把模块 01–12 的能力用于做完整的设计决策。你的产出是一份「能扛住架构评审」的设计方案，而不是又一份读书笔记。先决条件：完成模块 01–12（或至少 02 / 03 / 04 / 06 / 07 / 08 / 10 / 11 / 12 的核心节）。

1. 场景（Scenario）

🎯 学习重点：先从业务目标、用户旅程与既有系统识别边界，不要一上来画模型框。

Helios Cloud（虚构公司）是一家 B2B SaaS 公司：约 2,000 家企业客户、合计约 50 万名终端用户，销售「数据管道 + 分析」产品。公司要建一套 Helios Assist——同时服务两类用户的智能助理：

用户群	入口	典型问题	体量
终端用户客户	Web/App 内嵌聊天	「怎么配置数据源重试策略？」「我的任务失败 TS-1042 怎么办？」「我要退款」	峰值 200 会话/分钟
内部坐席与工程师（约 200 人）	内部工作台	「这家客户上次工单怎么处理的？」「退款政策对年付客户怎么说？」	工作时段 20 会话/分钟

知识源（全部在 Helios 自有基础设施上）：

产品文档 wiki：约 8,000 页（Markdown，结构良好，周更）
支持政策手册：约 300 页 PDF（退款/SLA/升级政策，季度更新，旧版必须作废失效）
历史工单：120 万条，已做摘要与脱敏，需按客户隔离访问
系统数据（实时）：工单系统（内部 API）、订单/计费（内部 API）、CRM（MCP server 已由平台团队建设中）

既有系统与团队：SSO（OIDC）、审计平台（必须对接）、平台团队负责 MCP server 建设、客服团队负责人审坐席排班。测试与灰度基础设施齐备（可发 1%–25% 流量）。

2. 需求（Requirements）

🎯 学习重点：把每条需求转成可测试 SLO/门禁，并识别安全、延迟、成本与可靠性的冲突。

编号供工作簿与评分引用。

#	需求	可验收指标（草案，可在工作簿 D10 修订）
R1	常见咨询自动解决	一级咨询 deflection rate ≥ 60%（自动解决、无需坐席）
R2	有据回答	答案 groundedness ≥ 95%（每条主张可溯源到检索证据或工具结果）
R3	工具行动	能查工单/订单、创建工单、发起退款申请
R4	退款审批	金额 > $200 或规则命中风险信号 → 必须人工审批后执行
R5	升级	模型低置信 / 用户要求 / 降级链打穿 → 转人工，且坐席拿到结构化上下文
R6	延迟	首字 p50 ≤ 5s、p95 ≤ 12s（终端用户侧）
R7	成本	平均每自动解决会话成本 ≤ $0.10（API 侧，按 2026-08-30 价目）
R8	可靠性	整体可用性 99.5%；Claude API 故障时系统降级可用（受限回答 + 顺畅转人工），不得白屏
R9	审计	每次工具调用、审批、升级有不可抵赖的审计记录（谁/何时/依据/结果）
R10	知识新鲜度	政策文档更新后 ≤ 24h 生效；已作废政策不得再被引用

3. 约束（Constraints）

🎯 学习重点：约束是方案筛选器；最佳架构必须在渠道、数据、团队和预算现实内成立。

C1 数据驻留：客户 PII 不得离开 Helios 控制的边界进入任意第三方系统（含检索供应商、外部 MCP server）；进出模型 API 的 PII 须最小化并脱敏。
C2 渠道：公司使用 Anthropic 自营 API（截至 2026-08-30 现役四档模型可用：Fable 5 / Opus 5 / Sonnet 5 / Haiku 4.5，来源: https://platform.claude.com/docs/en/models/overview（访问于 2026-08-30））。
C3 不可逆操作：退款执行、账户变更、数据删除永远不允许模型直接执行——这是合规红线。
C4 组织：平台团队出 MCP server，业务团队做应用；工具需求要跨团队对齐。
C5 预算：上线首季度 API 预算 $60k（约 60 万次自动解决会话，按 R7 反推），一次性建设预算另计。
C6 评估门槛：上线前必须有 golden dataset 与回归流程（对照模块 12）；无评估不上线。
C7 坐席容量：人工坐席 concurrently 处理能力有限，设计不得把升级率推高到坐席崩溃。
C8 部署：应用部署在 Helios 的 VPC；对 Claude API 的调用要经统一出口（超时/重试/熔断集中管理）。

4. 验收标准（项目「完成」的定义）

🎯 学习重点：交付物必须给出决策理由、量化证据、失败路径和可追溯来源。

你的方案必须能回答下列验收测试（评审者会逐条问）：

画得出两张图：数据面（一次请求的完整路径）与控制面（配置/策略/评估/发布如何管理）——对照 reference-architecture.md 自查。
对 decision-workbook.md 的 15 个决策点各有明确选择 + 理由 + 放弃了什么（没有 tradeoff 记录的决策视为未完成）。
三个「为什么」：为什么这套架构安全（提示注入路径逐条有缓解）、为什么便宜（成本模型算得出每会话成本）、为什么可靠（每个组件挂了会发生什么说得清）。
评估体系：golden dataset 从哪来、评什么指标、多少分能上、回归何时触发。
对照 rubric.md 五维度自评 ≥ 合格线，并指出你最弱的一维。

5. 怎么做这个项目

🎯 学习重点：先独立决策，再用工作簿和参考架构做差异复盘，避免抄答案失去取舍训练。

① 读本页（需求/约束/验收）                       20 min
② 打开 decision-workbook.md，逐点先写自己的答案   2–4 h（别先看参考答案）
③ 读 reference-architecture.md 对照补图           1 h
④ 读 bad-vs-better.md，给你的设计「排雷」          30 min
⑤ 用 rubric.md 自评，修订最弱维度                 1 h
⑥ （可选）跑 examples/capstone_skeleton.py，      15 min
   对照伪组件实现理解编排循环/审批门/降级链

学习者交付物建议：一份 my-decisions.md（对照工作簿 15 点）+ 一张自己画的数据面图 + 一页成本模型。工作簿与参考架构是答案书，先自己做再看。

6. 文件导航

🎯 学习重点：README 定边界、workbook 记决策、architecture 画运行路径、rubric 做验收。

文件	内容
`decision-workbook.md`	15 个决策点 ×（背景/选项/填写区/参考答案/模块回链）——本项目核心
`reference-architecture.md`	完整参考架构：数据面 + 控制面 + 退款流程时序（3 张 Mermaid 图）、逐层职责、失败与降级路径
`bad-vs-better.md`	坏架构 vs 好架构全案例对照（全塞上下文 / prompt 当安全 / 无评估 vs 检索 / 应用层强制 / 评估闭环）
`rubric.md`	五维度 × 四级别评分标准
`examples/capstone_skeleton.py`	无 key 可跑的架构骨架模拟（编排循环 / 工具执行 / 人审门 / 降级）

7. 与模块 01–12 的映射（Capstone 用到什么）

🎯 学习重点：综合题要求把模型、prompt、RAG、工具、安全、评估和生产运维串成一套论证。

决策点用到	模块
模型选型、成本结构、上下文窗口、context rot	01 / 02
调用面：重试/退避、缓存、Batches、错误分类	03
工具回路、tool_choice、谁决定什么	04
提示结构、结构化输出、thinking 取舍	05
MCP vs 直接 API、工具发现治理	06
RAG 全链路、RAG vs 塞上下文、groundedness	07
workflow vs agent、编排模式、停止条件	08
（对照参考）agentic coding 工具的权限/审计实践	09
参考架构、重试/降级/熔断/升级、成本-延迟-可靠性	10
提示注入、LLM 指令 ≠ 应用层强制、最小权限工具	11
evals、golden dataset、回归、线上监控	12

速查：架构决策浓缩版见仓库根目录 ../ARCHITECTURE_CHEATSHEET.md。

7A. 架构师犀利细节：预算、边界与最坏情况

🎯 学习重点：能用需求数字反推架构，并明确哪些比例只是场景假设、哪些是硬门禁。

99.5% 可用性对应约 0.5% 不可用预算；反模式是只承诺“重试三次”，正解是按调用链分配超时/重试预算，并在 Claude、检索或工具故障时进入受限回答与转人工。
p50 ≤5s、p95 ≤12s要求同时优化典型路径和长尾；全流量开放式 agent 会把工具轮数与尾延迟放大。三路径分诊让 L1 保持单次调用、L2 固定步骤、L3 才承担多步成本。
每会话 ≤$0.10必须按完整路径算：示例 L1 约 $0.065，L2 约 $0.10–0.15，L3 约 $0.5–1.5。L3 小于 10% 只是本案例设计假设；若真实流量漂移，预算会立刻失效，必须按路径分桶告警。
1%→5%→25%→100% 灰度降低爆炸半径，但低流量档可能观察不到稀有故障；升档条件应同时满足最小样本、观察窗口与关键指标，而不只“等十分钟没报警”。
安全门禁不可平均：groundedness ≥95%、工具正确率 ≥98% 可以是质量阈值；越权拦截必须 100%，不能让高平均分抵消一次跨租户访问。
上下文边界：8,000 页 wiki + 300 页政策显著超过本模块引用的小于 200k token（约 500 页）整体塞入判断线；正解是 hybrid retrieval + rerank + metadata pre-filter，把作废或越权文档在候选阶段排除。
反模式 vs 正解：给模型 admin token 再靠 prompt 禁止退款，是把策略和能力放在同一失效域；窄工具、服务端鉴权、金额 gate、审批与 append-only 审计把决策拆到可验证边界。

8. 来源与时效

🎯 学习重点：模型、价格、限额和产品状态会变化，架构结论必须绑定核验日期。

本模块所有论断性内容在工作簿内逐条标注来源；易变事实（模型名/价格/限额/产品状态）均标注「截至 2026-08-30」。来源清单见 ../sources/sources-13-capstone.csv。

📚 目录