> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 豆包应用插件 Demo

**Demo 代码附件**

<a data-download-card data-size="273.09 KB" href="/apps-plugin/docs/downloads/doubao-supermart-demo.zip" download="doubao-supermart-demo.zip">doubao-supermart-demo.zip</a>

## 简介

:::info 提示

**豆包随手购**是一款豆包应用插件 Demo。用户只需用自然语言说出购物需求，豆包就能帮你完成“理解需求 → 生成购物方案 → 挑选替换商品 → 优化优惠 → 模拟下单”，实现一句话逛完超市。

<div hidden data-lark-callout-end></div>

:::

本教程以「豆包随手购」为例，介绍如何从零开始开发一个豆包应用插件，涵盖：

- 使用 `dbx` CLI 初始化项目、本地调试与真机预览
- 全页形式的页面（Page）开发
- 与 AI 对话联动的卡片组件（Widget）开发
- MCP Server 的开发
- Skill 的编写

## 项目结构

```text
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

```bash
npm install -g @doubao-dev/cli
```

### 2. 登录认证

```bash
dbx auth login
```

登录后可通过以下命令确认状态：

```bash
dbx auth status
```

### 3. 初始化项目

参考 [快速开始](/apps-plugin/docs/overview/quick-start.md) 章节 。

初始化完成后，新项目根目录包含 `manifest.yaml`、`skill/SKILL.md` 和前端工程，并安装内置开发 Skill。

## 开发前端 UI

### 全局配置

#### app.ts — 全局生命周期

```typescript
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 — 页面与卡片注册

```typescript
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` 注册页面入口：

```typescript
// 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>
  );
}
```

#### 页面跳转

```typescript
import { navigateTo } from '@doubao-dev/framework/api';

navigateTo({ url: 'pages/plan-detail/index' });
```

#### 事件处理

使用 `bindtap` 绑定点击事件：

```typescript
<view bindtap={() => console.log('点击')}>点击我</view>
```

#### 样式编写

支持 SCSS，推荐 BEM 命名规范：

```scss
// src/pages/home/index.scss
.home-page {
  display: flex;
  flex-direction: column;
  padding: 20px;

  &__title {
    font-size: 24px;
    font-weight: bold;
  }
}
```

### 开发卡片组件（Widget）

Widget 是 AI 对话中渲染的卡片，由工具调用结果驱动。新代码默认导出 Widget 函数组件，并在 `src/app.config.ts` 注册卡片入口。

#### 读取工具返回数据

```typescript
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` 开箱即用的卡片模板，覆盖大多数场景：

```typescript
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：

<table><colgroup><col width="195"/><col width="443"/></colgroup><tbody><tr><td>Prop</td><td>说明</td></tr><tr><td><code>items</code></td><td>列表项数组，渲染标准图文行</td></tr><tr><td><code>children</code></td><td>自定义内容区，传入后  <code>items</code>  不生效</td></tr><tr><td><code>header</code></td><td>标题栏，支持右侧操作文字</td></tr><tr><td><code>footer</code></td><td>底部操作区，支持主/次按钮</td></tr></tbody></table>

#### 自定义布局（children）

当标准 `items` 无法满足布局需求时，可通过 `children` 完全自定义内容区，同时保留 `footer` 按钮：

```typescript
<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` 统一管理，购物车变更后需同步给模型上下文：

```typescript
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 对比

| 特性     | Page                | Widget                          |
| ------ | ------------------- | ------------------------------- |
| 定义方式   | 默认导出 Page 函数组件      | 默认导出 Widget 函数组件                |
| 用途     | 全页面，可导航             | AI 对话卡片                         |
| 触发方式   | `navigateTo` 跳转     | 工具调用出卡                          |
| 额外生命周期 | `onShow` / `onHide` | `onForeground` / `onBackground` |
| 获取数据   | props / store       | `getViewData()`                 |

***

## 开发 MCP Server

豆包应用插件通过 MCP（Model Context Protocol）实现 AI 工具调用。对话中模型根据 Skill 规则调用工具，工具返回结构化数据，豆包端依据 `manifest.yaml` 的绑定关系自动渲染对应 Widget。

### 工具目录结构

Demo 工程，仅供参考！

```text
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` 中声明输出类型和卡片绑定：

```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` 数组：

```typescript
export interface ToolResult {
  content: { type: 'text'; text: string }[];  // 给模型 / 用户看的自然语言
  structuredContent: Record<string, unknown>;  // 成功：{ entities: [...] }；失败：{ code, message }
  isError?: boolean;                           // true = 业务失败，不出卡
}
```

成功出卡时返回：

```typescript
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,
};
```

业务失败时返回（不出卡）：

```typescript
return {
  content: [{ type: 'text', text: '暂不支持该场景' }],
  structuredContent: { code: 40404, message: '暂不支持该场景' },
  isError: true,
};
```

#### 3. 出卡流程

```text
模型调用工具
    ↓
handler 返回 structuredContent.entities
    ↓
豆包端查 manifest：工具名 + entity_type → tool_card_binding
    ↓
找到绑定的 Widget id（如 PlanCard）
    ↓
渲染 Widget，entity 数据通过 getViewData() 传入
```

## Skill 开发

Skill 是豆包 AI 的行为规范文件，定义模型在何时调用哪个工具、如何回复、以及各种边界情况的处理规则。

### 文件位置

```text
skill/
└── SKILL.md    # Skill 定义文件，dbx dev 启动时自动加载
```

`dbx dev` 会读取项目 `skill/` 目录及子目录中的所有 `SKILL.md`。如果 Skill 放在其他位置，用 `--skill <path>` 指定它所在的目录；相对路径从 `--project-path` 指定的项目目录算起。

### 文件结构

SKILL.md 由 YAML Front Matter 和 Markdown 正文两部分组成：

```markdown
---
name: supermart-assistant
description: 都把随手购。用户表达"买菜/购物/下单"等意图时触发……
---

# 正文（模型行为规范）
```

**Front Matter 字段说明：**

<table><colgroup><col width="233"/><col width="452"/></colgroup><tbody><tr><td>字段</td><td>说明</td></tr><tr><td><code>name</code></td><td>Skill 唯一标识，建议用 kebab-case</td></tr><tr><td><code>description</code></td><td>触发条件描述，模型据此判断是否激活该 Skill</td></tr></tbody></table>

`description` 是触发入口，直接影响模型是否启用这套规则，需简洁地描述核心使用场景和关键词（如「买菜/买齐/购物/凑单/下单」）。

### 正文内容规范

正文是给模型看的自然语言指令，建议包含以下几个部分：

#### 1. 通用边界

明确模型能做什么、不能做什么，防止模型越权操作：

```markdown
## 通用边界

- 价格、金额、件数必须来自工具返回，禁止自行估算
- 场景购物必须有：场景、人数、预算三要素，缺一先追问
- create_mock_order 只有用户明确确认购买后才能调用
- 用户要求超出能力（真实支付、退款）时，说明仅支持模拟环境
```

#### 2. 意图识别与工具选择

描述用户各类表达对应调用哪个工具，以及工具之间的编排顺序：

```markdown
## 意图识别与工具选择

- 描述整体场景（"四个人吃火锅""准备一周早餐"）→ create_shopping_plan
- 搜索/加购/替换商品（"搜羊肉卷""把肥牛换成羊肉"）→ search_products
- 问优惠/省钱/凑单（"有没有更省的买法"）→ optimize_cart
- 明确确认购买 → create_mock_order

# 推荐编排顺序：
create_shopping_plan → search_products（可多次）→ optimize_cart → create_mock_order
```

#### 3. 回复与卡片规范

约束模型文本回复的内容，避免与卡片信息重复或矛盾：

```markdown
## 回复与卡片

- 工具成功时文本只做一句话总结，明细由卡片承载，不在文本中罗列清单
- 只有工具返回中存在 <card reference_id="..."> 时才输出卡片引用
- optimize_cart 后只能说"预计可省 X 元"，不能说"已为你省下"
```

#### 4. 工具失败处理

覆盖各种异常情况，避免模型重试或凭空编造：

```markdown
## 工具失败处理

- isError 返回时如实转述 message，不自动重试，不输出卡片
- search_products 返回 status=empty：告知未找到，转述 suggestion
- optimize_cart 返回 status=keep：说明当前已是较优方案
```

#### 5. 工具调用格式

为每个工具提供调用示例，帮助模型准确构造入参：

````markdown
## 工具：create_shopping_plan

```json
{
  "name": "create_shopping_plan",
  "parameters": {
    "scene": "hotpot",
    "people_count": 4,
    "budget": 200,
    "preferences": { "spicy_level": "low" }
  }
}
```
````

### 完整示例（豆包随手购）

````markdown
---
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 的关系

```text
用户输入
    ↓
豆包模型读取 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 已登录的手机号，用户一键授权即可。
- **自定义登录页**：无手机号绑定时，走自定义页面（手机号 + 验证码）完成登录。

### 一、先理解全局

登录接入涉及「一份声明 + 四端协作」，先看清谁调谁、按什么顺序：

<table><colgroup><col width="199"/><col width="285"/><col width="411"/></colgroup><tbody><tr><td>部分</td><td>位置</td><td>职责</td></tr><tr><td>① manifest 声明</td><td><code>manifest.yaml</code></td><td>声明平台 OAuth 三个回调地址  <code>user_auth.*</code> ；给需要登录的 Tool 标注  <code>login_type</code></td></tr><tr><td>② 前端登录链路</td><td><code>src/auth/</code></td><td>一键登录 API、自定义登录页、隐私回调、公共 helper（凭证边界 + 结果回传守卫）</td></tr><tr><td>③ 业务鉴权服务（Server）</td><td><code>server/open-capability/login</code></td><td>前端登录交换、平台 OAuth 回调（换 / 刷新 token、删除授权字段）、供 MCP 复用的内部 token 校验</td></tr><tr><td>④ MCP Server 鉴权</td><td><code>server/mcp-server/src/auth.ts</code></td><td>处理  <code>login_type</code>  工具时校验平台注入的  <code>X-DB-*</code>  Header，调登录服务  <code>/internal/introspect</code>  判真伪</td></tr></tbody></table>

**整体时序**（以一键登录为例，自定义登录页仅第 ①②③ 步不同）：

```text
① 用户点登录 → 前端 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」链路，差异只在前端入口与业务凭证：

<table><colgroup><col width="153"/><col width="288"/><col width="369"/></colgroup><tbody><tr><td>维度</td><td>宿主手机号一键登录</td><td>自定义登录页</td></tr><tr><td>适用场景</td><td>用户在豆包 App 已绑定手机号</td><td>无手机号绑定时的兜底入口</td></tr><tr><td>前端入口</td><td><code>login.ts</code> （ <code>defineLoginApi</code> ）</td><td><code>login-page/index.tsx</code> （ <code>defineLoginPage</code> ）</td></tr><tr><td>触发</td><td>宿主一键授权回调  <code>onLogin(res)</code></td><td>用户提交手机号 + 验证码</td></tr><tr><td>业务凭证</td><td><code>phone_code</code> （ <code>onLogin(res).code</code> ）</td><td>手机号 + 验证码（用户填写）</td></tr><tr><td>服务端接口</td><td><code>POST /auth/doubao/login</code></td><td><code>POST /auth/custom-login</code></td></tr><tr><td>手机号来源</td><td><code>phone_code</code>  换取并解密（ <strong>需应用证书私钥</strong> ）</td><td>用户直接填写，无需证书</td></tr></tbody></table>

### 二、凭证与密钥速查

链路中同时存在**一次性凭证**（每次登录临时生成）和**长期身份与密钥**（应用级 / 用户级，后台申请后长期使用），二者不能混用。实现时可回查本节。

**四类一次性凭证**：

<table><colgroup><col width="200"/><col width="241"/><col width="379"/></colgroup><tbody><tr><td>凭证</td><td>来源</td><td>用途</td></tr><tr><td><code>login_code</code></td><td>前端  <code>login()</code></td><td>一次性登录码，交给业务 Server 换  <code>open_id</code></td></tr><tr><td><code>phone_code</code></td><td>一键登录  <code>onLogin(res).code</code></td><td>手机号授权码，交给业务 Server 换取并解密手机号</td></tr><tr><td><code>developer_login_code</code></td><td>业务 Server 签发（5 分钟一次性）</td><td>只用于  <code>postLoginResult</code>  回传给平台，禁止写 storage</td></tr><tr><td><code>access/refresh_token</code></td><td>业务 Server 在平台回调时签发</td><td>平台调  <code>login_type</code>  工具时注入，mcp-server 侧校验</td></tr></tbody></table>

**长期身份与密钥**（在开发者后台申请并配置）：

<table><colgroup><col width="161"/><col width="76"/><col width="271"/><col width="200"/></colgroup><tbody><tr><td>概念</td><td>归属</td><td>在登录中的作用</td><td>存放位置</td></tr><tr><td><code>app_key</code></td><td>应用</td><td>应用唯一标识，换 token、换  <code>open_id</code> 、回调校验时标识应用</td><td>manifest  <code>app_key</code> 、 <code>config.appId</code> （非敏感）</td></tr><tr><td><code>app_secret</code></td><td>应用</td><td>应用密钥，调  <code>get_openid</code>  /  <code>get_client_token</code>  时证明应用身份</td><td>仅环境变量  <code>DOUBAO_APP_SECRET</code> （敏感）</td></tr><tr><td><strong>开发者证书（应用证书）/ 私钥</strong></td><td>应用</td><td>平台用你的 <strong>公钥</strong> 加密手机号密文，服务端用配对的 <strong>私钥</strong> 解密（见 3.3）</td><td>私钥  <code>dev.key</code>  只存服务端  <code>DEV_KEY_PATH</code> （敏感）； <code>dev.csr</code>  提交平台</td></tr><tr><td><strong>平台证书</strong></td><td>平台</td><td>用于验签「平台 → 你」的回调请求（如支付回调）， <strong>本登录 Demo 不涉及</strong></td><td>开发者后台「证书管理 → 平台证书」</td></tr><tr><td><code>open_id</code></td><td>用户</td><td>用户在本应用下的稳定唯一标识，账号绑定与 MCP 鉴权的身份主键</td><td>服务端账号表 / token 表</td></tr></tbody></table>

> 证书在开发者后台「**开发设置 → 证书管理**」中管理，分「应用证书」和「平台证书」两类：**应用证书**是你自己的证书（对应私钥你保管），用于加密手机号下发（登录用）和支付请求签名；**平台证书**是平台的证书，用于你验签平台发来的回调。本登录 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` 指定）：
>
> ```bash
> openssl ecparam -genkey -name prime256v1 -noout -out dev.key   # 私钥，仅服务端保管
> openssl req -new -key dev.key -out dev.csr -subj "/CN=xxx/O=xxx" # 证书请求，提交平台
> ```

```yaml
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** —— 敏感值只从环境变量读取，绝不硬编码：

```typescript
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;
```

各配置项的含义与敏感性：

<table><colgroup><col width="156"/><col width="200"/><col width="438"/></colgroup><tbody><tr><td>配置</td><td>环境变量</td><td>说明</td></tr><tr><td>监听端口</td><td><code>LOGIN_SERVER_PORT</code></td><td>默认  <code>3300</code> ，需与 manifest  <code>user_auth.*</code>  及前端  <code>authApiBaseUrl</code>  一致</td></tr><tr><td>AppID</td><td><code>DOUBAO_APP_ID</code></td><td>与 manifest 的  <code>app_key</code>  一致（非敏感，可入代码）</td></tr><tr><td><strong>AppSecret</strong></td><td><code>DOUBAO_APP_SECRET</code></td><td><strong>敏感，仅走环境变量</strong> ，绝不硬编码 / 提交</td></tr><tr><td>OpenAPI Base</td><td><code>DOUBAO_OPENAPI_BASE</code></td><td>平台网关地址，联调 / 生产按实际替换</td></tr><tr><td>开发者私钥</td><td><code>DEV_KEY_PATH</code></td><td><strong>应用证书</strong> 对应的 PEM 私钥，解密手机号密文用（见 3.3）；绝不进版本库</td></tr></tbody></table>

> **关于验证码**：自定义登录页当前用固定验证码 `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`：

```typescript
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` 定义页面，本地校验手机号 + 验证码后走同一交换链路：

```typescript
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 统一处理：

```typescript
// 登录结果只允许回传一次（成功优先、失败幂等）
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`：

```typescript
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` 换取与签发链路：

```typescript
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`，涉及三个接口：

<table><colgroup><col width="399"/><col width="399"/></colgroup><tbody><tr><td>接口</td><td>作用</td></tr><tr><td><code>/api/token/v1/developer/get_client_token</code></td><td>换应用级 client\_token（内存缓存复用）</td></tr><tr><td><code>/api/login/v1/developer/get_openid</code></td><td><code>login_code</code>  →  <code>open_id</code></td></tr><tr><td><code>/api/login/v1/developer/get_user_phonenumber</code></td><td><code>phone_code</code>  → 加密手机号（在本地私钥解密）</td></tr></tbody></table>

```typescript
// 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），私钥只从本地安全路径读取，日志绝不打印手机号：

```typescript
// 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：

```typescript
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` 中实现：

```typescript
// 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`。

```typescript
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 表判真伪：

```typescript
// 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 启动：

```bash
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
```

**注意事项**：

:::info 提示

demo中的代码主要是用于演示登录怎么接入，真实的业务上线，需注意以下部分：

<div hidden data-lark-callout-end></div>

:::

- `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` 需线下确认后才开启，本节仅作附注说明。

### 一、先理解全局

支付接入同样是「一份声明 + 多端协作」先看清谁调谁、按什么顺序：

<table><colgroup><col width="145"/><col width="273"/><col width="360"/></colgroup><tbody><tr><td>部分</td><td>位置</td><td>职责</td></tr><tr><td>① manifest 与证书</td><td><code>manifest.yaml</code>  + 开发者后台证书</td><td>支付无需新增 manifest 字段（沿用  <code>app_key</code> ）； <strong>应用证书私钥</strong> 给支付请求签名、 <strong>平台证书</strong> 验签支付回调</td></tr><tr><td>② MCP 建单</td><td><code>server/mcp-server/src/tools/createOrder.ts</code></td><td><code>create_mock_order</code>  以商品目录重算可信金额，调支付服务建单，产出  <code>out_order_no</code>  并出 OrderCard</td></tr><tr><td>③ 支付服务（Server）</td><td><code>server/open-capability/payment</code></td><td>建单草稿、预下单签名、回调验签、状态收敛、履约推送；与登录共用进程/端口 3300</td></tr><tr><td>④ 前端支付链路</td><td><code>src/pay/pay.ts</code>  + 订单详情页</td><td>「去支付」闭环：预下单 → SDK 拉起收银台 → 轮询收敛 → 推履约</td></tr></tbody></table>

**整体时序**（普通支付）：

```text
① 对话确认购买 → 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`）证明用户身份，支付服务据此绑定订单归属。所以**必须先接入登录、再接入支付**。

### 二、凭证与密钥速查

支付链路里同时有**单据与会话**（每笔订单临时生成）和**证书密钥**（应用级，后台申请后长期使用）。其中证书部分正是登录章节「二、凭证与密钥速查」里埋的伏笔——**平台证书在支付回调验签时正式登场**。

**单据与会话**：

<table><colgroup><col width="232"/><col width="295"/><col width="293"/></colgroup><tbody><tr><td>凭证</td><td>来源</td><td>用途</td></tr><tr><td><code>out_order_no</code> （SM 单号）</td><td>支付服务  <code>newOutOrderNo()</code>  建单时生成</td><td>业务订单号，贯穿建单 / 预下单 / 查单 / 回调 / 履约；即 OrderCard 的  <code>order_id</code></td></tr><tr><td>Page session token</td><td>登录时签发，前端存  <code>business_page_session</code></td><td>前端请求头  <code>X-DB-Page-Session</code> ，向支付服务证明「当前页面用户」并绑定订单归属</td></tr><tr><td><code>data</code>  /  <code>dbAuthorization</code></td><td>支付服务预下单时生成</td><td><code>data</code>  是待支付订单串、 <code>dbAuthorization</code>  是其签名头； <strong>前端原样透传给 SDK <code>requestOrder</code>，绝不在端上拼装或改动</strong></td></tr><tr><td><code>orderId</code> （平台交易号）</td><td>SDK  <code>requestOrder</code>  返回</td><td>仅用于  <code>getOrderPayment</code>  拉起收银台，不与业务订单号  <code>out_order_no</code>  混用</td></tr></tbody></table>

**证书与密钥**（在开发者后台「开发设置 → 证书管理」申请 / 获取）：

<table><colgroup><col width="152"/><col width="105"/><col width="278"/><col width="299"/></colgroup><tbody><tr><td>概念</td><td>归属</td><td>在支付中的作用</td><td>存放位置</td></tr><tr><td><strong>应用证书 / 私钥</strong></td><td>应用</td><td>服务端用 <strong>私钥</strong> 对预下单  <code>data</code>  做 ECDSA_SHA256 签名（「签什么发什么」）； <code>cert_serial</code>  随  <code>dbAuthorization</code>  上送，平台按此选你的公钥验签</td><td>私钥  <code>dev.key</code>  只存服务端  <code>DEV_KEY_PATH</code> （敏感）；序列号  <code>DEV_CERT_SERIAL</code></td></tr><tr><td><strong>平台证书</strong></td><td>平台</td><td>验签「平台 → 你」的支付回调：平台用平台私钥签名回调，服务端用 <strong>平台证书公钥</strong> 对原始报文字节 ECDSA 验签，防伪造 / 篡改</td><td>服务端内置 PEM（ <code>callback-verify.ts</code> ），按  <code>cert_serial</code>  选证书</td></tr><tr><td><code>app_key</code></td><td>应用</td><td>应用唯一标识，建单 / 调平台交易接口时标识应用</td><td>manifest  <code>app_key</code> 、 <code>config.appId</code> （非敏感），与登录共用</td></tr></tbody></table>

> 应用证书与登录用的是**同一对密钥**（`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 凭证、私钥路径），只补充支付相关字段：

```typescript
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;
```

<table><colgroup><col width="130"/><col width="284"/><col width="406"/></colgroup><tbody><tr><td>配置</td><td>环境变量</td><td>说明</td></tr><tr><td>商户 UID</td><td><code>PAYMENT_MERCHANT_UID</code></td><td>收款商户，sandbox 可填测试值；正式环境须为已绑定商户</td></tr><tr><td>回调地址</td><td><code>PAYMENT_NOTIFY_URL</code></td><td>默认指向本进程  <code>/payment/callback</code> ，上线换 <strong>公网 HTTPS</strong></td></tr><tr><td><strong>应用证书序列号</strong></td><td><code>DEV_CERT_SERIAL</code></td><td>随  <code>dbAuthorization</code>  上送，平台按此选你的公钥验签</td></tr><tr><td><strong>应用私钥</strong></td><td><code>DEV_KEY_PATH</code></td><td>与登录共用的 PEM 私钥，预下单签名用；绝不进版本库</td></tr><tr><td>回调时间窗</td><td><code>PAYMENT_CALLBACK_MAX_SKEW_MS</code></td><td><code>event_time</code>  偏差超过此值即拒绝（防重放），默认 5 分钟</td></tr><tr><td>签约开关</td><td><code>SIGN_ENABLED</code></td><td>默认关闭；未开启时所有  <code>/payment/sign/*</code>  返回  <code>40310</code></td></tr></tbody></table>

#### 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` 暂空（预下单时再绑定）：

```typescript
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 字节」签名。**关键：签名什么就返回什么，前端原样透传**：

```typescript
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"}` 否则平台重试：

```typescript
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`，接口幂等、失败不阻断主流程：

```typescript
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` 收敛，以平台状态为准；回查失败不阻断，返回本地状态让前端继续轮询：

```typescript
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` 一律服务端生成、前端原样透传：

```typescript
// 支付业务服务地址：与登录同一 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`）时引导去登录：

```typescript
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**：

```typescript
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，无需另起服务**。启动方式与登录完全一致：

```bash
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 在项目根目录执行：

```bash
dbx dev
```

启动成功后，在交互式调试控制台中输入：

```text
web
```

控制台会打开 Web 模拟器；如果浏览器没有自动打开，使用控制台输出的完整调试地址。改完前端代码（Page / Widget / 样式）等热更新生效后，让 agent 在 REPL 里执行 `web` 重新打开调试器即可，无需重启 `dbx dev`；若配置、目录或端口变化导致会话无法复用，再重启。

### 联调本地 MCP Server

> 示例 query：**「把工具调用打到本地 MCP Server 联调，而不是 manifest 里的远程地址」**

如需将工具调用打到本地 MCP Server（而非 manifest 中的远程地址），启动时加 `--mcp-endpoint`。agent 会先起本地 MCP，再用它的地址启动 `dbx dev`：

```bash
# 终端 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 会按需附加，一般无需手动指定）：

```bash
dbx dev --verbose                                    # 输出详细生命周期日志
dbx dev --mcp-endpoint http://127.0.0.1:3200/mcp    # 覆盖 MCP 地址（本地联调）
```

### 登录联调：在 Web 调试器里配置证书与手机号

> 示例 query：**「我要联调手机号一键登录，帮我准备好证书，告诉我在 Web 调试器里怎么配」**

联调登录（尤其是**手机号一键登录**）时，只启动服务还不够：手机号是平台加密下发的，Web 调试器需要先登记你的公钥、并模拟一个「已绑定手机号的宿主用户」，否则解密拿不到手机号。启动 `dbx dev` 后打开完整的 `web_debugger` URL，在调试器里完成两件事：

![该图片为Web调试器界面，是豆包应用插件Demo本地调试中登录联调环节的操作界面，核心展示了与联调操作相关的关键设置项。界面上方的“Sandbox”标签被特别标注，左侧显示“点击配置登录信息”的提示，中间区域提供了“调试手机号模拟”项，还设有“证书内容”输入框，明确提示需粘贴与服务端私钥dev.key配对的dev.csr内容，界面右下角带有“上传到Sandbox”的操作按钮，整体对应文档中“输入证书（dev.csr内容）”的操作要求。](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/RHKbwcZwBiqWjekT2PfcM0VhnYg-02.067dba29b1.png)
<!-- lark-image-display-size width="3428" height="1674" -->

**① 输入证书（`dev.csr` 内容）** —— 调试器提供「输入证书」框，把与服务端私钥 `dev.key` **配对的** `dev.csr` **内容**粘贴进去（是内容，不是文件路径，更**不要粘私钥 `dev.key`**）。它的作用是在当前调试会话登记 ECC P-256 公钥，让平台用这把公钥加密手机号，服务端再用 `dev.key` 解密——等价于正式环境「在后台上传 CSR」这一步。让 agent 帮你准备证书内容：

```bash
# 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`。

连接成功后，继续在当前控制台的真机模式中输入以下命令：

```text
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` 直连真机）。
