basic-knowledge-writing

name	basic-knowledge-writing
description	BasicKnowledge 写作技能：在 BasicKnowledge/ 下撰写新文章或新模块时，确保风格、结构、质量与现有内容一致。Use when: 新建知识模块、撰写技术文章、扩展现有模块内容。

BasicKnowledge 写作技能

用途

指导在 BasicKnowledge/ 下创建新模块或撰写新文章，使其在结构、命名、语言风格、排版规范上与现有内容保持一致。

模块结构规则

BasicKnowledge/
├── 模块名/                     ← 下划线连接的英文短名（如 deep_learning）
│   ├── introduction.md         ← 必须存在，模块总览与索引入口
│   ├── 主题文件.md             ← 单一概念一个文件
│   └── 子模块目录/             ← 可选，内容足够独立时拆分
│       └── introduction.md     ← 子模块同样需要入口

关键原则

• 每个模块必须有 introduction.md 作为入口。
• 禁止在 BasicKnowledge/ 根目录直接放内容文件，必须放在子模块中。
• 子模块可嵌套，但嵌套层级不宜超过 2 层。

文件命名规范

类型	格式	示例
单一概念	概念名.md	transformer.md、gate.md、cnn.md
对比/关联	概念A_and_概念B.md	sql_and_rag.md、meta_and_auto.md
入口文件	introduction.md	固定名称，不可变

• 使用下划线连接多词（math_foundations.md），不用驼峰或连字符。
• 不加序号前缀（不写 01_fundamentals.md）。
• 不加时间戳。

Introduction 标准模板

每个 introduction.md 遵循 5 层递进结构：

第 1 层：开篇定位（1-2 段）

用一句话回答"这个模块讲什么"。可引用上层模块或外部背景建立语境。

第 2 层：问题陈述

• 为什么需要这个模块（痛点或机遇）。
• 传统方法的局限。
• 新范式的价值主张。

第 3 层：概念速写（表格）

用表格列出模块内所有文件与内容简介，附相对路径链接：

| 文件 | 内容简介 |
|------|---------|
| [transformer.md](./transformer.md) | Transformer 架构深度解析 |

第 4 层：历史脉络或演进阶段

递进式讲述学科发展，标注关键年份与里程碑，每阶段配短评。技术类模块此层必须；哲学类模块可替换为"思想演进"。

第 5 层：学习建议与路线

指明推荐阅读顺序、前置知识、应用场景。

写作风格分类

根据内容类型选择对应风格：

类型	特征	适用模块
概念类	LaTeX 数学推导主导、引理-证明风格、少代码	deep_learning/、llm/transformer.md
工程类	表格密集、编号实践建议、伪代码或代码框架	llm/engineering.md、agent_workflow/
哲学类	对话式叙述、类比与隐喻、明确价值判断	meta_code/、data_tech/introduction.md

同一模块内可混合多种风格，但单个文件应以一种风格为主。

语言约定

1. 简体中文为主，不混用繁体。
2. 技术术语首次出现时附英文括号：注意力机制（Self-Attention）。
3. 后续引用同一术语可直接用中文或英文，保持文内一致。
4. 避免一二人称客套，直接陈述事实。
5. 句式紧凑，一段不超过 6-8 行。

标题层级

# 一级标题     ← 文件主标题，仅 1 个
## 二级标题    ← 核心章节，通常 3-6 个
### 三级标题   ← 小节展开
#### 四级标题  ← 偶尔使用，保持可读性

• 禁止五级标题。如需更细粒度，拆分为新文件。
• 二级标题可用中文序号前缀（## 一、xxx、## 二、xxx）或直接用标题。
• 单文件二级标题不超过 8 个字。

数学公式规范

场景	格式
行内公式	$x = \mathbf{w}^T \mathbf{x} + b$
独立公式	$$...$$ 单独成行
向量	\mathbf{x}（粗体小写）
矩阵	\mathbf{W}（粗体大写）
标量	普通字体
推导过程	用 \implies 或 aligned 环境

代码块使用

• 工程/实践类文件中使用 Python 代码，标注语言标签：```python。
• 数学推导中使用伪代码，标注 ```text 或不标注语言。
• 纯概念/数学类文件中尽量避免代码块。

交叉引用

• 模块内引用：相对路径 [gate.md](./gate.md)。
• 跨模块引用：相对路径回溯 [transformer.md](../llm/transformer.md)。
• 章节引用：文字说明 见下文第 X 小节，不使用 HTML 锚点。
• introduction.md 汇聚所有子文件入口，是模块的唯一查阅起点。

表格使用

• 用于快速对比、参数列表、文件索引。
• 单表不超过 6-8 行，过长则拆分或改用列表。
• 每行不超过 120 字符。

新模块创建流程

1. 确定模块名：英文短名，下划线连接，放在 BasicKnowledge/ 下。
2. 创建 introduction.md：按 5 层模板撰写，先完成第 1-3 层，后续迭代补充 4-5 层。
3. 拆分子文件：每个核心概念独立为一个 .md 文件。
4. 建立引用网络：在 introduction.md 表格中链接所有子文件。
5. 更新架构文档：在 docs/architecture/repository-structure.md 中登记新模块及其文件。

新文件添加流程（扩展现有模块）

1. 在目标模块目录下创建 .md 文件，遵循命名规范。
2. 更新该模块的 introduction.md，在概念速写表中添加新条目。
3. 更新 docs/architecture/repository-structure.md。

刚性约束

• 禁止在 BasicKnowledge/ 根目录放内容文件。
• 禁止五级及以上标题。
• 每个模块必须有 introduction.md。
• introduction.md 必须包含文件索引表（第 3 层）。
• 任何新增或修改后必须同步更新 docs/architecture/repository-structure.md。
• 所有 .md 文件使用 UTF-8 编码。