# 工具目录

本目录只保存可重复使用的工程工具和自动测试。运行产生的 JSON、文本、截图和日志统一写入 `reports/`；需要长期保留的脱敏证据经检查后移入 `archive/evidence/<日期>/`。

## 自动测试

所有 `*.test.mjs` 由 `node --run test:legacy` 自动执行：

- `business-input-templates.test.mjs`：业务模板、Prompt 与解析契约；
- `lifecycle-contract.test.mjs`、`operation-plans.test.mjs`：生命周期与插件契约；
- `build-lifecycle-replay.test.mjs`、`record-split-probe-result.test.mjs`：回放和探针结果构建；
- `product-lookup.test.mjs`、`split-plan-reconciliation.test.mjs`、`team-batch.test.mjs`、`execution-guard.test.mjs`：独立组件；
- `repository-hygiene.test.mjs`：目录边界、规划文件、发布清单、重复产物和活动文档卫生。

## 构建与可复用 helper

| 文件 | 用途 |
|---|---|
| `build_lifecycle_replay.mjs` | 从稳定输入构建生命周期回放 |
| `build_business_instruction_docx.py` | 从业务模板 Markdown 重建版本化 DOCX；执行和渲染验证遵循 Documents skill |
| `record_split_probe_result.mjs` | 校验并记录分团探针结果 |
| `chrome-cdp-target.mjs` | 多个工具共享的 CDP 目标解析 |
| `dry_run_order_create.mjs` | 从脱敏样例生成下单 dry-run |

DOCX 构建后必须按 Documents skill 全页渲染。macOS bundled LibreOffice 需要中文字体时，将 workspace dependencies 中 `dependencies/native/poppler/poppler/etc/fonts/fonts.conf` 传给 `FONTCONFIG_FILE`；出现方框字、截断或溢出即视为验证失败。

## 手工只读与保存前工具

以下工具不会自行取得业务写入授权；默认用于页面发现、Schema 抽取、候选解析、保存前拦截或只读回查：

- `cdp_lwlt_probe.mjs`、`extract_order_add_schema.mjs`；
- `inspect_*.mjs`、`validate_order_add_lookups.mjs`、`resolve_order_add_lookups.mjs`；
- `browser_order_add_dry_run.mjs`、`browser_order_add_preflight.mjs`、`browser_order_add_submit_intercept.mjs`、`browser_order_add_template_selftest.mjs`、`browser_order_add_raw_instruction_test.mjs`；
- `run_readonly_lifecycle_requery_via_extension.mjs`、`run_readonly_reference_probe_via_extension.mjs`、`verify_order_marker.mjs`。

## 可能产生写入的手工工具

以下文件不是生产自动入口。只有用户对本轮具体对象和动作明确授权后才可运行：

- `browser_order_add_submit_approved.mjs`；
- `run_lifecycle_fixture_via_platform.mjs`；
- `run_native_independent_update_baseline_via_extension.mjs`；
- `persist_extension_result_via_browser_session.mjs`（写平台任务结果，不应借此重放 ERP 动作）。

任何工具失败或写入状态不确定时，先对同一对象只读回查，禁止自动重试或换工具再次提交。