# 概览

<div className="docs-lead-note">
  <p className="font-medium">
    直接运行智能体，或使用你需要的基础能力
  </p>

  <p className="mt-2 text-sm leading-6">
    智能体服务封装模型调用、工具执行等能力，通过智能体 API 完成业务任务。需要直接控制模型、沙箱或搜索时，也可以独立使用对应服务。
  </p>
</div>

## 开始使用 [#开始使用]

<div className="mt-4 grid gap-6 md:grid-cols-3">
  <div>
    <p className="text-sm text-fd-muted-foreground">
      01
    </p>

    <p className="mt-1 font-medium">
      <a href="/docs/cloud">选择服务</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      运行智能体，或直接调用模型、沙箱与搜索。
    </p>
  </div>

  <div>
    <p className="text-sm text-fd-muted-foreground">
      02
    </p>

    <p className="mt-1 font-medium">
      <a href="/docs/cloud/get-started/concepts">创建云 Key</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      在 Praxis Cloud 控制台创建 API Key，了解鉴权方式与权限范围。
    </p>
  </div>

  <div>
    <p className="text-sm text-fd-muted-foreground">
      03
    </p>

    <p className="mt-1 font-medium">
      <a href="/docs/cloud">完成第一次调用</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      打开所选服务的快速开始，完成一个请求并查看结果。
    </p>
  </div>
</div>

## 选择你需要的服务 [#选择你需要的服务]

每项服务都有独立的快速开始、使用指南与 API。

<hr className="my-8 border-fd-border" />

### 智能体 [#智能体]

定义职责、提供资料并运行任务。由智能体服务管理底层能力调用。

<div className="mt-4 grid gap-6 sm:grid-cols-2">
  <div>
    <p className="font-medium">
      快速开始
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      创建并运行第一个智能体
    </p>
  </div>

  <div>
    <p className="font-medium">
      核心概念
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      智能体与运行
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      会话、记忆与协作
    </p>
  </div>

  <div>
    <p className="font-medium">
      使用指南
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      配置职责与能力
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      提供文件与资料
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      使用工具与组织协作
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      接入自己的应用
    </p>
  </div>

  <div>
    <p className="font-medium">
      技术参考
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/get-started/concepts">限制与错误处理</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      智能体 API
    </p>
  </div>
</div>

<hr className="my-8 border-fd-border" />

### 模型 [#模型]

通过统一接口调用模型，生成文本、处理多模态输入。

<div className="mt-4 grid gap-6 sm:grid-cols-2">
  <div>
    <p className="font-medium">
      快速开始
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/services/model/quickstart">发出第一个模型请求</a>
    </p>
  </div>

  <div>
    <p className="font-medium">
      核心概念
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/services/model/concepts/models-and-catalog">模型与供应商</a>
    </p>

    <p className="mt-1 text-sm">
      <a href="/docs/cloud/services/model/concepts/protocols">兼容协议与路由</a>
    </p>
  </div>

  <div>
    <p className="font-medium">
      接入与使用
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cookbook">接入第三方工具</a>
    </p>

    <p className="mt-1 text-sm">
      <a href="/docs/cloud/services/model/guides/streaming">流式响应</a>

      与

      <a href="/docs/cloud/services/model/guides/tool-calling">工具调用</a>
    </p>

    <p className="mt-1 text-sm">
      <a href="/docs/cloud/services/model/guides/structured-output">结构化输出</a>

      与

      <a href="/docs/cloud/services/model/guides/multimodal">多模态</a>
    </p>

    <p className="mt-1 text-sm">
      <a href="/docs/cloud/services/model/concepts/routing">路由与失败重试</a>
    </p>
  </div>

  <div>
    <p className="font-medium">
      技术参考
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/services/model/limits-and-errors">限制与错误处理</a>
    </p>

    <p className="mt-1 text-sm">
      <a href="/docs/api">模型 API →</a>
    </p>
  </div>
</div>

<hr className="my-8 border-fd-border" />

### 沙箱 [#沙箱]

在隔离环境中执行代码、操作文件和使用浏览器。

<div className="mt-4 grid gap-6 sm:grid-cols-2">
  <div>
    <p className="font-medium">
      快速开始
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      创建沙箱并执行一个任务
    </p>
  </div>

  <div>
    <p className="font-medium">
      核心概念
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      沙箱与生命周期
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      执行环境与资源
    </p>
  </div>

  <div>
    <p className="font-medium">
      使用指南
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      执行命令 · 管理文件
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      使用浏览器与网络
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      回收环境与处理失败
    </p>
  </div>

  <div>
    <p className="font-medium">
      技术参考
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/get-started/concepts">限制与错误处理</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      沙箱 API
    </p>
  </div>
</div>

<hr className="my-8 border-fd-border" />

### 搜索 [#搜索]

查询所需信息，获取搜索结果与来源。

<div className="mt-4 grid gap-6 sm:grid-cols-2">
  <div>
    <p className="font-medium">
      快速开始
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      完成第一次搜索
    </p>
  </div>

  <div>
    <p className="font-medium">
      核心概念
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      搜索范围与查询
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      结果、排序与来源
    </p>
  </div>

  <div>
    <p className="font-medium">
      使用指南
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      设置搜索条件
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      读取与筛选结果
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      在应用中使用搜索
    </p>
  </div>

  <div>
    <p className="font-medium">
      技术参考
    </p>

    <p className="mt-2 text-sm">
      <a href="/docs/cloud/get-started/concepts">限制与错误处理</a>
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      搜索 API
    </p>
  </div>
</div>

## 管理你的云服务 [#管理你的云服务]

<div className="mt-4 grid gap-6 sm:grid-cols-2">
  <div id="identity-permissions" className="scroll-mt-24">
    <p className="font-medium">
      <a href="/docs/cloud/get-started/concepts">身份与权限</a>
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      管理云 Key 与授权范围
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      保护服务访问凭证
    </p>
  </div>

  <div id="usage-billing" className="scroll-mt-24">
    <p className="font-medium">
      用量与费用
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      计量口径、用量查询
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      账单与费用管理
    </p>
  </div>

  <div id="quotas-limits" className="scroll-mt-24">
    <p className="font-medium">
      <a href="/docs/cloud/account/quotas">配额与限制</a>
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      查询服务配额
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      了解请求与资源限制
    </p>
  </div>

  <div id="observability-troubleshooting" className="scroll-mt-24">
    <p className="font-medium">
      观测与故障排查
    </p>

    <p className="mt-2 text-sm text-fd-muted-foreground">
      请求标识、日志与排错
    </p>

    <p className="mt-1 text-sm text-fd-muted-foreground">
      服务异常的定位路径
    </p>
  </div>
</div>

## API [#api]

智能体 / 模型 / 沙箱 / 搜索 —— 查阅请求参数、响应结构、错误码与代码示例。需要验证调用时，在当前页面展开调试面板，配置并发送请求。

<p className="mt-3">
  <a href="/docs/api">浏览所有 API →</a>
</p>

# 第一个请求

（待补充）

# 选择服务

（待补充）

# 核心概念

Core concepts

# 智能体

智能体服务封装模型调用、工具执行等能力：你定义职责、提供资料与文件、配置工具与协作，由智能体服务管理底层能力调用，通过智能体 API 完成业务任务。

## 与其他服务的关系 [#与其他服务的关系]

智能体建立在模型、沙箱、搜索等云能力之上；这些能力也向构建者独立开放，见[选择服务](/docs/cloud)。

## 出口 [#出口]

[API 参考 →](/docs/api/native/agent) · [Cookbook →](/docs/cookbook)

# 快速开始

（待补充）

# 嵌入到网页

本页带你把一个服务型智能体放进自己的网页，让登录用户直接在页面里和它对话。你需要一个 Praxis API Key、一个网站后端和一个前端页面。

本页用 Kit 组件完成接入。一行 iframe 和 Hosted 跳转的用法见[嵌入方式](/docs/cloud/services/agent/embed/methods)。所有示例使用 develop 环境。

## 工作方式 [#工作方式]

浏览器里的页面不持有 API Key。你的后端用 API Key 为当前登录用户签发一张短期令牌，前端的 Kit 组件拿这张令牌与智能体对话。

```text
浏览器 ──(你的登录态)──▶ 你的后端 ──(API Key)──▶ POST /agent/v1/embed_tokens
   ▲                                                      │
   └──────────── { id, token, expires_at } ◀──────────────┘
浏览器（Kit）──(token)──▶ Praxis API
```

## 1. 在控制台准备智能体 [#1-在控制台准备智能体]

1. 在 Console 新建一个**服务型智能体**，写好指令并保存。
2. 为它设置嵌入策略：选择**运行环境**，在**允许的来源**里添加你的网站来源（如 `https://shop.example.com`）；本地调试可允许 localhost。
3. 记下智能体的 `id`（形如 `agent_…`）或短号。

期望：嵌入策略保存成功，来源列表里能看到你的网站。没有嵌入策略的智能体不能签发令牌。

## 2. 后端签发令牌 [#2-后端签发令牌]

用 API Key 调 `POST /agent/v1/embed_tokens`。API Key 只放在后端，不要写进前端代码。

```ts
// 你的后端，以 fetch 为例
const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换

export async function issueToken(userId: string) {
  const response = await fetch(`${API}/agent/v1/embed_tokens`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, // 占位：你的 API Key
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: "agent_xxx",       // 换成你的智能体 id 或短号
      external_user_id: userId, // 你系统里这位用户的稳定 ID
    }),
  });
  if (!response.ok) throw new Error("token request failed");
  const { token, expires_at } = await response.json();
  return { token, expires_at };
}
```

把它挂在你自己的登录保护之后，例如 `POST /api/praxis-token`：先确认用户已登录，再用**登录态里的用户 ID** 签发，不要信任前端传来的用户 ID。

期望：Praxis 返回 HTTP 200 和 `{ id, token, expires_at }`；你的宿主端点返回 `{ token, expires_at }`，`expires_at` 为 ISO 8601 时间。字段规则见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)。

## 3. 前端加载 Kit [#3-前端加载-kit]

```html
<script type="module">
  import "/praxis-kit.js"; // Kit 的构建产物，由你的站点提供

  const agent = document.createElement("praxis-agent");
  agent.setAttribute("layout", "popup");
  agent.setAttribute("launcher", "bubble");
  agent.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com", // 正式地址上线后替换
      getToken: async (current) => {
        const response = await fetch("/api/praxis-token", { method: "POST", credentials: "same-origin" });
        if (!response.ok) throw new Error("客服暂时不可用，请稍后重试");
        return (await response.json()).token;
      },
    },
    agent: { name: "好物集客服" },
    startScreen: { greeting: "你好，有什么可以帮你？" },
  });
  document.body.appendChild(agent);
</script>
```

* `api.url` 填 API 域名，也可以是完整的 `/agent/v1` 地址。
* `getToken(current)` 由 Kit 在需要令牌时调用，参数是当前令牌（首次为 `null`），返回令牌字符串。令牌只保存在内存里。
* `setOptions` 把字段合并进当前配置；移除元素会取消进行中的流。
* 在 React 里使用 `@deepractice-ai/praxis-kit-react` 的 `<PraxisAgent>`，见[嵌入方式](/docs/cloud/services/agent/embed/methods)。

期望：页面右下角出现气泡，点开后能发送消息并收到回复；浏览器里没有 `praxis.error` 事件。

## 完整样例 [#完整样例]

仓库里的「好物集」演示站（`apps/kit-demo`）是一个可运行的完整宿主：假登录、`/api/praxis-token` 签发端点、把会员等级作为[上下文](/docs/cloud/services/agent/embed/context)随令牌传入，以及挂载 Kit 的前端。

## 常见问题 [#常见问题]

* **签发返回「Agent not found」**：智能体必须是服务型、未归档、属于你的 API Key 所在组织。
* **签发返回 `INVALID_PARAMS`「embed policy not configured」**：智能体还没有嵌入策略。
* **签发返回 `EMBED_USER_BLOCKED`**：该 `external_user_id` 在智能体的封禁名单里。
* **组件无法对话**：确认页面来源在「允许的来源」里，且 `api.url` 与签发令牌用的是同一个环境。

下一步：[选择嵌入方式](/docs/cloud/services/agent/embed/methods) · [令牌细节](/docs/cloud/services/agent/embed/tokens) · [传入上下文](/docs/cloud/services/agent/embed/context)

# 嵌入方式

把服务型智能体交给你的终端用户有四种方式。它们共用同一套[嵌入令牌](/docs/cloud/services/agent/embed/tokens)，差别在谁来渲染界面、你要写多少代码。

|        | iframe          | Kit 组件                              | Hosted 页             | API                  |
| ------ | --------------- | ----------------------------------- | -------------------- | -------------------- |
| 谁渲染界面  | Praxis（页内框架）    | Praxis 的 `<praxis-agent>`，在你的页面里    | Praxis（独立页面，用户被跳转过去） | 你自己                  |
| 外观在哪配置 | 控制台             | 前端 `setOptions`（布局、启动按钮、标题、欢迎语、输入框） | 控制台                  | 完全自定                 |
| 代码量    | 后端签发 + 一行标签     | 后端签发 + 前端十几行                        | 后端签发 + 302 跳转        | 后端签发 + 自建全部界面与事件流    |
| 适合场景   | 想最快上线、外观不需要深度定制 | 要和宿主页面融合：浮窗、侧栏、控制打开、监听事件            | 使用独立对话页，由宿主验证身份后跳转   | 自有 App、非网页载体、完全自定义体验 |
| 当前状态   | 可用              | 可用                                  | 可用                   | 可用                   |

## 怎么选 [#怎么选]

* **最快嵌入网页**：用 iframe 加载器；需要在宿主代码里定制组件时用 Kit。
* **用 React**：用 `@deepractice-ai/praxis-kit-react`，它把 `<praxis-agent>` 包成 `<PraxisAgent>` 和 `usePraxisAgent()`。
* **不是网页，或界面必须完全自己画**：用 API，自己签发令牌，用会话和事件接口收发消息。接口见 [API 参考](/docs/api/native/agent)。
* **独立对话页**：用 Hosted，由后端签发后跳转。

## iframe 一行接入 [#iframe-一行接入]

先按[快速开始](/docs/cloud/services/agent/embed/quickstart)配置来源白名单和后端 `POST /api/praxis-token`，返回 `{ token, expires_at }`。把下面一行放进宿主页面，将 `ABC123` 换成智能体短号：

```html
<script src="https://kit-develop.praxisusercontent.com/v1/loader.js" data-agent="ABC123" data-token-endpoint="/api/praxis-token" async></script>
```

加载器用 POST 请求你的令牌接口，并携带浏览器凭据；后端必须从登录态确定用户。API Key 只留在后端。

| 属性                    | 用法                                    |
| --------------------- | ------------------------------------- |
| `data-agent`          | 必填，5–8 位字母数字短号，不是 `agent_…` ID        |
| `data-token-endpoint` | 必填，宿主签发端点，返回 `{ token, expires_at }`  |
| `data-layout`         | 可选，`inline`、`popup`、`sidebar`、`modal` |
| `data-launcher`       | 可选，`bubble`、`none`，或宿主按钮的 CSS 选择器     |

不写 `data-layout` / `data-launcher` 时，使用控制台保存的外观；写入时覆盖对应设置。外观尚未设置布局时，加载器默认 `popup`。

直接 iframe 地址为 `https://chat-develop.praxisusercontent.com/a/ABC123`。地址本身不提供登录用户凭证；用上面的加载器完成令牌传递。页面的 `frame-ancestors` 来自来源白名单；宿主还需允许 chat 域名的 `frame-src`，见[安全](/docs/cloud/services/agent/embed/security)。

期望：刷新宿主页后看到保存的外观，发送消息后收到回复。

## Hosted 托管页 [#hosted-托管页]

像 Stripe Checkout 一样：宿主后端验证用户身份，签发时设置 `hosted: true`，再向浏览器返回 302，`Location` 为返回的 `hosted_url`。完整示例和一次性凭证规则见[嵌入令牌](/docs/cloud/services/agent/embed/tokens)。Hosted 与 iframe 共用控制台保存的外观。

## Kit 组件 [#kit-组件]

Kit 是一个自定义元素，界面渲染在 Shadow DOM 里，宿主样式不会影响对话界面。布局有 `inline`、`sidebar`、`popup`、`modal`，启动按钮有 `none`、`bubble`、`mascot`。接入步骤见[嵌入到网页](/docs/cloud/services/agent/embed/quickstart)。

React 示例：

```tsx
import { PraxisAgent, usePraxisAgent } from "@deepractice-ai/praxis-kit-react";

const options = {
  api: { url: "https://api-develop.deepraxis.com" }, // 正式地址上线后替换
  agent: { name: "好物集客服" },
};

export function Support() {
  const { ref, control } = usePraxisAgent();
  return (

## API [#api]

API 方式没有现成界面。你的后端签发令牌，客户端用令牌调用会话与事件接口；终端用户令牌只能访问自己名下的会话。适合需要自画界面的场景。

下一步：[嵌入到网页](/docs/cloud/services/agent/embed/quickstart) · [嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)

# 嵌入令牌与终端用户

嵌入令牌是你的后端为一位终端用户签发的短期凭证。用它的人只能以这位用户的身份与指定智能体对话。

## 签发 [#签发]

`POST /agent/v1/embed_tokens`，用 API Key 鉴权，只在后端调用。

```bash
curl https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "external_user_id": "customer_123",
    "ttl_seconds": 900,
    "system_message": [{ "type": "text", "text": "当前用户会员等级：金卡" }]
  }'
```

示例域名为 develop 环境，正式地址上线后替换。期望：HTTP 200。

| 字段                 | 说明                                                                           |
| ------------------ | ---------------------------------------------------------------------------- |
| `agent`            | 必填。服务型智能体的 id 或短号，必须属于你的组织、未归档，并已设置嵌入策略                                      |
| `external_user_id` | 必填。你系统里终端用户的稳定 ID，1–128 个字符，只含 `A-Z a-z 0-9 _ . : @ -`。在同一组织的同一智能体内唯一标识这位用户  |
| `ttl_seconds`      | 令牌有效期，60–3600 秒。缺省用嵌入策略的默认值，且不能超过策略的上限与 3600 秒                               |
| `version`          | 固定使用的智能体版本。缺省时用策略里固定的版本，否则用签发时的最新版本。令牌签发后版本不再变化                              |
| `system_message`   | 宿主上下文，文本块数组，合计不超过 8192 字节。见[传入上下文](/docs/cloud/services/agent/embed/context) |
| `agent_override`   | `{ "system": "…" }`，替换该令牌的指令。仅当嵌入策略允许覆盖时可用，否则返回 `EMBED_FIELD_NOT_ALLOWED`    |
| `budget_cents`     | 单个会话的预算（分）。缺省用策略默认值，不能超过策略上限                                                 |
| `allowed_origins`  | 来源白名单的子集，缺省为策略里的全部来源                                                         |
| `metadata`         | 原样保存的宿主元数据，最多 16 个键，键 1–64 字符，值字符串不超过 512 字符                                 |
| `hosted`           | 设为 `true` 时额外返回用于 Hosted 跳转的 `hosted_url`                                    |

每次调用都会产生一份新的签发记录，签发不是幂等的。

返回：

```json
{ "id": "emb_…", "token": "…", "expires_at": "2026-10-19T08:00:00.000Z" }
```

`id` 是这次签发的标识，用于吊销与查询；`token` 交给前端；`expires_at` 是 ISO 8601 UTC 时间。

## 跳转到 Hosted [#跳转到-hosted]

验证用户登录后调用以下函数，`userId` 必须来自服务端登录态：

```ts
export async function openHosted(userId: string) {
  const response = await fetch("https://api-develop.deepraxis.com/agent/v1/embed_tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent: "agent_xxx", external_user_id: userId, hosted: true }),
  });
  if (!response.ok) throw new Error("Hosted issuance failed");
  const { hosted_url } = await response.json();
  return new Response(null, { status: 302, headers: { Location: hosted_url } });
}
```

期望：浏览器跳转后进入托管对话页。`hosted_url` 的 `#c=…` 片段携带**60 秒内有效、只能用一次**的凭证，不是嵌入令牌。托管页自动向 `POST /agent/v1/embed/exchange` 提交 `{ "code": "…" }`，取得 `{ token, expires_at }`。凭证已用、过期或无效时返回 `NOT_FOUND`（404），应重新签发，不要复用或分享这个链接。兑换凭证的期限与令牌有效期是两回事。

## 匿名访客 [#匿名访客]

访客没有宿主登录态时，可向 `POST /agent/v1/embed_tokens/anonymous` 提交 `{ "publishable_key": "PRAXIS_API_KEY" }`。这里的 `PRAXIS_API_KEY` 是**可公开 key 的占位符**，不能填服务器 API Key。响应含 `{ token, expires_at }`，新访客还会收到 `visitor_secret`；后续请求带上这个 `visitor_secret` 可延续访客身份。它是私有访客凭证，不要公开。

接口验证浏览器来源白名单，并执行可公开 key 的匿名限额。不接受调用方指定 `external_user_id`、指令、预算或 Hosted 选项。每日会话与花费上限按 UTC 自然日计算，统计实际会话，不把令牌刷新计为新会话。

## 刷新 [#刷新]

Kit 需要令牌时调用你提供的 `getToken(current)`：首次 `current` 为 `null`，更换时传入当前令牌。在里面请求你自己的后端，由后端重新签发并返回新令牌字符串即可。重新签发前先确认用户仍然登录。令牌只保存在浏览器内存里。

## 吊销 [#吊销]

吊销单张令牌：

```bash
curl -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens/emb_xxx/revoke \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

期望：返回带 `revoked_at` 的签发记录。该令牌立即失效，它打开的事件流会收到 `session.error`（`EMBED_TOKEN_REVOKED`）后关闭，其他令牌不受影响。重复吊销返回同一条记录。上游吊销失败时返回错误，记录保持未吊销，可重试。

`GET /agent/v1/embed_tokens` 列出签发记录，可按 `agent_id`、`external_user_id` 过滤，用 `limit`（1–100，默认 20）和 `page` 翻页。记录里不包含令牌本身。

## 封禁终端用户 [#封禁终端用户]

在智能体的嵌入策略里维护**封禁名单**（`blocked_end_users`）：名单里的 `external_user_id` 不能再获得令牌，签发返回 `EMBED_USER_BLOCKED`。名单在 Console 的嵌入设置里管理。

按终端用户管理（[API 参考](/docs/api/native/agent) 为准）：

* `POST /agent/v1/agents/{agent_id}/end_users/{external_user_id}/revoke_tokens`：一次吊销该用户当前所有有效令牌，进行中的对话随即中断；
* `POST .../block`：封禁，同时立即吊销现有令牌，之后宿主为他签发新令牌会返回 `EMBED_USER_BLOCKED`；
* `POST .../unblock`：解封。

Console「运营与管理 · 终端用户」页提供同样的操作（见 [Console：运营与管理](/docs/cloud/services/agent/embed/console-operate)）。

## 终端用户只能访问自己的会话 [#终端用户只能访问自己的会话]

用嵌入令牌调用 API 的是终端用户，不是你的组织。他只能创建和读取**自己名下**的会话，看不到同一智能体下其他用户的会话，也不能调用签发、吊销、列出令牌这类宿主接口（调用会得到 404）。身份来自令牌，不来自请求里的任何参数。

# 传入上下文

智能体需要知道「这位用户是谁、他在看什么、能调用你的什么系统」。有五个渠道，按可信度和稳定性选用。

| 渠道                  | 谁写         | 何时生效         | 可信度        |
| ------------------- | ---------- | ------------ | ---------- |
| 1. 智能体指令            | 你，在控制台     | 每个会话         | 最高，属于智能体本身 |
| 2. 覆盖指令             | 你的后端，签发令牌时 | 该令牌的会话       | 高，仅策略允许时可用 |
| 3. `system.message` | 你的后端       | 令牌签发时，或会话进行中 | 可信的宿主上下文   |
| 4. 页面上下文            | 页面         | 每条用户消息       | 不可信        |
| 5. 工具（MCP）          | 你的系统       | 调用时          | 取决于你的鉴权    |

## 1. 智能体指令 [#1-智能体指令]

在控制台配置，写智能体的角色、口吻和边界，所有会话共享。适合不随用户变化的内容。

## 2. 覆盖指令 [#2-覆盖指令]

签发令牌时传 `agent_override: { "system": "…" }`，替换这张令牌所属会话的指令；`null` 表示清空。仅当嵌入策略允许覆盖时可用，否则签发失败（`EMBED_FIELD_NOT_ALLOWED`）。适合按客户、按租户换一套话术。

## 3. `system.message` [#3-systemmessage]

宿主向智能体传入的可信事实，例如用户姓名、会员等级、语言。有两种写入方式：

* **签发令牌时**：`system_message` 字段，文本块数组，合计不超过 8192 字节。会话开始后，这些内容在下一次模型请求里出现。
* **会话进行中**：用 API Key 向会话发送 `system.message` 事件，内容为文本块数组。每次不超过 8192 字节，同一会话累计不超过 65536 字节；会话已归档时被拒绝。

多次写入会**累积**为宿主上下文，在系统提示里放在智能体指令之后，包在 `<host_context>` 标签中，压缩历史时也不会丢。

```json
{ "type": "system.message", "content": [{ "type": "text", "text": "用户刚完成了订单 A1024 的支付" }] }
```

只有持有 API Key 的宿主能发 `system.message`；终端用户令牌不能。

## 4. 页面上下文 [#4-页面上下文]

Kit 会在每条用户消息里附带页面登记的上下文（例如正在看的课程），体积上限 4096 字节、最多 32 项，并标记为**不可信**：它来自浏览器，用户可以改。需要可信事实时请用渠道 3。登记方法见[前端工具与页面上下文](/docs/cloud/services/agent/embed/client-tools)。

## 5. 工具 [#5-工具]

智能体可以通过 MCP 调用你的系统，查订单、发起退货。平台在调用时会附带三个请求头：

| 请求头                         | 含义                              |
| --------------------------- | ------------------------------- |
| `X-Praxis-External-User-Id` | 令牌里的 `external_user_id`，即你的终端用户 |
| `X-Praxis-Agent-Id`         | 智能体 id                          |
| `X-Praxis-Session-Id`       | 会话 id                           |

只有会话属于某位终端用户时才带这些头。你的工具**必须**按 `X-Praxis-External-User-Id` 限定数据范围，例如只返回这位用户自己的订单。不要依赖模型传来的参数确定用户：它可以被诱导。「好物集」演示站的订单 MCP 就是这样做的。

## 选哪个 [#选哪个]

* 所有用户都一样：用渠道 1。
* 按用户或租户变化的事实，必须可信：用渠道 3。
* 需要换一整套指令：用渠道 2。
* 要读写你的数据：用渠道 5，并在工具里鉴权。

# 前端工具与页面上下文

智能体在对话里常常需要「此刻页面上的东西」：视频播到了哪里、表单填了什么、选中了哪一行。这些数据只在浏览器里，你的后端看不到。Kit 给了两个入口：

| 入口        | 谁触发     | 数据怎么到智能体            | 适合                       |
| --------- | ------- | ------------------- | ------------------------ |
| **前端工具**  | 智能体决定调用 | 智能体调用，页面里的函数执行并返回结果 | 按需读取、需要计算或查询的数据，以及页面上的动作 |
| **页面上下文** | 页面主动提供  | 随每条用户消息附带           | 几乎每轮都用得上的小事实，例如「正在看第几课」  |

## 前端工具 [#前端工具]

分三步：在智能体里声明工具，在页面里实现它，智能体调用时 Kit 把结果送回去。

### 1. 在智能体定义里声明 [#1-在智能体定义里声明]

在智能体的 `tools` 里加一项 `type: "custom"`。智能体只看得到名字、描述和输入结构，执行在你的页面里。

```json
{
  "type": "custom",
  "name": "read_playback_progress",
  "description": "读取用户当前视频的播放进度，单位秒。用户问「我看到哪了」时调用。",
  "input_schema": { "type": "object", "properties": {} }
}
```

* `name` 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`，不能与其他自定义工具或内置工具重名。
* `description` 决定智能体何时调用它，写清楚用途和何时用。
* `input_schema` 是 JSON Schema，`type` 必须是 `object`。

### 2. 在页面里实现（Web Component） [#2-在页面里实现web-component]

把处理函数赋给元素的 **`onClientTool` 属性**。它是 JavaScript 属性，不是 HTML 属性，也不是 `setOptions` 的选项。

```html
<video id="lesson-video" src="/lessons/3.mp4" controls></video>
<praxis-agent style="display:block;height:600px"></praxis-agent>

<script type="module">
  import "/praxis-kit.js";

  const video = document.querySelector("#lesson-video");
  const agent = document.querySelector("praxis-agent");

  agent.setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      getToken: async () => {
        const response = await fetch("/api/praxis-token", { method: "POST" });
        if (!response.ok) throw new Error("暂时无法使用");
        return (await response.json()).token;
      },
    },
    agent: { name: "课程助手" },
  });

  // 前端工具：智能体调用时执行
  agent.onClientTool = async ({ id, name, input }) => {
    if (name !== "read_playback_progress") throw new Error(`未知工具：${name}`);
    return { positionSeconds: video.currentTime, durationSeconds: video.duration };
  };

  // 页面上下文：随每条用户消息附带
  agent.setReadable("lesson", "正在看第 3 课");
  agent.setReadable("playback", { positionSeconds: 83 });
  // 之后可以移除
  agent.removeReadable("playback");

  // 可选：观察调用与日志
  agent.addEventListener("praxis.tool.change", e => console.log(e.detail));
  agent.addEventListener("praxis.log", e => console.warn(e.detail));
</script>
```

处理函数收到 `{ id, name, input }`：`id` 是这次调用的编号，`name` 是工具名，`input` 是智能体按 `input_schema` 传来的参数。Kit 不维护工具注册表，所有自定义工具都进这一个函数，所以**对不认识的名字必须抛错**。

返回值的处理：

| 你返回                      | 智能体收到                   |
| ------------------------ | ----------------------- |
| 字符串                      | 原样                      |
| 其他可序列化的值                 | `JSON.stringify` 后的文本   |
| `undefined`              | 空字符串                    |
| 抛出错误、Promise 被拒绝、结果无法序列化 | 错误文本，并标记为错误（`is_error`） |

### 2'. 在页面里实现（React） [#2-在页面里实现react]

React 绑定提供两个 hook：`usePraxisTool` 注册工具，`usePraxisReadable` 提供页面上下文。它们要在 `<PraxisAgent>` 的子树里，或在外层 `<PraxisProvider>` 里使用。

```tsx
import { useMemo, useRef } from "react";
import {
  PraxisAgent, usePraxisTool, usePraxisReadable,
} from "@deepractice-ai/praxis-kit-react";

function LessonBridge({ lesson, videoRef }) {
  // 页面上下文：lesson 变化时自动更新，卸载时自动移除
  usePraxisReadable("lesson", `正在看第 ${lesson.number} 课：${lesson.title}`);

  // 前端工具：卸载或改名时自动取消注册
  usePraxisTool("read_playback_progress", () => ({
    positionSeconds: videoRef.current?.currentTime ?? 0,
    durationSeconds: videoRef.current?.duration ?? 0,
  }));
  return null;
}

export function LessonPage({ lesson }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const options = useMemo(() => ({
    api: { url: "https://api-develop.deepraxis.com" },
    agent: { name: "课程助手" },
  }), []);

  return (
    <>
      <video ref={videoRef} src={lesson.src} controls />
    </>
  );
}
```

要点：

* `usePraxisTool(name, handler)`：`handler` 收到 `(input, call)`，可返回值或 Promise。handler 更换时自动使用最新的函数，不会重新注册。同名工具重复注册时，最后挂载的生效，开发模式下会警告；它卸载后恢复上一个。
* `usePraxisReadable(name, value)`：挂载时设置，`JSON.stringify(value)` 变化时更新，卸载时移除。值要能 JSON 序列化，变化要触发 React 渲染。
* 没有用 hook 注册的工具名，会交给 `<PraxisAgent onClientTool={…}>`；两者都不处理时，调用以 `unknown tool <name>` 报错返回给智能体。
* 想在 `<PraxisAgent>` 之外的组件里注册，把整棵树包在 `<PraxisProvider>` 里。
* `options` 请保持引用稳定（`useMemo`），见[组件参考](/docs/cloud/services/agent/embed/component-reference)。

## 页面上下文 [#页面上下文]

`setReadable(name, value)`（React 里是 `usePraxisReadable`）登记一条页面事实。此后**每一条用户消息**发出时，Kit 都会附带当前所有登记项的快照，包括首条消息、输入框发送、`sendUserMessage` 和推荐问题。

* `name` 匹配 `[A-Za-z0-9_.:-]{1,64}`；值是字符串或可 JSON 序列化的值。非法的名字或值会抛出 `TypeError`，且不会覆盖原来的值。
* 更新同名项保持它原来的位置；移除后重新登记会排到最后。
* 没有登记项时不附带任何内容。

服务端把它渲染成附在**本轮用户消息末尾**的一段文本，并明确标记为不可信：

```xml
<page_context untrusted="true">
<item name="lesson">正在看第 3 课</item>
<item name="playback">{"positionSeconds":83}</item>
</page_context>
```

它不进系统提示，也不会延续到下一轮：下一条消息带的是那一刻的新快照。所以页面状态变了，智能体下一轮自然看到新值，你不需要清理旧值。

## 超时、错误与未注册的工具 [#超时错误与未注册的工具]

| 情况                                                      | 结果                                                                                     |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 元素上没有 `onClientTool`（React 里没有对应 hook 和 `onClientTool`） | 立刻返回 `tool <name> is not available on this page`，标记为错误（React 中为 `unknown tool <name>`） |
| 处理函数抛错或 Promise 被拒绝                                     | 错误信息作为错误结果返回，智能体看得到，通常会向用户解释或换个办法                                                      |
| 结果无法 `JSON.stringify`                                   | 同上，作为错误返回                                                                              |
| 页面一直没有返回结果                                              | 服务端等待最多 **120 秒**，到时记一条错误结果（`client tool timed out`），本轮继续                              |
| 结果写回失败                                                  | Kit 触发 `praxis.log`（`level: "error"`），不会重跑你的函数，也不会发出成功的 `end` 事件；服务端的 120 秒超时兜底        |

同一个调用编号只执行一次：Kit 在执行前先认领编号，并检查历史里是否已有结果。切换会话、断线重连、重新挂载都不会让已经回答过的调用重跑；还没有结果的历史调用在页面重新打开时可以被执行。这不是跨标签页的事务保证，同一会话在两个标签页打开时，不要让工具产生副作用。

### 事件 [#事件]

在元素上监听，都会冒泡并穿过 Shadow DOM。

| 事件                   | `detail`                                                 | 说明                                                     |
| -------------------- | -------------------------------------------------------- | ------------------------------------------------------ |
| `praxis.tool.change` | `{ id, name, status: "start" \| "end", isError? }`       | `start` 在你的函数执行前；`end` 在结果被服务端确认之后                     |
| `praxis.log`         | `{ level: "info" \| "warn" \| "error", message, data? }` | 上下文被截断时为 `warn`，`data.names` 列出被丢弃的名字；结果写回失败时为 `error` |

React 里对应 `onToolChange` 和 `onLog`。

## 限制 [#限制]

| 项       | 限制                                                                          |
| ------- | --------------------------------------------------------------------------- |
| 页面上下文条数 | 每条消息最多 32 项                                                                 |
| 页面上下文体积 | 序列化后合计最多 4096 字节（UTF-8）                                                     |
| 超出时     | Kit 从**最早登记的**开始丢弃，直到满足两项限制，并触发 `praxis.log` 的 `warn`；登记本身不受影响。全部被丢弃时不附带该字段 |
| 名字      | `[A-Za-z0-9_.:-]{1,64}`                                                     |
| 工具名     | `^[a-zA-Z0-9_-]{1,64}$`                                                     |
| 等待结果    | 最多 120 秒                                                                    |

给智能体看的数据要精简：只放这一轮可能用到的事实，大块数据用前端工具按需读取。

## 常见问题 [#常见问题]

* **工具没被调用**：确认智能体定义里有同名的 `custom` 工具，并且 `description` 说明了何时用。
* **总是收到「not available」**：`onClientTool` 要赋给元素的属性，且在智能体调用之前赋好；放在 `setOptions` 里无效。
* **上下文没有出现**：确认值已登记且没有超过限制，留意 `praxis.log` 的警告。

下一步：[工具授权](/docs/cloud/services/agent/embed/tool-authorization) · [安全](/docs/cloud/services/agent/embed/security) · [组件参考](/docs/cloud/services/agent/embed/component-reference)

# 工具授权

智能体能调用你的系统：查订单、改地址、申请退货。这一页讲两件事：**哪些调用要先让用户确认**，以及**真正的权限在哪里卡住**。

## 两档策略 [#两档策略]

每个工具有一个权限策略，只有两档：

| 策略             | 行为                            |
| -------------- | ----------------------------- |
| `always_allow` | 智能体直接调用，不打断用户                 |
| `always_ask`   | 调用前暂停，在对话里显示确认卡，用户选择允许或拒绝后才继续 |

没有第三档。写入 `auto` 会被拒绝（`auto 尚未支持`）。

策略写在智能体定义的 `tools` 里，MCP 工具集可以设整体默认，也可以逐个工具覆盖：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "orders",
  "default_config": { "permission_policy": { "type": "always_ask" } },
  "configs": [
    { "name": "list_orders", "permission_policy": { "type": "always_allow" } },
    { "name": "request_return", "permission_policy": { "type": "always_ask" } }
  ]
}
```

优先级：单个工具的 `configs[].permission_policy`，然后是 `default_config.permission_policy`，都没写则使用默认值。

## 默认值 [#默认值]

| 工具类型                            | 没有写策略时                                                                              |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| MCP 工具（`mcp_toolset`）           | `annotations.readOnlyHint === true` 时为 `always_allow`；缺失、false 或非布尔值时为 `always_ask` |
| 内置工具集（`agent_toolset_20260401`） | 工具集的 `default_config` 没写时为 `always_allow`                                           |
| 前端工具（`type: "custom"`）          | 没有确认步骤。它由你页面里的代码执行，见[前端工具](/docs/cloud/services/agent/embed/client-tools)           |

此缺省规则适用于所有智能体的 MCP 工具。hint 来自 MCP 服务器，是不可信的提示，只影响缺省；单工具和工具集的显式配置始终优先。询问同样不是安全手段。给每个工具设策略时，按「用户自己能不能撤销、做错了代价多大」来决定：查询类放行，退款、删除、发送类保留询问。

## 确认卡 [#确认卡]

当某个调用的策略是 `always_ask`，对话会暂停，Kit 在对话里显示确认卡。终端用户选择允许或拒绝：

* 允许：调用继续，结果回到智能体。
* 拒绝：调用不执行，对话继续。

确认卡由 Kit 自带，你不需要写界面。会话预算用完后，会话不再接收新的任务，但仍然接收工具确认和中断。需要在自有界面里处理确认的宿主，可以用 API 发送 `user.tool_confirmation` 事件，字段为 `tool_use_id` 和允许 / 拒绝，详见 [API 参考](/docs/api/native/agent)。

## 真正的安全：在工具服务端鉴权 [#真正的安全在工具服务端鉴权]

智能体调用你的 MCP 服务器时，平台会带上三个请求头，说明这次调用代表谁：

| 请求头                         | 含义                                     |
| --------------------------- | -------------------------------------- |
| `X-Praxis-External-User-Id` | 签发令牌时传入的 `external_user_id`，即你系统里的终端用户 |
| `X-Praxis-Agent-Id`         | 智能体 id                                 |
| `X-Praxis-Session-Id`       | 会话 id                                  |

这三个头只在会话属于某位终端用户时才带；没有终端用户的会话不带，你的服务要把缺失当作拒绝。它们来自平台对令牌的验证，**不是模型可以填写的参数**，所以是你唯一应该信任的身份来源。

规则：

1. **身份只取请求头**。不要让工具接收 `user_id` 之类的参数再相信它：模型可以被诱导填任何值。
2. **每次查询都按用户限定范围**。查询条件里带上用户，而不是查出来再过滤；操作一个具体对象（订单、地址）前先确认它属于这个用户。
3. **缺少身份就拒绝**，返回错误，不要退化成匿名访问。
4. **服务本身也要认证调用方**。MCP 服务器是公网地址，请求头可以被伪造；在智能体定义里为 MCP 服务器配置 `headers`（例如 `Authorization: Bearer …`），服务端先校验这个凭据，再信任 `X-Praxis-*` 头。
5. **危险动作在服务端再检查一遍**业务规则（订单是否已签收、是否超过退货期），不要依赖「用户在确认卡上点过允许」。

示例：一个按终端用户限定范围的订单查询和退货工具（与 MCP 实现无关的部分）。

```ts
// 你的 MCP 服务器：每个请求先认证，再按终端用户执行
type Caller = { userId: string };

function authenticate(request: Request): Caller | Response {
  // 1) 认证 Praxis：智能体定义里为这个 MCP 服务器配置的 Authorization 头
  if (request.headers.get("authorization") !== `Bearer ${process.env.PRAXIS_MCP_SECRET}`) {
    return new Response("Unauthorized", { status: 401 });
  }
  // 2) 终端用户身份：只信平台附带的请求头
  const userId = request.headers.get("X-Praxis-External-User-Id");
  if (!userId) return new Response("Missing end-user identity", { status: 403 });
  return { userId };
}

// list_orders：只读，没有任何用户可选的参数
async function listOrders(caller: Caller) {
  return db.orders.findMany({ where: { userId: caller.userId } }); // 范围在查询里
}

// request_return：参数 order_id 来自模型，必须再校验归属和业务规则
async function requestReturn(caller: Caller, input: { order_id: string; reason: string }) {
  const order = await db.orders.findFirst({
    where: { id: input.order_id, userId: caller.userId }, // 不属于该用户就查不到
  });
  if (!order) return { isError: true, text: "订单不存在" }; // 与「不属于你」不作区分
  if (order.status !== "delivered") return { isError: true, text: "只有已签收的订单可以退货" };
  return db.returns.create({ data: { orderId: order.id, reason: input.reason } });
}
```

`db` 表示你自己的数据访问层。要点是：`userId` 永远来自 `X-Praxis-External-User-Id`，`order_id` 虽然由模型提供，但在带着 `userId` 的查询里才有效，别人的订单号查不出东西。

仓库里的「好物集」演示站（`apps/kit-demo`）的订单 MCP 就是这样做的：`list_orders` 声明 `readOnlyHint: true`，`request_return` 声明 `destructiveHint: true`，两者都从同一个请求头取用户。

## 选择策略的建议 [#选择策略的建议]

| 工具                | 建议                                 |
| ----------------- | ---------------------------------- |
| 只读查询，且服务端已按用户限定范围 | `always_allow`                     |
| 会改变数据，用户可以自己撤销    | 视情况，确认卡能减少误操作                      |
| 不可撤销、涉及金额或对外发送    | `always_ask`，同时服务端再校验              |
| 前端工具              | 没有确认卡。不要让它执行不可撤销的动作，需要时在你自己的界面里弹确认 |

下一步：[安全](/docs/cloud/services/agent/embed/security) · [传入上下文](/docs/cloud/services/agent/embed/context)

# 安全

嵌入把一个智能体放进你的页面，页面的访问者就是智能体的使用者。这一页说明平台替你守住了什么、哪些要你自己守，以及宿主页怎样配置。

## 责任划分 [#责任划分]

| 平台保证                      | 你负责                                                                       |
| ------------------------- | ------------------------------------------------------------------------- |
| 嵌入令牌只能访问一个智能体下**自己名下**的会话 | 用你自己的登录态确定 `external_user_id`，不要信浏览器传来的值                                  |
| 越权访问一律返回 404，不透露资源是否存在    | 工具服务端按终端用户鉴权（[工具授权](/docs/cloud/services/agent/embed/tool-authorization)） |
| 令牌只在浏览器内存里，短期有效，可以随时撤销    | 保管 API Key，只在后端使用                                                         |
| 只接受白名单来源的页面使用令牌           | 配好 `allowed_origins`，宿主页配好 CSP                                            |

## 隔离边界 [#隔离边界]

* **令牌的主体是终端用户**，不是你的组织。持有令牌的人只能创建和读取自己名下的会话，看不到同一智能体下其他用户的会话，也不能调用签发、撤销、列出令牌这类宿主接口（返回 404）。身份来自令牌，不来自请求参数。
* **跨用户、跨智能体一律 404**，而不是 403：不告诉访问者「这个东西存在但不属于你」。
* **API Key 永远不进浏览器**。后端用它签发令牌；浏览器只拿令牌。令牌的签发与撤销见[令牌与终端用户](/docs/cloud/services/agent/embed/tokens)。

## 令牌 [#令牌]

* 令牌有效期 60 到 3600 秒。设短一些：被截获的令牌价值有限。`getToken` 会在到期前被再次调用，换发时再确认一次用户仍处于登录状态。
* 令牌只存在于内存，不要自己写进 `localStorage`、Cookie 或页面 HTML。
* 发现泄露或用户登出时，按签发记录的 `id` 撤销，令牌立即失效，进行中的事件流会收到 `EMBED_TOKEN_REVOKED` 并关闭。
* 对某个用户启用封禁（`blocked_end_users`），他就拿不到新令牌。

## 来源白名单 [#来源白名单]

嵌入策略里的 `allowed_origins` 限定哪些页面来源可以使用令牌。签发令牌时可以再收窄（传 `allowed_origins`，必须是策略白名单的子集）。来源不在名单上时，请求返回 `EMBED_ORIGIN_NOT_ALLOWED`（403）。

* 只接受 `https` 来源；`https://*.example.com` 形式的通配只匹配一级子域名，不含端口。
* 本地开发才打开 `allow_localhost`，上线前关掉。
* 来源由浏览器写入请求，它挡住的是**别的网站**拿你的令牌去用，挡不住拿到令牌的非浏览器客户端。令牌本身仍要妥善保管。

## 哪些不是秘密 [#哪些不是秘密]

下面这些内容，模型可能被用户要求复述，请当作公开信息对待：

* 智能体的指令（Console 里写的 instructions）。
* 覆盖指令（`agent_override.system`）。
* `system.message` 里的宿主上下文。
* 页面上下文和前端工具的返回值。
* 工具的名字、描述和输入结构。

所以不要在这些地方放密钥、内部规则、不想让用户看到的话术或别人的数据。需要保密的数据放在你的工具服务端，用[终端用户身份](/docs/cloud/services/agent/embed/tool-authorization)控制谁能取到。

## 提示注入与不可信上下文 [#提示注入与不可信上下文]

智能体读到的内容里，凡是来自浏览器或第三方的，都可能含有试图操纵它的指令：用户输入、页面上下文、网页内容、工具返回的文本。

* **页面上下文是不可信的**。服务端把它放进附在本轮用户消息末尾的 `<page_context untrusted="true">` 块里，不进系统提示，也不延续到下一轮。值里的 `<`、`>`、`&` 和引号会被转义，不能伪造出新的标签。详见[前端工具与页面上下文](/docs/cloud/services/agent/embed/client-tools)。
* **可信事实走 `system.message`**。只有持有 API Key 的后端能写入它，终端用户令牌不能。
* **不要靠指令里的「不要……」守住边界**。真正要禁止的事，在工具一侧不提供，或者在服务端拒绝。
* 智能体可以调用的工具越少越安全：只为这个场景开需要的工具，写入类工具保留 `always_ask`，并在服务端校验。

## iframe 与 Hosted [#iframe-与-hosted]

iframe 页的 `frame-ancestors` 来自智能体的来源白名单；白名单为空时禁止所有网站嵌入。Hosted 是独立页面，使用 `frame-ancestors 'none'`。平台托管的 chat 页从自身可信来源请求 API；宿主来源由 iframe 策略和跨窗口通信校验。

使用一行加载器时，宿主 CSP 还需在 `frame-src` 放行 `https://chat-develop.praxisusercontent.com`。加载器同时校验跨窗口消息的来源和发送窗口。Hosted 凭证只能使用一次，见[嵌入令牌](/docs/cloud/services/agent/embed/tokens)。

## Shadow DOM [#shadow-dom]

`<praxis-agent>` 渲染在 **open** Shadow DOM 里：宿主页的样式不会漏进对话，对话的样式也不会影响宿主页。这是样式隔离，**不是安全边界**：open 的 Shadow DOM 可以被页面脚本读取，同一页面上的任何脚本都能访问对话内容。不要把智能体嵌入你不信任的第三方脚本也在运行的页面里，需要强隔离时使用 iframe。

## 内容安全策略（CSP） [#内容安全策略csp]

如果你的页面设置了 CSP，需要放行 Kit 脚本所在的来源，以及 Kit 连接 API 的来源。

| 环境      | 脚本来源（`script-src`）                          | 连接来源（`connect-src`）                 |
| ------- | ------------------------------------------- | ----------------------------------- |
| develop | `https://kit-develop.praxisusercontent.com` | `https://api-develop.deepraxis.com` |
| 生产      | `https://kit.praxisusercontent.com`         | `https://api.deepraxis.com`         |

```http
Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://kit-develop.praxisusercontent.com;
  connect-src 'self' https://api-develop.deepraxis.com;
  frame-src https://chat-develop.praxisusercontent.com;
```

要点：

* `connect-src` 里的 API 地址要和 `setOptions` 的 `api.url` 一致，也就是签发令牌的那个环境。
* 如果你自己托管 Kit 的构建（如快速开始里的 `/praxis-kit.js`），`script-src 'self'` 就够了，不需要放行 CDN。
* Kit 会向 Shadow DOM 里插入 `<style>` 元素（用于主题）。设置了严格 `style-src` 的页面，需要允许内联样式，例如 `style-src 'self' 'unsafe-inline'`。
* 头像、启动图片等你通过选项传入的图片地址，要放行 `img-src`。
* 宿主页面被别人嵌入的保护由宿主自己的 `frame-ancestors` 决定。

## 子资源完整性（SRI） [#子资源完整性sri]

从 CDN 加载时，用**不可变路径**并加上 `integrity`，浏览器会校验文件内容，CDN 被篡改时拒绝执行：

```html
<script
  type="module"
  src="https://kit-develop.praxisusercontent.com/v0.1.0/praxis-kit.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>
```

* `integrity` 的值（`sha384-…`）由发布 Kit 版本时给出，路径里的版本号（`v0.1.0`）对应一次不可变的发布，内容不会改变。
* 必须带 `crossorigin="anonymous"`，否则浏览器不会校验。
* 浮动路径 `https://kit-develop.praxisusercontent.com/v1/praxis-kit.js` 会随新版本更新内容，&#x2A;*不要配 `integrity`**，配了会在下次发布后加载失败。需要锁定内容时请用不可变路径。

## 上线前检查清单 [#上线前检查清单]

* [ ] API Key 只在后端，页面和仓库里找不到。
* [ ] `external_user_id` 来自你的登录态。
* [ ] `allowed_origins` 只有你的站点，生产环境没有开 `allow_localhost`。
* [ ] 令牌有效期合理，登出时撤销令牌。
* [ ] 指令和 `system.message` 里没有秘密。
* [ ] 工具服务端按 `X-Praxis-External-User-Id` 鉴权，并认证调用方。
* [ ] 页面 CSP 放行了 Kit 与 API，CDN 加载使用不可变路径和 SRI。

相关：[工具授权](/docs/cloud/services/agent/embed/tool-authorization) · [令牌与终端用户](/docs/cloud/services/agent/embed/tokens) · [限制与错误](/docs/cloud/services/agent/embed/limits-and-errors)

# 服务型智能体 · 接入与配置

服务型智能体是放进你自己的网站或应用、替你的用户回答问题和办事的智能体。每个智能体有两个工作台：**接入与配置**用来把它做好、接上线；**运营与管理**用来看它跑得怎么样，见[运营与管理](/docs/cloud/services/agent/embed/console-operate)。本页讲前者。

打开 Console，进入「服务型智能体」，点「新建服务型智能体」，或点列表里已有的智能体。页面顶部显示名称、版本徽标（如 v3）、状态标记和短号，短号旁边的按钮可以复制。两个工作台在页签栏左侧切换：「接入与配置」「运营与管理」。接入与配置有五个页签：

| 页签      | 做什么                              | 状态 |
| ------- | -------------------------------- | -- |
| 试用调试    | 在 Console 里直接和智能体对话，模拟终端用户       | 可用 |
| 配置      | 指令、模型、工具、MCP、安全等                 | 可用 |
| 版本      | 查看历史版本，决定嵌入使用哪一版                 | 可用 |
| 接入方式与外观 | 配置 iframe、Hosted，获取 Kit 和 API 示例 | 可用 |
| 密钥      | 签发令牌用的 API key，以及可公开 key         | 可用 |

页面右上角的「发布新版本」会带你到「版本」页签。

## 试用调试 [#试用调试]

先在「配置 · 安全」里保存嵌入策略，才能试用；没有策略时页面会提示「先在『配置 → 安全』里设置嵌入策略，才能试用」，点「去配置」直达。

* **形态**：顶部的 `inline`、`popup`、`sidebar`、`modal` 切换智能体在页面里的样子，与网站嵌入时的布局一一对应。
* **版本**：下拉选择试用哪一版，默认是嵌入策略固定的版本，没有固定则是最新版。切换版本会重新签发令牌并开始新对话。
* **调试面板**有三个页签：
  * 「上下文」：当前版本的指令（只读）和宿主传入的上下文（host\_context）。「页面上下文」可添加、删除名称和值，每条用户消息会带上这些内容。
  * 「事件」：嵌入组件触发的事件列表（ready、error、thread.change、response.start、response.end、open、close 等），点一条展开详情。
  * 「模拟」：填写 external\_user\_id 和 system\_message，点「重新签发」，用这个身份开始新对话。用来检查「不同用户看到不同内容」。

期望：点「重新签发」后对话区重置，「上下文」页签里 host\_context 显示你填的 system\_message，「事件」页签出现 ready 事件。这与你的后端签发令牌是同一件事，见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)。

## 配置 [#配置]

左侧是配置分组，右侧是内容。

| 分组      | 内容                                       |
| ------- | ---------------------------------------- |
| 基本      | 名称、描述、注册号、智能体 ID，以及配置版本列表                |
| 指令      | 角色、口吻、回答范围                               |
| 模型      | 使用的模型                                    |
| 工具与授权   | 启用哪些工具，以及每个工具的授权方式：「自动执行」或「每次询问」         |
| MCP 与凭据 | 智能体连接的 MCP 服务器，以及可用的凭据库                  |
| 开场与外观   | 此配置入口仍为占位；请到「接入方式与外观 → iframe」保存外观       |
| 安全      | 运行环境、来源白名单、令牌与预算、限流、封禁名单入口               |
| 暂不支持    | 服务型智能体暂不支持的能力：按消息切换模型、工具模式、语音输入、按终端用户的记忆 |

### 保存与版本 [#保存与版本]

「基本」「指令」「模型」「工具与授权」「MCP 与凭据」里的修改是一份草稿，页面底部的保存栏会列出改动过的分组。点保存会生成**新版本**；已固定版本的嵌入不会自动升级，见下文「版本」。离开页面前有未保存的改动会提示。

「安全」和「凭据库」是另外保存的：各有自己的保存按钮，保存后显示「已保存，不产生新版本」。

### 工具与授权 [#工具与授权]

「授权方式」列出已启用的工具，每个选「自动执行」或「每次询问」。每次询问会在对话里弹出确认卡。**询问确认只是帮终端用户确认意图，不是安全手段**，工具应按终端用户在服务端鉴权，见[工具授权](/docs/cloud/services/agent/embed/tool-authorization)。MCP 服务器可以设置默认授权，也可以逐个工具设置。

### MCP 与凭据 [#mcp-与凭据]

在这里添加智能体要调用的 MCP 服务器。页面上的说明提醒：平台调用 MCP 时会附带 `X-Praxis-External-User-Id`、`X-Praxis-Agent-Id`、`X-Praxis-Session-Id` 三个请求头，工具应据此按终端用户鉴权。

下方「凭据库」勾选后保存：会话按凭据的「允许的主机」或 MCP 地址自动匹配凭据来调用 MCP 服务器。还没有创建嵌入策略时，这里会提示先到「安全」创建。

### 安全 [#安全]

这是嵌入策略，决定谁能签发令牌、令牌能做什么。

| 字段                | 含义                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------ |
| 运行环境（必填）          | 智能体会话运行所在的环境。下拉里没有选项时显示「暂无可用运行环境」                                                          |
| 来源白名单             | 允许嵌入的网站来源，点「添加来源」逐个填写，需为 https，如 `https://example.com`，也可用 `https://*.example.com`；最多 50 个 |
| 允许 localhost      | 仅开发调试用                                                                                     |
| 令牌有效期默认值 / 上限（分钟） | 签发时不指定则用默认值，不能超过上限                                                                         |
| 每会话预算默认值 / 上限（元）  | 单个会话最多花多少                                                                                  |
| 允许宿主覆盖指令          | 打开后，宿主后端签发令牌时可以替换该令牌的指令                                                                    |
| 月度上限（元）           | 留空表示不限                                                                                     |
| 触顶动作              | 「停止新会话」或「只告警」                                                                              |
| 单个终端用户的活跃会话上限     | 同一终端用户正在运行的会话数；空闲的历史会话不计入                                                                  |
| 每分钟请求上限           | 每个终端用户                                                                                     |
| 封禁名单              | 显示被封禁的人数，在「运营与管理 · 终端用户」里管理                                                                |

第一次保存会创建嵌入策略；没有策略时不能签发令牌。每一项的详细含义见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)和[安全](/docs/cloud/services/agent/embed/security)。

## 版本 [#版本]

「版本」页签左侧是版本列表：版本号、创建时间、相对上一版的改动摘要，当前被嵌入使用的那一版带「嵌入中」标记。点版本号 vN，右侧显示它与上一版的对比。

嵌入使用哪一版由嵌入策略决定：

* **未固定**：列表顶部显示「未固定，跟随最新」，之后新签发的令牌用最新版本。
* **固定**：点某一版右侧的「设为嵌入版本」（最新版）或「回滚到此版本」（更早的版本），确认后新签发的令牌使用这一版。已固定时，列表顶部出现「取消固定」，确认后恢复跟随最新。

**已经签发的令牌不变**：确认框里会写明「已签发的令牌不变」，旧令牌到期前仍使用签发时的版本。没有嵌入策略时这些按钮不可用，页面会提示先到「配置 · 安全」设置。「近 7 天会话数」一列目前显示「—」。

## 接入方式与外观 [#接入方式与外观]

进入「接入方式与外观 → iframe」，在实时预览旁调整外观，点「保存」。期望：显示「已保存，嵌入页刷新后生效」，刷新宿主页面验证。未配置来源白名单时，iframe 会被所有网站拒绝，请先到「配置 → 安全」设置。

保存的外观作用于 iframe 与 Hosted。Kit 组件的外观写在宿主代码里。Hosted 页签提供「打开预览」和后端跳转示例；接入代码见[嵌入方式](/docs/cloud/services/agent/embed/methods)。

### 可保存的外观 [#可保存的外观]

| 设置      | 字段                                                                                                   |
| ------- | ---------------------------------------------------------------------------------------------------- |
| 智能体与顶栏  | `agent.name`、`agent.avatar`；`header.title`、`header.subtitle`、`header.icon`                           |
| 布局与启动按钮 | `layout`：inline/sidebar/popup/modal；`launcher.type`：none/bubble/mascot，以及 `image`、`position`、`label` |
| 主题      | `theme.colorScheme`、`accent`、`surface`、`grayscale`、`radius`、`density`、`fontFamily`、`fontSize`        |
| 语言      | `locale`：`zh` 或 `en`；未设置时 iframe 与 Hosted 跟随浏览器语言                                                    |
| 开场与输入框  | `startScreen.greeting`、`startScreen.prompts`（label/prompt 对）、`composer.placeholder`                  |
| 其他      | `disclaimer`、`footer`、`history.enabled`                                                              |

图片（`agent.avatar`、`header.icon`、`launcher.image`）必须使用 HTTPS。保存对象最多 8 KB；名称最多 40 字符，问候语 200 字符；推荐问题最多 4 个，每个标签最多 40 字符、问题最多 200 字符；输入框占位文字最多 80 字符，免责声明 200 字符，页脚 120 字符。保存外观不能包含凭据或可执行回调。

`GET /agent/v1/embed/appearance` 通过嵌入令牌或可公开 key 确定智能体并读取外观，不接受智能体 ID、短号或其他寻址参数；嵌入令牌放在 `Authorization: Bearer <token>`，可公开 key 放在 `Praxis-Publishable-Key: PRAXIS_API_KEY`（占位符）；组织 API Key 不能通过此端点读取。未保存外观时返回 `{}`。iframe 与 Hosted 页会自动加载。

## 密钥 [#密钥]

**签发令牌用的 API key**：你的后端用 API key 为自己的登录用户签发嵌入令牌，key 只放在服务器上。页面给出一个签发示例命令和「复制」按钮，旁边「去 API Keys 创建」带你去创建 key。下方「最近用于签发本智能体令牌的 key」基于最近 50 条签发记录，显示每个 key 最近一次用于签发的时间和次数；还没有时显示「还没有用 API key 签发过」。

**可公开 key**：这一栏可以新建、编辑、停用、启用和删除可公开 key，并设置名称、匿名每分钟上限、单会话预算、每日会话数上限和每日花费上限（金额单位为元，留空表示不限）。新建后完整的 key 值**只显示一次**，请立即复制。可公开 key 可以出现在网页源码里，保护依赖「配置 · 安全」的来源白名单和这里的各项上限。匿名访客可通过 `POST /agent/v1/embed_tokens/anonymous` 换取令牌，见[嵌入令牌](/docs/cloud/services/agent/embed/tokens)。可公开 key 与服务器上的 API Key 是两种凭据。

期望：新建可公开 key 后弹出「只显示这一次」对话框，列表里出现这把 key 的前缀、状态「启用」和各项上限。

下一步：[运营与管理](/docs/cloud/services/agent/embed/console-operate) · [嵌入到网页](/docs/cloud/services/agent/embed/quickstart)

# 服务型智能体 · 运营与管理

智能体上线之后，在「运营与管理」工作台看它跑得怎么样，并处理个别用户的问题。打开 Console「服务型智能体」，选中一个智能体，点页签栏左侧的「运营与管理」。五个页签：

| 页签    | 做什么                  | 状态 |
| ----- | -------------------- | -- |
| 概览    | 会话量、活跃用户、好评率、来源和版本分布 | 可用 |
| 会话    | 按终端用户、来源筛选会话，回放对话    | 可用 |
| 终端用户  | 查看用户，吊销令牌、封禁、解封      | 可用 |
| 用量与预算 | 花费与预算                | 可用 |
| 签发记录  | 谁在什么时候签发了令牌，吊销令牌     | 可用 |

接入与配置见[接入与配置](/docs/cloud/services/agent/embed/console-integrate)。

## 概览 [#概览]

右上角选时间范围：24 小时、7 天、30 天。

* **指标**：会话、活跃终端用户、花费、每会话花费、好评率、首字延迟 P50、错误率。没有对应样本时显示「—」。首字延迟、错误率、工具调用与需要关注的计数来自平台统计，无需配置 Observability。
* **会话量**：24 小时按小时、其余按天的趋势图。没有会话时显示「暂无会话」。
* **来源分布**：会话来自哪里——嵌入 · Kit 组件、嵌入 · iframe、托管对话页、API、自动化。
* **版本分布**：各版本的会话数和占比，当前版本带「当前版本」标记。想看新版本发布后流量是否切过去，用它。
* **花费趋势**：24 小时按小时，其余按天。
* **需要关注**：所选时间范围内的「来源被拦」「预算触顶」次数。
* **工具调用 Top 5**：按调用次数显示工具排行；没有调用时显示「暂无工具调用」。

## 会话 [#会话]

列表列出这个智能体的所有会话：标题、终端用户、来源、版本、最后活跃和状态（空闲、运行中、重试中、已结束、已归档）。消息数、花费、反馈三列目前显示「—」。

* **筛选**：输入终端用户 ID 点「筛选」，或在「来源」下拉选 Kit、iframe、托管页面、API、自动化。
* **回放**：点一行，右侧展开只读的对话回放，头部显示终端用户、来源、版本和创建时间。回放里不能发送消息，也不会改动会话。
* **归档**：回放头部的「归档」会让会话不能再继续发送消息，对话记录仍可查看，需确认。
* 列表较长时点「加载更多」。

期望：点开一个会话，右侧出现完整对话；点「关闭回放」收起。

## 终端用户 [#终端用户]

终端用户是宿主在签发令牌时给出的 `external_user_id`。表格列出终端用户 ID、首次出现、最后活跃、会话数、花费和状态（正常或已封禁），可按用户 ID 前缀搜索。点用户 ID 打开详情抽屉，里面有基本信息和最近会话，点最近会话会跳到「会话」页签。

每行有两个操作，点后都会弹出确认框：

| 操作   | 效果                                                |
| ---- | ------------------------------------------------- |
| 吊销令牌 | 吊销该用户当前所有有效令牌，正在进行的对话会被中断；宿主可以重新签发。完成后提示「已吊销 N 张」 |
| 封禁   | 宿主之后为该用户签发新令牌会被拒绝，现有令牌立即吊销。状态变为「已封禁」              |
| 解封   | 宿主可以再次为该用户签发令牌                                    |

已封禁的用户行上显示「解封」，其余显示「封禁」。「配置 · 安全」里显示的封禁人数与这里一致，封禁名单在这里管理。被封禁用户的签发请求会收到 `EMBED_USER_BLOCKED`，见[限制与错误](/docs/cloud/services/agent/embed/limits-and-errors)。

## 用量与预算 [#用量与预算]

页面显示本月花费、月度上限与触顶动作、7/30/90 天的每日花费、预算与限流、本月来源拆分，以及花费最高的终端用户 Top 20。本月统计按 UTC 自然月计算。点「修改上限」进入「配置 · 安全」。「花费构成」仍显示「即将上线」。

## 签发记录 [#签发记录]

每次宿主后端签发嵌入令牌都会留下一条记录：签发时间、终端用户、版本、签发者（成员或 API Key，显示前 8 位）、来源 origin、过期时间和状态（有效、已过期、已吊销）。记录里不包含令牌本身。

* 按终端用户 ID 筛选，点「筛选」；在「状态」下拉选全部、有效、已过期或已吊销。
* 有效的令牌右侧有「吊销」：确认后这张令牌立刻失效，正在进行的对话被中断，宿主可以重新签发，页面提示「令牌已吊销。」。只吊销这一张，同一用户的其他令牌不受影响；要一次吊销某个用户的全部令牌，用「终端用户」页签。
* 还没有记录时显示「还没有签发记录」，宿主通过 API 签发令牌后会出现在这里。

签发记录是排查「用户说打不开」的第一站：先找到该用户最近一条记录，看状态是不是已过期或已吊销，再看来源 origin 是否在来源白名单里。

下一步：[接入与配置](/docs/cloud/services/agent/embed/console-integrate) · [嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)

# 组件参考

`<praxis-agent>` 是一个 Web Component，把智能体对话界面嵌入你的页面。本页列出它的选项、方法和事件，以及对应的 React 组件。

## 选项 [#选项]

通过 `setOptions` 传入。首次调用必须包含 `api.url`、`api.getToken` 和 `agent.name`，缺任何一项会抛出 `TypeError`。

| 选项                             | 类型                                             | 说明                                                                  |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------- |
| `api.url`                      | `string`                                       | 接口地址，必填。初始化后不能更改，否则抛出 `TypeError`；换后端请新建元素。                         |
| `api.getToken`                 | `(current: string \| null) => Promise<string>` | 必填。返回嵌入令牌。`current` 是当前令牌，首次为 `null`；令牌到期前会再次调用。                    |
| `agent.name`                   | `string`                                       | 必填。显示的智能体名称。                                                        |
| `agent.avatar`                 | `string`                                       | 头像地址。                                                               |
| `layout`                       | `"inline" \| "sidebar" \| "popup" \| "modal"`  | 默认 `inline`。                                                        |
| `launcher`                     | 见下表                                            | 默认：`inline` 为 `none`，其余布局为 `bubble`。                                |
| `header`                       | 见下表                                            | 顶栏内容。                                                               |
| `history.enabled`              | `boolean`                                      | 默认开启。设为 `false` 后隐藏历史会话入口，`showHistory()` 不再生效。                     |
| `width`                        | `number`                                       | `sidebar` 布局的宽度，单位 CSS 像素，默认 400。                                   |
| `theme`                        | 见下表                                            | 外观。                                                                 |
| `startScreen`                  | 见下表                                            | 空会话时的开场。                                                            |
| `composer.placeholder`         | `string`                                       | 输入框占位文字，默认「发送消息」。                                                   |
| `composer.attachments.enabled` | `boolean`                                      | 默认开启。设为 `false` 后不能选择、粘贴或拖入文件。                                      |
| `disclaimer`                   | `string`                                       | 对话区的免责声明。                                                           |
| `footer`                       | `string`                                       | 对话区底部的文字。                                                           |
| `autoScroll`                   | `boolean`                                      | 控制新内容到达时是否自动滚动。                                                     |
| `locale`                       | `"zh" \| "en"`                                 | 界面语言。未指定时先取宿主页面的 `lang`，再取浏览器语言；`zh` 开头的语言标签使用中文，其余使用英文，无语言信息时使用英文。 |

### launcher [#launcher]

| 字段         | 类型                                | 说明      |
| ---------- | --------------------------------- | ------- |
| `type`     | `"none" \| "bubble" \| "mascot"`  | 必填。     |
| `image`    | `string`                          | 图片地址。   |
| `position` | `"bottom-right" \| "bottom-left"` | 启动按钮位置。 |
| `label`    | `string`                          | 按钮文字。   |

### header [#header]

| 字段         | 类型                                              | 说明                                                        |
| ---------- | ----------------------------------------------- | --------------------------------------------------------- |
| `title`    | `string`                                        | 标题。                                                       |
| `subtitle` | `string`                                        | 副标题。                                                      |
| `icon`     | `string`                                        | 受支持的 Lucide 图标名，或图片地址。                                    |
| `actions`  | `{ id: string; icon: string; label: string }[]` | 自定义顶栏按钮。点击时触发 `praxis.header.action`，`detail` 为 `{ id }`。 |

### theme [#theme]

| 字段            | 类型                                         | 说明                                                                              |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| `colorScheme` | `"light" \| "dark" \| "system"`            | `system` 跟随浏览器的深浅色设置。                                                           |
| `accent`      | `string`                                   | 主色。必须是不透明的明确 CSS 颜色；含 `var()`、`currentcolor` 等不被接受，会抛出 `TypeError`。前景色按对比度自动选择。 |
| `surface`     | `string`                                   | 背景色，限制同 `accent`。                                                               |
| `grayscale`   | `"neutral" \| "warm" \| "cool"`            | 灰阶色板。                                                                           |
| `radius`      | `"none" \| "sm" \| "md" \| "lg" \| "full"` | 圆角，分别对应 0、4、10、18、9999 像素。                                                      |
| `density`     | `"compact" \| "normal" \| "spacious"`      | 间距，基础单位分别为 3、4、5 像素。                                                            |
| `fontFamily`  | `string`                                   | 字体族。空字符串或含 `; { } < >` 会抛出 `TypeError`。                                         |
| `fontSize`    | `number`                                   | 基础字号，单位像素，必须为正的有限数，否则抛出 `RangeError`。                                           |

未设置 `accent` 时使用默认绿色（浅色 `#167A43`，深色 `#30a46c`）。

### startScreen [#startscreen]

| 字段         | 类型                                    | 说明                               |
| ---------- | ------------------------------------- | -------------------------------- |
| `greeting` | `string`                              | 问候语。                             |
| `prompts`  | `{ label: string; prompt: string }[]` | 推荐问题。最多显示前 4 个；点击后立即发送 `prompt`。 |

## 更新选项 [#更新选项]

`setOptions(partial)` 把传入的字段合并进当前配置：嵌套对象逐层合并，数组整体替换，显式传 `undefined` 会重置该字段。`api.url` 不能改。

## 方法 [#方法]

在元素上直接调用。

| 方法                                | 说明                                                                                                               |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `setOptions(partial)`             | 初始化或更新选项。                                                                                                        |
| `sendUserMessage(text)`           | 以用户身份发送一条消息，返回 `Promise`，值为 `"accepted"`、`"rejected"` 或 `"unknown"`。文本为空或超长、有待处理的审批、历史仍在加载、输入框不可用时返回 `rejected`。 |
| `setComposerValue(text)`          | 替换输入框中的草稿。                                                                                                       |
| `focusComposer()`                 | 聚焦输入框。历史面板打开时不生效。                                                                                                |
| `setThreadId(id)`                 | 切换到指定会话；传 `null` 回到空会话。同时关闭历史面板，会话变化时触发 `praxis.thread.change`。                                                  |
| `showHistory()` / `hideHistory()` | 打开或关闭历史面板。                                                                                                       |
| `open()` / `close()` / `toggle()` | 展开或收起面板。`inline` 布局下没有效果。                                                                                        |

## 事件 [#事件]

事件都是冒泡、可穿过 Shadow DOM 的 `CustomEvent`。

| 事件                                             | `detail`                           | 何时触发                                                                                                                                                  |
| ---------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `praxis.ready`                                 | 无                                  | 界面已挂载。不代表网络认证已成功。                                                                                                                                     |
| `praxis.error`                                 | `KitError` 或 `{ message: string }` | 传输失败时为 `KitError`（含 `code`、`status`、`retryable`、`message`）；会话加载或发送失败时为 `{ message }`。错误码见[限制与错误](/docs/cloud/services/agent/embed/limits-and-errors)。 |
| `praxis.thread.change`                         | `{ threadId: string \| null }`     | 当前会话变化，包括首条消息创建出新会话。                                                                                                                                  |
| `praxis.response.start`                        | 无                                  | 智能体开始回复。                                                                                                                                              |
| `praxis.response.end`                          | 无                                  | 回复结束。                                                                                                                                                 |
| `praxis.open` / `praxis.close`                 | 无                                  | 面板展开或收起。                                                                                                                                              |
| `praxis.history.open` / `praxis.history.close` | 无                                  | 历史面板打开或关闭。                                                                                                                                            |
| `praxis.header.action`                         | `{ id: string }`                   | 点击了 `header.actions` 中的按钮。                                                                                                                            |

```js
const agent = document.querySelector("praxis-agent");
agent.addEventListener("praxis.thread.change", event => {
  console.log(event.detail.threadId);
});
```

## React [#react]

React 组件来自 `@deepractice-ai/praxis-kit-react`，需要 React 18 或 19。

```tsx
import { PraxisAgent, usePraxisAgent } from "@deepractice-ai/praxis-kit-react";

export function Chat({ options, getToken }) {
  const { ref, control } = usePraxisAgent();
  return (

# 嵌入的限制与错误

本页列出嵌入时会碰到的上限和错误码。标注「策略」的值由你为智能体配置的嵌入策略决定，其余是平台固定值。

## 上限 [#上限]

### 签发令牌 [#签发令牌]

| 项目                  | 限制                                                                        |
| ------------------- | ------------------------------------------------------------------------- |
| 令牌有效期 `ttl_seconds` | 60 到 3600 秒。不传时用策略的默认值，且不能超过策略的有效期上限（`ttl_max_seconds`，同样在 60 到 3600 之间）。 |
| `external_user_id`  | 1 到 128 个字符，只能包含字母、数字和 `_ . : @ -`。                                       |
| `system_message`    | 文本块总计不超过 8192 字节（UTF-8）。                                                  |
| `metadata`          | 最多 16 个键；键 1 到 64 个字符，值为不超过 512 个字符的字符串。                                  |
| 会话预算 `budget_cents` | 0 到策略的会话预算上限；不传时用策略的默认值。                                                  |
| `allowed_origins`   | 必须是策略 `allowed_origins` 的子集。                                              |

### 策略 [#策略]

| 项目                                          | 限制                                                                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 来源白名单 `allowed_origins`                     | 最多 50 条。只接受 `https` 来源；通配写法 `https://*.example.com` 只匹配一级子域名，不含端口。开启 `allow_localhost` 后额外允许 `http://localhost` 和 `http://127.0.0.1`。 |
| 每个终端用户的活跃会话数 `max_active_sessions_per_user` | 1 到 100。只计运行中的会话，不计空闲的历史会话。                                                                                                           |
| 每个终端用户每分钟请求数 `per_user_rate_per_min`        | 1 到 600。                                                                                                                              |
| 被封禁的终端用户 `blocked_end_users`                | 最多 1000 个。                                                                                                                            |
| 月度上限 `monthly_cap_cents`                    | 以分计；`null` 表示不设上限。                                                                                                                    |
| 触顶动作 `on_cap`                               | `stop_new_sessions`：拒绝新建会话，返回 `EMBED_MONTHLY_CAP_REACHED`；`alert_only`：只告警，不拦截。                                                       |

月度花费按 UTC 自然月统计。

### 会话与消息 [#会话与消息]

| 项目                         | 限制                                                                             |
| -------------------------- | ------------------------------------------------------------------------------ |
| 附件                         | 每条消息最多 5 个，单个不超过 10 MB。只支持内联：PNG、JPEG、GIF、WebP 作为图片，PDF、TXT、MD 作为文档，不会上传为会话文件。 |
| 推荐问题 `startScreen.prompts` | 最多显示 4 个。                                                                      |
| 会话标题                       | 不超过 500 个字符。                                                                   |
| 创建会话时的初始事件                 | 最多 50 条，只能是纯文本的用户消息。                                                           |
| 会话预算                       | 达到令牌上的 `budget_cents` 后，会话不再接受新的工作，只接受工具确认和中断。                                 |

## 错误 [#错误]

错误从两处到达页面：接口返回的错误体，以及 Kit 自身产生的错误。传输错误通过 `praxis.error` 事件的 `detail` 交给你，字段为 `code`、`status`、`retryable` 和 `message`；会话加载或发送失败可能只有 `message`，按错误码分支前先检查 `code` 是否存在。

### EMBED\_\* 错误码 [#embed_-错误码]

| 错误码                         | HTTP | 含义                                                        | 可重试 | 建议处理                                                                                          |
| --------------------------- | ---- | --------------------------------------------------------- | --- | --------------------------------------------------------------------------------------------- |
| `EMBED_TOKEN_EXPIRED`       | 401  | 令牌已过期。                                                    | 否   | Kit 会自动调用 `getToken` 换新令牌并重试一次；持续出现说明你的令牌服务返回了已过期的令牌。                                         |
| `EMBED_TOKEN_REVOKED`       | 401  | 令牌已被吊销。                                                   | 否   | Kit 不再刷新，对话进入终止状态。让用户重新进入页面，由你的服务重新签发。                                                        |
| `EMBED_ORIGIN_NOT_ALLOWED`  | 403  | 页面来源不在白名单内。                                               | 否   | 把页面来源加入策略的 `allowed_origins`，并确认签发令牌时的 `allowed_origins` 包含它。                                 |
| `EMBED_USER_BLOCKED`        | 403  | 该终端用户被封禁。                                                 | 否   | 在策略的 `blocked_end_users` 中确认并移除，或提示用户联系你。                                                     |
| `EMBED_RATE_LIMITED`        | 429  | 每分钟请求数或同时运行的会话数超限，或达到匿名每日会话上限。                            | 是   | 请求限流时稍后重试；并发超限时等待运行结束或中断运行，或调高 `max_active_sessions_per_user`。归档空闲历史不会释放运行名额；每日上限在下个 UTC 日恢复。 |
| `EMBED_BUDGET_EXHAUSTED`    | 402  | 会话预算耗尽，或达到匿名每日花费上限。                                       | 否   | 会话预算耗尽时开始新会话，或调高签发时的 `budget_cents`；匿名每日上限需等待额度恢复。                                            |
| `EMBED_MONTHLY_CAP_REACHED` | 402  | 月度上限已到，且触顶动作为 `stop_new_sessions`。                        | 否   | 调高 `monthly_cap_cents`，或把 `on_cap` 改为 `alert_only`；下个 UTC 月自动恢复。                              |
| `EMBED_FIELD_NOT_ALLOWED`   | 400  | 创建会话时带了嵌入令牌不允许的字段，或初始事件格式不被允许；也用于策略不允许的 `agent_override`。 | 否   | 只传标题、时区和纯文本的初始用户消息。                                                                           |

### 相关的通用错误码 [#相关的通用错误码]

| 错误码                                                                          | HTTP | 含义                                                                                    | 可重试 |
| ---------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------- | --- |
| `INVALID_PARAMS`                                                             | 400  | 请求参数不合法，信息会指出是哪个字段，例如 `Invalid external_user_id`、`system_message exceeds 8192 bytes`。 | 否   |
| `NOT_FOUND`                                                                  | 404  | 授权、策略或请求的资源不存在或不可访问；Hosted 凭证无效、过期或已使用也返回此码。                                          | 否   |
| `UNAUTHENTICATED`                                                            | 401  | 凭证缺失或无效，包括已停用的可公开 key。                                                                | 否   |
| `AGENT_NOT_FOUND` / `SESSION_NOT_FOUND`                                      | 404  | 找不到智能体或会话。                                                                            | 否   |
| `SESSION_FORBIDDEN` / `PERMISSION_DENIED` / `READ_ONLY`                      | 403  | 调用方无权执行此操作；终端用户的资源隔离也可能以 404 隐藏资源。                                                    | 否   |
| `INVALID_STATE` / `SESSION_CONFLICT` / `AGENT_ARCHIVED` / `SESSION_ARCHIVED` | 409  | 智能体或会话当前状态不允许此操作。                                                                     | 否   |
| `INVALID_PAGE_TOKEN`                                                         | 400  | 分页或事件游标无效。                                                                            | 否   |
| `EVENT_CONTENT_UNAVAILABLE`                                                  | 404  | 事件内容不可用。                                                                              | 否   |
| `EVENT_CONTENT_CORRUPT`                                                      | 500  | 存储的事件内容无法正确读取。                                                                        | 否   |
| `UPSTREAM_UNAVAILABLE`                                                       | 502  | 上游服务不可用。                                                                              | 是   |
| `INTERNAL`                                                                   | 500  | 未分类的服务端错误。                                                                            | 否   |

### Kit 自身产生的错误码 [#kit-自身产生的错误码]

这些错误没有对应的接口响应，`status` 为 0 或接口状态码。

| 错误码                      | 含义                                    | 可重试  |
| ------------------------ | ------------------------------------- | ---- |
| `network_error`          | 网络请求失败。                               | 是    |
| `http_error`             | 响应不是已知的错误体。`status` 为 429 或 5xx 时可重试。 | 视状态码 |
| `invalid_token`          | `getToken` 返回了空令牌。                    | 是    |
| `invalid_response`       | 响应不是合法 JSON，或历史分页没有前进。                | 否    |
| `invalid_stream`         | 事件流不是 SSE，或某条数据不是合法 JSON。             | 否    |
| `stream_disconnected`    | 事件流在没有取消的情况下中断。Kit 最多重连 5 次。          | 是    |
| `event_cursor_not_found` | 历史中找不到续传位置。                           | 否    |
| `callback_error`         | 事件回调抛出了异常。                            | 否    |
| `aborted` / `disposed`   | 操作被取消，或元素已移除。                         | 否    |

`getToken` 失败时，Kit 按 1、2、4 秒的间隔最多重试 3 次，之后令牌状态变为过期并发出 `praxis.error`。

## 暂不支持 [#暂不支持]

以下能力在嵌入里尚未提供：

* 按消息切换模型
* 工具模式
* 语音输入
* entities、commands、widgets
* 按终端用户的记忆

# 概念

（待补充）

# 指南

（待补充）

# 限制与错误

（待补充）

# 自动化

自动化把平台能力组合成脚本或工作流，由你主动运行，或由触发器自动启动。

| 对象  | 用途                                |
| --- | --------------------------------- |
| 脚本  | 一段 TypeScript 从头执行到尾，返回一个结果。      |
| 工作流 | YAML 描述的多步骤流程，保存检查点，支持等待和暂停。      |
| 动作  | 有输入输出约定的可复用能力，由脚本或工作流调用。          |
| 运行  | 一次脚本或工作流的执行，记录输入、输出、状态和调用。        |
| 触发器 | 在指定时间或收到 webhook 时启动一个已发布的脚本或工作流。 |

## 选择入口 [#选择入口]

一次计算、批量处理或组合 API 调用，用脚本；跨时间等待、需要步骤检查点的任务，用工作流。把多个编排都会使用的能力封装成动作。动作没有独立运行入口，在脚本或工作流里调用它。

脚本失败后重跑会重新执行整段代码；已发生的效果不会回滚。需要自动执行时，在已发布目标上配置触发器。

## 先运行一次 [#先运行一次]

在 [Develop Console](https://console-develop.deepraxis.ai/keys) 创建 API Key，设置为 `PRAXIS_API_KEY`。在装有 curl 和 jq 的 Bash 中执行，使用 Bearer 认证完成一次加一计算，不调用模型：

```bash
export PRAXIS_API_URL="https://api-develop.deepraxis.ai"
: "${PRAXIS_API_KEY:?Set PRAXIS_API_KEY to your develop API Key}"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"source":"export default async (input: { n: number }) => ({ answer: input.n + 1 });","language":"ts","input":{"n":41},"wait":60}' \
  | jq '{id,status,output,error}'
```

期望：`status` 为 `completed`，`output` 为 `{"answer":42}`。若仍在排队或运行，将返回的 `id` 存为 `RUN_ID`，再[读取结果](/docs/cloud/services/automation/quickstart#read-result)。继续按[快速开始](/docs/cloud/services/automation/quickstart)保存和发布脚本。

## 下一步 [#下一步]

* [快速开始](/docs/cloud/services/automation/quickstart)：用 curl 得到第一个结果，再发布脚本。
* [概念](/docs/cloud/services/automation/concepts)：版本、运行树、幂等与费用。
* [编写脚本](/docs/cloud/services/automation/guides/write-script)：输入输出、平台能力、动作和日志。
* [触发器](/docs/cloud/services/automation/guides/triggers)：定时与 webhook。
* [限制与错误](/docs/cloud/services/automation/limits-and-errors)：容量、超时和排错。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 快速开始

本教程使用 develop、Bash、curl 和 jq。所有命令在同一个 Bash 会话中按顺序执行；不需要安装 SDK。脚本只做加法，不调用计费能力。

<a id="environment" />

## 1. 创建 API Key [#1-创建-api-key]

打开 [Develop Console → API Keys](https://console-develop.deepraxis.ai/keys)，创建 Key，并将其保存到环境变量 `PRAXIS_API_KEY`。Key 的管理说明见[平台管理](/docs/cloud/account)。

```bash
export PRAXIS_API_URL="https://api-develop.deepraxis.ai"
: "${PRAXIS_API_KEY:?Set PRAXIS_API_KEY to your develop API Key}"
command -v curl
command -v jq
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs?limit=1" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -e '.data | type == "array"'
```

期望：两个命令都能找到，最后输出 `true`，退出码为 0；这同时验证 Key 能访问自动化运行列表。

<a id="run-source" />

## 2. 临时运行脚本 [#2-临时运行脚本]

[创建运行](/docs/api/native/automation/createRun)接受源码和输入。`wait` 表示本次 HTTP 请求等待运行终态的最长秒数，范围 0–60，默认 0。`wait: 60` 最多等待 60 秒，运行提前结束就提前返回；等待结束不会取消运行。HTTP 200 表示已到终态（也可能失败），202 表示仍在排队或执行，两者都要检查 `status`。

```bash
SOURCE='export default async (input: { n: number }) => ({ answer: input.n + 1 });'
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg source "$SOURCE" \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
jq -e '.id | startswith("run_")' <<< "$RUN"
```

期望：输出 `true`，`RUN_ID` 是新运行的 ID。源码接收 `n: 41`，返回 `answer: 42`。

HTTP 202 的响应仍是 Run 对象。下面是字段节选（`id` 以实际响应为准）：

```json
{
  "id": "run_...",
  "status": "running",
  "output": null,
  "error": null
}
```

保留 `RUN_ID`，按下一节 GET `/automation/v1/runs/$RUN_ID`，直到 `completed`、`faulted` 或 `cancelled`。不要因为等待结束就重复创建运行。

<a id="read-result" />

## 3. 读结果 [#3-读结果]

用[读取运行](/docs/api/native/automation/getRun)检查终态。下面的函数在约 3 分钟内轮询；脚本失败时打印真实错误并返回非零退出码。

```bash
read_result() {
  local result
  for attempt in $(seq 1 90); do
    result=$(curl --fail-with-body -sS \
      "$PRAXIS_API_URL/automation/v1/runs/$1" \
      -H "Authorization: Bearer $PRAXIS_API_KEY") || return 1
    case "$(jq -r '.status' <<< "$result")" in
      completed) jq -e '.output.answer == 42' <<< "$result"; return $? ;;
      faulted|cancelled) jq '{status,error}' <<< "$result"; return 1 ;;
    esac
    sleep 2
  done
  echo 'Still pending: retrieve the run again using its ID' >&2
  return 1
}
read_result "$RUN_ID"
```

期望：输出 `true` 且退出码为 0，证明运行已 `completed`，输出确实为 42。若仍未完成，保留 `RUN_ID`，再次读取；不要因为客户端等待结束就重复创建运行。

<a id="publish-script" />

## 4. 保存为脚本并发布 [#4-保存为脚本并发布]

把同一份源码保存为[脚本草稿](/docs/api/native/automation/createScript)，读取当前 `draft.revision` 后[发布版本](/docs/api/native/automation/publishScriptVersion)。每次教程使用不同的名称。

命名空间由你自行取名，例如自己的项目名。下面的 `docs-samples` 只是示例；修改 `NAMESPACE` 后，后续请求会使用同一个命名空间。

```bash
NAMESPACE="docs-samples"
SCRIPT_NAME="hello-$(date +%s)-$RANDOM"
SCRIPT=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/scripts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg namespace "$NAMESPACE" --arg name "$SCRIPT_NAME" --arg source "$SOURCE" \
    '{namespace:$namespace,name:$name,draft:$source}')")
jq -e '.id | startswith("scr_")' <<< "$SCRIPT"
DRAFT=$(curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq -er '.draft.revision')
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/scripts/$NAMESPACE/$SCRIPT_NAME/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg revision "$DRAFT" \
    '{version:"1.0.0",expected_draft_revision:$revision}')" \
  | jq -e '.version == "1.0.0"'
```

期望：两次检查均输出 `true`；版本 `1.0.0` 已发布。若返回 `PRECONDITION_FAILED`，报错原文「草稿已修改」，重新读取草稿，确认内容后用最新 revision 发布。

<a id="run-version" />

## 5. 按版本运行 [#5-按版本运行]

```bash
TARGET="$NAMESPACE/$SCRIPT_NAME@1.0.0"
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" \
    '{target:$target,input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"
```

期望：再次输出 `true`，结果仍为 42。保留 `TARGET`，下一步可以给它[添加触发器](/docs/cloud/services/automation/guides/triggers)。用完后可[归档脚本](/docs/api/native/automation/archiveScript)；归档会保留名称和历史。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 概念

脚本和工作流描述要做什么；运行记录某一次执行；触发器决定何时执行。动作是执行期间调用的可复用能力。

## 定义、版本与标签 [#定义版本与标签]

脚本与工作流共用 `namespace/name`，一个名字只能属于其中一种。草稿可以修改；发布的版本不可变，版本号不能复用。同版本同内容再次发布会返回已有版本。弃用版本保留历史，不等于删除。

版本和 dist-tag 遵循 npm 的引用方式：`docs-samples/hello@1.0.0` 固定版本，`@^1.2.0`、`@~1.2`、`@1.x` 选择范围，`@latest` 跟随标签。省略 `@` 等价于 `@latest`。每次运行记录实际解析的版本。

正式版发布会按版本选择规则更新 `latest`；发布较低版本不会自动把它退回。预发布版本需显式指定标签，例如 `beta`。`stable`、`beta` 等标签可以移动；标签名不能是版本号或版本范围；`latest` 不能删除。移动标签影响之后解析它的运行，不改写已发布版本。

用[发布版本](/docs/api/native/automation/publishScriptVersion)管理不可变内容，用[设置标签](/docs/api/native/automation/setScriptTag)把标签指向已有版本。写标签不需要 `If-Match`。修改草稿则需要最新 ETag，发布草稿需要 `expected_draft_revision`。

动作没有语义版本号：兼容更新立即生效，调用记录保存实际修订。输入输出不兼容时使用新名字，避免破坏既有调用方。工作流发布时锁定脚本和子工作流依赖的精确版本，动作不锁定。

## 运行生命周期 [#运行生命周期]

| 状态          | 含义                 |
| ----------- | ------------------ |
| `pending`   | 已受理，等待开始。          |
| `running`   | 正在执行。              |
| `waiting`   | 工作流正在等待事件、定时器或子运行。 |
| `suspended` | 工作流被暂停。            |
| `completed` | 成功结束，读取 `output`。  |
| `faulted`   | 执行失败，读取 `error`。   |
| `cancelled` | 已取消。               |

脚本没有 `waiting` 和 `suspended`。取消请求尚未结束时，运行可能仍为 `running`，并带 `cancel_requested_at`。超时是 `faulted`，错误类型为 `timeout`，不是另一个状态。终态不会恢复；[重跑](/docs/api/native/automation/rerunRun)创建新的根运行，`rerun_of` 指向原运行。

HTTP 成功表示请求被处理，不代表脚本成功。分别检查 `status`、`output` 和 `error`。脚本可查看[调用](/docs/api/native/automation/listRunCalls)与[日志](/docs/api/native/automation/listRunLogs)，工作流可查看[步骤](/docs/api/native/automation/listRunTasks)与[等待点](/docs/api/native/automation/listRunWaits)。

## 子运行与来源 [#子运行与来源]

脚本可以通过 `praxis.automation.runs.create` 启动子运行。子运行的 `initiator` 始终保留最初发起者（人、API Key 或触发器）；父子关系由 `parent_run_id` 表达。按来源筛选子运行用 `channel=run`，按指定父运行查找用 `parent_run_id` 过滤；公开详情中的 `parent` 提供父运行摘要，`root_run_id` 指向根运行。

父运行被取消时向下级联；父正常结束时子运行可以继续。子运行 deadline 不会超出父运行剩余时间。同一目标在调用链上再次出现会被循环检测拒绝；深度和扇出上限见[限制](/docs/cloud/services/automation/limits-and-errors)。

## 幂等与重试 [#幂等与重试]

[创建运行](/docs/api/native/automation/createRun)接受 `Idempotency-Key`。作用域为同一 owner、HTTP 方法、路径和 key，保留 24 小时；请求指纹不包含 `wait`。网络重试应复用原 key 和请求内容；重放返回当前运行，并带 `Idempotent-Replayed: true`。有意再跑一次时使用新 key。

同 key 不同请求返回 `IDEMPOTENCY_KEY_MISMATCH`；尚在处理时返回 `IDEMPOTENCY_IN_FLIGHT`，详见创建运行的错误表。幂等不提供事务回滚，失败前已经完成的调用可能产生了效果。

## 费用归因 [#费用归因]

运行本身不单独收费。运行中调用模型、搜索等能力产生费用，按这些能力的原价计费，并归因到运行与触发器上显示。没有能力调用的纯计算脚本不会产生模型或搜索费用。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 编写脚本

脚本默认导出一个接收输入的函数；返回值成为运行的 `output`。

执行本页前，先在同一个 Bash 会话完成快速开始第 1–3 步：[设置 `PRAXIS_API_URL` 与 `PRAXIS_API_KEY`](/docs/cloud/services/automation/quickstart#environment)、[定义 `SOURCE` 并临时运行](/docs/cloud/services/automation/quickstart#run-source)、[定义并调用 `read_result` 辅助动作](/docs/cloud/services/automation/quickstart#read-result)。该动作检查结果是否为 42，与本页的加一示例对应。

## 入口与 schema [#入口与-schema]

把下面的内容保存为 `script.ts`：

```typescript
export default async (input: { n: number }): Promise<{ answer: number }> => {
  console.log("Adding one", input.n);
  return { answer: input.n + 1 };
};
```

输入 schema 从参数类型推导；输出 schema 从显式返回类型推导，`Promise` 会展开。支持基本类型、对象、数组、联合类型及可解析的本地类型别名。不能推导的类型会得到空 schema 和警告；不要把空 schema 当成已经验证了字段。省略返回类型时，不应依赖返回表达式自动推导出输出约束。

通过[校验定义](/docs/api/native/automation/validateDefinition)检查实际生成的 schema，再发布：

```bash
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/validate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --rawfile source script.ts '{kind:"script",source:$source}')" \
  | jq -e '.valid == true and .input_schema.properties.n.type == "number" and .output_schema.properties.answer.type == "number"'
```

期望：输出 `true`，退出码 0。读取完整校验响应中的 `errors` 与 `warnings` 可以定位不能推导的类型。

## 运行与日志 [#运行与日志]

```bash
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --rawfile source script.ts \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs/$RUN_ID/logs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

期望：结果断言为 `true`；日志响应包含 `Adding one 41`。`console.log/info/debug` 记录为 `info`，`console.warn` 和 `console.error` 保留各自级别。日志不是返回值；需要交给调用方的数据必须 `return`。可通过[日志接口](/docs/api/native/automation/listRunLogs)读取，或使用 `Accept: text/event-stream` 订阅。

## 全局 praxis [#全局-praxis]

运行时已经提供 `praxis`，无需 import、API Key 或安装包。它提供以下 SDK 入口；方法参数采用参考页中的 `path`、`query`、`body` 形状，例如 `praxis.automation.runs.create({body:{target,input}})`。能否调用仍取决于发起者权限。

| 入口                    | 能力参考                                          |
| --------------------- | --------------------------------------------- |
| `praxis.agent`        | [Agent](/docs/api/native/agent)               |
| `praxis.model`        | [Model](/docs/api/native/model)               |
| `praxis.file`         | [File](/docs/api/native/file)                 |
| `praxis.sandbox`      | [Sandbox](/docs/api/native/sandbox)           |
| `praxis.search`       | [Search](/docs/api/native/search)             |
| `praxis.database`     | [Database](/docs/api/native/database)         |
| `praxis.automation`   | [Automation](/docs/api/native/automation)     |
| `praxis.organization` | [Organization](/docs/api/native/organization) |
| `praxis.meta`         | [Meta](/docs/api/native/meta)                 |

脚本不能直接访问外部网络。用平台提供的能力完成操作，并 `await` 调用以取得结果及处理异常。

## 调用平台内置动作 [#调用平台内置动作]

`call("命名空间/名字", 输入)` 接收 Action 引用和输入对象，返回 Action 的输出。它是当前运行里的一个步骤：有自己的输入、输出，并在[调用记录](/docs/api/native/automation/listRunCalls)里占一条，不会产生子运行。`praxis` 是平台命名空间；省略命名空间的裸名也只解析到平台 Action。调用总使用 Action 的当前修订，暂不支持 `@版本`；不再接受 `命名空间::名字` 写法。

调用失败时抛出错误，带 `code`、`message`、`hint`、调用记录序号 `seq` 和 `request_id`。多个 `call` 可以用 `Promise.all` 并发。`praxis.*` 只表示平台 SDK，`call(...)` 和 `praxis.ocr(...)` 这类写法已删除，运行时会报错并提示改用 `call`。

把下面内容保存为 `chat.ts`；它调用 `praxis/chat`。模型由动作内置并由维护者选择，调用时不选模型；`praxis/ocr`、`praxis/image`、`praxis/embed` 也一样。旧 `model` 字段已废弃，传入的值会被忽略。此调用会产生模型费用：

```typescript
export default async (input: { prompt: string }) => {
  return await call("praxis/chat", {
    messages: [{ role: "user", content: input.prompt }],
    stream: false,
  });
};
```

```bash
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --rawfile source chat.ts \
    '{source:$source,language:"ts",input:{prompt:"Say hello in one sentence."},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" | jq '{id,status,output,error}'
```

期望：终态为 `completed`，`output` 为模型结果，`error` 为 null。若仍是 `pending` 或 `running`，重复最后一条 GET，直到终态；`faulted` 时读取错误，不能把 HTTP 成功当成模型成功。动作输入输出的完整约定可用[读取动作](/docs/api/native/automation/getAction)查看 `praxis/chat`。

## 调用自建动作 [#调用自建动作]

以下示例[创建动作](/docs/api/native/automation/createAction)，再用它的完整名字调用。生成的脚本源码中引用是字符串字面量，便于发布前校验。

```bash
ACTION_NAME="add-one-$(date +%s)-$RANDOM"
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/actions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg name "$ACTION_NAME" '{
    namespace:"docs-samples",name:$name,
    input_schema:{type:"object",properties:{n:{type:"number"}},required:["n"],additionalProperties:false},
    output_schema:{type:"object",properties:{answer:{type:"number"}},required:["answer"],additionalProperties:false},
    implementation:{kind:"code",language:"ts",source:"export default async (input: { n: number }) => ({ answer: input.n + 1 });"}
  }')" | jq -e '.id | startswith("act_")'
SOURCE="export default async (input: { n: number }) => await call(\"docs-samples/$ACTION_NAME\", input);"
RUN=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg source "$SOURCE" \
    '{source:$source,language:"ts",input:{n:41},wait:60}')")
RUN_ID=$(jq -er '.id' <<< "$RUN")
read_result "$RUN_ID"
```

期望：动作创建与运行结果均输出 `true`，结果为 42。用完后可[归档动作](/docs/api/native/automation/archiveAction)。动作可复用，但不能在动作内部再编排其他动作、脚本或工作流。

## 调用另一个脚本或工作流 [#调用另一个脚本或工作流]

`invoke("命名空间/名字@版本", 输入)` 把另一个已发布的脚本或工作流作为**子运行**启动，等它结束后返回子运行的输出；省略 `@版本` 用最新版。和 `call` 的区别：`call` 是当前运行里的一个步骤，不产生子运行；`invoke` 产生一个有自己 ID、状态和日志的子运行，并在[调用记录](/docs/api/native/automation/listRunCalls)里用 `child_run_id` 指向它。

```typescript
export default async (input: { urls: string[] }) => {
  // 多个 invoke 用 Promise.all 并发；子运行经队列启动，不受单次请求链长度限制。
  const pages = await Promise.all(input.urls.map(url => invoke("team/fetch-page", { url })));
  return { pages };
};
```

* **等待有上限**：`invoke` 同步等待子运行结束，等待时间受父运行 `deadline` 限制。到期时抛出 `INVOKE_TIMEOUT`，消息里带子运行 ID；子运行不会因此被取消，可以用该 ID 另行读取结果。需要等很久的子运行，请在工作流里用 `run:` 步骤——工作流在等待期间不占用计算。
* **失败**：子运行失败、被取消或无法创建时抛出错误，`code` 是子运行的错误码，`message` 带子运行 ID。目标不存在或已归档时立即失败，不会排队。
* **取消与超时**：父运行被取消或失败时，仍在等待中的子运行会一起被取消。
* **查看子运行**：[列出运行](/docs/api/native/automation/listRuns)时用 `parent_run_id` 筛选，得到每个子运行的 ID、目标、状态和耗时。
* **限制**：每个运行最多 100 个子运行，同时执行的最多 20 个，多出的排队等待；嵌套最多 10 层，不允许自己调用自己。

脚本不能自行指定独立运行（detach）的子运行；需要“启动后不等结果”时，调用 [创建运行](/docs/api/native/automation/createRun)。

## 返回值和时间预算 [#返回值和时间预算]

返回 JSON 可序列化的值；不要返回 `undefined`、BigInt 或循环引用。序列化后的 UTF-8 返回值最多 1 MiB，超过会使运行失败。大结果应保存到文件等存储中，返回引用。

脚本墙钟时间默认最多 5 分钟；CPU 时间最多 30 秒，并受剩余 deadline 进一步约束。等待平台调用与纯计算的耗时不同，增加等待时长不能解决死循环。全部数值见[限制与错误](/docs/cloud/services/automation/limits-and-errors)。

## 有依据的错误与修法 [#有依据的错误与修法]

| code                 | 报错原文                              | 修法                                |
| -------------------- | --------------------------------- | --------------------------------- |
| `SCRIPT_ERROR`       | `脚本执行出错`                          | 阅读 detail 中的原始异常及用户代码行号，修正后创建新运行。 |
| `CPU_LIMIT_EXCEEDED` | `脚本 CPU 时间超出上限`                   | 终止无限循环，缩小每批纯计算量。                  |
| `PAYLOAD_TOO_LARGE`  | `Payload exceeds 1 MiB`           | 缩小 JSON 返回值，返回存储引用。               |
| `INPUT_INVALID`      | `Value must be JSON serializable` | 返回明确的 JSON 值，如对象或 null。           |

运行失败看 `Run.error`；创建请求被拒绝看 HTTP problem 响应。两者不能混用。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 触发器

触发器把“何时执行”与脚本、工作流的内容分开。

执行本页前，先在同一个 Bash 会话完成快速开始第 1–3 步：[设置 `PRAXIS_API_URL` 与 `PRAXIS_API_KEY`](/docs/cloud/services/automation/quickstart#environment)、[定义 `SOURCE` 并临时运行](/docs/cloud/services/automation/quickstart#run-source)、[定义并调用 `read_result` 辅助函数](/docs/cloud/services/automation/quickstart#read-result)。该函数检查结果是否为 42，与本页的加一示例对应。再完成第 4–5 步：[保存并发布脚本](/docs/cloud/services/automation/quickstart#publish-script)、[设置 `TARGET`](/docs/cloud/services/automation/quickstart#run-version)。`TARGET` 必须指向这个接收 `n`、返回 `answer` 的已发布脚本。

## 定时执行 [#定时执行]

每个 schedule 只能选择一种规则：

| 规则                  | 用途                                     |
| ------------------- | -------------------------------------- |
| `cron: "0 9 * * *"` | 每天当地时间 09:00；五段，分钟精度，支持 L、W、#。         |
| `every: "PT5M"`     | 每隔五分钟；最短一分钟，按经过的时长计算。                  |
| `at`                | RFC 3339 绝对时间，必须带时区偏移或 Z；不能早于现在或晚于一年后。 |

`timezone` 使用 IANA 名称，API 默认 UTC。当地时间 cron 在夏令时春季跳过不存在的时刻，秋季重复的时刻只运行一次。`every` 按时长、`at` 按绝对时间执行，不使用这条 cron 夏令时规则。

先[预览下次时间](/docs/api/native/automation/previewTriggerSchedule)：

```bash
curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers/preview" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"schedule":{"cron":"0 9 * * *"},"timezone":"Asia/Shanghai"}' \
  | jq -e '{next_fire_times} | select(.next_fire_times | length == 5)'
```

期望：输出五个未来时间，例如：

```json
{
  "next_fire_times": [
    "2026-10-13T01:00:00.000Z",
    "2026-10-14T01:00:00.000Z",
    "2026-10-15T01:00:00.000Z",
    "2026-10-16T01:00:00.000Z",
    "2026-10-17T01:00:00.000Z"
  ]
}
```

日期随预览时间变化。末尾的 `Z` 表示 UTC。例如 `2026-10-13T01:00:00.000Z` 换算为**上海时间（UTC+8）10 月 13 日 09:00**。`timezone` 决定 cron 按哪个当地时区计算，返回的时间统一用 UTC 表达。

再[创建触发器](/docs/api/native/automation/createTrigger)，并立即触发一次检查目标：

```bash
TRIGGER=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" '{
    name:"daily-hello",target:$target,kind:"schedule",input:{n:41},
    schedule:{cron:"0 9 * * *"},timezone:"Asia/Shanghai",
    overlap:"skip",catchup_window_seconds:300
  }')")
SCHEDULE_ID=$(jq -er '.id' <<< "$TRIGGER")
jq -e '.state == "enabled" and (.next_fire_times | length == 5)' <<< "$TRIGGER"
FIRING=$(curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/fire" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}')
jq -e '.outcome == "started"' <<< "$FIRING"
read_result "$(jq -er '.run_id' <<< "$FIRING")"
```

期望：三次断言输出 `true`。`started` 只表示启动成功；`read_result` 用返回的 `run_id` [读取运行](/docs/api/native/automation/getRun)，确认终态成功且结果为 42。

`target` 写 `@1.0.0` 固定版本，写 `@latest` 跟随标签；每条触发记录保存实际版本。创建和修改时检查静态输入，触发时再次检查，避免新版本不再接受原输入。

## 重叠、延迟与有效时间 [#重叠延迟与有效时间]

默认 `overlap: "skip"`：上一次运行未结束时，本次记录为 `skipped_overlap`；`allow` 允许重叠启动，仍受运行并发限制。没有排队补齐、取消旧运行或历史 backfill 策略。

`catchup_window_seconds` 默认 300。调度延迟超过窗口记为 `missed`，不会启动；这不是恢复后重放所有错过任务的承诺。暂停期间不执行，恢复后继续未来调度。

用 `start_at` 与 `end_at` 设置有效时间范围（RFC 3339）。一次性 `at` 执行后、或达到结束时间后变为 `expired`。连续 5 次触发失败会自动暂停。通过[暂停](/docs/api/native/automation/pauseTrigger)和[恢复](/docs/api/native/automation/resumeTrigger)控制后续触发。

暂停上面创建的触发器，再恢复：

```bash
curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/pause" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}' \
  | jq -e '.state == "paused" and (.next_fire_times | length == 0)'
curl --fail-with-body -sS -X POST \
  "$PRAXIS_API_URL/automation/v1/triggers/$SCHEDULE_ID/resume" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' --data '{}' \
  | jq -e '.state == "enabled" and (.next_fire_times | length == 5)'
```

期望：两次请求都输出 `true`；恢复后返回这个每日计划的下五次执行时间。

工作流 YAML 中的 cron/every schedule 在发布为 latest 时管理一个 `source=definition` 触发器；修改要重新发布定义，不能直接 PATCH 这个触发器。可以暂停或恢复它。`schedule.after` 与 `schedule.on` 暂不支持。

## Webhook [#webhook]

创建时选 `input_mode: "body"`，收到的 JSON 就是运行输入；非 JSON 请求体作为字符串。以下示例把 `n:41` 传给快速开始的脚本：

```bash
HOOK=$(curl --fail-with-body -sS "$PRAXIS_API_URL/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n --arg target "$TARGET" '{
    name:"webhook-hello",target:$target,kind:"webhook",webhook:{input_mode:"body"}
  }')")
WEBHOOK_ID=$(jq -er '.id' <<< "$HOOK")
WEBHOOK_URL=$(jq -er '.webhook_url' <<< "$HOOK")
curl --fail-with-body -sS "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "webhook-id: hello-$(date +%s)-$RANDOM" \
  --data '{"n":41}' | jq -e '.id | startswith("frg_")'
```

期望：HTTP 202，断言输出 `true`，响应含触发记录 ID。异步启动结果需要再查触发历史。

完整 URL 只在创建或[轮换](/docs/api/native/automation/rotateTriggerWebhook)时返回；其中的 token 是凭据，无需 API Key，不要公开。旧 URL 在轮换后失效。错误 token、暂停或不存在的触发器都返回 404。请求体最多 1 MiB；相同 `webhook-id` 在 24 小时内去重。

## 签名头与 envelope [#签名头与-envelope]

当前 webhook 入口验证 secret URL，不自动验证 Standard Webhooks、GitHub 或 Stripe 的 HMAC 签名。传入 `webhook-signature` 不代表它已经通过验签。

若目标需要读取头部，创建时使用 `webhook: {input_mode:"envelope"}`，并让目标的输入 schema 接受下列形状（这不是快速开始的 `n` 输入）：

```json
{
  "body": { "n": 41 },
  "headers": { "content-type": "application/json", "webhook-id": "delivery-1" },
  "webhook_id": "delivery-1",
  "received_at": "2026-10-11T12:00:00.000Z"
}
```

`webhook_id` 未提供时为 null。只保留以下头：`content-type`、`user-agent`、`webhook-id`、`webhook-timestamp`、`webhook-signature`、`x-github-event`、`x-github-delivery`、`x-hub-signature-256`、`stripe-signature`；Authorization、Cookie 不会转交。

JSON body 会先被解析，envelope 不包含独立的原始请求字节。对于必须签署原始字节的协议，不能用 `JSON.stringify(body)` 代替原文验签。需要这种验证时，在你接收原始请求的服务中按发送方协议先验证，再转发到 secret URL。当前没有可直接套用到此 JSON envelope 的通用验签示例。

## 查看触发记录与清理 [#查看触发记录与清理]

```bash
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/triggers/$WEBHOOK_ID/firings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  | jq -e '.data | length > 0'
curl --fail-with-body -sS \
  "$PRAXIS_API_URL/automation/v1/triggers/$WEBHOOK_ID/firings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  | jq '.data[] | {outcome,run_id,resolved_version,error}'
```

期望：第一个请求输出 `true`，第二个列出记录。若异步处理尚未完成，稍后重新读取。`started` 表示已启动，`failed` 看 error，`missed` 表示超过窗口，`skipped_overlap` 表示前次未结束，`deduped` 表示命中去重。按 `run_id` 继续查看运行终态，记录保留 30 天。

测试完成后删除本页创建的两个触发器，避免继续定时执行：

```bash
for id in "$SCHEDULE_ID" "$WEBHOOK_ID"; do
  curl --fail-with-body -sS -X DELETE \
    "$PRAXIS_API_URL/automation/v1/triggers/$id" \
    -H "Authorization: Bearer $PRAXIS_API_KEY"
done
```

期望：curl 均退出 0。删除不影响已经启动的运行。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 限制与错误

以下默认值约束单次运行及其子运行；调用方设置的更短 deadline 也约束后续执行。并发超限时排队，不会增加执行容量。

## 执行与数据 [#执行与数据]

| 限制                       | 数值                       |
| ------------------------ | ------------------------ |
| 嵌套深度                     | 10                       |
| 每运行子运行总数 / 同时活跃子运行       | 100 / 20                 |
| 运行树总节点                   | 1,000                    |
| 每 owner / 每定义并发运行        | 100 / 20                 |
| 动作 / 沙箱动作超时              | 30 s / 10 min            |
| 脚本墙钟超时                   | 5 min                    |
| 工作流默认 / 最大超时             | 24 h / 7 days            |
| 创建运行 wait 上限             | 60 s                     |
| 载荷软阈值 / 硬上限              | 256 KiB / 1 MiB          |
| 调用载荷内联阈值 / 检查点内联阈值       | 32 KiB / 256 KiB         |
| 每运行任务执行数（含循环与重试）         | 4,000                    |
| 每运行持久执行步骤预算              | 9,000                    |
| 每 fork 分支 / 嵌套并发效果       | 10 / 25                  |
| 幂等保留时间                   | 24 h                     |
| 运行日志保留期                  | 30 days                  |
| 每页记录数                    | 100                      |
| 标签数量 / key 长度 / value 长度 | 50 / 40 / 500 characters |
| 描述长度                     | 1,000 characters         |
| SSE 心跳间隔                 | 20 s                     |

{/* Sources: services/automation/src/api/contract.ts:42-70; services/automation/src/runs/workflow/primitives.ts:7-12. */}

载荷软阈值不是拒绝边界；硬上限为 1 MiB，按 JSON 编码后的 UTF-8 字节计算。内联阈值决定数据的存储方式，不代表脚本可以返回超过硬上限的结果。

## 脚本运行时 [#脚本运行时]

| 限制          | 数值                         |
| ----------- | -------------------------- |
| CPU 时间      | 最多 30 秒，并取剩余 deadline 中较小者 |
| 每脚本连接器请求    | 1,000 次，包含日志和进度            |
| 同时执行的连接器操作  | 20                         |
| 单条日志        | 4,096 UTF-8 字节，超出截断        |
| 调用摘要        | 512 字符                     |
| 脚本错误 detail | 1,000 字符                   |
| 保留的用户堆栈帧    | 最多 5 条                     |

{/* Sources: services/automation/src/script-runtime/core.ts:8-91; index.ts CPU limit; connectors.ts Gate(20). */}

脚本输出必须可序列化为 JSON，编码失败会使运行失败。脚本没有检查点或事务回滚；具体报错原文与修法见[编写脚本](/docs/cloud/services/automation/guides/write-script)。

## 触发器 [#触发器]

| 限制              | 数值     |
| --------------- | ------ |
| 每 owner 启用中的触发器 | 100    |
| every 最短间隔      | 1 分钟   |
| cron 精度         | 五段，分钟  |
| 一次性 at 时间范围     | 当前至一年后 |
| 默认补跑窗口          | 300 秒  |
| 预览未来时间          | 最多 5 个 |
| 连续触发失败后自动暂停     | 5 次    |
| webhook 请求体     | 1 MiB  |
| webhook-id 去重   | 24 小时  |
| 触发记录保留期         | 30 天   |

{/* Sources: services/automation/TRIGGERS.md sections 2-3; services/automation/src/triggers/core.ts; webhook.ts:4. */}

## 找到对应错误 [#找到对应错误]

HTTP 错误表示请求被拒绝；运行状态 `faulted` 表示执行失败，即使读取它的 HTTP 响应为 200。排查时保存运行 ID 与响应头 `X-Request-Id`。

* [创建运行错误表](/docs/api/native/automation/createRun)：输入、目标解析、幂等与配额。
* [发布错误表](/docs/api/native/automation/publishScriptVersion)：草稿已变、版本冲突与定义校验。
* [触发器错误表](/docs/api/native/automation/createTrigger)与[调度错误表](/docs/api/native/automation/previewTriggerSchedule)。
* [Webhook 错误表](/docs/api/native/automation/receiveWebhook)：请求体大小、输入与不可用 URL。
* [鉴权与通用错误](/docs/api/errors)。

例如 `INTERVAL_TOO_SHORT` 的报错原文为 `every must be at least one minute`，把间隔改为 `PT1M` 或更长；不要原样重试无效调度。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)

# 模型

统一接口访问 LLM、图像、语音、Embedding 模型；兼容 OpenAI 与 Anthropic 协议，现有 SDK 零改动接入。

## 出口 [#出口]

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 快速开始

用一个云 API Key 调用 `deepseek-flash`，读取实付费用，再找到同一次调用的记录。示例会产生少量费用。

## 1. 准备 Key 与终端 [#1-准备-key-与终端]

在[控制台 → API Keys](https://console.deepraxis.ai/keys)点击「创建 Key」，填写名称并创建，将 Key 安全注入当前终端的 `PRAXIS_API_KEY` 环境变量。不要写入代码或日志。已有 Key 可直接使用。

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)，在 macOS / Linux 终端执行：

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`；切换环境时，将 `PRAXIS_API_BASE` 设为对应 API 域名，不带末尾斜杠或 API 路径。

## 2. 发出请求并读取费用 [#2-发出请求并读取费用]

保存为 `quickstart.py`，在该文件所在目录执行 `uv run -q --no-project --with openai --with anthropic --with google-genai python quickstart.py`。

```python
import json
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRAXIS_API_KEY"],
    base_url=os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com") + "/openai/v1",
    timeout=90.0,
    max_retries=0,
)
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply with exactly: Hello Praxis."}],
    max_tokens=256,
)
reply = raw.parse()
usage = reply.usage.model_dump()
request_id = raw.headers.get("x-request-id")
generation_id = raw.headers.get("x-praxis-generation-id")
assert raw.status_code == 200 and reply.choices[0].message.content
assert request_id and generation_id
assert isinstance(usage.get("cost"), (int, float)) and usage["cost"] >= 0
print(reply.choices[0].message.content)
print("usage:", usage)
print("X-Request-Id:", request_id)
print("X-Praxis-Generation-Id:", generation_id)
Path("quickstart-result.json").write_text(json.dumps({
    "request_id": request_id, "generation_id": generation_id, "cost": usage["cost"],
}))
```

期望：退出码 0，输出非空回答（通常为 `Hello Praxis.`）、`usage` 和两个 ID，并生成 `quickstart-result.json`。该文件只保存本次调用的 ID 与费用，不含 Key。

`usage` 包含输入和输出 token 数；`usage.cost` 是本次实付美元金额，不是每百万 token 的单价。不要把缺失费用当成零。字段定义见 [Chat Completions API](/docs/api/compatible/openai/createChatCompletion)。

## 3. 找到这次调用 [#3-找到这次调用]

打开[控制台 → 模型 → 调用日志](https://console.deepraxis.ai/call-logs)。在「按 X-Request-Id / Generation ID 查找」输入框粘贴上一步的 `X-Request-Id`，按 Enter。此路径与控件名核对于 2026-10-13 的 Console。

期望：出现模型为 `deepseek-flash` 的本次调用，可查看状态、用量与费用。记录可能延迟几秒；使用与 Key 相同的账号及环境，并确保时间范围包含刚才的调用。

不使用浏览器时，可用下面的等价硬验证。保存为 `verify-generation.py`，在同一目录执行 `uv run -q --no-project --with openai --with anthropic --with google-genai python verify-generation.py`。

```python
import json
import os
import time
from decimal import Decimal
from pathlib import Path
import httpx

saved = json.loads(Path("quickstart-result.json").read_text())
base = os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com")
with httpx.Client(timeout=60.0) as client:
    for attempt in range(10):
        response = client.get(
            base + "/model/v1/generation",
            params={"id": saved["generation_id"]},
            headers={"Authorization": "Bearer " + os.environ["PRAXIS_API_KEY"]},
        )
        if response.status_code != 404:
            break
        time.sleep(3)
    response.raise_for_status()
    record = response.json()
    assert record["id"] == saved["generation_id"]
    assert record["model"] == "deepseek-flash"
    assert abs(Decimal(str(record["cost"])) - Decimal(str(saved["cost"]))) <= Decimal("0.0000005")
    print("Verified generation:", record["id"])
    print("cost:", record["cost"])
    print("X-Request-Id:", response.headers.get("x-request-id"))
```

期望：退出码 0，输出 `Verified generation` 和按美元六位小数记录的费用；脚本允许相应舍入差异。查询使用 `X-Praxis-Generation-Id`，不是 `X-Request-Id` 或响应正文的 `id`；详见[生成记录 API](/docs/api/native/model/getGeneration)。

## 失败分支 [#失败分支]

* `404` 查询记录：记录尚未可查时，脚本每 3 秒重试，最多 10 次；仍失败则保留两个 ID，检查 Key、环境及生成 ID 是否来自同一次调用，再查询。
* `Model "gpt-4o" does not exist.`：模型 ID 不自动映射；使用本页的 `deepseek-flash` 或[目录](/docs/cloud/services/model/catalog)中的 ID。

接下来可使用[流式响应](/docs/cloud/services/model/guides/streaming)或[工具调用](/docs/cloud/services/model/guides/tool-calling)。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 模型目录

模型与价格会变化，请从[控制台 → 模型目录](https://console.deepraxis.ai/models)或实时 API 读取，不依赖静态清单。

## 1. 准备查询 [#1-准备查询]

准备 Python 3.10+ 与 [uv](https://docs.astral.sh/uv/getting-started/installation/)。原生目录 `GET /model/v1/models` 无需 Key；下面同时查询 OpenAI 兼容目录，需要按[快速开始](/docs/cloud/services/model/quickstart)设置 `PRAXIS_API_KEY`。

期望：已有 Key 环境变量。示例默认使用 `https://api.deepraxis.com`；切换环境时，设置 `PRAXIS_API_BASE` 为 API 域名，不带末尾斜杠或 API 路径。

## 2. 核对模型与协议 [#2-核对模型与协议]

保存为 `catalog.py`，执行 `uv run -q --no-project --with openai --with anthropic --with google-genai python catalog.py`。

```python
import os
import httpx

base = os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com")
with httpx.Client(timeout=60.0) as client:
    response = client.get(base + "/model/v1/models")
    response.raise_for_status()
    models = response.json()["data"]
    model = next(item for item in models if item["id"] == "deepseek-flash")
    assert "openai.chat.completions" in model["supported_apis"]
    for field in ("id", "type", "supported_apis", "context_window", "pricing"):
        print(field + ":", model[field])
    print("X-Request-Id:", response.headers.get("x-request-id"))

    filtered = client.get(
        base + "/openai/v1/models",
        params={"api": "responses"},
        headers={"Authorization": "Bearer " + os.environ["PRAXIS_API_KEY"]},
    )
    filtered.raise_for_status()
    ids = [item["id"] for item in filtered.json()["data"]]
    assert "deepseek-flash" in ids
    print("Responses models:", ids)
    print("X-Request-Id:", filtered.headers.get("x-request-id"))
```

期望：退出码 0，打印 `deepseek-flash` 的类别、协议、上下文和价格，以及包含该 ID 的 Responses 列表。示例核对于 2026-10-13；以查询时的结果为准。若断言失败，不要向所选协议发送请求，先从最新列表选择支持它的模型。

## 3. 根据结果选择 [#3-根据结果选择]

先按 `type` 找任务类别，再用 `supported_apis` 确认要调用的协议；不能从模型名称推断协议。原生列表还可用 `supported_api=openai.responses` 筛选；OpenAI 兼容列表的 `api=chat,embeddings` 表示匹配任一协议。

再核对上下文和输出限制，以及输入、输出、缓存或非 token 计量的单价。[模型与目录概念](/docs/cloud/services/model/concepts/models-and-catalog)解释计费单位及可用率；[列出模型 API](/docs/api/native/model/listModels)提供字段定义。

期望：所选 ID 支持应用需要的协议，限制能容纳请求，价格单位与任务一致。最后按[快速开始](/docs/cloud/services/model/quickstart)发起真实调用并核对实付费用。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 概念

一次模型调用由模型 ID 指定要用的模型，由协议决定请求和响应的格式；平台在符合要求的线路中完成调用。

* [模型与目录](/docs/cloud/services/model/concepts/models-and-catalog)：区分模型类别、协议支持与计费单位。
* [协议兼容](/docs/cloud/services/model/concepts/protocols)：理解同一个地址下不同协议的适用范围。
* [路由](/docs/cloud/services/model/concepts/routing)：理解线路选择、失败换线与参数要求。
* [会话亲和](/docs/cloud/services/model/concepts/session-affinity)：理解重复使用同一线路与缓存的关系。
* [BYOK](/docs/cloud/services/model/concepts/byok)：查看自带凭证的开放状态。

第一次调用从[快速开始](/docs/cloud/services/model/quickstart)进入；选择模型从[模型目录](/docs/cloud/services/model/catalog)进入。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 模型与目录

模型目录描述可以选择什么；一次调用的记录描述实际用了多少、付了多少。两者用途不同。

## 模型 ID 与能力 [#模型-id-与能力]

请求中的 `model` 使用目录返回的完整 `id`，例如 `deepseek-flash`。显示名称不是 ID；相同 ID 也不表示底层版本永远不变，滚动版本应以模型说明为准。

`type` 区分语言、图像、语音、视频、向量等模型类别，不能据此推断它支持所有相关接口。`supported_apis` 才是已开放协议的列表；选择 Chat、Responses 或 Messages 前分别核对它。输入和输出模态说明能处理什么内容，不等于所有文件格式都能原生读取。

上下文窗口限制一次输入与生成可容纳的内容，不是每次必然能输出的长度。原生目录的字段为 `context_window`；OpenAI 兼容目录使用 `context_length`。输出上限需另看模型说明与 API 参考。

## 标价与实付 [#标价与实付]

目录 `pricing` 的金额为美元，单位由价格项决定。token 单价以每个 token 表达，展示为每百万 token 时乘以一百万；输入与输出分别定价。`input_cache_read` 是缓存命中时的输入读价，不保证每次都会命中。

并非所有模型按 token 计费：视频可按秒、图像可按张、OCR 可按页、转写可按音频分钟。价格项缺失不表示免费，不要把所有数值都乘以一百万。具体价格项与字段定义见[列出模型 API](/docs/api/native/model/listModels)。

Chat 响应的 `usage.cost` 是本次实付美元金额；用目录单价乘以 token 数只是估算，可能忽略缓存或其他计量。需要核对实际调用时，使用[快速开始中的生成记录查询](/docs/cloud/services/model/quickstart)。

## 可用率 [#可用率]

可用率衡量平台与上游能否完成有效请求：平台或上游原因的失败计入，调用方参数等原因造成的拒绝不计入。它不表示任意参数都能成功，也不保证下一次请求必然成功。

[模型目录](/docs/cloud/services/model/catalog)说明如何获取当前目录；本页不维护静态模型与价格清单。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 路由

你选择模型，平台从支持该模型及所用协议的线路中选择一次调用的去向。同一个模型可以有多条线路；线路数量与状态会变化。

## 从请求到线路 [#从请求到线路]

平台先检查模型、协议和参数要求，再结合健康状态与优先级选择可用线路。备选线路必须支持同一种协议；Chat、Responses、Messages 之间不会为了换线而偷偷转换。

同优先级的可用线路还可能受[会话亲和](/docs/cloud/services/model/concepts/session-affinity)影响。优先级不是对某个供应商的永久绑定，也不是每次都选择最低价格的保证。

## 失败换线 [#失败换线]

当一次尝试因可重试的上游故障、限流或线路不可用而失败时，平台可自动尝试其他合适的线路。没有可用备选或尝试仍失败时，请求返回错误；不是无限重试，也不保证已开始的流式回答可以无缝续接。

调用方参数错误不靠换线修复。应用仍需检查完成状态，并按[错误与限制](/docs/cloud/services/model/limits-and-errors)处理失败。

## 参数要求与供应商选择 [#参数要求与供应商选择]

`provider.require_parameters` 要求线路声明支持请求中的相关工具与采样参数，避免把要求交给不支持它的线路。它限制候选线路，不会为模型增加能力，也不保证模型一定调用工具或生成某种回答；没有符合要求的线路时可拒绝请求。具体参数支持以 [Chat API 参考](/docs/api/compatible/openai/createChatCompletion)为准。

`provider` 中指定供应商的 `order`、`only`、`ignore` 是 BYOK 专属选项；`require_parameters` 这种能力约束不属于供应商选择限制。平台模型由平台选线。[BYOK 当前即将推出](/docs/cloud/services/model/concepts/byok)，不要依赖它指定平台供应商。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 协议兼容

协议兼容让你沿用客户端的请求格式；不表示每个模型支持所有协议或官方的全部功能。以模型的 `supported_apis` 和各端点支持说明为准。

只有一个地址 `https://api.deepraxis.com`，按协议分入口：

| 入口           | 协议                |
| ------------ | ----------------- |
| `/openai`    | OpenAI 系协议        |
| `/anthropic` | Anthropic 系协议     |
| `/google`    | Google Gemini API |

## OpenAI Chat Completions [#openai-chat-completions]

`POST /openai/v1/chat/completions`。常用的对话协议；流式（SSE）、工具调用与多模态输入是否可用取决于模型。 模型能力与字段差异见 [Chat API](/docs/api/compatible/openai/createChatCompletion)；会话标识的作用见[会话亲和](/docs/cloud/services/model/concepts/session-affinity)。

## OpenAI Responses [#openai-responses]

`POST /openai/v1/responses` 及 retrieve / delete / cancel / input\_items。OpenAI 新一代有状态协议；Codex 等 Agent 走这里。支持范围见 [Responses API](/docs/api/compatible/openai/createResponse)。压缩响应与输入 token 计数端点当前未实现，调用返回 501。

## OpenAI Files [#openai-files]

`/openai/v1/files`：上传 `user_data` 文件供后续请求引用；可列出、读元数据、下载、删除。

## OpenAI Images [#openai-images]

`POST /openai/v1/images/generations`：使用目录声明支持图像生成的模型。

## Anthropic Messages [#anthropic-messages]

`POST /anthropic/v1/messages`。Claude Code、Anthropic SDK 走这里。 具体支持范围见 [Messages API](/docs/api/compatible/anthropic/createMessage)。

## Anthropic Files [#anthropic-files]

`/anthropic/v1/files`：上传、列出、读元数据、删除；**上传后不可下载**（与官方一致）。

## Google Gemini API（generateContent） [#google-gemini-apigeneratecontent]

`POST /google/v1beta/models/{model}:generateContent`。目前用于 Gemini 原生协议的图像生成与编辑。

## 模型目录 [#模型目录]

用 `GET /openai/v1/models?api=responses` 查找支持 Responses 的模型，`api=chat,embeddings` 匹配任一协议。原生目录 `GET /model/v1/models` 及模型详情会返回每个模型的 `supported_apis`；原生列表可用 `?supported_api=openai.responses` 筛选。

`GET /openai/v1/models`：列出当前 Key 可调用的模型，OpenAI 风格返回；Kilo Code 等客户端靠它自动发现模型。

Anthropic 客户端使用 `GET /anthropic/v1/models`，Google 客户端使用 `GET /google/v1beta/models`；分别返回对应协议的模型列表。

## 标准化地址 [#标准化地址]

以上每个入口还有一个标准化长路径 `/v1/router/<vendor>/...`，语义完全相同，见 [API 参考](/docs/api/compatible)。

→ 深入：[OpenAI 兼容接口](/docs/cloud/services/model/guides/openai-compatible) · [Anthropic 兼容接口](/docs/cloud/services/model/guides/anthropic-compatible)

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 会话亲和

会话亲和让同一会话后续请求，在条件允许时优先复用之前成功的线路。它是一种选路偏好，不是锁定供应商，也不是替应用保存对话历史。

## 为什么有用 [#为什么有用]

多轮对话常重复系统提示、工具定义和早期消息。重复前缀留在同一条支持缓存的线路上，更有机会命中上游缓存，降低重复输入的费用与延迟。相同会话 ID 不保证命中缓存；内容变化、缓存失效或换线都可能让它失效。

## 如何识别同一会话 [#如何识别同一会话]

客户端可用请求体的 `session_id` 或请求头 `x-session-id` 标识会话；两者同时存在时，请求体优先。没有显式会话 ID 时，还可能使用 `prompt_cache_key` 或从对话前缀推导标识。自动推导受内容变化影响，因此长期多轮对话应保持显式标识一致，不同对话使用不同标识。

## 何时生效 [#何时生效]

缓存亲和要求该线路支持本次模型与协议、输入得到保留，并且缓存读取价格低于普通输入价格。成功完成的调用才更新亲和记录；后续请求仍须通过当前的健康与能力检查。

亲和只在同优先级范围内调整顺序，不绕过冷却或参数要求。距上次成功已空闲 10 分钟、原线路不再合适，或亲和记录不可用时，按正常路由继续；因此应用不能依赖它保证状态永远留在同一上游。

Chat 请求仍应携带需要的消息历史。有状态 Responses 的续写属于独立的协议能力，不能用会话 ID 代替 `previous_response_id`。参数说明见 [Chat API](/docs/api/compatible/openai/createChatCompletion) 与 [Responses API](/docs/api/compatible/openai/createResponse)。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# BYOK：自带模型凭证

BYOK（自带模型供应商凭证）即将推出，Console 尚未开放配置入口。目前请使用 Praxis 云 API Key 调用[模型目录](/docs/cloud/services/model/catalog)中的平台模型，由平台管理线路与计费；首次调用见[快速开始](/docs/cloud/services/model/quickstart)。

[API 参考 →](/docs/api/native/model) · [Cookbook →](/docs/cookbook)

# 指南



# OpenAI 兼容接口

OpenAI SDK 使用 `https://api.deepraxis.com/openai/v1`。请求按同协议转发；兼容不表示所有官方端点、字段和模型都可用。

## 选对地址 [#选对地址]

| 客户端              | 基础地址                                  | 模型目录                                                   |
| ---------------- | ------------------------------------- | ------------------------------------------------------ |
| OpenAI SDK       | `https://api.deepraxis.com/openai/v1` | `/openai/v1/models`                                    |
| Anthropic SDK    | `https://api.deepraxis.com/anthropic` | `/anthropic/v1/models`                                 |
| Google GenAI SDK | `https://api.deepraxis.com/google`    | `/google/v1beta/models`                                |
| Praxis 原生 API    | `https://api.deepraxis.com/model/v1`  | 见[原生 API](/docs/api/native/model)，包含 `providerOptions` |

各兼容目录只列声明提供该协议的模型。出现在 OpenAI 目录里不等于同时支持 Chat Completions 和 Responses；未声明的操作返回 `404 model_protocol_not_offered`。

## 字段差异去哪里核对 [#字段差异去哪里核对]

| 应用使用的内容                   | 发请求前核对                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| `messages`、工具、采样、思考、供应商偏好 | [Chat Completions 字段支持](/docs/api/compatible/openai/createChatCompletion)                         |
| `input`、响应存储、响应工具         | [Responses 字段支持](/docs/api/compatible/openai/createResponse)                                      |
| `usage.cost`、生成 ID        | [迁移页费用处理](/docs/cookbook/migration/from-openai#行为差异)与[生成记录](/docs/api/native/model/getGeneration) |
| 上传、文件用途                   | [上传文件](/docs/api/compatible/openai/createFile)                                                    |
| 对话以外的端点                   | [操作支持情况](/docs/api/compatible/openai)与[不支持清单及替代](/docs/cookbook/migration/from-openai#不支持的端点与替代)  |

未知顶层字段可能原样转发给同协议上游；请求被接受不证明字段已生效。已声明字段仍会校验。依赖一个选项前，请查看对应端点的字段支持说明。

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 验证 Responses [#2-验证-responses]

示例使用 `deepseek-flash`。截至 2026-10-12，`glm-5.3-flash` 也提供 Responses；`gpt-5.6-sol` 提供 Chat Completions，但不提供 Responses。使用前在[模型目录](https://console.deepraxis.ai/models)确认所需操作。

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.com/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.responses.with_raw_response.create(
    model="deepseek-flash",
    input="Reply OK.",
    max_output_tokens=1024,
)
reply = raw.parse()
text = reply.output_text
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

期望：`output_text` 是最终正文，不把思考输出当作正文。若返回 `model_protocol_not_offered`，换支持 Responses 的模型；若提示 `does not exist`，从目录复制准确 ID。已有应用回滚时同时恢复原地址、Key 与模型，再运行原冒烟请求。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook：从 OpenAI 迁移 →](/docs/cookbook/migration/from-openai)

# Anthropic 兼容接口

Anthropic SDK 使用 `https://api.deepraxis.com/anthropic`。SDK 会追加 `/v1/messages`，基础地址不要再加 `/v1`。请求按同协议转发，可用能力取决于模型的声明。

## 兼容覆盖什么 [#兼容覆盖什么]

`/anthropic/v1/models` 只列 Anthropic 兼容模型。不要假设其他协议目录里的 ID 在这里也可用。未声明的操作返回 `404`（`anthropic.messages is not offered for …`）；换地址不会把不支持的模型能力转换出来。

## 字段差异去哪里核对 [#字段差异去哪里核对]

| 应用使用的内容                           | 需要核对的差异                                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `thinking`、`output_config.effort` | 思考选项取决于模型；部分模型不能关闭思考，见 [Messages](/docs/api/compatible/anthropic/createMessage)                            |
| 缓存控制、工具、元数据、beta 或 workspace 请求头  | [Messages 字段支持](/docs/api/compatible/anthropic/createMessage)，不要假设所有官方扩展可用                                 |
| `count_tokens`                    | 带 `x-praxis-token-count: estimated` 的校准估算，见[统计 token](/docs/api/compatible/anthropic/countTokens)          |
| 模型限额与能力                           | [模型列表](/docs/api/compatible/anthropic/listModels)，未知限额可能为 `null`                                           |
| 文件上传、过期时间                         | [上传文件](/docs/api/compatible/anthropic/createFile)                                                          |
| 费用                                | [Messages 费用处理](/docs/cookbook/migration/from-anthropic#行为差异)与[生成记录](/docs/api/native/model/getGeneration) |

未知顶层字段可传到同协议上游，由上游决定是否接受；已声明字段会校验。成功响应不代表所有选项都已执行。操作支持见 [API 列表](/docs/api/compatible/anthropic)，缺失操作的处理见[迁移替代方案](/docs/cookbook/migration/from-anthropic#不支持的操作与替代)。

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 验证 Messages 与 token 统计 [#2-验证-messages-与-token-统计]

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.deepraxis.com/anthropic",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.messages.with_raw_response.create(
    model="deepseek-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Reply OK."}],
)
reply = raw.parse()
text = "".join(block.text for block in reply.content if block.type == "text")
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
count = client.messages.with_raw_response.count_tokens(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply OK."}],
)
print("count_tokens:", count.parse().input_tokens)
print("X-Request-Id:", count.headers.get("x-request-id"))
print("x-praxis-token-count:", count.headers.get("x-praxis-token-count"))
assert count.status_code == 200
assert count.headers.get("x-praxis-token-count") == "estimated"
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

期望：即使第一块是思考，仍能从 `type == "text"` 的块取得正文。第二次调用输出 token 估算与 `estimated`；不能把估算当成计费用量。

若返回 `400`（`cannot disable thinking`），移除关闭思考的要求或改选允许关闭的模型；若返回 `anthropic.messages is not offered for …`，选择 Anthropic 兼容且支持该操作的模型。已有应用回滚时恢复原地址、Key、模型与思考选项，再运行原 Messages 请求。

[API 参考 →](/docs/api/compatible/anthropic) · [Cookbook：从 Anthropic 迁移 →](/docs/cookbook/migration/from-anthropic)

# 流式响应

流式响应把一条回答拆成多个事件。显示收到的文本后，还要读取终态和用量，才能确认本轮完成。

本页使用 `POST /openai/v1/chat/completions` 的 `deepseek-flash`，并提供 `POST /anthropic/v1/messages` 的 `claude-opus-5` 示例；两者于 2026-10-12 验证通过。

## 1. 准备终端 [#1-准备终端]

将 Praxis 云 API Key 放入环境变量 `PRAXIS_API_KEY`；获取方式见 [Key 与鉴权](/docs/cloud/account/api-keys)。不要把 Key 写入代码。准备 Python 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)；TypeScript 示例使用 [Bun](https://bun.sh/docs/installation)。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

将每段 Python 保存为标明的文件名，以 `uv run -q --no-project --with openai --with anthropic python <文件名>` 执行。各段代码独立运行。

## 2. 用 Python 接收文本和末块用量 [#2-用-python-接收文本和末块用量]

保存为 `streaming.py`，运行 `uv run -q --no-project --with openai --with anthropic python streaming.py`。

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
text, finish, usage = '', None, None
with client.chat.completions.with_streaming_response.create(
    model='deepseek-flash', messages=[{'role':'user','content':'Reply with exactly: Hello streaming.'}],
    max_tokens=256, stream=True, stream_options={'include_usage':True},
) as response:
    print('X-Request-Id:', response.headers.get('x-request-id'))
    for chunk in response.parse():
        if chunk.usage is not None:
            usage = chunk.usage
        for choice in chunk.choices:
            piece = choice.delta.content or ''
            text += piece
            print(piece, end='', flush=True)
            if choice.finish_reason is not None:
                finish = choice.finish_reason
print('\nfinish_reason:', finish)
assert text.strip() and finish == 'stop', 'Incomplete text response'
assert usage is not None, 'No final usage received'
print('usage:', usage.model_dump())
```

期望：逐块输出 `Hello streaming.`，随后输出 `finish_reason: stop` 和包含输入、输出 token 数的 `usage`；退出码为 0。

Chat Completions 的读取顺序是：

1. 收集 `choices[].delta.content`；role、思考或空增量可能没有正文，不应当作文本显示。
2. 记录 `finish_reason`。本例的完整文本回答以 `stop` 结束；`tool_calls` 应进入[工具调用](/docs/cloud/services/model/guides/tool-calling)流程。
3. 设置 `stream_options.include_usage=true` 后，继续读取末块 `usage`。这一块的 `choices` 可以为空，不能直接访问 `choices[0]`。
4. HTTP 事件流以 `data: [DONE]` 收尾；SDK 负责处理该标记并结束迭代。

不要在收到 `finish_reason` 时立即跳出循环，否则会漏掉之后的用量。断开连接不等于模型完成；没有终态或末块用量时，不应把部分文本和未知用量记为完整结果。

## 3. 用 cURL 检查事件顺序 [#3-用-curl-检查事件顺序]

在同一终端执行：

```bash
curl --fail-with-body --no-buffer --silent --show-error --include \
  "${PRAXIS_API_BASE:-https://api.deepraxis.com}/openai/v1/chat/completions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: Hello streaming."}],"max_tokens":256,"stream":true,"stream_options":{"include_usage":true}}'
```

期望：HTTP 200，响应类型为 `text/event-stream`；正文增量后出现 `finish_reason: "stop"`、带 `usage` 的块，最后是 `data: [DONE]`；cURL 退出码为 0。`--no-buffer` 避免 cURL 缓冲显示，但单独退出码 0 不能证明回答完整，仍需检查终态。

## 4. 使用 Anthropic Messages [#4-使用-anthropic-messages]

Messages 依次发送 `message_start`、内容块的 `content_block_start` / `content_block_delta` / `content_block_stop`、`message_delta` 和 `message_stop`，中间可能有 `ping`。不要将它按 Chat Completions 的 `choices` 解析。输入用量在起始消息中，后续用量更新由 SDK 汇总；`get_final_message()` 返回完整结果。

保存为 `streaming-anthropic.py`，运行 `uv run -q --no-project --with openai --with anthropic python streaming-anthropic.py`。

```python
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/anthropic')
with client.messages.stream(model='claude-opus-5', max_tokens=256,
    messages=[{'role':'user','content':'Reply with exactly: Hello streaming.'}]) as stream:
    print('X-Request-Id:', stream.response.headers.get('x-request-id'))
    for text in stream.text_stream:
        print(text, end='', flush=True)
    message = stream.get_final_message()
assert message.stop_reason == 'end_turn'
assert any(block.type == 'text' and block.text.strip() for block in message.content)
print('\nusage:', message.usage.model_dump())
```

期望：输出同样的文本和最终用量，`stop_reason` 为 `end_turn`，退出码为 0。

## 实测失败与处理 [#实测失败与处理]

把 `text-embedding-3-small` 用在本页聊天请求中时，实测返回 HTTP 404：

> openai.chat.completions is not offered for text-embedding-3-small

这是模型不提供聊天端点，不是等待更多事件可以解决的问题。改用本页已验证的 `deepseek-flash` 后，文本、终态与末块用量均正常返回。

协议细节：[OpenAI](https://developers.openai.com/api/docs/guides/streaming-responses) · [Anthropic](https://platform.claude.com/docs/en/build-with-claude/streaming)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 工具调用

模型返回工具名称和参数，由你的程序执行工具，再把结果交回模型。收到工具调用还不是完成回答。

本例查询本地演示数据：Paris 的温度固定为 22°C，不访问天气服务。`deepseek-flash` 在 `GET /openai/v1/models` 的 `supported_parameters` 中列有 `tools` 和 `tool_choice`；下面的两轮调用于 2026-10-12 验证通过。

## 1. 准备终端 [#1-准备终端]

将 Praxis 云 API Key 放入环境变量 `PRAXIS_API_KEY`；获取方式见 [Key 与鉴权](/docs/cloud/account/api-keys)。不要把 Key 写入代码。准备 Python 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)；TypeScript 示例使用 [Bun](https://bun.sh/docs/installation)。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

将每段 Python 保存为标明的文件名，以 `uv run -q --no-project --with openai --with anthropic python <文件名>` 执行。各段代码独立运行。

## 2. 定义工具并完成两轮调用 [#2-定义工具并完成两轮调用]

保存为 `tool-calling.py`，运行 `uv run -q --no-project --with openai --with anthropic python tool-calling.py`。

代码先声明 `get_temperature` 的名称、描述和参数，再要求模型调用它；验证参数后执行本地查询，将结果和原始 `tool_call_id` 一起回填，最后请求文字回答。两轮都设置 `reasoning_effort="none"`。

```python
import json
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
tools = [{'type':'function','function':{
    'name':'get_temperature', 'description':'Read the demo temperature for Paris.',
    'parameters':{'type':'object','properties':{'city':{'type':'string','enum':['Paris']}},
        'required':['city'],'additionalProperties':False}}}]
messages = [{'role':'user','content':'Use get_temperature for Paris, then tell me the temperature in Celsius.'}]
first = client.chat.completions.create(model='deepseek-flash', messages=messages,
    tools=tools, reasoning_effort='none', tool_choice={'type':'function','function':{'name':'get_temperature'}}, max_tokens=1024)
print('X-Request-Id:', first._request_id)
message = first.choices[0].message
assert first.choices[0].finish_reason == 'tool_calls' and message.tool_calls
messages.append(message.model_dump(exclude_none=True))
for call in message.tool_calls:
    assert call.function.name == 'get_temperature'
    args = json.loads(call.function.arguments)
    assert args == {'city':'Paris'}, args
    result = {'city':args['city'], 'temperature_c':22}
    messages.append({'role':'tool','tool_call_id':call.id,'content':json.dumps(result)})
second = client.chat.completions.create(model='deepseek-flash', messages=messages,
    tools=tools, reasoning_effort='none', tool_choice='none', max_tokens=1024)
print('X-Request-Id:', second._request_id)
answer = second.choices[0].message.content or ''
assert second.choices[0].finish_reason == 'stop' and '22' in answer, answer
print(answer)
```

期望：第一轮 `finish_reason=tool_calls`，函数参数是 `{"city":"Paris"}`；第二轮回答包含 `22`，`finish_reason=stop`；退出码为 0。

保留第一轮完整 assistant 消息，为每个工具调用返回一条 `role="tool"` 消息。不要重造调用 ID，也不要只把结果作为普通用户文字发回。参数是 JSON 字符串，需要解析和校验；不要直接执行模型提供的任意函数名。这里用 `tool_choice="none"` 明确结束工具阶段；使用 `auto` 的实际应用应允许多轮工具调用，并设置轮数上限。

## 3. 用 TypeScript 执行同一流程 [#3-用-typescript-执行同一流程]

保存为 `tool-calling.ts`，运行 `bun tool-calling.ts`；使用内置 `fetch`，无需安装 SDK。

```typescript
import assert from 'node:assert/strict';
const base = process.env.PRAXIS_API_BASE ?? 'https://api.deepraxis.com';
async function chat(body: object) {
  const response = await fetch(`${base}/openai/v1/chat/completions`, {
    method: 'POST', headers: {'Authorization': `Bearer ${process.env.PRAXIS_API_KEY}`, 'Content-Type': 'application/json'},
    body: JSON.stringify({model: 'deepseek-flash', max_tokens: 1024, reasoning_effort: 'none', ...body}),
  });
  console.log('X-Request-Id:', response.headers.get('x-request-id'));
  const data = await response.json();
  assert(response.ok, JSON.stringify(data));
  return data;
}
const tools = [{type: 'function', function: {name: 'get_temperature',
  description: 'Read the demo temperature for Paris.',
  parameters: {type: 'object', properties: {city: {type: 'string', enum: ['Paris']}},
    required: ['city'], additionalProperties: false}}}];
const messages: any[] = [{role: 'user', content: 'Use get_temperature for Paris, then tell me the temperature in Celsius.'}];
const first = await chat({messages, tools, tool_choice: {type: 'function', function: {name: 'get_temperature'}}});
const choice = first.choices[0];
assert.equal(choice.finish_reason, 'tool_calls');
assert(choice.message.tool_calls?.length);
messages.push(choice.message);
for (const call of choice.message.tool_calls) {
  assert.equal(call.function.name, 'get_temperature');
  const args = JSON.parse(call.function.arguments);
  assert.deepEqual(args, {city: 'Paris'});
  messages.push({role: 'tool', tool_call_id: call.id,
    content: JSON.stringify({city: args.city, temperature_c: 22})});
}
const second = await chat({messages, tools, tool_choice: 'none'});
assert.equal(second.choices[0].finish_reason, 'stop');
assert(second.choices[0].message.content.includes('22'));
console.log(second.choices[0].message.content);
```

期望：完成相同的工具调用与回填，最终回答包含 `22`，退出码为 0。

## 4. 使用 Anthropic Messages [#4-使用-anthropic-messages]

Messages 用 `input_schema` 定义参数，返回 `tool_use` 内容块和 `stop_reason="tool_use"`。将完整 assistant 内容带回后，在下一条 `role="user"` 消息中放入 `tool_result`，用 `tool_use_id` 对应原调用。本例的 `claude-opus-5` 已实测通过。

保存为 `tool-calling-anthropic.py`，运行 `uv run -q --no-project --with openai --with anthropic python tool-calling-anthropic.py`。

```python
import json
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/anthropic')
tools = [{'name':'get_temperature','description':'Read the demo temperature for Paris.',
    'input_schema':{'type':'object','properties':{'city':{'type':'string','enum':['Paris']}},
        'required':['city'],'additionalProperties':False}}]
messages = [{'role':'user','content':'Use get_temperature for Paris, then tell me the temperature in Celsius.'}]
raw = client.messages.with_raw_response.create(model='claude-opus-5', max_tokens=1024,
    tools=tools, tool_choice={'type':'tool','name':'get_temperature'}, messages=messages)
print('X-Request-Id:', raw.headers.get('x-request-id'))
first = raw.parse()
assert first.stop_reason == 'tool_use'
messages.append({'role':'assistant','content':[block.model_dump(exclude_none=True) for block in first.content]})
results = []
for block in first.content:
    if block.type == 'tool_use':
        assert block.name == 'get_temperature' and block.input == {'city':'Paris'}
        results.append({'type':'tool_result','tool_use_id':block.id,
            'content':json.dumps({'city':'Paris','temperature_c':22})})
assert results
messages.append({'role':'user','content':results})
raw = client.messages.with_raw_response.create(model='claude-opus-5', max_tokens=1024,
    tools=tools, tool_choice={'type':'none'}, messages=messages)
print('X-Request-Id:', raw.headers.get('x-request-id'))
second = raw.parse()
answer = ''.join(block.text for block in second.content if block.type == 'text')
assert second.stop_reason == 'end_turn' and '22' in answer, answer
print(answer)
```

期望：第一轮请求工具，第二轮返回包含 `22` 的文本，`stop_reason=end_turn`，退出码为 0。

## 实测失败与处理 [#实测失败与处理]

强制指定函数、但没有关闭思考时，`deepseek-flash` 返回 HTTP 400：

> tool\_choice a named function is not supported while thinking is enabled on this model. Set reasoning effort to "none" or use tool\_choice "auto".

本页采用已验证的解决办法：显式设置 `reasoning_effort="none"`。仅第一轮设置、第二轮省略时，还曾收到 HTTP 400：

> The selected thinking setting is not supported on this model route.

两轮都保留 `reasoning_effort="none"` 后通过。不要在重试时丢掉该参数。

协议细节：[OpenAI](https://developers.openai.com/api/docs/guides/function-calling) · [Anthropic](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 结构化输出

结构化输出将回答约束为指定的 JSON 结构；接收端仍需检查终态、解析 JSON 并验证业务字段。

## 选择支持的模型 [#选择支持的模型]

先查看 `GET /openai/v1/models` 中的 `supported_parameters`：候选模型应列有 `response_format` 和 `structured_outputs`。2026-10-12，`gpt-5.6-sol` 的 Chat Completions `json_schema` + `strict` 和 `claude-opus-5` 的 Messages `output_config` 均实测通过，下面分别使用它们。

`deepseek-flash` 虽列有上述参数，本次 `json_schema` 请求仍返回 400，因此本页不使用它演示 schema 约束。目录声明不能替代实际响应验证。`json_object`（JSON mode）只表达 JSON 格式要求，不等于 schema 约束；需要固定字段和类型时使用本页的 `json_schema`。

## 1. 准备终端 [#1-准备终端]

将 Praxis 云 API Key 放入环境变量 `PRAXIS_API_KEY`；获取方式见 [Key 与鉴权](/docs/cloud/account/api-keys)。不要把 Key 写入代码。准备 Python 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)；TypeScript 示例使用 [Bun](https://bun.sh/docs/installation)。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

将每段 Python 保存为标明的文件名，以 `uv run -q --no-project --with openai --with anthropic python <文件名>` 执行。各段代码独立运行。

## 2. 使用 json\_schema 和 strict [#2-使用-json_schema-和-strict]

保存为 `structured-output.py`，运行 `uv run -q --no-project --with openai --with anthropic python structured-output.py`。

`response_format.json_schema` 中同时给出 `name`、`strict: true` 和 `schema`。本例将所有属性列入 `required`，并用 `additionalProperties: false` 禁止额外字段。

```python
import json
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
schema = {'type':'object', 'properties':{
    'city':{'type':'string'}, 'temperature':{'type':'integer'}},
    'required':['city','temperature'], 'additionalProperties':False}
response = client.chat.completions.create(model='gpt-5.6-sol', max_tokens=1024,
    messages=[{'role':'user','content':'Return JSON for Paris with temperature 22.'}],
    response_format={'type':'json_schema','json_schema':{
        'name':'weather','strict':True,'schema':schema}})
print('X-Request-Id:', response._request_id)
choice = response.choices[0]
assert choice.finish_reason == 'stop' and not choice.message.refusal
value = json.loads(choice.message.content)
assert set(value) == {'city','temperature'}
assert isinstance(value['city'], str) and type(value['temperature']) is int
assert value == {'city':'Paris','temperature':22}, value
print(value)
```

期望：输出 `{'city': 'Paris', 'temperature': 22}`，退出码为 0。代码不剥除 Markdown 围栏；只有直接可解析、字段和类型符合要求的 JSON 才通过。

先检查 `finish_reason` 和 `refusal`，再解析内容。被截断或拒绝的回答不能当成符合 schema 的业务结果；流式回答应先收齐文本再解析。

## 3. 用 TypeScript 验证相同结果 [#3-用-typescript-验证相同结果]

保存为 `structured-output.ts`，运行 `bun structured-output.ts`；无需安装 SDK。

```typescript
import assert from 'node:assert/strict';
const base = process.env.PRAXIS_API_BASE ?? 'https://api.deepraxis.com';
const schema = {type: 'object', properties: {
  city: {type: 'string'}, temperature: {type: 'integer'}},
  required: ['city', 'temperature'], additionalProperties: false};
const response = await fetch(`${base}/openai/v1/chat/completions`, {
  method: 'POST', headers: {'Authorization': `Bearer ${process.env.PRAXIS_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({model: 'gpt-5.6-sol', max_tokens: 1024,
    messages: [{role: 'user', content: 'Return JSON for Paris with temperature 22.'}],
    response_format: {type: 'json_schema', json_schema: {name: 'weather', strict: true, schema}}}),
});
console.log('X-Request-Id:', response.headers.get('x-request-id'));
const data = await response.json();
assert(response.ok, JSON.stringify(data));
const choice = data.choices[0];
assert.equal(choice.finish_reason, 'stop');
assert(!choice.message.refusal);
const value = JSON.parse(choice.message.content);
assert.deepEqual(value, {city: 'Paris', temperature: 22});
console.log(value);
```

期望：同样得到 `city=Paris`、整数 `temperature=22`，没有额外字段，退出码为 0。

## 4. 使用 Messages 的 output\_config [#4-使用-messages-的-output_config]

Messages 将 schema 放在 `output_config.format` 下，`type` 为 `json_schema`；不要把 Chat Completions 的 `response_format` 或 `json_schema.name` 外壳搬过来。这里也不添加 OpenAI 的 `strict` 字段。

保存为 `structured-output-anthropic.py`，运行 `uv run -q --no-project --with openai --with anthropic python structured-output-anthropic.py`。

```python
import json
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/anthropic')
schema = {'type':'object', 'properties':{
    'city':{'type':'string'}, 'temperature':{'type':'integer'}},
    'required':['city','temperature'], 'additionalProperties':False}
raw = client.messages.with_raw_response.create(model='claude-opus-5', max_tokens=1024,
    messages=[{'role':'user','content':'Return JSON for Paris with temperature 22.'}],
    output_config={'format':{'type':'json_schema','schema':schema}})
print('X-Request-Id:', raw.headers.get('x-request-id'))
message = raw.parse()
assert message.stop_reason == 'end_turn'
value = json.loads(''.join(block.text for block in message.content if block.type == 'text'))
assert set(value) == {'city','temperature'}
assert isinstance(value['city'], str) and type(value['temperature']) is int
assert value == {'city':'Paris','temperature':22}, value
print(value)
```

期望：`stop_reason=end_turn`，JSON 验证通过并输出相同对象，退出码为 0。

## 实测失败与处理 [#实测失败与处理]

`deepseek-flash` 的 schema 请求返回 HTTP 400，错误消息的固定部分为：

> This response\_format type is unavailable now

消息还会附带当次请求标识。切换为本页已实测通过的 `gpt-5.6-sol` 后通过。不要将 HTTP 200、Markdown 中的一段 JSON 或能解析的普通 JSON 当成 schema 约束已生效；保留示例中的完整验证。

协议细节：[OpenAI](https://developers.openai.com/api/docs/guides/structured-outputs) · [Anthropic](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 调整思考强度

同一个“低”档，在 Chat、Messages 和 Google 中使用不同字段。先选模型支持的协议与档位，再查看响应中的思考用量；档位是提示，实际消耗以 usage 为准。

## 选择协议与档位 [#选择协议与档位]

打开[控制台 → 模型目录](https://console.deepraxis.ai/models)，点进模型详情的「协议与思考档位」。期望：看到该模型支持的调用方式和思考选项；没有“关闭”时，不要发送关闭思考的设置。

用 `GET /model/v1/models` 的 `supported_apis` 确认协议；Chat 目录 `GET /openai/v1/models?api=chat` 的 `reasoning.supported_efforts` 和 `reasoning.mandatory` 可用于程序检查。2026-10-13 的 Chat 目录将 `glm-5.3`、`glm-5.3-flash` 和 `kimi-k3` 标为 `mandatory=true`，即不能关闭思考；调用前仍需重查目录。不要假设每个模型都有全部档位。下列用量字段是本页所选模型实测返回的字段，不保证所有模型都提供明细。

| 调用方式                   | 设置思考的入口                                                                 | 本页读取的用量                                            |
| ---------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| Chat Completions       | `reasoning_effort`；也接受 `reasoning` 对象                                   | `usage.completion_tokens_details.reasoning_tokens` |
| Anthropic Messages     | `thinking` 控制模式，`output_config.effort` 选择档位                             | `usage.output_tokens_details.thinking_tokens`      |
| Google generateContent | `generationConfig.thinkingConfig` 中的 `thinkingBudget` 或 `thinkingLevel` | `usageMetadata.thoughtsTokenCount`                 |

Chat 的档位范围从 `none` 到 `max`，实际可选项以模型为准；`none` 表示关闭，不是“低”。Messages 的 `enabled`、`adaptive`、`disabled` 分别表达预算思考、自适应思考和关闭，不能把 `thinking.effort` 当作档位字段。Google 的预算和档位随模型而异，不要同时发送两种控制。

完整字段定义见 [Chat](/docs/api/compatible/openai/createChatCompletion)、[Messages](/docs/api/compatible/anthropic/createMessage)、[Google](/docs/api/compatible/google/generateContent)。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. Chat：设为低并读取用量 [#2-chat设为低并读取用量]

`deepseek-flash` 支持 Chat 和 `low`。

保存为 `reasoning-chat.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python reasoning-chat.py`。

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
response = client.chat.completions.create(
    model='deepseek-flash', reasoning_effort='low', max_tokens=2048,
    messages=[{'role': 'user', 'content': 'What is 17 times 23? Answer briefly.'}])
assert response.choices[0].finish_reason == 'stop'
assert '391' in (response.choices[0].message.content or '')
details = response.usage.completion_tokens_details
assert details is not None and details.reasoning_tokens is not None, 'Reasoning usage was not reported'
print('X-Request-Id:', response._request_id)
print('answer:', response.choices[0].message.content)
print('reasoning_tokens:', details.reasoning_tokens)
```

期望：回答包含 `391`，终态为 `stop`，打印实际 `reasoning_tokens`，退出码 0。数字会随调用变化。

## 3. Messages：设为低并读取用量 [#3-messages设为低并读取用量]

这里选用 `claude-opus-5`，因为本次验证中它会返回思考 token 明细。`deepseek-flash` 的 Messages 响应未返回该明细；缺失不等于 0，也不能用 `output_tokens` 代替。

保存为 `reasoning-messages.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python reasoning-messages.py`。

```python
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/anthropic')
raw = client.messages.with_raw_response.create(
    model='claude-opus-5', max_tokens=2048,
    thinking={'type': 'adaptive'}, output_config={'effort': 'low'},
    messages=[{'role': 'user', 'content': 'What is 17 times 23? Answer briefly.'}])
response = raw.parse()
answer = ''.join(block.text for block in response.content if block.type == 'text')
assert response.stop_reason == 'end_turn' and '391' in answer
usage = response.usage.model_dump()
details = usage.get('output_tokens_details') or {}
assert details.get('thinking_tokens') is not None, 'Thinking usage was not reported'
print('X-Request-Id:', raw.headers.get('x-request-id'))
print('answer:', answer)
print('thinking_tokens:', details['thinking_tokens'])
```

期望：回答包含 `391`，终态为 `end_turn`，打印实际 `thinking_tokens`，退出码 0。

## 4. Google：按模型选预算或档位 [#4-google按模型选预算或档位]

以下依次调用两个模型：`gemini-2.5-flash` 使用预算，`gemini-3.1-flash-lite-preview` 使用低档。使用 HTTP 是为了直接展示 Google 的字段名。

保存为 `reasoning-google.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python reasoning-google.py`。

```python
import json
import os
import httpx

base = os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com')
with httpx.Client(timeout=120) as client:
    for model, thinking in [
        ('gemini-2.5-flash', {'thinkingBudget': 1024}),
        ('gemini-3.1-flash-lite-preview', {'thinkingLevel': 'low'}),
    ]:
        response = client.post(base + '/google/v1beta/models/' + model + ':generateContent',
            headers={'Authorization': 'Bearer ' + os.environ['PRAXIS_API_KEY']},
            json={'contents': [{'role': 'user', 'parts': [{'text': 'What is 17 times 23? Answer briefly.'}]}],
                  'generationConfig': {'maxOutputTokens': 2048, 'thinkingConfig': thinking}})
        print('X-Request-Id:', response.headers.get('x-request-id'))
        response.raise_for_status()
        data = response.json()
        candidate = data['candidates'][0]
        answer = ''.join(part.get('text', '') for part in candidate['content']['parts'])
        assert candidate['finishReason'] == 'STOP' and '391' in answer
        assert 'thoughtsTokenCount' in data['usageMetadata'], 'Thinking usage was not reported'
        print(model, answer, json.dumps(data['usageMetadata']))
```

期望：两次回答都包含 `391`，终态为 `STOP`，各自打印 `thoughtsTokenCount`，退出码 0。

## 如何比较结果 [#如何比较结果]

保持模型和问题一致，多次采样，比较实际思考 token、完整回答、耗时与质量。预算不是跨模型统一的硬上限；“低”不保证每次都比“高”少用 token，也不保证更快。不要根据一条响应推断单调关系。用量字段缺失时，保留“未报告”，不要填 0。

## 实测失败与处理 [#实测失败与处理]

`glm-5.3` 设置 `reasoning_effort="none"` 返回 HTTP 400，错误码 `thinking_disable_unsupported`：

> glm-5.3 cannot disable thinking; omit the thinking setting or choose a level.

省略关闭设置或选择模型支持的档位，再请求。不要靠换成另一个协议的“关闭”字段绕过限制。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# Responses API

只有声明 `openai.responses` 的模型才能使用 Responses。支持 Chat Completions 不代表支持 Responses。用 `GET /openai/v1/models?api=responses` 查询；2026-10-13 返回 `deepseek-flash` 和 `glm-5.3-flash`。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. 接着上一条响应提问 [#2-接着上一条响应提问]

平台会展开 `previous_response_id` 引用的历史。第二次调用只发送新问题和第一条响应 ID。两次使用相同 Key 和模型；示例检查第二条回答能取回未出现在新问题中的代码。

保存为 `responses.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python responses.py`。

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
models = client.models.list(extra_query={'api': 'responses'})
print('X-Request-Id:', models._request_id)
assert 'deepseek-flash' in [model.id for model in models]
first = client.responses.create(model='deepseek-flash',
    input='Remember this code: LIME-742. Reply OK.',
    reasoning={'effort': 'none'}, max_output_tokens=512)
print('X-Request-Id:', first._request_id)
assert first.status == 'completed' and first.id
second = client.responses.create(model='deepseek-flash',
    previous_response_id=first.id, input='What was the code? Reply with only the code.',
    reasoning={'effort': 'none'}, max_output_tokens=512)
print('X-Request-Id:', second._request_id)
assert second.status == 'completed' and 'LIME-742' in second.output_text
assert second.usage is not None
print('answer:', second.output_text)
print('usage:', second.usage.model_dump())
```

期望：两条响应均为 `completed`，第二条回答包含 `LIME-742` 并打印用量，退出码 0。复用历史不意味着输入免费，应逐轮查看 usage。

## 限制与实测失败 [#限制与实测失败]

`POST /openai/v1/responses/compact` 与 `POST /openai/v1/responses/input_tokens` 当前返回 HTTP 501，错误码 `not_implemented`。不要依赖它们压缩对话或预先计数；由应用控制历史长度，完成后读取实际用量。

用 `gpt-5.6-sol` 请求实测返回 HTTP 404，错误码 `model_protocol_not_offered`。改选 Responses 筛选目录中的模型。若示例目录断言失败，先重查该目录再重试。其他网关的响应 ID 不随地址迁移，应重建必要的历史。

参数见[生成响应](/docs/api/compatible/openai/createResponse)，各操作支持状态见 [OpenAI API 参考](/docs/api/compatible/openai)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 读取图片、PDF 和文本文件

先确认模型同时支持所选协议和输入类型。查看 `GET /model/v1/models` 的 `supported_apis`、`architecture.input_modalities` 和 `x_praxis.input_modalities`：`native` 表示原生输入，`converted` 表示经过转换，`unsupported` 表示不可用。支持图片不代表支持音频或视频。

本例用 `deepseek-flash` 读取内联图片，用 `qwen3.8-flash` 读取 PDF 和文本的 `file_id` 引用；后者声明原生 PDF 输入。文件上传和生命周期细节见[文件服务指南](/docs/cloud/services/file)。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. 发送已知内容并校验回答 [#2-发送已知内容并校验回答]

脚本在本地构造红色 PNG、单页 PDF 和文本文件。先校验图片颜色，再以 `purpose=user_data` 上传两个文档并询问校验码。每个上传文件都在 `finally` 中删除，包括回答检查失败的情况，无需自备文件。

保存为 `multimodal.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python multimodal.py`。

```python
import base64
import os
import struct
import zlib
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')

# Build a 128 x 128 red PNG using only the Python standard library.
def chunk(kind, data):
    return struct.pack('>I', len(data)) + kind + data + struct.pack('>I', zlib.crc32(kind + data))
image = (b'\x89PNG\r\n\x1a\n'
    + chunk(b'IHDR', struct.pack('>IIBBBBB', 128, 128, 8, 2, 0, 0, 0))
    + chunk(b'IDAT', zlib.compress((b'\x00' + b'\xff\x00\x00' * 128) * 128))
    + chunk(b'IEND', b''))
response = client.chat.completions.create(model='deepseek-flash', reasoning_effort='none', max_tokens=256,
    messages=[{'role': 'user', 'content': [
        {'type': 'text', 'text': 'Name the main color in this image in English.'},
        {'type': 'image_url', 'image_url': {'url': 'data:image/png;base64,' + base64.b64encode(image).decode()}},
    ]}])
print('X-Request-Id:', response._request_id)
answer = response.choices[0].message.content or ''
assert response.choices[0].finish_reason == 'stop' and 'red' in answer.lower(), answer
print('image:', answer)

# Build a one-page PDF with selectable text.
text = b'The verification code is LIME-742.'
stream = b'BT /F1 18 Tf 50 100 Td (' + text + b') Tj ET'
objects = [b'<< /Type /Catalog /Pages 2 0 R >>',
    b'<< /Type /Pages /Kids [3 0 R] /Count 1 >>',
    b'<< /Type /Page /Parent 2 0 R /MediaBox [0 0 400 200] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>',
    b'<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>',
    b'<< /Length ' + str(len(stream)).encode() + b' >>\nstream\n' + stream + b'\nendstream']
pdf, offsets = b'%PDF-1.4\n', [0]
for index, obj in enumerate(objects, 1):
    offsets.append(len(pdf))
    pdf += f'{index} 0 obj\n'.encode() + obj + b'\nendobj\n'
xref = len(pdf)
pdf += b'xref\n0 6\n0000000000 65535 f \n'
pdf += b''.join(f'{offset:010d} 00000 n \n'.encode() for offset in offsets[1:])
pdf += f'trailer\n<< /Size 6 /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n'.encode()

for name, data, mime in [('code.pdf', pdf, 'application/pdf'), ('code.txt', text, 'text/plain')]:
    file = client.files.create(file=(name, data, mime), purpose='user_data')
    print('upload X-Request-Id:', file._request_id)
    try:
        response = client.chat.completions.create(model='qwen3.8-flash', reasoning_effort='none', max_tokens=256,
            messages=[{'role': 'user', 'content': [
                {'type': 'text', 'text': 'What is the verification code in the file? Reply with only the code.'},
                {'type': 'file', 'file': {'file_id': file.id}},
            ]}])
        print('chat X-Request-Id:', response._request_id)
        answer = response.choices[0].message.content or ''
        assert response.choices[0].finish_reason == 'stop' and 'LIME-742' in answer, answer
        print(name, answer)
    finally:
        deleted = client.files.delete(file.id)
        print('delete X-Request-Id:', deleted._request_id)
        assert deleted.deleted
```

期望：图片回答包含 `red`，`code.pdf` 和 `code.txt` 都返回 `LIME-742`，两个删除操作成功，退出码 0。仅 HTTP 成功不够，内容断言也必须通过。

## 实测失败与处理 [#实测失败与处理]

同一 PDF 使用 `deepseek-flash` 时，HTTP 200，但回答说：

> I wasn't able to read the attached PDF

该模型目录标注 PDF 为转换输入，这次未能证明成功读取。将文档请求切到原生 PDF 输入的 `qwen3.8-flash` 后，内容校验通过。遇到无法读取时，选已验证模型或直接提供相关文本；不要仅凭回答看似合理就认为文件已读到。请求结束前保持文件可用。

本页验证的 `file_id` 路径接受 PDF 和文本，不限于图片；这不代表所有模型支持所有文件类型。参数见 [Chat Completions](/docs/api/compatible/openai/createChatCompletion)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 生成与编辑图像

使用 OpenAI Images API 的 `gpt-image-2` 生成和编辑图片。调用前查 `GET /openai/v1/models?api=images`；原生模型目录分别声明 `openai.images.generations` 和 `openai.images.edits`。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. 生成并编辑 [#2-生成并编辑]

在可写目录运行。示例会产生两次图像调用费用：生成一次、编辑一次，并保存 `circle.png` 与 `circle-edited.png`；使用新目录避免覆盖同名文件。示例关闭自动重试。

保存为 `images.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python images.py`。

```python
import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1',
    timeout=180, max_retries=0)
models = client.models.list(extra_query={'api': 'images'})
print('X-Request-Id:', models._request_id)
assert 'gpt-image-2' in [model.id for model in models]

def save(response, filename):
    print('X-Request-Id:', response._request_id)
    assert len(response.data) == 1 and response.data[0].b64_json
    image = base64.b64decode(response.data[0].b64_json, validate=True)
    assert image.startswith(b'\x89PNG\r\n\x1a\n'), 'Expected PNG output'
    Path(filename).write_bytes(image)
    assert response.usage is not None, 'Usage was not reported'
    print(filename, len(image), 'bytes; usage:', response.usage.model_dump())

save(client.images.generate(model='gpt-image-2',
    prompt='A single blue circle centered on a plain white background.',
    n=1, size='1024x1024', quality='low'), 'circle.png')
with open('circle.png', 'rb') as image:
    save(client.images.edit(model='gpt-image-2', image=image,
        prompt='Change the blue circle to a red circle. Keep the white background.',
        n=1, size='1024x1024', quality='low'), 'circle-edited.png')
```

期望：两个文件都是非空 PNG，每次响应包含一张图片和 token 用量，退出码 0。打开图片：第一张应为白底蓝圆，第二张应为白底红圆。文件签名检查验证格式，不代替画面检查。

## 3. 查看图像费用 [#3-查看图像费用]

`gpt-image-2` 按 token 计价，不是每张固定价。文本输入、图像输入、图像输出分别计价；编辑还会产生输入图像 token。查看响应中的用量，以及[模型目录](https://console.deepraxis.ai/models/gpt-image-2)中的实时价格；账户汇总见[用量与费用](/docs/cloud/account/billing)。

若目录断言失败，先停止生成，选择当前可用的图像模型。若输出断言失败，保留请求 ID 和响应错误，不要为排查文件问题反复生成。

操作细节：[生成](/docs/api/compatible/openai/createImage)与[编辑](/docs/api/compatible/openai)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 在对话中引用文件

上传、过期、下载与删除见[文件服务](/docs/cloud/services/file)。

对话中可用 `file_id` 引用以 `purpose=user_data` 上传的图片、文本或 PDF，通过消息中的 `{"type":"file","file":{"file_id":"上传返回的 ID"}}` 传入。文件被接受不代表所选模型能读出内容；用途为 `vision` 或 `assistants` 的文件不作为这里的图片输入。

2026-10-13 在 Develop 复核：`qwen3.8-flash` 能从文本和 PDF 中读出指定短语。`deepseek-flash` 引用同一 PDF 时返回 HTTP 200，但回答明确表示转换失败（`provider_rejected`）、未读取文件。遇到这种情况，换用已验证可读的模型，或把提取出的文本直接放入消息；不要把 HTTP 200 当成读取成功。

图片输入仍需选择支持图片的模型；下例使用 `qwen3-vl-plus`。

安装 `openai`，设置 `PRAXIS_API_KEY`。使用 Develop 时，另设 `PRAXIS_API_BASE=https://api-develop.deepraxis.ai`。示例上传一张小 PNG，获取描述后删除文件。

```python
import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRAXIS_API_KEY"],
    base_url=os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com") + "/openai/v1",
)
image = base64.b64decode(
    "iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABWklEQVR4nO3OQQ0AMBAEofVv+iqDxzRBALvtg/wgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwg7gEgaMOyrMtNTwAAAABJRU5ErkJggg=="
)
file = client.files.create(file=("pixel.png", image, "image/png"), purpose="user_data")
try:
    response = client.chat.completions.create(
        model="qwen3-vl-plus",
        max_tokens=80,
        messages=[{"role": "user", "content": [
            {"type": "text", "text": "Describe this image in one sentence."},
            {"type": "file", "file": {"file_id": file.id}},
        ]}],
    )
    print(response.choices[0].message.content)
finally:
    client.files.delete(file.id)
```

期望：输出一句图片描述；请求结束后文件被删除。

# 插件

插件在模型调用前后处理请求或响应，让模型可以使用经过转换的输入。它们不会改变模型本身的原生能力。`file-parser` 是第一个插件：在需要时，把文档或图片转换为文字，再交给你选择的模型。

同一套 `plugins` 参数适用于 `/model/v1/chat/completions`、`/model/v1/messages` 和 `/model/v1/responses` 的创建请求，支持流式和非流式。参数由平台消费，不会作为模型参数传给上游。

## 配置与默认行为 [#配置与默认行为]

在请求体中加入 `plugins` 数组，每个配置用 `id` 指定插件：

```json
{
  "plugins": [
    { "id": "file-parser", "enabled": true }
  ]
}
```

未传 `plugins` 或传 `plugins: []` 都表示沿用默认配置，**不表示关闭**。当前文件解析默认开启；模型能原生处理的 PDF 和图片，在符合模型限制时直接传递。否则，文字 PDF 和 Office 文档在本地提取文字，扫描页使用 OCR，图片使用 OCR 和视觉描述。提取出的文字占用主模型的上下文窗口。

关闭转换使用：

```json
{
  "plugins": [
    { "id": "file-parser", "enabled": false }
  ]
}
```

关闭后，原生支持的输入仍可使用；模型不支持的输入会被拒绝。配置会检查插件 ID、字段和取值，未知配置不会被静默忽略。

### PDF 处理方式 [#pdf-处理方式]

| `pdf.engine` | 行为                                               |
| ------------ | ------------------------------------------------ |
| `auto`（默认模式） | 优先原生处理；需要转换时提取文字，并对扫描页或文字不足的页使用 OCR。             |
| `native`     | 只允许原生 PDF 输入。模型不支持或超过原生限制时拒绝，不自动转为文字。            |
| `ocr`        | 强制走文字转换，即使模型支持原生 PDF；有可用文字的页仍本地提取，需要识别的页才调用 OCR。 |

请求中**省略 `pdf.engine` 会继承默认配置**；没有租户或平台覆盖时即为自动模式。当前请求参数只接受显式的 `native` 或 `ocr`，不能用字符串 `"auto"` 覆盖已有默认。可在控制台将租户 PDF 默认方式设为自动。

```json
{
  "plugins": [
    { "id": "file-parser", "pdf": { "engine": "ocr" } }
  ]
}
```

`pdf.engine` 只影响 PDF。可用 `"image": { "describe": false }` 关闭非原生图片转换；它不关闭原生视觉输入，也不影响文档。

### 配置优先级 [#配置优先级]

从高到低：**平台策略 > 租户锁定 > 本次请求 > 租户默认 > 插件默认**。

平台策略决定的值不可被覆盖。租户锁定后，请求尝试改变锁定值会返回 `PLUGIN_SETTING_LOCKED`。没有锁定的字段可以在本次请求中覆盖，且不会修改租户默认配置。文件大小、页数等平台限制不可通过请求调整。

## 费用 [#费用]

* 本地文字提取不产生额外模型用量；转换后的文字仍按主模型输入计费。
* OCR 按实际处理页数计量，图片描述按描述模型的输入、缓存输入和输出用量计量；单价以所用模型的价格为准。
* OCR、图片描述和主模型是各自的用量记录。主模型失败不会抹掉已经发生的转换用量。
* 命中解析缓存不发起新的转换子调用，因此不新增这部分用量；下一轮主模型仍按实际输入和输出计费。

## 解析注明与下一轮带回 [#解析注明与下一轮带回]

转换成功的响应会携带文件注明（annotations）。保留完整对象，不要修改哈希或解析内容：

```json
{
  "type": "file",
  "file": {
    "hash": "<原样保留服务返回的哈希>",
    "name": "notes.pdf",
    "content": [{ "type": "text", "text": "解析出的文字" }]
  }
}
```

| 入口                 | 非流式位置                                                          | 流式位置                                                                   |
| ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Chat Completions   | `choices[].message.annotations`                                | `choices[].delta.annotations`，每个 choice 返回一次                           |
| Anthropic Messages | 响应消息顶层 `annotations`                                           | `message_start.message.annotations`                                    |
| Responses          | `output[]` 中 message 的 `content[]` 内 `output_text.annotations` | `response.content_part.done`、`response.output_item.done` 和响应终态中的对应文字快照 |

已有的引用注明及其下标会保留；Responses 的未完成快照不插入文件注明，完成快照才附加。Messages 的顶层字段和 Responses 中的 `type: "file"` 是平台扩展；不要把文件注明变成 Anthropic content block。只有实际转换才产生这些注明，原生直传不产生。Responses 若只返回工具调用、拒绝块或空输出，不会为携带注明而合成文字消息。

下一轮保留原始用户输入和上一轮 assistant 内容，把注明一同带回：

```js
// Chat Completions
messages.push(response.choices[0].message);

// Anthropic Messages：保留顶层扩展字段
messages.push({
  role: "assistant",
  content: response.content,
  annotations: response.annotations,
});

// Responses：保留 output_text 的 annotations
input.push(...response.output);
```

然后追加新的用户问题。流式客户端同样保留聚合结果中的注明；若自行组装消息，需从上述事件位置收集它们。SDK 类型未声明扩展字段时，使用其额外字段机制或读取原始 JSON。

带回内容与服务端解析结果、原文件、配置及模型能力匹配时，会跳过重新解析。修改内容、切换配置或缓存不可用时，不保证复用；客户端注明不能自行证明“已解析”。即使不再携带原文件，注明中的文字也会作为普通对话上下文送给模型。单独传 `previous_response_id` 不等于显式带回文件注明。

## 查看模型支持方式 [#查看模型支持方式]

`GET /model/v1/models` 的 `architecture.input_modalities` 使用 OpenRouter 形状，只列原生模态。原生 PDF 能力表示为 `file`，不会因启用插件而加入这一数组。

扩展字段 `x_praxis.input_modalities` 按输入类型标注 `native`、`converted` 或 `unsupported`：

```json
{
  "architecture": { "input_modalities": ["text"] },
  "x_praxis": {
    "input_modalities": {
      "text": "native",
      "image": "converted",
      "pdf": "converted",
      "docx": "converted",
      "pptx": "converted",
      "xlsx": "converted",
      "audio": "unsupported",
      "video": "unsupported"
    }
  }
}
```

这是一个仅支持原生文字的对话模型的示例。标注由模型能力和已注册插件推导；`converted` 表示存在转换路径，实际请求还受租户设置、请求配置和限额约束。嵌入、OCR 等非对话调用不因此获得对话插件。音频、视频目前没有转换插件，只有模型原生支持时才可输入。

## 限制 [#限制]

* 需要转换的文件必须提供内联内容，或使用当前入口支持的已授权文件引用；插件不下载任意外部 URL。
* 当前支持 PDF、DOCX、PPTX、XLSX 和图片转换。Office 提取正文、幻灯片文字及单元格值，不解析嵌入对象或其中的图片。
* 单文件最多 10 MiB，每请求累计最多 20 MiB；PDF 解析最多 100 页，付费 OCR 最多 20 页，每批最多 10 页；每请求最多 4 个付费子调用、同时最多 2 个。
* 转换总时限为 90 秒；OCR 子调用最多 45 秒，图片描述最多 30 秒。流式转换期间可能先收到 `: PRAXIS PROCESSING` 保活注释，它不是模型输出。
* 提取文字最多 1,000,000 字符，表格每 sheet 最多 1,000 行。模型自身的上下文和输入限制仍然适用。
* Responses 仅在创建时转换新提交的输入；retrieve、cancel 等操作不重新转换。需要转换的 `background: true` 请求返回 `PLUGIN_BACKGROUND_UNSUPPORTED`。
* 并发请求同时未命中缓存时，可能各自发起付费转换。主模型失败时，当前接口不保证返回已解析的文件注明。

# 会话亲和

同一对话的请求复用 `x-session-id`，新对话使用新 ID。会话亲和帮助符合条件的请求复用供应商，但不保证固定供应商或缓存命中。

会话 ID 不会替你保存 Chat Completions 的历史。每轮仍需发送必要消息；如需按响应 ID 接续，使用 [Responses](/docs/cloud/services/model/guides/responses-api)。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. 两轮使用同一个 ID [#2-两轮使用同一个-id]

示例生成一个 UUID，两轮都发送该请求头，并在第二轮带上第一轮的消息。

保存为 `session-affinity.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python session-affinity.py`。

```python
import os
import uuid
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
session_id = str(uuid.uuid4())
messages = [{'role': 'user', 'content': 'Remember this code: LIME-742. Reply OK.'}]
for turn in range(2):
    response = client.chat.completions.create(model='deepseek-flash',
        messages=messages, reasoning_effort='none', max_tokens=256,
        extra_headers={'x-session-id': session_id})
    print('X-Request-Id:', response._request_id)
    assert response.choices[0].finish_reason == 'stop'
    answer = response.choices[0].message.content or ''
    assert answer
    print('turn', turn + 1, answer)
    if turn == 0:
        messages.append({'role': 'assistant', 'content': answer})
        messages.append({'role': 'user', 'content': 'What was the code? Reply with only the code.'})
    else:
        assert 'LIME-742' in answer, answer
```

期望：得到两条完成的响应、两个请求 ID，第二轮回答包含 `LIME-742`，退出码 0。这验证了请求和历史传递，不证明某个供应商或缓存命中；缓存用量另按 [Prompt Cache 指南](/docs/cloud/services/model/guides/prompt-cache)检查。

## 实测失败与处理 [#实测失败与处理]

请求体传空 `session_id` 实测返回 HTTP 400：`session_id must not be empty`。使用非空会话 ID。请求体同时提供 `session_id` 时优先于请求头；避免在两个位置维护不同值，也不要让无关对话共用一个全局 ID。

字段细节：[Chat Completions](/docs/api/compatible/openai/createChatCompletion)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# Prompt Cache 与成本

Prompt Cache 复用重复输入的前缀计算，不复用上一条回答。是否命中要看返回的缓存 token 数，不能凭回答相同或速度更快判断。

本页的 OpenAI 示例使用 `deepseek-flash`，不添加缓存控制参数。2026-10-12 实测：26,016 个输入 token 的第二次请求报告 25,856 个缓存 token；这是一组观测值，不是每次调用的保证。

## 1. 准备终端 [#1-准备终端]

将 Praxis 云 API Key 放入环境变量 `PRAXIS_API_KEY`；获取方式见 [Key 与鉴权](/docs/cloud/account/api-keys)。不要把 Key 写入代码。准备 Python 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)；TypeScript 示例使用 [Bun](https://bun.sh/docs/installation)。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

将每段 Python 保存为标明的文件名，以 `uv run -q --no-project --with openai --with anthropic python <文件名>` 执行。各段代码独立运行。

## 2. 连续请求相同前缀 [#2-连续请求相同前缀]

将不常变的指令和资料放在前面，当前问题放在后面，保持模型、前缀内容和顺序一致。下面生成较长的演示资料并连续请求两次，会产生两次模型调用费用。

保存为 `prompt-cache.py`，运行 `uv run -q --no-project --with openai --with anthropic python prompt-cache.py`。

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1')
prefix = '\n'.join(f'Record {i}: Paris is in France. The demo temperature is 22 Celsius.' for i in range(1500))
hits = []
for turn in range(2):
    response = client.chat.completions.create(model='deepseek-flash',
        messages=[{'role':'system','content':prefix},
            {'role':'user','content':'What country is Paris in? Reply with one word.'}],
        reasoning_effort='none', max_tokens=64)
    print('X-Request-Id:', response._request_id)
    assert response.choices[0].finish_reason == 'stop'
    usage = response.usage
    assert usage and usage.prompt_tokens_details is not None
    cached = usage.prompt_tokens_details.cached_tokens
    assert cached is not None
    hits.append(cached)
    print(turn + 1, 'prompt_tokens:', usage.prompt_tokens, 'cached_tokens:', cached)
assert hits[1] > 0, 'No cache hit observed on the second request'
```

期望：输出两次输入和缓存 token 数，第二次 `cached_tokens > 0`，退出码为 0。重复运行时第一次也可能命中，不要求第一次为零。

`usage.prompt_tokens_details.cached_tokens` 是输入中的缓存部分，已包含在 `prompt_tokens` 内，不能再相加。缓存只减少符合条件的输入费用，不使输出免费；成本按所选模型的缓存输入、普通输入和输出单价计算，不套用固定折扣。缓存最短前缀和保留时间由模型决定。

## 3. 用 TypeScript 检查命中 [#3-用-typescript-检查命中]

保存为 `prompt-cache.ts`，运行 `bun prompt-cache.ts`；无需安装 SDK。

```typescript
import assert from 'node:assert/strict';
const base = process.env.PRAXIS_API_BASE ?? 'https://api.deepraxis.com';
const prefix = Array.from({length: 1500}, (_, i) =>
  `Record ${i}: Paris is in France. The demo temperature is 22 Celsius.`).join('\n');
const hits: number[] = [];
for (let turn = 0; turn < 2; turn++) {
  const response = await fetch(`${base}/openai/v1/chat/completions`, {
    method: 'POST', headers: {'Authorization': `Bearer ${process.env.PRAXIS_API_KEY}`, 'Content-Type': 'application/json'},
    body: JSON.stringify({model: 'deepseek-flash', max_tokens: 64, reasoning_effort: 'none',
      messages: [{role: 'system', content: prefix},
        {role: 'user', content: 'What country is Paris in? Reply with one word.'}]}),
  });
  console.log('X-Request-Id:', response.headers.get('x-request-id'));
  const data = await response.json();
  assert(response.ok, JSON.stringify(data));
  assert.equal(data.choices[0].finish_reason, 'stop');
  const cached = data.usage.prompt_tokens_details?.cached_tokens;
  assert.equal(typeof cached, 'number');
  hits.push(cached);
  console.log(turn + 1, 'prompt_tokens:', data.usage.prompt_tokens, 'cached_tokens:', cached);
}
assert(hits[1] > 0, 'No cache hit observed on the second request');
```

期望：第二次报告正数 `cached_tokens`，退出码为 0。

## 4. 观察 Anthropic cache\_control [#4-观察-anthropic-cache_control]

Messages 可在稳定文本块上设置 `cache_control: {type: "ephemeral"}`。本例使用 `claude-opus-5`，连续调用后分别读取 `cache_creation_input_tokens`（写入）和 `cache_read_input_tokens`（读取）。Messages 的 `input_tokens` 是未计入读写缓存部分的输入；总输入为这三项之和。

本次实测请求被接受，但两次读写缓存数均为零，因此此例用于观察缓存状态，不承诺命中。`GET /openai/v1/models` 的 `supported_parameters` 可查询参数声明，但不是每次缓存命中的证明；最终仍以用量字段为准。

保存为 `prompt-cache-anthropic.py`，运行 `uv run -q --no-project --with openai --with anthropic python prompt-cache-anthropic.py`。

```python
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/anthropic')
prefix = '\n'.join(f'Record {i}: Paris is in France. The demo temperature is 22 Celsius.' for i in range(1500))
hits = []
for turn in range(2):
    raw = client.messages.with_raw_response.create(model='claude-opus-5', max_tokens=64,
        system=[{'type':'text','text':prefix,'cache_control':{'type':'ephemeral'}}],
        messages=[{'role':'user','content':'What country is Paris in? Reply with one word.'}])
    print('X-Request-Id:', raw.headers.get('x-request-id'))
    message = raw.parse()
    assert message.stop_reason == 'end_turn'
    usage = message.usage
    assert usage.cache_read_input_tokens is not None
    assert usage.cache_creation_input_tokens is not None
    hits.append(usage.cache_read_input_tokens)
    print(turn + 1, 'input:', usage.input_tokens, 'write:', usage.cache_creation_input_tokens,
        'read:', usage.cache_read_input_tokens)
print('HIT' if hits[1] > 0 else 'MISS: no cached input reported')
```

期望：两次请求完成，输出读写统计和 `HIT` 或 `MISS: no cached input reported`，退出码为 0。只有读取 token 为正数才算观察到命中；退出码 0 只证明请求和统计读取成功。

## 实测未命中时怎么处理 [#实测未命中时怎么处理]

本次 Messages 示例的实际结果是 `cache_creation_input_tokens=0`、`cache_read_input_tokens=0`，没有 HTTP 报错。不要把请求被接受等同于缓存生效。需要复现已验证的缓存命中时，运行上面的 `deepseek-flash` OpenAI 示例，并检查正数 `cached_tokens`。

为保持前缀可复用，确认两次请求使用相同模型和完整前缀；不要在前缀中加入时间戳或每次变化的标识。保留用量和 `X-Request-Id` 以便核对，不能用相同回答代替命中证据。

协议细节：[OpenAI](https://developers.openai.com/api/docs/guides/prompt-caching) · [Anthropic](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# BYOK：接入你自己的模型密钥

BYOK 即将推出：控制台 → 模型 → BYOK 当前不可点击，标为「即将推出」，暂时无法在此导入自己的供应商密钥。当前可使用 [Praxis 云 API Key](/docs/cloud/account/api-keys)，从[模型目录](https://console.deepraxis.ai/models)选择模型，按[模型快速开始](/docs/cloud/services/model/quickstart)调用。不要把供应商的 Key 当作 `PRAXIS_API_KEY`。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook →](/docs/cookbook)

# 错误与限流



# 沙箱

## 它是什么 [#它是什么]

（待补充）

## 与其他服务的关系 [#与其他服务的关系]

（待补充）

## 出口 [#出口]

[API 参考 →](/docs/api/native/sandbox) · [Cookbook →](/docs/cookbook)

# 快速开始

（待补充）

# 概念

（待补充）

# 指南

（待补充）

# 限制与错误

（待补充）

# 搜索

## 它是什么 [#它是什么]

（待补充）

## 与其他服务的关系 [#与其他服务的关系]

（待补充）

## 出口 [#出口]

[API 参考 →](/docs/api/native/search) · [Cookbook →](/docs/cookbook)

# 快速开始

（待补充）

# 概念

（待补充）

# 指南

（待补充）

# 限制与错误

（待补充）

# 云端浏览器

云端浏览器是一个在云上运行的 Chrome，可以用 Playwright 或 Puppeteer 直接连接操控，也可以在 Console 实时观看与接管。

## 三种用法 [#三种用法]

以下示例在 Node.js 中运行。先设置 `PRAXIS_API_KEY`，将代码保存为 `.mjs` 文件，再用 `node` 执行。只需安装客户端包，无需下载本地 Chrome。

```bash
export PRAXIS_API_KEY="你的 API Key"
npm install playwright @browserbasehq/sdk
```

### 一步连接 [#一步连接]

连接 `wss://api-develop.deepraxis.ai/browser/v1/connect` 即可新开一个浏览器。`?session=<id>` 连接已有会话；`?name=<名称>` 有就连接，没有就创建。名称可用 1–128 个字母、数字或 `. _ : -`，不能同时传 `session` 和 `name`。

```javascript
import { chromium } from "playwright";

const headers = { Authorization: `Bearer ${process.env.PRAXIS_API_KEY}` };
const browser = await chromium.connectOverCDP(
  "wss://api-develop.deepraxis.ai/browser/v1/connect",
  { headers },
);
const cdp = await browser.newBrowserCDPSession();
const session = await cdp.send("Praxis.getSession");
console.log(session.sessionId, session.liveViewUrl, session.consoleUrl);
try {
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
  console.log(await page.textContent("body"));
} finally {
  await browser.close();
  // 用完立即释放，停止计费。
  const closed = await fetch(
    `https://api-develop.deepraxis.ai/browser/v1/sessions/${session.sessionId}`,
    { method: "POST", headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ status: "REQUEST_RELEASE" }) },
  );
  if (!closed.ok) throw new Error(await closed.text());
}
```

新建时还可带 `context`、`persist`、`timeout`（秒）、`idle`（毫秒）、`labels` 和 `viewport`。后两项用 `JSON.stringify` 配合 `URLSearchParams` 编码；连接已有会话时，这些新建参数不生效。创建会话返回的 `connectUrl` 自带凭证，连接时无需再带 API Key；不要公开此地址。

### Browserbase 官方 SDK [#browserbase-官方-sdk]

使用自己的 API Key，把官方 SDK 的 `baseURL` 设为 `https://api-develop.deepraxis.ai/browserbase`。SDK 自动发送 `X-BB-API-Key`。无需 Browserbase 项目，`projectId` 可省略。

```javascript
import Browserbase from "@browserbasehq/sdk";
import { chromium } from "playwright";

const bb = new Browserbase({
  apiKey: process.env.PRAXIS_API_KEY,
  baseURL: "https://api-develop.deepraxis.ai/browserbase",
});
const session = await bb.sessions.create({ timeout: 300, keepAlive: true });
try {
  const browser = await chromium.connectOverCDP(session.connectUrl);
  try {
    const page = await browser.contexts()[0].newPage();
    await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
    console.log(await page.textContent("body"));
  } finally {
    await browser.close();
  }
} finally {
  await bb.sessions.update(session.id, { status: "REQUEST_RELEASE" });
}
```

可调用的端点见 [Browserbase 兼容 API](/docs/api/compatible/browserbase)。代理、反检测、扩展和 Selenium 不可用；`region`、`solveCaptchas` 当前接受但忽略，不会选区域或代解验证码。

### REST 先创建再连接 [#rest-先创建再连接]

`POST /browser/v1/sessions` 返回的 `connectUrl` 包含连接凭证，有效期覆盖会话寿命。直接交给 Playwright 或 Puppeteer，无需再传 API Key。

```javascript
import { chromium } from "playwright";

const base = "https://api-develop.deepraxis.ai/browser/v1";
const headers = {
  Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`,
  "Content-Type": "application/json",
};
const response = await fetch(`${base}/sessions`, {
  method: "POST", headers, body: JSON.stringify({ timeout: 300, keepAlive: true }),
});
if (!response.ok) throw new Error(await response.text());
console.log("X-Request-Id:", response.headers.get("X-Request-Id"));
const session = await response.json();
try {
  const browser = await chromium.connectOverCDP(session.connectUrl);
  try {
    const page = await browser.contexts()[0].newPage();
    await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
    console.log(await page.textContent("body"));
  } finally {
    await browser.close();
  }
} finally {
  const closed = await fetch(`${base}/sessions/${session.id}`, {
    method: "POST", headers, body: JSON.stringify({ status: "REQUEST_RELEASE" }),
  });
  if (!closed.ok) throw new Error(await closed.text());
}
```

完整请求参数见[云端浏览器 API](/docs/api/native/browser)。Puppeteer 使用 `puppeteer.connect({ browserWSEndpoint: session.connectUrl })` 连接同一地址。

## 实时观看与接管 [#实时观看与接管]

打开 [Console](https://console-develop.deepraxis.ai) 的 **浏览器 › 会话**，选择会话即可观看并接管。程序也可通过 CDP 命令 `Praxis.getSession` 取得 `sessionId`、`liveViewUrl` 和 `consoleUrl`。需要用户完成登录或确认操作时，调用[请求人工接管](/docs/api/native/browser/browserRequestHandoff)，完成后调用[完成人工接管](/docs/api/native/browser/browserCompleteHandoff)。

会话状态为 `PENDING`、`RUNNING`、`ERROR`、`TIMED_OUT` 或 `COMPLETED`。API 创建且 `keepAlive=false` 的会话在客户端断开且无人观看后结束；一步连接和 Console 打开的会话默认在无人连接或观看 5 分钟后释放。单次最长 6 小时。没有暂停或休眠；下次继续使用登录态，需要 Context。

## 登录态 [#登录态]

先[创建 Context](/docs/api/native/browser/browserCreateContext)，再在创建会话时传 `browserSettings.context`。`persist: true` 会在会话关闭时保存 cookie 与 localStorage；不保存 IndexedDB。同一登录态正在被写入时，另一会话可能收到 `409 CONTEXT_LOCKED`。

```javascript
// 接上面的 REST 初始化代码；contextId 为创建 Context 返回的 id。
const response = await fetch(`${base}/sessions`, {
  method: "POST", headers,
  body: JSON.stringify({
    timeout: 300,
    browserSettings: { context: { id: contextId, persist: true } },
  }),
});
```

## 计费与限制 [#计费与限制]

* **$0.12 / 浏览器小时**，按秒计费，单会话 1 分钟起。平台原因导致的失败只按实际秒数计费；释放后不再计费。
* 每个账户默认最多同时 **10 个会话**，每个会话最长 **6 小时**。
* 不支持代理、验证码代解、反检测、选区域或扩展。代理、反检测和扩展等不支持的配置返回 `501`；`region`、`solveCaptchas` 当前接受但忽略。
* 部分网站（如 Google、百度）会把云端浏览器识别为机器人。
* 排查请求时保留响应头 `X-Request-Id`。

# 应用

应用把一个站点（静态文件、一段 Worker 代码，或两者）发布到平台上，并给它一个可访问的地址。每次发布产生一个版本，部署后成为线上版本。

## 存储放哪儿 [#存储放哪儿]

订单、会话等运行数据放在应用自带的 `d1`、`kv` 或 `r2` components 中，由应用代码执行业务规则。结构化内容用 Database，文件用 File，可检索知识用 Knowledge：它们是共享内容库，应用可以通过公开 API 读取，但不作为应用的私有运行库。

* [运行时能力](/docs/cloud/services/application/runtime-capabilities)：应用里能做什么、不能做什么，以及各项限制。

# 运行时能力

下表是应用当前的运行时能力。

## 发布与部署 [#发布与部署]

| 能力               | 状态  | 说明                                               |
| ---------------- | --- | ------------------------------------------------ |
| Worker → 版本 → 部署 | 支持  | 创建版本不会上线；部署后才成为线上版本。创建版本时设置 `deploy: true` 可一步完成 |
| 回滚               | 支持  | 对旧版本再创建一次部署，无需重新上传文件                             |
| 整站替换             | 支持  | 每个版本的文件清单必须完整列出站点的全部文件；只有内容变化的文件需要上传，没变的不会重传     |
| 灰度发布             | 不支持 | 一个部署只能让一个版本占 100%                                |
| 保留版本数            | 限制  | 最近 100 个版本                                       |
| 单个脚本大小           | 限制  | 压缩后 10 MiB                                       |
| 部署超时             | 限制  | 10 分钟内没有完成即失败                                    |

## 静态资源 [#静态资源]

| 能力                   | 状态 | 说明                                                                           |
| -------------------- | -- | ---------------------------------------------------------------------------- |
| 内容寻址去重               | 支持 | 相同内容只存一份，重复发布不会重复上传                                                          |
| 路径与大小                | 限制 | 每个版本最多 100000 个文件，单个文件最大 25 MiB                                              |
| `html_handling`      | 支持 | 可选 `auto-trailing-slash`、`force-trailing-slash`、`drop-trailing-slash`、`none` |
| `not_found_handling` | 支持 | 可选 `none`、`404-page`、`single-page-application`                               |
| `_headers`           | 支持 | 仅作用于静态资源的响应，最多 100 条规则，每行最多 2000 字符                                          |
| `_redirects`         | 支持 | 仅作用于静态资源的响应，最多 2000 条静态规则和 100 条动态规则，每行最多 1000 字符                            |

`_headers` 和 `_redirects` 不会作用于 Worker 代码生成的响应。需要跨域访问时，在代码里自己设置 CORS 头：

```js
const CORS = {
  "access-control-allow-origin": "*",
  "access-control-allow-methods": "GET, POST, OPTIONS",
  "access-control-allow-headers": "content-type",
};

export default {
  async fetch(request) {
    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
    return Response.json({ ok: true }, { headers: CORS });
  },
};
```

## 出站请求 [#出站请求]

| 能力         | 状态 | 说明                        |
| ---------- | -- | ------------------------- |
| 访问公网地址     | 支持 | 代码里的 `fetch()` 可以请求任意公网地址 |
| 访问平台上的其他应用 | 支持 | 请求其他应用的地址，得到的是对方应用的响应     |

## 绑定 [#绑定]

| 类型                                                        | 状态  | 说明                              |
| --------------------------------------------------------- | --- | ------------------------------- |
| `d1`                                                      | 支持  | 在创建版本时声明                        |
| `kv_namespace`                                            | 支持  | 在创建版本时声明                        |
| `r2_bucket`                                               | 支持  | 在创建版本时声明                        |
| `secret_text`                                             | 支持  | 在创建版本时声明；值通过密钥接口写入              |
| `plain_text`                                              | 支持  | 在创建版本时声明                        |
| `json`                                                    | 支持  | 在创建版本时声明                        |
| `praxis_token`                                            | 支持  | 启用 owner 组织的平台 API 访问，不注入 token |
| `praxis_vault_ref`                                        | 不可用 | 当前不能使用                          |
| 其他类型（如 `service`、`queue`、`durable_object_namespace`、`ai`） | 不支持 | 创建版本时返回 `UNSUPPORTED`           |

## 密钥 [#密钥]

| 能力    | 状态  | 说明                                                                     |
| ----- | --- | ---------------------------------------------------------------------- |
| 写入密钥  | 支持  | `PUT /application/v1/workers/{id}/secrets/{name}`。写入后会基于当前版本派生一个新版本并部署 |
| 读回密钥值 | 不支持 | 值只写不读，任何接口都不会返回                                                        |

## 兼容标志 [#兼容标志]

| 能力                             | 状态   | 说明                                                                                         |
| ------------------------------ | ---- | ------------------------------------------------------------------------------------------ |
| `compatibility_flags`          | 支持   | 创建版本时传入，会原样生效                                                                              |
| `global_fetch_strictly_public` | 固定开启 | 每个版本都会带上，不能关闭；传入 `global_fetch_private_origin` 或 `no_global_fetch_strictly_public` 会返回 400 |

## 调用平台 API [#调用平台-api]

在要部署的版本中声明绑定：

```json
{ "type": "praxis_token", "name": "PRAXIS_API_TOKEN" }
```

应用可以不带 API Key 调用 Develop API：

```js
export default {
  async fetch() {
    return fetch("https://api-develop.deepraxis.com/application/v1/workers");
  }
};
```

应用拥有与 owner 组织 API Key 相同的组织访问权限。其他组织的资源返回不存在。应用代码不会收到 token 或密钥，也不会生成 `env.PRAXIS_API_TOKEN`。未声明该绑定时，受保护接口返回 401，除非请求自行提供有效凭证。其他目标域名的请求保持原样。

Praxis SDK 使用同一条访问路径：省略 `apiKey`，将 `baseUrl` 设为 Develop API 地址，无需修改 SDK。已有应用需要部署声明该绑定的版本后才能启用。移除绑定会在新部署生效、路由缓存刷新后停止注入身份（最多 10 秒）。

# 文件

文件服务保存被素材库、知识库和对话引用的原始文件。上传后得到 `file_id`，再把它交给需要使用文件的服务。

素材库组织素材及其理解结果；知识库提取文档内容并建立检索索引。只上传文件，不会自动将它加入库，也不会自动让它可检索。

[快速开始](/docs/cloud/services/file/quickstart) · [概念](/docs/cloud/services/file/concepts) · [限额与错误](/docs/cloud/services/file/limits-and-errors)

[API 参考 →](/docs/api/native/file) · [Cookbook →](/docs/cookbook)

# 快速开始

安装 SDK，并将 API Key 设置在环境变量 `PRAXIS_API_KEY` 中。把下面的 Python 代码保存为 `files.py`。

使用 Develop 时，另设 `PRAXIS_API_BASE=https://api-develop.deepraxis.ai`；未设置时使用正式 API。Key 必须属于所选环境。

```bash
python -m pip install openai
python files.py
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRAXIS_API_KEY"],
    base_url=os.environ.get("PRAXIS_API_BASE", "https://api.deepraxis.com") + "/openai/v1",
)
file = client.files.create(
    file=("hello.txt", b"Hello, Praxis!\n", "text/plain"),
    purpose="user_data",
    expires_after={"anchor": "created_at", "seconds": 3600},
)
try:
    print("uploaded:", file.id)
    files = client.files.list(limit=100)
    print("listed:", any(item.id == file.id for item in files))
    content = client.files.content(file.id).read()
    assert content == b"Hello, Praxis!\n"
    print("downloaded:", content.decode().strip())
finally:
    deleted = client.files.delete(file.id)
    print("deleted:", deleted.deleted)
```

期望：输出上传的 ID、`listed: True`、`downloaded: Hello, Praxis!` 和 `deleted: True`。即使列出或下载失败，示例也会删除自己创建的文件。

[API 参考 →](/docs/api/native/file) · [Cookbook →](/docs/cookbook)

# 概念

## purpose 用途 [#purpose-用途]

`purpose` 记录文件的预期用途。上传接受三个值：

| purpose      | 用途与限制                                                                            |
| ------------ | -------------------------------------------------------------------------------- |
| `user_data`  | 通用输入文件。在对话中引用图片时必须使用此值。                                                          |
| `assistants` | 用于智能体或知识库工作流的文件。上传不等于加入智能体或知识库；对话图片引用不接受此用途。                                     |
| `vision`     | 只接受 PNG、JPEG、GIF、WebP 图片（按内容识别），其他内容返回 400 `FILE_TYPE_UNSUPPORTED`；对话图片引用不接受此用途。 |

上传不接受 `batch`、`fine-tune` 和 `evals`。通过 Anthropic 上传的文件统一记为 `user_data`。

## 引用 file\_id [#引用-file_id]

同一账户的 `/file/v1/files`、`/openai/v1/files` 和 `/anthropic/v1/files` 共用文件 ID，可跨接口读取元数据和删除。上传文件的下载使用文件 API 或 OpenAI API；Anthropic 下载仅支持会话输出文件。

* **对话**：图片以 `user_data` 上传，用 `type: "file"` 与 `file.file_id` 引用。不要将 ID 填进 `image_url.url`。文本和 PDF 的文件 ID 当前不能作为对话图片输入。参见[图片引用示例](/docs/cloud/services/model/guides/files)。
* **素材库**：用 `file_id` 导入，生成素材记录。参见[素材 API](/docs/api/native/media/assets)。
* **知识库**：将 `file_id` 加入库后，才会提取内容并建立索引。参见[知识库概念](/docs/cloud/services/knowledge/concepts)。
* **智能体**：用 `type: "file"`、`file_id` 和 `mount_path` 将文件加入会话资源。仅设置 `purpose=assistants` 不会挂载文件。参见[会话资源 API](/docs/api/native/agent)。

会话输出文件的元数据可包含 `scope`、`relative_path` 和 `revision`。用 `scope_id` 列出某个会话的文件；Anthropic 使用该筛选时需要 `anthropic-beta: managed-agents-2026-04-01` 请求头。

## 过期 [#过期]

不设置过期时间的上传文件保留到被删除。`expires_after` 从 `created_at` 起计算秒数，响应中的 `expires_at` 是到期时间。过期文件不能再读取或引用。可用范围见[限额与错误](/docs/cloud/services/file/limits-and-errors)。

## 下载安全 [#下载安全]

下载内容被识别为 HTML、SVG、XML 或 JavaScript 时，以附件下发，并设置 `X-Content-Type-Options: nosniff`。类型按内容识别，不依赖扩展名：上传的 HTML 或 SVG 也可能被识别为纯文本并以纯文本返回。下载不会执行其中的内容。

## 分段下载 [#分段下载]

内容下载支持单个 `Range` 区间：`bytes=0-1023`、`bytes=1024-`（从某处到结尾）或 `bytes=-1024`（最后 1024 字节）。命中时返回 206 和 `Content-Range`；区间超出文件大小返回 416。所有下载响应都带 `Accept-Ranges: bytes`，可用于断点续传和音视频拖动。

[API 参考 →](/docs/api/native/file) · [Cookbook →](/docs/cookbook)

# 限额与错误

## 限额 [#限额]

| 项目                                    | 限额                                                   |
| ------------------------------------- | ---------------------------------------------------- |
| 单文件                                   | 100 MiB（104,857,600 字节）；不接受空文件                       |
| 文件存储配额                                | 20 GiB（21,474,836,480 字节），账户内文件共享                    |
| OpenAI 或文件 API 的 `expires_after`      | `anchor: "created_at"`，3,600–2,592,000 秒（1 小时至 30 天） |
| 文件 API 的 `praxis[expires_in_seconds]` | 3,600–7,776,000 秒（1 小时至 90 天）                        |
| Anthropic 表单 `expires_in_seconds`     | 3,600–7,776,000 秒（1 小时至 90 天）                        |

过期参数只能选一种。Anthropic 的 `expires_in_seconds` 只能放在表单中；放在查询参数里返回 400。参见[上传参数](/docs/api/native/file/createFile)。

## 未知字段 [#未知字段]

兼容接口按各自官方的方式拒绝未知参数，不会静默忽略：

| 接口           | 可用参数                                                                       | 其他参数                                                                                     |
| ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Anthropic 上传 | 表单 `file`、`expires_in_seconds`；查询参数仅 `beta`                                | 400 `invalid_request_error`，如 `purpose: Extra inputs are not permitted`                  |
| OpenAI 上传    | 表单 `file`、`purpose`、`expires_after[anchor]`、`expires_after[seconds]`；无查询参数 | 400 `invalid_request_error`，如 `Unrecognized request argument supplied: foo`，`param` 为该字段 |
| OpenAI 列表    | 查询参数 `after`、`order`、`limit`、`purpose`                                     | 同上                                                                                       |

`praxis[expires_in_seconds]` 与 `scope_id` 等扩展只在[文件 API](/docs/api/native/file) 中可用。

按内容识别 PDF、DOCX/XLSX/PPTX、PNG/JPEG/GIF/WebP、支持的音视频格式和 UTF-8 文本。改扩展名不能让任意二进制文件变成受支持类型。

## 错误处理 [#错误处理]

| 错误                              | 处理方式                                                                       |
| ------------------------------- | -------------------------------------------------------------------------- |
| `PURPOSE_UNSUPPORTED`           | 传入 `user_data`、`assistants` 或 `vision`。                                    |
| `FILE_EMPTY`                    | 上传非空文件。                                                                    |
| `FILE_TOO_LARGE`                | 将单文件控制在 100 MiB 以内。                                                        |
| `FILE_TYPE_UNSUPPORTED`         | 使用支持的文件内容类型，仅修改扩展名无效；`purpose=vision` 只接受图片；损坏的 Office 文档或 ZIP 压缩包也会返回此错误。 |
| `VALIDATION_ERROR`              | 检查文件名与过期参数。                                                                |
| `QUOTA_EXHAUSTED`               | 删除不再需要的文件后重试上传。                                                            |
| HTTP 404                        | 检查 ID、账户以及文件是否已过期或删除。                                                      |
| `File is not an eligible image` | 在对话中使用支持的图片，并以 `purpose=user_data` 重新上传。                                   |

过大的请求可能先被边缘拒绝，返回 HTTP 413 与 HTML 正文，而不是文件 API 的 JSON 错误。解析错误正文前先检查 HTTP 状态。

[API 参考 →](/docs/api/native/file) · [Cookbook →](/docs/cookbook)

# 素材库

素材库为智能体存放、理解和检索图片、视频、音频与文档。一个库是一个隔离单元，素材、文件夹与检索都限定在库内。官方 Cloudinary SDK 可以直接使用。

[快速开始](/docs/cloud/services/media/quickstart) · [概念](/docs/cloud/services/media/concepts) · [限制与错误](/docs/cloud/services/media/limits-and-errors)

[API 参考 →](/docs/api/native/media)

# 快速开始

准备 API Key，将下方代码保存为 quickstart.mjs，在 Node.js 中运行。示例建库、上传图片、按标签检索，并给出原图与缩略图地址。

```bash
npm install cloudinary@2
# Set PRAXIS_API_KEY in your environment.
node quickstart.mjs
```

```javascript
import { v2 as cloudinary } from "cloudinary";

const base = "https://api.deepraxis.com";
const key = process.env.PRAXIS_API_KEY;
if (!key) throw new Error("Set PRAXIS_API_KEY");
async function media(path, method = "GET", body) {
  const response = await fetch(base + "/media/v1" + path, {
    method,
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`Media HTTP ${response.status}`);
  return response.json();
}
const library = await media("/libraries", "POST", { name: "Agent media" });
cloudinary.config({
  cloud_name: library.id,
  oauth_token: key,
  upload_prefix: base + "/cloudinary",
});
const asset = await cloudinary.uploader.upload(
  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABWklEQVR4nO3OQQ0AMBAEofVv+iqDxzRBALvtg/wgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwgzg/i/CDOD+L8IM4P4vwg7gEgaMOyrMtNTwAAAABJRU5ErkJggg==",
  { public_id: "quickstart/pixel", tags: ["docs"] },
);
const found = await cloudinary.search.expression("resource_type:image AND tags:docs").execute();
const delivery = asset.secure_url;
const thumbnail = delivery.replace("/upload/", "/upload/w_160,c_fit/");
const understandings = await media(`/libraries/${library.id}/assets/${asset.asset_id}/understandings`);
const current = await media(`/libraries/${library.id}/assets/${asset.asset_id}`);
const matches = current.semantic === "ready"
  ? await media(`/libraries/${library.id}/search/semantic`, "POST", { query: "a small image", top_k: 5 })
  : null;
console.log({ library_id: library.id, asset_id: asset.asset_id, found, delivery, thumbnail, understandings, matches });
```

理解异步完成。上传响应不含处理状态；用 GET 读取素材，查看 processing 与 semantic。实测量级：图片约半分钟，3 秒视频约 50 秒，raw 文件立即就绪（不做理解）。首次读取可能为空；matches 为 null 时稍后重新读取素材，semantic 为 ready 后再检索。理解与语义检索可用；上传、表达式检索和原文件读取无需等待理解完成。

示例保留库供继续使用。用完后，把 LIBRARY\_ID 设为输出的 library\_id 并删除：

```bash
curl -X DELETE "https://api.deepraxis.com/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

[API 参考 →](/docs/api/native/media)

# 概念

一个库是素材的隔离单元。检索只会命中当前库的素材。

## 库与素材 [#库与素材]

素材有稳定的 asset\_id。public\_id 是交付地址中的名称，可以带路径。asset\_folder 组织素材；移动文件夹不改变 public\_id。按 asset\_folder 列出素材只匹配这一层，不包含子文件夹；空字符串表示根。display\_name 是显示名称，不决定交付地址。音频使用 resource\_type=video，并带 is\_audio=true。

库名最长 64 个字符，可以重名；库以 library\_id 区分。更新素材的 tags、context 或库的 labels 都是整体替换：传入的值就是新的全部内容，传 {}（tags 传 \[]）即清空。

上传 0 字节文件返回 400 FILE\_EMPTY；声明或识别为图片却读不出宽高（例如被截断）的文件返回 400 Invalid image file。其他任意文件按 raw 存放。

## 理解 [#理解]

理解可以产出描述、标签、图片文字、音频转写与视频帧内容。片段结果带起止时间。记录不可变；新版本可以替代旧记录，默认不返回被替代的记录。

整体状态为 pending（等待）、processing（处理中）、ready（完成）、partial（部分完成）或 failed（失败）。单项状态为 pending、running、ready、failed、unsupported（不支持）或 skipped（跳过）。关闭理解或不支持的内容不会阻止原文件读取。

## 语义检索 [#语义检索]

当 semantic 为 ready，即可自然语言检索。默认混合检索结合关键词与语义，也可只用语义。命中带匹配内容；音视频片段带起止毫秒，方便定位。从未完成理解的素材不进入语义结果；重新处理中的素材继续用上一版结果参与检索，直到新结果就绪。

## 文档与其他文件（raw） [#文档与其他文件raw]

PDF、文本等 raw 文件只存放，不做理解，semantic 为 unavailable，不进入语义检索，只能按元数据（public\_id、display\_name、tags、context 等）用表达式检索。需要按全文内容检索文档，请使用[知识库](/docs/cloud/services/knowledge)。

## 删除与恢复 [#删除与恢复]

删除后立即不可见。库可在 7 天内恢复，到期后无法恢复。单个素材没有恢复接口。

## 与文件的区别 [#与文件的区别]

「文件」存放原始文件；素材库进一步组织、理解和检索内容。从文件导入是拷贝：两份文件独立，之后的修改或删除不会互相同步。

[API 参考 →](/docs/api/native/media)

# 限制与错误

视频超过 100 MiB 时不生成帧与音轨理解，也不生成预览海报；仍可存放和读取原文件。

| 限制                    | 数值         |
| --------------------- | ---------- |
| 每账户库数                 | 100        |
| 每库素材数                 | 1000000    |
| 图片最大字节数（50 MiB）       | 52428800   |
| 视频最大字节数（2 GiB）        | 2147483648 |
| 文档最大字节数（100 MiB）      | 104857600  |
| 单请求最大字节数；更大需分片        | 100000000  |
| 非末片最小字节数；各片等长         | 5242880    |
| 分片会话有效小时数             | 24         |
| 视频帧与音轨理解源文件字节上限       | 104857600  |
| 表达式检索每页上限             | 500        |
| 表达式检索默认条数             | 100        |
| 语义检索命中上限              | 50         |
| 语义候选上限                | 100        |
| 以图搜图上传图片最大字节数（10 MiB） | 10485760   |
| 每份素材文字向量上限（图片向量另计）    | 61         |
| 故事板画面上限               | 12         |
| 每库同时理解的任务数            | 4          |
| 理解超时毫秒数               | 600000     |
| 理解最大重试次数              | 3          |
| 每素材标签上限               | 1000       |
| 标签字符上限                | 255        |
| 上下文字节上限               | 1024       |
| 批量素材 ID 上限            | 1000       |
| 库恢复天数                 | 7          |
| 库名字符上限；允许重名           | 64         |
| bge-m3 语义检索最低余弦相似度    | 0.55       |

[错误码与重试规则 →](/docs/api/native/media/errors)

# 知识库

知识库将文件内容分段并建立索引，让应用按语义、关键词和文件属性查找相关文本，适合问答检索、政策查询和给模型提供参考资料。

| 服务  | 适合保存和查找什么                |
| --- | ------------------------ |
| 文件  | 上传、保存和下载原始文件，提供文件 ID     |
| 素材库 | 组织素材、管理文件夹与标签，并查找图片等素材   |
| 知识库 | 从文件内容中查找相关文本分段，返回来源文件与内容 |

一个源文件可以加入多个知识库。从知识库移除文件不会删除源文件；删除源文件后，它会自动从所有知识库中移出，之后不再被搜索到。

* [快速开始](/docs/cloud/services/knowledge/quickstart)：用官方 openai Python SDK 上传、入库和搜索。
* [概念](/docs/cloud/services/knowledge/concepts)：处理状态、分段、搜索与恢复。
* [限制与错误](/docs/cloud/services/knowledge/limits-and-errors)：容量、文件格式与失败处理。

[知识库 API →](/docs/api/native/knowledge) · [OpenAI 兼容接口 →](/docs/api/compatible/openai/vector-stores)

# 快速开始

在服务端运行 Python，将 develop API Key 放入 `PRAXIS_API_KEY` 环境变量。示例连接 develop，每次创建一个知识库和两个文本文件，并在结束时删除它们。

```bash
python -m pip install openai
```

保存为 `quickstart.py`，运行 `python quickstart.py`。先上传政策文件，再建库并等待处理完成；`upload_and_poll` 将第二个文件的上传、添加和等待合成一次调用。上传成功后仍需检查入库状态。

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PRAXIS_API_KEY"],
    base_url="https://api.deepraxis.com/openai/v1",
    timeout=120.0,
)
store = None
file_ids = []
try:
    uploaded = client.files.create(
        file=("refund-policy.txt", b"Refunds are available within 30 days of purchase."),
        purpose="assistants",
    )
    file_ids.append(uploaded.id)
    print("uploaded:", uploaded.id)

    store = client.vector_stores.create(
        name="Knowledge quickstart",
        file_ids=[uploaded.id],
    )
    print("store:", store.id)
    first = client.vector_stores.files.poll(
        uploaded.id, vector_store_id=store.id, poll_interval_ms=1000,
    )
    if first.status != "completed":
        raise RuntimeError(f"Ingestion failed: {first.last_error}")

    attached = client.vector_stores.files.upload_and_poll(
        vector_store_id=store.id,
        file=("refund-timing.txt", b"Refunds are processed in 5 business days."),
        poll_interval_ms=1000,
    )
    file_ids.append(attached.id)
    print("ingestion:", attached.status)
    if attached.status != "completed":
        raise RuntimeError(f"Ingestion failed: {attached.last_error}")

    results = client.vector_stores.search(
        vector_store_id=store.id,
        query="How many business days does a refund take?",
        max_num_results=5,
    )
    assert results.data, "Expected at least one matching chunk"
    for result in results.data:
        print(result.filename, result.score)
        for part in result.content:
            print(part.text)
    print("pagination:", results.has_more, results.next_page)
finally:
    try:
        if store is not None:
            deleted = client.vector_stores.delete(store.id)
            print("store deleted:", deleted.deleted)
    finally:
        for file_id in file_ids:
            deleted = client.files.delete(file_id)
            print("file deleted:", file_id, deleted.deleted)
        client.close()
```

输出包含文件 ID、知识库 ID、`ingestion: completed`、命中文本与清理结果。每个文件一条结果，命中的文本块按相关度排列。搜索不支持翻页；结果没有被截断时最后输出 `pagination: False None`。

2026-10-11 的 develop 实测中，文本、Markdown、PDF、DOCX、CSV、JSON 与 HTML 处理约需 4–21 秒；一张 PNG 约需 87 秒。这些是样例耗时，不是时延保证。服务允许处理至多 30 分钟；失败时查看 `last_error`。

示例删除知识库后，知识库会保留 7 天供恢复；源文件单独删除。若要继续使用这些资料，请在自己的程序中将清理步骤放到使用结束之后。

[查看请求字段 →](/docs/api/compatible/openai/vector-stores) · [理解搜索结果 →](/docs/cloud/services/knowledge/concepts)

# 概念

## 知识库与文件 [#知识库与文件]

知识库使用 `vs_` 开头的 ID。`/knowledge/v1` 和 `/openai/v1/vector_stores` 访问相同数据；前者额外提供恢复、失败重试、分段、事件和搜索解释。所有示例都使用 API Key，从服务端调用。

先通过文件服务上传，得到 `file_id`，再将其加入知识库。知识库内文件 ID 与源文件 ID 相同。重复加入已有文件会返回原记录，不重新处理，也不会应用新的属性或分段策略。批次也一样：已在库中的文件出现在批次里不会重新入库，批次的 attributes 和 chunking\_strategy 只作用于新加入的文件。要改属性，用更新文件接口（`POST /vector_stores/{id}/files/{file_id}`）；要换分段策略，先移除该文件再重新加入。

## 处理状态 [#处理状态]

| status       | 含义     | 下一步                                |
| ------------ | ------ | ---------------------------------- |
| in\_progress | 内容正在处理 | 轮询文件状态或使用 SDK 的 poll 方法            |
| completed    | 内容已可搜索 | 发起搜索                               |
| failed       | 处理失败   | 查看 last\_error，修正文件或通过原生 API retry |
| cancelled    | 已取消处理  | 先移除，再按需要重新添加                       |

图片（PNG、JPEG、GIF、WebP）入库的内容是模型生成的画面描述，不是逐字 OCR：图中的文字可能被概括或遗漏，搜索命中的是这段描述。图片入库比文本慢，实测单张约数秒到数十秒，多个文件同时入库时更久。

原生 API 的 `praxis.stage` 给出 queued、parse、chunk、embed、index 进度。完成后 stage 为 null。知识库的 status 由处理情况与过期状态决定；空库也可为 completed，因此它不表示库内一定有内容。

批次把多个文件添加到同一知识库，最多 500 个。`file_ids` 和逐文件配置的 `files` 二选一。使用 `files` 时忽略顶层 attributes 和 chunking\_strategy。取消只对进行中的批次生效；对已完成、已失败或已取消的批次调用取消，会原样返回当前状态。

## 分段 [#分段]

默认 auto 会转为每段 800 个估算 token、相邻重叠 400 token。static 可设置每段 100–4096 token；重叠不得超过段大小的一半。token 数为估算值，不等同于具体模型 tokenizer 的结果。

原生 API 可读取每段的文本、序号、估算 token、页码、UTF-16 起止位置和相邻重叠量；页码可能为 null。读取文件 content 得到的是分段文本，拼接时需考虑重复内容。`usage_bytes` 是已入库文件的源文件大小（字节），未完成入库的文件为 0；知识库的 `usage_bytes` 是其中所有文件之和。

## 搜索结果 [#搜索结果]

`/openai/v1/vector_stores/{id}/search` 与 OpenAI 一致：**每个文件一条结果**，`content` 按相关度从高到低列出该文件命中的文本块，`score` 取其中最高分，`max_num_results` 限制的是文件数（默认 10、最多 50）。`/knowledge/v1` 的搜索**按块返回**，同一文件可能出现多次，适合直接拼接成模型的参考资料。

`query` 可为字符串或字符串数组；数组会以换行连接后共同搜索。`filters` 筛选文件属性，支持 eq、ne、gt、gte、lt、lte、in、nin 和 and/or 组合。比较按类型匹配，例如数字 1 与字符串 "1" 不相同。

默认混合语义与关键词检索，权重为 0.7/0.3。原生 API 可通过 `ranking_options.hybrid_search` 调整权重并用 `praxis.explain: true` 查看解释；在 OpenAI 兼容接口传 hybrid\_search 会返回 400。只有 ranker 为 default-2024-11-15 时请求重排；none、auto 和省略时使用初始排序。重排的效果尚未单独实测。

score 在 0–1 之间，是同一次搜索内的相对排序依据，不是相关性概率，也没有默认下限：库里不相关的内容也会返回，分数可能与相关内容很接近（实测相关文件 0.70，不相关文件 0.61–0.62）。需要过滤时设置 `ranking_options.score_threshold`，低于该值的结果不返回；OpenAI 同样默认不设阈值。可以从 0.5 起试，再用自己的资料和典型问题看相关与不相关结果的分数，逐步上调到不再误删相关结果为止。

`rewrite_query: true` 时先改写查询再检索，见下方「模型」。`has_more` 表示还有更多结果被 `max_num_results` 截掉；搜索不支持翻页，`next_page` 恒为 null。原生结果附带 chunk\_id、page、span；兼容结果不含这些字段和 praxis。

## 模型 [#模型]

每个知识库有三个模型角色，创建时可在原生 API 的 `models` 里指定，之后用更新接口修改；不指定就用默认模型。读取知识库时 `models` 返回各角色当前生效的模型。

| 角色              | 作用                                                  | 默认模型              |
| --------------- | --------------------------------------------------- | ----------------- |
| `embedding`     | 给分段和查询生成向量                                          | bge-m3            |
| `rerank`        | `ranking_options.ranker` 为 default-2024-11-15 时重排结果 | bge-reranker-base |
| `query_rewrite` | 搜索设置 `rewrite_query: true` 时改写查询                    | qwen3.8-flash     |

库中已有文件后不能更换 `embedding`（已有向量来自原模型），更换会返回 409；其他角色随时可改。模型必须在模型目录中并支持该角色，嵌入模型还必须输出 1024 维向量，否则返回 400。某个角色设为 null 恢复它的默认模型，`models: null` 恢复全部默认。OpenAI 兼容接口不返回 `models`，传入会返回 400（与 OpenAI 对未知参数的处理一致），但搜索同样按知识库设置的模型执行。

`rewrite_query: true` 时，搜索前先用 `query_rewrite` 模型把问题改写成简洁的检索查询（例如「退货以后多久能收到退款？」→「退款到账时间」），用改写结果检索，`search_query` 返回改写后的查询；`query` 为数组时逐条改写。每次改写是一次小模型调用，会产生费用，按模型用量计费，并增加约 1–2 秒延迟。改写失败、超过 5 秒或返回为空时，该条查询回退为原文继续搜索，不会让搜索失败。不传或为 false 时不调用模型。

## 更新、过期与删除 [#更新过期与删除]

name 省略时默认为空字符串；创建时不接受 null，更新时 null 会清空名称。metadata 更新会替换全部内容；null 清空。description 被接受后丢弃，不能用来保存说明。未知写入字段当前会被忽略，拼写错误不一定报错。

`expires_after` 只接受 last\_active\_at 和 1–365 天；搜索和添加文件刷新活动时间，null 取消自动过期。删除后，知识库进入「删除中」：`/knowledge/v1` 读取返回 `status: deleting` 和清除时间 `purge_at`，默认列表不再显示（用 `status=deleting` 可以列出），搜索、更新和添加文件返回 409；7 天内可以 `restore` 恢复，也可以用 `purge` 立即永久删除（不可撤销）。`/openai/v1/vector_stores` 与 OpenAI 一致，删除后读取返回 404。删除知识库不会删除「文件」中的源文件。

[API 参考 →](/docs/api/native/knowledge) · [上限与错误 →](/docs/cloud/services/knowledge/limits-and-errors)

# 限制与错误

## 容量 [#容量]

以下为当前 API 上限。下方耗时来自样例实测，不是服务保证。

| 项目                       | 上限                         |
| ------------------------ | -------------------------- |
| 每个组织的未删除知识库              | 100                        |
| 每个知识库的文件                 | 10,000                     |
| 单个源文件                    | 100,000,000 bytes (100 MB) |
| 单个文件估算 token             | 5,000,000                  |
| 每批文件                     | 1–500                      |
| 知识库名称                    | 256 characters             |
| metadata / attributes 键数 | 16                         |
| 键长度 / 字符串值长度             | 64 / 512 characters        |
| 静态分段大小                   | 100–4096 tokens            |
| 默认分段 / 重叠                | 800 / 400 tokens           |
| 分段重叠上限                   | ≤ ½ chunk size             |
| 搜索返回结果数（兼容接口按文件、原生接口按分段） | 1–50; default 10           |
| 列表每页条数                   | 1–100; default 20          |
| 过期天数                     | 1–365                      |
| JSON 请求体                 | 1,000,000 bytes            |
| 入库截止时间                   | 30 minutes                 |
| 处理重试次数                   | 3                          |
| 删除后保留                    | 7 days                     |

metadata 的值只能是字符串；attributes 的值可以是字符串、数字或布尔值。筛选条件在根条件以下最多嵌套 20 层。语义和关键词检索各取最多 50 个候选；搜索不提供下一页。

## 文件格式与处理耗时 [#文件格式与处理耗时]

知识库可以入库以下类型（按文件服务识别的类型判断）：

| 类型                    | 入库内容               |
| --------------------- | ------------------ |
| PDF                   | 文档文本               |
| DOCX、PPTX、XLSX        | 文档文本               |
| PNG、JPEG、GIF、WebP     | 模型生成的画面描述，不是逐字 OCR |
| HTML                  | 可见文本，去掉脚本和样式       |
| 纯文本、Markdown、CSV、JSON | 原文                 |

能上传不代表能入库。文件服务接受、但知识库不能入库的类型有：音频（MP3、WAV、FLAC、OGG、M4A）、视频（MP4、WebM）、NDJSON、XML、YAML、SVG，以及识别为 Python、JavaScript 的源代码文件。它们加入知识库时不会被拒绝，而是在异步入库阶段失败，文件 status 为 failed，`last_error.code` 为 unsupported\_file。加密的 PDF 或 Office 文件同样在入库阶段失败（invalid\_file）。空文件、ZIP 和其他二进制文件在上传时就被文件服务拒绝。

2026-10-11 develop 实测：文本与文档约 4–21 秒入库完成；单张图片约 4–11 秒，7 个文件同时入库时一张 PNG 用了约 87 秒。

## HTTP 错误 [#http-错误]

| HTTP | code                                                                                                        | 处理建议                               |
| ---- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 400  | INVALID\_PARAMS / LIMIT\_EXCEEDED                                                                           | 修正参数或减少数量。                         |
| 401  | UNAUTHENTICATED                                                                                             | 检查 API Key；兼容响应 code 为 null。       |
| 404  | VECTOR\_STORE\_NOT\_FOUND / FILE\_NOT\_FOUND / FILE\_NOT\_IN\_STORE / BATCH\_NOT\_FOUND / CHUNK\_NOT\_FOUND | 核对资源 ID 与所属知识库。                    |
| 409  | VECTOR\_STORE\_INVALID\_STATE / FILE\_INVALID\_STATE                                                        | 检查删除、过期或文件处理状态。                    |
| 413  | PAYLOAD\_TOO\_LARGE                                                                                         | JSON 请求超过 1 MB；兼容响应 code 可能为 null。 |
| 429  | RATE\_LIMITED                                                                                               | 稍后重试。                              |
| 500  | — / null                                                                                                    | 服务内部错误；保留请求 ID 并稍后重试。              |
| 501  | NOT\_IMPLEMENTED                                                                                            | 当前不支持该操作。                          |
| 503  | PROVIDER\_UNAVAILABLE                                                                                       | 处理服务暂不可用，稍后重试。                     |

原生错误通常包含 `error.code`、`error.message` 与 `error.details`。兼容错误包含 `error.message`、`error.type`、`error.param` 与 `error.code`，官方 SDK 按 HTTP 状态抛出对应异常。未知路径可能没有 code，401 可能没有 details，路径编码错误也可能返回 HTML。

## 异步失败 [#异步失败]

文件 status 为 failed 时查看 `last_error.code`：unsupported\_file 表示无法解析该格式；invalid\_file 表示内容无效、为空或加密；server\_error 表示处理失败或超时。超过估算 token 上限当前映射为 invalid\_file，但尚未实测超限文件。添加成功后仍应检查文件状态。原生 API 支持重试 failed 文件；本次实测未覆盖失败后的成功重试。

真正过期及删除 7 天后的清除尚未端到端观察。实测也未得到可用于承诺的知识库每秒请求额度。

[完整错误对象 →](/docs/api/native/knowledge/errors) · [搜索限制 →](/docs/cloud/services/knowledge/concepts)

# 数据库

## Database 是什么、不是什么 [#database-是什么不是什么]

Database 是 headless CMS 式的内容库：人、智能体和脚本通过公开 API 直接读写结构化的表与行。它保存行程、目录等内容，独立于使用这些内容的应用。它不是应用的私有运行库，也不是数据仓库。

| 角色    | 谁用                       | 生命周期                    | 存在哪里                                      |
| ----- | ------------------------ | ----------------------- | ----------------------------------------- |
| 内容库   | 人、智能体、脚本；应用也可通过公开 API 读取 | 内容独立于应用发布进行编辑和复用        | 结构化内容用 Database，文件用 File，可检索知识用 Knowledge |
| 应用运行库 | 管理订单、会话和业务规则的应用代码        | 状态随应用运行而变化，由应用自己的业务约束管理 | 应用自带的 `d1`、`kv` 或 `r2` components         |
| 数据仓库  | 分析人员和报表流水线               | 积累历史数据用于分析              | 专门的分析型数据仓库，不使用 Database                   |

典型模式是**内容库 → 构建 → 发布到应用**：从 Database 读取行程内容，构建站点文件，再用 [`praxis.application.publish`](/docs/cloud/services/application) 上传、创建版本并部署。修改源内容不会更新这些已发布的文件；需要再次构建和发布才能包含修改。

每个库是一个隔离单元，包含自己的表、字段、行和事件。

通过 Database API 创建库与表结构；通过官方 supabase-js 读写行。同一库的两个行访问地址共享数据。

* [快速开始](/docs/cloud/services/database/quickstart)：建库、建表，再读写第一行。
* [概念](/docs/cloud/services/database/concepts)：字段类型、关联、版本与恢复。
* [限制与错误](/docs/cloud/services/database/limits-and-errors)：容量和查询边界。

[API 参考 →](/docs/api/native/database) · [Supabase 兼容接口 →](/docs/api/compatible/supabase) · [Cookbook →](/docs/cookbook)

# 快速开始

在 Node.js 22 或更高版本中运行，将 develop API Key 放入 PRAXIS\_API\_KEY 环境变量。每次运行都会创建一个新库。

```bash
npm install @supabase/supabase-js
```

将下面内容保存为 `quickstart.mjs`，运行 `node quickstart.mjs`。

```javascript
import { createClient } from "@supabase/supabase-js";

const api = "https://api.deepraxis.com";
const key = process.env.PRAXIS_API_KEY;
if (!key) throw new Error("Set PRAXIS_API_KEY");

async function request(path, method, body) {
  const response = await fetch(`${api}/database/v1${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${result.message}`);
  return result;
}

const database = await request("/databases", "POST", {
  name: "Agent tasks",
  labels: { purpose: "docs" },
});
await request(`/databases/${database.id}/tables`, "POST", {
  name: "tasks",
  fields: [
    { name: "title", type: "string", required: true, unique: true },
    { name: "done", type: "boolean" },
  ],
});

const supabase = createClient(`${api}/supabase/${database.id}/`, key, {
  auth: { persistSession: false, autoRefreshToken: false },
});

const inserted = await supabase.from("tasks")
  .insert({ title: "Write a summary", done: false }).select();
if (inserted.error) throw inserted.error;

const selected = await supabase.from("tasks")
  .select("*").order("title").limit(10);
if (selected.error) throw selected.error;
console.log({ database_id: database.id, rows: selected.data });
```

输出包含 `database_id` 和刚写入的行。保存库 ID 供后续请求使用。Supabase 地址末尾的斜杠不可省略。

[继续更新与删除行 →](/docs/api/compatible/supabase/tables) · [理解字段与版本 →](/docs/cloud/services/database/concepts)

用完后，可用下面的请求删除示例库。恢复规则见[概念](/docs/cloud/services/database/concepts)。

```bash
curl -X DELETE "https://api.deepraxis.com/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

将 `DATABASE_ID` 设为示例输出的库 ID。

# 概念

## Database 是什么、不是什么 [#database-是什么不是什么]

Database 是 headless CMS 式的内容库：人、智能体和脚本通过公开 API 直接读写结构化的表与行。它保存行程、目录等内容，独立于使用这些内容的应用。它不是应用的私有运行库，也不是数据仓库。

| 角色    | 谁用                       | 生命周期                    | 存在哪里                                      |
| ----- | ------------------------ | ----------------------- | ----------------------------------------- |
| 内容库   | 人、智能体、脚本；应用也可通过公开 API 读取 | 内容独立于应用发布进行编辑和复用        | 结构化内容用 Database，文件用 File，可检索知识用 Knowledge |
| 应用运行库 | 管理订单、会话和业务规则的应用代码        | 状态随应用运行而变化，由应用自己的业务约束管理 | 应用自带的 `d1`、`kv` 或 `r2` components         |
| 数据仓库  | 分析人员和报表流水线               | 积累历史数据用于分析              | 专门的分析型数据仓库，不使用 Database                   |

典型模式是**内容库 → 构建 → 发布到应用**：从 Database 读取行程内容，构建站点文件，再用 [`praxis.application.publish`](/docs/cloud/services/application) 上传、创建版本并部署。修改源内容不会更新这些已发布的文件；需要再次构建和发布才能包含修改。

库是隔离单元，表定义记录的结构，字段定义值的类型，行保存实际记录。

## 库、表、字段、行 [#库表字段行]

API Key 决定你能访问哪些库。表和字段可用 ID 或名称寻址；关联字段使用表 ID，因此改名不会改变关联目标。库的标签用于分类和筛选。

默认行只包含主键 `id` 和用户字段，`select=*`、`return=representation` 及 RPC 都遵循这一规则。字段保留名只有 `id`；新字段不能以 `_` 开头。`created_at`、`updated_at`、`version` 可作为普通字段。字段名以小写字母开头，后续只含小写字母、数字和下划线，最多 63 字；表名也允许下划线开头。已有下划线用户字段仍可读写，且优先于同名系统元数据；这时该表无法访问同名元数据。

系统元数据只读，需显式取用：`select=*,_version,_created_at,_updated_at`。`*` 不会展开它们。可用 `_version=eq.3` 过滤，或 `order=_created_at.desc` 排序。不指定 `order` 时，仍按内部创建时间再按 `id` 排序。过滤或排序使用旧元数据名且没有同名用户字段时返回 400：`details` 为 `use _created_at`（或对应的新名字），`hint` 为 `system metadata moved to underscore columns`。

时间字段可定义为 `{"name":"created_at","type":"datetime","default":"now()"}`。插入时省略该字段，就保存服务器当前 UTC 时间；读回字段定义仍显示 `"now()"`。显式 null 和 PATCH 中省略的字段不使用默认值。string/json 字段的 `"now()"` 默认值仍为字面量字符串。给已有表新增这个字段时，回填也会求值。

## 七种字段类型 [#七种字段类型]

| 类型         | 保存的值                                                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `string`   | 字符串                                                                                                                                          |
| `integer`  | 整数                                                                                                                                           |
| `number`   | 数值                                                                                                                                           |
| `boolean`  | `true` 或 `false`                                                                                                                             |
| `datetime` | RFC 3339 日期时间，例如 `2026-10-11T08:30:00+08:00`；不存在的日期（如 2 月 30 日）返回 400。值统一按 UTC、3 位毫秒保存和读出，例如 `2026-10-11T00:30:00.000Z`；精度为毫秒，超过 3 位的小数秒四舍五入 |
| `json`     | 满足指定 JSON Schema 的 JSON 值                                                                                                                    |
| `link`     | 同一库中另一张表的行 ID，或多个行 ID                                                                                                                        |

`required` 要求写入非空值。新增带 `default` 的字段时，已有行一律用它回填；不带 `default` 的新字段在已有行上为空。在已有行的表上新增 `required` 字段时必须提供 `default`；把已有字段改为 `required` 时，若仍有行在该列为空则返回 400 `VALIDATION_FAILED` 并说明空行数，先补齐这些行再修改。`unique` 要求值唯一。前五种类型默认建立索引；不需要的字段可以设 `indexed: false`。`json` 和 `link` 不能设为索引字段。字段类型创建后不可修改。

## 批量写入与事务 [#批量写入与事务]

一次 POST 最多插入 **500 行**。单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查询目标，再插入引用它的行；先查后插不能保证并发期间目标不变，仍需处理插入时的关联错误。

同一批次会按所有行的键的并集补齐缺失值为 `null`（PostgREST 行为），因此某行省略必填字段可能导致整批失败。发送 `Prefer: missing=default` 可让缺失的键使用字段默认值；显式传入的 `null` 仍为 `null`，没有默认值的必填字段仍必须提供。

默认 `return=minimal`：成功返回 201，body 为空。需要读回新增行时发送 `Prefer: return=representation`，或在 supabase-js 的 `.insert(...)` 后调用 `.select()`。

## JSON Schema [#json-schema]

`json` 字段必须在 `options.schema` 中提供 JSON Schema。例如，下面的字段只接受包含字符串 `summary` 的对象。

```json
{
  "name": "detail",
  "type": "json",
  "options": {
    "schema": {
      "type": "object",
      "properties": { "summary": { "type": "string" } },
      "required": ["summary"],
      "additionalProperties": false
    }
  }
}
```

更新 schema 约束之后的写入，不会重写已有行。查询时可用 `detail->>summary` 读取字符串值。

## 关联与删除保护 [#关联与删除保护]

`link` 的 `options.linked_table_id` 指向同一库中的目标表，`multiple` 决定保存单个行 ID 还是行 ID 数组。关联目标创建后不可更改。

```json
{
  "name": "project",
  "type": "link",
  "options": { "linked_table_id": "tbl_example", "multiple": false }
}
```

把 `tbl_example` 换成已创建表的 ID。引用不存在的行会被拒绝；删除仍被其它行引用的行也会被拒绝；同一次删除中的行互相引用时可以一起删除。先解除引用，再删除目标，不会自动级联删除。

## 用 \_version 避免覆盖他人的更新 [#用-_version-避免覆盖他人的更新]

新行的 `_version` 为 1，每次更新递增。更新时同时过滤行 ID 和读到的版本；没有返回行表示该条件不再匹配，需要重新读取后决定下一步。

```typescript
const { data: row, error: readError } = await supabase.from("tasks")
  .select("*,_version").eq("id", rowId).single();
if (readError) throw readError;

const { data, error } = await supabase.from("tasks")
  .update({ done: true })
  .eq("id", row.id)
  .eq("_version", row._version)
  .select();
if (error) throw error;
if (data.length === 0) throw new Error("Read the row again before updating");
```

## 删除库后 7 天内恢复 [#删除库后-7-天内恢复]

删除库后不能再读写其中的行。在 7 天内调用[恢复库](/docs/api/native/database/databases#恢复库)可以重新使用库及保留的表和行；超过窗口无法恢复。此恢复能力针对整个库，不是单独删除的表、字段或行。

[API 参考 →](/docs/api/native/database) · [限制与错误 →](/docs/cloud/services/database/limits-and-errors)

# 限制与错误

按以下边界规划库与查询。

| 限制                  | 上限              |
| ------------------- | --------------- |
| 每库最多表数              | 50              |
| 每表最多字段数             | 64              |
| 每表最多索引字段数（含 unique） | 16              |
| 每表最多行数              | 1000000         |
| 单行最多字节数             | 2097152 (2 MiB) |
| 单次插入最多行数            | 500             |
| 单条查询最多参数值数          | 100             |
| 删除库后可恢复天数           | 7               |
| 单次查询最多扫描行数          | 3000000         |

单条请求最长执行 8 秒，超时返回 57014（重试不会成功）；给过滤和排序字段建索引，或缩小查询范围。不带过滤的计数总是很快。不指定 limit 时每次最多返回 1000 行，用 limit / offset 或 Range 翻页。大表上需要批量修改或删除时，按主键或索引字段的范围分批执行，例如每批几万行。单次批量插入可包含上述行数上限，不必将每行的字段数相乘作为查询参数数目。

[错误码与重试属性 →](/docs/api/native/database/errors)
一次批量 POST 最多插入 **500 行**，单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查后插，并处理并发变化导致的关联错误。

同一批次按所有行的键的并集补齐缺失值为 `null`（PostgREST 行为）。发送 `Prefer: missing=default` 可改用字段默认值；显式 `null` 仍为 null，没有默认值的必填字段仍必须提供。默认 `return=minimal` 返回 201、body 为空；发送 `Prefer: return=representation` 才返回行。

## 按错误细节修正请求 [#按错误细节修正请求]

保留字段名只有 `id`；新字段名不能以 `_` 开头，这个前缀留给系统元数据。`created_at`、`updated_at`、`version` 可用作普通字段名。datetime 字段可用 `"now()"` 作为默认值。

`details` 指出字段或 JSON 路径及实际收到的值，批量校验还包含从 0 开始的行号。值最多显示 80 个字符，不回显整行。`hint` 给出修正方式，没有建议时为 null。下面是省略第 2 行必填 title 的错误示例：

```json
{
  "code": "23514",
  "message": "row validation failed",
  "details": "row 1: title: required value (got null)",
  "hint": "Rows in one insert are filled to the union of their keys with null (PostgREST behavior). Send every key in every row, or send Prefer: missing=default to use field defaults."
}
```

唯一冲突返回 409，例如：

```json
{
  "code": "23505",
  "message": "unique constraint violated",
  "details": "Key (email)=(a@b.c) already exists.",
  "hint": null
}
```

# 保险库

Vault 保管智能体调用第三方服务时需要的凭据，例如 GitHub 令牌、OpenAI API Key 或 Linear 的授权。每个库是一组 Secret，一个 Secret 是一个凭据。

Secret 只写：值写入后任何接口都不会再返回它。每个 Secret 都带一组允许的域名，只有发往这些域名的请求才能用到它。智能体和工具按名字引用 Secret，例如 `GITHUB_TOKEN`。

* [快速开始](/docs/cloud/services/vault/quickstart)：建库、加 Secret，再列出。
* [概念](/docs/cloud/services/vault/concepts)：Secret 的种类、模板、导入、一键授权与续期。
* [限制与错误](/docs/cloud/services/vault/limits-and-errors)：容量上限和错误处理。

[API 参考 →](/docs/api/native/vault) · [Claude 托管智能体凭据库 →](/docs/api/compatible/anthropic/managed-agents) · [Cookbook →](/docs/cookbook)

# 快速开始

把 API Key 放进 `PRAXIS_API_KEY` 环境变量，依次运行下面三个请求。每次运行都会创建一个新库。请先安装 `jq` 以提取 ID；可设置 `VAULT_NAME` 自选显示名称。

## 1. 建库 [#1-建库]

```bash
VAULT_JSON=$(curl --fail-with-body -sS -X POST "https://api.deepraxis.com/vault/v1/vaults" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg name "${VAULT_NAME:-Agent credentials}" '{display_name: $name}')")
export VAULT_ID=$(printf '%s' "$VAULT_JSON" | jq -er '.id')
printf '%s\n' "$VAULT_JSON"
```

期望：HTTP 200，返回 `type` 为 `vault`、`status` 为 `active`、`secret_count` 为 `0` 的对象。命令已把返回的 `vlt_` ID 保存到 `VAULT_ID`。

## 2. 加入 Secret [#2-加入-secret]

```bash
curl -X POST "https://api.deepraxis.com/vault/v1/vaults/$VAULT_ID/secrets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "GITHUB_TOKEN", "value": "ghp_example", "allowed_hosts": ["api.github.com"]}'
```

期望：HTTP 200，返回 `type` 为 `vault_secret`、`kind` 为 `static`、`version` 为 `1` 的对象。响应里没有 `value`：值写入后不会再返回。这个 Secret 只能用在发往 `api.github.com` 的请求上。

## 3. 列出 Secret [#3-列出-secret]

```bash
curl "https://api.deepraxis.com/vault/v1/vaults/$VAULT_ID/secrets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

期望：HTTP 200，`data` 中有一项，`name` 为 `GITHUB_TOKEN`；`next_cursor` 为 `null`。

## 清理 [#清理]

```bash
curl -X POST "https://api.deepraxis.com/vault/v1/vaults/$VAULT_ID/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

curl -X DELETE "https://api.deepraxis.com/vault/v1/vaults/$VAULT_ID" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

期望：归档返回 HTTP 200、`status: "archived"`，随后删除返回 HTTP 200、`{"id": "<VAULT_ID>", "type": "vault_deleted"}`。删除会一并删除库中的全部 Secret，不可恢复。

[从模板开始、导入 .env 与一键授权 →](/docs/cloud/services/vault/concepts) · [完整请求与对象 →](/docs/api/native/vault)

# 概念

库是一组 Secret；Secret 是一个凭据，由名字、值和允许的域名组成。其余功能都只是产生或更新 Secret 的方式。

## 库与 Secret [#库与-secret]

API Key 决定你能访问哪些库。库有显示名称和最多 16 对 metadata 标签。

Secret 的名字在库内唯一，创建后不能修改，只能使用大写字母、数字和下划线，长度为 1–128 个字符，可以以下划线开头，但不能以数字开头，例如 `GITHUB_TOKEN`。可以用名字或 `vsec_` 开头的 ID 寻址一个 Secret；非法名称查找也返回 404 `SECRET_NOT_FOUND`。

值只写：创建或替换后，任何接口都不再返回它。每次替换值，`version` 加一。

## 允许的域名 [#允许的域名]

每个 Secret 必须声明 `allowed_hosts`，1–16 个；空数组返回 400 `INVALID_PARAMS`。只有发往这些域名的请求才能用到这个 Secret。

| 写法               | 匹配                                           |
| ---------------- | -------------------------------------------- |
| `api.github.com` | 只匹配这个域名                                      |
| `*.example.com`  | 匹配 `example.com` 的任意子域名，不匹配 `example.com` 本身 |
| `192.0.2.1`      | 只匹配这个 IPv4 地址                                |

域名写入时统一转为小写，去掉末尾的点，国际化域名转为 punycode。重复项会去重。不提供“任意域名”。IPv6、单标签主机（包括 `localhost`）、`*.internal`、平台域名，以及回环、链路本地、私网与 CGNAT IPv4 均返回 400 `INVALID_PARAMS`。

## 两种 Secret [#两种-secret]

| kind     | 值从哪来              | 状态                                     |
| -------- | ----------------- | -------------------------------------- |
| `static` | 你填写的值             | `active`                               |
| `oauth`  | 一键授权得到的访问令牌，由平台续期 | `active`、`refreshing`、`refresh_failed` |

两种 Secret 归档后状态都是 `archived`。

## 模板 [#模板]

模板为常用服务预填名字、允许的域名和种类，你只需填写值。`GET /vault/v1/templates` 列出全部模板，static 模板有 `github`、`openai`、`anthropic`、`stripe`，OAuth 模板有 `linear`、`atlassian`。GitHub 预填 `GITHUB_TOKEN` 和 `api.github.com`、`uploads.github.com`。添加 static Secret 时可传 `template_id`，其来源记录为 `metadata.template`。

`metadata.source` 和 `metadata.template` 是系统保留键，调用方不能写入，也不占自定义标签的 16 对限额。更新库或 Secret 的 metadata 按键合并：字符串写入，`null` 删除该键，省略的键保留。Secret 的 `description: null` 清除备注，省略则保留。

## 导入 .env [#导入-env]

`POST /vault/v1/vaults/{vault_id}/secrets:import` 一次创建多个 static Secret。传 `dotenv`（`KEY=VALUE` 多行文本）或 `lines` 数组，二者选一；新建时，`allowed_hosts` 默认值应用到没有自带域名的行。同名 Secret 只替换值，只有该行自身的 `allowed_hosts` 才会改变原域名，顶层默认域名不会覆盖原域名。结果分别列出新建、替换和失败的行，失败行带行号与错误码，其余行照常写入。

## 一键授权 [#一键授权]

Linear（CIMD：客户端元数据文档）和 Atlassian（DCR：动态客户端注册）可以通过一键授权产生 `oauth` Secret，无需事先注册应用。需要应用注册的服务（GitHub、HubSpot、Asana、Vercel）请手动添加凭据；Asana 不在一键授权模板中。

1. 调用 `POST /vault/v1/authorizations`，传支持授权的 `template_id`，或要授权的 `resource_url`。
2. 把返回的 `connect_url` 交给最终用户。这个链接 30 分钟内有效、只能使用一次。
3. 用户在确认页看到发起方、目标服务和申请的权限，同意后跳转到服务方完成授权。
4. 完成后，库中出现名为 `secret_name` 的 `oauth` Secret。读取 `GET /vault/v1/authorizations/{id}` 可查看状态：`pending`、`authorizing`、`completed`、`failed` 或 `expired`。

库中已有同名 Secret 时，授权会原地更新它：ID 不变，`version` 加一。

需要授权后回到你的应用时，传 `return_url`。它必须在回跳地址白名单内：用 `PUT /vault/v1/settings/return_urls` 设置，最多 10 个 https 地址，精确匹配。回跳时会带上 `authorization_id` 和 `status`。

## 续期与校验 [#续期与校验]

`oauth` Secret 的访问令牌由平台在过期前续期。服务方拒绝续期时，Secret 变为 `refresh_failed`，`oauth.last_error` 说明原因；重新授权或替换值后恢复为 `active`。服务方暂时不可用时，Secret 保持 `active` 并稍后重试。

`POST …/secrets/{secret}/validate` 用当前令牌向服务发一次探测，返回 `valid`、`invalid` 或 `unknown`，只适用于 `oauth` Secret。调用方收到服务的 401 后，可以调用 `POST …/secrets/{secret}/refresh` 立即续期；同样仅支持 `oauth` Secret。对 static Secret 校验返回 400 `VALIDATE_UNSUPPORTED`，续期返回 400 `SECRET_KIND_MISMATCH`。

## 审计事件 [#审计事件]

库的事件记录创建、更新、归档、删除、使用、续期和授权结果，不包含 Secret 的值。`GET /vault/v1/vaults/{vault_id}/events` 按时间倒序列出，可用 `secret` 按名称或 ID 过滤；未知 Secret 返回空列表。更新事件的 `detail.changed` 列出修改的字段，例如 `value`、`allowed_hosts`。

事件没有按天自动过期的保留期；归档保留事件，删除库或 Secret 会清除其历史事件，仅留下删除记录。`limit` 默认 50、最大 200；超限或无效 `cursor` 返回 400 `INVALID_PARAMS`。完整事件类型见[事件参考](/docs/api/native/vault/vaults)。

## 归档与删除 [#归档与删除]

归档库会同时归档库内全部 Secret 并清除它们的值，之后不能再写入。删除库会删除全部 Secret，不可恢复。单个 Secret 同样可以归档或删除。

## 与 Claude 托管智能体凭据库兼容 [#与-claude-托管智能体凭据库兼容]

同一批库也可以用 Claude 托管智能体的[官方 SDK 兼容接口](/docs/api/compatible/anthropic/managed-agents)访问（`/anthropic/v1/vaults`）。每个请求需要 API Key、`anthropic-version: 2023-06-01`，以及包含 `managed-agents-2026-04-01` 的 `anthropic-beta`；该头可用逗号分隔包含其它 beta。列表使用 `page` 而非 `cursor` 分页；凭据只能用 `vsec_` ID 寻址。库的 `display_name: null` 返回 400。

错误体为 `{type: "error", error: {type, message}, request_id}`；409 对应 `conflict_error`。409 等不可重试错误带 `x-should-retry: false`，不会触发 SDK 自动重试。

| 凭据类型                   | 对应的 Secret                                                                     |
| ---------------------- | ------------------------------------------------------------------------------ |
| `environment_variable` | 名字为 `secret_name`，允许的域名为 `networking.allowed_hosts`；`networking` 只支持 `limited` |
| `static_bearer`        | 允许的域名为 `mcp_server_url` 的主机，名字自动生成为 `MCP_<主机>`                                 |
| `mcp_oauth`            | 暂不支持创建，返回 501；请改用一键授权                                                          |

通过 `/vault/v1` 创建的 Secret 在该接口中显示为 `environment_variable`，`injection_location` 为只在请求头中替换。

# 限制与错误

按以下边界规划库与 Secret。

| 限制                           | 上限                   |
| ---------------------------- | -------------------- |
| 每库有效 Secret 数                | 50                   |
| Secret 值大小                   | 16384 bytes (16 KiB) |
| 每个 Secret 的允许域名数             | 16                   |
| 单次导入行数                       | 50                   |
| 授权创建 / OAuth 校验（每账户每分钟，各自计数） | 30 / 30              |
| 库名称长度                        | 255                  |
| metadata 键值对数                | 16                   |
| metadata 键 / 值长度             | 64 / 512             |
| 列表每页条数                       | 50 (最大 200)          |

同名 Secret 已存在返回 409 SECRET\_CONFLICT；往已归档的库写入返回 409 VAULT\_INVALID\_STATE；超过有效 Secret 上限返回 400 VAULT\_LIMIT\_EXCEEDED；值超过 16 KiB 返回 413 SECRET\_TOO\_LARGE。一键授权创建与 OAuth 校验各按账户独立计数，每个固定一分钟窗口各最多 30 次；超出返回 429 RATE\_LIMITED，等待下一窗口重试。授权链接过期返回 410 AUTHORIZATION\_EXPIRED，需要重新发起授权。

通过 Claude 托管智能体的凭据库接口访问时，每库最多 20 个有效凭据，错误使用该接口自己的错误格式。

[错误码与重试属性 →](/docs/api/native/vault/errors)

# 账户与计费



# 身份与权限

（操作指南，待补充。）

# 定价

Praxis 的价格只有一条规则：以模型厂商的官网价为基准，Praxis 标价低于官网价。每个模型的具体价格在[模型目录](/docs/cloud/services/model/catalog)里，单位是美元每百万 token，不含税。

## 价格怎么定 [#价格怎么定]

* 基准是厂商官网定价页的价格，Praxis 记录来源与日期。
* Praxis 标价对所有客户相同，低于官网价；折扣对输入、输出、缓存创建、缓存读取四种 token 类型一致。
* 厂商调价时，Praxis 标价同步更新；Praxis 主动调整标价提前 30 天通知。

## 怎么付费 [#怎么付费]

* 预付充值，按实际消耗扣减，用多少付多少；订阅也是用量的订阅，不卖许可。
* 未消耗的余额可以兑付。
* 用量与余额在控制台的[用量](/docs/cloud/account/usage)与[费用与充值](/docs/cloud/account/billing)页查看。

## 经合作伙伴购买 [#经合作伙伴购买]

Praxis 可能与介绍您的合作伙伴存在分润安排，不影响您的价格：经合作伙伴购买不会比直接购买更贵。合作伙伴计划的规则在[合作伙伴](/docs/partners)。

# 用量查询

（操作指南，待补充。）

# 费用与充值

（操作指南，待补充。）

# 配额与限制

（操作指南，待补充。）

# 帮助与参考

这里保留跨章节的帮助资料。API 鉴权、端点、错误与版本已经归入顶层 [API](/docs/api)。

# 术语表

（参考，待补充。）

# 服务状态

状态页：`https://status.deepraxis.ai`（建设中，ticket-3549）。

# 常见问题

（待补充：模型 id 怎么填 · 国内网络 · 余额为零会怎样 · Key 泄露 · 流式不出字。）

# 支持与反馈

* 控制台 → [帮助与反馈](https://console.deepraxis.ai/feedback)
* （待补充：其他渠道。）

# 安全与合规

（待补充：数据驻留 APAC · 文件保留期 · 隐私政策 / 服务条款链接 · 备案。）

导出自 Praxis 文档 · 2026-10-20 · 共 96 页