@cloudbase/agent-ui-miniprogram 1.0.1-alpha.7 → 1.0.1-alpha.9

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @cloudbase/agent-ui-miniprogram
 
+## 1.0.1-alpha.8
+
+### Patch Changes
+
+- alpha release 0.1.2-alpha.1
+  - Update all public packages to version 0.1.2-alpha.1
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
+## 1.0.1-alpha.7
+
+### Patch Changes
+
+- alpha release 0.1.2-alpha.1
+  - Update all public packages to version 0.1.2-alpha.1
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
 ## 1.0.1-alpha.6
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,466 @@
+# @cloudbase/agent-ui-miniprogram
+
+微信小程序的 [AG-UI](https://docs.ag-ui.com) 客户端 SDK。
+
+## 为什么用这个库？
+
+**[AG-UI](https://docs.ag-ui.com)** 是一个用于构建 AI 对话应用的协议。它定义了客户端和服务端如何通信——流式文本、工具调用、消息历史等。
+
+如果从零开始构建 AG-UI 客户端，你需要：
+
+1. 解析服务端的 Server-Sent Events 流
+2. 处理 15+ 种事件类型（TEXT_MESSAGE_START、TOOL_CALL_ARGS、RUN_ERROR...）
+3. 维护消息状态、合并流式片段、跟踪工具调用状态
+4. 执行客户端工具并回传结果
+5. 保持 UI 与所有状态变化同步
+
+**@cloudbase/agent-ui-miniprogram 帮你处理了这些逻辑。** 你只需要：
+
+调用 `this.agui.sendMessage` 发送消息：
+
+```javascript
+// chat.js
+this.agui.sendMessage('你好')
+```
+
+将注入的消息列表数据 `uiMessages` 渲染成 UI：
+
+```xml
+<!-- chat.wxml -->
+<view wx:for="{{agui.uiMessages}}" wx:key="id">
+  {{item.role}}: {{item.parts[0].text}}
+</view>
+```
+
+---
+
+## 安装
+
+```bash
+npm install @cloudbase/agent-ui-miniprogram@beta
+```
+
+---
+
+## 快速开始
+
+```javascript
+import { createAGUIBehavior, CloudbaseTransport } from '@cloudbase/agent-ui-miniprogram'
+
+Component({
+  behaviors: [
+    createAGUIBehavior({
+      transport: new CloudbaseTransport({ botId: 'your-bot-id' }),
+    })
+  ],
+
+  methods: {
+    onSend(e) {
+      this.agui.sendMessage(e.detail.value)
+    }
+  }
+})
+```
+
+```xml
+<view class="chat">
+  <view wx:for="{{agui.uiMessages}}" wx:key="id" class="message {{item.role}}">
+    <block wx:for="{{item.parts}}" wx:for-item="part" wx:key="id">
+      <text wx:if="{{part.type === 'text'}}">{{part.text}}</text>
+      <view wx:if="{{part.type === 'tool'}}" class="tool">
+        🔧 {{part.name}}: {{part.status}}
+      </view>
+    </block>
+  </view>
+  <view wx:if="{{agui.error}}" class="error">{{agui.error.message}}</view>
+</view>
+
+<input placeholder="输入消息..." bindconfirm="onSend" disabled="{{agui.isRunning}}" />
+```
+
+---
+
+## 核心概念
+
+本 SDK 使用小程序的 [Behavior](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/behaviors.html) 机制——一种可以在多个组件间复用代码的 mixin 模式。
+
+当你在组件中添加由 `createAGUIBehavior()` 创建出的 Behavior 后，它会：
+
+1. 将 AG-UI 相关状态注入到 `this.data.agui` 中
+2. 提供 `this.agui.xxx` 方法调用 AG-UI 相关能力
+
+### 状态
+
+Behavior 会在 `this.data.agui` 中提供以下数据：
+
+| 属性 | 用途 |
+|------|------|
+| `uiMessages` | 渲染聊天界面 |
+| `isRunning` | 显示加载状态、禁用输入框 |
+| `error` | 显示错误信息 |
+
+对于其他数据，请查看 API Reference 了解。
+
+### Transport
+
+```mermaid
+flowchart LR
+    A[小程序<br/>@cloudbase/agent-ui-miniprogram] <-->|transport| B[AG-UI 服务端<br/>你的后端]
+    B <--> C[LLM<br/>Claude 等]
+```
+
+@cloudbase/agent-ui-miniprogram 采用了通信层（Transport）无关的设计。它只负责处理 AG-UI 事件流、管理状态、提供交互方法，而不关心如何与后端通信。
+
+Transport 层专门负责与后端通信，你可以在创建 Behavior 的时候传入任意符合定义的 Transport 实例。
+
+```javascript
+createAGUIBehavior({
+  transport: new AnyTransport()
+})
+```
+
+@cloudbase/agent-ui-miniprogram 提供了 `CloudbaseTransport`，对接 Cloudbase 云开发 Agent。
+
+```javascript
+createAGUIBehavior({
+  transport: new CloudbaseTransport({ botId: '...' })
+})
+```
+
+自定义 Transport 需要满足的接口：
+
+```typescript
+interface Transport {
+  run(input: RunAgentInput): AsyncIterable<BaseEvent>
+}
+```
+
+### 客户端工具
+
+客户端工具能够让 Agent 能够与小程序环境交互。
+
+**使用场景：**
+
+- 访问设备功能（位置、相机、存储）
+- 读取客户端数据（用户偏好、购物车）
+- 触发 UI 操作（导航、弹窗、提示）
+
+**示例：**
+
+```javascript
+createAGUIBehavior({
+  transport,
+  tools: [{
+    name: 'get_location',
+    description: '获取用户当前位置',
+    parameters: { type: 'object', properties: {} },
+    handler: async ({ args }) => {
+      const res = await wx.getLocation()
+      return JSON.stringify(res)
+    }
+  }]
+})
+```
+
+当 Agent 决定调用工具时，SDK 会执行你的 handler 并自动将结果发回给 Agent。
+
+---
+
+## CloudbaseTransport 配置
+
+用于微信云开发 Cloudbase 的 Transport 实现，基于 `wx.cloud.extend.AI.bot`。
+
+### 前置条件
+
+1. **开通微信云开发** - 在小程序中启用云开发
+2. **创建 Agent** - 创建一个 AI Bot 并获取其 `agentId`
+
+### 配置步骤
+
+#### 1. 在 app.js 中初始化云开发
+
+```javascript
+// app.js
+App({
+  onLaunch() {
+    wx.cloud.init({
+      env: 'your-env-id'
+    })
+  }
+})
+```
+
+#### 2. 使用 CloudbaseTransport
+
+```javascript
+import { createAGUIBehavior, CloudbaseTransport } from '@cloudbase/agent-ui-miniprogram'
+
+const transport = new CloudbaseTransport({
+  botId: 'your-agent-id'  // 从云开发控制台获取
+})
+
+Component({
+  behaviors: [createAGUIBehavior({ transport })]
+})
+```
+
+### CloudbaseTransport 构造函数
+
+```typescript
+new CloudbaseTransport(options: { botId: string })
+```
+
+| 选项 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `botId` | `string` | 是 | 云开发控制台中的 Agent ID |
+
+### 工作原理
+
+CloudbaseTransport 内部调用 `wx.cloud.extend.AI.bot.sendMessage()`：
+
+```javascript
+const res = await wx.cloud.extend.AI.bot.sendMessage({
+  botId: 'your-bot-id',
+  data: {
+    threadId: '...',
+    messages: [...],
+    tools: [...],
+    context: [...]
+  }
+})
+
+for await (const event of res.eventStream) {
+  // AG-UI 事件在这里流式返回
+}
+```
+
+---
+
+## API 参考
+
+### `createAGUIBehavior(options?)`
+
+创建一个带有 AG-UI 状态管理的 Behavior mixin。
+
+```javascript
+import { createAGUIBehavior } from '@cloudbase/agent-ui-miniprogram'
+
+Component({
+  behaviors: [createAGUIBehavior(options)]
+})
+```
+
+#### 配置项
+
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `transport` | `Transport` | Transport 实现（`sendMessage` 必需） |
+| `threadId` | `string` | 会话线程 ID（不传则自动生成） |
+| `messages` | `Message[]` | 初始消息 |
+| `tools` | `ClientTool[]` | 带有 handler 的客户端工具 |
+| `contexts` | `Context[]` | Agent 运行时的上下文 |
+| `onRawEvent` | `(event: BaseEvent) => void` | 每个原始 AG-UI 事件的回调 |
+
+### 实例方法
+
+组件 attached 后通过 `this.agui.xxx` 访问。
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `init` | `(config: AGUIConfig) => void` | 初始化或重新初始化 transport/threadId |
+| `sendMessage` | `(input: string \| Message[]) => Promise<void>` | 发送消息并运行 agent |
+| `appendMessage` | `(message: Message) => void` | 添加消息但不触发 agent |
+| `setMessages` | `(messages: Message[]) => void` | 替换整个消息历史 |
+| `reset` | `() => void` | 重置为配置项中的初始状态 |
+| `setThreadId` | `(threadId: string) => void` | 更改线程 ID |
+| `addTool` | `(tool: ClientTool) => void` | 注册新工具 |
+| `removeTool` | `(name: string) => void` | 按名称移除工具 |
+| `updateTool` | `(name: string, updates: Partial<ClientTool>) => void` | 更新工具属性 |
+| `clearTools` | `() => void` | 移除所有工具 |
+
+### 状态属性
+
+通过 `this.data.agui.xxx` 访问（WXML 中使用 `{{agui.xxx}}`）。
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `messages` | `Message[]` | 原始消息历史（用于 AI） |
+| `uiMessages` | `UIMessage[]` | UI 优化的消息（用于渲染） |
+| `isRunning` | `boolean` | Agent 是否正在处理中 |
+| `error` | `AGUIClientError \| null` | 当前错误（如果有） |
+| `activeToolCalls` | `ToolCallState[]` | 进行中的工具调用 |
+| `threadId` | `string` | 当前会话线程 ID |
+| `tools` | `Tool[]` | 已注册的工具定义（不含 handler） |
+| `contexts` | `Context[]` | 已注册的上下文 |
+| `runId` | `string \| null` | 当前运行 ID（未运行时为 null） |
+
+### `this.agui` 完整类型
+
+可以通过 `this.agui` 访问到所有的数据和方法。
+
+```typescript
+interface AGUINamespace {
+  // 方法
+  init(config: AGUIConfig): void
+  sendMessage(input: string | Message[]): Promise<void>
+  appendMessage(message: Message): void
+  setMessages(messages: Message[]): void
+  reset(): void
+  setThreadId(threadId: string): void
+  addTool(tool: ClientTool): void
+  removeTool(name: string): void
+  updateTool(name: string, updates: Partial<ClientTool>): void
+  clearTools(): void
+
+  // 状态（只读，与 this.data.agui 同步）
+  readonly messages: Message[]
+  readonly uiMessages: UIMessage[]
+  readonly isRunning: boolean
+  readonly error: AGUIClientError | null
+  readonly activeToolCalls: ToolCallState[]
+  readonly threadId: string
+  readonly tools: Tool[]
+  readonly contexts: Context[]
+  readonly runId: string | null
+
+  // 配置（只读，传入 createAGUIBehavior 的原始选项）
+  readonly config: CreateAGUIBehaviorOptions
+}
+```
+
+### 类型定义
+
+#### AG-UI 协议类型
+
+以下类型来自 [AG-UI 协议](https://docs.ag-ui.com)，本 SDK 对标版本：**v0.0.42**
+
+详细定义请参考 AG-UI 官方文档：
+- [`Message`](https://docs.ag-ui.com/sdk/js/core/types#message) - 消息结构
+- [`Tool`](https://docs.ag-ui.com/sdk/js/core/types#tool) - 工具定义
+- [`ToolCall`](https://docs.ag-ui.com/sdk/js/core/types#toolcall) - 工具调用结构
+- [`Context`](https://docs.ag-ui.com/sdk/js/core/types#context) - Agent 上下文
+- [`RunAgentInput`](https://docs.ag-ui.com/sdk/js/core/types#runagentinput) - Agent 运行输入
+- [`BaseEvent`](https://docs.ag-ui.com/sdk/js/core/events) - 事件基础结构
+- [`EventType`](https://docs.ag-ui.com/sdk/js/core/events) - 事件类型枚举
+
+#### UIMessage
+
+```typescript
+interface UIMessage {
+  id: string
+  role: 'user' | 'assistant' | 'system' | 'developer'
+  parts: UIMessagePart[]
+}
+
+type UIMessagePart = TextPart | ToolPart
+
+interface TextPart {
+  id: string
+  type: 'text'
+  text: string
+  state?: 'streaming' | 'done'
+}
+
+interface ToolPart {
+  id: string
+  type: 'tool'
+  toolCallId: string
+  name: string
+  argsString: string
+  args: Record<string, unknown>
+  status: 'pending' | 'ready' | 'executing' | 'completed' | 'failed'
+  result?: unknown
+  error?: AGUIClientError
+}
+```
+
+#### ClientTool
+
+扩展自 AG-UI 的 `Tool` 类型，增加了 `handler` 函数用于执行客户端工具。
+
+```typescript
+interface ClientTool extends Tool {
+  handler: (params: ToolHandlerParams) => string | Promise<string>
+}
+
+interface ToolHandlerParams {
+  name: string
+  description: string
+  toolCallId: string
+  args: Record<string, unknown>
+}
+```
+
+#### AGUIClientError
+
+```typescript
+interface AGUIClientError {
+  code: AGUIClientErrorCode
+  message: string
+  recoverable: boolean
+  details?: unknown
+  originalError?: Error
+}
+
+type AGUIClientErrorCode =
+  | 'INIT_ERROR'
+  | 'TRANSPORT_ERROR'
+  | 'RUNTIME_ERROR'
+  | 'INVALID_EVENT'
+  | 'TOOL_EXECUTION_ERROR'
+  | 'TOOL_NOT_FOUND'
+  | 'PARSE_ERROR'
+  | 'TIMEOUT'
+  | 'INVALID_CONFIG'
+  | 'UNKNOWN'
+```
+
+#### ToolCallState
+
+```typescript
+interface ToolCallState {
+  toolCallId: string
+  name: string
+  argsString: string                    // 原始参数字符串（流式传输中）
+  args: Record<string, unknown>         // 解析后的参数
+  status: ToolCallStatus
+  result?: unknown
+  error?: AGUIClientError
+}
+
+type ToolCallStatus = 'pending' | 'ready' | 'executing' | 'completed' | 'failed'
+```
+
+#### AGUIConfig
+
+```typescript
+interface AGUIConfig {
+  transport: Transport
+  threadId?: string
+}
+```
+
+#### CreateAGUIBehaviorOptions
+
+```typescript
+interface CreateAGUIBehaviorOptions {
+  transport?: Transport
+  threadId?: string
+  messages?: Message[]
+  tools?: ClientTool[]
+  contexts?: Context[]
+  onRawEvent?: (event: BaseEvent) => void
+}
+```
+
+#### Transport
+
+```typescript
+interface Transport {
+  run(input: RunAgentInput): AsyncIterable<BaseEvent>
+}
+```
+
+> `RunAgentInput` 和 `BaseEvent` 类型定义见 [AG-UI 协议类型](#ag-ui-协议类型)。
+
+---

package/dist/behavior.d.ts

@@ -0,0 +1,65 @@
+/**
+ * AG-UI Behavior for WeChat Miniprogram
+ * Main entry point - provides the Behavior mixin pattern
+ */
+import { type CreateAGUIBehaviorOptions } from "./types";
+/**
+ * Creates an AG-UI Behavior mixin for WeChat Mini Program components.
+ *
+ * This factory function returns a Behavior definition that provides AG-UI
+ * protocol support via the `agui` namespace on component data.
+ *
+ * @param options - Configuration options for the behavior
+ * @param options.transport - Transport instance for communicating with the agent backend
+ * @param options.messages - Initial message history to populate the conversation
+ * @param options.tools - Client tools that the agent can invoke
+ * @param options.threadId - Custom thread ID (auto-generated if not provided)
+ * @param options.contexts - Additional context objects to pass to the agent
+ * @param options.onRawEvent - Callback invoked for each raw AG-UI event received
+ * @returns A Behavior definition to be mixed into a Component
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with transport
+ * const transport = new CloudbaseTransport({ botId: 'your-bot-id' });
+ * Component({
+ *   behaviors: [createAGUIBehavior({ transport })],
+ * });
+ *
+ * // With initial messages and tools
+ * Component({
+ *   behaviors: [createAGUIBehavior({
+ *     transport,
+ *     messages: [{ id: 'm1', role: 'user', content: 'Hello' }],
+ *     tools: [{
+ *       name: 'get_weather',
+ *       description: 'Get current weather',
+ *       parameters: { type: 'object', properties: { city: { type: 'string' } } },
+ *       handler: async ({ args }) => ({ temp: 72, city: args.city }),
+ *     }],
+ *   })],
+ * });
+ * ```
+ */
+export declare function createAGUIBehavior(options?: CreateAGUIBehaviorOptions): string;
+/**
+ * Default AG-UI behavior instance with no static configuration.
+ *
+ * Use this for a purely imperative usage pattern where all configuration
+ * is done at runtime via `agui.init()`.
+ *
+ * @example
+ * ```typescript
+ * Component({
+ *   behaviors: [aguiBehavior],
+ *   lifetimes: {
+ *     attached() {
+ *       this.agui.init({
+ *         transport: new CloudbaseTransport({ botId: 'my-bot' }),
+ *       });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare const aguiBehavior: string;

package/dist/event-handler.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AG-UI Event Handler
+ * Processes AG-UI events and updates state accordingly
+ */
+import { type BaseEvent, type Message, type AGUIState, type PendingToolCall, type ActiveMessage, type UIMessage } from "./types";
+/**
+ * AG-UI event type - uses local BaseEvent to avoid Zod dependency
+ */
+export type AGUIEvent = BaseEvent;
+/**
+ * Context for event handling - provides access to current state and update functions
+ */
+export interface EventHandlerContext {
+    getState(): AGUIState;
+    setData(updates: Record<string, unknown>): void;
+    /** Callback uses BaseEvent for public API simplicity */
+    onRawEvent?: (event: BaseEvent) => void;
+}
+/**
+ * Internal state tracked during event processing
+ */
+export interface EventProcessingState {
+    activeMessages: Map<string, ActiveMessage>;
+    pendingToolCalls: Map<string, PendingToolCall>;
+    /** Maps raw message id to uiMessage id (for merged messages) */
+    rawToUiMessageMap: Map<string, string>;
+}
+/**
+ * Create initial processing state
+ */
+export declare function createProcessingState(): EventProcessingState;
+/**
+ * Rebuild UI-optimized messages from raw AG-UI messages.
+ *
+ * This utility function transforms the raw message array into a format
+ * optimized for UI rendering:
+ * - Filters out tool role messages (they appear as parts in assistant messages)
+ * - Merges consecutive assistant messages into a single UIMessage with multiple parts
+ * - Converts text content and tool calls into a unified parts-based structure
+ *
+ * @param messages - Raw AG-UI message array
+ * @returns Array of UIMessage objects optimized for rendering
+ *
+ * @example
+ * ```typescript
+ * const messages: Message[] = [
+ *   { id: 'm1', role: 'user', content: 'Hello' },
+ *   { id: 'm2', role: 'assistant', content: 'Hi there!' },
+ *   { id: 'm3', role: 'assistant', content: 'How can I help?' },
+ * ];
+ *
+ * const uiMessages = rebuildUiMessages(messages);
+ * // Result: [
+ * //   { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
+ * //   { id: 'm2', role: 'assistant', parts: [
+ * //     { type: 'text', text: 'Hi there!' },
+ * //     { type: 'text', text: 'How can I help?' },
+ * //   ] },
+ * // ]
+ * ```
+ */
+export declare function rebuildUiMessages(messages: Message[]): UIMessage[];
+/**
+ * Process a single AG-UI event and update state
+ */
+export declare function processEvent(event: AGUIEvent, ctx: EventHandlerContext, processingState: EventProcessingState): void;