feat(tools): 新增execution-to-guide执行案转搭建指南工具

- execution_parser.py: 解析关卡执行案Markdown提取区域/结构体/布景/边界/光照
- asset_expander.py: BSP资产建议展开+绝对坐标计算+旋转推断
- guide_writer.py: 生成精确匹配build_guide_parser格式的搭建指南
- composite_writer.py: 组合资产清单+JSON模板生成
- converter.py: 主入口CLI工具
- 更新level-execution-template.md: 移除交互物/收集品章节,新增组合资产标记

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 00:44:46 +08:00
parent f86ffb511e
commit 6f8b599629
9 changed files with 2731 additions and 29 deletions
+52
View File
@@ -0,0 +1,52 @@
# execution-to-guide
关卡执行案 → 搭建指南 转换器。
将 `docs/design/关卡-vXX-<名称>-执行案.md` 自动转换为 `docs/technical/关卡-vXX-搭建指南.md`,供 `level-builder` 工具解析并在 UE5 中搭建白模关卡。
## 用法
```bash
# 基本用法(自动推断输出路径到 docs/technical/)
cd tools/execution-to-guide
python converter.py -i ../../docs/design/关卡-v01-城郊小街-执行案.md
# 指定输出路径
python converter.py -i ../../docs/design/关卡-v01-城郊小街-执行案.md -o ../../docs/technical/关卡-v01-搭建指南.md
# 详细日志
python converter.py -i <执行案.md> -v
```
## 依赖
- `tools/level-builder/config/` 下的 `asset_mapping.py`、`material_mapping.py`、`substitution_rules.py`
- `tools/level-builder/parsers/markdown_table.py`
工具会自动从上级 `level-builder` 目录加载这些依赖。
## 模块说明
| 文件 | 功能 |
|------|------|
| `converter.py` | 主入口,编排解析→展开→生成流程 |
| `execution_parser.py` | 解析执行案 Markdown,提取区域/结构体/布景/组合资产/边界/光照 |
| `asset_expander.py` | 将 BSP 资产建议字符串展开为 Actor 规格(坐标计算、旋转推断、资产映射) |
| `guide_writer.py` | 生成搭建指南 Markdown(匹配 `build_guide_parser.py` 的格式预期) |
| `composite_writer.py` | 生成组合资产清单 + JSON 模板(无直接 BSP 匹配的物件) |
## 数据流
```
关卡执行案 (.md)
│
▼
execution_parser.py → ExecutionPlanData
│
▼
asset_expander.py → list[ActorSpec] (展开 BSP 建议 + 坐标计算)
│
▼
guide_writer.py → 搭建指南 (.md) (精确匹配 build_guide_parser 格式)
composite_writer.py → 组合资产清单 (.md + .json)
```