查询类CLI

查询类 CLI

定位:只读取数——把自然语言查询翻译成对固定 API 端点的调用,再把 JSON 整理成人话。能查什么由端点和参数固化。对应风险等级 R0(纯读)。

📎 案例参考:实战 A sql-query-api · Stripe CLI customers list/find · GitHub gh pr list · kubectl get。规范基线见 设计指南/CLI设计/CLI设计规范。

---

何时用

• ✅ 取一条确定的数据:某房号交易、某项目台账、某条记录
• ✅ 查询维度收敛、相对固定,端点能枚举覆盖
• ✅ 后端已有稳定 REST API,不想暴露 SQL/宽表
• ❌ 要任意维度聚合 / Top-N / 下钻归因 → 用 设计指南/CLI设计/分析类CLI

命令形态:资源 + 动作(业界共识)

现代 API CLI 普遍用 resource-action 模式(Stripe / gh / kubectl 一致),AI 一学就会迁移:

CLI	查询命令	关键参数
Stripe	stripe customers list / find ID	--limit · cursor 分页
GitHub	gh pr list / gh api ...	--state · --json
kubectl	kubectl get pods	-o json · --selector
实战 A	query.py ledger	--project · --keyword · --sale-status {小订/认购/签约} · --limit 1-200

要点:一个子命令对应一个端点;枚举参数防 AI 乱传。

关键设计点

1. 端点固化:能查什么由端点+参数决定;新维度 = 改代码 + 重启 + 发版(这是 API 模式的天花板,要心里有数)。
2. 枚举校验:销售状态/合同类别这类用 enum 限定,模型传错直接 400 + hint。
3. 分页:--limit/--offset 或 cursor;给默认上限(实战 A 默认 50,上限 200)。
4. 只读 SELECT:参数走占位符,杜绝注入。
5. 不做 mock 兜底:DB/后端不可用直接 503,绝不编造数据——如实告知「当前 API 不支持/连不上」。
6. 先探活再查:health → query,把环境错和业务错分开(评测与改进/失败分析与治理 L6)。

输出协议

stdout 纯 JSON(顶层 source/count/filters_applied/elapsed_ms/rows),stderr 走进度;错误结构化 {ok:false,error_code,hint}。详见 设计指南/CLI设计/CLI设计规范 输出协议节。

案例:用户问题 → CLI

查询类的转换特征:自然语言里只有”一个对象 + 几个固定筛选”,落成一个子命令打一个端点。模型只填业务参数,不拼 SQL。

▸ 「信宏城一期有哪些已经签约的房子?」

sql-query ledger --project 信宏城一期 --sale-status 签约 --limit 50

销售状态是 enum(小订/认购/签约),模型传「已售」这种会 400 + hint;--limit 默认 50、上限 200。

▸ 「查一下张伟这个客户的认购记录」

sql-query ledger --keyword 张伟 --sale-status 认购

--keyword 走占位符防注入;一个端点对应一个动作,客户名是筛选不是新维度。

▸ 「3 号楼 1801 那套的成交价是多少?」

sql-query ledger --project 深圳湾一号 --keyword "3-1801" --limit 1

取一条确定数据;价格是端点固化返回的字段,不需要新增维度。

▸ 「列出最近创建的 10 个客户」(resource-action 通用范式)

stripe customers list --limit 10        # gh pr list / kubectl get pods 同理

现代 API CLI 一致用 资源 动作,AI 一学就会迁移。

▸ 反例:「这个项目一共卖了多少套?」→ 别硬塞查询类 这是 COUNT(*) 聚合,不该给查询端点加 --group-by / --count 开关(参数爆炸的开始)。 → 升级到 设计指南/CLI设计/分析类CLI 的 aggregate。这条边界就是查询类与分析类的分界线。

坏味道

• 端点想「什么都能查」→ 参数爆炸,退化成 API wrapper
• 该聚合的问题硬塞进查询端点(加 group_by 开关)→ 不如直接上 DSL
• 后端挂了返回空数组而非 503 → 模型误以为「查到 0 条」

一句话

查询类 CLI 胜在稳定、口径固定、好审计;代价是灵活性低,新维度要改代码。需要灵活多维就升级到 设计指南/CLI设计/分析类CLI。