name: awesome-novel description: 和 AI 协作写小说的工作流系统。7 个 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/ → Task 工具调用子 agent → 子 agent 读取 order 执行 → 清理 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 和 .opencode/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 定义到 .opencode/agents/（OpenCode）或 .claude/agents/（Claude Code）
4. 按题材继承反 AI 规则和文风偏好到 .claude/knowledge/
5. 按题材继承格式规范、题材案例到 .claude/knowledge/
6. 创建空白的写作记忆文件（.claude/memory/*.md）
7. 创建永久记忆占位文件（.claude/knowledge/permanent-memory.md）
8. 生成 CLAUDE.md（OpenCode 下生成 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 文件并结束
6. novel-agent 确认 order 已清理，推进 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 的字段映射表，按优先级逐文件转换：

字段映射细节在 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.0
• settings/world-setting.md 存在且已填充
• settings/writing-style.md 存在且已填充
• settings/genre-setting.md 存在
• settings/anti-ai.md 存在
• settings/foreshadowing.md 存在
• 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       # 每角色一个文件
├── 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}/    # 剧情推演记录（可选）
├── archives/
│   ├── *.draft.md        # 草稿
│   └── *.md              # 定稿
├── .agent/
│   ├── status.md         # 进度追踪
│   └── task/             # agent 间 order 文件
├── .opencode/
│   └── agents/           # Agent 定义（OpenCode 用）
└── .claude/
    ├── agents/           # Agent 定义（Claude Code 用）
    ├── knowledge/        # 反 AI 规则、文风偏好、永久记忆、格式规范
    └── memory/           # 写作动态记忆

Agent 协作架构

novel-agent（总指挥）
  ├─ 新项目 → 调度 volume-planner（规划卷纲）
  ├─ 卷纲就绪 → 调度 chapter-planner（生成章纲）
  ├─ 章纲就绪 → 调度 prompt-crafter（组装提示词）
  ├─ 提示词就绪 → 调度 writer（写正文）
  ├─ 正文就绪 → 可选调度 reader（深度评审）
  └─ 作者确认 → 调度 updater（归档 + lore-keeping）

各 agent 定义在 .opencode/agents/（OpenCode）或 .claude/agents/（Claude Code），skill SOP 在 skills/。agent 间通过 .agent/task/*-order.md 文件通信。

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

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

重要：novel-agent 是顶层入口，通过 @novel-agent 加载进主 agent，禁止通过 Agent 工具将 novel-agent 作为 subagent 调度。 主 agent 加载 novel-agent 定义后即扮演总指挥角色，拥有完整的 Agent 工具权限来调度子 agent。如果 novel-agent 被作为 subagent 派出，它将失去 Agent 工具调用能力，导致调度链断裂。

工具契约

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

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

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

你需要什么

• 安装了 Claude Code 或 OpenCode 的电脑
• 大概 1 分钟完成安装

安装

Claude Code：

git clone https://github.com/modoojunko/awesome-novel-skill.git && cd awesome-novel-skill && ./install.sh claude-code

OpenCode：

git clone https://github.com/modoojunko/awesome-novel-skill.git && cd awesome-novel-skill && ./install.sh opencode

或者手动复制（以 Claude Code 为例）：

git clone https://github.com/modoojunko/awesome-novel-skill.git
cd awesome-novel-skill
mkdir -p ~/.claude/skills/awesome-novel
cp -r agents ~/.claude/skills/awesome-novel/
cp -r skills ~/.claude/skills/awesome-novel/
cp -r templates ~/.claude/skills/awesome-novel/
cp -r knowledge ~/.claude/skills/awesome-novel/
[ -d memory ] && cp -r memory ~/.claude/skills/awesome-novel/
cp -r tools ~/.claude/skills/awesome-novel/
cp SKILL.md ~/.claude/skills/awesome-novel/
echo "安装完成!"

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

看到 "安装完成" 就可以了。

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

开始写小说

安装后，打开终端，在你想放小说项目的目录下启动 Claude Code 或 OpenCode，然后说一句：

帮我写本小说

系统会自动加载写作流程。后续再进入该项目时，说 @novel-agent 或 "帮我继续写" 就能从中断处恢复。

Agent 会引导你完成后续步骤。系统由 8 个 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）

novel-agent 只负责调度和验证，不直接写内容。子 agent 各司其职，完成后清理任务标记。

一次性设定

第一次写小说时，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       # 每角色一个文件
├── volumes/              # 卷纲（情绪走向/冲突阶梯/信息差/场景卡）
├── chapters/             # 章纲
├── prompts/              # 提示词
├── sandbox/              # 剧情推演记录（可选，作者卡剧情时调用）
├── archives/             # 正文（定稿）
├── .agent/               # Agent 进度 + 任务通信
│   ├── status.md         # 进度标记（phase/volume/chapter）
│   └── task/             # 子 agent 间 order 文件
├── .opencode/            # Agent 定义（OpenCode 用）
│   └── agents/           # 8 个 Agent 定义（初始化时部署）
└── .claude/              # Agent 定义（Claude Code 用）+ 知识库 + 写作记忆
    ├── agents/           # 8 个 Agent 定义（初始化时部署）
    ├── knowledge/        # 格式规范、反 AI 规则、文风偏好、永久记忆
    └── memory/           # 写作动态记忆（各环节作者反馈）
        ├── volume-memory.md
        ├── chapter-memory.md
        ├── prompt-memory.md
        └── writing-memory.md

这些全是纯文本 Markdown 文件，你可以直接用编辑器打开看或手动改。

规划故事骨架

设定聊完后，Agent 帮你规划整体故事结构。规划分四个维度同时推进：

1. 情绪走向 — 读者读这卷从头到尾情绪怎么变化？爽卷就是"压抑→压抑→提升→打脸→装逼"，悬疑卷就是"紧张→逼近→震惊→舒缓"
2. 冲突阶梯 — 核心冲突拆成 2-4 层逐级升高的障碍，每层比前一层更难，层间有关键转折点
3. 信息差 — 明确"谁知道什么、谁不知道什么"。卷定义起点→终点，每章演绎信息差的动态变化（设→用→揭→新）
4. 场景卡 — 每章拆成 2-5 个场景卡，每卡三要素：主角想干啥、有什么拦着他、有什么悬念让读者想看下去

不知道结局？ 告诉 Agent"我只知道开头"，它照样帮你规划第一卷。

逐章写作循环（Agent 协作）

多 Agent 协作自动推进，novel-agent（总指挥）按进度调度子 agent，你只需审阅和决策：

调度规则： @novel-agent 是顶层入口，由主 AI 加载后扮演总指挥角色。novel-agent 通过 Agent 工具调度子 agent，不直接代劳写作任务。子 agent 完成后清理任务标记，novel-agent 检测到后自动推进下一阶段。

第一章写完后，Agent 会问"下一章继续吗？"

自动做的事（Agent 维护）

• 去 AI 味（prompt-crafter + writer + anti-ai）：提示词组装时注入反 AI 规则，正文生成时自查，独立 anti-ai agent 做 Gate A-F 管线检测和量化评分定级
• 动态记忆（多 agent + updater）：各 agent 在对话中实时记录你的写作偏好和反馈（正反案例），归档时 updater 兜底清理、去重压缩。高频使用的规则自动晋升为永久记忆（.claude/knowledge/permanent-memory.md），越写越懂你
• 记伏笔（updater）：归档时自动扫描未兑现/新埋的钩子，检测陈旧度和集中收束风险
• 管角色状态（updater）：每章归档后自动追加角色状态历史、情绪弧线和人际关系变化。下一章写作时 Agent 知道最新状态
• 节奏检查（updater）：连续高压超过 3 章或连续平淡超过 2 章，提醒你调整
• 卷边界检测（updater）：整卷完成后自动输出报告，询问下一卷方向

常用指令

两种协作模式

随时可以切换，跟 Agent 说一声就行。

更高阶的玩法

预置题材画像

不想从头设定写作风格？Agent 在一次性设定阶段就会问你用不用预置风格。项目内置 24 套题材档案，每套包含角色人设倾向、叙事语气和章节提示词模板。涵盖仙侠、都市、悬疑、历史、科幻末世、西方奇幻等主流类型。

常见问题

Q: 我不会编程，能装吗？

能。上面那几行命令复制粘贴到终端，回车就行。唯一的前提是你的电脑上已经装好了 Claude Code 或 OpenCode。

Q: 我升级了技能，之前写的小说项目怎么迁移到新格式？

升级后首次在当前项目目录启动时，Agent 会自动检测旧版格式，引导你完成迁移。核心逻辑：旧文件整体挪到 old/ 目录保留备份，在原地初始化新项目骨架，再逐字段将旧版设定转换到新版格式。已归档的正文直接拷贝，正在写的不迁移。确认迁移无误后可手动删除 old/ 目录。

Q: 写到一半可以改设定吗？

可以。随时跟 Agent 说"改一下世界观里的 XXX"或"这个角色的性格我想调整"，它会帮你更新。

Q: 生成的文字有 AI 味怎么办？

默认配置就是"低 AI 味"——禁止了常见机器腔句式、写完后自动检测。动态记忆系统会记录你如何修改 AI 原文，提炼为你的专属规则，后续自动规避。

Q: 可以用自己的写作风格吗？

可以。项目创建后有专门的写作风格文件，你可以把自己的偏好写进去，后面所有章节都会按这个风格来。

Star History

致谢

本项目部分设计受到 InkOS 的启发——包括 AI 味检测体系、伏笔/钩子追踪、题材配置和分层技法模型。感谢 @Narcooo 的优秀工作。

贡献

欢迎参与贡献！详情请查看 CONTRIBUTING.md。

写作风格贡献（作家）

如果你是有创作经验的作家，欢迎为反AI写作库贡献题材正反例：

贡献内容： knowledge/anti-ai/{genre}.md — 你所在题材的高频AI病句正反例

贡献格式：

# {题材名}反AI规则

> 适用题材：{genre-id}

## 高频AI病句正反例

### 1. {问题类型}

❌ "AI味的写法"
✅ "真人感的写法"

## 写作要点

1. **{要点}** — 说明

正反例原则：

• ❌ 要具体：给真实的AI味句子，不是抽象描述
• ✅ 要可执行：给可复制的真人感写法，不是"要自然"
• 每类问题包含一对对照，同一场景、同一情绪，转化清晰

提交方式：

1. Fork 项目
2. 在 knowledge/anti-ai/ 下新建或编辑题材文件
3. 提交 PR，标题格式：反AI: 添加{题材名}正反例

见 knowledge/anti-ai/README.md。

代码贡献（程序员）

项目结构：

awesome-novel-skill/
├── agents/              # 多 Agent 协作
│   ├── novel-agent.md   # 总指挥
│   ├── volume-planner.md# 叙事架构师
│   ├── chapter-planner.md# 场景设计师
│   ├── prompt-crafter.md# 提示词工程师
│   ├── writer.md        # 写手
│   ├── anti-ai.md       # 反 AI 编辑
│   ├── reader.md        # 测试读者
│   └