ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 权限预设表:auto 注册、custom 派生与切换事件到底该怎么读

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness权限预设autocustom
切了预设但行为没变,或 custom 与当前预设互相覆盖。本文讲 PresetSpec 的两个旋钮、auto 为何只能由固定钩子注册、custom 为什么是派生值,以及 set 写入选择事件与旋钮事件的顺序。

“切了预设但行为没变”,多半是因为新预设与旧预设共享同一组旋钮,真正生效的只有那两条底层事件。 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) 的执行顺序:

  1. 解析预设,未知名称抛异常;
  2. 在适用时运行 Auto 准入;
  3. 在 name 尚不是生效预设时追加一条仅记日志的 permission/preset 事件;
  4. 通过各旋钮自己的 setter(setSandboxMode 与 setApprovalPolicy)写入,且仅当该 knob 的生效值发生变化时才写。

同一轮次内,选择事件先于旋钮事件出现;重新选择当前生效的预设则什么都不追加。

permission/preset 是持久、仅记日志的用户意图:它不进入模型 transcript,模型可见的后果由 knob 事件经各自消费方承担。它存在的理由很具体——两个预设可能共享同一个旋钮组合,没有这条事件,current() 就保不住用户选的究竟是哪一个。

permissions 投影把该选择与两个 knob 事件一同折叠,并保留用于区分空恢复 seed 与新会话的 session/end-seed 边界;回放不需要任何追赶状态或原始日志重扫。恢复的 auto 选择在 agent 发布前必须存在 live Auto 注册。

验证:连续切换预设

验证要覆盖“只写变化”与“共享组合仍能分辨”两件事。(来源) 六步:

  1. 新会话读 current(),断言是默认预设而非 custom。
  2. 调 set(session, 'danger-full-access'),断言先出现 permission/preset,随后出现两个 knob 事件。
  3. 再次 set 同一个预设,断言没有新增任何事件。
  4. 配置两个沙箱与审批完全相同的预设,来回切换,断言 current() 能回报最后的那个名字。
  5. 手动改审批策略到某个不匹配任何预设的组合,断言 current() 返回 custom。
  6. 移除 Auto integration 后再读 catalog(),断言 auto 条目消失,且会话序列没有变化。

如果第 4 步返回了第一个匹配项而不是最后一次选择,说明 permission/preset 没被投影折叠进去。

预设与审批策略的关系,可以对照权限与审批设置;auto 死锁的排查见权限预设 auto 死锁。

一句话收束: 预设是两旋钮捆绑,custom 与 auto 都不可配置,auto 只由固定钩子发布,custom 只是派生值,set 只写变化且选择事件先行。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的配置表里能不能自己写一个叫 auto 的预设?

不能,DSH plugin 把 custom 与 auto 都列为保留名称。DSH plugin 在加载时发现名为 custom 或 auto 的配置条目会直接抛异常,配置错误不会拖到运行期。

DSH plugin 的 custom 能当切换目标吗,还是只是派生值?

不能,DSH plugin 的 custom 只是派生值。DSH plugin 允许客户端把它显示为当前值,但它绝不是切换目标,也绝不出现在事件载荷里。

DSH plugin 重新选中当前生效的预设时,会追加日志事件吗?

不会,DSH plugin 在这种情况什么都不追加。DSH plugin 只在 name 还不是生效预设时才追加 permission/preset,并且只在旋钮生效值真的变化时才写旋钮。

DSH plugin 的目录变化会改变会话序列,或触发投影帧吗?

不会,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

来源