AI Skills
story-setup

story-setup

熱門

網路小說寫作工具集基礎架構部署。為 Claude Code / OpenCode / Codex / OpenClaw 提供內建適配；Web AI / 通用 Agent 可採用 skills + AGENTS.md 檔案模式。觸發方式：/story-setup、$story-setup、「準備寫書」、「幫我搭建環境」、「設定寫作專案」。

4101星標
641分支
更新於 2026/7/14
獲取技能源代碼

相關技能

plan-canvas24萬homelab-vlan-segmentation24萬workflow-automation7萬
SKILL.md
唯讀
名稱
story-setup
描述

網路小說寫作工具集基礎架構部署。為 Claude Code / OpenCode / Codex / OpenClaw 提供內建適配；Web AI / 通用 Agent 可採用 skills + AGENTS.md 檔案模式。觸發方式：/story-setup、$story-setup、「準備寫書」、「幫我搭建環境」、「設定寫作專案」。

版本
1.2.5

story-setup：網路小說寫作工具集基礎架構部署

你是寫作基礎架構部署器。將網路小說寫作工具集部署到使用者專案目錄：已適配的 CLI 走專用 hooks/agents/config；NarraFork、Web AI、自訂 Agent 等環境採用通用檔案模式。

執行鐵律：不覆蓋使用者已有設定，進行合併而非替換。

Phase 1：檢測專案狀態

  1. 檢查目前目錄是否已部署過（存在 .story-deployed）
    • 如果已存在 → 使用 AskUserQuestion 確認是否重新部署
  2. 檢查是否有書名目錄（包含 追蹤/ 子目錄的目錄，或使用者自訂結構）
    • 有 → 識別為長篇專案，顯示目前專案資訊
    • 無 → 識別為新專案或短篇專案
  3. 檢查 .claude/settings.local.json 是否存在
    • 存在 → 讀取現有設定，後續進行合併
    • 不存在 → 後續建立新檔案
  4. 檢查 .active-book 檔案是否存在
    • 存在 → 顯示目前活躍書目
    • 不存在 → 跳過
  5. 檢查 opencode.json 或 .opencode/ 是否存在
    • 存在 → 識別為 opencode 專案，target_cli = opencode
    • 不存在 → 跳過
  6. 檢查 .codex/、.codex/config.toml、.codex/agents/、.codex/hooks.json、AGENTS.md 中的 Codex 區段
    • 存在 → 識別為 Codex 專案，target_cli = codex
    • 不存在 → 跳過
  7. 檢查 openclaw.json、.openclaw/、.agents/skills/、AGENTS.md 中的 OpenClaw 區段，或 skills/*/SKILL.md 中的 metadata.openclaw
    • 存在 → 識別為 OpenClaw 專案，target_cli = openclaw
    • 不存在 → 跳過
  8. 若 .claude/ 或 CLAUDE.md、opencode 標記、Codex 標記、OpenClaw 標記同時存在 → 使用 AskUserQuestion 讓使用者選擇目標環境（選項：Claude Code / OpenCode / Codex / OpenClaw / 通用 Web AI 或其他 Agent / 任意組合）
  9. 若四類內建 CLI 標記都不存在（全新專案或 Web AI 專案）→ 使用 AskUserQuestion 讓使用者選擇目標環境
    • 使用者選擇 opencode → target_cli = opencode，部署時建立 opencode.json 與 .opencode/
    • 使用者選擇 claude-code → 按現有邏輯處理
    • 使用者選擇 codex → target_cli = codex，部署時建立 .codex/
    • 使用者選擇 openclaw → target_cli = openclaw，部署時複製 OpenClaw 相容 skills 到專案 skills/
    • 使用者選擇通用 Web AI / 其他 Agent → target_cli = generic，部署通用 AGENTS.md 與專案本地 skills/；不寫入平台專屬 hooks/agents
    • 使用者選擇多端 → target_cli = claude-code,opencode,codex,openclaw,generic 的子集（僅包含使用者選擇的端）

Phase 2：部署基礎架構

使用 AskUserQuestion 確認部署位置後，依序執行。

2.0 部署清單（可機械化檢查）

Source path Target path Owner class Merge mode Validation check
skills/story-setup/references/templates/CLAUDE.md.tmpl CLAUDE.md user+managed marker/section merge contains story skill routing sections
skills/story-setup/references/templates/hooks/ .claude/hooks/ story-setup managed recursive replace session-*.sh, detect-story-gaps.sh, validate-story-commit.sh, guard-outline-before-prose.sh, check-prose-after-write.sh, lib/common.sh, lib/sentinel.sh exist
skills/story-setup/references/templates/rules/*.md .claude/rules/*.md story-setup managed replace every rule contains paths frontmatter
skills/story-setup/references/templates/agents/*.md .claude/agents/*.md story-setup managed replace 7 agent files exist
skills/story-setup/references/agent-references/*.md .claude/skills/story-setup/references/agent-references/*.md story-setup managed replace every story-setup/references/agent-references/*.md reference resolves
skills/story-setup/references/templates/settings-hooks.json .claude/settings.local.json user+managed merge by hook command hook JSON valid and registered commands deduped
skills/story-setup/references/templates/上下文.md.tmpl {書名}/追蹤/上下文.md user state create only if absent never overwrite existing writing context
generated sentinel .story-deployed story-setup managed replace contains agents_version, setup_skill_version, target_cli, resolver_strategy, references_dir
skills/story-setup/references/opencode/AGENTS.md.tmpl AGENTS.md user+managed marker/section merge contains story skill routing sections
skills/story-setup/references/opencode/agents/ .opencode/agents/ story-setup managed replace 7 agent files exist（replace 前按 2.4.4 Step 0 快取現有 model:，避免覆蓋使用者已配模型）
skills/story-setup/references/opencode/plugin.ts .opencode/plugins/story-hooks.ts story-setup managed replace TypeScript plugin file exists
skills/story-setup/references/opencode/commands/ .opencode/commands/ story-setup managed replace 13 command files exist
skills/story-setup/references/opencode/opencode.json.patch merge into opencode.json user+managed merge by plugin/permission key plugin entry registered
skills/story-setup/references/agent-references/ skills/story-setup/references/agent-references/ story-setup managed replace every reference resolves
skills/story-setup/references/opencode/pre-commit.sh .git/hooks/pre-commit user+managed append or create file exists and is executable；含 marker 區塊則替換區塊內容，不含則檢測 exit 0 位置智慧插入
skills/story-setup/references/codex/AGENTS.md.tmpl AGENTS.md user+managed marker/section merge contains Codex story skill routing sections
skills/story-setup/references/codex/agents/ .codex/agents/ story-setup managed replace 7 TOML agent files parse and contain name/description/developer_instructions
skills/story-setup/references/codex/hooks/hooks.json .codex/hooks.json user+managed merge by event+command hook JSON valid; commands deduped
skills/story-setup/references/codex/hooks/story_codex_hook.py .codex/hooks/story_codex_hook.py story-setup managed replace Python syntax valid
skills/story-setup/references/agent-references/ .codex/skills/story-setup/references/agent-references/ story-setup managed replace every reference resolves
skills/story-setup/references/openclaw/AGENTS.md.tmpl AGENTS.md user+managed marker/section merge contains OpenClaw story skill routing sections
skills/story-setup/references/generic/AGENTS.md.tmpl AGENTS.md user+managed marker/section merge contains generic story skill routing sections
repository skills/{browser-cdp,story*}/ skills/{browser-cdp,story*}/ story-setup managed for known skill names replace known skill dirs only 13 SKILL.md files exist; OpenClaw-compatible frontmatter
skills/story-setup/references/agent-references/ skills/story-setup/references/agent-references/ story-setup managed replace via full skill copy every reference resolves

opencode.json 合併演算法

部署 opencode.json.patch 時按以下規則合併：

  1. 讀取現有 opencode.json（若存在），解析 JSON
  2. 合併 plugin 陣列：將 ./.opencode/plugins/story-hooks.ts 加入陣列，進行去重
  3. 保留使用者已有的其他設定欄位（permission、model、provider 等），不進行覆蓋
  4. 寫入合併後的 opencode.json

2.1 部署 CLAUDE.md

  • 讀取 skills/story-setup/references/templates/CLAUDE.md.tmpl
  • 替換佔位符（見下方「範本佔位符」段落）
  • 寫入專案根目錄 CLAUDE.md（若已存在，按「CLAUDE.md 合併策略」處理）

2.2 部署 Hooks

  • 遞迴複製完整目錄樹：將 skills/story-setup/references/templates/hooks/ 複製到使用者專案 .claude/hooks/
  • 必須保留子目錄 lib/，其中：
    • lib/common.sh 提供 project_root、discover_active_book、discover_all_books
    • lib/sentinel.sh 提供 .story-deployed 欄位讀取
  • 只需對 .claude/hooks/*.sh 設定執行權限（chmod +x）；lib/*.sh 由 hook source，不要求可執行權限位元

2.3 部署 Rules

  • 讀取 skills/story-setup/references/templates/rules/ 下所有 .md 檔案
  • 複製到使用者專案的 .claude/rules/ 目錄

2.4 部署 Agents

  • 讀取 skills/story-setup/references/templates/agents/ 下所有 .md 檔案
  • 複製到使用者專案的 .claude/agents/ 目錄
  • Agent 檔案屬於 story-setup 管理檔案，可安全覆蓋；版本升級時按 UPGRADING.md 的版本檢測結果重新部署
  • 部署後必須開啟新會話：agent 只在會話啟動時註冊；原因與必須輸出的報告文案見 Phase 3 第 6 步。

2.4.1 Agent 相容性處理

  • Agent frontmatter 以 Claude Code 為主；OpenCode 由 scripts/sync-opencode.py 產生 .opencode/agents/*.md；Codex 由 scripts/generate-codex-agents.py 產生 .codex/agents/*.toml。
  • OpenClaw Phase 1 不部署 agents：OpenClaw 只部署 skills，agent 協作相關 skill 必須按既有 fallback 規則降級 solo/direct，不要將 Claude/OpenCode agent frontmatter 直接複製成 OpenClaw agent。
  • 部署到專案後，agent 內引用的參考資料必須走 story-setup/references/agent-references/*.md 這條 skill 內複製路徑；不要跨 skill 引用其他 skill 的 references。若全域安裝路徑不同，優先使用專案內 .claude/skills/ 或 skills/ 作為規範路徑前綴，其次使用工具的 skill 搜尋能力，不要假定固定的絕對路徑。

2.4.2 部署 Agent References

  • 將 skills/story-setup/references/agent-references/ 下所有 .md 複製到專案內 .claude/skills/story-setup/references/agent-references/
  • 若目標專案已經使用專案本地 skills/ 目錄，也可以同步複製到 skills/story-setup/references/agent-references/ 作為 fallback，但不得只複製 fallback 而遺漏 .claude/skills/ 主路徑
  • 驗證：凡 agent 或 reference 中出現 story-setup/references/agent-references/<file>.md，來源包與目標包都必須存在 <file>.md

2.4.3 部署 Codex Agents（target_cli 含 codex 時）

  • 讀取 skills/story-setup/references/codex/agents/ 下所有 .toml 檔案，複製到使用者專案 .codex/agents/
  • Agent 檔案屬於 story-setup 管理檔案，可安全覆蓋；產生來源由 scripts/generate-codex-agents.py 從 Claude agent 範本確定性產生
  • 檢驗每個 TOML 都能解析，且包含 Codex 必需欄位：name、description、developer_instructions
  • 唯讀職責 agent（chapter-extractor、consistency-checker、story-explorer）必須保留 sandbox_mode = "read-only"
  • 部署後必須 trust + 開啟新 Codex 會話（報告文案與 fallback 規則見 Phase 3 第 8 步）；若執行階段傳回 unknown agent_type，呼叫端必須降級為 solo/direct 並報告 fallback。
  • 將 skills/story-setup/references/agent-references/ 同步複製到 .codex/skills/story-setup/references/agent-references/，作為 Codex agent 的專案內參考資料主路徑

2.4.4 設定 OpenCode Agent 模型

僅當 target_cli 含 opencode 時執行。OpenCode 子代理未指定模型時會繼承主模型，導致低成本 Agent 也消耗主模型額度。此步驟會自動檢測使用者模型並寫入 model: 欄位。

Step 0：保留已有模型設定（必須在 .opencode/agents/ 的 replace 之前執行）

OpenCode agents 部署方式為 replace，會覆蓋上次寫入的 model:。因此在執行該 replace 之前先掃描現有 .opencode/agents/*.md，快取每個 agent 的 model:（agent 名稱 → 模型 ID）。後續若檢測失敗/逾時、或使用者跳過某一級時，使用快取值回填，避免將使用者上次設定好的低成本模型抹成主模型。若 replace 已先發生、快取為空，則按全新部署處理，並在安裝報告中提示「未能保留上次模型設定」。

Step 1：取得模型清單

優先執行 opencode models --verbose，其輸出包含 cost（input/output/cache 單價）、context、capabilities 等 metadata；不可用或解析失敗時退回使用 opencode models 純文字（每行 provider/model）。兩者皆使用 60000ms（60 秒）逾時，因為首次執行需載入 models.dev 快取。

  • 成功 → 進入 Step 2
  • 逾時 → 重試一次（快取可能未預熱）；若仍然逾時，則按 Step 0 快取回填已有 model:、跳過自動設定，並在安裝報告中輸出手動設定指南
  • 失敗（命令不存在、輸出為空等）→ 同上：回填 Step 0 快取、跳過自動設定、輸出手動設定指南
Step 2：模型分級

優先按成本分級（有 --verbose 時）：按每個模型的實際 cost 由低到高分檔——低階取最便宜/免費檔、中階取中價檔、高階取最貴或上下文/能力最強檔。免費模型按真實 cost=0 歸為低階，不按名稱中的行銷詞（例如 nemotron-3-ultra-free 名稱含 ultra 但 cost=0，應歸為低階）。無 cost 資料的模型也據此納入候選，不予丟棄。

退回按關鍵字分級（無 --verbose 或無 cost 時）：按模型 ID 中最後一個 / 之後的模型名稱以 -、.、_ 分割為區段，逐段精確比對關鍵字（不區分大小寫）。例如 minimax-m3 拆為 [minimax, m3]，不比對 mini 也不比對 max；claude-haiku-4.5 拆為 [claude, haiku, 4, 5]，比對 haiku。關鍵字分級為啟發式，安裝報告中标註 分級依據：關鍵字（heuristic）。

等級 比對關鍵字 對應 Agent
低階 haiku, flash, mini, nano, lite chapter-extractor, consistency-checker, story-explorer
中階 sonnet, plus story-researcher, narrative-writer, character-designer
高階 opus, pro, ultra, max story-architect
  • 一個模型可能比對多個等級的關鍵字，取最高等級
  • 關鍵字退回機制下未比對任何關鍵字的模型，仍列入候選附加建議（若按成本分級則一律納入），並在安裝報告中列出，提示「可透過自訂輸入使用」
  • 同一等級內，若包含多個模型供應商，優先列出知名供應商（anthropic、openai、google、deepseek）的模型
Step 3：逐級互動選擇

按 低階 → 中階 → 高階 順序，每一級使用 AskUserQuestion 讓使用者選擇。

低階選項結構：

問題："為低成本 Agent（chapter-extractor, consistency-checker, story-explorer）選擇模型："
選項：
  - provider/model-id
  - provider/model-id
  - 自訂輸入（手動輸入完整模型 ID，ID 拼寫錯誤要在執行階段才會暴露）
  - 跳過，使用主模型（成本可能較高）

中階選項結構：

問題："為寫作品質關鍵 Agent（narrative-writer, character-designer, story-researcher）選擇模型："
選項：
  - provider/model-id
  - provider/model-id
  - 自訂輸入（請勿使用低階模型，會影響正文品質；ID 拼寫錯誤要在執行階段才會暴露）
  - 跳過，使用主模型（主模型品質通常足夠）

高階選項結構：

問題："為總指揮 Agent（story-architect）選擇模型："
選項：
  - provider/model-id
  - provider/model-id
  - 自訂輸入（手動輸入完整模型 ID，ID 拼寫錯誤要在執行階段才會暴露）
  - 跳過，使用主模型（成本可能較高）

規則：

  • 候選最多顯示 5 個，超過則截斷並提示「更多模型請使用自訂輸入」。每一級無論候選數是否為 0 皆使用 AskUserQuestion 彈出，選項至少包含