Skip to content

kio831/hermimo-link

BranchesTags

Repository files navigation

Hermimo Link v1.0.5

Release Python License Platform

让 Hermes 与 MiMo 像两个真正的协作同事一样互相交任务。

Hermimo Link 是一个仅依赖 Python 标准库的双 Agent 共享任务总线。你只需要对当前 Agent 说“让另一边帮我做这个”，任务就会被准确投递到另一端，自动执行、失败重试并回传结果。

English quick start is available near the end of this page.

第一次使用：五分钟上手

  1. 准备 Python 3.10+，并确认终端能够分别调用 Hermes 和 MiMo。
  2. 下载并完整解压发布包；不要直接在 ZIP 压缩包内运行安装或升级脚本。
  3. 按下方“安装”章节分别安装 Hermes 端和 MiMo 端。两端必须指向同一个物理共享目录，但必须使用各自独立的 Skill 安装目录。
  4. 启动两个 worker；使用 Windows MiMo + WSL Hermes 的一键升级时，升级程序会安装后台启动器并自动启动。
  5. 各自新开一次 Hermes 和 MiMo 会话，然后直接用自然语言交任务。

例如，对 Hermes 说：

请确认 Hermimo Link v1.0.5 已加载，并让 MiMo 检查这个项目的报错；等结果回来后再汇总给我。

对 MiMo 反向委派时说：

让 Hermes 评审这个方案，要求它给出风险和验证依据；等结果回来后告诉我。

正常投递会出现 TASK|<任务ID>|...，正常完成会出现 RESULT|<任务ID>|success|...。如果自动接收暂时异常，保留这个任务 ID，按“发送任务 ID 补收”章节恢复即可。

它解决什么问题

Hermes 和 MiMo 各有所长，但普通文件共享不能解决这些关键问题：

  • 谁应该执行这个任务？
  • 两端同时扫描时，如何避免重复执行？
  • 写到一半的 JSON 被另一端读到怎么办？
  • Agent 暂时失败后，如何自动重试？
  • MiMo 发给 Hermes 的任务会不会被 MiMo 自己拿走？
  • 两个 Agent 会不会把同一个任务来回踢成死循环？

Hermimo Link 使用独立收件箱、原子写入、原子认领、最终结果标记和转交深度限制解决这些问题。

核心特性

能力 说明
真正双向 Hermes → MiMo 与 MiMo → Hermes 使用同一套协议和 worker
自动路由 已安装 Skill 的 endpoint.json 标识本端并自动选择另一端
快速响应 默认每 0.2 秒检查一次任务，可用环境变量调整
防重复执行 任务从 inbox 原子移动到 processing，只有一个 worker 能认领
自动重试 默认最多尝试 3 次，重试结果不会被误认为最终失败
防无限转交 嵌套任务继承父任务和深度，默认最多转交 4 层
安全路径 HERMIMO_ALLOWED_ROOTS 限制 Agent 可以进入的工作目录
可选签名 HERMIMO_SHARED_SECRET 为任务、结果和事件添加 HMAC-SHA256 签名
可追溯 每次排队、认领、完成、重试和拒绝都会留下事件记录
条件协作 显式要求或遇到明确阻塞、能力缺失时，先通知用户再转交有边界的小任务
崩溃恢复 worker 中断后会回收超时的 processing 任务并按重试策略继续
后台自启动 Windows MiMo + WSL Hermes 可通过一键升级安装隐藏启动器
任务 ID 补收 自动接收异常时，把 `TASK
零第三方依赖 只需要 Python 3.10+

工作方式

sequenceDiagram
    participant U as 用户
    participant H as Hermes
    participant B as Hermimo Link
    participant M as MiMo
    U->>H: 让 MiMo 优化这个模块
    H->>B: 原子写入 inbox/mimo
    B->>M: MiMo worker 原子认领
    M->>M: 执行并验证
    M->>B: 写入最终结果
    B-->>H: RESULT|id|success
    H-->>U: 汇报结果与证据
Loading

共享目录结构：

.hermimo-link/
├── inbox/hermes/          # 等待 Hermes 执行
├── inbox/mimo/            # 等待 MiMo 执行
├── processing/<agent>/    # 已被对应 worker 认领
├── results/               # 最新结果
├── events/                # 不可变事件记录
├── archive/<agent>/       # 成功完成的任务
├── dead-letter/<agent>/   # 拒绝或重试耗尽的任务
├── state/                 # worker 心跳和历史结果
├── scripts/               # 运行脚本
├── service/               # Windows 隐藏自启动包装器
├── instructions/          # 两端长期协作规则
└── references/            # 协议说明

安装

已安装旧版：一键覆盖升级

upgrade.cmd 适用于 Windows MiMo + WSL Hermes，并会保留现有任务、结果和事件记录。升级前先让旧版正在排队或执行的任务结束，并关闭旧 worker：

.\upgrade.cmd

如果 Hermes 不在默认 WSL 发行版中：

.\upgrade.ps1 -WslDistro "你的发行版名称"

升级程序会备份旧运行文件，修复并覆盖两端 Skill，写入长期协作规则，安装隐藏开机启动 worker，运行双向协议自检，然后检查两个 worker 心跳。看到以下两行才表示升级完成：

SELFTEST|PASS|19 checks
Hermimo Link v1.0.5 upgrade completed

升级完成后，各自新开一次 Hermes 和 MiMo 会话，让两端重新加载长期指令。Linux、纯 Windows 或其他部署方式没有使用上述组合时，请分别在两端重新运行对应的 setup.sh 或 setup.ps1，不要直接套用 Windows + WSL 专用升级流程。

高级用户可运行 upgrade.ps1 -NoStart 只安装而暂不启动，或使用参数覆盖 WSL 发行版、Skill 路径和共享目录。

从 V1.0.4 开始启用 HERMIMO_SHARED_SECRET 时，旧版已生成的无签名任务或结果不能通过 V1.0.5 的签名校验。因此应先完成旧任务，并把旧结果仅作为历史存档保留，不要重新放回 V1.0.5 队列。

前置条件

  • Python 3.10 或更高版本
  • 已安装并能从终端调用 Hermes 和 MiMo
  • 两端能够读写同一个物理目录

Windows / PowerShell

在 Hermes 端运行：

.\setup.ps1 -Agent hermes -SharedDir "$env:USERPROFILE\.hermimo-link"

在 MiMo 端运行，并使用同一个目录：

.\setup.ps1 -Agent mimo -SharedDir "$env:USERPROFILE\.hermimo-link"

如果系统提示“running scripts is disabled”，使用一次性执行策略运行，不会修改系统的永久策略：

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1 `
  -Agent hermes -SharedDir "$env:USERPROFILE\.hermimo-link"

如果还要把 Skill 自动复制进某个 Agent 的 skills 父目录：

.\setup.ps1 -Agent hermes `
  -SharedDir "$env:USERPROFILE\.hermimo-link" `
  -SkillDir "C:\path\to\agent\skills"

不同 Agent 版本的 skills 目录可能不同，因此安装脚本不会猜测路径；传入 -SkillDir 时，它会创建 hermimo-link 子目录。

V1.0.5 不再把 HERMIMO_AGENT 写入用户级全局环境。每个 Skill 安装目录会生成自己的 endpoint.json；同一系统用户运行两端时，请为两端传入不同的 skills 父目录。直接从发布目录运行命令时，使用 --from hermes 或 --from mimo 明确本端。

Linux / WSL

# Hermes 端
bash setup.sh hermes "$HOME/.hermimo-link" "/path/to/hermes/skills"

# MiMo 端
bash setup.sh mimo "$HOME/.hermimo-link" "/path/to/mimo/skills"

Linux/WSL 安装同样使用各 Skill 目录内的 endpoint.json 保存身份，不会在 .bashrc 中写入全局 HERMIMO_AGENT。

Hermes 在 WSL、MiMo 在 Windows

两端必须指向 Windows 上的同一个物理目录。例如 Windows 用户名是 alice：

# Windows / MiMo
.\setup.ps1 -Agent mimo -SharedDir "C:\Users\alice\.hermimo-link"
# WSL / Hermes
bash setup.sh hermes "/mnt/c/Users/alice/.hermimo-link"

不要让 WSL 使用自己的 ~/.hermimo-link、Windows 又使用另一个目录，否则两端互相看不到任务。

启动两个 Worker

Hermes 端：

python scripts/worker.py --agent hermes

MiMo 端：

python scripts/worker.py --agent mimo

启动成功会输出：

READY|hermes|<shared-directory>|0.2
READY|mimo|<shared-directory>|0.2

如果 Agent 的实际命令与默认值不同，请先设置命令模板：

$env:HERMIMO_HERMES_COMMAND = 'hermes run {prompt}'
$env:HERMIMO_MIMO_COMMAND = 'mimo.exe run {prompt}'

使用

最简单的方式：直接对 Agent 说

  • 对 Hermes 说：让 MiMo 帮我分析这个报错，并把修复方案发回来。
  • 对 MiMo 说：这个架构问题让 Hermes 帮我判断一下。
  • 对任意一端说：这部分另一边更擅长，转给它，等结果回来。

Skill 会读取本端身份并自动投递给另一端。

命令行投递并等待结果

python scripts/delegate_task.py \
  --from hermes \
  --goal "优化 parser.py 的性能" \
  --context "项目位于 D:/work/app，热点函数是 parse_tokens" \
  --verification "返回修改文件和基准测试结果" \
  --wait

成功投递和完成会分别返回：

TASK|<uuid>|<task-path>
RESULT|<uuid>|success|<result-path>

异步执行时去掉 --wait，之后用任务 ID 查询：

python scripts/taskctl.py wait <task-id>
python scripts/taskctl.py show <task-id>

需要让接收端直接进入项目目录时，先在接收端设置允许范围，再添加 --workdir：

$env:HERMIMO_ALLOWED_ROOTS = 'D:\work'
python scripts/delegate_task.py --from hermes --goal '检查项目' --workdir 'D:\work\app' --wait

任务管理

python scripts/taskctl.py list
python scripts/taskctl.py workers
python scripts/taskctl.py show <task-id>
python scripts/taskctl.py wait <task-id> --timeout 600
python scripts/taskctl.py retry <task-id>
python scripts/taskctl.py cancel <task-id>

对方没有收到时：发送任务 ID 补收

投递成功后会显示：

TASK|<task-id>|<task-path>

把其中的 <task-id> 发给应该接收任务的 Agent，并对它说：

请通过 Hermimo Link 补收任务：<task-id>

接收方会先确认任务确实发给自己；如果任务仍在收件箱，就只认领这个 ID：

python scripts/taskctl.py show <task-id>
python scripts/worker.py --agent <hermes-or-mimo> --task-id <task-id> --once
python scripts/taskctl.py wait <task-id> --timeout 300

这里必须使用 Hermimo 输出的任务 ID。有些界面会把聊天编号称为“会话 ID”，但 Hermes 与 MiMo 各自的聊天会话 ID 不能互相通用，也不能代替任务 ID。已经处于 processing 或已经完成的任务只需等待或查看结果，不要再次执行；进入 dead-letter 的任务应先查明原因，再使用 taskctl.py retry <task-id>。

安装后自检

安装脚本会自动运行不调用真实 Agent 的双向自检，也可以随时手动运行：

python scripts/self_test.py

正确输出：

SELFTEST|PASS|19 checks  # Windows
SELFTEST|PASS|18 checks  # Linux / WSL

这个自检会验证双向投递、任务/结果/事件 HMAC、子进程密钥隔离、并发原子认领、取消终态、结果发布顺序、失败重试、拒绝结果、崩溃恢复、手动重试清理和 Windows 命令路径，但不会消耗 Hermes 或 MiMo 的模型额度。

常用配置

环境变量 用途 默认值
HERMIMO_LINK_DIR 两端共享目录 ~/.hermimo-link
HERMIMO_AGENT 当前端身份 优先读取进程变量，否则读取已安装 Skill 的 endpoint.json
HERMIMO_POLL_INTERVAL 轮询间隔 0.2 秒
HERMIMO_HERMES_COMMAND Hermes 命令模板 hermes run {prompt}
HERMIMO_MIMO_COMMAND MiMo 命令模板 mimo.exe run {prompt}
HERMIMO_ALLOWED_ROOTS 可接受的任务工作目录 未配置时拒绝 workdir
HERMIMO_SHARED_SECRET 两端 worker/根会话共享的主签名密钥 默认不签名
HERMIMO_DELEGATION_TOKEN 仅限当前父任务的嵌套委派令牌 worker 自动生成

安全建议

  1. 把共享目录视为一个命令通道，不要公开写权限。
  2. 两端设置相同且随机的 HERMIMO_SHARED_SECRET。
  3. 使用 HERMIMO_ALLOWED_ROOTS 限制 Agent 能操作的项目目录。
  4. Worker 使用普通用户运行，不要使用管理员或 root 权限。
  5. 不要把 API Key、密码或访问令牌放进任务 context。
  6. Agent 原有的系统规则和安全限制始终高于收到的任务内容。
  7. 一键升级会把旧启动脚本中的内联 DEEPSEEK_API_KEY 迁移到 WSL 权限为 600 的环境文件，并脱敏备份；已经出现在进程命令行中的旧密钥仍应立即撤销和轮换。

重要注意事项

  • 当前不是任意 Agent 的通用适配器。 V1.0.5 内置的是 Hermes 与 MiMo 的命令模板、身份和路由；接入其他 Agent 需要为其补充命令适配、身份配置和协议测试。
  • HMAC 只校验来源和完整性，不加密内容。 任务、结果、事件、日志以及 Agent 的标准输出/错误仍以明文保存在共享目录中，不要在里面放 API Key、密码、个人隐私或其他机密。
  • 崩溃恢复是至少执行一次，不是严格只执行一次。 worker 在崩溃恢复或超时重试后，任务可能再次执行。涉及付款、发邮件、发布、删除或写入外部系统的任务必须设计成幂等操作，并保留人工确认。
  • 取消只适用于仍在 inbox 中的排队任务。 taskctl.py cancel 不会强制终止已经进入 processing 的 Agent 进程；执行中的任务应等待结束，或由操作者单独停止对应进程并检查现场。
  • 两端签名密钥必须完全一致。 只给一端设置或两端值不同都会导致任务被拒绝。HERMIMO_DELEGATION_TOKEN 由 worker 自动生成，不要手工配置或长期保存。
  • workdir 使用接收端能识别的本机路径。 它还必须位于接收端的 HERMIMO_ALLOWED_ROOTS 内；Windows 路径和 WSL 路径不能直接混用。
  • 同一用户运行双端时，Skill 目录必须分开。 Hermes 与 MiMo 各自的 endpoint.json 代表本端身份，不能复制同一份安装目录给两端共用。
  • 任务 ID 不等于聊天或会话 ID。 补收、查询、取消和重试只能使用 TASK| 后显示的 UUID。
  • 后台环境和当前终端可能不同。 后台 worker 使用的账户必须能找到 Python、Hermes/MiMo 命令和所需环境变量；终端里能运行不代表后台一定能运行。
  • 不要把运行时数据提交到 GitHub。 .hermimo-link/、.mimocode/、endpoint.json、任务、结果、日志、备份和包含密钥的配置都属于本机数据。仓库只应包含干净的发布源码。

故障排查

任务一直停在 inbox

  • 确认目标端 worker 正在运行并输出了正确的 READY|...。
  • 确认两端使用同一个物理 HERMIMO_LINK_DIR。
  • 检查任务是否进入了正确的 inbox/hermes 或 inbox/mimo。

任务进入 dead-letter

查看对应任务事件和最终结果：

python scripts/taskctl.py show <task-id>

常见原因包括 Agent 命令不存在、签名不一致、workdir 不在允许范围、任务格式错误或执行超时。

任务投递成功但命令无法启动

根据本机安装方式修改命令模板。例如：

$env:HERMIMO_MIMO_COMMAND = 'C:\Tools\mimo.exe run {prompt}'
# 路径含空格时，给可执行文件路径加双引号：
$env:HERMIMO_MIMO_COMMAND = '"C:\Program Files\MiMo\mimo.exe" run {prompt}'

从旧版迁移

  • V1.0.3 简化包使用公共 tasks/ 和 .seen_tasks.json，请不要与 V1.0.5 worker 混用。
  • V1.0.5 默认使用 .hermimo-link/，仍接受 V0.1.4 的协议 v2 任务和旧的 HANDSHAKE_DIR 回退。
  • 先停止旧轮询脚本，再分别在两端运行新的安装脚本。
  • 保留旧目录作为备份，确认 V1.0.5 自检通过后再迁移任务。

V1.0.5 更新内容

  • 为结果和事件增加带类型隔离的 HMAC-SHA256 签名，并在等待和查看结果时验证签名。
  • Agent 子进程不再继承 HERMIMO_SHARED_SECRET，嵌套委派改用父任务范围的受限令牌。
  • taskctl 严格校验 UUID、任务字段、文件名和签名，阻止路径越界。
  • 取消任务会发布签名的最终结果，不再让等待方超时。
  • 最终结果改为终态移动后的两阶段发布，并支持恢复待发布结果。
  • 每个已安装 Skill 使用独立 endpoint.json，避免同一用户下双端身份互相覆盖。
  • Skill 指令使用自身绝对目录定位脚本，并收窄自动触发条件。
  • 增加 agents/openai.yaml，扩充安全、取消、并发和状态一致性自检。

V1.0.4 更新内容

  • 修复公共 .seen_tasks.json 格式冲突和双端误消费问题。
  • Hermes 与 MiMo 使用完全相同的自动 worker。
  • 增加本端身份和自动选择另一端的路由机制。
  • 默认轮询间隔从 1 秒降低到 0.2 秒。
  • 增加 --wait 和 taskctl wait，忽略中间重试结果。
  • 默认失败尝试次数调整为 3 次，默认重试等待 2 秒。
  • 增加父任务继承和最大转交深度，防止无限来回委派。
  • 修复 Windows 安装路径，加入可选 skills 目录安装和自动自检。
  • 接受带 UTF-8 BOM 的 Windows JSON 文件。
  • 统一发布包、Skill 指令、协议文档和版本号。
  • 修复 Windows 完整命令路径中的反斜杠丢失。
  • 被拒绝的任务现在会立即生成最终结果，不再让 --wait 空等到超时。
  • 增加 processing 租约、worker 心跳和崩溃后的超时恢复。
  • 修复 taskctl retry 留下重复任务和旧结果的问题，并保留历史结果。
  • 加入长期主动委派规则和 Windows MiMo + WSL Hermes 一键覆盖升级。
  • 增加按 Hermimo 任务 ID 精确补收，目标端可在自动接收异常时只认领指定任务。

English quick start

Hermimo Link is a standard-library-only task bus that lets Hermes and MiMo route work to each other, execute it automatically, retry failures, and return final results.

# Hermes endpoint
.\setup.ps1 -Agent hermes -SharedDir "$env:USERPROFILE\.hermimo-link"

# MiMo endpoint, using the same physical directory
.\setup.ps1 -Agent mimo -SharedDir "$env:USERPROFILE\.hermimo-link"

Start one worker on each endpoint:

python scripts/worker.py --agent hermes
python scripts/worker.py --agent mimo

An installed Skill reads its endpoint-local identity automatically. When running directly from the release directory, pass --from explicitly:

python scripts/delegate_task.py \
  --from hermes \
  --goal "Review this module" \
  --context "Repository: D:/work/app" \
  --verification "Return findings and evidence" \
  --wait

If automatic receipt is delayed, give the receiving endpoint the UUID printed after TASK|:

python scripts/worker.py --agent <receiver> --task-id <task-id> --once
python scripts/taskctl.py wait <task-id> --timeout 300

Use the Hermimo task ID, not a Hermes or MiMo native chat/session ID.

Important limitations:

  • V1.0.5 is specifically adapted for Hermes and MiMo; other agents require an adapter and protocol tests.
  • HMAC authenticates records but does not encrypt task content, results, events, or logs.
  • Crash recovery provides at-least-once execution, so externally visible side effects must be idempotent and user-confirmed.
  • taskctl.py cancel only cancels tasks that are still queued in an inbox; it does not kill a task already being processed.
  • Use separate Skill directories for the two endpoints, while pointing both endpoints to the same physical shared runtime directory.
  • Do not commit runtime queues, endpoint.json, logs, backups, or secrets to GitHub.

License

MIT © 2026 kio831

About

Hermes ↔ MiMo Code 文件握手协作通道 — 双 Agent 自动互通任务

Topics

multi-agent handshake task-delegation ai-agent hermes-agent mimo-code task-bus

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 5

Hermimo Link v1.0.5 — Security, Reliability and Upgrade Release Latest
Jul 21, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages