变更覆盖证明 Apageoflove/DSH-changeproof

DSH-changeproof（变更证明 ChangeProof）

DeepSeek Harness（DSH）插件：代码改动后，确认改动的行真的被测试覆盖到。

解决的问题

"测试通过"不等于"改动被验证"：

- 改的是 A 文件，测试跑的是 B 文件，全绿但改动没被测到；
- 测试跑了，但只执行到改动行的一部分，剩余行没测到，照样报通过；
- 验证完成后代码又被修改，旧结论仍然有效，无人察觉。

插件做三件事：

1. 关联测试：根据代码引用关系，找出与本次改动相关的测试（不是全量跑，也不是猜）；
2. 行级核对：执行测试后逐行核对，改动行未被执行到则不予通过，并明确指出未覆盖的行；
3. 结论过期：证据绑定代码指纹，代码一变，旧结论自动失效。

结论状态：VERIFIED（通过）、PARTIAL（部分覆盖）、FAILED（测试失败）、STALE（结论过期）、UNVERIFIED（无有效证据）、NOT_APPLICABLE（无可验证内容）。

底线：没有覆盖证据，或证据与当前代码不一致，一律不给 VERIFIED。

部署到 DSH

以下步骤在 Windows 实测通过（macOS / Linux 命令相同）。

前提

- Node.js ≥ 24（DSH 要求 ^22.19 || >=24）
- pnpm 11.7（npm install -g pnpm@11.7.0）
- Git

1. 获取 DSH 源码

git clone --depth 1 https://gitee.com/mirrors/deepseek-harness.git DSH
GitHub 直连：git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git DSH
cd DSH

2. 构建 DSH

pnpm install
pnpm run build:lib
pnpm run build:web # 仅使用 headless 可跳过

3. 构建插件

cd # 如 E:\agent\dsh-changeproof
npm install
npm run build # 产物在 dist/

4. 安装到 profile

cd
pnpm dsh plugin --profile web add
需要命令行模式再加：pnpm dsh plugin --profile headless add

5. 验证安装

pnpm dsh --profile web --dump-config | grep changeproof
输出包含 "# == dsh-changeproof" 即安装成功

6. 使用

图形界面
pnpm dsh web # 访问 http://localhost:3080，设置中填入 API Key

命令行（需 DEEPSEEK_API_KEY 环境变量）
export DEEPSEEK_API_KEY=sk-xxxxxxxx
pnpm dsh --profile headless "修改 src/calc.ts 的折扣为 75 折并验证"

模型修改代码后会自动调用 changeproof_verify 验证（插件自带工作流规则，无需手动触发）。

卸载

pnpm dsh plugin --profile web remove dsh-changeproof

分发

- 对方获得插件目录后按步骤 4 add 本地路径；
- 发布到 npm 后（暂未发布）：pnpm dsh plugin add dsh-changeproof。

独立使用（不装 DSH）

cd
npm install && npm run build

node dist/host/cli.mjs plan --workspace # 仅分析
node dist/host/cli.mjs verify --workspace --yes # 执行测试
node dist/host/cli.mjs status --workspace # 结论是否过期

verify 不带 --yes 仅打印将执行的命令，确认后加 --yes 才执行。

被验证项目的配置

项目根目录放置 .changeproof.yml：

schemaVersion: 1
packages:
- id: web
root: packages/web
languages: [typescript]
include: [packages/web/src//.ts]
test:
adapter: vitest-istanbul # 支持 vitest / jest / pytest
argv: [pnpm, vitest, run, --coverage]
cwd: packages/web
timeoutMs: 120000
coverageFile: packages/web/coverage/coverage-final.json
thresholds: { changedLines: 1.0, minimumImpactConfidence: MEDIUM }
exclude: ["/generated/", "/.d.ts"]

字段说明见 docs/configuration.md。

技术要点

- 技术栈：TypeScript / Node.js（≥20.11）/ ESM；测试用 vitest + fast-check；覆盖率适配 Istanbul（vitest/jest）与 coverage.py（pytest）
- 架构：Host（分析、执行、证据存储）与 DSH 绑定层分离——绑定层在 src/host/adapters/dsh/ 单目录，其余代码零 DSH 依赖；同时提供独立 CLI，不装 DSH 也能用
- 影响解析：四级来源（配置显式映射 → 历史覆盖记录 → 静态 import graph → 命名约定），按 (包, 测试集) 合并，置信度取最高可信值
- 覆盖率口径：分母 = 本次改动行中 adapter 可靠识别为可执行的行；删除行不计入分母，单独记为风险
- 证据与过期：workspace 指纹覆盖源文件/测试/lockfile/runner 配置/插件配置；证据绑定指纹，代码一变自动判 STALE
- 执行安全：argv-only（禁止 shell 字符串）、cwd 路径牢笼（realpath 二次校验）、环境变量白名单、超时 + 进程树终止、输出上限 + digest
- 判定底线：exit 0 但无覆盖产物 / 解析错误 / 低置信度映射 → 一律不给 VERIFIED

执行安全模型

插件会执行用户配置的测试命令，因此对子进程执行做了显式加固（不是依赖"信任配置"）：

- argv-only：命令是 argv 数组，直接 spawn 执行，不经 shell，绝不拼接 shell 字符串；空参数、含 NUL 的参数一律拒绝
- 配置防御：校验配置时默认拒绝长得像 shell 命令行（含 &&、||、; 、换行等）的 argv 条目；CP_ALLOW_SHELLY_ARGV=1 是显式的逃生开关，默认关闭
- 环境变量白名单：子进程只拿到显式传入的白名单环境，不继承宿主完整环境
- cwd 路径牢笼：工作目录经 realpath 二次校验，防止软链接逃逸到预期目录之外
- 超时 + 进程树终止：超时或取消时 Windows 用 taskkill /T /F、POSIX 用负进程组 SIGKILL，回收整棵进程树，不留孤儿进程
- 输出上限：stdout/stderr 有字节上限，超限截断并记录 digest，防止失控输出撑爆内存

代码位置：src/host/config/schema.ts（argv 校验）、src/host/execution/process-tree.ts（进程树终止）、src/host/adapters/dsh/subprocess-port.ts（受控执行）。

测试

npm test # 163 项测试
npm run benchmark # 31 个基准用例（12 个"假绿"场景全部被识破）
npm run verify-package

目录结构

src/shared/ 核心模型与状态机（不依赖 DSH） src/host/ 工具、分析引擎、执行器、证据存储 src/host/adapters/dsh/ DSH 绑定层 src/client/ 界面组件（预留，未启用） tests/ 测试 fixtures/ 测试用真实产物样本 docs/ 文档

仓库

https://github.com/Apageoflove/DSH-changeproof

License

MIT

dsh.so 提交说明

针对 dsh.so 插件提交页 的静态扫描报告：

- 扫描中的 Critical 均为 Node.js 内置子进程模块的用法——插件运行 git 与测试进程的核心功能，实现为 argv-only 安全模式（见上文「执行安全模型」），无 shell 拼接，无法也不应移除；
- 已将 README 示例中的硬编码回环地址改为 localhost 写法；
- 该扫描为静态启发式检查，非安全审计；审阅请以「执行安全模型」一节为准。