wehub-resource-sync
5.7 KiB
5.7 KiB
操作手册结构
操作手册应像真实软件随附的操作说明，目标是让读者知道软件用途、功能和基本操作。
推荐采用软著审核友好的通用骨架，类似传统操作手册：
- 相关文档：用表格指向总体设计、详细设计、测试案例等配套资料。
- 说明：说明软件定位、目标用户、业务场景和整体流程。
- 功能特点：按当前项目真实功能概括 4-8 项特点，每项说明业务作用和用户可见结果。
- 系统要求：用表格说明最低配置和推荐配置；Web 项目可写浏览器、网络和服务访问要求，桌面项目可写操作系统、处理器、内存、存储和分辨率。
- 具体页面 / 功能操作：从第 5 章开始，按真实页面、导航入口或核心流程逐章说明，每章写使用场景、页面用途、进入位置、页面内容、用户动作、输入限制或异常提示、操作结果和截图预留。
- 典型使用流程：如项目存在清晰串联流程，可单独写一章串起从进入软件到完成核心任务的过程。
- 常见问题解答：写 3-5 个与当前软件真实使用相关的问题和解决方法。
- 术语表：解释软件名称、核心业务对象、页面模块和用户可能不熟悉的术语。
以上是通用骨架，不是旧项目内容。正式章节标题使用中文大写序号，例如 一、相关文档，不要使用 (1)、相关文档。生成时必须根据当前项目业务、页面入口、功能关系和用户可见控件填充内容，不要照抄用户提供的范本文案。
具体页面和流程必须来自 草稿/业务理解.json 中模型写入的 manual_modules。如果该字段为空，不能根据 business_features 生成兜底模块，应停止并要求模型阅读真实页面和项目资料后补全。
写作口径
- 使用通用、客观、简洁的中文。
- 不写面向终端用户的复杂教程。
- 每个章节必须有段落化说明，不能只写项目符号列表；正文不要用
-、*、1. 2. 3.堆信息。 - 每个核心页面或功能模块必须覆盖“使用场景 + 页面用途 + 进入位置 + 页面内容 + 用户动作 + 输入/状态规则 + 系统反馈 + 截图预留”，但这些信息要合并成自然段落，不能直接输出成字段表单。
- 优先写用户真实能看到和操作的内容，例如输入框、按钮、下拉框、标签页、列表、卡片、弹窗、错误提示、状态栏、导入导出入口、额度或权限提示。
- 补充说明段落只能写当前软件的用途、业务场景、页面组织和用户流程，不写“本操作手册用于……”“面向软著审核……”“不描述代码实现……”这类解释文档写作方式的元话语。
- 禁止在脚本中按 auth、query、form、workflow 等分类自动生成入口、步骤或结果反馈。入口和步骤必须来自模型对当前项目真实页面的阅读。
- 功能特点不要写成“开头一句总述 + 编号列表 + 结论”的头中尾结构。每个特点用段落展开，说明该功能解决什么业务问题、用户在页面上看到什么、完成操作后得到什么结果。不同功能的说明要有差异，避免每条都使用相同句式。
- 页面章节不要输出“进入方式：”“页面内容：”“操作步骤：”“操作规则：”“操作结果与反馈：”这类模板小标题。
- 操作手册语言要让审核员和普通读者能看懂，重点说明模块是做什么的、怎么操作、操作后看到什么。避免代码、框架、接口、状态管理、异步任务等技术化表达。
- “AI 味”主要表现为空泛、整齐、万能、没有项目现场感：例如每个模块都用同一种句式，反复写“提升效率、优化体验、提供支持”，使用“旨在、赋能、一站式、智能化、高效便捷、显著提升、强大能力、丰富功能”等口号，却没有说明当前项目的真实页面、真实对象、真实动作和真实反馈。发现这类内容时必须改写成朴素、具体、可回溯到项目证据的表达。
- 截图前必须先让用户在 Chrome DevTools MCP、Codex Computer Use、用户自行截图三种方式中选择；选择后检查对应能力是否可用。用户说现在不截图或先跳过截图时，记录为
skip，并在每个需要截图的位置保留正式 Word 中可见的截图预留文字。 - 不夸大不存在的功能。
- 功能名称和章节组织由模型根据项目证据判断；路由、页面、README、接口和组件命名只是证据来源，不是固定抽取规则。
- Markdown 草稿生成前由 agent 自行检查章节完整性、内容厚度、项目流程一致性和语言自然度，发现章节过薄、模块套话、AI 味、技术化表达或相邻模块含义混淆时先循环补写和修正；完整草稿生成后只向用户发起一次整体确认，再进入 Word 生成。
- 操作手册生成时必须同步输出
操作手册自检记录.md/json。记录中至少包含初稿生成、按项目流程扩写、去除制式表达和 AI 味三轮；如果第三轮仍发现问题，要继续自动修正并追加轮次记录。 - 操作手册必须基于已确认的业务理解写作。相近功能应结合项目真实业务分别说明各自的操作目的、用户动作和结果反馈，不能用同一段话替换不同模块。
- 自检时必须检查是否生成了“功能操作说明”大章下反复套同一批模块的情况；如果出现同一模块重复多次，必须改为每个真实页面独立成章。
- 禁止把测试项目中的行业、角色、流程、功能名称或示例文案写成通用规则；范本只能帮助理解软著手册需要“通顺、具体、能给审核员看懂”，不能作为固定内容来源。