文档目录规范¶
触发场景：新建 / 移动任何 .md 文件时必查。 起因：历史上根目录散落开发日志、更新规则和设计说明，破坏文档分层并增加 MkDocs 引用成本。整改后，根目录只保留平台或工具约定的标准入口文件。 目标：让"放哪儿"成为零思考。
SOP 决策树¶
要建/移一个 .md 文件
↓
是 README / CHANGELOG / LICENSE / CONTRIBUTING ?
├─ 是 ──> repo 根（GitHub 自动识别）
└─ 否 ──> 继续 ↓
是给 AI / 工具的入口（CLAUDE.md / .copilot/...）?
├─ 是 ──> repo 根（工具约定）
└─ 否 ──> 继续 ↓
按内容类型分到 docs/：
↓
用户操作说明（入口 / 步骤 / 状态 / 错误 / 限制）? ──> docs/product/
↓
版本相关日志（开发日志 / 每版本细节）? ──> docs/changelog/
↓
工程契约（PRD / API / 数据模型）? ──> docs/specs/{active,done,parked}/
↓
知识沉淀（架构 / 字段语义 / 组件用法）? ──> docs/wiki/
↓
bug 归档（病灶 / 修法 / 元教训）? ──> docs/issues/
↓
操作手册（遇到 X 怎么做）? ──> docs/rules/
↓
原始素材（用户原话 / 半成品想法）? ──> docs/raw/{inbox,feedback,conversations,ideas}/
repo 根的合法 .md（白名单 — 只允许这些）¶
| 文件 | 用途 | 谁看 |
|---|---|---|
README.md |
项目首页 | GitHub 主页访客 |
CHANGELOG.md |
按版本聚合（机器生成） | 用户 / GitHub releases / MkDocs |
CLAUDE.md |
给 AI 的工作入口 | Claude Code 工具 |
LICENSE |
开源许可（若有） | 法务 / GitHub |
CONTRIBUTING.md |
贡献指南（若有） | 外部贡献者 |
绝对不能在根：开发日志 / 更新规则 / 设计说明 / bug 笔记 / 临时想法 — 这些全部属于 docs/。
docs/ 一级（每个目录的角色）¶
| 目录 | 内容 | 文件命名 | 示例 |
|---|---|---|---|
docs/index.md |
MkDocs 站点首页 | 固定 | index.md |
docs/product/ |
用户可照着操作的产品使用文档 | <feature>.md，当前只允许平铺 |
docs/product/google-maps-collection.md |
docs/changelog/ |
项目内部日志（每版细节） | development-log.md + development-log-archive-*.md |
docs/changelog/development-log.md |
docs/specs/ |
工程契约 | SPEC-XXX-<英文短标题>.md |
docs/specs/active/SPEC-007-...md |
docs/wiki/ |
知识沉淀 | <英文短标题>.md（kebab-case） |
docs/wiki/shared-queue-architecture.md |
docs/issues/ |
bug 归档 | XXXX-<英文短标题>.md（4 位 ID） |
docs/issues/0070-shared-window-orphan...md |
docs/rules/ |
操作手册 | <场景>.md 或 NN-<场景>.md |
docs/rules/00-meta-rule.md |
docs/raw/ |
原始素材 | YYYY-MM-DD-<描述>.md（按日期） |
docs/raw/feedback/2026-05-28-xxx.md |
docs/_topics/ |
自动主题 hub（rebuild 生成） | 各 tag.md | docs/_topics/scheduling.md |
docs/_todo.md |
自动待办聚合 | 固定 | (rebuild 生成) |
docs/_overview.md |
自动概览 | 固定 | (rebuild 生成) |
product/ 当前结构限制¶
docs/product/当前只允许INDEX.md与平铺的*.md产品页，不建立二级目录。- 原因：现有
rebuild-docs.py为 product INDEX 生成 basename 链接；嵌套目录会生成错误链接或文件名冲突。 - 需要二级目录时，先升级相对路径生成、重复 basename 检查和
docs:check覆盖，再调整本规则；不能先建目录后补工具。 - 产品页只写已实现、可验证的用户行为；未来方案仍放
docs/specs/。
specs/ 子目录¶
| 子目录 | 状态 |
|---|---|
docs/specs/active/ |
进行中（status: approved / in-progress） |
docs/specs/done/ |
已落地（status: done） |
docs/specs/parked/ |
暂缓（status: parked + parked_reason） |
命名约定（文件名）¶
必遵守（v0.10.110 起统一英文文件名）¶
- ❌ 不用中文（v0.10.110 起 129 文件追溯英文化）
- ❌ 不用
+ / （ / ）（MkDocs URL 编码后丑陋，v0.10.105 清理过 19 个） - ❌ 不用空格 / 大写（kebab-case）
- ✅ 文件名：英文 + 数字 +
-+_（kebab-case，URL 安全） - ✅ 文章标题（frontmatter
title:）：中文 OK（实际显示用） - ✅ ISSUE 用 4 位数字 ID 开头：
0070-shared-window-orphan.md - ✅ SPEC 用 SPEC- 前缀：
SPEC-007-feature-name.md - ✅ raw/ 用日期前缀：
2026-05-28-feature-name.md
推荐¶
- 文件名用"主题 + 子主题"短句：
SPEC-006-task-delete-data-cascade-confirm.md - 不超过 60 字符（含 .md）
- 用
-分词（最终 URL 安全） - 中文标题放 frontmatter
title:字段（rebuild-docs.py 用此渲染 INDEX）
frontmatter（每个 md 必含）¶
---
title: <中文短标题>
description: <30 字内描述，便于检索>
tags: [类型, 主题1, 主题2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: product | raw | spec | wiki | issue | rule | index
status: <类型特定>
related:
- "[[wikilink-1]]"
---
docs:check 会校验必填字段 — 缺会阻止 commit。
移动 / 重命名时的同步¶
重要：移动 .md 后必须全局更新所有引用：
# 1. git mv 移文件
git mv 老路径.md 新路径.md
# 2. 全局更新引用（脚本 + 手工）
grep -rln "老路径\|老文件名" docs/ scripts/ *.md mkdocs.yml
# → 每个引用文件改成新路径
# 3. 必跑：校验 frontmatter、INDEX 收录和 wikilink
pnpm docs:check
# 4. 先只读检查自动生成结果是否漂移（在系统临时目录重建并比较）
pnpm docs:rebuild:check
# 5. 仅在确认不会覆盖他人未提交生成结果时，才在当前工作区重建
pnpm docs:rebuild
pnpm docs:changelog
# 脏工作树或共享工作区禁止直接用写入型重建命令覆盖未知改动。
反例（v0.10.108 之前的现状）¶
| 文件 | 在哪 | 问题 |
|---|---|---|
~~development-log.md~~ |
根 | 应在 docs/changelog/，由 MkDocs 直接读取 |
~~开发日志-archive-*.md~~ |
根 | 同上，由 MkDocs 直接读取 |
~~更新规则.md~~ |
根 | 是 rule 类型，应在 docs/rules/version-release-iron-rules.md |
~~v2-UI改版说明.md~~ |
根 | 是 SPEC，应在 docs/specs/done/SPEC-000-v2-ui-redesign.md |
历史整改已将业务文档移入 docs/；根目录只保留 README、CHANGELOG、AI / 工具入口及可选的 LICENSE / CONTRIBUTING。
工具支持¶
| 命令 | 作用 |
|---|---|
pnpm verify |
先检查现有依赖，再串行执行类型、文档、治理测试和静态扫描；不自动 install、不运行 postinstall、不 build、不生成 changelog、不写当前工作区 |
pnpm docs:check |
检查 frontmatter、INDEX 收录和 wikilink；不检查普通 Markdown 链接，不重建文件 |
--diff 扫描基线 |
六个 baseline 文件缺失、不可读、JSON 损坏或 schema 非法时退出 2；合法 hits: [] 继续按空基线执行，不自动重建 |
scan:issue-coverage --strict |
执行 audit_grep 契约：expect: absent（默认，命中即违规）、expect: present（至少命中一次）、paths（限定扫描范围）、allow_paths（仅 present，允许路径外命中也违规）；扫描 scope 内全部 UTF-8 普通文本文件（含 .sh、CSS/HTML 与无扩展 hook），明确跳过含 NUL 或非法 UTF-8 的二进制；pattern / description / paths / allow_paths 必须加引号，expect 只允许加引号或精确、区分大小写的 plain absent / present；顶层只接受无缩进 plain audit_grep: 或 audit_grep: []，quoted key、冒号前空格、根级缩进、重复 key 均拒绝；tag、inline comment、block scalar、无法识别的对象行、重复字段等未支持 YAML 形态 fail closed；空字段、symlink、未知字段、非法路径/正则、不可枚举后代目录或 grep 异常退出 2；默认 scope 的全部后代普通文本均扫描，不按 docs / dist 等后代目录名额外排除；grep 仅做文件预选排序且绝不缩小最终集合，原始 Python 正则会精确扫描全部已枚举文本，因此兼容 \\A / \\Z、[\\s\\S]、JS [^]、lazy quantifier、大于 255 的上限和负向前瞻 |
pnpm docs:rebuild:check |
在系统临时目录运行真实重建器并逐文件比较；不写当前工作区 |
pnpm docs:rebuild |
重建 INDEX / _overview / _todo / _topics；会写文件，脏工作树慎用 |
pnpm docs:changelog |
重生成 CHANGELOG.md；会写文件 |
Docs-Impact |
产品影响提交的文档同步声明，见 Docs-Impact 规则 |
相关¶
- Docs-Impact 规则 — 功能改动与产品/研发文档同批同步
- [[00-meta-rule|00-元规则]] — 用户讲新工具/反馈时自动建档
- 每版本沉淀检查表 — 何时必建 ISSUE/wiki/SPEC
- 用户反馈前置查询 — 用户报问题时先查 INDEX
- 版本发布流程 — bump → build → commit 全流程
- CF-Pages-部署 — MkDocs site 部署到 CF Pages