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

🛡️ dsh-evidence

面向 DSH 智能体执行的可验证、防篡改审计证据包
SHA256 清单 • 仅追加哈希链回执 • 时效有效性（validUntil）• 零冗余

DSH Suite
Integrity
License

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

💡 为什么选择 dsh-evidence？

AI 智能体常常会幻觉出“测试通过”，或在静默产生错误输出的命令上宣称成功。在交付代码或审计任务时，无法证明实际运行了什么以及输出事后是否被修改。

dsh-evidence 为智能体任务执行提供密码学证明：
- ⛓️ 仅追加哈希链回执：每次快照或执行链接都会向 receipt.jsonl 追加一个密码学哈希。任何事后文件修改都会立即导致验证失败。
- 📦 自包含快照（copy=true）：将输出目录、生成的二进制文件和验证脚本打包为可移植、可验证的 tarball。
- ⏱️ 时效有效性（validUntil）：明确跟踪证据何时变为 stale（被触碰）或 expired，防止过期日志被用于支撑新的声明。
- 🤝 诚实的边界声明：清晰定义密码学哈希能够证明什么、不能证明什么。

🚀 快速开始

安装

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="bench.json|verify.py" claim="30% speedup verified" validUntil=2026-12-31
3. 审计与验证：evidence_verify name="bench-2026"

🧩 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. Tamper-proof 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 | 上下文经济 | 基准测试（例如 savings-bench）注册证据快照以证明真实的 token 节省。 |
| 🔍 dsh-session-index | 会话搜索 | 搜索过往会话归档，以精确定位历史证据回执并跳回。 |

📖 深入探究与参考

🛠️ 可用工具（5 个工具）

| 工具 | 用途 |
|---|---|
| evidence_create | 初始化证据目录、evidence.json（v2）以及 receipt.jsonl 链。 |
| evidence_add | 添加文件/目录（SHA256、大小、mtime），可选 claim、validUntil 和 copy=true。 |
| evidence_verify | 重新计算 SHA256 哈希，验证链一致性，并针对过期/陈旧状态进行审计。 |
| evidence_list | 列出所有本地证据包，并附摘要健康计数。 |
| evidence_show | 检查完整清单、声明断言、时间戳和回执链。 |

📁 包结构与清单格式

~/.dsh/evidence//
evidence.json     # Manifest with top-level manifestHash self-integrity
receipt.jsonl     # Append-only hash-chained receipts
files/            # Self-contained copies when copy=true

⚖️ 诚实的能力声明

- 可以证明：快照内容匹配、文件被改动（损坏/陈旧）、对 evidence.json 的手动编辑，以及回执序列被篡改。
- 无法证明：命令意图的真实性、作者身份，或文件系统根访问权限被篡改（哈希不是数字签名）。

🧪 构建与测试

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 许可。