Skip to content

xinetzone/SpecWeave / .agents/skills/docgen-cmd

docgen-cmd

Verified

当用户提到'生成导航'、'更新导航'、'更新看板'、'刷新看板'、'生成文档索引'、'docgen'、'更新README'、'应用清单'、'文档生成'时,必须使用此技能。提供文档导航表与执行看板自动生成能力:扫描文档目录生成导航表、扫描.trae/specs/生成进度看板、生成apps/应用清单索引。不要手动编辑导航表或看板区域——它们由标记包裹,本Skill会自动更新标记区域内的内容,手动编辑会被下次生成覆盖。

DocGen 文档导航与看板生成 Skill

⚠️ 本Skill是脚本命令门面(L1索引层),遵循渐进式披露三层架构:

  • L0:.agents/ONBOARDING.md(入口速查)
  • L1:本文件(<500行,触发词+决策树+核心命令+安全清单)
  • L2:脚本源码 docgen.py(完整实现)

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 是幂等操作(多次运行结果相同),且仅更新标记区域(标记外人工内容不受影响)。推荐的预览/回滚流程:

  1. 执行前先 git commit 或 git stash 保存当前状态
  2. 执行 docgen 子命令
  3. 用 git diff 查看生成结果
  4. 如不满意,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

# 生成/更新导航表(扫描docs/和根目录.md,更新README.md和docs/README.md)
python .agents/scripts/docgen.py nav

导航表自动从frontmatter或文件内容提取:

  • 标题:Markdown第一个H1标题,无标题则用文件名
  • 描述:frontmatter中的description字段,或正文前60字符摘要
  • 链接:自动计算相对路径

5.2 刷新Spec进度看板(dashboard)

# 生成/更新 Spec 执行进度看板(扫描.trae/specs/下所有主题和Spec)
python .agents/scripts/docgen.py dashboard

看板自动统计:

  • 每个主题下的Spec总数、已完成数、进行中、待开始
  • 每个Spec的任务完成进度(解析tasks.md中的复选框)
  • 整体进度百分比

5.3 更新应用清单(apps)

# 生成/更新 apps/README.md 应用清单
python .agents/scripts/docgen.py apps

5.4 一键全量更新(all)

# 依次执行 nav → dashboard → apps(原子化收尾/发布前推荐)
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. 安全检查清单(执行前确认)

  • 明确需要更新哪个部分(nav/dashboard/apps/all),不要盲目执行all
  • Git工作区已提交或有备份(执行前git commit/stash,可用git diff预览变更、git checkout回滚)
  • 新增的Markdown文件包含规范的frontmatter(id、title、description等)或H1标题
  • Spec文件(spec.md)包含正确的status字段和tasks.md
  • 没有手动编辑过标记区域内的内容(如有手动修改,先移到标记外)
  • 执行后检查更新结果,确认导航表链接正确、看板进度符合预期
  • 如配合链接修复,先执行链接修复再生成导航(避免导航表引用断链)

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. 关键参考

参考层级路径何时查阅
脚本源码(完整参数)L2docgen.py需要理解扫描逻辑、添加新的生成目标时
原子化收尾SkillL1atomization-finalize-cmd文件移动/拆分后的完整收尾(含链接修复)
链接检查SkillL1link-check-cmd生成导航前先确认链接有效
共享工具库L2scripts/lib/markdown.py理解标题/描述提取逻辑
扫描配置L2scripts/constants.pySCAN_DIRS、TARGETS、MANUAL_DESCRIPTIONS等配置

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的功能,遵循五要素模型和渐进式披露三层架构。
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall