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

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

@@ -0,0 +1,832 @@
+# 组件开发指南
+
+> 项目配置：下文 `defineAppConfig` 和 `appId` 示例适用于独立应用项目，沿用其配置要求。Plugin CLI 项目以根目录的 `plugin.json` 为标识，`src/` 位于 `com.doubao/app/` 下；`app.config.ts` 默认导出普通对象，不填写 `appId`，由 CLI 查询注入。配置示例以 `doubao-plugin-app` Skill 的应用开发指南为准，本文的组件、Hooks 和入口 metadata 用法共用。
+
+Page（页面）和 Widget（卡片）组件的完整开发指南。
+
+---
+
+## 🎯 Page 开发指南
+
+### App 配置、可选入口与多级目录
+
+独立应用项目的 `src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`，`appId` 使用开放平台 `db_xxxxxx` 风格。`pages` / `widgets` 是可选的显式入口配置。
+一级页面目录会自动发现，例如 `src/pages/home/index.tsx` 会产出页面路径 `/pages/home/index`；不配置到 `pages` 时仍可构建，
+但 `title`、`description` 等页面 metadata 为空。
+
+需要补 metadata、固定首页顺序或声明多级目录时，再配置 `pages` 数组。数组第一项会作为应用首页
+（最终 manifest 的 `appletEntry`）。显式声明入口时，entry 写到 `index`，例如 `'pages/home/index'`，
+不要省略入口文件名。
+
+如果不配置 `pages` / `widgets`，一级 Page / Widget 仍会按目录产出；Page 的跳转路径按入口推导，Widget 的默认 ID 取入口最后一级目录名，
+页面/卡片 metadata 字段为空，Widget 的 `boxType` 默认为 `inbox`。没有显式 `pages` 顺序时，默认首页入口为
+`index`；首页不是 `index` 时建议配置 `pages` 第一项。
+
+多级目录不会被一级扫描自动发现，例如 `src/pages/account/demo/index.tsx` 需要显式写
+`entry: 'pages/account/demo/index'`。页面跳转使用 entry 对应的路径，例如 `/pages/account/demo/index`。
+
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  pages: [
+    'pages/home/index',
+    'pages/account/demo/index',
+    {
+      entry: 'pages/profile/index',
+      title: '资料页',
+      description: '补充 metadata 的页面示例'
+    }
+  ]
+});
+```
+
+### 基本结构
+
+```tsx
+import { useDestroy, useHide, useShow, useViewData } from '@doubao-dev/framework';
+import './index.scss';
+
+interface PageViewData {
+  title: string;
+}
+
+export default function Page() {
+  useShow(() => console.log('页面显示'));
+  useHide(() => console.log('页面隐藏'));
+  useDestroy(() => console.log('页面销毁'));
+
+  const viewData = useViewData<PageViewData>();
+  return <MyPageComponent {...viewData} />;
+}
+```
+
+### 页面布局示例
+
+**1. 默认页面布局**
+普通 Page 默认采用可滚动安全区布局：根节点使用垂直 `scroll-view`，内容区预留顶部安全距离，避免状态栏和右上角胶囊按钮遮挡。
+完整规则和样式写法见 [开发规则](../rules/dos-and-donts.md)。
+```tsx
+export default function Page() {
+  return (
+    <scroll-view className="full-page" scroll-orientation="vertical" enable-scroll={true}>
+      <view className="full-page__content">
+        <view className="full-page__header">头部</view>
+        <view className="full-page__body">内容区域</view>
+        <view className="full-page__footer">底部</view>
+      </view>
+    </scroll-view>
+  );
+}
+```
+
+**2. 九宫格布局示例**
+
+```tsx
+export default function GridPage() {
+  const items = [
+    { id: '1', title: '应用1', icon: '🎯' },
+    { id: '2', title: '应用2', icon: '📱' },
+    { id: '3', title: '应用3', icon: '⚡' }
+  ];
+
+  return (
+    <view className="grid-container">
+      {items.map(item => (
+        <view key={item.id} className="grid-item">
+          <text className="icon">{item.icon}</text>
+          <text className="title">{item.title}</text>
+        </view>
+      ))}
+    </view>
+  );
+}
+```
+
+### 页面参数接收
+
+```tsx
+import { useViewData } from '@doubao-dev/framework';
+
+interface PageViewData {
+  userId: string;
+  tab?: string;
+}
+
+export default function ProfilePage() {
+  const viewData = useViewData<PageViewData>();
+  const { userId, tab = 'profile' } = viewData;
+
+  return (
+    <view>
+      <text>用户 ID: {userId}</text>
+      <text>当前标签: {tab}</text>
+    </view>
+  );
+}
+```
+
+### 页面导航
+
+```tsx
+import { navigateTo, redirectTo, reLaunch } from '@doubao-dev/framework/api';
+
+// 保留当前页面，打开新页面
+navigateTo({
+  url: '/pages/user-detail/index?userId=123&tab=profile'
+});
+
+// 替换当前页面
+redirectTo({
+  url: '/pages/settings/index'
+});
+
+// 关闭所有页面并回到首页
+reLaunch({
+  url: '/pages/home/index'
+});
+```
+
+`url` 在常规页面跳转里填写目标 Page 路径，通常和 `src/pages/<page-name>/index.tsx` 对应，例如
+`/pages/detail/index`。
+
+页面内通过 `useViewData<PageViewData>()` 读取 URL 中传入的参数。
+
+### 常用模式
+
+**1. 数据加载**
+
+```tsx
+import { useEffect, useState } from '@doubao-dev/framework';
+import { request } from '@doubao-dev/framework/api';
+
+interface UserData {
+  name?: string;
+}
+
+function MyPage({ userId }: { userId: string }) {
+  const [data, setData] = useState<UserData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        setLoading(true);
+        setError('');
+        const result = await request({
+          url: `https://api.example.com/users/${userId}`,
+          method: 'GET'
+        });
+        setData(result.data as UserData);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : '加载失败');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    void fetchData();
+  }, [userId]);
+
+  if (loading) return <text>加载中...</text>;
+  if (error) return <text>错误: {error}</text>;
+  if (!data) return <text>无数据</text>;
+
+  return <view>{/* 渲染数据 */}</view>;
+}
+```
+
+**2. 表单提交**
+
+```tsx
+import { useState } from '@doubao-dev/framework';
+import { navigateBack, request, showToast } from '@doubao-dev/framework/api';
+
+function FormPage() {
+  const [formData, setFormData] = useState({
+    name: '',
+    email: ''
+  });
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async () => {
+    try {
+      setSubmitting(true);
+      await request({
+        url: 'https://api.example.com/submit',
+        method: 'POST',
+        data: formData
+      });
+      showToast({ message: '提交成功' });
+      navigateBack(); // 返回上一页
+    } catch (err) {
+      showToast({ message: '提交失败' });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <view>
+      <input
+        value={formData.name}
+        onInput={e => setFormData({ ...formData, name: e.detail.value })}
+        placeholder="姓名"
+      />
+      <input
+        value={formData.email}
+        onInput={e => setFormData({ ...formData, email: e.detail.value })}
+        placeholder="邮箱"
+      />
+      <button onClick={handleSubmit} disabled={submitting}>
+        {submitting ? '提交中...' : '提交'}
+      </button>
+    </view>
+  );
+}
+```
+
+---
+
+## 🎴 Widget 开发指南
+
+### 可选 Widgets 配置
+
+一级 Widget 目录会自动发现，例如 `src/widgets/my-widget/index.tsx` 会产出 `widgetId: 'my-widget'`。不配置
+`widgets` 时仍可构建，但 `name`、`description` 等 metadata 为空，`boxType` 默认是 `inbox`。
+`titleType` 需要显式传值；默认无标题写 `titleType: 'none'`。
+
+Widget 的卡片内容和布局必须使用 [Widget 模板库](../widget-templates/overview.md) 中的 `@doubao-dev/template` 模板完成。创建
+Widget 时先读模板库的选型指南和 props 参考，选中模板后再回到本指南处理入口组件、`useViewData<T>()`、生命周期、
+`boxType`、`titleType` 和端能力调用。
+
+不要在 Widget 中手写 `view` / `text` / `image` 拼卡片布局。现有 Props 无法覆盖的内容，按模板能力或新设计需求确认。
+
+需要补 metadata 或声明多级目录时，再配置 `widgets` 数组。显式声明入口时，entry 写到 `index`，例如
+`'widgets/my-widget/index'`，不要省略入口文件名。
+多级目录如 `src/widgets/order/detail/index.tsx` 需要显式写 `'widgets/order/detail/index'`。
+如果不配置 `id`，默认 `widgetId` 是最后一级目录名 `detail`。Widget ID 必须在应用内全局唯一；如果多个入口得到
+相同 ID，构建会失败，需要在 `app.config.ts` 中为它们配置不同的 `id`。
+
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/simple-card/index',
+      titleType: 'none'
+    },
+    {
+      entry: 'widgets/order/detail/index',
+      titleType: 'none'
+    },
+    {
+      entry: 'widgets/my-widget/index',
+      id: 'my-widget',                 // 卡片唯一标识
+      name: '我的卡片',                 // 卡片名称
+      description: '卡片功能描述',       // 卡片描述
+      boxType: 'inbox',                // 卡片类型: inbox | full_box | custom_box
+      border: true,
+      keywords: ['demo', 'widget'],
+      titleType: 'none'                // 不展示标题栏
+    }
+  ]
+});
+```
+
+### 基本结构
+
+```tsx
+import {
+  useBackground,
+  useDestroy,
+  useForeground,
+  useHide,
+  useMounted,
+  useShow,
+  useViewData
+} from '@doubao-dev/framework';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface MyWidgetData {
+  items: ContentCardItem[];
+}
+
+export default function Widget() {
+  useShow(() => console.log('卡片显示'));
+  useHide(() => console.log('卡片隐藏'));
+  useForeground(() => console.log('应用回到前台'));
+  useBackground(() => console.log('应用进入后台'));
+  useMounted(() => console.log('卡片挂载'));
+  useDestroy(() => console.log('卡片销毁'));
+
+  const viewData = useViewData<MyWidgetData>();
+  return <ContentCard items={viewData.items} />;
+}
+```
+
+### 卡片类型 (boxType)
+
+**1. inbox - 普通卡片**
+
+默认卡片类型，适用于绝大多数场景（信息展示、结果回显、轻量交互）。
+
+推荐使用场景：
+- 内容相对简短：标题/摘要/列表/状态提示等
+- 不需要占用整行宽度，希望保持对话流的紧凑阅读体验
+- 交互以按钮、简单表单项为主
+
+在 `src/app.config.ts` 的对应 Widget entry 上配置 `boxType: 'inbox'`。入口和 metadata 写法以
+  [开发规则](../rules/dos-and-donts.md) 为准。卡片内容仍从 [Widget 模板库](../widget-templates/overview.md) 选模板，不因 `boxType`
+  变化而手写布局。
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/info-card/index',
+      id: 'info-card',
+      name: '信息卡片',
+      boxType: 'inbox',
+      titleType: 'none'
+    }
+  ]
+});
+```
+
+**2. full_box - 全宽卡片**
+
+适用于需要更大展示空间的卡片（例如图表、图片墙、复杂表单等）。
+
+在 `src/app.config.ts` 的对应 Widget entry 上配置 `boxType: 'full_box'`。入口和 metadata 写法以
+[开发规则](../rules/dos-and-donts.md) 为准。需要全宽展示时，优先选择模板库中的列表、订单、票务或媒体布局模板；
+匹配不上时按模板能力或新设计需求确认。
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/user-action-card/index',
+      id: 'user-action-card',
+      name: '全宽卡片示例',
+      boxType: 'full_box',
+      titleType: 'none'
+    }
+  ]
+});
+```
+
+**3. custom_box - 自定义容器样式**
+
+在 `src/app.config.ts` 的 Widget entry 上配置 `boxType: 'custom_box'`，构建后 Manifest 对应
+`boxType: 4`。容器不添加默认背景、圆角和描边，由业务小程序的内容样式设置；标题栏仍由
+`titleType` 控制。未配置时仍默认为 `inbox`。
+
+### ViewData 类型
+
+Widget viewData 通过 `useViewData<T>()` 的泛型参数和 TypeScript 接口表达。数据结构应尽量贴近所选模板的 props
+或列表项类型。
+
+```tsx
+import { useViewData } from '@doubao-dev/framework';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface ProductCardData {
+  title: string;
+  imageSrc?: string;
+  price?: string;
+  quantity?: string;
+  infoRows?: ContentCardItem[];
+}
+
+export default function ProductCard() {
+  const viewData = useViewData<ProductCardData>();
+
+  return (
+    <ContentCard
+      items={[
+        {
+          title: viewData.title,
+          subtitle: [viewData.price, viewData.quantity].filter(Boolean).join(' | '),
+          thumbnailSrc: viewData.imageSrc
+        },
+        ...(viewData.infoRows ?? [])
+      ]}
+    />
+  );
+}
+```
+
+### 常用模式
+
+**1. 数据获取和展示**
+
+```tsx
+import { useEffect, useState, useViewData } from '@doubao-dev/framework';
+import { request } from '@doubao-dev/framework/api';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface WeatherInfo {
+  city: string;
+  temperature: number;
+  condition: string;
+  windSpeed: number;
+}
+
+export default function WeatherWidget() {
+  const { city } = useViewData<{ city: string }>();
+  const [weather, setWeather] = useState<WeatherInfo | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    const fetchWeather = async () => {
+      try {
+        setError('');
+        const response = await request({
+          url: `https://api.example.com/weather?city=${city}`,
+          method: 'GET'
+        });
+        setWeather(response.data as WeatherInfo);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : '获取天气失败');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    void fetchWeather();
+  }, [city]);
+
+  if (loading) return <ContentCard items={[{ title: '加载中...' }]} />;
+  if (error) return <ContentCard items={[{ title: error }]} />;
+  if (!weather) return <ContentCard items={[{ title: '暂无数据' }]} />;
+
+  const items: ContentCardItem[] = [
+    { key: 'condition', title: weather.city, subtitle: weather.condition },
+    { key: 'wind', title: '风速', subtitle: weather.windSpeed },
+    { key: 'temperature', title: '温度', subtitle: `${weather.temperature}℃` }
+  ];
+
+  return <ContentCard items={items} />;
+}
+```
+
+**2. 用户交互**
+
+```tsx
+import { useState } from '@doubao-dev/framework';
+import { sendFollowUpMessage } from '@doubao-dev/framework/api';
+import { AskHumanCard } from '@doubao-dev/template';
+
+function InteractiveWidget({ initialCount }: { initialCount: number }) {
+  const [count, setCount] = useState(initialCount);
+
+  const handleIncrement = () => {
+    const nextCount = count + 1;
+    setCount(nextCount);
+    // 以用户身份发送后续消息，触发新一轮对话
+    void sendFollowUpMessage({
+      content: [{ type: 'text', text: `用户将计数增加到 ${nextCount}，请基于新的计数继续回复` }]
+    });
+  };
+
+  return (
+    <AskHumanCard
+      variant="jump"
+      items={[
+        {
+          key: 'increment',
+          text: `增加到 ${count + 1}`,
+          showArrow: 'right',
+          onClick: handleIncrement
+        }
+      ]}
+    />
+  );
+}
+```
+
+**3. 打开页面**
+
+```tsx
+import { navigateTo } from '@doubao-dev/framework/api';
+import { AskHumanCard } from '@doubao-dev/template';
+
+function ActionWidget({ itemId }: { itemId: string }) {
+  const handleViewDetail = () => {
+    navigateTo({
+      url: `/pages/item-detail/index?id=${itemId}`
+    });
+  };
+
+  return (
+    <AskHumanCard
+      variant="jump"
+      items={[
+        {
+          key: 'view-detail',
+          text: '查看详情',
+          showArrow: 'right',
+          onClick: handleViewDetail
+        }
+      ]}
+    />
+  );
+}
+```
+
+---
+
+## 🎨 样式开发
+
+### SCSS 文件组织
+
+```scss
+// 样式变量
+$primary-color: #1890ff;
+$text-color: #333;
+$bg-color: #f5f5f5;
+$border-radius: 8px;
+$spacing: 16px;
+
+// 容器样式
+.container {
+  padding: $spacing;
+  background-color: $bg-color;
+
+  .header {
+    font-size: 36px;
+    color: $text-color;
+    margin-bottom: $spacing;
+  }
+
+  .content {
+    background-color: #fff;
+    border-radius: $border-radius;
+    padding: $spacing;
+  }
+}
+
+// 响应式布局
+.responsive-layout {
+  display: flex;
+  flex-wrap: wrap;
+  gap: $spacing;
+
+  .item {
+    flex: 1 1 calc(50% - #{$spacing});
+    min-width: 200px;
+  }
+}
+```
+
+### 常用布局模式
+
+本节布局示例面向 Page 的普通内容区。Widget 卡片整体布局不要手写，先使用
+[Widget 模板库](../widget-templates/overview.md) 中的模板。
+
+承载 `button`、`input`、`switch` 等内置组件时，还要按 [开发规则](../rules/dos-and-donts.md) 检查组件最小宽度、换行和收缩。
+
+**1. Flex 布局**
+
+```scss
+.flex-container {
+  display: flex;
+  flex-direction: row;      // row | column
+  justify-content: center;  // flex-start | center | flex-end | space-between
+  align-items: center;      // flex-start | center | flex-end | stretch
+  gap: 16px;
+}
+```
+
+**2. Grid 布局**
+
+```scss
+.grid-container {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 16px;
+  padding: 16px;
+}
+```
+
+**3. Page 内容块布局**
+
+```scss
+.content-block {
+  background-color: #fff;
+  border-radius: 8px;
+  padding: 24px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  margin-bottom: 16px;
+}
+```
+
+---
+
+## 🔌 View Data APIs
+
+在 Page 和 Widget 开发中，通过 `useViewData<T>()` 获取当前视图数据。
+
+获取当前视图的数据，支持泛型类型定义，确保类型安全。
+
+**类型定义**：
+```typescript
+import { useViewData } from '@doubao-dev/framework';
+
+function useViewData<T extends Record<string, any> = Record<string, any>>(): T
+```
+
+**使用场景**：
+
+1. **在入口组件和生命周期 Hook 中获取数据**：
+```tsx
+import { useMounted, useViewData } from '@doubao-dev/framework';
+import { AskHumanCard } from '@doubao-dev/template';
+
+interface TodoData {
+  tasks: string[];
+}
+
+export default function TodoWidget() {
+  const viewData = useViewData<TodoData>();
+  useMounted(() => console.log('任务列表:', viewData.tasks));
+
+  return (
+    <AskHumanCard
+      variant="jump"
+      items={[
+        {
+          key: 'task-count',
+          text: `${viewData.tasks.length} 个任务`,
+          showArrow: 'right'
+        }
+      ]}
+    />
+  );
+}
+```
+
+2. **在自定义函数中访问数据**：
+```tsx
+import { useViewData } from '@doubao-dev/framework';
+import { ContentCard } from '@doubao-dev/template';
+
+interface WeatherData {
+  city: string;
+  temperature: number;
+}
+
+function WeatherWidget() {
+  const viewData = useViewData<WeatherData>();
+
+  const loadWeatherIcon = () => {
+    return viewData.temperature > 25 ? '☀️' : '❄️';
+  };
+
+  return <ContentCard items={[{ title: loadWeatherIcon() }]} />;
+}
+```
+
+**注意事项**：
+- ✅ **推荐**：在入口组件函数中使用 `useViewData<T>()` 获取数据
+- ✅ **推荐**：生命周期 Hook 可以闭包访问入口组件读取的数据
+- 🔒 **类型安全**：始终定义明确的 TypeScript 接口并传递给泛型参数
+
+## 🔧 开发最佳实践
+
+### 1. TypeScript 类型定义
+
+```tsx
+// 定义 props 类型
+interface ComponentProps {
+  title: string;
+  count?: number;
+  onAction: (value: string) => void;
+}
+
+// 定义 state 类型
+interface ComponentState {
+  loading: boolean;
+  data: DataType | null;
+  error: string | null;
+}
+
+function MyComponent({ title, count = 0, onAction }: ComponentProps) {
+  const [state, setState] = useState<ComponentState>({
+    loading: false,
+    data: null,
+    error: null
+  });
+
+  return <view>{/* 组件内容 */}</view>;
+}
+```
+
+### 2. 错误处理
+
+```tsx
+try {
+  // 异步操作
+  const result = await someAsyncOperation();
+  setData(result);
+} catch (err) {
+  const message = err instanceof Error ? err.message : '未知错误';
+  // 记录错误
+  console.error('操作失败:', message);
+
+  // 显示用户友好的错误消息
+  setError('操作失败，请重试');
+
+  // 可选：上报错误
+  reportAppLog({
+    level: 'error',
+    message,
+    context: { operation: 'someAsyncOperation' }
+  });
+}
+```
+
+### 3. 性能优化
+
+```tsx
+import { useMemo, useCallback } from '@doubao-dev/framework';
+
+function OptimizedComponent({ data, onSelect }) {
+  // 缓存计算结果
+  const processedData = useMemo(() => {
+    return data.map(item => ({
+      ...item,
+      computed: expensiveComputation(item)
+    }));
+  }, [data]);
+
+  // 缓存回调函数
+  const handleClick = useCallback((id: string) => {
+    onSelect(id);
+  }, [onSelect]);
+
+  return (
+    <view>
+      {processedData.map(item => (
+        <view key={item.id} onClick={() => handleClick(item.id)}>
+          {item.computed}
+        </view>
+      ))}
+    </view>
+  );
+}
+```
+
+### 4. 生命周期管理
+
+```tsx
+useEffect(() => {
+  // 订阅
+  const subscription = subscribeEvent('data-update', handleDataUpdate);
+
+  // 定时器
+  const timer = setInterval(() => {
+    fetchData();
+  }, 5000);
+
+  // 清理函数
+  return () => {
+    unsubscribeEvent(subscription);
+    clearInterval(timer);
+  };
+}, []);
+```
+
+---
+
+## 📚 延伸阅读
+
+- **Page/Widget 基础示例** → [../examples/page-widget-basics.md](../examples/page-widget-basics.md)
+- **常用模式** → [../examples/common-patterns.md](../examples/common-patterns.md)
+- **登录与授权约定入口** → [auth.md](./auth.md)
+- **失效卡片** → [expired-widget.md](./expired-widget.md)
+- **豆包应用插件的端能力 API 使用配方** → [../examples/doubao-agentic-service-api-recipes.md](../examples/doubao-agentic-service-api-recipes.md)
+- **Page 组件配方** → [../examples/page-widget-recipes.md](../examples/page-widget-recipes.md)
+- **最佳实践** → [best-practices.md](./best-practices.md)
+- **性能优化** → [performance-optimization.md](./performance-optimization.md)
+- **故障排查** → [troubleshooting.md](./troubleshooting.md)
+- **Framework 核心入口、生命周期和 Hooks** → [../framework/core.md](../framework/core.md)
+- **豆包应用插件的端能力 API 速查** → [../doubao-agentic-service-api/quick-reference.md](../doubao-agentic-service-api/quick-reference.md)