# herdr-link 中文文档

规范地址：https://npmcn.com/package/herdr-link/

版本：0\.7\.0
npm 元数据更新时间：2026-11-03T19:16:25.332Z
中文译文更新时间：2026-11-03T20:15:26.733Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/herdr-link
原文对照：https://npmcn.com/package/herdr-link/?lang=original
项目主页：https://github.com/LZHcode1986/herdr-link#readme
源码仓库：https://github.com/LZHcode1986/herdr-link

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：358 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.6\.0
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-coding-agent \*
- 首次发布：2026-08-25T12:51:34.104Z
- 最新版本发布：2026-11-03T19:16:24.965Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Herdr会话的链接-跨代理互操作层。OpenCode本地适配器+共享工作室MCP服务器的Pi / Claude Code / Codex / AGY。

## 安装

```sh
npm install herdr-link
```

也可以使用：`pnpm add herdr-link`、`yarn add herdr-link`、`bun add herdr-link`

## README

# Herdr Link

[![npm version](https://img.shields.io/npm/v/herdr-link.svg)](https://www.npmjs.com/package/herdr-link) [![CI](https://github.com/LZHcode1986/herdr-link/actions/workflows/ci.yml/badge.svg)](https://github.com/LZHcode1986/herdr-link/actions/workflows/ci.yml) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/herdr-link/LICENSE) [![node](https://img.shields.io/node/v/herdr-link.svg)](https://npmcn.com/package/herdr-link/package.json)

[English](https://npmcn.com/package/herdr-link/README.md) | **简体中文**

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`](https://npmcn.com/package/herdr-link/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 都呈现同样的惰性两级能力面：

```text
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 配置

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

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

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

```text
examples/agent_config.example.json
```

在目标项目中使用模板：

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

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

```json
{
  "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：

```bash
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`）：

```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` |

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

```bash
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）

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

```bash
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`](https://npmcn.com/package/herdr-link/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 中不提供任何 Herdr 工具：Pi 扩展只注册 wait guard，OpenCode 不注册工具，MCP 返回空工具集。Pi 仍可能显示已配置的 MCP server 元数据；
-   Herdr 环境 dormant 态下，模型侧只有 `herdr_link` gateway 可用（Codemode Host 通过 `searchTools()` 发现）；
-   **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 控制。

```bash
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、导入隔离
```

目录结构：

```text
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：ctx.tool.transform gateway、按 session 注入契约、会话级项目目录
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](https://npmcn.com/package/herdr-link/PROTOCOL.md#9-non-goals) 为准。

## 许可证

[MIT](https://npmcn.com/package/herdr-link/LICENSE)

## 常见问题

### herdr-link 是什么？

Herdr会话的链接-跨代理互操作层。OpenCode本地适配器\+共享工作室MCP服务器的Pi / Claude Code / Codex / AGY。

### 如何安装 herdr-link？

在项目目录运行 npm install herdr-link，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 herdr-link、herdr-link-opencode-install，可以用 npx herdr-link 直接运行。

### herdr-link 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/herdr-link 是否存在。

### herdr-link 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### herdr-link 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.6\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### herdr-link 可以商用吗？

herdr-link 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### herdr-link 还在维护吗？

最新版本 0\.7\.0 发布于 2026/11/04（今天）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/08/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。