dsh-write-protect
给 DSH 沙箱补上工作区里某一段路径的只读保护, 典型用途是不让模型改 .git. 也可以在 workspace-write 下声明工作区外的额外可写根, 让 bash 与 write / edit 写到相邻目录, 而不必切到 danger-full-access.
write / edit 工具在所有平台都会挡住保护路径, 并放行额外可写根. bash 等命令在 Linux / macOS 上同样生效; Windows 上 bash / pwsh 既挡不住 .git, 也拿不到额外可写根. 读取不受影响.
官方沙箱只有 "整个工作区可写" 和 "全只读" 两档, 管不到工作区内部的某一段, 也不能把工作区外的个别目录并进 allow-list; Codex 一类实现默认会保护 .git, 本插件补这一块.
安装
dsh plugin --profile web add azazo1/dsh-write-protect
固定版本:
dsh plugin --profile web add azazo1/dsh-write-protect#v0.1.2
GitHub Release 同时挂不带版本号的预构建包, 安装时跳过 allowBuilds:
dsh plugin --profile web add https://github.com/azazo1/dsh-write-protect/releases/latest/download/dsh-write-protect.tgz
本地检出用一键脚本 (scripts/install.sh, Linux / macOS, 可传 profile 名, 默认 web):
./scripts/install.sh # 装进 web profile
./scripts/install.sh headless # 装进指定 profile
./scripts/install.sh --dsh-home ~/.dsh --profile web
脚本是检出内工具, 不随 npm 包发布. 它先把当前检出拷进 <profile>/plugins/dsh-write-protect 再 dsh plugin add 注册. 必须先复制: 就地 link 的检出会被 Node 解析回真实路径, 从检出目录向上走不到宿主自己的 @deepseek-ai/*, boot 会报 Cannot find package '@deepseek-ai/dsh-sandbox-local'. 从 npm / GitHub 安装没有这个问题 (pnpm 会把包物化在 profile 里). 复制会跳过 .git / node_modules / .tmp / dist / .agent; profile 模板本身关掉了 peer 自动安装 (autoInstallPeers: false), 所以宿主提供的 @deepseek-ai/* 不会被装进 profile 遮蔽宿主. 装完重启应用生效.
安装后会接管沙箱策略和 write / edit 围栏, Linux / macOS 上还会接管命令沙箱. 改配置即时生效, 不用重启 dsh web.
引擎版本线跟随 @deepseek-ai/dsh-* 的 0.1.6-alpha.1 (peerDependencies 同号). 官方 SandboxProvider.confine() 自 0.1.6-alpha.1 起改为异步 (Promise<ConfinedArgv> 加 signal 参数, 0.1.5-rc.1 仍是同步签名), 本插件的覆写同样异步; 还在 0.1.5 及更早引擎上的部署请继续用 v0.1.1.
展开是有界的, 这一点对"装完插件整个 dsh web 卡住"很关键. policy.resolve() 是同步契约, 而默认保护条目 .git 不带 /, 属于非锚定通配 —— 要找到任意层级的匹配就必须遍历整个工作区. 工作区一大 (把家目录当工作区是一类常见情况), 一次同步遍历就是几十秒到几分钟, 期间 Host 事件循环被占死, 而 resolve() 在 systemPrompt 组装、bash / 终端 spawn、fs 写围栏、设置页预览上都会走到, 于是整个 web 连首页都打不开. 现在的取舍是: 同步遍历最多 500 个队列项 / 50ms, 被截断时先把已找到的路径用上 (广度优先, 浅层优先, 工作区根上的 .git 通常头两项就命中) 并告警, 深层匹配交给后台分片遍历 (最多 20000 项 / 10s) 补齐后自动并入, 补齐结果不会被更差的同步结果覆盖. 家目录级工作区仍可能漏掉最深处的匹配, 需要无条件覆盖时请改用锚定条目 (/.git), 或按仓库分别声明路径.
配置
保护路径的默认值统一定义在 src/constants.ts 的 DEFAULT_READ_ONLY_PATHS, 额外可写根默认空列表 (DEFAULT_WRITABLE_PATHS), macOS broker 加固默认开启 (DEFAULT_HARDEN_BROKER); patch 的 policy 行与设置页部署 base 都由它们兜底. 需要部署级覆盖时在 patch 行显式给出数组或开关:
- id: dsh-write-protect-policy
name: dsh-write-protect
config:
mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
workspaceRoot: !!js process.cwd()
# 部署级覆盖示例.
# readOnlyPaths: ['.git', '//etc/pki']
# writablePaths: ['../shared-scratch', '//tmp/dsh-extra']
# hardenBroker: false
readOnlyPaths 的每一项是一行 gitignore 语义的模式, 数组逐行合并为生效文本:
- 不含
/ 的条目 (如 .git, vendor) 在工作区内任意层级匹配, 覆盖嵌套仓库等场景.
- 以
/ 开头或含中间 / 的条目锚定到工作区根 (如 /.git, dist/a.txt); 字面条目即使尚不存在也保留保护, 例如 git init 之前的 /.git.
// 开头的条目是文件系统绝对路径 (如 //etc/pki), 这是本插件额外支持的写法, gitignore 没有这种形态.- 尾部
/ 表示只匹配目录 (如 build/).
- 通配:
* 匹配单段内任意字符, ? 匹配单字符, [...] 字符类 (含 [:alpha:] 等 POSIX 类), ** 独立成段时递归 (如 a/**/b); \ 转义下一字符 (\#, \!, 尾部空格用 \ 保留).
! 开头剔除匹配项, 按 gitignore 的 last-match-wins 顺序解释; 受保护目录内部无法通过取反重新放行后代.- write / edit 按模式逐路径判定, 与路径是否存在无关; bash / pwsh 侧的保护路径是枚举出来的, 只覆盖展开时刻已存在的路径, 且非锚定通配 (如
.git) 在超大工作区上受展开预算限制 (同步遍历先覆盖浅层, 后台补全再往里补, 仍有未覆盖到的匹配时 Host 日志会告警). 解析时会解开符号链接并去重.
- 置为空列表
[] 即停用保护 (插件仍在, 只是不再多挡任何路径).
writablePaths 的每一项是一行字面路径, 不是 gitignore glob:
- 行首
~ 或 ~/... 展开为当前用户家目录; ~other 不支持.
$NAME 与 ${NAME} 展开为环境变量; 未设置或空值的变量整行丢弃并告警. \$ 保留字面 $.- 宿主绝对路径 (
/tmp/extra) 或 // 前缀 (//tmp/extra) 按文件系统解析.
- 其余相对当前会话工作区, 含
.. (如 ../sibling-project).
- 工作区内的路径本来就可写, 展开时忽略并告警; 文件系统根 (
/ 或盘符根) 拒绝, 避免把只读宿主根整棵翻成可写.
- 不支持通配与
! 取反. 不存在的路径仍保留词法形态: write / edit 与 Seatbelt 可按前缀放行, bwrap / Landlock 在叠加时跳过并告警.
- 只在
workspace-write 下并进 allow-list, 不打穿 read-only. 保护路径优先: 额外根内部仍可被保护.
- 置为空列表即不额外放行.
hardenBroker 是 macOS broker 逃逸加固的部署 base, 布尔值, 缺省 true:
- 开启时在 Seatbelt profile 末尾追加 broker 拒绝形式 (见 "保护范围").
- 关掉后命令按官方 profile 运行, 只影响 macOS, 只影响这一个加固; 保护路径与额外可写根照常.
- 用户在设置页拨动开关后该值不再生效.
设置页
写入保护设置页
Web Settings 侧边栏的 "写入保护" 页面有三块内容: 保护路径 (gitignore 语义), 额外可写根 (字面路径) 和 macOS broker 加固开关. 保存后实时生效并持久化:
# 保护路径
.git
secrets/*.pem
!secrets/example.pem
# 额外可写根
../shared-scratch
~/scratch
$HOME/scratch
/tmp/dsh-extra
- 保护路径:
# 开头是注释, 空行忽略; ! 排除, 按最后匹配生效; 不能在仍受保护的目录内部重新放行后代. 通配与锚定语义同 "配置" 一节. Windows 上的绝对条目写作 //C:/Users/me/secret: gitignore 语义里 \ 是转义符, / 才是分隔符.
- 额外可写根: 每行一条字面路径, 不要通配.
~ / ~/... 为家目录, $NAME / ${NAME} 为环境变量; 绝对路径按文件系统解析, 相对路径 (含 ..) 相对当前会话工作区. Windows 上 \ 是分隔符而不是转义符, C:\Users\me\caches 与 ~\caches 都按字面解析; 盘符相对路径 (C:caches) 的落点取决于进程当前目录, 会被拒绝并出现在 "未生效" 里.
- 两份文本都按当前会话的工作区根解析, 每个会话各自生效. 开关是全局的, 与工作区无关.
- 预览按钮把当前草稿交给 Host 展开, 不必先保存: 列出生效的保护路径与额外可写根, 以及被忽略或拒绝的行. 展开使用当前选中会话的 cwd; 没有选中会话时回退到部署工作区根 (通常是
dsh web 的启动路径). 预览走异步完整展开 (不受同步的短预算影响), 在家目录级工作区上要等几秒, 期间不会阻塞 dsh web; 到异步预算上限时返回已展开的部分并在 "未生效" 里说明.
mode 与 workspaceRoot 是官方 policy 行字段的复述 (patch 对整行配置做替换, 必须带上), 取值语义与 base bundle 一致.
保护范围
保护路径与额外可写根会同时作用在下面几个入口, 解析结果是同一份:
| 入口 | 哪些系统 | 效果 |
|---|
| write / edit 工具 | 全平台 | 按保护模式逐路径判定, 命中即拒绝 (与展开预算无关); workspace-write 下额外根放行 |
| bash 等命令 | Linux, macOS | 内核级只读 / 额外可写; Windows 做不到, 见下方限制 |
| 提示词 | 全平台 | 先告诉模型哪些不能写, 哪些额外根可写 |
| macOS broker 加固 | macOS | 堵住 open 经 launchd 把命令挪到沙箱外执行 |
两类入口的判定方式不同, 这是有意的: write / edit 拿得到目标路径, 因此直接按 gitignore 模式判定 —— 深层嵌套、尚未存在、枚举没覆盖到的匹配一样挡得住, 每条写入只做几次正则; bash 的沙箱 (mount / profile) 只能吃具体路径, 所以那一侧才需要枚举展开, 也才有预算与补齐这回事.
主场景是 workspace-write. read-only 下官方已挡住全部文件写入, 额外可写根不打穿; 但官方 profile 的 (allow default) 在两种模式下都一样, 所以 broker 加固不区分模式.
macOS broker 逃逸加固
官方 macOS profile 是 (version 1) (allow default) (deny file-write*) ..., mach-lookup 与 process-exec 全开. 而经 launchd 代理启动的进程不继承 Seatbelt profile, 于是沙箱内一条 open x.app 就能让启动的进程在沙箱外任意读写, deny file-write* 被整条绕开 —— read-only 同样会被打穿. 本插件在 profile 末尾追加:
(deny mach-lookup (global-name-prefix "com.apple.coreservices"))
(deny appleevent-send)
(deny mach-priv-task-port)
SBPL 按 last-match-wins 解释, 追加在末尾才能盖过 (allow default). com.apple.coreservices 是 LaunchServices 的服务名段, open / NSWorkspace 靠它把请求交给 launchd; 名称过滤器按 reverse-DNS 分段匹配, 所以只能整段拒绝, 收窄到子服务无效. appleevent-send 关掉让别的 app 代劳那条路, mach-priv-task-port 关掉注入已运行进程的 task port.
加固只做收紧, 不放宽任何位置; 常规命令 (node, git, pnpm, python, curl, tar, rsync 等) 不受影响.
设置页的 "macOS broker 逃逸加固" 开关与 patch 的 hardenBroker 控制这一个加固是否生效, 缺省开启. 关掉后 provider 原样返回官方 argv, 适合确实需要从沙箱内驱动宿主 GUI 的场景; 关掉即恢复可以被 open 打穿的状态. 保护路径与额外可写根的叠加不受这个开关影响.
patch 配置和设置页文本走同一套解析.
边界与已知限制
- Windows 上 bash 挡不住, 也放不宽: write / edit 能挡保护路径、能放行额外根; bash / pwsh 两者都不行. Windows 沙箱只能把整个工作区设成可写或不可写.
- broker 加固只在 macOS 生效: 官方 macOS profile 的
(allow default) 让 open 能把命令交给 launchd 在沙箱外跑, 本插件追加的拒绝形式堵住这条路. Linux 的 bwrap 用 mount namespace, 没有 launchd 那类代理通道, 但它的网络命名空间未隔离, 沙箱内仍可连宿主守护进程 (Docker socket, ssh-agent 一类) 让外面代劳, 这类问题本插件不处理.
- Linux 没有 bwrap, 落到 Landlock 时: 没法单独保护子路径, 命令按官方沙箱跑并告警一次; 额外可写根可以加
--rw. write / edit 两者都生效.
- 完全放开沙箱时 (
danger-full-access): bash 不进沙箱, 挡不住; write / edit 仍然挡.
- Linux bwrap 要求路径真实存在: 通配扫出来的保护路径如果当时还不在磁盘上, 会跳过这条只读挂载并告警. 需要无条件保护的工作区根路径请用字面条目 (如
/.git); 字面条目即使还不存在, write / edit 也会拒绝.
- 枚举只覆盖展开当时已经存在的路径 (只影响命令侧): bash / pwsh 的保护路径清单是枚举出来的, 新建路径最迟在下一次展开时纳入; 部分 (被预算截断) 结果缓存 5 秒后重算, 完整结果与已放弃补全的根缓存 60 秒; 已经要保护的目录不会再往里扫, 里面的匹配项不再单独列出; 被
! 放行的目录还会继续找. 目录符号链接不跟随, 避免扫到工作区外. write / edit 不受这条限制: 它直接按模式判定, 新建的 .git 立刻就被挡.
- 超大工作区上只有命令侧是有界覆盖: 家目录级工作区里更深、更靠后 (广度优先队列更晚) 的匹配可能落在同步预算与后台补全预算之外, 此时 Host 日志会告警. write / edit 仍然是完备的 (按模式逐路径判定); 要让命令也无条件挡住, 请用锚定条目 (
/.git) 或按仓库分别声明路径, 别依赖 **/.git 一类的全局通配.
- 尾部
/** 按那个目录本身保护: 和保护其下全部后代等价, 同时避免枚举全部后代, 代价是该目录自己也写不了.
- 指向保护目录内部的符号链接会被拒绝, 指向外部的不受影响.
本地开发
just install # 安装依赖
just typecheck # TypeScript 类型检查
just build # 构建 lib/
just test # 测试套件 (Seatbelt e2e 仅在 macOS 上运行)
just verify # 以上全流程 + 打包预览
改完源码想在真实 DSH 里手工验证时, 先 just build, 再用 ./scripts/install.sh 把当前检出装进 profile (脚本装的是 lib/, 源码比产物新时会提醒).
源码分三块, 边界是"有没有文件系统依赖":
| 文件 | 职责 | 依赖 |
|---|
src/gitignore.ts | gitignore 语义的解析、编译与逐路径匹配 (含 PatternSet.match), write / edit 围栏的判定核心 | 纯字符串/正则, 零运行时依赖 |
src/patterns.ts | 把模式枚举成具体路径 (有界同步 + 后台分片补全), 供 bash 沙箱与提示词使用 | node:fs、canonicalPath |
src/fs.ts / src/policy.ts / src/provider.ts | 三个挂载点: write/edit 围栏、沙箱 policy、进程沙箱 argv 叠加 | DSH 引擎 |
src/path-expand.ts 负责额外可写根的字面路径展开 (~ / 环境变量 / 平台差异).
测试覆盖: 纯匹配器语义 (锚定, **, 字符类, 取反, 前缀围栏, 目录标记, 大小写, 工作区外不match; 不需要任何临时目录), 路径解析语义 (相对锚定, 解开符号链接, 去重, 通配枚举与取反, 额外可写字面路径), 展开预算与异步补全 (同步截断时先给浅层结果, 后台补全后深层匹配出现且不被更差的同步结果覆盖), write / edit 按模式判定 (启动后才出现的深层路径、尾部 / 与同名文件、工作区边界), bwrap / Seatbelt / Landlock 的命令行叠加, write / edit 工具的拒绝与额外根放行矩阵, settings 通道的 base 与用户覆盖分层, client bundle 的 loader 注册, macOS 上真实 sandbox-exec 的内核级端到端 (包括 open broker 逃逸的对照组与加固后的拦截验证), 以及 Linux 上真实 bwrap 的内核级端到端 (保护路径写入 EROFS, 读取照常, 额外可写根可写; 本机 bwrap 不可用时整组跳过).
License
MIT
