@lovrabet/rabetbase-cli 2.5.2-beta.3 → 2.5.2-beta.4

package/skills/rabetbase/knowledge/components.md

@@ -0,0 +1,292 @@
+# 公共组件用法
+
+本文件基于 `@lovrabet/components` 最新版本的 README 和包根入口公开类型，登记可复用的 UI 组件规范。生成或修改页面前，先确认项目使用最新版本；生成或修改自定义页面时还需阅读 [`generation-standards.md`](custom-page/generation-standards.md)。
+
+## 使用边界
+
+- 自定义页面可导入的组件包仅限 [`generation-standards.md`](custom-page/generation-standards.md)“依赖白名单”中的包及其子路径
+- `@lovrabet/components` 使用包根入口的公开具名导出，不导入内部实现路径
+- 组件的用户可见文案必须使用 `$i18n.t("key")`
+- 所有组件均支持 Ant Design 主题、多语言和响应式自适应；优先继承页面配置，仅在单个组件确需覆盖时传入 `locale`
+- `env` 已废弃，后续不再透出，也不属于向用户展示或由用户选择的能力；新代码不得传入该参数
+- 组件样式优先复用 Ant Design token 和 CSS 变量，不写死主题色
+- 未登记的业务组件、组件属性或行为不得猜测
+
+## `@lovrabet/components` 组件
+
+组件、属性和行为以 `@lovrabet/components` 最新版本包根入口的公开导出为准。页面代码从包根入口导入：
+
+```js
+import {
+  YTAIButton,
+  YTAIInput,
+  YtAddressPicker,
+  YtCodeEditor,
+  YTRichEditor,
+  YTRichEditorPreview,
+  YtUpload,
+  YtUserSelect,
+} from "@lovrabet/components";
+```
+
+### 请求能力
+
+组件只消费已传入的请求实例，不负责创建或配置请求实例。`apiFetch` 用于 `YTAIButton`、`YTAIInput` 等 AI 组件；`runtimeFetch` 用于 `YtUserSelect`、`YtUpload`、`YTRichEditor` 等用户、文件和默认图片上传能力。
+
+面向新代码，请求实例的消费优先级为：组件属性传入的实例优先于 `YtConfigProvider` 注入的实例；两者均未传入时，组件使用内置的线上默认实例。页面中多个相关组件共用同一实例时，在根部通过 `YtConfigProvider` 注入；仅单个组件需要使用另一实例时，直接传入该组件的 `apiFetch` 或 `runtimeFetch` 属性。
+
+`apiFetch` 与 `runtimeFetch` 分别独立解析，不会相互替代：未传入 `runtimeFetch` 时不会使用 `apiFetch`，反之亦然。已废弃的 `env` 不属于新代码的请求实例选择规则。
+
+推荐按以下顺序使用：
+
+1. 页面内多个组件共用实例时，优先通过 `YtConfigProvider` 在根部传入。
+2. 仅个别组件需要不同实例时，再通过该组件属性覆盖根部实例。
+3. 不需要传入实例时，直接使用组件，组件会回退到内置的线上默认实例。
+
+根部共享实例时，其下未显式传入实例的相关组件都会消费对应实例：
+
+```tsx
+import { YtConfigProvider } from "@lovrabet/components";
+
+<YtConfigProvider apiFetch={apiFetch} runtimeFetch={runtimeFetch}>
+  <YtUserSelect appCode={appCode} />
+  <YtUpload appCode={appCode} />
+  <YTAIButton promptId={promptId} userPrompt={userPrompt} />
+</YtConfigProvider>;
+```
+
+单个组件传入的实例会覆盖根部同类实例，适合该组件有独立请求需求的场景：
+
+```tsx
+<YtUpload appCode={appCode} runtimeFetch={fileRuntimeFetch} />
+
+<YTAIButton apiFetch={aiApiFetch} promptId={promptId} userPrompt={userPrompt} />
+```
+
+未传入 `YtConfigProvider` 或组件级实例时，无需额外配置：
+
+```tsx
+<YtUserSelect appCode={appCode} />
+
+<YTRichEditor appCode={appCode} defaultValue={content} />
+```
+
+请求实例的创建、Domain 配置和注入位置由上层应用处理；组件文档不约定这些配置方式。
+
+| 组件 | 适用场景 | 关键使用方式 |
+| --- | --- | --- |
+| `YTAIButton` | 通过已配置的提示词或 Skill 发起 AI 调用 | 配置 `promptId` 或 `skillId` 与必填 `userPrompt`，处理成功和失败回调 |
+| `YTAIInput` | 需要输入内容后发起 AI 调用 | 配置 AI 调用参数，并使用 `inputType`、`userPromptTemplate` 和提交前校验控制输入流程 |
+| `YtUserSelect` | 多选、编辑或只读展示应用用户 | 交互值使用用户 code 字符串数组，使用 `preview` 切换只读展示 |
+| `YtAddressPicker` | 选择或只读展示地址层级 | 受控传入地址 value 路径；需要自定义地址时传入 `options` 或 `optionsUrl` |
+| `YtUpload` | 上传、展示、预览或下载附件 | 使用默认上传时必须显式传入当前有效的 `appCode`，组件不再自动注入；以 `value` 和 `onChange` 管理已完成的业务文件，使用 `maxCount` 限制数量 |
+| `YTRichEditor` | 编辑富文本内容 | 用 `defaultValue` 初始化，通过 `onChange` 接收 HTML；使用默认图片上传时必须显式传入 `appCode`，组件不再自动注入，也可通过 `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`。Skill 调用需要展示流式结果时可传入 `showPopover`，默认值为 `false`。需要在调用前校验页面状态时，传入 `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/*"
+  maxCount={maxFiles}
+  maxSizeMB={maxFileSizeMB}
+  value={files}
+  onChange={setFiles}
+/>
+```
+
+展示已有附件时，将已确认的 `YtUploadFile[]` 传给 `value`；只读预览、下载和列表展示时传入 `preview`。`max` 是已废弃的兼容属性，新代码使用 `maxCount`。
+
+自定义 `upload` 的类型为 `(file: File) => Promise<string>`。方法每次只接收一个文件，必须返回非空且可直接用于预览和下载的最终文件 URL；失败时应抛出或返回 rejected Promise，不得吞掉错误后返回空字符串。正式页面不得返回 `URL.createObjectURL(file)` 等仅在当前浏览器会话内有效的临时地址。传入 `upload` 后使用方自行负责上传服务、鉴权和服务端文件校验，组件仍负责 `maxCount`、`maxSizeMB`、`accept` 和上传状态展示；其中 `accept` 只限制文件选择器，不能替代服务端类型校验。文件与业务数据的关联、持久化和删除不属于 `upload` 方法职责。
+
+### 富文本编辑与预览
+
+```jsx
+const [content, setContent] = useState(initialContent);
+
+<YTRichEditor
+  appCode={appCode}
+  defaultValue={initialContent}
+  onChange={setContent}
+  onImageUploadError={setError}
+/>
+
+<YTRichEditorPreview content={content} />
+```
+
+未传 `upload` 时组件使用 Lovrabet 默认图片上传，此时必须由页面显式传入有效的 `appCode`。组件不再从页面配置、运行环境或其他全局信息中自动注入 `appCode`。调用方无需配置或感知内部环境参数。需要使用自定义上传时，传入接收 `File` 并返回可访问图片 URL 的 `upload(file) => Promise<string>`，此时不需要 `appCode`。`upload` 和 `appCode` 均未配置时，文字编辑和内容预览仍可使用，但图片上传功能不可用。图片上传和内容持久化仍需遵循已确认的服务契约。
+
+富文本的自定义 `upload` 每次只处理一张图片，返回值必须是可直接作为图片 `src` 使用的非空最终 URL。失败时应抛出或返回 rejected Promise，由 `onImageUploadError` 统一处理；不得返回临时 Blob URL，也不得返回包含 URL 的对象。`maxImageSize` 和 `imageAccept` 只提供编辑器侧选择与体积限制，上传服务仍需校验文件内容、类型、权限和大小。该方法只负责获得图片地址，富文本内容仍通过 `onChange` 返回并由页面业务逻辑持久化。
+
+### 代码编辑
+
+```jsx
+const [code, setCode] = useState("");
+
+<YtCodeEditor
+  language="json"
+  value={code}
+  onChange={setCode}
+  placeholder={$i18n.t("codeEditor.placeholder")}
+  wordWrap="on"
+/>
+```
+
+`YtCodeEditor` 默认使用 JSON 语言和 `240px` 高度。只读展示时使用 `readOnly`，按需使用 `minimap`、`lineNumbers`、`wordWrap`、`fontSize`、`tabSize` 或 `options` 配置编辑器；这些显式属性优先于 `options` 中的同名配置。
+
+## 主题、多语言与自适应
+
+- 所有组件继承外层 Ant Design `ConfigProvider` 的主题色以及浅色、深色算法，不需要为组件单独写死颜色
+- 组件默认跟随页面由 `@lovrabet/i18n` 管理的全局语言；确需覆盖单个组件时传入 `locale`
+- `locale` 支持 `zh-CN`、`en-US`、`id-ID`、`ja-JP` 和 `tr-TR`，显式传入时优先于页面全局语言
+- 所有组件均支持响应式自适应；页面仍应提供可收缩的容器，避免固定宽度阻止组件适配小屏
+
+### AI 调用组件
+
+#### `YTAIButton`
+
+- `userPrompt` 必填
+- `promptId` 与 `skillId` 二选一，组件优先使用 `promptId`
+- 使用 `skillId` 时传入当前 `appCode`；`showPopover` 只在 Skill 场景生效，用于展示流式结果，默认值为 `false`
+- `gradient` 默认开启；需要使用普通 Ant Design 按钮样式时传入 `gradient={false}`
+- `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`
+
+- 当前用户列表由组件加载，页面不自行猜测或复刻用户查询接口
+- 组件固定为多选模式；交互场景使用用户 code 字符串数组，`onChange` 始终返回 `string[]`
+- 读取时兼容字符串或数字类型的用户编号、历史 `{ code }[]` 以及用于旧数据展示的单个字符串或数字，新写入仍使用字符串数组
+- 需要只读展示时传入 `preview`
+- 查询应用用户列表时传入当前 `appCode`
+
+#### `YtAddressPicker`
+
+- `value` 使用 `string[] | null`，`onChange` 返回仅保留非空字符串的地址层级路径
+- 传入 `options` 时使用调用方提供的级联选项；未传时使用组件内置地址数据，也可通过 `optionsUrl` 配置地址选项来源
+- 只读展示时传入 `preview`
+- 自定义选项的 `label` 为用户可见内容时，必须来自已翻译词条或已确认的业务数据
+
+#### `YtUpload`
+
+- 使用默认上传时必须由调用方显式传入当前有效的 `appCode`，组件不会自动注入；使用自定义 `upload` 或只读预览时不依赖默认上传配置
+- 自定义 `upload` 的签名为 `(file: File) => Promise<string>`，必须返回非空、稳定且可直接预览和下载的最终文件 URL；传入后替代默认上传逻辑
+- 自定义上传失败时抛出错误或返回 rejected Promise，不返回空字符串、响应对象或仅当前会话有效的 Blob URL
+- `value` 支持 `YtUploadFile[]` 或兼容的 JSON 字符串，`onChange` 返回上传完成的业务文件列表
+- 使用 `maxCount`、`maxSizeMB` 和 `accept` 限制上传数量、体积和文件选择范围；`max` 仅用于兼容旧代码
+- `accept` 只限制文件选择器，需要严格限制文件类型时仍由上传服务校验；需要只读展示、预览和下载时传入 `preview`
+- 文件持久化、提交和删除由页面业务逻辑处理；先确认数据集 SDK 或其他已确认服务契约，再写入文件字段
+
+### 内容编辑组件
+
+#### `YTRichEditor` 与 `YTRichEditorPreview`
+
+- `YTRichEditor` 的 `defaultValue` 支持 HTML 字符串或 JSON 内容，`onChange` 返回 HTML 字符串，空内容返回 `null`
+- 未传 `upload` 时使用默认图片上传，调用方必须显式传入有效的 `appCode`；组件不会再自动注入 `appCode`
+- 传入 `upload` 时使用自定义图片上传，不需要 `appCode`；方法签名为 `(file: File) => Promise<string>`，必须返回非空、稳定且可直接作为图片 `src` 使用的最终 URL
+- 自定义图片上传失败时抛出错误或返回 rejected Promise，由 `onImageUploadError` 处理；不返回响应对象或临时 Blob URL
+- `upload` 和 `appCode` 均未配置时，文字编辑和内容预览仍可使用，图片上传功能不可用
+- 使用 `maxImageSize` 和 `imageAccept` 限制图片，使用 `onImageUploadError` 处理上传或校验失败
+- 通过 `disabled` 控制编辑状态；通过 `locale` 设置工具栏和错误提示语言
+- 使用 `YTRichEditorPreview` 或 `YTRichEditor.Preview` 展示 HTML，且必须传入 `content`
+- 需要自定义加载占位时使用 `loadingFallback`，不得猜测组件内部资源地址
+
+#### `YtCodeEditor`
+
+- 使用 `value` 与 `onChange` 管理编辑内容；空值按空字符串处理
+- `language`、`theme`、`minimap`、`lineNumbers`、`wordWrap`、`fontSize`、`tabSize` 和 `options` 用于配置 Monaco 编辑器
+- 需要展示不可编辑内容时使用 `readOnly` 或 `disabled`
+- 未传 `theme` 时组件跟随外层 Ant Design 主题；页面不自行猜测 Monaco 运行资源或加载方式
+
+### 非组件公开能力
+
+- 包根入口公开 `useUserList`，用于自定义用户选择交互；默认优先使用 `YtUserSelect`，仅在已确认 Hook 返回结构时直接调用
+- `queryLLM` 未从 `@lovrabet/components` 包根入口公开，不导入内部路径；需要 AI 调用时使用 `YTAIButton` 或 `YTAIInput`
+
+### 使用检查
+
+- 组件名称与属性以公开类型声明为准，不使用 README、Storybook 或包内部文件中未公开的实现路径
+- `YTRichEditor` 和 `YtUpload` 使用默认上传时，确认代码显式传入当前有效的 `appCode`，不得依赖历史默认注入行为
+- 所有用户可见字符串，包括按钮文本、占位文本和自定义选项 label，均使用 `$i18n.t("key")` 或来自已确认的业务数据
+- 组件的加载、空态、失败和禁用状态与页面交互一致
+- 自定义数据读取或写入仍遵循 [`generation-standards.md`](custom-page/generation-standards.md) 中的数据客户端文档流程

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

@@ -6,7 +6,7 @@
 
 在生成 JSX、CSS 或词包前，先阅读本规范，并按需加载以下文档：
 
-- 选择或组合 UI 组件时，阅读 [`components.md`](components.md)
+- 选择或组合 UI 组件时，阅读 [`components.md`](../components.md)
 - 访问数据集时，先确认数据集事实，并按“数据客户端文档”拉取目标数据集的 SDK 契约
 
 未在这些文档中登记的规范、组件或方法，不得假设存在。
@@ -15,7 +15,7 @@
 
 | 范畴     | 约束                                                                                                                      |
 | -------- | ------------------------------------------------------------------------------------------------------------------------- |
-| 提交内容 | `page custom-update` 提交完整页面文件，未提交的已有文件会被删除                                                            |
+| 提交内容 | `page custom-update --page-dir <dir>` 提交目录中的完整页面文件，未包含的已有文件会被删除                               |
 | 推荐结构 | 页面入口仍为 `src/app/index.jsx`；其余文件和组件目录可按页面需要组织，`src/app/index.css`、`src/locales/index.js`、`src/components/*.jsx` 仅为示例 |
 | 组件复用 | 优先查阅并复用已有组件库和页面已有组件；仅当现有能力无法满足需求时才创建新组件 |
 | 依赖     | 仅使用“依赖白名单”中的包及其子路径                                                                                       |
@@ -46,7 +46,7 @@
 | -------- | ---------------------------------- | ------ |
 | 页面目标 | 页面解决的问题、目标用户、完成标准 |        |
 | 页面身份 | 新建页面或已有 `pageId`            |        |
-| 布局     | 区域划分、响应式要求、视觉约束     |        |
+| 布局     | 区域划分、响应式要求（PC Web 与 mobile）以及视觉约束     |        |
 | 交互     | 查询、编辑、跳转、提交、确认等行为 |        |
 | 数据     | 数据集、字段、操作、权限和错误语义 |        |
 | 文案     | 语言范围、词条命名和默认文案       |        |
@@ -58,16 +58,22 @@
 - `src/app/index.jsx` 负责页面入口、页面级状态和主布局
 - 复杂或可复用区域可按页面需要拆分到合适的相对路径，`src/components/` 仅为示例
 - 每个组件只接收其实际需要的数据和回调，避免把页面全部状态逐层透传
+- 建议根据具体需求优先考虑自适应设计，尽量避免不必要的固定像素宽高和固定列数；页面需要同时用于 PC Web 与 mobile 时，建议兼顾两端的展示与交互。对于明确限定终端、尺寸或布局的场景，可采用与需求匹配的固定方案
+
+### 内置页面模板
+
+`BLANK`、`ONEPAGE` 和 `DASHBOARD` 的选型、内容边界、mock 数据替换、创建与更新方式及交互设计统一见 [`page-templates.md`](page-templates.md)。本文件只维护页面实现所需的数据访问、主题、路由、国际化、ECharts 和源码约束。
 
 ### `src/app/index.jsx` 模板
 
-初始化创建自定义页面时，必须以此模板生成 `src/app/index.jsx`。将 `{{pageName}}` 替换为页面名称；保留词包注册、上下文 Hook 和样式导入，再按需求扩展布局、状态与数据调用。通过 `page create --page-content` 初始化创建时，传入的 `src/app/index.jsx` 也必须从此模板派生。
+初始化创建自定义页面时，必须以此模板生成 `src/app/index.jsx`。将 `{{pageName}}` 替换为页面名称；保留词包注册、上下文 Hook 和样式导入，再按需求扩展布局、状态与数据调用。通过 `page create --page-dir <dir>` 初始化创建时，目录中的 `src/app/index.jsx` 也必须从此模板派生。
 
 更新已有页面时，以 `page custom-detail` 返回的最新 `codeContent` 为基线；不强制套用或补齐本模板，应仅按更新需求修改页面内容。
 
 ```jsx
 import React from "react";
 import {
+  useAppTheme,
   useSdkClient,
   useNavigate,
   useLocation,
@@ -79,6 +85,9 @@ const App = () => {
   const $i18n = useI18n(); // 国际化多语言实例
   const navigate = useNavigate(); // 路由跳转实例
   const location = useLocation(); // 浏览器 location 实例
+  const theme = useAppTheme(); // 当前主题（可能未提供）
+  const mode = theme?.mode; // "light" | "dark"
+  const skinColor = theme?.skinColor; // 十六进制色值，如 "#ababab"
 
   return <div className="page-container">{/* 自定义页面内容 */}</div>;
 };
@@ -133,6 +142,7 @@ export default App;
 
 ```js
 import {
+  useAppTheme,
   useSdkClient,
   useI18n,
   useNavigate,
@@ -146,6 +156,66 @@ import {
 | `useI18n`      | 获取页面国际化实例       | 词条 key 和词包翻译                   | 见“国际化”     |
 | `useNavigate`  | 获取页面路由跳转方法     | 目标页面 code 和跳转方式              | 见“导航”       |
 | `useLocation`  | 获取当前地址信息         | 需要读取的地址信息                    | 见“导航”       |
+| `useAppTheme`  | 获取当前主题             | 主题是否可用与组件兼容性              | 见“主题配置”   |
+
+### 主题配置
+
+在页面中调用 `useAppTheme()` 即可读取当前主题；没有主题时返回 `undefined`。
+
+```js
+const theme = useAppTheme();
+const mode = theme?.mode; // "light" | "dark"
+const skinColor = theme?.skinColor; // 十六进制色值，如 "#ababab"
+```
+
+- 不要依赖 `theme` 一定存在；所有访问必须使用可选链或默认值
+- `mode` 与 `skinColor` 为运行期提示，不替代完整的 Ant Design 主题系统
+- 推荐使用 `antd` 主题系统设置主题色，优先复用 `ConfigProvider` 的 `token`、`algorithm` 与组件 token
+- 新增页面逻辑涉及颜色时，推荐优先使用当前 `ConfigProvider` 提供的 token 或 CSS 变量，让按钮、链接、选中态和自定义区域尽量跟随应用主题色变化
+
+### antd 主题色使用 Demo
+
+```jsx
+import { Card, ConfigProvider, theme as antdTheme } from "antd";
+import { useAppTheme, useI18n } from "@/context/app-context";
+
+const isThemeColor = (value) =>
+  /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value || "");
+
+const getThemeConfig = (appTheme) => ({
+  cssVar: { key: "custom-page-theme" },
+  algorithm:
+    appTheme?.mode === "dark"
+      ? antdTheme.darkAlgorithm
+      : antdTheme.defaultAlgorithm,
+  ...(isThemeColor(appTheme?.skinColor)
+    ? {
+        token: {
+          colorPrimary: appTheme.skinColor,
+        },
+      }
+    : {}),
+});
+
+const App = () => {
+  const $i18n = useI18n();
+  const appTheme = useAppTheme();
+
+  return (
+    <ConfigProvider theme={getThemeConfig(appTheme)}>
+      <Card title={$i18n.t("title")}>{$i18n.t("content")}</Card>
+    </ConfigProvider>
+  );
+};
+
+export default App;
+```
+
+- 推荐做法（最佳实践，可按页面实际情况调整，不作为强制要求）：
+  - `mode === "dark"` 时可使用 `antdTheme.darkAlgorithm`，其他情况可使用 `antdTheme.defaultAlgorithm`
+  - `skinColor` 合法时可作为 `colorPrimary`；未传入或不合法时建议不设置该 token，交由 Ant Design 使用默认主题色
+  - 需要在 CSS 中使用 token 时，建议启用 `cssVar`，随后使用 `var(--ant-color-primary)`、`var(--ant-color-bg-layout)` 等变量，减少直接写死 hex
+  - 仅使用组件 token 时，可以不启用 `cssVar`
 
 ### 国际化
 

package/skills/rabetbase/knowledge/custom-page/page-templates.md

@@ -0,0 +1,68 @@
+# 自定义页面模板
+
+本文档集中说明自定义页面内置模板的选择、内容边界和使用方式。页面开发约束、数据访问、主题、路由、国际化和 ECharts 规范见 [`generation-standards.md`](generation-standards.md)。
+
+## 模板选择
+
+| 模板 | 适合场景 | 模板内容 |
+| --- | --- | --- |
+| `BLANK` | 从空白页面和基础布局开始实现 | 页面入口、基础样式、词包和主题示例，不包含具体业务内容或业务数据 |
+| `ONEPAGE` | 综合页面、一页式业务工作台，或需要在一个页面内集中完成业务数据的查看、编辑、操作和管理 | 一页式工作台布局，包含业务概览、关联记录、详情和后续处理区域 |
+| `DASHBOARD` | 通过指标卡、趋势、分布和对比等图表多维展示业务数据 | 基于 ECharts 的响应式仪表盘布局，包含指标、筛选、图表和明细入口 |
+
+模板随 CLI npm 包发布并从本地读取，不依赖 CDN：
+
+| 模板 | 本地文件 |
+| --- | --- |
+| `BLANK` | `templates/custom-pages/blank.json` |
+| `ONEPAGE` | `templates/custom-pages/onepage.json` |
+| `DASHBOARD` | `templates/custom-pages/dashboard.json` |
+
+## 内容与数据边界
+
+- `BLANK` 是空白基础页面，不包含具体业务内容或示例业务数据，使用时从实际页面需求开始补充内容和数据接入。
+- `ONEPAGE` 和 `DASHBOARD` 只提供布局、主题和交互示例，其中的数据均为 mock，不直接读取或写入业务数据。
+- 使用 `ONEPAGE` 或 `DASHBOARD` 时，必须使用真实的业务数据集替换全部 mock 数据，不把模板内容作为最终页面发布。
+- 替换数据前先确认实际数据集、字段、关联关系、统计口径、可用操作和权限范围。
+- 按 [`generation-standards.md`](generation-standards.md) 中的数据访问方式，通过 `useSdkClient()` 获取页面提供的 `client`，使用 `client` 完成数据查询和写入，不在页面中另建客户端或自行拼接接口。
+- 数据接入同时处理加载状态、空态、失败提示和重试；需要额外权限或业务规则控制时，按页面开发规范使用受控 BFF。
+
+## 创建和更新
+
+内置模板既用于初始化页面，也用于已有页面的实现参考。页面已经生成或已有完整内容时，仍可根据实际需求参考对应模板的布局、主题、组件组织和交互方式；此时只选择性合并需要的实现，不要求重新创建页面，也不能直接使用模板覆盖已有内容。
+
+创建页面时，通过 `--page-pattern` 使用内置模板初始化：
+
+```bash
+rabetbase page create --page-pattern <BLANK|ONEPAGE|DASHBOARD> --name <name> --appcode <appCode> --dry-run
+```
+
+创建页面时必须显式选择一种来源：使用内置模板时传入 `--page-pattern <BLANK|ONEPAGE|DASHBOARD>`；使用完整本地页面内容时传入 `--page-dir <dir>`。两个参数不能同时使用，也不能同时省略。
+
+使用 `--page-dir` 创建已经准备好内容的页面时，也可先参考模板实现，再提交完整页面文件。更新已有页面时，`page custom-update` 不接受 `--page-pattern`；先通过 `page custom-detail` 获取最新完整页面内容，再按需要参考 `BLANK`、`ONEPAGE` 或 `DASHBOARD`，选择性合并后提交。
+
+## `ONEPAGE` 交互设计
+
+`ONEPAGE` 以当前页面作为业务上下文中心，在一个页面中高效完成业务数据的查看、编辑、操作和管理；存在上下游或关联业务时，通过打开子页面连接完整业务链路。
+
+- 主页面集中展示当前业务对象、关联数据、处理进度和可执行操作，减少在多个菜单之间切换。
+- 查看、新增或编辑关联数据时，优先使用 `navigate("/pagecode", { onePage: true })` 打开子页面，保留主页面的筛选条件、选中记录和操作上下文。
+- 子页面关闭或操作完成后，回到主页面并刷新受影响的关联列表、详情和统计信息，同时保持当前操作位置。
+- 使用前确认真实页面 code、数据集关联关系、可用操作和权限范围，并替换模板中的 mock 数据和示例入口。
+
+## `DASHBOARD` 交互设计
+
+`DASHBOARD` 在一个页面中组合指标数据和图表，从总览、趋势、分布、构成和对比等维度集中展示业务数据情况。
+
+- 先展示关键指标和整体状态，再通过图表呈现变化、差异和构成，避免堆叠与页面目标无关的图表。
+- 时间范围、分类条件和统计维度统一管理，并联动更新相关指标和图表。
+- 图表通过提示信息、图例切换和数据项点击查看具体维度；需要查看明细时，可在当前页面展开明细，或通过 `navigate("/pagecode", { onePage: true })` 打开子页面。
+- 进入明细和返回看板时保留筛选条件和查看位置。
+- 指标和图表分别处理加载、空态、失败和重试，避免单个区域异常阻断整个页面。
+- 使用前确认真实数据来源、统计口径、权限和可用操作；ECharts 只负责呈现，不承担数据访问、业务计算或权限判断。
+
+## 主题适配
+
+- 页面通过 `useAppTheme()` 获取应用主题配置，并通过 Ant Design 主题系统应用 `mode` 和 `skinColor`。
+- 推荐复用 Ant Design token 和 CSS 变量，不在业务代码中直接写死主色值。
+- `ONEPAGE` 和 `DASHBOARD` 的布局、组件和图表颜色都需要同时适配亮色与暗色模式。

package/skills/rabetbase/references/rabetbase-page-create.md

@@ -7,7 +7,9 @@
 ```bash
 rabetbase page create --page-pattern BLANK --name "客户看板" --appcode <appCode> --dry-run --format compress
 rabetbase page create --page-pattern BLANK --name "客户看板" --parent-menu-id 100 --appcode <appCode>
-rabetbase page create --name "客户看板" --page-content '<json>' --appcode <appCode>
+rabetbase page create --page-pattern ONEPAGE --name "客户看板" --appcode <appCode> --dry-run --format compress
+rabetbase page create --page-pattern DASHBOARD --name "业务数据看板" --appcode <appCode> --dry-run --format compress
+rabetbase page create --name "客户看板" --page-dir ./customer-dashboard --appcode <appCode>
 ```
 
 ## 参数
@@ -16,16 +18,26 @@ rabetbase page create --name "客户看板" --page-content '<json>' --appcode <a
 |---|---|---|
 | `--name <name>` | 否 | 可选页面名称，1–100 个字符；省略时默认 `Custom_page_<timestamp>` |
 | `--parent-menu-id <id>` | 否 | 父菜单 ID |
-| `--page-pattern <pattern>` | 条件必填 | 页面模式；当前只支持 `BLANK`，与 `--page-content` 必须且只能提供一个 |
-| `--page-content <json>` | 条件必填 | 完整页面文件 JSON；对象的键为相对路径，值为文件内容，与 `--page-pattern` 必须且只能提供一个 |
+| `--page-pattern <pattern>` | 条件必填 | 页面模式；支持 `BLANK`、`ONEPAGE`、`DASHBOARD`，不能与 `--page-dir` 同时使用；模板详情见 [`page-templates.md`](../knowledge/custom-page/page-templates.md) |
+| `--page-dir <dir>` | 条件必填 | 完整页面文件目录；不能与 `--page-pattern` 同时使用，目录必须包含文件；CLI 递归读取目录内的常规文件，将相对路径和 UTF-8 文件内容作为完整页面文件提交 |
 | `--appcode <code>` | 是 | 目标应用 code |
 
+## 页面内容来源
+
+1. 使用内置模板时显式传入 `--page-pattern`
+2. 使用完整页面文件时显式传入 `--page-dir`
+3. 两者同时提供、均未提供或目录为空时，本地校验失败
+
 ## 执行步骤
 
-1. 使用基础模板时传 `--page-pattern BLANK`；已有完整源码时只传 `--page-content`。
-2. 使用 `--dry-run` 确认页面名称、父菜单与最终页面文件。
-3. 确认后使用相同参数执行创建。
-4. 从结构化输出的 `data.after.pageId` 确认新页面 ID，并核对 `data.pageType=CUSTOM`；模式创建返回 `data.pagePattern=BLANK`，完整源码创建返回 `null`。
-5. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。
+1. 不使用页面模板时，若本地已有完整页面目录，直接将该目录传给 `--page-dir`；若本地没有已有内容，则先在当前工作目录创建临时专用页面目录并生成完整页面文件，再传 `--page-dir`。CLI 读取目录后负责转换为请求内容，调用方不需要也不得自行拼接 `page-content` JSON。
+2. 使用内置模板时，按 [`page-templates.md`](../knowledge/custom-page/page-templates.md) 选择 `BLANK`、`ONEPAGE` 或 `DASHBOARD`，并显式传入对应的 `--page-pattern`。
+3. 使用 `--dry-run` 确认页面名称、父菜单与最终页面文件。
+4. 确认后使用相同参数执行创建。
+5. 仅当步骤 1 创建了临时页面目录时，正式创建流程成功、失败、中断或取消后删除该目录，删除范围仅限本流程创建的临时目录；通过 `--page-dir` 传入的本地已有页面目录不得删除。
+6. 创建成功时，从结构化输出的 `data.after.pageId` 确认新页面 ID，并核对 `data.pageType=CUSTOM`；模板创建返回对应的 `data.pagePattern`，目录创建返回 `data.pagePattern=null`。
+7. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。
+
+页面创建始终同时创建菜单。`BLANK`、`ONEPAGE` 与 `DASHBOARD` 分别读取内置的 `templates/custom-pages/blank.json`、`templates/custom-pages/onepage.json` 与 `templates/custom-pages/dashboard.json` 作为完整页面文件。未发布模式会在本地失败，不请求服务端。
 
-页面创建始终同时创建菜单。`BLANK` 模式会按应用语言设置生成词包；读取设置失败时使用默认中英文词包。未发布模式会在本地失败，不请求服务端。
+三个模板的适用场景、内容边界、mock 数据替换、真实数据接入和交互设计统一见 [`page-templates.md`](../knowledge/custom-page/page-templates.md)。页面开发和 `client` 使用方式见 [`generation-standards.md`](../knowledge/custom-page/generation-standards.md)。

package/skills/rabetbase/references/rabetbase-page-custom-detail.md

@@ -23,4 +23,4 @@ rabetbase page custom-detail --id <pageId> --format compress
 - `runtimePageUrl`：查看已发布内容的页面地址，仅在有已发布内容时返回；host 为 `<appCode>.<appDomain host>`
 - `editPageUrl`：打开当前节点或独立部署工作台中的页面编辑器
 
-`data.codeContent` 是当前完整页面文件，可在本地完成新增、修改或删除后，作为 `page custom-update --page-content <json>` 的完整页面内容提交。
+`data.codeContent` 是当前完整页面文件。将其写入本地目录后完成新增、修改或删除，再以 `page custom-update --page-dir <dir>` 提交该目录中的完整页面内容。

package/skills/rabetbase/references/rabetbase-page-custom-update.md

@@ -1,10 +1,10 @@
 # page custom-update
 
-以完整页面文件 JSON 更新 自定义页面，并创建新的保存版本。未包含的文件会被删除。
+从本地目录读取完整页面文件更新 自定义页面，并创建新的保存版本。目录中未包含的文件会被删除。
 
 ```bash
-rabetbase page custom-update --id <pageId> --page-content '<json>' --dry-run --format compress
-rabetbase page custom-update --id <pageId> --page-content '<json>' --appcode <appCode>
+rabetbase page custom-update --id <pageId> --page-dir <dir> --dry-run --format compress
+rabetbase page custom-update --id <pageId> --page-dir <dir> --appcode <appCode>
 ```
 
 ## 参数
@@ -12,13 +12,17 @@ rabetbase page custom-update --id <pageId> --page-content '<json>' --appcode <ap
 | 参数 | 必填 | 说明 |
 |---|---|---|
 | `--id <pageId>` | 是 | 自定义页面 ID |
-| `--page-content <json>` | 是 | 完整页面文件 JSON；对象的键为相对路径，值为文件内容 |
+| `--page-dir <dir>` | 是 | 包含完整页面文件的本地目录，CLI 递归读取其中的常规文件 |
 | `--appcode <code>` | 否 | 目标应用 code，省略时根据 `pageId` 查询 |
 
 ## 执行步骤
 
-1. 先使用 `page custom-detail` 读取 `data.codeContent` 中的完整页面文件。
-2. 在本地完成所有文件新增、修改或删除后，使用 `--dry-run` 确认完整页面文件。
-3. 确认后使用相同参数执行更新。
-4. 从结构化输出的 `data.after.version` 确认已保存新版本。
-5. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。
+1. 先使用 `page custom-detail` 读取 `data.codeContent` 中的完整页面文件，并写入专用本地目录。
+2. 需要调整页面布局或交互时，以具体需求和最新页面文件为准。[`page-templates.md`](../knowledge/custom-page/page-templates.md) 中的 `BLANK`、`ONEPAGE` 和 `DASHBOARD` 仅作为可选参考；模板实现适合当前需求时，可将相关结构、样式和交互选择性合并到最新页面文件中，不要求使用模板。
+3. 在该目录完成所有文件新增、修改或删除后，使用 `--page-dir` 与 `--dry-run` 确认完整页面文件。
+4. 确认后使用相同参数执行更新。
+5. 正式更新命令结束后，无论成功、失败或中断，删除步骤 1 创建的临时页面目录，删除范围仅限该目录。
+6. 从结构化输出的 `data.after.version` 确认已保存新版本。
+7. 输出的 `pageUrl` 用于查看最新保存内容，包含尚未发布的修改；`editPageUrl` 用于打开页面编辑器，继续修改页面。
+
+`page custom-update` 不接受 `--page-pattern`。内置模板在更新场景中仅作为实现参考，详细规则见 [`page-templates.md`](../knowledge/custom-page/page-templates.md)；更新始终以 `page custom-detail` 返回的最新完整页面内容为基线，避免覆盖已有功能和尚未发布的修改。

package/skills/rabetbase/references/rabetbase-project-create.md

@@ -57,6 +57,9 @@ rabetbase project create my-project --appcode <code>
 
 `api pull` 的单应用/项目应用清单输出结构见 [`rabetbase-api-pull.md`](rabetbase-api-pull.md)，TypeScript 合并规则见 [`sdk-client-generation.md`](../guides/sdk-client-generation.md)。Agent 可根据实际输出选择检查、修复和验证方式。
 
+
+项目创建完成后，如需在子应用页面中使用公共组件，先阅读 [`components.md`](../knowledge/components.md) 确认最新组件用法，并可参考项目内 `src/pages/components-demo` 的交互和实现。`components-demo` 必须在项目配置了有效 AppCode 后使用，优先在创建工程时传入 `--appcode <code>`；如创建后补充 AppCode，需执行 `rabetbase config set appcode <code>` 和 `rabetbase api pull` 完成初始化，否则用户选择、附件上传等依赖应用信息的组件无法使用。示例中的 mock 数据和富文本图片 mock 上传仅用于展示效果，正式页面需按实际业务替换。
+
 ## 提示
 
 - `--name` 和位置参数二选一，`--name` 优先
@@ -67,7 +70,7 @@ rabetbase project create my-project --appcode <code>
 - 交互与非交互模式使用同一创建流程，都会安装依赖、格式化代码并写入项目配置
 - 项目模板从 CDN 下载并校验 SHA-256；CDN 不可用、模板不兼容或校验失败时命令停止，修复后重试
 - 新项目中的 `.rabetbase.json` **只继承**全局中的少量偏好及 `region` / Domain 路由配置，**不会**把全局的 `apps` / `defaultApp` 复制进新项目
-- `src/api/sdk-config.ts` 与 `rabetbase.domain-routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；Domain 配置变化后用 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 刷新项目快照。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新；若项目创建时首次拉取失败，按 CLI 提示执行 `rabetbase api pull --force --yes` 完成占位脚手架初始化
+- `src/api/sdk-config.ts` 与 `rabetbase.domain-routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；`rabetbase run start|dev|build|preview` 会在执行脚本前刷新公开 Domain 快照，也可用 [`project domain-routing-sync`](rabetbase-project-domain-routing-sync.md) 立即显式刷新。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新；若项目创建时首次拉取失败，按 CLI 提示执行 `rabetbase api pull --force --yes` 完成占位脚手架初始化
 
 | 当前有效路由 | `src/api/sdk-config.ts` |
 |--------------|-------------------------|
@@ -76,7 +79,7 @@ rabetbase project create my-project --appcode <code>
 | Global | `{ runtimeDomain: "https://runtime.lovrabet.ai" }`，兼容 SDK 1.5.3 |
 | 独立部署 | `{ runtimeDomain: "https://…" }` |
 
-模板依赖 SDK 1.5.3+。CLI 从统一 Routing Profile 生成 `rabetbase.domain-routing.json`，其中只包含最终 User/App/Runtime Domain、`cdn.libraries`、`cdn.lovrabet`、本地地址和证书 URL，不复制节点注册表。每个官方节点直接配置两个 CDN 地址；中国大陆当前使用 AliCDN，印尼当前使用 Cloudflare cdnjs，任一新节点都可以使用独立 CDN。企业独立部署使用清单中的显式值。
+模板依赖 SDK 1.5.3+。CLI 从统一 Routing Profile 生成 `rabetbase.domain-routing.json`，其中只包含最终 API/User/App/Runtime/Skill/KB Domain、`cdn.libraries`、`cdn.lovrabet`、本地地址和证书 URL，不复制节点注册表。每个官方节点直接配置两个 CDN 地址；中国大陆当前使用 AliCDN，印尼当前使用 Cloudflare cdnjs，任一新节点都可以使用独立 CDN。企业独立部署使用清单中的显式值。
 
 ## 参考
 

package/skills/rabetbase/references/rabetbase-project-domain-routing-sync.md

@@ -16,12 +16,12 @@ rabetbase project domain-routing-sync --format compress
 - 不要求登录或 AppCode，不访问平台，不生成全局副本。
 - 该文件供项目模板与 Vite 消费，不是 React Router、页面 path 或菜单路由配置。
 
-生成内容只包含公开信息：User/App/Runtime Domain、资源策略、本地开发 Domain 与可选证书 URL；不会写入 Cookie、AccessKey 等认证配置。
+生成内容只包含公开信息：API/User/App/Runtime/Skill/KB Domain、资源策略、本地开发 Domain 与可选证书 URL；不会写入 Cookie、AccessKey 等认证配置。
 
 ## 使用时机
 
 - `project create` 会自动完成首次生成，无需紧接着重复执行。
-- 修改项目级 Domain 配置后执行。
+- 修改项目级 Domain 配置后需要立即刷新时执行；后续执行 `rabetbase run start|dev|build|preview` 也会在脚本启动前自动刷新。
 - 全局 Domain 配置变化且当前项目需要采用新结果时执行。
 - 文件缺失或模板提示重新生成时执行。