# 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)](./LICENSE)
[![node](https://img.shields.io/node/v/herdr-link.svg)](./package.json)

[English](./README.md) | **简体中文**

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`](./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")   # 最终 send 返回 sent 之后的工具步骤
```

- **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 配置

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

```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（原生扩展）

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

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

手动/开发加载：

```bash
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（单文件插件）

OpenCode 把插件目录里**每个文件**都当作 plugin 加载，因此必须部署预构建的单文件 bundle——绝不能平铺源文件：

```bash
npm install -g herdr-link    # 或源码构建：npm run build:opencode
cp "$(npm root -g)/herdr-link/dist/herdr-link.opencode.js" \
   ~/.config/opencode/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）。

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

没有原生自定义工具注册面的 Runtime 共用同一个 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`](./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 控制。

```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
npm run build:mcp           # dist/herdr-link.mcp.js
```

目录结构：

```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.ts                    Pi Runtime Adapter：gateway + deferred Tier 1（setActiveTools），激活后注入契约
src/opencode.ts              OpenCode Runtime Adapter：single-gateway dispatcher + 按 sessionID 契约注入
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 插件、MCP server bin）
scripts/mcp-probe.mjs        stdio 握手排障探针
```

分层原则：`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](./PROTOCOL.md#9-non-goals) 为准。

## 许可证

[MIT](./LICENSE)