用途:从源码仓库生成准确的 DocsPress 兼容 Markdown 文档,并在需要时维护多个 API 版本。
主要能力:先确定事实来源,解析仓库根目录并保留无关改动,用 rg --files 盘点项目,检查包清单、锁文件、入口、导出、命令定义、schema、环境示例、测试、示例、发布配置与现有文档;据此识别目标读者与公开接口,并判断是否真正支持多版本 API(需有维护分支、版本化 schema、兼容性测试或既有版本化文档等明确证据)。写作前建立覆盖图:安装命令对应清单与锁文件,配置与环境变量对应 schema、默认值与代码读取,API 签名对应导出源码与类型声明,CLI 命令与标志对应解析器定义与帮助输出,行为与边界对应测试,运维步骤对应脚本与 CI 工作流。测试与可执行示例比注释更可信,矛盾之处标记待解决而非静默取舍。不把私有辅助函数写成公开 API,不编造命令、选项、URL、支持保证、性能声明或输出文本。
使用方式:复用并就地更新已有文档,按项目规模规划文档树(如 index.md、getting-started、guides、reference、troubleshooting),只创建有源码支撑的页面。docs/index.md 映射为 Docs 根,文件夹 index.md 作分区落地页,避免多个文件归一化到同一路由。多版本时保留仓库自然布局并添加有序注册表(如 docs-versions.json,含 latest 与 versions,来源类型可为 root、directory 或 suffix),每个源文件只归属一个版本,每个版本每个页面有唯一逻辑路由,同版本内互链,缺失页面回退到该版本根。
写作规范:使用 frontmatter title,正文从 ## 开始;用 .md 或 .markdown 与相对链接;路径稳定、slug 可读;代码块标注准确语言;命令前说明前置条件、命令后说明验证;示例最小但可运行,不使用真实凭据或生产标识。可使用 DocsPress Gutenberg 块(如 hero、code-tabs、callout、api-request、fields、diagram、terminal-session、result、file-tree、prompt、version-switcher、version-notice 等),以自闭合注释加紧凑 JSON 形式书写,不添加渲染 HTML 体、尾逗号或自造属性。
限制:仅依据仓库证据,缺失事实不编造;多版本需明确证据;块属性取值受插件允许值约束;发布设置不在本技能内完成。