By name: code-to-docs description: 基于代码生成或更新 Markdown 文档，忽略现有 .md 作为事实来源；按叶子目录自底向上汇总模块，输出模块分层、依赖方向、可复用清单与可独立重构的最小单元。适用于「从代码刷新文档/整理架构/模块拆分/代码驱动文档」的请求。
Code To Docs 技能
概述
用于在仅参考代码的前提下，分目录生成或更新文档，并给出复用与重构边界总结。
核心原则：代码是唯一事实来源，现有文档仅用于定位与格式对齐。
工作流程
┌─────────────────────────────────────────────────────────────┐
│ Code To Docs 工作流 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 应用忽略规则 │
│ ↓ │
│ 2. 建立代码清单 → 定位叶子目录 │
│ ↓ │
│ 3. 叶子目录文档（自底向上） │
│ ↓ │
│ 4. 上层目录汇总 │
│ ↓ │
│ 5. 顶层总结（结构/分层/依赖/复用/重构） │
│ ↓ │
│ 6. 输出校验 │
│ │
└─────────────────────────────────────────────────────────────┘
步骤详解
| 步骤 | 动作 | 说明 |
|---|---|---|
| 1 | 应用忽略规则 | 直接应用默认忽略，用户明确要求时再调整 |
| 2 | 建立代码清单 | rg --files 获取文件，定位叶子目录 |
| 3 | 叶子目录文档 | 逐个读取，使用「叶子目录模板」 |
| 4 | 上层目录汇总 | 融合子目录结果，使用「上层目录模板」 |
| 5 | 顶层总结 | 全局结构、分层、依赖、复用、重构 |
| 6 | 输出校验 | 仅返回路径与说明，不输出全文 |
叶子目录定义：包含代码文件，且没有子目录包含代码文件。
默认忽略规则
忽略目录
.git/ node_modules/ dist/ build/ out/ coverage/
vendor/ .cache/ tmp/ logs/ .idea/ .vscode/
.next/ .nuxt/ target/ bin/ obj/
忽略文件
*.md # 仅用于定位与格式对齐，不作为事实来源
*.min.js # 压缩文件（若为唯一源码再纳入）
*.map # Source Map
文档落盘规则
| 情况 | 处理方式 |
|---|---|
目录已有 .md |
选择最贴近目录用途的文档更新 |
| 没有现有文档 | 默认创建 README.md |
| 顶层文档 | 默认使用 README.md |
| 旧文档与代码冲突 | 以代码为准改写 |
文档模板
叶子目录模板
# <目录名>（<相对路径>）
## 职责与边界
- <该目录负责的功能范围>
- <明确不负责的内容或依赖假设>
## 关键入口与导出
- 入口文件：<文件名/作用>
- 关键导出：<函数/类/模块>（简述作用）
## 主要流程/数据流
- <流程/调用链的关键步骤>
- <输入/输出与状态变化>
## 关键配置/常量
- <配置项/常量>：<用途与影响范围>
## 依赖关系
- 上游依赖：<依赖的模块/服务/第三方>
- 下游依赖：<被哪些模块调用>
## 复用与重构提示
- 可复用点：<可抽象的能力>
- 最小重构单元：<建议抽离的子模块与理由>
上层目录模板
# <目录名>（<相对路径>）
## 目录职责
- <本层级提供的能力/聚合关系>
## 子模块清单
- <子目录1>：<一句话职责>
- <子目录2>：<一句话职责>
## 上层入口与组合关系
- 入口文件：<文件名/作用>
- 组合方式：<如何组织/调度子模块>
## 跨模块交互/依赖方向
- <关键依赖方向与边界>
## 关键配置
- <配置项/常量>：<用途>
## 风险或重构候选
- <耦合点/重复逻辑/技术债>
顶层总结模板
# 项目总览
## 结构图
- <树状结构或分层列表>
## 模块分层与依赖方向
- <层级说明与依赖方向>
## 可复用模块清单
- <模块>：<复用理由/适用范围>
## 最小重构单元划分
- <单元>：<范围、边界、理由>
## 关键技术约束
- <运行时/平台/框架/构建链路限制>
## 后续建议
- <重构优先级/演进建议>
复用与重构判断准则
模块边界判断
| 原则 | 说明 |
|---|---|
| 运行时边界 | 前端/后端、content/background/popup 等 |
| 业务域边界 | 同一业务流程/领域逻辑尽量聚合 |
| 依赖方向 | 稳定依赖不应反向引用不稳定模块 |
| 层级边界 | UI 层不直接访问底层，需经服务/适配层 |
可复用模块特征
✅ 清晰输入/输出，接口稳定，副作用可控
✅ 外部依赖少，配置驱动，适配多场景
✅ 与具体业务/页面解耦，命名语义抽象
✅ 可通过测试或示例说明其行为
最小重构单元划分
✅ 满足「共同变更」原则：这些文件通常一起修改
✅ 对外接口清晰：可通过单一入口调用或替换
✅ 内部高内聚、外部低耦合：减少跨目录双向依赖
✅ 无隐式共享状态：避免全局变量或隐式副作用
快速判定清单
可复用判定
- 是否存在稳定 API/导出？
- 是否可以脱离当前目录单独使用？
- 是否能被多个上层模块调用？
可独立重构判定
- 是否能在不修改上层调用的前提下替换实现？
- 是否能明确划定文件范围与依赖边界？
- 是否不存在跨目录循环依赖？
使用示例
触发场景
用户请求 触发技能
──────────────────────────────────────────
"帮我整理这个项目的文档" → code-to-docs
"从代码刷新 README" → code-to-docs
"分析一下代码结构" → code-to-docs
"哪些模块可以复用" → code-to-docs
"帮我做模块拆分建议" → code-to-docs
执行命令
# 获取代码文件清单
rg --files --glob '!node_modules' --glob '!dist' --glob '!*.md'
# 查找叶子目录
find . -type d -exec sh -c 'ls "$1"/*.{js,ts,py} 2>/dev/null | head -1' _ {} \;
注意事项
- 大型仓库：先分层处理，叶子目录优先，避免一次性加载过多文件
- 测试/脚本目录：如需纳入，需显式放开忽略规则
- 不确定项：记录为「假设/备注」随结果说明，不阻塞执行
- 文档冲突：始终以代码为准，旧文档仅参考格式
输出规范
- 仅返回新增/更新的
.md路径与简要说明 - 不输出文档全文（除非用户明确要求）
- 标记假设与备注