编写用户手册
目标
基于真实产品系统或用户提供的材料，生成新的 DevCube 用户手册内容。默认采用“系统探索优先”的方式：学习界面、截取关键截图、规划手册结构、基于已确认模版生成 .draft.md 草稿、运行检查，并在内容转正式前请产品经理确认业务事实。
本 Skill 只用于新内容编写。不要用于历史手册治理或旧文档重构。
默认工作流
- 判断任务类型：
- 模块级生成：为新模块规划并生成模块概述、快速开始、场景指南、操作任务和功能参考等页面。
- 单功能生成：先判断页面类型，再生成对应页面和推荐导航位置。
- 评审或转正式：检查草稿、根据确认结果二次修订，或将已确认草稿转为正式页面。
- 收集最小启动信息，并执行系统访问门禁：
- 系统探索模式下，必须先拿到系统地址或访问方式、登录方式或可用会话、功能路径和范围。
- 缺少系统地址、访问方式、登录方式或可用会话时，不要生成 IA 规划文件、协作报告或手册草稿；先在对话中明确提醒用户补充系统访问条件。
- 提醒用户可提供测试账号、临时账号、已登录会话、验证码协助或其他可用访问方式。不要把账号、密码、Cookie、Token 等凭据写入 Skill、手册、协作报告或日志。
- 如果用户明确说明暂时无法提供系统入口，并要求先基于材料生成，才可降级为材料驱动方式；此时需要请用户补充截图、录屏、原型、字段清单或流程说明。
- 写文件前必须确认目标输出位置；如果用户暂未提供，但系统访问条件已满足，可以先探索和规划，再确认路径。
- 在探索前要求用户准备可用于编写手册的数据：
- 优先使用测试、演示或预发环境。
- 准备低风险账号、真实感样例数据、已配置好的流程，以及适合截图的页面状态。
- 如需覆盖多个角色，准备角色账号、可切换权限或角色截图。
- 按任务需要读取 references：
- 信息架构和页面类型选择：读取
references/page-types.md。 - 写作、术语、任务信息块、风险提示和禁止编造规则：读取
references/writing-standards.md。 - 系统探索、访问和安全边界：读取
references/exploration-workflow.md。 - 截图规则：读取
references/screenshot-standards.md。 - 草稿转正式：读取
references/draft-to-official.md。 - 产出物检查：读取
references/review-checklist.md。 - Word 预览和内链跳转：读取
references/word-export-links.md。 - 复杂页面起草或需要校准风格时，读取
references/examples.md。
- 在用户指定范围内探索系统：
- 只探索用户提供路径及其直接相关页面、表单、弹窗、页签、列表、详情和结果页。
- 对每个本批能力分组，按“菜单入口 -> 列表/概览 -> 目标数据 -> 详情/抽屉/页签 -> 关键表单/配置区 -> 结果/状态验证”的深度路径探索；不要只停留在列表页。
- 如果详情页、表单、配置区或结果页无法进入，记录原因，例如无样例数据、权限不足、需要写操作授权、详情入口不可见或当前账号看不到该状态。
- 遇到跨模块依赖时，先记录依赖，并询问是否继续深入。
- 默认只读探索。涉及新建、保存、提交、删除、发布、审批、回滚、权限或配置变更前，先说明目的、所需数据和预期影响，并请求确认。
- 高风险操作优先观察已有页面或记录；生成文档时补充风险提示，并把影响范围和回退方式放入确认清单。
- 如果当前环境无法操作浏览器或截图，说明限制，并请求用户提供截图、录屏、原型或文字说明后再降级为材料驱动生成。
- 先规划，再起草：
- 在
conductor/user-manual-generation/<module-name>/manual-ia-plan-YYYYMMDD.md生成信息架构规划。 - 只有在已获得系统访问条件并完成必要探索，或用户明确确认“先按材料驱动生成”后，才生成 IA 规划文件。
- 规划应包含模块或功能边界、用户角色、页面类型分配、建议文件路径、截图计划、草稿生成批次、Word 或本地预览范围，以及待确认问题。
- 导航规划必须使用
模块概述、快速开始、常用任务、功能参考。任务类页面统一归入常用任务，不要使用主要流程作为导航名称。 常用任务下必须按能力、对象或用户目标分组；每个能力分组第一篇必须是能力名称场景指南，后续再列具体操作任务。不要把所有任务页平铺在常用任务下。- 单功能生成也要说明该页面应归属的
常用任务能力分组；如果目标分组尚不存在，应建议补充对应场景指南后再挂载任务页。 - 截图计划必须包含本批或全量页面的截图覆盖矩阵，列明每篇文档的必需截图、目标页面或状态、数据要求、是否需要用户授权和截图状态。
- 多页面整包生成前，等待产品经理确认规划；很小的单页需求也要先简要说明页面类型判断。
- 按批次基于模版生成草稿：
- 从
assets/templates/复制对应页面模版作为起点。 - 将草稿写入已确认的目标手册目录，例如
docs/<product>/<module>/quickstart/*.draft.md、tasks/*.draft.md或reference/*.draft.md。 - 不要在 IA 确认后一次性生成全部规划页面。默认按一个相关功能组生成一批，完成本批检查和用户确认后，再等待用户指令继续下一批。
- 每批建议包含：模块概述和一个快速开始，或一个场景指南加 2 到 4 篇相关任务/参考，或一个单功能页面。只有用户明确要求一次性生成全部时，才可跳过分批门禁。
- 每批起草前先更新本批截图覆盖矩阵；必需截图未完成时，不要静默省略，应说明缺口、原因、需要用户补充的数据或授权，并询问是否先保留文字草稿。
- 截图前必须确认页面已加载完成。页面仍有 loading、骨架屏、遮罩、表格空白加载态或数据未渲染时，不得保存为最终手册截图。
- 探索临时截图可放在
conductor/user-manual-generation/<module-name>/assets/，只用于分析和协作报告；最终手册截图必须复制到目标 Markdown 就近assets/目录并规范命名。 - Markdown 正文只能引用最终手册截图，不得引用
conductor/user-manual-generation/.../assets/中的临时截图。 - 手册正文中不要出现
TODO、待补充、文档编写中、xxx等占位内容；未知问题放入协作报告。
- 生成协作报告：
- 在
conductor/user-manual-generation/<module-name>/manual-generation-report-YYYYMMDD.md写入协作报告。 - 报告包含已探索路径、已查看页面、未执行的写操作或高风险操作、截图清单、临时截图到最终截图的映射、生成文件、检查结果、导航建议、Word 导出和内链说明，以及待确认问题。
- 每批报告必须包含截图覆盖矩阵和缺图清单。缺图清单应说明缺失截图、影响文档、缺失原因、需要用户提供什么以及是否先保留文字草稿。
- 协作报告不要加入
mkdocs.yml，也不要写入用户手册正文。
- 每次生成或修改草稿后运行产出物检查：
- 使用
scripts/check_manual_output.py <file-or-dir> --report <report.md>。 - 需要结构化结果时使用
--json。 - 可安全修复的机械问题应自动修复，然后重新运行检查。
- 业务事实、推断规则、权限、角色行为、状态流转和风险细节必须留给产品经理确认，不要擅自补成事实。
- 每批草稿生成后，输出本批文件清单、截图覆盖矩阵、缺图清单、检查结果和待确认问题，并明确询问用户是否接受当前截图覆盖、是否需要补图、以及是否继续下一批。
-
根据确认结果二次修订：
- 将产品经理的确认结果回填到草稿。
- 更新截图、图注、风险提示、相关链接和导航建议。
- 重新运行检查，并更新协作报告。
-
只有在明确确认后才将草稿转为正式文档：
- 去掉文件名中的
.draft。 - 将同一批转正式页面之间的
.draft.md链接同步改为.md。 - 如果目标正式文件已存在，不要覆盖；先请求明确确认。
- 先提出
mkdocs.yml导航修改建议，确认后再修改。 - 需要草稿预览或 Word 导出时，先提出
mkdocs.local.yml修改建议，确认后再修改。 - 转正式后再次运行产出物检查。
- 去掉文件名中的
资源使用
assets/templates/存放已确认的页面模版。生成所有手册页面时，都应以对应模版为起点。references/存放详细规范。执行任务前按需要读取对应文件，不要把全部规范重复塞进对话。scripts/check_manual_output.py用于确定性检查手册产出物；存在阻断项时返回非零状态码。
确认纪律
不要编造用户角色、字段、状态、权限、规则、风险、流程分支或系统行为。若结论来自界面观察推断，应写入确认清单并说明推断依据。手册语言可以润色，但未知业务事实不能被写成确定结论。
