取证护栏 a5557/dsh-agent-guard

dsh-agent-guard（中文）

一个让「读一手证据」成为最省事路径的 DSH 护栏插件。
零网络、零遥测、零运行时依赖。

dsh-agent-guard 来自一次真实事故：一个 agent 没有读一手证据，把正常设计误判成缺陷，然后改写了应用自己的私有存储，导致应用崩溃。这个插件就是那次事故本该撞上的护栏。

当前版本：只读取证 + 写入治理 + 留痕与回滚点。所有结论都有实证，见 VERIFY.md。

它为什么存在

一次完全正常的目录整理之后，一个 agent 会话看到「磁盘上的会话目录数」多于「注册表登记的工作区数」，据此断定「丢了 40 个对话」，然后开始"修复"：先用目录联接，再用一个「重命名会话目录 + 重写注册表」的脚本。应用崩溃了。那些"丢失的对话"从未丢失——它们是 DSH 有意不登记的 origin: "subagent" 内部记录。

四条根因与对应措施：

| 根因 | 会出什么事 | 本插件的对策 |
| R1 路径即身份 | 工作区身份、存储键、会话文件头都以绝对路径为准；移动文件夹 = 换身份 | 检测并报告；绝不通过制造「第二个名字」去"修复" |
| R2 用汇总数字代替一手证据 | 「目录数 ≠ 登记数」被读成数据丢失 | guard_inspect 读每个会话的首帧身份头，把内部记录标为 countsAsConversation: false |
| R3 影响预算失衡 | 显示类问题被"修复"成改写全部核心数据 | 影响预算：display 类目标一律不得写核心数据 |
| R4 把不确定性转成用户的一次双击 | 破坏性脚本被做成 .bat 交付 | 生成这类脚本是告警动作，绝不"一键" |

安装

本地目录（路径需为绝对路径）：
dsh plugin --profile <profile> add <本目录绝对路径>

发布后按精确版本安装：
dsh plugin --profile <profile> add dsh-agent-guard@0.1.0

package.json 声明了 dsh.bundle.patch，所以安装即挂载为 profile 的一层。
注意：没有声明 dsh.bundle 的包会被安装但不会挂载——本插件声明了。

卸载：

dsh plugin --profile <profile> remove dsh-agent-guard

卸载只移除注册，不删任何数据，包括回滚点——那是用户自己的资产。
（DSH 没有插件级卸载回调，所以 $DSH_HOME/agent-guard/ 会保留；README 下方有手动清理说明。）

用法

作为工具（已安装）

guard_inspect(scope?, workspace?, maxSessions?, includeHeaders?, redact?)
guard_journal(action?, limit?, snapshot?)

作为独立 CLI（零 profile 改动）

v0 的设计目标之一就是：DSH 起不来时它照样能用——而那正是最需要证据的时候。

dsh-agent-guard inspect # 人类可读摘要 dsh-agent-guard inspect --json # 机器可读报告 dsh-agent-guard inspect --redact # 路径/标题/id 换占位符 dsh-agent-guard inspect --no-headers # 只做目录级清点（更快） dsh-agent-guard inspect --scope workspaces,processes

界面（原生席位）

插件带客户端半边，所以它在界面里有原生席位：

- 侧边栏图标（sidebar.panellist，官方目前没有占用者）→ 点开主面板，显示护栏状态、回滚点与最近受保护操作；
- 设置页（「环境护栏」）→ 同样的状态，外加如何停用的准确做法。

两处都严格只读：没有修复、没有迁移、没有回滚按钮。
客户端半边是手写的 window.__ModuleLoader__.load bundle，因此本包零构建步骤、 零 devDependencies。同时在 /agent-guard 提供一份等价的同源 HTTP 面板，作为宿主没有 client bundle 通道时的降级方案。

说明：官方 client bundle 由 tsdown 构建，本包按同一契约手写（用 React.createElement 代替 JSX），并由单测在受控沙箱里真实执行、断言三个席位的注册形态与"无写入口"。

截图

目前没有，而且只接受真实运行出来的截图。 本项目的规矩和它要求别人的一样：先有证据，再下结论。用示意图代替真实界面，正是这个插件存在的意义所要拒绝的那种"用汇总代替一手证据"。

| 建议截什么 | 来源 |
| 1-panel.png | 正常安装后，在不含私人内容的工作区会话里，打开侧边栏面板或设置页 |
| 2-blocked-write.png | DSH 运行中，agent 尝试写 $DSH_HOME/storages/workspace.json → 审批/拒绝提示，以及 guard_journal 里对应那条记录 |
| 3-inspect.png | dsh-agent-guard inspect --redact 的输出（已脱敏，可直接公开） |

欢迎按这个方式贡献截图；公开前请先脱敏（CLI 视图用 --redact 即可）。

输出长什么样

会话：磁盘上 74 个会话目录，本次解出 74 个身份头
· 用户对话 31 条 | origin:"subagent" 或 delegationDepth > 0 的内部记录 43 条（内部记录由应用有意不登记，不计入「缺失对话」）
· <workspace>：登记 9（磁盘上找到 9）| 磁盘 12（对话 9 / 内部记录 3）| 未登记 3

发现（4 条） [info] orphan-session-space 存在一个会话存储目录，但没有任何已登记工作区的路径编码到它……
[info] unregistered-subagent-records
3 条记录带 origin: "subagent" 或 delegationDepth > 0：这是应用有意不登记的内部记录，不是丢失的对话。

请注意每一条结论的形状：「未登记」永远和 origin 分解一起给出，读不出来的身份头记为 unreadable——绝不当作「不存在」。「读不出来」和「没有」是两件不同的事。

能力与红线

能做的

- 读工作区注册表、会话身份头、目录布局与宿主运行状态；
- 在受保护路径被写入前拦截：先备份再放行，备份失败则拒绝写入；
- 只追加留痕（带哈希链，可发现改写），每轮生成回滚点，按保留策略只清理自己的快照；
- 用 guard_journal 查看护栏自身状态、最近记录与人工回滚说明。

拦不住的（必须知道）

| 旁路 | 原因 |
| pwsh/bash 里的改名、删除 | DSH 没有 rename/delete 工具，这些动作只以不透明的命令行文本出现，只能启发式提取路径 |
| 后台任务（run_in_background） | 命令交给 job registry；前台调用超时后会被提升为 job，而拦截早已执行完 |
| 宿主终端（ctx.terminals） | 它是 PTY 服务，不注册任何工具 |
| 客户端/HTTP 宿主 API | 不经过工具流水线 |
| 用户手工双击脚本、其他进程写同一路径 | 插件在宿主进程内，管不到进程外 |

所以正确的说法是「能阻止本会话内 agent 的工具调用」，而不是「能阻止一切破坏」。

另有一条性能边界：pre-execute 没有超时，且运行在单一有序通道里——在其中做的备份会阻塞该回合且中途不可取消，因此备份预算被刻意压得很小（默认单文件上限 8 MiB，超限即拒绝写入）。

永久红线

- 绝不写 DSH 的 sessions/、storages/、profiles/；
- 凭据文件只检查存在与权限元数据，绝不读内容；
- 不提供任何「一键修复/迁移 DSH 数据」的功能；
- 不生成可双击的改数据脚本；
- 无网络、无遥测、无安装钩子。

关键设计取舍

- 规则引擎是纯函数、无 I/O，所以 T1–T9 可以直接单测，不需要起整个应用。
- 引擎故障时 fail-safe：降级为「先备份 + 告警」，绝不无备份放行。
- 自身数据目录：$DSH_HOME/agent-guard/（可配置）。若沙箱拒绝写入，会降级到临时目录 并告警；两者都不可写则进入「仅内存」模式并明确提示记录会丢失——降级可以，静默降级不行。
- 日志不记命令原文，只记 12 位摘要；命令、消息正文、凭据都不进日志。
- 回滚只给人工说明，不给自动回滚命令：自动改写应用私有存储正是事故的形态。

兼容性

| 组件 | 已验证版本 |
| DSH | 0.1.7-rc.2 |
| Node | ≥ 22（使用内建 node:zlib 的 zstd；实测 24.x） |
| 平台 | Windows 已验证；核心只依赖路径字符串，Windows 专有探测在其他平台降级为「不支持」 |
| 运行时依赖 | 无 |

常见问题

为什么不直接帮我修会话数据？ 因为那就是事故本身。DSH 的存储是应用私有的：会话目录名是工作区路径的编码键，注册表由应用自己持有并重写。安全做法是物理的（把目录搬回去）或在应用内完成（让用户重新登记工作区），而不是由第三方改写私有存储。

它说 43 条记录未登记，我丢对话了吗？ 没有。那些是内部 origin: "subagent" 记录，DSH 有意不登记、不显示。
报告永远在计数旁边给出这个分解，就是为了让这个数字不会被误读。

会联网吗？ 不会。本包没有任何 HTTP 客户端，没有遥测，没有统计。想分享报告时用 --redact。

身份头读不出来会怎样？ 会被记为 unreadable / incomplete，并且排除在对话/记录统计之外。
不确定永远不会被当成"不存在"。

怎么手动清理插件数据？ 确认不再需要回滚点后，自行删除 $DSH_HOME/agent-guard/ 即可。插件不会替你删。

文档

- VERIFY.md — 每条 API 结论与一手证据，以及已知缺口
- IMPLEMENTATION-PLAN.md — 范围、模块划分、验收判据
- docs/incident-redacted.md — 事故复盘（脱敏，只讲机制）

完整设计文档与发布/验收报告刻意不放进本仓库：它们是绑定了作者本机环境的工作文档。
使用本插件所需的关键结论都在 VERIFY.md 里。

许可证

MIT。