【免费下载链接】octo-cliMetadata-driven CLI for AI Agent Bots — 48 operations across 7 domains, structured JSON envelope I/O, zero interactive prompts.项目地址https://gitcode.com/gh_mirrors/oct/octo-cli点击查看免费下载octo-cli 是面向 AI Agent Bot 的元数据驱动命令行工具覆盖 7 大域共 48 个操作。在 octo-cli 中新增一个 API 端点不需要写一行 Go 代码——只需在internal/registry/specs/下的 OpenAPI 3.1 规范里补一段 JSONCLI 命令、参数校验、分页行为就会全部自动生成。本文完整演示这套只改规范、不改代码的扩展流程。一、元数据驱动架构为什么加端点不用写Go代码octo-cli 的核心理念是规范即代码。启动时内嵌在二进制里的 OpenAPI 规范被解析并自动注册为命令树internal/registry/specs/*.json OpenAPI 3.x 规范编译期内嵌 │ ▼ internal/registry (Registry) 解析规范按 operationId 暴露操作元数据 │ ▼ cmd/service (Service Engine) 每个操作自动注册一条 cobra 命令 │ ▼ internal/cmdutil (Factory, DI) 按命令装配配置 凭据 客户端 │ ▼ internal/client (HTTP client) 路由、重试、dry-run │ ▼ internal/output (envelope) 稳定的 JSON 信封输出整个链路的关键只有一行 Go 代码——internal/registry/loader.go 中的//go:embed specs/*.json它让specs/目录下的每一个JSON 文件在重新编译时自动打进二进制。而 cmd/service/service.go 中的RegisterServiceCommands会为规范里的每个操作生成一条命令标志位flags、必填参数、风险门控全部由元数据推导。换句话说你唯一需要编辑的文件就是那个 JSON。二、开发环境准备克隆、构建与验证三件套开始之前需要 Go 1.24 和make。完整说明见 CONTRIBUTING.md。git clone https://gitcode.com/gh_mirrors/oct/octo-cli cd octo-cli make build # 构建出 ./bin/octo-cli make test # go test -race -count1 ./... make ci # fmt vet lint test build与 CI 完全一致⚡ 小贴士make ci就是 CI 会跑的完整检查集本地跑绿了再提交可以省掉远程反复排错的等待。三、核心步骤3步在OpenAPI规范中新增端点3.1 第一步定位目标规范文件规范按**域domain**组织一域一文件全部位于 internal/registry/specs/ 目录域规范文件覆盖内容eventevent.json事件轮询、ACKgroupgroup.json群组读写messagemessage.json消息收发与搜索botbot.jsonBot 注册与元数据建议以最小的 event.json 作为模板——它只有 2 个操作、80 行出头是学习规范结构的最短路径。 如果是全新域直接新建internal/registry/specs/domain.json即可//go:embed会自动收录无需注册。官方文档见 CONTRIBUTING.md。3.2 第二步编写 OpenAPI 操作片段以在event域新增一个查询事件统计端点为例在 event.json 的paths对象里加入/v1/bot/events/{event_id}/stats: { get: { operationId: event.stats, summary: Get delivery stats for an event, x-octo-risk: read, parameters: [ { name: event_id, in: path, required: true, schema: { type: integer } } ], responses: { 200: { description: Stats, content: { application/json: { schema: { type: object, properties: { event_id: { type: integer }, seen_count: { type: integer } } } } } } } } }这段 JSON 就是全部工作量。命名和字段如何映射到命令规则如下operationIddomain.verb映射为octo-cli domain verbdomain.resource.verb映射为octo-cli domain resource verb如message.search.all。所以event.stats生成命令octo-cli event statspath 参数→ 位置参数octo-cli event stats 123query 参数→ 类型化 flag请求体顶层字段→ 自动提升为 flag复杂嵌套结构仍可用--data传入x-octo-riskread/write风险标记3.3 第三步重新构建并离线验证规范内嵌在二进制里所以每次改动后必须重新构建然后全部离线验证规范内嵌schema命令不需要联网make build # 重新编译embed 收录新片段 bin/octo-cli schema --list # 确认 event.stats 出现在操作清单 bin/octo-cli schema event.stats # 检查请求/响应 schema 是否符合预期 bin/octo-cli event stats 123 --dry-run # 预览最终请求不实际发送 make test # 全量测试含规范加载与去重校验✅ 看到--dry-run打印出正确的 URL 和请求体新端点就成功上线了。四、x-octo扩展字段速查让规范承载更多行为标准 OpenAPI 字段之外octo-cli 用一批x-octo-*扩展字段声明传输行为。这些字段在 internal/registry/loader.go 中被解析为操作元数据扩展字段位置作用x-octo-service文件顶层服务域名决定顶层命令名x-octo-base-url文件顶层基础 URL 环境变量名统一为OCTO_API_BASE_URLx-octo-space-header文件顶层是否发送X-Space-Id头x-octo-risk操作级read/write风险标记x-octo-flag参数/体字段自定义 flag 名如channel_id→--chat-id见 message.jsonx-octo-secret参数/体字段敏感值在--verbose/--dry-run中脱敏x-octo-pagination操作级声明游标参数与响应字段解锁--page-all自动翻页见 message.jsonx-octo-multipart操作级标记 multipart 上传x-octo-binary-response操作级标记二进制响应配合-o落盘x-octo-enum-hintschema 级为枚举值错误提供提示文案x-octo-cli-hidden操作级隐藏命令但保留元数据x-octo-disabled文件顶层暂时下架整个域规范仍加载schema 可查比如想让列表接口支持--page-all只需声明分页映射x-octo-pagination: { cursorParam: cursor, cursorField: pagination.next_cursor, hasMoreField: pagination.has_more }五、常见坑点Registry 会在加载时抛出的错误规范错误不会静默——Registry 在启动阶段就会快速失败常见报错及原因错误信息原因解决registry: parse file: ...JSON 语法错误或类型不符用 JSON 校验工具先过一遍registry: duplicate operationId ...operationId全局重复loader.go 跨所有域查重换用唯一的domain.verb命名registry: duplicate service ...两个文件声明了同一个x-octo-service确保域名与文件名一一对应...malformed x-octo-required-unless-query条件必填声明格式错误参照 loader.go 中的校验规则修正⚠️ 另外注意如果端点需要 multipart、二进制响应等特殊处理官方建议扩展 registry/service 引擎而不是为单个域写专用代码路径见 CONTRIBUTING.md。六、提交前检查清单CI校验与提交规范提交 PR 前make ci必须全绿对应检查为gofmt、go vet、golangci-lint、go test -race、构建、go mod tidy。针对规范类改动再额外确认三点bin/octo-cli schema --list domain中新操作已出现且 summary 正确--dry-run输出的请求与后端契约逐字段一致行为变更附带测试——项目偏好表驱动测试用 Factory 桩RegistryFunc、ClientFunc等注入不碰真实网络internal/registry/ 下已有大量此类测试可参考提交信息遵循Conventional Commits例如feat: add event.stats endpoint。回顾一下定位域规范 → 补一段 OpenAPI JSON →make build→schema --list--dry-run验证。整个流程零 Go 代码这正是 octo-cli 元数据驱动设计的回报。深入架构细节可阅读 docs/architecture-design.md构建目标定义在 Makefile更多命令示例见 README.md。赞分享【免费下载链接】octo-cliMetadata-driven CLI for AI Agent Bots — 48 operations across 7 domains, structured JSON envelope I/O, zero interactive prompts.项目地址https://gitcode.com/gh_mirrors/oct/octo-cli点击查看免费下载相关推荐从OpenAPI规范到Go代码oapi-codegen自动化开发实战指南从OpenAPI规范到Go代码oapi codegen自动化开发实战指南 oapi codegen是一款强大的代码生成工具能够从OpenAPI 3规范自动生开发工具代码生成API设计Voxtype开发者指南如何在Rust代码中新增一个ASR语音转写后端Voxtype开发者指南如何在Rust代码中新增一个ASR语音转写后端 voxtype 是一款面向 Wayland 合成器的按键说话push to talk告别重复编码OpenAPI规范如何实现前后端代码自动生成告别重复编码OpenAPI规范如何实现前后端代码自动生成 你是否还在为API文档与代码不一致而头疼是否在手动编写API客户端和服务端代码时浪费大量时间本文API设计文档后端上一篇Jsonformer数据类型处理字符串、数字、布尔值的完美转换下一篇企业级Google Maps集成Client ID与签名验证完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考