16. 5 个 STAR 故事#

五个故事索引#

怎么选故事#

面试官问「最难的问题」，选前缀缓存或静默失效，这两个排查过程最长。问「做过什么决策」，选只留一个 Agent。问「怎么做性能优化」，选延迟那条。问「踩过什么坑」，选币种错 7 倍。

STAR 各段的时间分配#

情况和任务加起来 20 秒，动作 50 秒，结果 20 秒。动作段一定要说「否掉了哪个做法、为什么」，这是面试官判断你有没有真做过的地方。

出处：五个故事的提交正文分别是 80c698c、5a27c27、2242ef5 + cccdf1a、eb9d61b、ae4073e + 74dc2a5

这些数字你自己量的吗？

是。每个故事改之前先跑一遍拿基线，改完同样的输入再跑一遍。数字都在提交正文里，改动和数字是一起提交的。

有没有改了之后变差的？

有。币种那条第一版修法是加规则「价格一律用美元」，结果模型把用户的预算 300 元也说成 300 美元，错换了个地方。后来改成删规则才对。

这些是你一个人做的吗？

这个项目是我一个人做的，排查、改动、测量都是我。参考过 Anthropic 公开的购物 Agent 示例和一本 18 章的教学文档。

90 秒完整版（S / T / A / R）#

情况：购物清单最后一步由一个收尾工具排版，文案由模型写。线上出现价格写成人民币、数字不在候选里的情况。同一份输入跑两遍，一遍写「38 美元」，一遍写「到手约 ¥26」。

任务：让清单里的每个价格都来自工具返回，不许模型自己算。

动作：先读提示词，发现两条规则互斥。一条要「价格落在什么区间」，这需要模型跨候选取最小最大做运算；另一条写「价格系统按商品 id 自动带上，你不用也不要写」。我先试了加规则「价格一律用美元符号」，结果模型把用户说的「预算 300」也写成「预算 300 美元」，用户的预算是人民币，还是错 7 倍。于是改成删掉要区间那条。

结果：删后同样输入三遍全对。价格数字的唯一出口改成商品卡，由代码用工具返回的数字直接渲染。

为什么是删不是加#

提示词自相矛盾时，再叠一条规则只是让模型换个地方犯错。矛盾删掉，模型没有理由去算价格，错误就没有来源。

现在价格从哪来#

商品卡上的价格由 _card_reason 用工具返回的 landed_usd 或 price_usd 直接格式化，模型写的文案不含价格数字。

出处：提交 80c698c（2026-09-07）正文、prompt/prompts.yml:243（注释记录了这条被删规则和反面教训）、app/tools/shopping_summary.py:215（_card_reason）、:230（价格取值）

为什么美元会被写成人民币？

到手价字段是美元，但用户的预算是人民币。模型算区间时把两个币种混在一起，没有换算，所以差了大约 7 倍。

怎么保证以后不再出现？

两层。第一，提示词里明确写价格由系统带上、模型不要写。第二，商品卡价格由代码渲染，数字直接来自工具返回，模型碰不到。

这个问题是怎么发现的？

线上用户看到的清单里出现了候选里没有的数字。我拿同一份输入复跑两遍，两遍写法不同，确认是模型在自己算。

提示词自相矛盾，为什么之前没发现？

两条规则相隔几十行，是不同时间加的。加「价格区间」那条时没回头看后面那条。教训是改提示词要通读整段，不能只加一句。

90 秒完整版（S / T / A / R）#

情况：主环就是项目里唯一的那个 Agent 循环。它每轮都把系统提示词和全部对话历史发给模型。前缀缓存要求这次请求的开头和上次逐字一样，所以正常情况下命中率应该逐轮上升。评测批次里有四条问题的命中率反而卡在 31.6% 到 64.1%，只有系统提示词那 2048 个 token 命中。

任务：找出为什么对话历史一次都没命中。

动作：把每轮真正发出去的请求打出来逐轮比对。发现套在模型外面的检查代码会在某些轮插一条临时提醒，比如「你在重复搜索」「必须调收尾工具」。这条提醒只拼进当轮请求，没有写进对话历史。下一轮请求里它不见了，第 N+1 轮的开头就不再是第 N 轮的延伸，缓存断掉。修法是提醒消费之后随模型回复一起写进历史。同类还有两处：催收尾时重发的首答，和一条每轮重复注入的预算提示，改成只在换档那一次注一次。

结果：那条最差的问题复跑，8 次搜索加 3 次跑偏提醒的病态路径，命中率从 31.6% 升到 67.5%。注入那一轮付一次重算，之后逐轮递增。

一个容易说错的点#

命中率高不是 cache_control 标记的功劳。本项目用的服务商是隐式前缀缓存，带标记和不带标记的对照组第二次都命中。标记继续打是因为零成本，真正起作用的是「请求开头逐字稳定」。

出处：提交 5a27c27（2026-07-16）正文、app/harness/adapter.py:74（_persist_injections）、:77（注释「不落 state 的代价是缓存塌方」）、app/harness/formatter.py:9（标记不是命中率的原因）

为什么不直接不插这些提醒？

提醒本身有用，跑偏和不收尾是 Agent 最常见的失败。问题不在插，在插了不留痕。写进历史之后它既起作用又不破坏前缀。

写进历史不会让上下文越来越长吗？

会长一点，但提醒只在触发时插，一次会话最多几条。每轮重复注的那条预算提示我改成只注一次，就是为了不攒一摞。

怎么防止以后再有人犯同样的错？

有一个基线脚本跑固定请求并输出命中率，改注入逻辑后可以对比。它要调真实模型，没放进每次提交都跑的测试。

前缀缓存和 KV cache 是一回事吗？

前缀缓存是服务商把前缀的 KV cache 存下来复用。对调用方来说，能控制的只有请求开头是否逐字一致。第 07 章有展开。

90 秒完整版（S / T / A / R）#

情况：架构改过两次。第一版子 Agent 是主 Agent 的完整克隆，第二版改成主从：主 Agent 分配，检索子 Agent 和交易子 Agent 各管一类工具。第二版跑了一段时间，我想确认它值不值。

任务：用线上数据判断子 Agent 有没有被用上，再决定留还是删。

动作：统计会话记录。交易子 Agent 经历 440 个会话，派发 0 次，因为下单和取消本来就只出一张确认卡，让用户点按钮走 HTTP 接口，主 Agent 自己做也不碰安全边界。检索子 Agent 派发 60 次，每次只调一次搜索工具就回来，定点调查 0 次、真实用户 0 次。派发的价值在于子任务要跑多步或者中间结果太大，这两条都不满足。于是分两步删：先删交易子 Agent，再删整条派发机制，包括派发工具、派发预算、子 Agent 的提示词段。权限文件保留，因为写工具仍要精准放行。

结果：跨平台和多槽位检索改成同一轮发多条 item_search。真模型验收 4 遍，每遍同轮 3 到 5 条，派发 0 次。这和 Anthropic 公开的购物 Agent 示例一致，那个示例也是一个模型一个循环。

删了什么，留了什么#

出处：提交 2242ef5（2026-09-15，删交易子 Agent）、cccdf1a（2026-09-16，删派发机制）、2592361（合并）、app/agent/agents.py:8（模块说明）、CLAUDE.md §2.2

60 次派发都只搜一次，是不是提示词没写好？

可能有一部分原因。但就算提示词写好了，我们的子任务本身就是「搜一次」，多一层转发不会让它变成多步任务。

删掉之后，安全边界靠什么？

靠三样代码机制：工具标好是不是只读，权限引擎只给点名的写工具开门，下单只出确认卡、用户点按钮走 HTTP 才真下单。这三样删子 Agent 前后没变。

前两版算白做了吗？

不算。第一版暴露了权限只靠提示词的问题，第二版拆了读写。这次能下决心删，依据就是第二版跑出来的数据。

什么情况下你会改回多 Agent？

子任务自己要跑很多步，或者中间结果很大不适合放进主上下文。比如让一个子 Agent 读几十个网页做研究。

90 秒完整版（S / T / A / R）#

情况：前两轮提速已经把每轮多余的 token 压掉了，比如候选商品不再整段重复输出。剩下的每个 token 看起来都有用，但一条验收问题还要 83.2 秒。

任务：在看起来没有浪费的流程上再找出能删的东西。

动作：先做两份数据。一份是全量事件时间线，每个事件带时间戳；一份是逐轮 token 复盘，每轮的输入、输出、思考、缓存命中四个数。两份对上之后，83.2 秒的构成很清楚，见下表。然后四项改动全是删东西：planner 换成同模型关思考的档位，改前先做对照实验，两档解析产出一致；收尾工具的返回本来就是给用户看的完整清单，模型再念一遍只多一句开场白，所以执行层看到收尾产物就直接结束；比价和运费两个工具都是零秒的纯计算，拆成两步却要模型中间多解码一轮，合成一步；模型曾在候选够了之后又发搜索、被规则拒绝，白烧一轮，所以把下一步能调什么提前告诉它。

结果：83.2 秒降到 39.7 秒，主循环 9 轮变 5 轮。690 个测试全过。

83.2 秒的构成#

四项改动现在的状态#

前三项都还在。第四项依赖的四阶段状态机在 2026-09-21 删掉了，现在的做法是搜索成功后自动跑比价和精挑，模型不用自己决定下一步。

出处：提交 eb9d61b（2026-07-13）正文、docs/milestones/Mperf.2 归因表、app/tools/planner.py:597（get_planner_llm）、app/harness/adapter.py:162（收尾直接结束）、app/tools/price_compare.py:8（合并原因）、app/harness/hooks/progress.py:13（状态机已删）

关掉思考模式，质量不会掉吗？

planner 是结构化抽取，输出受 schema 约束。对照实验两档的预算、品类、排除词一致。风险是只测了一条问题，所以还有评测种子集做回归。

为什么最大的耗时藏在工具里没人发现？

事件时间线上工具就是一个「开始、结束」，看不到里面调了模型。教训是工具耗时要拆成工具逻辑和工具内模型调用两部分。

收尾不让模型复述，用户体验有变化吗？

有。用户看到的从模型转述变成收尾工具原文，语气少一层人味。好处是聊天回复、下载的清单文件、商品卡三处文案从此一定一致。

三轮提速的数字能连起来说吗？

不能。三轮用的测试问题不同，基线也不同。第 09 章有三轮的分表。

90 秒完整版（S / T / A / R）#

情况：运行时从 LangChain 换成 AgentScope 2.0，中间有个开关让两套并存。测试都绿，线上也在跑，但有些行为对不上：比如每轮开头多一次模型调用，图搜功能整条不通。

任务：摘掉 LangChain，同时把新框架侧「看起来在跑、其实没生效」的功能全找出来。

动作：不是删旧代码就完，而是每个功能在两套运行时里对照。开局预跑 planner 在新框架从没实现，补进适配器。工具入参校验失败原本是模型传错参数，却被计进进程级共享的熔断器，补上校验异常豁免。派发预算指着两个已经删掉的工具名，改成按次数限制。用量统计拿到畸形数据会把异常甩回主循环，改成记日志跳过。测试从旧适配器迁到新适配器，不是删掉，31 个检查代码的用例改用新的会话对象驱动。两天后又查出第 5 个：某个模型在被强制指定函数时只回一张存根，全默认值的 schema 校验照样过，线上多数轮次拿着空表在跑。改成先用 auto 模式，再加一道空表检查。

结果：LangChain 依赖全部移除，1060 个测试全过。五处失效全部有对应测试。

五处失效一张表#

派发预算那条随派发机制在 2026-09-16 一起删了，现在不存在。

出处：提交 ae4073e（2026-09-06）正文、74dc2a5、app/harness/prefill.py:1（开局预跑）、app/harness/adapter.py:488（校验异常不计熔断）、app/agent/invoke.py:148（call_structured）、:162（存根问题的记录）

为什么测试没抓到？

测试是按旧运行时写的，新运行时那侧根本没有对应用例。所以这次的原则是测试迁过去，不是删掉。

存根那个问题，怎么发现的？

planner 拆出来的字段太单一，每条问题都只有一个默认任务。回头看原始返回，发现模型被强制指定函数时只回了最短的合法 JSON。

空表检查怎么判「空」？

不按值比较，按字段有没有出现过。显式传 null 是合法结果，按值比较会把它误判成空表，每条无预算的问题都会多采样一次。

迁移前做了什么准备？

先做了 4 个小实验钉死工具返回形态和缓存标记能不能传到请求里，确认框架能承接再动手。

两版修法对比#

判断标准#

改提示词时我会问一句：这个改动是让问题不发生，还是让问题测不出来？加规则属于后者，它只覆盖我测到的那个例子。删矛盾属于前者。

出处：提交 80c698c 正文第二段、prompt/prompts.yml:248（注释里的反面教训）

如果非要在文案里提价格怎么办？

让工具把带币种的价格字符串算好传给模型，模型只能原样引用。数字从代码来，模型不做运算。

这类提示词矛盾怎么系统性地发现？

目前靠评测：同一输入跑多遍，输出不稳定就说明模型在两条规则之间摇摆。没有自动化的矛盾检测。

为什么不用更强的模型？

矛盾的提示词换什么模型都是赌。而且强模型更贵更慢，收尾这步是延迟大头。

三个位置对比#

现状#

现在偏好由检查代码在 planner 跑完后作为系统消息追加，不碰系统提示词前缀。它在一次任务内不变，所以任务内缓存不受影响。formatter.py:76 的注释写「系统提示词纯静态、无运行时注入」已经过时，以 context_shaping.py:211 为准。

出处：docs/milestones/M6.1 第 2、3 节、app/harness/hooks/context_shaping.py:103（偏好注入钩子）、:211（追加系统提示词块）

命中率怎么量？

模型返回的用量里有 cached_tokens 字段，除以输入 token 就是命中率。请求不报错不代表缓存生效，必须看这个数字。

服务商不支持显式标记怎么办？

本项目的服务商就是隐式缓存，不看标记，只看前缀是否逐字一致。所以真正要做的是让前缀稳定，标记只是顺手打。

历史越来越长，缓存还有用吗？

有。历史只在尾部增长，前面不变，命中的部分逐轮变多。超过阈值由框架做压缩，压缩后前缀会变一次。

对照实验采集六列#

评测分数、总耗时、模型调用次数、成本、子 Agent 误调写工具次数、派发次数。六条问题串行跑，因为并发会被排队噪声淹没。

两次实验的区别#

出处：提交 09edc3b（2026-09-06）正文、docs/handbook/01「走过的弯路」表、对照脚本已归档到 scripts/archive/

只启用 amazon，跨平台功能还有意义吗？

召回库里 amazon 占绝大多数，这是数据限制，第 18 章有讲。同轮多发搜索现在主要用在套装的多个槽位上，不只是多平台。

440 个会话里有多少是真实用户？

提交正文没有拆分，只写了检索子 Agent 那 60 次派发里真实用户 0 次。这个数字面试时要说清是混合数据。

为什么不直接看日志数派发？

子 Agent 的消息不回传主循环，主线程日志里看不到它调了什么工具。只有在工具调用前挂探针才数得到。

两轮不产生决策的浪费#

• 撞规则轮：候选够了之后模型又发两条搜索，被规则拒绝。规则是对的，但模型花了 3.1 秒解码去撞墙，下一轮思考飙到 498 个 token 在消化被拒。

• 复述轮：收尾工具的返回就是完整清单，模型又花 729 个 token、7.5 秒把它重新排版一遍，还有抄错数字的风险。

机制正确不等于机制免费#

检查代码拒绝得对，但模型撞上去的那轮解码是实打实的延迟。所以后来把信息提前给模型，检查从「拦截」退成「保险丝」，正常路径碰不到它。

出处：docs/milestones/Mperf.2「归因」与「结论」两节、提交 eb9d61b 正文

96% 耗时在模型解码，这个数怎么来的？

上一轮延迟审计量的。全部真实工具加起来不到 2.5 秒，其余都是模型在生成 token。所以优化方向是减 token 和减轮数，不是优化工具。

为什么不换更快的模型或服务商？

这轮零新增基础设施，没加缓存层、没加并行框架、没换供应商。每一项都是把不产生价值的 token 拿掉，没有新东西要维护。

现在线上怎么看这些数据？

接了 Langfuse 看每次调用的耗时和 token，工具耗时超阈值有告警。第 09 章有讲。

空表检查踩过的坑#

• 按值比较：显式 null 会被当成缺席，每条无预算的问题都多采样一次。

• 用 model_fields_set 判：存根里凭空多出默认字段名，检查永远不触发。

• 强制指定函数：模型只回最短合法 JSON，全默认值校验照过。所以先 auto，再检查。

熔断计数的唯一判据#

工具异常里只有非校验类的才算失败。校验失败是调用方的问题，熔断器是进程级共享的，计进去会让一个模型错误影响所有会话。

出处：app/agent/invoke.py:111（空表异常说明）、:131、:138（两个坑的记录）、:162（第四个坑）、app/harness/adapter.py:488（校验异常豁免）、提交 ae4073e 正文「测试从旧适配器迁到新适配器」

为什么不用集成测试直接跑真模型？

真模型的测试贵而且不稳定，没放进每次提交都跑的那批。有一个评测种子集在改动大的时候跑，属于回归。

连续两次空表之后怎么办？

抛一个专门的异常，调用方按自己的方式降级。解析失败和空表是两种问题，一个是这次请求坏了，一个是模型在这条提示词上退化了，日志要分开记。

迁移时怎么保证行为不变？

先做 4 个小实验，钉死工具返回形态和缓存标记能不能进请求。再让测试在两套适配器上都跑。

三条对应表#

反例也要说#

币种加规则那版、第一次对照实验作废、缓存标记被误以为是命中率的原因，这三个都是先做错再改对的。讲出来比只讲成功可信。

出处：本章 c02 到 c11 各卡的提交正文

「能删就不加」会不会删过头？

会。所以删之前要有数据，删之后要有验收。子 Agent 删完用真模型跑 4 遍，延迟改完 690 个测试全过。

这些方法在团队里怎么推？

把数字写进提交正文。改动和数字一起提交，别人看历史就知道为什么改、改了多少。

哪个故事你觉得最有价值？

静默失效。它说明测试绿不等于功能在跑，这个意识比任何单个修复都值钱。