前言¶

在 DSH 裏調用外部子代理時，會遇到一個常見中間狀態：DSH 已經發起了 subagent_codex 或 subagent_claude_code 一類工具調用，外部 CLI 也執行結束，但 DSH 側不一定能直接看出這次調用是否對應某個 Codex 或 Cursor 會話產物。

下面介紹 dsh-observability。它由 jeremy9682 維護，MIT 許可，目標是爲 DeepSeek Harness 提供外部子代理運行的可觀測性。

這是什麼¶

dsh-observability 倉庫包含兩個小型插件：

• 根目錄包：dsh-codex-observability
• plugin-cursor/ 下的包：dsh-tool-cursor

需要注意名稱口徑：倉庫名和 README 使用 dsh-observability，根包 package.json 中的包名是 dsh-codex-observability。寫配置、查日誌或排查依賴時，建議按實際包名區分。

核心功能¶

dsh-codex-observability¶

dsh-codex-observability 用於在受跟蹤工具調用前後，對 product session roots 做指紋，並把 attribution envelope 寫入 journal 文件。

已覈實的默認關注對象包括：

~/.codex/sessions
~/.cursor/chats

它會寫入類似 sessionRef、sessionStatus 的歸屬信息。這裏只寫入指針，不寫入 prompt 或 transcript 內容。

dsh-tool-cursor¶

dsh-tool-cursor 提供 cursor_delegate 工具，用於把任務委託給官方 cursor-agent CLI 的 headless 模式。該實現移植自 opencodex cursor.ts 參考實現。

行爲邊界是：

• 默認只讀
• edit 模式只提出更改，從不應用更改

獨立工具¶

倉庫還提供獨立工具：

bin/dsh-run-attributed.mjs

它可以爲任意 CLI 包裹同一類指紋、envelope 和三級超時：

• first-event
• idle
• total

安裝與啓用¶

環境要求¶

先確認運行環境滿足：

dsh 0.1.0-rc.6
Node ^22.19 || >=24

如果使用 pnpm >= 10，首次執行 prepare 或 build 時會請求 allowBuilds 權限。需要將打印出的 key 寫入 profile 的 pnpm-workspace.yaml，然後重新運行。

從 GitHub 安裝¶

安裝根包：

dsh plugin --profile web add github:jeremy9682/dsh-observability

從本地 checkout 安裝¶

安裝 root 包：

dsh plugin --profile web add ~/Projects/dsh-observability

安裝 cursor 工具包：

dsh plugin --profile web add ~/Projects/dsh-observability/plugin-cursor

默認配置¶

下面是兩個插件的默認配置項：

- id: codex-observability
  name: dsh-codex-observability
  config:
    enabled: true
    roots: ['~/.codex/sessions', '~/.cursor/chats']
    tools: [subagent_codex, subagent_claude_code]
    journal: '~/.dsh/storages/codex-observability.jsonl'

- id: tool-cursor
  name: dsh-tool-cursor
  config:
    timeoutSeconds: 600
    defaultMode: ask

配置項含義可以按名字理解：

• roots：需要觀察的產品會話根目錄
• tools：需要跟蹤的外部子代理工具
• journal：歸屬指針寫入的 journal 文件
• timeoutSeconds：cursor_delegate 的超時時間
• defaultMode：cursor_delegate 的默認模式

典型用法¶

用獨立工具包裹 Codex CLI¶

如果只是想給一個 CLI 調用加上指紋、envelope 和超時控制，可以使用：

node bin/dsh-run-attributed.mjs --provider codex --seat codex-landing \
  --root ~/.codex/sessions --first-event 60 --idle 240 --total 300 \
  -- codex exec --json "<task>"

這一步做的事情是：先指定 provider、seat 和要觀察的會話根目錄，再設置三級超時，最後把真正的 codex exec --json "<task>" 命令作爲被包裹對象。

觀察結果看哪裏¶

dsh-codex-observability 會把歸屬信息寫入 journal 文件，默認位置是：

~/.dsh/storages/codex-observability.jsonl

寫入內容是指針級別的信息，例如 sessionRef 和 sessionStatus，不包含 prompt 或 transcript 內容。

適用場景與注意¶

適合以下場景：

• 在 DSH 中調用外部 Codex、Cursor 等 CLI 子代理
• 需要判斷某次工具調用是否產生了可觀察的產品會話文件
• 希望只記錄歸屬指針，不把 prompt 或 transcript 內容落盤

使用前需要注意：

1. 插件以當前 DSH 進程權限運行，安裝前應檢查源碼和許可證。
2. 許可證爲 MIT。
3. dsh-tool-cursor 默認只讀；edit 模式只提出更改，從不應用更改。
4. dsh-codex-observability 只寫入指針，不寫入 prompt 或 transcript 內容。
5. 持久化 in-session-log 指針目前等待上游支持兩項能力：
   - downstream event-type registration surface
   - append-time ignorable control

在支持落地前，當前使用 file journal 作爲可工作回退。
6. 根包 package.json 顯示 peerDependencies：

{
  "@deepseek-ai/cordis": "4.0.1",
  "@deepseek-ai/schemastery": "3.18.1"
}

結尾¶

dsh-observability 解決的問題比較具體：在 DSH 調用外部子代理之後，補齊一次“這次調用是否對應某個會話產物”的觀測鏈路。它不擴大權限邊界，也不記錄完整對話內容，主要提供指針、超時和歸屬狀態。

相關地址：

• 目錄頁：https://www.skillhub.cn/plugins/jeremy9682/dsh-observability
• GitHub：https://github.com/jeremy9682/dsh-observability