@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/examples/open-api-recipes.md

@@ -0,0 +1,203 @@
+# Open API 使用配方
+
+本文件放高频端能力的组合示例。完整参数和返回类型以 [Open API 目录](../reference/open-api/README.md)
+和 `@doubao-apps/framework/api` 类型提示为准；这里重点展示端能力如何和 Page / Widget、生命周期、事件处理、状态反馈组合使用。
+
+---
+
+## 使用原则
+
+- Open API 从 `@doubao-apps/framework/api` 导入。
+- 首次加载或随输入变化的调用放在 `useEffect` 或生命周期钩子中。
+- 用户触发的调用放在事件处理函数中。
+- Page / Widget 默认用 `getViewData<T>()` 声明输入类型。
+- `request` 不支持泛型参数，不要写 `request<T>()`；业务返回类型在 `response.data` 上做类型收窄或断言。
+- 异步调用提供 loading、success、error 等可见状态。
+
+---
+
+## 位置能力 Widget
+
+`getLocation` 放在 `useEffect` 中调用，不要在 `render()` 中直接调用。
+
+```tsx
+import { defineWidget, getViewData, useEffect, useState } from '@doubao-apps/framework';
+import { getLocation } from '@doubao-apps/framework/api';
+import './index.scss';
+
+interface LocationCardData {
+  title?: string;
+}
+
+interface LocationInfo {
+  latitude: number;
+  longitude: number;
+  accuracy: number;
+  speed: number;
+  timestamp: string;
+}
+
+function LocationCard() {
+  const viewData = getViewData<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;
+    };
+  }, []);
+
+  return (
+    <view className="location-card">
+      <text className="location-title">{viewData.title || '位置能力'}</text>
+      {status === 'loading' && <text className="location-status">定位中...</text>}
+      {status === 'error' && <text className="location-error">{error}</text>}
+      {status === 'success' && location && (
+        <view className="location-result">
+          <text>纬度: {location.latitude}</text>
+          <text>经度: {location.longitude}</text>
+          <text>精度: {location.accuracy}</text>
+          <text>速度: {location.speed}</text>
+          <text>时间: {location.timestamp}</text>
+        </view>
+      )}
+    </view>
+  );
+}
+
+export default defineWidget({
+  render() {
+    return <LocationCard />;
+  }
+});
+```
+
+---
+
+## Storage 状态持久化 Widget
+
+`getStorage` 放在 `useEffect` 中读取初始状态，`setStorage` 放在事件处理函数中保存用户操作。Storage 支持
+JSON 可序列化数据，读取时用泛型声明 `result.data` 的业务类型。
+
+```tsx
+import { defineWidget, getViewData, useEffect, useState } from '@doubao-apps/framework';
+import { getStorage, setStorage } from '@doubao-apps/framework/api';
+import './index.scss';
+
+interface StorageCounterData {
+  title?: string;
+  storageKey?: string;
+  defaultValue?: number;
+}
+
+interface StoredCounter {
+  value: number;
+  updatedAt: string;
+}
+
+function StorageCounter() {
+  const viewData = getViewData<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');
+    }
+  };
+
+  return (
+    <view className="storage-counter">
+      <text className="storage-title">{viewData.title || '本地计数'}</text>
+      <text className="storage-value">{count}</text>
+      <button onClick={() => setCount(current => current + 1)}>增加</button>
+      <button onClick={handleSave}>保存</button>
+      {status === 'loading' && <text>读取中...</text>}
+      {status === 'saving' && <text>保存中...</text>}
+      {status === 'saved' && <text>已保存</text>}
+      {error && <text className="storage-error">{error}</text>}
+    </view>
+  );
+}
+
+export default defineWidget({
+  render() {
+    return <StorageCounter />;
+  }
+});
+```

package/dist/skills/doubao-apps-dev/references/guides/component-development.md

@@ -8,16 +8,16 @@ Page（页面）和 Widget（卡片）组件的完整开发指南。
 
 ### App 配置、可选入口与多级目录
 
-`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`。`pages` / `widgets` 是可选的显式入口配置。
+`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`，`appId` 使用开放平台 `db_xxxxxx` 风格。`pages` / `widgets` 是可选的显式入口配置。
 一级页面目录会自动发现，例如 `src/pages/home/index.tsx` 会产出 `pageId: 'home'`；不配置到 `pages` 时仍可构建，
 但 `title`、`description` 等页面 metadata 为空。
 
-需要补 metadata、固定首页顺序或声明多级目录时，再配置 `pages` 数组。`pages` 是有序数组，第一项会作为应用首页
-（最终 manifest 的 `appletEntry`）；如果希望 `home` 是默认打开页面，把 `pages/home/index` 放在第一项。
-数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
+需要补 metadata、固定首页顺序或声明多级目录时，再配置 `pages` 数组。数组第一项会作为应用首页
+（最终 manifest 的 `appletEntry`）。显式声明入口时，entry 写到 `index`，例如 `'pages/home/index'`，
+不要省略入口文件名。
 
 如果不配置 `pages` / `widgets`，一级 Page / Widget 仍会按目录产出；Page / Widget 的默认 ID 取入口最后一级目录名，
-页面/卡片 metadata 字段为空，Widget 的 `boxType` 默认为 `inbox`。没有显式 `pages` 顺序时，首页入口会走构建兜底/历史默认
+页面/卡片 metadata 字段为空，Widget 的 `boxType` 默认为 `inbox`。没有显式 `pages` 顺序时，默认首页入口为
 `index`；首页不是 `index` 时建议配置 `pages` 第一项。
 
 多级目录不会被一级扫描自动发现，例如 `src/pages/account/demo/index.tsx` 需要显式写
@@ -27,7 +27,7 @@ Page（页面）和 Widget（卡片）组件的完整开发指南。
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   pages: [
     'pages/home/index',
@@ -48,6 +48,10 @@ export default defineAppConfig({
 import { definePage, getViewData, useState, useEffect } from '@doubao-apps/framework';
 import './index.scss';
 
+interface PageViewData {
+  title: string;
+}
+
 export default definePage({
   // 1. 生命周期钩子
   onShow() {
@@ -67,8 +71,8 @@ export default definePage({
 
   // 2. 渲染函数
   render() {
-    // 使用 getViewData() 和 getViewContext() 获取数据和上下文
-    const viewData = getViewData();
+    // 使用 getViewData<T>() 和 getViewContext() 获取数据和上下文
+    const viewData = getViewData<PageViewData>();
 
     return <MyPageComponent {...viewData} />;
   }
@@ -148,22 +152,22 @@ import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
 
 // 保留当前页面，打开新页面
 navigateTo({
-  url: 'user-detail?userId=123&tab=profile'
+  url: '/pages/user-detail/index?userId=123&tab=profile'
 });
 
 // 替换当前页面
 redirectTo({
-  url: 'settings'
+  url: '/pages/settings/index'
 });
 
 // 关闭所有页面并回到首页
 reLaunch({
-  url: 'home'
+  url: '/pages/home/index'
 });
 ```
 
-`url` 在常规页面跳转里填写页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
-`src/pages/detail/index.tsx` 默认为 `detail`。
+`url` 在常规页面跳转里填写目标 Page 路径，通常和 `src/pages/<page-name>/index.tsx` 对应，例如
+`/pages/detail/index`。
 
 页面内可继续通过 `getViewData<PageViewData>()` 读取 URL 中传入的参数。
 
@@ -175,28 +179,33 @@ reLaunch({
 import { useEffect, useState } from '@doubao-apps/framework';
 import { request } from '@doubao-apps/framework/api';
 
+interface UserData {
+  name?: string;
+}
+
 function MyPage({ userId }: { userId: string }) {
-  const [data, setData] = useState(null);
+  const [data, setData] = useState<UserData | null>(null);
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
+  const [error, setError] = useState('');
 
   useEffect(() => {
     const fetchData = async () => {
       try {
         setLoading(true);
+        setError('');
         const result = await request({
-          url: `/api/users/${userId}`,
+          url: `https://api.example.com/users/${userId}`,
           method: 'GET'
         });
-        setData(result.data);
+        setData(result.data as UserData);
       } catch (err) {
-        setError(err.message);
+        setError(err instanceof Error ? err.message : '加载失败');
       } finally {
         setLoading(false);
       }
     };
 
-    fetchData();
+    void fetchData();
   }, [userId]);
 
   if (loading) return <text>加载中...</text>;
@@ -224,7 +233,7 @@ function FormPage() {
     try {
       setSubmitting(true);
       await request({
-        url: '/api/submit',
+        url: 'https://api.example.com/submit',
         method: 'POST',
         data: formData
       });
@@ -266,15 +275,16 @@ function FormPage() {
 一级 Widget 目录会自动发现，例如 `src/widgets/my-widget/index.tsx` 会产出 `widgetId: 'my-widget'`。不配置
 `widgets` 时仍可构建，但 `name`、`description` 等 metadata 为空，`boxType` 默认是 `inbox`。
 
-需要补 metadata 或声明多级目录时，再配置 `widgets` 数组。多级目录如 `src/widgets/order/detail/index.tsx`
-需要显式写 `entry: 'widgets/order/detail/index'`；如果不配置 `id`，默认 `widgetId` 是最后一级目录名 `detail`。
-数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
+需要补 metadata 或声明多级目录时，再配置 `widgets` 数组。显式声明入口时，entry 写到 `index`，例如
+`'widgets/my-widget/index'`，不要省略入口文件名。
+多级目录如 `src/widgets/order/detail/index.tsx` 需要显式写 `'widgets/order/detail/index'`。
+如果不配置 `id`，默认 `widgetId` 是最后一级目录名 `detail`。
 
 ```ts
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   widgets: [
     'widgets/simple-card/index',
@@ -353,7 +363,7 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   widgets: [
     {
@@ -390,7 +400,7 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  appId: 'com.example.my-doubao-app',
+  appId: 'db_xxxxxx',
   name: '我的豆包应用',
   widgets: [
     {
@@ -464,29 +474,38 @@ export default defineWidget({
 import { useEffect, useState } from '@doubao-apps/framework';
 import { request } from '@doubao-apps/framework/api';
 
+interface WeatherInfo {
+  city: string;
+  temperature: number;
+  condition: string;
+}
+
 function WeatherWidget({ city }: { city: string }) {
-  const [weather, setWeather] = useState(null);
+  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: `/api/weather?city=${city}`,
+          url: `https://api.example.com/weather?city=${city}`,
           method: 'GET'
         });
-        setWeather(response.data);
+        setWeather(response.data as WeatherInfo);
       } catch (err) {
-        console.error('获取天气失败:', err);
+        setError(err instanceof Error ? err.message : '获取天气失败');
       } finally {
         setLoading(false);
       }
     };
 
-    fetchWeather();
+    void fetchWeather();
   }, [city]);
 
   if (loading) return <text>加载中...</text>;
+  if (error) return <text>{error}</text>;
   if (!weather) return <text>无数据</text>;
 
   return (
@@ -533,7 +552,7 @@ import { navigateTo } from '@doubao-apps/framework/api';
 function ActionWidget({ itemId }: { itemId: string }) {
   const handleViewDetail = () => {
     navigateTo({
-      url: `item-detail?id=${itemId}`
+      url: `/pages/item-detail/index?id=${itemId}`
     });
   };
 
@@ -693,7 +712,7 @@ function MyPage() {
 ```typescript
 import { getViewData } from '@doubao-apps/framework';
 
-function getViewData<T extends Record<string, any>>(): T
+function getViewData<T extends Record<string, unknown>>(): T
 ```
 
 **使用场景**：
@@ -714,7 +733,7 @@ export default defineWidget({
   },
 
   render() {
-    // render 函数中使用 getViewData() 获取数据
+    // render 函数中使用 getViewData<T>() 获取数据
     const viewData = getViewData<TodoData>();
     return <view>{viewData.tasks.length} 个任务</view>;
   }
@@ -743,23 +762,23 @@ function WeatherWidget() {
 ```
 
 **注意事项**：
-- ✅ **推荐**：在 render 函数中使用 `getViewData()` 获取数据
-- ✅ **推荐**：在生命周期钩子和自定义函数中使用 `getViewData()` 获取数据
+- ✅ **推荐**：在 render 函数中使用 `getViewData<T>()` 获取数据
+- ✅ **推荐**：在生命周期钩子和自定义函数中使用 `getViewData<T>()` 获取数据
 - 🔒 **类型安全**：始终定义明确的 TypeScript 接口并传递给泛型参数
 
-### 使用 `getViewData()` 和 `getViewContext()`
+### 使用 `getViewData<T>()` 和 `getViewContext()`
 
-render 函数不再通过参数接收 viewData 和 context，请使用以下方法获取数据和上下文：
+render 函数内通过以下 API 获取 viewData 和 context：
 
 **推荐做法**：
 ```tsx
-// ✅ 推荐：render 函数中使用 getViewData()
+// ✅ 推荐：render 函数中使用 getViewData<T>()
 render() {
   const viewData = getViewData<WeatherData>();
   return <text>{viewData.city}: {viewData.temperature}°C</text>;
 }
 
-// ✅ 推荐：生命周期钩子中使用 getViewData()
+// ✅ 推荐：生命周期钩子中使用 getViewData<T>()
 onMounted() {
   const viewData = getViewData<WeatherData>();
   // 处理数据...
@@ -813,8 +832,9 @@ try {
   const result = await someAsyncOperation();
   setData(result);
 } catch (err) {
+  const message = err instanceof Error ? err.message : '未知错误';
   // 记录错误
-  console.error('操作失败:', err);
+  console.error('操作失败:', message);
 
   // 显示用户友好的错误消息
   setError('操作失败，请重试');
@@ -822,7 +842,7 @@ try {
   // 可选：上报错误
   reportAppLog({
     level: 'error',
-    message: err.message,
+    message,
     context: { operation: 'someAsyncOperation' }
   });
 }
@@ -885,6 +905,10 @@ useEffect(() => {
 
 - **组件示例** → [../examples/component-basics.md](../examples/component-basics.md)
 - **常用模式** → [../examples/common-patterns.md](../examples/common-patterns.md)
+- **MCP UI 约定入口** → [mcp-ui.md](./mcp-ui.md)
+- **失效卡片** → [expired-widget.md](./expired-widget.md)
+- **Open API 使用配方** → [../examples/open-api-recipes.md](../examples/open-api-recipes.md)
+- **内置组件使用配方** → [../examples/component-recipes.md](../examples/component-recipes.md)
 - **最佳实践** → [best-practices.md](./best-practices.md)
 - **性能优化** → [performance-optimization.md](./performance-optimization.md)
 - **故障排查** → [troubleshooting.md](./troubleshooting.md)

package/dist/skills/doubao-apps-dev/references/guides/expired-widget.md

@@ -0,0 +1,113 @@
+# 失效卡片
+
+`expiredWidget()` 用于把已经过期的业务 Widget 实例更新成框架内置失效卡，通常在业务 Widget 内容失效后调用。
+
+`__doubao_apps__expired-widget` 是框架内置虚拟 Widget，不需要在 `src/widgets` 中创建同名目录，也不要手动注册到
+`src/app.config.ts`。
+
+`expiredWidget()` 的 `url` 是用户点击失效卡后跳转的目标 Page 路径或 schema。
+
+---
+
+## 当前 Widget 标记为失效
+
+在 Widget 内部可以通过 `getWidgetInstanceId()` 获取当前实例 ID，再调用 `expiredWidget()`。`getWidgetInstanceId()`
+只在 Widget 环境有值，在 Page 中通常返回 `undefined`。
+
+```ts
+import { getWidgetInstanceId } from '@doubao-apps/framework';
+import { expiredWidget } from '@doubao-apps/framework/api';
+
+async function markCurrentWidgetExpired() {
+  const widgetInstanceId = getWidgetInstanceId();
+  if (!widgetInstanceId) {
+    return;
+  }
+
+  await expiredWidget({
+    widgetInstanceId,
+    url: '/pages/detail/index?from=expired',
+    title: '内容已失效',
+    detailText: '点击查看最新内容'
+  });
+}
+```
+
+---
+
+## 从 Widget 打开 Page 并传递 widgetInstanceId
+
+如果需要在 Page 中处理过期逻辑，先在 Widget 中拿到 `widgetInstanceId`，通过页面跳转参数传给目标 Page。
+
+```tsx
+import { defineWidget, getWidgetInstanceId } from '@doubao-apps/framework';
+import { navigateTo } from '@doubao-apps/framework/api';
+
+function OrderWidget() {
+  const handleOpenDetail = async () => {
+    const widgetInstanceId = getWidgetInstanceId();
+    const query = widgetInstanceId ? `?widgetInstanceId=${encodeURIComponent(widgetInstanceId)}` : '';
+
+    await navigateTo({
+      url: `/pages/order-detail/index${query}`
+    });
+  };
+
+  return (
+    <view className="order-widget">
+      <button text="查看详情" onClick={handleOpenDetail} />
+    </view>
+  );
+}
+
+export default defineWidget({
+  render() {
+    return <OrderWidget />;
+  }
+});
+```
+
+---
+
+## Page 中读取 widgetInstanceId 并标记失效
+
+Page 不直接拥有 Widget 实例 ID。需要从 `getViewData<T>()` 读取上一步传入的 `widgetInstanceId`，或通过业务数据、通信等方式拿到目标实例 ID。
+
+```tsx
+import { definePage, getViewData } from '@doubao-apps/framework';
+import { expiredWidget } from '@doubao-apps/framework/api';
+import './index.scss';
+
+interface OrderDetailPageData {
+  widgetInstanceId?: string;
+}
+
+function OrderDetailPage() {
+  const viewData = getViewData<OrderDetailPageData>();
+
+  const handleMarkExpired = async () => {
+    if (!viewData.widgetInstanceId) {
+      return;
+    }
+
+    await expiredWidget({
+      widgetInstanceId: viewData.widgetInstanceId,
+      url: '/pages/order-detail/index?from=expired',
+      title: '订单状态已更新',
+      detailText: '点击查看最新订单状态'
+    });
+  };
+
+  return (
+    <view className="order-detail-page">
+      <button text="标记原卡片失效" disabled={!viewData.widgetInstanceId} onClick={handleMarkExpired} />
+    </view>
+  );
+}
+
+export default definePage({
+  render() {
+    return <OrderDetailPage />;
+  }
+});
+```