@doubao-dev/cli 0.0.35 → 0.0.36

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/26-/345/237/272/347/241/200/344/277/241/346/201/257.md

@@ -36,7 +36,7 @@
 <tbody>
 <tr><td>Android</td><td>支持</td></tr>
 <tr><td>iOS</td><td>支持</td></tr>
-<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>PC</td><td>支持</td></tr>
 <tr><td>HarmonyOS</td><td>不支持</td></tr>
 </tbody>
 </table>
@@ -112,6 +112,7 @@ console.log(result.platform, result.benchmarkLevel);
 
 - **Android**：`abi`、`deviceAbi`、`cpuType` 仅 Android 返回
 - **iOS**：不返回 `abi`、`deviceAbi`、`cpuType`
+- **PC**：Flow Web 浏览器的 `platform` 返回 `web`；Windows、macOS 桌面客户端分别返回 `windows`、`mac`，不返回 Android 专属字段
 
 <a id="getdeviceinfosync"></a>
 ### getDeviceInfoSync()

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/33-/345/261/217/345/271/225.md

@@ -9,6 +9,7 @@
 | API | 说明 |
 | --- | --- |
 | [getScreenBrightness](#getscreenbrightness) | 获取屏幕亮度。 |
+| [setScreenBrightness](#setscreenbrightness) | 设置屏幕亮度。 |
 | [setKeepScreenOn](#setkeepscreenon) | 设置屏幕常亮状态。 |
 | [disableUserScreenRecord](#disableuserscreenrecord) | 禁止用户录屏。 |
 | [enableUserScreenRecord](#enableuserscreenrecord) | 允许用户录屏。 |
@@ -27,11 +28,6 @@
 ## 扫码预览
 ![扫码预览 getScreenBrightness](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fget-screen-brightness%252Findex)
 
-## 使用限制
-
-> [!WARNING]
-> **iOS**：豆包 iOS 暂不支持该接口，调用直接失败；iOS 上调用无法取得屏幕亮度。
-
 ## 支持版本
 
 前端库版本不低于 `0.0.19`。
@@ -44,7 +40,7 @@
 </thead>
 <tbody>
 <tr><td>Android</td><td>支持</td></tr>
-<tr><td>iOS</td><td>不支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
 <tr><td>PC</td><td>不支持</td></tr>
 <tr><td>HarmonyOS</td><td>不支持</td></tr>
 </tbody>
@@ -64,7 +60,7 @@
 
 ## 使用说明
 
-- **Android**：返回值为归一化后的 0 到 1 亮度
+- 返回值为归一化后的 0 到 1 亮度
 
 ## 调用方式
 
@@ -120,10 +116,121 @@ console.log(value);
 <tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
 </thead>
 <tbody>
-<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android</td></tr>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+<a id="setscreenbrightness"></a>
+### setScreenBrightness()
+
+# setScreenBrightness
+
+设置屏幕亮度。
+
+## 扫码预览
+![扫码预览 setScreenBrightness](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fget-screen-brightness%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.4.0`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- value 必须是 0 到 1 之间的有限数字
+
+## 使用说明
+
+- 该设置仅在当前小程序生命周期内生效，退出后自动恢复原亮度
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+setScreenBrightness(params: SetScreenBrightnessParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>value</code></td><td><code>number</code></td><td>是</td><td>-</td><td>取值范围 0 到 1，0 最暗，1 最亮</td><td>屏幕亮度值。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { setScreenBrightness } from '@doubao-dev/framework/api';
+
+await setScreenBrightness({ value: 0.8 });
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 错误码
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>参数不合法</td><td>Android、iOS</td></tr>
 </tbody>
 </table>
 
+## 平台差异
+
+- **Android**：使用当前宿主窗口亮度，不修改系统全局亮度
+- **iOS**：小程序进入后台时恢复系统亮度，回到前台时重新应用设置值
+
 <a id="setkeepscreenon"></a>
 ### setKeepScreenOn()
 
@@ -594,6 +701,15 @@ off();
 
 • **value**: `number` - 屏幕亮度值
 
+<a id="setscreenbrightnessparams"></a>
+### SetScreenBrightnessParams
+
+设置屏幕亮度的请求参数。
+
+#### Properties
+
+• **value**: `number` - 屏幕亮度值
+
 <a id="setkeepscreenonparams"></a>
 ### SetKeepScreenOnParams
 

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/groups.md

@@ -38,6 +38,6 @@
 | 日历 | 向系统日历添加事件和重复事件。 | 2 | [查看](./30-日历.md) |
 | 电话 | 拨打电话。 | 1 | [查看](./31-电话.md) |
 | 扫码 | 调起扫码并读取扫码结果。 | 1 | [查看](./32-扫码.md) |
-| 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 6 | [查看](./33-屏幕.md) |
+| 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 7 | [查看](./33-屏幕.md) |
 | 震动 | 触发短震动和长震动。 | 2 | [查看](./34-震动.md) |
 | 文件系统 | 文件读写、目录管理和文件信息操作。 | 1 | [查看](./35-文件系统.md) |

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/quick-reference.md

@@ -2,7 +2,7 @@
 
 > 这是豆包智能服务运行时 API，也称 Open API。默认从 `@doubao-dev/framework/api` 导入；本文件根据 `packages/open-api/src` 的导出结构自动生成，按模块列出 API 名称和说明。
 
-覆盖 152 个函数。详细参数、返回值、示例和相关类型请查看 [豆包智能服务的端能力 API 分组目录](groups.md)，精确字段也可按参数/结果类型名查看 IDE 类型提示或 `@doubao-dev/framework/api` 类型定义。
+覆盖 153 个函数。详细参数、返回值、示例和相关类型请查看 [豆包智能服务的端能力 API 分组目录](groups.md)，精确字段也可按参数/结果类型名查看 IDE 类型提示或 `@doubao-dev/framework/api` 类型定义。
 
 ## 使用方式
 
@@ -406,6 +406,7 @@ iBeacon 搜索和结果读取能力。
 | API | 说明 |
 | --- | --- |
 | [getScreenBrightness](33-屏幕.md#getscreenbrightness) | 获取屏幕亮度。 |
+| [setScreenBrightness](33-屏幕.md#setscreenbrightness) | 设置屏幕亮度。 |
 | [setKeepScreenOn](33-屏幕.md#setkeepscreenon) | 设置屏幕常亮状态。 |
 | [disableUserScreenRecord](33-屏幕.md#disableuserscreenrecord) | 禁止用户录屏。 |
 | [enableUserScreenRecord](33-屏幕.md#enableuserscreenrecord) | 允许用户录屏。 |

package/skills/doubao-agentic-service-development/references/frontend/examples/page-widget-basics.md

@@ -347,6 +347,7 @@ export default function RecommendList() {
 3. **卡片类型 (boxType)**
    - `inbox` - 普通卡片
    - `full_box` - 全宽卡片
+   - `custom_box` - 背景、圆角和描边由业务内容设置，标题栏仍遵循 `titleType`
 
 4. **消息交互**
    - 接收 AI 传入的数据

package/skills/doubao-agentic-service-development/references/frontend/guides/client-tools-and-events.md

@@ -0,0 +1,209 @@
+# 端工具、事件与页面上下文
+
+## 选择数据方向
+
+| 能力 | 接入点 | 职责 |
+| --- | --- | --- |
+| Client Tool | `tools.json`、`app.config.ts.tools`、默认函数 handler | 执行端侧能力并返回工具结果 |
+| Agent Event | `events.json`、业务 `SKILL.md` 事件占位符、`useAgentEvent` | 更新已打开页面 |
+| Page Model Context | `useModelContext().setPageContext` | 提交当前页面完整状态，供后续模型轮次使用 |
+
+端工具不能直接读取其他 Page 的 React state；事件不会自动打开页面；提交模型上下文不会发起新一轮对话。
+
+## JSB 调用限制
+
+端工具在独立的 ToolRuntime 中执行，可调用的 JSB 受白名单限制。当前 Android 和 iOS 允许以下业务 JSB；表中名称是宿主方法名，业务仍通过 `@doubao-dev/framework/api` 中对应的公开 API 调用。
+
+| 类别 | 允许的 JSB |
+| --- | --- |
+| 账号与登录 | `doubao.getAccountInfo`、`doubao.login` |
+| 设置与授权状态 | `doubao.getSetting`、`doubao.getAppAuthorizeSetting`、`doubao.getSystemSetting` |
+| 系统与设备 | `doubao.getSystemInfo`、`doubao.getDeviceInfo` |
+| 网络与定位 | `doubao.request`、`doubao.getLocation` |
+| 埋点 | `doubao.reportEvent` |
+| 存储 | `doubao.setStorage`、`doubao.getStorage`、`doubao.removeStorage`、`doubao.clearStorage`、`doubao.getStorageInfo` |
+
+工具结果回传由 Framework 处理，业务只需返回符合协议的结果对象。
+
+不在白名单中的 JSB 会被拒绝，包括 `navigateTo`、`redirectTo`、`reLaunch`、`navigateBack`、`openPage` 等路由能力。SDK 导出了某个 API，或该 API 能在 Page / Widget 中使用，不代表它能在端工具中调用；需要页面跳转时，应在支持该路由能力的 Page / Widget 交互中完成。
+
+白名单放行也不代表调用必然成功：仍需满足接口权限、用户授权、宿主支持和限流等条件。在 `tools.json` 中声明 `permissions` 不能扩大端工具的 JSB 白名单；业务需要处理实际调用失败。
+
+
+
+## Schema 限制
+
+这里使用的是平台支持的 JSON Schema 子集，不支持 `enum`、数值上下界（`minimum` / `maximum`，即 min/max）等校验能力。不要在 schema 中添加这些约束；将可选值和取值范围写入字段 `description`，并在业务代码中校验。此限制同时适用于 `tools.json` 的 `inputSchema`、`outputSchema` 和 `events.json` 的 `payloadSchema`。
+
+优先使用基础结构字段 `type`、`properties`、`required`、`items` 和 `description`。描述中的约束不会自动执行：端工具在 handler 中检查输入，Page 在事件回调中检查 payload，输出也应符合声明的结果结构。
+
+## tools.json 与端工具注册
+
+在项目根目录声明 `tools.json`。`tools` 是非空数组；每项需要唯一 `name`、`description`、对象形式的 `inputSchema` 和 `outputSchema`。端工具显式设置 `tool_type: "client"`；省略时按远程工具处理。
+
+```json
+{
+  "tools": [
+    {
+      "name": "calculate_total",
+      "description": "Calculate an amount in integer cents when the user explicitly provides unit price and quantity. Does not create orders or charge money.",
+      "tool_type": "client",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "unit_price_cents": { "type": "integer", "description": "Non-negative unit price in cents" },
+          "quantity": { "type": "integer", "description": "Positive item count" }
+        },
+        "required": ["unit_price_cents", "quantity"]
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "total_cents": { "type": "integer" }
+        },
+        "required": ["total_cents"]
+      }
+    }
+  ]
+}
+```
+
+将以下配置合入 `src/app.config.ts`，保留现有页面与卡片配置。`entry` 相对于 `src/`，注册名称与 `tools.json.name` 必须一致。
+
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'your-app-id',
+  name: 'Amount Calculator',
+  tools: [{ entry: 'tools/calculate-total/index', name: 'calculate_total' }]
+});
+```
+
+在 `src/tools/calculate-total/index.ts` 默认导出 handler，接收解析后的对象，返回结果对象或 Promise。以下示例只计算整数分金额，不下单、不扣款：
+
+```ts
+export default function calculateTotal(input: Record<string, unknown>) {
+  const { unit_price_cents: unitPrice, quantity } = input;
+  if (
+    typeof unitPrice !== 'number' ||
+    !Number.isSafeInteger(unitPrice) ||
+    unitPrice < 0 ||
+    typeof quantity !== 'number' ||
+    !Number.isSafeInteger(quantity) ||
+    quantity <= 0
+  ) {
+    return {
+      isError: true,
+      content: [
+        { type: 'text', text: 'Provide a non-negative integer price and a positive integer quantity.' }
+      ]
+    };
+  }
+
+  // Integer cents avoid fractional currency rounding; reject unsafe totals before returning a result.
+  const total = unitPrice * quantity;
+  if (!Number.isSafeInteger(total)) {
+    return { isError: true, content: [{ type: 'text', text: 'The total exceeds the supported range.' }] };
+  }
+
+  return {
+    content: [{ type: 'text', text: `Total: ${total} cents. No order was placed.` }],
+    structuredContent: { total_cents: total }
+  };
+}
+```
+
+结果必须包含文本块 `content` 数组；`structuredContent` 可为对象或对象数组，业务失败返回 `isError: true`。运行时的外形检查不替代业务校验。
+
+需要卡片时：声明 `_meta.ui.widgetId` 并匹配注册的 Widget ID；`outputSchema` 使用对象数组，实体顶层恰有一个字段标记 `x-db-is-entity-id: true`；handler 返回对应实体数组。`entity_type` 由运行时补充，不在 schema 中声明。使用 `same_conversation` 过期策略时，同一个实体 ID 字段还必须是唯一的 `x-db-is-refresh-key`。
+
+## events.json 与页面订阅
+
+在项目根目录声明 `events.json`。根对象的 `events` 数组中，每项包含 `name`、`description` 和对象形式的 `payloadSchema`：
+
+```json
+{
+  "events": [
+    {
+      "name": "demo.pageDataUpdated",
+      "description": "Update the displayed title for the current page task when explicitly requested by the user.",
+      "payloadSchema": {
+        "type": "object",
+        "properties": {
+          "task_id": { "type": "string", "description": "The target page task ID" },
+          "title": { "type": "string", "description": "The title explicitly requested by the user" }
+        },
+        "required": ["task_id", "title"]
+      }
+    }
+  ]
+}
+```
+
+在开发者的业务 `SKILL.md` 中加入事件占位符；业务 Skill 的存放位置按项目组织，不由本开发 Skill 指定。事件名必须与声明和订阅一致：
+
+```text
+仅当用户明确要求修改已打开页面的标题时，发送 demo.pageDataUpdated 事件。
+目标任务 ID 使用当前页面上下文或用户明确提供的值，标题使用用户要求的内容。
+缺少必要信息时先追问。普通问答不发送此事件，也不声称该事件会保存服务端数据。
+
+{{event:demo.pageDataUpdated}}
+```
+
+将页面注册到 `app.config.ts.pages`，打开时传入 `taskId`。`task_id` 是业务目标标识，Framework 不会自动用它筛选页面：
+
+```tsx
+import { useAgentEvent, useState, useViewData } from '@doubao-dev/framework';
+
+export default function EventDemoPage() {
+  const { taskId } = useViewData<{ taskId?: string }>();
+  const [title, setTitle] = useState('Original title');
+
+  useAgentEvent('demo.pageDataUpdated', payload => {
+    // Event schemas do not enforce page ownership; validate the target before changing local state.
+    if (typeof taskId !== 'string' || !taskId || payload.task_id !== taskId) return;
+    if (typeof payload.title !== 'string' || !payload.title.trim()) {
+      console.error('Invalid demo.pageDataUpdated title');
+      return;
+    }
+    setTitle(payload.title);
+  });
+
+  if (!taskId) return <text>Missing taskId</text>;
+  return <text>{title}</text>;
+}
+```
+
+Framework 自动调用可选的 App `onAgentEvent` 后分发给订阅者，不要手动重复转发。Hook 随挂载订阅、卸载取消，不按页面可见性或栈顶筛选，也不重放历史事件。业务应校验目标、保证重复事件处理幂等，异步任务自行捕获错误。
+
+## 页面模型上下文
+
+在上面的页面中导入 `useEffect`、`useModelContext`，在条件返回前加入：
+
+```tsx
+const modelContext = useModelContext();
+
+useEffect(() => {
+  if (typeof taskId !== 'string' || !taskId) return;
+  void modelContext.setPageContext({
+    taskId,
+    pageInfo: {
+      context_schema: 'demo.page.v1',
+      task_id: taskId,
+      title
+    }
+  }).catch(error => {
+    console.error('Failed to update page context', error);
+  });
+}, [modelContext, taskId, title]);
+```
+
+每次提交完整 `pageInfo`，不依赖局部字段合并。控制器稳定，但不会自动同步 React state；通过依赖最新 state 的 Effect 提交。处理调用失败，在下一轮对话确认模型使用最新页面值。此 Hook 的 `{ taskId, pageInfo }` 与 `/api` 的 `updateModelContext({ taskId?, entityId?, content })` 参数不同。
+
+## 调试检查
+
+- 端工具：先固定参数直接运行，再检查真实调用结果；非法输入应返回业务错误。
+- 页面事件：先打开页面，再手动触发；错误目标和非法 payload 不更新状态；随后验证 Agent 事件链路。
+- 页面上下文：修改状态并提交后，在下一轮对话核对最新值。
+- Web 模拟器通过不代表目标宿主已验证；需要读取运行现场时参考[Debugger MCP](debugger-mcp.md)。

package/skills/doubao-agentic-service-development/references/frontend/guides/component-development.md

@@ -289,7 +289,7 @@ export default defineAppConfig({
       id: 'my-widget',                 // 卡片唯一标识
       name: '我的卡片',                 // 卡片名称
       description: '卡片功能描述',       // 卡片描述
-      boxType: 'inbox',                // 卡片类型: inbox | full_box
+      boxType: 'inbox',                // 卡片类型: inbox | full_box | custom_box
       border: true,
       keywords: ['demo', 'widget'],
       titleType: 'none'                // 不展示标题栏
@@ -390,6 +390,12 @@ export default defineAppConfig({
 });
 ```
 
+**3. custom_box - 自定义容器样式**
+
+在 `src/app.config.ts` 的 Widget entry 上配置 `boxType: 'custom_box'`，构建后 Manifest 对应
+`boxType: 4`。容器不添加默认背景、圆角和描边，由业务小程序的内容样式设置；标题栏仍由
+`titleType` 控制。未配置时仍默认为 `inbox`。
+
 ### ViewData 类型
 
 Widget viewData 通过 `useViewData<T>()` 的泛型参数和 TypeScript 接口表达。数据结构应尽量贴近所选模板的 props

package/skills/doubao-agentic-service-development/references/frontend/guides/debugger-mcp.md

@@ -44,7 +44,7 @@ Page / Widget 运行现场。它不替代用户业务 MCP server，只描述 deb
 - 方法：`POST /__wsd_mcp`。
 - 会话：当前实现不生成 session id，每次请求创建一次 MCP server / transport。
 - CORS 预检：`OPTIONS /__wsd_mcp` 返回 204。
-- 数据来源：调试台 UI 通过 `/__wsd_connection` WebSocket 同步运行期快照、接收控制命令和 Sandbox 事件，查询 tools 从 debugger server 内存中的最新快照读取数据。`/__agent_trace` 保留为 HTTP 快照访问接口。
+- 数据来源：调试台 UI 通过 `/__wsd_connection` WebSocket 同步运行期快照、接收控制命令和 Sandbox 事件，查询 tools 从 debugger server 内存中的最新快照读取数据。`GET /__agent_trace` 保留为只读的 HTTP 快照访问接口。
 - 浏览器控制：调试台通过共享 WebSocket 通道接收控制命令；渲染命令会在目标完成渲染且生成匹配命令的新 DOM 快照后回执。
 
 Web SDK Debugger 连接用户业务 MCP endpoint 时使用自动版本协商：优先选择 `2026-07-28`，对只支持 2025-era

package/skills/doubao-agentic-service-development/references/frontend/widget-templates/overview.md

@@ -7,7 +7,7 @@
 1. **一个 widget 一张卡片**：入口组件直接 return 模板组件，不要再包 `view` / `scroll-view`。
 2. **统一从 `@doubao-dev/template` 导入**模板组件和类型；新 Widget 默认直接导出组件函数。
 3. **优先用模板，不手搓卡片**：先按选型表找模板并使用其公开 Props；匹配不上时按模板能力或新设计需求确认。
-4. **新代码不传 `children`**：部分模板和列表项仍保留该属性，但已经废弃，只用于兼容旧项目。生成或修改代码时，改用当前模板的结构化字段或已声明的具名 `ReactNode` 字段；没有匹配字段时按模板能力或新设计需求确认。
+4. **新代码不传 `children`**：改用当前模板的结构化字段或已声明的具名 `ReactNode` 字段；一个业务语义需要多个已知模块时使用 `CompositeCard`，不要自行开放卡片布局。
 5. **显式标注列表类型**：每个模板导出 `XxxProps` 和列表项类型，例如 `ContentCardItem`、`CheckoutCardProductItem`。
 6. **header/footer 统一约定**：带标题栏和底部操作区的模板统一使用 `header` / `footer`。`header` 只控制标题栏，`footer` 只控制底部按钮，二者不影响内容区展示数量。
 7. **底部按钮对象**：`footer.primaryActionButton` / `footer.secondaryActionButton` 内传 `text`、`onClick`、`disabled`、`loading`、`throttle`。只传一个按钮时占据整行。
@@ -19,14 +19,15 @@
 
 按业务意图依次判断：
 
-1. 核对并提交订单：通用商品、机票或出行票务订单都使用 `CheckoutCard`。
-2. 展示地图、路线、位置或叫车状态：用 `MapCard`。
-3. 展示多条交通行程：用 `TransitCard`。
-4. 在多个报价、权益或服务方案中选择：用 `PriceActionCard`。
-5. 让用户在候选项中确认或执行固定跳转：用 `AskHumanCard`；单个或两个全宽跳转项使用 `variant="jump"`。
-6. 其余图文、商品或服务列表：用 `ContentCard`。
+1. 一个业务语义需要组合多个模板已知模块，且没有完全匹配的具名模板：用 `CompositeCard`。
+2. 核对并提交订单：通用商品、机票或出行票务订单都使用 `CheckoutCard`。
+3. 展示地图、路线、位置或叫车状态：用 `MapCard`。
+4. 展示多条交通行程：用 `TransitCard`。
+5. 在多个报价、权益或服务方案中选择：用 `PriceActionCard`。
+6. 让用户在候选项中确认或执行固定跳转：用 `AskHumanCard`；单个或两个全宽跳转项使用 `variant="jump"`。
+7. 其余图文、商品或服务列表：用 `ContentCard`。
 
-不能按以上意图选型时，不要直接拼新的卡片外壳。先查现有模板的公开 Props；无法表达时将其作为模板能力或新设计需求确认。
+不能按以上意图选型时，不要直接拼新的卡片外壳。先查 `CompositeCard` 的 section 白名单；白名单仍无法表达时，将其作为模板能力或新设计需求确认。
 
 ## Widget 骨架
 
@@ -74,6 +75,7 @@ export default function ProductCard() {
 | 下单/支付确认（通用电商） | `CheckoutCard` | 商品摘要 + 提单信息 + 费用汇总 + 合计 + 操作按钮 |
 | 机票/出行下单确认 | `CheckoutCard` | 商品或票务摘要 + 订单信息 + 费用明细 + 合计 + 操作按钮 |
 | 交通票务推荐列表 | `TransitCard` | 多条出发/到达行程，全量展示 items |
+| 车票预订等复合业务 | `CompositeCard` | 在一个标准卡片外壳中按顺序组合行程、选项组等已知模块 |
 | 让用户在多个候选里人工确认 | `AskHumanCard` | 一组可点击选项，跳过入口也通过 items 表达 |
 | 单个全宽操作按钮（任务态） | `AskHumanCard`（`variant="jump"`） | 一个可带右箭头的全宽按钮 |
 
@@ -81,7 +83,8 @@ export default function ProductCard() {
 
 - **`header`**：标题栏配置，常用 `actionText` / `showAction` / `onActionClick`。
 - **`footer`**：底部操作区配置，常用 `primaryActionButton` / `secondaryActionButton`。
-- **`children`**：部分模板为兼容旧项目保留的废弃属性，新代码不要使用。
+- **`children`**：不用于自定义卡片布局；复合场景使用 `CompositeCard.sections`。
+- **`CompositeCard.sections`**：单层有序数组，只接受白名单 `type`，不接受任意 JSX；复用模块保留原有内容留白，`OptionGroup` 在组合卡内由专用容器补充左右 12px、下方 16px，上方不额外留白。
 - **图片资源**：传运行时可访问的图片 URL；本地图片放到业务项目 `src/assets` 后静态 `import` 再传入，不要直接写 `'/assets/xxx.png'`。`ContentCard` 普通缩略图使用 `thumbnailSrc`，需要媒体节点时使用 `thumbnail`，且节点优先。
 - **`className` / `style` / `onClick`**：作用在卡片根节点。
 - **列表项 `key`**：不传默认用数组下标，建议显式传稳定 key。
@@ -104,6 +107,7 @@ export default function ProductCard() {
 |------|------|
 | `render` 里把模板包在 `view` / `scroll-view` 里 | 直接 `return <XxxCard ... />` |
 | 想做卡片却手写 `view`+`text`+`image` 拼布局 | 先查选型表和公开 Props；没有内容槽位时按新模板或设计需求确认 |
+| 用 `children` 或额外 `view` 拼接行程和乘车人选择 | 使用 `CompositeCard`，配置 `transit`、`content` 与 `option-group` sections |
 | 继续传 `moreText` / `primaryActionText` / `secondaryActionText` | 改为 `header.actionText` 和 `footer.primaryActionButton` / `footer.secondaryActionButton` |
 | 需要单个全宽跳转操作 | 使用 `AskHumanCard variant="jump"` 和一个 `items` 项 |
 | 列表项不传 `key` 导致更新错乱 | 给每个 item 传稳定 key |

package/skills/doubao-agentic-service-development/references/frontend/widget-templates/props.md

@@ -82,7 +82,7 @@
 
 `OptionGroupLargeItem`：`value` · `title` · `subtitle?` · `disabled?` · `onClick?`，不支持 `icon`。
 
-组件统一使用 8px 间距并自动换行；`lg` 最后一行保持单栏宽度，`md` 按内容宽度排列。用户点击时先触发选择变化，再触发 item 的 `onClick`；达到 `maxSelected` 后点击未选项不会触发 `onChange`，但仍会触发 item 的 `onClick`，已选项仍可取消；禁用项不触发事件。
+组件统一使用 8px 间距并自动换行；`lg` 单行选项平均填满可用宽度，发生换行后各行保持相同栏宽和列位置，`md` 按内容宽度排列。用户点击时先触发选择变化，再触发 item 的 `onClick`；达到 `maxSelected` 后点击未选项不会触发 `onChange`，但仍会触发 item 的 `onClick`，已选项仍可取消；禁用项不触发事件。
 
 ---
 
@@ -106,6 +106,29 @@
 
 ---
 
+## CompositeCard — 组合卡
+
+`import { CompositeCard, type CompositeCardContentSection, type CompositeCardOptionGroupSection, type CompositeCardProps, type CompositeCardSection, type CompositeCardTransitSection } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标准标题栏配置 |
+| `sections` | `CompositeCardSection[]` | 单层有序模块数组，按配置顺序展示 |
+| `footer` | `TemplateCardFooterProps` | 标准底部操作区配置 |
+| `className` / `style` / `onClick` | 对应根节点类型 | 作用在组合卡根节点 |
+
+当前白名单：
+
+- `CompositeCardTransitSection`：`{ type: 'transit', props: { items?: TransitCardItem[] } }`。
+- `CompositeCardContentSection`：`{ type: 'content', props: { items?: ContentCardItem[] } }`；只复用 ContentCard 的内容区域，不渲染其卡片外壳、header 或 footer。
+- `CompositeCardOptionGroupSection`：`{ type: 'option-group', props: OptionGroupProps }`。
+
+`props` 透传给对应模块，因此模块原有的回调、`className`、`style` 和具名 `ReactNode` 字段仍然有效；组合器不开放 section `children`、任意 JSX、布局参数或 wrapper 样式，也不提供独立标题字段。标题、说明等内容通过 `content` section 表达。卡片统一管理标准 header/footer，复用模块保留原有内容留白、内部布局与窄屏策略；`OptionGroup` 由组合卡内的专用容器补充左右 12px、下方 16px，上方不额外留白。
+
+`items` 为空的 section 会连同间距一起收起；运行时未知 `type` 不展示。`sections` 不支持运行中插入、删除或重排，不要求配置 section key。
+
+---
+
 ## MapCard — 地图卡
 
 `import { MapCard, type MapCardMapProps, type MapCardMetaItem, type MapCardProps, type TemplateCardFooterActionButton } from '@doubao-dev/template'`
@@ -230,6 +253,8 @@ MapCard 的 `ref` 直接绑定到内部 Map，可通过 `MapRef` 调用地图实
 
 `TransitCardTag`：`text: string | number` · `tone?: 'marketing' | 'neutral'`（默认 `marketing`）。标签展示在价格下方；不传 `tag` 时保持单价格布局。
 
+窄屏下模板会先压缩行程与价格之间的空白，再压缩出发、中转和到达列之间的空白；空间仍不足时隐藏价格，内容块本身保持原有宽度。
+
 ---
 
 ## AskHumanCard — 人工确认选项卡

package/skills/doubao-agentic-service-development/references/frontend-dev.md

@@ -208,6 +208,7 @@ my-doubao-app/
 - **内置组件**：`button`、`switch`、`slider` 等直接使用小写标签，不要从组件包 import；`button` 点击使用 `onClick`，不要使用 `onTap` / `bindtap`；`switch.onChange` 直接接收 `boolean`，`slider.onChange` 直接接收 `number`，`slider` 不支持 `step` / `defaultValue`；事件和 props 先查 [组件 API](frontend/components/overview.md)
 - **Lynx 渲染规则**：实现 Page / Widget 的布局或样式前，先按 [Lynx API 文档导航](frontend/lynx/overview.md) 读取匹配文档；不要套用 Web HTML/CSS 的默认行为
 - **Framework Hooks**：`useState`、`useEffect` 等 Hooks 必须从 `@doubao-dev/framework` 导入，不要从 `react` 导入
+- **端工具与全页事件**：实现前先读[端工具、事件与页面上下文](frontend/guides/client-tools-and-events.md)，确认 `tools.json`、`events.json` 格式和入口注册。端工具调用宿主 API 前还需确认参考页中的 JSB 白名单及适用范围，不能沿用 Page / Widget 的可调用能力。两者使用平台支持的 JSON Schema 子集，不支持 `enum`、`minimum` / `maximum`（min/max）等校验；可选值和范围写入 `description`，由 handler 或事件回调校验。
 - **调试现场读取**：本地 Web SDK 调试台可通过 Debugger MCP 暴露只读运行现场；需要读取 runtime console、trace events、simulator tool calls 或 log snapshot 时，先查 [Debugger MCP 协议](frontend/guides/debugger-mcp.md)
 - **错误处理**：处理边界情况和错误状态
 
@@ -351,6 +352,7 @@ doubao build --env-mode ppe
 
 | 任务 | 必读 | 可选 | 不要读 / 不要做 |
 |-----|----------|--------|------|
+| 开发端工具、声明 Agent 事件、提交页面模型上下文 | [端工具、事件与页面上下文](frontend/guides/client-tools-and-events.md) | [Framework 核心参考](frontend/framework/core.md) | 不要向 schema 添加 `enum`、min/max 等不支持的约束；不要假设工具可直接读取页面 state |
 | 创建 Page | [component-development.md](frontend/guides/component-development.md) 的 Page 开发、[dos-and-donts.md](frontend/rules/dos-and-donts.md) 的 Page 布局规则 | [page-widget-basics.md](frontend/examples/page-widget-basics.md) 的 Page 完整示例 | 不要同时加载全部 guides；不要把 Page metadata 写进源码入口 |
 | 创建 Widget | [Widget 模板库](frontend/widget-templates/overview.md) 的选型指南和模板 props、[component-development.md](frontend/guides/component-development.md) 的 Widget 开发 | [page-widget-basics.md](frontend/examples/page-widget-basics.md) 的 Widget 模板接入示例 | 不要手写卡片布局；不要把 Widget metadata 写进源码入口 |
 | 配置入口、metadata、多级目录、首页顺序 | [dos-and-donts.md](frontend/rules/dos-and-donts.md) 的 App 配置、入口和命名规则 | [component-development.md](frontend/guides/component-development.md) 的 Page / Widget 开发流程 | 不要省略显式入口的 `/index` |