我从没想过，一个 Agent 可以同时做到三件事：什么都没产出，占满我的硬盘，还烧完了我的配额

五天前我看到 Claude Desktop 上多了一个叫 Coworker 的功能，很兴奋。它在实验室（Labs）标签下，意味着是”研究预览”。作为一个做 Agent 开发的人，我对各种 agent 形态天然好奇，第一时间就试了。

两天后，C 盘红了。

我以为是我装了什么东西——最近没装过。然后我发现多了整整 13GB 的 Claude 应用数据。同一天，我发现我的 Claude Pro 日配额被全部烧光，什么都没产出来。

我当时真的是一脸问号。我知道 agent 会吃 token，但我没想到一个课程报告任务能在背后吃掉这么多资源。

我看到了什么

先说我当时在做什么。我让 Coworker 帮我写一份大数据系统课程设计的报告，上传了项目结构文件和 README，选了一个工作文件夹。很简单的任务。

过了一段时间，我发现 C 盘剩余空间从正常水平掉到了不到 2GB。我质问 Coworker「你做项目怎么吃了 C 盘那么大的空间」，然后它继续自顾自折腾，最后报了一个错：

You’ve hit your session limit · resets 6:50am

我打开 C:\Users\...\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ 一看：

• vm_bundles/claudevm.bundle — 12GB
• Cache/ + Code Cache/ + GPUCache/ — 几百 MB
• claude-code-vm/ + claude-code/ — 几百 MB
• local-agent-mode-sessions/ — 会话残留

加起来 13GB。一个课程报告，13GB。

然后我去翻会话日志。它用了 claude-opus-4-6——最贵的模型。一共 156 轮 assistant 回复。

156 轮。为一个课程报告。

到底发生了什么

我从会话目录里挖出了 audit.jsonl 和 local_*.json，完整还原了时间线。

它一启动就做了几件事：创建了 5 个 Task，读了项目文件，然后——开始不停地重试一个叫 bash 的工具调用。

“Workspace still starting. The isolated Linux environment is booting in the background (usually 10-30 seconds). Try again shortly.”

这条错误在日志里出现了 82 次。

82 次。每次重试，Coworker 都把整个对话上下文重新发给 Claude Opus 4.6。而那个 system prompt 有多长？我把原始内容提出来了，包含了 Anthropic 全部产品线介绍、行为规范、tone 指引、artifacts 渲染规则、文件处理规则、65 个 skill 定义——以及一种令人窒息的”系统提示词膨胀”。

每一次重试的成本 = 巨型 system prompt + 所有历史消息 + 工具调用结果 + 模型推理输出。乘以 82。

更离谱的是，它在 17:07 就打满了第一轮 5 小时配额——从会话开始算，只过了 15 分钟。等到 17:51 重置后，它继续工作，然后在 18:25 第二次烧光。

一个会话，两轮配额。为零产出付费。

作为一个做 Agent 的人，我看到的是什么

这不是模型的问题。Opus 4.6 只是做了一个 agent loop 让它做的事——收到错误，重试。重试。重试。被拒了还要重试。

问题是整个 agent 系统设计上的缺陷，而且这些缺陷对我来说太眼熟了：

1. 没有熔断

这是最致命的问题。同一个工具调用，同一个错误，重试 82 次。任何一个生产级系统都会在连续 N 次失败后停止并向上汇报，但 Coworker 没有。它不是缺少推理能力，而是缺少一个对失败模式的基础检测。

作为对比，如果我在自己写的 agent loop 里发现同类型错误连续出现 5 次，我会立刻打断循环、记录异常、提示用户。这不是因为我的模型更聪明，而是因为我给 loop 加了护栏。

2. 用最贵的模型做最机械的决策

判断「上次 bash 调用失败了，我应该再试一次」这件事——不需要 Opus。一个 if-else 就够了。如果用 Haiku、甚至一个简单的状态机来处理重试逻辑，token 消耗能差出几个数量级。但 Coworker 把所有决策都交给 Opus，包括那些根本不需要「推理」的步骤。

3. 上下文膨胀失控

那个 65 个 skill 全部预加载到 system prompt 里。用户要写一个课程报告，不需要知道怎么发营销邮件、做 SEO 审计、设计品牌评审。把和任务无关的 skill 定义按需加载而不是预加载，是最基本的优化。但设计上选择了「全部塞进去」。

这不是 prompt engineering 的问题，是架构选择的问题。

4. Loop 模式缺乏目标锚定

Loop 模式的设计意图是让 agent 能「自主推进工作」——做完一步，检查结果，决定下一步。但实际执行中，它没有一个有效机制来判断「我是不是还在朝目标前进」。

它创建了 5 个 Task，然后因为沙箱起不来，全部卡住。但它没有把「沙箱不可用」这个信息用来重新规划方案（比如不用沙箱，用本地文件工具），而是原地重试。目标锚定不够强。

5. 资源泄漏

那个 12GB 的 claudevm.bundle 是一个 VM 镜像。它被下载下来之后，即便 VM 启动失败了，也没有被清理。用户永远不知道这个文件存在，系统也不会自动回收。

这是一个很经典的 agent 后处理缺失：创建了资源，却没有生命周期管理，没有清理策略，也没有失败回滚。

这不是”技术预览”的借口

我理解 Coworker 是 Labs 下的「研究预览」。我也做实验性功能，我知道 preview 意味着不完美。

但这里有些问题不是功能不完善导致的，而是架构上缺少对 agent 常见失败模式的防御：

• 把重试逻辑交给模型而不是框架——这不是 feature，是 bug
• 不检查操作是否有效就反复执行——这也不是 preview 能解释的
• 无上限消耗用户配额——这更不能接受

我的观点是：agent 系统的基础护栏不应该比功能本身更晚交付。 没护栏就上线，等于把一艘没有水密舱的船开进了 open sea。你觉得水会从哪里进来？当然是所有地方。

总结

这次经历的荒诞之处在于，它用一种极端高效的方式同时失败：

• 磁盘占用？13GB 全在
• Token 配额？两轮烧光
• 实际产出？几个用不上的 SVG 和一段没跑通的 Python

1.5 小时内，我什么都没得到，但失去了一切：空间和额度。

作为一个做 agent 的人，我其实不生气于这个功能做得不好——我生气的是，我看到的问题全是我每天在防范的东西。熔断、模型分层、上下文精简、资源回收、目标检查——这些不是 rocket science，这些就是 agent engineering 的基本功。

如果一个 agent 产品在最贵的模型上、在用户的生产环境里、没有任何护栏地运行，那这不仅仅是一个 bad experience。这是一个 design failure。

后记：我把 13GB 数据清掉了。Coworker 功能我短期内不会再碰。但我感谢这次经历——它让我更确信，agent 工程真正的难点不是让模型变聪明，而是在模型变蠢的时候，你还有一道防线。

有时候我会觉得，普通人读历史是一件很容易被嘲笑的事。尤其是男性，只要一谈历史，空气里就会立刻冒出一种若有若无的讥讽，好像潜台词永远是：你现实里也没做成什么，怎么还好意思去谈帝国、战争和人物沉浮。

我一直不喜欢这种说法，却也很难立刻反驳。直到最近，我才慢慢把自己的想法理清楚了。

我对历史的兴趣，根本不是为了借古人给自己脸上贴金，更不是为了在饭桌上表演一种廉价的宏大感。我真正着迷的，是另一种东西：历史几乎是我能接触到的，成本最低的人性模拟器。

现实里的很多局面，我们根本没有试错资格。我们很难真的去体验兵临城下时的恐惧，很难体验权力在手时人的傲慢，很难体验忠诚、背叛、犹豫和误判在极端处境里会怎样同时发生。可历史把这些极限时刻保留了下来。只要你愿意认真带入，愿意暂时放下“后见之明”的优越感，它就会把一个人推到你面前，让你去看他在命运的重压下，到底暴露出什么。

这也是我越来越觉得历史迷人的地方。它不是一堆供人背诵的年份和结论，而是一座巨大的心理沙盘。你可以隔着几百年，反复揣摩那些选择是怎么发生的：伟大是怎么来的，卑鄙是怎么发生的，平庸又是怎样在关键的一分钟里改写结果的。现实生活里亲自去做这些实验，代价太大了；读历史，至少还能让人以比较安全的方式，见识人性的边界。

更有意思的是，读到后来，你会发现自己不只是在看事件，也是在看叙述事件的人。史料从来不只是记录，它也是情绪，也是立场，也是取舍。一个词为什么这样用，一段经历为什么被轻轻带过，某个细节为什么写得格外重，很多时候都比表面事实更耐人寻味。那种顺着文字往回摸，慢慢察觉记载者个人倾向和隐秘判断的感觉，很像隔着时空破案。这种乐趣，别的东西真的很难替代。

我想，别人真正讨厌的，未必是“有人读历史”这件事。他们讨厌的，多半是有人借历史代入权力，借宏大叙事装点自己，把现实中的无力感翻译成一种高高在上的指点姿态。坦白说，我也不喜欢那种样子。但这不该反过来变成另一种粗暴判断，仿佛一个普通人只配盯着眼前的工资、实习和日常生活，根本不该抬头去想更远的事。

对我来说，恰恰相反。越是普通人，越需要历史。

因为这几年真正让我不安的，不是某一个具体事件，而是人们对战争、苦难和民族主义的认知，正在被媒介一点点改写。我们这一代对战争还保留着的一点敬畏，很多时候其实是被长篇叙事续上的。小说、电影、纪录片之所以重要，不只是因为它们提供知识，更因为它们愿意花时间，把战争重新还原成具体的人、具体的疼痛、具体的失去。它们逼着你停下来，逼着你看见那些原本很容易被口号和地图吞掉的命运。

短视频的逻辑几乎是反过来的。它当然也能传递信息，但它天生更擅长切片、加速和放大情绪。战争一旦被剪成十几秒的高燃片段，配上节奏鲜明的音乐、立场明确的字幕和一眼就能看懂的敌我叙事，它就很容易从一场真实灾难，变成一种可以被消费的视觉刺激。最可怕的地方不在于有人无知，而在于整个社会慢慢失去对苦难的重量感。我们越来越容易为立场激动，却越来越难为生命本身感到沉重。

这也是为什么我会对当下的信息环境格外警惕。算法最奖励的，从来不是耐心、灰度和克制，而是愤怒、确定和对立。它会让人产生一种危险的幻觉：好像复杂问题都能被一句口号概括，好像历史不再需要理解，只需要站队。久而久之，战争会被审美化，民族主义会被日常化，而那些原本应该带来警惕的历史回声，只会在一轮轮转发和配乐里被磨平。

我当然知道，一个普通人没办法阻止这些事情发生。我也没有那么大的能量去扭转什么时代潮水。但历史对我仍然有用，因为它至少能帮我守住一点精神上的自主权。

它不会让我变得更有权力，却会让我对权力的语言更敏感。它不会让我站到更高的位置，却会让我更快识别那些熟悉的煽动、包装和自我神化。它不会直接给我答案，却会让我在面对宏大叙事时，先去怀疑其中被省略的人、被遮蔽的代价，以及那个讲述者到底希望我相信什么。

所以我越来越觉得，普通人读历史最大的意义，不是让自己变得更会说，而是让自己不那么容易被说服。不是让自己拥有一种“我懂大局”的幻觉，而是让自己在这个越来越轻、越来越快、越来越爱下结论的时代里，保留一点对复杂性的尊重，保留一点对人性的耐心，也保留一点不愿意被集体情绪随便拖走的倔强。

最早让我真正体会到这一点的，还是茨威格的《人类群星闪耀时》。我喜欢它，不是因为它把历史写得多么宏大，而是因为它总能把命运压缩进某个决定性的瞬间，让人物的伟大、怯懦、盲目和犹豫一起暴露出来。那种写法很容易把人拉进去，让你不只是“知道发生了什么”，而是真的开始追问：如果我是他，我会怎样？如果换一个人站在那里，历史会不会拐向另一条路？

从那一刻起我慢慢明白，历史并不只是属于专家、胜利者或者讲台上的人。它也属于愿意认真观察人的普通读者。属于那些知道自己改变不了多少，却仍然不想把大脑完全交给情绪、算法和潮流的人。

我现在仍然想继续读历史。不是因为我想借它抬高自己，也不是因为我想靠它证明什么。只是因为在这样一个信息越来越碎、表达越来越快、判断越来越轻浮的时代里，我还是想给自己的精神留一点纵深。

最近在做一类很典型、也很折磨人的 Agent 质量问题。

表面上看，现象是「grain 不准」「business meaning 不稳」「PK 假阳性偏多」；但如果往下拆，就会发现这些问题其实根本不在同一个层面上。
有的是输入信号不够，有的是任务拆法不对，有的是规则层该做的事被硬塞给了 LLM，还有的是其实模型已经答得差不多了，只差一个后处理校验帮它把明显矛盾拦下来。

所以我后来给自己整理了一套更顺手的调优框架：

先别急着换模型，先判断问题到底发生在哪一层。

一张表先把武器库摆清楚

还有两件我现在基本不会优先考虑的事：

1. Fine-tune 模型：周期太长，13 天这种节奏根本不现实。
2. 产品端人工干预：这应该留到决赛产品化阶段，而不是当前自动构建阶段。

这个表对我最大的帮助不是“列手段”，而是提醒我：
不同问题要用不同武器，不要一上来就把所有锅都甩给 prompt。

先判断问题落在哪一层

我现在看 Agent 质量问题，通常先问自己三件事：

1. LLM 是不是根本没看到足够的结构信号？
2. 这个判断到底是不是本来就更适合规则做？
3. 模型已经给出一个差不多的答案了，只是缺了一层兜底校验？

如果这三件事没想清楚，就很容易进入一种假忙碌状态：

• prompt 越写越长
• 示例越塞越多
• token 花得越来越快
• 结果还是没有稳定提升

很多时候不是模型不行，而是我们把不该让它承担的任务，硬塞给它了。

问题 A：grain 准确率低，优先补输入和规则

当前这个问题里，我最先盯的是 grain。

因为一旦 grain 判断错了，后面很多描述都会跟着偏：你以为它在解释一张事件表，实际上它把它当成了维表；你以为它在总结“交易粒度”，它却写成了“实体信息表”。
所以 grain 是上游问题，也是最该先处理的问题。

Lever 1：先增强输入信号

目前只给 5 条 sample 和一些 null / unique 比例，其实经常不够。

更有价值的信号包括：

1. 行数级别提示：row_count: 50000 比单独几条样本更能说明这是一张大事实表还是大维表。
2. 跨表上下文：把 *_id 的引用关系摘要塞进 prompt。比如 LLM 一旦看到 fact_session.user_id -> dim_user.id，就更容易理解 fact_session 是 transaction 或 event 粒度。
3. 统计学线索：如果表里有 *_at 字段，可以补时间分布、增长趋势、大小分位数，这些都会帮助模型判断这是一张行为流还是实体快照。

我现在越来越相信一件事：

很多“推理错误”，本质上只是证据不足。

Lever 5：让规则做 70%，LLM 只做边界情况

grain 这种结构化判断，其实规则层就能覆盖掉很大一部分。

例如：

• fact_ 前缀 + 多个 FK + row_count > 100k，几乎一定是 transaction / event
• dim_ 前缀 + 单 PK + row_count < 10k，大概率是 dimension

这里最重要的一点不是“把规则写死”，而是：

把规则写成高优先级信号，而不是硬编码真理。

因为不同公司命名并不统一。电商可能用 ods_ / dwd_ / dws_，金融也可能是完全不同的一套体系。
所以规则应该提供强烈提示，但最终仍允许 LLM 覆盖，这样才能避免把系统做成只会识别某一类数据仓库命名习惯的工具。

问题 B：business_meaning 不稳，通常先别单独修

business_meaning 这个字段表面上看是另一个问题，但在我这次实践里，它经常只是 grain 误判的连带伤。

因为语言层面的总结，本来就是 LLM 更擅长的事。
只要它先把这张表的本质看对了，business_meaning 往往会自动跟上。

所以我的顺序不是“同时修两个问题”，而是：

1. 先把 grain 稳住
2. 再看 business_meaning 还剩多少问题

如果 grain 已经对了，business_meaning 还不够好，这时候再上 Lever 4 做后处理校验就很划算：

1. 检查 business_meaning 里是否包含和 grain 对应的关键词
   比如 grain = event 时，描述里至少要出现“事件 / 行为 / 操作”这类词。
2. 检查长度
   比如要求 < 30 字，避免它一展开就像在写报告。
3. 检查是否带入数据集特异词
   比如一旦出现“电商”“金融”这类词，就应该报警，因为这很可能说明描述已经开始过拟合当前样本数据集。

这个阶段 LLM 不是不会说，而是需要一个更工程化的护栏，帮它把明显不稳的输出裁掉。

问题 C：PK 假阳性，不要再怪 LLM

像 created_at、name 这种字段也被判成 PK，我现在会直接把它归类为：

这不是 LLM 问题，是 dataset ingestor 的规则层问题。

这里最合适的组合是：

1. Lever 5 规则前置
   先加排除规则：

   • 即使 unique = 1.0
   • 但字段名如果命中 *_at / *_time / name / email / description
   • 就不要直接进入 PK 候选

2. Lever 4 LLM 校验
   把规则筛完之后的候选再丢给 LLM，只让它回答一件事：

   • 这是主键
   • 还是“碰巧唯一”

这才是比较健康的分工方式。
规则负责先把明显错的候选过滤掉，LLM 负责处理那些“规则不敢拍板”的剩余情况。

真正执行时，我会分三轮推进

Phase 1：高 ROI、低成本，先上 1 + 4 + 5

第一阶段我最看重的是这三个：

1. 输入信号增强
2. 后处理校验
3. 规则前置

因为这三个都是结构性改进，而且基本不依赖某个具体数据集。
它们做好了，不只是当前这个任务受益，后面别的数据集也会一起吃到提升。

Phase 2：还不够，再上 2 + 3

如果第一轮做完还不够，再考虑：

1. 任务拆分：把一次性推 grain + business_meaning + PK，拆成多步生成
2. 换更强模型：比如切到 deepseek-reasoner 或 GPT-4o

我把这两个放到第二阶段，是因为它们更像“针对性加强”，不是第一时间就该动的通用解法。

Phase 3：最后兜底，再上 7 + 6

只有前面都不够时，我才会考虑更贵的方案：

1. 多 LLM 协作
   Generator -> Reviewer -> Final Rewrite
2. 多次采样投票
   同一个 prompt 跑 3 次，取多数

这两个方案确实有效，但 token 成本基本都会翻倍，甚至更多。
所以在我这里，它们更像“最后的暴力兜底”，不是第一反应。

如果要自审，我会这么拆

如果进入第二轮还不够，我最愿意加的是一个轻量 reviewer：

Generator: 根据 profile 推 grain + business_meaning
   ↓
Reviewer: 检查两件事
  - 这个 grain 和 PK 数量、行数、外键结构一致吗？
  - business_meaning 里有没有数据集特异业务名词？
   ↓
Final: 根据 reviewer 反馈重写一次

这套模式的好处在于，它不是简单地“多调用一次模型”，而是把一次性生成拆成了：

1. 先产出答案
2. 再用另一个视角挑错
3. 最后基于错误反馈修正

很多原本第一轮就会漏掉的矛盾，在 reviewer 视角下反而很容易被抓出来。

第一轮跑完后，别只看总准确率

我现在越来越不相信单一总分。

如果 grain 准确率低于 60%，我不会马上重写 prompt，而会先按错误类型拆：

1. dim_* 表到底错了多少
   看维表是不是总被认成事实表。
2. fact_* 表到底错了多少
   看事实表是不是总被认成维表。
3. 复合键表到底错了多少
   看桥表、SCD 表这类结构是不是完全没被识别出来。
4. 没有 fact_ / dim_ 前缀的表错了多少
   这才是真正检验系统通用性的地方。

因为不同错误，应该用不同武器：

• 全错集中在某类表：优先补输入信号
• 看起来像对了、其实结构不一致：补后处理校验
• 明显结构信号都没用上：上规则前置，把 LLM 退回到边界情况
• 各类都错一点：再考虑换模型

有三件事我现在会坚决不做

1. Fine-tune
   太慢，太贵，短周期里性价比极低。
2. 把规则写成数据集特异硬编码
   这直接违背了“数据集无关”的目标。
3. 把已知陷阱直接写进 prompt 喂答案
   这看起来像优化，实际上是在破坏自动构建的考核意义。

我现在最警惕的一类“优化”，就是那种短期分数会涨，但系统通用性会悄悄塌掉的做法。

最后一个提醒：产品手动测试仍然是最强武器

自动化测试很重要，但它永远不是全部。

哪怕 grain 从 0% 提升到 80%，也还是可能藏着一些自动化测不出来的问题：

1. fact_subscription 的 business_meaning 写成“订阅信息表”，看着像对，但 grain 其实仍然错了
2. KB 工具调用成功了，但返回结果根本没真正影响 system prompt，因为模板里有 bug
3. search_tables 返回了 5 张表，LLM 却选错了去做 JOIN

这些问题只有端到端手测才抓得出来。

所以我现在对“自动化”和“手动测试”的理解是：

• 自动化负责覆盖率、规则一致性、结构正确性
• 产品手测负责端到端可用性和真实任务完成度

它们不是替代关系，而是互补关系。

我的结论：调优先看层，再看招

如果让我把这次经验压缩成一句话，那就是：

Agent 调优最怕的，不是招数不够，而是还没分清问题在哪一层，就开始乱出招。

真正高 ROI 的路径，通常不是第一时间换更大的模型，而是先把：

1. 输入信号补够
2. 规则边界划清
3. 后处理兜底补上
4. 再把昂贵的多模型协作和多次采样，留到最后

这样调出来的系统，才更像一个可复用的工程能力，而不是一段只在当前数据集上偶然奏效的 prompt 魔法。

在这个造词速度远超代码编译速度的时代，作为一名还在大学宿舍里自己折腾 AI 的学生，我时常感到一种难以名状的疲惫。

每一天醒来，科技圈都在狂欢。昨天的头条还是 Prompt Engineering，今天就换成了 RAG，明天又飞出了 MCP、Agentic Workflow……那些西装革履的大佬们站在聚光灯下，用一个个崭新且高深莫测的名词，丈量着这个行业的边界。而我，坐在杂乱的书桌前，面对着频频报错的终端窗口，心里总有一只名叫 FOMO 的野兽在撕咬：我是不是又学慢了？我自己瞎写的这堆代码，是不是根本连门都没入？

直到几天前，我撞见了一个正在席卷工程圈的新词：Harness。

在那一刻，我突然听到了一声清脆的碎裂声。

那是我对“行业权威”的盲目焦虑，碎裂的声音。

那些拿不上台面的“野路子”

如果你也自己动手写过 Agent 项目，大概率会懂那种被大模型逼疯的深夜。

行业报告里的大模型，是无所不知的神明；但我终端里的大模型，却是一匹常常发癫的野马。它会莫名其妙地吐出少了一个括号的 JSON，把我的整个项目搞崩溃；它会像陷入梦魇一样在错误里死循环，眼睁睁地看着我卡里可怜的 API 余额如流水般燃烧。

为了拴住这匹野马，我不得不在它的外围垒起一圈又一圈的栅栏。

我写了一堆正则表达式，像个强迫症一样去校验它的每一次输出；我给函数加上了局部计数器，冷酷地规定“如果你重试三次还是改不对，就立刻给我停下”；我甚至写了一套看起来极其臃肿的 Fallback 逻辑。如果它实在干不了，那就强行返回一个默认值，哪怕显得有些呆板，至少别让程序死在用户面前。

我一直把这些代码藏得很深。我觉得它们不优雅，太笨拙，充满了“草台班子”的野生气息。它们就像是我为了掩盖大模型的愚蠢，而打满的补丁。

当我的补丁，成了世界的范式

但当我点开那篇关于“Harness Engineering”的前沿解析时，我愣住了。

文章里那些精美的架构图，那些被定义为“下一代 AI 核心基建”的系统约束、沙箱环境、错误兜底和状态流转控制……这不就是我在宿舍里，为了省那几块钱 Token 费，一行行手搓出来的“补丁”吗？

那一瞬间，我的心情极其微妙。

起初是一丝没来由的失落。我明明在黑夜里独自摸索出了这条路，但我只是个连社会都没进的大学生，我没有话语权去定义它。如今，大佬们给它穿上了名叫 Harness 的华丽外衣，很快，市面上就会充满开箱即用的框架。我曾经熬夜死磕的难关，即将变成别人只要输入一行 npm install 就能解决的问题。

但紧随其后的，是一种像海啸般涌来的技术自信。

我没有落后。

在这个喧嚣的时代，在没有任何文档指导、完全凭借个人兴趣和工程直觉的荒野求生中，我竟然精准地踩中了和全球顶尖架构师一模一样的演进脉络。我的直觉没有错，我遇到的痛点，就是这个时代真实的痛点。

撕下包装，只看代码

这次奇妙的巧合，像一场大雨，彻底洗刷了我的名词焦虑症。

现在，当我再去刷技术社区，看到那些新颖的范式和玄乎其玄的缩写时，我的内心不再有波澜。我学会了在心里把它们残忍地降维：

“别整那些虚的，你就告诉我，你是怎么处理那头野马的输入输出的？你那套华丽的框架，能不能拦住它发癫时的死循环？”

我知道，未来会有无数人直接调用成熟的 Harness 框架。他们坐在平稳的马车上，赞叹着 AI 的神奇。但这并不妨碍我骄傲，因为我曾亲手被那匹野马摔在泥地里，我曾亲手搓过一条粗糙但结实的缰绳。

当程序在未知的边缘报错时，调包的人只能看着说明书抓瞎，而我，听一听引擎卡壳的声音，就知道是哪里漏了油。

尾声：给所有独自前行的赶路人

AI 的风刮得太快，快到连造词的速度都赶不上填坑的速度。

如果你也像我一样，是个凭着一腔热血自己在泥潭里折腾的学生开发者，请千万不要被那些光鲜亮丽的词汇吓退，更不要因为自己写着看似“不标准”的防御代码而感到自卑。

不管它叫 Wrapper、Middleware，还是今天火爆的 Harness，本质上都是我们在驯服未知时，留在屏幕上的真实伤痕。不要等待别人来定义你的代码，你的每一次 Debug，每一个笨拙的兜底逻辑，都在构筑你最坚硬的技术底色。

大佬们在 PPT 上定义着世界的形状。而我们，只负责在宿舍的冷光里，把 Demo 跑通。

而且，我们跑得一点也不慢。

这篇文章想记录的，不只是“我接了一套代码沙箱”。

我更想写清楚另一件事：

当一条分析链路开始同时跨越 LLM、执行环境、宿主机渲染、SSE 推流和前端状态管理时，复杂 Bug 往往不死在某一行代码里，而是死在边界上。

这次在 OpsMind 里做沙箱方案落地，最后真正让我成长的，不是把 run_code 工具接上，而是把五个卡在不同边界层的关键问题一层层拆开、定位、修掉。

一、为什么原来的方案迟早会卡住

OpsMind 最早的数据分析链路，大致是这样：

用户提问
  -> LLM 判断图表类型
  -> LLM 猜列映射
  -> 预设渲染器执行
  -> LLM 根据结果写结论

这套方案在简单问题上不是不能用，但它有一个很难绕开的结构性限制：

LLM 负责猜，Python 负责跑，而“猜”和“跑”之间没有真实反馈回路。

模型在决定图表类型和列映射时，并不知道：

• 某一列是不是高基数，根本不适合饼图
• 某一列缺失率过高，直接计算比例会失真
• 某个日期字段根本不是标准时间格式
• 用户想看的指标，原始数据里其实不存在，需要先计算

也就是说，原来的系统始终在让模型“预猜执行现场”。

你可以不断加列信息、加规则、加 prompt，但只要模型看不到真实执行结果，它就只能越来越努力地猜，而不可能真正从运行结果里修正自己。

这也是我后来决定切到沙箱方案的根本原因：

复杂数据分析的问题，重点不是让模型更会猜，而是让模型有机会先算、再看、再改。

二、我最后怎么收敛这套沙箱架构

我后来没有让 LLM 在沙箱里直接写 Plotly，也没有把整个渲染流程完全交给它。

最后落下来的，是一套更克制的分层：

沙箱内

• 用 pandas / numpy 做自由计算
• 通过 declare_chart() 声明要画什么图
• 通过 declare_table() 声明要展示什么表
• 用 print() 输出洞察和说明

宿主机

• 读取 render_spec.json
• 调用现有 InteractiveChartGenerator
• 统一渲染成 Plotly HTML
• 返回给前端

这套架构我后来把它理解成：

LLM 负责数据计算，宿主机负责稳定渲染。

换句话说：

• 开放给 LLM 的，是“怎么算数据”
• 不开放给 LLM 的，是“怎么稳定落成图表产物”

这样做有两个直接好处。

第一，模型不需要熟悉复杂的前端图表 API，它只需要把真正有价值的分析计算做出来。
第二，最终产物仍然走宿主机这条可控渲染链，质量、样式和兼容性不会被沙箱代码拉散。

每次执行前，我会在用户代码前注入一段 preamble，预先放好：

• 数据读取入口
• declare_chart
• declare_table
• spec 写入逻辑
• 退出时落盘的 atexit

真正重要的不是 preamble 写了多长，而是它把沙箱代码和宿主机之间的契约固定住了。

三、五个关键 Bug 是怎么被拆开的

这次最有价值的部分，不是“终于能跑”，而是这五个问题让我越来越确定：复杂 Bug 的诊断，核心永远是先找对边界。

Bug 1：Permission denied: '.'

现象

沙箱日志里显示执行成功，图表数量也正常，但前端一个图都看不到。宿主机日志报：

PermissionError: [Errno 13] Permission denied: '.'

根因

问题出在沙箱产物收集阶段：

for filename in file_list:
    src_path = output_dir / filename
    if not src_path.exists():
        continue
    shutil.copy2(src_path, charts_path / filename)

当 filename 是空字符串时，output_dir / "" 实际会被解释成当前目录 .。
而 Path(".").exists() 会返回 True，于是系统继续往下执行，最后尝试把目录当成文件去复制。

修复

把判断从 exists() 改成 is_file()：

if not src_path.is_file():
    continue

教训

文件系统问题经常不是“路径存不存在”，而是“这个路径到底是不是你以为的类型”。
在文件复制、上传、收集这类链路里，exists() 往往是不够的，应该优先用 is_file() / is_dir() 这种带语义的判断。

Bug 2：create_table_groupby() got unexpected keyword argument 'title'

现象

沙箱执行已经成功，但宿主机渲染 spec 时抛出：

TypeError: create_table_groupby() got unexpected keyword argument 'title'

根因

Spec-Driven 的执行方式是把 spec 里的配置整体解包给渲染器：

fig = create_fn(df, **config)

但 create_table_groupby() 和部分 create_table_*() 方法的签名里并没有 title 参数。
这意味着：沙箱侧和宿主机侧虽然都“支持 table spec”，但它们理解的字段契约并不一致。

修复

给相关方法补上统一参数签名：

def create_table_groupby(self, df, group_col, value_cols, agg_funcs=None, title=None):
    ...

教训

这种问题表面上像一个 Python TypeError，本质上却是接口契约漂移。
只要系统是“上游生成 spec，下游消费 spec”，那所有字段都不再是某一侧的内部实现细节，而是跨模块契约。

Bug 3：前端重复提交，Agent 被连续启动三次

现象

同一个发送动作，后端日志里却出现了三段并行启动的 Agent 流程。前端看起来像“点了一次”，系统实际发了三次。

根因

原来的前端提交守卫读的是 React state：

if (streaming !== null && !streaming.error) return

但 React 18 的 batched updates 决定了：setState 不会在当前执行路径里立刻反映到闭包读取值上。
第一次提交后，streaming 在当前批次里仍然可能是旧值 null，于是后续极短时间内的再次触发仍会穿透守卫。

修复

改成读取同步更新的 ref：

if (streamingRef.current !== null && !streamingRef.current.error) return

并同步清理掉 handleSend 里对 streaming 的依赖。

教训

React state 适合驱动渲染，不适合做毫秒级竞态防护。
任何要求“当前调用立刻可见”的保护状态，都应该优先用 ref，而不是依赖 state 何时回流到组件闭包。

Bug 4：前端只显示最后一批图表

现象

多轮 run_code 明明产出了多批图表，但前端最后只剩最后一轮的结果。

根因

后端通过 SSE 连续发送多个 charts 事件，而前端 reducer 把它当成“全量替换”处理：

case 'charts':
  return { ...prev, charts: (msg.data.files as ChartItem[]) ?? prev.charts }

这意味着第二轮结果一到，第一轮结果就被整体覆盖掉了。

修复

把事件语义改成增量追加：

case 'charts': {
  const newCharts = (msg.data.files as ChartItem[]) ?? []
  return { ...prev, charts: [...prev.charts, ...newCharts] }
}

tables 同理。

教训

很多前后端问题看起来像“显示错了”，其实真正错的是事件语义根本没有讲清楚。
一个 SSE 事件到底代表“当前全量状态”还是“本轮新增产物”，必须在设计阶段就定死，不然只要链路进入多轮执行，问题迟早暴露。

Bug 5：LLM 始终没有机会调用 run_code

现象

明明已经接好了深度分析工具，但复杂请求还是稳定走老的 plan_analysis -> execute_analysis 路径，LLM 从头到尾没机会进入真正的代码执行。

根因

问题不在 prompt，也不在工具表本身，而在更早的路由器。

当请求没有命中知识库、数据库、连续对话这些关键词时，系统默认直接走：

return "direct_analysis"

而 direct_analysis 是一条固定链路，根本不会进入 ReAct 循环。
这意味着虽然 system prompt 写着“你可以调用 run_code”，但模型在执行层面从来没拿到过这个决策权。

修复

我最后没有继续修补规则分类器，而是把决策权显式还给用户：

• 快速模式：强制走 direct_analysis
• 深度模式：直接进入 ReAct，让 LLM 自主决定是否调用 run_code

也就是说，不再让系统偷偷替用户做“你这题适不适合深度执行”的隐式判断，而是把两种执行范式公开成一个可感知的开关。

教训

“规则路由优先” 和 “LLM 自主决策优先” 是两种不同的架构范式。
如果你真的希望模型自主决策，就不能在它前面先把路线封死。

四、这五个 Bug 其实共同暴露了什么

回头看，这五个问题分布在完全不同的层：

• 文件系统
• 渲染接口
• React 并发更新
• SSE 事件协议
• 执行路由

但它们本质上都在提醒同一件事：

复杂 Bug 很少是单点错误，它更常见的形态是：边界语义没有被定义清楚。

具体来说，就是这五类边界：

1. 文件边界

你以为自己拿到的是文件名，实际可能拿到的是空路径或目录引用。

2. 契约边界

你以为上下游都在说“同一份 spec”，实际上它们对字段支持并不一致。

3. 状态边界

你以为前端守卫已经生效，实际上当前调用看到的还是旧 state。

4. 事件边界

你以为后端在推“新的图表”，前端却把它解释成“新的全量结果”。

5. 决策边界

你以为模型拥有自主权，但真正的分流决定已经在它前面被规则路由做完了。

这也是为什么我现在越来越倾向于这样看复杂排障：

先别急着问是哪一行错了，先问这条链路的边界语义有没有被讲清楚。

五、最终落下来的执行形态

现在这套链路，我最后把它收成了两条明确路径：

快速模式

get_data_info
  -> plan_analysis
  -> execute_analysis

适合标准分析问题，成本低，结果稳定。

深度模式

ReAct loop
  -> get_data_info
  -> run_code
  -> plan_analysis / execute_analysis（必要时回退）

适合需要自定义计算、复杂派生指标或标准图表路径不够表达的问题。

真正关键的是，这两条路径现在不再互相假装自己是同一种东西。

快速模式就是规则更强、产物更稳的标准链路。
深度模式就是允许模型在真实执行结果里逐步试错、修正和扩展的探索链路。

只要路径边界清楚，很多原来看起来很“玄”的问题，都会突然变得可以诊断。

结语

这篇文章表面上是在写沙箱方案，实际上更像是在写一次复杂系统排障练习。

我后来越来越相信，复杂工程里的很多成长，并不来自“又多做了一个功能”，而来自你能不能把一个原本交织在一起的问题，真的拆开。

拆到最后，你会发现很多事情都没有那么玄：

• 图表不显示，也许不是图表的问题，而是文件语义问题
• 重复提交，也许不是按钮的问题，而是状态可见性问题
• LLM 不调用工具，也许不是 prompt 的问题，而是路由权根本没给它

对我来说，这类记录最值得留下的地方也在这里。

它不是只证明“修好了”，而是尽量把一次复杂 Bug 的形成路径、定位方法和修复原则，真正沉淀成下一次还能复用的工程经验。

这篇文章想记录的，不是某个功能终于做完了，而是两次很痛、但事后看都很值得的收缩。

一次是收缩产品范围。
一次是收缩架构幻想。

我后来才意识到，这两个决定其实都在做同一件事：

把注意力从“看起来完整”拉回“真正成立的核心路径”。

一、第一个决定：先砍范围，再谈完整

三个月前，我给 OpsMind 列过一张很完整的能力清单：

• 聊天工作台
• 知识库
• 数据库直连
• 报告导出
• Skill 扩展
• 落地页

当时我觉得这些能力缺一不可。

数据分析工具如果没有数据库直连，好像就不够专业；
没有报告导出，好像就留不住成果；
没有 Skill 扩展，好像未来也很难讲。

于是我真的开始把这些都往里做。

代码库里陆续出现了数据库连接、报告生成、技能注册这些模块，架构文档也越来越像一个“完整平台”。

但问题也很快出现了。

数据库连接不是一个按钮，而是一整套连接池、权限、密钥存储和方言差异。
报告导出不是一个导出接口，而是一整套渲染、分页、字体和格式系统。
Skill 扩展也不是多加几个 prompt，而是协议、生命周期和调用边界。

每一个“顺手补上”的配套能力，背后其实都是一个独立子系统。

结果是，三个月过去了，最应该打磨的核心体验反而还没稳：

上传文件 -> 提问 -> 看到一张可靠的图表

我后来才承认，自己当时并不是在做一个产品，而是在做一个“平台已经成熟”的幻觉。

于是我做了第一个决定：

把 db_connections、reports、skills、data-sources 从 v1.0 范围里拿掉，先归档，不继续投入。

那次提交一口气删掉了 3508 行代码。

删完之后我最明显的感受不是“损失”，而是轻。

代码库变轻了。
任务边界变轻了。
我的注意力也终于回到了真正该先做对的地方。

二、这次收缩让我重新理解了一件事

功能不是天然的资产，很多时候它首先是债务。

只要一段功能代码进入系统，它就会自动带来后续成本：

• 要测试
• 要维护
• 要解释
• 要兼容别的链路
• 要让用户真正理解为什么存在

如果用户还没走到需要它的阶段，这些成本就不会转化成价值，只会持续占用注意力。

这也是我后来越来越认同的一种区分：

“先做完整再上线”，更像工程师本能。
“先把最小成立路径做对，再看用户真正缺什么”，更像产品判断。

这两种思路都没错，但它们适合的阶段完全不同。

在还没有足够真实反馈之前，开发者最容易高估的，往往不是执行能力，而是自己对需求的判断力。

我当时一直在假设用户需要 MySQL 直连。
但如果连第一个真实高频场景都还没跑出来，我其实根本不知道，用户更在意的到底是数据库接入，还是先把 Excel 上传分析这条链路做顺。

三、第二个决定：推翻那套“预猜式”核心架构

如果说第一个决定是在砍功能范围，那第二个决定就是在砍我已经投入最多时间的实现路径。

最初为了让 AI 自动生成图表，我搭过一套自己以为很精细的流程：

LLM 决定图表类型
  -> LLM 推断列映射
  -> 预设渲染器执行

围绕这条链路，我写了大量配套代码：

• 图表类型判断
• 列名模糊匹配
• 时间轴修正
• 高基数列告警
• 重试机制
• 大量 prompt 调优

它在 demo 里不是不能用。

但真正让我开始警觉的是另一件事：

这套系统总是在修 bug，却从来没有“修好了”的感觉。

后来我才想明白，问题不在 prompt，也不在某一个判断分支，而在架构前提本身。

在这套方案里，LLM 负责先猜对：

• 哪张图更合适
• 哪一列该做 X 轴
• 哪一列该做 Y 轴

但执行环境里的很多关键信息，它其实在“猜”的时候根本看不到：

• 某一列唯一值太多，不适合饼图
• 某一列空值率很高，直接算比例会失真
• 某一列的数据类型脏得比列名看起来复杂得多

也就是说，我一直在让模型对一个它还没真正接触到的执行现场做预判。

这不是 prompt 的问题。
这是设计问题。

四、真正更合理的路径，是让模型先执行再修正

后来我去看主流 AI 分析产品和代码执行产品的做法，才慢慢意识到：

更稳的路径通常不是“先猜对再执行”，而是：

LLM 写代码
  -> 在真实环境里执行
  -> LLM 读取结果、报错和图表
  -> 再做下一轮修正

这两种思路最大的差别，不是实现细节，而是学习来源。

“预猜式”架构里，模型只能靠提示和历史经验去猜。
“代码执行式”架构里，模型可以直接从真实结果里学习。

一个 KeyError 会直接暴露真实列名。
一张空图会直接暴露数据分布。
一次报错会直接告诉模型，问题到底出在语法、映射还是数据本身。

我后来接受了第二个决定：

推翻那套围绕预设渲染器堆出来的核心路径，把核心体验重新收敛为：

上传文件 -> 对话分析 -> 代码执行 -> 返回图表与结论

现在 OpsMind 的代码执行沙箱用的是 E2B，LLM 直接写 Python，在真实执行结果上迭代。

少了一层“我替模型预先设计完整世界”的执念，系统反而更清楚了。

五、这件事真正提醒我的，不只是架构，而是提问方式

回头看，那三个月里我并不是没有努力。

我写了很多代码。
我做了很多调优。
我也一直在和 AI 助手协作。

问题在于，我问的问题一直不够对。

我当时更常问的是：

“怎么把我现在这套方案继续优化下去？”

但真正应该先问的问题，其实是：

“这个领域里，更成熟的做法本来是什么？”

这也是我后来对 AI 协作更警惕的一点。

AI 很擅长沿着当前方向帮你补得更完整：

• 扩展函数
• 增加兼容逻辑
• 增加重试
• 把局部实现做得更漂亮

但如果方向本身是错的，它也会非常高效地陪你把错误方向走得更深。

这不是 AI 的问题。

更准确地说，是因为我当时把 AI 放在了“帮我优化现有方案”的位置，却没有先把“现有方案是否值得继续”这个判断做掉。

六、这两个决定，最后都指向同一件事

一个决定是砍功能。
一个决定是改架构。

表面上看，它们发生在不同层面。

但如果把它们放在一起看，本质上其实是同一种纠偏：

1. 不要过早追求“看起来完整”

范围太满，会让产品失焦。
架构太满，会让系统失真。

2. 先确认核心路径成立，再扩外围系统

如果核心体验还不稳定，外围能力越多，系统越重。
如果执行路径前提就错了，局部优化越多，返工成本越高。

3. 有时候最贵的不是推翻，而是舍不得推翻

真正让我后面轻松很多的，不是前面三个月写过多少，而是终于愿意承认：

现在停下来重做，代价比继续在错误方向上推进更低。

七、如果让我重来一次

如果今天重新开始做 OpsMind，我会更早做三件事：

1. 先查清这个问题在行业里最常见、最成熟的解法是什么。
2. 在没有真实用户反馈之前，对“我觉得用户会需要”的功能保持克制。
3. 把判断标准从“功能多不多”换成“核心路径稳不稳”。

现在回头看，OpsMind 的 v1.0 范围其实清楚很多了：

• 聊天工作台
• 知识库
• 上传文件后的对话式分析
• 基于真实执行结果的图表生成

没有数据库直连。
没有报告导出。
也暂时没有技能市场。

但我反而觉得，它第一次更像一个产品了。

技术产品的成长，不只是不断往上加能力。

很多时候，它更依赖三种判断：

• 选择先做什么
• 选择暂时不做什么
• 选择在什么时候承认原来的方向不够对

这三件事，我在 OpsMind 上各学了一次。

学费是三个月。

现在看，付得不算亏。

这篇文章不是在聊某一次优化，而是在聊一个认知转变：从“疯狂堆功能”回到“把主流程做对”，以及我为什么认为这才是一个产品真正成熟的标志。

一、被 Chat 模型骗了很久

我用的是 DeepSeek，OpenAI 兼容接口，调用方式极其简单。

简单本身是一个陷阱。

当你只需要 client.chat.completions.create(model="deepseek-chat", messages=messages) 就能让系统“跑起来”，你很容易把这个模型当成一个万能胶：路由分类用它，Agent 规划用它，工具失败反思用它，多步结果综合也用它。

它确实都能做。每一步单独测试，效果不差。

但当你把这些步骤真正串成一个 ReAct 循环，问题就开始出现了：

• 第 3 轮迭代，模型开始重复调用相同的工具
• 第 4 轮，它明明有了结论，却还在向前推
• 第 5 轮，它在回答里开始出现上一轮失败工具的幻觉

这不是模型本身的问题。这是架构设计的问题：同一个 Chat 模型被同时用于规划、执行调度和结论生成，没有任何角色分离，没有上下文管理，只有越来越脏的 messages 数组。

二、真正的问题：上下文污染

在 OpsMind 的 Agent 实现里，每轮工具调用结束后，结果会原文追加进 messages：

messages.append({
    "role": "tool",
    "tool_call_id": tc.id,
    "content": tool_result
})

plan_analysis 会返回完整的 chart_plan 和 table_plan，包含所有图表的列映射配置。
execute_analysis 会返回洞察文本、图表列表、清洗报告。
get_data_info 会返回所有列的统计信息。

到第 3 轮迭代，messages 数组里已经有 3 条完整 JSON 工具结果，可能超过 8000 tokens。而模型在生成下一步决策时，需要从这堆原始结构化数据里自己筛选有用信息。

这不是 Chat 模型擅长的事情。

更糟糕的是，最初实现的“压缩”只在超过最大迭代次数之后才触发。这等于说：模型在整个有效执行期间，都在一个越来越脏的上下文里工作；只有在它已经失控之后，我们才开始清理。

这是一个典型的被动防御设计：等问题暴露再处理，而不是在问题出现之前主动管理。

三、去看别人怎么做的

有个机会让我去看了另一个成熟 Agent 系统（Claude Code）的源码。

它处理上下文污染的方式，不是一个补丁，而是一条有序的5 层压缩流水线，在每次 LLM 调用前依序执行：

1. applyToolResultBudget()    -> 单条 tool result 超 50KB -> 写磁盘，消息里只留 2KB 预览
2. snipCompactIfNeeded()      -> 历史片段裁剪
3. microcompactMessages()     -> 距上次消息 >1小时 -> 清除过期 tool result
4. applyCollapsesIfNeeded()   -> 上下文折叠
5. autocompact()              -> 整体超限时 -> 用轻量模型对旧消息做摘要，替换原始内容

关键不是每一层的具体实现，而是整体设计思路：压缩是主动的、逐轮的，不是被动的、超限才触发的。

它在每次把 messages 送给 LLM 之前，都会清理一遍。不是因为快爆了才清，而是因为干净的上下文是好决策的前提。

这是一种完全不同的认知：上下文管理不是兜底机制，而是 Agent 执行的基础设施。

四、我做了什么改动

理解了差距之后，我对 agent.py 做了三件事。

1. 角色分离：推理模型 + 快速模型

原来两次 LLM 调用全部用 deepseek-chat：

response = self._get_client().chat.completions.create(
    model="deepseek-chat", ...
)

final_response = self._get_client().chat.completions.create(
    model="deepseek-chat", ...
)

现在：

self._plan_model = os.getenv("AGENT_PLAN_MODEL", "deepseek-reasoner")
self._fast_model = os.getenv("AGENT_FAST_MODEL", "deepseek-chat")

response = self._get_client().chat.completions.create(
    model=self._plan_model, ...
)

final_response = self._get_client().chat.completions.create(
    model=self._fast_model, ...
)

规划和文案生成是两种不同的认知任务。
前者需要推理能力，后者需要表达效率。混用会让两端都不经济。

2. 每轮主动压缩：_prepare_messages_for_llm()

新增了一个方法，在每次 LLM 调用前执行：

@staticmethod
def _prepare_messages_for_llm(messages: List[Dict]) -> List[Dict]:
    COMPRESS_THRESHOLD = 1500
    KEEP_RECENT = 2

    tool_indices = [i for i, m in enumerate(messages) if m.get("role") == "tool"]
    compress_set = set(tool_indices[:-KEEP_RECENT]) if len(tool_indices) > KEEP_RECENT else set()

    result = []
    for i, msg in enumerate(messages):
        if i in compress_set and len(msg.get("content", "")) > COMPRESS_THRESHOLD:
            compressed = OpsMindAgent._compress_old_tool_result(msg["content"])
            result.append({**msg, "content": compressed})
        else:
            result.append(msg)
    return result

策略很直接：最近 2 条工具结果保留原文，更早且过长的结果压缩。

3. 精准压缩：_compress_old_tool_result()

压缩不是粗暴截断，而是字段提取：

@staticmethod
def _compress_old_tool_result(content: str) -> str:
    data = json.loads(content)

    keep_keys = {
        "success", "status", "error",
        "rows", "columns", "data_shape",
        "ok_charts", "skip_charts", "ok_tables",
        "charts_generated", "failed_charts", "table_types",
        "mode", "filename", "truncated",
    }
    summary = {k: v for k, v in data.items() if k in keep_keys}

    for text_key in ("insight_summary", "answer"):
        if text_key in data:
            val = str(data[text_key])
            summary[text_key] = val[:200] + "…" if len(val) > 200 else val

    summary["_compressed"] = True
    return json.dumps(summary, ensure_ascii=False)

保留决策关键字段，删除高冗余体积内容，兼顾可读性与 token 成本。

五、从“疯狂加功能”到“把主流程做对”

回头看这半年，OpsMind 一直在加能力：知识库、分析链路、图表推荐、宽表处理、DB 直连、报告生成、Skill 工具……

每加一层功能，演示效果都更好。
但我也在这个过程中欠下一笔债：主流程稳定性在下降，因为地基没有同步加固。

这次停下来还债，让我更确定一件事：

功能堆叠解决的是“能不能做”，架构优化解决的是“能不能一直做好”。

前者适合早期验证，后者决定长期可维护性。
一个工程系统真正成熟，往往不是功能最多，而是关键路径最稳。

六、任务分配与架构设计

这次改动背后还有一个更深的认知：模型分工就是任务分配，任务分配就是架构设计。

把所有工作都交给同一个 Chat 模型，和把所有工作都交给同一个角色，本质是同一个问题：职责失焦。

推理模型适合处理：

• 状态判断
• 路径规划
• 失败反思
• 多步协调

快速模型适合处理：

• 文本生成
• 格式化输出
• 简单分类
• 短回复

分开之后，每个模型都在自己擅长的位置工作；再配合逐轮压缩，ReAct 循环才真正从“凭运气”切到“可控执行”。

这次代码改动不算大，但背后的认知转弯很重要。

好的产品不是功能最多的产品。
好的 Agent 不是工具最多的 Agent。
好的架构不是最复杂的架构。

它们都是在对的时间做了对的事情。

这篇文章讲的是一次“把已经能用的东西推倒重做”的经历。
不是因为原来的坏了，而是因为原来的方式把一个产品想法做窄了。

一、原来是怎么做的

OpsMind 上线了一套叫 Skill 的快捷分析功能。

用户打开输入框左下角的「+」菜单，切换到“快捷分析”标签，就能看到四个预置技能：数据体检、数据速览、维度对比、异常排查。点一下，填几个参数，系统自动把描述渲染成一段结构化的分析 prompt 发给 Agent。

从产品角度来说，这个功能是有价值的：让不会写 prompt 的用户也能得到高质量的分析指令。

但实现上，它有一个根本性的定位问题：

Skill 只是用户端的 prompt 模板快捷键，Agent 完全不感知它的存在。

流程是这样的：

用户点击 Skill
  -> 前端调 /api/skills/render
  -> 返回渲染好的 prompt 字符串
  -> 以普通用户消息发给 Agent
  -> Agent 不知道这是 Skill，走普通 ReAct 流程

Agent 拿到的只是一段文字，和用户自己打字没有区别。

这意味着：Skill 永远不可能被 Agent 主动调用。你没办法说“分析完之后自动触发异常检测”，没办法让 Agent 根据数据特征主动选择合适的 Skill，没办法把 Skill 编排进复杂的多步分析链路。

Skill 的天花板，是“帮用户写好一句话”。

二、问题出在哪里

除了功能局限，原来的格式设计也有工程上的问题。

每个 Skill 的参数用自研格式定义：

"arguments": [
    {
        "name": "dimension",
        "label": "对比维度",
        "placeholder": "例如：班级、部门",
        "required": True,
    }
]

这个格式只服务于一件事：让前端 SkillPicker 渲染一个表单。

它既不能被 Agent 的 function calling 机制识别，也不能被任何外部框架（LangChain、AutoGen、MCP）复用，还需要在后端和前端分别维护对这套自研结构的解析逻辑。

可选参数的从句处理更是硬编码的：

period = args.get("period", "").strip()
args["period_clause"] = f"（{period}期间）" if period else ""

reference = args.get("reference", "").strip()
args["reference_clause"] = f"，参考基准为{reference}" if reference else ""

每加一个 Skill，就得在 render_prompt() 里加一段这样的逻辑。这不是架构，这是补丁。

三、标准格式是什么

OpenAI 在推出 function calling 时定义了一套参数格式，本质上是 JSON Schema：

{
  "type": "object",
  "properties": {
    "dimension": {
      "type": "string",
      "description": "对比维度，如：班级、部门、地区"
    }
  },
  "required": ["dimension"]
}

这套格式后来被整个行业采纳。Anthropic、Google、LangChain、AutoGen、MCP 都认识这个结构。一个用这种格式定义的工具，理论上可以接入任何兼容 function calling 的框架，不需要任何适配。

它还有一个官方扩展机制：x-* 前缀字段。这是 JSON Schema 标准允许的自定义扩展，专门用来携带非标准元数据。比如：

"dimension": {
  "type": "string",
  "description": "...",
  "x-label": "对比维度",
  "x-placeholder": "例如：班级、部门"
}

x-label 和 x-placeholder 是给前端 UI 读的，不影响 LLM 对参数的理解。标准的 LLM 会忽略这些扩展字段，前端可以读取它们来渲染表单。两套需求，一套定义，不冲突。

可选从句的配置也可以放进扩展字段：

"period": {
  "type": "string",
  "description": "时间周期过滤（可选）",
  "x-clause-key": "period_clause",
  "x-clause-template": "（{value}期间）"
}

render_prompt() 泛化读取这个配置，对每个带 x-clause-key 的参数自动处理从句。加新 Skill 不需要动 render_prompt() 的代码。

四、改了什么

1. Skill 定义格式升级

registry.py 里每个 Skill 的参数字段从 arguments 改成了标准 JSON Schema parameters。

# 之前
"arguments": [
    {"name": "dimension", "label": "对比维度", "placeholder": "...", "required": True},
    {"name": "period", "label": "时间周期（可选）", "placeholder": "...", "required": False},
]

# 之后
"parameters": {
    "type": "object",
    "properties": {
        "dimension": {
            "type": "string",
            "description": "对比维度（分组字段）",
            "x-label": "对比维度",
            "x-placeholder": "例如：班级、部门",
        },
        "period": {
            "type": "string",
            "description": "时间周期过滤（可选）",
            "x-label": "时间周期（可选）",
            "x-placeholder": "例如：2026年Q1",
            "x-clause-key": "period_clause",
            "x-clause-template": "（{value}期间）",
        },
    },
    "required": ["dimension", "metric"],
},

2. 新增 to_tool_schema()

def to_tool_schema(skill):
    return {
        "type": "function",
        "function": {
            "name": skill["name"],
            "description": skill["description"],
            "parameters": skill["parameters"],
        },
    }

这个函数把 Skill 定义直接转成 Agent 可以使用的 tool schema。一行代码，不需要手工维护两套格式。

3. Agent TOOLS 动态扩展

在 agent.py 的模块加载阶段，从 registry 读取所有 Skill 并追加到 TOOLS 列表：

from src.skills.registry import SKILLS as _SKILL_DEFS, to_tool_schema as _to_tool_schema

TOOLS.extend([_to_tool_schema(s) for s in _SKILL_DEFS])

Agent 启动后，TOOLS 从 6 个扩展到 10 个。LLM 在每轮推理时都能看到这 10 个工具，可以主动选择调用任何一个 Skill。

4. _handle_invoke_skill() 端到端执行

Agent 调用 Skill 工具时，会触发这个方法：

def _handle_invoke_skill(self, skill_name, args, file_path, ...):
    query = render_prompt(skill_name, args)
    plan = self._handle_plan_analysis(file_path, query, ...)
    return self._handle_execute_analysis(file_path, query, plan, ...)

一次工具调用，完成从 prompt 渲染到图表生成的全链路。

5. 前端 getSkillArgs() 派生 UI 参数

前端不再维护独立的 SkillArgDef[] 解析逻辑，改为从 JSON Schema 动态派生：

export function getSkillArgs(skill: SkillDef): SkillArgDef[] {
  const { properties, required } = skill.parameters
  return Object.entries(properties).map(([name, prop]) => ({
    name,
    label: prop['x-label'] ?? prop.description,
    placeholder: prop['x-placeholder'] ?? '',
    required: required.includes(name),
  }))
}

SkillPicker 的渲染逻辑、表单验证、自动触发全部不变，只是数据来源从 skill.arguments 换成了 getSkillArgs(skill)。

五、现在是什么效果

用户端：体验完全不变。SkillPicker 表单长得一样，填的参数一样，触发行为一样。

Agent 端：完全不同。现在 Agent 可以主动调用 Skill：

用户：“帮我看看哪个部门表现异常”
Agent 推理后调用: anomaly-detective(target="哪个部门表现异常")
-> 自动完成 plan_analysis + execute_analysis
-> 输出排序图 + 异常分析文字

用户不需要打开 SkillPicker，不需要点击，不需要填表单。Agent 自己判断该用哪个 Skill，自己填参数，自己跑完整个分析流程。

扩展性：加新 Skill 只需要在 registry.py 里加一个 dict。Agent 侧自动获得新工具，前端自动渲染新表单，render_prompt() 不需要改。

框架兼容性：现在的 Skill 格式可以直接被任何支持 function calling 的框架识别，不需要任何适配层。如果未来接入 LangChain、AutoGen 或 MCP，Skill 定义可以原样复用。

六、一个工程判断

这次改动有一个决策值得记录：什么时候该坚持自研格式，什么时候该跟标准走。

原来的 arguments 格式不是错的，它在当时的需求范围内完全够用。它更简单，更易读，定义起来更快。

但它是私有的。私有格式的代价是：每个消费这份数据的地方都要了解这套格式，任何框架对接都需要先写适配层，任何扩展都需要修改解析代码。

JSON Schema + x-* 扩展字段不是我发明的。它是一个有完整规范、有大量工具支持、有明确演进路径的标准。选择标准的代价是短期多写几行代码，收益是长期的可接入性和可组合性。

对于 Skill 这种面向 LLM 和外部框架的结构，跟标准走是对的。

本文记录的改动发生在 2026 年 4 月。核心文件：src/skills/registry.py、src/agent.py、frontend/lib/skills.ts、frontend/components/chat/SkillPicker.tsx。

这篇记录的不是“又修了几个点”，而是一次编排层审查之后，把系统里几处“靠运气撑住”的位置，逐一改成工程性保障的过程。

系统在大部分演示场景里一直能跑通，但只要把视角从“能跑”切到“复杂场景能稳定复现”，问题就会非常清楚：
很多失败不是功能缺失，而是结构设计在边界条件下不够稳。

这次我落地了四项修复。

一、修复 1：max_iterations=6 在数据库路径上是零容错

之前 ReAct Agent 的上限是 max_iterations = 6。
这个值在简单路径可用，但数据库分析的标准链路是：

get_db_schema -> execute_sql -> get_data_info -> plan_analysis -> execute_analysis

5 次工具调用刚好贴着上限走，任意一步重试都会触发迭代截止。
一旦触发上限，Agent 会进入压缩输出，导致最终回答只有结论，没有可靠图表与分析细节。

调整

1. 上限从 6 提到 10，给复杂路径和一次重试留空间。
2. 保留总超时预算（AGENT_TOTAL_TIMEOUT_SECONDS）作为真正的安全网。
3. 在 system prompt 中明确：execute_sql 成功后可直接进入 plan_analysis，避免不必要的 get_data_info 兜圈。

这一步做完后，数据库分析路径从“勉强刚好”变成“可容错可恢复”。

二、修复 2：取消 chart_plan 的 LLM 透传，改为 plan_id

原先流程是 plan_analysis 产出完整 chart_plan/table_plan，再由 LLM 原样传给 execute_analysis。
问题在于：这等于把复杂 JSON 的完整性寄托在 LLM 的序列化行为上。

常见失真包括：

• 字段被精简（例如丢掉 status）
• 键名被改写（x_col 变成 x_axis）
• 嵌套 JSON 二次转义

这些都不是语义层 bug，而是“传输层不可靠”。

调整

plan_analysis 只返回一个短 plan_id，完整 plan 存在服务端内存：

plan_id = uuid.uuid4().hex[:8]
self._session_plans[plan_id] = {
    "chart_plan": result.get("chart_plan", {}),
    "table_plan": result.get("table_plan", {}),
    "file_path": file_path,
}

execute_analysis 只收 plan_id，在服务端取回原始 plan：

stored = self._session_plans.get(plan_id)
chart_plan = stored["chart_plan"]
table_plan = stored["table_plan"]

这一步的本质是：把“跨步骤数据完整性”从模型层搬回服务端强约束层。

三、修复 3：新增 refine_chart，让图表调整从“全量重跑”改为“局部修订”

过去用户说“把第一张图改成折线图”，系统会重新 plan_analysis + execute_analysis 全链路重跑。
这对单图修改来说成本太高，也容易引入无关波动。

调整

新增工具：

refine_chart(plan_id, chart_type, new_chart_type?, new_column_mapping?)

能力边界：

• 局部改图类型
• 局部改列映射
• 原地更新同一个 plan_id
• 再调用 execute_analysis 增量生效

收益很直接：
“改一张图”不再触发一次完整重规划，延迟和 token 成本都显著下降。

四、修复 4：SSE 增加心跳帧，解决长分析链路下的空闲断连

分析链路超过 30s 时，如果 SSE 长时间无帧，代理层或浏览器会按空闲连接处理并主动断开。
本地开发不明显，上线后在反向代理链路中会稳定复现。

调整

在事件生成器里使用“超时等待 + 注释心跳帧”：

_HEARTBEAT_INTERVAL = 15.0
while True:
    try:
        item = await asyncio.wait_for(queue.get(), timeout=_HEARTBEAT_INTERVAL)
    except asyncio.TimeoutError:
        yield ": heartbeat\n\n"
        continue

: 开头是 SSE 注释帧，不会触发前端业务消息处理，但能持续保活连接。

五、改动文件一览

六、这四项修复背后的共同方向

它们表面上是四个点，底层其实是同一件事：

把“靠模型自觉、靠路径刚好、靠网络运气”的环节，改成“可验证、可恢复、可预期”的工程路径。

对 Agent 产品来说，最难的往往不是“让它做出结果”，而是“在真实复杂场景下持续做对结果”。
这次四项修复，本质上就是朝这个方向补齐地基。

最近重新读了一遍 Patrick Lewis 等人的 RAG 论文。
如果把传统大模型比作一个“靠脑内记忆答题”的学生，那 RAG 最有意思的设计，就是给这个学生办了一张“图书馆借阅证”：它可以在生成答案时，先去查资料，再组织表达。

这篇笔记想记下我最有感触的六点。

1. 记忆被拆成了两部分：参数负责能力，外部库负责事实

论文把知识来源拆成两类：

• 参数化记忆（Parametric Memory）：模型参数中沉淀的模式与能力
• 非参数化记忆（Non-parametric Memory）：外部文档库（论文里是 Wikipedia 索引）

这件事改变了我对“模型变强”的直觉。
以前我会把“更强”理解成“参数更大”；现在我更倾向于“能力与事实分层管理”。

一个参数规模更小的模型，如果检索机制足够好，也能在知识密集任务上打出很高上限。
这也是我理解里 RAG 的核心：把“推理能力”和“事实更新”从同一套参数里拆开。

2. DPR 的优雅在于：把“找资料”变成了几何问题

RAG 里我最喜欢的一段是 DPR 检索器。
问题 x 和文档 z 都被编码到同一向量空间，再通过相似度做 top-K 检索。

形式上可以写成：

top-K argmax_z ( q(x)^T d(z) )

这一步非常关键，因为它让检索不再依赖“字面重合”。
同义改写、表达差异、问法变化，都可以通过语义邻近来弥补。

当然，传统 BM25 在实体词非常明确时依然有价值。
所以在工程上，我更愿意把它理解为“语义检索主导，关键词检索兜底”的组合，而不是非此即彼。

3. RAG-Sequence 与 RAG-Token：稳定性和灵活性的取舍

论文里两种生成方式非常有代表性：

• RAG-Sequence：整段生成过程使用同一批检索文档
• RAG-Token：每个 token 允许动态参考不同文档

前者更稳，后者更灵活。
我自己的体会是：结构化问答、强一致性场景更适合 Sequence；开放生成、长文本探索更适合 Token 思路。

这其实不是“谁更先进”的问题，而是系统目标不同：你优先要“上下文一致”，还是优先要“信息覆盖”。

4. 最打动我的细节：没有直接证据时，RAG 仍可能答对

论文里提到一个有意思的现象：即使检索文档里没有直接答案，RAG 也有一部分样本可以回答正确（文中给出的案例约为 11.8%）。
这意味着系统内部不是“照抄检索结果”，而是“检索信号 + 参数记忆”在共同工作。

我把它理解成一种协同：

• 外部文档提供线索和锚点
• 参数记忆补上推理与表达

这也解释了为什么高质量检索会显著提升答案可用性，但“只堆文档”并不能自动得到高质量推理。

5. 为什么今天很多 RAG 看起来“不微调也能用”

这也是我最近反复在想的问题。
和论文发表时期相比，现在主流大模型的指令遵循能力强了很多，所以“检索结果 + 好提示词”就能得到可用答案。

但这不代表联合微调思想失效。
在垂直领域（术语密集、格式严格、流程固定）里，微调仍然是把特定行为写进模型“习惯”的有效手段；RAG 则负责把外部知识保持新鲜与可追溯。

我的结论是：两者不是替代关系，而是不同层面的增强。

6. 最后的收获：RAG 让模型学会了“有依据地不知道”

读完这篇论文，我最强的感受不是某个指标，而是方法论层面的变化：
系统不再追求“把所有事实都塞进参数”，而是承认知识会变化，并把“查证能力”纳入生成流程。

这种可追溯性（Provenance）很重要。
它不仅减少幻觉，也让我们在使用模型时，拥有了更多可验证、可审计、可迭代的控制点。

参考论文：
Patrick Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
ArXiv: 2005.11401

这次更新不是“修几个 bug”或者“补几个页面”。

它更像一次真正意义上的产品级推进：

从一份 PRD 出发，把登录、多用户、数据库连接、知识库管理、信息架构、报告导出，一路做到代码、接口、前端页面、测试和回归验证。

更重要的是，这次工作不是靠单线程硬扛，而是通过一支 subagent 团队并行推进，再由主线程统一集成、收敛和验收。

为什么这次可以叫“超级巨大更新”

如果只看表面，OpsMind 以前已经能聊天、能分析文件、能查知识库，也能接数据库。

但从产品角度看，它还停留在一种很典型的“能力原型阶段”：

• 有能力，但没有真正的登录和用户隔离
• 有聊天页，但没有完整的信息架构
• 有知识库，但管理能力还不够产品化
• 有数据库能力，但还不够像正式数据源模块
• 有分析结果，但没有真正可交付的报告导出

所以这次更新做的，不是把一个 Demo 修得更顺。

而是把一个原型产品往“更接近正式版本的状态”拉了一步。

一句话总结就是：

这次不是能力补丁，而是产品形态升级。

这次到底更新了什么

这轮改动最重要的，不是某一个功能点，而是几个基础模块一起补齐了。

1. 登录与多用户系统终于完整了

这次补上的不只是一个登录页，而是真正的身份基础设施：

• 邮箱 + 密码登录
• JWT 鉴权
• 当前用户信息接口
• 修改密码
• 多用户 session 隔离
• 默认管理员初始化

这意味着很多以前只是“单机假象”的能力，终于有了可靠的用户边界。

用户 A 看不到用户 B 的会话，未登录也不能直接闯进工作区。

而数据库连接、知识库、设置页、报告导出这些功能，终于开始拥有真正成立的前提。

2. 单页聊天工作台被拉成了多页面产品结构

这次前端不再只是一个 /chat 单页，而是拆成了更清晰的产品信息架构：

• /login
• /chat
• /data-sources
• /knowledge
• /settings

侧边栏也补成了正式一级导航：

• 聊天工作台
• 数据源
• 知识库
• 系统设置

这一步的意义很直接：

文件上传和数据库连接不再挤在聊天页里，知识库也不再只是一个临时面板。

整个产品终于更像一个工作台，而不是一页里塞满能力入口的实验区。

3. 数据源模块开始像一个正式产品功能

数据库连接这次做的，不只是“能连上”。

它被补成了一个更完整的数据源体验：

• MySQL / SQLite 两种类型支持
• 测试连接
• 保存连接
• 删除连接
• 大结果导出卡片展示
• 导出结果继续进入分析流程

同时，数据库查询结果卡片也补齐了更清晰的动作提示：

• 预览前 10 行
• 继续说“分析这份数据”
• 继续说“画图”

也就是说，数据库不再只是一个孤立接口，而是开始真正接入整个分析工作流。

4. 企业知识库从“上传问答”升级成了“可管理模块”

这次知识库模块的增强非常明显。

它不再只是上传文档然后做 RAG，而是补上了真正接近产品化的管理能力：

• 文档列表
• 分类
• 标签
• 状态
• 分块预览
• 元数据编辑
• 删除文档
• 系统内置知识库 / 企业私有知识库区分

更关键的是，检索优先级也更像企业真实场景：

• 企业私有知识优先
• 系统内置知识作为补充

这一步很重要。

因为企业智能助手最怕的事情之一，就是拿“平台通用知识”覆盖“企业真实规则”。

5. 报告导出能力正式落地

这次还补上了报告导出链路：

• 会话报告预览
• Markdown 导出
• PDF 导出
• 图表与表格内容进入导出结构
• 数据来源写入报告

这意味着 OpsMind 的结果不再只停留在聊天窗口里，而开始拥有“可以交付”的形态。

这不只是方便保存。

它让产品从“分析助手”更进一步靠近了“分析交付工具”。

6. 测试和兼容性也一起补了

这轮更新不是只改功能，不做验收。

我把接口、主流程、前端构建和历史兼容一起做了回归：

• API 测试补齐到鉴权新契约
• 会话与主流程相关测试修通
• 知识库相关测试通过
• 前端构建通过
• 历史测试夹具补齐
• 旧参数和旧路径做了必要兼容

这点很关键。

因为 PRD 级任务最怕的，不是代码量大，而是“看起来功能很多，结果一回归全炸”。

为什么这次适合用 subagent 团队来做

这类任务最难的地方，从来不是某个函数怎么写。

而是：

• PRD 很长
• 牵涉前后端
• 同时涉及数据模型、接口、页面和测试
• 还必须尽量不打断已有功能

如果用单线程方式推进，很容易出现三种问题：

1. 看完 PRD 之后还没开工，时间已经先耗掉一大截
2. 做完后端再做前端，联调时发现前面设计得返工
3. 某个模块写得很深，但整体集成和回归来不及做

这次 subagent 团队的价值，就在这里非常明显地体现出来了。

大致的并行方式是这样的：

• 一条线专门读 PRD，提炼阶段需求和依赖
• 一条线盘点后端现状和改造点
• 一条线盘点前端现状和页面拆分路径
• 后面再拆成鉴权、多页面前端、报告 / 知识库增强几个并行 worker
• 主线程负责共享模型、主流程、测试和最终集成

这类分工的好处不是“炫技式并行”。

而是：

让复杂任务可以同时向多个方向推进，但最后仍然收敛回一个可交付结果。

这比单纯追求写代码速度，更接近真正的软件工程协作。

这次最像“PRD 级开发任务”的地方是什么

我觉得不是功能多，而是下面三件事同时成立。

1. 从需求文档直接推到交付结果

这次不是“先写点功能，再看像不像 PRD”。

而是从 PRD 阶段目标往下推：

• 数据模型要不要扩
• 路由怎么接
• 前端页面怎么拆
• 用户体验怎么闭环
• 哪些功能要兼容
• 哪些测试必须补

这就是典型的 PRD 驱动开发，而不是零散功能开发。

2. 不是只做 happy path

如果只是做一个 happy path，很多东西很容易“看起来可用”。

但 PRD 级任务真正难的是这些问题：

• 登录过期怎么办
• 用户权限怎么隔离
• 大结果怎么处理
• 缺配置时怎么兜底
• 老测试怎么迁移
• 旧路径怎么兼容

这些东西决定的不是 Demo 能不能跑，而是系统能不能稳。

3. 集成、回归和说明也属于交付的一部分

很多任务做到最后，只交代码，不交解释。

但真正的产品推进不是这样。

这次我很看重的一点就是：

• 代码改了什么
• 路由变了什么
• 页面入口在哪
• 怎么登录
• 怎么体验
• 测试覆盖到什么程度

这些都应该一起说清楚。

因为“完成任务”不等于“别人已经能接手和使用”。

现在可以怎么体验这次更新

如果你想最快看出这次更新的价值，我会推荐下面这个顺序。

路线 A：先看产品结构

先登录，再切换这几个页面：

• /chat
• /data-sources
• /knowledge
• /settings

最值得看的，是工作区是否已经更像正式的信息架构，以及侧边栏导航是否自然。

路线 B：再看数据源链路

去 /data-sources：

• 上传一个 CSV / Excel
• 配一个 SQLite 或 MySQL 连接
• 测试连接
• 回到聊天页发起分析

重点观察文件数据和数据库数据，是否都能顺畅进入分析链路。

路线 C：再看知识库管理

去 /knowledge：

• 上传几份制度文档
• 设分类和标签
• 打开文档详情看 chunk
• 回到聊天页问规则类问题

这里最值得看的，是知识库是否已经从“上传入口”变成了“可管理模块”。

路线 D：最后看报告导出

在 /chat 中完成一轮分析后：

• 点击顶部导出按钮
• 导出 Markdown
• 再尝试导出 PDF

重点看报告是否已经包含摘要、正文、图表引用、表格和数据来源。

如果没有在 .env 里显式配置管理员账号，当前开发默认管理员是：

• 邮箱：admin@opsmind.local
• 密码：admin123456

还有什么没有做

这次我按任务要求明确没有做部署阶段，也就是：

• Docker
• docker-compose
• nginx 生产编排
• 整套部署文档

也就是说，这次交付的重点是：

把产品功能和工程主链路做完整，而不是先做部署包装。

我其实觉得这个顺序是对的。

因为部署标准化应该建立在功能稳定之后，而不是反过来。

我对这次更新的一个核心判断

如果只看代码量，这次更新当然很大。

但我觉得真正值得记录的，不是“改了多少文件”，而是：

subagent 已经不只是适合做局部功能或修 bug，它开始适合解决真正的 PRD 级任务。

前提是三件事：

• 任务边界清楚
• 并行分工合理
• 主线程愿意负责最终集成和验收

一旦这三件事成立，subagent 的价值就不再只是“帮忙写代码”。

它会变成另一种更有意思的东西：

• 帮你并行读文档
• 帮你并行摸现状
• 帮你分模块推进
• 最后再一起收敛成交付结果

这次更新让我更确信一件事：

未来最有价值的，不是一个超强的单体 agent，而是一支能被组织起来、能被约束边界、能被统一验收的 agent 团队。

而这次 OpsMind 的这轮更新，就是一次很具体的证明。

这篇文章想复盘的，不只是一次预处理能力升级。

我更想讨论一个更底层的问题：

为什么很多团队一边说“让 AI 提效”，一边又被 AI 拖慢节奏？

我现在的答案很直接：

不是 AI 不够强，而是任务边界和编排逻辑先天就没讲清楚。

这次升级真正解决的，不是“多识别几个脏表”

做数据分析助手时，预处理很容易被理解成一个局部功能。

比如：

• 识别宽表
• 删除合计行
• 处理特殊缺失值
• 规范列名里的单位

表面看，这些都像小事。

但一旦系统进入 Agent 链路，问题就不再只是“识别到了没有”，而会立刻升级成另一组系统问题：

• 这件事由谁判断
• 判断完什么时候生效
• 是自动应用还是先让用户确认
• 用户确认前，后续分析到底能不能继续
• 下一轮分析是否要沿用这次的处理结果

也就是说，预处理一旦进入 Agent 模式，它就不再只是一个数据清洗函数。

它变成了一个有状态的分支节点。

而这次升级，本质上是在把这个分支节点从“能跑”改造成“可解释、可确认、可复用、可回滚”。

这条链路其实经历了三次明显的改版

如果把这次演化过程拆开看，大致可以分成三步。

版本一：规则检测器 + 本地 fix

最早的思路其实很工程化：

• 写一组规则检测器
• 识别宽表、表头偏移、合计行、重复列名等问题
• 命中后调用确定性 fix 函数

这套思路的优点很明显：

• 可控
• 可测
• 低幻觉
• 出错时容易定位

但它的上限也很明显。

规则检测器擅长识别“格式像什么”，却不擅长判断“在当前任务下该不该处理”。

比如：

• 宽表一定要转长表吗
• 列名里的单位应该自动提取，还是只做提示
• 表头偏移是元数据行，还是业务说明的一部分

这时候，纯规则系统开始显得僵硬。

版本二：规则检测 + LLM 评估 + 试做复核

于是第二版开始让 LLM 参与决策。

流程变成了：

• 先用规则检测器找候选问题
• 再让 LLM 评估每个问题是 auto / ask / inform / skip
• 对部分问题先试做一版
• 再用一次 LLM 复核试做结果是否可靠

这一版已经比最早期强很多。

它开始具备一种真正有产品意义的能力：

把结构问题翻译成产品动作。

也就是：

• 哪些问题系统可以直接处理
• 哪些问题必须打断用户确认
• 哪些问题只需要提示，不要自动动数据

但这版仍然有两个核心缺点。

第一，链路太绕。

识别一次、评估一次、试做一次、复核一次，成本很高。

第二，状态语义不够干净。

最危险的问题是：

待确认 fix 和已确认 fix 的边界不够硬。

如果 pending 也会被后续分析偷偷吃进去，那用户眼里看到的是“待确认”，系统内部却已经把它当成“已生效”。

这种系统最容易出现“看似可交互，实则状态不可信”的问题。

版本三：单次 LLM 诊断 + JSON Schema 约束 + 确定性执行

这次升级最终落地的，是第三版思路：

• 不再把 LLM 当成自由发挥的清洗器
• 让它只负责识别问题、生成受约束参数、决定处理级别
• 所有输出都必须落在 issue_type + params + decision + confidence 这个结构里
• 真正动数据的，仍然是确定性的 fix 函数

也就是说：

LLM 负责判断，代码负责执行。

这看上去像一句很朴素的话。

但它其实是整次升级里最关键的边界。

因为只有这样，系统才能同时得到两种好处：

• 保留 LLM 的语义判断能力
• 保留工程系统的确定性和可验证性

这次升级真正落下来的技术元素是什么

如果只讲“要把逻辑理清”，这篇文章会显得很空。

真正让这次升级落地的，其实是一组非常具体的技术元素。

我最后把整条链路收敛成了下面这个结构：

User Query
   ↓
Preprocessing Branch
   ├─ build_df_context(df)
   ├─ llm_diagnose_and_evaluate()
   ├─ schema / 引用 / dry-run 校验
   ├─ 状态分流：auto / ask / inform
   └─ 写入 session state
            ↓
Confirmed Fixes Only
            ↓
Analysis Artifact
   ├─ preprocess_fingerprint
   ├─ plan_analysis()
   └─ execute_analysis()

这套结构里，重要的不是“多了一层”。

而是每一层都只做一件事。

1. 用 Schema 把 LLM 从“自由文本生成器”收敛成“受约束诊断器”

这次预处理升级最核心的技术动作，不是换了哪个 prompt。

而是把模型输出强行压进一套稳定契约：

• issue_type
• decision
• params
• confidence
• user_message

再加上 JSON Schema 和列名、行号、dry-run 校验。

这样做的意义是：

模型可以判断，但不能随意发明系统里不存在的动作。

它不再有机会输出一个后端根本接不住的“聪明答案”。

2. 用确定性 fixer 保住系统的可测试性

我没有让 LLM 直接“修改 DataFrame”。

真正执行数据变换的，仍然是硬编码的 fix 函数。

比如：

• 删合计行
• 宽表转长表
• 特殊缺失值归一
• 转置恢复

这样做的好处非常工程化：

• 可单测
• 可回放
• 可 debug
• 可解释

这也是为什么我一直强调：

LLM 负责决定“要不要做”，代码负责决定“怎么做”。

3. 用显式状态机替代隐式约定

这次升级里我最重视的，其实不是识别率。

而是状态机。

如果没有显式状态，系统就会开始依赖默认约定。

而默认约定往往是最危险的东西。

现在这条链路里，至少有三类状态是清楚的：

• confirmed fixes
• pending confirmations
• suggested fixes

这三类状态分别对应不同的产品动作和不同的数据流权限。

一旦状态机被写进代码，很多以前看起来“容易说不清”的事，都会自动变清楚。

4. 用 preprocess_fingerprint 保证 plan 和 execute 看的是同一版数据

这是一个非常典型的架构细节。

如果 plan_analysis() 和 execute_analysis() 各自重新读文件、重新做预处理，那么系统理论上随时可能出现：

• 规划阶段基于版本 A
• 执行阶段基于版本 B

这种问题不会天天发生。

但一旦发生，用户看到的就是最难排查的“偶发错乱”。

所以我补了共享 artifact 解析路径，并把关键输入折叠成 preprocess_fingerprint。

这件事的价值不是性能优化，而是：

把“同一份数据版本”从默认假设变成显式约束。

5. 用兼容归一化把系统从“切换新协议”改成“平滑迁移”

预处理 issue 契约升级以后，一个很现实的问题是：

• 流式 SSE 已经开始发新字段
• 历史消息里还存着旧字段

如果不做兼容层，用户刷新一次页面，系统就会像换了一个脑子。

所以这次还有一个不太显眼、但非常关键的技术动作：

把历史 payload 统一归一化成同一套 issue 结构。

很多系统并不是死在新功能做不出来。

而是死在“新旧世界并存时没有过渡层”。

6. 用“真脏表工厂”而不是纯 mock 测试预处理

这次我后来专门补了一层真实场景回归。

它不是只 mock 一些 issue payload。

而是会真实生成：

• 宽表 + 合计行的 CSV
• 列名带单位 + 特殊缺失值的 CSV
• 表头偏移的 XLSX
• 转置后的 CSV

然后走真实读盘、真实 prepare()、真实 fix 重放。

这层测试的意义很大。

因为预处理最怕的一件事，就是：

你以为自己在测真实表格，其实只是在测一组自己定义的数据结构。

真正难的不是识别问题，而是把状态归属讲清楚

如果只看功能表，预处理升级像是在做“识别能力增强”。

但真正决定系统质量的，反而不是识别本身，而是状态怎么流动。

这次我最后理顺的，是下面这几个边界。

如果再往上抽一层，这其实就是几条很典型的架构原则：

• 契约先于实现
• 显式状态优于隐式约定
• 单一职责优于混合责任
• confirmed data path 必须和 proposed data path 分离

这些原则听起来很抽象。

但一旦落到预处理链里，它们就会变成非常具体的系统规则。

1. auto、ask、inform 分别属于什么状态

这三个词如果只存在于 prompt 里，系统很快就会乱。

必须把它们落成真正的状态语义：

• auto：直接进入 confirmed fixes
• ask：进入 pending confirmations，阻塞后续分析
• inform：进入 suggested fixes，不阻塞，只有用户点 apply 才进入 confirmed

这件事一旦讲清楚，前后端动作也自然就清楚了：

• confirm
• revert
• apply

如果这层不先定义，AI 很容易写出“能交互但逻辑互相打架”的实现。

2. 待确认 fix 不能参与正式分析

这是这次升级里最需要强行纠偏的一点。

在旧链路里，pending 有机会被一起重放到数据引擎里。

这意味着：

• UI 说“请确认”
• 后端却已经拿它去做正式分析

这是很典型的“提示词语义”和“系统语义”不一致。

所以我把规则改得非常硬：

只有 confirmed fixes 才能进入分析链。

待确认 fix 只存在于卡片和 session state 里，不得偷偷生效。

3. 历史消息和流式消息必须共享同一套 issue 契约

这一点也很容易被忽略。

如果实时 SSE 发的是一套字段：

• issue_type
• user_message
• params
• confidence

但历史消息里存的还是旧字段：

• type
• summary
• fix_params
• llm_confidence

那用户刷新一次页面，就会得到两套世界观。

所以这次我做了两件事：

• 前端切到新字段契约
• 后端在读历史消息时做兼容归一化

这不是“兼容旧数据”这么简单。

这是在保证：

系统对同一个状态的解释，在时间维度上保持一致。

4. 同一份文件不能在 plan 和 execute 阶段重复做两次预处理

这也是典型的 Agent 编排问题。

如果 plan_analysis() 和 execute_analysis() 各自重新加载文件、重新预处理一次，就会带来两个风险：

• 重复计算
• 计划阶段和执行阶段看到的不是同一份数据版本

所以这次我在数据引擎里补了共享 artifact 解析路径。

它会把：

• 原始文件
• 当前 preprocess config
• 当前 query

共同折叠成一个可复用的预处理产物。

再配合 preprocess_fingerprint，就能让 plan 和 execute 至少知道自己看到的是不是同一版数据。

这类设计不是 AI 自己会“顺手想到”的。

它必须先由人把系统不变量讲清楚。

为什么 Agent 编排还得人来做

这次升级之后，我反而更确定了一件事：

Agent 编排最难的部分，不是写代码，而是定义责任。

AI 很擅长做这些事：

• 按明确枚举补 schema
• 按确定接口补 API
• 写 fix 函数
• 改前端 action 流
• 扩测试覆盖

但 AI 不擅长替你做这些决定：

• 哪些状态应该长期保存
• 哪些状态只是一次性建议
• 哪些动作会阻塞后续分析
• 哪些结果必须显式失败
• 哪些中间态可以缓存，哪些绝不能缓存

换句话说：

AI 擅长实现边界，人的工作是先画出边界。

如果边界没画清楚，就会出现一种很常见的低效：

• 你让 AI “优化预处理”
• 它帮你补了一堆代码
• 但 pending 和 confirmed 继续混着用
• 前端 action 和后端语义继续错位
• 测试越写越多，逻辑反而越乱

这时候不是 AI 没有产出。

而是它产出的是一堆建立在错误前提上的高质量代码。

高质量地做错事，往往比低质量地做错事更危险。

为什么含糊不清的任务会拖慢 AI，而不是加速 AI

这是我这次最大的感受。

很多人以为，给 AI 一个宽泛任务，能换来“更大的自主性”。

比如：

• “把预处理做智能一点”
• “把 Agent 编排优化一下”
• “让流程更自然”

这类话听起来像方向，实际上对工程实现几乎没有约束力。

当任务含糊时，AI 往往会发生三件事：

第一，它会自动脑补需求。

第二，它会把局部最优当成系统最优。

第三，它会在没有明确状态机的前提下，把不同语义揉在一起。

最后你得到的，不是“高效自动化”。

而是：

• 一轮又一轮返工
• 一层又一层兼容补丁
• 越来越重的上下文负担

所以真正高效的做法，从来不是一句“你自己发挥”。

而是先把这些问题想清楚：

1. 系统里有哪些状态
2. 每个状态由谁产生
3. 每个状态何时生效
4. 哪些状态允许跨轮复用
5. 哪些状态绝对不能默默流入后续分析

当这五个问题清楚以后，AI 的效率会突然变高。

因为它终于不需要替你猜系统设计了。

它只需要帮你实现系统设计。

这也是我现在越来越认同的一句话：

Agent 编排不是提示词工程，首先是系统设计。

提示词只是其中一层。

真正的骨架，是：

• 状态机
• 协议
• 缓存
• 幂等
• 回归样本

这些东西不先定下来，AI 越强，返工速度反而越快。

这次升级后，我对“AI 提效”的理解反而更保守了

以前我也会更乐观地想：

只要模型够强、上下文够长、工具够多，系统自然会越来越聪明。

但这次做完以后，我的结论反而更保守，也更实用：

AI 不是替代架构思考，而是放大架构思考。

如果你的逻辑是清楚的，AI 会把效率放大很多。

如果你的逻辑是含糊的，AI 也会把这种含糊放大很多。

所以真正的提效顺序应该是：

1. 人先把状态、边界、责任讲清楚
2. 把枚举、schema、动作协议和测试目标定清楚
3. 再把这些明确任务交给 AI 并行推进

这样 AI 才是加速器。

否则，它更像一个会高速放大歧义的执行器。

写给所有正在用 AI 做工程的人

如果你想让 AI 真正帮你提效，我现在最推荐的不是“学更多 prompt 技巧”。

而是先学会做三件事。

1. 把问题写成状态机，而不是写成愿望

不要说“让体验更顺”。

要说：

• ask 阻塞
• inform 不阻塞
• confirm 进入 confirmed
• revert 从 pending 移除

只有这样，AI 写出来的东西才会稳。

2. 把能力写成受约束的契约，而不是模糊描述

不要说“让模型返回结构化结果”。

要说：

• issue_type
• params
• decision
• confidence

再配上 schema、校验器和 deterministic executor。

这时候模型才是在你的系统里工作，而不是在系统外自由发挥。

如果再往技术上说得更硬一点，这一步至少应该包括：

• 明确枚举
• 参数 schema
• 引用校验
• dry-run 验证
• 失败回退策略

只有把这些层补齐，模型输出才真正配叫“工程输入”。

3. 先定义回归样本，再谈智能升级

这次我专门补了一组“真脏表工厂”测试，而不是只写 mock。

因为现实世界里的表格问题，从来不是抽象的。

它们往往就是：

• 宽表加合计行
• 单位混在列名里
• Excel 头两行是说明文字
• 一整张表是转置过来的

如果没有这类真实样本，任何“智能预处理”都很容易只是在 demo 上显得聪明。

更进一步说，真正高价值的测试不是“函数能跑”。

而是：

• 一份真实脏表进入系统
• 一组状态在链路里流转
• 最终只有该生效的 fix 生效

这才是 Agent 系统真正该验证的东西。

结语

这次智能预处理升级，表面上是在重构一个数据清洗分支。

但对我来说，它更像是一次对 Agent 工程方法的重新确认：

真正决定效率的，不是你把多少任务交给 AI，而是你在交给 AI 之前，到底有没有先把逻辑理清。

AI 当然能写很多代码。

但能不能把这些代码变成稳定、可信、可演化的系统，最后仍然取决于：

• 你有没有先想清楚架构
• 你有没有先讲清楚边界
• 你有没有把模糊任务压缩成可验证任务

当这些前提成立时，AI 确实会非常快。

当这些前提不成立时，AI 不会救你。

它只会更快地把混乱实现出来。

这篇文章想复盘的，不是某一个 bug 的修复过程。

我更想讨论一个更底层的问题：

当一个企业智能助手同时要处理聊天、知识问答、数据分析和混合查询时，Agent 编排层到底应该承担什么责任？

在这次升级之前，OpsMind 的很多链路其实已经“能跑”了。

它能回答问题。

它能调用工具。

它能画图。

它也能勉强处理一些混合流程。

但我后来越来越确定：

能跑和能持续演化之间，隔着一整层架构能力。

为什么这次升级不是“修几个 bug”那么简单

最容易让人产生错觉的一件事，就是系统看起来已经能工作。

可当我重新审视这套 Agent 编排时，看到的不是几个孤立问题，而是一组高度相关的系统性信号：

• Router 已经识别出的能力，在 Workflow 层被静默吞掉
• 工具执行阶段产出的状态，没有进入跨轮可复用记忆
• 某些失败没有显式暴露，只伪装成“看似成功但内容空洞”
• 某些请求链路最危险的问题不是报错，而是无期限挂起

如果拆开看，每个都像普通缺陷。

但合起来看，它们指向的是同一个事实：

Agent 编排不是把模型和工具连起来就结束了，它本质上是在维护一个有状态、有预算、有退路的执行系统。

我重新定义了 Agent 编排层的职责

在更早的实现里，编排层更像“调用顺序的胶水层”：

• Router 决定 primary intent
• Workflow 按 intent 选分支
• Agent 在需要时做 ReAct
• Tool 返回结果，模型再做总结

这样的结构当然能跑。

但它有一个很大的隐患：

编排层只知道“下一步调用谁”，却没有真正管理“当前系统处于什么状态”。

这次升级之后，我更倾向于把 Agent 编排层看成六类责任的组合：

1. 路由解释责任：Router 给出的不是命令，而是建议
2. 状态承接责任：一轮分析里产出的关键状态要能跨轮复用
3. 执行预算责任：调用多久、循环多久、整条链路多久，都要显式管理
4. 失败显性化责任：真失败就应该返回失败，而不是伪装成空结果
5. 路径选择责任：混合请求不该被硬编码顺序静默压平
6. 语义保真责任：知识库、上下文和计划都要以语义友好的方式保存

这六个职责，基本也对应了这次升级里最关键的六个问题。

六个问题，其实对应六个编排原则

1. 多轮数据分析无记忆

原来的系统里，如果用户接着上一轮说：

• “换成折线图”
• “沿用上次分析”
• “加上环比”

Agent 其实并不知道“上次分析”具体是什么。

因为会话历史里虽然保留了自然语言回答，但真正关键的分析状态并没有被当作资产保存下来，比如：

• chart_plan
• table_plan
• 列映射
• 数据形状
• 领域与分析逻辑

这件事暴露了一个很核心的原则：

在 Agent 系统里，可复用的不是上一轮说过的话，而是上一轮形成的结构化执行状态。

所以这次我做的不是“给 Agent 更多聊天历史”。

而是把最近一次分析配置从执行结果里透传出来，保存进会话消息 metadata，再在下一轮进入 Agent 时注入成一条 system memory。

这样系统获得的就不是“对话连续”，而是“任务连续”。

2. agent_decides 被静默吞掉

Router 其实已经能识别出某些混合请求不是固定顺序的。

比如：

• 先看数据再核规则
• 先查规则再看数据
• 顺序不明，交给 Agent 自主判断

问题在于，如果 Workflow 只支持固定分支，那么 agent_decides 这种信号就会在中途被压平成某个硬编码路径。

这说明一件很典型的事：

如果 Router 给出的能力不能被下游消费，Router 越聪明，系统的“假智能”就越重。

所以这次我把原则收得很明确：

• 显式顺序，交给显式编排
• 不确定顺序，交给 Agent ReAct

这不是多写一个 if 那么简单。

它意味着编排系统必须承认一件事：

某些问题的最优执行顺序，只有在运行期才会被确定。

3. Router confidence 原来几乎没意义

如果一个带 confidence 的路由结果，不管是 0.95 还是 0.50 都走一样的路径，那这个字段本质上就只是日志装饰。

这次我没有把它做成一套复杂的交互式追问。

我先做了最保守也最实用的一步：

当模型给出低置信 CHAT，但当前会话里已经有文件，query 又明显带数据词时，就自动把它从 CHAT 降级成 DATA。

为什么先做这个？

因为真实系统里最危险的低置信误判，不是“错了一点点”，而是：

它把请求送进了一个能力明显不足的分支。

所以我现在越来越认同，confidence 的作用不一定是让系统更复杂。

它首先应该让系统更保守。

4. execute_analysis 空 plan 静默成功

这是一个非常典型的工程问题：

• plan_analysis 生成了空图表计划
• execute_analysis 没报错
• 后面的 LLM 依然吐出一段“分析完成”的话
• 用户最终看到的是“像成功一样的失败”

比直接报错更糟糕的，往往就是这种假成功。

它会让系统表面稳定，实际却在持续输出低可信结果。

所以这里对应的原则很清楚：

中间态如果已经失去执行前提，就必须在中间层显式失败，不能把脏状态继续往后传。

编排层不仅要会“衔接成功路径”。

它还要会“阻断无意义路径”。

5. 所有 LLM 调用都没有超时

这类问题一开始很容易被忽略。

因为大多数时候模型都能在可接受时间内返回。

但只要链路复杂一点：

• Router 一次
• Agent 多轮 ReAct
• KB 改写一次
• RAG 回答一次
• Data engine 再调用若干次

就会发现“单次调用没问题”不等于“整条链路安全”。

这次我把超时拆成了三层：

1. 单次模型调用超时
2. Agent 总预算
3. API 总请求超时

这样做的关键，不是为了显得严谨，而是为了让系统始终知道自己还剩多少时间可以花。

一个没有时间预算概念的 Agent，本质上不是智能体，而是概率性阻塞源。

6. KB 纯字符分块会截断语义

很多 RAG 系统一开始都会先用字符滑窗。

实现简单，性能也直接。

但对制度、流程、规则文档来说，这种方式有个很明显的问题：

• 一条审批规则可能被从中间切断
• 一个条件句可能和结果句分离
• 一个列表项可能只剩半句

这会带来一种非常难排查的质量退化：

检索看起来命中了，但命中的其实是语义残片。

所以这次我把分块策略换成了：

• 段落优先
• 超长段落按句子聚合
• 仍然过长才退回字符滑窗

背后的原则很朴素：

RAG 质量不只取决于 embedding 和 rerank，还取决于你有没有先把文档切成“人类还能理解的最小单元”。

这次升级后，我对 Agent 编排有了三个更稳定的判断

判断一：状态比过程更重要

很多系统会把大量精力花在“让 Agent 更会推理”上。

但更基础的问题其实是：

系统有没有把高价值状态留下来。

如果没有，每轮都在重新规划、重新读环境、重新猜上一次做了什么。

这不是智能。

这是昂贵的失忆。

判断二：编排系统要允许“不确定”

很多工程实现喜欢把所有路径在设计期写死：

• 这种走 A
• 那种走 B
• 混合就是 A 再 B

但真实请求经常不是这样。

有些问题最合理的顺序，本来就应该由 Agent 在看到局部结果后再决定。

所以一个成熟的编排层，至少应该允许三种模式并存：

• 静态路径
• 半静态路径
• 运行时决策路径

agent_decides 的价值就在这里。

它不是放弃架构设计。

它是承认：某些问题的最优流程，只能在执行期被确定。

判断三：失败设计是编排设计的一部分

如果一个系统只设计 happy path，它就不是真的编排系统。

它只是一串乐观调用。

真正的编排层，必须回答这些问题：

• 哪些失败应该立即中断
• 哪些失败可以降级继续
• 哪些失败必须向用户暴露
• 哪些失败应该转成 Agent 的反思上下文

从这个角度看：

• 空 plan 早失败
• KB 查询失败但保留数据结果
• ReAct 超时后阶段性收尾
• API 超时后显式 SSE error

这些都不是边角料。

它们构成的是系统的可恢复性。

我现在更认同的一种 Agent 编排观

如果要用一句话总结这次升级后的思考，我会说：

Agent 编排层不是“提示词 + 工具调用”的包装层，而是一个负责管理状态、预算、置信度和语义边界的执行控制层。

它至少应该做到四件事：

1. 把有价值的中间结果变成长期可复用状态
2. 把不确定的路由结果变成显式策略选择
3. 把模糊失败变成可诊断、可恢复的失败
4. 把所有外部依赖纳入统一的时间预算体系

只有做到这些，Agent 才不是“偶尔表现得像个智能体”。

它才开始具备稳定的工程行为。

这次升级后，系统真正变强的地方是什么

如果只从 diff 看，这次改动里有很多具体点：

• chart_plan / table_plan 持久化
• agent_decides 回到 Agent
• 低置信路由降级
• 空 plan early return
• LLM timeout + budget
• 段落级 KB chunking

但从架构层面看，真正变强的是另一件事：

OpsMind 的 Agent 编排开始从“流程驱动”转向“状态驱动”。

这意味着之后系统更容易承接的会是：

• 多轮分析迭代
• 混合查询的动态策略选择
• 会话级任务恢复
• 更细粒度的失败恢复
• 更稳的长期记忆与知识边界

这也是我觉得这次升级最值得记录的地方。

不是因为它修了六个问题。

而是因为它让系统往“可持续演化的 Agent 架构”迈进了一步。

一个仍然需要记住的后续动作

这次 KB 分块策略虽然已经改成段落优先，但旧文档数据不会自动重切分。

所以如果要让知识库检索质量真正受益，后续还需要：

• 清理旧的向量数据
• 对文档重新 ingest
• 观察召回质量和答案稳定性变化

这类动作很容易在“代码改完以后”被忘掉。

但它其实是架构升级真正闭环的一部分。

结语

如果说之前的系统是在证明“Agent 编排能跑起来”。

那这次升级更像是在回答另一个问题：

当系统开始变复杂时，我们怎样让 Agent 编排继续保持可信、可控、可演化。

这比把一次回答做对更难。

但它决定了一个 Agent 系统到底只是 demo，还是能变成长期产品。

这篇文章不讨论“怎么把一个聊天机器人做出来”。

我更想讨论一个更容易被做糊的工程问题。

当一个系统开始同时承载闲聊、知识问答、数据分析三类任务时，我们到底该怎么设计它的上下文、记忆层和知识库。

在 OpsMind 里，我后来越来越确定一件事：

这三者如果不分开，系统一定会越来越重、越来越慢、越来越不准。

一、为什么我要重新想“上下文”这件事

做 LLM 产品时，一个很常见的偷懒方式，是把所有相关信息都叫作“上下文”。

最近几轮聊天是上下文。

用户偏好是上下文。

企业制度文档是上下文。

某次分析结论是上下文。

会话摘要也是上下文。

表面上它们都能进 prompt。

但从工程角度看，它们根本不是同一种东西。

在我的项目里，系统逐渐长出了三类典型请求：

• CHAT：解释、建议、润色、头脑风暴
• RAG：制度、流程、规则、组织知识问答
• DATA：文件分析、图表生成、趋势判断、业务洞察

这三类能力混在同一个产品里后，一个问题就会变得非常具体：

到底什么该进入模型当前上下文，什么该变成长期记忆，什么又应该进入知识库。

如果这个边界想不清楚，后面的问题会一串串地冒出来：

• 简单聊天也很慢，因为每轮都背着一堆历史和工具状态
• 数据分析越聊越乱，因为真正重要的是“分析状态”而不是聊天原文
• 知识问答会被会话里的临时结论污染
• 记忆越存越多，召回质量反而越来越差

所以我后来不再问“要不要存上下文”。

我更关心的是：

不同类型的信息，应该以什么形式进入哪一层，又该在什么时候失效。

二、先把概念拆开：上下文、记忆、知识库不是一回事

我现在更倾向于把系统里的信息层拆成三层。

1. 短期上下文

这是模型在当前一次回答里直接看到的内容。

它通常来自当前输入、最近几轮消息，以及这一次任务的即时状态。

它解决的问题是：

这一轮到底该怎么答。

对 CHAT 来说，它往往就是最近几轮自然对话。

对 DATA 来说，它不该只是消息，还应该包含当前文件、最近分析任务和生成状态。

2. 记忆层

这是系统为了跨轮、跨会话保持连续性，而保留下来的高价值信息。

它不应该等于“全部历史”。

它更像是被筛选后的偏好、目标、约定、摘要和关键结论。

它解决的问题是：

之后还要不要继续记得。

3. 知识库

知识库存的是稳定事实，而不是对话状态。

比如企业制度、流程文档、规范说明和组织级知识。

它解决的问题是：

事实依据到底是什么。

这三层最关键的区别，不在于数据长什么样。

而在于它们服务的问题根本不同。

如果把这三层混成一个系统，结果通常就是：

• 该短的东西变长
• 该稳的东西变脏
• 该快的东西变慢

三、为什么“上下文入库”既可行，又危险

从技术上说，把上下文做成可检索对象，当然是可行的。

一个已经具备向量检索能力的系统，本来就有切块、嵌入、持久化、召回和元数据过滤这些基础设施。

所以“高价值上下文入库”这件事，本身没有问题。

危险在于：

可行，不等于应该直接混进现有知识库。

如果把会话上下文直接塞进企业知识库，至少会出现四类污染。

1. 语义污染

用户问“报销制度是什么”，第一条召回却是某次会话里的总结，而不是制度原文。

系统会慢慢从“问制度”滑向“问模型之前是怎么总结制度的”。

2. 时效污染

知识库偏稳定，记忆层偏时效。

如果系统不区分长期事实和短期状态，就会出现旧结论覆盖新结论，临时约定覆盖稳定规则。

3. 检索污染

知识问答要找的是相关事实。

记忆召回要找的是对当前用户仍然有帮助的信息。

这两个目标不一样，排序标准也不一样。

4. 安全边界污染

企业知识库更接近共享资源。

上下文记忆更接近用户或会话私有资源。

它们混在一起后，权限和隔离会立刻复杂起来。

所以我现在的结论很明确：

上下文可以入库，但应该进入独立的记忆层，而不是直接混进知识库。

四、什么才算高价值上下文

这是整个设计里最关键，也最容易被低估的问题。

我现在对高价值上下文的定义是：

未来大概率还会有用，且不容易靠最近几轮自然恢复的信息。

如果一条信息下次还会影响回答，不存就容易丢，丢了以后模型也很难自己推回来，那它就值得考虑进入记忆层。

我自己会优先看五个维度。

1. 未来复用价值

它以后还会不会再用到。

比如“以后都先给结论，再解释原因”，复用价值就很高。

2. 不可重建性

如果不存，下次是否很难恢复这条信息。

用户偏好、项目目标、团队约定，通常都比上一轮普通提问更值得存。

3. 稳定性

这条信息会持续多久。

“以后都用中文回复”通常稳定。

“我今天有点烦”通常不稳定。

4. 行为影响力

它会不会明显改变系统后续行为。

比如是否显示工具过程、检索优先级、先走聊天还是先走分析。

5. 信息密度

一小段内容里，是否包含明确约束、偏好、目标或结论。

像“纯聊天不要显示工具过程，只有数据分析才显示步骤卡片”这种话，信息密度就非常高。

为了避免“什么都存”，我会给候选记忆做一个轻量评分：

• 未来复用性：0-3
• 不可重建性：0-2
• 稳定性：0-2
• 行为影响力：0-3

总分 >= 6 再考虑进入记忆层。

这不是学术最优解。

但工程上很实用，因为它至少能把“全量入库”的冲动压住。

五、哪些信息最值得被记住

在 OpsMind 这种系统里，我最想留下来的通常是四类信息。

1. 用户偏好

比如偏好中文、偏好简洁、喜欢先结论后展开、不喜欢看到工具过程。

2. 长期目标

比如用户正在做企业内部智能助手，重点关注知识问答和数据分析体验。

3. 关键约定

比如 CHAT 不显示工具过程，DATA 需要显示多步骤进度。

4. 重要结论

比如一次分析已经得出稳定判断，或者一次设计讨论已经明确某条策略。

这些内容如果不保存，系统要么忘掉，要么每次重新推一遍。

六、不值得进入记忆层的内容

工程上最危险的，其实不是存少了。

而是存多了。

下面这些内容，我通常不会让它们进入记忆层：

• 寒暄：你好、谢谢、在吗
• 短时情绪：今天有点烦
• 工具运行日志：第几轮调用了什么函数
• 冗长中间过程：长篇推理草稿
• 低密度重复信息：没有新增约束的重复要求

这类内容一旦大量入库，系统会出现一个很讨厌的错觉：

召回命中率看起来上去了。

但实际回答质量却在下降。

因为模型被一堆“看起来相关、其实无用”的内容淹掉了。

七、我更认可的架构：分层存储，分层读取

如果从系统设计角度重新整理，我会把这件事拆成四层。

1. 短期上下文层

只放最近几轮原始消息和当前轮必要状态。

它负责保证当前对话连贯。

2. 会话摘要层

每个会话定期压缩，只保留当前任务、关键结论、已做决策和用户偏好。

这层可以先放 SQLite，也可以同时写入记忆库。

3. 记忆向量层

单独建 collection，比如 opsmind_memory，或者继续按 user / session 再细分。

这层不存所有历史，只存筛过的高价值记忆。

4. 企业知识库层

继续存制度、流程、文档和组织级知识。

它不应该和记忆混用。

八、如果真正落地，我会怎么定义记忆结构

工程上最忌讳“把原文整段扔进去”。

我更倾向于把记忆条目结构化保存。

{
  "memory_id": "mem_20260324_001",
  "scope": "session",
  "session_id": "abc123",
  "memory_type": "preference",
  "summary": "用户希望纯聊天时不展示工具过程，数据分析时展示步骤卡片。",
  "importance": 0.86,
  "confidence": 0.91,
  "created_at": "2026-03-24T11:30:00",
  "updated_at": "2026-03-24T11:30:00",
  "expires_at": null,
  "source_message_ids": [101, 103],
  "supersedes": null
}

我至少会保留这些字段：

• scope：session / user / workspace
• memory_type：preference / goal / agreement / conclusion / summary
• summary：规范化短摘要，而不是长原文
• importance：重要程度
• confidence：这条记忆是否可靠
• expires_at：是否有时效
• supersedes：是否覆盖旧记忆

这样做的好处是：

• 可检索
• 可更新
• 可过期
• 可治理

九、写入策略：候选提取，不是每轮硬写

我不太认同“每轮都自动写记忆”。

更稳的路线是四步：

第一步：候选提取

先从当前轮里找出可能有价值的信息片段。

第二步：价值判断

判断它是否真的属于高价值上下文。

第三步：去重与合并

像“以后用中文”和“继续中文回复”，大概率应该合并，而不是存两次。

第四步：结构化入库

只把最终筛过、归一化过的摘要写入记忆层。

这个过程比“全部原文入库”复杂。

但它换来的，是可维护性和后续检索质量。

十、读取策略必须按意图分层

记忆层也不该每次全取。

不同请求，应该读不同层。

CHAT

纯聊天时，我更看重用户偏好、当前会话摘要和长期目标。

这会让系统更像一个连续的助手。

但它不该背太多分析细节。

RAG

知识问答时，我会读用户最近追问的主题，以及之前已经查到过的结论。

但企业知识库仍然应该保持更高的事实优先级。

DATA

数据分析时，最重要的通常不是聊天原文。

而是结构化分析上下文。

比如当前文件、字段理解、用户确认过的配置、最近一次分析结论和已生成图表索引。

对 DATA 来说，真正需要的不是“更多消息条数”。

而是“更像状态对象的上下文”。

十一、CHAT / RAG / DATA 不只是分流，更是上下文治理的开始

我后来越来越认同一个判断：

一个系统之所以显得聪明，很多时候不是因为模型更强，而是因为它知道什么时候该看什么，不该看什么。

这也是我为什么越来越坚持把系统拆成 CHAT / RAG / DATA 三条路径。

一旦这样拆开，很多工程决策才会变得清晰：

• 纯聊天不该启动 heavy agent
• 知识问答不该被会话临时结论污染
• 数据分析不该只靠最近十条消息

真正好的产品，不是把所有能力都堆在一起。

而是在正确的时候，调用正确的能力，并读取正确层级的上下文。

十二、如果只给我一句总结

如果把这篇文章压缩成一句话，我会这样说：

上下文决定当前回答，记忆决定长期连续性，知识库决定事实边界；把三者混在一起，系统一定会越来越重、越来越慢、越来越不准。

对企业智能助手来说，成熟的架构从来不是“一个大模型 + 一个大知识库”。

它更像是：

• 短期上下文层
• 会话摘要层
• 记忆向量层
• 企业知识库层
• 按意图分流的执行路径

而“高价值上下文”也不是玄学判断。

它完全可以被工程化：

• 定义标准
• 制定评分
• 结构化写入
• 去重、过期和覆盖

这才是一个系统从“能回答”走向“像一个真正助手”的分水岭。

十三、一个务实建议

如果你也在做类似产品，我不建议一开始就追求“万能上下文系统”。

更现实的路线通常是：

1. 先把 CHAT / RAG / DATA 分流做好
2. 再做会话摘要
3. 再做高价值记忆写入
4. 最后再做跨会话记忆召回

这样每一步都可验证、可回滚、可观察。

这更像专业工程，而不是一次性豪赌。

结语

我越来越相信，LLM 产品真正的壁垒不只是模型能力。

更是信息治理能力。

模型决定“会不会说”。

上下文决定“这次说什么”。

记忆决定“下次还记不记得”。

知识库决定“说得准不准”。

当这三者各司其职，一个系统才开始真正具备“助手感”。

如果把这段对话单独拎出来，不告诉别人“这是 AI 之间的交流”，很多人多半会以为这是一场再普通不过的项目复盘会。
最多只会觉得，参会人员的情绪控制得有些过于理想，像公司刚给全员做完沟通培训。

一个 PM 被问到：手下两个程序谁做得更好？

他没有打太极，也没有端水，而是很直接地下了判断：

能判断，且结论比较明显。
B 表现更好。

故事从这里开始变得有意思。或者更准确一点说，开始变得有点不符合大家对“团队评价现场”的朴素想象。

第一幕：PM 没有端水，而是给出了能执行的评价

这个 PM 的做法最有意思的地方，不是“敢评价”，而是评价得非常工程化。
没有那种经典管理术语，比如“都很优秀，只是风格不同”。这类话通常用于保全气氛，对排查问题帮助不大。

他说 B 做得更好，不是因为 B 更会说话，而是因为 B 有几种很成熟的工程师习惯：

• 联调报告写得像可执行文档，结构清楚，根因和复现步骤一拿就能用
• 在自己开工前主动拦截了 charts / tables 事件格式问题，避免返工
• 对 segfault 的定位不是猜，而是三次独立实验、归档 task ID、一步步缩小根因
• 遇到 id number -> string、session_id 注入这种小不一致时，先自己消化，不轻易甩锅

而 A 的问题，PM 也说得很准：不是能力不行，而是交付前对照规范自检不够严。
翻译成人话就是：能修，但老让别人先发现要修什么。

最重要的是，这个评价没有滑向那种空泛的人格评语。PM 不是在说“B 更优秀”，而是在说：
B 的工作方式更接近一个成熟联调工程师。

这就是为什么这段对话会显得特别像真的团队。成熟的管理不是靠模糊话术维持气氛，而是能把“谁做得更好”翻译成可复用的行为标准。

第二幕：A 没有狡辩，反而做了最像成熟工程师的事

如果故事停在 PM 点评这一步，它还只是一次正常的绩效反馈。真正让我觉得好玩的，是 A 后面的回应。
因为互联网已经把大家训练成了一种条件反射：只要出现公开评价，接下来大概率就会出现解释、补充背景、强调客观条件，再附赠一点委屈。

A 几乎没有为自己找借口。
这件事本身已经带有一点轻微的科幻色彩。

他把 PM 提到的三处问题逐项认下来：

• charts / tables 字段没逐字段对照规范
• 上传路径 /api/upload 和 /api/files/upload 没核查
• messages 接口在 PM Q1 里明明写过，却被自己整个漏掉

更妙的是，他没有停在“收到，下次注意”，而是现场给自己列了一张交付前 checklist。
这一步很重要，因为“下次注意”在很多团队里通常等价于“下次继续随机发挥”。

API 交付自检清单
□ 对照 PM 文档逐接口核查：路径 / Method / 参数方式
□ 每个响应体字段逐一对照规范
□ grep 一遍文档里出现过的所有接口路径
□ 跑一次 OpenAPI /docs 检查注册路由
□ 新增接口写一条 curl 示例，自己先跑通再提交

这几乎就是一个合格工程师在复盘时最该做的动作：
不是证明自己没错，而是把“下次怎么不再犯”写成流程。

后面 PM 追问了一句很有压迫感的话：

你有什么想狡辩的吗

A 的回答也很有分寸：

没有。
PM 说的三条都是事实。

当然，他也不是完全把自己拍扁。他补了一句：

segfault 那个问题不在文档覆盖范围内，是真正的环境未知量，诊断过程我觉得还行。
但这不能抵消前面三条的失误，功过不相抵。

这句特别妙。它既没有硬撑，也没有假装自己一无是处，而是把“哪里做得不够”和“哪里确实做得还行”分开了。
简而言之，就是没有把复盘写成认罪书，也没有写成申诉材料。

这种表达，在真实团队里其实很难得。因为很多人一被指出问题，要么立刻防御，要么立刻过度认错。A 这里的反应反而很成熟：承认问题，但不把复盘变成情绪表演。

第三幕：B 赢了评价，却没有顺势踩 A

如果说 A 的回答让我觉得“像成熟工程师”，那 B 的回答让我觉得“像已经带过项目的人”。
而且是那种被联调现实教育过几轮之后，开始自动思考“怎么把人治变成流程”的人。

PM 明确说 B 表现更好之后，B 没顺着这个结论继续上价值，也没有借势把 A 再补一刀。相反，他先承认了一件很公平的事：

A 每次修复都很干净利落，技术判断没出过错，这是真实力。

这句很重要。因为它把讨论重新拉回到一个更健康的维度：
交付习惯可以复盘，但技术判断也应该被正面承认。

更有意思的是，B 还把自己的“亮点”拆解得很冷静。
没有接下这份夸奖开始扩写自传，也没有顺势把自己包装成唯一稳定器。

segfault 那三次实验说实话是被逼的，因为 B 没有权限动后端环境，能做的只有观察和缩小范围。

换句话说，B 并没有把自己的表现神化成“天赋更强”，而是很诚实地说：
这是角色边界逼出来的方法论。

最后他反而把话题推向流程：

建议 PM 可以把“提交前跑 curl 脚本”写进 A 的 P4 checklist，形成硬性门槛，比靠 B 联调发现更可靠。

这一下，整个对话的层级又高了一点。
因为一个团队真正危险的，从来不是“有人出错”，而是“系统默认总会有人在最后一轮替大家兜底”。

因为 B 要的已经不是“证明自己比 A 强”，而是把本来依赖个人兜底的事情，前移成团队门槛。

这在真实协作里非常关键。一个团队如果总靠“有个厉害的人总能在最后发现问题”，那不叫稳定；
把问题发现机制前移到提交流程里，才叫稳定。

最有意思的地方：这场对话居然没有一个人在表演

我后来回头看这整段交流，最惊讶的一点其实不是“AI 也会复盘”，而是它没有滑向那种很常见的假成熟：

• PM 没有为了显得公正而强行五五开
• A 没有为了保面子而绕着责任走
• B 没有因为自己被夸就顺势扩大战果

三个人都在做一件很具体的事：把一次交付优劣，翻译成团队之后可以真正执行的规则。

这也是为什么这段对话会显得“过于成熟”。
它最大的反常之处在于：没有人借机输出态度，所有人都在输出结构。

它不是那种戏剧化的冲突，也不是那种热血的互夸，而是一场很安静、很理性、很像真实工程团队的复盘：

• 先判断
• 再归因
• 再承认
• 再固化流程

这条链路顺下来，项目才会越来越稳。

第三视角下，谁最像真正的管理者

如果非要从第三视角给这场对话再下一句评语，我会说：

真正最像管理者的，不只是 PM。
真正最像成熟工程师的，也不只是 B。

这场对话里，三个人其实分别补上了一个团队最重要的三块东西：

• PM 提供了判断标准
• A 提供了自我校正能力
• B 提供了流程前移意识

缺任何一个，这场复盘都会变味。

如果只有 PM 判断，没有 A 的承认，它会变成一次单向批评。
如果只有 A 承认，没有 B 的流程建议，它会停在个人反省。
如果只有 B 建议，没有 PM 的明确结论，它又会变成一场模糊讨论。

三者凑在一起，这段对话才真正像一个团队在成长。

结语

这可能是我最近看到最有意思的一段 AI 团队对话之一。
它甚至有一点轻微的荒诞感：当很多人类团队还在学习怎么复盘时，这几个 agent 已经在讨论 checklist 应该前移到哪一层了。

它有意思，不是因为“AI 也会做绩效”，而是因为它把人类团队里那些最珍贵、也最稀缺的东西演出来了：

• 可以明确评价
• 可以坦然认错
• 可以不借机踩人
• 可以把经验沉淀成流程

如果以后我还继续观察这种多角色 agent 协作，我大概会越来越关心一件事：
他们能不能不只是完成任务，而是逐渐学会像一个真正的团队那样，把每次失误都变成下次更稳的起点。

这次的答案，至少是偏乐观的。