Lathe 

在微服务与 API 驱动的开发时代，维护一套与上游规格同步的命令行工具（CLI）往往是团队的噩梦：手写代码容易漂移，文档更新滞后，而新兴的 AI Agent 更因缺乏结构化上下文而无法准确调用 API。Lathe 是一个基于 Go 的 API-to-CLI 生成器，旨在从 OpenAPI 3、Swagger 2.0 及 Protobuf 规格中，自动生成生产级、Agent 友好的 Cobra CLI。

Lathe 秉持 “Spec is Truth”（规格即真理）的设计原则，将 API 规格作为唯一事实来源。它生成的不仅是一个面向人类的工具，更是一个具备“自我描述”能力的智能接口，让 AI Agent 能够通过结构化契约精准发现、验证并执行命令，彻底告别猜测 Flag 与构造请求体的混乱。

核心亮点：自动化、Agent 友好、结构化契约

1. 专为 AI Agent 设计的交互范式

Lathe 生成的 CLI 内置了一套标准的 Search-Show-Execute 工作流，确保 Agent 调用的准确性：

• 意图搜索 (search)：Agent 通过自然语言意图（如 “create user”）查找候选命令，获取结构化 JSON 列表。
• 命令预览 (commands show)：在执行前，Agent 可获取命令的精确形态，包括必填 Flag、请求体结构、认证要求及 HTTP 方法。
• 认证预检 (auth status)：若命令需要认证，Agent 可先检查登录状态，避免无效请求。
• 结构化输出：默认优先使用 -o json，便于 Agent 解析结果，而非难以处理的人类表格。

2. 内置 Skill 目录，无缝集成 Agent 生态

• 自动生成 Skill：Codegen 阶段自动创建 skills/<cli-name>/ 目录，包含 SKILL.md、OpenAI 配置及模块参考文档。
• 快速上手指南：Skill 文档指导 Agent 如何发现命令、读取 Catalog、处理认证及构造 Body，大幅降低 Agent 的学习成本。
• 运行时 Catalog：CLI 内部嵌入完整的命令目录 JSON，Agent 可随时查询最新能力，无需依赖外部文档。

3. 多后端支持，保持规格同步

• 广泛兼容：支持 Swagger 2.0、OpenAPI 3 以及带 google.api.http 注解的 Protobuf 服务。
• 版本锁定：通过 specs/sources.yaml 锁定上游 Git 仓库的 Tag 或 Commit SHA，确保生成过程的可复现性。
• 自动同步：API 变更时，只需更新锁定的 Tag 并重新生成，CLI 即刻同步，杜绝人工维护导致的漂移。

4. 灵活定制与增强

• Overlay 机制：无需修改上游 API 规格或生成的 Go 代码，即可通过 YAML 文件补充命令摘要、别名、参数帮助信息及示例。
• 统一运行时：所有生成模块共享同一套认证管理、请求构造、分页处理、流式响应及错误处理逻辑，保证体验一致性。
• 单二进制文件：最终产物为独立的 Go 二进制文件，易于分发、安装及自动化部署。

快速开始

1. 初始化项目

基于 github.com/samzong/lathe 创建仓库，并配置两个核心文件：

cli.yaml (定义 CLI 身份)

cli:
  name: acmectl
  short: "Command-line tool for Acme services"

auth:
  validate:
    method: GET
    path: /api/v1/whoami
    display:
      username_field: data.username
      fallback_field: data.email

specs/sources.yaml (锁定 API 来源)

sources:
  iam:
    repo_url: https://github.com/acme/iam.git
    pinned_tag: v1.4.0
    backend: swagger
    swagger:
      files:
        - api/openapi/user.swagger.json
  # 支持 openapi3 和 proto 后端...

2. 生成与构建

make bootstrap  # 同步规格并运行 Codegen
go build -o bin/acmectl ./cmd/acmectl

3. 使用 CLI

人类用户：

./bin/acmectl auth login --hostname api.acme.com
./bin/acmectl iam users create-user \
  --set email=alice@example.com \
  --set role=viewer \
  -o json

AI Agent 执行流程：

1. 搜索：./bin/acmectl search "create user" --json
2. 预览：./bin/acmectl commands show iam users create-user --json
3. 鉴权：若 auth.required=true，执行 ./bin/acmectl auth status --hostname api.acme.com
4. 执行：确认参数后执行命令，优先使用 -o json 输出。

高级配置：Overlay 润色

若需优化帮助文案或添加示例，创建 internal/overlay/iam.yaml：

commands:
  create-user:
    short: "Create a user in the IAM service"
    aliases: [adduser]
    example: |
      acmectl iam create-user \
        --set email=alice@example.com \
        --set role=viewer
    params:
      role:
        help: "User role (viewer, editor, admin)"
        default: viewer

运行 Codegen 时指定 Overlay 目录：

go run ./cmd/codegen -overlay internal/overlay

Lathe 不仅仅是一个代码生成工具，它是连接 API 规格、人类开发者与 AI Agent 的桥梁。在 LLM 重塑软件交互的今天，Lathe 通过结构化、可机器读取的 CLI 表面，让 API 调用变得更加确定、高效且智能。