dsh-tm-guard: macOS DSH 智能体权限门控插件

前言¶

DeepSeek Harness (DSH) 的智能体在本地 macOS 环境运行时，往往需要文件读写、网络访问或系统管理权限。直接赋予完全控制权存在风险。dsh-tm-guard 旨在为 DSH 提供一个“零干预”的权限门控层，通过策略决策来限制智能体的操作范围。

这是什么¶

dsh-tm-guard 是一个为 DSH agents 设计的权限管理插件。它是一个 npm 包（dsh-tm-guard），属于 DSH Cordis 生态的一部分，而非独立的沙箱或 CLI 工具。插件通过声明 dsh.bundle.patch，挂钩 DSH 的 tools/pre-execute 事件流，在工具执行前进行分类和拦截。

核心功能¶

插件的核心逻辑遵循“可回滚的操作允许执行，不可回滚的操作拒绝执行”的原则。

零干预权限门控：在 DSH 代理运行时自动生效，无需人工持续介入。
基于 Time Machine/APFS 的自动回滚：对于本地可写目录，插件会自动创建本地 git 基线或调用 macOS 快照。如果操作是可逆的（如本地 git 操作），插件会自动批准并记录；如果操作无法回滚（如网络请求、进程终止），则直接拒绝。
阻断与审计：默认阻止网络访问、包管理器安装、进程/系统管理操作。同时，插件内置敏感路径列表，阻断对 SSH 配置、AWS 凭证、GPG 密钥等敏感信息的读取。所有决策均记录在审计日志中。
工具白名单配置：允许通过配置文件扩展受信任的工具列表。

安装与启用¶

安装前需确认环境满足以下条件：
* 系统：macOS 且使用 APFS 文件系统。
* 备份：Time Machine 已配置，工作目录在 TM 备份卷上且未被排除。
* 权限：运行 DSH 的终端/应用拥有“完全磁盘访问”权限。
* 工具：git 在系统路径中。
* DSH 版本：必须与插件的 peerDependencies 范围匹配。

使用官方安装命令添加插件：

dsh plugin --profile <name> add dsh-tm-guard

典型用法¶

安装后，插件会加载到对应的 DSH Profile 中。你需要通过配置文件调整策略。

1. 扩展写入保护范围¶

在 Profile 的 cordis.patch.yml 中添加 protectedPaths，指定智能体可以写入的目录。默认已保护 process.cwd()。

# cordis.patch.yml
protectedPaths:
  - ./my-project/src
  - ./config

2. 解锁受信任的工具¶

默认情况下，web_search、skill 等工具被归类为“混合/未知”并拒绝执行。在 cordis.patch.yml 中添加 extraAllowTools 来白名单化这些工具：

# cordis.patch.yml
extraAllowTools:
  - web_search
  - skill

注意：切勿将 subagent、subagent_fork、workflow 或 job_output 加入白名单，这会绕过分类器，导致安全策略失效。

3. 验证安装与审计¶

启动 Profile 后，控制台日志应显示加载信息。你可以使用插件注册的工具来检查状态：

# 查看门控状态和日志
tm_status

# 查看审计日志
tm_audit

适用场景与注意¶

适用场景：需要在本地 macOS 环境中安全运行 DSH 智能体，特别是涉及代码生成、配置修改或需要联网的场景。
重要提示：
- 插件并非安全沙箱，它运行在 DSH 进程的权限上下文中，依赖宿主系统的权限管理。
- 在生产环境使用前，建议阅读源码并确认许可证兼容性。
- 确保插件版本与 DSH 主版本兼容。

短结尾¶

dsh-tm-guard 提供了一种基于时间机器和本地快照的实用权限管理方案，适合希望在 macOS 上安全部署 DSH 智能体的开发者。更多配置细节与源码可参考 GitHub 仓库。