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

package/dist/skills/doubao-plugin-app/references/frontend/rules/dos-and-donts.md

@@ -0,0 +1,479 @@
+# 开发规则 - Do's and Don'ts
+
+> 项目配置：下文 `defineAppConfig` 和 `appId` 示例适用于独立应用项目，沿用其配置要求。Plugin CLI 项目以根目录的 `plugin.json` 为标识，`src/` 位于 `com.doubao/app/` 下；`app.config.ts` 默认导出普通对象，不填写 `appId`，由 CLI 查询注入。配置示例以 `doubao-plugin-app` Skill 的应用开发指南为准，本文的组件、Hooks 和入口 metadata 用法共用。
+
+Doubao Apps SDK 框架的开发规则和最佳实践。
+
+新 Page / Widget 直接导出组件函数，并在组件内使用生命周期 Hooks。
+
+---
+
+## ✅ 推荐做法（Do's）
+
+### 项目管理
+
+#### ✅ 使用 pnpm 包管理器
+```bash
+# 推荐
+pnpm install
+pnpm add @doubao-dev/framework
+
+# 不推荐（除非项目已使用 npm）
+npm install
+npm install @doubao-dev/framework
+```
+
+
+### 组件开发
+
+#### ✅ 在 app.config.ts 配置 App 元信息
+```ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用'
+});
+```
+
+#### ✅ 需要稳定首页时在 app.config.ts 明确入口
+```ts
+// ✅ pages 数组第一项会作为首页（appletEntry）
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/home/index',
+      title: '首页',
+      description: '应用默认打开的页面'
+    }
+  ]
+});
+```
+
+一级页面目录不写进 `pages` 也会自动发现；如果首页不是默认入口 `index`，或需要固定首页顺序，建议显式配置
+`pages` 数组第一项。entry 必须写到 `index`，例如 `pages/home/index`。
+
+#### ✅ 需要补充展示信息时在 app.config.ts 定义 metadata
+```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: '展示和编辑用户个人资料'
+    }
+  ]
+});
+```
+
+```ts
+// ❌ 不好的做法：缺少 title、description 等信息
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index'
+    }
+  ]
+});
+```
+
+#### ✅ 多级目录必须显式声明 entry
+```ts
+// src/pages/account/demo/index.tsx
+// src/widgets/order/detail/index.tsx
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  pages: [
+    // Page 只声明入口、不补 metadata 时，可以直接写字符串
+    'pages/account/demo/index',
+    {
+      entry: 'pages/account/settings/index',
+      title: '账号设置页'
+    }
+  ],
+  widgets: [
+    {
+      entry: 'widgets/order/detail/index',
+      titleType: 'none'
+    },
+    {
+      entry: 'widgets/order/summary/index',
+      id: 'order-summary',
+      name: '订单摘要卡片',
+      titleType: 'none'
+    }
+  ]
+});
+```
+
+Page 使用由完整 entry 派生的 URL，例如 `pages/account/demo/index` 对应 `/pages/account/demo/index`。
+Widget 如果不配置 `id`，默认取入口最后一级目录名，例如 `widgets/order/detail/index` 默认为 `detail`；该 ID
+必须在应用内全局唯一。
+
+#### ✅ 分离样式文件
+```tsx
+// ✅ 好的做法
+// index.tsx
+import './index.scss';
+
+export default function Page() {
+  return <view className="container">内容</view>;
+}
+```
+
+```scss
+// index.scss
+.container {
+  padding: 16px;
+  background: #fff;
+}
+```
+
+```tsx
+// ❌ 不好的做法
+export default function Page() {
+  return <view style={{ padding: '16px', background: '#fff' }}>内容</view>;
+}
+```
+
+#### ✅ Page 默认使用可滚动安全区布局
+
+Page 默认按沉浸式全屏承载，内容会从顶部开始铺满。除地图、相机、视频、沉浸式大屏等明确不滚动的场景外，
+普通全页默认使用垂直 `scroll-view` 作为根滚动容器，由内容区负责顶部安全距离和页面内边距，避免被状态栏和右上角胶囊按钮遮挡。
+
+```tsx
+// ✅ 好的做法：Page 根节点提供垂直滚动，内容区负责安全区和页面内边距
+import './index.scss';
+
+export default function DemoPage() {
+  return (
+    <scroll-view className="demo-page" scrollOrientation="vertical" enableScroll>
+      <view className="demo-page__content">
+        <view className="demo-page__header">
+          <text className="demo-page__title">页面标题</text>
+        </view>
+        <view className="demo-page__body">页面内容</view>
+      </view>
+    </scroll-view>
+  );
+}
+```
+
+```scss
+.demo-page {
+  height: 100vh;
+  background: #f7f8fa;
+}
+
+.demo-page__content {
+  min-height: 100%;
+  box-sizing: border-box;
+  padding: 88px 24px 32px;
+}
+
+.demo-page__header {
+  // 右上角通常有宿主胶囊按钮；标题或自定义操作区不要贴到右上角。
+  padding-right: 160px;
+}
+```
+
+全页布局先串清三件事：谁占满视口、谁承接滚动、谁负责安全区和页面内边距。
+内容超过首屏，或存在固定头部、大尺寸业务区时，先检查这条链路，再处理具体模块样式。
+不要依赖内容自然撑高、普通 `view` 的 `overflow: scroll`，或让多个节点隐式争夺滚动和裁剪职责。
+
+#### ✅ 复杂布局先定义边界和收缩语义
+
+Page / Widget 中出现多层容器、固定尺寸模块、横向 grid / flex、卡片底部操作区或内置组件组合时，
+都要先定义边界和收缩语义：哪个容器给出可用空间，哪个节点可以增长，哪个节点可以收缩、换行或独占一行，哪个节点不能越界。
+元素被挤出、重叠或裁剪时，不要只给最里层补样式；通常要沿父子链路同时检查容器边界、盒模型、间距、固定尺寸和收缩能力。
+
+- `button`、`switch`、`slider`、`input` 等内置组件通常自带最小尺寸、内边距和交互态样式；放入横向布局时，要按有固有尺寸的内容处理。
+- 固定尺寸的业务模块要和外层可用空间一起设计，避免尺寸、边距和边框叠加后把父容器撑出。
+- 多列、多按钮或图文混排时，优先明确容器和子项的收缩、换行或独占一行策略，再处理视觉细节。
+
+#### ✅ 使用 TypeScript 类型定义
+```tsx
+// ✅ 好的做法
+interface UserInfo {
+  name: string;
+  age: number;
+  avatar?: string;
+}
+
+export default function UserWidget() {
+  const viewData = useViewData<UserInfo>();
+  return <view>{viewData.name}</view>;
+}
+```
+
+```ts
+// ✅ 把 metadata 写到 src/app.config.ts
+import { defineAppConfig } from '@doubao-dev/framework/config';
+
+export default defineAppConfig({
+  appId: 'db_xxxxxx', // 独立应用项目填写；Plugin CLI 项目不填写
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/user-card/index',
+      id: 'user-card',
+      name: '用户卡片',
+      description: '用户信息卡片',
+      titleType: 'none'
+    }
+  ]
+});
+```
+
+```tsx
+// ❌ 不好的做法
+export default function UserWidget() {
+  // 错误：类型和实际任务字段不匹配
+  const viewData = useViewData<{ title: string }>();
+  return <view>{viewData.name}</view>;
+}
+```
+
+#### ✅ 使用生命周期钩子
+```tsx
+// ✅ 好的做法
+import { useDestroy, useHide, useShow } from '@doubao-dev/framework';
+
+export default function Page() {
+  useShow(() => console.log('Page shown'));
+  useHide(() => console.log('Page hidden'));
+  useDestroy(() => console.log('Page destroyed'));
+
+  return <view>内容</view>;
+}
+```
+
+
+#### ✅ 错误处理和边界情况
+```tsx
+// ✅ 好的做法
+export default function ItemsWidget() {
+  const viewData = useViewData<{ items: string[] }>();
+  if (!viewData.items || viewData.items.length === 0) {
+    return <view>暂无数据</view>;
+  }
+
+  return (
+    <view>
+      {viewData.items.map((item, index) => (
+        <view key={index}>{item}</view>
+      ))}
+    </view>
+  );
+}
+```
+
+```tsx
+// ❌ 不好的做法
+export default function ItemsWidget() {
+  const viewData = useViewData<{ items?: string[] }>();
+  // 没有检查 viewData.items 是否存在
+  return <view>{viewData.items.map(item => <view>{item}</view>)}</view>;
+}
+```
+
+
+
+## ❌ 禁止做法（Don'ts）
+
+### 样式相关
+
+#### ❌ 不在 TSX 中写 style 对象
+
+样式统一写到 `index.scss`，TSX 中通过 `className` 切换状态。不要把 Web 写法里的内联 style 对象迁移过来。
+
+```tsx
+// ❌ 错误：内联 style 对象
+<view style={{ width: 100, height: 56, fontSize: 14 }} />
+
+// ✅ 正确：使用 className
+<view className="profile-card" />
+```
+
+```scss
+.profile-card {
+  width: 100px;
+  height: 56px;
+  font-size: 14px;
+}
+```
+
+#### ❌ 不写内联样式
+```tsx
+// ❌ 错误
+export default function Page() {
+  return <view style={{ padding: 16, background: '#fff' }}>内容</view>;
+}
+```
+
+```tsx
+// ✅ 正确
+import './index.scss';
+
+export default function Page() {
+  return <view className="container">内容</view>;
+}
+```
+
+### 异步操作
+
+#### ❌ 不在 render 中发起请求
+```tsx
+// ❌ 错误 - 每次渲染都会发请求
+import { request } from '@doubao-dev/framework/api';
+
+export default function Page() {
+  void request({ url: 'https://api.example.com/data', method: 'GET' });
+  return <view>内容</view>;
+}
+```
+
+```tsx
+// ✅ 推荐 - 使用 Hook 管理请求和状态
+import { useEffect, useState } from '@doubao-dev/framework';
+import { request } from '@doubao-dev/framework/api';
+
+export default function UserPage() {
+  const [userData, setUserData] = useState<{ name?: string } | null>(null);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    const loadUser = async () => {
+      try {
+        setError('');
+        const response = await request({ url: 'https://api.example.com/data', method: 'GET' });
+        setUserData(response.data as { name?: string });
+      } catch (caughtError) {
+        setError(caughtError instanceof Error ? caughtError.message : '请求失败');
+      }
+    };
+
+    void loadUser();
+  }, []);
+
+  if (error) {
+    return <view>{error}</view>;
+  }
+
+  return <view>{userData?.name}</view>;
+}
+```
+
+### 组件结构
+
+#### ❌ 不过度嵌套组件
+```tsx
+// ❌ 错误 - 过度嵌套
+export default function Page() {
+  return (
+    <view>
+      <view>
+        <view>
+          <view>
+            <view>
+              <view>内容</view>
+            </view>
+          </view>
+        </view>
+      </view>
+    </view>
+  );
+}
+```
+
+```tsx
+// ✅ 正确 - 扁平结构
+export default function Page() {
+  return (
+    <view className="page">
+      <view className="header">头部</view>
+      <view className="content">内容</view>
+      <view className="footer">底部</view>
+    </view>
+  );
+}
+```
+
+### 类型使用
+
+#### ❌ 不忽略 TypeScript 类型
+```tsx
+// ❌ 错误
+export default function UserWidget() {
+  const viewData = useViewData<{ name: string }>();
+  // @ts-ignore
+  return <view>{viewData.unknownProperty}</view>;
+}
+```
+
+```tsx
+// ✅ 正确
+interface UserInfo {
+  name: string;
+  age: number;
+}
+
+export default function UserWidget() {
+  const viewData = useViewData<UserInfo>();
+  return <view>{viewData.name}</view>;
+}
+```
+
+### 状态管理
+
+#### ❌ 不在全局作用域定义状态
+```tsx
+// ❌ 错误 - 全局变量会在多个实例间共享
+let count = 0;
+
+export default function CounterWidget() {
+  count++; // 所有实例共享这个 count
+  return <view>Count: {count}</view>;
+}
+```
+
+```tsx
+// ✅ 推荐 - 使用组件内状态，实例之间互不影响
+import { useState } from '@doubao-dev/framework';
+
+export default function CounterWidget() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <view
+      onClick={() => {
+        setCount(prev => prev + 1);
+      }}
+    >
+      Count: {count}
+    </view>
+  );
+}
+```
+
+## 📚 相关文档
+
+- [组件开发指南](../guides/component-development.md)
+- [最佳实践](../guides/best-practices.md)
+- [性能优化](../guides/performance-optimization.md)

package/dist/skills/doubao-plugin-app/references/frontend/widget-templates/design-boundary.md

@@ -0,0 +1,46 @@
+# Widget 模板定制边界
+
+对话流 Widget 必须使用平台模板，最外层直接返回模板组件。模板不支持 `children`，不能自行实现卡片外壳。此约束针对 Widget，普通 Page 可按页面规范开发。
+
+模板卡片由固定外壳、标题栏、内容区和操作区组成。回答“能否这样配”时，以当前 [props.md](props.md) 的公开 props 为准，不根据相近卡型或历史实现猜测字段。
+
+## 判断顺序
+
+1. 先按 [overview.md](overview.md) 的选型决策选择当前卡型。
+2. 检查该卡型是否已有对应的 props、列表项字段或事件回调。
+3. 现有 Props 无法表达内容时，通过开发者平台提交反馈；不要自行拼装模板结构。
+4. 需要新增外壳结构、标题栏区域或底部操作区能力时，视为模板边界外需求，通过开发者平台反馈所需的新模板或设计能力。
+
+## 允许的定制
+
+- 通过 `header` 配置标题栏及右侧操作。
+- 通过 `footer` 配置一个主按钮和一个次按钮；只传一个按钮时占据整行。
+- 通过现有回调补充根节点或列表项的业务行为；不支持自定义 `className` / `style`。
+- 使用模板已有的列表项类型表达重复数据，并传稳定 `key`。
+
+## 具名内容槽位
+
+- 文本槽位仅允许字符串、数字，或直接传 primitive `Tag` / `Title`。
+- `action` 只接受模板定义的标准操作配置，不接受 ReactNode。
+- `thumbnail` / `image` 优先使用对应 URL 字段；直接单个 `<image />` 或 `<svg />` 可用于媒体内容。
+- 业务组件、fragment、原生布局容器、叠层及 primitive 外的业务包装属于自定义 UI，不作为绕过模板结构的方式。
+- 跨业务复用的视觉单元应新增为 template primitive；可用组件以 `primitives` 实际导出为准。
+
+ReactNode / ReactElement 只描述值的类别，不代表允许任意 JSX。Kit 的 Web / Lynx JSX 构建流程会检查可静态识别的槽位元素、样式入口和 widget 根节点，输出包含文件、行列和字段路径的 `[卡片检查]` warning，不改变运行时渲染，也不阻断构建。跨文件数据和无法解析的动态表达式存在检查盲区；没有 warning 不代表符合规范。
+
+## 不应绕过的边界
+
+- 不要在 Widget 或其依赖的业务组件中导入自定义 CSS、SCSS、Sass、Less、Stylus（含 CSS Modules）覆盖模板。构建检查会沿 Widget 模块依赖链输出 `widget.styles` warning；平台模板、组件和框架包自身的样式放行，普通 Page 独有样式不受此规则限制。构建器无法解析的运行时样式加载不在该检查范围内。
+- 不要在模板外再包一层 `view` 或 `scroll-view` 来重建卡片外壳。
+- 不要把底部操作区扩展为第三个按钮，或用绝对定位伪造额外区域。
+- 不要通过未公开的类名、历史 props 或其他卡型字段改变模板结构。
+- 不要为了展示更多内容自行假设模板会折叠、截断或重排行数；以对应 props 的行为说明为准。
+
+## 处理结果
+
+| 诉求 | 处理方式 |
+|------|----------|
+| 当前 props 可直接表达 | 直接使用对应字段，并遵循其类型和事件语义 |
+| 当前 Props 无法表达内容 | 不额外包裹节点，通过开发者平台提交反馈 |
+| 需要不同的卡片意图 | 回到选型决策，选择更匹配的现有模板 |
+| 需要新的结构或操作区 | 明确说明当前模板不支持，通过开发者平台提交新模板或设计需求 |

package/dist/skills/doubao-plugin-app/references/frontend/widget-templates/overview.md

@@ -0,0 +1,118 @@
+# 豆包 Widget Template Library 参考
+
+`@doubao-dev/template` 是面向 widget 开发的卡片模板库。模板已经把标题栏、内容区、信息区、价格和操作按钮等结构组合好，开发者只需要选模板并传业务数据。
+
+## 核心规则
+
+1. **一个 widget 一张卡片**：入口组件直接 return 模板组件，不要再包 `view` / `scroll-view`。
+2. **统一从 `@doubao-dev/template` 导入**模板组件和类型；新 Widget 默认直接导出组件函数。
+3. **必须使用模板**：先按选型表找模板并使用其公开 Props；匹配不上时按模板能力或新设计需求确认。
+4. **使用模板公开字段**：只使用当前模板的结构化字段或已声明的具名内容字段（文本使用字符串、数字、Tag / Title，媒体使用 image / svg）；一个业务语义需要多个已知模块时使用 `CompositeCard`，没有匹配字段时按模板能力或新设计需求确认。
+5. **显式标注列表类型**：每个模板导出 `XxxProps` 和列表项类型，例如 `ContentCardItem`、`CheckoutCardProductItem`。
+6. **header/footer 统一约定**：带标题栏和底部操作区的模板统一使用 `header` / `footer`。`header` 只控制标题栏，`footer` 只控制底部按钮，二者不影响内容区展示数量。
+7. **底部按钮对象**：`footer.primaryActionButton` / `footer.secondaryActionButton` 内传 `text`、`onClick`、`disabled`、`loading`、`throttle`。只传一个按钮时占据整行。
+8. **模板边界是强约束**：对话流 Widget 必须使用平台模板，否则无法通过审核。现有模板无法满足需求时，通过开发者平台提交反馈，不以业务诉求为由自行实现模板外的布局或样式。
+9. **内容槽位受限并接受构建检查**：模板不支持 `children`。ReactNode / ReactElement 类型不代表可以传任意 JSX；具名内容槽位只允许对应白名单，详见 [design-boundary.md](design-boundary.md)。
+
+`Title`、`Tag`、`Icon`、`OptionGroup` 和 `Price` 是卡片内容中的业务单元，不参与根卡片选型；需要标题、标签、图标、结构化选项集合或价格排版时从 `@doubao-dev/template/primitives` 导入使用。
+
+## 选型决策顺序
+
+按业务意图依次判断：
+
+1. 一个业务语义需要组合多个模板已知模块，且没有完全匹配的具名模板：用 `CompositeCard`。
+2. 核对并提交订单：通用商品、机票或出行票务订单都使用 `CheckoutCard`。
+3. 展示地图、路线、位置或叫车状态：用 `MapCard`。
+4. 展示多条交通行程：用 `TransitCard`。
+5. 在多个报价、权益或服务方案中选择：用 `PriceActionCard`。
+6. 展示并使用优惠券：用 `CouponCard`。
+7. 让用户在候选项中确认或执行固定跳转：用 `AskHumanCard`；单个或两个全宽跳转项使用 `variant="jump"`。
+8. 其余图文、商品或服务列表：用 `ContentCard`。
+
+不能按以上意图选型时，不要直接拼新的卡片外壳。先查 `CompositeCard` 的 section 白名单；白名单仍无法表达时，将其作为模板能力或新设计需求确认。
+
+## Widget 骨架
+
+```tsx
+import { ContentCard, type ContentCardItem } from '@doubao-dev/template';
+
+const items: ContentCardItem[] = [
+  {
+    key: 'a',
+    title: '主标题',
+    subtitle: '4199 元 | 商品描述',
+    description: '补充描述',
+    thumbnailSrc: 'https://example.com/p.png'
+  }
+];
+
+export default function ProductCard() {
+  return (
+    <ContentCard
+      items={items}
+      footer={{
+        secondaryActionButton: {
+          text: '查看更多',
+          onClick: () => console.log('view more')
+        },
+        primaryActionButton: {
+          text: '立即下单',
+          onClick: () => console.log('submit')
+        }
+      }}
+    />
+  );
+}
+```
+
+## 选型指南
+
+按“卡片要表达什么”选模板：
+
+| 场景 | 模板 | 一句话 |
+|------|------|--------|
+| 地图路线/位置/叫车状态 | `MapCard` | 固定高度地图 + 来源标识，可配信息区、紧凑操作和底部操作区 |
+| 商品/服务/内容列表 | `ContentCard` | 通用图文列表项，每项可带副标题、缩略内容和右侧操作 |
+| 多条可操作报价/权益/结果 | `PriceActionCard` | 每行左价格 + 中信息 + 右按钮，可配底部操作区 |
+| 优惠券展示与使用 | `CouponCard` | 根据券数量自动切换单券、双券或可横向滚动的多券布局 |
+| 下单/支付确认（通用电商） | `CheckoutCard` | 商品摘要 + 提单信息 + 费用汇总 + 合计 + 操作按钮 |
+| 机票/出行下单确认 | `CheckoutCard` | 商品或票务摘要 + 订单信息 + 费用明细 + 合计 + 操作按钮 |
+| 交通票务推荐列表 | `TransitCard` | 多条出发/到达行程，全量展示 items |
+| 车票预订等复合业务 | `CompositeCard` | 在一个标准卡片外壳中按顺序组合行程、选项组等已知模块 |
+| 让用户在多个候选里人工确认 | `AskHumanCard` | 一组可点击选项，跳过入口也通过 items 表达 |
+| 单个全宽操作按钮（任务态） | `AskHumanCard`（`variant="jump"`） | 一个可带右箭头的全宽按钮 |
+
+## 通用约定
+
+- **`header`**：标题栏配置，常用 `actionText` / `showAction` / `onActionClick`。
+- **`footer`**：底部操作区配置，常用 `primaryActionButton` / `secondaryActionButton`。
+- **`CompositeCard.sections`**：单层有序数组，只接受白名单 `type`，不接受任意 JSX；复用模块保留原有内容留白，`OptionGroup` 在组合卡内由专用容器补充左右 12px、下方 16px，上方不额外留白。
+- **图片资源**：传运行时可访问的图片 URL；本地图片放到业务项目 `src/assets` 后静态 `import` 再传入，不要直接写 `'/assets/xxx.png'`。`ContentCard` 普通缩略图使用 `thumbnailSrc`，需要媒体节点时使用 `thumbnail`，且节点优先。
+- **`onClick`**：作用在卡片根节点。卡片、列表项和 primitives 均不支持 `className` / `style`。
+- **列表项 `key`**：不传默认用数组下标，建议显式传稳定 key。
+- **行数限制**：`PriceActionCard.infoRows` 最多展示前 2 行；`ContentCard` 和 `TransitCard` 不再根据 footer 折叠内容。
+- **地图布局**：`MapCard` 统一管理地图的 168px 高度；地图覆盖物通过 `mapProps.children` 传入，不使用卡片 `children`。
+
+## 详细 Props 参考
+
+每个模板完整 props、列表项字段、行为约束见 [props.md](props.md)。先查选型表锁定模板，再到该文件确认字段。
+
+## 定制边界
+
+回答“能否这样配置”时，先确认当前 props 是否支持。没有对应 props 或明确内容槽位的结构性需求，不要通过额外包裹节点或样式覆盖伪造，按模板能力或新设计需求处理。底部操作区最多包含一个主按钮和一个次按钮。
+
+详见 [design-boundary.md](design-boundary.md)。
+
+## 常见错误
+
+| 错误 | 修正 |
+|------|------|
+| `render` 里把模板包在 `view` / `scroll-view` 里 | 直接 `return <XxxCard ... />` |
+| 想做卡片却手写 `view`+`text`+`image` 拼布局 | 先查选型表和公开 Props；没有内容槽位时按新模板或设计需求确认 |
+| 用 `children` 或额外 `view` 拼接行程和乘车人选择 | 使用 `CompositeCard`，配置 `transit`、`content` 与 `option-group` sections |
+| 继续传 `moreText` / `primaryActionText` / `secondaryActionText` | 改为 `header.actionText` 和 `footer.primaryActionButton` / `footer.secondaryActionButton` |
+| 需要单个全宽跳转操作 | 使用 `AskHumanCard variant="jump"` 和一个 `items` 项 |
+| 列表项不传 `key` 导致更新错乱 | 给每个 item 传稳定 key |
+| 用 `onClick` 当整卡和按钮的混用回调 | 底部按钮用 `footer.*ActionButton.onClick`，列表项右侧按钮用对应 action 的回调；`onClick` 是整卡或列表项点击 |
+| 期望 `TransitCard` 自动折叠 4 条以上内容 | 模板全量展示 `items`，需要折叠时由业务先处理数据并通过 footer 提供入口 |
+| 从 `react` import 模板/类型 | 模板组件与类型从 `@doubao-dev/template` 导入 |