模组 CLI · TARP

模组 CLI 使用与桌面应用相同的加载和校验逻辑，不修改模组，不创建存档。独立 CLI 支持 Node.js 22.12.0 或更新版本，也支持 Bun；两者运行同一份 JavaScript 产物；单独校验不需要桌面运行时、桌面构建或个人应用配置。

获取命令入口

模组开发优先复用已有的 tarp 命令或已构建的 JavaScript 入口。编程助手不因本地已有平台源码就自动安装依赖或构建 CLI；没有可用入口时，说明校验尚未完成。下文的 tarp module … 在已准备好的源码环境中对应 bun run cli module …，不要把两种写法拼在一起。

独立包名为 @jointarp/module-cli，命令名为 tarp。公开包发布到 npm 后，可以安装并确认实际版本：

npm install -g @jointarp/module-cli
tarp --version
tarp --help

只安装 Bun 时，可以直接执行：

bunx --bun @jointarp/module-cli --version
bunx --bun @jointarp/module-cli module validate "./小河渡口" --json

需要复现指定版本时，在包名后加版本号，例如 bunx --bun @jointarp/[email protected] --version。包是否可用以 npm 的实际发布状态为准；若提示找不到包或版本，使用提供的 tgz 或已有构建入口，不要改装同名的其他包。

拿到发布或打包后的 tgz 时，也可以从本地安装：

npm install -g ./tarp-module-cli.tgz
tarp --version
tarp --help

安装包包含构建后的 JavaScript，YAML、Zod 和 smol-toml 等运行依赖由包管理器在安装时提供，无需安装源码仓库的开发依赖。tarp 命令默认通过 Node.js 启动；Bun 使用上面的 bunx --bun 入口，或显式运行 bun <安装目录>/index.js。桌面预览仍需要另外安装 TARP，并按下文配置 TARP_DESKTOP。

开发者需要自行构建 CLI 时，在源码仓库根目录执行：

bun install --frozen-lockfile
bun run --filter @jointarp/module-cli build
bun run cli --version
bun run cli module validate "<模组目录>" --json

源码构建需要 Bun 1.4.0 或更新版本，准备步骤见源码仓库 README。也可运行 node packages/module-cli/out/index.js module validate "<模组目录>" --json，或将开头的 node 换为 bun。这属于 CLI 获取方式，不是模组创作的默认步骤；已有可用入口时直接使用。模组路径始终相对于命令执行目录解析。

校验

tarp module validate "./小河渡口"
tarp module validate "./小河渡口" --json

沿用最小模组时，应看到“校验通过”、2 种文档类型、2 份文档和 0 个阅读页。失败时先看问题中的文件路径，再修正对应字段或引用，重新运行同一条命令。

校验范围包括模组元配置、文档类型和布局、字段值、引用目标、计算表达式、阅读页、序章、开局和建卡。CLI 与桌面端创建冒险时使用相同的初始状态校验，支持同类型或不同类型的多份 world_state 文档；玩法状态只按模组声明的字段类型、引用和计算规则检查，不预设场景归属或回合规则。路径含空格时加引号；校验目录应包含 module.toml 或 module.json，不要指向它的上级项目目录。

--json 输出包含 schemaVersion、appVersion、status、path、可选名称、文档类型数量、文档数量、阅读页数量与 issues。问题包含 kind、path、message。appVersion 是执行入口版本，独立 CLI 报自身版本，桌面命令入口报应用版本。

退出码	含义
`0`	校验或操作成功
`1`	模组校验或操作失败
`2`	命令参数错误

编程助手或自动检查应结合退出码和结构化结果判断，不依赖中文提示的固定措辞。参数错误的 JSON 是 status: "error" 与 message，不一定包含完整校验统计或 issues。

按风险检查实际结果

validate 会执行公式并检查合法性，但输出不是各字段的求值快照，也不判断结果是否符合本模组规则。公式即使合法，也可能算出不符合规则的数值。只改变输入后重复运行 CLI，不能代替对实际结果的核对。

简单文案、路径或已确认数值的修正，沿用 CLI 和相关检查即可。重要公式、揭露条件或状态机制变化时，根据已有能力选择验证层次：

层次	实际验证方式	不能据此声称的结果
配置校验	对真实模组运行 CLI，检查退出码与问题	数值平衡、视觉效果和主持执行已经正确
公式与展示结果	有当前版本的实际加载器或计算器时，读取真实类型与文档，对选定输入求值并核对预期	状态写入、存档恢复和多人操作已经通过
已有模组测试	模组仓库已提供相应测试入口时，按既有命令检查该模组的行为与数据；测试使用隔离数据	AI 主持必然会按规则操作，或实际游玩已验收
MCP 临时局预演	通过客户端 MCP准备指定局面，驱动真实队友与主持并核对状态	跳过的开局、完整路线、界面和声音已经验收

结果检查在临时副本或既有测试的隔离数据中进行，不改变交付模组的初始值和玩家存档。优先运行模组仓库已有的结果检查入口；环境已有实际加载器或计算结果接口时也可复用。没有相应入口不要求安装 TARP 源码、搭建运行时或开发平台测试，也不另写一套求值器或更新逻辑再测试它自己。独立 CLI 只有当前帮助列出的能力，不虚构快照、模拟或测试子命令。

先按规则写出输入与预期，再执行真实实现并比较。以本指南的生命上限示例为例：

真实输入	应核对的结果
`CON = 50`、`SIZ = 60`、`hp = 8`	`max_hp = 11`，当前生命值仍为 8
将 `CON` 改为 70	`max_hp = 13`，不会自动治疗当前生命值
仅把展示标签改名，保留字段键	计算结果不变

根据本次改动的风险，选择少量能发现问题的情况：初始状态、关键变化、数值边界、未发现与已发现、文档公式例外及相关引用变化。修改字段名时也检查结果，防止缺失值回退到 0 仍被当作合法。预期值来自规则依据，不直接复制待测公式作为“正确答案”。

本次规则涉及的状态保存和开局初始化，只有已有模组测试或 MCP 临时局实际执行了相应平台行为，才算验证过；在副本中手改出一个结果只算输入准备或状态推演。没有对应入口时，将这些情形列入开发者手动验收清单，编程助手不为验证模组而调用真实冒险的主持工具。已有测试执行失败时，应报告具体问题，不能说成没有测试入口。

交付时区分配置校验、实际结果检查、状态推演、MCP 临时局预演和开发者手动验收，说明所用入口、关键输入与预期、实际结果及未验证项。编程助手提供新建冒险、界面、声音和真实游玩的验收步骤，由开发者执行，详情见模组设计。

桌面预览

tarp module preview "./小河渡口"

预览成功后，桌面应用应打开“小河渡口”的文档列表。

预览先检查元配置和类型定义能否读取，再用桌面应用打开目录。个别内容文档有校验错误时仍可预览并查看问题，不复制到模组库，不创建冒险。桌面已运行时复用窗口，外部修改后再次调用可以重新载入。

使用安装后的桌面应用，需要将 TARP_DESKTOP 设置为可执行文件路径。macOS 示例：

TARP_DESKTOP=/Applications/TARP.app/Contents/MacOS/launcher tarp module preview "./小河渡口"

Windows 和 Linux 同样指定已安装应用的可执行文件，值中不填 shell 命令或额外参数。源码环境未设置此变量时会尝试仓库内已构建的 Electrobun 桌面应用。preview 不支持 --json。

预览用于检查文档、布局和引用；正式验收序章与开局、建卡、状态时，由开发者手动将模组导入应用并新建测试冒险。已有冒险继续使用自己的模组副本。