上位机技术文档工程：方案、总结、说明书与验收

内容类型：正式技术文档方法难度：进阶适合：需要编写设计方案、研制总结、说明书、测试/验收资料的上位机工程师阅读时间：约 13 分钟

正式不等于“所有内容都写成长段落”。真正专业的技术文档应该准确、客观、可追溯，并使用最适合当前信息的表达形式：设计原因用段落，参数和接口用表格，操作过程用步骤，状态变化用图或状态表，测试结论必须有证据。

host-computer-dev V9 起已经把文档能力从“文字润色”升级成“技术文档工程”，V10 继续保留并加强证据边界。

1. 先识别文档类型

文档	核心问题	推荐表达
设计方案	为什么这样设计，整体怎么组成	正式段落 + 架构图 + 技术路线表
详细设计	模块具体如何实现和协同	多视图 + 接口/状态/数据表
研制总结	实际做了什么，怎么证明完成	过程 + 问题 + 测试 + 符合性矩阵
使用说明	用户怎样正确、安全操作	前置条件 + 编号步骤 + 截图 + 预期结果
测试/验收报告	是否达到要求	测试项 + 方法 + 实际数据 + 判定
需求规格	系统必须满足什么	唯一编号 + 可验证要求
接口协议	双方如何正确交互	字段表 + 报文 + 时序 + 错误码

不要用同一套“八步法”覆盖所有文档，也不要为了“正式”机械套旧模板。

2. 文档工作流

text

识别文档类型和读者
→ 收集当前材料
→ 建 Evidence Map
→ 冻结当前事实边界
→ 选择必要章节和视图
→ 编写正文
→ 设计图/表/符合性矩阵
→ 正式化修订
→ 技术与格式检查
→ 交付

模板只是参考结构。项目没有的内容不要为了凑章节虚构；真正重要但模板没有的内容应补进去。

3. Evidence Map：正式结论必须知道依据来自哪里

内部建议区分：

状态	可以支持什么表达
`Verified`	有实际测试、测量、现场或验收证据，可写“经测试/实测……”
`SourceConfirmed`	当前代码、配置、协议或批准资料明确支持，可写“系统实现/配置为……”
`DesignOnly`	只有设计方案，可写“设计为/拟采用……”
`HardwarePending`	要求真实设备/现场/HITL 证据，但对应步骤尚未执行或现场条件尚未具备
`EnvironmentBlocked`	本应在软件环境执行的验证因权限、E-SafeNet、缺 SDK/工具等环境原因被阻断
`Unverified`	证据不足，只能标待确认或保守描述

例如：代码里存在 CheckInterlock()，只能证明有相关实现；没有测试和现场证据时，不能直接写“经验证系统具备可靠联锁能力”。

推荐追溯链：

text

Requirement
→ Design
→ Implementation
→ Verification Method
→ Actual Evidence
→ Conclusion

4. 事实来源要有优先级

同一事实出现冲突时，不能靠“哪个文档写得更正式”决定。

建议优先核对：

text

当前批准需求/技术协议
→ 当前真实代码与配置
→ 当前测试/现场证据
→ 当前接口/设备资料
→ 已确认的 CONTEXT / ADR
→ 历史样稿

具体项目可以调整顺序，但必须能解释为什么采用某个来源。

如果来源之间仍冲突：

text

ConflictDetected
→ 明确冲突内容
→ 不自动替用户选业务事实
→ 保留待确认

5. 技术细节不是一律删除，而是按读者分级

L1 方案/评审级

强调：

业务目标；
系统边界；
技术路线；
模块能力；
关键约束；
主要风险和验证策略。

通常不写大量类名、方法名和代码。

L2 详细设计级

允许并经常需要：

协议和字段；
状态机；
数据结构；
数据库/文件模型；
模块接口；
关键算法机制；
线程与资源生命周期；
异常恢复设计。

L3 使用/维护/接口级

必要时可以写：

端口、地址；
配置项；
命令；
路径；
字段名；
版本；
必要报文或代码片段。

“正式文档不能出现 C#、UDP、MySQL、类名”不是通用规则，是否保留取决于文档用途和读者。

6. 详细设计：按需要选择视图

上位机项目常用：

text

业务流程视图
系统组成视图
软件模块视图
设备通信视图
运行时序视图
状态机视图
数据存储视图
部署视图
安全联锁视图
异常恢复视图

不是每份详细设计都必须包含全部视图。只选择真正有助于解释当前系统和当前评审范围的部分。

7. 设计方案：重点是可行性、边界与取舍

设计方案不要写成“详细设计提前展开”。更适合回答：

text

目标和约束是什么？
总体方案是什么？
为什么选这条技术路线？
系统如何组成？
关键风险是什么？
如何证明方案可行？
本阶段不做什么？

对尚未实现的能力使用“拟采用、设计为、计划通过”等表达，不提前写成“已实现”。

8. 研制总结：不是把设计文档改成过去时

推荐逻辑：

text

为什么研制
→ 要求是什么
→ 采用什么方案
→ 实际完成什么
→ 做了哪些验证
→ 遇到哪些问题
→ 为什么发生
→ 如何解决和归零
→ 哪些仍 Unverified / HardwarePending
→ 是否满足当前要求
→ 形成哪些交付成果

如果项目有 .agent-memory/changes、Git 历史、测试报告、现场日志，应优先从这些证据恢复过程，而不是靠人回忆。

尤其不要出现：

text

Fake/Replay 通过
→ 研制总结写“真机验证通过”

正确写法应保留：

text

软件侧验证：Verified
真实设备验证：HardwarePending

9. 使用说明：操作员视角优先

推荐任务结构：

text

目的
前置条件
操作步骤
预期结果
异常处理
注意 / 警告

例如：

text

### 应用试验参数

前置条件：设备连接正常，当前状态允许参数应用。

操作步骤：
1. 进入“试验配置”。
2. 填写参数。
3. 单击“参数校验”。
4. 校验通过后单击“应用设备”。

预期结果：界面显示应用结果；真实设备是否产生输出按当前产品规则执行。

操作员说明使用清晰业务语言；底层 SCPI、堆栈、寄存器等维护信息按需要放在维护章节或日志说明中。

详见操作员界面与维护诊断。

10. 测试/验收：方法、实际结果和结论分开

推荐符合性矩阵：

要求	设计/实现	验证方式	实际结果	状态	结论
R-001	某功能已实现	focused test	8/8 Passed	Verified	符合软件侧要求
R-002	高压输出流程	真机 2 kV 验证	尚未执行	HardwarePending	待现场验证

如果只有设计和代码证据，没有实际测试结果，就不能把“设计满足”写成“验收通过”。

如果测试因为环境被阻断，也应写 EnvironmentBlocked，而不是把它混成 Passed 或 Failed。

11. 图表不是装饰

信息	适合形式
系统组成	架构图/部署图
模块调用	时序图
状态变化	状态图/状态表
技术参数	表格
测试符合性	矩阵
用户操作	编号步骤 + 截图
原理和取舍	正式段落

图题、表题、章节引用、单位和术语必须前后一致。图中信息也必须和正文、代码、当前版本一致。

12. 历史样稿只能参考结构，不能继承旧事实

旧文档可以学习：

封面和签审习惯；
章节组织；
更改栏；
符合性表；
测试记录；
交付清单；
截图式操作说明。

不能直接继承：

旧软件版本；
旧数据库版本；
旧协议参数；
旧设备范围；
旧性能结果；
旧路径和地址；
旧测试“通过”结论。

当前材料与旧样稿冲突时，优先当前证据；仍无法确认时明确标注。

13. 正式语言不能超过证据强度

谨慎使用：

“完全满足”；
“稳定可靠”；
“无任何异常”；
“全面验证”；
“达到设计指标”；
“已完成所有测试”。

这些词都需要相应证据范围。

更准确的写法：

text

在本次规定的 8 项自动测试中均通过。

连续运行 4 h 未观察到目标异常；24 h 长稳尚未执行。

当前软件侧功能已完成，真实设备联调待现场条件具备后开展。

14. Review 时检查什么

技术审查至少覆盖：

文档类型和读者是否匹配；
是否有技术事实丢失；
是否把设计结论写成测试结论；
是否把 Fake/Replay 写成真机；
HardwarePending / EnvironmentBlocked 是否被隐藏；
术语是否统一；
图号、表号、章节引用是否有效；
数值、单位、时间尺度是否一致；
是否遗留 TODO / 待确认；
是否有模板造成的无关章节；
是否有历史样稿污染当前事实；
是否符合项目签审和正式交付习惯。

15. Compose / Revise / Review 三种模式

text

Compose
= 从材料生成新文档

Revise
= 在已有文档上修订内容/结构

Review
= 检查问题和证据，不擅自全文重写

Review 任务不因为发现几处问题就默认重排整份说明书；只分析文字内容时也不必先做图片、目录、页面渲染等无关检查。

16. 和 V10 Skill 的关系

host-computer-dev-15-document-generator 按文档类型加载当前需要的 Profile，不把说明书、研制总结、协议、详细设计的全部规则一次塞进上下文。

一句话原则

正式技术文档的核心不是“写得像公文”，而是结构适合用途、事实来自当前证据、结论不超过验证边界，并让评审者能够追溯每个重要结论。

上位机技术文档工程：方案、总结、说明书与验收 ​

1. 先识别文档类型 ​

2. 文档工作流 ​

3. Evidence Map：正式结论必须知道依据来自哪里 ​

4. 事实来源要有优先级 ​

5. 技术细节不是一律删除，而是按读者分级 ​

L1 方案/评审级 ​

L2 详细设计级 ​

L3 使用/维护/接口级 ​

6. 详细设计：按需要选择视图 ​

7. 设计方案：重点是可行性、边界与取舍 ​

8. 研制总结：不是把设计文档改成过去时 ​

9. 使用说明：操作员视角优先 ​

10. 测试/验收：方法、实际结果和结论分开 ​

11. 图表不是装饰 ​

12. 历史样稿只能参考结构，不能继承旧事实 ​

13. 正式语言不能超过证据强度 ​

14. Review 时检查什么 ​

15. Compose / Revise / Review 三种模式 ​

16. 和 V10 Skill 的关系 ​

一句话原则 ​

上位机技术文档工程：方案、总结、说明书与验收

1. 先识别文档类型

2. 文档工作流

3. Evidence Map：正式结论必须知道依据来自哪里

4. 事实来源要有优先级

5. 技术细节不是一律删除，而是按读者分级

L1 方案/评审级

L2 详细设计级

L3 使用/维护/接口级

6. 详细设计：按需要选择视图

7. 设计方案：重点是可行性、边界与取舍

8. 研制总结：不是把设计文档改成过去时

9. 使用说明：操作员视角优先

10. 测试/验收：方法、实际结果和结论分开

11. 图表不是装饰

12. 历史样稿只能参考结构，不能继承旧事实

13. 正式语言不能超过证据强度

14. Review 时检查什么

15. Compose / Revise / Review 三种模式

16. 和 V10 Skill 的关系

一句话原则