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

package/dist/skills/doubao-plugin-app/references/frontend/widget-templates/props.md

@@ -0,0 +1,301 @@
+# Template 模板 Props 参考
+
+`priceExtraLoading` 在列表项上配置，默认 `false`，统一控制操作文案或 Tag 的加载状态。加载时隐藏原内容但保留区域高度，在下方区域靠右、垂直居中显示与 Button 相同的 16px 加载图标，图标右边缘与价格区域右边缘对齐。颜色跟随当前文案或标签文字并适配深浅色，屏蔽该区域点击；上方价格不变。没有非空文案和标签时不新增加载区域，业务负责切换状态。
+
+所有模板从 `@doubao-dev/template` 导入。本文件记录当前版本支持的模板 Props 与行为约束。
+
+约定：
+
+- `TemplateText = string | number`，`TemplateKey = string | number`。
+- `TemplateCardHeaderProps`：`actionText?: string` · `showAction?: boolean` · `onActionClick?: (event) => void`。
+- `TemplateCardFooterProps`：`primaryActionButton?: TemplateCardFooterActionButton` · `secondaryActionButton?: TemplateCardFooterActionButton`。
+- `TemplateCardFooterActionButton`：`text?` · `disabled?` · `loading?` · `throttle?` · `onClick?`。
+- `header`、`footer` 和内容区相互独立。footer 不会影响 `items` 展示数量。
+- 只使用各模板和列表项明确声明的公开字段。
+- 只使用各模板和列表项明确声明的字段；没有匹配字段时不要自行拼装结构，按模板能力或新设计需求确认。
+- `onClick` 作用在卡片根节点；卡片和 primitives 均不支持 `className` / `style`。
+- 图片资源传运行时可访问 URL；本地图片放到业务项目 `src/assets` 后静态 `import` 再传入。
+
+---
+
+## Title — 标题展示组件
+
+`import { Title, type TitleMaxLines, type TitleProps, type TitleValue } from '@doubao-dev/template/primitives'`
+
+`Title` 用于卡片内容中的一行或两行标题排版，不是独立卡片模板。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `text` | `string \| number` | 标题内容 |
+| `maxLines` | `1 \| 2` | 最大行数，默认 `1`；超出后末行渐隐，不显示省略号 |
+| `showArrow` | `boolean` | 是否展示右侧箭头，默认 `true` |
+| `loading` | `boolean` | 展示扫光占位 |
+
+箭头紧跟实际文字末尾，两行时跟随第二行末字；超长时保留箭头并渐隐其前方文字。隐藏箭头时，超长文字仍渐隐。
+
+---
+
+## Tag — 标签展示组件
+
+`import { Tag, type TagProps, type TagTone, type TagValue } from '@doubao-dev/template/primitives'`
+
+`Tag` 用于卡片内容中的营销、权威或常规辅助标签，不是独立卡片模板。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `text` | `string \| number` | 标签内容，不截断 |
+| `tone` | `'marketing' \| 'authority' \| 'neutral'` | 标签色调，默认 `authority` |
+
+多个标签由业务容器横向排列，标签间距为 4px，容器高度为 26px；标签内容不会收缩或截断，空间不足时由业务容器隐藏放不下的整枚标签。
+
+---
+
+## Icon — 图标组件
+
+`import { Icon, type IconName, type IconProps } from '@doubao-dev/template/primitives'`
+
+`Icon` 通过名称选择模板体系提供的图标。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `name` | `'add'` | 图标名称，当前仅支持 `add` |
+
+`Icon` 只负责展示，不接收点击或状态属性；可点击的添加控件使用 `TemplateExtraAction` 的 `add` 类型。
+
+---
+
+## OptionGroup — 选项集合组件
+
+`import { OptionGroup, type OptionGroupItem, type OptionGroupProps, type OptionGroupSize, type OptionGroupValue } from '@doubao-dev/template/primitives'`
+
+`OptionGroup` 用于座席、乘车人等选择场景，不是独立卡片模板；只接收结构化 `items`，不支持 `children`。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `items` | `OptionGroupItem[]` | 选项数据，`value` 必须唯一 |
+| `size` | `'md' \| 'lg'` | 默认 `md`；`md` 内容撑开，`lg` 按栏等分 |
+| `columns` | `number` | 仅 `lg` 支持，每行栏数默认 `3` |
+| `selectionMode` | `'single' \| 'multiple'` | 默认单选 |
+| `value` | `OptionGroupValue \| OptionGroupValue[]` | 受控选择值，类型由选择模式决定 |
+| `maxSelected` | `number` | 仅多选模式支持；双选时传 `2` |
+| `onChange` | `(nextValue, item, event) => void` | 选择变化回调，返回完整的新值 |
+
+`OptionGroupMediumItem`：`value` · `title` · `icon?: IconName` · `disabled?` · `onClick?`，不支持 `subtitle`。
+
+`OptionGroupLargeItem`：`value` · `title` · `subtitle?` · `disabled?` · `onClick?`，不支持 `icon`。
+
+组件统一使用 8px 间距并自动换行；`lg` 单行选项平均填满可用宽度，发生换行后各行保持相同栏宽和列位置，`md` 按内容宽度排列。用户点击时先触发选择变化，再触发 item 的 `onClick`；达到 `maxSelected` 后点击未选项不会触发 `onChange`，但仍会触发 item 的 `onClick`，已选项仍可取消；禁用项不触发事件。
+
+---
+
+## Price — 价格展示组件
+
+`import { Price, type PricePrefixTone, type PriceProps, type PriceTone, type PriceValue } from '@doubao-dev/template/primitives'`
+
+`Price` 用于卡片内容中的价格排版，不是独立卡片模板。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `value` | `string \| number` | 价格值；字符串保留前导零和末尾小数位 |
+| `currency` | `string` | 币种符号，默认 `¥`；空字符串隐藏 |
+| `prefix` / `suffix` | `string` | 价格前缀 / 后缀 |
+| `prefixTone` | `'default' \| 'highlight' \| 'muted'` | 前缀主文字色 / 营销红 / `--neutral-70`；不传时跟随价格色调 |
+| `description` | `string` | 价格后的辅助信息 |
+| `originalPrice` | `string \| number` | 原价，以删除线展示 |
+| `tone` | `'default' \| 'highlight'` | 默认色或营销强调色 |
+| `loading` | `boolean` | 展示扫光占位 |
+
+---
+
+## Stepper — 数量调节组件
+
+`import { Stepper, type StepperProps } from '@doubao-dev/template/primitives'`
+
+`Stepper` 是受控组件，点击后业务需根据 `onChange` 更新 `value`；也可作为 `ContentCardItem.action` 的 `stepper` 类型使用。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `value` | `number` | 当前数量 |
+| `min` | `number` | 最小值，默认 `0` |
+| `max` | `number` | 可选的最大值 |
+| `onChange` | `(value: number, event: TouchEvent) => void` | 点击可用的加减按钮时返回下一数量 |
+
+每次增减 `1`；达到 `min` 或 `max` 时对应按钮不可点击，不触发 `onChange`。
+数值区域固定宽 38px，左右各留 4px；组件总宽 86px，超长数值单行省略，不会撑宽组件。
+
+---
+
+## CompositeCard — 组合卡
+
+`import { CompositeCard, type CompositeCardContentSection, type CompositeCardOptionGroupSection, type CompositeCardProps, type CompositeCardSection, type CompositeCardTransitSection } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标准标题栏配置 |
+| `sections` | `CompositeCardSection[]` | 单层有序模块数组，按配置顺序展示 |
+| `footer` | `TemplateCardFooterProps` | 标准底部操作区配置 |
+| `onClick` | `(event: TouchEvent) => void` | 卡片根节点点击回调 |
+
+当前白名单：
+
+- `CompositeCardTransitSection`：`{ type: 'transit', props: { items?: TransitCardItem[] } }`。
+- `CompositeCardContentSection`：`{ type: 'content', props: { items?: ContentCardItem[] } }`；只复用 ContentCard 的内容区域，不渲染其卡片外壳、header 或 footer。
+- `CompositeCardOptionGroupSection`：`{ type: 'option-group', props: OptionGroupProps }`。
+
+`props` 透传给对应模块，因此模块原有的回调和具名内容字段仍然有效；组合器不开放 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'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `mapProps` | `Omit<MapProps, 'className' \| 'style'>` | 地图配置；卡片统一管理地图宽高和类名 |
+| `title` | `TemplateText` | 信息区单行标题 |
+| `showArrow` | `boolean` | 是否展示标题箭头，默认 `true` |
+| `metaItems` | `MapCardMetaItem[]` | 辅助信息，最多展示前 2 项 |
+| `inlineActions` | `TemplateCardFooterActionButton[]` | 右侧紧凑操作，最多展示前 2 个；双按钮依次按次按钮、主按钮渲染 |
+| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
+
+`MapCardMetaItem`：`key?` · `text: TemplateText` · `tone?: 'default' | 'highlight'`。多项之间由模板渲染分隔点。
+
+地图区域高度固定为 168px。信息区和 footer 都是可选结构，可分别单独展示或组合展示。MapCard 不支持 `children`；地图覆盖物通过 `mapProps.children` 传入。
+MapCard 的 `ref` 直接绑定到内部 Map，可通过 `MapRef` 调用地图实例方法。
+地图左上角的应用插件标题由客户端 `titleType` 控制，MapCard 不重复渲染来源标题。
+
+---
+
+## ContentCard — 列表卡
+
+`import { ContentCard, type ContentCardItem, type ContentCardProps, type TemplateExtraAction, type TemplateCardHeaderProps, type TemplateCardFooterProps } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
+| `items` | `ContentCardItem[]` | 列表数据，全量展示 |
+| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
+
+`ContentCardItem`：`key?` · `title?: string | number | ReactElement`（字符串/数字最多一行；两行标题传 `<Title maxLines={2} />`）· `subtitle?: string | number | ReactElement`（字符串/数字最多一行）· `description?: string | number | ReactElement`（字符串/数字最多一行）· `thumbnailSrc?: string` · `thumbnail?: ReactElement`（优先于 `thumbnailSrc`）· `action?: TemplateExtraAction`（包含 `stepper` 数量调节器）· `onClick?`
+
+`TemplateExtraAction`：
+
+- `{ type: 'button', text, disabled?, loading?, onClick? }`
+- `{ type: 'add', disabled?, loading?, onClick? }`（24px × 24px 添加控件，内部图形为 12px × 12px，与 Stepper 的加号一致）
+- `{ type: 'stepper', value, min?, max?, onChange? }`（受控数量调节器，宽 86px，单次增减 1）
+- `{ type: 'switch', checked, disabled?, onChange? }`（受控）
+- `{ type: 'playback', playing, progress?, disabled?, onToggle? }`（受控；`progress` 范围 `0~1`）
+
+同一列表项的 `action.type` 从 `add` 切换为 `stepper` 时保持右侧加号位置并向左展开；由业务显式切换类型，不根据 `value` 自动展开或收起。
+带缩略图时，文字高度超过 80px 图片则顶对齐，否则垂直居中；操作区始终相对图片垂直居中。
+
+---
+
+## PriceActionCard — 价格操作卡
+
+`import { PriceActionCard, type PriceActionCardItem, type PriceActionCardInfoRow, type PriceActionCardProps } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
+| `items` | `PriceActionCardItem[]` | 价格列表 |
+| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
+
+`PriceActionCardItem`：`key?` · `price?: TemplateText` · `badgeText?: TemplateText` · `infoRows?: PriceActionCardInfoRow[]`（最多前 2 行）· `actionText?` · `onClick?` · `onActionClick?`
+
+`PriceActionCardInfoRow`：`key?` · `text: TemplateText`
+
+---
+
+## CouponCard — 券卡
+
+`import { CouponCard, type CouponCardItem, type CouponCardProps } from '@doubao-dev/template'`
+
+`items?: CouponCardItem[]`，默认空数组；`onClick?: (event) => void` 为卡片根节点点击回调。
+
+`CouponCardItem`：`key?` · `value: string | number` · `unit?: string`（默认 `元`）· `condition?: string` · `sourceName?: string` · `title?: string` · `validityText?: string` · `actionText?: string`（默认 `立即用`，空字符串隐藏）· `disabled?: boolean` · `loading?: boolean` · `onClick?` · `onActionClick?`。
+
+- 按 `items.length` 自动布局：单券高 80px、最大宽 400px；双券高 80px、间距 8px、每张最大宽 200px；三张及以上高 112px、间距 4px、每张宽 96–150px，超出横向滚动。
+- `title`、`validityText` 仅在单券中展示；所有文案限制一行，超出省略。
+- `disabled` 时整体透明度 50%，禁止券与按钮点击；使用后的文案与状态由业务更新。
+- `loading` 由业务控制，复用 Button 加载态，保持操作按钮宽度并禁止重复点击；不影响券内容点击及整体透明度。
+- 按钮不触发券或根节点点击；券配置 `onClick` 时阻止向根节点冒泡，未配置则保留冒泡。
+- 仅支持结构化文本与回调，不支持 ReactNode、`children`、`style`、`className`，无 `header` / `footer`。
+
+---
+
+## CheckoutCard — 提单卡（通用电商）
+
+`import { CheckoutCard, type CheckoutCardProductItem, type CheckoutCardInfoItem, type CheckoutCardFeeItem, type CheckoutCardProps } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
+| `productItems` | `CheckoutCardProductItem[]` | 商品摘要，支持单/多个 |
+| `infoItems` | `CheckoutCardInfoItem[]` | 提单信息列表 |
+| `feeItems` | `CheckoutCardFeeItem[]` | 费用明细，优惠信息也通过该属性传入 |
+| `totalLabel` / `totalPrice` | `string` / `TemplateText` | 合计标签 / 合计价格 |
+| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
+
+`CheckoutCardProductItem` 继承商品摘要 props，并增加 `key?`。常用字段：`title?` · `tagText?: TemplateText`（展示在标题前）· `tagTone?: 'default' | 'highlight'`（默认 `default`）· `spec?` · `imageSrc?` · `image?: ReactElement` · `pricePrefix?` · `price?: TemplateText` · `quantity?: TemplateText` · `showChevron?` · `onClick?`
+
+`CheckoutCardInfoItem`：`key?` · `label: string` · `value: TemplateText` · `valueExtra?: TemplateText`。两项使用相同样式，并与左侧 label 的首行对齐。
+
+`CheckoutCardFeeItem`：`key?` · `label: string` · `value: TemplateText`
+
+`feeItems` 作为单行整体与 `totalLabel` / `totalPrice` 共同布局；空间不足时合计整体换到第二行，两组各自超宽时单行省略，汇总区域最多两行。
+
+---
+
+## TransitCard — 交通票务列表卡
+
+`import { TransitCard, type TransitCardItem, type TransitCardPrice, type TransitCardPriceAction, type TransitCardPriceActionTone, type TransitCardProps, type TransitCardTag } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
+| `items` | `TransitCardItem[]` | 行程列表，全量展示 |
+| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
+
+`TransitCardItem`：`key?` · `title?: string | number | ReactElement` · `departureMain?` / `departureSub?: TemplateText` · `transferTop?` / `transferBottom?: TemplateText` · `arrivalMain?` / `arrivalDayOffset?` / `arrivalSub?: TemplateText` · `price?: TransitCardPrice | TemplateText` · `priceAction?: TransitCardPriceAction` · `tag?: TransitCardTag` · `priceExtraLoading?: boolean` · `onClick?` · `onRouteClick?` · `onPriceClick?`
+
+`onRouteClick` 覆盖左侧行程热区（含标题），`onPriceClick` 覆盖右侧价格热区（含标签或操作文案）。区域回调使用 `TouchEvent`，触发时不会再触发列表项 `onClick`；未配置区域回调时保留原有整项点击行为。
+
+`TransitCardPrice`：`value: string | number` · `currency?: string`（默认 `¥`）· `prefix?: string` · `prefixTone?: 'default' | 'highlight' | 'muted'`（不传时跟随价格色调）· `tone?: 'default' | 'highlight'`。生成新代码时只使用结构化价格配置。
+
+`price` 传数字时作为 `Price.value` 并使用默认币种；传字符串时按首个币种符号拆为 `prefix + currency + value`，没有币种符号时整串作为 `value` 且 `currency=""`。标量价格使用 Price 的默认 `tone`。
+
+`TransitCardPriceAction`：`text: string | number` · `tone?: 'highlight' | 'muted'`（默认 `highlight`）· `showIcon?: boolean`（默认 `true`）。操作文案展示在价格下方，箭头样式由模板统一管理；与 `tag` 同时传入时优先展示 `priceAction`。
+
+`TransitCardTag`：`text: string | number` · `tone?: 'marketing' | 'neutral'`（默认 `marketing`）。标签展示在价格下方；不传 `tag` 时保持单价格布局。
+
+窄屏下模板会先压缩行程与价格之间的空白，再压缩出发、中转和到达列之间的空白；空间仍不足时隐藏价格，内容块本身保持原有宽度。
+
+---
+
+## AskHumanCard — 人工确认选项卡
+
+`import { AskHumanCard, type AskHumanCardItem, type AskHumanCardProps } from '@doubao-dev/template'`
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `items` | `AskHumanCardItem[]` | 选项列表 |
+| `variant` | `'suggestion' \| 'jump'` | 选项行为语义；默认 `suggestion`，单个或两个固定跳转按钮用 `jump` |
+| `onClick` | `(event) => void` | 卡片根节点点击 |
+
+`AskHumanCardItem`：`key?` · `text?: TemplateText` · `loading?` · `openType?: 'launchApp'` · `launchAppUrl?` · `showArrow?: 'left' | 'right' | 'none'` · `onClick?` · `onLaunchApp?` · `onLaunchAppError?`
+
+跳过、固定跳转等入口也通过 `items` 表达；`showArrow` 支持 `'left'`、`'right'`、`'none'`，默认不展示。单个全宽操作按钮用
+`variant="jump"` 和一个 `items` 项表达。
+
+## 内容槽位静态检查
+
+文本字段类型为 `string | number | ReactElement`；构建检查允许字符串、数字或直接传入的 primitive `Tag` / `Title`。
+媒体字段类型为 `ReactElement`；构建检查仅允许直接传入的 `<image />` 或 `<svg />`。
+类型声明只约束值的类别，不能区分 JSX 的具体元素；primitive 从 template 的 `primitives` 子入口导入。
+构建对可静态确定的违规节点输出 `[卡片检查]` warning，不改变运行时行为。
+检查支持当前文件的常量、导入别名、命名空间、对象/数组展开、条件表达式和表达式形式的 map 回调。
+跨文件数据、动态函数返回值等无法确定的内容会跳过；没有 warning 不代表所有内容均已验证。

package/dist/skills/doubao-plugin-app/references/mcp-and-cards.md

@@ -0,0 +1,38 @@
+# MCP、业务 Skill 与卡片
+
+## 配置职责
+
+| 文件 | 职责 |
+| --- | --- |
+| 根目录 `mcp.json` | `mcpServers.<连接名>` 配置 type、url 和 headers，Web 模拟器目前接入单个 `streamable-http` 服务 |
+| `plugin.json` | `extensions.com.doubao.mcpServers.<连接名>` 提供 displayName 和 displayDescription 多语言展示信息，连接名与 mcp.json 一致 |
+| `com.doubao/app/manifest.yaml` | 声明工具输出、实体 schema 和卡片绑定；配置 mcp_server 时与 mcp.json 指向同一服务 |
+| `skills/<name>/SKILL.md` | 指导模型何时调用工具、参数规则和结果处理 |
+
+MCP 连接和服务展示信息属于整个插件，始终维护在插件根目录；`extensions.com.doubao` 是平台命名空间，不代表这些配置属于 App。App Manifest 只维护应用侧工具输出、实体和卡片绑定。
+
+新项目已配置共享线上购物服务，无需启动本地 MCP。使用自建服务时由开发者启动；发布时应使用平台可访问的地址。
+
+## 业务 Skill
+
+每个业务 Skill 使用独立目录，YAML frontmatter 必须包含非空的 `name`、`description`、`metadata.display_name`（展示名称）和 `metadata.display_description`（展示描述）。`name` 与所在目录名一致，并避免与平台已有 Skill 重名；重命名时同步修改目录和字段。展示字段必须放在 `metadata` 下，不能用顶层 `description` 代替；以当前项目的业务 Skill 为例修改。
+
+正文中的字段名、必填项、类型、范围和示例必须与 MCP `tools/list` 的 `inputSchema` 一致。购物示例 `search_products` 的 query 为非空字符串，limit 为 1～10 的整数；用户要求更多结果时也不能传入 100 等越界值。
+
+依据工具实际结果回答，失败时说明原因。辅助资料可放入 references、scripts、assets，但当前 Web 模拟器只读取 SKILL.md 正文，不加载这些附件。
+
+## 出卡契约
+
+按当前模板的商品搜索链路，逐项核对：
+
+1. 工具返回 `structuredContent.entities`；文本 `content` 不能代替结构化实体。
+2. 每个实体的 `entity_type` 命中 Manifest 的 `entities`，`is_entity_id: true` 字段实际存在且稳定标识该实体。
+3. `tools.<工具名>.output` 声明 `kind: entities` 和对应的 `entity_types`。
+4. 实体的 `tool_card_binding.<工具名>` 指向 app.config.ts 中的 Widget ID；一个列表实体可以渲染一张含多项的卡片。
+5. Widget 用 `useViewData<T>()` 读取该实体，字段和类型与返回数据一致，最后映射成卡片模板 props。
+
+业务错误返回 `isError: true`，通过 structuredContent 的 code 和 message 提供数字错误码及文案，不生成成功实体。
+
+## 排查顺序
+
+先检查工具是否调用成功和参数校验，再核对原始实体、Manifest 映射、Widget 注册及字段，最后查看本地编译和 [模拟器日志与 Trace](frontend/guides/debugger-mcp.md)。平台同步与本地编译分别判断；反复安装不能解决个人测试插件接口不支持 App 的限制。

package/dist/templates/README.md.template

@@ -0,0 +1,11 @@
+# __PLUGIN_NAME__
+
+应用插件项目，包含购物 MCP、商品搜索业务 Skill、App 页面和卡片。
+
+```sh
+dbx dev --app
+```
+
+输入 `web` 打开 Web 模拟器，发送“搜索牛奶”查看商品卡片。
+
+项目配置与上传见 [CLI 开发 Skill](.agents/skills/doubao-plugin-cli/SKILL.md)，页面和卡片开发见 [App 开发 Skill](.agents/skills/doubao-plugin-app/SKILL.md)。链接缺失时运行 `dbx skills`。

package/dist/templates/com.doubao/app/manifest.yaml

@@ -0,0 +1,41 @@
+manifest_version: 2
+permissions: []
+mcp_server:
+  end_point: https://s0piqd9123oupmbgufs9i.apigateway-cn-beijing.volceapi.com/mcp
+  description: 初始化模板使用的共享购物示例 MCP 服务
+  mcp_config:
+    protocol: Streamable
+tools:
+  search_products:
+    login_type: no_login
+    description: 根据关键词搜索商品，返回商品名称、规格和价格。
+    output:
+      kind: entities
+      entity_types:
+        - product_search_entity
+entities:
+  product_search_entity:
+    schema:
+      search_id:
+        type: string
+        is_entity_id: true
+      entity_type:
+        type: string
+        llm_visible: false
+      query:
+        type: string
+      products:
+        type: array
+        items:
+          type: object
+          properties:
+            sku_id:
+              type: string
+            name:
+              type: string
+            spec:
+              type: string
+            price:
+              type: float
+    tool_card_binding:
+      search_products: example

package/dist/templates/com.doubao/app/package.json.template

@@ -0,0 +1,13 @@
+{
+  "name": "__PLUGIN_NAME__-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@doubao-dev/framework": "latest",
+    "@doubao-dev/template": "latest"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  }
+}

package/dist/templates/com.doubao/app/src/app.config.ts.template

@@ -0,0 +1,5 @@
+export default {
+  name: '__PLUGIN_NAME__',
+  pages: ['pages/home/index'],
+  widgets: ['widgets/example/index']
+};

package/dist/templates/com.doubao/app/src/app.ts.template

@@ -0,0 +1,3 @@
+import { defineApp } from '@doubao-dev/framework';
+
+export default defineApp({});

package/dist/templates/com.doubao/app/src/pages/home/index.css

@@ -0,0 +1,14 @@
+.page {
+  padding: 24px;
+}
+.title {
+  font-size: 24px;
+  font-weight: 600;
+  margin-bottom: 16px;
+}
+.description {
+  font-size: 16px;
+  color: #666666;
+  line-height: 24px;
+  margin-bottom: 12px;
+}

package/dist/templates/com.doubao/app/src/pages/home/index.tsx.template

@@ -0,0 +1,14 @@
+import './index.css';
+
+export default function HomePage() {
+  return (
+    <view>
+      <navigation-bar title="示例页面" />
+      <view className="page">
+        <text className="title">应用插件已连接</text>
+        <text className="description">你已从对话卡片打开示例页面。</text>
+        <text className="description">修改此页面或卡片代码，保存后即可查看更新。</text>
+      </view>
+    </view>
+  );
+}

package/dist/templates/com.doubao/app/src/widgets/example/index.tsx.template

@@ -0,0 +1,29 @@
+import { useViewData } from '@doubao-dev/framework';
+import { navigateTo } from '@doubao-dev/framework/api';
+import { ContentCard } from '@doubao-dev/template';
+
+type ProductSearch = {
+  products: { sku_id: string; name: string; spec: string; price: number }[];
+};
+
+export default function ExampleCard() {
+  const data = useViewData<ProductSearch>();
+  return (
+    <ContentCard
+      items={(data?.products ?? []).map((product) => ({
+        key: product.sku_id,
+        title: product.name,
+        subtitle: product.spec,
+        description: `¥${product.price}`
+      }))}
+      footer={{
+        primaryActionButton: {
+          text: '打开示例页面',
+          onClick: () => {
+            void navigateTo({ url: '/pages/home/index' }).catch((error) => console.error(error));
+          }
+        }
+      }}
+    />
+  );
+}

package/dist/templates/com.doubao/app/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "noImplicitThis": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@doubao-dev/framework",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+    "types": ["@doubao-dev/framework/types"]
+  },
+  "include": ["src"]
+}

package/dist/templates/mcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "shopping": {
+      "type": "streamable-http",
+      "url": "https://s0piqd9123oupmbgufs9i.apigateway-cn-beijing.volceapi.com/mcp"
+    }
+  }
+}

package/dist/templates/plugin.json.template

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "__PLUGIN_NAME__",
+  "description": "根据关键词搜索示例商品",
+  "extensions": {
+    "com.doubao": {
+      "displayName": {
+        "zh": "__PLUGIN_NAME__",
+        "en": "__PLUGIN_NAME__"
+      },
+      "displayDescription": {
+        "zh": "根据关键词搜索示例商品",
+        "en": "Search example products by keyword."
+      },
+      "mcpServers": {
+        "shopping": {
+          "displayName": {
+            "zh": "商品搜索",
+            "en": "Product search"
+          },
+          "displayDescription": {
+            "zh": "按关键词搜索示例商品。",
+            "en": "Search example products by keyword."
+          }
+        }
+      }
+    }
+  }
+}

package/dist/templates/skills/example/SKILL.md.template

@@ -0,0 +1,14 @@
+---
+name: __PLUGIN_NAME__
+description: 用户希望按关键词查找商品时，调用共享示例 MCP 的 search_products 工具。
+metadata:
+  display_name: 商品搜索
+  display_description: 根据关键词搜索示例商品，查看名称、规格和价格。
+---
+
+用户要求查找商品时调用 `search_products`，将商品关键词作为 `query` 传入。
+参数规则：`query` 必须是非空字符串；`limit` 必须是 1～10 的整数，默认传 3。
+用户要求超过 10 条时，每次最多查询 10 条，不得传入 100 等超出范围的值。
+例如搜索牛奶：`{"query":"牛奶","limit":3}`。
+根据工具实际返回结果回答；工具失败时说明原因，不编造商品和价格。
+结果中展示实际返回的名称、规格和价格；有 App 时由商品卡片呈现。

package/dist/upload.d.ts

@@ -0,0 +1,44 @@
+declare interface AppProject {
+    root: string;
+    plugin: {
+        name: string;
+        id?: string;
+    };
+    app?: {
+        root: string;
+    };
+    mcpServers: Record<string, unknown>[];
+    readSkills(): {
+        root: string;
+        content: string;
+    }[];
+}
+
+declare interface PreviewParams {
+    name?: string;
+    ability_id?: string;
+    version: string;
+}
+
+declare interface PreviewTools {
+    withProgress<T>(message: string, action: () => Promise<T>): Promise<T>;
+    queryBuildStatus(params: PreviewParams, signal: AbortSignal): Promise<{
+        artifact_status?: string;
+        artifact_build_error_info?: {
+            error_info?: string;
+            error_code?: string;
+        };
+    }>;
+    createPreview(params: PreviewParams, signal: AbortSignal): Promise<{
+        preview?: {
+            preview_url?: string;
+        };
+        display_name?: string;
+        test_version?: string;
+        expires_at_ms?: string | number;
+    }>;
+}
+
+export declare function showPreview(project: AppProject, version: string, tools: PreviewTools): Promise<void>;
+
+export { }

package/dist/upload.js

@@ -0,0 +1,38 @@
+import { setTimeout as promises_setTimeout } from "node:timers/promises";
+import { z } from "zod";
+async function showPreview(project, version, tools) {
+    const { id, name } = project.plugin;
+    const params = {
+        ...id ? {
+            ability_id: id
+        } : {
+            name
+        },
+        version
+    };
+    const signal = AbortSignal.timeout(600000);
+    z.string().regex(/^\d+\.\d+\.\d+$/, '版本号须为 x.y.z 格式').parse(version);
+    await tools.withProgress('等待云构建', async ()=>{
+        while(true){
+            const status = await tools.queryBuildStatus(params, signal);
+            if ('BUILD_SUCCEEDED' === status.artifact_status) return;
+            if ('BUILD_FAILED' === status.artifact_status) {
+                const error = status.artifact_build_error_info;
+                throw new Error(error?.error_info || error?.error_code || '云构建失败');
+            }
+            await promises_setTimeout(2000, void 0, {
+                signal
+            });
+        }
+    });
+    const result = await tools.createPreview(params, signal);
+    if (!result.preview?.preview_url) throw new Error('服务端未返回预览链接');
+    const { printPreview } = await import("./preview.js");
+    await printPreview({
+        url: result.preview.preview_url,
+        name: result.display_name || name,
+        version: result.test_version || version,
+        expiresAt: result.expires_at_ms
+    });
+}
+export { showPreview };