docs: add design for AI Interaction

Updates #1454

Signed-off-by: Aofei Sheng <[email protected]>

Author: aofei

docs/product/ai-interaction.zh.md

@@ -0,0 +1,155 @@
+# AI 交互（AI Interaction）
+
+AI 交互是 Go+ Builder 中允许游戏在运行时与 AI 大语言模型进行通信的功能。通过这一功能，用户可以在游戏中创建智能对抗（如棋牌类游戏的人机对战）、智能对话、动态内容生成、自适应游戏体验等丰富的交互场景。
+
+AI 交互功能专为学习编程的 10 岁左右的儿童设计，提供了极简的 API，使他们能够轻松地将 AI 能力集成到自己的游戏中，而无需理解复杂的网络请求、错误处理或 AI 模型细节。
+
+## 基本概念
+
+### AI 交互（AI Interaction）
+
+AI 交互是指游戏运行时与外部 AI 大语言模型之间的通信过程。这种交互包括向 AI 发送消息以及接收和处理 AI 的回应。
+
+AI 交互的基本流程是：
+
+1. 游戏向 AI 发送消息（可能包含游戏状态等上下文信息）
+2. AI 处理消息并生成回应
+3. 游戏接收 AI 的回应并执行相应操作
+
+### AI 角色（AI Role）
+
+AI 角色是指 AI 在与游戏交互过程中所扮演的特定身份或行为模式。通过设定明确的角色，可以引导 AI 生成更加一致、更符合游戏场景的回应。
+
+角色定义通常包含以下内容：
+
+- 身份描述：角色的基本身份，如"向导"、"对手"、"老师"等
+- 行为准则：角色应该如何行事，包括语气、态度和决策风格
+- 知识范围：角色应该了解或不了解的内容范围
+- 目标导向：角色在游戏中的主要目标或任务
+
+### AI 上下文（AI Context）
+
+AI 上下文是帮助 AI 理解当前游戏状态、对话历史和环境信息的关键数据集合。良好的上下文能够使 AI 生成更加准确、相关的回应，提高游戏体验的智能性和连贯性。
+
+AI 上下文分为两类：
+
+1. 自动附着的上下文：由 spx 自动收集并提供给 AI 的信息，如对话历史、基本游戏环境等，这些信息无需用户手动提供，spx 会在每次 AI 交互时自动附加
+2. 用户提供的上下文：由开发者通过 API 显式提供的特定信息，如当前游戏状态、特殊规则、角色属性等，spx 会自动将这些信息转换为 AI 可理解的格式，使 AI 能够根据当前情境生成更加智能的回应
+
+AI 上下文通常包含以下几种类型的信息：
+
+- 游戏状态信息：如当前角色位置、游戏分数、收集的物品、已完成的任务等
+- 对话历史：之前与 AI 的交互记录，帮助 AI 理解对话的连续性
+- 环境信息：游戏世界的规则、可用资源、时间限制等
+- 用户信息：如用户的游戏风格、学习进度、困难点等
+
+良好的上下文设计原则：
+
+- 相关性：仅提供与当前任务或对话相关的信息
+- 简洁性：避免冗余信息，保持上下文数据结构清晰
+- 时效性：及时更新上下文，确保 AI 获得最新的游戏状态
+- 可理解性：以 AI 易于处理的方式组织信息
+
+### AI 指令（AI Command）
+
+AI 指令是游戏预先注册的、允许 AI 调用的函数。通过指令机制，AI 可以执行游戏中的特定操作，如移动精灵、播放声音、改变游戏状态等。
+
+每个 AI 指令通常由以下组成部分：
+
+- 指令结构：定义指令的名称、参数类型及其含义
+- 描述信息：说明指令的功能、使用场景和参数含义
+- 执行逻辑：指令对应的具体函数，接收参数并执行相应操作
+
+### AI 消息（AI Message）
+
+AI 消息是游戏发送给 AI 的文本内容，可以包含问题、指令或其他信息。AI 会根据消息内容生成回应。
+
+AI 消息可以附带额外的上下文数据，帮助 AI 更好地理解游戏当前状态。
+
+### AI 回应（AI Response）
+
+AI 回应是 AI 对游戏发送的消息的处理结果。回应通常包含两部分：
+
+1. 文本回应：AI 生成的文本内容
+2. AI 指令集：AI 决定按顺序调用的一系列 AI 指令
+
+## API 设计
+
+为了使 AI 交互功能易于使用，我们提供了 4 个核心 API：
+
+### setAIRole
+
+`setAIRole` 是一个"命令"类 API，用于设置 AI 在交互过程中应该扮演的角色。通过定义明确的角色，可以使 AI 的回应更加一致、更符合游戏场景，并避免在每次 `aiThink` 调用中重复角色描述。
+
+```go
+setAIRole role
+setAIRole role, additionalContext
+```
+
+为了便于使用，`setAIRole` 可以在游戏的任何时刻调用，以改变 AI 的角色设定。一旦设置，该角色将持续生效，直到被新的角色设定替换。
+
+参数说明：
+
+- `role`：`string` 类型，描述 AI 应该扮演的角色，如"向导"、"对手"、"老师"等
+- `additionalContext`：可选参数，`map[string]any` 类型，提供关于角色的额外上下文信息
+
+### onAICommand
+
+`onAICommand` 是一个"事件"类 API，用于注册可被 AI 调用的指令。用户可以通过它预定义游戏中可被 AI 执行的操作。
+
+```go
+onAICommand T, (command) => {}
+```
+
+参数说明：
+
+- `T`：泛型，表示具体的 AI 指令结构体类型
+- `command`：`T` 类型，表示 AI 执行当前指令时传入的参数集合
+
+指令结构体 `T` 需要满足以下要求：
+
+1. 必须实现 `Desc() string` 方法：此方法返回指令的详细描述，包括指令的功能、使用场景和参数含义，用于帮助 AI 理解如何正确使用该指令
+2. 导出字段作为参数：结构体中所有导出字段（首字母大写）都会被 spx 自动识别为 AI 可设置的参数，这些字段的类型应当是基本类型（如 `string`、`int`、`float64`、`bool` 等）或其切片
+3. 字段标签：建议为每个字段添加描述性标签，如 `desc:"角色的名称"`，其中 `desc` 标签用于向 AI 提供该参数的详细说明
+
+示例：
+
+```go
+type MoveCommand struct {
+    Direction string  `desc:"移动方向，可选值：up, down, left, right"`
+    Steps     int     `desc:"移动步数，正整数"`
+    Speed     float64 `desc:"移动速度，单位：像素/秒"`
+}
+
+func (c MoveCommand) Desc() string {
+    return "使角色按指定方向、步数和速度移动。此指令用于控制角色在游戏中的位置变化。"
+}
+```
+
+### aiThink
+
+`aiThink` 是一个"命令"类 API，用于向 AI 发送消息并选择性提供额外的上下文数据以获取回应。spx 会自动处理 AI 的回应，包括执行 AI 决定调用的指令。
+
+```go
+aiThink msg
+aiThink msg, additionalContext
+```
+
+为了便于使用，`aiThink` 采用阻塞式设计，且不返回任何值。如果请求过程中发生错误，spx 会自动重试若干次。如果多次尝试仍未成功，将触发通过 `onAIError` 注册的错误处理函数。如果未注册，则使用默认的错误处理方式。
+
+参数说明：
+
+- `msg`：`string` 类型，向 AI 发送的消息内容
+- `additionalContext`：可选参数，`map[string]any` 类型，提供给 AI 的额外上下文数据
+
+### onAIError
+
+`onAIError` 是一个"事件"类 API，用于注册当 AI 通信失败时的错误处理逻辑。通过定义错误处理函数，可以在网络请求失败或 AI 响应无效等错误发生时，向用户展示友好的提示信息。
+
+```go
+onAIError (err) => {}
+```
+
+参数说明：
+
+- `err`：`error` 类型，具体的错误，可通过调用 `err.Error` 获得对应的字符串描述