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

package/dist/skills/doubao-plugin-app/references/frontend/examples/doubao-agentic-service-api-recipes.md

@@ -0,0 +1,209 @@
+# 豆包应用插件的端能力 API 使用配方
+
+本文件放高频豆包应用插件的端能力 API 的组合示例。这些 API 也称 Open API，代码统一从
+`@doubao-dev/framework/api` 导入。完整参数和返回类型以 [豆包应用插件的端能力 API 目录](../doubao-agentic-service-api/groups.md)
+和 IDE 类型提示为准；这里重点展示端能力如何和 Page / Widget、生命周期、事件处理、状态反馈组合使用。
+Widget 示例只展示端能力和状态管理组合，卡片展示层使用 [Widget 模板库](../widget-templates/overview.md) 中的模板。
+
+---
+
+## 使用原则
+
+- 豆包应用插件的端能力 API 从 `@doubao-dev/framework/api` 导入。
+- 首次加载或随输入变化的调用放在 `useEffect` 或生命周期钩子中。
+- 用户触发的调用放在事件处理函数中。
+- Page / Widget 默认用 `useViewData<T>()` 声明输入类型。
+- `request` 不支持泛型参数，不要写 `request<T>()`；业务返回类型在 `response.data` 上做类型收窄或断言。
+- 异步调用提供 loading、success、error 等可见状态。
+
+---
+
+## 位置能力 Widget
+
+`getLocation` 放在 `useEffect` 中调用，不要在 `render()` 中直接调用。
+
+```tsx
+import { useEffect, useState, useViewData } from '@doubao-dev/framework';
+import { getLocation } from '@doubao-dev/framework/api';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface LocationCardData {
+  title?: string;
+}
+
+interface LocationInfo {
+  latitude: number;
+  longitude: number;
+  accuracy: number;
+  speed: number;
+  timestamp: string;
+}
+
+export default function LocationCard() {
+  const viewData = useViewData<LocationCardData>();
+  const [status, setStatus] = useState<'loading' | 'success' | 'error'>('loading');
+  const [location, setLocation] = useState<LocationInfo | null>(null);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    let active = true;
+
+    const loadLocation = async () => {
+      try {
+        setStatus('loading');
+        setError('');
+        const result = await getLocation();
+        if (!active) {
+          return;
+        }
+        setLocation({
+          latitude: result.latitude,
+          longitude: result.longitude,
+          accuracy: result.accuracy,
+          speed: result.speed,
+          timestamp: result.timestamp
+        });
+        setStatus('success');
+      } catch (caughtError) {
+        if (!active) {
+          return;
+        }
+        setError(caughtError instanceof Error ? caughtError.message : '定位失败');
+        setStatus('error');
+      }
+    };
+
+    void loadLocation();
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  if (status === 'loading') {
+    return <ContentCard items={[{ key: 'status', title: viewData.title || '位置能力', subtitle: '定位中...' }]} />;
+  }
+
+  if (status === 'error') {
+    return <ContentCard items={[{ key: 'error', title: viewData.title || '位置能力', subtitle: error }]} />;
+  }
+
+  const items: ContentCardItem[] = location
+    ? [
+        { key: 'lat', title: '纬度', subtitle: location.latitude },
+        { key: 'lng', title: '经度', subtitle: location.longitude }
+      ]
+    : [{ key: 'empty', title: viewData.title || '位置能力', subtitle: '暂无数据' }];
+
+  return <ContentCard header={{ actionText: viewData.title || '位置能力' }} items={items} />;
+}
+```
+
+---
+
+## Storage 状态持久化 Widget
+
+`getStorage` 放在 `useEffect` 中读取初始状态，`setStorage` 放在事件处理函数中保存用户操作。Storage 支持
+JSON 可序列化数据，读取时用泛型声明 `result.data` 的业务类型。
+
+```tsx
+import { useEffect, useState, useViewData } from '@doubao-dev/framework';
+import { getStorage, setStorage } from '@doubao-dev/framework/api';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface StorageCounterData {
+  title?: string;
+  storageKey?: string;
+  defaultValue?: number;
+}
+
+interface StoredCounter {
+  value: number;
+  updatedAt: string;
+}
+
+export default function StorageCounter() {
+  const viewData = useViewData<StorageCounterData>();
+  const storageKey = viewData.storageKey || 'counter';
+  const defaultCount = viewData.defaultValue ?? 0;
+  const [count, setCount] = useState(defaultCount);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'saving' | 'saved' | 'error'>('loading');
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    let active = true;
+
+    const loadStoredValue = async () => {
+      try {
+        setStatus('loading');
+        setError('');
+        const result = await getStorage<StoredCounter>({ key: storageKey });
+        if (!active) {
+          return;
+        }
+        setCount(typeof result.data.value === 'number' ? result.data.value : defaultCount);
+        setStatus('ready');
+      } catch (caughtError) {
+        if (!active) {
+          return;
+        }
+        setError(caughtError instanceof Error ? caughtError.message : '读取缓存失败，已使用默认值');
+        setStatus('ready');
+      }
+    };
+
+    void loadStoredValue();
+
+    return () => {
+      active = false;
+    };
+  }, [storageKey, defaultCount]);
+
+  const handleSave = async () => {
+    try {
+      setStatus('saving');
+      setError('');
+      await setStorage<StoredCounter>({
+        key: storageKey,
+        data: {
+          value: count,
+          updatedAt: new Date().toISOString()
+        }
+      });
+      setStatus('saved');
+    } catch (caughtError) {
+      setError(caughtError instanceof Error ? caughtError.message : '保存失败');
+      setStatus('error');
+    }
+  };
+
+  const items: ContentCardItem[] = [
+    {
+      key: 'status',
+      title: viewData.title || '本地计数',
+      subtitle: status === 'loading' ? '读取中...' : status === 'saving' ? '保存中...' : status === 'saved' ? '已保存' : '就绪'
+    },
+    ...(error ? [{ key: 'error', title: '错误', subtitle: error }] : []),
+    { key: 'count', title: '当前计数', subtitle: count }
+  ];
+
+  return (
+    <ContentCard
+      items={items}
+      footer={{
+        secondaryActionButton: {
+          text: '保存',
+          loading: status === 'saving',
+          disabled: status === 'loading',
+          onClick: handleSave
+        },
+        primaryActionButton: {
+          text: '增加',
+          disabled: status === 'loading' || status === 'saving',
+          onClick: () => setCount(current => current + 1)
+        }
+      }}
+    />
+  );
+}
+```

package/dist/skills/doubao-plugin-app/references/frontend/examples/page-widget-basics.md

@@ -0,0 +1,368 @@
+# 组件基础示例
+
+> 项目配置：下文 `defineAppConfig` 和 `appId` 示例适用于独立应用项目，沿用其配置要求。Plugin CLI 项目以根目录的 `plugin.json` 为标识，`src/` 位于 `com.doubao/app/` 下；`app.config.ts` 默认导出普通对象，不填写 `appId`，由 CLI 查询注入。配置示例以 `doubao-plugin-app` Skill 的应用开发指南为准，本文的组件、Hooks 和入口 metadata 用法共用。
+
+Page（页面）和 Widget（卡片）组件的基础用法对比。
+
+---
+
+## 📋 核心差异
+
+| 特性 | Page | Widget |
+|------|------|--------|
+| **使用场景** | 全屏页面、九宫格、浮窗 | 聊天流中的卡片 |
+| **定义方式** | 默认导出组件函数 | 默认导出组件函数 |
+| **输入数据** | URL 参数、页面配置 | AI 生成的结构化数据 |
+| **显示位置** | 独立页面/窗口 | 聊天对话中 |
+| **交互方式** | 完整的页面交互 | 卡片内交互 + 消息发送 |
+| **生命周期** | 函数入口使用 `useCreated`, `useMounted`, `useShow`, `useHide`, `useDestroy`, `useError`；对象入口使用对应的 `onXxx` 字段 | 与 Page 相同，函数入口额外支持 `useForeground`, `useBackground`；对象入口使用对应的 `onXxx` 字段 |
+
+---
+
+## 🎯 Page 基础示例
+
+### 用户资料页面
+
+**文件结构**：
+```
+src/pages/user-profile/
+├── index.tsx       # 组件逻辑
+└── index.scss      # 组件样式
+```
+
+### app.config.ts
+
+独立应用项目的 `app.config.ts` 需要配置 `appId` 和 `name`。这里额外配置 `pages` 是为了补充标题和描述；页面使用
+`/pages/user-profile/index` 作为完整路径。
+
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index',
+      title: '用户资料',
+      description: '显示用户个人信息和统计数据'
+    }
+  ]
+});
+```
+
+### index.tsx
+
+```tsx
+import { useEffect, useHide, useShow, useState, useViewData } from '@doubao-dev/framework';
+import './index.scss';
+
+interface UserProfilePageData {
+  userId?: string;
+  title?: string;
+}
+
+interface UserProfile {
+  id: string;
+  name: string;
+  avatar: string;
+  email: string;
+  stats: {
+    posts: number;
+    followers: number;
+    following: number;
+  };
+}
+
+export default function UserProfilePage() {
+  const viewData = useViewData<UserProfilePageData>();
+  const [user, setUser] = useState<UserProfile | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  useShow(() => console.log('页面显示'));
+  useHide(() => console.log('页面隐藏'));
+
+  // 数据获取
+  const fetchUserProfile = async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      // 模拟 API 请求
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      const mockData: UserProfile = {
+        id: viewData.userId || '12345',
+        name: '张三',
+        avatar: 'https://via.placeholder.com/150',
+        email: 'zhangsan@example.com',
+        stats: {
+          posts: 42,
+          followers: 1234,
+          following: 567
+        }
+      };
+
+      setUser(mockData);
+    } catch (err) {
+      setError('加载失败，请重试');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // 编辑按钮
+  const handleEdit = () => {
+    console.log('编辑用户资料');
+  };
+
+  useEffect(() => {
+    void fetchUserProfile();
+  }, [viewData.userId]);
+
+  // 渲染
+  if (loading) {
+    return (
+      <view className="profile-container">
+        <view className="loading">加载中...</view>
+      </view>
+    );
+  }
+
+  if (error) {
+    return (
+      <view className="profile-container">
+        <view className="error">{error}</view>
+        <button onClick={fetchUserProfile}>重试</button>
+      </view>
+    );
+  }
+
+  if (!user) {
+    return null;
+  }
+
+  return (
+    <view className="profile-container">
+      {/* 头部 */}
+      <view className="profile-header">
+        <text className="page-title">{viewData.title || '用户资料'}</text>
+        <image className="avatar" src={user.avatar} />
+        <text className="name">{user.name}</text>
+        <text className="email">{user.email}</text>
+        <button className="edit-btn" onClick={handleEdit}>
+          编辑资料
+        </button>
+      </view>
+
+      {/* 数据统计 */}
+      <view className="profile-stats">
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.posts}</text>
+          <text className="stat-label">帖子</text>
+        </view>
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.followers}</text>
+          <text className="stat-label">关注者</text>
+        </view>
+        <view className="stat-item">
+          <text className="stat-value">{user.stats.following}</text>
+          <text className="stat-label">关注中</text>
+        </view>
+      </view>
+    </view>
+  );
+}
+```
+
+### index.scss
+
+```scss
+.profile-container {
+  padding: 32px;
+  background-color: #f5f5f5;
+
+  .loading,
+  .error {
+    text-align: center;
+    padding: 40px;
+    font-size: 28px;
+    color: #666;
+  }
+
+  .profile-header {
+    background-color: #fff;
+    border-radius: 16px;
+    padding: 40px;
+    text-align: center;
+    margin-bottom: 32px;
+
+    .page-title {
+      display: block;
+      font-size: 32px;
+      font-weight: 600;
+      color: #222;
+      margin-bottom: 24px;
+    }
+
+    .avatar {
+      width: 160px;
+      height: 160px;
+      border-radius: 80px;
+      margin-bottom: 24px;
+    }
+
+    .name {
+      font-size: 36px;
+      font-weight: bold;
+      color: #333;
+      margin-bottom: 12px;
+    }
+
+    .email {
+      font-size: 28px;
+      color: #666;
+      margin-bottom: 24px;
+    }
+
+    .edit-btn {
+      padding: 16px 48px;
+      background-color: #1890ff;
+      color: #fff;
+      border-radius: 8px;
+      font-size: 28px;
+    }
+  }
+
+  .profile-stats {
+    display: flex;
+    justify-content: space-around;
+    background-color: #fff;
+    border-radius: 16px;
+    padding: 32px;
+
+    .stat-item {
+      text-align: center;
+
+      .stat-value {
+        font-size: 36px;
+        font-weight: bold;
+        color: #333;
+        margin-bottom: 8px;
+      }
+
+      .stat-label {
+        font-size: 24px;
+        color: #999;
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🎴 Widget 基础示例
+
+Widget 卡片内容和布局必须使用 [Widget 模板库](../widget-templates/overview.md) 中的 `@doubao-dev/template` 模板。先根据业务场景在模板库中选型，
+再在入口组件中读取 `viewData` 并直接返回模板组件。
+
+### 列表卡片
+
+**文件结构**：
+```
+src/widgets/recommend-list/
+├── index.tsx       # 组件逻辑
+```
+
+### index.tsx
+
+```tsx
+import { useDestroy, useMounted, useViewData } from '@doubao-dev/framework';
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+interface RecommendListData {
+  items: ContentCardItem[];
+  actionText?: string;
+}
+
+export default function RecommendList() {
+  const viewData = useViewData<RecommendListData>();
+  useMounted(() => console.log('卡片挂载'));
+  useDestroy(() => console.log('卡片销毁'));
+
+  return (
+    <ContentCard
+      items={viewData.items}
+      footer={
+        viewData.actionText
+          ? {
+              primaryActionButton: {
+                text: viewData.actionText,
+                onClick: () => console.log('查看更多')
+              }
+            }
+          : undefined
+      }
+    />
+  );
+}
+```
+
+---
+
+## 🔑 关键要点
+
+### Page 开发要点
+
+1. **完整的页面生命周期**
+   - `useShow()` - 页面显示时调用
+   - `useHide()` - 页面隐藏时调用
+   - `useDestroy()` - 页面销毁时调用
+
+2. **页面配置（可选 pages）**
+   - 一级目录不写进 `pages` 也会自动发现，默认 `id` 是目录名
+   - 需要 `title`、`description`、固定首页或多级目录时再配置
+   - 多级目录需要显式写 `entry`
+
+3. **状态管理**
+   - 使用 React Hooks（useState, useEffect）
+   - 处理加载、错误、数据状态
+
+4. **用户交互**
+   - 按钮点击、表单提交
+   - 页面跳转、数据更新
+
+### Widget 开发要点
+
+1. **卡片生命周期**
+   - `useShow()` / `useHide()` - 卡片显示/隐藏
+   - `useForeground()` / `useBackground()` - 应用前后台切换
+   - `useMounted()` / `useDestroy()` - 挂载/销毁
+
+2. **ViewData 定义**
+   - 使用 TypeScript 类型定义 `useViewData<T>()` 的 viewData 结构
+   - 数据结构优先贴近 `@doubao-dev/template` 的模板 props 或列表项类型
+   - 对可选字段和空数据做兜底处理
+   - 避免直接使用 `any`
+
+3. **卡片类型 (boxType)**
+   - `inbox` - 普通卡片
+   - `full_box` - 全宽卡片
+   - `custom_box` - 背景、圆角和描边由业务内容设置，标题栏仍遵循 `titleType`
+
+4. **消息交互**
+   - 接收 AI 传入的数据
+   - 可以发送消息回 Bot
+   - 支持通过模板按钮和事件进行卡片内交互
+
+---
+
+## 📚 延伸阅读
+
+- **组件开发完整指南** → [../guides/component-development.md](../guides/component-development.md)
+- **常用开发模式** → [./common-patterns.md](./common-patterns.md)
+- **豆包应用插件的端能力 API 使用配方** → [./doubao-agentic-service-api-recipes.md](./doubao-agentic-service-api-recipes.md)
+- **Page 组件配方** → [./page-widget-recipes.md](./page-widget-recipes.md)
+- **Framework 核心入口、生命周期和 Hooks** → [../framework/core.md](../framework/core.md)
+- **豆包应用插件的端能力 API 速查** → [../doubao-agentic-service-api/quick-reference.md](../doubao-agentic-service-api/quick-reference.md)

package/dist/skills/doubao-plugin-app/references/frontend/examples/page-widget-recipes.md

@@ -0,0 +1,65 @@
+# Page 组件配方
+
+本文件放内置组件和 Page 状态组合的示例。组件的完整 props 和事件签名见 [组件 API](../components/overview.md)；这里重点展示受控状态、事件处理和保存态如何组合。
+Widget 卡片整体布局和操作区必须使用 [Widget 模板库](../widget-templates/overview.md) 中的模板，不手写卡片布局。
+
+---
+
+## Settings Page
+
+内置组件用小写标签直接写 JSX，不要 import 组件。需要按钮、开关和滑块时，三个标签都要直接出现在 TSX 中：
+`button` 用 `onClick`；`switch` / `slider` 的 `onChange` 直接接收值，不是事件对象。
+
+```tsx
+import { useState, useViewData } from '@doubao-dev/framework';
+import './index.scss';
+
+interface SettingsPanelData {
+  title: string;
+  enabled: boolean;
+  volume: number;
+}
+
+export default function SettingsPanel() {
+  const viewData = useViewData<SettingsPanelData>();
+  const [enabled, setEnabled] = useState(viewData.enabled);
+  const [volume, setVolume] = useState(viewData.volume);
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useState('');
+
+  const handleSave = async () => {
+    setSaving(true);
+    setMessage('');
+    try {
+      await Promise.resolve();
+      setMessage(`已保存: ${enabled ? '开启' : '关闭'} / ${volume}`);
+    } catch {
+      setMessage('保存失败，请重试');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <view className="settings-panel">
+      <text className="settings-title">{viewData.title}</text>
+      <button
+        text={saving ? '保存中' : '保存'}
+        type="primary"
+        loading={saving}
+        disabled={saving}
+        onClick={handleSave}
+      />
+      <switch checked={enabled} onChange={(checked: boolean) => setEnabled(checked)} />
+      <slider
+        value={volume}
+        min={0}
+        max={100}
+        showValue={true}
+        onChange={(nextVolume: number) => setVolume(nextVolume)}
+      />
+      {message && <text className="settings-message">{message}</text>}
+    </view>
+  );
+}
+```