Communitygithub.com

AntTheLimey/gm-apprentice

将 gm-apprentice 战役库发布为托管在 GitHub Pages 或 Cloudflare Pages 上的静态网站,并运行桌面上变更请求循环,让玩家在游戏中请求角色表编辑。

gm-apprentice 是什么?

此技能将 Obsidian 格式的战役库内容转换为可供玩家分享的静态网站,支持 Cloudflare Pages(推荐)和 GitHub Pages。它引导 GM 完成完整的设置流程,包括预检检查、版本验证、网站搭建和部署。技能还提供自动化变更请求循环(能力 7),允许 GURPS 4e 和 CoC 7e 玩家在游戏过程中提交角色表编辑,GM 可以审查并应用这些更改。其他关键能力包括常规更新、故障排除、schema 迁移、内容过滤(隐藏 GM 笔记)、多网站管理以及实时状态栏/收件箱设置(仅限 Cloudflare)。该技能内置了完整的构建工具(gm-apprentice-publish),并提供了丰富的参考资料来处理配置、schema 和云平台设置。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AntTheLimey/gm-apprentice/tree/HEAD/skills/publish-site

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

发布网站

你将 gm-apprentice 库内容转换为可供 TTRPG GM 分享的静态网站,托管在 Cloudflare Pages(新设置推荐)或 GitHub Pages(完全支持)上。无论哪种方式,构建的网站完全相同;vault.config.json 中的 host 字段(cloudflare-pages 或 github-pages;缺失则默认为 github-pages)决定部署方式。

用简单易懂的语言引导 GM 完成设置、常规更新和故障排除。大多数 GM 不具备技术背景——解释 npm、git 或终端命令的作用,而不是假设他们知道。

版本检查: 首次调用时运行 python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <vault> version。OK/SETUP → 继续。MISMATCH → 宣布该行,运行 campaign-organizer 的 references/migration-procedure.md,然后继续。AHEAD → 宣布该行,告诉 GM 更新插件,停止。ERROR → 报告该行(插件安装损坏),停止。没有结果行且出现 not a directory 错误 → 询问 GM 正确的库路径。

构建工具

所有构建逻辑都位于 gm-apprentice-publish 工具中,该工具随此插件一起提供(切勿从 npm 注册表安装,也切勿复制其逻辑):

<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish

<plugin-version> 来自 .claude-plugin/plugin.json(或此技能自身的缓存路径)。一次性命令从缓存运行:

TOOL="<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish/bin/gm-publish.js"
node "$TOOL" init <target-dir>   # 搭建新网站(自动固定到此版本)
node "$TOOL" update-pin --site <dir>                       # 重新指向 + 对过时的网站执行 npm install(在插件外:添加 --tag publish-vX.Y.Z 以固定到发布 tarball)
node "$TOOL" manifest diff --config <dir>/vault.config.json    # 根据清单分类库文件
node "$TOOL" manifest apply --config <dir>/vault.config.json ...  # 编辑清单
node "$TOOL" manifest publish-played --config <dir>/vault.config.json  # 注册已进行的游戏会话
node "$TOOL" deploy --verify --config <dir>/vault.config.json  # 构建、部署、探测 URL
node "$TOOL" doctor --site --config <dir>/vault.config.json    # 审计库是否存在发布缺陷
node "$TOOL" explain "<vault-relative path>" --config <dir>/vault.config.json  # 单个文件的发布链
node "$TOOL" --version
node "$TOOL" --help

在此技能运行任何构建或部署之前,请自行运行 node "$TOOL" manifest publish-played --config <dir>/vault.config.json,这样网站就不会遗漏已进行的游戏会话(#277)。它仅在与将发布的链接 Wrap-Up 一起时标记已审阅的会话索引,因此网站会隐藏中心主体。它跳过 Excluded 条目,在玩家模式下没有清单则不执行任何操作。报告它标记的路径。其他每个已进行的游戏会话都会列为“不明确”,并附上原因(没有 Wrap-Up、Wrap-Up 尚未审阅、Excluded 或不会发布、过时的网站固定)。在一次提问中列出所有会话及其原因,询问 GM。对于没有 Wrap-Up 将发布的会话,说明其索引主体将按原样发布,并建议先框定任何隐藏笔记。使用 manifest publish-played --config <dir>/vault.config.json --session "<index>" 注册每个已批准的会话,如果它有 Wrap-Up(未审阅,或过时的固定:它仅免除审阅检查,因此转发它仍然给出的任何原因),则添加 --include-unreviewed;如果它没有 Wrap-Up,则使用 --publish-body。切勿使用 manifest apply 标记会话索引。不要静默标记它们;如果 GM 说“还没有”,则保留它们并且在此次运行中不再询问。当原因指出网站固定到更旧的工具时,首先提供 update-pin --site <dir>。构建本身对库是只读的,因此此操作位于技能中,而不是在 build/deploy 中。

在搭建的网站内,使用 npm 构建(它从搭建的 file: 固定中解析工具——无注册表,无网络):

npm install      # 链接固定的构建工具(依赖项随附供应商)
npm run build    # 从库生成 docs/
# 打印一位 PC 的角色表——需要 vault.config.json,因此在此运行它
npx gm-apprentice-publish sheet show --pc <name> [--player-safe] [--json]

需要 Node 22+;如果出现版本错误,请将 GM 发送到 https://nodejs.org (LTS)。

网站目录: 能力 2 和 4 从 _meta/vault-config.md 读取 publish.site_dir;相对值是相对于库的。如果未设置,询问网站仓库的绝对路径,并提供保存到那里的选项。如果完全没有网站,则没有要注册的内容,因此跳过 publish-played。

九项能力

1. 首次设置

(“发布我的战役”、“设置网站”、“我希望玩家看到我的战役”)

按照 references/setup-wizard.md 逐步操作——它是权威的(首先预检 doctor,Cloudflare 默认,从 publish.setup_progress 恢复)。不要即兴发挥或跳过步骤。

2. 常规更新

(“更新我的网站”、“重建”、“我已更新库”)

  1. 找到网站目录(如上)。
  2. node "$TOOL" update-pin --site <dir> —— 报告其输出的一行。
  3. node "$TOOL" manifest diff --config <dir>/vault.config.json。如果列出新增/删除的文件,展示它们;GM 确认后,node "$TOOL" manifest apply --config <dir>/vault.config.json --publish <path>... --exclude "<path>=<reason>"... --prune。将已进行的游戏会话索引排除在 --publish 之外:publish-played(如上)会注册它们。
  4. node "$TOOL" deploy --verify --config <dir>/vault.config.json —— 逐字转发其最后一行。如果退出码非零,则转到能力 3。缺少 Cloudflare 凭据会在 deploy 中内联解释;要直接设置它们,运行 node "$TOOL" doctor --set-cloudflare-creds。

3. 故障排除

(错误消息、“构建崩溃”、“图片不显示”、“页面缺失”、“链接损坏”)

首先运行 node "$TOOL" doctor --site --config <dir>/vault.config.json;对于单个缺失页面,运行 node "$TOOL" explain "<vault-relative path>"。然后使用 references/troubleshooting.md:指明失败模式,用简单语言解释原因,逐步指导修复,并提供应用修复的选项。

4. Schema 迁移

(“我添加了新实体类型”、“campaign-organizer 已更新”、“库中新增文件夹”、“更新后页面缺失”)

  1. 找到网站目录并读取其 vault.config.json。
  2. 将 folderMap 与库的文件夹进行比较;提出 folderMap / excludeDirs 补充项。
  3. 确认后应用,然后运行 npm run build 确认。
  4. 简要说明新类型的渲染方式(专用模板或智能 wiki 回退——参见 references/schema-reference.md)。

5. 多网站管理

(“我有两个战役”、“更新我所有的网站”)

在对话中跟踪每个网站仓库路径及其库路径,提供对所有网站循环执行常规更新的选项,并在每次推送前确认每个网站。

6. 内容过滤

(“仅发布玩家内容”、“隐藏 GM 笔记”、“玩家将看到什么”、“发布无剧透”)

阅读 references/content-filtering.md 中的“内容可见性模型”和“清单格式”。在 mode: player 模式下,文件仅作为 ## Publishing 下的 checked 条目发布——将其放在 ## Excluded 或 ## Needs Decision 下不会发布它;mode: full 忽略清单。

  1. 读取 _meta/vault-config.md。如果没有 publish: 部分,首先按照 content-filtering.md 中的“设置提问流程”(主题、图像、404)并编写初始配置。确认 mode 为 player——如果是 full,则停止并要求 GM 在构建清单之前更改它。
  2. 根据可见性模型对每个库文件进行分类,并编写 _meta/publish-manifest.md。
  3. 总结,然后引导 GM 处理有歧义的条目,在清单中记录每个决定(checked 在 ## Publishing 下,或移至 ## Excluded 并附上原因)。

后续发布通过能力 2 的清单差异来拾取新增和删除的文件。

7. 变更请求循环(桌面上)

(“开始你的检查循环”、“拾取变更请求”、“打开收件箱”、“监视角色表变更”)

按照 references/change-request-loop.md 操作——一个无人值守、自定进度的循环,应用干净的玩家角色表编辑(GURPS 4e 和 CoC 7e)并标记边界情况。

8. 实时状态栏设置(Tier 2a)/ 9. 桌面上收件箱设置(Tier 2b)

(“打开状态栏”、“让玩家实时更新 HP/FP” / “设置收件箱”、“让玩家提交变更”)

仅限 Cloudflare Pages。从网站目录运行 node "$TOOL" setup-status-bar 或 node "$TOOL" setup-inbox(如果不是 ./vault.config.json,则使用 --config <path>)。两者都是预检门控的、幂等的,并自行处理 KV——参见 references/cloudflare-pages.md 中的“快速方法”。setup-inbox 仅提供基础设施;桌面会话由能力 7 处理。

参考资料

  • references/configuration.md —— 所有设置。当两者都设置某些内容时,_meta/vault-config.md(过滤、主题)优先于 vault.config.json(路径、URL、显示)。
  • references/schema-reference.md —— 每种实体类型渲染哪些字段。
  • references/cloudflare-pages.md —— Cloudflare 令牌、凭据(doctor --set-cloudflare-creds)、首次部署、自定义域名。
  • references/github-pages.md —— 手动启用 GitHub Pages。两台主机可以从同一个 docs/ 并行运行。

配套技能

campaign-organizer 创建此技能读取的库结构——缺失页面或 schema 不匹配通常可以追溯到它。对于新内容,将 GM 发送到 ttrpg-expert,然后重建。在发布前进行一次 campaign-qa 检查,可以防止断开的链接出现在实时网站上。

版权

发布的网站是公开的。发布前,提醒 GM 库中已许可的 TTRPG 内容必须在其许可范围内使用(参见 gm-apprentice 仓库中的 ATTRIBUTION.md)。切勿将许可的规则文本放入生成的页面;如果库笔记包含逐字的规则文本,请标记它供 GM 改写。

相关技能