# 写作风格指南

以下规则用于 AI 在本书中撰写或改写章节内容，保持与现有章节一致的写作风格与结构。

本项目包含两个教程：
- **编程导引**（docs/chapters）——JavaScript 编程入门
- **Agentic AI**（docs/agentic-ai）——AI 协作与 Agent 实践

## 语气与叙述

- 友好、耐心、口语化、引导式，但不幼稚、不俯视读者，也不把读者当成小孩子。
- 常用提问引导思考（例如"为什么会这样？""那该怎么办？"），语气保持专业与克制。
- 先给直观解释，再给更严格的概念或结构化表述。
- 允许轻量自我指代/引导（如"我们可以看到""我们先看一个例子"）。
- 不用类比来解释概念。直接用清晰的语言把概念说清楚，让一般读者也能理解。

## 概念呈现方式

- 先直觉，再进入正式概念或定义。
- 即便解释口语化，也尽量给出标准、严谨的术语和定义，避免误导。
- 中英术语并列出现，格式常为"中文（English）"或"中文 English"。
- 不堆砌概念，控制密度与节奏。
- 不用"短句总结"的固定模板。要点在正文中自然强调即可。
- 加粗要克制。每个段落最多保留一个强调点，不要每个关键词都加粗。

## 章节结构与节奏

- 使用清晰的 Markdown 标题层级（# 章节、## 小节、### 子节）。
- 每个小节围绕一个明确问题或概念展开。
- 示例与解释交替出现，避免纯概念堆叠。
- 常见收尾结构：
  - "小结"（每条控制在一句话以内）
  - "练习"（列表形式，偏可操作，一到四条为宜）
  - "延伸阅读"（链接到 reference 目录）

## 示例与代码

- 以 JavaScript 为主，必要时可以用伪代码或其他语言对比，但需明确标注。
- 代码块短小、可直接运行，示例名称尽量直观。
- 代码前后给出简短解释，强调"为什么这么写/会发生什么"。
- 允许用数学公式（LaTeX）辅助说明，但不应喧宾夺主。

## 格式与排版

- 列表常用无序列表（* 或 -），用于"要点/原因/步骤"。
- 提醒/注释常用引用块（> 提醒：...）。
- 强调差异或对比时使用短段落分隔。

## 读者假设

- 默认读者为零基础或初学者，尽量减少跳步。
- 遇到"容易误解/容易出错"的点要显式提醒。
- 不制造焦虑，适当安抚读者，明确展示学习进步与里程碑。

## 链接与引用

- "延伸阅读"集中链接到 `docs/reference`（或其子目录）下的概念条目。
- 章节主体尽量少外链；必要外链放在首次出现处，且简短。

## 练习风格

- 练习题偏"动手写/动手改"，一到四条为宜。
- 明确引导 Learn-by-doing，鼓励多动手、多尝试。
- 引导发散思维，不局限于教程中给定的例子或解法。
- 题目表述清晰，避免过度开放。
- 与本章关键概念直接相关。

## Agentic AI 教程特有约定

- 核心概念（Prompting 基础、对齐定律、不要焦虑、技能>工具）在多个章节反复出现，但每次侧重不同，不做简单重复。
- 反模式和最佳实践分散到各章节的相关位置讲，不在开头集中灌输。
- 技术概念（MCP、Gateway、Memory 等）点到为止，配合一两个例子，不深入协议细节。
- 动手练习不给具体代码，只描述实现步骤和目标，让读者自己写。
- 附录（reference/）放技术细节较深的内容（RAG、API 调用），正文只讲原理和概念。