Serial-Studio 规范驱动开发 Phase 2:plan.md 技术方案模板全解

原创2026-09-18 18:05:081,925 阅读
文章标签:桌面应用数据可视化物联网IoT协议嵌入式工业制造硬件开发

Serial-Studio 规范驱动开发 Phase 2:plan.md 技术方案模板全解

Serial-Studio 采用「spec → plan → tasks → implementation」四阶段规范驱动开发。本文以 plan.md 模板 为骨架,逐一讲解每个必填章节的写作目标与判定标准,并对照仓库内真实样例(如 OPC UA 驱动方案)与配套验证脚本,说明一份可被评审通过、可直接交给 /ss-tasks 拆解的技术方案应当如何撰写。读完本文,你将掌握 plan.md 的完整结构、热路径与静默破坏检查要点,以及方案与测试、静态检查工具链的对接方式。

一、plan.md 在四阶段流程中的位置与作用

Serial-Studio 的非平凡开发默认走规范驱动流程(详见 spec-driven.md):每个功能占据一个编号目录(如 doc/claude/specs/0066-opcua-driver/),按顺序产出并逐份由人工批准:

阶段 技能 产物 门禁(Gate)
1. 需求(Specify) /ss-spec spec.md — WHAT & WHY:问题、目标、非目标、编号需求、验收标准、约束 维护者标记 approved
2. 方案(Plan) /ss-plan plan.md — HOW:涉及文件、数据流、热路径/线程影响、数据模型、API/QML、权衡、风险、测试计划 维护者批准设计
3. 任务(Tasks) /ss-tasks tasks.md — 有序、可单独验证的检查清单 + 完成定义 维护者批准拆解
4. 实现(Implement) /ss-implement 逐任务代码;tasks.md 保持更新 完成定义达成;自查;sanitize

模板存放于 doc/claude/specs/templates/,编号与状态生命周期见 specs/README.md:编号四位零填充、单调递增、永不重用;status 沿 draft → approved → in-progress → done | shelved 演进。

plan.md 是 Phase 2(四阶段中的第 2 阶段),模板开头声明其定位:"The HOW. The technical design that satisfies every requirement in spec.md."它承接已批准的 spec(WHAT/WHY),产出满足全部需求的技术设计(HOW),并在人工标记 approved 之前,禁止启动 /ss-tasks。

模板还提出了一个反直觉的前提:写方案前必须阅读相关 doc/claude/ 子文档和真实代码——"a plan grounded in a stale mental model is worse than no plan"(基于过时心智模型的方案比没有方案更糟)。这同样呼应了 spec-driven 的核心纪律:每个阶段以上一产物为唯一事实来源,发现更早阶段有误必须回改并重新确认,绝不静默偏离。

plan.md 也是「把权衡提前摆上桌面」的关键载体:仓库工作关系规则"以决策形式呈现权衡,而非事后注释"被内建进模板的 Tradeoffs 章节;热路径与静默破坏类别被强制要求每次都给出显式回答,而不是等帧流中断后才被事后发现。

二、frontmatter 与标题约定

模板以 YAML frontmatter 开头:

---
spec: NNNN-short-slug
phase: plan
status: draft        # draft -> approved (gate before /ss-tasks)
updated: YYYY-MM-DD
---
  • spec:对应目录名(如 0066-opcua-driver),与 spec.md 保持一致。
  • phase: plan:固定标识本文件属于第二阶段。
  • status:从 draft 到 approved 的转换就是启动 /ss-tasks 的门禁;未获批准不得进入下一阶段。
  • updated:维护者修订方案时应更新的日期。

标题遵循 # Plan NNNN — <Feature name> 格式。模板开头附有引用块,说明本文档的角色与门禁规则;真实的 0066 方案 保留了该引用块并将 status 更新为 approved(2026-08-22),是模板到成品的直接对照。

三、Approach:一段话总结设计

模板要求用 3~5 句话给出选定的设计:做什么、插在哪里、为什么是这个形态而非备选。细节留给下文,这段是评审者最先阅读的摘要。

以 0066 方案 的 Approach 为例,它在一段话内交代了:

  • 技术选型:新商业版 IO::Drivers::OpcUa HAL 驱动,包装一个 QOpcUaClient(Qt OPC UA,open62541 后端,安全策略 None);
  • 关键流程:端点发现 → 异步连接(spec-0050 单裁决闩锁)→ 地址空间浏览成标签模型 → 通过 QOpcUaNode::enableMonitoring 订阅(轮询回退)→ 每标签值缓存 → 驱动侧定时把变更标签序列化为一帧紧凑二进制增量帧;
  • 解析侧:新增 opcua 原生模板(NativeLatchParser,schema 参数列出每标签索引与类型,未变更标签 latch),项目生成时写 schema 对象而非生成 Lua,解析运行在 Native span 通道;
  • 影响边界:"Nothing downstream of the driver changes"(驱动下游无需任何改动)。

这段文字本身就是评审者判断"方向对不对"的第一手材料,写方案时应先精炼出这样一段。

四、Affected subsystems & files:可 grep 验证的文件清单

模板要求列出每一个预期新建或修改的文件,并为每个文件写一行角色说明。关键纪律是:写方案时就用 grep 确认触点真实存在——例如新增枚举值或驱动时,必须确认它出现在每一个 switch/列表里(可参考 ss-new-driver 技能提供的驱动触点清单)。

真实样例的清单长达 30+ 行,涵盖:

  • 新建源码:app/src/IO/Drivers/OpcUa.h/.cpp(驱动本体)、OpcUaTagModel.h/.cpp(地址空间浏览的 QAbstractItemModel)、OpcUaWire.h(驱动编码器与原生模板解码器共享的线协议词汇表,镜像 CANBus/GsUsbProtocol.h);
  • 改动触点:SerialStudio.h 的 BusType::OpcUa 追加在商业块末尾(枚举顺序即索引,直接影响 Hardware.qml 的 StackLayout 与 api_client.py 的 bus_map)、ConnectionManager 的 UI 槽与三处 BusType switch、EnumLabels.cpp 的 slug/label、ProjectEditorForms.cpp 总线下拉框;
  • 生成物(禁止手改):api-schema.json、sdk-symbols.json、proto-fields.json 通过 spec-0036/0037 生成器再生成;
  • 测试与文档:tst_opcua_wire.cpp(ctest 单测)、tests/integration/test_opcua_driver.py、doc/help/Drivers-OPC-UA.md、示例工程 examples/OPC UA PLC Simulator/。

这份清单同时是仓库信任契约中"文件清单即车道(lane)"的载体(见 trust-contract.md):实现阶段只允许动清单内的文件,任何清单外的修改都要先在对话中明说,而不是悄悄混进 diff;捆绑无关修复、重命名、import 排序进同一个 diff 属于典型的"范围蔓延"错误。

五、Architecture & data flow:数据与控制如何移动

本节要写明数据和控制流经改动的路径:涉及的对象、signal/slot、线程。模板要求引用 architecture.md 索引下的子系统文档(dataflow、io、project、scripting 等),而不是重新推导一遍。

真实样例将 OPC UA 驱动的数据流拆为 9 步:Discovery → Dial(spec 0050 单裁决)→ Browse → Subscribe → Value cache → Publish tick → Decode → Project generation → Diagnostics。每一步都标注具体 API(requestEndpoints、enableMonitoring、readNodeAttributes、publishReceivedData)与线程归属(驱动与 QOpcUaClient 同在 GUI 线程,不触碰流水线线程)。

注意这里的组织方式:每个环节用编号步骤展开,明确输入、触发信号、缓存位置与失败路径。例如 Dial 步骤完整列出 stateChanged(Connected) → reportOpenFinished(true),以及 errorChanged/connectError/Disconnected 期间 → failDial(reason) → reportOpenFinished(false, reason) + ConnectionManager::disconnectDevice(this) 的全部失败分支。这保证评审者不用读代码就能预演一遍运行路径。

六、Hotpath & threading impact:必答清单

模板标注该节为 REQUIRED——即便答案是"无影响"也必须显式回答。这源于仓库对数据热路径的严格纪律(详见 common-mistakes.md 的静默破坏清单)。四个必答问题:

  1. 是否触碰热路径? 热路径指 FrameReader / CircularBuffer / FrameBuilder / Dashboard 绘制 / span 快速通道。若触碰,必须完整阅读相关代码、调用 ss-hotpath,并说明 SPSC、Qt::DirectConnection、no-alloc、slot-pool、cached-flag 规则如何被保持,以及 --benchmark-hotpath 的验证计划。
  2. 是否新增跨线程 signal/slot? 是/否 + 连接类型及原因。热路径上两端都在主线程却用 Queued 连接,会在 10 kHz 以上因队列满而丢帧。
  3. 是否为缓存的 hotpath flag 新增输入? 如 m_operationMode、m_anyAsyncSink、m_captureLatestFrame、m_streamAvailable。热路径读取的是缓存标志而非实时 getter,漏接变更信号会让缓存静默失效——帧永远到不了仪表盘,或导出静默停止。必须说明新信号如何接入缓存刷新(updateStreamAvailable / BlockPublisher::refreshSinkFlag 等),并以 Qt::DirectConnection 连接(queued 刷新会比已在流动的帧滞后整整一个事件循环回合)。
  4. 时间戳所有权:确认源头在驱动边界盖戳,下游不得重新盖戳;导出/报表工作线程也不得自行 steady_clock::now(),而应使用共享时间戳帧上的偏移换算。

真实样例给出的答案是"触碰热路径?否;新增跨线程 signal/slot?否;新增 hotpath flag 输入?否 + 时间戳规则",并补充:--benchmark-hotpath 门禁不受影响(新模板不在基准集合内,改由 ctest 单测覆盖),解析循环带 SS_ASSERT_HOTPATH 断言,除 storeAt 的 QString 赋值外零分配。

七、Data model & persistence:数据模型与迁移故事

本节回答数据如何持久化、旧文件如何兼容。模板点名的关注点包括:

  • Frame.h 的 Keys:: 新增(单一事实来源);
  • schema/writer 版本号提升;
  • widgetSettings / 项目 JSON 形态;
  • Sessions 数据库 schema;
  • legacy-alias 回退;
  • 为所有读取旧文件的路径写明迁移故事。

真实样例的要点:"无新 Keys::"——标签列表与认证模式搭车在 source 的 connectionSettings 对象(现有 SourceConn)里,schema 放在 frameParserParams;凭据复用 MQTT::CredentialVault(SimpleCrypt 设置保险库),通过给设置键加 "opcua/" 前缀作用域避免与 MQTT 条目冲突,而不是新建第二个保险库类;线协议版本由帧首的 kWireVersion 字节承载,解码器拒绝不匹配并计数。这些决策都直接服务于"不新增持久化面、不破坏旧文件"。

conn-settings 的形态也在方案中给出,例如:

{"endpointUrl": "...", "endpointIndex": 0, "authMode": 0, "username": "",
 "publishingInterval": 100, "tags": [{"id": "ns=2;s=Plant.Line1.Temp",
 "name": "Temp", "t": "f64", "unit": "°C", "n": 1, "path": "Plant/Line1"}]}

密码从不写入设置(走保险库),这样项目重开时(需求 R13)无需重新浏览地址空间即可恢复标签。

八、API / SDK surface:命令面与脚本可达性

本节覆盖:新增或改动的 API handler(位于 app/src/API/Handlers/,在 CommandHandler::initializeHandlers() 中注册)、EnumLabels.cpp 的 slug/label、生成的 SDK、脚本 apiCall 可达性;商业功能放在 #ifdef BUILD_COMMERCIAL 之后。

真实样例列出了完整命令面:opcua.getConfiguration、opcua.setEndpointUrl、opcua.discoverEndpoints(异步、5 秒超时)、opcua.getEndpoints、opcua.setEndpointIndex、opcua.setAuthMode、opcua.setUsername、opcua.setPassword、opcua.setPublishingInterval、opcua.browse {nodeId}(单层,返回带类型/访问权限的子节点)、opcua.getTags/setTags/addTag/removeTag/clearTags、opcua.generateProject、opcua.getStatus;并注明 slug opcua、label OPC UA、bus_map["opcua"] = 10,全部置于 BUILD_COMMERCIAL 之后;generateProject 前的策略预检遵循注册表层既有模式。API 表面经生成器(spec-0036/0037)再生成,绝不手改——common-mistakes.md 明确记录:手改 Generated TU、proto-fields.json 或重推导 dataset 键都会被 code-verify.py 拦截(api-generated-edited、proto-field-renumbered、registry-parallel-field-map),但拦截发生在浪费编辑之后。

九、QML / UI:界面触点与已知坑位

新组件、供其消费的模型、ComboBox 恢复竞态防护、主题/玻璃表面、字体自动缩放;无界面则写 None。模板点名了 ComboBox restore-race guards——对应 common-mistakes.md 中反复出现的坑:可编辑字段对模型值的实时绑定会在提交回显时导致光标跳变、字段被清空回填、负号被吞(正确做法是仅在失焦时从模型同步,提交时钳制数值边界而非用拦截按键的 validator);同一窗口重复绑定相同 QML Shortcut 序列会触发无人处理的 activatedAmbiguously() 导致按键失效。

真实样例的 UI 规划覆盖:OpcUa.qml 复用 Modbus.qml 的 GroupBox/GridLayout 外观,端点下拉用组件完成时索引同步 + onActivated 写入的恢复竞态防护;禁用端点以禁用调色板渲染并附 tooltip 原因;authMode == 1 时显示主题警告色的未加密凭据横幅;拨号/连接期间面板经既有 StackLayout 门禁锁定。标签浏览对话框为 TreeView 配复选框委托、文件夹三态、类型/访问列、按显示名过滤的搜索框、软上限横幅与"全选可读"。

十、Tradeoffs & alternatives considered:把决策记录在案

模板要求:评审者可能有不同看法的决策要提前摆出,格式为"决策 | 备选 | 选定及一句理由",且要推荐而非枚举,但也要记录被否决项,避免评审重复争论。真实样例记录了 7 项决策,例如:

决策 备选 选定 + 理由
帧编码/解析器 (a) Modbus 式快照帧 + 生成 Lua;(b) 增量帧 + 新 opcua 原生 latch 模板;(c) CSV 文本 + delimited 模板 (b)。无需随标签列表维护生成代码;走 Native span 通道而非 64 kHz Lua 层级;字符串以 QString 原生 latch;增量使 2048 标签帧保持小巧。"镜像 Modbus"的前提不成立:Modbus 早于原生模板存在
发布节奏 每次数据变更即发 vs. 每个发布定时器发一帧 定时。订阅会在一个发布周期内投递 N 次通知;每周期一帧把 GUI→流水线流量限制在命令速率,并契合 spec 的"单一更新率"
订阅分组 每标签一个 QOpcUaNode 用 enableMonitoring vs. 裸 QOpcUaClient 批量 API 每节点。Qt 会把相同监控参数的节点合并进同一订阅;节点 API 还免费提供 sourceTimestamp(attr) 与 valueAttributeError()
凭据存储 带作用域复用 MQTT::CredentialVault vs. 新建 OpcUa 保险库类 复用 + 作用域前缀。一个加密保险库、一个 SimpleCrypt 密钥;把类移出 MQTT/ 越界

"记录被否决项"的价值在于:评审者读到 (a)/(c) 时知道它们已被考虑并因何被否,不必重新论证。

十一、Risks & mitigations:静默破坏类别自查

列出可能回归或破坏的点及防御手段,必须包含 common-mistakes.md 中本改动暴露于其下的静默破坏类别。常见类别包括:热路径上的 mutex/QueuedConnection/QMap::operator[] 隐式插入、跨线程后置时间戳、started 先于 QThread::run() 导致 wait() 超时(须先 thread.quit() 再 wait())、缓存 hotpath flag 漏接刷新信号、QFileDialog::fileSelected 槽内同步重入 Qt(macOS 上须用 QMetaObject::invokeMethod(..., Qt::QueuedConnection) 包裹槽体)、%n 与 .arg() 混用破坏翻译等。

真实样例列出 8 项风险,例如:

  • 卡死的连接按钮:拨号窗口每个失败路径都必须到达 reportOpenFinished(false) 并且 disconnectDevice(this)。缓解:单一 failDial() 漏斗 + 15 秒拨号定时器兜底(无重试、无重拨)+ 连接关闭端口的 pytest 断言 io.getStatus 保持 connecting。
  • 连接/错误栈上的模态框:驱动经 logDriverError 记日志、绝不弹 QMessageBox;唯一的例外是用户点击触发的项目生成确认框(与 Modbus 一致)。
  • QOpcUaClient 在信号在途时被删除:close() 先断开全部客户端信号再 deleteLater;node 对象是 client 的子对象。
  • 服务器时钟偏移:每次连接计算一次偏移映射;时间戳偏离接收时刻超过 5 秒则回退为接收时刻并计入 unstamped(防止时间环回卷,仪表盘时间环永不回卷)。
  • 超尺寸帧:kMaxTags、kMaxStringBytes 与每标签最坏情况预留共同约束帧体;解码器对每个读取按 kMaxBytesPerFrame 边界检查。
  • 枚举顺序:OpcUa 追加在 Mqtt 之后保持既有整数值不变;Hardware.qml Loader 索引与 bus_map 必须用 10;tst_enum_labels 覆盖 slug/label。
  • 生成物漂移:API 表面由生成器再生成,scripts/registry-verify.py 与 code-verify.py --check 列入任务清单。
  • Qt 模块缺失:find_package(Qt6 COMPONENTS OpcUa) 仅在商业块内;GPL 构建从不引用它。

十二、Test & verification plan:把验收标准映射为可执行检查

模板要求把 spec.md 的每条验收标准映射为具体检查,并区分你能运行与维护者运行的两类:

  • 单元(可自行运行):tests/scripts/ 的 JS 解析器用例——列出它们;
  • 集成/安全/性能(维护者运行):pytest tests/...——列出文件及断言内容,并注明需要应用启动且启用 API 服务器;
  • 热路径:触碰热路径时跑 --benchmark-hotpath;
  • 静态检查:提交前 python scripts/code-verify.py --check <files>;交接前 qt-cpp-review;提交前 python scripts/sanitize-commit.py。

真实样例进一步细分:ctest 单测(线协议全类型往返、字符串上限/截断、max-tag 边界、版本字节拒绝、模板 latch 语义——脏子集更新、未知索引忽略、截断条目停止遍历);集成测试清单(test_discover_endpoints、test_connect_anonymous、test_bad_credentials_verdict、test_closed_port_settles、test_browse_tree、test_generate_project_groups_and_types、test_subscription_delivery_rate、test_poll_fallback、test_source_timestamps_in_csv、test_bad_status_keeps_last_value、test_reconnect_after_sim_restart、test_project_roundtrip_no_browse、test_api_surface,每个对应 R 编号需求与 AC 验收标准);示例/图库验证(examples.json 由既有示例测试校验);文档验证(python scripts/documentation-verify.py doc/help/Drivers-OPC-UA.md);CI 矩阵(opcua_sim 模拟器步骤,Windows 支线排除 requires_opcua_sim)。

这些脚本的定位见 scripts.md:code-verify.py 是结构+语气 linter(裸调用即 --check),sanitize-commit.py 是提交前总驱动(chmod → expand-doxygen → clang-format → code-verify --fix → 各类 census 门禁 → black → 文档/声明验证 → 生成器重生成 → 报告再生成),documentation-verify.py 校验 AI 叙述/营销文案,claim-verify.py 校验文档中对仓库路径、file:line 引用、类名、锚点常量的引用是否真实存在。另有四个"对增长设防"的 census 门禁:singleton-census、tu-census、dup-census 与 claim-baseline,均以 --accept 重新播种基线。

十三、与前后文档的衔接:spec 与 tasks

plan.md 不是孤立的:它向上兑现 spec.md 的编号需求(如 R1~R16)与验收标准(AC1~AC11),向下被 tasks.md 模板 拆解为"小、有序、可单独验证"的任务单元。tasks 模板的约定包括:一个任务 = 一次聚焦的可评审变更(超过 3 个文件或需一段话描述就该拆分);每个任务标注 Files/Does/Verify/Deps;最后是整功能的完成定义(Definition of Done)——含"每条验收标准在 spec.md 中达成并勾选""code-verify.py --check 在所有改动文件上干净""diff 是所要求的、且仅此而已,无范围蔓延、无外来文件""spec.md 状态置为 done"。plan 的文件清单正是 tasks 拆解与 DoD 范围核对的依据;/ss-implement 按任务列表自上而下执行并持续更新勾选状态。

十四、写作纪律与常见误区

综合模板注释、spec-driven.md 与 common-mistakes.md,撰写 plan.md 时应遵守:

  • 门禁纪律:上一阶段未获人工批准,不得启动下一阶段;跳步(给未评审的 spec 做方案、给未批准的方案写代码)会让"猜错、晚发现"的失败模式复活。
  • 先读代码再写方案:方案必须基于真实代码而非记忆模型;触点用 grep 确认存在(如 grep -rn "BusType::ModBus" 与 ss-new-driver 清单)。
  • 显式回答热路径与静默破坏问题:这是模板强制的必答项,不是可选项;新增 hotpath flag 输入而不接缓存刷新是"静默破坏"的典型来源。
  • 记录被否决的备选:让评审不必重新争论。
  • 文件清单即车道:清单外的任何修改都要先在对话中提出并获同意。
  • 产物必须保持真实:后续阶段若发现更早文档有误,回改并重新确认,绝不静默偏离——过期的 spec 比没有更糟。
  • 范围判断:规范驱动是非平凡/多文件工作的默认(新驱动、新控件、schema 变更、API 面、任何触碰热路径的改动);打字错误、单行修复、重命名、注释、文档微调这类"小、显然、评审者不会合理偏好另一种做法"的改动直接做,不必套四阶段仪式。
  • 生成物与派生文件:.ts/.qm 翻译、生成器产物、报告文件等由维护者再生成,实现阶段绝不手改。

十五、小结:一份可放行方案的检验清单

对照 plan.md 模板 自检:

  1. Approach 一段话能否让只看摘要的评审者理解"做什么、插在哪、为什么"?
  2. 文件清单是否完整且逐项 grep 验证过,包括每个 switch/列表触点与生成物?
  3. 数据流是否按步骤展开,失败路径与线程归属是否明确?
  4. 热路径四问是否全部显式作答?
  5. 数据模型是否说明了持久化形态、版本与旧文件迁移故事?
  6. API/QML 面是否完整,商业功能是否在 BUILD_COMMERCIAL 之后?
  7. 权衡表是否记录了被否决项与理由?
  8. 风险表是否覆盖本改动暴露的静默破坏类别?
  9. 测试计划是否把每条验收标准映射为可运行检查,并区分自跑与维护者跑?
  10. frontmatter 的 status 是否保持 draft,等待人工 approved 后才启动 /ss-tasks?

全部通过后,这份 plan.md 就从"设计草稿"升级为"实现契约",可以作为 tasks.md 模板 拆解和实现阶段验证的可靠依据。

登录后查看全文
Serial-Studio