Write a Book Skill

辅助从选题规划到生成完整 Word (.docx) 书籍的全流程创作。支持三种书籍类型：小说/故事、教程/技术书、非虚构/干货。

前置条件

pip install -r requirements.txt

最低版本要求（见 requirements.txt）：
- python-docx ≥ 1.2.0
- Pillow ≥ 10.0.0
- requests ≥ 2.28.0

通用工作流程

按以下 5 步顺序执行：

步骤 1：需求确认

与用户确认：
- 书籍主题、书名
- 书籍类型（小说 / 教程 / 非虚构）
- 目标读者
- 预计总字数 / 章节数
- 署名作者名

步骤 2：规划大纲

根据书籍类型生成完整大纲。每种类型的结构模板见下文的"三种写作模板"。

步骤 3：初始化 Word 文档

用 init_book() 创建文档，包含封面页和内容简介页。（出版规范要求）

from book_writer import init_book

init_book(
    title='书名',
    author='作者名',
    output_path='output.docx',
    content_intro='本书深入探讨了……（约300字的内容简介，出版规范要求）'
)

出版格式说明： init_book() 会自动生成两种页面：
- 封面页：书名 + 作者名
- 内容简介页：约300字的书籍介绍（出版规范必选项）

生成顺序：封面 → 内容简介 →（后续手动添加的前言）→（后续自动生成的目录）→ 正文

步骤 4：逐章写作（分块策略）

这是核心步骤。策略如下：
- 每次生成 2-3 章的内容
- 立即写入 Word 文档并保存
- 重复直到全书完成
- 每批写入后验证文件存在且可打开
- 所有正文写完后，调用 add_toc_page() 生成目录页（放在前言之后、正文之前）

步骤 5：最终润色与交付

• 调用 add_toc_page() 插入 Word 自动目录（基于 Heading 1-3 样式）
• 调用 finalize_book() 添加页眉 / 页码，最终保存
• 告知用户文件路径

目录使用说明： Word 目录是域代码（TOC field），用户用 Word 打开后：
1. 右键点击目录区域
2. 选择"更新域"（Update Field）
3. 选择"更新整个目录"
4. 目录即自动生成，包含所有 Heading 1-3 的章节标题和页码

三种写作模板

小说 / 故事模板

大纲结构：

- 书名
- 人物表（主角、配角、反派，含性格/背景/动机）
- 世界观设定（时间、地点、规则）
- 章节列表（每章含：章名、视角、核心事件、字数目标）

写作要点：
- 每章以场景为单位，场景之间用 *** 或空行分隔
- 对话使用标准中文引号（「」或 ""）
- 保持视角一致
- 注意伏笔回收

内容格式标记（传给 add_chapter() 的 content_list）：

heading2      →  节标题
paragraph     →  正文段落
scene_break   →  场景分隔（***）
dialogue      →  对话（自动格式化）

教程 / 技术书模板

大纲结构：

- 书名
- 目标读者与前置知识
- 章节列表（每章含：章名、知识点列表、代码示例概要、练习题）
- 附录（参考资源、术语表）

写作要点：
- 每章围绕 3-5 个知识点展开
- 代码示例独立成块，标注语言
- 每章末尾配练习/思考题
- 术语首次出现时加粗

内容格式标记：

heading2      →  节标题
paragraph     →  正文
code_block    →  代码块（使用等宽字体、灰色背景）
list_bullet   →  无序列表
list_number   →  有序列表
exercise      →  练习题（特殊样式）
tip           →  提示框（特殊样式）

非虚构 / 干货模板

大纲结构：

- 书名
- 核心论点（一句话概括）
- 章节列表（每章含：章名、分论点、案例/数据、关键结论）
- 参考文献

写作要点：
- 每章先抛出论点，再用案例/数据论证，最后总结
- 引用权威来源并标注
- 数据用表格呈现
- 每章结尾有"本章小结"

内容格式标记：

heading2      →  节标题
paragraph     →  正文
table         →  数据表格
quote         →  引用/引文
list_bullet   →  要点列表
summary       →  本章小结（特殊样式）
reference     →  参考文献条目

Word 生成引擎（Python 代码模板）

以下代码供你（AI）在 bash 中执行。所有函数都设计为可增量调用，支持分块写入。

模块说明

book_writer.py（核心文档引擎）

支持出版级格式：内容简介页、自动目录（TOC via Word域代码）、页眉页码。请直接引用 book_writer.py 源文件，此处仅列出新增的关键函数说明。

函数清单

init_book —— 新增参数

def init_book(title, author, output_path, content_intro=None):

content_intro 为可选参数，传入约300字的内容简介文字后，自动在封面之后生成内容简介页。

add_content_intro —— 内容简介页

def add_content_intro(doc, text, output_path=None):

在封面后插入"内容简介"页（出版规范要求）。text 为300-400字左右的书籍介绍。

add_toc_page —— 自动目录页

def add_toc_page(doc, output_path=None):

在文档中（前言之后、正文之前）插入目录页。使用 Word TOC 域代码：

TOC \o "1-3" \h \z \u

• \o "1-3"：收录 Heading 1 ~ Heading 3 级别的标题
• \h：生成超链接
• \z：隐藏不必要的格式
• \u：使用段落大纲级别

用户操作： 打开 Word 后右键点击目录区域 → 更新域 → 更新整个目录，目录自动生成。

finalize_book —— 最终处理

def finalize_book(doc, output_path, add_toc=True):

• add_toc=True 时自动调用 add_toc_page() 插入目录页
• 添加页眉（显示书名）
• 添加页脚页码（Word PAGE 域）

分块写入执行流程（出版格式完整版）

完整的出版格式顺序为：

封面 → 内容简介 → 前言 → 目录（TOC）→ 正文（各篇章）→ 结语

当书籍较长（超过 10 章）时，采用分块策略：

第 1 批：初始化 + 前言 + 前 2 章

from book_writer import init_book, add_chapter, add_content_intro
from docx import Document

# 创建文档（含封面和内容简介页）
init_book(
    title='书名',
    author='作者名',
    output_path='output.docx',
    content_intro='本书深入探讨了……（约300字的内容简介，供出版审核使用）'
)

# 前言
doc = Document('output.docx')
add_chapter(doc, '前言', [
    ('paragraph', '正文内容...'),
])
doc.save('output.docx')

# 第 1 章
doc = Document('output.docx')
add_chapter(doc, '第1章 标题', [
    ('paragraph', '正文内容...'),
])
doc.save('output.docx')

# 第 2 章
doc = Document('output.docx')
add_chapter(doc, '第2章 标题', [
    ('paragraph', '正文内容...'),
])
doc.save('output.docx')

第 2 批：第 3-5 章

from docx import Document
from book_writer import add_chapter

doc = Document('output.docx')
add_chapter(doc, '第3章 标题', [
    ('paragraph', '正文内容...'),
])
doc.save('output.docx')
# ... 重复第4、5章

最后一批：收尾（插入目录 + 页眉页码）

from docx import Document
from book_writer import add_toc_page, finalize_book

doc = Document('output.docx')

# 插入目录页（自动放在前言之后、正文之前）
add_toc_page(doc)

# 添加页眉/页码，最终保存（add_toc=False 因为已手动插入）
finalize_book(doc, 'output.docx', add_toc=False)

print('书籍已生成：output.docx')
print('请在Word中打开，右键目录区域选择"更新域"以生成完整目录')

AI 封面与插图生成（多 Provider 支持）

SkillHub 风格：AI 不渲染文字——AI 只生成纯背景/插图，所有文字由 Pillow 精确排版。

> 核心原则：AI cannot render text reliably.
> Generate the art/background with AI, then add typography with code.

Provider 配置

支持两种图片生成后端，通过环境变量或代码配置：

方式一：环境变量（推荐）

# Windows PowerShell
$env:DASHSCOPE_API_KEY="sk-xxx"

# macOS / Linux
export DASHSCOPE_API_KEY="sk-xxx"

方式二：代码创建 Provider

from image_gen import create_provider, verify_connection

# 阿里云百炼
provider = create_provider("aliyun", api_key="sk-xxx",
                           base_url="https://dashscope.aliyuncs.com/api/v1")
# OpenAI
provider = create_provider("openai", api_key="sk-xxx",
                           base_url="https://api.openai.com/v1")

# 验证连通性
print(verify_connection(provider=provider))  # "ok"

方式三：auto-detect（从环境变量自动识别）

from image_gen import create_provider
provider = create_provider()  # 自动读取 DASHSCOPE_API_KEY 或 OPENAI_API_KEY

无 API 模式（纯文字）

如果用户没有配置任何 API Key，封面和插图生成会自动跳过：
- generate_cover() 返回 None，init_book() 使用纯文字封面
- 插图生成函数返回 None，add_chapter() 中跳过 illustration 类型

封面生成

from cover_gen import generate_cover

# 方式一：传 provider 实例
cover_path = generate_cover(
    title="书名", author="作者名", output_path="cover.png",
    provider=provider,                    # <-- 推荐
    book_type="fiction",                  # fiction / tutorial / nonfiction
    subtitle="副标题（可选）",
    scene_description="背景场景描述（可选）",
    size="2048*2048",
)

# 方式二：传 provider_type（auto-create）
cover_path = generate_cover(
    title="书名", author="作者名", output_path="cover.png",
    provider_type="openai",               # 或 "aliyun"
)

# 方式三：旧式参数（向后兼容）
cover_path = generate_cover(
    title="书名", author="作者名", output_path="cover.png",
    base_url="https://dashscope.aliyuncs.com/api/v1",
    api_key="sk-xxx",
)

流程：
1. AI 生成纯背景图 — prompt 强制要求 "no text, no letters, no typography"
2. Pillow 按体裁自动排版文字（书名 / 副标题 / 分割线 / 作者 / 版本号）

体裁自动排版规则：

嵌入 Word：

from book_writer import add_cover_image
doc = Document('output.docx')
if cover_path:
    add_cover_image(doc, cover_path, width_cm=12.7)
doc.save('output.docx')

章节插图生成

所有插图 prompt 均含 "no text, no letters, no typography"，AI 只画图不写字。

from illust_gen import (
    generate_scene_illustration,
    generate_tutorial_diagram,
    generate_nonfiction_illustration,
    generate_divider,
    generate_chapter_header,
)

# 传 provider 实例
generate_scene_illustration("第1章", "雨夜古城小巷", "ch1_scene.png", provider=provider)
generate_tutorial_diagram("第3章", "ER diagram with tables", "ch3_er.png", provider=provider)
generate_divider("divider.png", provider=provider)
generate_chapter_header(1, "ch1_header.png", provider=provider)

# 或传 provider_type
generate_scene_illustration("第1章", "雨夜古城小巷", "ch1_scene.png", provider_type="aliyun")

在 add_chapter() 中通过 illustration 类型插入：

add_chapter(doc, '第1章 标题', [
    ('illustration', 'ch1_header.png', {'width_cm': 14}),
    ('paragraph', '正文内容...'),
    ('illustration', 'ch1_scene.png', {'caption': '雨夜相遇', 'width_cm': 12}),
    ('paragraph', '更多正文...'),
])

插图决策规则：
- 小说：每个关键场景配 1 张场景图
- 教程：每个主要知识点配 1 张示意图
- 非虚构：每个核心论据配 1 张概念图
- 每章开头可选章首装饰，结尾可选分隔线

Prompt 编写规范

1. 使用英文 prompt，AI 模型英文理解通常更好
2. 强制无文字：始终包含 "No text, no letters, no typography"
3. 风格描述：如 "cinematic lighting", "minimalist design"
4. 质量关键词：如 "award-winning", "professional", "premium"
5. 仅画背景：封面 prompt 不加任何文字要求

分块写入执行流程（含插图版）

第 1 步：获取 API 配置

from image_gen import create_provider

# 三种方式选一：
# 1) 环境变量 auto-detect
provider = create_provider()

# 2) 阿里云百炼
provider = create_provider("aliyun", api_key="sk-xxx",
                           base_url="https://dashscope.aliyuncs.com/api/v1")

# 3) OpenAI
provider = create_provider("openai", api_key="sk-xxx")

第 2 步：生成封面 + 初始化文档

from cover_gen import generate_cover
from book_writer import init_book, add_cover_image
from docx import Document

cover_path = generate_cover("书名", "作者名", "cover.png",
                            provider=provider, book_type="fiction",
                            subtitle="副标题")
init_book("书名", "作者名", "output.docx")
doc = Document("output.docx")
if cover_path:
    add_cover_image(doc, cover_path)
doc.save("output.docx")

第 3 批：逐章写作 + 插图

from docx import Document
from book_writer import add_chapter
from illust_gen import generate_scene_illustration

ch1_img = generate_scene_illustration("第1章", "场景描述", "ch1_scene.png",
                                      provider=provider)

doc = Document('output.docx')
content = []
if ch1_img:
    content.append(('illustration', ch1_img, {'caption': '图注'}))
content.append(('paragraph', '正文内容...'))
add_chapter(doc, '第1章 标题', content)
doc.save('output.docx')

第 4 步：收尾（含目录）

from docx import Document
from book_writer import add_toc_page, finalize_book

doc = Document('output.docx')

# 插入目录页（放在前言之后、正文之前）
add_toc_page(doc)

# 添加页眉/页码，最终保存
finalize_book(doc, 'output.docx', add_toc=False)

print('书籍已生成：output.docx')
print('请在Word中打开，右键目录区域选择"更新域"以生成完整目录')

格式规范总结

最佳实践

1. 先规划再动笔：至少花一轮对话确定完整大纲，用户确认后再开始写
2. 每批 2-3 章：避免单次生成内容过多导致质量下降
3. 每批验证：每批写入后检查文件大小是否合理（至少增长 1KB/章）
4. 中间版本：每完成 5 章另存为 书名_草稿_v2.docx 等版本
5. 中文字体：务必使用 set_cn_font() 设置中文字体，否则 Word 中中文可能显示异常
6. 风格一致：同一本书中保持相同的术语、语气、格式
7. 用户确认：每完成一批（3-5 章），询问用户是否需要调整再继续
8. 代码测试：在批量写书前，先用 1 章测试脚本能否正常运行
9. 文件路径：使用绝对路径或确认 workdir，避免文件找不到
10. API Key 安全：优先使用环境变量（DASHSCOPE_API_KEY / OPENAI_API_KEY），避免在代码中明文写入
11. 生成前确认：每张封面/插图生成前，向用户展示 prompt 并确认，避免浪费 API 调用
12. Prompt 用英文 + 禁止文字：封面/插图 prompt 始终包含 "No text, no letters, no typography"，文字交给 Pillow 排版
13. 种子复用：生成满意的插图后记录 seed 值，后续类似插图可复用相同 seed 保持风格一致
14. 无 API 模式：用户没有图片 API 时，skill 应自动退化为纯文字模式——只生成 Word 文档，跳过封面/插图生成