dsh-extra-paths

English | 中文

让 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 的工作区变更卡片里。