Skip to content

Latest commit

 

History

History
74 lines (54 loc) · 3.48 KB

File metadata and controls

74 lines (54 loc) · 3.48 KB

写作风格指南

以下规则用于 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 调用),正文只讲原理和概念。