前言¶

在 DSH 中運行智能體任務後，session/event 日誌會持續累積。對短任務來說，直接查看事件序列可能足夠；對長任務來說，扁平日誌不容易回答幾個問題：哪個調用屬於哪個分支、智能體何時偏離原始目標、是否在同一目標附近反覆重試。

dsh-trajectory-governance 是 DeepSeek Harness（DSH）的插件，用於對智能體軌跡做治理與異常診斷。它消費已提交事件，重建結構化軌跡樹，保存觀測層快照，並運行三類時間異常策略。下面介紹它的定位、核心能力、安裝方式和典型用法。

這是什麼¶

• 倉庫：dfycaly98931680/dsh-trajectory-governance
• 維護者：dfycaly98931680
• 定位：Agent trajectory governance & anomaly diagnosis for DeepSeek Harness (dsh).
• 運行方式：consume-only event subscription，zero kernel modification
• 數據位置：插件獨立 SQLite，目錄爲 ~/.dsh-trajectory-governance/
• 視圖關係：不覆蓋官方 Trajectory 視圖，另提供獨立 GUI tab

核心功能¶

軌跡樹¶

將扁平 session/event 日誌重建爲結構化、多分支的 trajectory tree。

快照¶

保存 observation-layer snapshots，包含 nodeId、context hash 和 branchId。快照可用於在軌跡上標記檢查點，也用於後續回溯或 fork。

異常診斷¶

運行三種時間異常策略：

1. loop deadlock
2. invalid retry
3. goal drift

診斷結果掛載到樹節點，並在獨立 GUI tab 中展示。

告警與中斷¶

提供 alerts、desktop notifications、Cordis bus events 和 webhook posts。

一鍵中斷調用官方 agent.cancel 能力。

默認告警層級爲 notify；auto-stop 僅在配置後對 loop deadlock 且 confidence >= 0.9 生效。

Breakpoint fork¶

在穩定 turn/end 邊界調用官方 ctx.sessions.fork，創建新的 child session。按 README 描述，它不修改 workspace files。

CLI 檢查¶

提供針對 sessions、trajectory tree 和 snapshots 的 CLI 檢查工具，直接查詢插件自己的 SQLite。

安裝與啓用¶

要求 dsh >= 0.1.0-rc.6。

Bundle 安裝¶

dsh plugin --profile web add github:dfycaly98931680/dsh-trajectory-governance#<commit-sha>

這條命令從 GitHub 指定 commit 安裝插件 bundle。

如果 git 安裝時 pnpm 要求對 prepare build 做顯式 allow-list，需要在 profile 的 pnpm-workspace.yaml 中加入：

allowBuilds:
  dsh-trajectory-governance: true

Dev overlay¶

dsh web --patch C:\path\to\dsh-plugin\overlay.dev.yml

這裏使用本地 overlay 文件啓動，不需要走 pnpm 構建路徑。路徑按實際插件目錄替換。

典型用法¶

1. 在 DSH GUI 中運行一個智能體任務。
2. 打開 軌跡治理 / Trajectory Governance tab。
3. 選擇一個 session，查看軌跡樹、快照標記和診斷結果。
4. 點擊節點，查看原始事件和掛載的診斷報告。
5. 使用 snapshot bar 捕獲檢查點、列出快照、跳回指定位置，或通過 API/CLI 刪除過期分支。

CLI 檢查命令：

node scripts/inspect.mjs [dbPath]
node scripts/tree.mjs <sessionId> [dbPath]
node scripts/snapshot.mjs <dbPath> <cmd> [...]

先運行 inspect.mjs 查看 sessions 和 events 概覽，再用 tree.mjs 輸出指定 session 的 trajectory tree，最後用 snapshot.mjs 執行快照相關命令。

適用場景與注意¶

適合以下場景：

• 需要把 DSH 長任務的事件流整理成可讀軌跡。
• 需要識別 loop deadlock、invalid retry、goal drift。
• 需要獨立 SQLite 存儲、桌面通知、Cordis bus events 或 webhook 接入。

使用前注意：

• 插件是觀測層，不 steer、不 intercept、不 rollback。
• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼、commit 和許可證。當前可覈實資料中 license 無法確認。
• git 安裝可能需要 pnpm build allow-list；已構建 tarball 不需要 build permission。
• 官方 Trajectory 視圖保持不變，插件不覆蓋該視圖。

鏈接¶

• 社區目錄：https://www.skillhub.cn/plugins/dfycaly98931680/dsh-trajectory-governance
• GitHub：https://github.com/dfycaly98931680/dsh-trajectory-governance