@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/knowledge/react-page/components.md

@@ -0,0 +1,225 @@
+# React 自定义页面组件用法
+
+本文件登记 React 自定义页面可复用的 UI 组件规范。生成或修改页面前先阅读 [`generation-standards.md`](generation-standards.md)。
+
+## 使用边界
+
+- 可导入的组件包仅限 [`generation-standards.md`](generation-standards.md)“依赖白名单”中的包及其子路径
+- `@lovrabet/components` 使用包根入口的公开具名导出，不导入内部实现路径
+- 组件的用户可见文案必须使用 `$i18n.t("key")`
+- 组件样式使用 Ant Design CSS 变量，不写死颜色或其他样式常量
+- 未登记的业务组件、组件属性或行为不得猜测
+
+## `@lovrabet/components` 组件
+
+本节基于组件库 README、公开类型声明和 Storybook 用例整理。组件、属性和行为以当前发布版本的公开导出为准。页面代码从包根入口导入：
+
+```js
+import {
+  YTAIButton,
+  YTAIInput,
+  YtAddressPicker,
+  YtCodeEditor,
+  YTRichEditor,
+  YTRichEditorPreview,
+  YtUpload,
+  YtUserSelect,
+} from "@lovrabet/components";
+```
+
+| 组件 | 适用场景 | 关键使用方式 |
+| --- | --- | --- |
+| `YTAIButton` | 通过已配置的提示词或 Skill 发起 AI 调用 | 配置 `promptId` 或 `skillId` 与必填 `userPrompt`，处理成功和失败回调 |
+| `YTAIInput` | 需要输入内容后发起 AI 调用 | 配置 AI 调用参数，并使用 `inputType`、`userPromptTemplate` 和提交前校验控制输入流程 |
+| `YtUserSelect` | 选择、编辑或只读展示应用用户 | 受控传入用户 code，使用 `preview` 切换只读展示 |
+| `YtAddressPicker` | 选择或只读展示地址层级 | 受控传入地址 value 路径；需要自定义地址时传入 `options` 或 `optionsUrl` |
+| `YtUpload` | 上传、展示、预览或下载附件 | 传入当前 `appCode`，以 `value` 和 `onChange` 管理已完成的业务文件 |
+| `YTRichEditor` | 编辑富文本内容 | 用 `defaultValue` 初始化，通过 `onChange` 接收 HTML，并为图片上传提供 `upload` |
+| `YTRichEditorPreview` | 只读展示富文本 HTML | 传入必填 `content` |
+| `YtCodeEditor` | 编辑或只读展示代码、JSON 等文本 | 以 `value` 和 `onChange` 受控，按需设置 `language`、`readOnly` 和编辑器选项 |
+
+## 使用 Demo
+
+以下示例基于组件库 Storybook 用例调整而来。示例中的 `appCode`、提示词或 Skill 标识、数据和回调均由页面上下文提供；所有用户可见文案使用 `$i18n.t("key")`。示例均假设已通过 `useI18n()` 获取 `$i18n`，并按需从 React 导入 `useState`。
+
+### AI 按钮
+
+```jsx
+<YTAIButton
+  promptId={promptId}
+  userPrompt={$i18n.t("ai.userPrompt")}
+  onSuccess={setGeneratedContent}
+  onError={setError}
+>
+  {$i18n.t("ai.generate")}
+</YTAIButton>
+```
+
+使用 `skillId` 替代 `promptId` 时，同时传入 `appCode`。需要在调用前校验页面状态时，传入 `onClick` 并在不满足条件时返回 `false`。
+
+### AI 输入框
+
+```jsx
+<YTAIInput
+  inputType="textarea"
+  promptId={promptId}
+  userPromptTemplate={$i18n.t("ai.userPromptTemplate")}
+  placeholder={$i18n.t("ai.placeholder")}
+  buttonText={$i18n.t("ai.generate")}
+  onBeforeSubmit={validateInput}
+  onSuccess={setGeneratedContent}
+  onError={setError}
+/>
+```
+
+`userPromptTemplate` 中使用 `{input}` 引用输入内容。`validateInput` 返回 `false` 时不会调用 AI。
+
+### 用户选择
+
+```jsx
+const [userCodes, setUserCodes] = useState([]);
+
+<YtUserSelect
+  appCode={appCode}
+  value={userCodes}
+  onChange={setUserCodes}
+  placeholder={$i18n.t("userSelect.placeholder")}
+/>
+```
+
+只读展示时使用 `<YtUserSelect appCode={appCode} value={userCodes} preview />`。
+
+### 地址选择
+
+```jsx
+const [address, setAddress] = useState([]);
+
+<YtAddressPicker
+  options={addressOptions}
+  value={address}
+  onChange={setAddress}
+/>
+```
+
+`addressOptions` 的用户可见 `label` 必须使用词条或已确认的业务数据。只读展示时传入 `preview`。
+
+### 附件上传
+
+```jsx
+const [files, setFiles] = useState([]);
+
+<YtUpload
+  appCode={appCode}
+  accept="image/*"
+  max={maxFiles}
+  maxSizeMB={maxFileSizeMB}
+  value={files}
+  onChange={setFiles}
+/>
+```
+
+展示已有附件时，将已确认的 `YtUploadFile[]` 传给 `value`；只读预览、下载和列表展示时传入 `preview`。
+
+### 富文本编辑与预览
+
+```jsx
+const [content, setContent] = useState(initialContent);
+
+<YTRichEditor
+  defaultValue={initialContent}
+  upload={uploadImage}
+  onChange={setContent}
+  onImageUploadError={setError}
+/>
+
+<YTRichEditorPreview content={content} />
+```
+
+`uploadImage` 接收 `File` 并返回可访问图片 URL。图片上传服务和内容持久化的实现必须遵循已确认的服务契约。
+
+### 代码编辑
+
+```jsx
+const [code, setCode] = useState("");
+
+<YtCodeEditor
+  language="json"
+  value={code}
+  onChange={setCode}
+  placeholder={$i18n.t("codeEditor.placeholder")}
+  wordWrap="on"
+/>
+```
+
+只读展示时使用 `readOnly`，按需使用 `minimap`、`lineNumbers`、`tabSize` 或 `options` 配置编辑器。
+
+### AI 调用组件
+
+#### `YTAIButton`
+
+- `userPrompt` 必填
+- `promptId` 与 `skillId` 二选一，组件优先使用 `promptId`
+- 使用 `skillId` 时传入当前 `appCode`；`showPopover` 只在 Skill 场景生效
+- `onClick` 返回 `false` 可阻止本次调用；通过 `onSuccess`、`onResponse` 和 `onError` 分别处理结果、完整响应和失败
+- `options` 仅用于传入已确认的 `temperature`、`maxTokens` 等 AI 调用选项
+- 提示词标识、权限和可用环境未确认时，不生成调用代码
+
+#### `YTAIInput`
+
+- 继承 `YTAIButton` 的 AI 调用配置和回调，且不直接传入 `userPrompt`
+- 使用 `inputType="input"` 或 `inputType="textarea"` 选择输入形态，使用 `display="inline"` 或 `display="block"` 控制按钮布局
+- `userPromptTemplate` 中的 `{input}` 会替换为当前输入内容；需要特殊拼接时使用 `formatUserPrompt`
+- 使用 `onBeforeSubmit` 校验输入，返回 `false` 时阻止调用；使用 `onInputChange` 同步页面状态
+- `placeholder`、`buttonText` 和其他用户可见字符串必须传入 `$i18n.t("key")` 的结果
+
+### 选择与上传组件
+
+#### `YtUserSelect`
+
+- 当前用户列表由组件加载，页面不自行猜测或复刻用户查询接口
+- `value` 支持用户 code 数组、单个 code，以及兼容历史数据的 `{ code }` 数组；`onChange` 始终返回用户 code 数组
+- 需要只读展示时传入 `preview`
+- 传入当前 `appCode` 以明确查询上下文；`env` 只在需要覆盖当前环境识别时设置
+
+#### `YtAddressPicker`
+
+- `value` 与 `onChange` 使用 `string[]` 形式的地址层级路径
+- 传入 `options` 时使用调用方提供的级联选项；未传时使用组件内置地址数据，也可通过 `optionsUrl` 配置地址选项来源
+- 只读展示时传入 `preview`
+- 自定义选项的 `label` 为用户可见内容时，必须来自已翻译词条或已确认的业务数据
+
+#### `YtUpload`
+
+- 传入当前 `appCode`，不依赖页面自行读取宿主全局变量
+- `value` 支持 `YtUploadFile[]` 或兼容的 JSON 字符串，`onChange` 返回上传完成的业务文件列表
+- 使用 `max`、`maxSizeMB` 和 `accept` 限制上传数量、体积和文件类型；需要只读展示、预览和下载时传入 `preview`
+- 文件持久化、提交和删除由页面业务逻辑处理；先确认数据集 SDK 或其他已确认服务契约，再写入文件字段
+
+### 内容编辑组件
+
+#### `YTRichEditor` 与 `YTRichEditorPreview`
+
+- `YTRichEditor` 使用 `defaultValue` 初始化内容，`onChange` 返回 HTML 字符串或空值
+- 启用图片上传时，`upload` 必须返回可访问图片 URL；用 `onImageUploadError` 和 `onLoadError` 处理上传或资源加载失败
+- 通过 `disabled` 控制编辑状态；通过 `locale` 设置工具栏和错误提示语言
+- 使用 `YTRichEditorPreview` 或 `YTRichEditor.Preview` 展示 HTML，且必须传入 `content`
+- 需要覆盖运行资源或加载占位时，使用已确认的 `resourceUrl` 和 `loadingFallback`，不得猜测资源地址
+
+#### `YtCodeEditor`
+
+- 使用 `value` 与 `onChange` 管理编辑内容；空值按空字符串处理
+- `language`、`theme`、`minimap`、`lineNumbers`、`wordWrap`、`fontSize`、`tabSize` 和 `options` 用于配置 Monaco 编辑器
+- 需要展示不可编辑内容时使用 `readOnly` 或 `disabled`
+- 未传 `theme` 时组件跟随外层 Ant Design 主题；页面不自行猜测 Monaco 运行资源或加载方式
+
+### 非组件公开能力
+
+- `queryLLM` 是 `YTAIButton` 对应的直接 AI 调用方法。仅在已确认提示词或 Skill 标识、调用权限和错误处理策略时使用
+- `useUserList` 是 `YtUserSelect` 对应的用户列表 Hook。默认优先使用 `YtUserSelect`；仅在需要自定义交互且已确认返回结构时使用
+
+### 使用检查
+
+- 组件名称与属性以公开类型声明为准，不使用 README、Storybook 或包内部文件中未公开的实现路径
+- 所有用户可见字符串，包括按钮文本、占位文本和自定义选项 label，均使用 `$i18n.t("key")` 或来自已确认的业务数据
+- 组件的加载、空态、失败和禁用状态与页面交互一致
+- 自定义数据读取或写入仍遵循 [`generation-standards.md`](generation-standards.md) 中的数据客户端文档流程

package/skills/rabetbase/knowledge/react-page/generation-standards.md

@@ -0,0 +1,385 @@
+# React 自定义页面生成规范
+
+本规范用于编写或修改 React 自定义页面的完整 `codeContent`。执行命令流程、参数和发布规则以 [`react-custom-page-workflow.md`](../../guides/react-custom-page-workflow.md) 为准。
+
+## 使用方式
+
+在生成 JSX、CSS 或词包前，先阅读本规范，并按需加载以下文档：
+
+- 选择或组合 UI 组件时，阅读 [`components.md`](components.md)
+- 访问数据集时，先确认数据集事实，并按“数据客户端文档”拉取目标数据集的 SDK 契约
+
+未在这些文档中登记的规范、组件或方法，不得假设存在。
+
+## 固定实现约束
+
+| 范畴     | 约束                                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 提交内容 | `page react-update` 提交完整页面文件，未提交的已有文件会被删除                                                            |
+| 推荐结构 | 页面入口仍为 `src/app/index.jsx`；其余文件和组件目录可按页面需要组织，`src/app/index.css`、`src/locales/index.js`、`src/components/*.jsx` 仅为示例 |
+| 组件复用 | 优先查阅并复用已有组件库和页面已有组件；仅当现有能力无法满足需求时才创建新组件 |
+| 依赖     | 仅使用“依赖白名单”中的包及其子路径                                                                                       |
+| 文案     | 用户可见文案通过 `$i18n.t("key")` 获取，并在词包中提供翻译                                                                |
+| 路由     | 使用 `navigate` 跳转、使用 `location` 读取地址，不使用 `window.location`                                                  |
+| 样式     | 使用 Ant Design CSS 变量，不写死颜色或其他样式常量                                                                        |
+| 数据访问 | `client` 支持当前页面可用的全部 `@lovrabet/sdk` 能力，先确认数据集、SQL 或 BFF 的事实与 SDK 调用方式，再使用 `client` |
+
+### 依赖白名单（严格）
+
+- 在所有代码和文件中，包括 `src/**`、配置文件和脚本，导入仅限以下包及其子路径：
+  - `react@18`
+  - `react-dom@18`
+  - `lodash@4`
+  - `dayjs@1`
+  - `antd@5`
+  - `@ant-design/icons@5`
+  - `echarts@5`
+  - `@lovrabet/components`
+- 禁止引入、建议引入或暗示使用任何未在白名单中的依赖
+
+## 生成前信息清单
+
+生成前应确认以下信息。缺失且会影响页面行为时，先向用户确认。
+
+| 信息     | 已确认内容                         | 待补充 |
+| -------- | ---------------------------------- | ------ |
+| 页面目标 | 页面解决的问题、目标用户、完成标准 |        |
+| 页面身份 | 新建页面或已有 `pageId`            |        |
+| 布局     | 区域划分、响应式要求、视觉约束     |        |
+| 交互     | 查询、编辑、跳转、提交、确认等行为 |        |
+| 数据     | 数据集、字段、操作、权限和错误语义 |        |
+| 文案     | 语言范围、词条命名和默认文案       |        |
+
+## 页面实现分层
+
+### 入口与布局
+
+- `src/app/index.jsx` 负责页面入口、页面级状态和主布局
+- 复杂或可复用区域可按页面需要拆分到合适的相对路径，`src/components/` 仅为示例
+- 每个组件只接收其实际需要的数据和回调，避免把页面全部状态逐层透传
+
+### `src/app/index.jsx` 模板
+
+初始化创建自定义页面时，必须以此模板生成 `src/app/index.jsx`。将 `{{pageName}}` 替换为页面名称；保留词包注册、上下文 Hook 和样式导入，再按需求扩展布局、状态与数据调用。通过 `page react-create --page-content` 初始化创建时，传入的 `src/app/index.jsx` 也必须从此模板派生。
+
+更新已有页面时，以 `page react-detail` 返回的最新 `codeContent` 为基线；不强制套用或补齐本模板，应仅按更新需求修改页面内容。
+
+```jsx
+import React from "react";
+import {
+  useSdkClient,
+  useNavigate,
+  useLocation,
+  useI18n,
+} from "@/context/app-context";
+
+const App = () => {
+  const client = useSdkClient(); // 用于访问后端数据和服务
+  const $i18n = useI18n(); // 国际化多语言实例
+  const navigate = useNavigate(); // 路由跳转实例
+  const location = useLocation(); // 浏览器 location 实例
+
+  return <div className="page-container">{/* 自定义页面内容 */}</div>;
+};
+
+export default App;
+```
+
+### 数据与交互
+
+- 在调用 `client` 前按“数据客户端文档”拉取目标数据集的 SDK 契约
+- 单个数据集的常规查询和写入使用数据集模型能力；需要组合多个数据集的数据时，考虑使用自定义 SQL；数据需要个性化处理、复杂业务编排或调用外部服务时，考虑使用 BFF
+- 明确加载中、空结果、失败和成功后的页面行为
+- 写操作前明确校验、确认、提交中和失败恢复策略
+
+### 国际化与样式
+
+- 先定义词条，再在组件中使用词条 key
+- 所有用户可见文案必须使用 `$i18n.t("key")` 获取，并在 `src/locales/index.js` 中提供有效翻译，禁止硬编码字符串
+- 所有 CSS 样式必须使用 Ant Design 提供的 CSS 变量，例如 `color: var(--ant-color-primary);`，禁止直接写死色值或其他样式常量
+- 页面状态、禁用态和反馈文案与交互行为保持一致
+
+## 页面上下文内置能力
+
+### 使用边界
+
+- 仅使用本节已登记的内置能力和已确认的调用方式
+- 数据访问前先确认数据集字段、操作和 SDK 契约
+- 调用内置能力时保持组件生命周期、加载状态和错误反馈清晰
+- 未登记的方法、参数、返回结构或副作用不得猜测
+
+### 页面上下文入口
+
+页面可从 `@/context/app-context` 导入以下能力：
+
+```js
+import {
+  useSdkClient,
+  useI18n,
+  useNavigate,
+  useLocation,
+} from "@/context/app-context";
+```
+
+| 能力           | 已确认用途               | 使用前应确认                          | 详细规则       |
+| -------------- | ------------------------ | ------------------------------------- | -------------- |
+| `useSdkClient` | 获取当前页面的数据客户端 | 目标数据集、字段、操作和 SDK 调用方式 | 与 `@lovrabet/sdk` 客户端行为一致（见“数据客户端”） |
+| `useI18n`      | 获取页面国际化实例       | 词条 key 和词包翻译                   | 见“国际化”     |
+| `useNavigate`  | 获取页面路由跳转方法     | 目标页面 code 和跳转方式              | 见“导航”       |
+| `useLocation`  | 获取当前地址信息         | 需要读取的地址信息                    | 见“导航”       |
+
+### 国际化
+
+```js
+const $i18n = useI18n();
+$i18n.addLocale(locales);
+const title = $i18n.t("pageTitle");
+```
+
+- 页面加载词包后再使用词条
+- 所有用户可见文案必须使用 `$i18n.t("key")` 获取，禁止硬编码字符串
+- 每个 `$i18n.t("key")` 的 `key` 必须在 `src/locales/index.js` 中提供有效翻译
+- 词条命名、默认值和多语言回退规则在此处补充后再作为统一约定使用
+
+### 数据客户端
+
+```js
+const client = useSdkClient();
+```
+
+`client` 是运行时注入的 SDK 客户端实例，语义上与 `@lovrabet/sdk` 生成的 `createClient()` 返回对象一致，支持当前页面可用的全部 `@lovrabet/sdk` 能力。
+
+- 数据集模型调用（如 `models.<dataset>`）的语义、方法返回值、异常形态，以各 dataset 的 API-doc 返回文档为准
+- SQL、BFF 及其他非数据集能力的可用方法、参数、返回值和异常形态，均以 `@lovrabet/sdk` 的使用规范为准
+- 页面调用 SQL 前，先用 `rabetbase sql list` 与 `rabetbase sql detail --sqlcode <sqlCode>` 确认目标资源
+- 生成使用自定义 SQL 的页面代码前，使用代表性参数执行 `rabetbase sql exec --sqlcode <sqlCode> --params <json> --format json`。若返回 `data.error`，先解决执行错误；成功后再根据 `data.rows` 与 `data.rowCount` 确认实际数据结构
+- `sql exec` 仅用于确认 SQL 可执行及返回数据结构。页面代码按 `@lovrabet/sdk` 的使用规范处理 `client.sql` 的返回值，不使用 CLI 输出字段 `data.rows`
+- 页面调用 BFF 前，先用 `rabetbase bff list` 与 `rabetbase bff detail --id <id>` 确认目标资源
+- 数据操作需要注入自定义业务逻辑，例如校验、转换或加密时，优先考虑使用 BFF；页面运行时通过 `client` 按 `@lovrabet/sdk` 规范调用已确认的 BFF
+- CLI 只用于读取 SQL 与 BFF 的资源事实，页面运行时仍通过 `client` 调用，不在页面中拼接 CLI 命令或平台接口
+- 不在文档中出现的 dataset 字段、参数名、返回形态、方法名不得猜测
+- `client` 只是页面内可直接调用的入口，页面侧不在本地重新创建 `createClient` 或重复注册模型
+
+#### 数据客户端文档
+
+在生成或修改任何包含数据访问的页面代码前，获取目标数据集当前返回的 API-doc。该文档仅用于确认页面生成阶段的 SDK 契约，不得写入页面的 `codeContent`，也不得通过 `client` 在页面运行时再次请求。
+
+- 从 API-doc 确认查询、写入等数据方法的参数、响应结构和示例，并严格按该使用规范实现 `client` 调用
+- 数据集、字段、操作或权限发生变化时，重新获取 API-doc，不复用其他数据集或历史页面的调用假设
+- API-doc 的获取方式、环境地址和请求参数由当前页面平台能力提供，页面代码中不得固化这些请求细节
+
+#### 示例：API-doc 返回片段的消费方式（联系人）
+
+以下为 `联系人` 文档样例中的可用调用。示例仅用于该文档对应数据集；其他数据集必须按其文档替换签名与参数。
+
+- 目标 app：`app-c53b7ce2`
+- 数据集：`d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa`
+- SDK key：`dataset_d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa`
+
+```javascript
+// API-doc 示例可用的调用签名（完整以文档为准）:
+// filter(params)
+// getOne(id)
+// create(payload)
+// update(id, data)
+// delete(id)
+// getSelectOptions(params)
+// aggregate(params)
+// excelExport(params)
+
+const CONTACTS_DATASET_CODE = "dataset_d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa";
+const CONTACTS_DATASET_ALIAS = "crmContact";
+
+export const queryContactList = async (client, searchKeyword) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  const result = await model.filter({
+    where: {
+      name: searchKeyword ? { $contain: searchKeyword } : undefined,
+    },
+    select: ["id", "customer_id", "name", "sex", "position"],
+    orderBy: [{ id: "DESC" }],
+    currentPage: 1,
+    pageSize: 20,
+  });
+  return Array.isArray(result?.tableData) ? result.tableData : [];
+};
+
+export const queryContactDetail = async (client, id) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.getOne(id);
+};
+
+export const queryContactSelectOptions = async (client, fieldName) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.getSelectOptions({
+    code: fieldName,
+    label: fieldName,
+  });
+};
+
+export const createContact = async (client, contactPayload) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.create(contactPayload);
+};
+
+export const updateContact = async (client, id, contactPayload) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.update(id, contactPayload);
+};
+
+export const deleteContact = async (client, id) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.delete(id);
+};
+
+export const aggregateContact = async (client, params) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.aggregate(params);
+};
+
+export const exportContact = async (client, params) => {
+  const model = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+  return model.excelExport(params);
+};
+
+// 以下为文档中给出的注册信息示例（页面运行时不需要重复调用 createClient）：
+// import { registerModels, createClient } from "@lovrabet/sdk";
+// registerModels({
+//   appCode: "app-c53b7ce2",
+//   models: [
+//     {
+//       tableName: "crm_contact",
+//       datasetCode: "d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa",
+//       alias: "crmContact",
+//     },
+//   ],
+// });
+// const client = createClient();
+```
+
+#### 常见返回体处理（示例）
+
+`filter`、`aggregate` 返回常见 `paging`、`tableData`、`tableColumns`：
+
+```js
+const contactsModel = client.models.crmContact || client.models.dataset_d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa;
+const { paging, tableData, tableColumns } = await contactsModel.filter({ currentPage: 1, pageSize: 20 });
+console.log("total", paging?.totalCount);
+console.log("rows", tableData?.length ?? 0);
+console.log("columns", tableColumns?.length ?? 0);
+```
+
+其中：
+- `filter`、`aggregate` 返回字段包括 `paging.pageSize`、`paging.totalCount`、`paging.currentPage`
+- 成功返回的 `tableData` 为行数据，`tableColumns` 为列描述
+- `create`、`update`、`delete` 成功时返回 `null`
+- `excelExport` 成功时返回导出文件链接字符串
+
+### 示例：React 组件中的数据加载与错误处理
+
+```jsx
+import React, { useEffect, useState } from "react";
+import { message, Table, Button, Input } from "antd";
+import { useSdkClient, useI18n } from "@/context/app-context";
+
+const CONTACTS_DATASET_CODE = "dataset_d1c3af3347d543a7a9aa3311caf7af59_75_3c7120aa";
+const CONTACTS_DATASET_ALIAS = "crmContact";
+
+const App = () => {
+  const client = useSdkClient();
+  const $i18n = useI18n();
+  const [keyword, setKeyword] = useState("");
+  const [rows, setRows] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [selected, setSelected] = useState(null);
+
+  const loadRows = async () => {
+    setLoading(true);
+    try {
+      const contactsModel = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+      const result = await contactsModel.filter({
+        where: keyword ? { name: { $contain: keyword } } : undefined,
+        select: ["id", "name", "mobile", "email", "position"],
+        currentPage: 1,
+        pageSize: 20,
+      });
+      setRows(result?.tableData ?? []);
+    } catch (err) {
+      message.error($i18n.t("common.loadFailed"));
+      console.error("load contacts failed", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const loadDetail = async (record) => {
+    try {
+      const contactsModel = client.models[CONTACTS_DATASET_ALIAS] || client.models[CONTACTS_DATASET_CODE];
+      const detail = await contactsModel.getOne(record.id);
+      setSelected(detail);
+    } catch (err) {
+      message.error($i18n.t("common.loadDetailFailed"));
+      console.error("load contact detail failed", err);
+    }
+  };
+
+  useEffect(() => {
+    loadRows();
+  }, [keyword]);
+
+  return (
+    <div>
+      <Input
+        placeholder={$i18n.t("contact.searchPlaceholder")}
+        onChange={(event) => setKeyword(event.target.value)}
+      />
+      <Button loading={loading} onClick={loadRows}>
+        {$i18n.t("contact.search")}
+      </Button>
+      <Table
+        dataSource={rows}
+        rowKey="id"
+        onRow={(record) => ({
+          onDoubleClick: () => void loadDetail(record),
+        })}
+      />
+    </div>
+  );
+};
+
+export default App;
+```
+
+**注意事项**
+
+- 使用 `client` 前请确认该数据集当前 API-doc 的 `操作列表` 与字段，尤其是 `filter/getOne/getSelectOptions/update/create/delete` 的请求参数签名。
+- 运行时错误统一走 `try/catch`，并显示明确错误信息。
+- `dataset_d...` 这种标准 SDK key 为通用写法；若文档返回 `alias`，可改用 `client.models.<alias>`。
+- 所有示例文案仍以 `$i18n.t("...")` 作为文案入口。
+
+### 导航
+
+```js
+const navigate = useNavigate();
+const location = useLocation();
+```
+
+- 跳转使用 `navigate`，当前地址信息使用 `location`
+- 目标页面与当前页面关联时，优先使用 `navigate("/pagecode", { onePage: true })`，在当前页面基础上横向追加新页面
+- `"/pagecode"` 必须是以 `/` 开头的目标页面完整路径，可以携带参数和 hash
+- 仅当目标页面与当前页面无关联时，使用普通 `navigate("/pagecode")`
+- 不使用 `window.location`
+
+## 交付前检查
+
+- [ ] 完整页面文件包含全部需要保留的文件
+- [ ] 导入均在依赖白名单内
+- [ ] 每个本地相对导入均指向提交内容中的文件，导入名称与该文件的导出名称一致
+- [ ] 每个非全局标识符均由 import、组件参数、Hook 返回值或同一作用域内声明提供，不保留未定义引用
+- [ ] 用户可见文案均有有效词条和翻译
+- [ ] 数据集、SQL、BFF 与其他 SDK 调用的资源事实、参数和返回结构均有依据
+- [ ] 路由、状态和错误反馈符合已确认的交互
+- [ ] CSS 未写死颜色或其他样式常量
+- [ ] 已先执行 `page react-create --dry-run` 或 `page react-update --dry-run` 审阅完整提交内容，并通过 CLI 的基础 JS/JSX/TS/TSX 语法校验
+
+CLI 的基础校验只确认页面包含 `.jsx` 或 `.tsx` 文件，且页面内的 JS、JSX、TS、TSX 文件能够解析。变量引用、相对模块导出、数据调用契约和运行时行为必须由本清单和页面发布后的实际使用继续确认

package/skills/rabetbase/references/rabetbase-api-list.md

@@ -0,0 +1,58 @@
+# api list
+
+列出当前 App 下已生成的所有数据集（Dataset）模型，查看 API 客户端代码中有哪些可用 Model。
+
+## 命令
+
+```bash
+# 列出当前应用的模型
+rabetbase api list
+
+# 多应用模式：指定应用
+rabetbase api list --app order
+rabetbase api list --appcode app-order-001
+
+# 多应用：与全局合并配置一起列出时加 --global（默认仅项目级 apps）
+rabetbase api list --global
+
+# JSON 格式输出
+rabetbase api list --format json
+```
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--global` | 多应用时从「全局+项目」合并配置解析 `apps`（默认仅项目级 `apps`）。项目配置了 `inherit: false` 时见 `api pull` 文档同名词条 |
+| `--app <name>` | 多应用模式下，指定应用名称 |
+| `--appcode <code>` | 直接指定 appcode |
+| `--format json` | JSON 格式输出（用于脚本解析） |
+
+## 输出说明
+
+列出每个 Dataset 的：
+
+| 字段 | 说明 |
+|------|------|
+| `id` | Dataset ID |
+| `name` | Dataset 名称 |
+| `key` | Dataset Key |
+| `datasetCode` | Dataset Code（用于 API 调用） |
+
+## 多应用过滤
+
+多应用模式下：
+- **不加 `--app` / `--appcode`**：遍历已配置应用（默认仅 **项目** `apps`；需包含全局合并进来的应用时加 **`--global`**）
+- **加 `--app <name>`**：仅列出指定应用的模型
+- **加 `--appcode <code>`**：反查到对应 app profile，使用其 cookie/env
+
+若项目 **`inherit: false`**，`--global` 无法合并进全局 `apps`，行为与 `api pull` 一致（详见 **api pull** 文档「与 inherit: false 的关系」）。
+
+## 风险等级
+
+`read` — 仅读取，不修改文件。
+
+## 前置条件
+
+- 已完成 `rabetbase auth` 登录
+- 已运行过 `rabetbase api pull` 生成过 API 代码（用于确认本地已有哪些模型）