报告数据结构：DiagnosticReport 的字段与稳定性承诺

connproof diagnose <目标> --format json（各检测子命令均支持）输出的报告是给程序读的：客服系统解析它自动分类工单、脚本读它判断检测结果、监控拿它做对比。这篇文档是接入方需要的全部结构说明。

稳定性承诺

顶层字段 reportVersion（当前为 1）标记结构版本。同一版本内只增不删不改：新增可选字段不升版本，任何破坏性变更（删字段、改语义、改类型）必须升版本并在 CHANGELOG 记录迁移说明；
错误码（findings[].code）永不变更含义；
枚举值（status、severity）的现有取值永不移除。

接入建议：按字段名取值、容忍未知新字段、对 reportVersion 做前置检查。

顶层结构

json

{
  "reportVersion": 1,
  "toolVersion": "0.1.0",
  "startedAt": "ISO 8601 时间戳",
  "completedAt": "ISO 8601 时间戳",
  "environment": { "...": "环境快照" },
  "target": { "kind": "host|url|subscription|local", "value": "目标", "port": 443 },
  "findings": [ { "...": "见下" } ],
  "summary": { "...": "统计与结论" },
  "privacy": { "...": "脱敏元数据" },
  "redactionApplied": true
}

environment 包含 nodeVersion、platform、osRelease、arch、timezone 与 proxyEnvDetected（布尔，不含代理变量的值）。

finding 结构

每条 finding 是"一项检测 + 其规则上下文"的合体：

字段	类型	说明
`code`	string	稳定错误码，如 `TLS-002`
`slug`	string	文档 slug
`title`	string	英文报错原文
`status`	enum	pass / fail / warning / skipped / unsupported / inconclusive
`severity`	enum	info / low / medium / high / critical
`summary`	string	中文一句话结论
`evidence`	array	证据列表，见下
`likelyCauses`	string[]	按概率排序
`recommendedActions`	string[]	可执行步骤
`docPath` / `docUrl`	string	站内路径与完整文档链接
`applicablePlatforms`	string[]	windows/macos/linux/android/ios
`lastVerified`	string	YYYY-MM-DD
`ruleVersion`	number	规则内容版本

注意：pass 状态的 finding 也携带 code——它引用该检测层的代表性规则，含义是"针对这类故障检查过，未发现"。判断整体结果请用 status 而不是 code 的有无。

evidence 结构

json

{
  "label": "TLS 握手",
  "value": "成功，TLSv1.3，耗时 63 ms",
  "source": "tls",
  "timestamp": "ISO 8601",
  "redacted": false,
  "details": "可选的补充说明"
}

redacted: true 表示该条的 value/details 被脱敏模块改写过。

summary 与 privacy

summary 含六种状态各自的计数、total、失败中最高的 highestSeverity（无失败时缺省）与中文 conclusion。快速判断可用：summary.fail > 0 即存在确认故障。

privacy 含 redactionApplied（布尔）、redactedCategories（本次命中的脱敏类别数组，如 ["token","url-query"]）与固定的中文 statement。顶层 redactionApplied 是它的镜像，方便浅层读取。

接入示例

用任意 JSON 工具消费，例如判断是否有高危失败：

const report = JSON.parse(output);
const critical = report.findings.filter(
  (f) => f.status === 'fail' && (f.severity === 'high' || f.severity === 'critical'),
);
if (critical.length) console.log(critical.map((f) => f.code)); // ["TLS-002"]

结构由 @connproof/shared-types 的 TypeScript 类型定义权威描述，TS 项目可直接引用该包获得完整类型。

报告数据结构：DiagnosticReport 的字段与稳定性承诺 ​

稳定性承诺 ​

顶层结构 ​

finding 结构 ​

evidence 结构 ​

summary 与 privacy ​

接入示例 ​