zhaoshang_client_ui/harness/tools/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 正文流式）

文档生成与审计（不是断言脚本，但也打真实 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。放心写。