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 等代理装进可持久化的终端窗格里并对外开放了三层 APIAgent 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_ENV1环境中运行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走本地 socketUnix 域套接字 / 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_ENV1不成立就停止用 raw socket 做简单查询先用 CLI简单就是可维护凭侧边栏顺序猜窗格 ID从 JSON 响应的.result字段解析等待命令不设超时--timeout显式给值避免脚本挂死选型结论skill 管AI 会用CLI 管脚本能跑raw socket 管协议级控制。大多数团队只需要前两层第三层留给真正的事件驱动场景——这也是 Herdr 能把10 个代理、3 个客户端这种复杂协作收敛得如此干净的原因。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考