事件与拦截：权限门实战

一、先分清：两种"事件"Two Kinds of Events

// ✔ 观察账本里的工具结果（会话事件）
ctx.on('session/event', (_session, event) => {
  if (event.type === 'tool/result') { /* 记录 */ }
})

// ✔ 拦截工具执行管线（Cordis 事件）
ctx.on('tools/result', (exec, result) => { /* 观察 */ })

二、五种派发模式实战选型Dispatch Modes

三、waterfall 深入：洋葱模型The Onion

监听器按注册顺序层层包裹，像洋葱（L05 讲过军规，这里画出形状）：

ctx.on('tools/pre-execute', async (exec, next) => {
  // ── 进门：请求经过我（可检查、可改写 exec）
  if (!await isAllowed(exec)) {
    return { kind: 'deny', reason: 'Denied by policy.' }   // ← 不调 next = 短路定案
  }
  const decision = await next()      // ← 调 next = 交给下一层（洋葱更深处）
  // ── 出门：结果回来经过我（可再加工）
  return decision
})

• 调 next()：把请求委托给后面的监听器，最终拿到它们的结果；不调而直接 return = 短路——后面所有层不执行，你的返回值就是最终结果。
• 对"单一决策"事件（如权限），短路就是设计意图：决策权的监听器短路，只旁观的监听器必须放行。
• prepend: true 可把自己插到最前面执行（少用，需要时很关键）。

四、实战：一个完整的权限门Permission Gate

import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

declare function isAllowed(exec: ToolExecution): Promise<boolean>

export const name = 'permission-gate'

export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()   // 放行给后续策略
  })
}

返回 ask 则转人工审批（L09 讲过的审批弹窗就是走这条路）。注意这个插件没有 inject——监听事件不需要等服务，事件天然在双方都在场时才发生。

五、工具管线四兄弟怎么选Choosing the Hook

工具执行管线上有四个观察/拦截点，选错位置是这类插件最常见的 bug 来源：

记忆口诀：问人 pre、底线 guard、包全程 execute、改结果 post、只看 result。

六、实例：工具调用日志插件A Logger Plugin

import type { Context } from '@deepseek-ai/cordis'

export const name = 'tool-logger'

export function apply(ctx: Context) {
  ctx.on('tools/result', (exec, result) => {
    console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
    const text = result.content
      .map(b => b.type === 'text' ? b.text : '')
      .join('')
    console.log(`[result] ${text.slice(0, 100)}`)
  })
}

选 tools/result 而非 post-execute，因为 logger 只观察不改——选 result 保证你物理上改不了结果，错误从类型系统层面消失。

七、其他高频拦截点Other Hot Points