豆包应用插件 Demo
Demo 代码附件
doubao-supermart-demo.zip 273.09 KB
简介
提示
豆包随手购 是一款豆包应用插件 Demo。用户只需用自然语言说出购物需求,豆包就能帮你完成“理解需求 → 生成购物方案 → 挑选替换商品 → 优化优惠 → 模拟下单”,实现一句话逛完超市。
本教程以「豆包随手购」为例,介绍如何从零开始开发一个豆包应用插件,涵盖:
使用 dbx CLI 初始化项目、本地调试与真机预览
全页形式的页面(Page)开发
与 AI 对话联动的卡片组件(Widget)开发
MCP Server 的开发
Skill 的编写
项目结构
doubao-supermart-demo/
├── manifest.yaml # 应用声明:app_key、MCP 地址、工具绑定
├── package.json # 前端依赖与构建脚本
├── tsconfig.json # TypeScript 配置
├── src/ # 前端源码
│ ├── app.ts # 全局生命周期
│ ├── app.config.ts # 全局配置:页面、卡片注册
│ ├── config/ # 非敏感运行时配置(appId、API 地址)
│ ├── pages/ # 页面目录
│ ├── widgets/ # 卡片目录
│ ├── auth/ # 登录链路
│ ├── pay/ # 支付链路
│ └── shared/ # 公共逻辑
├── skill/
│ └── SKILL.md # AI Skill 定义
└── server/ # 服务端工程
├── mcp-server/ # MCP Server
└── open-capability/ # 登录、支付等开放能力
创建项目
1. 安装 CLI
npm install -g @doubao-dev/cli
2. 登录认证
登录后可通过以下命令确认状态:
3. 初始化项目
参考 快速开始 章节 。
初始化完成后,新项目根目录包含 manifest.yaml、skill/SKILL.md 和前端工程,并安装内置开发 Skill。
开发前端 UI
全局配置
app.ts — 全局生命周期
import { defineApp } from '@doubao-dev/framework' ;
export default defineApp ({
onLaunch () {
console .log ( 'App launched' );
} ,
onPageOpened ({ viewId } : { viewId : string }) {
console .log ( 'On page opened:' , viewId);
} ,
onForeground () {
console .log ( 'On foreground' );
} ,
onBackground () {
console .log ( 'On background' );
} ,
onDestroy () {
console .log ( 'On destroyed' );
} ,
});
整个应用插件只有一个 App 实例,所有页面共享
生命周期与页面绑定:第一个页面创建时启动,最后一个页面销毁时结束
app.config.ts — 页面与卡片注册
import { defineAppConfig } from '@doubao-dev/framework/config' ;
import { runtimeConfig } from './config/runtime' ;
export default defineAppConfig ({
appId : runtimeConfig .appId ,
name : '豆包随手购' ,
pages : [
'pages/home/index' , // 第一项为首页
{ entry : 'pages/plan-detail/index' , id : 'plan-detail' , title : '购物方案详情' } ,
{ entry : 'pages/product-selector/index' , id : 'product-selector' , title : '商品选择' } ,
{ entry : 'pages/cart/index' , id : 'cart' , title : '购物车' } ,
{ entry : 'pages/order-detail/index' , id : 'order-detail' , title : '订单详情' } ,
] ,
widgets : [
{ entry : 'widgets/plan-card/index' , id : 'PlanCard' , name : '购物方案卡' , description : '展示场景购物方案分组与金额' } ,
{ entry : 'widgets/product-select-card/index' , id : 'ProductSelectCard' , name : '商品选择卡' , description : '展示搜索/替换候选商品' } ,
{ entry : 'widgets/promo-card/index' , id : 'PromoCard' , name : '优惠方案卡' , description : '展示优惠凑单前后对比' } ,
{ entry : 'widgets/order-card/index' , id : 'OrderCard' , name : '订单结果卡' , description : '展示模拟订单创建结果' } ,
] ,
});
pages 数组中第一项为默认首页,widgets 中注册的卡片 id 需与 manifest.yaml 的 tool_card_binding 对应。
开发页面(Page)
页面定义
默认导出 Page 函数组件,并在 src/app.config.ts 注册页面入口:
// src/pages/home/index.tsx
import { navigateTo } from '@doubao-dev/framework/api' ;
import './index.scss' ;
export default function HomePage () {
return (
< view className = "home-page" >
< text className = "home-page__title" > 豆包随手购 </ text >
< view className = "home-page__list" >
< view
className = "home-page__card"
bindtap = {() => navigateTo ({ url: 'pages/plan-detail/index' })}
>
< text className = "home-page__card-label" > 购物方案详情 </ text >
</ view >
</ view >
</ view >
);
}
页面跳转
import { navigateTo } from '@doubao-dev/framework/api' ;
navigateTo ({ url : 'pages/plan-detail/index' });
事件处理
使用 bindtap 绑定点击事件:
< view bindtap = {() => console.log( '点击' )}>点击我</view>
样式编写
支持 SCSS,推荐 BEM 命名规范:
// src/pages/home/index.scss
.home-page {
display : flex ;
flex-direction : column ;
padding : 20 px ;
& __title {
font-size : 24 px ;
font-weight : bold ;
}
}
Widget 是 AI 对话中渲染的卡片,由工具调用结果驱动。新代码默认导出 Widget 函数组件,并在 src/app.config.ts 注册卡片入口。
读取工具返回数据
import { useViewData } from '@doubao-dev/framework' ;
export default function ResultCard () {
const data = useViewData < MyEntityType >() ?? ({} as MyEntityType );
// data 即 MCP 工具返回的 entity 数据
return < view >{data.title} </ view > ;
}
使用模板组件(推荐)
框架提供 @doubao-dev/template 开箱即用的卡片模板,覆盖大多数场景:
import { ContentCard , type ContentCardItem } from '@doubao-dev/template' ;
const items : ContentCardItem [] = products .map ((p) => ({
key : p .sku_id ,
title : p .name ,
subtitle : ` ${ fmtPrice ( p .price) } · ${ p .spec } ` ,
thumbnail : < text style ={{ fontSize : '24px' }}>{p.emoji} </ text > ,
action : { type : 'button' , text : '添加' , onClick : () => pick (p) } ,
}));
return (
< ContentCard
items = {items}
footer = {{ primaryActionButton : { text : '查看更多' , onClick : more } }}
/>
);
ContentCard 支持的主要 Props:
自定义布局(children)
当标准 items 无法满足布局需求时,可通过 children 完全自定义内容区,同时保留 footer 按钮:
< ContentCard
footer = {{
secondaryActionButton : { text : '调整商品' , onClick : openDetail } ,
primaryActionButton : { text : '采用方案' , onClick : adopt } ,
}}
>
{ /* 方案概览 */ }
< view style = {{ display : 'flex' , flexDirection : 'row' , padding : '8px 16px' }} >
< text style = {{ fontSize : '20px' }} > 📋 </ text >
< view style = {{ flex : 1 , marginLeft : '10px' }} >
< text style = {{ fontSize : '14px' , fontWeight : '600' }} > {data.title} </ text >
< text style = {{ fontSize : '12px' , color : 'rgba(0,0,0,0.45)' }} > {subtitle} </ text >
</ view >
</ view >
{ /* 分组列表 */ }
{ groups .map ((g) => (
< view key = {g.name} style = {{ display : 'flex' , flexDirection : 'row' , padding : '8px 16px' }} >
< text >{g.name} </ text >
< text >{ fmtPrice (g.subtotal)} </ text >
</ view >
))}
</ ContentCard >
存储与上下文同步
全局状态通过 shared/store.ts 统一管理,购物车变更后需同步给模型上下文:
import { getStorageSync , setStorageSync , updateModelContext } from '@doubao-dev/framework/api' ;
// 保存购物车并同步给模型
export function saveCartSnapshot (s : CartSnapshot ) : void {
setStorageSync ({ key : 'cart_snapshot' , data : s });
updateModelContext ({ content : JSON .stringify ({ cart_snapshot : s }) }) .catch (() => {});
}
Page vs Widget 对比
开发 MCP Server
豆包应用插件通过 MCP(Model Context Protocol)实现 AI 工具调用。对话中模型根据 Skill 规则调用工具,工具返回结构化数据,豆包端依据 manifest.yaml 的绑定关系自动渲染对应 Widget。
工具目录结构
Demo 工程,仅供参考!
server/mcp-server/src/
├── server.ts # 入口,注册工具、监听端口
├── tools/
│ ├── index.ts # 汇总导出所有工具
│ ├── createShoppingPlan.ts # 生成购物方案
│ ├── searchProducts.ts # 搜索商品
│ ├── optimizeCart.ts # 优惠凑单
│ └── createOrder.ts # 创建模拟订单
├── core/
│ ├── logic.ts # 纯业务逻辑(购物车计算、优惠计算等)
│ └── schemas.ts # 入参校验 Schema
└── types/
└── index.ts # ToolDef / ToolResult 类型定义
出卡协议
豆包应用插件的「出卡」是通过工具返回结构化实体(Entity)触发的,全链路分为三层:
1. manifest.yaml 声明
每个工具在 manifest.yaml 中声明输出类型和卡片绑定:
tools :
create_shopping_plan :
description : 根据场景、人数、预算和偏好生成商超购物方案
output :
kind : entities
entity_types : [ shopping_plan_entity ] # 声明本工具会返回的实体类型
entities :
shopping_plan_entity :
schema :
plan_id : { type : string , is_entity_id : true } # is_entity_id:实体唯一 ID
title : { type : string }
subtotal : { type : float }
# ...其他字段
tool_card_binding :
create_shopping_plan : PlanCard # 工具名 → 渲染哪个 Widget
2. 工具返回结构
每个工具的 handler 返回 ToolResult,核心是 structuredContent.entities 数组:
export interface ToolResult {
content : { type : 'text' ; text : string }[]; // 给模型 / 用户看的自然语言
structuredContent : Record < string , unknown >; // 成功:{ entities: [...] };失败:{ code, message }
isError ?: boolean ; // true = 业务失败,不出卡
}
成功出卡时返回:
return {
content : [{ type : 'text' , text : '已生成4人清淡火锅方案:共12件,预计 ¥176.5' }] ,
structuredContent : {
entities : [{
entity_type : 'shopping_plan_entity' , // 【必填】与 manifest 的 entity key 对应
plan_id : 'plan_hotpot_4p_low' , // 【必填】is_entity_id 字段
title : '4人清淡火锅购物方案' ,
subtotal : 176.5 ,
cart_snapshot : JSON .stringify (snapshot) ,
// ...其他字段与 manifest schema 对齐
}]
} ,
isError : false ,
};
业务失败时返回(不出卡):
return {
content : [{ type : 'text' , text : '暂不支持该场景' }] ,
structuredContent : { code : 40404 , message : '暂不支持该场景' } ,
isError : true ,
};
3. 出卡流程
模型调用工具
↓
handler 返回 structuredContent.entities
↓
豆包端查 manifest:工具名 + entity_type → tool_card_binding
↓
找到绑定的 Widget id(如 PlanCard)
↓
渲染 Widget,entity 数据通过 getViewData() 传入
Skill 开发
Skill 是豆包 AI 的行为规范文件,定义模型在何时调用哪个工具、如何回复、以及各种边界情况的处理规则。
文件位置
skill/
└── SKILL.md # Skill 定义文件,dbx dev 启动时自动加载
dbx dev 会读取项目 skill/ 目录及子目录中的所有 SKILL.md。如果 Skill 放在其他位置,用 --skill <path> 指定它所在的目录;相对路径从 --project-path 指定的项目目录算起。
文件结构
SKILL.md 由 YAML Front Matter 和 Markdown 正文两部分组成:
---
name : supermart-assistant
description : 都把随手购。用户表达"买菜/购物/下单"等意图时触发……
---
# 正文(模型行为规范)
Front Matter 字段说明:
description 是触发入口,直接影响模型是否启用这套规则,需简洁地描述核心使用场景和关键词(如「买菜/买齐/购物/凑单/下单」)。
正文内容规范
正文是给模型看的自然语言指令,建议包含以下几个部分:
1. 通用边界
明确模型能做什么、不能做什么,防止模型越权操作:
## 通用边界
- 价格、金额、件数必须来自工具返回,禁止自行估算
- 场景购物必须有:场景、人数、预算三要素,缺一先追问
- create_mock_order 只有用户明确确认购买后才能调用
- 用户要求超出能力(真实支付、退款)时,说明仅支持模拟环境
2. 意图识别与工具选择
描述用户各类表达对应调用哪个工具,以及工具之间的编排顺序:
## 意图识别与工具选择
- 描述整体场景("四个人吃火锅""准备一周早餐")→ create_shopping_plan
- 搜索/加购/替换商品("搜羊肉卷""把肥牛换成羊肉")→ search_products
- 问优惠/省钱/凑单("有没有更省的买法")→ optimize_cart
- 明确确认购买 → create_mock_order
# 推荐编排顺序:
create_shopping_plan → search_products(可多次)→ optimize_cart → create_mock_order
3. 回复与卡片规范
约束模型文本回复的内容,避免与卡片信息重复或矛盾:
## 回复与卡片
- 工具成功时文本只做一句话总结,明细由卡片承载,不在文本中罗列清单
- 只有工具返回中存在 <card reference_id="..."> 时才输出卡片引用
- optimize_cart 后只能说"预计可省 X 元",不能说"已为你省下"
4. 工具失败处理
覆盖各种异常情况,避免模型重试或凭空编造:
## 工具失败处理
- isError 返回时如实转述 message,不自动重试,不输出卡片
- search_products 返回 status=empty:告知未找到,转述 suggestion
- optimize_cart 返回 status=keep:说明当前已是较优方案
5. 工具调用格式
为每个工具提供调用示例,帮助模型准确构造入参:
## 工具:create_shopping_plan
```json
{
"name" : "create_shopping_plan" ,
"parameters" : {
"scene" : "hotpot" ,
"people_count" : 4 ,
"budget" : 200 ,
"preferences" : { "spicy_level" : "low" }
}
}
```
完整示例(豆包随手购)
---
name : apps-plugin-shopping-suishougou
description : 豆包随手购商超购物服务。当用户表达商超购物意图时使用:按场景采购(火锅、早餐、家庭聚餐、下午茶、露营、囤货)、搜索/添加/替换食材与日用品、凑单省钱或控制预算、确认下单送货,也包括承接上文的追加或替换表达("把它换成…""再加两瓶""就这样下单")。仅提供模拟下单演示,不涉及真实支付、真实库存、物流查询与售后。
---
# 豆包随手购
帮助用户完成商超购物:生成场景购物方案 → 搜索/替换商品 → 优惠凑单 → 创建模拟订单。
## 通用规则
- 价格、金额、件数、商品名、订单号只能来自工具返回或用户原话;工具没返回的数字一律不说,禁止自行计算或估算总价。
- **购物车快照透传** :最近一次工具返回中的 `cart_snapshot` (或 `next_cart_snapshot` )即当前购物车。任何带 `cart_snapshot` 入参的工具调用,都要把上一次工具返回的快照值原样透传(可能是 JSON 字符串,原样携带即可),不得解析、改写字段或凭记忆重构。用户在页面里改过购物车时,以对话上下文中最新的快照为准。
- 只有工具成功、且模型可见结果中存在 `<card reference_id="...">` 时才输出卡片,引用必须使用该 reference_id,不得编造,也不得把 plan_id/sku_id/order_id 当作卡片 id。
## 场景路由
使用该 Skill 当用户意图涉及商超购物(买食材、买日用品、办一顿饭、凑单省钱、下单送货)。按下表路由:
| 用户意图 | 处理方式 |
| --- | --- |
| 描述整体场景需求("四个人吃火锅""准备一周早餐""公司下午茶""露营买些什么") | 调 create_shopping_plan |
| 搜索/加购具体商品("搜羊肉卷""再加两瓶可乐""有便宜点的牛奶吗") | 调 search_products |
| 替换购物车中的商品("把肥牛换成羊肉") | 调 search_products,带 replace_sku_id(从当前快照找被替换商品的 sku_id) |
| 问优惠、省钱、凑单、控预算("有没有更省的买法""控制在两百以内") | 调 optimize_cart,携带最新快照 |
| 明确确认购买("就这样下单""帮我提交""按这个方案买") | 调 create_mock_order |
- 编排顺序:create_shopping_plan →(可选,可多次)search_products →(可选)optimize_cart → create_mock_order。不强制走全链路,用户只想搜牛奶时直接 search_products。
- 一句话含多个动作("把肥牛换成羊肉,再加两瓶可乐")时按顺序多次调 search_products:先替换(replace_sku_id + query 羊肉),再添加(query 无糖可乐)。
- 场景购物的关键字段是场景、人数、预算。三者缺一且上下文推断不出时,先追问缺失字段再调工具;口味(默认不辣 low)、品牌、配送时间非必填,可用默认值。
不要使用该 Skill 当:
- 用户要真实支付、退款、查物流、会员价等超出能力的诉求:说明这是演示环境仅支持模拟下单,不调用工具。
## 回复与卡片规则
- 四个工具成功时都会返回卡片。文本只做一句话总结(方案金额、找到几个商品、能省多少、订单创建成功),明细与操作交给卡片,不要在文本里重复罗列卡片已有的完整清单。
- 措辞要贴合业务状态:optimize_cart 后只能说"预计可省 X 元",不能说"已为你省下";create_mock_order 成功后才能说"订单已创建"。
- search_products 返回的 products 是可筛选列表:用户说"要第一个/便宜的那个"时,从原始 products 中筛选,不得新增或改写商品。
| widget id | 触发工具 | 展示时机 |
| --- | --- | --- |
| PlanCard | create_shopping_plan | 方案生成成功后下发 |
| ProductSelectCard | search_products | 搜索/替换有结果后下发 |
| PromoCard | optimize_cart | 优惠方案计算成功后下发 |
| OrderCard | create_mock_order | 模拟订单创建成功后下发 |
---
## 工具:create_shopping_plan
### 工具说明与使用场景
根据场景、人数、预算、偏好生成购物方案,是场景化购物的第一步。用户只搜单品时不要调用。
### 注意事项
- scene 可传中文场景词(火锅/早餐/家庭聚餐/下午茶/露营/囤货)或 id(hotpot/breakfast/family_dinner/afternoon_tea/camping/stock_up)。
- 缺人数或预算时先追问;"不要太辣"→ spicy_level=low,"微辣/中辣"→ medium,"重辣"→ high。
### 工具调用格式
```json
{ "name" : "create_shopping_plan" , "parameters" : { "type" : "object" , "properties" : {
"scene" : { "type" : "string" , "description" : "场景 id 或中文场景词" } ,
"people_count" : { "type" : "integer" , "minimum" : 1 , "maximum" : 20 } ,
"budget" : { "type" : "number" , "description" : "预算(元),来自用户原话" } ,
"preferences" : { "type" : "object" , "properties" : {
"spicy_level" : { "type" : "string" , "enum" : [ "low" , "medium" , "high" ] } ,
"dietary_restrictions" : { "type" : "array" , "items" : { "type" : "string" } } ,
"preferred_categories" : { "type" : "array" , "items" : { "type" : "string" } } } }
} , "required" : [ "scene" , "people_count" , "budget" ] } }
```
## 工具:search_products
### 工具说明与使用场景
搜索商品,用于加购或替换。替换购物方案中的商品时也用它(带 replace_sku_id),不要重新生成方案。该工具只返回候选,不修改购物车;用户在卡片/页面中选择后快照才会更新。
### 注意事项
- query 来自用户原话中的商品词;价格约束("50 元以内")映射到 price_range.max。
- replace_sku_id 必须取自当前快照 items 中被替换商品的 sku_id,不得猜测。
### 工具调用格式
```json
{ "name" : "search_products" , "parameters" : { "type" : "object" , "properties" : {
"query" : { "type" : "string" } ,
"category" : { "type" : "string" , "description" : "meat/vegetable/dairy_drink/grain_condiment/snack/daily" } ,
"price_range" : { "type" : "object" , "properties" : { "min" : { "type" : "number" } , "max" : { "type" : "number" } } } ,
"sort" : { "type" : "string" , "enum" : [ "recommended" , "price_asc" , "price_desc" ] } ,
"replace_sku_id" : { "type" : "string" , "description" : "被替换商品的 sku_id,仅替换场景传" } ,
"limit" : { "type" : "integer" , "minimum" : 1 , "maximum" : 10 }
} , "required" : [ "query" ] } }
```
## 工具:optimize_cart
### 工具说明与使用场景
基于当前购物车计算更省的买法(满减凑单)。用户问优惠/省钱/预算时调用;购物车为空时先引导用户生成方案或加购。
### 注意事项
- 用户明确说"别再加东西"时传 allow_add_items=false。
- 返回的 next_cart_snapshot 仅在用户"应用方案"后才成为当前购物车;用户未表态时当前快照不变。
### 工具调用格式
```json
{ "name" : "optimize_cart" , "parameters" : { "type" : "object" , "properties" : {
"cart_snapshot" : { "type" : "object" , "description" : "上一次工具返回的快照值,原样透传(JSON 字符串或对象均可)" } ,
"budget" : { "type" : "number" } ,
"optimization_goal" : { "type" : "string" , "enum" : [ "lowest_payable" , "within_budget" ] } ,
"allow_add_items" : { "type" : "boolean" } ,
"allow_replace_items" : { "type" : "boolean" }
} , "required" : [ "cart_snapshot" ] } }
```
## 工具:create_mock_order
### 工具说明与使用场景
根据最终购物车创建模拟订单,是链路终点。仅在用户明确确认购买后调用,是唯一会产生"订单"业务状态的工具。用户只是查看优惠、浏览方案时绝不能下单。
### 注意事项
- 调用前自检:用户已明确表达购买意愿;存在有效快照;配送时间明确或用户接受默认(明天 18:00-19:00)。三者齐备才调用,并传 user_confirmed=true。
- "明晚七点前送到"→ delivery_time 传 "明天 19:00 前"(转述用户时间要求即可,无需精确格式)。
- 地址默认 mock_address_home(家),用户说送公司时传 mock_address_office。
### 工具调用格式
```json
{ "name" : "create_mock_order" , "parameters" : { "type" : "object" , "properties" : {
"cart_snapshot" : { "type" : "object" , "description" : "上一次工具返回的快照值,原样透传(JSON 字符串或对象均可)" } ,
"delivery" : { "type" : "object" , "properties" : {
"address_id" : { "type" : "string" , "enum" : [ "mock_address_home" , "mock_address_office" ] } ,
"delivery_time" : { "type" : "string" } } } ,
"user_confirmed" : { "type" : "boolean" , "description" : "必须为 true,且仅在用户明确确认后" }
} , "required" : [ "cart_snapshot" , "user_confirmed" ] } }
```
## 通用注意事项(失败降级)
- 工具失败、无返回、结果为空、status/isError 异常时,如实说明未成功,不出卡片,不编造成功结论,不自动重试。
- isError(如 40404 不支持的场景、40001 未确认下单、40002 空购物车):如实转述 message,并按提示补救(换场景词、先向用户确认、先加商品)。
- search_products 返回 status=empty:告知没找到,转述 suggestion 建议换关键词。
- create_shopping_plan 返回 budget_warning 非空:如实转述超支金额与降配建议,询问用户是否调整预算或接受方案。
- optimize_cart 返回 status=keep:说明当前已是较优方案(转述 reason),不虚构更省的买法。
Skill 与 MCP 的关系
用户输入
↓
豆包模型读取 Skill 规则(SKILL.md)
↓
按意图识别规则选择工具
↓
调用 MCP Server 工具(manifest.yaml 中声明的 end_point)
↓
工具返回 entities → 豆包端按 tool_card_binding 出卡
↓
模型根据 Skill 回复规范生成文本回复
Skill 控制「模型怎么做决策」,MCP Server 控制「工具怎么执行」,两者通过 manifest.yaml 中的工具声明连接。修改 Skill 无需重启服务,dbx dev 运行时热生效。
登录接入
🔵 本节的登录能力与前面各部分一样,都是通过 dbx CLI 驱动 coding agent、用自然语言增量生成的。你只需描述「给应用插件接入豆包手机号一键登录 + 自定义登录页」,agent 会按下面的分工把后端鉴权服务、登录页、manifest.yaml 声明一并落地。本节把 agent 产出的成果整理成可复用的接入说明。
本 Demo 在 Coding Agent 中使用的指令:给这个豆包应用插件接入登录:支持豆包手机号一键登录 + 自定义登录页(手机号 + 验证码)。
登录让豆包应用插件能识别用户身份、给 login_type 工具带上登录态。豆包提供两种登录方式,本 Demo 都做了接入:
宿主手机号一键登录 :复用豆包 App 已登录的手机号,用户一键授权即可。
自定义登录页 :无手机号绑定时,走自定义页面(手机号 + 验证码)完成登录。
一、先理解全局
登录接入涉及「一份声明 + 四端协作」,先看清谁调谁、按什么顺序:
整体时序 (以一键登录为例,自定义登录页仅第 ①②③ 步不同):
① 用户点登录 → 前端 login() 取 login_code;一键登录额外从 onLogin(res).code 取 phone_code
↓
② 前端 POST /auth/doubao/login { app_id, login_code, phone_code }
↓
③ 业务 Server:login_code --get_openid--> open_id
phone_code --get_user_phonenumber--> 加密手机号 --私钥解密--> 手机号
账号绑定 / 注册 → 签发 developer_login_code(持久化,5min 一次性)
↓
④ 前端 postLoginResult({ result: true, code: developer_login_code })
↓
⑤ 平台回调 FetchTokenURL(/auth/fetch_token) { app_id, code }
业务 Server 消费 developer_login_code → 签发 MCP access/refresh_token
↓
⑥ 之后调用 login_type 工具,平台注入 X-DB-OPENID / X-DB-ACCESS-TOKEN
mcp-server 调 /internal/introspect 校验 token → 放行工具
两种登录方式对比 —— 共用同一套「换 open_id → 账号绑定 → 签发 developer_login_code → 回传平台 → 换 MCP token」链路,差异只在前端入口与业务凭证:
二、凭证与密钥速查
链路中同时存在一次性凭证 (每次登录临时生成)和长期身份与密钥 (应用级 / 用户级,后台申请后长期使用),二者不能混用。实现时可回查本节。
四类一次性凭证 :
长期身份与密钥 (在开发者后台申请并配置):
证书在开发者后台「开发设置 → 证书管理 」中管理,分「应用证书」和「平台证书」两类:应用证书 是你自己的证书(对应私钥你保管),用于加密手机号下发(登录用)和支付请求签名;平台证书 是平台的证书,用于你验签平台发来的回调。本登录 Demo 只用到应用证书对应的私钥来解密手机号。
三、分步实现
下面按调用时序 分 5 步:先配置声明(3.1),再前端触发(3.2),然后服务端交换与回调(3.3 / 3.4),最后 MCP 鉴权(3.5)。每步标注【配置】/【前端】/【服务端】并给出关键代码。授权手机号一键登录与自定义登录共用同一套服务端交换与签发链路,差异只在前端入口与业务凭证。
3.1【配置】准备凭证与 manifest 声明登录
要做什么 :在 manifest.yaml 声明平台 OAuth 的三个回调地址(user_auth.*)并给需要登录的 Tool 标注 login_type;在登录服务 config.ts 约定各类凭证来源——敏感值(AppSecret、私钥)只从环境变量 / 本地安全路径读取,绝不硬编码。
准备应用证书(一键登录换手机号必需) :手机号一键登录会拿到平台加密下发的手机号密文,需用应用证书对应的私钥 解密。做法是本地生成一对 ECC P-256 密钥(dev.key 私钥 + dev.csr 证书请求),把 dev.csr 提交到开发者后台「开发设置 → 证书管理 → 应用证书 → 生成证书」换取平台签发的应用证书,私钥 dev.key 只留服务端(路径由 DEV_KEY_PATH 指定):
openssl ecparam -genkey -name prime256v1 -noout -out dev.key # 私钥,仅服务端保管
openssl req -new -key dev.key -out dev.csr -subj "/CN=xxx/O=xxx" # 证书请求,提交平台
mcp_server :
end_point : https://.../mcp
# 三方登录 OAuth Endpoint(本地联调用 localhost;上线前替换为公网 HTTPS 地址)
# 由 server/open-capability/login 业务鉴权服务实现,默认端口 3300。
user_auth :
fetch_token_url : http://127.0.0.1:3300/auth/fetch_token # 用 developer_login_code 换 MCP token
refresh_token_url : http://127.0.0.1:3300/auth/refresh_token # 轮换 MCP token
delete_userinfo_url : http://127.0.0.1:3300/auth/delete_userinfo # 宿主授权字段删除通知
tools :
create_shopping_plan :
login_type : normal # 声明该工具需要登录态;平台会注入 X-DB-* Header
output : { kind : entities , entity_types : [ shopping_plan_entity ] }
config.ts —— 敏感值只从环境变量读取,绝不硬编码:
export const config = {
port : Number ( process . env . LOGIN_SERVER_PORT ?? 3300 ) ,
appId : process . env . DOUBAO_APP_ID ?? 'db_app_3mclF4c' , // 与 manifest.app_key 一致(非敏感)
appSecret : process . env . DOUBAO_APP_SECRET ?? '' , // 敏感,仅环境变量
openApiBase : process . env . DOUBAO_OPENAPI_BASE ?? 'https://hello.doubao-dev.com' ,
dbFile : process . env . LOGIN_DB_FILE ?? path .join ( SERVER_ROOT , 'data' , 'login.db' ) ,
devKeyPath : process . env . DEV_KEY_PATH ?? path .join ( SERVER_ROOT , 'secrets' , 'dev.key' ) , // 手机号解密私钥
developerLoginCodeTtl : 300 , accessTokenTtl : 7200 , refreshTokenTtl : 2592000 , pageSessionTtl : 7200 ,
} as const ;
各配置项的含义与敏感性:
关于验证码 :自定义登录页当前用固定验证码 MOCK_VERIFY_CODE = '123456',这是本 Demo 有意保留的占位实现 ,只模拟「短信/邮箱验证码」这一步业务凭证校验,方便本地联调和真机演示。登录链路的其余部分(换 open_id、账号绑定、developer_login_code 签发与持久化、MCP token 生命周期)都是正式实现。生产接入时把 /auth/custom-login 里对 MOCK_VERIFY_CODE 的比对替换为真实的短信/邮箱验证码下发与校验服务即可。
3.2【前端】接入登录入口与结果回传
要做什么 :实现两个登录入口——授权手机号一键登录(login.ts)与自定义登录页(login-page/index.tsx),并用公共 helper(shared.ts)统一处理凭证边界与结果回传守卫。位置:src/auth/。
授权手机号一键登录 (login.ts)—— 用 defineLoginApi 承接宿主一键登录回调,onLogin(res).code 即 phone_code:
import { defineLoginApi , type LoginResult } from '@doubao-dev/framework' ;
export default defineLoginApi ({
onLogin : async (res : LoginResult ) => {
resetLoginResultGuard ();
try {
const phoneCode = res ?.code; // 手机号授权码
const loginCode = await fetchLoginCode (); // 另行 login() 取 login_code
const auth = await exchangeDoubaoLogin ({ loginCode , phoneCode });
await postLoginSuccessOrFail ( auth .code); // 先回传成功
await safeStorePageSession (auth); // 再写本地 session
} catch (error) {
await postLoginFailureOnce (); // 任何失败都回传一次失败态
}
} ,
onRefuseLogin : async () => { await postLoginFailureOnce (); } ,
});
自定义登录页 (login-page/index.tsx)—— 用 defineLoginPage 定义页面,本地校验手机号 + 验证码后走同一交换链路:
export default defineLoginPage ({
onDestroy () { void reportLoginFailureIfNeeded (); } , // 页面销毁兜底回传失败
render () { return < CustomLoginPage />; } ,
});
// 提交逻辑(节选)
const handleSubmit = async () => {
// ...手机号 / 验证码本地校验...
const loginCode = await fetchLoginCode (); // 1) 校验通过取 login_code
const auth = await exchangeCustomLogin ({ loginCode , phone , verifyCode }); // 2) 业务交换
await postLoginSuccessOrFail ( auth .code); // 3) 先回传成功
await safeStorePageSession (auth); // 4) 保存 session
await exitApp (); // 关闭登录页
};
postLoginResult (shared.ts)—— 登录链路最容易出错的是「凭证混用」和「结果重复回传」,公共 helper 统一处理:
// 登录结果只允许回传一次(成功优先、失败幂等)
let loginResultPosted = false ;
export async function postLoginSuccessOrFail (developerLoginCode : string ) {
if (loginResultPosted) return ;
try {
await postLoginResult ({ result : true , code : developerLoginCode }); // 只回传 developer_login_code
loginResultPosted = true ;
} catch (error) {
await postLoginFailureOnce (); // 失败补回一次失败态
throw error;
}
}
// 只保存 Page session token,绝不保存 developer_login_code / MCP token
export async function safeStorePageSession (auth : AuthExchangeResponse ) { /* setStorage(...) */ }
前端调用业务接口的地址集中在 src/config/runtime.ts 的 authApiBaseUrl,联调指向 http://127.0.0.1:3300,上线换成公网 HTTPS 地址。
3.3【服务端】实现前端登录交换接口
要做什么 :接收前端提交的登录码,换取 open_id(一键登录还会解密手机号),完成账号绑定 / 注册,签发一次性 developer_login_code 与 Page session 返回前端。授权手机号一键登录与自定义登录共用同一 open_id 链路,只有业务凭证不同。位置:open-capability/login/src/server.ts。
授权手机号一键登录 POST /auth/doubao/login:
app .post ( '/auth/doubao/login' , async (req , res) => {
const { app_id , login_code , phone_code } = req .body ?? {};
if (app_id !== config .appId || ! login_code) {
return res .status ( 400 ) .json ({ code : 40001 , msg : 'invalid app_id or login_code' });
}
// 1) login_code → open_id
const openId = await getOpenId (login_code);
// 2) 有 phone_code 时换取并解密手机号
let phone = null ;
if (phone_code) phone = decryptPhoneNumber ( await getEncryptedPhoneNumber (phone_code));
// 3) 账号绑定 / 注册
const account = upsertAccount ({ appId : app_id , openId , phone });
// 4) 签发短期一次性 developer_login_code(已持久化)
const developerLoginCode = issueDeveloperLoginCode ({ appId : app_id , openId , ... });
// 5) 生成 Page session(前端全页调用业务接口用)
const session = createPageSession ({ appId : app_id , openId , ... });
res .json ({ code : developerLoginCode , session_token : session .token , session_expires_in : session .expiresIn });
});
自定义登录 POST /auth/custom-login —— 差异只在业务凭证校验(手机号格式 + 验证码),之后走同一 open_id 换取与签发链路:
app .post ( '/auth/custom-login' , async (req , res) => {
const { app_id , login_code , phone , verify_code } = req .body ?? {};
if (app_id !== config .appId || ! login_code) { /* 40001 */ }
if ( typeof phone !== 'string' || ! / ^ 1\d {10}$ / .test (phone)) { // 手机号格式校验
return res .status ( 200 ) .json ({ code : 40010 , msg : 'invalid phone' });
}
// 验证码校验:demo 有意保留的占位(固定 MOCK_VERIFY_CODE,详见 config.ts);
// 生产替换为真实短信/邮箱验证码服务,本行之外的登录链路均为正式实现。
if (verify_code !== MOCK_VERIFY_CODE ) {
return res .status ( 200 ) .json ({ code : 40011 , msg : 'invalid verify_code' });
}
const openId = await getOpenId (login_code); // 与一键登录同一 open_id 链路
const account = upsertAccount ({ appId : app_id , openId , phone }); // 手机号来自用户填写(非 phone_code 解密)
// ...issueDeveloperLoginCode + createPageSession,返回同上
});
底层换取 open_id / 手机号的平台 OpenAPI 封装在 openapi.ts,涉及三个接口:
// login_code → open_id(一键登录与自定义登录都走这里)
export async function getOpenId (loginCode : string ) : Promise < string > {
const resp = await postJson ( '/api/login/v1/developer/get_openid' , {
app_id : config .appId , app_secret : config .appSecret ,
grant_type : 'authorization_code' , login_code : loginCode ,
});
if ( resp .code !== 0 || ! resp . data ?.open_id) throw new Error ( `get_openid failed: code= ${ resp .code } ` );
return resp . data .open_id;
}
// phone_code → 加密手机号(仅一键登录);client_token 内存缓存复用
export async function getEncryptedPhoneNumber (phoneCode : string ) : Promise < string > {
const clientToken = await getClientToken ();
const resp = await postJson ( '/api/login/v1/developer/get_user_phonenumber' ,
{ phone_code : phoneCode } , { 'x-DB-AccessToken' : clientToken });
if ( resp .code !== 0 || ! resp . data ?.encrypt_phone_number) throw new Error ( 'get_user_phonenumber failed' );
return resp . data .encrypt_phone_number;
}
手机号解密 (phone-crypto.ts)—— 平台用应用证书里的公钥 (即 dev.csr 提交的那把)加密手机号,服务端用配对的私钥 dev.key 解密;算法为 ECDH P-256 + AES-256-GCM(ECIES),私钥只从本地安全路径读取,日志绝不打印手机号:
// cipher_data = Base64URL(TLV{version, ephemeral_pub, data_key_cipher, data_cipher})
export function decryptPhoneNumber (cipherDataBase64Url : string ) : string {
const devPrivateKeyPem = loadDevPrivateKey ();
const tlv = parseTlv ( base64UrlDecode (cipherDataBase64Url));
const sharedSecret = ecdh (devPrivateKeyPem , tlv .get ( TLV_EPHEMERAL_PUB_KEY )); // 私钥 × 临时公钥
const kek = crypto .createHash ( 'sha256' ) .update (sharedSecret) .digest ();
const dataKey = aesGcmDecrypt (kek , tlv .get ( TLV_DATA_KEY_CIPHER ));
const dataPlain = aesGcmDecrypt (dataKey , tlv .get ( TLV_DATA_CIPHER ));
return normalizePhone (dataPlain); // 日志只输出 phone_len,绝不打印手机号明文
}
3.4【服务端】实现平台 OAuth 回调
要做什么 :前端把 developer_login_code 回传平台后,平台会回调登录服务的三个 user_auth.* 地址,由登录服务签发 / 轮换 MCP token、并响应授权字段删除通知。位置同样在 server.ts。
平台回调 POST /auth/fetch_token:用 developer_login_code 换 MCP token:
app .post ( '/auth/fetch_token' , (req , res) => {
const { app_id , code } = req .body ?? {};
if (app_id !== config .appId || ! code) {
return res .json ({ code : 40001 , msg : 'invalid app_id or code' });
}
const consumed = consumeDeveloperLoginCode (app_id , code); // 一次性消费,过期/复用即失败
if ( ! consumed) return res .json ({ code : 40004 , msg : 'code is invalid, expired, or already used' });
const token = createMcpToken ({ appId : consumed .app_id , openId : consumed .open_id , ... });
res .json ({
code : 0 , msg : 'success' ,
data : {
access_token : token .access_token , expires_in : config .accessTokenTtl ,
refresh_token : token .refresh_token , refresh_token_expires_in : config .refreshTokenTtl ,
} ,
});
});
refresh_token(轮换 token)与 delete_userinfo(幂等删除宿主授权手机号)同理,均在 server.ts 中实现:
// refresh_token:rotateMcpToken 校验并轮换,失败返回 40004
const rotated = rotateMcpToken ({ oldRefreshToken : refresh_token , ... });
if ( ! rotated || rotated .app_id !== app_id) return res .json ({ code : 40004 , msg : '...' });
// delete_userinfo:按 request_id 幂等,只清手机号,不退登/解绑/撤 token
const firstTime = markDeleteNoticeHandled (request_id , open_id);
if (firstTime && ( fieldNames . length === 0 || fieldNames .includes ( 'PHONE' ))) {
clearAccountPhoneByOpenId ( config .appId , open_id);
}
res .json ({ success : true , error_code : 0 , error_message : '' });
3.5【服务端】MCP Server 校验登录态
要做什么 :平台调用 login_type 工具时会注入 X-DB-OPENID / X-DB-ACCESS-TOKEN,MCP Server 用中间件对 tools/call 强校验,调登录服务的内部接口 /internal/introspect 判 token 真伪。位置:mcp-server/src/auth.ts。
const AUTH_INTROSPECT_URL =
process . env . AUTH_INTROSPECT_URL ?? 'http://127.0.0.1:3300/internal/introspect' ;
const AUTH_DISABLED = process . env . MCP_AUTH_DISABLED === '1' ; // 本地可临时跳过
// Express 中间件:仅对 tools/call 强校验(initialize / tools/list 握手放行)
export async function mcpAuthMiddleware (req , res , next) {
if ( AUTH_DISABLED || ! isToolCall ( req .body)) return next ();
const openId = headerValue (req , 'x-db-openid' );
const accessToken = headerValue (req , 'x-db-access-token' );
if ( ! openId) return unauthorized (res , 'missing openid' ); // 缺 open_id → 401
if ( ! accessToken) return unauthorized (res , 'missing access token' );
const result = await introspect (openId , accessToken); // POST /internal/introspect
if ( ! result .active) return unauthorized (res , 'invalid access token' ); // active=false → 401
next ();
}
登录服务侧 /internal/introspect 复用 authenticate()(auth-verify.ts)查 token 表判真伪:
// token 缺失/过期/撤销/open_id 不匹配都算未授权
const token = findByAccessToken ( db .accessToken);
if ( ! token || token .revoked_at || token .access_expires_at < Date .now () || token .open_id !== db .openId) {
throw new AuthError ( 401 , 'invalid access token' );
}
四、demo联调与上线
本地启动与联调 —— 登录服务与 MCP Server 同属 server/ 一个工程,分别用 npm script 启动:
cd server
# 终端 1:登录鉴权服务(端口 3300),app_secret 只在进程环境注入
DOUBAO_APP_ID = 'db_app_xxx' DOUBAO_APP_SECRET = 'xxx' pnpm dev:login
# 终端 2:MCP Server(端口 3200)
pnpm dev:mcp
# 终端 3:dbx dev,联调本地 MCP
dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp
# 登录服务冒烟测试(15 项,覆盖两类登录交换 + fetch/refresh/delete + introspect)
pnpm test:smoke
注意事项 :
提示
demo中的代码主要是用于演示登录怎么接入,真实的业务上线,需注意以下部分:
manifest.yaml 的 user_auth.* 三个 URL、前端 runtime.ts 的 authApiBaseUrl,都要从 127.0.0.1:3300 换成可公网访问的 HTTPS 地址 。
登录服务需独立部署 (不随应用插件制品上传),并保证 DOUBAO_APP_SECRET、私钥只存在于服务端环境。
应用证书与私钥必须成对、按环境管理 :dev.key 与提交平台的 dev.csr(应用证书)来自同一对密钥,联调与生产不能跨环境混用,否则手机号解密会失败;证书有效期 1 年,到期前 30 天平台会通知更换。
把 MOCK_VERIFY_CODE 占位校验替换为真实验证码服务,并移除自定义登录页上的固定验证码提示文案。
支付接入
🔵 本节的支付能力与登录一样,都是通过 dbx CLI 驱动 coding agent、用自然语言增量生成的。你只需描述「给这个商超应用插件接入豆包应用插件支付,走对话下单 → 订单卡 → 去支付的闭环」,agent 会把支付服务端、前端支付、MCP 建单衔接一并落地。支付与登录复用同一个 server/ 工程 ,不新起服务。本节把 agent 产出的成果整理成可复用的接入说明。
支付让「豆包随手购」能把对话里生成的购物车变成一笔真实可付款的订单。本 Demo 的支付闭环入口只有一条:对话 → create_mock_order 出订单卡(OrderCard)→ 用户点「查看订单」进订单详情页 → 点「去支付」拉起收银台 (购物车页的本地下单已下线)。
普通支付 :本 Demo 已完整接入的主链路(建单 → 预下单 → 拉起收银台 → 回调验签 → 履约)。
签约 / 代扣(协议支付) :技术链路已实现但默认关闭 (SIGN_ENABLED != 'true'),协议模板与 service_id 需线下确认后才开启,本节仅作附注说明。
一、先理解全局
支付接入同样是「一份声明 + 多端协作」先看清谁调谁、按什么顺序:
整体时序 (普通支付):
① 对话确认购买 → mcp-server create_mock_order 以商品目录重算可信金额
↓ POST :3300/payment/orders(内部,服务端→服务端)
② 支付服务建订单草稿(open_id 暂空)→ 返回 out_order_no(SM 单号)
↓ 出 OrderCard,order_id = out_order_no,状态「待支付」
③ 用户点「查看订单」进详情页 → 点「去支付」→ 前端 payOrder(out_order_no)
↓ POST :3300/payment/orders/:outOrderNo/preorder(带 X-DB-Page-Session)
④ 支付服务:按 Page session 绑定下单用户 → 用「应用证书私钥」对 data 签名
↓ 返回 { data, dbAuthorization }(byte-identical,前端原样透传)
⑤ 前端 SDK requestOrder({ data, dbAuthorization }) → orderId
getOrderPayment({ orderId }) 拉起收银台,用户完成支付
↓
⑥ 平台回调 POST :3300/payment/callback(X-DB-Authorization)
支付服务用「平台证书公钥」对原始报文字节 ECDSA 验签 → 幂等落库 → 状态迁移
↓
⑦ 前端轮询 GET :3300/payment/orders/:outOrderNo 收敛到 PAID
支付成功 → POST /fulfill 推履约完成(fulfill_push_finish)
与登录的关系 :登录负责「用户是谁」(open_id + Page session),支付负责「这个用户付这笔钱」。前端支付的每个请求都带登录时存下的 Page session token(X-DB-Page-Session)证明用户身份,支付服务据此绑定订单归属。所以必须先接入登录、再接入支付 。
二、凭证与密钥速查
支付链路里同时有单据与会话 (每笔订单临时生成)和证书密钥 (应用级,后台申请后长期使用)。其中证书部分正是登录章节「二、凭证与密钥速查」里埋的伏笔——平台证书在支付回调验签时正式登场 。
单据与会话 :
证书与密钥 (在开发者后台「开发设置 → 证书管理」申请 / 获取):
应用证书与登录用的是同一对密钥 (dev.key + 提交平台的 dev.csr):登录用私钥解密 平台下发的手机号密文,支付用私钥签名 预下单请求。平台证书则是登录章节说「本登录 Demo 不涉及」的那类——它在这里用于验签平台发来的支付回调。
三、分步实现
下面按调用时序 分步:先配置证书(3.1),再服务端建单 / 预下单 / 回调 / 收敛(3.2–3.4),然后前端去支付闭环(3.5),最后 MCP 建单衔接(3.6)。每步标注【配置】/【服务端】/【前端】并给出关键代码。
3.1【配置】准备证书与支付服务配置
要做什么 :支付不需要在 manifest.yaml 新增字段 (沿用 app_key 与登录已声明的 user_auth.*)。需要准备的是两类证书,以及支付服务专有配置 payment/src/config.ts——商户、回调地址、证书序列号、金额与时间窗口。敏感值(私钥、AppSecret)只从环境变量 / 本地安全路径读取。
应用证书(预下单签名必需) :与登录复用同一对 ECC P-256 密钥(dev.key 私钥 \+ 提交平台的 dev.csr)。登录已配置过就无需重复生成,支付只是多用它来签名 (登录用来解密手机号)。私钥路径由 DEV_KEY_PATH 指定,序列号由 DEV_CERT_SERIAL 指定(sandbox 用 CSR 公钥验签,可填占位值)。
平台证书(回调验签必需) :平台的公钥证书,用于验签平台发来的支付回调。本 Demo 已把 sandbox 平台证书(ByteDance Smart Sign Cert ocean_mini_program)内置在 callback-verify.ts;平台若轮换证书,按 cert_serial 追加登记,未知序列号不得回退到任意证书 。
支付专有配置沿用 shared/config.ts 的通用项(端口、app 凭证、私钥路径),只补充支付相关字段:
export const paymentConfig = {
... sharedConfig , // 端口 3300、appId/appSecret、DEV_KEY_PATH 等,与登录共用
merchantUid : process . env . PAYMENT_MERCHANT_UID ?? 'sandbox_merchant_demo' , // 收款商户,正式环境须为已绑定商户
payNotifyUrl : process . env . PAYMENT_NOTIFY_URL // 支付回调地址
?? `http://127.0.0.1: ${ sharedConfig .port } /payment/callback` , // 上线换公网 HTTPS
devCertSerial : process . env . DEV_CERT_SERIAL ?? 'sandbox-dev-cert' , // 应用证书序列号,随签名上送
payExpireSeconds : Number ( process . env . PAYMENT_EXPIRE_SECONDS ?? 300 ) , // 预下单支付超时
callbackMaxSkewMs : Number ( process . env . PAYMENT_CALLBACK_MAX_SKEW_MS ?? 5 * 60 * 1000 ) , // 回调时间窗,防重放
signEnabled : process . env . SIGN_ENABLED === 'true' , // 签约/代扣开关,默认关闭
} as const ;
3.2【服务端】建单与预下单签名
要做什么 :实现两个核心端点——内部建单(POST /payment/orders,仅内网、由 mcp-server 调)与前端预下单(POST /payment/orders/:outOrderNo/preorder,带 Page session)。位置:server/open-capability/payment/src/router.ts。
内部建单 POST /payment/orders —— 只信任传入的可信金额(total_amount 分,由 mcp-server 依据商品目录算好),落库为草稿,open_id 暂空(预下单时再绑定):
router .post ( '/payment/orders' , (req , res) => {
const { idempotency_key , order_name , order_desc , total_amount , currency , items } = req .body ?? {};
if ( ! idempotency_key) return res .status ( 400 ) .json ({ code : 40001 , msg : 'missing idempotency_key' });
if ( ! Number .isInteger (total_amount) || total_amount <= 0 ) // 金额必须为正整数(分)
return res .status ( 400 ) .json ({ code : 40002 , msg : 'total_amount must be a positive integer (分)' });
const row = insertOrder ({ outOrderNo : newOutOrderNo () , idempotencyKey : idempotency_key ,
totalAmount : total_amount , currency : currency ?? 'CNY' , orderName : order_name , orderDesc : order_desc ,
items : /* 快照 */ });
res .json ({ code : 0 , msg : 'success' , data : { out_order_no : row .out_order_no , total_amount : row .total_amount } });
});
前端预下单 POST /payment/orders/:outOrderNo/preorder —— Page session 鉴权 \+ 绑定下单用户 \+ 用应用证书私钥对「即将发送的 data 字节」签名。关键:签名什么就返回什么,前端原样透传 :
router .post ( '/payment/orders/:outOrderNo/preorder' , (req , res) => {
const session = findValidPageSession ( pageSessionToken (req)); // X-DB-Page-Session 鉴权
if ( ! session) return res .status ( 401 ) .json ({ code : 40101 , msg : 'invalid or expired page session' });
const row = findOrderByOutOrderNo ( req . params .outOrderNo);
if ( ! row) return res .status ( 404 ) .json ({ code : 40401 , msg : 'order not found' });
if ( ! bindOrderUser ({ outOrderNo : row .out_order_no , openId : session .open_id , ... })) // 绑定归属;他人订单拒绝
return res .status ( 403 ) .json ({ code : 40301 , msg : 'order belongs to another user' });
const dataStr = JSON .stringify ({ outOrderNo : row .out_order_no , merchantUid : paymentConfig .merchantUid ,
totalAmount : row .total_amount , orderName : row .order_name , currency : row .currency ,
payNotifyUrl : paymentConfig .payNotifyUrl , /* ... */ });
const auth = sign ({ method : 'POST' , path : '/requestOrder' , body : dataStr } , // 用私钥签「即将发送的字节」
paymentConfig .devCertSerial);
transitionOrder ({ outOrderNo : row .out_order_no , to : 'PAYING' }); // CREATED -> PAYING(幂等)
res .json ({ code : 0 , msg : 'success' ,
data : { out_order_no : row .out_order_no , data : dataStr , dbAuthorization : auth .header } }); // 原样透传
});
签名器 (signer.ts):ECDSA_SHA256,待签名串固定 6 行 METHOD\nPATH\nCANONICAL_QUERY\nBODY_SHA256_HEX\nTIMESTAMP\nNONCE,签名走 ASN.1 DER 编码为 padded Base64URL,组装成 dbAuthorization 头(含 signature / cert_serial / nonce / timestamp)。严格遵循 security/signature-authentication-and-encryption.md。
3.3【服务端】回调验签与履约
要做什么 :实现平台支付回调(POST /payment/callback,用平台证书公钥 验签)与履约推送(POST /payment/orders/:outOrderNo/fulfill)。回调是支付安全的核心——验签通过前不得进入业务处理 。
支付回调 POST /payment/callback —— 用 req.rawBody 原始字节验签(不能用反序列化后的对象重新序列化),验签通过后幂等落库 \+ 状态迁移,必须回 {code:0,msg:"success"} 否则平台重试:
router .post ( '/payment/callback' , (req , res) => {
const rawBody = req .rawBody; // 入口 express.json 的 verify 钩子缓存的原始字节
const authorization = req .headers[ 'x-db-authorization' ] ?? '' ;
const msg = JSON .parse ( req . body .msg); // 外层 { type, version, msg(JSON字符串) }
try {
verifyCallback ({ method : 'POST' , path : '/payment/callback' , rawBody , authorization , // 平台证书公钥验签
eventTimeMs : Number ( msg .event_time) , maxSkewMs : paymentConfig .callbackMaxSkewMs ,
registerNonce : ( ... ) => registerNonce ( ... ) }); // 时间窗 + nonce 防重放
} catch (error) {
return res .status ( 401 ) .json ({ code : 40101 , msg : `verify failed: ${ error .reason } ` }); // 验签失败即拒绝,平台重试
}
const eventKey = ` ${ msg .out_order_no } : ${ msg .pay_status } : ${ msg .event_time } ` ;
const firstTime = recordCallbackEvent ({ eventKey , ... }); // 幂等:重复事件直接返回 success
if (firstTime && mapPayStatus ( msg .pay_status)) // SUCCESS->PAID / FAIL->PAY_FAILED ...
transitionOrder ({ outOrderNo : msg .out_order_no , to : mapPayStatus ( msg .pay_status) , ... });
res .json ({ code : 0 , msg : 'success' });
});
验签器 (callback-verify.ts)方向与签名器相反:平台用平台私钥签名回调,服务端用内置的平台证书公钥 验签。步骤为「解析 X-DB-Authorization 字段 → 按 cert_serial 选平台证书并校验有效期 → 校验 timestamp 时间窗 \+ nonce 防重放 → 重建 canonical request → ECDSA 验签」。
履约推送 POST /payment/orders/:outOrderNo/fulfill —— 仅 PAID 订单可调用,向平台推 fulfill_push_finish,接口幂等、失败不阻断主流程:
router .post ( '/payment/orders/:outOrderNo/fulfill' , async (req , res) => {
const session = findValidPageSession ( pageSessionToken (req)); // 鉴权 + 归属校验
const row = findOrderByOutOrderNo ( req . params .outOrderNo);
if ( row .local_status !== 'PAID' ) // 未支付不可履约
return res .status ( 409 ) .json ({ code : 40902 , msg : `order not paid (status ${ row .local_status } )` });
const ok = await pushFulfillFinish ({ orderId : row .order_id , outOrderNo : row .out_order_no });
setFulfillStatus ( row .out_order_no , ok ? 'NOTIFIED' : 'NOTIFY_FAILED' );
res .json ({ code : 0 , msg : 'success' , data : { fulfill_status : ok ? 'NOTIFIED' : 'NOTIFY_FAILED' } });
});
3.4【服务端】订单状态收敛
要做什么 :前端查单端点 GET /payment/orders/:outOrderNo。回调可能延迟到达,所以本地非终态时主动回查平台 order_query 收敛,以平台状态为准;回查失败不阻断,返回本地状态让前端继续轮询:
router .get ( '/payment/orders/:outOrderNo' , async (req , res) => {
const session = findValidPageSession ( pageSessionToken (req));
let row = findOrderByOutOrderNo ( req . params .outOrderNo);
if ( row .open_id && row .open_id !== session .open_id) // 归属校验
return res .status ( 403 ) .json ({ code : 40301 , msg : 'order belongs to another user' });
const notTerminal = ! [ 'PAID' , 'PAY_FAILED' , 'CLOSED' ] .includes ( row .local_status);
if (notTerminal) {
try {
const platform = await queryOrder ({ orderId : row .order_id , outOrderNo : row .out_order_no }); // 回查平台
const to = mapPayStatus ( platform ?.pay_status);
if (to) row = transitionOrder ({ outOrderNo : row .out_order_no , to , ... }).row ?? row; // 以平台为准
} catch { /* 回查失败不阻断,返回本地状态,前端继续轮询 */ }
}
res .json ({ code : 0 , msg : 'success' , data : toOrderView (row) }); // 金额同时给出分与元,便于页面展示
});
3.5【前端】去支付闭环
要做什么 :实现支付 helper payOrder(outOrderNo),串起「预下单 → SDK 拉起收银台 → 轮询收敛 → 支付成功推履约」,并在订单详情页的「去支付」按钮里调用。位置:src/pay/pay.ts + src/pages/order-detail/index.tsx。
支付 helper (pay.ts)—— 与 auth 严格分层,只处理已登录用户的支付动作;Page session token 从登录时存的 business_page_session 取,data / dbAuthorization 一律服务端生成、前端原样透传:
// 支付业务服务地址:与登录同一 open-capability 服务,复用 authApiBaseUrl(3300),不新增端口。
const PAY_API_BASE = runtimeConfig .authApiBaseUrl;
export async function payOrder (outOrderNo : string ) : Promise < PayOutcome > {
const token = await pageSessionToken (); // 未登录抛 'LOGIN_REQUIRED'
// 1) 业务服务端预下单,拿到 data / dbAuthorization(服务端签名,前端原样透传)
const { data , dbAuthorization } = await preorder (outOrderNo , token);
// 2) SDK 预下单换平台交易订单号 orderId
const { orderId } = await requestOrder ({ data , dbAuthorization });
// 3) 拉起收银台(用户在此完成/取消支付)
await getOrderPayment ({ orderId });
// 4) 轮询业务服务端收敛最终状态(不信任端上「看起来成功」)
const settled = await pollUntilSettled (outOrderNo , token);
// 5) 支付成功则推履约完成(幂等,失败不阻断)
if ( settled .local_status === 'PAID' ) await pushFulfill (outOrderNo , token);
return { status : settled .local_status , order : settled };
}
订单详情页 (order-detail/index.tsx)—— 「去支付」按钮调 payOrder(order.order_id);未登录(LOGIN_REQUIRED)时引导去登录:
const pay = async () => {
try {
const outcome = await payOrder ( order .order_id); // order_id 即 out_order_no
setPayStatus ( outcome .status); // 更新页面状态(PAID / PAY_FAILED ...)
} catch (error) {
if ((error as Error ).message === 'LOGIN_REQUIRED' ) {
showToast ({ message : '请先登录后再支付' });
navigateTo ({ url : 'pages/index/index' }); // 引导登录
}
}
};
3.6 MCP 建单衔接(对话下单入口)
支付闭环的起点是 MCP 工具 create_mock_order(位置:mcp-server/src/tools/createOrder.ts)。它名字沿用 create_mock_order(避免破坏 skill / manifest 的 OrderCard 卡片绑定),但已从「纯模拟」升级为真实支付前置:以商品目录为权威重算金额(绝不采信模型给的单价)→ 调支付服务建单 → 出 OrderCard :
async handler (args) {
if ( args .user_confirmed !== true ) return bizError ( 40001 , '请先与用户确认购买意愿后再创建订单' );
const trusted = buildTrustedOrder ( args .cart_snapshot); // 以商品目录重算可信金额,未知 sku 拒单
const created = await createPaymentOrder ({ // 调 payment 的 POST /payment/orders
idempotencyKey : idempotencyKeyOf ( args .cart_snapshot , trusted .total_amount_fen) , // 同购物车复用同订单
orderName , orderDesc , trusted });
const entity = { entity_type : 'mock_order_entity' ,
order_id : created .out_order_no , // order_id 即业务订单号 out_order_no
status : 'pending_payment' , status_text : '待支付' , payable : trusted .payable , /* ... */ };
return { content : [{ type : 'text' , text : '已为你创建订单……请在订单卡片点击「去支付」完成付款。' }] ,
structuredContent : { entities : [entity] } }; // 出 OrderCard(manifest tool_card_binding)
}
签约 / 代扣附注 :/payment/sign/preorder(签约单预下单)与 /payment/sign/withhold(发起代扣)的技术链路已实现,但默认关闭——SIGN_ENABLED != 'true' 时一律返回 40310 SIGN_DISABLED。协议模板与 service_id 需线下确认后再开启,且开启仅用于验证技术链路,不代表协议已具备正式效力。
四、联调与上线
本地启动与联调 —— 支付服务就是登录服务,同一个进程、同一个端口 3300,无需另起服务 。启动方式与登录完全一致:
cd server
# 终端 1:open-capability 服务(登录 + 支付,端口 3300);app_secret / 私钥只在进程环境注入
DOUBAO_APP_ID = 'db_app_xxx' DOUBAO_APP_SECRET = 'xxx' DEV_KEY_PATH = ./secrets/dev.key pnpm dev:login
# 终端 2:MCP Server(端口 3200)
pnpm dev:mcp
# 终端 3:dbx dev,联调本地 MCP
dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp
真机 / 模拟器验证走完整闭环:对话确认购买 → OrderCard →「查看订单」→ 订单详情页「去支付」→ 拉起收银台 。sandbox 环境收银台由模拟器本地发起,回调也由模拟器本地触发。
上线注意事项 :
金额一律服务端可信计算 :create_mock_order 以商品目录(CATALOG)重算,total_amount 为最小货币单位(分)整数;服务端不信任前端 / 模型给的任何金额。
回调与商户按环境替换 :PAYMENT_NOTIFY_URL 换成可公网访问的 HTTPS 地址 ;PAYMENT_MERCHANT_UID 换成正式已绑定商户;DEV_CERT_SERIAL 换成平台签发的开发者证书序列号。
平台证书按 cert_serial 管理 :平台轮换证书时在 callback-verify.ts 追加登记对应 PEM,未知序列号不得回退到任意证书;应用证书私钥与登录共用,同样按环境(联调 / 生产)隔离、不跨环境混用。
回调防重放常开 :callbackMaxSkewMs 时间窗 + nonce 去重需在多实例部署时接共享原子存储(当前为单进程内存实现)。
签约 / 代扣如需上线,先线下确认协议模板与 service_id,再开启 SIGN_ENABLED。
本地调试
你可以让 Coding Agent 帮你启动预览、连接本地 MCP 或向手机推送卡片。下面每个场景都给出了可以直接对 AI 说的示例,以及对应的命令;也可以在终端中自己执行。
请在项目根目录运行 dbx dev 启动本地调试。让 AI 操作下文的控制台命令时,需要使用交互式终端(TTY);只需要 Web 预览时,也可以让 AI 保持服务运行,再打开终端显示的完整 Web 地址。
启动 Web 模拟器
示例 query:「帮我启动本地调试,打开 Web 模拟器预览这个应用插件」
agent 在项目根目录执行:
启动成功后,在交互式调试控制台中输入:
控制台会打开 Web 模拟器;如果浏览器没有自动打开,使用控制台输出的完整调试地址。改完前端代码(Page / Widget / 样式)等热更新生效后,让 agent 在 REPL 里执行 web 重新打开调试器即可,无需重启 dbx dev;若配置、目录或端口变化导致会话无法复用,再重启。
联调本地 MCP Server
示例 query:「把工具调用打到本地 MCP Server 联调,而不是 manifest 里的远程地址」
如需将工具调用打到本地 MCP Server(而非 manifest 中的远程地址),启动时加 --mcp-endpoint。agent 会先起本地 MCP,再用它的地址启动 dbx dev:
# 终端 1:启动本地 MCP Server
cd server/mcp-server && pnpm dev
# 输出:supermart mcp server: http://127.0.0.1:3200/mcp
# 终端 2:启动 dbx dev,覆盖 MCP 地址
dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp
本地 MCP Server 使用 tsx watch 启动,代码修改后自动热重载,无需重启。
如果本轮还要联调登录(login_type 工具),让 agent 一并起登录服务:「同时把登录服务也起起来一起联调」 ——即先按 [登录接入 · 四、联调与上线](#四联调与上线) 起 pnpm dev:login(3300)与 pnpm dev:mcp(3200),再 dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp。
常用选项(agent 会按需附加,一般无需手动指定):
dbx dev --verbose # 输出详细生命周期日志
dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp # 覆盖 MCP 地址(本地联调)
登录联调:在 Web 调试器里配置证书与手机号
示例 query:「我要联调手机号一键登录,帮我准备好证书,告诉我在 Web 调试器里怎么配」
联调登录(尤其是手机号一键登录 )时,只启动服务还不够:手机号是平台加密下发的,Web 调试器需要先登记你的公钥、并模拟一个「已绑定手机号的宿主用户」,否则解密拿不到手机号。启动 dbx dev 后打开完整的 web_debugger URL,在调试器里完成两件事:
① 输入证书(dev.csr 内容) —— 调试器提供「输入证书」框,把与服务端私钥 dev.key 配对的 dev.csr 内容 粘贴进去(是内容,不是文件路径,更不要粘私钥 dev.key )。它的作用是在当前调试会话登记 ECC P-256 公钥,让平台用这把公钥加密手机号,服务端再用 dev.key 解密——等价于正式环境「在后台上传 CSR」这一步。让 agent 帮你准备证书内容:
# agent 会先在服务端找现有 dev.key/dev.csr;没有才生成这对密钥(私钥仅留服务端)
openssl ecparam -genkey -name prime256v1 -noout -out dev.key
openssl req -new -key dev.key -out dev.csr -subj "/CN=xxx/O=xxx"
# 然后读取 dev.csr 内容交给你,粘贴到 Web 调试器「输入证书」框
② 配置手机号 —— 在调试器里按界面提示填入用于联调的手机号,模拟「宿主侧已绑定手机号」的场景,一键登录入口才会出现并回调 phone_code。若不配置手机号,则相当于「宿主未绑定手机号」,只能走自定义登录页(手机号 + 验证码)那条链路。
几个联调要点:
证书必须成对、同会话 :web_debugger 里录入的 dev.csr 与服务端加载的 dev.key 必须来自同一对密钥;新建 / 切换 Web 模拟器会话后要重新录入 CSR。混用不同环境的 CSR/Key,会出现「get_user_phonenumber 成功但服务端解不开手机号」。
只有一键登录换手机号才需要证书 :纯自定义登录页联调不解密手机号,可以不配证书。
平台回调走本地 Bridge :联调会话里平台发起的 fetch_token / refresh_token 回调会经 Bridge 打到本地登录服务,因此不必先部署公网;但登录服务要持续运行,且 manifest.yaml 里的 user_auth.* 地址端口要和实际监听一致。
用沙箱身份联调 :登录会真正调用平台 OpenAPI,应使用沙箱 AppID/AppSecret,避免影响真实应用/用户。先执行 dbx sandbox info 确认当前项目沙箱及 Secret 是否存在;只有确实需要凭证时才执行 dbx sandbox info --include-secret,且不得把 Secret 写入日志、截图或代码仓库。
配好证书与手机号后,就能在 Web 调试器里实际触发需要登录的工具,走完「登录卡 → 换 open_id/手机号 → postLoginResult → 平台回调换 MCP token → 工具放行」整条链路。
验证工具与出卡链路(dbx check)
示例 query:「帮我验证一下 create_shopping_plan 这个工具能不能被正确调用、出的卡对不对」
Web 模拟器验证的是前端视觉;如果要验证 Skill 判断 → MCP 工具调用 → 出卡数据 这条后端链路(比如模型该不该调这个工具、entities 字段是否和 manifest 对齐),让 agent 用 dbx check --query '<query>' --expect-card required --verbose 跑。它不看前端渲染,专门排查协议与数据流,和 dbx dev 互补:一个看交互现场,一个看后端链路。--expect-card required 仅用于预期出卡的 Query;不应出卡时用 none,不确定时保留默认值 auto。
check 从 Manifest 读取 MCP endpoint,不继承 dev --mcp-endpoint 的临时覆盖。验证本地 MCP 时,先确认 Manifest 指向本次待测服务,或用 --manifest <path> 指定待测配置;正式构建前再确认正式配置使用公网可访问的地址。
推送页面 / 卡片到真机
示例 query:
「我手机连上了,帮我把首页推到真机上看看」
「推一张 4 人火锅的方案卡到豆包对话里」
真机推送要在 dbx dev 会话中先连接设备 :在 REPL 里执行 desktop 进入真机模式,按提示用豆包 App 扫码完成连接后,才能把页面 / 卡片推到这台设备。Agent 不需要打开豆包开发者工具时,可使用 desktop --agent。
连接成功后,继续在当前控制台的真机模式中输入以下命令:
pages
page
widgets
widget PlanCard --data '{"title":"4人火锅方案","item_count":8}'
pages 列出可打开的页面,page 不带参数时交互选择页面;也可传入列表中的完整 URL,页面参数写在 URL query 中。widgets 列出已注册的卡片 ID,widget 不带 ID 时可交互选择;--data 传入符合该 Widget 数据结构的 mock JSON。page 和 widget 均可用 --device-id <id> 指定已连接的设备,执行 page --help 或 widget --help 查看参数。
真机推送依赖当前这个 dbx dev 会话的设备连接:换了会话后需要重新连接设备。它和「上传云构建后扫码预览 UGC Bot 版本」是两条不同路径,本节指的是前者(dbx dev 直连真机)。