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

package/dist/preview.js

@@ -0,0 +1,16 @@
+import chalk from "chalk";
+import qrcode from "qrcode";
+async function printPreview({ url, name, version, expiresAt }) {
+    console.log(`预览链接：${url}`);
+    if (!process.stdout.isTTY) return;
+    const { modules } = qrcode.create(url);
+    if (process.stdout.columns && modules.size + 6 > process.stdout.columns) throw new Error('终端宽度不足，请拉宽窗口后重试');
+    const qr = await qrcode.toString(url, {
+        type: 'utf8',
+        margin: 2
+    });
+    console.log(`\n${chalk.blue.bold('豆包扫码预览')} · ${name} ${version}\n`);
+    console.log(qr.split('\n').map((row)=>`  \x1b[38;2;0;0;0m\x1b[48;2;255;255;255m${row}\x1b[0m`).join('\n'));
+    if (expiresAt) console.log(chalk.dim(`有效期至 ${new Date(Number(expiresAt)).toLocaleString()}`));
+}
+export { printPreview };

package/dist/rslib-runtime.js

@@ -0,0 +1,33 @@
+var __webpack_modules__ = {};
+var __webpack_module_cache__ = {};
+function __webpack_require__(moduleId) {
+    var cachedModule = __webpack_module_cache__[moduleId];
+    if (void 0 !== cachedModule) return cachedModule.exports;
+    var module = __webpack_module_cache__[moduleId] = {
+        exports: {}
+    };
+    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+    return module.exports;
+}
+__webpack_require__.m = __webpack_modules__;
+(()=>{
+    __webpack_require__.d = (exports, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports, key)) Object.defineProperty(exports, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.add = function(modules) {
+        Object.assign(__webpack_require__.m, modules);
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+export { __webpack_require__ };

package/dist/skills/doubao-plugin-app/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: doubao-plugin-app
+description: 使用 @doubao-dev/plugin-cli 开发应用插件中的 App 页面、Widget 卡片、Manifest 和 MCP 出卡链路，使用 Web、真机和桌面工具调试。适用于包含 com.doubao/app/manifest.yaml 的 Plugin CLI 项目。
+metadata:
+  display_name: 应用插件 App 开发
+  display_description: 开发和调试应用插件的页面、卡片、Manifest 与 MCP 出卡链路。
+---
+
+# 应用开发
+
+本 Skill 配合 `@doubao-dev/plugin-cli` 使用；CLI 命令先读项目的 `doubao-plugin-cli` Skill。仅用于豆包 App 工程；普通 Skill、MCP 和 MCP Apps 项目不读取此 Skill，也不创建 App Manifest。
+
+`dbx init <name> --app` 新建 App，使用共享线上购物 MCP，包含业务 Skill、卡片和页面。运行 `dbx dev --app` 后，在 Web 模拟器发送“搜索牛奶”体验商品卡片。
+
+先读 [应用开发指南](references/app-development.md)，确认前端目录、依赖安装、Page / Widget 注册和 viewData 用法。开发调试先读其中的 [本地调试](references/app-development.md#本地调试)，使用新 Plugin CLI 的 Kit、Web 模拟器和状态命令。
+真机扫码、版本选择、断线恢复和桌面工具操作，阅读 [真机与桌面调试](references/app-development.md#真机与桌面调试)。
+涉及工具调用、运行态 Skill、实体或卡片不显示时，读 [MCP 与出卡配置](references/mcp-and-cards.md)，逐项对齐 Skill、MCP 返回、Manifest 和 Widget。
+
+App 前端配置以本 Skill 的应用开发指南为准；插件根配置和 CLI 操作统一读取 `doubao-plugin-cli` Skill。组件、Hooks、API、模板和 Lynx 资料复用 SDK 的开发 Skill，随应用开发工具包交付；项目配置以本 Skill 的应用开发指南为准，不要求手填 AppID。只读取当前任务需要的章节。
+
+CLI 命令和平台同步操作读取插件根目录下的 `.agents/skills/doubao-plugin-cli/SKILL.md`。

package/dist/skills/doubao-plugin-app/references/app-development.md

@@ -0,0 +1,85 @@
+# 应用开发指南
+
+## 项目与配置
+
+`plugin.json` 所在目录是插件根目录，前端位于 `com.doubao/app/`；下文的 `src/` 相对此目录。`dbx` 可以在根目录或前端目录运行。
+
+- 存在 `manifest.yaml` 才启用 App；CLI 优先按 `plugin.json.id`，其次按 name 查询 AppID，失败使用本地调试 ID。上传返回的插件 ID 自动保存，源清单和前端配置无需填写 AppID，发布时由服务端补齐。
+- `dbx init <name> --app` 准备独立的开发包、Kit 和前端依赖。跳过安装或安装失败时，在前端目录运行 `pnpm install`；工具包不需要加入前端依赖。
+- 新项目从npm registry 安装 `@doubao-dev/framework` 和 `@doubao-dev/template` 的 latest 版本，由项目 lockfile 固定解析结果；已有项目沿用自身包体系和版本。Hooks 从 framework 导入，端能力从 framework/api 导入。
+
+`com.doubao/app/src/app.config.ts` 示例：
+
+```ts
+export default {
+  name: '我的应用插件',
+  pages: ['pages/home/index'],
+  widgets: ['widgets/example/index']
+};
+```
+
+前端配置默认导出普通对象，按需声明 `pages`、`widgets` 和 metadata。AppID 由 CLI 管理，无需手填。
+
+## 实现与验证
+
+1. 工具调用或出卡变化先按 [MCP 与出卡配置](mcp-and-cards.md) 对齐业务 Skill、MCP 和 Manifest。
+2. 在 `src/widgets/<name>/index.tsx` 实现卡片，在 `src/pages/<name>/index.tsx` 实现全屏页面，在 `src/app.config.ts` 注册入口，保留已有配置。
+3. 使用 Lynx 的 `view`、`text`、`image` 和独立样式文件；布局按 Lynx 文档实现。Widget 优先使用 SDK 卡片模板，核对 props 后映射实体数据。
+4. `useViewData<T>()` 的类型与返回实体一致，并处理数据未到达的空态。字符串入口 `widgets/example/index` 的 Widget ID 为 `example`，显式对象入口使用其 `id`，均须与 Manifest 绑定一致。
+5. 请求放在生命周期或事件回调中并处理失败，密钥放在服务端。用 `dbx dev --app` 验证真实出卡、交互和导航，不能只以编译成功判断链路可用。
+
+页面、卡片和配置的完整示例以当前项目模板为准，SDK 用法按下表读取。
+
+上传前按项目根目录 `.agents/skills/doubao-plugin-cli/references/upload.md`检查本地图标、尺寸和路径；Web 调试成功不代表平台物料校验已通过。
+
+## 本地调试
+
+从根目录或 App 目录运行 `dbx dev --app`，复用已有实例。`dbx dev` 在含 App 的项目中会交互选择调试目标；`--plugin` 只调试 Skill / MCP，`--app` 同时调试 App。非 TTY 或指定 `--no-tui` 时不询问，未传 `--app` 默认只调试 Skill / MCP。Kit 缓存缺失时自动安装，默认版本由 CLI 构建时锁定，可用 `DBX_KIT_VERSION=<准确版本>` 覆盖，准备期间 Ctrl+C 可取消。
+
+- 源清单未填写 AppID 时，模拟器对话使用 Sandbox 会话创建返回的真实 `sandbox_appid`，会话重建后重新读取，不将占位 ID 写入请求清单。
+- `web` 打开模拟器，`status` 查看详情和 URL；非交互环境从日志获取地址；Agent 使用 `dbx dev --app --no-tui` 后台启动并读取服务状态和地址，保留进程句柄，不等待命令结束。真机和桌面工具按下文操作，命令在 dev 交互界面内输入，不是独立的 `dbx` 子命令。
+- 「本地」编译和「平台」同步并行；AppID 查询最多等待 5 秒。交互终端未登录时，dev 先完成浏览器授权再启动；非交互环境先完成登录。个人开发包只同步接口支持的非 App 模块，完整 App 包用 `dbx upload` 上传。
+- 前端改动由 Kit 热更新；业务 `skills/`、`mcp.json` 改动同步平台。MCP 地址或 headers 变化后自动重启 App 运行时；更改应用身份或 App 配置后重启 dev。
+- Web 模拟器只读取业务 `skills/<name>/SKILL.md` 正文。CLI 操作以项目的 `doubao-plugin-cli` Skill 和 `dbx --help` 为准；打开桌面工具时，在 dev 的 `device` 菜单输入 `desktop`。
+
+## 真机与桌面调试
+
+前提：CLI 能从平台查询到有效 AppID，手机能访问电脑的局域网资源地址。没有平台 AppID 时先使用 Web 模拟器；不能用 Web Sandbox 的兜底 ID 申请真机授权。
+
+1. 运行 `dbx dev --app`，等待应用编译就绪，输入 `device` 进入真机菜单。
+2. 输入 `version`，选择已上传的云端版本以调试对话和工具调用，或选择“本地调试，不绑定云端版本”。上下键选择、Enter 确认、Esc 返回。没有版本时可先使用本地调试。
+3. 使用手机豆包扫描终端中的连接二维码，等待调试包安装和连接就绪。已有可复用连接时不必重新扫码。
+4. 连接后用 `page` 或 `widget`，上下键选择页面或卡片，Enter 确认、Esc 返回。卡片能打开不代表 MCP 出卡成功，对话链路还需验证工具调用和实体数据。
+
+| 命令 | 用途 |
+| --- | --- |
+| `qr` | 沿用当前调试版本，重新生成连接二维码 |
+| `qr-size` | 二维码显示时切换半角/全角，不重新申请票据或断开连接；窗口过窄时拉宽终端 |
+| `version` | 选择云端版本或不绑定版本的本地调试；切换后会重新连接 |
+| `page` / `widget` | 连接后选择页面或卡片 |
+| `desktop` | 按需安装并打开桌面开发工具，与 CLI 共用设备连接，查看日志、截图和页面结构 |
+| `cancel` | 连接过程中取消，已连接时断开；空闲时不显示 |
+| `back` | 返回上级菜单；已连接时保留连接，未连接完成时取消连接 |
+
+`status` 在主菜单查看调试详情，不在每个子菜单重复提供。命令可用 Tab 补全，Ctrl+C 退出开发会话并清理连接。
+
+连接短暂中断会等待 30 秒恢复，先等待，不要立即重新扫码；超时后按提示执行 `qr`。无法连接时检查 AppID、登录账号、手机到电脑的网络可达性，再查看 `status` 和桌面日志。
+
+这里的二维码用于连接本地开发服务，需要保持 dev 运行。`dbx upload` 输出的是云构建成功后的预览二维码；它与本地连接二维码用途不同，上传成功也不代表云构建或预览已成功。
+
+## 按需读取 SDK 参考资料
+
+| 场景 | 参考资料 |
+| --- | --- |
+| Page / Widget、生命周期、viewData | [组件开发](frontend/guides/component-development.md) |
+| 选择卡片模板和核对 props | [模板索引](frontend/widget-templates/overview.md) |
+| 内置组件的 props 和事件 | [组件索引](frontend/components/overview.md) |
+| 网络、导航、位置等端能力 | [API 速查](frontend/doubao-agentic-service-api/quick-reference.md) |
+| Hooks 与框架核心能力 | [Framework](frontend/framework/core.md) |
+| 布局、CSS、Lynx 与 Web 差异 | [Lynx 索引](frontend/lynx/overview.md) |
+| 登录和隐私授权入口 | [前端授权](frontend/guides/auth.md) |
+| 端工具、事件、页面模型上下文 | [端工具与事件](frontend/guides/client-tools-and-events.md) |
+| 模拟器日志、Trace、工具调用现场 | [Debugger MCP](frontend/guides/debugger-mcp.md) |
+| 编译和运行问题 | [排障指南](frontend/guides/troubleshooting.md) |
+
+前端项目配置由本 Skill 单独维护，API、组件和样式资料与 SDK 共用。登录、跳转等 API 的 AppID 参数按对应接口说明填写，与项目配置中的 AppID 注入分别处理。

package/dist/skills/doubao-plugin-app/references/frontend/components/container-overlay.md

@@ -0,0 +1,131 @@
+# 容器与覆层组件
+
+## `<view>`
+
+基础布局容器，最常用。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+| flatten | boolean | true | 扁平化节点，避免创建真实渲染对象，提升性能 |
+| onClick | (e: TouchEvent) => void | - | 点击 |
+| onLongPress | (e: TouchEvent) => void | - | 长按 |
+| onTouchStart / onTouchEnd / onTouchMove | (e: TouchEvent) => void | - | 触摸事件 |
+| onAppear | (e: UIAppearanceEvent) => void | - | 进入可视区域 |
+| onDisappear | (e: UIAppearanceEvent) => void | - | 离开可视区域 |
+
+---
+
+## `<popup>`
+
+支持拖拽、多位置停靠的弹窗。
+
+```tsx
+import type { PopupRef } from '@doubao-dev/framework/components';
+import { useRef } from '@doubao-dev/framework';
+
+const popupRef = useRef<PopupRef>(null);
+
+// 打开弹窗
+popupRef.current?.open();   // 默认中心
+popupRef.current?.open(1);  // 顶部
+popupRef.current?.open(-1); // 底部
+popupRef.current?.close();
+
+<popup
+  ref={popupRef}
+  scrollContainerId="popup-scroll"
+  maxHeight={lynx.__globalProps.screenHeight}
+  closeOnMaskClick
+  enableDrag
+  onPopupPositionChange={(pos) => {
+    // 0=中心, 1=顶部, -1=底部, 4=关闭
+  }}
+>
+  {({ 'main-thread:gesture': gesture }) => (
+    <view id="popup-scroll" style={{ height: '100%' }}>
+      <text>弹窗内容</text>
+    </view>
+  )}
+</popup>
+```
+
+### PopupRef 方法
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| open | position?: 0 \| 1 \| -1 | 打开弹窗。0 中心 / 1 顶部 / -1 底部，默认中心 |
+| close | - | 关闭弹窗 |
+| translateTo | position: number \| string | 移动到指定位置，支持数字或 "px" / "%" / "rpx" |
+
+### PopupProps
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| scrollContainerId | string | - | **必填**，内部滚动容器 ID |
+| children | (prop: RenderFunction) => ReactElement | - | 渲染函数 |
+| autoHeight | boolean | false | 根据内容高度自动调整 |
+| contentId | string | - | autoHeight 为 true 时需要设置 |
+| enableDrag | boolean | true | 启用拖拽 |
+| enableBounces | boolean | true | 松手回弹 |
+| closeOnMaskClick | boolean | true | 点击遮罩关闭 |
+| maxHeight | number | screenHeight | 最大高度 |
+| heightPercent | HeightPercent | - | `{ init, top, bottom, boundaryArea, flingThreshold }` |
+| bottomNode | ReactElement | - | 固定在弹窗底部的节点，不受拖动影响 |
+| enterDuration / exitDuration | number | 300 | 进入/退出动画时长 (ms) |
+| onPopupPositionChange | (position: number) => void | - | 位置变化回调 |
+| onPopupTopChange | (height: number) => void | - | 高度变化回调 |
+
+---
+
+## `<movable-area>` / `<movable-view>`
+
+```tsx
+<movable-area style={{ width: '100%', height: '300px' }}>
+  <movable-view direction="all" scale outOfBounds inertia friction={2} damping={20}>
+    <text>拖我 / 双指缩放</text>
+  </movable-view>
+</movable-area>
+```
+
+### movable-view 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| direction | `'all' \| 'vertical' \| 'horizontal' \| 'none'` | `'all'` | 移动方向 |
+| disabled | boolean | false | 禁用 |
+| x / y | number | 0 | 初始偏移 |
+| scale | boolean | false | 双指缩放 |
+| scaleValue | number | 1 | 初始缩放值 |
+| scaleMin / scaleMax | number | 0.5 / 10 | 缩放范围 |
+| outOfBounds | boolean | false | 允许超出区域（松手回弹） |
+| animation | boolean | true | 回弹动画 |
+| damping | number | 20 | 阻尼系数，值越大回弹越快 |
+| inertia | boolean | false | 惯性滑动 |
+| friction | number | 2 | 摩擦系数，值越大越快停止（必须 > 0） |
+| onDrag | (x: number, y: number) => void | - | 拖拽回调 |
+| onScale | (scale: number) => void | - | 缩放回调 |
+
+---
+
+## `<theme-provider>`
+
+让子树消费 `--bg-*` / `--neutral-*` / `--primary-*` 等 CSS 变量时跟随宿主主题（light/dark）。
+
+内置组件会自动应用主题，只在业务自定义内容需要主题变量时才需要包裹。
+
+```tsx
+<theme-provider>
+  <view style={{ background: 'var(--bg-1)' }}>
+    <text style={{ color: 'var(--neutral-text-1)' }}>跟随主题的文字</text>
+  </view>
+</theme-provider>
+```
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | ReactNode | - | 子元素 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+| flatten | boolean | false | 默认 false，因为该容器需作为 CSS 变量作用域 |

package/dist/skills/doubao-plugin-app/references/frontend/components/form-controls.md

@@ -0,0 +1,146 @@
+# 表单组件
+
+## `<input>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| ref | Ref\<InputRef\> | - | 实例 ref |
+| value | string | - | 受控值 |
+| defaultValue | string | - | 非受控默认值 |
+| placeholder | string | - | 占位文本 |
+| type | `'text' \| 'number' \| 'digit' \| 'password' \| 'tel' \| 'email'` | `'text'` | 输入类型 |
+| maxlength | number | 140 | 最大长度 |
+| disabled | boolean | false | 禁用 |
+| readonly | boolean | false | 只读 |
+| confirmType | `'send' \| 'search' \| 'go' \| 'done' \| 'next'` | `'send'` | 键盘确认按钮类型 |
+| showSoftInputOnFocus | boolean | true | 聚焦时是否显示软键盘 |
+| onInput | (e: BaseEvent\<'bindinput', InputInputEvent\>) => void | - | 输入变化，取值 `e.detail.value` |
+| onFocus | (e: BaseEvent\<'bindfocus', InputFocusEvent\>) => void | - | 聚焦 |
+| onBlur | (e: BaseEvent\<'bindblur', InputBlurEvent\>) => void | - | 失焦 |
+| onConfirm | (e: BaseEvent\<'bindconfirm', InputConfirmEvent\>) => void | - | 点击确认按钮 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+### InputRef 方法
+
+| 方法 | 类型 | 说明 |
+|------|------|------|
+| setValue | (value: string) => Promise\<void\> | 设置值 |
+| getValue | () => Promise\<{ value: string; selectionStart: number; selectionEnd: number }\> | 获取值和选区 |
+| focus | () => Promise\<void\> | 聚焦 |
+| blur | () => Promise\<void\> | 失焦 |
+
+```tsx
+import type { InputRef } from '@doubao-dev/framework/components';
+import { useState, useRef } from '@lynx-js/react';
+
+// 受控
+const [val, setVal] = useState('');
+<input value={val} onInput={(e) => setVal(e.detail.value)} placeholder="请输入" />
+
+// 通过 ref 控制
+const inputRef = useRef<InputRef>(null);
+<input ref={inputRef} placeholder="请输入" />
+<button onClick={() => inputRef.current?.focus()}>聚焦</button>
+
+// 密码输入
+<input type="password" maxlength={20} placeholder="请输入密码" />
+```
+
+---
+
+## `<textarea>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| placeholder | string | - | 占位文本 |
+| maxlength | number | 140 | 最大长度 |
+| maxlines | number | - | 最大行数 |
+| lineSpacing | number \| `${number}px` \| `${number}rpx` | - | 行间距 |
+| disabled | boolean | false | 禁用 |
+| readonly | boolean | false | 只读 |
+| confirmType | `'send' \| 'search' \| 'go' \| 'done' \| 'next'` | `'done'` | 确认按钮类型 |
+| showSoftInputOnFocus | boolean | true | 聚焦时显示软键盘 |
+| bounces | boolean | true | iOS 弹性效果 |
+| onInput | (e: TextAreaInputEvent) => void | - | 输入变化 |
+| onFocus | (e: TextAreaFocusEvent) => void | - | 聚焦 |
+| onBlur | (e: TextAreaBlurEvent) => void | - | 失焦 |
+| onConfirm | (e: TextAreaConfirmEvent) => void | - | 点击确认按钮 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+<textarea
+  placeholder="请输入内容"
+  maxlength={500}
+  maxlines={5}
+  onInput={(e) => console.log(e.detail.value)}
+/>
+```
+
+---
+
+## `<picker-view>` / `<picker-column>` / `<picker-divider>`
+
+嵌入页面的滚动选择器。
+
+**关键约束：**
+- `picker-view` 高度必须用 **inline `style.height`** 传入，不能只写在 CSS class 中，否则内部 JS 无法同步读取高度，offset 回退为 108px
+- `itemHeight` 要与 `style.height` 配合设置
+
+### picker-view 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| style | CSSProperties | - | **height 必须 inline 传入** |
+| itemHeight | number | 36 | 单个选项高度 (px) |
+| theme | `'light' \| 'dark'` | - | 未传时跟随宿主主题 |
+| onChange | (values: (string \| number)[], options: PickerColumnOption[]) => void | - | 所有列选中项变化 |
+| className | string | - | 样式类名 |
+
+### picker-column 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| options | `{ label: string; value: string \| number; disabled?: boolean }[]` | 列数据 |
+| value | string \| number | 受控当前值 |
+| defaultValue | string \| number | 非受控默认值 |
+| onChange | (value: string \| number, option: PickerColumnOption) => void | 当前列变化 |
+| className | string | 列的类名 |
+| style | CSSProperties | 列的样式 |
+
+### picker-divider 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| text | string | 展示文本 |
+| children | ReactNode | 自定义内容，优先级高于 text |
+| className | string | 类名 |
+| style | CSSProperties | 样式 |
+
+`picker-divider` 不参与值计算，不会出现在 `onChange` 的 values/options 中。
+
+```tsx
+const hours = Array.from({ length: 24 }, (_, i) => ({ label: String(i).padStart(2, '0'), value: i }));
+const minutes = ['00', '15', '30', '45'].map(v => ({ label: v, value: v }));
+
+// 时间选择器（带分隔符）
+<picker-view
+  style={{ height: '216px' }}
+  itemHeight={36}
+  onChange={(values) => console.log('选中:', values)}
+>
+  <picker-column options={hours} defaultValue={10} />
+  <picker-divider text=":" />
+  <picker-column options={minutes} defaultValue="00" />
+</picker-view>
+
+// 年月日选择器
+const years = Array.from({ length: 10 }, (_, i) => ({ label: `${2020 + i}年`, value: 2020 + i }));
+const months = Array.from({ length: 12 }, (_, i) => ({ label: `${i + 1}月`, value: i + 1 }));
+
+<picker-view style={{ height: '216px' }} itemHeight={36}>
+  <picker-column options={years} defaultValue={2024} />
+  <picker-column options={months} defaultValue={1} />
+</picker-view>
+```

package/dist/skills/doubao-plugin-app/references/frontend/components/interactive-controls.md

@@ -0,0 +1,120 @@
+# 交互控件组件
+
+## `<button>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| text | string | - | 按钮文字 |
+| type | `'primary' \| 'default' \| 'plain'` | `'primary'` | 样式类型 |
+| size | `'default' \| 'large' \| 'mini'` | `'default'` | 尺寸 |
+| disabled | boolean | false | 禁用 |
+| loading | boolean | false | 加载中状态 |
+| icon | ReactNode | - | 文字前的图标 |
+| children | ReactNode | - | 自定义内容，优先级高于 icon/text |
+| throttle | number | 500 | onClick 节流时间 (ms) |
+| onClick | (e?: TouchEvent) => void | - | 点击回调 |
+| onDisabledClick | (e?: TouchEvent) => void | - | 禁用状态下点击回调 |
+| openType | `'getPhoneNumber' \| 'agreePrivacyAuthorization' \| 'agreePrivacyAuthorization\|getPhoneNumber'` | - | 开放能力 |
+| onGetPhoneNumber | (e: GetPhoneNumberResult) => void | - | 获取手机号回调，openType 包含 getPhoneNumber 时有效 |
+| onAgreePrivacyAuthorization | (e: AgreePrivacyResult) => void | - | 隐私授权回调，openType 包含 agreePrivacyAuthorization 时有效 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+// 基础按钮
+<button text="提交" type="primary" onClick={() => handleSubmit()} />
+
+// 加载状态
+<button text="加载中" loading />
+
+// 自定义内容
+<button>
+  <image src="icon.png" style={{ width: '16px', height: '16px' }} />
+  <text>自定义按钮</text>
+</button>
+
+// 开放能力：获取手机号
+<button
+  openType="getPhoneNumber"
+  onGetPhoneNumber={(e) => console.log(e)}
+/>
+```
+
+---
+
+## `<switch>`
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| checked | boolean | - | 受控值；设置后 defaultChecked 被忽略 |
+| defaultChecked | boolean | false | 非受控默认值 |
+| disabled | boolean | false | 禁用 |
+| size | `'default' \| 'large'` | `'large'` | 尺寸 |
+| onChange | (checked: boolean) => void | - | 状态变化，直接接收 boolean，不是事件对象 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+// 非受控
+<switch defaultChecked onChange={(checked) => console.log(checked)} />
+
+// 受控
+const [on, setOn] = useState(false);
+<switch checked={on} onChange={setOn} />
+```
+
+---
+
+## `<slider>`
+
+**仅支持受控用法，必须传 `value`。**
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | number | - | **必填**，当前值 |
+| min | number | 0 | 最小值 |
+| max | number | 100 | 最大值 |
+| showValue | boolean | true | 是否显示当前数值 |
+| disabled | boolean | false | 禁用 |
+| onChange | (value: number) => void | - | 数值变化，直接接收 number |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+```tsx
+const [volume, setVolume] = useState(50);
+<slider value={volume} min={0} max={100} onChange={setVolume} />
+```
+
+---
+
+## `<radio-group>` / `<radio>`
+
+```tsx
+const [selected, setSelected] = useState('a');
+
+<radio-group value={selected} onChange={(v) => setSelected(v)}>
+  <radio value="a">选项 A</radio>
+  <radio value="b">选项 B</radio>
+  <radio value="c" disabled>选项 C（禁用）</radio>
+</radio-group>
+```
+
+### radio-group 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | string \| number | 当前选中值（受控） |
+| defaultValue | string \| number | 默认值（非受控） |
+| onChange | (value: string \| number) => void | 选中变化回调 |
+| className | string | 样式类名 |
+| style | CSSProperties | 内联样式 |
+
+### radio 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | string \| number | 该项的值 |
+| disabled | boolean | 禁用 |
+| children | ReactNode | 标签内容 |
+| className | string | 样式类名 |
+| style | CSSProperties | 内联样式 |

package/dist/skills/doubao-plugin-app/references/frontend/components/map-canvas.md

@@ -0,0 +1,107 @@
+# 地图与画布组件
+
+## `<map>` / `<map-marker>`
+
+完整文档见 SDK 的 `map.md`。
+
+### map 核心属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| ref | Ref\<MapRef\> | - | 实例 ref |
+| center | `{ longitude: number; latitude: number }` | - | 地图中心 |
+| scale | number | 16 | 缩放级别（3-20） |
+| minScale / maxScale | number | 3 / 20 | 缩放范围 |
+| polyline | Polyline[] | [] | 路线数组 |
+| polygons | Polygon[] | [] | 多边形数组 |
+| circles | Circle[] | [] | 圆数组 |
+| rotate | number | 0 | 旋转角度（度） |
+| showScale | boolean | false | 显示比例尺 |
+| enableScale | boolean | true | 允许缩放 |
+| enableDrag | boolean | true | 允许拖动 |
+| enableRotate | boolean | false | 允许旋转 |
+| mapStyle | `'normal-light' \| 'normal-dark' \| 'simple-light' \| 'simple-dark' \| string` | `'normal-light'` | 地图主题，支持内置主题；自 0.2.1 起支持自定义样式 ID |
+| onClick | (e: { point: { latitude: number; longitude: number } }) => void | - | 点击地图 |
+| onMapLoaded | () => void | - | 地图加载完成 |
+| onRegionChange | (e) => void | - | 视野变化 |
+| className | string | - | 样式类名 |
+| style | CSSProperties | - | 内联样式 |
+
+### MapRef 方法
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| setCenter | (center, scale?) | 设置中心点 |
+| getCenter | () | 获取当前中心点 |
+| getScale | () | 获取当前缩放级别 |
+| setScale | (scale) | 设置缩放级别 |
+| getBound | () | 获取可见区域边界 |
+| setBound | (bounds) | 设置可见区域边界 |
+| fitPoints | (points, padding?) | 视野适配点集，padding 顺序 `[left, right, top, bottom]` |
+| setAnchor | (position) | 设置地图锚点 |
+
+### map-marker 核心属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| position | `{ longitude: number; latitude: number }` | - | 坐标（必填） |
+| children | ReactNode | - | 自定义标记点 UI（必填） |
+| anchor | [number, number] | [0.5, 1] | 经纬度在图标上的锚点 |
+| alpha | number | 1 | 透明度（0-1） |
+| rotation | number | 0 | 旋转角度（0-360） |
+| clickable | boolean | true | 是否可点击 |
+| draggable | boolean | false | 是否可拖拽 |
+| onClick | () => void | - | 点击回调 |
+
+```tsx
+import type { MapRef } from '@doubao-dev/framework/components';
+import { useRef } from '@doubao-dev/framework';
+
+const mapRef = useRef<MapRef>(null);
+
+<map
+  ref={mapRef}
+  center={{ longitude: 116.397, latitude: 39.916 }}
+  scale={15}
+  style={{ width: '100%', height: '300px' }}
+  onMapLoaded={() => mapRef.current?.fitPoints([
+    { longitude: 116.39, latitude: 39.91 },
+    { longitude: 116.40, latitude: 39.92 },
+  ])}
+>
+  <map-marker position={{ longitude: 116.397, latitude: 39.916 }} onClick={() => console.log('clicked')}>
+    <view style={{ width: '24px', height: '24px', background: '#FF3B30', borderRadius: '50%' }} />
+  </map-marker>
+</map>
+```
+
+---
+
+## `<canvas>`
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| ref | Ref\<CanvasRef\> | 实例 ref，获取绘图上下文 |
+| style | CSSProperties | 内联样式（设置宽高） |
+| className | string | 样式类名 |
+| onResize | (e: CanvasResizeEvent) => void | 尺寸变化回调 |
+
+### CanvasRef 方法
+
+通过 ref 获取实例后调用 `getContext('2d')` 获取 2D 绘图上下文，API 与 Web Canvas 基本一致。
+
+```tsx
+import type { CanvasRef } from '@doubao-dev/framework/components';
+import { useRef, useEffect } from '@doubao-dev/framework';
+
+const canvasRef = useRef<CanvasRef>(null);
+
+useEffect(() => {
+  const ctx = canvasRef.current?.getContext('2d');
+  if (!ctx) return;
+  ctx.fillStyle = '#FF3B30';
+  ctx.fillRect(10, 10, 100, 100);
+}, []);
+
+<canvas ref={canvasRef} style={{ width: '300px', height: '300px' }} />
+```