{{項目名}} 寫作規範
基本信息
| 屬性 | 值 |
|---|---|
| 書名 | {{書名}} |
| 目標讀者 | {{讀者畫像}} |
| 源碼項目 | {{項目名}} {{版本號}} |
| 編程語言 | {{語言}} |
| 預計章節數 | {{章節數}} |
| 每章字數 | {{最低字數}}~{{最高字數}}字 |
| 項目倉庫 | {{倉庫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}} |
术语使用规则
- 首次出现: 中文翻译（English Original）
- 后续出现: 仅使用中文翻译或仅使用英文（按上面的约定）
- 标题中: 优先使用中文，括号注英文
- 代码注释中: 跟随代码语言
敏感内容规避
- ❌ 不评价商业产品优劣（如"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中記錄，下一輪審查時修正"}}