命令行工具实验失败后该学到什么

我让 Agent 给公开 Markdown 自动分组，结果它把“安装”和“卸载”合成一类。失败不说明模型完全不能用，只说明规则没有被写清。那次输出看着很整齐，类别名称也像模像样；问题是我只抽查了几个相近词，没有把反义操作放进样本。等到准备接到脚本里，才发现卸载说明被推荐到安装分组，读者照着找会直接走错方向。

tool group fixtures/opposites.md --dry-run

我把这条 fixture 加进测试，并要求模型返回理由和置信度；低置信度直接保留原文。实验输入不含内部文档，输出须人工确认。下一步不是扩大调用，而是补足这类反例。

先把失败变成可重复的输入

我没有先改提示词，而是留下了最小的 Markdown 文件：两个标题、几段说明，以及会让规则混淆的动词。这样做有两个好处。第一，测试运行很快，不必每次处理整套文档；第二，别人看到失败时能够判断是分词、分类边界，还是后处理把结果拼错了。只保存公开样例也避免了把真实文档带进调试记录。

这个 fixture 不该只断言“命令成功退出”。我会检查每个段落是否仍在原位置、分类标签是否符合预期、模型给出的理由有没有提到真正的区分词。理由不是为了追究模型说得是否漂亮，而是排查它是不是碰巧猜对。若理由里只出现泛泛的主题词，下一次换个措辞就很可能再错一次。

把人工确认留在边界位置

自动分组适合处理重复、格式稳定的工作，但它不该替用户改写原文，也不该偷偷合并含义相反的操作。因此脚本把结果分成三类：规则明确的直接标注；有冲突或低置信度的交给人工；无法判断的保持未分组。未分组不是失败状态，它只是说明当前规则还没有覆盖这个句子。

人工查看时，我更关心修改成本。若一个类别需要频繁拖回去，说明类别设计过细，或者输入中缺少足够线索；若所有内容都落到人工队列，说明自动化的边界画得太宽。把这种观察写在 issue 里，比把参数一路调大有用。每次变更只动一个因素，例如先增加反义词规则，再观察误分是否下降，避免同时改模型、提示和后处理后无从定位原因。

测试通过后仍要看错误路径

这类工具容易在演示中显得可靠，因为演示通常只给它干净的标题。真正接入前，还要试试空文件、重复标题、混合中英文命令和没有正文的列表项。它们未必需要被完美分类，但程序应给出可读结果，不能丢段落或把内容写进错误文件。--dry-run 在这里很重要：先看计划，再允许写回。

我会把每次实验记录成版本、fixture 名称、规则改动和人工结论，不记录用户文档或接口返回的原文。出现误分时，先把该样例加回测试，再修实现。这样下一轮不是凭印象说“模型似乎进步了”，而是能看到哪些输入已经被稳定覆盖，哪些仍应该留给人处理。

还有一个容易忽略的点：分类规则本身也要能被删除。某条补丁如果只服务于一份过时样例，就在注释里写清原因和退出条件；等样例不再代表真实输入时，一并移除。测试集不是越多越好，保留能解释风险的例子，维护成本才不会反过来吞掉工具带来的收益。