WorkBuddy 教材编写规范（Textbook Style Guide）¶
本规范是教科书（textbook/ 目录，ch01~ch09）编写与修订的统一对照基准。
版本基准：本教材以 WorkBuddy 当前最新版本为准。产品界面与功能迭代较快，具体以实际产品为准。涉及版本差异的内容显式标注。
1. 教材定位与边界¶
| 原则 | 说明 |
|---|---|
| 教材讲 what / why | 概念、功能、机制、使用场景、最佳实践——“是什么、为什么、怎么用” |
| 教材 ≠ 操作手册 | 可独立阅读的知识体系；操作步骤精炼到关键流程，不逐步截图 |
| 截图标注规范 | UI 操作位置统一标注 > 📷 请参见产品界面：[操作路径描述]，不嵌入实际截图 |
| 官方文档引用 | 引用官方文档内容时标注带链接的出处：（[官方文档《页面名》](页面URL)）；无法对应具体页面时使用 （[官方文档](https://www.workbuddy.cn/docs/workbuddy/Overview)） |
2. 每章统一骨架¶
# 第 N 章 <中文章节名>
> 章首引言：本章定位 + 与其他章节的关系（1-3 行）
## 学习目标
（“学完本章，你应该能够”，5-8 条，每条可测量）
## N.1 <一级小节>
### N.1.1 <二级小节>
（主体按知识体系组织）
## 本章小结
（要点回顾 + “衔接下一章” 一段）
## 思考题
（3-5 道引导性题目）
3. 内容规范¶
3.1 概念讲透，不留指针¶
- 所有概念在首次出现时直接讲完整
- 禁止“详见第 X 章/后面会介绍”这类推脱写法
- 允许“第 X 章展开实操/第 X 章深化”（概念已讲完 vs 实操未做）
- 重要知识点前后章节呼应、多角度加深，鼓励
3.2 重要概念不用表格¶
- 重要概念（功能、机制、原理）禁止用表格带过——用段落 + 列表展开讲
- 表格只允许两类：
- 速查类：功能速查、配置项速查、渠道对比速查
- 对比决策类：模式对比、渠道选型——表后必须跟“选择建议”段落
- 判断标准：表格是否承载“讲解”？承载讲解必须写成文字；纯对照/速查才用表
3.3 多选项必讲“为什么选它”¶
凡出现多个选项（工作模式/接入渠道/模型选择/连接器…），必须：
- 每个选项讲清特点
- 给出适用场景
- 说明推荐选择与理由
- 用“选型口诀”一句话收尾
3.4 操作流程的表述纪律¶
- 关键操作流程用编号步骤（Step 1/2/3…）
- 每步标注操作路径（如「左侧边栏 → 专家 → 技能」）
- UI 截图位置统一标注
> 📷 请参见产品界面：[路径] - 不要大段堆砌操作细节，聚焦关键节点
3.5 安全与最佳实践¶
- 每章涉及权限/数据/安全的内容，设独立小节或提示块
- 使用
> ⚠️ 安全提示：格式标注安全注意事项 - 最佳实践用
> 💡 最佳实践：格式标注
3.6 颗粒度与篇幅¶
- 篇幅参考：150-400 行/章（视主题容量；以内容准确完整为准，不机械凑字数，宁精勿滥）
- 合并章节（如第 4 章、第 8 章）可适当超过上限，但需保证结构清晰、小节粒度合理
- 每章至少覆盖：核心概念详解、使用场景、操作要点、最佳实践
4. 术语规范¶
4.1 产品专有术语（保留原文）¶
以下术语全书统一使用官方名称，不翻译不改写：
| 术语 | 说明 |
|---|---|
| WorkBuddy | 产品名 |
| Ask / Craft / Plan | 三种工作模式 |
| Skill | 技能（AI 工具函数） |
| MCP | Model Context Protocol |
| Agent | 专家（AI 智能体） |
| Team | 专家团 |
| Claw / 助理 | 远程操控功能 |
| Token Plan / Coding Plan | 计费方式 |
| Ollama | 本地模型部署工具 |
| OPC | One Person Company（一人公司） |
4.2 通用术语一致性¶
- “工作空间”不写“工作区”
- “连接器”不写“连接件/接口”
- “产物”不写“产出物/成果物”
- “积分”不写“点数/额度”
- “提示词”不写“提示语/Prompt”（Prompt 可与“提示词”互用）
5. 格式规范¶
| 项目 | 规范 |
|---|---|
| 标题 | # 第 N 章 <中文名>；小节 ## N.1 / ### N.1.1 |
| 文件名 | chNN-english-name.md（如 ch01-product-fundamentals.md） |
| 学习目标 | “学完本章，你应该能够：” + 编号列表，动词可测量 |
| blockquote | 用于：关键认知、最佳实践、安全提示、截图标注 |
| 表格 | 仅速查/对比决策类（§3.2），表后跟文字 |
| 章间引用 | 用“第 N 章”格式；不使用文件名 |
6. 质量检查清单（每章交付前自查）¶
- 无 OCR 乱码残留
- 无口语化/幻灯片碎片（如「就是我们今天要讲的」）
- 无内容重复（原文多处小结与正文重复的问题已消除）
- 官方文档引用内容已标注来源
- 术语与本规范术语表一致
- 章节骨架完整（学习目标/正文/小结/思考题）
- 重要概念未用表格带过
- 截图位置统一使用标注格式
- 安全/最佳实践独立标注
版本记录： - v1.0：基于 K8s 教材编写规范适配 WorkBuddy 课程（2026-08） - v1.1：章节结构由 11 章整合为 9 章；篇幅规范调整为 150-400 行/章（2026-08） - v1.2：章节顺序重构——灵感前置至第 3 章；技能/专家/专家团合并为第 4 章；连接器与资料库合并为第 5 章；模型配置独立为第 6 章；助理与自动化分别位于第 7、8 章（2026-08） - v1.3：全书事实审校——以官方文档为准逐条核实知识点，修正口径与数字出处，正文补充（官方文档）引用标注（2026-08）