| name | docgen-cmd |
| version | 1.1.0 |
| description | 当用户提到'生成导航'、'更新导航'、'更新看板'、'刷新看板'、'生成文档索引'、'docgen'、'更新README'、'应用清单'、'文档生成'时，必须使用此技能。提供文档导航表与执行看板自动生成能力：扫描文档目录生成导航表、扫描.trae/specs/生成进度看板、生成apps/应用清单索引。不要手动编辑导航表或看板区域——它们由标记包裹，本Skill会自动更新标记区域内的内容，手动编辑会被下次生成覆盖。 |
| argument-hint | <nav|dashboard|apps|all> [--path <dir>] |
| user-invocable | true |
| paths | [".agents/scripts/docgen.py","README.md","docs/README.md","apps/README.md"] |
| title | DocGen 文档导航与看板生成 Skill |
| x-toml-ref | ../../../.meta/toml/.agents/skills/docgen-cmd/SKILL.toml |
DocGen 文档导航与看板生成 Skill
⚠️ 本Skill是脚本命令门面（L1索引层），遵循渐进式披露三层架构：
1. Skill ID
docgen-cmd
2. 功能描述
文档索引与看板自动生成工具，提供四个子命令，覆盖三类文档生成场景：
| 子命令 | 功能 | 更新目标 |
|---|
| nav | ⭐ 扫描文档目录生成导航表 | README.md、docs/README.md 中 <!-- nav-start -->/<!-- nav-end --> 标记区域 |
| dashboard | ⭐ 扫描 .trae/specs/ 生成进度看板 | 根 README.md 中看板区域 |
| apps | 生成 apps/ 应用清单索引 | apps/README.md 中应用清单区域 |
| all | 依次执行 nav → dashboard → apps | 以上全部 |
幂等性与预览机制：docgen 是幂等操作（多次运行结果相同），且仅更新标记区域（标记外人工内容不受影响）。推荐的预览/回滚流程：
- 执行前先
git commit 或 git stash 保存当前状态
- 执行 docgen 子命令
- 用
git diff 查看生成结果
- 如不满意，
git checkout . 回滚到之前状态
为什么用本Skill而非手动编辑导航表？ 手动维护导航表和看板有三个问题：一是容易遗漏新增文档，导致导航不全；二是格式不统一，表格对齐、描述截断容易出错；三是看板进度需要统计每个Spec的任务完成状态，人工统计既慢又不准。本Skill自动扫描frontmatter提取标题/描述/状态，保证导航和看板始终与实际文件同步。
3. 何时使用本技能
当用户提到以下任何内容时触发：
- "生成导航"、"更新导航"、"刷新导航表"、"文档索引"
- "更新看板"、"刷新看板"、"进度看板"、"Spec看板"
- "生成文档"、"docgen"、"更新README导航"
- "应用清单"、"apps索引"
- 新增/删除/重命名文档后
- 提到
docgen.py、generate-nav.py、generate-dashboard.py 脚本
关于触发：导航表和看板都用HTML注释标记包裹（如 <!-- nav-start -->/<!-- nav-end -->），标记区域内的内容会被脚本完全覆盖——不要手动编辑标记区域内的表格，否则下次生成会丢失。如果需要添加说明，放在标记区域外面。
4. 方案选择决策树
需要更新文档索引/看板？
├─ 新增/删除/重命名了 docs/ 下的文档？ → nav（更新导航表，第5.1节）
├─ Spec 状态变更（完成任务/新增Spec）？ → dashboard（刷新进度看板，第5.2节）
├─ apps/ 目录新增了应用？ → apps（更新应用清单，第5.3节）
├─ 原子化收尾/发布前全量更新？ → all（依次执行全部，第5.4节）
└─ 文件移动/原子化拆分后需要完整收尾？ → 优先使用 atomization-finalize-cmd（内部调用nav+dashboard+链接修复）
⚠️ 强制：触发时记录输入参数日志
决策前输出CMD_START日志（session前缀 doc-YYYYMMDD-<topic>）：
[CMD-LOG] | level=INFO | cmd=docgen | step=S0 | event=CMD_START | session=doc-... | msg=开始文档生成：<简述> | ctx={"target_dir":"...","gen_type":"navigation/dashboard/app-index"}
为什么决策前必须记录日志？ 文档生成覆盖多个文件，生成类型判断错误会产生错误索引，CMD_START记录生成类型和目录便于排查。
与其他Skill的关系：
- 原子化收尾后通常由
atomization-finalize-cmd 自动调用本Skill
- 只需要单独更新导航或看板时直接使用本Skill
为什么all的执行顺序是nav→dashboard→apps？ nav和dashboard都可能修改根README.md，nav更新导航表区域（文件中靠前位置），dashboard更新看板区域（靠后位置），顺序执行不会相互覆盖；apps操作独立文件apps/README.md，放在最后不影响。这和装修顺序同理——先处理公共区域再处理独立房间。
5. 核心命令（快速开始）
脚本路径：docgen.py
注意：generate-nav.py 和 generate-dashboard.py 是向后兼容包装器，实际功能都在 docgen.py 中，新代码直接使用 docgen.py。
5.1 更新文档导航表（nav）
cd d:\spaces\SpecWeave
python .agents/scripts/docgen.py nav
导航表自动从frontmatter或文件内容提取：
- 标题：Markdown第一个H1标题，无标题则用文件名
- 描述：frontmatter中的
description字段，或正文前60字符摘要
- 链接：自动计算相对路径
5.2 刷新Spec进度看板（dashboard）
python .agents/scripts/docgen.py dashboard
看板自动统计：
- 每个主题下的Spec总数、已完成数、进行中、待开始
- 每个Spec的任务完成进度（解析tasks.md中的复选框）
- 整体进度百分比
5.3 更新应用清单（apps）
python .agents/scripts/docgen.py apps
5.4 一键全量更新（all）
python .agents/scripts/docgen.py all
完整参数说明见脚本源码 --help 输出；所有子命令支持 --path <dir> 指定项目根目录（默认自动解析）。
6. 标记区域说明
脚本通过HTML注释标记定位要更新的区域，标记区域内的内容会被完全覆盖：
| 目标文件 | 标记对 | 区域内容 |
|---|
| README.md | <!-- nav-start --> / <!-- nav-end --> | 文档导航表 |
| docs/README.md | <!-- nav-start --> / <!-- nav-end --> | 文档导航表 |
| README.md | 看板区域标记 | Spec执行进度看板 |
| apps/README.md | <!-- APPS_TABLE_START --> / <!-- APPS_TABLE_END --> | 应用清单表 |
为什么使用标记区域而非全文件重写？ 全文件重写风险高——README.md中有人工维护的项目介绍、核心优势、架构说明等内容，自动生成只应覆盖"机器可生成"的部分（导航表、看板），保留人工编写的内容。标记区域机制实现了"人机分区编辑"：标记外是人写的，标记内是机器生成的，互不干扰。
7. 安全检查清单（执行前确认）
8. 常见错误处理
| 错误场景 | 原因 | 处理方式 |
|---|
| "未找到标记"警告 | 目标文件中缺少对应HTML注释标记 | 检查README.md中是否有 <!-- nav-start --> 标记；需要的话手动添加标记对 |
| 导航表中缺少某个文档 | 文档不在扫描目录内，或frontmatter/标题格式有问题 | 检查constants.py中的SCAN_DIRS配置；确认文档有H1标题或frontmatter title |
| 看板进度显示100%但实际未完成 | Spec的status字段为completed但tasks有未完成项，或反之 | 检查spec.md的frontmatter status字段，或tasks.md的复选框格式 |
| 应用清单为空 | apps/目录不存在或为空，或缺少README.md | 确认apps/目录存在且包含应用子目录；apps/README.md需存在并包含标记 |
| 描述显示为文件名 | 文档缺少frontmatter description且无法从正文提取摘要 | 给文档添加规范的TOML frontmatter（id、type、title、description等） |
脚本输出会显示"找到 N 个文档"/"找到 N 个主题，M 个 Spec"，如果数量与预期不符，说明扫描范围或文件格式有问题。
9. Gotchas（陷阱与反直觉行为）
为什么需要Gotchas？ 错误处理记录"已知错误码及修复方式"，Gotchas记录"容易踩的坑、反直觉行为、容易被忽略的约束条件"——不会产生明确错误码但会导致结果不符合预期的隐性陷阱。
- 不要手动编辑标记区域：
<!-- nav-start -->和<!-- nav-end -->之间的导航表内容下次运行docgen时会被完全覆盖，手动编辑的内容会丢失。如果需要添加说明文字，放在标记区域外面。
- 标记必须成对出现：缺少结束标记（
<!-- nav-end -->）会导致脚本误判后续所有内容为导航区，大量覆盖人工编写的内容。执行docgen前确认目标文件中标记对完整存在。
- 文件命名含日期格式YYYY-MM-DD：报告类文档的文件名必须包含ISO日期格式前缀（如
2026-07-01-xxx.md），导航表排序和索引生成都依赖此格式进行时间排序。缺少日期会导致排序混乱。
- 新增文档后必须重新运行docgen：docgen不会自动检测文件变化，新增/删除/重命名文档后导航表不会自动更新，必须手动运行
python .agents/scripts/docgen.py nav（或all）才能刷新索引。
- 原子化后的索引页由docgen管理：原子化拆分生成的索引页（如原子化后的导航表）属于docgen自动管理范围，不要手动维护这些导航表——手动修改会被下次docgen运行覆盖，索引一致性由脚本保证。
10. 关键参考
11. Changelog
- v1.1.0 (2026-07-01): 在§4决策树后添加S0 CMD_START强制日志规范，记录触发时的输入参数（target_dir/gen_type）便于排查生成类型错误问题。
- v1.0.0 (2026-06-30): 初始版本，基于docgen.py脚本封装为命令门面Skill，整合了原generate-nav.py和generate-dashboard.py的功能，遵循五要素模型和渐进式披露三层架构。
