novel-writing

novel-writing

Claude Code 小说写作插件 — 自主批次写作闭环，支持大纲、章节、角色、世界观、节拍表、风格保留修订，配合交叉引用的知识图谱实现全程一致性管理。

---

目录

• 安装
• 操作指南
• 快速上手
• 完整技能参考
• 自主批次写作闭环
• Hook 系统
• 项目结构
• Profile 模式
• 状态管理
• 知识图谱
• 架构原理
• 故障排除

---

安装

前置要求

• Claude Code 已安装并认证
• Node.js 16+（用于运行 scripts/lib/ 下的工具脚本）

手动安装

步骤 1：准备插件目录

将插件克隆或复制到本地任意目录。建议放在一个固定位置，避免后续移动：

# 方式 A：克隆仓库
git clone https://github.com/你的用户名/novel-writing.git D:\DATA\github\novel-writing

# 方式 B：直接将文件夹复制到目标路径

注意：插件目录路径中最好不要包含中文或空格，如果路径含空格需要用引号包裹（如 "D:\我的项目\novel-writing"）。

步骤 2：找到并编辑 settings.json

Claude Code 的配置文件位于用户主目录：

# Windows
C:\Users\<你的用户名>\.claude\settings.json

# macOS / Linux
~/.claude/settings.json

如果文件不存在，需要手动创建。打开终端执行：

# Windows PowerShell
New-Item -Path "$env:USERPROFILE\.claude\settings.json" -ItemType File

# macOS / Linux
touch ~/.claude/settings.json

如果文件存在但没有 plugins 字段，用任意文本编辑器打开，添加 plugins 节点：

{
  // 保留文件中已有的其他配置...
  "plugins": {
    "novel-writing": {
      "path": "D:\\DATA\\github\\novel-writing"
    }
  }
}

Windows 路径格式：在 JSON 中使用反斜杠 \\ 转义，或使用正斜杠 /（更稳定）。例如 D:/DATA/github/novel-writing。

步骤 3：重启 Claude Code

关闭当前 Claude Code 窗口，重新启动让插件加载生效。

步骤 4：安装依赖

插件脚本依赖 uuid 模块，需要在插件根目录安装：

cd D:\DATA\github\novel-writing
npm install uuid

步骤 5：验证安装

启动 Claude Code 后输入以下命令，确认无报错即为安装成功：

/outline
/chapter
/character
/world
/beat
/edit
/auto

出现技能描述而非 "unknown command" 即表示插件正常加载。

常见问题

Q: settings.json 中的 plugins 字段不生效？

确认 JSON 格式正确——缺少逗号、引号不匹配是常见错误。可用在线 JSON 校验工具验证。

Q: 提示 Cannot find module 'uuid'？

执行步骤 4 的 npm install uuid，确保在插件根目录下运行。

Q: 多工作区如何配置？

插件支持工作区级别的 settings.json。在工作区根目录创建 settings.json 并配置 plugins，该配置仅在当前工作区生效，覆盖用户级配置。

Q: 如何确认插件实际加载了哪些 Skill？

在 Claude Code 中输入 / 查看斜杠命令菜单，列出的命令中包含 outline、chapter、character 等即为成功。

初始化项目

# 创建第一个小说项目
node scripts/lib/state-manager.js create "我的小说" --genre=奇幻 --tone=史诗

# 查看所有项目
node scripts/lib/state-manager.js list

# 切换到指定项目
node scripts/lib/state-manager.js load <project-id>

---

快速上手

五步开始写作

Step 1：构建世界观

/world
→ 定义魔法系统、组织、地点、时间线

Step 2：创建角色档案

/character create [角色名]
→ 填写角色背景、性格弧光、人物关系

Step 3：生成大纲

/outline
→ 输入故事前提、体裁、结构偏好
→ 生成三幕结构章节大纲

Step 4：创建节拍表（可选）

/beat --framework=save-the-cat
→ 场景级节拍分解

Step 5：开始写作

/auto --batch=5
→ 自主批次写作，一次性生成5章
→ 写完后自动更新所有状态文件

快速 MVP（极简模式）

一条命令即可完成小说写作全流程：

# 1. 创建项目
node scripts/lib/state-manager.js create "我的小说"

# 2. 加载项目
node scripts/lib/state-manager.js load <project-id>

# 3. 在 Claude Code 中直接执行自动写作
/auto 生成一部仙侠小说 总章数50章

自动完成以下步骤：

1. 检测 world.json 是否存在 → 不存在则自动创建
2. 检测 characters.json 是否存在 → 不存在则自动创建
3. 检测 outline.json 是否存在 → 不存在则根据参数自动生成大纲
4. 循环执行 /auto --batch=5 直至完成目标章节数

循环写作（每次生成5章）：

/auto --batch=5
→ 自动续写后续章节，无需手动指定
→ 循环直到完成目标

验证进度：

node scripts/lib/state-manager.js meta <project-id>

---

完整技能参考

/outline — 大纲规划

生成或扩展故事大纲。

• 输入故事前提、体裁、结构偏好（三幕/四幕/英雄之旅）
• 按 Act → Chapter 生成层级结构
• 每章包含：标题、摘要、POV、地理位置、关键事件、字数目标
• 输出到 data/{project}/outline.json 和 chapters/00-outline.md

/chapter — 章节写作

根据大纲和风格档案撰写单章。

• --continue — 续写下一章
• --num=N — 写第 N 章
• --light — 短章（1500-2500 字）
• --full — 长章（4000-6000 字）
• 首次写作自动提取风格档案

/character — 角色管理

创建、编辑、查询角色档案。

• create [name] — 创建新角色
• edit [name] — 编辑现有角色
• 直接提问模式：/character 谁知道这个秘密？
• 支持关系网络、首次出现章节等交叉引用

/world — 世界构建

构建故事世界：魔法系统、地点、组织、时间线。

• build [type] — 构建特定组件
• 直接提问模式：/world 哪个组织控制北方领土？
• 支持层级地点、派系成员、事件时间线等交叉引用

/beat — 节拍表

场景级叙事结构规划。

• --framework=three-act|save-the-cat|scenes — 选择框架
• --chapter=N — 针对特定章节
• --expand — 扩展已有节拍表
• 自动关联角色和地点的首次出现

/edit — 风格修订

在保留作者风格的前提下修订文稿。

• --level=light|medium|heavy — 修订强度
• --chapter=N — 指定修订章节
• --focus=pacing|dialogue|description|consistency|grammar — 重点领域
• 三级修订：轻度润色 → 质量改进 → 结构调整

---

自主批次写作闭环

核心技能 /auto，实现无人值守的批次写作。

工作流程