發佈網站
你將 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. 例行更新
(「更新我的網站」、「重建」、「我已更新寶庫」)
- 找到網站目錄(如上所述)。
node "$TOOL" update-pin --site <dir>— 回報其輸出的單一行。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(上述)會註冊它們。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 已更新」、「寶庫中有新資料夾」、「更新後頁面缺失」)
- 找到網站目錄並讀取其
vault.config.json。 - 將
folderMap與寶庫的資料夾進行比較;提出folderMap/excludeDirs的新增建議。 - 主持人確認後套用,然後執行
npm run build以確認。 - 簡要說明新類型的呈現方式(專用模板或智慧型 wiki 回退——參見
references/schema-reference.md)。
5. 多站點管理
(「我有兩個戰役」、「更新我所有的網站」)
在對話中追蹤每個網站倉庫路徑及其寶庫路徑,提議對所有網站進行例行更新循環,並在推送前逐一確認每個網站。
6. 內容過濾
(「僅發佈玩家內容」、「隱藏 GM 筆記」、「玩家會看到什麼」、「發佈時不含劇透」)
閱讀 references/content-filtering.md § 內容可見性模型 和 § Manifest 格式。在 mode: player 下,檔案僅在 ## Publishing 下作為已勾選的條目發佈——在 ## Excluded 或 ## Needs Decision 下勾選它並不會發佈;mode: full 則忽略 manifest。
- 讀取
_meta/vault-config.md。如果沒有publish:部分,首先遵循 content-filtering.md § 設置提問流程(主題、圖片、404)並撰寫初始配置。確認mode為player——如果為full,則停止並要求主持人在建置 manifest 前先更改。 - 根據可見性模型對每個寶庫檔案進行分類,並寫入
_meta/publish-manifest.md。 - 總結,然後引導主持人逐一檢視模糊不清的項目,並將每個決定記錄在 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)。切勿將授權的規則文字放入生成的頁面;如果寶庫筆記包含逐字的規則文字,請標記出來,讓主持人用自己的話改寫。