@doubao-apps/create 0.0.25 → 0.0.27

package/dist/template-starter/.ai/guides/component-development.md

@@ -124,45 +124,31 @@ export default definePage({
 });
 ```
 
-### 页面打开方式
+### 页面导航
 
 ```tsx
-import { openPage } from '@doubao-apps/framework/api';
-
-// 全屏页面
-openPage({
-  pageId: 'my-page',
-  mode: 'full', // 或省略此参数，默认为 'full'
-  pageData: JSON.stringify({ userId: '123' }),
-  context: {},
-  pageSettings: {
-    title: '页面标题'
-  }
+import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
+
+// 保留当前页面，打开新页面
+navigateTo({
+  url: 'user-detail?userId=123&tab=profile'
 });
 
-// 弹窗页面
-openPage({
-  pageId: 'settings',
-  mode: 'popup',
-  context: {},
-  pageSettings: {
-    title: '设置',
-    heightPercent: 60 // 高度百分比
-  }
+// 替换当前页面
+redirectTo({
+  url: 'settings'
 });
 
-// 悬浮窗
-openPage({
-  pageId: 'mini-player',
-  mode: 'floating',
-  context: {},
-  pageSettings: {
-    width: 300,
-    height: 200
-  }
+// 关闭所有页面并回到首页
+reLaunch({
+  url: 'home'
 });
 ```
 
+`url` 在常规页面跳转里填写页面的 `pageId`，与该页面的 `aiMeta.id` 一致；需要传参时可直接在后面拼接 query string。
+
+页面内可继续通过 `getViewData<PageInput>()` 读取 URL 中传入的参数。
+
 ### 常用模式
 
 **1. 数据加载**
@@ -207,7 +193,7 @@ function MyPage({ userId }: { userId: string }) {
 
 ```tsx
 import { useState } from '@doubao-apps/framework';
-import { close, request, showToast } from '@doubao-apps/framework/api';
+import { navigateBack, request, showToast } from '@doubao-apps/framework/api';
 
 function FormPage() {
   const [formData, setFormData] = useState({
@@ -225,7 +211,7 @@ function FormPage() {
         data: formData
       });
       showToast({ message: '提交成功' });
-      close(); // 关闭页面
+      navigateBack(); // 返回上一页
     } catch (err) {
       showToast({ message: '提交失败' });
     } finally {
@@ -257,40 +243,38 @@ function FormPage() {
 
 ## 🎴 Widget 开发指南
 
+### Metadata 配置
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/my-widget': {
+      id: 'my-widget',                 // 卡片唯一标识
+      name: '我的卡片',                 // 卡片名称
+      description: '卡片功能描述',       // 卡片描述
+      boxType: 'inbox',                // 卡片类型: inbox | full_box
+      border: true,
+      keywords: ['demo', 'widget'],
+      titleType: 'normal'
+    }
+  }
+});
+```
+
 ### 基本结构
 
 ```tsx
-import { defineWidget, getViewData, useState, useEffect } from '@doubao-apps/framework';
+import { defineWidget, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
-export default defineWidget({
-  // 1. AI 元数据配置
-  aiMeta: {
-    id: 'my-widget',                  // 卡片唯一标识
-    name: '我的卡片',                  // 卡片名称
-    description: '卡片功能描述',        // 卡片描述
-    boxType: 'inbox',                 // 卡片类型: inbox | full_box
-
-    // 2. 输入数据 Schema（JSON Schema 格式）
-    input: {
-      type: 'object',
-      properties: {
-        title: {
-          type: 'string',
-          title: '标题',
-          description: '卡片标题文本'
-        },
-        content: {
-          type: 'string',
-          title: '内容',
-          description: '卡片内容文本'
-        }
-      },
-      required: ['title']              // 必填字段
-    }
-  },
+interface MyWidgetData {
+  title: string;
+  content?: string;
+}
 
-  // 3. 生命周期钩子
+export default defineWidget({
   onShow() {
     console.log('卡片显示');
   },
@@ -316,10 +300,8 @@ export default defineWidget({
     console.log('卡片销毁');
   },
 
-  // 4. 渲染函数
   render() {
-    const input = getViewData();
-
+    const input = getViewData<MyWidgetData>();
     return <MyWidgetComponent {...input} />;
   }
 });
@@ -336,23 +318,26 @@ export default defineWidget({
 - 不需要占用整行宽度，希望保持对话流的紧凑阅读体验
 - 交互以按钮、简单表单项为主
 
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/info-card': {
+      id: 'info-card',
+      name: '信息卡片',
+      boxType: 'inbox'
+    }
+  }
+});
+```
+
 ```tsx
 export default defineWidget({
-  aiMeta: {
-    id: 'info-card',
-    name: '信息卡片',
-    boxType: 'inbox',
-    input: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', title: '标题' },
-        content: { type: 'string', title: '内容' }
-      }
-    }
-  },
   render() {
     const input = getViewData<{ title: string; content: string }>();
-    
+
     return (
       <view className="info-card">
         <text className="title">{input.title}</text>
@@ -367,20 +352,23 @@ export default defineWidget({
 
 适用于需要更大展示空间的卡片（例如图表、图片墙、复杂表单等）。
 
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/user-action-card': {
+      id: 'user-action-card',
+      name: '全宽卡片示例',
+      boxType: 'full_box'
+    }
+  }
+});
+```
+
 ```tsx
 export default defineWidget({
-  aiMeta: {
-    id: 'user-action-card',
-    name: '全宽卡片示例',
-    boxType: 'full_box',
-    input: {
-      type: 'object',
-      properties: {
-        action: { type: 'string', title: '操作' },
-        result: { type: 'string', title: '结果' }
-      }
-    }
-  },
   render() {
     const input = getViewData<{ action: string; result: string }>();
     return (
@@ -393,127 +381,26 @@ export default defineWidget({
 });
 ```
 
-### Input Schema 定义
+### 输入数据类型
 
-**基础类型**
+Widget 输入数据通过 `getViewData<T>()` 的泛型参数和 TypeScript 接口表达。
 
 ```tsx
-// 字符串
-{
-  type: 'string',
-  title: '标题',
-  description: '字段描述',
-  default: '默认值',
-  minLength: 1,
-  maxLength: 100
-}
-
-// 数字
-{
-  type: 'number',
-  title: '数量',
-  minimum: 0,
-  maximum: 100,
-  default: 1
-}
-
-// 布尔值
-{
-  type: 'boolean',
-  title: '是否启用',
-  default: false
-}
-
-// 枚举
-{
-  type: 'string',
-  enum: ['option1', 'option2', 'option3'],
-  title: '选项'
-}
-
-// 数组
-{
-  type: 'array',
-  items: {
-    type: 'string'
-  },
-  title: '标签列表',
-  minItems: 1,
-  maxItems: 5
-}
-
-// 对象
-{
-  type: 'object',
-  properties: {
-    name: { type: 'string', title: '名称' },
-    age: { type: 'number', title: '年龄' }
-  },
-  required: ['name']
+interface ProductCardData {
+  name: string;
+  price: number;
+  images?: string[];
+  category: '电子' | '服装' | '食品' | '图书';
+  inStock: boolean;
+  specs?: {
+    color?: string;
+    size?: string;
+  };
 }
-```
-
-**复杂 Schema 示例**
 
-```tsx
 export default defineWidget({
-  aiMeta: {
-    id: 'product-card',
-    name: '商品卡片',
-    boxType: 'inbox',
-    input: {
-      type: 'object',
-      properties: {
-        name: {
-          type: 'string',
-          title: '商品名称',
-          description: '商品的显示名称'
-        },
-        price: {
-          type: 'number',
-          title: '价格',
-          minimum: 0,
-          description: '商品价格（元）'
-        },
-        images: {
-          type: 'array',
-          items: { type: 'string' },
-          title: '商品图片',
-          description: '商品图片 URL 列表',
-          minItems: 1,
-          maxItems: 5
-        },
-        category: {
-          type: 'string',
-          enum: ['电子', '服装', '食品', '图书'],
-          title: '分类'
-        },
-        inStock: {
-          type: 'boolean',
-          title: '是否有货',
-          default: true
-        },
-        specs: {
-          type: 'object',
-          properties: {
-            color: { type: 'string', title: '颜色' },
-            size: { type: 'string', title: '尺寸' }
-          },
-          title: '规格'
-        }
-      },
-      required: ['name', 'price']
-    }
-  },
   render() {
-    const input = getViewData<{
-      name: string;
-      price: number;
-      images?: string[];
-      category: string;
-      inStock: boolean;
-      specs?: { color?: string; size?: string };
-    }>();
+    const input = getViewData<ProductCardData>();
     return (
       <view className="product-card">
         <text className="name">{input.name}</text>
@@ -579,16 +466,17 @@ function WeatherWidget({ city }: { city: string }) {
 **2. 用户交互**
 
 ```tsx
+import { sendQueryMessage } from '@doubao-apps/framework/api';
+
 function InteractiveWidget({ initialCount }: { initialCount: number }) {
   const [count, setCount] = useState(initialCount);
 
   const handleIncrement = () => {
     setCount(count + 1);
-    // 可以发送消息到 Bot
+    // 发送一条用户消息到当前会话
     sendQueryMessage({
       content: `计数增加到 ${count + 1}`,
-      type: 'text',
-      context: {}
+      type: 'text'
     });
   };
 
@@ -604,18 +492,12 @@ function InteractiveWidget({ initialCount }: { initialCount: number }) {
 **3. 打开页面**
 
 ```tsx
-import { openPage } from '@doubao-apps/framework/api';
+import { navigateTo } from '@doubao-apps/framework/api';
 
 function ActionWidget({ itemId }: { itemId: string }) {
   const handleViewDetail = () => {
-    openPage({
-      pageId: 'item-detail',
-      mode: 'full', // 全屏页面，可省略（默认）
-      pageData: JSON.stringify({ id: itemId }),
-      context: {},
-      pageSettings: {
-        title: '详情'
-      }
+    navigateTo({
+      url: `item-detail?id=${itemId}`
     });
   };
 

package/dist/template-starter/.ai/guides/system-prompt.md

@@ -21,7 +21,7 @@
 
 ### **项目文档系统**
 本地项目文档（按优先级）：
-1. **AGENTS.md** - 项目主入口，包含快速开始和核心规则
+1. **SKILL.md** - 项目主入口，包含快速开始和核心规则
 2. **.ai/rules/** - 框架规则和约束
 3. **.ai/guides/** - 开发指南
 4. **.ai/examples/** - 代码示例库
@@ -50,7 +50,7 @@ LynxBase MCP 提供：
 ## 知识体系
 
 ### 知识优先级
-1. **项目本地文档**（AGENTS.md 及 .ai/ 目录）
+1. **项目本地文档**（SKILL.md 及 .ai/ 目录）
 2. **LynxBase MCP**（Lynx 官方/内部文档）
 3. **通用编程知识**
 
@@ -64,7 +64,7 @@ LynxBase MCP 提供：
 
 [生成代码]
 
-详细的开发规范请参考：[.ai/prompts/component-development.md](.ai/prompts/component-development.md)
+详细的开发规范请参考：[component-development.md](component-development.md)
 ```
 
 **错误做法**：
@@ -191,7 +191,7 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
 
 **4. 项目结构问题** → 引用本地文档
 - 示例："如何组织组件？"
-- 响应：简短说明 + 引用 AGENTS.md 或 .ai/rules/
+- 响应：简短说明 + 引用 SKILL.md 或 .ai/rules/
 
 **5. 问题诊断** → 分析 + 解决方案 + 预防措施
 - 示例："报错了"
@@ -209,7 +209,7 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
 
 2. **规划方法**
    - **Lynx 相关** → 查询 **LynxBase MCP** 获取支持数据
-   - **项目结构/规则** → 引用本地文档（AGENTS.md、.ai/）
+   - **项目结构/规则** → 引用本地文档（SKILL.md、.ai/）
 
 3. **调用适当工具**
    - Lynx 相关 → **LynxBase MCP**
@@ -261,7 +261,7 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
    - 提供错误处理代码
 
 4. ❌ **不要违反框架规则**
-   - 严格遵守 AGENTS.md 和 Lynx 规范
+   - 严格遵守 SKILL.md 和 Lynx 规范
    - 不要为了方便走捷径
 
 5. ❌ **不要过度工程化**
@@ -280,13 +280,13 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
 
 | 用户请求 | 查阅文档 | 你的动作 |
 |---------|---------|---------|
-| "创建页面" | `.ai/prompts/component-development.md` (Page) + LynxBase MCP | 生成代码 + 引用文档 |
-| "创建卡片" | `.ai/prompts/component-development.md` (Widget) + LynxBase MCP | 生成代码 + 引用文档 |
+| "创建页面" | `.ai/guides/component-development.md` (Page) + LynxBase MCP | 生成代码 + 引用文档 |
+| "创建卡片" | `.ai/guides/component-development.md` (Widget) + LynxBase MCP | 生成代码 + 引用文档 |
 | "Lynx 组件如何用" | LynxBase MCP → `query-assets` → `get-assets` | 查询 + 提供示例 |
 | "如何调用 API" | `.ai/examples/common-patterns.md` + Doubao Bridge 文档 | 提供示例 + 引用文档 |
-| "性能优化" | `.ai/prompts/performance-optimization.md` + Lynx 性能指南 | 分析问题 + 引用文档 |
-| "报错了" | `.ai/prompts/troubleshooting.md` + 错误分析 | 诊断 + 修复 + 引用文档 |
-| "框架规则" | `.ai/rules/dos-and-donts.md` + AGENTS.md | 简要说明 + 引用文档 |
+| "性能优化" | `.ai/guides/performance-optimization.md` + Lynx 性能指南 | 分析问题 + 引用文档 |
+| "报错了" | `.ai/guides/troubleshooting.md` + 错误分析 | 诊断 + 修复 + 引用文档 |
+| "框架规则" | `.ai/rules/dos-and-donts.md` + SKILL.md | 简要说明 + 引用文档 |
 
 ---
 
@@ -309,7 +309,7 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
 1. 调用 **LynxBase MCP** 查询主线程相关文档
 2. 简短解释："主线程脚本是在 Lynx 主线程执行的 JS 代码，用于高频交互和实时更新..."
 3. 提供简单示例
-4. 引用详细文档："更多详情请查阅 LynxBase 文档或参考 [性能优化指南](.ai/prompts/performance-optimization.md)"
+4. 引用详细文档："更多详情请查阅 LynxBase 文档或参考 [性能优化指南](performance-optimization.md)"
 
 ### 示例 3：项目规则
 **用户**："组件应该放在哪里？"
@@ -324,8 +324,8 @@ ReactLynx 镜像 React API（`useState`、`useEffect` 等），但所有生命
 - `index.scss` - 样式文件
 - `types.ts` - 类型定义（可选）
 
-详细规范请参考：[AGENTS.md](./AGENTS.md) 和 [组件开发指南](.ai/prompts/component-development.md)"
+详细规范请参考：[SKILL.md](../../SKILL.md) 和 [组件开发指南](component-development.md)"
 
 ---
 
-*系统提示词版本: 2.0.0 | 集成: Lynx + Doubao Apps SDK | 维护: Doubao Apps SDK 团队*
+*系统提示词版本: 2.0.0 | 集成: Lynx + Doubao Apps SDK | 维护: Doubao Apps SDK 团队*

package/dist/template-starter/.ai/reference/framework-api-quick-ref.md

@@ -136,7 +136,7 @@ console.log(info.keys, info.currentSize, info.limitSize);
 ## 引入依赖
 
 ```ts
-import { getLocation, getPhoneNumber, openPage, request, showToast, setStorage, getStorage } from '@doubao-apps/framework/api';
+import { getLocation, getPhoneNumber, navigateTo, navigateBack, request, showToast, setStorage, getStorage } from '@doubao-apps/framework/api';
 ```
 
 ## 使用示例
@@ -144,7 +144,8 @@ import { getLocation, getPhoneNumber, openPage, request, showToast, setStorage,
 ```ts
 await showToast({ message: '保存成功' });
 
-const { viewId } = await openPage({ pageId: 'detail', context: {} });
+await navigateTo({ url: 'detail?id=123' });
+await navigateBack();
 
 const res = await request({ url: '/api/data', method: 'GET' });
 
@@ -155,85 +156,57 @@ const phone = await getPhoneNumber();
 
 以下为常用端能力 API 的节选，完整以 `@doubao-apps/framework/api` 类型定义为准。
 
-### openFloatingWindow
+### navigateTo
 
 **参数**:
 ```typescript
 {
-  /** 期望要打开的 page 的 id */
-  pageId: string;
-
-  /** 打开页面时传入的数据，运行时通过 getViewData 获取 */
-  pageData?: string;
-
-  /** view context 对象，在全页和卡片中通过 getViewContext() 获取 */
-  context: object;
-
-  /** 打开 Page 时配置页面参数 */
-  pageSettings?: {
-    /**
-     * 悬浮窗口在横向上的吸附位置
-     *
-     * @deprecated 最新的 Lynx 悬浮窗中已失效
-     */
-    align?: 'left' | 'right';
-    
-    /**
-     * 设置 Lynx 悬浮窗的宽度，单位是 `px`
-     */
-    width?: number;
-    
-    /**
-     *  设置 Lynx 悬浮窗的高度，单位是 `px`
-     */
-    height?: number;
-    
-    /**
-     * 优先级。越高代表优先级越高，取值-2~2
-     */
-    priority?: number;
-    
-    /**
-     * 是否自动恢复展示。在被高优悬浮窗打断时会发挥作用，只有为 true 才会得到恢复的机会，否则直接释放
-     */
-    autoReshow?: boolean;
-  };
+  /** 跳转目标，填写页面的 pageId，可拼接 query，如 'detail?id=123' */
+  url: string;
 }
 ```
 
-**返回值**:
+**返回值**: Promise
+
+### redirectTo
+
+**参数**:
 ```typescript
 {
-  /** 创建出的 view id */
-  viewId: string;
-  
-  /**
-   * 返回展示悬浮窗的结果
-   * 0: 展示失败
-   * 1: 展示成功
-   * 2: 排队中
-   */
-  floatingShowResult?: number;
+  /** 跳转目标，填写页面的 pageId，如 'settings' */
+  url: string;
 }
 ```
 
-### close
+**返回值**: Promise
+
+### reLaunch
 
 **参数**:
 ```typescript
 {
-  /** 要关闭的页面 id，留空(undefined) 为当前页面 */
-  viewID?: string;
-  /** 要关闭的多个页面 id */
-  viewIDs?: string[];
-  /**
-   * @default false
-   */
-  animated?: boolean;
+  /** 跳转目标，填写页面的 pageId，如 'home' */
+  url: string;
 }
 ```
 
-**返回值**: 无（空对象）
+**返回值**: Promise
+
+### navigateBack
+
+**参数**:
+```typescript
+{
+  /** 返回的页面数，默认为 1 */
+  delta?: number;
+}
+```
+
+**返回值**: Promise
+
+> `close()` 已废弃，公开路由场景请优先使用 `navigateBack()`。
+>
+> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`，该值一般与页面的 `aiMeta.id` 一致；需要传参时可直接拼接 query string。
 
 ### showToast
 
@@ -413,7 +386,7 @@ const phone = await getPhoneNumber();
 
 | API | 功能 | 示例 |
 |-----|------|------|
-| `sendQueryMessage(params)` | 发送用户消息 | `sendQueryMessage({ content: '查询天气', type: 'text', context: {} })` |
+| `sendQueryMessage(params)` | 发送用户消息 | `sendQueryMessage({ content: '查询天气', type: 'text' })` |
 | `setAdditionalContext(params)` | 设置上下文 | `setAdditionalContext({ additionalContext: '...' })` |
 
 ### sendQueryMessage
@@ -426,12 +399,6 @@ const phone = await getPhoneNumber();
 
   /** 消息类型，目前仅支持 text */
   type: 'text';
-
-  /** Plugin tool 或 Page/Widget 携带的上下文信息 */
-  context: object;
-
-  /** 扩展信息 */
-  ext?: Record<string, string>;
 }
 ```
 
@@ -500,21 +467,7 @@ interface PageInput {
   [key: string]: any;  // URL 参数
 }
 
-// Widget Input Schema
-interface WidgetInputSchema {
-  type: 'object';
-  properties: {
-    [key: string]: {
-      type: 'string' | 'number' | 'boolean' | 'array' | 'object';
-      title: string;
-      description?: string;
-      default?: any;
-    };
-  };
-  required?: string[];
-}
-
-// aiMeta 配置
+// src/app.config.ts 中的 metadata 配置
 interface PageAIMeta {
   id: string;                      // 页面唯一标识
   title?: string;                  // 页面标题
@@ -526,7 +479,15 @@ interface WidgetAIMeta {
   name?: string;                   // 卡片名称
   description?: string;            // 卡片描述
   boxType?: 'inbox' | 'full_box';  // 卡片类型
-  input: WidgetInputSchema;        // 输入数据格式
+  border?: boolean;                // 是否显示边框
+  keywords?: string[];             // 搜索关键词
+  titleType?: 'none' | 'normal' | 'float';
+}
+
+// Widget 渲染数据类型
+interface WidgetViewData {
+  title: string;
+  content?: string;
 }
 ```