TS TypeSafe 文档中文版
原文 ↗

快速开始

更想直接上手？这里有你立刻开始所需的一切。

试一试：Playground

  1. 打开 Playground 并登录。
  2. 粘贴任意文本作为状态。
示例状态
Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.
  1. 添加一个问题。 试试 Noul 问题："Does this message express urgency?"
json
{
  "urgency": {
    "type": "noul",
    "instructions": "Does this message express urgency?"
  }
}
  1. 添加更多问题。 在一次调用中混合使用 Noul、Choice 和 Score，并一次性查看所有结果。

调用它：API

  1. 从控制台获取你的 API 密钥
  2. 向 API 端点发送 POST 请求
  3. 查阅 API 参考 了解全部细节。
http
POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

示例 cURL 命令

bash
curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
  {
    "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
    "model": "jev-latest",
    "questions": {
      "urgency": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }
EOF

请求体

json
{
  "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

响应体

json
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "sales": 0.0,
        "billing": 0.15
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": {
        "0": 0.0,
        "1": 1.0,
        "2": 0.0
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 1.0
    }
  },
  "usage": {
    "input_tokens": 392,
    "output_tokens": 65
  }
}

查看 API 参考 了解全部细节。

编写代码：Python SDK

  1. 安装 SDK（需要 Python >= 3.10）。
使用 pip
pip install typesafe-sdk
使用 uv
uv add typesafe-sdk
  1. 使用 SDK。 客户端会从环境变量中读取 TYPESAFE_API_KEY，并默认调用 jev-latest。
python
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
 
client = TypeSafeClient()
 
ticket = "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP."
 
response = client.system_one(
    state=ticket,
    questions={
        "department": Choice(
            instructions="Which team should handle this",
            criteria={
                "billing": "Payment or subscription issues",
                "technical": "Bugs or integration problems",
                "sales": "Pricing or account questions",
            },
        ),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=[
                "Calm, just stating facts",
                "Frustrated but civil",
                "Very angry, strong language",
            ],
        ),
        "is_urgent": Noul(
            instructions="The message conveys urgency or time-sensitivity",
        ),
    },
)
 
print(response.answers["department"].choice)  # "technical"
print(response.answers["frustration"].score)  # 1.0
print(response.answers["is_urgent"].noul)     # 1.0

安装选项与详细用法见客户端 SDK。

凭感觉用它：agent skill

  1. 安装 TypeSafe skill：使用 Claude Code 插件或 npx skills add typesafe-ai/skills --skill typesafe-ai。你也可以在 GitHub 上阅读 SKILL.md。

在你的终端中运行这两条命令：

bash
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai
bash
npx skills add typesafe-ai/skills --skill typesafe-ai

出现提示时选择你的 agent。默认安装到当前项目；加上 -g 可全局安装。

把这段提示词粘贴到你的编码 agent 中：

plaintext
Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.
  1. 在构建过程中告诉你的编码 agent 使用 TypeSafe skill！
编码 agent 提示词
Let's build a simple CLI that uses the TypeSafe API to evaluate a set of supplied documents on multiple dimensions. Use the TypeSafe skill to understand how to use the TypeSafe API and how to structure the system. Ask me questions about what kinds of documents I want to evaluate and on what dimensions.

更多细节见 Agent Skill 页面。