Herdr 插件与 Socket API 完全指南HERDR_BIN_PATH 可移植性技巧【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrHerdr 是编程智能体的终端运行时the runtime your coding agents live on本文讲 Herdr 插件与 Socket API 中HERDR_BIN_PATH的可移植性技巧让你的插件在 Linux、macOS 与 Windows 上行为一致。Herdr 把 Claude Code、Codex、Cursor 等 CLI 智能体装进可持久化的终端工作区关闭客户端或断开 SSH 后服务器仍在后台运行重启后还能恢复布局与智能体会话。为什么需要 HERDR_BIN_PATH先搞懂传输差异 Herdr 的 Socket API 跑在本地 socket 上但两个平台的形态不一样UnixLinux/macOSUnix 域 socket默认路径~/.config/herdr/herdr.sock命名会话在sessions/name/下各有独立 socketWindows命名管道named pipe。两者都由HERDR_SOCKET_PATH暴露但原始 socket 传输是操作系统相关的——你的脚本如果直接连原始 socket就得为两个平台各写一套连接逻辑。而HERDR_BIN_PATH指向当前正在运行的 Herdr 二进制本身。通过它调用 Herdr CLIworkspace list、pane read、agent wait等CLI 内部会替你消化平台差异插件代码保持完全可移植。官方文档的结论很直接plugins.mdx#L249-L254当插件需要从 Node、PowerShell、Bash 或其他运行时可移植地调用 Herdr 时使用HERDR_BIN_PATH。Herdr 插件运行时环境变量速查表 插件命令启动时以插件目录为工作目录Herdr 会注入一组上下文变量详见 plugins.mdx变量作用HERDR_BIN_PATH运行中 Herdr 二进制的路径可移植回调首选HERDR_SOCKET_PATH原始 socket 路径/管道仅用于底层直连HERDR_ENV1标记运行在 Herdr 内部Herdr 外的脚本应跳过上报HERDR_PLUGIN_ID/HERDR_PLUGIN_ROOT插件身份与其安装目录HERDR_PLUGIN_CONFIG_DIR/HERDR_PLUGIN_STATE_DIR用户可编辑配置 / 运行时状态目录HERDR_PLUGIN_CONTEXT_JSON工作区、标签页、窗格、智能体等完整调用上下文HERDR_WORKSPACE_ID/HERDR_TAB_ID/HERDR_PANE_ID可用时的层级 id⚠️ 容易踩的坑这些是Herdr 管理的权威变量。你在启动命令上用--env覆盖同名变量会失败——与调用方提供的环境变量冲突时Herdr 注入的值保持权威见 cli-reference.mdx#L464。第一个插件HERDR_BIN_PATH 回调的最小写法 Herdr 没有受限 SDK——整个 Herdr CLI 就是插件 API。清单声明一个动作入口里带兜底地回调 Herdr[[actions]] id list-workspaces title List workspaces contexts [workspace] command [node, index.js]const herdr process.env.HERDR_BIN_PATH ?? herdr; // 用 herdr 执行 workspace list、pane read 等任意 CLI 命令在 Herdr 内部运行时HERDR_BIN_PATH保证调用的是当前会话的二进制在 Herdr 外部手动调试时?? herdr兜底走PATH。清单用platforms [linux, macos, windows]声明支持的平台Herdr 校验清单、注入上下文、启动命令并记录日志——宿主侧的脏活全由 Herdr 完成。Socket API什么时候才需要下沉原始请求 Herdr 控制面分三层选择原则是能用上层就不下沉层适合场景智能体技能教编程智能体在窗格内使用 HerdrCLI 包装配合HERDR_BIN_PATHShell 脚本、插件、简单编排——可移植性最佳原始 socket API自定义协议客户端、长期事件订阅原始 socket 使用换行分隔的 JSON每个请求一行{id:req_1,method:ping,params:{}}成功响应与请求共享id事件订阅events.subscribe会保持连接打开并持续推送事件。方法覆盖 workspace、tab、pane、agent、worktree、events、plugin 等领域完整清单与请求结构见 socket-api.mdx协议 schema 可随时用herdr api schema --json打印机器可读。 官方对可移植性的建议socket-api.mdx#L516-L518对插件来说需要可移植的 Windows 行为时优先调用HERDR_BIN_PATH和 CLI 包装命令。原始 socket 客户端要自己负责使用平台原生的本地 socket 形式。实战可移植的智能体状态上报 智能体运行在 Herdr 窗格内时会自动继承HERDR_ENV、HERDR_PANE_ID、HERDR_BIN_PATH和HERDR_SOCKET_PATH。可移植的上报写法Unix shell 示例$HERDR_BIN_PATH pane report-agent $HERDR_PANE_ID \ --source custom:my-agent \ --agent my-agent \ --state working仅在HERDR_ENV1且必要变量存在时才上报集成在 Herdr 外会保持安静--source保持稳定且唯一智能体退出时用pane release-agent释放生命周期权威需要直接 IPC 时可发送等价的pane.report_agent、pane.release_agentsocket 请求。完整说明与各家智能体的官方集成见 integrations.mdx#L71-L86。HERDR_BIN_PATH 可移植性 5 大技巧 ✅永远优先 CLI 回调插件与钩子里调用 Herdr 一律走$HERDR_BIN_PATH ...把 Unix socket 与命名管道的差异交给 CLI。脚本里加裸命令兜底process.env.HERDR_BIN_PATH ?? herdrHerdr 内外都能运行方便本地调试。Windows 用%HERDR_BIN_PATH%语法自定义命令在 Windows 上经cmd.exe /d /c执行环境变量用%VAR%形式需要 PowerShell 语法时显式调用powershell.exe -NoProfile -Command ...见 configuration.mdx#L232-L234。别试图覆盖受管变量HERDR_SOCKET_PATH、HERDR_BIN_PATH等与调用方冲突时保持权威强行覆盖无效。状态与配置分开放用户配置放HERDR_PLUGIN_CONFIG_DIR运行时状态放HERDR_PLUGIN_STATE_DIRHERDR_PLUGIN_ROOT在 GitHub 安装时是托管源码检出不要放持久数据。总结选对集成层跨平台零成本 写插件、写智能体钩子 →HERDR_BIN_PATH CLI 包装跨平台开箱即用写自定义协议客户端、需要长期事件流 → 原始Socket API并自行处理平台原生 socket 形式深入阅读plugins.mdx、socket-api.mdx、integrations.mdx、cli-reference.mdx。掌握HERDR_BIN_PATH你就拿到了 Herdr 插件与 Socket API 体系里最顺手的那把跨平台钥匙 。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Herdr 插件与 Socket API 完全指南：HERDR_BIN_PATH 可移植性技巧
Herdr 插件与 Socket API 完全指南HERDR_BIN_PATH 可移植性技巧【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrHerdr 是编程智能体的终端运行时the runtime your coding agents live on本文讲 Herdr 插件与 Socket API 中HERDR_BIN_PATH的可移植性技巧让你的插件在 Linux、macOS 与 Windows 上行为一致。Herdr 把 Claude Code、Codex、Cursor 等 CLI 智能体装进可持久化的终端工作区关闭客户端或断开 SSH 后服务器仍在后台运行重启后还能恢复布局与智能体会话。为什么需要 HERDR_BIN_PATH先搞懂传输差异 Herdr 的 Socket API 跑在本地 socket 上但两个平台的形态不一样UnixLinux/macOSUnix 域 socket默认路径~/.config/herdr/herdr.sock命名会话在sessions/name/下各有独立 socketWindows命名管道named pipe。两者都由HERDR_SOCKET_PATH暴露但原始 socket 传输是操作系统相关的——你的脚本如果直接连原始 socket就得为两个平台各写一套连接逻辑。而HERDR_BIN_PATH指向当前正在运行的 Herdr 二进制本身。通过它调用 Herdr CLIworkspace list、pane read、agent wait等CLI 内部会替你消化平台差异插件代码保持完全可移植。官方文档的结论很直接plugins.mdx#L249-L254当插件需要从 Node、PowerShell、Bash 或其他运行时可移植地调用 Herdr 时使用HERDR_BIN_PATH。Herdr 插件运行时环境变量速查表 插件命令启动时以插件目录为工作目录Herdr 会注入一组上下文变量详见 plugins.mdx变量作用HERDR_BIN_PATH运行中 Herdr 二进制的路径可移植回调首选HERDR_SOCKET_PATH原始 socket 路径/管道仅用于底层直连HERDR_ENV1标记运行在 Herdr 内部Herdr 外的脚本应跳过上报HERDR_PLUGIN_ID/HERDR_PLUGIN_ROOT插件身份与其安装目录HERDR_PLUGIN_CONFIG_DIR/HERDR_PLUGIN_STATE_DIR用户可编辑配置 / 运行时状态目录HERDR_PLUGIN_CONTEXT_JSON工作区、标签页、窗格、智能体等完整调用上下文HERDR_WORKSPACE_ID/HERDR_TAB_ID/HERDR_PANE_ID可用时的层级 id⚠️ 容易踩的坑这些是Herdr 管理的权威变量。你在启动命令上用--env覆盖同名变量会失败——与调用方提供的环境变量冲突时Herdr 注入的值保持权威见 cli-reference.mdx#L464。第一个插件HERDR_BIN_PATH 回调的最小写法 Herdr 没有受限 SDK——整个 Herdr CLI 就是插件 API。清单声明一个动作入口里带兜底地回调 Herdr[[actions]] id list-workspaces title List workspaces contexts [workspace] command [node, index.js]const herdr process.env.HERDR_BIN_PATH ?? herdr; // 用 herdr 执行 workspace list、pane read 等任意 CLI 命令在 Herdr 内部运行时HERDR_BIN_PATH保证调用的是当前会话的二进制在 Herdr 外部手动调试时?? herdr兜底走PATH。清单用platforms [linux, macos, windows]声明支持的平台Herdr 校验清单、注入上下文、启动命令并记录日志——宿主侧的脏活全由 Herdr 完成。Socket API什么时候才需要下沉原始请求 Herdr 控制面分三层选择原则是能用上层就不下沉层适合场景智能体技能教编程智能体在窗格内使用 HerdrCLI 包装配合HERDR_BIN_PATHShell 脚本、插件、简单编排——可移植性最佳原始 socket API自定义协议客户端、长期事件订阅原始 socket 使用换行分隔的 JSON每个请求一行{id:req_1,method:ping,params:{}}成功响应与请求共享id事件订阅events.subscribe会保持连接打开并持续推送事件。方法覆盖 workspace、tab、pane、agent、worktree、events、plugin 等领域完整清单与请求结构见 socket-api.mdx协议 schema 可随时用herdr api schema --json打印机器可读。 官方对可移植性的建议socket-api.mdx#L516-L518对插件来说需要可移植的 Windows 行为时优先调用HERDR_BIN_PATH和 CLI 包装命令。原始 socket 客户端要自己负责使用平台原生的本地 socket 形式。实战可移植的智能体状态上报 智能体运行在 Herdr 窗格内时会自动继承HERDR_ENV、HERDR_PANE_ID、HERDR_BIN_PATH和HERDR_SOCKET_PATH。可移植的上报写法Unix shell 示例$HERDR_BIN_PATH pane report-agent $HERDR_PANE_ID \ --source custom:my-agent \ --agent my-agent \ --state working仅在HERDR_ENV1且必要变量存在时才上报集成在 Herdr 外会保持安静--source保持稳定且唯一智能体退出时用pane release-agent释放生命周期权威需要直接 IPC 时可发送等价的pane.report_agent、pane.release_agentsocket 请求。完整说明与各家智能体的官方集成见 integrations.mdx#L71-L86。HERDR_BIN_PATH 可移植性 5 大技巧 ✅永远优先 CLI 回调插件与钩子里调用 Herdr 一律走$HERDR_BIN_PATH ...把 Unix socket 与命名管道的差异交给 CLI。脚本里加裸命令兜底process.env.HERDR_BIN_PATH ?? herdrHerdr 内外都能运行方便本地调试。Windows 用%HERDR_BIN_PATH%语法自定义命令在 Windows 上经cmd.exe /d /c执行环境变量用%VAR%形式需要 PowerShell 语法时显式调用powershell.exe -NoProfile -Command ...见 configuration.mdx#L232-L234。别试图覆盖受管变量HERDR_SOCKET_PATH、HERDR_BIN_PATH等与调用方冲突时保持权威强行覆盖无效。状态与配置分开放用户配置放HERDR_PLUGIN_CONFIG_DIR运行时状态放HERDR_PLUGIN_STATE_DIRHERDR_PLUGIN_ROOT在 GitHub 安装时是托管源码检出不要放持久数据。总结选对集成层跨平台零成本 写插件、写智能体钩子 →HERDR_BIN_PATH CLI 包装跨平台开箱即用写自定义协议客户端、需要长期事件流 → 原始Socket API并自行处理平台原生 socket 形式深入阅读plugins.mdx、socket-api.mdx、integrations.mdx、cli-reference.mdx。掌握HERDR_BIN_PATH你就拿到了 Herdr 插件与 Socket API 体系里最顺手的那把跨平台钥匙 。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考