zhaoshang_client_ui/harness/tools

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

--define:import.meta.env='{}'：验证脚本跑在 node 里没有 import.meta.env， 需要喂一个空对象，否则读取环境变量的模块会直接抛错。

⚠️ 排查协议类问题时，务必读原始 SSE 载荷。曾经因为只看自己封装的中间事件， 两次误判"后端不返回补问"，而实际是适配层已把事件并入 message 通道、查错了事件名。

本目录不参与构建

tools/ 下的脚本不进入前端产物，也不参与 npm run build。放心写。