前言¶

在 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