# Luban Generate Debug

> Diagnoses Luban generation and validation failures. Use when gen.bat fails, schema/data errors appear, or the user pastes Luban logs / --errorFormat json reports.

- Skill: `focus-creative-games/luban-generate-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add focus-creative-games/luban-generate-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/focus-creative-games/luban-generate-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: focus-creative-games (https://skillmd.com/u/focus-creative-games)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/focus-creative-games/luban-generate-debug

---


# Luban: 生成失败排查

## 优先动作

1. 用同一命令加 `--errorFormat json`，解析 `errors[]`。
2. 看 `category`：`schema` / `data` / `validation` / `codegen` / `cli`。
3. 有 `file` + `location` + `fieldPath` 时先修对应单元格/字段。

## 排查顺序

1. **CLI**：`--conf` 路径、`-t` 是否存在、`-c`/`-d` 是否匹配。
2. **Schema**：目标 group、表 value_type、继承关系。
3. **Data**：类型解析、枚举名、必填、分隔符。
4. **Validation**：`ref` / `range` / `path`（path 需 `pathValidator.rootDir`）。
5. **Codegen**：关键字冲突、非法标识符。

## 有用命令

```bash
# 只校验（推荐 Agent CLI）
dotnet Luban.Agent.dll validate --conf luban.conf -t all

# 或主 CLI
dotnet Luban.dll --conf luban.conf -t all -f --strict --errorFormat json -x outputSaver=null

# 导出 / 查询 schema
dotnet Luban.Agent.dll schema --conf luban.conf -t all
dotnet Luban.dll --conf luban.conf -t all -c schema-json -x outputCodeDir=./schema-out
```

## 常见坑

- 未登记 `__tables__`
- Sheet 无 `##` 头
- 引用 ID 不存在（`#ref=`）
- 输出目录被清掉了手写文件（目录选错）

## 原则

修好数据或按程序意图改 schema；禁止为通过生成而削弱校验（除非用户明确要求且说明风险）。