前言¶

DeepSeek-Harness 的插件生態支持 waterfall 和 serial 兩種分發模式。在多插件協作場景下，Cordis 原生的鉤子執行順序依賴於插件的註冊順序，而這種順序往往由插件的依賴注入（inject）機制驅動，對於互不感知的獨立插件而言，這本質上是非確定性的。

這意味着插件無法可靠地聲明相對順序，例如“auth 必須在 logging 之前執行”。一旦相關插件的依賴關係發生微調，執行順序可能隨機翻轉，導致邏輯錯誤。dsh-plugin-hooks-ordering 插件通過引入確定性的排序算法，解決了這一問題。

核心功能¶

該插件爲 Cordis hooks 提供確定性的 before/after 排序，支持 waterfall 和 serial 兩種分發模式，並提供 DeepSeek-Harness 層支持。具體能力包括：

爲 Cordis hooks 提供確定性的 before/after 排序。
支持 waterfall 和 serial 兩種分發模式。
提供純拓撲排序算法。
支持約束圖 DAG 日誌記錄。
提供 DeepSeek-Harness (dsh) 層支持。

安裝與依賴¶

安裝時需要指定 peer dependency @deepseek-ai/cordis。

pnpm add @tengxiaohtx/dsh-plugin-hooks-ordering
pnpm add @deepseek-ai/cordis

使用方法¶

Waterfall 鉤子¶

Waterfall 鉤子使用洋蔥模型，通過 prepend 監聽器實現前後階段控制。

導入 HookOrdering。
安裝插件並控制目標鉤子。
在 front 和 back 階段註冊參與者。

import HookOrdering from '@tengxiaohtx/dsh-plugin-hooks-ordering'

ctx.plugin(HookOrdering)

// 控制鉤子，控制多次會拋出錯誤
ctx.hooksOrdering.control('request/assemble')

// 註冊參與者：auth 必須在 logging 之前執行
ctx.hooksOrdering.register('request/assemble', 'front', {
  name: 'auth',
  before: ['logging'],
  run: (req) => authenticate(req),
})

ctx.hooksOrdering.register('request/assemble', 'front', {
  name: 'logging',
  run: (req) => log(req),
})

// 註冊參與者：metrics 必須在最後執行
ctx.hooksOrdering.register('request/assemble', 'back', {
  name: 'metrics',
  run: (req) => emitMetrics(req),
})

Serial 鉤子¶

Serial 鉤子沒有 next() 鏈，因此使用 front 協調器（短路）和 back 協調器（盡力而爲）來控制順序。

import { SerialHookOrdering } from '@tengxiaohtx/dsh-plugin-hooks-ordering'

ctx.plugin(SerialHookOrdering)
ctx.serialHooksOrdering.control('turn/stopping')

// front 階段：運行在原生鏈之前，返回非 falsy 值會短路整個分發
ctx.serialHooksOrdering.register('turn/stopping', 'front', {
  name: 'guard',
  run: (turn) => (isAllowed(turn) ? undefined : 'DENIED'),
})

// back 階段：盡力而爲地最後運行
ctx.serialHooksOrdering.register('turn/stopping', 'back', {
  name: 'audit',
  run: (turn) => recordAudit(turn),
})

DAG 日誌記錄¶

插件支持將約束圖（DAG）導出爲 JSON，用於調試順序問題。

安裝時傳入日誌路徑。
通過 dumpDag() 方法獲取當前 JSON 字符串。

ctx.plugin(HookOrdering, { log: './hooks-ordering-dag.json' })

// 程序中獲取 DAG
const dag = ctx.hooksOrdering.dumpDag()

DeepSeek-Harness 集成¶

插件提供 /dsh 入口，用於在 DeepSeek-Harness 層面控制真實的 dsh 鉤子。

在 cordis.patch.yml 中添加插件配置。
插件會自動接管多個包貢獻的鉤子，如 agent/pre-step、tools/post-execute 等。

- insert:
    - id: hooks-ordering
      name: '@tengxiaohtx/dsh-plugin-hooks-ordering/dsh'
      config:
        # hooks: ['agent/pre-step', 'tools/post-execute', 'llm/stream', 'turn/stopping']

分層架構¶

該插件分爲三層，可根據需要選擇使用層級：

算法層：提供純拓撲排序算法和 DAG 渲染器，零依賴，無 Cordis 依賴。
Cordis 服務層：提供 HookOrdering 和 SerialHookOrdering 服務，可在任意 Cordis 應用中控制鉤子。
DeepSeek-Harness 層：提供 dsh 插件和 cordis.patch.yml，用於控制真實的 dsh 鉤子。

注意事項¶

該插件不修改或分叉 Cordis 框架。
通過 prepend listener 實現洋蔥模型。
front 階段會短路 serial 分發。
back 階段是盡力而爲。

總結¶

dsh-plugin-hooks-ordering 爲 Cordis 插件提供了穩定的鉤子執行順序控制。通過拓撲排序和分層設計，它在不破壞框架的前提下，解決了多插件協作中的依賴順序不確定性問題。

dsh-plugin-hooks-ordering

前言¶