# hermes-dsh-bridge

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-blue)](https://github.com/dsh-market/awesome-dsh-plugin)

> **Hermes Agent ↔ DeepSeek Harness (DSH) 桥**:让 Hermes 把任务派发给 DSH 执行,
> 并在 DSH 侧边栏以 **UI 可见会话** 实时观看执行过程。

主线能力:

- **Hermes → DSH 派单** — `POST /mcp/collab` JSON-RPC:`dispatch_task`(one-shot / continuable),返回真实 token 用量,支持任务信封、知识切片、项目记忆注入。
- **可见派单 (visible dispatch)** — 默认把 one-shot 任务落地为 DSH 侧边栏可见的根会话(不是隐藏子代理):你能亲眼看到 agent 一步步执行 SSH、改文件、跑命令。
- **DSH → Hermes 工具** — 10 个工具:`list_hermes_sessions`、`import_hermes_session`、`load_hermes_persona`、`consult_hermes`、`hermes_inbox`、`hermes_inbox_append`、`load_hermes_project_memory`、`mirror_session_to_hermes`、`session_mirror`、`dispatch_status`、`rotate_outbox_now`。
- **会话镜像** — 把任意 Hermes 会话作为原生 DSH 会话继续对话(side-by-side)。
- **MCP 工具暴露** — 通过 `dsh-mcp-client` 把外部 MCP server(如 hermes-web)暴露给 DSH 子代理。

---

## 快速开始

前置:DSH Desktop >= 0.7.x、Node >= 22、Hermes Agent(任意版本,只要有会话目录)。

```bash
# 1. 安装插件
dsh plugin --profile web add hermes-dsh-bridge

# 2. 创建磁盘连接(源码方式)
#    把本仓库 clone 到本地,在 profile 的 package.json dependencies 里
#    用 "link:" / junction 指向 packages/dsh-hermes-link

# 3. 配置 Hermes 家目录(必须与你的 Hermes 安装一致)
$env:HERMES_HOME = 'C:\Users\<you>\AppData\Local\hermes'   # Windows
# 或
export HERMES_HOME="$HOME/.hermes"                         # Linux/macOS
```

启动 DSH Desktop 后,插件健康检查:

```bash
curl http://127.0.0.1:<port>/mcp/collab/health
# {"ok":true,"version":"0.5.1","hermes_home":"...","importer_ready":true,...}
```

> DSH Desktop 每次启动 HTTP 端口随机;从 `harness.log` 尾部取
> `dsh web: http://127.0.0.1:PORT/?token=...` 获得当前端口与 token。

## 派单示例

```bash
curl -X POST http://127.0.0.1:<port>/mcp/collab \
  -H 'content-type: application/json' \
  -H "cookie: dsh-auth=<token>" \
  -d '{
    "jsonrpc": "2.0", "id": "t1", "method": "tools/call",
    "params": {
      "name": "dispatch_task",
      "arguments": {
        "task_id": "demo-001",
        "skill": "pwsh",
        "task": "检查本机磁盘空间,汇报使用率",
        "model": "deepseek/deepseek-v4-flash",
        "visible": true
      }
    }
  }'
```

`visible: true`(默认)时,返回体带 `visible_session_id` 与 `workspace_title`——
打开 DSH 侧边栏对应工作区即可看到该会话实时执行。

## 环境变量

| 变量 | 默认 | 作用 |
|---|---|---|
| `HERMES_HOME` | `~/.hermes` | Hermes 会话/记忆根目录 |
| `DSH_LINK_LLM_PROVIDER` | `commandcode` | 子代理 LLM provider |
| `DSH_LINK_VISIBLE_WORKSPACE` | 空 | 可见派单落地的 workspace(workspaceId/title/path 子串) |
| `DSH_LINK_SSH_HOST` / `DSH_LINK_SSH_KEY` | 空 | 给子代理的 SSH 直连提示(避免探测主机) |
| `DSH_LINK_PROXY` | 空 | 子代理 HTTP 代理提示 |
| `DSH_LINK_TZ_HINT` | 空 | 时区提示(如 `server logs are UTC; Beijing = UTC+8`) |

## 架构

```
┌─────────────┐   POST /mcp/collab (JSON-RPC)   ┌─────────────────────┐
│   Hermes    │ ──────────────────────────────▶ │  DSH Desktop        │
│  Agent      │     dispatch_task / followup    │  ┌───────────────┐  │
└─────────────┘ ◀────────────────────────────── │  │ dsh-hermes-   │  │
      ▲               run.result / consult      │  │ link plugin   │  │
      │                                         │  └───────┬───────┘  │
      │      MCP tools (list_hermes_sessions,   │          │ creates  │
      └──────────────────────────────────────── │    UI-visible root  │
              import, mirror, consult ...)      │    session (侧边栏) │
                                                └─────────────────────┘
```

## 安全模型

- `POST /mcp/collab` 由 DSH web token 鉴权(`HERMES_LINK_TOKEN`,当前 `auth: open` 仅供本地回环)。
- 派单信封带 task_id 与 skill 白名单;子代理只能用一个工具(`toolFilter.allow=[skill]`)。
- amend/consult 协议带 nonce 认证;审计全量落盘 `audit.jsonl`。
- 详细见 [docs/security-model.md](docs/security-model.md)。

## 文档

- [安装指南](docs/plugin-install-guide.md)
- [插件开发指南](docs/plugin-developer-guide.md)
- [安全模型](docs/security-model.md)
- [共享约定](docs/sharing-conventions.md)

## License

[MIT](LICENSE)。本项目代码继承自 [dsh-hermes-link](https://github.com/Tianbuyu-wwx/dsh-hermes-link)
(MIT, Copyright (c) 2026 Tianbuyu-wwx),并在其之上继续演进。