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

package/dist/skills/doubao-plugin-app/references/frontend/framework/core.md

@@ -0,0 +1,283 @@
+# Framework 核心入口、生命周期和 Hooks
+
+> 项目配置：下文 `defineAppConfig` 和 `appId` 示例适用于独立应用项目，沿用其配置要求。Plugin CLI 项目以根目录的 `plugin.json` 为标识，`src/` 位于 `com.doubao/app/` 下；`app.config.ts` 默认导出普通对象，不填写 `appId`，由 CLI 查询注入。配置示例以 `doubao-plugin-app` Skill 的应用开发指南为准，本文的组件、Hooks 和入口 metadata 用法共用。
+
+本文件只覆盖 `@doubao-dev/framework` 和 `@doubao-dev/framework/config` 的开发范式：
+App / Page / Widget 入口、生命周期、Hooks、viewData 和 `app.config.ts` 配置。
+
+豆包应用插件的端能力 API（也称 Open API，例如网络、Storage、位置、路由、Toast、模型上下文等）从
+`@doubao-dev/framework/api` 导入，不在本文件展开。只要代码要从该路径导入 API，必须先读
+[豆包应用插件的端能力 API 速查](../doubao-agentic-service-api/quick-reference.md) 和 [分组目录](../doubao-agentic-service-api/groups.md)。
+
+---
+
+## 导入边界
+
+| 能力 | 导入路径 | 本文件是否展开 |
+|-----|----------|----------------|
+| 入口定义、Hooks、viewData | `@doubao-dev/framework` | 是 |
+| App 配置、入口 metadata | `@doubao-dev/framework/config` | 是 |
+| 网络、Storage、位置、路由、Toast、模型上下文等端能力 | `@doubao-dev/framework/api` | 否，见 `../doubao-agentic-service-api/` |
+
+不要从 `react` 直接导入 Hooks；在豆包应用插件代码里使用 `@doubao-dev/framework` 导出的 Hooks。
+
+---
+
+## 入口定义
+
+| 入口 | 文件位置 | 用途 |
+|-----|----------|------|
+| `defineApp()` | `src/app.ts` | 定义应用入口和 App 生命周期 |
+| 默认导出组件函数 | `src/pages/<page-name>/index.tsx` | 推荐的 Page（全屏页面）入口 |
+| 默认导出组件函数 | `src/widgets/<widget-name>/index.tsx` | 推荐的 Widget（聊天卡片）入口 |
+| 默认导出组件函数 | `src/auth/login-page/index.tsx` | 推荐的自定义登录页入口；没有 `src/auth` 入口时旧路径 `src/mcp-ui/mcp-login-page/index.tsx` 继续兼容 |
+
+Page / Widget 的名称、标题、描述、`boxType` 等 metadata 写在 `src/app.config.ts`，不要写到
+源码入口。Page / Widget 直接默认导出组件函数，并在组件内使用生命周期 Hooks。
+
+`src/auth/login-page/index.tsx` 与兼容的 `mcp-login-page` 约定路径会由构建工具自动注入登录页固定 metadata。
+已有 `defineLoginPage()` 对象入口无需迁移；新登录页不要使用其他目录名。
+
+### Page 示例
+
+```tsx
+import { useMounted, useState, useViewData } from '@doubao-dev/framework';
+import './index.scss';
+
+interface DetailPageData {
+  id: string;
+  title?: string;
+}
+
+export default function DetailPage() {
+  const viewData = useViewData<DetailPageData>();
+  const [selected, setSelected] = useState(false);
+  useMounted(() => console.log('detail page mounted'));
+
+  return (
+    <view className="detail-page">
+      <text className="title">{viewData.title || '详情'}</text>
+      <text className="id">{viewData.id}</text>
+      <button text={selected ? '已选择' : '选择'} onClick={() => setSelected(true)} />
+    </view>
+  );
+}
+```
+
+### Widget 示例
+
+Widget 卡片展示层必须使用 [Widget 模板库](../widget-templates/overview.md)。本文件只展示 Framework 入口形态。
+
+```tsx
+import { useViewData } from '@doubao-dev/framework';
+import { InfoListTemplate, type InfoListTemplateProps } from '@doubao-dev/template';
+
+interface ProductWidgetData {
+  title: string;
+  items: InfoListTemplateProps['items'];
+}
+
+export default function ProductWidget() {
+  const viewData = useViewData<ProductWidgetData>();
+
+  return <InfoListTemplate title={viewData.title} items={viewData.items} />;
+}
+```
+
+---
+
+## App 生命周期
+
+`defineApp()` 放在 `src/app.ts`，只负责应用级生命周期。App metadata 写在 `src/app.config.ts`。
+
+| 钩子 | 触发时机 | 常见用途 |
+|------|----------|----------|
+| `onLaunch()` | 应用启动 | 初始化全局状态、注册全局监听 |
+| `onPageOpened({ viewId })` | Page 打开 | 记录页面打开事件、调试 viewId |
+| `onForeground()` | 应用进入前台 | 恢复全局订阅、刷新全局状态 |
+| `onBackground()` | 应用进入后台 | 暂停任务、保存状态 |
+| `onDestroy()` | 应用销毁 | 清理全局资源 |
+| `onError(error)` | 生命周期或工具调用报错 | 兜底上报、错误隔离 |
+
+```tsx
+import { defineApp } from '@doubao-dev/framework';
+
+export default defineApp({
+  onLaunch() {
+    console.log('app launched');
+  },
+  onPageOpened({ viewId }) {
+    console.log('page opened', viewId);
+  },
+  onForeground() {
+    console.log('app foreground');
+  },
+  onBackground() {
+    console.log('app background');
+  },
+  onDestroy() {
+    console.log('app destroyed');
+  },
+  onError(error) {
+    console.error(error);
+  }
+});
+```
+
+---
+
+## Page / Widget 生命周期
+
+函数入口使用生命周期 Hooks；对象入口继续支持对应的 `onXxx` 字段：
+
+| Hook / 对象字段 | 触发时机 | 常见用途 |
+|------|----------|----------|
+| `useCreated()` / `onCreated()` | View 创建时 | 初始化非渲染数据结构 |
+| `useMounted()` / `onMounted()` | 首次渲染后，只触发一次 | 首次加载、订阅、启动一次性任务 |
+| `useShow()` / `onShow()` | 首次显示或从隐藏恢复 | 刷新可见数据、恢复轮询 |
+| `useHide()` / `onHide()` | View 隐藏 | 暂停任务、保存草稿 |
+| `useDestroy()` / `onDestroy()` | View 销毁 | 清理订阅、计时器和外部资源 |
+| `useError()` / `onError()` | View 生命周期报错 | 错误兜底和上报 |
+
+Widget 额外支持：
+
+| 钩子 | 触发时机 | 常见用途 |
+|------|----------|----------|
+| `useForeground()` / `onForeground()` | 应用回到前台或设备解锁 | 恢复卡片可见内容 |
+| `useBackground()` / `onBackground()` | 应用进入后台或设备锁屏 | 暂停卡片任务 |
+
+异步端能力不要直接写在组件函数或对象入口的 `render()` 中；首次加载放在 `useEffect` / `useMounted()`，用户动作放在事件处理函数。
+
+---
+
+## Hooks
+
+常用 Hooks 从 `@doubao-dev/framework` 导入：
+
+```tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useState
+} from '@doubao-dev/framework';
+```
+
+| Hook | 用途 |
+|------|------|
+| `useState(initial)` | 组件局部状态 |
+| `useEffect(effect, deps)` | 副作用、订阅和清理 |
+| `useReducer(reducer, initial)` | 复杂状态流转 |
+| `useMemo(factory, deps)` | 缓存计算结果 |
+| `useCallback(callback, deps)` | 缓存事件处理函数 |
+| `createContext(defaultValue)` / `useContext(context)` | 跨组件共享状态 |
+
+Framework 还提供视图生命周期 Hooks：
+
+| Hook | 对应能力 |
+|------|----------|
+| `useCreated(callback)` | View created |
+| `useMounted(callback)` | View mounted |
+| `useShow(callback)` / `useHide(callback)` | View show / hide |
+| `useDestroy(callback)` | View destroy |
+| `useError(callback)` | View error |
+| `useForeground(callback)` / `useBackground(callback)` | 应用前后台变化 |
+| `useViewData<T>()` | 读取并订阅 viewData 更新 |
+
+---
+
+## View Data
+
+| API | 用途 |
+|-----|------|
+| `useViewData<T>()` | 读取 Page / Widget 输入数据并响应后续更新，必须传泛型 |
+| `getWidgetInstanceId()` | 在 Widget 中获取当前实例 ID，Page 中通常为空 |
+| `getCurrentPages()` | 获取当前页面栈，返回 `CurrentPage[]`，当前页面信息包含 `route` |
+
+```tsx
+import {
+  getCurrentPages,
+  getWidgetInstanceId,
+  useViewData
+} from '@doubao-dev/framework';
+
+interface CardData {
+  title: string;
+  count?: number;
+}
+
+export default function Card() {
+  const viewData = useViewData<CardData>();
+  const widgetInstanceId = getWidgetInstanceId();
+  const pages = getCurrentPages();
+
+  return (
+    <view>
+      <text>{viewData.title}</text>
+      <text>{pages.at(-1)?.route || ''}</text>
+      <text>{widgetInstanceId || ''}</text>
+    </view>
+  );
+}
+```
+
+在 Page / Widget 组件内使用 `useViewData<T>()` 读取输入数据；它会在 viewData 更新时触发重新渲染。
+
+---
+
+## App Config
+
+独立应用项目的 `src/app.config.ts` 使用 `defineAppConfig()` 配置 App 元信息和入口 metadata。
+
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  description: '应用描述',
+  keywords: ['doubao', 'demo'],
+  pages: [
+    'pages/home/index',
+    {
+      entry: 'pages/account/demo/index',
+      title: '账号示例页'
+    }
+  ],
+  widgets: [
+    {
+      entry: 'widgets/product-card/index',
+      name: '商品卡片',
+      description: '展示商品摘要',
+      boxType: 'inbox',
+      border: true,
+      titleType: 'none'
+    }
+  ]
+});
+```
+
+配置规则：
+
+- 独立应用项目的 `appId` 使用开放平台 `db_xxxxxx` 风格，`name` 必填。
+- `pages` / `widgets` 可不写；不写时会按一级目录自动发现入口。
+- 需要稳定首页顺序、补标题或补 Widget metadata 时，使用数组配置。
+- 字符串数组项只声明入口；对象数组项用 `entry` 声明入口并补 metadata。
+- `entry` 写完整到 `index`，例如 `pages/home/index`、`widgets/product-card/index`。
+- Page 对象常用 `title`；Widget 对象常用 `name`、`description`、`boxType`、`border`、`titleType`。
+- Widget 默认无标题时显式配置 `titleType: 'none'`。
+
+更完整的入口、目录和 metadata 规则见 [开发规则](../rules/dos-and-donts.md)。
+
+---
+
+## 相关文档
+
+- [组件开发完整指南](../guides/component-development.md)
+- [开发规则](../rules/dos-and-donts.md)
+- [Page / Widget 基础示例](../examples/page-widget-basics.md)
+- [Widget 模板库](../widget-templates/overview.md)
+- [豆包应用插件的端能力 API 速查](../doubao-agentic-service-api/quick-reference.md)

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

@@ -0,0 +1,277 @@
+# 登录与授权约定入口
+
+`src/auth` 用于登录、隐私授权和自定义登录页。没有 `src/auth` 入口时，旧目录 `src/mcp-ui` 继续作为兼容 fallback。该目录由构建工具按约定扫描，不需要写到 `src/app.config.ts` 的 `pages` / `widgets` 中。
+
+---
+
+## 入口类型
+
+| 入口 | 文件路径 | 是否手写 | 用途 |
+|------|----------|----------|------|
+| 隐私协议回调 | `src/auth/privacy.ts` | 按需手写 | 处理同意或拒绝隐私协议 |
+| 登录回调 | `src/auth/login.ts` | 按需手写 | 处理手机号授权登录或拒绝登录 |
+| 登录页面 | `src/auth/login-page/index.tsx` | 按需手写 | 展示自定义登录页 |
+| 登录/隐私卡片 | `mcp-privacy-login-card` | 框架生成 | 根据 `privacy.ts` / `login.ts` 自动挂接回调 |
+
+`mcp-privacy-login-card` 是内置虚拟 Widget，构建工具会自动注入固定 metadata。不要在 `src/widgets` 中创建同名目录，
+也不要手动注册到 `app.config.ts`。
+
+---
+
+## privacy.ts
+
+`privacy.ts` 只导出隐私协议回调，不定义 UI。
+
+```ts
+import { definePrivacyApi, type PrivacyAgreeResult } from '@doubao-dev/framework';
+
+export default definePrivacyApi({
+  async onAgreePrivacy(res: PrivacyAgreeResult) {
+    console.log('onAgreePrivacy', res);
+  },
+
+  async onRefusePrivacy() {
+    console.log('onRefusePrivacy');
+  }
+});
+```
+
+---
+
+## login.ts
+
+`login.ts` 只导出登录回调，不定义 UI。内置登录卡完成手机号授权后，会把手机号授权结果传给 `onLogin`。
+
+最小登录闭环：
+
+1. 从 `LoginResult` 读取手机号授权 `code`。
+2. 调用 `login()` 获取豆包应用插件登录 `code`。
+3. 把两个 code 发给业务后端换取业务登录凭证。
+4. 按需保存业务 session。
+5. 调用 `postLoginResult()` 把登录结果回传给宿主。
+
+示例中的后端地址是占位 URL，实际项目需要替换成自己的 HTTPS 登录接口。
+
+```ts
+import { defineLoginApi, type LoginResult } from '@doubao-dev/framework';
+import { login, postLoginResult, request, setStorage } from '@doubao-dev/framework/api';
+
+interface AuthResponse {
+  loginCode: string;
+  sessionKey: string;
+}
+
+function isAuthResponse(data: unknown): data is AuthResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'loginCode' in data &&
+    'sessionKey' in data &&
+    typeof data.loginCode === 'string' &&
+    typeof data.sessionKey === 'string'
+  );
+}
+
+async function exchangeLoginCode(params: { appId: string; loginCode: string; phoneCode: string }) {
+  const response = await request({
+    url: 'https://example.com/api/doubao-login',
+    method: 'POST',
+    header: {
+      'content-type': 'application/json'
+    },
+    data: params
+  });
+
+  if (response.statusCode < 200 || response.statusCode >= 300 || !isAuthResponse(response.data)) {
+    throw new Error('登录响应无效');
+  }
+
+  return response.data;
+}
+
+export default defineLoginApi({
+  async onLogin(res: LoginResult) {
+    if (!res.code) {
+      await postLoginResult({ result: false });
+      return;
+    }
+
+    try {
+      const loginResult = await login({ timeout: 30000 });
+      const auth = await exchangeLoginCode({
+        appId: 'your-app-id',
+        loginCode: loginResult.code,
+        phoneCode: res.code
+      });
+
+      await setStorage({
+        key: 'session_key',
+        data: auth.sessionKey
+      });
+
+      await postLoginResult({
+        result: true,
+        code: auth.loginCode
+      });
+    } catch (error) {
+      console.error('onLogin failed', error);
+      await postLoginResult({ result: false });
+    }
+  },
+
+  async onRefuseLogin() {
+    await postLoginResult({ result: false });
+  }
+});
+```
+
+---
+
+## login-page
+
+自定义登录页放在 `src/auth/login-page/index.tsx`，直接默认导出组件函数。
+旧路径 `src/auth/mcp-login-page/index.tsx` 继续兼容；没有 `src/auth` 入口时，也会继续兼容 `src/mcp-ui/mcp-login-page/index.tsx`。
+构建工具会把它作为特殊 Page 处理，metadata 仍使用内置 `id: 'mcp-login-page'` 和 `path: '/pages/mcp-login-page/index'`。
+已有 `defineLoginPage()` 对象入口无需迁移；新登录页不要使用其他目录名。
+
+```tsx
+import {
+  useViewData,
+  type LoginResult,
+  useDestroy,
+  useEffect,
+  useState
+} from '@doubao-dev/framework';
+import {
+  login,
+  navigateBack,
+  postLoginResult,
+  request,
+  setStorage,
+  showToast
+} from '@doubao-dev/framework/api';
+import './index.scss';
+
+interface McpLoginPageData {
+  title?: string;
+  description?: string;
+}
+
+interface AuthResponse {
+  loginCode: string;
+  sessionKey: string;
+}
+
+function isAuthResponse(data: unknown): data is AuthResponse {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'loginCode' in data &&
+    'sessionKey' in data &&
+    typeof data.loginCode === 'string' &&
+    typeof data.sessionKey === 'string'
+  );
+}
+
+let loginResultPosted = false;
+
+async function postLoginFailure() {
+  if (loginResultPosted) {
+    return;
+  }
+
+  await postLoginResult({ result: false });
+  loginResultPosted = true;
+}
+
+async function exchangeLoginCode(params: { appId: string; loginCode: string; phoneCode: string }) {
+  const response = await request({
+    url: 'https://example.com/api/doubao-login',
+    method: 'POST',
+    header: {
+      'content-type': 'application/json'
+    },
+    data: params
+  });
+
+  if (response.statusCode < 200 || response.statusCode >= 300 || !isAuthResponse(response.data)) {
+    throw new Error('登录响应无效');
+  }
+
+  return response.data;
+}
+
+export default function McpLoginPage() {
+  const viewData = useViewData<McpLoginPageData>();
+  const [submitting, setSubmitting] = useState(false);
+
+  useEffect(() => {
+    loginResultPosted = false;
+  }, []);
+
+  useDestroy(() => {
+    void postLoginFailure();
+  });
+
+  const handlePhoneLogin = async (res?: LoginResult) => {
+    if (submitting) {
+      return;
+    }
+
+    if (!res?.code) {
+      showToast({ message: res?.message || '未完成手机号授权', type: 'warning' });
+      return;
+    }
+
+    try {
+      setSubmitting(true);
+      const loginResult = await login({ timeout: 30000 });
+      const auth = await exchangeLoginCode({
+        appId: 'your-app-id',
+        loginCode: loginResult.code,
+        phoneCode: res.code
+      });
+
+      await setStorage({
+        key: 'session_key',
+        data: auth.sessionKey
+      });
+
+      await postLoginResult({
+        result: true,
+        code: auth.loginCode
+      });
+      loginResultPosted = true;
+      await navigateBack();
+    } catch (error) {
+      console.error('mcp login failed', error);
+      showToast({ message: '登录失败，请稍后重试', type: 'error' });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleCancel = async () => {
+    await postLoginFailure();
+    await navigateBack();
+  };
+
+  return (
+    <view className="mcp-login-page">
+      <text className="mcp-login-page__title">{viewData.title || '登录'}</text>
+      <text className="mcp-login-page__description">{viewData.description || '请完成登录后继续使用'}</text>
+      <button
+        text={submitting ? '登录中...' : '手机号一键登录'}
+        type="primary"
+        openType="getPhoneNumber"
+        loading={submitting}
+        disabled={submitting}
+        onGetPhoneNumber={(res) => {
+          void handlePhoneLogin(res);
+        }}
+      />
+      <button text="暂不登录" disabled={submitting} onClick={handleCancel} />
+    </view>
+  );
+}
+```