> 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/actions.md).

# Actions

### 1. 配置 `actionConfig` 在连接时

```ts
const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    // 角色可以发出的动作名称
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow', 'Wave', 'Attack'],

    // 场景中角色可以作用的对象
    objects: [
      { name: 'sword',  description: '地上的一把锋利钢剑' },
      { name: 'chest',  description: '角落里的一个木制宝箱' },
      { name: 'torch',  description: '墙上的一支燃烧火把' },
    ],

    // 机器人可以引用或作用的其他角色
    characters: [
      { name: 'Player', bio: '当前用户' },
      { name: 'Guard',  bio: '附近的一名守卫 NPC' },
    ],

    // 可选：角色开始时关注的对象
    current_attention_object: 'sword',
  },
});
```

规则：

* `actions`, `objects`、以及 `characters` 定义了本次会话中唯一有效的可交互项。
* `current_attention_object` 必须与 `objects[].name`.
* 如果可用动作或对象集合发生变化，请使用更新后的配置重新连接 `actionConfig`.

### 2. 接收 `actionResponse`

订阅 `actionResponse` 以在每回合后获取角色的动作决策。

```ts
client.on('actionResponse', ({ actions }) => {
  // actions: Array<{ name: string; target?: string }>
  // 空数组是有效的无动作响应
  for (const action of actions) {
    dispatch(action.name, action.target);
  }
});
```

* 动作有顺序——按顺序执行。
* `target` 是可选的；某些动作（例如 `"Wave"`）没有目标。
* 空 `actions` 数组不是错误——角色只是选择不采取行动。

### 3. 在运行时更新关注点

使用 `updateContext`告诉角色玩家当前正在看哪个对象。角色会用它来解析“它”“那个”“这里”。

```ts
// 玩家把注意力转到箱子上——静默更新
client.updateContext({
  current_attention_object: 'chest',
  run_llm: 'false',
});

// 更新关注点并让角色作出回应
client.updateContext({
  text: '玩家现在正在看拉杆。',
  current_attention_object: 'lever',
  run_llm: 'auto',
});

// 清除关注对象
client.updateContext({
  current_attention_object: '',
  run_llm: 'false',
});
```

`current_attention_object` 必须与 `actionConfig.objects[].name`.

***

### 4. 更新描述性场景上下文

使用 `updateSceneMetadata` 来告知角色其应了解的环境变化。这只是 **仅用于描述** ——不会添加新的动作目标。

```ts
client.updateSceneMetadata([
  { name: 'fog',  description: '浓雾已经弥漫开来，能见度很低' },
  { name: 'rain', description: '外面正下着大雨' },
]);
```

如果角色需要对某物采取行动，它必须在 `actionConfig.objects`.

***

### 5. 以编程方式触发动作

使用 `sendTriggerMessage` 让角色在没有用户输入的情况下说话并行动——用于脚本事件或过场动画。

```ts
// 在 Convai 控制台中定义的命名触发器
client.sendTriggerMessage('greet_player');

// 带自定义指令的触发器
client.sendTriggerMessage('pickup_item', '捡起剑并把它递给玩家。');
```

***

### 完整示例

```ts
const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow'],
    objects: [
      { name: 'apple',  description: '木箱上的一个绿色苹果' },
      { name: 'basket', description: '玩家附近的一个柳条篮子' },
    ],
    characters: [{ name: 'Player', bio: '当前用户' }],
    current_attention_object: 'apple',
  },
});

client.on('actionResponse', ({ actions }) => {
  for (const { name, target } of actions) {
    console.log(`[ACTION] ${name}${target ? ` → ${target}` : ''}`);
    // 例如 "Move To → apple"、"Pick Up → apple"、"Drop → basket"
  }
});

// 玩家在界面中选择篮子
client.updateContext({
  current_attention_object: 'basket',
  run_llm: 'false',
});

// 玩家说“把那个放进篮子里”
// 角色将“那个”解析为 apple，并执行：Move To apple → Pick Up apple → Move To basket → Drop apple
```

***

### API 参考

#### `actionConfig` （connect 选项）

| 字段                         | 类型                        | 描述          |
| -------------------------- | ------------------------- | ----------- |
| `actions`                  | `string[]`                | 角色可以发出的动作名称 |
| `objects`                  | `{ name, description }[]` | 场景中的对象      |
| `characters`               | `{ name, bio }[]`         | 其他角色        |
| `current_attention_object` | `string?`                 | 初始关注对象      |

#### `actionResponse` 事件

```ts
client.on('actionResponse', ({ actions }) => { ... });
// actions: Array<{ name: string; target?: string }>
```

#### `updateContext` （attention）

| 字段                         | 类型                                 | 描述                 |
| -------------------------- | ---------------------------------- | ------------------ |
| `text`                     | `string?`                          | 可选的上下文文本           |
| `mode`                     | `"append" \| "replace" \| "reset"` | 如何应用文本             |
| `run_llm`                  | `"true" \| "false" \| "auto"`      | 是否触发响应             |
| `current_attention_object` | `string?`                          | 新的关注对象，或 `""` 用于清除 |

#### `updateSceneMetadata(items)`

| 字段      | 类型                        | 描述       |
| ------- | ------------------------- | -------- |
| `items` | `{ name, description }[]` | 描述性的场景元素 |

#### `sendTriggerMessage(triggerName?, triggerMessage?)`

以编程方式触发角色响应。两个参数都是可选的。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.