# @brooswit/herdr-sdk 中文文档

规范地址：https://npmcn.com/package/%40brooswit/herdr-sdk/

版本：1\.0\.0
npm 元数据更新时间：2026-10-17T15:50:46.691Z
中文译文更新时间：2026-11-08T16:04:42.677Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：495 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-24T14:25:19.963Z
- 最新版本发布：2026-10-17T15:50:46.208Z
- 近 30 天下载量：3523（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

用于 herdr socket API 的 TypeScript 客户端, 由 herdr 发布的 JSON Schema 生成

## 安装

```sh
npm install @brooswit/herdr-sdk
```

也可以使用：`pnpm add @brooswit/herdr-sdk`、`yarn add @brooswit/herdr-sdk`、`bun add @brooswit/herdr-sdk`

## README

# @brooswit/herdr-sdk (英语)

输入的脚本客户端 [医生](https://herdr.dev/) 套接字 API , 由 schema herdr 本身所生成 `herdr api schema --json`) (中文(简体) ).

```ts
import { HerdrClient } from "@brooswit/herdr-sdk";

const h = new HerdrClient();                       // herdr's own default config dir, or $HERDR_SOCKET_PATH
const { snapshot } = await h.session.snapshot();  // fully typed
await h.agent.wait({ target: "w1:p3", until: ["idle"], timeout_ms: 30_000 });

const sub = await h.subscribe([{ type: "pane.agent_status_changed", pane_id: "w1:p3" }]);
for await (const frame of sub) console.log(frame.event, frame.data);
```

## 层

| 目录 | 任务 |
| --- | --- |
| `src/transport` | unix socket QQ新线限定框架 。 没有JSON 没有协议. |
| `src/protocol` | 信封形状, `HerdrError`,编号。 没有I/O. |
| `src/client` | 一个请求 —— 一个回应 —— 服务器关闭(即herdr的电线行为) . |
| `src/events` | `events.subscribe`:长生相接者,作同心行者. |
| `src/services` | 每个方法家族一个文件; 细打字外观. |
| `src/reducers` | 纯:快照+推放帧 → 当前舰队状态. |
| `src/generated` | 代码输出 . **不编辑**; 运行 `bun run generate`。 。 。 . |
| `scripts/gen` | 生成器,每个输出一个文件. |

## 套接字地址

-   **首字母顺序 :** `HERDR_SOCKET_PATH` (herdr自己公布)胜出; `HERDR_SOCKET` 仅被誉为堕落的后退 `HERDR_SOCKET_PATH` 未设定。 偏爱 `HERDR_SOCKET_PATH` 在新代码.
-   **默认路径**,当两者都没有设定时,镜像herdr自己的配置目录分辨率: `XDG_CONFIG_HOME` 如果设置; 否则在 Windows 上 `%APPDATA%`,则 `%USERPROFILE%\AppData\Roaming`,则 `$HOME/.config`,然后是临时目录;否则(POSIX) `$HOME/.config`,然后是临时目录——与 `herdr/herdr.sock` (或 `herdr-dev/herdr.sock` 与 `{ dev: true }`,或 `.../sessions/<name>/herdr.sock` 与 `{ sessionName }`) (中文(简体) ).
-   **每个操作系统地址:** 在 Linux/ macOS 上,上面的路径是一个真实的 Unix- domain 套接字, 使用不变 。 在 Windows 上, herdr 在命名的管子上听 `\\.\pipe\<path>` 相反——路径本身只有前缀,否则就永远不会被重写. 这个 SDK 自动从 `process.platform`· ; `socketEndpoint()` (从 `src/transport/socket-path.ts`直接需要时进行衍生.
-   **Dev 构建/ 命名会话 :** 通过 `{ dev: true }` 指向一个 `herdr-dev` 构造的配置目录, 或 `{ sessionName }` 连接到指定的会话套接字,例如 . `new HerdrClient({ dev: true, sessionName: "work" })`也从未在运行时猜测过.

## 这是建立在电线上的事实(Herdr 0.8.2, 议定书20)

-   请求 `{id, method, params}` → `{id, result:{type,…}}` 或者说 `{id, error:{code,message}}`。 。 。 .
-   服务器 **一个答复后关闭**。每个RPC都是自己的连接.
-   `events.subscribe` 鸡巴 `subscription_started` 然后保持连接打开,流出 `{event, data}` 边框.
-   超时为打出错误( T)`code: "timeout"`从不挂起. `isTimeout(e)`。 。 。 .
-   计划没有说明每种方法的返回结果; `scripts/gen/method-result-map.ts` 有,而且 `test/live` 证明这一点.

## 脚本

```
bun run generate     # schema → src/generated
bun run check        # generate + drift guard + typecheck + unit  (what CI runs)
bun run build
HERDR_LIVE=1 bun test test/live   # against your running herdr
```

## 常见问题

### @brooswit/herdr-sdk 是什么？

用于 herdr socket API 的 TypeScript 客户端, 由 herdr 发布的 JSON Schema 生成

### 如何安装 @brooswit/herdr-sdk？

在项目目录运行 npm install @brooswit/herdr-sdk，或使用 pnpm add / yarn add / bun add。

### @brooswit/herdr-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @brooswit/herdr-sdk 支持 ESM 还是 CommonJS？

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

### @brooswit/herdr-sdk 可以商用吗？

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

### @brooswit/herdr-sdk 的下载量有多少？

根据 npm 官方下载统计，@brooswit/herdr-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,523 次，日均约 117 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @brooswit/herdr-sdk 还在维护吗？

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