---
title: Developers
description: "基于 OpenChatly 进行开发——面向企业的云原生智能体框架：涵盖 CLI、Git 与变更请求、kortix.yaml 参考、REST API、Apps（应用）、自托管以及 @kortix/sdk。"
---

OpenChatly 是面向企业的云原生智能体框架（agent harness）。你可以在开源智能体框架 `pi` 上编写智能体，在 `kortix.yaml` 中进行声明，然后运行 `kortix ship` 来部署它们。每个会话都在其独立的云计算机上运行。[触发器（Triggers）](#triggers-键triggers-keys) 会基于事件启动智能体，智能体之间也可以相互交接工作（请参阅 [Agents working together（智能体协同工作）](#智能体协作agents-working-together)）。

本页涵盖了 CLI 与 Git 工作流、[kortix.yaml 参考](#kortixyaml-参考)、REST API、Apps（应用）、自托管以及 TypeScript SDK。若要了解 OpenChatly 是什么以及人们如何使用它，请阅读 [Guide（指南）](/docs/zh/guide)。

## 快速入门（Quickstart）

从打开一个空白终端到合并一个变更请求（change request），全程只需几步。每一步都是对你项目仓库的 Git 操作：

| 步骤 | 命令 | 在 Git 中发生的情况 |
| --- | --- | --- |
| 创建项目 | `kortix init`, `kortix ship` | 执行 `git init`，提交（commit），并推送到项目的仓库 |
| 获取项目 | `kortix projects clone` | 通过 OpenChatly 执行 `git clone` |
| 运行会话 | `kortix sessions new` | 智能体在其专属分支上工作，分支命名为 `<session_id>` |
| 审核并合并 | `kortix cr merge` | 将会话分支合并到默认分支中 |

### 安装 CLI（命令行工具）

```sh
curl -fsSL https://kortix.com/install | bash
```

该脚本支持 x86_64 和 arm64 架构的 macOS 和 Linux 系统。在 Windows 上，请在 WSL（Windows Subsystem for Linux）中运行该脚本。如需锁定特定版本或使用开发版（dev）通道，请参阅 [CLI → Install（CLI → 安装）](#安装)。

### 登录（Sign in）

```sh
kortix login
```

此时会打开你的浏览器，请在浏览器中批准 CLI 的登录请求。

CLI 会自动选定你的账户并保存一个默认项目：如果只有一个项目，则直接选定它；如果有多个，则会让你从列表中选择。如果没有任何项目，则会跳过项目设置。

在没有浏览器的机器上，可以使用令牌（token）登录：`kortix login --token kortix_pat_…`。关于令牌的类型，请参阅 [Use any git client（使用任意 Git 客户端）](#使用任意-git-客户端)。

### 创建或获取项目

项目（Project）本质上是一个 Git 仓库，其根目录下必须包含一个 `kortix.yaml` 配置文件。你可以新建一个项目，或者克隆队友已经创建的项目。

**New project（新建项目）**

```sh
kortix init my-agent
cd my-agent
kortix ship
```

`kortix init` 会基于初始模板创建 `my-agent` 目录，并执行 `git init -b main`。接着它会询问你要关联哪些本地编码工具：Claude Code、Codex、pi 或 Cursor。默认会选中 Codex。命令结束时，会输出一段提示语，请将其粘贴到你的编码工具中。

`kortix ship` 会验证 `kortix.yaml` 文件，提交更改，提示你设置缺失的密钥（secrets），推送当前分支，并连接已声明的连接器（connectors）。如果在一个没有关联仓库且没有默认项目的文件夹中运行，它会为你创建该项目。

如果没有设置 `origin`（远程仓库），OpenChatly 会创建并托管该仓库。如果设置了 GitHub 的 `origin`，OpenChatly 则会关联该仓库。随后，常规的 `git push` 和 `git pull` 即可正常工作。详情参见：[Commit and push（提交与推送）](#提交并推送commit-and-push)。

> **Warning**
>
> 如果 `kortix login` 保存了默认项目，在未关联仓库的文件夹中运行 `kortix ship` 会将代码连同密钥一起推送到该默认项目中。若要创建新项目，请在首次运行 `kortix ship` 之前先执行 `kortix projects unset`。

**Existing project（现有项目）**

```sh
kortix projects ls --all
kortix projects clone <project_id> my-agent
cd my-agent
```

`kortix projects clone` 会使用你的 OpenChatly 登录凭证来克隆仓库。目录名称默认会使用项目 ID，因此建议你手动传入一个自定义名称。CLI 会在克隆的目录中写入 `.kortix/link.json` 文件，并安装一个凭证辅助工具（credential helper），这样常规的 `git pull` 和 `git push` 即可正常工作。

克隆项目需要 `project.gitops.push` 权限，该权限由项目的 **Manager（管理员）** 角色持有。**Member（普通成员）** 无法克隆项目。普通成员只能在 Web 应用中启动会话，或者在任意文件夹下执行 `kortix projects use <project_id>` 后启动。此外，普通成员还需要具备对某个智能体的访问权限：请参阅 [Teams（团队）](/docs/zh/guide#teams)。

请在克隆下来的目录内部运行后续命令。如果在目录外部运行，命令将默认作用于你的默认项目。

**Web app（Web 应用）**

在 Web 应用中打开 **Create a project（创建项目）**（`/new`）。输入 **Project name（项目名称）**。如果拥有多个账户，请选择对应的 **Account（账户）**。在 **Git account（Git 账户）** 下选择仓库：

| 选项 | 结果 |
| --- | --- |
| **OpenChatly managed（OpenChatly 托管）** | OpenChatly 会创建并托管一个私有仓库。 |
| 某个 GitHub 账户，**Create a new repository（创建新仓库）** | OpenChatly 会在该 GitHub 账户下创建一个私有仓库。 |
| 某个 GitHub 账户，**Import an existing repository（导入现有仓库）** | OpenChatly 会关联你已有的仓库，并保留其原有文件。 |

点击 **Create project（创建项目）**。若要在终端中操作该项目，请运行 `kortix projects clone`。

### 新项目包含的内容

`kortix init` 命令以及通过 **Create project（创建项目）** 创建的新仓库，都基于同一个初始模板（starter）：

```text
my-agent/
├── kortix.yaml        清单文件（manifest）：定义了智能体 `worker` 及其权限
├── agents/            智能体的提示词文件：worker.md
├── skills/            包含 11 个技能，每个技能为一个独立文件夹，内含一个 SKILL.md 文件
├── memory/MEMORY.md   项目记忆文件
├── README.md          项目说明文件
└── .gitignore         Git 忽略配置文件
```

- `kortix.yaml` 会启用 My OpenChatly（配置为 `builtin_agents: { my_kortix: true }`），并将 `default_agent` 设置为 `mykortix`。如果启动会话时未指定智能体，将默认运行 My OpenChatly；除非你手动指定其他智能体，否则 My OpenChatly 会将工作交接给 `worker` 智能体。
- `worker` 是一个通用智能体。它拥有的所有权限（grants）均设置为 `all`（全部）。
- `worker` 会设置 `workspace: { project_repository: true }`，因此每个会话都会在 `/workspace` 目录下获得该仓库的一个检出副本（checkout），并运行在其专属的分支上。
- `kortix-cli` 是 `skills` 文件夹中唯一需要显式列出的 OpenChatly 技能。其他 `kortix-*` 技能会自动注册，并随每个会话自带。`kortix.yaml` 中的 `skills` 键用于列出其余的 10 个技能。

`kortix init` 还会为你选择的编码工具生成相应的配置文件。Codex、pi 和 Cursor 会生成 `AGENTS.md` 文件；Codex、Claude Code 和 pi 会在 `.agents/`、`.claude/` 或 `.pi/` 目录中获得指向 `skills/` 的链接。关于所有配置项的详细说明，请参阅 [kortix.yaml reference（kortix.yaml 参考）](#kortixyaml-参考)。

### 运行会话（Run a session）

会话（Session）是智能体执行工作的一个独立单元。它在专属的沙盒环境中运行，并拥有独立的代码分支。

```sh
kortix sessions new --prompt "Add a skill that drafts the weekly status report"
```

如果不加 `--agent` 参数，会话将运行 My OpenChatly，并由它将工作交接给 `worker`。如果项目中关闭了 My OpenChatly，会话将运行 `kortix.yaml` 中配置的 `default_agent`（默认智能体）。使用 `--agent <name>` 和 `--model <id>` 参数可以覆盖默认的智能体和模型。在终端中，CLI 会打印出用于与该新会话交互的 `kortix sessions chat` 命令。在 Web 应用中，直接在项目页面输入提示词（prompt）即可。

在 Credits（积分）套餐或 Enterprise（企业版）套餐下，会话将使用平台默认的模型运行。在 Free（免费版）套餐下，需要先连接你自己的模型提供商密钥或 ChatGPT 订阅。详情请参阅 [Models（模型）](/docs/zh/guide#模型models)。

| 任务 | 命令 |
| --- | --- |
| 与智能体对话 | `kortix chat`（自动选择你最近运行的会话） |
| 发送单条提示词 | `kortix chat <session_id> --prompt "…"` |
| 在会话的沙盒中打开 Shell | `kortix sessions shell <session_id>` |
| 列出所有会话 | `kortix sessions ls` |

### 审查与合并（Review and merge）

变更请求（Change Request）提议将会话所在的分支合并到默认分支（在新项目中为 `main`）。OpenChatly 不会自动发起变更请求。

OpenChatly 的内置技能 `kortix-system` 会指示智能体推送代码，使用 `kortix cr open` 发起变更请求，然后等待。如果智能体没有自动发起，你可以要求它发起，或者由你自己手动发起：

```sh
kortix cr open --head <session_id> --session <session_id> --title "Weekly status report skill"
```

然后进行审查并合并：

```sh
kortix cr ls          # 列出所有打开的变更请求
kortix cr diff 1      # 查看编号为 1 的变更请求的统一差异（unified diff）
kortix cr merge 1     # 将编号为 1 的变更请求合并到基础分支
git pull              # 拉取远程更新，将已合并的代码同步到你本地的克隆仓库
```

这里的 `1` 是通过 `kortix cr ls` 命令获取的变更请求编号。如果需要将工作退回让智能体修改，请运行 `kortix cr request-changes 1 --message "…"`。这条备注（note）会发送到该变更请求对应的会话中，如果会话处于休眠状态，它还会被唤醒。在 Web 应用中，你可以直接使用项目的 **Review（审查）** 页面进行操作。

初始模板中的 `worker` 智能体默认持有 `kortix_permissions: all` 权限，因此 API 允许它合并自己发起的变更请求。不过，`kortix-system` 技能会指示它保持等待状态，直到你明确要求它合并为止。关于哪些智能体可以执行合并操作，请参阅：[Agents that merge（可合并的智能体）](#执行合并的智能体)。

### 检查你的配置（Check your setup）

```sh
kortix doctor
```

`kortix doctor` 会检查你的登录状态和项目配置。随后，它会启动一个一次性测试会话，发送 `ping` 命令，最多等待 180 秒以接收智能体的回复，然后自动删除该会话。如果任何检查失败，命令将以退出码 `1` 结束。使用 `--no-session` 参数会在登录和项目检查完成后停止，不启动测试会话；`--keep-session` 参数会保留该测试会话；`--prompt` 参数用于更改发送的测试消息；`--timeout <seconds>` 参数用于更改等待超时时间。

### 后续步骤

<CardGroup>
  <Card icon="git-branch" title="Git（版本控制）" href="#git版本控制">克隆、推送、会话分支与变更请求。</Card>
  <Card icon="bot" title="Agents（智能体）" href="/docs/zh/guide#智能体agents">编写智能体并决定每个智能体的权限范围。</Card>
  <Card icon="plug" title="Connectors（连接器）" href="/docs/zh/guide#连接器connectors">为智能体提供受控的应用、API 和 MCP 服务器访问权限。</Card>
  <Card icon="clock" title="Triggers（触发器）" href="/docs/zh/guide#触发器triggers">通过定时任务、Webhook、应用事件或已合并的变更请求来启动会话或调用你的应用。</Card>
</CardGroup>

## Git（版本控制）

每个 OpenChatly 项目都是一个独立的 Git 仓库。你可以使用任何 Git 客户端对其进行克隆和推送。你可以拉取（fetch）每个会话所在的分支，并通过变更请求（Change Requests）将工作合并到基础分支。本节适用于所有在 Web 应用之外处理项目文件的开发者，以及需要配置推送权限的管理员。

从项目到完成代码审查的最短路径：

```bash
kortix projects clone <project_id> my-project
cd my-project
git checkout -b tighten-triage
# edit agents/, skills/ or kortix.yaml
git commit -am "Tighten the triage prompt"
git push origin tighten-triage
kortix cr open --head tighten-triage --title "Tighten the triage prompt"
```

### 你的项目仓库

一个项目可以拥有以下两种类型的仓库之一。在项目创建之后，这两种仓库的使用方式是完全相同的。

| 类型 | 说明 | 获取方式 |
| --- | --- | --- |
| 托管仓库 (Managed) | 由 OpenChatly 创建并管理的私有仓库。你无需拥有 GitHub 账号。 | 在创建项目时，在 **Git account（Git 账号）** 下选择 **OpenChatly managed（OpenChatly 托管）**。或者，在没有 `origin` 远程仓库的文件夹中运行 `kortix ship`，也可以运行 `kortix ship --origin managed`。 |
| GitHub 仓库 | 位于你的 GitHub 个人或组织账号下的仓库。OpenChatly 通过 OpenChatly GitHub App 访问它（你需要在 **Account settings（账号设置）** → **Git** 中安装该 App），或者通过 GitHub Token 进行访问。 | 在 **Git account** 下选择一个 GitHub 账号，然后选择 **Create a new repository（创建新仓库）** 或 **Import an existing repository（导入现有仓库）**。或者，在 `origin` 指向 GitHub 的文件夹中运行 `kortix ship`。 |

在自托管实例（Self-hosted instance）上，平台管理员需要在管理控制台中配置托管仓库。在此之前，`GET /v1/projects/managed-git/status` 接口会返回 `configured: false`，并且新建项目表单会提示“此实例上不可用 OpenChatly 托管仓库”。详情请参阅 [Self-hosting（自托管）](#自托管self-hosting)。

#### Git 远程源 (The git origin)

无论仓库属于哪种类型，每个项目都会有一个唯一的克隆 URL：

```text
https://<api-host>/v1/git/<project_id>.git
```

在 OpenChatly Cloud 上，该地址为 `https://api.kortix.com/v1/git/<project_id>.git`。你可以通过以下两种方式找到它：

- 运行 `kortix projects info <project_id> --json` 命令，查看其中的 `git_origin_url` 字段。
- 在界面中依次进入 **Project admin（项目管理）** → **Git repo（Git 仓库）** → **Use your own Git client（使用你自己的 Git 客户端）** → **Clone address（克隆地址）**。

请克隆 `git_origin_url`，而不是 `repo_url`。`repo_url` 是 OpenChatly 转发请求所指向的上游仓库。

- 远程源（origin）仅支持通过 HTTPS 协议进行 Git 通信。
- 你需要使用 OpenChatly 令牌（token）进行身份验证。OpenChatly 会在服务端自动添加上游仓库的凭据。这意味着你的 GitHub 或其他提供商的凭据绝不会出现在你的本地电脑或沙盒环境中。
- 审计日志（Audit log）会将每次克隆和拉取操作记录为 `git.clone`，将每次推送操作记录为 `git.push`。详情请参阅 [Audit log（审计日志）](/docs/zh/guide#审计日志audit-log)。

### 克隆项目

1. **安装 CLI 并登录**

    按照 [CLI → Install（CLI 安装）](#安装) 的指引操作，然后运行 `kortix login`。

2. **执行克隆**

    运行 `kortix projects clone [<project_id>] [<dir>]`。你可以使用 `kortix projects ls` 命令来查看项目 ID。如果不指定 ID，该命令将克隆已关联的或默认的项目。克隆生成的目录名默认使用项目 ID，而不是项目名称。

3. **在新文件夹中完成配置**

    （可选）运行 `kortix init --force` 来为检出的代码配置本地编码智能体。运行 `kortix env pull` 会生成一个 `.env` 文件，其中包含项目中每个密钥对应的 `NAME=` 行。请注意，该命令仅写入密钥名称，密钥的实际值仍安全保存在 OpenChatly 中。使用 `--force` 参数会覆盖已存在的 `.env` 文件。

在 **Project admin（项目管理）** → **Git repo（Git 仓库）** → **Work on this locally（在本地进行开发）** 页面中，也展示了相同的三个步骤，并为你填好了相应的命令。

执行克隆操作会完成以下三件事：

1. 它会在进程环境变量中携带你的令牌来运行 `git clone`。该令牌绝不会出现在远程 URL 或 `.git/config` 文件中。
2. 它会写入 `.kortix/link.json` 文件，将当前文件夹与项目绑定，以便 `kortix` 命令能够识别。该文件会被添加到 `.git/info/exclude` 中，因此这个绑定链接仅保留在你的本地电脑上，不会被提交到仓库。
3. 它会在仓库自身的 `.git/config` 文件中为远程源（origin）安装一个凭据助手（credential helper）：

```ini
[credential "https://api.kortix.com/v1/git/<project_id>.git"]
	helper =
	helper = !kortix git-credential
[credential]
	useHttpPath = true
```

空的 `helper =` 配置行会禁用你为该 URL 在其他地方配置的所有凭据助手，从而确保你的系统密钥链（keychain）永远不会存储 OpenChatly 令牌。每次 Git 请求凭据时，`kortix git-credential` 都会自动将已保存登录信息的令牌提供给 Git。完成克隆后，你可以直接使用原生的 `git pull` 和 `git push` 命令。如果登录信息失效，Git 会停止操作并提示：“OpenChatly Git needs login. Run: kortix login”；如果绑定链接中指定了主机名，还需要加上 `--host <name>` 参数。

只有当仓库根目录下存在 `.kortix/`、`kortix.yaml` 或 `kortix.yml` 时，克隆操作才会写入绑定链接文件和凭据助手配置。在其他任何仓库中，你需要手动在根目录创建 `.kortix/` 文件夹，然后按照 [Wire the helper by hand（手动配置凭据助手）](#手动配置凭据助手wire-the-helper-by-hand) 中的说明手动进行绑定。

### 使用任意 Git 客户端

远程源（origin）支持 HTTP Basic 身份验证。用户名可以是任意字符串（通常约定使用 `x-access-token`），密码则使用 OpenChatly 令牌。

```bash
git clone https://api.kortix.com/v1/git/<project_id>.git
# Username: x-access-token
# Password: kortix_pat_…
```

普通的 Git 会将密码保存在你配置的凭据存储区（credential store）中。为了避免令牌被存入任何凭据存储区，你可以改为在每次执行命令时通过请求头（header）来传递令牌：

```bash
git -c http.extraHeader="Authorization: Bearer $KORTIX_GIT_TOKEN" clone https://api.kortix.com/v1/git/<project_id>.git
```


| 令牌类型 | 权限说明 |
| --- | --- |
| 个人访问密钥（Personal access key，`kortix_pat_…`），通过 `kortix login`、**Settings → Personal access keys** 或 `kortix tokens new` 获取 | 代表你本人执行操作。OpenChatly 会根据你在该项目中的角色进行权限校验。仅拥有账号成员身份并不能获得访问权限。 |
| 项目 CLI 令牌（Project CLI token，`kortix_pat_…`），通过 `kortix projects cli-tokens new` 获取 | 代表你本人执行操作，但仅限于单个项目。 |
| 会话令牌（Session token，沙盒环境中的 `KORTIX_TOKEN`） | 仅能读取仓库代码，并只能推送当前会话所在的分支。详情请参阅 [Who can clone and push（谁可以克隆和推送）](#谁可以克隆和推送)。 |
| 服务账号密钥（Service account key，`kortix_sa_…`）、OAuth 令牌、网关密钥、浏览器登录令牌 | 拒绝访问，返回 `401` 错误。 |

[Security（安全）](/docs/zh/guide#安全性) 章节详细说明了如何创建和撤销这些密钥。

#### 手动配置凭据助手（Wire the helper by hand）

请在代码检出目录（checkout）的根目录下运行以下命令。`kortix projects link` 命令会拒绝处理没有 `.kortix/` 目录或 `kortix.yaml` 文件的文件夹。此外，该凭据助手仅对与项目 `git_origin_url` 完全匹配的 URL 做出响应。

```bash
ORIGIN=https://api.kortix.com/v1/git/<project_id>.git
git config --local --replace-all credential.$ORIGIN.helper ''
git config --local --add credential.$ORIGIN.helper '!kortix git-credential'
git config --local credential.useHttpPath true
kortix projects link <project_id>
```

`kortix projects link` 命令会生成 `.kortix/link.json` 文件。凭据助手会读取该文件，以获取项目和主机的相关信息。

#### 在 CI 环境中使用

运行 `kortix projects cli-tokens new` 创建一个项目 CLI 令牌，并将其作为 CI 密钥（secret）进行安全存储。该令牌以创建者的身份执行操作，因此该创建者必须拥有推送（push）权限才能成功推送代码。

```bash
AUTH="Authorization: Bearer $KORTIX_GIT_TOKEN"
git -c http.extraHeader="$AUTH" clone https://api.kortix.com/v1/git/$PROJECT_ID.git project
cd project
# change files, then commit
git -c http.extraHeader="$AUTH" push origin HEAD:refs/heads/ci-update
```

#### 来自远程源（origin）的错误

| 状态码 | 错误信息 | 修复方法 |
| --- | --- | --- |
| `400` | `invalid project identifier`（无效的项目标识符） | 在 URL 中使用项目 ID（UUID 格式）。 |
| `401` | `authentication required`（需要身份验证），附带 `WWW-Authenticate: Basic realm="OpenChatly Git"` | 发送令牌。Git 会提示你输入。 |
| `401` | `git proxy requires an OpenChatly token`（Git 代理需要 OpenChatly 令牌） | 输入的密码不是 OpenChatly 令牌。请使用 `kortix_pat_` 开头的令牌。 |
| `403` | `token is not authorized for this project`（该令牌无权访问此项目） | 你在该项目中没有允许执行此操作的角色。请参阅 [Who can clone and push（谁可以克隆和推送）](#谁可以克隆和推送)。 |
| `403` | `token is scoped to a different project`（该令牌的作用域限定在其他项目） | 该令牌绑定到了另一个项目。 |
| `404` | `Not found`（未找到） | 该项目不存在或已被删除。 |
| `409` | `Repository changed during authorization; retry the request`（授权期间仓库发生变更；请重试请求） | 在你连接时，有人替换了该仓库。请重试。 |
| `409` | `OpenChatly cannot reach <owner>/<repo>: …`，以 `remote: …` 打印 | 仓库已断开连接。请参阅 [Repository disconnected（仓库已断开）](#仓库断连repository-disconnected)。 |
| `502` | `No git upstream is configured for this project`（该项目未配置 Git 上游仓库）或 `git upstream unreachable`（无法访问 Git 上游仓库） | OpenChatly 无法访问上游仓库。请检查 **Git repo（Git 仓库）** 下的连接设置。 |
| `503` | `git_credential_unavailable`（Git 凭据不可用） | OpenChatly 无法获取上游仓库的凭据。如果响应体中包含 `retry: true`，请重试；否则请检查连接设置。 |

### 提交并推送（Commit and push）

完成克隆后，你可以使用普通的 Git 命令进行提交和推送。`kortix ship` 命令可以将以下步骤整合为一步执行：

1. 运行 `kortix validate` 检查。使用 `--no-verify` 可跳过此步骤。
2. 运行 `git add -A` 并提交，提交信息使用 `-m` 参数提供的内容。默认的提交信息为 `kortix: ship`。如果工作区有未提交的更改，使用 `--no-commit` 会导致命令失败。
3. 提示你为每个没有值的 `env` 密钥设置值。使用 `--no-env` 可跳过此步骤。
4. 将当前分支推送到远程同名分支。
5. 连接每个声明过但仍需登录的连接器（connector）。使用 `--no-connect` 可跳过此步骤。

使用 `-n` 或 `--dry-run` 参数会打印执行计划，但不会进行任何实际更改。`kortix deploy` 是此命令的别名。

#### 首次执行 ship 命令

如果文件夹中没有 `.kortix/link.json` 且 CLI 没有设置默认项目，系统会创建一个新项目。`kortix login` 和 `kortix projects use` 命令可以设置默认项目。在这种情况下，`ship` 命令会推送到默认项目。使用 `kortix projects unset` 可以清除默认项目设置。

对于新项目，`ship` 命令会根据文件夹的 `origin` 自动选择仓库类型，无需提示：

| 文件夹的 `origin` | `ship` 命令创建的内容 |
| --- | --- |
| GitHub URL | 通过 OpenChatly GitHub App 创建一个 GitHub 项目。如果未安装该 App，`ship` 会打印安装链接并要求你安装后重试。使用 `-y` 参数则会直接停止。使用 `--github-token <PAT>` 可以在不使用 App 的情况下进行绑定；该令牌需要拥有对仓库 Contents 的读写权限。 |
| 其他 URL（如 GitLab、Bitbucket 或普通 Git） | 不创建任何内容。因为 OpenChatly 仅绑定 GitHub 仓库，`ship` 会在发出任何请求前停止，并建议使用 `--origin managed`。 |
| 无 `origin`，或指定 `--origin managed` | 创建一个托管仓库（managed repository）。`ship` 会将 `origin` 设置为该 Git 远程源，并安装凭据助手。 |

如果是 GitHub URL，首次执行 `ship` 时会使用你本地的 Git 凭据推送到现有的 `origin`。

使用 `--origin <github-url>` 可以首先将 `origin` 设置为指定的 GitHub URL。`--account <id|slug>` 用于选择账号，`--name` 用于指定项目名称。

一旦项目创建成功，`ship` 会立即写入 `.kortix/link.json`，并且 `git add -A` 会将其提交。拥有推送权限（`project.gitops.push`，即 Manager 角色）的队友在克隆该仓库后，也可以运行 `kortix ship`。后续的 `ship` 操作会将 `origin` 设置为项目的 Git 远程源，并安装凭据助手。

### 谁可以克隆和推送

有五种权限控制 Git 操作：

| 权限 | 允许的操作 |
| --- | --- |
| `project.gitops.read` | 读取提交、差异和变更请求。对于会话：允许克隆和拉取。 |
| `project.gitops.push` | 推送代码。发起变更请求。 |
| `project.gitops.merge` | 合并变更请求。 |
| `project.gitops.ref.any` | 对于会话：允许推送非自身的分支。 |
| `project.gitops.ref.delete` | 删除分支。 |

项目的 **Member（成员）** 仅持有 `project.gitops.read` 权限。成员可以读取其有权发起的会话所在的分支、提交和变更请求，但无法读取其他成员的私有会话的任何内容。

克隆操作会提供所有分支的访问，因此需要 `project.gitops.push` 权限才能克隆或拉取。Member 无法使用自己的 Git 客户端进行克隆，但 Member 发起的会话仍然可以克隆并推送其所在的分支。

**Manager（管理员）** 持有上述全部五种权限。账号所有者和管理员在其账号下的所有项目中均表现为 Manager 角色。详情请参阅 [Teams（团队）](/docs/zh/guide#teams)。

拥有推送权限的 **人员（People）**：
- 可以推送任何分支，包括默认分支；
- 需要 `project.gitops.ref.delete` 权限才能删除分支；
- 永远无法删除默认分支，任何人都不能。

账号的 IP 白名单和 MFA（多因素认证）策略同样适用于 Git 请求。

**会话（Sessions）** 使用会话令牌进行推送：
- 会话只能推送其自身的分支（即以 `session_id` 命名的分支）。
- 推送任何其他分支都需要在智能体的 `kortix_permissions` 中配置 `project.gitops.ref.any`。删除分支需要 `project.gitops.ref.delete` 权限。
- 推送到默认分支还需要 `project.agent.write`、`project.trigger.create`、`project.trigger.update` 和 `project.trigger.delete` 权限。
- 智能体的 `kortix_permissions` 必须显式列出该权限，或设置为 `all`，并且智能体的最高角色（ceiling role）也必须持有该权限。两者不会相互扩大权限范围。发起会话的人员的角色不作为输入条件。没有 `kortix_permissions` 键的智能体不持有任何项目权限。详情请参阅 [What an agent may do（智能体的权限范围）](/docs/zh/guide#智能体agents)。

默认情况下，智能体通过 [变更请求（change requests）](#变更请求change-requests) 将代码合入主干。[Agents（智能体）](/docs/zh/guide#智能体agents) 章节说明了如何授予权限。

OpenChatly 不会阻止强制推送（force-push）。对于 GitHub 仓库，建议添加规则集（ruleset）以阻止对默认分支的强制推送和删除。该规则集不会阻止变更请求的合并，因为合并操作是快进（fast-forward）或合并提交（merge commit）。

#### 排查被拒绝的推送

当 OpenChatly 拒绝推送中的某个引用（ref）时，会拒绝整个推送操作。Git 会打印出每个引用被拒绝的具体原因：

```text
 ! [remote rejected] HEAD -> feature-x (a session may only push its own branch (<session_id>); commit there and open a change request to land this elsewhere)
```

| 拒绝原因 | 触发原因 |
| --- | --- |
| `<branch> is the default branch and cannot be deleted`（默认分支无法被删除） | 尝试删除了默认分支。 |
| `deleting <ref> requires git ref-delete authority`（删除该引用需要 Git 引用删除权限） | 没有 `project.gitops.ref.delete` 权限的人员尝试删除了分支。 |
| `a session may only push its own branch (…)`（会话只能推送其自身的分支） | 没有 `project.gitops.ref.any` 权限的会话尝试推送了其他分支。 |
| `pushing <branch> skips change-request review and needs agent and trigger write permission; …`（推送该分支会跳过变更请求审查，需要智能体和触发器的写入权限） | 会话在没有 `project.gitops.ref.any` 权限及相关清单（manifest）权限的情况下，直接推送到了默认分支。 |
| `pushing <branch> could change agent grants without review, and an agent grants only what it holds; …`（推送该分支可能会未经审查地更改智能体授权，且智能体只能授予其自身拥有的权限） | 受控智能体直接推送到了默认分支，但并未持有其可能授予的所有权限。 |
| `a session may not delete its own branch`（会话不能删除其自身的分支） | 没有 `project.gitops.ref.delete` 权限的会话尝试删除了其自身的分支。 |

### 会话分支（Session branches）

每个会话都在其专属的分支上工作。分支名称直接使用 `session_id`，不带任何前缀。OpenChatly 会根据会话的 `base_ref` 创建该分支；除非在创建会话时指定了其他分支，否则 `base_ref` 默认为项目的默认分支。

只有当智能体配置了 `workspace: { project_repository: true }` 时，会话才会获得该分支以及在 `/workspace` 目录下的代码检出（checkout）。初始模板智能体（starter agents）默认开启了此配置。如果没有开启，对仓库的调用将返回 `403 session_repository_access_denied` 错误。

在沙盒环境内部，该分支的名称通过环境变量 `$KORTIX_BRANCH_NAME` 获取。智能体在该分支上进行提交，并运行 `git push origin HEAD`。[Inside a session sandbox（会话沙盒内部）](#在会话沙盒内部) 章节列出了其他相关的环境变量。

被推送的分支在会话停止或被删除后，仍会保留在仓库中。`/workspace` 目录保存着该会话的文件，其生命周期与会话相同。当会话被删除时，智能体未推送的代码工作将随之丢失。详情请参阅 [Computers（计算环境）](/docs/zh/guide#计算机computers)。

在你的电脑上获取智能体的工作成果：

```bash
git fetch origin <session_id>
git checkout <session_id>
```

- `kortix files branches` 命令会列出那些相对于默认分支有领先（ahead）或落后（behind）提交的分支。
- `kortix sessions info <session_id>` 命令会显示该会话的 `branch`（当前分支）和 `base_ref`（基础分支）。
- 若要在其他分支上启动会话，请在创建会话时传入 `base_ref` 参数，可通过 `POST /v1/projects/<project_id>/sessions` 接口，或使用 [SDK](#从代码管理会话) 中的 `sessions.create()` 方法来实现。注意：`kortix sessions new` 命令目前不支持通过命令行标志（flag）来指定此参数。

当基础分支发生更新时，请在会话中打开命令面板（command palette），并运行 **Ask Agent: Sync Branch & Reload（询问智能体：同步分支并重新加载）**。智能体会将 `origin/<base_ref>` 合并到当前会话分支中，解决可能出现的冲突，运行相关测试，并提交更改。它的最后一步操作是执行 `kortix sessions reload … --no-repo --force --yes`，这会重启智能体运行环境（runtime）并结束当前回合。等运行环境恢复后，请发送 `continue` 指令让智能体继续工作。

### 变更请求（Change requests）

变更请求的作用是将一个分支（源分支，head）合并到另一个分支（目标分支，base）。OpenChatly 会将合并、差异比对（diff）和冲突检查作为 Git 操作直接在项目仓库上执行。因此，变更请求功能适用于所有类型的仓库。

```text
open ──merge──▶ merged          (final)
open ──close──▶ closed ──reopen──▶ open
```

#### 从你的电脑发起变更请求

```bash
git push origin my-branch
kortix cr open --head my-branch --title "Add the triage agent" --description "Why and what changed"
```

- 目标分支（base）默认为项目的默认分支。使用 `--base <branch>` 参数可以指定其他目标分支。
- 如果源分支（head）相对于目标分支没有领先的提交，系统会返回 `CR_HEAD_NOT_AHEAD` 错误并拒绝操作。请先推送（push）代码。
- 后续每次向源分支推送代码，都会自动更新同一个变更请求。

#### 从会话（Session）中发起变更请求

智能体（Agent）需遵循以下标准流程：

1. 在 `$KORTIX_BRANCH_NAME` 分支上进行提交。
2. 推送代码：运行 `git push origin HEAD`。
3. 发起变更请求：运行 `kortix cr open --title "…" --description "…"`。在沙盒环境中，`--head` 和 `--session` 参数会自动从 `$KORTIX_BRANCH_NAME` 和 `$KORTIX_SESSION_ID` 环境变量中获取值。
4. 将生成的变更请求编号报告给用户，然后停止操作。

从会话中发起的变更请求，其目标分支固定为该会话的 `base_ref`。智能体无法更改目标分支：如果 `--base` 指定了其他分支，将返回 `400 CR_BASE_NOT_SESSION_BASE` 错误。不过，用户可以使用 `--base` 参数为同一个源分支手动发起变更请求。

#### 审查与合并

你可以在 Web 应用的 [Review page（审查页面）](#审查页面the-review-page) 进行审查，也可以在终端中进行：

```bash
kortix cr ls                     # 列出所有处于打开状态的变更请求
kortix cr diff 3                 # 查看编号为 3 的变更请求的统一差异（unified diff）
kortix cr merge-preview 3        # 预览合并结果：检查是否可以合并，并列出存在的冲突
kortix cr merge 3                # 合并编号为 3 的变更请求
kortix cr request-changes 3 --message "Rename the flag first"  # 要求修改：拒绝合并并附带留言“请先重命名该标志参数”
```

一次合并会执行以下步骤：

1. OpenChatly 在源分支（head）上校验 `kortix.yaml` 及其 `imports:`（导入项）。清单无效会以 `422` `MANIFEST_INVALID` 错误中止合并。源分支上没有清单的，则视为校验通过。
2. 当源分支严格领先于目标分支（base）时，OpenChatly 对目标分支执行快进（fast-forward）。
3. 否则，OpenChatly 会创建一个合并提交，格式为 `Merge CR #<n>: <title>`，作者署名为 `OpenChatly <support@openchatly.com>`。使用 `--message` 可指定其他提交信息。
4. 出现冲突会以 `409` 错误中止合并，并列出冲突文件清单。

一次合并可能会一并带上同一目标分支上其他处于打开状态的变更请求的提交。举例：你合并了某个堆叠（stack）中最顶部的那条请求，其下方的请求也会随之一起合入。OpenChatly 会将其中每一条都标记为 `merged`（已合并），并共用同一个合并提交。响应会在 `also_merged` 字段中列出它们，而 `kortix cr merge` 会打印 `Also merged #<n>`（已连带合并 `#<n>`）。

合并完成后，在该目标分支上运行的会话（session）会采用新的配置，OpenChatly 也会根据新的 `kortix.yaml` 同步项目的连接器（connector）。请参阅 [配置来源于目标分支](/docs/zh/developers#配置来源于目标分支base-branch)。

**Request changes（要求修改）** 会将该条留言记录在变更请求上，并以一条新的提示词（prompt）发送给发起该请求的会话。处于休眠状态的沙盒会被唤醒。

#### 执行合并的智能体

- 声明了 `kortix_permissions` 的智能体，只有在其授权（grant）中包含 `project.gitops.merge` 时才能合并。未声明 `kortix_permissions` 的智能体无法合并。
- 会话无法合并由它自己发起的变更请求，除非其在 `kortix.yaml` 中的授权包含 `project.gitops.merge`。若缺少该权限，合并会返回 `403` `CR_SELF_MERGE_REFUSED`。
- 若一次合并会改动 `agents`、`default_agent` 或 `triggers`，则同样需要具备直接编辑时所需的权限：`project.agent.write`，或 `project.trigger.create`、`.update`、`.delete`。执行合并的智能体无法授予任何其自身未持有的权限。

在授权中写明 `project.cr.open` 或 `project.cr.merge`，分别等同于 `project.gitops.push` 或 `project.gitops.merge`。在新的授权中请改用 `gitops` 这一命名。

#### 权限

| 操作 | 所需权限 |
| --- | --- |
| 列出、查看、比对差异、合并预览 | 对项目的读取（Read）权限。 |
| 发起（Open） | `project.gitops.push` |
| 编辑、关闭、重新打开 | 对项目的写入（Write）权限。智能体还需要 `project.gitops.push`。 |
| 合并 | `project.gitops.merge`，对于智能体还需上文所述的清单权限。 |
| 要求修改（Request changes） | `project.review.act` |

#### `kortix cr` 命令

`<cr>` 是变更请求的编号（如 `3`）或其 UUID。

| 命令 | 作用 |
| --- | --- |
| `kortix cr ls [--status <s>]` | 列出变更请求。`<s>` 可为 `open`（默认）、`merged`、`closed` 或 `all`。 |
| `kortix cr show <cr>` | 查看单个变更请求。 |
| `kortix cr diff <cr>` | 打印统一差异（unified diff）。 |
| `kortix cr open --head <branch> --title <t> [--base <branch>] [--description <t>]` | 发起一个变更请求。别名：`--from`、`--into`、`--body`。 |
| `kortix cr merge-preview <cr>` | 显示是否可以合并，以及冲突清单。 |
| `kortix cr merge <cr> [--message <t>]` | 合并该变更请求。 |
| `kortix cr request-changes <cr> --message <t>` | 将留言发送给发起该请求的智能体。 |
| `kortix cr close <cr>` | 关闭该变更请求（不执行合并）。 |
| `kortix cr reopen <cr>` | 重新打开一个已关闭的变更请求。 |
| `kortix cr version-diff --from <head> --into <base>` | 在你发起变更请求之前，先汇总一次合并的内容。 |

每条命令都接受 `--project <id>` 和 `--host <name>` 参数。`ls`、`show`、`diff`、`merge-preview`、`request-changes` 和 `version-diff` 还接受 `--json` 参数。REST 接口路由位于 [API 参考](https://api.kortix.com/v1/docs) 中的 `/v1/projects/<project_id>/change-requests` 之下。

`GET /change-requests` 返回一页数据，按编号从新到旧排列：默认返回 50 个变更请求，通过 `limit` 参数最多可返回 500 个（`limit` 值更大时会返回 `400`）。将 `next_cursor` 作为 `cursor` 参数回传即可获取下一页；最后一页时该值为 `null`。`kortix cr ls` 会自动跟随游标，列出全部变更请求。

#### 错误

| 错误码 | 状态码 | 含义 |
| --- | --- | --- |
| `CR_HEAD_NOT_AHEAD` | `422` | 源分支相对于目标分支没有领先的提交。请在源分支上提交你的工作并推送。 |
| `CR_BASE_NOT_SESSION_BASE` | `400` | 智能体试图将目标分支指向除其会话 `base` 之外的分支。 |
| `MANIFEST_INVALID` | `422` | 源分支上的清单校验未通过。响应体中会列出具体问题。请运行 `kortix validate`。 |
| （冲突 conflict） | `409` | 合并发生冲突。响应体中会列出冲突文件。 |
| （未处于打开状态 not open） | `409` | 该变更请求已被合并或已关闭。 |
| `CR_SELF_MERGE_REFUSED` | `403` | 会话在缺少合并授权的情况下，试图合并自己发起的变更请求。 |
| `CR_GOVERNANCE_UNVERIFIED` | `503` | OpenChatly 无法读取清单以核查某智能体的合并。本次未发生任何合并。请重试。 |
| （清单不可读 manifest unreadable） | `502` | OpenChatly 无法从源分支读取清单。 |

### 审查页面（The Review page）

审查页面是项目的“收件箱”，专门用于展示所有等待人工处理的事项。你可以在项目侧边栏中打开 **Customize（自定义） → Review（审查）**，或直接访问 `/projects/<project_id>/customize/review`。

| 事项类型 | ID 格式 | 来源 |
| --- | --- | --- |
| 变更（Change） | `cr:<id>` | 变更请求（Change request）。 |
| 审批（Approval） | `call:<id>` | 被策略拦截并等待审批的连接器调用（connector call）。请参阅 [Connectors（连接器）](/docs/zh/guide#连接器connectors)。 |
| 产出（`output`）、问题（`decision`）、已完成的批次（`batch`） | 自身 ID | 智能体通过 `kortix review submit` 提交的事项。 |

列表分为 **Needs you（需要你处理）**、**Waiting（等待中）** 和 **Done（已完成）**。过滤器包括 **All（全部）**、**Changes（变更）**、**Approvals（审批）**、**Outputs（产出）**、**Questions（问题）** 和 **Finished（已完成）**。
快捷键：`j` 和 `k` 上下移动，`Enter` 打开事项，`a` 批准，`e` 要求修改，`d` 忽略，`1`、`2`、`3` 切换列表，`/` 搜索，`?` 显示帮助。

变更请求会作为一个独立页面打开，并附带代码差异（diff）。其他所有事项都会在列表上方以弹窗形式打开，审批事项也是如此。按 `Esc` 可关闭弹窗。

对于“产出（output）”事项，首先会显示智能体的备注，然后是智能体生成的具体内容：`/drives/` 目录下的第一个图片、视频或音频文件会在弹窗中直接播放，`preview` 文本会作为其描述显示，其他文件则每行显示一个，点击即可打开。如果产出事项没有关联任何文件，则仅显示其备注。

每个列表每次加载 50 个事项，按时间从新到旧排列。点击 **Load more（加载更多）** 可显示接下来的 50 个。过滤器和搜索仅作用于当前已加载的事项。侧边栏 **Review（审查）** 旁的数字，以及等待你处理的会话上的红点，都会统计所有需要你处理的事项总数。

不同事项类型对应的处理结果如下：

| 事项类型 | `approve`（批准） | `reject`（拒绝） | `changes`（要求修改） |
| --- | --- | --- | --- |
| 变更（Change） | 合并该变更请求。 | 关闭该变更请求。 | 将留言发送给发起该请求的智能体。必须填写留言。 |
| 审批（Approval） | 允许该调用继续执行。 | 拒绝该调用。 | 不可用。 |

对于智能体提交的事项，支持所有处理结果：`approve`（批准）、`reject`（拒绝）、`changes`（要求修改）、`answer`（回答）和 `dismiss`（忽略）。

审查页面仅对持有相应权限的角色显示处理按钮。对变更请求或智能体事项进行任何处理，都需要项目的写入权限（`project.write`）：

| 操作控件 | 所需权限 |
| --- | --- |
| **Ship it（发布）**（Web 端）/ **Merge（合并）**（移动端） | `project.write` + `project.gitops.merge` |
| **Solve with agent（让智能体解决）**（Web 端）/ **Resolve conflicts（解决冲突）**（移动端）：用于替换冲突变更请求的合并操作 | `project.write` + `project.gitops.merge` |
| 要求修改（Ask for changes）、关闭（close）、忽略（dismiss）、回答（answer），以及对智能体事项的所有处理操作 | `project.write` + `project.review.act` |
| 对连接器审批的 **Approve（批准）** 和 **Deny（拒绝）** | 项目管理员（Manager），或发起该会话的人员。API 会拒绝其他任何人操作。 |
| 移动端的 **+** 按钮（用于发起变更请求） | `project.write` + `project.gitops.push` |

内置的 Member（成员）角色不持有任何上述权限。他们只能看到没有处理按钮的变更请求和智能体事项，且仅能在自己发起的会话中决定连接器的审批。

在 Files（文件）页面和会话变更卡片上的变更请求弹窗也遵循相同的权限规则。**Apply changes（应用更改）** 和 **Fix with agent（让智能体修复）** 需要 `project.write` + `project.gitops.merge`。**Dismiss（忽略）** 和 **Reopen（重新打开）** 需要 `project.write`。

| 命令 | 作用 |
| --- | --- |
| `kortix review ls [--segment <s>] [--kind <k>]` | 列出事项。分段（Segments）：`needs_you`、`waiting`、`done`。类型（Kinds）：`change`、`approval`、`output`、`decision`、`batch`。 |
| `kortix review show <item>` | 查看单个事项，包括连接器调用的参数。 |
| `kortix review act <item> <verdict> [--message <t>]` | 对单个事项做出处理决定。 |
| `kortix review bulk <verdict> <id>…` | 批量处理多个智能体事项。会自动跳过变更请求和审批，因为它们各自需要单独审查。 |
| `kortix review submit --kind <k> --title <t>` | 提交 `output`、`decision` 或 `batch`。可选参数：`--summary`、`--risk`（可选 `none`、`low`、`medium`、`high`）、`--detail <json>`、`--agent`、`--session`。 |

在提交产出（output）时，通过 `--detail` 参数指定关联的文件。`files` 接受 `{"path", "note"}` 格式的对象或纯文件路径：

```bash
kortix review submit --kind output --title "Launch video" \
  --summary "Draft cut. Check the claims before you publish." \
  --detail '{"files":[{"path":"/drives/me/launch/cut.mp4"},{"path":"/drives/me/launch/sources.json","note":"Sources"}],"preview":"The post text."}'
```

审查页面还会读取 `artifact`、`description` 以及所有其他值为 `/drives/` 或 `/workspace/` 下文件路径的键，并以该键的名称作为文件显示名。`/drives/` 下的文件会通过提交该事项的会话打开。`/workspace/` 下的文件仅会列出，无法直接打开：因为审查页面没有运行中的沙盒环境。

读取事项需要 `project.review.read` 权限，做出处理决定需要 `project.review.act` 权限，提交事项需要 `project.review.submit` 权限。Member（成员）角色持有读取和提交权限。Manager（管理员）角色持有上述全部三种权限。

REST 接口路由位于 `/v1/projects/<project_id>/review` 之下：

| 路由 | 返回内容 |
| --- | --- |
| `GET /review/items` | 一页事项列表：按 **Needs you（需要你处理）**、**Waiting（等待中）**、**Done（已完成）** 排序，每个分段内按时间从新到旧排列。过滤器：`segment`、`kind`、`session_id`。`limit` 默认为 50；超过 200 会返回 `400`。将 `next_cursor` 作为 `cursor` 参数回传即可获取下一页；最后一页时该值为 `null`。分页遍历不是快照：如果在两次分页请求之间某个事项的状态发生变化，它可能会出现在后续页面中或被遗漏。`kortix review ls` 会跟随游标，确保每个事项只列出一次，并显示其最新状态。 |
| `GET /review/items/<item>` | 根据 ID 返回单个事项，包括 `cr:<id>` 和待处理的 `call:<id>`。 |
| `GET /review/summary` | `{ needs_you_total, needs_you_by_session }`：侧边栏显示的统计数量。对于你无权决定的连接器调用，仅计入有权决定的人员的统计中。 |

### 配置来源于目标分支（base branch）

会话运行的是其目标分支（base branch）当前的配置版本：即 `kortix.yaml` 及其注册的文件。这些文件包括智能体提示词（prompts）、技能（skills）、工具（tools）、命令（commands）和扩展（extensions）。会话不会运行 `/workspace` 中的文件。

- 在 `/workspace` 中或会话分支上进行的编辑，只有在通过合并或推送落实到目标分支后才会生效。
- 目标分支上的每一次提交都是一次新的配置版本。运行中的会话会在下一个回合开始时同步到新配置。推送或合并操作也会在后台触发配置同步。
- 若要立即应用新配置，请在会话菜单中选择 **Reload config（重新加载配置）**，或运行 `kortix sessions reload <session_id>`。这会重启智能体运行环境。`--force` 会在当前回合中强制重新加载并结束该回合；除非传入 `--yes`，否则系统会先进行确认。`--no-repo` 会跳过 `/workspace` 中的 `git pull` 操作。`--status` 仅用于报告会话是否落后于最新配置。
- 若要在合并前测试配置，请创建一个将会话的 `base_ref` 指向你的分支的会话。该会话发起的变更请求也会以该分支为目标。
- 此类会话会运行该分支上的智能体行为：包括每个智能体的提示词、模型和权限规则，以及其启用的技能、工具、命令和扩展。但治理规则（Governance）仍来源于默认分支：即声明了哪些智能体，以及它们的密钥、连接器和权限授权。分支不能在合并前扩大智能体的可用权限范围。当项目要求使用已声明的智能体时，如果某个智能体仅在该分支上声明，系统会返回 `400` `AGENT_NOT_DECLARED` 错误并拒绝操作。

当某个配置版本加载失败时，会话会运行上一个成功加载的版本，或者回退到平台默认配置。会话头部会显示 **Older config（旧版配置）**。在目标分支发生变更之前，OpenChatly 不会重试加载失败的版本。请在目标分支上修复配置：可使用 `kortix validate` 检查清单。

| 限制项 | 限制值 |
| --- | --- |
| 配置版本 | 压缩后 32 MiB，解压后 128 MiB |
| 项目快照 | 压缩后 512 MiB。超过此限制时，运行中的会话将停止获取配置更新，直到新会话启动。 |
| `kortix validate` 警告 | 单个文件达到 10 MiB 或以上，或总大小超过 512 MiB |

若要将文件保留在 Git 中但不包含在配置版本中，请在 `.gitattributes` 中将其标记为 `export-ignore`。针对目录的规则会覆盖该目录下的所有内容。配置版本、`kortix validate` 的大小检查以及会话配置下载都会排除这些文件。清单文件（manifest file）始终会完整包含在内。

```text
fixtures export-ignore
datasets/raw export-ignore
```

### 管理仓库

**Project admin（项目管理员）** → **Git repo（Git 仓库）**（`/projects/<project_id>/admin/git`）会展示该仓库、其 **Status（状态）**、**Base branch（目标分支）** 以及 **Manifest file（清单文件）**。该页面还包含 **Work on this locally（在本地处理）**、**Use your own Git client（使用你自己的 Git 客户端）** 和 **People with access（有访问权限的人员）** 等板块。Project admin 可从 Customize 中的 **Settings（设置）** 进入。目标分支是新会话和变更请求发起时所依据的分支。

在命令行（CLI）中，`kortix projects set --branch <branch>` 和 `--manifest <path>` 可以修改同样的这些字段。两者都需要 `project.settings.write` 权限。

#### GitHub 连接

`GET /v1/projects/<project_id>/git/connection` 会返回连接的 `state`（状态）：

| `state` | 含义 |
| --- | --- |
| `connected` | OpenChatly 可以访问该仓库。 |
| `reconnect_required` | OpenChatly GitHub App 的安装缺失、不可用，或与该仓库不匹配。请打开响应中的 `install_url` 以重新安装该 App。 |
| `unavailable` | OpenChatly 因某个无法通过 App 修复的原因而无法访问该仓库。 |
| `not_connected` | 该项目没有关联任何仓库。 |

#### 仓库断连（Repository disconnected）

OpenChatly 通过安装在仓库所有者账号上的 OpenChatly GitHub App 来访问 GitHub 仓库。当这种访问权限失效时，该项目即处于 **disconnected（已断连）** 状态。此时 `GET /v1/projects/<project_id>/git/connection` 会返回 `state: reconnect_required`、`reason: repository_disconnected`、一个 `disconnected_reason`（断连原因）、一条说明原因与修复方法的 `message`，以及一个 `install_url`。

| `disconnected_reason` | 原因 | 修复方法 |
| --- | --- | --- |
| `app_uninstalled` | OpenChatly GitHub App 已从该所有者账号上被卸载，或其连接已从你的 OpenChatly 账号中被移除。 | 由组织的某位 GitHub 所有者重新安装该 App：**Project admin（项目管理员）** → **Git repo（Git 仓库）** → **Reconnect GitHub（重新连接 GitHub）**。 |
| `app_suspended` | 某位所有者在 GitHub 上暂停（suspend）了该 App。 | 由某位 GitHub 所有者在 GitHub 的 **Settings → GitHub Apps** 下取消暂停。 |
| `repo_not_accessible` | 该仓库被删除、改名，或已从 App 的仓库访问范围中被移除。 | 由某位 GitHub 所有者在 GitHub 的 **Settings → GitHub Apps → OpenChatly → Repository access** 下重新添加该仓库，或者由你更换一个仓库。 |

在项目处于断连状态期间：

- 每一个读取该仓库的 API 路由都会以 `409` 应答，并返回 `code: repository_disconnected`、`reason`，以及相同的 message。项目详情仍可加载：其 `config.manifest_version.unknown_reason` 为 `repository_disconnected`，且 `git_connection.status` 为 `error`。
- 会话的创建与启动会立即以该 `409` 失败。已经运行中的会话则继续运行。
- 定时触发器（Scheduled triggers）会跳过每一次运行，并把该 message 记录为该触发器的最近一次错误。它们不会重试。
- 通过 OpenChatly git origin 执行的 `git clone`、`fetch` 和 `push` 会以 `remote: …` 的形式打印该 message。
- Web 应用会在侧边栏、**Git repo** 中，以及某个无法启动的会话上显示 **GitHub disconnected（GitHub 已断连）**。`kortix projects info` 会打印原因和重新连接的链接。

OpenChatly 最多每 5 分钟重新检查一次 GitHub。在 GitHub 上完成修复后，项目会在下一次检查时重新连接。通过 **Reconnect GitHub** 重新连接则会立即检查；曾存储旧安装的项目会迁移到新安装上。

#### 更换仓库

在 **Git repo** 下选择 **Change（更换）**，并输入新的 GitHub 仓库 URL。OpenChatly 会通过 GitHub App 验证访问权限。新仓库需要在其默认分支上具备清单文件。

请先停止活动中的会话，并关闭或合并处于打开状态的变更请求。新会话将使用新仓库；现有会话在更换之后无法重新启动。

该接口路由为 `PUT /v1/projects/<project_id>/git/repository`。它需要 `project.settings.write` 和 `project.connector.write` 权限。

#### 授予人员直接访问权限

托管仓库（managed repository）位于 OpenChatly 名下的 GitHub 上。若要允许某人在 github.com 上对其进行处理，请在 **People with access（有访问权限的人员）** 下添加其 GitHub 用户名，并赋予 **Can edit（可编辑）** 或 **Can view（可查看）** 权限。GitHub 会向其邮箱发送邀请。

这需要 `project.members.manage` 权限，且仅对托管仓库有效。对于你自己拥有的仓库，请在 GitHub 上管理访问权限。

#### 位于其他 Git 托管上的仓库

若要允许 OpenChatly 访问位于其他 Git 托管上的仓库，请用 `PUT /v1/projects/<project_id>/git-credential` 及请求体 `{ "token": "…" }` 存储一个令牌。OpenChatly 会将其作为一项平台凭据（platform credential）保存，而不是沙盒可读取的密钥。这需要 `project.connector.write` 权限。GitHub 仓库和托管仓库会以 `409` 拒绝此操作。

对于位于其他 Git 托管上的仓库，在 `origin` 指向该仓库的检出（checkout）目录中运行 `kortix sessions new`，即可创建会话分支。它会用你自己的 Git 凭据推送你当前的分支。

#### 无需克隆即可浏览

`kortix files` 读取的是已提交的仓库。它作用于默认分支，除非用 `--ref <branch|tag|sha>` 指定其他引用。每个子命令都需要 `project.file.read` 权限。

| 命令 | 作用 |
| --- | --- |
| `kortix files ls [<path>]` | 列出文件。 |
| `kortix files cat <path>` | 打印一个文件的内容。 |
| `kortix files search <query> [--content]` | 搜索文件名，或搜索文件内容。 |
| `kortix files history <path>` | 列出改动过某个文件的提交。 |
| `kortix files branches` | 列出各分支，及其相对于默认分支的领先（ahead）和落后（behind）情况。 |
| `kortix files commits [--path <p>]` | 列出 `--ref` 上的提交。 |
| `kortix files show <sha>` | 展示单个提交及其涉及的文件。 |
| `kortix files diff <sha> [--path <p>]` | 打印某个提交的补丁（patch）。 |
| `kortix files 内部工具 -o <file.zip> [--path <p>]` | 将仓库或某个子树下载为 zip 包。 |

对于运行中沙盒里尚未提交的文件，请使用 `kortix sessions cp <session_id>:<path> <dst>`。请参阅 [计算机（Computers）](/docs/zh/guide#计算机computers)。

#### 删除

`kortix projects rm <project_id>` 会删除一个项目。这需要 `project.delete` 权限。删除项目时，会一并删除其托管仓库。你自己连接的仓库则原样保留、不受影响。

通过 API，`DELETE /v1/projects/<project-id>` 会应答 `{ "ok": true, "deleted": true, "repo_deleted": <bool> }`。`repo_deleted` 表示是否有一个托管仓库随之被删除。该响应还为旧版客户端携带了 `archived: true`；其含义与 `deleted` 相同，并且不存在恢复操作。

## kortix.yaml 参考

`kortix.yaml` 是位于项目仓库根目录的清单文件。它定义了项目的各个智能体，以及每个智能体可以使用的一切。本节列出全部键。

该格式没有版本号。它只会以两种方式变更，从而保证今天有效的文件始终有效：

1. **新增的键是可选的**，省略它会保持今天的行为不变。
2. **被替换的键只是弃用（deprecated），绝不删除。** 旧键继续有效：OpenChatly 会按替换它的那个键来读取它。`kortix validate` 会显示一条警告，附上替代键和一个修复 id（fix id）。`kortix validate --fix` 会重写该文件及其导入文件中所有被弃用的键，并保留注释。OpenChatly 的每次写入操作都会保存最新的格式形态。 列出了这些键。

最小的实用清单文件如下：

```yaml
# yaml-language-server: $schema=https://kortix.com/schema/kortix.schema.json
default_agent: assistant  # 默认智能体：assistant

agents:
  assistant:              # 定义名为 assistant 的智能体
    description: Answers questions about the project.  # 描述：回答关于该项目的问题。
    prompt: You answer questions about this project. Read the files before you answer.  # 提示词：你负责回答关于本项目的问题。在回答前，请先阅读相关文件。
    tools: all                               # 工具：all（若省略：默认使用 all，但会触发警告）
    skills: all                              # 技能：all（若省略：不启用任何技能）
    workspace: { project_repository: true }  # 工作区配置：{ project_repository: true }（若省略：/workspace 中将不包含项目仓库）
```

所有键（key）均为可选。该智能体的任何工具调用都不会等待人工确认：如果省略 `permission`（权限）字段，其默认值为 `allow`（允许）。如果文件中没有定义 `agents`（智能体），则只会运行通过 `builtin_agents` 开启的内置智能体。

### 文件与模式（File and schema）

请将 `kortix.yaml` 放在项目仓库的根目录下。OpenChatly 会优先读取 `kortix.yaml`，若不存在则读取 `kortix.yml`，并加载其中引用的文件。建议在文件开头添加 schema（模式）声明行，这样 YAML 编辑器就能对每个键进行校验和自动补全：

```yaml
# yaml-language-server: $schema=https://kortix.com/schema/kortix.schema.json
```

`kortix schema` prints the same schema. `kortix schema --url` prints its URL.

Validate before you push:

```bash
kortix validate                                  # ./kortix.yaml and its imports
kortix validate --file config/kortix.yaml --json
kortix validate --scopes                         # every grantable kortix_permissions entry
```

| 标志（Flag） | 作用 |
| --- | --- |
| `--file <path>` | 校验指定的文件，而不是默认的 `./kortix.yaml`。 |
| `--json` | 打印 JSON 格式的校验报告：包含 `valid`（是否有效）、`path`（路径）和 `issues`（问题列表）。 |
| `--scopes` | 打印可授予的 `kortix_permissions` 条目及已重命名的条目，然后退出。 |
| `--no-dockerfile-lint` | 跳过对沙盒模板 Dockerfile 的检查。 |

- `kortix validate` 会为每个问题打印一行信息：包含文件路径、行号和列号（如 `kortix.yaml:14:7`）、键的路径（key path）以及修复建议。如果没有错误，退出码为 `0`；有一个或多个错误时，退出码为 `1`；如果文件缺失或不可读，退出码为 `2`。
- `kortix ship` 在提交前会运行相同的检查。
- 变更请求的合并操作会对合并后的清单进行模式（schema）检查。如果出现错误，合并会被拦截并返回 `422` `MANIFEST_INVALID`。警告（warning）永远不会拦截合并。
- 未知的键会被视为错误。这适用于顶层以及智能体（agent）块、命令（commands）、扩展（extensions）、`workspace`、App 块、触发器（trigger）的 `on` 和 `run`，以及被导入的文件。错误信息会指出最接近的键（如 `Did you mean "prompt"?`）或替代它的键。`env` 下的未知键仅作为警告。

`kortix validate` 和 `kortix ship` 还会检查清单周围的文件。以下情况均被视为错误：

- 智能体或命令引用的 `prompt_file` 不存在；
- `skills` 文件夹中没有 `SKILL.md`，或者 `SKILL.md` 的 frontmatter 中 `name:` 与该技能名称不匹配；
- `tools` 模块或 `extensions.<name>.pi` 的仓库路径不存在；
- 智能体的 `connectors` 或 `connectors_required` 中声明的 slug 未在 `connectors` 中定义（`kortix_slack`、`kortix_teams`、`kortix_email`、`kortix_telegram` 和 `computer` 始终视为已定义）；
- 智能体的 `secrets` 名称或触发器的 `secret_env` 未在 `env` 中定义。

当 Git 中的文件总大小超过 512 MiB，或单个文件达到 10 MiB 时，系统会发出警告。

> **Warning**
>
> `kortix.yaml` 会提交到 Git 中。绝对不要在其中写入任何密钥值（secret value）。请在 **Secrets（密钥）** 中设置值，在 **Connectors（连接器）** 中设置连接器的登录凭据。连接器的 `headers` 为纯文本。

### 当 kortix.yaml 出现问题时

OpenChatly 会在以下三个地方展示默认分支上该文件的问题：

1. **`kortix validate`**：打印每个问题及其所在的文件、行号和列号。
2. **项目界面**：显示带有错误信息的横幅，以及需要人工处理的警告。**Fix with My OpenChatly（使用 My OpenChatly 修复）** 会启动一个会话，让 My OpenChatly 修复该文件并为你打开一个变更请求以供审查。如果该文件将 My OpenChatly 排除在外，按钮会显示为 **Fix in a new session（在新会话中修复）**，并启动默认智能体的会话。带有修复 id 的警告（如弃用的键、旧格式）不会显示在横幅中：OpenChatly 下次向该文件写入更改时会自动修复它。
3. **每个会话的智能体**：会在其系统提示词（system prompt）中收到相同的问题列表，包含每个问题的行号和修复建议。智能体可以通过变更请求来修复该文件。

OpenChatly 拒绝写入包含错误（包括未知键）的文件：`kortix ship`、变更请求合并、写入清单的 API 路由以及 Web 应用中的文件编辑器都会因此停止。但如果包含错误的文件通过其他方式（如直接推送）进入了默认分支，它永远不会导致整个项目停止。OpenChatly 会运行有效的部分，并仅移除损坏的部分：

| 错误所在位置 | 运行状态 |
| --- | --- |
| 任何位置的未知键 | OpenChatly 会忽略该键。 |
| 智能体或触发器 | 该智能体或触发器会被关闭。指定该智能体的会话会失败，并报错说明问题。关闭的触发器不会被触发。 |
| 连接器、App、技能、工具、命令、扩展、空间（space）或沙盒模板 | 该条目将不可用。 |
| `project` 或 `default_agent` | 该键将使用其默认值。 |
| 任何其他键（`env`、`sandbox`、`policy`、`policies`、`approvals`、`imports`、`builtin_agents`）、YAML 语法错误或未知的 `kortix_version` | 没有任何项目智能体会运行。如果文件中设置了 `builtin_agents.my_kortix: true`，My OpenChatly 会运行，以便它可以修复该文件。 |

每条规则都是在收回权限。任何错误都不会赋予智能体超出文件所授予的权限。

### 旧版格式

使用此格式之前创建的项目仍然可以正常工作，无需更改：

- 包含 `kortix_version: 2` 的 `kortix.yaml`；
- 旁边没有 `kortix.yaml` 的 `kortix.toml`（`kortix_version = 1`）。

OpenChatly 会按照本页所述的格式读取该文件及其指向的文件：每个智能体的 `.md` frontmatter 会转换为智能体的键，正文（body）会转换为提示词（prompt），OpenCode 的 `permission` 和 commands 会转换为 `permission` 和 `commands`。此格式中没有对应位置的设置（如 OpenCode 插件）会被列为警告。`kortix validate` 会报告一个警告 `fix: legacy-format`，然后对转换后的文件进行校验。

`kortix validate --fix` 会永久转换这些文件：它会写入 `kortix.yaml`，在每个智能体的 `.md` 中仅保留提示词，并删除 `kortix.toml` 及其替代的 OpenCode 文件。OpenChatly 自身对项目进行的第一次更改（如新增触发器）会在该提交中进行相同的转换。其他编辑 `kortix.yaml` 的 `kortix` 命令会要求你先运行 `kortix validate --fix`。

如果 `kortix_version` 为其他任何值，将被视为错误，没有任何项目智能体会运行（如果文件中开启了 My OpenChatly，则 My OpenChatly 会运行）。

### 弃用的键

每一行中的旧键仍然有效。`kortix validate --fix` 会写入具有相同含义的替代键。

| 修复 id（Fix id） | 弃用的键 | 替代写法 |
| --- | --- | --- |
| `legacy-format` | `kortix_version: 2` 文件，或 `kortix.toml` | 转换后的文件：运行 `kortix validate --fix`（请参阅 [旧版格式](#旧版格式)）。 |
| `drop-kortix-version` | `kortix_version: 3` | 无需替代：直接删除该行。 |
| `tools-explicit` | 没有 `tools` 的智能体（它会获得所有工具） | `tools: all`，或它所需的工具列表 |
| `agent-disable` | `disable: true` | `enabled: false` |
| `agent-env` | 智能体的 `env` | `secrets` |
| `agent-kortix-cli` | `kortix_cli` | `kortix_permissions` |
| `agent-connectors-personal` | `connectors_personal` | `connectors_required` |
| `agent-repository-access` | `repository_access: true` | `workspace: { project_repository: true }` |
| `agent-workspace-mode` | `workspace: branch` 或 `workspace: runtime` | `workspace: { project_repository: true }` 或 `false` |
| `sandbox-templates` | 顶层的 `sandboxes` 列表 | `sandbox.templates` |
| `sandbox-singular` | 直接在 `sandbox` 上设置的镜像键（`image`、`dockerfile`、`context` 等） | 一个名为 `sandbox.default` 的 `sandbox.templates` 条目 |
| `acp-runtimes` | `runtimes`，以及智能体的 `runtime` 和 `agent` | 无需替代：直接删除它们。每个会话都运行 pi。 |
| `permission-renamed` | 已重命名的 OpenChatly 权限，如 `project.cr.open` | 它的新名称（`kortix validate --scopes` 会列出它们） |
| `tool-retired` | `tools` 中已废弃的 OpenChatly 工具名称：`kortix-connectors_call`、`kortix-connectors_describe`、`memory` | 无需替代：该名称会被移除，除非项目在其下注册了自己的工具（`tools.memory`）。对于 `memory`：智能体使用文件工具编辑 `memory/` 目录。 |

当弃用的键和它的替代键同时被设置且值不同时，OpenChatly 不会进行猜测：这会直接被视为错误。

### 示例项目

一个客服（支持）项目：包含两个智能体、一个技能、一个工具、两个命令、一个扩展、一个配置了只读规则集的连接器，以及一个定时触发器（每周执行）。

```yaml
# yaml-language-server: $schema=https://kortix.com/schema/kortix.schema.json
default_agent: support

project:
  name: support-desk
  description: Answers help desk tickets.

env:
  required: [HELPDESK_TOKEN]
  optional: [STRIPE_API_KEY]

sandbox:
  default: python
  templates:
    - slug: python
      name: Python 3.12
      image: python:3.12-slim
      cpu: 2
      memory: 4

# 注册表（Registries）：项目拥有的资源。注册表中的条目不会直接赋予任何智能体权限。
skills:
  refund-policy: skills/refund-policy

tools:
  lookup_order: tools/lookup_order.ts

commands:
  triage:
    description: Sort a ticket by urgency.
    prompt: "Read ticket $1 and reply with its urgency: low, normal or high."
  weekly-report:
    description: Write the weekly support report.
    prompt_file: commands/weekly-report.md

extensions:
  web-access:
    pi: npm:pi-web-access@0.30.0

connectors:
  - slug: helpdesk
    provider: http
    base_url: https://helpdesk.example.com/api
    auth:
      type: bearer
    policy_sets:
      read-only:
        description: Reads only.
        policies:
          - match: "get_*"
            action: always_run
          - match: "*"
            action: block

policy:
  default_mode: risk
policies:
  - match: "helpdesk.delete_*"
    action: block
approvals:
  ttl: 4h

# Agents: each one enables registered things by name.
agents:
  support:
    description: Answers help desk tickets.
    mode: primary
    prompt_file: agents/support.md
    permission:
      bash:
        "*": allow
        "git push *": ask
    tools: all
    skills: [refund-policy, kortix-cli]
    subagents: [researcher]
    commands: all
    extensions: [web-access]
    connectors: [helpdesk]
    secrets: [HELPDESK_TOKEN]
    kortix_permissions: [project.session.read, project.gitops.push]
    workspace: { project_repository: true }
  researcher:
    description: Looks up an order's history. Never edits files.
    mode: subagent
    prompt: You research orders and report what you find. Never edit files.
    permission:
      edit: deny
    tools: [read, glob, grep, lookup_order, web_search]
    connectors: [helpdesk]
    policy_sets:
      helpdesk: read-only

triggers:
  - slug: weekly-report
    name: Weekly report
    on:
      cron: "0 0 9 * * 1"
      timezone: Europe/Berlin
    run:
      agent: support
      prompt: Write the weekly support report for the last 7 days.
```

该仓库还包含 `agents/support.md`（提示词）、`skills/refund-policy/SKILL.md`（其中包含 `name: refund-policy`）、`commands/weekly-report.md` 以及工具模块：

```ts
// tools/lookup_order.ts
export default {
  description: 'Look up an order by id.',
  parameters: {
    type: 'object',
    properties: { id: { type: 'string', description: 'The order id' } },
    required: ['id'],
  },
  async execute(args: { id: string }) {
    return `order ${args.id}: shipped`;
  },
};
```

`kortix validate` 会显示每个智能体启用了哪些权限。`researcher`（研究员）智能体省略了大部分授权（grants），因此它不会获得这些权限中的任何一项：

```text
✓  kortix.yaml is valid

What each agent enables:
  support  skills=[refund-policy, kortix-cli]  subagents=[researcher]  commands=[all]  extensions=[web-access]  connectors=[helpdesk]  secrets=[HELPDESK_TOKEN]
  researcher  skills=[none (default-deny)]  subagents=[none (default-deny)]  commands=[none (default-deny)]  extensions=[none (default-deny)]  connectors=[helpdesk]  secrets=[none (default-deny)]
```

### 注册表与授权（Registries and grants）

项目负责注册存在的资源。每个智能体通过名称来启用它所使用的资源。已注册的资源在智能体显式启用之前，不会传递给任何智能体。

| 项目声明（The project declares） | 智能体启用方式（An agent enables it with） |
| --- | --- |
| `skills`：技能文件夹 | `skills` |
| `tools`：工具模块 | `tools` |
| `commands`：斜杠命令 | `commands` |
| `extensions`：智能体运行时扩展包 | `extensions` |
| `connectors`：应用和 API | `connectors`、`policy_sets` |
| `env`：密钥名称 | `secrets` |
| `apps`：应用（Apps） | `apps` |
| `agents`：其他智能体 | `subagents` |

- **授权（Grant）** 可以是 `all`（或 `*`）、`none`（或 `""`），或名称列表。包含 `*` 的列表表示全部。
- **省略即代表无。** 省略 `skills`、`subagents`、`commands`、`extensions`、`connectors`、`secrets`、`apps` 或 `kortix_permissions` 意味着不授予任何权限。
- **三个键默认开放：** `tools` 默认为 `all`（当智能体省略该键时，`kortix validate` 会发出警告），`permission` 默认为 `allow`，`codemode` 默认为 `on`。
- **`workspace.project_repository` 默认为 `false`。** 对于任何需要读取或修改仓库、运行仓库脚本或发起变更请求的智能体，请将其设置为 `true`。
- **名称必须存在。** 如果列出的技能、命令、扩展、子智能体或工具未被注册且不是内置的，将视为错误。
- **`secrets` 会传递到沙盒。** 被授权的密钥在智能体沙盒中表现为环境变量或受网络策略限制的密钥。模型登录凭据、连接器和 Git 凭据保留在 OpenChatly 服务端：智能体的模型和连接器设置决定它们的使用方式。
- **内置组件无需在注册表中声明。** OpenChatly 技能包括：`kortix-cli`、`kortix-memory` 及其他 `kortix-*` 技能。OpenChatly 工具包括：`web_search`、`image_search`、`image_gen`、`scrape_webpage`、`show`。请参阅 [OpenChatly 工具](#openchatly-工具)。内置工具包括：`bash`、`read`、`write`、`edit`、`glob`、`grep`、`question`、`task`。只有当智能体的 `skills` 授权中显式列出了某个 OpenChatly 技能或设置为 `all` 时，才会加载该技能。
- **My OpenChatly 仅在文件显式开启时运行。** `builtin_agents: { my_kortix: true }` 用于开启它，初始化清单（starter）会默认开启。如果没有该键、设置为 `false`，或文件无法被 OpenChatly 读取，则保持关闭。关闭时，请求 `mykortix` 智能体会返回 `409 builtin_agent_disabled` 错误。
- **会话运行的智能体。** 未指定智能体的会话或触发器会运行 `default_agent`。如果开启了 My OpenChatly 且未设置 `default_agent`，则会运行 My OpenChatly。当 My OpenChatly 启动一个未指定智能体的会话时，该会话会运行 `default_agent`；如果 `default_agent` 为 `mykortix`，则运行第一个启用的、`mode` 为 `primary` 或 `all` 的智能体。初始化清单会设置 `builtin_agents.my_kortix: true`、`default_agent: mykortix` 以及一个项目智能体 `worker`，因此新项目会运行 My OpenChatly，并由 My OpenChatly 将工作分配给 `worker`。
- **包含错误的文件** 如果设置了 `my_kortix: true`，仍会运行 My OpenChatly，以便 My OpenChatly 可以修复该文件。
- **扩展（Extensions）** 是智能体运行时的扩展包。一个包可以包含运行时扩展、技能、提示词或主题。变更请求合并时会构建 npm 包，会话永远不会在安装时拉取它们。会话在运行时启动时加载其扩展，因此更改会在运行中会话的下一次启动时生效。

{/* generated:kortix-yaml:start */}

{/* 由 apps/web/scripts/generate-kortix-yaml-doc.mjs 根据 packages/manifest-schema/src/json-schema.ts 生成。请在那里编辑描述，然后运行该脚本。 */}

### 顶层键（Top-level keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `imports` | list（列表） | — | 其集合会合并到此文件中的 YAML 文件或文件夹。请参阅 [imports（导入）](#imports导入)。 |
| `default_agent` | string（字符串） | — | 当会话或触发器未指定智能体时运行的智能体，也是 My OpenChatly 未指定智能体时启动的智能体。必须是一个已声明、已启用且 `mode` 为 `primary` 或 `all` 的智能体；当 `builtin_agents.my_kortix` 为 true 时，默认为 `mykortix`。若省略：当 My OpenChatly 开启时，默认使用 My OpenChatly。 |
| `project` | map（映射） | — | `name`：项目名称。更改名称的推送操作会重命名项目，在 OpenChatly 中的重命名操作也会提交到此字段。`description`：供阅读仓库的人员查看的项目描述文本。 |
| `env` | map（映射） | — | 项目所需的密钥名称。值存放在 Secrets（密钥）中，绝不存放在此文件中。请参阅 [env 键](#env-键env-keys)。 |
| `sandbox` | map（映射） | 平台默认镜像 | 沙盒模板及项目的默认模板。请参阅 [sandbox 键](#sandbox-键sandbox-keys)。 |
| `triggers` | list（列表） | — | 启动智能体工作的定时计划、Webhooks 和 App 事件。请参阅 [triggers 键](#triggers-键triggers-keys) 和 [Triggers（触发器）](/docs/zh/guide#触发器triggers)。 |
| `connectors` | list（列表） | — | 智能体可调用的应用和 API。请参阅 [connectors 键](#connectors-键connectors-keys) 和 [Connectors（连接器）](/docs/zh/guide#连接器connectors)。 |
| `apps` | map（映射） | — | App slug → App 配置块。请参阅 [apps 键](#apps-键apps-keys)。 |
| `skills` | map（映射） | OpenChatly 技能 | 技能名称 → 仓库文件夹。OpenChatly 技能（`kortix-*`）始终会被注册。请参阅 [skills 条目](#skills-条目skills-entries)。 |
| `tools` | map（映射） | OpenChatly 工具 | 工具名称 → 仓库模块。OpenChatly 工具始终会被注册。请参阅 [tools 条目](#tools-条目tools-entries)。 |
| `commands` | map（映射） | — | 斜杠命令名称 → 命令。请参阅 [commands 条目](#commands-条目commands-entries)。 |
| `extensions` | map（映射） | — | 扩展名称 → 包。请参阅 [extensions 条目](#extensions-条目extensions-entries)。 |
| `policy` | map（映射） | — | 当没有规则匹配时，对连接器调用的默认决策。请参阅 [policy 键](#policy-键policy-keys)。 |
| `policies` | list（列表） | — | 针对整个项目的连接器规则。它们在每个策略集（policy set）和基础规则之前运行。请参阅 [policy 键](#policy-键policy-keys)。 |
| `approvals` | map（映射） | — | 被挂起的连接器调用等待决策的时长。请参阅 [policy 键](#policy-键policy-keys)。 |
| `spaces` | map（映射） | — | 空间（Spaces）：包含房间（始终为第一个标签页）和已配置标签页的频道。智能体通过 `agents.<name>.space` 加入空间。 |
| `builtin_agents` | map（映射） | — | 平台添加到此项目的内置智能体。除非设置为 true，否则每个智能体均处于关闭状态。 |
| `agents` | map（映射） | — | 智能体名称 → 智能体配置块，可在此处或导入的文件中定义。名称由小写字母、数字、`-` 和 `_` 组成，最多 128 个字符。请参阅 [Agent 键](#智能体键agent-keys)。 |

### 智能体键（Agent keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `description` | string（字符串） | — | 智能体的功能描述。当另一个智能体可能将其作为子智能体启动时，会读取此描述来进行选择。 |
| `model` | string（字符串） | 项目默认值 | `provider/model`（提供商/模型）。请参阅 [Models（模型）](/docs/zh/guide#模型models)。 |
| `mode` | `primary`, `subagent`, `all` | `all` | `primary`：由人工和触发器运行；没有智能体会启动它。`subagent`：仅由另一个智能体启动；智能体选择器会隐藏它。`all`：两者皆可。 |
| `variant` | string（字符串） | — | 模型的推理级别：当模型提供该选项时，可选 `minimal`、`low`、`medium`、`high`、`xhigh` 或 `max`。 |
| `temperature` | number（数字） | 模型默认值 | 采样温度。如果模型拒绝自定义温度，则会忽略此设置。 |
| `top_p` | number（数字） | 模型默认值 | 核采样（Nucleus sampling）。 |
| `steps` | integer（整数），1 或更大 | 无限制 | 一次运行中的模型请求次数。达到限制的请求将不会获得工具，以便模型直接给出回答。 |
| `color` | string（字符串）或 `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info` | — | 接受此设置。会话不会使用它。 |
| `hidden` | boolean（布尔值） | `false` | `true`：智能体选择器不会列出该智能体。 |
| `options` | map（映射） | — | 接受此设置。会话不会使用它。 |
| `permission` | `ask`, `allow`, `deny` 或 map（映射） | `allow` | 决定哪些工具调用会运行、需要人工确认或永不运行。`skill` 和 `task` 属于 `skills` 和 `subagents`。请参阅 [Permission 规则](#权限规则permission-rules)。 |
| `prompt` | string（字符串） | — | 系统提示词。请设置 `prompt` 或 `prompt_file`，不可同时设置。 |
| `prompt_file` | string（字符串） | — | 指向 `.md` 文件的仓库路径。整个文件内容将作为系统提示词。 |
| `enabled` | boolean（布尔值） | `true` | `false`：没有会话会以此智能体启动，也没有智能体会将其作为子智能体启动。 |
| `codemode` | `on`, `only`, `off` | `on` | `on`：模型获得所有工具加上 `codemode`，`codemode` 会运行一个 JavaScript 脚本来调用其他工具。`only`：仅 `codemode`。`off`：不使用 `codemode`。脚本的调用遵循智能体的 `permission` 规则。 |
| `context` | `record`, `summary` | `record` | 当会话上下文填满时的处理方式。`record`：智能体立即在全新的上下文中继续，并在需要细节时逐字搜索会话的完整记录；不进行任何总结。`summary`：通过模型调用生成对话摘要，智能体基于该摘要继续。 |
| `tools` | `all`, `none`, list（列表）或 map（映射） | `all` | 智能体可调用的工具：内置工具、OpenChatly 工具和已注册的工具。列表形式仅允许使用列出的工具。`{ exclude: [bash] }` 允许使用除列出工具外的所有工具。 |
| `skills` | grant（授权）或 map（映射） | — | 智能体可加载的已注册技能和 OpenChatly 技能。`{ exclude: [...] }` 授予除列出技能外的所有技能。可选 "all"、"none"（默认）、名称列表，或 `{ exclude: [names] }` 以排除指定名称。 |
| `subagents` | grant（授权） | `none` | 此智能体可使用 `agent` 工具（别名 `task`）启动的智能体：必须是已声明、已启用、`mode` 为 `subagent` 或 `all`，且不是其自身的智能体。子智能体不能启动另一个子智能体。 |
| `commands` | grant（授权） | `none` | 智能体运行的已注册命令。 |
| `extensions` | grant（授权）或 map（映射） | — | 智能体会话加载的已注册扩展。`{ exclude: [...] }` 授予除列出扩展外的所有扩展。可选 "all"、"none"（默认）、名称列表，或 `{ exclude: [names] }` 以排除指定名称。 |
| `connectors` | grant（授权） | `none` | 智能体可调用的连接器 slug。 |
| `connectors_required` | list（列表） | — | 连接器 slug，是 `connectors` 的子集。会话不会对其进行校验。 |
| `policy_sets` | map（映射） | 基础规则 | 连接器 slug → 该连接器上的策略集名称。请参阅 [Connector 规则与审批](#连接器规则与审批connector-rules-and-approvals)。 |
| `secrets` | grant（授权） | `none` | 智能体沙盒接收的密钥名称。 |
| `apps` | grant（授权） | `none` | 当 App 的访问受限或为私有时，智能体可打开的 App slug。 |
| `kortix_permissions` | grant（授权） | `none` | 无论谁启动会话，该智能体都持有的项目权限（`project.*`）。`kortix validate --scopes` 会打印这些权限。账号级别的权限会报错。请参阅 [Agents（智能体）](/docs/zh/guide#智能体agents)。 |
| `workspace` | `branch`, `runtime`, `read` | — | 此智能体的新会话在 /workspace 中获得的内容。`workspace` 下的任何其他键均视为错误。 |
| `workspace.project_repository` | boolean（布尔值） | `false` | `true`：新会话会在 `/workspace` 中检出项目仓库，位于其专属的会话分支上。`false`：不进行检出，仓库调用会返回 `403` `session_repository_access_denied`。项目工具仍会加载。 |
| `sandbox` | string（字符串） | `sandbox.default` | 模板 slug，或设为 `default` 以使用平台镜像。 |
| `space` | string（字符串） | — | 智能体工作的空间（顶层 `spaces` 映射中的键，或单独的 slug）。仅用于分组。 |
| `network_egress` | map（映射） | — | 仅支持 `{ version: 1, default: deny, rules: [] }`。校验时会带有警告：OpenChatly 目前不强制执行此规则。 |

### 注册表条目（Registry entries）

#### skills 条目（skills entries）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `skills.<name>` | string（字符串） | — | 存放该技能 `SKILL.md` 文件的仓库文件夹。文件夹的最后一段即为名称：例如 `pdf` 对应 `skills/pdf`。`SKILL.md` 的 frontmatter 中需包含 `name: <name>`。 |
| `<name>` | string（字符串） | — | 由小写字母和数字组成，单词间用 `-` 连接，最多 64 个字符。以 `kortix-` 开头的名称会报错。 |

#### tools 条目（tools entries）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `tools.<name>` | string（字符串） | — | 指向 `.ts`、`.js`、`.mts`、`.mjs`、`.cts` 或 `.cjs` 模块的仓库路径。该模块需默认导出 `{ description, parameters, execute(args, context) }`。`parameters` 是一个 JSON Schema 对象。`execute` 返回一个字符串或 JSON 值。 |
| `<name>` | string（字符串） | — | snake_case 格式：以小写字母开头，后接字母、数字或 `_`，最多 64 个字符。使用内置工具名称或 `pty_` 开头的名称会报错。OpenChatly 工具的名称会覆盖原有的 OpenChatly 工具。`kortix tools eject <name>` 命令会将某个 OpenChatly 工具复制到 `tools/<name>.ts` 并写入其条目。 |

#### commands 条目（commands entries）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `commands.<name>` | map（映射） | — | 定义一个斜杠命令。只有当智能体的 `commands` 授权中列出了该命令时，它才能运行。其他智能体调用时会收到 `403` 错误：`{"error": "command_not_enabled", "command": "<name>", "agent": "<agent>"}`。 |
| `<name>` | string（字符串） | — | 由小写字母和数字组成，单词间用 `-` 连接，最多 64 个字符。在 `/` 菜单中，同名命令会隐藏同名的技能。 |
| `commands.<name>.description` | string（字符串） | — | 在 `/` 菜单中显示的描述。 |
| `commands.<name>.prompt` | string（字符串） | — | 提示词模板。`$ARGUMENTS` 获取命令后的所有文本。`$1`、`$2` 等按顺序获取单词，序号最大的变量会获取剩余的所有内容。如果模板中既没有 `$ARGUMENTS` 也没有 `$1`，则参数会被追加到末尾。请设置 `prompt` 或 `prompt_file`，不可同时设置。 |
| `commands.<name>.prompt_file` | string（字符串） | — | 指向 `.md` 文件的仓库路径。整个文件内容（包含 frontmatter）将作为模板。 |

#### extensions 条目（extensions entries）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `extensions.<name>` | map（映射） | — | 定义一个包：包含智能体运行时的扩展、技能、提示词或主题。 |
| `<name>` | string（字符串） | — | 由小写字母和数字组成，单词间用 `-` 连接，最多 64 个字符。 |
| `extensions.<name>.pi` | string（字符串）或 map（映射） | — | 格式为 `npm:<package>@<x.y.z>`（必须指定确切版本），或仓库路径（如 `extensions/audit.ts`，不可带前导 `./`），或 `{ source, extensions, skills, prompts, themes }` 映射。使用版本范围（version range）会报错。每个扩展都必须设置此项：未设置的扩展不会在任何新会话中加载。 |
| `extensions.<name>.pi.source` | string（字符串） | — | npm 的固定版本或仓库路径。在映射形式中为必填项。 |
| `extensions.<name>.pi.extensions` | list（列表） | 全部 | 仅加载包中匹配这些 glob 模式的扩展文件。设为 `[]` 则不加载任何文件。 |
| `extensions.<name>.pi.skills` | list（列表） | 全部 | 仅加载包中匹配这些 glob 模式的技能文件。设为 `[]` 则不加载任何文件。 |
| `extensions.<name>.pi.prompts` | list（列表） | 全部 | 仅加载包中匹配这些 glob 模式的提示词文件。设为 `[]` 则不加载任何文件。 |
| `extensions.<name>.pi.themes` | list（列表） | 全部 | 仅加载包中匹配这些 glob 模式的主题文件。设为 `[]` 则不加载任何文件。 |

### 章节键（Section keys）

#### env 键（env keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `env.required` | list（列表） | — | 项目所需的密钥名称：由大写字母、数字和 `_` 组成，且不以数字开头。控制台（dashboard）和 `kortix ship` 命令会提示输入缺失的值。缺失的值不会阻止会话启动。 |
| `env.optional` | list（列表） | — | 提供相同提示的可选密钥名称。值存放在 Secrets（密钥）中，绝不存放在此文件中。 |

#### sandbox 键（sandbox keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `sandbox.templates` | list（列表） | — | 命名的沙盒镜像列表。 |
| `sandbox.templates[].slug` | string（字符串） | 必填 | 必须唯一。由小写字母、数字、`-` 和 `_` 组成，最多 64 个字符。`default` 为保留字。 |
| `sandbox.templates[].name` | string（字符串） | 同 slug | 在模板选择器中显示的标签。 |
| `sandbox.templates[].entrypoint` | string（字符串） | 镜像默认值 | 覆盖容器的入口点（entrypoint）。 |
| `sandbox.templates[].image` | string（字符串） | — | 带有标签（tag）或摘要（digest）的镜像。缺少标签会报错。使用 `:latest` 会触发警告。请设置 `image` 或 `dockerfile`，不可同时设置。若都不设置：使用平台基础镜像。 |
| `sandbox.templates[].dockerfile` | string（字符串） | — | 指向 Dockerfile 的仓库路径。`kortix validate` 会对其进行 Lint 检查：禁止从仓库 `COPY` 文件、禁止 `RUN` heredoc、必须使用 Debian 系基础镜像。 |
| `sandbox.templates[].cpu` | integer（整数），1 或更大 | 平台默认值 | vCPU 核心数。超过 32 会触发警告，且 OpenChatly 会强制使用 32。 |
| `sandbox.templates[].memory` | integer（整数），1 或更大 | 平台默认值 | 内存大小（GiB）。超过 128 会触发警告，且 OpenChatly 会强制使用 128。 |
| `sandbox.templates[].disk` | integer（整数），1 或更大 | 平台默认值 | 磁盘大小（GiB）。超过 500 会触发警告，且 OpenChatly 会强制使用 500。 |
| `sandbox.templates[].container_runtime` | boolean（布尔值） | `false` | `true`：在沙盒内部运行 Docker。 |
| `sandbox.templates[].residential_proxy` | boolean（布尔值）或 map（映射） | — | `true`，或 `{ country: us }`：沙盒的 Web 流量通过住宅 IP 地址发出，按 GB 从积分中扣费。OpenChatly 主机和包注册表会直接连接。仅在部署环境支持的情况下，会话才会启动。不属于镜像配置的一部分。 |
| `sandbox.default` | string（字符串） | `default` | `sandbox.templates` 中的 slug，或设为 `default` 以使用平台镜像。 |

#### triggers 键（triggers keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `slug` | string（字符串） | 必填 | 必须唯一。由小写字母、数字、`-` 和 `_` 组成，最多 128 个字符。 |
| `name` | string（字符串） | 同 slug | 在控制台（dashboard）中显示的标签。 |
| `enabled` | boolean（布尔值） | `true` | `false`：触发器不会被触发。 |
| `filter` | map（映射） | — | Payload 路径 → 值（等于），或以下操作符之一：`not`、`in`、`exists`、`prefix`、`not_prefix`。只有当每个路径都匹配时，才会触发。 |
| `max_runs_per_hour` | integer（整数），1 或更大 | `60` | 触发器在任意 60 分钟内启动的运行次数。 |
| `max_runs_per_day` | integer（整数），1 或更大 | — | 触发器在一个 UTC 日内启动的运行次数。 |
| `max_lateness` | string（字符串） | — | 仅适用于定时计划，`60s` 或更长。如果错过的触发时间晚于此时长，则不再运行。 |
| `overlap` | `skip`, `allow` | 定时计划为 `skip`，其他为 `allow` | `skip`：在上一次运行处于活动状态时，挂起本次触发。当 `run.session` 为 `reuse`、`pinned` 或 `keyed` 时：在上一次提示词仍在该会话中等待时挂起。 |
| `on` | map（映射） | 必填 | 触发器的触发条件：定时计划（`cron`、`every` 或 `at`）、Webhook 或 App 事件。 |
| `on.cron` | string（字符串） | — | 6 字段的 Cron 表达式，秒在前：`"0 0 9 * * 1"` 表示每周一 09:00。触发器每 60 秒最多触发一次。 |
| `on.timezone` | string（字符串） | `UTC` | `cron` 和 `at` 使用的 IANA 时区。 |
| `on.every` | string（字符串） | — | 固定周期：一个整数加上 `s`、`m`、`h` 或 `d`，至少为 `60s`。 |
| `on.at` | string（字符串） | — | 在指定的 ISO-8601 时间触发一次，例如 `2026-06-01T09:00:00Z`。 |
| `on.webhook` | map（映射） | — | 在接收到发往触发器 Webhook URL 的签名请求时触发。 |
| `on.webhook.secret` | string（字符串） | 必填 | 用于对发往触发器 Webhook 的请求进行签名的密钥名称。 |
| `on.event` | string（字符串） | — | 配合 `on.app` 使用：App 事件名称，或设为 `"*"` 表示所有事件。 |
| `on.app` | string（字符串） | — | App 的 slug。触发器会响应该 App 的事件。 |
| `run` | map（映射） | 必填 | 触发后运行的内容：智能体的一轮对话，或对 App 的调用。 |
| `run.agent` | string（字符串） | `default_agent` | 已声明的智能体。 |
| `run.prompt` | string（字符串） | — | 运行的第一条消息。除非设置了 `run.app`，否则为必填项。 |
| `run.session` | `fresh`, `reuse`, `pinned`, `keyed` | `fresh` | `fresh`：每次触发创建一个新会话。`reuse`：使用此触发器创建的最后一个会话，若无可用会话则创建新会话。`pinned`：使用 `run.session_id` 指定的会话。`keyed`：根据 `run.session_key` 的值，每个值对应一个会话。 |
| `run.session_key` | string（字符串） | — | 配合 `keyed` 使用：基于 payload 的模板，例如 `"{{ body.chat_id }}"`。如果渲染出的键为空，则按 `fresh` 处理。 |
| `run.session_id` | string（字符串） | — | 要运行的会话 ID。当模式为 `pinned` 时为必填项。 |
| `run.model` | string（字符串） | 智能体默认模型 | `provider/model`（提供商/模型）。 |
| `run.app` | string（字符串） | — | 触发后调用此 App，而不是调用智能体。 |
| `run.path` | string（字符串） | — | 配合 `run.app` 使用：请求路径。必须以 `/` 开头。 |
| `run.method` | `POST`, `GET` | — | 配合 `run.app` 使用：请求方法。 |
| `run.payload` | map（映射） | — | 配合 `run.app` 使用：请求体。 |
| `type` | `cron`, `webhook`, `app`, `change_request` | — | 在扁平形式（flat form）中必填：指没有 `on` 和 `run` 的触发器。在 `on` 旁边设置 `type` 会报错。 |
| `agent` | string（字符串） | — | `run.agent` 的扁平形式。 |
| `session_mode` | `fresh`, `reuse`, `pinned`, `keyed` | — | `run.session` 的扁平形式。 |
| `session_key` | string（字符串） | — | `run.session_key` 的扁平形式。 |
| `session_id` | string（字符串） | — | `run.session_id` 的扁平形式。 |
| `prompt` | string（字符串） | — | `run.prompt` 的扁平形式。 |
| `model` | string（字符串） | — | `run.model` 的扁平形式。 |
| `cron` | string（字符串） | — | `on.cron` 的扁平形式，需配合 `type: cron`。 |
| `run_at` | string（字符串） | — | `on.at` 的扁平形式，需配合 `type: cron`。 |
| `timezone` | string（字符串） | — | `on.timezone` 的扁平形式。 |
| `secret_env` | string（字符串） | — | `on.webhook.secret` 的扁平形式，需配合 `type: webhook`。 |
| `app` | string（字符串） | — | `on.app` 的扁平形式，需配合 `type: app`。 |
| `target` | map（映射） | — | `run.app`、`run.path`、`run.method` 和 `run.payload` 的扁平形式：`{ app, path, method, payload }`。 |
| `every` | string（字符串） | — | `on.every` 的扁平形式，需配合 `type: cron`。 |

#### connectors 键（connectors keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `slug` | string（字符串） | 必填 | 必须唯一。由小写字母、数字、`-` 和 `_` 组成，最多 128 个字符。`kortix_slack`、`kortix_teams`、`kortix_email`、`kortix_telegram`、`kortix_discord` 和 `computer` 为内置连接器的保留字。 |
| `name` | string（字符串） | 同 slug | 显示标签。 |
| `enabled` | boolean（布尔值） | `true` | `false`：关闭该连接器。 |
| `provider` | `pipedream`, `composio`, `mcp`, `openapi`, `postman`, `graphql`, `http`, `channel` | 必填 | OpenChatly 访问应用或 API 的方式。当你连接频道时，OpenChatly 会自动写入 `channel` 条目。 |
| `app` | string（字符串） | — | `composio` 和 `pipedream`：应用名称。对这两种提供商为必填项。 |
| `url` | string（字符串） | — | `mcp`：服务器 URL。为必填项。 |
| `endpoint` | string（字符串） | — | `graphql`：端点（endpoint）。为必填项。 |
| `base_url` | string（字符串） | — | `http`：基础 URL。为必填项。 |
| `transport` | `http`, `sse` | `http` | 仅适用于 `mcp`。 |
| `spec` | string（字符串） | — | `openapi` 和 `postman`：规范（spec）的 URL 或仓库路径。如果不设置，连接器将无法加载。 |
| `authorization_strategy` | `project`, `user` | `project` | `project`：连接器的账号属于项目。`user`：每个用户连接自己的账号。 |
| `sensitive` | boolean（布尔值） | `false` | `true`：当没有规则匹配时，任何调用（包括读取操作）都需要人工审批。 |
| `auth` | map（映射） | — | OpenChatly 发送凭据的方式。凭据保存在 OpenChatly 中，绝不保存在此文件中。 |
| `auth.type` | `bearer`, `basic`, `custom`, `api_key`, `oauth1`, `hmac`, `aws_sigv4`, `mtls`, `none` | 必填 | `oauth1` 仅适用于 `openapi`、`postman` 和 `http`。 |
| `auth.in` | `header`, `query`, `cookie` | `header` | 凭据的传递位置。 |
| `auth.name` | string（字符串） | — | Header、query 或 cookie 的名称。对于 `custom` 和 `api_key` 为必填项。 |
| `auth.prefix` | string（字符串） | — | 凭据值前面的文本，例如 `Bearer`。 |
| `headers` | map（映射） | — | 静态请求头，最多 32 个。其值在 Git 中以纯文本形式存储。 |
| `policies` | list（列表） | — | 基础规则：`{ match, action, conditions }`。 |
| `policy_sets` | map（映射） | — | 规则集名称 → `{ description, policies }`：可通过 `agents.<name>.policy_sets` 授予智能体的规则集。规则集名称由小写字母、数字、`-` 和 `_` 组成，最多 64 个字符，且不能为 `base`。最多 32 个规则集，每个规则集最多 200 条规则。不适用于 `channel` 连接器。 |

#### policy 键（policy keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `policy.default_mode` | `allow_all`, `risk` | `allow_all` | `allow_all`：调用直接运行。`risk`：读取操作直接运行，写入或删除操作需等待审批。 |
| `policies[].match` | string（字符串） | 必填 | 必填。针对 `<connector-slug>.<tool>` 的 glob 模式（如 `gmail.send_*` 或 `*.delete*`），或 `/regex/flags` 正则表达式。不区分大小写。 |
| `policies[].action` | `always_run`, `require_approval`, `block` | 必填 | 必填。匹配到的调用所执行的操作。 |
| `policies[].conditions` | list（列表） | — | 必须满足所有条件。每个条件的格式为 `{ arg, match, negate }`：`arg` 是调用参数中的点分路径（dot path），`match` 是 glob 模式或 `/regex/` 正则表达式，`negate: true` 表示取反。 |
| `approvals.ttl` | string（字符串） | `24h` | 一个整数加上 `m`、`h` 或 `d`，例如 `30m`、`4h` 或 `7d`。OpenChatly 会将其限制在 5 分钟到 30 天之间。 |

#### apps 键（apps keys）

| 键 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `apps.<slug>` | map（映射） | — | 单个应用的部署设置。任何其他键均视为错误。其包含的键有：`path`、`type`、`image`、`dockerfile`、`command`、`port`、`root`、`output_dir`、`install_command`、`build_command`、`spa`、`readiness_path`、`idle_timeout_seconds`、`always_on`、`uses`、`resources`、`env`、`secrets`、`processes`、`http_service`、`services`、`mounts`、`vm`、`deploy`、`labels`、`display`。完整参考：[在 kortix.yaml 中配置](#在-kortixyaml-中进行配置)。 |

{/* generated:kortix-yaml:end */}

### 权限规则（Permission rules）

`agents.<name>.permission` 决定了哪些工具调用会直接运行、等待人工确认，或永不运行。当智能体请求确认时，人工会看到什么内容，请参阅 [Agents（智能体）](/docs/zh/guide#智能体如何在风险操作前先征求同意)。

```yaml
permission:
  bash:
    "*": allow
    "git push *": ask
    "rm -rf *": deny
  edit:
    "*": allow
    "secrets/*": deny
  external_directory: deny
  webfetch: ask
```

- **值（Value）。** 为每个工具指定一个操作：`allow`（允许）、`ask`（询问）或 `deny`（拒绝）。也可以是一个 `键 → 操作` 的映射，或 `键 → glob模式 → 操作` 的嵌套映射。
- **键（Keys）。** 代表一种能力（capability）：`read`、`edit`、`glob`、`grep`、`bash`、`external_directory`、`question`、`webfetch`、`websearch`。也可以是工具自身的名称，工具名称的优先级高于其所属的能力。
- **遵循特定能力的工具。** `write` 遵循 `edit` 能力。项目自定义的 `memory` 工具（已退役的 OpenChatly 工具的导出副本）遵循 `edit` 能力，若仅用于查看则遵循 `read` 能力。`image_gen` 遵循 `edit` 能力。`web_search` 和 `image_search` 遵循 `websearch` 能力。`scrape_webpage` 遵循 `webfetch` 能力。
- **仅支持操作（Action only）。** `question`、`webfetch` 和 `websearch` 只能指定操作，不支持 glob 模式映射。
- **`bash` 的 glob 匹配。** 会匹配一行中的每个命令。在 `a; b`、`a | b` 或 `$(b)` 中，以最严格的匹配结果为准：优先 `deny`，其次 `ask`，最后 `allow`。
- **路径 glob 匹配。** 匹配相对于 `/workspace` 的文件路径。`/workspace` 之外的路径也会受 `external_directory` 规则的约束。路径规则不约束 `bash` 命令。
- **优先级（Precedence）。** 无论键的顺序如何，最具体的匹配规则优先。模式（pattern）最长的规则最具体。
- `permission.skill` 和 `permission.task` 是无效的键（会报错）。请使用 `skills` 和 `subagents`。

### 连接器规则与审批（Connector rules and approvals）

OpenChatly 会按照以下顺序决定每次连接器调用的处理方式。在每个列表中，第一个匹配到的规则将生效。

1. 项目的 `policies`（全局策略）。
2. 调用方智能体在该连接器上设置的策略集（`agents.<name>.policy_sets`）。如果该连接器未定义某个策略集，则会阻断该智能体在该连接器上的所有调用。
3. 连接器自身的 `policies`（基础规则）。
4. 如果没有规则匹配：对于 `sensitive`（敏感）连接器，调用会被挂起以等待人工审批。否则，由 `policy.default_mode`（默认策略模式）决定。

策略集或基础规则不能放宽项目级规则的限制。但策略集可以为其所属的智能体放宽基础规则的限制。

```yaml
policy:
  default_mode: risk
policies:
  - match: gmail.send_email
    action: require_approval
    conditions:
      - arg: to
        match: "*@example.com"     # a glob, or /regex/ in slashes
  - match: gmail.send_email
    action: block
approvals:
  ttl: 4h
```

- 如果智能体的 `policy_sets` 条目中引用了该连接器未定义的策略集，将视为错误。如果该条目引用的连接器未被授予该智能体，或者未在 `connectors` 中声明，则会触发警告：该条目不会生效。
- `kortix validate` 不会校验 `policy` 或 `policies`。当 OpenChatly 同步连接器时，如果遇到格式错误的规则，会跳过该规则并将其报告为连接器同步错误。
- 被挂起的调用如果在 `approvals.ttl` 规定的时间内无人做出决策，将会过期。关于如何审批挂起的调用，请参阅 [Connectors（连接器）](/docs/zh/guide#审批被挂起的操作)。

### 沙盒模板（Sandbox templates）

会话会按照以下顺序选择其沙盒模板：

1. 会话请求中指定的模板。
2. 运行该会话的智能体的 `sandbox` 配置。
3. `sandbox.default`（默认沙盒）。
4. 平台默认镜像。

硬件配置值小于 1 会报错。大于最大值的配置会触发警告，且 OpenChatly 会将其截断至最大值。`gpu` 配置会触发警告且不会生效。直接在 `sandbox` 上设置镜像相关的键（`image`、`dockerfile`、`slug`、`cpu`、`memory`、`disk`、`entrypoint`、`context`、`context_dir`、`gpu`）会报错：请将它们放入模板中。

硬件配置是镜像的一部分，因此更改会在下一次会话时生效：运行中的会话会保持其原有的规格。在阿里云（Alibaba）上，`container_runtime` 需要 Gen2（MicroVM）模板：Gen1 模板无法运行嵌套的 Docker。Gen2 模板仅接受 Ubuntu 和 Debian 镜像，且此处的 `disk`（磁盘）大小包含了镜像本身，因此需要预留足够的空间。

如果模板既没有设置 `image` 也没有设置 `dockerfile`，则会使用其自身的规格和设置来构建平台镜像。该模板的首个会话会等待该构建过程完成，这与任何其他模板的行为一致。

#### 住宅 IP（Residential IP）

模板上的 `residential_proxy` 配置会将沙盒的 Web 流量通过住宅 IP 地址发出。`country` 参数需填写 ISO 3166-1 标准的两位字母国家代码（alpha-2）；如果不指定该参数，分配的地址可能来自任何国家。

```yaml
sandbox:
  default: web
  templates:
    - slug: web
      residential_proxy: true
    - slug: shop-us
      image: python:3.12-slim
      residential_proxy: { country: us }
```

1. 通过住宅地址产生的流量将按 GB 从你的积分（credits）中扣费。
2. OpenChatly 自身的主机（包括 API、模型网关、启动文件存储）以及常用的包注册表会直接连接（不经过代理）。
3. 启用该功能时会阻断 UDP 协议，因此 QUIC 和 WebRTC 无法泄露沙盒的真实地址。
4. 使用该模板的会话仅在部署环境提供住宅 IP 且使用 Platinum 沙盒提供商时才会启动。在其他情况下，会话将无法启动，并提示“此沙盒模板请求住宅 IP，但当前部署环境不提供此功能”。它绝不会回退使用沙盒自身的地址。`kortix validate` 会为每个请求了住宅 IP 的模板打印警告。
5. 这是一个启动时的配置，不属于镜像的一部分：修改它不会触发重新构建。新启动的沙盒会使用当前配置值；而运行中的沙盒会保持其原有配置。
6. 在 **Project admin** → **Sandbox templates** 中创建的模板具有相同的设置，即 **Residential IP** 复选框。

沙盒内各目录的持久化机制：

- `/workspace` 存放当前会话的文件，仅在会话的生命周期内保留。
- `/drives`（Drive）存放你的文件（`/drives/me`），这些文件在你的各个会话之间共享，并在你手动删除前一直保留。智能体所属的共享驱动器（Shared Drive）会挂载到 `/drives/<name>`。共享驱动器目前为实验性功能，默认处于关闭状态。请在 **Project admin** → **Feature flags** 中开启。请参阅 [Drive（驱动器）](/docs/zh/guide#云盘drive)。
- 其他任何目录（如主目录、`/tmp`、已安装的包）在会话重新打开时都可能丢失。请将工具放入沙盒模板中。

### imports（导入）

`imports` 用于将清单（manifest）拆分到多个 YAML 文件中。OpenChatly 会首先将它们合并。校验（Validation）、触发器（triggers）、授权（grants）以及连接器同步（connector sync）均读取合并后的清单。

```yaml
# kortix.yaml
default_agent: assistant
imports:
  - triggers/          # every .yaml and .yml file below this folder
agents:
  assistant:
    prompt: You write reports.
```

```yaml
# triggers/reports/weekly.yaml
triggers:
  - slug: weekly-report
    on:
      cron: "0 0 15 * * 0"
    run:
      agent: assistant
      prompt: Build the weekly report.
```

1. 路径相对于仓库根目录。使用 `..`、绝对路径或 glob 模式均会报错。如果路径未匹配到任何 `.yaml` 或 `.yml` 文件，也会报错。
2. 导入文件夹时，会获取该文件夹下任意深度的所有 `.yaml` 和 `.yml` 文件，并按路径排序。
3. 被导入的文件中只能包含 `agents`、`apps`、`commands`、`connectors`、`extensions`、`skills`、`tools`、`triggers` 和 `imports`。出现任何其他键均会报错。
4. 导入最多支持嵌套 8 层和 200 个文件。出现循环引用会报错。同一个文件被引用两次时，只会合并一次。
5. 一个名称只能对应一个文件。如果在两个文件中声明了相同的触发器 slug、连接器 slug、智能体名称、App slug、技能、工具、命令或扩展，将会报错，并在错误信息中指出这两个文件。
6. 条目按以下顺序合并：首先是导入方文件（主文件），然后是其 `imports` 列表中列出的文件。
7. 在 OpenChatly 中对某个条目进行编辑时，会重写声明该条目的文件。如果是新增条目，则会写入 `kortix.yaml`。

损坏的导入会导致整个清单（manifest）校验失败：

```text
error imports: triggers "weekly-report" is declared in both triggers/a.yaml and triggers/b.yaml — one name, one file
```

## 智能体工具（Agent tools）

智能体在会话中调用的工具包括：每个智能体都拥有的 OpenChatly 工具、仅 My OpenChatly 拥有的工具、用于启动和协调其他智能体的工具，以及图像生成工具。

### OpenChatly 工具

OpenChatly 维护了五个核心工具。每个项目默认注册所有五个工具，无需额外配置。除非智能体的 `tools` 配置对其进行了限制，否则每个智能体都会获得这些工具。

| 工具 | 功能描述 |
| --- | --- |
| `web_search` | 搜索网页。返回标题、URL、摘要和简短回答。 |
| `image_search` | 搜索图像。返回图像 URL、标题、来源页面和尺寸。 |
| `image_gen` | 使用项目可用的图像模型生成或编辑 1 到 4 张图像，并将其保存在工作区中。请参阅 [Generate images（生成图像）](#生成图像generate-images)。 |
| `scrape_webpage` | 获取一个或多个网页，并将其转换为 Markdown 格式返回。 |
| `show` | 向会话中的人工用户展示文件、图像、URL、文档或文本。每个展示项如果其路径是大小不超过 32 MiB 的图像文件（png、jpg、jpeg、webp、gif、avif、svg），且在 2 秒内被读取，则会附带 `sha256`（其字节的小写十六进制 SHA-256 哈希值）。 |

- **查看会话拥有的工具：** 在项目根目录运行 `kortix tools ls`。
- **接管 OpenChatly 工具：** `kortix tools eject <name>` 会将沙盒运行的源代码写入 `tools/<name>.ts`，并将工具指向该文件。导出的副本只能导入 `node:*` 模块。`web_search`、`image_search` 和 `scrape_webpage` 使用 `context.env` 中的 `KORTIX_API_URL` 和 `KORTIX_TOKEN` 调用 OpenChatly API。`image_gen` 使用 `KORTIX_LLM_BASE_URL` 和 `KORTIX_TOKEN` 调用 OpenChatly LLM 网关。`show` 作用于项目检出目录中的文件。
- **`memory` 不是 OpenChatly 工具。** 如果在智能体的 `tools` 配置中命名了 `memory`，`kortix.yaml` 会触发警告且该名称不生效；`kortix validate --fix` 会将其删除。如果项目注册了自己的 `tools.memory` 模块，则会保留它。智能体通过 `read`、`write` 和 `edit` 来编辑 `memory/` 目录。My OpenChatly 通过 [`kortix_memory`](#my-openchatly-记忆my-openchatly-memory) 记住每个用户。
- **`context.turnId`** 在工具的 `execute(args, context)` 接收到的 `context` 中是可选的。它代表当前调用所属的对话轮次（turn），同一轮次的所有调用（包括来自 `codemode` 脚本或子智能体的调用）共享相同的 `turnId`。`context.signal` 则可能因调用而异。建议基于 `turnId` 设置每轮调用的限制。

### My OpenChatly 工具

My OpenChatly（内置智能体）额外拥有九个工具。其中八个通过 `--json` 参数在沙盒内运行 `kortix` CLI；`kortix_memory` 则直接调用 API。每个工具返回一个 JSON 对象：包含 Web 应用在会话中展示的 `card`（卡片）、供模型使用的 `data`（数据），以及当 OpenChatly 拒绝或命令失败时的 `error`（错误）。其契约为 `@kortix/api-contract/kortix-tool-card`。只有在编译后的配置中的 `kortix_tools` 命名了这些工具时，它们才会被加载。平台的 My OpenChatly 配置默认包含它们；项目自定义的智能体不会获得这些工具。

| 工具 | 操作 | 运行的 CLI 命令 |
| --- | --- | --- |
| `kortix_agents` | `list`, `models`, `get`, `create`, `update`, `set_access` | `kortix agents ls`, `models ls`, `agents config`, `agents scope` |
| `kortix_sessions` | `list`, `read`, `message`, `stop` | `kortix sessions ls`, `sessions log`, `sessions chat --queue`, `sessions stop` |
| `kortix_schedules` | `follow_up`, `wake_on`, `events`, `list`, `create`, `automate`, `test`, `runs`, `pause`, `resume`, `remove` (别名 `delete`), `run_now` | `kortix loop`, `triggers add --on …`, `triggers events --connector`, `triggers ls` 和 `loops ls`, `triggers add --runtime`, `triggers add <slug> --apply`, `triggers fire --dry-run`, `triggers runs`, `triggers pause/resume/rm/run` |
| `kortix_connectors` | `list`, `find`, `add`, `connect` | `kortix connectors ls`, `connectors catalog`, `connectors catalog install`, `connectors connect` |
| `kortix_people` | `list`, `pending`, `invite`, `set_role`, `remove` | `kortix access ls`, `access pending`, `access invite`, `access grant`, `access revoke` |
| `kortix_access` | `me`, `who_can_grant` | `kortix whoami`, `kortix access ls` |
| `kortix_usage` | `summary`, `top_sessions` | `kortix billing costs` |
| `kortix_change_requests` | `list`, `get`, `merge`, `close` | `kortix cr ls`, `cr show`, `cr diff`, `cr merge`, `cr close` |
| `kortix_memory` | `list`, `view`, `save`, `delete` | 无 CLI：`/v1/projects/:id/memory/me/agent/mykortix`。请参阅 [My OpenChatly 记忆](#my-openchatly-记忆my-openchatly-memory)。 |

- **`kortix_schedules`（计划任务）。** `follow_up`、`wake_on`、`list`、`create`、`pause`、`resume`、`remove` 和 `run_now` 会直接修改运行时数据并立即生效，不会更改项目文件。`automate` 会将持久化触发器写入默认分支的 `kortix.yaml` 中，支持定时计划、Webhook、连接器事件或 App 事件。`test` 使用模拟 Payload 运行触发器，但不会实际触发。`runs` 列出其最近的运行记录。
- **权限控制。** 每个工具都使用会话令牌（session token）执行操作，因此 OpenChatly 会根据用户自身的项目角色检查每个操作。如果操作被拒绝，将返回 `error.kind: "denied"` 及 `error.grantors`（可以授予该权限的项目经理、账户所有者和管理员）。卡片上会展示这些信息。
- **机器可读的错误。** 当设置 `KORTIX_ERROR_FORMAT=json` 时，CLI 会向 stderr 输出一行 `{"kortix_error":{…}}`，而不是人类可读的尾部信息。该行包含 `kind`（`denied` 或 `failed`）、`status`、`code`、`action` 和 `message`（在已知情况下）。任何运行该 CLI 的程序都可以设置此环境变量。
- **启动工作** 请使用 `agent` 工具，而不是这些工具。每次交接工作都是一个独立的会话。从 My OpenChatly 发起时，默认在后台运行：调用会立即返回子任务的 `task_id`，当子任务完成时，API 会将子任务的报告作为新消息传递到调用方会话中。请参阅 [Agents working together（智能体协作）](#智能体协作agents-working-together)。
- **变更请求（Change requests）。** `kortix_change_requests` 可以列出未决的变更请求（编号、标题、作者、状态），读取单个请求（摘要、更改的文件、是否可合并），以及合并或关闭请求。My OpenChatly 仅在用户在对话中同意后才会执行合并。合并或关闭变更请求需要 `project.review.act` 权限。
- **运行多个智能体** 请使用 `workflow` 工具：一个包含 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的简短脚本。每个 `agent()` 都是一个真实的子会话。会话会以实时卡片的形式展示运行状态。请参阅 [Workflows（工作流）](#工作流workflows)。

#### My OpenChatly 记忆（My OpenChatly memory）

`kortix_memory` 是 My OpenChatly 关于其对话用户的记忆，跨越该项目中与用户的每一次会话。该功能默认仅对 My OpenChatly 开启：项目自定义的智能体永远不会获得此功能。

- **存储机制。** 每个事实以独立的 Markdown 文件形式存储在用户专属文件夹 `/Users/<person>/Memory/mykortix/<name>.md` 中。不会在其他地方存储。没有专门的管理界面：用户可以直接询问 My OpenChatly 它记住了什么、修改某个页面或要求遗忘。其他成员永远无法看到这些记忆。
- **页面结构。** 包含 Front-matter：`name`（小写 slug，最多 64 个字符）、`description`（单行，最多 200 个字符，用于判断相关性）和 `type`，然后是 `# Title` 和事实内容（最多 16,384 字节）。类型包括：`user`（用户身份）、`feedback`（工作偏好）、`project`（工作内容）、`reference`（资源位置）。`feedback` 或 `project` 类型的页面必须以 **Why:** 和 **How to apply:** 结尾。`[[other-name]]` 用于链接相关页面。如果用户在文件夹中创建的文件没有 `name`，则使用文件名作为名称。
- **操作。** `list`（索引）、`view`（`name`）、`save`（`name`, `type`, `description`, `body`, 可选 `title`）、`delete`（`name`）。`save` 会替换同名页面或创建新页面，因此同一个事实不会被保存两次。如果名称不是合法的 slug，将在请求前被拒绝。检测到密钥或密码会被拒绝（`422 secret_detected`）。每个用户最多 200 个页面（`409 memory_full`）。卡片会提示 `Remembered: …`、`Updated: …` 或 `Forgot: …`。
- **回忆机制。** My OpenChatly 的每一轮对话开始时，都会将会话所有者的页面索引追加到系统提示词中，格式为每行 `- [Title](name.md) — description`，最多 8,000 个字符。此功能依赖 Drive，不依赖频道。如果其他成员向该会话发送提示词，则不会获取索引。
- **无 Drive 环境。** 在未部署 Drive 存储的环境中，所有操作将返回 `403 feature_disabled`，工具会提示：“记忆功能依赖于 Files（文件），但该项目未开启 Files。请联系项目管理员开启 Files。”
- **API。** `GET /v1/projects/:id/memory/me/agent/mykortix`（索引），`GET`、`PUT` 和 `DELETE …/pages/:name`。调用方可以是登录的用户本人，或是其 My OpenChatly 会话（使用会话令牌，令牌的 `on_behalf_of` 指向该用户）。任何其他会话令牌都会收到 `403 my_kortix_only`。数据结构定义在 `@kortix/api-contract/memory` 中的 `MyKortixMemory*`。

### 智能体协作（Agents working together）

每个会话都拥有相同的多智能体工具。会话可以将工作交接给指定的智能体、与其他会话通信、带领团队共享任务列表，以及运行工作流。在整个过程中，人工用户始终与当前会话保持对话。

| 目标 | 使用的工具 | 相关章节 |
| --- | --- | --- |
| 在后台将工作交接给另一个智能体 | `agent`（别名 `task`）、`task_stop` | [Work in the background（后台工作）](#后台工作work-in-the-background)、[Named agents and forks（命名智能体与分支）](#命名智能体与分支named-agents-and-forks) |
| 为单一任务定制子智能体 | 带有 `model`、`tools` 或内联 `agent` 规范的 `agent` | [Custom subagents（自定义子智能体）](#自定义子智能体custom-subagents) |
| 从一个脚本运行多个智能体 | `workflow` | [Workflows（工作流）](#工作流workflows) |
| 在结果到达时唤醒会话 | loops（循环）和 triggers（触发器） | [Follow-through（跟进：在结果到达时唤醒）](#跟进在结果到达时唤醒follow-through-wake-on-the-result) |
| 与另一个会话通信 | `send_message`、`list_agents` | [Messages between sessions（会话间消息）](#会话间消息messages-between-sessions) |
| 在团队成员间共享任务列表 | `task_create`、`task_list`、`task_get`、`task_update` | [Agent teams（智能体团队）](#智能体团队agent-teams) |
| 按状态查看所有会话 | 智能体看板（agent board） | [Agent board（智能体看板）](#智能体看板agent-board) |

#### 后台工作（Work in the background）

由人工用户发起的会话充当编排器（orchestrator）：该会话启动的任何任务都不会阻塞会话本身。

- **工作交接（Hand-offs）。** 在深度为 0 的会话中，使用 `session: "separate"` 参数调用 `agent` 默认在后台运行（此时 `run_in_background` 默认为 `true`）。该调用会立即返回子任务的 `task_id`。而在深度为 1 或更深的子会话中，以及工作流脚本中的每个 `agent()`，默认都会等待其结果。
- **工作流（Workflows）。** `workflow` 工具始终在后台运行，并在一个专用的运行器会话（runner session）中执行。请参阅 [Workflow controls（工作流控制）](#工作流控制workflow-controls)。
- **团队（Teams）。** 团队成员是后台运行的子任务。每个成员在其对话轮次结束时，都会向其主导者（lead）发送空闲通知。
- **结果以消息形式到达。** 当后台子任务、工作流运行器或团队成员完成时，API 会向调用方会话发送一条消息。如果会话处于空闲状态，该消息会触发一个新的对话轮次。如果多个任务同时完成，它们会在同一个轮次中一起到达。
- **人工用户保持对话。** 在子任务工作期间，输入框（composer）保持可用状态。人工用户发送的消息会被立即响应，而任务完成的通知则在对话轮次之间到达。
- **无需等待即可获取状态。** `list_agents` 和 `kortix sessions status` 可以读取每个子任务的状态。两者都不会等待子任务完成。

#### 工作流（Workflows）

`workflow` 工具用于运行一段 JavaScript 脚本，该脚本负责启动和协调多个智能体。脚本中包含执行计划和中间结果。模型仅接收脚本的返回值。每个会话都拥有此工具。它只能由人工用户自己的消息触发启动：如果对话轮次是由其他会话的消息、房间消息、触发器或提醒发起的，则会拒绝启动工作流。

该工具的调用参数包括 `script`（必填）、`description`、`args`、`max_agents`、`resume_run_id`、`fresh` 和 `name`。如果要通过 `name` 运行已保存的工作流，或者使用其自带脚本恢复某次运行，调用时需传递 `script: ""`（空字符串）。

```js
export const meta = {
  name: 'audit-routes',
  description: 'Audit route handlers for missing auth',
  phases: [{ title: 'Find' }, { title: 'Audit' }],
}

phase('Find')
const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

phase('Audit')
const audits = await pipeline(found.files, (file) =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }))

return audits.filter(Boolean)
```

- **格式（Format）。** 可选的首条语句 `export const meta = { name, description, phases }` 必须是纯字面量：不允许使用变量、函数调用或展开运算符（spread）。在 `phase(title)` 启动每个阶段之前，卡片上会将这些阶段列为“待处理（pending）”。脚本主体是支持顶层 `await` 的纯 JavaScript。它没有 `fetch`，不能访问文件，没有定时器，也不能使用 `Date.now()` 和 `Math.random()`。
- **脚本 API（Script API）。** `agent(prompt, opts)` 会在独立会话中启动一个智能体，并解析（resolve）为其最终答案。选项包括 `label`、`phase`、`agent`（项目智能体的名称）、`model`、`instructions`、`tools`、`schema`、`strict` 和 `stallMs`。
- **扇出与并发（Fan-out）。** `parallel([() => …])` 可同时运行多个函数。`pipeline(items, stage1, stage2, …)` 会将每个项目依次通过各个阶段处理。`log(text)` 用于显示进度行，`args` 则是调用时传入的 `args` 值。
- **自定义智能体（Custom agents）。** `model`（`provider/model` 引用）允许在另一个模型上运行智能体（包括命名智能体）。如果指定了 `instructions` 但未指定 `agent`，则会为该智能体提供专属的系统提示词：相当于为此次调用创建一个内联智能体。`tools` 将智能体限制为仅能使用列出的工具。列出的每个工具都必须是调用方会话拥有的，因此子智能体永远不会获得比调用方更多的权限；对于命名智能体，它仅保留其自身定义也允许使用的工具。只有当提示词及所有这些选项都未改变时，恢复操作（resume）才会重用智能体。`agent` 工具接受相同的选项。请参阅 [Custom subagents（自定义子智能体）](#自定义子智能体custom-subagents)。
- **失败处理（Failures）。** 当智能体会话被停止时，`agent()` 会解析为 `null`。如果智能体执行失败，则会抛出异常。如果直接 `await`，错误将终止整个运行。如果在 `parallel()` 或 `pipeline()` 内部，失败的智能体会变为 `null`，运行将继续。
- **审批（Approval）。** 在第一个智能体启动之前，人工用户会看到标题、阶段和智能体数量，并提供 **Run it（运行）**、**Run it, and don't ask again in this session（运行且本次会话不再询问）** 和 **Cancel（取消）** 选项。数量上限由调用的 `max_agents` 决定，运行会拒绝超过该限制的 `agent()` 调用。子会话（例如后台运行器）不会触发审批询问。
- **结构化输出（Structured output）。** 使用 `schema`（JSON Schema）时，智能体必须返回匹配的 JSON，且 `agent()` 会解析该值。如果回答错误，会在同一会话中进行纠正，最多尝试 5 次。如果最后一次回答仍不匹配，`agent()` 会解析为 `{ schema_error, text }`（包含原因和最后一次回答），运行继续；恢复操作（resume）会重新询问该智能体。如果设置 `strict: true`，`agent()` 会直接抛出异常。OpenChatly 会校验关键字：`type`、`properties`、`required`、`additionalProperties`、`items`、`enum`、`const`、`minItems`、`maxItems`、`minLength`、`maxLength`、`minimum` 和 `maximum`。如果 Schema 存在自相矛盾（例如 `required` 中的键被 `additionalProperties: false` 排除），调用会在智能体启动前被阻止。
- **后台执行（Background）。** 每个工作流都在后台运行。调用会在几秒内启动一个运行器会话并返回，因此调用轮次结束，人工用户可以继续对话。运行器在其首条消息中接收脚本（脚本、参数和记录最多 200,000 个字符），运行脚本，并保持自身计算环境处于唤醒状态。一个运行器仅运行那一个工作流。其结果会作为新消息传递到调用方会话中，从而触发一个新的轮次。
- **停止运行（Stopping a run）。** 停止调用轮次、发送新消息、停止或重启调用会话都不会停止工作流运行。只有通过卡片的 **Stop（停止）** 按钮、控制路由（control route）或对运行器会话执行 `task_stop` 才能停止。如果工作流未完成，运行器会以错误结束其轮次，因此通知会说明其失败及原因。
- **内联回退（Inline fallback）。** 后台运行需要在调用方之下再有两层会话：一层用于运行器，一层用于其智能体。如果会话不具备这些层级（例如处于深度上限下一层的子会话，或没有 OpenChatly 控制平面的沙盒），脚本将以内联方式运行，结果中会注明这一点。
- **恢复运行（Resume）。** 每个结果都会命名一个 `run_id`。当会话的最新一次运行被停止、失败或中断时，下一次 `workflow` 调用会自动使用新脚本（无论是否编辑过，`script: ""` 会运行其自带脚本）恢复该运行。`resume_run_id` 会以相同方式恢复指定的运行，而 `fresh: true` 则会启动全新运行。在任何顺序下，只要 `agent()` 调用的提示词、智能体、模型和 Schema 相同，就会直接返回其保存的结果，而不会创建新会话。其他所有调用都会正常执行。恢复操作会保留 `run_id` 并启动新的运行器会话，其首条消息会携带已完成智能体的保存结果（超过 200,000 个字符的结果会重新运行）；调用同样会立即返回。如果原运行器仍在工作，则会拒绝恢复请求。
- **保存的工作流（Saved workflows）。** 保存的工作流是项目仓库中的 `.kortix/workflows/<name>.js` 文件。通过 `name` 和 `args` 即可运行。拥有项目检出（checkout）的会话会读取其工作树，工具描述中会列出已保存的名称。My OpenChatly 没有检出：它会从项目的默认分支读取文件。该工具不会自动保存工作流。如需保存，由人工用户提出请求，拥有仓库访问权限的智能体会写入 `.kortix/workflows/<name>.js` 并发起变更请求（change request）。
- **停滞处理（Stalls）。** 如果智能体在 `stallMs`（默认 15 分钟）内没有新输出，将会停止，并使用相同的提示词启动新会话。仍在运行的工具调用被视为有效输出。在尝试 6 次后，`agent()` 会抛出 `agent stalled on all 6 attempts` 异常。
- **限制（Limits）。** 一次运行最多启动 50 个智能体（`KORTIX_WORKFLOW_MAX_AGENTS`），且最多同时运行 8 个（`KORTIX_WORKFLOW_MAX_CONCURRENT`）。会话的子智能体限制同样适用（`KORTIX_PI_CLOUD_SUBAGENTS_MAX`，默认为 4）：以较低的限制为准。一次 `parallel()` 或 `pipeline()` 调用最多处理 4,096 个项目。运行在 2 小时后结束。如果运行包含超过 25 个智能体，卡片会将其标记为大型运行。

#### 工作流控制（Workflow controls）

人工用户可以通过工作流卡片控制正在运行的工作流。卡片会调用运行该工作流的沙盒：即会话本身或其后台运行器。

| 控制操作 | 功能描述 |
| --- | --- |
| **Pause（暂停）** | 不启动新的 `agent()`。正在运行的智能体会完成其工作。 |
| **Resume（恢复）** | 重新开始启动新的 `agent()` 调用。 |
| **Restart（重启）**（针对单个智能体） | 停止该智能体的会话，并使用相同的提示词重新启动。 |
| **Stop（停止）** | 停止所有智能体并结束运行。被停止智能体的 `agent()` 调用会解析为 `null`。 |
| **Save（保存）** | 通过变更请求将运行脚本保存为 `.kortix/workflows/<name>.js`，以便后续通过 `name` 再次运行。 |

- **控制路由（Routes）。** 向 `POST /kortix/runtime/workflows/:runId/control` 发送 `{ action: "pause" | "resume" | "restart_agent" | "stop", session_id? }` 会返回 `200 { ok: true, paused }`，未知运行返回 `404`。`restart_agent` 需要 `session_id`（智能体的子会话）。`GET /kortix/runtime/workflows` 会返回 `200 { runs }`，即该会话的运行记录，按最新优先排序。契约为 `@kortix/api-contract/multi-agent` 中的 `WorkflowControlBody`。
- **大型工作流（Large workflow）。** 包含超过 25 个智能体的运行会在卡片上显示 **Large workflow（大型工作流）** 标签。该标签不会暂停或限制运行。
- **ultracode。** 人工用户输入的消息中包含 `ultracode` 一词意味着“将其作为工作流运行”。输入框（composer）会高亮显示该词。随后，My OpenChatly 会编写并启动工作流，而不是逐步执行。该词在触发器、频道或其他会话发起的消息中无效。

#### 跟进：在结果到达时唤醒（Follow-through: wake on the result）

稍后到达的结果必须能够唤醒等待它的会话。每个智能体都会在结束当前轮次前自行设置该唤醒机制，无需被要求：例如在发送邮件或消息、提交订单或表单、发起变更请求（Change Request）、启动部署、向人工用户提问或开始监控某个页面之后。该规则存在于 My OpenChatly 的系统提示词、托管的 `kortix-system` 技能（`<scheduling>` 章节和 `references/scheduling.md`）以及初始的 `worker` 智能体中。

| 会话等待的内容 | 唤醒方式 | My OpenChatly 工具 (`kortix_schedules`) |
| --- | --- | --- |
| 邮件或消息的回复 | 循环检查（Loop），加上连接器事件（当应用已连接且项目开启了 `event_triggers` 时）。连接器事件为实验性功能，默认关闭；请在 **Project admin** → **Feature flags** 中开启：`kortix triggers add "<text>" --on event --connector <slug> --event <TYPE>` | `follow_up`；`wake_on` 配合 `on: { connector_event }`（`events` 列出事件类型） |
| 变更请求（Change Request） | `kortix triggers add "<text>" --on cr-merged --cr <id>` | `wake_on` 配合 `cr_merged` |
| 部署、CI 运行、后台作业 | `--on webhook --secret-env <NAME>`（会打印出提供给外部系统的 URL），否则每 10 到 30 分钟循环检查一次 | `wake_on` 配合 `webhook`（返回 URL） |
| 人工用户的回答、响应缓慢的供应商 | 循环检查（Loop） | `follow_up` |
| 无事件支持的页面或状态 | 循环检查，或使用监控 App 配合 `--on app --app <slug>` | `wake_on` 配合 `app_event` |
| 工作交接、团队成员、工作流 | 无需额外设置：每个任务都会自行汇报结果 | 无 |

- **回退循环（Fallback loop）。** 当事件可能永远不会发生时，智能体还会设置一个循环。检查频率与等待内容相匹配：对于回复，会在收件人的工作时间首次等待 2 到 4 小时，然后每天检查 2 到 4 次；部署检查为 10 到 30 分钟；响应缓慢的供应商为每天一次。
- **循环文本携带上下文：** 包括发送了什么、发给谁、检查什么、每种结果对应的操作，以及结束日期（默认为 14 天）。循环没有过期时间或退避（backoff）标志：结束日期存在于文本中，智能体在多次空检查后会用频率更低的循环替换原循环。
- **向人工用户说明（一行文字）：** “我将每 3 小时检查一次回复，直到 11 月 14 日，或者直到收到全部 12 封回复。”
- **每次触发（Fire）：** 都会进行检查、执行操作并汇报变化。当条件满足或超过结束日期时，智能体会移除其设置的所有循环和触发器（`kortix loops rm`、`kortix triggers rm`）。
- **能执行检查的会话拥有唤醒权。** 发送邮件的后台子任务会设置自己的循环。该子任务的后续每个轮次（包括循环触发）都会向其父会话发送一条通知，因此 My OpenChatly 能收到每一次检查的结果。
- **会话事件触发器（Session event triggers）** 是目标为当前会话的运行时触发器（`--session`，在会话内为默认值）。来源包括：`cr-merged`、`webhook`、`event`（连接器）、`app`。触发器触发时消息格式为 `[REMINDER trigger.<id> — … trigger (<source>) …]`；循环触发格式为 `[REMINDER reminder.<id> — …]`。两者都不是用户消息。
- **App 事件是 24/7 全天候监控。** App 独立于任何会话运行：`every` 触发器调用它（无会话、无模型），它仅在源数据发生变化时发布 App 事件，会话触发器（`--on app`）或 `kortix.yaml` 触发器会唤醒智能体。基于内容生成的事件 `id` 确保未变化的源不会重复触发：OpenChatly 对每个触发器在 30 天内仅接受一次相同的 `id`。请参阅 [Triggers and App events（触发器与 App 事件）](#触发器与应用事件triggers-and-app-events)。
- **循环功能关闭时。** `403 feature_disabled` 表示项目关闭了 Loops 功能（标志位 `reminders`）。智能体会说明此情况，并在此期间使用一次性的 `at` 触发器作为替代。

**长周期任务：规划、委派、设置唤醒、保持状态、收尾。** 包含多个部分或耗时数天的任务会跨越单个轮次和上下文窗口：当上下文填满时，智能体会在一个全新的上下文中继续，并从会话的完整记录中读取所需信息。以下三个核心来源教授了处理此类任务的标准模式：

1. **规划（Plan）** 并行部分和等待部分。
2. **委派（Delegate）** 使用后台 `agent` 调用（命名智能体，可复用于后续跟进）、用于多智能体的 `workflow`，或用于共享任务列表的团队。它们会自行汇报结果。
3. **设置唤醒（Set wake-ups）** 针对所有外部等待：设置事件触发器，加上带结束日期的回退循环。
4. **在上下文之外保持状态（Keep state outside the context）：** 循环文本（待办、下一步、停止规则）、会话中的状态文件 `out/status.md`（已完成、待办、下次检查、未决问题），或 Goal（`kortix-goals` 技能，用于需独立验证的多日目标）。Goals 为实验性功能，默认关闭；请在 **Project admin** → **Feature flags** 中开启。每个被唤醒的轮次都会首先读取状态、推进进度、更新状态，并重新设置或移除唤醒机制。
5. **在任务重复时配置 OpenChatly：** 设置项目触发器、监控 App，或专用的智能体/技能。对于任何无人值守长期运行、每次运行消耗积分或扩大访问权限的任务，智能体会先征求同意。它会自行设置当前会话的循环而无需询问，并会进行宣告。
6. **收尾（Close out）：** 移除其设置的所有循环和会话触发器，停止不再需要的智能体（`task_stop`），并发送简短的最终报告。

完整的工作示例位于 `kortix-system` 技能的 `references/scheduling.md` → Long jobs（长周期任务）章节中。

#### 命名智能体与分支（Named agents and forks）

- **命名（A name）。** 调用 `agent({ name: "post-writer", … })` 会为子智能体分配一个句柄（handle）。OpenChatly 会将其存储在子智能体的元数据 `agent_handle`（`AGENT_HANDLE_KEY`）中。`send_message` 工具将其作为 `to`（接收方）参数，会话列表会将其显示为 `@post-writer`。仅靠名称本身不会使其成为团队成员；这需要设置 `team: true`（请参阅 [Agent teams（智能体团队）](#智能体团队agent-teams)）。
- **分支（A fork）。** 调用 `agent({ fork: true, … })` 会使用当前会话对话记录的副本（而非空白记录）来启动子智能体。当子智能体需要迄今为止的所有对话内容时，请使用此选项。普通的子智能体只能看到其专属的提示词。
- **优先复用（Reuse first）。** 建立在先前工作交接基础上的后续任务，应交由同一个子智能体处理：向其名称发送 `send_message`，或使用 `task_id` 调用 `agent`。子智能体会保留其对话记录，且其计算环境已在运行中。仅为独立或并行任务启动新的子智能体。`agent` 和 `send_message` 的工具描述中会向模型说明此规则。
- **继续执行子任务（Continue a child）。** 对已完成的子智能体使用 `task_id` 调用 `agent`，会在其同一会话中发送后续指令。对已完成的子智能体（处于空闲、已完成或已停止状态）使用 `name` 调用 `agent` 也会产生相同效果：不会启动新会话，且结果会提示 `This continued your earlier subagent "<name>" in its same session`（工具元数据 `continued: true`）。如果名称对应的子智能体仍在工作，或正在等待人工用户操作，则该请求会被拒绝。失败的子智能体会释放其名称。向已完成的子智能体发送消息会在其同一会话中将其唤醒，随后后台子智能体或团队成员会自行发送下一份报告。
- **停止子任务（Stop a child）。** 使用子智能体的 `task_id` 或名称调用 `task_stop` 会停止其会话。
- **深度限制（Depth）。** 独立的子智能体最多可向下启动至深度 2 的独立子智能体（`KORTIX_PI_CLOUD_SUBAGENTS_MAX_DEPTH`）。一个会话最多同时运行 4 个独立子智能体（`KORTIX_PI_CLOUD_SUBAGENTS_MAX`）。

#### 自定义子智能体（Custom subagents）

会话在调用时为每个子智能体量身定制其任务配置。任何配置都不会保存到项目中。

| 调用方式 | 选项 |
| --- | --- |
| `agent` 工具 | `subagent_type`：项目智能体的名称。或者 `agent: { instructions, model?, tools?, description? }`：仅针对此次调用的内联智能体；此时 `subagent_type` 会被忽略。顶层的 `model` 参数可在其他模型上运行命名智能体。 |
| 工作流 `agent(prompt, opts)` | `agent`（项目智能体的名称）、`instructions`、`model`、`tools` 和 `schema`，以及 `label`、`phase`、`strict` 和 `stallMs`。请参阅 [Workflows（工作流）](#工作流workflows)。 |

- **模型（Model）。** 格式为 `provider/model` 引用。网关模型为 `kortix/<id>`；Claude 订阅模型为 `claude-agent/<id>`。My OpenChatly 使用 `kortix_agents` 的 `models` 操作列出项目模型：每行包含确切的 `id`、名称、`fast`（基于模型名称判断）、`reasoning` 和 `images`（如适用）以及上下文大小。其他智能体通过 `kortix models ls --json` 按线路 ID（wire id）读取相同的目录：在网关 ID 前加上 `kortix/` 前缀。如果未指定 `model`，子智能体将使用其所属智能体的模型，否则使用调用方的模型。对于批量和并行工作，请使用快速模型；对于综合分析和判断，请使用最强的推理模型。
- **工具（Tools）。** `tools` 是一个工具名称列表。子智能体仅保留其所属智能体拥有的名称：缺失的名称会被丢弃，绝不会新增。当调用方自身的工具被限制时，子智能体也仅能获得调用方拥有的名称（`childToolAllowlist`）。如果未指定 `tools`：子智能体保留其所属智能体的工具，若调用方工具受限，则在其范围内保留。只读研究员的配置示例为 `["read", "grep", "glob"]`，不包含 `edit`、`write` 或 `bash`。
- **扩展（Extensions）。** 内联规范没有扩展选项。子智能体拥有其所属智能体授权（grant）赋予的扩展。
- **新增工具或扩展** 属于对项目文件的修改：即 `tools/<name>.ts`，或 `extensions/<name>.ts`，或固定的 npm 包，需在 `kortix.yaml` 中注册（请参阅 [tools entries（工具条目）](#tools-条目tools-entries) 和 [extensions entries（扩展条目）](#extensions-条目extensions-entries)）。拥有仓库访问权限的智能体会写入该文件并发起变更请求。合并后，授权列表中包含该工具/扩展的每个智能体均可使用。My OpenChatly 没有检出（checkout）环境：它会将此工作交接给此类智能体。

#### 会话间消息（Messages between sessions）

`send_message` 用于将文本从项目中的一个会话发送到另一个会话。`list_agents` 用于列出当前会话可以触达的会话。消息传递功能在每个项目中默认开启，无需配置功能标志（feature flag）。提供这些工具的运行时环境会在 `GET /kortix/health` 的 `capabilities`（能力）列表中声明 `session.messaging`。

- **`to`（接收方）。** 可以是智能体句柄（agent handle）、会话 ID、至少 8 个字符的唯一前缀、`parent`（与 `main` 相同），或 `@name`。当 `to` 匹配到多个会话时，调用会返回 `409 ambiguous_recipient`，并附带 `candidates`（候选列表）。
- **输入参数（Input）。** `{ to, message, summary?, notify_when_idle?, type?, approve?, project_id? }`（即 `PeerMessageSendBody`）。`summary` 是单行预览。`project_id` 用于解析其他项目中的 `to`。
- **传递机制（Delivery）。** 接收方在其轮次（turn）的下一步骤中读取消息。如果接收方处于空闲状态，该消息会触发一个新的轮次。消息文本以类似 `[message from reviewer · session 3f2a1b9c · #m_7Kq2]` 的标头开头，并以注明其来自其他会话的说明结尾。`@kortix/shared` 中的 `peerMessagePromptText` 和 `parsePeerMessagePrompt` 负责写入和读取该文本。Web 应用会将其显示为一行 **Message from @reviewer**，而不是人工用户输入的轮次。
- **无授权效力（No authority）。** 来自其他会话的消息仅代表请求，绝不等同于授权。它不能回答权限提示词或向人工用户提问，也不能更改设置。
- **发送权限（Who may send）。** 只有当某个人工用户有权向某个会话发送提示词时，该用户所在的会话才能向该会话发送消息。拒绝操作会返回明确的结果，绝不会静默丢弃消息。
- **结果状态（Results）。** `delivered`（已送达）、`held`（等待接收方的人工用户处理）、`refused`（接收方拒绝消息，或发送方无权向其发送）、`denied`（人工用户拒绝了被挂起的消息）、`expired`（挂起的消息在 5 分钟内无人审批）、`dropped`（60 秒内向同一会话发送了相同的文本）。每个结果都会附带一个 `note`（备注），例如 `Not sent: reviewer refuses messages.`（未发送：审核者拒绝接收消息）。
- **空闲通知（Idle notice）。** 设置 `notify_when_idle: true` 会在接收方轮次结束时向发送方发回一条通知。如果接收方已处于空闲状态，通知会立即送达。该监听机制在 12 小时后失效。
- **`list_agents`。** `scope: "mine"`（默认）列出父会话、子会话、主导者（lead）和团队成员。`scope: "project"` 列出项目中的每个活跃会话。查询其他项目需要显式指定 `project_id`。每一行（`ReachableAgent`）包含 `handle`、`session_id`、`short_id`、`relation`（`self`、`parent`、`child`、`lead`、`teammate`、`session`）、`state`、`inbound` 和 `can_receive`。

**入站策略（Inbound）。** 每个会话自行决定如何处理来自其他会话的消息。默认策略为 `accept`。

| 模式 | 行为描述 |
| --- | --- |
| `accept`（接受） | 消息正常送达。 |
| `hold`（挂起） | 消息处于等待状态，直到该会话的人工用户选择 **Approve**（批准）或 **Deny**（拒绝）。5 分钟后过期。一个会话最多挂起 100 条消息。 |
| `refuse`（拒绝） | 消息不予发送。发送方会读取到 `Not sent`（未发送）。 |

**限制（Limits）。** 每条消息最多 16,000 个字符（`PEER_MESSAGE_MAX_CHARS`），`summary` 最多 200 个字符，每个发送方会话每分钟最多发送 30 条消息（`PEER_MESSAGE_PER_MINUTE`）。


| 路由 (Route) | 请求体 (Body) | 响应 (Answer) |
| --- | --- | --- |
| `GET /projects/:id/sessions/:sid/reachable?scope=mine\|project` | 无 | `200 ReachableAgents` |
| `POST /projects/:id/sessions/:sid/peer-messages` (`:sid` = 发送方) | `PeerMessageSendBody` | `200 PeerMessageSendResult`；`409` 接收方 `to` 存在歧义 |
| `GET /projects/:id/sessions/:sid/peer-messages?direction=in\|out` | 无 | `200 { messages }` |
| `POST /projects/:id/sessions/:sid/peer-messages/:mid/approve` (`:sid` = 接收方) | 无 | `200 PeerMessage` |
| `POST /projects/:id/sessions/:sid/peer-messages/:mid/deny` | 无 | `200 PeerMessage` |
| `PUT /projects/:id/sessions/:sid/inbound` | `{ inbound }` | `200 { inbound }` |

该接口的契约（contract）定义在 `@kortix/api-contract/multi-agent` 中。在终端中执行：

```bash
kortix sessions reachable --scope project
kortix sessions message reviewer "The schema change landed; rebase is safe." --notify-idle
kortix sessions inbound 3f2a1b9c hold
kortix sessions inbound 3f2a1b9c approve m_7Kq2
```

在会话内部，CLI 会以 `$KORTIX_SESSION_ID` 环境变量发送身份标识。在会话外部，请传递 `--from <session>` 参数。

#### 智能体团队（Agent teams）

智能体团队由一个主导会话（lead session）及其启动的团队成员（teammates）组成。它们共享一个任务列表，并通过名称相互发送消息。智能体团队功能目前为实验性功能，默认处于关闭状态。请在 **Project admin** → **Feature flags** 中开启，或使用命令 `kortix projects features enable agent_teams`。提供任务工具的运行时环境会在 `GET /kortix/health` 的 `capabilities`（能力）列表中声明 `session.team_tasks`。

- **团队成员（Teammates）。** 开启该功能标志后，主导者调用 `agent({ name, team: true })` 会启动一个团队成员：这是一个子会话，其元数据 `team_lead`（`TEAM_LEAD_KEY`）指向主导者，且 `agent_handle` 为其名称。如果仅指定 `name` 而不带 `team`，则会创建一个普通的命名子会话（同样需要开启该功能标志）。如果未开启标志、未指定名称、使用了 `fork` 参数，或在深度为 1 及更深的会话中调用 `team: true`，将会失败并返回具体原因。`GET /projects/:id/sessions?team_lead=<sid>` 可列出某个主导者的团队成员。团队成员不能启动自己的团队成员。
- **角色绑定会话。** 团队成员运行的是现有的智能体：通过 `subagent_type` 指定的项目智能体，或默认智能体。其名称和提示词中的角色仅作为该子会话的上下文（`initial_context` 和提示词）。`kortix.yaml` 中的任何内容都不会改变，团队也不会被保存：团队的生命周期依附于其主导会话。
- **任务列表（The task list）。** `task_create`、`task_list`、`task_get` 和 `task_update` 用于读取和修改主导者的任务列表。一个任务包含编号（`seq`，显示为 `#3`）、`subject`（主题）、`description`（描述）、`status`（状态：`pending` 待处理、`in_progress` 进行中、`completed` 已完成）、`owner`（所有者）以及 `blocked_by`（阻塞项：该任务需要等待的其他任务编号）。只要 `blocked_by` 中的任务尚未全部完成，`blocked` 状态就会保持为 `true`。
- **认领任务（Claim）。** 团队成员通过 `task_update({ claim: true })` 获取下一个待处理、无所有者且未被阻塞的任务。认领操作是原子性的：竞争失败的请求会收到 `409 task_taken`，而认领被阻塞的任务会收到 `409 task_blocked`。主导者可以通过 `owner` 字段直接分配任务。
- **空闲通知（Idle notices）。** 当团队成员的轮次结束时，主导者会收到一条包含该成员最终答复的通知。主导者会将这些答复汇总后呈现给人工用户。
- **关闭会话（Shutdown）。** 主导者发送 `send_message({ to: "<teammate>", type: "shutdown_request" })`。团队成员会以 `type: "shutdown_response"` 及 `approve: true`（表示同意，其会话将停止）或 `approve: false` 及具体原因进行回复。

| 路由 (Route) | 请求体 (Body) | 响应 (Answer) |
| --- | --- | --- |
| `GET /projects/:id/sessions/:lead/tasks` | 无 | `200 { tasks }` |
| `POST /projects/:id/sessions/:lead/tasks` | `SessionTaskCreateBody` | `201 SessionTask` |
| `PATCH /projects/:id/sessions/:lead/tasks/:seq` | `SessionTaskUpdateBody` | `200 SessionTask`；`409 { code: "task_taken" \| "task_blocked" }` |
| `DELETE /projects/:id/sessions/:lead/tasks/:seq` | 无 | `200 { deleted: true }` |

```bash
kortix tasks add "Draft the outline" --owner writer
kortix tasks add "Review the draft" --blocked-by 1
kortix tasks claim 2          # exit 3 when another session took it first
kortix tasks 3f2a1b9c ls      # a lead's list from outside the team
```

#### 智能体看板（Agent board）

`/projects/<id>/sessions?view=board` 会以看板形式展示项目的所有会话，并按状态进行分组。在 **Sessions（会话）** 页面中，将 **Layout（布局）** 设置为 **Board（看板）**。点击卡片即可打开对应的会话。

| 状态 (`board_state`) | 含义 |
| --- | --- |
| `working`（工作中） | 正在运行一个对话轮次（turn）。 |
| `needs_input`（需要输入） | 会话正在等待人工用户操作：`attention`（关注点）为 `question`（提问）或 `approval`（审批）。 |
| `idle`（空闲） | 对话轮次已结束；会话正在等待接收新消息。 |
| `completed`（已完成） | 工作已完成。 |
| `failed`（失败） | 会话执行失败。 |
| `stopped`（已停止） | 会话已被停止。 |

API 返回的每个会话行都包含看板的字段：`board_state`、`attention`（`question`、`approval` 或 `null`）、`last_activity_at`（最后活动时间）、`result_excerpt`（最后答复的摘要，最多 280 个字符）、`agent_handle`（智能体句柄）、`team_lead_session_id`（团队主导会话 ID）和 `inbound`（入站策略）。`kortix sessions status --json` 命令会打印每个会话的 `board_state`、`attention`、`agent_handle` 和 `team_lead_session_id`。

#### 通过 SDK 访问（From the SDK）

SDK 暴露了相同的接口，且作用域限定在会话级别。请参阅 [SDK reference（SDK 参考）](#sdk-参考sdk-reference)。

```ts
const s = kortix.session(projectId, sessionId);
await s.reachable({ scope: 'project' });
await s.peerMessages.send({ to: 'reviewer', message: 'The schema change landed.', notify_when_idle: true });
await s.setInbound('hold');
await s.tasks.create({ subject: 'Review the draft', blocked_by: [1] });
await s.workflows.control(runId, { action: 'pause' });
```

React: `useReachableAgents`, `usePeerMessages`, `useTeamTasks`, `useSessionWorkflows` and `useTeammates` in `@kortix/sdk/react`.

### 生成图像（Generate images）

`image_gen` 工具可根据提示词（prompts）生成 1 到 4 张图像，或编辑工作区中现有的图像。每张生成的图像都会保存在 `/workspace/output/images/` 目录下。该工具使用项目可访问的图像模型：例如已连接的 ChatGPT 计划中的 `gpt-image-2`，OpenAI、Google、xAI 或 OpenRouter 密钥对应的图像模型，或者你自定义命名的端点模型。OpenChatly 官方托管的模型阵容中没有图像模型。

- **单次调用，1 到 4 张图像。** 每个提示词对应一张图像。工具会为每个提示词发送一个请求，且这些请求会同时并发执行。
- **需要图像模型。** 请在 **Customize** → **Models** 中连接 ChatGPT（**Connect ChatGPT**），或使用 `kortix providers login openai` 命令连接；也可以添加 OpenAI、Google、xAI 或 OpenRouter 的密钥。请参阅 [Models（模型）](/docs/zh/guide#模型models)。如果未配置，调用将失败并返回 `image_model_unavailable`。
- **输出为路径，而非图像本身。** 模型接收到的数据结构为 `{ action, model, provider, images: [{ path, size, prompt, sha256 }], failed: [{ prompt, error }] }`。`model` 和 `provider` 标识了生成第一张保存图像的模型和提供商。`size` 格式为 `WxH`，优先从保存文件的头部读取；若无法读取，则使用提供商报告的尺寸。`sha256` 是保存文件字节的小写十六进制 SHA-256 哈希值。仅当提示词失败时才会出现 `failed` 字段。如果所有提示词均失败，调用将以第一个错误信息终止。

| 参数 (Argument) | 值/说明 (Value) |
| --- | --- |
| `action` | `generate`（生成新图像）或 `edit`（编辑参考图像）。必填。 |
| `prompts` | 1 到 4 个非空字符串，每个字符串对应一张图像：描述图像内容或需要修改的内容。必填。 |
| `model` | 图像模型 ID，例如 `codex/gpt-image-2`、`openai/gpt-image-1`、`google/gemini-2.5-flash-image` 或 `openrouter/google/gemini-2.5-flash-image`。省略则使用 `auto`。请参阅 [Which model makes the image（哪个模型生成图像）](#哪个模型生成图像)。 |
| `aspect_ratio` | `auto`（默认）、`1:1`、`3:2`、`2:3`、`16:9`、`9:16`、`4:3` 或 `3:4`。 |
| `quality` | `auto`（默认）、`low`、`medium` 或 `high`。 |
| `transparent_background` | 设为 `true` 则生成透明背景。默认为 `false`。 |
| `reference_images` | 仅用于 `edit` 操作且为必填：1 到 5 个工作区内的 png、jpg、jpeg 或 webp 文件路径。每个提示词都会使用这些参考图。 |

- `quality` 和 `transparent_background` 参数仅对 ChatGPT 和 OpenAI 模型有效。其他模型不会接收这些参数。
- ChatGPT 和 OpenAI 模型接收的是尺寸（size）而非比例（ratio）。`auto` 对应 `auto`；`1:1` 对应 `1024x1024`；`3:2`、`4:3` 和 `16:9` 对应 `1536x1024`；`2:3`、`3:4` 和 `9:16` 对应 `1024x1536`。xAI 模型不接收宽高比参数。其他模型会按原样接收比例参数，`auto` 时不接收比例参数。
- 文件名由提示词的 slug（短标识符）加上时间戳组成。扩展名根据图像字节内容确定：`.png`、`.jpg` 或 `.webp`。任何其他格式的响应（例如 SVG）都不会被写入。

#### 聊天中的图像卡片（The image card in the chat）

一次调用会显示一张卡片，每个提示词对应一个画面框（frame）。

- 调用运行期间，卡片会为每张图像显示一个符合请求比例的占位符，并带有 "Generating image"（或 "Generating 3 images"；编辑时为 "Editing image"）以及已用时间。调用结束后，占位符会被实际图像替换。
- 单张图像会填满消息的宽度。2 到 4 张图像会填满一个矩形区域：2 张并排显示，3 张为一大两小布局，4 张为 2×2 网格。在 Web 端，卡片高度最大为窗口高度的 60%。
- 卡片上不显示提示词和模型名称。点击图像可全屏查看（无裁剪）。全屏视图会显示生成该图像的提示词和模型。
- 如果某个提示词失败，对应的画面框会显示错误信息。如果原因是连接缺失或过期，卡片会显示一个连接操作按钮。在共享或只读视图中不显示任何操作按钮。

#### 图像限制（Image limits）

该工具在代码层面强制执行以下限制。智能体读取的提示词、文件或网页均无法提高这些限制。

| 限制项 (Limit) | 值 (Value) |
| --- | --- |
| 每次调用的图像数 | 4 张。 |
| 每轮对话的图像数 | 10 张。如果某次调用会导致总数超过 10 张，该调用将在发出任何请求前被整体拒绝：`Image limit for this turn reached (10 images; 8 used, 3 asked).`（已达到本轮图像限制：10 张；已用 8 张，请求 3 张）。 |
| 每个会话的图像数 | 50 张，在单次沙盒运行内计算。沙盒重启会重置计数。 |
| 每次编辑的参考图像数 | 5 张。 |
| 单张参考图像大小 | 20 MiB。 |
| 单次编辑的所有参考图像总大小 | 50 MiB。 |
| 单次调用超时时间 | 300 秒。 |

- 同一轮对话中的所有调用都计入相同的 10 张限额：包括直接调用、并行调用、`codemode` 脚本中的调用、重试调用，以及该轮次启动的子智能体调用。
- 参考图像必须位于解析符号链接后的 `/workspace` 目录内。其内容必须与扩展名匹配。任何不符合要求的文件在请求离开沙盒前都会被拒绝。
- 图像始终保存在 `/workspace/output/images/` 目录下。现有文件永远不会被覆盖：工具会在文件名后追加 `-2`、`-3` 等后缀。
- 当对话轮次停止时，请求也会随之停止，且不会再写入任何文件。

#### 图像错误（Image errors）

当网关拒绝提示词时，错误格式为 `Image generation failed (<status>): <message> <suggestion> [<code>]`。如果是速率限制，会在代码前添加 `Retry after <n> s.`（`<n>` 秒后重试）。当网关指明失败的提供商时，`[provider:<id>]` 会紧跟在代码之前，例如 `[provider:openai] [provider_reauth_required]`。`openai-codex` 代表 ChatGPT。工具自身也会报告三种失败情况：`Image generation returned no image.`（图像生成未返回图像）、返回的图像不是 png、jpeg 或 webp 格式，以及工具自身的 300 秒超时。工具的超时早于网关超时，因此慢请求通常以工具超时结束，而不是 `image_timeout`。

| 错误代码 (Code) | 原因 (Cause) |
| --- | --- |
| `image_model_unavailable` | 项目无法访问任何图像模型。 |
| `not_an_image_model` | `model` 指定的模型无法生成图像。建议信息中最多会列出 5 个项目可用的图像模型。 |
| `image_model_unsupported` | OpenChatly 无法调用该模型的提供商进行图像生成，例如 Anthropic 或 Bedrock。 |
| `provider_not_connected` | `model` 指定的提供商没有配置密钥或 ChatGPT 账户。 |
| `provider_reauth_required` | ChatGPT 登录已过期，或提供商拒绝了该密钥。请重新连接 ChatGPT 或检查密钥。 |
| `image_rate_limited` | 已达到提供商的图像生成限制。错误信息会提供重置前的剩余秒数。 |
| `image_upstream_error` | 提供商失败或未返回图像，例如在安全拒绝之后。 |
| `image_upstream_unreachable` | 无法连接到提供商。 |
| `image_response_too_large` | 提供商返回的响应超过 48 MiB。 |
| `image_timeout` | 网关在 300 秒后停止了请求。 |

#### 关闭图像生成功能

可以通过智能体的 `tools` 映射（map）为某个智能体单独关闭 `image_gen` 工具，或者通过权限规则（permission rule）来禁用它：

```yaml
agents:
  worker:
    tools:
      image_gen: false        # 模型看不到该工具（工具被隐藏）
  researcher:
    permission:
      image_gen: deny         # 模型能看到该工具，但每次调用都会被拒绝
```

- 设置 `image_gen: ask` 可在每次调用时进行审批。
- 由于 `image_gen` 会写入文件，因此 `edit: deny` 也会拒绝该操作，除非智能体为 `image_gen` 单独设置了规则。项目的内置 `memory` 工具同样适用此规则。

#### 替换图像工具

将 `image_gen` 映射到你自己的模块。该模块将替换 OpenChatly 的内置工具：

```yaml
tools:
  image_gen: tools/image_gen.ts
```

执行 `kortix tools eject image_gen` 会将 OpenChatly 的源代码写入 `tools/image_gen.ts` 并配置该行。请务必保留输出格式 `{ action, model, provider, images: [{ path, size, prompt, sha256 }], failed }`，否则聊天界面会显示原始输出而不是图像卡片。`sha256` 为可选字段。

#### 哪个模型生成图像

`image_gen` 工具和网关的 `/v1/images/*` 端点每次请求仅使用一个图像模型。当 `model` 设置为 `auto` 或留空时，网关会按以下顺序尝试请求可访问的所有图像模型。遇到任何错误都会将请求转交给下一个模型。超时或请求被终止则会结束该流程。

1. `codex/gpt-image-2`（当已连接 ChatGPT 账户时）。
2. 按以下顺序，每个已连接的提供商提供一个模型。每个提供商使用模型目录中列为图像模型的第一个 ID：
   - OpenAI 密钥：`gpt-image-1.5`、`gpt-image-1`、`gpt-image-1-mini`。
   - Google 密钥：`gemini-2.5-flash-image`、`gemini-3.1-flash-image`。
   - OpenRouter 密钥：`google/gemini-2.5-flash-image`、`google/gemini-3.1-flash-image`。
   - xAI 密钥：`grok-imagine-image`。

- 被禁用的提供商或模型会被跳过。
- 指定的模型必须是模型目录中列出的支持图像输出的模型。其他任何模型都会返回 `not_an_image_model`，并附带最多 5 个项目可用的图像模型建议。指定的模型没有回退（fallback）机制。
- 目录中有两种支持图像输出的模型不计入此列：Google Deep Research 智能体（`deep-research-*`）以及每次请求动态选择模型的路由器（ID 最后一段为 `auto`，例如 `openrouter/openrouter/auto`）。
- OpenChatly 托管的模型在 `auto` 顺序中排在最后，且它们都不支持图像输出。
- 自定义端点的模型仅在明确指定名称时才会被尝试（例如 `my-vllm/flux-dev`）。`auto` 永远不会自动选择它。该模型必须存在于端点的模型列表中；如果缺失，将返回 `model_not_found` 错误。当端点在 `/chat/completions` 的响应中以 `data:` URL 格式在 `choices[0].message.images[0].image_url.url` 中返回图像时，该机制生效。否则，调用将失败并返回 `image_upstream_error`：即端点自身的错误，或 `<model> returned no image.`（模型未返回图像）。
- 路由策略和 [回退模型](/docs/zh/guide#回退模型fallback-models) 不适用于图像生成。
- OpenChatly 会根据模型所属提供商的协议进行调用：ChatGPT、OpenAI 和 xAI 使用 OpenAI Images API；Google 密钥使用 Gemini `generateContent`；OpenRouter 和自定义端点使用带图像输出的聊天补全（chat completions）。Anthropic 和 Bedrock 模型无法通过 OpenChatly 生成图像。
- **ChatGPT 计划** 拥有独立的图像限制，与计划的聊天限制分开计算。达到图像限制不会导致账户的聊天功能暂停。

#### 图像成本

- **ChatGPT 计划：** OpenChatly 不收取任何费用。生成的图像会消耗该计划的图像配额。
- **自定义端点：** OpenChatly 不收取任何费用。
- **自有密钥：** 由提供商对图像进行计费。OpenChatly 对自有密钥的计费规则与聊天相同：请参阅 [Models（模型）](/docs/zh/guide#模型models)。
- **OpenChatly 仅对成功交付的图像收费。** 被拒绝的请求、未返回图像的响应、超时或被终止的请求均不会产生 OpenChatly 费用，且任何冻结的积分都会被退还。

#### 网关上的图像端点

网关密钥（`kortix_gw_…`）也可以调用图像端点：

| 端点 (Endpoint) | 格式 (Format) |
| --- | --- |
| `POST /v1/images/generations` | 图像生成。 |
| `POST /v1/images/edits` | 图像编辑，支持 1 到 5 张参考图像。 |

两者均接收 `{ model, prompt, aspect_ratio, quality, background, images }` 参数。`model` 默认为 `auto`。`images` 仅用于编辑操作：`[{ "image_url": "data:image/png;base64,..." }]`。网关每次请求仅生成一张图像，并丢弃所有其他字段。如果缺少 `aspect_ratio`，传统的 `size` 参数（`1024x1024`、`1536x1024`、`1024x1536`）会被解析为匹配的比例。所有提供商的响应格式均为 `{ created, model, provider, data: [{ b64_json, mime_type }], size, usage }`。`size` 和 `usage` 仅在提供商提供时存在。

#### 网关上的音频端点

网关密钥（`kortix_gw_…`）也可以调用 OpenAI 音频端点。它们仅在 OpenChatly 托管的音频模型上运行，因此需要包含托管模型的计划。`model` 需指定一个 OpenChatly 托管的音频模型；这些模型不在模型列表或模型选择器中。

| 端点 (Endpoint) | 格式 (Format) |
| --- | --- |
| `POST /v1/audio/transcriptions` | 语音转文字。Multipart 请求体：`file`、`model`，以及可选的 `language`、`prompt`、`temperature`、`response_format`（`json`、`verbose_json` 或 `text`；默认为 `json`）。 |
| `POST /v1/audio/speech` | 文字转语音。参数：`{ model, input, voice, response_format, sample_rate, speed }`：`pcm`（16 位单声道，默认）或 `mp3`，`sample_rate` 范围为 8000 到 48000（默认 24000），`speed` 范围为 0.5 到 1.5。音频在生成时以流式传输。`pcm` 响应会在 `x-sample-rate` 标头中标明采样率。 |
| `GET /v1/audio/voices?model=` | 获取语音模型的可用声音：`{ object: "list", data: [{ id, name, description, languages, tags }] }`。 |

- `json` 或 `verbose_json` 格式的转录结果包含 `usage: { type: "duration", seconds }`：即计费的时长。`text` 格式的转录结果为纯文本。
- 网关仅转发上述字段，并丢弃所有其他字段。
- **成本：** 每次请求按托管上游提供商报告的价格以积分计费，并应用与托管聊天模型相同的加价。被拒绝的请求不收费，且任何冻结的积分都会被退还。语音流在接收到第一段音频时即开始计费，即使客户端中途停止也是如此。声音列表查询是免费的。

## CLI（命令行界面）

`kortix` 是 OpenChatly 的命令行工具。它在终端中实现了与 Web 应用相同的功能：创建和克隆项目、运行会话、审查变更请求，以及配置智能体、连接器和密钥。你可以在本地电脑、CI（持续集成）环境、编码智能体中使用它，也可以在会话沙盒中使用（在沙盒内它已预装并完成登录）。

```sh
curl -fsSL https://kortix.com/install | bash
kortix login
kortix --help
```

### 安装

安装脚本支持 x86_64 和 arm64 架构的 macOS 与 Linux 系统。在 Windows 上，请在 WSL（Windows 子系统 for Linux）内运行。安装需要系统已安装 `curl`。脚本会执行以下步骤：

1. 从 GitHub Releases 下载适用于你系统的发布二进制文件。
2. 根据发布版的 `SHA256SUMS` 文件进行校验。如果校验和缺失或不匹配，安装将中止。如果已安装 `cosign`，脚本还会校验 `SHA256SUMS` 文件的 Sigstore 签名，签名校验失败同样会中止安装。
3. 将二进制文件放置在 `~/.kortix/kortix` 目录下。
4. 将 `kortix` 和 `kortixt`（[TUI 终端界面](/docs/zh/guide#全平台everywhere)）的链接创建到 `/usr/local/bin` 目录中。如果该目录不可写，脚本会在 `~/.local/bin` 目录存在时将其作为备选；否则，脚本会尝试使用 `sudo` 权限进行安装。

| 环境变量 (Variable) | 作用 (Effect) |
| --- | --- |
| `KORTIX_VERSION=<x.y.z>` | 安装指定版本，而非最新版本。 |
| `KORTIX_CHANNEL=dev` | 安装开发通道版本（`dev-latest`）。另一个可选值为 `prod`（默认值）。 |
| `KORTIX_BIN_DIR=<dir>` | 将命令链接到此指定目录，而非默认的 `/usr/local/bin`。 |
| `KORTIX_HOME=<dir>` | 将二进制文件放置到此指定目录，而非默认的 `~/.kortix`。 |

```sh
curl -fsSL https://kortix.com/install | KORTIX_VERSION=0.14.8 bash
```

请通过运行 `kortix version` 命令来检查安装是否成功。如需更新或卸载 CLI 工具，请参阅 [Maintain the CLI（维护 CLI）](#维护-climaintain-the-cli)。

### 登录主机

```sh
kortix login
```

CLI 同一时间只能登录到一个 OpenChatly 实例。一个实例即为一个 **host（主机）**。你需要先登录到一个主机，然后从中选择一个账户。接着，在该账户下选择一个项目，并在该项目中运行会话。

执行 `kortix login` 会完成以下步骤：

1. 打开你的浏览器。你在浏览器中批准 CLI 的访问请求，随后令牌（token）会通过本地回调（callback）传回。
2. 选择你的账户。如果只有一个账户，系统会自动选中；如果有多个账户，系统会提示你选择。使用 `--account <slug>` 参数可跳过此提示。
3. 为该主机设置一个默认项目。使用 `--no-project` 参数可跳过此步骤。

如果该主机已经存在登录状态，`kortix login` 不会做任何更改并会给出相应提示。若要登录其他账户，请先运行 `kortix logout` 退出当前登录；或者传入 `--token` 或 `--api` 参数来替换当前的登录状态。

| 标志 (Flag) | 作用 (Effect) |
| --- | --- |
| `--token <token>` | 使用个人访问密钥登录，无需打开浏览器。适用于无图形界面的服务器（headless machine）。 |
| `--device` | 允许在任意设备的浏览器上批准登录，无需本地回调。 |
| `--account <slug>` | 直接选择指定的账户，不进行提示。 |
| `--no-project` | 不设置默认项目。 |
| `--host <name>` | 登录到指定名称的主机，而非当前活跃的主机。 |
| `--api <url>` | 指定该主机的 API URL。注册非内置的主机时需要此参数。 |

如需创建用于 `--token` 参数的令牌，请参阅 [Security（安全）](/docs/zh/guide#安全性)。

#### 主机（Hosts）

每个主机都保留自己独立的登录状态。两个内置主机涵盖了大多数使用场景：

| 主机 (Host) | URL |
| --- | --- |
| `cloud` | `https://api.kortix.com`。默认主机。 |
| `selfhost` | `http://localhost:13738`。执行 `kortix self-host start` 会将其设置为你自己实例的 URL。 |

| 任务 (Task) | 命令 (Command) |
| --- | --- |
| 添加主机并登录 | `kortix hosts add <name> --url <api-url> --login`。如果 `kortix login` 打开了错误的网页地址，请添加 `--dashboard-url <url>` 参数。 |
| 切换当前活跃的主机 | `kortix hosts use <name>` |
| 在另一个主机上运行单条命令 | `kortix <command> --host <name>` |
| 列出所有主机及其登录状态 | `kortix hosts ls` |
| 显示某个主机或当前活跃主机的信息 | `kortix hosts info [<name>]`（可加 `--json`） |
| 显示某个主机上已登录的用户 | `kortix hosts whoami [<name>]`（可加 `--json`） |
| 移除你添加的主机 | `kortix hosts rm <name>`。内置主机不会被移除，而是被重置。 |
| 从主机退出登录 | `kortix logout`，或 `kortix hosts logout <name>` |
| 切换当前活跃账户 | `kortix accounts use <slug>` |

CLI 会自动将远程的 `http://` URL 转换为 `https://`。但私有地址会保留 `http://` 协议：包括 `localhost`、私有 IP 地址，以及以 `.localhost`、`.local`、`.lan`、`.internal` 或 `.home.arpa` 结尾的域名。没有包含点号（`.`）的名称（例如 Docker Compose 的服务名）也会保留 `http://` 协议。

登录信息保存在 `~/.config/kortix/config.json` 文件中，文件权限为 `0600`。你可以通过环境变量 `KORTIX_CONFIG_FILE` 指定其他路径。

#### 检查当前身份

| 命令 (Command) | 输出内容 (Output) |
| --- | --- |
| `kortix whoami` | 显示当前主机、用户、活跃账户、默认项目和令牌上下文。脚本使用时可加 `--json`。 |
| `kortix token` | 仅显示令牌上下文：令牌类型（用户、项目或会话令牌）、所属项目、会话和智能体，以及连接器和权限授予情况。此命令绝不会打印令牌本身。 |

### 命令使用哪个项目

项目相关的命令会按照以下顺序查找并使用第一个匹配的项目：

1. 命令行中通过 `--project <id>` 指定的项目。
2. 当前目录下的 `.kortix/link.json` 文件。CLI 不会向上查找父目录。
3. `KORTIX_PROJECT_ID` 环境变量。
4. 当前主机的默认项目。

| 任务 (Task) | 命令 (Command) |
| --- | --- |
| 设置主机的默认项目 | `kortix projects use [<project_id>]` |
| 将当前目录绑定到一个项目 | `kortix projects link [<project_id>]` |
| 移除绑定 | `kortix projects unlink` |
| 清除默认项目 | `kortix projects unset` |

执行 `kortix projects use` 还会将活跃账户切换为该项目所属的账户。`kortix projects link` 会写入 `.kortix/link.json` 文件，且仅在包含 `.kortix/` 目录或 `kortix.yaml` 文件的目录中有效。执行 `kortix projects clone` 以及首次执行 `kortix ship` 时，系统会自动为你写入绑定信息。

绑定信息中还会记录主机。在已绑定的目录中执行命令时，无论当前活跃的主机是什么，命令都会发送到该绑定的主机上。

会话 ID 是跨项目通用的。当会话不在当前解析出的项目中时，CLI 会在你的其他账户和已登录的主机中进行搜索。使用 `--project` 可将搜索范围限制在该特定项目内。使用 `--host` 可将搜索范围限制在该主机的账户和项目内。通过 `kortix sessions ls` 获取的 8 位短 ID 可以在任何需要会话 ID 的地方使用。

### 日常使用循环

该工作流基于项目的 Git 仓库运行。你需要推送自己的分支，每个会话（session）都在独立的分支上工作，最后合并其提交的变更请求（change request）。[Quickstart（快速入门）](#快速入门quickstart) 会带你完成首次操作的完整流程。[Git（Git 指南）](#git版本控制) 则详细介绍了克隆、从任意 Git 客户端推送、会话分支以及变更请求等内容。

```sh
kortix init my-agent && cd my-agent           # 使用初始模板创建新项目
kortix ship                                   # 验证、提交并推送；同时创建项目
kortix sessions new --prompt "Add a skill that drafts the weekly status report"  # 新建会话并下达提示词
kortix chat <session_id>                      # 与智能体对话；使用 -p "…" 可直接发送单条提示词
kortix sessions wait-for <session_id>         # 阻塞等待，直到智能体完成任务
kortix cr ls && kortix cr diff 1              # 查看变更请求列表及第 1 个请求的差异
kortix cr merge 1 && git pull                 # 合并该变更请求并拉取最新结果
```

- `kortix init` 会根据初始模板（starter）创建一个新项目。其相关配置字段请参阅 [kortix.yaml 参考手册](#kortixyaml-参考)。
- `kortix projects clone <project_id> my-agent` 则用于获取一个现有的项目。它会使用你的 OpenChatly 登录凭证进行克隆，并安装 Git 凭证助手（credential helper），因此在克隆的目录中可以直接使用 `git pull` 和 `git push` 命令。
- `kortix ship` 会执行 `kortix validate` 检查，提交所有更改（相当于执行 `git add -A`），并提示你补充缺失的密钥。随后，它会将当前分支推送到远端同名分支，并提示你连接已声明的连接器。`kortix deploy` 是与此功能相同的命令。
- `1` 是通过 `kortix cr ls` 命令获取的变更请求编号。`kortix cr request-changes 1 --message "…"` 会将该备注信息发送给发起此变更请求的会话。

### 在 CI 和脚本中运行

在环境变量中为任务提供令牌（token）。此时 CLI 无需执行 `kortix login`：

| 环境变量 (Variable) | 值 (Value) |
| --- | --- |
| `KORTIX_TOKEN` | 个人访问密钥（格式为 `kortix_pat_`）。 |
| `KORTIX_PROJECT_ID` | 当任务在非绑定目录中运行时，指定要操作的项目。 |
| `KORTIX_API_URL` | 主机的 API URL。如果使用 OpenChatly Cloud，则无需设置此项。 |

`KORTIX_TOKEN` 的优先级高于任何已存储的登录状态，且 CLI 绝不会将其写入磁盘。你可以创建一个仅能访问单个项目的密钥：

```sh
kortix tokens new ci-nightly --project <project_id> --expires 90d
```

该密钥仅会显示一次，请务必将其保存在你的 CI 密钥存储库中。`--expires` 参数接受 ISO-8601 格式的日期，或者使用相对时间跨度，例如 `30d`（30天）、`12h`（12小时）、`6w`（6周）或 `1y`（1年）。

```yaml
# .github/workflows/nightly-report.yml
name: Nightly report
on:
  schedule:
    - cron: "0 6 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    env:
      KORTIX_TOKEN: ${{ secrets.KORTIX_TOKEN }}
      KORTIX_PROJECT_ID: ${{ vars.KORTIX_PROJECT_ID }}
    steps:
      - run: curl -fsSL https://kortix.com/install | bash
      - run: |
          id=$(kortix sessions new --prompt "Write the nightly report" --wait --json | jq -r .session_id)
          kortix sessions wait-for "$id" --timeout 1800
          kortix sessions log "$id" --limit 1
```

当智能体完成任务时，`kortix sessions wait-for` 返回退出码 `0`；若其最后一轮执行失败，返回 `1`；若正在等待用户回复，返回 `3`；若超时，则返回 `124`。因此，在 CI 步骤中，如果智能体的某轮执行失败，该步骤也会随之失败。你可以将 `--json` 的输出通过管道传递给 `jq` 进行处理。当设置了 `CI` 环境变量或标准输出（stdout）不是终端时，更新检查会自动关闭。若要在 OpenChatly 内部按计划定时启动会话，请使用 [Triggers（触发器）](/docs/zh/guide#触发器triggers)。

### 从你的编码智能体中使用 OpenChatly

像 Claude Code、Codex、Cursor 或 pi 这样的编码智能体，需要安装二进制文件、完成登录，并获取平台操作手册。

1. **安装并登录**

    安装 CLI 并运行 `kortix login`，或者在智能体的环境变量中设置 `KORTIX_TOKEN`。

2. **检查配置**

    ```sh
    kortix doctor
    ```

    `kortix doctor` 会检查登录状态和项目配置。随后，它会启动一个一次性（用完即弃）的测试会话，最多等待 180 秒以加载其沙盒环境，接着发送 `ping` 命令并等待回复，最后删除该测试会话。当所有检查均通过时，该命令返回退出码 `0`；若有任何一项检查失败，则返回 `1`。如果没有可用的模型来响应测试，该命令同样返回 `0`：此时请使用 `kortix providers` 命令连接一个模型，然后重新运行诊断。使用 `--no-session` 参数可在完成登录和项目检查后直接停止，不再启动测试会话。

3. **加载操作手册**

    ```sh
    kortix system-skills get kortix-system
    ```

    主机会实时提供 OpenChatly 的系统内置技能，因此它们始终与你正在交互的版本保持一致。请让你的智能体首先运行此命令。

4. **将项目接入本地工具**

    在已克隆的项目目录中，运行以下命令：

    ```sh
    kortix init --force
    ```

    该命令会将项目的技能（skills）链接到各个本地编码工具默认的查找路径中，并在项目根目录添加一个 `AGENTS.md` 指针文件，供 Codex、pi 和 Cursor 使用。如果不加任何参数，它会自动配置所有受支持的工具。你也可以使用 `--primary <tool>` 和 `--agents <list>` 参数来手动指定工具，可选值包括：`claude`、`codex`、`pi`、`cursor`。

    这些链接会被添加到 `.git/info/exclude` 文件中，因此它们永远不会作为代码变更显示出来。此操作也不会改变会话（sessions）在 OpenChatly 中的运行方式。

5. **委派工作**

    ```sh
    id=$(kortix sessions new --prompt "Fix the failing export test" --wait --json | jq -r .session_id)
    kortix sessions wait-for "$id" --timeout 900
    case $? in
      0) kortix sessions log "$id" ;;
      3) kortix sessions pending "$id" ;;
    esac
    ```

    返回退出码 `3` 表示智能体正在等待用户回答问题或授予权限。请使用 `kortix sessions answer` 或 `kortix sessions approve` 命令进行回复或批准，然后再次执行等待命令。返回退出码 `1` 表示上一轮执行失败，该命令会打印出具体的失败原因。

MCP 客户端无需使用 CLI 即可调用 OpenChatly。详情请参阅 [Other AI tools (MCP)（其他 AI 工具 (MCP)）](/docs/zh/guide#其他-ai-工具mcp)。

### 在会话沙盒内部

每个沙盒都已预装 CLI 并完成登录。平台会自动设置 `KORTIX_TOKEN`、`KORTIX_API_URL`、`KORTIX_PROJECT_ID` 和 `KORTIX_SESSION_ID` 环境变量，因此智能体无需登录或进行任何绑定即可直接运行命令。此处的令牌是会话令牌：通过 `kortix token` 可以查看其所属会话、智能体及权限授予情况。它仅能操作当前会话所属的项目。

智能体常用的命令：

| 命令 (Command) | 用途 (Purpose) |
| --- | --- |
| `kortix connectors call <slug> <action> [json]` | 调用连接器操作。请参阅 [Connectors（连接器）](/docs/zh/guide#连接器connectors)。 |
| `kortix secrets request <NAME>` | 生成一个有效期为 7 天的链接，供他人输入密钥值。 |
| `kortix secrets sync` | 立即拉取当前会话的密钥和权限授予信息。 |
| `kortix cr open --title "<text>"` | 从当前会话分支发起一个变更请求。在会话中运行时，它会自动填充 `--head` 参数。 |
| `kortix review submit --kind <kind> --title "<text>"` | 提交输出结果、决策或批量任务以供审核。 |
| `kortix loop "<prompt>" --in 24h` | 稍后（例如 24 小时后）再次向当前会话发送提示词（形成循环）。循环是一项项目级功能，默认开启；使用 `kortix projects features disable reminders` 可将其关闭。`kortix remind` 是此命令的别名。 |
| `kortix triggers add "<prompt>" --on cr-merged --cr <id>` | 当某个变更请求被合并时唤醒当前会话。其他触发源包括：`--on webhook --secret-env NAME`、`--on event`、`--on app`，或定时标志（`--every`、`--cron`、`--at`、`--in`）。使用 `--agent <name>` 可改为启动该智能体的新会话。 |
| `kortix sessions update --label <label>` | 为智能体当前运行的会话添加标签。 |

`--on event` 会在连接器事件发生时启动会话。连接器事件目前处于实验阶段，默认关闭。你可以在 **Project admin（项目管理）** → **Feature flags（功能标志）** 中将其开启。

智能体可执行的操作由 `kortix.yaml` 中的 `kortix_permissions` 字段决定。当 API 拒绝执行某条命令时，CLI 会打印出令牌类型、智能体名称及其权限授予情况。详情请参阅 [Agents（智能体）](/docs/zh/guide#智能体agents)。无论权限授予情况如何，以下命令在智能体会话的令牌中始终被拒绝：

- `kortix projects cli-tokens new` 和 `rm`
- `kortix gateway keys`（`ls`、`new`、`rm`）

在沙盒中执行 `kortix update` 会被拒绝。平台会统一管理二进制文件：如需获取最新版本的 CLI，请重启会话。

若要操作另一个项目的 `.kortix/link.json`，需要预先存储该项目所在主机的登录信息。请先在沙盒中运行 `kortix login`。

### 命令参考

使用 `kortix <command> --help` 或 `kortix help <command>` 可以查看每个命令的子命令和标志。如果某个命令所属的功能在当前项目中处于关闭状态，它将不会显示在 `kortix --help` 的输出中。

{/* generated:cli-commands:start */}

{/* 由 apps/web/scripts/generate-cli-commands-doc.mjs 根据 apps/cli/src/command-table.ts 和脚本的 COMMANDS 行自动生成。请修改这些源文件，然后运行该脚本。 */}

**从这里开始**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `system-skills [get <name>]` | 打印由主机实时提供的 OpenChatly 平台操作手册。`kortix skills` 是相同的命令。 | [从你的编码智能体中使用 OpenChatly](#从你的编码智能体中使用-openchatly) |

**登录（按主机）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `hosts <subcommand>` | 添加、切换、列出 OpenChatly 实例并退出登录。 | [主机](#主机hosts) |
| `login` | 登录到当前活跃的主机。等同于 `kortix hosts login`。 | [登录主机](#登录主机) |
| `logout` | 从当前活跃的主机退出登录。等同于 `kortix hosts logout`。 | [主机](#主机hosts) |
| `whoami` | 显示当前主机、已登录用户和活跃账户。 | [检查当前身份](#检查当前身份) |
| `token` | 显示令牌上下文：所属项目、会话、智能体及权限授予。 | [检查当前身份](#检查当前身份) |
| `self-host <subcommand>` | 使用 Docker 镜像设置、启动、更新和停止你自己的 OpenChatly 实例。 | [自托管](#自托管self-hosting) |

**账户（在主机内）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `accounts <subcommand>` | 列出并切换账户。 | [团队](/docs/zh/guide#teams) |
| `members <subcommand>` | 邀请和移除成员，并更改其角色。 | [团队](/docs/zh/guide#teams) |
| `groups <subcommand>` | 管理共享同一角色的用户组。 | [团队](/docs/zh/guide#teams) |
| `tokens <subcommand>` | 管理个人访问密钥、服务账户和已连接的应用。 | [安全](/docs/zh/guide#安全性) |
| `billing <subcommand>` | 查看套餐、额度、交易记录以及按项目和会话产生的费用。 | [计费](/docs/zh/guide#计费billing) |

**项目（在账户内）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `init [project-name]` | 使用初始模板创建项目目录及其 `kortix.yaml` 配置文件。 | [日常使用循环](#日常使用循环) |
| `projects <subcommand>` | 列出、创建、克隆、绑定、使用、重命名和删除项目。还包括功能标志（`features`）和项目 CLI 令牌（`cli-tokens`）的管理。 | [命令使用哪个项目](#命令使用哪个项目) |

**会话（在项目内）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `sessions <subcommand>` | 启动、对话、跟踪、停止和删除会话。 | [会话命令](#会话命令) |
| `chat [session-id]` | 与会话中的智能体对话：进入行内聊天模式，或使用 `-p` 发送单条提示词。等同于 `kortix sessions chat`。 | [会话命令](#会话命令) |
| `tui [options]` | 将完整产品作为终端应用运行。`kortix t` 和 `kortixt` 也可以启动它。目前处于实验阶段。 | [随处可用](/docs/zh/guide#全平台everywhere) |

**编写代码与推送（Author and ship）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `ship` | 验证、提交并推送当前分支。如果文件夹没有绑定且没有默认项目，系统将为其创建一个新项目。`kortix deploy` 是相同的命令。 | [提交并推送](#提交并推送commit-and-push) |
| `validate` | 检查 `kortix.yaml` 和沙盒模板 Dockerfiles。每个问题输出一行信息：`<文件>:<行>:<列>  <严重级别>  <路径>  <消息>`。 | [检查与验证](#检查与验证check-and-validate) |
| `doctor [--no-session]` | 检查登录状态和项目配置，然后启动一个一次性测试会话并等待智能体回复。 | [检查与验证](#检查与验证check-and-validate) |
| `schema [--url]` | 打印 `kortix.yaml` 的 JSON Schema。 | [检查与验证](#检查与验证check-and-validate) |

**智能体与连接器（Agents and connectors）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `agents <subcommand>` | 管理默认智能体、模型固定、作用域以及完整的智能体配置。 | [智能体](/docs/zh/guide#智能体agents) |
| `tools <subcommand>` | 列出会话可用的工具；`eject` 可将 OpenChatly 工具复制到项目中以便你进行自定义修改。 | [智能体](/docs/zh/guide#智能体agents) |
| `models <subcommand>` | 查看项目提供的模型及其默认模型。 | [模型](/docs/zh/guide#模型models) |
| `gateway <subcommand>` | 管理 LLM 网关路由、预算、密钥、使用量、日志和测试。 | [模型](/docs/zh/guide#模型models) |
| `connectors <subcommand>` | 添加、连接、调用和管理连接器。`moves` 和 `move` 用于将 Pipedream 和 Composio 连接器迁移到 OpenChatly。 | [连接器](/docs/zh/guide#连接器connectors) |
| `secrets <subcommand>` | 管理项目密钥、其暴露范围以及使用权限。 | [安全](/docs/zh/guide#安全性) |
| `providers <subcommand>` | 使用 API 密钥或 OAuth 连接模型提供商。 | [模型](/docs/zh/guide#模型models) |
| `env <subcommand>` | 将密钥名称拉取到 `.env` 文件中，或将 `.env` 文件作为密钥推送。 | [安全](/docs/zh/guide#安全性) |
| `channels <subcommand>` | 管理 Slack 和 Microsoft Teams 连接，以及每个通道运行的智能体。 | [通道](/docs/zh/guide#频道channels) |
| `sandboxes <subcommand>` | 管理沙盒模板、构建及其健康状态。 | [计算环境](/docs/zh/guide#计算机computers) |
| `apps <subcommand>` | 部署和管理应用：具有稳定 OpenChatly URL 的网站和服务器。 | [应用参考](#应用参考apps-reference) |
| `marketplace <subcommand>` | 搜索、查看、安装和卸载市场技能。 | [技能](/docs/zh/guide#技能skills) |

**文件、变更与触发器（Files, changes and triggers）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `files <subcommand>` | 读取已提交的仓库：文件、历史记录、分支、提交、差异和 zip 下载。 | [Git](#git版本控制) |
| `drive <subcommand>` | 项目网盘（Drive）：列出、读取、上传、移动和删除文件，以及共享文件夹。 | [网盘](/docs/zh/guide#云盘drive) |
| `search <query>` | 根据你的文件夹访问权限，按文件名和文本搜索项目网盘。在会话中，它涵盖会话可挂载的所有文件夹，包括其挂载点之外的文件夹。 | [网盘](/docs/zh/guide#云盘drive) |
| `cr <subcommand>` | 变更请求：列出、显示、查看差异、发起、合并、请求修改、关闭和重新打开。 | [Git](#git版本控制) |
| `review <subcommand>` | 审核收件箱：变更请求、被拦截的连接器调用和提交的输出结果。 | [Git](#git版本控制) |
| `triggers <subcommand>` | 管理所有触发器（`kortix.yaml` 和运行时）：`ls` 同时列出两者，`add` 写入 `kortix.yaml`（使用 `--on`、`--session` 或 `--runtime` 可创建运行时触发器），`fire`、`enable`、`disable`、`run`、`pause`、`resume` 和 `rm` 接受 slug 或运行时 ID。 | [触发器](/docs/zh/guide#触发器triggers) |
| `loops <subcommand>` | 设置进入同一会话的定时任务（循环：唤醒创建它的会话的触发器）。`kortix loop "…" --in 24h` 可添加一个循环。别名：`reminders`。 | [触发器](/docs/zh/guide#触发器triggers) |
| `capture <subcommand>` | 搜索你代理的人员的 Capture 时间线。Capture 默认关闭，需由账户管理员开启。 | [Capture](/docs/zh/capture) |

**访问与权限（Access and permissions）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `access <subcommand>` | 授予、列出和撤销人员、组和智能体的角色分配。 | [团队](/docs/zh/guide#teams) |
| `roles <subcommand>` | 管理系统和自定义角色，以及每个角色的允许操作。 | [团队](/docs/zh/guide#teams) |
| `permissions <subcommand>` | 查看构建角色的权限目录。`kortix perms` 是相同的命令。 | [团队](/docs/zh/guide#teams) |
| `audit <subcommand>` | 读取账户审计日志。 | [团队](/docs/zh/guide#teams) |
| `grants <subcommand>` | 将智能体分配给成员或组。 | [团队](/docs/zh/guide#teams) |

**CLI 自身管理（The CLI itself）**

| 命令 (Command) | 功能说明 (What it does) | 参阅 (See) |
| --- | --- | --- |
| `feedback "<message>" [--kind bug\|idea\|friction]` | 向 OpenChatly 团队发送产品反馈。 | [维护 CLI](#维护-climaintain-the-cli) |
| `update` | 将二进制文件替换为最新版本。 | [维护 CLI](#维护-climaintain-the-cli) |
| `uninstall` | 从当前机器卸载 CLI。 | [维护 CLI](#维护-climaintain-the-cli) |
| `help` | 显示命令列表。`kortix help <command>` 打印特定命令的帮助信息。 | [约定](#约定conventions) |
| `version` | 打印 CLI 版本。 | [维护 CLI](#维护-climaintain-the-cli) |

{/* generated:cli-commands:end */}

### 会话命令

以下命令均为 `kortix sessions <subcommand>` 格式。使用 `kortix sessions --help` 可列出所有标志。其背后的行为机制请参阅 [计算环境](/docs/zh/guide#计算机computers)。

#### 启动与列表

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `new --prompt "<text>"` | 启动一个会话。`--agent <name>` 和 `--model <id>` 可覆盖项目默认设置。`--wait` 会阻塞直到会话准备好接收提示词。`--json` 会打印会话对象。 |
| `new … --with-file <path>` | 在提示词发送前，将本地文件上传到 `/workspace/incoming/<name>`。可重复使用。 |
| `new … --label <label>`, `--meta <key>=<value>` | 对会话进行分类。两者均可重复使用。 |
| `new … --connector <alias>=<connection-id>` | 将连接绑定到会话。可重复使用。`--no-connectors` 不绑定任何连接。 |
| `ls` | 列出会话及其启动者。支持 `--mine`、`--shared`、`--automated`、`--search <q>`、`--label <label>`、`--children <session_id>`。列表会排除你已归档的会话，并标记置顶会话为 `(pinned)`。`--pinned` 仅列出你的置顶会话，`--archived` 仅列出已归档的会话。`--deleted` 列出你可以恢复的已删除会话，显示其完整 ID 及可恢复的截止日期。 |
| `pin <session_id>…`, `unpin <session_id>…` | 在你自己的列表中置顶或取消置顶会话。仅更改你的列表。 |
| `archive <session_id>…`, `unarchive <session_id>…` | 将会话从你自己的列表中移除或放回。归档会取消置顶会话，但不会停止会话。 |
| `status` | 每个活跃会话输出一行信息，显示其智能体当前正在执行的操作。`--all` 会加上已停止的会话。 |
| `info <session_id>` | 显示单个会话的信息。 |

#### 对话（Talk）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `chat [<session_id>]` | 与智能体进行行内聊天。如果不指定 ID，则默认选择你最近运行的会话。使用 `--new` 可启动一个新会话。 |
| `chat <session_id> -p "<text>"` | 发送一条提示词，打印回复并退出。`--json` 会将回复以 JSON 格式打印。 |
| `chat <session_id> -p "<text>" --queue` | 将提示词存入会话的收件箱并立即返回。即使沙盒处于休眠或繁忙状态，提示词也会被保留。 |
| `chat <session_id> -p "<text>" --steer` | 将提示词发送给当前正在运行的轮次。智能体会在其下一步骤中读取该提示词。如果没有正在运行的轮次，则启动一个新轮次。 |
| `queue <session_id>` | 管理收件箱：`ls`（列出）、`rm <prompt-id>`（删除）、`now <prompt-id>`（立即执行）、`hold`（暂停）、`release`（释放）。 |
| `message <to> "<text>"` | 从当前会话向另一个会话发送消息（默认使用 `$KORTIX_SESSION_ID`，否则使用 `--from <session_id>`）。支持 `--summary` 和 `--notify-idle`。若发送失败，返回退出码 `1`。请参阅 [会话间消息](#会话间消息messages-between-sessions)。 |
| `reachable` | 列出当前会话可以发送消息的目标会话。使用 `--scope project` 可列出所有活跃会话。 |
| `inbound <session_id> [accept\|hold\|refuse]` | 设置会话如何处理来自其他会话的消息。`ls`、`approve <id>`、`deny <id>` 用于处理被暂停的消息。 |

#### 监控（Watch）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `log [<session_id>]` | 查看近期消息（只读）。对于已停止的会话，会从保存的对话记录中读取，且不会唤醒该会话。支持 `--limit <n>`（默认值为 10）。 |
| `wait-for <session_id>` | 阻塞等待，直到智能体完成任务。返回退出码：`0` 表示完成，`1` 表示上一轮失败（会打印原因），`3` 表示正在等待问题解答或权限授予，`124` 表示超时。支持 `--timeout <seconds>`（默认值为 300）。 |
| `digest` | 生成近期会话的简短回顾。支持 `--since 7d`（例如过去 7 天）。 |

#### 解除阻塞（Unblock）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `pending <session_id>` | 查看智能体正在等待解答的问题和工具权限请求。 |
| `approve <session_id> [<request-id>]` | 批准权限请求。支持 `--always`、`--reject`、`--message "<why>"`。 |
| `answer <session_id> [<request-id>]` | 回答问题。支持 `--option <value>`、`--text "<answer>"`、`--reject`。 |
| `approvals <session_id>` | 管理因策略而暂停的连接器调用：`ls`（列出）、`approve <execution-id>`（批准）、`deny <execution-id>`（拒绝）。 |

#### 文件与端口（Files and ports）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `cp <src> <dst>` | 在你的本地机器与沙盒之间，或两个沙盒之间复制文件。沙盒路径格式为 `<session_id>:<path>`。对目录操作请使用 `-r`。 |
| `files <session_id> <sub>` | 操作实时的 `/workspace` 目录：`ls`、`status`、`find`、`write`、`touch`、`mkdir`、`mv`、`rm`。 |
| `attachments <session_id>` | 查看上传的文件及智能体展示的文件。即使会话已停止也可使用。支持 `--download <id>`、`--all`、`--out <dir>`。 |
| `preview <session_id> [port]` | 打印沙盒端口的预览 URL。默认端口为 `3000`。 |
| `forward <session_id> --port <sandbox>[:<local>]` | 将沙盒端口转发到本地 `localhost`（支持 HTTP 和 WebSocket）。按 Ctrl+C 停止转发。 |
| `shell [<session_id>]` | 在沙盒中打开一个不包含智能体的原生终端。使用 `--new` 可打开一个全新的终端。 |

#### 生命周期（Lifecycle）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `stop <session_id>` | 停止沙盒。`/workspace` 和 `/drives` 中的文件会被保留。 |
| `start <session_id>` | 唤醒会话。使用 `--wait` 会阻塞直到会话准备就绪。 |
| `restart <session_id>` | 停止并重新启动沙盒。如果会话没有沙盒，则会从该会话的分支启动一个新的沙盒。 |
| `recover <session_id>` | 在新的沙盒中继续一个丢失的会话，基于该会话的分支和保存的对话记录。当沙盒丢失时，`start` 命令会提示使用此命令。 |
| `reload <session_id>` | 拉取仓库并将基础分支的智能体配置加载到正在运行的沙盒中。除非传递 `--force`，否则在轮次运行期间拒绝执行。`--status` 仅报告会话是否落后于最新配置。 |
| `model <session_id> <model-id>` | 更改模型。正在运行的沙盒会重启其智能体运行时，这会结束当前轮次。 |
| `compact <session_id>` | 立即开启全新的上下文：当智能体需要细节时，它会搜索会话的完整记录（如果智能体配置了 `context: summary`，则改为进行摘要）。`--json` 会输出 `mode` 名称。如果会话已停止，会先将其唤醒。 |
| `rename <session_id> <name>` | 设置会话名称。传入 `""` 可恢复自动生成的标题。 |
| `update [<session_id>]` | 添加或移除标签和元数据。 |
| `rm <session_id>…` | 停止并删除会话。每个会话在 30 天内可恢复；超过期限后，其消息、文件和分支将被彻底删除。命令会打印每个会话的 `restore` 恢复命令。`--json` 会添加 `restore_until` 和 `project_id` 字段。 |
| `restore <session_id>` | 在 30 天内恢复已删除的会话。需传入完整的会话 ID（`ls --deleted` 可列出），如果该会话不在当前绑定的项目中，还需传入 `--project`。 |

#### 访问控制（Access）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `share <session_id> --mode private\|project\|members` | 设置 OpenChatly 中谁可以打开该会话。支持 `--member <id\|email>`、`--group <id>`。 |
| `scope <session_id>` | 读取或替换会话的密钥和连接。更改将在下一条提示词时生效。 |
| `links <session_id>` | 管理指向某个预览端口或文件的公共链接：`ls`、`create`、`revoke <share-id>`。 |
| `open <session_id>` | 在 Web 应用中打开该会话。 |

### 产物命令（Artifact commands）

以下命令均为 `kortix artifacts <subcommand>` 格式。使用 `kortix artifacts --help` 可列出所有标志。这些命令需要开启 `artifacts` 功能标志（默认开启）。注释相关的命令还需要开启 `artifact_comments` 标志（默认关闭）。关于 Artifact 的定义，请参阅 [Artifacts（产物）](/docs/zh/guide#交付物artifacts)。

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `types [<type>]` | 两种类型：`doc` 和 `html`。指定类型时：显示其格式规则和初始模板。`--starter` 仅打印初始模板。 |
| `publish <file\|dir>` | 上传并分享一个新的 Artifact，保存在你网盘的 `Artifacts/` 文件夹下。`.md` 文件或包含 `index.md` 的文件夹为文档（doc）。`.html` 文件或包含 `index.html` 的文件夹为网页（page）。支持 `--title`、`--description`、`--visibility private\|project\|public`（默认为 `private`）。命令会打印分享链接。 |
| `publish <file\|dir> --id <artifact>` | 将文件保存到指定的 Artifact 中。使用 `--base-version <v>` 时，如果在版本 `<v>` 之后有人保存过（即 `info` 或 `pull` 中的 `entry_version`），则拒绝保存并返回退出码 `3`。 |
| `add <path>` | 分享网盘中已有的文件夹。该文件夹必须包含 `index.md` 或 `index.html`。选项与 `publish` 相同。 |
| `ls` | 列出你可打开的 Artifacts，按最新排序。支持 `--mine`、`--shared`、`--pinned`、`--type doc\|html`、`--search "<text>"`。 |
| `info <artifact>`, `open <artifact>` | `info` 打印标题、类型、网盘路径、文件和链接。`open` 仅打印链接。 |
| `cat <artifact> [<path>]`, `pull <artifact> <dir>` | `cat` 打印单个文件（默认为入口文件）。`--version <id>` 可读取旧版本。`pull` 下载文件，以便编辑后重新发布。 |
| `share <artifact>` | 设置 `--visibility private\|project\|public`。使用 `--with <email\|user-id>` 可将某人添加到私有 Artifact 中。可重复使用，或传入 `--with ""` 清空列表。 |
| `rename <artifact> "<title>"` | 重命名 Artifact。 |
| `pin <artifact>`, `unpin <artifact>` | 在你自己的列表中置顶或取消置顶。 |
| `versions <artifact>`, `restore <artifact> <version-id>` | `versions` 列出所有保存记录，按最新排序。`restore` 将某个保存记录写回为新版本。 |
| `rm <artifact>` | 停止分享。其评论会被删除，但文件仍保留在网盘中。 |
| `comments <artifact>` | 查看未解决的评论线程。`--all` 会加上已解决的线程。`--resolved` 仅显示已解决的线程。等待他人回复的线程会有相应提示。 |
| `comment <artifact> "<text>"` | 在整个 Artifact 上开启一个评论线程。`--quote "<text>"` 可将其锚定到最多 500 个字符的精确段落。如果引用的文本不在文件中，则返回非零退出码且不发布评论。`--selector "<css>"` 可将其锚定到网页的某个元素。 |
| `reply <thread-id> "<text>"` | 通过完整 ID 回复某个线程。 |
| `resolve <thread-id>`, `reopen <thread-id>` | 解决或重新打开某个线程。 |
| `activity <artifact>` | 查看保存记录和事件，按最新排序。`--limit` 接受 1 到 100 的值。 |
| `focus <artifact>` | 仅限智能体会话。显示正在查看该 Artifact 的人员（智能体工作时）：`--thread <thread-id>`（智能体回复的线程）或 `--quote "<text>"`（智能体修改的段落，最多 500 个字符）。支持 `--status reading\|editing\|writing\|idle`，默认为 `editing`。`idle` 会将智能体从查看者列表中移除。使用个人令牌时返回退出码 `1`。 |

`<artifact>` 为 Artifact ID 或 `ls` 输出中的前 8 个字符。`--json` 会打印机器可读的输出。退出码：`0` 成功，`1` API 错误，`2` 用法错误，`3` 版本冲突。

### 检查与验证（Check and validate）


| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `kortix validate` | 根据 Schema 检查 `kortix.yaml`，对每个 `sandbox.templates` Dockerfile 进行代码检查（lint），并对 Git 中的大文件发出警告。退出码：`0` 表示有效，`1` 表示有错误，`2` 表示文件未找到。支持 `--file <path>`、`--json`、`--no-dockerfile-lint`、`--fix`（优先重写已废弃的结构）。`--scopes` 会打印所有可授予的 `kortix_permissions` 值。`kortix ship` 也会运行相同的检查。 |
| `kortix schema` | 打印 `kortix.yaml` 的 JSON Schema。使用 `--url` 则打印其 URL：`https://kortix.com/schema/kortix.schema.json`。 |
| `kortix doctor` | 检查登录状态和项目配置，然后启动一个一次性测试会话，发送 `ping` 并等待回复。支持 `--no-session`、`--keep-session`、`--prompt "<text>"`、`--timeout <seconds>`（等待沙盒的时长，默认 180 秒）。退出码：`0` 表示通过，`1` 表示失败。 |
| `kortix system-skills list` | 列出 OpenChatly 系统内置技能。 |
| `kortix system-skills get <name>` | 打印某个技能及其参考文件的路径。`--full` 会加上每个参考文件的内容。 |
| `kortix system-skills file <name> <path>` | 打印某个参考文件的内容。 |
| `kortix system-skills path [<name>]` | 打印该技能在磁盘上的目录路径。 |

Schema 字段请参阅 [kortix.yaml 参考手册](#kortixyaml-参考)。

### 约定（Conventions）

- `kortix`、`kortix help` 和 `kortix --help` 会打印相同的界面：显示你的主机、账户和项目，然后列出所有命令。`kortix help <command>` 会打印特定命令的帮助信息。
- `--host <name>` 可将单条命令发送到另一台主机。`--project <id>` 可将其发送到另一个项目。两者也可以放在命令之前使用：`kortix --host <name> sessions ls`。
- 对于支持的命令，`--json` 会打印 JSON 格式的输出。在任何命令上，它都会关闭主机和更新通知（包括标准错误输出 stderr 中的通知）。
- `--debug`（或设置环境变量 `KORTIX_DEBUG=1`）会将解析后的主机、账户和凭证来源打印到标准错误输出（stderr）。
- 如果命令拼写错误，将返回退出码 `2`；如果命令名称在两次编辑（edits）的容差范围内，会将其作为建议打印出来。CLI 绝不会自动搭建项目目录，只有 `kortix init` 才会执行此操作。

| 退出码 (Exit code) | 含义 (Meaning) |
| --- | --- |
| `0` | 成功。 |
| `1` | 命令失败。原因会输出到标准错误输出（stderr）。当智能体的上一轮执行失败时，`kortix sessions wait-for` 也会返回 `1`。 |
| `2` | 用法错误：未知的命令或子命令、错误的标志或缺失的参数。当文件未找到时，`kortix validate` 也会返回 `2`。 |
| `3` | 仅限 `kortix sessions wait-for`：智能体正在等待问题解答或权限授予。 |
| `124` | 仅限 `kortix sessions wait-for`：已超时。 |

| 别名 (Alias) | 对应命令 (Command) |
| --- | --- |
| `deploy` | `ship` |
| `session` | `sessions` |
| `skills` | `system-skills` |
| `perms` | `permissions` |
| `remind` | `reminders add` |
| `t`, `kortixt` | `tui` |
| `sessions pause` / `wake` | `sessions stop` / `start` |
| `sessions wait` | `sessions wait-for` |
| `sessions messages`, `sessions history` | `sessions log` |
| `sessions overview`, `sessions ps` | `sessions status` |
| `sessions terminal`, `sessions ssh` | `sessions shell` |
| `sessions copy` | `sessions cp` |
| `sessions undelete` | `sessions restore` |

### 维护 CLI（Maintain the CLI）

| 命令 (Command) | 效果 (Effect) |
| --- | --- |
| `kortix version` | 打印版本号。`kortix --version` 和 `-v` 具有相同效果。 |
| `kortix update` | 重新运行安装脚本并替换二进制文件。 |
| `kortix uninstall` | 移除二进制文件、`kortix` 和 `kortixt` 链接、`~/.kortix` 目录，以及包含所有主机登录信息的 CLI 配置文件。 |
| `kortix feedback "<message>"` | 向 OpenChatly 团队发送产品反馈。 |

单独运行 `kortix` 命令最多每 6 小时检查一次新版本，并提示是否安装。其他命令会显示一行来自缓存检查的通知。使用 `KORTIX_NO_UPDATE_CHECK=1` 可关闭检查。使用 `KORTIX_NO_UPDATE_PROMPT=1` 可保留通知但跳过安装提示。会话沙盒内永远不会进行更新检查。

`kortix uninstall` 在移除任何内容前会进行确认：

| 标志 (Flag) | 效果 (Effect) |
| --- | --- |
| `-y`, `--yes` | 跳过确认提示。 |
| `--keep-auth` | 保留 CLI 配置文件及其登录信息。 |
| `--keep-home` | 保留 `~/.kortix` 目录。仅移除二进制文件和链接。 |

`kortix feedback` 支持 `--kind bug|idea|friction`（默认为 `idea`）。在会话中运行时，它会自动为报告标记会话和项目的 ID。

## REST API

OpenChatly REST API 是用于管理账户、项目、会话、密钥、连接器、触发器和应用的 HTTP 接口。Web 应用、CLI、SDK 以及 OpenChatly MCP 服务器均调用此 API。你可以从任何能够发送带有 Bearer 令牌的 HTTPS 请求的编程语言中直接调用它。

以下示例展示了如何创建个人访问密钥、列出你的项目以及启动一个会话。

```bash
kortix tokens new my-script --expires 30d    # prints kortix_pat_… once
export TOKEN=kortix_pat_...

curl -s https://api.kortix.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"

curl -s https://api.kortix.com/v1/projects/<project_id>/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"initial_prompt": "Summarize the open change requests."}'
```

`GET /v1/projects` 会返回一个项目数组，每个项目都包含 `project_id`。

创建会话时，如果成功，接口会返回 `201` 状态码以及包含 `session_id` 和 `branch_name` 的会话信息。如果 OpenChatly 将创建请求放入队列，则会返回 `202` 状态码，并附带 `status`、`command_id` 和 `session_id`。在这种情况下，请通过 `GET /v1/projects/<project_id>/sessions/<session_id>` 轮询读取该会话，直到它出现为止。

如果仅有 `session_id`，使用 `GET /v1/sessions/<session_id>` 也能返回相同的会话及其 `project_id`。两者的访问规则是相同的。对于无权读取的会话、未知的 ID 以及已删除的会话，该接口均会返回 `404`，因此仅凭 ID 永远无法确认一个会话是否存在。如果使用的密钥（key）的作用域仅限于某个特定项目，则无法调用此路由，请改用带有该项目作用域的路由。

### 选择接入方式（Pick a surface）

所有四种接入方式都能以相同的权限访问同一个 API。

| 接入方式 (Surface) | 适用场景 (Use it for) | 凭证 (Credential) |
|---|---|---|
| REST API | 适用于任何编程语言。主要用于非 TypeScript 的集成、脚本和服务器。 | 通过 [Authenticate（认证）](#认证authenticate) 获取的 Bearer 令牌 |
| [SDK](#sdk) (`@kortix/sdk`) | 适用于 TypeScript 和 React。支持会话的实时流式传输、类型化错误处理、自动重试以及会话运行时。 | `getToken` 方法会返回一个 Bearer 令牌 |
| [CLI](#cli命令行界面) (`kortix`) | 适用于终端、CI 任务以及会话沙盒内的智能体。 | 使用 `kortix login` 登录，或在 CI 环境中配置令牌 |
| [OpenChatly MCP server](/docs/zh/guide#其他-ai-工具mcp) | 适用于 Claude、Cursor、ChatGPT 及其他代替你执行操作的 MCP 客户端。其 `search_api`、`describe_api` 和 `call_api` 工具可读取并调用此 API。 | 客户端通过 OAuth 登录 |

**建议：** 对于任何驱动会话的操作，请优先使用 SDK。SDK 封装了会话的启动、就绪等待、事件流以及运行时路由，而 REST API 参考文档中并未列出这些路由。

### 基础 URL 与参考文档（Base URL and reference）

| 部署方式 (Deployment) | 基础 URL (Base URL) |
|---|---|
| OpenChatly Cloud | `https://api.kortix.com/v1` |
| 自托管（带域名） | 默认为 `https://api.<domain>/v1`。请参阅 [自托管](#自托管self-hosting)。 |
| 自托管（单机） | 默认为 `http://localhost:13738/v1` |

每个部署实例都会提供其专属的路由参考文档：

- `GET /v1/docs`：交互式参考文档。本文档顶部的 **API reference（API 参考）** 标签页会打开 OpenChatly Cloud 的副本。
- `GET /v1/openapi.json`：OpenAPI 3.1 规范文档。其 `servers` 条目为相对 URL `/`，它会相对于你获取该文档的地址进行解析。因此，从自托管实例生成的客户端会自动指向该实例。
- `GET /v1/health`：无需令牌。返回 `status`（状态）、`service`（服务）、`version`（版本）、`commit`（提交哈希）、`environment`（环境）、`timestamp`（时间戳）和 `started_at`（启动时间）。

该参考文档不包含运维人员专用的路由。自托管的运维人员可以通过在 API 环境变量中设置 `OPENAPI_PUBLIC_DOCS=false` 来同时关闭 `/v1/docs` 和 `/v1/openapi.json`。

### 认证（Authenticate）

在每个请求中发送以下标头（Header）：

```http
Authorization: Bearer <token>
```

令牌（Token）决定了请求代表谁执行操作。每种 OpenChatly 凭证都以一个表明其类型的前缀开头。你可以在 [Security（安全）](/docs/zh/guide#安全性) 页面创建和管理它们。

| 前缀 (Prefix) | 凭证类型 (Credential) | 代表身份 (Acts as) |
|---|---|---|
| `kortix_pat_` | 个人访问密钥（**Settings（设置）** → **Personal access keys（个人访问密钥）**，`kortix tokens new`，`kortix login`） | 代表你本人，拥有你的角色权限。如果密钥绑定了特定项目，则在该项目之外访问时会返回 `403`。 |
| `kortix_sa_` | 服务账户密钥（**Account settings（账户设置）** → **Tokens & automation（令牌与自动化）**，`kortix tokens service-accounts new`） | 代表服务账户。在被分配角色之前，它没有任何访问权限。 |
| `kortix_oat_` | 来自 [Sign in with OpenChatly（使用 OpenChatly 登录）](#使用-openchatly-登录) 的 OAuth 访问令牌。有效期为 1 小时。使用 `kortix_ort_` 刷新令牌可以获取新的访问令牌。 | 代表批准该应用的用户。 |
| `kortix_gw_` | 项目网关密钥（`kortix gateway keys new`） | 仅代表某个项目的 LLM 网关推理路由，无其他权限。请参阅 [从你自己的应用调用 LLM 网关](#从你自己的应用调用-llm-网关call-the-llm-gateway-from-your-own-app)。 |
| `kortix_scim_` | SCIM 令牌（**Account settings（账户设置）** → **Identity & directory（身份与目录）**） | 代表某个账户在 `/scim/v2` 下的目录同步操作。 |
| `KORTIX_TOKEN` 中的 `kortix_pat_` | 会话令牌。OpenChatly 会在每个会话沙盒中自动设置此令牌。 | 代表该特定会话的智能体，权限仅限于其所属项目。随会话结束而失效。 |

如果 OAuth 令牌不包含 `kortix` 作用域（scope），它只能访问 `/v1/accounts/me`、`/v1/oauth/userinfo` 和 `/v1/oauth/revoke`。其他路由会返回 `403`，且 `message` 字段以 `insufficient_scope`（权限不足）开头。即使包含 `kortix` 作用域，OAuth 令牌也无法更改登录状态、密码或 MFA（多因素认证）状态。它也不能创建超出授权有效期的凭证，或请求删除账户。

通过 [无头登录（headless sign-in）](#无头模式登录用户) 获取的用户访问令牌也可以作为 Bearer 令牌使用，它代表该用户本人。

如果令牌缺失或无效，将返回 `401` 状态码，并附带 `WWW-Authenticate: Bearer` 标头。如果返回的 `401` 错误中包含 `code: "session_token_revoked"`，则表示该凭证已被撤销、已过期，或属于一个已关闭的会话。该令牌永远无法再次使用：请停止重试并获取新令牌。

相同的令牌也可用于访问项目的 Git 源（origin）。请参阅 [Git](#git版本控制)。

### 错误（Errors）

错误响应为 JSON 格式。每个响应体都包含 `error` 字段。通用错误结构还会包含 `message` 和 `status` 字段。类型化错误会包含 `code` 字段，并可能包含更多字段。

| 字段 (Field) | 类型 (Type) | 含义 (Meaning) |
|---|---|---|
| `error` | `true` 或文本 | 当为文本时，表示人类可读的错误原因。 |
| `message` | 文本 | 人类可读的错误原因。 |
| `code` | 文本 | 稳定的机器码。**请根据此字段进行逻辑分支判断，切勿依赖文本内容。** |
| `status` | 数字 | 重复输出的 HTTP 状态码。 |

某些错误会包含额外的字段。当请求体（body）、查询参数（query）或路径（path）验证失败时，会返回：

```json
{ "error": true, "message": "Validation failed", "status": 400, "issues": [ … ] }
```

`issues` 字段会列出每个无效字段的 `path`（路径）和 `message`（消息）。

| 状态码 (Status) | 含义 (Meaning) | 处理方法 (What to do) |
|---|---|---|
| `400` | 请求无效。 | 阅读 `issues` 或 `message`。修正请求内容。 |
| `401` | 没有有效的凭证。 | 发送有效的令牌。如果遇到 `session_token_revoked` 错误，请停止重试。 |
| `402` | 账户无法支付此费用，或其套餐不包含此功能。 | 阅读 `code` 字段：`insufficient_credits`（余额不足）、`subscription_required`（需要订阅）、`no_account`（无账户）、`entitlement_required`（需要授权）、`budget_exceeded`（超出预算）。计费相关的 `402` 错误（`insufficient_credits`、`subscription_required`、`no_account`）还会附带 `billing_state`、`balance` 和 `account_id` 字段。请根据 `billing_state` 进行逻辑分支判断，以决定是进行订阅还是充值。请参阅 [常见错误代码](#常见错误代码common-error-codes)。 |
| `403` | 凭证有效，但不允许执行该操作。 | 权限拒绝时会指明所需的 `action`（操作）和 `code`（代码）。`feature_disabled`（功能已禁用）错误会附带 `feature` 字段（标志键）。 |
| `404` | 对象不存在，或你无权查看。对于无权查看的对象，OpenChatly 会返回 `404` 而不是 `403`。 | 检查 ID 是否正确。检查你对该对象的访问权限。 |
| `409` | 请求与当前状态冲突。 | 阅读 `code`。重新加载对象并重新做出决定。 |
| `422` | 请求格式有效，但无法应用该操作。 | 阅读 `code`，例如 `CR_HEAD_NOT_AHEAD`。 |
| `429` | 触发速率限制。 | 等待 `Retry-After` 标头指定的秒数。请参阅 [重试与幂等性](#重试与幂等性retries-and-idempotency)。 |
| `500` | OpenChatly 内部缺陷。 | 不要陷入循环重试。请携带响应标头中的 `X-Request-Id` 报告此问题。 |
| `502`, `503`, `504` | 临时性故障。`503` 通常会附带 `Retry-After` 标头。 | 对读取操作进行重试。在重复写入操作前，请先检查状态。 |

每个响应都会携带 `X-Request-Id` 标头。在报告问题时请引用该 ID。

### 常见错误代码（Common error codes）

以下是客户端最常用作逻辑分支判断的代码。链接的章节对每种修复方法进行了说明。

| 错误代码 (`code`) | 状态码 (Status) | 原因 (Cause) | 修复参考 (Fix on) |
|---|---|---|---|
| `session_token_revoked` | `401` | 该凭证已永久失效，无法再次使用。 | [安全](/docs/zh/guide#安全性) |
| `insufficient_credits` | `402` | 账户的积分余额为空。 | [计费](/docs/zh/guide#计费billing) |
| `subscription_required` | `402` | 账户没有适用于 OpenChatly 计费使用的套餐。 | [计费](/docs/zh/guide#计费billing) |
| `no_account` | `402` | 账户尚未建立计费账户，设置未完成。 | [计费](/docs/zh/guide#计费billing) |
| `entitlement_required` | `402` | 套餐缺少 `sso`、`scim`、`rbac`、`auditAccess` 或 `branding` 权限。响应体会指明 `entitlement`。 | [安全](/docs/zh/guide#安全性) |
| `budget_exceeded` | `402` | 设置为阻断的模型预算已达到上限。 | [模型](/docs/zh/guide#模型models) |
| `feature_disabled` | `403` | 项目已关闭此功能标志。响应体会指明 `feature`。 | **项目管理** → **功能标志** |
| `feature_operator_only` | `403` | 仅 OpenChatly（平台管理员）可以更改此标志。 | 请联系平台管理员。 |
| `account_mfa_required` | `403` | 账户要求开启双重认证，但此次登录未使用。 | [安全](/docs/zh/guide#安全性) |
| `expiry_required`, `expiry_too_far` | `400` | 新密钥违反了账户的密钥规则。 | [安全](/docs/zh/guide#安全性) |
| `INVALID_IDEMPOTENCY_KEY` | `400` | `Idempotency-Key` 标头的长度不在 1 到 255 个字符之间，或包含非法字符（仅允许 `A-Z a-z 0-9 . _ : + / = -`）。 | [重试与幂等性](#重试与幂等性retries-and-idempotency) |
| `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_*_CONFLICT` | `409` | 该密钥正被另一个请求使用，或者当前请求的 `connector_bindings`、`secrets`、`runtime_context` 或 `provider_secret_pools` 与之前不同。 | [重试与幂等性](#重试与幂等性retries-and-idempotency) |
| `IDEMPOTENCY_KEY_SESSION_DELETED` | `409` | 该密钥所属的会话已被删除。 | 请使用新密钥。 |
| `INVALID_SESSION_RUNTIME_CONTEXT`, `INVALID_SESSION_CONNECTOR_BINDINGS`, `INVALID_SESSION_SECRETS` | `400` | 创建会话时的字段格式错误。 | [通过代码创建会话](#会话创建错误session-create-errors) |
| `session_not_deleted` | `409` | 恢复操作指定了一个未被删除的会话。 | [计算环境](/docs/zh/guide#计算机computers) |
| `session_sandbox_removal_pending` | `409` | 恢复操作发起时，提供商尚未确认已删除会话的沙盒已被移除；或者在删除时正在启动的沙盒可能仍在到达中。 | 请在一分钟后重试恢复操作。[计算环境](/docs/zh/guide#计算机computers) |
| `session_purged` | `410` | 该会话在 30 天前已被删除。其消息、文件和分支已被彻底清除。 | [计算环境](/docs/zh/guide#计算机computers) |
| `project_archived` | `404` | 项目已被删除。 | 请使用其他项目。 |
| `request_deadline` | `503` | 请求处理时间超过了 API 的 25 秒限制。 | 对读取操作进行重试。在重复写入操作前，请先检查状态。 |
| `git_mirror_unavailable` | `503` | 项目仓库暂时无法访问。 | 等待 `Retry-After` 标头指定的时间后重试。[Git](#git版本控制) |
| `repository_push_rejected` | `409` | 由于分支保护或仓库规则，Git 托管方拒绝了推送。 | [Git](#谁可以克隆和推送) |
| `CR_HEAD_NOT_AHEAD` | `422` | 变更请求分支没有领先于其基础分支的提交。 | [Git](#变更请求change-requests) |
| `CR_SELF_MERGE_REFUSED` | `403` | 会话试图在没有 `project.gitops.merge` 授权的情况下合并自己的变更请求。 | [Git](#变更请求change-requests) |
| `MANIFEST_INVALID` | `422` | 变更请求导致 `kortix.yaml` 无效。合并被阻止。`issues` 字段会列出错误详情。 | [kortix.yaml 参考手册](#kortixyaml-参考) |
| `PERSONAL_SECRET_REQUIRES_PRIVATE_SESSION` | `409` | 你试图分享一个包含“仅与你共享”的密钥的会话。 | [安全](/docs/zh/guide#安全性) |
| `project_secret_write_limit` | `429` | 项目在一小时内写入密钥的次数超过了 100 次。 | [安全](/docs/zh/guide#安全性) |
| `app_config_invalid` | `400` | 应用发布配置无效。`issues` 字段会列出错误详情。 | [应用参考](#应用参考apps-reference) |
| `app_auth_required` | `401` | 应用 URL 需要一个有权打开它的查看者。 | [应用访问](#应用访问app-access) |

连接器调用会在 `{ ok: false, status: "denied" | "error", reason }` 结构中使用 `reason` 字段（而不是 `code`）来报告结果。诸如 `connector_not_connected` 和 `policy_block` 等原因，请参阅 [连接器](/docs/zh/guide#连接器connectors)。LLM 提供商和模型的故障请参阅 [模型](/docs/zh/guide#模型models)。

### 重试与幂等性（Retries and idempotency）

SDK 会自动重试读取请求，以及没有收到响应的 `DELETE` 请求。它**永远不会**自动重试其他类型的写入请求。在你自己编写的客户端中，请根据响应情况自行决定：

| 响应情况 (Response) | 是否重试 (Retry) |
|---|---|
| `GET` 或 `HEAD` 请求返回 `502`、`503` 或 `504` | 是。如果存在 `Retry-After` 标头，请等待该时间后重试。SDK 会重试 2 次，分别在 250 毫秒和 500 毫秒后。 |
| 写入请求返回 `502`、`503` 或 `504` | 请先读取当前状态。 |
| 返回 `429` | 是。等待 `Retry-After` 指定的秒数。响应体会以 `retry_after_seconds` 字段重复说明等待时间。 |
| 写入请求无响应（网络故障） | 请先读取当前状态，或者在路由支持的情况下，使用相同的 `Idempotency-Key` 重新发送。 |
| 返回 `400`、`401`、`402`、`403`、`404`、`409`、`422` | 否。请先修改请求内容或当前状态。 |
| 返回 `500` | 否。请携带 `X-Request-Id` 报告此问题。 |

#### 幂等性密钥（Idempotency-Key）

以下两个创建路由支持通过幂等性密钥来对重试的请求进行去重：

| 路由 (Route) | 密钥传递位置 (Where the key goes) | 格式要求 (Format) |
|---|---|---|
| `POST /v1/projects/<project_id>/sessions`（启动会话） | `Idempotency-Key` 标头 | 1 到 255 个字符，仅允许 `A-Z a-z 0-9 . _ : + / = -` |
| `POST /v1/projects/provision`（使用新仓库创建项目） | 请求体中的 `idempotency_key` 字段 | 最多 200 个字符，仅允许 `A-Z a-z 0-9 . _ : -` |

针对每个意图（intent），请发送一个新的随机值（例如 UUID）。在重试该意图时，请发送相同的值。重复的会话创建请求会返回原始会话，而不会启动第二个沙盒。

会话密钥在整个 OpenChatly 平台中是全局唯一的。如果某个密钥已被其他项目或账户使用，将返回 `409` `IDEMPOTENCY_KEY_CONFLICT` 错误。

#### 分页（Pagination）

支持分页的列表路由接受 `limit` 和 `cursor` 参数。请将返回的下一个游标作为 `cursor` 传回。如果没有返回下一个游标，则表示你已经获取了最后一页。

| 列表路由 (List) | 下一个游标 (Next cursor) | `limit` 限制 |
|---|---|---|
| `GET /v1/projects/<project_id>/sessions` | 响应标头中的 `X-Next-Cursor` | 默认 50，最大 200 |
| `GET /v1/accounts/<account_id>/audit` | 响应体中的 `next_cursor` | 默认 50，最大 200 |
| `GET /v1/projects/<project_id>/files?depth=1` | 响应体中的 `next_cursor` | 默认 500，最大 2,000。如果不传 `limit` 或 `cursor`：单次响应最多返回 5,000 条记录 |

会话分页列表仅包含你有权打开的会话。除最后一页外，每一页都严格包含 `limit` 指定数量的会话。删除某个会话不会改变列表中其他会话的顺序。

会话列表还会返回一个 `ETag`。将其作为 `If-None-Match` 标头传回，如果列表未发生变化，接口会返回 `304` 且不带响应体。

#### 速率限制（Rate limits）

API 边缘预算（edge budgets）会在每个响应中返回 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset`（距离窗口重置的剩余秒数）。当预算耗尽时，API 会返回 `429` 状态码，并附带 `Retry-After` 标头和以下响应体：

```json
{ "error": "rate_limit_exceeded", "retry_after_seconds": 12 }
```


| 路由 (Route) | 限制 (Limit) |
|---|---|
| `/v1` 下的所有 API 路由（不包括下方列出的健康检查端点和公共认证系列） | 每个客户端地址、每个 API 副本每分钟 300 次请求；每 200 毫秒补充一个令牌。 |
| 公共认证系列：`/v1/auth`、`/v1/oauth`、`/v1/access`、`/v1/tunnel/device-auth` | 在验证和认证之前，每个客户端地址、每个 API 副本拥有独立的共享预算：每分钟 30 次请求。 |
| 沙盒代理：`/v1/p/<external_id>/<port>/*`（预览和会话运行时） | 每个沙盒每分钟 600 次请求。 |
| 单个项目中的密钥写入 | 每小时 100 次，错误代码为 `code: "project_secret_write_limit"`。 |

边缘预算（edge budgets）也会将**被拒绝的请求**计算在内。`OPTIONS` 请求、`/v1/health`、`/v1/health/live` 和 `/v1/health/ready` 端点可豁免此限制；此外，未携带边缘转发标头的请求由于没有客户端地址，同样不受此限制。这些预算旨在防止滥用。它们不是账户配额，且每个 API 副本独立计算，因此包含多个副本的部署可以接受各预算的倍数请求。

### 参考文档未涵盖的内容（What the reference does not cover）

参考文档中未列出会话运行时（session runtime）路由。以下接入方式需要使用不同的凭证或协议，而非普通的 Bearer 令牌调用：

| 接入方式 (Surface) | 替代方案 (Use instead) |
|---|---|
| 会话运行时：`/v1/p/<external_id>/8000/kortix/runtime/*`（包括提示词、事件流、文件和运行中会话的对话记录）。路径中使用的是提供商处的沙盒外部 ID，而不是 `session_id`。你可以从 `kortix sessions info <session_id> --json` 的 `sandbox_url`（`/v1/p/` 之后的部分）或 SDK `ensureReady()` 返回的 `sandboxId` 中获取。 | 使用 SDK 的会话句柄：`kortix.session(projectId, sessionId)`。请参阅 [通过代码创建会话](#从代码管理会话)。 |
| SCIM 2.0：`/scim/v2/accounts/<account_id>`。需要使用 `kortix_scim_` 令牌，而非个人访问密钥。 | [单点登录与目录同步](/docs/zh/guide#单点登录与目录同步) |
| 入站触发器 Webhooks：`POST /v1/webhooks/projects/<project_id>/<slug>`。使用触发器密钥进行认证，而非 OpenChatly 令牌：需发送 HMAC 签名（`X-Kortix-Signature` 或 `X-Hub-Signature-256`）、`X-Kortix-Token` 或 `Authorization: Bearer <secret>`。 | [Webhooks](/docs/zh/guide#触发器triggers) |
| 应用事件与应用运行：`POST …/apps/<app_id>/events`，`POST` 和 `DELETE …/apps/<app_id>/runs`。需要使用应用的 `KORTIX_APP_TOKEN`，而非 OpenChatly 令牌。 | [应用事件](/docs/zh/guide#触发器triggers) |
| LLM 网关的 OpenAI 和 Anthropic 兼容端点。需要使用 `kortix_gw_` 密钥。 | [从你自己的应用调用 LLM 网关](#从你自己的应用调用-llm-网关call-the-llm-gateway-from-your-own-app) |
| 项目 Git 源：`https://api.kortix.com/v1/git/<project_id>.git`。 | [Git](#git版本控制) |

### 机器可读文档（Machine-readable docs）

这些文档也以纯 Markdown 格式发布，供编码智能体和 LLM 工具使用：

| URL | 内容 (Content) |
|---|---|
| `https://kortix.com/llms.txt` | 所有公开页面（含文档）的索引，附带指向其 Markdown 版本的链接。 |
| `https://kortix.com/llms-full.txt` | 包含所有公开页面的单个文件。 |
| `https://kortix.com/markdown/docs/<path>.md` | 单个页面。例如，本文档的 Markdown 路径为 `/markdown/docs/index.md`。 |
| 任何 `/docs/<path>` URL，请求时附带 `Accept: text/markdown` 标头 | 与上述相同的页面，以 Markdown 格式返回。 |

你可以将编码智能体指向 `https://kortix.com/llms.txt` 以获取概念说明，指向 `https://api.kortix.com/v1/openapi.json` 以获取精确的路由信息。使用 [OpenChatly MCP server](/docs/zh/guide#其他-ai-工具mcp) 的 MCP 客户端会通过 `search_api` 和 `describe_api` 自行读取路由参考文档。

### 从你自己的应用调用 LLM 网关（Call the LLM gateway from your own app）

<a id="use-the-gateway-from-your-own-tools" />

LLM 网关将项目的模型提供给你的自有代码使用，它与会话使用相同的提供商、路由、备用模型和预算机制。你的应用可以使用网关密钥，通过 OpenAI 或 Anthropic 兼容的端点来调用它。

1. **创建网关密钥（Create a gateway key）**

    打开 **Customize（自定义）** → **Models（模型）** → **Gateway（网关）** 并创建一个密钥，或者运行 `kortix gateway keys new <name>`。该密钥以 `kortix_gw_` 开头，仅属于单个项目，且**仅显示一次**。请将其存储为 `KORTIX_GATEWAY_KEY`。

2. **将你的 SDK 或客户端指向网关（Point your SDK or client at the gateway）**

    在 OpenChatly Cloud 上，基础 URL 为 `https://gateway.kortix.com`。**Gateway（网关）** 标签页会显示你所在实例的 URL。如果使用 OpenAI SDK，请将 `base_url` 设置为 `https://gateway.kortix.com/v1`。如果使用 Anthropic SDK，请将 `base_url` 设置为 `https://gateway.kortix.com`。

| 端点 (Endpoint) | 方法与路径 (Method and path) |
| --- | --- |
| OpenAI 兼容的聊天补全 | `POST /v1/chat/completions` |
| Anthropic 兼容的消息 | `POST /v1/messages` |
| 获取该项目可用的模型 | `GET /v1/models` |

```sh
curl https://gateway.kortix.com/v1/chat/completions \
  -H "Authorization: Bearer $KORTIX_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

模型 ID 的格式为 `<provider>/<model>`（即 `<提供商>/<模型>`）。`GET /v1/models` 会列出项目提供商所支持的模型 ID。网关密钥仅能访问其所属项目的网关推理路由：REST API 会拒绝该密钥的其他请求。使用 `kortix gateway keys ls` 可列出所有密钥，使用 `kortix gateway keys rm <keyId>` 可撤销某个密钥。`kortix gateway usage` 和 `kortix gateway logs` 命令用于查看请求记录、错误和费用。

## 应用参考（Apps reference）

App（应用）是由单个项目拥有并由 OpenChatly 托管的网站、内部工具或后端服务。它拥有一个稳定的 URL、一套访问策略以及带版本号的发布版本。在请求到达你的代码之前，OpenChatly 会负责完成访客的登录认证。

### 什么是 App（What an App is）

App 分为静态应用和服务器应用。静态应用由 OpenChatly 直接提供文件服务，无需运行机器。服务器应用则运行由 OpenChatly 根据你的源代码或镜像构建的机器。

| 组成部分 (Part) | 说明 (What it is) |
|---|---|
| 发布版本 (Release) | `vN`：一个产物（文件、构建结果或 OCI 镜像）加上其解析后的配置。发布版本一旦生成便不可更改。失败的发布版本永远不会替换线上的流量。回滚操作本质上是一个新的发布版本。 |
| 进程组 (Process group) | 一个命名命令。如果没有配置 `processes`，服务器应用会默认拥有一个名为 `app` 的进程组。 |
| 机器 (Machine) | 运行线上发布版本的某个进程组。其 `machine_id` 在不同发布版本间保持不变。每个发布版本都会替换其根磁盘。 |
| 服务 (Service) | 进程组中一个命名的 HTTP 端口。每个服务都有自己独立的主机名和 `access`（访问策略）。 |
| 卷 (Volume) | 由某台机器挂载的持久化磁盘。它的生命周期长于任何发布版本和机器。 |
| 标签 (Label) | 自由格式的标记，例如 `backend`。标签不会触发任何特定行为。 |

数据库、消息队列或任何其他后端服务，都可以被视为一个带有卷的服务器应用。模板可以为你生成现成的 App，请参阅 [模板：Convex 后端](#模板convex-后端template-convex-backend)。

每个 App 都会在 `capabilities`（能力）字段中列出其支持的功能，例如 `machines`（机器）或 `volumes`（卷）。如果调用的功能需要但 App 缺少相应的能力，接口会返回 `409 app_capability_unsupported` 错误。

### 展示托管在其他地方的应用（Show an App hosted elsewhere）

外部应用（external App）是指运行在其他地方的网站，例如仪表盘、供应商工具或其他团队的服务。OpenChatly 会在 Apps 页面中将其与自身托管的应用并列显示，并在内嵌框架中原地打开它。OpenChatly 永远不会部署、唤醒或对其计费，它也不占用 App 的配额槽位。

通过 CLI 添加一个外部应用：

```bash
kortix apps create grafana --name "Grafana" --url https://grafana.example.com
```

- URL 必须使用 `https` 协议。包含用户名或密码的 URL 会被拒绝。
- App 的 `url` 和 `external_url` 指向该网站。其 `capabilities`（能力）为 `["preview"]`。
- 网站自身决定是否允许被嵌入框架（iframe）。当你添加该应用时，OpenChatly 会读取其 `X-Frame-Options` 和 CSP（内容安全策略）的 `frame-ancestors` 标头。如果网站拒绝被嵌入，其 `capabilities` 将变为 `[]`，并附带警告信息 `app_external_not_frameable`。此时，OpenChatly 会显示一个 **Open in a new tab（在新标签页中打开）** 控件，而不是使用框架嵌入。
- 如果网站使用 Cookie 维持登录状态，由于浏览器限制了跨站框架中的 Cookie，它可能会要求你在框架内重新登录。遇到这种情况时，请在新标签页中打开该网站。
- 访问策略（access policy）决定项目中的哪些人可以**看到**该 App；而网站自身的登录机制决定哪些人可以**使用**它。
- 使用 `kortix apps set grafana --url <https-url>` 可以将其更改为其他 URL。
- 对外部应用执行部署（deploy）、回滚（rollback）、启动（start）、停止（stop）以及获取登录令牌等操作，均会返回 `409 app_capability_unsupported` 错误。

### 自托管前置要求（Self-hosting prerequisites）

在自托管实例上，只有在运维人员设置了 Apps 基础域名及其泛域名 DNS 记录后，App 的主机名才能正确解析。请参阅 [自托管](#应用托管app-hosting)。

### 部署你的第一个应用（Deploy your first App）

1. **构建网站（Build the site）**

    ```bash
    npm run build
    ```

2. **部署输出目录（Deploy the output directory）**

    ```bash
    kortix apps deploy dist --slug my-site --type static --spa
    ```
    该命令会创建 App、上传文件，并等待 URL 准备就绪，最后会打印出该 URL。如果不指定 `--slug`，系统会默认使用目录名作为 slug。

3. **打开应用（Open it）**

    新创建的 App 默认为 `private`（私有）：只有你自己可以打开它。请在已登录 OpenChatly 的浏览器中打开该 URL，或者生成一个有效期为 5 分钟的登录链接：
    ```bash
    kortix apps access-link my-site
    ```

4. **发布后续版本（Ship the next release）**

    ```bash
    npm run build && kortix apps deploy dist --app my-site
    ```
    对于后续的每次发布，请务必使用 `--app`（或在 `kortix.yaml` 中进行配置）。如果不指定，CLI 会尝试创建一个新 App；如果该 slug 已存在，则会返回 `409` 错误。

新创建的应用默认不会显示在 **Apps（应用）** 页面上，而是位于 **Background（后台）** 分类下。在部署时添加 `--listed` 参数，可以为网站或 UI 生成一张展示卡片（请参阅 [应用显示位置](#应用显示位置where-an-app-shows)）。

Web 界面会在项目侧边栏的 **Apps**（`/projects/<id>/apps`）中列出你有权打开的所有应用。该页面会显示应用的实时状态、预览以及访问控制。应用的详情页会列出其所有的发布版本。如果是服务器应用，会额外增加一个 **Machines（机器）** 标签页；如果应用带有卷（Volume），则会增加一个 **Volumes（卷）** 标签页。在 URL 中添加 `?app=<app_id>` 可以直接打开某个应用的详情页。你可以通过 CLI、SDK 或智能体会话来创建和部署应用。

### 部署源（Sources）

| 部署源 (Source) | 你部署的内容 (You deploy) | OpenChatly 的处理方式 (OpenChatly) |
|---|---|---|
| `static` | 文件：HTML、已构建的 SPA 或 `dist/` 目录 | 直接提供文件服务。无需机器，无冷启动。 |
| `bundle` | 包源代码 | 运行安装和构建命令，然后在机器上提供输出目录的服务。 |
| `dockerfile` | 包含 Dockerfile 的目录 | 构建镜像，然后在指定端口运行 `--command`。 |
| `oci_image` | 公共镜像引用（`--image`） | 在指定端口运行 `--command`。 |

- 对于所有可以提前构建的 UI，请选择 `static`。在本地构建后直接部署输出目录。例如，配置了 `output: 'export'` 的 Next.js 网站，可以将 `out/` 目录作为 `static` 部署。
- 对于需要服务端渲染（SSR）、原生包或任何其他服务，请选择 `dockerfile`。
- `dockerfile` 和 `oci_image` 需要指定 `--command`（推荐使用明确的 JSON argv 数组格式）和 `--port`，或者在 `kortix.yaml` 中配置 `http_service.internal_port`。纯后台任务应用（只有 `processes` 没有 service）不需要指定端口。

对于目录部署，如果省略 `--type`，CLI 会自动推断源类型：包含 `Dockerfile` 则推断为 `dockerfile`；否则包含 `package.json` 则推断为 `bundle`；否则推断为 `static`。默认配置如下：

| 设置项 (Setting) | `static` | `bundle` |
|---|---|---|
| 安装命令 (Install command) | — | `corepack enable && pnpm install --frozen-lockfile` |
| 构建命令 (Build command) | — | `pnpm build` |
| 输出目录 (Output directory) | — | `dist` |
| SPA 回退 (`--spa`) | 关闭 | 开启 |
| 就绪检查路径 (Readiness path) | `/` | `/` |

CLI 上传规则：
- 遵守 `.gitignore`、`.dockerignore` 和 `.kortixignore` 规则。
- 永远不会上传 `.git/`、`.kortix/` 或 `.env*` 文件。除非你显式传递 `--include-node-modules` 参数，否则也会排除 `node_modules`。
- 构建时的环境变量（例如 `.env.production` 中的 `VITE_*`）只能通过你在部署前手动运行的构建过程注入到静态应用中。

限制（Limits）：

| 限制项 (Limit) | 值 (Value) |
|---|---|
| 压缩包大小（压缩后） | 50 MiB |
| 压缩包大小（解压后） | 1 GiB |
| 压缩包内文件数量 | 100,000 |
| 静态应用文件数量 | 20,000 个，单个文件最大 50 MiB。超出限制的较大网站会报 `invalid_site` 错误。 |

静态应用不运行代码，因此会忽略 `env` 和 `secrets`。如果在部署时设置了这些变量，系统会记录一个 `environment_ignored`（环境变量已忽略）事件。

部署过程会依次经历 `queued`（排队中）、`validating`（验证中）、`building`（构建中）、`provisioning`（资源准备中）、`checking`（检查中）和 `ready`（就绪）状态，或者以 `failed`（失败）或 `cancelled`（已取消）结束。`kortix apps deploy` 命令最多等待 `--wait-seconds` 指定的时间（默认 `1200` 秒）。使用 `--no-wait` 参数可以在部署进入排队状态后立即返回。

### 在 kortix.yaml 中进行配置

`kortix.yaml` 中的 `apps.<slug>` 代码块用于保存应用的部署设置和发布版本配置。将其提交到代码仓库后，后续的每次部署都会使用这些相同的设置。

```yaml
apps:
  docs:
    path: docs/dist
    type: static
    spa: true
  api:
    path: services/api
    type: dockerfile
    command: ["node", "server.js"]
    labels: [backend]
    display: { preview: none }     # 图标卡片，而非实时预览缩略图
    always_on: true
    uses: [docs]
    processes:
      app: ""                      # "" 表示运行该代码块的 command
      worker: "node worker.js"     # 没有任何 service 引用它：即一个后台 worker
    http_service:
      internal_port: 3000
      access: app                  # public（公开） | app（应用内） | admins（仅管理员）
      processes: [app]
      checks: [{ type: http, path: /health }]
    services:
      - { name: admin, internal_port: 3001, access: admins }
    mounts:
      - { source: data, destination: /data, initial_size_gb: 10, processes: [app] }
    vm:
      - { cpu: 1, memory_gb: 2 }
      - { cpu: 1, memory_gb: 1, processes: [worker] }
    deploy:
      release_command: "node migrate.js"
    env:
      PUBLIC_BASE_URL: https://example.com
    secrets:
      API_TOKEN: api_token         # 运行时名称：项目密钥（secret）的标识符
```


| 字段 (Field) | 含义 (Meaning) |
|---|---|
| `path`, `type`, `image`, `dockerfile`, `command`, `root`, `output_dir`, `install_command`, `build_command`, `spa` | 部署源配置。`type` 的值为 `static`、`bundle`、`dockerfile` 或 `oci_image`。`command` 是镜像的启动参数（argv）。所有路径均相对于 `kortix.yaml` 文件。 |
| `port`, `readiness_path` | `http_service.internal_port` 和单一 HTTP 检查的简写形式。 |
| `always_on`, `idle_timeout_seconds`, `resources` | 运行模式，以及应用的默认机器规格（`cpu`、`memory_gb`、`disk_gb`）。 |
| `env`, `secrets` | 运行时环境变量，以及映射到项目密钥标识符的运行时名称。部署时仅从此代码块读取这两项配置。 |
| `uses` | 该应用依赖的其他应用。每次部署时，此列表会覆盖应用原有的依赖列表。应用不能依赖自身。 |
| `labels` | 最多 10 个标签，仅允许小写字母、数字和 `-`（正则：`^[a-z0-9][a-z0-9-]{0,30}$`）。 |
| `display` | 控制 OpenChatly 在哪里展示该应用。仅影响展示效果。请参阅 [应用显示位置](#应用显示位置where-an-app-shows)。 |
| `processes`, `http_service`, `services`, `mounts`, `vm`, `deploy` | 发布版本配置。详见后续章节。 |

**规则：**

- 不带参数运行 `kortix apps deploy` 时，会部署所有包含 `path` 或 `image` 的代码块：部署顺序为先部署其所依赖的应用，然后按应用名称排序。它会跳过其他不包含路径或镜像的代码块。
- `kortix apps deploy <path>` 会部署 `path` 为该路径的代码块。`--manifest-app <slug>` 用于指定代码块。通过命令行标志传入的参数优先级高于代码块中的配置。
- `kortix validate` 会应用 API 的发布版本配置规则。如果配置无效，API 会返回 `400 app_config_invalid` 以及 `issues: [{ path, message }]`。系统会在部署时检查机器规格，请参阅 [运行模式、机器与扩缩容](#运行模式机器与扩缩容run-mode-machines-and-scale)。
- 任何未定义的键都会报错。`backends` 是一个错误键：请在 `uses` 中列出依赖的应用。`kind` 会被忽略，并附带警告。
- 静态应用会忽略运行模式、机器规格、`env`、`secrets` 以及发布版本配置。

#### 应用显示位置（Where an App shows）

`display` 决定了应用在 **Apps（应用）** 页面上的显示位置。它永远不会改变应用的运行方式或访问权限。只有注册为 `listed: true` 的应用才会在网格中显示卡片。其他所有应用（如轮询器、机器人、后端服务）都会位于网格下方的 **Background（后台）** 列表中。

后台列表的每一行会显示应用的状态、运行方式、触发器以及最近的活动。打开一个后台应用，可以看到它的功能：运行方式、触发器以及由其 [事件](/docs/zh/guide#触发器triggers) 启动的智能体。在 Web 界面中，通过 **Settings → Show on Apps page（设置 → 在应用页面显示）** 可以在网格和列表之间移动应用。与 `kortix.yaml` 可以声明的其他应用设置一样，该开关会将 `display.listed` 提交到 `kortix.yaml` 的 `apps.<slug>` 中；推送包含该修改的代码无需进行部署即可生效。

| 键 (Key) | 默认值 (Default) | 效果 (Effect) |
|---|---|---|
| `listed` | `false` | 设为 `true` 会在网格中为该应用生成一张卡片。`kortix apps deploy --listed` 和 `kortix apps set <app> --listed` 可设置此项；`--unlisted` 可取消设置。外部应用（`--url`）默认从一开始就是 `listed` 状态。 |
| `preview` | `live` | `live` 会在卡片上以框架形式嵌入应用。`none` 则仅显示图标。对于根页面不是面向用户的（如 API 或后端服务），请使用 `none`。 |
| `parent` | 无 | `parent: <slug>` 会使该应用成为目标应用详情页中的一个标签页，且没有自己的独立卡片。标签页的名称会自动去除 `<parent>-` 前缀：例如 `backend-dashboard` 会显示为 **Dashboard**。如果指定的父应用不存在，该应用仍会作为卡片显示。 |
| `space`, `agent` | 无 | 将应用分组到某个空间（`spaces` 键）或智能体下。这仅用于分组，不会授予任何权限。请参阅 [kortix.yaml 参考手册](#kortixyaml-参考)。 |

配置了 `preview: none` 的应用会在其第一个标签页中打开。部署时，如果代码块声明了 `display`，系统会写入该配置；如果缺少 `display`，则保留应用现有的配置。`kortix apps show` 命令会在 `shown` 行打印出该配置。

使用 `PATCH /v1/projects/<project_id>/apps/<app_id>` 并传入 `display` 会整体替换该配置，传入 `{}` 则会恢复为默认值。如果包含未知键（有效键仅为 `listed`、`preview`、`parent`、`space` 和 `agent`）、`preview` 的值不是 `live` 或 `none`，或者 `parent` 格式错误，接口会返回 `400` 错误。

> **Warning**
>
> 切勿在 `kortix.yaml` 中放置访问设置、密码或成员 ID。请使用 `kortix apps access` 命令进行设置。请参阅 [应用访问](#应用访问app-access)。

完整的 `kortix.yaml` 参考手册请参阅 [kortix.yaml 参考手册](#kortixyaml-参考)。

### 进程、服务与健康检查（Processes, services and checks）

以下设置仅适用于服务器应用。

- **进程组（Process groups）。** `processes` 将组名映射到 Shell 命令。`""` 表示运行应用的 `command`。组名必须以小写字母开头，且仅允许小写字母、数字、`-` 或 `_`。
- **主服务（Primary service）。** `http_service` 在应用自身的主机上响应请求。其字段包括：`internal_port`、`access`、`auto_stop_machines`（`off`、`stop`、`suspend`；其中 `suspend` 的行为与 `stop` 相同）、`auto_start_machines`、`min_machines_running`（0–100）、`processes`、`checks`。
- **其他服务（More services）。** `services` 最多可列出 10 个额外的 HTTP 服务，格式为 `{ name, internal_port, access, processes, checks }`。每个服务在 `<app host>--<name>` 主机上响应。`http` 是主服务的保留名称。
- **后台任务（Workers）。** 没有被任何服务引用的进程组即为后台任务（Worker）。它会持续运行，且永远不会因空闲而停止。
- **端口（Ports）。** `internal_port` 的范围是 1–65535。端口 `7331` 和 `8080` 属于应用主管进程（App supervisor），会被拒绝。两个服务不能共享同一个端口。
- **仅限 HTTP（HTTP only）。** 配置了 `protocol: tcp` 的服务会被拒绝。应用不支持 TCP 服务，且应用之间没有私有网络。

服务的 `access` 字段控制对服务主机的访问权限：

| `access` 值 | 允许访问的对象 |
|---|---|
| `public` | 任何人。服务需自行检查登录状态。 |
| `app`（默认） | 应用访问策略允许的任何用户。 |
| `admins` | 应用策略允许且持有 `project.app.admin` 权限的用户。其他用户会收到 `403 app_service_admins_only` 错误。 |

**健康检查（Checks）** 在机器内部运行。只有当所有新机器的所有检查都通过时，发布版本才会正式上线。

| 检查字段 (Check field) | 默认值 (Default) | 限制范围 (Bounds) |
|---|---|---|
| `type` | 如果设置了 `path` 则为 `http`，否则为 `tcp` | `http`, `tcp` |
| `path` | `/` | 必须以 `/` 开头 |
| `interval_s` | 15 | 1–3600 |
| `timeout_s` | 5 | 1–600 |
| `grace_period_s` | 10 | 0–3600 |

**部署策略** (`deploy.strategy`)：

| 策略 (Strategy) | 执行过程 (What happens) | 默认启用条件 (Default when) |
|---|---|---|
| `bluegreen`（蓝绿部署） | 新机器启动并通过健康检查后，流量才会切换。无停机时间。 | 发布版本没有挂载卷（mount）时 |
| `rolling`（滚动更新） | 每次替换一台机器。卷（volume）会从旧机器迁移到新机器。会有几秒钟的停机时间。 | 发布版本包含挂载卷时 |
| `immediate`（立即替换） | 立即同时替换所有机器，不等待健康检查。 | — |
| `canary`（金丝雀发布） | 先启动一台新机器。当其健康后，再滚动更新其余机器。 | — |

包含挂载卷的发布会拒绝 `bluegreen` 和 `canary` 策略：因为它们会导致两台机器同时挂载同一个卷。如果发布版本始终无法通过健康检查，该发布将被放弃，流量会保留在上一版本上。

`deploy.release_command`（最多 2000 个字符）在每个发布版本中仅运行一次，且在任何机器变更之前执行。它会在一个临时机器中运行，使用新镜像、`env`（环境变量）和 `secrets`（密钥），但不包含卷。如果返回非零退出码，发布会以 `release_command_failed` 失败，且不会进行任何变更。此命令通常用于执行应用外部数据库的迁移。

### 运行模式、机器与扩缩容（Run mode, machines and scale）

服务器应用以以下两种模式之一运行：

| 模式 (Mode) | 行为 (Behavior) | 适用场景 (Use it for) |
|---|---|---|
| 始终运行 (`--always-on`) | 7×24 小时运行。OpenChatly 每 5 分钟检查一次，若应用停止则自动重启。 | WebSockets、后台循环任务、数据库 |
| 按需运行 (`--on-demand`) | 在 `idle_timeout_seconds` 内无请求则停止。下一次请求或调用该应用的触发器会将其唤醒。停止时会保留磁盘数据，但内存数据会丢失。 | 仅响应请求的应用、由定时任务调用的轮询器 |

新创建的应用默认为“始终运行”模式。可使用 `kortix apps set <app> --always-on` 或 `--on-demand` 更改模式，也可以在 `kortix.yaml` 中配置 `always_on`。模式更改会在 5 分钟内生效，无需重新部署。静态应用没有运行时，会忽略运行模式配置。

机器规格：

| 设置项 (Setting) | 默认值 (Default) | 限制范围 (Bounds) |
|---|---|---|
| `cpu` | 1 | 1–32 |
| `memory_gb` | 2 | 1–128 |
| `disk_gb` | 10 | 1–500 |
| `idle_timeout_seconds` | 300 | 120–86400。仅适用于“按需运行”模式。 |

超出限制范围的值会返回 `400 app_machine_out_of_range` 错误。OpenChatly 永远不会自动截断或限制该值。应用的规格设置是所有进程组的默认规格。

发布版本中的 `vm` 条目用于单独指定某个进程组的规格。规格变更会在下一次发布时生效。

```bash
kortix apps machines api                          # 查看机器列表：id（机器ID）、group（进程组）、state（状态）、release（发布版本）、size（规格）、volume（挂载卷）
kortix apps machines restart api <machine>        # 重启指定机器（也支持 start 启动、stop 停止、destroy 销毁操作）
kortix apps scale count api 3 --process worker    # 设置扩缩容数量：每个进程组可设置 0-20 台机器
kortix apps scale show api                        # 查看当前应用的扩缩容配置
kortix apps exec api -- node scripts/report.js    # 在机器中执行单条命令
```

- 每个进程组默认运行 1 台机器。`scale count` 可为每个进程组设置 0–20 台机器，并在后台自动应用。
- 带有挂载卷（mount）的进程组只能运行 1 台机器。如果 `scale count` 设置大于 1，会返回 `409 volume_single_machine` 错误，因为第二台机器会获得一个全新的空卷，导致在同一个 URL 下提供不同的数据。如果需要扩展数据库，请使用纵向扩容：`kortix apps set <app> --cpu <n> --memory-gb <n>`，然后进行部署（会有几秒钟的停机时间，但不会丢失数据）。使用 `--new-volumes` 参数可以接受独立卷，适用于能够自行复制数据的软件。
- 销毁一台机器会保留其卷。该进程组运行的机器数量会减少一台。
- `kortix apps stop` 会立即暂停服务器应用。下一次经过授权的请求会将其唤醒。`kortix apps start` 会在流量到达前提前唤醒应用。静态应用对这两个命令都会返回 `409 static_app_no_runtime` 错误。
- `exec` 命令需要 `project.app.admin` 权限，且会被审计。它接受 1–256 个单词组成的启动参数（argv），并在当前线上发布版本的运行中机器上执行（或通过 `--machine <id>` 指定机器）。命令会在 `--timeout` 秒后超时（范围 1–300，默认 60 秒）。标准输出（stdout）和标准错误（stderr）各自最多返回 1 MiB 的数据。CLI 会以该命令的退出码作为自身的退出码。如果目标机器处于停止状态，会返回 `409 machine_not_running` 错误。

**账户限制（Account limits）：**

| 错误代码 (Code) | HTTP 状态码 | 含义 (Meaning) |
|---|---|---|
| `app_quota_exceeded` | 402 | 账户已达到应用数量上限。外部应用（external App）不占用配额。 |
| `app_concurrency_limit` | 429 | 账户同时运行的应用数量已达上限。 |
| `subscription_required`, `insufficient_credits`, `plan_upgrade_required` | 402 | 账户无法启动计算资源。此时访问该应用 URL 的访客会收到 `app_account_unfunded` 错误。 |

没有计费系统的自托管实例不受上述任何限制。

### 卷与快照（Volumes and snapshots）

卷是一种 Platinum（铂金）级别的存储卷，与机器的根磁盘完全独立。它通过发布版本配置中的 `mounts` 条目来进行声明。

```yaml
mounts:
  - { source: data, destination: /data, initial_size_gb: 10, snapshot_retention_days: 5 }
```

- `source` 为卷的名称：长度为 1–30 个字符，仅允许使用小写字母、数字或 `_`。
- `destination` 必须是绝对路径。不能为 `/`，不能以 `/` 结尾，也不能位于 `/bin`、`/boot`、`/dev`、`/etc`、`/lib`、`/lib64`、`/proc`、`/root`、`/run`、`/sbin`、`/sys`、`/usr`、`/var` 或 `/kortix` 目录下。建议使用 `/data`。
- `initial_size_gb`（1–100）代表应用所需的容量。Platinum 存储为每个卷分配固定的大小（目前为 100 GB），且卷无法扩容（若尝试扩容会返回 `400 volume_fixed_size` 错误）。请将可能超出此限制的持久化文件（如上传文件和文档）存放在对象存储中。
- `kortix apps volumes` 命令会显示每个卷的使用情况和大小，数据直接从 Platinum 存储实时读取。请在使用量达到上限前规划向对象存储的迁移：当卷写满时，所有写入操作都会失败。
- 同一时间只能有一台机器对卷进行写入操作，且一台机器最多只能挂载一个卷。OpenChatly 会强制执行单写者锁（single-writer lock）。
- 卷的生命周期独立于所有发布版本。回滚操作只会更改代码和配置，绝不会更改卷中的数据。

```bash
kortix apps volumes backend                             # 查看卷信息：name（名称）、group（进程组）、used（已用空间）、size（总大小）、attached machine（绑定的机器）、retention（保留策略）
kortix apps volumes create backend data --size 10 --process app  # 创建卷
kortix apps volumes set backend data --retention 30     # 设置快照保留策略：每日快照保留 30 天
kortix apps volumes snapshots backend data              # 查看快照列表：包含每日自动快照、手动快照和最终快照
kortix apps volumes snapshot backend data               # 立即创建一个手动快照
kortix apps volumes restore backend data <snapshot>     # 从快照恢复卷（需要 project.app.admin 权限）
kortix apps volumes fork backend data data_copy         # 复制卷（添加 --snapshot <id> 参数可从指定快照复制）
kortix apps volumes destroy backend data --yes          # 销毁卷（需要 project.app.admin 权限）
```

| 操作 (Operation) | 作用 (What it does) |
|---|---|
| 每日快照 (Daily snapshot) | OpenChatly 每天为每个卷创建一个快照。`daily`（每日）和 `manual`（手动）快照会保留 `snapshot_retention_days` 指定的天数（范围 1–60，默认 5 天）。 |
| `snapshot`（创建快照） | 创建一个 `manual`（手动）快照。OpenChatly 会先提交当前挂载的卷（形成一个冻结的时间点），然后固定该提交。每日快照的生成机制与此相同。 |
| `restore`（恢复） | 机器会停止，卷的内容会回退到快照状态，随后机器基于该卷重新启动。被替换掉的内容仍会保留在卷的历史记录中。 |
| `fork`（复制/分叉） | 在同一应用内创建一个全新的、未挂载的卷。该卷会基于当前卷的内容或指定的快照瞬间生成。 |
| `create`（创建卷） | 提前创建一个卷。该进程组中下一个带有同名挂载配置的机器将会自动接管该卷。 |
| `destroy`（销毁） | 销毁时需要提供卷的名称作为确认（不提供会返回 `400 confirmation_required` 错误）。如果机器正在挂载该卷，销毁会被拒绝并返回 `409 volume_attached` 错误。OpenChatly 会保留一个 `final`（最终）快照 7 天，之后彻底清除数据。 |

### 应用访问（App access）

访问模式（Access mode）决定了谁可以打开某个应用。它不会授予任何被用户角色所拒绝的权限。

| 模式 (Mode) | 可以打开应用的用户 |
|---|---|
| `private`（私有，默认） | 创建者 |
| `project`（项目内） | 所有可以读取该项目的人员 |
| `restricted`（受限） | 你列出的成员和群组（每种最多 100 个，且至少需要指定一个） |
| `public`（公开） | 任何人。无需登录。 |
| `password`（密码保护） | 任何知道密码的人（密码长度 8–256 个字符） |

项目管理员、账户所有者和账户管理员可以查看并打开项目中的每一个应用，因此即使是私有应用，在创建者离开后依然可以被正常管理。

```bash
kortix apps deploy dist --app my-site --access project
kortix apps access my-site --mode restricted --members <member_id> --groups <group_id>
kortix apps access my-site --mode password --password '<password>'
kortix apps access-link my-site
```

- 有权打开应用的用户需使用其 OpenChatly 账号登录。访问链接（通过 `kortix apps access-link` 生成）有效期为 5 分钟，并会设置一个有效期为 8 小时、仅限主机访问的安全 Cookie。请将该链接视为机密信息妥善保管。
- 访问策略的任何变更都会撤销该应用持有的所有 Cookie 和所有查看者令牌（viewer token）。所有人都必须重新登录。
- OpenChatly 仅存储密码的哈希值。API、CLI 和 SDK 永远不会返回密码明文：策略中仅会报告 `password_configured`（密码已配置）。
- 应用列表仅显示你有权打开的应用。对于你无权打开的应用，系统会返回 `404` 错误，而不是 `403`。
- 在 Web 界面中，在应用（Apps）页面的 URL 中添加 `?open_app=<app_id>` 参数，可以通过访问链接直接打开该应用。

### 识别访问者身份（Know who is looking）

访问网关（gate）会在请求到达你的应用之前，要求每位访问者完成登录。你的应用无需实现自己的登录流程即可获知访问者身份。查看者作用域（viewer scope）决定了应用能获取多少身份信息：

| `--viewer` 参数 | 应用接收到的信息 |
|---|---|
| `identity`（默认） | 查看者的用户 ID、邮箱、姓名、头像、账户角色及所属群组。这些信息包含在每个请求的签名 `x-kortix-app-viewer` 标头中。 |
| `api` | 包含上述所有信息，此外还会在 `x-kortix-app-viewer-token` 标头中提供一个有效期为 1 小时的令牌，该令牌可在 OpenChatly API 中代表该查看者进行操作。其权限上限受查看者角色的限制。 |
| `off` | 不传递任何身份信息。 |

```bash
kortix apps access my-site --viewer api
```

当用户通过其 OpenChatly 账号或访问链接打开应用时，即产生一个“查看者（viewer）”。配置为 `password`（密码保护）模式的应用永远不会产生查看者。而 `public`（公开）模式的应用，仅在访客通过访问链接进入时才会产生查看者。

**在浏览器端。** 在应用的源站（origin）上调用 `GET /_kortix/viewer` 接口即可获取当前查看者信息。请通过同一源站下的 `/_kortix/api/v1/*` 路径来调用 OpenChatly API：如果从应用源站直接向 API 发起请求，会因跨域资源共享（CORS）策略而失败。

```tsx
import { createKortix, kortixAppViewerToken } from '@kortix/sdk';
import { useKortixAppViewer } from '@kortix/sdk/react';

const kortix = createKortix({ backendUrl: '/_kortix/api/v1', getToken: kortixAppViewerToken() });

function Header() {
  const { status, viewer } = useKortixAppViewer();   // 'loading' | 'anonymous' | 'viewer'
  return <span>{status === 'viewer' ? viewer.email : 'Signed out'}</span>;
}
```

`/_kortix/api/v1/*` 接口在以下情况会返回特定错误：如果查看者作用域（scope）不是 `api`，返回 `403 viewer_api_disabled`；如果没有查看者身份，返回 `401 no_viewer_identity`；如果请求来自其他源（跨域），返回 `403 cross_site_request`。此外，`/v1/oauth/*` 和 MCP 相关路径会直接返回 `404`。

**在应用服务端。** 请从 `@kortix/sdk/server` 导入：

```ts
import { readAppViewer, createAppViewerKortix } from '@kortix/sdk/server';

const viewer = await readAppViewer(request);
// { userId, email, name, picture, groupIds, groups, role, projectId, accountId, appId, accessMode, token, expiresAt } or null
if (!viewer) return new Response('Not found', { status: 404 });

const kortix = await createAppViewerKortix(request, { backendUrl: 'https://api.kortix.com/v1' });   // scope api only
```

- `readAppViewer` 使用 OpenChatly 自动注入的 `KORTIX_APP_VIEWER_SECRET` 环境变量来验证签名标头。伪造的标头将无法通过验证。
- `createAppViewerKortix` 利用网关（gate）在每个请求中添加的令牌，构建一个代表该查看者进行操作的客户端。请为每个请求单独构建一个客户端，切勿存储或记录该令牌。
- `createKortixAppGuard()` 会返回一个统一的解析器，同时处理网关标头和您应用自身的 OpenChatly 登录。`requireViewer(request)` 和 `requireGroup(request, groupIds)` 只会返回 `{ viewer }` 或 `{ response }`，永远不会返回 null。即使应用的访问模式发生变更，群组检查功能依然可以正常工作。
- 拥有 `member`（成员）角色的查看者，如果要在具有 Agent 权限的项目中启动会话，必须获得 Agent 授权。如果没有该授权，API 会返回 `403 no_agent_access` 错误。

如果应用部署在自定义域名上，则没有网关（gate）保护。在这种情况下，请使用 [Sign in with OpenChatly（使用 OpenChatly 登录）](#sdk-认证) 进行身份验证。

### 应用间调用（Apps that use Apps）

一个应用可以调用同一项目下的其他应用。在这种情况下，您的应用代码会获取目标应用的登录令牌，并通过自身的源站（origin）来访问它们。

```bash
kortix apps link crm --uses backend  # add; kortix apps unlink removes
kortix apps set crm --uses backend,files # replace; --uses= clears
```

在 `kortix.yaml` 配置块中设置 `uses: [backend]`，会在每次部署时应用相同的依赖列表。如果指定的 slug（应用标识）不存在或您无权查看，系统会返回 `400 app_not_found` 错误，并在响应中附带可用的 `slugs` 列表。

**登录令牌（Sign-in tokens）。** 每个项目都有一个令牌颁发机构（issuer），地址为 `https://<api host>/v1/projects/<project_id>`，它提供公开的 `/.well-known/openid-configuration` 和 `/jwks.json` 端点。令牌是一个有效期为 15 分钟的 ES256 JWT，其 `aud`（受众）字段为目标应用的 ID。

令牌中携带 `sub`（用户标识）、`email`、`name`、`picture`、`groups`、`group_ids`、`role`、`account_id` 和 `project_id` 字段。Agent（智能体）的令牌会携带 `kind: "agent"` 字段，且不包含 groups 或 role 信息。如果用户在某个应用中获取了用于调用其他应用的令牌，该令牌还会携带 `via_app_id` 字段，即用户最初登录的应用 ID。

| 获取者 | 获取方式 |
|---|---|
| 应用内的用户 | 在应用源站上调用 `GET /_kortix/token?audience=<slug or id>`：目标可以是应用自身（默认）或其使用的应用。也可以在 `@kortix/sdk` 中使用 `kortixToken({ audience })` 方法。 |
| 成员、脚本或 Agent 会话 | 运行 `kortix apps token <app>`（添加 `--json` 参数会返回 `expires_at` 过期时间），或调用 `POST /v1/projects/<project_id>/apps/<app_id>/token`。Agent 会话获取的令牌会标明其所属的 Agent。 |

如果请求的受众（audience）不在允许列表中，会返回 `403 app_not_linked` 错误。只要用户有权访问当前应用，即使他们无权直接打开被调用的应用，系统也会为其颁发该应用所有依赖应用的令牌。建议将后端应用设置为 `private`（私有）：这样它不会出现在用户的常规应用列表中，且其独立 URL 也会拒绝未授权访问。但这不会影响依赖它的应用为其读者提供正常服务。

令牌仅用于证明用户身份，不代表其操作权限。在任何处理非公开数据的函数中，都必须校验 `groups`、`role` 或 `via_app_id`。如果一个后端应用服务于两个前端应用，可以通过 `via_app_id` 确保每个应用的读者只能获取属于该应用的数据。当用户被移除权限后，其访问权限会在一个令牌生命周期（15分钟）内失效。

**绑定（Bindings）。** 在应用源站上访问 `/_kortix/apps/<slug>/*` 路径，会将 HTTP 和 WebSocket 请求转发至被调用应用的 `http` 服务。若要访问其他服务，可使用 `/_kortix/apps/<slug>--<service>/*` 路径。这种方式让浏览器端代码只需使用单一源站，且无需处理 CORS（跨域）问题。被调用的应用会自行校验请求中的令牌。

```ts
import { kortixBinding } from '@kortix/sdk';

const backend = kortixBinding('backend'); // { url: <origin>/_kortix/apps/backend, token: a token fetcher }
```

为了在资源包（bundle）加载完成前发起首次令牌请求（例如通过内联的 `<script>` 标签），请将 `fetch` 方法传递给 `kortixBinding`。在首次调用时返回提前获取的响应，之后再返回真实的 `fetch` 方法。这样绑定机制就不会重复请求令牌。

| 被调用的应用或服务 | 返回结果 |
|---|---|
| 不在 `uses` 依赖列表中 | `403 app_not_linked` |
| 配置了 `access: admins` 的服务 | `403 app_binding_forbidden` |
| 静态应用（static App） | `409 app_binding_unsupported` |
| 没有正在运行的发布版本 | `503 app_binding_unavailable` |
| 找不到指定的服务 | `404 app_service_not_found` |

**服务端到服务端调用（Server to server）。** 机器上没有查看者（viewer）Cookie，因此会跳过绑定机制。它会使用令牌直接调用 `KORTIX_USES_URL_<SLUG>` 环境变量。由于每次部署都会生成新的机器，因此依赖关系的变更会在下一次部署时同步到该变量中。

**校验令牌（Verify a token）。** 使用 `@kortix/sdk` 中的 `verifyKortixToken(bearer)` 方法可以检查令牌的签名、过期时间（允许 60 秒的时钟偏差）、颁发者（issuer）和受众（audience）。在服务端应用中，该方法无需额外配置：它会自动读取注入的 `KORTIX_AUTH_*` 环境变量。在其他环境中，则需要传入从应用的 `auth` 配置中获取的 `issuer`、`audience` 和 `jwks` 参数。

若需进行离线校验（例如在自托管的 Convex 部署中），可以运行 `kortix apps auth-env <app>` 命令。它会以 dotenv 格式打印出 `KORTIX_AUTH_ISSUER`、`KORTIX_AUTH_AUDIENCE` 和 `KORTIX_AUTH_JWKS`（密钥集以 `data:` URL 的形式提供）。这些值都是公开的。

`readKortixMember(claims)` 方法会将令牌的声明（claims）或查看者对象转换为一个成员（member）对象，如果转换失败则返回 `null`。`requireKortixMember(claims, { groups, roles })` 方法会返回该成员对象，如果不符合条件则会抛出 `KortixMemberError`，错误码为 `unauthenticated`（未认证）或 `forbidden`（禁止访问）。参数中的列表条件表示“满足其中任意一项即可”。

群组匹配支持通过名称或 ID 进行。空列表表示不允许任何人访问。群组功能需要 Enterprise（企业版）计划；而角色（roles）功能在所有计划中均可用。

### Agent 与应用（Agents and Apps）

Agent 会话会使用其会话凭证（放在 `Authorization: Bearer` 或 `X-Kortix-App-Authorization: Bearer` 标头中）来调用应用。当应用自身的业务逻辑需要使用 `Authorization` 标头时，请使用第二个标头。在网关（gate）转发请求之前，它会移除 `X-Kortix-App-Authorization` 标头、包含 OpenChatly 凭证的 `Authorization` 标头以及所有 OpenChatly 相关的 Cookie。

其他所有的标头和 Cookie 都会原封不动地传递给应用。应用代码永远不会接收到 OpenChatly 的凭证。

网关会将 Agent 会话视为 Agent 本身，而不是启动该会话的用户：

| 应用访问模式 | Agent 会话获准访问的条件 |
|---|---|
| `public`（公开） | 始终允许 |
| `project`（项目内） | Agent 拥有 `project.app.read` 权限 |
| `restricted`（受限）或 `private`（私有） | 应用的 slug 在 Agent 的 `apps` 列表中，且 Agent 拥有 `project.app.read` 权限 |
| `password`（密码保护） | 永远拒绝 |

被拒绝的请求会返回 `401 app_auth_required` 错误。Agent 会话只能打开其所属项目内的应用。

```yaml
agents:
  report-writer:
    prompt: Write the weekly report from the reports App.
    kortix_permissions: [project.app.read]
    apps: [reports]    # App slugs, all, or none (the default)
```

在 `kortix.yaml` 中通过 `kortix agents scope report-writer --apps reports`（也可设置为 `all` 或 `none`）来配置应用列表，或者在 **Customize** → **Agents** → 选择对应 Agent → **Apps** 中进行设置。应用的访问对话框会列出已获授权的 Agent。在代码中，可调用 `apps.access.agents(appId)` 来获取列表。详见 [Agents](/docs/zh/guide#智能体agents)。

脚本、CI 任务或服务账户可以通过个人访问密钥（`kortix_pat_`）或服务账户密钥（`kortix_sa_`）来调用非公开应用。请将密钥放在 `Authorization: Bearer` 或 `X-Kortix-App-Authorization: Bearer` 标头中发送。网关会在令牌的当前项目绑定范围内，应用与浏览器登录用户相同的访问决策。配置为 `password`（密码保护）模式的应用永远不会接受 OpenChatly 凭证。

如果 `openapi` 或 `http` 连接器的基础 URL 指向同一项目内的应用，则无需 OpenChatly 凭证。连接器网关会自动为调用会话添加一个有效期为 60 秒的签名断言。详见 [Connectors](/docs/zh/guide#连接器connectors)。

### 触发器与应用事件（Triggers and App events）

应用可以启动 Agent，触发器也可以调用应用。

| 需求 | 使用方式 |
|---|---|
| 当应用检测到某些情况时运行 Agent | 应用使用 `Authorization: Bearer $KORTIX_APP_TOKEN` 向 `$KORTIX_APP_EVENTS_URL` 发送应用事件。配置了 `on: { event, app }` 的触发器会接管并启动 Agent。详见 [App events](/docs/zh/guide#触发器triggers)。 |
| 按计划或事件调用应用 | 使用配置了 `run: { app, path, method, payload }` 的触发器。OpenChatly 会唤醒按需运行的应用并发送请求。此过程无会话（session），无模型（model）。详见 [Call an App](/docs/zh/guide#触发器triggers)。 |
| 应用稍后调用自身 | 使用应用令牌调用 `POST /v1/projects/<project_id>/apps/<app_id>/runs`，并设置 `run_after` 或 `run_at` 参数。详见 [Call an App](/docs/zh/guide#触发器triggers)。 |

要响应外部事件，建议优先使用 Webhook，其次是连接器事件（connector event），最后才是定时任务。如果数据源不提供推送且必须全天候监控，可以构建一个 Watcher（监控）应用：通过 `every` 触发器定期调用应用的 `/tick` 接口，应用仅在数据源发生变化时才发送应用事件（基于内容生成的 `id` 确保每个触发器在 30 天内仅触发一次）；随后，会话触发器（`kortix triggers add "<text>" --on app --app <slug>`）会唤醒等待中的会话，或者由 `kortix.yaml` 中的触发器启动一个 Agent。应用本身永远不会直接启动 Agent：它只负责发送事件，由触发器来决定后续操作。请将 Watcher 应用设置为不公开且按需运行：它属于后台（Background）列表。完整示例请参阅 `kortix-system` 技能中的 `references/scheduling.md` → Watch 24/7。

应用事件和运行调用仅支持 REST 协议。它们使用应用令牌（App token）进行身份验证，而不是 OpenChatly 令牌。

### 应用内的环境变量（Environment inside an App）

OpenChatly 会在每台机器中自动注入以下环境变量：

| 变量 | 值 |
|---|---|
| `KORTIX_APP_SLUG` | 应用的 slug（标识） |
| `KORTIX_APP_URL` | 主服务的 URL |
| `KORTIX_SERVICE_URL_<NAME>` | 其他 HTTP 服务的 URL（名称中的 `-` 会转换为 `_`） |
| `KORTIX_USES_URL_<SLUG>` | 当前应用所依赖的其他应用的 URL（slug 中的 `-` 会转换为 `_`） |
| `KORTIX_MACHINE_ID` | 机器的 ID，在多次发布版本间保持稳定 |
| `KORTIX_PROCESS_GROUP` | 机器的进程组 |
| `KORTIX_AUTH_ISSUER`, `KORTIX_AUTH_AUDIENCE`, `KORTIX_AUTH_JWKS` | 用于验证应用登录令牌的配置值 |
| `KORTIX_APP_VIEWER_SECRET` | 用于验证签名查看者标头的密钥 |
| `KORTIX_APP_ACCOUNT_ID` | 拥有该应用的账户 ID |
| `KORTIX_APP_ID` | 应用的 ID |
| `KORTIX_APP_TOKEN` | 用于 [App events](/docs/zh/guide#触发器triggers) 和定时运行的应用令牌。属于机密信息。 |
| `KORTIX_APP_EVENTS_URL` | 应用发送事件的接收地址 |

您自己的环境变量通过 `kortix.yaml` 中的 `env` 和 `secrets` 进行配置：

- 最多支持 128 个 `env` 变量和 128 个 `secrets` 映射。单个值的大小上限为 32 KiB。
- 变量名仅允许大写字母、数字和 `_`（正则匹配 `^[A-Z_][A-Z0-9_]*$`），长度上限为 128 个字符。
- `kortix validate` 和部署过程会拒绝使用保留名称，并说明原因。保留名称包括：所有以 `KORTIX_` 开头的名称；`PORT`、`PATH`、`HOME`、`PWD`、`USER`、`LOGNAME`、`SHELL`、`HOSTNAME`、`TERM`、`TMPDIR`、`NODE_ENV`、`NODE_OPTIONS`、`LD_PRELOAD`、`LD_LIBRARY_PATH`；以及 `SLACK_SIGNING_SECRET` 和 `SLACK_BOT_TOKEN`。
- 同一个名称不能同时出现在 `env` 和 `secrets` 中。
- `secrets` 会将运行时变量名映射到项目中的机密标识符。该机密必须具有 `environment` 暴露级别。OpenChatly 会在创建机器时解析该机密，且永远不会将其写入镜像中。详见 [Security](/docs/zh/guide#安全性)。

### URL 与访客体验（URLs and what visitors see）

OpenChatly 在创建应用时会分配主机名，且永不更改。在 OpenChatly Cloud 上，其格式为 `https://<env>-<slug>-<route-key>.apps.kortix.com`，其中 `<route-key>` 为 16 位十六进制字符。同一标签下加上 `--<service>` 后缀可访问其他服务。

如果标签长度超过 63 个字符，服务 URL 将为 `null`：此时请通过绑定（binding）来访问该服务。自托管实例会在其应用基础域名上提供服务。详见 [Self-hosting](#应用托管app-hosting)。

静态应用的文件服务规则如下：

- HTML 文件在每次加载时都会重新验证（`no-cache`）。
- 带哈希值的构建产物（如 `_next/static/`，以及 `assets/` 或 `static/js|css|media/` 下带哈希值的文件）会被缓存一年。其他所有文件均需重新验证。
- 开启 SPA 回退（fallback）后，导航到未知路径的请求会返回 `index.html`。请求缺失的文件会返回 `404.html` 及 `404` 状态码。
- 如果存在 `docs/index.html`，访问 `/docs` 会 `308` 重定向到 `/docs/`。
- 除非应用设置为 `public`（公开），否则响应会被标记为 `private`，以防止被共享缓存存储。

对于已停止的服务端应用，经过授权的请求会将其唤醒，等待其就绪后处理该请求。在应用部署或唤醒期间，浏览器会收到一个状态页面（HTTP `202`，`retry-after: 3`，每 3 秒自动刷新）。其他客户端会收到 `202` 状态码及包含 `code` 字段的 JSON，该字段表示当前阶段（例如 `app_deployment_building` 或 `app_starting`）。请等待 3 秒后重试。

| 状态 | HTTP 状态码 | `code` 字段 |
|---|---|---|
| 上次部署失败 | 503 | `app_deployment_failed` |
| 上次部署已取消 | 503 | `app_deployment_cancelled` |

账户限制相关的错误会返回 `402` 或 `429`：详见 [Run mode, machines and scale](#运行模式机器与扩缩容run-mode-machines-and-scale)。

### 发布版本、回滚与删除（Releases, rollback and deletion）

```bash
kortix apps releases my-site            # 查看发布版本列表：版本号 (vN)、状态 (status)、部署策略 (strategy)；并标记当前正在运行的版本
kortix apps show my-site                # 查看应用详情：功能特性 (capabilities)、链接 (links)、运行模式 (run mode)、发布版本 (releases)
kortix apps logs my-site [deployment]   # 查看运行时日志；可通过 --after N 和 --limit N 参数控制起始位置和获取数量
kortix apps rollback my-site v3         # 基于 v3 版本创建一个新的发布版本（即回滚到 v3）；默认会等待部署完成，添加 --no-wait 参数可跳过等待
```

- 回滚操作会基于目标版本的构建产物和配置创建一个全新的发布版本，并像常规部署一样进行发布。卷（Volumes）中的数据会保持不变。如果目标版本的状态不是 `ready`（就绪），系统会返回 `409 release_not_ready` 错误。
- 应用会保留当前正在运行的发布版本，以及最近 5 个处于 `ready` 状态的其他发布版本作为回滚目标。每次部署后，OpenChatly 会自动淘汰更旧的版本。自托管环境的运维人员可以修改保留数量：详见 [Self-hosting](#应用托管app-hosting)。
- 运行时日志的每一行都带有 `source`（来源）字段：`app`（您的业务进程）、`appd`（应用监管进程）或 `caddy`（访问日志，其中永远不会包含请求标头）。
- 在 Web 界面中，打开应用后进入某个发布版本，即可查看其事件记录和构建日志。

删除单个发布版本或整个应用：

```bash
kortix apps delete my-site --deployment v1 --yes   # 删除指定的单个发布版本（v1）及其对应的镜像
kortix apps delete my-site --yes                   # 删除整个应用，包括其关联的所有机器和镜像
```

- 当前正在运行的发布版本（live release）无法被删除（错误码：`409 deployment_live`）。请先执行回滚操作。
- 仍在构建中的发布版本无法被删除（错误码：`409 deployment_in_progress`）。
- 如果构建过程触及了云服务商的镜像数量上限，将会失败并提示 `app_image_quota_exceeded`。请删除不再需要的发布版本以释放配额。
- 删除应用需要 `project.app.write` 权限。如果应用包含卷（volumes），还需要 `project.app.admin` 权限。每个卷都会保留一个 `final`（最终）快照，保留期为 7 天，之后 OpenChatly 会将其彻底清除。请务必先导出您需要的数据。

### 模板：Convex 后端（Template: Convex backend）

`convex` 模板用于部署一个支持 OpenChatly 登录的自托管 Convex 后端，提供数据库、服务端函数、实时查询、文件存储、定时任务和搜索等功能。它本质上是一个带有卷（volume）的常规服务端应用。

```bash
kortix apps launch --template convex   # 添加 --no-deploy 参数表示仅生成并写入 kortix.yaml 配置文件，而不立即执行部署
```

请在包含 `kortix.yaml` 文件的目录下运行该命令。如果目录下没有该文件，`launch` 命令会自动创建它。如果指定的 slug（应用标识）已存在于文件中，系统会拒绝该操作：请更换一个 `--name` 参数。

`launch` 命令会向 `kortix.yaml` 中写入两个配置块，并生成控制台（dashboard）所需的两个文件：`apps/backend/dashboard/Dockerfile` 和 `apps/backend/dashboard/start.js`（如果同名文件已存在，则会保留原文件）。随后它会执行以下操作：

1. 部署 `backend`（后端）应用。
2. 从后端机器上读取管理员密钥，并将其写入项目机密 `BACKEND_ADMIN_KEY` 中（规则：将应用 slug 转换为大写，并将 `-` 替换为 `_`）。该命令绝不会在终端打印此密钥。每次执行 launch 命令都会重新写入该密钥。
3. 部署 `backend-dashboard`（后端控制台）应用。

之所以分为两个应用，是因为 Convex 将后端和控制台作为两个独立的镜像提供，而 OpenChatly 的单个应用只能运行一个镜像。在 **Apps**（应用）页面中，它们会显示为一个整体：控制台会作为后端的 **Dashboard**（控制台）标签页存在。后端应用依托卷（volume）实现 7×24 小时不间断运行；而控制台在空闲时会自动休眠。

| 应用 | 详细说明 |
|---|---|
| `backend` | Convex 后端服务，镜像通过摘要（digest）固定版本。`http` 服务运行在 3210 端口（`access: public`，提供 `/version` 检查）：包含客户端 URL、WebSocket 同步接口和管理 API。`site` 服务运行在 3211 端口（`access: public`）：提供 HTTP Actions。数据卷 `data` 挂载于 `/convex/data`，容量为 10 GB。始终开启，配置为 1 vCPU / 1 GB 内存 / 10 GB 磁盘。标签为 `backend`。配置 `display: { preview: none }`。 |
| `backend-dashboard` | Convex 控制台，基于 `apps/backend/dashboard/` 目录构建（`type: dockerfile`）。访问权限为 `access: admins`，按需运行。它依赖 `backend` 应用，并通过 `/_kortix/apps/backend` 路径访问后端。配置 `display: { parent: backend }` 使其成为 `backend` 的 **Dashboard** 标签页。配置 `secrets: { NEXT_PUBLIC_ADMIN_KEY: BACKEND_ADMIN_KEY }` 用于自动登录。 |

`start.js` 脚本会使用管理员密钥完成控制台的自动登录。由于控制台配置为 `access: admins`，因此只有拥有 `project.app.admin` 权限的用户才能访问。

两个后端服务都设置为 `public`，是因为 Convex 会在每个函数内部自行校验登录状态。请务必保持后端应用只有 1 台机器：如果增加第二台机器，它会获得一个全新的空卷，从而形成一个完全独立的第二个数据库。

连接并推送您的 Convex 代码（例如从 `apps/backend/` 目录推送）。当前会话的环境变量中已包含 `BACKEND_ADMIN_KEY`：

```bash
cd apps/backend
npm install convex@1.46.0 @kortix/sdk
export CONVEX_SELF_HOSTED_URL=<backend App URL> CONVEX_SELF_HOSTED_ADMIN_KEY="$BACKEND_ADMIN_KEY"
kortix apps auth-env backend | while IFS='=' read -r k v; do printf '%s' "$v" | npx convex env set "$k"; done
npx convex deploy
```

请使用 Convex CLI `1.46.0` 版本：该版本与固定版本的后端镜像相匹配。

> **Warning**
>
> 管理员密钥（Admin Key）拥有对后端代码和数据的完全控制权。请仅向负责部署后端的 Agent 授予 `BACKEND_ADMIN_KEY` 权限。切勿将此密钥提交到代码仓库，或将其打包到 Web 应用中。

为函数配置 OpenChatly 登录验证：

```ts
// convex/auth.config.ts
export default {
  providers: [{
    type: 'customJwt',
    issuer: process.env.KORTIX_AUTH_ISSUER!,
    applicationID: process.env.KORTIX_AUTH_AUDIENCE!,
    jwks: process.env.KORTIX_AUTH_JWKS!,
    algorithm: 'ES256',
  }],
};
```

```ts
// convex/members.ts
import { query } from './_generated/server';
import { readKortixMember, requireKortixMember } from '@kortix/sdk';

export const me = query({
  args: {},
  handler: async (ctx) => readKortixMember(await ctx.auth.getUserIdentity()),   // null when signed out
});

// In every function that touches non-public data:
// const member = requireKortixMember(await ctx.auth.getUserIdentity(), { roles: ['owner', 'admin'] });
```

在 React 中，通过 `useQuery(api.members.me)` 读取成员信息。请勿调用 `useConvexAuth()`：它在普通的 `ConvexProvider` 下会抛出异常。

- **控制台（Dashboard）。** 打开 **Apps**（应用）→ `backend` → **Dashboard**（仅限项目管理员访问）。打开后即处于已登录状态。运行 `kortix apps access-link backend-dashboard` 会打印一个 5 分钟有效的链接，指向同一页面。
- **在执行数据迁移、批量导入或数据回填（backfill）之前，** 请先运行 `kortix apps volumes snapshot backend data` 创建快照。若需恢复，可运行 `kortix apps volumes restore backend data <snapshot>`：当前线上数据会回滚到该快照的状态。
- **自行留存一份副本**，使用 `npx convex export --path backup.zip --include-file-storage`。
- **从外部访问**时，运行 `kortix apps connect backend` 会打印调用后端的方法：包括其 URL，以及用于获取登录令牌、发起 HTTP 调用以及在自己的服务端集成的代码片段。该命令不会打印任何机密信息。

### 构建一个内部工具（Build an internal tool）

一个内部工具由两个应用构成：一个 Convex 后端应用负责数据与逻辑，一个静态应用负责 UI 界面。OpenChatly 会为团队完成登录，因此前端 UI 能够识别当前访问者的身份，后端的每个函数也都能知晓调用方是谁。

```text
apps/backend/convex/       Convex 后端函数目录：包含 schema.ts、auth.config.ts、members.ts 等文件
apps/backend/dashboard/    控制台应用目录：包含 Dockerfile 和 start.js（由模板自动生成）
apps/crm/                  前端 UI 目录：一个基于 Vite 和 React 的项目
kortix.yaml                Kortix 配置文件：定义了 apps.backend 和 apps.backend-dashboard（由模板生成）以及 apps.crm
```

1. **启动后端**

    运行 `kortix apps launch --template convex`。

2. **编写并推送函数**

    在 `apps/backend/convex/` 目录下编写数据模型（schema）和函数。从 [模板：Convex 后端](#模板convex-后端template-convex-backend) 章节中引入 `auth.config.ts`。在每个公开的查询（query）和变更（mutation）函数中，首先调用 `requireKortixMember` 进行身份校验。编写完成后，使用 `npx convex deploy` 进行推送部署。

3. **将 UI 与后端连接**

    通过绑定（binding）进行连接。它会为 UI 提供一个统一的源地址（origin）和登录令牌：

    ```ts
    // apps/crm/src/convex.ts
    import { ConvexReactClient } from 'convex/react';
    import { kortixBinding } from '@kortix/sdk';

    const backend = kortixBinding('backend');
    export const convex = new ConvexReactClient(backend.url);
    convex.setAuth(backend.token);
    ```

4. **Declare the UI App**

    Add a block to `kortix.yaml`. `listed: true` gives the UI a card on the
    **Apps** page.

    ```yaml
    apps:
      crm:
        path: apps/crm/dist
        type: static
        spa: true
        uses: [backend]
        display: { listed: true }
    ```

5. **构建、部署并向项目开放访问**

    ```bash
    (cd apps/crm && npm run build)
    kortix apps deploy apps/crm/dist
    kortix apps access crm --mode project
    ```

内部数据切勿使用 `public` 权限。因为 `public` 应用不存在已登录的成员，所以任何需要成员身份的函数都会拒绝调用。

[OpenChatly UI](#ui-组件kortixui)（`@kortix/ui`）是专为应用 UI 打造的组件库。请通过 npm 安装，并确保两个包的版本一致：`npm i @kortix/ui @kortix/sdk`。切勿将组件源码直接复制到应用中。对于未使用 Tailwind 的 Vite 应用，请在 `src/main.tsx` 中引入一次 `@kortix/ui/styles.css`；对于使用 Tailwind v4 的应用，请在主 CSS 文件中引入 `@import 'tailwindcss'; @import '@kortix/ui/tailwind.css';`。在编写自定义组件前，请优先组合使用 `Card`、`Table`、`Modal`、`Badge` 和 `InfoBanner` 等基础组件，并通过 CSS 变量来实现主题定制。会话的聊天视图请使用 `@kortix/ui/session` 中的 `SessionThread` 组件。

如需撤销某项更改：

| 故障类型 | 撤销/回滚方式 |
|---|---|
| UI 界面 | `kortix apps rollback crm <vN>` |
| 后端的镜像或配置 | `kortix apps rollback backend <vN>`。卷（volume）中的数据会保持不变。 |
| Convex 代码 | 从 Git 中检出上一个正常的 `apps/backend/convex` 代码，然后重新运行 `npx convex deploy`。 |
| 数据 | `kortix apps volumes restore backend data <snapshot>`。该快照之后的所有数据更改都将丢失。 |

### 基于 TypeScript 在应用上进行构建

`@kortix/sdk` 中的 `kortix.project(projectId).apps` 暴露了所有应用操作接口。CLI 命令行工具底层也调用了相同的接口。

请根据应用的 `capabilities`（能力）来进行分支判断，而**不要**根据应用的创建方式来判断：

| 能力（Capability） | 应用具备该能力的条件 |
|---|---|
| `deployments`（部署）, `rollback`（回滚）, `preview`（预览）, `member_tokens`（成员令牌） | 始终具备 |
| `static`（静态） | 当前运行的发布版本为静态应用 |
| `sleep`（休眠）, `machines`（机器）, `scale`（扩缩容）, `exec`（执行命令） | 当前运行的发布版本为服务端应用 |
| `volumes`（卷）, `snapshots`（快照） | 应用配置了数据卷 |

如果调用的操作需要某项能力，但应用并不具备该能力，系统将返回 `409` 错误：

```json
{ "error": "This App does not support exec.", "code": "app_capability_unsupported", "capability": "exec" }
```

CLI 会首先进行校验：如果应用不支持该能力，CLI 会直接退出并返回状态码 `1`，同时输出提示信息 `App <slug> does not support <capability>.`，且不会发送任何网络请求。此外，对于没有分配机器的应用，其机器（machine）和数据卷（volume）相关的路由会直接返回 `409 app_no_machines` 错误。

```ts
import { createKortix } from '@kortix/sdk';

const kortix = createKortix({ backendUrl: 'https://api.kortix.com/v1', getToken: async () => process.env.KORTIX_TOKEN! });
const apps = kortix.project(projectId).apps;

const app = await apps.create({ slug: 'docs', name: 'Docs' });
const artifact = await apps.artifacts.uploadArchive(tarGzBytes);
const deployment = await apps.deployments.create(app.app_id, {
  artifact_id: artifact.artifact_id,
  source: { kind: 'static', spa: true },
});

for (;;) {
  const { deployment: current } = await apps.deployments.get(app.app_id, deployment.deployment_id);
  if (current.status === 'ready') break;
  if (current.status === 'failed' || current.status === 'cancelled') throw new Error(current.error ?? current.status);
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
```


| 分组 | 接口调用 |
|---|---|
| 应用 (App) | `list`, `create`, `get`, `update`（支持 `labels` 和 `display`）, `remove`, `start`, `stop`, `rollback(appId, deploymentId)` |
| 构建产物 (Artifacts) | `artifacts.register`（`archive` 或 `oci_image`）, `artifacts.uploadArchive`, `artifacts.finalize` |
| 发布版本 (Releases) | `deployments.create`（参数：`artifact_id`, `source`, `provider?`, `environment?`, `secrets?`, `config?`）, `deployments.list`, `deployments.get`（包含事件和构建日志）, `deployments.logs`, `deployments.remove` |
| 机器 (Machines) | `machines.list`, `machines.start`, `machines.stop`, `machines.restart`, `machines.destroy`, `scale(appId, { worker: 3 })`, `exec(appId, { command: ['ls', '/data'] })` |
| 卷 (Volumes) | `volumes.list`, `volumes.create`, `volumes.update`, `volumes.destroy(appId, volumeId, name)`, `volumes.snapshots`, `volumes.snapshot`, `volumes.restore`, `volumes.fork` |
| 访问控制 (Access) | `access.get`, `access.update`（参数：`mode`, `member_ids`, `group_ids`, `password`, `viewer_token_scope`）, `access.session`（5 分钟有效的链接）, `access.agents` |
| 登录验证 (Sign-in) | `token(appId)`, `authEnv(appId)` |

`@kortix/sdk/react` 提供的 React Hooks：
`useProjectApps`, `useAppDeployments`, `useAppDeployment`, `useAppAccess`, `useAppMachines`, `useAppVolumes` 和 `useAppVolumeSnapshots`。
完整的函数签名与类型定义请参阅：[SDK 参考文档](#项目句柄the-project-handle) 和 [React Hooks 文档](#react-hooks)。

### 权限与 CLI 参考

| 权限 | 允许执行的操作 | 持有者 |
|---|---|---|
| `project.app.read` | 列出并打开您有权查看的应用。列出被授予应用权限的 Agent。创建访问链接。生成登录令牌。读取 `auth-env` 的值。 | 成员 (Member), 管理员 (Manager) |
| `project.app.write` | 创建应用。修改名称、规格大小、运行模式、标签 (labels)、`display`、`uses` 和外部 URL。读取并修改访问策略。删除发布版本。删除应用。 | 管理员 (Manager) |
| `project.app.deploy` | 上传构建产物、部署、回滚、启动和停止。读取发布版本、其事件、构建日志及运行时日志。列出、启动、停止、重启和销毁机器。扩缩容。列出并创建卷，设置快照保留策略，列出并创建快照，克隆卷。 | 管理员 (Manager) |
| `project.app.admin` | 执行命令 (`exec`)。恢复或销毁卷。打开 `access: admins` 的服务。删除包含卷的应用。读取应用的事件凭证 (`GET …/apps/<app_id>/events/credentials`)。 | 管理员 (Manager) |

`project.app.write` 和 `project.app.deploy` 均包含 `project.app.read` 权限。
`project.app.admin` 包含 `project.app.write` 权限，但**不包含** `project.app.deploy` 权限。
账户所有者和系统管理员在所有项目中均视为管理员 (Manager)。关于角色和自定义角色的详细说明，请参阅 [Teams（团队）](/docs/zh/guide#teams)。

`<app>` 代表应用 ID 或 Slug。每个子命令都支持 `--project <id>`、`--host <name>` 和 `--json` 参数。

| 命令 | 功能说明 |
|---|---|
| `kortix apps list` (`ls`) | 列出您有权打开的应用：显示 Slug、状态和 URL |
| `kortix apps create <slug>` (`new`) | 创建一个尚未部署的应用。参数：`--name`, `--cpu`, `--memory`, `--disk`, `--idle-timeout`, `--always-on` 或 `--on-demand`, `--uses`。使用 `--url <https-url>` 可创建外部应用 |
| `kortix apps launch --template convex` | 将模板的配置块写入当前目录的 `kortix.yaml` 并执行部署。参数：`--name <slug>`, `--no-deploy` |
| `kortix apps deploy [path]` | 部署一个目录、`.tar.gz` 文件或通过 `--image` 指定镜像。参数：`--app`, `--slug`, `--name`, `--manifest-app`, `--type static\|bundle\|dockerfile`, `--command`, `--port`, `--dockerfile`, `--root`, `--output-dir`, `--install-command`, `--build-command`, `--readiness-path`, `--spa` 或 `--no-spa`, `--include-node-modules`, `--access`, `--password`, `--members`, `--groups`, `--always-on` 或 `--on-demand`, `--listed` 或 `--unlisted`, `--no-wait`, `--wait-seconds` |
| `kortix apps set <app>` (`update`) | 修改 `--name`, `--url`（外部应用）, `--cpu`, `--memory-gb`, `--disk-gb`, `--idle-timeout`, `--always-on` 或 `--on-demand`, `--uses`, `--listed` 或 `--unlisted` |
| `kortix apps link <app> --uses <slugs>` | 添加被引用的应用。使用 `unlink` 可移除引用 |
| `kortix apps show <app>` (`get`) | 查看能力 (capabilities)、链接、运行模式和发布版本 |
| `kortix apps releases <app>` | 查看发布版本列表，并标记当前正在运行的版本 |
| `kortix apps rollback <app> <vN>` | 基于 `vN` 版本创建一个新的发布版本。参数：`--no-wait` |
| `kortix apps logs <app> [deployment]` | 查看运行时日志。参数：`--after N`, `--limit N` |
| `kortix apps start <app>`, `stop <app>` | 唤醒服务端应用，或立即使其休眠 |
| `kortix apps machines [ls\|start\|stop\|restart\|destroy] <app> [machine]` (`machine`) | 列出机器或对特定机器执行操作 |
| `kortix apps scale count <app> <n>` | 设置某个组的机器数量（0–20）。参数：`--process <group>`（默认为 `app`） |
| `kortix apps scale show <app>` | 查看每个组的机器数量 |
| `kortix apps exec <app> -- <command…>` | 执行单条命令。参数：`--machine <id>`, `--timeout <s>` |
| `kortix apps volumes [ls\|create\|set\|snapshots\|snapshot\|restore\|fork\|destroy] <app> …` (`volume`) | 管理卷和快照。使用 `set --retention <days>` 可设置每日快照的保留天数 |
| `kortix apps labels <app> [a,b]` | 查看或替换标签。参数：`--clear` |
| `kortix apps access <app>` | 读取或设置访问权限。参数：`--mode`, `--password`, `--members`, `--groups`, `--viewer off\|identity\|api` |
| `kortix apps access-link <app>` | 生成一个 5 分钟有效的登录链接 |
| `kortix apps connect <app>` | 查看如何通过代码访问该应用。不会输出任何机密信息 |
| `kortix apps token <app>` | 生成一个 15 分钟有效且包含您身份信息的登录令牌 |
| `kortix apps auth-env <app>` | 以 dotenv 格式输出 `KORTIX_AUTH_*` 环境变量 |
| `kortix apps delete <app> --yes` (`rm`, `remove`) | 删除应用。使用 `--deployment <vN>` 可仅删除某个特定的发布版本 |

完整的 CLI 文档请参阅：[CLI](#cli命令行界面)。所有 API 路由请参阅 REST 参考文档：`https://api.kortix.com/v1/docs`。

## 自托管（Self-hosting）

自托管实例是指将完整的 OpenChatly 平台部署在您自己控制的服务器上。整个平台由一个 Docker Compose 服务栈承载，通过 `kortix self-host` 命令即可完成该服务栈的安装、配置与更新。本页面专为负责运行和维护服务器的运维人员编写。

请注意：会话（Sessions）运行在 Platinum 沙箱环境中，而非您的本地服务器上。因此，您的自托管实例必须能够从公网访问，以便这些沙箱能够成功回调您的服务。

快速入门指南共分为六个步骤。后续章节将对每个步骤进行详细解析。

1. **配置 DNS 解析指向服务器**

    为 `kortix.example.com` 和 `api.kortix.example.com` 创建 A 或 AAAA 记录，并为 `*.apps.kortix.example.com`（应用域名）和 `*.p.kortix.example.com`（沙箱预览域名）创建泛域名（Wildcard）记录。请保持所有记录为“仅 DNS”（DNS only）模式：切勿通过 Cloudflare 进行代理。同时，请确保服务器的 80 和 443 端口已开放。

2. **在服务器上运行初始化引导**

    该命令会自动安装 Docker 和 OpenChatly CLI，随后使用 TLS 证书和您的 Platinum API 密钥启动服务栈。它会将 `apps.<domain>` 和 `p.<domain>` 分别设置为应用域名和预览域名。

    ```sh
    curl -fsSL https://raw.githubusercontent.com/kortix-ai/CompanyOS/dev/scripts/kortix-selfhost-up.sh \
      | bash -s -- --domain kortix.example.com --email ops@example.com --platinum-key <platinum_api_key>
    ```

3. **回答初始化配置问题**

    如果引导脚本已将您的用户添加到 `docker` 用户组，请先打开一个新的终端 Shell。运行 `kortix self-host configure` 并输入您的管理员邮箱。直接按回车键（Enter）将保留其他所有默认配置，包括引导脚本已设置的 Platinum API 密钥。配置完成后，运行 `kortix self-host start` 以应用这些设置。

4. **注册管理员账号**

    打开 `https://kortix.example.com` 并使用您设置的管理员邮箱进行注册。在 `/admin/git` 页面连接 GitHub，创建团队账号和一个项目，然后添加大模型密钥。详见 [首次登录与配置](#首次登录与初始化设置)。

    请在服务栈启动后尽快完成此操作。在您设置 `EMAIL_URL` 或启用 `DISABLE_SIGNUP=true` 之前，任何能够访问该实例的人都可以为任意邮箱地址（包括管理员邮箱）创建并验证账号。

5. **将应用和预览服务切换为泛域名证书**

    运行 `kortix self-host tls wildcard`，根据提示添加输出的 DNS 记录，然后再次运行该命令。这可以防止应用和预览服务的主机名被记录在公开的证书日志中。此操作需要开放 UDP 和 TCP 的 53 端口。详见 [证书与安全过滤](#证书与安全过滤机制)。

6. **检查实例状态**

    运行 `kortix self-host doctor` 并修复所有未通过的检查项。详见 [加固实例安全](#加固实例安全)。

### 服务运行架构

`kortix self-host init` 会将 `docker-compose.yml`、`.env`、`Caddyfile` 和 `updater.sh` 写入 `~/.config/kortix/self-host/<instance>/` 目录。`kortix self-host start` 会执行 `docker compose up` 命令。所有服务均包含在一个名为 `kortix-<instance>` 的 Compose 项目中。

| 服务 | 功能说明 |
|---|---|
| `frontend` | Web 前端应用。 |
| `kortix-api` | 位于 `/v1` 路径的 REST API。它会将接收到的所有 `/v1/llm` 请求转发给 `llm-gateway`。 |
| `llm-gateway` | 独立的大语言模型（LLM）网关。Caddy 会将 `api.<domain>/v1/llm*` 的请求路由至此服务。 |
| `kortix-migrate` | 一次性任务。在 `kortix-api` 启动前执行数据库迁移。 |
| `kortix-updater` | 每天拉取新镜像，执行迁移并滚动更新应用服务。该服务需要挂载 Docker Socket。 |
| `capture-store` | 用于存储 [OpenChatly Capture](/docs/zh/capture) 录屏文件以及新会话初始快照的对象存储（MinIO）。该服务不对外暴露端口，设备和沙箱通过 API 源地址（origin）进行访问。数据存储在 `kortix-capture-data` 卷中。Capture 数据会随接入设备的增加而增长；快照会在 30 天后过期。如果设置 `KORTIX_CAPTURE_STORE=external`，服务栈中将不包含 `capture-store`，且除非通过 `KORTIX_PROJECT_SNAPSHOT_*` 指定了外部存储，否则不会生成快照。详见 [集成配置](#集成配置)。 |
| `supabase-*` | Supabase 发行版，所有镜像均通过摘要（digest）固定版本：包括 Postgres (`supabase-db`)、Auth、REST、Realtime、Storage、imgproxy、Meta、Functions、Kong、Supavisor 连接池、Studio、Analytics 和 Vector。 |
| `caddy` | 仅限域名模式。在 80 和 443 端口终止 TLS 并路由流量。它通过 ACME HTTP-01 挑战为每个主机获取证书，或在执行 `tls wildcard` 后获取泛域名证书。 |
| `acme-dns` | 仅在运行 `kortix self-host tls wildcard` 后启用。一个轻量级 DNS 服务器，负责响应一个被委托的域（`acme.<domain>`），以便 Caddy 能够通过 ACME DNS-01 挑战。它绑定在服务器本机地址的 53 端口。 |
| `cloudflared` | 仅限隧道模式。通过 Cloudflare 隧道对外发布 `kortix-api`。 |

开箱即用的特性：

- **沙箱（Sandboxes）。** 每个会话都运行在实例配置的沙箱提供商环境中：Platinum、阿里云 Agent Sandbox 或 Daytona。`kortix-api` 使用对应提供商的密钥来创建沙箱。沙箱会回调实例的公网 API 地址（`KORTIX_URL`）。
- **会话数据保留机制。** `/workspace` 目录保存当前会话的文件，仅在会话生命周期内有效。`/drives`（Drive）保存您的个人文件和公司文件，跨会话共享且持续保留直至被删除。其他任何数据（如主目录、`/tmp`、已安装的软件包）在会话重新打开时都会丢失。请将常用工具预置在 [沙箱模板](#沙盒模板sandbox-templates) 中。
- **Drive 与 App 卷。** 每个 Drive 和 App 卷都是 Platinum 卷。其数据存储在 Platinum 端，而非您的本地服务器上。
- **镜像。** Docker Hub 上的 `kortix/kortix-frontend`、`kortix/kortix-api` 和 `kortix/kortix-gateway`。拉取这些镜像无需凭证。
- **模型提供商。** 网关会调用您在项目中配置的模型提供商。

#### 网络可达性模式

| 模式 | 设置方式 | 公网 URL | 应用副本数 | 会话运行状态 |
|---|---|---|---|---|
| domain（域名模式） | `--domain <domain>` | `https://<domain>` 和 `https://api.<domain>` | `kortix-api`、`llm-gateway`、`frontend` 各 2 个副本，置于 Caddy 之后 | 是 |
| tunnel（隧道模式） | `--tunnel cloudflare` | Web 应用保留在 `http://localhost:13737`。仅 API 通过隧道 URL 对外公开。 | 各 1 个副本 | 是 |
| local（本地模式） | 不添加上述参数 | 无：所有端口仅绑定 `127.0.0.1` | 各 1 个副本 | 否，沙箱无法访问 API |

域名模式是生产环境的推荐配置。隧道模式适用于在本地机器上进行评估测试。如果不配置域名，服务将发布回环端口（loopback ports）：前端 `13737`，API `13738`，Supabase `13740`。当服务栈停止时，`start` 命令会自动将已占用的端口迁移到空闲端口。

### 环境要求

- **一台具有公网 IP 的 Linux 服务器。** 引导脚本会自动安装 Docker Engine 和 Compose 插件。如果服务器上已安装这些组件，则仅需安装 CLI。CLI 支持 Linux 和 macOS 系统，架构支持 x86_64 和 arm64。
- **DNS 配置。** 在首次启动前，必须为 `<domain>` 和 `api.<domain>` 配置 A 或 AAAA 记录并指向服务器。Caddy 需要这些记录来获取证书。请勿开启代理（Cloudflare 需设置为 "DNS only"）。
- **开放 80 和 443 端口** 的入站流量。
- **泛域名记录** 用于新域名实例启用的源地址：
  - `*.p.<domain>` 用于沙箱预览。所有公开实例都必须配置此项：否则浏览器预览将回退到路径代理模式，这会破坏根绝对路径链接，且 `doctor` 检查会失败。
  - `*.<apps base domain>`（例如 `*.apps.<domain>`），用于托管 [Apps](#应用参考apps-reference)。
- **开放 UDP 和 TCP 的 53 端口** 的入站流量，用于签发泛域名证书。详见 [证书与安全过滤](#证书与安全过滤机制)。
- **沙箱提供商密钥。** 默认为 `PLATINUM_API_KEY`；如果部署了阿里云或 Daytona，则需设置对应提供商的密钥。如果没有该密钥，会话将无法启动；如果不使用 Platinum，项目将无法使用 Drive 功能。
- **模型提供商密钥。** 在首次登录后通过 Web 应用添加。

### 安装

#### 初始化裸机服务器

引导脚本仅支持在 Linux 上运行。如果缺失 Docker 和 Compose 插件，它会自动安装，随后安装 CLI，运行 `kortix self-host init`，设置域名，并执行 `kortix self-host start`。重复运行此脚本是安全的。

| 参数 | 默认值 | 作用 |
|---|---|---|
| `--domain <domain>` | 无 | 设置 `KORTIX_DOMAIN`。启用 Caddy 和 TLS。 |
| `--api-domain <domain>` | `api.<domain>` | 设置 `KORTIX_API_DOMAIN` |
| `--email <email>` | `admin@<domain>` | 设置 `KORTIX_ACME_EMAIL`，用于证书联系邮箱 |
| `--channel <stable\|latest>` | `stable` | 镜像更新通道 |
| `--auto-update <on\|off>` | `on` | 每日自动更新器 |
| `--instance <name>` | `default` | 实例名称 |
| `--platinum-key <key>` | 环境变量中的 `PLATINUM_API_KEY` | 设置 `PLATINUM_API_KEY` |

引导脚本以非交互模式运行 `init`。它不会设置管理员邮箱，因此请在脚本执行完毕后运行 `kortix self-host configure`，然后再运行 `kortix self-host start`。如果引导脚本将您的用户添加到了 `docker` 组，请在执行下一条 `kortix self-host` 命令前打开一个新的 Shell。

#### 手动安装

如果服务器上已经安装了 Docker 和 Compose 插件，请使用此方式（手动安装路径）。

```sh
curl -fsSL https://kortix.com/install | bash
kortix self-host init --domain kortix.example.com --admin-email you@example.com
kortix self-host start
```

首次在终端中运行 `init` 命令时，系统会逐一询问所有的初始化配置问题。如果添加了 `--yes` 参数，或者在没有终端（TTY）的 Shell 中运行，则会跳过这些提问并保留所有默认配置。当实例尚无任何配置时，`start` 命令会先自动执行 `init`。如果缺少 Platinum API 密钥，`init` 和 `start` 会输出一条警告信息，然后继续执行。

#### 使用 Cloudflare 隧道进行试用评估

如果想在您自己的机器上试用 OpenChatly，且无需配置域名：

```sh
kortix self-host init --tunnel cloudflare
kortix self-host start
```

Web 应用会在 `http://localhost:13737` 打开。`cloudflared` 会将 API 发布到一个 `https://<random>.trycloudflare.com` 形式的 URL 上。每次 `cloudflared` 重启时，该 URL 都会发生变化，而 `start` 和 `update` 命令会自动捕获新的 URL。如果您需要一个固定的 URL，请在 Cloudflare Zero Trust 中创建一个命名隧道（named tunnel），将其公共主机名（public hostname）指向 `http://kortix-api:8008`，然后同时设置以下两个值：

```sh
kortix self-host env set CLOUDFLARE_TUNNEL_TOKEN=<token> CLOUDFLARE_TUNNEL_HOSTNAME=kortix-api.example.com
kortix self-host start
```

### 配置（Configure）

运行 `kortix self-host configure` 会按以下顺序重新询问初始化配置问题。每个问题的输入框都会预填当前的配置值，直接按回车键（Enter）即可保留原值。`configure` 命令仅会写入配置文件，需运行 `kortix self-host start` 才能使配置生效。

| 步骤 | 配置项说明 |
|---|---|
| 网络可达性 | `domain`（配置主域名、API 子域名、ACME 邮箱）或 `tunnel`（快速隧道或命名隧道）。 |
| 管理员邮箱 | `KORTIX_PLATFORM_ADMIN_EMAILS`，多个邮箱以逗号分隔。这些用户将被设为平台管理员。也可通过 `--admin-email <email>` 设置。 |
| 企业版许可证 | `ENTERPRISE_LICENSE_AVAILABLE`。启用许可证后，将解锁 SSO、SCIM、基于角色的访问控制（RBAC）、审计和品牌定制功能。拥有最早品牌定制的公司账号，或 `KORTIX_PLATFORM_ADMIN_EMAILS` 中管理员的个人账号，将决定登录页面的品牌展示（`GET /v1/access/branding`）。也可通过 `--enterprise-license` 设置。 |
| 限制账号创建 | 默认开启。仅平台管理员可创建新账号，其他用户将收到 `403 account_creation_restricted` 错误。常规注册、邀请、SSO 以及个人账号的创建依然有效。也可通过 `--no-restrict-account-creation` 和 `--restrict-account-creation` 设置。 |
| 沙箱提供商 | `platinum`、`alibaba` 或 `daytona`，配置将写入 `ALLOWED_SANDBOX_PROVIDERS`。此选项仅用于启用可用的提供商；具体新会话使用哪个提供商，需在管理控制台的计算（Compute）设置中指定（详见下文）。此外还需配置对应提供商的相关参数（详见下文）。 |
| 应用托管 | 可选。`KORTIX_APPS_BASE_DOMAIN`，需配置泛域名 DNS 记录。 |
| 预览源地址 | `KORTIX_PREVIEW_BASE_DOMAIN`，建议设为 `p.<domain>`，需配置 `*.p.<domain>` 记录。在域名模式下，默认会要求配置此项。 |
| Composio | 可选。`COMPOSIO_API_KEY`，用于 [connectors（连接器）](/docs/zh/guide#连接器connectors) 的应用目录。 |
| 更新策略 | 自动更新的开启/关闭状态、更新通道、每日更新时间及时区。 |

| 提供商 | 密钥 | 其他配置项及默认值 |
|---|---|---|
| `platinum` | `PLATINUM_API_KEY` | `PLATINUM_API_URL`（`https://api.platinum.dev`），`PLATINUM_TEMPLATE`（可选） |
| `alibaba` | `ALIBABA_SANDBOX_API_KEY` | `ALIBABA_SANDBOX_API_URL`（`https://api.cn-hangzhou.sandbox.aliyuncs.com`），`ALIBABA_SANDBOX_DOMAIN`（`cn-hangzhou.sandbox.aliyuncs.com`），`ALIBABA_SANDBOX_TEAM_ID`，`ALIBABA_SANDBOX_TEMPLATE`，`ALIBABA_SANDBOX_REGION`（`cn-hangzhou`），`ALIBABA_SANDBOX_ENDPOINT`（`sandbox.cn-hangzhou.sandbox.aliyuncs.com`） |
| `daytona`（可选） | `DAYTONA_API_KEY` | `DAYTONA_SERVER_URL`（`https://app.daytona.io/api`），`DAYTONA_TARGET`（`us`） |

> **Info**
>
> **选择提供商与实例规格。** `ALLOWED_SANDBOX_PROVIDERS` 仅列出会话可使用的提供商，并不决定最终使用哪一个。在“管理后台 → 计费（Billing） → 计算（Compute）”中（即 `sandbox_defaults` 和 `compute_rates` 设置），每个提供商对应一行配置——包含实例规格、vCPU/内存/磁盘、阿里云模板固定版本及费率表——新会话将默认落入该行配置的规格。如果某提供商未被启用，则无法选择其对应的配置行。在管理员保存该设置之前，`ALIBABA_SANDBOX_TEMPLATE`、`ALLOWED_SANDBOX_PROVIDERS` 中的首个名称以及 `*_DISK_GB` 的值仅作为初始种子数据；而计费系统始终会根据实际启动的实例规格进行计量扣费。如果未设置 `KORTIX_DEPRECATED_PROVIDERS`，`daytona` 将被自动弃用；若要保留 Daytona 以供选择，请将其设置为空值。

每个实例默认开启 SAML 登录，且 `init` 命令会生成一次 `SAML_PRIVATE_KEY`。在注册身份提供商（Identity Provider）后，请勿更改该密钥：它是该实例的 SAML 身份标识。关于 SSO 的配置，请参阅 [单点登录与目录同步](/docs/zh/guide#单点登录与目录同步)。

#### 更改或添加域名

每个实例拥有一个主域名，并可完整支持任意数量的别名域名。运行 `kortix self-host domain show` 可列出所有域名。

**添加域名。** 将以下记录指向服务器：`<domain>`、`api.<domain>`；如果启用了应用托管和预览源地址，还需配置 `*.apps.<domain>` 和 `*.p.<domain>`。然后运行：

```bash
kortix self-host env set KORTIX_DOMAIN_ALIASES=<domain>[,<domain>]
```

每个别名域名的运作方式与主域名一致：

| 主机名 | 提供的服务 |
|---|---|
| `<alias>`（别名主域名） | Web 前端应用。在此打开的页面会使用同一别名下的 API 和认证服务。 |
| `api.<alias>` | API 服务。 |
| `*.apps.<alias>`、`*.p.<alias>` | 应用和沙箱预览。应用在别名下展示的链接也会使用该别名。 |

邮件发送、沙箱回调和 Webhook 仍然使用主域名。用户在打开的每个域名上都需要单独登录一次。SAML SSO 仅使用主域名：在别名上发起的 SSO 登录，最终会在主域名上完成。若要停用某个别名，只需将其从列表中移除即可。

**更换主域名。** 将新域名的 DNS 记录指向服务器，然后运行：

```bash
kortix self-host domain move <domain>
```

该命令会检查每个新域名是否都解析到与当前主域名相同的 IP 地址。如果有任何一个解析不一致，命令将不会执行任何更改，并列出需要修复的域名（可通过 `--skip-dns-check` 跳过此检查）。随后，命令会显示即将发生的更改并要求您确认；在脚本中可通过传入 `--yes` 参数来自动确认。确认后，它会写入新配置并运行 `caddy validate` 进行校验。接着，它会逐个副本地滚动更新前端、API 和网关服务，并重启 Caddy 和认证服务，整个过程仅需几秒钟。如果校验失败，系统会自动恢复到之前的配置。旧域名下的子主机名会随之迁移，且旧域名会自动变为别名，因此所有旧链接都能继续正常工作。

请重新注册外部服务中保存的 URL：包括 GitHub App 的回调地址（callback）和 OAuth 的重定向 URI（redirect URIs）。

如果用户使用 SAML SSO 登录，请务必在更换主域名**之前**更新身份提供商（Identity Provider）。因为服务提供者（SP）的实体 ID（Entity ID）和 ACS URL 是跟随主域名的，在身份提供商更新这些配置之前，所有的 SSO 登录都会失败。Microsoft Entra ID 和 Okta 支持配置多个值，因此您可以在现有值旁边添加新值：

| 字段 | 值 |
|---|---|
| 标识符（Entity ID） | `https://<domain>/auth/v1/sso/saml/metadata` |
| 回复 URL（ACS） | `https://<domain>/auth/v1/sso/saml/acs` |
| 登出 URL | `https://<domain>/auth/v1/sso/saml/slo` |

#### 证书与安全过滤机制

家用路由器和 ISP 的安全过滤器（例如 Spectrum Security Shield 和 Xfinity Advanced Security）会在威胁情报源将某个域名评定为高风险时，直接拦截整个域名，此时被拦截的浏览器会显示 `ERR_SSL_PROTOCOL_ERROR` 错误。这些情报源读取的信号之一是公开的证书透明度（Certificate Transparency）日志：Caddy 签发的每张证书都会将其主机名记录在该日志中。如果每个主机名单独签发一张证书，日志中就会列出所有的应用和沙箱预览，且预览名称在设计上就是随机的（如 `dev-p3000-<sandbox>.p.<domain>`）。同一域名下大量看似随机的名称，很容易被误判为恶意软件基础设施。

解决方案是为应用和预览服务按基础域名分别签发一张泛域名证书：

```bash
kortix self-host tls wildcard --zone acme.<domain>
```

泛域名证书需要通过 ACME DNS-01 挑战进行验证。OpenChatly 不需要您提供 DNS 提供商的 API 令牌：该命令会在您的服务器上启动一个轻量级 DNS 服务器（acme-dns），它仅响应一个专属区域 `acme.<domain>` 的查询，并打印出您需要在 DNS 中一次性添加的记录。如需使用其他区域名称，请传入 `--zone <zone>` 参数。该命令会自动获取服务器的公网 IPv4 地址以及 53 端口绑定的地址。如果自动获取失败，请手动传入 `--public-ip <address>` 或 `--listen-ip <address>`。

| 记录名称 | 类型 | 记录值 |
|---|---|---|
| `acme.<domain>` | NS | `ns.acme.<domain>` |
| `ns.acme.<domain>` | A | 服务器的公网 IPv4 地址 |
| `_acme-challenge.apps.<domain>` | CNAME | 命令输出的值 |
| `_acme-challenge.p.<domain>` | CNAME | 命令输出的值 |

每个别名域名都需要添加对应的两条 CNAME 记录。服务器必须允许来自任何来源的 UDP 和 TCP 53 端口入站流量（需在云防火墙或安全组中配置规则）。acme-dns 仅服务于其专属区域，不会响应任何其他查询。

泛域名设置所暴露和存储的内容如下：

| 组件 | 位置 | 访问权限 |
|---|---|---|
| acme-dns DNS 服务器 | 服务器本机地址的 UDP 和 TCP 53 端口（`KORTIX_ACME_DNS_LISTEN_IP`） | 互联网。它仅响应 `acme.<domain>` 区域：包括该区域的 NS 和 A 记录以及当前的挑战 TXT 值。它不是一个递归解析器。 |
| acme-dns API（用于注册账号、写入挑战值） | 服务器上的 `127.0.0.1:13750`，以及 Compose 网络内的 `http://acme-dns` | 仅限服务器本机和 Caddy 容器。它永远不会在公网地址上发布。 |
| 账号凭证，每个基础域名一个文件 | `<instance>/acme-dns/accounts/<base>.json`，文件权限 `0600`，目录权限 `0700` | 仅限服务器 root 用户和 Caddy 容器（只读）。 |

该命令仅在凭证的所有字段完全符合 acme-dns 格式（UUID、密码字母表、完整的 `<subdomain>.acme.<domain>` 域名）时才接受该账号。它会拒绝任何其他格式，且不会将其他字段写入磁盘。如果凭证文件未通过相同的格式检查，系统会使用新注册的账号替换它，并打印新的 CNAME 值。代码扫描器可能会标记此处的两个数据流：凭证从 HTTP 响应写入文件，再从该文件读取并用于 HTTP 请求。这两种行为均经过审查，属于预期设计并被保留：数据从服务器本机的 acme-dns（通过回环地址）写入 `0600` 权限的文件，再从该文件读回至同一个 acme-dns。

添加记录后，请再次运行该命令。它会通过该区域的权威名称服务器和公共解析器检查这些记录，并仅切换记录验证通过的基础域名。如果某个基础域名没有配置记录，它将保持“每个主机名单独一张证书”的模式，因此不会影响任何服务的正常运行。首次切换时，系统会使用 OpenChatly Caddy 镜像（`kortix/caddy`，内置 acme-dns 模块）重启一次 Caddy，耗时几秒钟；后续的切换则会平滑重载 Caddy，不会断开现有连接。Caddy 会自动续期泛域名证书。运行 `kortix self-host tls show` 可查看每个主机的证书获取方式。若要恢复为“每个主机名单独一张证书”的模式，请使用 `kortix self-host env set` 从 `KORTIX_WILDCARD_TLS_BASES` 中移除对应的基础域名。

其他有助于避免域名被上述安全过滤器拦截的规则：

- 为每个实例使用独立的域名。不要在无关的实例之间共享同一个父域名：父域名一旦被拦截，其下的所有实例都会受到牵连。
- 不要将任何 DNS 记录指向实例未拥有的地址，并及时删除已停用主机的记录。
- 对上述所有记录关闭 Cloudflare 代理（设置为 "DNS only"）。Caddy 需要直接的路径来签发证书。

### 首次登录与初始化设置

1. **注册管理员账号。** 打开 `https://<domain>`，使用 `KORTIX_PLATFORM_ADMIN_EMAILS` 列表中的邮箱进行注册。密码、邮箱验证码或社交登录方式均可匹配该列表。SAML 登录方式不适用。若需后续更改管理员，请设置完整的逗号分隔列表：`kortix self-host env set KORTIX_PLATFORM_ADMIN_EMAILS=you@example.com,ops@example.com`。该值会完全替换现有列表。
2. **连接托管 Git。** 打开 `/admin/git`。OpenChatly 会通过此 GitHub 身份创建并推送每个新项目仓库。请选择 **Create a GitHub App**（推荐）、**Paste an existing App** 或 **Use an access token**。在完成此设置之前，OpenChatly 无法创建项目仓库，但您仍然可以连接现有的仓库。详见 [Git](#git版本控制)。
3. **创建团队账号。** 您刚注册的账号是个人账号。它不能用于 SAML SSO（会报 `403 sso_personal_account` 错误），且项目无法转移到其他账号。创建账号的菜单位于项目内部，因此请先在 `/new` 创建一个项目。在该项目中，打开项目菜单 → **Switch Project** → **Create an account…**。默认情况下，仅平台管理员可以创建账号。请在此账号中邀请您的团队成员并配置 SSO。
4. **在团队账号中创建项目。** 在点击 **Create an account…** 后，OpenChatly 会打开 `/new` 页面，并自动选中新建的账号。
5. **在项目中添加模型密钥：** 进入 **Customize** → **Models** → **Providers**，或运行 `kortix providers set <provider>`。每个项目都需要自己的密钥。自托管实例不包含 OpenChatly 托管的模型。项目可以使用 Platinum API 密钥将 **Platinum** 作为提供商进行连接。详见 [连接您自己的提供商](/docs/zh/guide#模型models)。
6. **开启邮件服务。** 设置一个连接字符串：

   ```sh
   kortix self-host env set EMAIL_URL=smtp://user:password@smtp.example.com:587
   ```

随后，OpenChatly 将通过该服务发送登录和邀请邮件，要求新账号进行邮箱验证，并启用魔法链接（Magic-link）登录。`EMAIL_FROM` 的默认值为 `OpenChatly <noreply@<domain>>`。其他支持的格式包括：`smtps://user:password@host:465`、`resend://<api-key>`、`ses://<key-id>:<secret>@<region>`、`ses://<region>`、`mailtrap://<api-token>`。可使用逗号分隔多个配置以构建回退链（fallback chain），系统将从左到右依次尝试。

7. **关闭注册。** 当您的团队成员都完成注册后，请运行 `kortix self-host env set DISABLE_SIGNUP=true`，然后运行 `kortix self-host start` 以使认证服务读取该配置。

新实例启动时的默认配置如下：

| 配置项 | 默认值 |
|---|---|
| 登录方式 | 仅限密码登录。邮箱注册无需通过邮件验证，因此注册时使用的邮箱地址处于未验证状态。详见 [未验证的邮箱地址](#未验证的邮箱地址)。 |
| 社交登录 | 无 |
| 计费功能 | 关闭 |
| 营销页面 | 关闭。所有营销路由都会直接打开 Web 应用。可通过设置 `KORTIX_PUBLIC_DISABLE_LANDING_PAGE=false` 开启。 |
| 连接器应用目录 | 在设置 `COMPOSIO_API_KEY` 之前处于隐藏状态 |
| 账号创建 | 仅限平台管理员 |

### 加固实例安全

`kortix self-host doctor` 会执行以下检查。当所有检查均通过时，命令以退出码 `0` 结束；当有任何一项失败时，以退出码 `1` 结束。使用 `--json` 参数可将结果以 JSON 格式输出。

| 检查项 | 失败条件 | 修复方法 |
|---|---|---|
| `docker` | `docker --version` 执行失败 | 安装 Docker。 |
| `docker-compose` | 缺少 Compose 插件 | 安装 Compose 插件。 |
| `compose-config` | 渲染生成的 `docker-compose.yml` 无效 | 使用 `env set` 修正错误提示中指出的值。 |
| `capture-store` | Compose 文件中没有 `capture-store` 服务，导致 Capture 设备无法同步。如果实例设置了 `KORTIX_CAPTURE_STORE=external`，则不包含该服务，同样会触发此检查失败。 | 运行 `kortix self-host update`。 |
| `instance-dir` | 实例目录自上次写入后发生了移动 | 运行 `kortix self-host configure`，或执行 `init`、`start`、`update`、`env set` 中的任意一个。 |
| `email-url` | 已设置 `EMAIL_URL` 但无法解析 | 修正该值。 |
| `preview-origins` | 处于域名模式且 `KORTIX_PREVIEW_BASE_DOMAIN` 为空 | 将 `*.p.<domain>` 指向服务器，然后运行 `kortix self-host env set KORTIX_PREVIEW_BASE_DOMAIN=p.<domain> KORTIX_PREVIEW_ALLOW_DIRECT_EDGE=true`。 |
| `wildcard-tls` | 处于域名模式，但应用或预览的基础域名仍在使用“每个主机名单独一张证书” | 运行 `kortix self-host tls wildcard` 并添加其输出的 DNS 记录。详见 [证书与安全过滤机制](#证书与安全过滤机制)。 |
| `open-sign-up` | 域名或隧道实例开放了注册，且未开启邮箱验证 | 设置 `EMAIL_URL`，或在团队成员注册完成后设置 `DISABLE_SIGNUP=true`。 |

> **Warning**
>
> 新实例在默认情况下会跳过邮件验证，直接确认所有注册。在您修复 `open-sign-up` 问题之前，任何能够访问该实例的人都可以为任意邮箱地址（包括管理员邮箱）创建并验证账号。请先以管理员身份注册，然后再设置 `EMAIL_URL` 或 `DISABLE_SIGNUP=true`。在域名或隧道实例上运行 `kortix self-host init` 时，也会打印此警告。
>
> 使用 `init --disable-signup` 可以在首次启动时直接关闭注册，适用于通过其他方式创建账号的安装场景。在关闭注册期间，任何人都无法注册，包括管理员。

服务栈默认的安全机制：

- 仅 Caddy 对外发布 80 和 443 公共端口。其他所有发布的端口均绑定在 `127.0.0.1`。
- `.env` 和 `docker-compose.yml` 的文件权限被设置为 `0600`。
- [Connectors（连接器）](/docs/zh/guide#连接器connectors) 会拒绝访问私有和内部地址，并返回 `connector_egress_blocked`。可在 `KORTIX_CONNECTOR_EGRESS_ALLOW_HOSTS` 中列出允许连接器访问的内部主机。
- `kortix-updater` 需要挂载 Docker Socket，因此其镜像版本通过摘要（digest）固定。

请妥善保管 `.env` 文件：它包含了所有的密钥，且其中的 `API_KEY_SECRET` 用于加密所有存储的密钥、连接器凭证和令牌。如果丢失 `API_KEY_SECRET`，这些加密数据将无法读取。在“密钥（Secrets）”页面，此类项目密钥会被标记为 **Undecryptable（无法解密）**；在 **Customize** → **Models** → **Providers** 中，每个账号密钥和 ChatGPT 登录凭证也会显示相同标记。

连接器凭证不会显示标记：通过该凭证发起的调用会返回 `credential_undecryptable` 错误。启动会话时会提示所需的首个缺失值，任何需要该值的后续请求都会返回 `409 SECRET_UNDECRYPTABLE`。请重新输入每个值以修复问题，并在重新连接账号之前，重新保存每个 OAuth 应用。

#### 未验证的邮箱地址

在您设置 `EMAIL_URL` 之前，`ENABLE_EMAIL_AUTOCONFIRM=true` 为默认值。此时，认证服务会在不发送邮件的情况下直接确认每次注册，API 也会从 `.env` 中读取相同的值。当该值为 `true` 时，API 会将密码、邮箱验证码或社交登录使用的邮箱视为“未经验证”。该邮箱地址归属于第一个使用该地址注册的用户：

| 路径/场景 | 当 `ENABLE_EMAIL_AUTOCONFIRM=true` 时的行为 |
|---|---|
| 使用待处理的邀请登录 | 登录不会接受该邀请。 |
| 针对该地址的 SCIM `POST /Users` 请求 | 创建一个待处理的邀请（`201`），不建立成员关系。密码登录不会看到该邀请，接受或拒绝该邀请会返回 `403 email_unconfirmed`。邀请页面随后会显示 **Continue with single sign-on（继续使用单点登录）**。用户可通过账号的 SAML 提供商登录（即使邮箱不在该提供商的域名下）并加入团队。管理员也可以点击待处理邀请上的 **Resend（重新发送）**：此时该邀请变为用户主动发出的邀请。 |
| **Members** → **Invite**（针对该地址） | 创建一个待处理的邀请，而不是直接添加登录账号。 |
| 用户发出或重新发送的邀请（**Members** → **Invite** 或 **Resend**，即项目邀请） | 持有该地址的登录账号会在项目选择器和 **Switch Project** 菜单中看到该邀请，并可以接受它。该登录账号是第一个使用该地址注册的人，因此可能并非您原本想邀请的人。 |
| `KORTIX_PLATFORM_ADMIN_EMAILS` | 匹配使用该地址的密码登录。第一个使用白名单地址注册的用户将成为平台管理员。 |

已经是账号成员的登录账号，以及通过该账号自身的 SAML 提供商进行的登录，在该账号内依然可以正常匹配。`KORTIX_PLATFORM_ADMIN_EMAILS` 永远不会匹配 SAML 登录。设置 `EMAIL_URL` 会关闭 `ENABLE_EMAIL_AUTOCONFIRM` 并恢复正常的匹配逻辑。在开启自动确认期间创建的登录账号不会被再次验证：添加邮件服务后，其邮箱地址会像已验证地址一样正常匹配邀请和 SCIM 请求。

请在邀请他人之前设置 `EMAIL_URL`。如果没有设置，只能在对方完成注册后才能发出邀请：因为一个邮箱地址只能对应一个密码登录账号，一旦注册，其他人将无法占用该地址。云实例永远不会设置该值。

### 平台管理员控制台

平台管理员可打开 `/admin` 页面。在自托管实例中，平台管理员是指在 `KORTIX_PLATFORM_ADMIN_EMAILS` 中列出的用户。

| 页面 | 路径 | 包含内容 |
|---|---|---|
| 概览（Overview） | `/admin` | 实例实时数据，每 15 秒刷新一次。 |
| 账号（Accounts） | `/admin/accounts` | 所有账号。支持筛选、排序和查看单个账号详情。 |
| 项目（Projects） | `/admin/projects` | 所有账号下的所有项目，按活跃度降序排列，并显示由运维人员管理的功能标志（feature flags）。 |
| 分析（Analytics） | `/admin/analytics` | 按 UTC 日期统计的平台每日活动。 |
| 沙箱（Sandboxes） | `/admin/sandboxes` | 新沙箱的分配位置及实时运行的沙箱集群。 |
| 连接器（Connectors） | `/admin/connectors` | 连接器目录中列出的应用。当用户所在网络无法访问某供应商的登录页面时，可在此屏蔽该供应商的域名。 |
| Git | `/admin/git` | 实例托管的 GitHub 身份。当通过 `MANAGED_GIT_*` 环境变量设置时，此页面为只读。 |
| 维护（Maintenance） | `/admin/utils` | 系统级通知和全面锁定开关。 |

### 连接您的客户端

只要您提供实例的地址，每一个 OpenChatly 客户端都会与您的实例通信。Web 应用位于 `https://<domain>`，API 位于 `https://api.<domain>`。

| 客户端 | 接入实例的方式 |
|---|---|
| Web | 打开 `https://<domain>` 并登录。 |
| CLI | 运行 `kortix self-host start` 会注册 CLI 主机 `selfhost` 并将其设为活动主机。然后运行 `kortix login`，并在浏览器中批准登录请求。在另一台计算机上，请运行 `kortix hosts login selfhost --api https://api.<domain>`。运行 `kortix hosts use cloud` 可切换回 OpenChatly Cloud。 |
| 桌面端 | 首次启动时选择 **Self-hosted（自托管）** 并输入 `<domain>`。之后可通过 **OpenChatly** → **Change OpenChatly Instance…（更改 OpenChatly 实例…）** 进行修改。 |
| 移动端 | 在登录界面选择 **Self-hosted（自托管）**，输入 `<domain>` 并选择 **Connect（连接）**。 |
| 其他 AI 工具（MCP） | 将 `https://api.<domain>/v1/mcp` 添加到该工具中并登录。详见 [其他 AI 工具（MCP）](/docs/zh/guide#其他-ai-工具mcp)。 |

如需使用您自己的身份提供商实现用户登录，请参阅 [单点登录与目录同步](/docs/zh/guide#单点登录与目录同步)。有关 CLI 命令，请参阅 [CLI](/docs/zh/developers#cli命令行界面)。

### 集成配置

这些配置通过 `kortix self-host env set` 进行设置。下表每一行说明相应变量开启或关闭的功能。

| 变量 | 作用 |
|---|---|
| `COMPOSIO_API_KEY` | 连接器应用目录。未设置时，Easy connect（一键连接）、`/connections` 页面以及引导流程中的应用选择步骤将被隐藏。自定义连接器无需该项即可正常工作。 |
| `KORTIX_OAUTH_CLIENTS` | 为您自己的 OAuth 客户端配置 [应用目录](/docs/zh/guide#连接器connectors) 中那些服务器不支持动态客户端注册的应用。JSON 格式，每个供应商一条记录：`google`、`github`、`slack`、`hubspot`、`asana`、`box`。若缺少对应记录，这些应用将不会被列出。详见 [OpenChatly OAuth 客户端](#openchatly-oauth-客户端)。 |
| `SLACK_CLIENT_ID`、`SLACK_CLIENT_SECRET`、`SLACK_SIGNING_SECRET` | 使用您自己的 Slack 应用实现一键 **Add to Slack（添加到 Slack）**。若三个值未全部设置，则每个项目需各自连接自己的 Slack 应用。详见 [频道（Channels）](/docs/zh/guide#频道channels)。 |
| `MICROSOFT_APP_ID`、`MICROSOFT_APP_PASSWORD`、`MICROSOFT_APP_TENANT`（默认 `botframework.com`） | 一个共享的 Microsoft Teams 机器人。若未设置，则每个项目需自带自己的机器人应用。 |
| `DISCORD_APPLICATION_ID`、`DISCORD_PUBLIC_KEY`、`DISCORD_CLIENT_SECRET`、`DISCORD_BOT_TOKEN`；可选 `DISCORD_REDIRECT_URI` | 使用您自己的 Discord 应用实现 **Add to Discord（添加到 Discord）**。请在 Discord Developer Portal（Discord 开发者门户）中创建应用，开启 **Requires OAuth2 Code Grant（需要 OAuth2 授权码模式）**，并将 `<api>/v1/webhooks/discord/oauth/callback` 添加为 OAuth2 重定向地址。妥善保存机器人令牌（bot token）和客户端密钥（client secret），然后运行 `apps/api/scripts/discord-app-setup.ts`（步骤见该脚本文件头部说明）：它会检查门户设置、写入应用 ID 和公钥，并在 API 使用这些值运行后，将交互端点 URL（Interactions Endpoint URL）设为 `<api>/v1/webhooks/discord`。若四个值未全部设置，Discord 将显示为未配置状态。设置 `DISCORD_MESSAGE_CONTENT=true`（并为该应用开启 **Message Content（消息内容）** 意图）后，OpenChatly 线程（thread）中的每一条消息都能送达代理（agent）；若不开启，则线程中的消息必须 @ 提及该应用才能触达。当 Discord 拒绝授予该意图时，OpenChatly 会记录一条错误日志并在不启用它的情况下继续运行：@ 提及和私信仍可正常工作。对于运行在 100 个及以上服务器中的应用，Discord 要求进行验证；当达到 75 个时 OpenChatly 就会记录一条警告。详见 [频道（Channels）](/docs/zh/guide#频道channels)。 |
| `KORTIX_CAPTURE_STORE=external`、`KORTIX_CAPTURE_S3_BUCKET`、`KORTIX_CAPTURE_S3_REGION`、`KORTIX_CAPTURE_STS_ROLE_ARN` | 将 [OpenChatly Capture](/docs/zh/capture) 的录屏文件保存在您自己的 S3 存储桶中，而非内置的 `capture-store`。设备会直接上传到该存储桶。API 会扮演（assume）指定的 IAM 角色，并为每台设备授予其专属文件夹的访问凭证。存储桶需由您自行创建。若使用非 AWS 的对象存储，还需设置 `KORTIX_CAPTURE_S3_ENDPOINT`、`KORTIX_CAPTURE_STS_ENDPOINT`、`KORTIX_CAPTURE_S3_PUBLIC_ENDPOINT`、`KORTIX_CAPTURE_S3_FORCE_PATH_STYLE=true`，以及密钥对 `KORTIX_CAPTURE_S3_ACCESS_KEY_ID` 和 `KORTIX_CAPTURE_S3_SECRET_ACCESS_KEY`。若未设置存储桶或角色，设备请求凭证时会返回 `503 capture_credentials_unavailable`。设置完成后请运行 `kortix self-host start`。 |
| `RESEND_API_KEY` | 通过 Resend 发送事务性邮件。 |
| `TUNNEL_ENABLED` | 默认 `true`。设为 `false` 会关闭 [计算机（Computers）](/docs/zh/guide#计算机computers) 功能：`/v1/tunnel/*` 将返回 `503 tunnel_disabled`。 |
| `PLATINUM_API_KEY` | 必需。用于会话、App 机器与卷，以及 Drive（`/drives`）。 |

OAuth 回调地址，例如 `<KORTIX_URL>/v1/connectors/oauth2/callback` 以及 Slack、Teams 的重定向地址，都使用 `KORTIX_URL`。域名模式和命名隧道能保持它稳定不变。快速隧道（quick tunnel）每次重启都会改变它，从而破坏您此前注册的所有回调地址。

### 隐藏用户无法连接的连接器应用

当用户所在的网络位置无法完成某应用的登录时，`/admin/connectors` 会将其排除在目录之外。该配置管理的是供应商域名，而非单个应用：一条记录会隐藏该域名下所有"授权时需在浏览器中打开供应商页面"的应用，子域名同样包含在内。同一供应商下使用 API 密钥认证的应用仍会保留在目录中，完全无需授权的应用也是如此——因为这两类都不会把用户引导到一个可能无法加载的页面上。

无论域名规则如何，单个应用都可以被单独隐藏或强制显示。更改会在 30 秒内同步到目录。**Test all（测试全部）** 按钮会从 API 服务器所在的网络对每个供应商的公开站点进行探测测量：这仅作参考，因为探测所到达的站点并非登录页面，且系统不会据此自动应用任何更改。

实例出厂时已针对本部署所处的市场预置了一套默认配置。**Restore defaults（恢复默认）** 即可回到该配置。

#### OpenChatly OAuth 客户端

目录中的某些 MCP 服务器不允许 OpenChatly 自行注册。OpenChatly 需要通过一个 OAuth 客户端登录它们，该客户端由您在每个实例上、于各供应商处手动创建一次。

1. 在供应商处创建一个 OAuth 应用，其重定向 URI（redirect URI）设为 `<KORTIX_URL>/v1/connectors/oauth2/callback`。
   - Google：使用 **Web application（Web 应用）** 类型的客户端。勾选 **Use this client for an AI-powered agent（将此客户端用于 AI 驱动的智能体）**。启用 Gmail、Calendar、Drive、Docs 和 Sheets API 及其 MCP 服务。添加 Google [MCP 服务器指南](https://developers.google.com/workspace/guides/configure-mcp-servers) 中所列的权限范围（scopes）。Workspace MCP 服务器目前属于 Google 的开发者预览版。
   - GitHub：使用 OAuth 应用（而非 GitHub App）。
2. 将各客户端作为一个 JSON 值进行存储：

   ```sh
   kortix self-host env set KORTIX_OAUTH_CLIENTS='{"google":{"client_id":"<id>","client_secret":"<secret>"},"github":{"client_id":"<id>","client_secret":"<secret>"}}'
   ```

3. 重启 API。每个已配置供应商的应用就会出现在目录中。

#### 需要您自己提供 OAuth 应用的 Composio 工具包

部分工具包没有 Composio 托管的登录方式。同步此类工具包会失败，并返回 `422 composio_auth_config_required` 错误。请在 Composio 控制台（dashboard）中打开 **Auth Configs（认证配置）**，并使用您自己的 OAuth 应用创建一条配置。

然后再次进行同步，无需重启。

### 更新与版本

`kortix-updater` 会在 `KORTIX_UPDATE_TZ`（默认 `America/New_York`）时区的 `KORTIX_UPDATE_TIME`（默认 `02:00`）每天执行一次检查。自动更新默认处于开启状态。

| 更新通道 | 镜像 |
|---|---|
| `stable`（默认） | 在 OpenChatly 生产环境稳定运行后，才向自托管实例推送的正式版本。 |
| `latest` | OpenChatly 发布的每一个版本。 |
| `--tag <version>` | 指定的确切版本。指定具体版本（pin）的优先级高于更新通道。 |

每次更新流程：

1. 检查可用磁盘空间。当剩余空间低于 `KORTIX_MIN_FREE_DISK_MB`（默认 `2048` MB）时，更新将中止。
2. 拉取配置的镜像标签。如果没有任何镜像发生变更，流程将中止。
3. 运行 `kortix-migrate` 执行数据库迁移。如果迁移失败，系统不会替换任何组件，当前版本将继续提供服务。
4. 滚动更新 `kortix-api`、`llm-gateway` 和 `frontend`。当配置为 2 个副本时，新容器必须在 `KORTIX_ROLLOUT_TIMEOUT`（默认 `300` 秒）内通过健康检查，旧容器才会停止，从而保证实例持续可用。如果滚动更新失败，系统将继续使用之前的版本。若仅有 1 个副本，每个服务将在原地重启，期间会出现短暂的停机。
5. 在更新完全成功后，清理被替代的旧镜像。系统会保留当前版本和上一个版本，以便在需要时快速回滚。

`kortix self-host status` 命令会显示最近一次更新的结果（`ok` 成功、`degraded` 降级、`failed` 失败、`skipped` 已跳过或 `never-run` 从未运行）以及版本变更情况。它还会展示运行中的镜像与配置之间的漂移检查（drift check）结果，以及更新计划。您可以设置 `KORTIX_UPDATE_WEBHOOK_URL`，以便通过 JSON `POST` 请求接收每次更新运行的状态。

```sh
kortix self-host update                          # 立即应用当前更新通道（channel）的更新
kortix self-host update --channel latest         # 切换到指定更新通道
kortix self-host update --tag <version>          # 锁定到指定版本
kortix self-host rollback --release <version>    # 回滚到指定版本
kortix self-host version                         # 查看当前运行版本、最新版本及当前更新通道
```

手动执行 `update` 时，系统会采用与每日自动更新相同的滚动发布（rollout）流程。如果此时有其他更新任务正持有锁，命令将以退出码 `75` 结束并跳过本次滚动发布。版本锁定（pin）在每次每日自动更新中都会持续生效。

在不带 `--tag` 参数的情况下运行 `init` 或 `update`，会将实例恢复到其所属的更新通道（channel）。若要更改自动更新设置、更新时间或时区，请运行 `kortix self-host configure`，然后再运行 `kortix self-host start`。

#### 升级早于会话日志（session log）功能的实例
<a id="sessions-saved-by-an-older-version" />

如果实例曾运行过不支持会话日志功能的早期版本，其部分会话历史记录会保存在旧版的 v1 存储中。`0.14.9` 版本会在主 API 容器的后台自动转换该存储。转换完成后，日志会输出以下信息：

```text
[session-log] backfill: the session logs hold every v1 mirror message; no code reads the mirror again
```

后续版本不会执行 v1 存储的转换。如果存储中仍存在后台转换任务尚未处理完的会话，其 `kortix-migrate` 步骤将拒绝运行（报错 `session log release refused`）。此时系统不会替换任何组件，当前版本将继续提供服务。若要完成转换：

1. 锁定转换版本：`kortix self-host update --tag 0.14.9`。
2. 等待 `kortix self-host logs kortix-api` 日志中出现上述提示行。
3. 恢复到您的更新通道：`kortix self-host update`。

全新安装的实例无需执行上述步骤即可直接更新。

### 运维与调优

#### 配置与密钥

所有配置项均保存在实例的 `.env` 文件中。

- `kortix self-host env ls` 会按组列出所有配置值，并默认隐藏（掩码处理）密钥。使用 `--show` 参数可显示完整内容。
- `kortix self-host env set KEY=VALUE ...` 用于写入配置值，并重启读取该配置的服务。若仅输入 `KEY`，系统会提示您输入值。由于设置新的 `API_KEY_SECRET` 会导致所有已存储的凭证无法解密，因此 `env set` 命令会提前发出警告。在终端中执行时，系统会要求您确认；在脚本中执行时，必须传入 `--yes` 参数：若未传入，命令将以退出码 `2` 结束，且不写入任何内容。
- `kortix self-host env rotate <KEY>` 或 `--all-generated` 用于重新生成系统自动生成的密钥。轮换 `SUPABASE_JWT_SECRET` 时，还会同时重新生成匿名（anon）和服务角色（service-role）密钥。CLI 会拒绝重新生成 `API_KEY_SECRET`、`POSTGRES_PASSWORD` 和 `SAML_PRIVATE_KEY`，因为新值会导致已存储的数据或连接失效。

`env set` 命令会拒绝修改镜像和版本相关的键（`KORTIX_VERSION`、`API_IMAGE`、`FRONTEND_IMAGE`、`GATEWAY_IMAGE`）。请使用 `--tag` 或 `--channel` 参数来修改这些配置。当配置更改未生效时，请运行 `kortix self-host start`：该命令会重建所有配置发生更改的服务。

#### 内存限制

| 变量 | 默认值 | 容器 |
|---|---|---|
| `KORTIX_API_MEMORY_LIMIT` | `2048m` | `kortix-api`：当 `/v1/llm` 请求体到达时，负责中继该请求体。 |
| `KORTIX_GATEWAY_MEMORY_LIMIT` | `2048m` | `llm-gateway` |
| `KORTIX_FRONTEND_MEMORY_LIMIT` | `512m` | `frontend` |
| `KORTIX_CAPTURE_STORE_MEMORY_LIMIT` | `1024m` | `capture-store` |

Postgres 数据库的内存限制固定为 `1280m`。`KORTIX_GATEWAY_MAX_REQUEST_BYTES` 用于提高网关的请求体大小上限（适用于包含大量图片的对话轮次）。调整该值时，请同步提高网关的内存限制。

#### 会话与沙箱生命周期

| 变量 | 默认值 | 作用 |
|---|---|---|
| `KORTIX_SANDBOX_AUTOSTOP_MINUTES` | `15` | 沙箱在最后一次对话轮次结束后的空闲时长达到此分钟数时自动停止。打开的会话页面不会在此时间窗口内保持沙箱运行。 |
| `KORTIX_SANDBOX_TURN_GRANT_MINUTES` | `240` | 运行中的对话轮次保持沙箱运行的时长。模型调用和观察到的运行中轮次会刷新此计时。 |
| `KORTIX_SANDBOX_TURN_WAITING_MINUTES` | `120` | 等待用户操作的对话轮次保持沙箱运行的时长。最长不超过轮次授权时长（turn grant）的一半。无人值守的运行任务默认获得 30 分钟。 |
| `KORTIX_SANDBOX_PREVIEW_GRANT_MINUTES` | `30` | 预览流量保持沙箱运行的时长。 |
| `KORTIX_SANDBOX_PROVIDER_AUTOSTOP_MINUTES` | `720` | Platinum 自身的空闲停止时间，作为 API 无法触及沙箱时的兜底机制。 |
| `ALLOWED_SANDBOX_PROVIDERS` | `platinum` | 会话可使用的沙箱提供商，以逗号分隔；第一个名称为默认提供商。目前支持 `platinum`、`alibaba` 和 `daytona`。 |
| `KORTIX_DEFAULT_SANDBOX_CPU`、`_MEMORY_GB`、`_DISK_GB` | `2`、`4`、`10` | 当模板未指定沙箱规格时的默认大小（CPU 核数、内存 GB、磁盘 GB）。 |

用户可在 [Computers（计算机）](/docs/zh/guide#计算机computers) 页面直观地看到这些配置值产生的效果。

#### 应用托管（App hosting）

| 变量 | 默认值 | 作用 |
|---|---|---|
| `KORTIX_APPS_BASE_DOMAIN` | 新域名实例下为 `apps.<domain>` | 托管 [Apps（应用）](#应用参考apps-reference) 的域名，例如 `apps.kortix.example.com`。需要配置 `*.apps.kortix.example.com` 的 DNS 记录。可通过 `kortix self-host configure` 进行设置。仅在设置该变量后，Caddy 才会为 Apps 提供服务。 |
| `KORTIX_ACME_DNS_ZONE` | 无 | 内置 acme-dns 响应的专属区域，例如 `acme.kortix.example.com`。可通过 `kortix self-host tls wildcard` 进行设置，同时需配置 `KORTIX_ACME_DNS_PUBLIC_IP`（记录中的地址）和 `KORTIX_ACME_DNS_LISTEN_IP`（53 端口绑定的地址）。详见 [证书与安全过滤机制](#证书与安全过滤机制)。 |
| `KORTIX_WILDCARD_TLS_BASES` | 无 | 配置每个 Apps 和预览（preview）基础域名使用一张泛域名证书。当 DNS 记录验证通过后，`kortix self-host tls wildcard` 会自动添加基础域名。 |
| `KORTIX_APPS_RETAINED_DEPLOYMENTS` | `5` | 每个应用保留的已就绪版本数量（除当前运行版本外），用于回滚。最少保留 `1` 个。 |

#### 日志、容器与数据库控制台

- `kortix self-host logs [service]` 用于实时跟踪日志，例如 `kortix self-host logs kortix-api`。每个容器保留 3 个日志文件，每个文件大小上限为 10 MB。
- `kortix self-host ps` 用于列出所有容器。加上 `status` 参数可额外显示更新报告。
- Supabase Studio 在服务器的 `http://127.0.0.1:13740`（`SUPABASE_PORT`）上响应。请通过 SSH 隧道访问，并使用 `env ls --show` 命令查看 `DASHBOARD_PASSWORD`，以 `kortix` 身份登录。

#### 在同一台服务器上运行多个实例

在每个命令后传入 `--instance <name>` 参数即可指定实例。实例名称必须以字母开头，且只能包含字母、数字、点、下划线和连字符。每个实例拥有独立的目录和 Compose 项目。

由于 Caddy 会占用 80 和 443 端口，每台服务器上只能有一个实例运行在域名模式下。可通过设置 `KORTIX_SELF_HOST_CONFIG_DIR` 将根目录从默认的 `~/.config/kortix/self-host` 迁移到其他位置。

#### Caddy 路由机制

| 主机名（Host） | 路径（Path） | 转发目标 |
|---|---|---|
| `api.<domain>` | `/v1/llm*` | `llm-gateway:8090` |
| `api.<domain>` | 其他所有路径 | `kortix-api:8008` |
| `<domain>` | `/rest/v1`、`/auth/v1`、`/storage/v1`、`/realtime/v1`、`/functions/v1`、`/graphql/v1` | `supabase-kong:8000` |
| `<domain>` | 其他所有路径 | `frontend:3000` |
| `*.<preview base domain>` | 所有路径 | `kortix-api`，每个沙箱端口对应一个 origin |
| `*.<apps base domain>` | 所有路径 | `kortix-api`，每个应用对应一个主机名 |

Caddy 会对每个副本进行健康检查，并在连接失败时自动重试另一个副本。它会发送 `Strict-Transport-Security` 头，`max-age` 设为 30 天。上述两个泛域名路由块仅在设置了相应的基础域名时才会生效。

若未配置泛域名证书，Caddy 会在首次请求时为每个主机名单独获取证书，且 API 会预先验证每个主机名。此时只需配置一条泛域名 DNS 记录即可。执行 `kortix self-host tls wildcard` 后，每个 Apps 和预览基础域名将改用一张泛域名证书。详见 [证书与安全过滤机制](#证书与安全过滤机制)。

### 备份与卸载

服务器将数据保存在两个位置：实例目录 `~/.config/kortix/self-host/<instance>/` 和命名的 Docker 卷。每个 Docker 卷的命名规则为 `kortix-<instance>_<volume>`，例如 `kortix-default_kortix-capture-data`。

| 数据 | 存储位置 | 服务器备份 |
|---|---|---|
| 所有密钥和签名密钥 | 实例目录下的 `.env` 文件 | 是 |
| Postgres 数据库 | 实例目录下的 `volumes/db/data` | 是 |
| 存储的文件 | 实例目录下的 `volumes/storage` | 是 |
| Postgres 配置及其 pgsodium 密钥 | Docker 卷 `db-config` | 是 |
| OpenChatly Capture 录屏文件 | Docker 卷 `kortix-capture-data` | 是 |
| TLS 证书 | Docker 卷 `kortix-caddy-data` | 是 |
| 泛域名证书 DNS 账号 | 实例目录下的 `acme-dns/` 及 Docker 卷 `kortix-acme-dns-data` | 是 |
| 更新器状态、已部署版本及镜像历史记录 | Docker 卷 `kortix-updater-state` | 是 |
| Drive 文件夹与 App 卷 | Platinum 卷，存储在 Platinum 端 | 否 |
| 每个会话的 `/workspace` | 该会话的 Platinum 沙箱 | 否 |

请先停止服务栈（stack）以确保文件状态一致。然后复制实例目录和各个 Docker 卷，最后重新启动服务：

```sh
kortix self-host stop
cd ~
sudo tar -czf kortix-backup.tgz -C ~/.config/kortix/self-host default
for v in db-config kortix-capture-data kortix-caddy-data kortix-updater-state; do
  docker run --rm -v "kortix-default_$v":/data -v "$PWD":/backup alpine:3.20 \
    tar -czf "/backup/$v.tgz" -C /data .
done
kortix self-host start
```

请将命令中的 `default` 替换为您的实际实例名称。由于 `acme-dns/` 目录位于实例目录内部，因此生成的压缩包中已包含该目录。当开启泛域名证书功能时，请将 `kortix-acme-dns-data` 添加到卷列表中进行备份。App 卷会自动保留其每日快照：详见 [Volumes and snapshots（卷与快照）](#卷与快照volumes-and-snapshots)。

若要在已安装 Docker 和 CLI 的服务器上进行恢复，请将备份文件放入您的主目录（home directory），然后运行以下命令：

```sh
cd ~
mkdir -p ~/.config/kortix/self-host
sudo tar -xzf kortix-backup.tgz -C ~/.config/kortix/self-host
for v in db-config kortix-capture-data kortix-caddy-data kortix-updater-state; do
  docker run --rm -v "kortix-default_$v":/data -v "$PWD":/backup alpine:3.20 \
    tar -xzf "/backup/$v.tgz" -C /data
done
kortix self-host start
```

执行 `start` 时可能会提示某个卷 `already exists but was not created by Docker Compose`（已存在但并非由 Docker Compose 创建）。该警告是无害的：服务栈会正常使用这些恢复的卷。

> **Warning**
>
> `kortix self-host uninstall` 命令会执行 `docker compose down --volumes --remove-orphans`，并删除实例目录。该操作会彻底删除数据库、存储的文件、Capture 录屏文件以及证书，且**无法撤销**。
>
> 在终端中执行时，系统会要求您输入实例名称以进行确认。若不在终端环境中执行，则必须传入 `--yes` 参数。

### 命令参考

每个子命令都支持 `--instance <name>` 参数（默认为 `default`）。

| 命令 | 作用 |
|---|---|
| `init` | 写入或刷新 Compose 文件和 `.env`。在终端中首次运行时会询问配置问题。别名：`setup`。 |
| `start` | 拉取镜像并启动服务栈。别名：`up`、`deploy`。 |
| `stop` | 停止服务栈，保留数据。别名：`down`。 |
| `restart` | 先执行 `stop`，再执行 `start`。 |
| `configure` | 重新询问配置问题。别名：`config`。 |
| `status` | 显示容器状态、上次更新、配置漂移及更新计划。支持 `--json`。 |
| `ps` | 仅执行 `docker compose ps`。 |
| `doctor` | 执行 [加固实例安全](#加固实例安全) 中的各项检查。支持 `--json`。 |
| `plan` | 验证 Compose 文件，不应用任何更改。支持 `--json`。 |
| `logs [service]` | 实时跟踪日志。 |
| `open` | 在浏览器中打开 Web 应用。 |
| `version` | 显示当前运行版本、最新正式版及更新通道。 |
| `update` | 立即应用当前通道或 `--tag <version>` 指定的版本。别名：`upgrade`、`reconcile`。 |
| `rollback --release <version>` | 更新到指定版本。也可使用 `--tag`。 |
| `env ls [--show]` | 列出所有配置项。支持 `--json`。 |
| `env set KEY=VALUE ...` | 设置配置值并重启受影响的服务。 |
| `env rotate KEY` 或 `--all-generated` | 重新生成系统自动生成的密钥。 |
| `domain show` | 显示主域名及其别名域名。 |
| `domain move <domain>` | 将 `<domain>` 设为主域名，当前域名保留为别名。`--skip-dns-check` 可跳过 DNS 检查。 |
| `tls show` | 显示每个主机获取 TLS 证书的方式。 |
| `tls wildcard` | 将 Apps 和预览（preview）切换为泛域名证书。支持 `--zone`、`--public-ip`、`--listen-ip`。 |
| `uninstall` | 删除服务栈、所有数据及其目录。 |
| `connect-github` | 已弃用。该命令仅打印 GitHub 连接指引，请使用 `/admin/git`。 |

| 标志（Flag） | 适用命令 | 含义 |
|---|---|---|
| `--domain <domain>` | `init`、`configure`、`update` | 域名模式。`--domain ""` 用于清除域名配置。 |
| `--tunnel cloudflare` | `init`、`configure`、`update` | 隧道模式。 |
| `--tag <version>` | `init`、`update`、`rollback` | 锁定指定版本。别名：`--version`、`--release`。 |
| `--channel <stable\|latest>` | `init`、`update`、`configure` | 指定要跟踪的更新通道。 |
| `--auto-update <on\|off>` | `init`、`update`、`configure` | 开启或关闭每日自动更新。在下次执行 `start` 时生效。 |
| `--update-time <HH:MM>`、`--update-tz <zone>` | `init`、`update`、`configure` | 设置每日更新的 24 小时制时间窗口和 IANA 时区。在下次执行 `start` 时生效。 |
| `--admin-email <email>` | `init`、`configure` | 设置 `KORTIX_PLATFORM_ADMIN_EMAILS`。 |
| `--enterprise-license` | `init`、`configure`、`update` | 设置 `ENTERPRISE_LICENSE_AVAILABLE=true`。 |
| `--restrict-account-creation`、`--no-restrict-account-creation` | `init`、`configure`、`update` | 限制仅管理员可创建账号，或允许所有人创建。 |
| `--disable-signup` | `init`、`configure`、`update` | 设置 `DISABLE_SIGNUP=true`。任何人都无法注册，包括管理员。可通过 `env set DISABLE_SIGNUP=false` 重新开放。 |
| `--yes` | 所有命令 | 接受所有默认值。在无终端环境下执行 `uninstall` 时为必传参数。 |
| `--json` | `status`、`doctor`、`plan`、`env ls` | 输出机器可读的 JSON 格式。 |

## SDK

`@kortix/sdk` 是 OpenChatly API 的 TypeScript 客户端。它可用于创建项目和会话、发送提示词（prompts）、流式接收智能体（agent）的回复以及读取结果。该包包含了适用于服务端、浏览器、React 和 Generative UI 的多个分层模块，而 `@kortix/ui` 则在此基础上提供了预构建的 UI 组件。

### SDK 模块说明

| 入口模块 | 运行环境 | 依赖项 | 适用场景 |
| --- | --- | --- | --- |
| [`@kortix/sdk`](#从代码管理会话) | 通用 | 全局 `fetch` | 从任意运行时调用 API：Node 18+、Bun、浏览器或边缘计算节点（edge worker）。包含核心客户端及所有无框架依赖的模块。 |
| [`@kortix/sdk/server`](#sdk-认证) | 服务端 | `node:async_hooks` | 一个服务端代表多个用户操作、使用 OpenChatly 进行用户登录，或读取 OpenChatly App 的当前查看者。**切勿**将其打包到浏览器端。 |
| [`@kortix/sdk/react`](#react) | 浏览器 | `react` 18+、`@tanstack/react-query` 5.75.2 或更高 5.x 版本 | 在 React 或 React Native 应用中运行会话。`useSession` 负责管理整个会话生命周期。 |
| [`@kortix/sdk/genui/fence`](#生成式-uigenerative-ui) | 通用 | 无 | 仅需检测并拆分智能体文本中的 `openui` 代码块。不加载任何解析器。 |
| [`@kortix/sdk/genui`](#生成式-uigenerative-ui) | 通用 | `zod`、`@openuidev/lang-core` 0.3.1 | 需要解析代码块，或将其转换为 Markdown 格式以用于 CLI、邮件或机器人。 |
| [`@kortix/sdk/genui/react`](#生成式-uigenerative-ui) | 浏览器 | `react`、`zod`、`@openuidev/lang-core` 0.3.1 | 使用自定义的 React 组件来渲染代码块。 |
| [`@kortix/ui`](#ui-组件kortixui) | 浏览器 | `@kortix/sdk`、`react` 19+、`react-dom` 19+、`@tanstack/react-query` | 希望直接使用 OpenChatly 的会话聊天界面及组件，而无需自行构建。 |

各项任务的详细指南将在后续的 H2 章节中提供：[SDK 认证](#sdk-认证)、[通过代码管理会话](#从代码管理会话)、[通过代码管理项目](#通过代码管理项目projects-from-code)、[React 集成](#react)、[Generative UI](#生成式-uigenerative-ui)、[OpenChatly UI](#ui-组件kortixui)。完整的函数签名请参阅 [SDK 参考文档](#sdk-参考sdk-reference)。

### 安装

```bash
npm install @kortix/sdk
```

该包仅支持 ESM（ECMAScript Modules）模块规范。请根据您使用的分层模块，安装相应的可选对等依赖（peer dependencies）：

| 分层模块 | 安装命令 |
| --- | --- |
| `@kortix/sdk/react` | `npm install react @tanstack/react-query` |
| `@kortix/sdk/genui`、`@kortix/sdk/genui/react` | `npm install zod @openuidev/lang-core@0.3.1` |
| `@kortix/ui` | `npm install @kortix/ui`，版本需与 `@kortix/sdk` 保持一致。详见 [OpenChatly UI](#ui-组件kortixui)。 |

对于没有构建步骤（no build step）的页面，可直接加载浏览器打包文件（browser bundle）。它会定义一个全局变量 `Kortix`，其导出的名称与根入口模块相同，例如 `Kortix.createKortix` 和 `Kortix.narrowChatEvent`：

```html
<script src="https://cdn.jsdelivr.net/npm/@kortix/sdk@<version>/dist/kortix.global.js"></script>
```

请将 `<version>` 替换为已发布的版本号。该包还在 `dist/kortix.esm.min.js` 路径下提供了一个 ES 模块（ESM）打包文件。在一个页面中，请仅加载全局打包文件或 ESM 构建版本，**切勿同时加载两者**。如果同时加载，页面中将存在两个 `ApiError` 类，导致 `instanceof ApiError` 判断失败。

浏览器仅在 API 允许的源（origin）下直接调用 OpenChatly API。OpenChatly Cloud 默认允许其自身的源。若从您自己的站点发起浏览器调用，请通过您的服务器进行代理转发，例如使用 [Sign in with OpenChatly（使用 OpenChatly 登录）](#使用-openchatly-登录) 中的同源代理（same-origin proxy）。对于自托管实例，可通过 API 的 `CORS_ALLOWED_ORIGINS` 配置项来添加允许的源。

### 创建客户端

每个进程只需调用一次 `createKortix`，并传入 API 的基础 URL（base URL）以及一个用于返回令牌（token）的函数。

```ts
import { createKortix } from '@kortix/sdk';

export const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => process.env.KORTIX_API_KEY ?? null,
});
```

| 选项 | 类型 | 作用 |
| --- | --- | --- |
| `backendUrl` | `string`，必填 | API 的基础 URL，需包含 `/v1`。OpenChatly Cloud 的地址为 `https://api.kortix.com/v1`。自托管实例的地址为其 API 的源（origin）加上 `/v1`。 |
| `getToken` | `() => Promise<string \| null>`，必填 | 返回凭证，若无人登录则返回 `null`。SDK 会在每次请求时调用此函数，且不会存储任何内容。凭证的存储与刷新由您的宿主应用负责。支持缓存的 getter 可以携带 `invalidate(rejectedToken)` 方法：当收到 `401` 响应时，SDK 会在重试前调用此方法。详见 [SDK 认证](#sdk-认证)。 |
| `credentialHeader` | `string` | 将原始令牌通过此自定义请求头发送，而非默认的 `Authorization: Bearer`。适用于读取自定义请求头的代理场景。 |
| `clientVersion` | `string` | 您的应用标识及版本，格式为 `<surface>/<version>`，例如 `my-app/1.2.0`。SDK 会将其作为 `X-Kortix-Client-Version` 发送。API 仅将其写入请求日志，不会赋予任何额外权限。 |
| `fetch` | fetch 形状的函数 | 用于测试、边缘计算运行时（edge runtimes）和适配器的 fetch 实现。默认使用全局的 `fetch`。 |
| `eventStreamTransport` | `RuntimeEventTransport` | 当您的 `fetch` 无法流式传输响应体时（例如没有 `expo/fetch` 的 React Native），通过此选项传递事件流的字节数据。SDK 仍会保持重连、恢复和心跳机制。默认使用配置好的 `fetch` 并以流的形式读取。 |
| `getUserId` | `() => Promise<string \| null>` | 返回当前用户 ID。SDK 会据此对离线消息缓存进行作用域隔离。 |
| `billingEnabled` | `boolean` | 开启 `@kortix/ui` 的计费拦截功能：包括升级提示和余额提示。默认关闭。 |
| `sandboxId` | `string \| null` | 针对仅拥有单个本地沙箱的宿主应用，设置默认的沙箱 ID。 |
| `featureFlags` | `KortixFeatureFlagOverrides` | 针对没有 `NEXT_PUBLIC_*` 构建时变量的宿主应用（如 React Native 或 CLI），提供按标志（flag）覆盖的配置。 |
| `onError` | `(error, context?) => void` | 错误处理回调，可用于显示 Toast 或记录日志。默认无操作（no-op）。 |
| `onAccessRemedy` | `(code: 'sso_required' \| 'account_mfa_required') => void` | 当 API 拒绝请求，直到用户通过单点登录（SSO）或完成多因素认证（MFA）后才放行时触发。仅针对 REST 响应触发，不适用于会话运行时及其事件流。浏览器还会收到 `kortix:sso-required` 和 `kortix:mfa-required` 的 window 事件。默认无操作。 |
| `onToast` | `(level, message, options?) => void` | Toast 提示回调。`level` 的值为 `'info'`、`'success'`、`'error'` 或 `'warning'`。由您的宿主应用负责渲染。 |
| `onNotify` | `(event: { kind, sessionId, ... }) => void` | 操作系统或 Web 通知回调。由您的宿主应用负责渲染。React 层会将对话轮次结束的通知发送到此处。 |

> **Warning**
>
> 客户端在整个进程中仅持有一份配置。如果使用不同的 `backendUrl` 或 `getToken` 再次调用 `createKortix()`，将会重新指向所有先前的客户端，并在控制台输出一条警告。若服务器需要同时为多个用户提供服务，请使用 `@kortix/sdk/server` 中的 `createScopedKortix()` 为每个请求创建独立的客户端。详见 [从单一后端服务多用户](#从单一后端服务多用户)。

客户端提供的句柄（如 `kortix.projects`、`kortix.project(projectId)`、`kortix.session(projectId, sessionId)`、`kortix.auth`、`kortix.accounts` 等）均在 [SDK 参考文档](#sdk-参考sdk-reference) 中列出。`kortix.validateToken()` 方法用于检查 `getToken` 当前返回的令牌是否有效，并解析为 `{ valid, identity?, error? }`。该方法永远不会抛出异常。

### 获取 API 密钥

脚本、CI 任务或服务器可通过个人访问密钥（Personal Access Key）进行认证。该密钥以 `kortix_pat_` 开头。您可以在 Web 应用的 **Settings → Personal access keys（设置 → 个人访问密钥）** 中创建，或使用 CLI 创建：

```bash
kortix tokens new my-script --expires 90d
```

OpenChatly 仅在创建时显示一次密钥。请将其作为机密信息（secret）妥善存储，并通过 `getToken` 函数返回。对于无需绑定特定个人身份的无人值守自动化任务，请使用服务账号密钥（以 `kortix_sa_` 开头，在 **Account settings → API keys（账号设置 → API 密钥）** 中创建）。

> **Warning**
>
> 个人访问密钥等同于您本人的身份操作。请务必将其保留在服务器端，**切勿**将其打包到浏览器端代码、移动应用或公开代码仓库中。浏览器应用应改用 [Sign in with OpenChatly（使用 OpenChatly 登录）](#使用-openchatly-登录) 进行用户认证。关于各类凭证及其适用运行环境的详细说明，请参阅：[选择凭证](#选择凭证)。

### 您的第一个会话

以下脚本会在您的首个项目中创建一个会话，等待其准备就绪，发送一条提示词（prompt），以流式方式接收事件直到当前对话轮次结束，最后输出智能体（agent）的最终回复文本。

```ts title="first-session.mts"
import { createKortix, narrowChatEvent } from '@kortix/sdk';

const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => process.env.KORTIX_API_KEY ?? null,
});

const [project] = await kortix.projects.list();
if (!project) throw new Error('No project. Create one with kortix.projects.provision({ name }).');
const { session_id } = await kortix.project(project.project_id).sessions.create({ name: 'First session' });
const session = kortix.session(project.project_id, session_id);
const { runtimeSessionId } = await session.ensureReady();

const replyIds = new Set<string>();
const textParts = new Map<string, { messageID: string; text: string }>();
let finish!: (error?: unknown) => void;
const turnEnded = new Promise<unknown>((resolve) => (finish = resolve));

const stream = await session.stream({
  onEvent: (raw) => {
    const e = narrowChatEvent(raw);
    if (!e || ('sessionID' in e && e.sessionID && e.sessionID !== runtimeSessionId)) return;
    if (e.type === 'message.updated' && e.message.role === 'assistant') replyIds.add(e.message.id);
    if (e.type === 'message.part.updated' && e.part.type === 'text') textParts.set(e.part.id, e.part);
    if (e.type === 'session.idle' && replyIds.size > 0) finish();
    if (e.type === 'session.error') finish(e.error ?? 'session.error');
  },
});

await session.send('List the top-level files in this repository.');
const error = await turnEnded;
stream.close();
if (error) throw error;
for (const part of textParts.values()) if (replyIds.has(part.messageID)) console.log(part.text);
```

使用 Bun 或 `tsx` 运行它：

```bash
KORTIX_API_KEY=kortix_pat_... bun first-session.mts
KORTIX_API_KEY=kortix_pat_... npx tsx first-session.mts
```

各步骤的具体作用如下：

1. `sessions.create()` 返回包含 `session_id` 的会话记录。同时，沙箱会在后台开始预配（provision）。
2. 当运行时（runtime）准备好接受任务时，`ensureReady()` 会完成解析（resolve）。它返回 `runtimeSessionId`，即根对话的 ID。默认最长等待时间为 180 秒。
3. `stream()` 会在 `send()` 之前打开，以确保脚本不会错过任何早期事件。
4. 当提示词（prompt）被成功存储时，`send()` 即完成解析，而不是等到当前对话轮次结束。
5. `narrowChatEvent()` 将原始的运行时事件过滤并转换为聊天事件。每个 `message.part.updated` 事件都携带完整的消息片段（part），因此该映射机制会保留每个片段的最新文本。
6. 当收到针对 `runtimeSessionId` 的 `session.idle` 事件，且已存在助手消息时，当前对话轮次结束。若收到 `session.error` 事件，则当前轮次以错误状态结束。

每次运行都会创建一个新会话，该会话会在 Web 应用中显示，并保留相同的对话记录。关于如何回答问题、处理权限请求、文件操作、错误及重试机制，请参阅 [通过代码管理会话](#从代码管理会话)。

### 版本与稳定性

- `@kortix/sdk` 会随 OpenChatly 平台的每次发布同步发布到 npm，并携带对应的发布版本号。
- 以下入口模块遵循语义化版本（semver）规范：`@kortix/sdk`、`/react`、`/server`、`/genui`、`/genui/fence`、`/genui/react`、`/wire-message-id`、`/workspace-search` 和 `/capture-rules`。
- 导出的名称（包括类型）构成公开契约。若导出名称被重命名，将保留带有 `@deprecated` 标记的别名，直到下一个主版本发布。
- `@kortix/sdk/internal/*` 专为 OpenChatly Web 应用内部提供服务，不受语义化版本约束，可能在任何版本中发生变更。
- 其他子路径（如 `@kortix/sdk/turns` 和 `@kortix/sdk/projects-client`）是根模块名称的已弃用别名。它们将保持可用直到下一个主版本发布。完整列表请参阅 [SDK 参考文档](#sdk-参考sdk-reference)。
- 运行时并不支持所有的会话控制功能。在展示某项控制功能前，请先使用 `runtimeSupports` 进行检查：详见 [基于运行时能力进行拦截](#基于运行时能力runtime-capabilities进行门控)。
- 每个版本的变更均记录在 SDK 的 CHANGELOG 中。可运行的示例代码与 npm 包分开独立发布。

## SDK 认证

每个 SDK 请求都会携带一个 Bearer 凭证。`createKortix` 会从您的 `getToken` 函数中获取该凭证，而 `backendUrl` 则指定了接收该凭证的 API。本节列出了这两个参数的所有来源。请在下方的矩阵中选择适用您场景的行，然后阅读对应的子章节。客户端选项本身的说明请参阅 [创建客户端](#创建客户端)。

在 OpenChatly Cloud 上，`backendUrl` 为 `https://api.kortix.com/v1`。在自托管实例上，则为 `<您的 API 源(origin)>/v1`。

### 选择凭证

凭证仅包含其所代表的主体（principal）的角色权限，不包含其他任何信息。

| 调用方 | 凭证类型 | 运行环境 | `getToken` 返回值 | 参阅 |
|---|---|---|---|---|
| 脚本、CI 任务或您自己的后端 | 个人访问密钥（`kortix_pat_`） | 仅限服务端 | 从环境变量中读取的密钥 | [getToken 与 401 恢复](#gettoken-与-401-恢复) |
| 通过实例的 Supabase 进行用户登录的 Web 应用 | Supabase JWT | 浏览器或服务端 | `(await supabase.auth.getSession()).data.session?.access_token ?? null` | [无头模式登录用户](#无头模式登录用户)（适用于新代码） |
| 带有“使用 OpenChatly 登录”按钮的自有 Web 应用 | OAuth 访问令牌（`kortix_oat_`，有效期 1 小时；刷新令牌 `kortix_ort_`，有效期 30 天） | 服务端持有；浏览器发送占位符 | 服务端调用 `auth.kortix(request)`；浏览器返回 `'kortix-session'` | [使用 OpenChatly 登录](#使用-openchatly-登录) |
| OpenChatly App 内部的代码 | App 查看者令牌 | App 的浏览器端或 App 的服务端 | 浏览器端调用 `kortixAppViewerToken()`；服务端调用 `createAppViewerKortix(request, …)` | [识别 OpenChatly App 中的查看者](#识别-openchatly-app-中的查看者) |
| 同时为多个用户服务的单个服务器进程 | 上述任意凭证，按请求分配 | 仅限服务端 | 基于当前请求的函数 | [从单一后端服务多用户](#从单一后端服务多用户) |

此外还有两种凭证。服务账号密钥（`kortix_sa_`）作为无人值守自动化的服务账号使用。在为其分配角色之前，它没有任何访问权限。您可以在 **Account settings → API keys（账号设置 → API 密钥）** 中创建，或使用 `kortix tokens service-accounts new` 命令创建。OpenChatly 会在会话沙箱内设置 `KORTIX_TOKEN` 和 `KORTIX_API_URL`。它们作为该会话的智能体（agent）运行，且仅限于该项目和该会话。其权限受智能体的 `kortix_permissions` 限制，且不得超过其最高角色上限（详见 [智能体的权限范围](/docs/zh/guide#智能体agents)）。

关于每种凭证的创建、过期时间、项目绑定及密钥规则，请参阅 [安全](/docs/zh/guide#安全性)。如果凭证有效但缺少所需权限，将返回 `403` 错误。请在 [Teams（团队）](/docs/zh/guide#teams) 中授予相应角色。

> **Warning**
>
> `kortix_pat_` 或 `kortix_sa_` 密钥**绝不能**发送到浏览器端。请务必将其保留在服务器上，并为浏览器代码提供代理：
> 针对用户认证，使用 [使用 OpenChatly 登录](#使用-openchatly-登录)；
> 针对服务器持有的密钥，使用 [`forwardKortixRequest`](#从单一后端服务多用户)。

### getToken 与 401 恢复

SDK 会在每次请求前调用 `getToken`。SDK 本身不进行任何缓存，因此令牌的存储与刷新由您的代码负责。

- **`getToken` 返回 `null`**：SDK 不会发送请求。类型化的调用（如 `kortix.projects.list()`）会抛出 `AuthError`，其 `code` 为 `'NO_SESSION'`。而 `kortix.validateToken()` 则会解析为 `{ valid: false, error }`。
- **SDK 发送令牌**：默认作为 `Authorization: Bearer <token>` 发送。如果设置了 `credentialHeader`（例如代理读取自定义请求头时设置为 `'x-app-reader-token'`），SDK 会将原始令牌放入该请求头中发送，且不再发送 `Authorization` 头。发生 `401` 重试时，依然会再次调用 `getToken`。如果调用方自行设置了同名请求头，则调用方设置的头优先级更高。
- **API 返回 `401`**：如果存在 `getToken.invalidate(rejectedToken)` 方法，SDK 会先调用它，然后再次调用 `getToken`，并重试一次原请求。如果重试后再次收到 `401`，则将错误抛给调用方。
- **并行的 `401`**：同一令牌的多个并行 `401` 响应只会触发一次 `invalidate` 调用和一次 `getToken` 调用。这确保了在每次调用时轮换刷新令牌的宿主应用不会发生竞态条件。
- **不重试的情况**：当新令牌与被拒绝的令牌相同时、当请求体为 `ReadableStream` 时，或当调用方自行设置了 `Authorization` 请求头时，SDK 不会进行重试。

如果您的 `getToken` 使用了缓存，**必须**附加 `invalidate` 方法。如果没有该方法，第二次调用将返回同一个失效的令牌，导致 SDK 无法进行重试。

```ts
import { createKortix } from '@kortix/sdk';

declare function fetchTokenFromMyServer(): Promise<string | null>;

let cached: string | null = null;

const getToken = Object.assign(
  async () => (cached ??= await fetchTokenFromMyServer()),
  {
    invalidate: (rejected: string) => {
      if (cached === rejected) cached = null;
    },
  },
);

const kortix = createKortix({ backendUrl: 'https://api.kortix.com/v1', getToken });
```

若需针对认证失败的情况进行分支处理，请调用 `isAuthFailure(error)` 方法。当错误为 `AuthError`，或任何 `status`（状态码）为 `401` 或 `403` 的错误时，该方法均会返回 `true`。该方法仅通过读取状态码进行判断，从不依赖错误消息文本（message text）。

```ts
import { createKortix, isAuthFailure } from '@kortix/sdk';

declare function redirectToSignIn(): void;

const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => localStorage.getItem('kortix-token'),
});

try {
  await kortix.projects.list();
} catch (error) {
  if (isAuthFailure(error)) redirectToSignIn();
  else throw error;
}
```

若要在不使用 `try` 代码块的情况下检查凭证，请调用 `kortix.validateToken()` 方法。该方法会请求 `GET /accounts/me` 接口，且**永远不会抛出异常**。其解析结果为 `{ valid: true, identity }` 或 `{ valid: false, error }`。

`clientVersion`（例如 `'my-app/1.4.0'`）会作为 `X-Kortix-Client-Version` 请求头发送。OpenChatly 仅将其写入请求日志中，不会赋予任何额外权限。审计日志会记录由 `getToken` 返回的凭证信息。

### 无头模式登录用户

`kortix.auth.*` 模块通过 OpenChatly API（`/v1/auth/*`）处理用户的注册与登录。它不需要 Supabase 的 URL 或密钥。该模块在 OpenChatly Cloud 和自托管实例上的工作方式完全相同。适用于 CLI 工具、原生应用或您自定义的登录界面。

请创建一个会话存储（session store）和一个客户端。该存储负责保存令牌，在令牌过期前 60 秒自动进行刷新，并为 `getToken` 提供数据。

```ts
import { createKortix, createKortixSession } from '@kortix/sdk';

const session = createKortixSession({
  storage: {
    get: () => localStorage.getItem('kortix'),
    set: (value) => localStorage.setItem('kortix', value),
    remove: () => localStorage.removeItem('kortix'),
  },
});

const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: session.getToken,
});

const { session: tokens, user } = await kortix.auth.signInWithPassword({
  email: 'ada@example.test',
  password: 'correct-horse-battery',
});
await session.set(tokens, user);

await kortix.projects.list(); // runs as that person
```

请使用 `createKortixSession` 创建存储。**切勿**为了调用 `kortix.auth.session` 而创建第二个 `createKortix` 客户端，因为每次调用 `createKortix` 都会重新指向整个进程唯一的配置。

#### 登录流程

| 流程 | 调用方法 |
|---|---|
| 注册 | `auth.signUp({ email, password, data?, redirect_to? })` 返回 `{ user, session, requires_email_confirmation }`。当 `requires_email_confirmation` 为 `true` 时，`session` 为 `null`，直到用户通过邮件中的链接或调用 `verifyOtp({ type: 'signup' })` 完成确认。 |
| 密码登录 | `auth.signInWithPassword({ email, password })` |
| 魔法链接或验证码 | 先调用 `auth.sendMagicLink({ email, create_user?, redirect_to?, data? })`，然后使用邮件中的验证码调用 `auth.verifyOtp({ email, token, type: 'magiclink' })`。 |
| 社交登录 (PKCE) | `auth.signInWithProvider({ provider, redirect_to, scopes? })` 返回 `{ url, code_verifier }`。请妥善保存 `code_verifier`，并将浏览器重定向至 `url`。随后使用重定向返回的 `code` 调用 `auth.exchangeCode({ code, code_verifier })`。`provider` 为实例已配置的提供商，例如 `google` 或 `github`。 |
| 企业 SSO | `auth.signInWithSso({ domain, redirect_to? })` 返回 `{ url }`。若返回 `404`，则表示该域名未配置身份提供商。详见 [安全](/docs/zh/guide#安全性)。 |
| 重置密码 | 先调用 `auth.resetPassword({ email, redirect_to? })`，然后调用 `auth.verifyOtp({ email, token, type: 'recovery' })`，最后使用该会话的访问令牌调用 `auth.updatePassword({ password }, accessToken)`。密码长度需在 8 到 256 个字符之间。 |

所有返回会话的流程均会返回 `{ session, user }`。请将这两个参数一并传入 `session.set(...)`。`redirect_to` 必须是实例允许的绝对 `http` 或 `https` URL。

#### 已登录用户

以下调用的访问令牌（access token）均作为参数传入，因此它们在 `getToken` 接入之前即可使用。而 `auth.refresh` 则需要传入刷新令牌（refresh token）。`auth.user`、`auth.updateUserMetadata`、`auth.updatePassword` 以及 `auth.mfa.*` 系列调用会拒绝任何其他凭证（如个人访问密钥），并返回 `401 invalid_token` 错误。`auth.signOut` 始终返回 `200`。

| 调用方法 | 作用 |
|---|---|
| `auth.user(accessToken)` | 返回 `{ user }`。 |
| `auth.updateUserMetadata({ data }, accessToken)` | 写入用户资料元数据：显示名称、头像、语言等。拒绝修改密码或邮箱。 |
| `auth.updatePassword({ password }, accessToken)` | 设置新密码。 |
| `auth.mfa.enroll({ factor_type, friendly_name?, phone?, issuer? }, accessToken)` | 注册 `totp` 或 `phone` 类型的多因素认证（MFA）因子。 |
| `auth.mfa.challenge(factorId, { channel? }, accessToken)` | 发起 MFA 验证挑战。 |
| `auth.mfa.verify(factorId, { challenge_id, code }, accessToken)` | 验证 MFA 验证码。在顶层直接返回新的令牌对（`access_token`、`refresh_token`、`expires_at`），而非 `{ session, user }` 格式。请使用 `session.set(result as unknown as AuthSession)` 进行存储。 |
| `auth.mfa.unenroll(factorId, accessToken)` | 移除某个 MFA 因子。 |
| `auth.refresh({ refresh_token })` | 轮换令牌对。会话存储会自动为您调用此方法。 |
| `auth.signOut(accessToken, { scope? })` | 在 OpenChatly 端撤销会话。`scope` 可选值：`global`（默认，所有设备）、`local`（仅当前会话）、`others`（除当前外的所有其他会话）。 |

若要退出登录，请先撤销会话，然后清空存储：

```ts
const token = await session.getToken();
if (token) await kortix.auth.signOut(token);
await session.clear();
```

#### 会话存储

`kortix.auth.session(options?)` 与 `createKortixSession(options?)` 是同一个函数。每次调用都会创建一个新的存储实例。请仅创建一个实例并妥善保留。

| 选项 | 默认值 | 作用 |
|---|---|---|
| `storage` | 无（仅保存在内存中） | 提供 `{ get, set, remove }` 方法，支持同步或异步操作：如 `localStorage`、文件、Cookie 容器或数据库行。 |
| `onChange` | 无 | 在每次登录、刷新令牌和退出登录后执行。 |
| `refreshSkewSeconds` | `60` | 在令牌过期前多少秒进行刷新。 |
| `request` | 客户端的 `backendUrl` | 用于刷新令牌调用的配置：`{ backendUrl?, fetch?, signal? }`。 |

| 方法 | 作用 |
|---|---|
| `getToken()` | 返回有效的访问令牌。如需刷新，会先进行刷新操作。若已退出登录则返回 `null`。 |
| `set(session, user?)` | 存储由 `kortix.auth.*` 调用返回的会话。 |
| `current()`, `user()` | 返回当前存储的会话和用户信息。不会触发刷新。 |
| `refresh()` | 立即轮换令牌。并发的调用者会共享同一次刷新操作。 |
| `subscribe(listener)` | 在每次状态变更时调用 `listener`。返回一个用于取消订阅的函数。 |
| `load()` | 立即读取存储，而不是等到首次使用时才读取。 |
| `clear()` | 在本地清除会话。请先调用 `auth.signOut` 以在服务端撤销该会话。 |

`session.getToken` 没有 `invalidate` 方法。如果未过期的令牌返回 `401` 错误，该错误将直接抛给调用方，请使用 `isAuthFailure` 进行处理。如果 OpenChatly 以 `4xx` 状态码拒绝了刷新请求，将强制用户退出登录：存储会自动清空，且 `getToken()` 返回 `null`。如果是网络故障，存储的会话将被保留以供下次调用使用。

#### 错误与限制

每个 `kortix.auth.*` 调用在失败时都会抛出包含 `code`、`message` 和 `status` 的 `HeadlessAuthError`。

| `code` | `status` | 原因 |
|---|---|---|
| `sso_required` | `403` | 该邮箱域名必须通过 SSO 登录。注册、密码登录、魔法链接和 `verifyOtp` 均会拒绝此类请求。请使用 `signInWithSso`。 |
| `signup_closed` | `403` | 该实例不接受来自此地址的注册。 |
| `over_request_rate_limit` | `429` | 请求过于频繁。请等待 `retry-after` 响应头指示的时间。 |
| `invalid_token` | `401` | 需要用户访问令牌的调用收到了其他类型的凭证。 |
| `not_configured` | `0` | 未配置 `backendUrl`。请先创建客户端。 |

所有不需要访问令牌的 `/v1/auth/*` 路由共享同一个速率限制：每个客户端 IP 每分钟最多 30 次请求，该限制在每个 API 副本上独立计算。其他错误代码则由身份服务原样返回。

### 使用 OpenChatly 登录

“使用 OpenChatly 登录”可使 OpenChatly 成为您运行的 Web 应用的身份提供商。用户使用其 OpenChatly 账号登录，您的服务器即可获知用户身份，且您的应用可以该用户的身份和角色调用 OpenChatly API。底层协议为带有 PKCE 的 OAuth 2.1。浏览器端永远不会持有 OpenChatly 令牌。

适用场景：您自己的站点上已有 OpenChatly 账号的用户。如果您想使用自定义的登录界面，请使用 [无头模式登录](#无头模式登录用户)。如果在 OpenChatly 托管的 App 内部，请使用 [App 查看者](#识别-openchatly-app-中的查看者)。

请先注册应用并妥善保存 `client_id`。相关字段说明请参阅 [OAuth 客户端注册](#oauth-客户端注册)。以下步骤以 Next.js App Router 为例。任何能够传递 Web `Request` 对象的框架均适用。

1. **在您的服务器上创建认证套件（auth kit）**

    ```ts
    // lib/kortix-auth.ts (server only)
    import { createKortixAuth } from '@kortix/sdk/server';

    export const auth = createKortixAuth({
      backendUrl: 'https://api.kortix.com/v1',
      clientId: process.env.KORTIX_OAUTH_CLIENT_ID!,
      clientSecret: process.env.KORTIX_OAUTH_CLIENT_SECRET, // omit for a public client
      redirectUri: 'https://dashboard.example.test/api/kortix/auth/callback',
      cookieSecret: process.env.KORTIX_AUTH_COOKIE_SECRET!, // 32 characters or more
    });
    ```

2. **挂载一个通配（catch-all）路由**

    ```ts
    // app/api/kortix/auth/[...kortix]/route.ts (Next.js App Router)
    import { auth } from '@/lib/kortix-auth';

    const handle = (request: Request) => auth.handler(request);
    export { handle as GET, handle as POST };
    ```

    将一个 Web `Request` 对象传入 `auth.handler`，并返回其 `Response`。

3. **为页面设置访问门槛，并以该用户的身份调用 OpenChatly**

    ```ts
    import { auth } from '@/lib/kortix-auth';

    export async function GET(request: Request) {
      const gate = await auth.requireViewer(request);
      if (gate.response) return gate.response; // 302 to /refresh or /signin

      const kortix = await auth.kortix(request); // acts as the signed-in person
      return Response.json(await kortix.projects.list());
    }
    ```
    `requireViewer` 会将会话 Cookie 中访问令牌已过期的用户重定向至 `/refresh`；没有任何会话 Cookie 的用户则被重定向至 `/signin`。

4. **从浏览器调用 OpenChatly**

    ```tsx
    import { createKortix } from '@kortix/sdk';
    import { SignInWithKortix, useKortixViewer } from '@kortix/sdk/react';

    // The same values auth.clientConfig() returns on the server.
    createKortix({
      backendUrl: window.location.origin + '/api/kortix/auth/proxy',
      getToken: async () => 'kortix-session',
    });

    export function Header() {
      const { status, viewer } = useKortixViewer();
      if (status === 'signed-in') return <span>{viewer.email}</span>;
      return <SignInWithKortix className="button" />;
    }
    ```
    浏览器发送的是占位的 Bearer 值 `kortix-session`（即 `KORTIX_SESSION_SENTINEL`，从 `@kortix/sdk/server` 导出）。`/proxy` 路由会在您的服务器上将这个占位值替换为该用户真正的令牌。所有 SDK 调用都会经由它完成，包括 [`useSession`](#react)。

> **Warning**
>
> **切勿**在浏览器代码中引入 `@kortix/sdk/server`，或任何引入了它的模块（例如 `lib/kortix-auth.ts`）。它会连带引入 `node:async_hooks`。在浏览器端，请像第 4 步那样，把 `createKortix` 的两个配置值直接以字面量写出。在服务端，`auth.clientConfig(origin?)` 会返回同样的这两个值。

#### createKortixAuth 配置选项

| 选项 | 默认值 | 作用 |
|---|---|---|
| `backendUrl` | 必填 | OpenChatly API 的基础 URL，需包含 `/v1`。 |
| `clientId` | 必填 | 已注册的客户端 ID。 |
| `clientSecret` | 无 | 客户端密钥。对于公共客户端（public client），请省略此项。 |
| `redirectUri` | 必填 | 绝对回调 URL，必须与注册的 URL 逐字节完全一致。 |
| `cookieSecret` | 必填 | 32 个字符或更长。用于通过 AES-256-GCM 加密 Cookie。 |
| `scopes` | `['profile', 'email', 'kortix']` | 要请求的权限范围（Scopes）。 |
| `basePath` | 去掉 `/callback` 后的 `redirectUri` 路径 | `handler` 的挂载路径。 |
| `sessionTtlSeconds` | `2592000`（30 天） | 会话在无需重新登录情况下的存活时间。 |
| `cookieSameSite` | `'lax'` | 仅当应用嵌入在其他源（origin）中且需要登录时，才设置为 `'none'`。这要求使用 `https`。在 `http` 环境下，Cookie 保持为 `Lax`。 |
| `fetch` | 全局 `fetch` | 用于测试或边缘计算运行时的自定义 fetch 实现。 |

该认证套件会在 OpenChatly 官方判定过期前 30 秒，就将访问令牌视为已过期，从而确保正在处理中的请求永远不会命中失效的令牌。

**错误处理：**

- 当 `backendUrl` 或 `clientId` 为空、`redirectUri` 不是绝对的 `http` 或 `https` URL，或者 `cookieSecret` 少于 32 个字符时，`createKortixAuth` 会抛出代码为 `invalid_options` 的 `KortixAuthError`。
- 当无人登录时，`auth.kortix` 会抛出代码为 `unauthenticated` 的 `KortixAuthError`。
- Handler（路由处理器）本身不会抛出异常。它会将 `state_mismatch` 和 `token_exchange_failed` 作为 JSON 响应中的 `error` 字段返回。

| 权限范围 (Scope) | 授予您的应用的权限 |
|---|---|
| `profile` | 用户的 ID、邮箱和账号成员身份。 |
| `email` | 邮箱地址。 |
| `kortix` | 代表该用户在整个 OpenChatly API 上执行操作。若无此权限，令牌仅能访问身份认证相关的路由。 |

#### Handler 提供的路由

所有路径均位于 `basePath` 下，在示例中为 `/api/kortix/auth`。

| 路径 | 作用 |
|---|---|
| `/signin?return_to=/path` | 启动带有 PKCE 和 10 分钟有效期的事务 Cookie 的登录流程，然后重定向至 OpenChatly。 |
| `/callback` | 交换授权码（code），设置加密的 `HttpOnly` 会话 Cookie，并重定向至 `return_to`。 |
| `/refresh?return_to=/path` | 轮换令牌对并重定向。`requireViewer` 会将用户发送到此路径。 |
| `/signout?return_to=/path` | 在 OpenChatly 端撤销刷新令牌并清除 Cookie。 |
| `/me` | 以 JSON 格式返回用户信息，或返回 `401`。如果访问令牌已过期，会自动刷新。 |
| `/proxy/*` | 代表该用户将请求转发至 OpenChatly API。 |

`return_to` 参数始终会被限制为同源路径（通过 `safeReturnTo` 处理）。当用户拒绝授权时，回调会重定向至带有 `?kortix_auth_error=<code>` 的 `return_to`。如果事务缺失或已过期，将返回 `400` 错误及 `error: 'state_mismatch'`。如果授权码交换失败，将返回 `error: 'token_exchange_failed'`。

#### 服务端与浏览器端 API

| 来源 | API | 返回值 |
|---|---|---|
| `@kortix/sdk/server` | `auth.viewer(request)` | `{ userId, email, accounts, scopes, token, expiresAt }` 或 `null`。只读操作：永远不会轮换刷新令牌。 |
| `@kortix/sdk/server` | `auth.requireViewer(request)` | `{ viewer }`，或包含重定向至 `/refresh` 或 `/signin` 的 `{ response }`。 |
| `@kortix/sdk/server` | `auth.kortix(request)` | 一个代表该用户执行操作的请求级（request-scoped）客户端。若用户已退出登录，则抛出 `unauthenticated` 的 `KortixAuthError`。 |
| `@kortix/sdk/server` | `auth.signInUrl(returnTo?)`, `auth.signOutUrl(returnTo?)` | 登录/登出链接的目标地址。 |
| `@kortix/sdk/server` | `auth.clientConfig(origin?)` | 浏览器端 `createKortix` 的配置：`backendUrl` 为 `/proxy`，`getToken` 返回 `kortix-session`。 |
| `@kortix/sdk/react` | `useKortixViewer({ basePath? })` | `{ status, viewer, reload }`。`status` 的值为 `loading`、`signed-in`、`signed-out` 或 `error`。 |
| `@kortix/sdk/react` | `<SignInWithKortix basePath? returnTo? />` | 启动登录并返回当前页面的链接组件。 |
| `@kortix/sdk/react` | `kortixSignOutHref(basePath?, returnTo?)` | 登出链接的目标地址。 |

React 辅助组件默认将 `basePath` 设为 `/api/kortix/auth`。如果您将 `handler` 挂载在其他路径，请传入 `basePath`。

#### 授权同意与撤销

首次登录时，会显示一个 OpenChatly 授权同意页面，上面列有您的应用名称和请求的权限范围。OpenChatly 会记住每个用户对该应用的授权。后续的登录将直接返回您的应用。用户可以通过调用 `kortix.accounts.connectedApps.list()` 和 `.revoke(clientId)`，或者按照 [安全](/docs/zh/guide#安全性) 章节所述在 Web 端和 CLI 中撤销应用授权。撤销后，该应用的令牌将立即失效，应用必须重新请求授权。

#### 其他 OAuth 客户端的发现机制

SDK 会从 `backendUrl` 派生出所有端点。通用的 OAuth 客户端可以通过读取 API 源上的 `GET /.well-known/oauth-authorization-server` 获取配置。相同的文档也位于 `/v1/oauth/.well-known/oauth-authorization-server`。动态客户端注册端点为 `POST /v1/oauth/register`。如果自注册的客户端在 7 天内既没有获得授权同意，也没有生成任何令牌，OpenChatly 会将其删除。

#### OAuth 客户端注册

您可以在 **Account → Tokens → OAuth apps（账号 → 令牌 → OAuth 应用）** 中注册，或使用 `kortix.iam.oauthClients.create(accountId, input)` 进行注册。注册需要在该账号上拥有 `token.create` 权限。`kortix.iam.oauthClients` 还提供 `list`、`get`、`update`、`rotateSecret` 和 `remove` 方法。

| 字段 | 值 |
|---|---|
| `name` | 在授权同意屏幕上显示的名称。 |
| `client_type` | 对于保存密钥的服务端，使用 `'confidential'`（默认）。对于浏览器或原生应用，使用 `'public'`：使用 PKCE，无密钥。 |
| `redirect_uris` | 逐字节比对。仅允许 `https`，环回主机（`localhost`、`*.localhost`、`127.0.0.1`、`[::1]`）除外。 |
| `scopes` | `profile`、`email`、`kortix` 中的任意组合。默认：全部三个。 |
| 结果 | 返回 `client_id`。`client_secret` 仅显示一次。 |

### 识别 OpenChatly App 中的查看者

由 OpenChatly 托管的 App 无需自行实现登录。Apps 的网关（gate）会在 App 返回第一个字节之前完成访客的登录，App 随后向网关询问访客的身份。App 的查看者设置（通过 `kortix apps access` 配置）决定了它能获取的信息：

| `kortix apps access <app> --viewer` | App 获取的信息 |
|---|---|
| `off` | 无查看者信息。 |
| `identity` | 查看者的身份：用户 ID、邮箱、姓名、所属组、角色。 |
| `api` | 身份信息，加上一个代表该查看者在 OpenChatly API 上执行操作的令牌（受其角色权限上限约束）。 |

查看者令牌并非该用户的 OpenChatly 会话。它的有效期为 1 小时。它携带 `profile` 和 `email` 权限，对于 `api` 类型的 App 还会携带 `kortix` 权限。它随 App 的生命周期结束而失效。如果 App 部署在自己的独立域名上，则没有网关保护：请在此场景下使用 [使用 OpenChatly 登录](#使用-openchatly-登录)。

#### 在浏览器端

App 自身源（origin）上的 `/_kortix/api/v1/*` 路径会将每次调用以查看者（viewer）的身份转发至 OpenChatly API。因此，浏览器不会发起任何跨域请求。

```tsx
import { createKortix, kortixAppViewerToken } from '@kortix/sdk';
import { useKortixAppViewer } from '@kortix/sdk/react';

createKortix({
  backendUrl: '/_kortix/api/v1',
  getToken: kortixAppViewerToken(),
});

export function Greeting() {
  const { status, viewer } = useKortixAppViewer();
  if (status === 'loading') return null;
  if (status === 'anonymous') return <span>Not signed in</span>;
  return <span>{viewer.name ?? viewer.email}</span>;
}
```


| API | 作用 |
|---|---|
| `kortixAppViewerToken({ path?, fetch? })` | 一个带有 `invalidate` 方法的 `getToken` 实现。返回查看者令牌，若无人登录或 App 的访问模式为 `identity`，则返回 `null`。在令牌过期前 60 秒自动重新获取。 |
| `fetchKortixAppViewer({ path?, fetch? })` | 发起 `GET /_kortix/viewer` 请求。返回 `{ user_id, email, name, picture, group_ids, groups, role, account_id, project_id, app_id, access_mode, scopes, access_token, expires_at }` 或 `null`。并发的调用者会共享同一次请求。 |
| `useKortixAppViewer({ path? })` | 返回 `{ status: 'loading' \| 'anonymous' \| 'viewer', viewer }`。 |
| `clearKortixAppViewerCache()` | 清除缓存的查看者信息和令牌，例如在退出登录后调用。 |

`fetchKortixAppViewer` 永远不会抛出异常。任何非 `2xx` 的网关响应都会导致其返回 `null`。网关会发送以下两种错误：

| 状态码 | `error` | 原因 |
|---|---|---|
| `401` | `no_viewer_identity` | 无人登录，或该查看者无权访问此 App。 |
| `404` | `viewer_disabled` | App 的查看者设置已关闭（`off`）。 |

智能体（Agent）会话通过 `access_token: null` 获取其身份信息。网关永远不会向智能体颁发任何能代表启动该智能体的真实用户的令牌。

#### 在 App 的服务端

网关会将查看者身份注入到每个代理请求的 `x-kortix-app-viewer` 请求头中（对应常量 `APP_VIEWER_HEADER`）。对于 `api` 类型的 App，令牌还会被注入到 `x-kortix-app-viewer-token` 请求头中（对应常量 `APP_VIEWER_TOKEN_HEADER`）。网关会强制删除客户端自行伪造的同名请求头。App 需使用 `KORTIX_APP_VIEWER_SECRET`（对应环境变量 `APP_VIEWER_SECRET_ENV`）来验证该请求头，此密钥由 OpenChatly 在部署时自动设置。若缺少该密钥，下文提到的所有函数均无法获取到查看者信息。

```ts
import { createAppViewerKortix, createKortixAppGuard } from '@kortix/sdk/server';

const guard = createKortixAppGuard();

export async function GET(request: Request) {
  const gate = await guard.requireGroup(request, ['Finance']);
  if (gate.response) return gate.response; // 404 { error: 'not_found' }

  const kortix = await createAppViewerKortix(request, {
    backendUrl: 'https://api.kortix.com/v1',
  });
  return Response.json({
    viewer: gate.viewer.userId,
    projects: await kortix.projects.list(),
  });
}
```


| API (`@kortix/sdk/server`) | 作用 |
|---|---|
| `readAppViewer(request, { secret? })` | 返回经过验证的查看者信息 `{ userId, email, name, picture, groupIds, groups, role, projectId, accountId, appId, accessMode, token, expiresAt }`，若无效则返回 `null`。仅需一次 HMAC 校验，无网络请求。 |
| `createAppViewerKortix(request, { backendUrl, secret? })` | 创建一个代表该查看者执行操作的请求级（request-scoped）客户端。若无可用的验证查看者，抛出代码为 `no_viewer` 的 `AppViewerUnavailableError`；若 App 不是 `api` 类型，抛出代码为 `identity_only` 的异常。 |
| `createKortixAppGuard(options?)` | 提供网关请求头的解析器，并结合 `createKortixAuth` 中的 `auth` 实现 App 自身的登录机制。返回 `{ viewer, requireViewer, requireGroup, identityConfigured }`。 |
| `guard.requireViewer(request)` | 返回 `{ viewer }`；若验证失败则返回 `{ response }`：当配置了 `auth` 时返回重定向至登录页的 `302` 响应，否则返回 `404`。 |
| `guard.requireGroup(request, groups)` | 当查看者属于指定的任一 `groups`（ID 或名称）时，返回 `{ viewer }`；否则返回 `404` 的 `{ response }`。若传入空列表，将拒绝所有人。 |

**`createKortixAppGuard` 配置选项：** `secret`、`backendUrl`（用于登录路径上的群组查询）、`auth`、`accountId`（默认为 `KORTIX_APP_ACCOUNT_ID`）、`groupCacheTtlMs`（默认 `60000`）、`fetch`。如果群组查询失败，将视为无可用群组，此时群组守卫会拒绝访问。

#### 用于 App 间调用的成员令牌（Member Token）

成员令牌是一个有效期为 15 分钟的 ES256 令牌，用于在某个 App 中标识查看者。其 `aud`（受众）字段为该 App 的 ID。一个 App 可以使用它来调用在其 `uses` 字段中声明的其他 App。相关函数来自 `@kortix/sdk`，可在浏览器、Node 18+、Bun、Deno 和 Worker 环境中运行。

```ts
// Browser of the calling App
import { kortixBinding } from '@kortix/sdk';

const api = kortixBinding('api');
const res = await fetch(`${api.url}/orders`, {
  headers: { authorization: `Bearer ${await api.token()}` },
});
```

```ts
// Server of the called App
import { KortixMemberError, requireKortixMember, verifyKortixToken } from '@kortix/sdk';

export async function GET(request: Request) {
  const bearer = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
  try {
    const member = requireKortixMember(await verifyKortixToken(bearer), { groups: ['Finance'] });
    return Response.json({ userId: member.userId });
  } catch (error) {
    if (error instanceof KortixMemberError) {
      return new Response(null, { status: error.code === 'forbidden' ? 403 : 401 });
    }
    throw error;
  }
}
```


| API (`@kortix/sdk`) | 作用 |
|---|---|
| `kortixToken({ audience?, path?, fetch? })` | 用于发起 `GET /_kortix/token` 请求的获取器。`audience` 默认为当前 App，也可以是 `uses` 中声明的 slug 或 ID。若无查看者，则返回 `null`。传入 `{ forceRefreshToken: true }` 可强制重新向网关请求。 |
| `kortixBinding(slug, { origin?, fetch? })` | 返回 `{ url, token }`。对于 HTTP 和 WebSocket，`url` 的格式为 `<origin>/_kortix/apps/<slug>`。在非浏览器环境中，请传入 `origin`。 |
| `verifyKortixToken(token, { jwks?, issuer?, audience?, fetch? })` | 校验签名、`exp`（允许 60 秒的时钟偏差）、签发者（issuer）和受众（audience）。默认值分别取自 `KORTIX_AUTH_JWKS`、`KORTIX_AUTH_ISSUER` 和 `KORTIX_AUTH_AUDIENCE`。若未指定 audience 则拒绝验证；若设置 `audience: false`，则接受该项目下的任何 App。验证通过返回一个 `KortixMember` 对象。任何校验失败均会抛出代码为 `unauthenticated` 的 `KortixMemberError`。 |
| `readKortixMember(claims)` | 从已验证的声明（claims）中构建一个 `KortixMember` 对象，若无效则返回 `null`。此方法**不会**校验签名。 |
| `requireKortixMember(claims, { groups?, roles? })` | 返回该成员对象，否则抛出 `KortixMemberError`。若传入空列表，将拒绝所有人。 |
| `KortixMemberError` | 错误 `code` 为 `unauthenticated`（应映射为 `401`）或 `forbidden`（应映射为 `403`）。 |

`KortixMember` 对象的结构为：`{ userId, email, name, picture, groups, groupIds, role, accountId, projectId }`。

对于未在 `uses` 中声明的 App，令牌路由会返回 `403 app_not_linked`；对于智能体（agent）会话，会返回 `403 agent_viewer`。若绑定的是静态 App，将返回 `409 app_binding_unsupported`。`kortixToken` 在上述所有拒绝情况下均会返回 `null`，并在遇到 `app_not_linked` 时输出一条控制台警告。关于签发者、密钥集和受众的值，请参阅 [Apps 参考文档](#应用参考apps-reference)。

### 从单一后端服务多用户

`createKortix` 会将配置存储在一个全局的进程级作用域中。这对于浏览器标签页、CLI 工具或单租户任务来说是正确的。但在同时处理不同用户请求的服务器上，最后一次 `createKortix` 调用会覆盖所有正在处理中的请求的配置。此时请使用 `@kortix/sdk/server`。它利用 Node.js 的 `AsyncLocalStorage` 隔离每个请求的配置，并支持在 Node 和 Bun 环境中运行。

**每个请求一个客户端。** `createScopedKortix` 接受与 `createKortix` 相同的配置选项，且**永远不会**修改全局的进程级配置。

```ts
import { createScopedKortix } from '@kortix/sdk/server';

declare function tokenFor(request: Request): Promise<string | null>;

export async function GET(request: Request) {
  const kortix = createScopedKortix({
    backendUrl: 'https://api.kortix.com/v1',
    getToken: () => tokenFor(request),
  });
  return Response.json(await kortix.projects.list());
}
```

作用域客户端（Scoped Client）的顶层 `kortix.runtime()` 方法会抛出异常，因为它会解析到另一个请求的沙箱环境。请通过其句柄 `kortix.session(projectId, sessionId)` 来操作会话，并使用 [从代码管理会话（Sessions from code）](#从代码管理会话) 章节中介绍的相关方法。

**每个请求一个作用域。** `runWithKortix(config, fn)` 会为 `fn` 中 `await` 的所有操作（包括通过 `createKortix` 创建的客户端上的调用）设置配置。`getScopedConfig()` 会返回当前作用域的配置，若在作用域外调用则返回 `undefined`。

```ts
import { runWithKortix } from '@kortix/sdk/server';

declare function tokenFor(request: Request): Promise<string | null>;
declare function handleRequest(request: Request): Promise<Response>;

export function handle(request: Request): Promise<Response> {
  return runWithKortix(
    { backendUrl: 'https://api.kortix.com/v1', getToken: () => tokenFor(request) },
    () => handleRequest(request),
  );
}
```

**浏览器代码的代理。** `forwardKortixRequest({ request, upstreamUrl, token })` 会将来自您路由的一个请求，使用您服务器持有的令牌，转发至 OpenChatly API。

```ts
import { forwardKortixRequest } from '@kortix/sdk/server';

declare function tokenFor(request: Request): Promise<string>;

export async function handle(request: Request): Promise<Response> {
  const url = new URL(request.url);
  const rest = url.pathname.replace(/^\/api\/kortix\//, '');
  return forwardKortixRequest({
    request,
    upstreamUrl: 'https://api.kortix.com/v1/' + rest + url.search,
    token: await tokenFor(request),
  });
}
```

该代理会移除浏览器请求中的 `cookie` 和 `host` 请求头，设置 Bearer 令牌，保留流式响应体，并从响应中移除 `set-cookie` 头。当 OpenChatly 服务不可达时，它会返回 `502` 状态码及 `{ "error": "Upstream request failed" }`。

请将浏览器客户端指向该路由，并使用任意非空占位符令牌：`createKortix({ backendUrl: '/api/kortix', getToken: async () => 'proxy' })`。真正的密钥始终安全地保存在服务器端。

若要使用密钥、连接器绑定和 `Idempotency-Key`（幂等键）为您的用户启动会话，请参阅 [从代码管理会话](#从代码管理会话)。

## 从代码管理会话

一个会话（Session）代表一个智能体（Agent）在独立的沙箱和专属的 Git 分支上的一次运行。本节将介绍如何使用无框架依赖的 `@kortix/sdk` 根入口，通过 TypeScript 来驱动会话。操作步骤按生命周期顺序排列：创建、等待就绪、发送、流式传输、获取回复、应答、基于能力进行拦截（gate）、控制、文件操作，以及为您的用户启动会话。SDK 的完整错误目录位于文末。

所有示例均使用 [SDK](#sdk) 章节中创建的客户端。如果是 React 应用，请使用 `useSession` 代替以下调用。详见 [React](#react)。

### 会话句柄（The session handle）

```ts
const s = kortix.session(projectId, sessionId);
// The same handle: kortix.project(projectId).session(sessionId)
```

- 创建句柄（Handle）时不会发送任何网络请求。
- 会话拥有其专属的运行时（Runtime）。句柄仅解析其自身会话的沙箱环境。不同会话的句柄绝不会共享运行时；而同一进程内同一会话的多个句柄则会共享其已解析的运行时。
- `session_id` 既是沙箱的 ID，也是该会话对应的 Git 分支名称。
- `ensureReady()` 返回的是 `sandboxId`。该值是提供商（Provider）分配给沙箱的外部 ID，并非 `session_id`。
- 会话运行的是 pi 运行时。它不提供的控制项请参阅 [基于运行时能力进行拦截（Gate on runtime capabilities）](#基于运行时能力runtime-capabilities进行门控)。

### 创建会话

```ts
import { generateSessionId } from '@kortix/sdk';

const project = kortix.project(projectId);
const sessionId = generateSessionId(); // a v4 UUID, known before the create returns

const created = await project.sessions.create({
  session_id: sessionId,
  agent_name: 'support',
  initial_prompt: 'Triage the open issues labeled bug.',
  labels: ['triage'],
  metadata: { app_ticket: 'T-142' },
});
```

所有字段均为可选。如果未提供任何输入，会话将运行项目默认的 Agent（智能体）和模型，并等待提示词（Prompt）。创建操作会立即开始配置沙箱环境。如果创建时需要用到新的密钥或连接器凭证，请务必在调用创建接口之前完成写入。

| 字段 | 含义 |
| --- | --- |
| `initial_prompt` | 初始提示词。运行时启动后，服务器会自动下发该提示词，您无需为此手动调用 `send()`。 |
| `agent_name` | 要运行的 Agent 名称。默认值：项目 `kortix.yaml` 中配置的 `default_agent`（在新项目中默认为 My OpenChatly）。 |
| `model` | 模型 ID（参见 [模型](/docs/zh/guide#模型models)）。如果账号无权使用该模型，将返回 `400` 错误。 |
| `name` | 会话标题。若未提供，服务器将根据初始提示词自动生成标题。 |
| `labels` | 最多 20 个标签，去除首尾空格后长度为 1 到 64 个字符。重复的标签会被自动过滤。匹配规则为精确且区分大小写。 |
| `metadata` | 自定义键值对的 JSON 对象，每次写入的 JSON 大小上限为 16,384 个字符。服务器保留的键（如 `source`、`trigger_kind` 或 `trigger_slug`）会返回 `400` 错误。请为您的自定义键添加前缀（例如 `app_`）。 |
| `session_id` | 由 `generateSessionId()` 生成的 v4 UUID。若使用相同的 ID 再次创建，将返回 `409` 错误及 `session_already_exists` 提示。 |
| `base_ref` | 会话分支的起始分支或引用（Ref）。默认值：项目的默认分支。 |
| `sandbox_slug` | 要启动的沙箱标识（slug），取自 `kortix.yaml` 中的配置。优先级：Agent 指定的沙箱 > 项目默认沙箱 > `default`。 |
| `runtime_context`, `connector_bindings`, `inherit_unbound`, `secrets` | 面向客户的上下文、连接器账号和密钥。详见 [为您的用户启动会话](#为您的用户启动会话)。 |

`require_connectors` 参数会被接受但将被忽略。

如需在稍后修改会话名称、标签或元数据：

```ts
const s = kortix.session(projectId, created.session_id);
await s.update({ name: 'Bug triage', labels: ['triage', 'done'], metadata: { app_ticket: null } });

const { items, next_cursor } = await project.sessions.listPage({ labels: ['triage', 'done'] });
```

- `labels` 会替换整个标签列表。传入 `[]` 将清空所有标签。
- `metadata` 采用键合并（merge）策略。将某个键的值设为 `null` 即可删除该键。
- 将 `name` 设为 `null` 或 `''`（空字符串），将会话标题恢复为自动生成模式。
- `listPage({ labels })` 仅返回同时包含所有指定标签的会话。如需获取下一页，请将返回的 `next_cursor` 作为 `cursor` 参数传入。`list()` 方法则以纯数组的形式返回单页数据。

`listPage` 的完整配置选项请参阅 [SDK 参考文档](#sdk-参考sdk-reference)。

### 等待就绪

```ts
const { runtimeSessionId, runtimeUrl, sandboxId } = await s.ensureReady({ readyTimeoutMs: 300_000 });
```

`ensureReady()` 负责配置或恢复沙箱，并等待其运行时（Runtime）准备就绪。

- 当响应状态为 `provisioning`（配置中）或 `starting`（启动中）且 `retriable: true` 时，它会以长轮询（Long Poll）的方式调用 `POST .../start` 接口。每次轮询最长等待 30 秒，两次轮询之间间隔 1 秒。
- 默认超时时间为 `180_000` 毫秒。可通过传入 `readyTimeoutMs` 参数来修改该值。
- 达到超时时间，或收到 `failed`（失败）或 `stopped`（已停止）的响应时，会立即抛出 `code: 'RUNTIME_UNAVAILABLE'` 的 `ApiError`。
- 除 `408` 或 `429` 外的其他 `4xx` 响应（例如 `402`）会立即被拒绝，并抛出 `SessionStartError`（包含 `status`、`code` 和 `terminal: true`）。
- 针对同一会话的并发调用会共享同一个启动请求。如果句柄（Handle）已处于就绪状态，调用将立即返回。
- `runtimeSessionId` 是运行时中根会话（Root Conversation）的 ID。事件（Events）中会通过 `sessionID` 字段携带该值。

您可以使用 `s.get()` 读取会话的数据行（Row）。读取数据行不会触发沙箱唤醒。将该数据行传入 `ensureReady()` 可进行优化：如果该行的状态为 `running`，且已包含沙箱名称和 `runtime_session_id`，则会直接复用该状态，无需再次发起启动请求。

```ts
const row = await s.get();
const ready = await s.ensureReady({ session: row });
```

`s.start()` 和 `s.startOrThrow()` 会发送一次启动请求，并返回原始的 `SessionStartResult`（包含 `stage`、`retriable`、`sandbox`、`failure` 字段）。在遇到临时性失败时，`start()` 会解析并返回 `null`；遇到其他 `4xx` 错误时，则会抛出 `SessionStartError`。而 `startOrThrow()` 遇到错误时会直接抛出 `ApiError`（例如将 `402` 抛出为 `BillingError`）。您可以使用这两个方法来实现自定义的进度展示。在其他所有场景中，请统一使用 `ensureReady()`。

| 行为 | 方法 |
| --- | --- |
| 内部自动调用 `ensureReady()` | `send`、`abort`、`rewind`、`restoreRewind`、`stream`、`messages`、`pendingRequests`、`answerPermission`、`answerQuestion`、`compact`，以及所有 `files.*` 方法 |
| 在句柄获取到运行时之前，抛出 `SessionNotReadyError` | `previewUrl`、`proxyUrl`、`sandboxPortUrl` |
| 仅读取 OpenChatly API，绝不访问沙箱 | `get`、`update`、`cost`、`scope`、`log`、`turn`、`messageAuthors`、`modelUsage`、`prompts.*` |

`s.health()` 永远不会抛出 `SessionNotReadyError`。在句柄获取到运行时之前，它会返回 `status: 0`、`ok: false` 和 `health: null`。

启动失败代表进入冷却期，而非最终定论。冷却期过后的再次启动会重新尝试。冷却时间会依次递增：2 分钟、5 分钟、10 分钟。在连续 5 次启动失败后，`ensureReady()` 会立即抛出 `RUNTIME_UNAVAILABLE` 错误。该最终定论会在最后一次失败 30 分钟后失效。调用 `s.restart()` 可立即清除该状态。

### 发送提示词（Send prompts）

```ts
const { prompt_id, state, message_id } = await s.send('Refactor the auth module.');
```

- `send()` 会将提示词（Prompt）放入会话的持久化提示词收件箱中。Web 应用和 CLI 写入的是同一个收件箱。
- `send()` 在提示词成功持久化后即完成解析（Resolve），而**不会**等待当前对话轮次（Turn）结束。请通过流式传输（Stream）或调用 `s.messages()` 来获取回复。
- 如果收件箱中的记录已经处于失败状态，`send()` 会抛出 `code: 'PROMPT_FAILED'` 的 `ApiError`。
- SDK 中没有提供“发送提示词并等待回复”的封装方法。关于如何获取回复，请参阅 [获取回复（Get the reply）](#获取回复get-the-reply) 章节中的示例模式。

您可以在每次调用时，或在句柄（Handle）级别指定模型和 Agent：

```ts
await s.send('Write the tests.', { agent: 'tester' }); // this call only
s.setModel({ providerID: 'kortix', modelID: 'glm-5.3-flash' }); // later send() calls on this handle
s.setAgent('reviewer');
```

**优先级规则：** `send()` 方法中传入的选项 > 当前句柄上通过 `setModel()` / `setAgent()` 设置的值 > 会话保存的默认值。模型 ID 可通过 `kortix.projects.modelPicker(projectId)` 获取；Agent 名称则来自 `kortix.projects.detail(projectId)` 返回结果中的 `config.agents`。如需修改会话保存的默认模型，请参阅 [控制会话（Control the session）](#控制会话control-the-session)。

#### 引导（Steer）、排队（Queue）或中断（Interrupt）

`send()` 默认采用排队机制：提示词会等待当前正在运行的对话轮次（Turn）结束后再执行。若要自定义提示词如何介入正在运行的轮次，请使用 `s.prompts.create()` 方法：

```ts
import { mintWireMessageId } from '@kortix/sdk';

const messageId = mintWireMessageId();
await s.prompts.create({
  clientMessageId: messageId,
  messageId,
  remintOnDelivery: true,
  delivery: 'steer',
  parts: [{ type: 'text', text: 'Use the staging database.' }],
});
```


| `delivery`（投递方式） | 当对话轮次正在运行时 |
| --- | --- |
| `steer`（引导） | 正在运行的轮次会在下一步读取该提示词。当前轮次不会停止。 |
| `queue`（排队） | 提示词会等待当前轮次结束，然后作为一个全新的轮次运行。 |
| `interrupt`（中断） | 当前轮次会在正在运行的工具执行完毕后结束。然后该提示词作为一个全新的轮次运行。 |

如果没有正在运行的轮次，这三种方式都会直接启动一个新轮次。使用 `steer` 需要具备 `session.steer` 运行时能力，并且必须由启动当前轮次的成员发出。否则，服务器会将其作为 `queue` 进行投递，并在收件箱记录中设置 `steer_fallback`（引导降级）原因：

- `unsupported`（不支持）：运行时未列出 `session.steer` 能力。
- `not_prompter`（非发起者）：当前运行的轮次是由其他成员启动的。
- `turn_ended`（轮次已结束）：在提示词送达之前，当前轮次已经结束。

#### 提示词收件箱（The inbox）

收件箱仅列出会话尚未投递的提示词。

| 方法 | 功能说明 |
| --- | --- |
| `s.prompts.list()` | 返回 `{ prompts }`：按时间从旧到新排列的等待中的提示词，每条记录包含 `state`（状态）、`reason`（原因）和 `steer_fallback`（降级原因）。 |
| `s.prompts.edit(promptId, text)` | 替换等待中提示词的文本内容。如果提示词正在被发送至运行时，将返回 `409` 冲突错误。 |
| `s.prompts.interrupt(promptId)` | 将等待中的提示词转换为 `interrupt`（中断）模式。 |
| `s.prompts.retry(promptId)` | 重试状态为 `failed`（失败）的提示词。 |
| `s.prompts.remove(promptId)` | 移除并返回该提示词。如果 Agent 已经在读取该提示词，将返回 `409` 冲突错误。 |
| `s.prompts.hold(held)` | 暂停（传入 `true`）或释放（传入 `false`）整个提示词队列。 |

#### 附加文件（Attach files）

先将文件上传至项目，然后在 `file` 字段中传入该文件的 ID：

```ts
import { mintWireMessageId } from '@kortix/sdk';

const report = new File([reportBytes], 'report.pdf', { type: 'application/pdf' });
const upload = await kortix.project(projectId).attachments.upload(report);

const messageId = mintWireMessageId();
await s.prompts.create({
  clientMessageId: messageId,
  messageId,
  remintOnDelivery: true,
  parts: [
    { type: 'text', text: 'Summarize this report.' },
    { type: 'file', attachment_id: upload.attachment_id, filename: upload.filename, mime: upload.mime },
  ],
});
```

- **限制条件：** 单个文件大小限制为 1 字节至 50 MiB；单条消息的文件总大小上限为 100 MiB；单条消息最多允许附加 20 个文件。
- **上传机制：** 文件上传无需沙箱处于运行状态。在提示词（Prompt）执行之前，服务器会将每个文件写入沙箱的 `/workspace/uploads/.kortix-inbox/` 目录。
- **过期机制：** 如果上传的文件未被任何提示词使用，将在 24 小时后过期（通过 `expires_at` 字段标记）。
- **前端集成：** 浏览器端的编辑器（Composer）可使用 `@kortix/sdk/react` 提供的 `usePromptAttachments` Hook 来处理附件。

### 流式事件（Stream events）

```ts
const stream = await s.stream({
  onEvent: (event) => {
    /* one runtime event */
  },
  onGapRehydrate: (gapMs) => {
    /* re-read the state you cache */
  },
  signal: abortController.signal, // optional
});
stream.close();
```

`stream()` 方法会先确保会话处于就绪状态，然后通过 OpenChatly API 打开运行时的（Runtime）事件流。其底层传输机制是基于流式 `fetch` 的服务器发送事件（Server-Sent Events, SSE），**不支持 WebSocket**。

> **Info**
>
> 请务必在调用 `send()` 之前打开事件流。如果在发送之后才打开流，可能会错过当前轮次的最初几个事件。

每个原始事件都包含 `type`（类型）和 `properties`（属性）。`narrowChatEvent(event)` 函数会将聊天所需的事件映射为类型化的 `KortixChatEvent` 联合类型，对于其他无关事件则返回 `null`：

| `KortixChatEvent.type` | 触发时机 | 载荷（Payload） |
| --- | --- | --- |
| `message.updated` / `message.removed` | 消息发生变更或被删除。 | `message` / `messageID` |
| `message.part.updated` / `message.part.removed` | 消息片段（文本、工具调用、文件）发生变更或被移除。该事件会携带完整的片段内容。 | `part` / `messageID`, `partID` |
| `session.status` | 会话的忙碌状态发生改变。 | `status` |
| `session.idle` | 一个对话轮次结束。 | `sessionID` |
| `session.error` | 一个对话轮次执行失败。 | `error` |
| `permission.asked` / `permission.replied` | Agent 请求权限，以及对应的回复。 | `requestID`, `permission`, `patterns` / `reply` |
| `question.asked` / `question.answered` | Agent 提出问题，以及对应的回复。`question.answered` 合并了底层的 `question.replied` 和 `question.rejected`。 | `requestID`, `questions` / `outcome`, `answers` |
| `todo.updated` | Agent 的待办事项列表发生变更。仅当运行时支持 `session.todo` 能力时才会发送此事件。 | `todos` |
| `connection` | 流连接建立（`server.connected`）。 | `status` |

除 `connection` 和 `heartbeat-gap` 外，每个事件都会携带 `sessionID`。子 Agent（Subagent）的会话会使用自己的 `sessionID` 发送其专属事件。`narrowChatEvent` 会过滤掉 `message.part.delta` 事件。若要在文本输入时实时渲染，需从原始事件中读取 `message.part.delta`，并拼接 `properties.delta`。`heartbeatGapEvent(gapMs)` 函数会基于 `onGapRehydrate` 构建联合类型中合成的 `heartbeat-gap` 成员。

SDK 会负责维持连接的生命周期：

- 事件会以每 16 毫秒一次的批次到达。在同一批次中，针对同一片段字段的连续 `message.part.delta` 事件会被合并为一个事件：`properties.delta` 包含拼接后的文本，`id` 为最后一个事件的 ID，`coalesced` 列表则记录了被替换的事件。
- 当健康的流断开后，SDK 会在 250 毫秒后尝试重连。否则，重连延迟会从 1 秒逐步退避至 30 秒。每次延迟最多会引入 50% 的随机抖动（Jitter）。重连时会通过 `Last-Event-ID` 恢复状态。
- 沙箱每 20 秒会发送一次心跳保活。如果 60 秒内未收到任何数据帧，SDK 会主动断开连接并重新连接。
- 当发生重连，且断开的流之前曾投递过事件，或者断线时间超过 5 秒时，会触发 `onGapRehydrate(gapMs)` 回调。
- 如果连续发生 8 次严重故障（如沙箱被停止或删除），流将永久停止。请等待会话重新运行后再打开新的流。

#### 原始流与 React Native

`openEventStream({ url: runtimeUrl, onEvent })` 是 `stream()` 底层的原始方法。针对同一个运行时 URL 的两次调用会共享同一个连接。其配置选项（如 `onParked`、`onConnectionChange`、超时时间及故障限制）请参阅 [SDK 参考文档 > 事件流](#事件流event-stream)。

对于 `fetch` 无法流式传输响应体的宿主环境（例如 React Native），可以在 `createKortix` 中传入自定义的传输层。SDK 仍会保留重连、状态恢复、退避策略和心跳检查等机制：

```ts
import { createKortix, type RuntimeEventTransport } from '@kortix/sdk';

const eventStreamTransport: RuntimeEventTransport = async function* ({ url, headers, signal }) {
  // 针对单次连接的每个服务器发送消息，Yield 返回 { data?, id?, retry? }。
  // 当服务器结束连接时，Return 退出。
  // 当连接失败时，抛出异常（对于非 2xx 的响应，需携带 `status`）。
};

const kortix = createKortix({ backendUrl, getToken, eventStreamTransport });
```

在不支持 `visibilitychange` 和 `online` 事件的宿主环境中，需调用 `notifyHostSignal('visible' | 'online' | 'retry')`。`useSession` 持有的事件流会在收到该信号时自动重连。而通过 `stream()` 获取的句柄（Handle）则不会监听此信号。

### 获取回复（Get the reply）

当您的 `runtimeSessionId` 对应的对话轮次结束时，会触发 `session.idle`（空闲）或 `session.error`（错误）事件。请等待其中任一事件触发后，再读取最后一条消息：

```ts
import { classifyTurn, narrowChatEvent } from '@kortix/sdk';

const s = kortix.session(projectId, sessionId);
const { runtimeSessionId } = await s.ensureReady();

let settle!: (error?: unknown) => void;
const turnEnded = new Promise<void>((resolve, reject) => {
  settle = (error) => (error === undefined ? resolve() : reject(error));
});

const stream = await s.stream({
  onEvent: (raw) => {
    const event = narrowChatEvent(raw);
    if (event?.type === 'session.idle' && event.sessionID === runtimeSessionId) settle();
    if (event?.type === 'session.error' && event.sessionID === runtimeSessionId) {
      settle(event.error ?? new Error('The turn failed.'));
    }
  },
});

try {
  await s.send('List the open TODO comments in this repository.');
  await turnEnded;
} finally {
  stream.close();
}

const { messages } = await s.messages({ limit: 1 });
const last = messages.at(-1);
const turn = last ? classifyTurn(last) : null;
const text = (turn?.parts ?? [])
  .flatMap((part) => (part.kind === 'text' && !part.synthetic ? [part.text] : []))
  .join('\n');
```

- `classifyTurn(message)` 返回 `{ parts, error, isEmpty }`。每个片段（part）都有一个 `kind`（类型），例如 `text`（文本）、`reasoning`（推理）、`tool`（工具）、`file`（文件）等。`error` 为该轮次标准化后的错误信息。
- `s.turn()` 可在不使用流式传输的情况下获取状态，返回：`turns`（空闲时为空）、`last_ended`（最后结束时间）、`recent_failures`（近期失败次数）和 `can_stop`（是否可停止）。当无法保持流式连接打开时，可使用轮询（Poll）方式调用此方法。
- Agent 的回复中可能包含生成式 UI 块（`openui` 围栏代码）。若需纯文本，请使用 `@kortix/sdk/genui` 中的 `genuiToMarkdown(text)` 进行转换。详见 [生成式 UI（Generative UI）](#生成式-uigenerative-ui)。

**读取会话记录：**

| 方法 | 返回值 | 是否唤醒沙箱 |
| --- | --- | --- |
| `s.messages({ limit?, before?, conversationId? })` | 返回按时间从旧到新排列的分页消息，格式为 `{ info, parts }`（`kortix.transcript.v1`）及 `hasMore` 标志。传入 `conversationId` 可读取子 Agent 的会话。 | 是 |
| `s.log({ thread?, before_seq?, limit? })` | 返回存储的会话日志（`kortix.session/2`）的单页数据：包含会话记录、每个线程的头部信息，以及指定线程中最新的 `limit` 条消息（默认 40 条，最多 500 条）。将第一条消息的 `seq` 作为 `before_seq` 传入可获取更早的消息。若会话尚无存储日志，则返回 `null`。 | 否 |
| `s.messageAuthors()` | 返回发送每条消息的成员或会话，以及停止每个已终止轮次的成员。 | 否 |
| `s.modelUsage()` | 返回回复每个轮次所使用的模型，若使用了降级模型，还会包含 `fallback_from` 字段。 | 否 |

在运行时（Runtime）停止时，请使用 `s.log()`。它读取的是 API 数据库，而非沙箱内部。

### 响应 Agent（Answer the agent）

Agent 可能会暂停并等待权限或答复。请先读取其等待的内容，然后进行响应：

```ts
const { statuses, permissions, questions } = await s.pendingRequests();

const permission = permissions[0];
if (permission) await s.answerPermission(permission.id, 'once'); // 'once' | 'always' | 'reject'

const question = questions[0];
if (question) await s.answerQuestion(question.id, [['Yes']]); // one answer list per question
```

- 传入 `'always'` 将在当前会话的剩余时间内授予该权限。
- 调用 `answerQuestion(id, null)` 可忽略（Dismiss）该问题。
- 事件流会通过 `permission.asked` 和 `question.asked` 事件来通知这两类请求。它们的 `requestID` 即为响应时所需的 `id`。
- `s.pending()` 返回相同的三个字段，但该方法已被弃用，请改用 `pendingRequests()`。

### 基于运行时能力（Runtime Capabilities）进行门控

运行时（Runtime）并不支持所有功能。`s.health()` 会在 `health.capabilities` 中列出当前支持的能力。当某项能力缺失时，请隐藏对应的控件：

```ts
import { runtimeSupports } from '@kortix/sdk';

await s.ensureReady();
const { health } = await s.health();
const canCompact = runtimeSupports(health?.capabilities, 'session.compact');
```


| 能力（Capability） | 功能特性 |
| --- | --- |
| `session.subagents` | 子 Agent（Subagent）子会话 |
| `session.compact` | 按需启动全新上下文（或进行摘要） |
| `session.context_record` | 完整上下文及 `compact()` 重置均写入会话的可搜索记录中；不进行任何摘要 |
| `session.commands` | 项目斜杠命令（Slash commands） |
| `session.steer` | 正在运行的轮次在下一步读取的提示词 |
| `session.log.v2` | 事件流以 `log.*` 帧的形式提供会话日志 |
| `session.messaging` | 会话间消息传递：`send_message` 和 `list_agents` 工具 |
| `session.team_tasks` | 团队共享任务列表：`task_*` 工具 |
| `session.rewind` | 回滚至某条消息并恢复该状态 |
| `session.fork` | 在指定消息处分叉（Fork）会话 |
| `session.mcp` | 运行时自行连接的 MCP 服务器 |
| `session.todo` | 运行时的待办事项列表 |
| `session.shell` | 作为对话轮次运行的 Shell 命令 |
| `session.attach` | 附加运行时自带的终端客户端 |
| `session.config` | 客户端读取并修补的运行时配置文档 |

- 每个会话都运行 Pi。Pi 始终支持 `session.subagents`、`session.compact`、`session.commands`、`session.steer` 和 `session.log.v2`。除非 Agent 的上下文设置为 `summary`，否则 Pi 还会添加 `session.context_record`；当沙箱连接到 OpenChatly API 时，会添加 `session.messaging`；对于主导或加入团队的会话，会添加 `session.team_tasks`。
- Pi **不**支持 `session.rewind`、`session.fork`、`session.mcp`、`session.todo`、`session.shell`、`session.attach` 或 `session.config`。
- Agent 团队（Agent teams）属于实验性功能，默认关闭。请在 **Project admin（项目管理）** → **Feature flags（功能标志）** 中开启。
- 针对未列出功能的请求路由将返回 `501 feature_not_supported` 错误。
- 在收到健康检查（Health）响应之前，或能力列表中没有 `session.*` 条目时，`runtimeSupports` 会返回 `true`。

会话的计算机可能配备桌面环境，并通过 `6901` 端口进行流式传输。当镜像安装了桌面环境时，守护进程会在相同的 `capabilities` 列表中列出 `machine.desktop`。My OpenChatly 的计算机以及非 Ubuntu 24.04 基础模板均不包含桌面环境。只有当该条目被明确列出时，`hasSessionDesktop(health?.capabilities)` 才会返回 `true`；在收到健康检查响应之前，它始终返回 `false`。

### 控制会话（Control the session）

| 方法 | 功能说明 |
| --- | --- |
| `s.abort()` | 终止当前运行的轮次。会话保留。 |
| `s.setModel(model)` / `s.setAgent(agent)` | 仅为当前句柄后续的 `send()` 调用设置模型和 Agent。 |
| `s.changeModel(modelId)` | 为会话保存新模型。详见下文。 |
| `s.compact(model?)` | 启动全新上下文：若具备 `session.context_record`，Agent 将继续运行并搜索会话的完整记录；否则将使用指定的 `model` 对对话进行摘要。需要 `session.compact` 能力。 |
| `s.restart()` | 原地停止并启动沙箱。清除启动失败的最终定论。 |
| `s.stop()` | 停止沙箱。磁盘、分支和对话记录保留。 |
| `s.recover()` | 在新沙箱上继续已丢失的会话（即提供商移除了其沙箱）。下次启动时将从分支引导并加载已保存的对话。 |
| `s.delete()` | 删除会话及其沙箱。解析返回 `{ ok, restore_until }`。会话在 30 天内可恢复。超过该期限后，其消息、文件和分支将被永久删除。 |
| `s.restore()` | 在 `restore_until` 期限前恢复已删除的会话。下次启动时将从分支引导启动一个新沙箱。 |
| `s.rewind(messageId)` / `s.restoreRewind()` | 将对话回滚至某条用户消息，并在下一次提示词之前撤销该操作。需要 `session.rewind` 能力（Pi 不支持此能力）。 |
| `s.configState()` / `s.reloadConfig({ force? })` | 检查会话是否正在运行基础分支的当前配置，并加载该配置。重新加载会重启运行时。在对话轮次运行期间调用将返回 `409 SESSION_BUSY`；传入 `force: true` 可强制终止当前轮次。 |

```ts
const { applied_live, push_failed } = await s.changeModel('glm-5.3-flash');
```

- `changeModel()` 会在不重启运行时的情况下重新配置 Pi。当前正在运行的轮次将使用其原有的模型直至完成。
- `applied_live: true`：表示运行中的会话已立即应用了新模型。`false`：表示新模型将在下一次启动时生效。
- `push_failed: true`：表示新模型已成功保存，但当前运行中的运行时仍在使用旧模型。
- 在 `stopped`（已停止）、`failed`（失败）或 `completed`（已完成）的会话上调用此方法会返回 `409 SESSION_NOT_RUNNING` 错误。仅会话所有者或项目管理员有权调用，其他用户将收到 `403` 错误。
- OpenChatly 的 Web 和移动端应用会基于会话保存的模型来打开会话。在创建时或通过 `changeModel()` 设置的模型，将成为下一条消息使用的模型（除非用户在会话中手动选择了其他模型）。`@kortix/sdk` 中的 `sessionModelCandidates()` 提供相同的模型排序列表。

若 `restore()`（恢复）被拒绝，将抛出 `ApiError`，其 `code` 可能为 `session_not_deleted`（会话未删除）、`session_sandbox_removal_pending`（沙箱正在移除中，请一分钟后重试）或 `session_purged`（会话已彻底清除）。若 `recover()`（重建/恢复丢失的会话）被拒绝，将抛出 `session_not_lost`、`session_transcript_missing`、`session_sandbox_removal_pending` 或 `session_log_restore_off` 错误。

关于分享、公开链接和循环（Loops）的内容，请参阅 [SDK 参考文档](#sdk-参考sdk-reference)。

### 文件与预览（Files and previews）

`s.files` 用于读写实时运行的沙箱。每次调用前都会先确保会话处于就绪状态。

| 方法 | 功能说明 |
| --- | --- |
| `list(dir)`, `read(path)`, `readBlob(path)` | 列出目录内容。以文本或 `Blob` 格式读取文件。 |
| `status()` | 获取已变更文件的 Git 状态。 |
| `findFiles(query, { type?, limit? })`, `findText(pattern)` | 按文件名或文件内容进行搜索。 |
| `write(path, blob)` | 写入文件。直接在原位置覆盖文件。 |
| `upload(file, targetPath?, filename?)` | 写入新文件。绝不覆盖：若文件名已被占用，将自动分配一个唯一名称。 |
| `create(path)`, `copy(from, to)`, `remove(path)`, `mkdir(dir)`, `rename(from, to)` | 编辑文件树（创建、复制、删除、创建目录、重命名）。 |

```ts
await s.files.write('/workspace/NOTES.md', new Blob(['# Notes\n']));
const readme = await s.files.read('/workspace/README.md');
```

获取预览 URL 需要确保句柄处于就绪状态：

```ts
await s.ensureReady();
const url = s.previewUrl(3000, '/docs'); // 可直接在浏览器标签页中打开的 URL
const fixed = s.proxyUrl('http://localhost:3000/'); // 将 Agent 打印的 localhost URL 重写为可访问的代理 URL
const direct = s.sandboxPortUrl(3000); // 经过身份验证的 API 代理 URL，适用于携带 Bearer Token 的客户端
const ports = await s.previews(); // 获取运行时（Runtime）当前暴露的所有端口
```

关于端口和预览功能的详细信息，请参阅 [Computers（计算机）](/docs/zh/guide#计算机computers) 章节。

### 为您的用户启动会话

您的服务器只需持有一个 OpenChatly 凭证，即可为其客户启动会话。您的客户无需直接登录 OpenChatly。

1. 使用个人访问密钥（`kortix_pat_…`，代表您本人操作）或服务账号密钥（`kortix_sa_…`，代表其自身操作，且需先分配项目角色）。详见 [Security（安全）](/docs/zh/guide#安全性)。
2. 使用 `@kortix/sdk/server` 中的 `createScopedKortix` 创建客户端。该方法永远不会写入进程级别的全局配置，从而确保一个请求绝不会读取到另一个请求的配置。详见 [SDK authentication（SDK 身份验证）](#sdk-认证)。

```ts
import { createScopedKortix } from '@kortix/sdk/server';

const kortix = createScopedKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => process.env.KORTIX_API_KEY!,
});

const created = await kortix.project(projectId).sessions.create({
  agent_name: 'support',
  initial_prompt: 'Answer ticket T-123.',
  labels: ['support', 'customer:c-42'],
  metadata: { app_customer_id: 'c-42', app_ticket_id: 'T-123' },
  runtime_context: { customer_id: 'c-42', plan_tier: 'pro' },
  connector_bindings: { gmail: { connection_id: supportInboxConnectionId } },
  secrets: ['HELPDESK_API_KEY'],
});
```

- 这两种凭证类型都会将请求的来源（Origin）标记为 `backend`。请求体（Body）中无法设置 Origin。从会话沙箱内部生成的 Token，其 Origin 永远不会是 `backend`。
- 在使用作用域客户端（Scoped client）时，直接调用 `kortix.runtime()` 会抛出异常。请通过 `kortix.session(projectId, sessionId)` 来访问特定会话。
- 使用 `listPage({ labels: ['customer:c-42'] })` 可以查找特定客户的会话。

#### 安全地重试创建操作

SDK 的 `sessions.create()` 方法不会自动发送 `Idempotency-Key`（幂等键）。若需重试 SDK 的创建操作，请先使用 `generateSessionId()` 生成一个 `session_id`，并在重试时发送相同的 ID。如果重试时收到 `409 session_already_exists` 错误，说明首次创建已经成功。

若通过 HTTP 直接调用，请在请求头中携带 `Idempotency-Key`：

```bash
curl -X POST "https://api.kortix.com/v1/projects/<project_id>/sessions" \
  -H "Authorization: Bearer $KORTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-app:ticket-T-123:reply" \
  -d '{ "agent_name": "support", "initial_prompt": "Answer ticket T-123.", "secrets": ["HELPDESK_API_KEY"] }'
```

- API 会返回 `201` 状态码及对应的会话信息。使用相同键的重放请求将返回同一个会话。
- 键的长度为 1 到 255 个字符，允许使用的字符包括 `A-Z a-z 0-9 . _ : + / = -`。
- 键在整个 OpenChatly 平台中是全局唯一的。如果其他项目或账号已使用过该键，将返回 `409 IDEMPOTENCY_KEY_CONFLICT` 错误。请在键中包含您自己的唯一标识。
- 如果在首次创建操作仍在运行时进行重放，API 将返回 `202` 状态码，并附带 `status` 和 `session_id`。
- 如果重放时传入的 `connector_bindings`（连接器绑定）、`secrets`（密钥）或 `runtime_context`（运行时上下文）与首次请求不一致，将分别返回 `409 IDEMPOTENCY_BINDING_CONFLICT`、`IDEMPOTENCY_SECRETS_CONFLICT` 或 `IDEMPOTENCY_CONTEXT_CONFLICT` 错误。
- 如果该键对应的会话已被删除，将返回 `409 IDEMPOTENCY_KEY_SESSION_DELETED` 错误。此时请使用一个新的键。

#### 传递上下文、账号和密钥

`runtime_context` 用于向 Agent 传递非敏感的值，例如您的客户 ID。

- 值可以是字符串（最多 4,096 个字符）、数字、布尔值或 `null`。
- 键的长度为 1 到 64 个字符：必须以一个小写字母开头，后续可包含小写字母、数字、`.`、`_` 或 `-`。如果键中包含 `token`、`secret`、`password`、`credential`、`api_key`、`private_key`、`authorization` 或 `cookie` 等敏感词段，将被拒绝。
- 最多允许 64 个键，且 JSON 总大小不超过 16 KiB。
- 以 `kortix.` 开头的键为平台保留。仅当会话创建自己的子会话（使用自身的会话 Token）时才能设置这些键。任何其他创建操作如果指定了这些键，将返回 `400 INVALID_SESSION_RUNTIME_CONTEXT` 错误。
- 沙箱会在环境变量 `KORTIX_SESSION_CONTEXT` 中以 JSON 格式接收该对象。您需要在创建时进行设置。后续的作用域变更（Rescope）不会改变该值。

`connector_bindings` 用于将每个别名（Alias）固定到特定的连接器账号，格式为 `{ alias: { connection_id } }`，最多支持 64 个条目。绑定机制遵循“全有或全无”原则：

- 当您设置绑定时，未被绑定的别名将不会获得任何账号。设置 `inherit_unbound: true` 可以让未绑定的别名使用项目的默认账号。
- 共享（`project` 级别）账号对这两种凭证类型均有效。
- 私有（`member` 级别）账号仅对其所有者有效，且仅在私有会话中可用。新创建的会话默认为私有会话。服务账号（Service account）永远不会使用私有账号。
- 凭证本身绝不会进入沙箱。OpenChatly 会在每次调用连接器时动态解析。详见 [Connectors（连接器）](/docs/zh/guide#连接器connectors)。

`secrets` 用于缩小沙箱可接收的项目密钥范围，即从 Agent 的授权范围内缩减为您列出的标识符。它**永远不会扩大**原有的授权范围。传入 `[]` 将不传递任何项目密钥。仅允许来源为 `backend` 的调用方设置此项。详见 [Security（安全）](/docs/zh/guide#安全性)。

#### 更改运行中会话的作用域（Change the scope of a running session）

```ts
const scope = await s.scope();
scope.secrets_allowlist; // null: the agent's grant applies
scope.connector_bindings_configured; // false: the session uses the project defaults

const next = await s.rescope({
  secrets: ['HELPDESK_API_KEY'],
  connector_bindings: { gmail: { connection_id: otherConnectionId } },
});
next.dropped_secrets; // the secrets the change removed
next.retroactive; // false when the change removed a secret
```

API 的响应将返回新的 `SessionScope` 对象，其中包含本次变更的 `added_secrets`（新增的密钥）、`dropped_secrets`（移除的密钥）和 `dropped_bindings`（移除的绑定）。

您发送的每个字段都会**完全替换**其之前的值。如果您省略了某个字段，它将保持原样不变。

| 值 | `secrets`（密钥） | `connector_bindings`（连接器绑定） |
| --- | --- | --- |
| `null` | 使用 Agent 的密钥授权范围。 | 移除覆盖设置，使用项目默认配置。 |
| `[]` / `{}` | 不传递任何项目密钥。 | 完全不使用任何连接器账号（包括项目默认配置）。 |
| 列表 / 映射对象 | 仅传递这些指定的密钥（需在 Agent 的授权范围内）。 | 仅绑定这些指定的账号。 |

- 如果您本意是使用 `null` 却误传了 `{}`，将会阻断所有连接器。
- 连接器的变更将在下一次连接器调用时生效。
- 当传递的密钥集合发生变化时，密钥的变更会触发运行时（Runtime）重启。
- 被移除的密钥将无法再到达沙箱。但它**无法**从已经读取过该密钥的模型上下文或进程中抹除。如果这涉及安全问题，请及时轮换（Rotate）该密钥。
- 作用域变更（Rescope）不能超出 Agent 原有的授权范围。
- 仅会话所有者或项目管理员有权更改作用域。其他任何用户调用都会收到无错误代码的 `403` 响应。

#### 读取每个会话的用量（Read usage per session）

读取用量数据的操作永远不会唤醒沙箱：

```ts
const record = await s.cost(); // model and compute totals, tokens, compute time, ledger entries

const page = await kortix.billing.sessionCosts.list({
  projectId,
  from: '2026-10-01T00:00:00Z',
  to: '2026-11-01T00:00:00Z',
  limit: 25,
});
```

`sessionCosts.list` 会查询该账号在左闭右开的 UTC 时间窗口 `[from, to)` 内的所有会话成本。默认时间窗口为过去 30 天。可通过 `accountId`（账号 ID）、`projectId`（项目 ID）或 `ownerId`（所有者 ID）进行过滤。详见 [Billing（计费）](/docs/zh/guide#计费billing)。

### 错误与重试（Errors and retries）

#### 会话创建错误（Session create errors）

`sessions.create()` 和 `POST /projects/:id/sessions` 接口可能会返回以下错误。JSON 响应体中的 `code` 字段包含错误代码，SDK 会将其复制到 `ApiError.code` 中。

| HTTP 状态码 | 错误代码（Code） | 含义 |
| --- | --- | --- |
| `400` | `INVALID_SESSION_MODEL` | 模型 ID 格式错误，或该账号无权使用该模型。 |
| `400` | `INVALID_SESSION_CONNECTOR_BINDINGS` | 绑定映射（Binding map）格式错误。 |
| `400` | `INVALID_SESSION_RUNTIME_CONTEXT` | 运行时上下文违反了键、值、条目或大小规则，或者使用了保留的 `kortix.` 键。 |
| `400` | `INVALID_SESSION_SECRETS` | 密钥列表格式错误，或包含的标识符超过 128 个。 |
| `400` | `INVALID_IDEMPOTENCY_KEY` | `Idempotency-Key` 请求头长度超过 255 个字符，或包含了不允许的字符。 |
| `400` | `UNKNOWN_SANDBOX_TEMPLATE` | 指定的沙箱标识（slug）在项目中不存在。 |
| `402` | `subscription_required` / `insufficient_credits` | 该账号无法启动会话（需要订阅或余额不足）。 |
| `403` | `origin_override_forbidden` | 非 `backend`（后端）来源的调用方尝试发送密钥列表。 |
| `403` | `CONNECTOR_NOT_ASSIGNED` | Agent 未被授予您绑定的连接器的权限。 |
| `404` | `CONNECTOR_CONNECTION_NOT_FOUND` | 该项目下该连接器不存在此账号，或调用方无权使用。 |
| `404` | `SECRET_IDENTIFIER_NOT_FOUND` | 密钥列表中指定了未知的项目密钥。 |
| `409` | `CONNECTOR_CONNECTION_INACTIVE` | 该账号或其连接器处于非活跃、已禁用或未连接状态。 |
| `409` | `PERSONAL_CONNECTOR_CONNECTION_REQUIRES_PRIVATE_SESSION` | 将私有账号绑定到了非私有会话上。 |
| `409` | `SECRET_IDENTIFIER_KEY_COLLISION` | 列表中两个不同的密钥被设置为了相同的环境变量。 |
| `409` | `session_already_exists` | 具有该 `session_id` 的会话已存在。 |
| `409` | `repository_disconnected` | GitHub App 无法再连接到该项目的代码仓库。 |
| `409` | `IDEMPOTENCY_*_CONFLICT` | 另一个创建操作正持有该键，或者该键之前被用于不同的请求体。 |
| `409` | `IDEMPOTENCY_KEY_SESSION_DELETED` | 该键属于一个已被删除的会话。 |
| `500` | `SESSION_CREATE_FAILED` | 创建失败。响应体中包含 `retry: true`，请进行重试。 |
| `503` | `SESSION_MODEL_RESOLUTION_FAILED` | 服务器无法解析默认模型。请进行重试。 |

#### 作用域变更错误（Rescope errors）

`s.rescope()` 接口可能会返回以下错误：

| HTTP 状态码 | 错误代码（Code） | 含义 |
| --- | --- | --- |
| `400` | `INVALID_SESSION_SCOPE` | 请求体格式错误，或缺少必要的字段。 |
| `403` | `NOT_IN_AGENT_GRANT` | 指定的密钥超出了 Agent 的授权范围。 |
| `403` | `NOT_GRANTED_CONNECTOR` | 指定的连接器超出了 Agent 的授权范围。 |
| `403` | `SECRET_IDENTIFIER_NOT_AVAILABLE` | 指定的密钥不存在，或该会话无权使用。 |
| `403` | `CONNECTOR_CONNECTION_NOT_FOUND` / `CONNECTOR_CONNECTION_INACTIVE` | 该账号未知、不可用或处于非活跃状态。 |
| `409` | `AGENT_GRANT_UNRESOLVED` | 服务器无法读取 Agent 的授权信息。请进行重试。 |
| `409` | `SECRET_IDENTIFIER_KEY_COLLISION` | 列表中两个不同的密钥被设置为了相同的环境变量。 |
| `409` | `PERSONAL_CONNECTOR_CONNECTION_REQUIRES_PRIVATE_SESSION` | 将私有账号绑定到了非私有会话上。 |

#### 错误类（Error classes）

每次 SDK 调用在失败时都会抛出一个 `Error` 的子类。请先检查 `instanceof`，然后根据 `status`（状态码）或 `code`（错误代码）进行分支处理：

```ts
import { ApiError, BillingError, formatBillingErrorForUI, isAuthFailure } from '@kortix/sdk';

try {
  await kortix.project(projectId).sessions.create({ agent_name: 'support' });
} catch (err) {
  if (err instanceof BillingError) {
    const ui = formatBillingErrorForUI(err); // { alertTitle, alertSubtitle }
  } else if (isAuthFailure(err)) {
    // 401, 403 or no token: sign in again or fix the key
  } else if (err instanceof ApiError) {
    console.error(err.status, err.code, err.details);
  } else {
    throw err;
  }
}
```


| 错误类 | 抛出时机 | 关键属性 |
| --- | --- | --- |
| `ApiError` | 任何失败的请求：错误状态码、网络故障、超时或请求被中止。 | `status`、`code`、`details`（解析后的响应体）、`detail`（响应体中 FastAPI 风格的 `detail` 字段）、`response`、`url`、`endpoint`、`timeout` |
| `AuthError`（继承自 `ApiError`） | `getToken()` 返回 `null` 时。此时不会发送任何请求。 | `code` 为 `NO_SESSION` |
| `BillingError`（继承自 `ApiError`） | 收到所有 `402` 状态码时。 | `code`（例如 `insufficient_credits`）；`detail.message` |
| `RequestTooLargeError`（继承自 `ApiError`） | 收到 `431` 状态码时：请求头过大（例如单次请求中包含过多文件）。 | `detail.message`、`detail.suggestion` |
| `SessionNotReadyError` | 在调用 `ensureReady()` 之前执行了预览（preview）方法。 | `name` 为 `SessionNotReadyError` |
| `SessionStartError` | `ensureReady()`、`start()` 或 `startOrThrow()` 收到除 `408` 或 `429` 之外的 `4xx` 错误。该类**不**继承自 `ApiError`。 | `status`、`code`、`terminal`。可使用 `isSessionStartError(err)` 进行检查。 |

用于对错误进行分类的辅助函数：

| 辅助函数 | 返回 `true` 的条件 |
| --- | --- |
| `isAuthFailure(err)` | 错误为 `AuthError`，或者其 `status` 为 `401` 或 `403`。 |
| `isFeatureDisabledError(err)` | 功能标志（Flag）控制的路由被拒绝：返回 `403` 且 `code` 为 `FEATURE_DISABLED_CODE`（`feature_disabled`）。`featureDisabledKey(err)` 会返回对应的标志名称。 |
| `isRepositoryDisconnectedError(err)` | GitHub App 无法再连接到代码仓库：`code` 为 `REPOSITORY_DISCONNECTED_CODE`（`repository_disconnected`）。API 会随 `409` 状态码返回此错误。 |
| `isSandboxNotReadyError(err)`、`isRuntimeStartingError(err)` | 沙箱正在启动、已停止或处于挂起（parked）状态。建议显示等待状态并进行重试。 |
| `formatBillingErrorForUI(err)` | 针对 `BillingError` 返回 `{ alertTitle, alertSubtitle }`，否则返回 `null`。 |

- `code` 是 API 返回的错误代码，或者是状态码的字符串形式。
- 被中止的请求的 `name` 为 `'AbortError'`，`code` 为 `'ABORTED'`。这不被视为失败。
- 每个请求的默认超时时间为 `30000` 毫秒。超时请求的 `code` 为 `'TIMEOUT'`。
- 在 `getToken()` 重新执行后，会再发送一次 `401` 请求。详见 [SDK authentication（SDK 身份验证）](#sdk-认证)。
- 登录调用会抛出 `HeadlessAuthError`。详见 [SDK authentication（SDK 身份验证）](#sdk-认证)。

在您的代码捕获到错误之前，SDK 会自动重试某些请求：

| 请求方法 | 会重试的情况 | 绝不重试的情况 |
| --- | --- | --- |
| `GET`、`HEAD` | 遇到 `502`、`503`、`504` 或网络故障时，最多重试 2 次（分别在 250 毫秒和 500 毫秒后） | 遇到 `500` 或任何其他状态码 |
| `DELETE` | 遇到网络故障且没有收到任何响应时，最多重试 2 次 | 收到任何状态码时 |
| `POST`、`PUT`、`PATCH` | 从不重试 | — |

会话创建（Session create）是一个 `POST` 请求。为了使其具备重试安全性，请参阅 [安全地重试创建操作](#安全地重试创建操作)。

## 通过代码管理项目（Projects from code）

项目（Project）拥有其代码仓库、连接器、密钥、触发器和应用（Apps）。会话在项目中运行。本节展示了每个项目级任务对应的单次调用。所有方法均挂载在项目句柄 `kortix.project(projectId)` 上。创建该句柄不会发送任何请求。完整的方法列表请参阅 [SDK 参考文档 > 项目句柄](#sdk-参考sdk-reference)。

以下每个示例均假设已按照 [创建客户端](#创建客户端) 中的说明创建了一个客户端：

```ts
import { createKortix } from '@kortix/sdk';

const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => process.env.KORTIX_API_KEY!,
});
const p = kortix.project(process.env.KORTIX_PROJECT_ID!);
```

### 创建并更新项目（Provision and update a project）

`kortix.projects.provision(input)` 用于创建一个由 OpenChatly 托管 Git 仓库的项目。该方法会初始化 OpenChatly 的入门模板（Starter），以便会话可以立即启动。该请求的超时时间为 120,000 毫秒。

| 字段 | 规则 |
| --- | --- |
| `name` | 必填。 |
| `idempotency_key` | 在每次尝试创建时发送相同的键。重试时将返回首次创建的项目。该键的作用域限定在账号级别。它标识的是**创建尝试**而非请求体内容：如果复用同一个键但传入了不同的 `name`，依然会返回首次创建的项目。 |
| `account_id` | 拥有该项目的账号。若省略，则使用调用方的默认账号。 |
| `starter_template` | 可选值为 `general-knowledge-worker` 或 `minimal`。 |
| `source_item_id` | 克隆市场（Marketplace）中的 `registry:project` 条目，以替代入门模板。当同时设置时，此字段的优先级高于 `starter_template`。 |
| `marketplace_items` | 需要安装的市场条目 ID 列表。 |
| `default_branch` | 新仓库的默认分支。若省略，则使用服务器默认分支。 |
| `icon` / `icon_glyph` | 一个 Emoji 字符串，或一个 `ProjectGlyph` 对象。当两者同时设置时，`icon_glyph` 优先。无效的值会被丢弃，且**不会**导致创建请求失败。 |

如果收到 `409` 状态码且错误代码为 `provision_in_flight`（`PROVISION_IN_FLIGHT_CODE`），表示使用相同键的早期调用仍在运行中。请使用相同的键进行重试。

```ts
import { ApiError, PROVISION_IN_FLIGHT_CODE } from '@kortix/sdk';

const key = crypto.randomUUID();

async function provision() {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return await kortix.projects.provision({ name: 'Northwind support', idempotency_key: key });
    } catch (error) {
      if (!(error instanceof ApiError) || error.code !== PROVISION_IN_FLIGHT_CODE) throw error;
      await new Promise((resolve) => setTimeout(resolve, 2_000));
    }
  }
  throw new Error('provision still in flight after 5 attempts');
}

const project = await provision();
console.log(project.project_id, project.default_branch);
```

通过项目句柄（Handle）读取和更改项目：

| 方法 | 返回值 |
| --- | --- |
| `p.get()` | `KortixProject` 数据行：包含 `project_id`、`account_id`、`name`、`repo_url`、`default_branch`、`manifest_path`、`status`（`active` 或 `archived`）。 |
| `p.detail()` | 包含完整配置的项目信息。 |
| `p.update(input)` | 更新后的数据行。`input` 接受 `name`、`default_branch`、`manifest_path`、`icon` 和 `icon_glyph`。省略某个键即可保持其原有值。设置 `icon: null` 将移除图标。 |
| `p.archive()` | `{ ok }`。项目状态将变更为 `status: 'archived'`（已归档）。 |

```ts
await p.update({ name: 'Northwind support (EU)' });
```

### 调用连接器（Call a connector）

`p.connector(slug)` 会返回一个连接器句柄。`run(action, args, options?)` 会返回操作的输出结果，且已剥离提供商的外层包装（Provider envelope）。连接器调用不具备幂等性，因此 `run` 方法永远不会进行重试。

```ts
import { ConnectorApprovalPendingError, ConnectorCallError } from '@kortix/sdk';

const gmail = p.connector('gmail');

try {
  const output = await gmail.run(
    'send_email',
    { to: 'ops@example.test', subject: 'Weekly report', body: 'Attached.' },
    { approvalContext: 'Send the weekly report to the ops list' },
  );
  console.log(output);
} catch (error) {
  if (error instanceof ConnectorApprovalPendingError) {
    console.log('Waiting for approval:', error.approvalUrl ?? error.executionId);
  } else if (error instanceof ConnectorCallError) {
    console.error(error.status, error.code, error.hint);
    if (error.connectUrl) console.error('Connect an account:', error.connectUrl);
  } else {
    throw error;
  }
}
```

`run` 的选项参数（`ConnectorCallOptions`）：

| 选项 | 规则 |
| --- | --- |
| `account` | 来自 `accounts()` 的连接标签或 ID；或 `me`（调用者自己的默认私有账号）；或 `project`（与项目共享的默认账号）。省略时使用连接器的默认账号。指定的命名账号绝不会被替换为其他账号。 |
| `approvalContext` | 用调用方的语言描述该次调用要做什么。当某项策略（policy）拦截该次调用时，审批人会看到这段描述。提供商（Provider）永远不会收到它。 |
| `timeoutMs` | 客户端超时截止时间。默认为 90,000 毫秒。在客户端超时之后，该次调用实际上仍可能已经执行完成。 |
| `signal` | 中止该请求。该次调用在上游（upstream）仍可能已经执行完成。 |

该句柄的其他方法：

| 方法 | 返回值 |
| --- | --- |
| `describe()` | 返回该连接器及其每一个操作（action）的输入与输出 schema（模式）；当调用方无权调用时返回 `null`。 |
| `describe(action)` | 返回单个操作及其 schema；若无则返回 `null`。 |
| `accounts()` | 返回调用方可以用来执行该连接器的所有账号，默认账号排在最前。 |
| `paginate(action, args, { next, maxPages? })` | 一个异步迭代器，逐个产出每一页的输出结果。`next(output, args)` 返回下一页的参数；在最后一页之后返回 `undefined`。`maxPages` 默认为 100。 |
| `call(action, args, options?)` | 返回原始的调用结果。`200` 和 `202` 状态码都会被解析（resolve）。 |
| `uploadAttachment(content, input)` | 为后续对该连接器的调用暂存（Stage）一个文件。 |

Composio 工具的文件字段（例如 YouTube 的 `videoFile` 或 Gmail 的 `attachment`）需要一个公开的 `https` URL。请将该 URL 作为字段的值传入，或作为文件对象的 `s3key` 或 `url` 传入。OpenChatly 会通过其出站防护（egress guard，仅允许公开主机，最大 100 MB）下载该文件，将其上传到 Composio，并发送 Composio 的文件引用。如果下载失败，将返回 `file upload failed for <field>: …`（`<field>` 字段文件上传失败：……）。

```bash
kortix connectors call youtube multipart_upload_video '{"title":"Demo","videoFile":"https://example.com/demo.mp4"}'
```

##### 将视频上传至 YouTube

一键连接 YouTube：从目录（Catalogue）中安装 YouTube 应用，然后使用 Google 账号登录即可。无需配置 API 密钥、客户端 ID 或客户端密钥。

`youtube.upload_video` 可将会话（Session）中的文件直接上传至 YouTube，文件大小不受 OpenChatly 限制（最大支持 YouTube 的 256 GB 上限）。该操作由 OpenChatly 代为执行。它会在已连接的账号下发起一个 YouTube 可恢复上传（Resumable upload）任务，并返回以下信息：

| 字段 | 说明 |
| --- | --- |
| `caller_only.upload_url` | 上传会话的 URL。该 URL 仅对当前这一个视频有效，且大约在一周后过期。 |
| `caller_only.upload_command` | 一个用于将文件发送至上传 URL 的 `curl` 命令。它会输出视频资源信息：其中 `id` 即为视频 ID，对应链接为 `https://youtu.be/<id>`。 |
| `caller_only.resume_status_command` | 用于查询 YouTube 已接收的字节数。如果返回 HTTP `308` 状态码及 `Range: bytes=0-N` 响应头，则表示从第 `N+1` 个字节开始继续发送剩余数据。 |
| `video` | YouTube 接收到的视频标题、隐私状态和发布时间表。 |

文件会从会话直接传输至 Google。Google 的身份验证令牌（Token）保留在登录提供商处，绝不会进入会话中。上传 URL 是专门针对单个视频的凭证。当某项策略（Policy）拦截该调用以待审批时，审阅人看到的已存储结果中会剔除 `caller_only` 字段；只有返回给调用会话的恢复提示（Resume prompt）中才会携带该字段。

请使用 `jq --arg` 来构建参数。切勿将文件路径直接粘贴到 JSON 字符串中，以免文件名中包含的引号导致 JSON 结构被破坏并意外增加字段。

```bash
F=/workspace/output/video.mp4
jq -n --arg file "$F" --argjson size "$(stat -c %s "$F")" \
  '{title:"Launch demo", privacy_status:"private", file_path:$file, file_size:$size, mime_type:"video/mp4"}' \
  > /tmp/yt-args.json
kortix connectors call youtube upload_video @/tmp/yt-args.json --out /tmp/yt-upload.json
bash -c "$(jq -r '.data.result.caller_only.upload_command' /tmp/yt-upload.json)"
```

参数：`title`（必填，最多 100 个字符）、`description`（描述）、`tags`（标签）、`category_id`（分类 ID）、`privacy_status`（隐私状态，默认为 `private` 私享，还可设为 `unlisted` 不公开列示、`public` 公开）、`publish_at`（一个 ISO 8601 格式的时间；需要搭配 `private` 使用）、`made_for_kids`（是否为儿童制作）、`contains_synthetic_media`（是否包含合成媒体内容）、`notify_subscribers`（是否通知订阅者，默认为 `true`）、`default_language`（默认语言）、`file_path` 与 `file_size`（会被写入 `upload_command`）、`mime_type`（MIME 类型，默认为 `video/*`）。

| 响应 | 含义 |
| --- | --- |
| `400` | 某个参数有误。错误信息会指出是哪一个。 |
| `upstream_429` | YouTube 的每日上传配额已用尽。请在太平洋时间午夜之后再重试。 |
| `upstream_502` 且伴随 `youtubeSignupRequired` | 该 Google 账号没有 YouTube 频道。请在 youtube.com/create_channel 创建一个。 |

`kortix connectors types --out kortix-connectors.d.ts` 会为 `run`、`call` 和 `paginate` 生成类型定义。若没有该文件，参数会被视为任意对象（any object），输出则为 `unknown`。

#### 连接器错误（Connector errors）

| 错误类 | 触发时机 | 需读取的字段 |
| --- | --- | --- |
| `ConnectorCallError` | 调用未执行，或执行后失败。继承自 `ApiError`。 | `code`：`upstream_<status>`（例如 `upstream_429`）、当 `2xx` 响应内部发生失败时的 `upstream_error`，或一个由服务端给出的原因，如 `connector_not_connected`、`account_required`、`credential_not_shared`、`credential_undecryptable`、`policy_block`、`upstream_timeout`、`computer_offline`、`invalid_json`，若以上均不符则为 `connector_error`。此外还有 `reason`、`hint`、`connectUrl`、`availableAccounts`、`requestedAccount`、`upstreamStatus`、`retryAfterSeconds`、`binding`。 |
| `ConnectorApprovalPendingError` | 某项策略（policy）拦截该调用，等待人工决策（HTTP `202`）。此时尚未执行任何操作。 | `executionId`、`approvalUrl`、`approvalSummary`、`approvalInstructions`、`retryable`。当 `retryable` 为 true 时，完全相同的调用会在审批通过后执行。 |
| `ConnectorPageLimitError` | `paginate` 已达到 `maxPages` 上限，但仍有更多分页。`code` 为 `max_pages_exceeded`。 | `nextArgs`：将其传入 `paginate` 即可续传（resume）。 |

仅在 `upstreamStatus` 为 `429` 或 `503` 时进行重试，并需等待 `retryAfterSeconds` 所指示的时间之后。其他所有错误都需要人工介入：从 `connectUrl` 连接一个账号、从 `availableAccounts` 中挑选一个账号，或对某次审批作出决策。

#### 在 React 中读取连接器（Read a connector in React）

来自 `@kortix/sdk/react` 的 `useConnectorQuery(projectId, slug, action, args, options?)` 会将单个操作作为带缓存的查询（cached query）来读取。请仅将其用于**读取类**操作：每一次抓取（fetch）都会在上游执行该操作，并写入一条审计记录（audit row）。

```tsx
import { useConnectorQuery } from '@kortix/sdk/react';

function Inbox({ projectId }: { projectId: string }) {
  const { data, error, isPending } = useConnectorQuery(projectId, 'gmail', 'fetch_emails', { max_results: 10 });
  if (isPending) return <p>Loading</p>;
  if (error) return <p>{error.message}</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
```


| 选项 | 规则 |
| --- | --- |
| `account` | 与 `run` 中的规则相同。 |
| `enabled` | 设为 `false` 会使查询保持空闲状态。如果 `projectId` 为 `null`，查询同样会保持空闲。 |
| `staleTime` | 数据过期时间。默认为 30,000 毫秒。 |

该 Hook 仅在遇到上游返回 `429` 或 `503` 状态码时进行重试，最多重试 2 次，且需等待 `Retry-After` 响应头指定的时间之后。窗口重新获得焦点（Window focus）时永远不会触发重新抓取。遇到 `connector_not_connected`（连接器未连接）错误时，请配合使用 `useConnectorSetup` 来渲染一个连接按钮。在 OpenChatly 应用中，客户端会将当前用户读取为查看者（Viewer）：详见 [在 OpenChatly 应用中识别查看者](#识别-openchatly-app-中的查看者)。

#### 管理连接器和策略（Manage connectors and policies）

相关配置均位于 `p.connectors` 下：

| 任务 | 调用方法 |
| --- | --- |
| 列出并检查 | `p.connectors.list()`、`.config(slug)`、`.catalog()`、`.search(query)` |
| 添加与移除 | `p.connectors.create(input)`、`.remove(slug)`、`.discover.install({ id, way?, name?, slug? })` |
| 设置基础规则 | `p.connectors.policies.set(slug, rules)` |
| 设置某个策略集（Policy set）的规则 | `p.connectors.policies.set(slug, rules, { policySet: name })` |
| 创建或列出策略集 | `p.connectors.policySets.upsert(slug, name, { description? })`、`.list(slug)` |
| 将策略集绑定到 Agent | `p.setAgentScope(agentName, { policy_sets: { [slug]: name } })` |

一条规则的结构为 `{ match, action, conditions? }`。`match` 是针对工具名称的通配符匹配（Glob）。`action` 的可选值为 `always_run`（始终执行）、`require_approval`（需要审批）或 `block`（阻断）。`policies.set` 会完全替换整个规则列表。

```ts
await p.connectors.policies.set('gmail', [
  { match: 'fetch_*', action: 'always_run' },
  { match: 'send_*', action: 'require_approval' },
  { match: 'delete_*', action: 'block' },
]);
```

关于项目规则（Project rules）、策略集（Policy sets）和基础规则（Base rules）是如何结合使用的，请参阅 [Connectors（连接器）](/docs/zh/guide#连接器connectors)。

### 存储密钥（Store secrets）

`p.secrets.upsert(input)` 用于创建或更新项目密钥。该密钥的值是**仅可写入**的（write-only）：任何接口调用都不会返回该值。当采用 `runtime`（运行时）策略时，会话会将该密钥作为名为 `name` 的环境变量进行读取。

```ts
await p.secrets.upsert({ name: 'ACME_API_KEY', value: process.env.ACME_API_KEY! });

const { items } = await p.secrets.list();
for (const secret of items) {
  console.log(secret.identifier, secret.configured, secret.status ?? 'ok');
}
```

| `upsert` 字段 | 规则 |
| --- | --- |
| `name` | 必填。即环境变量名称。 |
| `value` | 若省略，则保留已存储的值。 |
| `identifier` | 在项目内必须唯一。默认值为 `name`。当需要在同一个 `name` 下存储第二个密钥时，需设置此字段。 |
| `strategy` | 决定该值如何传递给会话。`runtime`（对应 `environment` 暴露方式）会设置一个环境变量。`egress`（对应 `egress-enforced`）会在会话中放入一个句柄（Handle），OpenChatly 会在向已批准的主机发送请求时自动替换为真实值。`broker` 会将该值完全隔离在会话之外。`denied`（对应 `none`）不传递任何内容。默认为 `runtime`。`kortix secrets` 命令行工具也接受括号中的暴露方式名称。 |
| `consumer` / `egress_policy` / `handle_prefix` | `egress` 和 `broker` 策略的传递设置。详见 [Security（安全性）](/docs/zh/guide#安全性)。 |
| `shared_with` | 允许使用该共享值的人员、用户组和 Agent。设为 `[]` 表示项目内的所有人。若省略，则保留当前的列表。 |

`list()` 会返回 `{ items, required, optional }`。其中 `required` 和 `optional` 是 `kortix.yaml` 中声明的环境变量键。若某个密钥的 `status` 为 `'undecryptable'`（无法解密），则必须通过 `upsert` 重新设置。`mine` 描述了调用者自己的密钥值，可通过 `setPersonal(name, { value })` 进行设置。

`p.secrets.setGitCredential({ token })` 用于为自带（Bring-your-own）的 Git 仓库存储访问令牌（Token）。该方法会返回 `{ configured, provider, git_connection }`。

```ts
await p.secrets.setGitCredential({ token: process.env.GIT_TOKEN! });
```

### 运行触发器（Run triggers）

触发器（Trigger）可以基于定时计划、Webhook 或 App 事件来启动会话（Session）或调用 App。`p.triggers.create(input)` 会返回完整的触发器列表（包含 `{ triggers, errors, triggers_paused }`）。

```ts
await p.triggers.create({
  name: 'Daily digest',
  slug: 'daily-digest',
  type: 'cron',
  every: '1d',
  prompt_template: 'Summarize yesterday’s support tickets.',
});

const run = await p.triggers.fire('daily-digest');
console.log(run.status, run.session_id, run.run_id);
```

| `create` 字段 | 规则 |
| --- | --- |
| `name` / `type` | 必填。`type` 的可选值为 `cron`、`webhook`、`event`、`app` 或 `change_request`。如果传入 `monitor`，API 会返回 `400` 拒绝该请求。 |
| `connector` / `event` / `event_account` / `event_source` / `event_config` | 针对 `event` 类型：需指定连接器 slug 和来自 `p.triggers.eventTypes(...)` 的事件类型 ID，以及可选的账号、来源和提供商配置。 |
| `slug` | 若省略，则根据 `name` 自动生成。创建后不可更改。 |
| `prompt_template` | 必填（除非 `target` 指定调用的是 App）。 |
| `cron` / `every` / `run_at` / `timezone` | 用于 `cron` 类型的调度计划：可以是 6 字段的 cron 表达式、如 `5m` 或 `1h` 的时间间隔（最小为 `1m`），或一个 ISO-8601 格式的具体时间点。`timezone` 默认为 `UTC`。 |
| `secret_env` | 针对 `webhook` 类型：用于验证交付（deliveries）签名的项目密钥。 |
| `app` | 针对 `app` 类型：必填。指定其事件会触发该触发器的 App slug。该 App 必须已存在。 |
| `filter` | 将 Payload 路径映射到其必须满足的条件，例如 `{ 'event.name': … }`。未通过过滤的 Payload 不会启动任何会话。 |
| `target` | `{ app, path?, method?, payload? }`：用于调用 App 而非 Agent。 |
| `agent` / `model` | 指定 Agent（默认为 `default`）以及 `provider/model` 的覆盖项。 |

连接器事件触发器（Connector event triggers）目前处于实验阶段，默认关闭。请在 **Project admin** → **Feature flags**（项目管理员 → 功能标志）中开启。

关于每个字段的详细说明（包括会话复用和速率限制），请参阅 [Triggers（触发器）](/docs/zh/guide#触发器triggers)。

| 调用方法 | 功能说明 |
| --- | --- |
| `p.triggers.update(slug, input)` | 更改触发器。传入 `null` 可清空某个可空字段。 |
| `p.triggers.fire(slug, { payload?, dryRun? })` | 立即运行一次触发器（即使触发器处于暂停状态也可执行）。`payload` 会与手动传入的 payload 进行深度合并（deep-merge）。设置 `dryRun: true` 时不会写入任何数据，仅返回 `rendered_prompt`、`filter_matches`、`session_key` 和 `payload`。实际触发会返回 `status`（`fired`、`queued`、`deduped` 或 `failed`）、`session_id`、`command_id` 和 `run_id`。 |
| `p.triggers.runs(slug, { cursor?, limit? })` | 获取某个触发器的运行记录，按时间倒序排列：返回 `{ runs, next_cursor }`。`limit` 范围为 1 到 100，默认为 25。在 `next_cursor` 有值的情况下，某一页返回的记录数可能少于 `limit`。请持续跟随 `next_cursor` 直到其为 `null`。 |
| `p.triggers.replay(slug, runId, { confirmUnverified? })` | 使用当前触发器配置和该次运行存储的 payload 再次触发。若该运行正在排队或执行中，返回 `409 run_in_progress`。若为未经身份验证的 Webhook payload 且未设置 `confirmUnverified: true`，返回 `409 payload_unverified`。若 payload 超过 64 KiB，返回 `422 payload_truncated`。 |
| `p.triggers.setActivation(paused)` | 传入 `true` 会暂停该项目的所有触发器。传入 `false` 会恢复它们。手动调用 `fire` 依然有效。 |

```ts
const { runs } = await p.triggers.runs('daily-digest', { limit: 10 });
const failed = runs.find((r) => r.status === 'failed');
if (failed) await p.triggers.replay('daily-digest', failed.run_id);
```

### 处理审批（Resolve approvals）

当策略规则（Policy rule）设置为 `require_approval`（需要审批）时，连接器调用会被挂起，直到有人作出决策。

**项目级 Token 的行为：**
当调用方使用项目作用域的 Token（如会话 Token，或通过 `project_id` 创建的 PAT）时，OpenChatly 会接管该调用。审批通过后，系统会作为原始调用方执行**一次**该调用，并在运行时重新检查策略。**请勿重复发起该调用**：在等待或执行期间重复调用，将返回相同的 `execution_id`。被挂起的响应中会带有 `runs_on_approval: true` 标记。如果是在会话（Session）中，OpenChatly 会将结果返回给 Agent 并恢复其运行；如果不在会话中，请通过 ID 读取结果（见下文）。

**其他 Token 的行为：**
如果调用方使用的是其他 Token（如控制台登录 Token，或未绑定项目的 PAT），响应中**不会**包含 `runs_on_approval`。在这种情况下，仅仅审批通过并不会自动执行该调用：调用方必须在 **15 分钟内**，从**相同的会话和用户**下，使用完全相同的参数（相同的连接器、操作、参数和账号）重新发起调用，该调用才会被执行一次。

`p.approvals.list()` 会返回 `{ count, approvals }`。每条审批记录都包含 `execution_id`、`action`、`session_id`、`requested_at` 和 `expires_at`。

`p.approvals.resolve(executionId, decision, { note? })` 用于对某次调用作出决策。`decision` 的值为 `'approve'`（批准）或 `'deny'`（拒绝）。`note` 会作为指令传递给 Agent。只有项目经理或启动该会话的人才有权限作出决策。决策仅对当前这一次调用有效。

通过 `GET /v1/projects/:id/review/items/call:<execution_id>` 可以获取决策结果以及 `detail.next_step`。
- 如果调用由 OpenChatly 自动执行，返回结果会包含 `detail.run`：包括 `state`（`queued`、`dispatched`、`ok`、`error`、`refused` 或 `unknown`）、`finished_at`，以及包含最多 4 KB 脱敏 `output_preview`（输出预览）的 `outcome`。
- 如果调用是由调用方手动重新发起的，返回结果会包含是否使用了该审批（`approval_used_at`）以及重新执行的截止时间（`rerun_by`）。

若希望某个工具无需审批即可运行，请配置一条 `always_run`（始终执行）规则。

```ts
const { approvals } = await p.approvals.list();
for (const approval of approvals) {
  if (approval.action === 'gmail.send_email') {
    await p.approvals.resolve(approval.execution_id, 'approve');
  }
}

await p.approvals.resolve('<execution_id>', 'deny', { note: 'Send it to the ops list only.' });
```

在代码中，被挂起调用的 `executionId` 对应于 `ConnectorApprovalPendingError.executionId`。

- **使用项目级 Token 时**：请通过 ID 轮询读取接口，直到 `detail.run.state` 变为最终状态（final）；**请勿**重复发起 `run`。
- **使用其他 Token 时**：在审批通过后，重新发起完全相同的 `run`。

`p.approvals.sessionsNeedingInput()` 会返回 `{ total, sessions }`：表示每个会话中处于挂起状态的调用数量。

Review 收件箱（`p.review.*`）的相关说明请参阅 [SDK reference > The project handle（SDK 参考 > 项目句柄）](#sdk-参考sdk-reference)。

### 部署与运维 App（Deploy and operate Apps）

App 是由项目托管的服务。`p.apps` 可用于创建 App、上传构建产物（Build）、部署版本（Release）以及运行其底层机器。

1. **Create the App**

    ```ts
    const app = await p.apps.create({ slug: 'hello', name: 'Hello App' });
    ```

    `slug` 和 `name` 为必填项。`cpu`、`memory_gb`、`disk_gb`、`idle_timeout_seconds`、`always_on` 和 `uses` 为可选项。`external_url` 用于指定一个托管在其他地方且永远不会在此部署的 App。

2. **Register a build**

    ```ts
    const { artifact } = await p.apps.artifacts.register({
      kind: 'oci_image',
      image: 'docker.io/hashicorp/http-echo:1.0',
    });
    ```

    如果是 `.tar.gz` 格式的构建产物，请改为调用 `artifacts.uploadArchive(bytes)`。该方法会注册一个 `kind: 'archive'` 类型的产物，上传字节数据，并使用 `sha256` 和 `size_bytes` 完成产物的最终确认。它会返回 `AppArtifact` 对象。

3. **Deploy a release**

    ```ts
    const deployment = await p.apps.deployments.create(app.app_id, {
      artifact_id: artifact.artifact_id,
      source: {
        kind: 'oci_image',
        image: 'docker.io/hashicorp/http-echo:1.0',
        command: ['http-echo', '-listen=:5678', '-text=Hello'],
        port: 5678,
      },
    });
    ```

    `source.kind` 的可选值为 `static`、`bundle`、`dockerfile` 或 `oci_image`。`environment` 用于存放非密钥类型的环境变量值。`secrets` 则用于将环境变量键映射到项目密钥的标识符（identifier）。

4. **Wait for the release**

    ```ts
    let status = deployment.status;
    while (!['ready', 'failed', 'cancelled'].includes(status)) {
      await new Promise((resolve) => setTimeout(resolve, 3_000));
      status = (await p.apps.deployments.get(app.app_id, deployment.deployment_id)).deployment.status;
    }
    console.log(status, app.url);
    ```

    一个版本（Release）会依次经历 `queued`（排队中）、`validating`（验证中）、`building`（构建中）、`provisioning`（资源分配中）和 `checking`（检查中）状态，最终变为 `ready`（就绪）、`failed`（失败）或 `cancelled`（已取消）。`deployments.logs(appId, deploymentId, { after?, limit? })` 会返回 `{ entries, next_cursor }`。

**App 运维操作：**

| 调用方法 | 功能说明 |
| --- | --- |
| `p.apps.start(appId)` / `p.apps.stop(appId)` | 启动或停止 App。返回 `App` 对象。 |
| `p.apps.deployments.list(appId)` | 获取该 App 的所有版本记录。 |
| `p.apps.rollback(appId, deploymentId)` | 使用早期版本的构建产物和配置，排队创建一个新版本。返回包含该 `deployment` 的 `App` 对象。 |
| `p.apps.scale(appId, { app: 2 })` | 设置每个进程组（Process group）的机器数量，范围为 0 到 20，在后台应用。如果某个组挂载了卷（Volume），默认只运行 1 台机器，除非在第三个参数中传入 `{ newVolumes: true }`。 |
| `p.apps.exec(appId, { command, machine_id?, timeout_s? })` | 在某台机器上执行单条命令。仅限项目管理员使用。`timeout_s` 范围为 1 到 300，默认为 60。返回 `exit_code`、`stdout`、`stderr`（每项最多 1 MiB）以及 `truncated`（是否被截断）。 |
| `p.apps.deployments.remove(appId, deploymentId)` | 删除未处于活跃状态（非 live）的版本。若尝试删除当前活跃版本，返回 `409 deployment_live`；若构建正在进行中，返回 `409 deployment_in_progress`。 |

```ts
const result = await p.apps.exec(app.app_id, { command: ['sh', '-c', 'uptime'] });
console.log(result.exit_code, result.stdout);
```

关于机器（Machines）、卷（Volumes）、访问权限（Access）、App 令牌（App tokens）和 `authEnv` 的说明，请参阅 [SDK reference > The project handle（SDK 参考 > 项目句柄）](#sdk-参考sdk-reference)。关于 `kortix.yaml` 中的 App 配置，请参阅 [Apps reference（Apps 参考）](#应用参考apps-reference)。

### 文件、Git 与变更请求（Files, git and change requests）

以下接口用于读写项目代码仓库。若要操作正在运行的会话（Session）中的文件，请使用 [Sessions from code（代码中的会话）](#从代码管理会话) 中的 `s.files`。

| 调用方法 | 功能说明 |
| --- | --- |
| `p.files.listDirectory({ path?, ref?, cursor?, limit? })` | 获取单层文件夹内容：返回 `{ entries, truncated, next_cursor }`。若指定了 `cursor` 或 `limit`，单页包含 `limit` 条记录（默认 500，最多 2,000）。若未指定，单次响应最多包含 5,000 条记录。 |
| `p.files.read(path, ref?)` | 读取文件：返回 `{ path, ref, content, revision? }`。若服务器版本早于 `revision` 字段引入的时间，则返回值中会省略该字段。 |
| `p.files.write({ path, ref, content, expected_revision })` | 提交单个文件。`expected_revision` 为 `read` 接口返回的 `revision` 值。返回 `{ commit_sha }`。 |
| `p.files.search(query, { content?, ref?, limit? })` | 搜索文件名；若设置 `content: true`，则搜索文件内容。 |
| `p.git.commits()` / `p.git.commitDiff(sha)` / `p.git.branches()` | 分别用于获取提交日志（Log）、某个提交的差异（Diff）以及分支列表（Branches）。 |
| `p.changeRequests.list(status?, { limit?, cursor? })` | 分页获取变更请求，按编号从新到旧排列：返回 `{ change_requests, next_cursor }`。`status` 可选值为 `open`、`merged`、`closed` 或 `all`。`limit` 默认为 50。若超过 500，服务器将返回 `400` 错误。 |
| `p.changeRequests.open({ title, head_ref, base_ref?, description? })` | 从指定分支发起（Open）一个变更请求。 |
| `p.changeRequests.merge(crId, { message? })` / `.close(crId)` | 合并（Merge）或关闭（Close）变更请求。 |

在不覆盖并发修改的情况下编辑单个文件：

```ts
const file = await p.files.read('README.md');
await p.files.write({
  path: 'README.md',
  ref: file.ref,
  content: `${file.content}\nOwned by the Acme support team.\n`,
  expected_revision: file.revision ?? '',
});
```

审查（Review）处于开放状态的变更请求：

```ts
const { change_requests } = await p.changeRequests.list('open', { limit: 20 });
for (const cr of change_requests) console.log(cr.number, cr.title, cr.head_ref);
```

关于会话（Sessions）如何创建分支和变更请求的详细说明，请参阅 [Git](#git版本控制)。

## React

`@kortix/sdk/react` 是 SDK 的 React 封装层。其中的核心 Hook `useSession` 负责管理单个会话视图：包括启动（start）、流式传输（stream）、会话记录（transcript）、提示词（prompts）以及回复（replies）。该层会读取您在 [SDK > 创建客户端](#创建客户端) 中创建的客户端（Client），且不会创建第二个客户端实例。它同时支持 React 和 React Native 环境。

本节将介绍如何构建单个会话视图，从初始配置到自行渲染每一条消息。关于账号、项目、触发器、Apps 以及权限检查的完整 Hooks 目录，请参阅 [SDK reference（SDK 参考）](#sdk-参考sdk-reference)。预构建组件请参阅 [OpenChatly UI](#ui-组件kortixui)。

### 初始配置（Set up）

1. **Install the peers（安装对等依赖）**

    `react` 18 或更高版本以及 `@tanstack/react-query` `^5.75.2` 是 `@kortix/sdk` 的可选对等依赖（Optional peers）。但 React 封装层需要这两者才能正常运行。

    ```bash
    npm install @kortix/sdk react @tanstack/react-query
    ```

2. **Import the client module once（仅导入一次客户端模块）**

    `createKortix()` 会写入一个进程级别的全局配置。由于所有的 Hook 都会读取该配置，因此没有任何 Hook 需要接收客户端（Client）作为参数。请务必在第一个 Hook 渲染之前，导入用于创建客户端的模块。

    ```ts
    // lib/kortix.ts
    import { createKortix } from '@kortix/sdk';

    export const kortix = createKortix({
      backendUrl: 'https://api.example.test/v1',
      getToken: async () => readSessionToken(),
    });

    declare function readSessionToken(): Promise<string | null>;
    ```

    关于配置选项和“每个宿主（Host）仅一个客户端”的规则，请参阅 [Create the client（创建客户端）](#创建客户端)。关于 `getToken` 的来源说明，请参阅 [SDK authentication（SDK 身份验证）](#sdk-认证)。

3. **Mount QueryClientProvider（挂载 QueryClientProvider）**

    `useSession`、提示词相关的 Hooks 以及大部分数据 Hooks 底层均基于 React Query。若未提供 `QueryClientProvider`，这些 Hooks 将会抛出错误。请确保每个宿主（Host）仅保留一个 `QueryClient` 实例。

    ```tsx
    'use client';
    import '@/lib/kortix';
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { useState, type ReactNode } from 'react';

    export function Providers({ children }: { children: ReactNode }) {
      const [queryClient] = useState(() => new QueryClient());
      return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
    }
    ```

4. **Optional: KortixProjectProvider（可选：KortixProjectProvider）**

    SDK 本身不读取路由（Router）。但某些 Hooks 需要知道“当前屏幕上显示的项目”，例如 `useRuntimeProviders` 和 `useRuntimeLocal`。`KortixProjectProvider` 用于提供该项目的 ID，而 `useKortixRouteProjectId()` 则用于读取它。在 Provider 外部，该 ID 为 `null`。`useSession` 不需要此 ID。

    ```tsx
    import { KortixProjectProvider } from '@kortix/sdk/react';
    import type { ReactNode } from 'react';

    export function ProjectScope({ projectId, children }: { projectId: string | null; children: ReactNode }) {
      return <KortixProjectProvider projectId={projectId}>{children}</KortixProjectProvider>;
    }
    ```

### useSession

`useSession(projectId, sessionId, options?)` 用于端到端地运行单个会话视图。它会通过长轮询（Long-poll）请求 `POST …/start` 接口，直到沙箱（Sandbox）准备就绪，随后打开事件流（Event stream），读取已保存的历史记录，同步消息与状态，并发送提示词（Prompts）。每个会话视图只需调用一次。当 `/start` 接口返回 `stage: 'ready'` 时，即表示沙箱已准备就绪。该 Hook 不会执行单独的健康检查。

```tsx
import { useSession } from '@kortix/sdk/react';

export function SessionView({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const s = useSession(projectId, sessionId);

  if (s.messages.length === 0 && s.phase !== 'ready') {
    if (s.phase === 'error') return <NotRunning stage={s.stage} onRetry={s.retry} />;
    if (s.conversationEmpty) return <Composer disabled onSend={s.send} />;
    return s.savedTranscript === 'none' ? <Booting stage={s.stage} /> : <MessageSkeleton />;
  }

  return (
    <>
      {s.messages.map(({ info, parts }) => (
        <Message key={info.id} info={info} parts={parts} />
      ))}
      {s.sendError && <p role="alert">{s.sendError.message}</p>}
      <Composer
        disabled={s.phase !== 'ready'}
        busy={s.isBusy}
        canStop={s.canStop}
        onSend={s.send}
        onStop={() => void s.cancel()}
      />
    </>
  );
}
```

`NotRunning`、`Composer`、`Booting`、`MessageSkeleton` 和 `Message` 是您需要自行实现的组件。

#### 渲染规则

在会话启动期间，请根据以下规则选择要渲染的视图：

| 状态 | 渲染内容 |
| --- | --- |
| `messages` 包含数据行 | 渲染会话记录（Transcript）。在沙箱唤醒之前，会先渲染已保存的历史记录。 |
| 没有数据行且 `conversationEmpty` 为 `true` | 渲染输入框（Composer）。表示会话没有消息，也没有需要等待的内容。 |
| 没有数据行且 `savedTranscript` 为 `'loading'` | 渲染占位符行。表示已保存的副本正在加载中。 |
| 没有数据行且 `savedTranscript` 为 `'none'` | 渲染带有 `stage` 状态的启动屏幕。在运行时响应之前，无法显示任何内容。 |
| `phase` 为 `'error'` | 渲染 `startError` 或 `failure` 信息，并提供一个调用 `retry()` 的重试（Retry）按钮。 |

**已保存的历史记录**是指 API 存储的会话日志副本。即使沙箱已停止，也不会阻止获取该副本。

- 首次读取会获取最新的 40 条消息。可通过 `loadOlder()` 向前翻页加载更早的消息。如果存储中没有日志，则会向运行时（Runtime）发起分页请求。
- 未知的 `savedTranscript` 状态会被视为 `'loading'`，绝不会是 `'none'`。
- 当 `GET …/log` 请求失败时（如 `5xx` 错误、网络问题、无 `code` 的 `404` 错误或无效的分页参数），`useSession` 会保留当前屏幕上的副本，并在 2 秒、10 秒和 30 秒后，或在 API 返回的 `Retry-After` 时间后（最多 60 秒）重新读取该页。
- 没有任何 Hook 会读取 `GET …/transcript` 接口。

若要在 `useSession` 绑定会话之前显示会话内容（例如在连接屏幕中），可从 `@kortix/sdk` 调用 `readSavedSessionCopy({ projectId, sessionId, runtimeSessionId })`。该方法永远不会抛出异常，并会解析返回 `{ log, empty, envelope }`：

- `log` 是最新的会话日志页（`GET …/log`）。对于没有存储日志的新会话，会返回 `404 session_log_missing`：此时 `log` 为 `null`，不会读取其他内容。
- 当该页面证明对话为空，且没有已结束或正在进行的回合（Turn）时，`empty` 为 `true`。此时应渲染输入框（Composer）。
- `envelope` 已废弃，始终为 `null`。

当 `useSession` 绑定会话时，它会重新读取日志页。

对于子代理（Sub-agent）的已保存历史记录，请调用 `useSessionSync(childRuntimeSessionId, { kortixSessionScope: sessionId, savedChild: true })`。它会读取会话日志。可通过 `useSessionLogThread(parentSession, childRuntimeSessionId)` 获取对话线程。

#### 返回值

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `phase` | `'starting' \| 'ready' \| 'error'` | 整体状态。当状态为 `ready` 时允许发送消息。当 `stage` 为 `failed` 或 `stopped`，或 `/start` 请求失败时，状态为 `error`。 |
| `stage` | `string \| null` | `/start` 接口的原始阶段：`provisioning`（资源分配中）、`starting`（启动中）、`ready`（就绪）、`stopped`（已停止）或 `failed`（失败）。用于启动屏幕。 |
| `startError` | error 或 `null` | `/start` 的致命失败错误。可将其渲染以替代加载动画（Spinner）。 |
| `failure` | object 或 `null` | 来自 `/start` 的类型化致命资源分配失败对象。 |
| `retry` | `() => void` | 重新轮询 `/start` 接口。用于重试按钮。 |
| `messages` | `{ info, parts }[]` | 会话记录。消息内容（Parts）会实时流式传入。 |
| `savedTranscript` | `'loading' \| 'shown' \| 'none'` | 指示在沙箱唤醒前是否可以显示已保存的历史记录。 |
| `conversationEmpty` | `boolean` | 已保存的副本证明会话没有消息，且此后没有结束的回合，也没有正在进行或排队的回合。 |
| `freshness` | `'idle' \| 'loading' \| 'fresh' \| 'stale' \| 'error'` | 会话记录的读取状态。当没有数据行且状态为 `loading` 或 `error` 时，表示正在等待或发生失败，而非会话为空。 |
| `retryTranscript` | `() => void` | 重新读取会话记录的尾部。 |
| `hasOlder`, `isLoadingOlder`, `loadOlder` | `boolean`, `boolean`, `() => Promise<void>` | 用于向更早的消息进行分页加载。 |
| `status` | `SessionStatus` | 会话的运行时状态。 |
| `working` | `WorkingProjection` | `{ state: 'idle' \| 'working', pendingDelivery?, source, turnId, since, serverOpenTurnToken }`。表示当前正在处理的回复。 |
| `isBusy` | `boolean` | 等同于 `working.state === 'working'`。 |
| `canStop` | `boolean` | 仅当服务器的 `/turn` 响应为 `can_stop: false` 时为 `false`。在共享会话中，只有发起该回合的成员、会话所有者或项目管理员才能停止它。此时不应显示停止按钮。 |
| `presenceAwake` | `{ until: Date, capAt: Date } \| null` | 结合 `browserPresence` 使用：`until` 是最近一次活跃状态更新后沙箱停止的时间，`capAt` 是活跃状态能保持沙箱唤醒的最晚时间。当用户不在场、用户无权启动会话、会话启动报告沙箱未就绪，以及从回合开始到下一次更新响应期间，该值为 `null`。当用户在场时，Hook 会每 5 分钟重新读取一次，同时在回合结束和沙箱就绪时也会重新读取。 |
| `isSending` | `boolean` | 指示 `send` 请求是否正在进行中。 |
| `sendError` | `KortixSendError \| null` | 上一次 `send` 请求的失败信息。新的 `send` 请求会清除该错误。 |
| `questions`, `permissions` | arrays | 待处理的代理提问和工具审批请求。此处的 permission 指单个工具的审批，而非访问控制权限。 |
| `hasPending` | `boolean` | 至少有一个提问或审批请求处于打开状态。 |
| `diffs`, `todos` | arrays | 实时的文件差异（Diffs）和待办事项列表。除非运行时列出了 `session.todo`，否则 `todos` 保持为空。 |
| `rewindMessageId`, `rewindPending`, `rewindError` | `string \| null`, `boolean`, `KortixSendError \| null` | 暂存的回退（Rewind）消息 ID、正在进行的回退或恢复操作，以及上一次的失败信息。只有列出了 `session.rewind` 的运行时才支持回退，pi 不支持。 |
| `models` | `FlatModel[]` | 可选的模型列表。 |
| `agents`, `defaultAgent`, `commands` | arrays, `string \| null`, array | 可选的代理列表、默认代理和斜杠命令。在沙箱启动前即可获取。 |
| `agentName` | `string \| null` | 创建该会话时使用的代理名称，来自第一次 `/start` 的响应。若未绑定则为 `null`。 |
| `picks` | `SessionPicks` | 该会话选择的 `model`、`agent` 和 `variant`，包含 `setModel`、`setAgent` 和 `setVariant` 方法。`send` 方法会使用这些配置。 |
| `runtimeSessionId` | `string \| null` | 运行时的根会话 ID，在解析完成前为 `null`。 |
| `runtimeUrl` | `string \| null` | 会话运行时的代理 URL，在 `stage` 变为 `ready` 之前为 `null`。用于直接调用运行时。 |

#### 操作方法（Actions）

| 方法 | 功能说明 |
| --- | --- |
| `send(text, override?)` | 将提示词放入会话的提示词收件箱。消息会立即显示。`override` 为 `{ model?, agent?, variant? }`，仅对当前消息生效。在 `phase` 变为 `ready` 之前，该方法不执行任何操作。它永远不会抛出异常：失败信息会存入 `sendError`。 |
| `sendParts(parts, override?)` | 发送包含文本和文件的消息片段。`override` 还可接收 `clientMessageId`：若发送失败，使用相同的值重新发送，服务器会确保仅投递一次。在 `ready` 之前调用会抛出“未就绪”错误。 |
| `cancel()` | 停止当前正在运行的回合。它会优先拦截排队的提示词，防止排队的提示词触发下一个回合。在运行时绑定前，会解析返回 `{ status: 'aborted' }`、`{ status: 'timed-out' }`、`{ status: 'failed', error }` 或 `{ status: 'skipped' }`。它永远不会被拒绝（Reject）。 |
| `runCommand(command, args, options?)` | 运行项目的斜杠命令。`args` 为字符串。`options` 为 `{ agent?, model?, variant? }`。在 `ready` 之前调用会直接解析返回且不执行任何操作。受 `session.commands` 限制。 |
| `rewind(messageId)` | 将会话回退到某条用户消息，并恢复文件状态。当会话处于忙碌状态时调用会抛出异常。受 `session.rewind` 限制。 |
| `restoreRewind()` | 在下一个提示词提交回退操作之前，恢复被移除的消息。受 `session.rewind` 限制。 |
| `answerQuestion(id, answers)` | 回答一个打开的提问。`answers` 为 `string[][]` 类型，每个提问对应一个数组。 |
| `rejectQuestion(id)` | 拒绝一个打开的提问。 |
| `answerPermission(id, reply, message?)` | 响应工具审批请求。`reply` 为 `'once'`（仅一次）、`'always'`（始终）或 `'reject'`（拒绝）。 |

这三个回复操作只有在服务器接受回复后，才会移除对应的条目。如果失败，会抛出 `KortixSendError`，且该条目保持打开状态。`answerQuestion`、`rejectQuestion` 和 `answerPermission` 也作为普通函数从 `@kortix/sdk/react` 中导出。请使用 [`useRuntimeSupports`](#基于能力控制控件显隐gate-controls-by-capability) 来隐藏受限制的操作。`removeQuestion` 和 `removePermission` 已废弃：它们不会通知到代理，因此运行状态会一直处于阻塞。

#### 配置选项（Options）

| 选项 | 默认值 | 功能说明 |
| --- | --- | --- |
| `enabled` | `true` | 设为 `false` 会暂停整个 Hook：不请求 `/start`，也不开启流。可用于等待前置条件通过（例如计费检查）。 |
| `waitMs` | `15000` | Hook 发送给 `/start` 的长轮询超时预算（毫秒）。服务器会对其上限进行限制。 |
| `initialRuntimeSessionId` | `null` | 您的服务器已经持有的运行时会话 ID。在 `/start` 运行期间，会话记录会基于此 ID 进行渲染。最终以 `/start` 的响应为准。 |
| `replayStartStash` | `true` | 当会话就绪且为空时，自动发送“新建会话”屏幕中保存的第一条提示词。如果您的宿主（Host）自行处理第一条消息，请设为 `false`。 |
| `chatEngine` | `true` | 当您的应用为该会话挂载了自己的聊天界面时，设为 `false`。此时 `messages`、`diffs` 和 `todos` 为空，`questions` 和 `permissions` 保持实时更新，且 `replayStartStash` 关闭。 |
| `subscribeMessages` | `true` | 设为 `false` 时，仅在会话记录的结构发生变化时才会触发调用方重新渲染，而不会在每次流式传输增量（Delta）时都重新渲染。请在子组件中使用 `useSessionMessages` 来绘制消息行。请参阅 [自行渲染消息](#自行渲染消息)。 |
| `browserPresence` | `false` | 当用户正在使用页面时（过去 10 分钟内有输入），保持当前标签页的活跃状态租约（Presence lease）。该租约用于路由通知并填充 `presenceAwake`。无论页面是否打开，沙箱都会在最后一次回合结束后停止空闲窗口（默认 15 分钟）。 |
| `presenceAlerts` | `false` | 设为 `true` 会告知服务器该标签页会自行显示通知，因此当标签页处于使用状态时，服务器会跳过电话和 Web 推送。仅当标签页的浏览器通知已开启且已获授权时才传入 `true`。需要配合 `browserPresence` 使用。 |
| `presencePageExit` | `false` | 当页面关闭时终止活跃状态租约。若设为 `false`，租约将在 90 秒过期时终止。需要配合 `browserPresence` 使用。 |
| `repositoryMode` | 无 | 针对基于旧版 `/start` 构建的调用方，接受 `'previous'` 值。服务器仅将其作为遥测数据读取，不会改变任何行为。 |

### 发送消息与处理错误

#### KortixSendError

`sendError`、`rewindError` 以及回复操作均使用同一种错误类型 `KortixSendError`：包含 `{ kind, message, cause }`，以及每种 `kind` 对应的一个详情字段。`message` 可直接用于界面显示。

| `kind` | 含义 | 详情字段 |
| --- | --- | --- |
| `billing` | API 以 `402` 状态码拒绝了该回合。 | `billing`：解析后的 `BillingError` 对象。 |
| `connector` | 会话需要一个连接器，但该连接器没有可用的连接。API 在沙箱看到该请求之前就拒绝了回合。 | `connectors`：`{ id, slug, name, authorization_strategy }[]`。`project` 表示修复一个共享连接即可解决；`user` 表示运行该会话的用户必须自行连接。 |
| `runtime-not-ready` | 沙箱仍在启动中。请在 `phase` 变为 `ready` 后重试。 | 无 |
| `runtime-error` | 任何其他失败。 | `gateway`：当 LLM 网关响应时包含：`{ provider?, code?, suggestion?, upstreamStatus?, requestId? }`。 |

`classifySendError(error)` 会将任何抛出的值转换为 `KortixSendError`。请在 `sendParts`、`rewind` 或回复操作的 `catch` 块中使用它。

```tsx
import { classifySendError, type UseSessionResult } from '@kortix/sdk/react';

async function approve(session: UseSessionResult, permissionId: string, report: (message: string) => void) {
  try {
    await session.answerPermission(permissionId, 'once');
  } catch (error) {
    const failure = classifySendError(error);
    if (failure.kind === 'connector') report(`Connect ${failure.connectors?.map((c) => c.name).join(', ')}`);
    else report(failure.message);
  }
}
```

#### useSessionSend

`useSession().send` 适用于发送纯文本的输入框（Composer）。而 `useSessionSend(runtimeSessionId, options?)` 是更底层的发送方法，适用于自行构建消息片段（Parts）的宿主（Host），例如在文件上传步骤之后。它返回 `{ send, stop, isSending, isStopping, sendError }`。

| 选项 | 功能说明 |
| --- | --- |
| `workingSessionId` | OpenChatly 会话 ID。必须传入此参数，因为该 Hook 的第一个参数是运行时会话 ID。发送和停止的收据（Receipts）会归档在此 ID 下。 |
| `projectId` | 项目 ID。调用 `stop()` 时，会在中止操作之前拦截该会话的提示词收件箱。 |
| `classify` | 用于替换 `classifySendError` 函数。 |

`send(parts, options?, callOptions?)` 会解析返回 `{ ok: true }` 或 `{ ok: false, error, cause }`，其中 `error` 为 `KortixSendError` 类型。消息会立即显示。如果发送失败，它会重新读取运行时的消息；如果重新读取失败或返回为空，则会移除该消息。当有先前的停止操作仍在进行中时，`stop()` 会解析返回 `{ status: 'skipped' }`。

### 待处理的提示词与回合结果

`send` 适用于每次只发送一条提示词的输入框。以下 Hooks 增加了队列功能、对正在运行的回合的引导（Steering）控制，以及回合结束的原因说明。它们接收与 `useSession` 相同的 `projectId` 和 `sessionId` 参数。

#### useSessionPrompts

`useSessionPrompts(projectId, sessionId, options?)` 用于读写服务器上的会话提示词收件箱。服务器会按顺序投递待处理的提示词。控制流（Control stream）会推送队列的变更。仅当该流断开时，才会运行轮询机制。`options` 为 `{ enabled?, pollMs? }`。

| 成员 | 功能说明 |
| --- | --- |
| `prompts` | 待处理的行（`SessionPrompt[]`）。每行包含 `prompt_id`、`state`（`queued` 排队中、`delivering` 投递中、`waiting` 等待中、`failed` 失败）、`delivery`、`placement`、`full_text` 和 `last_error`。已投递的提示词会离开此列表。 |
| `enqueue(input)` | 添加一条提示词。它在提示词被存储时解析返回，而不是在被投递时。 |
| `edit(promptId, text)` | 替换处于等待状态（waiting）的行的文本。该行保持原有位置不变。 |
| `remove(promptId)` | 移除处于等待状态的行并返回该行，以便撤销（Undo）操作可以将其重新加入队列。 |
| `interrupt(promptId)` | 将处于等待状态的行转换为 `interrupt`（中断）：当前正在运行的回合会在其正在运行的工具执行完毕后结束，然后执行该行。 |
| `retry(promptId)` | 接下来运行该行。适用于 `failed`（失败）的行。 |
| `hold(held)` | 暂停或释放整个队列。新的发送操作或 `retry` 会释放队列。 |
| `sent`, `isLoading`, `refetch` | 运行时已接受但会话日志中尚未包含的提示词、首次读取的状态，以及手动重新读取的方法。 |

对于已经正在发往运行时的行，`edit`、`remove` 和 `interrupt` 会抛出 `409` 错误。

`enqueue` 接收 `delivery`（`steer` 引导、`queue` 排队或 `interrupt` 中断）以及可选的 `placement`。投递模式请参阅 [Sessions from code > Send prompts（代码中的会话 > 发送提示词）](#发送提示词send-prompts)。`placement` 仅设置待处理行的显示位置：在消息列表中的 `transcript`（会话记录，由 `interrupt` 隐含），或在输入框上方列表中的 `composer`（输入框，由 `steer` 和 `queue` 隐含）。

#### useSessionWorking

`useSessionWorking(projectId, sessionId, options?)` 返回与 `useSession().working` 相同的 `WorkingProjection` 对象，适用于不持有 `useSession` 返回结果的组件。`options` 为 `{ enabled?, runtimeSessionId? }`。请传入 `runtimeSessionId`，以便该 Hook 读取对应运行时的状态事件。当提示词在收件箱中等待时，它会保持 `working` 状态；当该提示词仍在投递过程中时，它会将 `pendingDelivery` 设为 `true`。只要 `state` 为 `'working'`，就应显示停止（Stop）按钮。

#### 回合结束的原因

被中断的回合的会话记录（Transcript）中仅包含一个中止（Abort）错误。API 会记录沙箱（Sandbox）给出的具体原因，例如其内存保护机制（Memory guard）。由用户主动请求的停止操作，永远不会被视为失败。

```tsx
import { turnEndNotice } from '@kortix/sdk';
import { useSessionTurnOutcome } from '@kortix/sdk/react';

function TurnEndLine(props: {
  projectId: string;
  sessionId: string;
  userMessageId: string;
  hasError: boolean;
  isAbort: boolean;
}) {
  const outcome = useSessionTurnOutcome(props.projectId, props.sessionId);
  const notice = turnEndNotice(outcome, props.userMessageId, { hasError: props.hasError, isAbort: props.isAbort });
  if (!notice) return null;
  if (notice.kind === 'sandbox-memory') return <p>The computer ran out of memory ({notice.usedPct ?? '?'}% used).</p>;
  if (notice.kind === 'cause') return <p>{notice.message}</p>;
  return <p>The turn stopped without a recorded cause.</p>;
}
```

- 传入启动该回合的用户消息 ID。
- 当会话记录（Transcript）在该回合上显示错误时，`hasError` 为 `true`。当该错误为中止（Abort）错误时，`isAbort` 为 `true`。
- `turnEndNotice` 返回 `{ kind: 'sandbox-memory', usedPct, detail }`（沙箱内存相关）、`{ kind: 'cause', name, message }`（具体原因）、`{ kind: 'unexplained' }`（未解释）或 `null`。返回 `null` 表示：直接显示会话记录中的内容即可。对于非中止类的会话记录错误，始终返回 `null`。
- `useSessionTurnOutcome` 不会发起任何网络请求。它读取的是 `useSessionWorking` 保持实时更新的 `/turn` 缓存。
- `turnEndCause(outcome, messageId)` 返回原始记录的原因，若没有则返回 `null`。

#### 回合结束通知

当回合结束时，`useSession` 会调用 `createKortix` 中的 `onNotify` 选项，传入 `{ kind: 'task-complete', sessionId, sessionTitle }`（任务完成）或 `{ kind: 'session-error', sessionId, errorTitle, sessionTitle }`（会话错误）。当出现待处理的提问或工具审批时，会触发 `{ kind: 'question', sessionId, questionText, sessionTitle }` 和 `{ kind: 'permission', sessionId, toolName, sessionTitle }`。当 SDK 知道该会话所属的项目时，每个事件还会携带 `projectId`：请务必使用该 ID，而不是您当前的路由信息（因为路由可能已经指向了另一个项目）。仅当用户当前没有查看该会话时，才显示通知。

在视图挂载期间，其事件流会触发上述事件。当视图卸载但回合仍在运行时，`useSession` 会将该回合移交给一个后台监听器（Watch）：

1. 该监听器会每 5 秒请求一次 `GET …/turn`，5 分钟后改为每 15 秒请求一次。12 小时后停止监听。
2. 浏览器会限制隐藏窗口的定时器，因此在隐藏窗口中，回合结束的通知可能会延迟到达。
3. 当没有正在进行的回合时，它会触发 `task-complete`，或带有记录原因的 `session-error`。由用户主动请求的停止操作不会触发任何通知。
4. `task-complete` 还会携带 `watchedSinceMs`，即监听器在宿主（Host）中开始监听时的 `Date.now()` 时间戳。如果宿主在标签页之间转发完成事件，它会跳过在该时间戳之后已经显示过的事件。
5. 该会话的新视图一旦挂载，就会终止后台监听器，从而确保每个回合的结束只被通知一次。

如果宿主没有配置 `onNotify`，则不会启动后台监听器，也不会产生额外的 `/turn` 请求。

### 基于能力控制控件显隐（Gate controls by capability）

`useRuntimeSupports(capability)` 用于判断当前打开的会话的运行时是否支持某项能力。它读取的是运行时最近一次 `/kortix/health` 响应中的 `capabilities` 列表。对于不支持的能力，应直接隐藏对应的控件，而不是让其在调用时抛出 `501` 错误。

```tsx
import { useRuntimeSupports, type UseSessionResult } from '@kortix/sdk/react';

function CommandPicker({ session }: { session: UseSessionResult }) {
  const canRunCommands = useRuntimeSupports('session.commands');
  if (!canRunCommands) return null;
  return (
    <ul>
      {session.commands.map((command) => (
        <li key={command.name}>
          <button onClick={() => void session.runCommand(command.name, '')}>/{command.name}</button>
        </li>
      ))}
    </ul>
  );
}
```

在运行时首次响应之前，以及对于未列出任何 `session.*` 能力的运行时，该 Hook 会返回 `true`。关于能力列表、pi 提供的服务，以及不依赖框架的 `runtimeSupports(caps, name)` 函数，请参阅 [Sessions from code > Gate on runtime capabilities（代码中的会话 > 基于运行时能力进行控制）](#基于运行时能力runtime-capabilities进行门控)。

`useHasSessionDesktop()` 用于判断当前打开的会话所在的计算机是否具有桌面环境（`machine.desktop`）。在运行时首次响应之前，它会返回 `undefined`，这样宿主（Host）就可以选择等待，而不是在拥有桌面环境的计算机上错误地显示“无桌面”。

### 自行渲染消息

建议从 `@kortix/ui/session` 中的 `SessionThread` 组件开始。它可以根据 `useSession` 的返回结果渲染完整的聊天界面：包括会话记录（Transcript）、工具调用、[Generative UI（生成式 UI）](#生成式-uigenerative-ui) 块、待处理的提示词、发送错误以及输入框（Composer）。关于初始化配置、样式、Props 和工具行（Tool-row）的自定义覆盖，请参阅 [OpenChatly UI > Add a session（OpenChatly UI > 添加会话）](#添加会话)。只有当您完全使用自己的组件来绘制每一个部分时，才使用下方的无头（Headless）工具包。

请根据您要绘制的内容选择匹配的层级：

| 您要绘制的内容 | 使用的工具 | 参考文档 |
| --- | --- | --- |
| 扁平的消息列表，每条消息占一行 | `useSessionMessages`、`useChatTurns`、`renderParts` | [分类并渲染消息片段（Classify and render parts）](#分类并渲染消息片段) |
| 工具卡片 | 消息片段 `ToolView` 上的 `toolViewModel` | [读取工具调用（Read a tool call）](#读取工具调用) |
| 包含子代理线程的回合、分组块或完整的工具调用记录 | `useSessionLogThread`、`sessionLogTurns` | [从会话日志渲染块（Render blocks from the session log）](#从会话日志渲染内容块) |

#### 在回合流式传输时保持视图稳定

流式传输的回合大约每 16 毫秒就会更新一次会话记录。请在视图中调用 `useSession(projectId, sessionId, { subscribeMessages: false })`。在会话记录组件中使用 `useSessionMessages(session)` 来读取消息行，并将完整的 `useSession` 结果传入。这样，只有该组件会在每次接收到增量（Delta）时重新渲染。`useSessionMessages(session, { throttleMs })` 最多每 `throttleMs` 毫秒传递一次变更，且最后一次变更必定会送达。

#### 分类并渲染消息片段

`useChatTurns(messages)` 为每条消息返回一个 `TurnView` 对象：`{ message, parts, error?, isEmpty }`。它基于 `messages` 数组进行了记忆化（Memoized）处理。`renderParts(parts, renderers)` 会为每个消息片段的 `kind`（类型）调用对应的渲染器。其类型定义要求必须为每种 `kind` 提供一个渲染器，因此如果出现新的 `kind`，会在构建（Build）阶段报错，而不是在 UI 运行时崩溃。

```tsx
import { toolViewModel } from '@kortix/sdk';
import { renderParts, useChatTurns, useSessionMessages, type UseSessionResult } from '@kortix/sdk/react';

export function Transcript({ session }: { session: UseSessionResult }) {
  const messages = useSessionMessages(session, { throttleMs: 50 });
  const turns = useChatTurns(messages);
  return (
    <ol>
      {turns.map((turn) =>
        turn.isEmpty ? null : (
          <li key={turn.message.info.id} data-role={turn.message.info.role}>
            {renderParts(turn.parts, {
              text: (p) => (p.synthetic ? null : <Markdown key={p.id} text={p.text} />),
              reasoning: (p) => <Thinking key={p.id} text={p.text} />,
              tool: (p) => <ToolCard key={p.id} view={toolViewModel(p.tool)} status={p.tool.status} />,
              file: (p) => <Attachment key={p.id} name={p.filename} url={p.url} isImage={p.isImage} />,
              subtask: (p) => <Subtask key={p.id} description={p.description} agent={p.agent} />,
              retry: (p) => <p key={p.id}>Retry {p.attempt}: {p.message}</p>,
              compaction: (p) => <p key={p.id}>Earlier messages were summarized.</p>,
              patch: () => null,
              snapshot: () => null,
              agent: () => null,
              step: () => null,
              unknown: () => null,
            })}
            {turn.error && <p role="alert">{turn.error.message}</p>}
          </li>
        ),
      )}
    </ol>
  );
}
```

`Markdown`、`Thinking`、`ToolCard`、`Attachment` 和 `Subtask` 是您需要自行实现的组件。

| 片段 `kind`（类型） | 包含字段 |
| --- | --- |
| `text` | `id`, `text`, `synthetic`。`synthetic`（合成）片段是运行时内部使用的：请勿将其渲染为聊天气泡。 |
| `reasoning` | `id`, `text` |
| `tool` | `id`, `tool: ToolView` |
| `file` | `id`, `filename?`, `mime`, `url`, `isImage`, `isPdf` |
| `subtask` | `id`, `description`, `agent`, `prompt`, `model?` |
| `patch` | `id`, `hash`, `files`, `fileCount` |
| `snapshot` | `id`, `snapshot` |
| `agent` | `id`, `name` |
| `retry` | `id`, `attempt`, `message`, `createdAt` |
| `compaction` | `id`, `auto`, `overflow`, `tailStartId?`, `mode?`（`record`：基于记录的重置，不进行任何摘要）, `tokensBefore?`, `entries?` |
| `step` | `id`, `phase: 'start' \| 'finish'`, `snapshot?`, `reason?`, `cost?`, `tokens?` |
| `unknown` | `raw`：当前 SDK 版本不认识的片段类型。分类过程永远不会抛出异常。 |

`@kortix/sdk` 中的 `classifyPart(part)` 和 `classifyTurn(message)` 是 `useChatTurns` 背后的分类函数，适用于 React 之外的代码。`classifyTurn` 返回 `{ parts, error?, isEmpty }`。当消息没有错误且没有可见的片段时，`isEmpty` 为 `true`。

#### 读取工具调用

一个 `tool`（工具）片段包含一个 `ToolView` 对象：`name`（名称）、`kind`（类型）、`title`（标题）、`status`（状态：`pending` 待处理、`running` 运行中、`done` 完成、`error` 错误）、`input`（输入）、`output`（输出）、`error`（错误）、`outputParsed`（解析后的 JSON 输出，适用于最大 256 KiB 的输出）、`outputText`（输出文本）、`files`（文件）、`diff`（差异）、`diagnostics`（诊断信息）、`answers`（回答）、`childSessionId`（子会话 ID）和 `metadata`（元数据）。如果工具在已完成的状态下报告 `success: false`，则其 `status` 为 `'error'`。请读取这些字段，而不是运行时自身的工具状态。

对于工具卡片，请调用 `toolViewModel(view)`。它会根据 `kind` 返回每种工具家族对应的单一数据结构。其中 `generic`（通用）结构涵盖了所有其他工具，且始终可以安全地进行渲染。

```ts
import { classifyTurn, toolViewModel } from '@kortix/sdk';
import type { MessageWithParts } from '@kortix/sdk/react';

declare const message: MessageWithParts;

for (const part of classifyTurn(message).parts) {
  if (part.kind !== 'tool') continue;
  const view = toolViewModel(part.tool);
  if (view.kind === 'shell') console.log(view.command, view.exitCode);
}
```

<Expandable title="工具辅助函数与视图模型结构">

| 函数 | 返回值 |
| --- | --- |
| `toolViewModel(view)` | 单个工具调用的视图模型，其结构如第二个表格所示。 |
| `toolKind(name)` | 根据任意工具名称返回一个 `ToolKind`（工具类型）：`read`（读取）、`list`（列表）、`glob`（通配符匹配）、`grep`（文本搜索）、`write`（写入）、`edit`（编辑）、`apply_patch`（应用补丁）、`bash`、`pty`（伪终端）、`script`（脚本）、`web_search`（网页搜索）、`webfetch`（网页抓取）、`media`（媒体）、`show`（展示）、`task`（任务）、`delegate`（委派）、`workflow`（工作流）、`platform`（平台）、`sessions`（会话）、`todowrite`（待办事项写入）、`question`（提问）、`memory`（记忆）、`connectors`（连接器）、`automations`（自动化）、`projects`（项目）、`skill`（技能）、`context`（上下文）、`retired`（已弃用）或 `other`（其他）。 |
| `toolInfo(name)` | 返回 `{ label, category }`。`category`（分类）为 `shell`（命令行）、`files`（文件）、`search`（搜索）、`edit`（编辑）、`web`（网络）、`task`（任务）或 `other`（其他）。 |
| `getToolInfo(name, input?)` | 返回用于工具卡片的 `{ icon, title, subtitle }`。对于未知的工具，其 `title` 将直接使用原始名称。 |
| `humanizeToolName(name)` | 为没有已知标签的工具名称生成一个可读的标签。`toolInfo` 会将其作为后备方案。 |
| `toToolView(call)` | 从单个 v1 版本的工具片段或会话日志中的 `ToolCallBlock` 生成一个 `ToolView`。 |
| `getPermissionForTool(permissions, callId)`, `getQuestionForTool(questions, callId)` | 获取属于某个工具调用的、处于打开状态的工具审批请求或提问。 |
| `inputPath(input)` | 获取文件工具的路径，依次从 `filePath`、`file_path` 或 `path` 中读取。 |

`toolViewModel` 的结构：

| `kind`（类型） | 包含字段 |
| --- | --- |
| `web-search` | `query`（查询词）, `results?`（结果）, `answer?`（回答）, `error?`（错误） |
| `shell` | `command`（命令）, `stdout?`（标准输出）, `exitCode?`（退出码） |
| `file-read` · `file-write` | `path`（路径）, `preview?`（预览） |
| `file-edit` | `path`（路径）, `diff?`（差异）：包含 `{ type: 'added' \| 'removed' \| 'unchanged', text }` 的行数组 |
| `search` | `pattern`（模式）, `matches?`（匹配项） |
| `task` | `description`（描述）, `agent?`（代理）, `name?`（名称）, `sessionId?`（会话 ID）, `background?`（是否后台）, `teammate?`（协作者）, `started?`（是否已开始）, `model?`（模型）, `resultExcerpt?`（结果摘要） |
| `todo` | `items`（事项列表） |
| `question` | `questions`（问题列表）, `answers?`（回答） |
| `generic` | `label`（标签）, `inputPretty?`（格式化输入）, `outputPretty?`（格式化输出）。适用于所有其他工具。 |

</Expandable>

#### 从会话日志渲染内容块

会话日志（`kortix.session/2`）是会话的运行时中立记录：包含线程、按 `seq`（序号）排列的消息以及类型化的内容块。当您需要渲染子代理线程、回合分组或完整的工具调用记录时，请从会话日志进行渲染。`useSession` 会加载日志。除了子代理线程的第一页外，这些 Hooks 不会自行发起任何请求。

| Hook | 返回值 |
| --- | --- |
| `useSessionLogThread(session, threadId?, { throttleMs?, prompts? })` | 返回一个 `SessionLogThread`：根线程，或 `threadId` 指定的子代理线程。在收到第一条消息之前为 `null`。将 `useSessionPrompts` 的结果作为 `prompts` 传入，可以在根线程中将待处理的提示词显示为临时消息。 |
| `useSessionLogOlder(session, threadId?)` | 针对单个线程返回 `{ hasOlder, isLoadingOlder, loadOlder }`。对于根线程，使用 `useSession().loadOlder` 效果相同。 |
| `useSessionLog(session)` | 返回完整的 `SessionLog`。每当有新消息时都会发生变化。 |
| `useSessionLogRecord(session)` | 返回不包含线程的会话字段，例如 `restore_grade`、`grade_counts`、`harness` 和 `ext`。在日志加载完成前为 `null`。它不会因消息更新而发生变化。 |

`@kortix/sdk` 中的 `sessionLogTurns(thread, options?)` 会将一个线程按用户消息分组，每个用户消息对应一个 `SessionLogTurn`：包含 `id`、`user`（用户）、`assistant`（助手）、`blocks`（内容块）、`status`（状态）、`error`（错误）、`response`（最后一个文本块）、`live`（实时）、`queued`（排队中）和 `retrying`（重试中）等字段。请传入 `busy` 状态，以便正在运行的回合保持实时（live）状态。

```tsx
import { sessionLogCallStatus, sessionLogOpenCall, sessionLogTurns, toolCallStatus } from '@kortix/sdk';
import { useSessionLogThread, type UseSessionResult } from '@kortix/sdk/react';

export function BlockTranscript({ session }: { session: UseSessionResult }) {
  const thread = useSessionLogThread(session, undefined, { throttleMs: 50 });
  if (!thread) return null;
  const turns = sessionLogTurns(thread, { busy: session.isBusy });
  return (
    <ol>
      {turns.map((turn) => (
        <li key={turn.id}>
          {turn.blocks.map((block) => {
            if (block.type === 'text') return <p key={block.id}>{block.text}</p>;
            if (block.type !== 'tool_call') return null;
            const call = sessionLogOpenCall(block);
            return (
              <p key={block.id}>
                {call.name}: {sessionLogCallStatus(block, turn.live)} ({toolCallStatus(call)})
              </p>
            );
          })}
        </li>
      ))}
    </ol>
  );
}
```

<Expandable title="工具调用内容块辅助函数">

| 函数 | 功能说明 |
| --- | --- |
| `toolCallStatus(call)` | 返回 `pending`（待处理）、`running`（运行中）、`completed`（已完成）或 `error`（错误）。 |
| `sessionLogCallStatus(call, live)` | 返回用于渲染的状态：`pending`、`running`、`complete`、`error` 或 `interrupted`（已中断）。如果回合未处于实时（live）状态，但存在未关闭的调用，则状态为 `interrupted`。 |
| `sessionLogOpenCall(call)` | 当运行时关闭了调用但未返回结果时，返回该调用的开放状态（Open shape）。请通过此函数来渲染调用，以确保实时回合中每个调用的绘制方式保持一致。 |
| `toolCallRawOutput(call)` | 返回已完成调用的输出文本。对于其他状态的调用返回空字符串 `''`。 |
| `toolCallError(call)` | 返回失败调用的错误文本。对于未失败的调用返回 `undefined`。 |
| `subAgentCalls(thread)` | 按顺序返回子代理行（Sub-agent row）中列出的工具调用。 |
| `toolCallBlock(part)` | 从 `useSessionMessages` 返回的工具片段（Tool part）中提取 `ToolCallBlock`。 |

</Expandable>

待处理的权限审批或提问通过 `call.call_id` 与调用进行匹配：`getPermissionForTool(permissions, call.call_id)`。关于基于内容块的片段、突发步骤、成本、恢复和全文等辅助函数（如 `sessionLogTurnSegments`、`sessionLogBurstSteps`、`sessionLogThreadMetrics` 等），请参阅 [SDK reference > Session log helpers（SDK 参考 > 会话日志辅助函数）](#会话日志辅助工具session-log-helpers)。

#### 下一步：富文本内容块（Rich blocks）

代理的回复中可以包含 `openui` 内容块：即在文本片段中嵌入卡片、对比图、图表、表格、地图和其他组件。`SessionThread` 会自动渲染它们。如果您使用自定义渲染器，可以通过 `@kortix/sdk/genui/react` 来查找并渲染它们；或者使用 `@kortix/sdk/genui` 中的 `genuiToMarkdown` 将它们转换为纯 Markdown 格式。请参阅 [Generative UI（生成式 UI）](#生成式-uigenerative-ui)。

### 快速打开与离线支持

#### 提前启动打开读取

`prefetchSessionOpen(queryClient, projectId, sessionId)` 会在会话视图挂载之前，提前启动该视图所需的读取操作。它会发送一个 `GET …/snapshot?transcript=0` 请求，用于获取会话行（Session row）、当前回合和提示词队列。随后，`useSession` 将直接使用该请求的结果，而不再自行发起请求。

```tsx
import { prefetchSessionOpen } from '@kortix/sdk/react';
import { useQueryClient } from '@tanstack/react-query';
import type { ReactNode } from 'react';

export function SessionLink(props: { projectId: string; sessionId: string; children: ReactNode }) {
  const queryClient = useQueryClient();
  const warm = () => void prefetchSessionOpen(queryClient, props.projectId, props.sessionId);
  return (
    <a href={`/sessions/${props.sessionId}`} onPointerEnter={warm} onFocus={warm} onTouchStart={warm}>
      {props.children}
    </a>
  );
}
```

- 在会话链接（Session link）发生悬停（Hover）、聚焦（Focus）或触摸时，或者当路由指向某个会话时，调用此方法。
- 它永远不会调用 `/start` 接口，因此绝不会唤醒沙箱（Sandbox）。
- 它永远不会被拒绝（Reject）。
- 如果在 30 秒内对同一个会话进行第二次调用，不会发送任何请求。

#### 在页面重新加载时从设备端进行渲染

两种设备端存储（Device stores）用于保存用户已经查看过的内容，以便在页面重新加载或冷启动时，能够在第一帧就将其绘制出来。随后，服务器的响应会就地刷新这些数据。这两种存储都是按用户隔离的，且都有容量上限。它们均从 `@kortix/sdk` 中导出。

| 存储 | 保存内容 | 默认容量限制 |
| --- | --- | --- |
| `createPersistedQueryCache({ storage, userId, shouldPersist })` | 被 `shouldPersist` 接受的 React Query 结果。`isPersistableQueryKey` 接受账户、项目、项目详情、会话列表和会话行。恢复的条目在首次被读取时会重新获取（Refetch）最新数据。 | 1,000,000 个字符，保留 7 天 |
| `createSavedCopyStore({ storage, userId })`，通过 `setSavedCopyStore` 注册 | 服务器发送的已保存的会话副本。`useSession` 会在服务器响应之前，先绘制保留的副本。 | 最多 12 个会话，总计 1,500,000 个字符，每个副本最多 300,000 个字符，保留 14 天 |

```ts
import type { QueryClient } from '@tanstack/react-query';
import {
  browserKeyValueStorage,
  createPersistedQueryCache,
  createSavedCopyStore,
  isPersistableQueryKey,
  setSavedCopyStore,
} from '@kortix/sdk';

export function adoptDeviceCaches(queryClient: QueryClient, userId: string) {
  const storage = browserKeyValueStorage(); // null where localStorage is blocked or absent
  if (!storage) return null;
  const cache = createPersistedQueryCache({ storage, userId, shouldPersist: isPersistableQueryKey });
  cache.restore(queryClient); // synchronous with localStorage
  const stop = cache.persist(queryClient);
  window.addEventListener('pagehide', () => void cache.flush());
  const copies = createSavedCopyStore({ storage, userId });
  setSavedCopyStore(copies);
  return { cache, copies, stop };
}

export type DeviceCaches = ReturnType<typeof adoptDeviceCaches>;
```

- `persist`（持久化）操作每秒最多写入一次。请在 `pagehide`（页面隐藏）事件中调用 `flush()`，以确保在页面重新加载时保留最后一次变更。
- 在 React Native 环境中，请将 `AsyncStorage` 作为 `storage` 传入。此时 `restore`（恢复）方法将返回一个 Promise。
- 已保存副本存储（Saved-copy store）仅保留服务器发送的副本，绝不保留实时的会话记录（Live transcript）。已停止的回合不会作为正在运行的回合恢复。
- 当存储已满、损坏或丢失时，永远不会抛出异常。此时应用将直接从服务器加载数据。
- `isPersistableQueryKey` 永远不会保留权限探测（Permission probe，即 `useCan`）的结果。

### 退出登录与身份变更

SDK 会在内存中保存每个用户的会话状态：包括会话记录（Transcripts）、待处理的提问和工具审批、回合收据（Turn receipts）、打开会话的预取数据以及模型选择（Model picks）。请在每次身份变更时清除这些状态：包括退出登录、不同用户登录，以及在另一个标签页中登录导致用户变更（且未触发页面加载）的情况。

```ts
import type { QueryClient } from '@tanstack/react-query';
import { setSavedCopyStore } from '@kortix/sdk';
import { resetIdentityState } from '@kortix/sdk/react';
import type { DeviceCaches } from './device-caches';

export async function onIdentityChange(queryClient: QueryClient, device: DeviceCaches) {
  setSavedCopyStore(null);
  device?.stop();
  queryClient.clear();
  resetIdentityState();
  await device?.cache.clear();
  await device?.copies.clear();
}
```

`resetIdentityState()` 永远不会抛出异常。它还会从 `localStorage` 中移除模型选择（Model picks）记录。但它**不会**清除 React Query 缓存、您自己的存储，或您传给 `createKortix` 的 Token 来源（Token source）。请在同一个处理函数（Handler）中手动重置这些内容。虽然设备端存储不会为其他用户恢复数据，但已退出登录的设备绝不应保留这些数据。

## 生成式 UI（Generative UI）

`SessionThread` 无需额外代码即可渲染生成式 UI 内容块，而 `UnifiedMarkdown` 在传入 `genui` 配置时也能渲染它们。这两者均属于 [OpenChatly UI](#ui-组件kortixui) 的一部分。本节内容专为需要自行渲染内容块的宿主（Host）提供，例如：自定义 Web 渲染器、原生应用，或纯文本渠道（如 CLI、电子邮件或聊天机器人）。

### 什么是内容块（Block）

代理（Agent）默认使用 Markdown 格式进行回复。当它需要展示结构化内容时，会添加一个带有 `openui` 语言标签的围栏代码块（Fenced block）：例如带优先级的推荐列表、对比表、基于工具数据的图表、地图上的位置等。而对于简短的回答、解释说明和代码，则继续保持纯文本（Prose）格式。

````markdown
有两个选项符合需求。

```openui
root = Compare([acme, northwind], ["Price", "Seats"], "Acme")
acme = CompareItem("Acme", ["120", "40"])
northwind = CompareItem("Northwind", ["95", "25"])
```
````

SDK 会以两种数据结构读取回复：

| 类型 | 数据结构 | 用途 |
| --- | --- | --- |
| `GenuiSegment` | `{ kind: 'markdown', text }` 或 `{ kind: 'genui', code, version, closed }` | 按顺序排列的回复片段。`closed: false` 表示在流式传输过程中，该块尚未结束（即最后一个块）。 |
| `GenuiNode` | `{ id, type, props, partial }` | 一个经过验证的组件实例。`id` 是稳定的 React Key。`type` 是目录（Catalog）中的名称，例如 `BarChart`。`partial: true` 表示模型尚未完成该语句的生成。 |

内容块（Block）仅包含数据。SDK 负责解析它，根据目录（Catalog）进行验证，并为您提供一棵由 `GenuiNode` 组成的树。您需要将每个 `type` 映射到对应的 UI 组件。

围栏标签 `openui` 和 `openui-lang` 代表 Schema 版本 1。标签 `openui-v<N>` 指定版本号为 `N`。任何其他标签都将被视为普通的代码块。

### 启用生成式 UI

生成式 UI 没有项目级别的标志（Project flag），也没有全局的强制关闭开关（Kill switch）。每个会话都会按名称列出 `kortix-genui` 系统技能（System skill）及其单行描述。只有当回复需要内容块时，代理才会加载完整的目录（Catalog），因此不包含内容块的回合不会触发加载。

只有当代理在 `kortix.yaml` 中的 `skills` 授权配置为 `all` 或明确包含 `kortix-genui` 时，它才能看到该技能。初始代理（Starter agents）默认授权为 `all`。请参阅 [kortix.yaml 参考文档](#kortixyaml-参考)。

查看器（Viewer）端有独立的开关。向 `GenuiBlock` 传入 `enabled={false}`，该内容块就会退化为 Markdown 格式渲染。

### 安装对等依赖（Peers）

`@kortix/sdk/genui` 和 `@kortix/sdk/genui/react` 需要两个可选的对等依赖（Peer dependencies）。如果缺少这些依赖，导入操作将会失败。

```bash
npm i zod @openuidev/lang-core@0.3.1
```

`@kortix/sdk/genui/react` 还需要 `react` 18 或更高版本。`@openuidev/lang-core` 会在安装时发送一次匿名（Pseudonymous）的 PostHog 遥测事件。设置环境变量 `OPENUI_TELEMETRY_DISABLED=1` 或 `DO_NOT_TRACK=1` 即可关闭该功能。

| 入口模块 | 包含内容 | 是否加载对等依赖 |
| --- | --- | --- |
| `@kortix/sdk/genui/fence` | 围栏（Fence）检测工具：`splitGenui`、`separateGenuiClosers`、`genuiVersionOf`、`genuiVersionFromClassName` | 否 |
| `@kortix/sdk/genui` | 解析器、文本转换、提示词（Prompt）、`safeUrl`、版本常量以及上述围栏函数 | 是 |
| `@kortix/sdk/genui/react` | `GenuiBlock`、`useGenuiParse`、`defaultGenuiComponents` | 是 |

根入口 `@kortix/sdk` 和 `@kortix/sdk/react` 永远不会加载这些对等依赖。

### 在不使用解析器的情况下检测内容块

`@kortix/sdk/genui/fence` 模块永远不会导入 `zod` 或 `@openuidev/*`。请将其放入您的主包（Main bundle）中。当回复中包含内容块时，再懒加载（Lazily load）渲染器。

| 函数 | 返回值 |
| --- | --- |
| `splitGenui(text)` | `GenuiSegment[]`：按顺序返回 Markdown 和内容块片段。仅识别顶层围栏。位于引用块（Blockquote）或列表项内部的围栏仍被视为 Markdown。嵌套在其他围栏内部的 `openui` 标签也仍被视为 Markdown。 |
| `separateGenuiClosers(text)` | 返回处理后的文本，将模型粘连在最后一行语句上的围栏闭合标记移至单独的一行。请在调用任何 Markdown 解析器或 `splitGenui` 之前运行此函数。如果文本无需修改，则返回原始字符串。 |
| `genuiVersionOf(tag)` | 返回该围栏标签对应的 Schema 版本；如果该围栏不属于生成式 UI，则返回 `null`。 |
| `genuiVersionFromClassName(className)` | 功能同上，但针对的是 Markdown 渲染器生成的 `language-…` 类名。 |

```ts
import { separateGenuiClosers, splitGenui } from '@kortix/sdk/genui/fence';

const hasBlock = splitGenui(separateGenuiClosers(text)).some((segment) => segment.kind === 'genui');
```

### 在 React 中渲染内容块

`GenuiBlock` 用于渲染单个内容块。它永远不会抛出异常，也永远不会显示内容块的源代码。以下示例将回复拆分为多个片段（Segments），并逐一进行渲染。这里使用 `react-markdown` 来渲染纯文本部分；实际上，任何 Markdown 渲染器都可以胜任。

```tsx
import Markdown from 'react-markdown';
import { separateGenuiClosers, splitGenui } from '@kortix/sdk/genui/fence';
import { defaultGenuiComponents, GenuiBlock } from '@kortix/sdk/genui/react';

// A module constant: GenuiBlock needs a stable renderMarkdown.
const renderMarkdown = (markdown: string) => <Markdown>{markdown}</Markdown>;

export function AssistantText({ text, streaming }: { text: string; streaming: boolean }) {
  const segments = splitGenui(separateGenuiClosers(text));
  return (
    <>
      {segments.map((segment, index) =>
        segment.kind === 'markdown' ? (
          <Markdown key={index}>{segment.text}</Markdown>
        ) : (
          <GenuiBlock
            key={index}
            code={segment.code}
            version={segment.version}
            streaming={streaming && !segment.closed}
            components={defaultGenuiComponents}
            renderMarkdown={renderMarkdown}
          />
        ),
      )}
    </>
  );
}
```

如果您希望在 Markdown 渲染器的 `code` 重写（Override）中渲染内容块，请使用 `genuiVersionFromClassName(className)` 来读取版本号。返回 `null` 表示这是一个普通的代码块。请仅对围栏（Fence）仍处于打开状态的块传入 `streaming: true`。

#### `GenuiBlock` 属性（Props）

| 属性 | 是否必填 | 含义 |
| --- | --- | --- |
| `code` | 是 | 截至目前围栏内的代码体内容。 |
| `streaming` | 是 | 当该块的围栏处于打开状态时为 `true`。当围栏关闭时请传入 `false`，以便在回复继续时让该块完成渲染并稳定下来。 |
| `components` | 是 | 一个 `GenuiComponentMap` 对象：将块名称映射到您的组件。如果找不到对应名称，该节点将作为 Markdown 渲染。 |
| `renderMarkdown` | 是 | `(markdown: string) => ReactNode`，用于降级渲染（Fallback）。请传入一个稳定的函数（模块常量或 `useCallback` 包裹的函数）。传入新函数会导致该块的 Markdown 部分和节点视图重新渲染。 |
| `version` | 否 | 从围栏标签中获取的 Schema 版本。默认值：`GENUI_SCHEMA_VERSION`。如果当前构建版本不支持该版本，将显示 `GENUI_UNSUPPORTED_NOTE`。 |
| `enabled` | 否 | 默认为 `true`。设为 `false` 会将该块作为 Markdown 渲染（查看器设置）。 |
| `renderPending` | 否 | `(node: GenuiNode) => ReactNode`，用于渲染模型尚未生成完毕的节点。默认不渲染任何内容。建议为图表或表格返回一个固定高度的占位框，以防止布局发生跳动。 |
| `onSettled` | 否 | 每个块停止流式传输时触发一次，并携带一个 `GenuiBlockEvent` 对象：包含 `outcome`（结果状态：`rendered` 已渲染、`fallback` 已降级、`parse_error` 解析错误、`render_error` 渲染错误、`unsupported` 不支持）、`components`（排序后的组件名称）、`msToFirstPaint`（首次绘制耗时）和 `issueCount`（问题数量）。该事件不包含任何内容数据。 |

如果一个已稳定（Settled）的块没有有效的根节点，将渲染一行提示：如果流在语句中间结束，显示 `GENUI_CUT_OFF_NOTE`；否则显示 `This content could not be displayed.`（无法显示此内容）。如果某个组件抛出异常，该块将降级为 Markdown 渲染。如果在块处于流式传输期间发生抛出异常，当块稳定下来时还会再尝试渲染一次。

#### 组件（Components）

`defaultGenuiComponents` 包含了所有 19 种块的无品牌（Unbranded）默认组件。它们渲染语义化 HTML，并通过 CSS 变量进行主题化：`--genui-fg`、`--genui-muted`、`--genui-border`、`--genui-surface`、`--genui-accent`、`--genui-radius`。图表和地图默认会渲染为数据表格和位置列表。如果宿主希望渲染绘制的图表，需要为这些名称传入自定义组件。

每个组件都会接收 `GenuiComponentProps`：

| 字段 | 含义 |
| --- | --- |
| `node` | `GenuiNode` 节点对象。 |
| `props` | 经过验证的属性（Props）。子插槽（Child slots）包含 `GenuiNode[]`。 |
| `renderChild` | `(node: GenuiNode) => ReactNode`。通过相同的组件映射表渲染子节点。 |
| `streaming` | 指示该块是否仍在流式传输中。 |

您可以替换某个名称的组件，同时保留其他名称的默认组件：

```tsx
import type { GenuiNode } from '@kortix/sdk/genui';
import { defaultGenuiComponents, type GenuiComponentMap, type GenuiComponentProps } from '@kortix/sdk/genui/react';

function Callout({ props }: GenuiComponentProps) {
  return (
    <aside data-tone={props.tone}>
      {props.title ? <strong>{props.title}</strong> : null}
      <p>{props.body}</p>
    </aside>
  );
}

function Stack({ props, renderChild }: GenuiComponentProps) {
  const children = props.children as GenuiNode[];
  return <div style={{ display: 'flex', flexDirection: props.direction === 'row' ? 'row' : 'column', gap: 12 }}>{children.map(renderChild)}</div>;
}

export const components: GenuiComponentMap = { ...defaultGenuiComponents, Callout, Stack };
```

请在模块级别（Module level）仅定义一次组件映射表。对于 React Native 宿主，请传入原生组件的映射表，以及一个返回原生节点的 `renderMarkdown` 函数。`GenuiBlock` 内部不使用任何 DOM API。

`useGenuiParse(code, version, streaming)` 返回 `GenuiBlock` 用于渲染的 `GenuiParseResult`。您可以使用它来构建自定义的块外壳（Block shell）。该 Hook 会为每个块保留一个解析器实例。

### 解析与流式传输

`@kortix/sdk/genui` 可以在不依赖 React 的情况下进行解析。

| 函数 | 返回值 |
| --- | --- |
| `parseGenui(code, version?)` | 针对已完成块的 `GenuiParseResult`。 |
| `createGenuiParser(version?)` | 一个 `GenuiParser` 实例。`update(code, streaming)` 接收迄今为止完整的块文本，但仅解析新增的文本。相同的输入会返回相同的结果对象。未发生变化的节点在多次调用之间会保持其引用标识（Identity）不变。 |

`GenuiParseResult` 包含 `root`（根 `Stack` 节点，或 `null`）、`pending`（已引用但尚未写入的语句名称）、`issues`（问题列表）和 `streaming`（是否正在流式传输）。

`issues` 列出了被解析器丢弃或修复的所有问题。它仅用于日志记录和调试，**绝不**应展示给用户。一个结果对象最多保留 50 个问题；当达到上限时，会追加一个 `cut-off`（截断）问题。每个 `GenuiIssue` 都包含 `code`（错误码）、`message`（消息），以及（在已知情况下）`component`（组件名）和 `statementId`（语句 ID）。

| `GenuiIssueCode`（错误码） | 含义 |
| --- | --- |
| `schema` | 节点违反了字段限制。该节点被丢弃，其有效的子节点会移至父级插槽中。 |
| `unknown-component` | 该名称不在当前构建版本的目录（Catalog）中。 |
| `wrong-child` | 该插槽不接受此组件。 |
| `url` | 存在不安全的链接或图片 URL。 |
| `depth` | 容器嵌套深度超过 4 层。 |
| `too-many-nodes` | 该块展开后的节点数超过 500 个。 |
| `too-large` | 该块的源代码长度超过 65,536 个字符。不会被解析。 |
| `version` | 围栏标签指定的 Schema 版本在当前构建版本中不支持渲染。 |
| `no-root` | 已稳定的块没有有效的根节点。 |
| `cut-off` | 流在某个语句中间结束。 |
| `unsupported-statement` | 包含 `Query`、`Mutation` 或 `$state` 语句。会被忽略且永远不会执行。 |
| `parse-failed` | 解析器在该输入上失败。不会渲染任何内容。 |

如果某个节点解析失败，该节点会被丢弃，但其同级节点（Siblings）仍会正常渲染。

### 在纯文本宿主中渲染

对于无法渲染 UI 的宿主，可以将内容块转换为 Markdown 格式。输出结果是确定性的，且永远不会包含块的源代码。

| 函数 | 转换对象 |
| --- | --- |
| `genuiToMarkdown(text, { streaming? })` | 转换整个回复。位于引用块和列表项内部的内容块也会被转换。不包含内容块的文本会原样返回。 |
| `genuiBlockToMarkdown(code, version?, { streaming? })` | 转换单个块体（Block body）。 |
| `genuiToMarkdown(node)` | 转换单个 `GenuiNode` 及其子节点。对于未知或尚未完成的节点，返回空字符串 `''`。 |
| `genuiA11yText(node)` | 为图表或地图节点生成供屏幕阅读器使用的无障碍文本，其他情况返回 `null`。 |

图表会被转换为带有 `Source:`（来源）行的表格。地图会被转换为位置列表。标签页（Tabs）和手风琴（Accordions）会被展开。步骤（Steps）会被转换为有序列表。检查清单（Checklist）会被转换为任务列表（`- [ ]`）。对于仍在流式传输中的回复，请传入 `{ streaming: true }`：此时未完成的最后一个块不会附带截断提示（Cut-off note）。

```ts
import { genuiToMarkdown } from '@kortix/sdk/genui';

const markdown = genuiToMarkdown(replyText);
```

OpenChatly CLI 会以这种方式打印会话回复。请将输出视为不受信任的 Markdown，并通过与纯文本相同的过滤程序（Sanitizer）进行渲染。如需获取会话的回复文本，请参阅 [Sessions from code（通过代码获取会话）](#从代码管理会话)。

### 让其他模型学习该格式

| 名称 | 值 |
| --- | --- |
| `buildGenuiPrompt()` | 以字符串形式返回 `kortix-genui` 技能的主体内容：包括语法、组件签名、规则和示例。可作为系统提示词（System prompt）提供给 OpenChatly 之外的模型。 |
| `GENUI_PROMPT_VERSION` | 该提示词的 8 位十六进制哈希值。请将其与评估结果一起存储，以便在提示词发生变更时能够察觉。 |
| `GENUI_SCHEMA_VERSION` | `1`。当前构建版本支持渲染的 Schema 版本。 |

### 内容块（Blocks）

目录（Catalog）包含 19 种顶级内容块。子节点仅能出现在其父节点内部。

| 内容块 | 包含内容 | 限制 |
| --- | --- | --- |
| `Stack` | 块的布局；`direction` 为 `col`（列）或 `row`（行）；`layout` 为 `list`（列表）或 `grid`（网格）。解析器会将每个根节点包裹在一个 `Stack` 中。 | 1–12 个子节点 |
| `Card` | 包含图片、文本、徽章和评分的单个选项 | 最多 4 个 `Badge`；评分 0–5 |
| `Stat` | 带有趋势的单个关键数字 | |
| `StatRow` | 一行排列的关键数字 | 2–4 个 `Stat` |
| `Table` | 供快速浏览的行数据 | 1–8 列，最多 50 行，单元格最多 200 个字符 |
| `Compare` | 并排对比的选项；`winner` 指定胜出项 | 2–4 个 `CompareItem`，最多 12 项规格 |
| `RankedList` | 按优先级排序的推荐列表，最佳项在前 | 1–10 个 `RankedItem` |
| `BarChart` | 跨类别的数值 | 1–24 个类别，1–4 个 `Series` |
| `LineChart` | 随时间变化的趋势 | 2–365 个 X 轴标签，1–4 个 `Series` |
| `PieChart` | 整体的份额占比 | 2–6 个 `Slice` |
| `Map` | 地点及可选的路线 | 1–25 个 `Marker`，缩放级别 1–18，路线最多 500 个点 |
| `Steps` | 按顺序排列的流程或旅程 | 1–12 个 `Step` |
| `Checklist` | 供读者勾选的事项 | 1–20 个事项，每项最多 120 个字符 |
| `Tabs` | 供用户切换的视图 | 2–5 个 `Tab`，每个包含 1–8 个块 |
| `Accordion` | 读者可选择跳过的章节 | 1–10 个 `AccordionItem`，每个包含 1–8 个块 |
| `Badge` | 状态标签；色调（Tone）为 `neutral`（中性）、`good`（良好）、`warn`（警告）、`bad`（糟糕） | 标签最多 24 个字符 |
| `Callout` | 要点或警告；色调为 `info`（信息）、`warn`（警告）、`success`（成功） | 正文最多 400 个字符 |
| `Image` | 带有可选标题和文本的图片 | |
| `Link` | 指向来源或文档的链接 | 标签最多 80 个字符 |

子节点包括：`Tab`、`AccordionItem`、`CompareItem`、`RankedItem`、`Series`（最多 365 个值）、`Slice`、`Marker`、`Step`。

所有内容块的通用限制：

- 容器嵌套：最多 4 层。
- 引用展开后每个块的节点数：最多 500 个。
- 块源代码长度：最多 65,536 个字符。
- URL 长度：最多 2,048 个字符。

较旧的 SDK 无法识别后续新增的内容块。它会以 `unknown-component` 错误丢弃该节点。请更新 `@kortix/sdk` 以渲染新的内容块。

### 安全机制

- 内容块仅包含数据，绝不包含代码。`Query`、`Mutation` 和 `$state` 语句永远不会被执行。
- 内容块无法调用工具或更改状态。Checklist 的勾选状态仅保存在组件内部，不会被存储或发送。
- 每个链接和图片 URL 都会经过 `safeUrl(raw)` 处理。它会返回一个标准化的绝对 `http` 或 `https` URL，或返回 `null`。它会拒绝包含凭据的 URL 以及长度超过 2,048 个字符的 URL。请在您自己的组件中，对所有渲染的 URL 使用此函数。
- `GENUI_CUT_OFF_NOTE` 的值为 `'Response was cut off.'`。当流在某个语句中间结束时，它会显示在已稳定（Settled）的内容块下方。
- `GENUI_UNSUPPORTED_NOTE` 的值为 `'This content needs a newer version of OpenChatly.'`。当内容块的 Schema 版本在当前构建版本中不支持渲染时，它会替代该块显示。

## UI 组件（@kortix/ui）

`@kortix/ui` 是 OpenChatly Web 应用的 React 组件库。它构建于 [`@kortix/sdk/react`](#react) 和 `@kortix/sdk/genui/react` 之上。它以模块的形式提供基础组件（按钮、表单、覆盖层）以及完整的会话体验：包括会话工作区、线程、编辑器、文件、终端、项目主页和会话列表。OpenChatly Apps、白标（White-label）宿主和您自己的应用都渲染相同的组件。

这些组件会读取您在 [Create the client（创建客户端）](#创建客户端) 中创建的单一客户端实例。`@kortix/ui` 不会添加第二个客户端，也不需要额外的配置。组件采用 Tailwind CSS v4 的类名字符串，并读取 CSS 变量。您只需通过 Token 重新设置主题，**绝不**需要通过复制组件来进行定制。

### 安装与对等依赖

```bash
npm i @kortix/ui @kortix/sdk @tanstack/react-query @openuidev/lang-core@0.3.1 zod @phosphor-icons/react@2.1.10 react@19 react-dom@19
```

请安装与 `@kortix/sdk` 相同发布版本的 `@kortix/ui`。版本规则请参阅 [Versions and stability（版本与稳定性）](#版本与稳定性)。模块入口（如 `@kortix/ui/session`、`/workspace`、`/theme` 及 [Modules（模块）](#模块modules) 中列出的其他入口）从 0.14.4 版本开始提供；0.14.3 版本仅包含根入口、组件子路径和样式表。如果在 OpenChatly Monorepo 内部使用，请在您的包依赖中添加 `"@kortix/ui": "workspace:*"`。

| 对等依赖（Peer） | 适用场景 |
| --- | --- |
| `react` >= 19, `react-dom` >= 19 | 所有入口。 |
| `@kortix/sdk`, `@tanstack/react-query` 5 | `@kortix/ui/session`、`@kortix/ui/workspace` 以及其他所有渲染项目或会话数据的入口。需要挂载一个 `QueryClientProvider`（[Set up（配置）](#初始配置set-up)）。 |
| `@openuidev/lang-core@0.3.1`, `zod` | 会话线程（Session thread），因为它需要渲染 [Generative UI（生成式 UI）](#生成式-uigenerative-ui) 内容块。这两者都是 `@kortix/sdk` 的可选对等依赖。如果缺少 `@openuidev/lang-core`，`vite build` 会因 `@kortix/sdk/dist/genui` 中的 `Missing export`（缺少导出）而失败。 |
| `tw-animate-css`, `tailwind-scrollbar`, `tailwind-scrollbar-hide` | 在 Tailwind v4 宿主中使用 `@kortix/ui/tailwind.css` 时需要。没有使用 Tailwind 的宿主无需安装。 |
| `@phosphor-icons/react@2.1.10` | 用于您自己的图标。请锁定 `@kortix/ui` 使用的版本，以便 `IconProvider` 也能作用于您的图标。 |

> **Info**
>
> 在安装时请明确指定 `react@19 react-dom@19`。如果不指定版本，npm 可能会选择 React 18 来满足 `cmdk@0.2.1` 的 React 18 对等依赖要求，从而导致安装无法完成。`Command` 组件在 React 19 上可以正常工作。如果宿主开启了 `strict-peer-dependencies`（严格对等依赖检查），必须允许 `cmdk` 的 React 对等依赖。

#### 导入路径（Import map）

| 导入路径 | 包含内容 |
| --- | --- |
| `@kortix/ui` | 核心功能：`UiProvider`、`useUiStrings`、`useUiLink`、`useUiBrand`、`defaultUiStrings`、`SessionIdsProvider`、`setUiRoutes`、`setUiTelemetry`、`setUiHostEnv`、`lazyClient`、`cn`、`useIsDark`、`useIsMobile`、`useDebounce`，以及 [Components and modules（组件与模块）](#组件与模块) 中列出的基础组件。 |
| `@kortix/ui/<component>` | 单个组件文件，例如 `@kortix/ui/modal` 或 `@kortix/ui/toast`。重型组件（图表、地图、数据网格、Emoji 选择器）仅从各自的子路径加载。 |
| `@kortix/ui/<module>` | 每个模块的一个精选入口，例如 `@kortix/ui/workspace` 或 `@kortix/ui/session`。请参阅 [Modules（模块）](#模块modules)。 |
| `@kortix/ui/theme` | `KortixTheme`、`themeToCss`、`themeToCssVars`、`ThemeScope`。请参阅 [Theming（主题化）](#主题定制theming)。 |
| `@kortix/ui/tailwind.css`, `/tokens.css`, `/tokens.css`, `/theme.css`, `/styles.css`, `/fonts.css` | 样式表。请参阅 [Add the styles（添加样式）](#添加样式)。 |

#### 服务端渲染（SSR）

以下入口会从 JavaScript 中导入 CSS（如 KaTeX 等）：`session`、`composer`、`session-panel`、`workspace`、`files`、`file-viewer`、`markdown`、`genui`、`customize`。原生 Node 环境无法解析这些文件，会抛出 `ERR_UNKNOWN_FILE_EXTENSION ".css"` 错误。请使用以下修复方案之一：

- Vite SSR 宿主：添加 `ssr: { noExternal: ['@kortix/ui'] }`。
- Next.js 宿主：在 `transpilePackages` 中添加 `@kortix/ui`。
- 任何宿主：仅使用 `lazyClient` 在客户端加载该模块。

根入口以及 `theme`、`i18n`、`icons`、`diff`、`changes`、`terminal`、`browser`、`apps` 和 `access` 入口可以在 Node 环境中正常解析。

### 添加样式

请在您的主样式表或入口文件中仅加载一次样式。请根据您的宿主环境选择对应的标签页。

**Tailwind CSS v4 宿主**

在引入 Tailwind 之后导入 `@kortix/ui/tailwind.css`。它会引入设计令牌（`tokens.css`）、组件层（`theme.css`）、动画工具类和滚动条插件。`theme.css` 包含一个 `@source` 规则，因此 Tailwind 会扫描该包以提取类名。

```css title="app.css"
@import 'tailwindcss';
@import '@kortix/ui/tailwind.css';
```

您自己的类名也会解析为相同的设计令牌：例如 `bg-background`、`text-muted-foreground`、`border-border`。

如果您希望使用自定义的令牌值，请逐个导入样式文件。除了 `tokens.css` 之外，其他每一行都是必需的。如果缺少 `tw-animate-css` 和那两个插件，覆盖层（Overlays）将失去进入和退出动画，并且 `scrollbar-hide` 工具类也会失效。不过，构建过程不会报告任何错误。

```css title="app.css"
@import 'tailwindcss';
@import 'tw-animate-css';
@import '@kortix/ui/tokens.css'; /* optional: or set every variable yourself */
@import '@kortix/ui/theme.css';
@plugin 'tailwind-scrollbar';
@plugin 'tailwind-scrollbar-hide';
```

> **Warning**
>
> `tokens.css` 会将 `--spacing` 设置为 `0.23rem`，这比 Tailwind 默认的 `0.25rem` 紧凑 8%。您自己的间距工具类也会受其影响：例如 `p-4` 的计算结果是 14.72px，而不是 16px。如果您希望自己的类名保持 Tailwind 的默认间距，请在导入该文件后，于 `:root` 中重新设置 `--spacing: 0.25rem`。此时，组件的渲染尺寸将会变大 8%。

**不使用 Tailwind 的宿主**

请导入一个预构建（Prebuilt）的样式文件。它包含了样式重置（Reset）、设计令牌（Tokens）以及组件所使用的全部类名。

```ts title="main.tsx"
import '@kortix/ui/styles.css';
```

它不包含任何仅供您自己代码使用的类名。请使用读取 CSS 变量的纯 CSS 来编写您自己的标记样式，例如使用 `var(--border)`。

- 暗黑模式通过在 `<html>` 标签上添加 `dark` 类名来激活。`useIsDark()` 会返回当前的暗黑模式状态。
- 这两种导入路径都会为页面设置基础样式：`body` 会使用 `--background` 和 `--foreground` 变量进行绘制，边框默认使用 `--border` 变量，原生控件会遵循 `color-scheme` 属性，文本选中状态会读取 `--selection` 变量，并且可交互元素会显示指针光标。您无需再添加任何基础样式规则。
- `@kortix/ui/fonts.css` 用于加载 Roobert 字体。该字体仅限 OpenChatly 官方界面使用。其他所有宿主请使用系统字体栈（`--font-sans-system`），或在其 [theme（主题）](#主题定制theming) 中配置 `fonts.sans`。

### 挂载 Providers（上下文提供者）

请在应用的根节点（Root）挂载 Providers，且必须将其放置在路由（Router）和 `QueryClientProvider` 的内部。该操作仅需执行一次。

```tsx title="providers.tsx"
import { UiProvider, type UiLinkComponent } from '@kortix/ui';
import { IconProvider } from '@kortix/ui/icon-provider';
import { Toaster } from '@kortix/ui/toast';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState, type ReactNode } from 'react';
import { Link } from 'react-router-dom';

import './kortix'; // creates the one client: see SDK > Create the client

// UiProvider calls `link` with anchor props, `href` and a Next.js-style `prefetch` hint.
const RouterLink: UiLinkComponent = ({ href, prefetch: _prefetch, ...props }) => (
  <Link to={href} {...props} />
);

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  return (
    <QueryClientProvider client={queryClient}>
      <UiProvider link={RouterLink}>
        <IconProvider>
          {children}
          <Toaster />
        </IconProvider>
      </UiProvider>
    </QueryClientProvider>
  );
}
```


| Provider（提供者） | 作用 | 缺失时的表现 |
| --- | --- | --- |
| `UiProvider` (`@kortix/ui`) | 将组件与您的路由、文案、品牌标识和宿主功能连接起来。具体选项见下表。它还会加载动画功能。 | 使用英文文案，使用普通的 `<a>` 和 `<img>` 标签，页面跳转时会全量刷新，显示 OpenChatly 官方 Logo，没有查看器（Viewer），没有插槽（Slots）。展开的行会保持关闭状态。 |
| `IconProvider` (`@kortix/ui/icon-provider`) | 为所有 Phosphor 图标设置 OpenChatly 的粗细和尺寸。 | 使用 Phosphor 图标的默认样式。 |
| `<Toaster />` (`@kortix/ui/toast`) | 渲染由 `@kortix/ui/toast` 中的 `successToast`、`errorToast` 及其他辅助函数触发的提示消息。 | 不会显示任何提示消息。 |
| `TooltipProvider` (`@kortix/ui/tooltip`) | 可选。为其下方的所有工具提示设置统一的悬停延迟，例如 `delayDuration={200}`。`Hint` 组件会挂载自己的 Provider，延迟为 300 毫秒。 | 每个工具提示使用各自的延迟时间。 |

`setUiTelemetry` (`@kortix/ui`) 不是一个 Provider。请在模块加载时调用一次，并传入 `track`、`captureException`、`captureMessage` 和 `addBreadcrumb`。请声明 `UiTelemetryRegister { event: YourEvents }`，以便 `tsc` 能够检查事件名称。如果不进行此配置，`track` 将不执行任何操作，而 `captureException` 仅会将错误输出到控制台。

#### `UiProvider` 选项

所有选项均为可选。请传入具有稳定引用（Stable identity）的对象。

| 选项 | 作用 |
| --- | --- |
| `link` | 您的路由 Link 组件，调用时会传入 `href` 属性。 |
| `navigation` | 将您的路由封装为四个 Hooks：`useRouter`（包含 `push`、`replace`、`prefetch`、`back`）、`usePathname`、`useSearchParams`、`useParams`。当您的路由监听 `history.pushState` 时（Next.js 会监听，React Router 不会），请添加 `observesHistory: true`。Next.js 宿主请直接传入 `next/navigation` 的 Hooks。 |
| `strings` | 基础组件的后备文案：`confirm`、`cancel`、`close`、`commandPaletteTitle`、`commandPaletteDescription`。仅传入您已翻译的键值。 |
| `i18n` | 会话 UI 的翻译配置：可传入 `useTranslations` 和 `useLocale`（next-intl 签名），或传入 `locale` 和 `messages`。默认使用 `@kortix/ui/i18n` 内置的英文目录。 |
| `image` | 您的图片组件。默认使用普通的 `<img>` 标签。 |
| `useBrand` | 一个返回您的 Logo URL 的 Hook。配置后，`KortixLogo` 将渲染您的品牌标识。 |
| `useViewerId` | 一个返回当前登录用户 ID 的 Hook。如果不配置查看器，多人协作的会话将无法识别发送者。 |
| `useViewer` | 一个返回当前登录用户信息的 Hook，格式为 `{ id, email?, metadata? }`。UI 会从 `metadata` 中读取 `name`、`full_name` 和 `avatar_url`。 |
| `updateViewerMetadata` | 将 UI 偏好设置保存到当前登录用户，以便跨设备同步。如果不配置，偏好设置将仅保存在浏览器本地。 |
| `components` | 会话 UI 会打开但不拥有的宿主功能组件：`ShareSessionModal`（由 `@kortix/ui/workspace` 导出）、`ProjectProviderModal`、`ProviderAccountsModal`、`ConnectorConnectModal`、`ArtifactViewer`、`RoomPanel`、`HomeAnnouncement`、`Wallpaper`。如果缺少某个插槽对应的组件，该控件将被隐藏。 |
| `resolvePreviewUrl` | `(request) => Promise<string \| null>`。返回会话浏览器框架使用的 URL，并附带您宿主自身的凭据。返回 `null` 则继续使用 SDK 默认的预览 URL。当浏览器不允许持有 OpenChatly Token 时请使用此选项。 |
| `config` | 宿主功能开关。详见下表。 |

| `config` 键 | 默认值 | 作用 |
| --- | --- | --- |
| `connectorsEnabled` | `true` | 设为 `false` 会隐藏托管的应用连接器目录。自定义连接器不受影响。 |
| `managedModelsEnabled` | `false` | 当部署环境提供托管模型列表时设为 `true`。模型选择器会列出这些模型。 |
| `terminalEnabled` | `true` | 设为 `false` 会隐藏终端。适用于代理无法升级 WebSocket 连接的宿主。 |
| `cliConnectEnabled` | `true` | 设为 `false` 会隐藏终端中的“从您的机器连接”提示栏。适用于不提供 `<origin>/install` 页面且不附带 OpenChatly CLI 的宿主。 |
| `publicSharesEnabled` | `true` | 设为 `false` 会隐藏所有公开链接控件。适用于不提供 `/share/session/<token>` 页面的宿主。 |
| `accountApiEnabled` | `true` | 适用于使用单一操作员密钥并拦截账户路由的宿主，请设为 `false`。此时不会运行任何 IAM、计费或会话监督请求。每个权限门控都会显示其控件，并由服务器强制执行路由检查。 |
| `modelPickerEnabled` | `true` | 设为 `false` 会隐藏模型和推理强度选择器。会话将使用默认模型运行。 |
| `contextMeterEnabled` | `true` | 设为 `false` 会隐藏上下文使用量环形指示器。 |
| `sessionOverridesEnabled` | `true` | 设为 `false` 会隐藏会话覆盖设置齿轮图标（沙箱、密钥、连接器、文件夹）。 |
| `runtimeSlashEnabled` | `true` | 设为 `false` 会从 `/` 菜单中移除运行时的技能、命令和 Compact 会话。 |
| `useSlashActions` | 无 | 一个返回自定义 `/` 菜单行的 Hook，格式为：`{ id, label, description, group, onSelect }`。 |
| `offeredAgents`, `agentLabels` | 所有代理，名称首字母大写 | 代理选择器提供的代理列表及其显示名称。 |
| `takeFiles`, `attachAccept` | 作为提示附件上传 | `takeFiles(files)` 用于将附加、拖拽和粘贴的文件存入您自己的存储中。`attachAccept` 是选择器的 `accept` 文件类型列表。 |
| `commandPaletteShortcut`, `settingsShortcut` | `false` | 当您的宿主在 ⌘K 时打开命令面板或在 ⌘, 时打开设置时，请设为 `true`。此时编辑器会提示这些快捷键。 |
| `providerIconBaseUrl` | models.dev | 您的宿主提供服务商 Logo 的基础 URL，格式为 `<base>/<icon>.svg`。OpenChatly 提供商会绘制 `useBrand` 的图标。 |
| `deploymentVersion` | latest | 用于版本锁定的 CLI 安装命令的发布版本号。 |

计费门控不是 `UiProvider` 的选项。它们通过 [`createKortix`](#创建客户端) 读取 `billingEnabled` 配置。自定义宿主通常会关闭此选项，此时不会渲染任何升级控件。

### 添加会话

一个会话需要一个 [`useSession`](#usesession) 的返回值。将其传入组件即可；无需编写第二个聊天 Hook，也无需自行处理传输层。

`SessionWorkspace` (`@kortix/ui/workspace`) 会渲染 OpenChatly Web 应用的完整会话界面：包括对话线程（Thread）以及由操作触发的可调整大小的侧边面板（包含文件、文件查看器、浏览器、终端、变更等）。在手机端，该面板会以抽屉（Sheet）形式展示。父组件负责设置其尺寸。

```tsx title="session.tsx"
import { useSession } from '@kortix/sdk/react';
import { SessionWorkspace } from '@kortix/ui/workspace';

export function Session({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const session = useSession(projectId, sessionId);
  return <SessionWorkspace session={session} />;
}
```

`SessionWorkspace` 接收 `session`、`children`（用于替代默认线程的自定义列）、`hideHeader`、`readOnly` 和 `className` 属性。其中，`hideHeader` 和 `readOnly` 仅对默认的对话线程生效。

#### 仅渲染对话线程

`SessionThread` (`@kortix/ui/session`) 用于渲染单个会话的聊天界面：包括对话记录（Transcript）、流式传输中的回合、工具调用行、权限与提问提示、发送错误信息，以及带有附件、斜杠命令、模型与代理选择器和停止按钮的编辑器（Composer）。

```tsx title="chat.tsx"
import { useSession } from '@kortix/sdk/react';
import { SessionThread } from '@kortix/ui/session';

export function Chat({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const session = useSession(projectId, sessionId);
  return (
    <div className="flex h-dvh flex-col">
      <SessionThread session={session} hideHeader />
    </div>
  );
}
```

| 属性（Prop） | 类型（Type） | 作用 |
| --- | --- | --- |
| `session` | `UseSessionResult`，必填 | `useSession(projectId, sessionId)` 的返回值。 |
| `hideHeader` | `boolean` | 隐藏标题行（包含标题、分享、菜单）。当您的页面已有自己的页眉时使用。 |
| `readOnly` | `boolean` | 隐藏编辑器（Composer）。此时对话线程仅作为只读记录展示。 |
| `composerPlaceholder` | `string` | 编辑器的占位符文本。默认使用编辑器自带的占位符。 |
| `quote` | `{ id: number; text: string } \| null` | 将 `text` 作为引用添加到编辑器的回复中，效果与在对话记录中选择“回复”相同。每个新的 `id` 仅会添加一次其对应的文本。 |
| `firstPrompt` | `string` | 您的宿主刚刚创建的会话的第一条提示词。在沙箱启动期间，线程会立即绘制该提示词，随后将其移入对话记录中。请仅在创建新会话时传入此属性。 |
| `density` | `'default' \| 'compact'` | 设为 `compact` 会收紧间距（Gutters），适用于较窄的列，例如侧边抽屉面板。 |
| `className` | `string` | 应用于线程根元素的 CSS 类名。 |

- 高度由父组件设置，线程会自动填满该高度。
- `SessionThread`、`SessionWorkspace` 和 `ProjectHome` 会自行挂载项目作用域（Project scope）和 `SessionIdsProvider`。
- 如果页面上没有侧边面板，线程打开的文件或预览内容将以对话框（Dialog）形式展示。
- `SessionThread` 默认会渲染 [Generative UI（生成式 UI）](#生成式-uigenerative-ui) 内容块，您无需为其编写任何代码。
- `ModelSelector` 和 `AgentSelector` (`@kortix/ui/session`) 是编辑器的选择器组件。它们是受控组件，因此也可以用于会话之外的表单中。

#### 替换单个工具调用行

`@kortix/ui/session` 在加载时会注册所有内置的工具调用行。您可以使用 `ToolRegistry.register(name, Component)` 来替换特定工具名称对应的行。如果针对同一名称进行多次注册，后注册的将优先生效。该行组件会接收 `ToolProps` 属性：其中 `call` 是包含 `name`、`input`、`status`（`pending` 等待中、`running` 运行中、`complete` 完成、`error` 错误）以及 `result.content`（包含文本和附件部分）的会话日志工具调用对象。`BasicTool` 用于绘制标准工具行，而 `GenericTool` 是默认的工具行。

```tsx title="src/shell-row.tsx"
import { BasicTool, ToolRegistry, type ToolProps } from '@kortix/ui/session';
import { TerminalWindowIcon } from '@phosphor-icons/react';

function ShellRow({ call }: ToolProps) {
  const command = (call.input as { command?: string } | null)?.command ?? '';
  const output = (call.result?.content ?? [])
    .map((part) => (part.type === 'text' ? part.text : ''))
    .join('');
  return (
    <BasicTool icon={<TerminalWindowIcon />} trigger={{ title: 'Shell', subtitle: command }}>
      <pre className="bg-muted overflow-x-auto rounded-md p-3 font-mono text-xs">
        {output || 'No output yet'}
      </pre>
    </BasicTool>
  );
}

// Replaces the built-in row of the `bash` tool.
ToolRegistry.register('bash', ShellRow);
```

请在您的入口文件中仅导入一次该文件：`import './shell-row'`。

#### 组合自定义工作区

这些模块可以在任意层级进行组合。请根据您的需求选择合适的层级。

| 您的需求 | 使用的组件 |
| --- | --- |
| 在您的应用外壳（Chrome）中嵌入完整的 OpenChatly 会话界面 | `SessionWorkspace` |
| 在 OpenChatly 侧边面板旁显示您自定义的对话列 | `<SessionWorkspace session={session}>{yourColumn}</SessionWorkspace>` |
| 仅显示对话线程，无侧边面板 | `SessionThread`。它会自行挂载预览宿主（Preview host）。如果您的页面既没有 `SessionThread` 也没有侧边面板，请从 `@kortix/ui/files` 中导入并挂载一次 `<FilePreviewHost />`。 |
| 使用您自定义的面板 | 从 `@kortix/ui/session-panel` 导入 `SessionPanelProvider` 和 `ActionPanel`，或从 `@kortix/ui/terminal` 导入 `SessionTerminal`。 |
| 使用单个独立的内容块 | 从 `@kortix/ui/session` 导入：`UserMessage`、`ThrottledMarkdown`、`ToolPartRenderer`、`ModelSelector`、`AgentSelector`、`SessionPermissionPrompt`、`QuestionPrompt`；从 `@kortix/ui/composer` 导入：`ComposerChatInput`。 |
| 所有部分均由您自己的组件绘制 | 不使用 `@kortix/ui/session`。请从 `@kortix/sdk/react` 导入 `useChatTurns` 和 `renderParts`：[Render messages yourself（自行渲染消息）](#自行渲染消息)。 |

如果在 `SessionThread`、`SessionWorkspace` 和 `ProjectHome` 之外使用内容块，您需要手动挂载这两个组件为您提供的上下文作用域（Scopes）：从 `@kortix/sdk/react` 导入的 `KortixProjectProvider` 和从 `@kortix/ui` 导入的 `SessionIdsProvider`。如果不挂载 `SessionIdsProvider`，`useSessionIds()` 将无法返回任何 ID。

```tsx title="ask.tsx"
import { KortixProjectProvider } from '@kortix/sdk/react';
import { SessionIdsProvider } from '@kortix/ui';
import { ComposerChatInput } from '@kortix/ui/composer';

// The composer before a session exists. You decide what a send does.
export function Ask({ projectId, onAsk }: { projectId: string; onAsk: (text: string) => void }) {
  return (
    <KortixProjectProvider projectId={projectId}>
      <SessionIdsProvider projectId={projectId}>
        <ComposerChatInput projectId={projectId} onSend={(text) => onAsk(text)} />
      </SessionIdsProvider>
    </KortixProjectProvider>
  );
}
```

### 路由（Routes）

组件所链接或导航到的每个 URL 均来源于同一个路由表。请在模块加载时调用一次 `setUiRoutes` (`@kortix/ui`)。未指定的路由将保留其默认值。

- 如果您在另一个 URL 提供某个页面，请为其返回您自定义的路径。
- 如果您不提供某个页面，请返回 `null`。此时，指向该页面的所有链接都会被隐藏，且不会发生任何导航。
- `project`、`session`、`channel` 和 `dm` 路由不能返回 `null`。侧边栏仅在项目的 `project_channels` 标志开启时，才会链接到 `channel` 和 `dm`。
- 如果宿主配置了 `customize` 路由但未指定 `admin` 路由，`admin` 将自动采用与 `customize` 相同的路径映射。

| 路由（Route） | 参数（Arguments） | 默认值（Default） |
| --- | --- | --- |
| `project` | `projectId` | `/projects/<id>`（新会话编辑器） |
| `session` | `projectId`, `sessionId` | `/projects/<id>/sessions/<sessionId>` |
| `sessions` | `projectId`, `view?: 'archived' \| 'deleted'` | `/projects/<id>/sessions`，附带 `?view=<view>` |
| `files` | `projectId`, `panel?: 'proposed-changes'` | `/projects/<id>/files`，附带 `?panel=<panel>` |
| `drive` | `projectId` | `/projects/<id>/drive` |
| `apps` | `projectId` | `/projects/<id>/apps` |
| `rooms` | `projectId` | `/projects/<id>/rooms` |
| `goals` | `projectId` | `/projects/<id>/goals` |
| `artifacts` | `projectId` | `/projects/<id>/artifacts` |
| `space` | `projectId`, `slug` | `/projects/<id>/spaces/<slug>` |
| `members` | `projectId` | `/projects/<id>/members` |
| `sandboxSettings` | `projectId` | `/projects/<id>/admin/sandbox` |
| `customize` | `projectId`, `path?` | `/projects/<id>/customize/<path>`（包含 agents, skills, connectors, triggers, reminders, models, secrets, review, settings） |
| `admin` | `projectId`, `path?` | `/projects/<id>/admin/<path>`（项目管理后台区块） |
| `channel` | `projectId`, `slug` | `/projects/<id>/c/<slug>` |
| `dm` | `projectId`, `agentName` | `/projects/<id>/dm/<agentName>` |
| `memory` | `projectId` | `/projects/<id>/memory` |

```ts
import { setUiRoutes } from '@kortix/ui';

setUiRoutes({
  session: (projectId, sessionId) => `/w/${projectId}/chat/${sessionId}`,
  drive: () => null,
  customize: () => null,
});
```

`uiRoutes()` 会返回当前生效的路由表。`defaultUiRoutes` 则包含默认的路由配置。

### 主题定制（Theming）

白标（White-label）定制主要通过覆盖 CSS 变量来实现。宿主需要修改的每个值都是一个 CSS 变量：包括亮色和暗色模式下的颜色、圆角、边框宽度、字体、字体比例（Type scale）、间距密度、阴影以及动效。`@kortix/ui/theme` 可以将一个带有类型定义的主题对象转换为这些 CSS 变量。

主题对象中的每个字段都是可选的。未设置的字段将保留 OpenChatly 的默认值。如果未设置 `dark`（暗色模式）的颜色，系统将回退到 OpenChatly 默认的暗色配置，而**不会**回退到您设置的 `light`（亮色模式）值。

```tsx title="app/layout.tsx"
import { themeToCss, type KortixTheme } from '@kortix/ui/theme';
import type { ReactNode } from 'react';

const brand: KortixTheme = {
  light: { blue: '#4f46e5', ring: '#4f46e5', border: '#e0e7ff' },
  dark: { blue: '#818cf8', ring: '#818cf8', border: '#312e81' },
  radius: '0.25rem',
  fonts: { sans: 'Inter, system-ui, sans-serif' },
};

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <style>{themeToCss(brand)}</style>
      </head>
      <body>{children}</body>
    </html>
  );
}
```

`themeToCss` 是一个纯函数。它可以在服务端运行，确保首次渲染（First paint）时就能应用您的主题。它的样式规则优先级高于 `tokens.css`，因此生成的 `<style>` 元素可以放置在页面的任意位置。白标（White-label）示例均采用了这种主题配置方式：`apps/white-label/lumen/src/config/theme.ts` 和 `apps/white-label/reskin/src/config/theme.ts`。

| 导出项（Export） | 签名（Signature） | 用途（Use） |
| --- | --- | --- |
| `KortixTheme` | `{ light?, dark?, radius?, spacing?, borderWidth?, fonts?, text?, lineHeights?, shadows?, durations?, easing?, vars? }` | 主题对象。`light` 和 `dark` 接受下方的颜色键以及任何 `--custom` 自定义变量。`vars` 用于在两种模式下设置其他任意变量。未知的字段、颜色或色阶会导致类型错误，并在运行时抛出异常。 |
| `themeToCss` | `(theme: KortixTheme, selector = ':root') => string` | 生成样式表：亮色模式应用于 `.dark` 类名之外，暗色模式应用于 `.dark` 类名之上或内部。传入 `selector` 参数可对单个元素进行主题定制。如果值中包含 `;`、`{`、`}`、`<`、`>`、`\` 或注释，或者变量名不匹配 `--[A-Za-z0-9_-]+` 正则，该函数将抛出异常。由租户数据构建的主题不能添加 CSS 规则。 |
| `themeToCssVars` | `(theme: KortixTheme) => { light: Record<string, string>; dark: Record<string, string> }` | 将相同的变量以数据形式返回，适用于自行编写 CSS 或通过 JavaScript 设置变量的宿主。与模式无关的值会同时出现在两者中。 |
| `ThemeScope` | `<ThemeScope theme={...} className? {...divProps}>` | 为单个子树应用主题：例如嵌入式小部件、客户预览界面或设置面板。 |
| `THEME_COLOR_VARS` | `Record<ThemeColor, string>` | 颜色键到 CSS 变量的映射表。 |

#### ThemeScope（主题作用域）

```tsx title="themed-chat.tsx"
import type { UseSessionResult } from '@kortix/sdk/react';
import { SessionThread } from '@kortix/ui/session';
import { ThemeScope } from '@kortix/ui/theme';

export function ThemedChat({ session }: { session: UseSessionResult }) {
  return (
    <ThemeScope theme={{ light: { primary: '#0f766e' }, radius: '1rem' }} className="bg-background h-dvh">
      <SessionThread session={session} />
    </ThemeScope>
  );
}
```

- 在该作用域内打开的对话框（Dialog）、气泡卡片（Popover）、菜单、工具提示、下拉选择、抽屉面板（Sheet）与侧边抽屉，都会被传送（Portal）到位于 `<body>` 末尾、并承载该作用域主题的宿主节点中。嵌套作用域的覆盖层会同时承载内外两层主题。作用域的祖先元素上若有 `transform`、`filter`、`backdrop-filter`、`contain` 或 `overflow: hidden`，也不会裁剪或偏移这些覆盖层。
- 该作用域会在其元素上设置 `font-family` 和 `color`。它不会绘制任何背景：请自行添加 `bg-background`。
- `className="dark"` 会强制该子树使用暗色模式。作用域无法在暗色页面内部强制切换为亮色。
- 作用域元素内仅包含您的子节点。它对应的 `<style>` 会作为该元素的前一个兄弟节点渲染。因此子节点上的 `flex`、`grid`、`space-y-*`、`first:` 和 `last:` 表现与没有该作用域时一致。
- Toast（提示消息）不会被传送。若要为 Toast 定制主题，请将 `<Toaster />` 挂载在 `ThemeScope` 内部、其顶层位置，而不要放在带有 transform 的面板之中。

#### 令牌（Tokens）

颜色可接受任意 CSS 颜色。默认值依次为 亮色 / 暗色。

| 键（Key） | 变量（Variable） | 控制内容（Controls） | 默认值（Default） |
| --- | --- | --- | --- |
| `background` | `--background` | 页面 | `#ffffff` / `#0b0b0b` |
| `pane`, `surface` | `--pane`, `--surface` | 基础面板与凸起面板 | `#ffffff` / `#0c0c0c`、`#fcfcfc` / `#141414` |
| `foreground` | `--foreground` | 文本 | `#1f1f1f` / `#ffffff` |
| `foregroundStrong`, `foregroundWeak` | `--foreground-strong`, `--foreground-weak` | 强调文本与弱化文本 | 跟随 `foreground` / `mutedForeground` |
| `action`, `actionForeground` | `--action`, `--action-foreground` | 默认 `Button` 的填充色及其文字（主要操作、Send 发送） | 跟随 `foreground` / `background` |
| `card`, `cardForeground` | `--card`, `--card-foreground` | `Card`、聊天工具卡片与提问 | `#f4f4f4` / `#141414` |
| `popover`, `popoverForeground` | `--popover`, `--popover-foreground` | 菜单、气泡卡片、输入框 | `#ffffff` / `#141414` |
| `primary`, `primaryForeground` | `--primary`, `--primary-foreground` | `Progress`、`Slider`、`Calendar` 选中态、菜单高亮 | `#1f1f1f` / `#ffffff` |
| `secondary`, `secondaryForeground` | `--secondary`, `--secondary-foreground` | 次要按钮 | `#ededed` / `#1c1c1c` |
| `muted`, `mutedForeground` | `--muted`, `--muted-foreground` | 弱化填充、聊天用户气泡、代码块、字幕说明 | `#ededed` / `#1c1c1c`、`#666666` / `#999999` |
| `accent`, `accentForeground` | `--accent`, `--accent-foreground` | 悬停的行 | `#f4f4f4` / `#141414` |
| `destructive`, `destructiveForeground` | `--destructive`, `--destructive-foreground` | 错误、危险操作按钮 | `#e7000b` / `#ff6467` |
| `border` | `--border` | 所有细线及默认边框颜色 | `#e2e2e2` / `#262626` |
| `input` | `--input` | 输入框填充色 | `#ededed` / `#1c1c1c` |
| `ring`, `focusRing` | `--ring`, `--focus-ring` | 聚焦环、聚焦状态的编辑器；卡片聚焦环 | `#0099ff`；`focusRing` 跟随 `ring` |
| `hover`, `active` | `--hover`, `--active` | 半透明的悬停与按下叠加色 | 墨色（ink）4.5% / 7.5%，白色 6% / 10% |
| `selection`, `selectionForeground` | `--selection`, `--selection-foreground` | 文本选中态 | `primary` 的 72% |
| `sidebar`, `sidebarForeground`, `sidebarPrimary`, `sidebarPrimaryForeground`, `sidebarAccent`, `sidebarAccentForeground`, `sidebarRow`, `sidebarRowControl`, `sidebarBorder`, `sidebarRing` | `--sidebar-*` | 侧边栏。`sidebar` 同时用于填充 `Dialog`、`AlertDialog`、`Modal` 和 `Sheet`。 | OpenChatly 面板色值 |
| `blue` | `--kortix-blue` | 强调色：选中的 `Switch`、`Checkbox` 或 `RadioGroup`，`brand` 与 `blue` 的 `Button` 变体，信息类 `Badge`、`InfoBanner` | `#2b91f7` |
| `green`, `orange`, `yellow`, `red`, `purple` | `--kortix-*` | 状态色调。请保留其语义。 | `#199338`、`#d18b19`、`#cca300`、`#f14b4c`、`#ab80d6` |
| `brand` | `--kortix-base` | OpenChatly 基础强调色 | 跟随 `ring` |
| `chart1` … `chart5` | `--chart-1` … `--chart-5` | 图表系列色 | 一组琥珀色渐变色阶 |
| `terminalSurface`, `terminalForeground`, `terminalBorder` | `--terminal-*` | 终端面板（始终为暗色） | `#0f0f0f`、`#e5e5e5`、白色 10% |

以下键在两种模式下均适用：

| 键（Key） | 变量（Variable） | 控制内容（Controls） | 默认值（Default） |
| --- | --- | --- | --- |
| `radius` | `--radius` | 所有圆角。`rounded` 为 −6px，`-sm` −4px，`-md` −2px，`-lg` 相等，`-xl` +4px，`-2xl` +6px。 | `0.625rem` |
| `borderWidth` | `--border-width` | 所有未显式指定宽度的 `border*` 与 `divide-*` 线条 | `1px` |
| `spacing` | `--spacing` | 间距密度：所有 `p-*`、`m-*`、`gap-*`、`size-*` 均为其倍数 | `0.23rem` |
| `fonts.sans`, `fonts.mono` | `--font-family-sans`, `--font-family-mono` | 正文与标题；代码、ID、`Badge` | 系统字体栈 |
| `text.xs` … `text['8xl']` | `--text-<step>` | 每个 `text-*` 色阶的字号 | `0.8125rem` … `6rem` |
| `lineHeights.<step>` | `--text-<step>--line-height` | 每个 `text-*` 色阶的行高 | 每个色阶对应的 OpenChatly 比例 |
| `shadows['2xs']` … `shadows['2xl']` | `--shadow-<step>` | 每个 `shadow-*` 色阶的层级高度。使用 `0 0 #0000` 可将某一层压平。 | Tailwind 的阴影色阶 |
| `durations.fast` … `durations.slower` | `--duration-<step>` | `duration-fast` … `duration-slower` | `100ms`、`150ms`、`200ms`、`300ms`、`500ms` |
| `easing.default`, `in`, `out`, `inOut` | `--ease-*` | `ease-*` 缓动曲线 | OpenChatly 缓动曲线 |
| `vars` | 任意 `--name` | 其他任意变量，例如 `--liquid-glass-blur` | 无 |

#### 限制

- 显式指定宽度的类名（`border-2`、`border-[3px]`）保持固定。只有不带宽度的 `border*` 与 `divide-*` 会跟随 `borderWidth`。
- 没有对应色阶的字号保持固定：即 10px、11px 和 12px 的字幕说明，以及 `0.8rem` 的行内代码小标签（inline code chip）。
- 没有对应色阶的时长保持固定：`duration-80`、`duration-0`，侧边栏滑入动画（在 `cubic-bezier(0.32, 0.72, 0, 1)` 上的 `200` / `240` / `260ms`）、命令面板（`140` / `180ms`）以及进入/退出关键帧（`200` / `250ms`）。所有 `duration-100` / `150` / `200` / `300` / `500` 都会读取 `duration-fast` … `duration-slower`。
- 聊天界面没有自己的专属令牌，它们读取 `muted`、`card`、`border` 和 `mutedForeground`。
- 装饰性取值保持固定：对话框的遮罩层（scrim）、`inverse` 的 `Button` 变体、`Tag` 的状态调色板、加载器与点阵（dot-matrix）渐变，以及图例色块。

#### 规则

- 通过令牌进行主题定制。绝不要分叉（fork）或重新给某个组件写样式：分叉出来的副本将无法再获得后续的修复更新。
- 请通过 `UiProvider` 的 `useBrand` 选项传入您的 Logo。
- 不要加载 `fonts.css`。请设置 `fonts.sans`。
- 纯 CSS 在 `@kortix/ui` 导入之后即可生效。请将亮色取值放在 `:root:not(.dark)` 中，暗色取值放在 `.dark` 中。裸写的 `:root` 规则同样会匹配 `<html class="dark">`，从而覆盖暗色取值。`themeToCss` 会为您自动生成这些选择器。

### 组件与模块

#### 基础元素（Primitives）

根入口 `@kortix/ui` 会连同各部件一起导出基础元素：`Button`、`Badge`、`Card`、`Input`、`Textarea`、`Label`、`Checkbox`、`Switch`、`Select`、`Modal`、`Hint`、`Popover`、`DropdownMenu`、`Tabs`、`FilterBar`、`Separator`、`Skeleton`、`Bubble`、`Message`、`Marker`。其余每个组件都对应一个子路径，形如 `@kortix/ui/<file>`。位于 [openchatly.com/design-system](https://openchatly.com/design-system) 的实时目录会以亮色和暗色分别渲染每一个组件，并附上其使用规则。

| 需求 | 组合方式（Compose） | 导入路径（Import） |
| --- | --- | --- |
| 操作 | `Button`、`ButtonGroup`、`Toggle` | `button`、`button-group`、`toggle` |
| 表单 | `Field`、`Input`、`Textarea`、`Select`、`CheckboxGroup`、`RadioGroup`、`Switch`、`Slider`、`Label` | `field`、`input`、`textarea`、`select`、`checkbox-group`、`radio-group`、`switch`、`slider`、`label` |
| 搜索 | `InputGroupSearch`、`PageSearchBar`、`Command` | `input-group`、`page-search-bar`、`command` |
| 覆盖层 | `Modal`、`Sheet`、`Popover`、`DropdownMenu`、`Hint` | `modal`、`sheet`、`popover`、`dropdown-menu`、`hint` |
| 确认 | `ConfirmDialog`、`AlertDialog` | `confirm-dialog`、`alert-dialog` |
| 反馈 | `InfoBanner`、Toast 辅助函数、`Loading`、`Skeleton`、`Progress` | `info-banner`、`toast`、`loading`、`skeleton`、`progress` |
| 状态 | `Badge`、`CountBadge`、`StatusBadge` | `badge`、`count-badge`、`status` |
| 布局 | `Card`、`Section`、`Tabs`、`Disclosure`、`Accordion`、`Separator`、`ScrollArea`、`Sidebar` | `card`、`section`、`tabs`、`disclosure`、`accordion`、`separator`、`scroll-area`、`sidebar` |
| 数据 | `Table`、`DefinitionList`、`InlineMeta`、`Empty`、`Calendar` | `table`、`definition-list`、`inline-meta`、`empty`、`calendar` |
| 人物 | `UserAvatar`、`EntityAvatar` | `user-avatar`、`entity-avatar` |

先组合，再造新（Compose before you create）：

- 对话框用 `Modal`，工具提示用 `Hint`，加载动画用 `Loading`，小标签用 `Badge`，危险操作前用 `ConfirmDialog`。
- 在业务功能代码中禁止使用 `Dialog` 和 `Tooltip`。根入口之所以导出它们，是因为 `Modal` 和 `Hint` 基于它们构建，二者都带有 `@deprecated`（已废弃）标记。
- 绝不要直接调用 `sonner` 的 `toast()` 函数。请使用 `@kortix/ui/toast` 中的辅助函数。
- 绝不要给图标加上 `animate-spin` 当作加载动画来用。图标来自 `@phosphor-icons/react`。

#### 模块（Modules）

每个模块都有一个入口（Entry）。入口导出的名称即为其公共 API，受语义化版本（Semver）保护。每个模块都需要在根节点挂载 `UiProvider` 和 `QueryClientProvider`。

| 入口（Entry） | 包含内容（Holds） | 最小挂载方式（Minimal mount） |
| --- | --- | --- |
| `@kortix/ui/workspace` | 组合的项目界面：`SessionWorkspace`、`ProjectHome`（新会话编辑器；用于创建并打开会话）、`ProjectSessionList`、`ProjectSessionsView`、`ProjectFilesView`、`ProjectSidebar`、`ShareSessionModal` | `<SessionWorkspace session={session} />`、`<ProjectHome projectId={projectId} />`；`ProjectSessionList` 需放置在 `SidebarProvider` 内部 |
| `@kortix/ui/session` | 对话界面：`SessionThread`、对话回合（turns）、工具调用行、`ToolRegistry`、`BasicTool`、`GenericTool`、提示词（prompts）、`ModelSelector`、`AgentSelector` | `<SessionThread session={session} />` |
| `@kortix/ui/composer` | 编辑器（Composer）：`ComposerChatInput`、`SessionChatInput`、其子部件及发送管道（send pipeline） | 在项目作用域内使用 `<ComposerChatInput projectId={projectId} onSend={...} />` |
| `@kortix/ui/session-panel` | 侧边面板：`SessionPanelProvider`、`ActionPanel`、`SessionFiles`、`SessionChanges`、`SessionAudit`、`openSessionQuickView` | 带有运行时 ID 的 `SessionPanelProvider` |
| `@kortix/ui/files` | 项目文件（基于 Git 的仓库：`ProjectFilesProvider`、`FileExplorerPage`、`DriveExplorer`）、沙箱文件（`SandboxFileExplorer`）、`FilePreviewHost`、云盘与变更请求 Hooks | 来自 `workspace` 的 `ProjectFilesView`（它会填满父容器；需由父组件设置高度）；如果页面没有侧边面板且没有 `SessionThread`，请挂载一次 `<FilePreviewHost />` |
| `@kortix/ui/file-viewer` | `FileViewer`、`FileContentRenderer`（支持 pdf、docx、xlsx、csv、pptx、zip、图片、代码）、`FilePreviewModal`、`FileSourceProvider` | `<FileViewer content={text} fileName="notes.md" />` |
| `@kortix/ui/terminal`、`@kortix/ui/browser` | `SessionTerminal`；`SessionBrowser`、`BrowserLanding` | 已挂载的 `useSession` 的运行时 ID |
| `@kortix/ui/markdown` | `UnifiedMarkdown`、`MarkdownWithFrontmatter`、`HighlightedCode` | `<UnifiedMarkdown content={text} trust="agent" />` |
| `@kortix/ui/genui` | `GenuiBlock` 与 `genuiComponents`，基于 `@kortix/sdk/genui/react` 的 Web 组件集。参见 [Render blocks in React（在 React 中渲染内容块）](#在-react-中渲染内容块)。 | 无 |
| `@kortix/ui/diff`、`@kortix/ui/changes` | `DiffView`；`ChangeList` | `<DiffView before={{ name, contents }} after={{ name, contents }} />` |
| `@kortix/ui/apps`、`@kortix/ui/artifacts` | `AppPreview`、应用框架池与应用视图模型；Artifact 框架与会话卡片 | 无 |
| `@kortix/ui/access`、`@kortix/ui/customize` | 共享与角色管理（`AccessDialog`、`RoleSelect`、`PrincipalPicker`）；项目配置页面（`ConnectorsPage`、`AgentsPage`、`TriggersPage`、`SecretsPage`、`ModelsPage`、`SkillsPage`、`ProjectSettingsPage`） | `<ConnectorsPage projectId={projectId} />` |
| `@kortix/ui/theme`、`@kortix/ui/i18n`、`@kortix/ui/icons` | 带类型的主题对象；`useTranslations` 与 `useLocale`；组件库的图标字形 | 无 |

包技能（Package skill）列出了每个入口的所有名称、对应的 Props 及一个示例：`packages/ui/skills/kortix-ui/references/modules.md`。

> **Warning**
>
> 深层路径不受语义化版本（Semver）保护。`@kortix/ui/internal/*` 和 `@kortix/ui/<module>/<path>`（例如 `@kortix/ui/session/thread/session-chat`）虽然可以解析，但它们仅存在于 OpenChatly 自己的应用中（见 `packages/ui/scripts/deep-exports.json`）。它们可能在任何版本中发生变更或被移除。请始终导入模块入口（Entry）。如果某个入口缺少您需要的名称，请提交问题（Report），以便将该名称添加到入口中。

### 构建仪表盘（Dashboard）

仪表盘是指包裹在组合界面外层的您的应用外壳（Chrome）：例如在您的侧边栏中展示 OpenChatly 会话列表、使用 `ProjectHome` 启动会话、使用 `SessionWorkspace` 进行会话操作、使用 `ProjectFilesView` 管理项目文件。

以下步骤基于一个 Vite + React 19 + react-router 应用的文件结构。请在 [Install and peers（安装与对等依赖）](#安装与对等依赖) 的安装步骤中添加 `react-router-dom`。浏览器中应保存已登录用户的刷新令牌（Refreshing token），绝不能保存 API 密钥。

1. **创建客户端（Create the client）**

    从 [Create the client（创建客户端）](#创建客户端) 中的客户端配置开始。在浏览器环境中，请从无头会话存储（Headless session store）中获取 `getToken`（参见 [Sign users in headlessly（无头模式用户登录）](#无头模式登录用户)）。该存储会保存用户的令牌，并在其过期前 60 秒自动刷新。

    ```ts title="src/kortix.ts"
    import { createKortix, createKortixSession } from '@kortix/sdk';

    // The signed-in user's tokens. Memory only: pass `storage` to keep them across reloads.
    export const authSession = createKortixSession();

    // One client per host, at module scope. Every @kortix/sdk/react hook and
    // every @kortix/ui component reads it.
    export const kortix = createKortix({
      backendUrl: import.meta.env.VITE_KORTIX_API_URL ?? 'https://api.kortix.com/v1',
      getToken: () => authSession.getToken(),
    });
    ```

    浏览器来源（Origin）必须包含在 API 的 CORS（跨域资源共享）白名单中。在本地开发时，请通过您的开发服务器代理 `/v1` 请求，并将 `backendUrl` 指向该代理地址。如果在 OpenChatly App 内部运行，客户端将直接作为查看器（Viewer）运行：详情请参见 [Know the viewer in an OpenChatly App（在 OpenChatly App 中识别查看器）](#识别-openchatly-app-中的查看者)。

2. **连接您的路由与主题**

    ```ts title="src/theme.ts"
    import type { KortixTheme } from '@kortix/ui/theme';

    export const acmeTheme: KortixTheme = {
      light: { blue: '#0f766e', ring: '#0f766e', border: '#cbd5e1', muted: '#f1f5f9' },
      dark: { blue: '#2dd4bf', ring: '#2dd4bf', border: '#334155', muted: '#1e293b' },
      radius: '0.375rem',
    };
    ```

    ```tsx title="src/router-adapters.tsx"
    import type { UiLinkComponent, UiNavigation, UiRouter } from '@kortix/ui';
    import { useMemo } from 'react';
    import { Link, useLocation, useNavigate, useParams, useSearchParams } from 'react-router-dom';

    export const RouterLink: UiLinkComponent = ({ href, prefetch: _prefetch, ...props }) => (
      <Link to={href} {...props} />
    );

    function useUiRouterAdapter(): UiRouter {
      const navigate = useNavigate();
      return useMemo(
        () => ({
          push: (href) => navigate(href),
          replace: (href) => navigate(href, { replace: true }),
          prefetch: () => {},
          back: () => navigate(-1),
        }),
        [navigate],
      );
    }

    export const navigation: UiNavigation = {
      useRouter: useUiRouterAdapter,
      usePathname: () => useLocation().pathname,
      useSearchParams: () => useSearchParams()[0],
      useParams: () => useParams(),
    };
    ```

    ```tsx title="src/providers.tsx"
    import { UiProvider } from '@kortix/ui';
    import { IconProvider } from '@kortix/ui/icon-provider';
    import { themeToCss } from '@kortix/ui/theme';
    import { Toaster } from '@kortix/ui/toast';
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { useState, type ReactNode } from 'react';

    import './kortix';
    import { navigation, RouterLink } from './router-adapters';
    import { acmeTheme } from './theme';

    const themeCss = themeToCss(acmeTheme);
    const config = { managedModelsEnabled: true };

    // Mount inside the router: `navigation` calls its hooks.
    export function Providers({ children }: { children: ReactNode }) {
      const [queryClient] = useState(() => new QueryClient());
      return (
        <QueryClientProvider client={queryClient}>
          <UiProvider link={RouterLink} navigation={navigation} config={config}>
            <IconProvider>
              <style href="acme-theme" precedence="default">{themeCss}</style>
              {children}
              <Toaster />
            </IconProvider>
          </UiProvider>
        </QueryClientProvider>
      );
    }
    ```

    React 19 会将带有 `href` 和 `precedence` 属性的 `<style>` 标签自动提升（Hoist）到 `<head>` 中。Next.js 宿主请直接透传 `next/link` 和 `next/navigation` 的 Hooks，无需做任何修改。

3. **将您的会话列表放入侧边栏**

    ```tsx title="src/project-shell.tsx"
    import { SessionIdsProvider } from '@kortix/ui';
    import {
      Sidebar,
      SidebarContent,
      SidebarGroup,
      SidebarHeader,
      SidebarInset,
      SidebarMenu,
      SidebarMenuButton,
      SidebarMenuItem,
      SidebarProvider,
      SidebarRail,
    } from '@kortix/ui/sidebar';
    import { ProjectSessionList } from '@kortix/ui/workspace';
    import { FolderSimpleIcon, NavigationArrowIcon, SquaresFourIcon } from '@phosphor-icons/react';
    import { Link, Outlet, useLocation, useParams } from 'react-router-dom';

    export function ProjectShell() {
      const { projectId = '', sessionId } = useParams();
      const { pathname } = useLocation();
      const nav = [
        { to: `/projects/${projectId}`, label: 'New session', icon: NavigationArrowIcon },
        { to: `/projects/${projectId}/files`, label: 'Files', icon: FolderSimpleIcon },
        { to: '/', label: 'All projects', icon: SquaresFourIcon },
      ];
      return (
        <SessionIdsProvider projectId={projectId} sessionId={sessionId}>
          <SidebarProvider>
            <Sidebar collapsible="offcanvas" variant="inset">
              <SidebarHeader className="px-3 py-2 text-sm font-medium">Acme Agents</SidebarHeader>
              <SidebarContent className="min-h-0">
                <SidebarGroup className="py-0">
                  <SidebarMenu>
                    {nav.map(({ to, label, icon: Icon }) => (
                      <SidebarMenuItem key={to}>
                        <SidebarMenuButton asChild isActive={pathname === to}>
                          <Link to={to}>
                            <Icon />
                            <span>{label}</span>
                          </Link>
                        </SidebarMenuButton>
                      </SidebarMenuItem>
                    ))}
                  </SidebarMenu>
                </SidebarGroup>
                {/* The Kortix session list: sections, status, rename, delete, live updates. */}
                <SidebarGroup className="min-h-0 flex-1 flex-col py-0">
                  <ProjectSessionList projectId={projectId} />
                </SidebarGroup>
              </SidebarContent>
              <SidebarRail />
            </Sidebar>
            <SidebarInset className="h-dvh min-h-0 overflow-hidden">
              <Outlet />
            </SidebarInset>
          </SidebarProvider>
        </SessionIdsProvider>
      );
    }
    ```

4. **添加页面**

    ```tsx title="src/pages.tsx"
    import { useProjects, useSession } from '@kortix/sdk/react';
    import { Card, CardContent, CardHeader, CardTitle } from '@kortix/ui';
    import Loading from '@kortix/ui/loading';
    import { ProjectFilesView, ProjectHome, SessionWorkspace } from '@kortix/ui/workspace';
    import { Link, useParams } from 'react-router-dom';

    export function ProjectsPage() {
      const projects = useProjects();
      return (
        <main className="mx-auto flex max-w-xl flex-col gap-4 p-8">
          <Card>
            <CardHeader>
              <CardTitle>Projects</CardTitle>
            </CardHeader>
            <CardContent className="flex flex-col gap-1">
              {projects.isLoading && <Loading />}
              {projects.data?.map((project) => (
                <Link
                  key={project.project_id}
                  to={`/projects/${project.project_id}`}
                  className="hover:bg-accent rounded-md px-2 py-1.5"
                >
                  {project.name}
                </Link>
              ))}
            </CardContent>
          </Card>
        </main>
      );
    }

    // The project home: sending creates the session and opens it.
    export function HomePage() {
      const { projectId = '' } = useParams();
      return <ProjectHome projectId={projectId} />;
    }

    // The session: the thread and the side panel (files, viewer, terminal, browser).
    export function SessionPage() {
      const { projectId = '', sessionId = '' } = useParams();
      const session = useSession(projectId, sessionId);
      return <SessionWorkspace key={sessionId} session={session} />;
    }

    // The project's git-backed files. It fills its parent.
    export function FilesPage() {
      const { projectId = '' } = useParams();
      return <ProjectFilesView projectId={projectId} />;
    }
    ```

    `ProjectHome` 接收 `beforeSend` 用于拦截（控制）消息的发送，以及 `onSend` 用于完全替换默认的发送行为。

5. **登录与路由配置**

    ```tsx title="src/main.tsx"
    import { Button, Input, Label, setUiRoutes } from '@kortix/ui';
    import { StrictMode, useEffect, useState } from 'react';
    import { createRoot } from 'react-dom/client';
    import { createBrowserRouter, Outlet, RouterProvider } from 'react-router-dom';

    import './app.css';
    import './shell-row';
    import { authSession, kortix } from './kortix';
    import { FilesPage, HomePage, ProjectsPage, SessionPage } from './pages';
    import { ProjectShell } from './project-shell';
    import { Providers } from './providers';

    function SignIn() {
      const [signedIn, setSignedIn] = useState(authSession.current() !== null);
      const [email, setEmail] = useState('');
      const [password, setPassword] = useState('');
      const [error, setError] = useState<string | null>(null);

      useEffect(() => authSession.subscribe((session) => setSignedIn(session !== null)), []);

      if (signedIn) return <Outlet />;
      return (
        <form
          className="mx-auto flex max-w-sm flex-col gap-3 p-8"
          onSubmit={async (event) => {
            event.preventDefault();
            setError(null);
            try {
              const { session, user } = await kortix.auth.signInWithPassword({ email, password });
              await authSession.set(session, user);
            } catch (err) {
              setError(err instanceof Error ? err.message : 'Sign-in failed');
            }
          }}
        >
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" value={email} onChange={(event) => setEmail(event.target.value)} />
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" value={password} onChange={(event) => setPassword(event.target.value)} />
          {error && <p className="text-destructive text-sm">{error}</p>}
          <Button type="submit" disabled={!email || !password}>
            Sign in
          </Button>
        </form>
      );
    }

    // This app serves `project`, `files` and `session` at their default paths.
    // Every link to another page is hidden.
    setUiRoutes({
      sessions: () => null,
      drive: () => null,
      apps: () => null,
      rooms: () => null,
      goals: () => null,
      artifacts: () => null,
      space: () => null,
      members: () => null,
      sandboxSettings: () => null,
      customize: () => null,
      admin: () => null,
      memory: () => null,
    });

    const router = createBrowserRouter([
      {
        element: (
          <Providers>
            <SignIn />
          </Providers>
        ),
        children: [
          { path: '/', element: <ProjectsPage /> },
          {
            path: '/projects/:projectId',
            element: <ProjectShell />,
            children: [
              { index: true, element: <HomePage /> },
              { path: 'files', element: <FilesPage /> },
              { path: 'sessions/:sessionId', element: <SessionPage /> },
            ],
          },
        ],
      },
    ]);

    createRoot(document.getElementById('root')!).render(
      <StrictMode>
        <RouterProvider router={router} />
      </StrictMode>,
    );
    ```

    `./app.css` 包含来自 [Add the styles（添加样式）](#添加样式) 的导入。`./shell-row` 是来自 [Replace one tool row（替换工具调用行）](#替换单个工具调用行) 的行组件。

- 更多数据需通过 [React hooks（React 钩子）](#react-hooks) 中的 Hooks 获取，例如 `useProjectSessions`、`useProjectApps` 和 `useProjectTriggers`。
- 绝不要自行 `fetch` OpenChatly API。如果 SDK 缺少您需要的调用，请将其作为 SDK 缺陷（Gap）上报。
- 三种白标（White-label）产品形态遵循以下结构：
  - Lumen Workspace：采用自身主题的 OpenChatly 工作区，支持直连模式（浏览器保存凭证）或包装器模式（由其自身服务器保存凭证）。
  - Team Console：基于单一账户的静态 [OpenChatly App](/docs/zh/guide#应用apps)，以查看器（Viewer）身份登录。
  - Lumen：拥有独立用户、数据和计费体系的产品，以 OpenChatly 作为 Agent 后端。

### 面向 Agent 的配置

`@kortix/ui` 在 `packages/ui/skills/kortix-ui/SKILL.md` 提供了 `kortix-ui` 技能。每个 OpenChatly 项目都会将其作为托管技能（Managed skill）获取。当 `kortix.yaml` 中的 `skills` 授权为 `all` 或显式指定了 `kortix-ui` 时，Agent 会加载该技能。它指导 Agent 如何配置该包、组合哪些组件、禁用哪些基础元素以及如何验证页面。其参考文档如下：

| 文件（File） | 包含内容（Holds） |
| --- | --- |
| `references/custom-dashboard.md` | 将本节中的仪表盘构建流程整理为一份检查清单：安装、客户端、路由适配器、主题、侧边栏、页面、自定义工具行、App 登录、验证。 |
| `references/modules.md` | 每个入口的所有导出名称、对应的 Props 及一个示例。 |
| `references/theming.md` | 所有主题键（Theme key）。 |

在 OpenChatly 会话中，Agent 可通过 `kortix system-skills file kortix-ui references/custom-dashboard.md` 读取参考文档。在您自己的编码 Agent 使用 `@kortix/ui` 编写 UI 之前，请确保它已加载 `SKILL.md` 及其参考文档。

## SDK 参考（SDK reference）

本节供查阅使用。每个表格列出了名称、参数、调用的返回值以及可能抛出的错误。[SDK](#sdk)、[Sessions from code（通过代码管理会话）](#从代码管理会话)、[Projects from code（通过代码管理项目）](#通过代码管理项目projects-from-code) 和 [React](#react) 中的指南展示了各个调用的实际用法。

本节约定：

- `kortix` 指代通过 `createKortix` 创建的客户端。`p` 代表 `kortix.project(projectId)`。`s` 代表 `kortix.session(projectId, sessionId)`。
- 路由路径相对于 `backendUrl`（以 `/v1` 结尾）。[REST 参考](#rest-api) 列出了每个路由。
- 调用失败会抛出 `ApiError`。`status` 为 HTTP 状态码，`code` 为 API 错误码，`details` 为解析后的响应体，`detail` 为 FastAPI 的错误字段。错误目录详见 [Sessions from code > Errors and retries（通过代码管理会话 > 错误与重试）](#错误与重试errors-and-retries)。
- 创建句柄（如 `kortix.project(id)`、`kortix.session(pid, sid)`、`p.connector(slug)`）不会发送任何网络请求。

### 入口与稳定性（Entry points and stability）

| 导入路径（Import） | 状态（Status） | 包含内容（What it holds） |
| --- | --- | --- |
| `@kortix/sdk` | 稳定（Stable） | 客户端及所有不依赖框架的模块。不导入 React 和任何 `node:*` 模块。可在浏览器、Node 18 及以上版本、Bun 和边缘运行时（Edge runtimes）中运行。 |
| `@kortix/sdk/react` | 稳定（Stable） | React Hooks。这是唯一导入 React 的入口。对等依赖（Peers）：`react`、`@tanstack/react-query`。 |
| `@kortix/sdk/server` | 稳定（Stable） | 适用于 Node 和 Bun 的服务端辅助工具（见下表）。导入了 `node:async_hooks`。绝不要将其打包到浏览器端。 |
| `@kortix/sdk/genui` | 稳定（Stable） | 生成式 UI（Generative UI）解析器与文本渲染器。对等依赖：`zod`、`@openuidev/lang-core@0.3.1`。参见 [Generative UI（生成式 UI）](#生成式-uigenerative-ui)。 |
| `@kortix/sdk/genui/fence` | 稳定（Stable） | `splitGenui`、`separateGenuiClosers`、`genuiVersionOf`、`genuiVersionFromClassName`。不加载 `zod`。 |
| `@kortix/sdk/genui/react` | 稳定（Stable） | `GenuiBlock`、`useGenuiParse`、`defaultGenuiComponents`。 |
| `@kortix/sdk/wire-message-id` | 稳定（Stable） | 在一个无导入的模块中提供 `mintWireMessageId` 和 `WIRE_MESSAGE_ID`。根入口同样导出这些名称。 |
| `@kortix/sdk/workspace-search` | 稳定（Stable） | `createWorkspaceSearchClient` 及其排序辅助工具（参见 [Workspace search（工作区搜索）](#工作区搜索workspace-search)）。 |
| `@kortix/sdk/capture-rules` | 稳定（Stable） | OpenChatly 捕获（Capture）相关常量：`CAPTURE_LAYERS`、`CAPTURE_EXCLUSION_GROUPS`、`CAPTURE_RETENTION_LIMITS`、`CAPTURE_FRAME_INTERVALS_MS`、`CAPTURE_MAX_HEIGHTS`、`CAPTURE_DEVICE_DEFAULTS`、`normalizeCaptureAppId`、`normalizeCaptureDomain`。 |
| `@kortix/sdk/internal/*` | 内部（Internal） | OpenChatly Web 应用的状态存储，例如 `sync-store`、`server-store`、`sandbox-connection-store`、`opencode-pending-store`、`idb-sync-cache`、`diagnostics-store`、`managed-storage`。不受语义化版本（Semver）保护。请勿导入。前四个存储已废弃。 |
| 其他子路径 | 已废弃（Deprecated） | 在下个大版本前仍可解析的别名。参见 [Deprecated names（已废弃的名称）](#废弃的名称deprecated-names)。 |

稳定的入口受语义化版本（Semver）保护。指向 `dist/` 的深层路径不受 Semver 保护。

#### `@kortix/sdk/server`


| 导出项（Export） | 功能说明（What it does） |
| --- | --- |
| `createScopedKortix(config)` | 类似 `createKortix` 的客户端，但其所有调用（包括 `project()` 和 `session()` 句柄上的调用）都仅使用此配置。请为每个请求创建一个实例。参见 [Serve many users from one backend（从单一后端服务多用户）](#从单一后端服务多用户)。 |
| `runWithKortix(config, fn)` | 在请求作用域配置（Node `AsyncLocalStorage`）下运行 `fn`。 |
| `getScopedConfig()` | 获取当前作用域内的配置；在 `runWithKortix` 外部调用时返回 `undefined`。 |
| `forwardKortixRequest(options)` | 使用上游令牌将单个同源请求转发至 OpenChatly API。它会剥离宿主凭证并保持流式响应体。上游请求失败时返回 `502` 及 `{ error: 'Upstream request failed' }`。 |
| `createKortixAuth(options)` | 为您的应用提供 OpenChatly 登录功能：支持带 PKCE 的 OAuth 2.1、加密会话 Cookie、令牌刷新、登出、`/me` 接口以及同源 `/proxy`。参见 [Sign in with OpenChatly（使用 OpenChatly 登录）](#使用-openchatly-登录)。 |
| `readAppViewer(request, options?)` | 在 OpenChatly App 内部：验证已签名的查看器（Viewer）请求头并返回查看器对象，验证失败则返回 `null`。 |
| `createAppViewerKortix(request, options)` | 在 OpenChatly App 内部：创建一个以查看器身份调用 OpenChatly API 的客户端。 |
| `createKortixAppGuard(options)` | App 的查看器解析器。`requireViewer` 和 `requireGroup` 会返回查看器对象或 `Response`。参见 [Know the viewer in an OpenChatly App（在 OpenChatly App 中识别查看器）](#识别-openchatly-app-中的查看者)。 |
| `KortixAuthError`, `AppViewerUnavailableError` | `createKortixAuth` 及 App 查看器辅助工具抛出的错误类型。 |
| `safeReturnTo` | 仅接受同源返回路径，拒绝其他任何值。 |
| `APP_VIEWER_HEADER`, `APP_VIEWER_TOKEN_HEADER`, `APP_VIEWER_SECRET_ENV`, `KORTIX_SESSION_SENTINEL` | 相关的请求头和环境变量名称。 |

### 客户端（The client）

`createKortix(config)` 返回客户端实例。其配置选项详见 [Create the client（创建客户端）](#创建客户端)。

| 成员（Member） | 访问范围（What it reaches） | 路由（Routes） |
| --- | --- | --- |
| `config` | 当前生效的配置。 | 无 |
| `auth` | 无头注册、登录、魔术链接、OTP、OAuth、SSO、MFA、令牌刷新、登出，以及令牌存储 `auth.session(options)`。 | `/auth/…` |
| `accounts` | 账户、成员、邀请、API 密钥、已连接应用、账户密钥、品牌配置、审计日志。 | `/accounts/…` |
| `iam` | 权限分配、角色、权限、用户组、Agent 身份、OAuth 客户端、权限探测。 | `/accounts/{accountId}/iam/…` |
| `accountInvites` | 账户邀请中被邀请方的操作接口。 | `/account-invites/…` |
| `projects` | 项目列表、创建、初始化、模型访问权限及自定义模型提供商。 | `/projects/…` |
| `project(projectId)` | [项目句柄](#项目句柄the-project-handle)。 | `/projects/{projectId}/…` |
| `session(projectId, sessionId)` | [会话句柄](#会话句柄the-session-handle)。 | `/projects/{projectId}/sessions/{sessionId}/…` |
| `connectors` · `connector(slug)` | 使用携带项目信息的令牌（如会话令牌）调用连接器。方法与 `p.connectors` 的数据平面部分及 `p.connector(slug)` 相同。 | `/connectors/…` |
| `github` | 按账户划分的 GitHub App 安装与仓库链接。 | `/projects/github/…` |
| `gitBackend` | 托管 OpenChatly 管理仓库的实例 Git 后端。 | `/projects/git/backend` |
| `billing` | 套餐、积分余额、交易记录、用量、按会话用量、订阅。 | `/billing/…` |
| `sandboxShares` | 单个沙箱端口的公开分享链接。 | `/p/share` |
| `connectStatus()` | 检查当前实例是否配置了托管的 OAuth 连接提供商。 | `/connectors/connect-status` |
| `marketplace` | 公开的市场目录及其来源。 | `/marketplace/…` |
| `capture` | 单账户的 OpenChatly 捕获（Capture）、设备登录审批，以及调用者自身的读取操作。 | `/accounts/{accountId}/capture/…`、`/capture/…` |
| `notifications` | 调用者的通知收件箱与偏好设置、Web Push，以及原生设备的推送令牌。 | `/notifications/…` |
| `mobileClientPolicy()` | `{ minimum_version, store_url_ios, store_url_android }`。字段为 `null` 表示运营方未设置值。无需令牌。 | `/clients/mobile` |
| `validateToken()` | 校验粘贴的 API 密钥。绝不抛出异常。 | `/accounts/me` |
| `runtime()` | 逃生舱：获取进程级活跃沙箱的运行时客户端。在作用域客户端上调用会抛出异常。请改用 [会话句柄](#会话句柄the-session-handle)。 | sandbox |

#### `kortix.projects`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `list()` · `listForAccount(accountId)` | 调用者可打开的项目 · 指定账户下的项目。 |
| `get(projectId)` · `detail(projectId)` | 项目摘要 · 包含配置的完整详情。 |
| `provision(input)` | 在新的 OpenChatly 托管仓库上创建新项目。入参：`{ name, account_id?, seed_starter?, starter_template?: 'general-knowledge-worker' \| 'minimal', marketplace_items?, source_item_id?, default_branch?, icon?, icon_glyph?, idempotency_key? }`。 |
| `create(input)` · `createRepo(input)` | 在现有 `repo_url` 上创建项目 · 在新的 GitHub 仓库上创建项目。 |
| `update(projectId, input)` · `archive(projectId)` | 修改设置 · 归档项目。 |
| `llmCatalog(projectId)` · `modelPicker(projectId)` | 完整的模型目录 · 用于模型选择器的精简列表。 |
| `modelAccess(projectId)` · `setModelAccess(projectId, { target: 'provider' \| 'model', id, enabled })` | 读取 · 开启或关闭某个提供商或模型。提供商 ID `kortix` 代表 OpenChatly 托管模型。禁用当前默认模型会返回 `409 cannot_disable_default`。 |
| `customLlmProviders(projectId)` | 项目的所有自定义 OpenAI 兼容提供商，类型为 `CustomLlmProvider[]`。遗留的仅含密钥的行会显示 `configured: false`。 |
| `setCustomLlmProvider(projectId, providerId, { name, base_url, models })` | 创建或替换自定义提供商。每个 `models` 条目为 `{ id, name, context?, output?, attachment?, reasoning? }`；未提供的字段将从端点的 `GET /models` 获取。若无效将拒绝并返回 `400` `invalid_body`、`reserved_provider_id` 或 `unsafe_base_url`。 |
| `deleteCustomLlmProvider(projectId, providerId)` | 删除提供商定义，随后删除其 `CUSTOM_<ID>_API_KEY` 项目密钥。定义或密钥缺失不会报错。 |
| `sandboxHealth(projectId)` · `sandboxTemplates(projectId)` | 沙箱构建健康状态 · 构建模板。 |
| `sessions(projectId)` · `createSession(projectId, input?)` | 等同于 `p.sessions.list()` · `p.sessions.create()`。 |

`idempotency_key`（幂等键）为 1 到 200 个字符的 `A–Z a–z 0–9 . _ : -`。每次创建尝试请发送一个新值。使用相同密钥重复请求会返回首次创建的项目（`201`，相同的 `project_id`）。若在首次调用执行期间重复请求，会返回 `409 provision_in_flight`：请使用相同密钥重试。

#### `kortix.github` 和 `kortix.gitBackend`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `github.getInstallation(accountId)` · `github.listInstallations(accountId)` | 账户的 GitHub App 安装 · 用户可访问的安装。 |
| `github.listLinkableInstallations(input)` · `.linkInstallation(input)` · `.saveInstallation(input)` · `.deleteInstallation(accountId, installationId?)` | GitHub 用户可链接的安装 · 链接 · 记录 · 取消链接。 |
| `github.listRepositories(accountId, installationId?)` · `.listRepositoryBranches(…)` | 该安装可见的仓库 · 它们的分支及默认分支。 |
| `github.linkRepository(input)` | 将仓库作为项目导入。 |
| `github.replaceProjectRepository(input)` | 将项目指向另一个仓库。过期的 `expected_repo_url` 会返回 `409`。新会话将使用新仓库，运行中的会话保留其当前检出。 |
| `github.storeUserToken(input)` | 存储用户的 GitHub 授权。在个人 GitHub 账户中创建仓库时必须提供。 |
| `gitBackend.get()` | `{ configured, kind: 'app' \| 'pat' \| null, owner }`。任何已登录用户均可读取。 |
| `gitBackend.repositories({ search?, limit? })` | 该所有者下的仓库。仅限自托管运营方调用；其他调用者会收到 `403`。 |

#### `kortix.marketplace` 和 `kortix.sandboxShares`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `marketplace.items(options?)` · `.item(id)` · `.itemFile(id, path)` | 浏览目录 · 单个条目 · 条目的某个文件。 |
| `marketplace.marketplaces()` · `.featured()` | 所有市场 · 精选市场。 |
| `marketplace.sources.list()` · `.add(input)` · `.remove(id)` | 市场来源管理。 |
| `sandboxShares.list(sandboxId)` · `.create({ sandboxId, port, ttl?, label? })` · `.revoke(sandboxId, token)` | 单个沙箱端口的公开分享链接管理。 |

### 账户、IAM、计费与通知

#### `kortix.auth`

| 成员（Member） | 功能说明（What it does） |
| --- | --- |
| `signUp` · `signInWithPassword` · `sendMagicLink` · `verifyOtp` · `signInWithProvider` · `exchangeCode` · `signInWithSso` | 登录流程。 |
| `refresh` · `resetPassword` · `updatePassword` · `updateUserMetadata` · `user` · `signOut` | 令牌与账户维护。 |
| `mfa.enroll` · `mfa.challenge` · `mfa.verify` · `mfa.unenroll` | 多因素认证（MFA）。 |
| `session(options)` | 令牌存储。它通过您的存储适配器保存令牌，并在令牌过期前 60 秒自动刷新。请将其 `getToken` 方法传递给 `createKortix`。 |

参数、`HeadlessAuthError` 错误码及限制详见 [Sign users in headlessly（无头模式用户登录）](#无头模式登录用户)。

#### `kortix.accounts`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `list()` · `get(accountId)` · `create({ name })` · `updateName(accountId, name)` · `leave(accountId)` | 调用者所属的账户。 |
| `members(accountId)` · `invite(accountId, input)` · `updateMemberRole(accountId, userId, role)` · `removeMember(accountId, userId)` | 成员及其账户角色。 |
| `invites(accountId)` · `cancelInvite(accountId, inviteId)` · `resendInvite(accountId, inviteId)` | 待处理的邀请。 |
| `tokens.list(accountId?, { mine? })` · `tokens.create({ accountId?, name, expiresAt?, projectId? })` · `tokens.revoke(tokenId, accountId?)` | 个人访问令牌（`kortix_pat_…`）。`mine: true` 仅列出调用者自己的密钥。`projectId` 可将密钥绑定到特定项目。 |
| `connectedApps.list()` · `connectedApps.revoke(…)` | 用户已授权的 OAuth 和 MCP 客户端（跨所有账户）。路由：`/oauth/grants`。 |
| `secretResources.list` · `.create` · `.rotate` · `.retry` · `.remove` · `.grant` · `.revoke` · `.setAccess` | 账户级别的提供商密钥及允许使用它们的项目。 |
| `branding.get(accountId)` · `.update(accountId, { app_name })` · `.uploadAsset(accountId, kind, file)` · `.removeAsset(accountId, kind)` · `.reset(accountId)` | 组织品牌配置。`kind` 可选值：`logo`、`icon`、`favicon`、`logo_dark`、`icon_dark`、`favicon_dark`。 |
| `audit.log(accountId, filters?)` · `audit.export(accountId, { format: 'csv' \| 'jsonl', …filters })` | 审计日志，可按项目、会话、操作者、来源、结果、请求、资源、操作或时间进行过滤 · 将相同的事件导出为文件。 |
| `audit.activity(accountId, { since?, until?, projectId?, actor?, client?, actorType?, credentialKind? })` | 按 UTC 日统计的活动：每个用户的活跃天数、独立活跃小时数及事件。`client: 'browser'` 仅保留网页端用户的活动。 |
| `audit.webhooks.list` · `.create` · `.update` · `.remove` | 用于将审计事件流式传输至 SIEM 的签名 Webhooks。 |

#### `kortix.iam`

权限分配（Assignment）是一条授权记录：包含一个主体（`user`、`group`、`service_account`、`pending` 或 `project`）、一个角色、一个作用域（`account` 或特定 `project`）、一个可选对象（`agent`、`skill`、`secret`、`app`、`trigger` 或 `connection`）以及一个可选的过期时间 `expiresAt`。

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `assignments.list(accountId, filter?)` | 实时权限分配。过滤条件：`principalType` 配合 `principalId`、`scopeType`、`scopeId`、`objectType`、`objectId`、`roleId`、`includeExpired`。 |
| `assignments.create(accountId, { principal, scope, object?, expiresAt?, roleId \| roleKey })` · `assignments.revoke(accountId, assignmentId)` | 授权 · 撤销。`roleKey` 用于指定内置角色：`owner`、`admin`、`member`、`manager`、`agent-user`。 |
| `permissions.list(accountId)` · `permissions.forRole(…)` | 权限目录（`action`、`scope_type`、`resource_type`、`delegable`、`description`、`area`、`level`、`implies`） · 特定角色的权限。 |
| `roles.list` · `.create` · `.update` · `.setPermissions` · `.remove` · `.usage` | 自定义角色。若账户未开通 `rbac` 权益，API 将返回 `402 entitlement_required`。 |
| `groups.list` · `.get` · `.create` · `.update` · `.remove` · `groups.members.list` · `.add` · `.remove` | 用户组及其成员。 |
| `agentIdentities(accountId)` | Agent 主体，用于将角色绑定到 Agent。 |
| `oauthClients.list` · `.get` · `.create` · `.update` · `.rotateSecret` · `.remove` | 使用 OpenChatly 登录的客户端。API 仅在 `create` 和 `rotateSecret` 时返回一次密钥。 |
| `can(accountId, userId, { action, resourceType?, resourceId? })` · `canBatch(accountId, userId, probes)` | 检查主体是否可执行某项操作 · 在单次请求中检查多项操作，结果按输入顺序返回。未知操作会返回 `400`。 |

探测辅助工具（从根入口导出）：

| 名称（Name） | 功能说明（What it does） |
| --- | --- |
| `PROJECT_ACTIONS` | API 可响应的所有项目操作。示例：`PROJECT_ACTIONS.PROJECT_GITOPS_MERGE` 对应 `project.gitops.merge`。 |
| `TRIGGER_CONTROL_ACTIONS` · `triggerControlsFrom(cans)` | 触发器探测 · `{ canCreate, canFire, canUpdate, canDelete }`。创建、更新和删除还需具备 `project.write` 权限。 |
| `REVIEW_CONTROL_ACTIONS` · `changeRequestControlsFrom(cans)` | 评审探测 · `{ canOpen, canMerge, canClose }`。开启需要 `project.write` 和 `project.gitops.push`。合并需要 `project.write` 和 `project.gitops.merge`。关闭和重新开启需要 `project.write`。 |
| `reviewVerdictAllowed(item, verdict, cans)` | 检查是否可对某个评审项给出特定裁定。批准变更请求会触发合并，因此遵循 `canMerge`。其他裁定需要 `project.write` 和 `project.review.act`。 |

连接器调用会携带 `can_resolve`（在 `SessionAuditAction` 上）或 `canResolve`（在评审项上）。仅当该值不为 `false` 时才显示“批准”和“拒绝”按钮。若会话由 API 令牌或服务账户发起，`resolvers` 为 `managers`，否则为 `managers_and_launcher`。

#### `kortix.accountInvites`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `listMine()` | 发送给调用者邮箱的待处理邀请。 |
| `describe(inviteId)` · `accept(inviteId)` · `decline(inviteId)` | 对单个邀请执行操作。这些操作无需账户成员身份。 |
| `acceptAndLand(inviteId, invite?)` | 接受邀请并返回 `{ accepted, landing }`。`landing` 为邀请授予的第一个项目 `{ kind: 'project', projectId, accountId }`，或 `{ kind: 'account', accountId }`。请传入您读取到的邀请对象：若接受后未授予任何权限，则默认进入邀请中指定的第一个项目。 |

`accountInviteLanding(accepted, invite?)`（从根入口导出）对先前已接受的邀请应用相同规则，无需发送网络请求。

#### `kortix.billing`

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `accountState(accountId?)` · `accountStateMinimal(accountId?)` | 套餐、积分余额及限制 · 精简形式。 |
| `creditBreakdown(accountId?)` | 按桶（Bucket）划分的积分余额。 |
| `transactions(params?)` · `transactionsSummary(params?)` | 交易历史 · 汇总。 |
| `usageHistory(params?)` · `usageRollup(params?)` | 历史用量 · 按模型、提供商或日期分组的用量。 |
| `sessionCosts.list({ accountId?, projectId?, limit?, offset? })` · `sessionCosts.get(sessionId, options?)` | 按会话的用量记录 · 单个会话的模型与算力账本。 |
| `tierConfigurations()` | 命名的套餐层级及允许的 `monthlyUsd` 范围。 |
| `setPlan({ monthlyUsd, successUrl, cancelUrl, locale?, accountId? })` | 订阅或更改积分套餐。解析为 `{ status: 'checkout_created', checkout_url }`（需重定向至该链接）、`{ status: 'updated' \| 'unchanged' }` 或 `{ status: 'payment_pending', client_secret }`。React 中使用：`useSetBillingPlan()`。 |
| `previewPlan({ monthlyUsd, accountId? })` | 预览 `setPlan` 的效果，不产生实际更改。 |
| `acceptEnterpriseOffer(…)` | 获取当前开放的企业版报价的 Stripe Checkout 链接。需要 `billing.write` 权限。无可用报价时返回 `404`，报价已开票时返回 `409`。 |
| `contactSales(…)` | 向 OpenChatly 销售团队发送联系请求。 |
| `subscription.createPortalSession(returnUrl, accountId?)` · `.cancel(feedback?, accountId?)` · `.reactivate(accountId?)` | 管理订阅。 |
| `credits.purchase(input)` · `credits.autoTopupSettings(accountId?)` · `credits.configureAutoTopup(input)` | 购买积分 · 读取和设置自动充值。 |

`canOfferTopup(state)` 和 `canManageBilling(state)`（从根入口导出）用于读取账户状态。仅当套餐允许购买积分且调用者有权更改计费时，`canOfferTopup` 才返回 `true`。当 `state` 为 `undefined` 或 `null` 时，两者均返回 `false`。已废弃的计费调用详见 [Deprecated names（已废弃的名称）](#废弃的名称deprecated-names)。

#### `kortix.notifications`

除 `releaseDeviceToken` 外，每个方法都需要个人凭证。服务账户调用会收到 `403` 错误。


| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `registerDeviceToken(input)` · `unregisterDeviceToken(token)` · `releaseDeviceToken(token, { backendUrl? })` | 原生应用的推送令牌。`releaseDeviceToken` 无需凭证。 |
| `list(…)` · `markRead(…)` | 收件箱及其已读状态。 |
| `preferences()` · `updatePreferences(…)` | 按类型设置的推送与邮件偏好。 |
| `webPushPublicKey()` · `registerWebPushSubscription(…)` · `unregisterWebPushSubscription(…)` | 当前浏览器的 Web Push 配置。 |

会话推送会发送到创建该会话的用户的手机上。当对话回合结束或失败，或者 Agent 提问或请求权限时，会触发推送。只要该用户的某个标签页持有该会话的存在租约（`s.presence`），就不会发送推送。

#### `kortix.capture`

Capture（捕获/录屏）归属于账户。`kortix.capture.account(accountId)` 用于绑定特定账户。当账户关闭 Capture 时，所有账户级调用均返回 `403 capture_disabled`。读取其他成员的数据需要 `capture.read_all` 权限，并会写入一条 `capture.member_view` 审计事件。写入操作需要 `capture.manage` 权限。

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `account(id).workspace.get()` · `.workspace.setEnabled(on)` | `{ account_id, enabled, can_read_all, can_manage, updated_at }` · 开启或关闭 Capture。 |
| `account(id).devices.list({ userId?, scope? })` | 带有实时状态的设备：`recording`（录制中）、`paused`（已暂停）、`permission_missing`（缺少权限）、`not_recording`（未录制），或超过 120 秒无状态上报的 `offline`（离线）。`scope: 'account'` 会列出所有成员的设备。 |
| `account(id).devices.revoke(deviceId)` · `.devices.link(deviceId, userId \| null)` · `.devices.assetUrl(deviceId, name)` | 撤销设备令牌 · 将设备链接到成员或取消链接 · 获取操作截图的 5 分钟有效签名 URL。 |
| `account(id).enrollment.tokens.list()` · `.tokens.create(input)` · `.tokens.revoke(tokenId)` | IT 部署（Rollout）令牌。 |
| `account(id).enrollment.list({ status? })` · `.enrollment.approve(enrollmentId, userId?)` · `.enrollment.deny(enrollmentId)` | 提交了部署令牌的计算机。 |
| `account(id).policy.get()` · `.policy.set(policy)` | 捕获层级、隐私、保留策略、录制及通知。 |
| `account(id).storage.get()` · `.storage.set(input)` | 账户保存录制的存储位置：托管存储或自有 S3 存储桶。 |
| `account(id).timeline.get(query?)` · `.timeline.items(query?)` · `.timeline.days(query?)` | 某个 UTC 日或某个时间窗口（最长 31 天）内的应用与窗口运行记录 · 窗口内的帧、操作与音频（各 500 条） · 包含录制项的日期列表（按最新排序）。 |
| `account(id).search({ q, kinds?, app?, from?, to?, limit?, userId?, scope? })` | 对屏幕文本、操作和音频进行全文搜索（按最新排序）。 |
| `account(id).frame(frameId, { userId? })` · `.media(chunkId, { userId? })` | 包含屏幕文本的单帧及 5 分钟有效的视频签名 URL · 录制项的视频与音频签名 URL。 |
| `deviceGrant(userCode)` · `approveDevice(userCode, accountId?)` · `denyDevice(userCode)` | 设备登录流程中用户侧的操作。 |
| `me.search(query)` · `me.timeline(query)` · `me.frame(frameId)` | 读取令牌所代表的用户在当前账户下的数据。若凭证不代表任何个人，将收到 `403 capture_no_human`。 |

### 项目句柄（The project handle）

`kortix.project(projectId)` 返回 `p`。每个方法都已绑定了项目 ID。`p.session(sessionId)` 返回 [会话句柄](#会话句柄the-session-handle)。该句柄的任务指南详见 [Projects from code（通过代码管理项目）](#通过代码管理项目projects-from-code)。

#### 项目（Project）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `get()` · `detail()` · `update(input)` · `archive()` | 读取 · 包含配置的完整详情 · 修改设置 · 归档。 |
| `llmCatalog()` · `modelPicker()` · `modelAccess()` · `setModelAccess(change)` · `customLlmProviders()` · `setCustomLlmProvider(providerId, input)` · `deleteCustomLlmProvider(providerId)` · `sandboxHealth()` | 与 [`kortix.projects`](#kortixprojects) 相同，但已绑定项目 ID。 |
| `validateManifest(raw)` | 在服务端使用合并（Merge）所用的 Schema 验证 `kortix.yaml` 文本。 |
| `audit(options?)` | 项目的审计时间线。 |
| `skills.create(input)` · `skills.remove(…)` | 将技能写入默认分支 · 移除技能。整文件夹移除会包含用户编辑的内容；共享依赖将保留。 |
| `attachments.upload(…)` · `.delete(…)` · `.createController(options?)` | 提示词附件，以及用于跟踪编辑器上传状态的控制器。 |
| `onboardingComplete(…)` | 标记项目新手引导已完成。 |
| `updateFeatureFlag(key, enabled)` | 为项目设置功能标志（`PATCH /projects/{projectId}/features`）。`key` 为 `FEATURE_FLAG_KEYS` 之一。`enabled: null` 会清除覆盖设置。需要 `project.settings.write` 权限。 |
| `claudeSubscription.get()` · `.startLogin(target?)` · `.completeLogin(input)` · `.setToken(token, target?)` | 调用者的 Claude Pro 或 Max 账户。API 绝不返回令牌。 |
| `artifacts.activity(…)` · `artifacts.comments.*` | Artifact 活动与评论线程。参见 [Artifacts](#制品artifacts)。 |
| `connector(slug)` · `session(sessionId)` | 单个连接器句柄 · 会话句柄。 |

若请求的路由受控于已关闭的功能标志，将返回 `403`，并带有 `code: 'feature_disabled'` 和 `feature` 字段。可使用 `isFeatureDisabledError(error)` 进行测试。使用 `featureDisabledKey(error)` 读取标志键。

#### 会话（Sessions）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `sessions.list(options?)` | 以数组形式返回一页会话。 |
| `sessions.listPage(options?)` | 返回一页数据及 `next_cursor`。`null` 表示最后一页。游标仅对生成它的过滤条件有效。 |
| `sessions.create(input?)` | 创建会话。沙箱将在后台启动。字段说明：[Create a session（创建会话）](#创建会话)。 |

`list` 和 `listPage` 的选项（Options）：

| 选项（Option） | 取值（Values） |
| --- | --- |
| `scope` | `visible`（默认）或 `project`（管理员清单）。两者都会排除调用者无法打开的会话。 |
| `limit` · `cursor` | 1 到 `PROJECT_SESSION_PAGE_MAX_LIMIT`（200）行 · 上一页的 `next_cursor`。 |
| `parent` | `root`：顶级会话，每行带有 `child_count`。会话 ID：该会话的子会话。 |
| `startedBy` | `me`、`others` 或 `automated`。 |
| `createdBy` | 用户 ID：该用户发起的会话。 |
| `agent` | Agent 标识（Slug）：运行该 Agent 的会话。 |
| `updatedAfter` | ISO 8601 格式：在该时间或之后有活动的会话。 |
| `q` | 搜索调用者可打开的所有会话，1 到 200 个字符。 |
| `labels` | 包含所有指定标签的会话（精确匹配）。 |
| `view` | `pinned`、`archived` 或 `deleted`（可恢复的会话，每行带有 `restore_until`）。不指定 `view` 时，列表会排除调用者已归档的会话。 |

每行数据都带有 `parent_session_id` 和 `initiator: { type: 'member' | 'trigger' | 'channel' | 'api' | 'system', id, label }`。`sessionParentId(session)`（从根入口导出）用于读取父会话 ID。

#### 文件、Git 与变更请求

这些方法用于读写项目仓库。若需操作运行中会话内的文件，请使用 [`s.files`](#会话句柄the-session-handle)。

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `files.listDirectory({ ref?, path?, cursor?, limit? })` | 获取单层文件夹内容：`{ entries, truncated, next_cursor }`。不传 `cursor` 和 `limit` 时，单次响应最多包含 5,000 个条目。传入其中任一参数时，每页包含 `limit` 个条目（默认 500，最大 2,000）。当 `next_cursor` 为字符串时，请将其作为 `cursor` 传入。每一页读取的始终是首页的提交（Commit）。 |
| `files.list(options?)` | 递归获取指定路径下的所有文件，最多返回 1,000 个。截断的响应会带有 `X-Kortix-Truncated: 1` 标识。 |
| `files.read(path, ref?)` · `files.history(path, { ref?, limit?, skip? })` | 读取特定引用（Ref）下的文件 · 获取该文件的提交历史。 |
| `files.write({ path, ref, content, expected_revision })` | 仅在文件的 Blob 修订版本未发生变化时，才提交对文本文件的编辑。返回 `{ commit_sha }`。 |
| `files.search(query, { content?, ref?, limit? })` | 搜索文件名，或设置 `content: true` 搜索文件内容。内容匹配的结果会带有 `line_number`（行号）和 `line_text`（行文本）。 |
| `files.archive(ref, path?)` · `files.archiveRequest(ref, path?)` | 将归档下载为 `Blob` 对象 · 发起相同的下载请求，由宿主环境将其流式写入磁盘。 |
| `git.commits()` · `git.commit(sha)` · `git.commitDiff(sha)` | 提交日志 · 单个提交详情 · 该提交的差异（Diff）。 |
| `git.branches()` · `git.versionDiff(…)` | 分支列表 · 两个引用之间的差异。 |
| `git.inviteCollaborator(…)` | 邀请 GitHub 用户加入 OpenChatly 托管的仓库。 |
| `gitToken()` | 获取用于 OpenChatly 托管仓库的、全新的作用域推送令牌。若为自带仓库（Bring-your-own repository），将返回 `409` 错误。 |
| `changeRequests.list(status?, { limit?, cursor? })` · `.get(crId)` · `.diff(crId)` · `.mergePreview(crId)` | 读取变更请求。`list` 返回一页数据（按最新排序）：默认 50 条，最大 500 条。 |
| `changeRequests.open(input)` · `.update(crId, input)` · `.merge(crId, input?)` · `.close(crId, input?)` · `.reopen(crId, input?)` | 变更请求的生命周期管理。 |
| `changeRequests.requestChanges(crId, input)` | 记录反馈意见，并可将其发送给发起该变更的会话。 |

相关路由：`/projects/{projectId}/files`、`/commits`、`/branches`、`/version-diff`、`/change-requests`。详见 [Git](#git版本控制)。

#### 评审与审批（Review and approvals）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `review.list(params?)` | 获取一页评审收件箱（包含变更请求、审批、Agent 输出）：`{ review_items, next_cursor }`，默认 50 条，最大 200 条。排序：需您处理（Needs you）、等待中（Waiting）、已完成（Done）。过滤条件：`segment`、`kind`、`sessionId`。在两页之间被处理的条目可能会在后续页返回：请使用 `review_item_id` 作为行的主键。 |
| `review.get(id)` · `.submit(input)` · `.act(id, …)` · `.bulkAct(input)` · `.recoverChangeRequest(…)` | 获取单个条目（包括 `cr:<id>` 和待处理的 `call:<id>`） · 提交 · 处理单个 · 批量处理 · 恢复变更请求。 |
| `review.summary()` | `{ needs_you_total, needs_you_by_session }`，在服务端统计。适用于角标（Badge）展示，而非列表。 |
| `approvals.list(options?)` · `approvals.sessionsNeedingInput(options?)` | 等待决策的连接器调用 · 因等待某个调用或 Agent 提问而阻塞的会话，并附带每个会话的计数。 |
| `approvals.resolve(executionId, 'approve' \| 'deny', { note? })` | 处理单个调用。`note` 会作为指令发送给 Agent。 |

#### 密钥、令牌与设置链接（Secrets, tokens and setup links）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `secrets.list()` | 仅返回密钥元数据，绝不返回值。`status` 为共享值的状态，`mine.status` 为调用者自身值的状态。`'undecryptable'` 表示服务端无法解密：请重新写入该值。 |
| `secrets.upsert(input)` · `secrets.remove(name)` | 创建或更新仅可写入的值及其交付策略 · 删除。 |
| `secrets.setStrategy(identifier, 'runtime' \| 'egress' \| 'broker' \| 'denied', options?)` | 暴露方式：`runtime` 为环境变量，`egress` 在网络边缘注入，`broker` 使值保留在会话之外，`denied` 为不暴露。 |
| `secrets.broker(identifier, request)` | 使用密钥发送一个受策略约束的 HTTPS 请求。需要会话作用域的令牌。 |
| `secrets.setPersonal(name, { value?, active? })` · `secrets.removePersonal(name)` | 调用者自身的值，用于调用者的会话。`active: false` 会保留该值但使用共享值。 |
| `secrets.setGitCredential(input)` | 自带 Git 仓库（Bring-your-own git repository）的凭证。 |
| `secrets.listProviderOAuth()` · `.startProviderOAuth(…)` · `.pollProviderOAuth(…)` · `.removeProviderOAuth(provider)` | 通过设备码流程（Device-code flow）进行的模型提供商订阅登录。 |
| `tokens.list()` · `tokens.create(input?)` · `tokens.revoke(tokenId)` | 项目 API 密钥。OpenChatly 还会为每个会话生成一个 `KORTIX_TOKEN`。 |
| `setupLinks.requestSecret(input)` · `setupLinks.requestSecret(input)` | 生成一个供用户打开以输入密钥或连接应用的链接，无需完整的项目访问权限。 |

#### 连接器与策略（Connectors and policies）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `connector(slug).run(action, args, options?)` | 操作的输出。若调用等待审批，将抛出 `ConnectorCallError` 或 `ConnectorApprovalPendingError`。 |
| `connector(slug).call` · `.describe(action?)` · `.accounts()` · `.paginate(action, args, { next, maxPages? })` · `.uploadAttachment(content, input)` | 原始结果 · 模式（Schemas） · 可调用账户 · 分页迭代器（超过 `maxPages` 时抛出 `ConnectorPageLimitError`） · 暂存文件。 |
| `connectors.call(tool, args?, { account? })` · `connectors.callAction(slug, action, args, options?)` | 调用 `<connector>.<action>` · 相同操作，由 `kortix connectors types` 提供类型。 |
| `connectors.catalog(options?)` · `.tools()` · `.search(query)` · `.describe(tool)` · `.accounts(slug)` · `.uploadAttachment(…)` | 查找并检查可调用的工具和账户。 |
| `connectors.list()` · `.config(slug)` · `.create(input)` · `.remove(slug)` · `.sync()` · `.auth.discover(input)` | 配置连接器。`auth.discover` 从 OpenAPI 规范、Postman 集合或端点读取认证信息。 |
| `connectors.setName` · `.setSensitive` · `.setCredentialMode` · `.setCredential` · `.deleteCredential` · `.setOAuth2ClientCredentials` | 连接器设置及其共享账户的存储凭证。 |
| `connectors.policies.get(slug, { policySet? })` · `.policies.set(slug, policies, { policySet? })` | 单个连接器的基础规则，或某个策略集的规则。规则格式为 `{ match, action, conditions? }`。 |
| `connectors.policySets.list(slug)` · `.upsert(slug, name, { description? })` · `.rename(slug, name, newName)` · `.remove(slug, name)` | 策略集：包含每个集及其规则和使用该集的 Agent · 创建或设置描述 · 重命名（同时更新所有 Agent 引用） · 删除。当有 Agent 使用该集时，`remove` 会返回 `409 policy_set_in_use`。从根入口导出：`listConnectorPolicySets`、`upsertConnectorPolicySet`、`renameConnectorPolicySet`、`deleteConnectorPolicySet`。 |
| `connectors.agents(…)` · `connectors.rulesMatrix()` | 获取单个连接器上声明的所有 Agent 及其授权和规则集 · 在单次请求中获取所有连接器与所有 Agent 的对应关系。 |
| `connectors.connections.list()` · `.listAll()` · `.reconcile(…)` · `.reconcileMember(…)` · `.updateCredential(…)` · `.revoke(…)` · `.activate(…)` · `.setDefault(…)` · `.rename(…)` · `.share(…)` · `.addComputer(…)` | 已连接的账户：共享或私有、默认值、标签、共享状态、已配对的计算机。 |
| `connectors.discover.list` · `.sections` · `.detail` · `.tools` · `.install` | 应用目录。`list` 和 `sections` 接受 `q`、`category`、`kinds`（`mcp`、`composio`、`openapi`、`graphql`）和 `oneClick`。`install({ id, way?, name?, slug? })` 返回 `next` 状态：`connect`、`credential` 或 `ready`。 |
| `connectors.listMoves()` · `connectors.move(slug, { connectionId? })` | 将 Pipedream 或 Composio 连接器迁移至其 OpenChatly MCP 应用（保持相同的 Slug）。`listMoves` 返回 `ConnectorMove[]`。`move` 返回 `ConnectorMoveResult`：`status: 'sign_in'` 附带 `connection_id`，或 `status: 'moved'`。从根入口导出：`listConnectorMoves(projectId)`、`moveConnector(projectId, slug, { connectionId? })`。 |
| `connectors.pipedream.listApps` · `.listSections` · `.connect` · `.finalize` | 针对 OAuth 应用的旧版 Pipedream 连接。 |
| `policies.list()` · `policies.set(policies)` | 项目策略。 |
| `agentIdentities()` · `setAgentScope(agentName, scope)` | 获取项目中的 Agent 作为主体 · 将密钥、连接器和策略集绑定到特定 Agent。`scope.policy_sets` 为 `{ <slug>: <name> \| null }`，按连接器合并；`null` 或 `'base'` 会移除该条目。 |

#### 触发器与循环（Triggers and loops）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `triggers.all()` | 调用者可见的所有触发器：`kortix.yaml` 触发器（`origin: 'declared'`）和运行时触发器（`origin: 'runtime'`：循环和 `triggers.createRuntime` 行），`GET /v1/projects/<id>/triggers/all`。每个触发器都有一个 `source`（`schedule`、`webhook`、`event`、`app`、`change_request`）和一个 `target`（`agent`、`session` 或 `app`）。从根入口导出：`listUnifiedTriggers(projectId)`。React 中使用：`useUnifiedTriggers(projectId)`。 |
| `triggers.createRuntime({ prompt, name?, source, target })` | 运行时触发器，存储在数据库中（`POST …/triggers/runtime`，ID 为 `trigger.<hex>`）。`target: { session_id }` 会在每次触发时唤醒该会话；`target: { agent }` 会启动该 Agent 的新会话。`source: { type: 'change_request', cr_id?, base? }` 会在变更请求合并时触发。 |
| `triggers.updateRuntime(id, { enabled })` · `.runRuntime(id)` · `.removeRuntime(id)` | 暂停或恢复、立即触发一次，或删除运行时触发器。`kortix.yaml` 中的触发器需通过 `triggers.update` 及其他 slug 方法进行更改。 |
| `triggers.list()` | 获取所有触发器，包含解析错误和 `triggers_paused` 状态。 |
| `triggers.eventApps()` · `triggers.eventTypes(…)` | 可触发 `event` 触发器的连接器及其连接状态 · 单个应用的事件类型。需要开启 `event_triggers` 功能标志。 |
| `triggers.create(input)` · `.update(slug, input)` · `.remove(slug)` | 写入触发器。`name` 和 `type` 为必填。`type` 为 `cron`、`webhook`、`event`、`app` 或 `change_request`。API 会以 `MONITOR_REMOVED` 拒绝 `type: monitor`，并指明替代方案：一个 App 和一个 `type: app` 触发器。除非 `target`（`{ app, path?, method?, payload? }`）调用 App，否则 `prompt_template` 为必填。调度（Schedule）接受 `cron`、`every` 或 `run_at`。`type: 'app'` 接受 `app`，以及可选的 `filter: { 'event.name': … }`。`type: 'change_request'` 接受可选的 `filter: { base: '<branch>' }`。 |
| `triggers.fire(slug, { payload?, dryRun? }?)` | 立即运行单个触发器（即使在触发器暂停时也可运行）。`payload` 会深度合并到手动负载中。`dryRun: true` 不会写入任何内容，并返回 `ProjectTriggerDryRunResult`（`rendered_prompt`、`filter_matches`、`session_key`、`payload`）。真实触发会返回 `status`（`fired`、`queued` 或 `deduped`）、`session_id`、`command_id` 和 `run_id`。 |
| `triggers.runs(slug, { cursor?, limit? }?)` · `triggers.projectRuns({ status?, cursor?, limit? }?)` | 单个触发器的运行记录 · 项目的所有运行记录（按最新排序）：`{ runs, next_cursor }`。`limit` 为 1 到 100，默认 25。当设置了 `next_cursor` 时，单页包含的记录可能少于 `limit`。 |
| `triggers.replay(slug, runId, { confirmUnverified? }?)` | 使用运行记录的存储负载和当前规范重新触发。若运行正在排队或执行中，返回 `409 run_in_progress`。若为未验证的 Webhook 负载且未设置 `confirmUnverified: true`，返回 `409 payload_unverified`。若负载超过 64 KiB，返回 `422 payload_truncated`。 |
| `triggers.setActivation(paused)` | 暂停或恢复项目的所有触发器。 |
| `reminders.list()` · `reminders.updateMany(…)` · `reminders.removeMany(…)` | 调用者可打开的所有会话上的循环（SDK 中命名为 reminders）。单个会话的循环为 `s.reminders`。 |

所有触发器字段详见 [Run triggers（运行触发器）](#运行触发器run-triggers) 和 [Triggers（触发器）](/docs/zh/guide#触发器triggers)。

#### 应用（Apps）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `apps.list()` · `.get(appId)` · `.create(input)` · `.update(appId, input)` · `.remove(appId)` | 应用清单与生命周期管理。 |
| `apps.artifacts.register(input)` · `.uploadArchive(…)` · `.finalize(…)` | 上传构建产物。 |
| `apps.deployments.create(appId, …)` · `.list(appId)` · `.get(…)` · `.logs(…)` · `.remove(…)` | 发布版本及其日志。`remove` 用于删除未上线的版本。 |
| `apps.rollback(appId, deploymentId)` · `.start(appId)` · `.stop(appId)` | 将流量回滚到早期版本 · 启动 · 停止。 |
| `apps.machines.list(appId)` · `.start` · `.stop` · `.restart` · `.destroy(appId, machineId)` | 机器管理。`destroy` 会保留该机器的数据卷（Volume）。 |
| `apps.scale(appId, { <group>: count })` | 每个进程组的机器数量，范围为 0 到 20。 |
| `apps.exec(appId, input)` | 在机器中运行单条命令。需要 `project.app.admin` 权限。每次调用都会被审计。 |
| `apps.volumes.list(appId)` · `.create` · `.update` · `.destroy(appId, volumeId, confirmName)` · `.snapshots` · `.snapshot` · `.restore(appId, volumeId, snapshotId)` · `.fork` | 持久化数据卷与快照管理。 |
| `apps.access.get(appId)` · `.update(appId, …)` · `.session(appId)` · `.agents(appId)` | 控制谁可以打开该应用 · 访问会话 · 在 `kortix.yaml` 授权中提及该应用的 Agent（只读）。 |
| `apps.token(appId)` | 获取一个 15 分钟有效、以调用者身份命名的应用登录令牌。需要 `member_tokens` 能力。 |
| `apps.authEnv(appId)` | 获取 `KORTIX_AUTH_ISSUER`、`KORTIX_AUTH_AUDIENCE` 和 `KORTIX_AUTH_JWKS`，用于无需网络请求即可验证应用令牌。 |

相关路由：`/projects/{projectId}/apps/…`。详见 [Deploy and operate Apps（部署与运行应用）](#部署与运维-appdeploy-and-operate-apps) 和 [Apps reference（应用参考）](#应用参考apps-reference)。

#### 制品（Artifacts）

`p.artifacts` 包含评论与活动相关的调用。Artifact 的调用是从根入口导出的，且第一个参数为 `projectId`。当 `artifacts` 功能标志关闭时，所有 `/projects/{projectId}/artifacts…` 路由均返回 `403 feature_disabled`。评论与活动路由还需要开启 `artifact_comments` 标志，该标志默认关闭。

| 根导出（Root export） | 功能说明（What it does） |
| --- | --- |
| `listArtifacts(projectId, { scope?, type?, q?, limit? }?)` | 获取调用者可打开的制品列表（按最新更改排序），类型为 `Artifact[]`。`scope`：`all`、`mine`、`shared` 或 `pinned`。`type`：`doc` 或 `html`。开启 `artifact_comments` 时，每行数据会带有 `open_thread_count`。 |
| `getArtifact(projectId, artifactId, { version? }?)` | 获取 `ArtifactDetail`：包含 `can_edit`、`entry_version`、文件列表以及有效期为 12 小时的签名 `view_url`。传入 `version` 可读取制品在某次保存时的状态。 |
| `createArtifact(projectId, { files, title?, description?, visibility? })` | 将新文件作为制品发布到调用者在 Drive 中的 `Artifacts` 文件夹。`files` 将路径映射为 `{ content }` 或 `{ content_base64 }`。`index.md` 会生成文档，`index.html` 会生成页面。`visibility` 默认为 `private`。错误：`400 missing_entry`、`413 file_too_large`（单文件超过 16 MB）、`413 publish_too_large`（总计超过 32 MB）。 |
| `shareArtifactPath(projectId, { path, title?, description?, visibility? })` | 共享 Drive 中已有的文件夹。若该路径已经是制品，将返回 `409 already_shared`。 |
| `saveArtifact(projectId, artifactId, { files, base_version?, title?, description? })` | 将文件作为一次保存写入制品。传入 `base_version` 时，若他人已更新，将返回 `409 version_conflict`。若无写入权限，将返回 `403 artifact_read_only`。 |
| `updateArtifact(projectId, artifactId, { title?, description?, visibility?, shared_with_user_ids? })` | 重命名或共享。`shared_with_user_ids` 会替换私有制品的共享人员。需要是创建者或具备 `project.artifact.manage` 权限，否则返回 `403 artifact_read_only`。若无 `project.artifact.public` 权限而设置公开链接，将返回 `403 public_link_forbidden`。 |
| `deleteArtifact(projectId, artifactId)` | 停止共享。删除制品的评论和截图。文件将保留在 Drive 中。 |
| `setArtifactPinned(projectId, artifactId, pinned)` | 设置调用者自己的置顶状态。 |
| `listArtifactVersions(projectId, artifactId)` · `restoreArtifactVersion(projectId, artifactId, version)` | 获取 Drive 历史中的所有保存记录（按最新排序），类型为 `ArtifactVersion[]` · 将某次保存写回作为新的保存。 |
| `readArtifactFile(projectId, artifactId, { path?, version?, signal? }?)` | 以 `Blob` 形式读取单个文件的源码。默认读取当前的入口文件。 |
| `listArtifactTypes(projectId)` | 获取 `doc` 和 `html` 类型，包含各自的格式规则和初始模板。 |
| `getPublicArtifact(artifactId, options?)` | 无需令牌即可获取公开制品的标题、类型和 `content_url`。若制品非公开，将抛出 `status` 为 404 的 `HostBoundaryError`。 |
| `parseArtifactUrl(url)` | 从应用链接解析出 `{ projectId, artifactId }`，或从公开链接解析出 `{ projectId: null, artifactId }`。其他 URL 返回 `null`。 |

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `artifacts.comments.list(artifactId, { status?, version? }?)` | 获取包含评论的线程，类型为 `ArtifactCommentThread[]`。`status`：`open`（默认）、`resolved` 或 `all`。传入 `version` 可读取特定文件提交；此时返回的行不允许执行操作。从根导出：`listArtifactComments`。 |
| `artifacts.comments.get(threadId)` | 根据 ID 获取单个线程，包含相同的可见性检查。从根导出：`getArtifactCommentThread`。 |
| `artifacts.comments.create(artifactId, { anchor, body, marks?, screenshot_base64? })` | 开启一个线程并返回。`anchor.type` 为 `none`、`text`、`point` 或 `region`。`text` 锚点的 `quote` 最多 500 个 UTF-16 代码单元，`prefix` 和 `suffix` 各最多 32 个。`body` 为 1 到 10,000 个字符。错误：`400 invalid_anchor`、`400 invalid_comment`。从根导出：`createArtifactComment`。 |
| `artifacts.comments.reply(artifactId, threadId, { body, marks?, screenshot_base64? })` | 添加评论并返回。若线程的首条评论已删除，将返回 `409 thread_deleted`。从根导出：`replyArtifactComment`。 |
| `artifacts.comments.setStatus(artifactId, threadId, 'open' \| 'resolved')` | 重新打开或解决线程。从根导出：`setArtifactCommentStatus`。 |
| `artifacts.comments.edit(artifactId, threadId, commentId, { body })` · `.remove(artifactId, threadId, commentId)` | 修改调用者自己的评论 · 删除评论并留下墓碑记录。具备 `project.artifact.manage` 权限的调用者可删除任何评论。否则返回 `403 artifact_comment_forbidden`。从根导出：`editArtifactComment`、`deleteArtifactComment`。 |
| `artifacts.comments.send(artifactId, { thread_ids, batch_id?, agent? })` | 在单个回合中将 1 到 100 个线程移交给 Agent。返回 `{ session_id, created }`。重用 `batch_id` 可重试相同的移交；若省略，SDK 会自动生成。当 Agent 会话发送等待人工处理的线程时，返回 `409 artifact_comment_paused`。当读取图像的模型将收到超过 20 张截图、100 MiB 解码图像或 12 MiB 图像部分时，返回 `413 artifact_comment_screenshot_limit`。从根导出：`sendArtifactComments`。 |
| `artifacts.comments.context(artifactId, { version?, agent? }?)` | 获取调用者的权限、可提及的人员和 Agent（附带插入令牌）、发送目标，以及 Send 会获取的线程：`send_thread_ids`（前 100 个）和 `send_thread_count`。从根导出：`getArtifactCommentContext`。 |
| `artifacts.comments.snapshot(artifactId, { version? }?)` · `.readScreenshot(artifactId, commentId)` | 获取文本锚点指向的已保存文本，格式为 `{ version, text }` · 以 `Blob` 形式读取某条评论的截图。从根导出：`readArtifactCommentSnapshot`、`readArtifactCommentScreenshot`。 |
| `artifacts.activity(artifactId, { limit?, cursor? }?)` | 获取一页保存与事件记录（按最新排序）：`{ items, next_cursor, older_versions }`。`limit` 为 1 到 100。将 `next_cursor` 作为 `cursor` 传入。从根导出：`listArtifactActivity`。 |
| `artifacts.live.connect(artifactId, { view, version?, hidden?, webSocket?, onEvent? })` | 打开制品的实时 WebSocket 并返回 `ArtifactLiveConnection`：包含 `status`、`participants`、`you`、`setCursor`、`setSelection`、`setTyping`、`setFocus`、`setHidden`、`close`。它会自动重连，间隔 1 到 30 秒，每次使用新票据。关闭代码 `4403` 会以 `access_lost` 状态结束。从根导出：`createArtifactLiveConnection`。React 中使用：`useArtifactLive(projectId, artifactId, { enabled, view, version?, hidden? })`。 |
| `artifacts.live.ticket(artifactId)` · `.signal(artifactId, { status, thread_id?, quote? })` | 获取一次性 WebSocket 票据，有效期 60 秒 · 标记 Agent 会话在制品中的状态：`reading`、`editing`、`writing` 或 `idle`。`signal` 需要绑定会话的令牌；使用个人令牌将返回 `403`。从根导出：`createArtifactLiveTicket`、`signalArtifactLiveAgent`。 |

线程会携带其交付状态：`agent_state` 为 `none`、`pending`、`sent` 或 `paused`，`sent_session_id` 指明接收该线程的会话。`agent_error` 记录交付失败；当循环守卫（Loop guard）暂停线程时，该值为 `null`。在单个制品上，单个作者每分钟最多写入 60 条评论，单个会话每小时最多写入 30 条评论。超出任一限制将返回 `429 artifact_comment_rate_limited`。

当无法读取项目的 Agent 清单时，`context` 仍会响应：`agents` 为空，`send_target` 为 `null`，且 `agents_unavailable` 为 `true`。用户仍可继续评论。带有显式 `@agent.` 提及的评论将被拒绝，直到清单可再次读取。

相关路由：`/projects/{projectId}/artifacts…`、`/projects/{projectId}/artifact-comment-threads/{threadId}`，以及用于 `getPublicArtifact` 的 `/artifacts/meta/{artifactId}`。详见 [Artifacts（制品）](/docs/zh/guide#交付物artifacts)。

#### 网关与模型（Gateway and models）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `gateway.logs(options?)` · `gateway.log(logId)` | 模型请求日志。 |
| `gateway.overview(days?)` · `.series(days?)` · `.breakdown(days?)` · `.sessions(days?)` · `.errors(days?)` | 按天数窗口进行的汇总统计。 |
| `gateway.budgets()` · `.setBudget(input)` · `.deleteBudget(budgetId)` | 预算（Budgets）管理。 |
| `gateway.keys()` · `.createKey(name)` · `.revokeKey(keyId)` | 供您自己的工具使用的网关 API 密钥。 |
| `gateway.routing.get()` · `.set(policy)` · `.reset()` · `.preview(input)` | 路由策略（默认模型、视觉模型、有序回退列表） · 在不发起模型调用的情况下解析路由。 |
| `gateway.playground(prompt, models, system?)` | 针对 1 到 6 个模型运行同一个提示词（Prompt）。 |
| `modelDefaults.get()` · `.set(input)` · `.clear(params)` | 按账户、Agent 和项目设置的默认模型。 |
| `setDefaultAgent(agentName)` | 在 `kortix.yaml` 中设置 `default_agent`。该 Agent 必须已被声明并启用。 |

详见 [Models（模型）](/docs/zh/guide#模型models)。

#### 渠道（Channels）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `channels.slack.installation()` · `.mode()` · `.manifest()` · `.connect(input)` · `.completeInstall(input)` · `.disconnect()` | 项目的 Slack 应用。 |
| `channels.slack.getFile(url)` · `.uploadFile(input)` | 通过服务端下载或上传 Slack 文件。Bot 令牌始终保留在服务端。 |
| `channels.teams.completeInstall(input)` | 以已登录用户的身份完成 Microsoft Teams 的安装。 |
| `channels.telegram.installation()` · `.connect(input)` · `.disconnect()` | 项目的 Telegram 机器人。 |
| `channels.telegram.users()` · `.allowUser(id)` · `.removeUser(id)` · `.setAllowedUsers(ids)` · `.dismissAccessRequest(id)` · `.userPhoto(…)` | 控制谁可以向机器人发消息，以及查看请求访问权限的人员。 |
| `channels.discord.mode()` · `.installation()` · `.completeInstall(input)` · `.disconnect()` | 项目的 Discord 应用。 |
| `channels.discord.users()` · `.allowUser(id)` · `.removeUser(id)` · `.setAllowedUsers(ids)` · `.dismissAccessRequest(id)` | 控制谁可以向 Discord 应用发消息。 |

详见 [Channels（渠道）](/docs/zh/guide#频道channels)。

#### 访问控制（Access）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `access.list()` · `access.invite(email, role, expiresAt?)` · `access.update(userId, role)` · `access.revoke(userId)` | 项目成员。角色包括：`manager`（管理员）、`member`（成员）。 |
| `access.pendingInvites()` · `.resendInvite(inviteId)` · `.revokeInvite(inviteId)` | 待处理的邀请。 |
| `access.requests()` · `.approveRequest(id)` · `.rejectRequest(id)` | 访问请求。 |
| `access.groupGrants()` · `.attachGroupGrant(…)` · `.updateGroupGrant(…)` · `.detachGroupGrant(groupId)` | 拥有项目访问权限的用户组。 |
| `access.resourceGrants.list()` · `.create(input)` · `.remove(grantId)` | 为成员或用户组授予对单个对象（如特定 Agent 或技能）的访问权限。 |

详见 [Teams（团队）](/docs/zh/guide#teams)。

#### 沙箱（Sandbox）

| 方法（Method） | 功能说明（What it does） |
| --- | --- |
| `sandbox.list()` · `sandbox.snapshots()` | 项目的沙箱 · 已构建的快照。 |
| `sandbox.rebuildSnapshot(slug?)` · `sandbox.fixWithAgent()` | 重新构建快照 · 请求 Agent 修复失败的构建。 |
| `sandbox.createTemplate(input)` · `.updateTemplate(…)` · `.removeTemplate(templateId)` · `.buildTemplate(templateId)` | 沙箱模板。 |
| `sandbox.setProvider(provider \| null)` | 固定沙箱提供商，或传入 `null` 使用平台默认值。当更改立即生效时返回 `kind: 'project'`；当新提供商的镜像正在构建时返回 `kind: 'preparation'`。 |

详见 [Computers（计算环境）](/docs/zh/guide#计算机computers)。

### 会话句柄（The session handle）

`kortix.session(projectId, sessionId)` 或 `p.session(sessionId)` 返回 `s`。`session_id` 同时也是沙箱 ID。涉及运行时调用的方法会首先调用 `ensureReady()`。相关指南详见 [Sessions from code（通过代码管理会话）](#从代码管理会话)。

| 领域（Area） | 方法（Method） | 功能说明（What it does） |
| --- | --- | --- |
| 会话行（Row） | `get({ showErrors? }?)` | 获取会话行数据。 |
| 会话行（Row） | `update({ name?, labels?, metadata? })` | 修改名称、标签和元数据。 |
| 会话行（Row） | `delete()` · `restore()` | 删除 · 在恢复窗口期（`restore_until`）内恢复已删除的会话。 |
| 会话行（Row） | `setPinned(pinned)` · `setArchived(archived)` | 设置调用者自己的置顶和归档状态。置顶会取消归档；归档会取消置顶。不会影响其他人的列表。需要个人凭证；使用 Agent 令牌会收到 `403` 错误。 |
| 生命周期（Lifecycle） | `start(…)` · `startOrThrow(…)` | 启动运行时；请求失败时返回 `null` · 相同功能，但请求失败时会抛出 `ApiError`（包含 `status`、`code` 以及计费相关的 `402` `detail`）。 |
| 生命周期（Lifecycle） | `ensureReady({ readyTimeoutMs?, session? }?)` | 预置或恢复沙箱并等待其就绪。默认 `readyTimeoutMs` 为 `180_000`。支持幂等操作。 |
| 生命周期（Lifecycle） | `restart()` · `stop()` | 重启运行时 · 停止运行时。两者都会重置句柄的就绪状态。 |
| 生命周期（Lifecycle） | `recover()` | 在新计算机上继续已丢失的会话。当提供商移除了沙箱时（`start` 失败，原因为 `runtime_identity_unavailable`），会话即视为丢失。拒绝情况：`409 session_not_lost`、`409 session_transcript_missing`、`409 session_sandbox_removal_pending`（请一分钟后重试）、`503 session_log_restore_off`。 |
| 生命周期（Lifecycle） | `health(init?)` | 运行时探测，包含 `capabilities`。非 2xx 状态码时绝不抛出异常。 |
| 提示词（Prompts） | `send(text, { model?, agent? }?)` | 将提示词加入队列。`model` 为 `{ providerID, modelID }`。当提示词被持久化时即解析完成，而非等待对话回合结束。 |
| 提示词（Prompts） | `abort()` | 停止当前对话回合。 |
| 提示词（Prompts） | `prompts.create(input)` · `.list()` · `.remove(promptId)` · `.retry(promptId)` · `.edit(promptId, text)` · `.interrupt(promptId)` · `.hold(held)` | 提示词收件箱。 |
| 事件（Events） | `stream({ onEvent, onGapRehydrate?, signal? })` | 打开实时事件流。解析为带有 `close()` 方法的句柄。选项：[openEventStream](#事件流event-stream)。 |
| 对话（Conversation） | `messages({ conversationId?, limit?, before?, signal? }?)` | 获取一页对话记录（`kortix.transcript.v1`）。`conversationId` 用于读取子 Agent 对话。 |
| 对话（Conversation） | `pendingRequests()` | 获取每个线程的状态（`idle`、`busy`、`compacting`）以及等待回答的权限请求和问题。 |
| 对话（Conversation） | `answerPermission(requestId, 'once' \| 'always' \| 'reject', message?)` | 回答权限请求。 |
| 对话（Conversation） | `answerQuestion(requestId, answers \| null)` | 回答问题（每个问题对应一个答案），或传入 `null` 将其忽略。 |
| 对话（Conversation） | `compact({ providerID, modelID }?)` | 总结上下文。需要 `session.compact` 能力。 |
| 对话（Conversation） | `rewind(messageId)` · `restoreRewind()` | 回退到某条消息 · 撤销回退。需要 `session.rewind` 能力；pi 不提供此服务。 |
| 存储读取（Stored reads） | `turn()` | 在服务端读取当前回合。 |
| 存储读取（Stored reads） | `log({ thread?, before_seq?, limit? }?)` | 获取一页存储的会话日志；若会话无日志则返回 `null`。在沙箱停止时也可响应。 |
| 存储读取（Stored reads） | `liveLog({ thread?, before_seq?, limit? }?)` | 获取沙箱自身会话日志的某个线程的一页数据；在回合运行期间，其数据比 `log()` 更新。若沙箱没有会话日志操作，返回 `null`。 |
| 存储读取（Stored reads） | `messageAuthors()` · `modelUsage()` · `usage()` · `cost()` · `audit(limit?, options?)` | 每条消息的作者 · 每个回合使用的模型及 OpenChatly 的计费情况 · 该会话及其启动的所有会话的成本（美元） · 会话的用量记录 · 会话的审计操作。 |
| 模型与 Agent（Model and agent） | `setModel({ providerID, modelID } \| undefined)` · `setAgent(agent)` | 设置此句柄后续所有 `send` 调用的默认模型或 Agent。`send(text, { model, agent })` 可为单次提示词覆盖此设置。 |
| 模型与 Agent（Model and agent） | `changeModel('provider/model')` | 持久化模型设置，无需重启 pi。 |
| 作用域（Scope） | `scope()` · `rescope(scope)` | 读取 · 更改会话的作用域。 |
| 作用域（Scope） | `providerSecretPool.list()` · `.get(providerId)` · `.set(providerId, secretIds \| null)` | 此会话可使用的池化提供商密钥。 |
| 配置（Config） | `configState()` · `reloadConfig(input?)` · `reloadConfigStream(…)` | 检查会话是否运行了清单编译出的配置 · 重新加载 · 带进度地重新加载。 |
| 文件（Files） | `files.list(dir)` · `.read(path)` · `.readBlob(path)` · `.status()` · `.findFiles(query, { type?, limit? })` · `.findText(pattern)` | 读取沙箱文件系统。 |
| 文件（Files） | `files.upload(file, …)` · `.write(path, blob)` · `.create(path)` · `.copy(from, to)` · `.remove(path)` · `.mkdir(dir)` · `.rename(from, to)` | 写入沙箱文件系统。行为说明：[Files](#文件files)。 |
| 文件（Files） | `attachments.upload(file, options?)` · `attachments.read(attachmentId, signal?)` | 会话附件。`read` 返回 `Blob`，且在沙箱停止时也可使用。 |
| 预览（Previews） | `previews()` · `previewUrl(port, path = '/')` · `proxyUrl(url?)` · `sandboxPortUrl(port)` | 预览候选项 · 沙箱端口的可访问 URL · Agent 的 `localhost` URL 的代理 URL · 原始端口 URL。后三个方法在 `ensureReady()` 之前调用会抛出 `SessionNotReadyError`。 |
| 人员（People） | `participants()` · `setSharing(intent)` | 会话的参与者 · 控制谁可以打开它。`intent` 为 `{ mode: 'private', ownerId }`、`{ mode: 'project' }` 或 `{ mode: 'members', memberIds?, groupIds? }`。仅限所有者或项目管理员。 |
| 人员（People） | `watch()` · `setWatch(watching)` | 控制调用者是否接收此会话的通知 · 关注或静音。 |
| 人员（People） | `presence({ tab_id, active, alerts? }, { keepalive? }?)` | 当前标签页的存在租约。返回 `{ ok, awake_until, awake_cap_at }`。 |
| 人员（People） | `publicShares.list()` · `.create(…)` · `.revoke(…)` | 预览或工作区文件的公开分享链接。若请求体包含 `{ transcript: true }`，将返回 `400`。 |
| Git | `commit(input?)` | 将沙箱的待处理更改提交并推送到会话分支。 |
| Agents | `reachable({ scope? }?)` · `setInbound(inbound)` | 此会话可发送消息的 Agent · 控制谁可以向它发消息：`accept`（接受）、`hold`（挂起）或 `refuse`（拒绝）。 |
| Agents | `peerMessages.send(body)` · `.list({ direction? }?)` · `.approve(messageId)` · `.deny(messageId)` | 会话间消息：发送、列出接收（`in`）或发送（`out`）的消息、交付或丢弃挂起的消息。 |
| Agents | `tasks.list()` · `.create(body)` · `.update(seq, body)` · `.remove(seq)` | 此会话领导的团队的共享任务列表。Agent 团队为实验性功能，默认关闭。请在 **Project admin** → **Feature flags** 中开启。 |
| Agents | `workflows.list()` · `workflows.control(runId, body)` | 在此会话沙箱上运行的工作流（按最新排序） · 暂停、恢复或停止运行，或重启其某个 Agent。`list` 会唤醒休眠的会话。 |
| 循环（Loops） | `reminders.list()` · `.create(input)` · `.update(reminderId, input)` · `.remove(reminderId)` · `.run(reminderId)` | 会话的提醒（Reminders）。`run` 会立即触发一次；调度时间不会改变。 |

`s.transcript()`、`s.transcriptSync()`、`s.pending()` 和 `s.runtime` 已废弃。详见 [Deprecated names（已废弃的名称）](#废弃的名称deprecated-names)。

### React Hooks

所有 Hook 均位于 `@kortix/sdk/react`。大多数为 React Query Hook：除非表格中另有说明，Hook 会返回查询结果（`data`、`isLoading`、`error` 等）以及表格中列出的变更（Mutations）方法。写入操作会自动刷新匹配的读取查询。请按照 [React > Set up（React > 设置）](#初始配置set-up) 配置 Provider。

#### 会话 Hooks（Session hooks）

| Hook（Hook） | 返回值（What it returns） |
| --- | --- |
| `useSession(projectId, sessionId, options?)` | 完整的会话生命周期：启动、就绪状态、实时流、消息和操作。表格说明：[React > useSession](#usesession)。 |
| `useSessionSend(sessionId, options?)` | 一个带有 `KortixSendError` 错误分类的发送函数。详见 [Send and handle errors（发送与处理错误）](#发送消息与处理错误)。 |
| `useSessionPrompts(projectId, sessionId, { pollMs?, enabled? }?)` | 单个会话的提示词收件箱。 |
| `useSessionWorking(projectId, sessionId, { enabled?, runtimeSessionId? }?)` | 当前是否有对话回合正在进行，以及其结束的原因。 |
| `useRuntimeSupports(capability)` | `boolean`：当前打开的会话的运行时是否提供某项能力（Capability）。在运行时首次响应之前，始终返回 `true`。 |
| `useSessionMessages(session, { throttleMs? }?)` | 将单个对话的消息作为 `MessageWithParts[]` 返回。 |
| `useSessionLog(session)` · `useSessionLogThread(session, threadId?, { throttleMs? }?)` | 会话日志，或 `null` · 会话日志中的单个线程。 |
| `useChatTurns(messages)` | `TurnView[]`：使用 `classifyTurn` 对每条消息进行分类。 |
| `useSessionChildren(projectId, parentSessionId, { q, limit, enabled })` | 某个父会话启动的子会话（分页）。 |
| `useSessionReminders(projectId, sessionId)` | 会话的循环（Loops），附带 `update` 和 `remove` 方法。 |
| `useSessionMessageAuthors` · `useSessionModelUsage` · `useSessionUsage` · `useSessionProviderSecretPools` | 对应 `s.messageAuthors()`、`s.modelUsage()`、`s.usage()` 和 `s.providerSecretPool.list()` 的读取 Hook。 |
| `useSessionWorkflows` · `usePeerMessages` · `useReachableAgents` · `useTeammates` · `useTeamTasks` | 获取单个会话的工作流运行记录、对等消息（Peer messages）、可达的 Agent、队友和团队任务。 |
| `useSessionStreamConnected(projectId, sessionId)` | `boolean`：会话的实时流是否已连接。 |
| `useHasSessionDesktop()` | `boolean \| undefined`：当前打开的会话所在的计算机是否具备桌面环境。在守护进程（Daemon）响应之前为 `undefined`。 |

#### 项目与账户 Hooks（Project and account hooks）


| Hook（Hook） | 返回值（What it returns） |
| --- | --- |
| `useAccounts({ userId, enabled })` | 调用者的账户。在用户可能在不刷新页面的情况下切换的宿主环境中，请传入已登录用户的 `userId`。 |
| `useProjects(accountId?, options?)` | 单个账户的项目。 |
| `useProjectSessions(projectId, options)` | 单个项目的会话（分页），按最新活动排序。读取 `sessions`（扁平数据）和 `fetchNextPage`。过滤条件同 [Sessions（会话）](#会话sessions)。新增 `keepPreviousData`（在加载新过滤条件时保留旧行数据）、`refetchInterval` 和 `pollFirstPageOnly`（实验性）。 |
| `useProjectModels(projectId)` | 可选模型，类型为 `FlatModel[]`。列表加载期间为空。 |
| `useProjectModelPickerCatalog(projectId)` | 每个模型的模型选择器记录（`reasoning_options`、`temperature`、`limit`）。 |
| `useModelAccess(projectId)` | 已禁用的提供商和模型，以及 `setEnabled({ target, id, enabled })` 方法。 |
| `useCustomLlmProviders(projectId)` | `{ providers, isLoading, error, save(providerId, input), remove(providerId), isSaving }`。 |
| `useProjectConfig(projectId)` | 配置摘要（默认 Agent、斜杠命令），类型为 `ProjectConfigSummary`。 |
| `useVisibleAgents({ projectId })` | 用户可选择的 Agent，类型为 `Agent[]`。 |
| `useProjectSecrets(projectId)` | 密钥，附带 `upsert`、`remove`、`setPersonal` 和 `removePersonal` 方法。 |
| `useAccountSecretResources(accountId, projectId?)` | 账户密钥资源。 |
| `useProjectTriggers(projectId)` | 触发器，附带 `create`、`update`、`remove`、`fire`、`dryRun` 和 `replay` 方法。`fire.mutate(slug)` 或 `fire.mutate({ slug, payload? })` 返回 `FireProjectTriggerResponse`。`dryRun.mutate(slug \| { slug, payload? })` 返回 `ProjectTriggerDryRunResult` 且不写入任何内容。`replay.mutate({ slug, runId, confirmUnverified? })`。触发（Fire）和重放（Replay）会刷新触发器列表及所有运行记录列表。 |
| `useTriggerRuns(projectId, slug, { enabled?, refetchInterval?, limit? }?)` · `useProjectTriggerRuns(projectId, { status? }?, { enabled?, refetchInterval? }?)` | 运行记录，作为按 `next_cursor` 分页的无限查询。读取 `data.pages[].runs`；当 `hasNextPage` 为真时调用 `fetchNextPage()`。除非传入 `refetchInterval`（毫秒），否则不会轮询。`limit` 为 1 到 100（服务端默认 25），设置的 limit 会作为独立的缓存条目。 |
| `useProjectReminders(projectId)` | 项目的循环（Loops），附带 `update`、`remove`、`updateMany` 和 `removeMany` 方法。 |
| `useChangeRequests(projectId, status?)` | 变更请求，附带 `open`、`merge`、`close` 和 `requestChanges` 方法。 |
| `useReviewItemPages(projectId, query)` · `useReviewSummary(projectId)` · `useSessionsNeedingInput(projectId)` | 评审收件箱，作为无限查询（行数据：`reviewItemsOf(query.data)`） · 摘要，每 60 秒轮询 · 阻塞的会话，每 30 秒轮询。 |
| `useProjectApps(projectId)` | 应用，附带 `create`、`update`、`start`、`stop` 和 `remove` 方法。 |
| `useAppDeployments` · `useAppDeployment` | 部署列表，附带 `deploy` 和 `rollback` · 单个部署及其构建日志。 |
| `useAppMachines(projectId, appId)` · `useAppVolumes(projectId, appId)` · `useAppVolumeSnapshots(projectId, appId, volumeId)` · `useAppAccess` | 机器，附带 `start`、`stop`、`restart`、`destroy`、`scale`，每 5 秒轮询 · 数据卷，附带 `snapshot`、`restore`、`fork`、`extend`、`destroy` · 快照（按最新排序） · `{ policy, session, update }`。 |
| `useKortixAppViewer()` | 在应用内部使用：`{ status: 'loading' \| 'anonymous' \| 'viewer', viewer }`。 |
| `useConnectorQuery(projectId, slug, action, args, { account, enabled, staleTime })` | 单个连接器操作的输出，作为缓存查询。**仅用于只读操作**：每次获取都会执行该操作。 |
| `useConnectorSetup(token, { backendUrl, storage, openPopup, onOpened })` | 连接链接（`/connect/<token>`）背后的流程：包含 `phase`（`loading`、`ready`、`starting`、`opened`、`connected`、`error`）、`info`、`error`、`connectedAs`、`connect()`。您需要自行提供弹窗打开器。 |
| `useFeatureFlag(projectId, key)` | `{ enabled, isLoading }`。加载中和出错时读取为 `false`。 |
| `useCan(target, action)` · `useCans(target, actions)` | `{ allowed, reason, isLoading, isError }` · 单个请求检查多个操作，返回以操作为键的映射（请保持 `actions` 在渲染间稳定）。`target` 为 `{ accountId }`、`{ accountId, resource }` 或 `{ projectId }`。加载中和出错时读取为 `allowed: false`。 |
| `usePermissionsFor(accountId, memberUserId, probes)` | 检查其他成员可执行的操作。需要 `member.read` 权限。 |
| `useSetBillingPlan()` | 针对 `billing.setPlan` 的变更（Mutation）Hook。 |
| `useGatewayOverview` · `useGatewaySeries` · `useGatewayBreakdown` · `useGatewaySessions` · `useGatewayErrors` | 过去 `days` 天（默认 30 天）的网关用量。 |
| `useGatewayLogs` · `useGatewayLog` · `useGatewayBudgets` · `useSetGatewayBudget` · `useDeleteGatewayBudget` · `useGatewayKeys` · `useCreateGatewayKey` · `useRevokeGatewayKey` · `useGatewayRoutingPolicy(projectId)` | 网关日志、预算、密钥和路由策略。 |
| `useProjectName(projectId)` | 项目的显示名称，来自单一缓存源。 |
| `useKortixViewer({ basePath? })` | 在使用 OpenChatly 登录的应用中：从 `<basePath>/me` 获取当前查看者，以及 `reload()` 方法。详见 [Sign in with OpenChatly（使用 OpenChatly 登录）](#使用-openchatly-登录)。 |
| `useArtifacts(projectId, { scope?, type?, q?, limit? }?)` · `useArtifact(projectId, artifactId, version?)` · `useArtifactText(projectId, artifact)` | 制品列表 · 单个制品（当前或某次保存时的状态） · 文档的 Markdown 内容。`prefetchArtifact(queryClient, projectId, artifactId)` 可在点击前预加载制品及文档 Markdown。详见 [Artifacts（制品）](#制品artifacts)。 |
| `useArtifactVersions(projectId, artifactId, enabled?)` · `useArtifactTypes(projectId)` | 保存记录 · 两种类型。 |
| `useArtifactMutations(projectId)` | 变更方法：`create`、`share`、`save`、`update`、`remove`、`pin` 和 `restore`。每个方法都会刷新列表和当前打开的制品。 |
| `useArtifactComments(projectId, artifactId, { status?, version?, enabled? }?)` | 评论线程（默认 `open`），附带 `create`、`reply`、`setStatus`、`edit`、`remove`、`send` 和 `isWriting` 方法。写入采用乐观更新（Optimistic）：每个加载的线程列表会立即显示更改，失败的写入仅撤销其自身的更改。在服务端确认之前，线程或评论会带有 `optimistic: true`。新条目还会带有 `optimistic-` 前缀的 ID、空作者（`user_id: ''`）以及所有 `can_*` 字段为 `false`：请将其渲染为待处理状态。传入 `version` 时，该 Hook 会拒绝所有写入。 |
| `useArtifactCommentContext(projectId, artifactId, { version?, agent?, enabled? }?)` | 评论上下文：权限、提及令牌、发送目标和 `agents_unavailable`。评论写入会刷新此上下文。 |
| `useArtifactActivity(projectId, artifactId, { limit?, cursor?, enabled? }?)` · `useInfiniteArtifactActivity(projectId, artifactId, { limit?, enabled? }?)` | 单页活动 · 所有页面，作为排序并去重的 `items`，附带 `olderVersions` 和 `fetchNextPage`。 |
| `useArtifactCommentScreenshot(projectId, artifactId, commentId)` | 单条评论的截图，类型为 `Blob`。该 Hook 在卸载后不会保留副本。 |
| `useProjectGoals` · `useSessionGoal` · `useProjectGoalFiles` | 目标（Goals）、会话正在处理的目标，以及单个目标的文件。目标为实验性功能，默认关闭。请在 **Project admin** → **Feature flags** 中开启。 |
| `useProjectTriggerEventApps` · `useProjectTriggerEventTypes` | 用于 `event` 触发器的连接器和事件类型。 |
| `useConnectorLinkInfo(token, options)` | 连接令牌背后的 `ConnectorSetupLinkInfo`，适用于卡片展示。加载期间为 `undefined`，请求失败时为 `null`。 |
| `useCaptureWorkspace` · `useSetCaptureEnabled` · `useCaptureDevices` · `useRevokeCaptureDevice` · `useCapturePolicy` · `useSetCapturePolicy` · `useCaptureDays` · `useCaptureTimeline` · `useCaptureTimelineItems` · `useCaptureSearch` · `useCaptureChunkMedia` · `useCaptureDeviceGrant` · `useApproveCaptureDevice` · `useDenyCaptureDevice` · `useCaptureStorage` · `useSetCaptureStorage` · `useCaptureEnrollments` · `useCaptureEnrollmentTokens` 及其创建、批准、拒绝和撤销 Hook · `useLinkCaptureDevice` | OpenChatly Capture。每个账户 Hook 的第一个参数为账户 ID。传入 `null` ID 不会发送请求。`useCaptureDevices` 每 10 秒轮询一次。 |

**多个 Hook 的通用规则：**

- `useCan` 及其相关 Hook 用于决定 UI 的显示内容。API 会对每次写入重新进行权限检查。请探测路由实际检查的操作（例如 `PROJECT_ACTIONS.PROJECT_GITOPS_PUSH` 即 `project.gitops.push`），**永远不要**直接检查角色。在更改访问权限的写入操作后，请调用 `invalidatePermissionProbes(queryClient, { accountId, userId })`。否则，判定结果会缓存 5 分钟。
- 运行时重启或配置重新加载后，请调用 `resetRuntimeQueries(queryClient)`。
- 制品评论、上下文和活动 Hook 在挂载且可见时每 10 秒轮询一次。它们需要 `artifact_comments` 功能标志，该标志为实验性且默认关闭。请在 **Project admin** → **Feature flags** → **Artifact comments** 中开启。

#### 查询键与缓存辅助工具（Query keys and cache helpers）

| 名称（Name） | 功能说明（What it does） |
| --- | --- |
| `qk` | 所有 Hook 的查询键（Query Key）工厂。包含以下系列（Families）：`qk.accounts`、`qk.projects`、`qk.project`、`qk.notifications`、`qk.drives`、`qk.capture`。除 `qk.capture` 外，每个系列都有 `scope(…)` 方法，用于生成所有键的前缀；`qk.capture.account(accountId)` 则是单个账户 Capture 键的前缀。示例：`qk.project.detail(projectId)`、`qk.project.secrets(projectId)`。 |
| `invalidateProject(queryClient, projectId)` | 使 `qk.project.scope(projectId)` 下的所有查询失效。 |
| `invalidatePermissionProbes(queryClient, { accountId?, userId? })` | 使缓存的 `useCan` 权限判定结果失效。 |
| `resetRuntimeQueries(queryClient)` | 移除所有运行时查询，确保下一次读取操作从新的运行时获取数据。 |
| `resetIdentityState(…)` | 在用户登出时清除个人状态。详见 [Sign-out and identity changes（登出与身份变更）](#退出登录与身份变更)。 |

```tsx
import { useQueryClient } from '@tanstack/react-query';
import { qk } from '@kortix/sdk/react';

function useRefreshSecrets(projectId: string) {
  const queryClient = useQueryClient();
  return () => queryClient.invalidateQueries({ queryKey: qk.project.secrets(projectId) });
}
```

### 无框架依赖模块（Framework-free modules）

根包 `@kortix/sdk` 在客户端旁导出了以下模块。

| 模块（Module） | 导出名称（Names） | 功能说明（What it does） |
| --- | --- | --- |
| 文件（Files） | `files`, `FileExistsError`, `uploadNativeFile` | 对进程级活动沙箱进行文件操作，包含 `s.files` 的方法。若宿主环境存在多个会话，请使用 `s.files`。 |
| 会话健康状态（Session health） | `getSessionHealth(runtimeUrl?, init?)`, `isRuntimeReady(health)`, `runtimeSupports(capabilities, name)` | 探测运行时并读取其能力（Capabilities）。 |
| 预览 URL（Preview URLs） | `detectLocalhostUrls`, `rewriteLocalhostUrl`, `proxyLocalhostUrl`, `parseLocalhostUrl`, `buildWebProxyUrl` | 将 Agent 的 `localhost` URL 重写为可访问的代理 URL。 |
| 事件流（Event stream） | `openEventStream`, `narrowChatEvent`, `heartbeatGapEvent` | `s.stream` 背后的实时流，以及用于聊天事件的窄化（Narrow）处理。 |
| 认证（Auth） | `authenticatedFetch`, `getAuthToken` | 一个会自动从您的 `getToken` 中添加令牌的 `fetch` 方法。 |
| API 客户端（API client） | `backendApi` | 所有方法底层的类型化 HTTP 客户端。仅用于没有封装方法的 API 路由。 |
| 错误（Errors） | `ApiError`, `AuthError`, `BillingError`, `RequestTooLargeError`, `isAuthFailure`, `isFeatureDisabledError`, `featureDisabledKey`, `FEATURE_DISABLED_CODE`, `REPOSITORY_DISCONNECTED_CODE` | 错误类型与检查工具。目录：[Errors and retries（错误与重试）](#错误与重试errors-and-retries)。 |
| 分类（Classify） | `classifyPart`, `classifyTurn`, `toolViewModel`, `toolInfo`, `humanizeToolName`, `toToolView`, `sessionLogTurns` 及其他回合辅助工具 | 将会话消息和会话日志块转换为可渲染的部分（Parts）。指南：[Render messages yourself（自行渲染消息）](#自行渲染消息)。 |
| 编辑器列表（Composer lists） | `projectConfigAgentsToRuntimeAgents`, `composerSelectableAgents`, `resolveComposerAgent`, `pickerProviderList`, `flattenModels`, `createModelVisibility`, `modelInDefaultView`, `resolveComposerModel`, `resolveModelDefault`, `sessionModelCandidates`, `latestPromptModel`, `modelRefToKey` | 按照 OpenChatly Web 应用的规则构建 Agent 选择器和模型选择器。所有函数均为纯函数。 |
| 对话记录导出（Transcript export） | `formatTranscript(session, messages, options?)` | 将单个会话格式化为 Markdown 字符串。 |
| 消息 ID（Message ids） | `mintWireMessageId()`, `WIRE_MESSAGE_ID` | 为提示词生成消息 ID · 验证消息 ID。**切勿**手动生成 ID。 |
| 按 ID 操作沙箱（Sandboxes by id） | `restartSandbox(id)`, `stopSandbox(id)`, `getSandboxById(id)` | 仅通过 `session_id` 对会话的沙箱进行操作。单次 `GET /sessions/:id` 即可找到项目（无论会话有多旧）。提供商外部 ID 仍可使用，但仅限于该会话位于其项目首页时。若已知项目 ID，请使用 `s.restart()`、`s.stop()` 和 `s.get()`。 |
| 沙箱，跨项目（Sandboxes, every project） | `getSandbox()`, `ensureSandbox()`, `listSandboxes(id?)` | 仅读取每个项目的首页会话（默认 50 行）。对于较旧的会话，请使用 `p.sessions.listPage()`。 |

#### 文件（Files）

```ts
import { FileExistsError, files } from '@kortix/sdk';

export async function saveNotes(file: File): Promise<void> {
  const { content } = await files.read('/workspace/README.md');
  console.log(content.length);

  await files.upload(file, '/workspace/uploads', file.name, {
    onProgress: ({ loadedBytes, totalBytes }) => console.log(loadedBytes, '/', totalBytes),
  });

  try {
    await files.create('/workspace/notes.md');
  } catch (error) {
    if (error instanceof FileExistsError) console.log('exists:', error.path);
    else throw error;
  }
}
```

| 方法（Method） | 行为说明（Behavior） |
| --- | --- |
| `upload(file, dir, name, { onProgress? })` | 8 MiB 或更小的文件通过单次请求上传。更大的文件按 8 MiB 分块上传，每块在到达服务端时都会进行校验。`onProgress` 回调会在每个分块上传完成后执行。 |
| `write(path, blob)` | 替换指定 `path` 处的文件。若 `path` 是一个文件夹，操作将失败。 |
| `create(path)` | 创建一个空文件，且绝不覆盖现有文件。若 `path` 处已存在任何内容，将抛出 `FileExistsError`（`status` 为 `409`，`code` 为 `FILE_EXISTS`）。 |
| `uploadNativeFile({ uri, name, type? }, targetPath?, baseUrl?)` | 通过单次请求上传 React Native 设备上的文件。字节流直接从 `uri` 传输，**不会**进入 JS 堆内存（JS heap）。 |

#### 会话健康状态（Session health）

`getSessionHealth(runtimeUrl?, init?)` 会发送 `GET {runtimeUrl}/kortix/health` 请求。即使返回非 2xx 状态码也**不会**抛出异常。它会返回 `{ status, ok, health, body, hop, upstreamStatus }`。若未提供运行时 URL，将返回 `status: 0` 和 `ok: false`。当运行时准备好接受工作时，`isRuntimeReady(health)` 返回 `true`。`s.health()` 是针对单个会话的相同探测方法。

#### 事件流（Event stream）

`openEventStream(options)` 会立即返回 `{ close() }`。`s.stream(options)` 会在 `ensureReady()` 之后，使用会话的运行时 URL 调用此方法。指向同一 URL 的流会共享同一个连接。

| 选项（Option） | 默认值（Default） | 功能说明（What it does） |
| --- | --- | --- |
| `url` | — | 会话运行时地址：`{backendUrl}/p/{externalId}/{port}`。 |
| `onEvent(event)` | — | 每次事件按顺序触发一次（合并后）。同一部分（Part）或同一会话日志块的连续增量（Deltas），若在同一次 16 毫秒的刷新中到达，将作为一个事件触发：`properties.delta` 为它们拼接后的文本，`coalesced` 列出被替换的事件。处理函数中抛出的异常会被捕获并记录日志。 |
| `onGapRehydrate(gapMs)` | — | 在重新建立连接时调用，传入自上一帧以来的时间差（毫秒）。当断开的流曾传递过事件，或时间差超过 5 秒时触发。 |
| `signal` | — | 当 AbortSignal 被中止时停止流，效果同 `close()`。 |
| `connectTimeoutMs` | `20000` | 在重试之前，等待连接调用的最大时间。 |
| `heartbeatTimeoutMs` | `60000` | 已打开的流在重新连接前允许的最大静默时间。 |
| `maxConsecutiveHardFailures` | `8` | 流进入“停泊（Parked）”状态前的连续严重失败次数。退避（Backoff）时间从 1 秒开始，最高上限为 30 秒。 |
| `onParked({ consecutiveFailures, lastError })` | — | 当流进入停泊状态时调用一次。停泊的句柄永远不会重连：请打开一个新的流。 |
| `onConnectionChange(state)` | — | 连接状态变更：`connecting`（连接中）、`open`（已打开）或 `lost`（已断开）。 |

`narrowChatEvent(event)` 将 `RuntimeEvent` 窄化为 `KortixChatEvent` 联合类型。事件列表详见 [Stream events（流事件）](#流式事件stream-events)。

#### 工作区搜索（Workspace search）

从 `@kortix/sdk/workspace-search` 导入的 `createWorkspaceSearchClient(fileClient, getCacheKey?)` 会返回一个基于会话工作区的文件和文件夹搜索客户端，带有缓存的索引，并按相关性排序。`fileClient` 需包含 `listFiles(path)` 和 `findFiles(query, options?)` 方法，形状与 `s.files` 相同。`getCacheKey` 用于划分缓存（例如按会话 ID 划分）。该模块还导出了排序辅助工具：`rankWorkspaceSearchEntry`、`searchIndexedWorkspaceEntries`、`normalizeSearchQuery` 和 `normalizeWorkspacePath`。

### 会话日志类型（Session log types）

根包导出了会话日志的类型（会话日志是与运行时无关的会话记录）及其常量。它不导出任何验证器。`s.log(query)` 用于读取单页数据。在 React 中，`useSessionLog` 和 `useSessionLogThread` 会返回该数据。

| 名称（Name） | 说明（What it is） |
| --- | --- |
| `SESSION_LOG_SCHEMA` · `SESSION_LOG_MINOR` | `'kortix.session/2'` · `1`。 |
| `SessionLog` | 记录主体：包含线程（Threads）、待办事项（Todos）、待处理的问题和权限、`harness`（写入该记录的运行时及运行时的历史记录）、`restore_grade`（恢复评级）。 |
| `SessionLogThread` · `SessionLogMessage` | 单个线程（主线程或子 Agent） · 单条消息，包含 `seq`、`role`、`kind`、`status`、`model`、`usage`、`blocks`。 |
| `SessionLogBlock` | 块的联合类型，包括 `TextBlock`、`ReasoningBlock`、`AttachmentBlock`、`ToolCallBlock`、`CompactionBlock`、`SubtaskBlock`、`StepBlock`、`HarnessBlock`，通过 `type` 字段进行区分。 |
| `ToolResultContent`, `CompactionLayoutEntry`, `ThreadInteraction`, `ModelRef` | 上述记录的组成部分。 |
| `KNOWN_TOOL_KINDS` · `KnownToolKind` · `SessionLogToolKind` | 每个读取器都会渲染的工具类型：`shell`、`read`、`write`、`edit`、`patch`、`list`、`glob`、`grep`、`web_fetch`、`web_search`、`todo`、`task`、`question`、`plan`、`mcp`、`other` · 块的工具类型（任意字符串）。遇到未知的类型时，请将其渲染为 `other`。 |
| `SessionLogTodo` | 单个待办事项。 |
| `RestoreGrade` · `GradeCounts` | 记录的恢复完整度（`native`、`converted` 或 `partial`） · 缺失内容的统计。 |
| `SessionLogPage` · `SessionLogPageQuery` | `s.log()` 的返回结果 · 其查询参数 `{ thread?, before_seq?, limit? }`。 |

超过 256 kB 的文本会通过引用进行存储，适用于 `TextBlock` 以及工具结果中的 `text` 项。此时，`text` 字段仅保存前 16 kB 的内容，`bytes` 字段保存完整文本的 UTF-8 字节长度，而 `ref` 字段的格式为 `kortix-attachment://<project_id>/<session_id>/<attachment_id>`。调用 `s.attachments.read(attachmentId)` 可将完整文本作为 `Blob` 返回，即使在沙箱停止的状态下也可使用。

```ts
import type { SessionLog, SessionLogBlock } from '@kortix/sdk';

export function toolCalls(log: SessionLog): SessionLogBlock[] {
  return log.threads
    .flatMap((thread) => thread.messages.flatMap((message) => message.blocks))
    .filter((block) => block.type === 'tool_call');
}
```

超过 256 kB 的文本可通过下方的全文辅助工具完整获取。`fetchSessionAttachment(ref)` 用于通过 `ref` 读取单个附件。

#### 对话记录类型（Transcript types）

`s.messages()` 和 `useSessionMessages` 会返回对话记录，其模式为 `kortix.transcript.v1`（`KORTIX_TRANSCRIPT_SCHEMA`）。其类型定义在 `packages/api-contract/src/transcript.ts` 中，SDK 根包会导出这些类型。

| 名称（Name） | 说明（What it is） |
| --- | --- |
| `KortixMessage` · `MessageWithParts` | 单条消息：`{ info, parts }`。`info` 为 `KortixUserMessageInfo` 或 `KortixAssistantMessageInfo`（包含 `role`、`time`、`agent`、`modelID`、`providerID`、`cost`、`tokens`、`error`、`parentID`）。 |
| `TranscriptPage` | `s.messages()` 的单页结果：`{ messages, hasMore }`，按时间从旧到新排序。 |
| `KortixPart` · `KortixPartType` | 消息部分的联合类型，通过 `type` 字段区分：`text`、`reasoning`、`file`、`tool`、`step-start`、`step-finish`、`snapshot`、`patch`、`agent`、`retry`、`compaction`、`subtask`。 |
| `KortixToolPart` · `KortixToolState` | 工具调用：包含 `callID`、`tool` 以及 `state`，其 `status` 为 `pending`、`running`、`completed` 或 `error`。 |
| `KortixMessageError` | 助手消息的错误，按 `name` 区分的联合类型。 |
| `TURN_ERROR_CODES` · `TurnErrorCode` · `isTurnErrorCode(value)` | 回合失败的原因：`auth`、`rate_limit`、`credits`、`context_length`、`output_length`、`aborted`、`unknown`。 |
| `PendingInteractions` · `RuntimePending` | 会话运行时正在等待的内容：状态、权限请求和问题。`s.pendingRequests()` 会返回 `RuntimePending`。 |
| `RuntimePermissionRequest` · `RuntimePermissionReply` · `RuntimeQuestionRequest` · `RuntimeQuestionAnswer` | 权限请求及其回复（`once`、`always`、`reject`） · 问题及其答案。 |

#### 会话日志辅助工具（Session log helpers）

来自根包 `@kortix/sdk` 的纯函数，用于处理会话日志块。它们不依赖 React 和 DOM。相关指南：[React > Render blocks from the session log（React > 从会话日志渲染块）](#从会话日志渲染内容块)。

| 名称（Name） | 功能说明（What it does） |
| --- | --- |
| `sessionLogTurns(thread, options?)` | 为每条用户消息生成一个 `SessionLogTurn`：包含 `id`、`user`、`assistant`（按 `reply_to` 及顺序排列的回复）、`partial`（提示词未加载完）、`blocks`、`status`、`error`（`code`、`message`、`details`、`raw`）、`cost`（按平台加价计算的回复用量）、`compaction`（`block`、`hasContent`、`inFlight`）、`threads`（其生成的子线程）、`plan`、`shell`（Shell 回合的 bash 调用，需要 `session.shell`）、`response`（最后一个文本块）、`attachments`、`live`、`queued`、`retrying`。选项：`busy`、`liveMessageId`、`held`（收件箱中按队列顺序挂起的提示词）、`threads`、`pricing`、`hideOutOfContext`。`hideOutOfContext: true` 会排除所有未处于流式传输中且 `in_context: false` 的消息。当消息及其派生字段发生变化时，回合会保持其身份标识。 |
| `sessionLogTurnSegments(blocks, options?)` | 回合的片段：`burst`（一段非文本块）、`text`、`standalone`（`show`、`image_gen` 或子 Agent 调用，或在 `standaloneCallIds` 中命名的调用）、`show-group`（相邻的 `show` 调用）。 |
| `splitSessionLogTurnWork(segments, { working })` | 已结算回合的折叠结果：`work`、`hoisted`（交付物：`show-group` 片段以及按调用顺序排列的 `show`、`show_user` 和 `image_gen` 调用）、`final`（最后的文本）。当回合正在执行或没有工作时返回 `null`。 |
| `sessionLogBurstSteps(blocks)` | Burst 的行：`thought`（一段推理）、`block`、`group`（同系列调用，包含 `family`、`label`、`status`）。已回答的问题作为单独的一行。 |
| `sessionLogBurstSummary(blocks)` | Burst 的步骤统计：`total`（一段推理计为 1）、`failed`、`completed`、`hasPlumbing`。 |
| `sessionLogBurstRunning(blocks, { working, trailing? })` | Burst 是否正在进行中。一旦回合停止工作，此值永远为 `false`。 |
| `sessionLogShowGroupCall(calls)` | 将 `show-group` 片段作为一个 `show` 调用：`input.items` 为轮播图；失败的调用会在其位置保留一个 `error` 项。 |
| `sessionLogAnsweredQuestionCall(call, answers, input?)` | 在运行时确认答案之前，将 `question` 调用显示为已回答。 |
| `sessionLogRetrying(thread)` | 线程的最后一条回复是否因提供商错误而处于打开且可重试的状态（读取时不对回合进行分组）。将其传入 `busy` 选项。 |
| `sessionLogActivityText(turn, childMessages?)` | 实时回合的活动提示行，例如 `Reading files...`。正在运行的任务会读取其子线程的消息。 |
| `sessionLogThreadMetrics(thread, options?)` | 单个线程的 `cost`、`messages`（`all`、`user`、`assistant`）、`tokens`（`input`、`output`、`reasoning`、`cacheRead`、`cacheWrite`）和 `context`（最后一条带 Token 的回复：其 `usage` 即为上下文大小）。选项：`pricing`。 |
| `classifySessionLogMessage(message)` | 针对单条会话日志消息的 `classifyTurn`：将其块作为 `ClassifiedPart` 返回，错误作为 `TurnError` 返回。适用于接收 `ClassifiedPart` 的渲染器。 |
| `sessionLogPromptMessage(prompt, threadId)` | 线程尚未放置的、已排队的收件箱提示词的用户消息：ID 为 `message_id`，否则为 `queued-<prompt_id>`。将其追加到线程消息之后，并在 `held` 中命名。 |
| `isSessionLogRestoreNote(message)` | 判断该消息是否为部分恢复（Partial restore）留给 Agent 的备注。请将其渲染为通知，而非用户的提示词。 |
| `sessionLogRestoreNotice(session)` | 部分恢复未能恢复的内容：`{ generation, missing }`，其中 `missing` 为 `{ kind, count }` 的列表（`attachment`、`text`、`tool_input`、`tool_result`、`cut_point`、`other`）。除非评级为 `partial` 且恢复操作写入了记录，否则返回 `null`。请传入 `useSessionLogRecord(session)`。 |
| `sessionLogReferencedTexts(messages)` | 对话记录渲染的通过引用存储的文本，每个 `ref` 仅出现一次：`{ ref, bytes }`。 |
| `sessionLogWithFullTexts(thread, texts)` | 返回 `thread`，其中 `ref` 作为 `texts` 键的每个文本都会被替换为完整文本。 |
| `sessionLogFullTextAction(refs)` | 当所有文本总计不超过 `SESSION_LOG_FULL_TEXT_INLINE_MAX_BYTES`（1 MiB）时返回 `'inline'`，否则返回 `'download'`。 |
| `sessionLogFullTextPlan(refs)` | `{ inline, download }`：最小的文本优先填满 1 MiB 的内联预算，其余的作为下载处理。 |
| `toolCallMetadata(call)` | 过渡性方法。获取运行时的工具调用显示元数据，例如 bash 的 `command` 或任务的 `sessionId`。若无元数据，返回一个共享的空对象。 |

`toToolView`、`getChildSessionId`、`partOutcome`、`contextToolTrigger` 和 `shouldShowToolPart` 既接受 `ToolCallBlock`，也接受 v1 工具部分。`freshSendHint` 和 `fallbackBusyRowAfterTurnId` 既接受 `SessionLogTurn[]`，也接受 v1 回合。`stepLabel` 接受任何会话日志块（非调用块通过其 `type` 读取）。**闭合规则**：由运行时闭合的调用（`result.synthetic`，或 `result.error.code` 为 `'interrupted'`）在实时回合中渲染为 `running` 或 `pending`，在其他任何情况下渲染为 `interrupted`。

```ts
import { sessionLogCallStatus, sessionLogTurnSegments, sessionLogTurns, type SessionLogThread } from '@kortix/sdk';

export function standaloneCalls(thread: SessionLogThread, busy: boolean) {
  return sessionLogTurns(thread, { busy }).flatMap((turn) =>
    sessionLogTurnSegments(turn.blocks)
      .filter((segment) => segment.kind === 'standalone')
      .map((segment) => ({ segment, status: sessionLogCallStatus(segment.block, turn.live) })),
  );
}
```

#### 图片卡片（The image card）

宿主环境用于渲染 `image_gen` 调用的组件。这是纯数据，从 `@kortix/sdk` 和 `@kortix/sdk/turns` 导出。`image_gen` 调用是一种交付物（Deliverable）：它是一个 `standalone`（独立）片段，并且会像 `show` 一样被提升（Hoisted）到最终文本之上。

| 名称（Name） | 功能说明（What it does） |
| --- | --- |
| `imageGenView(call, live?)` | 将单个 `ToolCallBlock` 转换为 `ImageGenView` 卡片。单次调用可请求 1 到 4 张图片。调用信息包含：`phase`（`ImageGenPhase`：`generating`、`ready`、`failed` 或 `stopped`）、`action`（`generate` 或 `edit`）、`prompts`（调用的提示词；Phase 1 调用仅有一个 `prompt`）、`aspectRatio`（`"<w> / <h>"`：调用请求的比例，否则为 `1 / 1`；在所有阶段保持一致，以便多张图片的布局能在图片落地前确定矩形大小）、`startedAt`（从调用开始计算的纪元毫秒数）、`model` 和 `provider`（生成图片的模型，如 `google/gemini-2.5-flash-image`，以及响应请求的提供商，来自工具输出；在调用完成前或输出未指定时为 `null`）、`error`（整个调用的失败信息）、`images`。因中断、闭合规则结果或中止文本而失败的调用状态为 `stopped`。已完成但没有图片路径或 URL 的调用状态为 `failed`。未完成的调用在 `live` 为 `false` 时状态为 `stopped`，否则为 `generating`。 |
| `ImageGenView['images']` | 每张图片对应一个帧（Frame）：调用运行期间每个提示词对应一帧（参数流式传输时为一帧），随后是调用生成的每张图片及失败的每个提示词，按提示词顺序排列。当整个调用 `failed` 或 `stopped` 时为空。帧包含 `prompt`、`phase`（`generating`、`ready` 或 `failed`）、`aspectRatio`（`"<w> / <h>"`：图片生成后为实际尺寸，否则为请求的 `aspect_ratio`（`16:9` 表示为 `16 / 9`），或旧版请求的 `size`；`auto` 或两者皆无时默认为 `1 / 1`）、`imagePath`（沙箱文件：`.png`、`.jpg` 或 `.webp`）、`directUrl`（旧版无路径的单图输出；仅为 http(s) URL，绝不会与 path 同时存在）和 `error`（该提示词的失败信息）。旧版单图输出（`{"path"}`、Replicate URL 或裸路径）视为一个帧。 |
| `ImageGenView['error']` | 包含 `message`、`suggestion?`（第一句话之后的文本）、`code?`（网关尾部的 `[code]`，如 `provider_not_connected` 或 `image_rate_limited`）、`retryAfterSeconds?`（来自 `Retry after N s.`）、`limit?`（`'turn'` 或 `'session'`：工具自身的图片上限在发起请求前拒绝了整个调用；此时不渲染任何内容）、`connectModel`（仅在 `image_model_unavailable`、`provider_not_connected` 或 `provider_reauth_required` 时为 true：在项目设置中连接模型即可修复该调用）。在视图（View）上，除非 `phase` 为 `failed`，否则为 `null`；在帧（Frame）上，除非其 `phase` 为 `failed`，否则为 `null`。 |
| `imageGenRetryDelay(seconds)` | 返回 `{ value, unit }`：90 秒以下取整秒（至少为 1），90 分钟以下取分钟，否则取小时，均向上取整。 |
| `formatImageGenElapsed(ms)` | 将耗时格式化为 `m:ss`，例如 `0:42` 或 `2:05`。 |
| `ImageGenView['images'][i].sha256` | 可选。当 `image_gen` 输出指定了该值时，为已保存文件字节的十六进制小写 sha256。旧版输出没有此字段；格式错误的值会被丢弃。 |
| `imagePathsShownByImageGen(blocks)` | `blocks` 中的 `image_gen` 调用所绘制的图片路径（每个调用的每个 `ready` 帧），每个路径均不带 `/workspace/` 前缀。 |
| `imageDigestsShownByImageGen(blocks)` | `blocks` 中的 `image_gen` 调用所绘制的每张图片的 `sha256`（当输出指定了该值时）。 |
| `showItemDigest(call, path)` | `show` 调用的输出为 `path` 处的文件（其单个 `entry` 或 `items` 之一）提供的 `sha256`，匹配时带或不带 `/workspace/` 前缀均可；当输出未指定时返回 `undefined`。`sessionLogShowGroupCall` 的项会将其作为 `sha256` 携带。 |
| `withoutImageGenDuplicates(items, paths, digests?)` | 从 `items` 中移除 `path` 在 `paths` 中（带或不带 `/workspace/` 前缀）或 `sha256` 在 `digests` 中（即在其他路径下的相同字节，如 Drive 副本）的项。两者皆不匹配的项保留。 |
| `showDrawnByImageGen(call, paths, digests?)` | 当 `call` 为 `show` 或 `show_user` 调用，且其命名的每个文件（`items` 或 `path`）都在 `paths` 中，或在其输出提供的摘要中存在于 `digests` 中时返回 true：此时宿主环境不为其渲染任何内容。 |
| `sessionLogImageGenRuns(segments, { paths, digests })` | 将作为单个网格绘制的 `image_gen` 调用序列作为 `Map` 返回，键为每个成员的块 ID，值为所属序列：两个或多个独立的 `image_gen` 调用，且中间没有可见的非图片交付物（已经由卡片绘制的 `show`、burst 或文本不会打断序列，因为已结算的回合会将交付物一起提升）。宿主环境仅在 `run[0]` 处绘制网格，其余位置不绘制。 |
| `imageGenGrid(views)` | 将序列的单个网格作为 `ImageGenGrid` 返回：包含 `tiles`（`ImageGenGridTile`：`image`、调用在序列中的索引 `call`、每个调用的首个瓦片标记 `first`），按调用顺序排列；`rows`（每行的瓦片数）；以及 `strip`。最多 4 个瓦片时为 Bento 布局；5 个及以上时为每行 3 个，若能整除则为每行 4 个，或分为一行/两行每行 2 个（5 = 3+2, 6 = 3+3, 7 = 3+2+2, 8 = 4+4）。当序列的首个调用请求竖屏图片时，`strip` 为 `true`：每行瓦片并排显示（最多 4 个），各行尽可能均匀分布（5 = 3+2, 7 = 4+3, 10 = 4+3+3）。整体失败或停止的调用每个提示词保留一个槽位，但因图片上限被拒绝的调用（`error.limit`）不占槽位。 |
| `createImageCache({ maxEntries, maxBytes?, dispose? })` | 无框架依赖的已加载图片缓存 `ImageCache<V>`（`V` 为宿主环境的绘制来源：对象 URL 或原生源）。`get(ref)`（`ImageCacheRef`：`path?`、`sha256?`）：若有 `sha256`，仅匹配该字节的条目，绝不匹配其他字节的路径条目；否则匹配 `path` 处的条目。`put(ref, value, bytes?)`（相同摘要的现有条目优先，新值被销毁）、`link(path, entry)`、`setSize(entry, w, h)`、`retain(entry)`（被持有的条目永远不会被驱逐；返回释放函数）、`forget(path)`、`clear()`、`subscribe(listener)`。当超过 `maxEntries` 或 `maxBytes` 时，最久未使用且未被持有的条目会被驱逐并传给 `dispose`。`ImageCacheEntry` 包含 `value`、`bytes`、`width`、`height`。 |

```ts
import {
  imageDigestsShownByImageGen,
  imageGenGrid,
  imageGenView,
  imagePathsShownByImageGen,
  sessionLogImageGenRuns,
  showDrawnByImageGen,
} from '@kortix/sdk';

const drawn = imagePathsShownByImageGen(turn.blocks);
const view = imageGenView(call, turn.live);
for (const image of view.images) {
  if (image.phase === 'ready' && image.imagePath) renderImage(image.imagePath, image.aspectRatio);
  else if (image.phase === 'failed') renderNote(image.error?.message);
  else renderPlaceholder(image.aspectRatio, image.prompt);
}
if (showDrawnByImageGen(showCall, drawn, imageDigestsShownByImageGen(turn.blocks))) skip(showCall); // the image card already shows it

// Consecutive image_gen cards of a turn draw as one grid at the first call.
const runs = sessionLogImageGenRuns(segments, { paths: drawn, digests: imageDigestsShownByImageGen(turn.blocks) });
const run = runs.get(call.id);
if (run && run[0] === call) renderGrid(imageGenGrid(run.map((one) => imageGenView(one, turn.live))));
```

聊天行为的相关说明详见 [The image card in the chat（聊天中的图片卡片）](#聊天中的图像卡片the-image-card-in-the-chat)。

#### v1 回合辅助函数（v1 turn helpers）

针对 v1 消息（`MessageWithParts`、`kortix.transcript.v1`、`KORTIX_TRANSCRIPT_SCHEMA`）的纯函数，这也是 `s.messages()` 和 `useSessionMessages` 返回的数据结构。

| 名称（Names） | 功能说明（What they do） |
| --- | --- |
| `groupMessagesIntoTurns(messages)` · `collectTurnParts(turn)` | 将每条用户消息与其对应的助手回复进行配对 · 获取单个回合的所有部分（Parts）。 |
| `findLastTextPart(parts)` · `turnHasSteps(parts)` | 获取最终的回答文本 · 判断该回合是否包含工具、压缩（Compaction）、快照（Snapshot）或补丁（Patch）部分。 |
| `getTurnStatus(parts, childMessages?)` · `getWorkingState(…)` · `formatDuration(ms)` | 获取状态行，例如 `Reading files...`。传入 `childMessages` 可显示子 Agent 的活动状态。 |
| `getTurnError(turn)` · `getChildSessionError(messages)` · `unwrapError(error)` | 获取标准化的回合错误和子 Agent 错误。 |
| `getRetryInfo(status)` · `getRetryMessage(status)` | 获取重试状态 `{ attempt, message, next, details? }` · 获取完整的重试消息。 |
| `getChildSessionId(part)` · `getChildSessionToolParts(messages)` · `rootRuntimeSession` · `directSubsessions` · `runtimeSessionsOf` · `projectSessionForRuntimeId` | 将委派（Delegating）工具调用与其子对话关联起来。 |
| `getHiddenToolParts(…)` · `isToolPartHidden(…)` | 获取对话记录中隐藏的工具部分。 |
| `isTextPart`, `isToolPart`, `isReasoningPart`, `isFilePart`, `isAgentPart`, `isCompactionPart`, `isSnapshotPart`, `isPatchPart`, `isStepPart`, `getPartText` | 类型守卫（Type guards）。 |
| `sortSessions(now)` · `childMapByParent(sessions)` · `allDescendantIds(map, id)` | 会话列表排序与层级关系。 |
| `getFilename`, `getDirectory`, `relativizePath`, `stripAnsi`, `formatTokens` | 格式化工具。 |

分组和状态函数接受结构化类型 `PartLike`、`MessageInfoLike`、`TurnLike`、`ToolStateLike` 和 `SessionStatusLike`，因此您自定义的消息结构同样适用。

### 废弃的名称（Deprecated names）

以下列出的每个名称都带有 `@deprecated` 标记，并将在下一个大版本中移除。您的编辑器会标记每一次使用。此列表并不完整：您的编辑器同样会标记所有其他废弃名称，并且当存在替代方案时，`@deprecated` 标签会指明替代项。

#### 子路径（Subpaths）

这些子路径会重新导出根包或 `@kortix/sdk/react` 已经导出的名称，或者封装了内部 Store。

| 子路径（Subpaths） | 替代方案（Use instead） |
| --- | --- |
| `/config`, `/auth`, `/api-client`, `/projects-client`, `/feature-flags`, `/fresh-sessions`, `/instance-routes`, `/platform-client`, `/event-stream`, `/files`, `/session`, `/session/url`, `/turns` | 根包 `@kortix/sdk` 中的同名导出。 |
| `/sync-store`, `/server-store`, `/sandbox-connection-store`, `/idb-sync-cache`, `/internal/sync-store`, `/internal/server-store`, `/internal/sandbox-connection-store` | 无替代方案。请使用 `useSession` 读取会话状态。 |
| `/message-queue` | `s.send` 或 `useSession().send`。OpenChatly 会在服务端对提示词进行排序。 |

#### 名称（Names）

| 已废弃（Deprecated） | 替代方案（Use instead） |
| --- | --- |
| `claimNext`, `completeInFlight`, `createSessionQueue`, `editQueued`, `enqueue`, `failInFlight`, `removeQueued`, `reorderQueued`, `retryFailed`, `QueuedMessage`, `QueuedMessageInput`, `SessionQueue` | `s.send` 或 `useSession().send`。 |
| `wireIdClock`, `wireIdClockAt`, `wireIdClockDelta`, `maxWireIdClock`, `isWireIdAheadOf`, `newestWireIdClock`, `mintWireMessageIdAbove`, `MintWireMessageIdAboveInput`, `MintedWireMessageId`, `WIRE_ID_TIME_SCALE`, `WIRE_ID_TIME_MASK`, `WIRE_ID_CLOCK_TOLERANCE`, `WIRE_ID_BACKDATE_MS` | `mintWireMessageId` 和 `WIRE_MESSAGE_ID`（保持最新）。消息 ID 是不透明的。 |
| `s.runtime` | 会话方法：`messages`, `pendingRequests`, `answerPermission`, `answerQuestion`, `compact`, `send`, `abort`, `rewind`。 |
| `s.transcript()` · `s.transcriptSync()` | `s.log(query)`。 |
| `s.pending()` | `s.pendingRequests()`。 |
| `p.sessions.ensureWarm()` · `p.sessions.claimWarm(input)` | `p.sessions.create()`。它们会抛出 `ENDPOINT_RETIRED` 拒绝错误。 |
| `findActiveTranscriptShare`, `getPublicSessionShare`, `getPublicSessionShareMessages`, `PublicSessionShareError`, `PublicSessionShareMeta`, `PublicSessionTranscript`, `PublicSessionTranscriptMessage`, `PublicSessionTranscriptToolCall` | 无替代方案。API 已移除公开对话记录分享功能；所有调用均返回 `404`。 |
| `clientSource`（`createKortix` 的一个选项） | 移除该选项。它已失效。请发送 `clientVersion` 来标识版本。 |
| `p.updateExperimentalFeature` · `updateExperimentalFeature` · `ExperimentalFeatureKey` · `ExperimentalFeatureView` | `p.updateFeatureFlag` · `updateFeatureFlag` · `FeatureFlagKey` · `FeatureFlagView`。 |
| `p.connectors.setAuthorizationStrategy` · `setConnectorAuthorizationStrategy` | 移除该调用。它不会产生任何更改。 |
| `getConnectionPolicies` · `setConnectionPolicies` | `p.connectors.policies.get` · `p.connectors.policies.set`。 |
| `pipedreamConnect` · `pipedreamFinalize` · `p.connectors.connections.pipedreamConnect` · `.pipedreamFinalize` | `connectorConnect` · `connectorFinalize`。 |
| `listDiscoverIntegrations` · `getDiscoverIntegration` · `DiscoverIntegration*` 类型 | `listDiscoverConnectors` · `getDiscoverConnector` · `DiscoverConnector*` 类型。 |
| `SessionScopeResult` · `toWorkspaceRelative` | `SessionScope` · `toDaemonPath`。 |
| `setCachedAuthToken` · `setBootstrapAuthToken` | 从您自己的 `getToken` 中返回令牌。 |
| `billing.checkout.createSession` · `billing.checkout.confirmSession` · `createPerSeatCheckout` · `claimPerSeatBilling` | `billing.setPlan(input)`。它们会抛出 `ENDPOINT_RETIRED` 拒绝错误且不发送任何请求。 |
| `billing.subscription.scheduleDowngrade` · `.cancelScheduledChange` · `.prorationPreview` | `billing.setPlan(input)` 或 `billing.subscription.createPortalSession`。它们会抛出 `ENDPOINT_RETIRED` 拒绝错误。 |

其他废弃的根包名称封装了 API 不再提供的路由。它们会抛出 `ENDPOINT_RETIRED` 拒绝错误、解析为 `null` 或返回 `404`，且没有替代方案。

### 持久化会话模型控制（Durable session model controls）

`session.setModel()` 仅作为本地偏好，仅对通过该 SDK 句柄发起的后续发送生效。
`session.getModel()` 读取持久化固定配置（`{ model: string | null }`）。
`session.changeModel(model)` 保存持久化固定配置，且不会发送提示词。
Pi 会在不重启的情况下重新配置；当前正在运行的回合会执行完毕，新模型会在下一个回合生效。

**Agent 固定配置、权限与优先级。** Agent 配置的 `model` 仅作为默认值，而非强制锁定：已授权的调用者可以使用会话的持久化固定配置来替换它。更改该固定配置需要会话所有者或项目管理员的生命周期权限；作用域受限的 Agent 令牌还需要 `project.session.stop` 权限。仅拥有项目可见性（Project visibility）不会授予覆盖权限。请求的模型必须通过账户/模型可用性以及提供商密钥访问检查；更改固定配置不会绕过这些检查。

在 Pi 初始化或重新配置时，持久化固定配置的优先级高于默认的 Agent/项目模型。对于单个回合，显式指定的提示词模型具有最高优先级；其次，显式选择的 Agent 的配置模型具有更高优先级；最后才应用当前会话的选择。针对单次提示词的覆盖不会重写持久化固定配置。`switchModel` 会将其后续操作（Continuation）显式地以请求的模型加入队列，因此即使 Agent 有默认模型，该后续操作也会使用切换后的模型。当前正在运行的回合会保持其原有模型；新的选择将应用于后续回合。

```ts
await session.switchModel({
  model: 'kortix/glm-5.3-flash',
  prompt: 'Continue verification with the new model.',
  idempotency_key: 'verification-model-1',
});
```

模型切换会在同一个数据库事务中保存固定配置（Pin）并将后续操作（Continuation）加入队列。
在传输失败后，请重用相同的密钥（Key）和负载（Payload）。使用相同密钥但不同负载的请求会被拒绝。
自我切换（Self-switches）限制为每小时最多 3 次。已排队的后续操作会等待当前回合完成。
响应中包含 `prompt_id` 和 `deduped`；在报告实时应用状态之前，请先检查 `push_failed` 字段。

**CLI 命令**：`kortix sessions model get [session-id]`、`set [session-id] <model>` 以及 `switch [session-id] <model> --prompt "Continue verification" --idempotency-key verification-model-1`。
新命令默认使用 `KORTIX_SESSION_ID` 环境变量。现有的 `sessions model <session-id> <model>` 命令仍然受支持。
**切勿**向自身发送对等消息（Peer message）来继续模型切换。
