> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/character-versioning.md).

# 连接到角色版本

连接到角色的草稿、最新发布版本或带标签的版本，并从客户端列出、比较、发布、提升和丢弃版本。

每个角色都有一个可编辑的草稿；发布后，还会有一组不可变的带标签版本，例如 `1.0` 和 `1.1`。可移动的 `latest` 指针指定客户端未设置选择器时运行时使用的发布版本。使用此页面测试草稿中的更改，在准备就绪后发布一个标签，并通过将 `latest` 指向较早的标签来回滚。

{% hint style="warning" %}
角色版本控制目前处于 Beta 阶段。显式选择器（`draft`, `latest` 或某个标签）可在生产环境和暂存环境中使用。不支持角色版本解析的部署（例如自托管运行时）会以 `503 Character version resolution is unavailable`响应这些选择器。省略 `characterVersion` 则会像以前一样工作。
{% endhint %}

### 前提条件

* 已安装 Convai Web SDK，并且客户端可以连接。请参阅 [Web SDK 快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/quickstart.md).
* 一个 Convai API 密钥。 `client.characterVersions` 在没有 API 密钥时为 `null` 。

### 选择版本选择器

在客户端配置中设置 `characterVersion` ，以选择要运行的版本。

| `characterVersion`  | 运行的版本                                               |
| ------------------- | --------------------------------------------------- |
| *（省略）*              | 当前生效的最新发布版本。早于版本控制功能创建的角色仍按原方式运行。                   |
| `'draft'`           | 可编辑的草稿，用于测试尚未发布的更改。                                 |
| `'latest'`          | 明确指定已提升为最新版本的发布版本。                                  |
| `'1.2'` / `'1.2.3'` | 不可变的带标签版本，格式为 `major.minor` 或 `major.minor.patch` 。 |

在线路传输时，选择器会与角色 ID 拼接为 `<uuid>-draft`, `<uuid>-latest` 或 `<uuid>-1.2`. `characterId` 也可以直接包含该后缀；只有两者一致时才允许同时设置。连接后， `client.characterId` 仍会返回不带后缀的 UUID， `client.characterVersion` 会返回选择器，而 `client.characterReference` 会返回拼接后的形式。

### 连接到某个版本

`characterVersion` 是 `ConvaiConfig`的一部分，因此可以将它传递给 `useConvaiClient`, `new ConvaiClient()` 或 `connect()`.

{% tabs %}
{% tab title="React" %}
{% code title="src/App.tsx" %}

```tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

export default function App() {
  const client = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    characterVersion: 'draft', // or 'latest', '1.2', or omit
  });

  return <ConvaiWidget convaiClient={client} />;
}
```

{% endcode %}

该钩子会返回 `characterVersion`, `characterReference` 和 `characterVersions` 以及其他客户端成员。
{% endtab %}

{% tab title="TypeScript" %}
{% code title="src/main.ts" %}

```typescript
import { ConvaiClient } from '@convai/web-sdk/core';
import { createConvaiWidget } from '@convai/web-widget/vanilla';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  characterVersion: 'latest',
});

await client.connect();

createConvaiWidget(document.body, { convaiClient: client });
```

{% endcode %}
{% endtab %}
{% endtabs %}

更改版本意味着开启新会话。请先调用 `disconnect()`，然后使用新配置调用 `connect()` 。 `reconnect()` 会复用已存储的配置，包括其 `characterVersion`.

如果标签未知，则会报错： `404 Character version was not found`.

### 管理版本

`client.characterVersions` 会为已配置的角色返回一个 `CharacterVersionManager` 。只要配置中包含 `apiKey` 和 `characterId`，就可以使用它；即使尚未连接也可使用，因此你可以先列出版本并选择一个，然后再连接到该版本。

默认情况下，管理器会调用 `https://api2.convai.com`。将 `characterApiUrl` 设为 `https://api2-stg.convai.com` 即可在预发布环境中使用。

{% tabs %}
{% tab title="React" %}
{% code title="src/App.tsx" %}

```tsx
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';

export default function App() {
  const client = useConvaiClient({
    apiKey: 'YOUR_API_KEY',
    characterId: 'YOUR_CHARACTER_ID',
    characterVersion: 'draft',
    characterApiUrl: 'https://api2-stg.convai.com', // optional, defaults to production
  });

  const release = async () => {
    const versions = client.characterVersions;
    if (!versions) return; // no apiKey configured
    const { has_unpublished_changes, latest_version } = await versions.list();
    if (has_unpublished_changes) {
      await versions.create('1.1', { makeLatest: true });
    }
    console.log('latest was', latest_version);
  };

  return (
    <>
      <button onClick={release}>将草稿发布为 1.1</button>
      <ConvaiWidget convaiClient={client} />
    </>
  );
}
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="src/main.ts" %}

```typescript
import { ConvaiClient } from '@convai/web-sdk/core';
import { createConvaiWidget } from '@convai/web-widget/vanilla';

const config = {
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
};

const client = new ConvaiClient(config);
const versions = client.characterVersions;

if (versions) {
  // 检查草稿中的更改，然后发布。
  const diff = await versions.diff('latest', 'draft', { view: 'semantic' });
  diff.changes.forEach((c) => console.log(`${c.change_type} ${c.label}`));
  const released = await versions.create('2.0', { makeLatest: true });

  // 连接到刚刚发布的标签。
  await client.connect({ ...config, characterVersion: released.version });
}

createConvaiWidget(document.body, { convaiClient: client });
```

{% endcode %}
{% endtab %}
{% endtabs %}

每个方法都会按原样返回 API 的 JSON，其中字段名为 snake\_case。SDK 会先在本地检查选择器或标签；格式不正确时，会在发送请求前抛出错误。

#### 列出版本

`list()` 会在 `items`中返回已发布的标签，以及 `latest` 和草稿的状态。

```ts
const { items, latest_version, draft_revision_id, has_unpublished_changes } = await versions.list();
```

`has_unpublished_changes` 在 `true` 草稿与其分支来源的版本不同时，该值为 true。 `draft_revision_id` 在 `null` 对于早于版本管理功能创建且尚无草稿的角色，该值为 null。

#### 比较版本

`diff(from, to)` 用于比较两个选择器。每一侧可以是 `'draft'`, `'latest'` 或一个标签。

```ts
const raw = await versions.diff('1.0', '1.1');                                 // JSON 路径
const semantic = await versions.diff('latest', 'draft', { view: 'semantic' }); // 带标签的更改
```

默认的原始视图会列出发生变化的 JSON 路径。语义视图会将它们归类为带标签的更改，每项更改都有一个 `change_id` ，可传给 `revert()`.

#### 发布草稿

`create(version)` 会将当前草稿发布为不可变标签。标签必须采用 `major.minor` 或 `major.minor.patch`. `latest` 不会移动，除非传入 `makeLatest: true`.

```ts
await versions.create('1.1');                       // 仅创建标签，latest 保持不变
await versions.create('1.2', { makeLatest: true }); // 创建标签并将 latest 指向它
```

#### 提升版本或回滚

`promote(version)` 将 `latest` 指向一个已发布的标签。提升较旧的标签即可回滚；较新的标签仍可通过其标签连接。

```ts
await versions.promote('1.1'); // latest → 1.1
await versions.promote('1.0'); // 回滚：latest → 1.0
```

#### 丢弃或撤销草稿更改

`discardDraft()` 会将草稿重置为其已发布的父版本。 `revert()` 会撤销语义差异中的一项更改。这两个方法都需要传入你上次看到的草稿修订版本。

```ts
const { draft_revision_id } = await versions.list();
if (draft_revision_id) {
  await versions.discardDraft(draft_revision_id);
}
```

```ts
const diff = await versions.diff('latest', 'draft', { view: 'semantic' });
const change = diff.changes.find((c) => c.can_revert);
if (change && diff.draft_revision_id) {
  await versions.revert({
    from: 'latest',
    changeId: change.change_id,
    expectedDraftRevisionId: diff.draft_revision_id,
  });
}
```

{% hint style="info" %}
`discardDraft()` 和 `revert()` 若草稿在你读取其修订版本后发生了变化，就会拒绝执行，以免并发编辑被悄然丢弃。发生失败后，请再次调用 `list()` 以获取当前的 `draft_revision_id`.
{% endhint %}

#### 从已发布版本创建分支

`fork(version)` 会用某个已发布标签的内容替换草稿，这样你就可以从较旧的版本开始新的工作。将你上次看到的草稿修订版本作为第二个参数传入；如果期间有其他人修改了草稿，操作就会被拒绝。

```ts
const { draft_revision_id } = await versions.list();
await versions.fork('1.0', draft_revision_id ?? undefined);
```

#### 弃用标签

`deprecate(version)` 会将标签标记为已弃用，而 `deprecate(version, false)` 会清除该标记。已弃用的标签仍可连接。

#### 为旧版角色创建草稿

`bootstrap()` 会为早于版本控制功能的角色创建草稿。此操作具有幂等性： `created` 为 `false` 表示该角色已有草稿。

```ts
await versions.bootstrap();
```

### 在不使用客户端的情况下使用管理器

`CharacterVersionManager` 可以独立构造，并使用 API 密钥或 Convai 个人访问令牌。请从以下位置导入： `@convai/web-sdk/core` 或 `@convai/web-sdk/vanilla`.

{% code title="versions.ts" %}

```ts
import { CharacterVersionManager } from '@convai/web-sdk/core';

const versions = new CharacterVersionManager({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
});

const { has_unpublished_changes } = await versions.list();
```

{% endcode %}

### 处理错误

非 2xx 响应会被拒绝，并返回 `CharacterApiError`。其 `status` 是 HTTP 状态码，而 `detail` 是解析后的响应正文。

```ts
import { CharacterApiError } from '@convai/web-sdk/core';

try {
  await versions.promote('9.9');
} catch (err) {
  if (err instanceof CharacterApiError) {
    console.error(err.status, err.detail);
  }
}
```

| 错误                                                         | 原因                                                          |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| `503 Character version resolution is unavailable`          | 运行时无法解析显式选择器，例如未部署角色版本解析功能的自托管部署。此时请省略 `characterVersion` 。 |
| `404 Character version was not found`                      | 此角色不存在该标签。                                                  |
| `403` 来自 `resolve()`                                       | `includeRuntimeSettings` 仅供可信服务使用。API 密钥无法请求此项。             |
| `Expected "draft", "latest", or a major.minor[.patch] tag` | 选择器格式错误，会在发送请求前于本地被拒绝。                                      |

### API 参考

| 属性 / 方法                                               | 类型                                                                       | 说明                                                                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `ConvaiConfig.characterVersion`                       | `'draft' \| 'latest' \| string \| null`                                  | 要连接的版本。 `major.minor[.patch]` 字符串用于选择标签。省略时使用有效的最新版本。                                                             |
| `ConvaiConfig.characterId`                            | `string`                                                                 | 可直接携带选择器，格式为 `<uuid>-draft`。仅当两者一致时，才允许同时设置。                                                                      |
| `ConvaiConfig.characterApiUrl`                        | `string`                                                                 | 以下对象的基础 URL： `client.characterVersions`。默认值为 `https://api2.convai.com`；staging 环境为 `https://api2-stg.convai.com`. |
| `client.characterId`                                  | `string \| null`                                                         | 当前连接对应的纯角色 UUID。                                                                                                  |
| `client.characterVersion`                             | `CharacterVersionSelector \| null`                                       | 当前生效的选择器，或 `null` （未指定版本时）。                                                                                       |
| `client.characterReference`                           | `string \| null`                                                         | 发送给运行时的组合值 `<uuid>[-selector]` 。                                                                                  |
| `client.characterVersions`                            | `CharacterVersionManager \| null`                                        | 已配置角色的版本管理器； `null` 未配置 `apiKey`.                                                                                 |
| `new CharacterVersionManager(options)`                | `{ characterId, apiKey?, personalAccessToken?, baseUrl?, workspaceId? }` | 独立构造。必须提供一种凭据。                                                                                                    |
| `list()`                                              | `Promise<CharacterVersionList>`                                          | 已发布的标签，以及 `latest_*`, `draft_*` 和 `has_unpublished_changes` 字段。                                                   |
| `resolve(version?, { includeRuntimeSettings? })`      | `Promise<ResolvedCharacterVersion>`                                      | 运行时针对该引用将运行的配置快照。                                                                                                 |
| `diff(from, to, { view? })`                           | `Promise<CharacterVersionRawDiff \| CharacterVersionSemanticDiff>`       | 比较两个选择器。 `view: 'semantic'` 返回带标签且可还原的更改。                                                                         |
| `create(version, { makeLatest? })`                    | `Promise<CharacterVersionInfo>`                                          | 将草稿发布为不可变标签。                                                                                                      |
| `promote(version)`                                    | `Promise<CharacterVersionInfo>`                                          | 将 `latest` 指向某个已发布标签。                                                                                             |
| `discardDraft(expectedDraftRevisionId)`               | `Promise<DiscardCharacterDraftResult>`                                   | 将草稿重置为其已发布的父版本。                                                                                                   |
| `revert({ from, changeId, expectedDraftRevisionId })` | `Promise<RevertCharacterChangeResult>`                                   | 撤销草稿中的一项语义更改。                                                                                                     |
| `fork(version, expectedDraftRevisionId?)`             | `Promise<ForkCharacterVersionResult>`                                    | 用某个已发布标签的内容替换草稿。                                                                                                  |
| `deprecate(version, deprecated = true)`               | `Promise<CharacterVersionInfo>`                                          | 标记或取消标记某个标签为弃用。弃用的标签仍可用于连接。                                                                                       |
| `bootstrap()`                                         | `Promise<CharacterDraftBootstrapResult>`                                 | 为版本控制引入之前的角色创建草稿。                                                                                                 |
| `CharacterApiError`                                   | `Error` 包含 `status: number`, `detail: unknown`                           | Character API 返回任何非 2xx 响应时都会拒绝。                                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/character-versioning.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
