# CLI 使用说明

TTTK 提供一个 CLI 工具，用于预览和校验目录内的 TTRPG 文档。

> 将内容编译为 HTML 的 `compile` 命令尚未实现（见下方说明）。

## 安装

```bash
# 无需安装，直接运行
npx tttk serve ./content

# 或全局安装
npm install -g tttk
```

安装完成后，可在任意目录使用 `tttk` 命令。

## 命令

CLI 使用子命令组织：

### serve - 预览模式

运行一个 Web 服务器预览目录中的内容，并实时监听文件更新。

```bash
tttk serve [dir] -p 3000
```

**参数：**

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `[dir]` | 要预览的目录 | `.` (当前目录) |

**选项：**

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-p, --port <port>` | 端口号 | `3000` |
| `-h, --host <host>` | 主机地址 | `0.0.0.0` |

**功能：**

- 扫描目录下的所有 `.md`、`.csv`、`.yarn` 文件
- 为每个文件创建路由
- 提供实时文件监听，修改后自动刷新
- 通过 `/__CONTENT_INDEX.json` 提供文件索引

**示例：**

```bash
# 预览当前目录
tttk serve

# 预览指定目录
tttk serve ./my-ttrpg-content

# 指定端口
tttk serve ./docs -p 8080
```

### check - 校验模式

静态校验目录内的 tttk 文档，输出结构化诊断（文件、行号、代码），存在错误时以退出码 `1` 结束。

```bash
tttk check [dir] --json
```

`lint` 是 `check` 的别名。

**参数：**

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `[dir]` | 要校验的目录 | `.` (当前目录) |

**选项：**

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--json` | 以 JSON 输出诊断 | `false` |
| `--strict` | 将警告视为错误 | `false` |
| `--quiet` | 只报告错误 | `false` |

**退出码：**

| 代码 | 含义 |
|------|------|
| `0` | 无错误（`--strict` 下存在警告也会失败） |
| `1` | 存在错误（或 `--strict` 下存在警告） |
| `2` | 用法 / IO 错误（例如目录不存在） |

**输出示例：**

```
content/adventures/hollow-mill/adventure.md
  12:1   error   TTTK-C001  :md-table reference "./npcs.csv" does not resolve
                           hint: expected a file relative to this document, or an inline id defined in it
  40:8   warning TTTK-R002  spark-table first header "Name" is not a dice formula

2 errors, 1 warning
12 files checked
```

**诊断代码：**

| 代码 | 级别 | 说明 |
|------|------|------|
| `TTTK-S001` | error | Markdown 解析失败 |
| `TTTK-S002` | error | 容器指令 `:::` 未闭合 |
| `TTTK-D001` | error | 未知的 `:md-*` 元素名 |
| `TTTK-D002` | error | 属性块畸形（例如未加引号的值中含空格） |
| `TTTK-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） |
| `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 |
| `TTTK-R003` | error | `role=declare` 解析失败（缺少 `key`/`expr` 等） |
| `TTTK-R004` | warning | `role=declare` 中 `key`/`expr` 为空的行被跳过 |
| `TTTK-R005` | error | `role=tag` 的 YAML 无法解析 |
| `TTTK-R006` | error | `role=tag` 缺少 `tag:` 或元素未知 |
| `TTTK-C001` | error | 内容引用无法解析（文件不存在，或内联 id 未定义） |
| `TTTK-C002` | warning | 引用解析到的文件类型不符合预期 |
| `TTTK-C003` | info | 同一文档中重复引用同一 CSV |
| `TTTK-C004` | error | `:md-embed` 循环引用 |
| `TTTK-L001` | error | 链接目标文件不存在 |
| `TTTK-L002` | warning | `#锚点` 未匹配到任何标题 |
| `TTTK-A001` | warning | 图标在 `assets/` 中不存在 |
| `TTTK-A002` | warning | 图片不存在 |
| `TTTK-V001` | error | CSV 解析失败（引号未闭合等） |
| `TTTK-V002` | warning | 行的列数与表头不一致 |
| `TTTK-V003` | warning | `label` 值重复 |
| `TTTK-V004` | warning | `body` 中的 `{{prop}}` 不是列名或 front-matter 键 |
| `TTTK-V005` | warning | spark-table 行的骰点值不是数字或范围 |

完整的语法目录（元素、属性、代码块角色）由 `src/cli/validate/known.ts` 生成到 `docs/reference.md`，可用 `npm run gen:reference` 重新生成。

**实现说明：**

- 校验复用与应用相同的 `scanDoc` 与内容注册表，因此通过校验意味着应用也能解析。
- 定位基于**原始文件**（行号准确），围栏代码块与行内代码中的示例语句会被跳过。
- 图标校验假设校验根目录之上不存在 `assets/` 目录。

**示例：**

```bash
# 校验当前目录
tttk check

# 校验指定目录并输出 JSON
tttk check ./content --json

# CI：只关注错误
npx tttk check ./content --quiet
```

### compile - 编译模式（未实现）

> **存根命令。** `compile` 目前不会产生任何输出，`--help` 中也已标明。
> 请使用 `tttk serve` 预览内容、`tttk check` 校验内容。

原计划的用法如下（仅供参考，尚未实现）：

```bash
tttk compile [dir] -o ./dist/output
```

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `[dir]` | 要编译的目录 | `.` (当前目录) |

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-o, --output <dir>` | 输出目录 | `./dist/output` |

## 输入文件

CLI 会搜索目录下的以下文件：

- `.md` - Markdown 文档
- `.csv` - 表格数据
- `.yarn` - Yarn Spinner 叙事文件
- `.svg` - 矢量图标

### 文件组织建议

```
my-ttrpg-content/
├── index.md              # 首页
├── rules/
│   ├── index.md          # 规则首页
│   ├── combat.md         # 战斗规则
│   └── magic.md          # 魔法系统
├── characters/
│   ├── index.md
│   └── npc-list.csv      # NPC 列表
└── assets/
    ├── images/           # 图片资源
    └── icons/            # 图标资源
```

### 相对路径引用

若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），引用会相对于当前文档所在目录解析：

```markdown
<!-- 引用同目录下的 CSV -->
:md-table[./sparks.csv]

<!-- 引用子目录的图片 -->
![地图](./maps/city-map.png)

<!-- 引用上级目录的文件 -->
:md-deck[../data/cards.csv]
```

使用 `tttk check` 可以校验这些引用是否都能解析。

## 开发服务器特性

### 实时索引

访问 `http://localhost:3000/__CONTENT_INDEX.json` 可获取当前内容目录的文件索引。

### 自动刷新

文件变化时，服务器会自动重新加载内容，无需手动刷新页面。

### SPA 路由

使用 hash 路由支持单页应用导航：

- `/content/rules/combat.md` → `#/content/rules/combat.md`
- 支持浏览器前进/后退

## 常见问题

### 端口被占用

```bash
# 使用其他端口
tttk serve -p 8080
```

### check 报告了很多警告

先用 `--quiet` 只看错误，或在 CI 中配合 `--strict`：

```bash
tttk check ./content --quiet
tttk check ./content --json
```

警告通常确有其事（例如锚点或图标不存在），建议逐条确认。

### compile 没有输出

`compile` 目前是未实现的存根命令，不会产生任何输出。请使用 `tttk serve` 预览，使用 `tttk check` 校验。