CLI

CLI 命令行工具 (CLI)

English Version | 简体中文

---

代码仓库内置了一个轻量级命令行客户端 typesafe，完全基于 Go 标准库构建。 它封装了与 SDK 相同的核心能力：统一的配置解析、指数退避重试、强类型错误以及全特性的多模态问答。

---

安装

# 安装最新版本至 $(go env GOPATH)/bin
go install github.com/guchengod/typesafe-sdk-go/cmd/typesafe@latest

或者从 GitHub Releases 直接下载对应操作系统的预编译二进制文件（支持 Darwin/macOS、Linux、Windows 的 amd64 与 arm64 架构）。

设置 API Key 即可使用：

export TYPESAFE_API_KEY="ts_live_..."
typesafe version

---

命令列表

命令	作用
typesafe ask	针对特定 State 上下文发起命名问题评估（System One）
typesafe models	列出当前账号有权访问的模型列表
typesafe version	打印 CLI 版本及当前 Go 运行时信息
typesafe help	打印帮助信息与使用说明

---

全局连接参数

所有命令均支持以下连接参数，无论参数放置在子命令名称之前或之后均可解析：

参数	说明
--api-key string	API 密钥（默认取环境变量 $TYPESAFE_API_KEY）
--base-url string	API 根地址（默认取环境变量 $TYPESAFE_BASE_URL 或 https://api.typesafe.ai）
--timeout duration	单次网络请求超时时间（默认 10s）
--retries int	首次失败后的最大重试次数（默认 2）
--verbose	输出详细的网络请求与响应日志到 stderr

typesafe --api-key "$KEY" models
typesafe models --api-key "$KEY"     # 完全等价

---

评估命令: ask

typesafe ask --state <state> [--model <name>] [<questions>] [--format json|text] [--images] [--long-context]

1. 提供 State 上下文 (--state)

--state 指定评估的问题所依据的内容，支持以下形式：

形式	示例	说明
内联 JSON	--state '{"body": "我被重复扣费了。"}'	解析为 JSON 对象发送
普通字符串	--state "我被重复扣费了。"	作为纯文本发送
本地文件	--state @ticket.json	自动读取文件内容
标准输入	--state -	从标准输入流读取

2. 声明问题（可混合使用）

# 快捷提问参数（可多次重复传入）
--noul   'billing=这是账单问题吗？'
--choice 'queue=billing:财务账单,technical:技术故障,other'
--score  'urgency=日常,紧急,严重'
--box    'target=定位图片中的目标物体'

# 或通过 JSON 字典整体传入（支持内联、@文件或从标准输入读取）
--questions '{"billing": {"type": "noul", "instructions": "这是账单问题吗？"}}'
--questions @questions.json
--questions -

• --choice 选项格式为 label 或 label:描述，无描述的标签将传递为 null。
• --box 用于指定目标物体的定位指令。
• 同一个问题名称在一次请求中只能被声明一次。

3. 危险区功能标头参数

参数	说明
--images	附带 x-typesafe-images: true 标头，开启多模态图像与 Box 目标定位支持
--long-context	附带 x-typesafe-long-context: true 标头，开启超长上下文评估窗口 (262k)

4. 示例

通过管道读取工单并配合 jq 进行过滤：

cat ticket.txt | typesafe ask --state - --noul 'spam=是否为垃圾营销？' | jq '.answers.spam.noul'

评估多个问题并以易读的文本格式输出：

typesafe ask \
  --state @ticket.json \
  --model jev-preview \
  --images \
  --noul 'billing=这是账单问题吗？' \
  --choice 'queue=billing:财务,technical:技术,other' \
  --score 'urgency=普通,加急,特急' \
  --box 'badge=工单截图中的VIP徽章' \
  --format text

文本格式输出示例：

model    jev-1.13.0
usage    Usage{input_tokens: 367, output_tokens: 69}
billing  noul 0.9900
queue    choice billing (confidence 1.00)
urgency  score 0.53 of 2 (confidence 0.20)
badge    box [0.12, 0.45, 0.38, 0.82] (confidence 0.95)

---

模型命令: models

typesafe models                # 输出格式化 JSON
typesafe models --format text  # 输出表格

表格输出示例：

NAME         RELEASE                           DESCRIPTION
jev-latest   2026-09-10T18:38:01.391457+00:00  The latest iteration of TypeSafe's System One Model: Jev
jev-preview  2026-09-15T10:00:00.000000+00:00  Experimental multimodal and bounding box localization model

---

退出状态码 (Exit Codes)

CLI 严格遵循 Unix 命令行规范，提供语义化退出码以适配 CI/CD 自动化流水线：

退出码	含义
0	执行成功
1	参数调用错误或输入不合法，未向网络发起任何请求
2	服务端返回非 2xx 失败状态码（如 400、401、413、429 等）
3	网络连接失败、DNS 失败或超时，请求未成功抵达服务端

Shell 脚本示例：

if ! typesafe ask --state @ticket.json --noul 'spam=是否为垃圾邮件？' > answer.json; then
  case $? in
    2) echo "服务端拒绝了请求" >&2 ;;
    3) echo "无法连接到 TypeSafe API" >&2 ;;
    *) echo "命令行参数或输入有误" >&2 ;;
  esac
  exit 1
fi

---

调试与排错

添加 --verbose 参数可将请求与响应细节输出至 stderr（敏感凭据如 Authorization 会自动脱敏为 ***）：

typesafe ask --state @ticket.json --noul 'q=是否为垃圾邮件？' --verbose > answer.json