dfycaly98931680/dsh-trajectory-governance

dsh-trajectory-governance

Awesome DSH Plugin

面向 DeepSeek Harness (dsh) 的智能体轨迹治理与异常诊断。

将扁平的 session/event 日志重建为结构化、多分支的轨迹树，保留观测层快照，并运行三种时序异常策略（循环死锁 / 无效重试 / 目标漂移），结果挂载到树节点上，并在独立的 GUI 标签页中呈现。

零内核修改 · 仅消费的事件订阅 · 观测层快照（无控制平面回滚）· 独立 SQLite 存储 · 绝不覆盖官方 Trajectory 视图。

为什么

官方 Trajectory 页面是扁平的原始事件日志。对于长时间运行的智能体任务（数十轮、子智能体、分叉），你无法看到：

- 哪个工具调用属于哪个子任务 / 子智能体 / 分叉分支，
- 智能体从何处开始偏离原始目标，
- 它是否在原地循环、空烧 token（死锁 / 无效重试）。

本插件是一个上层观测与推理层：它消费已提交的事件，并推导出结构、快照和诊断——它从不操控、拦截或回滚智能体。两种视图共存。

| 方面 | 官方 Trajectory | dsh-trajectory-governance |
| --- | --- | --- |
| 视图 | 扁平原始事件日志 | 结构化多分支轨迹树 |
| 谱系 | 无 | 父/子 + 分叉/子智能体分支（隐式推导） |
| 快照 | 无 | 观测层快照（nodeId + 上下文哈希 + branchId） |
| 诊断 | 无 | loop_deadlock / invalid_retry / goal_drift，含置信度 + 建议 |
| 存储 | 宿主存储 | 插件私有 SQLite（~/.dsh-trajectory-governance/） |
| 行为 | — | 仅消费；从不调度、分叉或回退智能体 |

架构

dsh web profile
├─ @deepseek-ai/dsh-base (official core)
└─ dsh-trajectory-governance (this bundle)
│
│  ctx.on('session/event' | 'session/created' | 'session/disposed'
│         | 'subagent/start' | 'subagent/end')   ← emit-mode, post-commit, read-only
▼
┌─ ingest ───────────────┐   ┌─ tree ─────────────────┐
│ normalize (scalars)    │──▶│ cross-session trajectory │
│ sqlite (events/sessions)│   │ tree + branch attach    │
└────────────────────────┘   └─────────────────────────┘
┌─ snapshot ─────────────┐   ┌─ diagnose ──────────────┐
│ index-only snapshots    │   │ 3 strategies (async)    │
│ LRU/TTL prune, branches │   │ results → anomalies DB  │
└────────────────────────┘   └─────────────────────────┘
│
▼
┌─ api (host) ────────────┐   ┌─ client (browser) ─────┐
│ /trajectory-governance/  │◀──│ independent Tab:        │
│ api/* (JSON, same-origin)│   │ conversation.view slot, │
└─────────────────────────┘   │ id 'trajectory-…'       │
└─────────────────────────┘
数据流：session/event（持久化，提交后）→ 规范化 + 持久化 →
树/快照/诊断服务 → JSON API → GUI 标签页。诊断引擎
异步按间隔运行（增量水位线 + 尾部重叠），
绝不阻塞 agent 循环。

安装

需要 dsh >= 0.1.0-rc.6。有两种方式：

打包安装（已发布 / git）：

dsh plugin --profile web add github:dfycaly98931680/dsh-trajectory-governance#

git 安装会拉取源码，因此该包附带了一个 prepare 构建；pnpm
要求为其显式配置允许列表（将打印出的键添加到该 profile 的
pnpm-workspace.yaml，然后重新运行）：

allowBuilds:
dsh-trajectory-governance: true

或者安装已构建的 tarball（pnpm pack）——无需构建权限。

开发覆盖层（无需 pnpm）：

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

然后重启 web 应用。你应该会在日志中看到 [trajectory-governance] loaded;
storage=... sessions=N events=M anomalies=K。

使用

1. 在 GUI 中运行任意 agent 任务（最好是长时间运行的任务）。
2. 打开 轨迹治理 / Trajectory Governance 标签页（一个独立的 conversation.view
条目——官方 Trajectory 标签页不受影响）。
3. 选择一个会话：树会渲染出分支徽标（subagent/fork）、
快照标记（★）以及红色高亮的异常区间（⚠）。
4. 点击某个节点可查看原始事件 + 挂载的诊断报告（类型、置信度、
严重程度、描述、建议）。
5. 使用快照栏在任意节点捕获检查点、列出它们，并跳转
回去；通过 API/CLI 删除过期的分支。

CLI 检查工具（针对插件自有的 SQLite）：

node scripts/inspect.mjs   [dbPath]                 # sessions/events overview
node scripts/tree.mjs       [dbPath]     # trajectory tree JSON
node scripts/snapshot.mjs    [...]     # list|create|context|delete|prune

配置

插件行接受 config（全部可选；在默认值之上深度合并）：

- insert:
- id: trajectory-governance
name: dsh-trajectory-governance
config:
storage:
path: C:/data/trajectory.db   # default ~/.dsh-trajectory-governance/trajectory.db
diagnosis:
strategyA:
enabled: true
windowSize: 5
similarityThreshold: 0.85
resultSimilarityThreshold: 0.8
strategyB:
enabled: true
minRounds: 3
strategyC:
enabled: true
sampleEveryNRounds: 5
similarityThreshold: 0.5
consecutiveSamples: 2
embedder: lexical        # 'lexical' built-in; 'llm' is the extension seam
analyzer:
enabled: true
intervalMs: 10000
alerts:
enabled: true
minConfidence: 0.8
cooldownMs: 600000
channels:
desktop: true          # browser Notification (client side)yaml
cordisEvent: true      # 生态系统中的 'trajectory/anomaly' 总线事件
webhook:
url: ""              # 飞书/钉钉/Slack 风格的文本 webhook
actions:
onLoopDeadlock: notify   # notify | suggest-stop(一键中断按钮) | auto-stop
onInvalidRetry: notify
onGoalDrift: notify
cost:
enabled: true
tokenPricePerM: 0.28     # 根据你的服务商定价调整
estimateWhenUsageMissing: true

完整 schema：src/diagnose/config.ts 中的 DIAGNOSIS_CONFIG_SCHEMA。

告警与止损（v0.2）

当检测到新的异常时（置信度 ≥ alerts.minConfidence），插件会：

1. 在 Cordis 总线上发出 trajectory/anomaly（生态系统通知插件
可订阅），并在已配置的情况下 POST 一个文本 webhook —— 消息使用
止损语言：类型、置信度，以及该区间已经消耗了多少 token/金钱/时间
（来自官方 assistant/message.usage）；
2. GUI 标签页轮询 /api/alerts，显示桌面通知（浏览器
Notification API，工具栏中有权限按钮），并将异常会话
固定在下拉列表顶部，按浪费的 token 排序；
3. 提供一键中断（POST /api/actions/interrupt），它会调用
官方 agent.cancel 能力 —— 绝不使用 monkey-patch。默认层级
为 notify；auto-stop（仅用于循环死锁，置信度 ≥ 0.9）可
为无人值守场景配置。

断点与浪费报告（v0.3）

断点退出 —— 合法的轻量级“回滚”。 本插件不采用
控制平面倒带（已由 dsh-turn-rewind 覆盖），
而是提供诊断驱动的重启：在任意快照 / 异常
起点 / 选定节点处，“在此处分叉新会话” 会将目标解析到
最近的稳定 turn/end 边界，并调用官方
ctx.sessions.fork(source, boundary) —— 在该点播种一个全新的子会话。
它从不触碰工作区文件，保持观察层的立场，
并将“你在这里浪费了钱”转化为一键操作。

浪费归因报告 —— 不是又一个用量统计仪表盘（那个细分领域已经
饱和）：它回答的是别人都没做的归因问题，“哪些
会话浪费了 token/金钱，属于哪些异常类型”：
sh
curl http://127.0.0.1:3080/trajectory-governance/api/report/waste          # 所有会话（Markdown + JSON）
curl "http://127.0.0.1:3080/trajectory-governance/api/report/waste?sessionId="  # 单个会话详情

两者也可从标签页访问（“浪费报告” / “本会话报告”按钮）。

快速演示（复现循环死锁与目标漂移）

即时（无需等待真实循环）： 将一个合成会话播种到
实时存储中，刷新标签页，选择 demo-session：
sh
node scripts/demo-seed.mjs            # 写入默认实时数据库

你应该会看到一棵树，其中红色高亮的 loop_deadlock（5 个相同的工具
调用）以及一个严重的 goal_drift 范围，外加一个快照标记（★）。

真实 agent：

1. 给 agent 一个冗长、开放式的重构提示（例如“重构这个项目为
TypeScript 并补单元测试，先读代码再动手”）。
2. 让它运行，直到它开始重复相同的工具调用（相同文件、相同
内容）且没有可见进展——策略 A 会在触发节点上标记 loop_deadlock。
3. 在另一个领域提出后续请求（“顺便帮我看看怎么做番茄意面”）——在
采样 N 轮之后，策略 C 会针对原始基线标记 goal_drift（轻度/中度/严重）。

验证：树标签页会以红色高亮显示这些范围；scripts/inspect.mjs 会显示
异常计数；scripts/tree.mjs  会转储已挂载的 anomalyInfo。

截图

TODO — 在首次实际运行后添加：树标签页概览 / 异常卡片 / 快照
列表。（此处预留占位符。）

测试
sh
npm install
npm run build && npm test    # 46 tests: normalize/store/subscriber/tree/snapshot/diagnose/api

边界（重要）

- 零内核修改 —— 不 fork、不 monkey-patch、不访问宿主存储。
- 仅消费事件 —— session/event 等是 emit 模式、提交后、
即发即忘的监听器；payload 永远不会被修改。
- 观测层快照 —— 快照是一个索引（nodeId + 上下文哈希
+ branchId）；上下文从事件存储重建。此插件永远不会 fork、
恢复或回滚 agent。
- 独立标签页 —— 使用自己的 slot id 注册；官方 Trajectory
页面（id trajectory）永远不会被覆盖。
- 预览 API —— SESSION_FORMAT_VERSION = 0，不暗示任何兼容性。
事件词汇表集中在 src/core/event-catalog.ts 中；未知类型
遵循信封的 ignorable 标记。

仓库布局

src/
index.ts                  # Cordis plugin entry (name/apply)
core/                     # types + 44-type event catalog
ingest/                   # normalize + session-event subscriber
persistence/              # node:sqlite store (events/sessions/snapshots/anomalies)
tree/                     # trajectory tree builder + queries
snapshot/                 # observation snapshots + branch manager
diagnose/                 # similarity, config, 3 strategies, engine, mount, runtime
api/                      # host JSON API (/trajectory-governance/api/*)
client/                   # independent GUI tab (conversation.view, id 'trajectory-governance')
tests/                      # node:test suites
scripts/                    # inspect / tree / snapshot / smoke
cordis.patch.yml            # official bundle load row
plugin.manifest.yaml        # self-describing metadata (loader uses cordis.patch.yml)

许可证

MIT —— 参见 LICENSE。属于 awesome-dsh-plugin
生态系统的一部分。主题：dsh-plugin。