@doubao-apps/create 0.0.30 → 0.0.31

package/dist/template-empty/AGENTS.md

@@ -203,6 +203,18 @@ export default defineWidget({
 - **Components**：SDK 内置 UI 组件（Button、Switch、Slider、Swiper、Dialog 等）
 - **Bridge API**：系统能力接口（网络、存储、设备、UI 交互等）
 
+### Playground 测试页范式
+
+当任务涉及 `examples/playground`、Open API 测试页、JSB 验证页或组件 Demo 时，必须按当前 Playground 结构编写：
+
+- **API 测试页**：放在 `examples/playground/src/pages/api/<group>/<api-name>/index.tsx`，并同步 `src/case-metadata.ts` 与 `src/pages/api/registry.ts`；`apiCaseMetas.name` 使用 `<group>/<api-name>`，允许带 `/`。
+- **组件测试页**：放在 `examples/playground/src/pages/component/<component-name>/index.tsx`，并同步 `src/case-metadata.ts` 与 `src/pages/component/registry.ts`。
+- **页面结构**：直接写 `definePage`、`PlaygroundPage`、纵向排列的多个 `TestCase`、`ActionButton` 和真实 API/组件调用，禁止任何页面工厂函数。
+- **覆盖方式**：API 页尽可能覆盖参数组合、边界值、失败路径和事件回调；组件页覆盖默认态、边界态和交互态。不要只写 2～3 个 happy path。
+- **日志隔离**：多个 `TestCase` 不共用同一个日志 state；日志 payload 可带 `case` / `caseName`，避免不同日志面板串扰。
+- **路由编码**：入口页跳转含 `/` 的 case name 时必须 `encodeURIComponent`；开发模式 `delegate-page` 的 query 需要 encode/decode。
+- **响应式主题**：Playground 外壳和示例辅助 UI 使用 `--pg-*` 变量；不要在 Playground 任务中顺手修组件库自身主题。
+
 ### Lynx 组件
 
 Lynx 组件库完整参考文档请访问官方文档：

package/dist/template-empty/package.json

@@ -6,10 +6,10 @@
     "build": "doubao build"
   },
   "dependencies": {
-    "@doubao-apps/framework": "^0.0.30"
+    "@doubao-apps/framework": "^0.0.31"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.30",
+    "@doubao-apps/kit": "^0.0.31",
     "typescript": "5.5.3"
   },
   "version": "0.0.16"

package/dist/template-empty/references/reference/open-api/09-/345/274/200/346/224/276/350/203/275/345/212/233-/344/270/232/345/212/241/350/203/275/345/212/233.md

@@ -22,6 +22,9 @@
 | [getPrivacySetting](#getprivacysetting) | 获取隐私设置状态。 |
 | [sendQueryMessage](#sendquerymessage) | 以用户身份发送一条消息。<br><br>返回 void，不是 Promise。 |
 | [setAdditionalContext](#setadditionalcontext) | 设置全局上下文供大模型理解。<br><br>设置全局上下文。 |
+| [createTask](#createtask) | 创建任务。<br><br>创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识 可用于幂等创建和后续业务关联。远端任务创建成功后，返回的 taskId 可用于查询或更新任务。 |
+| [updateTask](#updatetask) | 更新任务状态或任务详情。<br><br>更新任务时至少传入 taskStatus 或 taskDetail 中的一个。更新远端任务成功后，旧 token 会失效， 如返回 nextToken，后续需要使用新的 token 继续更新远端任务。 |
+| [getTask](#gettask) | 查询任务。<br><br>根据任务 ID 查询任务的模板、详情、状态和类型。若返回 token，可在后续远端任务更新中继续使用。 |
 | [updateModelContext](#updatemodelcontext) | 向 Agent 捐赠上下文。 |
 | [updateWidget](#updatewidget) | 更新指定卡片。 |
 | [openApp](#openapp) | 通过 deep link 等方式打开外部应用。 |
@@ -309,6 +312,124 @@ await sendQueryMessage({ content: '订阅消息', type: 'text' })
 
 设置全局上下文。
 
+<a id="createtask"></a>
+### createTask()
+
+> **createTask**(`params`): `Promise`\<[`CreateTaskResult`](#createtaskresult)\>
+
+创建任务。
+
+#### Parameters
+
+• **params**: [`CreateTaskParams`](#createtaskparams)
+
+任务创建参数。
+
+#### Returns
+
+`Promise`\<[`CreateTaskResult`](#createtaskresult)\>
+
+返回创建后的任务 ID、远端任务 token 和过期时间。
+
+#### Remarks
+
+创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识
+可用于幂等创建和后续业务关联。远端任务创建成功后，返回的 taskId 可用于查询或更新任务。
+
+#### Example
+
+```typescript
+import { createTask } from '@doubao-apps/framework/api';
+
+const result = await createTask({
+  outTaskId: 'order-20260529-001',
+  taskTemplate: 'remote_normal_v1',
+  taskType: 'remote',
+  taskDetail: JSON.stringify({
+    title: '订单处理中',
+    description: '正在为你处理订单，请稍候'
+  })
+});
+
+console.log(result.taskId, result.token, result.expiresIn);
+```
+
+<a id="updatetask"></a>
+### updateTask()
+
+> **updateTask**(`params`): `Promise`\<[`UpdateTaskResult`](#updatetaskresult)\>
+
+更新任务状态或任务详情。
+
+#### Parameters
+
+• **params**: [`UpdateTaskParams`](#updatetaskparams)
+
+任务更新参数，taskStatus 与 taskDetail 二选一。
+
+#### Returns
+
+`Promise`\<[`UpdateTaskResult`](#updatetaskresult)\>
+
+返回任务 ID、新 token 和过期时间。
+
+#### Remarks
+
+更新任务时至少传入 taskStatus 或 taskDetail 中的一个。更新远端任务成功后，旧 token 会失效，
+如返回 nextToken，后续需要使用新的 token 继续更新远端任务。
+
+#### Example
+
+```typescript
+import { updateTask } from '@doubao-apps/framework/api';
+
+const result = await updateTask({
+  taskId: 'task_123',
+  taskStatus: 'completed',
+  taskDetail: JSON.stringify({
+    title: '订单已完成',
+    description: '订单处理完成'
+  })
+});
+
+console.log(result.taskId, result.nextToken, result.expiresIn);
+```
+
+<a id="gettask"></a>
+### getTask()
+
+> **getTask**(`params`): `Promise`\<[`GetTaskResult`](#gettaskresult)\>
+
+查询任务。
+
+#### Parameters
+
+• **params**: [`GetTaskParams`](#gettaskparams)
+
+任务查询参数。
+
+#### Returns
+
+`Promise`\<[`GetTaskResult`](#gettaskresult)\>
+
+返回任务详情、状态、类型和 token 信息。
+
+#### Remarks
+
+根据任务 ID 查询任务的模板、详情、状态和类型。若返回 token，可在后续远端任务更新中继续使用。
+
+#### Example
+
+```typescript
+import { getTask } from '@doubao-apps/framework/api';
+
+const task = await getTask({ taskId: 'task_123' });
+
+if (task.taskStatus === 'running') {
+  console.log('任务仍在运行', task.taskDetail);
+}
+```
+
 <a id="updatemodelcontext"></a>
 ### updateModelContext()
 
@@ -843,6 +964,194 @@ Whether user authorization for privacy agreement is required
 
 指定 bot id
 
+<a id="createtaskparams"></a>
+### CreateTaskParams
+
+创建任务的请求参数。
+
+#### Properties
+
+##### outTaskId
+
+> **outTaskId**: `string`
+
+开发者侧任务唯一标识，用于幂等和关联
+
+##### taskDetail
+
+> **taskDetail**: `string`
+
+模板对应的数据的 JSON 字符串
+
+##### taskTemplate
+
+> **taskTemplate**: `"remote_normal_v1"`
+
+任务样式模板，当前仅支持 remote_normal_v1
+
+##### taskType
+
+> **taskType**: [`TaskType`](#tasktype-2)
+
+任务类型，当前支持 local 和 remote
+
+<a id="createtaskresult"></a>
+### CreateTaskResult
+
+创建任务的返回结果。
+
+#### Properties
+
+##### expiresIn?
+
+> `optional` **expiresIn**: `number`
+
+任务超时过期时间
+
+##### taskId
+
+> **taskId**: `string`
+
+任务 ID，后续可以使用这个 ID 更新任务
+
+##### token?
+
+> `optional` **token**: `string`
+
+远端任务 token，后续使用 token 通过 OpenAPI 更新远端任务
+
+<a id="tasktype-2"></a>
+<a id="tasktype"></a>
+### TaskType
+
+> **TaskType**: `"local"` \| `"remote"`
+
+任务类型。
+
+local 表示本地任务，remote 表示远端任务。
+
+<a id="updatetaskparams"></a>
+### UpdateTaskParams
+
+更新任务的请求参数。
+
+#### Properties
+
+##### taskDetail?
+
+> `optional` **taskDetail**: `string`
+
+模板对应的数据的 JSON 字符串，与 taskStatus 二选一
+
+##### taskId
+
+> **taskId**: `string`
+
+任务 ID
+
+##### taskStatus?
+
+> `optional` **taskStatus**: [`TaskStatus`](#taskstatus-2)
+
+任务状态，与 taskDetail 二选一
+
+<a id="updatetaskresult"></a>
+### UpdateTaskResult
+
+更新任务的返回结果。
+
+#### Properties
+
+##### expiresIn?
+
+> `optional` **expiresIn**: `number`
+
+任务超时过期时间
+
+##### nextToken?
+
+> `optional` **nextToken**: `string`
+
+每次更新后旧的 token 失效，必须使用新返回的 token
+
+##### taskId
+
+> **taskId**: `string`
+
+任务 ID，更新后任务 ID 不变
+
+<a id="taskstatus-2"></a>
+<a id="taskstatus"></a>
+### TaskStatus
+
+> **TaskStatus**: `"running"` \| `"completed"`
+
+任务状态。
+
+running 表示任务运行中，completed 表示任务已完成。
+
+<a id="gettaskparams"></a>
+### GetTaskParams
+
+查询任务的请求参数。
+
+#### Properties
+
+##### taskId
+
+> **taskId**: `string`
+
+任务 ID
+
+<a id="gettaskresult"></a>
+### GetTaskResult
+
+查询任务的返回结果。
+
+#### Properties
+
+##### expiresIn?
+
+> `optional` **expiresIn**: `number`
+
+任务超时过期时间
+
+##### taskDetail
+
+> **taskDetail**: `string`
+
+模板对应的数据的 JSON 字符串
+
+##### taskId
+
+> **taskId**: `string`
+
+任务 ID
+
+##### taskStatus
+
+> **taskStatus**: [`TaskStatus`](#taskstatus-2)
+
+任务状态，运行中或已完成
+
+##### taskTemplate
+
+> **taskTemplate**: `"remote_normal_v1"`
+
+任务样式模板，当前仅支持 remote_normal_v1
+
+##### taskType
+
+> **taskType**: [`TaskType`](#tasktype-2)
+
+任务类型，local 或 remote
+
+##### token?
+
+> `optional` **token**: `string`
+
+每次更新后旧的 token 失效，必须使用新返回的 token
+
 <a id="updatemodelcontextparams"></a>
 ### UpdateModelContextParams
 

package/dist/template-empty/references/reference/open-api/12-/350/256/276/345/244/207-wi-fi.md

@@ -10,10 +10,11 @@ Wi-Fi 模块能力；通常先 startWifi，再获取列表或连接。
 | --- | --- |
 | [startWifi](#startwifi) | 初始化 Wi-Fi 模块。<br><br>Wi-Fi 流程入口。 |
 | [stopWifi](#stopwifi) | 关闭 Wi-Fi 模块。 |
-| [setWifiList](#setwifilist) | 设置 Wi-Fi 预设列表。<br><br>用于预设 Wi-Fi 列表。 |
+| [setWifiList](#setwifilist) | 设置 Wi-Fi 预设列表（iOS 特有）。<br><br>该接口为 iOS 特有，用于预设 Wi-Fi 列表。 |
 | [connectWifi](#connectwifi) | 连接指定 Wi-Fi。<br><br>通常先调用 startWifi。 |
 | [getConnectedWifi](#getconnectedwifi) | 获取当前已连接 Wi-Fi 信息。 |
 | [getWifiList](#getwifilist) | 获取 Wi-Fi 列表。<br><br>通常先调用 startWifi。 |
+| [onWifiConnected](#onwificonnected) | 监听连接上 Wi-Fi 的事件。<br><br>返回取消监听函数。 |
 
 ## API 详情
 
@@ -56,7 +57,7 @@ Wi-Fi 流程入口。
 
 > **setWifiList**(`params`): `Promise`\<`object`\>
 
-设置 Wi-Fi 预设列表。
+设置 Wi-Fi 预设列表（iOS 特有）。
 
 #### Parameters
 
@@ -68,7 +69,7 @@ Wi-Fi 流程入口。
 
 #### Remarks
 
-用于预设 Wi-Fi 列表。
+该接口为 iOS 特有，用于预设 Wi-Fi 列表。
 
 <a id="connectwifi"></a>
 ### connectWifi()
@@ -123,12 +124,45 @@ Wi-Fi 流程入口。
 
 通常先调用 startWifi。
 
+<a id="onwificonnected"></a>
+### onWifiConnected()
+
+> **onWifiConnected**(`handler`): () => `void`
+
+监听连接上 Wi-Fi 的事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onWifiConnected } from '@doubao-apps/framework/api';
+
+const off = onWifiConnected(({ wifi }) => {
+  console.log(wifi.ssid);
+});
+
+off();
+```
+
 ## 相关类型
 
 <a id="setwifilistparams"></a>
 ### SetWifiListParams
 
-设置 Wi-Fi 预设列表的请求参数。
+设置 Wi-Fi 预设列表的请求参数（iOS 特有）。
 
 #### Properties