Story Setup

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

你是写作基础设施部署器。将网文写作工具集的全套基础设施（hooks、rules、agents、CLAUDE.md、AGENTS.md、Codex/OpenClaw 配置）部署到用户项目目录。

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

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 让用户选择目标 CLI（选项：仅 Claude Code / 仅 OpenCode / 仅 Codex / 仅 OpenClaw / 任意组合）
9. 如四者都不存在（全新项目）→ 使用 AskUserQuestion 让用户选择目标 CLI
   • 用户选择 opencode → target_cli = opencode，部署时创建 opencode.json 和 .opencode/
   • 用户选择 claude-code → 按现有逻辑处理
   • 用户选择 codex → target_cli = codex，部署时创建 .codex/
   • 用户选择 openclaw → target_cli = openclaw，部署时复制 OpenClaw 兼容 skills 到项目 skills/
   • 用户选择多端 → target_cli = claude-code,opencode,codex,openclaw（仅包含用户选择的端）

Phase 2：部署基础设施

使用 AskUserQuestion 确认部署位置后，依次执行。

2.0 部署清单（机械可检查）

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 的版本检测结果重新部署
• 部署后必须新开会话：Claude Code 只在会话启动时扫描 .claude/agents/ 注册 subagent。当前会话内新部署的 agent 不会立即可用——必须让用户新开一个 Claude Code 会话，story-architect/narrative-writer 等 custom agent 才会注册成 subagent_type；否则 story-review、story-long-write 等想 spawn 时会拿到「subagent_type 不可用」并降级 solo（单视角）。这一步必须在安装报告里明确告知用户（见 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（consistency-checker、story-explorer）必须保留 sandbox_mode = "read-only"
• 部署后必须 trust + 新开 Codex 会话：Codex custom agents 位于 .codex/agents/*.toml，项目 .codex/ 配置层需要被 trust；部署后需要新会话/刷新后才可能稳定暴露给 spawn。若运行时返回 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）。

• 一个模型可能匹配多个等级的关键词，取最高等级
• 关键词回退下未匹配任何关键词的模型仍列入候选附加建议（按成本分级则一律纳入），并在安装报告列出，提示"可通过自定义输入使用"
• 同一等级内，如果包含多个模型供应商，优先列出知名供应商（anthropic、openai、google、deepseek）的模型

Step 3：逐级交互选择

按 低端 → 中端 → 高端 顺序，每级用 AskUserQuestion 让用户选择。

低端选项结构：

问题："为低成本 Agent（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 弹出，选项至少含：候选模型（如有）、自定义输入、保留现有模型（Step 0 缓存到该 agent 的 model，无则不显示此项）、跳过，用主模型。候选为 0 时仍弹窗，并在问题说明里给出对应警告 + 列出未分级/未入档模型供参考——不再静默跳过交互（否则用户够不到自定义输入）。
• 自定义输入：用户输入 provider/model-id 完整 ID；写入前校验为单行、无控制字符、匹配 ^[A-Za-z0-9._-]+/[A-Za-z0-9._:+-]+$，不符则提示重输或改选跳过。
• 保留现有模型：写回 Step 0 缓存的该 agent model（重新部署时保住用户上次配置），不算"跳过"。
• 跳过，用主模型：显式清除——不写该 agent 的 model:，agent 继承主模型。想保留上次配置请选 保留现有模型。
• 各级候选为 0 时在问题说明里给出提示：
  • 低端："未检测到低成本模型，这 3 个 agent 将使用主模型，成本可能较高"
  • 中端："未检测到匹配的中端模型。narrative-writer、character-designer、story-researcher 将使用主模型。如主模型质量足够此配置合理；如需降本，请用自定义输入指定不低于主模型质量的中端模型，或从下方未分级模型里选。"
  • 高端："未检测到高端模型，story-architect 将使用主模型"

Step 4：写入 model 字段

对应用户选择的 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
---

• 如果 agent 文件已有 model: 字段（重新部署场景），替换该顶层 model: 的值，不新增重复键
• 保留现有模型：写回 Step 0 缓存的该 agent model
• 跳过，用主模型：不写入 model: 字段
• 检测失败/超时、没走到本步骤的等级：用 Step 0 缓存回填 model:，避免 replace 抹掉用户上次配置

2.5 部署 Session State 模板

• 读取 skills/story-setup/references/templates/上下文.md.tmpl
• 仅当已识别为长篇书目且 {书名}/追踪/ 已存在时，创建缺失的 {书名}/追踪/上下文.md
• 如果目标文件已存在，不覆盖；短篇项目不得因此创建 追踪/ 目录

2.6 合并 Hooks 注册到 settings.local.json

兼容性说明：settings-hooks.json 中 PreToolUse 的 if 字段使用 Claude Code hook 条件语法，需要运行环境支持 hook-level if。若目标工具不支持该字段，hook 脚本本身仍会自检并 advisory-only 退出；部署时可删除该 if 字段并保留 matcher + command。

• 读取 skills/story-setup/references/templates/settings-hooks.json
• 读取用户项目的 .claude/settings.local.json（如存在）
• 合并 hooks 配置（按「settings-hooks.json 合并算法」处理）
• 写入 .claude/settings.local.json

Codex hooks.json 合并算法（target_cli 含 codex 时）

Codex 项目 hooks 部署到 .codex/hooks.json，hook 脚本部署到 .codex/hooks/story_codex_hook.py。

1. 读取 skills/story-setup/references/codex/hooks/hooks.json
2. 读取用户现有 .codex/hooks.json（如存在），提取 hooks 部分
3. 对每个 hook event（SessionStart、PreToolUse、PreCompact、PostCompact、Stop）按 command 去重追加；每个 hook 同时携带 command（POSIX sh，Unix）与 commandWindows（cmd.exe，Windows）两个字段，整体保留不要拆开
4. 保留用户已有其他 hooks/config，不覆盖未知字段
5. 写入 .codex/hooks.json 后提示用户：项目 .codex/ 层需要被 Codex trust，非 managed command hooks 还需要在 /hooks 中 review/trust 后才会运行；Windows 下 Codex 以 cmd.exe 跑 hook，走 commandWindows（cwd 为项目根时生效，否则 no-op），正文守卫在 Windows 非项目根目录下不强制拦截