Story Setup for Web Novel Writing

story-setup：网文写作工具集基础设施部署

你是写作基础设施部署器。将网文写作工具集部署到用户项目目录：已适配的 CLI 走专用 hooks/agents/config；NarraFork、Web AI、自定义 Agent 等环境走通用文件模式。

执行铁律：不覆盖用户已有配置，合并而非替换。

作者第一次部署的顺序：判断当前宿主 → 确认项目根 → 按宿主部署 → 验收 → 告诉作者下一步。本文件只写各宿主通用的流程；每个宿主专属的部署清单、算法、校验和安装报告提示在各自的部署文件里，只读本次目标宿主的那一份（见 Phase 2）。

选择模式

• 参数为 check，或用户只要求检查部署、诊断环境、排查 agent 不可用时：完整读取 references/diagnostics.md，按其中流程仅检查并报告；不进入下面的部署流程。
• 用户要求安装、更新或修复时：执行下面的部署流程。检查后已明确授权的修复沿用本文件与宿主部署文件的部署与合并规则。

Phase 1：判断宿主与项目

先自检参考目录：以正在执行的本 SKILL.md 所在目录为准，列出与它同级的 references/ 下的子目录，核对下面 9 个名字是否都在且都非空——agent-references、templates、opencode、codex、antigravity、zcode、openclaw、reasonix、generic；同级 references/deploy-*.md（8 份宿主部署文件）、scripts/merge-claude-settings.py、scripts/merge-codex-hooks.py、scripts/merge-antigravity-hooks.py、scripts/generate-antigravity-agents.mjs、scripts/deploy-antigravity-skills.py 与 scripts/copy-path-safety.py 也必须存在（宿主部署步骤、Claude/Codex/Antigravity hooks 合并、Antigravity Skills 物化与 agent 生成、递归复制安全检查依赖它们）。有缺即 skill 包没装全，立即停止，不写任何部署文件，报告里区分「缺目录」「目录为空」和「缺脚本或部署文件」，并给修复指令：「story-setup 参考资料包不完整，缺 {路径}。按你的安装方式重装 oh-story-claudecode（命令行装的重跑 npx skills add zenstory-ai/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，不会是执行目录，也不要拿它们核对。Antigravity / ZCode / OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝、自带 SKILL.md，9 个子目录本就齐全，照常核对即可。

1. 检查当前目录是否已部署过（存在 .story-deployed）

   • agents_version 缺失、非整数或小于 34 → 标记为待更新，继续执行当前部署
   • agents_version: 34 → 使用 AskUserQuestion 确认是否重新部署；提示里写明重新部署只用当前本地 skill 包刷新项目文件，要拿 skill 本身的新版本得先更新 oh-story-claudecode（npx skills add 或 marketplace），再回来重跑
   • agents_version 大于 34 → 当前 story-setup 比项目部署旧；停止以避免降级覆盖，提示先更新 oh-story-claudecode，不写任何部署文件
   • 同时读 target_cli 字段。已部署项目以 sentinel 里的值为准：非空时（逗号分隔的多端组合原样保留）这些端照常重新部署，不再让作者选；第 4 步仍判断当前宿主：判断出来且不在其中（作者换了软件）→ AskUserQuestion 问「这个文件夹之前是给 {已部署宿主名} 装的，你现在用的是 {当前宿主名}，要一起装上吗？」（「一起装上（推荐）」「只更新原来的」），选前者就加进 target_cli；判断不出不问。字段缺失或为空才走第 4-6 步。用户明确要求增删目标端时，用 AskUserQuestion 在现有值基础上改，改完的值写回 sentinel。
   • target_cli 不含 opencode、但项目里有 .opencode/plugins/story-hooks.ts 或 .opencode/agents/（多端部署时 OpenCode 曾被版本门拦下）→ 用 AskUserQuestion 问是否把 OpenCode 加回来；选加回则先过 references/deploy-opencode.md 的「部署前置」，通过后写回 target_cli

2. 检查是否有书名目录（包含 追踪/ 子目录的目录，或用户自定义结构）

   • 有 → 识别为长篇项目，显示当前项目信息
   • 无 → 识别为新项目或短篇项目

3. 检查 .active-book 文件是否存在：存在 → 显示当前活跃书目；不存在 → 跳过

4. 判断当前宿主（能判断就不问作者）。依次看，第一条能定下来的就用：

   • 你自身的运行环境：系统提示、可用工具名或 skill 调用语法已表明你运行在 Claude Code、Codex、OpenCode、Google Antigravity（含命令行 agy）、ZCode、OpenClaw 或 Reasonix 里；
   • 正在执行的本 SKILL.md 的安装位置带有宿主专属目录（如 .claude/、.codex/、.zcode/、.gemini/、.openclaw/、.opencode/）；
   • 判断不出（例如网页版 AI、自建 Agent，或以上信号互相矛盾）→ 第 5 步的项目标记只当候选，交第 6 步问作者。

5. 看项目里已有哪些宿主的标记：

   • .claude/ 或 CLAUDE.md → target_cli = claude-code
   • opencode.json、opencode.jsonc 或 .opencode/ → target_cli = opencode
   • .codex/、.codex/config.toml、.codex/agents/、.codex/hooks.json、AGENTS.md 中的 Codex 段 → target_cli = codex
   • .agents/hooks.json、.agents/agents/，或 .agents/rules/oh-story.md 中的 Antigravity 标记 → target_cli = antigravity
   • .zcode/、.zcode/config.json、zcode.json、.zcode/skills/、.zcode/commands/、AGENTS.md 中的 ZCode 段 → target_cli = zcode
   • openclaw.json、.openclaw/，或 AGENTS.md 中的 OpenClaw 段（标题行含 网文写作工具集（OpenClaw））→ target_cli = openclaw
   • .reasonix/、reasonix-plugin.json、REASONIX.md，或 AGENTS.md 中的 Reasonix 段（标题行含 网文写作工具集（Reasonix））→ target_cli = reasonix
   • AGENTS.md 中的通用段（标题行含 网文写作工具集（通用 Agent / Web AI））→ target_cli = generic

   后三类只认各端互斥的标记：skills/*/SKILL.md 的 metadata.openclaw 不作 OpenClaw 信号（13 个 skill 都带，三条 skills-only 路径部署出的 skills/ 一样）；.agents/skills/ 由 Antigravity、Codex 与 Reasonix 共用，也不单独作准。

6. 定下 target_cli：

   • 第 4 步定出了当前宿主 → target_cli 就是它。项目里另有其他宿主的标记时，用 AskUserQuestion 问一句白话：「这个文件夹之前也给 {其他宿主名} 装过写作工具，这次要一起更新吗？」选项：「只装 {当前宿主名}（推荐）」「一起更新」。作者一开始就说要装多个时照办。
   • 定不出、项目标记恰好只有一个宿主 → AskUserQuestion 问「上次是给 {宿主名} 装的，这次还是它吗？」，是就用它，不是按下一条问。
   • 定不出、其余情况 → 用 AskUserQuestion 问：「你现在是在哪个软件里跟我对话？」选项用产品名加一句说明：Claude Code（Anthropic 的命令行 / 桌面版）、Codex（OpenAI 的命令行）、OpenCode、Google Antigravity（含命令行 agy）、ZCode、OpenClaw、Reasonix（DeepSeek 的命令行）、网页版 AI 或其他工具（NarraFork、自建 Agent 等）、好几个都要用。提问工具一次放不下这么多选项时，把项目标记里出现过的放前面，其余让作者在「其他」里直接写名字。
   • 作者的答案按「Claude Code → claude-code、网页版 AI 或其他工具 → generic、其余取小写产品名」换成 target_cli；多端为 claude-code,opencode,codex,antigravity,zcode,openclaw,reasonix,generic 中选中的端。

7. 确认项目根（通常不问）：项目根就是当前工作目录。只有当前目录是用户主目录、磁盘根目录、系统目录，或就是本 skill 包自身的安装/源码目录时，才用一句白话问作者：「写作工具要装在哪个文件夹？一般就是放书稿的那个文件夹。」其他情况直接部署，在安装报告的「部署明细」里写明装在哪。

Phase 2：部署基础设施

整个 Phase 2 幂等：目录复制、文件写入和各宿主部署文件里的合并算法重复执行结果一致。因环境原因（工具不可用、权限被拒、网络失败）中途失败时，直接从头重跑本 Phase，不需要先清理半成品；create only if absent 的用户状态文件（见各部署清单的 Owner class）不会被二次覆盖。

两列基准目录不同：部署清单里 Source path 相对正在执行的这份 skill 包，Target path 相对用户项目根。执行每一行（以及各宿主部署算法里的每个递归复制步骤）之前，先把通配符具体化为单个源/目标，再用本 SKILL.md 同级的 scripts/copy-path-safety.py 检查。该脚本按 Path.resolve / realpath 语义跟随已有 symlink，并在两侧都存在时用 samefile 核对文件系统对象；只转绝对路径或比较字符串不算检查完成。读取其 JSON：status: same 时 no-op，禁止复制；仅 copy_allowed: true 时可以复制；source_missing、unsafe_target_within_source 或 filesystem_identity_error 必须停止该步骤并报告。无法运行脚本时只能用当前环境的文件系统 API 做完全相同的 canonical realpath、same-object 与 target-descendant 检查；无法确认就停止，不得尝试复制。OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝，重跑时执行的就是项目里那份；Reasonix / Codex 还可能经 .agents/skills → ../skills symlink 加载，路径文本不同也可能指向同一目录，照字面复制会把目录嵌进自身并撑满磁盘。

部署前清理自嵌套残留：{.claude,.codex,.zcode}/skills/story-setup/references/agent-references/ 与项目根 skills/story-setup/references/agent-references/ 里若多出 agent-references/ 层（可能嵌了多层），以及 skills/story-setup/skills/，整段删掉再部署，并在安装报告里列出删掉的路径。

Step 1：按宿主部署

对 target_cli 里的每个宿主，完整读取对应部署文件，按其中的部署清单（机械可检查）与算法依次执行；不读其他宿主的文件。

多端部署时几个宿主共用根 AGENTS.md，按下方「AGENTS.md 合并策略」合并成一份；某一端被自己的前置条件拦下（如 OpenCode 版本门、Antigravity 缺 Node）时，按该端部署文件的规定处理，其他端照常部署。