# tools/ — 临时脚本放这里

写验证脚本、调试脚本、一次性数据处理的脚本，**都放这个目录**，不要再丢到项目根目录。

## 为什么

以前这类脚本临时写在项目根目录（`_tmp_xxx.mjs`），用完就删。问题有三个：

- 根目录被污染，`ls` 一下分不清哪些是项目文件
- 好用的脚本删了就没了，下次还要重写（例如"验证适配层输出契约"这种脚本写过不止一次）
- 出了问题无法复现 —— 当时是怎么验的，没留下任何东西

放在这里之后，**脚本可以留着**。它们是"当时怎么验证的"最好的证据。

## 约定

- 命名：`<用途>.mjs`，例如 `verify-adapter.mjs`、`probe-summary-dup.mjs`
- 顶部写一行注释说明：**这个脚本验证什么、怎么跑**
- 只读脚本优先（探测接口、打印数据），改动数据的脚本要显式说明
- 一次性用完确实没价值的，可以删；**有复用价值的留下**

## 常用套路

项目里几个反复用到的做法，可以直接抄：

```bash
# 把 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 下来要跑验证脚本前，先重新生成**：

```bash
# 协议适配层（入口 _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`。放心写。