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 下来要跑验证脚本前，先重新生成：
# 协议适配层（入口 _entry-coordinator.ts）
# ⚠️ 必须带 --loader:.png=dataurl：协调器 import 了企业微信二维码
# （@/assets/qiyeweixin.png，result.cipa=true 时展示用），
# node 侧的 esbuild 不认识 .png 会直接报错
npx esbuild harness/tools/_entry-coordinator.ts --bundle --format=esm \
--outfile=harness/tools/_coordinator.mjs --alias:@=./src \
--define:import.meta.env='{}' --loader:.png=dataurl
# 会话/问答记录 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 流 |
_coordinator.mjs |
verify-answer-stream.mjs |
❌ 纯逻辑（增量规整器/状态机）+ 假 SSE 喂真实协调器（F073 正文流式） |
_coordinator.mjs |
verify-answer-stream-payload.mjs |
❌ 回放真实 SSE 抓包（协调器 + 应用侧组装）；默认用 fixtures/answer-stream-tail.payload.md |
载荷夹具 fixtures/
fixtures/answer-stream-tail.payload.md 是一份合成的原始 SSE 载荷，形态取自真抓包：
answer_end 给出的文本比增量拼接多一截尾巴（真载荷 1309 → 1610 字，尾部是追问建议）。
这个形态会让应用侧记录的「流式正文」不再是上屏内容的后缀 —— 2026-09-20 用户报的
「同一段内容出现两次」就是它。夹具入库是为了让这条回归随时可回放；
真抓包（600KB 量级）不入库，需要时把浏览器存的响应文件作为参数传进去即可。
文档生成与审计（不是断言脚本，但也打真实 DMS 读模型定义）：
| 脚本 | 干什么 | 产物 |
|---|---|---|
gen-company-info-mapping-doc.mjs |
生成「company_info ↔ DMS 企业两栏目」字段对应文档 | docs/reference/company-info-dms-mapping.md |
audit-company-info-coverage.mjs |
审计字段覆盖率（载荷 / 模型 / 代码写入列三边对齐） | 控制台清单 |
probe-answer-stream.mjs |
打真实后端，统计 F073 正文流式的原始载荷并喂真实协调器 | 控制台统计与契约一致性核对 |
--define:import.meta.env='{}'：验证脚本跑在 node 里没有import.meta.env， 需要喂一个空对象，否则读取环境变量的模块会直接抛错。⚠️ 排查协议类问题时，务必读原始 SSE 载荷。曾经因为只看自己封装的中间事件， 两次误判"后端不返回补问"，而实际是适配层已把事件并入 message 通道、查错了事件名。
本目录不参与构建
tools/ 下的脚本不进入前端产物，也不参与 npm run build。放心写。