apple-ouyang Docs System
维护 docs/ 入口系统，而不是把 markdown 当散文件处理。
长期文档仓固定入口是 ~/kernel-docs；如果实际仓库不在这个目录，安装脚本会维护同名软链接。
长期文档默认只写入 ~/kernel-docs/docs/<version>/<domain>/topic.md，不要把长期文档写回当前代码仓的 docs/。
When To Use
- 先看当前仓有哪些长期文档入口
- 根据
summary和read_when决定先读哪篇 - 校验
docs/元数据质量 - 为旧文档补空 YAML 头，或为已有 YAML 头补缺字段
- 判断文档该落到哪个
version/domain
Execution Modes
Daily Sync- 每次进入本 Skill 都先检查当前
repo_root + branch今天是否已经成功执行过git pull --rebase - 同一个
repo_root + branch在同一个自然日最多成功 pull 一次 - 状态记录在
~/.claude/kernel-docs-pull-state.json - 如果今天尚未成功 pull，且工作区干净，则先执行
git pull --rebase - 如果工作区不干净，先停止并明确说明无法安全 rebase，不要跳过后继续
- 每次进入本 Skill 都先检查当前
Discover- 先跑
docs-list - 需要时用
--version、--domain、--json缩小范围 - 如果没有命中文档，或命中的文档明显不覆盖当前问题，则调用
kernel-code-to-docsskill
- 先跑
Lint- 运行
docs-lint - 同时检查路径、缺字段、占位
summary、空泛read_when
- 运行
Init Front Matter- 运行
docs-init-frontmatter --write - 没有 YAML 头时补空外壳；已有 YAML 头时只补缺字段，不重写正文
- 运行
Route- 先判断版本，再判断领域，再决定是否需要抽查同主题旧文档
默认先走 Discover。
Core Rules
- 每次进入本 Skill，先做一次每日
git pull --rebase检查，再继续后续动作 - 每日 pull 的频率按“自然日 +
repo_root + branch”控制，不按 24 小时滑窗控制 - 只有成功 pull 才更新
~/.claude/kernel-docs-pull-state.json - pull 失败时不要记成功，也不要伪装成已同步
- 文档入口发现必须先走
docs-list - 不要用
rg、grep、find直接扫描docs/决定先读哪篇 archive默认隐藏；只有显式--all才展示archive是生命周期，不是版本维度；归档路径固定为docs/archive/<domain>/- 文档路径固定为
~/kernel-docs/docs/<version>/<domain>/topic.md - 不使用
plan/research深目录 process已并入archdocs-init-frontmatter只补空的 YAML 外壳，或补缺失字段；不自动生成字段内容summary必须回答“这篇文档帮助做什么判断/操作”summary不能写成TODO、待补充、占位read_when必须写成任务触发语句read_when不能只写“修改前”“需要时”“排查时”Discover/Route场景下，如果文档入口不足以覆盖当前问题，默认继续读代码并转交kernel-code-to-docs，不要停在“没有文档”- 这个转交是单向的；一旦已经进入
kernel-code-to-docs，不要再回跳到本 Skill 做二次分发
Version And Domain Rules
固定版本目录：
v2v3lite
固定领域目录：
archmemoryfilesystemdfxdebugsecuritydrivers
归类规则：
- 架构、启动、调度、IPC、跨子系统机制：
arch - 内存管理、页表、分配器、缺页异常：
memory - VFS、具体文件系统实现、缓存一致性：
filesystem - 日志、trace、观测、诊断链路：
dfx - GDB、crash 分析、现场定位、调试手册：
debug - 权限、隔离、认证、加固：
security - 设备模型、总线、驱动框架、外设适配：
drivers
版本判断：
- 仓名以
hm-开头：v3 - 绝对路径包含
RTOS_V3_master：v3 - 绝对路径包含
RTOS_V2_master：v2 - 路径或仓名包含
kernel-5.x：v2 lite只有用户明确说明时才按lite处理
阅读已有文档时遵循非对称规则：
- 当前路径命中
v2：只看docs/v2/ - 当前路径命中
v3：默认看docs/v3/；只有用户明确要求参考v2/Linux时，才额外看docs/v2/ - 当前上下文是
lite：先看docs/lite/；不够时再补看docs/v2/；不看docs/v3/ - 当前路径无法判断版本：根据用户提到的
V2/Linux/V3/鸿蒙/lite选择版本文档 - 需要追历史实现或废弃方案时，再额外看
docs/archive/
Front Matter
推荐最小模板：
---
summary: 一句话说明这篇文档帮助完成什么判断或操作
read_when:
- 遇到什么任务、决策或排障场景时先读
---
约束：
summary优先写“作用 + 决策对象”，不要只重复标题read_when表示“AI 在什么场景下应该优先读这篇文档”read_when要写成任务触发语句，不要写成状态词、作者备注或空泛占位
source 如果需要写，语义是“这篇文档主要基于什么材料写成”，不是必填路径：
- 参考文档时，只记录文档名
- 参考代码时，写
git仓库名:仓内相对路径 - 不要求穷举所有参考文件；精确证据路径和行号放正文
Stop Conditions
下面这些情况不要继续留在这里：
- 用户真正要的是归档、知识上浮、修复错误归档
- 任务核心已经变成代码调研沉淀，而不是 docs 入口维护
- 落点还没判断清楚，就准备直接新建文件
这时改走 archive / knowledge-lift 流程或 kernel-code-to-docs。
如果命中下面情况，也先停下并说明原因：
- 今天还没成功 pull，但当前工作区不干净，无法安全执行
git pull --rebase
Commands
git pull --rebase~/.claude/bin/docs-list [--all] [--version <v2|v3|lite>] [--domain <domain>] [--json]~/.claude/bin/docs-lint [--files <path...>]~/.claude/bin/docs-init-frontmatter [--files <path...>] --write- 不传仓路径时，这些命令默认操作
~/kernel-docs
Output Contract
默认输出必须至少回答下面一项：
- 这次应该先读哪些文档，以及为什么
- 哪些文件元数据不合规
- 哪些旧文档已补空 YAML 头，或哪些文档已补缺字段
- 某篇文档更适合哪个
version/domain - 如果没有相关文档，为什么要转交
kernel-code-to-docs
Done Criteria
- 入口发现：只看输出就能决定下一篇该读什么
- 元数据校验：问题文件、问题类型、下一步动作都明确
- 空 YAML 头初始化：正文原样保留，只补空外壳或缺字段
- 路由：版本和领域判断都有依据
- 缺文档时：不会停在入口层，而是明确转到
kernel-code-to-docs