{{项目名}} 写作规范

基本信息

属性	值
书名	{{书名}}
目标读者	{{读者画像}}
源码项目	{{项目名}} {{版本号}}
编程语言	{{语言}}
预计章节数	{{章节数}}
每章字数	{{最低字数}}~{{最高字数}}字
项目仓库	{{仓库URL}}

文风定义

• 人称: 第一人称复数（"我们"）
• 语气: {{风格描述}}
• 比喻密度: 每个核心概念至少一个比喻
• 幽默程度: {{无/偶尔/适中/频繁}}
• 读者称呼: {{如"你"/"读者"/"各位开发者"}}

风格示例

{{示例段落}}

禁止的表达方式

• ❌ {{禁止表达1，如"众所周知"}}
• ❌ {{禁止表达2，如"显而易见"}}
• ❌ {{禁止表达3，如"简单来说"后面跟很复杂的内容}}

格式规范

标题层级

层级	用途	数量限制	示例
H1 (#)	章标题	每章仅一个	# 第3章：中间件的秘密
H2 (##)	主要节	3~6个/章	## 请求的一生
H3 (###)	子节	按需	### 路由匹配算法
H4 (####)	避免使用	过深则重构	—

代码块规范

• 必须标注语言: ```
• 关键行添加注释: 解释"为什么"而不是"是什么"
• 单个代码块不超过30行
• 超长代码使用省略: // ...省略相关代码... 并说明省略了什么
• 文件路径标注: 代码块上方标注源文件路径

段落控制

• 每段不超过 5行
• 避免连续 3段 以上纯文字（穿插代码/图表/列表）
• 章节开头用 故事/问题/悬念 引入
• 每个H2节结束前有一句 承上启下 的过渡

图表规范

规则：凡是需要画流程图、架构图、层次图、目录树的地方，一律使用 Mermaid，禁止使用 ANSI 盒子字符（┌ ─ ┤ ├ └ │）。

• 流程图用于描述 {{流程类场景，如请求处理流程}}
• 类图用于描述 {{结构类场景，如模块依赖关系}}
• 每张图必须有 标题 和 简要说明

常用图类型：

场景	图类型	指令
垂直层次架构（如分层架构图）	flowchart	flowchart TD
水平处理流程	flowchart	flowchart LR
阅读路线图 / 多步骤顺序	flowchart	flowchart TD + -->
文件目录树	graph	graph LR
并列分类对比	flowchart	flowchart LR + 分类节点
分组/子系统布局	flowchart + subgraph	subgraph name["…"]

语法要点：

• 含空格/中文/括号的标签必须加引号：node["第6层：入口 (CLI)"]
• 多行标签用 <br/>：node["第一行<br/>第二行"]（不能用 \n，Mermaid 不识别）
• 节点 ID 只用英文字母/数字，不用中文
• 不支持 **bold** Markdown 语法，保持纯文本标签

特殊标记

• 💡 提示: 锦上添花的补充知识
• ⚠️ 注意: 容易踩的坑
• 🔍 深入: 可以跳过的深层探讨
• 📝 练习: 动手实践的建议

术语规范

保留英文的术语

{{列表，如：Promise, callback, middleware, event loop, closure}}

翻译的术语

英文	中文翻译
{{英文术语1}}	{{中文翻译1}}
{{英文术语2}}	{{中文翻译2}}

术语使用规则

1. 首次出现: 中文翻译（English Original）
2. 后续出现: 仅使用中文翻译或仅使用英文（按上面的约定）
3. 标题中: 优先使用中文，括号注英文
4. 代码注释中: 跟随代码语言

敏感内容规避

• ❌ 不评价商业产品优劣（如"X框架比Y框架好"）
• ❌ 不涉及政治/宗教/性别话题
• ❌ 避免绝对化表述（"最好的"、"唯一的"、"一定要"）
• ✅ 技术对比保持客观，只陈述事实和数据
• ✅ 引用他人观点时注明出处

章节结构模板

# 第{{N}}章: {{章标题}}

## 开场引入（200~300字）
<!-- 用故事/问题/悬念引入。例如：
  "想象你正在调试一个线上问题，日志显示请求到达了服务器，
   但响应却神秘地消失了。你检查了路由，检查了中间件，
   一切看起来都没问题。直到你打开了{{模块}}的源码..."
-->

## {{节标题1}}
<!-- 第一个核心知识点 -->

## {{节标题2}}
<!-- 第二个核心知识点 -->

## {{节标题3}}
<!-- 第三个核心知识点。3~5个H2节为宜 -->

## 代码解析
<!-- 带注释的关键代码段，分步骤讲解 -->

## 设计思考
<!-- 为什么作者这样设计？有什么替代方案？做了什么取舍？ -->

## 小结
<!-- 200字以内，回顾本章要点，用列表形式 -->

## 思考题（可选）
<!-- 2~3个启发性问题，不是考试题，而是引导读者深入思考 -->
1. {{问题1}}
2. {{问题2}}

交叉引用规范

• 前向引用: "我们将在第{{N}}章详细讨论这个话题"
• 后向引用: "正如第{{N}}章所述，..."
• 避免循环引用（A引用B，B又引用A）

版本与更新

• 当源码项目发布新版本时: {{处理策略，如"仅更新受影响章节"}}
• 勘误流程: {{如"在audit-log.md中记录，下一轮审查时修正"}}