Herdr API分层选择：skill、CLI、raw socket何时用哪个完整指南-育师

Herdr API分层选择：skill、CLI、raw socket何时用哪个完整指南

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr

🐑 Herdr 是一款面向 AI 编程代理的终端工作区管理器（the runtime your coding agents live on），它把 Claude Code、Codex、Cursor 等代理装进可持久化的终端窗格里，并对外开放了三层 API：Agent Skill、CLI 命令行和raw socket 原始套接字。三层共享同一套控制面，但抽象程度不同——选错层会导致自动化代码又长又脆。本文帮你用 3 分钟搞清楚：skill 何时用、CLI 何时用、raw socket 何时用。

一、先看懂 Herdr API 的三层结构

Herdr 把"控制能力"分成三层，从"教 AI 做事"到"直接发协议报文"逐级下沉：

层级	面向对象	典型场景
Agent Skill	正在 Herdr 内运行的编码代理	让 AI 自己拆分窗格、读日志、等另一个代理完成
CLI 包装命令	人和 Shell 脚本	写脚本编排、日常调试、快速查看状态
Raw Socket API	自研工具、协议客户端	长连接事件订阅、实时面板、自定义客户端

官方文档给了一句非常实用的原则（见 socket-api.mdx）：大多数自动化都应该从 CLI 包装命令开始，只有当你需要直接的请求/响应控制或长生命周期的事件订阅时，才下沉到 raw socket。

二、Agent Skill：何时用（让 AI 自己驱动 Herdr）

一句话定位：skill 不是给人用的 API，而是"教学文件"。它是一份 Markdown 指令，装进支持技能系统的编码代理后，AI 就会从 Herdr 窗格内部通过herdrCLI 正确地操作会话。

适合用 skill 的信号 🎯：

你希望 Claude Code、Codex 等代理在 Herdr 里"自己开窗格、跑测试、等兄弟代理"
你不想要 AI 反复试探命令语法，需要现成的最佳实践和安全规则
代理已经在HERDR_ENV=1环境中运行（skill 内置了这条护栏，不在 Herdr 内就拒绝操作）

skill 会教给 AI 这些协调动作：检查邻居状态、无抢占焦点地分屏、读取窗格输出、用agent wait等待另一个代理进入idle/blocked/done状态。完整规则就写在 skills/herdr/SKILL.md 里，安装好的二进制可以用herdr --skill直接打印与版本匹配的技能副本。

⚠️ 注意区分：仓库里的 website/agent-guide.md 是"教 AI 如何帮人类配置 Herdr"的指南，而 skill 是"教 AI 如何操作 Herdr"，两者用途不同。

三、CLI：脚本编排与调试的主力层

一句话定位：90% 的自动化需求，CLI 就够了。CLI 命令走的就是底层 socket，但帮你省掉了协议细节，且大多数控制命令返回JSON，方便脚本解析。

适合用 CLI 的信号 🎯：

Shell 脚本编排：拆分窗格 → 启动代理 → 等待完成 → 读取结果
人工调试：快速查看 workspace / tab / pane / agent 的实时状态
CI 集成：用退出码判断成败（服务器错误退出码 1，语法错误退出码 2）

# 无焦点抢占地分屏，再让新窗格跑测试 herdr pane split --current --direction right --cwd "$PWD" --no-focus herdr agent wait reviewer --until done --timeout 120000

两条黄金习惯：

从 JSON 响应里解析 ID（如.result.pane.pane_id），不要靠猜或按侧边栏顺序推导；
需要定位"自己所在的窗格"时优先用--current或环境变量$HERDR_PANE_ID，避免误操作别人聚焦的窗格。

完整命令手册见 cli-reference.mdx，编排套路见 agent-automation.mdx。

四、Raw Socket API：何时必须下沉到底层

一句话定位：需要长连接、事件流或自定义协议客户端时才用。Herdr 使用换行分隔的 JSON走本地 socket（Unix 域套接字 / Windows 命名管道），每个请求一行：

{"id":"req_1","method":"ping","params":{}}

适合用 raw socket 的信号 🎯：

事件订阅：events.subscribe打开一条长连接，持续接收pane.agent_status_changed、workspace.created等推送——这是 CLI 做不到的
一次请求完成提交+等待：agent.prompt可携带wait对象，提交提示词并启动等待在一个请求里原子完成，避免两次调用之间的竞态
自研客户端/UI：用session.snapshot做一次性引导快照 + 事件流增量更新，维护自己的本地状态缓存
插件与集成上报：hooks、插件通过pane.report_agent、pane.report_metadata上报代理状态和展示元数据

不用手写协议文档：herdr api schema --json会打印与当前二进制匹配的完整 JSON Schema（仓库内副本见 herdr-api.schema.json），工具链可以直接校验。命名会话各有独立 socket（~/.config/herdr/sessions/<name>/herdr.sock），跨会话操作先确认连对了 socket。

💡 记住降级顺序：先问自己"CLI 能不能表达？"能就别碰 raw socket——CLI 层还封装了跨平台差异，raw socket 客户端要自己处理平台原生的本地 socket 形式。

五、30 秒决策清单

按顺序问自己三个问题：

🤖 使用者是AI 代理且在 Herdr 窗格内？→ 装skill，让它走 CLI 最佳实践
📜 使用者是脚本或人，一次一问一答？→ 用CLI，解析 JSON 响应
🔌 需要长连接事件流、原子复合操作或自定义协议客户端？→ 上raw socket，先用herdr api schema --json导出协议再动手

六、常见误区速查

误区	正确做法
在 Herdr 外部强行控制 Herdr 会话	skill 的护栏：`HERDR_ENV=1`不成立就停止
用 raw socket 做简单查询	先用 CLI，简单就是可维护
凭侧边栏顺序猜窗格 ID	从 JSON 响应的`.result`字段解析
等待命令不设超时	`--timeout`显式给值，避免脚本挂死