交付案例：把 44 个仓储项目的坑，做成 AI 能调用的工具

我把自己在仓储物流项目里见过的坑整理成一个库，再把它做成两样东西：一个 5 分钟的项目自评，和一组能让 Claude、Cursor 这类 AI 助手直接调用的工具。

这篇写它是怎么做出来的、哪里坏过，以及我怎么验证它靠不靠谱。

一、起因与约束

从 2019 年做仓储物流系统落地以来，同样的坑我看见了很多次：

• 货位表填了一半就上线；
• 立库选了黑盒，验收以后改一条出库规则都要走变更单；
• 上线前没有人说得清「切换那天晚上谁在现场」。

这些经验原来散在三个地方：我写的实施手册、上线清单和判断卡。它们能帮到人，但只能靠人去读。

我想让两类人用上它：

• 甲方项目经理：离上线还有几个月，想知道自己的项目哪里会出事；
• 乙方实施顾问：已经在用 AI 助手干活，希望助手能直接查到「这个症状对应哪个坑、该怎么办」。

约束有四条：

1. 不能带出任何公司：坑都来自真实项目，必须脱敏；
2. 每张坑卡我本人审过才算数：机器整理的不直接上线；
3. 中英文两套：中文站和英文站都要用；
4. 一个人维护：不能做成要天天照看的系统。

二、我的判断

判断 1：打分不交给大模型。

甲方要的是能复查的结论：同样的回答，今天测和明天测，结果必须一样。所以自评的计分规则写死在代码里：

• 按所处阶段和项目规模（有没有立库、AGV，接不接 MES）筛出适用的题；
• 答「否」或「不知道」，就认为对应的坑成立；
• 先按严重度、再按离当前阶段的远近排序，取前 3 条建议。

规则都写进了单元测试。零命中时不硬凑 3 条；全答「不知道」时，给出「先去找乙方要哪几样材料」。

判断 2：大模型放在它擅长的地方，也就是听懂人话。

工具里没有接大模型。工具通过 MCP 开放给用户自己的 AI 助手（MCP 是让 AI 助手调用外部工具的标准接口）：

• 助手负责理解用户在说什么；
• 坑库负责给出有出处的答案：每个坑都标了来自手册哪一章、清单哪一条。

这样答案不会被模型「编」出来，用户也不用为我的模型调用付钱。

判断 3：只有一份真源。

坑库、题库、站点和计分规则只在一个代码包里维护。网站、账户中心、MCP 服务都从这个包取数据，并且都带版本号和内容哈希。三处对不上，测试就会拦住。

三、做了什么

坑卡（Markdown，一张一个文件，本人审过才收）
   │  编译：脱敏检查 + 结构校验
   ▼
坑库代码包（唯一真源）：21 站 · 5 条线 · 44 个坑 · 30 道自评题 · 计分规则
   ├─▶ 网站：首页避坑模块、自评介绍页、体检报告样例页
   ├─▶ 账户中心：分阶段答题、结果页、一键预约体检
   └─▶ MCP 服务：3 个工具
         · wms_list_questions   列出适用的自评题
         · wms_risk_scan        按回答扫描风险（和网页自评同一套计分）
         · wms_symptom_lookup   用户描述一个现场症状，返回最可能的 3 个坑

症状问诊（wms_symptom_lookup）也是确定性匹配，不调大模型：

• 把一句话切成词，每个词按区分度打分；
• 词出现在「同义说法、关键词」里算得重，出现在标题、现场表现里算得轻；
• 最高分不到阈值就回答「没找到」，宁可不答，也不硬凑。

2026 年 10 月，中文站先上线（10-09），英文站随后上线（10-13）。

四、哪里出了问题，怎么查的

1. 中文页面上写的是英文站的接入地址。

• 现象：准备上线中文工具时发现，中文 /mcp/ 页上有 3 处接入地址写的是英文站的域名。
• 原因：工具目录的快照是从英文账户中心拉的，校验规则也只认英文域名，所以中文页面「合法地」显示了错误的地址。
• 改法：作为单独修复先发，不等大版本。目录快照按语言分成两份，中文页读国内账户中心那份；再加两道检查，一是校验快照语言，二是构建时检查接入地址的域名。

2. 「本机复验通过」，外面访问却是 403。

• 现象：给自评介绍页加访问计数时，部署脚本报告「复验成功」，但从外部访问英文测试站的计数地址是 403，计数一直不涨。
• 原因：测试站除了口令，还有一层地址准入。脚本只关了口令，没放行地址；复验又是从服务器本机发起的，本机恰好在允许名单里，所以看不出问题。顺带还发现，脚本从配置里取主机名时取错了一行。
• 改法：脚本在这类站点上同时放行计数地址；主机名只认对应的那条指令；补了 3 条测试，更新了 1 条。
• 回头看：中文测试站也是同样的配置，这个问题已经存在了几天，只是一直没人从外面看过。

教训：验证要站在用户的位置做。从被允许的地方去验证，永远看不出问题。

3. 评测集里有一条标注是错的。

• 现象：英文评测集里，「Developers test once」这句被标成应该命中某个坑。
• 原因：独立复核时发现，中文原卡里找不到能支撑这个判断的内容，是英文同义词表里多出来的说法把它「凑」上了。
• 改法：改标为「不应命中」，并在评测集说明里记下这次修改。

教训：评测集本身也要被审。标注错了，指标再好看也是假的。

五、怎么验证

验收门槛写在测试里：前 3 个候选的命中率 ≥ 80%，不该命中时的误报率 ≤ 20%。

阈值是用标注样本校准的：应命中的说法，最高分里最低的是 19.5；不该命中的说法，最高分里最高的是 16.9。阈值取 18。

2026-11-04 重跑的结果（5 个测试文件，82 条通过、1 条跳过）：

评测	应命中	不该命中
中文	59 / 59 进入前 3	误报 0 / 10
英文·校准集	29 / 29	误报 0 / 11
英文·留出集（不参与调参）	14 / 14	误报 0 / 10
英文·200 字以上的长描述	2 / 3	误报 0 / 8

这些数字能说明什么、不能说明什么，要讲清楚：

• 标注样本是 AI 代理按坑卡写的「模拟说法」，不是真实用户的原话；
• 100% 命中更可能说明样本偏容易，不能说明工具在真实现场同样准；
• 长描述只命中 2/3，是目前最弱的地方：用户讲一大段背景时，关键信号会被稀释。

真实用户的说法没命中时，会先脱敏再记下来。攒够以后，用这些说法补同义词，并扩充评测集。

六、结果

• 中英文两套已经在线：网页自评、体检样例和 3 个 MCP 工具都能用；
• 坑库、网站、账户中心、MCP 服务四处由同一个代码包驱动，版本号可查；
• 真实使用数据还很少，所以这篇不写效果数字。等真实问诊记录攒够了，再补一篇「真实说法下的命中率」。

七、再做一次，我会怎么改

1. 先拿 20 句真实用户原话做评测集，再写同义词。 先写同义词再造样本，容易变成自己出题自己答。
2. 验证一律从外部做。 第 2 个坑说明，任何「复验」都要从用户的位置发起。
3. 长描述单独处理。 先从一大段话里抽出症状句，再拿去匹配，而不是整段一起打分。

想先看看自己的项目？可以做一下 5 分钟自评，或者看看体检报告样例。