hermes-dsh-bridge
一句话：把 DeepSeek Harness 的 Agent 能力封装成一个 MCP server（跑在 Harness 内部），
让外部 MCP 客户端（Hermes / Claude Code / Codex / dsh 等）驱动 Harness 去真正干活。
Hermes 是大脑，Harness 是双手。
Hermes (MCP client, 大脑) ──HTTP──▶ harness-mcp-server (:8090)
│ ctx.agents.create → mount preset
▼
Harness agent（bash / fs / todo / web… 完整工具集）
当前版本 0.8.1：兼容 dsh ≥ 0.1.2-rc.1（已在 0.1.5-rc.2 实测）；26 个工具。新增 task_inbox 终态主动回调（Webhooks / HMAC-SHA256 / SSRF 防护）。
30 秒 quickstart
前置：Node ≥ 22.18、dsh ≥ 0.1.2-rc.1、一个已配置好的 Harness profile。
下面 4 步跑通最小闭环（假设 profile 名是 <PROFILE>，端口用默认 8090）。
# ① 装插件到 profile
cd ~/.dsh/profiles/<PROFILE>/node_modules && npm install hermes-dsh-bridge
# ② 修 dual-package hazard（必做，否则 agent 会「嘴炮」没有工具）
GLOBAL_TREE=$(npm root -g)/@deepseek-ai/dsh/node_modules/@deepseek-ai
for pkg in cordis cosmokit dsh-agent dsh-llm dsh-session dsh-tools dsh-scope \
dsh-agent-presets dsh-code-runtime dsh-system-prompt dsh-typert-protocol \
dsh-attachment dsh-brand dsh-invariants dsh-timeout dsh-settings \
dsh-home-paths dsh-atomic-write dsh-user-approval \
cordis-plugin-include cordis-plugin-loader; do
rm -rf "@deepseek-ai/$pkg" 2>/dev/null; ln -sfn "$GLOBAL_TREE/$pkg" "@deepseek-ai/$pkg"
done
# ③ 在 profile 的 cordis.patch.yml 末尾追加配置
cat >> ~/.dsh/profiles/<PROFILE>/cordis.patch.yml <<'EOF'
- insert:
- id: hermes-dsh-bridge
name: 'hermes-dsh-bridge'
config:
http: true
port: 8090
host: 127.0.0.1
provider: <your-provider-id> # ← 你的 Harness 里已配置的 provider
model: <your-model-id> # ← 你的 Harness 里已配置的 model
EOF
# ④ 重启 + 自检（doctor 会逐项告诉你哪里没配好）
systemctl restart dsh.service
node scripts/doctor.mjs --profile <PROFILE>
看到 全部通过 后，验证一次真实连通（最便宜的调用是 echo）：
curl -s -X POST http://127.0.0.1:8090/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0"}}}'
# 期望：data: {... "serverInfo":{"name":"harness","version":"0.8.0"}}
python3 examples/hermes_dsh_mcp.py list # 应列出 25 个工具
python3 examples/hermes_dsh_mcp.py call echo '{"text":"hi"}'
python3 examples/hermes_dsh_mcp.py run '回复:安装成功' # 真跑一次 agent（会调 LLM，稍慢）
跑通后按需进入下面的分场景进阶。
前置依赖
| 依赖 | 要求 | 检查命令 | 不满足会怎样 |
|---|
| Node.js | ≥ 22.18 | node --version | 缺 zstd / stripTypeScriptTypes，dsh 或插件直接启动失败 |
| dsh | ≥ 0.1.2-rc.1（实测 0.1.5-rc.2） | dsh --version | 旧 API：会话存储契约不符、session_list 崩溃；v0.5.0 及更早只兼容 dsh ≤ 0.1.1-rc.2 |
| Harness profile | 已用 dsh --profile <name> 启动过一次 | ls ~/.dsh/profiles/ | 没有 profile 目录可装 |
| Harness 全局树 | 含 @deepseek-ai/* 包 | npm root -g | symlink 修复无从下手 → dual-package hazard |
| LLM provider | profile 的 cordis.patch.yml 里已配好 llm-* 段 | grep -n 'llm-' ~/.dsh/profiles/<PROFILE>/cordis.patch.yml | agent 组装崩：prompt variable "{{model}}" has no value 或 MISSING_CREDENTIAL |
| bubblewrap（可选） | 宿主机装了才能跑受限 bash | which bwrap | workspace-write 档下写命令被拒（读命令仍可用） |
Hermes 端配置片段
把 MCP server 注册到 Hermes（或任何 MCP 客户端）。最小配置：
{
"mcpServers": {
"harness": {
"type": "streamable-http",
"url": "http://127.0.0.1:8090/mcp",
"headers": { "Authorization": "Bearer <你的 authToken；未开启认证则省略>" }
}
}
}
没有现成客户端时，仓库自带零依赖 Python 客户端可直接用：
python3 examples/hermes_dsh_mcp.py list
python3 examples/hermes_dsh_mcp.py call status_get '{}'
# 非默认地址/认证：
DSH_MCP_URL=http://127.0.0.1:8090/mcp DSH_MCP_TOKEN=xxx python3 examples/hermes_dsh_mcp.py list
安装（三种路径，按人群选）
方式 A — npm 安装（推荐给绝大多数人）
适用于：只想用，不想改代码。
cd ~/.dsh/profiles/<PROFILE>/node_modules
npm install hermes-dsh-bridge
装完必须做 dual-package hazard 修复（见上面 quickstart 第 ② 步或下方 FAQ），
否则 agent 会失去全部工具。包主页：https://www.npmjs.com/package/hermes-dsh-bridge
方式 B — 源码构建
适用于：要改代码 / 要跑最新未发布提交 / 排查问题。
git clone https://github.com/Emilia-awa/hermes-dsh-bridge.git
cd hermes-dsh-bridge
npm install && npm run build # tsc -b && tsdown → 产出 lib/index.js
npm test # 三套 mock 单测（不需要真实 dsh）
# 把整个目录放进 profile：
rm -rf ~/.dsh/profiles/<PROFILE>/node_modules/hermes-dsh-bridge
cp -r . ~/.dsh/profiles/<PROFILE>/node_modules/hermes-dsh-bridge
# 然后同样做 dual-package hazard symlink 修复并重启
方式 C — Hermes 一键配置片段
适用于：AI agent 帮人装、或想直接抄一份完整可用的 patch。
# ① 装包（同方式 A）
cd ~/.dsh/profiles/<PROFILE>/node_modules && npm install hermes-dsh-bridge
# ② 修 symlink（同 quickstart 第 ② 步，略）
# ③ 追加完整配置段
cat >> ~/.dsh/profiles/<PROFILE>/cordis.patch.yml <<'EOF'
- insert:
- id: hermes-dsh-bridge
name: 'hermes-dsh-bridge'
config:
http: true
port: 8090
host: 127.0.0.1
# authToken: '<随机长token>' # 非 loopback 暴露时必须开
workspaceRoots: ['<你的工作区>'] # 限制 agent 能在哪干活
enableFsWrite: false # 需 fs_write 才开
defaultSandbox: workspace-write # read-only | workspace-write | danger-full-access
approvalsBridge: web # web | builtin | file-push | off
approvalTimeoutMs: 300000 # 超时按拒绝收尾，绝不放行
provider: <your-provider-id> # ⚠️ 必填：你 Harness 里已配置的
model: <your-model-id> # ⚠️ 必填：该 provider 下的 model
EOF
# ④ 重启并自检
systemctl restart dsh.service
node scripts/doctor.mjs --profile <PROFILE> # 应全部通过
给 AI agent 的硬性约束：provider / model 一律写成占位符 <your-provider-id> /
<your-model-id>，不要写死某台机器的真实配置；装完必须跑 doctor.mjs 并把失败项的修复建议读完。
自检：node scripts/doctor.mjs
零依赖，node 直接跑，只读（不改文件、不重启服务）。逐项输出 ✓/✗ + 修复建议，
最后汇总「N 项通过，M 项失败」，退出码 0=全通过 / 1=有失败。
node scripts/doctor.mjs # 默认 127.0.0.1:8090，自动探测 profile
node scripts/doctor.mjs --profile web # 指定 profile
node scripts/doctor.mjs --port 8091 --host 127.0.0.1
DSH_MCP_TOKEN=xxx node scripts/doctor.mjs # 开了 authToken 的部署
检查 7 项：Node 版本 / dsh 可执行与版本 / profile 存在 / settings 文件 / patch 是否配了插件 /
端口监听 / MCP 握手 + tools/list。
本机真实运行输出（作为预期输出示例）
以下是在本机（Node v22.22.3 / dsh 0.1.5-rc.2，插件确实装在该 profile）实际跑出来的原文：
$ node scripts/doctor.mjs --profile web
环境
✓ Node 版本 — v22.22.3 (需要 >= v22.18.0)
dsh
✓ dsh 可执行 + 版本 — dsh 0.1.5-rc.2 (本插件需要 >= 0.1.2-rc.1; 已在 0.1.5-rc.2 实测)
✓ dsh profile 存在 — /root/.dsh/profiles/web (--profile 指定)
✓ dsh settings 文件 — /root/.dsh/settings.yaml
✓ profile patch 已配置插件 — /root/.dsh/profiles/web/cordis.patch.yml → - id: harness-mcp-server
✗ dsh --dump-config 可运行 — node:fs:2430 (profile 目录不可写)
↳ 修复: dump-config 需要写 /root/.dsh/profiles/web/cordis.yml; 用对该目录有写权限的用户跑, 或直接看下面「MCP 握手」的运行态结论(运行态通过即插件已装载)
运行时
✓ 8090 端口监听 — 127.0.0.1:8090 已监听
✓ MCP 握手 — serverInfo.name=harness version=0.5.0
✓ tools/list 工具可用 — 25 个工具(期望 25~26; 含 agent_run, session_stats, preset_set, fs_read, approval_respond)
────────────────────────────────────────────────────────────
结果: 8 项通过, 1 项失败
失败项一览:
✗ dsh --dump-config 可运行: node:fs:2430 (profile 目录不可写)
工具清单(25): echo, harness_list_tools, status_get, config_get, fs_read, fs_list, fs_stat, session_list, session_log, session_stats, session_search, preset_list, preset_get, preset_set, policy_get, set_policy, approval_list, approval_respond, agent_run, task_inbox, task_result, task_list, task_cancel, rename_session, attach_session
按上面每项的 ↳ 修复建议处理后重跑本脚本。
怎么读这份输出：
dsh --dump-config 那一项 ✗ 是权限问题（该目录属 root，当前用户不可写 cordis.yml），
不是插件问题 —— 它只用于静态确认，运行态的「MCP 握手 + tools/list」通过就说明插件已装载。
本机以 web profile 启动的服务其实已经在跑本插件（version=0.5.0 是该进程启动时的旧版本号，
升级后重启即变 0.7.0）。tools/list 是 25 个（enableFsWrite 未开）；开了 enableFsWrite: true 会是 26 个。- 若
tools/list 失败但端口在听，通常是 authToken 开了却没带 token —— 用 --token 或 DSH_MCP_TOKEN 重跑。
工具（26 个）
默认注册 25 个；enableFsWrite: true 时多一个 fs_write。
| 分类 | 工具 |
|---|
| 任务 | agent_run（同步）、task_inbox（异步队列）、task_result、task_list、task_cancel |
| 会话 | session_list、session_log、session_stats、session_search、rename_session、attach_session |
| 文件 | fs_read、fs_list、fs_stat、fs_write（opt-in） |
| 预设 | preset_list、preset_get、preset_set |
| 权限/审批 | policy_get、set_policy、approval_list、approval_respond |
| 状态 | status_get、config_get |
| 元 | echo、harness_list_tools |
完整的入参表 / 返回字段 / 错误码见 docs/TOOLS.md。
典型闭环
Hermes 记忆 ──context──▶ task_inbox ──▶ Harness agent 执行 ──▶ 结构化结果 {changes, verification, leftovers}
│
task_result 轮询 ◀────────────────────────┘
▼
结果回写 Hermes 记忆（下一轮 context）
agent_run 返回示例：
{
"sessionId": "…",
"assistantText": "最终回答",
"toolCalls": [{ "name": "bash", "args": "…" }],
"toolResults": ["命令输出"],
"changes": "改了什么",
"verification": "怎么验证的",
"leftovers": "遗留问题",
"stats": {
"rounds": 1, "steps": 3,
"llmTime": 13.9, "llmTimeMs": 13900,
"toolTime": 0.04, "toolTimeMs": 40,
"ttft": 3349, "tokensPerSec": 40.7,
"cacheHitRate": 1, "inputTokens": 8831, "outputTokens": 157
}
}
进阶：权限三档与审批桥
三档语义
会话文件权限档与 Harness 原生 SandboxMode 一一对应，通过会话日志的 sandbox/mode
事件固化（重启靠 replay 保持）：
| 档位 | 语义 |
|---|
read-only | 只读（仅 /dev/null 等必要 sink 可写） |
workspace-write | 工作区 + 后端临时区可写（默认，defaultSandbox 可改） |
danger-full-access | 完全绕过文件围栏 + bash 解禁，全程无审批任意读写 —— 仅限可信环境 |
agent_run / task_inbox 的 sandbox 参数是请求级覆盖：仅影响新建/resume 的会话组合；
已有会话保持原档位（显式切换用 set_policy）。同 cwd 三档互不污染。session_list 行在会话有 sandbox/mode 记录时带 sandboxMode 列。
审批转接（approvals 桥）
Harness agent 需要提权 → approval/request → [审批桥挂起]
Hermes: approval_list() 轮询 → approval_respond(approvalId, sessionId, 'allowed-once'|'rejected')
→ agent 继续（或收到拒绝）；Web UI 与 Hermes 双通道先答者胜
approvalsBridge 四档：web（默认，订阅 apiProxy mux；apiProxy 缺失时自动降级 builtin）/
builtin（插件内建应答器）/ file-push（内建应答 + pending_<id>.json 文件通知）/
off（关闭桥，审批回到部署默认 fail-closed）。- 审批未决期间
agent_run 同步阻塞（长阻塞场景请用 task_inbox 异步路径）；
approvalTimeoutMs（默认 300000ms = 5 分钟）超时收尾为取消/拒绝 —— 绝不超时放行。
- ⚠️
approval_respond 等于远程提权按钮：MCP server 暴露非 loopback 时必须开 authToken
（见 docs/SECURITY.md）。
完整配置字段见 docs/CONFIG.md。
FAQ：常见错误排查
把 src/index.ts 里所有面向用户的错误文案过了一遍，每条给「原因 + 修复步骤」。
所有错误的统一形状是 <错误>: <关键值> (<原因一句话>; <下一步动作>)。
| 症状 / 错误文案 | 原因 | 修复步骤 |
|---|
agent_run 返回文本但 toolCalls 恒空；agent 只输出 <tool_calls> 文本 | dual-package hazard：插件自己的 node_modules 和 Harness 全局树各有一份 @deepseek-ai/*，Symbol 不匹配 → scopeOf 为 undefined → preset 挂载被跳过 | ① 重做 symlink 修复（quickstart 第 ② 步）② 重启 Harness。dsh 升级/重装后 symlink 可能被还原，需再跑一次。日志特征：agent ctx unscoped (dsh rc.6 bug); preset mount skipped |
prompt variable "{{model}}" has no value | patch 没写 provider/model（插件默认 provider 是 deepseek-official、model 为空） | 在 patch 的 config 里补 provider: <your-provider-id> 和 model: <your-model-id>，必须是你的 Harness 里已配置好的，然后重启 |
MISSING_CREDENTIAL: <provider> | API key 没注入 Harness 进程 env | 在 systemd unit 加 Environment=<KEY>=...（或 EnvironmentFile=），或 export 后重启服务 |
Cannot find package '@deepseek-ai/cordis-plugin-include' | symlink 修复漏了 cordis-plugin-*；它们没发布到 npm registry，只存在于 Harness 全局树 | 补做 quickstart 第 ② 步里的 cordis-plugin-include / cordis-plugin-loader 两个 symlink |
| 版本号对但行为像旧版 | 系统里有双 npm 全局树，装错树 | which dsh + npm prefix -g 核对；用 systemctl show dsh.service -p ExecStart 看服务实际启动的 bin.js 路径，统一到那棵树 |
session_list failed: Cannot read properties of undefined (reading 'length') | dsh 0.1.5 改了 sessionPersistence 契约（list() 返回 snapshot、inspect() 移除）；v0.7.0 已修 | 升级到 hermes-dsh-bridge@0.7.0 并重启。若仍报，是 lib/index.js 陈旧 → npm run build 或重装 |
tools/list 只返回很少工具，或缺 fs_write | enableFsWrite 默认 false（fs_write 是 opt-in）；或插件没被加载 | fs_write 缺失属正常；其他缺失看 doctor 的 profile patch 已配置插件 与 dsh 已装载插件 两项 |
MCP 请求返回 401 {"message":"Unauthorized"} |
0.1.5 用户从旧版升级特别注意
| 变化 | 旧行为（≤ 0.1.1-rc.2 / dsh ≤ 0.1.1） | 新行为（dsh ≥ 0.1.2，0.1.5 起强制） | 你要做什么 |
|---|
| 会话存储格式 | session.jsonl.zstd + 目录带 session- 前缀 | session.v3.jsonl.zstd + 目录无 session- 前缀 | 不用迁数据；升级插件到 0.7.0 即自动兼容两代格式 |
sessionPersistence 契约 | list() 返回裸 header；有 inspect(id) | list() 返回 snapshot {header, revision, sizeBytes}；inspect() 移除，改 open(id,'read') + handle.read() | 升级插件；0.7.0 已做双契约兼容层 |
session_list 行为 | 单行读取失败可能整表崩 | 逐行容错：坏行跳过并计入新的 skipped 字段（0 = 全部正常） | 检查结果的 skipped；非 0 说明有个别会话读不出来，但列表仍可用 |
ctx.agent（单数） | 存在 | 移除 | 与本插件无关（只用 ctx.agents），但要保证 dsh ≥ 0.1.2 |
apiProxy 服务 | 随包提供，审批桥走 web | 0.1.5 不再随包发布 | 审批桥自动降级 builtin（本机部署用 file-push）→ status_get.sandboxPolicy.bridge 会显示实际生效值 |
| Web UI 面板 slot | 'conversation' | 'main' | 与本插件无关（不注册任何 UI slot） |
升级指南
0.7.0 → 0.8.0
破坏性变更：无。
task_inbox 新增可选参数 notifyUrl 与 replyContext；- 任务执行终态支持异步 HTTP POST 回调唤醒，带 HMAC-SHA256 验签与 SSRF 拦截；
- 历史调用不传 callback 时完全遵循 0.7.0 行为，100% 零破坏兼容。
0.5.x / 0.6.x → 0.7.0
破坏性变更：无。 工具名、参数名、既有返回字段全部保持不变 —— 0.7.0 只新增字段
（next / landing / skipped / preset / offset / pending 等）并统一错误串后缀。
按下面步骤迁移：
# 1) 升级插件
cd ~/.dsh/profiles/<PROFILE>/node_modules && npm install hermes-dsh-bridge@0.7.0
# 2) 重做 symlink（npm install 会把 symlink 还原成实体目录）
# 见 quickstart 第 ② 步
# 3) 检查 dsh 版本（0.7.0 要求 >= 0.1.2-rc.1）
dsh --version
# 4) 重启 + 自检
systemctl restart dsh.service
node scripts/doctor.mjs --profile <PROFILE>
python3 examples/hermes_dsh_mcp.py call status_get '{}' # version 应为 0.7.0
需要留意的行为变化（非破坏性，但客户端如有硬编码需调整）：
| 变化 | 影响 | 应对 |
|---|
时间戳改为 ISO8601 本地时区 + *_epoch 原值 | 原来读 epoch 数字的客户端若直接展示会看到日期串 | 用 *_epoch 字段排序/计算，用 *At 字段展示 |
列表类返回统一分页（默认 20，最大 100），带 next | 之前"一次全返回"，现在可能截断 | 读 truncated/next 翻页；需要更多一次给 limit |
session_log 默认最多 50 条事件 | 长会话默认只给首尾 | 调大 tail（最大 500）、head=0 只看最新，或用 preset/types 收窄 |
错误串统一加了 (<原因>; <下一步>) 后缀 | 用 == 精确比对错误串的客户端会失配 | 用前缀匹配（task not found / session not found / unknown preset / query must not be empty 均保留） |
config_get 不再回显 authToken: '***' | 只有 authTokenSet: boolean | 用布尔值判断是否开启 |
默认 cwd 改为 workspaceRoots[0]（配了才生效） | 之前是 process.cwd()（对远程调用无意义） | 不配 workspaceRoots 则行为不变；配了就是显式工作区 |
approvalTimeoutMs 默认 300000ms（5 分钟） | 老文档曾写 120s，是文档错误 | 想回到 2 分钟请显式设 approvalTimeoutMs: 120000 |
0.5.0 以下 → 0.7.0
跨大版本，有破坏性变更：v0.5.0 及更早只兼容 dsh ≤ 0.1.1-rc.2（旧 API）。
- 先升级 dsh 到 ≥ 0.1.2-rc.1（建议 0.1.5-rc.2），否则旧插件在 0.1.5 上会因会话存储契约变更崩溃。
- 升级插件到 0.7.0。
- 确认 patch 里审批桥配置：0.1.2 起
apiProxy 不再注入，approvalsBridge: web 会静默降级 builtin；
如需文件通知改用 file-push（配套 approvalFileDir）。
- 旧
sandbox 相关默认值不变（workspace-write），无需迁移数据。
- 重做 symlink → 重启 →
node scripts/doctor.mjs。
完整历史见 CHANGELOG.md。
文档
定位
适合做备用工具而非日常主力：日常改代码请直接驱动你的主 Agent。需要上下文隔离
（大重构会撑爆客户端上下文）或并行执行不相关任务时再找它。
- Agent 会话按 cwd 复用（避免每次调用重新加载项目上下文）。
- Bash 沙箱化（
workspace-write）：宿主机装 bubblewrap，否则写命令会被拒。
- reasoning/thinking 块在返回前剥离（插件侧 + 文本级兜底双层过滤）。
License
GPL-3.0-only，上游 MIT 部分保留——见 NOTICE.md。
