教程指南生成技能

为用户生成风格统一、内容完整、专业精美的新手教程指南，输出为 .docx Word 文档。

触发条件

用户提供：

• 主题名称（必填）：如"微信小程序开发"、"Superpowers 完全新手教程"
• 参考链接（可选）：官方文档、视频、文章等
• 二维码图片（已内置）：公众号/视频号二维码存于 assets/ 目录，无需用户提供

输出规范

• 格式：.docx Word 文档 + .md Markdown 文档（同时生成）
• 文件名：[主题名]-完全新手指南.docx / [主题名]-完全新手指南.md
• 保存路径：默认写入当前工作目录所属的 kj-llm-wiki 仓库下的 raw/papers/
  • 例如当前工作目录是 /Users/didi/ai_space/kj-llm-wiki，输出到 /Users/didi/ai_space/kj-llm-wiki/raw/papers/
  • 例如当前工作目录是 /Users/chengkangjian/Library/Mobile Documents/iCloud~md~obsidian/Documents/kj-llm-wiki，输出到该目录下的 raw/papers/
  • 如需临时指定输出目录，可在运行脚本时设置环境变量 TUTORIAL_GUIDE_OUTPUT_DIR
• 使用 docx npm 包生成，脚本保存到 skills/tutorial-guide/scripts/gen_[主题名].js
• 脚本中同时生成 .docx 和 .md 两个文件到同一目录

文档结构（顺序固定）

1. 封面页

• 主标题：[主题名称] 完全新手指南（居中，36pt，粗体，深蓝色 #1a73e8）
• 副标题：从零开始，手把手带你入门（居中，18pt，灰色 #5f6368）
• 作者：作者：[公众号名]（居中，14pt）
• 日期：当前日期（居中，12pt，灰色）
• 封面后插入分页符

2. 目录页

• 标题"目录"（居中，Heading1 样式，深蓝色）
• 手动构建目录条目（禁止使用 TableOfContents 组件——该组件需在 Word 中手动更新域才能显示，直接打开时目录为空）
• 目录条目格式：前言、第一章 XXX、第二章 XXX … 每行一个条目，使用普通段落（Normal 样式），字体 13pt，左对齐，行间距适中
• 目录后插入分页符

手动目录段落示例：

// 目录条目示例（根据实际章节列表逐条生成）
new Paragraph({
  children: [
    new TextRun({ text: "前言", size: 26, font: "Arial" }),
    new TextRun({ text: "\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t3", size: 26, font: "Arial", color: "888888" })
  ],
  spacing: { before: 80, after: 80 }
}),
new Paragraph({
  children: [
    new TextRun({ text: "第一章  概念介绍与核心原理", size: 26, font: "Arial" })
  ],
  spacing: { before: 80, after: 80 }
}),
// ... 以下按实际章节逐条手动列出

⚠️ 注意：页码可写固定占位（如省略或标注"—"），但章节名称必须与正文标题完全一致，目录条目必须完整列出所有章节和小节标题。

3. 前言

• Heading1："前言"
• 正文介绍：这个工具/技术是什么、能解决什么问题、适合哪些读者

4. 正文章节（5-15 章，根据主题内容量合理设计）

章节数量规则：

• 简单工具/入门主题：5-8 章
• 中等复杂度开发框架：8-12 章
• 综合性平台/语言：10-15 章

每章必须包含：

• Heading1：第X章 [章节名]
• Heading2：各小节（每章至少 2-3 个小节）
• 锚点开场：用具体场景/问题/反常识提问引入，禁止"本章介绍……"
• 正文段落：说人话、短句优先，步骤具体可操作，不水字数
• 可验证的易错点：至少 1 个有来源或可复现的常见错误，写出触发条件、具体报错或误区表现
• 有序/无序列表（使用 numbering config，禁止手动插入 bullet 符号）
• 代码块（Courier New 等宽字体 + 浅灰背景段落，代码必须可直接运行）
• 提示框（带边框底色段落，前缀：💡小贴士 / ⚠️注意 / ✅最佳实践）

典型章节参考（根据主题灵活调整）：

• 第一章：概念介绍与核心原理
• 第二章：环境准备与安装配置
• 第三章：快速入门（Hello World）
• 第四章：核心功能详解
• 第五章：常用 API / 组件
• 第六章：数据管理与状态
• 第七章：界面设计与样式
• 第八章：调试与测试
• 第九章：发布与部署
• 第十章：实战案例
• 第十一章：进阶技巧
• 第十二章：常见问题与排错
• 末章：总结与学习路线

5. 公众号 & 视频号引流页（固定，每次必须包含）

放在文档末尾，分页符后另起一页：

标题：关注我，获取更多教程（居中，Heading1，蓝色）

引导语（居中段落）：

感谢阅读这份指南！如果对你有帮助，欢迎关注我的公众号和视频号，获取更多实用技术教程、工具测评和行业干货 🎉

二维码区域：使用 2 列无边框 Table，两个二维码并排同行展示

每列单元格从上到下：

1. 平台标题（📱 公众号 或 📹 视频号，居中粗体）
2. 二维码图片（ImageRun，1.5英寸×1.5英寸 = 1371600 EMU）或占位说明文字
3. 说明文字（居中，如"扫码关注，获取图文教程"）

Table 规范：

• 表格宽度：9360 DXA，两列各 4680 DXA
• 所有边框设为 BorderStyle.NONE（无边框）
• 单元格内容水平居中、垂直居中
• 二维码图片已内置，直接读取以下路径，无需用户提供：
  • 公众号二维码：<skill目录>/assets/qr-gongzhonghao.jpg
  • 视频号二维码：<skill目录>/assets/qr-shipinhao.jpg
• 运行时用 fs.readFileSync(path) 读取图片 buffer，传入 ImageRun

二维码嵌入示例：

const path = require('path');
// 脚本在 skills/tutorial-guide/scripts/ 下，assets 在上一级
const ASSETS = path.resolve(__dirname, '../assets');
const qrGzh = fs.readFileSync(path.join(ASSETS, 'qr-gongzhonghao.jpg'));
const qrSyh = fs.readFileSync(path.join(ASSETS, 'qr-shipinhao.jpg'));

new ImageRun({
  data: qrGzh,
  transformation: { width: 144, height: 144 }, // 约 1.5 英寸
  type: 'jpg',
  altText: { title: '公众号二维码', description: '程序员AI破局指南', name: 'qr-gzh' }
})

结尾（居中段落）：

💬 有问题？欢迎在公众号后台留言，我会及时回复！

docx 生成技术规范

完整的 docx 生成技术规范（依赖安装、标准 imports、主题配色系统 TOOL_THEMES、样式定义、页面设置、列表配置、代码块/提示框样式、引流页 Table、Markdown 同步生成、输出路径与验证）已收录于 references。编写生成脚本前必须读取 references/docx-generation-spec.md，脚本中的所有样式和主题变量以该文件为准。

内容风格规范

教程正文必须遵循以下风格，这不是可选项——风格写错比内容写少更难弥补。

写作视角：同行，不是老师

用平视、具体的语气写，像同行在和朋友解释为什么值得学、怎么快速上手，不摆出站讲台的姿态。第一人称只能承载用户素材或可追溯记录已明确支持的真实经历，不得为了制造“同行感”假写亲历。

❌ 错误示范（AI 腔/教材腔）：

本章将系统介绍 XXX 的核心概念与使用方法，帮助读者建立完整的知识体系。

✅ 正确示范（无亲历素材时）：

配置 XXX 时，有个容易忽略的细节：参数 Y 一旦写错，启动时就会报 invalid configuration。这章先把这个参数说清楚。

五条硬规则

1. 开场要有锚点：每章用一个具体场景/报错/反常识问题开头，禁止用"本章介绍……"
2. 说人话：能用"改这个配置"就不说"修改对应配置项参数"；长句拆短句，读出来不绕口
3. 理性落地：感性描述之后必须跟可操作步骤，"原来如此"之后必须跟"那么怎么做"
4. 不得虚构：易错点必须来自官方文档、可复现验证、用户提供的经历或明确标注的示例。没有亲历证据时，写“常见错误是……”“如果……会……”，禁止写“我当时踩坑了”“我亲测”“我的项目里”。同样不得补造耗时、次数、对话、用户反馈、线上事故或效果数据。
5. 去 AI 味：删掉以下句式——"值得注意的是"、"不难发现"、"总而言之"、"不仅如此"、"综上所述"、"这使得……成为可能"

禁止清单

• ❌ 段落开头大量用转折词堆砌（"然而"、"此外"、"因此"……连续出现）
• ❌ 每段结尾都总结一遍刚说过的话
• ❌ 用抽象词描述抽象概念（"高效"、"强大"、"灵活"……没有具体场景支撑）
• ❌ 把官方文档原文翻译一遍当内容
• ❌ 爹味口吻："你必须"、"切记"——改成说明条件和理由的建议，如"更稳妥的顺序是"、"在 X 情况下建议 Y"

内容深度标准

每章正文必须满足以下深度门槛，不达标时必须通过 webSearch 调研补充：

深度自评：写完每章后，问自己"一个完全不懂的新手能否按本章内容独立操作？"——如果不能，说明内容不够深，执行 webSearch 补充。

生成流程

1. 分析主题：根据主题名和可选链接，推断技术领域、目标读者、内容复杂度
2. 选择主题配色：根据工具品牌色从 TOOL_THEMES 中选择对应 key（或自定义），确定 const C = TOOL_THEMES['xxx']
3. 规划章节：根据复杂度决定章节数（5-15章），设计适合该主题的结构，提前列出完整章节大纲
4. 调研补充（必要时）：对知识储备不足或需要最新信息的章节，用 webSearch 调研后再写：
   • 搜索词示例："[主题] 入门教程 最佳实践"、"[主题] 常见错误 解决方案"、"[主题] 官方文档 快速开始"
   • 优先参考：官方文档、GitHub README、知名技术博客（掘金/SegmentFault/MDN/dev.to）
   • 每章至少能提供 1 个具体的可运行示例或真实截图描述
5. 读取内置二维码：公众号和视频号二维码已内置于 skills/tutorial-guide/assets/，直接读取 qr-gongzhonghao.jpg 和 qr-shipinhao.jpg，用 fs.readFileSync + ImageRun 嵌入，禁止用占位框替代
6. 编写 JS 脚本：将完整文档内容写入 skills/tutorial-guide/scripts/gen_[主题名].js；脚本通过 resolveOutputDir() 同时生成 .docx 和 .md 到当前工作目录所属 kj-llm-wiki/raw/papers/；目录页按第 3 步大纲手动逐条构建段落，不得使用 TableOfContents
7. 执行生成：node /Users/didi/ai_space/kj-skills/skills/tutorial-guide/scripts/gen_[主题名].js
8. 自检（必做，不可跳过）：对照下方质量检查清单逐项核查，如发现任意一项不达标，修改脚本后重新执行，直到全部通过
9. 验证文件：ls -lh "$(pwd)/raw/papers/" | grep 完全新手指南 确认两个文件都存在
10. 告知用户：输出两个文件的完整路径，说明 .docx 可在 Word 打开，.md 已同步至 kj-llm-wiki

质量检查清单

正确性优先，美化其次。以下前三项不达标禁止交付。

• 主题配色：已从 TOOL_THEMES 选择匹配工具品牌色的主题，封面/表头/note 颜色与工具视觉一致
• 封面：主标题、副标题、作者、日期齐全，封面后有分页符
• 目录：手动构建，条目与正文标题逐字一致，覆盖所有章节，目录后有分页符（禁止使用 TableOfContents 组件）
• 目录条目数量与正文章节数匹配，不遗漏任何 Heading1 / Heading2
• 章节数：5-15 章，根据主题内容量合理安排
• 每章至少 2 个 Heading2 小节，内容详细可操作
• 每章包含可运行代码/命令示例，至少 1 个有来源或可复现的常见错误 + 解决方法
• 内容不足时已通过 webSearch 调研补充，不靠泛泛描述凑字数
• 风格自查：无"本章介绍……"开场，无"值得注意的是/不难发现/综上所述"等 AI 腔套话
• 每章有具体场景锚点开场，有"同行视角"而非"讲师视角"
• 无爹味口吻（"你必须""切记"），建议已说明适用条件和理由
• 真实性门禁：所有第一人称经历、耗时/次数、对话、报错、用户反馈、效果数据和发布结果均有可追溯来源；无来源的内容已改为客观说明、条件句或明确标注的假设示例
• 列表使用 numbering config，未手动插入 bullet 符号
• 代码块使用 Courier New 等宽字体 + 深色背景（1E2A3A）+ 绿色代码字
• 提示框至少出现 3 次（💡小贴士 / ⚠️注意 / ✅最佳实践）
• 引流尾页：独立成页，公众号和视频号二维码并排一行（2列无边框 Table），有引导文案
• 二维码已从 assets/qr-gongzhonghao.jpg 和 assets/qr-shipinhao.jpg 读取并用 ImageRun 嵌入，不得用占位框替代
• DOCX 文件已写入 kj-llm-wiki/raw/papers/[主题名]-完全新手指南.docx
• Markdown 文件已同步生成到 kj-llm-wiki/raw/papers/[主题名]-完全新手指南.md，章节结构与 docx 一致
• 用 ls 命令确认两个文件都存在且大小非零

用户输入格式

给我一份 [主题名] 完全新手指南
生成一份 [主题名](链接) 教程
帮我写一个 [主题名] 的新手教程，链接：[URL]

技能自动补全所有缺失信息，无需向用户询问细节。

完成后提示

文档生成并验证通过后，在告知用户文件路径的同时，主动提示：

📦 文档已生成完毕！如需为这篇教程准备公众号配套物料（前言、标题、摘要、封面图提示词、转发文案），可以说「帮我生成配套物料」或直接触发 wechat-companion 技能。