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

package/skills/rabetbase/guides/custom-page-workflow.md

@@ -20,10 +20,24 @@
 ### 新建页面
 
 1. 先阅读 [`rabetbase-page-create.md`](../references/rabetbase-page-create.md)
-2. 使用基础模板时传 `--page-pattern BLANK`；已有完整源码时只传 `--page-content`。先执行 `page create --dry-run`，确认页面名称、父菜单和最终页面文件
-3. 经用户确认后创建页面，记录 `data.after.pageId`。新页面默认尚未发布
-4. 执行 `page custom-detail --id <pageId>`，以 `data.codeContent` 中的完整页面文件为修改基线
-5. 需要定制初始文件时，再按“更新页面”流程保存完整页面文件
+2. 阅读 [`page-templates.md`](../knowledge/custom-page/page-templates.md)，先判断内置模板能否作为页面的主要结构和交互起点；适合时选择 `BLANK`、`ONEPAGE` 或 `DASHBOARD`，不适合时按完整页面内容创建。模板也可在创建或更新页面时作为布局、主题和交互实现参考
+3. 根据模板判断和本地内容情况选择创建方式：
+
+| 内容来源 | 处理方式 |
+|---|---|
+| 使用内置模板 | 直接传 `--page-pattern <BLANK|ONEPAGE|DASHBOARD>`，由 CLI 读取对应模板 |
+| 不使用内置模板，且没有本地已有内容 | 在当前工作目录创建临时专用页面目录，生成完整 JSX、样式、词包和组件文件，再将该目录传给 `--page-dir <dir>` |
+| 本地已有完整页面目录 | 直接将该目录传给 `--page-dir <dir>`，无需创建临时目录或重新生成内容 |
+
+模板只能作为局部实现参考，或创建后需要替换其中大部分文件时，按不使用内置模板处理，直接准备完整页面目录并使用 `--page-dir`。
+
+`--page-pattern` 与 `--page-dir` 必须且只能选择一个；两者同时提供、均未提供，或 `--page-dir` 指向空目录时，本地校验失败。CLI 会递归读取 `--page-dir` 指向的目录并转换为页面请求内容，Agent 不得自行拼接或转码 `page-content` JSON
+4. 先使用与正式创建相同的 `--page-pattern` 或 `--page-dir` 参数执行 `page create --dry-run`，确认页面名称、父菜单和最终页面文件
+5. 经用户确认后执行正式创建命令
+6. 仅当步骤 2 为从零生成内容而创建了临时目录时，流程成功、失败、中断或用户取消后都删除该目录；删除范围仅限本次创建的临时目录，不得删除用户已有页面目录
+7. 创建成功时记录 `data.after.pageId`。新页面默认尚未发布
+8. 执行 `page custom-detail --id <pageId>`，以 `data.codeContent` 中的完整页面文件为修改基线
+9. 需要定制初始文件时，再按“更新页面”流程保存完整页面文件
 
 创建页面会同时创建菜单入口。不得额外调用菜单创建命令重复创建入口。
 
@@ -37,15 +51,18 @@
 ### 更新页面
 
 1. 阅读 [`rabetbase-page-custom-update.md`](../references/rabetbase-page-custom-update.md)
-2. 将新增、修改和保留的所有文件整理为完整 `page-content` JSON
-3. 先执行 `page custom-update --dry-run` 审阅完整页面文件
-4. 经用户确认后执行更新
-5. 再执行 `page custom-detail --id <pageId>`，确认 `codeContent` 已包含预期文件和内容
-6. 已发布页面更新后，最新保存内容需要再次发布，用户访问的已发布页面才能看到本次修改
+2. 以 `page custom-detail` 返回的最新完整页面内容为修改基线
+3. 需要调整页面模式或交互时，可参考 `BLANK`、`ONEPAGE` 或 `DASHBOARD` 的布局、主题和交互实现，按实际需求选择性合并；模板仅作为实现参考，不直接覆盖已有页面
+4. 将新增、修改和保留的所有文件整理到一个专用本地目录
+5. 先执行 `page custom-update --page-dir <dir> --dry-run` 审阅完整页面文件
+6. 经用户确认后执行更新
+7. 正式更新命令结束后，无论成功、失败或中断，都删除步骤 4 创建的临时页面目录，删除范围仅限该目录
+8. 再执行 `page custom-detail --id <pageId>`，确认 `codeContent` 已包含预期文件和内容
+9. 已发布页面更新后，最新保存内容需要再次发布，用户访问的已发布页面才能看到本次修改
 
-`page custom-update` 会完整保存页面文件：未提交的文件会被删除。不得仅提交本次修改的单个文件，也不得为删除文件再调用不存在的独立删除命令。
+`page custom-update` 会完整保存页面文件：传入目录中未包含的文件会被删除。不得只保留本次修改的单个文件，也不得为删除文件再调用不存在的独立删除命令。
 
-当前 CLI 没有逐文件新增、编辑或删除命令。将本地文件操作整理为完整 `codeContent` 后再调用 `custom-update`；每次更新都会创建一个新的保存版本，`custom-detail` 默认读取最新页面内容。
+当前 CLI 没有逐文件新增、编辑或删除命令。将本地文件操作整理到完整目录后再调用 `custom-update`；每次更新都会创建一个新的保存版本，`custom-detail` 默认读取最新页面内容。
 
 ### 发布页面
 
@@ -62,7 +79,8 @@
 自定义页面的 React JSX 实现有“未发布”和“已发布”两种状态。未发布的修改可通过 `pageUrl` 或编辑器查看，已发布页面只展示最近一次发布的内容。
 
 ```text
-page create --page-pattern BLANK
+page create --page-pattern <BLANK|ONEPAGE|DASHBOARD>
+或 page create --page-dir <dir>
   → 未发布
   → 生成或更新完整页面文件
   → 未发布
@@ -139,7 +157,7 @@ page create --page-pattern BLANK
 
 编写页面内容前，先阅读 [`generation-standards.md`](../knowledge/custom-page/generation-standards.md)。
 
-- 选择、组合或新增 UI 组件时，按需阅读 [`components.md`](../knowledge/custom-page/components.md)
+- 选择、组合或新增 UI 组件时，按需阅读 [`components.md`](../knowledge/components.md)
 - 调用页面上下文、国际化、路由或数据客户端时，按需阅读 `generation-standards.md` 中的“页面上下文内置能力”
 - 未登记的组件、方法、参数和返回结构不得猜测，先补充确认后的规范再复用
 
@@ -157,14 +175,14 @@ src/components/*.jsx
 代码遵循以下约束：
 
 - 仅导入 [`generation-standards.md`](../knowledge/custom-page/generation-standards.md)“依赖白名单”中的包及其子路径
-- 使用页面上下文时，从 `@/context/app-context` 导入 `useSdkClient`、`useI18n`、`useNavigate`、`useLocation`
+- 使用页面上下文时，从 `@/context/app-context` 导入 `useSdkClient`、`useI18n`、`useNavigate`、`useLocation`、`useAppTheme`
 - 数据读取或写入前，先确认数据集及 SDK 用法；接口或字段无法从现有事实确认时，不得猜测请求协议
 - 所有用户可见文案通过 `$i18n.t("key")` 获取，并在 `src/locales/index.js` 提供有效翻译
 - 路由跳转使用 `navigate`，读取地址信息使用 `location`；关联页面优先使用 `navigate("/pagecode", { onePage: true })`
 - CSS 使用 Ant Design CSS 变量，不写死颜色或其他样式常量
 - 不新增白名单外依赖，不使用 `window.location`
 
-传 `--page-pattern BLANK` 时，`page create` 生成基础 JSX、样式和词包。首次自定义时，将初始文案和样式一并调整为上述约束后再发布，不把初始化模板视为最终页面实现。
+内置模板的本地文件、内容边界、mock 数据替换方式以及 `ONEPAGE`、`DASHBOARD` 交互设计统一见 [`page-templates.md`](../knowledge/custom-page/page-templates.md)。页面通过 `client` 访问真实业务数据的方式仍按 [`generation-standards.md`](../knowledge/custom-page/generation-standards.md) 执行。
 
 ## 页面内容自检
 
@@ -183,7 +201,7 @@ src/components/*.jsx
 ## 最小验证闭环
 
 ```text
-新建：create --page-pattern BLANK --dry-run → create --page-pattern BLANK → custom-detail → [按需] custom-update --dry-run → custom-update → custom-detail → [尚未发布（status 非 FORMAL）且经确认] custom-publish --dry-run → custom-publish
+新建：选择 --page-pattern <BLANK|ONEPAGE|DASHBOARD> 或 --page-dir <dir> → 使用相同来源参数执行 create --dry-run → create → custom-detail → [按需] custom-update --dry-run → custom-update → custom-detail → [尚未发布（status 非 FORMAL）且经确认] custom-publish --dry-run → custom-publish
 
 修改：custom-list（按需）→ custom-detail → custom-update --dry-run → custom-update → custom-detail → [尚未发布（status 非 FORMAL）且经确认] custom-publish --dry-run → custom-publish
 ```
@@ -198,5 +216,5 @@ CLI 当前不提供本地预览或独立删除命令。
 - [`rabetbase-page-custom-update.md`](../references/rabetbase-page-custom-update.md)
 - [`rabetbase-page-custom-publish.md`](../references/rabetbase-page-custom-publish.md)
 - [`generation-standards.md`](../knowledge/custom-page/generation-standards.md)
-- [`components.md`](../knowledge/custom-page/components.md)
+- [`components.md`](../knowledge/components.md)
 - [`rabetbase-codegen-sdk.md`](../references/rabetbase-codegen-sdk.md)

package/skills/rabetbase/guides/page-development-workflow.md

@@ -39,7 +39,7 @@
 - 标准管理后台
 - 单数据集或轻度关联数据集
 
-如果目标是工作台、看板、时间轴或复杂协作视图，它不属于数据列表页工作流，但仍然属于页面需求，应使用 `rabetbase page create --page-pattern BLANK` 或 `--page-content` 创建 CUSTOM JSX 页面。`rabetbase project` 表达的是独立子应用工程，不是页面类型，也不是复杂页面的兜底入口。
+综合操作页面、工作台、时间轴和复杂协作视图不走数据列表页工作流，应使用自定义页面。内置模板的选型、内容边界和交互模式见 [`page-templates.md`](../knowledge/custom-page/page-templates.md)；已有完整页面文件时使用 `--page-dir <dir>`。`rabetbase project` 用于独立子应用工程，不作为自定义页面类型或复杂页面的兜底入口。
 
 ### 2. 校验数据集与关联页
 

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` 的布局、组件和图表颜色都需要同时适配亮色与暗色模式。