# dsh-forge 架构文档

> 版本：0.1.14（正式版）· 最后更新：2026-09-03

## 1. 总览

dsh-forge 是 DeepSeek Harness（dsh）的**插件组合分析**插件。它以只读方式检视 harness 的插件组合树，
输出依赖关系、冲突检测、风险评估、可视化与升级建议，辅助开发者做出安全的组合变更决策。

### 设计原则

- **分析只读**：所有分析计算只读；`simulate_combination` 操作虚拟副本；报告生成与历史归档为**可选落盘**（`writeReport` → `reports/`，`archive_snapshot` → `data/history/`），路径可经 `DSH_FORGE_REPORTS_DIR` / `DSH_FORGE_HISTORY_DIR` 覆盖。
- **零依赖引擎**：`core/` 仅使用 Node.js 内置 API（fs / path / module），不依赖任何第三方包。
- **诚实声明**：静态扫描结果标注 `confidence` / `evidenceTier`，未校准数据标 `calibrated: false` + 免责声明。
- **三层分离**：分析引擎（core）↔ 插件壳（src）↔ 客户端 UI（ui-plugin）职责清晰，可独立测试。

## 2. 三层架构

```
┌─────────────────────────────────────────────────────────┐
│                    Harness (dsh web)                      │
│  ┌───────────────────────┐  ┌──────────────────────────┐ │
│  │   dsh-forge (host)    │  │  dsh-forge-ui (client)   │ │
│  │   src/index.js        │  │  ui-plugin/lib/client.js │ │
│  │   ┌─────────────────┐ │  │  ┌────────────────────┐  │ │
│  │   │  14 tools       │ │  │  │ sidebar 入口       │  │ │
│  │   │  (defineTool)   │ │  │  │ modal + iframe     │  │ │
│  │   └────────┬────────┘ │  │  │ dashboard.html     │  │ │
│  │            │          │  │  └────────────────────┘  │ │
│  │   ┌────────▼────────┐ │  └──────────────────────────┘ │
│  │   │  core/ (引擎)   │ │                               │
│  │   │  30 个纯逻辑模块 │ │                               │
│  │   └─────────────────┘ │                               │
│  └───────────────────────┘                               │
└─────────────────────────────────────────────────────────┘
```

### 2.1 core/ — 分析引擎

零依赖纯逻辑层，可脱离 harness 独立运行（`node --input-type=module -e "..."`）。

| 模块 | 职责 | 关键导出 |
| --- | --- | --- |
| `composition.js` | 组合源发现 + YAML 解析 + 生态收集 | `collectEcosystem`, `discoverSources`, `mergeRows` |
| `truth.js` | dump-config 真相源（三态降级） | `loadTruthEcosystem` |
| `analyze.js` | 依赖图构建 + 风险评估 | `buildGraph`, `assess`, `riskScore` |
| `conflicts.js` | 冲突检测引擎 | `checkConflicts`, `scanToolNames`, `scanServices` |
| `scope.js` | 作用域感知（global vs per-agent） | `scanScopeHints` |
| `calibration.js` | 运行期事件校准 | `createCalibration`, `staticCalibration` |
| `leaks.js` | 非可逆副作用泄漏扫描 | `scanLeaks` |
| `semver.js` | SemVer 解析 + 区间满足性 | `satisfies`, `parseVersion`, `compareVersions` |
| `upgrade.js` | npm registry 升级检查 | `checkUpgrades` |
| `audit.js` | 逐行配置审计 | `auditConfiguration` |
| `diff.js` | 快照差异对比 | `diffCombinations` |
| `simulate.js` | 组合模拟 | `simulateCombination`, `applyOps` |
| `plan.js` | 升级路径预演（离线：proposeUpgrade 范围/阻断；simulateUpgrade 版本上移编排；cloneWithVersion 版本克隆） | `proposeUpgrade`, `simulateUpgrade`, `cloneWithVersion` |
| `visualize.js` | 多格式可视化 | `html`, `mermaid`, `asciiTree` |
| `dashboard.js` | 交互仪表盘数据构建 | `dashboard`, `buildEmbedData` |
| `skins.js` | 仪表盘皮肤 token（light/dark 双主题，零依赖纯逻辑） | `SKINS`, `DEFAULT_SKIN`, `skinCssVars` |
| `history.js` | 快照存档与加载 | `archiveSnapshot`, `listHistory`, `loadHistory` |
| `report.js` | Markdown 报告生成 + 写入归档（报告/history 路径可配置，history 失败可见） | `buildMarkdownReport`, `writeReport`, `gates`, `reportsDir`, `historyDir`, `pkgVersion` |
| `stats.js` | 历史趋势统计 | `historyStats` |
| `presets.js` | 预设对比 | `comparePresets`, `readPreset` |
| `verify.js` | 行级装载预检 | `verifyRows` |
| `mode.js` | TUI/Web/check 四层证据决策（启动入口/环境/场景/复杂度） | `decideUiMode`, `hasDesktop`, `decideAfterPortProbe` |
| `suggest.js` | 补丁建议生成 | `suggestPatch` |
| `knowledge.js` | 知识库 + 已知模式 + 废弃扫描 | `knownPatterns`, `scanDeprecations` |
| `errors.js` | 统一错误反馈（归一化/聚合/预检/渲染） | `buildFeedback`, `normalizeFeedback`, `preflight`, `renderFeedback` |
| `evidence.js` | 证据元数据（INV-6/A-2）：稳定 finding_id + 置信度上限 + schema 校验 | `makeFindingId`, `attachFindingIds`, `capConfidence`, `validateFindings` |
| `evidence-fusion.js` | 证据融合（A-1 三态 + A-3 可行动 + INV-3 只降不清除） | `fuse` |
| `gate.js` | 闸门裁决（方向 4）：冻结 pass 语义（severity-only）+ 追加 lever/blockedBy/degraded；可配置策略（severity/tier/confidence→block\|warn\|allow），tier 只收紧、无 policy 时逐字节兼容冻结路径 | `computeGate`, `gateFromFindings`, `severityBlocks`, `validatePolicy`, `resolveVerdict`, `stricter` |
| `runtime-calibration.js` | 运行时校准（A-4 滑窗 + INV-2 时序边界 + A-2 关联键） | `createRuntimeCalibration`, `staticRuntimeCalibration` |
| `web-server.js` | Web 面板共享服务（CLI 与 harness 壳复用的 3060 数据通道 + CORS/端口探测/浏览器打开） | `createWebHandler`, `startWebServer`, `probePort`, `openBrowser` |

`core/index.js` 是门面模块，统一 re-export 全部公共 API，并提供两条分析管线与 `saveSnapshot()` / `loadSnapshot()` 快照序列化：

- **`runAnalysis(opts)`（同步）**：一站式管线 `collectEcosystem → buildGraph → checkConflicts → assess → scanLeaks → attachFindingIds → capConfidence → fuse → buildFeedback`；数据来自 `datasetPath` 快照或即时扫描，供测试与离线脚本使用。
- **`runAnalysisAsync(opts)`（异步，CLI/插件壳/Web 统一入口）**：与工具路径（`selectEco`）同一真相源偏好——优先经 `loadTruthEcosystem` 取 `dsh --dump-config` 真实快照（dump-config），取不到才回退 `collectEcosystem` 扫描（scan）；`check` / `plan` / `web` 与 auto-web 面板均经它装载，避免在可取得 dump 时静默降级。

### 2.2 src/ — 插件壳

| 文件 | 职责 |
| --- | --- |
| `src/index.js` | cordis 插件入口：`apply(ctx, config)` → 创建 calibration → 遍历 14 个工具工厂 → `defineTool` 注册；注册后 `void startAutoWeb(cfg)` 同步拉起共享 Web 面板（3060，不自动开浏览器） |
| `src/tools/index.js` + `src/tools/*.js` | 14 个工具定义（每工具一文件，共享 `common.js`）：name / description / parameters(JSON Schema) / output.schema / execute / render |

工具注册流程：
```
apply(ctx, config)
  → createRuntimeCalibration(ctx)   // 运行期事件订阅 or 静态降级
  → probeRuntime(ctx)               // 探测 22 个 harness 服务
  → for each factory in ALL_TOOLS:
      ctx.tools.register(defineTool(factory(cfg)))
```

每个工具的 `execute` 方法通过 `selectEco(args, config)` 获取生态数据，再委托 `core/` 对应模块计算。

> **双入口职责（勿混淆）**：`src/index.js`（cordis 插件壳）只负责把 14 个工具注册进 harness，并持有运行期探测与启动预检；`core/index.js`（零依赖分析引擎门面）是 CLI 与全部测试的唯一事实源。新增分析能力一律进 `core/` 并在 `core/index.js` re-export；只有需要暴露给 harness 作为工具时才在 `src/tools/<tool>.js` 新增定义。CLI（cli/dsh-forge.mjs）与测试套件 import `core/`，不依赖 `src/`。

### 2.3 ui-plugin/ — 客户端插件

| 文件 | 职责 |
| --- | --- |
| `ui-plugin/index.js` | cordis 客户端插件入口 |
| `ui-plugin/lib/client.template.js` | 源模板：2 个 slot 注册 + modal 组件 |
| `ui-plugin/lib/client.js` | 构建产物（`scripts/build-ui.mjs` 打包，内嵌 dashboard.html） |

2 个 UI 入口 slot：
- `sidebar.footer.action` — sidebar 底部「▦ 插件仪表盘」按钮
- `conversation.chat.turnTail` — 对话流引导卡片

子 slot 注册通过 `ctx.slots.inject(parent, fn)` 等待父 slot 声明后再注册，避免抢跑。


### 2.4 cli/ — 独立双壳入口（默认 TUI，按需 Web）

`cli/dsh-forge.mjs`（package.json `bin.dsh-forge`）复用 `core/` 分析引擎，
按 `core/mode.js` 的四层证据选择形态：

| 命令 | 形态 |
| --- | --- |
| `dsh-forge` | 自动决策：终端内默认 TUI；无 TTY+桌面会话 → Web；CI/管道 → check |
| `dsh-forge tui` | 强制 TUI（零依赖 ANSI；`W` 一键开 Web，`R` 刷新，`Q` 退出） |
| `dsh-forge web` / `serve` | 强制 Web（`node:http` + 10 模块交互仪表盘；缺 client.js 回退自包含 SVG 拓扑；端口占用自动降级） |
| `dsh-forge check` / `ci` | 纯日志或 `--json`，无界面，面向脚本消费 |

TUI 壳与 Web 壳不引入第三方依赖：TUI 用 ANSI 渲染，Web 用 `node:http`
serve `core/dashboard.js` 生成的 10 模块交互仪表盘（缺 `web/dashboard-client.js`
时回退 `core/visualize.js` 的自包含 SVG 页面），保持 core 零依赖与离线可部署。
Web 形态为混合审查：每次请求用当前分析结果新鲜渲染（静态层），live 模式页头提供
`↻ 刷新` 按钮（`/api/refresh` 清除分析缓存后重新分析并返回新嵌入数据，动态层），
静态快照渲染则优雅隐藏该控件。

## 3. 数据流

### 3.1 生态数据收集（selectEco）

```
用户调用工具 execute(args)
  │
  ├─ args.dataset?  ──→ loadSnapshot(file)          // 离线快照模式
  │
  └─ truthSource = auto | dump-config | scan
       │
       ├─ dump-config (首选)
       │    → loadTruthEcosystem({ home, profile })
       │    → dsh --dump-config → 解析生效组合树（含 provenance）
       │    → 成功: 返回 ecosystem + truthSource="dump-config"
       │    → 失败: auto 模式降级到 scan
       │
       └─ scan (回退)
            → collectEcosystem(opts)
            → discoverSources() → 解析 cordis.yml + bundle 补丁 + patch.yml
            → 扫描 node_modules 包清单
            → 返回 ecosystem + truthSource="scan" + warnings
```

> **CLI / 插件壳 / Web 统一入口（v0.1.14）**：工具走 `selectEco()`（上图），而独立 CLI（`cli/dsh-forge.mjs` 的 `loadAnalysisAsync`）、harness 插件壳 auto-web 与 Web 面板 `refresh` 统一经 `runAnalysisAsync()` 装载分析——与上图**同一真相源偏好**：优先 `dump-config`，不可用才回退 `scan`。三处不再各自退化为 scan；`core/web-server.js` 的 `createWebHandler` 已 async 化，`readAnalysis()` 统一 `await` 可能返回 Promise 的分析对象。

### 3.2 冲突检测（check_conflicts）

```
check_conflicts execute
  │
  ├─ selectEco() → eco
  ├─ buildGraph(eco) → graph
  ├─ checkConflicts(eco, { graph })
  │    ├─ 版本冲突: satisfies() 检查依赖 range
  │    ├─ 工具重名: scanToolNames() + scope.js 作用域分级
  │    │    ├─ 全部 scoped → tool-name-scoped-variant (heuristic/info)
  │    │    └─ 含全局 → tool-collision (contract/high)
  │    ├─ 服务覆盖: scanServices() → provide 重复 (impact: "待实证")
  │    └─ 泄漏扫描: scanLeaks() → apply 路径对账 + 知识库排除
  ├─ calibration.snapshot() → 运行期行为基线 (或 null)
  └─ 返回 { conflicts, leaks, calibration, inputScope, truthSource, disclaimer }
```

### 3.3 升级检查（check_upgrades）

```
check_upgrades execute(args)
  │
  ├─ selectEco() → eco
  └─ checkUpgrades(eco, { limit, registry, timeoutMs, concurrency })
       ├─ 筛选 @deepseek-ai/* 包 (limit 默认 40)
       ├─ 并发池 (默认 6) 查询 npm registry /latest
       │    ├─ 主 registry (npmjs.org) 连续失败 ≥2 → 切镜像 (npmmirror)
       │    ├─ 独立超时 (默认 3.5s) → 失败包入 networkFailures
       │    └─ 404 → 该包无 latest (跳过)
       ├─ 比对 installed vs latest → 过滤非升级
       ├─ 阻断预测: satisfies(latest, consumerRange) === false → blockers
       └─ 返回 { candidates: [{ package, installed, latest, blockers, installCmd }], networkFailures, elapsedMs, ... }
```

### 3.4 升级路径预演（plan / plan_upgrade）

`dsh-forge plan --to <pkg@ver,...>`（`src/tools/plan.js` 暴露 `plan_upgrade`）是**离线且确定性**的升级推演：不做行级变更、不改组合、**永不触发 `check` 的 gate-exit**。

```text
plan(e)  [cli --to pkg@ver | plan_upgrade targets]
└─ 全显式版本 → 纯离线：simulateUpgrade(eco, wish)              （确定性，无网络）
└─ 含 @latest   → proposeUpgrade(eco,{fetch}) 走仓库解析后接 simulateUpgrade
simulateUpgrade(eco, wish)
├─ cloneWithVersion(eco, wish)       # 版本级克隆（不触碰 row）
├─ buildGraph + checkConflicts + assess   # before（基线）
├─ buildGraph + checkConflicts + assess   # after（目标）
└─ 返回 { upgraded[], before, after, riskDelta, newResolved,
          rowDiff, verdict, doSteps }
```

- `proposeUpgrade` 出升级范围与 `breaks`（consumer 声明范围拒收）；`breaks` 判定复用 `upgrade.js` 的 `satisfies(version, range)`，保证单一实现。
- ESLint 之外的一切纯函数位于 `core/plan.js`（模块数 28→29），CLI/工具/测试三处复用。

### 3.5 闸门杠杆与置信分层（方向 4）

冻结契约 `gate.pass` 不变（任何 `blocking/high` 即 fail，与置信无关）。`core/gate.js` 在 `pass/blocked` 之外追加透明层：

| gate 字段 | 含义 |
| --- | --- |
| `lever` | `block`（≥1 strict 高置信阻断）\| `degraded`（触发但全部是置信降级证据）\| `advisory`（PASS） |
| `blockedBy[]` | 装载级明细：「因哪条规则拦了谁」——`{ finding_id, rule, finalSeverity, confidence, evidenceTier, capped }` |
| `degraded[]` | `blockedBy` 的子集：scan cap 或低/中置信却达阻断级别，应先用 `dump-config` 复核再 enforce |
| `policyApplied` | 本次是否使用了显式 gate 策略（只有调用方传 `--policy`/`{policy}` 时才出现） |

`projectFinding` 追加 `capped` / `rule` 字段（schema 追加式，不破坏 report@1）。`check` BLOCKED 时文本列出前 8 条阻断明细；report.md 在闸被触发时输出「闸门明细（blockedBy）」表与降级提示。CLI/`report.js::gates` 均复用 `computeGate`（单一实现）。

### 3.5.1 可配置闸门策略（选项 C，`--policy <file.json>`）

显式传入 policy 才改变裁决；未传时走冻结路径（逐字节兼容）。

```json
{ "severity": { "blocking": "block", "high": "warn", "medium": "allow", "low": "allow" },
  "tier": { "contract-source": "block" },
  "confidence": { "low": "warn" } }
```

- 每条 finding：`baseline = severity[finalSeverity]`（缺省：blocking/high→block，其余 allow）；`tier`/`confidence` 维度**只收紧**（`stricter`，block>warn>allow）——降级用 `severity`，权威证据用 `tier` 钉死。
- 有 policy 时 `gate.pass = 不存在 block 裁决`；`gate.blocked` 仍为冻结 severity 计数（报告保留原始红灯）。
- `validatePolicy` 确定性校验（非法 key/value 抛错，CLI 读 `--policy` 失败 exit 2）。
- CLI：`dsh-forge check --dataset X --json --policy policy.json`，`exit 1` 基于 policy 裁决后的 `pass`。

## 4. 真相源三态设计（truthSource）

| 模式 | 数据来源 | 精度 | 降级 |
| --- | --- | --- | --- |
| `dump-config` | `dsh --dump-config` 官方输出 | 精确（harness 实际装载树） | 不可用则报错 |
| `auto`（默认） | 优先 dump-config | 精确 | 失败自动降级 scan + warning |
| `scan` | 源码扫描重建 | 近似（可能偏离） | — |

`core/truth.js` 的 `findDshBin()` 从 8 层候选路径查找 dsh 可执行文件，超时 20s 兜底。

## 5. 测试架构

全部自包含、零本机依赖（mock fetch / mock ctx / DOM-mock / VM bundle）。

| 套件 | 文件 | 项数 | 覆盖 |
| --- | --- | --- | --- |
| 仪表盘结构+交互 | `test/ui-test.mjs` | 77 | workspace 结构 / 默认页（使用引导）/ 页切换 + 搜索/筛选/排序/toggle/增删候选 + 名词解释/悬停提示 + 旧模块引导条/表头详释 + 133 行数据 + live 动态标记回归 |
| 客户端插件 VM 执行 | `test/ui-plugin-test.mjs` | 22 | 2 slot 注册 + locale + 模态开关 + wide/collapsed 渲染 |
| SemVer 回归 | `test/semver-consistency.test.mjs` | 30 | core/semver.js 单一实现 30 用例固定断言 + 防 dashboard 镜像回归 |
| 作用域/校准/泄漏 | `test/review-fixes.test.mjs` | 15 | scope 三态 + mock 事件校准 + 泄漏切片 |
| 证据融合引擎 | `test/evidence-fusion.test.mjs` | 23 | A-1 三态 + A-2 稳定 id + A-3 可行动 + 完整融合矩阵 + tier/confidence 去混淆 + INV-3 绝不清除 |
| 运行时校准 | `test/runtime-calibration.test.mjs` | 25 | A-4 滑窗/基数上限/超限丢帧（可观测）+ INV-2 时序边界（单调时钟）+ 可逆性/dispose 释放引用 |
| 真相源三态降级 | `test/truth-source-degradation.test.mjs` | 17 | INV-4 置信度上限（只降不升、纯函数不突变）+ scan 全局降级 + 64 位 finding_id 哈希 |
| 升级检查优化 | `test/upgrade-opt.test.mjs` | 16 | 并发池 + 超时 + 镜像降级 + 安装命令 + 独立性 + 阻断预测 |
| 错误反馈冒烟 | `test/feedback-smoke.test.mjs` | 40 | FORGE 错误码 / 分级 / 聚合 / 渲染 |
| 空组合 / 泄漏规则 | `test/empty-plugins.test.mjs` | 24 | 空组合边界 + 泄漏规则 |
| 随机子集探索 | `test/exploratory-empty.test.mjs` | 27 | 随机插件池 + 多轮组合一致性 |
| 反馈深度探索 | `test/exploratory-feedback.test.mjs` | 563 | 反馈结构合法 / 分级计数 / 排序稳定 / 确定性 |
| TUI/Web/check 决策 | `test/mode-decision.test.mjs` | 19 | 四层证据决策（命令/环境/场景/复杂度）/ env 一致性 / 端口占用降级 / 场景启发 |
| 分析缓存守护 | `test/cache-behavior.test.mjs` | 7 | 同参命中 / clear 失效 / 文件变更 / live profile patch 变更 / 淘汰 / 快照 stamp |
| 主链路融合回归 | `test/main-path-fusion.test.mjs` | 8 | P0 主路径真正 fuse：runAnalysis 项带 runtimeState/finalSeverity/evidenceTag（离线 not-executed）+ INV-3 不清除 + severity 秩有效 |
| 启发式检测收敛 | `test/heuristic-detect.test.mjs` | 16 | 句柄捕获感知泄漏（已知安全降级 / leak-context / 全部 BARE 规则）+ 动态工具名按包追踪与显式扫描局限 |
| check --json schema 冻结 | `test/check-report-schema.test.mjs` | 10 | P0-3 冻结 check report schema（schemaVersion/inputs/findings[]/gate）+ gate 门禁（high/blocking 拦截）|
| 闸门杠杆/置信分层 | `test/gate-lever.test.mjs` | 12 | 方向 4：computeGate/gateFromFindings 的 lever(block/degraded/advisory)、blockedBy 明细、degraded 分层；冻结 gate.pass 语义保持 |
| 可配置闸门策略 | `test/gate-policy.test.mjs` | 11 | 方向 4（选项 C）：validatePolicy/resolveVerdict 的 severity→baseline + tier 只收紧；契约冲突在 scan cap 下仍 block；severity 降级放行；无 policy 冻结路径逐字节兼容 |
| finding_id 唯一性消重 | `test/finding-id-uniqueness.test.mjs` | 6 | makeFindingId 纳入 involved packages/service/row，区分同类别多条 finding；A-2 message 不变 id（0 碰撞回归）|
| 14 工具快照半集成 | `test/tools-snapshot-smoke.test.mjs` | 14 | 快照驱动调用 14 个工具 + output.schema 最小校验（防 schema/output 漂移），CI 可运行 |
| YAML fail-loud / vm 沙箱 | `test/composition-strict.test.mjs` | 8 | 严格解析接受合法 patch（含 config block scalar、cordis inject 行键）/ 未知行键与顶层条目抛错 / globalThis 逃逸被拒 / dshHomePath 可用 |

测试策略：
- **单一实现回归**：semver-consistency 固定断言 core/semver.js 行为，并守护 dashboard.js 不再内嵌镜像副本
- **VM 真实执行**：ui-plugin-test 用 `vm.createContext` 执行 client.js bundle
- **DOM-mock**：ui-test 用 mock React createElement 模拟仪表盘交互
- **mock fetch**：upgrade-opt.test 用 mock fetch 验证网络逻辑，零真实网络依赖

## 6. 工程资产

| 路径 | 说明 |
| --- | --- |
| `.github/workflows/ci.yml` | CI 模板（Node 22+，运行自包含测试套件；跳过依赖本机路径/真实 harness 的 smoke13.test.mjs） |
| `scripts/generate-dashboard.mjs` | 用当前 dashboard.js 从离线快照重新生成 reports/dashboard.html |
| `scripts/build-ui.mjs` | 构建客户端 bundle（内嵌 dashboard.html 到 client.js） |
| `scripts/mount-ui.mjs` | 挂载脚本（自动探测部署 node_modules；env：DSH_HOME / DSH_DEPLOY_NM / DSH_FORGE_ROOT / DSH_PROFILE_PATCH） |
| `scripts/mount-ui.ps1` | Windows PowerShell 挂载脚本 |
| `pnpm-workspace.yaml` | pnpm workspace 配置 |
| `data/ecosystem.json` | 离线生态快照（`dsh-forge-ecosystem@1` 格式） |
| `data/history/` | 历史快照存档（gitignored，运行期生成；`data/ecosystem.json` 为 versioned 基线） |
| `reports/runtime-verification-checklist.md` | 静态盲区的运行时沙箱验证清单（A 生命周期 / B 事件竞态 / C Seam / D Agent Loop / E 证据规范） |


## 8. 架构设计不变量（Design Invariants）

| 编号 | 不变量 | 违反后果 | 验证方式 |
|---|---|---|---|
| INV-1 | core 层保持离线零依赖，运行时观测逻辑只在 src 插件壳层 | core 无法独立运行，离线审计能力丧失 | CI：纯 Node.js 环境运行 core 测试套件 |
| INV-2 | 运行时校准只观测 dsh-forge 加载之后的事件，不回溯初始化 | 虚假承诺导致漏检，用户信任崩塌 | 文档显式声明 + 测试验证启动时序边界 |
| INV-3 | 运行时未观测到风险仅降级、绝不清除（且未观测三态化，absence≠evidence-of-absence） | 引入新漏检，违反保守性原则 | 单元测试覆盖全部融合降级 + 三态边界（A-1） |
| INV-4 | 真相源降级到 scan 后全局降低置信度上限 | 输出虚假高可靠结果，误导自动化决策 | 自动化测试：scan 模式输出校验 |
| INV-5 | vm 加固仅提升可信配置场景安全性，不用于对抗不可信输入 | 安全边界被突破，代码注入风险 | 安全文档声明 + 威胁模型评审 |
| INV-6 | 所有静态扫描输出必须携带置信度元数据（confidence/evidence），区分推测来源与事实证据 | 证据不可追溯，无法区分误报与真实风险 | Schema 校验：所有 findings 必须含 confidence 字段 |

## 7. 版本策略

- 遵循三位 SemVer（X.Y.Z），使用 prerelease 后缀标识开发阶段（如 `alpha-v0.1.0`）
- hotfix/patch 使用 prerelease 后缀（如 `alpha-v0.1.0-patch.1`），不使用第四位版本号
- harnessVersion 绑定：`0.1.1-rc.2`
- 知识库模式声明验证版本，版本漂移输出 `knowledge-version-drift` 告警