Codex Skill · DevCube 用户手册

write-user-manual Skill 介绍

该 Skill 面向产品经理编写新的 DevCube 用户手册内容。它以“系统探索优先”为默认方式， 通过最少输入进入产品系统学习界面流程、规划手册结构、截取关键截图、生成符合规范和模版的 .draft.md 草稿，并在转正式前完成产出物检查和业务确认。

基本信息

Skill 标识

项目 说明
名称 write-user-manual
显示名 编写用户手册
位置 conductor/skills/write-user-manual
主要用户 产品经理、用户手册负责人、模块内容负责人

核心目标

帮助产品经理基于真实系统和已确认的用户手册规范，生成新模块或新功能的用户手册草稿。 Skill 不以“润色文字”为核心，而是把系统探索、页面类型选择、草稿生成、截图组织、 产出物检查和草稿转正式流程串成一套稳定工作流。

系统探索优先 先规划后生成 草稿优先 禁止编造

应用场景

新模块手册生成

基于模块路径和功能范围，规划模块概述、快速开始、场景指南、任务页和功能参考。

单功能页面生成

针对一个新增功能，先判断页面类型，再生成操作任务、功能参考或场景指南。

系统探索与截图

在指定范围内浏览界面、学习流程、记录页面状态，并截取关键节点截图。

草稿检查与二次修订

对生成的 Markdown、图片、链接、任务信息块和风险提示进行检查，并根据确认结果修订。

草稿转正式文档

在产品经理确认后，处理 .draft.md 到正式 .md 的重命名和互链更新。

本地预览与 Word 导出准备

提出 mkdocs.local.yml 导航建议，并检查相关文档在 Word 导出中的内链跳转范围。

输入要求

最小启动输入

  • 系统地址或访问方式。
  • 登录方式、可用会话或临时访问授权。
  • 功能路径和范围，例如菜单、页面、按钮、页签或操作范围。
  • 写文件前确认目标输出位置；该项可在规划后再确认。

建议提前准备

  • 测试、演示或预发环境。
  • 低风险账号和必要权限。
  • 真实感样例数据和已配置好的流程。
  • 适合截图的页面状态。
  • 多角色场景所需的账号、权限说明或截图。

系统探索模式下，系统地址或访问方式、登录方式或可用会话、功能路径和范围是启动前置条件。 如果缺少系统入口或登录方式，Skill 应先在对话中提醒用户补充访问条件，不应直接生成 IA 规划或草稿。 只有用户明确要求“先按材料驱动生成”时，才基于截图、录屏、原型或字段说明降级生成。

Skill 默认只读探索。涉及新建、保存、提交、删除、发布、审批、回滚、权限或配置变更时， 需要先说明目的、所需数据和预期影响，再向用户请求确认。

SOP

判断任务类型

区分模块级生成、单功能生成、草稿检查、二次修订或草稿转正式。

读取规范和模版

按任务需要读取页面类型、写作规范、探索流程、截图规范、检查清单等 references。

检查系统访问门禁

确认已获得系统地址、登录方式或可用会话、功能路径和范围；缺少访问条件时先向用户索要，不生成规划文件。

限定范围探索系统

只探索用户指定路径和直接相关页面；按入口、列表、详情、表单和结果验证逐层深入，跨模块依赖先记录再询问。

建立截图覆盖矩阵

按本批文档列出必需截图、目标页面或状态、数据要求、授权要求和截图状态。

等待页面稳定后截图

页面无 loading、骨架屏、遮罩和未渲染表格后再截图；真实空数据页面需在协作报告中说明。

生成 IA 规划

输出页面类型分配、建议目录、导航结构、每篇页面目标、截图计划、草稿生成批次、预览范围和待确认问题。

按批生成草稿

默认按一个相关功能组生成一批；每批检查并等待用户确认后，才继续下一批。

复制最终手册截图

探索临时截图保留在协作目录；选中的截图复制到目标文档就近 assets/ 并规范命名。

生成协作报告

记录探索路径、临时截图到最终截图映射、生成文件、未执行操作、检查结果、导航建议和待确认项。

运行产出物检查

检查标题、任务信息块、占位内容、图片、链接、风险提示、草稿命名和预览范围。

确认后修订和转正式

根据产品经理确认结果修订草稿；明确授权后去掉 .draft、更新互链并建议导航变更。

输入与输出

阶段 输入 输出
启动 系统地址、登录方式、功能路径、范围说明。 探索计划、需用户准备的数据和权限提醒。
规划 系统探索结果、页面观察、用户补充材料。 manual-ia-plan-YYYYMMDD.md，包含页面清单、目录建议、常用任务 能力分组、截图覆盖矩阵和生成批次。
起草 已确认 IA、页面模版、截图和业务材料。 按批生成 .draft.md 草稿、最终手册截图、相关文档链接和图注。
检查 草稿文件、图片目录、可选 mkdocs.local.yml。 阻断项、警告项、建议项；可生成 Markdown 报告或 JSON。
协作 探索记录、检查结果、待确认业务问题。 manual-generation-report-YYYYMMDD.md，包含截图覆盖矩阵、缺图清单，用于产品经理验收和二次修订。
转正式 产品经理确认后的草稿批次。 正式 .md 文件、互链更新、导航建议和转正式后检查结果。

内置资源

References

  • page-types.md：页面类型和递进关系。
  • writing-standards.md：写作规范、术语、风险提示、禁止编造。
  • exploration-workflow.md：系统探索、权限、安全和降级策略。
  • screenshot-standards.md：截图场景、命名、存放和引用。
  • draft-to-official.md：草稿、协作报告、转正式和导航策略。
  • review-checklist.md：阻断项、警告项和建议项。
  • word-export-links.md：Word 预览和内链跳转要求。
  • examples.md：已确认样板的精简示例。

Templates

  • module-overview.md：模块概述。
  • quickstart.md：快速开始。
  • scenario-guide.md：场景指南。
  • task-guide.md：操作任务。
  • function-reference.md：功能参考。
  • best-practice-faq.md：最佳实践或 FAQ。

产出物检查机制

检查脚本

Skill 内置 scripts/check_manual_output.py，用于在草稿生成、草稿修改和转正式前执行确定性检查。 

python3 conductor/skills/write-user-manual/scripts/check_manual_output.py \
  docs/<product>/<module>/tasks/example.draft.md \
  --phase draft \
  --mkdocs-config mkdocs.local.yml \
  --report conductor/user-manual-generation/<module>/check-report.md

阻断项

如无一级标题、断图、断链、占位内容、任务页缺少任务信息块、高风险操作缺风险提示、正文引用探索临时截图。

警告项

如无截图、图片缺图注、图片命名不规范、图片未放在就近 assets、预览范围未覆盖、标题层级过深、页面类型疑似不匹配、导航使用 主要流程、协作报告缺截图覆盖矩阵。

建议项

如补充相关文档、增加结果验证截图、优化截图裁剪或简化表达。

截图工作规则

探索深度

  • 按菜单入口、列表或概览、目标数据、详情或抽屉、关键表单或配置区、结果验证逐层探索。
  • 列表页不能替代详情页、配置页和结果页；详情型任务必须尝试打开详情或抽屉。
  • 无法深入时记录原因，例如缺数据、缺权限、需写操作授权或跨模块待确认。

截图覆盖矩阵

  • 每批草稿生成前列出文档、页面类型、必需截图、目标页面或状态。
  • 记录数据要求、授权要求和截图状态。
  • 缺少必需截图时，交付给用户确认前必须列出缺图清单和需要用户协助的动作。

截图就绪门禁

  • 页面无加载图标、骨架屏、遮罩 loading 或按钮 loading。
  • 表格、列表、详情区已完成渲染，或明确显示稳定的“暂无数据”。
  • 查询、切换页签、展开菜单或打开弹窗后，需要重新等待稳定。
  • 截图后如发现 loading 或未渲染区域，应重新等待并重截。

临时截图与最终截图

  • 探索临时截图放在 conductor/user-manual-generation/<module>/assets/。
  • 最终手册截图复制到目标 Markdown 就近 assets/ 目录。
  • Markdown 正文只引用最终手册截图。
  • 默认保留临时截图用于追溯；仅在用户要求时清理未使用截图。

边界和安全规则

适合使用

  • 新模块或新功能用户手册编写。
  • 基于系统路径自动探索并生成草稿。
  • 关键截图规划和自动命名。
  • 草稿检查、二次修订和转正式准备。
  • 本地预览和 Word 内链范围检查。

不适合使用

  • 历史文档治理和旧文档重构。
  • 旧文档覆盖矩阵迁移。
  • 未授权的生产环境写操作。
  • 基于常识编造字段、状态、权限或业务规则。
  • 把协作报告作为用户手册正文发布。

所有未知业务事实都应进入待确认清单。界面观察可以形成推断，但不能直接写成未经确认的确定结论。