DSH ↔ Hermes Dual-Agent Collaboration Pipeline

中文版 README 见 README.zh-CN.md

⚠️ AI-GENERATED CODE NOTICE: All code in this repository was generated by DeepSeek AI models and has NOT undergone human review. Use at your own risk. Review critical paths (security, permissions, file operations) before deployment.

📋 License & attribution: MIT. Code adapted from DeepSeek Harness, Hermes Agent, and dsh-harness-mcp-server (all MIT) — see NOTICE-借鉴与合规.md. Related project: Ericwong5021/dsh-kanban (similar name, different type: React UI kanban vs our background executor).

English README below. Let Hermes Agent (an interactive AI agent) and DSH / DeepSeek Harness (a Web-based AI agent) work together like two teammates: Hermes dispatches tasks and reviews results; DSH executes them automatically in its Web GUI, writes results back to a kanban board, and notifies Hermes on completion. Fully unattended — you only look at the results.

When to use this

• You run Hermes Agent and DSH (DeepSeek Harness) on the same machine
• You want DSH's Web GUI sessions to automatically execute tasks dispatched by Hermes (instead of manually opening a conversation in the GUI every time)
• You want a task queue: Hermes writes tasks into a kanban board, a DSH watcher claims and executes them serially
• You want completion notifications: when DSH finishes a task, it pops up automatically in your Hermes session — no polling required

Not for: single-agent setups (one agent has nothing to collaborate with), or cross-machine distributed setups (this pipeline assumes one machine with a shared filesystem).

Architecture

┌─────────────┐    kanban board (SQLite)    ┌──────────────────┐
│   Hermes    │  ────────────────────────→  │   DSH Web GUI    │
│  (CLI/etc)  │  hermes kanban create       │  (dsh web :3080) │
└─────┬───────┘                             └────────┬─────────┘
      │  /dsh-send skill                             │  watcher plugin
      │                                              │  claim → run → write-back
      │  ~/.dsh/kanban-trigger/<id>.trigger          │
      └─────────────────────── event-driven wake ────┘
                                                  │
      ~/.dsh/kanban-done/<id>.done  ←─────────────┘  writeDoneFile()
      │
      ▼
  Hermes idle loop _drain_done_notifications()
      → session auto-pops 【外部通知】task completed

Four key mechanisms:

1. Kanban queue: task state machine (ready → running → done/blocked), persisted in SQLite, crash-recoverable
2. Event-driven wake-up: Hermes writes a trigger file, the watcher's fs.watch responds immediately (+30s fallback polling)
3. Output whitelist: output is only allowed into whitelisted dirs (default $DSH_WORKSPACE, desktop), preventing privilege escalation writes
4. Completion notification: watcher writes a done file → Hermes session notices it automatically, no polling

Repository layout

├── dsh-side/          DSH-side components (maintained by DSH)
│   ├── plugins/dsh-kanban-watcher/   kanban watcher plugin source + README
│   ├── hermes-side/                  Hermes-side skill source (dsh-send SKILL.md) — mirror of hermes-side/dsh-send-skill/
│   ├── docs/                         capability survey & collaboration feasibility
│   └── scripts/                      session decompress/extract/comment tools + restart script
└── hermes-side/      Hermes-side changes (maintained by Hermes)
    ├── hermes-external-event-steer.patch   source diff (104 lines)
    ├── dsh-send-skill/                /dsh-send skill — mirror of dsh-side/hermes-side/dsh-send/
    ├── dsh-web.service                systemd service file (TEMPLATE — edit placeholders before use)
    ├── PR-提交说明.md                  material for filing a Hermes issue
    └── README.md                      usage doc

Quick start

📖 New-user zero-to-install guide: INSTALL.md (kanban init, plugin mount, skill deploy, verification, known pitfalls)

🤖 AI Agent users (another Hermes/DSH/Claude Code instance): just run ./install.sh --yes — fully automatic, idempotent, re-runnable. It auto-detects paths, skips completed steps, and exits 2 with fix hints when prerequisites are missing. Pre-flight with ./install.sh --dry-run. Ensure the DSH web profile is initialized first (dsh web --port 3080 once).

Prerequisites: Hermes Agent + DSH (npm global @deepseek-ai/dsh) installed on the same machine, sharing ~/.dsh.

# 0. Clone this repository first (--recurse-submodules pulls the dsh-kanban-watcher plugin submodule)
git clone --recurse-submodules <your-repo-url> && cd <repo-dir>

# 1. DSH side: install the watcher plugin + start web
cd ~/.dsh/profiles/web
pnpm add file:<repo-dir>/dsh-side/plugins/dsh-kanban-watcher
systemctl --user enable --now dsh-web.service   # or manually: dsh web --port 3080
# (dsh-web.service is a template — edit the <DSH_BIN>/<NPM_PREFIX> placeholders first)

# 2. Hermes side: apply the patch + enable the feature
cd ~/.hermes/hermes-agent
git apply <repo-dir>/hermes-side/hermes-external-event-steer.patch
hermes config set features.external_event_steer true
# restart the Hermes CLI session

# 3. Dispatch a task
# in your Hermes session:
/dsh-send analyze this week's trading data and write a report to the DSH workspace

# 4. Completion notification pops up automatically
# 【外部通知】task t_xxxx「analyze this week's trading data」completed. Result: ...

Usage examples

# Dispatch with a model (note: plugin modelMap only maps flash + __fallback__,
# so a model outside the map (e.g. pro) falls back to flash)
/dsh-send --model deepseek-v4-flash write a scraper for HLTV data

# Dispatch with a skill (copy a Hermes skill to the shared area for DSH to reference)
/dsh-send --skill two-step-t1-dip-buy-strategy analyze the current market with this strategy

# Session inheritance (continue a previous conversation's context, new in v0.2.0)
/dsh-send --resume keep-discussing-X analyze the conclusion from before

# Specify a working directory
/dsh-send --workspace dir:$DSH_WORKSPACE/weekly-reports write this week's report

# View the queue
/inbox

Design principles (dual-agent review gate)

• Territory-based division of labor: whoever owns the environment owns the work — DSH-related code is written by DSH, Hermes-related by Hermes; after the implementer produces output, the other agent independently reviews it (security / error handling / scope / dependency compatibility)
• Mutual restart: Hermes restarts DSH and DSH restarts Hermes; a task to restart the other process must never go into the board for the watcher to self-execute (the watcher runs inside the DSH host — killing the host kills the executor)
• Output whitelist: Hermes side is the single source of truth; the DSH watcher's permission preset mirrors the same whitelist
• The user is the final merge approver: review comments are answered one by one (fixed or explained why not), the user decides

Known limitations

• The watcher executes tasks serially (one at a time, later tasks queue)
• 30s fallback polling + fs.watch: near-real-time, not real-time
• SQLite multi-process writes have lock contention (busy_timeout + retry fallback)
• External event injection only works in Hermes CLI sessions, not gateway platforms
• After plugin code updates, restart dsh web for the change to take effect (node does not hot-reload)

(The watcher falls back to 30s polling when fs.watch events are coalesced/lost.)

Why not an off-the-shelf solution

• Community MCP server (dsh-harness-mcp-server) not used: its dependency ^0.0.1-rc.1 does not match DSH profile 0.1.0-rc.6 (singleton-conflict risk), its task queue is in-memory (lost on restart), and sessions are reused per cwd (not per task). This project's kanban board is a persisted queue that fills those gaps.
• Transitional positioning: this pipeline is expected to last until DSH ships a mature ACP/JSON-RPC cross-agent task protocol; then the watcher can be swapped while keeping the board and skill layers.
• Deployment note: Hermes gateway ships its own kanban watcher — do NOT enable the Hermes dispatcher on board dsh (it would race the DSH watcher). The board/assignee isolation design already avoids the conflict.

Path variables

Repository code and docs are sanitized: real machine paths appear as $VAR placeholders. Replace them with your own paths when deploying:

Variable	Meaning	Example
$HOME / $USER	home directory / username	/home/alice / alice
$DSH_WORKSPACE	DSH workspace (default task dir)	/home/alice/DSH
$DSH_HOME	DSH data dir	~/.dsh
$DSH_TRIGGER_DIR	kanban trigger file dir	~/.dsh/kanban-trigger
$DSH_DONE_DIR	done file dir (completion notices)	~/.dsh/kanban-done
$DSH_SESSIONS	DSH session archive dir	~/.dsh/sessions
$DSH_WEB_PROFILE	DSH web profile dir	~/.dsh/profiles/web
$DSH_BIN	dsh executable	/home/alice/.hermes/node/bin/dsh
$HERMES_HOME	Hermes data/source dir	~/.hermes
$HERMES_BIN	hermes CLI executable	~/.local/bin/hermes
$HERMES_BIN_DIR	hermes CLI dir	~/.local/bin
$NPM_PREFIX	npm global prefix	~/.hermes/node
$HERMES_VENV_PYTHON	Hermes venv Python	~/.hermes/hermes-agent/venv/bin/python
$DESKTOP	Windows desktop	/mnt/c/Users/xxx/Desktop
$WIN_USERNAME	Windows username	alice
$HOSTNAME	machine hostname	myhost

Docs

• CHANGELOG.md — release notes (version history + what's new)
• INSTALL.md — full zero-to-install guide + known pitfalls (中文版: INSTALL-安装指南.md)
• dsh-side/docs/DSH-Hermes双Agent协作管道-能力盘点与可行性.md — project origin (DSH capability survey + collaboration feasibility)
• dsh-side/plugins/dsh-kanban-watcher/README.md — watcher plugin detailed docs (config/usage/security)
• hermes-side/README.md — external_event_steer internals & security design (done-file untrusted input, seen baseline)
• hermes-side/PR-提交说明.md — material for filing an issue with Hermes Agent