Menu
网文写作工具集基础设施部署。为 Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix 提供内置适配；Web AI / 通用 Agent 可走 skills + AGENTS.md 文件模式。触发方式：/story-setup、$story-setup、「准备写书」「帮我搭一下环境」「配置写作项目」。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
网络小说工具箱主入口。根据用户需求自动路由到对应 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、/写短篇、「帮我写一篇短篇」「写个盐言故事」。
| 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。