ttrpg-tools/docs/cli.md

CLI 使用说明

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

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

安装

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

# 或全局安装
npm install -g tttk

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

命令

CLI 使用子命令组织：

serve - 预览模式

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

tttk serve [dir] -p 3000

参数：

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

选项：

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

功能：

• 扫描目录下的 .md、.csv、.yarn、.svg 文件（跳过以 . 开头的文件和 node_modules）
• 把内容目录挂在 URL 根路径下，文档 rules/combat.md 对应路由 /rules/combat
• 监听文件变化并重建内存中的内容注册表
• 提供 /__CONTENT_INDEX.json、/__CONTENT_REGISTRY.json、/__COMPLETIONS.json 等接口（见开发服务器特性）

示例：

# 预览当前目录
tttk serve

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

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

check - 校验模式

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

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 解析失败（YAML 非法或结构不符）
TTTK-R004	warning	role=declare 块没有声明任何变量或标签修饰符
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/ 目录。

示例：

# 校验当前目录
tttk check

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

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

compile - 编译模式（未实现）

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

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

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），引用会相对于当前文档所在目录解析：

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

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

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

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

开发服务器特性

内容接口

• /__CONTENT_INDEX.json — 原始文件索引（{ 路径: 文件内容 }）
• /__CONTENT_REGISTRY.json — 内容注册表（文件路径索引 + 文档内联内容）
• /__COMPLETIONS.json — 补全数据（骰点、链接、spark 表格、声明、标签修饰符）

内容目录与 URL 的对应关系

内容目录挂在 URL 根路径下，文档去掉 .md 扩展名后即为路由：

• 文档 rules/combat.md → http://localhost:3000/rules/combat
• 图片 rules/maps/city.png → http://localhost:3000/rules/maps/city.png

文件监听

服务器会监听内容目录的变化并重建内存中的注册表；重新加载页面即可看到最新内容。

SPA 路由

路由基于 History API（而非 hash）。直接访问深层链接或刷新页面时，未知路径会回退到 index.html， 因此浏览器前进/后退与深链接均可正常工作。

常见问题

端口被占用

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

check 报告了很多警告

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

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

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

compile 没有输出

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