前言¶
在 DeepSeek Harness（DSH）里用 write / edit 改工作区外的文件时，常见路径是：沙箱拒绝 → 模型带 escalation 重试 → 弹出人工审批。若你经常要把笔记写进 Obsidian 库、或让 bash 在固定目录里落盘，每一步都要点批准，会打断节奏。
dsh-fs-allowlist 针对这类需求：把指定目录加入白名单后，对这些路径的 write/edit 可直接通过；命中白名单的 bash 提权也可自动答复 allowed-once。其余路径行为与未装插件时一致。下面介绍它做什么、怎么装、怎么配。
这是什么¶
dsh-fs-allowlist 是社区维护的 DSH 插件（维护者 wzn16，仓库 wzn16/dsh-fs-allowlist）。一句话：在 DSH 默认沙箱之上，为配置过的目录根开放免审批写入，并提供设置页管理白名单。
插件当前版本 0.3.0（见仓库 package.json），许可证 MIT。目录页：skillhub.cn/plugins/wzn16/dsh-fs-allowlist。SkillHub 等社区目录与 DeepSeek / 幻方无官方从属关系；DSH 生态本身是「一切皆插件」的思路，本插件是其中一条权限扩展路径。
核心功能¶
资料中的能力分三层，可对照下表理解覆盖范围：
| 层级 | 机制 | 覆盖 |
|---|---|---|
| write/edit 工具 | 包装 ctx.fs.checkedTarget 围栏；白名单路径提前放行 |
对白名单根的读写免审批 |
| bash 命令 | tools/pre-execute 索引命令文本；approval/request 在命令或 escalation 理由命中白名单时自动 allowed-once |
对白名单路径相关的 bash 写入免审批（先匹配命令文本，未命中仍走人工） |
| 设置 GUI | settings.plugins.tab 区块 + 服务端 HTTP 管理路由 |
可视化增删目录、开关 bash 自动批准 |
配置热重载：在 GUI 里改立即生效；手改配置文件约 3 秒内生效，无需重启 DSH 进程（安装/卸载插件本身仍见下文「重启 Desktop」说明）。
write/edit 层¶
每次 write/edit 都会经过 dsh-fs-sandbox 挂载的 ctx.fs.checkedTarget()：工作区外默认 FS_SANDBOX_DENIED，再 escalation 与审批。本插件在该围栏外包一层：
- 规范解析后的目标落在白名单根内 → 提前放行（语义与围栏一致）；
- 否则（未命中、只读模式、解析失败）→ 原样交给原围栏。
原子写入、版本守卫、写前读、diff 事件等仍由下层 dsh-fs-local 负责，插件不改动。白名单匹配与围栏相同，使用 realpath（最深已存在祖先）语义，避免通过符号链接逃出名单。
bash 层¶
bash 在 Seatbelt 进程沙箱内运行，配置文件无法由插件扩展。插件用两个监听器配合：tools/pre-execute 按 callId 记录命令文本；approval/request 应答器把命令文本与 escalation 理由中的类路径 token 展开 ~ 后，递归对照白名单根（父目录条目覆盖其下所有子路径）。多数命令文本里会带目标路径，因此不必依赖模型在理由里写全路径。未命中则仍弹出人工审批（fail-safe）；可在设置页关闭 bash 自动批准。
安装与启用¶
本地已有插件源码目录时，安装到 web profile：
dsh plugin --profile web add /path/to/dsh-fs-allowlist
从 GitHub 安装（README 给出的 release 后用法）：
dsh plugin --profile web add "github:wzn16/dsh-fs-allowlist#main"
插件会安装到 $DSH_HOME/profiles/web。安装后须重启 DSH Desktop 才生效（仅刷新浏览器不够）。profile 会链接源码目录，改源码后同样只需重启，不必重装。
回滚示例：
dsh plugin --profile web remove dsh-fs-allowlist
也可清空 fs-allowlist.json 后重启，行为与未配置时一致。
配置¶
默认配置文件路径：$DSH_HOME/fs-allowlist.json（macOS 默认示例：~/Library/Application Support/dsh-desktop/harness/fs-allowlist.json；解析器也支持 $DSH_HOME、Windows %APPDATA%、Linux XDG 以及开源布局 ~/.dsh）。
手改示例（更推荐用 Settings → Plugins → Directory Allowlist 页面，无需手改 JSON）：
{
"extraWritableRoots": [
"/Users/you/ObsidianVault"
],
"bashAutoApprove": true
}
- 文件缺失、JSON 无效或列表为空 → 视为空白名单，插件完全透明（等同未安装），便于一步回滚。
- 未写
bashAutoApprove时默认为true。
行为对照¶
| 场景 | 行为 |
|---|---|
| 工作区内 write/edit | 免审批（原生，不变） |
| 白名单根内 write/edit | 免审批 |
| 其他位置 write/edit | 拒绝 → escalation → 审批（不变） |
| 只读模式下写白名单根 | 仍拒绝（更严开关优先） |
| bash 触及白名单根（命令或理由匹配） | 自动批准，无弹窗 |
| 其他 bash escalation（未匹配） | 常规定审批 |
典型用法¶
- 安装插件并重启 DSH Desktop。
- 打开 Settings → Plugins → Directory Allowlist，添加 Obsidian 库或其它固定写入根（与
extraWritableRoots等价）。 - 需要时在设置页关闭 bash 自动批准；write/edit 白名单逻辑不受该开关影响（见 README 行为矩阵）。
- 在对话中让智能体用 write/edit 或 bash 向白名单路径写入；命中名单时不应再出现「沙箱拒绝 → 重试 → 手动批准」的完整链条。
仓库 README 以 Obsidian vault 作为 extraWritableRoots 示例路径，可按本机实际目录替换。
适用场景与注意¶
适合谁：经常让 DSH 智能体写入工作区外、但范围可控的目录（例如个人笔记库、固定导出目录），并希望减少重复点击审批。
务必知晓：
- 白名单条目意味着智能体可在不询问的情况下写入该树；名单应刻意收窄。
- bash 自动批准依赖命令文本与理由的路径启发式；两者都不含白名单路径时仍会弹窗（by design）。
checkedTarget是发行包内部接缝；DSH 大版本若重构，插件可能降级为「告警 + 透明」（等同未装），需按发行说明适配。- 插件与 DSH 同进程权限运行；安装前请自行审阅 源码与 MIT 许可证。
结尾¶
dsh-fs-allowlist 在不改变工作区外默认沙箱策略的前提下，为少数可信目录打开 write/edit 与 bash 的免审批通道，并用设置页和热重载降低维护成本。需要细节与英文说明时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/wzn16/dsh-fs-allowlist
- GitHub：https://github.com/wzn16/dsh-fs-allowlist
