Project-Caffeine/docs/guides/project-caffeine-documentation-specification-guide.md

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。