数据就绪预检

在打开框架簿或跑战斗模拟 / 多场景平衡之前做硬闸。

何时用

• 会读框架工作簿或走战斗模拟加载链
• 定档点到数值模拟 / 平衡 / 导表类事项

怎么做

1. 判定要不要闸

1. 本轮会打开框架簿或模拟加载链则本技能优先于平衡正文。
2. 工作根与产物路径来自 HARNESS_ROOT、.harness/state.json 与任务备注；产物写 .harness/artifacts/<工作项>/data-readiness.json。
3. 环境若已指定框架簿路径，预检须验证该文件存在。
4. 只改技能文案、不读表则可跳过，并在定档 why 写明。
5. 不合格则本轮生产性模拟不得继续。

2. 跑预检脚本

1. 运行 python ~/.cursor/hooks/数据就绪预检.py（可加 --root <数值工具或业务根>）。
2. HARNESS_ROOT = 业务根。框架簿优先读环境变量 FRAMEWORK_WORKBOOK / BATTLE_SIM_WORKBOOK，否则读正式面地图里 kind=excel 的官方根。需要核对的页签用 DATA_READY_SHEETS（逗号分隔），未设则只核文件在。
3. 执行预检：退出码 0 就绪，2 未就绪，1 脚本故障。
4. 打开 JSON：核对 ok、workbook、tried_paths、findings。
5. 缺 openpyxl 则先装依赖再重跑，不改业务工作簿。
6. 找不到脚本不得用目测文件代替。

3. 公式缓存

JSON 出现标准属性取值为空或公式未写出时：先跑约定的框架缓存刷新（Excel 全量计算并保存），关闭占用窗口后重跑预检。跳过取值校验的开关不算通过。预检 exit 2 则本轮不进入生产性 dry-run。

4. 解读 findings

1. 逐条执行 next_actions。
2. 缺簿：按 JSON tried_paths 核文件，仍无则补环境变量或配置。
3. 缺页：对照模拟配置的 sheet 常量，从正式簿同步，禁止空页占位。
4. 表头 / 标定行：与配置中的列名、曲线 id 对齐，不在本技能写死项目暗号。
5. 硬失败清单必须可指路径；修复落到配置、加载代码、框架簿或环境变量。

5. 再验与收口

1. 配置中的候选路径指向真实文件。
2. 重跑预检要求退出码 0 且 ok=true。
3. 通过后再跑约定 dry-run；日志进 artifacts。
4. 结案写清：修了什么、预检结果、dry-run 结果。未通过则指派补表 / 补路径 / 复跑。

注意

数据缺口一律硬失败。不清理无关仓。证据进 artifacts。