story-setup

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"}} story-setup：网文写作工具集基础设施部署 你是写作基础设施部署器。将网文写作工具集部署到用户项目目录：已适配的 CLI 走专用 hooks/agents/config；NarraFork、Web AI、自定义 Agent 等环境走通用文件模式。 执行铁律：不覆盖用户已有配置，合并而非替换。 Phase 1：检测项目状态 先自检参考目录 ：以正在执行的本 SKILL.md 所在目录为准，列出与它同级的 references/ 下的子目录，核对下面 8 个名字是否都在 且都非空 —— agent-references 、 templates 、 opencode 、 codex 、 zcode 、 openclaw 、 reasonix 、 generic ；同级 scripts/merge-claude-settings.py 与 scripts/merge-codex-hooks.py 也必须存在（Claude/Codex hooks 合并算法依赖它们）。有缺即 skill 包没装全， 立即停止，不写任何部署文件 ，报告里区分「缺目录」和「目录为空」，并给修复指令：「story-setup 参考资料包不完整，缺 {目录名}。按你的安装方式重装 oh-story-claudecode（命令行装的重跑 npx skills add worldwonderer/oh-story-claudecode -y -g ，marketplace / Plugin Management 装的在面板里重装），再执行 /story-setup。」 判据是「有没有 SKILL.md 」：只看正在执行的 SKILL.md 同级的 references/ 。项目内 .claude/skills/story-setup/ 、 .codex/skills/story-setup/ 和 OpenCode 的 skills/story-setup/ 只有 references/agent-references/ 、不含 SKILL.md ，不会是执行目录，也不要拿它们核对。ZCode / OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝、自带 SKILL.md ，8 个子目录本就齐全，照常核对即可。 检查当前目录是否已部署过（存在 .story-deployed ） agents_version 缺失、非整数或小于 25 → 标记为待更新，继续执行当前部署 agents_version: 25 → 使用 AskUserQuestion 确认是否重新部署；提示里写明重新部署只用 当前本地 skill 包 刷新项目文件，要拿 skill 本身的新版本得先更新 oh-story-claudecode（ npx skills add 或 marketplace），再回来重跑 agents_version 大于 25 → 当前 story-setup 比项目部署旧；停止以避免降级覆盖，提示先更新 oh-story-claudecode，不写任何部署文件 同时读 target_cli 字段。 已部署项目以 sentinel 里的值为准 ：非空时（逗号分隔的多端组合原样保留）跳过下面第 5-12 步的环境探测与选择，直接按这些端重新部署。只有字段缺失或为空，才回落到探测。用户明确要求增删目标端时，用 AskUserQuestion 在现有值基础上改，改完的值写回 sentinel。 检查是否有书名目录（包含 追踪/ 子目录的目录，或用户自定义结构） 有 → 识别为长篇项目，显示当前项目信息 无 → 识别为新项目或短篇项目 检查 .claude/settings.local.json 是否存在 存在 → 读取现有配置，后续合并 不存在 → 后续创建新文件 检查 .active-book 文件是否存在 存在 → 显示当前活跃书目 不存在 → 跳过 检查 opencode.json 或 .opencode/ 是否存在 存在 → 识别为 opencode 项目， target_cli = opencode 不存在 → 跳过 检查 .codex/ 、 .codex/config.toml 、 .codex/agents/ 、 .codex/hooks.json 、 AGENTS.md 中的 Codex 段 存在 → 识别为 Codex 项目， target_cli = codex 不存在 → 跳过 检查 .zcode/ 、 .zcode/config.json 、 zcode.json 、 .zcode/skills/ 、 .zcode/commands/ 、 AGENTS.md 中的 ZCode 段 存在 → 识别为 ZCode 项目， target_cli = zcode 不存在 → 跳过 检查 openclaw.json 、 .openclaw/ ，或 AGENTS.md 中的 OpenClaw 段（标题行含 网文写作工具集（OpenClaw） ） 存在 → 识别为 OpenClaw 项目， target_cli = openclaw 不存在 → 跳过 检查 .reasonix/ 、 reasonix-plugin.json 、 REASONIX.md ，或 AGENTS.md 中的 Reasonix 段（标题行含 网文写作工具集（Reasonix） ） 存在 → 识别为 Reasonix 项目， target_cli = reasonix 不存在 → 跳过 检查 AGENTS.md 中的通用段（标题行含 网文写作工具集（通用 Agent / Web AI） ） 存在 → 识别为通用 Web AI 项目， target_cli = generic 不存在 → 跳过 第 8-10 步只认各端 互斥 的标记。 skills/*/SKILL.md 的 metadata.openclaw 不作 OpenClaw 信号：13 个 skill 全都带这个字段，而 OpenClaw / Reasonix / generic 三条 skills-only 路径部署出的 skills/ 长得一样，用它判定会把后两者一律误认成 OpenClaw。 .agents/skills/ 同理由 Codex 与 Reasonix 共用，也不单独作准。三端真正的分辨点是各自 AGENTS.md 模板的标题行。 如 .claude/ 或 CLAUDE.md 、OpenCode、Codex、ZCode、OpenClaw、Reasonix、generic 标记同时存在 → 使用 AskUserQuestion 让用户选择目标环境（选项：Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix / 通用 Web AI 或其他 Agent / 任意组合） 如七类标记都不存在（全新项目）→ 使用 AskUserQuestion 让用户选择目标环境 用户选择 opencode → target_cli = opencode ，部署时创建 opencode.json 和 .opencode/ 用户选择 claude-code → 按现有逻辑处理 用户选择 codex → target_cli = codex ，部署时创建 .codex/ 用户选择 zcode → target_cli = zcode ，部署时创建 .zcode/ 、合并根 AGENTS.md ，不创建项目 custom agents 用户选择 openclaw → target_cli = openclaw ，部署时复制 OpenClaw 兼容 skills 到项目 skills/ 用户选择 reasonix → target_cli = reasonix ，部署时复制 skills 到项目 skills/ 、写入 Reasonix 版 AGENTS.md ，不创建项目 custom agents/hooks 用户选择通用 Web AI / 其他 Agent → target_cli = generic ，部署通用 AGENTS.md 与项目本地 skills/ ；不写平台专属 hooks/agents 用户选择多端 → target_cli = claude-code,opencode,codex,zcode,openclaw,reasonix,generic 的子集（仅包含用户选择的端） Phase 2：部署基础设施 使用 AskUserQuestion 确认部署位置后，依次执行。 整个 Phase 2 幂等：目录复制、文件写入和下表各合并算法重复执行结果一致。因环境原因（工具不可用、权限被拒、网络失败）中途失败时，直接从头重跑本 Phase，不需要先清理半成品； create only if absent 的用户状态文件（见下表 Owner class）不会被二次覆盖。 Step 1：部署清单（机械可检查） 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 replace managed registrations by stable hook identity hook JSON valid；旧 matcher 注册已迁移、当前模板命令各一份、用户 hook 保留 skills/story-setup/scripts/merge-claude-settings.py 部署时执行，不复制到项目 story-setup helper execute 替换已知 story hook 注册、保留用户 hooks/顶层字段，v24→v25 迁移与重复执行幂等 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 合并算法 部署 opencode.json.patch 时按以下规则合并： 读取现有 opencode.json （如存在），解析 JSON 合并 plugin 数组：将 ./.opencode/plugins/story-hooks.ts 加入数组，去重 保留用户已有的其他配置字段（ permission 、 model 、 provider 等），不覆盖 写入合并后的 opencode.json Step 2：部署 CLAUDE.md 读取 skills/story-setup/references/templates/CLAUDE.md.tmpl 替换占位符（见下方「模板占位符」段） 写入项目根目录 CLAUDE.md （如已存在，按「CLAUDE.md 合并策略」处理） Step 3：部署 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 ，不要求可执行位 Step 4：部署 Rules 读取 skills/story-setup/references/templates/rules/ 下所有 .md 文件 复制到用户项目的 .claude/rules/ 目录 Step 5：部署 Agents 读取 skills/story-setup/references/templates/agents/ 下所有 .md 文件 复制到用户项目的 .claude/agents/ 目录 Agent 文件属于 story-setup 管理文件，可安全覆盖；版本升级时按 UPGRADING.md 的版本检测结果重新部署 target_cli 含 opencode 时，覆盖 .opencode/agents/ 之前先执行下面「配置 OpenCode Agent 模型」的 Step 1 缓存现有 model: 。那一步写在本节后面，但必须先跑——照顺序读到哪做到哪会先覆盖再缓存，用户已配的模型就没了。 部署后必须新开会话 ：agent 只在会话启动时注册；原因与必须输出的报告文案见「验证安装」中的「输出安装报告」。 Agent 兼容性处理 Agent frontmatter 以 Claude Code 为主；OpenCode 的 .opencode/agents/*.md 与 Codex 的 .codex/agents/*.toml 都由 references/opencode/agents/ 、 references/codex/agents/ 下的预生成产物直接复制，这两个目录是部署的唯一来源。预生成产物由 oh-story-claudecode 仓库根的 scripts/sync-opencode.py 和 scripts/generate-codex-agents.py 维护；这两个脚本是仓库维护工具，不随 story-setup 下发，部署时不需要也无法调用。 ZCode 3.3.4 不部署项目 agents ：其自定义子智能体只支持用户级 ~/.zcode/agents/ ，plugin manifest 中的 agents 当前不执行。不要创建 .zcode/agents/ 或修改用户 home；相关 Skill 必须直接 solo/direct 并报告 fallback。 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。各 adapter 只使用当前规范前缀：Claude Code 为 .claude/skills/ ，OpenCode / OpenClaw / Reasonix / generic 为 skills/ ，Codex 为 .codex/skills/ ，ZCode 为 .zcode/skills/ ；不在运行时遍历历史备选路径。 部署 Agent References 将 skills/story-setup/references/agent-references/ 下所有 .md 复制到项目内 .claude/skills/story-setup/references/agent-references/ 校验：凡 agent 或 reference 中出现 story-setup/references/agent-references/<file>.md ，源包与目标包都必须存在 <file>.md 部署 Codex Agents（target_cli 含 codex 时） 读取 skills/story-setup/references/codex/agents/ 下所有 .toml 文件，复制到用户项目 .codex/agents/ Agent 文件属于 story-setup 管理文件，可安全覆盖； references/codex/agents/ 里的 TOML 由仓库根的 scripts/generate-codex-agents.py 从 Claude agent 模板确定性生成后提交入库，部署只做复制 校验每个 TOML 都能解析，且包含 Codex 必需字段： name 、 description 、 developer_instructions 只读职责 agent（ chapter-extractor 、 consistency-checker 、 story-explorer ）必须保留 sandbox_mode = "read-only"