> 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.

# 框架概述与应用配置

豆包应用插件的端侧框架面向“AI 对话中的可交互服务”组织应用。本文依次介绍框架分层、应用组成、构建与运行机制，以及对应的工程约定和入口定义方式。

## 框架分层

应用插件前端的运行职责可以分为四层：业务入口、Framework、UI 渲染器和豆包宿主。UI 渲染器底层由 [Lynx](https://lynxjs.org/) 提供，负责将组件树转换为原生视图。四层之间的关系如下图所示。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 70, "rankSpacing": 90, "htmlLabels": true}}}%%
flowchart TB
  B["业务入口<br/>App：管理应用生命周期<br/>Page / Widget：承载交互视图<br/>Client Tool：执行端侧能力"]
  F["Framework<br/>启动 App · 管理视图运行时<br/>生命周期 · 运行时数据 · 端能力接口"]
  R["UI 渲染器<br/>JSX · 组件 · Hooks · 状态 · 事件"]
  H["豆包宿主<br/>容器 · 上下文 · 端能力"]

  B -->|通过入口配置与源码约定接入| F
  F -->|仅 Page / Widget 挂载组件树| R
  R -->|提交原生视图更新| H
  H -.->|提供容器与宿主侧运行参数| F

  classDef business fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef framework fill:#FFFFFF,stroke:#7B67D6,stroke-width:2px,color:#1F2329;
  classDef render fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  classDef host fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  class B business;
  class F framework;
  class R render;
  class H host;
```

实线表示开发者代码进入视图渲染的主要链路，虚线表示宿主向 Framework 提供运行环境。App 负责应用级生命周期，不进入 UI 渲染链路；只有 Page 和 Widget 会挂载组件树。

各层职责如下表所示。

| 层次        | 包含内容                                | 主要职责                                |
| --------- | ----------------------------------- | ----------------------------------- |
| 业务入口      | App、Page、Widget、Client Tool         | 描述应用结构和交互载体                         |
| Framework | 入口定义、生命周期、View Data / Context、端能力接口 | 把业务入口接入豆包宿主，并管理视图运行时                |
| UI 渲染器    | JSX、组件、Hooks、状态和事件                  | 执行组件函数，并把 props 或 state 变化转换为原生视图更新 |
| 豆包宿主      | 容器、上下文和端能力                          | 创建或绑定视图容器，传入宿主侧运行参数，提供路由、网络和设备能力    |

> **注意**
>
> Page 和 Widget 不是浏览器网页。开发时不要直接套用 HTML DOM、浏览器 CSS 默认值或同步主线程的执行假设。
>
> 开发时按以下文档确认可用能力：
>
> - 元素、事件和线程模型：参考[视图渲染与交互](/apps-plugin/docs/client-framework/rendering.md)；
> - CSS 属性及取值范围：先查询 [CSS 能力清单](/apps-plugin/docs/client-framework/css-capabilities.md)；
> - 布局、选择器、尺寸单位和动画的行为差异：再按需阅读[样式与布局差异](/apps-plugin/docs/client-framework/styling.md)；

## 应用组成

一个应用插件可以包含 App、Page、Widget 和 Client Tool 入口。各入口承担不同职责，并分别进入对应的运行上下文。

| 入口          | 定义与位置                                                               | 什么时候运行    | 主要职责                         |
| ----------- | ------------------------------------------------------------------- | --------- | ---------------------------- |
| App         | `defineApp()`；`src/app.ts`                                          | 应用插件启动时   | 不渲染界面，处理应用级生命周期和应用实例         |
| Page        | 默认导出 Page 函数组件；`src/pages/<name>/index.tsx`                         | 宿主打开对应页面时 | 渲染全页，承载详情、编辑和连续操作            |
| Widget      | 默认导出 Widget 函数组件；`src/widgets/<name>/index.tsx`                     | 宿主展示对应卡片时 | 渲染卡片，承载轻量结果、状态和操作            |
| Client Tool | 默认导出 handler；`src/tools/<name>/index.ts`，在 `app.config.ts.tools` 注册 | 宿主调用工具时   | 执行端侧能力，返回 Tool Result，不渲染 UI |

这些入口之间存在明确边界：

- App 负责应用级生命周期，不直接渲染 Page / Widget；
- Page 由路由或宿主按页面 URL 打开，Widget 由宿主按出卡协议选择并展示；
- 每个 Page / Widget 都有独立的视图实例，不应依赖其他入口的局部变量或组件状态；
- App 与视图、不同视图之间通过 View Data、路由参数、开放 API 或业务存储显式传递数据；

开发者只需要定义 App、Page、Widget 和需要的 Client Tool。应用启动代码、视图启动代码以及组件树根节点由构建工具生成，不应在业务代码中手动调用 Framework 内部的 bootstrap 方法。

Page / Widget 的创建、挂载、显示和销毁顺序见[生命周期与错误处理](/apps-plugin/docs/client-framework/lifecycle.md)，宿主输入和组件状态如何驱动刷新见[数据流与状态更新](/apps-plugin/docs/client-framework/data-flow.md)。

## 构建与运行

构建工具不会把所有入口打进同一个视图。它先分析目录约定和 `app.config.ts`，再分别生成 App、Page 和 Widget 产物；配置端工具时还会生成独立端工具运行时产物。

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 70, "rankSpacing": 60, "htmlLabels": true}}}%%
flowchart TB
  SOURCE["业务源码<br/>app.ts · pages · widgets · tools"] --> ANALYZE["Kit 构建分析<br/>目录约定 + app.config.ts"]
  ANALYZE --> APP["应用入口产物<br/>App"]
  ANALYZE --> PAGE["独立 Page 产物<br/>JS 与样式"]
  ANALYZE --> WIDGET["独立 Widget 产物<br/>JS 与样式"]
  ANALYZE --> TOOL["独立端工具运行时<br/>注册 handler 并返回结果"]

  classDef source fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef build fill:#FFFFFF,stroke:#7B67D6,stroke-width:2px,color:#1F2329;
  class SOURCE source;
  class ANALYZE,APP,PAGE,WIDGET,TOOL build;
```

这些产物进入运行时后，分别经过以下链路。

运行时由豆包宿主和 Framework 协作完成：

- App：宿主接收应用插件运行请求并启动应用入口，Framework 执行 App 生命周期；
- Page：宿主解析页面 URL，查找 Page，创建页面容器并传入页面渲染参数；
- Widget：宿主解析出卡数据，构造 Widget 渲染上下文并绑定卡片视图；
- 视图就绪后：Framework 建立对应的 Page / Widget View 实例，并挂载 UI 组件树；

**App 运行链路**

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 55, "rankSpacing": 55, "htmlLabels": true}}}%%
flowchart LR
  A1["应用插件启动"] --> A2["豆包宿主<br/>启动应用运行时"] --> A3["Framework<br/>启动 App"]

  classDef input fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef host fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef framework fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  class A1 input;
  class A2 host;
  class A3 framework;
```

**Page 运行链路**

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 55, "rankSpacing": 55, "htmlLabels": true}}}%%
flowchart LR
  P1["页面打开请求"] --> P2["豆包宿主<br/>按 URL 查找 Page<br/>创建页面容器"] --> P3["Framework<br/>建立 Page View<br/>挂载 UI 组件树"]

  classDef input fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef host fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef framework fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  class P1 input;
  class P2 host;
  class P3 framework;
```

**Widget 运行链路**

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 55, "rankSpacing": 55, "htmlLabels": true}}}%%
flowchart LR
  W1["出卡数据"] --> W2["豆包宿主<br/>构造 Widget 渲染上下文<br/>绑定卡片视图"] --> W3["Framework<br/>建立 Widget View<br/>挂载 UI 组件树"]

  classDef input fill:#FFFFFF,stroke:#3370FF,stroke-width:2px,color:#1F2329;
  classDef host fill:#FFFFFF,stroke:#D99A19,stroke-width:2px,color:#1F2329;
  classDef framework fill:#FFFFFF,stroke:#449B67,stroke-width:2px,color:#1F2329;
  class W1 input;
  class W2 host;
  class W3 framework;
```

开发者不需要调用宿主内部的容器创建或视图绑定接口，也不应依赖宿主原生上下文的字段结构。Page / Widget 只通过 Framework 提供的 View Data / Context 接口读取对前端开放的数据。

这套构建与运行方式有四个直接影响开发的结论：

1. App 随应用运行时启动，不依赖某个 Page / Widget 是否已经显示；
2. Page / Widget 是独立视图产物，不能依赖彼此的模块内存或组件 state；
3. Page 按 URL 打开，Widget 根据出卡数据绑定，二者的宿主入口不同；
4. 业务代码只定义入口和组件，构建工具负责生成 bootstrap、视图根节点和产物清单；

端工具没有 Page 的组件树和视图状态，不应依赖某个页面先初始化。工具返回值与 Agent 事件经过不同链路，具体见[Agent 与端侧交互](/apps-plugin/docs/client-framework/agent-interaction.md)。

## 工程约定

### 公开包的导入边界

| 导入路径                               | 职责                                     |
| ---------------------------------- | -------------------------------------- |
| `@doubao-dev/framework`            | App 入口定义、Hooks、View Data / Context、页面栈 |
| `@doubao-dev/framework/config`     | `defineAppConfig`、`defineConfig` 和配置类型 |
| `@doubao-dev/framework/api`        | 路由、网络、Storage、设备和业务开放能力                |
| `@doubao-dev/framework/components` | Framework 组件声明                         |

导入 API 时注意区分：

- React Hooks 从 `@doubao-dev/framework` 导入，以保持依赖与豆包应用插件内置的 React 运行时一致；
- 端能力从 `@doubao-dev/framework/api` 导入；

### 推荐目录

```text
src/
├── app.ts
├── app.config.ts
├── pages/
│   └── order-detail/
│       ├── index.tsx
│       └── index.scss
└── widgets/
    └── order-card/
        ├── index.tsx
        └── index.scss
```

入口发现遵循以下规则：

1. 一级 `src/pages/*/index.tsx` 和 `src/widgets/*/index.tsx` 可按约定自动发现；
2. Page / Widget 的多级目录、首页顺序和 metadata 在 `src/app.config.ts` 中显式声明；
3. 显式 `pages` 数组的第一项作为首页入口；

Page 使用由完整入口派生的 URL 作为身份。旧 Page ID 打开方式仅作为兼容入口保留，新代码和调试流程应使用
URL。Widget 默认 id 由入口目录名推导；需要被 Manifest 长期引用时，建议在配置对象中显式声明稳定且全局唯一的
`id`。查询和调试方式见全页（Full Page）开发。

## 应用配置

前端配置、Manifest 和视图代码分别解决不同问题：

| 配置位置                | 负责内容                        | 不负责内容               |
| ------------------- | --------------------------- | ------------------- |
| `src/app.config.ts` | Page / Widget 入口、名称、标题和卡片形态 | 实体 schema、权限和出卡绑定   |
| `manifest.yaml`     | AppID、MCP Server、实体、权限和出卡绑定 | 模板 Props、字段格式化和组件状态 |
| Page / Widget TSX   | View Data 校验、模板映射、交互和本地状态   | 替代 Manifest 权限配置    |

构建流程会同时消费前端入口配置与工程配置，但二者不会互相覆盖业务字段。工程目录、Manifest 和调试流程见前端开发（卡片 / 全页）。出现“入口能预览但正式对话不出卡”时，应检查 Manifest 和出卡绑定，而不是继续修改 `app.config.ts` 中的 UI metadata。

`src/app.config.ts` 集中维护以下信息：

- 应用的 `appId`、`name`、描述和关键词；
- Page / Widget 入口及其 metadata；
- Widget 的卡片形态；

应用配置应同时提供 `appId` 和 `name`；标题、描述和卡片形态在 `src/app.config.ts` 中集中维护。

```ts
import { defineAppConfig } from '@doubao-dev/framework/config';

export default defineAppConfig({
  appId: 'your-app-id',
  name: '订单助手',
  description: '查询订单并展示处理进度',
  keywords: ['订单', '进度'],
  pages: [
    {
      entry: 'pages/order-detail/index',
      title: '订单详情'
    }
  ],
  widgets: [
    {
      entry: 'widgets/order-card/index',
      name: '订单卡片',
      description: '展示订单摘要与当前状态',
      boxType: 'inbox',
      border: true,
      titleType: 'none'
    }
  ]
});
```

配置时注意：

- `pages` 对象项用于补充标题等 metadata；
- `widgets` 对象项还可配置名称、描述、边框和标题形态；
- 只有确有 Web 目标时才配置入口的 `web` 字段；

配置 `web` 字段不代表豆包应用插件的 UI 渲染环境与 Web 行为完全一致。

## 入口定义

三类入口分别承担应用生命周期和界面渲染职责。下面只展示入口定义的最小结构；数据、生命周期和交互逻辑分别在对应专题文档中说明。

Page / Widget 直接导出函数组件，并在 `src/app.config.ts` 中注册入口。视图生命周期使用 `useShow()`、`useHide()`、`useMounted()` 等 Hooks。

### App 示例

```ts
// src/app.ts
import { defineApp } from '@doubao-dev/framework';

export default defineApp({
  onError(error) {
    console.error('app error', error);
  }
});
```

### Widget 示例

```tsx
// src/widgets/order-card/index.tsx
export default function OrderCard() {
  return <view className="order-card" />;
}
```

### Page 示例

```tsx
// src/pages/order-detail/index.tsx
export default function OrderDetailPage() {
  return <view className="page" />;
}
```

函数组件只负责返回组件树。请求、订阅、计时器和宿主 API 调用应放在 `useEffect`、生命周期 Hooks 或事件处理函数中。完整实现方式见卡片（Widget）开发和全页（Page）开发。
