防篡改审计证据 huangjua/dsh-evidence

🛡️ dsh-evidence

为 DSH 提供本地审计证据包，哈希可验证 SHA256 清单 • 逻辑哈希链回执 • 时效性（validUntil）

功能 • 快速开始 • DSH Power Suite • 工具 • 简体中文

💡 为什么需要 dsh-evidence？

「测试通过」这类任务声明，需要可复核的输出文件。有了记录下来的快照，复核者就能把当前文件与记录的哈希做对比，并查看相关声明和本地回执链。至于生成这些文件的命令，插件既不观察，也不认证。

dsh-evidence 记录快照，并检查本地一致性：
- ⛓️ 哈希链回执：每次 create/add 都会延长一条逻辑哈希链。验证时会检查记录内容、链结构，以及链与清单的绑定关系。
- 📦 复制快照（copy=true）：v3 按相对于证据包的 files/... 路径存储。整体移动证据包，本地副本验证依然成立；source 记录来源，但绝不能替代缺失的副本。
- ⏱️ 时效性（validUntil）：有效期过期与完整性分开报告。stale 表示内容一致但修改时间不同，并不表示有效期已过。
- 🤝 如实声明边界：明确说明密码学哈希能证明什么、不能证明什么。

🚀 快速开始

安装

In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-evidence

典型使用流程

1. 创建证据包：evidence_create name="bench-2026" description="Performance audit"
2. 添加快照与断言：evidence_add name="bench-2026" paths="E:\\project\\bench.json|E:\\project\\verify.py" claim="Recorded benchmark output for review" validUntil="2026-12-31"
3. 审计并验证：evidence_verify name="bench-2026"

输入路径与稳定的证据根目录

相对 paths 按调用会话的项目目录解析，该目录由经过验证的宿主接口提供（ToolRunContext.agent.session.header.cwd）。cwd 缺失、无效或不是绝对路径时，返回 RELATIVE_PATH_REQUIRES_CWD；这种情况下请提供完整的绝对输入路径。不会回退到插件的启动目录，也不会调用 process.chdir()。在 Windows 上，盘符相对路径 C:file.txt 和根相对路径 \file.txt 会被视为有歧义而拒绝；请改用 C:\project\file.txt 或完整的 UNC 路径。
证据根目录遵循另一套规则。插件在 apply 时解析一次配置好的 evidenceRoot。配置的相对根目录和每次调用传入的相对 root 覆盖，始终使用同一个捕获的进程目录，因此不同的调用项目无法移动证据存储。绝对 root 覆盖会选中那个确切的存储。没有显式配置时，根目录为 DSH_HOME/evidence；未设置 DSH_HOME 时为 %USERPROFILE%/.dsh/evidence。若要把存储独立放在别处，优先使用绝对路径的配置根目录。

完整性、事务与兼容性

v2 和 v3 要求 receipt.jsonl 非空且有效，并与当前清单绑定。回执缺失或为空时返回 FAIL，错误码为 RECEIPT_MISSING / RECEIPT_EMPTY。普通 add 在暂存文件之前，会先拒绝损坏或不匹配的旧链。真正的 v1 包没有回执，仍可读取，此时 receiptChain=UNVERIFIED_LEGACY，会给出明确警告，且不支持普通追加；离线迁移会保留原始包。

工具失败时使用宿主的 HarnessError 契约，错误结果因此保留稳定错误码。写入错误的消息中，在可用时会包含 commitState、transactionId 以及锁清理失败的详情。提交决定之后发生取消，会完成发布，或留下可查询的恢复状态。取消之后观察到已完成的写入，会报告 COMMITTED_AFTER_CANCEL，状态为 COMMITTED，并带上事务 ID；之后注册表层面的取消仍可能是 ABORTED，文本会说明已提交的结果。重试被取消的写入之前，先查询 evidence_verify / evidence_show。取消本身并不表示没有写入被提交。

status 表达完整性；freshness=CURRENT|EXPIRED 单独表达可读清单中记录的有效日期，包括缺失或损坏文件上的日期。内容一致的过期文件可以通过完整性校验。

写入会把完整清单、回执生成以及所有副本暂存到 .transaction/ 内。.transaction/COMMITTED 的原子发布就是提交决定。在此之前，失败或取消会保留旧的已发布产物；在此之后，恢复流程会完成新一代产物。报告的错误包含稳定错误码，并在相关时包含 commitState 和 transactionId。用 evidence_verify 恢复或查询待处理事务。两处实时元数据替换是各自独立的可恢复发布步骤。该协议已针对进程崩溃和注入的写入失败做过测试，未覆盖断电场景。
校验期间会一直持有 bundle 锁，直到整个文件检查完成，所以检查耗时一长，追加操作就会被拖住。等待和哈希计算都支持取消。活跃的持有者不会因为锁太旧而被顶掉。锁的回收与释放都在同一道短闸门内串行执行，释放时必须提供精确的 PID/token。只有 ESRCH 的 PID 才能被回收。PID 被复用、持有者属于旧版或未知、.lock.gate 成为孤儿，这几种情况一律按失败关闭处理。校验超时返回 status=BUSY、receiptChain=NOT_CHECKED、freshness=UNKNOWN；这不构成任何完整性结论。

普通持有者进程死亡后，下一次操作可以回收它的锁并恢复事务。如果崩溃发生在短闸门内，就需要离线介入：停掉所有写入方，保留锁和事务产物以备检查，确认没有持有者残留后，再手动删除已证实为孤儿的闸门。不做任何基于时长的删除。不要新旧锁协议混跑。真实桌面端的端到端验证仍属于单独的部署检查；模拟工具调用不能替代它。

目录扫描、限制与取消

evidence_add 异步扫描，不跟随文件或目录链接。跳过的链接、重复的物理文件、当前 bundle 及其别名都会作为排除项上报。断开的链接/junction、无法读取的目录、属性获取失败、不支持的输入类型都返回 SCAN_INCOMPLETE；不会悄悄把它们转成一次成功的部分快照。当前 bundle 整体排除。在其他可识别的 bundle 文件夹里，内部的 .lock、.lock.gate、.transaction 以及具名事务清理目录会被排除。可识别 bundle 文件夹之外的同名普通输入文件仍然有效。

默认值为 maxFiles=10000 和 maxTotalBytes=10737418240（10 GiB）。覆盖值必须是正的安全整数。超出任一限制返回 SCAN_LIMIT_EXCEEDED，不截断、也不提交本次扫描。paths 为空或只含分隔符返回 INPUT_EMPTY；空目录或扫描结果全部被排除返回 SCAN_EMPTY。添加成功返回 scan.status=COMPLETE、文件/字节总数、最多 100 条排除路径、excludedTotal 和 exclusionsTruncated。COMPLETE 描述的是明确声明的扫描范围，包含其中的排除项。
add/verify、遍历、复制和哈希都串行执行，并发上限为 1；文件 IO 使用 256 KiB 分块。宿主取消信号能触达锁等待、扫描、复制、哈希和校验。相关句柄在操作 promise 落定前关闭。事务提交决策前取消，会保留旧的已发布代际；决策之后取消，事务协议会走完，或报告恢复要求。读取前后各检查一次文件标识与属性，add 提交前再检查一次。观察到变化就返回 FILE_CHANGED；这些检查不会为外部进程正在改动的文件建立强一致快照。仅元数据创建和离线迁移命令保留各自独立的同步事务发布路径；离线命令还保留同步复制。

有界校验与浏览

evidence_verify detailLimit=20 对缺失、损坏、过期、失效和出错的情况返回完整 counts，路径数组有界，issues 包含路径、代码和原因。issueTotal 和 issuesRemaining 披露截断情况；一个文件可能贡献多条 issue。文本视图显示同样的完整计数和剩余 issue 数。detailLimit 接受 1 到 100 的整数。status=PASS 检查当前完整性，freshness=EXPIRED 表示记录的有效期已过。freshness=UNKNOWN 表示没有得出可靠的有效性结论，例如 bundle 处于 BUSY，或读不到它的 manifest。stale 表示哈希匹配但修改时间有差异。

evidence_list 接受 offset=0 和 limit=20（最大 100），返回 total、returned、remaining 和 nextOffset。条目按名称排序。无效、缺少 manifest 和忙碌的 bundle 目录仍会显示，并附带状态和诊断信息。READABLE 描述 manifest 是否可读；文件和回执的完整性请用 verify 检查。查询在显示截断前搜索完整名称/描述。每次调用分页都描述当时的根，并发新增可能改变后续页。
evidence_show 沿用同一套文件分页，并独立使用 receiptOffset=0、receiptLimit=10（上限 100）。它返回 page 和 receiptPage，记录来自有效的本地回执链，数量有上限。回执无效或不可用时，会给出明确原因。返回的描述、声明、来源和回执备注会转义控制字符，并限制为 500 个显示字符；回执载荷的路径数组最多显示 20 条路径，同时给出原始总数。这个受限视图会省略元数据和无法识别的扩展字段。presentation 标明这些省略项和显示投影：原始清单/记录哈希保留下来供参考，但无法从分页或净化后的投影重新计算。要重新计算这些哈希，请读取原始文件。浏览不会改动原始文件，也不确立内容真实性或命令执行。

stale 提示允许最多 1 微秒的舍入误差，用于毫秒级元数据与文件系统时间戳 API 转换浮点单位的情况。主动扫描/复制/哈希的变更检测则改为比较精确的纳秒属性和文件标识。

可移植 v3 路径与旧格式

v3 条目显式使用 storage: "external" 加绝对键，或 storage: "copy" 加规范 files/... 键。复制会拒绝路径穿越、盘符/UNC 键、设备名、备用数据流，以及包内的链接/联接。重复的基名会获得确定性的 -2、-3 后缀；匹配不区分大小写。这些边界检查覆盖观察到的文件系统状态，不覆盖在协作锁协议之外持续替换路径的恶意进程。

v1/v2 外部引用仍可读取。旧副本只从可识别的 <bundle>/files/<basename> 键映射到当前包中的该文件。映射有歧义时返回 MIGRATION_REQUIRED；本地副本缺失即失败，即使记录的旧路径或原始来源仍然存在。旧副本绝不通过那些旧位置校验。v2 外部追加保持 v2；复制追加需要迁移到新的 v3 包。

离线迁移

在已安装的候选目录中运行，试用时使用隔离副本：

node scripts/migrate-bundle.mjs --root 'E:\evidence' --name 'old-bundle' --preflight
node scripts/migrate-bundle.mjs --root 'E:\evidence' --name 'old-bundle'
Optional: --destination-root 'E:\new-evidence' --destination-name 'reviewed-v3'
默认会新建一个同级目录 old-bundle-migrated-v3，绝不覆盖已存在的目标。原始 manifest、receipt 和正文保持原样。预检会拒绝损坏的链、绑定错误、缺失副本、有歧义的映射，以及待处理的源事务。迁移期间持有源锁，把复制出的字节与原始记录的哈希逐一比对，并把源元数据摘要和校验限制写进 metadata.migration。新的 receipt 链从这次迁移开始，不继承旧的 receipt 历史。即使新包通过当前一致性检查，v1 源仍会保留可见的 UNVERIFIED_LEGACY 来源标记。预提交失败可能留下空的目标预留；重试时换个新名字，或者离线检查这个孤立的预留。永远不要把这条命令当作损坏证据的修复手段。

🧩 DSH Power Suite

本插件属于 DSH Agent Power Suite —— 4 个模块化、零硬依赖的插件，组成完整的开发者工作流闭环：

flowchart LR
M["🧠 dsh-local-memory(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy(2. Save 80%+ tokens reading code)"]
E --> A["🛡️ dsh-evidence(3. Local audit receipts)"]
A --> S["🔍 dsh-session-index(4. CJK search & bookmarks)"]
S --> M

style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px

| 插件 | 在套件中的角色 | 与 Evidence 的协同 |
| 🛡️ dsh-evidence | 审计与回执（当前） | 记录文件哈希、本地回执和待审声明。 |
| 🧠 dsh-local-memory | 记忆层 | 可以把记住的决策与已审阅的证据包关联起来。 |
| ⚡ dsh-context-economy | 上下文经济 | 可以把基准测试输出文件登记为证据快照。 |
| 🔍 dsh-session-index | 会话搜索 | 搜索历史会话归档，定位历史证据回执并跳回。 |

📖 深入解析与参考

🛠️ 可用工具（5 个）

| 工具 | 用途 |
| evidence_create | 初始化证据目录、evidence.json（v3）和 receipt.jsonl 链。 |
| evidence_add | 添加文件/目录（SHA256、大小、mtime），可选 claim、validUntil 和 copy=true。 |
| evidence_verify | 检查文件哈希、回执一致性和有效期；返回有界的问题路径和完整计数。 |
| evidence_list | 分页浏览本地证据包目录，保留无效或占用中的条目并附带诊断信息。 |
| evidence_show | 查看一页 manifest 条目，以及单独一页本地回执记录。 |

📁 包结构与清单格式

~/.dsh/evidence/<name>/
evidence.json # Manifest with top-level manifestHash self-integrity
receipt.jsonl # Logical hash-chain receipts; recoverable generation writes
files/ # v3 copies keyed by relative files/... paths
.transaction/ # Pending generation, removed after publication

⚖️ 如实说明能力边界

- 能校验：当前文件哈希与记录哈希是否一致、清单自哈希、收据链结构以及清单绑定关系。claim、description 和收据时间戳都是本地记录的声明。
- 无法独立证明：命令是否真的执行过、内容是否真实、作者身份、被删除的完整历史后缀，以及能否抵抗对整个包的重写。只要能替换全部本地文件，就能重新算出一个自洽的包。本地哈希不是数字签名，也不是可信的外部时间戳服务。

🧪 构建与测试

node scripts/build.mjs # Compile src ➡️ lib
npm run typecheck
npm test # Run test suite
npm run pack:check # Packaging check

属于 DSH Agent Power Suite 的一部分。基于 BSD-3-Clause 许可发布。