Communitygithub.com

AntTheLimey/gm-apprentice

將 gm-apprentice 戰役寶庫發佈為靜態網站(支援 GitHub Pages 或 Cloudflare Pages),並執行遊戲桌前的變更請求循環,讓玩家在遊玩時申請角色表編輯。

gm-apprentice 是什麼?

此技能專為 TTRPG 主持人設計,能將 gm-apprentice 寶庫內容轉換為可分享的靜態網站,託管於 Cloudflare Pages(新設置建議)或 GitHub Pages(完整支援)。它涵蓋從初次設置、常規更新、故障排除、架構遷移到多站點管理的完整工作流程。技能也包含遊戲中的變更請求循環,讓玩家在遊玩期間能申請角色表修改(支援 GURPS 4e 和 CoC 7e)。其建置工具 `gm-apprentice-publish` 隨外掛一起提供,無需從 npm registry 安裝。技能會自動處理版本檢查、播放會話註冊,並有詳細的參考文檔處理內容過濾(如隱藏主持人筆記)、Cloudflare KV 設置和自訂網域。發佈前,技能會提醒使用者確保授權 TTRPG 規則文字不直接出現在頁面上。

相容平台✓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 主持人使用,託管於 Cloudflare Pages(新設置建議) 或 GitHub Pages(完整支援)。建置完成的網站無論選擇哪種託管方式都完全相同; vault.config.json 中的 host 設定(cloudflare-pages 或 github-pages;若無此設定則預設為 github-pages)決定部署方式。

以淺顯的語言引導主持人完成設置、例行更新和故障排除。 大多數使用者並非技術背景——請解釋 npm、git 或終端機指令的用途,而不是假設他們已經知道。

版本檢查: 首次調用時執行 python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <vault> version。 OK/SETUP → 繼續。MISMATCH → 宣布該行,執行 campaign-organizer 的 references/migration-procedure.md,然後繼續。AHEAD → 宣布該行,告訴主持人更新外掛,停止。ERROR → 回報該行(外掛安裝損壞),停止。若沒有 verdict 行且出現 not a directory 錯誤 → 詢問主持人正確的寶庫路徑。

建置工具

所有建置邏輯都位於 gm-apprentice-publish 工具中,此工具隨此外掛一起提供(切勿從 npm registry 安裝,也切勿複製其邏輯):

<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    # 將寶庫檔案與 manifest 進行比對分類
node "$TOOL" manifest apply --config <dir>/vault.config.json ...  # 編輯 manifest
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 條目,若無 manifest 且處於 player 模式則不執行任何動作。回報它標記了哪些路徑。其他每個已進行的場次都會列出為「不明確」,並附上原因(沒有 Wrap-Up、Wrap-Up 尚未審查、被 Excluded 或不會發佈,或是網站固定到過時版本)。一次向主持人提問,只問一個問題,列出所有場次及其原因。對於沒有將要發佈的 Wrap-Up 的場次,告知其索引主體將按原樣發佈,並建議先將任何主持人筆記用 fence 包圍。為每個主持人確認的場次,使用 manifest publish-played --config <dir>/vault.config.json --session "<index>" 註冊,加上 --include-unreviewed(當它有 Wrap-Up,但未審查或固定到過時版本:這僅免除審查檢查,因此要轉達它仍然給出的任何原因)或 --publish-body(當它沒有 Wrap-Up)。切勿使用 manifest apply 標記場次索引。不要默默標記它們;如果主持人說「還不要」,則離開它們,並在此次運行中不再詢問。當原因指出網站固定到較舊的工具時,先提供 update-pin --site <dir>。建置本身對寶庫是唯讀的,因此此邏輯存在於技能中,而不是 build/deploy 中。

在已建立的網站內部,使用 npm 建置(它從 scaffold 的 file: 固定解析工具——無需 registry,無需網路):

npm install      # 連結固定的建置工具(依賴項已打包隨附)
npm run build    # 從寶庫生成 docs/ 目錄
# 列印一位玩家的角色表——需要 vault.config.json,因此在此處執行
npx gm-apprentice-publish sheet show --pc <name> [--player-safe] [--json]

需要 Node 22+;若出現版本錯誤,請引導主持人前往 https://nodejs.org(LTS)。

網站目錄: 能力 2 和 4 會從 _meta/vault-config.md 讀取 publish.site_dir;相對值相對於寶庫目錄。若未設定,詢問網站倉庫的絕對路徑,並提供將其儲存在該處的選項。如果完全沒有網站,則沒有什麼可註冊的,因此跳過 publish-played。

九項能力

1. 初次設置

(「發佈我的戰役」、「設置網站」、「我希望玩家看到我的戰役」)

按步驟遵循 references/setup-wizard.md——這是權威指南(先執行 preflight doctor,預設使用 Cloudflare,從 publish.setup_progress 繼續)。不要自行發揮或跳過步驟。

2. 例行更新

(「更新我的網站」、「重建」、「我已更新寶庫」)

  1. 找到網站目錄(如上所述)。
  2. node "$TOOL" update-pin --site <dir> — 回報其輸出的單一行。
  3. node "$TOOL" manifest diff --config <dir>/vault.config.json。 如果列出新增/移除的檔案,請呈現它們;主持人確認後,執行 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. 架構遷移

(「我新增了一個實體類型」、「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 § 內容可見性模型 和 § Manifest 格式。在 mode: player 下,檔案僅在 ## Publishing 下作為已勾選的條目發佈——在 ## Excluded 或 ## Needs Decision 下勾選它並不會發佈;mode: full 則忽略 manifest。

  1. 讀取 _meta/vault-config.md。如果沒有 publish: 部分,首先遵循 content-filtering.md § 設置提問流程(主題、圖片、404)並撰寫初始配置。確認 mode 為 player——如果為 full,則停止並要求主持人在建置 manifest 前先更改。
  2. 根據可見性模型對每個寶庫檔案進行分類,並寫入 _meta/publish-manifest.md。
  3. 總結,然後引導主持人逐一檢視模糊不清的項目,並將每個決定記錄在 manifest 中(在 ## Publishing 下勾選,或移至 ## Excluded 並附上原因)。

後續的發佈會透過能力 2 的 manifest diff 功能來處理新增和移除的檔案。

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>)。兩者都有 preflight 檢查、具冪等性,且自行處理 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 建立此技能讀取的寶庫結構——頁面缺失或架構不符通常可以追溯到它。對於新內容,請將主持人引導至 ttrpg-expert,然後重建。在發佈前進行一次 campaign-qa 檢查,可以防止損壞的連結出現在線上網站。

版權

發佈的網站是公開的。在發佈前,提醒主持人寶庫中的授權 TTRPG 內容必須在其授權範圍內使用(參見 gm-apprentice 倉庫中的 ATTRIBUTION.md)。切勿將授權的規則文字放入生成的頁面;如果寶庫筆記包含逐字的規則文字,請標記出來,讓主持人用自己的話改寫。

相關技能