Herdr API Schema 指南：一条命令导出 JSON Schema，把编码智能体接入你的工具链

Herdr API Schema 指南：一条命令导出 JSON Schema，把编码智能体接入你的工具链

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

Herdr 是一个让编码智能体（Coding Agent）"居住"其中的终端运行时，它把 Claude Code、Codex、Gemini CLI 等多个 AI 智能体放进各自的终端窗格统一管理与监控。更关键的是，Herdr 内置了Herdr API Schema：一条命令即可导出描述整个 Socket API 的 JSON Schema，让你在校验、文档生成和客户端开发中直接复用这份契约，把智能体工作流无缝接入自己的工具链。

先认识一下 Herdr：智能体的终端运行时

如果你习惯了"一个终端窗口跑一个 AI 助手"，Herdr 会把工作流升级成"一个面板管 N 个助手"：每个工作区、标签页、窗格都是一个独立会话，你还能看到每个智能体当前是空闲、工作中、被阻塞还是已完成。

除了可视化界面，Herdr 还暴露了一套本地 Socket API——所有界面能做的事（建工作区、切标签页、读窗格输出、等待智能体结束……）都可以通过请求-响应或事件订阅的方式程序化完成。而Herdr API Schema就是这套 API 的机器可读说明书。

三条命令拿到 Herdr 的 JSON Schema

Schema 已经内置在 Herdr 二进制里，安装后直接用 CLI 导出即可：

herdr api schema # 打印简短摘要（协议版本、包含的 schema 列表） herdr api schema --json # 打印完整的 JSON Schema 全文 herdr api schema --output herdr-api.schema.json # 写入文件，交给工具链使用

对应的实现非常直接：CLI 启动时就把 schema 文件打包进了程序，src/cli/api.rs 中的include_str!保证了"你导出的 schema 永远和你正在运行的二进制版本一致"。

Herdr API Schema 里到底有什么

导出的文件遵循 JSON Schema Draft 2020-12）：

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "protocol": 20, "schema_version": 1, "schemas": { "request": { "...": "所有原始请求的定义" }, "success_response": { "...": "成功响应" }, "error_response": { "...": "错误响应" }, "event": { "...": "服务器主动发出的事件" }, "subscription_event": { "...": "订阅推送的事件" } } }

其中request部分覆盖了全部控制面方法，按领域分组如下：

完整的方法清单和参数细节可以直接查阅官方文档 socket-api.mdx，中文版本见 zh-cn/socket-api.mdx。

三个真实工具链场景

场景一：请求校验。把 schema 交给ajv、check-jsonschema或 Pydantic，在脚本发出请求前先校验参数结构，把"拼错字段名"这类低级错误挡在门外。

场景二：AI 辅助开发客户端。把--json的输出直接喂给编码智能体，让它基于权威契约生成你所在语言的客户端代码，而不是靠猜。

场景三：事件驱动的编排。agent.wait会一直挂到智能体完成，配合events.subscribe可以实现"智能体 A 完成 → 自动把结果交给智能体 B"的流水线，而不需要轮询。

为什么这份 Schema 值得信任：单一事实来源

很多项目的 API 文档是手写的，容易和代码脱节。Herdr 的做法恰恰相反：

• 所有请求与响应类型定义在 src/api/schema.rs，通过 Rust 的schemars派生宏自动生成JSON Schema；
• schema 文件被声明为构建资源（见 Cargo.toml），随发布物一起分发；
• 升级 Herdr 后重新执行herdr api schema --output即可同步最新契约，protocol字段（当前为 20）帮助你识别协议代际。

也就是说，代码改了，schema 必然跟着改——这正是"导出 JSON Schema 给工具链"最让人安心的地方。

小结

只需一条命令，Herdr API Schema 就把"人读的文档"升级成了"机器可用的契约"。无论你想做 CI 契约测试、IDE 插件还是智能体编排流水线，这份 JSON Schema 都是最可靠的起点。

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