@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/guides/mcp-ui.md

@@ -0,0 +1,275 @@
+# MCP UI 约定入口
+
+`src/mcp-ui` 用于登录、隐私授权和 MCP 相关特殊页面。该目录由构建工具按约定扫描，不需要写到
+`src/app.config.ts` 的 `pages` / `widgets` 中。
+
+---
+
+## 入口类型
+
+| 入口 | 文件路径 | 是否手写 | 用途 |
+|------|----------|----------|------|
+| 隐私协议回调 | `src/mcp-ui/privacy.ts` | 按需手写 | 处理同意或拒绝隐私协议 |
+| 登录回调 | `src/mcp-ui/login.ts` | 按需手写 | 处理手机号授权登录或拒绝登录 |
+| 登录页面 | `src/mcp-ui/mcp-login-page/index.tsx` | 按需手写 | 展示自定义登录页 |
+| 登录/隐私卡片 | `mcp-privacy-login-card` | 框架生成 | 根据 `privacy.ts` / `login.ts` 自动挂接回调 |
+
+`mcp-privacy-login-card` 是内置虚拟 Widget，不要在 `src/widgets` 中创建同名目录，也不要手动注册到 `app.config.ts`。
+
+---
+
+## privacy.ts
+
+`privacy.ts` 只导出隐私协议回调，不定义 UI。
+
+```ts
+import { definePrivacyApi, type PrivacyAgreeResult } from '@doubao-apps/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-apps/framework';
+import { login, postLoginResult, request, setStorage } from '@doubao-apps/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 });
+  }
+});
+```
+
+---
+
+## mcp-login-page
+
+自定义登录页放在 `src/mcp-ui/mcp-login-page/index.tsx`，使用 `defineLoginPage()`，不要用普通 `definePage()`。
+构建工具会把它作为特殊 Page 处理，metadata 使用内置 `id: 'mcp-login-page'` 和 `path: '/pages/mcp-login-page/index'`。
+
+```tsx
+import { defineLoginPage, getViewData, type LoginResult, useEffect, useState } from '@doubao-apps/framework';
+import {
+  login,
+  navigateBack,
+  postLoginResult,
+  request,
+  setStorage,
+  showToast
+} from '@doubao-apps/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;
+}
+
+function McpLoginPage() {
+  const viewData = getViewData<McpLoginPageData>();
+  const [submitting, setSubmitting] = useState(false);
+
+  useEffect(() => {
+    loginResultPosted = false;
+  }, []);
+
+  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>
+  );
+}
+
+export default defineLoginPage({
+  onDestroy() {
+    void postLoginFailure();
+  },
+
+  render() {
+    return <McpLoginPage />;
+  }
+});
+```

package/dist/skills/doubao-apps-dev/references/guides/performance-optimization.md

@@ -168,14 +168,16 @@ function InfiniteList() {
 // ✅ 好的做法 - 图片懒加载
 function LazyImage({ src, placeholder }: Props) {
   const [loaded, setLoaded] = useState(false);
+  const imageClassName = loaded
+    ? 'lazy-image__actual lazy-image__actual--visible'
+    : 'lazy-image__actual lazy-image__actual--hidden';
 
   return (
     <view className="lazy-image">
       {!loaded && <image src={placeholder} className="lazy-image__placeholder" />}
       <image
         src={src}
-        className="lazy-image__actual"
-        style={{ display: loaded ? 'block' : 'none' }}
+        className={imageClassName}
         onLoad={() => setLoaded(true)}
         onError={() => console.error('Failed to load image')}
       />
@@ -184,6 +186,16 @@ function LazyImage({ src, placeholder }: Props) {
 }
 ```
 
+```scss
+.lazy-image__actual--hidden {
+  display: none;
+}
+
+.lazy-image__actual--visible {
+  display: block;
+}
+```
+
 #### 图片尺寸优化
 
 ```tsx
@@ -220,7 +232,7 @@ function UnoptimizedImage({ src }: Props) {
 // ✅ 好的做法 - 清理定时器和订阅
 function TimerComponent() {
   const [count, setCount] = useState(0);
-  const timerRef = useRef<any>(null);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
 
   useEffect(() => {
     // 创建定时器
@@ -291,9 +303,12 @@ function DataFetcher() {
 
 ```tsx
 // ✅ 好的做法 - 分批处理大数据
-async function processBigData(data: any[]) {
+async function processBigData<T, R>(
+  data: T[],
+  processBatch: (items: T[]) => Promise<R[]>
+): Promise<R[]> {
   const BATCH_SIZE = 100;
-  const results = [];
+  const results: R[] = [];
 
   for (let i = 0; i < data.length; i += BATCH_SIZE) {
     const batch = data.slice(i, i + BATCH_SIZE);
@@ -308,7 +323,7 @@ async function processBigData(data: any[]) {
 }
 
 // ❌ 不好的做法 - 一次性处理所有数据
-async function processBigData(data: any[]) {
+async function processBigData<T>(data: T[]) {
   // 如果数据量大，会阻塞 UI
   return data.map(item => expensiveOperation(item));
 }
@@ -322,8 +337,10 @@ async function processBigData(data: any[]) {
 
 ```tsx
 // ✅ 好的做法 - 动态导入大组件
+type HeavyComponent = () => JSX.Element;
+
 function HeavyFeature() {
-  const [Component, setComponent] = useState<any>(null);
+  const [Component, setComponent] = useState<HeavyComponent | null>(null);
 
   useEffect(() => {
     // 只在需要时加载

package/dist/skills/doubao-apps-dev/references/reference/components-quick-ref.md

@@ -10,22 +10,28 @@
 |---------|------|----------|
 | `<button>` | 按钮交互 | `text`, `type`, `size`, `loading`, `disabled`, `openType`, `onClick` |
 | `<switch>` | 开关切换 | `checked`, `defaultChecked`, `disabled`, `onChange` |
-| `<slider>` | 滑块选择 | `value`(必填), `min`, `max`, `showValue`, `onChange` |
+| `<slider>` | 滑块选择 | `value`(必填), `min`, `max`, `showValue`, `disabled`, `onChange` |
 | `<swiper>` | 轮播容器 | `data`, `itemWidth`, `itemHeight`, `loop`, `duration`, `onChange` |
 | `<swiper-item>` | 轮播项 | `index`, `realIndex` |
 
 ---
 
+## 事件命名
+
+应用 TSX 中使用 React 风格事件名。`button` 点击使用 `onClick`；不要在业务代码里写 `onTap`、`bindtap` 或 `catchtap`。
+`switch` / `slider` / `swiper` 使用 `onChange`，回调直接接收当前值。
+
+---
+
 ## button 按钮
 
 ```tsx
 <button
   text="提交"
   type="primary"       // primary | default | plain
-  size="default"       // default | small | large
+  size="default"       // default | mini | large
   loading={false}
   disabled={false}
-  icon={<IconNode />}
   throttle={500}       // 节流时间(ms)
   onClick={() => {}}
 />
@@ -68,6 +74,7 @@ const [value, setValue] = useState(50);
 ```
 
 > `onChange` 回调直接接收 `number` 值，而非事件对象。
+> `slider` 不支持 `step`、`defaultValue` 或事件对象参数；不要传这些 props。
 
 ---
 
@@ -97,7 +104,11 @@ const [value, setValue] = useState(50);
 ## 注意事项
 
 1. **无需 import**：所有组件直接使用小写标签，不需要从任何包导入
-2. **onChange 回调签名**：switch/slider/swiper 的 `onChange` 直接接收值（boolean/number/number），不是事件对象
-3. **Lynx 不支持 CSS 继承**：组件样式自包含，不依赖父元素样式
-4. **受控/非受控**：switch 支持两种模式，slider 只支持受控模式
-5. **节流处理**：button 内置 500ms 节流，可通过 `throttle` 自定义
+2. **事件命名**：button 使用 `onClick`，不要写 `onTap`、`bindtap` 或 `catchtap`
+3. **onChange 回调签名**：switch/slider/swiper 的 `onChange` 直接接收值（boolean/number/number），不是事件对象
+4. **Lynx 不支持 CSS 继承**：组件样式自包含，不依赖父元素样式
+5. **受控/非受控**：switch 支持两种模式，slider 只支持受控模式
+6. **节流处理**：button 内置 500ms 节流，可通过 `throttle` 自定义
+7. **Slider props**：slider 只使用 `value`、`min`、`max`、`showValue`、`disabled`、`onChange`，不要写 `step`
+
+完整 Page 组合示例见 [内置组件使用配方](../examples/component-recipes.md)。