LobeHub Acceptance 跨端证据契约全解析：8 种证据介质、提交命令与安全边界

2026-09-07 19:36:44作者：俞予舒Fleming

本指南以 acceptance 内置技能的证据契约参考文档为主体，讲解 LobeHub 的 Agent 交付验收体系中"一份证据如何被采集、定型与提交"的完整规则：八种证据介质的选用时机、lh acceptance run result submit 命令行参数、音频与双文本证据的特例要求、来源标注（Provenance）以及工件安全红线。读完你可以独立判断一次验收轮次中每个检查项该产出何种证据、用 --file 还是 --content、如何填写 --by 与 --desc，并理解声明了 requiredEvidence 的检查为何"没有附件就不能通过"。

1. 这份契约在整个 Acceptance 体系中的位置

证据契约（Cross-surface evidence contract）是 acceptance 技能中被所有验证端面（surface）共享的参考文档之一。技能整体遵循如下执行主线：

author (or discover) the plan  →  pick the surface  →  capture evidence  →  publish the round  →  self-check coverage

证据采集命令归属于所选端面各自的指南：CLI/后端看 surfaces/cli.md，Web/Electron 看 surfaces/web.md、surfaces/electron.md，macOS 原生与 iOS 模拟器分别看 surfaces/native.md、surfaces/ios-simulator.md。证据文档第一条规则正是：不要为了学会如何提交工件而去加载其他端面的指令——"怎样采集"归属端面指南，"什么是合法证据"归属这份契约。

这一点可以从 index.ts 的资源装配得到印证：evidence.md 与 SKILL.md、各端面指南被一同注册为 resources，其中 references/evidence.md 承载共享契约，而采集命令分散在各自 surface 指南中。

2. 八种证据介质与选用时机（Evidence media）

契约把证据介质严格限定为八种类型，每种都有明确的"何时使用"判定：

类型	使用时机
`text`	命令输出、日志、聚焦的请求/响应数据，或计算型断言能够证明该标准
`markdown`	面向评审者的叙述性文字（推理说明、结构化发现）应以正文形式呈现
`dom_snapshot`	结构化内容比像素更强、更小
`screenshot`	已稳定的视觉状态、布局或原生渲染本身即是主张
`gif`	短时状态需内联渲染，通常不超过约 10 秒
`video`	更长的动画、转场、手势或多步流程需要播放器与更好的压缩
`audio`	交付物是用户听到的东西——TTS 输出、语音回复、提示音
`transcript`	对话、事件流或请求日志本身就是证明

2.1 按扩展名自动判型：证据如何被分类

在报告摄取（lh acceptance run ingest）路径中，证据文件并不强制手填类型，而是由 evidenceTypeForFile() 按扩展名自动推断，见 verifyHelpers.ts：

gif → gif；png/jpg/jpeg/webp/svg/bmp → screenshot
mp4/webm/mov/m4v → video
音频先于文本兜底判断：mp3/wav/m4a/aac/flac/ogg/oga/opus/aiff/aif/wma → audio
html/htm → dom_snapshot；md/markdown → markdown；其余一律回退为 text

源码注释点出了这段顺序的意义：在没有 audio 类型之前，无法识别的二进制会被错误落到 text，导致一个 TTS 片段被发布成"不可读、不可播的 blob"。这一行为有专门的测试锁定，见 verify.test.ts：tts-zh.mp3、reply.WAV、voice.m4a、tone.opus 均应判为 audio，flow.webm 判为 video。

3. `requiredEvidence`：缺件即 `uncertain` 的硬规则

在 SKILL.md 中有一条主契约：一个声明了 requiredEvidence 的检查不能仅凭 Agent 的文字通过——缺失的工件会把该检查标记为 uncertain 并挂起交付。因此契约里"介质类型是绑定的"不是建议，而是发布系统的判定前提。

对应地，在终局交接（Final handoff）阶段，技能要求对每个带 requiredEvidence 的检查逐一核对：声明过的每个 type 至少要出现一次，并把覆盖结果与验收链接一并汇报，否则无论工作本身多好，交付都停留在 uncertain。

4. 音频交付物：把"声音本身"交上去

audio 是八种介质中最容易被误解的一种，契约单独成节给出三条理由：

声音无法用文字验证；
波形截图只能证明"存在一个文件"，不能证明内容正确；
必须上传产物本身（用 --type audio），由验收页面提供播放器供评审者试听。

文档给出了标准提交命令，这里完整保留并标注每个参数：

# 生成的文件就是证据——附上该功能实际产出的工件，
# 而不是转码结果或播放器截图。
lh acceptance run result submit --operation "$OPERATION_ID" --item "$CHECK_ITEM_ID" \
  --type audio --file ./out/tts-zh-female.mp3 --by program \
  --desc "TTS output for 「今天天气不错」, zh-CN female voice, 2.4s"

配套约束包括：

mp3/wav/m4a/aac/flac/ogg/opus 按扩展名可识别，因此 acceptance run ingest 会自动把它们归类为 audio；
引用前先听一遍：确认片段非静音、内容正确（时长 + 一遍转写，或频谱检查）——空文件或截断文件在文件列表里和正常文件看起来一模一样；
当主张是关于"说了什么"（输入文本、声音/模型、实测时长）时，给片段搭配一段短的 text 工件：播放器证明它能播，文本工件让它可以审计；
捕获产品实际产出的东西。带系统音频的屏幕录制只是"UI 在正确时机播放了它"的兜底方案；要证明"输出正确"，请附上文件本身。

命令的 --type 选择在 submit 命令的参数装配中定义，result submit 的定位是"一次调用完成检查结果 upsert 并附加证据"（见 acceptanceRun.ts 的命令描述）。

5. 非可视化行为的双文本证据

对于 CLI、API、后端、策略、安全与迁移类主张，光凭一段文字往往不够，契约要求同一个检查上提交两份彼此独立的 text 工件：

推理工件（reasoning artifact）：主张、前提或威胁模型、方法、通过标准、解释与局限；
执行工件（execution artifact）：精确的命令或请求、相关原始观测、退出/状态值，以及对照通过标准的简短映射。

两条硬约束不可省略：

两份工件都必须放在**当前不可变轮次（immutable round）**内；
不要要求评审者拿旧轮次的解释去拼接新一轮的执行输出。

"轮次不可变"本身是 SKILL.md 的核心规则：已发布的轮次是永久记录，改完代码后绝不向旧轮次重提交，而是把复验发布为下一个轮次，让验收页面展示演进过程。

6. 文件还是内联：`--file` 与 `--content` 的取舍

证据既可随文件上传，也可直接内联为文本。文档给出两条选择规则：

--file 用于二进制工件与较大的文本/DOM/transcript 文件；
--content 用于短的文本断言；
二者必须恰好传一个（pass exactly one of --file and --content）。

# File artifact captured by the selected surface.
lh acceptance run result submit --operation "$OPERATION_ID" --item "$CHECK_ITEM_ID" \
  --type "$EVIDENCE_TYPE" --file "$ARTIFACT_PATH" --by "$PROVENANCE" \
  --desc "Observed state after the planned action"

# Short text assertion.
lh acceptance run result submit --operation "$OPERATION_ID" --item "$CHECK_ITEM_ID" \
  --type text --content "$ASSERTION_OUTPUT" --by cli \
  --desc "Machine-readable assertion output"

"短"不是口头约定，而是有实现边界：在 verifyHelpers.ts 中，只有 dom_snapshot/markdown/text/transcript 四种文本类介质允许内联，且上限为 INLINE_TEXT_EVIDENCE_LIMIT = 5000 字节；inlineTextEvidenceForFile() 会检查内容不含二进制 NUL 字节、能按 UTF-8 解码且长度小于 5000 字节才返回内联内容，否则走文件上传通道。这也解释了为何契约同时要求描述（--desc）要事实化：识别动作、观测到的状态与相关目标即可，除非明确要求，否则不要把结论性判定写进描述——结论应由评审者根据工件本身作出。

7. 来源标注 Provenance（`--by`）

每个工件都要标注"谁产的"。契约规则：

--by 的值应为所选端面指南中命名的生产者；
未经修改的工件用直接采集源；
确定性测试、脚本或媒体转换用 program；
绝不从文件扩展名推断来源——一个由脚本渲染出的 PNG 依然是 program 产物，而不是浏览器截图。

从命令装配可见可选值与默认值：--by 的取值范围是 agent-browser | cdp | cli | program | llm_judge，默认 cli（见 acceptanceRun.ts）。端面指南给出了更细的约定，例如 CLI 端面在 surfaces/cli.md 中规定：命令 stdout 用 cli，你运行过的脚本/测试用 program。

另一处实现事实可作旁证：在 ingest 摄取路径中，上传证据的代码统一以 capturedBy: 'cli' 记录，并按扩展名自动判型、优先内联、必要时调用 uploadLocalFile 上传；单件工件上传失败不会中断整次摄取——它只是跳过该工件并告警，因为会话、结果与报告才是主交付物。

8. 工件安全：红线清单

证据是给人类评审者看的，因此内容边界由人审标准决定，契约给出四条安全守则：

引用前检查每一个图片、片段与生成的文档；
绝不上传凭据、Cookie、令牌、私有用户数据、无关主机窗口或通知；
优先提交聚焦的工件，而不是未过滤的日志或全会话录制；
提交衍生图表、拼贴图、GIF 或经过编辑的对比图时，保留原始素材。

这一安全要求与端面指南互相呼应——CLI 端面同样要求剥离输出中的令牌/密钥后再上传（见 surfaces/cli.md）。

9. 从契约到完整工作流：一次可落地的自检清单

将上述契约放进 acceptance 技能的完整执行上下文，一份合规的证据应同时满足：

类型匹配：介质类型与检查声明的 requiredEvidence 完全一致，不降级替代；
双件齐备：非可视化行为同时有推理工件与执行工件，且都在同一不可变轮次内；
来源可信：--by 按端面指南标注，program 仅用于确定性测试/脚本/媒体变换；
描述事实化：--desc 只描述动作、状态与目标，不预判结论；
内容干净：无凭据、无无关窗口、无未聚焦的原始日志，衍生素材保留原件；
覆盖可证：终局时对每个 requiredEvidence 检查核对每个声明类型至少出现一次，并在最终回复中给出验收页面地址（形如 …/acceptance/<acceptanceId>，可附 ?r=<roundIndex> 定位该轮固定快照）与覆盖结果，例如 Coverage: 2/2 criteria, all required evidence uploaded。