跳转至

文档规范 / Documentation Standard

适用范围 / Scope

本页定义当前仓库文档站的信息架构、写作边界和评审规则。

  • 文档源文件以 docs/ 和 mkdocs.yml 为准。
  • API 详情优先由源码 docstring 和 mkdocstrings 生成。
  • 业务逻辑、公开接口、配置、系统边界或导航结构变更后，默认必须同步文档。

目标 / Goals

新的文档体系首先解决“放哪里”和“怎么找”：

  • 可预测 / Predictable：每个主题有一个明显归属。
  • 低重复 / Low Duplication：系统说明、运维说明和参考说明不互相复制。
  • 可扩展 / Scalable：新增子系统时，不需要再发明一套新的顶层分类。

顶层分类 / Top-Level Taxonomy

区域 主要回答的问题 放置内容
getting-started/ 我第一次进入仓库，先看什么 环境准备、快速启动、项目地图、阅读路径
concepts/ 这些跨系统概念分别是什么意思 agents、sessions、knowledge sources、MCP、runtime 概念
core/ 当前实现层是怎么工作的 平台深度设计、runtime 设计、service 架构
database/ 数据落在哪里，如何迁移 schema、关系、索引、迁移策略
systems/ 某个系统如何工作 RAG、编排器、MCP、Fusion、评测、单证识别等系统页
guides/ 我具体该怎么操作和使用 配置、部署、Studio 使用、专题操作步骤
operations/ 我该如何部署、配置、治理、排障 运维与 runbook 内容
reference/ 我需要快速查字段、配置、代码入口 API、配置、存储、数据模型、代码索引
api/ 我需要源码级接口与对象说明 端点、契约、服务对象、解析器、模型配置
chameleon/ freight/ marketplace/ roadmap/ ai-agent/ 这是一个跨系统专题还是规划方案 产品线、业务专题、专项设计、路线图
changelog/ timelines/ 这个系统怎么演进到现在 时间线与历史材料
dev/ 研发维护者应遵守什么规则 贡献规范、文档规范、评测、测试、性能

放置规则 / Placement Rules

四步判断法 / Four-Step Decision Rule

写新文档前，先依次判断这四件事：

  1. 它讲的是“怎么理解”还是“怎么操作”。
  2. 它服务于“跨系统抽象”还是“单一系统”。
  3. 它适合“连续阅读”还是“查表检索”。
  4. 它表达的是“当前状态”还是“历史 / 规划”。

如果这四步还不能唯一定位，说明主题过大，应该先拆页，再分别放置。

Getting Started

放在 docs/getting-started/。它是新读者入口，只负责帮助读者启动、定位仓库和选择阅读路径。

以下内容不应放进这里：

  • 某个系统的深度设计
  • 长期运维手册
  • 具体接口字段和对象定义

旧版单页快速开始仍可保留在 docs/getting-started.md，但定位是启动入口补充页，而不是另一套平行分类。

Concept

放在 docs/concepts/，前提是它满足这两个条件：

  • 被多个系统复用
  • 不依赖某个单一系统的完整实现细节才有意义

Core Design

放在 docs/core/。它回答“当前实现实际上怎么工作”，比 docs/concepts/ 更靠近工程实现。

适合放在这里的内容：

  • 平台整体架构
  • runtime 深度设计
  • service 分层与内部协作
  • 当前态链路说明

不适合放在这里的内容：

  • 面向最终用户的操作说明
  • 单个系统自己的稳定首页
  • 纯字段查表

Database

放在 docs/database/。凡是以表、模型、关系、索引、迁移为中心的话题，优先进入这里，而不是分散到系统页或参考页。

System

放在 docs/systems/<system>/。每个系统至少应有：

  1. 概览
  2. 关键入口或关键文件
  3. 阅读意图
  4. 指向运维页与参考页的链接

如果一篇文档主要服务于一个明确系统，即使它包含架构、运行时或排障，也优先归到对应系统目录，不再放回 core/。

Guide

放在 docs/guides/。它回答“怎么做”，强调任务完成路径。

适合放在这里的内容：

  • 配置步骤
  • Studio 控制台操作
  • 外部接入流程
  • 具体功能使用说明

不适合放在这里的内容：

  • 系统内部运行机制总览
  • 备份恢复或生产治理流程
  • 历史演进说明

Operations

放在 docs/operations/。它回答“怎么运行、怎么配置、怎么治理、怎么排障”，不负责解释完整内部设计。

Reference

放在 docs/reference/。它回答“接口长什么样、对象有哪些字段、代码入口在哪”，偏索引型、查表型阅读。

API Reference

放在 docs/api/。它是比 docs/reference/ 更贴近源码对象和公开接口的一层参考区。

适合放在这里的内容：

  • HTTP / SSE / WebSocket 端点
  • 请求响应契约
  • 服务对象、解析器、模型配置
  • 与 mkdocstrings 对接的源码级说明

Topical Design

放在 docs/chameleon/、docs/freight/、docs/marketplace/、docs/roadmap/、docs/ai-agent/ 等专题目录。

当一篇文档满足以下任一条件时，优先视为专题方案：

  • 跨越多个系统
  • 带明显业务域背景
  • 属于产品线方案而不是平台通用结构
  • 表达未来规划、阶段设计或专项方向

Changelog

放在 docs/changelog/ 或 docs/timelines/。任何按时间演进组织的内容都不应继续作为主导航入口去承担当前设计说明。

Dev

放在 docs/dev/。它面向仓库维护者，包含协作流程、贡献规范、评测、测试和性能实践。

禁止事项 / Anti-Patterns

  • 不要再新增一套平行顶级分类去承载“同样类型”的页面。
  • 不要把“怎么用”和“怎么实现”写在同一篇总览里。
  • 不要把接口字段、对象签名、参数表大量复制进系统页或操作页。
  • 不要让原型页、时间线页、规划页承担当前实现说明的职责。
  • 不要因为重构导航就直接隐藏旧页面，除非其内容已经被新结构吸收或确认废弃。

页面模板 / Page Templates

系统页最小模板 / Minimum System Page Template

# 系统名称

一句话说明系统职责。

## 何时阅读本页

- ...

## 关键文件

| 路径 | 作用 |
| --- | --- |
| `ai_service/...` | ... |

## 核心流程

```mermaid
flowchart LR
  A --> B --> C
```

## 相关页面

- 运维页
- 参考页
- 概念页

运维页最小模板 / Minimum Operations Page Template

  1. 适用对象
  2. 典型任务
  3. 关键命令或入口
  4. 指向系统页的深链

参考页最小模板 / Minimum Reference Page Template

  1. 查表目的
  2. 对象或入口清单
  3. 指向系统页的上下文链接

何时必须更新文档 / When Documentation Is Required

出现以下任一情况时，默认必须同步文档：

  • 改变了用户、运维或开发者的操作流程
  • 改变了公开 API、请求响应模型、事件格式或数据模型
  • 改变了配置项、环境变量、默认值或优先级
  • 改变了系统职责、运行拓扑、存储边界或导航结构
  • 新增了应该进入主导航的新页面

API 与手写文档边界 / API vs Narrative

  • 手写页负责说明职责、边界、调用顺序和阅读顺序。
  • API 页负责说明对象签名、参数、返回值和字段。
  • 系统页不应手工复制大段签名表；应链接到 mkdocstrings 或参考页。

mkdocstrings 示例：

::: ai_service.services.rag.embedding.EmbeddingService
    handler: python

双语策略 / Bilingual Policy

站点仍以中文为主，但入口页允许同页双语标题或少量英文术语说明。

推荐使用双语的页面

  • docs/index.md
  • docs/getting-started/index.md
  • docs/concepts/index.md
  • docs/reference/index.md
  • docs/dev/documentation-standard.md

术语规则

  • 类名、函数名、环境变量、配置键保持英文原样
  • 术语首次出现时可使用“中文 + English”
  • 不为每个函数额外维护两套平行中英文正文
  • 面向读者的缩写术语统一保持大写，例如 MCP、RAG、API、OCR、LLM
  • 目录名、文件路径、URL、接口字段和配置键保持其真实大小写，例如 docs/api/、systems/rag/、rag-debug

评审清单 / Review Checklist

  • 页面是否放在正确 IA 层级
  • 新页面是否进入 mkdocs.yml 或被可靠链接
  • 系统页是否链接了相关运维页与参考页
  • 是否避免复制 API 签名、字段表和旧导航术语
  • 链接、图片、Mermaid 图是否可用
  • Markdown 是否为 UTF-8
  • 是否执行 uv run --group docs mkdocs build