Herdr Link

English | 简体中文

Herdr Link 是运行在 Herdr 会话中的跨 Agent 按需互操作层。同一 workspace 内的 Agent 可以按调用方明确选择启动 Agent、互相发现、交换协议化消息、关闭已完成的 pane——通过一个 lazy gateway 暴露 4 项核心能力，零学习成本。

提供 OpenCode（插件 bundle）以及 Pi / Claude Code / Codex / AGY 通过同一个共享 stdio MCP server 接入的 Adapter。线上格式为 herdr-link/1 协议，唯一规范见 PROTOCOL.md。

为什么选择 Herdr Link？

让 Agent 学会跨 Agent 通信的常规方式是给它官方 Herdr Skill。这可行，但有一笔随每个 Agent、每个会话不断重复支付的成本：

• Agent 必须先阅读 Skill 文档并思考如何驱动 CLI，然后才谈得上真正通信；
• 这些推理过程每次使用都在消耗 token 并增加延迟；
• 使用知识靠模型反复自行推导，而不是直接交给它。

Herdr Link 把这一步彻底去掉。Adapter 通过一个惰性 gateway 暴露 4 项核心能力，并在激活后提供紧凑的通信契约：

| | 官方 Herdr Skill 路线 | 使用 Herdr Link | |---|---|---| | Agent 需要学什么 | Skill 文档 + CLI 用法 | 无需学习——直接调用工具 | | 第一条消息之前 | 用法推理（token + 延迟） | 一次工具调用 | | 空闲期上下文开销 | 加载时携带 Skill 内容 | 仅一个极小的 dormant gateway | | 对端寻址 | 每次临时推导 | herdr_link_peers 直接返回 live named agents |

一句话总结：

• 更少消耗。 无需阅读、无需推导。dormant 态下模型只看到一个极小的 herdr_link gateway——没有契约文本，只有覆盖 activation 与四个 action 的最小 schema；激活后获得紧凑的契约面，而不是一本手册。
• 更快控制。 启动 Agent、发现对端、发送协议化消息或关闭 pane 都是一次直接的工具调用——中间没有任何多步 CLI 编排。
• 无感接入（零推理）。 用户显式提出 Herdr 需求、或收到 inbound herdr-link/1 消息时自动激活；完成通过普通的 herdr_link_send：将指定结果发给 from；未指定结果时成功后精确发送 done；失败/阻塞时发送简短说明；只有明确要求不回复时才不发送。done 只是普通消息，不是 ACK、任务状态或投递回执。

工作方式

每种 Runtime 都呈现同样的惰性两级能力面：

Agent A → herdr_link {}                    # 激活（幂等）
Agent A → herdr_link_start(name, config_agent[, cwd])  # 配置模式，Link 管理 placement
Agent A → herdr_link_start(name, kind, args[, cwd])     # 显式模式，Link 管理 placement
Agent A → herdr_link_start(..., with="worker-a")       # 同 tab：与 live Agent 并排
Agent A → herdr_link_send(to="B", ...)     # status "sent"
Agent B → （收到 inbound wrapper）herdr_link {}   # 自动激活触发
Agent B → herdr_link_send(to="A", message="结果或 done")
任意一方 → herdr_link_close(agent="worker-a")   # 由调用方决定；独立的后续工具步骤

• Dormant 层：只有 herdr_link gateway 可用；Codemode Host 通过 searchTools() 发现它。空参 {} 调用一次性激活当前 session（幂等、纯内存态）。
• Active 层：herdr_link_start、herdr_link_peers、herdr_link_send、herdr_link_close，外加激活后的契约面。每次通信调用都经 Herdr 实时解析身份/workspace 并执行同 workspace guard。

启动 Agent

herdr_link_start 只执行调用方已经作出的启动选择，不选择业务角色。placement 由 Link 机械处理：未给出 with anchor 时新建 tab；给出 with anchor 时与 anchor 同 tab 并排。

项目级 start 配置

项目级配置是可选的，固定位置为：

<project-root>/.agents/agent_config.json

GitHub 仓库和 npm 包都包含官方模板：

examples/agent_config.example.json

在目标项目中使用模板：

mkdir -p .agents
cp /path/to/agent_config.example.json .agents/agent_config.json

复制命令只是便利方式；下面同时给出完整 schema，因此 npm 用户不需要知道包实际安装目录：

{
  "agents": {
    "example-single": {
      "placement": { "mode": "new_tab" },
      "variants": [
        {
          "kind": "pi",
          "args": [
            "--model",
            "your-provider/your-model",
            "--thinking",
            "high"
          ]
        }
      ]
    },
    "example-with": {
      "placement": { "mode": "with" },
      "variants": [
        {
          "kind": "pi",
          "args": [
            "--model",
            "your-provider/your-model",
            "--thinking",
            "high"
          ]
        }
      ]
    }
  }
}

需要长期复用的启动方式使用 configured start：{"name":"worker-01","config_agent":"example-single"}。config_agent 是 agents 下由项目自行定义的 key，Herdr Link 不解释其业务含义。

一次性启动使用 explicit start，不修改项目配置：{"name":"worker-01","kind":"pi","args":["--model","model-x","--thinking","high"]}。两种模式严格互斥；配置调用不能只覆盖 kind 或 args。

Placement 由 Link 管理：每个 configured entry 必须声明 placement（new_tab 或 with）；显式启动默认新建 tab，除非传入 with=<live Agent Name>（与 anchor 同 tab 并继承其 pane cwd）。cwd 可选，只设置新 tab 的 launch 工作目录，绝不改变 .agents/agent_config.json 的查找位置。

人类用户与 AI Agent 的配置规则

人类用户或 AI Agent 创建、修改 .agents/agent_config.json 时：

1. 长期或重复使用的启动方式写入 agents.<config-key>。
2. <config-key> 由项目自行命名，例如 work-agent、reviewer、research-agent、fast-worker；Herdr Link 不赋予它业务含义。
3. 每个 configured entry 必须显式声明 placement：{"mode":"new_tab"}（独立 tab）或 {"mode":"with"}（与 live anchor 并排，不新建 tab）。
4. 每个 variant 必须包含非空 kind。
5. args 如果存在，必须是字符串数组，并直接放在 herdr agent start ... -- 之后传递。
6. 只有一个 variant 时不需要 strategy。
7. 多个 variants 必须使用 "strategy": "round-robin"。
8. 不要创建半填写 entry 并期待 herdr_link_start 运行时补齐；不支持 partial override、merge 或猜测缺失值。
9. 用户只要求这一次使用某组参数时，不要修改配置文件，应使用 explicit start。
10. “以后默认这样启动”或“以后让这个 worker 在 A/B 之间轮换”等持久偏好，才适合修改配置文件。

决策关系：

| 用户意图 | 项目文件 | 启动模式 | |---|---|---| | 长期 / 重复启动方式 | 写入 .agents/agent_config.json | configured | | 一次性 / 临时启动参数 | 不修改文件 | explicit |

Herdr Link 不决定 Agent 应该做什么，也不调度工作、选择模型或回收 Agent。start 只执行调用方提交的配置或显式启动选择；Link 机械创建声明的 placement（新 tab，或 with anchor 旁的 sibling pane），其余能力是消息层。

安装

Pi（共享 stdio MCP server）

Pi 使用内置 MCP 客户端，连接与 Claude Code、Codex、AGY 相同的 stdio server。保留 Pi 包管理器中的包登记，使 pi update npm:herdr-link 更新同一份安装；MCP server 直接从该安装目录启动，不使用 npx：

pi install npm:herdr-link   # 尚未登记时执行

最低支持 Pi 0.99.2（MCP server description 支持）。在用户级 Pi MCP 配置中注册 server（~/.pi/agent/mcp.json；设置 PI_CODING_AGENT_DIR 时使用 <agent-dir>/mcp.json）：

{
  "mcpServers": {
    "herdr_link": {
      "command": "node",
      "args": ["<agent-dir>/npm/node_modules/herdr-link/dist/herdr-link.mcp.js"],
      "exposure": "codemode",
      "description": "Only use Herdr Link when the user explicitly requests Herdr communication or when handling an inbound Herdr Link message."
    }
  }
}

exposure: "codemode" 不把 MCP 工具放进声明工具列表；模型通过 searchTools() 发现 gateway 与 Tier 1，使用 tools.mcp__herdr_link__herdr_link({}) 激活，并通过 mcp__herdr_link__* namespace 调用 Tier 1。server 继承 Pi 进程的 HERDR_*。修改包或 MCP 配置后重启 Pi。

Pi 不注入任何提示词文本，呈现方式刻意比其他 Host 更轻：dormant 阶段的触发条件来自 mcp.json 的 description 字段与 gateway 描述，激活后以共享 MCP 的工具描述为唯一契约来源。Claude Code、Codex、AGY 在启动时注入一段短 Tier-0 hint，OpenCode 注入按 session 的契约——Pi 两者都不做。PROTOCOL §3 把这定义为两档契约呈现之一——「描述式」（另一档为注入式），Pi 与其它 shared MCP Host 同属描述式。唯一保留的 Pi 扩展是极简 wait guard：在 Herdr managed pane 内拦截 herdr agent wait 与 herdr agent prompt ... --wait 两类 Bash 命令，只匹配真正会执行的命令词（引号、heredoc/here-string 正文与注释内的同名文本不计），不注册工具、不修改提示词。

OpenCode（V1 / V2 独立 bundle）

OpenCode 把插件目录里每个文件都当作 plugin 加载，因此只能部署一份预构建 bundle——不能平铺源文件，也不能同时放入两个 Runtime 的 bundle。同一个 npm 包提供两份互相隔离的构建：

| OpenCode Runtime | Bundle | |---|---| | OpenCode 1（V1） | dist/herdr-link.opencode.js | | OpenCode 2（V2） | dist/herdr-link.opencode-v2.js |

用包内安装器部署其中的一份：

npm install -g herdr-link
herdr-link-opencode-install --runtime v1 --dry-run   # 或 --runtime v2
herdr-link-opencode-install --runtime v1             # 或 --runtime v2

安装器是 Node CLI，Windows PowerShell、Linux（含 WSL）与 macOS 使用同一组命令。它会确定 OpenCode 配置目录（优先 opencode debug paths，其次 HOME/XDG/AppData 默认值），用包内固定的 dist/herdr-link.opencode.manifest.json 校验 bundle 的 Runtime 标记与 SHA-256，扫描全局与项目级插件目录中的重复 Herdr Link 入口，未经明确确认（非交互场景用 --yes）绝不覆盖来源不明的文件，替换前保留带时间戳的备份，原子替换后校验部署文件的导出形状；最终校验失败会自动回滚——恢复带时间戳的备份，或在没有旧文件时删除本次刚写入的文件，并明确报告回滚结果。 WSL 安装只作用于 WSL 自己的配置目录；Windows 原生 OpenCode 属于独立配置，不会被修改。

OpenCode V1 还要求插件目录能够解析 @opencode-ai/plugin。 安装器会用 Node ESM 解析（import.meta.resolve）+ 文件系统版本读取做预检（支持范围 ^1.18.13），不会代为安装依赖；预检失败会带修复指引中止部署。V2 没有该 SDK 前置要求。

切换 Runtime 会重写同一个目标文件：安装器会显示旧、新 Runtime，要求明确确认并保留备份。--dry-run 不写任何文件。直接使用 opencode plugin add herdr-link 不是受支持的安装方式；包的根路径刻意不暴露插件导出。 卸载即删除 plugins/herdr-link.js；需要回退时恢复带时间戳的备份即可。安装器只会删除校验失败时自己刚写入的目标文件，不会删除其他插件或用户文件。

OpenCode 没有按 session 启停工具的 API，因此 Adapter 采用single-gateway dispatcher 呈现：{} 激活，之后 {"action":"start"|"peers"|"send"|"close", ...} 分发到同一控制层。start 使用 name + config_agent 或完整的 name + kind + args，可选 with / cwd 控制 placement；两种模式不合并。契约只注入已激活 session 的 system prompt（按 sessionID 记忆的内存态；server 重启回到 dormant）。

V2 使用 ctx.tool.transform 注册 herdr_link，并以 options: { codemode: false } 直接列入模型工具清单（插件工具默认只进 Code Mode catalog，模型不知道工具名就无法发现它）。注册不依赖进程注入的 HERDR_*：OpenCode 的 server 插件运行在服务多个 pane 的共享后台服务里，本就没有 pane 身份。每次调用把 session 归属到恰好一个 live pane：先匹配 Herdr 的 OpenCode 集成为该 pane 上报的 agent session id（子会话沿 parentID 回到上报的根会话），再退到唯一的会话项目目录；零个或多种匹配即 fail closed（SELF_UNNAMED），Herdr CLI 不可用仍是 NOT_IN_HERDR。契约只通过 ctx.session.hook("context") 注入已激活会话。V1 入口保留，互不覆盖。

Claude Code / Codex / AGY（共享 stdio MCP server）

Claude Code、Codex、AGY 与 Pi 共用同一个 stdio MCP server（不依赖 MCP SDK，配置使用 Node 原生 JSON.parse），以本包的 bin 发布：

npx -y herdr-link           # 在 stdio 上启动 MCP server

注册 namespace 必须用 herdr_link（下划线）。各 host 呈现形态不同：Claude Code / Codex 以前缀函数（mcp__herdr_link__<tool>）呈现，AGY 经原生 call_mcp_tool wrapper 调用——入参、出参与错误语义完全一致。各 host 的注册配置与 Tier-0 hint 接线（launcher 参数 / SessionStart hook / PreInvocation hook）见 docs/mcp-wiring.md。

MCP 同样是惰性呈现：非 Herdr 环境 tools/list 返回空集；Herdr managed pane 内 dormant 时只列出 gateway；激活后发射一次 notifications/tools/list_changed（不响应刷新的 host 可继续通过 gateway action 分发保持全功能）。

环境要求

in-pane 宿主（Pi、Claude Code、Codex、AGY、OpenCode V1）必须由 Herdr 在 managed pane 中启动。OpenCode V2 不需要这些变量：它把每个 session 归属到自己的 pane，binary 缺省时按 PATH 解析 herdr：

| 变量 | 用途 | |---|---| | HERDR_ENV=1 | 确认处于 Herdr 环境 | | HERDR_BIN_PATH | 当前 Herdr binary 路径；失效时返回 NOT_IN_HERDR | | HERDR_PANE_ID | caller pane，用于实时解析 self identity 与权威 workspace |

• 非 Herdr managed pane 中没有任何 Herdr 能力可用：Pi 扩展只注册 wait guard，MCP 返回空工具集，OpenCode V2 仍列出 gateway 但每次调用 fail closed（SELF_UNNAMED）。Pi 仍可能显示已配置的 MCP server 元数据；
• Herdr 环境 dormant 态下，模型侧只有 herdr_link gateway——不注入 Contract 文本；OpenCode V2 直接在工具清单中列出它，Codemode Host 通过 searchTools() 发现；
• Self identity bootstrap（PROTOCOL.md §6.3）：用户手动启动、已被 Herdr 识别但尚无合法 Agent Name 的 agent，会被自动赋一个生成的 hl-* 名字（in-pane 宿主在 Adapter 启动时执行一次 ensureSelfName()；OpenCode V2 按归属 pane 在每次通信路径内兜底）。已有名字绝不改写、不持久化；bootstrap 失败时 Link 以 SELF_UNNAMED 报错；
• 运行期失败通过 Link error 返回（NOT_IN_HERDR / SELF_UNNAMED / PEER_NOT_FOUND / SEND_FAILED / CLOSE_FAILED / START_CONFIG_NOT_FOUND / START_AGENT_NOT_FOUND / START_CONFIG_INVALID / START_INPUT_INVALID / START_FAILED）。

错误模型

| Code | 含义 | |---|---| | NOT_IN_HERDR | Herdr 环境不可用（变量缺失、binary 失效/被删除、transport 失败、非法 JSON） | | SELF_UNNAMED | Herdr Link 已尝试建立稳定 Agent Name（self identity bootstrap，PROTOCOL.md §6.3）但失败——occupant 尚未被 Herdr 检测或自动命名未成功 | | PEER_NOT_FOUND | 目标不是当前 workspace 内的 live named peer（不存在/非法名/其他 workspace——对模型不可区分） | | SEND_FAILED | guard 通过后 Herdr 未接受 message prompt | | CLOSE_FAILED | 目标已解析到 pane，但 Herdr pane close 失败 | | START_CONFIG_NOT_FOUND | 配置模式找不到 .agents/agent_config.json | | START_AGENT_NOT_FOUND | config_agent 不在配置的 agents 映射中 | | START_CONFIG_INVALID | JSON、schema、variants 或 strategy 非法 | | START_INPUT_INVALID | start 字段缺失、类型错误或两种模式混用 | | START_FAILED | Herdr 拒绝或启动 Agent 失败 |

错误是本地 tool failure，不是跨 Agent 消息类型；Link 不提供 ACK、wait、poll、task/pending 状态、自动重试或 fallback。

开发

仓库包含完整的可审计与可扩展组件（test/、tsconfig.json、构建脚本）。npm 发布包由 package.json 的 files allowlist 控制。

npm install
npm run typecheck
npm test                    # node --experimental-strip-types --test test/*.test.ts
npm run build:opencode      # dist/herdr-link.opencode.js（V1）
npm run build:opencode-v2   # dist/herdr-link.opencode-v2.js（V2）
npm run build:mcp           # dist/herdr-link.mcp.js
npm run check:opencode-bundles  # manifest、Runtime 标记、SHA-256、导入隔离

目录结构：

PROTOCOL.md                  协议唯一规范（Envelope、两级能力面、Contract、工具语义、错误模型）
src/protocol.ts              协议核心：类型、envelope/wrapper 构建、错误、COMMUNICATION_CONTRACT
src/herdr.ts                 Herdr CLI 控制层：configured/explicit Agent start、JSON 配置解析、cursor、live identity/workspace 解析
src/pi-wait-guard.ts          Pi 扩展：极简 Bash wait guard（不注册工具、不注入提示词）
src/opencode.ts              OpenCode Runtime Adapter：single-gateway dispatcher + 按 sessionID 契约注入
src/opencode-v2.ts           OpenCode 2 Runtime Adapter：直接列出的 gateway、按 session 注入契约、按调用归属 pane
src/mcp.ts                   共享 stdio MCP server：JSON-RPC、惰性工具列表、gateway dispatch
docs/mcp-wiring.md           Pi / Claude Code / Codex / AGY 注册与 Tier-0 hint 接线指南
dist/*.js                    预构建 bundle（OpenCode V1/V2 插件、MCP server bin）
dist/herdr-link.opencode.manifest.json 构建清单：各 bundle 的 Runtime、版本与 SHA-256
scripts/mcp-probe.mjs        stdio 握手排障探针
scripts/install-opencode.mjs  OpenCode Runtime 安装器（bin: herdr-link-opencode-install）
scripts/build-opencode.mjs    OpenCode bundle 构建 + manifest 生成
scripts/check-opencode-bundles.mjs  bundle/manifest/导入隔离检查

分层原则：protocol.ts 零 Herdr IO；herdr.ts 只做 Herdr 控制面调用（execFile argv 数组，无 shell）；pi-wait-guard.ts / opencode.ts / mcp.ts 各自只做 Runtime 接线。OpenCode 与 MCP 的 activation 是内存中的 session 局部状态：不持久化、不跨 session 恢复。

范围与非目标

Herdr Link 是同一 workspace 内的互操作层，不是业务调度器或任务管理系统。它只提供调用方明确选择的 configured/explicit Agent start execution primitive；不负责业务角色选择、Agent 调度/回收、模型选择、workflow/task/stage 状态、业务结果 schema/evidence/receipt/review、ACK/wait/poll/retry/pending-request 语义或可靠投递保证、持久队列或跨 session 状态、跨机器传输、权限审批、跨 workspace 的 discovery/send/close（属于官方 Herdr Skill / CLI 控制面），或 workspace/topology 管理。Link 只按每次 start 声明的 placement 机械创建（新 tab，或 with anchor 旁的 sibling pane），绝不规划或重塑既有 topology。业务 payload 放入 message 字段；Link 不解释其语义。完整范围以 PROTOCOL.md §9 为准。

许可证

MIT