name: awesome-novel description: 和 AI 协作写小说的工作流系统。9 个 agent 协作完成从设定到归档的完整写作流程。入口检测 → 初始化/迁移 → 交 novel-agent 调度。适用场景：从零写新小说、导入已有小说。

Novel — 小说创作工作流

和 AI 一起写小说。本 skill 负责项目状态检测、新项目初始化、旧版项目自动迁移，完成后将控制权交给 novel-agent。

唤起方式： 用户在项目目录输入 /awesome-novel（Claude Code / OpenCode / Grok Build 直接输入；Codex 输入 /use awesome-novel；或说"帮我写本小说"）即进入下方检测流程。新目录会先询问作者，确认后运行 init.py 在本地初始化小说工作空间。

OpenCode 集成说明

本 skill 也支持 OpenCode。安装在 ~/.config/opencode/skills/awesome-novel/ 后，项目初始化脚本会自动部署 agent 定义到 .opencode/agents/，OpenCode 即可自动发现：

• @novel-agent — 加载总指挥 agent
• @volume-planner、@chapter-planner 等 — 加载子 agent
• Task 工具 — novel-agent 通过 Task 工具调用子 agent

调度机制： novel-agent 写 order 文件到 .agent/task/（status: pending）→ Task 工具调用子 agent → 子 agent 读取 order 执行 → 完成后将 order 覆盖为 status: DONE 后退回。

Codex 集成说明

本 skill 也支持 Codex。skill 本体用户级安装到 ~/.codex/skills/awesome-novel/；init.py --platform codex 初始化小说项目时，把 9 个自定义 agent 部署为项目级 .codex/agents/*.toml（Codex 官方 TOML 格式，含 name/description/developer_instructions）：

• @novel-agent — 总指挥 agent（TOML 名 novel-agent）
• @volume-planner、@chapter-planner 等 — 子 agent（TOML 名与源 agent 一致）
• 独立工具 — memory-recording、roleplay-sandbox 部署为 .codex/skills/<name>/SKILL.md

调度机制： novel-agent 写 order 文件到 .agent/task/（status: pending）→ 用 spawn_agent 调度子 agent（agent 名 = .codex/agents/*.toml 的 name）→ 子 agent 读取 order 执行 → 完成后将 order 覆盖为 status: DONE 后退回。order 文件协议与其余平台完全一致。

ZCode 集成说明

本 skill 也支持 ZCode。ZCode 的 skill 约定（目录 + SKILL.md）与 Claude Code 同源，天然兼容；但 ZCode 无项目级 agents 目录，agents 即 skills。skill 本体用户级安装到 ~/.zcode/skills/awesome-novel/；init.py --platform zcode 初始化小说项目时，把 9 个 agent 部署为项目级 .zcode/skills/<name>/SKILL.md（与 Reasonix 同构，另含 memory-recording、roleplay-sandbox 独立工具，共 11 个 skill）：

• novel-agent — 总指挥（入口调度者，由 ZCode 按描述自动发现，无 @ 语法）
• writer、volume-planner、chapter-planner 等 — 子 agent（subagent skill，由 novel-agent 用 Agent 工具按 skill 名 spawn）

调度机制： novel-agent 写 order 文件到 .agent/task/（status: pending）→ 用 Agent 工具调度子 agent（子 agent 名 = .zcode/skills/ 下的 skill 名）→ 子 agent 读取 order 执行 → 完成后将 order 覆盖为 status: DONE 后退回。order 文件协议与其余平台完全一致。

dsh 集成说明

本 skill 也支持 DeepSeek Harness（dsh，DeepSeek 官方的开源 agent harness）。dsh 的 skill 约定（目录 + SKILL.md，frontmatter 只认 name/description）与 Claude Code 同源，天然兼容；但 dsh 无项目级 agents 目录（subagent 是运行时能力），agents 即 skills。skill 本体用户级安装到 ~/.dsh/skills/awesome-novel/；init.py --platform dsh 初始化小说项目时，把 9 个 agent 部署为项目级 .dsh/skills/<name>/SKILL.md（与 ZCode 同构，另含 memory-recording、roleplay-sandbox 独立工具，共 11 个 skill；<项目根>/.dsh/skills/ 是 dsh 的项目级 skill 根，自动发现且优先级最高）：

• novel-agent — 总指挥（入口调度者，由 dsh 按 name/description 自动路由，无 @ 语法）
• writer、volume-planner、chapter-planner 等 — 子 agent（subagent skill，由 novel-agent 用 subagent 工具调度）

调度机制： novel-agent 写 order 文件到 .agent/task/（status: pending）→ 用 subagent 工具调度子 agent（prompt 中要求子 agent 先调用 skill(name="<子agent名>") 加载自身指令；子 agent 名 = .dsh/skills/ 下的 skill 名）→ 子 agent 读取 order 执行 → 完成后将 order 覆盖为 status: DONE 后退回。order 文件协议与其余平台完全一致。

Grok Build 集成说明

本 skill 也支持 Grok Build（SpaceXAI 的编码 agent TUI）。skill 本体用户级安装到 ~/.grok/skills/awesome-novel/；init.py --platform grok 初始化小说项目时，把 9 个自定义 agent 部署为项目级 .grok/agents/*.md（Grok 原生 agent 发现路径，含 name/description/tools）：

• novel-agent — 总指挥（必须在主会话运行；Grok 子代理深度上限为 1，禁止把 novel-agent 当 subagent 调度）
• writer、volume-planner、chapter-planner 等 — 子 agent（由 novel-agent 用 spawn_subagent 按 subagent_type 调度）
• 独立工具 — memory-recording、roleplay-sandbox 部署为 .grok/skills/<name>/SKILL.md

调度机制： novel-agent 写 order 文件到 .agent/task/（status: pending）→ 用 spawn_subagent 调度子 agent（subagent_type = .grok/agents/*.md 的 name，isolation: none）→ 子 agent 读取 order 执行 → 完成后将 order 覆盖为 status: DONE 后退回。order 文件协议与其余平台完全一致。

检测流程 — 严格按此执行，禁止跳过

用户输入 /awesome-novel（或"帮我写本小说"）→ 检测项目状态
├─ 作者表达的是短篇意图（"写短篇 / 写个盐言故事 / 写个短故事"）→ 走短篇分支（见下）
├─ story.yaml 存在 → 旧版 2.x → 执行自动迁移（见下文）
├─ story.md 不存在 → 询问作者是否初始化 → 是则执行 init.py
│   └─ python <本 skill 安装目录>/tools/init.py [project-path] [--genre <编号>] → 完成后 @novel-agent
└─ story.md 存在 → 已有项目
    ├─ story.md 含 length: short → 短篇项目 → @short-agent 继续写作（不进卷纲/章纲流程）
    ├─ 检查同步新鲜度
    │   ├─ python <本 skill 安装目录>/tools/sync-project.py . --check → exit 0 → 已最新，略过
    │   ├─ python <本 skill 安装目录>/tools/sync-project.py . --check → exit 1 → 有更新
    │   │   └─ 展示变更文件，询问作者是否同步
    │   │       ├─ 确认 → 运行 python <本 skill 安装目录>/tools/sync-project.py .
    │   │       └─ 跳过 → 继续
    │   └─ .agent/.sync-fingerprint 不存在（首次）
    │       └─ 静默运行 python <本 skill 安装目录>/tools/sync-project.py . → 写入指纹
    └─ → @novel-agent 继续写作

短篇分支（length: short）

作者在项目目录表达短篇意图时走本分支：

短篇意图 + story.md 不存在 → 询问是否创建【短篇】项目 → 确认后执行
│   python <本 skill 安装目录>/tools/init.py [project-path] --length short → 完成后 @short-agent
└─ story.md 存在且含 length: short → @short-agent 继续写作

• 短篇项目与长篇项目的目录、流程、agent 组完全独立（stories/{slug}/ 篇目制，无卷纲/章纲/提示词）
• 短篇流程：定情绪 →（作者确认）→ 构思排纲 →（作者确认）→ 契约组装 → 契约审计 → 分批写作 → 去AI味精修 → 兑现度核对 → 验收交付 →（改稿或下一篇）
• 长篇项目（story.md 无 length: short）里作者想写短篇 → 提示另建短篇项目目录，不混用
• 可选工具（不进调度链，作者主动触发）：作者说「扫个榜 / 看看什么火」进入 short-scan（市场选题）；说「拆这篇 / 分析这篇爆款」进入 short-analyze（对标拆解，产出 analysis/{书名}/ 供写作阶段召回）——两个工具的 SOP 在平台 skills 目录下，按各自 SOP 执行，不写 order、不占 phase

强制规则：

• story.md 不存在时，先询问作者是否要在此目录创建小说项目，确认后再运行 init.py
• 禁止未经确认直接执行 init.py
• 确认后必须运行 init.py，禁止手动创建目录结构替代
• 禁止在 skill 安装目录（含 skills/awesome-novel 路径）内运行 init.py — 此目录是技能仓库，不是小说项目
• 如果当前目录是 skill 安装目录，应提示作者切换到目标目录后再执行
• init.py 执行完毕后，确认 .agent/status.md 与平台部署目录已生成（Claude Code → .claude/agents/；OpenCode → .opencode/agents/；Reasonix → .reasonix/skills/；Codex → .codex/agents/；ZCode → .zcode/skills/；dsh → .dsh/skills/；Grok Build → .grok/agents/），方可进入 novel-agent
• 如果 init.py 报错，必须先修复问题重新执行，不允许绕过

初始化 — 先询问，确认后执行，不可跳过

全新项目先询问作者是否初始化，确认后运行 init.py（项目路径可选，默认当前目录）：

python <本 skill 安装目录>/tools/init.py [project-path] [--genre <编号>]

<本 skill 安装目录> 即本 SKILL.md 所在目录（如 ~/.claude/skills/awesome-novel/、~/.config/opencode/skills/awesome-novel/、~/.codex/skills/awesome-novel/、~/.zcode/skills/awesome-novel/、~/.dsh/skills/awesome-novel/、~/.grok/skills/awesome-novel/）。AI 用绝对路径调用，避免在项目目录找不到 tools/init.py。

禁止以任何理由跳过 init.py： 手动创建目录、复制模板、直接调用 agent 都属于违规行为。init.py 是初始化入口，必须执行且完整运行。

init.py 会：

1. 选题材
2. 创建项目骨架（settings/、volumes/、chapters/、prompts/、archives/）
3. 部署 agent/skill 到当前平台约定目录（Claude Code → .claude/agents/；OpenCode → .opencode/agents/；Reasonix / ZCode / dsh 不部署 agents，agents 即 .reasonix/skills/ / .zcode/skills/ / .dsh/skills/；Codex → .codex/agents/*.toml；Grok Build → .grok/agents/*.md）
4. 按题材继承反 AI 规则和文风偏好到平台 knowledge 目录（.claude/knowledge/ / .opencode/knowledge/ / .reasonix/knowledge/ / .codex/knowledge/ / .zcode/knowledge/ / .dsh/knowledge/ / .grok/knowledge/）
5. 按题材继承格式规范、题材案例到平台 knowledge 目录
6. 创建空白的写作记忆文件（平台 memory 目录）
7. 创建永久记忆占位文件（平台 knowledge 目录）
8. 生成 CLAUDE.md（OpenCode / Reasonix 下同时生成 AGENTS.md）
9. 初始化状态文件 .agent/status.md

以上 9 步全部由 init.py 自动完成，AI 无需也不应手动干预。

检查： 运行后确认 .agent/status.md 存在且内容正确，方可进入 @novel-agent。

设定讨论 — novel-agent 与作者讨论后，由 updater 写入

init.py 完成后进入 @novel-agent，此时 phase=setup，按以下流程：

1. novel-agent 检测到 setup 阶段，与作者逐项讨论设定（世界观/角色/风格/题材）。如果作者需要帮忙取书名，参考 knowledge/title-craft/index.md 的方法论给出建议
2. 讨论完毕后，novel-agent 写 order 文件 .agent/task/setting-update-order.md
3. novel-agent 通过 Agent 工具调用 updater
4. updater 读取 order，写入 settings/world-setting.md、settings/genre-setting.md、settings/character-setting/*.md 等设定文件
5. updater 将 order 覆盖为 status: DONE 并结束
6. novel-agent 确认 order 标记 DONE（只代表写入完成），展示已写入的设定摘要给作者确认：文件清单（对照 order 的 outputs 逐项列出）+ 世界观/题材/角色/文风要点，参照 docs/tutorial.md 3.8 完成报告样式，面向作者用日常语言，结尾话术："设定已写入 settings/。哪里不对直接说；没问题就说'可以'，我开始规划卷纲。"
7. 作者明确确认（"可以/没问题/就这样"；或说"之前已确认过"）→ 才可推进 phase → outline，进入卷纲规划。作者要求修改 → novel-agent 写 setting-update-order（order 内嵌修改意见）→ 调 updater → 改完重新展示确认，循环受重试/断路器约束，连续修改仍不满意 → 暂停，请作者直接给最终文案。作者回复模糊（"差不多""你看着办""都行"）→ 追问具体哪项不确定；未明确前一律视为未确认。未确认前不得推进 phase。（作者说"你全权写"全自动模式 → 展示摘要后视为已确认直接推进）

权限规则： novel-agent 不得直接写 settings/ 下的文件，设定写入必须通过 updater 的 setting-update 模式完成。

幂等约定： phase=setup 且 setting-update-order 已 DONE（outputs 存在非空）→ 视为「已写入、待作者确认」，中断重启后直接展示摘要等确认——不新增状态字段、不重派 updater、不推进 phase；order 缺失但 outputs 已存在 → 同样直接进入展示确认。

自动迁移（2.x → 3.0）

检测到 story.yaml 存在时，按以下流程自动迁移：

Step 1: 展示迁移计划

扫描项目目录，给作者看三张清单：

文件清单：

• 设定文件：story.yaml + settings/ 下所有文件
• 角色文件：settings/character-setting/ 下所有文件
• 卷纲：volumes/ 下所有文件
• 正文：archives/ 下 .md 文件数量
• 章纲（已归档）：chapters/ 下 status: archived 的章节数量
• 章纲（跳过）：chapters/ 下 status != archived 的章节列表
• 提示词：prompts/ 下文件数量

废弃清理（直接丢弃）：

• author-intent.md、current-focus.md
• drafts/、drifts/、tmp/、temp-*.txt
• manuscripts/、.vscode/

作者确认后继续。

Step 2: 备份旧文件

mkdir -p old
mv story.yaml settings/ volumes/ chapters/ archives/ prompts/ old/
rm -rf drafts/ drifts/ tmp/ manuscripts/ .vscode/ author-intent.md current-focus.md

Step 3: 初始化新骨架

python tools/init.py [project-path] [--genre <编号>]

init.py 创建目录结构 + 空模板 + agent 定义 + 记忆/知识库。后续迁移步骤负责填数据。

Step 4: 迁移设定（逐文件按 templates/migration/ 映射）

对照 templates/migration/migration-spec.md 的字段映射表，按优先级逐文件转换：

字段映射细节在 templates/migration/migration-spec.md 中有完整定义。

Step 5: 拷贝已归档正文 + 提示词

只拷贝已定稿的正文（非 .draft.md），提示词全部复制：

# 正文：只拷定稿（跳过 draft）
for f in old/archives/*.md; do
  [ -f "$f" ] || continue
  case "$f" in *.draft.md) ;; *) cp "$f" archives/ ;; esac
done
cp old/prompts/*.md prompts/ 2>/dev/null
cp old/prompts/*.txt prompts/ 2>/dev/null

正文不做任何修改。

Step 6: 验收

• story.md 存在，skill_version = 4.13.0
• settings/world-setting.md 存在且已填充
• settings/writing-style.md 存在且已填充
• settings/genre-setting.md 存在
• 平台 knowledge/anti-ai.md 存在（迁移自旧 anti-ai.yaml）
• settings/foreshadowing.md 存在（迁移自旧 hooks.yaml，或沿用 init 生成的空台账）
• settings/character-setting/ 角色数与旧版一致
• volumes/ 卷数与旧版一致
• chapters/ 所有 archived 章节已迁移
• archives/ 正文全部复制
• prompts/ 提示词全部复制
• 旧 .yaml 已移入 old/（无残留）
• 废弃文件已清理

Step 7: 交接 novel-agent 评估补充

迁移完成后，调度 @novel-agent，由其执行：

1. 项目空间评估 — 扫描全部迁移后的文件，对照验收清单识别缺失项
2. 补充决策 — 判断缺失项该由哪个 agent 处理：
   • 设定缺失（世界观/角色/风格/题材等）→ 调度 updater（setting-update 模式）
   • 其他 → 直接向作者提问
3. 逐项引导补充 — 每次调度一个 agent 完成补充后，再评估下一项，直到项目就绪
4. 汇报就绪 — 全部就绪后向作者展示迁移+补充结果，进入写作循环。确认无误后，作者可手动删除 old/ 目录。

边界条件

项目目录结构

{project-name}/
├── story.md              # ★ 项目索引
├── settings/
│   ├── world-setting.md  # 世界观
│   ├── writing-style.md  # 写作风格（蒸馏后含量化层主卡）
│   ├── genre-setting.md  # 题材设定
│   ├── character-setting/
│   │   └── <id>.md       # 每角色一个文件
│   ├── style-profiles/   # 分场景风格卡（蒸馏产出：dialogue/fight/group-scene/…）
│   │   └── genre-baselines/  # 题材风格基线（base/benchmark/delta）
│   └── .style-versions/  # 蒸馏版本快照（style-distiller 蒸馏时生成）
├── volumes/
│   └── volume-{N}.md     # 卷纲
├── chapters/
│   └── vol-{N}-ch-{M}.md # ★ 章纲（status: outline → draft → archived）
├── prompts/
│   └── vol-{N}-ch-{M}-prompt.md  # 提示词
├── sandbox/
│   └── vol-{N}-ch-{M}/    # 剧情推演记录（可选）
├── novel-samples/        # 文风蒸馏样本（作者把待学文风的文章放这里，style-distiller 专用）
├── archives/
│   ├── *.draft.md        # 草稿
│   └── *.md              # 定稿
├── .agent/
│   ├── status.md         # 进度追踪
│   └── task/             # agent 间 order 文件
├── .claude/             # Claude Code 用（平台一，七选一）
│   ├── agents/          # Agent 定义
│   ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
│   └── memory/          # 写作动态记忆
├── .opencode/           # OpenCode 用（平台二，七选一）
│   ├── agents/          # Agent 定义
│   ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
│   └── memory/          # 写作动态记忆
├── .reasonix/           # Reasonix 用（平台三，七选一）
    ├── skills/          # 11 个 SKILL.md（agents 即 skills）
    ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/          # 写作动态记忆
├── .codex/              # Codex 用（平台四，七选一）
    ├── agents/          # 9 个自定义 agent（TOML）
    ├── skills/          # 独立交互工具（memory-recording、roleplay-sandbox）
    ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/          # 写作动态记忆
├── .zcode/              # ZCode 用（平台五，七选一）
    ├── skills/          # 11 个 SKILL.md（agents 即 skills）
    ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/          # 写作动态记忆
├── .dsh/                # DeepSeek Harness 用（平台六，七选一）
    ├── skills/          # 11 个 SKILL.md（agents 即 skills）
    ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/          # 写作动态记忆
└── .grok/               # Grok Build 用（平台七，七选一）
    ├── agents/          # 9 个自定义 agent（Markdown）
    ├── skills/          # 独立交互工具（memory-recording、roleplay-sandbox）
    ├── knowledge/       # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/          # 写作动态记忆

实际项目只生成七选一的一套平台目录（由 init.py --platform 决定），.claude/ / .opencode/ / .reasonix/ / .codex/ / .zcode/ / .dsh/ / .grok/ 不会同时存在。

Agent 协作架构

下图是主线概览；完整 order 类型清单与判定细则以 skills/novel-dispatch.md（唯一权威）+ agents/novel-agent.md（执行细则）为准。

novel-agent（总指挥）
  ├─ 新项目 → 调度 volume-planner（规划卷纲）
  ├─ 卷纲就绪 → 调度 chapter-planner（生成章纲）
  ├─ 章纲就绪 → 调度 prompt-crafter（组装提示词）
  ├─ 提示词就绪 → 调度 writer（写正文）
  ├─ 正文就绪 → 调度 anti-ai（去 AI 味管线）
  ├─ 去 AI 味完成 → 可选调度 reader（深度评审）
  ├─ 评审通过/跳过 → 调度 updater（归档 + lore-keeping）
  └─ 归档完成 → 卷完成判定 → 下一章 / 卷 N+1 / 完本

各 agent 定义在平台约定目录（Claude Code → .claude/agents/；OpenCode → .opencode/agents/；Reasonix / ZCode / dsh → .reasonix/skills/ / .zcode/skills/ / .dsh/skills/；Codex → .codex/agents/*.toml；Grok Build → .grok/agents/*.md），skill SOP 在 skills/。agent 间通过 .agent/task/*-order.md 文件通信。

可选工具： 剧情推演沙盘（skills/roleplay-sandbox.md）是独立的交互式工具，不在 agent 调度链中。作者卡剧情时主动调用，产出推演记录（sandbox/）供编写章纲时参考。

调度规则： novel-agent 是唯一调度者，只写 order 文件 + 调用子 agent。所有内容创作（卷纲/章纲/提示词/正文）、设定维护、归档更新均由子 agent 完成，novel-agent 不得越权代劳。子 agent 完成任务后把 order 覆盖为 status: DONE（不删除文件），novel-agent 检测到 DONE 即确认完成。

作者确认关卡（人铸灵魂，AI 行笔墨）： 设定、卷纲、章纲 order DONE 后必须停下，向作者展示摘要、等作者确认后才进入下一步——未确认不写下一个 order，作者说"继续/推进"只推进到下一个确认点即停。正文流水线（提示词→正文→去AI味→验收→归档）无需逐步确认，归档后再问作者。详见 skills/novel-dispatch.md。

重要：novel-agent 是顶层入口，通过 @novel-agent（Claude Code / OpenCode / Codex）或 ZCode / Grok Build 的 skill 自动发现加载进主 agent，禁止通过 Agent / spawn_subagent 将 novel-agent 作为 subagent 调度。 主 agent 加载 novel-agent 定义后即扮演总指挥角色，拥有完整的调度权限。如果 novel-agent 被作为 subagent 派出，它将失去再派子 agent 的能力（Grok 深度上限为 1），导致调度链断裂。

工具契约

个人使用免费 — 本 Skill 对个人用户完全免费。 商业使用 — 请联系作者获取授权。

让 AI 成为你的小说创作搭档,从世界观搭建到角色塑造，从章节规划到正文写作，一步步陪你完成整部小说。

加入交流群

遇到问题、交流写作心得、催更或提建议，欢迎进群，作者常在。

QQ 交流群 2群：1006050538 进群后可直接提问，或和大伙儿分享你写的小说。

如果这个项目对你有帮助，可以请我喝杯咖啡 ☕
一杯咖啡，不是合同。不影响 issue 优先级和功能方向。

你需要什么

• 安装了 Claude Code、OpenCode、Reasonix、Codex、ZCode、DeepSeek Harness（dsh） 或 Grok Build 的电脑
• Python 3.9+（macOS 系统自带 3.9 即可用；推荐 3.11+）
• OpenCode / Codex / ZCode / dsh / Grok Build 平台还需 pyyaml（pip install pyyaml；系统 Python 权限受限时用 pip install --user pyyaml）
• 大概 1 分钟完成安装

安装

不用复制粘贴命令。 打开你正在使用的 AI 工具（Claude Code / OpenCode / Codex / ZCode / DeepSeek Harness），对它说：

帮我安装 awesome-novel-agent

AI 会自动从仓库 https://github.com/modoojunko/awesome-novel-agent 下载（若它说找不到，就把这个仓库地址发给它），并运行准备好的安装脚本 ./install.sh <平台>，把 skill 本体装到你机器上：

看到 "安装完成" 就可以了。想手动安装时，克隆仓库后运行 ./install.sh <平台>（平台：claude-code / opencode / codex / zcode / dsh / grok）；Windows 用 PowerShell 时运行 install.ps1 <平台>。install.sh / install.ps1 同时兼容 deepseek-tui / hermes / openclaw（非主推平台）。安装脚本会先检查 Python 版本（需要 3.9+）和 pyyaml 依赖（仅 opencode / codex / zcode / dsh / grok），不满足会直接中止并给出升级 / 安装提示，不会等到 init.py / sync-project.py 执行时才报错。

Reasonix：

Reasonix 的 skill 是项目级部署（装在每个小说项目的 .reasonix/skills/），不走 install.sh。对 Reasonix 说 "帮我安装 awesome-novel-agent"，它会克隆仓库并用 init.py 在你的目标目录直接初始化小说项目：

git clone https://github.com/modoojunko/awesome-novel-agent.git && cd awesome-novel-agent
python tools/init.py <小说项目路径> --platform reasonix
cd <小说项目路径> && reasonix code

用 --genre <编号> 指定预置题材，不传则交互式选题材。

ZCode：

ZCode 的 skill 约定与 Claude Code 同源（目录 + SKILL.md），但无项目级 agents 目录——项目内的 9 个 agent 以 skill 形式部署（agents 即 skills）。skill 本体走 install.sh 用户级安装，项目内容由 init.py --platform zcode 项目级部署到 .zcode/：

./install.sh zcode
python ~/.zcode/skills/awesome-novel/tools/init.py <小说项目路径> --platform zcode

DeepSeek Harness（dsh）：

dsh 的 skill 约定与 Claude Code 同源（目录 + SKILL.md），但无项目级 agents 目录——项目内的 9 个 agent 以 skill 形式部署（agents 即 skills），<项目根>/.dsh/skills/ 是 dsh 的项目级 skill 根（自动发现，优先级最高）。skill 本体走 install.sh 用户级安装，项目内容由 init.py --platform dsh 项目级部署到 .dsh/：

./install.sh dsh
python ~/.dsh/skills/awesome-novel/tools/init.py <小说项目路径> --platform dsh

Grok Build：

Grok Build 的 skill 约定（目录 + SKILL.md）与 Claude Code 同源，天然兼容；自定义 agent 走项目 .grok/agents/*.md（Grok 原生发现路径）。skill 本体走 install.sh 用户级安装，项目内容由 init.py --platform grok 项目级部署到 .grok/：

./install.sh grok
python ~/.grok/skills/awesome-novel/tools/init.py <小说项目路径> --platform grok

OpenCode 用户注意： 安装路径为 ~/.config/opencode/skills/awesome-novel/，初始化后 agent 定义部署在项目 .opencode/agents/ 下，OpenCode 自动发现。详情见下方 OpenCode 集成 说明。

Codex 用户注意： skill 安装到 ~/.codex/skills/awesome-novel/，初始化后 9 个自定义 agent 以 TOML 形式部署在项目 .codex/agents/ 下，Codex 自动发现。详情见下方 Codex 集成 说明。

ZCode 用户注意： skill 安装到 ~/.zcode/skills/awesome-novel/，初始化后 9 个 agent 以 SKILL.md 形式部署在项目 .zcode/skills/ 下（ZCode 无项目级 agents 目录，agents 即 skills），ZCode 自动发现。详情见下方 ZCode 集成 说明。

DeepSeek Harness 用户注意： skill 安装到 ~/.dsh/skills/awesome-novel/，初始化后 9 个 agent 以 SKILL.md 形式部署在项目 .dsh/skills/ 下（dsh 无项目级 agents 目录，agents 即 skills），dsh 自动发现。详情见下方 dsh 集成 说明。

Grok Build 用户注意： skill 安装到 ~/.grok/skills/awesome-novel/，初始化后 9 个自定义 agent 以 Markdown 形式部署在项目 .grok/agents/ 下（Grok 原生发现），独立工具部署为 .grok/skills/。novel-agent 必须在主会话运行。详情见下方 Grok Build 集成 说明。

看到这个项目觉得有用？ 顺手点个 Star，这样它会出现在你的 GitHub 首页，让更多人发现。 {: .prompt-info }

开始写小说

安装好本体后，在你想放小说项目的目录下启动 Claude Code / OpenCode / Codex / ZCode / DeepSeek Harness / Grok Build，输入：

/awesome-novel

（Codex 输入 /use awesome-novel，或者直接说 "帮我写本小说"。）

skill 会自动检测目录状态：新目录会先和你确认，然后运行 init.py 在本地初始化小说工作空间（项目骨架、agent 定义、知识库、记忆文件），完成后进入写作流程。后续再进入该项目时，说 @novel-agent 或 "帮我继续写" 就能从中断处恢复。

Reasonix 用户在项目目录运行 reasonix code 后，输入 @novel-agent 进入写作流程。ZCode 用户在项目目录说 "帮我写本小说" 或 "帮我继续写" 即可（ZCode 无 @ 语法，agents 即 skills，novel-agent 由 ZCode 自动发现）。DeepSeek Harness 用户同样直接说 "帮我写本小说" 或 "帮我继续写" 即可（dsh 的 skill 由模型按 name/description 自动路由）。Grok Build 用户输入 /awesome-novel 或说 "帮我写本小说"。

Agent 会引导你完成后续步骤。系统由 9 个 AI Agent 协作驱动，自动检测进度、调度任务，你只需确认方向和审阅内容。

novel-agent（总指挥 — 顶层入口，由 @novel-agent 加载）
  ├─ setup 阶段 → 调度 updater（设定写入）
  ├─ outline 阶段 → 调度 volume-planner（卷纲）→ chapter-planner（章纲）
  ├─ draft 阶段 → 调度 prompt-crafter（提示词）→ writer（正文）
  ├─ anti-ai 阶段 → 调度 anti-ai（去 AI 味）
  ├─ review 阶段 → 调度 reader（深度评审，可选）
  └─ archive 阶段 → 调度 updater（归档 + lore-keeping）

上图是用户视角主线；完整调度表（含文风重蒸馏、归档后重写、记忆兜底等）见 skills/novel-dispatch.md。

novel-agent 只负责调度和验证，不直接写内容。子 agent 各司其职，完成后把 order 标记为 status: DONE 通知完成。

一次性设定

第一次写小说时，Agent 会和你聊这几个方面。不用一次性想好全部，想不到的跳过，后面随时补：

1. 题材选择 — 仙侠、都市、悬疑、历史……说你脑子里想的那个就行。Agent 会按题材类型自动配置写作风格和节奏模板。也可以直接从 24 套预置题材画像里选一个，省去手动调风格的步骤
2. 世界观 — 故事发生在什么世界？有什么特殊规则？（比如"修仙世界，灵根决定天赋"）
3. 主要角色 — 主角是谁？TA 是什么样的人？Agent 会逐个角色和你讨论性格、能力、成长经历
4. 写作风格 — 偏好更偏描写还是更偏对话、更古风还是更现代？也可以导入你喜欢的小说来提取文风

项目结构

设定聊完后，Agent 会在当前目录下创建你的小说项目，结构如下：

{你的小说文件夹}/
├── story.md              # 项目总索引（元信息/主线/卷规划）
├── CLAUDE.md             # 项目级 CLAUDE.md（tools 白名单）
├── settings/             # 设定文件
│   ├── world-setting.md  # 世界观
│   ├── writing-style.md  # 写作风格（蒸馏后含量化层主卡）
│   ├── genre-setting.md  # 题材设定
│   ├── timeline.md       # 时间线
│   ├── character-setting/ # 角色档案
│   │   └── <id>.md       # 每角色一个文件
│   ├── style-profiles/   # 分场景风格卡（蒸馏产出：dialogue/fight/group-scene/…）
│   │   └── genre-baselines/  # 题材风格基线（base/benchmark/delta）
│   └── .style-versions/  # 蒸馏版本快照（style-distiller 蒸馏时生成）
├── volumes/              # 卷纲（情绪走向/冲突阶梯/信息差/场景卡）
├── chapters/             # 章纲
├── prompts/              # 提示词
├── sandbox/              # 剧情推演记录（可选，作者卡剧情时调用）
├── novel-samples/        # 文风蒸馏样本（把想学文风的文章放这里，style-distiller 专用）
├── archives/             # 正文（定稿）
├── .agent/               # Agent 进度 + 任务通信
│   ├── status.md         # 进度标记（phase/volume/chapter）
│   └── task/             # 子 agent 间 order 文件
├── .opencode/            # OpenCode 用（七选一，由 init.py --platform 决定）
│   ├── agents/           # 9 个 Agent 定义（初始化时部署）
│   ├── knowledge/        # 格式规范、反 AI 规则、文风偏好、永久记忆
│   └── memory/           # 写作动态记忆
├── .claude/              # Claude Code 用（七选一）
│   ├── agents/           # 9 个 Agent 定义（初始化时部署）
│   ├── knowledge/