Herdr事件钩子插件完全指南如何监听 worktree.created 等运行时事件【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr如果你正在用Herdr管理多个 coding agent一定遇到过这种场景worktree 刚创建完你就希望自动跑初始化脚本agent 一进入 blocked 状态就希望立刻收到通知。Herdr 的事件钩子插件Event Hooks正是为此设计的——在herdr-plugin.toml里声明一个[[events]]钩子当运行时发出worktree.created、pane.agent_detected等事件时Herdr 会自动执行你指定的命令全程无需轮询、无需写轮询循环。事件钩子是什么为什么需要它Herdr 是 coding agents 的运行时它接管终端窗口让 Claude Code、Codex、Cursor 等 agent 在各自的 pane 里并行工作。除了管理窗口Herdr 还会把运行时状态变化广播为结构化事件。事件钩子插件让你在事件发生的瞬间做出反应worktree.created→ 新 worktree 创建后自动git初始化pane.agent_status_changed→ agent 被阻塞时推送通知workspace.closed→ 会话关闭时归档日志核心优势声明式。钩子写在 manifest 里由 Herdr 统一触发、注入环境变量、记录日志你只写命令本身。30 秒上手声明你的第一个事件钩子一个 Herdr 插件就是一个包含 herdr-plugin.toml 的目录。事件钩子用[[events]]表声明完整示例见官方插件文档 plugins.mdxid example.layout name Layout version 0.1.0 min_herdr_version 0.7.0 platforms [linux, macos, windows] [[events]] on worktree.created command [herdr, workspace, list]on指定监听的事件名command是普通 argv 数组不经过 shell 解释。插件安装或链接后只要对应事件发生钩子就会自动运行。链接本地插件进行测试herdr plugin link /path/to/my-plugin可监听哪些运行时事件Herdr 允许插件钩子引用约 20 种事件定义在 events.rs 的PLUGIN_HOOK_EVENT_KINDS中按领域分为五组领域事件名典型用途️ 工作区workspace.created/workspace.updated/workspace.closed/workspace.renamed/workspace.moved/workspace.reordered/workspace.focused自动备份、布局恢复、日志归档 Worktreeworktree.created/worktree.opened/worktree.removed初始化脚本、同步依赖、清理临时目录 标签页tab.created/tab.closed/tab.focused/tab.renamed/tab.moved状态同步、提示词注入 窗格pane.created/pane.closed/pane.focused/pane.moved/pane.exited进程生命周期监控 Agentpane.agent_detected/pane.agent_status_changed通知、自动补 prompt、状态看板源码中还有刻意保留未开放的语义高频率的输出变化类钩子如pane.output_matched订阅暂未开放给插件 manifest以避免高频事件冲击。事件订阅协议的完整定义见 events.rs。钩子运行时能获得什么环境变量钩子命令启动时工作目录就是插件目录且 Herdr 会注入一批开箱即用的环境变量见 runtime.rs变量含义HERDR_PLUGIN_EVENT当前事件名如worktree.createdHERDR_PLUGIN_EVENT_JSON事件完整载荷 JSON钩子专属含事件详情HERDR_BIN_PATH正在运行的 Herdr 二进制路径跨平台回调用它最稳HERDR_SOCKET_PATHsocket 地址需要发原始 JSON 请求时使用HERDR_PLUGIN_CONTEXT_JSON调用上下文workspace / tab / pane / worktree / agent 等 idHERDR_PLUGIN_CONFIG_DIR/HERDR_PLUGIN_STATE_DIR插件专属配置与状态目录最佳实践用HERDR_BIN_PATH回调 CLI而不是硬编码herdr——这样插件在 Unix socket 和 Windows named pipe 下都能正常工作。需要持久化状态时写在HERDR_PLUGIN_STATE_DIR下别写进插件安装目录。事件钩子 vs events.subscribe怎么选两者都基于同一套事件流但适用场景不同插件事件钩子声明在 manifest 里随事件自动触发适合事件 → 执行一条命令的固定响应逻辑。socket API 的events.subscribe/events.wait长连接订阅原始事件流适合自定义工具、需要复杂判断逻辑的订阅者方法清单见 socket-api.mdx。一个典型组合钩子捕获worktree.created脚本里通过$HERDR_BIN_PATH调用 CLI 完成后续编排再读取HERDR_PLUGIN_EVENT_JSON拿到精确的事件上下文。安装、调试与注意事项herdr plugin list # 查看已注册插件 herdr plugin log list --plugin example.layout # 查看钩子运行日志 herdr plugin action invoke example.layout.apply # 手动触发 action 调试几个容易踩的坑min_herdr_version要如实填写——版本低于要求时安装/链接会直接拒绝。command是 argv 数组不经过 shell——需要 shell 特性时自己包一层sh -c。钩子失败不会拖垮 Herdr——启动与事件钩子异步执行日志可查但要注意排查。插件就是普通代码以你的用户权限运行、可调用完整 CLI。安装第三方插件前先看一眼 manifest 和脚本内容herdr plugin install交互模式下会先预览。相关资料插件开发完整文档plugins.mdxSocket API 与事件订阅socket-api.mdx事件协议定义events.rsmanifest 解析实现manifest.rs钩子触发运行时runtime.rs完整协议 JSON Schemaherdr-api.schema.json从worktree.created的一条声明开始你就能把 Herdr 的运行时事件变成自动化工作流的触发器——这正是runtime your coding agents live on 的延伸意义。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考