Briefing · Product Boundary

01 / 19

Lathe 产品定位与竞品边界对齐

Lathe 现在从 CLI-first 应用初始化一路覆盖到可验证执行；核心承诺仍是 spec 驱动、可复现、对 agent 可检查。

Audience维护者 · 贡献者 · 产品对齐会

Date2026-07-21

Scope定位 · init / Skill 入口 · 技术结构 · capabilities · 品类边界 · 准入

Thesis

02 / 19

核心主张

Lathe 是 spec-to-agent-toolchain 生成器，不是通用 CLI 框架，也不是手写 SDK 的替代品。

Product promise

Agent 不应猜测

命令名、flags、auth 状态、body 形状、HTTP path、输出格式，都必须能从生成物的机器可读契约里读出来，而不是靠模型猜。

Source of truth

钉住的输入，不是手写树

耐久输入是 specs/sources.yaml、cli.yaml、pinned upstream refs、optional overlays。生成代码是输出，不是权威。

成功标准不是「命令更多」，而是：人与 agent 都能先发现、再检查、再执行——且结果可从同一组钉住输入复现。

Diagnosis

03 / 19

常见品类错位

边界漂移通常不是缺功能，而是把相邻品类的职责误塞进 Lathe。

Misread A

当成通用 CLI 框架

期待手写命令、运行时插件、任意业务逻辑挂载。权重会离开 spec fidelity，变成第二个 Cobra 脚手架。

Misread B

当成 SDK / client 生成器

OpenAPI Generator、gRPC stub 解决的是库语言绑定。Lathe 交付的是可执行、可搜索、可检查的 CLI 表面。

Misread C

当成 API 网关或代理

网关管流量、策略、路由。Lathe 不终结请求链；它生成下游二进制去调用已有 API。

Misread D

当成运行时插件平台

远程扩展、动态 use:、第三方 codegen hook 会破坏可复现与安全边界。扩展应在生成期选中并静态编译进 CLI。

Product Surface

04 / 19

当前产品面：从创建到可验证执行

新增的是进入路径，不是边界改写：lathe init 与 Lathe Skill 把同一条 spec-first 工作流交给人和 agent。

1

Guide

lathe skill install

产品工作流

2

Create

lathe init

node · go · python · rust

3

Declare

openapi.yaml

cli.yaml

4

Generate

bootstrap

CLI + Skill

5

Prove

__lathe verify

inspect → execute

Implemented · PR #96

安全初始化，而非复制目录

internal/projectinit 校验声明式 .lathe-template.yaml，记录模板 commit，在临时同级目录 bootstrap，验证无 commit / 无 staged / 无 remote，再原子移动到目标。

Two Skill owners

构建指导与执行指导分开

internal/latheskill 是 Lathe 自身静态 Skill，指导创建和维护应用；skills/<cli>/ 是生成 Skill，指导检查和执行具体下游 CLI。

lathe init 不是通用项目脚手架：无 hook、无在线 registry、无远程创建、无 commit / stage / push。

Section

05 / 19

Technical structure

技术结构

产品边界由包图、IR 与一等 capabilities 强制执行。以下七页对齐真实流水线与能力面。

Model

06 / 19

两阶段与包边界

codegen-time 与 runtime 共享 CommandSpec 类型，但运行在不同二进制、不同时机。

01

Declare

sources.yaml

cli.yaml

02

Sync

specsync

pin → cache

03

Codegen

parse → normalize

overlay → render

04

Seam

*_gen.go

literals only

05

Runtime

build · HTTP

catalog · format

Codegen-time · internal/

cmd/lathe → lathecmd 编排。sourceconfig / specsync / backends/* / rawir / normalize / overlay / codegen/app / render。可读规格与 .cache。

Runtime · pkg/

pkg/runtime（CommandSpec、Build、HTTP、Formatter）、pkg/config（Manifest / Hosts）、pkg/lathe（Run / NewApp）、internal/auth。禁止 import internal/codegen/**。

硬约束：runtime 不得再读 raw specs、overlays 或 sync cache；overlay 概念在合并进 CommandSpec 后消失。

Pipeline

07 / 19

Codegen 流水线

四后端扇入同一 raw IR；normalize 投影为 runner 最小声明；render 是纯模板发射。

A

Load

sourceconfig

Git pin / local_path

B

Sync

specsync

sync-state.yaml

C

Parse

backend → RawModule

D

Normalize

[]CommandSpec

E

Assemble

overlay → app.App

validate names

F

Emit

render + gofmt

modules · workflow · Skill

Determinism

可复现优先

Git 源用 pinned_tag 解析到 commit；normalize 做 method-ordering；生成物不应手改。

Generated app

先组合、校验，再写出

internal/codegen/app.App 汇总 modules、workflows 与 Skill，先拒绝 root command 冲突，再统一渲染；它是内部模型，不是公开扩展 ABI。

Skill

引导 ≠ 权威

默认写 skills/<cli>/；可 skill.bundle 打进二进制。执行仍以 catalog 为准。

Backends

08 / 19

多后端 → 同一 RawOperation

到达 normalize.Normalize 时，来源后端已无关；差异只在 parse 阶段消化。

Concern	Swagger 2	OpenAPI 3	Proto	GraphQL
Grouping	first tag	first tag	service	graphql.groups
Operation ID	operationId	operationId	rpc	source + field
Path / method	operation	operation	google.api.http	POST /graphql
Body	requestBody	requestBody + $ref	input message	{query, variables}
Response	first 2xx	first 2xx	output message	selection + policy

Proto 仅带 google.api.http 的 RPC 成为操作；GraphQL 是 curated control-plane 路径，不是任意公开 GraphQL 的默认承诺。

IR

09 / 19

双 IR：为什么必须两个

rawir 保后端细节；CommandSpec 只留 runner 需要的声明。

rawir.RawModule

Normalization 输入

schemas、refs、per-response shape。支撑 list-path 检测、默认列选择、语义投影。留在 internal/codegen。

runtime.CommandSpec

Runtime 输入

命令路径、HTTP、flags、body 构建、auth 需求、输出提示。以 Go 字面量编进下游 CLI；catalog 由此导出。

Seam file

internal/generated/<mod>/<mod>_gen.go

模块级 []CommandSpec + 顶层 modules_gen.go。

Package graph

pkg/runtime 不得 import internal/codegen/**。边界靠依赖方向，不只靠文档。

Anti-pattern

在 runtime 重新解析规格、或把 overlay 字段泄漏进 catalog JSON，都会撕开可复现缝。

Runtime

10 / 19

Runtime 表面（下游 CLI 实际拥有什么）

生成后的二进制共享同一 runner；差异来自编译进去的 CommandSpec，而不是动态加载。

Discovery

Catalog 族

search、commands --json、commands show、commands schema。暴露 path、method、flags、auth、body、output formats。

Auth

Hostname-keyed

auth login / logout / status；凭据在 Hosts；可走 oauth device 等 cli.yaml 配置。执行前按 auth.required 预检。

Request

Body + HTTP

--file / --set / --set-str；enum 校验；retry；分页与 streaming hints。HTTP client 在 pkg/runtime。

Output

Formatter registry

-o table|json|yaml|raw。Agent 默认偏好 json；错误走 LatheError 等结构化路径，避免把秘密打进 debug。

安全敏感面：SSRF / 不安全 TLS、header 与 token 泄漏、响应错误泄漏、specsync 路径穿越、模板注入。改 HTTP 或 auth 必须当作产品行为证明。

Capabilities

11 / 19

生成 CLI 一等能力：workflow · skill.bundle · verify

写进 catalog.cli.capabilities 的是编译进二进制的能力开关，不是营销清单。

workflow.dsl

Workflow

在 cli.yaml 声明线性 API 步骤，编译成普通 Cobra 命令。夹在「生成 op」与「手写 Go」之间；catalog kind=workflow。

v0：无 rollback / if-else / shell / dry-run。失败停在第一步错误，返回 WorkflowError。

skill.bundle

Skill bundle

skill.bundle: true 时 codegen 挂 kitup，二进制携带 Skill，暴露 <cli> skill install。无需下游手写 embed 桥。

Skill 仍是引导；执行权威仍是 catalog。

__lathe verify

Self-evidence

<cli> __lathe verify --json：root help、catalog schema/round-trip、flags、孤立 auth status；有 bundle 时跑 skill_install；有 workflow 时跑 workflow_contract。

扩展默认姿态：capability switch + 静态链接（如 kitup）。Capability 命令本身不是 catalog operation；agent 用 capabilities[] 发现「装了什么」，用 catalog 发现「能调哪些 API」。

Contracts

12 / 19

Runtime UX 与版本化契约

产品兼容性靠版本字段与退出码，不靠「看 help 猜」。

Versioned contracts

双 schema

runtime.SchemaVersion：生成字面量 ↔ runner 挂载契约，不匹配启动失败。catalog_schema_version：discovery JSON 形状。改字段语义 = 产品行为。

Catalog vs framework

谁进目录

只有生成 API / workflow 命令进 catalog。auth、search、commands、skill、update、__lathe 走 --help，不进 ops 列表。

Operation UX

Pagination · streaming · LRO

cursor / body-cursor、--all、--max-pages；SSE 等 streaming hints；202 + Location 轮询 hints。写在 catalog output.*，richapi 是证明面。

Auth · errors · naming

可脚本化默认

oauth device + hostname-keyed Hosts + validate。LatheError 退出码 0/1/2/3/4（ok / general / usage / api / not_authenticated）。command_path：auto / namespaced。

Overlay 可批量填 defaults.pagination 等空默认，但不创造参数、不覆盖上游已有默认；命令级 override 最后胜出。

Matrix

13 / 19

相邻品类对照

不是「谁更强」，而是「谁该拥有哪一层职责」。

品类	典型产物	Agent 契约	与 Lathe
CLI 框架 Cobra / urfave	手写命令树	无内建 catalog	下游运行时底座；不是竞品主战场
SDK / stub 生成 oapi-codegen 等	语言库 / client	库 API，非 CLI 发现环	相邻；解决不同交付物
手写 API CLI	定制二进制	可有可无	漂移成本高；Lathe 的替代对象
API Gateway / MCP 服务	在线协议面	协议侧工具	不同部署模型；可并列，不合并
Lathe	可检查的 Cobra CLI + Skill	search → show → auth → exec	本产品定义所在

Boundary

14 / 19

In scope / Out of scope

贡献与产品决策用同一把尺子：是否强化 spec 保真、可复现、可检查性。

In scope · strengthen

+多后端规格保真：Swagger 2 / OpenAPI 3 / protobuf google.api.http / curated GraphQL
+运行时 catalog、search、commands show/schema 兼容性
+auth / body / output / retry·debug 行为正确且不泄密
+overlay 润色；Skill 质量；skill.bundle / kitup 安装面
+workflow DSL（线性 API 组合）与 __lathe verify 自证
+lathe init 与 Lathe Skill：把 starter 收敛进同一 CLI-first contract

Out of scope · challenge

−新规格格式堆叠（超出既定后端）作为核心默认
−运行时插件加载器、远程动态扩展
−GUI / TUI 作为主产品面
−workflow 当通用编排引擎（rollback / 分支 / shell）
−通用项目脚手架、模板 hook / registry、远程仓库生命周期

Out-of-scope 能力可做 sibling 项目，挂在生成 CLI 之上，而不是把 Lathe 核心做成平台 ABI。

Contract

15 / 19

Agent 契约：发现环

生成 Skill 是引导与索引；runtime catalog 才是执行权威。

1

search

"<intent>" --json

仅候选，禁止直执

2

commands show

<path...> --json

精确契约

3

auth status

--hostname

当 required

4

execute

已知后执行

-o json

Surface	Agent 用法	兼容敏感点
search	意图 → 候选命令列表	评分可调；不得当作执行说明书
commands show	单命令 flags / body / HTTP / auth	字段增删需 schema 意识
commands schema	catalog 版本与形状自检	跨版本消费者依赖

触碰 pkg/runtime/catalog.go、pkg/lathe/catalog.go、pkg/runtime/build.go、internal/codegen/render/skill.go = 产品行为变更。

Checklist

16 / 19

需求准入：这是不是 Lathe 的活？

评审提案时按序回答；任一「否」应触发重新框定或 sibling 方案。

01 规格可钉住吗？ 变更能否回溯到 pinned input（或明确的 local working-tree 源），而不是一次性手改生成物？
02 runtime 仍独立吗？ 是否避免让执行路径依赖 raw spec、overlay 概念或 sync cache？
03 agent 可检查吗？ 新行为是否出现在 catalog / show / schema，或明确声明为非契约表面？
04 权重落在哪？ 是强化初始化入口、生成正确性与契约，还是在堆通用脚手架 / 手写命令 / 插件机制 / 非 CLI 面？
05 安全边界清楚吗？ SSRF、凭据、token 泄漏、路径穿越、不可信规格进模板——是否有对应约束？

对齐后的工作口径

本 briefing 的产出是共享语言，不是排期板。

Describe

对外一句话

从钉住的 API 规格生成人类能用、agent 能安全检查的 Cobra CLI。

Review

PR / Issue 话术

先问「是否强化发现环与可复现」；把插件/GUI/新规格默认值标为越界或 sibling。

Extend

扩展默认姿态

生成期能力开关 + 静态链接；不做公开插件 ABI，直到安全与兼容协议就绪。

□README / CONTRIBUTING 的 out-of-scope 表述与本页矩阵保持一致
□新提案默认走准入清单 01–05，再进入设计细节
□extension 讨论继续用「capability switch」，避免「plugin marketplace」叙事

Appendix

18 / 19

术语表

Term	Meaning in Lathe
RawModule / rawir	后端无关原始 IR；承载 schema/ref/response，供 normalize 决策。
CommandSpec	编译进下游 CLI 的声明式命令契约；runtime 与 catalog 的输入。
catalog	机器可读命令目录；agent 执行权威，优先于 Skill 文案。
overlay	codegen-time 润色；合并进 CommandSpec 后 runtime 不可见。
Generated Skill	skills/<cli>/ 下的 agent 引导与索引；描述具体生成 CLI，非执行权威。
Lathe Skill	internal/latheskill 中的产品自有静态 Skill；由 lathe skill install 安装，指导创建和维护 CLI-first 应用。
lathe init	从受约束 starter 创建本地 CLI-first 仓库的窄入口；模板 commit 可审计，但默认 main 不是长期 pin。
specsync	按 sources 钉住或暂存规格，写 sync-state.yaml。
workflow.dsl	线性组合生成 API 操作的命令；catalog kind=workflow；非通用编排引擎。
skill.bundle	将 Skill 编入二进制并暴露 skill install（kitup）；capability，非 catalog op。
__lathe verify	生成 CLI 自证报告：catalog / auth / 可选 skill_install 与 workflow_contract。
extension / sibling	生成期静态能力 vs 核心外相邻项目；皆非运行时插件 ABI。

依据：当前代码、docs/architecture.md、docs/contracts.md、docs/workflow.md、docs/lathe-init-design.md、docs/lathe-extension.md、CLAUDE.md、README。

End

19 / 19

Lathe · Product Boundary Briefing