Edge-Echo/dsh-ledger

dsh-ledger

dsh-ledger

npm version
npm downloads

可验证的 DeepSeek Harness 执行账本。 回答单纯看会话日志回答不了的两个问题：

1. Agent 到底对这台机器做了什么？ —— turn/step/工具调用/类型化效应/文件版本链/token 成本，以及所有值得一看的异常。
2. 事后能不能证明这条记录没被改过？ —— 对原始日志做 RFC 6962 Merkle 树、可对外发布的存在性证明、Ed25519 签名的证据清单。

库优先（library-first），零原生依赖，Node ≥ 22。

为什么这不是"包一层 JSON.parse"

DSH 的会话日志是 append-only 的 session.jsonl.zstd，而每一次 append 都是一个独立的 zstd 帧——一个文件就是几万个帧的拼接。Node 的 zlib 只能解出第一个帧，流式 API 也一样：

zstdDecompressSync(Buffer.concat([frameA, frameB]))  // 只会返回 frameA 的文本

DSH 官方自己是用「私有 zstd handle + koffi FFI 调 libzstd」绕过去的。dsh-ledger 换了一条路：直接解析帧结构（RFC 8878）来定位精确的帧边界，完全不解压。下面这些能力全都建立在这上面。

| | 解压再猜边界 | dsh-ledger |
|---|---|---|
| 找帧边界 | 做不到 | 结构化遍历，34,729 帧仅 27 ms |
| 增量读取 | 不支持 | 支持，可从字节检查点续读 |
| 内存 | 整个文件 | 输入放大 5 倍，驻留堆 1.01 倍（实测） |
| 写一半的尾帧 | 读坏 | 暂存，写完后再读一次且只读一次 |
| 文件中部损坏 | 直接中断 | 跳到下一个帧魔数继续 |
| 篡改证据 | 无 | Merkle 根 + 签名清单 |
| 原生依赖 | koffi + libzstd | 无 |

真实会话实测数据

以下全部是 npm run verify 在一个真实 20.05 MiB DSH 日志（34,729 帧 / 53,671 条记录）上的输出，不是合成跑分：

1. structural ingestion with bounded memory
frames=34729 records=53671 bytes=21024791 polls=6 pendingPeak=5233 2449ms (8.2 MiB/s)

2. bounded memory (retained heap does not scale with file size)
reference      20.05 MiB -> 53671 records, retained heap peak 34.63 MiB
5x scaled     100.25 MiB -> 268355 records, retained heap peak 34.99 MiB
[PASS] 5x the input does not mean 5x the memory — 100.25 MiB used 1.01x

3. checkpoint resume        [PASS] resume reads no bytes — 0 bytes read
4. independent checks       [PASS] frame count  npm 上不带 scope 的 dsh-ledger 属于另一个无关的包，因此本项目发布在作者 scope 下。
项目名、仓库名与命令行都仍叫 dsh-ledger，只有安装名不同。
js
import { readLedger, renderSummary, findSessionLogs, attest, verifyManifest } from '@edge-echo/dsh-ledger'

const [log] = await findSessionLogs()        // 最新的在前
const ledger = await readLedger(log.path)
console.log(renderSummary(ledger))

ledger.graph.calls          // 工具调用 + 结果 + 耗时 + 效应
ledger.effectSummary        // { edit: 687, shell: 650, read: 262, write: 178, … }
ledger.chains               // 每个文件的版本链：新建？已被 shell 污染？

const manifest = await attest(log.path)      // 对外发布的证据清单
const result = await verifyManifest(suspectPath, manifest)
result.ok        // 任何一个字节被改/被增/被删都会变成 false

值得知道的设计取舍

效应保真度是显式标注的，绝不隐含。 每个效应都带 exact（write 有完整内容）、partial（edit 只有被替换的片段）、observed（只能证明这个路径被碰过）、undecidable 之一。

shell 命令只标注、不猜测。 参考会话里 1,860 次调用中有 650 次是 pwsh。一条 shell 命令能创建、覆盖、删除任何东西——从命令字符串去推断它的文件效应，那是把猜测包装成证据。所以 dsh-ledger 原样记录命令、把效应标为 undecidable，转而让"这条命令被记录过"本身变得可证明。因此当某文件的两次记录版本之间有 shell 命令跑过时，版本链会被标为 contaminated——参考会话是 177 条里的 58 条，因为这是事实。

帧的哈希不需要解压。 帧树覆盖的是原始字节，所以它能对"自己读不懂的内容"作证，且不花任何 zstd 开销。

用 RFC 6962，不用朴素 Merkle。 叶子是 SHA-256(0x00 ‖ data)，内部节点是 SHA-256(0x01 ‖ left ‖ right)。这个域分隔阻止了"把内部节点冒充成叶子"的伪造——那是常见的"奇数节点直接上提"构造允许的攻击。

刻意做成库而不是插件。 完整性格式和图谱 API 才是别的工具该依赖的东西；DSH 工具壳是薄薄一层，等 API 稳定后再加。package.json 里没有 dsh bundle 入口。

已知局限（如实列出）

- 解码吞吐约 8 MiB/s（单线程）：Node 每次 zstdDecompressSync 都会新建 zstd 上下文（约 1.9 KB/帧 → 每帧 ~45 µs）。同样的文件结构化遍历只要 27 ms，慢的只是解码。用 4 个 worker 线程走 SharedArrayBuffer 实测 2.0×，尚未接入。完整性工作完全不需要解码。
- shell 的效应归因在原理上不可判定（见上）。补这个洞需要沙箱级的文件监控，不是日志分析能解决的。
- edit 是 partial 保真度：日志里有被替换文本和替换文本，但没有文件其余部分，所以不能声称编辑后文件的整体摘要。
- 路径按会话 cwd 解析，Windows 上大小写不敏感比较；不解析符号链接与目录联接。
- 清单只对"当时的日志"作证：签名之后再 append 会让清单失效——这是设计意图，不是缺陷。
- npm run verify 的驻留堆测量需要 --expose-gc，其余检查不需要。

验证
bash
npm run build     # tsc
npm test          # 28 项测试
npm run verify    # 33 项真实数据验收
npm run check     # 三件一起跑

测试的方向是攻击实现而不是确认实现：对 1..33 每种树大小的每个叶子做证明验证（分裂规则最容易错的尺寸）、把内部节点冒充叶子、每个叶子改一个字节、同长度帧换序、截断日志、追加帧、篡改已签名清单。

许可证

MIT