hypercross
9df6b9970a
Add check to the CLI guide, README, QWEN, and project structure: options, exit codes, diagnostic codes, and the checks not yet implemented. Mark compile as an unimplemented stub and fix stale element syntax in examples.
252 lines
6.6 KiB
Markdown
252 lines
6.6 KiB
Markdown
# 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-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） |
|
||
| `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 |
|
||
| `TTTK-R003` | error | `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 | 图片不存在 |
|
||
|
||
**尚未实现的校验：** CSV 数据校验（解析错误、列数不一致、`label` 重复、`{{prop}}` 引用无效列）、畸形属性块、`role=declare` 被跳过的行。
|
||
|
||
**实现说明：**
|
||
|
||
- 校验复用与应用相同的 `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]
|
||
|
||
<!-- 引用子目录的图片 -->
|
||
|
||
|
||
<!-- 引用上级目录的文件 -->
|
||
: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` 校验。
|