文档规范

1. 文档结构

docs/
├── index.md                 # 文档站首页（VitePress）
├── design/                  # 设计文档
│   ├── modules/             # 模块设计（已实现/正在实现，单 monorepo 包）
│   │   ├── index.md         # 模块索引
│   │   ├── data-model.md    # 标准化告警/配置/报告模型
│   │   └── ...              # dependabot-fetcher / dependency-fixer / pnpm-lockfile-fixer 等
│   └── governance/          # 专项设计与治理（跨模块 / 治理 / 重大变更）
│       ├── index.md         # 治理索引
│       ├── architecture.md  # 系统架构与模块边界
│       ├── security.md      # 安全设计
│       └── ...              # github-action-workflow / mcp-server(M6) 等
├── guide/                   # 使用指南
│   ├── quick-start.md       # 快速开始
│   ├── configuration.md     # 配置说明
│   ├── tech-stack.md        # 技术栈详解
│   └── ai-development.md    # AI 协同开发指南
├── plan/                    # 规划与任务
│   ├── roadmap.md           # 路线图（阶段概览）
│   ├── todo.md              # 当前阶段任务
│   ├── todo-archive.md      # 已完成阶段归档
│   └── backlog.md           # 待办积压（后续阶段详细任务）
├── research/                # 调研文档（命名规范见 §5.0 / §5.1）
│   ├── README.md            # 目录定位（简要，规范见本文档）
│   ├── 2026-07-26-competitive-research.md
│   └── ...
├── standards/               # 项目规范（本目录）
└── .vitepress/              # VitePress 站点配置（导航/侧边栏）

2. Markdown 约定

单个 H1 标题: 每个文件一个 # 标题，层级不跳级（# → ## → ###）
中文语境: 统一使用全角括号 （），禁止半角括号混用
代码块: 标注语言 ```typescript、```bash、```yaml
图表: 优先使用 Mermaid，不嵌入难维护的图片描述
VitePress 容器: 关键信息使用 ::: info / ::: warning / ::: danger
链接: 使用相对路径，确保路径真实可用。本地文件链接默认不带锚点（path.md）：锚点 slug 规则跨平台不一致（GitHub 移除全角标点 （）、、 等，VS Code / VitePress 保留），带锚点链接在部分平台会失效；必须带锚点时，目标标题避免全角标点，且锚点需能被 check:docs 脚本验证通过
链接检查: pnpm run check:docs（scripts/check-docs.mjs，零依赖）验证全部 md 文件的本地路径存在性与锚点匹配——按宽松规范化（小写 + 移除标点/符号/空白）兼容 GitHub / VS Code / VitePress 三种 slug 规则差异，只抓真实断链与假锚点；同时拒绝本地绝对路径（POSIX 斜杠开头、Windows 盘符形式、UNC 网络共享前缀）与路径穿越（../.. 解析超出仓库根）——md 本地链接必须使用项目内相对路径。已接入 CI（test.yml）。归档/重命名标题时：内容移入归档文件（标题带"已归档"等后缀）或标题改写后，必须全局检索指向该标题的锚点链接（rg -n '\[[^]]*\]\([^)]*#.*' 链接文本），同步改指新位置/新锚点——check:docs 是最后防线，会在 CI 滞后暴露（2026-08-07 roadmap → todo-archive 锚点失效案例，见经验归档 §二十二）
正文路径禁令: 文档正文与行内代码中禁止出现个人机器绝对路径（Windows 盘符形式、UNC 网络共享路径等），引用项目内位置时使用相对路径或 <repo-root>/ 占位符；fenced code block 内的示例代码不受限（教学示例可保留）。check:docs 会拒绝正文中的 Windows 盘符 / UNC 路径（2026-08-09 全局 temp 路径泄漏案例，见经验归档 §二十三）
Markdown 格式检查: pnpm run lint:md（@lint-md/cli，--fix 自动格式化：中英文/数字间距、标题规范、列表缩进等）与 pnpm run lint:md:check（无 --fix，CI 门禁用，已接入 test.yml / release.yml）。规则裁剪见根目录 .lintmdrc（关闭半角标点等与中文技术文档冲突的规则，参照 momei 项目做法）。提交前运行 pnpm run lint:md 保持文档格式化一致；lint-staged 已挂载 *.md 自动执行
裸 HTML 标签禁令（必须）: 正文与表格中引用 <tag> / <file> / <hash> 等占位符、命令或路径时，必须用反引号包裹（`<hash>`）——markdown 中裸 <tag> 会被 markdown-it 按 raw HTML 原样透传，VitePress 的 vue 模板编译把任何非自闭合标签视为需要闭合 → docs:build 报 Element is missing end tag；报错行号是转换产物行号，不能按源文件行号找（2026-08-10 release.md <path> 案例 → 2026-08-13 experience-archive <hash> 复现，见经验归档 §三十三/§三十九）。同理加粗 **...** 内的裸 *（如 *.test.ts）会破坏强调解析，须反引号包裹。lint:md 与 check:docs 均不检查 HTML 标签配对，docs:build（pnpm --filter dependfix-docs build）是唯一防线——新增/修改 docs/ 站点内 md 时必须本地执行；裸标签排查：rg '<[a-z][a-z0-9-]*>' 后人工过滤反引号内命中

3. 文档行数阈值

文档	健康窗口	warning 触发	强制分片
README	<= 300 行	301-400	> 400 行
`roadmap.md`	<= 800 行	801-900	> 900 行
`todo.md`	<= 500 行	501-600	> 600 行
`backlog.md`	<= 500 行	501-700	> 700 行
`todo-archive.md`	<= 500 行	501-700	> 700 行

超阈值时优先拆分到 archive/ 分片，主文档保留近线窗口与索引入口。

4. 事实源层次

层级	文件	职责
L0	`AGENTS.md`	项目级 AI 行为准则、安全红线、角色矩阵
L1	`docs/standards/*.md`	专项规范（开发、测试、文档等）
L2	`docs/design/modules/.md` + `docs/design/governance/.md`	模块设计 / 专项设计与治理
L3	平台适配文件	工具差异、目录发现

冲突顺序：L0 > L1 > L2 > L3。

规范单点声明原则：每条规则只在其职责归属的权威文档中完整声明一次（如任务粒度约束 → 规划规范 §1.1），其他文档 / skill / agent 定义只做一行链接引用（见 [X 规范 §Y](./xxx.md)），禁止在多处重复抄写完整条款、阈值或教训。执行分工：宽松指引（应当、建议）可在执行阶段（skill/agent）声明；严格约束（必须、阈值、禁令）优先挂在 review 阶段检查点（code-reviewer 检查项、Code Auditor 必查项）——review 阶段上下文干净（只看 diff + 验证证据），比开发阶段更容易强制执行（详见经验归档 §二十四）。

5. 设计文档分层

5.0 modules/ vs governance/ 分流依据

分流依据	`modules/`	`governance/`
文档对象	单个 monorepo workspace 包（`packages/core`、`packages/engine`、`packages/cli`、`packages/mcp`、`packages/skills`、`apps/platform`）	跨模块 / 跨包 / 平台级 / 治理级 / 重大变更
文档数量	1 包 = 1 个模块文档	1 主题 = 1 个治理文档（不按包拆分）
职责	当前已实现或正在实现的稳定模块总设计	专项设计 / 评估报告 / 治理边界 / 迁移方案 / 经验归档
状态字段	`✅ 已落地` + 修订时间戳	`✅ 已落地` / `🔶 设计中` / `🔶 设计先行稿（backlog 候选）` / `✅ 持续追加`
重命名触发	跟随 monorepo 包重命名（如 `packages/` → `modules/`）	不跟随包重命名，治理文档独立存续

模块设计：稳定模块总设计写入 docs/design/modules/（当前实现/正在实现的模块，与 monorepo 包对应）

治理/专题：专项治理、迁移方案、评估报告写入 docs/design/governance/（跨模块 / 治理 / 重大变更）

索引：docs/design/modules/index.md 与 docs/design/governance/index.md 分别维护索引；过时且暂不删除的文档归档到 docs/design/governance/archive/（按需创建）

5.1 设计文档硬阈值（hard requirement）

本条是设计文档强制要求的唯一权威声明。其他文档 / skill / agent 定义仅作一行引用。

适用范围（仅以下 4 类改动触发本硬阈值）：

改动类型	示例
专项设计	重大功能预研 / 架构调整 / 跨包契约重写
专项治理	治理决策落地 / 经验沉淀 / 文档治理批次
重大变更设计	breaking change / 数据迁移 / 协议变更
新增模块	新 monorepo 包 / 新平台子系统 / 新核心抽象层

不适用范围（普通功能改动不触发本硬阈值）：bug fix / 小优化 / 体验调整 / 文档措辞 / 测试补强 / 配置调整 / 依赖升级 / 现有模块功能扩展。

硬阈值规则（仅适用范围内的改动需满足）：

改动预计 > 10 文件 / > 800 行 → 必须有专项设计文档（docs/design/governance/<slug>.md）+ A 阶段 code-auditor deep depth 审计
跨 ≥ 2 个独立模块的代码改动 → 必须有专项设计文档（不论规模）

完整规则、触发判定、A 阶段必查项见规范与文档治理设计 §2.4。

5.2 通用带日期文件命名规范

需要带日期的文件（调研、评估、归档、快照、报告等）统一使用 {YYYY-MM-DD}-{topic-slug}.md：

日期为完成日期（YYYY-MM-DD），置于文件名最前——按文件名排序即按时间排序
topic-slug 为小写 kebab-case 主题词
同一天多次产出追加版本后缀 -v{n}（从 2 起）
适用于所有文档目录（docs/research/、docs/design/governance/、docs/plan/archive/ 等），不限于调研文档
例外（持续追加型文档不设日期）：跨阶段持续追加、不随单一产出结束的文档使用固定名，不套日期规则——如经验归档（experience-archive.md，章节按序追加，见其文件头"准入标准"）；再如 todo-archive.md、backlog.md 等规划滚动文档。判断标准：文档的"完成日期"不存在（永远在追加）→ 不设日期。

示例：

2026-08-02-release-tools-comparison.md（调研）
experience-archive.md（经验归档）
2026-08-06-audit-report-v2.md（同天第二版审计报告）

5.3 调研文档规范（docs/research/）

调研 / 研究类文档（竞品分析、技术调研、决策依据等）统一存放 docs/research/，与 docs/design/（设计落地）和 docs/plan/（规划）分离。

命名规范（沿用 §5.2 通用带日期文件命名规范）:

文件名必须包含日期，格式 {YYYY-MM-DD}-{topic-slug}.md
- 示例：2026-08-02-release-tools-comparison.md
- 日期为调研完成日期；topic-slug 为小写 kebab-case 主题词
同一天对同一主题多次调研（追加搜索、数据更新、结论修正）时，追加版本后缀：
- 2026-08-02-release-tools-audit-v2.md（保留旧版本作为历史决策依据，新版本 -v{n} 从 2 起）
旧版被新版完全覆盖且无决策参考价值时，可删除旧版

内容结构（建议）:

markdown

# {调研主题}

> 调研日期: {YYYY-MM-DD}
> 方法: {来源扫描 / 官方文档 / 交叉验证 / 本地实验}
> 结论: {一句话核心结论}

## 摘要
## 关键事实（含出处/链接）
## 交叉验证
## 结论与建议

内容处置流程: 调研完成后按优先级处置，并在文档末尾注明去向——

落地: 结论进入设计文档（design/modules/ 或 design/governance/）与规划（plan/）
保留: 作为未来决策依据（如发布工具对比支撑发布方案）
归档 / 删除: 被覆盖或价值已尽

目录治理: 调研文档与实现脱节时，判断"结论是否仍有效"：有效 → 保留；无效 → 删除或更新日期版本。阶段收尾时清理无引用、无价值的旧调研。

6. 文档同步原则

代码变更时同步更新相关设计文档
路径、链接、命令必须真实可用
设计文档先于大规模实现落盘
README 简洁入口，细节回收到 docs/ 专题页

7. `plan/` 文档范围严格区分

docs/plan/ 下 4 个文档不重叠——任何条目只能出现在唯一一个文档，禁止重复登记。

文档	范围	禁止内容
`todo.md`	当前阶段未完成待办	已闭环摘要 / commit 序列 / 验证矩阵 / ahead 数 / known-issue / 延期项 / 远期登记
`todo-archive.md`	已闭环阶段归档（主窗口保留 3-5 段）	当前阶段待办 / 未排期增强候选
`backlog.md`	未排期 / 延期 / 远期 + known-issue	已闭环阶段归档 / 当前阶段待办
`roadmap.md`	里程碑概览	单任务级管理 / commit / 待办

条目分流判定：

当前阶段需要推进 → todo.md
已完成但本批归档 → todo-archive.md
延期 / 用户指示暂缓 → backlog.md（延期/暂缓段）
远期登记 / 触发条件未达 → backlog.md（远期登记段）
known-issue / 已知边界 → backlog.md（已知边界段）或对应阶段归档段

反模式（违规）：

❌ todo.md 顶部 banner 写"M11 闭环 N commits + 验证矩阵 + commit 序列"——已闭环内容归 todo-archive.md
❌ backlog.md 重复登记已闭环项——避免双点维护漂移
❌ todo.md "未完成项目"段罗列远期项——远期归 backlog.md
❌ known-issue 写在 todo.md——todo.md 只含待办，known-issue 归 backlog.md 或归档段
❌ 把 ahead 数 / commit 序列 / 验证矩阵当"进度信息"塞 todo.md——这些是归档元数据，不是待办

执行检查：每次编辑 docs/plan/ 任一文档前，用 §7 表自检条目归属；编辑后用 rg 扫描违规关键词（"ahead / commit.*[0-9a-f]{7} / 验证矩阵 / 已闭环 / M\d 闭环 / done / completed / closed"），命中即重新分类。

判定理由：规范定义本身已完整说明边界，无需追溯历史档案。

8. 相关文档

本文档在 1.0.0 前参考 momei 项目的成熟做法完成继承与适配；1.0.0 后按项目自身实践持续演进，形成自有规范。

文档规范 ​

1. 文档结构 ​

2. Markdown 约定 ​

3. 文档行数阈值 ​

4. 事实源层次 ​

5. 设计文档分层 ​

5.0 modules/ vs governance/ 分流依据 ​

5.1 设计文档硬阈值（hard requirement） ​

5.2 通用带日期文件命名规范 ​

5.3 调研文档规范（docs/research/） ​

6. 文档同步原则 ​

7. plan/ 文档范围严格区分 ​

8. 相关文档 ​