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.7.0：兼容 dsh ≥ 0.1.2-rc.1（已在 0.1.5-rc.2 实测）；26 个工具。

---

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.7.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"} | 部署开了 authToken 但请求没带 | 请求头加 Authorization: Bearer <token>；doctor 用 --token / DSH_MCP_TOKEN | | MCP 请求返回 404 Session not found | 用了失效的 Mcp-Session-Id | 客户端必须回显 initialize 响应头里的 Mcp-Session-Id；会话过期就重新 initialize | | session not found: <id> | 会话不存在或已清理（rename_session 还要求会话是 live） | session_list 取有效 id；冷会话先 agent_run(sessionId=...) 唤醒再改名；attach_session 支持 live 或持久化 | | session is empty: <key> | 会话存在但完全没有事件（或该 cwd 下没有会话） | 先跑一轮 agent_run / task_inbox 带上这个 sessionId，或去掉 cwd 过滤 / 换一个会话 | | task not found: <id> | 任务结果已过 TTL（默认 10 分钟）被清理，或 id 从不存在 | task_list 看队列现状；结果要在保留期内取走 | | unknown preset: <id> | preset id 不在当前部署名单里 | preset_list 拿合法 id；单次任务用 agent_run(preset=...) | | session has already started: <id> | preset_set(scope=session) 只能改空白会话（log 里没出现过 turn/start） | 已跑过的会话 preset 已固化 → 改用 agent_run(preset=...) 起新会话，或用 scope=new-default 改默认 | | session <id> is not live; cold/persisted sessions must be resumed first | set_policy 只能改 live 会话 | 先 agent_run(task=..., sessionId=...) 让它活起来再 set_policy；或直接在那一轮用 sandbox=... 定档 | | path outside allowed roots (~/.dsh + workspaces): <p> | fs_* 路径越过了 path jail | 换到 workspaceRoots 内的路径；config_get 看允许哪些目录 | | path denied by policy (sensitive name): <p> | 命中敏感名黑名单（.ssh / .env / 含 token / *.pem） | 这批路径设计上永不开放，换文件 | | file too large: <size> / content too large: <size> | fs_read 单文件 > 8MB / fs_write 单次 > 4MB | fs_read 用 offset/limit 分段；fs_write 拆成多次 mode=append | | <tool> failed: dsh service unreachable (...) | ECONNREFUSED/ECONNRESET/socket hang up —— Harness 没起或断了 | systemctl status dsh.service，必要时 systemctl restart dsh.service，再 status_get 确认 | | task queue full (N/100) | 活动任务（queued+running）达到 maxQueue | 等任务结束、task_cancel 取消一些，或调大 maxQueue | | receipt=not-pending（approval_respond） | 你慢了：审批已被 Web UI / 另一路回答，或已超时/撤回（先答者胜） | approval_list 刷新拿最新 approvalId；note 字段会说明原因 | | sessionId mismatch: <approvalId> | approval_respond 的 sessionId 与该审批不匹配 | 用 approval_list 里同一行的 sessionId 重试 | | 审批一直挂起不返回 | 没人在回答；超时前会一直等 | approval_list 看 pending（>0 就回答）；status_get.sandboxPolicy.pendingApprovals 也能一眼看到 | | TRANSPORT: terminated 中途断流 | LLM provider 抖了一下，流断 | 用同一个 sessionId 续接，不要新开会话（新会话会重读所有代码） | | assistantText 只到 ~8000 字符 | 结果字段有意限长（assistantText ≤ 8000，toolCalls ≤ 50×2000，toolResults ≤ 20×2000） | 用 session_log(sessionId=..., preset="dialog") 取完整文本 | | rename_session 报 sessionTitle service unavailable | 该部署没加载会话标题服务 | 不影响其他功能；改用 agent_run(title=...) 在创建时命名 | | workspaceRegistry unavailable | 该部署没加载工作区注册表服务 | 不影响任务执行；attach_session（纯整理）不可用而已 |

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.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）。

1. 先升级 dsh 到 ≥ 0.1.2-rc.1（建议 0.1.5-rc.2），否则旧插件在 0.1.5 上会因会话存储契约变更崩溃。
2. 升级插件到 0.7.0。
3. 确认 patch 里审批桥配置：0.1.2 起 apiProxy 不再注入，approvalsBridge: web 会静默降级 builtin； 如需文件通知改用 file-push（配套 approvalFileDir）。
4. 旧 sandbox 相关默认值不变（workspace-write），无需迁移数据。
5. 重做 symlink → 重启 → node scripts/doctor.mjs。

完整历史见 CHANGELOG.md。

---

文档

• docs/CONFIG.md — 全部配置字段（与代码逐字段核对）、安全默认值、可复制示例
• docs/TOOLS.md — 26 个工具的完整参考（入参表 / 返回字段 / 错误码）
• docs/TROUBLESHOOTING.md — 深度排障（SSE 解析、8KB 截断、dual-package hazard…）
• docs/KNOWN_ISSUES.md — 已发现但本轮不修的缺陷（含真实默认值口径）
• docs/SECURITY.md — 威胁模型
• scripts/doctor.mjs — 安装自检
• examples/hermes_dsh_mcp.py — 零依赖 Python MCP 客户端（仅标准库）

定位

适合做备用工具而非日常主力：日常改代码请直接驱动你的主 Agent。需要上下文隔离 （大重构会撑爆客户端上下文）或并行执行不相关任务时再找它。

• Agent 会话按 cwd 复用（避免每次调用重新加载项目上下文）。
• Bash 沙箱化（workspace-write）：宿主机装 bubblewrap，否则写命令会被拒。
• reasoning/thinking 块在返回前剥离（插件侧 + 文本级兜底双层过滤）。

License

GPL-3.0-only，上游 MIT 部分保留——见 NOTICE.md。