多维管理器
一个自包含的技能，为长时间运行的多维计算实验的状态带来秩序。你的计算插件负责数学运算；这个技能管理周围的混乱：迭代、快照、审计和回滚。
该技能仅负责编排。它本身从不计算结果——每个数字都来自你的插件。
何时使用
- 工作流在参数空间（维度的笛卡尔网格）上运行多轮，并且需要记录每轮的状态。
- 每轮在计算前后都需要对声明的关键文件进行快照。
- 必须为每轮提供完整的审计跟踪（参数、哈希、时间戳、状态）。
- 用户必须能够无损回滚到任意过去轮次。
- 典型场景：纵向研究、参数扫描，或调用外部求解器（Mathematica、GAP、SymPy、自定义脚本）的符号/数值扫描。
必需工作流
依赖引导（首次运行时）
在首次运行前，探测此技能的运行时依赖：
- 核心：纯标准库——无需安装。
- 可选：
PyYAML（仅当配置是.yaml文件时；JSON 配置仅用标准库即可工作）。
如果 PyYAML 缺失且用户的配置是 YAML，告知用户并询问是否要 pip install pyyaml；仅在用户确认后安装。未经明确同意，切勿安装到全局环境中。
每当用户要求运行、检查或恢复多维实验时，请按以下步骤操作。
- 加载配置。 读取实验配置（
config.example.yaml是模板）。确认存在param_space.dimensions、critical_paths和plugin.command。如果使用 YAML，则必须安装 PyYAML；否则使用 JSON。 - 空间展开。 枚举所有维度的笛卡尔积。在执行前向用户报告总轮次数。
- 优先进行预演。 运行
python scripts/run.py dryrun --config <cfg>，让用户看到完整计划（每个参数组合），无任何副作用。仅在用户确认后才继续执行。 - 执行扫描。 运行
python scripts/run.py run --config <cfg>。对于每轮，依次：之前快照声明的关键路径，调用插件，之后快照，并追加一条审计记录。 - 正确响应失败。 如果某轮的插件退出码非零，将其状态记录为（
failed/error）。当启用了auto_rollback时，将上一个成功轮次的后状态恢复到工作目录，以便后续轮次从干净状态开始；此恢复本身也会被审计。不要因单个组合失败就停止整个扫描。 - 生成摘要。 扫描完成后，技能会在输出目录下写入
results_summary.csv、results_summary.md、report_draft.md和run_metadata.json。告知用户这些文件的位置。 - 按需恢复。 要恢复到过去的轮次，运行
python scripts/run.py rollback --config <cfg> --round <N>。默认情况下，它会恢复到新目录；仅在用户明确想要覆盖当前工作目录时才添加--force。
硬约束
- 切勿自行计算结果。 所有领域数学都属于用户插件。该技能仅调用插件并记录合同结果。
- 仅快照声明的关键路径。 从不复制整个工作目录；内容按哈希地址存储，因此未更改的文件不会产生额外开销。
- 默认情况下回滚是无损的。 没有
--force时，当前工作目录不会被修改；恢复的状态会放置在一个新目录中。每次回滚（手动或自动）都会写入审计日志。 - 确定性是用户的承诺。 该技能保证编排是可重现的（相同参数 -> 相同的记录计划，相同的哈希）。它无法使非确定性的插件变得确定；请参阅限制。
使用示例
# 打印完整轮次计划，无任何副作用（始终先执行此操作）。
python scripts/run.py dryrun --config config.example.yaml
# 执行扫描。
python scripts/run.py run --config config.example.yaml
# 恢复到过去轮次（默认到新目录，除非使用 --force）。
python scripts/run.py rollback --config config.example.yaml --round 7
# 重新生成摘要，或验证一轮的结果。
python scripts/run.py summary --config config.example.yaml
python scripts/run.py verify --config config.example.yaml --round 7
插件合同
管理器每轮启动一个 shell 命令：
python your_plugin.py --params {PARAMS} --out {OUT}
{PARAMS}- 包含本轮参数组合的 JSON 文件路径。{OUT}- 插件必须将其结果 JSON 写入的路径。- 退出码：
0成功，1断言失败/检查失败，2错误或跳过。
任何外部求解器（Mathematica、GAP、Python LMM 脚本）都需要被包装以遵守此合同：读取参数文件并写入结果文件。该技能不关心计算的具体内容。
故障处理
- 插件退出码为
1的轮次标记为failed；退出码2标记为error。两者都会保留在审计日志中；扫描继续。 - 配置错误（缺少空间、YAML 格式错误、缺少
{OUT}）会在产生任何副作用之前中止，并打印清晰的消息（退出码 2）。 - 回滚到一个从未记录过或没有后快照的轮次，会失败并给出清晰的错误信息，而不是损坏状态。
限制
- 确定性仅存在于编排层。 管理器会记录哈希并为相同参数重放相同的计划，但无法强制插件是确定性的。如果插件访问网络、使用随机种子或读取系统时钟，则相同的输入可能产生不同的输出。请自行在插件中声明此类非确定性。
- 关键路径必须提前声明。 未在
critical_paths中列出的文件永远不会被快照，因此无法回滚。 - 黄金输出验证是 v0.2 版本。 当前验证器仅检查插件合同（退出码 0 + 结果文件存在）。与已知预期输出的比较功能已计划但尚未实现。
- YAML 配置需要 PyYAML。 JSON 配置仅使用标准库即可工作。