目录白名单wangzhaonan16/dsh-fs-allowlist

dsh-fs-allowlist

功能总览

| 层 | 机制 | 覆盖 |
|---|---|---|
| write/edit 工具 | 包装 ctx.fs.checkedTarget 栅栏，白名单路径提前放行 | 知识库读写全免审批 |
| bash 命令 | 审批瀑布监听器：bash 升权理由命中白名单路径时自动 allowed-once | bash 写知识库免审批（文本启发式，未命中转人工） |
| 设置页 GUI | settings.plugins.tab 注册「目录白名单」页签 + 服务端 HTTP 管理路由 | 可视化增删目录、开关 bash 代答 |

配置支持热更新：GUI 修改即时生效；手动编辑配置文件 3 秒内自动生效，均无需重启 DSH。

原理

write/edit 层

DSH 的 write/edit 工具写入前都经过 dsh-fs-sandbox 挂载的 ctx.fs.checkedTarget() 栅栏（工作区外 → 抛 FS_SANDBOX_DENIED → 模型升权重试 → 审批弹窗）。本插件包装该栅栏方法：

- 目标路径 canonical 解析后落在白名单内 → 提前放行（返回与栅栏一致的解析结果）；
- 未命中 / read-only 模式 / 解析失败 → 原样委托原栅栏，行为分毫不变。

原子写、版本守卫、先读后写检查、diff 事件等文件语义全部位于栅栏之下的 dsh-fs-local，本插件不触碰。白名单判定与栅栏使用相同的 realpath（最深已存在祖先）语义，symlink 换向逃逸不成立。

bash 层（审批代答）

bash 走 Seatbelt 进程沙箱，白名单无法从插件层注入 profile；取而代之的是注册 approval/request 瀑布监听器：当请求来自 bash 工具、且升权理由文本中出现白名单路径（绝对路径或 ~ 缩写）时，自动应答 allowed-once，不弹人工审批。这是对模型所写理由的文本启发式：未命中一律转人工（失败安全）；开启即表示信任模型对升权理由的描述。可在设置页随时关闭。

安装

dsh plugin --profile web add /path/to/dsh-fs-allowlist

发布到 GitHub 后也可以直接：

dsh plugin --profile web add "github:wangzhaonan16/dsh-fs-allowlist#main"

装入 $DSH_HOME/profiles/web 并自动登记，重启 DSH Desktop 后生效（刷浏览器不够）。本插件源码目录被 profile 以 link: 方式引用，改源码后重启即生效，无需重装。

配置

$DSH_HOME/fs-allowlist.json（主目录解析与官方一致：$DSH_HOME 优先，桌面版按平台取 userData——macOS ~/Library/Application Support/dsh-desktop/harness、Windows %APPDATA%\dsh-desktop\harness、Linux $XDG_CONFIG_HOME/dsh-desktop/harness——再回退开源版 ~/.dsh）：

{
"extraWritableRoots": [
"/Users/wangzhaonan/zhaonan/ObsidianVault"
],
"bashAutoApprove": true
}

- 推荐通过 设置 → 插件 → 目录白名单 调整，免手编；
- 文件缺失 / JSON 非法 / 空列表 → 白名单为空，插件等效透明（= 未安装的行为），即一键回退；
- bashAutoApprove 缺省视为 true。

行为矩阵

| 场景 | 行为 |
|---|---|
| write/edit 写入工作区内 | 免审批（原生行为，不变） |
| write/edit 写入白名单目录 | 免审批直写 |
| write/edit 写入其他路径 | 拒绝 → 升权 → 审批（不变） |
| read-only 模式写白名单 | 仍拒绝（尊重更严旋钮） |
| bash 写白名单目录（理由命中） | 自动放行，不弹审批 |
| bash 其他升权（理由未命中） | 正常弹审批 |

已知边界

1. bash 代答按升权理由文本匹配，属启发式：极端情况下模型理由未写清路径会多弹一次审批（失败安全）；反之信任理由即信任该次调用。
2. checkedTarget 属于 DSH 随包内部方法：大版本升级若重构该方法，本插件以「告警 + 透明降级」失败（等效回到现状），不会破坏会话，届时跟版适配。
3. 白名单 = 授权 agent 对该目录免审批写入，请刻意收窄范围。

回滚

dsh plugin --profile web remove dsh-fs-allowlist（或清空 fs-allowlist.json）+ 重启 DSH。