Menu
网文写作工具集基础设施部署。为 Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix 提供内置适配；Web AI / 通用 Agent 可走 skills + AGENTS.md 文件模式。触发方式：/story-setup、$story-setup、「准备写书」「帮我搭一下环境」「配置写作项目」。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | story-setup |
| version | 1.2.7 |
| description | 网文写作工具集基础设施部署。为 Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix 提供内置适配；Web AI / 通用 Agent 可走 skills + AGENTS.md 文件模式。触发方式：/story-setup、$story-setup、「准备写书」「帮我搭一下环境」「配置写作项目」。 |
| metadata | {"openclaw":{"source":"https://github.com/worldwonderer/oh-story-claudecode"}} |
你是写作基础设施部署器。将网文写作工具集部署到用户项目目录：已适配的 CLI 走专用 hooks/agents/config；NarraFork、Web AI、自定义 Agent 等环境走通用文件模式。
执行铁律：不覆盖用户已有配置，合并而非替换。
.story-deployed）
agents_version 缺失、非整数或小于 21 → 标记为待更新，继续执行当前部署agents_version: 21 → 使用 AskUserQuestion 确认是否重新部署agents_version 大于 21 → 当前 story-setup 比项目部署旧；停止以避免降级覆盖，提示先更新 oh-story-claudecode，不写任何部署文件追踪/ 子目录的目录，或用户自定义结构）
.claude/settings.local.json 是否存在
.active-book 文件是否存在
opencode.json 或 .opencode/ 是否存在
target_cli = opencode.codex/、.codex/config.toml、.codex/agents/、.codex/hooks.json、AGENTS.md 中的 Codex 段
target_cli = codex.zcode/、.zcode/config.json、zcode.json、.zcode/skills/、.zcode/commands/、AGENTS.md 中的 ZCode 段
target_cli = zcodeopenclaw.json、.openclaw/、.agents/skills/、AGENTS.md 中的 OpenClaw 段，或 skills/*/SKILL.md 中的 metadata.openclaw
target_cli = openclaw.reasonix/、reasonix-plugin.json、REASONIX.md 中的 Reasonix 标记（Reasonix 与 Codex/OpenClaw 共用 .agents/skills，故不以 .agents/skills 单独判定 Reasonix，只认 Reasonix 专属标记）
target_cli = reasonix.claude/ 或 CLAUDE.md、OpenCode、Codex、ZCode、OpenClaw、Reasonix 标记同时存在 → 使用 AskUserQuestion 让用户选择目标环境（选项：Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix / 通用 Web AI 或其他 Agent / 任意组合）target_cli = opencode，部署时创建 opencode.json 和 .opencode/target_cli = codex，部署时创建 .codex/target_cli = zcode，部署时创建 .zcode/、合并根 AGENTS.md，不创建项目 custom agentstarget_cli = openclaw，部署时复制 OpenClaw 兼容 skills 到项目 skills/target_cli = reasonix，部署时复制 skills 到项目 skills/、写入 Reasonix 版 AGENTS.md，不创建项目 custom agents/hookstarget_cli = generic，部署通用 AGENTS.md 与项目本地 skills/；不写平台专属 hooks/agentstarget_cli = claude-code,opencode,codex,zcode,openclaw,reasonix,generic 的子集（仅包含用户选择的端）使用 AskUserQuestion 确认部署位置后，依次执行。
| 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, story_hook_core.js, story_hook_cli.js, lib/common.sh, lib/sentinel.sh exist；story_hook_core.js 与 OpenCode/ZCode 副本字节一致 |
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 前按「配置 OpenCode Agent 模型」中的「保留已有模型配置」缓存现有 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/story_hook_core.js | .opencode/plugins/lib/story_hook_core.js | story-setup managed | replace | Node syntax valid；与 ZCode 副本字节一致；被 story-hooks.ts import |
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 | replace managed registrations by stable hook identity | hook JSON valid; all stale direct/launcher registrations removed, current 6 registrations present exactly once |
skills/story-setup/references/codex/hooks/{story_codex_hook.py,run-story-hook.sh,run-story-hook.cmd} | .codex/hooks/ 同名文件 | story-setup managed | replace | Python/shell/cmd launcher 文件齐全 |
skills/story-setup/scripts/merge-codex-hooks.py | 部署时执行，不复制到项目 | story-setup helper | execute | 替换已知管理注册、保留用户 hooks 与未知顶层字段，结果幂等 |
skills/story-setup/references/agent-references/ | .codex/skills/story-setup/references/agent-references/ | story-setup managed | replace | every reference resolves |
skills/story-setup/references/zcode/AGENTS.md.tmpl | AGENTS.md | user+managed | marker/section merge | contains ZCode $story-* routing and solo fallback |
repository skills/{browser-cdp,story*}/ | .zcode/skills/{browser-cdp,story*}/ | story-setup managed for known skill names | replace known skill dirs only | 13 SKILL.md files exist and satisfy ZCode frontmatter limits |
skills/story-setup/references/zcode/commands/ | .zcode/commands/ | story-setup managed for known command names | replace known command files only | 13 commands have valid names/frontmatter |
skills/story-setup/references/zcode/hooks/story_zcode_hook.js | .zcode/hooks/story_zcode_hook.js | story-setup managed | replace | Node syntax valid; hook contract tests pass |
skills/story-setup/references/zcode/hooks/story_hook_core.js | .zcode/hooks/story_hook_core.js | story-setup managed | replace | Node syntax valid; hook contract tests pass |
skills/story-setup/references/zcode/config.json.patch | merge into .zcode/config.json | user+managed | merge by event+matcher+process args | JSON valid; 按「ZCode 部署算法」第 4 步 hooks 互斥分支校验——未装 oh-story 插件时 hooks.enabled=true、only supported events；已装插件时校验 .zcode/config.json 不含（或已移除）这批 oh-story hooks 注册 |
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 |
skills/story-setup/references/reasonix/AGENTS.md.tmpl | AGENTS.md | user+managed | marker/section merge | contains Reasonix story skill routing sections and solo/direct fallback |
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.patch 时按以下规则合并：
opencode.json（如存在），解析 JSONplugin 数组：将 ./.opencode/plugins/story-hooks.ts 加入数组，去重permission、model、provider 等），不覆盖opencode.jsonskills/story-setup/references/templates/CLAUDE.md.tmplCLAUDE.md（如已存在，按「CLAUDE.md 合并策略」处理）skills/story-setup/references/templates/hooks/ 复制到用户项目 .claude/hooks/lib/，其中：
lib/common.sh 提供 project_root、discover_active_book、discover_all_bookslib/sentinel.sh 提供 .story-deployed 字段读取.claude/hooks/*.sh 设置执行权限（chmod +x）；lib/*.sh 由 hook source，不要求可执行位skills/story-setup/references/templates/rules/ 下所有 .md 文件.claude/rules/ 目录skills/story-setup/references/templates/agents/ 下所有 .md 文件.claude/agents/ 目录UPGRADING.md 的版本检测结果重新部署scripts/sync-opencode.py 生成 .opencode/agents/*.md；Codex 由 scripts/generate-codex-agents.py 生成 .codex/agents/*.toml。~/.zcode/agents/，plugin manifest 中的 agents 当前不执行。不要创建 .zcode/agents/ 或修改用户 home；相关 Skill 必须直接 solo/direct 并报告 fallback。story-setup/references/agent-references/*.md 这一本 skill 内复制路径；不要跨 skill 引用其他 skill 的 references。各 adapter 只使用当前规范前缀：Claude Code 为 .claude/skills/，OpenCode / OpenClaw / Reasonix / generic 为 skills/，Codex 为 .codex/skills/，ZCode 为 .zcode/skills/；不在运行时遍历历史备选路径。skills/story-setup/references/agent-references/ 下所有 .md 复制到项目内 .claude/skills/story-setup/references/agent-references/story-setup/references/agent-references/<file>.md，源包与目标包都必须存在 <file>.mdskills/story-setup/references/codex/agents/ 下所有 .toml 文件，复制到用户项目 .codex/agents/scripts/generate-codex-agents.py 从 Claude agent 模板确定性生成name、description、developer_instructionschapter-extractor、consistency-checker、story-explorer）必须保留 sandbox_mode = "read-only"unknown agent_type，调用方必须降级 solo/direct 并报告 fallback。skills/story-setup/references/agent-references/ 同步复制到 .codex/skills/story-setup/references/agent-references/，作为 Codex agent 的项目内参考资料主路径仅当
target_cli含opencode时执行。OpenCode 子代理不指定模型时继承主模型，导致低成本 Agent 也消耗主模型额度。此步骤自动检测用户模型并写入model:字段。
.opencode/agents/ 的 replace 之前执行）OpenCode agents 部署是 replace，会覆盖上次写入的 model:。所以在执行该 replace 之前先扫描现有 .opencode/agents/*.md，缓存每个 agent 的 model:（agent 名 → 模型 ID）。后续检测失败/超时、或用户跳过某一级时，用缓存值回填，避免把用户上次配好的低成本模型抹成主模型。若 replace 已先发生、缓存为空，则按全新部署处理，并在安装报告中提示"未能保留上次模型配置"。
优先执行 opencode models --verbose，它输出含 cost（input/output/cache 单价）、context、capabilities 的 metadata；不可用或解析失败时回退到 opencode models 纯文本（每行 provider/model）。两者都用 60000ms（60 秒）超时，因为首次运行需加载 models.dev 缓存。
model:、跳过自动配置，在安装报告中输出手动配置指南优先按成本分级（有 --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 |
按 低端 → 中端 → 高端 顺序，每级用 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 拼写错误要到运行时才会暴露）
- 跳过，使用主模型（成本可能较高）
规则：
自定义输入、保留现有模型（「保留已有模型配置」缓存到该 agent 的 model，无则不显示此项）、跳过，用主模型。候选为 0 时仍弹窗，并在问题说明里给出对应警告 + 列出未分级/未入档模型供参考——不再静默跳过交互（否则用户够不到自定义输入）。自定义输入：用户输入 provider/model-id 完整 ID；写入前校验为单行、无控制字符、匹配 ^[A-Za-z0-9._-]+/[A-Za-z0-9._:+-]+$，不符则提示重输或改选跳过。保留现有模型：写回「保留已有模型配置」缓存的该 agent model（重新部署时保住用户上次配置），不算"跳过"。跳过，用主模型：显式清除——不写该 agent 的 model:，agent 继承主模型。想保留上次配置请选 保留现有模型。对应用户选择的 agent 文件（.opencode/agents/*.md，由部署清单中 OpenCode agents 部署步骤在此步骤之前已部署），在 frontmatter 末尾、closing --- 之前，以零缩进的顶层字段插入 model:（不要插进 permission: 等多行 map 的缩进块内部）。值含 YAML 特殊字符时加引号，确保不破坏 frontmatter：
---
description: ...
mode: subagent
permission:
read: allow
edit: deny
steps: 12
model: provider/model-id
---
model: 字段（重新部署场景），替换该顶层 model: 的值，不新增重复键保留现有模型：写回「保留已有模型配置」缓存的该 agent model跳过，用主模型：不写入 model: 字段model:，避免 replace 抹掉用户上次配置skills/story-setup/references/templates/上下文.md.tmpl{书名}/追踪/ 已存在时，创建缺失的 {书名}/追踪/上下文.md追踪/ 目录skills/story-setup/references/templates/settings-hooks.json.claude/settings.local.json（如存在）.claude/settings.local.jsonCodex 项目 hooks 部署到 .codex/hooks.json；运行脚本部署到 .codex/hooks/story_codex_hook.py、run-story-hook.sh、run-story-hook.cmd。JSON 只负责定位项目根与传递 event，解释器探测由平台 launcher 统一处理。
references/codex/hooks/hooks.json 作为唯一当前模板，读取项目 .codex/hooks.json（不存在时视为空对象）。for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done；无可用解释器时停止，不手写或简化 JSON 合并。"$PYBIN" "{story-setup skill目录}/scripts/merge-codex-hooks.py" --existing "{项目}/.codex/hooks.json" --template "{story-setup skill目录}/references/codex/hooks/hooks.json" --output "{项目}/.codex/hooks.json"。该 helper 会识别旧直调 story_codex_hook.py、当前 run-story-hook.sh 和 run-story-hook.cmd 三类管理身份，先移除所有已知管理注册，再追加当前模板。command 字符串追加去重，否则 v17 直调命令会与 v18 launcher 双重注册。story_codex_hook.py 命令数为 0，当前模板 6 个注册各存在且仅存在一次，用户 hook 与未知顶层字段仍在。然后提示用户：项目 .codex/ 层需要被 Codex trust，非 managed command hooks 还需要在 /hooks 中 review/trust 后才会运行；Windows 下走 commandWindows，launcher 从当前目录向上定位项目 .codex/hooks/，与 POSIX 路径的嵌套目录行为一致。ZCode 首版部署 Skills、Commands、AGENTS.md 和支持事件内的 Hooks；不部署 .zcode/agents 或 .zcode/rules。
skills/ 下 13 个包含 SKILL.md 的目录到 .zcode/skills/{skill-name}/；仅替换这些已知目录，保留用户其他 Skills。references/zcode/commands/*.md 到 .zcode/commands/；仅替换 13 个同名命令，保留用户其他 Commands。references/zcode/hooks/story_zcode_hook.js 和 references/zcode/hooks/story_hook_core.js 到 .zcode/hooks/。references/zcode/config.json.patch 和现有 .zcode/config.json（如只有根 zcode.json，仍创建 .zcode/config.json 承载 oh-story 项目 Hooks，不改写根文件）：
.zcode-plugin/plugin.json 的 hooks.json 已全局注册 SessionStart/PreToolUse/PostToolUse），则跳过下面把 config.json.patch 的 hooks 块合并进 .zcode/config.json——插件 manifest 已注册这批 hooks，再合并会让同一事件跑两遍（PreToolUse 拦两次、PostToolUse 注入两次）。只有未装插件（直接克隆 / 手动导入 references）时才合并 hooks。不确定时以「ZCode 是否已通过本插件注册这套 hooks」为准；skills/commands/hook 文件/AGENTS 与 config 的非 hook 字段两条路径都照常部署。hooks.enabled: true；用户已有更大的 timeoutMs 时保留，否则取模板值；对 hooks.events 的 SessionStart、PreToolUse、PostToolUse 按 event + matcher + process command + args 去重追加；不复制 ZCode 不支持的 PreCompact、PostCompact、SessionEnd、SubagentStop、Notification。references/zcode/AGENTS.md.tmpl 按「AGENTS.md 合并策略」写入根 AGENTS.md。.story-deployed 的 target_cli 写入 zcode 或多端组合，references_dir 写 .zcode/skills/story-setup/references/agent-references。node 命令运行项目 Hook。Plugin 安装不经过本算法：仓库根 .zcode-plugin/plugin.json 直接暴露同一组 Skills/Commands/Hooks。Plugin Skills 优先级低于 workspace .zcode/skills；两者同时存在时项目快照优先，升级项目快照需重新运行 $story-setup。Hooks 只能注册一份：插件 manifest 与 workspace .zcode/config.json 注册的是同一批事件，装了插件就不要再把 config.json.patch 的 hooks 合并进 .zcode/config.json（见上算法第 4 步的 hooks 互斥），否则 PreToolUse/PostToolUse 会双触发；插件在场时以插件 manifest 为 hooks 唯一注册源。
OpenClaw Phase 1 只部署 skills，不部署 OpenClaw agents/hooks/plugin。
skills/ 下所有包含 SKILL.md 的 story skill 目录（13 个：browser-cdp 与 story*）。skills/{skill-name}/，仅替换这些 story-setup 管理的已知 skill 目录；保留用户在 skills/ 下的其他目录。SKILL.md 必须满足 OpenClaw frontmatter 约束：name / description 是单行键值，metadata 是单行 JSON 对象且含 metadata.openclaw。skills/story-setup/references/openclaw/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。.story-deployed 的 target_cli 写入 openclaw 或多端组合；references_dir 对 OpenClaw 写 skills/story-setup/references/agent-references。Reasonix（DeepSeek-Reasonix CLI）当前只部署 skills 与 AGENTS.md，不部署 Reasonix hooks/custom agents（hook I/O 契约与子代理行为缺少可校验的真实 CLI，留待后续阶段）。
skills/ 下所有包含 SKILL.md 的 story skill 目录（13 个：browser-cdp 与 story*）到目标项目 skills/{skill-name}/；仅替换这些 story-setup 管理的已知 skill 目录，保留用户其他目录。.agents/skills → ../skills 相对 symlink（与 Codex 共用的 skill root），使 Reasonix 原生扫描 .agents/skills 时发现这些 skill；若已是指向 skills/ 的 symlink 则保留，若被占用为普通目录则不覆盖并在安装报告提示。Windows 未启用 symlink 时跳过本步，改走根 reasonix-plugin.json 的 reasonix plugin install。skills/story-setup/references/reasonix/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。skills/story-setup/references/agent-references/ 到 skills/story-setup/references/agent-references/，保证 narrative-writer / story-architect 等角色说明里的参考路径可解析。.story-deployed 的 target_cli 写入 reasonix 或多端组合；references_dir 对 Reasonix 写 skills/story-setup/references/agent-references。通用路径面向 NarraFork、Web AI、自定义 Agent 等可读取项目文件的环境，只部署通用文件，不声明平台原生 hooks/agents 能力。
skills/ 下所有包含 SKILL.md 的 story skill 目录（13 个：browser-cdp 与 story*）到目标项目 skills/{skill-name}/；仅替换这些 story-setup 管理的已知 skill 目录，保留用户其他目录。skills/story-setup/references/generic/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。skills/story-setup/references/agent-references/ 到 skills/story-setup/references/agent-references/，保证 narrative-writer / story-architect 等角色说明里的参考路径可解析。.story-deployed 的 target_cli 写入 generic 或多端组合；references_dir 对 generic 写 skills/story-setup/references/agent-references。.story-deployed 文件（sentinel file）key: value 格式，hook 用 references/templates/hooks/lib/sentinel.sh 读取）：
deployed_at: <date -u +"%Y-%m-%dT%H:%M:%SZ">
agents_version: 21
setup_skill_version: 1.2.7
target_cli: claude-code（或 opencode、codex、zcode、openclaw、reasonix、generic，或其任意组合）
resolver_strategy: project-local-skill-reference
references_dir: .claude/skills/story-setup/references/agent-references（Codex 写 .codex/skills/...；ZCode 写 .zcode/skills/...；OpenClaw / Reasonix / generic 写 skills/...；多端用逗号分隔）
.claude/.agents-pending-restart（空文件即可）。session-start.sh 在下一个会话启动时据此确认 agents 已随新会话注册，并自动删除该标记——用来向用户确认「重启已生效」。ZCode 不创建该标记，因为它不部署项目 agents。.story-deployed 已存在但 agents_version 缺失、非整数或小于 21，按本次流程更新 hooks/agents/rules/reference bundle（具体变更见 UPGRADING.md）；大于 21 时已在 Phase 1 停止，不得降级覆盖.claude/settings.local.json 中的 hooks 字段是否正确.claude/hooks/ 下的脚本是否存在且有执行权限.claude/hooks/lib/common.sh 与 .claude/hooks/lib/sentinel.sh 是否存在.claude/rules/ 下的规则文件是否存在且包含 paths frontmatter.claude/agents/ 下的 7 个 agent 定义文件是否存在.claude/skills/story-setup/references/agent-references/ 下 reference 文件完整story-setup/references/agent-references/<file>.md 都能解析到 deployed bundle.story-deployed 是否存在且包含时间戳、agents_version: 21、setup_skill_version: 1.2.7、target_cli、resolver_strategy、references_dir.claude/agents/，但这些 custom agent 只在「会话启动」时才会被 Claude Code 注册成 subagent_type。请新开一个 Claude Code 会话再开始写作，否则当前会话里 story-review / story-long-write 等想 spawn story-architect、narrative-writer 等时会拿到「subagent_type 不可用」并降级 solo（单视角，失去多 agent 协作）。判断是否生效：新会话里跑 /story-review，报告头若是 Effective Mode: full/lean 即注册成功；若是 Fallback: ... -> solo 说明还在旧会话或未注册。/story-long-write 或 /story-short-writeAgent 模型配置：
story-architect → <高端模型>（provider/model-id）
narrative-writer → <中端模型>（provider/model-id）
character-designer → <中端模型>（provider/model-id）
story-researcher → <中端模型>（provider/model-id）
chapter-extractor → <低端模型>（provider/model-id）
consistency-checker → <低端模型>（provider/model-id）
story-explorer → <低端模型>（provider/model-id）
opencode models 不可用），输出手动配置指南：
无法自动检测模型列表。以下 Agent 未配置模型，将使用主模型，成本可能较高：
- chapter-extractor（建议使用低成本模型）
- consistency-checker（建议使用低成本模型）
- story-explorer（建议使用低成本模型）
手动配置方法：编辑 .opencode/agents/{agent名}.md，在 frontmatter 中添加：
model: provider/model-id
可用模型列表与成本可通过 opencode models --verbose 查看（输出含每模型 cost/context）。
模型库与定价见 OpenCode 官方模型源 https://models.dev/。
.opencode/agents/ 下的 7 个 agent 定义文件是否存在，且 frontmatter 包含 mode: subagent 和 permission 字段.opencode/plugins/story-hooks.ts 是否存在.opencode/plugins/lib/story_hook_core.js 存在且 node --check 通过（story-hooks.ts import 之，与 .zcode 副本字节一致的共享写正文守卫核；置于 lib/ 子目录以避开 OpenCode 单层 .opencode/plugins/*.js 插件自动发现）.opencode/commands/ 下的 13 个 command 文件是否存在skills/story-setup/references/agent-references/ 下 reference 文件完整且数量与源目录一致opencode.json 的 plugin 数组是否包含 story-hooks 条目.git/hooks/pre-commit 是否存在且有执行权限（Windows 上跳过执行权限检查）.opencode/agents/ 下 agent 文件 frontmatter 可被 YAML 解析、model:（如有配置）是合法顶层标量，而非仅 grep 到 model: 子串AGENTS.md 含 Codex story skill routing sections.codex/agents/ 下 7 个 .toml agent 定义文件存在并可解析.codex/hooks.json 存在且 JSON 有效，Unix command 仅通过 run-story-hook.sh 启动，Windows commandWindows 仅通过 run-story-hook.cmd 启动；不存在直调 story_codex_hook.py 的注册.codex/hooks/story_codex_hook.py、run-story-hook.sh、run-story-hook.cmd 存在，Python 语法有效，POSIX/Windows launcher 能从嵌套 cwd 定位项目根.codex/skills/story-setup/references/agent-references/ 下 reference 文件完整且数量与源目录一致.codex/ 配置层，并在 /hooks review/trust 非 managed hooks；部署后新开 Codex 会话让 custom agents 生效；若当前运行时仍返回 unknown agent_type，按各 skill 的 fallback 规则降级 solo/directAGENTS.md 含 ZCode $story-* 路由、大纲守卫和 solo/direct fallback.zcode/skills/ 下 13 个 Skills 与 .zcode/commands/ 下 13 个 Commands，验证 frontmatter 和命名.zcode/hooks/story_zcode_hook.js、.zcode/hooks/story_hook_core.js 存在且 node --check 通过.zcode/config.json JSON 有效，并按「ZCode 部署算法」第 4 步的 hooks 互斥分支校验：未装 oh-story 插件时，hooks.enabled=true、仅注册 ZCode 支持事件、所有 process args 指向项目 Hook；已装 oh-story 插件（.zcode-plugin/plugin.json 已全局注册这批 hooks）时，改为校验 .zcode/config.json 不含（或已移除）这批 oh-story hooks 注册——不得为了让校验通过而把 config.json.patch 的 hooks 块合并回去，否则同一事件双触发.zcode/skills/story-setup/references/agent-references/ 完整且所有 reference 路径可解析node；部署后新开 ZCode session 刷新 Skills/Commands/AGENTS.mdAGENTS.md 含 OpenClaw story skill routing sectionsskills/ 下 13 个 story skill 目录存在，且每个 SKILL.md 包含单行 name、单行 description、单行 JSON metadata.openclawskills/story-setup/references/agent-references/ 下 reference 文件完整且数量与源目录一致AGENTS.md 含通用 story skill routing sectionsskills/ 下 13 个 story skill 目录存在，且每个 SKILL.md 可读skills/story-setup/references/agent-references/ 下 reference 文件完整且数量与源目录一致AGENTS.md 含 Reasonix story skill routing sections 与 solo/direct fallback 说明skills/ 下 13 个 story skill 目录存在，且每个 SKILL.md 可读.agents/skills 为指向 skills/ 的 symlink（POSIX；使 Reasonix 原生扫描发现 skill）；Windows 未建 symlink 时改为确认根 reasonix-plugin.json 可用于 reasonix plugin installskills/story-setup/references/agent-references/ 下 reference 文件完整且数量与源目录一致reasonix doctor capabilities 校验 skill 发现，部署后如未显示新 skills，新开 Reasonix session 或走根 reasonix-plugin.json 原生 plugin 安装| 占位符 | 替换规则 | 示例 |
|---|---|---|
{项目名} | 用户项目名称或目录名 | 《剑来》、《暗卫》 |
{书名} | 书名目录名（与目录一致） | 与 {项目名} 相同，或用户自定义 |
{目标平台} | 目标发布平台 | 起点、番茄、晋江、知乎盐言 |
{作者名} | 用户笔名或昵称 | 未指定时用「作者」 |
替换时去掉花括号。如果用户未指定项目名，用当前目录名。未指定的占位符保留原样不替换。
用户已有 CLAUDE.md 时，按 marker/section 合并：
## 标题切分为 section map用户已有 AGENTS.md 时，按 marker/section 合并：
## 标题切分为 section mapskills/story-setup/references/opencode/AGENTS.md.tmpl；Codex 使用 skills/story-setup/references/codex/AGENTS.md.tmpl；ZCode 使用 skills/story-setup/references/zcode/AGENTS.md.tmpl；OpenClaw 使用 skills/story-setup/references/openclaw/AGENTS.md.tmpl；Reasonix 使用 skills/story-setup/references/reasonix/AGENTS.md.tmpl；通用 Web AI / 其他 Agent 使用 skills/story-setup/references/generic/AGENTS.md.tmplhooks 注册合并按 command 字段去重：
.claude/settings.local.json（如存在），提取 hooks 部分settings-hooks.json 模板，提取要注册的 hooks.story-deployed 不存在 → 全新安装，Phase 2 全部执行.story-deployed 存在且 agents_version: 21 → 提示已部署，AskUserQuestion 确认是否重新部署.story-deployed 存在但 agents_version 缺失、非整数或小于 21 → 提示需要更新，重新执行 Phase 2 覆盖 agents/hooks/rules/reference bundle，CLAUDE.md / AGENTS.md / settings.local.json / .codex/hooks.json / .zcode/config.json 走合并策略.story-deployed 存在且 agents_version 大于 21 → 当前 skill 版本过旧，停止并提示先更新 oh-story-claudecode；不覆盖项目中的更新部署| 文件 | 用途 |
|---|---|
| references/templates/hooks/ | 8 个 hook 脚本模板 + story_hook_core.js（正文网/字数/大纲守卫/连续性/commit 侦测的共享实现，与 OpenCode/ZCode 同一份）+ story_hook_cli.js（bash hook 调核的 node 桥）+ lib/common.sh/lib/sentinel.sh（正文兜底 check-prose-after-write.sh 限 PostToolUse Write/Edit；cat>/tee 等 Bash 写正文由 Codex Stop 回合末 git 扫描兜，Claude/OpenCode 的 Bash 仅 pre-guard） |
| references/zcode/ | ZCode AGENTS、13 Commands、workspace config patch 与严格 JSON Hook runner |
流水线： 部署 位置： 初始化（最前置）
| 时机 | 跳转到 | 命令 |
|---|---|---|
| 部署完成，开始写作 | story-long-write / story-short-write | /story-long-write 或 /story-short-write |
| 导入已有小说做拆解 | story-import | /story-import |
| 需要浏览器登录态（扫榜/拆文取原文） | browser-cdp | /browser-cdp；generic 需平台允许本地脚本/浏览器控制 |
各端调用语法：Claude /名、Codex/ZCode $名、OpenClaw /skill 名、Reasonix / generic 直接点名 skill。
网络小说工具箱主入口。根据用户需求自动路由到对应 skill，并可启动本地 Dashboard 查看拆文库、写作项目和编辑文本。触发方式：/story、$story、/story dashboard、$story dashboard、/网文、「我想写小说」「打开工作台」「检查更新」。
网文去AI味。检测并清除文本中的AI写作痕迹，让文字回归自然、非模板化。触发方式：/story-deslop、/去AI味、「去AI味」「这篇太AI了」「网文去AI味」。
逆向导入已有小说。将已写好的小说（半成品或完本）反向解析为标准项目目录结构，兼容 story-long-write / story-short-write 后续写作流程；内部复用 story-long-analyze / story-short-analyze 的拆解管道，按篇幅自动分流。触发方式：/story-import、「导入小说」「反向解析」「导入」「把我的书导进来」。
长篇网文写作。从大纲到正文，辅助长篇网络小说的创作，包括世界观、人物、情节线管理。触发方式：/story-long-write、/写长篇、「帮我开书」「写大纲」「日更」「续写」「继续写」「修改第X章」「回炉」「重写第X章」。
多视角对抗式审查。full/lean 模式在已部署 reviewer agents 时并行 spawn；缺失/异常 agents 或 spawn 失败时自动降级 solo，参考文件不可读时使用内置 rubric fallback。触发方式：/story-review、/审查、「审查一下」「帮我审一下」。
短篇网文写作。辅助短篇小说创作，从构思到成稿，聚焦情绪拉扯与节奏把控。触发方式：/story-short-write、/写短篇、「帮我写一篇短篇」「写个盐言故事」。