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

package/dist/skills/doubao-plugin-app/references/frontend/guides/debugger-mcp.md

@@ -0,0 +1,537 @@
+# Debugger MCP 协议
+
+Web SDK Debugger MCP 是本地调试服务暴露给调试 Agent 的接口，用来发起模拟器对话，以及发现、渲染和读取当前
+Page / Widget 运行现场。它不替代用户业务 MCP server，只描述 debugger 自身的调试能力。
+
+## 目录
+
+- [Endpoint](#endpoint)
+- [Transport](#transport)
+- [Snapshot](#snapshot)
+- [Tools](#tools)
+- [`list_console_messages`](#list_console_messages)
+- [`get_console_message`](#get_console_message)
+- [`get_log_snapshot`](#get_log_snapshot)
+- [`list_render_targets`](#list_render_targets)
+- [`render_page`](#render_page)
+- [`render_widget`](#render_widget)
+- [`submit_chat_query`](#submit_chat_query)
+- [`set_viewport`](#set_viewport)
+- [`take_snapshot`](#take_snapshot)
+- [`get_computed_style`](#get_computed_style)
+- [`get_element_rect`](#get_element_rect)
+- [`scroll_to`](#scroll_to)
+- [`take_screenshot`](#take_screenshot)
+- [`list_agent_trace_events`](#list_agent_trace_events)
+- [`list_agent_tool_calls`](#list_agent_tool_calls)
+- [安全边界](#安全边界)
+
+## Endpoint
+
+本协议只约定 MCP endpoint path：
+
+```text
+/__wsd_mcp
+```
+
+完整 URL 的发现方式由启动器或宿主集成文档说明，不属于 Debugger MCP 协议本身。
+
+## Transport
+
+- 协议：MCP Streamable HTTP。
+- 协议版本：支持 `2026-07-28` modern era，也接受 2025-era legacy 请求；modern client 通过
+  `server/discover` 协商版本。
+- 方法：`POST /__wsd_mcp`。
+- 会话：当前实现不生成 session id，每次请求创建一次 MCP server / transport。
+- CORS 预检：`OPTIONS /__wsd_mcp` 返回 204。
+- 数据来源：调试台 UI 通过 `/__wsd_connection` WebSocket 同步运行期快照、接收控制命令和 Sandbox 事件，查询 tools 从 debugger server 内存中的最新快照读取数据。`GET /__agent_trace` 保留为只读的 HTTP 快照访问接口。
+- 浏览器控制：调试台通过共享 WebSocket 通道接收控制命令；渲染命令会在目标完成渲染且生成匹配命令的新 DOM 快照后回执。
+
+Web SDK Debugger 连接用户业务 MCP endpoint 时使用自动版本协商：优先选择 `2026-07-28`，对只支持 2025-era
+的 server 回退到 legacy handshake。每次 `tools/list` 或 `tools/call` 都建立独立 client，因此会重新执行协商，不缓存
+endpoint 的 era 判定。
+
+当 debugger server 尚未收到快照，或当前没有 Page / Widget 运行现场时，tools 返回：
+
+```json
+{
+  "stored": false
+}
+```
+
+如果 debugger server 已经记录过更新时间，返回体可能同时包含 `updatedAtMs`。
+
+## Snapshot
+
+MCP tools 读取 debugger server 内存中的最新 snapshot。
+
+所有 tools 都返回 MCP tool result：
+
+- `structuredContent`：任意 JSON value；当前 debugger 内置 tools 返回对象。
+- `content[0].text`：默认是同一 JSON 的格式化字符串；`take_snapshot` 直接返回 uid 文本树，方便 Agent 阅读。
+
+分页类 tools 的通用字段：
+
+| 字段 | 说明 |
+|------|------|
+| `stored` | 是否已有可读快照 |
+| `storedAt` | 快照写入时间 |
+| `updatedAtMs` | 快照更新时间戳 |
+| `total` | 当前过滤条件下的总数 |
+| `pageIdx` | 当前页序号，从 0 开始 |
+| `pageSize` | 每页条数，最大 200 |
+| `hasMore` | 是否还有下一页 |
+
+## Tools
+
+| Tool | 用途 | 关键参数 |
+|------|------|----------|
+| `list_console_messages` | 分页列出 runtime console | `target`、`levels`、`query`、`pageIdx`、`pageSize` |
+| `get_console_message` | 按 `msgid` 获取完整 console entry | `msgid` |
+| `get_log_snapshot` | 返回最近一次调试现场快照 | 无 |
+| `list_render_targets` | 列出 manifest 中可调试的 Page / Widget 及当前目标 | `type` |
+| `render_page` | 切换到全页视图并强制渲染指定路由 | `url` |
+| `render_widget` | 切换到卡片视图并渲染指定 Widget | `widgetId`、`structuredContent` |
+| `submit_chat_query` | 通过调试台对话框提交 query，并等待本轮生成结束 | `query` |
+| `set_viewport` | 设置当前 Page / Widget 的模拟视口尺寸 | `width`、`height` |
+| `take_snapshot` | 返回当前 Page / Widget 的 uid 文本树和可访问性信息 | `target`、`verbose` |
+| `get_computed_style` | 按快照 uid 查询元素的 computed style | `uid`、`properties` |
+| `get_element_rect` | 按快照 uid 查询元素的 x、y、width、height | `uid` |
+| `scroll_to` | 将当前 Page / Widget 的滚动容器移动到绝对坐标 | `uid`、`x`、`y` |
+| `take_screenshot` | 截取当前 Page / Widget 或指定 uid 元素 | `uid`、`format`、`quality` |
+| `list_agent_trace_events` | 分页列出 simulator / MCP / runtime trace events | `category`、`event`、`requestId`、`pageIdx`、`pageSize` |
+| `list_agent_tool_calls` | 分页列出 simulator tool calls | `toolName`、`status`、`requestId`、`query`、`pageIdx`、`pageSize` |
+
+除 `render_page`、`render_widget`、`submit_chat_query`、`set_viewport` 和 `scroll_to` 外，以上 tools 都是只读
+操作。渲染 tools 会改变本地调试台的当前视图和运行目标；`submit_chat_query` 会新增一轮对话并可能调用网络与 MCP
+tools；`set_viewport` 会改变当前模拟设备尺寸；`scroll_to` 会改变运行目标内滚动容器的当前位置。
+
+## `list_console_messages`
+
+`target` 可选值：
+
+- `current`：根据当前运行模式选择 Page / Widget / App。
+- `page`：只读 Page runtime console。
+- `widget`：只读 Widget runtime console。
+- `app`：只读 App runtime console。
+- `all`：读取全部 runtime console。
+
+`levels` 支持 `log`、`info`、`warn`、`error`、`debug`、`eval`。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  total: number;
+  pageIdx: number;
+  pageSize: number;
+  hasMore: boolean;
+  messages: Array<{
+    msgid: string;
+    target: 'page' | 'widget' | 'app';
+    level: string;
+    source: string;
+    timestamp: number;
+    text: string;
+    url?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    updatedAtMs?: number;
+  }>;
+}
+```
+
+列表项里的 `msgid` 可用于继续调用 `get_console_message` 读取完整参数和 stack。
+
+## `get_console_message`
+
+输入 `msgid`，返回：
+
+- `found`：是否命中。
+- `message`：完整 console entry，包括原始 `args`、位置和 stack 信息。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  found: true;
+  message: {
+    msgid: string;
+    target: 'page' | 'widget' | 'app';
+    level: string;
+    source: string;
+    timestamp: number;
+    text: string;
+    url?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    updatedAtMs?: number;
+    entry: Record<string, unknown>;
+  };
+}
+```
+
+未命中时返回：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  found: false;
+  msgid: string;
+}
+```
+
+## `get_log_snapshot`
+
+返回当前调试现场快照，包含 runtime console、trace events、tool calls 和调试上下文，适合 Agent 一次性读取当前现场。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  snapshot: Record<string, unknown>;
+}
+```
+
+## `list_render_targets`
+
+从最近一次调试快照列出 manifest 中可渲染的目标。`type` 可选值为 `all`、`page`、`widget`，默认 `all`。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  pages: Array<{
+    pageId: string;
+    path: string;
+    name: string;
+    isHome: boolean;
+  }>;
+  widgets: Array<{
+    widgetId: string;
+    name: string;
+  }>;
+  currentTarget?: RuntimeTargetInfo;
+}
+```
+
+首期只包含 manifest Page 和 Widget 模板，不包含对话区已经渲染的卡片实例。
+
+## `render_page`
+
+输入现有页面路由格式的 `url`，可携带 query。例如：
+
+```json
+{
+  "url": "/pages/weather/index?city=beijing"
+}
+```
+
+调用会切换到全页视图。即使当前已经是同一路由，也会强制重渲染。只有 Page controller 完成渲染，并生成携带同一
+command id 的新 DOM 快照后，tool 才返回成功：
+
+```ts
+{
+  rendered: true;
+  target: RuntimeTargetInfo;
+}
+```
+
+如需读取新页面结构，渲染成功后继续调用 `take_snapshot`。
+
+## `render_widget`
+
+输入 Widget id 和可选的 `structuredContent`：
+
+```json
+{
+  "widgetId": "weather-card",
+  "structuredContent": {
+    "city": "北京"
+  }
+}
+```
+
+`structuredContent` 默认 `{}`，不会复用调试台输入框的历史数据。调用会切换到卡片视图、同步输入框并强制渲染
+指定 Widget。成功返回与 `render_page` 相同的 `{ rendered, target }` 结构；随后调用 `take_snapshot` 读取新卡片
+结构。
+
+## `submit_chat_query`
+
+输入非空的 `query`：
+
+```json
+{
+  "query": "生成一张北京天气卡片"
+}
+```
+
+调用会切换到对话视图，并复用调试台输入框的正常提交流程；debugger server 不会绕过调试台直接请求 Simulator
+Gateway。tool 会等待本轮流式响应结束，成功时返回：
+
+```ts
+{
+  submitted: true;
+  completed: true;
+  query: string;
+  requestId: string;
+}
+```
+
+可用返回的 `requestId` 继续查询 `list_agent_trace_events` 和 `list_agent_tool_calls`，并通过 `get_log_snapshot`
+读取本轮 simulator message 和卡片数据。该 tool 只接收 `query`，不接收 token、header 或 session 参数；认证和
+Simulator 上下文均沿用当前调试台。
+
+## `set_viewport`
+
+输入模拟视口的 `width` 和 `height`，两者都必须是 1～9999 的整数：
+
+```json
+{
+  "width": 450,
+  "height": 844
+}
+```
+
+调用等价于在调试台选择自定义尺寸，只修改当前 Page / Widget 的模拟设备尺寸，不切换视图或运行目标。尺寸应用后返回：
+
+```ts
+{
+  updated: true;
+  viewport: {
+    width: number;
+    height: number;
+  };
+}
+```
+
+当前目标可能因设备尺寸变化而重新渲染；如需读取更新后的结构或图片，继续调用 `take_snapshot` 或 `take_screenshot`。
+
+## `take_snapshot`
+
+返回当前运行目标的 uid 文本树、可访问性信息、目标标识和视口信息。`target` 可选值为 `current`、`page`、
+`widget`，默认 `current`；指定类型与当前目标不一致时返回 `TARGET_MISMATCH`。`verbose: true` 会包含全部已采集
+属性和 `focusable=false` 等详细字段。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  available: true;
+  target: RuntimeTargetInfo;
+  nodeCount: number;
+  selectedUid?: string;
+  truncated: boolean;
+  snapshotUpdatedAtMs?: number;
+  snapshot: string;
+}
+```
+
+文本树示例：
+
+```text
+uid=root page
+  uid=title-1 text role="heading" name="天气" class="title" [selected]
+    uid=text-1 text "北京 26°C"
+```
+
+结构快照最多保留 5000 个节点，单个属性值最多保留 500 个字符；达到限制时 `truncated` 为 `true`。
+
+## `get_computed_style`
+
+输入 `take_snapshot` 返回的元素 `uid`，按需读取浏览器 `getComputedStyle` 结果。`properties` 可选；不传时返回全部
+computed style，传入时只返回指定 CSS 属性：
+
+```json
+{
+  "uid": "node-12",
+  "properties": ["display", "color", "font-size"]
+}
+```
+
+返回：
+
+```ts
+{
+  uid: string;
+  computedStyle: Array<{
+    name: string;
+    value: string;
+  }>;
+}
+```
+
+uid 不存在或对应节点不是元素时返回 `ELEMENT_NOT_FOUND`。
+
+## `get_element_rect`
+
+输入 `take_snapshot` 返回的元素 `uid`，返回相对于模拟设备视口的元素矩形；坐标和尺寸已经消除调试台显示缩放：
+
+```ts
+{
+  uid: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+## `scroll_to`
+
+按绝对坐标滚动当前 Page / Widget 中的容器。`uid` 来自 `take_snapshot`；传入时精确操作对应元素，不传时从当前
+inspector tree 中选择在运行目标视口内可见面积最大、且在请求坐标轴上有滚动范围的容器：
+
+```json
+{
+  "uid": "node-12",
+  "y": 480
+}
+```
+
+`x`、`y` 必须是大于等于 0 的有限数字。未传的坐标轴保持当前位置；两者都不传时只查询当前滚动信息。坐标超过
+范围时自动 clamp。滚动设置后等待两个 animation frame，再读取最终位置并返回：
+
+```ts
+{
+  scrolled: true;
+  uid: string;
+  x: number;
+  y: number;
+  maxX: number;
+  maxY: number;
+  viewportWidth: number;
+  viewportHeight: number;
+}
+```
+
+指定 uid 不存在时返回 `ELEMENT_NOT_FOUND`；当前没有运行目标时返回 `TARGET_NOT_FOUND`；找不到可滚动容器或请求
+坐标轴没有滚动范围时返回 `SCROLL_FAILED`。
+
+连续逐屏截图可由 Agent 编排 `scroll_to` 和 `take_screenshot`：
+
+1. 调用 `scroll_to({ y: 0 })`，保存返回的 `uid` 并截取当前目标。
+2. 若 `y !== maxY`，调用
+   `scroll_to({ uid, y: Math.min(y + viewportHeight, maxY) })`，再调用 `take_screenshot`。
+3. 重复上一步，直到返回 `y === maxY`。
+
+本期只负责逐屏滚动和截图，不生成或拼接完整长图。
+
+## `take_screenshot`
+
+不传 `uid` 时截取当前 Page / Widget 运行目标；传入 `uid` 时只截取对应元素。支持 `png`、`jpeg`、`webp`，默认
+`png`；`quality` 范围为 0～100，仅对 JPEG 和 WebP 生效：
+
+```json
+{
+  "uid": "node-12",
+  "format": "webp",
+  "quality": 80
+}
+```
+
+图片通过 MCP image content 返回，`structuredContent` 只包含元数据，不重复携带 base64：
+
+```ts
+{
+  captured: true;
+  format: 'png' | 'jpeg' | 'webp';
+  mimeType: string;
+  width: number;
+  height: number;
+  uid?: string;
+}
+```
+
+截图支持运行目标中的 open Shadow DOM。单张图片的 base64 负载限制为 8 MiB；跨域图片或字体无法被浏览器读取时可能返回
+`SCREENSHOT_FAILED`。
+
+## `list_agent_trace_events`
+
+按 `category`、`event`、`requestId` 过滤 trace events。常见 category 包括 `simulator`、`mcp`、`runtime`。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  total: number;
+  pageIdx: number;
+  pageSize: number;
+  hasMore: boolean;
+  events: Array<{
+    source: 'simulator' | 'widget_runtime' | 'page_runtime';
+    id: string;
+    timestamp: number;
+    category: string;
+    event: string;
+    requestId: string;
+    payload: unknown;
+  }>;
+}
+```
+
+## `list_agent_tool_calls`
+
+按 `toolName`、`status`、`requestId` 或 `query` 过滤 simulator tool calls。
+
+返回 `structuredContent`：
+
+```ts
+{
+  stored: true;
+  storedAt?: string;
+  updatedAtMs?: number;
+  total: number;
+  pageIdx: number;
+  pageSize: number;
+  hasMore: boolean;
+  toolCalls: Array<{
+    id: string;
+    requestId: string;
+    toolCallId: string;
+    toolName: string;
+    serverId: string;
+    appKey: string;
+    status: string;
+    createdAtMs: number;
+    updatedAtMs: number;
+    requiresUserApproval: boolean;
+    isMiniApp: boolean;
+    message: string;
+  }>;
+}
+```
+
+## 安全边界
+
+- 查询 tools 标记为 read-only，不修改调试现场。
+- `render_page`、`render_widget`、`submit_chat_query`、`set_viewport`、`scroll_to` 标记为非只读、非破坏性；
+  `set_viewport` 和 `scroll_to` 还标记为幂等、无外部网络访问。渲染、对话或调整尺寸可能触发生命周期、网络请求
+  和其他本地运行时副作用。
+- 同一调试台的控制命令串行执行；普通控制命令超时时间为 15 秒，`submit_chat_query` 为 120 秒；SSE 断线会
+  立即终止正在执行和排队的命令。
+- 控制命令失败返回 MCP error，并在 `structuredContent.error.code` 中使用
+  `DEBUGGER_NOT_CONNECTED`、`DEBUGGER_DISCONNECTED`、`TARGET_NOT_FOUND`、`ELEMENT_NOT_FOUND`、
+  `RENDER_FAILED`、`RENDER_TIMEOUT`、`VIEWPORT_FAILED`、`INSPECTION_FAILED`、`SCROLL_FAILED`、
+  `SCREENSHOT_FAILED`、`CHAT_NOT_READY`、`CHAT_BUSY`、`CHAT_SUBMIT_FAILED`、`CHAT_TIMEOUT` 或
+  `COMMAND_TIMEOUT`。
+  失败时不会把旧目标快照当作成功结果返回。
+- 不提供通用点击、输入或样式修改；`submit_chat_query` 只开放对话 query 提交。

package/dist/skills/doubao-plugin-app/references/frontend/guides/expired-widget.md

@@ -0,0 +1,101 @@
+# 失效卡片
+
+`expiredWidget()` 用于把已经过期的业务 Widget 实例更新成框架内置失效卡，通常在业务 Widget 内容失效后调用。
+
+`__doubao_apps__expired-widget` 是框架内置虚拟 Widget，不需要在 `src/widgets` 中创建同名目录，也不要手动注册到
+`src/app.config.ts`。
+
+`expiredWidget()` 的 `url` 是用户点击失效卡后跳转的目标 Page 路径或 schema。
+
+---
+
+## 当前 Widget 标记为失效
+
+在 Widget 内部可以通过 `getWidgetInstanceId()` 获取当前实例 ID，再调用 `expiredWidget()`。`getWidgetInstanceId()`
+只在 Widget 环境有值，在 Page 中通常返回 `undefined`。
+
+```ts
+import { getWidgetInstanceId } from '@doubao-dev/framework';
+import { expiredWidget } from '@doubao-dev/framework/api';
+
+async function markCurrentWidgetExpired() {
+  const widgetInstanceId = getWidgetInstanceId();
+  if (!widgetInstanceId) {
+    return;
+  }
+
+  await expiredWidget({
+    widgetInstanceId,
+    url: '/pages/detail/index?from=expired',
+    title: '内容已失效',
+    detailText: '点击查看最新内容'
+  });
+}
+```
+
+---
+
+## 从 Widget 打开 Page 并传递 widgetInstanceId
+
+如果需要在 Page 中处理过期逻辑，先在 Widget 中拿到 `widgetInstanceId`，通过页面跳转参数传给目标 Page。
+
+```tsx
+import { getWidgetInstanceId } from '@doubao-dev/framework';
+import { navigateTo } from '@doubao-dev/framework/api';
+
+export default function OrderWidget() {
+  const handleOpenDetail = async () => {
+    const widgetInstanceId = getWidgetInstanceId();
+    const query = widgetInstanceId ? `?widgetInstanceId=${encodeURIComponent(widgetInstanceId)}` : '';
+
+    await navigateTo({
+      url: `/pages/order-detail/index${query}`
+    });
+  };
+
+  return (
+    <view className="order-widget">
+      <button text="查看详情" onClick={handleOpenDetail} />
+    </view>
+  );
+}
+```
+
+---
+
+## Page 中读取 widgetInstanceId 并标记失效
+
+Page 不直接拥有 Widget 实例 ID。需要从 `useViewData<T>()` 读取上一步传入的 `widgetInstanceId`，或通过业务数据、通信等方式拿到目标实例 ID。
+
+```tsx
+import { useViewData } from '@doubao-dev/framework';
+import { expiredWidget } from '@doubao-dev/framework/api';
+import './index.scss';
+
+interface OrderDetailPageData {
+  widgetInstanceId?: string;
+}
+
+export default function OrderDetailPage() {
+  const viewData = useViewData<OrderDetailPageData>();
+
+  const handleMarkExpired = async () => {
+    if (!viewData.widgetInstanceId) {
+      return;
+    }
+
+    await expiredWidget({
+      widgetInstanceId: viewData.widgetInstanceId,
+      url: '/pages/order-detail/index?from=expired',
+      title: '订单状态已更新',
+      detailText: '点击查看最新订单状态'
+    });
+  };
+
+  return (
+    <view className="order-detail-page">
+      <button text="标记原卡片失效" disabled={!viewData.widgetInstanceId} onClick={handleMarkExpired} />
+    </view>
+  );
+}
+```