写作风格与格式规范
目标：深入浅出、通俗易懂、风趣幽默，但不牺牲技术准确性。
本文档已合并出版社《作者写作规范13条（1.27版）》的核心要求；后续章节写作与改稿以本规范为准。
- 默认读者对 Agent、LLM、终端/命令行（CLI）、Node 环境都不熟
- 但默认读者愿意跟着复制命令、看截图、做实验
基本原则（强约束）
Section titled “基本原则（强约束）”- 先给“能跑起来”的路径：读者能在 10 分钟内看到可用结果。
- 一页只解决一件事：避免巨段概念堆叠。
- 每个关键术语第一次出现必须解释：给一句话定义 + 一个例子。
- 少用缩写，先中文后英文：例如“终端/命令行（CLI）”“向导（Wizard）”；读者不需要先背缩写。
- 所有会过期的内容必须绑定版本与日期：命令输出、截图、UI 文案。
- 所有重要断言必须提供来源链接：Release/官方文档/权威文章。
- 坚持一致性：同一概念全书用同一术语，不混用别名（如“渠道”不要与“通道”混用）。
- 避免冗余：术语英文注释只在首次出现标注；重复内容用“参见”而非重复讲述。
- 强化目的性：每章、每节、每段均围绕该节目标，不写“与目标无关的好看内容”。
- 结构化优先：超过一页的连续叙述优先拆成标题与小节，不堆成长段。
Markdown 约定（建议）
Section titled “Markdown 约定（建议）”- 标题：Starlight 会用 frontmatter 的
title自动渲染页面主标题，因此正文中不要再写重复的# 章节标题；正文从##开始即可。 - 标题层级：
#仅用于章节标题；正文至少体现到三级结构：##章内模块（例如“背景与直觉”“动手步骤”）###节（例如2.1、2.2）####小节（例如2.1.1、2.1.2、2.1.3）
- 篇首语/章首语：
- 每一篇开始处必须有篇首语（1~2 段：价值意义 + 本篇内容概览）。
- 每一章开始处必须有章首语（1~2 段：本章内容概括 + 可选的学习提醒）。
- 左侧目录锚点规则：若侧边栏展示到
x.y，则在对应### x.y标题前增加锚点：<a id="sec-2-1"></a>### 2.1 运行环境检查
- 命令：使用代码块，并标注运行环境。
- 提示框：用 Blockquote
>表示“注意/警告/建议”。
出版社 .dotx 模板对齐规则（必用）
Section titled “出版社 .dotx 模板对齐规则（必用）”已解析模板：技术类图书写作模板（必用）.dotx。后续写作与排版需遵守以下映射：
- 目录层级（与模板一致）：
- 一级：
第X章 ... - 二级：
X.Y ... - 三级：
X.Y.Z ...（建议尽量有） - 四级及以下仅在内容足够长时使用（避免碎片化标题滥用）
- 一级：
- 篇首语/章首语：
- 每篇必须有篇首语（1~2 段：价值意义 + 内容概览）
- 每章必须有章首语（1~2 段：本章重点 + 可选注意事项）
- 标题提炼：
- 超过一页的连续内容，必须拆成可检索标题，不写无结构长段
- 每个小节只服务一个目标，避免“一个小节做三件事”
Markdown 到 .dotx 样式映射（交稿口径）
Section titled “Markdown 到 .dotx 样式映射（交稿口径）”为保证后续转 Word 时不返工，按以下映射写作：
##→ 章内主节（对应模板 Heading 2）###→ 节（对应模板 Heading 3）####→ 小节（对应模板 Heading 4）- 普通段落 → 正文（模板正文样式）
- 代码块 → 代码清单（模板中存在“代码清单”样式）
- 图题 → “图题/图注”样式（模板存在图题、图注、图序号样式）
- 表题 → “表题”样式（模板存在表题样式）
说明：当前我们在 Markdown 阶段先保证语义结构正确；最终 Word 排版时再将语义映射到模板样式。
链接写法规范
Section titled “链接写法规范”外部参考链接必须可被完整识别与复现。约定如下：
- 正文中出现外部链接时：尽量使用“文字 + 展开 URL”的形式，例如：
- Getting Started（https://docs.openclaw.ai/start/getting-started）
- 参考链接清单：统一用可见 URL 列表（不要只给超链接文本），例如：
## 参考链接
- Getting Started：<https://docs.openclaw.ai/start/getting-started>- Wizard：<https://docs.openclaw.ai/start/wizard>- 这样做的好处是：Astro 预览仍可点击，同时读者也能直接看到完整 URL。
图片、表格、代码（出版社要求）
Section titled “图片、表格、代码（出版社要求）”- 图片：
- 必须有图题与章节内编号（例如“图 1-1”），并在正文先文后图说明用途。
- 图片不得影响印刷可读性；自绘图优先白底高对比度，文字尽量精简。
- 表格：
- 必须有表题与编号（例如“表 1-1”），并在正文先文后表说明用途。
- 表格必须可编辑，不使用截图充当表格。
- 代码：
- 代码块不加“图/表式编号”，保持可复制可编辑，不用截图。
- 代码注释需中文化（必要英文术语可保留）。
- 缩进与格式按原语言规范，不混入正文格式。
英文与术语规则（出版社要求）
Section titled “英文与术语规则（出版社要求）”- 英文解释只在术语首次出现时标注；后文优先使用统一中文术语。
- 缩写首次出现使用：
缩写（英文全称，中文解释）。 - 非专有名词英文优先小写；动词不夹杂英文（避免类似“new 一个对象”）。
- 图中可翻译的英文尽量翻译，变量名/专有名词可保留。
敏感与引用合规（出版社要求）
Section titled “敏感与引用合规（出版社要求）”- 不写政治敏感、宗教敏感、负面影射性内容；不使用网络化、情绪化表达。
- 涉及政策与公共信息时，仅采用权威来源并给出明确出处。
- 引用他人图/表/观点/原文必须明确标注来源；网络文章默认不直接照搬。
- 优先“改写 + 标注来源”，避免大段直接引用。
内部标注（审阅用）
Section titled “内部标注（审阅用）”为便于你在 Astro 上审阅并区分“读者可见内容 vs 内部工作内容”，我们约定：
- 读者可见内容：正常 Markdown 正文。
- 内部工作内容（灰色标注）：统一使用 Starlight 的
note提示块，并写明编辑注，例如：
:::note[编辑注：事实核验]- Claims...- Sources...:::这类内容在预览站里会以灰色显示，便于审阅；出最终定稿时可整体删除或转移到“写作日志/核验记录”。
- 完全不可见内容：使用 HTML 注释（页面不会渲染），例如：
<!-- TODO: 这里补充截图占位与命令输出 -->- 允许轻松吐槽（例如“把密钥配错并不罕见”）
- 禁止低俗、擦边、涉政隐喻与现实人物影射