会话审计 bwndlct/dsh-session-audit

dsh-session-audit

看清你的 DeepSeek Harness Agent 这次到底是怎么干活的。

对一个 DSH Session 做 Steps / Tool Calls / 失败 / 重复动作 / Token / 验证命令（test/build/lint）的执行审计，通过一次 session_audit 工具调用输出一份可读的审计报告。

DSH Session Audit
──────────────────────────────────────────────

Session
ID session-d2309fa2-47d3-484a-8357-236e0acdd9aa
Model glm-5.3
Provider zai-coding-cn
Duration 51m 42s
Started 2026-08-14T09:08:08.384Z

Execution
Turns 4
Steps 121
Assistant msgs 120
Turn endings completed×1, interrupted×1, error×1

Tools
Total calls 150
Succeeded 143
Failed 6
Unresolved 1
Failure rate 4.0%

Top tools
bash 83 (1 failed)
write 26
edit 21 (4 failed)
read 12

Tokens
Input 349,428
Output 80,415
Cache read 9,243,520
Total 9,673,363

Execution signals
⚠ 3 consecutive failed tool calls detected
⚠ bash called 83 times
ℹ session has a turn that never closed

Verification
✓ pnpm run typecheck [typecheck]
✓ npm test [test] (2 attempts, 2 ok)

(来自本机真实会话的报告)

为什么需要

DSH 的 session 日志已经完整记录了“发生了什么”——它是 append-only 的事实源。
但读完一份上千事件的日志，并不能直接回答你真正关心的问题：

跑了多久？多少个 Turn / Step？哪些工具用得最多？在哪里失败？
有没有重复调用？最后验证过没有？

dsh-session-audit 把单个 session 的持久化事件日志折叠成这些答案。
它是 Step / Tool-call Profiler 和失败分析器，不是 Token 仪表盘（见现有同类插件）。

功能

- Session 指标 — 时长、Turns、Steps、assistant 消息数、工具调用总数、按工具分布、成功/失败拆分。
- Token 用量 — 按 turn:step 折叠 input / output / cache 桶，语义与官方 session-stats 投影一致；provider 没上报时显示 Unavailable，绝不估算。
- 确定性审计信号 — 连续失败、失败率、高频工具、完全相同的重复调用（对参数 key 顺序不敏感）、重复读取同一文件。纯规则判定，不用 LLM 打分。
- 验证命令识别 — 识别 shell 工具调用中的 test/build/lint/typecheck 命令（npm test、pytest、cargo test、tsc、eslint……）并报告实际观察到的结果。
- 三种格式 — text（默认）、Markdown、JSON（带稳定 schemaVersion）。
- 当前或历史 Session — 默认审计当前内存中的 session，也可按 id 审计任一持久化 session；支持列出最近的 session。
- 健壮 — 空会话、畸形事件、未来新增的事件类型、孤儿 result、崩溃尾部残帧：全部安全处理，并在报告中以数据质量说明呈现。

安装

要求 dsh（@deepseek-ai/dsh）0.1.0-rc.6+。

npm（发布后）
dsh plugin --profile web add dsh-session-audit

GitHub
dsh plugin --profile web add github:bwndlct/dsh-plugins/plugins/dsh-session-audit

本地开发（link）
dsh plugin --profile web add link:/path/to/dsh-plugins/plugins/dsh-session-audit

然后编辑 ~/.dsh/profiles/web/package.json，把包加进 dsh.profile.bundles（上面的安装命令不会做这一步）：

"dsh": {
"profile": {
"bundles": [
// ...现有条目... "dsh-session-audit" ] } }

重启 dsh（dsh web），并验证挂载：

dsh --profile web --dump-config | grep -A2 session-audit

使用

在会话里直接让 Agent 调用（自然语言即可），或使用斜杠命令（交互式 profile 中可用）：

- 审计当前会话 — 审计当前 session。
- 审计 session session-abc123 — 按 id 审计某个存储的 session。
- 列出最近的 session — 列出可审计的持久化 session。
- 用 markdown/json 格式审计当前会话 — 指定输出格式。

斜杠命令（当 commands 服务挂载时可用，如 web profile）：
- /session-audit [text|markdown|json] — 审计当前会话（空参数默认 text）
- /audit-list — 列出最近的持久化会话

工具参数：

| 参数 | 类型 | 含义 |
| session_id | string | 目标 session（默认当前会话） |
| format | text \| markdown \| json | 报告格式（默认 text） |
| list_sessions | boolean | 列出最近 session 而不是审计 |
| thresholds | object | 可选的审计规则阈值覆盖（与默认值浅合并） |

报告只留在本地——作为工具结果返回给你和模型阅读，不写盘。

审计信号

全部规则都是确定性的、阈值驱动；所有阈值集中在一个文件（src/rules/thresholds.ts），默认值保守，正常会话不会被警告淹没。

| 信号 | 级别 | 默认阈值 |
| 连续失败的工具调用 | warning | ≥ 3 |
| 工具总体失败率 | warning | ≥ 15% 且 ≥ 3 个有结果的调用 |
| 完全相同的工具调用重复 | warning | ≥ 3 次（参数按排序后的 key 比较，JSON key 顺序不同不会漏判） |
| 同一文件被反复读取 | info / warning | ≥ 4 次（≥ 8 次升 warning）；读取工具与参数名可配置（默认 read/read_file → file_path） |
| 高频工具 | info / warning | ≥ 15 次（info），≥ 30 次（warning） |
| Turn 非正常结束 | info | 任何 aborted / error / interrupted |
| 存在未关闭的 Turn | info | 活跃/被中断会话的标志 |
| 未观察到验证命令 | info | 措辞谨慎——"未观察到"，不是"没有验证" |
| 验证命令失败 | warning | 最后一次观察到的尝试失败 |
| 验证命令连续失败 | warning | ≥ 2 次失败且之后没有成功 |

刻意没有效率评分——报告陈述事实和确定性发现，判断权留给你。

验证命令识别

规则识别 shell 工具调用（bash / pwsh，可配置）里的常见验证命令：

- test：npm|pnpm|yarn|bun (run) test、pytest、cargo test、
go test、dotnet test、jest、vitest、mocha、mvn|gradle test、
make test
- lint：(npm|pnpm|yarn|bun) (run) lint、eslint、biome、 prettier、ruff、pylint、flake8、golangci-lint
- typecheck：(npm|…) typecheck、tsc、mypy、pyright、
cargo check
- build：(npm|pnpm|yarn|bun) (run) build、cargo build、
go build、dotnet build、make build|all

成败只根据工具结果里实际观察到的内容判定：harness 级错误，或 dsh-tool-bash 对非零退出追加的 [exit code: N] 标记（文档化约定），都算失败。匹配到命令但没有持久化结果的调用视为"未观察到"，不算失败。完全没有验证命令时，报告只说"未观察到验证命令"，绝不声称 "Agent 没有验证"——验证可能走了日志看不到的机制。

工作原理

DSH session（live 注册表 或 ~/.dsh/sessions 持久化日志，zstd 帧） │ session-reader — 按 session id 直查目录（目录名即 id）， │ 列出时只解码头帧，审计时完整解码；回退扫描 ▼ session-adapter — 原始事件 → 规范化 AuditEvent 词汇表 ▼ analyzer — 一次 O(n) 遍历：计数、工具配对、用量折叠 ▼ rules — 基于折叠事实的确定性信号 ▼
SessionAuditReport (schemaVersion 1.0) — text / markdown / json

- Turn/Step 计数与官方 dsh-session-stats 语义一致（steps = step/end 数；turns = 有已关闭 step 的不同 turn），审计数字与 Web UI 统计条一致。
- Token 桶遵循 dsh-llm 的 TokenUsage：input 不含缓存输入； cache 读/写单列；reasoning（output 的子集）只展示、不重复计入总数。
- 所有 DSH 事件形状知识都收敛在 adapter；analyzer 和 rules 只依赖规范化词汇表。

隐私

dsh-session-audit 只做本地分析。 只读取本机 DSH home 的 session 日志和内存中的 live session 注册表。不发起任何网络请求、不调 LLM API、不发遥测、不收集任何用户数据。报告只作为工具结果存在于你自己的会话里。

开发

cd plugins/dsh-session-audit
npm install --no-save # 安装 typescript + @types/node
npx tsc -p tsconfig.json # 类型检查 + 构建到 lib/
node --test tests/ # 32 个单元测试

目录结构：

src/
index.ts 工具注册 + live/磁盘 session 加载 dsh/ session-adapter.ts 原始 DSH 事件 → 规范化审计事件 session-reader.ts 持久化日志发现、zstd 解码、JSONL 解析 audit/ analyzer.ts O(n) 折叠 + 规则编排 types.ts SessionAuditReport schema、AuditEvent 词汇表 rules/ 每条规则一个文件 + 集中阈值 formatters/ text / markdown / json utils/ stable-json（排序 key 身份）、duration tests/ node:test 套件：analyzer、rules、边界、reader

兼容性

- 已针对 @deepseek-ai/dsh 0.1.0-rc.6（session format version 0）验证。
- 同时支持压缩（session.jsonl.zstd，默认）与明文（session.jsonl）持久化日志。
- SESSION_FORMAT_VERSION 仍是 pre-release；未来格式升级只需改 adapter——这正是所有形状知识集中一处的原因。

限制

- 验证命令识别基于模式；包在特殊脚本名里的验证器无法识别。
- 子 Agent 的 session 需按 id 单独审计；暂无跨 session 汇总。
- Reasoning token 在 provider 上报时展示，但部分 provider 的逐步值无法重建。
- 暂无时间序列 / 上下文增长分析（见路线图）。

路线图

- v0.3 — session 对比
- v0.4 — 上下文增长分析
- v0.5 — HTML 报告
- 之后 — Web 仪表盘视图、跨 harness 审计

现有同类插件

Token/费用仪表盘已经存在（dsh-spend、dsh-balance-stats、 dsh-session-cost、dsh-token-monitor），它们与本插件互补：回答的是 "花了多少"。本插件回答"Agent 是怎么干活的"——执行形态、失败位置、重复行为、验证情况。截至 v0.2.0，dshplugin 生态中没有其他覆盖单 session 执行审计的插件。

许可

MIT