前言¶
在使用 DSH 进行智能体开发时，常见的问题是智能体依赖摘要数据（如目录计数）而非第一手证据，误判数据丢失或状态异常，进而错误修改核心存储，导致应用崩溃。dsh-agent-guard 是为此类场景设计的 DSH 栅栏插件，它要求智能体先读取证据再执行操作，并在写入时进行拦截与备份。
是什么¶
dsh-agent-guard 是一个 DSH 安全护栏插件。它的核心价值在于：证据优先的只读检查、写入时的治理拦截，以及每回合的回滚点记录。该插件零运行时依赖、无网络请求、无遥测数据。它由用户 a5557 维护。
核心能力¶
证据优先的只读检查¶
插件通过 guard_inspect 工具读取所有会话的第一手身份头信息。它会识别并标记 DSH 内部刻意不注册的 origin: "subagent" 记录，避免将内部数据结构误判为数据丢失。
写入治理与拦截¶
插件在 tools/pre-execute 阶段拦截受保护的写入操作：
1. 拒绝未停止时的写入：当 DSH 未确认停止时，对核心数据的写入一律拒绝。
2. 备份再允许：允许的写入必须先备份，默认限制为 8MiB/文件。若备份失败或超限，写入被拒绝。
3. 断路器机制：若同一路径连续两次写入且校验和不一致，触发断路器，需人工介入。
4. 脚本生成拦截：智能体生成的 .bat/.cmd/.ps1/.sh 若引用受保护路径，会被标记为 emit-script 并拒绝。
每回合回滚点¶
插件维护每回合的回滚点。当发生破坏性操作时，这些点可用于恢复状态。
客户端 UI 集成¶
插件提供客户端 UI，集成在侧边栏和设置页面中，显示护栏状态、回滚点和最近受保护的操作。
安装与启用¶
安装插件需要指定 profile。插件在 package.json 中声明了 dsh.bundle.patch，因此添加包后会将其挂载为 profile 层。
# 从注册表安装指定版本
dsh plugin --profile <profile> add dsh-agent-guard@0.1.0
# 从本地目录安装（路径需绝对）
dsh plugin --profile <profile> add <absolute-path-to-this-directory>
典型用法¶
插件提供了命令行工具，同时也通过 UI 自动拦截。
工具命令¶
# 生成证据报告（只读，不修改任何数据）
guard_inspect(scope?, workspace?, maxSessions?, includeHeaders?, redact?)
# 查看护栏自身状态与日志
guard_journal(action?, limit?, snapshot?)
自动拦截规则¶
上述拦截规则在插件安装后自动生效。guard_journal 的 action: "trace" 可查看单次操作详情，action: "rollback" 则返回人工回滚指令（无自动回滚功能）。
注意事项与清理¶
数据持久化¶
卸载插件 (dsh plugin --profile <profile> remove dsh-agent-guard) 仅移除注册配置，不会删除任何数据，包括回滚点。如需清理，需手动删除数据目录。
# 清理回滚点数据（手动操作）
rm -rf "$DSH_HOME/agent-guard"
pnpm 残留¶
插件不会清理 pnpm 生成的 node_modules/.bin/dsh-agent-guard* shim 文件，这是 pnpm 的行为，非插件残留。
UI 限制¶
UI 界面严格为只读。没有修复功能、迁移功能或回滚按钮。
结语¶
dsh-agent-guard 为 DSH 提供了底层的安全防线，确保智能体在读取证据的基础上进行操作，防止因误判导致的数据破坏。相关文档与源码可参考社区目录或 GitHub 仓库。
