Herdr Link

English | 简体中文

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

提供 Pi（原生扩展）、OpenCode（插件 bundle）以及任意支持 MCP 的 Runtime 如 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——无契约、无 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 可见；空参 {} 调用一次性激活当前 session（幂等、纯内存态）。
• Active 层：herdr_link_start、herdr_link_peers、herdr_link_send、herdr_link_close，外加紧凑 Communication Contract。每次通信调用都经 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（原生扩展）

pi install npm:herdr-link          # 全局（推荐）
pi install -l npm:herdr-link        # 仅当前项目

# 改用源码安装：
pi install git:github.com/LZHcode1986/herdr-link

手动/开发加载：

mkdir -p ~/.pi/agent/extensions/herdr-link
cp src/pi.ts ~/.pi/agent/extensions/herdr-link/index.ts
cp src/herdr.ts src/protocol.ts ~/.pi/agent/extensions/herdr-link/
# 或：pi --extension /path/to/herdr-link/src/pi.ts

安装后 Adapter 注册 herdr_link gateway 与四个 Tier 1 工具；每个 session 开始时 Tier 1 处于 inactive，模型调用 herdr_link {} 后启用并注入契约。

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，并通过 ctx.session.hook("context") 只向已激活会话注入通信契约；每次工具调用通过 ctx.session.get({sessionID}) 解析发起会话的项目目录，且只有当该目录在调用者 workspace 内唯一对应一个 live pane 时才继续，否则 fail closed。V1 入口保留，互不覆盖。

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

没有原生自定义工具注册面的 Runtime 共用同一个 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 分发保持全功能）。

环境要求

运行进程必须由 Herdr 在 managed pane 中启动：

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

• 非 Herdr managed pane 中所有 Adapter 均为完全 no-op：Pi/OpenCode 不注册任何工具，MCP 返回空工具集；
• Herdr 环境 dormant 态下，模型侧只有 herdr_link gateway 可见；
• Self identity bootstrap（PROTOCOL.md §6.3）：用户手动启动、已被 Herdr 识别但尚无合法 Agent Name 的 agent，会被自动赋一个生成的 hl-* 名字（Adapter 启动时执行一次 ensureSelfName()，通信路径内另有 fallback）。已有名字绝不改写、不持久化；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.ts                    Pi Runtime Adapter：gateway + deferred Tier 1（setActiveTools），激活后注入契约
src/opencode.ts              OpenCode Runtime Adapter：single-gateway dispatcher + 按 sessionID 契约注入
src/opencode-v2.ts           OpenCode 2 Runtime Adapter：ctx.tool.transform gateway、按 session 注入契约、会话级项目目录
src/mcp.ts                   共享 stdio MCP server：JSON-RPC、惰性工具列表、gateway dispatch
docs/mcp-wiring.md           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.ts / opencode.ts / mcp.ts 各自只做 Runtime 接线。activation 是各 Adapter 内存中的 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