DSH plugin 权限预设表:auto 注册、custom 派生与切换事件到底该怎么读
“切了预设但行为没变”,多半是因为新预设与旧预设共享同一组旋钮,真正生效的只有那两条底层事件。 DSH plugin 的权限预设层不拥有执行策略,它只把 sandbox/mode 与 approval/policy 捆成具名选项。读懂这层捆绑关系,才能解释切换后的现象。 DSH插件 切了预设却没变化,先看两个预设是不是共用同一组旋钮。
预设只是两个旋钮的具名捆绑
它不执行策略,只写旋钮。(来源)
dsh-permission-presets 的权限预设层(ctx.permissionPresets)把两个相互独立的强制执行 knob——沙箱模式 sandbox/mode 与审批策略 approval/policy——捆绑成具名预设,供客户端作为单个 Permissions 选择器提供。
配置表拥有未来会话默认值,而固定的 registerAuto(admit) 钩子让 Auto review integration 在一个 effect 生命周期内发布仅限当前会话的选项。
这一层是可选能力,且不拥有执行策略:提示词叙述与回放仍读取各自 knob 的折叠结果,额外强制执行由 Auto review 拥有。所以“预设”不是一个权限系统,而是两个系统的组合快捷方式。
预设表与两个保留名
custom 与 auto 不能配置,配置了会在加载时炸。(来源)
PresetSpec 包含 sandbox、approval,以及可选 name 与 description(客户端展示信息)。默认配置表自带两项:
workspace-write—workspace-write+ask;danger-full-access—danger-full-access+never。
Config 有 presets 与 defaultPreset。defaultPreset 省略时,使用与组合后的 sandbox 与 approval 默认值匹配的那个预设。
该服务要求一个施加隔离的 ctx.shell 执行器与 ctx.approval,配置错误在插件加载时即失败:名为 custom 或 auto 的条目会抛异常;在不施加隔离的 bash 执行器(没有 sandboxMode 能力事实)之上组合同样抛异常,因为预设捆绑了一个沙箱模式。
这条加载期失败比运行期报错好排查得多:看到插件起不来,先检查预设名与执行器能力。
Auto 是固定的当前会话注册
Auto 不能被“注册成另一个预设”,它只能由固定钩子发布。(来源)
Auto integration 会在自身 effect 生命周期内调用 registerAuto(admit)。服务固定 auto 身份以及 danger-full-access 加 ask 的组合,已记录的 Auto 选择也匹配委派子会话固定的 never 策略。
展示归属也分得清:shipped 客户端的 locale 字典拥有 Auto 的 label 与 description,而配置预设的展示信息仍归 Host 所有。调用方不能通过通用 contribution API 发布其他预设。
Auto 排列在配置预设之后,绝不会进入 permission.defaultPreset 设置 schema,并在 effect dispose 时消失。
admit 是同步回调,会在 Auto 选择修改 Session 之前、以及存储的 Auto Session 发布之前运行。因此 integration 缺失或正在关闭时,不会改写持久身份——这是自动审批在会话恢复场景下的安全边界。
目录变更不发会话事件
目录是进程级快照,会话投影只有 currentValue。(来源)
注册或移除 Auto 会发出无 payload 的 permission-presets/catalog-changed 通知。进程级消费方要先订阅,再调用 catalog();每次收到通知后重新读取完整的可选目录。
permissions Session 投影只包含 currentValue,因此目录变化不会追加 Session 事件、不发布 Session 投影帧,也不改变 Session 序列。这条设计让“客户端菜单变了”与“会话历史变了”彻底分开。
current 与派生的 custom
custom 是算出来的当前值,不是可选项目。(来源)
current(session) 从必需的 permissions 投影派生实际生效的预设。该单元折叠会话的沙箱模式、审批策略与已记录选择;状态内部的缺失值回退到执行器配置的模式与审批服务配置,最后回退到 ask。投影 key 缺失时会显式失败。
选择顺序是:优先取仍然匹配的选择(包括 never 审批策略下已记录的 Auto 选择),其次取第一个匹配的配置条目,否则返回 CUSTOM_PRESET('custom')。
custom 只是派生值:客户端可以把它显示为当前值,但它绝不是切换目标,也绝不出现在事件 payload 中。
names 先按声明顺序列出配置预设,再在 Auto integration 存活时列出 Auto。catalog() 把这些条目作为进程级快照返回。optionOf(name) 为可用条目(label 回退为该 key)或派生的 custom 构建选项,传入其他任何名称都会抛异常。
客户端把目录与 Session 投影合并:custom 可以标记当前值,但绝不会成为目录条目。
切换顺序:先记选择,再写变化的旋钮
set 的写入是有条件的,重选同一个预设什么都不写。(来源)
set(session, name) 的执行顺序:
- 解析预设,未知名称抛异常;
- 在适用时运行 Auto 准入;
- 在
name尚不是生效预设时追加一条仅记日志的permission/preset事件; - 通过各旋钮自己的 setter(
setSandboxMode与setApprovalPolicy)写入,且仅当该 knob 的生效值发生变化时才写。
同一轮次内,选择事件先于旋钮事件出现;重新选择当前生效的预设则什么都不追加。
permission/preset 是持久、仅记日志的用户意图:它不进入模型 transcript,模型可见的后果由 knob 事件经各自消费方承担。它存在的理由很具体——两个预设可能共享同一个旋钮组合,没有这条事件,current() 就保不住用户选的究竟是哪一个。
permissions 投影把该选择与两个 knob 事件一同折叠,并保留用于区分空恢复 seed 与新会话的 session/end-seed 边界;回放不需要任何追赶状态或原始日志重扫。恢复的 auto 选择在 agent 发布前必须存在 live Auto 注册。
验证:连续切换预设
验证要覆盖“只写变化”与“共享组合仍能分辨”两件事。(来源) 六步:
- 新会话读
current(),断言是默认预设而非custom。 - 调
set(session, 'danger-full-access'),断言先出现permission/preset,随后出现两个 knob 事件。 - 再次
set同一个预设,断言没有新增任何事件。 - 配置两个沙箱与审批完全相同的预设,来回切换,断言
current()能回报最后的那个名字。 - 手动改审批策略到某个不匹配任何预设的组合,断言
current()返回custom。 - 移除 Auto integration 后再读
catalog(),断言 auto 条目消失,且会话序列没有变化。
如果第 4 步返回了第一个匹配项而不是最后一次选择,说明 permission/preset 没被投影折叠进去。
预设与审批策略的关系,可以对照权限与审批设置;auto 死锁的排查见权限预设 auto 死锁。
一句话收束: 预设是两旋钮捆绑,custom 与 auto 都不可配置,auto 只由固定钩子发布,custom 只是派生值,set 只写变化且选择事件先行。
常见问题
不能,DSH plugin 把 custom 与 auto 都列为保留名称。DSH plugin 在加载时发现名为 custom 或 auto 的配置条目会直接抛异常,配置错误不会拖到运行期。
不能,DSH plugin 的 custom 只是派生值。DSH plugin 允许客户端把它显示为当前值,但它绝不是切换目标,也绝不出现在事件载荷里。
不会,DSH plugin 在这种情况什么都不追加。DSH plugin 只在 name 还不是生效预设时才追加 permission/preset,并且只在旋钮生效值真的变化时才写旋钮。
不会,DSH plugin 的 permissions 投影只包含 currentValue。DSH plugin 的目录变更不追加会话事件、不发布投影帧、也不改变会话序列。
相关术语
- PresetSpec
- PresetSpec 是一个预设的沙箱与审批捆绑,含 sandbox、approval 与可选的展示名称与描述。— packages/interaction/permission-presets/src/index.ts
- registerAuto
- registerAuto 是固定的当前会话 Auto 注册钩子,只在调用方 effect 生命周期内发布 auto 选项。— packages/interaction/permission-presets/src/index.ts
- CUSTOM_PRESET
- CUSTOM_PRESET 是没有可用预设匹配旋钮组合时返回的派生值,字符串形式为 custom。— packages/interaction/permission-presets/src/index.ts
- permission/preset
- permission/preset 是持久、仅记日志的用户意图事件,用于在多个预设共享同一旋钮组合时保住用户的选择。— packages/interaction/permission-presets/src/index.ts
来源
- DeepSeek Harness 官方参考 - 权限预设· deepseek-ai
- packages/interaction/permission-presets/src/index.ts· deepseek-ai