前言¶

在 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