额外可写路径 0x7a76/dsh-extra-paths

dsh-extra-paths

让 DSH 对一组配置的外部路径首次尝试即可写、无需审批：既覆盖 write/edit 工具，也覆盖 bash 子进程。
插件以服务包装实现，不改 DSH 核心代码，并提供 Web 设置页与「当前工作区解析出的生效根」预览。

安装

需要 DSH 0.1.5 / 0.2.0 / 0.2.1（不在范围内会被安装闸门拒绝）。

dsh plugin --profile <name> add dsh-extra-paths # <name>=你的 profile 名

想从源码安装（开发时）：

pnpm install && pnpm build
dsh plugin --profile <name> add /path/to/dsh-extra-paths # 路径=本仓库的绝对路径

装好后打开 设置 → 插件 里的「Extra paths」卡片，或设置左栏的「额外可写路径」。

配置

写进设置文档 ~/.dsh/settings.yaml 的 extra-paths 段，或直接用设置页（保存即生效，无需重启）。
下面的 <工作根> 是占位符，指你放项目的那个上层目录（绝对路径，或 ~/ 开头的路径）：

extra-paths:
paths:
- <工作根>/notes/home # 用默认 scope/surfaces
- path: ../../notes/home # 相对路径按「会话工作区」解析 scope: always-write
- path: <工作根>/some-repo scope: write
surfaces: [fs] # 只允许 write/edit 工具写

| scope | 会话 read-only | 会话 workspace-write |
| write（默认） | 拒绝 | 可写 |
| always-write | 可写 | 可写 |

surfaces：fs = write/edit/str-replace 工具；shell = bash 子进程。读与执行本来就不受沙箱限制。

相对路径怎么写

相对路径按各会话自己的工作区解析（设置页里可以改「基准工作区」来预览）：

| 写法 | 解析成 | 说明 |
| .. | <工作根> | 工作区的上一层，该目录及其所有兄弟目录都可写 |
| ../某仓库 | <工作根>/某仓库 | 只放行那一个兄弟仓库（比 .. 精确，推荐） |
| ../../notes/home | <工作根>/notes/home | 往上几层再进别的树 |
| ~/notes/home | 家目录下 | 与工作区无关；~user 不展开（与宿主一致） |

模式：按目录结构锚定（不用写死路径）

path 里可以用通配符描述一组目录，于是"路径里存在某个目录"可以变成一个条件：

| 写法 | 命中（授予的根） |
| <工作根>//.worktrees/.. | 每个含 .worktrees 的仓库根（.worktrees 的上级） |
| <工作根>//.worktrees/ | 每个具体 worktree（不碰 .git 与主检出） |
| <工作根>/<某仓库>/.worktrees/ | 某一个仓库下所有 worktree（零遍历开销，最推荐） |
| <工作根>//notes | 每个仓库/项目下的 notes 目录 |

语法： = 恰好一层、 = 最多 3 层（只匹配真实存在的目录，所以"必须存在 .worktrees"是自然结果）；结尾的 .. 在命中之后再上移（因此 …/.worktrees/.. 就是".worktrees 的上级"，不会被词法折叠吃掉）。

安全边界（都是硬约束，不是建议）：

- 通配符前必须有字面量锚点，且锚点至少两层、必须是绝对路径或 ~/ 开头 —— /、~/、/srv/ 一律拒绝
- 遍历不进入 node_modules、.git， 也不进入隐藏目录（.worktrees 本身是字面量，仍在当层匹配）
- 有界： 最多 3 层、目录数 > 4096 或命中 > 256 时整个模式不生效（fail closed，绝不给"部分命中"这种不可预期的授权）；触顶原因会写进告警
- 展开结果缓存 30 秒，因此新建的 worktree 最迟 30 秒被纳入

设置页每行会实时显示解析到的绝对路径（符号链接以宿主的「解析预览」为准），模式行显示命中条数 [生效 ×N] 并列出每个具体根；0 命中或被拦截都会明确说明，所以不必"先保存再看解析对不对"。

已知边界

- 逐路径的"完全不受限"做不到：bash 沙箱是整次调用粒度。
- 相对路径按会话工作区解析，因此同一份配置在不同工作区指向不同目录——设置页的预览会显示实际解析结果。
- Windows 的 shell 侧不放行；always-write 会削弱 read-only 急停按钮对该路径的作用。
- 写在工作区外的文件不会出现在 deliverables 的工作区变更卡片里。