dsh-isolation-gate

门禁 · dsh-isolation-gate







给 DeepSeek Harness（DSH）的隔离区授权台：默认禁、名单制、点一下生效、可审计、agent 自己能查。

### ⚠️ 定位与免责声明（先看这段）

这个插件的主战场是 DeepSeek Harness（DSH）+ Windows —— 那是作者每天在用、也是唯一做过完整真机验证的组合。DSH 里的宿主工具执行门、面板、CLI、审计，都是在这个组合下逐项验过的。

别的 harness（Claude Code、ZCode、Gemini CLI、opencode、pi、MCP）和 别的操作系统（Linux、macOS）属于实验性支持：

- 有代码、有单测、CI 也在三平台上跑，但这不等于「在你那儿一定好用」；

- 可能不够完善，也可能因为对方版本一升级就失效；

- 各家的拦截强度也不一样 —— 有的能硬拦（前置钩子），有的只能"提示"（MCP），细节见下方支持矩阵。

欢迎提意见、报 bug、提 PR：<https://github.com/huanlin-labs/dsh-isolation-gate/issues> 。

没验证到的部分我不会写成「支持」；你遇到问题也不是你用错了，是本项目还没覆盖到。

[安装](#安装) · [功能](#功能) · [它拦在哪一层](#它拦在哪一层) · [CLI](#命令行--agent-自查) · [English](./README.en.md) · [更新日志](./CHANGELOG.md)

dsh plugin --profile desktop add dsh-isolation-gate

⭐ 如果它帮你少踩一次坑，点个 Star 能让更多人找到它 —— 这是这个项目唯一的「传播预算」。


这是什么（以及不是什么）

它不是又一个 allow/deny 规则引擎，也不是沙箱本身。

• 别人按「工具 / 命令 / 参数」立规则（dsh-permission-rules、dsh-permissions 这类：allow / deny / ask + glob / 正则）；
• 我们按「目录」立对象：这台机器上哪些目录属于禁区、现在给什么级别、谁改的、agent 自己怎么查。

规则引擎回答的是「这次调用准不准」，门禁回答的是「这个目录开不开」。两者可以叠着用，不冲突。

所以它的核心是管理面：

能力 · 说明

三级 · deny 禁（默认） / read 只读 / full 可读写删

两类受管对象 · 名字（D 根一级目录名，如 Zcode）或 任意绝对路径（如 <drive-root>\Zcode、E:\资料\合作档案\某项目）

默认禁 + 名单制 · 只有名单里的对象受管；未列出的不归它管；新增对象一律先按「禁」处理

一屏开关 · 每个对象一个分段控件（禁 / 只读 / 可读写删），点了即落盘，重启后保持

分组 · 「harness 隔离」「跨家合作」这类命名组；组头一键切三档；组只存在状态文件里，名单仍是"一行一对象"

选择文件夹 · 有原生目录选择器就用它；没有就退回「未入名单的一层目录一键加入 + 文本框」

两个拦截点 · ① 受管辖通道 bin/gate.mjs；② 宿主工具执行门 ctx.tools.guard()（2026-10-21 新增）

审计 · ~/.dsh/dsh-isolation-gate/access-log.jsonl：只记时间/对象/级别/操作/允许与否/理由，不记文件内容

agent 自查 · node bin/gate.mjs status —— 模型/脚本可以直接读策略，不用猜

它拦在哪一层

模型发起工具调用
   │
   ├─ tools/pre-execute  ← ★ 工具执行门（本插件 ctx.tools.guard）
   │      file tools 参数 / shell 命令文本 → 按三级判定 → 拒绝文案回到模型
   │
   ├─ 工具真正执行（read / write / edit / bash …）
   │
   └─ bin/gate.mjs  ← ★ 受管辖通道（agent 显式走它读写受管对象）
          判定不通过 ⇒ 一个字节都不碰

两条路都调用同一个 checkAccess，所以面板、CLI、工具门不会说两套话。

让模型自己管门禁（v1.1+）

插件注册 7 个模型可直接调用的工具，DSH 不必等人点面板：

工具 · 作用 · 权限

gate_status · 看默认级别、受管对象、待批数、授权窗口 · 只读

gate_check · 预判某目标某操作会被放行还是拦下 · 只读

gate_log · 读最近审计记录 · 只读

gate_requests · 看自己提交的待批申请 · 只读

gate_add · 把目录/名字纳入受管，固定为「禁」 · 只收紧

gate_set_level · 改级别；放宽必须带户主授权窗口 · 收紧可直做

gate_request · 提交「想放宽」的待批申请 + 理由 · 申请

不对称规则：模型能读、能加、能收紧，不能自己放宽——放宽只有两条路：

1. 提交 gate_request → 户主在「门禁」面板看到待批卡片 → 批准才生效；

2. 户主主动点「授权 AI 放宽 30 分钟」→ 窗口期内模型可直接放宽，到期自动收回。

没有任何「批准」工具，模型无法自己开门。所有工具调用都进审计日志。

对模型说一句就能用：

用 gate_status 看看现在什么被禁；确认 D:\仓库\合作档案 还是禁的话，帮我提个只读申请，理由写"核对合作档案里的结论"。

在别的 harness 里用（Claude Code 已支持）

策略引擎是纯 Node、跟 DSH 无关；别的 harness 只多一层适配器（读它的事件、喂给同一套判定）。

harness · 状态 · 怎么接

DSH · ✅ 原生 · 装插件（本文其余部分）

Claude Code · ✅ v1.3 起 · PreToolUse hook → bin/gate-hook-claude.mjs，见 docs/CLAUDE-CODE.md

opencode · 🧪 v1.4 起（代码+单测通过，未真机验证） · .opencode/plugins/gate.mjs 或 opencode.json 的 plugin；见 docs/OPENCODE.md

Gemini CLI · 🧪 v1.5 起（代码+单测通过，未真机验证） · .gemini/settings.json 的 BeforeTool → bin/gate-hook-gemini.mjs，见 docs/GEMINI-CLI.md

任何支持 MCP 的 harness（Cursor / Windsurf / Codex / Claude Desktop …） · ⚠️ advisory（只能问，不能硬拦） · stdio MCP 服务器 gate-mcp，见 docs/MCP.md

Codex CLI · 🧪 钩子能力随版本变（先自检再接线） · 通用适配器 gate-hook-generic，见 docs/CODEX.md

任何「stdin JSON + 退出码」钩子 · ✅ v1.7 起通用 · gate-hook-generic（GATE_DENY_STYLE 可选 exit2 / json-claude / json-gemini / text），见 docs/GENERIC-HOOK.md · 有工具前置钩子的，照上面两个适配器写一层；只有 MCP 的只能做事前询问，不能硬拦

共用同一份策略：名单 / 级别 / 审计默认都在 .agents 那三个文件里，DSH 面板里改完，Claude Code 下一次工具调用立刻按新级别判。

所有判定都写审计（channel: hook/claude-code），所以"谁在什么时候试图碰哪个目录"两边一本账。

边界（写在前面）：适配器只管那个 harness 的工具调用——你在终端里手动 cat 它不管；Bash 只靠命令行里的绝对路径判断，cd 后走相对路径会漏判。

各 harness 支持度（诚实矩阵）

「门禁」的本质是执行前拦住。有没有前置拦截点，决定了它是门禁还是记事本：

harness · 拦截点 · 能硬拦？ · 验证状态

DSH · ctx.tools.guard（进程内，能看到工具参数） · ✅ · **真

…(truncated)