@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/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)。