工程机制 — Harness、Loop 与 Living SDD

01 · 产品生成系统

Engineering 是产品背后的系统

Harness、Loop 与 SDD 不是产品族，而是把现场问题转化为测试增量、可追溯证据、可运行产品和可复用知识的三根协同支柱。

Harness

工程护栏与执行环境：定义约束、工具、角色、环境和质量门禁，让失败可见、执行可重复。

Loop

工程闭环：让意图经过实现、验证、观测和学习，并运行于每个 FDE 阶段内部。

Living SDD

活的双向契约：连接设计意图、实现事实、证据、偏差、已知问题和可复用决策。

02 · 双层 Harness

外层约束，内层执行

Harness 是让工程活动可约束、可执行、可验证、可重复的完整环境，不只是 AI 编码工具或文档模板。

为什么需要 harness，为什么每一次事故都必须变成一条规则：

千丈之堤，以蝼蚁之穴溃；百尺之室，以突隙之烟焚。

千丈长的大堤，因为一个蚂蚁洞而溃决；百尺高的房子，因为烟囱缝里的一缕火星而被烧毁。
《韩非子·喻老》

外层约束 Harness

WHY · WHO · SUCCESS

业务 Harness（Business Harness）

用户和现场问题
价值、范围与成功标准
法规和运行限制
资源与可行性

HOW · BOUNDARIES · PROOF

技术 Harness（Technical Harness）

领域模型和架构决策
接口、协议和组件边界
性能与安全不变量
部署、可观测性和恢复

DELIVERABLE · ACCEPTANCE · REUSE

产品 Harness（Product Harness）

交付物与验收标准
版本和发布状态
已知问题和延期项
复用资产和产品 Profile

内层执行 Harness

Human + AI Agents意图、判断与辅助执行

Repository + SDD版本化代码与共享契约

Tools + Diagnostics构建、分析与仪器

Tests + Review行为、合规、质量与安全

Deployment受控发布与回滚

Field Telemetry + Evidence现场行为、限制与证据

Harness 边界：必须让失败可见。工具输出追溯到代码和环境；自动化测试不能替代台架或现场验证；部署与遥测属于 Engineering；Human 和 AI Agent 服从相同的审查、证据与安全门禁。

03 · 嵌套反馈

一个交付循环，一个工程闭环

外层 Loop 降低产品风险；内层 Loop 让每个增量可实现、可审查、可观测、可修正。

OUTER · FDE DELIVERY LOOP

选择并消减现场风险

Echo
观察现场事实→Delta
验证最高风险假设→Product
稳定并交付→新的现场 Echo

INNER · ENGINEERING LOOP

构建每个可信增量

Specify · 规格→Implement · 实现→Test · 测试→Review · 审查→Deploy / Observe · 部署观测→Update SDD · 回写设计

Specify → Implement

声明意图、约束、接口、验收条件和证据要求，再实现能够推翻假设的最小增量。

Test → Review

使用与主张匹配的验证方法，并审查规格符合性、代码质量、安全边界和事实口径。

Deploy / Observe → Update SDD

收集运行行为、性能和故障，把决策、偏差、证据和已知问题写回活契约。

不是瀑布：Echo 阶段也会构建和测试抓包工具；Product 阶段也可能因现场故障返回 Specify。Loop 表达反馈和证据流，而不是僵化门禁。

第三条回路：交付环与工程环让增量穿过仓库；现场回路（§03.5）把用户症状带进来，并从 2026-09-19 起，把经测试的补丁带出去。

03.5 · 现场回路

触碰用户的那个回路

FDE 的第四项回路实践：支持链对自己迭代。一次 🐞 上报变成带出处的证据、公开的答复、看板卡片，对已排期的 bug，还会变成等待人点头的、经测试的补丁。

FIELD · 支持回路（FDE 实践 4）

上报 → 分诊 → 分类 → 答复/看板 → 实施 → 人工合入

上报
脱敏诊断包→分诊
10 分钟 cron，只读模型→分类
bug · feature · noise→答复 + 看板
公开、可检索、逐行引证→实施
单飞、测试为门→人工合入
main 永不被无人值守触碰

分类	自动动作	边界
noise——环境 / 误报 / 已修复签名	答复用户；看板列「已答复」，终态	无代码工作；答复已在公开答复页
bug，可定位的产品缺陷	答复用户，并自动排期进无人值守实施队列	修它是验证问题，不是产品选择
feature——新能力 / 新参数	答复用户；看板列「待决策」	排期是产品决策；由操作员决定
need_more_info	永不闭环，留在待决策	未答复的上报不允许假装闭环

安全护栏

模型只读；补丁以 unified-diff JSON 契约交付；保护路径（工具护栏 JS、certs/、win/、packaging/、.iss）一律拒绝；单补丁最多 8 个文件；先跑 git apply --check。

隔离

补丁只落在从干净 main 工作区新拉出的 fde/<id> 分支。无人值守进程永不触碰 main；合入是人的动作。

测试门禁

全套 unittest 决定：绿则提交到分支（看板记录 branch@hash 与测试结果行）；红则删除分支、还原工作区并记录原因。

两次加固回路的事故：cron 模型运行器连续两天以 SIGABRT 死亡（一次 Homebrew 升级打断了 bottled Node 的 dylib 链接，现在回路会点名自己的信号死亡）；以及测试夹具曾发布到线上看板（修复：把页面发布收敛为唯一可拦截接缝；完整跑一轮测试后线上页面逐字节不变）。无人值守回路必须让自身的失败可见。

边界：回路曾止于一条已答复的工单，后来止于一个已发布的修复；现在止于一个已审查的分支。判断留给人，收束为两个动词——决策（每个 feature 一次排期备注）与合入（接受一个已测试分支）。证据决定契约能否存活；「算不算数」永远不委托。线上入口：FDE 看板与答复页；操作入口三条命令——fde_board.py list|decide|implement。

是一个节拍栈，不是单条回路

分诊 · 10 分钟 → 答复 · 当天 → 实施 · 小时级（单飞） → 发布 · 天级 → 免疫 · 永久

系统的学习速率由「能捕捉每一类事故的最快回路」决定。现场回路补上了最外侧的周期：那些永远不会出现在仓库里的类别，没有声卡的虚拟机、USB 重枚举、macOS 权限弹窗、Gatekeeper。

04 · 活的双向契约

SDD 连接工程意图与工程事实

软件设计文档既指导实现，也由实现校准。规划架构与观测到的成熟度必须显式分开。

设计方向

意图 · 约束 · 决策

系统为何存在、拥有何种边界、哪些质量属性重要，以及为什么选择某种架构。

→ SDD ←

实现事实

代码 · 测试 · 部署 · 现场证据

实际存在什么、如何验证、在哪里运行、发生过什么故障、还有哪些限制。

显式生命周期状态

planned

已规划，尚未实现。

implemented

已实现，验证范围仍有限。

tested

通过明确的自动化或模拟测试。

bench-verified

已通过实物台架验证。

field-verified

已在目标运行环境现场验证。

released

已公开发布或投入生产运行。

deferred

已明确延期并保留边界。

known-issue

已知问题，绝不表述为完成。

不能自动升级：1897 项自动化测试不能证明全部电台已经现场验证；服务端通过不能关闭原生客户端 PTT 缺陷；固件完成不能证明 PCB 或 RF 台架。

最小证据记录

Claim · Source artifact · Version / commit · Environment · Verification method · Result · Limitations · Date

缺少这些字段，状态标签就是没有溯源的主张。

05 · 协同

三种结构，一个学习系统

Harness 约束执行，Loop 产生证据和反馈，SDD 保存并持续修订共同契约。

Harness 没有 Loop

只有工具和规则，系统不会学习。

Loop 没有 Harness

迭代可能很快，但结果不可重复、不可审计。

SDD 没有现场 Loop

文档会成为过期预测。

Loop 没有 SDD

知识停留在个人、终端或聊天记录。

Harness 没有 SDD

Agent、测试和部署缺乏共享语义与验收标准。

06 · 跨产品证据

同一体系，五种工程边界

矩阵展示 Engineering System 如何适配每个产品族，不用于产品排名。

产品族	Harness 重点	Loop 突破	SDD 作用	Engineering 证据
MRRC Universal	Hamlib、服务端权威、Web/PWA	现场网络与状态漂移反馈	固化通用电台边界	已发布和现场运行证据
MRRC Direct USB	USB、机型后端、客户端安全门禁	FT-710 垂直验证 → Modern 平台	提炼 RadioBackend 与 RadioCapabilities	FT-710：439 项测试；Modern：1897 项测试。实机验收单列；FT710Mobile P0 PTT 仍为已知问题。
SunMRRC	抓包、DSP、媒体诊断、原生客户端	未知协议 → Direct-IQ 产品	持续同步协议、媒体和安全契约	服务端、Web 与 SunsdrMobile 客户端分别取证
MRRC-FT8	时钟、音频、工作流状态、TX 保护	现场 QSO 周期驱动状态机演化	分离公开发布和 SDD V1.8 现场演进	发布证据与后续现场演进不是同一工件
EFHW	固件、传感器、舵机、RF 台架	测量—执行有界搜索	区分设计、固件、PCB、台架和现场状态	V3.0 设计/固件完成；PCB 和台架验证待完成

证据规则：能力与成熟度相互独立。功能可以存在而现场证据尚不完整；一个已发布子系统不能把成熟度借给另一客户端或硬件 Profile。

07 · 工程成熟度

从临时活动到可复用证据

成熟度描述工程体系，不评价产品优劣或团队价值。文档数量和测试数量都不能单独提升等级。

Ad hoc · 临时

知识存在于个人操作和临时记录。

Repeatable · 可重复

已经有基础 Harness 和可重复执行路径。

Traceable · 可追溯

规格、代码、测试、发布和证据能够关联。

Evidence-driven · 证据驱动

主张包含来源、环境、方法、结果和限制。

Reusable · 可复用

经过验证的架构、约束和资产可跨产品迁移。

看似快速的工程反模式

文档替代验证

再详细的 SDD 也不能证明硬件行为。

测试数量替代证据

覆盖数量不能证明环境、范围或实机验收。

AI 生成替代审查

快速输出仍需规格、质量、安全和溯源门禁。

发布替代现场安全

软件包可以发布，但某个场景或客户端仍可能未经验证。

SDD 停止接收反馈

忽略实现和现场证据的契约会变成虚构。

设计目标冒充完成

planned、implemented、tested 和 field-verified 是不同陈述。

工程附录

SDD 语义映射

业务 Harness

Executive Direction
System Context
Non-functional Requirements
Use Cases
Feasibility

技术 Harness

Subject Area / Domain Model
Architecture Decisions and Overview
Service and Component Models
Operational Model

产品 Harness

Project Definition
Acceptance Criteria
Version / Evidence History
Known Issues
Reusable Asset Catalog

项目可以采用不同章节编号；语义职责、生命周期状态和证据字段才是稳定契约。

最小证据记录模板

Claim / 主张：
Source artifact / 来源工件：
Version / commit：
Environment / 环境：
Verification method / 验证方法：
Result / 结果：
Limitations / 限制：
Date / 日期：

Engineering 审查清单

现场问题与成功条件是否明确？
控制权、状态所有者、接口和安全约束是否命名？
实现是否符合 SDD，或偏差是否已经记录？
每个成熟度主张是否注明方法、版本、环境与限制？
自动化、模拟、台架、现场和发布结果是否分开？
部署是否产生必须回写 SDD 的新证据或新 Echo？
哪些结果可复用，复用关系是否准确分类？