Herdr插件开发完全教程：写你的第一个herdr-plugin.toml

Herdr插件开发完全教程写你的第一个herdr-plugin.toml【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrHerdr 插件是运行在 Herdr 里的可分享工作流包一个包含 herdr-plugin.toml 清单文件的目录加上 Herdr 能启动的命令。本教程带你从零写出第一个 Herdr 插件完成从 manifest 编写、本地 link 调试到发布到插件市场的完整流程全文只涉及少量清单代码适合零插件经验的新手。为什么需要 Herdr 插件Herdr 是编码 Agent 的运行时——Claude Code、Codex、Cursor、Grok 等 Agent 的终端都住在它里面。官方刻意保持核心精简把可复用工作流交给插件生态Herdr 负责宿主面插件安装、清单校验、按键绑定、终端面板、事件回调、socket 访问插件负责实现语言、依赖、文件、持久化状态都由你自己决定。换句话说没有独立的插件 SDK整个 Herdr CLI 就是插件 API。你的插件可以用 Bash、Node、Python、Rust 写只要系统能执行这条命令即可。30 秒认识 herdr-plugin.toml 清单结构清单是 Herdr 与插件之间的合同声明元数据、平台、构建命令和入口点。最小可用清单长这样参考仓库中的 plugin-smoke 示例id example.workspace-tools name Workspace Tools version 0.1.0 min_herdr_version 0.7.0 description Small workspace helpers platforms [linux, macos, windows] [[actions]] id list-workspaces title List workspaces contexts [workspace] command [node, index.js]字段必填说明id✅插件唯一标识可用字母、数字、点、冒号、下划线、连字符name✅展示名称version✅语义化版本号min_herdr_version✅插件能运行的最低 Herdr 版本版本不匹配时 Herdr 会拒绝安装description⬜插件用途说明platforms⬜顶层平台列表各条目也可单独声明并覆盖顶层清单里还能声明 5 类钩子按需使用区块作用[[build]]安装期构建命令如[npm, run, build]失败则安装中止[[startup]]会话恢复后自动执行一次的初始化命令如恢复插件私有状态[[actions]]可被调用、可绑快捷键的操作入口[[events]]事件钩子如on worktree.created时自动运行命令[[panes]]声明一个插件终端面板支持 overlay / popup / split / tab 等摆放方式⚠️ 注意command是 argv 数组Herdr 不会经过 shell 执行所以不存在 shell 变量展开。第一步创建你的插件目录新建一个目录放入清单和一个可执行脚本即可my-plugin/ herdr-plugin.toml index.js在index.js里回调 Herdr 时请优先使用环境变量HERDR_BIN_PATH指向正在运行的 Herdr 二进制这样插件在 Unix socket 和 Windows 命名管道之间都能正常工作const { spawnSync } require(node:child_process); const herdr process.env.HERDR_BIN_PATH ?? herdr; const result spawnSync(herdr, [workspace, list], { encoding: utf8 }); process.stdout.write(result.stdout);第二步link 本地插件并验证开发阶段用link把工作目录注册进 Herdr无需服务器运行也能注册herdr plugin link /path/to/my-plugin herdr plugin action list --plugin example.workspace-tools herdr plugin action invoke example.workspace-tools.list-workspaces常用配套命令herdr plugin config-dir example.workspace-tools打印插件配置目录.env等用户可编辑配置放这里herdr plugin log list --plugin id查看命令执行日志herdr plugin unlink id注销插件但保留文件方便反复调试。插件运行时能拿到什么Herdr 启动插件命令时会注入一组环境变量理解它们是写好插件的关键环境变量用途HERDR_BIN_PATH调用 Herdr CLI 的可移植入口最常用HERDR_SOCKET_PATH原始 socket API 连接跨平台行为不同一般走 CLI 即可HERDR_PLUGIN_ID/HERDR_PLUGIN_ROOT插件 id 与插件目录不要在这里存凭据或持久状态HERDR_PLUGIN_CONFIG_DIR/HERDR_PLUGIN_STATE_DIR用户配置与运行时的持久状态目录Herdr 自动创建HERDR_PLUGIN_CONTEXT_JSON调用上下文workspace、tab、焦点面板、worktree、agent、选中文本、点击的 URL 等HERDR_WORKSPACE_ID/HERDR_TAB_ID/HERDR_PANE_ID当前上下文的常用 id可用时注入进阶快捷键绑定与事件钩子给插件操作绑一个快捷键在用户配置里加[[keys.command]] key prefixl type plugin_action command example.workspace-tools.list-workspaces description list workspaces事件钩子则让插件跟着 Herdr 走比如新 worktree 创建时自动执行一段命令[[events]] on worktree.created command [herdr, workspace, list]插件面板还支持placement popup弹出模态终端窗可配置width/height非常适合做选择器这类瞬态 UI完整字段见官方 plugins 文档。发布到插件市场社区插件市场是一个自动索引把herdr-plugin.toml放在公开仓库默认分支的根目录或子目录中并给仓库打上herdr-plugin主题标签索引每 30 分钟刷新一次用户即可通过herdr plugin install owner/repo[/subdir]一键安装。发布前建议写好description和min_herdr_version解析失败会被排除在市场之外用--ref支持固定版本方便用户 pin 到可信的修订版。安全提醒插件就是运行在你机器上的普通代码以你的用户身份执行并能调用完整 Herdr CLI。安装或 link 任何插件前花一分钟读一遍它的 manifest 和脚本交互式终端下herdr plugin install会先展示来源和将执行命令的预览。总结阶段你做了什么理解清单是合同CLI 即插件 API编写一个目录 herdr-plugin.toml 可执行脚本调试plugin link→action invoke→log list深化利用环境变量、快捷键、事件钩子、插件面板发布公开仓库 herdr-plugin标签市场自动收录现在就可以动手了复制 tests/fixtures/plugin-smoke/herdr-plugin.toml 这个最简清单改个 idlink 进来跑一次action invoke你就写出了第一个 Herdr 插件。更多细节参考 plugins 官方文档 与 marketplace 文档。【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考