README.md
tools/ — 临时脚本放这里
写验证脚本、调试脚本、一次性数据处理的脚本，都放这个目录，不要再丢到项目根目录。
为什么
以前这类脚本临时写在项目根目录（_tmp_xxx.mjs），用完就删。问题有三个：
- 根目录被污染，
ls一下分不清哪些是项目文件 - 好用的脚本删了就没了，下次还要重写（例如"验证适配层输出契约"这种脚本写过不止一次）
- 出了问题无法复现 —— 当时是怎么验的，没留下任何东西
放在这里之后，脚本可以留着。它们是"当时怎么验证的"最好的证据。
约定
- 命名：
<用途>.mjs，例如verify-adapter.mjs、probe-summary-dup.mjs - 顶部写一行注释说明：这个脚本验证什么、怎么跑
- 只读脚本优先（探测接口、打印数据），改动数据的脚本要显式说明
- 一次性用完确实没价值的，可以删；有复用价值的留下
常用套路
项目里几个反复用到的做法，可以直接抄：
# 把 TS 源码打包成能在 node 直接跑的 ESM（用于验证 src 里的真实逻辑）
npx esbuild harness/tools/<某入口>.ts --bundle --format=esm --outfile=harness/tools/<产物>.mjs
# 直接打后端 SSE 原始载荷（排查协议问题必须看原始载荷，不能只看封装的中间事件）
# —— 见 harness/docs/reference/api-chat.md 的事件说明
⚠️ 打包产物 _*.mjs 不入库，改了源码要重新打
_*.mjs 是 esbuild 从 _entry-*.ts 生成的构建产物，按 .gitignore 排除
（入库会与源码漂移，让人误以为测的是新代码）。clone 下来要跑验证脚本前，先重新生成：
# 会话/问答记录 DMS 相关（入口 _entry-dms.ts）
npx esbuild harness/tools/_entry-dms.ts --bundle --format=esm \
--outfile=harness/tools/_dms.mjs --alias:@=./src --define:import.meta.env='{}'
# 内容判空口径（入口 _entry-empty-content.ts）
npx esbuild harness/tools/_entry-empty-content.ts --bundle --format=esm \
--outfile=harness/tools/_empty-content.mjs
# 政策库判定与置顶（入口 _entry-policy-library.ts）
npx esbuild harness/tools/_entry-policy-library.ts --bundle --format=esm \
--outfile=harness/tools/_policy-library-utils.mjs
# 企业信息分类同步（入口 _entry-company-classify.ts）
npx esbuild harness/tools/_entry-company-classify.ts --bundle --format=esm \
--outfile=harness/tools/_company-classify.mjs --alias:@=./src --define:import.meta.env='{}'
对应的验证脚本：
| 产物 | 验证脚本 | 打不打真实后端 |
|---|---|---|
_dms.mjs |
verify-dms-chat-storage.mjs |
✅ 真实 DMS（需 dev server 起着） |
_dms.mjs |
verify-dms-payload-fields.mjs |
❌ 打桩 fetch 抓请求体 |
_company-classify.mjs |
verify-company-classify-sync.mjs |
❌ 纯逻辑 |
_company-classify.mjs |
verify-company-classify-dms.mjs |
✅ 真实 DMS（注入假分类响应，可反复跑） |
_company-classify.mjs |
verify-company-classify-e2e.mjs |
✅ 真实分类接口 + 真实 DMS（要一份真实形态的 company_info JSON，见脚本头注释） |
_coordinator.mjs |
verify-company-info-passthrough.mjs |
❌ 打桩 fetch 喂假 SSE 流 |
--define:import.meta.env='{}'：验证脚本跑在 node 里没有import.meta.env， 需要喂一个空对象，否则读取环境变量的模块会直接抛错。⚠️ 排查协议类问题时，务必读原始 SSE 载荷。曾经因为只看自己封装的中间事件， 两次误判"后端不返回补问"，而实际是适配层已把事件并入 message 通道、查错了事件名。
本目录不参与构建
tools/ 下的脚本不进入前端产物，也不参与 npm run build。放心写。