回滚权限闸门 ChaoJie0/dsh-tm-guard

dsh-tm-guard

给 macOS 上的 DeepSeek Harness（DSH）智能体用的零干预权限闸门。 本地、可回滚的操作——能通过本地 git 基线或 macOS Time Machine 撤销的写入——自动放行并打检查点；网络访问、安装软件包、系统/进程管理、远程 VCS，以及读取敏感凭据路径，一律拦截并记入审计。智能体在受保护的工作区里无人值守地运行，不弹任何审批提示。

核心规则：能回滚的操作放行；不能回滚的操作拒绝。

快速开始（2 分钟）

1. 安装：dsh plugin --profile <name> add dsh-tm-guard（见安装）。
2. 确认已加载：启动配置档——控制台会打印 [tm-guard] Loaded. Protected paths: ...（见验证安装）。
3. 保护你的工作区：默认已经保护 process.cwd()，拒绝网络/系统操作，并拦截 12 条敏感凭据路径的读取。要保护更多目录，把 protectedPaths 加进配置档的 cordis.patch.yml（见配置）。
4. 解锁你明确信任的工具：subagent、workflow、web_search、web_fetch、skill……默认全部拒绝（归类为 mixed/unknown）。把你信任的那些加进配置档 cordis.patch.yml 的 extraAllowTools。⚠️ 千万别加 subagent / subagent_fork / workflow / job_output——允许列表会直接短路分类器（见限制）。

最影响体验的两个字段：protectedPaths（智能体能写哪里）和 extraAllowTools（哪些工具绕过闸门）。其余都有安全默认值。

这是什么——不是什么

它是 DSH 的 Cordis 插件 / bundle：一个 npm 包（dsh-tm-guard），声明 dsh.bundle.patch，挂上 DSH 的 tools/pre-execute waterfall，注册 tm_ 模型工具，并注入一段运行模式系统提示词。它用官方的 dsh plugin add 流程安装，跑在 DSH 宿主进程里，权限跟宿主一致。

它不是：

- Claude Code 插件（没有 Claude Code 插件清单，也没有 Claude Code 钩子），
- VS Code 扩展，
- 独立命令行或产品，
- 安全沙箱（见限制与诚实边界）。

前置条件

- macOS，文件系统为 APFS。插件会调用 /usr/bin/tmutil，并使用本地 APFS 快照；不支持非 macOS 系统。
- Time Machine 已配置备份目标，且工作区所在的卷由 TM 备份、不在 Time Machine 排除列表里。验证：

tmutil destinationinfo
tmutil listlocalsnapshots /

- 给运行 dsh 的终端/应用授予 Full Disk Access（可浏览备份恢复和部分 tmutil 操作需要），前提是你想从已完成的备份自动回滚。在普通用户卷上创建本地快照本身不需要 sudo。
- git 在 PATH 中，用于主要的即时回滚网（每个可写目录会自动创建本地基线；所有 git 操作都在本地/离线进行）。
- 已安装 DSH CLI，且匹配 package.json 中的 peer 范围 —— 当前为 @deepseek-ai/cordis >=4.0.0 和 @deepseek-ai/dsh-tools >=0.1.0-rc.1 <0.1.0 || >=0.1.0 <0.1.2-0 || >=0.1.2-0 <0.2.0-0 || >=0.2.0-0 <0.3.0-0（覆盖 dsh 0.1.x，包括 0.1.2-rc.1，以及 dsh 0.2.x，包括 0.2.0-rc.2）。

安装

DSH 配置档通过 dsh plugin --profile <name> ... 安装树外包（转发到配置档目录内的 pnpm）。配置档名字随便取，比如 web，或者用完即弃的 tm-lab。

从 npm 安装（推荐）

预构建的 lib/ 随包发布，所以不需要构建步骤，也不需要批准构建脚本：

dsh plugin --profile web add dsh-tm-guard

从 GitHub / 源码安装

pnpm >=10 blocks git-dependency build scripts until you allow them.
The package's prepare script runs its zero-dependency build (see Development).
dsh plugin --profile web add github:ChaoJie0/dsh-tm-guard

如果安装卡在构建脚本批准上，把 pnpm 打印出来的 key 加到配置档的 pnpm-workspace.yaml：

allowBuilds:
dsh-tm-guard: true

然后重新运行命令。这项允许等于授权该包在安装时于你机器上运行代码；审计供应链时请锁定 commit：github:ChaoJie0/dsh-tm-guard#<sha>。

本地检出（测试）

git clone <repo> dsh-tm-guard
cd dsh-tm-guard
npm install # no runtime deps; runs prepare → builds lib/
dsh plugin --profile tm-lab add .
or a packed tarball: npm pack → dsh plugin --profile tm-lab add ./dsh-tm-guard-0.1.0.tgz

直接源码覆盖（仅开发用）

不安装，直接把 TypeScript 源码通过本地 overlay 文件加载进运行中的 DSH（路径因机器而异；这是维护者检出里附带的文件，不是 bundle 补丁）：

dsh web --patch "/abs/path/to/dsh-tm-guard/cordis.patch.local.yml"

验证安装

1. The composed tree must contain a dsh-tm-guard layer with a tm-guard row:
dsh --profile tm-lab --dump-config | grep -A2 'dsh-tm-guard'
== dsh-tm-guard
- id: tm-guard
name: dsh-tm-guard

2. Boot the profile — the console should print: [tm-guard] Loaded. Protected paths: ... Audit log: ... Deny-read paths: ...
dsh --profile tm-lab

3. In a session, the registered tools are available — ask the agent to run tm_status, or call tm_audit to inspect the gate log.

干净卸载：

dsh plugin --profile tm-lab remove dsh-tm-guard

工作原理

agent tool call
│
▼
ctx.on('tools/pre-execute') ← 注册时带 prepend：最先运行
│
├─ 对工具分类，并解析每一段 bash（按 ; && || | 拆分命令链）
├─ 静态脚本外发扫描（检查解释器脚本，见限制说明） ├─ 用 protectedPaths / denyReadPaths 校验目标路径 ├─ 为写入目录确保存在本地 git 基线（可即时回滚） ├─ git 网络不可用时做 fail-closed 健康检查（Time Machine） └─ 放行（先建检查点）或拒绝，并给出可审计的理由

三类决策：

1. 本地、可逆 —— 读取；在 protectedPaths 下写入；本地/离线 git（init/add/commit/reset/checkout/restore/clean/stash/...）；已识别的本地执行器。放行。首次写入前确保 git 基线存在，并创建 APFS 快照（受 snapshotCooldownSeconds 限流）。
2. 不可逆 / 非本地 —— 网络命令（curl、wget、ssh、git push/pull/clone/fetch）、包管理器（npm/pip/brew/cargo/... install）、进程/系统管理（kill、sudo、launchctl、shutdown）、子代理委派、灾难性模式（rm -rf /）。拒绝。
3. 敏感读取 —— 任何触及 denyReadPaths 的操作（默认：~/.ssh、~/.aws、~/.gnupg、~/.kube、~/.docker、~/.netrc、~/.git-credentials、~/.npmrc、~/.pypirc、~/.config、~/Library/Keychains、~/Library/Cookies），包括重定向夹带（cat ~/.ssh/config > project/out.txt）。拒绝并审计。

任何无法识别的操作默认拒绝（保守策略）。对于本地执行的解释器脚本，插件还会对入口文件、内联 -c/-e 代码和 heredoc 正文做一次静态、只读的外发扫描 —— 并沿本地 import 向下追踪几层 —— 标记真实的外发请求或无法验证的 eval/exec/__import__。

回滚。 本地 git 是主要机制（即时、离线、无需 root，覆盖已跟踪文件以及基线之后新建的文件）。Time Machine 是灾难恢复的兜底。tm_rollback 按顺序尝试：(1) 从可浏览的已完成 TM 备份复制（tm-backup，需要完全磁盘访问权限），(2) 挂载本地 APFS 快照（manual-mount，需要 root），(3) 打印精确的手动操作说明（manual）。

审计与报告。 每次放行/拒绝都会追加到 <workspace>/.tm-guard/audit.jsonl（工具、类别、理由、目标路径、快照 id）。每轮智能体结束且有工具活动后，会向 .tm-guard/reports/turn-<timestamp>.md 写入一份结构化 Markdown 报告，并附独立验收检查。autoApprove 开启时（默认开启），对于前置门禁已放行的调用，插件会用 allowed-once 回应 DSH 审批请求 —— 正是这一点让运行过程无需人工确认；只有预先放行的调用才能走到这一步。

已注册工具

| 工具 | 用途 |
| tm_snapshot | 创建 Time Machine 本地 APFS 快照检查点；接收 note 标签，返回快照日期 id。 |
| tm_list_snapshots | 列出本地可用快照及其日期，用来挑选回滚点。 |
| tm_rollback | 恢复指定的 path（可选按 snapshot_date），或设 last_operation=true 撤销审计日志里最近一次写入。 |
| tm_audit | 显示最近的闸门决策（允许/拦截、类别、目标路径、快照 id）；支持 limit、only_writes。 |
| tm_status | 打印 TM 健康状态/目标盘/快照数量、工作区保护、闸门策略和审计日志统计。 |
| tm_backup | 向配置好的 TM 磁盘发起备份；默认后台运行，wait=true 会阻塞，直到生成可浏览的还原点。 |
| tm_backup_status | 显示备份是否在运行、完成百分比和当前阶段。 |

配置

插件在插入的行上接受 Partial<TmGuardConfig>。用户通常在自己的配置档 cordis.patch.yml 里覆盖字段（补丁层按行后者优先；补丁会替换整行的 config）。

| 字段 | 类型 | 默认值 | 含义 |
| protectedPaths | string[] | [process.cwd()] | 智能体可写的绝对路径前缀。 |
| snapshotCooldownSeconds | number | 30 | 两次自动写前 APFS 快照之间的最小秒数。0 表示每次写入前都做快照；负数关闭自动快照。 |
| denyNetwork | boolean | true | 拒绝归类为网络操作的调用。 |
| denySystem | boolean | true | 拒绝进程/系统管理命令。 |
| denyReadPaths | string[] | 上面列出的凭据/钥匙串路径 | 智能体不可读取的绝对路径或 ~ 开头路径。空列表关闭该限制。 |
| extraAllowTools | string[] | [] | 绕过分类、始终允许的工具名。 |
| extraDenyTools | string[] | [] | 始终拒绝的工具名。 |
| verbose | boolean | true | 把每次闸门决策记到宿主控制台。 |
| requireTaskSnapshot | boolean | true | 系统提示词要求多步任务开始前先建检查点。 |
| failClosed | boolean | true | 没有回滚兜底时拦截写入（git 基线建不出来 且 Time Machine 不健康）。 |
| failClosedBlockReads | boolean | false | 兜底不健康时也拦截读取。默认 false，好让智能体自己诊断。 |
| turnReports | boolean | true | 写每轮 Markdown 报告 + 验收检查。 |
| blockingBackupBeforeWrite | boolean | false | 每次写入前跑一次阻塞式完整 TM 备份（慢，吃 SD 卡），而不是即时本地快照。 |
| requireGitBaseline | boolean | true | 文件写入前要求有已提交的本地 git 基线（自动创建）。 |
| autoApprove | boolean | true | 对已通过前置闸门的调用，把 DSH 审批请求直接答为 allowed-once。设为 false 则让审批请求送达用户 / 失败关闭。 |
⚠️ 千万不要把 subagent / subagent_fork / workflow / job_output 放进 extraAllowTools。 允许列表会直接短路分类，所以被白名单放行的子代理工具会绕过闸门的 mixed 类别拒绝，能在没有回滚覆盖的情况下写到 protectedPaths 之外。子代理默认就是 mixed，被拒绝正是这个原因；把它们挡在允许列表之外（见「限制」）。

示例 —— 你配置档里的 cordis.patch.yml（随包发布的 bundle 自己只插入一行裸记录；下面这样才是用户配置的写法）：

- insert:
- id: tm-guard
name: dsh-tm-guard
config:
protectedPaths:
- '/Users/you/projects'
denyReadPaths:
- '~/.ssh'
- '~/.aws'
- '~/Library/Keychains'
snapshotCooldownSeconds: 30
denyNetwork: true
denySystem: true
failClosed: true
requireGitBaseline: true
turnReports: true

限制与真实适用范围

信任这个插件之前，请先读这一节。它提高了无人值守运行的门槛，但并不等于隔离的证明。

- 只支持 macOS + Time Machine。 一切都依赖 /usr/bin/tmutil、APFS 本地快照，以及配置好的 TM 目标盘。没有 Linux/Windows 路径。创建本地快照不到一秒，但要把新的本地快照挂载回来做命令行恢复，需要 root 或 Time Machine 界面 —— 想立刻撤销，还是优先用 git 基线。
- 完全磁盘访问权限很关键。 没有它，从已完成的 TM 备份自动恢复（tm-backup 策略）读不到备份；插件会退回到需要 root 的挂载方式，或打印手动步骤。
- 静态出口扫描有盲区。 它是正则/文本分析，不是执行追踪。运行时拼出来的 URL、eval(decodedBytes)、藏在 Makefile 或 cargo run 后面的目标、未扫描的传递依赖文件里的代码，都抓不到。denyNetwork=true 也拦不住铁了心的行为者走允许的通道。
- 它不是内核级沙箱。 插件以受信任的宿主代码身份运行，用的是 DSH 进程自己的权限；闸门检查的是 harness 路由过来的工具调用。它不限制系统调用。维护者自己的部署把它和 LuLu 搭配使用 —— 那是外部、单独安装的 macOS 网络防火墙，在进程层拦截出站流量（比如禁止 python3/bash 出口，只放行宿主的模型端点）。LuLu 是第三方产品；本插件既不安装也不配置它。
- 命令分类是启发式的。 冷门的一行命令可能被分错；未知情况的默认处理是拒绝。用 extraAllowTools/extraDenyTools 调优，并保持 denyNetwork/denySystem 开启。
- 路径提取是启发式的，写入标志列表是人工维护的。 命令参数携带的路径（位置路径、重定向、key=value 操作数、紧贴的 --flag=value 值）靠模式匹配还原，而不是靠 shell 解析器。写入侧的紧贴标志列表（--output、--outfile、--target-directory、……）是维护者人工整理的允许列表：新出现的写入标志或尚未列入的冷门变体，不会被送到写入保护检查。未知即默认拒绝，让常见情况保持 fail-closed；遇到新的写入标志就审查一下，并让 denyNetwork 一直开着，作为出站兜底。
- 解释器 -c/-e 代码只扫描字面敏感路径。 python3 -c "print(open('/Users/alice/.ssh/id_rsa').read())" 会被拦下，但代码文本本身就是图灵完备的程序——动态拼出来的路径（'.'+'ssh'、os.path.join(expanduser('~'), ...)、解码……）能绕过文本扫描。这个残留缺口由 denyNetwork 出站阻断、审计日志和智能体自身的判断来兜住；如果需要更严格的行为，就把 python3 -c/node -e 从可信工具里移除。
- 子代理默认被阻断，因为子操作无法完整验证；只有当子代理继承同等约束时才启用。
- 面向生产环境或存有大量凭据的机器，除了本插件之外，还要用真正的操作系统沙箱 / 一次性配置档 / 虚拟机、最小权限凭据和出站过滤。安装任何 DSH 插件前先审查源码——插件是受信任的宿主代码，不是沙箱化的智能体代码。

开发

构建是零依赖的，用 Node 内置的 TypeScript 类型剥离（module.stripTypeScriptTypes）。构建机器要求：Node.js ≥ 22.6（或 ≥ 20.19 LTS）。产出的 lib/ 是纯 ESM JavaScript，外加手工维护的 lib/index.d.ts；使用方不需要 TypeScript 工具链。

npm run build # node scripts/build/build.mjs → lib/
npm run prepare # alias of build; run automatically on npm/git installs

项目结构：

src/
index.ts # plugin entry: pre-execute gate, hooks, system prompt, tm_ tools
classifier.ts # tool mapping + bash segment parser + decision matrix
scan-scripts.ts # static egress scan for interpreter scripts / inline code / heredocs
tm.ts # tmutil wrapper: snapshots, health, 3-strategy rollback
git.ts # local-git baseline creation
audit.ts # JSONL audit log
report.ts # per-turn markdown report
verify.ts # independent per-turn acceptance check
cordis.patch.yml # bundle layer (references the package by name)
cordis.patch.local.yml # maintainer-only absolute-source overlay (not published)
scripts/build/build.mjs

冒烟测试是不依赖任何库的 Node 脚本，直接导入 TypeScript 源码（Node 在导入时剥离类型；Node 版本要求与构建相同）：

node --experimental-strip-types test-classifier.mts
node --experimental-strip-types test-scan-scripts.mts
node --experimental-strip-types test-runtime.mts
node --experimental-strip-types test-git-rollback.mts
node --experimental-strip-types test-rollback.mts
node --experimental-strip-types test-verify.mts
node --experimental-strip-types test-report.mts
node --experimental-strip-types test-hook.mts

有些测试会在本机调用真实的 tmutil/git，并创建临时目录；它们不访问网络。

查看将要发布的内容： sh
npm pack --dry-run

许可证

MIT © 2026 dsh-tm-guard contributors。