这行字值得读三遍的地方在于，正式版和四月的预览版是同一个模型：总参数 284B、激活参数 13B，结构、尺寸都没变，只是重新做了后训练。一个 Flash 档位的轻量模型，靠重练「怎么干活」而不是「更大的底座」，在九项 Agent 基准上全线超过自家的 Pro 预览版。

更微妙的是时间线。7 月 24 日，deepseek-chat 和 deepseek-reasoner 两个老接口静默停用，所有流量在那之前就已经指向 deepseek-v4-flash。也就是说，在「正式」官宣之前，新模型已经在真实流量里跑了一周多，等 bug 被真实请求消化掉，再补一个正式标签。先灰度、后官宣，这件事本身就是这次发布最工程化的注脚。

斩杀线是怎么画出来的

「斩杀线」这个词来自 Artificial Analysis 那一类价格-性能坐标图：横轴是每百万 Token 的输出成本，纵轴是综合智能指数。V4-Flash-0731 拿到 50 分，比自家 V4-Pro 高 6 分，比 GPT-5.6 Luna 的 51 分低 1 分；输出价格是 $0.28/M，Luna 是 $1.2/M。社区流传的那句话是：「Codex、Claude 定上限，DeepSeek 定斩杀线。跟它持平没溢价，落后它就出局。」

图 1：斩杀线是价格-性能坐标系里的前沿。落在它右下角的模型，要么更弱，要么更贵。点位为公开报道口径的示意位置。

数据确实在支持这个说法。OpenRouter 周度调用量登顶；有编程工具厂商称发布当天平台使用量和新订阅都涨了约三成；几家海外初创把推理切过去之后，月推理成本降了六到八成。时间点也带着火药味——OpenAI 在发布前一天刚把 GPT-5.6 Luna 的 API 价格砍了 80%，第二天评论区就贴满了对比图。

但有一个前提值得单独说清楚：斩杀线是「价格-性能」坐标系里的线，坐标系本身是评测机构和媒体画的。它量的是单次任务的性价比，不是生产环境里的可靠性。它不包含你的仓库、你的工具链、你的验收口径。斩杀线是一条市场意义上的线，不是工程意义上的线。

这轮降价为什么不是价格战

如果只看「便宜」，很容易把这次发布理解成又一轮价格战。真正的信号藏在三个工程细节里。

第一个细节是 98% 的缓存命中折扣。缓存命中的输入只收 $0.0028/M，未命中是 $0.14/M，差 50 倍；行业通行的缓存折扣在 90% 左右。这不是慷慨，是对 Agent 工作负载结构的理解：系统提示词、工具定义、前几轮对话历史，每一轮都在重复发送，缓存命中对 Agent 场景来说不是优化选项，而是负载的内建属性。敢把折扣放到 98%，说明官方对命中率有很强的把握——否则这是自杀式定价。单任务成本比已经降价 80% 的 Luna 还低约 60%，关键就来自这里。

第二个细节是峰谷定价预告。定价页上写着：高峰时段（北京时间 9:00–12:00、14:00–18:00）所有计费项按两倍收取，生效时间以正式通知为准。推理负载有明显的潮汐，需要价格杠杆削峰填谷——这说明规模化运行的成本结构是真实的。「把批量任务排到夜间」很快会从省钱技巧变成基本常识。

第三个细节还是那条 changelog 本身：老接口按时停用，新模型先用 preview 标签消化真实流量，再正式宣布。回看 4 月 24 日预览版上线时预告的「三个月后停止维护」，一切都是按时发生的。灰度发布、按时切换、预算写进价格——这是运维纪律，不是营销。

可靠性提升是真的，但要看清它测的是什么

官方放出的九项基准全部上涨，每一项都超过 V4-Pro-Preview：

DeepSWE 从 7.3 涨到 54.4 是最值得看的一行。它考的是「把真实 GitHub issue 变成通过测试的补丁」：模型在仓库里自己读代码、写改动、跑测试、失败再试。这类分数描述的不是单次回答质量，而是多步任务的完成率。可靠的 Agent 和会聊天的模型之间的分界线就在这里——任务能不能执行到底，失败了会不会带着证据继续找，工具调用是不是稳定。

但三件事必须打折看。第一，这些是官方自测：DeepSeek Harness 的 minimal mode、max effort、特定采样参数，自家框架自家卷子；第二，DSBench 两个指标来自内部测试集，口径不能和公开基准混排；第三，Agent Last Exam 只有 25.2 分——这是业内著名的地狱级卷子，各家普遍在二三十分徘徊，绝对值没有横向意义。

值得交叉验证的是第三方。Artificial Analysis 的智能指数 50 分，比四月预览版高 10 分；Arena 的前端竞技场 1586 分、开放类第三名，比预览版高 154 分。两个独立口径指向同一结论：Agent 能力是真的上来了，不是 changelog 自嗨。但「评测里能交付」和「你的仓库里能交付」之间，还隔着权限模型、工具链版本、验收口径和发布流程——这段沟，工程团队得自己填。

图 2：可靠性来自验证回路：失败带证据重试、超限转人工、结果沉淀为评测集，回灌下一次任务。

AI 具备大规模工业级应用能力了吗

我的判断是：分场景。判断标准有三个——失败成本、可验证性、任务量。

低风险、结果可以自动验收、任务量大的场景，已经具备了。补单测、批量扫描、重复性重构、日志归因，这类工作的完成率已经够用，成本结构也支持铺量：有开发者在知乎说，一个下午跑掉五个多亿 token，账单没花到一杯奶茶钱。这类活以前因为「模型不行」和「太贵」两个原因没进生产，现在两个原因同时消失了。

高风险、语义含糊、失败代价大的场景，还不具备。跨模块排障、架构判断、涉及资金和权限的改动——模型跑分再高，也不是发布审批。这里真正缺的不是模型能力，是验证手段：你能不能为「删除这条用户数据」构造一个可信的验收？不能的话，换哪个模型都不行。

所以「大规模工业级应用」不是模型的属性，是系统属性。我把它拆成四层：

模型层和成本层的进展是 DeepSeek 给的；协议层给了一半；治理层完全是组织自己的事。四层齐了才叫「可采购的服务」，否则只是「很便宜的 API」。顺着这个框架再看网上的两种说法：说「AI 已经可以大规模工业级应用」的，多半只在模型层做判断；说「跑分都是虚的」的，多半没算成本层。两者都只看见了一部分。

接下来该做什么

给团队和给自己的建议都很朴素。

先让它干能验收的活。低风险、结果可自动验证的任务优先迁移，一次只换一个变量：同一仓库、同一任务集、同一套测试，比较完成率、耗时和 token 消耗。生产、权限、资金、安全的改动保留人工 review 和 CI——便宜不改变责任。

成本账盯缓存那行。系统提示词和工具定义保持稳定、可缓存，是省钱的正解；峰谷定价落地后，批量任务排到夜间。另外 Responses API 目前是无状态实现：不支持 previous_response_id，store 恒为 false，对话历史得自己带。协议通了，生态还在早期，接入前先读文档而不是看教程截图。

斩杀线是一条市场线，它的位置由价格和跑分决定，这次被大幅前移了。验收线是一条工程线，它的位置由验证回路和发布纪律决定，它不会因为别人发布了新模型而自动移动。

7 月 31 日那行 changelog 里还带着两句没被足够讨论的话：「V4-Pro 正式版将尽快发布」「峰谷定价具体生效时间以正式通知为准」，再加上大概率会来的开源权重，接下来的变量仍然很多。但无论下一版跑分如何，这次发布把一件此前模糊的事说清楚了：在可验收的低风险场景里，AI 已经从「值得试试」变成了「默认选项」。剩下的，是工程团队自己的事。

参考与数据来源

• DeepSeek API 更新日志与定价页：https://api-docs.deepseek.com/zh-cn/updates
• IT之家：DeepSeek-V4-Flash 正式版跑分报告（Artificial Analysis / Arena 第三方数据）
• 卡码笔记：V4-Flash 正式版上线拆解（基准对比、接入与峰谷定价提示）
• AI 内参：DeepSeek V4 Flash 正式上线与「AI 斩杀线」讨论综述
• 掘金：一行 changelog 里的暗涌（九项基准逐项解读、缓存折扣与接口限制）
• 知乎：DeepSeek V4 flash 正式版发布讨论（开发者实测口径）

这两者的差距，恰好是软件工程最难被压缩的部分。真实仓库里，业务规则通常不在一个文件中：权限来自网关上下文，状态是数据库字段和队列事件共同推导的，旧客户端依赖未写进接口文档的行为，发布还要兼容未完成的数据迁移。Agent 能快速补齐局部实现，却不会天然知道哪些历史约束值得保留。

下面用一个做过匿名化处理的内部任务平台需求说明这套流程。需求表面很简单：在失败任务列表中增加“批量重试”。仓库是常见的 React、Node.js、PostgreSQL 和消息队列组合，前端展示派生状态，服务端负责租户隔离和状态转换，Worker 按至少一次投递消费任务。

如果只按页面文案理解，批量重试不过是多选框加一个循环调用。真正进入生产前，需要回答的却是：哪些失败允许重试，谁有权限重试，处理中任务如何排除，同一任务会不会被重复入队，五十个任务中有三个状态已经变化时返回什么，以及操作是否能被审计。

图 1：Agent 不是从提示直接跳到代码。仓库事实和任务合同共同约束实现，验证证据再交给评审者做最后判断。

先把一句需求还原成状态变化

我不会先让 Agent 写代码，而是让它把需求翻译成业务结果和不变量。批量重试的目标不是“多发几次请求”，而是“操作者能对当前租户内、处于可重试失败状态的任务发起一次可追踪的新执行”。

这句话直接带出五条不能被实现细节稀释的约束：

1. 任务必须属于当前租户，不能相信浏览器提交的 tenantId。
2. 只有 failed 且错误类型允许重试的任务可以进入新一轮执行。
3. 每个任务同一时刻只能存在一个有效执行，按钮双击和网络重试不能重复入队。
4. 批量操作允许部分成功，但必须逐项返回稳定结果，不能只给一个笼统的 200 或 500。
5. 谁在什么时间重试了哪些任务，需要进入审计链路。

任务合同因此会写成业务语言，而不是文件清单：

type RetryBatchContract = {
  outcome: "retry-eligible-failed-runs";
  invariants: [
    "tenant scope comes from authenticated context",
    "at most one active attempt per run",
    "every accepted retry has an audit record",
    "partial failure is explicit per item",
  ];
  limits: { maxBatchSize: 50; maxAttemptsPerRun: 5 };
  outOfScope: ["change retry policy", "redesign run state model"];
};

outOfScope 很重要。Agent 容易发现现有状态模型不够优雅，然后顺手把一次交付变成状态机重构。这个判断可能没有错，但它扩大了审查面，也把能否发布与另一项高风险工作绑在一起。先把需求做对，再单独处理架构债务，通常更稳妥。

第一轮只建立仓库事实，不允许改文件

我会要求 Agent 从用户动作沿调用链向下追，而不是根据文件名随机搜索。这个需求至少需要确认六个位置：列表状态从哪里得到、单条重试入口怎样鉴权、领域层在哪里判断状态转换、队列消息如何生成幂等键、Worker 怎样领取任务，以及相邻测试使用什么构造方式。

第一次探索的交付物是一张很短的仓库地图：

如果 Agent 找到了另一套看似更方便的写法，我会让它先解释为什么现有边界不适用。真实仓库中，局部一致性通常比新抽象更有价值。评审者熟悉的事务模式、错误码和测试夹具，本身就是维护成本的一部分。

探索阶段还要先读取工作区状态。未提交修改不是噪声，更不能为了“恢复干净基线”而回滚。Agent 只拥有本次任务产生的差异；遇到重叠文件时，先理解现有修改，再决定能否安全合并。

变更计划按风险切片，不按前后端目录切片

“先写接口，再写页面”不够具体。我更关心每一步是否能独立证明一个业务事实。这个需求可以拆成四个切片：

1. 为现有单条重试补齐领域规则和反例，固定 canRetry 的语义。
2. 增加批量命令，在一个事务中领取可重试任务、创建 attempt 和 outbox 事件。
3. 定义逐项结果协议，让前端正确表达成功、跳过和冲突。
4. 增加多选交互，并在提交后按服务端结果更新列表，而不是乐观地把全部行改成“重试中”。

这里最值得审查的是第二步。一个常见但不可靠的实现是：先查询任务，再用 Promise.all 循环调用单条重试。查询与写入之间状态可能变化，任何中途失败都会留下难以解释的半成品，数据库成功和消息发送也可能分裂。

更合适的边界是让数据库事务保存新 attempt 与 outbox 事件，提交后由发布器发送队列消息：

WITH candidates AS (
  SELECT r.id
  FROM workflow_runs r
  WHERE r.tenant_id = $1
    AND r.id = ANY($2)
    AND r.status = 'failed'
    AND r.retryable = true
  FOR UPDATE
), attempts AS (
  INSERT INTO run_attempts (run_id, requested_by, status)
  SELECT id, $3, 'pending' FROM candidates
  ON CONFLICT (run_id) WHERE status IN ('pending', 'running')
  DO NOTHING
  RETURNING id, run_id
)
INSERT INTO outbox_events (topic, aggregate_id, payload)
SELECT 'run.retry.requested', run_id,
       jsonb_build_object('attemptId', id, 'runId', run_id)
FROM attempts
RETURNING aggregate_id;

这段 SQL 不是为了炫技。它把三个关键事实放在同一提交点：候选任务仍然符合条件、活跃执行不会重复创建、成功领取的任务一定留下待发布事件。未被领取的 ID 再根据当前状态映射成 not_found、not_retryable 或 already_active，返回给页面。

接口不会只返回一个 success: true：

{
  "operationId": "retry_01J...",
  "items": [
    { "runId": "r-101", "status": "accepted", "attemptId": "a-301" },
    { "runId": "r-102", "status": "skipped", "reason": "already_active" },
    { "runId": "r-103", "status": "rejected", "reason": "not_retryable" }
  ]
}

批量接口的价值不是替前端少发几个请求，而是把并发语义、权限和部分成功放进一个可以维护的领域边界。

给 Agent 的自主权必须和后果匹配

图 2：上下文、变更范围和执行资源都有预算。任何一项超出合同，Agent 都应停下来重新确认，而不是自行扩大任务。

我允许 Agent 自主读取符号、追调用链、修改局部代码、运行测试和整理差异，但不会把所有决定一起交出去。

业务语义仍由人确认。比如“超时失败是否允许重试”取决于外部副作用：任务可能已经向第三方提交成功，只是回执超时。单看数据库状态，Agent 无法判断重试是否安全。

公共协议和数据模型也需要人工承担。它们会影响其他团队和未来迁移，不应因为当前实现方便就改变。生产发布、数据删除、外部通知等不可逆动作，则必须有独立授权。

相反，可逆、局部、已有模式可依循的工作适合让 Agent 连续完成。关键不在于模型能力强弱，而在于错误发生后的影响半径和恢复成本。

验证要能发现“实现和测试一起理解错”

同一个 Agent 根据同一份上下文生成代码和测试，容易形成自洽闭环。测试会证明它实现的规则成立，却未必证明真实规则成立。因此验证来源要刻意分开。

这次变更至少需要五层证据：

并发用例不能只 mock 仓储层。需要两个请求同时重试同一个任务，并验证数据库最终只有一个活跃 attempt、一个可发布事件，另一个请求收到稳定的 already_active。租户用例则用相同 run ID 组合不同认证上下文，确认越界资源不会通过错误信息泄露存在性。

浏览器检查也不是“页面能打开”。我会实际选择一批混合状态任务，触发批量重试，确认按钮在提交期间禁用、逐项结果可见、失败行仍可定位、列表刷新后与服务端一致，并检查最长错误文案和窄屏布局。

交付物不是一句“已完成”

Agent 结束时，需要把结果压缩成评审者能复核的证据包：行为发生了什么变化，复用了哪些边界，哪些命令和场景已经验证，哪些风险没有覆盖，以及如何打开预览复现关键路径。

我更希望看到“并发重试已用真实 PostgreSQL 验证；外部队列故障只验证到 outbox 积压告警，未做灾备演练”，而不是“所有测试通过，功能已完善”。前一种表述给出了证据边界，后一种只是情绪判断。

这也是我使用编程 Agent 后最大的变化。实现候选变便宜了，审查注意力反而更珍贵。工程师需要把时间从逐字符生产代码，转移到定义问题、固定边界、设计独立验证和判断剩余风险。

Agent 可以连续工作很久，也可以比人更耐心地搜索和运行工具。它真正进入真实仓库的前提，不是一次生成更多文件，而是整个过程有可追踪状态、有停止条件、尊重现有工作，并且最终有人能够沿着证据判断：这项变更为什么可以进入生产。

这篇描述的是“Agent 进仓库之后”的工作协议，它的前提是执行环境本身被隔离好了——文件、网络、密钥和资源预算的边界见编码 Agent 的沙箱。评审端的验收标准——意图、不变量、证据与剩余风险——在AI 辅助编程之后的代码评审里提前定好了，这里只是把它们落到了真实仓库。

这种变化在架构工作里尤其明显。过去，一个代价较高的方案可能停留在白板上；现在，几套都能运行的候选可以在一天内出现。选择变多以后，判断质量反而更重要。错误方向不再因为实现困难而自然淘汰，它也可以迅速长成一套结构完整、测试齐全的系统。

我最近重新整理过一个典型案例。一个内部任务平台最初只有 pending、running、success、failed 四种状态。业务发展后，陆续增加人工审批、暂停、取消、外部系统回调和失败补偿。团队提出“升级成标准状态机”，AI 很快给出了枚举迁移、事件溯源和工作流引擎三套实现，每套都有代码结构、迁移脚本和测试建议。

真正困难的问题没有出现在这些代码里：产品页面中的“已取消”究竟表示用户不再等待，还是所有外部副作用已经停止？一个运行中的任务收到取消请求后，Worker 仍可能成功写回结果，计费和通知应该听谁的？历史报表按旧状态聚合，迁移后如何保持口径？

这些问题不先回答，选哪个框架都只是把含糊语义实现得更彻底。

图 1：判断不是凭资历拍板，而是把事实、约束、备选、验证和复审组织成可以被质疑的过程。

先判断问题属于哪一层

需求常以方案形式出现：“引入状态机”“换成事件驱动”“增加一个 Agent”。资深工程师的第一项工作不是评价技术，而是把方案退回到问题。

在这个案例里，表面症状是状态判断散落在多个服务中。继续追问后，问题分成了三层：

如果直接从第三层开始，平台会得到一个能力很强的引擎，但团队仍然会在每个节点里重复争论“取消后算不算成功”。架构设计不是把复杂度搬进更专业的工具，而是先让复杂度有正确归属。

AI 很适合帮忙列出遗漏场景、检索现有调用方、对比候选方案。它不适合独自定义“已完成”对业务的承诺，因为这个语义来自组织对用户、资金和数据的责任。

用不变量过滤方案，而不是给方案打印象分

我倾向先写一组跨方案都必须成立的不变量，再讨论技术选型：

I1 任务结果只能从一个领域入口确认，API 和 Worker 不得各自写最终状态
I2 取消请求与取消完成是两个事实，不能共用一个布尔值
I3 已发生的外部副作用必须可追踪，不能通过改状态假装撤销
I4 历史报表在迁移期间保持旧口径，并可解释新旧差异
I5 任一阶段都能在 30 分钟内切回旧读取路径

有了这些不变量，三个候选的差异就清楚了。简单枚举迁移改动小，但无法自然表达并发事件；事件溯源保留事实完整，却会显著提高查询、运维和团队学习成本；成熟工作流引擎擅长长事务与恢复，但会引入新的运行面和供应商边界。

最终选择未必是最“先进”的方案。对于当时的任务规模，我们采用了显式状态转换表、不可变事件记录和普通关系表投影，没有立刻引入完整事件溯源或外部引擎。原因很务实：它能够解决所有已确认不变量，团队能维护，也保留未来迁移的事件边界。

type RunState = "queued" | "running" | "cancel_requested" | "succeeded" | "failed" | "cancelled";
type RunEvent =
  | { type: "started"; attemptId: string }
  | { type: "cancel_requested"; actorId: string }
  | { type: "effect_committed"; effectId: string }
  | { type: "completed"; resultRef: string }
  | { type: "cancel_confirmed"; workerId: string };
 
function transition(state: RunState, event: RunEvent): RunState {
  // 转换表由领域规则维护；未知组合必须拒绝，而不是猜一个“合理状态”。
  return transitionTable[state]?.[event.type] ?? failInvalidTransition(state, event);
}

代码本身并不复杂。关键决定是把“取消意图”“Worker 确认停止”和“外部副作用已经提交”拆成不同事实。这个边界一旦确定，页面、计费、审计和恢复流程才有共同语言。

架构选择要同时计算三种成本

团队讨论方案时，容易只比较开发成本。AI 让开发成本继续下降后，另外两种成本会更加突出。

第一是验证成本。修改一个纯函数可能几分钟就能验证；改变跨服务状态语义，需要历史样本、并发场景、下游消费者和线上对照数据。代码越容易生成，越不能把“实现完成”误当作“语义已经证明”。

第二是认知成本。新增抽象、运行平台或协议都会进入值班和后续需求。一个方案由两个人熟练维护不代表组织已经具备这项能力。设计评审要问：半年后谁能排查它，故障发生时需要跨几支团队，新增成员需要理解多少隐含前提。

第三是退出成本。数据格式、外部协议和用户习惯一旦形成，回退远比删除代码困难。越不可逆的决定，越应该缩小初始承诺、增加对照期，并明确复审触发器。

我会用一张简单的决策表逼迫讨论落到事实：

这张表不是为了把决定伪装成数学题。它的作用是让反对意见有位置，也让未来复审时知道当初基于什么事实。

让迁移可观察，而不只是可回滚

“保留旧代码”不等于真正可回滚。状态模型迁移涉及持续写入的数据，回退前必须知道新旧语义是否仍然一致。

图 2：新模型先在影子路径中计算，不立即影响用户。差异有分类、有阈值、有负责人，才进入小流量读取。

我们先让旧模型继续作为唯一读写来源，同时根据相同事件计算新状态，但只记录差异。差异不能只统计一个总数，要区分原因：事件顺序问题、历史脏数据、转换表遗漏，还是旧逻辑本身不一致。

migration_gate:
  shadow_window: 14d
  required_samples: 10000
  unexplained_diff_rate: "< 0.05%"
  critical_diff: 0
  rollback:
    switch_read_to: legacy_projection
    keep_dual_write: true
  owners: [workflow, data, operations]

这里的阈值只是结构示例，真实数值应由业务影响决定。权限、资金等场景可能要求关键差异为零；低风险展示字段可以接受短期不一致。重要的是上线前写清楚什么结果允许继续、谁解释异常、多久没有结论就停止扩量。

新模型先服务内部查询，再进入少量租户，最后扩大读取。每一步都保留旧投影和切换入口。删除旧路径则要等完整数据保留周期结束，而不是新版本上线一周后就宣布迁移完成。

判断质量来自校准，不来自职位

架构师也会判断错。真正可靠的做法不是把决定包装得更确定，而是保留当时的假设和复审条件。

我会在 ADR 中记录四类内容：当时确认的事实、仍未知的部分、放弃方案的理由、未来什么信号会推翻当前决定。上线后再回看：差异率是否符合预期，故障恢复是否更快，新增状态的交付时间有没有下降，团队是否真的能独立排查。

有些决定最终有效，只是因为业务规模没有增长；有些方案短期遇到问题，但核心假设仍然正确。只看结果容易把运气当能力。持续对照“当时为什么这样判断”和“后来发生了什么”，经验才会变成可校准的方法。

AI 可以在这个过程中提供很大帮助：扫描调用关系、生成迁移候选、补齐反例、分析差异日志、整理决策记录。它提高的是获取证据和执行验证的速度，而不是替负责人承担结论。

代码产量增加，不代表系统吞吐增加

如果团队每天能生成更多代码，但评审、测试环境、跨团队确认和发布窗口没有变化，整体交付不会按相同比例加速。更常见的情况是，候选实现大量增加，维护者成为新的瓶颈。

因此我不太关心“AI 写了多少代码”或“节省多少编码时间”。更有意义的指标是：从提出问题到获得用户反馈用了多久，重大风险是否更早暴露，变更在评审中往返几次，生产故障能否更快定位和恢复。

成熟团队使用 AI，不是把代码队列堆得更长，而是缩短验证回路：更快做出可丢弃原型，更早生成反例，更便宜地运行迁移演练，更完整地收集上线证据。节省出来的时间应该投入判断，而不是继续扩大改动面积。

工程师的价值也不会收缩成“会不会提示模型”。从用户承诺到数据语义，从接口边界到发布恢复，从技术方案到团队能力，这些仍然需要完整的软件工程经验。AI 让很多实现工作变轻，却让含糊决定更快产生后果。

所谓高级工程能力，不是总能给出更复杂的方案，而是在信息不完整时把问题分层，在多个可行实现中识别真正约束，用可逆方式验证关键假设，并愿意对长期后果负责。代码会越来越便宜，这种判断仍然昂贵。

判断和执行的分离，恰好是 AI 时代人机分工的缩影：模型负责生成候选，人负责分层、约束与复审。候选实现进入生产前的人工确认，在人工审批不是弹窗里被描述成一段可验证的事务协议；而同样的“先定义不变量，再比较实现”思路，在如何让 AI 编程 Agent 在真实仓库里交付里被写成了任务合同。判断稀缺不是新结论，只是 AI 让它在每个环节都更先暴露。

我参与过的一个任务平台，最初用一列 status 支撑全部流程。MVP 只有排队、执行、成功和失败，简单枚举完全够用。后来产品陆续增加暂停、人工审批、超时重试和外部回调，前端、API、Worker、报表开始各自解释同一个状态。代码仍然能跑，新需求也能继续加，但每次修改都要在几个模块里同步补条件。

真正让我确认它已经从“简单设计”变成债务的，不是某段代码难看，而是三件具体的事：一次取消任务仍然触发了外部通知；同一个状态在列表和计费报表中含义不同；新增“等待审批”时，三个团队分别改了自己的判断，联调到最后一天才发现不一致。

这类债务危险之处在于，它很少让系统立即停机。它只是持续收取利息，直到一次业务变化把隐含矛盾集中暴露出来。

先区分有意识的借款和失控债务

两周 MVP 采用简单枚举并没有错。错误是上线后没有记录适用边界，也没有定义超出边界时怎么办。

一个健康的临时决定至少应写清四件事：当前为什么足够、牺牲了什么、什么信号出现时必须重审、谁负责推动重审。例如：

decision: single-status-column
context: 首版仅支持同步任务，无暂停与外部副作用
accepted_limits:
  - 一个任务只有一个执行尝试
  - 状态只服务运行流程，不承担计费口径
review_triggers:
  - 引入人工审批或补偿
  - 同一任务支持多次 attempt
  - 两个以上下游直接解释 status
owner: workflow-platform

触发器不是预测未来，而是避免团队在条件已经变化后仍然沿用旧决定。债务往往不是当初选错，而是系统演进后没有重新做决定。

债务利息必须能和业务优先级放在同一张表里

“这里应该重构”很难获得资源，因为它没有说明继续推迟会付出什么。架构债务需要像可靠性问题一样记录已发生影响，而不是表达工程师的不适。

我会把利息分成四类：

这里不需要伪造一个精确的“债务金额”。粗略但持续采集的事实已经足够帮助排序。某个旧模块虽然难看，但一年没有需求也没有故障，利息可能很低；一个刚上线的公共字段每周都引发跨团队误解，优先级反而更高。

找到共同根因，不要逐个修补症状

债务清单很容易膨胀：前端状态映射需要重构、Worker 重试条件混乱、报表口径不统一、取消逻辑有竞态。把它们当四项任务，会得到四套局部改进；把它们放回系统边界，会发现共同根因是“运行状态、用户意图和业务结果被压在同一个字段里”。

新的模型把这些事实拆开：

type RunProjection = {
  desiredState: "active" | "cancel_requested";
  executionState: "queued" | "running" | "stopped";
  outcome: "unknown" | "succeeded" | "failed" | "compensation_required";
  currentAttemptId: string | null;
  version: number;
};

这不是为了追求更多字段。用户请求取消，不代表 Worker 已经停止；Worker 停止，也不代表已经提交的外部副作用被撤回。把三个事实分开，API、页面、计费和恢复流程才能各自依赖正确语义。

架构治理的价值就在这里：它不是统一命名，而是重新决定哪个边界拥有事实，其他模块通过什么契约消费它。

偿还债务要先建立对照，再切换流量

直接替换旧状态字段风险很高，因为历史代码中可能有尚未发现的消费者。我们采用双算而不是立即双写：旧逻辑继续作为生产事实源，同一批事件同时送入新投影，结果只用于比较。

图 1：新模型先证明能解释现有事实，再承担读取和写入责任。每一阶段都有差异指标和回退入口。

迁移分成六步：

1. 盘点所有读写 status 的入口，并为旧行为补历史样本测试。
2. 从领域事件计算新投影，不影响任何线上读取。
3. 按原因记录新旧差异，优先处理权限、计费和外部副作用相关差异。
4. 让内部诊断页和少量租户读取新投影，旧读取保留一键切换。
5. 新写入只通过领域命令发生，旧字段由兼容层反向投影。
6. 覆盖完整数据保留周期后，删除旧写入口，再逐步清理读取兼容。

双算期间最容易犯的错误是只看总差异率。一个展示文案差异和一个计费结果差异不能被同一个百分比平均。差异需要按业务后果分级，关键语义要求零未解释样本，低风险差异可以设置收敛窗口。

回退也必须演练。配置里保留 read_projection=legacy 没有意义，除非值班人知道谁能操作、切换后新写入怎样兼容、缓存多久失效，以及怎样确认用户结果恢复。

双写和兼容层都有截止日期

渐进式迁移不是天然安全。双写会引入新的不一致来源，兼容层会把新旧模型耦合在一起。如果没有退出条件，“临时迁移架构”会成为下一笔债务。

因此每个阶段都要有 owner、进入条件和退出日期。迁移看板不只显示完成百分比，还要显示剩余旧消费者、未解释差异、回退演练时间和兼容层删除计划。

我通常会保留一个明确的停止条件：关键差异没有解释、回退演练失败、值班团队还不能独立定位时，不继续扩大流量。进度压力不能把未知风险包装成“后续优化”。

债务偿还要验证收益，而不是统计新代码

重构完成不代表债务已经还清。需要回到最初记录的利息：新增状态的交付周期是否缩短，跨模块条件是否减少，状态冲突和人工恢复是否下降，其他团队能否只依赖稳定契约。

如果代码更漂亮，但业务需求仍要跨多个团队同步修改，根因可能没有解决；如果引入通用平台后值班复杂度显著上升，偿还方式也可能产生了新的利息。

架构债务管理本质上是持续做决定：今天为了速度接受了什么限制，系统何时越过适用边界，继续推迟的代价是什么，谁负责以可回退方式处理。只要这些问题有明确答案，一个不完美的系统仍然可以健康演进。真正失控的不是临时代码，而是所有人都知道问题存在，却没有触发器、负责人和验证标准。

“触发器”要落到文档和监控两处：文档里是 ADR 的复审条件（见ADR 怎么写才有人看），监控里是利息指标到达阈值自动建任务。状态字段这类单点模型的迁移，我在低代码配置升级里用单向迁移、黄金样例和写回隔离做过一次完整的演示——债务的偿还方法，常常已经在别的问题上练过一遍。

我们在一个内部规则管理场景里遇到过这种缺口。运营人员要求 Agent 把三条告警规则的接收组从 A 调整为 B。页面展示了三条规则，用户点击确认。审批等待期间，Agent 根据新返回的数据重新规划，把另一条“相似规则”也加入执行列表。四条修改都符合最初的自然语言目标，却只有三条真正经过人确认。

问题不在模型是否聪明，而在系统把一次 UI 确认误当成了执行授权。高风险审批需要是一段可验证的事务协议：人批准的是一份规范化、不可变、有时效的执行计划；计划任何实质变化都必须重新审批。

先定义哪些动作需要人，而不是所有动作都弹窗

频繁确认会让人形成机械点击，最后既降低效率，也没有提高安全性。审批应该根据后果分级，而不是根据“是否由 AI 发起”分级。

风险还要结合作用域。修改一条测试环境规则和修改全公司生产告警不是同一件事，即使调用的是同一个工具。策略引擎应基于主体、资源、环境、数量和可逆性判断，模型只负责提出意图，不能自行给动作定级。

审批对象必须是确定性执行计划

自然语言说明可以帮助人理解，但不能作为授权凭证。真正进入审批的计划需要稳定字段：

type ExecutionPlan = {
  planId: string;
  taskId: string;
  actor: { userId: string; tenantId: string };
  tool: string;
  toolVersion: number;
  input: unknown;
  targets: Array<{
    resourceType: string;
    resourceId: string;
    expectedVersion: number;
  }>;
  expectedEffect: string;
  compensation?: ToolCall;
  createdAt: string;
  expiresAt: string;
};

网关先对工具输入做 Schema 校验和规范化，再按稳定字段顺序序列化并计算 planHash。模型生成的解释、展示顺序和措辞可以变化，工具版本、目标资源、输入与补偿动作不能在批准后变化。

const planHash = sha256(canonicalJson({
  actor: plan.actor,
  tool: plan.tool,
  toolVersion: plan.toolVersion,
  input: plan.input,
  targets: plan.targets,
  compensation: plan.compensation,
  expiresAt: plan.expiresAt,
}));

把 actor 和 expiresAt 纳入 hash 是为了防止批准在另一个租户、用户或时间窗口中被复用。具体字段应按威胁模型决定，但原则一致：执行器必须能证明“正在执行的就是被批准的那一份计划”。

审批界面展示业务影响，不展示模型思维过程

审批者需要回答的是“我要承担什么后果”，而不是阅读模型长篇解释。页面至少应展示目标对象、before/after、影响数量、数据快照时间、是否可逆、失败后的处理方式，以及触发这次操作的业务原因。

对于批量策略变更，我们会展示完整数量和分组汇总，同时允许展开逐项差异。只展示三个抽样对象不够，因为真正的风险可能藏在未展示部分；把几百行 JSON 全部铺开也不够，因为人无法在有限时间内理解。

审批权限本身也要受控。能使用 Agent 的人，不一定有权批准生产权限变更。对于职责分离场景，提出计划的人和批准人不能是同一主体；极高风险操作还需要两位不同角色的独立批准。

批准是一张有期限、只能消费一次的票据

type Approval = {
  approvalId: string;
  planHash: string;
  approvedBy: string;
  approvedAt: string;
  expiresAt: string;
  status: "approved" | "consumed" | "revoked";
};

执行器不能先读取 approved 再单独更新状态，这会在并发请求中被消费两次。批准消费和执行记录创建需要处于原子边界：

UPDATE approvals
SET status = 'consumed', consumed_at = now()
WHERE approval_id = $1
  AND plan_hash = $2
  AND status = 'approved'
  AND expires_at > now()
RETURNING approval_id;

只有返回一行才允许继续。按钮双击、网络重试或两个执行器竞争时，只有一个能拿到票据。对于支持幂等的外部系统，还要使用由 planHash 和执行序号派生的 idempotencyKey，避免内部防重与外部副作用脱节。

执行前必须处理 TOCTOU

审批时看到的资源可能在等待期间变化。这是典型的 time-of-check to time-of-use 问题。计划中为每个目标保存 expectedVersion，执行前通过 compare-and-set 更新：

UPDATE alert_rules
SET receiver_group = $1, version = version + 1
WHERE tenant_id = $2
  AND id = $3
  AND version = $4;

影响行数为零时返回 PLAN_STALE。Agent 可以重新读取资源并生成新计划，但不能把旧批准自动套在新状态上。即使最终参数碰巧相同，目标集合、版本或影响范围变化也需要重新评估。

批量操作还要事先声明原子性。是全部成功才提交，还是允许部分成功？数据库内的同域修改可以放在一个事务中；跨多个外部系统通常无法获得强原子性，此时必须逐项记录结果，并在审批界面明确“可能部分完成”。

超时不等于失败，结果未知必须成为正式状态

外部系统超时时，调用可能已经成功，只是回执丢失。自动重试高风险副作用，可能重复发消息、重复扣费或重复修改权限。把它简单标记为 failed 会诱导系统再次执行。

图 1：outcome_unknown 不是普通失败分支。系统先查证外部事实，再决定确认成功、重新执行或进入人工恢复。

执行状态至少要区分：

planned -> awaiting_approval -> approved -> executing -> succeeded
                                             |-> failed_before_effect
                                             |-> outcome_unknown
                                             |-> compensation_required

failed_before_effect 可以安全重试；outcome_unknown 先用幂等键查询对方回执，或通过资源当前状态核对。无法自动确认时，进入人工恢复队列，展示已知证据和推荐动作，而不是让 Agent猜测。

补偿也不是“回滚”两个字。外部消息无法真正收回，最多发送更正；权限恢复要确认期间是否发生新的合法修改；费用冲正本身可能需要新审批。补偿是一项新的业务动作，同样需要权限、幂等、审计和失败处理。

审计记录要能独立重放当时发生了什么

完整证据链包括：原始任务、规范化计划与 hash、策略判断、审批人和审批版本、一次性凭证消费、执行器身份、外部请求与回执、状态核对以及补偿结果。

审计不能只保存一段模型总结。半年后排查时，需要能够回答：人具体批准了哪些资源和参数，执行时资源版本是否一致，外部系统返回了什么，为什么进入结果未知，以及最后由谁确认恢复。

敏感字段可以脱敏或单独加密，但不能因此丢掉责任链。日志保留策略也应与业务风险匹配，而不是所有 Agent 调用统一保存七天。

人在环路里的价值是判断，不是替系统兜底

一个可靠的审批系统不会让人频繁点“允许”。低风险动作自动化，高风险动作才把影响压缩成可理解计划；系统负责保证批准和执行一致，处理并发、过期、状态漂移和未知结果。

人应该判断业务后果是否可以接受，不应该负责发现目标列表被悄悄改了、猜测按钮会不会执行两次，或者在超时后手工翻日志确认外部系统是否成功。这些属于工程系统应提供的确定性。

Agent 能让计划生成和工具编排更灵活，但授权边界必须更明确。模型负责提出候选，策略系统决定是否允许进入审批，审批人承担有上下文的业务判断，执行器严格消费被批准的计划。四个角色分开之后，人机协作才不是一层看起来安全的弹窗，而是一条可以审计和恢复的生产协议。

审批票据的消费与执行状态，和不要把生产密钥交给模型里的权限网关是同一套执行边界：前者管“人的确认如何被绑定”，后者管“模型请求如何被校验与幂等化”。超时后 outcome_unknown 的查询核对，与requestId 到了消息队列就断了里 traceId 与 jobId 的区分同源——执行链和业务身份必须分开保存。

这些工作并不比写代码“高级”，也不能成为不落地的借口。资深工程师仍然要能处理困难实现，只是评价产出时不能只看个人完成了多少需求，而要看系统和团队是否因此更容易做出正确改变。

我经历过一次很普通的发布事故。一个 Node.js 服务新增了第三方回调地址，预发环境配置正常，生产发布后进程也通过了健康检查。第一批异步任务执行到回调阶段才报错，因为生产环境缺少一个变量。值班人临时补配置、重启服务，四十多分钟后恢复。

如果只看故障工单，工作已经结束：原因明确，配置补上，任务重跑成功。但如果到这里为止，同类问题还会以另一个变量、另一个仓库再次出现。资深工程师的责任，是判断这次问题值得沉淀到哪一层，又避免因为一次事故就建设过重的平台。

先完成修复，再问系统为什么允许它发生

事故处理中，优先级仍然是恢复用户结果。先停止继续接收会失败的任务，补齐配置，重放确认安全的任务，并核对是否有外部副作用。这个阶段不适合一边救火一边重构配置系统。

恢复后再拆原因。表层原因是环境变量缺失，更深的系统缺口有四个：

1. 变量只在运行到回调分支时读取，启动阶段没有校验。
2. 健康检查只验证进程存活，不验证关键依赖配置。
3. 部署清单不知道服务声明了哪些必需变量。
4. 错误日志有变量名，却没有受影响任务、恢复入口和安全重试条件。

这四个问题分属代码、构建、部署和运维界面。只修当前服务里的 if (!env.X)，能降低一次风险，却没有解决跨仓库重复发生的模式。

把一次问题分成四层产出

我通常按修复、反馈、恢复路径和默认能力四层判断，不是每次都做到最上层：

图 1：不是每个问题都要平台化。重复频率、规则稳定性和影响范围共同决定沉淀到哪一层。

当前服务先增加类型化配置入口，进程启动时一次性解析：

const Env = z.object({
  DATABASE_URL: z.string().url(),
  CALLBACK_BASE_URL: z.string().url(),
  CALLBACK_TIMEOUT_MS: z.coerce.number().int().min(100).max(30_000),
});
 
export const env = Env.parse(process.env);

这里的价值不只是少写几个非空判断，而是让配置成为可查询契约。CI 可以导出必需键，部署系统可以和目标环境对照，文档也可以从同一份 Schema 生成。运行时仍要处理第三方不可达等动态失败，但“必需配置根本不存在”应该在接流量前被拒绝。

当我们确认多个服务反复遇到相同问题后，才把规则上移到流水线模板：构建产物携带配置清单，部署前比较环境键，缺失则门禁失败。平台不读取具体密钥，只验证声明和注入是否一致。这个边界减少了安全暴露，也避免中央平台理解每个业务变量的含义。

沉淀机制之前先算维护成本

技术负责人很容易把重复问题都解释成“缺少平台”。平台化本身也会产生长期成本：谁维护规则，例外怎样处理，旧服务如何迁移，误报会不会逼团队绕过门禁。

我会用三个条件决定是否自动化：问题是否已经重复出现，规则是否足够稳定，收益是否覆盖机制本身的维护成本。三者缺一，先用文档、模板或局部检查通常更合适。

以配置为例，“生产环境必须存在服务声明的必需键”是稳定规则，适合自动门禁；“每个回调超时必须小于五秒”取决于业务，不应该由统一平台替领域团队决定。高级工程能力不在于把更多东西集中控制，而在于识别哪些约束应该成为公共默认，哪些决定应保留在业务边界。

机制还要有退出设计。规则需要 owner、版本和例外期限；如果平台条件已经变化，旧门禁应该可以被安全删除。只会增加规则不会删除，工程系统最终会变成没人理解的阻力。

让决策权分布，而不是让所有问题都升级给同一个人

资深工程师常见的反模式是成为团队最可靠的同步接口。遇到复杂问题大家都来问，短期看解决很快，长期看整个系统依赖一个人的在线状态。

真正可分布的任务说明，不是把实现步骤写得更细，而是提供结果、约束、决策权和升级条件：

Outcome: 部署前发现必需配置缺失，运行中能定位受影响任务
Constraints: 平台不能读取密钥值；旧服务可以渐进接入
Decision rights: 各服务定义自己的 Schema 和业务校验
Escalation: 涉及跨环境密钥迁移或公共协议变化时共同评审
Evidence: 门禁拦截样例、回滚演练、恢复时间与误报率

负责人应该评审高风险边界和二阶影响，而不是统一所有命名和实现风格。可逆的局部选择交给最接近问题的人，决定作出后再通过结果校准。这样团队获得的是判断能力，而不是更详细的执行指令。

代码评审也一样。资深工程师的价值不应表现为每个 PR 留下最多意见，而是帮助作者看见数据语义、失败路径和长期边界。风格问题交给自动化，局部方案只要符合系统约束，就允许存在差异。

故障恢复能力必须离开个人记忆

事故时的“我知道怎么处理”不是可靠能力。Runbook 至少要让值班人独立完成四件事：确认用户影响、判断是否继续止损、执行可逆恢复、验证结果真正恢复。

配置事故的 Runbook 不会只写“补环境变量并重启”，而会说明：如何找到受影响任务，哪些任务可能已经发生外部副作用，怎样区分安全重试和人工核对，重启后观察哪些指标，什么情况下必须停止批量重放。

发布恢复后，我们让没有参与事故的同事按 Runbook 做一次演练。演练中暴露出来的问题比文档评审更真实：某个查询需要额外权限，重试按钮没有展示幂等键，指标名称和手册不一致。把这些障碍处理掉，恢复能力才真正离开原作者。

我会在复盘里问一句很直接的话：“下次同类故障发生时，谁能在没有我的情况下处理？”如果答案仍然只有一个人，修复就还没有完成。可能缺的是权限、工具、指标或演练，不一定是更多代码。

用系统结果衡量杠杆，不用产出数量包装价值

机制上线后仍要验证是否有效。配置门禁拦截过多少真实问题，误报率是否可接受，发布失败是否更早反馈，平均恢复时间是否下降，值班人能否独立完成重放。这些结果比“建设了配置平台”更能说明价值。

同样，ADR 数量、文档页数、分享场次都不是目标。一份 Runbook 从未在演练和事故中使用，可能只是写得很完整；一个公共组件让团队每次需求都来找原作者修改，也没有形成真正复用。

资深工程师的产出可以是代码、架构、工具、决策记录和更成熟的团队，但它们要满足同一标准：能被别人使用，能用结果验证，并且不需要作者持续在场才能运行。

高级工程师和架构师的“高度”，并不来自谈论更宏大的概念，而是能沿一次具体故障看到跨层原因，选择合适的沉淀层级，控制方案自身的复杂度，再把个人经验转成团队可以维护的默认能力。代码仍然重要，只是最终要服务于一个更稳定、可理解、可持续演进的工程系统。

这套“四层产出”与两篇文章互为注释：判定什么决定值得写下来、反对意见怎样保存，看ADR 怎么写才有人看；避免自己成为团队同步阻塞点的决策分级，看技术负责人的边界。而“经验年限不等于资深”的底层判断——如何区分熟练与能力——是经验年限不等于资深整篇的主题。

后来 Evals 不再是一份实验报告，而是发布流水线的门禁。每一项候选配置都有不可变版本，按离线、影子和线上阶段逐层证明。

图 1：离线评估阻止已知回归，线上预算捕捉分布变化；两者不能互相替代。

候选版本必须完整可重放

type AiReleaseCandidate = {
  id: string;
  model: string;
  modelParameters: Record<string, number | string>;
  systemPromptVersion: string;
  toolRegistryVersion: string;
  retrievalIndexVersion: string;
  policyVersion: string;
  codeSha: string;
};

只写“升级到新模型”无法重放。工具描述、权限策略和索引变化都会改变结果，必须和候选一起冻结。

门禁按风险分层，不用平均分放行

一个总分可能用文风提升抵消权限回归，这是不可接受的。门禁对关键维度使用硬阈值，其他维度才做权衡。

结果要带统计不确定性

样本量小时，86% 到 88% 可能只是波动。报告展示样本数、置信区间和逐 case 差异；对同一问题使用配对比较，优先看哪些已知案例变好或变坏，而不是只看平均。

失败必须保存输入、候选输出、工具轨迹、评分依据和随机种子/采样参数。否则下一次无法判断是模型随机性、外部工具还是评估器变化。

影子流量验证真实分布

通过离线门禁后，候选在不影响用户的情况下处理一部分脱敏生产请求。它不能执行真实写工具，只能走沙箱或回放录制结果。我们比较任务类型分布、工具计划、延迟、成本和拒答差异。

影子结果仍需遵守数据权限和保留策略，不因为“不展示给用户”就可以无限复制生产输入。

小流量阶段需要自动回退

真实发布使用稳定分桶。线上观察任务成功率、人工接管率、工具失败、权限拒绝、引用打开率、P95 延迟和单任务成本。错误预算快速燃烧或安全指标越界时，控制面把流量切回已知稳定候选。

模型响应不可完全复现，回退指的是配置和流量，不承诺已经发生的外部副作用自动消失。写工具仍需要幂等和补偿。

线上失败回到评估集

用户修正、人工接管和高成本任务进入候选池，经脱敏、聚类和人工标注后成为新 case。生产回流不能直接修改门禁集，避免错误标签和攻击输入污染；数据集升级有版本与评审。

这套门禁不会消除 AI 的不确定性，但让每次发布承担的风险可见。团队讨论从“新模型感觉更好”变成“核心任务无退化，权限用例全过，成本增加 8%，影子流量发现两类新失败”。能够这样交付，Evals 才从研究工具变成软件工程的一部分。

门禁的数据基础是评估集本身的来源和质量——120 个真实问题的构建、分维度评分与防过拟合，我在RAG 评估别再问“感觉怎么样”里记录过；而门禁真正拦下的那类“代码看起来完整”的回归，与AI 辅助编程之后的代码评审关注的是同一件事的两端：生成侧的证据包，和发布侧的回归集。

上下文变长后，成本和延迟上升，关键约束反而更容易被淹没。真正的问题不是信息不足，而是没有为当前任务组织信息。

上下文工程关注的不只是一段 Prompt，而是信息从进入系统、被选择、压缩、使用到沉淀的完整生命周期。

图 1：上下文组装器的工作不是把信息全部拼起来，而是为当前子任务选择最少但充分的输入，并保留来源与版本。

上下文是一种运行时资源

模型上下文与内存、连接数一样有限。即使窗口足够大，注意力也不是均匀分配。无关信息会增加噪声，相互矛盾的信息会迫使模型猜测，重复信息会浪费成本。

每个任务应有上下文预算。系统先放入不可违反的规则和当前目标，再加入完成任务所需事实、工具和少量相关示例。其余材料通过检索或工具按需获得。

预算需要可观测：固定指令、对话历史、检索材料、工具结果分别占用多少，哪些内容最终被引用。没有这些数据，团队只能凭感觉缩短 Prompt。

上下文还具有时间属性。用户刚刚确认的要求优先于早期假设，实时数据不能被旧缓存覆盖，已经失效的工具说明不应继续出现。信息新旧和来源可信度都应该成为选择条件。

分层组织，而不是拼接字符串

一份可靠上下文至少可以分为五层：系统规则定义行为边界；任务说明定义当前目标与完成标准；领域状态保存经过确认的事实；检索材料提供证据；工作记忆保存本次执行的中间产物。

不同层有不同写入权限。用户和系统可以修改目标，工具产生原始证据，验证步骤才有权把事实写入领域状态，临时推理不应自动成为长期记忆。

这种分层避免“模型说过的话”被误认为事实。每条长期记忆附带来源、创建时间、适用范围和置信状态。下次检索时，系统可以判断是否仍然有效。

上下文组装也应结构化。使用明确标题、Schema 和引用标识，让模型区分规则、事实与待解决问题。字符串模板只是最终序列化形式，内部应该保存可单独筛选和测试的数据对象。

检索需要理解任务意图

RAG 经常被简化为“切块、向量化、取前 K 条”。语义相似并不等于对当前任务有用。用户问“为什么这个版本性能下降”，需要的可能是变更记录、性能指标和架构说明，而不是包含“性能”一词最多的文档。

检索前先把任务转换为查询计划：需要哪些事实类型，时间范围是什么，哪些来源更可信，结果如何验证。复杂问题可以生成多个查询，再合并去重。

混合检索通常更可靠。向量处理语义相似，关键词保留精确标识，结构化过滤控制项目、版本和权限，重排模型根据完整问题重新排序。没有一种方式适合所有材料。

切块也应尊重文档结构。函数、章节、表格和决策记录有自然边界，固定字符切割会把定义和结论分开。每个片段保留标题路径、版本和原文位置，以便回答能够回到证据。

压缩不能丢失约束

长对话与工具输出需要压缩，但“总结一下”很容易删除看似细小、实际关键的条件。更稳妥的压缩是按类型提取：已确认目标、硬约束、已完成动作、开放问题和关键产物分别保存。

对日志和搜索结果，可以先用确定规则裁剪无关字段，再由模型摘要。数值、错误码、文件路径和引用标识应原样保留，不让语言模型重新表述后产生偏差。

压缩结果要带来源指针。需要细节时，Agent 可以通过工具重新读取原始内容，而不是把摘要当作不可追溯的事实。

摘要也有版本。任务范围变化后，旧摘要可能不再强调正确内容。依赖哈希或任务版本能帮助系统判断是否需要重新生成。

工具描述也是上下文

Agent 可用工具越多，选择错误工具的概率越高。把几十个工具的完整 Schema 全部放进每次调用，会占用大量预算并增加混淆。

可以先根据任务类型选择工具集合，只暴露当前阶段需要的能力。规划阶段看到搜索和任务拆分工具，执行节点只看到具体数据源，审阅节点只看到验证工具。

工具名称和描述要表达业务意图，而不是内部实现。参数有明确类型、范围和示例，错误返回可行动信息。一个设计良好的工具接口，本身就是对模型的约束。

工具结果也要控制规模。数据库查询返回一万行不应直接进入上下文，应该先聚合、分页或保存为产物，再提供摘要与句柄。模型需要知道结果在哪里和如何继续取用，不需要一次看到全部内容。

工作记忆与长期记忆分开

工作记忆服务当前执行，包含计划、节点输出和未完成问题。任务结束后，大部分内容应被丢弃。长期记忆只保存未来确实有价值、且经过验证的信息。

如果所有对话都自动进入长期记忆，错误假设、过期偏好和一次性内容会不断污染后续任务。写入长期记忆应当像写数据库：有 Schema、去重、权限、更新与删除机制。

用户偏好也需要范围。“所有回答简短”可能只适用于某个项目，不应被提升为全局永久规则。记忆条目应标注用户、组织、项目和任务层级，读取时按作用域合并。

冲突不可避免。新信息与旧记忆冲突时，系统不能悄悄选择一个。应根据来源与时间自动解决简单冲突，对关键事实请求用户确认，并保留变更历史。

多 Agent 需要最小共享事实

多个 Agent 协作时，共享全部对话会让边界消失。更好的方式是共享一块结构化任务状态：目标、约束、已确认事实、产物索引和开放问题。

每个 Agent 获得自己的局部上下文，只把通过验证的产物写回共享状态。检索 Agent 不需要知道报告的全部文风要求，写作 Agent 也不需要看到搜索过程里的每个失败查询。

产物之间保存依赖。某个事实被更正后，系统可以找到使用它的分析和报告节点，标记为过期。没有依赖关系，修正上游信息后只能从头重跑或冒险保留错误结果。

上下文传递使用引用和结构，而不是让 Agent 互相发送长篇“对话”。这更接近软件模块之间通过契约协作，也更容易测试。

安全边界必须在模型之外

检索材料可能包含提示注入，要求模型忽略规则或执行危险工具。系统不能依赖模型自行识别所有攻击。

外部内容被明确标记为不可信数据，不能覆盖系统规则。工具权限由代码控制，敏感写操作需要用户确认。检索层按用户权限过滤，不能先取回再要求模型“不许看”。

上下文日志也需要脱敏。为了调试保存完整 Prompt 很方便，却可能包含用户文件、身份与业务数据。生产系统应按字段分类保存，设置访问控制与保留周期。

安全不是在提示词里增加一句“不要泄漏”，而是让模型即使被诱导，也没有越过边界的能力。

评估上下文，而不只评估答案

最终答案错误，可能来自模型能力，也可能来自上下文缺失、检索噪声、旧记忆或工具描述不清。只给答案打分无法定位问题。

我们分别评估检索召回、证据相关性、关键约束覆盖、引用一致性和上下文成本。对固定任务，记录理想材料集合，检查系统是否取回；对答案中的事实，检查是否由上下文支持。

消融测试很有价值：删除某类上下文，结果是否变化；减少检索数量，正确率是否下降；更换摘要策略，约束是否保留。通过这些实验，可以知道哪些 Token 真正产生价值。

线上收集的失败进入回归集。上下文策略、嵌入模型、切块方式和工具描述每次调整后都重新运行，避免优化一个示例却损害整体。

上下文工程最终是信息架构

提示词仍然重要，但它只是系统向模型呈现信息的最后一步。更长期的能力是知道信息从哪里来、谁能修改、何时失效、如何检索、如何压缩，以及输出如何回到可验证来源。

当 Agent 表现不稳定时，先不要急着增加更多规则。检查它是否拿到了正确目标，是否被无关历史干扰，是否能访问需要的工具，是否把临时推断误当成事实。

模型越强，好的上下文工程越不是“教模型聪明一点”，而是让系统承担起组织复杂度的责任。Agent 应该知道完成当前任务所需的一切，同时对其余信息保持无知。

落地时我要求每段进入模型的上下文都携带来源和有效期：source、owner、权限、采集时间、版本、相关性理由和失效条件。输出引用能反查原文，任务结束后知道哪些上下文必须删除。同时统计检索到但未使用、被权限过滤、超过预算裁剪和最终被引用的比例——上下文工程不是塞得更多，而是让每一段信息都能解释为什么此刻应该在这里。

上下文在单 Agent 内部如何组织，在多 Agent 之间就变成“最小共享事实”的问题：哪些事实写回共享黑板、哪些留在局部，我在多 Agent 系统里做了展开；证据检索与权限过滤的具体评估方式，则属于RAG 评估。

我现在把执行环境当成产品能力，而不是运行命令前的准备工作。任务契约先定义允许影响，沙箱再从文件、网络、秘密和资源四个维度执行边界。

图 1：Agent 的自由度存在于沙箱内部；能否越过边界不依赖模型“自觉”。

每个任务先生成可执行契约

taskId: task-20260117-042
repository: console
baseSha: 8f12ac9
allowedPaths:
  - src/search/**
  - src/components/search/**
readOnlyPaths:
  - package.json
  - src/lib/content.ts
forbiddenCommands:
  - deploy
  - terraform apply
networkPolicy: registry-readonly
timeBudgetSeconds: 900
verification:
  - pnpm check
  - pnpm test -- search

契约由任务分解器和仓库策略共同生成，模型可以建议扩大范围，但扩大需要重新授权。提示里写“不要改其他文件”是沟通，文件系统策略才是边界。

用临时工作树保护用户现场

Agent 不直接在开发者当前工作区修改。执行器从 baseSha 创建独立 worktree 或快照，只挂载允许写目录，用户未提交文件不进入沙箱。任务结束交付 patch、提交候选和验证结果，由人决定怎样合并。

host repository (read-only metadata)
  └── sandbox worktree @ baseSha
      ├── writable: allowedPaths
      ├── read-only: dependency manifests
      └── hidden: .env, credentials, unrelated private files

如果 baseSha 已经落后，不能在沙箱里偷偷 merge 最新主分支。交付时显式报告基线，重新基于新 SHA 验证。

网络默认拒绝，按任务开放

多数代码修改只需要已缓存依赖和本地文档。需要安装包时，网络策略只允许公司 registry 的 GET，禁止任意域名与上传；需要访问 issue API 时，经工具代理返回最小字段，不把通用网络 socket 交给 Agent。

秘密通过代理使用，不进入上下文

测试需要凭证时，沙箱获得一次性、最小范围 token；工具代理执行请求并过滤响应。模型看不到长期 key，stdout 和补丁扫描也会阻止秘密外泄。任务结束立即撤销 token。

资源预算防止“正确但失控”

执行器限制 CPU、内存、进程数、磁盘和墙钟时间。每条命令有单独超时，输出达到上限后截断并保存 artifact。无限测试监听、递归扫描和巨量日志都不能拖垮宿主。

type CommandBudget = {
  timeoutMs: number;
  maxOutputBytes: number;
  maxProcesses: number;
  memoryMb: number;
};

超预算不是普通“测试失败”，交付中标记为环境/范围问题，避免模型通过反复重跑消耗更多资源。

交付物是一组证据

最终结果包含 baseSha、修改路径、diff、命令与退出码、测试报告、未验证项、越界请求和风险提示。沙箱日志能回答每个文件何时改变、哪个命令产生、网络访问过哪里。

我不指望沙箱证明代码一定正确。它解决的是另一类问题：即使 Agent 判断错误，影响也被限制在一个可回收环境；即使结果正确，团队也能看到它如何得到。对真实仓库而言，这种可控失败比偶尔惊艳的生成更重要。

沙箱是执行层，它之上还有两层约束：工具调用层面的授权与幂等，属于不要把生产密钥交给模型；评审层对“交付证据”的验收标准，属于AI 辅助编程之后的代码评审。三层各自负责一部分，Agent 才不会在任何一层获得完整万能权限。

评审如果仍然主要检查格式和常见语法，就无法覆盖新的风险。

图 1：生成代码只是中间一步。评审从意图和不变量开始，以不同来源的验证证据结束。

交付时我会要求一份评审证据包：任务契约、仓库基线、修改文件、关键假设、测试命令与输出、未验证项和人工关注点。只给 diff，会把理解成本转嫁给评审者。对认证、迁移、并发和外部副作用，评审必须有人类重新推演失败路径——AI 可以加快实现和搜索，责任不能被“模型写的”稀释。

证据包让产出速度与可审查性一起提高。这套标准在真实仓库里跑过一轮之后的细节——Agent 怎样理解仓库、交付怎样带证据——在如何让 AI 编程 Agent 在真实仓库里交付里展开；执行环境本身的边界则是编码 Agent 的沙箱的主题。

先验证意图

提交应说明解决什么问题、关键约束和验证方式。评审者先确认模型实现的是否是正确问题，再查看边界情况、失败模式和数据影响。

生成代码常倾向补齐“合理功能”，例如自动重试、默认回退或额外缓存。这些行为必须被显式确认，不能因为代码能运行就进入系统。

我遇到过一类很典型的生成结果：为了“提高可靠性”，模型给创建订单接口加了三次自动重试。代码有退避、日志和测试，看起来很完整，却没有回答创建接口是否幂等。第一次请求已经成功但响应超时，重试就可能创建第二笔订单。

评审这种代码时，我不会先讨论退避参数，而是先写不变量：

// 同一个 clientRequestId 最多对应一个订单
type CreateOrderCommand = {
  clientRequestId: string;
  userId: string;
  items: Array<{ sku: string; quantity: number }>;
};

只有服务端对 clientRequestId 建立唯一约束，并能查询已有结果，客户端才有安全重试的基础。AI 容易补出机制，评审者必须确认机制背后的业务前提。

缩小生成范围

让 AI 在稳定接口内完成局部实现，比一次生成跨越多层的大改动更容易验证。公共协议、权限、财务和不可逆数据变更仍需要更强人工设计。

测试也不能只由同一提示同时生成。先列不变量和反例，再让工具补充实现；关键路径保留独立验收与真实样本。

我会把评审按风险顺序走，而不是从第一行读到最后一行：

生成代码往往在第五层表现最好，风险却集中在前四层。先看漂亮实现，会让人过早接受它的前提。

提交要保留可追溯意图

使用 AI 反复修改后，开发者容易只保留最终文件，不知道某段代码为何出现。提交前需要清理无关生成、删除未使用抽象，并用自己的语言说明关键选择。无法解释的代码不应因为测试通过就进入生产。

我要求提交说明至少包含四段：

Intent: 要改变的行为
Invariants: 保持不变的业务事实
Evidence: 实际运行的检查与结果
Residual risk: 尚未覆盖的场景

“AI 生成并经人工检查”不是证据。类型检查通过、幂等并发用例通过、旧客户端回归通过，才是可以复核的证据。提示词可以保存为开发过程附件，不能替代这些工程事实。

模型与提示上下文也可以作为开发过程记录，但不能代替正式设计说明。未来维护者需要知道系统约束，而不是重放一场冗长对话。把探索压缩成可验证的决策，是使用 AI 后新的整理工作。

AI 提高的是产出候选方案的速度，不是自动提高正确率。未来代码评审更像设计审查：关注假设、系统边界和长期成本，而不只是逐行纠错。

问题不在 React 渲染，而在协议把一个有状态任务伪装成文本管道。我们改成带 runId、sequence 和明确类型的事件流，客户端用 reducer 重建状态。

图 1：文本只是事件之一；工具、审批、错误和结束都需要独立语义。

每个事件可排序、可去重

type RunEvent =
  | { runId: string; seq: number; type: "run.started"; at: string }
  | { runId: string; seq: number; type: "message.delta"; messageId: string; text: string }
  | { runId: string; seq: number; type: "tool.requested"; callId: string; tool: string; summary: string }
  | { runId: string; seq: number; type: "approval.required"; approvalId: string; planHash: string }
  | { runId: string; seq: number; type: "tool.completed"; callId: string; result: ToolSummary }
  | { runId: string; seq: number; type: "run.failed"; code: string; retryable: boolean }
  | { runId: string; seq: number; type: "run.completed"; usage: Usage };

服务端为每个 run 单调递增 seq，事件持久化后再推送。客户端保存 lastSeq，重连时请求 after=lastSeq；收到重复 seq 直接忽略，发现跳号则补拉，不能继续盲拼。

文本按 messageId 聚合

一个 run 可能产生多条 assistant message，也可能先写分析摘要再生成最终答案。delta 必须携带 messageId：

function reduce(state: RunState, event: RunEvent): RunState {
  if (event.seq <= state.lastSeq) return state;
 
  if (event.type === "message.delta") {
    const previous = state.messages[event.messageId] ?? "";
    return {
      ...state,
      lastSeq: event.seq,
      messages: { ...state.messages, [event.messageId]: previous + event.text },
    };
  }
  return transitionNonTextEvent(state, event);
}

渲染层按动画帧批量提交 delta，避免每个 token 都触发完整 Markdown 解析。代码块未闭合时使用增量友好的展示，完成后再做最终高亮。

断线不等于任务失败

浏览器连接断开，Agent 可能仍在运行。页面进入 reconnecting，先查询 run 状态和缺失事件；只有服务端明确 run.failed 才展示失败。用户刷新页面也能通过 URL 中的 runId 恢复，而不是丢掉整个任务。

停止也要有服务端确认

点击停止发送 run.cancel.requested，UI 不立即假装结束。Agent 在安全点取消工具和生成，服务端发 run.cancelled。已经发生的外部副作用不会因停止自动撤销，界面要列出已完成工具及补偿状态。

背压和大小限制必须进入协议

客户端消费慢或切到后台时，服务端不能无限缓冲。事件持久化与实时传输分离，WebSocket/SSE 只做通知；客户端按序补拉。单个工具结果不直接塞入事件流，只返回 artifactId、摘要和受权下载链接。

上线后我们观察重连成功率、序号缺口、重复事件、首 token、完成时间和取消耗时。一个流式界面的稳定性，不是动画是否顺滑，而是任何网络中断、工具等待和页面刷新后，用户仍能准确知道任务做到了哪一步。

事件协议与前端状态机的边界划分，和人工审批不是弹窗里审批协议的思路同源：把“需要人确认的阶段”变成协议里的一等事件，而不是 UI 上的一个临时状态。客户端如何组织这些事件的上下文，则属于上下文工程讨论的范围。

例如“文件分享”不是一个按钮或一个接口，而是包含资源、权限、链接、有效期、访问者和审计的完整能力。产品与技术都应围绕这些概念讨论。

我会先写领域事实，再讨论页面：

type ShareLink = {
  id: string;
  resourceId: string;
  createdBy: string;
  status: "active" | "revoked" | "expired";
  expiresAt?: string;
  access: "anyone" | "organization" | "invited";
  version: number;
};

产品看到的是创建、复制、撤销和访问记录；服务端看到的是状态转换、权限与审计；前端看到的是每个状态下可用动作。三方共享 ShareLink 这组事实，页面和接口只是不同投影。

共享领域语言

先建立关键对象、状态和用户任务，再映射页面与服务。产品确认用户能做什么，技术确认规则由谁拥有，设计确认状态如何被理解。一个词在不同角色那里不能代表三种东西。

状态图尤其有效。它让“审核中能否取消”“过期后是否恢复”这类边界提前出现，而不是等接口联调时才决定。

draft ──publish──> active ──revoke──> revoked
                       └──time──> expired
 
revoked / expired 不直接回到 active；需要创建新版本链接

“恢复过期链接”听起来是一个按钮，实际会影响访问者已经保存的 URL、审计记录和权限预期。决定创建新版本后，前端文案、API 和数据模型同时得到约束，不会各自补一套含义。

路线图也是风险图

功能排期之外，还要看到公共模型、数据迁移和外部依赖的技术风险。有些基础能力不能直接展示，却决定后续多个功能能否稳定交付。

技术也不能用“架构升级”作为脱离产品的独立目标。每项投入应对应降低的风险、减少的交付成本或新增的产品能力。

让边界进入验收

共享地图最终需要转成可验证结果。一个状态由谁创建、哪些角色能推进、失败后是否可恢复，都应成为验收条件，而不只检查正常路径页面是否完成。技术测试与产品验收由此围绕同一组事实。

针对分享能力，验收不只写“可以复制链接”，而会覆盖：

这些场景会自然带出缓存、时钟、幂等和审计问题。共享问题地图的价值，就是让产品边界在写代码前进入工程讨论。

当需求变化时，也先修改地图和状态约束，再评估页面与服务受到的影响。这样变更不会只停留在某一张设计稿，遗漏的数据迁移、通知和权限能更早出现。

当产品和技术共享同一张问题地图，架构不再是后台工作，需求也不再只是页面列表。团队讨论的是同一个系统，只是从不同角度观察。

图：产品与技术使用同一组约束，架构才不会各说各话。

这张地图需要被维护，否则三个月后就变成没人看的旧图纸。我维护它的方式是：每个用户任务连接到产品规则、数据实体、服务边界、SLO 和负责人；箭头写清同步、异步与失败恢复。需求变化时先改地图，再判断影响哪些契约和指标。

地图只保留决定边界的事实，不画每个类。它在产品评审、架构评审和事故复盘中使用，没人使用的图两个月后就删除。共享的价值来自共同决策，不来自图本身复杂。

跨市场产品让这个问题更明显：每个区域的支付、合规和弱网约束都必须进同一张图，否则“国际化”就成了前端文案的事。我在海外 ToC 产品中的前端不是一个页面层里用区域发布矩阵把这张图具体化了。

“在我的浏览器里正常”几乎没有意义，真实用户环境才是系统边界。

国际化从数据模型开始

国际化不是最后替换文案。日期、数字、货币、复数和文本方向都应通过统一格式层处理；布局不能依赖固定字符长度；服务端错误码与用户文案分离，避免后端直接返回某一种语言。

内容发布也需要版本与回退。当翻译缺失时，系统有明确的降级语言，不能让键名进入用户界面。

格式化必须晚于业务计算。服务端返回时间戳、币种和原始金额，前端根据用户区域展示：

const money = new Intl.NumberFormat(locale, {
  style: "currency",
  currency: invoice.currency,
  currencyDisplay: "narrowSymbol",
}).format(invoice.amountMinor / 100);
 
const createdAt = new Intl.DateTimeFormat(locale, {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: user.timeZone,
}).format(new Date(invoice.createdAt));

不能把 $ 默认理解成美元，也不能在服务端先格式化成 2025/07/26 再让各端猜日期。金额用最小货币单位保存，时间以明确时区的时间戳传输，展示层才有可靠输入。

文案长度也进入组件验收。按钮不固定宽度，表格列允许换行或截断并提供完整值，德语长复合词和阿拉伯语 RTL 至少进入视觉回归样本。国际化不是翻译团队交付后的最后检查。

体验需要分布数据

性能指标按地区、网络、设备和版本观察，整体平均值会掩盖重要长尾。静态资源使用 CDN，关键请求减少串行依赖，上传下载等长任务提供进度、暂停与恢复。

我会用相同版本按地区和设备分位观察，而不是只看全球平均：

LCP p75 by region + connection type
INP p75 by device memory bucket
API error rate by app version + country
upload completion rate by file size bucket

若全球 LCP 是 2.1 秒，某个核心市场的低端 Android 却达到 5 秒，平均值会给出错误结论。分段也不能无限细，否则每个桶样本太少；先围绕已知业务差异切分，再在异常桶里继续下钻。

大规模发布采用灰度和特性开关，把问题限制在较小范围。开关必须有负责人和清理日期，否则会变成永久条件分支。

错误恢复比错误提示更重要

网络中断、标签页关闭和设备存储不足都无法避免。长任务要保存可恢复状态，重复请求使用幂等标识，重新进入页面后能够继续，而不是要求用户从头开始。对于数据同步，界面应明确哪些已完成、哪些仍在等待。

大文件上传会先创建会话，客户端只保存会话 ID 和已确认分片：

type UploadCheckpoint = {
  uploadId: string;
  fileFingerprint: string;
  chunkSize: number;
  completedParts: number[];
  expiresAt: string;
};

重新进入页面后先向服务端查询已接收分片，再继续缺失部分。不能完全相信本地 checkpoint，因为用户可能换设备，服务端也可能清理过期会话。恢复协议必须以服务端事实校准。

错误文案根据用户动作解释下一步，不能只翻译服务端异常。地区与网络差异越大，产品越不能假设一次请求总会成功。恢复路径不是边缘体验，而是海外产品可靠性的主体。

面向大量个人用户时，前端承担的是产品运行时：它连接增长入口、账号状态、数据任务与错误恢复。架构价值最终体现在不同环境下仍然可靠完成用户目标。

图：语言只是表层，支付、合规、弱网和支持共同决定体验。

“支持更多国家”的正确粒度不是更多语言文件，而是一张区域发布矩阵。每个市场记录支付方式、税与价格展示、时区、弱网比例、隐私同意、客服时段、商店审核和关键设备。功能在一个国家成功，不代表换文案就能复制——法国市场支付失败的原因，往往在巴西根本不成立。

灰度按区域和版本稳定分桶，指标看支付完成、首个价值时刻、退款与支持工单，不只看注册。前端是这些本地约束交汇的地方，因此必须参与产品和服务端边界设计。

跨市场产品的另一面是：所有区域共享同一套领域事实，页面只是投影。产品与技术如何共用一张问题地图，在产品架构与技术架构应该共享同一张问题地图里展开。

我们把工具执行独立成权限网关。模型不持有密钥，也不能直接访问生产网络；它只提交结构化意图。网关用确定性规则决定参数是否有效、当前主体能否执行、是否需要审批以及怎样去重。

图 1：推理可以不确定，执行边界必须确定、最小授权并且可审计。

工具定义包含效果与风险

type ToolDefinition<Input, Output> = {
  name: string;
  version: number;
  inputSchema: JsonSchema<Input>;
  effect: "read" | "write" | "external_side_effect";
  risk: "low" | "medium" | "high";
  idempotency: "native" | "gateway" | "none";
  timeoutMs: number;
  execute(ctx: ToolContext, input: Input): Promise<Output>;
};

工具不是一段描述文字。版本、输入边界、副作用等级和幂等能力都进入注册表。模型请求不存在的字段会在 Schema 层失败，不会被执行器“尽量理解”。

策略基于主体、资源和上下文

type ToolContext = {
  actorId: string;
  tenantId: string;
  taskId: string;
  approvedScopes: string[];
  environment: "sandbox" | "production";
};

策略检查：用户是否能访问目标资源；任务契约是否允许该工具；环境是否匹配；参数影响范围是否超过限制；当前调用是否已有审批。模型说“用户要求我这么做”不是授权证据。

高风险审批绑定 planHash

Agent 先生成规范化计划，网关计算 hash。审批界面显示工具、资源、参数、预计影响和补偿动作。批准签名绑定 planHash；模型后来修改任何参数，都必须重新审批。

const canonicalPlan = stableStringify({
  tool: request.tool,
  version: request.version,
  input: request.input,
  tenantId: context.tenantId,
});
const planHash = sha256(canonicalPlan);

只批准一句自然语言“允许发邮件”范围太大，也无法证明实际执行内容与人看到的一致。

执行使用短期、下放权限的凭证

网关按单次调用向凭证服务申请几分钟有效、只允许指定资源和动作的 token。外部系统日志能识别真实 actor 与 taskId。长期密钥留在凭证服务，不进入模型上下文、工具结果或普通日志。

重试必须服从副作用语义

读工具可以有限重试；写工具需要 idempotencyKey；不支持幂等且结果未知的外部副作用不能自动重放，进入 unknown 状态等待查询或人工处理。

requested -> authorized -> executing -> succeeded
                               |-> failed_retryable
                               |-> failed_terminal
                               |-> outcome_unknown

网关保存规范化输入 hash、策略版本、审批、凭证范围、外部回执与耗时。工具输出回到模型前再做大小限制和敏感字段过滤，防止外部内容把秘密带入上下文。

这层网关看起来增加了延迟和代码，却让 Agent 从“拿着万能钥匙的脚本”变成一个受控调用方。模型擅长决定可能要做什么，真正执行仍需要软件工程里熟悉的 Schema、授权、事务、幂等和审计。

判断“哪些动作需要人在中途确认”不在网关内部完成，而在它上游的策略里：审批应该绑定不可变的执行计划、绑定 planHash、在计划变化时重新授权——这是人工审批不是弹窗整篇的内容。执行环境本身的隔离（文件、网络、密钥、资源）则是编码 Agent 的沙箱的主题，那里把这里的工具边界下沉到了进程级别。

最有效的分类不是“重要或不重要”，而是“可逆或不可逆”。

可逆决定快速行动

局部组件、日志库和内部工具通常可以替换。只要边界清楚，选择一个团队熟悉、能尽快交付的方案更合理。为这些决定写长篇评审，会让组织把时间花在低风险差异上。

不可逆或高迁移成本的决定需要更多关注：核心数据模型、公开 API、用户数据归属、任务状态语义和安全边界。一旦积累真实数据或外部依赖，修改成本会快速上升。

我会先给决定做一个粗粒度分类，不追求数学精确：

这张表阻止团队在低风险选择上争论一周，也提醒我不能用“两周 MVP”跳过数据删除和备份。速度的来源是把注意力投到正确位置，不是所有事情都少做。

保留证据和退出条件

决策记录不必很长，但要说明目标、约束、主要候选、选择理由和重新评估条件。例如当调用量达到某个范围，是否需要更换模型路由；当工作流复杂到何种程度，现有状态模型不再适用。

我实际使用的记录模板只有这些字段：

Decision: 任务状态持久化到关系数据库
Context: 任务跨多个模型与工具调用，进程重启后必须恢复
Constraints: 两周内上线；团队熟悉 PostgreSQL；当前规模不需事件平台
Alternatives: 进程内状态 / Redis / PostgreSQL
Choice: PostgreSQL 为事实源，队列只负责调度
Consequences: 状态转换需要事务；吞吐不是首要目标
Revisit when: 单任务事件量或并发达到现有写入瓶颈
Owner: workflow

Consequences 和 Revisit when 比“选择理由”更重要。它们承认决定有代价，也给未来改变留下正当入口。

创业速度不等于忽略质量。身份、数据安全、备份和核心流程恢复属于底线，不能以“以后再做”掩盖。其余质量则根据验证阶段分配。

团队理解也是迁移成本

某个方案即使技术上优秀，如果只有一人能维护，也会形成组织风险。选择需要考虑团队已有能力、学习时间和文档质量。关键系统至少应有第二个人能解释运行和恢复方式。

我会让第二个人在没有口头提示的情况下完成一次恢复演练：从告警找到任务、判断是否能重试、执行恢复并验证结果。只看过架构图不算掌握；能在压力较低的演练中走完整条路径，才说明知识没有锁在负责人脑中。

技术负责人不能把个人偏好包装成长期方向。对重要选择做小型原型，用真实任务比较，再公开记录取舍。这样未来改变决定时，团队是在更新假设，而不是推翻某个人的权威。

技术负责人最重要的工作不是选择最先进的技术，而是让团队知道哪些地方可以大胆试错，哪些边界必须谨慎保护。

图：有限注意力优先投入高影响、退出缓慢的选择。

实际操作中，我用一张可逆性表决定每个选择的讨论深度：影响半径、回退时间、数据迁移、外部绑定、验证窗口和最晚决定日。两小时能回退的 UI 库不占用一周会议；涉及客户数据格式和长期合同的选择必须留下 ADR 与退出方案。创业阶段最稀缺的是注意力，把判断精度用在不可逆和高影响处，比让所有技术决定都达到理论最优更重要。

两篇相邻的文章可以对照看：两周 MVP 里那些“能推迟就推迟”的功能，依据的是同一张可逆性表（见两周交付 AI MVP）；而决定一旦属于“必须记录”的那一档，留下证据的格式就是ADR 怎么写才有人看。

我们从客服记录、研究任务和失败反馈中整理了第一批 120 个问题。数据量不大，但每条都有来源、期望证据、权限条件和可接受回答标准。RAG 终于从主观演示变成可以回归的系统。

图 1：先判断证据有没有被找到，再判断模型有没有忠实使用；不能用一个总分掩盖不同失败。

数据集保留问题是怎样产生的

type RagCase = {
  id: string;
  question: string;
  userContext: { role: string; allowedDocumentIds: string[] };
  expectedEvidence: Array<{ documentId: string; sectionId: string }>;
  answerRubric: string[];
  mustRefuse: boolean;
  source: "support" | "research" | "production_failure";
  tags: string[];
};

问题文本会脱敏，但不能被改写成系统更容易回答的“标准问法”。口语、省略和错误术语恰恰是真实难度。数据集按版本保存，修改标准需要评审，不把不通过的用例悄悄删除。

检索与生成分开评分

如果期望证据没进入 top K，回答错误主要是检索问题；证据已经出现但模型忽略，才看提示与生成。

Recall@K = 命中的期望证据数 / 期望证据总数
MRR = 第一个正确证据排名的倒数
Citation precision = 被引用且真正支持结论的引用 / 全部引用

我们还记录“最小充分证据”：回答这个问题至少需要哪几段。否则检索返回一整本文档也能获得召回，却把成本和干扰留给模型。

权限错误比答错更严重

每条 case 携带用户可访问文档集合。评估在检索前注入权限，断言 top K 和引用中不出现越权文档。禁止先全局检索再在生成后过滤，因为标题、摘要和排名本身就可能泄漏信息。

评分器也需要被校准

LLM-as-judge 可以扩展评估，但它不是绝对真值。我们先让两位人工标注者独立评 50 条，解决 rubric 分歧，再比较 judge 与人工一致率。Judge 输入只包含问题、证据、回答和 rubric，不告诉它候选模型名称，减少偏好。

对数字、日期和实体关系，优先使用确定性检查；对解释完整性才用模型评分。所有低置信或发布边界附近用例进入人工复核。

回归报告必须能定位到配置变化

每次实验保存 corpus 版本、切分器、embedding、索引参数、reranker、提示版本和模型版本。报告不仅展示总分，还按问题标签、文档类型和失败阶段切片。

{
  "runId": "eval_20250419_07",
  "corpus": "finance-docs-v12",
  "chunker": "semantic-v4:600",
  "retriever": "hybrid-rrf-v3",
  "topK": 8,
  "prompt": "answer-with-citations-v9",
  "model": "pinned-model-version"
}

一次 chunk 调整让总分上升 2%，但“跨章节比较”标签下降 11%。如果只看平均值，我们会发布一个对关键研究任务更差的版本。

线上失败要回流，但不能污染测试集

用户点踩、人工修正和无答案请求进入候选池，经脱敏与标注后加入下一版数据集。用于日常调参的开发集和最终发布门禁集分开，避免团队无意中对固定答案过拟合。

这 120 个问题没有让 RAG 立刻变好，却改变了团队讨论方式。我们不再说“这个回答更自然”，而是能指出检索没找到证据、权限过滤太晚、引用不支持结论，或拒答边界错误。AI 系统能沉淀的第一份资产，往往不是提示词，而是一套来源真实、标准明确、可以反复运行的评估集。

有一件事我在早期吃过亏：评估集只覆盖“模型会不会答”，不覆盖“系统会不会发布”。把同样的用例接上发布流水线，用固定回归集做门禁、用影子流量验证真实分布，是从研究走向工程的那一步。这套完整流程在AI 功能怎么发布里，那里把 120 个问题变成了发布前置条件；评估任务本身的选型标准（频率、可验证性、错误后果）则来自AI 产品的起点不是模型能力。

MVP 不是缩小版完整产品。它应该用最少系统验证最大风险：用户是否愿意把真实研究材料交给产品，工作流能否产出可检查的结果，模型错误是否可以被发现和修正。

图 1：首版只打通一条真实、可追溯的垂直路径。平台化能力推迟到核心任务被证明以后。

第一天先写失败条件

开始前，我们没有列完整功能清单，而是写出两周后必须回答的问题：从一组指定材料出发，系统能否完成一个具体研究任务；结果是否带来源；用户能否看到并干预过程；一次任务的时间和成本是否可接受。

同时写出失败条件。若核心任务仍需大量手工补充、引用无法验证，或每次结果差异大到无法复用，那么界面再完整也不能证明方向成立。

明确失败条件能阻止团队用新增功能掩盖核心问题。登录方式、主题设置、复杂权限和完整计费都被推迟，只有直接影响验证的部分进入范围。

选择一条垂直路径

我们选取一种材料、一类任务和一种报告结构，打通从上传、解析、执行到结果查看的完整路径。没有先建设“通用 Agent 平台”，也没有支持所有文档与研究模板。

垂直路径必须是真实的，不能用静态数据伪造关键环节。文档确实经过解析，模型确实调用工具，结果确实保存并可重新打开。边缘场景可以少，主路径不能是演示脚本。

这条路径帮助团队很早发现系统级问题：长文档如何切分，引用如何对应原文，任务失败后状态如何保留。这些问题比主页设计更能决定产品方向。

架构只为当前风险服务

短周期常出现两个极端：完全不设计，所有逻辑写在接口里；或者担心未来重构，先搭建复杂平台。更合适的做法是只建立不会轻易消失的边界。

我们保留任务、节点、产物和来源四个核心模型。模型调用通过统一适配层，工作流状态持久化，前端只依赖稳定任务接口。至于节点市场、可视化编排和多租户配置，都不在 MVP 中。

数据库 Schema 优先表达事实，不追求覆盖未来所有角色。关键写操作保留版本与时间，方便排查。外部调用都有超时和错误分类，避免一个请求挂住整个服务。

这些基础并不昂贵，却让核心流程可以被观察和恢复。MVP 可以省略规模能力，不能省略理解失败所需的证据。

用现有能力换取时间

两周内不应该自建身份系统、对象存储、文档解析器和模型网关。优先使用稳定服务与成熟库，把团队时间留给领域工作流。

复用也有边界。选择第三方时，我们关注能否替换、数据是否可导出、故障时能否降级。MVP 不需要多云架构，但不能把核心数据锁在无法迁移的黑盒里。

UI 使用有限组件和明确布局，不建设完整设计系统。保持排版、间距和状态一致，比提供大量组件更重要。产品的专业感来自过程清楚和结果可信，不来自装饰数量。

每天交付可运行状态

短周期最怕最后几天才集成。我们把计划按可运行切片：第一天完成最小任务记录，随后接通单个模型节点，再加入文档来源、结果展示和失败恢复。每天结束时，主分支都有一条比昨天更完整的路径。

这样能提前暴露契约冲突，也能让产品判断建立在真实系统上。界面和服务端不各自等待“完成”，而是围绕同一个垂直路径交替推进。

每日复盘只回答三件事：今天验证了什么，发现了什么风险，明天最重要的未知是什么。任务数量不是进度，未知风险下降才是。

AI 功能必须可调试

传统接口输入确定，AI 节点可能因模型、提示词和上下文变化产生不同结果。MVP 如果只保存最终文本，出现问题时几乎无法改进。

每次执行记录工作流版本、模型、提示词版本、输入材料标识、工具调用和结构化产物。敏感原文按权限保存，不把所有内容写进普通日志。

用户看到的是简洁过程，开发视图则能比较不同执行。我们可以判断错误来自检索遗漏、上下文选择、工具失败还是模型生成，而不是统一归因于“模型不稳定”。

这种可调试性也支持快速迭代。修改提示词后，用固定样本重跑，比较引用覆盖、结构完整和人工评分，避免只凭一两个漂亮结果判断。

把人放进工作流

为了演示自动化，很容易让系统直接产出完整报告。但在高价值研究场景，用户需要控制范围、确认材料和修正中间判断。

我们在关键节点保留人工确认：解析后检查材料范围，形成提纲后允许调整，最终结论展示来源并支持回到原文。人机协作不是妥协，它是早期建立信任和收集反馈的方式。

人工步骤也帮助定义未来自动化边界。反复被用户直接通过的检查可以逐步自动化，经常被修改的节点则说明模型或任务定义尚不成熟。

延迟与成本要从第一天可见

AI 产品的单位经济性不能等规模化再考虑。一次任务调用多少模型、消耗多少 Token、等待多久，都会影响产品是否可持续。

我们为每个节点记录耗时和估算成本，界面给出过程反馈并允许取消。独立任务并行，非关键审阅可以按配置关闭。超出预算时，系统返回已完成产物并说明缺失，而不是无限继续。

早期用户可能容忍几分钟等待，但等待必须可理解。看到系统正在检索和分析，与面对一个没有状态的加载动画，是完全不同的体验。

上线标准不是功能完成

两周结束时，我们检查的不是需求列表勾选率，而是主路径能否由非开发者独立完成；失败后能否知道原因；结果能否追溯到来源；系统能否在新材料上重复工作。

还要明确哪些部分只是临时能力。MVP 的技术债如果被写下来、拥有触发条件和替换方案，就是有意识的借款；如果团队假装它不存在，就会在下一阶段变成惊喜。

首版上线后，最重要的产物不是代码，而是一组更清楚的问题：用户真正重视哪一步，哪些自动化不被信任，成本主要发生在哪里，什么能力值得继续投资。

速度来自清晰，而不是加班

短时间交付常被归因于团队更努力。努力当然重要，但持续速度主要来自范围清晰、决策链短、主路径统一，以及每天都能获得真实反馈。

当产品、设计、架构和工程由同一个小团队紧密完成时，信息传递成本很低，代价是每个决定都必须更克制。没有大团队替错误方向分摊成本。

两周 MVP 最终证明的，不是我们能多快写完一套系统，而是能多快找到值得继续建设的部分。速度的真正对象不是代码，而是认知。

执行时我会每天更新一张范围账本，只有四列：今天必须证明的假设、最小用户路径、暂时手工完成的部分、明确不做的能力。新增需求必须替换一项，而不是无条件叠加。两周结束时交付的不只是演示，还有真实输入样本、失败案例、用户反馈、成本与延迟数据，以及下一阶段是否值得投入的结论。MVP 的价值是减少不确定性，不是制造一套缩小版大系统。

短周期里“哪些决定要谨慎、哪些决定可以快”是分开的：核心数据模型和对外契约仍然要按不可逆决定对待，我在创业阶段的技术决策里用可逆性表给它们分配了不同的讨论深度。

但把角色写进提示词，并不会自动得到组织。多个 Agent 反而会带来更多状态、通信、成本和失败路径。如果没有控制面，系统只是多次模型调用的串联。

图 1：Agent 负责局部开放推理，控制面负责确定性的状态、预算、权限和恢复。各角色通过产物协作，不靠长对话维持一致。

先证明为什么需要多个 Agent

复杂任务不一定需要多 Agent。一个模型配合结构化工具调用，往往比角色网络更简单可靠。

我们只在三类情况考虑拆分：子任务需要明显不同的上下文或工具；子任务可以并行并独立验证；任务过程需要明确责任边界和中间产物。如果拆分只是为了让提示词看起来像团队，收益通常抵不过协调成本。

例如金融研究中，材料检索与财务指标计算适合分开。前者处理文档与来源，后者依赖结构化数据和确定公式。最终撰写可以消费两者的受控产物，而不是重新浏览全部原始上下文。

工作流拥有状态，Agent 不拥有流程

Agent 擅长在局部目标下推理和使用工具，但整个任务的生命周期应由确定性工作流控制。控制面知道当前节点、依赖、输入、输出、尝试次数和预算，Agent 只负责完成一个有边界的步骤。

我们把任务建模为有向图。节点可以是模型调用、确定性函数、人工确认或外部工具；边表达依赖和条件；运行状态持久化到数据库。这样进程重启后可以从已完成节点继续，而不是重新执行全部研究。

每个节点拥有稳定输入 Schema 和输出 Schema。模型输出先经过结构验证，缺失字段或引用格式错误会触发修复，而不是直接流入下游。自然语言仍然存在，但关键控制信息不依赖下游再次猜测。

我会把节点状态收敛成少量可枚举值，而不是用一段自然语言描述“Agent 似乎做到哪里了”。最小结构大致如下：

type NodeRun = {
  taskVersion: string;
  nodeId: string;
  status: "ready" | "running" | "waiting_user" | "succeeded" | "failed";
  inputHash: string;
  attempt: number;
  budget: { tokens: number; toolCalls: number; deadline: string };
  artifactIds: string[];
  error?: { kind: "transient" | "invalid_output" | "insufficient_evidence"; detail: string };
};

这段结构没有保存模型的完整思考，但足以回答工程上真正需要的问题：执行的是哪个版本、能否安全重试、已经产出什么、为什么停下来。

上下文要按任务分配

把所有历史对话、全部文档和所有 Agent 输出塞给每个节点，既昂贵又容易干扰推理。上下文工程的核心是为当前任务选择最少但充分的信息。

规划节点需要用户目标、可用工具与约束；检索节点需要查询意图和来源范围；分析节点需要经过筛选的事实与数据；撰写节点需要结论结构、证据和表达要求。

长材料先被切分和索引，再按问题检索。关键事实以结构化记忆保存，附带来源、时间和置信度。临时推理不会自动进入长期记忆，只有经过验证的产物才被提升。

上下文也要有版本。用户修改研究范围后，下游节点不能继续使用旧假设。通过任务版本与依赖哈希，可以判断哪些结果仍然有效，哪些必须重算。

通信使用产物，不使用角色对话

多 Agent 示例常让不同角色互相发送长消息，仿佛会议讨论。真实系统中，这会重复信息并放大误解。

更稳定的协作方式是传递明确产物：检索 Agent 输出带引用的材料列表，数据 Agent 输出指标表与计算依据，审阅 Agent 输出问题清单和通过状态。下游消费产物，不需要重放上游的全部思考。

共享黑板可以保存当前目标、已确认事实、未解决问题和产物索引。所有 Agent 读取同一份任务事实，但写入需要经过控制面验证，避免不同角色互相覆盖。

工具调用必须有安全边界

Agent 使用搜索、数据库、代码执行或文件系统时，模型输出不能直接成为无限制命令。工具层负责参数验证、权限、超时、速率限制和结果裁剪。

读操作与写操作分开授权，高风险动作需要人工确认。研究系统通常以读取为主，但导出、发送或修改外部数据仍应明确展示即将发生的动作。

工具返回错误要结构化：是否可重试、是否需要修改参数、是否缺少权限。把一段堆栈直接交给模型，可能让它在错误方向上反复尝试。

每次调用记录任务、节点、模型、工具、耗时和成本，但不保存不必要的敏感内容。审计日志既用于排障，也用于回答“这条结论是如何产生的”。

预算是系统状态的一部分

多 Agent 很容易形成调用乘法。一轮规划生成多个子任务，每个子任务继续反思和重试，成本与延迟会快速失控。

任务必须有总预算，包括模型调用次数、Token、工具次数和最长执行时间。节点获得局部预算，消耗接近上限时选择降级、请求用户缩小范围或返回当前最佳结果。

预算不是只为节省费用，它迫使工作流定义停止条件。没有停止条件的“继续思考”不等于更高质量，常常只是更多文字。

并行也需要限制。可以独立执行的检索任务并行能缩短时间，但过多并发会触发模型或数据源限流。调度器根据依赖、优先级与资源配额启动节点，而不是让 Agent 自由复制自己。

失败要能局部恢复

复杂工作流一定会失败：模型返回非法结构，数据源超时，引用无法访问，某个结论缺乏证据。可靠系统不应从头重跑。

节点执行采用幂等设计。相同任务版本与输入哈希对应同一执行，重试不会重复产生副作用。成功产物持久化，失败保留错误分类和尝试记录。

恢复策略按错误决定：临时网络错误自动退避；格式错误可以用约束更强的修复调用；证据不足返回规划节点补充检索；超过阈值进入人工确认。

人工不是工作流失败，而是一种正式节点。系统应展示需要判断的具体问题、已有证据和可选动作，用户确认后从原位置继续。

评估不能只看最终文风

最终报告读起来顺畅，可能仍然包含错误来源和遗漏数据。多 Agent 需要分层评估。

节点层检查结构合法率、工具成功率、引用覆盖和任务完成；工作流层检查总耗时、成本、重试与人工介入；结果层通过固定问题集评估事实正确、证据一致和任务价值。

对于关键计算，使用确定性程序复核，而不是让另一个模型“感觉是否正确”。对于来源，验证引用确实支持对应陈述。模型评审可以辅助发现表达和覆盖问题，不能成为唯一裁判。

线上失败样本进入评估集，每次提示词、模型或流程改变都运行回归。Agent 系统的行为受多项因素影响，没有稳定样本就无法知道优化是否真实。

可观测的是过程，不是思维链

调试系统并不需要暴露模型的私有推理。我们需要的是可执行过程：节点输入摘要、工具调用、结构化输出、状态转换、引用和错误。

界面以任务图展示进度，用户能看到正在检索、计算还是审阅，能展开中间产物，也能取消不再需要的分支。对开发者，追踪视图关联每次调用的版本、耗时和成本。

这种可观测性也改善产品信任。用户不必相信一个突然出现的答案，而是可以检查它使用了哪些材料，哪些步骤由确定程序完成，哪些判断仍有不确定性。

多 Agent 的价值在组织复杂度

多 Agent 不是让多个模型模拟一个公司。它的价值是把复杂任务拆成拥有清晰输入、工具与验证方式的工作单元，再由可靠控制面协调。

角色可以帮助模型理解局部目标，但系统边界必须由代码表达。自然语言负责开放推理，Schema 负责契约，工作流负责状态，工具层负责安全，评估负责反馈。

当这些基础设施不存在时，增加 Agent 只会增加不可预测性。当它们成立后，多 Agent 才可能在长周期、跨工具和可审计任务中产生真实价值。

具体到 Agent 之间的交接，我会要求使用结构化任务包：目标、输入 artifact、允许工具、已完成证据、未解决假设、预算和下一步验收。下游 Agent 不读取上游完整对话来猜任务：

outcome: 生成可评审的迁移计划
artifacts: [schema-v3.json, usage-scan.csv]
openQuestions: [删除字段是否仍有离线消费者]
allowedTools: [repo.read, metrics.query]
doneWhen: 风险与回滚步骤齐全

结构化交接同时降低上下文成本和责任模糊——这正是上下文工程里“最小共享事实”原则在 Agent 协作中的直接应用；工具侧的安全边界则在不要把生产密钥交给模型里单独记录。

真实研究任务不是生成一段文字，而是收集材料、验证来源、比较观点、形成判断并留下证据。模型输出只是其中一环。

找到高成本任务

我们先观察研究过程中哪些步骤重复、耗时且可以验证，例如从多份材料中提取指标、追踪同一事实的来源、按固定框架整理公司信息。开放式“帮我分析”很难评价，结构清楚的子任务更适合建立信任。

选择任务时同时考虑错误成本。低成本内容可以快速试错，影响投资判断的结论则必须保留人工复核和引用。

我们后来不用“模型效果好不好”筛任务，而是给候选任务写一张卡：

“从公告中提取指定指标并链接原文”得分通常高于“帮我判断这家公司是否值得投资”。前者边界窄、频率高、结果可核验；后者把证据选择、分析框架和风险偏好混在一个开放问题里，流畅回答反而容易制造错误信任。

把不确定性放进界面

普通软件习惯返回确定结果，大模型天然带有不确定性。产品不能用流畅文本掩盖这一点。答案应关联原始来源，区分事实与推断，信息不足时明确说不知道。

用户也需要控制任务范围、查看执行进度、修正中间结果，而不是只面对一个聊天输入框。

一条研究结论在界面里至少拆成四部分：

type ResearchClaim = {
  statement: string;
  kind: "fact" | "calculation" | "inference";
  citations: Array<{ documentId: string; page: number; quote: string }>;
  confidence: "high" | "medium" | "low";
  unresolved?: string[];
};

事实必须有引用；计算需要展示公式和输入；推断要和事实分开；信息不足则把缺口显示出来。confidence 不是模型随口给出的百分比，而是由引用覆盖、来源一致性和任务规则共同产生的离散结果。

先设计评估，再设计演示

每个核心任务都需要可以重复的样本与评价标准。提取任务看字段准确与来源覆盖，比较任务看关键差异是否遗漏，报告任务还要检查事实与引用一致。只问“回答看起来好不好”，团队会被语言流畅度误导。

评估集不必一开始很大，但要来自真实材料，并包含信息缺失、来源冲突和格式异常。每次更换模型、提示词或检索策略都重新运行。AI 产品只有拥有稳定反馈，迭代才不是围绕几个漂亮截图进行。

我们的评估样本会保存输入材料版本、期望字段、可接受变体和证据位置：

{
  "caseId": "metric-conflict-07",
  "question": "报告期内经营现金流是多少？",
  "expected": { "value": 128000000, "currency": "CNY", "period": "2024-Q4" },
  "requiredEvidence": [{ "document": "annual-report", "page": 86 }],
  "trap": "摘要页使用了累计口径，正文表格为单季口径"
}

这个样本同时测试检索、口径判断、结构化输出和引用。只比较最终数字，无法知道是碰巧答对还是证据链真的成立。

AI 产品的壁垒不会来自“接入了某个模型”。真正长期的能力是理解任务、组织上下文、验证结果，并让模型输出进入可负责的业务流程。

图：模型和提示放在失败合同之后，产品边界才稳定。

“失败合同”是我评估每个 AI 任务的第一步：证据不足时怎么拒答；工具超时是否重试；输出哪些字段必须有引用；用户如何修正；已经发生的副作用怎样补偿。提示词只负责在合同内组织模型行为。

我们用失败案例验收产品，而不是只演示最佳输入。能解释“不知道”“没有权限”和“结果未知”的系统，通常比偶尔给出惊艳答案的原型更接近可交付产品。这条线的后端工程化部分——评估集怎么做、门禁怎么设——在RAG 评估别再问“感觉怎么样”里展开。

有人用十年反复完成同一种任务，也有人在几年里不断扩大问题范围。资深不是速度更快的初级工程师，也不是会议里更有话语权的人。它是一组能在复杂环境中持续产生可靠结果的能力。

从接收问题到定义问题

早期工程师通常在明确任务中工作：实现页面、接入接口、修复错误。任务本身被假设为正确，完成标准也相对清楚。

复杂项目里，最昂贵的错误常发生在写代码之前。需求描述的是方案而不是目标，团队可能花几周准确实现一个不需要存在的功能。资深工程师会先问：谁遇到了什么问题，当前成本是什么，什么证据说明值得解决。

这不是用问题拖延行动，而是缩小错误方向的投入。一个好的重新定义，可能把“建设一套配置平台”变成“先消除三个重复流程”，让团队用更小代价验证价值。

定义问题还包括识别约束。时间、人员、已有系统、合规和维护能力都会影响答案。离开约束讨论“最佳实践”，往往只是在展示知识。

我会把需求从方案改写成一页问题说明：

Observed problem: 新项目从申请到首次可部署平均经过多个手工环节
Users: 需要创建项目的研发负责人
Current evidence: 重复填写仓库、构建、权限和通知配置
Constraints: 不能替换现有 Git 与部署系统；平台团队维护能力有限
Success: 默认项目无需线下沟通即可进入测试环境
Non-goals: 本阶段不建设通用工作流设计器

这份说明让“做一个研发平台”缩成一条可验证路径，也阻止团队因为技术兴趣提前建设节点市场和可视化编排。

从局部实现到系统结果

资深工程师不会只保证自己提交的代码正确。他会沿着结果向上下游观察：数据契约是否稳定，发布是否可回滚，监控能否发现失败，使用者是否真正完成任务。

这不意味着越权承担所有工作，而是能看到边界之间的空隙。系统故障经常发生在“这不归我负责”的地方。有人需要把局部团队重新连接到共同结果。

系统思维也要求理解二阶影响。加一层缓存能提高响应速度，也会引入失效和一致性；增加通用配置能覆盖更多场景，也会扩大测试组合；提高自动化程度，也会让错误更快传播。

成熟的方案不只描述收益，还主动写出新风险以及如何控制。

例如为接口增加缓存，方案至少要同时说明：

资深不是知道“用 Redis”，而是能把这笔交换讲完整，并在系统运行后检查假设是否成立。

判断什么不做

初学阶段，能力通过“能做什么”体现；走向资深后，价值越来越体现在“知道什么不值得做”。

技术世界持续产生新框架、新范式和更漂亮的架构图。把它们引入项目很容易带来短期兴奋，也可能让团队承担多年维护成本。资深工程师需要区分学习价值与生产价值。

拒绝也不能依赖权威。要说明目标为何不匹配、现有方案的真实瓶颈在哪里、替代路径是什么。如果反对只是“以前没这么做过”，那是保守；如果反对建立在成本与证据上，才是判断。

同样，技术债不是所有不完美代码。系统中存在很多局部粗糙，只要它稳定、低频、不会阻碍变化，就可能不值得重写。重构资源应该投向持续制造风险和摩擦的地方。

把不确定性显式化

复杂问题很少有完整信息。资深不意味着永远知道答案，而是知道哪些是假设、哪些需要验证、什么情况下应该改变方向。

设计方案时，可以把决定分为可逆与不可逆。可逆决定快速试验，通过数据修正；涉及公共协议、数据模型和长期绑定的决定，则投入更多评审和原型。

风险也应当有优先级。列出所有可能问题没有意义，需要估计发生概率、影响范围和发现难度。最值得提前处理的，往往是影响大且上线后难以察觉的错误。

我会把风险粗分成三维：影响、发生可能和可探测性。支付重复扣款即使概率低，也因为影响大且不能依赖用户发现而需要幂等和对账；内部报表一个可恢复的样式错位，通常不值得同等级投入。

这种分级会直接改变验证方式：高风险数据变更用备份、影子读取和分阶段切换；局部可逆 UI 变化用视觉回归和快速回滚。测试数量不需要平均分配，监督强度应该跟随后果。

当信息不足时，诚实表达置信度比强行给出确定答案更专业。“目前基于这些事实选择 A，如果指标 X 变化则转向 B”，比“行业都这么做”更可执行。

让团队获得能力

个人解决一个难题有价值，让团队以后都能解决同类问题更有价值。资深工程师会把一次经验沉淀为工具、约定、示例和判断框架。

但沉淀不是写一份没人阅读的长文档。知识要进入工作流：脚手架提供默认结构，CI 自动检查规则，组件库表达交互契约，故障手册连接告警和行动。正确路径应该更容易被采用。

技术负责人还要避免自己成为所有决策的中心。团队成员需要拥有完整上下文和适当决策权。负责人评审高风险边界，建立原则，并在结果不理想时承担责任，而不是逐行控制实现。

培养能力意味着允许可控范围内的不同做法。只接受与自己相同的方案，最终得到的不是一致团队，而是一组等待指令的人。

沟通是工程的一部分

架构无法只存在于一个人的脑中。一个方案如果无法让产品、设计、服务端和运维理解，就很难在真实组织里成立。

不同角色关心不同问题。面对业务，需要解释成本、风险和交付路径；面对工程师，需要明确契约、状态和失败模式；面对管理者，需要说明投入如何对应结果。改变表达不是降低专业性，而是建立共同决策所需的接口。

高质量沟通也包括书写。设计文档保存上下文，决策记录解释为何选择，复盘把事故转成系统改进。口头结论会消失，文字让后来者能重新检查假设。

会议数量不是沟通质量。能够异步说清楚的问题不必开会，需要多方权衡的决定则应让关键人同时出现。沟通的目标是减少误解和等待，而不是制造存在感。

对后果负责

资深最重要的变化，是从“我的实现没有问题”走向“最终结果由我共同负责”。系统上线后表现不佳，不能只证明代码符合需求；团队方向错误，也不能只说自己早已提出风险。

负责不等于独自背负。它意味着在问题暴露时先恢复系统，再讨论归因；在项目推进时主动补齐缺口；在承诺无法兑现时尽早沟通，而不是等最后一天解释。

责任还包括对长期维护者友好。今天聪明的实现，如果只有作者能修改，就是把成本留给未来。清晰、可测试、可观察和可回滚，都是对后果负责的形式。

保持一线，但改变写代码的目的

承担架构和团队职责后，写代码的时间可能减少。完全离开实现，会让判断逐渐失去现实感；继续抢走所有关键代码，又会阻碍团队成长。

我更愿意选择高杠杆的一线工作：验证风险最大的技术假设，搭建能被团队扩展的骨架，修复暴露系统性问题的缺陷，或亲自走完整个发布与排障链路。

写代码不再为了证明产出，而是为了获得真实反馈，并把复杂路径走通。其余实现交给最接近上下文的人，并通过评审保持系统方向。

资深是一种持续校准

没有人因为达到某个职级就永久拥有正确判断。业务会变化，技术会变化，曾经有效的经验也可能成为偏见。

真正可靠的资深工程师，会持续接触一线事实，愿意被数据和更好的论证修正。他拥有原则，但不把原则变成教条；相信经验，也知道经验的适用范围。

从机械专业自学编程，到前端、Node.js、工程平台和复杂数据系统，我学到的技术很多已经更替。留下来的不是 API，而是一些越来越稳定的习惯：先定义问题，寻找主要约束，让失败可见，为未来变化保留边界。

经验年限只是背景。资深真正意味着，在信息不完整、利益有冲突、系统会失败的现实里，仍然能与团队一起做出足够好的决定，并为结果负责。

图：经历只有沉淀成别人可使用的能力，才产生组织杠杆。

沉淀时我会用证据组合代替“负责过”。四类成果值得记录：亲手解决的复杂问题；建立后被他人持续使用的机制；培养后能独立负责的同事；主动停止或简化的错误方向。每项都链接变更前后指标、文档或真实使用者。这能防止履历只剩项目名和角色——资深不是离代码更远，而是能把一次判断变成系统、工具和团队都能继续复用的能力。

把“机制被他人使用”变成可检查的标准，需要回答更深一层的问题：哪种产出值得自动化为门禁，哪种只配留在文档。我在资深工程师的产出里用“修复、反馈、恢复路径、默认能力”四层来分，避免把每个重复问题都解释成“缺少平台”。

我们开始写 Architecture Decision Record。它不是架构说明书，也不是会议转录，只保存当时为什么做这个选择、承担什么代价、什么变化会让它需要重审。

图 1：决定的寿命往往比参与会议的人长，必须保留当时的约束和反证条件。

一页 ADR 的最小结构

# ADR-017: 任务调度继续使用 PostgreSQL 租约表
 
状态: Accepted
日期: 2024-10-19
负责人: Platform
 
## Context
当前峰值 40 jobs/s；要求事务内创建任务；团队无 Kafka 运维经验。
 
## Options
1. PostgreSQL lease table
2. Redis Streams
3. Kafka
 
## Decision
未来两个季度继续使用 PostgreSQL，补充索引、租约回收和容量指标。
 
## Consequences
接受轮询成本和单库容量上限；暂不承担新中间件运维成本。
 
## Revisit when
持续 15 分钟超过 200 jobs/s，或跨区域消费成为硬需求。

上下文里写量级和组织能力，比“PostgreSQL 简单”更有用。规模变化后，旧结论可能自然失效。

备选方案必须真实可选

为了证明自己的选择正确而列一个明显荒谬的对手，没有决策价值。每个选项写同一组维度：可靠性语义、吞吐与延迟、事务边界、运维成本、迁移成本、团队熟悉度和退出路径。

反对意见不要被会议结论抹掉

ADR 里保留主要反对理由和为什么仍未选择。Kafka 方案支持者担心两年后迁移更贵，这是合理风险；我们把它转成复审触发器和接口约束：业务层不依赖 PostgreSQL 表结构，任务协议保持可迁移。

决定要连接到执行证据

ADR 链接实现 PR、仪表盘和后续事故。代码中重要边界可以引用 ADR 编号，监控直接展示复审指标。当吞吐连续接近触发器时，自动创建技术任务，而不是等某个人想起旧文档。

状态不是只有 Accepted/Rejected。被新决定替代时标记 Superseded 并链接新 ADR；试验性选择用 Proposed；明确放弃的方案用 Rejected 并保留原因。不要修改旧 ADR 伪装历史一直正确。

不是什么都值得写 ADR

可轻易回退、影响范围小、遵循现有标准的选择不需要文档。ADR 留给跨团队、长期、昂贵或难逆的决定。数量太多会淹没真正重要的判断。

使用一段时间后，最直接的收益不是少开会，而是新成员能理解“为什么现在这样”，并知道哪些条件变化后可以合理挑战它。好文档不是阻止未来推翻决定，而是让未来的人不必先重演过去的全部争论。

ADR 也会过时。被新决定替代时标记 Superseded 并链接新 ADR；明确放弃的方案保留原因；复审触发器被触发过但没有跟进，是记录失效的最早信号。决定的价值在写下那一刻只是开始，后续每次重审都在更新它。这个“决定 → 利息 → 触发器 → 重审”的循环，在架构债务不是旧代码里有更完整的模型——那里把复审条件从文档变成了可监控的指标。

对负责人而言，ADR 还有一个附加作用：它让“这个决定当时为什么这么做”脱离个人记忆，团队不必事事等我解释。这与技术负责人的边界里把决定权下放给最接近问题的人，是同一套分权机制的两半。

如果负责人休假就无法做决定，说明系统依赖了个人，而不是建立了能力。

决策分级

不是每个决定都需要同样参与。影响公共协议、数据模型和长期成本的选择应共同评审；局部可逆实现交给最近问题的人决定；已有原则能覆盖的事情，不再重复开会。

负责人要提供的是上下文和标准：目标是什么，不能破坏什么，如何验证。结论可以由不同成员产生。

我后来用“影响范围 × 可逆性”给决定分级：

这张表减少了两种浪费：局部 CSS 实现不再排队等我拍板，核心数据模型也不会在 PR 最后一刻才被发现。技术负责人把精力放到决策成本真正高的地方。

评审关注风险而非控制

代码评审不应要求所有代码都写成负责人的风格。重点是行为正确、边界清楚、风险可控。对于复杂改动，提前评审设计比最后逐行挑选更有效。

设计评审我只要求一页能回答的问题，不鼓励用文档长度制造安全感：

要改变的用户/系统行为是什么？
必须保持哪些不变量？
数据和状态由谁拥有？
失败后如何恢复？
如何观察结果并判断方案有效？
什么信号出现时要撤回或重做？

评审结束要留下决定、反对意见和后续验证，不保存一份“大家讨论过”的会议纪要。这样没有参会的人也能沿证据重新判断。

事故发生时，负责人承担协调与结果责任，但不应该独占排查。让成员参与完整过程，复盘改进系统而不是寻找个人错误，团队才会形成下一次独立处理的能力。

上下文要公开流动

很多“必须由负责人决定”的问题，实际是信息只集中在负责人手里。把业务目标、架构约束和历史决策写进团队可访问的位置，成员才有可能独立判断。会议中的关键结论也要留下记录，不能依赖谁恰好在场。

信息公开不等于把所有细节推给每个人。负责人应提炼当前决定真正需要的上下文，并说明哪些边界不可突破。清晰上下文与明确授权同时存在，分布式决策才不会变成各自为政。

领导力不是让自己不可替代，而是让团队在没有即时指令时仍能做出一致、可靠的判断。

图：优秀负责人降低团队等待，而不是让所有决定汇聚到自己。

这套分权要能运行，前提是团队知道什么必须找我。我会公开自己的升级规则：跨团队不可逆决定、生产高风险操作、连续两次无法收敛的故障必须升级；普通实现选择由最接近上下文的人决定，并通过 ADR 或评审留下证据。

我每周检查自己是否成为等待点：多少 PR、发布和方案必须等我；哪些决定可以通过原则、工具或授权下放。技术负责人真正的杠杆，是让系统在自己不在线时仍能做出合格判断。

两条配套实践在这里没有展开：决定怎样留下证据、反对意见怎样不被会议抹掉，属于ADR 怎么写才有人看；把个人经验沉淀为团队默认能力的分层标准，属于资深工程师的产出，不应该只存在于代码仓库。

后来接入 OpenTelemetry 时，我们没有只给 HTTP 自动埋点，而是明确规定上下文怎样进入消息头、怎样在 Worker 恢复，以及异步重试如何表达新的执行尝试。

图 1：队列不是追踪终点；生产 span 与消费 span 通过消息上下文关联。

traceId 与 jobId 解决不同问题

traceId 描述一次执行链，适合性能和错误定位；jobId 描述长期业务任务，跨重试、暂停和人工恢复保持稳定。一次 Job 可能对应多个 trace。

type ExportMessage = {
  jobId: string;
  attempt: number;
  tenantId: string;
  payload: ExportInput;
};

trace context 放消息 headers，不混入业务 payload。日志同时记录 traceId、spanId、jobId 和 attempt，既能沿执行链看时间，也能汇总任务历史。

生产消息时注入上下文

import { context, propagation, trace } from "@opentelemetry/api";
 
const headers: Record<string, string> = {};
propagation.inject(context.active(), headers);
 
await queue.publish("export.requested", message, { headers });

消息中间件可能只接受字符串 header，需要显式序列化。不要把整个上下文对象 JSON 化，因为标准传播字段和采样标志需要被其他语言理解。

消费时恢复，但不伪造同步父子关系

队列消息可能等待很久、被多个消费者处理或批量消费。我们根据语义选择 parent 或 link。一次普通单消费可以以提取上下文为父：

const parent = propagation.extract(context.active(), delivery.headers);
 
await context.with(parent, async () => {
  const tracer = trace.getTracer("export-worker");
  return tracer.startActiveSpan("export.process", async span => {
    try {
      await processExport(delivery.message);
      span.setStatus({ code: 1 });
    } catch (error) {
      span.recordException(error as Error);
      throw error;
    } finally {
      span.end();
    }
  });
});

批处理由多个消息共同触发时，更适合新建 span 并链接多个来源，避免假装只有一个父节点。

采样不能让错误证据全部消失

全量 trace 成本太高，我们对普通成功请求低比例采样，对高风险任务和错误提高保留率。头部采样在请求开始时决定，无法预知后续失败；因此 Collector 还使用尾部采样，根据错误、长延迟和关键属性决定保留整条 trace。

上下文传播也要做契约测试

我们在集成环境发送带已知 traceparent 的消息，断言 Worker span 与其关联；重试产生新 span 但 jobId 不变；死信记录最后 traceId；日志能够从 trace 跳到 job 页面，再从 job 页面列出所有 attempts。

链路接通后，那类“API 成功、后台失败”的问题不再靠时间猜测。更重要的是，我们没有把 traceId 当万能业务 ID。追踪关注一次执行，业务模型关注一个长期任务；把两者同时保留，系统才既能诊断性能，也能解释用户结果。

这两类 ID 的边界会在 Agent 场景里被进一步放大：模型的一次调用既是执行链的一部分，又是一个需要审批、重试和补偿的长期任务。我在人工审批不是弹窗里把 planId、taskId 与执行尝试分离开，正是同一原则在事务边界的延伸。可观测性的整体组织方式则在可观测性不是一块 Grafana 大屏里展开。

收益来自减少工作，代价来自必须可靠地判断“什么变了”。

标识比比较更重要

没有稳定主键，只能按位置或完整对象比较。排序变化会被误认为所有行都改变，深比较本身也可能比重绘更贵。数据模型需要提供稳定标识和版本，更新算法才能保持简单。

我们先用映射建立旧数据索引，再生成新增、更新和删除集合。字段变化还要区分是否影响视觉，例如后台元数据变化不需要重绘图形。

一个 O(n) 的基础实现足以覆盖大多数表格和图元：

type Row = { id: string; version: number; value: number; label: string };
 
function diffRows(previous: Row[], next: Row[]) {
  const before = new Map(previous.map((row) => [row.id, row]));
  const added: Row[] = [];
  const updated: Row[] = [];
 
  for (const row of next) {
    const old = before.get(row.id);
    if (!old) added.push(row);
    else if (old.version !== row.version) updated.push(row);
    before.delete(row.id);
  }
 
  return { added, updated, removedIds: [...before.keys()] };
}

这里依赖服务端提供单调版本。如果只能深比较对象，首先要确认比较成本和数据语义；JSON.stringify 会受字段顺序影响，也会把和视觉无关的元数据变化算成更新。

什么时候放弃增量

变化比例很高、排序规则改变或图表配置变化时，完整重建反而更可靠。系统应设置阈值，在增量成本接近全量时切换策略，而不是执着于每次最小修改。

我会记录 changed / total、diff 耗时和渲染耗时，再决定阈值。假设 60% 数据变化时，增量路径既要维护索引，又要执行大量局部操作，往往不如一次全量替换。阈值不是固定经验值，而是当前渲染器和数据规模下的测量结果。

const changeRatio = (added.length + updated.length + removedIds.length) / next.length;
if (changeRatio > 0.45 || sortChanged || schemaChanged) {
  renderer.replaceAll(next);
} else {
  renderer.applyPatch({ added, updated, removedIds });
}

差量路径与全量路径必须得到一致结果。测试用随机变化序列同时执行两种策略，比较最终状态，可以发现遗漏删除、顺序错误和缓存失效问题。

这类测试适合属性测试：随机生成增加、删除、更新和重排序列，让增量状态与 replaceAll 后的状态做深比较。全量路径虽然慢，却是很好的参照实现；没有这条校准路径，增量缓存一旦漂移就很难自证。

先减少进入更新的数据

有时最有效的差量并不在 DOM 层。接口若能返回版本或变更游标，前端就不必先下载完整数据再比较；状态管理层若保留结构共享，组件也能快速判断哪些分支未变。越靠近数据源识别变化，后续各层浪费越少。

但端到端增量需要协议支持。丢失一段变更时必须能够重新同步全量，版本不连续要被发现。增量是一条快路径，全量仍是校准事实和恢复系统的基准路径。

性能优化总会交换复杂度。只有测量证明重绘是主要瓶颈，并且数据拥有稳定身份时，差量更新才是一笔值得做的交易。

图：任何版本缺口或 hash 不一致都必须回到可信基线。

差量协议必须守住三个不变量：同一 patch 重放结果不变；任何版本缺口都能回退全量；应用 patch 后的内容 hash 能与服务端目标 hash 对齐。客户端不满足任一项就停止继续增量，重新拉取基线。

上线时同时观察差量命中率、回退全量率、hash 不一致和节省字节。只看带宽下降，会忽略客户端状态逐渐偏离这个更危险的问题——增量路径的正确性只能由全量基线证明，这也是“全量路径必须保留”的原因。

在报表场景里，diff 之前还有一层：数据本身可以先按版本和变化游标交付，让前端不必下载完整快照再比较。这个思路与十万级数据渲染里按像素聚合、按需取数的预算思想一致——先减少进入系统的数据，再优化对已有数据的处理。

图 1：仪表盘用于探索，告警必须指向行动，复盘则同时修正系统和信号。

从问题反推信号

每个指标都应回答一个运营问题。请求量、错误率和延迟说明服务是否健康；任务等待时间和重试次数说明队列是否积压；业务流程完成率说明系统是否仍在交付价值。

我通常先写服务级目标，再决定采集什么。以发布平台为例，可以先定义：在 30 天窗口内，99.5% 的发布任务应在 15 分钟内进入成功、失败或等待人工状态；不能永久停在运行中。

这个目标拆成两个可计算信号：终态率和完成时长。Prometheus 查询可以从业务状态出发，而不是先看 CPU：

sum(rate(release_job_terminal_total[5m]))
/
sum(rate(release_job_created_total[5m]))

histogram_quantile(
  0.95,
  sum by (le) (rate(release_job_duration_seconds_bucket[15m]))
)

比值异常后，再沿任务队列等待、Worker 执行和外部部署接口查看资源信号。调查顺序和用户路径一致，仪表盘就不再是一组互不相关的系统图。

资源指标用于解释原因，业务指标用于判断影响。只看 CPU 很难知道用户是否无法发布，只看成功率又无法定位瓶颈。

日志应带有请求或任务标识，使一次流程可以跨服务串联。错误日志记录上下文和分类，但避免敏感数据与无界对象。追踪只在关键链路采样，不能为了完整而制造新的成本。

一次任务至少需要关联这些字段：

{
  "traceId": "tr_7a2f",
  "taskId": "release_812",
  "step": "deploy",
  "attempt": 2,
  "kind": "dependency_timeout",
  "dependency": "cluster-api",
  "durationMs": 5012
}

日志里不直接写完整部署参数和 Token。需要复原输入时，通过 taskId 到受权限控制的业务存储查询。日志负责索引事件，不应该成为影子数据库。

告警必须指向行动

告警阈值要考虑持续时间和业务基线，瞬时波动不应唤醒所有人。每条告警都需要负责人、影响说明和第一步检查入口；无人处理的告警应该删除或降级。

我会把告警说明和代码一起版本化：

alert: ReleaseTerminalRateLow
for: 10m
severity: page
owner: developer-platform
impact: 用户发布任务无法进入可解释终态
runbook: /runbooks/release-terminal-rate

for: 10m 避免单个采集周期波动直接呼叫值班；Runbook 第一屏先给查询路径和止损动作，而不是从系统历史讲起。一次告警若无法指向任何动作，它更适合做仪表盘信号，而不是打断人。

仪表盘用于探索，告警用于行动，复盘用于修正系统。三者通过相同信号连接，才形成真正的可观测性闭环。

从一次故障验证监控

监控体系是否有效，最好用真实故障或演练检查。隐藏一个下游依赖、制造任务积压，观察团队多快发现、能否判断用户影响、是否找到相关日志。如果只能通过熟悉系统的人凭经验定位，说明信号仍未形成路径。

复盘后不仅增加指标，也要删除无用面板、修正阈值和补充行动说明。可观测性与代码一样会老化，服务拆分、流量模式和业务目标改变后，过去重要的信号可能只剩噪声。持续维护信号质量，才不会在需要时面对一面失真的仪表墙。

告警还必须走完关闭闭环。告警关闭时必须选择：用户影响结束、指标误报、已知维护或尚未解决但转为长期任务；同时记录止损动作和后续 owner。没有结局的告警会不断重复消耗注意力。月度复盘看重复根因、无行动分页占比、从发现到止损的时间，以及 Runbook 是否真的被使用。可观测性的产出不是图表数量，而是更短、更确定的恢复路径。

这条链路的上游是告警如何被触发：用户结果怎样变成 SLO、错误预算和燃烧率，我在告警为什么总在半夜吵醒错误的人里单独记录过。

2024 年我们开始从用户结果定义 SLO，再用错误预算燃烧率决定告警。资源指标仍然保留，但更多用于诊断，而不是直接把人叫醒。

图 1：一条值得打断人的告警，应该说明用户结果正在以多快速度恶化，以及谁能做什么。

先定义用户看到的成功

以“创建报表”为例，成功不是 HTTP 200，而是用户在 30 秒内得到可打开的报表，且数据查询完成。请求被网关接受但异步任务最终失败，不能计为成功。

SLI = 30 秒内完成且结果可读取的创建次数 / 有效创建请求数
SLO = 30 天滚动窗口内 SLI >= 99.9%

有效请求排除明显非法输入，但不排除服务端权限判断或依赖失败。排除规则必须稳定，否则团队可以通过改变分母“优化”SLO。

错误预算把可靠性变成可消耗资源

99.9% 月度 SLO 意味着 0.1% 失败预算。燃烧率表示当前速度相对预算允许速度的倍数。短窗口高燃烧代表突发事故，长窗口持续燃烧代表慢性问题。

(
  sum(rate(report_create_total{result!="success"}[5m]))
  /
  sum(rate(report_create_total[5m]))
) / 0.001

生产规则使用 5m/1h 和 30m/6h 等多窗口组合：短、长窗口同时超过阈值才分页，降低一瞬间毛刺带来的噪声。

用数字说明会更具体。月度 99.9% 的 SLO 对应错误预算 0.1%，即 30 天里允许约 43 分钟失败。一次持续 10 分钟、错误率 6% 的事件，5 分钟窗口的燃烧率是 60 倍，足以分页；同一事件摊到 1 小时窗口只剩 10 倍。两个窗口不是重复报警，而是区分“正在发生的事故”和“一瞬间的毛刺”。

告警内容必须支持第一步行动

每条告警包含：受影响用户结果、开始时间、当前燃烧率、主要维度、最近发布、负责人、仪表盘和 Runbook。不要只发一条“error rate high”。

Runbook 的第一屏回答：如何确认影响；最快止损动作；哪些操作有风险；需要升级给谁。长篇原理放在后面。事故中人的工作记忆很有限，文档要按执行顺序写。

按所有权路由，而不是按技术栈

登录 SLO 由身份团队负责，即使根因发生在 Redis；报表创建由报表团队负责，即使错误来自队列。拥有用户结果的团队先接警，再根据 trace 与依赖图升级。按“数据库群”“Node.js 群”广播，通常会让每个人都以为别人会处理。

每次告警都要有结局

我们给告警记录分类：真实事故、已知维护、阈值不合理、数据错误、无行动价值。每月看分页数量、确认时间、无行动占比和重复根因。无法导致任何动作的告警要降级或删除。

改造后值班并没有变得轻松，而是打断更少、每次打断更接近真实用户影响。SLO 的价值不是制造一个新的百分比，而是让团队明确什么结果值得保护，并把注意力留给正在快速消耗可靠性预算的问题。告警只是这条链路的一环：从用户结果定义信号、再到告警关闭后的复盘闭环，完整的做法在可观测性不是一块 Grafana 大屏里展开。

优雅退出不是一个 process.on('SIGTERM') 日志，而是入口、在途工作和资源连接之间的协议。

图 1：先让外部世界知道“不要再给我新工作”，再处理已经承诺的工作，最后关闭依赖。

信号到达后先进入 draining

let draining = false;
 
app.get("/health/ready", (_req, res) => {
  if (draining) return res.status(503).json({ ready: false, reason: "draining" });
  res.json({ ready: true });
});

收到 SIGTERM 立即把 readiness 变为失败，让 Kubernetes 从 Service Endpoint 移除实例。这个传播需要时间，因此还要停止 HTTP server 接受新连接，并等待已有连接完成。

const server = app.listen(port);
 
function stopAcceptingRequests() {
  return new Promise<void>((resolve, reject) => {
    server.close(error => error ? reject(error) : resolve());
  });
}

Keep-Alive 连接可能延长等待。运行时需要跟踪 socket，在软超时后通知关闭空闲连接，硬超时才强制销毁。

队列消费者先暂停领取

Worker 收到信号后停止领取新任务，当前任务根据语义选择完成或归还租约。不能先关闭 Redis，再尝试更新任务状态。

async function drainWorkers() {
  await worker.pause(true);
  await waitForActiveJobs({ timeoutMs: 20_000 });
}

支付、发布这类有副作用任务必须有幂等和租约；即使硬超时杀进程，下一实例也能安全接管。优雅退出降低中断概率，不是替代任务可靠性。

资源关闭按依赖方向逆序

启动顺序通常是数据库/Redis → 仓储 → 服务 → HTTP/Worker，关闭反过来：入口 → 业务工作 → 日志/遥测 → Redis/数据库。业务还在运行时先断数据库，只会制造新的失败。

async function shutdown(signal: string) {
  if (draining) return;
  draining = true;
 
  const hardStop = setTimeout(() => process.exit(1), 30_000).unref();
  try {
    await stopAcceptingRequests();
    await drainWorkers();
    await telemetry.flush();
    await redis.quit();
    await database.close();
    clearTimeout(hardStop);
    process.exit(0);
  } catch (error) {
    logger.error("shutdown_failed", { signal, error });
    process.exit(1);
  }
}

时间预算必须小于平台终止窗口

总预算不能超过 Kubernetes terminationGracePeriodSeconds。平台在 30 秒杀进程，应用内部设计 60 秒等待没有意义。

图 2：预算不是平均分配，而是先给“让外部世界停止投递”留足时间，业务收尾才真正开始。

每个阶段还有各自的降级动作，不是排队等待超时才一起放弃：Endpoint 摘除超时，HTTP 层直接拒绝新请求；HTTP 超时，剩余 socket 强制关闭；队列任务超时，归还租约允许其他 Worker 重投。逐段降级让最坏情况也只损失最远的一段工作，而不是全部等待被一个卡住的阶段耗尽。

用真实信号做集成测试

我们在测试环境持续发送请求和队列任务，向进程发送 SIGTERM，断言：readiness 先失败；新请求不再进入；已接收请求有明确结果；任务不丢且不会产生不可接受重复；退出码和耗时被记录。

上线后观察发布窗口的 502、任务 lease 过期、强制退出数和 shutdown 各阶段耗时。只有应用、负载均衡和编排平台的时间线能对齐，优雅退出才不是一段看起来完整的 finally。队列连接关闭时如果还持有任务状态，那就是另一类泄漏——Node.js 内存泄漏排查里记录的实例生命周期问题，和这里的关闭顺序是同一个原则的两面。

但在真实 BI 页面里，虚拟列表只解决了最后一段。数据下载、解析、排序、聚合、格式化和图表转换都可能先把主线程占满。页面没有生成很多 DOM，用户仍然会感觉冻结。

优化之前必须把完整管线拆开。

图 1：虚拟列表只解决最后一段。数据规模、解析、计算、布局和绘制都需要独立预算。

建立数据预算

第一步不是写代码，而是确认产品真的需要在浏览器中持有十万条明细。用户要完成的是浏览、搜索、比较还是导出？多数场景只需要聚合结果或当前窗口数据，完整数据应留在服务端。

我们为不同组件定义数据预算：图表有最大点数，表格有直接渲染、虚拟渲染和服务端分页的分界，导出走独立任务。超过预算时，不静默抽样，而是告诉用户当前展示范围和获得完整结果的方式。

预算需要按项目基线测量，下面是一份可落地的起始配置，而不是通用真理：

阈值要和设备分布、字段宽度及交互一起压测。配置的价值是让运行时知道何时拒绝危险路径，不是证明浏览器最多能塞多少数据。

预算迫使产品和技术共同回答需求。没有边界的“支持大数据”，最终会变成浏览器承担不适合它的工作。

测量四个阶段

一份大数据从网络到屏幕，至少经过获取、计算、布局和绘制。我们分别记录：响应体大小与下载时间；JSON 解析、字段转换、排序聚合耗时；DOM 创建与布局耗时；Canvas 或 SVG 绘制耗时。

浏览器 Performance 面板可以看到长任务，但还需要业务标记把长任务对应到具体阶段。否则一次 800 毫秒阻塞只会显示为脚本执行，无法知道是排序还是图表配置转换。

内存也要测量。大数组复制、为每行创建新对象、保留旧筛选结果，都会让堆持续增长。一次操作完成后内存没有回落，往往说明引用仍被组件、缓存或监听器持有。

虚拟列表的真实复杂度

固定行高的虚拟列表相对简单：根据滚动位置计算起止索引，容器保留总高度，实际节点通过偏移放到正确位置。渲染节点数量从十万降到几十，布局成本显著下降。

function visibleRange(scrollTop: number, viewportHeight: number, rowHeight: number, total: number) {
  const overscan = 8;
  const start = Math.max(0, Math.floor(scrollTop / rowHeight) - overscan);
  const end = Math.min(total, Math.ceil((scrollTop + viewportHeight) / rowHeight) + overscan);
  return { start, end, offsetY: start * rowHeight, totalHeight: total * rowHeight };
}

overscan 避免快速滚动时露出空白，但不是越大越好。每行包含复杂单元格时，多渲染几十行就可能抵消虚拟化收益。滚动容器、焦点和行 key 也必须稳定，否则节点复用会把输入状态带到错误行。

可变行高会复杂得多。文本换行、展开详情和动态内容都会改变高度，需要测量并维护位置索引。高度估算不准会造成滚动跳动，频繁测量又会触发布局抖动。

我们尽量在大数据模式下约束行高和内容展示，复杂详情通过独立区域打开。不是所有桌面表格能力都应该与虚拟化同时存在。

虚拟化还会影响键盘导航、搜索、复制和可访问性。不存在于 DOM 的行无法被浏览器原生查找，焦点在节点回收时可能丢失。这些不是实现细节，而是功能契约的一部分。

把计算移出主线程

排序、聚合和复杂转换可以放进 Web Worker，让主线程保持交互响应。Worker 并不会让计算本身变快，它只是改变计算位置，还增加了数据传输成本。

如果把巨大对象频繁 postMessage，结构化克隆同样昂贵。我们减少传输字段，使用更紧凑的数据结构，在适合时使用 Transferable 转移二进制缓冲区。任务消息包含版本，用户改变条件后，旧任务结果会被丢弃。

// main thread
const values = new Float64Array(rows.map((row) => row.value));
worker.postMessage(
  { type: "aggregate", version, values: values.buffer },
  [values.buffer],
);
 
// worker
self.onmessage = ({ data }) => {
  const values = new Float64Array(data.values);
  const result = aggregateByBucket(values);
  self.postMessage({ version: data.version, result: result.buffer }, [result.buffer]);
};

Buffer 转移后主线程的 values 会失效，这是零拷贝的代价。只有数据所有权明确时才使用 Transferable；若主线程仍要读取同一数组，就需要重新设计边界，而不是偷偷复制回来。

Worker 逻辑保持纯粹：接收输入，执行确定转换，返回结果。不访问 UI 状态，也不承担无法恢复的副作用。这样可以单独测试，并在不支持 Worker 的环境中保留降级实现。

避免无意义的数据复制

前端代码为了“不可变”经常创建新数组和新对象。在小数据里成本可以忽略，十万行下，一次展开、映射和排序就可能制造多个完整副本。

我们区分领域状态和计算缓冲。对需要触发框架更新的边界保持不可变，对内部算法则允许受控地复用内存。排序前确认是否可以使用索引数组，而不是移动完整对象；格式化尽量发生在可见行，而不是预先处理全部数据。

缓存也不能无上限。查询结果按内存成本与访问频率淘汰，大结果的缓存时间更短。缓存命中提升速度，缓存失控则会把页面变成隐形数据仓库。

图表不等于全部数据点

屏幕宽度只有一两千像素，绘制十万个时间点无法提供十万个可区分的信息。对趋势图，服务端或 Worker 可以按像素范围聚合；对异常数据，采样必须保留峰值和转折，不能简单每隔 N 个取一点。

一个保守策略是在每个像素桶保留首值、末值、最小值和最大值。它不如专门的 LTTB 算法紧凑，但能保留突发峰谷，也容易解释。用户放大时间范围后再查询更细粒度数据，避免一次把所有原始点送进浏览器。

SVG 适合需要独立节点和交互的中小规模图形，Canvas 更适合大量绘制，但交互命中、可访问性和文本布局需要额外处理。选择渲染技术要根据图形数量与交互需求，不是根据库的流行程度。

动画在大数据更新中通常价值很低。过渡会同时保留前后状态，增加计算与绘制成本。对监控和分析工具，稳定、快速地呈现新结果比华丽过渡更重要。

更新应该与变化规模匹配

很多组件每次数据变化都会重新转换完整配置并重绘。即使只更新一个单元格，也触发全部行重新计算。优化需要让更新粒度接近实际变化。

表格可以用稳定行标识定位变化，图表可以根据系列与数据版本判断是否复用。React 或 Vue 的响应式机制只能减少框架层更新，无法替代底层图表库的增量策略。

但差量更新会增加状态复杂度。必须定义何时安全增量，何时完整重建，并用一致结果测试两条路径。追求每次都最小更新，可能得到无法证明正确的缓存系统。

把性能变成运行时能力

最终我们将这些经验沉淀为组件契约和监控：数据超过阈值时自动切换策略；长任务被记录并关联组件；页面退出时验证 Worker、监听器与图表实例被释放；关键数据量拥有固定基准测试。

十万级渲染不是某个神奇算法解决的问题。它要求从产品需求开始限制规模，在网络、计算、布局和绘制之间分配工作，再对每层建立可观察的边界。

基准测试必须使用真实分布，不只使用随机数。我们的数据集包含长字符串、高基数字段、大量空值、倾斜分组和用户真实排序操作。每个方案记录解析、传输、计算、首次可见、滚动帧率和内存峰值。验收不是“十万条能打开”，而是规定设备与浏览器上，首屏在预算内出现，交互不产生超过阈值的长任务，取消旧计算后内存能回落——真实分布通常比行数更决定性能。

浏览器可以处理很多数据，但用户需要的从来不是“数据已经进入内存”。用户需要的是在合理时间内看见答案，并且界面始终能够响应下一步操作。

两条相邻的实践在这篇里没有展开：让更新粒度匹配变化规模，属于差量更新的收益与代价；把计算真正搬离主线程的传输与取消细节，属于把十万行计算移进 Web Worker。数据管线的每一段，都在这两篇里找到了它该有的边界。

Worker 解决的是执行线程，不自动解决数据传输、任务竞争和结果过期。

图 1：每次计算都有 taskId；用户切换条件后，旧任务即使完成也不能覆盖新结果。

先把对象数组变成紧凑列数据

十万条 {region, amount, timestamp} 对象包含大量属性名和字符串重复。服务层把可枚举字段编码成字典，数值放进 TypedArray：

type ColumnBatch = {
  rowCount: number;
  regionCodes: Uint16Array;
  amounts: Float64Array;
  timestamps: Float64Array;
  regions: string[];
};

发送时转移 ArrayBuffer 所有权，不做结构化克隆：

worker.postMessage(
  { type: "aggregate", taskId, batch },
  [
    batch.regionCodes.buffer,
    batch.amounts.buffer,
    batch.timestamps.buffer,
  ],
);

转移后主线程里的这些 buffer 会被 detach，不能继续读。这个所有权变化必须写进接口，不能让调用方以为数据仍可复用。

任务协议要有版本和取消

type WorkerRequest =
  | { version: 1; type: "aggregate"; taskId: string; batch: ColumnBatch; groupBy: string[] }
  | { version: 1; type: "cancel"; taskId: string };
 
type WorkerResponse =
  | { version: 1; type: "progress"; taskId: string; completedRows: number }
  | { version: 1; type: "result"; taskId: string; result: AggregationResult }
  | { version: 1; type: "error"; taskId: string; code: string; message: string };

Worker 无法在一段不让出执行权的长循环中及时处理 cancel。聚合按批次运行，每处理几千行检查取消集合，并通过 setTimeout(0) 或分段消息给事件循环机会。

页面只接受当前任务结果

let activeTaskId: string | null = null;
 
function runAggregation(input: Input) {
  if (activeTaskId) worker.postMessage({ type: "cancel", taskId: activeTaskId });
  activeTaskId = crypto.randomUUID();
  worker.postMessage(buildRequest(activeTaskId, input), transferList(input));
}
 
worker.onmessage = ({ data }: MessageEvent<WorkerResponse>) => {
  if (data.taskId !== activeTaskId) return;
  if (data.type === "result") render(data.result);
};

取消是性能优化，taskId 检查才是正确性保证。旧 Worker 消息可能已经在队列中，不能假设 cancel 一定赶得上。

内存峰值比平均耗时更容易被忽视

我们同时记录主线程和 Worker 的输入字节、结果字节和峰值。数据解析阶段如果先创建对象数组，再转换 TypedArray，会短时间保留两份数据。更好的方式是流式解析直接填充列缓冲，或让服务端输出更适合计算的二进制/列格式。

Worker 不能替代服务端边界

把计算移出主线程后页面不再卡，并不意味着让浏览器承担无限数据合理。超过一定规模，我们仍要求服务端聚合、分页或预计算。Worker 是让中等规模交互更流畅的工具，不是把数据仓库搬到用户电脑的理由。

最终的性能收益来自一整套边界：紧凑表示降低传输成本，Transferable 避免复制，taskId 防止旧结果覆盖，分块计算支持取消，数据规模上限控制内存。只把一个函数包进 new Worker()，通常只能把卡顿从一个位置移到另一个位置。

上线后我在监控里保留四个数字：单次任务传输字节、Worker 内存峰值、取消及时率（cancel 发出后任务实际停止的时间）、以及过期结果丢弃数。前两个衡量收益，后两个衡量这个方案有没有引入新的竞态。没有这些观测，Worker 很容易从“优化”变成“更隐蔽的卡顿来源”。

这条边界和十万级数据渲染是同一件事的两面：那里讲如何把数据管线拆开测量，这里讲如何把其中的计算与传输真正搬离主线程。

原文发布于掘金。这次重新整理时，我保留了当时验证过的方案，也补上版本边界：CocoaPods、镜像站和网络环境都会变化，理解链路比记住某个镜像地址更可靠。

图 1：RubyGems 源、Specs 源和 podspec 中的源码地址彼此独立，换错一段不会改善另一段。

先判断到底慢在哪里

CocoaPods 是 Ruby 生态中的依赖管理工具。一次从零开始的安装，至少经过三段网络访问：

例如 pod install 已经完成版本解析，却卡在某个 GitHub 地址，此时更换 Specs 镜像没有用。Specs 只告诉 CocoaPods 去哪里下载依赖，最终产物仍可能来自另一个域名。

先用详细输出观察停点：

gem install -V cocoapods
pod install --verbose

-V 和 --verbose 不会让网络变快，但能避免在没有进度时盲等，也能把失败定位到具体阶段。

安装 CocoaPods：处理 RubyGems 源

在当时的国内网络环境里，直接访问 RubyGems 官方源很不稳定。我使用清华 RubyGems 镜像安装工具：

# 增加镜像并移除当时不可达的官方源
gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/ \
  --remove https://rubygems.org/
 
# 确认当前生效的源
gem sources -l
 
# 显示详细安装过程
sudo gem install -V cocoapods

gem 是 Ruby 的包管理器，作用类似 Node.js 的 npm 或 Python 的 pip。这里切换的只是 CocoaPods 工具及其 Ruby 依赖的下载源，不会改变后续 pod install 使用的 Specs 或源码地址。

使用系统 Ruby 时，sudo gem install 可能引入权限与版本冲突。团队环境更适合用 rbenv、asdf 或 Bundler 固定 Ruby 和 CocoaPods 版本：

# Gemfile
source "https://rubygems.org"
 
gem "cocoapods", "1.12.1"

bundle install
bundle exec pod install

上面的 1.12.1 是与 2023 年原文相近的示例，不是“永远应该安装”的版本。真正应该固定的是项目已经验证过的版本，并把 Gemfile.lock 提交到仓库。

解析依赖：理解 CDN 与 Git Specs 仓库

早期 CocoaPods 会同步完整的 Specs Git 仓库。这个仓库历史很长，当时约 1.3 GB；pod repo add 没有直观克隆进度，看起来像卡死。

原文使用的是清华 Git 镜像：

cd ~/.cocoapods/repos
pod repo remove master
git clone https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git master

手动 git clone 的主要价值不是更换了一套神秘机制，而是能看到对象接收和检出的进度。然后在项目 Podfile 顶部声明对应源：

source "https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git"

但这套方案有明确成本：第一次需要同步完整仓库，后续还要维护更新。CocoaPods 1.8 之后，官方默认转向按需请求的 CDN 模型，新项目通常不必克隆完整 Specs 历史：

source "https://cdn.cocoapods.org/"

所以不要不分版本地执行 rm -rf master。先运行这些命令了解当前状态：

pod --version
pod repo list
pod install --verbose

如果项目使用 CDN 且元数据访问正常，增加完整 Git Specs 仓库反而会让首次安装更慢。只有当前网络无法稳定访问 CDN、团队已经统一维护镜像，或者私有依赖明确要求 Git Specs 时，才值得切换模型。

下载依赖：Specs 可用不代表源码可用

完成版本求解后，CocoaPods 会读取每个 podspec 的 source，它可能指向 GitHub、另一个 Git 服务或压缩包 CDN。这个阶段的典型日志是已经选定版本，然后卡在 Downloading dependencies 或某个 git clone。

排查时我会直接看目标 pod 的规格：

pod spec which SomePod
pod install --verbose

确认以下信息：

• 卡住的是 Specs 元数据，还是具体源码地址；
• Podfile.lock 是否已经固定到某个不可达版本；
• 团队其他机器成功是因为网络可达，还是命中了本地缓存；
• 私有仓库凭证失败是否被误判成“下载慢”；
• 代理或镜像是否改变了下载内容的完整性。

镜像只解决可达性，不应该改变依赖解析结果。切换后必须检查 Podfile.lock 的版本和校验变化，不能看到命令成功就直接提交。

Podfile 中多个 source 的边界

使用私有 Specs 仓库时，通常会声明多个源：

source "https://git.example.com/ios/specs.git"
source "https://cdn.cocoapods.org/"
 
platform :ios, "13.0"
 
target "Runner" do
  pod "InternalAnalytics", "~> 2.4"
  pod "Alamofire", "~> 5.8"
end

源的顺序和同名 Pod 会影响解析。私有仓库不应该复制公共 Pod 的同名规格；否则同一个 Podfile.lock 在不同缓存状态下可能得到意外来源。对于关键私有依赖，团队需要明确仓库所有权、凭证分发和可用性，而不是让每个人单独修改本机配置。

团队环境比个人换源更重要

个人电脑上临时换源能解决一次安装，不能保证 CI 和同事环境稳定。更可靠的工程做法包括：

• 用 Bundler 固定 CocoaPods 版本；
• 提交 Podfile.lock，CI 使用 pod install 而不是随意 pod update；
• 在 CI 中记录 Ruby、CocoaPods、Xcode 和源配置；
• 对私有 Specs 与二进制产物建立团队级缓存和可用性监控；
• 镜像故障时有明确回退源，而不是现场搜索一条新命令；
• 定期验证镜像同步延迟与依赖校验，避免可用但过期。

可以把处理策略归纳成一个简单决策表：

这次问题真正教会我的事

当时最有用的不是记住清华镜像的 URL，而是终于把 CocoaPods 的网络请求拆成了三段。只有知道命令正在安装 Ruby 工具、解析 Specs，还是下载真正的依赖，才知道该改哪个配置。

环境问题最容易被写成一串“复制即可”的命令，但镜像地址、默认源和工具行为都会变化。把版本、适用时间和回退方式一起写进项目文档，才是这类经验能够长期复用的前提。

真正解决后，我会保存一份完整诊断记录：工具版本、Ruby 来源、gem sources -l、pod repo list、失败域名、最终使用的镜像和 lockfile 是否变化。下次同事遇到“pod install 很慢”，先对照这份记录判断卡在哪一段，而不是重新复制一组未知命令。

镜像配置每季度验证一次可达性与同步延迟；失效时回退到团队统一方案。这里有一个容易忽略的判断：镜像和代理可以解决可达性，但永远不能改变依赖解析结果。切换源后必须检查 Podfile.lock 的版本与校验是否变化——如果变了，说明两个源的元数据不一致，这次“换源”其实是换了一组依赖，不能直接提交。环境文档如果没有验证日期和负责人，很快就会从帮助变成新的故障源。

表格需要维度、指标、排序和汇总；折线图需要时间粒度、系列与缺失值策略；漏斗有自己的阶段语义；不同数据源又拥有不同查询能力。如果每个组件维护一套私有配置，编辑器、运行时和保存结构会被紧密绑定。

低代码 BI 的核心不是拖拽，而是设计一门足够稳定、又不过度承诺的描述语言。

图 1：编辑器保存的是领域 Spec，不是某个图表库的 option；运行时像编译器一样逐层验证和转换。

从业务问题建立中间模型

我们把一张报表拆成四类信息：数据查询描述“从哪里得到什么”；数据转换描述聚合、计算与格式；视觉编码描述字段如何映射到位置、长度、颜色；交互描述筛选、联动与下钻。

这四层不会完全独立，但明确区分后，很多能力可以跨组件复用。日期筛选不必在每种图表中重复实现，数据格式化也不需要嵌入视觉配置。

中间模型不能直接复制某个图表库的 option。图表库会升级或替换，产品概念却应该稳定。运行时通过适配器把领域配置转换为 G2Plot、ECharts 或表格组件需要的属性。

适配器也暴露能力矩阵。例如某类图支持双轴，另一类不支持；某数据源支持服务端聚合，另一数据源只能返回明细。编辑器根据矩阵限制可选项，避免生成运行时无法兑现的配置。

一个折线图的领域配置可以只有这些内容：

type ChartSpecV3 = {
  version: 3;
  source: { datasetId: string };
  query: {
    dimensions: Array<{ field: string; granularity?: "day" | "week" | "month" }>;
    measures: Array<{ field: string; aggregate: "sum" | "avg" | "count" }>;
    filters: FilterExpression[];
  };
  encoding: {
    x: { field: string; type: "temporal" | "category" };
    y: { field: string; format?: string };
    color?: { field: string };
  };
  interaction: { tooltip: boolean; zoom: boolean };
};

这里没有 grid.left、series.smooth 之类 ECharts 私有字段。表现细节由主题和适配器给默认值；确实形成产品能力的选项才进入 Schema。这个克制让保存数据不跟随图表库升级频繁迁移。

Schema 需要版本

配置一旦保存，就成为长期数据。新增字段容易，重命名、改变默认值或删除能力都会影响历史报表。

我们为 Schema 保留显式版本，并建立单向迁移。运行时加载旧配置时先转换到当前版本，迁移过程保持可测试。不能把兼容逻辑散落在每个组件里，否则几年后没有人知道某个判断在兼容哪个年代。

const migrations = {
  1: (spec: ChartSpecV1): ChartSpecV2 => ({
    ...spec,
    version: 2,
    interaction: { tooltip: spec.tooltip ?? true },
  }),
  2: (spec: ChartSpecV2): ChartSpecV3 => ({
    ...spec,
    version: 3,
    source: { datasetId: spec.dataset },
  }),
};
 
function migrate(input: AnyChartSpec): ChartSpecV3 {
  let current = input;
  while (current.version < 3) current = migrations[current.version](current as never);
  return current as ChartSpecV3;
}

迁移测试使用真实历史配置样本，并比较迁移前后的查询语义和最终编码，不只断言版本号变成 3。默认值变化尤其要有快照，否则旧报表会在没人编辑的情况下改变外观或计算。

默认值也必须写入语义。若一个字段未保存，当前版本与未来版本是否得到同样行为？为了压缩配置而省略默认值，可能让历史报表随着系统升级悄悄变化。

配置发布后还要可回滚。编辑态和运行态不能共享一份随时变化的数据，至少需要草稿、已发布版本与版本记录。用户在编辑器里的误操作不应立刻影响正在使用的看板。

编辑器不是配置表单集合

当配置项很多时，把它们全部展示出来只会把代码复杂度转移给业务用户。编辑器要围绕分析任务组织：先选数据，再确定想比较或观察什么，系统推荐合适图表，最后开放必要的表现调整。

字段选择需要理解类型和角色。数值可以作为指标，类别可以作为维度，时间拥有粒度和时区。拖拽行为不仅改变位置，还应该立即验证组合是否有效，并给出可以行动的反馈。

实时预览很重要，但不能每次输入都请求完整数据。编辑器可以使用采样数据、缓存查询结果，并对昂贵操作做节流。预览还要明确与生产数据的差异，避免用户把样本当作最终结果。

撤销与重做不适合通过保存整个页面快照无限堆积。更可控的方式是把编辑操作表达为命令，记录可逆变化。这样既能支持历史，也更容易分析用户如何构建报表。

运行时必须与编辑器解耦

编辑器关注创建体验，运行时关注加载速度、稳定性和兼容。两者共享 Schema 与渲染内核，但不应共享全部依赖。最终看板不需要拖拽库、属性面板和编辑历史。

运行时读取已发布配置，验证版本和完整性，按依赖加载数据，再渲染组件。单个图表失败不能拖垮整个看板，错误区域应保留位置并提供原因；公共筛选失败则需要明确影响范围。

运行链路被明确拆成编译与执行：

已发布 Spec
  → 版本迁移
  → Schema 与能力校验
  → 编译查询计划
  → 权限检查与数据请求
  → 数据转换
  → 编译视觉配置
  → 渲染器适配器

每一步返回结构化错误。field_not_found 属于配置问题，dataset_forbidden 属于权限问题，query_timeout 属于运行问题。编辑器可以定位到具体字段，运行时则给看板使用者可行动反馈，二者不需要解析一段统一异常字符串。

每个组件都应该有生命周期：初始化、等待数据、渲染、更新、销毁。图表库常持有 Canvas、事件监听和大块数据，组件切换或页面退出时若不释放，会在长时间使用的后台中形成明显内存问题。

动态渲染也要限制能力。允许配置任意 JavaScript 表达式看似灵活，却带来安全、调试和版本兼容风险。我们更倾向提供受限公式与内置转换函数，让表达能力可以被静态分析和控制。

数据规模决定架构

低代码让创建图表更容易，也会让一个页面出现更多查询和更大数据。运行时必须把数据规模当作一等约束。

聚合尽量下推到服务端，浏览器只接收展示需要的数据。表格使用分页或虚拟化，图表对点数设置上限并提供采样策略。超过范围时，系统应解释为什么不能直接渲染，而不是让页面卡死。

多图表联动会产生请求风暴。筛选变化先形成统一查询上下文，再由页面级调度器合并、排序和取消任务。相同查询共享结果，旧上下文的响应不能覆盖新状态。这套调度不是顺手实现的细节，值得单独展开——我在多图表页面为什么需要请求调度里记录了并发限制、优先级老化与取消语义。

缓存键必须包含数据源、查询条件、权限与版本。BI 数据往往具有权限边界，错误缓存比没有缓存更危险。

可扩展不等于无限配置

低代码产品很容易陷入需求循环：每个客户都有例外，于是新增一个开关；开关组合产生新问题，再新增更多开关。最终没有人能解释全部组合。

我们会判断需求属于通用分析能力、行业模板还是单一场景。通用能力进入 Schema，稳定组合沉淀为模板，单一场景则考虑自定义组件或明确不支持。边界本身就是产品能力。

插件机制也需要契约。一个新图表组件必须声明支持的数据角色、配置 Schema、运行时依赖、序列化方式与版本兼容。只注册一个 React 或 Vue 组件远远不够。

测试的是语义，不只是组件

低代码系统的组合数量巨大，不可能穷举所有配置。测试重点应放在模型不变量和关键组合。

Schema 验证确保非法配置无法进入运行时；迁移测试保证历史样本升级后语义不变；适配器测试验证领域配置生成正确图表选项；关键模板做视觉回归；真实大数据样本用于性能基线。

每次线上错误都应沉淀为最小配置样本。配置数据比手工操作更适合复现，也能成为长期回归集。

最终交付的是受控表达力

低代码 BI 的价值，是让业务用户更接近问题与数据，而不是让所有人变成前端开发者。平台需要提供足够表达力，也要阻止无效、危险或无法维护的组合。

拖拽界面只是可见部分。真正决定系统寿命的，是中间模型、版本迁移、运行时隔离、数据边界和扩展契约。

一个成熟的配置系统不会承诺“什么都能做”。它会清楚说明什么能稳定完成，什么需要定制，以及新增能力将如何进入已有秩序。

这种克制最后落到一个很具体的要求：每份配置都能导出一张诊断单。诊断单包含 Schema 版本、迁移路径、数据集版本、查询计划、预计点数、渲染器能力命中和被降级选项。用户反馈“图不对”时，支持人员不必先索要整份敏感数据：

specVersion: 7 -> 9
queryPlan: server aggregation / 5m
estimatedPoints: 8,640
renderer: echarts-adapter@4
warnings: connectNulls disabled because missingRate=18%

可解释的中间产物，是低代码平台长期可维护的部分。Schema 迁移的完整管线（单向迁移、语义校验、黄金样例、写回隔离）我在低代码配置升级里单独记录过，这里只保留了与引擎设计相关的边界。

我们最终把兼容从组件渲染里移出，所有配置先经过单向迁移到当前 Schema，再校验和编译。运行时只理解一个版本。

图 1：迁移是数据管线，不是散落在 UI 中的一组 ?? defaultValue。

每一步只知道相邻版本

type Migrator<From, To> = (input: From) => To;
 
const migrations: Record<number, Migrator<any, any>> = {
  1: (v1: ChartV1): ChartV2 => ({
    ...v1,
    version: 2,
    interaction: { tooltip: v1.tooltip !== false },
  }),
  2: (v2: ChartV2): ChartV3 => ({
    ...omit(v2, "dataset"),
    version: 3,
    source: { datasetId: v2.dataset },
  }),
};
 
function migrateToCurrent(input: UnknownSpec): ChartV3 {
  let current = structuredClone(input);
  while (current.version < 3) {
    const migrate = migrations[current.version];
    if (!migrate) throw new MigrationError("MIGRATION_PATH_MISSING", current.version);
    current = migrate(current);
  }
  return validateV3(current);
}

V1 直接迁到 V3 看似少一步，版本多后会产生大量组合。相邻迁移让每次发布只维护一个新边，历史配置按同一路径回放。

结构正确不等于语义正确

JSON Schema 能验证字段类型，不能判断“饼图只能有一个 measure”或“时间粒度只适用于时间字段”。迁移后还有领域校验：

function validateSemantics(spec: ChartV3, dataset: DatasetSchema): Issue[] {
  const issues: Issue[] = [];
  if (spec.kind === "pie" && spec.query.measures.length !== 1) {
    issues.push({ path: "query.measures", code: "PIE_REQUIRES_ONE_MEASURE" });
  }
  if (!dataset.fields.has(spec.encoding.x.field)) {
    issues.push({ path: "encoding.x.field", code: "FIELD_NOT_FOUND" });
  }
  return issues;
}

错误带路径、代码和上下文，编辑器可以定位字段；不能只抛一句 invalid config。

迁移必须保持用户意图

改变默认值最容易悄悄改图。例如 V1 缺少 connectNulls 时，旧运行时默认 true，新运行时默认 false。迁移不能简单留空，而要显式写入旧语义。

用黄金样例验证视觉结果

单元测试验证 JSON 输出还不够。我们保存一组代表性历史配置和固定数据，迁移前用旧运行时截图，迁移后用新运行时截图，对关键视觉和查询计划做差异检查。

黄金样例包括空数据、长标签、双轴、联动筛选和被删除字段。每次新增迁移都跑完整链路：V1 → 当前、V2 → 当前、当前重复迁移。重复执行当前配置应该不再改变内容。

读时迁移与写回分开

页面打开时先在内存迁移，确保可读；是否持久化新版本由后台任务控制。直接在用户打开页面时覆盖旧配置，一旦新运行时有 bug 就失去原始证据。

批量写回按租户和报表分批，记录原版本、目标版本、输入 hash、输出 hash、迁移器版本与结果。失败配置隔离，不阻塞全部批次，也不反复自动重试未知错误。

迁移管线上线后，我盯三个数字：迁移失败率、写回前后 hash 不一致率、以及用户打开历史报表时的报错数。前两个归数据团队管，第三个直接反映用户感知。一次默认值改动曾经让黄金样例里的两张旧图悄悄改变样式——如果只统计“迁移成功”而不断言视觉结果，这类静默变化会被平均分掩盖。所以验收只看两个终态：迁移结果与迁移前语义等价，且每一步都有可回放的证据。

这次治理之后，组件代码里大量“历史原因”判断被删除。更重要的是，我们终于能回答一份配置从哪个版本来、怎样变成今天的结构、哪一步可能改变语义。低代码配置一旦被用户保存，就和数据库数据一样需要严肃的演进纪律。这与低代码 BI 引擎里 Schema 版本化的设计一脉相承；当债务积累到需要偿还时，我在架构债务不是旧代码里记录了双算与逐步切换的完整做法。

从组件视角看，每个请求都合理；从页面视角看，它们在争夺同一组资源。

页面拥有调度权

我们在数据层建立请求队列，限制同一数据源的并发数，并根据可见性和业务优先级排序。首屏核心指标先执行，视口之外的图表延后，用户切换筛选条件后，旧队列中尚未开始的任务直接取消。

正在执行的请求也要识别版本。旧条件的结果晚于新条件返回时，不能覆盖当前页面。通过查询签名与取消信号，可以避免这类竞态。

调度器不需要一开始就做成复杂框架。我用过的最小模型只有四个字段：

type QueryTask<T> = {
  key: string;
  priority: number;
  createdAt: number;
  signal: AbortSignal;
  run: () => Promise<T>;
};
 
const MAX_CONCURRENCY = 4;
const running = new Map<string, Promise<unknown>>();
const waiting: QueryTask<unknown>[] = [];

key 由数据源、时间范围、维度和筛选条件规范化生成。完全相同的任务复用 running 中的 Promise；还没开始且已经过期的任务直接从 waiting 删除。正在执行的任务通过 AbortController 尽力取消，即使底层请求无法中止，结果提交前仍要比较当前查询版本。

function effectivePriority(task: QueryTask<unknown>, now = Date.now()) {
  const waitingSeconds = (now - task.createdAt) / 1000;
  return task.priority + Math.min(20, waitingSeconds * 0.5);
}

等待时间会逐步提高有效优先级，避免低优先级图表永久饥饿。用户刚操作的首屏查询仍然先执行，但一个已等待 40 秒的后台任务最终能获得位置。

合并不等于批量

参数完全相同的请求可以共享结果，时间范围和维度相近的请求有时可以在服务端批量处理。但盲目合并会生成超大响应，让一个失败影响所有图表。

调度策略必须可观测：排队时间、执行时间、取消原因和缓存命中都应被记录。否则优化只是在移动等待。除了指标，我还要求每次取消都带上原因字段（新任务替代、用户离开页面、过期），页面慢时能区分是服务端慢，还是请求在浏览器调度层等了很久——调度器不能从优化层变成新的黑盒。

如果只看接口耗时，会错过任务在浏览器队列里等了两秒的事实。用户感知时间是排队、网络、转换和渲染的总和。

拿一张 28 图的看板做回归，在去重与并发限制生效后，首屏发出的请求数能降到原来的三分之一以下，P95 完成时间通常能从十几秒收敛到几秒内——其中约一半来自不再重复发起相同查询，另一半来自主图不再等辅助图表排队。这个结果印证了一件事：先把"请求在等待"这个看不见的事实变成可量化指标，再谈算法。

优先级不能永远饿死后台任务

如果核心图表持续产生新请求，低优先级任务可能一直无法执行。调度器需要老化策略：等待越久，优先级逐步提高；同一组件也要限制占用，避免单个异常图表填满队列。

用户主动操作通常高于自动刷新，但自动刷新不能悄悄覆盖用户正在查看的结果。页面可见性、交互意图和数据时效共同决定优先级，简单的先进先出或固定等级都不足以表达真实需求。

组件自治适合局部开发，页面级性能需要全局协调。架构的作用之一，就是让局部正确不会累积成整体失控。

图：调度层统一分配网络注意力，组件不再各自争抢。

调度器让页面级资源分配成为可能，但要真正省下时间和内存，还需要数据本身更紧凑、计算更早离开主线程。同一个看板场景里的后续优化，我在十万级数据渲染和把计算移进 Web Worker里分别展开：前者拆开数据管线的每个阶段，后者处理任务取消与结果过期。请求调度是这三条线里的第一层。

这类问题最难的地方不是知道“内存泄漏”这个名词，而是从无数接口、定时任务和中间件里，找到究竟是哪类对象被谁持有。本文记录的是我当时真实的排查路径。原文最早发布于知乎，这里重新整理了证据链、代码边界和生产操作风险。

图 1：监控负责发现“什么时候开始异常”，堆快照负责回答“哪些对象为什么还活着”。

先证明它是泄漏，而不是内存高

Node.js 进程占用 500 MB 内存并不自动等于泄漏。V8 会为了减少频繁申请内存而保留已经扩张的堆，RSS 也包含堆外缓冲区、原生模块和线程栈。真正需要警惕的是：在相同负载下，执行完整 GC 后的存活对象基线仍然一轮轮上升。

process.memoryUsage() 暴露了几个容易混淆的指标：

function sampleMemory() {
  const bytes = process.memoryUsage();
  return Object.fromEntries(
    Object.entries(bytes).map(([name, value]) => [name, Math.round(value / 1024 / 1024)]),
  );
}
 
setInterval(() => {
  console.info("memory_mb", sampleMemory());
}, 30_000).unref();

原来的监控图里，heapUsed 与进程内存都在上涨，活动句柄数也从一百多个持续涨到四百多个。句柄这条线后来成为关键旁证。

图 2：内存上涨并非孤立信号；活动句柄同步增长，把范围指向了网络连接或事件资源。

先分全局泄漏与局部泄漏

我会先问一个简单问题：随便压一个最小接口，内存是否也会稳定上涨？

如果任何请求都能触发，泄漏大概率位于全局中间件、日志、请求上下文或公共组件。此时二分法很有效：关闭一半公共逻辑，用同一流量模型重测；根据结果继续对剩余范围二分。2020 年排查 Nuxt SSR 服务时，我就用这种办法在半小时左右把问题定位到 HTTP 客户端相关代码。

如果只有特定接口、异步任务或业务操作才触发，它就是局部泄漏。局部泄漏不能靠随意注释公共代码解决，需要把故障时间、发布记录、请求路径和任务类型对齐。

这次问题无法被最小接口复现，只在某批后台任务运行后出现，因此我按局部泄漏处理。

用时间线缩小功能范围

最理想的状态，是能确定泄漏从哪个发布版本开始。假设一个迭代只上线了 A、B、C 三个功能，就应该先在这三个变更里复现，不要一上来扫描整个仓库。

这次发现得比较晚，只能把初次出现时间缩到大约一个月，期间又跨过一个大版本。仅靠 Git 提交无法快速定位，所以我把以下信号放到同一条时间线上：

• QPS、状态码和请求路径；
• 平均响应时间与事件循环延迟；
• 进程重启次数、CPU 和 Node.js 版本；
• rss、heapUsed、external 与可用堆；
• 活动请求数和活动句柄数；
• 同期发布的异步任务与依赖变更。

这里只有堆快照是不够的。快照告诉你某一刻有什么对象，却不告诉你那个对象对应哪次业务动作。监控时间线把晦涩的对象变化重新接回了真实操作。

采集至少三份可比较的堆快照

一份 Heap Snapshot 只能描述一个时刻。为了判断哪些对象“只增不减”，至少需要基线、触发后和 GC 后三份快照。当时为了看清趋势，我实际采了五份。

一个可重复的采集序列是：

1. 服务启动并预热后，手动 GC，采基线快照；
2. 按固定次数执行可疑任务；
3. 内存上涨一个明确区间后，再次 GC 并采快照；
4. 重复任务与采集，形成对象数量的时间序列；
5. 修复后用完全相同的负载和采集点回归。

如果使用 heapdump 包，可以通过受控的运维信号触发，而不是暴露一个普通 HTTP 接口：

import heapdump from "heapdump";
 
process.on("SIGUSR2", () => {
  const file = `/tmp/service-${process.pid}-${Date.now()}.heapsnapshot`;
  heapdump.writeSnapshot(file, (error, filename) => {
    if (error) console.error("heap_snapshot_failed", error);
    else console.info("heap_snapshot_written", { filename });
  });
});

生产环境采快照有两个不能省略的前提：权限隔离，以及流量切走。采集时主线程会停顿，快照越大，停顿越长；当时我们让主、备两个 Pod 配合，先把业务流量迁移到备用实例，再在目标 Pod 上采集。快照文件本身也可能包含业务数据，下载、存储和删除都应走受控流程。

不要等到容器已经贴近 OOM 临界点才开始采集。写快照本身需要额外内存和时间，太晚可能一份也拿不到。

图 3：快照必须按同一操作序列采集，否则 Comparison 中的增量没有可比性。

从“什么在增长”走到“谁在持有”

在 Chrome DevTools 的 Memory 面板中，我通常按三个视图逐层收窄：

Summary：先看保留量和对象数量

Summary 用构造函数聚合对象。我先按 Retained Size 排序，再观察对象数量是否随每份快照稳定增长。除了业务类名，还会特别关注 TCP、Socket、EventEmitter、Timeout、Buffer 和全局对象。

图 4：业务对象不是唯一线索，底层资源对象常常更接近泄漏类型。

Comparison：只看两次操作之间的净增量

Comparison 比较两份快照的 # New、# Deleted 和大小变化。一次任务创建一批对象很正常；任务结束并 GC 后，对象仍在每轮净增长才异常。

Retainers 与 Containment：沿引用链找到所有者

找到异常对象后，不要停在类名上。继续看 Retainers，回答“是谁让它不能被 GC”。Containment 则适合观察从 GC Root 到目标对象的层级关系。

图 7：真正有用的不是看到一个 Socket，而是确认它通过哪条引用链仍然可达。

根因：把进程级队列当成任务级对象

把五份快照放在一起后，TCP、Socket 和 EventEmitter 的数量会随任务执行持续增加；Grafana 里的活动句柄也同步上升。再回看故障时间窗内的功能，范围收敛到了 Bull 消息队列。

问题不是 Bull 自身“必然泄漏”，而是生命周期使用错了：业务流程中频繁创建队列实例，却没有关闭底层 Redis 连接和事件监听。队列通常应该是进程级长生命周期对象。如果确实创建临时实例，就必须明确释放。

容易出问题的形态类似这样：

async function enqueueReport(input: ReportInput) {
  const queue = new Queue("report", { redis: redisOptions });
  await queue.add(input);
  // 函数结束了，但 queue 持有的连接与监听器还活着。
}

修复后的边界是：实例只创建一次，进程退出时统一关闭。

const reportQueue = new Queue("report", { redis: redisOptions });
 
export function enqueueReport(input: ReportInput) {
  return reportQueue.add(input);
}
 
async function shutdown(signal: string) {
  console.info("queue_shutdown", { signal });
  await reportQueue.close();
  process.exit(0);
}
 
process.once("SIGTERM", () => void shutdown("SIGTERM"));
process.once("SIGINT", () => void shutdown("SIGINT"));

具体关闭 API 会随 Bull/BullMQ 版本变化，但原则不变：连接、定时器、子进程、文件描述符和事件监听器都有所有者，也必须有明确的结束时机。这与我在Node.js 优雅退出里处理的问题同源——资源按依赖方向逆序关闭，进程才能安全离开。

回归验证要复用同一负载模型

“代码改了，内存暂时没涨”不能算结案。我们重新执行了与故障复现相同的任务次数、并发和观察周期，验证四件事：

• GC 后 heapUsed 回到稳定区间；
• 活动句柄数不再随任务次数线性增长；
• Comparison 中相关对象的净增量接近零；
• 服务吞吐、错误率和事件循环延迟没有因修复恶化。

如果测试前后的请求结构不同，曲线就没有可比性。内存问题的验收标准应该在修复前写下来，而不是看完新曲线后再解释。

我后来保留的排查清单

常见泄漏来源可以记住，但不要拿清单代替证据：

• 无边界全局缓存；
• 未清理的 EventEmitter 监听器；
• 持有大对象的闭包；
• 没有关闭的 Socket、文件、队列和子进程；
• 不再需要但仍被定时器引用的上下文；
• 原生模块或 Buffer 导致的堆外增长。

我现在处理这类问题的顺序很固定：先从监控确认趋势，再判断全局还是局部；用时间线缩小变更范围；按同一业务动作采至少三份快照；从对象增量沿 Retainers 找到所有者；最后用同一套压测做回归。

堆快照不是一个会直接指出代码行的答案机器。它更像现场取证：单独一张图很难说明问题，但时间、指标、对象数量、引用链和代码生命周期彼此印证后，根因就不再只是猜测。

这次排查的经验后来被固化成一份 Runbook。它固定了判定条件、采样顺序和生产风险：先看 GC 后基线与活动句柄；锁定发布时间窗；快照至少三份；采集前切流量并确认磁盘；快照按敏感数据管理；修复后复用同一负载。判断标准要先于采样写下来，否则拿到新曲线后再解释，任何结论都成立。

Runbook 没有停在文档层。每季度我们会在测试环境制造一次可控句柄泄漏，让值班同学从告警一路走到 Retainers。只有另一位工程师也能按文档独立完成定位，这次昂贵的排查经验才算真正留在团队里，而不是锁在当次参与者的记忆中。

这种成本不会消失，只是从产品开发转移到每个使用者和支持人员身上。

理解真实任务

研发平台的用户不是为了“使用平台”，而是为了创建工程、完成发布或定位失败。页面结构应围绕任务，而不是围绕后端模块。用户进入页面后要快速知道当前状态、下一步动作和阻塞原因。

以发布任务为例，页面最需要的不是把流水线所有字段铺开，而是稳定回答五件事：

1. 正在发布哪个提交到哪个环境。
2. 当前运行到哪一步，已经完成什么。
3. 是否正在等待某个人或某个外部系统。
4. 失败会不会影响已经在线的版本。
5. 用户现在能重试、回滚还是修改配置。

这些信息对应一个任务视图模型，而不是若干后端表的直接拼接：

type ReleaseTaskView = {
  target: { project: string; commit: string; environment: string };
  status: "running" | "waiting" | "failed" | "succeeded";
  currentStep: string;
  completedSteps: string[];
  blocker?: { owner: string; reason: string };
  availableActions: Array<"retry" | "rollback" | "edit-config">;
};

危险操作需要明确范围和后果，但不能用多次无意义确认替代权限与可恢复设计。普通操作则应减少表单输入，尽量从已有上下文推导默认值。

错误信息是关键界面

外部系统失败时，平台不能只展示状态码。它要说明哪一步失败、是否影响已有结果、可以重试还是需要修改配置。错误越具体，恢复越不依赖平台开发者。

同一个 403 在不同阶段可能意味着完全不同的动作。读取仓库时的 403 需要检查代码平台授权；部署生产环境时的 403 可能需要申请环境权限。平台在调用外部服务时就要记录领域阶段，不能把解释责任留给 UI 猜测。

一条可行动错误至少包含：发生位置、用户影响、是否可重试、推荐动作和追踪编号。堆栈可以放在开发视图，不应该成为用户唯一能看到的答案。

内部产品也需要观察使用：哪些入口没人找到，哪些步骤反复失败，哪些流程仍然在线下完成。用户反馈不只是需求列表，而是判断默认路径是否成立的证据。

培训不能代替设计

培训适合解释组织规则和少见风险，不适合弥补每次操作都要记忆的界面细节。如果同一个问题在群里重复出现，应先检查信息是否应该直接显示在任务附近，或者默认值是否可以从上下文推导。

帮助内容也要连接到当前状态。相比一份覆盖全平台的手册，错误旁的一段恢复说明、字段旁的来源解释更容易被使用。用户需要的不是知道系统拥有多少能力，而是在当前一步获得下一步答案。

好的内部平台不会让工程师感到自己在操作另一个复杂系统。它应该把组织经验变成清晰路径，把复杂度留在必要的位置。

图：跳出平台找人手工处理，也应该进入产品失败数据。

观察用户在哪里离开平台

我们给核心任务画漏斗：找到入口、通过权限、配置任务、首次执行、失败恢复、最终完成。用户跳去群里找人或登录服务器手工处理，也算平台任务失败，而不是“线下解决”。

每月选三条真实失败会话复盘，优先修阻断最多人的一步。内部用户不会因为没有竞品就接受糟糕体验，他们只会绕过平台；这些绕路正是最真实的产品反馈。

2022 年我们把发布模型改成 build once, deploy many：CI 在受控环境构建一次，后续环境只验证和部署同一 artifactId。

图 1：环境晋级的是已经验证过的产物，不是一次重新执行构建的机会。

产物必须能回答自己从哪里来

除了压缩包，我们生成 manifest：

{
  "artifactId": "console-20220917-7f31a2c",
  "repository": "git@example/console",
  "gitSha": "7f31a2c",
  "lockfileSha256": "...",
  "builderImage": "node-builder@sha256:...",
  "artifactSha256": "...",
  "sbom": "console-20220917-7f31a2c.spdx.json"
}

Git tag 只能说明源代码位置，不能说明构建器、依赖锁和最终字节。manifest 把这些事实绑定在一起，并由 CI 身份签名。

部署阶段不再拥有编译权限

部署器只做四件事：按 ID 下载；验证签名与 hash；注入环境配置；切换运行版本。它没有修改产物或访问包管理器的权限。配置通过环境变量或独立配置文件提供，不把生产密钥烤进构建包。

verify-signature artifact.tar.gz artifact.sig
echo "$EXPECTED_SHA256  artifact.tar.gz" | sha256sum --check
deploy --artifact "$ARTIFACT_ID" --environment production

缓存加速不能改变结果

CI 缓存用于依赖下载和中间层，但 key 至少包含 lockfile hash、运行时版本和构建配置。缓存 miss 只影响耗时，不能影响依赖集合。流水线定期做无缓存构建，与缓存构建的产物 hash 对比，发现构建中隐藏的时间戳或非确定性输入。

晋级和回滚都只移动指针

预发通过后，发布记录把同一 artifactId 标记为 production candidate。生产部署不触发新构建。回滚从最近稳定列表选择旧 ID，验证其数据库兼容范围后切换。

制品不能无限保留，但正在运行、处于回滚窗口或被审计冻结的产物不能删除。清理任务依据引用关系，而不是简单“保留最近十个文件”。

SBOM 让漏洞响应有范围

依赖漏洞出现时，我们需要知道哪些运行产物实际包含受影响版本，而不只是哪些仓库 package.json 写过它。每份制品生成 SBOM 并索引，安全团队可以从组件版本反查 artifactId、环境和负责人。

改造后一次发布失败变得更容易解释：如果 hash 不同，是产物传输问题；如果相同但行为不同，看环境配置和外部依赖；不会再把“重新构建一次试试”当成诊断手段。

不可变产物看起来是流水线细节，实际上建立了软件供应链的事实链。只有测试过的字节就是上线的字节，回滚才真正指向一个已知结果。

权限不是一个独立技术模块，而是业务规则的一部分。

图 1：角色只是授权来源之一。最终决策还要计算资源范围、临时授权、职责分离和策略版本。

从动作和资源开始

比起先列角色，我更愿意先列受保护的动作：谁可以在什么范围内对什么资源做什么。例如“发布生产环境”包含操作者、工程、环境和动作，缺一不可。

角色只是权限集合的管理方式，不应成为代码里到处出现的判断。业务服务询问授权系统“是否允许这个动作”，而不是判断用户是否叫某个角色。

我会把一次授权请求写成四元组：主体、动作、资源、上下文。

type AuthorizationRequest = {
  subject: { userId: string; organizationId: string };
  action: "release.read" | "release.create" | "release.approve";
  resource: { projectId: string; environment: "test" | "production" };
  context: { now: string; requestId: string };
};
 
type AuthorizationDecision = {
  allowed: boolean;
  policyVersion: string;
  reason: string;
  missingPermissions?: string[];
};

“生产发布审批人不能是发起人”就不适合塞进角色表。它依赖当前发布任务的 createdBy，属于资源和上下文共同决定的领域策略。把它写成明确规则，才能测试，也能在拒绝时解释。

拒绝也需要解释

一个成熟权限系统不仅返回允许或拒绝，还应给出缺少的条件。用户知道需要哪种权限、去哪里申请，平台支持成本会显著下降。

授权变化要被审计：谁在何时授予了什么范围，为什么授予，何时过期。高风险操作还需要职责分离，避免同一人发起并批准。

审计日志保存的是当时的决策证据，而不只是操作结果：

requestId / subject / action / resource
decision / reason / policyVersion
matchedGrants / evaluatedAt

如果半年后只知道“用户当时有管理员角色”，无法复原这个角色在当时包含哪些权限。保存策略版本和匹配授权，才能回答一次高风险操作为什么被允许。

缓存不能改变授权事实

权限查询频繁，团队自然会考虑缓存。缓存键必须包含用户、资源范围和动作，失效要响应组织与授权变更。管理员刚撤销生产权限，旧缓存不能继续允许操作。

对于高风险动作，可以接受额外延迟以换取实时检查；低风险只读能力则可使用短缓存。安全与性能不是统一答案，而要按后果分级。所有最终判断仍应记录当时使用的策略与权限版本，方便审计。

前端隐藏入口可以改善体验，真正的权限验证必须发生在服务端。安全边界不能依赖用户看不见按钮。

前端仍然应该消费同一份能力结果，用于禁用按钮和解释申请路径，但不能自己复制策略。否则服务端改规则后，页面可能显示可操作，提交却被拒绝；更糟糕的是页面隐藏了入口，API 却没有检查。

RBAC 是起点，不是答案。只有把权限放回具体领域，模型才会既安全又可维护。

权限规则必须拥有反例测试

每条允许规则至少配一个“相似但必须拒绝”的反例：项目管理员能发布本项目，不代表能发布别的项目；报表查看者能导出可见字段，不代表能导出隐藏个人信息。

allow: actor.role=project_admin, action=release.deploy, resource.projectId=actor.projectId
deny case: same role, different projectId
deny case: production environment without approval
audit: policyVersion + matchedRule

反例让权限从角色名称回到真实资源和上下文。

如果租户隔离只依靠开发者记得加条件，它迟早会失效。我们把 tenantId 从可选业务参数提升为安全上下文，在认证、服务、仓储、数据库和审计五层重复约束。

图 1：纵深防御不是重复浪费；任意一层遗漏时，下一层仍能阻止跨租户数据返回。

tenantId 只能来自可信身份

客户端可以选择当前工作空间，但不能自由声明自己属于哪个租户。网关根据会话和成员关系解析上下文：

type RequestContext = {
  actorId: string;
  tenantId: string;
  roles: string[];
  requestId: string;
};
 
async function resolveContext(session: Session, requestedTenant: string) {
  const membership = await memberships.find(session.userId, requestedTenant);
  if (!membership) throw new ForbiddenError("TENANT_ACCESS_DENIED");
  return { actorId: session.userId, tenantId: requestedTenant, roles: membership.roles };
}

后续代码接收 RequestContext，不再从 query/body 重新读取 tenantId。这样用户输入和授权结果不会混成同一个字符串。

仓储接口强制要求上下文

class CustomerRepository {
  constructor(private readonly db: Database) {}
 
  list(ctx: RequestContext, filter: CustomerFilter) {
    return this.db.query(
      "SELECT * FROM customers WHERE tenant_id = ? AND status = ?",
      [ctx.tenantId, filter.status],
    );
  }
}

不提供 listAll() 给普通业务层。确实需要跨租户的后台任务使用另一套明确命名、权限更高的接口，并要求 reason 和审计。

数据库层再做一次策略兜底

支持 Row-Level Security 的数据库可以在事务开始时设置租户上下文，让策略自动过滤：

ALTER TABLE customers ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY tenant_isolation ON customers
USING (tenant_id = current_setting('app.tenant_id'));

应用连接池必须在每个事务显式设置并结束后清理上下文，不能让租户状态泄漏到下一位请求。数据库策略也不能替代服务层授权：它保护行范围，不一定理解“某角色能不能导出”这样的动作。

唯一约束和缓存 key 也要带租户

隔离不仅发生在 SELECT：

UNIQUE (tenant_id, external_customer_id)

缓存 key 使用 tenant:{tenantId}:customer:{id}；对象存储路径、搜索索引、消息 payload 和指标标签都携带租户。漏掉任何一个共享系统，都可能形成旁路。

测试必须故意制造相同 ID

如果测试数据里两个租户的资源 ID 永不重复，漏过滤可能仍然看不出来。我们给租户 A、B 创建相同业务编号、相似名称和不同秘密字段，所有读取、更新、删除、搜索、导出都做负向断言。

跨租户管理员功能单独测试：授权明确、界面显著提示当前范围、操作需要理由、结果进入审计。不能因为运维方便就在普通请求里增加 allTenants=true。

这次险情没有造成真实数据泄漏，但它改变了架构标准。tenantId 不是开发者自觉添加的过滤器，而是贯穿系统的安全上下文。让错误必须同时穿过五层防线，远比要求每个人永远不忘一行 WHERE 可靠。

这时 CI/CD 已经不是工具配置，而是一款服务团队的内部产品。开发者是用户，提交到上线是用户旅程，失败信息就是产品反馈。

设计默认路径

多数项目应该通过模板获得一致的检查、构建、制品与部署步骤。差异通过少量显式参数表达，而不是复制整份配置。模板要有版本，升级也应可控，避免一次修改影响所有项目。

仓库配置只声明意图，平台模板负责实现细节：

pipeline:
  template: web-service@3
  runtime: node-20
  checks:
    - typecheck
    - unit
  artifact:
    command: pnpm build
    path: dist/
  deploy:
    staging: automatic
    production: approval

这里最重要的是 web-service@3 的版本。平台不能在周一悄悄修改模板，让所有仓库周二一起失败。新版本先在样本项目验证，提供迁移说明，再由仓库显式升级；严重安全修复才走受控的强制更新。

默认路径越完整，新项目越不需要重新学习发布细节。但平台也要允许合理例外，否则团队会绕过它。

失败必须可行动

“Job failed”不是有效反馈。失败信息应指出阶段、关键原因、相关日志和可能的处理方式。可重试的基础设施错误与必须修改代码的检查失败，展示方式应该不同。

我会把失败结果结构化，而不是让页面解析日志文本：

{
  "stage": "artifact-upload",
  "kind": "infrastructure",
  "retryable": true,
  "message": "制品存储暂时不可用",
  "logUrl": "/runs/812/logs#upload",
  "suggestedAction": "retry"
}

开发者看到的是“可直接重试，代码无需修改”；平台团队则能聚合同类基础设施故障。两种用户需要不同粒度，但共享同一事实。

流水线还要记录制品来源、提交、操作者和目标环境，使一次发布可以被审计和回滚。速度重要，可追踪性更重要。

制品只构建一次

同一份代码不应在测试和生产环境分别构建，因为依赖、时间和环境差异会产生不同制品。更可靠的流程是构建一次、验证一次，再把同一制品逐级提升。环境配置在部署阶段注入，并留下版本记录。

回滚也要提前演练。能够点击“回滚”不代表数据和依赖仍然兼容，关键服务需要定义可回退窗口与迁移策略。发布流程把这些检查显式化，才能让快速发布不以侥幸为前提。

衡量 CI/CD 不能只看构建时长，还要看等待、失败恢复和人工操作。真正高效的流水线，会让正确做法成为最省力的做法。

我最终会看四个数字：提交到首次反馈的时间、提交到可部署制品的时间、失败后恢复时间、需要人工介入的运行占比。单纯把构建从 8 分钟压到 6 分钟，如果任务仍排队 20 分钟，用户感知几乎没有变化。

图：流水线失败必须带证据和下一步，不能只返回一屏日志。

流水线失败要给出下一步，而不是一屏日志

每个阶段返回稳定错误码、证据链接和建议负责人。例如依赖完整性失败不应提示“build error”，而是指出 lockfile、registry 与缓存 key；部署健康失败直接链接新旧版本指标和回滚入口。

我们按失败后到恢复成功的时间衡量体验，而不是只看流水线成功率。一个严格但能快速自助修复的门禁，比偶尔放过问题、失败后只能找平台同学更像成熟产品。

从那以后我们把审计日志从普通文本日志里拆出来。它面向追责、合规和事故复盘，需要稳定结构、受控访问和独立保留策略。

图 1：一条审计记录至少要能重建“谁、在什么上下文、对什么资源、做了什么、结果如何”。

记录业务动作，不记录 Controller 名

type AuditEvent = {
  id: string;
  at: string;
  actor: { type: "user" | "service"; id: string; tenantId: string };
  action: "project.member.role_changed";
  resource: { type: "project_member"; id: string; projectId: string };
  before: { role: string };
  after: { role: string };
  reason?: string;
  requestId: string;
  sourceIp?: string;
  result: "succeeded" | "denied" | "failed";
};

POST /role/update 会随着路由重构变化，project.member.role_changed 表达的是长期业务语义。查询“所有管理员权限变更”不应该依赖某个年代的接口路径。

审计与业务写入共享提交边界

如果先改权限再异步写审计，进程崩溃可能留下“变更成功但没有记录”。我们在同一数据库事务写业务数据和 outbox 审计事件，独立消费者把它复制到审计存储：

BEGIN;
UPDATE project_members SET role = :new_role WHERE id = :member_id;
INSERT INTO audit_outbox (event_id, payload) VALUES (:event_id, :payload);
COMMIT;

这样审计平台短暂不可用不会阻塞核心事务，outbox 也不会丢。消费者去重 eventId，写入追加型存储，普通应用账号没有更新和删除权限。

before/after 需要脱敏和控制体积

完整对象差异很方便，却可能包含 token、手机号或大段配置。我们按资源类型维护字段白名单，只记录与动作相关的值。秘密字段记录“是否发生变化”，不记录内容。

审计记录本身也是敏感数据，查看审计的行为也要被审计。

被拒绝的高风险动作也值得记录

只有成功操作会留下业务变化，但连续权限拒绝可能是攻击或错误自动化。我们记录关键 denied，包含策略版本和拒绝原因，不把每个普通 404 都灌入审计库。

{
  "action": "production.deploy.requested",
  "result": "denied",
  "policyVersion": "rbac-42",
  "reason": "missing: production.deploy",
  "requestId": "req_8f2..."
}

可查询性要在事故前验证

我们用几个固定问题验收模型：谁在某时间窗修改了项目 P 的生产权限；某用户离职前 24 小时执行过哪些高风险动作；一次 requestId 涉及哪些资源变更；某服务账号使用过哪些权限。

如果这些问题需要临时 grep 文本，审计结构还不够。上线后还监控 outbox 积压、事件写入延迟、字段解析失败和存储完整性校验。

那次权限争议最后无法从旧日志得到完整答案，这是一次真实的信息损失。审计日志的价值不是让系统“看起来合规”，而是在团队最需要事实时，不必靠聊天记录和人的记忆拼凑发生过什么。

队列库能提供投递和消费机制，却无法替业务回答这些问题。

图 1：队列里的消息可以重复，业务任务状态必须持久、幂等，并且知道自动化何时停止。

一，任务能否重复执行

网络超时不代表对方没有成功。消费者重试前，必须假设上一次可能已经完成。为任务建立业务幂等键，并在执行前检查已有结果，可以避免重复创建发布或通知。

幂等键应来自业务语义，而不是每次请求随机生成。例如同一提交向同一环境发布，可以使用 projectId + commitSha + environment。数据库先以唯一约束占住事实，再投递队列：

create unique index uniq_release_request
on release_job(project_id, commit_sha, environment);

const job = await db.releaseJob.upsert({
  where: { projectId_commitSha_environment: input },
  create: { ...input, status: "queued", attempt: 0 },
  update: {},
});
await queue.publish({ jobId: job.id });

队列偶尔重复投递没有关系，消费者读取同一任务并检查状态。真正危险的是先发布消息、后写数据库：进程在两步之间退出，队列里就会出现查不到业务事实的任务。更严格的场景应使用 Outbox，把业务写入和待发送消息放在同一事务。

二，状态是否可追踪

只保存“成功/失败”不足以恢复。任务要记录输入摘要、当前步骤、尝试次数、外部标识和最后错误。队列中的瞬时状态还应同步到持久存储，避免任务丢失后没有证据。

三，错误是否适合重试

超时和临时限流可以指数退避重试，参数错误和权限拒绝则不会因等待而消失。错误分类不清，会制造无意义流量，甚至把小故障放大。

重试代码最重要的不是公式，而是上限和分类：

const delayMs = Math.min(60_000, 1_000 * 2 ** attempt) * (0.8 + Math.random() * 0.4);

没有抖动时，大量失败任务会在同一秒醒来，再次把下游压垮。退避是保护依赖，不是让任务看起来更努力。

四，自动化在哪里停止

超过重试上限的任务要进入明确的失败队列，并提供查看、修正和重新执行入口。可靠系统不是永不失败，而是失败后仍然知道发生了什么、下一步由谁处理。

顺序与并发也要写进语义

同一工程的两次发布任务可能同时进入队列。如果后一个先完成，状态就会倒退。需要按业务键限制并发，或者让更新携带版本条件，只允许从合法前置状态推进。

消费者数量增加会提高吞吐，也会放大数据库和外部接口压力。扩容依据不应只是队列长度，还要观察任务等待时间、执行时间与下游限额。队列把峰值摊开，不代表下游容量已经增加。

异步架构把时间从请求链路中移走，也把一致性问题暴露出来。只有任务拥有可重复、可观察、可恢复的生命周期，队列才真正提高可靠性。

每类任务都保留一份故障回放包

回放包包含脱敏输入、状态转移、每次 attempt、租约变化、外部回执、最终产物和代码版本。事故后能在隔离环境重放到某个检查点，而不是只看散落日志。

我们用它验收三件事：重复投递不会产生重复副作用；Worker 中途退出任务能被接管；结果未知不会被当成失败自动重试。可靠性只有能够重复演示失败和恢复，才真正进入工程资产。

至少一次投递系统里，重复不是罕见异常，而是协议允许的结果。消费者必须让同一业务事件执行多次仍得到同一结果。

图 1：幂等记录与业务结果要共享一致性边界；否则“标记完成”和“实际完成”会分离。

幂等键来自业务事件，不来自消费尝试

每次重投都会产生新的 deliveryTag，不能拿它去重。我们在事件创建时生成稳定 eventId：

type ReleaseCompleted = {
  eventId: string;
  eventType: "release.completed";
  releaseId: string;
  artifactId: string;
  occurredAt: string;
};

同一个发布完成事实，无论投递多少次都保持 eventId。生产者还要防止业务事务成功但消息未发出，因此采用 outbox：业务写入和待发布事件在同一数据库事务提交，后台再把 outbox 发送到队列。

数据库副作用用唯一约束兜底

如果消费者写的是数据库，可以让处理记录和业务写入处于同一事务：

BEGIN;
 
INSERT INTO consumed_events (consumer, event_id, consumed_at)
VALUES ('release-notifier', :event_id, NOW())
ON CONFLICT DO NOTHING;
 
-- 只有上一步确实插入一行时才执行业务写入
INSERT INTO notifications (event_id, channel, payload)
VALUES (:event_id, :channel, :payload);
 
COMMIT;

唯一约束是并发去重的最终防线。先查询“是否存在”再插入，中间有竞态，两个消费者可能同时认为不存在。

外部 API 没有事务怎么办

群机器人不支持与本地数据库同一事务。我们只能选择并明确失败窗口：

1. 先写本地 pending 记录；
2. 调用外部 API，并携带对方支持的幂等键；
3. 保存外部回执，状态改为 sent；
4. 超时但结果未知时先查询，不立即盲目重发；
5. 对方不支持查询或幂等时，接受“可能重复”，在消息正文带 eventId 供人工识别。

所谓 exactly-once 往往只在某一层成立。跨越数据库和第三方系统后，更诚实的目标是 effect-once：通过幂等、查询和补偿，让业务效果尽量只发生一次。

重试按错误类型决定