/awesome-novel-agent

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](https://docs.x.ai/build/overview)（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 安装目