book-writing-workspace

图书写作工作区

创建并维护可复用的手稿工作区，其中包含文件夹、写作 Agent、说明、审阅规则，以及可选的 Markdown → Re:VIEW → PDF 支持。

使用场景

• 图书写作、技术写作、写作项目、Re:VIEW
• 评估或规范现有的图书手稿仓库
• 需要时，根据模板创建新的技术写作项目
• 设置 Markdown → Re:VIEW → PDF 工作流
• 升级现有手稿工作区，使其能够生成 Re:VIEW 输出和可打印的 PDF
• 规范章节／小节文件布局、写作规则、审阅工作流和页数分配
• 添加可选的 Re:VIEW／PDF 支持，同时避免将写作工作区变成通用的 Git 或出版运营工具包

快速开始

即使要创建新项目，也要先评估手稿工作区：

1. 确认主要手稿位于 sections/ 中，并且每个小节使用一个文件。
2. 确认大纲或要点与最终手稿文件分开存放。
3. 确认章节引言文件采用 kebab-case 命名（例如 00-introduction/00-introduction.md）。
4. 找到工作区中声明读者画像的 SSOT；如果现有概述文档或规划文档已负责维护该信息，就不要强行创建新文件。
5. 对于新工作区，使用 docs/reader-personas.md 定义主要读者画像、次要读者画像、已有知识和完成目标。
6. 确认写作、标题、标记法、页数分配和审阅规则均可查阅。
7. 判断该项目是否需要 Re:VIEW／PDF 输出；除非工作流有此要求，否则应将其作为可选项。

操作工作流

如果工作区已经存在，不要只提供设置方面的建议。此技能还应支持：

1. 规范手稿文件夹和小节命名。
2. 按章节对齐大纲、草稿、最终手稿和图片。应根据引用图片的小节确定图片所属章节，而不是依据文件名前缀。对于屏幕截图，只描述截图中呈现的状态；跳过读者不需要的空值或不可用值；先介绍图片，再解释其中可见的标签。将“第 N 章将介绍”之类的交叉引用写在正文中，而不是图中。
3. 持续开展有针对性的写作和审阅，直到解决 P1／P2 问题。
4. 应用审阅者提出的修改，同时确保大纲、章节映射、问题汇总和进度跟踪表保持同步。
5. 根据本书特定的读者画像和预期成果审阅每一章。
6. 在定稿前检查字数目标和来源可信度。
7. 将构建后的页数作为判断是否超出页数预算并构成结构性问题的依据；字符数估算通常偏高，而且作者侧构建的页数并不等同于出版商的印刷页数。
8. 逐项处理外部问题、拉取请求和出版商校样意见；先确认校样所依据的修订版本，再根据权威来源核实每项事实主张。
9. 如果确定由作者撰写，则应在手稿中为仅用于排版的元素（例如章节扉页）设定权威来源，并标记好，以便转换器输出这些内容。
10. 将作者简介页视为出版约定的一部分：确保作者顺序、显示名称、角色、已确认的个人资料和链接，与结构映射、元数据、封面和版权页保持一致。不要编造缺失的个人简介信息；在作者确认之前，将临时文本标记为待确认；作者人数变更时，要以视觉方式检查封面上的换行。
11. 仅在项目需要可复现输出时启用 Re:VIEW／PDF 支持。
12. 冻结候选发布版本，并在交付或出版前通过发布就绪检查。

引导工作流

仅在创建新工作区或有意补充缺失结构时使用设置脚本。

python scripts/setup_workspace.py --name "project-name" --title "Book Title" --path "<parent-dir>" --chapters 8  # add --with-review only when Re:VIEW/PDF is needed

所有选项：references/setup-workflow.md。

1. 收集信息：项目名称、标题、位置、章节数
2. 运行脚本：scripts/setup_workspace.py
3. 检查输出：确认已创建 README、Agent、说明文件和文档
4. 自定义：编辑 docs/reader-personas.md、docs/page-allocation.md、docs/schedule.md 和 .github/copilot-instructions.md。如果使用了 --with-review，还要自定义 config/review-metadata/project.yml。

Git 工作流因项目而异。不要在此处添加通用的提交／推送提示；请遵循仓库现有的版本控制惯例。

元数据、迁移、转换器验证和回同步规则均位于参考文档中。请让主 SKILL 专注于手稿结构和写作工作流。

生成的工作区

• keypoints/、sections/ 和 images/ 下的手稿文件夹
• .github/agents/ 和 .github/instructions/ 下的 AI 工作流文件
• 项目文档，例如 README.md、docs/reader-personas.md、docs/page-allocation.md、docs/schedule.md 和 docs/release-readiness-record.md
• 辅助脚本，例如 scripts/count_chars.py（从此技能的 templates/scripts/ 复制）
• 使用 --with-review 时生成的可选 Re:VIEW 脚本和元数据

推荐的写作单元

• 默认将 1 个文件 = 1 个章节 作为手稿单元。
• 将章节简介放在 {NN}-{slug}/{NN}-{slug}.md 中，并将章节文件放在其旁边。
• 对于 PDF/Re:VIEW 输出，标题级别定义层级，而文件拆分主要用于改善创作和审阅工作流。

Agent 概览

Agent	职责	默认
@writing	撰写和编辑手稿	是
@writing-reviewer	审阅手稿（P1/P2/P3）	是
@converter	将 Markdown 转换为 Re:VIEW	仅在使用 --with-review 时

依赖项

工具	用途	必需
Python 3.8+	脚本	是
Git	版本控制	是
Docker	Re:VIEW PDF 构建	可选，仅在使用 --with-review 时

参考文档索引

主题	参考文档
文件夹结构	references/folder-structure.md
设置工作流	references/setup-workflow.md
自定义项	references/customization-points.md
外部审阅	references/external-review-handling.md
Re:VIEW / PDF 提示	references/review-pdf-tips.md
截图采集	references/screenshot-capture.md
发布就绪审查	references/release-readiness-review.md

可选构建流水线

对于添加转换或 PDF 渲染的工作区，请应用构建流水线关卡。将项目特定的命令、依赖项版本和格式化规则保留在生成的工作区中。

完成标准

• 已创建工作区文件夹结构
• 已将写作和审阅 Agent 部署到 .github/agents/
• 已选定一个读者画像 SSOT；新工作区使用 docs/reader-personas.md，且不含占位符
• 已配置 docs/page-allocation.md
• 发布候选版本可使用 docs/release-readiness-record.md
• 已自定义 README.md 和 docs/schedule.md
• 手稿文件遵循章节／小节命名约定
• 作者简介、元数据、封面和版权页中的作者顺序及显示名称一致；临时档案不会被视为已达到发布就绪状态
• scripts/count_chars.py 可用于目标手稿文件
• 缺少必需模板、脚本或资源时，设置过程会在产生任何更改前失败
• 在干净的临时目录中进行的冒烟测试会生成 docs/reader-personas.md 并成功退出
• 冒烟测试还会生成 docs/release-readiness-record.md、展开标题，并包含 Gate 8 行和清单锁定字段
• Re:VIEW/PDF 输出已明确排除在范围之外，或已启用并完成验证