/awesome-novel-agent

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

Novel — 小说创作工作流

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

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` 初始化小说项目时，把 8 个自定义 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 文件协议与其余平台完全一致。

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

检测项目状态
├─ story.yaml 存在 → 旧版 2.x → 执行自动迁移（见下文）
├─ story.md 不存在 → 询问作者是否初始化 → 是则执行 init.py
│   └─ python tools/init.py [project-path] [--genre <编号>] → 完成后 @novel-agent
└─ story.md 存在 → 已有项目
    ├─ 检查同步新鲜度
    │   ├─ python tools/sync-project.py . --check → exit 0 → 已最新，略过
    │   ├─ python tools/sync-project.py . --check → exit 1 → 有更新
    │   │   └─ 展示变更文件，询问作者是否同步
    │   │       ├─ 确认 → 运行 python tools/sync-project.py .
    │   │       └─ 跳过 → 继续
    │   └─ .agent/.sync-fingerprint 不存在（首次）
    │       └─ 静默运行 python tools/sync-project.py . → 写入指纹
    └─ → @novel-agent 继续写作

**强制规则：**

• `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/`），方可进入 `@novel-agent`
• 如果 `init.py` 报错，必须先修复问题重新执行，不允许绕过

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

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

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

**禁止以任何理由跳过 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 不部署 agents，agents 即 `.reasonix/skills/`；Codex → `.codex/agents/*.toml`） 4. 按题材继承反 AI 规则和文风偏好到平台 knowledge 目录（`.claude/knowledge/` / `.opencode/knowledge/` / `.reasonix/knowledge/` / `.codex/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**，推进 phase → outline，进入卷纲规划

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

自动迁移（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` 的字段映射表，按优先级逐文件转换：

| 优先级 | 旧文件 → 新文件 | 参考模板 | |--------|----------------|---------| | P0 | `old/settings/character-setting/*.yaml` → `settings/character-setting/*.md` | `templates/migration/character.md.template` | | P1 | `old/story.yaml` + `old/volumes/*.yaml` → `story.md` | `templates/migration/story.md.template` | | P2 | `old/volumes/*.yaml` → `volumes/volume-{N}.md` | `templates/migration/volume.md.template` | | P3 | `old/chapters/*.yaml`（archived）→ `chapters/vol-{N}-ch-{M}.md` | `templates/migration/chapter.md.template` | | P4 | `old/settings/world-setting.yaml` → `settings/world-setting.md` | `templates/migration/world-setting.md.template` | | P5 | `old/settings/writing-style.yaml` → `settings/writing-style.md` | `templates/migration/writing-style.md.template` | | P6 | `old/settings/anti-ai.yaml` → 平台 knowledge/anti-ai.md（`.claude/` / `.opencode/` / `.reasonix/`） | `templates/migration/anti-ai.md.template`（所有 agent 读 knowledge 路径，不读 settings/anti-ai.md） | | P7 | `old/settings/hooks.yaml` → `settings/foreshadowing.md` | `templates/migration/foreshadowing.md.template`（也可沿用 init 生成的空台账） | | P8 | 无旧源 → `settings/genre-setting.md` | `templates/migration/