219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# Project Caffeine 文档编写规范指南
|
||
|
||
## 1. 目的与概述
|
||
|
||
本文档编写规范旨在为 **Project Caffeine** 项目的全体成员提供统一的文档撰写标准。通过标准化的元数据管理、文档结构梳理、Markdown 排版、技术写作规范以及版本控制，确保所有输出的工程文档、架构设计与迭代规划具备高度的可读性、一致性与可追溯性。
|
||
|
||
## 2. 文档头部元数据规范 (YAML Frontmatter)
|
||
|
||
结合本项目的工程化管理要求，**所有 Markdown 文档的最顶部必须包含标准化的 YAML Frontmatter 元数据块**，以便于文档站点的解析、版本检索与资产归档。
|
||
|
||
必须包含以下核心字段：
|
||
|
||
- **`title`**：文档的正式标题。
|
||
- **`description`**：用 1-2 句话高度概括文档的核心主旨与意图。
|
||
- **`type`**：文档的类型界定（如 `README`, `System Development Guide`, `Roadmap` 等）。
|
||
- **`version`**：严格遵循“版本号 + 咖啡代号 + 里程碑”格式（例如 `v1.0.0 (Arabica) - MVP` 或 `Sprint 1`）。
|
||
- **file**：文件名
|
||
- **`author`**：统一署名为 **Gitconomy Research**。
|
||
- **`date`**：遵循 `YYYY-MM-DD` 的 ISO 标准格式。
|
||
- **`tags`**：提取核心技术栈与概念标签（如 `Project Caffeine`, `MCP`, `Deep Research` 等）。
|
||
- **`license`**：声明为 `CC BY-SA 4.0`。
|
||
- **`status`**：（可选）标注文档的生命周期状态（如 `Active`, `Design and Planning` 等）。
|
||
|
||
## 3. 文档类型与结构建议
|
||
|
||
为了确保各类工程文档的逻辑完整性与结构一致性，项目内的核心文档应当遵循以下分类及标准结构框架进行编写：
|
||
|
||
### 3.1 文档类型与用途
|
||
|
||
项目文档按用途分为以下几类，主要存放于仓库的 `docs/` 目录下：
|
||
|
||
|类型|说明|示例路径|
|
||
|:--|:--|:--|
|
||
|**README**|项目总体介绍、快速开始、核心特性、状态徽章等。每个主要模块/子包应有自己的 README。|`/README.md` `/packages/server/README.md`|
|
||
|**设计文档**|记录架构决策、模块设计、协议交互、数据流等，用于指导开发和评审。|`/docs/design/`|
|
||
|**开发指南**|面向开发者的环境搭建、编码规范、测试指南、调试技巧等。|`/docs/development/`|
|
||
|**用户指南**|面向最终用户的使用说明、配置示例、FAQ 等。|`/docs/user/`|
|
||
|**API 文档**|MCP 服务暴露的 tools（工具）、prompts（提示词）、resources（资源）的详细说明，包括 JSON-RPC 参数、返回值、示例。|`/docs/api/`|
|
||
|**贡献指南**|如何提交 Issue、PR，代码规范，文档规范，行为准则等。|`/CONTRIBUTING.md`|
|
||
|**更新日志**|记录版本变更，遵循 Keep a Changelog 格式。|`/CHANGELOG.md`|
|
||
|
||
> **注意**：每个文档顶部必须包含标准化的 YAML front matter（详见第 2 节），以便机器读取元数据。
|
||
|
||
### 3.2 README 主文档
|
||
|
||
README 是项目或子包的门面，必须清晰传达项目的核心定位与接入方式，包含以下标准模块：
|
||
|
||
- **项目标题与徽章**：显示构建状态、协议、核心技术栈及目标版本。
|
||
- **项目概述**：简述项目功能、核心价值与适用场景。
|
||
- **系统架构**：放置核心的架构图或拓扑图，概述系统组件及其职责。
|
||
- **技术栈与开发环境**：
|
||
- 核心语言与运行环境（要求使用 TypeScript 与 Node.js LTS v20+）。
|
||
- 依赖管理（明确标明是否采用 Monorepo / 原生 npm Workspaces）。
|
||
- 协议与 SDK 说明（如 MCP 协议与 JSON-RPC 2.0 标准规范）。
|
||
- 安全与环境要求（如配置隔离与“零信任架构原则”）。
|
||
- **开发路线图**：按 MVP 或 Sprint 分阶段展示任务、目标及关键功能（如 Arabica Sprint 1 阶段特性）。
|
||
- **参与方式**：Issue 提交规范、PR 流程以及讨论参与指引。
|
||
- **AI 生成内容声明**：明确提示用户系统生成的报告需人工核验，仅供参考。
|
||
- **许可证说明**：明确采用双轨制许可，即源代码通常采用 **MIT License**，而文档与研究成果采用 **CC BY-SA 4.0** 协议。
|
||
|
||
### 3.3 设计文档
|
||
|
||
用于详细阐述某一具体微服务或核心逻辑（如提示词策略 Server、资源读取模块），必须包含：
|
||
|
||
- **文档标题与版本信息**。
|
||
- **模块概述**：说明该模块的具体功能、作用及与其他系统组件的交互关系。
|
||
- **系统架构图/流程图**：直观展示数据与控制流向。
|
||
- **接口定义与通信协议**：如 stdio 或 HTTP+SSE 的传输层约定。
|
||
- **数据结构与格式**：如基于 **JSON-RPC 2.0** 的 schema 定义与验证规则。
|
||
- **核心算法或逻辑描述**：如针对长文本的语义分块（Semantic Chunking）策略或缓存机制。
|
||
- **配置示例与部署说明**：指引如何修改环境路径与启动系统。
|
||
- **注意事项与最佳实践**：如代码防范越权访问、性能优化红线等。
|
||
|
||
### 3.4 图表与示意图
|
||
|
||
文档中的视觉资产需遵循以下存放与引用规范：
|
||
|
||
- **格式要求**：首选使用原生 **SVG** 代码，在特定场景下可使用高分辨率 **PNG**。若采用 SVG，必须支持通过 Git 进行 diff 比对。
|
||
- **命名与文件夹组织**：图表文件必须存放在规定的资源目录中，遵循 `docs/assets/images/<模块名称>-<内容>.svg` 或对应的后缀格式。
|
||
- _示例_：`docs/assets/images/project-caffeine-system-topology.svg`。
|
||
- **图文对应**：所有图表下方必须配备简短的说明（Caption），确保图表与其解释的上下文内容紧密对应。
|
||
|
||
## 4. 结构与格式
|
||
|
||
我们使用标准的 Markdown 进行编写。
|
||
|
||
### 4.1 文件命名
|
||
|
||
文档文件命名推荐使用清晰的中文标题或英文 **kebab-case（短横线命名法）**，如 `project-caffeine-readme.md`，以保持与工程代码文件目录的命名风格统一。
|
||
|
||
### 4.2 章节标题的结构
|
||
|
||
- 使用 ATX 风格的标题（`#`）。
|
||
- 文档主标题使用 H1（`#`），章节标题从 H2（`##`）开始。
|
||
- 标题应简洁明了，采用**句首大写 (Sentence case)**，除非是专有名词。
|
||
|
||
### 4.3 章节标题的语法规范
|
||
|
||
#### H1: 主标题——副标题
|
||
|
||
1. **结构**：**主标题 + 副标题**
|
||
2. **要求**：主标题是文章或章节的核心主题，副标题进一步解释或细化主标题，提供更多上下文或具体内容。主副标题之间可以使用破折号连接。
|
||
|
||
#### H2: 定语 + 助词 + 名词
|
||
|
||
1. **结构**：**定语 + 助词 + 名词**
|
||
2. **要求**：H2标题通常作为章节标题，简洁地描述章节的核心内容。使用定语修饰名词，使标题具有具体性和引导性，助词（如“的”）连接定语与名词。
|
||
|
||
#### H3和H4: 谓语 + 宾语
|
||
|
||
1. **结构**：**谓语 + 宾语**
|
||
2. **要求**：H3和H4标题通常用于小节或细节部分，强调动作（谓语）和受动者（宾语）。这种结构使得标题更加具体，直接描述某个操作、过程或事件。
|
||
|
||
### 4.4 列表 (Lists)
|
||
|
||
- **无序列表**：使用减号 `-`。列表项如果是一句完整的话，以句号结尾；如果是短语，则不需要。
|
||
- **有序列表**：仅在步骤有严格顺序时使用数字列表。
|
||
|
||
### 4.5 表格
|
||
|
||
- 使用标准Markdown表格语法。
|
||
- 表格前后留一空行。
|
||
- 表头与内容之间必须有分隔行。
|
||
- 尽量保持列对齐以提高可读性。
|
||
|
||
### 4.6 链接与图片
|
||
|
||
- 使用相对路径引用仓库内图片。
|
||
- 外部链接应提供完整URL，包括https://前缀。
|
||
- 提供清晰的alt 文本，兼顾无障碍与 LLM 理解。
|
||
|
||
### 4.7 强调
|
||
|
||
- **粗体 (`text`)**：用于强调关键概念、新的术语定义或需要用户特别注意的UI元素。**不要滥用**，满篇粗体等于没有重点。
|
||
- _斜体 (`*text*`)_：用于书籍、文章标题，或表示语气的强调。
|
||
- `行内代码 (Inline Code)`：用于正文中的命令、文件名、分支名、路径或配置项。
|
||
|
||
## 5. 技术写作规范
|
||
|
||
这是体现专业性的核心区域。
|
||
|
||
### 5.1 代码块 (Code Blocks)
|
||
|
||
所有代码块必须指定语言标记，以便正确高亮。
|
||
|
||
- **命令行操作**：使用 `bash` 或 `sh`。
|
||
- 命令的输出结果**不**带 `$` 符号。
|
||
- 需要用户替换的部分使用尖括号 `<placeholder>` 包裹。
|
||
- **配置文件**：使用 `gitconfig`、`yaml`、`json` 等对应格式。
|
||
- **文件内容示例**：如果只是展示文本内容，可以使用 `text`。
|
||
|
||
### 5.2 标点符号
|
||
|
||
- 使用全角中文标点符号（，。！？：；“”‘’（））。
|
||
- 中英文混排时，英文与中文之间应保留一个空格（此项通常由排版引擎自动处理，但在 Markdown 源码中手动添加可以提高可读性）。
|
||
|
||
## 6. 文字风格规范指南
|
||
|
||
### 6.1 文字的情绪化与中立性
|
||
|
||
在编写文档时，我们应避免使用情绪化或带有政治色彩的语言。这不仅是为了确保技术的客观性，也是为了尊重读者的多元背景和文化视角。以下是一些具体的规范：
|
||
|
||
1. **避免带有攻击性或情绪化的语言**：我们的目标是帮助读者理解技术，而非通过情绪化的语言来引导思维。避免过于夸张、激烈的表述。
|
||
2. **避免政治性语言和隐含的偏见**：在技术文档中，避免任何可能引发争议的政治色彩和社会偏见。
|
||
3. **避免过于主观或过度的情感表达**：文档应该以冷静、客观的语气提供信息，而不是通过情感化的语言来影响读者的判断。
|
||
4. **简洁明了，避免冗长和情绪化的描述**：避免描述性语言过于冗长或情感化的调调。尽量做到简洁直接，保持专业性。
|
||
|
||
### 6.2 专业性和清晰度
|
||
|
||
1. **保持语气的中立性**：所有表达应当中立、平衡，避免偏袒或倾向某一方的语气。专业的写作风格是直接、简洁和清晰的，不带有个人情绪色彩。
|
||
2. **使用简洁明了的句式**：使用清晰的句式，避免过于复杂的结构。尽量使每个句子都传达一个清晰的想法，避免无谓的修饰和修辞手法。
|
||
|
||
### 6.3 拒绝“翻译腔”
|
||
|
||
这是我们文字风格的第一大敌。我们在编写或翻译内容时，必须符合中文的自然表达习惯。
|
||
|
||
1. **减少“被”字句**：英文习惯用被动语态，而中文习惯用主动语态。
|
||
2. **警惕“的”字风暴**：过多的“的”字会让句子变得粘连、拖沓。尝试通过重组句子来消除不必要的“的”。
|
||
3. **避免生硬的从句**：不要试图在一个长句中保留英文的所有修饰成分。将长句拆分为短句，符合中文的“流水句”特征。
|
||
|
||
### 6.4 词汇的选择
|
||
|
||
1. **动词的力量**：使用精准、有力的动词，避免使用“进行”、“作出了”等万能动词。
|
||
2. **术语的“中文本地化”**：除非是专有名词（如 Rebase, Cherry-pick 这种很难翻译传神的），否则尽量使用标准的中文术语，但要标注英文原词。
|
||
- **首次出现**：暂存区 (Staging Area)
|
||
- **后续使用**：暂存区
|
||
|
||
### 6.5 中英文混排与标点符号
|
||
|
||
1. **空格规范**：**汉字与英文、汉字与数字之间，必须保留一个空格。**
|
||
2. **标点符号**：
|
||
- **全角标点**：中文句子中，必须使用全角标点（，。！？：；（））。
|
||
- **英文标点**：只有在行内代码（Inline Code）或英文专业术语（如 `user.name`）中才使用半角标点。
|
||
- **空格禁忌**：全角标点与汉字或英文之间，**不需要**添加空格。
|
||
|
||
### 6.6 标题与段落
|
||
|
||
1. **标题即论点**：标题不应只是名词，最好是动宾结构或完整的论点，让读者只看目录就能懂大意。
|
||
2. **倒金字塔结构**：段落的第一句必须是**中心句 (Topic Sentence)**。先说结论，再展开解释，最后给例子。不要让读者读到最后一行才知道这一段想说什么。
|
||
|
||
## 7. 图形即代码 (Diagram as Code) 集成规范
|
||
|
||
文档中嵌入的架构图、时序图等图形资产，必须严格遵循《图形即代码设计规范指南》：
|
||
|
||
- **格式要求**：所有核心图表必须是可内嵌于 Markdown 的原生 **SVG** 代码，并支持通过 Git 进行 diff 比对与历史追溯。
|
||
- **兼容性与背景**：为防止 Git 平台深色模式下的反色问题与 XSS 清洗，**推荐在 SVG 最底层放置纯白背景**（`<rect width="100%" height="100%" fill="#FFFFFF" />`），且**严禁包含 `<script>` 标签或外部图像/字体引用**。
|
||
- **响应式适配**：SVG 必须使用 `viewBox` 属性定义坐标系，并将宽高设置为 `100%`，确保在 Markdown 容器内流畅等比缩放。
|
||
|
||
## 8. 术语与内容结构统一
|
||
|
||
- **MCP 协议原语**：在文档中描述系统能力时，需统一使用标准术语。例如，暴露给模型的主动操作必须统一称为 **Tools (工具)**；静态上下文数据源统一称为 **Resources (资源)**；复用模板称为 **Prompts (提示词)**。
|
||
|
||
## 9. 版权与许可声明
|
||
|
||
为了保障知识产权与开源精神的传承，**每一份标准文档的末尾，必须固定包含以下完全一致的版权与开源许可证声明**：
|
||
|
||
> ## 许可声明
|
||
>
|
||
> 本文档采用 **知识共享署名--相同方式共享 4.0 国际许可协议 (CC BY--SA 4.0)** 进行许可，© 2025-2026 Gitconomy Research。 |