结果第一版开发者培训我写了 92 页 PPT，讲完现场问问题的只有两个人，三周后调研发现真正在用 Claude 的工程师不到 15%。
我当场破防了。回去重写。
我复盘了两周，想明白一件事：培训不是信息传递，是行为改变。
信息传递只需要讲清楚。行为改变需要触发、需要场景、需要反馈闭环、需要同伴压力。那 92 页 PPT 把信息传递做得很好，但对行为改变基本零贡献。
后来我把培训大纲按四类角色重新拆了：开发者、PM、运营、领导层。每类角色关心的东西不一样，学习方式也不一样。硬塞同一份材料就是浪费所有人时间。
开发者讨厌纯讲。他们要的是跟着敲、能跑起来、下班能继续玩的东西。
我后来定稿的开发者培训是 4 小时，拆成 4 节，每节 45 分钟实操 + 15 分钟答疑。
第 1 节：API 基础和模型家族。讲 messages API、token、streaming、基本 prompt 写法。重点是让每个人当场跑通第一个 API 调用。Model 家族那部分我会花 10 分钟讲 Haiku/Sonnet/Opus 的选型直觉（claude-family-haiku-sonnet-opus 讲过具体对比）。
第 2 节：工具使用和 Claude Code。tool use、function calling、sub-agent。让每个人写一个调用 3 个工具的小 agent（查天气 + 计算 + 发 Slack）。Claude Code 基础用法，包括权限沙盒（claude-code-permissions-sandbox 讲过）。
第 3 节：MCP 和 Skill。这一节最干货。讲 MCP 怎么接、Skill 怎么组织。让每个人基于公司内部的一个真实工具写一个 MCP server。Skill 那块推 skill-team-knowledge-base 的做法。
第 4 节：Agent 模式和成本管理。长流程 agent 怎么搭、prompt 缓存怎么用、账单怎么看（cost-bill-anatomy 我直接链给他们）。
四节课下来每个人都带走三样东西：一个能跑的 agent demo、一个对接公司工具的 MCP server、一份个人 API key 的 30 天使用配额。
一个细节：我不做视频。开发者培训必须是直播或现场，因为一定会出各种报错，需要现场 debug。录完的视频后面新员工看可以，但首轮培训必须面对面。
PM 的痛点不是技术，是判断力。他们需要在产品设计阶段就知道”这个功能适合让 AI 做吗”、”成本大概多少”、”风险在哪”。
我给 PM 的 2 小时分两段：
第 1 小时：场景识别能力。给 12 个产品场景让他们分类：哪些适合 Claude 独立完成、哪些适合 AI 辅助人工、哪些根本不该用 AI。带着讨论每个场景的约束条件：成本敏感度、错误容忍度、合规要求、用户信任度。
第 2 小时：成本直觉和边界。token 是什么、1,000 token 大概多少字、一次对话多少钱、缓存能省多少。让 PM 做一个小计算：假设产品上线 10 万日活，每个用户每天 3 次对话，每次 1,500 token，月账单大概多少。这个练习做完 PM 对成本的直觉能上一个台阶。
PM 这一档最大的坑是：千万别让他们写 prompt。有些公司要求 PM 学 prompt engineering，结果 PM 花时间调 prompt，工程师的时间没省，反而多了一个扯皮环节。让 PM 识别场景就够了，细节交给工程师。
运营人数最多，但培训时长最短。原因是他们不需要懂技术，只需要知道规则。
这 1 小时核心就三件事：
使用规范。哪些内容可以粘进 Claude、哪些不行。明确的 allowlist 和 denylist。客户个人信息、合同原文、财务数据、员工信息都在 denylist 里。
风险识别。幻觉是什么、怎么识别、遇到要怎么处理。给 5 个真实案例让大家练眼力。
求助渠道。遇到不确定的内容要找谁、怎么上报、响应时间多少。这个流程图必须贴到每个人的工位或者内部 wiki 首页。
运营培训不要讲 API、不要讲 prompt engineering、不要讲模型对比。讲了他们也记不住，还会产生”AI 很复杂我用不好”的心理阴影。
领导最忙，也最容易被销售忽悠。他们需要的是”5 分钟能跟董事会讲清楚”的东西。
我给领导层的 30 分钟：
前 10 分钟讲 ROI。拿本公司的真实数字（从 POC 阶段的数据推算），说清楚”投入 X、产出 Y、回本周期 Z”。别用行业平均数据，自己的数据最有说服力。
中间 10 分钟讲风险。合规风险、成本失控风险、依赖单一供应商风险、员工技能断层风险。每个风险配一个已经部署的缓解措施。
最后 10 分钟讲决策场景。未来 12 个月领导可能会遇到的 5 个决策点（扩大预算、增加岗位、调整供应商、应对监管、处理事故），每个点事先给出决策框架。
领导层培训的最大坑是”讲太技术”。他们不关心 MCP 是什么，关心的是”我们公司有没有用好这个东西”。我有一次给 CFO 讲 prompt 缓存，讲了 10 分钟人家直接打断我：”你告诉我能省多少钱就行。” 那次之后我彻底改了讲法。
上面四套培训背后要有一个三层教材体系：
入门文档：1-2 页的 quick start。”如何登录”、”基本规则”、”求助渠道”。给所有人。
Skill 库：沉淀下来的可复用 prompt 和 Skill。按场景分类。skill-team-knowledge-base 里讲的那套做法最实用。
案例库：内部真实案例。某某部门用 Claude 解决了什么问题、怎么做的、效果多少。案例库是最能打的教材，比任何官方文档都有说服力，因为”这是我隔壁工位的同事干的”。
案例库要定期更新。我建议每两周收一次投稿，选出 2-3 个做成标准格式放进库里。这个事 HR 或者组织发展岗可以牵头，不需要技术团队做。
培训效果不看”满意度”、不看”参训率”。看培训后 30 天的实际采纳率。
我给所有客户定的指标都是同一个：”培训后 30 天内，本批学员每周至少使用 Claude 一次的比例”。
那家车企开发者组的数字：首轮培训 142 人，30 天后 119 人每周至少用一次，采纳率 83.8%。PM 组采纳率 61.2%，运营组 44.7%，领导层我们没测。
这个数字怎么来的？从 API 网关的日志里拉。每个人的 API key 都能追到人，直接查使用频率。这也是铁律 1 要做 key 分级的原因之一。
采纳率低于 50% 说明培训失败。低于 50% 一般有三个原因：场景没匹配上（教的东西他们工作里用不上）、工具不好用（API 网关太卡或者权限卡得太死）、同伴压力不够（身边人都不用）。
一轮培训搞完不是结束，是开始。持续运营靠三件事：
月度分享会。每月一次，45 分钟，两个部门轮流分享”本月我们用 Claude 干了什么”。要求讲具体案例、具体数字、具体踩坑。这个会不录播，为了让大家敢讲真话。
内部 champions 计划。每个部门选 1-2 个骨干当 champion，给他们额外的 API 额度、新功能 beta 优先体验权、季度一次外部会议参加机会（比如去听 Anthropic 的 dev day）。换取他们承担本部门第一响应支持、月度分享会讲一次、新人培训带练。
季度竞赛。每季度一个主题，比如”用 Skill 做的最酷的工作流”、”一年省钱最多的 prompt 优化”。奖品不用大，一块定制礼品或者一天带薪休假就够。竞赛的作用不是奖品，是强迫大家动脑子。
那家车企运营满一年以后，champions 计划扩到了 38 人，每月分享会的旁听人数稳定在 200+，季度竞赛一季度能收到 70+ 投稿。这是培训体系真正跑起来的样子。
“员工用 Claude 写代码，出了 bug 谁负责？” 规则明确：代码作者负责。Claude 是工具，工具不承担责任。这条要在培训首节就讲清楚，否则后面扯皮没完。
“用 Claude 生成的内容版权归谁？” 商业 API 的 output 版权归使用方（签了企业条款）。claude.ai 的 output 版权条款相对复杂。用企业 API 走 Bedrock/Vertex 最清晰。
“培训多久更新一次？” 我建议季度。Claude 每季度至少一次重要更新，培训材料要跟上。成本结构、新功能、新工具、新安全要求都得讲。
“不参加培训不给用 Claude 行不行？” 我的建议是：参加基础培训（1 小时合规篇）是硬门槛，进阶培训自愿。不逼着所有人学技术，但合规底线必须守住。
最后交付那份 43 页报告，CISO 看完给我发微信，就一句话：”这比我想象的还糟。”
那家公司之后三个月把治理体系重搭了一遍。我根据在他们那儿以及后来两家的经验，整出这 8 条铁律。不是网上抄的 best practice，是我亲眼见过违反之后出事儿的教训。
原则：organization > workspace > project > user 四级隔离。
反面教材：我审的第一家公司，全公司 200 多个调 Claude 的服务，共用 2 个 API key。其中一个 key 是当年做 POC 时申请的，权限范围宽得能从长城外看到长城内。key 的 owner 那个哥们儿去年 10 月离职了，这个 key 还在到处跑。
修复方案：
离职流程里加一条：”回收所有名下 API key”。这事儿要 HR 系统跟 Anthropic console 对接，或者至少有个 checklist。
原则：每个 key 必须有硬上限，告警分 50% / 80% / 100% 三级。
反面教材：第二家公司一个测试项目的 key，因为代码里的死循环，一夜从平均 $12 /天涨到 $2,847.12 /天。第二天早上发现的时候已经烧了 4 天。
修复方案：
这个机制实施以后，那家公司一个季度里拦下了 3 次类似的失控。自动暂停这条要跟 FinOps 团队吵一架才能定下来，因为业务方会担心误停。但我的经验是，误停 10 分钟可以解释，烧 $5 万没法解释。
原则：谁、在什么时间、用了什么 prompt、得到了什么输出，必须可查，保留至少 90 天。
反面教材：第三家公司被客户投诉某份文档里有错误信息，客户要求追查。他们去翻日志——没有。用的是直连 API 通过几个 Python 脚本调的，脚本里就打了”request success”这么一行。
修复方案：
审计日志至少记 8 个字段：时间戳、用户 ID、项目标签、model、输入 token 数、输出 token 数、prompt hash、完整 prompt 和 completion 的加密存储路径。
存储上用分级：30 天内热存储（随便查）、30-90 天温存储（需要工单）、90 天以上冷存储或删除（看行业合规要求，金融医疗可能要 7 年）。
查询接口要有权限控制。不是所有人都能翻别人的 prompt。审计员能翻全量，tech lead 能翻自己团队的，开发者只能翻自己的。
这个在 agent-sdk-production-deploy 里我讲过一部分生产部署时的日志架构。
原则：PII、PHI、PCI、商业机密，进 prompt 之前必须扫描 + 脱敏。
反面教材：第一家公司的客服系统，客服直接复制客户对话粘进 Claude 里让它帮忙写回复。客户对话里有身份证号、银行卡号、住址。这些全部原样传出去了。我发现这个问题的时候，直接让他们当天下架了那个功能。
修复方案：
在 prompt 组装的 gateway 层，用一个 PII 扫描器（presidio、aws comprehend 或自研正则库）过一遍。识别到的字段替换成占位符（[NAME_1]、[PHONE_1] 这种），Claude 返回之后再还原。
扫描器要覆盖：身份证、手机、邮箱、银行卡、地址、社保号、护照号、员工工号、客户 ID、合同编号。医疗场景再加病历号、诊断编码。
扫描不是完美的，会有 false negative。所以要配合铁律 5。
原则：Claude 的输出按敏感度分三档，分别对应不同的 review 流程。
反面教材在第二家公司：他们的法律合同生成工具，output 直接流到了合同签署环节，中间没有律师 review。某次 Claude 生成的条款漏写了一个违约责任条款，差点签出去。
修复上不难，关键是把”这个输出到底什么用”标清楚。我的建议是在 prompt 模板里就打 tag，response 里带着 tag，下游系统根据 tag 决定 review 路径。
原则：任何通过 AI 生成、即将发给客户/供应商/监管的内容，必须有 diff review。
反面教材：第三家公司一个市场营销邮件，Claude 生成后 PM 改了两处，发出去之前没人看最终版本。结果那封邮件里有一段 Claude 硬塞的”优惠活动详情”——是幻觉，公司根本没有这个活动。发给了 8,400 个客户。法务加班改了两天善后。
修复方案：
外发内容过一道 review 工作流，UI 上并排显示”AI 生成版 / 人工修改版 / 最终发送版”。Review 人必须签字确认。对了，签字要跟 HR 系统联动，不能”review 人：AI 助手”这种事儿出现（真有公司干过）。
自动化一点的做法：加一个 filter 层，检测 AI 输出里可能的幻觉点（比如具体的金额、日期、人名），强制要求人工逐项确认。
原则：Claude 版本升级、API 行为变化、价格调整、条款更新，必须有对内的通告和评估流程。
反面教材：Anthropic 去年某次调整了 content filter 的默认阈值，第一家公司有个内容审核应用直接误杀率涨了一倍，用户投诉。技术团队花了两天才定位到是外部变化。
修复方案：
订阅 Anthropic 的 changelog、Bedrock/Vertex 的 release note。每周 tech lead 级别碰头 15 分钟，过一遍有没有影响的变更。重要变更在内部发通告，给业务方时间准备。
另外搞一个”黄金集”回归测试：准备 200-500 条真实业务 prompt，每次 Claude 或基础设施有变动时跑一遍，看输出有没有显著飘移。这个思路跟 skill-testing-versioning 一个路子。
原则：每季度至少一次红队演练，包含 prompt injection、jailbreak、data leak 测试。
反面教材：第二家公司的 customer support agent 上线半年没做过任何安全测试。我去的时候随便试了三个 prompt injection，全过了，能让它输出系统 prompt、能让它调用不该调的工具、能让它泄露其他客户的对话片段。
修复方案：
季度红队要覆盖这几类：
测试用例库可以参考开源的 promptfoo、garak。红队执行最好请独立团队，不能自己测自己。
关于 MCP 相关的注入风险，mcp-security-best-practice 有详细的分析。
第一家公司治理审计前一个月，发生过一件事儿。
新入职的一位销售小哥，签了一份大客户的合同，上面明写了”乙方承诺不会将甲方的任何业务数据、合同内容用于第三方 AI 服务训练或推理”。
小哥不知道。他为了写一份跟这个客户的提案，把合同原文粘进 Claude 里让它帮忙”理解客户痛点”。当时用的是消费端 claude.ai，不是企业 API。
一周后客户的法务在走访过程中，要求检查乙方的合规体系。合规负责人翻 AI 使用记录，差点冒了一身冷汗。
幸好那家公司已经部署了 DLP（数据防泄漏）系统，出口侧拦截了合同文件的上传日志，能够证明 claude.ai 那边没成功传上去，只是个失败尝试。客户最后没追究，但签了一份补充协议，这家公司花了三个月做了整套治理升级。
这个事件后来变成他们所有新员工入职培训的第一个案例。我问那位 CISO 学到了什么，他说：”规则要写给普通人能看懂，不能写给安全工程师看。”
如果你是内审或外审，拿这 20 条扫一遍基本能过：
20 条能答对 16 条以上，算及格。
他问我：”你帮我看看，到底哪几步是真的要做的？”
我跟他说：”你把我原来那份拿出来，就 6 个月，1 页纸。别搞花的。”
这篇写的就是那份 1 页纸后面的故事。后来他们 800 人的研发部门，从我接手到全员启用，用了整整 6 个月零 11 天。
别上来就搞”集团 AI 战略规划委员会”。先挑 2 个人。
这 2 个人的画像很重要：一个是资深工程师，技术判断力强，在团队里有话语权，平时就爱折腾新东西。另一个是 PM 或 tech lead，会讲故事、会跟不同团队沟通、写 wiki 不嫌烦。
前两个月这俩人只做一件事：跑 3 个小 POC。我当时给他们定的三个是 code review、API 文档生成、客服工单 draft。选这三个不是随便选的，挑的都是”高频、低风险、能直接量化时间节省”的场景。code review 那个我在 industry-code-review-bot 写过完整代码。
这阶段最重要的产出是数字。不是”大家反馈不错”，是”第一周 Alice 的 code review 时间从平均 47 分钟降到 18 分钟”这种。没数字后面一切都白搭。
踩坑提醒：POC 别做超过 6 周。超过 6 周你就在骗自己。两个月做三个 POC，每个两周左右就得出结论。某银行做了 9 个月 POC 还在”完善方案”，最后整个项目没了，原因就是这个。
第三个月的核心动作是把前两个月的数字讲出去。
我当时给那个种子组的建议是：做一个 20 分钟的内部分享会，面向中层技术经理，核心就讲三件事：
数字要真实。我看过太多的 PPT 写”效率提升 40%”，底下一问怎么算的，说不清。那种 PPT 反而减分。我让他们写的版本是：”3 个开发者连续 6 周使用，code review 时间中位数从 47.2 分钟降到 18.6 分钟，减少 60.6%。样本小、非对照，数字有待更大范围验证。”
诚实是最有说服力的。中层经理不是傻子，你诚实他们会买账。
这个阶段同时要找一个 executive sponsor。就是一个 VP 级别的人，愿意在预算会议上为你说话的人。没有这个人后面推不动。我们那个车企的 sponsor 是研发总监，他当时看到那份数字之后问了一个问题：”800 人如果都能省这么多，一年省多少？” 后面的预算就是这句话打下来的。
第四个月放到 10 个人。这 10 个人怎么挑？我给的标准是：
保守派那三个特别重要。他们提的问题往往是后面规模化时会爆炸的问题。我们那个车企的一位老架构师就在 beta 期间提出：”如果 Claude 建议的代码改动引入了 bug，责任怎么算？”这个问题后来变成了团队的”AI 建议追溯规范”。
beta 期要收集两份东西：吐槽清单和痛点清单。吐槽是”今天 Haiku 又把我的变量名改烂了”这种，痛点是”我们代码规范里的这条，Claude 不知道”这种。吐槽听了笑笑就行，痛点要立刻变成工程 backlog。
这个阶段我建议已经开始搭内部工具链了。参考 skill-team-knowledge-base 那篇，Skill 库这时候就得开始积累。
第五个月是最重的。要做四件事：
统一 API 网关。所有业务方不直连 API，都走公司内部网关。网关负责鉴权、限流、预算检查、审计日志。这玩意儿不做，后面成本和治理都是一锅粥。我们那个车企用了 LiteLLM 魔改，加了一层自研的预算控制中间件。
账单平摊机制。每个事业部、每个项目一个 cost center。月底账单自动按 project 标签切分，推送到各部门财务。我当时写了一个小看板，每个 team lead 都能看到自家团队本月花了多少。这个看板上线第一周，研发部门的 AI 花费直接降了 18%，因为大家开始知道自己在花钱了。cost-bill-anatomy 里讲过怎么拆账单。
Skill 和 MCP 治理。团队成员写的 Skill 进一个内部 registry，有 review 流程。重要的 Skill 要做 skill-testing-versioning 里讲的版本化测试。MCP server 的权限严格按 claude-code-permissions-sandbox 的方法隔离，别给过宽权限。
应急预案。API 宕机了怎么办？超预算了怎么办？prompt 泄露了怎么办？这三个预案写出来，在 Confluence 或者飞书上挂着，每次值班轮换都看一遍。
这个月工作量很大，建议至少配 3 个工程师全职投入 4 周。
最后一个月是推广月。关键是培训要分角色。
开发者：4 节 45 分钟的录播视频（API 基础 / 工具使用 / MCP 接入 / Agent 模式）+ 1 场现场 workshop。workshop 上我建议做一个”真实代码挑战”，用 Claude 在 30 分钟内完成一个小任务，让人亲眼看到效果。
PM 和产品：2 小时专场，重点讲”什么场景适合 Claude、什么场景不适合、成本是怎么计算的”。别让 PM 动不动要求技术”给我接个 AI”，他们得自己有判断。
运营、客服：1 小时，重点是使用规范和风险。比如”客户个人信息不能直接粘进 prompt”、”AI 的回复要人工 review 之后再发”这种硬规则。
领导层：30 分钟就够。不讲技术，讲 ROI、风险点、未来 12 个月路线图。领导要的是决策依据，不是 API 文档。
培训完了要配套一个东西：champions 计划。每个部门选 1-2 个骨干，给他们稍微多一点权限（比如更高的 API 额度、新功能 beta 优先），换取他们承担”本部门第一响应人”的职责。新员工来了有人问、同事卡住了有人帮。这个机制省下了至少 80% 的中心化支持工作量。
前面提过那家银行。他们的失败不是技术问题，是组织问题。
具体哪几步出了错：
他们现在还在做 POC。从 2024 年 5 月到现在，快两年了。
对比之下我们那个车企 800 人的部门，6 个月铺开以后第 7 个月的度量：研发部门 72.8% 的工程师每周至少使用 Claude 3 次以上，code review 平均时长下降 43.1%，PR merge 周期中位数从 4.2 天缩到 2.6 天。这是真金白银的数字。
第一，别让 AI 团队自己铺开。AI 团队负责技术栈和工具链，铺开这事儿得业务线自己扛 owner。不然就变成”AI 团队推、业务线接不住”。
第二，allowance 比禁令管用。与其禁用某些场景，不如给大家明确的 allowlist：”这些场景放心用”。人类在规则不清晰的时候会过度保守。
第三，第一批宣布的成果要是真的。别为了发新闻稿夸大效果。夸大一次，半年内招不回信任。
第四，培训视频录完马上过时。Claude 更新太快了。我们那个车企的视频录完 3 个月，Opus 4.7 出来，Haiku 4.5 出来，Skill 模型改了，整套视频得重录。所以建议录的时候就做好季度更新的预期。
关于具体场景的落地细节，可以看 industry-legal-contract-review、industry-customer-support-agent、industry-bi-natural-language-query 这三篇。
我当时的回答是：”得看你走哪条路。”
然后我们就这一条路、那一条路讲了整整三小时。我后来意识到，很多技术团队在跟合规部门对接的时候，根本答不上来这个问题。不是他们不专业，是 Claude 的部署方式真的不止一种，每一种的数据流向完全不同。
直接 Anthropic API。这是最便宜、最新模型上线最快的一条路。Opus 4.7 发布那天，API 上就有了，Bedrock 和 Vertex 都要再等 2-4 周。但数据流向上，你的 prompt 和 completion 会传到 Anthropic 的服务器（目前主要在美国），Anthropic 的 commercial terms 明确说企业 API 数据不用于训练，保留 30 天用于滥用检测后删除。对大部分美国、欧洲客户够用。对中国客户、金融客户、医疗客户基本走不通。
AWS Bedrock。数据流向上，你的 prompt 和 completion 只在你选的 AWS region 内处理，不出 region，不回传 Anthropic 用于任何用途。合规资质一堆：HIPAA、SOC2 Type II、ISO 27001、PCI DSS、GDPR、FedRAMP Moderate 都有。对企业客户最友好的一条。代价是 token 单价比直连贵 8-15%，新模型上线会晚 2-4 周，有时候某些区域（比如东京）还没有最新的 Opus。
Google Vertex AI。跟 Bedrock 类似的企业合规套餐。优势在对接 GCP 生态（BigQuery、Dataflow、Looker），数据留在你的 GCP tenant 内。合规资质基本对齐 Bedrock。国内客户用得少，主要是 GCP 本身在大陆没法直接用。
这三条路选哪条，我一般问客户四个问题：数据能不能出大陆？合规评审走不走 SOC2？你主要在哪个云？成本敏感度多高？四个答案能直接把选项筛到一条。
国内客户 90% 的情况走不通直连 API，原因不是技术，是数据出境的合规口子太窄。从 2023 年数据安全法到 2024 年的跨境传输规则，一份包含个人信息的 prompt 传出大陆，理论上要做安全评估或者签标准合同，实操里没人真这么做，但出了事儿兜不住。
所以国内客户的实操路径一般三种：
第一种是 Bedrock 新加坡或东京 region + 数据前置脱敏。PII、PHI、PCI 这些敏感字段在 prompt 组装阶段就脱敏成占位符，回来之后再还原。脱敏逻辑写在一个独立的微服务里，审计日志全量保留。城商行那个客户就是这条路。
第二种是用阿里云百炼、火山引擎等国内”类 Claude”服务。说实话，模型能力上跟 Claude 原厂还是有差距，尤其是 agent 类任务。但纯文本生成、简单 QA 这种场景够用。风险点是：这些服务底层模型会迭代，某天突然换底模，你的效果可能掉一个大坎，事先不会通知你。
第三种是私有化部署开源模型 + 少量复杂任务走海外。这是混合架构，工程复杂度最高。但对医疗、军工这种数据一丁点都不能出的客户，只能走这条。我帮医院那家做的就是这套，数据路由决策树写了 200 多行。
顺便说一句，国内几个”代理直连 Claude”的服务，合规上不要碰。那些 API 的数据流向是完全不可控的，出了事儿你没法跟监管交代。我见过一家公司的安全官看到业务部门在用这种服务，当天就发邮件通报批评。
给合规部门和法务看的，不是技术文档，是这四份东西：
DPA（数据处理协议）。Anthropic、AWS、Google 都有模板，直连 API 签 Anthropic 的，走云则签云厂商的。关键看几条：数据处理目的、留存期限、子处理方清单、跨境传输条款、删除机制。法务会逐条红线标记。
SOC2 Type II 报告。Anthropic 的 SOC2 II 需要 NDA 才给，找你的客户经理或者 Trust Center 要。AWS 和 Google 的直接能下。合规部门会翻到控制测试那一章，看有没有 exception。
模型训练数据声明。这个很关键。商业 API（包括 Bedrock/Vertex 部署）的 prompt 不用于训练，这条要白纸黑字。消费端 claude.ai 是另一套规则。别把两个混在一起跟合规讲。
子处理方列表。Anthropic 用了哪些第三方（AWS/GCP/Cloudflare 等），对应的数据是什么。Anthropic 的 subprocessor list 在官网可查。
这四份凑齐，合规评审大概率能一轮过。我城商行那个客户评审一共走了三轮，最后一轮就是把这四份补齐。
关于 MCP 和工具链这边的安全要求我在 mcp-security-best-practice 讲过，治理细节在 enterprise-governance-audit-log。
那个 2,300 家门店的零售客户，业务覆盖 14 个国家。欧洲门店的客服数据归 GDPR 管，新加坡门店归 PDPA 管，美国归 CCPA，国内归个保法。他们一开始想”一套 API 打全球”，合规部门第一周就否了。
最后的架构我给描述一下：
中心有一个叫 AI Gateway 的服务（自研 + LiteLLM 魔改），所有业务方调模型都走这个网关。网关拿到请求以后做三件事：识别用户所在区域、按区域路由到对应 provider、记录审计日志。
欧洲流量走 Bedrock eu-central-1（法兰克福）；新加坡/东南亚走 Bedrock ap-southeast-1；美国走 Bedrock us-east-1；中国大陆走脱敏后 Bedrock ap-northeast-1。不同区域的 API key 隔离，预算隔离，审计日志分库存。
账单这边每个 region 的 cost center 独立结算。总部 IT 不再替区域业务付 AI 账单，每个国家的运营预算自己扛。这个改动政治上比技术上复杂，推了 6 周。
多云路由这块可以看 cost-multi-model-router 那篇，跟这个架构一脉相承。
他们做这个架构的时候漏了一个东西：日志本身的跨境问题。
一开始他们把所有 region 的审计日志统一推到总部一个 S3 bucket（在美东）。欧洲合规同事审出来一份 GDPR 问题报告，因为审计日志里包含了欧洲用户的 prompt 内容，推到美东本身就是跨境传输。
改完之后的架构是：每个 region 的审计日志留在本 region，中心只同步脱敏后的 metadata（token 数、延迟、模型、状态码这些）用于可观测性。真需要看原始日志，得登到对应 region 的控制台。
这个问题我后来在很多客户那儿都见过。日志是盲点。大家都盯着业务数据的跨境，忘了日志本身也是数据。
真要选路的话，我的决策树一般是这样：
别听供应商销售忽悠。他们只想卖给你他们家的。你手里要有一张自己算过的账。
两年前我还比较自信，觉得写 prompt 这事儿我摸得差不多了。直到一个周五晚上，跟同事吃饭时他随口问我：”你们 prompt 里的文档是按什么顺序排的？”
我说按相关度降序啊，最相关的放最前面，这不是常识吗？
他笑了笑说他们团队最近发现——把最相关的放最后，准确率反而高。
我第二天一早就跑去跑实验。我当时就懵了：同样 20 段 context 喂给 Claude Sonnet，只是换个顺序，问答准确率从 71.3% 跳到了 84.8%。
那一刻我才意识到，过去写过的所有 prompt，可能都没把位置这件事当一回事。
LLM 对 context 不同位置的敏感度是不均匀的。大致有三个效应：
Primacy effect（首因效应）：开头的内容 attention 权重高。这是因为 transformer 的 positional encoding 让模型对起始位置格外敏感，加上训练时大量 prompt 都把指令放开头。
Recency effect（近因效应）：结尾的内容 attention 权重也高，而且对”生成下一个 token”影响最直接——因为下一个 token 就是紧接着结尾生成的。
Lost in the middle（中间塌陷）：夹在中间的内容 attention 最弱。越长的 context，中间段的”存在感”越低。Stanford 和一些其他团队的研究都验证了这个效应，long context 模型也没能完全消除。
对 Claude 这种 200K 窗口的模型，middle 的塌陷更明显——因为 middle 的绝对长度太长了。
这是个老问题，我见过三种流派：
流派 A：全部放 system role 里。 Anthropic 官方推荐的做法。
流派 B：关键指令重复出现在 user role 的结尾。 有些团队的做法，为了对抗长上下文遗忘。
流派 C：混合——system 放角色和风格，user 结尾放具体任务指令。 我现在用这个。
我实测过几组。场景是法律问答，100 个 case：
数据很清楚。关于系统指令的详细用法可以看 system role 位置与写法。
但这里有个坑：user 结尾重复指令会消耗 prompt cache 命中率——因为 user 消息每次都变。一个折中做法是：system 里写全量指令 + 角色，user 里只在结尾放”请以 XX 格式输出”这种输出格式约束。这样既利用了 recency，又不破坏缓存。
给 Claude 喂多个检索到的文档，顺序怎么排？业内有三种主流观点：
观点 1：相关度降序（最相关放最前）
理由：primacy effect，模型最先读到最重要的。很多 RAG 框架默认这么做。
观点 2：相关度升序（最相关放最后）
理由：recency effect 比 primacy 更强，尤其对生成式任务——模型要生成答案时，最近读到的内容权重最高。
观点 3：U 型布局（最相关放两头，不相关放中间）
理由：避开 lost in the middle 的塌陷区。
我跑过一组对照实验，20 段 context 做 QA，100 个 case：
升序赢得最干净。U 型略差于升序，可能是因为”双重重点”分散了 attention。
但注意：这是我在 Claude Sonnet 4.5 上的结果，不同模型会有差异。我建议任何严肃项目都自己跑一次对比，一小时的事，受益一年。
细说一下那次实验的配置。
场景：企业内部的政策咨询 bot。文档库是公司规章制度，chunk 粒度是条款级别，大概 3 万条。
query 类型：”员工出差标准””年假怎么折算””加班费计算”之类。
原始 pipeline：embedding 召回 top-20，按相似度降序拼接成 context。
问题：好几个 bad case 里，正确答案其实在 top-10 但被 Claude “忽略”了——生成的答案里引用的是 top-3 的某个相近但不精确的条款。
重排方案：
结果：F1 从 0.71 → 0.85，其中 bad case 减少 71%。
这个”倒置”操作就一行代码，但带来的提升比我调了半周 prompt 换来的还多。有时候工程上的杠杆在最小的细节里。
法则一：最重要的指令写两遍。
system role 里写一遍（完整版），user 消息的结尾再重申一遍关键约束（简版）。注意简版要短，避免破坏缓存命中率。
法则二：证据按”模型最后看到的才是最重要的”来排。
不管你是从 embedding 出来的，还是 rerank 之后的，最终往 context 里拼的时候，最相关的那条放最后。反直觉但有效。
法则三：给每段内容加锚点标签。
不要让模型在一片扁平的文本里”大海捞针”。用 XML 标签把每段框起来：
1 | <context> |
这种结构对 Claude 特别友好（XML 在 Claude 上的表现），实测能让 lost-in-the-middle 的影响减弱 30% 以上。因为标签给了模型明确的”地标”，它找信息时有锚可抓。
细节 1：对话历史和检索文档混在一起的时候，要分开标签。我见过把历史对话和 RAG 文档用一个 <context> 包起来的，模型分不清哪些是用户说过的、哪些是文档里写的。
细节 2：当前用户 query 永远放最后。这是 recency effect 最直接的应用。不要在 query 后面再拼什么”请用中文回答”这种约束——把这类约束挪到 system 或者放在 query 前面。
细节 3：如果用了 CoT（chain of thought vs direct），思考过程会出现在 assistant role 里，这部分也受 recency 影响——它生成的最后几句话对最终答案影响最大。所以 CoT 的结构设计也要考虑位置。
细节 4：Claude 对 “Human:” “Assistant:” 这种轮次标记的敏感度比大多数团队想象的高。多轮对话如果历史摘要和真实对话混在一起，轮次标记乱了会让模型”精神分裂”。
Context engineering 这两年变成一个专门的方向，不是没理由的。LLM 不是一个黑盒输入输出机器——它是一个对”你怎么组织信息”极其敏感的系统。
同样的事实，不同顺序，不同结构，不同标签，输出的答案质量能差出一个量级。这个事实如果你做了十个项目还没体感，那你可能根本没在认真调 prompt。
位置这件事，说破了就是三个效应：首因、近因、中间塌陷。但真正把它用顺的团队，比你想象的少。希望这篇能让你少走点我当年的弯路。
延伸阅读
想系统掌握 prompt 构造，[从 Prompt 到 Context Engineering](/posts/prompt-to-context-engineering/) 是地基。结构化标签一定要看 [XML 标签在 Claude 上的妙用](/posts/prompt-xml-tags-claude-special/)。系统指令放哪、怎么放，[system role 写法](/posts/prompt-system-role-placement/) 讲得很细。做 API 的朋友最好再复习下 [Claude API 快速入门](/posts/claude-api-quickstart/)，里面有 messages 结构的最佳实践。
这篇是把我自己踩过的坑和客户现场见过的部署方式整理成一份清单。不保证面面俱到，但至少少走弯路。
别用单阶段，node:20 基础镜像加依赖动辄 1.2GB。我的模板大概是这样：
1 | FROM node:20-alpine AS builder |
几个点：alpine 小巧但要装 git（agent 经常要用），tini 做 PID 1 保证信号正确转发（否则 SIGTERM 传不到 node 进程），.claude/ 目录里的 agent 定义和 hook 配置要一起打进镜像。
最后镜像大小大概 340MB，对比单阶段小了一大截。
这条应该不用说，但我真见过有人把 ANTHROPIC_API_KEY 直接写 Dockerfile 里。
生产用 Secret Manager（k8s Secret、AWS Secrets Manager、Vault 都行）。pod 启动时注入环境变量，或者挂载成文件。我偏向后者，轮转 key 时不用重启 pod。
Agent SDK 实际在意的环境变量不少，我整理了一份：
| 变量 | 作用 | 我的生产值 |
|---|---|---|
ANTHROPIC_API_KEY | API 密钥 | secret 注入 |
ANTHROPIC_MODEL | 默认模型 | claude-sonnet-4-7 |
CLAUDE_AGENT_SESSION_DIR | session 目录 | /data/sessions |
CLAUDE_AGENT_CONFIG_DIR | agent 配置目录 | /app/.claude |
HTTP_PROXY / HTTPS_PROXY | 出站代理 | 按环境 |
NO_PROXY | 代理白名单 | localhost,127.0.0.1,10.0.0.0/8 |
OTEL_EXPORTER_OTLP_ENDPOINT | OTel 上报地址 | 按环境 |
CLAUDE_AGENT_LOG_LEVEL | 日志级别 | info |
CLAUDE_AGENT_SESSION_DIR 尤其重要——默认放在工作目录下，容器重启就没了。必须挂到 PersistentVolume 或者 emptyDir 根据需求选。
我最初给 agent pod 配的是 memory: 512Mi、cpu: 0.2，跑了一天就 OOM。
实测下来的合理配置：
如果 agent 会跑重量级工具（比如本地跑 ML 推理），资源得往上翻。
这条是我的一次生产事故换来的。
我最初的 readiness probe 只检查 HTTP 端口是否监听：
1 | readinessProbe: |
结果有一次 Anthropic API 某个区域抽风，agent 进程活着、端口开着，但所有 API 调用都超时。k8s 以为 pod 健康，继续把流量打过来，全挂。
改成 HTTP 探测 + 自定义 /healthz 接口，里面做一次轻量级的 API 连通性检查（每 30 秒缓存一次，不要每次都真的调）：
1 | readinessProbe: |
/healthz?deep=true 的实现里，我们会检查：本地 session 目录可写、Anthropic API 可达（cached 30s）、MCP server 连接正常。
这三样缺一不可。
JSON 格式：便于 ELK/Loki 直接解析。
脱敏：我前面那篇提过，output 里可能带 API key、数据库密码、用户隐私。正则过滤是兜底，更好的做法是 hook 里主动标记字段。
trace_id：每个 session 绑定一个 trace_id，所有 log 都带上。配合 OTel 能实现”看到一条日志，跳转到完整 trace”。
agent 跑长任务时（比如一个 15 分钟的 code migration），滚动升级直接 kill 会丢掉当前进度。
我们的做法：
deployment 里的关键配置：
1 | spec: |
maxUnavailable: 0 保证滚动时服务容量不降。
客户现场一份简化版：
1 | apiVersion: apps/v1 |
不完整但能看明白大致结构。
session 目录占用会随时间线性增长。我的经验数据：
日增量 * 保留天数 * 1.5（1.5 是安全系数）我们另外跑了个定时 job，每天凌晨把 30 天以上的 session 归档到 S3，释放 PVC 空间。
生产环境别让 agent 容器无限制访问外网。agent 理论上可能被 prompt injection 诱导发起外联。
我们的 NetworkPolicy 只允许：
api.anthropic.com:443其他全 deny。
Anthropic API 有速率限制。多实例并发跑 agent，一不小心就超限。
我们在 agent runner 里加了一层 token bucket，限制单实例对 API 的 QPS。集群层面再用 Redis 做分布式限流。两层兜底。
agent 是真的烧钱。没有成本监控，月底账单会吓死你。
我们每次 API 调用的 usage 信息（input_tokens、output_tokens、cache_read、cache_creation）全上报到 OTel，再在 Grafana 上算成本。
单个 review agent 实例日均 $0.47，单个 migration agent 日均 $2.13。集群总成本月均大概 $2800。有了这个数据才能做优化决策——比如是不是切一部分任务到 Haiku 能省钱。
我们还设了成本告警，单实例日成本超过基线 2 倍就 page。一般是 agent 陷入死循环或者 context 打爆 导致成本飙升。
Anthropic API 偶尔会抽风（不常，但发生过）。我们的兜底：
pending_api，写队列等恢复业务侧看到的是”任务排队中”，用户体验还能接受。
这 13 条不是一次性想出来的，是踩过坑之后沉淀下来的。有些坑可能你永远碰不到，有些坑我没踩过但你会踩到。
部署这事儿没有银弹，只有”少犯几次错”。每次出事故认真复盘，把它固化到流程和配置里，下次就能避开。
SDK 的可观测性那套 和部署配合起来，线上 agent 才算真正可以交给运维。
我当时就懵了。因为那张 Excel 全是 MMLU、HumanEval、GPQA 这种评测分数。我跟他们说，这些分数你看看就行，真要决策，别用这张表。
城商行那家的问题是合规。他们的 AI 应用场景是信贷合同审阅和内部知识库问答。合规部门一开始直接把 API 出境这条路堵死了——客户数据不能出大陆。这就把直接调 Anthropic API 这条路干掉了一大半。但他们不想用国产模型，原因是总行那边做过压力测试，中文 OCR 后的长合同抽取，Claude 的准确率能到 91.2%，国产几家卡在 78% 左右。那 13 个点的差距在风控场景是没法忍的。
最后怎么办？走 AWS Bedrock 的新加坡 region + 数据脱敏前置。走这条路的成本比直连 API 贵 12% 左右，但合规评审委员会过了。
零售连锁那家要的是跑规模。他们有 2,300 多个线下门店，每天生成 40 多万条客服工单，想让 AI 自动分类 + 拟回复。这种场景对成本敏感到极致，每 1,000 条工单的处理成本差 $0.08 一年都是几十万的账。他们一开始铁定要上 GPT-4o-mini，我让他们做了个 A/B：同样 5,000 条真实工单，Haiku 4.5 跟 4o-mini 对跑一周。结果 Haiku 的人工复核通过率高了 6.7 个点，成本几乎持平。
医院那家反而最麻烦。HIPAA、等保三级、病历不出院这三条叠一起，直连 API 和 Bedcork 都走不通。最后他们选了私有化部署一个开源 70B 做一线分流 + 少量复杂病例走 Bedrock 海外 region 脱敏后调用。这是一套混合架构，我帮他们写了数据路由的决策树，实际落地的时候又改了 4 轮。
我后来给这三家都用过同一张评分卡，六个维度，每项 10 分：
Claude 在我这三个客户里，能力、合规、数据主权三项都是最高分。Constitutional AI 这个机制在合规评审委员会那边意外地好使——银行风控部的一位老大哥原话是”这个训练方式至少能跟监管解释得清楚”。长 context（200K）在合同审阅场景直接碾压 32K 窗口的竞争对手，一份 180 页的并购协议可以一次喂进去，不用切片再拼接。
GPT 这边强在生态和多模态。Azure 那套企业合规也很齐。但 4o 以来对复杂 reasoning 的稳定性我个人觉得是下滑的，尤其是长链路任务。这个我跟甲方的技术组长聊的时候，他给我看他们的测试日志，一条复杂多步审核任务，GPT 会在第四五步开始飘，Claude 相对稳得多。这一点在 agent-sdk-production-deploy 那篇里我展开讲过。
本土支持这一项 Claude 是弱项。这事儿要承认。大陆没有官方商务团队，出问题只能在 Discord 和社区问。我给城商行做评审的时候，这项只给了 4 分。但他们最后还是选了 Claude+Bedrock，因为合规那几项硬指标加权后总分还是最高。
零售连锁那家最后从 OpenAI 全面迁到了 Claude。迁移周期 7 周，账单从平均每月 $48,210 降到 $30,180，省了 37.4%。这个数字不是吹的，我手里有账单截图。
省钱的来源三块：
一块是模型切换。他们原来 70% 的流量走 GPT-4o，30% 走 mini。迁移后 85% 走 Haiku 4.5，15% 走 Sonnet 4.6。Haiku 在他们的客服分类任务上跟 4o-mini 打平，但单价更友好。
第二块是 prompt 缓存。这个是 Claude 的杀手锏。他们的客服工单前缀是固定的系统 prompt + 公司知识库片段，每条工单这段加起来有 6,800 token。启用缓存以后这段 90% 走缓存读取，成本直接降到原来的 10%。具体怎么接我在 cost-bill-anatomy 讲过。
第三块是 Batch API。他们有一个每天凌晨跑的商品描述生成任务，迁到 Batch 以后这部分成本直接砍一半。cost-batch-api-50-off 那篇里的套路基本都用上了。
当时他们技术 VP 问我，省这点钱值不值得折腾 7 周。我算了笔账：一年省 $216,360，折合人民币 155 万。就算算上工程 3 个人月的投入，ROI 也是 5 倍以上。
有一条线是我一直跟客户明说的：80% 的企业场景不应该自研基座模型。
但有 20% 的场景自研反而对。我见过三种：
第一种是极端低延迟。某量化交易团队要的是 10ms 内的决策辅助，任何 API 调用的网络抖动都受不了。这种只能自己 host 小模型。
第二种是完全离线场景。某军工类客户的研发环境是物理隔离的，连不了公网，连 Bedrock 都走不通。只能自己 host。
第三种是把 LLM 当作核心业务护城河。比如一个法律 SaaS 想靠”专有合同模型”拉开跟竞品的差距，那是得自己训。这种客户要想清楚，自研一个 70B 级别的垂类模型，年投入至少 2,000 万起步，团队要 15 人以上。搞不定就别上。
这个话题我在评医院那家的时候聊过很久。他们一开始想全自研，我拦下来了。理由是他们的 AI 团队当时 4 个人，再招 10 个也不够。现在他们走的是”基座用 Claude + 医学专有知识库通过 MCP 和 context-memory-long-term-agent 里讲的长期记忆方案注入”，效果跟全自研差不了多少，但工程代价低一个数量级。
说白了，benchmark 分数是给媒体看的。真正决策的那张评分卡上，有一项在所有表格里都不会出现，但比什么都关键——“这个任务老板愿不愿意放手”。
银行那位 CIO 跟我说过一句话我一直记着：他说”同一个任务，如果 Claude 错了我能跟行长解释，GPT 错了我解释不清，那我就只能选 Claude”。这听着玄学，其实是信任度问题。Constitutional AI 的训练方式、Anthropic 的安全研究文化、长期的可解释性投入，在企业采购评审那个会议室里，比多考 2 分 MMLU 有用得多。
选型这事儿没有标准答案。你的约束决定你的选择。我上面讲的三个案子，银行选 Bedrock+Claude，零售选直连 Claude，医院选混合架构。三种答案，都是对的。
关于怎么把选型落地成跑通的产品，我还写过 mcp-security-best-practice 和 enterprise-governance-audit-log，治理那块的坑也不少，建议连着看。
去年有个事故我记到现在。
客户是家做法律咨询的，AI 助手用的 Claude Sonnet。用户在对话第 15 轮说自己有一笔 48 万的遗产纠纷，要咨询继承顺序。第 16 到第 40 轮中间聊了一堆背景——父母离异、兄弟几个、有一个继父、继父带来的两个子女。
到第 42 轮，用户问了一句”那我应该起诉谁”。
我们那会儿做了简单的历史截断——超过 30 轮就只保留最近 20 轮。结果 AI 回答里说成了”您只需要和两位兄弟协商即可”——那个继父和继子女的信息早就被截掉了。
那一次差点吃官司。从那之后我再也不敢用纯截断策略。
最朴素的做法：设一个轮数上限，超过就从头砍。实现十分钟能搞定。
信息损失率实测：我们跑过一个基准测试集，120 个 case，每个 case 40-60 轮对话。纯截断（保留最近 15 轮）的信息召回率是 **43.7%**。几乎一半关键信息丢了。
为什么这么惨：用户往往在对话早期交代背景，后期只抛出具体问题。截掉早期就是截掉上下文。
什么时候可以用：真的不建议用。除非你的场景是客服——每次对话独立，不跨 session。那用户如果第二次来咨询，你反正也不需要记得第一次。
说句实话我现在看到代码里有 messages[-N:] 这种直接切片的，都会把人叫过来谈话。
分三层：
L1 近期原文：最近 6-10 轮原封不动保留。
L2 中期要点：倒数第 11-30 轮，每 3-4 轮生成一个小摘要，约 150 token 左右。这一层保留关键 entity、用户意图转折点、AI 已做的承诺。
L3 远期摘要：30 轮以前整段压缩，约 500-800 token。这一层只保留”这场对话是关于什么、用户的核心诉求、已经解决和未解决的事项”。
信息损失率实测：同样那 120 个 case，分级压缩的召回率 **84.2%**。比截断好太多。
实现关键：
第一，L2 和 L3 的压缩 prompt 要完全不同。L2 是”请保留所有数字、日期、人名和具体诉求”，L3 是”请概括对话主题和已达成的共识，不超过 800 字”。粒度不一样。
第二，entity 白名单机制。压缩时显式提取出金额、时间、人名、地点、医疗术语、法律条文号，单独存成一个 entity list，和摘要一起喂回 context。这个机制救了我好几次。
第三，L2 不是一次性生成的，是增量更新。每 3 轮新对话来了之后，用 Haiku 对这 3 轮做小摘要，append 到 L2。而不是每次都重新压缩整段——太贵。
成本：Haiku 4.5 做压缩一次 300 token 左右，成本 0.00012 美刀。一个 60 轮对话全程大概压 15 次，总成本 0.0018 刀。相比 Sonnet 的 input 费用节省 70% 以上。
我踩的坑：最开始 L2 的摘要让 Haiku 自由发挥，结果它经常”优化”掉用户的原话。用户说”我觉得这个方案不错但有点贵”，压缩完变成”用户对方案表示满意”——“有点贵”这个关键反馈丢了。后来我在 prompt 里明确要求”保留用户的原始措辞，尤其是带情感倾向的表达”，才好转。
这个策略是我从一个客户那里学来的，他们团队里有个做知识图谱出身的工程师。
核心思想：不压缩对话，而是从对话里抽取事实。
每轮对话结束后，跑一个抽取任务，产出形如：
1 | <facts> |
每个 fact 带 id、类型、原始对话轮次引用。
再下次对话时，context 里不放对话历史本身，而是放 fact list + 最近 3-5 轮原文。
信息损失率实测：同样基准，召回率 **88.9%**。比分级压缩略高。但注意这个数字是在”精确引用”测试集上——如果测试集是”语气一致性””理解对话的情感脉络”这类软指标，entity-centric 反而不如分级压缩，因为它丢了语气。
为什么强：
第一，可审计。每个 fact 可以追溯到原始对话。用户质疑”AI 为什么说我不吃辣”，你能精确定位。
第二，可修改。用户说”我改主意了，现在可以接受高风险”，你直接把 f2 覆盖掉。朴素摘要做不到这种精细更新。
第三，可组合。fact 库可以跨会话累积，变成用户画像。但这需要额外做冲突检测，上一篇文章讲过。
什么时候别用：
任务如果高度依赖”情感连续性””语气”——比如陪伴聊天、创意写作——entity 抽取会把灵魂抽没。
实现成本：比分级压缩高一倍。每轮后要跑一次抽取 + 每次请求前要拼接 fact list。但长期看收益更大，尤其配合 CLAUDE.md 这种项目级配置 一起用。
做了张表，是我这半年几个项目的实测均值（60-80 轮对话）：
| 策略 | 信息召回率 | 单会话压缩成本 | 实现复杂度 | 适用场景 |
|---|---|---|---|---|
| 朴素截断 | 43.7% | 0 | 极低 | 基本别用 |
| 分级压缩 | 84.2% | ~$0.002 | 中 | 大部分通用场景 |
| Entity-centric | 88.9% | ~$0.004 | 高 | 严肃决策场景 |
我现在的默认选择：通用场景分级压缩，严肃场景 entity-centric。偶尔也会混用——近期用分级，远期用 entity 化的 fact list 兜底。
Anthropic 没公开过 Claude.ai 里”记得住几个月前对话”功能的技术细节。但从我观察到的行为来看，我的猜测是这样的：
第一，用了 entity-centric 为主的记忆层。因为 Claude.ai 能精确回忆”你三周前跟我说你在学 Rust”这种细节，而且跨会话都能命中。这不像纯摘要能做到的。
第二，近期会话保留更多原文。同一个会话内前后文连贯性极好，断层罕见。这说明近期没过度压缩。
第三，有 用户可见的记忆管理入口。用户能看到、删除、修改记忆。这种 UX 暗示底层是结构化的 fact，不是黑盒摘要。
第四，召回是 LLM 主导的。对话中 Claude 会自己判断”要不要调用记忆”，而不是每次机械检索。这点和我上一篇写的 agent 记忆架构思路一致。
当然这都是我瞎猜，Anthropic 哪天发工程 blog 估计会把我打脸。但八九不离十。
第一，压缩模型要比主模型小一档。 主力用 Sonnet，压缩用 Haiku。用 Opus 做压缩是浪费。
第二，摘要的 prompt 要版本化。 我在 repo 里专门有个 prompts/summarization_v3.xml，改动要走 review。因为摘要 prompt 直接决定了你的”记忆质量”，不是随便改的。
第三，留一个”压缩旁路”。 关键决策点（用户下单、签约、投诉）的那几轮对话永远保留原文，不进压缩池。这种关键轮次的识别靠 Haiku 实时打标。
做记忆这件事最忌讳聪明过头，把简单问题做复杂。但更忌讳偷懒，把复杂问题做简单。压缩这一块，属于后者。
延伸阅读
压缩策略上游是 [Context 预算拆桶](/posts/prompt-to-context-engineering/)，下游对接 [长期记忆架构](/posts/claude-md-project-config/)。压缩 prompt 的结构化输出强烈建议用 [XML 标签](/posts/prompt-xml-tags-claude-special/) 而非 Markdown。想省调用费，[Prompt Caching 深度指南](/posts/prompt-caching-deep-guide/) 配合分级压缩效果拔群——中期摘要那一段正好适合做缓存。
先澄清一个容易混的东西。
Claude Code CLI 有一套 hook 系统，配在 ~/.claude/settings.json 里，触发时机是 PreToolUse、PostToolUse、SessionStart、Stop 这几个。这套我之前写过。
Agent SDK 里的 hook 是另一层——它是 SDK 运行时的事件回调。它能看到 CLI hook 看不到的事件，比如 token budget 接近阈值、cache hit/miss、stream 断流、内部重试。粒度细得多。
两套 hook 可以同时存在且不冲突。我的生产部署两套都开了：CLI 那套做”这个命令能不能跑”的安全门，SDK 那套做”这个 agent 现在在干什么”的观察。
用了小半年，我在 SDK 里注册监听的事件主要有这 7 类。每类我都接到了 OTel 上，以 trace + metric 两种形态上报。
工具开始执行时触发。payload 里有工具名、输入参数、session id、agent id、父 span id（如果是嵌套调用）。
我用它做：工具调用的分布式追踪（span 起点）、输入参数的脱敏日志（比如去掉 API key）、工具 QPS 统计。
工具执行完成时触发。带执行时长、输出大小、是否成功、错误类型（如果失败）。
用来做：工具 P99 延迟、错误率、输出大小分布（用来优化 context 占用）。
当前 session 的 context 占用超过某个阈值时触发。SDK 默认 80% 触发 warning。
用来做：context 接近满的告警（提前知道 agent 要慢了）、触发自动压缩策略。
权限系统拒绝了某次工具调用时触发。带被拒的命令、拒绝原因、session id。
用来做：安全审计（看有没有异常的工具调用尝试）、用户体验优化（拒绝太多说明 allowlist 太严）。
session 被 resume 时触发。带 session 年龄、大小、上次停止原因。
用来做：session 复用率分析、resume 性能监控。
agent 停止执行时触发。带停止原因（end_turn、max_tokens、tool_use、user_interrupt、error）。
用来做：判断 agent 是不是健康结束的、异常终止率。
SDK 内部抛错时触发（不是工具执行错误，是 SDK 本身的错）。
用来做：SDK bug 发现、网络/API 问题监控。
我用的是 @opentelemetry/api + @opentelemetry/sdk-node，上报到 Grafana Tempo。
注册 hook 的大致形式：
1 | import { trace, metrics } from '@opentelemetry/api' |
这里我省略了不少生产细节，比如脱敏、trace_id 透传、采样策略。
Grafana 上我搭了一个专门的 agent 看板，8 个面板：
bash 工具大概 140 次/分钟，edit 工具 60 次/分钟。bash P99 约 4.7 秒（因为有长命令），edit P99 约 230 毫秒。看板刷新频率 10 秒，跨 3 天滚动窗口看趋势，单小时窗口看当前状态。
告警这事儿最容易踩的坑是——阈值定太死，半夜告警炸群；定太松，真出事了没人看。
我现在的阈值：
3.2% 和 8% 这两个数字是我基于历史数据拟合出来的——正常波动基本在 2% 以内，3.2% 意味着明显异常但可能是上游临时抖动，8% 意味着确定出事了。
最让我感谢 hook 日志的一次。
去年 12 月某天，运营同学说他们的内容审核 agent 行为异常——本来让它分类的文章，它突然开始”建议用户访问某 URL”。这是典型的 prompt injection 迹象。
我第一反应是翻 hook 日志。按 session id 拉出 tool_start 和 tool_end 记录，重建了 agent 当时的完整行为轨迹：
read 工具）定位完之后做了几件事：
这次定位前后花了大概 40 分钟。没有 hook 日志我估计两天都查不出来。
几个容易忽略的点：
/sk-[a-zA-Z0-9]{40,}/ + 一堆其他模式。可观测性对于 agent 系统不是可选项。agent 比传统服务更难调试——它的行为是非确定性的，错误可能藏在 20 层 tool_use 深处。没有细粒度的 hook 日志，你基本只能瞎猜。
好在 Agent SDK 把这套暴露得挺到位，接 OTel 的成本也不高。花一两天把这套搭起来，后面省的时间是几十倍。
我跟他解释完他愣了半天，差点把不用的那份退掉。
这种混乱我这两年见了太多次，干脆整理一篇。
先把定位讲清楚，后面选型才不纠结。
Claude 桌面端（claude.ai 网页版 + macOS/Windows 原生 App）：面向终端用户的聊天产品。像 ChatGPT 那样聊天用的。有 Projects、Artifacts、记忆、MCP 支持。按月订阅 Claude Pro（20 美元）或 Max（100+ 美元）解锁额度和功能。
Claude Code：面向开发者的命令行 + IDE 集成工具，专门写代码用。跑在你本地电脑上，直接操作你的文件系统和 git。走 Claude Pro/Max 的订阅额度——关键：不需要单独再买一份订阅，同一个 Pro 账号在桌面端和 Claude Code 里共用额度。
API（console.anthropic.com 拿 key 之后直接调）：面向产品开发的裸模型接口。按 token 计费，跟上面两个的订阅完全是两套账。你做一个产品给别人用，必走 API。
第三方客户端（比如 Chatbox、Cherry Studio、NextChat 这类）：自带 UI，但底层调用的是 API key。相当于你有一瓶矿泉水（API），这些客户端给你提供了更漂亮的杯子。
关键要理解：订阅和 API 是两套账。Pro 订阅不能让你的 API 变便宜，API 充值也不能让你用桌面端。
把你的需求对号入座：
| 你的需求 | 推荐入口 |
|---|---|
| 我就是想聊天、写东西、查资料 | 桌面端 Pro |
| 我要写代码、改代码库、做 refactor | Claude Code |
| 我要做个产品/服务给别人用 | API |
| 我想要 MCP 自由度（接各种外部工具） | 桌面端 + MCP 配置 |
| 我想多模型对比、本地跑 Prompt 实验 | 第三方客户端 + API |
| 我要批量处理数据、定时任务 | API（尤其是 batch API） |
| 我是个人开发者，写点小脚本自用 | API + 第三方客户端 |
最常被搞混的两项我展开一下。
我见过至少 5 个朋友这么理解过。实际上 Claude Code 是内置在 Pro/Max 订阅里的。你开了 Pro（20 美元/月），在终端 claude 命令装一下，登录同一个账号，就能直接用，没有额外费用。
如果你是重度代码用户，Max 订阅（100+ 美元/月）的额度更大，适合一天几小时都在 Claude Code 里泡着的人。
如果你不是订阅用户，也可以用 API key 跑 Claude Code，按 token 计费。这种方式在长时间密集使用时比订阅贵，但零散用比较灵活。
具体能力差异和跟 Cursor/Cline 的对比，我写过一篇 Claude Code 横向对比。
MCP（Model Context Protocol）这个协议，很多人第一次听说是从 Claude Code 那边，就以为只有 Claude Code 才支持。
实际情况是：桌面端现在也完全支持 MCP。你在桌面端配置 MCP server（比如接你本地的 Obsidian、Notion、GitHub、数据库），Claude 桌面端就能调用这些工具。
我自己的设置是桌面端接了 6 个 MCP server，一个日常查文件、一个查日历、一个查本地数据库、两个跟我自己产品后台打通、一个外部搜索。相当于把桌面端的 Claude 升级成了一个真正的”了解我的工作环境”的助手。
想搞清楚 MCP 跟 function calling 的区别、什么时候选哪个，可以看这篇 MCP vs Function Calling 对比。想看 MCP server 实战案例，内部工具用 MCP server 的思路里有几个可以直接抄的模板。
给你看一个具体的一天：
早上 8:30-10:00：开桌面端 Claude。今天要写一篇文章，先让 Claude 帮我梳理大纲、找论据、列潜在反驳。我开着 Projects，把相关的参考资料都挂在 project 上下文里。这个阶段用桌面端是因为它的 Artifacts 能直接预览写作效果，MCP 能让我连接本地笔记库。
上午 10:00-12:00：切到 Claude Code。有个项目要改一个鉴权模块的 bug，我用 Claude Code 跑在 repo 里，直接让它读代码、写测试、跑验证。这种活桌面端做不了——它没法直接动我的文件系统和 git。
下午 14:00-17:00：开 API 脚本。今天要把 500 篇客户反馈做情绪分类，写一个 Python 脚本调 API 批量跑。这种规模用桌面端会累死，用 Claude Code 也浪费——API + batch mode 跑一下，等 2 小时就出结果，而且是半价。
晚上：偶尔用第三方客户端（比如 Chatbox），因为我同时在测 Claude、GPT、Gemini 三家回答同一个问题，客户端能并排显示对比，方便。
所以四个入口不是互斥选一个，是互补。每个入口解决一类问题。
个人学习/写作：桌面端 Pro，一个订阅够用。
独立开发者做小产品：桌面端 Pro（聊天/测试用）+ API key（产品调用）。订阅是你的”工作台”，API 是你产品的”发动机”。
公司团队写代码：每人一个 Pro 订阅 + Claude Code。如果要做产品内嵌 AI 就再加 API。
数据处理/批量任务：只需 API，不必订阅。充值好额度，用 batch 接口，定时跑。
给家人/朋友送礼：他们大概率用桌面端就够了，Pro 订阅当生日礼物最实在。
Pro 订阅一个月 20 美元，上限大概相当于 API 充值 40-60 美元的用量。如果你每个月 API 消耗接近或超过这个水平、且主要是交互式使用，订阅会更划算。如果你只是零散用、或者用量很不稳定，API 按需付费更好。
搞清楚怎么选之后，具体到每次请求该用哪档模型，建议看Haiku/Sonnet/Opus 选型那篇，成本还能再挤下来一半。
想系统学 Claude？
选完入口，下一步看Claude Code 对比 Cursor 和 Cline搞清楚代码工具生态。桌面端要接 MCP 的朋友，MCP 和 Function Calling 的差异是必读。走 API 路线的，15 分钟 API 快速上手能把你送到第一个请求。
我爬起来打开控制台，发现是一个长文档摘要 agent 跑飞了，进入了一个自我引用的死循环。每次调用都把前一次的输出塞回 context，越滚越大。跑了大概 4 小时，烧掉 $347.18。
后来做善后的时候意识到一个事：如果我在流式输出里加一个 watchdog，检测到异常模式就主动 abort，这 $347 能压在 $10 以内。
从那之后我看 streaming 的视角就变了。它不只是前端体验好看那点事，它是实打实的 budget 保险丝。
非流式调用：你发一个 request，等 8 秒，拿到完整回复，按 output token 数扣钱。无论这回复你要不要，钱都付了。
流式调用：你发一个 request，开始一个 token 一个 token 往回吐。你可以在任何时刻 abort 连接。abort 之前生成的 token 计费，之后的不计费。
这个差别在大多数短任务里无关紧要 —— 生成个 200 字的回复也就一两秒，等就等了。但在三类场景里差距极大：
一是长文生成（5000+ token）。生成中途发现跑偏可以立刻停。
二是 agent 推理链（带 extended thinking 或多轮 tool use）。检测到重复工具调用就 abort。
三是 RAG 场景下的长文总结。用户看到一半觉得够了手动停。
省下来的钱取决于你 abort 得多及时。我实测过几个场景，激进 abort 策略下能从总 output token 里砍掉 50-70%。
具体怎么做。我一般在 SDK 外面包一层 streaming handler，里面维护一个 buffer，每收到一个 chunk 做下面这些检查：
检查一：重复内容检测。
用滑动窗口（比如最近 200 字符）算一个简单的 hash 或者 ngram 频率。如果当前窗口和 30 秒前的窗口相似度 > 85%，说明模型开始复读机了，直接 abort。
我救那个失控 agent 就是靠这个。它当时生成的是 “用户的问题是… 让我重新分析… 用户的问题是… 让我重新分析…” 这种循环。
检查二：工具调用异常。
如果是 agent 模式，同一个工具在短时间内被调用超过 N 次（我设的是 3 次/分钟）就怀疑循环了。特别是同一个工具被传入相同参数调用两次以上，基本就是死循环。直接 abort 然后报警。
检查三：明显跑偏的语义信号。
这个主观一点。我在一个合同审查 agent 里加了个规则：如果输出里出现「我无法完成这个任务」「让我重新开始分析」这类撤退语，说明模型卡住了，abort。
检查四：token 数硬阈值。
最 naive 的一条但很管用。给每种任务设一个合理的最大 output token 数（比如摘要任务 800、答复任务 300、报告生成 3000），流到阈值主动停。比 API 的 max_tokens 参数更细粒度，因为你可以根据任务类型动态调整。
API 原生支持 stop_sequences 参数，匹配到指定字符串自动停。和 streaming 搭配有奇效。
场景：我让 Claude 分步骤回答，每步用 <step>...</step> 包裹。设 stop_sequence 为 <end>，在 system prompt 里约定「回答完所有步骤后输出
这样我在 client 侧边流边处理 step，如果中途 step 解析出错或者业务逻辑判断已经够了，主动 abort。如果模型正常完成，遇到 <end> API 自己停。
比单纯靠 max_tokens 限制优雅。max_tokens 截断会留半句话、JSON 不完整，stop_sequence 截断在语义边界上。
这是我觉得最反直觉但最有效的一招。
传统做法：用户点「总结这个 50 页 PDF」，后端跑完返回 2000 字总结，用户看一半觉得够了关了页面。你为剩下那 1000 字付的钱全浪费。
流式做法：一开始就 stream。用户看着 token 一个个冒出来，看到自己想看的部分之后，点「够了」按钮，前端发 abort 信号给 server，server 关 Anthropic 的 stream 连接，停止计费。
我一个法律文档助手产品实测：开启用户主动停功能之后，平均 output token 从 1847 降到 563，省了 69.5%。用户满意度反而小涨了 2 个百分点，因为他们觉得自己「掌控了节奏」。
要注意的是 UI 上要把「停止」按钮做得明显。我一开始把它做成一个小 × 号，用户根本没注意到。改成一个大大的「这些够了，停止生成」之后才真正发挥作用。
回到开头那个 $347 事件。复盘之后我在公司内部统一加了一个 streaming watchdog，规则大致是：
上线之后第一周 watchdog 触发 abort 了 21 次。21 次里有 17 次是真的有问题（prompt bug、context 没裁、循环调用），4 次是正常长任务被误杀。后面调了阈值把误杀降到 1% 以下。
现在 watchdog 平均每天触发 abort 3-5 次。按每次平均节省 $0.80 算，一个月给我省 $100 多。更关键的是再也没出过那种一晚上烧几百刀的惊魂时刻。
更精细的玩法是给每个请求设一个成本预算。
我在 streaming handler 里维护一个累计 cost 计算器，每收到一个 token 按该模型的 output 单价累加。到达阈值（我给普通用户是 $0.10 / request，付费用户 $1.00）主动 abort 并返回一个礼貌的「本次回复已达生成上限」的提示。
实现不难。Sonnet 4.5 的 output 是 $15/M，每个 token 大概 $0.000015。你累加到 $0.10 就是 6666 个 token，足够 90% 的合理任务，拦截的是那 10% 的异常长输出。
这个机制救过我一次更隐蔽的事故：某个用户 prompt injection 让模型生成 50000 字的小说。如果没预算拦截，这一次请求 $0.75。watchdog 在 $0.10 处截断，省了 $0.65。单次不多，但如果被黑产批量刷就是另一回事了。
多租户 SaaS 的预算控制还涉及按用户维度的日/月上限，这块结合 Agent SDK 生产部署 里讲的 key 分层一起做比较干净。
流式 abort 主要解决的是「异常输出」的成本，常规输出的成本还是得靠 output token 压缩 和 多模型路由。
streaming 和 batch 是互斥的，选 batch 就没流式。但大多数实时场景不走 batch，所以不冲突。
cache 和 streaming 完全兼容。cache 优化的是 input 侧，streaming 管 output 侧，Prompt Caching 深度指南 那些实践可以和 streaming watchdog 叠加使用。
从把 streaming 当 UX 特性到当作 budget 工具，这个视角切换对我帮助很大。现在每个新产品上线前，streaming + watchdog 是标配。
顺带一提：别等出事才加 watchdog。我那 $347 账单虽然最后 Anthropic 客服帮我申诉退回了一部分（因为他们后台也看得出是异常模式），但也退了不到一半。自己装好保险丝比事后求情靠谱。
]]>你在 playground 里跑 10 次都好好的，上线之后一天跑一万次，总有几十次它给你塞一句”Here is the JSON you requested:”开头，或者最后多个 markdown 代码块标记，或者引号没闭合，或者塞了个注释（JSON 是不允许注释的）。
那段时间我下游 parser 的 try/except 里能喂饱一个告警群。
后来慢慢摸出来一套组合拳，现在我项目里 JSON 出错率能压到 0.5% 以下，而且剩下那 0.5% 也能被兜底解析救回来。这篇把所有套路说清楚。
我拿一个抽取 10 个字段的任务跑 10000 条，不同方案的合规率：
{ 作为起始：97.6%从 87% 到 99.8%，差的不是一点半点。但是 tool use 也不是每个场景都能用，所以后面的套路都要备着。
这是 Anthropic 官方也在推的方案。本质上你定义一个 tool（带 JSON schema），让 Claude”调用”这个 tool 来输出——Claude 在调用 tool 时的参数就是严格遵循 schema 的 JSON。
1 | tools = [{ |
tool_choice 强制指定调用哪个 tool——这样模型不会犹豫要不要调，直接调。返回的 tool_use block 里的 input 就是合规 JSON。
这条路的好处：
坏处：
关于 tool use 和 MCP 的关系、什么时候用哪个，这篇我专门讨论过。
不用 tool use 的时候，先把你要的结构写清楚。光说”return JSON”不够，得告诉它是什么样的 JSON。
1 | <output_format> |
几个要点：
high|medium|low 这种竖线语法，模型理解很好<output_format> 这种 XML 标签包起来比 markdown 标题稳。Claude 对 XML 的偏好我在这篇里系统讲过这是个非常好使的小 trick。在 API 调用里，你可以在 messages 的最后塞一个 assistant 消息，内容是 {——Claude 会从这个 { 继续往下写，自然就不会再加什么”Here is the JSON:”这种废话了。
1 | messages = [ |
返回结果会缺少最前面的 {，你自己拼回去就行。这个技巧光加这一条，成功率从 94% 干到 97% 以上。
注意：
<result>前面解决了开头，还有结尾问题。有时候模型会在 JSON 结束后多输出几行解释文字，虽然 parser 能切掉，但不优雅。
1 | response = client.messages.create( |
这个要根据你的 JSON 结构定。如果你的 JSON 只有一个顶层对象，} 后面跟两个换行基本能卡住收尾。如果是嵌套多层的复杂对象，你得想清楚停在哪儿。
Stop sequences 不会出现在返回结果里，是个干净的截断。
就算你前面四招都用上，总还有那么 0.5% 会翻车。真实线上不能让这 0.5% 打穿 pipeline。我现在的兜底层是这么写的：
1 | def robust_json_parse(text: str): |
这套逻辑能救回大约 90% 的”小翻车”。剩下实在救不回来的，触发重试机制，重跑一次基本就好了。
转义字符的坑。中文内容里夹英文引号、代码片段里的反斜杠，这些在 JSON 里必须转义。Claude 大多数时候会处理对，但偶尔会漏。我现在的做法是：需要输出代码或者含引号内容时，尽量用 base64 或单独字段存储，避免它在 string 里硬转义。
日期和数字。你在 schema 里说”amount: number”，它有 3% 概率给你一个 "12000" 字符串。解决办法：要么 parser 里做类型归一，要么在 schema 描述里加一句”金额必须是纯数字，不能加引号”。
可选字段。Claude 对”可选”理解有时候偏差。你让它”字段 X 如果没有就不要这个 key”，它有时候会给你填 null 或空字符串。我现在干脆规定：”所有可选字段，如果无值，填 null”——统一了就好处理。
多层嵌套深不要过四层。我跑过一个五层深的 schema，错误率直接飙到 15%。复杂结构建议拍扁成多轮调用，每次处理一层。
组合起来长这样：
1 | SYSTEM = """你是一个结构化数据抽取助手。严格按照指定 JSON schema 输出， |
能用 tool use 的场景我直接上 tool use。不能用的场景这个模板顶得住 99.5%。
JSON 稳定性这事，单个技巧提升都是边际的，组合起来才是降维打击。我见过太多人在一个技巧上死磕——“我加了 prefill 还是不稳啊”。那当然，你没加 schema 描述、没加 stop、没加兜底，单靠 prefill 救不了命。
把这 5 招全部铺上，再留一层重试和兜底，基本能把 JSON 这块的工程风险降到可以不再每天看告警的程度。
对了，如果你项目还没开 prompt caching，赶紧开。JSON schema 这种长期固定的内容进了缓存，省下的钱够你一个月的咖啡钱。这篇里有详细的配置方法。刚开始接触 Claude API 的同学可以先去看看API 快速入门打个底。
延伸阅读
Tool use 和 MCP 怎么选，看 MCP vs Function Calling。让 schema 进缓存省钱，去 Prompt Caching 深度指南。API 入门和基本用法，看 Claude API 快速入门。配合 XML 标签让整套 prompt 更稳，别错过 XML vs Markdown 对比。
医生读片本身快，真正耗时的是写 SOAP note——Subjective（主诉）、Objective（客观发现）、Assessment（评估）、Plan（计划）四段。一份报告医生要敲 12 到 18 分钟。他说：「我们医生下班前都是先读完片，然后吃晚饭再回来写报告到晚上 9 点。」
这个项目我做了 6 个月，中间合规过了 3 次。最后跑到生产上，单份报告生成时间 2 分 40 秒（含医生确认），医生日均多看 27 个案子。下面写核心架构和关键取舍。
这是项目最早期就要定的路线。医疗数据涉及 HIPAA，三条路：
路线 A：用 OpenAI / Anthropic 的公开 API——直接被否，HIPAA 合规缺 BAA（Business Associate Agreement）就是违规。
路线 B：自托管 open weight 模型（Llama 3.3 70B 这种）——合规上没问题，数据完全在自己机房。但要投 A100 集群、招 MLOps 工程师、做监控和 eval，年成本估算 $340K。
路线 C：用 Claude 走 AWS Bedrock。Bedrock 提供 HIPAA BAA，数据不出 AWS，合规层面等同于自己机房。年成本估算 $52K（API 调用 + S3 + 一点运维）。
CTO 选了路线 C。他原话：「我们 12 个医生的中心，养不起 MLOps 团队，但 Claude 的医学推理能力又是必须的。」
这里有个关键细节：不是所有 Claude 模型都自动享受 Bedrock 的 HIPAA 覆盖，要走 Anthropic 的企业协议或 Bedrock 的 BAA 产品。他们具体怎么签的我不参与，但工程架构是围绕这个合规前提搭的。
医生读片的习惯是边看边说（dictation），不是先写字再整理。所以入口是语音。
完整链路：
模板这块我做得比较细。不同影像类型的 SOAP 结构差别很大——胸部 CT 的 Objective 段要覆盖肺叶、纵隔、胸膜、骨结构四个部分，颅脑 MRI 要覆盖幕上、幕下、脑室、白质、血管五个部分。我做了 23 个模板，覆盖他们 94% 的日常业务。
红线一：PHI（受保护健康信息）隔离
每个客户的工作流完全独立：
这样即使出事，blast radius 也只限在单一客户。
红线二：敏感信息脱敏
生成 SOAP 时，模型只拿影像发现，不拿患者姓名、生日、SSN 这些。脱敏层在 prompt 注入前跑，把 John Smith, DOB 1967-03-14 这种替换成 [PATIENT]。生成完之后再反向替换回去，贴到医生 UI 展示。
模型本身永远看不到 PHI。这是合规审计时最关键的一条。
红线三：审计日志 + 可追溯
每一次模型调用记一条 audit log：调用时间、医生 ID、患者 ID（加密后的）、输入 hash、输出 hash、模型版本、延迟、token 消耗。
医生的每一次编辑也记录（原文 → 改后）。这些日志保留 7 年（HIPAA 要求）。
审计日志这块我没用 Claude，就是传统的日志系统。但写日志的时机跟 Agent 生命周期绑死，这个在 Agent SDK 生产部署 里讲过。
这个项目跟普通 Agent 最大的区别是：医生不能接受明显的错误。
一个漏诊或误诊，就算再小概率，都可能变成医疗事故。我做的是让模型的边界充分暴露给医生，让医生做最终决策。
具体做法：
生成的每一段带 confidence：模型输出时要求标注「Objective 段 - confidence: high/medium/low」。Low confidence 的段落 UI 上会飘黄，提示医生重点审核。
标记错误 → 回流：医生确认前会勾选「正确 / 需修改 / 明显错误」。被标「明显错误」的案例每周回流一次，我人工看一遍，如果是系统性问题就调 prompt，调完之后灰度 10% → 50% → 100%。
灰度用的是简单的 feature flag，版本切换在 Claude 模型 ID 层面：claude-sonnet-4-6 → claude-sonnet-4-7。不同医生可能跑在不同版本上，审计日志能追溯。
这个闭环做了 6 个月，系统误差率从 4.7% 降到 0.8%（医生标「明显错误」的比例）。
最早我想全用 Opus，医生建议太专业，Sonnet 会不会 hold 不住。跑了两周对比：
差 0.2 分，但成本贵 5 倍多。医生讨论之后决定用 Sonnet，关键理由是「再好的 AI 我们也要人工审核，那 Sonnet 足够了」。
只有在一种情况下用 Opus：复杂多病灶案例（比如多发转移瘤），Haiku 前置分类判断为复杂，自动升档到 Opus。这类案例占 6%，单独走一条链路。这种分级思路我在 Claude 家族选型 里写过。
月均 9600 份报告（320 × 30），3 月账单：
单份报告综合成本 $0.21。对比医生时间：医生人力成本大约 $2.4/分钟，原来一份报告 14 分钟 = $33.6，现在 2 分 40 秒 = $6.4，净节省 $27.2/份。月度净价值约 $261K。
Prompt caching 这里发挥很大，23 个模板都做了 cache，23 个模板的 system prompt 加起来 180K token，cache 命中率 83%。Prompt Caching 深度指南 有完整配置。
坑一：医学术语。ASR 识别「pneumothorax」（气胸）有时会识别成「new motor x」。我加了个医学术语 post-processor 做拼写纠正。
坑二：单位不一致。同一个 CT 报告，「5 mm」和「0.5 cm」混用。模板里统一强制成 mm。
坑三：对比既往片。放射科医生很看重「对比 2024-08-12 片，结节无明显变化」这种话，得让 Agent 能拉历史报告做对比。这涉及跨报告的 context，我用了类似 长期 Agent 记忆 的结构，每个患者维护一份压缩后的既往发现摘要。
坑四：法律措辞。医生不能说「没有肺癌」，必须说「未见明显恶性征象」。这种措辞模板里写死了，Claude 不允许自由发挥。
上线 4 个月之后，我去现场回访。一个资深放射科医生跟我说：
以前下班前最怕写报告，现在下午 5 点基本能走。我反而有时间多看几个疑难病例了。
CTO 给我看他们排班数据：医生日均读片量从 24 份涨到 51 份，多看的这 27 份里有 4 份查出了需要进一步复查的病灶——按他们的口径，这 4 份就可能是救命的。
这个项目让我对医疗 AI 的想法变了。真正的价值不是替代医生，是把医生从打字员解放出来做他们该做的判断。
这篇是完全按照”一个新手第一次碰 Claude API”的真实顺序来的，我自己按表计了时——从注册到第一个请求跑出来，熟手 5 分钟，生手大概 15 分钟。
这个地址要认准。不是 claude.ai（那是聊天产品），是 console.anthropic.com（开发者后台）。
国内用户一个现实问题：注册需要一个能接收短信验证码的手机号，国内号码是收不到的，需要一个海外号或者能收海外短信的虚拟号。这不是 Claude 的问题，是 Anthropic 现在的注册门槛。解决方案我就不在这里展开了，网上方案很多。
注册完之后登录，左侧菜单找 Billing，先把付款方式加上。没有付款方式的账号有免费额度但很少，几次测试就花完了。
Dashboard 左侧 API Keys → Create Key，给它起个名字比如 local-dev，点生成。
关键：这个 key 只会显示一次。复制下来立刻存好，页面关了就看不到了，只能重新生成。
存到哪？别存到代码里。我见过不止三个朋友把 key 直接 commit 到 GitHub 公开仓库的——有人 20 分钟内就收到 Anthropic 的告警邮件说 key 已经泄漏自动禁用了，运气好没扣钱；有人没这么走运，被人刷了 300 多刀。
Mac/Linux，在 ~/.zshrc 或 ~/.bashrc 加一行：
1 | export ANTHROPIC_API_KEY="sk-ant-xxx..." |
然后 source ~/.zshrc。
Windows PowerShell：
1 | [System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-ant-xxx...","User") |
重开一下 terminal。
验证：echo $ANTHROPIC_API_KEY（Windows 是 echo $env:ANTHROPIC_API_KEY），能打出 sk-ant- 开头的字符串就 OK。
测通这个说明网络+key 都没问题：
1 | curl https://api.anthropic.com/v1/messages \ |
正常情况下你会看到一个 JSON 返回，里面 content[0].text 就是 Claude 的回答。
跑不通？往下看 Step 7 的排错清单。
我假设你装了 Python 3.10+。
1 | pip install anthropic |
写一个 hello.py：
1 | from anthropic import Anthropic |
python hello.py，看到回答就成了。注意最后两行——这是我强烈建议你第一天就加上去的，永远打印 token 用量，后面我会讲为什么。
1 | npm install @anthropic-ai/sdk |
hello.mjs：
1 | import Anthropic from "@anthropic-ai/sdk"; |
node hello.mjs。
按出现频率排：
401 Unauthorized：key 错了。检查环境变量是不是真的生效了，有没有多余的空格或引号。最常见是 Windows 下 SetEnvironmentVariable 之后没重开 terminal。
429 Too Many Requests：限流。免费账号和刚加付款方式的账号初始限额很低。查 Anthropic console 里的 Limits 页面，看你当前等级。等几分钟重试，或者充值提升等级。
400 Invalid Request：参数有问题。最常见是 model 名字写错（比如写成 claude-4.6-sonnet 这种倒过来的），或者 max_tokens 忘了填，或者 messages 里 role 不是 user/assistant。错误返回 JSON 里通常会告诉你具体哪个字段有问题，认真看一眼。
500 / 529：Anthropic 自己的问题或者过载。重试，或者上 status.anthropic.com 看看。
ConnectionError：网络问题。国内访问需要稳定的出口，不然会很痛苦。
讲几个官方文档写了但你不读就发现不了的事：
输出比输入贵 5 倍。Sonnet 4.6 输入 3 美元/百万 tokens，输出 15 美元/百万 tokens。意思是你生成 1000 字的成本比你输入 1000 字高得多。所以如果你在做”让 Claude 大段生成”的任务，成本主要在输出端。我有个朋友第一周账单爆了，就是因为他让 Claude 一次性生成 30K tokens 的长文，一天 200 次。
缓存 tokens 单独计费，但便宜很多。同一段 prompt（比如系统提示词）重复用的时候，Anthropic 允许你缓存它，缓存命中的 token 只收 10% 的价钱。我在这篇 prompt caching 深度指南里写得很细，如果你的系统 prompt 长、且重复调用——比如 RAG、客服 bot、Agent workflow——一定要配置它，能省 60% 以上。
**max_tokens 不是”期望输出”是”最多输出”**。但你设 8000 和设 200 的成本差异只体现在实际生成了多少——没生成的不收费。所以设大点没事。但如果你不设限，模型可能真的给你写 8000，一次把你一天的预算吃光。
batch API 打 50% 折扣。如果你不需要实时响应、可以异步等几小时，用 batch API 价格直接砍半。批量跑总结、分类、翻译这种活非常适合。
第一个请求跑通之后我建议你做三件事：
一是把 print(response.usage) 这行代码作为永久习惯留着。成本意识是用 API 的第一课。
二是去试试 streaming 模式（client.messages.stream(...)），用户体验完全不一样。
三是搞清楚 Claude 的三档模型价格差异，按任务选型——三档选型这篇我详细写过。
想系统学 Claude？
跑通 API 之后，强烈建议立刻学prompt caching 深度配置，这是省钱的第一优先级。想搭真正的产品，Agent SDK 架构设计这篇从 0 讲到可上线。想知道什么时候该用 API 什么时候用桌面端，四个入口对比能给你清晰答案。
但我发现大多数人花时间在 input 优化上 —— 裁 context、上 cache、压 system prompt。这些都对，但 output 这侧的水更深，因为它更难控制。input 写多少你心里有数，output 让模型自由发挥，它能给你水出一篇小作文。
我有个客服自动回复项目，去年 11 月月账单 $3,124。当时 input 部分已经做过 cache，死活压不下来，后来定位才发现瓶颈在 output：平均每次回复 412 token。优化了三个月做到 168 token，月账单 $1,287。下面这三招就是当时试出来的。
最有效的一招。
未约束的输出 vs 强 schema 输出，差距能到 2-3 倍。举个例子，我问 Claude「这个工单属于什么类别」，放开让它回答，它会给我：
好的，让我来帮您分析一下这个工单。从描述来看，用户主要反映的是登录异常的问题，具体表现为……（省略 300 字）……所以我判断这个工单应该归入「账号与登录」类别。希望这个判断对您有帮助。
317 token。
改成 tool use，schema 里只允许 {"category": "account_login" | "billing" | ...}。返回：
1 | {"category": "account_login"} |
11 token。
差 29 倍。当然这是极端例子，一般业务场景没这么夸张，但 3-5 倍差是普遍的。
实操上用 tool_use 比让模型输出 JSON 字符串更稳。tool_use 底层有 constrained decoding 兜底，输出一定符合 schema。JSON Schema 输出控制 那篇里有详细写法。
需要注意：schema 里 description 写得越清楚，你能把输出项压得越少。我一开始 schema 里塞了 18 个字段防止模型漏，后来发现其中 6 个是冗余的（比如 is_urgent + urgency_level 一起有），砍掉之后 output token 又降了 22%。
这招知道的人不多但很硬核。
prefill 是在 assistant 回复开头先写几个字，模型接着写。stop_sequence 是匹配到指定字符串就停。组合起来能把格式锁死。
举例：我要 Claude 生成一段简短的邮件正文，不要开场白不要结尾。
普通 prompt 写法：「请帮我生成一段……邮件正文，不要开场白，不要结尾。」模型会回「好的，以下是邮件正文：……」然后还是给你开场白。
prefill 写法：在 assistant 消息里预填 <email>，stop_sequence 设成 </email>。模型必须在这对标签里写正文，写完主动停。
实测一个营销文案生成场景，普通写法平均 289 token，prefill + stop 之后平均 156 token。省 46%。
另一个妙用是中断啰嗦的 CoT。有时候你不想要 chain-of-thought，想直接答案，但模型忍不住要先 “Let me think about this…”。prefill 一个 The answer is: 就能跳过整个思考过程，直接出答案。这招对简单分类任务特别好用。
两段式。Haiku 负责产出大量内容，Sonnet 负责挑刺和精修。
单 Sonnet 跑一个营销邮件写作任务：平均 input 2.4k + output 540 token = $0.0153 一次。
改成两段：
单次只省 8%，看起来不多。但有意思的是，Sonnet 精修版的质量评估分比直接 Sonnet 写的高 11%（我做了一组 200 条的人工评分），因为草稿给了 Sonnet 具体的改进对象，比从零开始更容易产出好结果。
更进一步，如果你接受「60% 的请求用 Haiku 草稿就够好了，不需要精修」，做一个质量判官（也用 Haiku 跑 $0.0003 一次），整体成本能降到 $0.0068 一次，省 55%。
这套思路的深入玩法可以看 Haiku 路由降本，里面讲了更完整的多模型协作策略。
最简单但被低估。
system prompt 里加一句：「直接输出答案，不要任何开场白、解释、注释、寒暄、总结。禁止使用’好的’、’当然’、’希望对您有帮助’等礼貌用语。」
实测效果：同样一批客服回复任务，加前平均 412 token，加后平均 287 token，省 30%。
为什么有效？因为 Claude 4 系列被 RLHF 训得很客气，默认会加缓冲语。你得明确告诉它不要。
需要 pair 一个 few-shot 示例才稳定。我的 system prompt 里会放两三个 good example，每个都是冷冰冰的直接回答，没一句废话。模型看见之后会 mimic 这个风格。
把上面几招叠起来，我那个客服自动回复项目的优化路径：
基线（11 月）：412 token / 次，$3,124 / 月。
累计从 412 降到 168，省 59.2%。月账单 $3,124 降到 $1,287（按调用量不变算）。实际同期调用量还涨了 14%，所以真实账单是 $1,468，相比去年同期的 $3,562，省 58.8%。
最后必须说一下。不是所有场景都该压 output。
我的判断标准：先看业务指标（用户满意度、转化率、准确率），output 压缩之后这些指标如果掉超过 2%，立刻停止压缩。省钱不是目的，单位美元产生的业务价值才是。
另外，有些场景看起来 output 长，其实是因为 input 没给够。比如让 Claude 总结一段文档，它不得不重复复述原文。如果在 prompt 里先告诉它文档主题和重点，它就能抓重点写，输出自然短。这属于 input 侧花小钱省大钱，比硬压 output 聪明。
这三招（加 bonus 那招）我现在是每个新项目上线前都要过一遍的 checklist。花半天时间，省的是整个项目生命周期的 API 费用。
output token 这事的核心认知是：Claude 默认倾向于「说够说透」，你得主动告诉它「够了、停」。工具、prompt、schema 都是在实现这个「停」。
我在他们公司蹲了一周，亲眼看到以下场景：
典型的「工具都有，但链路不通」。我的任务是做一个 Agent，让业务人员直接用自然语言问问题。
第一版我想得挺简单：业务问题 → 丢给 Claude → 生成 SQL → 执行 → 返回结果。经典的 Text2SQL。
拿到他们数仓文档一看我就懵了：47 个业务域、1283 张表、超过 2 万个字段。
光把核心表的 schema 拼成 prompt 就 340K token，还没算字段注释、业务口径说明。context window 直接炸。
我第一反应是「那就塞个最相关的 schema」，但问题是：业务问问题的时候，他自己都不知道哪张表最相关。他问的是「这个月 A 客户订单情况」，背后可能涉及订单表、报价表、合同表、发货表、回款表五张主表，外加十几张维度表。
这个时候我才意识到，这不是一个 Text2SQL 问题，这是一个多阶段工程问题。
改版之后整个链路变成四层：
层一：业务域切分 + schema 检索
把 1283 张表按业务域切分成 47 组（销售域、生产域、采购域、财务域、仓储域……）。每个域做一份「schema 摘要」，包含这个域的核心业务概念、关键表、常用字段、业务口径。
用户问问题进来，先让 Claude 判断「这个问题涉及哪几个业务域」，然后只把这几个域的 schema 摘要注入 context。如果涉及具体表，再做二次检索拉详细字段。
这个思路其实就是分层 RAG，Context 检索与 Rerank 里有讲过类似的分层检索模式。
层二：SQL 生成
拿到相关 schema 之后，让 Sonnet 生成 SQL。这里我做了几个约束：
sql、dialect、tables_used、assumptions 四个字段（参考 Prompt JSON Schema）assumptions 字段必须列出所有歧义假设（比如「我假设『毛利』是指销售毛利，不含税费」）层三：验证执行
SQL 生成完不直接执行，要先过三道：
LIMIT 100 跑一次，让 Claude 判断结果是否合理（比如金额字段全是 0 明显不对），合理才放大查询第一版没这些保护，有次一个业务员问「过去三年所有订单明细」，直接生成了个 SELECT * FROM order_detail 全表扫描 3.7 亿行，平台告警打爆我的 Slack。
这个坑是上线一个月之后才发现的。
业务副总问：「上季度哪个型号毛利下滑得最狠？」
我的 Agent 返回：
1 | 型号 A：毛利率 23.4%，环比下降 8.7% |
副总看了一眼：「我知道 A 下滑了，我问你为什么。」
我当时就懵了。业务人员问「下滑得最狠」的潜台词是归因，不是 ranking。他要的是：「A 型号 Q1 毛利下滑 8.7%，主因是原材料涨价占了 5.2 个点，另外是华南区域打折促销占了 2.8 个点。」
这是一个多步分析任务，不是单次 SQL。
改版我加了一个「归因层」：
归因这一层必须用 Opus，Sonnet 做出来的归因经常是罗列数字，缺深度推理。这里的取舍思路我写过 CoT vs Direct，归因分析必须走 CoT。
上线三个月的数据：
BI 团队的角色也变了。原来 8 个人疲于奔命做需求，现在改成：
BI 经理跟我说：「终于有时间做正经事了。」
拉了 3 月数据：
平均单次业务问题 $0.027。相比人工处理一条需求的成本（估算 380 元/条，含 BI 工程师工时），降幅超过 99%。
Prompt caching 在这个场景特别有效。47 个业务域的 schema 摘要是固定的，我把高频的 12 个域的 schema 全部做 caching，命中率 78%，省了接近一半的 prompt 成本。具体配置可以看 Prompt Caching 深度指南。
坑一：口径不统一。「销售额」在销售部门指含税销售额，在财务部门指不含税。第一版 Claude 经常用错口径。后来在每个业务域摘要里加了「口径字典」，SQL 生成前强制注入。
坑二：业务术语。「毛茬产品」「粗加工件」「头批料」这些词在 schema 里根本不存在，但业务张口就来。我做了个业务术语 → 字段映射表，问题里出现业务黑话时先做转译。
坑三：时间歧义。「上季度」对财务是自然季度，对销售是考核季度（他们的销售考核季是 3 月 1 日到 5 月 31 日这样错位的）。必须在 prompt 里明确时间语义。
坑四：权限。财务数据不是所有人能看，原来 BI 平台靠列权限控制。Agent 得把用户身份透传下去，SQL 生成时带上权限过滤条件。这块涉及一些安全边界，可以参考 MCP Security Best Practice 的思路。
Q3 准备把可视化这块集成进来。
先说个直观感受。人类聊天为什么不会失忆？因为我们有工作记忆（几秒到几分钟）、短期记忆（几小时到几天）、长期记忆（几年）。每种用不同的脑区，有不同的编码方式，大脑自动做 routing。
LLM 没有这套。它每次推理就是把你给的 context 从头到尾读一遍，context 之外的东西对它来说不存在。所以”长期记忆”在 LLM 语境下其实是假命题——你是在工程层面伪造记忆效果。
伪造的方式大概四种，我一种种说。
最简单，把过去所有对话直接拼在一起喂进去。Claude 200K 窗口，理论上能塞几百轮对话。
适用场景：对话轮数少（< 30 轮），单次会话不跨天，不需要跨会话记忆。
隐藏成本：token。每轮的 input 都在涨，到 50 轮一次调用 80K input 是常态。Claude 的 input 定价 3 美刀/百万 token，80K 一次就是 0.24 刀。一个用户聊一小时就是几刀。
我踩的坑：2024 年做了个宠物健康咨询 bot，没做记忆压缩，直接全塞。上线第二天有个用户聊了 120 轮，最后一次请求 142K token。甲方看账单的时候脸都绿了。最后连夜上了摘要机制。
一句话结论：demo 阶段和轻量场景够用，上生产必翻车。
思路是：对话超过一定长度后，把早期部分压缩成摘要，保留近期原文。比如前 30 轮压成 500 字摘要，然后把最近 10 轮原文接上。再过 10 轮，就把原本的摘要 + 新的 10 轮再压一次。
适用场景：长对话但不需要精确引用细节，比如陪伴类、咨询类。
隐藏成本：信息损失是复利式的。每一次再压缩都在摘要的摘要基础上做，到第五六次迭代的时候，最早的对话已经面目全非。
我踩的坑：给一家心理咨询平台做 AI 倾诉对话。前 20 轮用户讲了自己的童年经历——一个具体的、对她很重要的细节。第一次摘要的时候这个细节被保留了。第四次摘要的时候这个细节被合并进了一个”用户有不愉快的家庭记忆”的笼统描述。后来用户在第 60 轮又提起这个细节，AI 回复”嗯，听起来挺难的”——因为它真的不知道了。用户当场崩溃。
那之后我做摘要会显式指令保留这些：具体人名、地点、日期、金额、医疗/法律相关的细节。不管压缩多少次都不能丢。
一句话结论：必须配合”重要 entity 白名单”机制，不能傻滚动。
把历史对话写入向量库或者结构化数据库，下次需要的时候检索回来。这是大部分生产级 agent 的做法。
适用场景：跨会话、跨天、跨用户的长期记忆。比如”这个用户三个月前提到过他的过敏史”。
隐藏成本：
第一，存什么是个大问题。不能把每一轮对话都存——太多了，检索的时候召回质量反而下降。我现在的做法是每轮对话后跑一个小任务（用 Haiku），判断”这一轮有没有产生值得长期记忆的 fact”，有的话抽成结构化条目再入库。
第二，检索时机。每次用户说话都做一次记忆检索？太贵。我的做法是：只有在 Claude 需要的时候才触发——在 system prompt 里告诉 Claude 它有个 recall 工具，需要回忆的时候自己调。这样大部分对话不触发检索。
第三，记忆冲突怎么办。用户三个月前说自己不吃辣，今天说想尝尝辣的。两个 fact 都在库里，检索回来了，模型懵了。我现在给每个记忆条目加时间戳 + confidence score，检索时按时间衰减 + 用户显式更新的优先级处理。
我踩的坑：最开始没做冲突处理，一个电商客服 bot 把用户”已经取消订阅”和”刚下单”两个 fact 同时召回。模型给出的回复自相矛盾，被投诉到客户那边。
一句话结论：现在做 agent 的主流选择，但工程量比想象大。关于怎么在 CLAUDE.md 里管理长期知识也是类似思路。
这是最工程化的方案。把每轮对话当做 event 存成时间序列，需要重建 context 的时候根据 query 回放相关 event。
和方式 C 的区别是：C 存的是抽象过的 fact（”用户过敏花生”），D 存的是原始事件流（”2026-01-15 14:30 用户说：我小时候吃花生起过疹子”）。
适用场景：对审计、可追溯性要求高的场景。金融、医疗、法务。还有就是你不确定未来要怎么用这些数据、不想过早抽象的时候。
隐藏成本：回放逻辑复杂。你要写很多”从事件流构建 context”的代码。而且存储成本线性增长，一年数据能到几十 GB。
我踩的坑：给一家医疗公司做随访 AI，用了事件溯源。前半年很爽，数据都留着，随时能追溯。问题在第八个月——单个患者的事件已经到几千条，每次回放都要过滤排序，latency 爬到 4-5 秒。后来加了”压缩快照”机制，每 100 个 event 生成一个中间快照，回放时从最近快照开始。这事儿其实就是借鉴了 event sourcing 里的 snapshot 模式。
一句话结论：大厂或者强监管场景才用得上，中小团队别碰。
最后给个我现在给中型项目用的默认架构，规模大概对标日活 10 万、单用户平均 30 分钟会话。
1 | ┌─ 近期原文（最近 8 轮） |
几个实现要点：
第一，摘要是异步的，不阻塞当前对话。用户发完消息，直接用近期原文 + 现有摘要拼 context。摘要更新在后台跑。
第二，fact 抽取用 Haiku 4.5，prompt 里明确要求结构化输出（见 XML 标签），包括 fact 类型、confidence、过期时间。
第三，主模型用 Sonnet 或 Opus，通过 tool use 主动调用 recall。具体工具定义和 MCP 结合可以看 MCP vs Function Calling。
第四，每 50 轮对话跑一次”记忆整理”——合并重复 fact、标记过时 fact、提升高频 fact 的权重。这个灵感来自人类睡眠时的记忆巩固。
跑了七八个月，200 轮以上的长会话测下来”还能记得早期重要信息”的比例 87.6%，比最朴素的方案 B 高了 30 多个点。
所有记忆方案都绕不过一个灵魂问题：这个”记忆”到底属于谁？
用户以为 AI 记住了他说的话。但底层可能是向量库里的几条 embedding，跟他想象的”AI 在关心我”差距很大。一旦产品把”长期记忆”做成卖点，就要对用户的期待负责——包括遗忘权、导出权、修正权。
这不是技术问题，是产品伦理问题。但做技术的人最好一开始就想清楚。
延伸阅读
长期记忆的 fact 抽取和 recall 都离不开 tool use，强烈建议读 [MCP vs Function Calling](/posts/mcp-vs-function-calling/)。如果你还想把记忆机制做得更模块化，[Skills 深度解析](/posts/skills-deep-dive/) 里有 Anthropic 官方的思路。压缩对话历史这一块后面有专门一篇讲 3 种策略 AB 对比。
刚用 Agent SDK 那会儿，我对 session 的心智模型是这样的：一个 session 就是一坨对话历史的 JSON 数组，保存在 .claude/sessions/<id>.json，resume 的时候把它塞回 messages 参数继续聊。
简单直接对吧？但这个理解挪到实际场景里全是问题。
第一次撞墙：我让 agent 修改了一个文件，然后中断 session。下次 resume 的时候它突然说”我刚才已经把 config.ts 改成 xxx 了”，但那个文件我在中断后手动改回过。agent 的说法和现实不一致，它给出的建议全是基于一个过时的世界模型。
第二次撞墙：我并行起了两个 session，一个让 agent A 重构 auth/ 目录，一个让 agent B 重构 db/ 目录。跑着跑着发现 agent B 突然开始改 auth/ 的文件。我以为是工具权限没隔离好，查了半天才发现是 session 之间有上下文泄露。
这两次之后我去翻了源码，才对 session 有了靠谱的认识。
Agent SDK 的 session 文件远不止对话历史。我把一个中等规模的 session 文件扒开看过，里面大致有这几块：
一个跑了 2 小时的 code review session，文件大小大概 47MB。跑了 4 小时的代码迁移任务，file snapshot 部分膨胀到 83MB。
明白了 session 存了什么，第一次撞墙的那个现象就解释清楚了——agent resume 时会基于 filesystem snapshot 判断”我改过什么”，但它不会去实际读磁盘比对。我在中断期间手动改回文件，这个信息 session 无感知。
SDK 其实有两个恢复命令：resume 和 continue。官方文档我粗读过几遍，一直没搞清楚差别。后来自己做了实验才弄明白。
continue 是从最新 checkpoint 接着跑。checkpoint 是 session 运行过程中定期保存的”当前完整状态”。continue 等于说”这个 agent 刚才在干活，打了个盹，现在接着干”。
resume 是从头回放 session。它会读所有 messages，重新让 Claude 回答一遍——区别是 Claude 看到完整历史之后，再继续新的对话。resume 适合”这个 session 我之前结束了，现在想基于它的上下文继续问问题”。
两者的一个关键差异：continue 保留 filesystem snapshot，resume 不保留（会重新基于当前磁盘建立快照）。所以手动改过文件后应该用 resume，而不是 continue。这是我第一次撞墙的教训。
第二次撞墙让我学到 session 隔离没想象中那么彻底。
我并行跑两个 agent，分别用两个 session。默认情况下它们共享同一个 .claude/ 目录，包括 hooks/、agents/ 配置、甚至 MCP server 的连接池。
具体是怎么污染的？我后来复盘发现：
.claude/shared-state.json 写了当前正在处理的文件列表auth/，就”帮忙”处理 db/ 以外的东西……但我给 B 的 prompt 本来只让它改 db/根本原因是我的 hook 实现不对，没做 session 隔离。但 SDK 默认也没强制这个——它给你的是共享目录，你自己要用 session id 做 namespace。
解决方式：所有涉及共享状态的 hook，key 都加 session id 前缀。或者索性每个 session 用独立的工作目录（CLAUDE_AGENT_SESSION_DIR 环境变量能覆盖）。
这个事儿挺惨的。
当时我正在清理一个项目仓库，因为 .claude/ 目录整个被 .gitignore 了，我本地又装了 4 个不同 agent 的临时 session（累计 1.2GB），就顺手 rm -rf .claude/sessions/。
结果是当天下午我要演示一个客户 demo，那个 demo 依赖一个跑了 40 分钟的 session——里面有 agent 分析客户代码之后建立的整套 mental model。演示前 30 分钟我想 resume，发现 session 全没了。我当时直接懵住。
后来的 debug 流程：
rm -rf 走的是直接删除）演示凑合过了，但一身冷汗。
这件事的教训有几条。第一，session 目录要主动备份，至少一周一次。第二，生产环境的 session 目录最好挪到工作目录外（用 CLAUDE_AGENT_SESSION_DIR=/data/agent-sessions 这种），避免被项目清理脚本误伤。第三，session 里的上下文本身是资产，跟代码一样值钱。
踩完坑之后，我反过来把 session 的特性用在一个场景上——增量 code review。效果挺好，写出来分享下。
场景：我们仓库每天有 40+ PR，一个 reviewer agent 跑一次要十几分钟（要加载代码、构建依赖图、分析）。如果每个 PR 都从零起 session 太慢。
我的方案：
resume 起一个新 session，继承那个 snapshot 的上下文。然后只把 PR 的 diff 喂给它。关键点是 resume 能继承完整的对话历史和 filesystem snapshot，让 agent 不用重新加载整个仓库。
这套方案的 context 管理 我在另一篇里展开过。
CLAUDE_AGENT_SESSION_DIR 支持相对路径但会基于 agent 启动时的 cwd，容易混淆，建议用绝对路径。session 这块儿看起来是个细节功能，但它其实是 Agent SDK 区别于”调 API 写 agent loop”的核心设计之一。理解它才能理解 Agent SDK 为什么这么组织代码。
误解它的代价就是我这两次撞墙的学费。希望看到这篇的人不用再交一遍。
“我们 staging 库一张 order_log 表没了，就刚才的事。Claude Code agent 调了咱们搓的那个 db_query MCP tool，不知道怎么执行了 truncate。”
那张表 21.4K 行，虽然只是 staging，但包含了 QA 组两周的测试数据。复盘完之后我整理了一套 MCP server 安全检查清单，现在我们团队所有 server 上生产前必须过这 6 项。
这篇没有理论，全是踩坑换来的。
先讲清楚那次怎么翻车的，后面的检查项才有上下文。
那个 db_query MCP tool 原始设计：
1 | { |
连接的是 staging 数据库的 read-write 账号。工程师 A 给 LLM 发了个需求：”帮我看下 order_log 表最近一周有多少行被标记为 test_data”。
LLM 的操作链：
db_query 跑了 SELECT COUNT(*) FROM order_log WHERE tag='test_data'，返回 17 行db_query 跑 DELETE FROM order_log WHERE tag='test_data'TRUNCATE TABLE order_log工程师 A 盯着另一个窗口写代码，10 几分钟后才反应过来。
事后我们 review 了这个决策链，LLM 的每一步”单独看”都不离谱，合起来就是灾难。问题出在：tool 的权限边界过大 + 没有 dry-run + 没有限流 + 审计缺失。
最基础但最容易漏。LLM 传过来的 tool 参数是不可信输入，必须校验。
上面那个 db_query 最起码应该：
1 | const SqlSchema = z.object({ |
或者更狠一点，直接只允许 SELECT：
1 | .refine(s => /^\s*SELECT\b/i.test(s.trim())) |
写 MCP tool 的时候脑子里要有这个模型：你不是在写 API，你是在给一个会自由组合 tool 的 AI Agent 开权限口子。Agent 会以你想不到的方式组合调用。
见过太多次 claude_desktop_config.json 里直接写 API key。文件不加密、可能被同步到 iCloud、被误 commit 到 git。
正确做法：
env 字段 + 系统 keychain（macOS）或 DPAPI（Windows）MCP server 启动流程应该是这样：
1 | const dbUrl = await fetchSecret("prod/db/readonly-url"); |
另外一个容易忽略的：MCP server 的 tools/list 返回给客户端的 description 里不要包含任何环境信息（”连接到 prod-us-east-1 的 xxx 集群”），这会经过 LLM、可能被日志到 Anthropic 侧。
这是那次事故之后我们组的硬性规定。
一个 MCP server 只承担一种权限级别：
company-db-readonly：只连 read-only DB 账号、只有 SELECT toolscompany-db-readwrite：独立 server，连 RW 账号、提供 INSERT/UPDATE tools（不提供 DELETE/TRUNCATE）company-db-admin：独立 server、独立审批流程、默认不启用用户要用到高权限 server 时，在 config 里显式启用。LLM 永远看不到 admin tools 除非用户主动开。
这个设计的额外好处是：你可以在 Claude Code 的 .mcp.json 里按项目控制——开发项目只挂 read-only、运维项目才挂 read-write。配合 Claude Code 权限沙箱 里的二级保护，基本不会出大事。
事故那次最抓狂的是：我们花了 40 多分钟才定位是哪个 tool 哪条 SQL 干的好事，因为没有统一日志。
正确的审计结构，每次 tool call 至少记录：
1 | { |
关键字段：
args_hash 而不是原文（避免日志泄露敏感参数）user_hint 从 MCP client 侧传过来（很多 MCP 客户端支持带用户上下文）duration_ms 方便发现异常日志存到公司统一日志平台，保留 90 天起步。出事了至少能查。
Agent 一跑起来可能一分钟调你 tool 几十次，这在人类 API 用户那边几乎不可能。
我见过最离谱的一次：某客户的 Claude Code agent 接了个 Slack MCP server，写代码的时候 stuck 住、反复调 list_channels 去”探索环境”，11 分钟调了 2847 次，把公司 Slack API quota 直接干穿了，整个公司 Slack bot 半小时不能用。
两层防护：
server 侧：每个 tool 按 session+tool 组合限流，比如 60 次/分钟。超过直接返回错误让 Agent 退避。
1 | // 简化伪代码 |
下游 API 侧：给 MCP server 配独立的 API key、独立 quota，爆了只影响 Agent 场景不影响业务。
MCP 火是 2024 年底的事，整个生态还很年轻。到 2026 年 4 月 npm 上 MCP 相关包有 840+ 个，但质量分布极其分散。
我扫过一次：top 100 包里 23 个有已知中高危漏洞（npm audit 高或严重），17 个最近 6 个月没更新，9 个连 README 都没有。
上生产前必须做的事：
npm audit 跑一遍，高危必须修socket.dev 这类 supply chain 工具扫Python 生态同理，pip-audit 跑一遍。
我们团队现在每个 MCP server 上生产前对照走一遍：
1 | [ ] 所有 tool 参数都有 zod/pydantic 校验 |
9 项都过了才放生产。
另外强烈推荐搭配 Claude Code 权限沙箱 做运行时隔离——哪怕 MCP server 本身有 bug，沙箱能兜住。两层防护比一层可靠得多。
那次事故之后客户问我：”你们早怎么不告诉我这些？”
我说：”说实话，MCP 生态起来才一年多，很多坑是我们自己也刚踩的。”
这篇文章写出来，就是希望下一个踩坑的人不是你。如果觉得有用，分享给团队一起看看。
上线一个月后我想着优化一下，加了 <thinking> 让模型”先分析问题意图再选择答案”。心想这肯定更稳吧，结果一跑——84%。
整整掉了 8 个点。我反复看了很多 case 才搞明白：这类任务本质上是”语义相似度召回”，模型在 embedding 层面其实已经做对了判断，你硬让它”逐步推理”，它反而会被自己推出来的中间结论带偏。
这事给我上了一课。CoT（Chain of Thought）不是越多越好，更不是万能。这篇说一下我现在怎么判断。
先说有用的场景。我经验里 CoT 确实能显著提升效果的几类任务：
一、数学和数值推理。不管多简单，只要涉及”一步算错全盘错”的计算，让它一步步来就对了。实测一个三步应用题，直接问正确率 73%，加 <thinking> 后 94%。这个提升是稳的。
二、多跳问答。“根据 A 文档里的 X 和 B 文档里的 Y 推出 Z”这种。模型需要先把中间结论落到纸面，不然容易幻觉。
三、合规 / 规则判断。比如”判断这份合同是否违反下面 7 条规则”。你不让它一条一条过，它会漏。让它显式地说”规则 1: 符合；规则 2: 不符合，因为…”准确率直接上去。
四、复杂决策树。客服分流、工单分类有 20 多种类别且存在嵌套层级的时候，CoT 能让模型稳得多。
这些任务的共同点：有可拆分的中间步骤、有客观验证路径、犯错代价高。给它展开的空间，它会自己纠偏。
这些是我踩过坑的：
一、纯召回 / 纯匹配任务。像我开头说的那个 FAQ 项目。模型其实一眼就知道答案，你让它”分析再选”是在给它添乱。
二、简单分类。三到五个类别、边界清楚的那种。加 CoT 会让模型过度理由化——“这条评论包含了正面情绪但也有一丝失望所以应该是…”结果越想越歪。直接判断快又稳。
三、创作 / 生成任务。让它写一个故事前先 <thinking> 梳理一下人物？没必要。创作是发散的，强行收窄到”先想后写”反而让输出变得程式化。
四、高吞吐短响应场景。API 客服实时应答，延迟要求 500ms 以内，你加一段思考就是 500+ tokens 的开销，用户体验直接崩。这时候宁可损失 2-3 个点的准确率也要快。
判断逻辑大致是：任务能不能”一眼看出对错”？能的话，CoT 大概率添乱。需要”想一下才能判断对错”的，CoT 才有意义。
<thinking> 标签的正确用法决定要用 CoT 之后，怎么用也有讲究。我看过太多人把这个标签用歪了。
错误用法一：标签里塞”万能咒语”。
1 | <thinking> |
这种写法 Claude 看了基本等于没看。空洞的”请认真思考”对输出没任何指导作用。
错误用法二：要求固定的思考步骤但步骤不匹配任务。
1 | <thinking> |
这种模板如果和真实任务路径对不上，反而在限制模型。比如任务是个简单数值题，它会被迫走”分析用户意图”这一步，浪费 token 还可能走偏。
我现在的写法：任务依赖型，而不是通用型。
合规判断场景：
1 | <thinking> |
数学题场景：
1 | <thinking> |
具体、可执行、紧贴任务。不是给模型”打气”，是给它”操作手册”。
再讲个我印象深的反例。某金融客户要做”判断一条新闻是利好还是利空”。
0-shot 准确率 81%，我觉得还能更高，加了一段：
1 | <thinking> |
测下来 76%。反复看了 case 之后我发现问题：金融新闻的”利好利空”很多时候是情感驱动的市场反应，不是严密因果推理的结果。
你让模型去分析”长期影响”，它经常会推出一个”虽然短期看是利空但长期利好”的结论，结果跟市场真实反应完全相反。真实市场就是看短期情绪，不看你的长期理性推理。
后来我把 thinking 拿掉，改成一条简短的 hint：”从市场短期情绪反应的角度判断”，准确率回到 81% 并稳定在那。
这个教训是：CoT 的前提是任务本身有”可推理”的结构。没有这个前提，你强行推理就是在制造噪声。
Claude 后来出的 extended thinking 模式（就是那个可以看到完整思考链、token 消耗翻倍的那个）我也用过不少。
值得开的场景：
不值得开的场景：
成本上，extended thinking 的 token 消耗能达到常规的 2-5 倍。我自己项目里的原则是：能用 Sonnet 常规模式解决的事，不开 thinking；必须开的时候，先用 Opus 试，效果 OK 再考虑降级。Claude 家族那篇里有更细的模型选型讨论。
还有个细节：extended thinking 模式下，prompt caching 的表现和常规模式有些差异，具体的我在缓存深度指南里提过。
简化一下我现在的判断流程：
顺便说一句，CoT 和 few-shot 不是互斥的。有时候我会写 3 条带 thinking 过程的示例，让模型学会”怎么思考”。这种组合在复杂推理上特别猛。few-shot 的数量和顺序我在另一篇里细讲了。
CoT 这个东西，两年前大家吹它是灵丹妙药，现在业内已经慢慢意识到它是一把双刃。用对了提升显著，用错了不但浪费 token 还损失精度。
核心就一句话：不是所有问题都需要”想一下”才能答。你问一个人”1+1 等于几”，他想 30 秒再回答你，你反而怀疑他是不是有啥毛病。模型也一样。
延伸阅读
CoT 和 few-shot 怎么组合，看 Few-shot 的 3/5/7 法则。开启 extended thinking 前的模型选型，去 Claude 家族 Haiku/Sonnet/Opus 那篇。thinking 模式下的 token 优化，看 Prompt Caching 深度指南。