story-setup

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

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

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

交互工具兼容门：本 Skill 中的 AskUserQuestion 表示“必须让用户做选择”，不表示必须存在同名工具。当前运行时未暴露该工具时（包括部分 TRAE Code、WorkBuddy / CodeBuddy Code、Web AI 会话），主 Agent 必须在当前主对话中直接提出同一个简短问题并等待回答；不得因工具缺失跳过确认、伪造已选结果或让子 Agent 代替提问。

---

Phase 1：检测项目状态

先自检参考目录：以正在执行的本 SKILL.md 所在目录为准，列出与它同级的 references/ 下的子目录，核对下面 10 个名字是否都在且都非空——agent-references、templates、opencode、codex、zcode、trae、workbuddy、openclaw、reasonix、generic；同级 scripts/merge-claude-settings.py、scripts/merge-codex-hooks.py、scripts/merge-trae-hooks.py、scripts/trae-core-ownership.py、scripts/merge-workbuddy-settings.py 与 scripts/copy-path-safety.py 也必须存在（Claude/Codex/TRAE/WorkBuddy hooks 合并、shared-core 归属验证与递归复制安全预检依赖它们）。有缺即 skill 包没装全，立即停止，不写任何部署文件，报告里区分「缺目录」和「目录为空」，并给修复指令：「story-setup 参考资料包不完整，缺 {目录名}。按你的安装方式重装 oh-story-claudecode（命令行装的重跑 npx skills add https://github.com/qin1473692580-ux/oh-story-claudecode/releases/latest/download/oh-story-release.zip -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 / TRAE Code / WorkBuddy / CodeBuddy Code / OpenClaw / Reasonix / generic 的项目副本是整份 skill 拷贝、自带 SKILL.md，10 个子目录本就齐全，照常核对即可。

1. 检查当前目录是否已部署过（存在 .story-deployed）
   • agents_version 缺失、非整数或小于 39 → 标记为待更新，继续执行当前部署
   • agents_version: 39 → 使用 AskUserQuestion 确认是否重新部署；提示里写明重新部署只用当前本地 skill 包刷新项目文件，要拿 skill 本身的新版本得先用固定 GitHub Release 资产重跑 npx skills add https://github.com/qin1473692580-ux/oh-story-claudecode/releases/latest/download/oh-story-release.zip -y -g，再回来重跑
   • agents_version 大于 39 → 当前 story-setup 比项目部署旧；停止以避免降级覆盖，提示先更新 oh-story-claudecode，不写任何部署文件
   • 同时读 target_cli 字段。已部署项目以 sentinel 里的值为准：非空时（逗号分隔的多端组合原样保留）跳过下面第 5-14 步的环境探测与选择，直接按这些端重新部署。只有字段缺失或为空，才回落到探测。用户明确要求增删目标端时，用 AskUserQuestion 在现有值基础上改，改完的值写回 sentinel。
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. 检查 .zcode/、.zcode/config.json、zcode.json、.zcode/skills/、.zcode/commands/、AGENTS.md 中的 ZCode 段
   • 存在 → 识别为 ZCode 项目，target_cli = zcode
   • 不存在 → 跳过
8. 检查 .trae/、.trae/hooks.json、.trae/skills/、.trae/agents/、.trae/commands/、.trae/rules/，或 AGENTS.md 中的 TRAE 段（标题行含 网文写作工具集（TRAE Code））
   • 存在 → 识别为 TRAE Code 项目，target_cli = trae
   • 不存在 → 跳过
9. 检查 .codebuddy/、.codebuddy/settings.json、.codebuddy/skills/、.codebuddy/agents/、.codebuddy/commands/、.codebuddy/rules/，或 .codebuddy/CODEBUDDY.md / 根 CODEBUDDY.md / 根 AGENTS.md 中的 oh-story WorkBuddy 管理段
   • 存在 → 识别为 WorkBuddy / CodeBuddy Code 项目，target_cli = workbuddy
   • 不存在 → 跳过
10. 检查 openclaw.json、.openclaw/，或 AGENTS.md 中的 OpenClaw 段（标题行含 网文写作工具集（OpenClaw））

• 存在 → 识别为 OpenClaw 项目，target_cli = openclaw
• 不存在 → 跳过

11. 检查 .reasonix/、reasonix-plugin.json、REASONIX.md，或 AGENTS.md 中的 Reasonix 段（标题行含 网文写作工具集（Reasonix））

• 存在 → 识别为 Reasonix 项目，target_cli = reasonix
• 不存在 → 跳过

12. 检查 AGENTS.md 中的通用段（标题行含 网文写作工具集（通用 Agent / Web AI））

• 存在 → 识别为通用 Web AI 项目，target_cli = generic
• 不存在 → 跳过

手順 8～12 では、各環境に固有の相互排他的なマーカーのみを認識します。skills/*/SKILL.md の metadata.openclaw は OpenClaw のシグナルとして扱いません。canonical 中文主包 Skill はすべてこのフィールドを含んでいます。また、OpenClaw／Reasonix／generic の skills-only 経路でデプロイされる skills/ の内容は同じであり、このフィールドを判定に使うと、後者の 2 つもすべて OpenClaw と誤認します。.agents/skills/ も同様に Codex と Reasonix で共有されているため、それだけでは判定しません。TRAE は .trae/ または TRAE 専用のタイトル行のみを認識します。WorkBuddy は .codebuddy/ またはその CODEBUDDY 管理セクションのみを認識します。skills-only の 3 環境を区別する決め手は、それぞれの AGENTS.md テンプレートのタイトル行です。

13. .claude/ または CLAUDE.md、OpenCode、Codex、ZCode、TRAE Code、WorkBuddy / CodeBuddy Code、OpenClaw、Reasonix、generic のマーカーが同時に存在する場合 → AskUserQuestion を使用して、ユーザーに対象環境を選択してもらいます（選択肢：Claude Code / OpenCode / Codex / ZCode / TRAE Code / WorkBuddy / CodeBuddy Code / OpenClaw / Reasonix / 汎用 Web AI またはその他の Agent / 任意の組み合わせ）。
14. 9 種類のマーカーがいずれも存在しない場合（新規プロジェクト）→ AskUserQuestion を使用して、ユーザーに対象環境を選択してもらいます。

• ユーザーが opencode を選択した場合 → target_cli = opencode。デプロイ時に opencode.json と .opencode/ を作成します。
• ユーザーが claude-code を選択した場合 → 既存のロジックに従って処理します。
• ユーザーが codex を選択した場合 → target_cli = codex。デプロイ時に .codex/ を作成します。
• ユーザーが zcode を選択した場合 → target_cli = zcode。デプロイ時に .zcode/ を作成し、ルートの AGENTS.md をマージします。プロジェクトの custom agents は作成しません。
• ユーザーが TRAE Code を選択した場合 → target_cli = trae。デプロイ時に .trae/ を作成してルートの AGENTS.md とマージし、.trae/hooks.json を作成します。ネイティブの Skills / Subagents / Commands / Rules / Hooks をデプロイします。
• ユーザーが WorkBuddy / CodeBuddy Code を選択した場合 → target_cli = workbuddy。デプロイ時に .codebuddy/ を作成し、「WorkBuddy memory マージ戦略」に従って使用する memory ファイルを 1 つ選択して .codebuddy/settings.json をマージし、ネイティブの Skills / Agents / Commands / Rules / Hooks をデプロイします。
• ユーザーが 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,trae,workbuddy,openclaw,reasonix,generic の部分集合（ユーザーが選択した環境のみを含みます）。

フェーズ 2：インフラストラクチャのデプロイ

AskUserQuestion を使用してデプロイ先を確認した後、順番に実行します。

フェーズ 2 全体は冪等です。ディレクトリのコピー、ファイルの書き込み、および以下の表の各マージアルゴリズムを繰り返し実行しても、結果は変わりません。環境上の理由（ツールが使用できない、権限が拒否された、ネットワークエラーなど）で途中失敗した場合は、このフェーズを最初から再実行してください。途中まで作成されたファイルを事前に削除する必要はありません。create only if absent のユーザー状態ファイル（以下の表の Owner class を参照）は、2 回目以降の実行で上書きされません。

Step 1：デプロイ項目（機械的に検証可能）

再帰コピーの安全性を事前検証（ディレクトリの replace/copy より前に実施）：まず、Source path を「実行中の story-setup skill パッケージ」内の絶対パスとして解決し、Target path をユーザープロジェクト内の絶対パスとして解決します。次に、利用可能な python3/python/py を使って scripts/copy-path-safety.py <source> <target> を実行します。JSON の結果を読み取ります。

• status=safe：パスが互いに包含されていない場合に限り、その項目のコピーを続行できます。
• status=same：ソースとターゲットが realpath/samefile で同一のオブジェクトを指しています。その項目を冪等な no-op として記録し、再帰コピーを行ってはなりません。
• status=unsafe：ターゲットがソース内にあるか、ソースがターゲット内にあります。フェーズ 2 全体を直ちに停止し、削除や上書きを行わず、reason と 2 つの realpath を報告します。
• status=error：ソースが存在しないか、パスの解決に失敗しました。デプロイパッケージが不完全なものとして扱い、直ちに停止します。

この事前検証の代わりに、文字列のプレフィックス、展開されていない相対パス、または「同じディレクトリには見えない」という判断を使ってはなりません。symlink/alias は realpath に基づいて判定する必要があります。ファイル単位の replace は既存の原子的な書き込みルールに従って続行できます。再帰的なディレクトリコピーはすべて、項目ごとにこの検証を通過する必要があります。

TRAE の所有権とバックアップのゲート（target_cli に trae が含まれる場合）：既存の .trae/ ファイルを変更する前に、今回変更する元ファイルを相対パスに従って .trae/.oh-story-backups/<UTC時刻のタイムスタンプ>/ にバックアップします。バックアップディレクトリ自体にも、事前に copy-path-safety.py を実行する必要があります。置き換えが許可されるのは、oh-story-managed マーカーが付いた canonical 中文主包 skill / command / agent / rule / AGENTS 管理ブロック、ヘッダーコメントに oh-story TRAE adapter と明記された story_trae_hook.js、および次の所有権証拠のいずれかを満たす story_hook_core.js のみです。所有権証拠は、汎用マーカー oh-story-managed: shared-hook-core を含むこと、scripts/trae-core-ownership.py で検証した後に sha256 が一意の正規ファイル references/trae/legacy-managed-sha256.json と一致すること、または同じプロジェクト内で検証済みの Claude/OpenCode/ZCode oh-story shared core とバイト単位で一致することです。Skill ディレクトリの所有権証拠は、SKILL.md の metadata.openclaw.source がこのリポジトリを指していること、または正確なマーカー `` です。所有権証拠のない同名のユーザーファイルは保持し、競合を報告する必要があります。上書きしてはなりません。.trae/hooks.json は常に helper を使って安定した command identity に基づいてマージし、ファイル全体を置き換えてはなりません。新たに作成する成果物には、次回安全にアップグレードできるよう、対応する管理マーカーを書き込む必要があります。

TRAE と Claude の Hook 重複実行防止ゲート：TRAE はプロジェクトの .claude/settings*.json を互換性のために読み取ります。Claude settings のコマンドは、クロスプラットフォームで実行可能な直接の bash ... 形式を維持し、POSIX の if を埋め込んではなりません。すべての Claude shell エントリーポイントは source lib/common.sh の後に共通ライブラリで TRAE_PROJECT_DIR を検出し、成功として無言で終了します。Claude では通常どおり実行し、TRAE プロセス内では .trae/hooks.json のみが実行します。デプロイ後は両環境の合成入力を使って、同じイベントから oh-story の出力が 1 組だけ生成されることを検証します。「二重のプロンプトが同じように見える」ことを許容可能と判断してはなりません。 WorkBuddy 归属与 Hook 互斥门（target_cli 含 workbuddy 时）：只替换带 oh-story-managed 标记的 canonical 中文主包 skill / command / agent / rule / CODEBUDDY（或 AGENTS）管理块，以及带适配器头注释或通用 shared-core 标记的 hook 文件；Skill 目录使用与 TRAE 相同的仓库 metadata / `` 双证据。同名用户文件保留并报告冲突。.codebuddy/settings.json 只通过 merge-workbuddy-settings.py 合并。若当前 skill 来自已启用的 oh-story CodeBuddy plugin（实际执行路径位于插件安装根，或当前会话 registry / codebuddy plugin list 明确显示 oh-story 已启用），plugin hooks 会自动加载，此时必须用空模板移除项目内旧的 oh-story-managed hook 注册，不能再合并 project-hooks.json；只有 project-local skills 模式才写项目 hooks，防止同一事件双触发。仓库里存在 .codebuddy-plugin/plugin.json 或插件曾经安装过都不算“当前已启用”的证据。

WorkBuddy 命名空间门：plugin 模式只由 .codebuddy-plugin/plugin.json 暴露 Skills、Agents 与 Hooks；不得同时在 manifest 暴露与 Skills 同名的 Commands，否则 /oh-story:story-* 会发生组件名竞争。plugin 模式调用 /oh-story:story、/oh-story:story-long-write 等命名空间化 Skill；运行 story-setup 后的项目模式才由 .codebuddy/commands/ 暴露 /story、/story-long-write 等裸命令。两种模式必须在安装报告中分开写，不能把裸命令说成 plugin 命令。

ソースパス	配置先パス	所有者クラス	マージモード	検証チェック
skills/story-setup/references/templates/CLAUDE.md.tmpl	CLAUDE.md	user+managed	マーカー／セクションマージ	ストーリースキルのルーティングセクションを含む
skills/story-setup/references/templates/hooks/	.claude/hooks/	story-setup managed	再帰的に置換	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 が存在する；story_hook_core.js は OpenCode/ZCode の複製とバイト単位で一致する
skills/story-setup/references/templates/rules/*.md	.claude/rules/*.md	story-setup managed	置換	すべてのルールに paths フロントマターが含まれる
skills/story-setup/references/templates/agents/*.md	.claude/agents/*.md	story-setup managed	置換	8 個のエージェントファイルが存在する
skills/story-setup/references/agent-references/*.md	.claude/skills/story-setup/references/agent-references/*.md	story-setup managed	置換	すべての story-setup/references/agent-references/*.md 参照が解決される
skills/story-setup/references/templates/settings-hooks.json	.claude/settings.local.json	user+managed	安定したフック ID で管理対象の登録を置換	フック JSON が有効；古い matcher 登録が移行され、現在のテンプレートコマンドがそれぞれ 1 つだけあり、ユーザーフックが保持される
skills/story-setup/scripts/merge-claude-settings.py	デプロイ時に実行し、プロジェクトにはコピーしない	story-setup helper	実行	既知の story hook 登録を置換し、ユーザーフック／トップレベルフィールドを保持する。過去の matcher を移行し、繰り返し実行しても冪等
skills/story-setup/references/templates/质检进度.md.tmpl	{书名}/追踪/质检进度.md	user state	存在しない場合のみ作成	既存の進捗テーブルは決して上書きしない
生成された sentinel	.story-deployed	story-setup managed	置換	agents_version、setup_skill_version、target_cli、resolver_strategy、references_dir を含む
skills/story-setup/references/opencode/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	ストーリースキルのルーティングセクションを含む
skills/story-setup/references/opencode/agents/	.opencode/agents/	story-setup managed	置換	8 個のエージェントファイルが存在する（置換前に「OpenCode Agent モデルの設定」の「既存のモデル設定を保持」に従って既存の model: をキャッシュし、ユーザーが設定済みのモデルを上書きしない）
skills/story-setup/references/opencode/plugin.ts	.opencode/plugins/story-hooks.ts	story-setup managed	置換	TypeScript プラグインファイルが存在する
skills/story-setup/references/opencode/story_hook_core.js	.opencode/plugins/lib/story_hook_core.js	story-setup managed	置換	Node の構文が有効；ZCode の複製とバイト単位で一致する；story-hooks.ts によって import される
skills/story-setup/references/opencode/commands/	.opencode/commands/	story-setup managed	置換	コマンド数が現在の OpenCode テンプレート一覧と一致する
skills/story-setup/references/opencode/opencode.json.patch	opencode.json にマージ	user+managed	プラグイン／権限キーでマージ	プラグインエントリが登録される
skills/story-setup/references/agent-references/	skills/story-setup/references/agent-references/	story-setup managed	置換	すべての参照が解決される
skills/story-setup/references/opencode/pre-commit.sh	.git/hooks/pre-commit	user+managed	追記または作成	ファイルが存在し、実行可能；マーカーブロックがある場合はブロックの内容を置換し、ない場合は exit 0 の位置を検出して適切な場所に挿入する
skills/story-setup/references/codex/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	Codex のストーリースキルルーティングセクションを含む
skills/story-setup/references/codex/agents/	.codex/agents/	story-setup managed	置換	8 個の TOML エージェントファイルが解析でき、name／description／developer_instructions を含む
skills/story-setup/references/codex/hooks/hooks.json	.codex/hooks.json	user+managed	安定したフック ID で管理対象の登録を置換	フック JSON が有効；古い直接登録／ランチャー登録がすべて削除され、現在の 6 個の登録がそれぞれ 1 つだけ存在する
skills/story-setup/references/codex/hooks/{story_codex_hook.py,run-story-hook.sh,run-story-hook.cmd}	.codex/hooks/ 内の同名ファイル	story-setup managed	置換	Python／シェル／cmd ランチャーファイルがすべて揃っている
skills/story-setup/scripts/merge-codex-hooks.py	デプロイ時に実行し、プロジェクトにはコピーしない	story-setup helper	実行	既知の管理対象登録を置換し、ユーザーフックと未知のトップレベルフィールドを保持する。結果は冪等
skills/story-setup/scripts/copy-path-safety.py	再帰的なディレクトリコピーの前に毎回実行し、プロジェクトにはコピーしない	story-setup helper	実行	同一なら何もしない；祖先／子孫の入れ子ならブロック；安全な場合のみコピー可能
skills/story-setup/references/agent-references/	.codex/skills/story-setup/references/agent-references/	story-setup managed	置換	すべての参照が解決される
skills/story-setup/references/zcode/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	ZCode の $story-* ルーティングと単独利用時のフォールバックを含む
正規リポジトリの skills/{browser-cdp,story*}/	.zcode/skills/{browser-cdp,story*}/	既知の 18 個のスキル名について story-setup managed	既知のスキルディレクトリのみ置換	SKILL.md の名前一覧が中国語メインパッケージの 18 個の Skill 一覧と一致し、ZCode のフロントマター制約を満たす
skills/story-setup/references/zcode/commands/	.zcode/commands/	既知の 18 個のコマンド名について story-setup managed	既知のコマンドファイルのみ置換	コマンド名／フロントマターが有効で、正規スキル一覧を網羅する
skills/story-setup/references/zcode/hooks/story_zcode_hook.js	.zcode/hooks/story_zcode_hook.js	story-setup managed	置換	Node の構文が有効；フックの契約テストに合格する
skills/story-setup/references/zcode/hooks/story_hook_core.js	.zcode/hooks/story_hook_core.js	story-setup managed	置換	Node の構文が有効；フックの契約テストに合格する
skills/story-setup/references/zcode/config.json.patch	.zcode/config.json にマージ	user+managed	イベント＋matcher＋プロセス引数でマージ	JSON が有効；「ZCode デプロイアルゴリズム」の第 4 ステップにあるフックの相互排他分岐に従って検証する——oh-story プラグイン未導入時は hooks.enabled=true かつサポート対象イベントのみ；プラグイン導入済みの場合は .zcode/config.json にこの oh-story フック登録群が含まれない（または削除済みである）ことを検証する
skills/story-setup/references/trae/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	TRAE Code のストーリールーティングとフォールバックの契約を含む
正規リポジトリの skills/{browser-cdp,story*}/	.trae/skills/{skill-name}/	固定された 18 個のソース名について story-setup managed	バックアップ＋管理対象ディレクトリのみ置換	対象の SKILL.md の数／名前が中国語メインパッケージの 18 個の Skill 一覧と一致する；ソースと対象が同一なら何もしない
skills/story-setup/references/trae/commands/	.trae/commands/{skill-name}.md	oh-story-managed マーカーで story-setup managed	管理対象の 18 個のファイルのみバックアップ＋置換	各正規スキルに同名のコマンドがちょうど 1 つあり、フロントマターに name／description を含む
skills/story-setup/references/trae/agents/	.trae/agents/	oh-story-managed マーカーで story-setup managed	汎用エージェント名簿（8 件）のみバックアップ＋置換	名前一覧が正確に chapter-extractor、character-designer、consistency-checker、narrative-writer、revision-governor、story-architect、story-explorer、story-researcher である；TRAE フロントマターが解析可能
リポジトリの skills/story-data-analyze/agents/trae/	.trae/agents/	oh-story-managed マーカーで story-setup managed	データエージェント名簿（5 件）のみバックアップ＋置換	名前一覧が正確に story-data-fetcher、story-data-method-validator、story-data-metrics-analyst、story-data-supervisor、story-data-text-improvement-planner である；汎用ロールと名前が重複しない
skills/story-setup/references/trae/rules/	.trae/rules/	oh-story-managed マーカーで story-setup managed	管理対象ファイルのみバックアップ＋置換	ルールのフロントマターに alwaysApply／globs を含む
skills/story-setup/references/trae/hooks/{story_trae_hook.js,story_hook_core.js}	.trae/hooks/ 内の同名ファイル	アダプターヘッダーでランナーを判定；固定名＋パッケージ化されたハッシュでコアを判定	管理対象ファイルのみバックアップ＋置換	Node の構文が有効；共有コアが他のアダプターの複製と一致する
skills/story-setup/references/trae/hooks/hooks.json	.trae/hooks.json	user+managed	安定したフックコマンド ID で管理対象の登録を置換	version: 1；TRAE がサポートするイベントのみを含む；ユーザーフック／トップレベルフィールドを保持する
skills/story-setup/scripts/merge-trae-hooks.py	デプロイ時に実行し、プロジェクトにはコピーしない	story-setup helper	実行	古い matcher／command を移行し、ユーザー設定を保持する。繰り返し実行してもバイト単位で同一
skills/story-setup/scripts/trae-core-ownership.py + references/trae/legacy-managed-sha256.json	デプロイ時に実行し、プロジェクトにはコピーしない	story-setup 所有権ヘルパー／レジストリ	置換前に分類	マーカー／レガシー SHA で管理対象と判定；不明なもの／エラーは保持して報告する
skills/story-setup/references/workbuddy/CODEBUDDY.md.tmpl	既存の CODEBUDDY.md／.codebuddy/CODEBUDDY.md、またはいずれもない場合は AGENTS.md／.codebuddy/CODEBUDDY.md	user+managed	「WorkBuddy メモリのマージ戦略」に従い、マーカーブロックのみマージ	既存の AGENTS を覆い隠さない；条件付きインポートのプレースホルダーが解決済み；管理ブロックが 1 つだけある
正規リポジトリの skills/{browser-cdp,story*}/	.codebuddy/skills/{skill-name}/	固定された 18 個のソース名について story-setup managed	管理対象ディレクトリのみ置換	SKILL.md の名前一覧が中国語メインパッケージの 18 個の Skill 一覧と一致する；ソースと対象が同一なら何もしない
skills/story-setup/references/workbuddy/commands/	.codebuddy/commands/{skill-name}.md	oh-story-managed マーカーで story-setup managed	管理対象の 18 個のファイルのみ置換	コマンドが正規スキルと 1 対 1 で対応し、フロントマターでは CodeBuddy がサポートするフィールドのみを使用する
skills/story-setup/references/workbuddy/agents/	.codebuddy/agents/	マーカーで story-setup managed	汎用エージェント名簿（8 件）のみ置換	名前一覧が正確に chapter-extractor、character-designer、consistency-checker、narrative-writer、revision-governor、story-architect、story-explorer、story-researcher である；WorkBuddy のフロントマターが有効で、プロジェクトの Agent 名にプラグインの名前空間が付いていない
リポジトリの skills/story-data-analyze/agents/workbuddy/	.codebuddy/agents/	マーカーで story-setup managed	データ用の物理エージェント名簿（2 件）のみ置換	名前一覧が正確に story-data-fetcher、story-data-readonly-runner である；論理ロールカード 4 件は Skill の references に残す
skills/story-setup/references/workbuddy/rules/	.codebuddy/rules/	マーカーで story-setup managed	管理対象ファイルのみ置換	alwaysApply が解析可能；ユーザーのルールを保持する
skills/story-setup/references/workbuddy/hooks/{story_workbuddy_hook.js,story_hook_core.js}	.codebuddy/hooks/ 内の同名ファイル	story-setup managed	管理対象ファイルのみ置換	Node の構文が有効；共有コアがバイト単位で一致する
skills/story-setup/references/workbuddy/hooks/project-hooks.json	.codebuddy/settings.json にマージ	user+managed	プラグインの相互排他に応じてマージまたは削除	プロジェクトローカルモードでは各登録が 1 つだけあり、プラグインモードでは 0 件；ユーザー設定とフックを保持する
skills/story-setup/scripts/merge-workbuddy-settings.py	デプロイ時に実行し、プロジェクトにはコピーしない	story-setup helper	実行	安定したランナー ID で古い登録を削除し、マージ／削除は冪等
skills/story-setup/references/openclaw/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	OpenClaw のストーリースキルルーティングセクションを含む
skills/story-setup/references/generic/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	汎用ストーリースキルルーティングセクションを含む
skills/story-setup/references/reasonix/AGENTS.md.tmpl	AGENTS.md	user+managed	マーカー／セクションマージ	Reasonix のストーリースキルルーティングセクションと単独／直接利用時のフォールバックを含む
正規リポジトリの skills/{browser-cdp,story*}/	skills/{browser-cdp,story*}/	既知の 18 個のスキル名について story-setup managed	既知のスキルディレクトリのみ置換	SKILL.md の名前一覧が中国語メインパッケージの 18 個の Skill 一覧と一致する；OpenClaw 分岐の検証がフロントマターと互換性がある
skills/story-setup/references/agent-references/	skills/story-setup/references/agent-references/	story-setup managed	スキル全体のコピーで置換	すべての参照が解決される

opencode.json 合并算法

部署 opencode.json.patch 时按以下规则合并：

1. 读取现有 opencode.json（如存在），解析 JSON
2. 合并 plugin 数组：将 ./.opencode/plugins/story-hooks.ts 加入数组，去重
3. 保留用户已有的其他配置字段（permission、model、provider 等），不覆盖
4. 写入合并后的 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、TRAE 的 .trae/agents/*.md 和 WorkBuddy 的 .codebuddy/agents/*.md 均使用对应 adapter 下的预生成产物，不得直接复制别端 frontmatter。TRAE 通用角色的唯一来源是 references/trae/agents/，数据分析角色的唯一来源是 skills/story-data-analyze/agents/trae/；WorkBuddy 对应来源为 references/workbuddy/agents/ 与 skills/story-data-analyze/agents/workbuddy/。不把 Claude 模型别名或某一端的专有字段机械带入另一端。OpenCode/Codex/WorkBuddy 预生成产物由仓库维护脚本生成；这些脚本不随 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/，TRAE Code 为 .trae/skills/，WorkBuddy / CodeBuddy Code 为 .codebuddy/skills/；插件模式可用由平台内联的 ${CODEBUDDY_PLUGIN_ROOT}/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、revision-governor、story-explorer）必须保留 sandbox_mode = "read-only"
• 部署后必须 trust + 新开 Codex 会话（报告文案与 fallback 规则见「验证 Codex 部署」）；若运行时返回 unknown agent_type，调用方必须降级 solo/direct 并报告 fallback。
• 将 skills/story-setup/references/agent-references/ 同步复制到 .codex/skills/story-setup/references/agent-references/，作为 Codex agent 的项目内参考资料主路径

部署 TRAE Agents（target_cli 含 trae 时）

• 先校验 references/trae/agents/ 的名字集精确为 chapter-extractor, character-designer, consistency-checker, narrative-writer, revision-governor, story-architect, story-explorer, story-researcher（8 张通用卡），再校验 canonical story-data-analyze/agents/trae/ 的名字集精确为 story-data-fetcher, story-data-method-validator, story-data-metrics-analyst, story-data-supervisor, story-data-text-improvement-planner（5 张数据卡）。两组必须无重名，合并后名册精确为 13 张；任一必需目录缺失、为空、名字集不等、重名或 frontmatter 不可解析时停止 TRAE 分支，不进行半套部署。
• 依次写入 .trae/agents/，只新建或替换带 `` 标记的同名文件；无标记同名文件保留并报告。不删除用户其他 agents。
• TRAE frontmatter 只用其原生字段：name、description、逗号字符串形式的 tools / disallowedTools 以及可选的 TRAE 内置 model；禁止自动把 Claude 模型别名写入。
• 部署后提示新开 TRAE 会话并确认 Subagents Beta 功能可用。若当前 TRAE 版本/会话不支持原生 Agent，必须按各 skill 契约降级 solo/direct，报告 Fallback: TRAE subagent unavailable -> solo/direct；不得声称 full/lean 多 Agent 已生效。

部署 WorkBuddy Agents（target_cli 含 workbuddy 时）

• 先校验 references/workbuddy/agents/ 的名字集精确为 chapter-extractor, character-designer, consistency-checker, narrative-writer, revision-governor, story-architect, story-explorer, story-researcher（8 张通用卡）；再校验 skills/story-data-analyze/agents/workbuddy/ 的物理名字集精确为 story-data-fetcher, story-data-readonly-runner（2 张数据卡），且四张只读逻辑角色卡完整留在该 Skill 的 WorkBuddy role-card references。全部物理名必须无重复，合并后中文主包物理名册精确为 10 张。
• CodeBuddy 当前会在 agentic registry 查询阶段把 内置 + 项目 Subagent 总数硬截为 20。本节列出的 WorkBuddy 精确 10 张物理卡低于平台上限；部署器不向该名册注入项目扩展卡，不靠排序或截断隐藏容量问题。
• 每个 Markdown 必须有合法 YAML frontmatter，name 与文件名一致，description 非空，tools / disallowedTools 为逗号字符串且只使用当前 CodeBuddy 工具名。plugin agent 禁止 hooks、mcpServers、permissionMode；项目 agent 也不依赖这些字段。
• 只新建或替换带 `` 标记的 .codebuddy/agents/<name>.md；无标记同名文件保留并报告冲突。项目定义优先级高于 plugin/user agent，项目模式统一用裸名称和 Agent(subagent_type: "<name>")。
• pooled runner 的逻辑角色卡留在所属 Skill 内，不能复制进 .codebuddy/agents/。主协调器必须按该 Skill 的运行时映射选择 runner，并在 prompt 中传入 logical_role、角色卡绝对路径、项目根、输入隔离合同和任务正文；runner 必须完整读取且核对角色卡后执行。
• plugin-only 模式的 UI 名为 oh-story:<name>；只有当前 registry 确实暴露该名称时才用它。未运行 story-setup 时不得凭磁盘 manifest 猜测 registry 已加载；调用失败立即按 Skill 合同降级。完成项目部署后统一使用 .codebuddy/agents/ 的裸名称，避免命名空间分歧。
• 部署后新开 WorkBuddy / CodeBuddy 会话，用 /agents 或当前 registry 确认本节列出的精确 10 张物理卡全部可见；再分别冒烟一个通用 Agent 和一个 pooled runner 逻辑角色。子 Agent 不得递归 spawn。

配置 OpenCode Agent 模型

仅当 target_cli 含 opencode 时执行。OpenCode 子代理不指定模型时继承主模型，导致低成本 Agent 也消耗主模型额度。此步骤自动检测用户模型并写入 model: 字段。

Step 1：保留已有模型配置（必须在 .opencode/agents/ 的 replace 之前执行）

OpenCode agents 部署是 replace，会覆盖上次写入的 model:。所以在执行该 replace 之前先扫描现有 .opencode/agents/*.md，缓存每个 agent 的 model:（agent 名 → 模型 ID）。后续检测失败/超时、或用户跳过某一级时，用缓存值回填，避免把用户上次配好的低成本模型抹成主模型。若 replace 已先发生、缓存为空，则按全新部署处理，并在安装报告中提示"未能保留上次模型配置"。

Step 2：获取模型列表

优先执行 opencode models --verbose，它输出含 cost（input/output/cache 单价）、context、capabilities 的 metadata；不可用或解析失败时回退到 opencode models 纯文本（每行 provider/model）。两者都用 60000ms（60 秒）超时，因为首次运行需加载 models.dev 缓存。

• 成功 → 进入「模型分级」
• 超时 → 重试一次（缓存可能未预热）；仍然超时则按「保留已有模型配置」缓存回填已有 model:、跳过自动配置，在安装报告中输出手动配置指南
• 失败（命令不存在、输出为空等）→ 同上：回填「保留已有模型配置」缓存、跳过自动配置、输出手动配置指南

Step 3：モデルの階層分け

コストに基づく優先的な階層分け（--verbose がある場合）：モデルごとの実際のコストを低い順に並べて階層分けします。低コスト層には最も安価または無料の層、中コスト層には中程度の価格帯、高コスト層には最も高価な層、またはコンテキスト／能力が最も優れた層を割り当てます。無料モデルは実際のコストが 0 であるため低コスト層に分類し、名前に含まれる宣伝文句には基づきません（たとえば、名前に ultra を含む nemotron-3-ultra-free はコストが 0 なので、低コスト層に分類します）。コストデータがないモデルも候補に含め、除外しません。

キーワードによるフォールバック階層分け（--verbose がない場合、またはコストデータがない場合）：モデル 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, revision-governor
高コスト層	opus, pro, ultra, max	story-architect

• 1 つのモデルが複数の階層のキーワードに一致する場合は、最も高い階層に分類します
• キーワードによるフォールバックでどのキーワードにも一致しないモデルも候補として追加提案に含め（コストによる階層分けではすべてのモデルを含めます）、インストールレポートに記載し、「カスタム入力で使用できます」と案内します
• 同じ階層内に複数のモデルプロバイダーが含まれる場合は、知名度の高いプロバイダー（anthropic、openai、google、deepseek）のモデルを優先して表示します

Step 4：階層ごとに対話形式で選択

低コスト層 → 中コスト層 → 高コスト層の順に、各階層で AskUserQuestion を使ってユーザーに選択してもらいます。

低コスト層の選択肢の構成：

问题："为低成本 Agent（chapter-extractor, consistency-checker, story-explorer）选择模型："
选项：
  - provider/model-id
  - provider/model-id
  - 自定义输入（手动输入完整模型 ID，ID 拼写错误要到运行时才会暴露）
  - 跳过，使用主模型（成本可能较高）

中コスト層の選択肢の構成：

问题："为写作质量关键 Agent（narrative-writer, character-designer, story-researcher, revision-governor）选择模型："
选项：
  - provider/model-id
  - provider/model-id
  - 自定义输入（请勿使用低端模型，会影响正文质量；ID 拼写错误要到运行时才会暴露）
  - 跳过，使用主模型（主模型质量通常足够）

高コスト層の選択肢の構成：

问题："为总指挥 Agent（story-architect）选择模型："
选项：
  - provider/model-id
  - provider/model-id
  - 自定义输入（手动输入完整模型 ID，ID 拼写错误要到运行时才会暴露）
  - 跳过，使用主模型（成本可能较高）

ルール：

• 候補は最大 5 件まで表示します。それを超える場合は切り捨て、「その他のモデルはカスタム入力を使用してください」と案内します。候補数が 0 かどうかにかかわらず、各階層で必ず AskUserQuestion を表示します。選択肢には少なくとも、候補モデル（ある場合）、カスタム入力、既存のモデルを保持（「既存のモデル設定を保持」から該当する agent の model をキャッシュし、値がない場合は表示しません）、スキップしてメインモデルを使用を含めます。候補が 0 件の場合もダイアログを表示し、質問の説明に該当する警告と、参考として未分類／階層外のモデルを記載します。対話を黙ってスキップしてはいけません（そうすると、ユーザーがカスタム入力を利用できなくなります）。
• カスタム入力：ユーザーが provider/model-id の完全な ID を入力します。書き込む前に、1 行であること、制御文字を含まないこと、^[A-Za-z0-9._-]+/[A-Za-z0-9._:+-]+$ に一致することを検証します。一致しない場合は、再入力するかスキップを選ぶよう案内します。
• 既存のモデルを保持：「既存のモデル設定を保持」からキャッシュした該当する agent model を書き戻します（再デプロイ時にユーザーの前回の設定を保持します）。「スキップ」には該当しません。
• スキップしてメインモデルを使用：明示的にクリアします。該当する agent の model: は書き込まず、その agent にメインモデルを継承させます。前回の設定を保持するには、既存のモデルを保持を選択してください。
• 各階層の候補が 0 件の場合は、質問の説明に次の案内を記載します：
  • 低コスト層：「低コストモデルが検出されませんでした。この 3 つの agent はメインモデルを使用するため、コストが高くなる可能性があります」
  • 中コスト層：「一致する中コストモデルが検出されませんでした。narrative-writer、character-designer、story-researcher はメインモデルを使用します。メインモデルの品質が十分であれば、この設定は妥当です。コストを抑える場合は、カスタム入力でメインモデル以上の品質の中コストモデルを指定するか、以下の未分類モデルから選択してください。」
  • 高コスト層：「高コストモデルが検出されませんでした。story-architect はメインモデルを使用します」

Step 5：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: の値を置き換え、重複するキーは追加しません
• 既存のモデルを保持： 「既存のモデル設定を保持」からキャッシュした該当する agent model を書き戻します
• スキップしてメインモデルを使用：model: フィールドを書き込みません
• 検出に失敗した場合／タイムアウトした場合、およびこのステップまで到達しなかった階層では、「既存のモデル設定を保持」からキャッシュした値で model: を補完し、置換によってユーザーの前回の設定が失われないようにします

Step 6：校正進捗テンプレートをデプロイする

• 追踪/上下文.md はこのステップではデプロイしません。これは _tracking-state.json から生成されるビューになりました。執筆スキルに付属する追跡トランザクションツールがコミット時にレンダリングするため、story-setup は作成も上書きもしません
• skills/story-setup/references/templates/质检进度.md.tmpl を読み込みます
• 長編の書籍プロジェクトと判定され、{书名}/追踪/ がすでに存在する場合に限り、存在しない {书名}/追踪/质检进度.md を作成します
• 対象ファイルがすでに存在する場合は上書きしません。短編プロジェクトでは、この処理を理由に 追踪/ ディレクトリを作成してはいけません。この表は Phase 5 で必須の項目（consistency-checker、AI らしさを取り除く独立審査）を機械的に確認するための記録です。プロジェクトがすでに執筆中であることを理由に欠落させてはいけません

Step 7：Hooks の登録を settings.local.json に統合する

1. 既存のクロスプラットフォームルールに従って Python を検出します：for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done。使用可能なインタープリターがない場合は停止し、手作業で統合したり簡略化したりしないでください。
2. "$PYBIN" "{story-setup skill目录}/scripts/merge-claude-settings.py" --existing "{项目}/.claude/settings.local.json" --template "{story-setup skill目录}/references/templates/settings-hooks.json" --output "{项目}/.claude/settings.local.json" を呼び出します。
3. helper は既知の story-setup hook の過去の登録をすべて削除し、現在のテンプレートを追加します。これにより、matcher、timeout、if はバージョンアップに合わせて更新され、古い block に混在するユーザーの hook と未知のトップレベルフィールドはそのまま保持されます。書き込み後に JSON を解析し、テンプレートのコマンドがそれぞれ 1 件ずつ存在すること、ユーザーの設定が残っていることを検証します。その後、helper を再実行してファイルのバイト列を比較し、冪等性を確認します。

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

Codex 项目 hooks 部署到 .codex/hooks.json；运行脚本部署到 .codex/hooks/story_codex_hook.py、run-story-hook.sh、run-story-hook.cmd。JSON 只负责定位项目根与传递 event，解释器探测由平台 launcher 统一处理。

1. 定位当前 story-setup skill 目录，读取 references/codex/hooks/hooks.json 作为唯一当前模板，读取项目 .codex/hooks.json（不存在时视为空对象）。
2. 按现有跨平台规则探测可用 Python：for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done；无可用解释器时停止，不手写或简化 JSON 合并。
3. 调用 "$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 三类管理身份，先移除所有已知管理注册，再追加当前模板。
4. 保留用户已有的非 story-setup hooks、matcher 块与未知顶层字段。重复执行必须幂等；禁止再按原始 command 字符串追加去重，否则 v17 直调命令会与 v18 launcher 双重注册。
5. 写入后解析 JSON 验证：旧直调 story_codex_hook.py 命令数为 0，当前模板 6 个注册各存在且仅存在一次，用户 hook 与未知顶层字段仍在。然后提示用户：项目 .codex/ 层需要被 Codex trust，非 managed command hooks 还需要在 /hooks 中 review/trust 后才会运行；Windows 下走 commandWindows，launcher 从当前目录向上定位项目 .codex/hooks/，与 POSIX 路径的嵌套目录行为一致。

部署源解析（防项目旧副本自复制）

1. 记下当前正在执行的 story-setup 目录与其上一级 skills 根，称为 bootstrap_root。如果它位于目标项目的 .trae/skills/、.codebuddy/skills/、.zcode/skills/、.codex/skills/、.claude/skills/ 或根 skills/ 下，它只是“已部署快照”，不得一概当成升级权威源。
2. 已部署项目另外枚举这些可验证候选：当前已启用 plugin 的 ${CODEBUDDY_PLUGIN_ROOT}/skills/story-setup、~/.agents/skills/story-setup、~/.claude/skills/story-setup、~/.codex/skills/story-setup，以及用户本次显式给出的本地安装目录。不搜索整个磁盘，不从网页或浮动仓库直接执行未验证内容。
3. 候选只有在以下条件全部成立时才有效：SKILL.md frontmatter 的 name=story-setup、version 为可比较的三段数字 SemVer、metadata.openclaw.source 指向本 oh-story 仓库，且 Phase 1 列出的 references 与 helper 自检全部通过。无效候选只报告，不读其他内容。
4. 在有效候选与 bootstrap_root 中按 SemVer 选最新完整包为 canonical_root；版本相同时优先项目外的安装包，版本较低的外部包不得反向降级项目。安装报告必须写出 bootstrap_root、canonical_root、各自版本/用途与选择原因。
5. 后续模板、helper 与 18 个中文主包 Skill 全部从 canonical_root 读取；项目自定义 Skill 不进入 TRAE/WorkBuddy 本轮适配部署源，已有用户 Skill 保留不动。
6. copy-path-safety.py 的 status=same 只让当前那一个 source/target 项 no-op；不得因项目内 story-setup 副本指向自身，就跳过从 canonical_root 刷新其他 Skills、Commands、Agents、Rules 和 Hooks。

canonical 中文主包 Skill 清单（所有 skills 复制分支共用）

1. canonical_root/skills/ 必须精确包含这 18 个可部署 Skill：browser-cdp、story、story-cover、story-data-analyze、story-deslop、story-explore、story-import、story-long-analyze、story-long-scan、story-long-write、story-publish、story-release-package、story-research、story-review、story-setup、story-short-analyze、story-short-scan、story-short-write。
2. 按上述固定名字集读取每个 SKILL.md frontmatter 的 name / description；任一缺失、目录名与 name 不一致或重名时停止部署。不因项目根出现额外 story* 目录而扩张主包。
3. 对每个源 Skill 目录与对应目标目录逐项执行 copy-path-safety.py；same 记录为 no-op，unsafe/error 停止，仅 safe 可复制。不对整个用户 skills 根目录做删除或整体替换。

TRAE / WorkBuddy 固定 Agent 名册

1. 两端共用通用名册精确为 8 张：chapter-extractor, character-designer, consistency-checker, narrative-writer, revision-governor, story-architect, story-explorer, story-researcher。
2. TRAE 数据名册精确为 5 张：story-data-fetcher, story-data-method-validator, story-data-metrics-analyst, story-data-supervisor, story-data-text-improvement-planner。TRAE 物理名册必须精确等于前述 8 张通用卡与这 5 张数据卡的并集，共 13 张。
3. WorkBuddy 数据物理名册精确为 2 张：story-data-fetcher, story-data-readonly-runner。WorkBuddy 物理名册必须精确等于前述 8 张通用卡与这 2 张数据卡的并集，共 10 张。四个只读逻辑角色卡随数据分析 Skill 自身部署，由其运行时映射定位，不作物理 Agent 注册。
4. 两端都只备份/替换上述精确 marker 卡，保留用户 Agent；上次受管但本次不在对应精确名字集的卡走「管理资产收敛」备份后删除。

ZCode 部署算法（target_cli 含 zcode 时）

ZCode 首版部署 Skills、Commands、AGENTS.md 和支持事件内的 Hooks；不部署 .zcode/agents 或 .zcode/rules。

1. 按「canonical 中文主包 Skill 清单」复制到 .zcode/skills/{skill-name}/；仅替换这 18 个已知目录，保留用户其他 Skills。
2. 复制 references/zcode/commands/*.md 到 .zcode/commands/；仅替换与 canonical skill 同名的管理命令，保留用户其他 Commands。若主包某个 skill 缺预生成模板，视为包不完整并停止，不临时为项目扩展生成 command。
3. 复制 references/zcode/hooks/story_zcode_hook.js 和 references/zcode/hooks/story_hook_core.js 到 .zcode/hooks/。
4. 读取 references/zcode/config.json.patch 和现有 .zcode/config.json（如只有根 zcode.json，仍创建 .zcode/config.json 承载 oh-story 项目 Hooks，不改写根文件）：
   • 保留用户所有未知字段、MCP、plugins、skills/commands disable overrides；
   • hooks 互斥（避免双触发）：若本项目经已安装的 oh-story 插件运行（marketplace 安装，仓库根 .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（仅未装插件时）：设置 hooks.enabled: true；用户已有更大的 timeoutMs 时保留，否则取模板值；对 hooks.events 的 SessionStart、PreToolUse、PostToolUse 按 event + matcher + process command + args 去重追加；不复制 ZCode 不支持的 PreCompact、PostCompact、SessionEnd、SubagentStop、Notification。
5. 将 references/zcode/AGENTS.md.tmpl 按「AGENTS.md 合并策略」写入根 AGENTS.md。
6. .story-deployed 的 target_cli 写入 zcode 或多端组合，references_dir 写 .zcode/skills/story-setup/references/agent-references。
7. 安装报告明确说明：ZCode 3.3.4 的项目/plugin custom agents 不执行，所有专业角色走 solo/direct；系统需要可用的 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 唯一注册源。

TRAE hooks.json 合并算法（target_cli 含 trae 时）

1. 读取 references/trae/hooks/hooks.json 作为唯一当前模板，读取项目 .trae/hooks.json（不存在时视为空对象）。TRAE 合法 schema 是顶层 { "version": 1, "hooks": {...} }，事件值为 matcher group 数组，group 内是 matcher + hooks，每个 hook 仅使用 { "type": "command", "command": "<单一 shell command 字符串>", "timeout": <秒> }。
2. 按跨平台规则探测 python3/python/py；无可用解释器时停止 TRAE 分支，不手写或整体覆盖 JSON。
3. 调用 "$PYBIN" "{story-setup skill目录}/scripts/merge-trae-hooks.py" --existing "{项目}/.trae/hooks.json" --template "{story-setup skill目录}/references/trae/hooks/hooks.json" --output "{项目}/.trae/hooks.json"。helper 只把 command 中包含 .trae/hooks/story_trae_hook.js 的注册识别为 oh-story 管理项：先从历史 event/matcher 块移除它们，再追加当前模板。同一 matcher 块中的用户 hook、其他事件、未知顶层字段全部保留。
4. 写后校验 version == 1；事件名只能来自 TRAE 支持集 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、Notification，当前模板不得出现 SessionEnd、PreCompact、PostCompact、SubagentStop；hook 内不得出现 ZCode 的 process/args/timeoutMs 或 Claude 的 if。正文工具 matcher 覆盖 TRAE 原生 RunCommand|Write|Edit，commit advisory 覆盖 RunCommand。
5. 统计模板中每个 oh-story command 身份在结果中恰好一份，用户 hook/顶层字段仍在；再次运行 helper，必须与上次输出字节一致。

TRAE Code 原生部署算法（target_cli 含 trae 时）

TRAE 分支部署原生 Skills / Subagents / Commands / Rules / Hooks，不走 generic skills-only 降级模式。

1. 按「canonical 中文主包 Skill 清单」确认固定 18 个 Skill。在任何写入前，按「TRAE 归属与备份门」为本次将改动的已存管理资产建立带 UTC 时间戳的备份；遇到无 oh-story-managed 标记的同名文件则保留、记录冲突并停止该资产写入。
2. 逐项过 copy-path-safety.py 后，把 18 个 canonical Skill 复制到 .trae/skills/{skill-name}/。目标缺失则创建；已是 oh-story skill（SKILL.md 的 metadata.openclaw.source 指向本仓库，或含精确标记 ``）才可备份后替换。现有 sentinel 不能代替单个 Skill 的归属证据；无证据则保留并报告。status=same 的 Skill 只验证，不复制进自身。
3. 对 18 个 canonical 名字逐一部署 references/trae/commands/{name}.md；任一模板缺失即按部署包不完整停止，不为项目额外 Skill 生成 fallback command。只替换带相同管理标记的文件。
4. 按「部署 TRAE Agents」与「TRAE / WorkBuddy 固定 Agent 名册」把通用 8 名与 TRAE 数据 5 名的精确并集（13 张）部署到 .trae/agents/。仅 Agent 内置 Agent 才能调用子 Agent；skill 流程遇到子 Agent 不可用必须走已定义的 solo/direct fallback。
5. 将 references/trae/rules/*.md 写入 .trae/rules/，只替换带 标记的文件；TRAE rule frontmatter 使用 `alwaysApply: false` 和 `globs`，不复制 Claude `paths` frontmatter。将 `references/trae/AGENTS.md.tmpl` 按「AGENTS.md 合并策略」写入根 `AGENTS.md`，只替换 与 `` 之间的块，保留用户其他段落。
6. 将 references/trae/hooks/story_trae_hook.js 与 story_hook_core.js 写入 .trae/hooks/；runner 只替换头注释证明为 oh-story TRAE adapter 的同名文件。既有 shared core 必须先运行 trae-core-ownership.py --candidate <文件> --registry references/trae/legacy-managed-sha256.json，或证明与同项目受信 sibling core 字节一致；退出 3（unmanaged）/2（registry error）都保留并报告，不覆盖。替换后执行 node --check 与跨 adapter byte-parity 校验，再按「TRAE hooks.json 合并算法」合并 .trae/hooks.json；禁止用模板整体覆盖用户配置。 Windows 的原生 RunCommand 由 PowerShell 提供，runner 必须同时覆盖已测试的静态 Set-Content、Add-Content、Out-File、Copy-Item、Move-Item、New-Item 写盘形式；动态表达式、splatting、.NET API 和未识别外部程序仍由 Skill 自检与写后门兜底，不得声称全部 PowerShell 写入都能在 PreToolUse 硬拦。
7. 校验 .trae/skills/ 与 .trae/commands/ 的受管名字集都精确等于 canonical 18，受管 Agent 名字集精确等于「TRAE / WorkBuddy 固定 Agent 名册」列出的 TRAE 13 名并集，rule/hooks/AGENTS 标记齐全，hooks 契约测试通过。用户其他 .trae 资产必须仍在。
8. .story-deployed 的 target_cli 写 trae 或多端组合，references_dir 写 .trae/skills/story-setup/references/agent-references。安装报告列出备份目录、冲突/no-op、18 Skill / 18 Command / 13 Agent 验证结果与 Agent 可用性，并提示新开 TRAE 会话刷新 Skills / Commands / Rules / Subagents / Hooks。

WorkBuddy settings.json 合并算法（target_cli 含 workbuddy 时）

1. 先判定本次会话是否已实际启用 oh-story plugin：只接受当前执行 Skill 路径位于 CodeBuddy plugin 安装根、运行时 registry 明确返回 oh-story，或可用的 codebuddy plugin list 明确显示该插件 enabled。仓库里有 manifest、磁盘上有未启用副本、或用户口头说“装过”都不能代替运行时证据。
2. plugin 已启用时选择 references/workbuddy/hooks/disabled-hooks.json；project-local 模式选择 references/workbuddy/hooks/project-hooks.json。按跨平台规则探测 python3/python/py，调用 merge-workbuddy-settings.py --existing {项目}/.codebuddy/settings.json --template <所选模板> --output {项目}/.codebuddy/settings.json；无 Python 时停止 WorkBuddy 分支，不手写 JSON。
3. helper 只把命令中含 story_workbuddy_hook.js 的注册认作 oh-story 管理项：先从所有历史事件/matcher 中移除，再按所选模板追加。用户 hook、权限、模型、MCP 和未知顶层字段全部保留；重复执行必须字节幂等。
4. project-local 模式把 story_workbuddy_hook.js 与 story_hook_core.js 写入 .codebuddy/hooks/，并确认四个当前注册各恰好一次。plugin 模式不再注册第二套项目 Hook，.codebuddy/settings.json 中 oh-story runner 注册必须为零。不得用“双份输出内容相同”证明兼容。
5. 校验 Hook 输出只使用 CodeBuddy 支持字段：JSON 输出分支都有顶层 continue: true；PreToolUse 拒绝使用 hookSpecificOutput.permissionDecision=deny；commit 提醒使用顶层 systemMessage；健康 no-op stdout 为空。matcher 只声明 runner 已有目标解析 fixture 覆盖的工具。

WorkBuddy / CodeBuddy Code 原生部署算法（target_cli 含 workbuddy 时）

WorkBuddy Desktop 内嵌 CodeBuddy Code CLI；项目模式原生发现 .codebuddy/skills/、.codebuddy/commands/、.codebuddy/agents/、.codebuddy/rules/ 与 .codebuddy/settings.json。不得把它降级成 generic skills-only。

1. 按「canonical 中文主包 Skill 清单」复制 18 个 Skill 到 .codebuddy/skills/{skill-name}/；只替换能由本仓库 metadata 或精确 marker 证明归属的主包目录，保留用户其他 Skills。源目标相同时记 no-op。
2. 对 18 个 canonical Skill 逐一复制 references/workbuddy/commands/{name}.md 到 .codebuddy/commands/{name}.md；模板缺失即按包不完整停止，不为项目扩展生成 fallback command。这里是项目裸命令 /story-*；plugin manifest 不加载这批 Commands。
3. 按「部署 WorkBuddy Agents」与「TRAE / WorkBuddy 固定 Agent 名册」把通用 8 名与 WorkBuddy 数据物理 2 名的精确并集（10 张）部署到 .codebuddy/agents/；项目卡使用裸 agent 名，由 Agent 工具的 subagent_type 字段调用。数据分析的四个只读逻辑角色按映射调用 pooled runner，不把逻辑卡复制到 registry。plugin-only 名称 oh-story:<name> 只能在当前 registry 真实返回时使用。
4. 将 references/workbuddy/rules/*.md 合并到 .codebuddy/rules/，只替换同管理标记文件；再按「WorkBuddy memory 合并策略」处理当前唯一生效的 memory 文件，禁止用一份很短的 CODEBUDDY 文件遮住已有 AGENTS.md。
5. 按「WorkBuddy settings.json 合并算法」选择 project-local 或 plugin 互斥分支，并运行 Node 语法、共享 core byte-parity、中文正文写前/写后门与合并幂等 fixture。Windows 若使用 PowerShell，只有专项 fixture 已覆盖的静态写入命令属于硬门；动态表达式、splatting、.NET API 或未识别外部写盘程序仍必须依赖 Skill 自检与写后兜底，安装报告不得声称“所有 PowerShell 写入均可硬拦截”。
6. 校验 .codebuddy/skills/ 与 .codebuddy/commands/ 的受管名字集精确等于 canonical 18，受管 Agent 名字集精确等于「TRAE / WorkBuddy 固定 Agent 名册」列出的 WorkBuddy 10 名并集，rule/memory marker 唯一，用户其他 .codebuddy 资产仍在。校验 pooled runner 的四个逻辑角色映射全集、唯一且指向 Skill 内真实卡；若本机可找到 WorkBuddy 内嵌或独立 codebuddy，还要在仓库根运行 codebuddy plugin validate . 验证 plugin manifest；命令不可用时明确记为未执行，不能伪称通过。
7. .story-deployed 的 target_cli 写 workbuddy 或多端组合，references_dir 写 .codebuddy/skills/story-setup/references/agent-references。安装报告分别列出：project 命令 /story-*；plugin-only Skill /oh-story:story-*；Hook 当前唯一注册源；Agent registry 结果；PowerShell 硬门边界。部署后完整执行 references/workbuddy/runtime-activation.md，新开 WorkBuddy / CodeBuddy 会话刷新发现结果；未进 /skills、/agents、/hooks 实际确认时只能报告静态/合成运行时通过。

Plugin 安装不经过项目复制算法：仓库根 .codebuddy-plugin/plugin.json 是唯一规范 manifest，路径均以 ./ 开头，只暴露 Skills、Agents、Hooks，不暴露同名 Commands。plugin hooks 与项目 hooks 必须互斥；即使随后运行了项目 story-setup 部署 Skills/Commands/Agents/Rules，也仍以 plugin hooks 为唯一注册源，并用 disabled-hooks.json 清掉项目旧注册。

管理资产收敛与减端（TRAE / WorkBuddy 必做）

1. Phase 1 在修改 target_cli 前同时保存 previous_targets 与 desired_targets。先完成新端部署和被移除端的退役，全部验证通过后才原子写回 sentinel；不得先改 .story-deployed 再留下仍会被平台发现的旧资产。
2. 目标端仍保留时也要做名字集收敛：Skill / Command 以 canonical 18 为唯一名册，TRAE Agent 以「TRAE / WorkBuddy 固定 Agent 名册」列出的通用 8 名 + TRAE 数据 5 名（共 13 张）为唯一名册，WorkBuddy Agent 以同节列出的通用 8 名 + WorkBuddy 数据物理 2 名（共 10 张）为唯一名册。将已有精确管理标记/仓库 metadata、但已不在对应精确名字集中的 Skill / Command / Agent / Rule 列为 stale managed assets。先备份，再只删这些可证归属的 stale 项；无标记同名项永不删。删后只在目录真的为空时移除空目录。
3. 从 previous_targets 移除 trae 时：
   • 对即将改动的 .trae/ 管理资产建立 .trae/.oh-story-backups/<UTC时间戳>/ 完整相对路径备份；
   • 用 merge-trae-hooks.py --template references/trae/hooks/disabled-hooks.json 从 .trae/hooks.json 移除且仅移除 story_trae_hook.js 注册，保留用户 hooks/顶层字段，并复跑确认字节幂等；
   • 仅删除能由本节归属门证明的 .trae/skills、commands、agents、rules 管理项及两个管理 hook 脚本；从 AGENTS.md 只移除 TRAE BEGIN/END 管理块。
4. 从 previous_targets 移除 workbuddy 时：
   • 先将即将改动的项目管理资产备份到 .codebuddy/.oh-story-backups/<UTC时间戳>/；
   • 用 merge-workbuddy-settings.py --template references/workbuddy/hooks/disabled-hooks.json 从 .codebuddy/settings.json 移除项目 oh-story Hook 注册，用户设置和 hooks 不动，复跑确认字节幂等；
   • 仅删除有精确归属证据的 .codebuddy/skills、commands、agents、rules 管理项及项目 hook 脚本；从当前唯一 memory 文件只移除 WorkBuddy BEGIN/END 块。如果该 memory 文件是 story-setup 创建且移除后只剩空白，可在备份后删除；否则保留。
   • 项目减端不等于卸载用户级/plugin 级 oh-story；已启用 plugin 只由 CodeBuddy plugin 管理命令单独卸载。
5. 两个项目 runner 还必须在每个事件入口检查 sentinel：如果存在有效 target_cli 且不含当前端，立即以空 stdout 成功返回。这是中途失败的防御线，不能代替上述物理注册/发现资产清理。
6. 退役验收必须同时证明：管理 Hook 注册为 0；管理 Skill/Command/Agent/Rule/memory 块不再被目标平台发现；用户资产字节未变；备份可回滚；再跑一次为 no-op。任一项失败时不更新 sentinel，报告部分退役路径。

OpenClaw skills-only 部署算法（target_cli 含 openclaw 时）

OpenClaw Phase 1 只部署 skills，不部署 OpenClaw agents/hooks/plugin。

1. 按「canonical 中文主包 Skill 清单」读取固定 18 个 Skill 目录。
2. 写入目标项目 skills/{skill-name}/，仅替换这 18 个 story-setup 管理目录；保留用户在 skills/ 下的其他目录，且不将它们注入中文主包。
3. 每个 SKILL.md 必须满足 OpenClaw frontmatter 约束：name / description 是单行键值，metadata 是单行 JSON 对象且含 metadata.openclaw。
4. 复制 skills/story-setup/references/openclaw/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。
5. .story-deployed 的 target_cli 写入 openclaw 或多端组合；references_dir 对 OpenClaw 写 skills/story-setup/references/agent-references。
6. 安装报告提示项见 Phase 3 第 12 步。

Reasonix skills-only 部署算法（target_cli 含 reasonix 时）

Reasonix（DeepSeek-Reasonix CLI）当前只部署 skills 与 AGENTS.md，不部署 Reasonix hooks/custom agents（hook I/O 契约与子代理行为缺少可校验的真实 CLI，留待后续阶段）。

1. 按「canonical 中文主包 Skill 清单」复制固定 18 个 Skill 到目标项目 skills/{skill-name}/；仅替换这些 story-setup 管理的已知目录，保留用户其他目录。
2. 在项目根创建 .agents/skills → ../skills 相对 symlink（与 Codex 共用的 skill root），使 Reasonix 原生扫描 .agents/skills 时发现这些 skill；若已是指向 skills/ 的 symlink 则保留，若被占用为普通目录则不覆盖并在安装报告提示。Windows 未启用 symlink 时跳过本步，改走根 reasonix-plugin.json 的 reasonix plugin install。
3. 复制 skills/story-setup/references/reasonix/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。
4. 校验 skills/story-setup/references/agent-references/ 已随完整的 story-setup skill 复制到位。若当前执行源就是项目内同一路径，安全预检返回 same，本步必须作为 no-op，禁止再把目录复制进自身。
5. .story-deployed 的 target_cli 写入 reasonix 或多端组合；references_dir 对 Reasonix 写 skills/story-setup/references/agent-references。
6. 安装报告提示项见 Phase 3 第 14 步。

通用 Web AI / 其他 Agent 部署算法（target_cli 含 generic 时）

通用路径面向 NarraFork、Web AI、自定义 Agent 等可读取项目文件的环境，只部署通用文件，不声明平台原生 hooks/agents 能力。

1. 按「canonical 中文主包 Skill 清单」复制固定 18 个 Skill 到目标项目 skills/{skill-name}/；仅替换这些 story-setup 管理的已知目录，保留用户其他目录。
2. 复制 skills/story-setup/references/generic/AGENTS.md.tmpl 到项目 AGENTS.md，按「AGENTS.md 合并策略」合并。
3. 校验 skills/story-setup/references/agent-references/ 已随完整的 story-setup skill 复制到位。若当前执行源就是项目内同一路径，安全预检返回 same，本步必须作为 no-op，禁止再把目录复制进自身。
4. .story-deployed 的 target_cli 写入 generic 或多端组合；references_dir 对 generic 写 skills/story-setup/references/agent-references。
5. 安装报告提示项见 Phase 3 第 13 步。

Step 8：创建部署标记

• 创建 .story-deployed 文件（sentinel file）
• 写入以下字段（YAML key: value 格式，hook 用 references/templates/hooks/lib/sentinel.sh 读取）：

  deployed_at: <date -u +"%Y-%m-%dT%H:%M:%SZ">
  agents_version: 39
  setup_skill_version: 1.2.22
  target_cli: claude-code（或 opencode、codex、zcode、trae、workbuddy、openclaw、reasonix、generic，或其任意组合）
  resolver_strategy: project-local-skill-reference
  references_dir: .claude/skills/story-setup/references/agent-references（Codex 写 .codex/skills/...；ZCode 写 .zcode/skills/...；TRAE 写 .trae/skills/...；WorkBuddy 写 .codebuddy/skills/...；OpenClaw / Reasonix / generic 写 skills/...；多端用逗号分隔）
  

• 此文件供 session-start.sh 和写作 skill 检测部署状态，避免重复提示
• target_cli 含 claude-code 时，同时创建一次性标记文件 .claude/.agents-pending-restart（空文件即可）。session-start.sh 在下一个会话启动时据此确认 agents 已随新会话注册，并自动删除该标记——用来向用户确认「重启已生效」。ZCode 不创建该标记，因为它不部署项目 agents。
• 如果 .story-deployed 已存在但 agents_version 缺失、非整数或小于 39，按本次流程更新 hooks/agents/rules/reference bundle（具体变更见 UPGRADING.md）；大于 39 时已在 Phase 1 停止，不得降级覆盖

Phase 3：验证安装

1. 验证 hooks 注册：
   • 检查 .claude/settings.local.json 中的 hooks 字段是否正确
   • 检查 .claude/hooks/ 下的脚本是否存在且有执行权限
   • 检查 .claude/hooks/lib/common.sh 与 .claude/hooks/lib/sentinel.sh 是否存在
2. 验证 rules 路径：
   • 检查 .claude/rules/ 下的规则文件是否存在且包含 paths frontmatter
3. 验证 agents：
   • 检查 .claude/agents/ 下的 8 个 agent 定义文件是否存在
4. 验证 agent reference bundle：
   • 检查 .claude/skills/story-setup/references/agent-references/ 下 reference 文件完整
   • 检查所有 story-setup/references/agent-references/<file>.md 都能解析到 deployed bundle
5. 验证部署标记：
   • 检查 .story-deployed 是否存在且包含时间戳、agents_version: 39、setup_skill_version: 1.2.22、target_cli、resolver_strategy、references_dir
6. 输出安装报告：
   • 列出所有已部署的文件
   • 列出需要注意的事项（如已有配置已合并）
   • ⚠️ 重启提示（必须醒目输出）：本次部署写入了 .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-write
   • 如果执行了「配置 OpenCode Agent 模型」，输出 Agent 模型配置摘要：

     Agent 模型配置：
       story-architect          → <高端模型>（provider/model-id）
       narrative-writer         → <中端模型>（provider/model-id）
       character-designer       → <中端模型>（provider/model-id）
       story-researcher         → <中端模型>（provider/model-id）
       revision-governor        → <中端模型>（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/ をご覧ください。
     

7. OpenCode のデプロイを検証します（target_cli に opencode が含まれる場合のみ）：
   • .opencode/agents/ に 8 個の agent 定義ファイルが存在し、frontmatter に mode: subagent と permission フィールドが含まれていることを確認します
   • .opencode/plugins/story-hooks.ts が存在することを確認します
   • .opencode/plugins/lib/story_hook_core.js が存在し、node --check に合格することを確認します（story-hooks.ts が import する、.zcode の複製とバイト単位で一致する共有の本文書き込みガードのコアです。OpenCode が .opencode/plugins/*.js を単層で自動検出するのを避けるため、lib/ サブディレクトリに配置します）
   • .opencode/commands/ の command 名の集合が、現在の OpenCode テンプレート一覧と一致することを確認します
   • skills/story-setup/references/agent-references/ に reference ファイルがすべて揃っており、数がソースディレクトリと一致することを確認します
   • opencode.json の plugin 配列に story-hooks エントリーが含まれていることを確認します
   • .git/hooks/pre-commit が存在し、実行権限があることを確認します（Windows では実行権限の確認をスキップします）
   • .opencode/agents/ の agent ファイルの frontmatter を YAML として解析でき、model:（設定されている場合）が model: 部分文字列を grep で見つけるだけでなく、有効なトップレベルスカラーであることを確認します
8. Codex のデプロイを検証します（target_cli に codex が含まれる場合のみ）：
   • AGENTS.md に Codex の story skill ルーティングセクションが含まれていることを確認します
   • .codex/agents/ に 8 個の .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 ではプロジェクトの .codex/ 設定レイヤーを信頼する必要があること、および /hooks で managed 以外の hooks を確認・信頼する必要があることを案内します。デプロイ後は Codex の新しいセッションを開いて custom agents を有効にします。現在のランタイムが引き続き unknown agent_type を返す場合は、各 skill の fallback ルールに従って solo/direct にフォールバックします
9. ZCode のデプロイを検証します（target_cli に zcode が含まれる場合のみ）：
   • ルートの AGENTS.md に ZCode の $story-* ルーティング、大纲ガード、solo/direct fallback が含まれていることを確認します
   • 「canonical 中国語メインパッケージ Skill 一覧」に従って、.zcode/skills/ と .zcode/commands/ が正確に 18 個の名前で構成されていることを確認し、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 パスを解決できることを確認します
   • fixture を使って SessionStart、PreToolUse deny/allow、PostToolUse を呼び出し、該当事項がない場合は stdout が空で、出力がある場合は ZCode の厳密な JSON 形式に準拠することを確認します
   • インストールレポートで、ZCode 3.3.4 はプロジェクト/plugin custom agents を実行せず、full/lean のマルチ Agent リクエストは安定して solo/direct にフォールバックすることを案内します。Hook は PATH 内の node に依存します。デプロイ後は ZCode の新しい session を開き、Skills/Commands/AGENTS.md を更新します
10. TRAE Code のデプロイを検証します（target_cli に trae が含まれる場合のみ）：
    • ルートの AGENTS.md に、完全な oh-story-managed: trae 管理ブロックが 1 つだけあり、ユーザーの他の段落が保持されていることを確認します
    • .trae/skills/ と .trae/commands/ の管理対象名がどちらも canonical 18 と完全一致することを確認します。各 skill に SKILL.md があり、各 command に name / description と oh-story-managed マーカーがあることを確認します
    • .trae/agents/ の管理対象名が「TRAE / WorkBuddy 固定 Agent 名簿」に記載された共通 8 名 + TRAE データ 5 名（計 13 枚）と完全一致することを確認します。frontmatter を解析でき、name が一意で、Claude 専用フィールドがなく、管理マーカーがすべて揃っていることを確認します
    • .trae/rules/ の管理ファイルに alwaysApply / globs が含まれ、Claude の paths frontmatter が含まれていないことを確認します
    • .trae/hooks/story_trae_hook.js と story_hook_core.js が存在し、node --check に合格することを確認します。.trae/hooks.jsonがversion: 1であり、TRAE 対応イベントと{type,command,timeout}hook schema のみを使用し、matcher がRunCommand|Write|Edit を網羅し、SubagentStop` が含まれていないことを確認します
    • fixture を使って SessionStart、PreToolUse deny/allow、PostToolUse を呼び出し、該当事項がない場合は stdout が空で、出力がある場合は TRAE の hookSpecificOutput に準拠することを確認します。merge-trae-hooks.py を再実行し、ユーザーの hook/未知のフィールドが保持され、バイト単位で冪等であることを確認します
    • .claude/settings*.json の oh-story コマンドが直接 bash ... のままであることを確認します（POSIX でしか解析できない if を埋め込んではなりません）。すべての Claude エントリーポイントが、TRAE_PROJECT_DIR による無出力終了ロジックを含む lib/common.sh を source していることを確認します。同じ PreToolUse fixture を使い、TRAE では Claude インポート Hook が出力せず、TRAE ネイティブ Hook が 1 回だけ実行されることを確認します
    • インストールレポートに .trae/.oh-story-backups/ の今回のバックアップ場所と、競合/no-op があればその内容を記載します。また、TRAE Settings の Hooks ページでこのプロジェクトの Hooks を確認・有効化し、プロジェクトの AGENTS.md / Rules のインポートが有効になっていることを確認してから、TRAE の新しいセッションを開いてネイティブ Skills / Commands / Rules / Subagents / Hooks を更新するよう案内します。Subagents Beta を利用できない場合、full/lean のマルチ Agent リクエストでは必ず Fallback: TRAE subagent unavailable -> solo/direct を報告します
11. WorkBuddy / CodeBuddy Code のデプロイを検証します（target_cli に workbuddy が含まれる場合のみ）：
    • .codebuddy/skills/ と .codebuddy/commands/ の管理対象名がどちらも canonical 18 と完全一致することを確認します。各 command に有効な frontmatter と管理マーカーがあることを確認します
    • .codebuddy/agents/ の管理対象名が「TRAE / WorkBuddy 固定 Agent 名簿」に記載された共通 8 名 + WorkBuddy データの物理 2 名（計 10 枚）と完全一致し、総数が 19 以下で、名前が一意であり、frontmatter が CodeBuddy 対応フィールドのみを使用していることを確認します。pooled runner の各論理ロールは、Skill 内の実在するカードに一意にマッピングされている必要があります。新しいセッションで基本 Agent、story-data-fetcher、pooled runner の論理ロールを 1 つずつ実際に呼び出し、成功した場合にのみマルチ Agent モードが有効だと報告できます。設定ページで「すべて有効」にすることは、Task registry の証拠の代わりにはなりません
    • .codebuddy/rules/ と、有効な memory ファイル 1 つの管理ブロックを確認します。プロジェクト既存の AGENTS.md の内容が直接読み込まれるか、@AGENTS.md / @../AGENTS.md 経由でインポートされている必要があります。テンプレートの条件付きプレースホルダーが残っていてはなりません。ルートと .codebuddy/ の両方に CODEBUDDY が存在する場合は、優先順位を推測せず、競合として報告する必要があります
    • .codebuddy/settings.json がユーザーフィールドを保持していることを確認し、相互排他分岐に従って検証します。project-local モードでは、現在の oh-story Hook 登録 4 件がそれぞれちょうど 1 回登録され、イベントが SessionStart / PreToolUse / PostToolUse のみであることを確認します。plugin モードでは、プロジェクト側の登録が 0 件であることを確認します。helper を 2 回実行し、バイト単位で冪等であることを確認します
    • fixture を使って SessionStart（agents_version 38/39/40 を含む）、PreToolUse deny/allow/commit、PostToolUse を呼び出します。正常な no-op では stdout が空で、すべての出力に continue: true が含まれ、拒否フィールドと通知フィールドが CodeBuddy schema に準拠し、パスの逸脱でプロジェクトルートを回避できないことを確認します
    • plugin manifest に Skills と同名の commands フィールドがなく、カスタムパスがすべて ./ で始まることを確認します。利用可能な場合は実際に codebuddy plugin validate . を実行します。インストールレポートでは、project /story-* と plugin /oh-story:story-* の違い、Hook の唯一の提供元、PowerShell のハードゲート境界を明記し、新しいセッションを開くよう案内します
12. OpenClaw のデプロイを検証します（target_cli に openclaw が含まれる場合のみ）：
    • AGENTS.md に OpenClaw の story skill ルーティングセクションが含まれていることを確認します
    • 「canonical 中国語メインパッケージ Skill 一覧」に従って、skills/ に固定の対象 Skill が 18 個あり、各 SKILL.md に 1 行の name、1 行の description、1 行の JSON metadata.openclaw が含まれていることを確認します
    • skills/story-setup/references/agent-references/ に reference ファイルがすべて揃っており、数がソースディレクトリと一致することを確認します
    • インストールレポートで、OpenClaw Phase 1 は skills のみであり、OpenClaw agents/hooks はデプロイされないため、ランタイムのハードブロックは利用できないことを案内します。本文書き込み前のアウトラインガード、commit 通知、session/compact の自動注入は、skill 内のソフト制約としてのみ機能します。OpenClaw は session 起動時に eligible skills のスナップショットを取得するため、デプロイ後にコマンド/skills が表示されない場合は、OpenClaw の新しい session を開くか、skills watcher の更新を待つ必要があります
13. 汎用 Web AI / その他の Agent のデプロイを検証します（target_cli に generic が含まれる場合のみ）：
    • AGENTS.md に汎用 story skill ルーティングセクションが含まれていることを確認します
    • 「canonical 中国語メインパッケージ Skill 一覧」に従って、skills/ に固定の対象 Skill が 18 個あり、各 SKILL.md が読み取り可能であることを確認します
    • skills/story-setup/references/agent-references/ に reference ファイルがすべて揃っており、数がソースディレクトリと一致することを確認します
    • インストールレポートで、generic はプラットフォーム専用 hooks/custom agents をデプロイしないことを案内します。アウトラインガード、commit 通知、session/compact の注入などのハードブロックとマルチ agent 協調は、skill 内のソフト制約または solo/direct fallback として実行されます
14. Reasonix のデプロイを検証します（target_cli に reasonix が含まれる場合のみ）：
    • AGENTS.md に Reasonix の story skill ルーティングセクションと solo/direct fallback の説明が含まれていることを確認します
    • 「canonical 中国語メインパッケージ Skill 一覧」に従って、skills/ に固定の対象 Skill が 18 個あり、各 SKILL.md が読み取り可能であることを確認します
    • プロジェクトの .agents/skills が skills/ を指す symlink であることを確認します（POSIX。Reasonix のネイティブスキャンで skill を検出できるようにします）。Windows で symlink が作成されていない場合は、ルートの reasonix-plugin.json を reasonix plugin install に使用できることを確認します
    • skills/story-setup/references/agent-references/ に reference ファイルがすべて揃っており、数がソースディレクトリと一致することを確認します
    • インストールレポートで、Reasonix は現在 skills のみであり、Reasonix hooks/custom agents はデプロイされないことを案内します。本文書き込み前のアウトラインガード、commit 通知、session/compact の自動注入は skill 内のソフト制約としてのみ機能し、専門 Agent が関わる Skill は solo/direct fallback に従います。skill の検出確認には reasonix doctor capabilities を使用できます。デプロイ後に新しい skills が表示されない場合は、Reasonix の新しい session を開くか、ルートの reasonix-plugin.json を使ってネイティブ plugin をインストールします

---

模板占位符

占位符	替换规则	示例
{项目名}	用户项目名称或目录名	《剑来》、《暗卫》
{书名}	书名目录名（与目录一致）	与 {项目名} 相同，或用户自定义
{目标平台}	目标发布平台	起点、番茄、晋江、知乎盐言
{作者名}	用户笔名或昵称	未指定时用「作者」

替换时去掉花括号。如果用户未指定项目名，用当前目录名。未指定的占位符保留原样不替换。

CLAUDE.md 合并策略

用户已有 CLAUDE.md 时，按 marker/section 合并：

1. 优先识别 story-setup 管理块标记（如果旧项目已有标记，只替换标记内内容）
2. 无标记时，读取用户现有 CLAUDE.md，按 ## 标题切分为 section map
3. 读取模板 CLAUDE.md.tmpl，同样切分
4. 模板中的标准 section（Skill 路由表、文件结构、协作规则、Compact 后恢复上下文）覆盖用户同名 section
5. 用户独有的 section（自定义内容）保留不动
6. 未知冲突用 AskUserQuestion 让用户选择保留哪个版本

AGENTS.md 合并策略（OpenCode / Codex / ZCode / TRAE Code / OpenClaw / Reasonix / generic）

用户已有 AGENTS.md 时，按 marker/section 合并：

1. 优先识别 story-setup 管理块标记（如果旧项目已有标记，只替换标记内内容）
2. 无标记时，读取用户现有 AGENTS.md，按 ## 标题切分为 section map
3. OpenCode 使用 skills/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；TRAE Code 使用 skills/story-setup/references/trae/AGENTS.md.tmpl（只替换 oh-story-managed: trae 标记块）；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.tmpl
4. 模板中的标准 section（Skill 路由表、文件结构、协作规则、Compact 后恢复上下文）覆盖同名 section；用户独有 section 保留
5. 多端同时部署时，Codex/OpenCode/ZCode/TRAE/OpenClaw/Reasonix/generic 共同可用的通用段落只保留一份；工具特有说明以小节或平台管理 marker 区分，避免互相覆盖

WorkBuddy memory 合并策略

CodeBuddy 把根 CODEBUDDY.md 与 .codebuddy/CODEBUDDY.md 作为项目 memory，并只在没有 CODEBUDDY memory 时回退读取 AGENTS.md。因此不能无条件新建一份短模板遮住现有通用约定。

1. 同时检查根 CODEBUDDY.md、.codebuddy/CODEBUDDY.md 和根 AGENTS.md。若两份 CODEBUDDY 都存在，停止 memory 写入并报告冲突，请用户选择唯一规范位置；不得猜测加载优先级，也不得删除任一份。其他 WorkBuddy 资产可继续验证，但安装报告必须标为 memory 未闭环。
2. 只有一份 CODEBUDDY 已存在时，在原位 marker-merge WorkBuddy 管理块；若同时存在 AGENTS.md，把模板占位 {{OH_STORY_AGENTS_IMPORT}} 按目标位置替换为根文件的 @AGENTS.md 或 .codebuddy 文件的 @../AGENTS.md，确保原通用约定仍进入上下文。无 AGENTS 时替换为空行。
3. 两份 CODEBUDDY 都不存在但 AGENTS.md 已存在时，直接把 WorkBuddy 管理块合并进现有 AGENTS.md，并把导入占位替换为空；不新建 CODEBUDDY 文件，从而继续使用 CodeBuddy 的 AGENTS fallback。
4. 三者都不存在时，创建 .codebuddy/CODEBUDDY.md，导入占位替换为空。所有分支都只替换 BEGIN/END oh-story-managed: workbuddy 内文本，用户独有内容保留。
5. 写后验证：管理块恰好一份；{{OH_STORY_AGENTS_IMPORT}} 不得残留；有既存 AGENTS 且最终使用 CODEBUDDY 时必须有正确相对导入；再次合并字节幂等。

重新部署

• .story-deployed 不存在 → 全新安装，Phase 2 全部执行
• .story-deployed 存在且 agents_version: 39 → 提示已部署，AskUserQuestion 确认是否重新部署；提示里写明重新部署只用当前本地 skill 包刷新项目文件，skill 本身的正式更新走固定 GitHub Release 资产：npx skills add https://github.com/qin1473692580-ux/oh-story-claudecode/releases/latest/download/oh-story-release.zip -y -g
• .story-deployed 存在但 agents_version 缺失、非整数或小于 39 → 提示需要更新，重新执行 Phase 2 刷新 story-setup 管理的 agents/hooks/rules/reference bundle，CLAUDE.md / AGENTS.md / CODEBUDDY.md / settings.local.json / .codex/hooks.json / .zcode/config.json / .trae/hooks.json / .codebuddy/settings.json 走合并策略，TRAE 管理资产先备份，WorkBuddy hooks 重判 plugin/project 互斥
• .story-deployed 存在且 agents_version 大于 39 → 当前 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 は Write/Edit に対する PostToolUse のフォールバックを担当。Bash によるリダイレクト、tee、touch、cp、mv、install での本文書き込みは、PreToolUse の共通コアがベストエフォートで識別し、アウトライン／追跡ゲートを実行します。識別されなかった Bash 書き込みは、Codex Stop によるターン末尾の git スキャンでフォールバックします）
references/templates/rules/	path-scoped ルールテンプレート 4 件
references/templates/agents/	agent 定義テンプレート 8 件（story-architect、character-designer、narrative-writer、consistency-checker、revision-governor、story-researcher、story-explorer、chapter-extractor）
references/agent-references/	Agent テンプレートに付属する参考資料のコピー。skill 間で references が共有されないよう、.claude/skills/story-setup/references/agent-references/ に配置します
references/templates/settings-hooks.json	hooks 登録用 JSON スニペット
references/templates/质检进度.md.tmpl	各章の Phase 5 品質チェック項目の完了状況表。機械的に確認できます
references/codex/AGENTS.md.tmpl	Codex プロジェクトルートの AGENTS.md テンプレート
references/codex/agents/	Codex custom agent TOML テンプレート 8 件
references/codex/hooks/hooks.json	Codex hooks 登録用 JSON テンプレート（.codex/hooks.json に配置）
references/codex/hooks/story_codex_hook.py	Codex hook adapter（.codex/hooks/story_codex_hook.py に配置）
references/openclaw/AGENTS.md.tmpl	OpenClaw プロジェクトルートの AGENTS.md テンプレート（skills のみ）
references/generic/AGENTS.md.tmpl	汎用 Web AI／その他の Agent プロジェクトルートの AGENTS.md テンプレート（skills + soft checks）
references/zcode/	ZCode の AGENTS、Commands、workspace config patch、厳格な JSON Hook runner
references/trae/	TRAE Code ネイティブの AGENTS、Commands、Agents、Rules、Hooks adapter
scripts/merge-trae-hooks.py	安定した command ID に基づいて .trae/hooks.json をマージし、ユーザー設定を保持します
scripts/trae-core-ownership.py + references/trae/legacy-managed-sha256.json	TRAE shared core を上書きする前に、marker／旧版の正確な SHA に基づいて所有元を分類します。未知のファイルは fail closed になります
references/workbuddy/	WorkBuddy／CodeBuddy Code ネイティブの memory テンプレート、プロジェクト Commands、Agents、Rules、Hooks adapter。plugin モードの Skills／Agents／Hooks でも、検証済みのこれらの成果物を再利用します
scripts/merge-workbuddy-settings.py	安定した runner ID に基づいて .codebuddy/settings.json のプロジェクト Hook をマージまたは削除し、ユーザー設定を保持するとともに、plugin と project の併用を防ぎます
リポジトリルートの .codebuddy-plugin/plugin.json	CodeBuddy plugin 仕様の manifest。Skills、Agents、Hooks のみを公開し、同名の Commands との競合を防ぎます
リポジトリルートの scripts/generate-workbuddy-adapter.py	メンテナンス時に、審査済みの TRAE の役割／コマンドと共有 core から WorkBuddy 成果物を決定的に生成します。プロジェクトへの配置時には配布しません

---

ワークフローの連携

パイプライン： 配置 位置： 初期化（最初）

タイミング	移動先	コマンド
配置完了後、執筆を開始する	story-long-write / story-short-write	/story-long-write または /story-short-write
既存の小説をインポートして分析する	story-import	/story-import
ブラウザーのログイン状態が必要な場合（ランキング巡回／本文取得のための作品分析）	browser-cdp	/browser-cdp。generic ではプラットフォームがローカルスクリプト／ブラウザー制御を許可している必要があります

各環境での呼び出し構文：Claude は /名、Codex/ZCode は $名、TRAE Code は /名、WorkBuddy のプロジェクトモードは /名、WorkBuddy の plugin-only モードは /oh-story:名、OpenClaw は /skill 名、Reasonix／generic は skill 名を直接指定します。