Preface¶

After running agent tasks in DSH, session/event logs continuously accumulate. For short tasks, directly viewing the event sequence may be sufficient; for long tasks, flat logs make it difficult to answer a few questions: which call belongs to which branch, when the agent deviates from the original goal, or whether it repeatedly retries around the same goal.

dsh-trajectory-governance is a plugin for DeepSeek Harness (DSH) used for agent trajectory governance and anomaly diagnosis. It consumes committed events, reconstructs a structured trajectory tree, saves observation-layer snapshots, and runs three types of temporal anomaly policies. Below, we introduce its positioning, core capabilities, installation methods, and typical usage.

What This Is¶

• Repository: dfycaly98931680/dsh-trajectory-governance
• Maintainer: dfycaly98931680
• Positioning: Agent trajectory governance & anomaly diagnosis for DeepSeek Harness (dsh).
• Runtime Mode: consume-only event subscription, zero kernel modification
• Data Location: plugin-independent SQLite, directory is ~/.dsh-trajectory-governance/
• View Relationship: does not override the official Trajectory view, provides a separate GUI tab

Core Features¶

Trajectory Tree¶

Rebuilds flat session/event logs into a structured, multi-branch trajectory tree.

Snapshots¶

Saves observation-layer snapshots, including nodeId, context hash, and branchId. Snapshots can be used to mark checkpoints on the trajectory and for subsequent rollback or forking.

Anomaly Diagnosis¶

Runs three temporal anomaly policies:

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

Diagnostic results are attached to tree nodes and displayed in a separate GUI tab.

Alerts and Interruptions¶

Provides alerts, desktop notifications, Cordis bus events, and webhook posts.

One-click interruption invokes the official agent.cancel capability.

The default alert level is notify; auto-stop only takes effect for loop deadlock with confidence >= 0.9 after configuration.

Breakpoint Fork¶

Calls the official ctx.sessions.fork at stable turn/end boundaries to create a new child session. According to the README, it does not modify workspace files.

CLI Inspection¶

Provides CLI inspection tools for sessions, trajectory trees, and snapshots, directly querying the plugin’s own SQLite.

Installation and Enabling¶

Requires dsh >= 0.1.0-rc.6.

Bundle Installation¶

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

This command installs the plugin bundle from a specific commit on GitHub.

If git installation requires explicit allow-listing for prepare builds in pnpm, add the following to the profile’s pnpm-workspace.yaml:

allowBuilds:
  dsh-trajectory-governance: true

Dev Overlay¶

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

Here, a local overlay file is used to start, bypassing the pnpm build path. Replace the path according to the actual plugin directory.

Typical Usage¶

1. Run an agent task in the DSH GUI.
2. Open the 轨迹治理 / Trajectory Governance tab.
3. Select a session to view the trajectory tree, snapshot markers, and diagnostic results.
4. Click a node to view the raw events and attached diagnostic reports.
5. Use the snapshot bar to capture checkpoints, list snapshots, jump back to a specified position, or delete expired branches via API/CLI.

CLI inspection commands:

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

First run inspect.mjs to view an overview of sessions and events, then use tree.mjs to output the trajectory tree of a specified session, and finally use snapshot.mjs to execute snapshot-related commands.

Applicable Scenarios and Notes¶

Suitable for the following scenarios:

• Needing to organize the event stream of long DSH tasks into a readable trajectory.
• Needing to identify loop deadlock, invalid retry, or goal drift.
• Needing standalone SQLite storage, desktop notifications, Cordis bus events, or webhook integration.

Before use, note:

• The plugin operates at the observation layer; it does not steer, intercept, or rollback.
• The plugin runs with the current dsh process permissions; check the source code, commit, and license before installation. The license cannot be confirmed in currently verifiable materials.
• Git installation may require pnpm build allow-listing; pre-built tarballs do not require build permissions.
• The official Trajectory view remains unchanged; the plugin does not override it.

Links¶

• Community Directory: https://www.skillhub.cn/plugins/dfycaly98931680/dsh-trajectory-governance
• GitHub: https://github.com/dfycaly98931680/dsh-trajectory-governance