@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

package/skills/lab-orbit-component-builder/examples/xnb-component-template/README.md

@@ -1,176 +1,176 @@
-# AgenticLab Orbit · Vue 组件模板
-
-> **本文件只描述「模板仓库」本身**：目录约定、脚本、占位示例与本地 mock 方式。  
-> **不替代**你从本模板初始化出的**实际业务工程**里应有的产品说明、接口约定、部署与运维文档——那些请在业务仓库的 README（或 `docs/`）中**单独编写与维护**。
-
-## 本文档范围：模板说明 vs 业务工程说明
-
-| 内容 | 写在哪里 | 说明 |
-|------|----------|------|
-| 多入口、`vite.config.ts` 中的 `COMPONENT_MAP`、`dev`/`build` 脚本、私有 NPM、占位 `Demo*` 命名、示例视图在做什么 | **本 README（模板仓）** | 便于复制模板、AI/Skill 识别脚手架用法。 |
-| 产品是做什么的、领域模型、与哪些后端/Book/表交互、环境差异、发版流程、团队分工与内链 | **业务工程自己的 README / 设计文档** | 随业务迭代更新；**不要**把业务长篇写进模板仓 README，避免模板与具体项目混淆。 |
-
-从本模板拉出新仓库后，建议在业务根目录至少补充：**项目简介**、**如何配置真实环境变量**、**各入口组件职责一览**、**与 Orbit/Webb 的发布与回滚说明**（可按团队规范扩展章节）。
-
----
-
-本脚手架（模板）面向 **AgenticLab Orbit** 场景：可嵌入 XNB / Webb 的 Vue 3 视图，单仓库内维护 **多个彼此独立的入口组件**（各自 `dev:<id>`、`build:<id>` 与一份产物），便于 Agent / Skill 按流程文档生成或迭代**脚手架层**代码，并与 Orbit Book、JsCode 等能力对齐。占位名与示例逻辑**落地业务时须全部替换**。
-
----
-
-## 操作摘要（供 AI / Cursor 自动识别）
-
-以下条目请助手在「帮用户装依赖 / 起 dev / 打构建」时**优先按顺序执行**；遇到网络或 404 时，先检查是否已切到公司私有源。
-
-| 步骤 | 动作 |
-|------|------|
-| 1. Node.js | 需要 **Node.js >= 22**（见 `.nvmrc`）。建议使用 `nvm use` 或 `fnm use` 自动切换。 |
-| 2. 私有 NPM | 公司私有源地址：**`https://npm.xtalpi.io/`**（[XtalPi-NPM](https://npm.xtalpi.io/)）。须通过 **nrm**（或等价方式）把当前终端的 npm registry 指到该地址。 |
-| 3. 首次登录（仅第一次或 token 失效时） | 已切到私有源后执行 **`npm login`**（不是 `nm login`）：**用户名**为域账户 / 公司邮箱去掉 **`@` 及邮箱后缀**（仅保留 `@` 前面的本地部分，例如 `zhangsan@company.com` → 用户名填 `zhangsan`）；**密码**为域账户密码。 |
-| 4. 安装依赖 | 在项目根目录执行 **`npm install`**。 |
-| 5. 本地配置（可选） | 复制 **`.env.local.example`** 为 **`.env.local`**，按说明填写（见下文「本地环境」）。 |
-| 6. 开发调试（DEV） | 默认入口：**`npm run dev`**（超级表格 `bitable`）；多区自定义页：**`npm run dev:custom-page`**。 |
-| 7. 构建产物（BUILD） | 默认组件：**`npm run build`**；多区自定义页：**`npm run build:custom-page`**；一次打全部：**`npm run build:all`**。 |
-
-**关键词（检索用）**：`nrm`、`npm login`、`私有 npm`、`npm.xtalpi.io`、`域账户`、`npm install`、`npm run dev`、`npm run build`、`Vite`、`Orbit 组件模板`。
-
----
-
-## 安装依赖（公司私有 NPM + nrm）
-
-依赖包需要从 **晶泰 / 公司内部私有 NPM** 拉取，公网默认 registry 会安装失败或缺包。
-
-1. **安装 Node.js >= 22**（见 `.nvmrc`）。若使用 nvm：`nvm install 22 && nvm use 22`。
-2. **安装 nrm**（npm 源切换工具，用于一键切换 registry）：在终端执行  
-   `npm install -g nrm`
-3. **添加并启用公司私有源**（地址固定为下面这一行）：  
-   - 私有 registry：**`https://npm.xtalpi.io/`**  
-   - 示例命令（名称 `xtalpi` 可自定，只要 `registry` 指向上址即可）：
-     ```bash
-     nrm add xtalpi https://npm.xtalpi.io/
-     nrm use xtalpi
-     ```
-   - 可用 `npm config get registry` 确认当前源已变为 `https://npm.xtalpi.io/`。
-4. **（首次使用私有 NPM 或登录失效时）执行登录**  
-   在已切换到 **`https://npm.xtalpi.io/`** 的前提下，在终端执行：  
-   **`npm login`**  
-   按提示输入：
-   - **Username（用户名）**：域账户用户名，即**公司邮箱去掉 `@` 及后面的邮箱后缀**，只保留 `@` 前面的部分（示例：邮箱为 `zhangsan@xtalpi.com` 时，用户名填 `zhangsan`）。
-   - **Password（密码）**：你的**域账户 / 公司统一登录密码**（与邮箱登录常用密码一致，具体以 IT 说明为准）。
-   - **Email**：可按提示填写完整公司邮箱（若与 Username 策略不一致，以终端提示或 IT 文档为准）。  
-   登录成功后再进行下一步；若从未在私有源登录过，`npm install` 可能报 401 / ENEEDAUTH。
-5. **进入本仓库根目录**（与 `package.json` 同级），执行：  
-   **`npm install`**  
-   等待安装完成，无报错即表示依赖就绪。
-
-> **给非技术同事**：不必理解 nrm 原理，只需按顺序执行；**第一次**务必先做 **`npm login`**，用户名是「邮箱 @ 前面那一段」、密码是域账户密码。若 `npm install` 报错，把终端完整报错发给技术同事或 AI 助手，并说明「已切到 npm.xtalpi.io、已尝试 npm login」。
-
----
-
-## 如何运行开发调试（DEV）
-
-「开发调试」指在本机起一个带界面的网页，改代码后可热更新，用于看组件长什么样、联调 mock。
-
-1. （建议）复制 **`.env.local.example`** 为 **`.env.local`**，按需填写（见「本地环境」小节）。
-2. 在仓库根目录执行：
-   - **默认调试超级表格 Cell**：`npm run dev`  
-     与 `npm run dev:bitable` 等价。
-   - **调试自定义多区页面（无超级表格）**：`npm run dev:custom-page`
-3. 终端里会出现本地访问地址（一般为 `http://localhost:5173`），用浏览器打开即可。
-4. 停止服务：在运行 `npm run dev` 的终端里按 **Ctrl + C**。
-
-更多 `dev:<组件id>` 见 `package.json` 的 `scripts`；新增组件后需增加对应脚本。
-
----
-
-## 如何构建（BUILD）
-
-「构建」指生成可部署的 **JavaScript 包**（在项目的 **`dist/`** 目录），供 Orbit / 宿主静态引用，不是「开发网页」。
-
-1. 确保已执行过 **`npm install`**，且 registry 仍为公司私有源（同上）。
-2. 在仓库根目录执行：
-   - **只构建默认组件（超级表格 Cell）**：`npm run build`（与 `npm run build:bitable` 等价），产物在 `dist/`，主文件名由 `vite.config.ts` 中 `COMPONENT_MAP` 的 `distBaseName` 决定（当前为 `DemoOrbitBitable.*.js`）。
-   - **只构建自定义多区页面**：`npm run build:custom-page`（产物基名 `DemoOrbitCustomPage`）
-   - **按配置依次构建全部组件**：`npm run build:all`
-3. 构建成功后，将 **`dist/`** 下对应 `.umd.js` 交给发布流程或按 Orbit 文档上传。
-
-> **给非技术同事**：若只需「拿到能用的文件」，请技术同事执行构建后，从 **`dist/`** 文件夹取文件即可；你本人只需会执行 `npm run build` 并把结果交给对方。
-
----
-
-## 命名约定（与 `package.json` 解耦）
-
-| 字段（在 `vite.config.ts` 的 `COMPONENT_MAP` 中） | 含义 |
-|---------------------------------------------------|------|
-| `distBaseName` | 决定 `dist/<distBaseName>.umd.js` 文件名；**须为合法 JS 标识符**（不要含 `.`、`-`），且**不要**默认等于 `package.json` 的 `name`。 |
-| `registrarName` | 包装结果里 `component.name` 使用的字符串，供 Webb / 宿主识别；**独立于** npm 包名。 |
-
-npm 的 `package.json#name` 仅表示**这个 npm 包**本身；默认入口 `main` 应指向**默认组件**那份产物（本模板默认 id 为 **`bitable`**，当前写死为 `DemoOrbitBitable.umd.js`，你改名后请手动改 `main`）。
-
-## 本模板的适用场景（非具体业务功能说明）
-
-- 需要一套可复制的 **Orbit Vue 组件库骨架**：本地 Quasar + `@xtalpi/webb-api` mock、`xnbContext` / `window.xnb` 联调方式。
-- 需要 **lib 构建**产出供 Orbit 静态加载或宿主引用的包。
-- 作为 **Cursor Agent Skill** 的**脚手架参考**：把本 README 中「操作摘要、目录、脚本」写进 Skill；**业务规则与数据语义**应引用业务仓自己的文档，而非本模板 README。
-
-## 技术栈（摘要）
-
-Vue 3、TypeScript 5.5、Vite 5、Quasar 2、`@xtalpi/webb-api`；构建层含 Webb 组件包装插件与可选 gzip（见 `vite.config.ts`）。Node.js >= 22。
-
-## 多入口目录
-
-| 位置 | 作用 |
-|------|------|
-| `src/views/<组件 id>.vue` | 独立入口视图（与配置中的 id 同名） |
-| `src/entries/<组件 id>.ts` | 薄入口：从对应 `.vue` 导出 `View` 与 `packageData` |
-| `vite.config.ts` | `COMPONENT_MAP`：每个 id 的 `distBaseName`、`registrarName` |
-| `package.json` | 为每个 id 维护 `dev:<id>`、`build:<id>`；`main` 指向默认组件产物 |
-
-根文件 `src/index.ts` 仅默认 re-export **`bitable`** 对应入口，兼容仍指向 `./src/index.ts` 的旧脚本。
-
-### 内置两个入口（`bitable` / `custom-page`）
-
-| 视图文件 | 场景说明 |
-|----------|----------|
-| **`src/views/bitable.vue`** | 与 **超级表格 / 子 Cell** 配合：`xnbContext` 上的 **`XNBBitable`**、`new XNBBitable({ bookPath, cellUid })`、`getSubCell` 等；页级编排在 **`src/use/useBitablePage.ts`**，表格生命周期在 **`src/use/useSuperTableBitableLifecycle.ts`**；类型在 **`src/types/xnb-context.ts`**。dev 下由 **`dev/src/mockXNBBitable.ts`** 模拟宿主注入。完整数据流与宿主契约请在**你们自己的工程文档**中维护。 |
-| **`src/views/custom-page.vue`** | **多区自定义页面**占位：顶栏 + 侧栏 + 多卡片主区，**不使用** 超级表格；可单独扩展为无 XNBBitable 的页面模板。 |
-
-## 命令速查（技术向）
-
-与上文「如何运行开发调试」「如何构建」一致；更多脚本见 **`package.json` → `scripts`**。
-
-| 脚本 | 说明 |
-|------|------|
-| `npm run dev` / `dev:bitable` | 调试超级表格 Cell（`bitable`） |
-| `npm run dev:custom-page` | 调试自定义多区页面（`custom-page`） |
-| `npm run build` / `build:bitable` | 构建默认组件（基名 `DemoOrbitBitable`） |
-| `npm run build:custom-page` | 构建 `custom-page`（基名 `DemoOrbitCustomPage`） |
-| `npm run build:all` | 构建 `COMPONENT_MAP` 中全部组件 |
-
-**新增组件**：增加 `src/views/<id>.vue` 与 `src/entries/<id>.ts` → 在 **`vite.config.ts`** 的 `COMPONENT_MAP` 写 `distBaseName` 与 `registrarName` → 在 **`package.json` 的 `scripts`** 增加 **`dev:<id>`**、**`build:<id>`**；若作为默认包入口，还要改 **`main`**。
-
-## 本地环境
-
-复制 **`.env.local.example`** 为 **`.env.local`**，按需填写（详见示例内注释）。常用变量：**`VITE_DEV_TOKEN`**（统一的开发 Token，供 mock choreo 与 AgenticLab API 使用）、**`VITE_REQUEST_URL`**（dev 代理 `/api` 指向该地址）。**DEV 前建议完成**，否则部分 mock 可能告警或缺省。
-
-## Orbit 中静态加载示例（JsCode，仅模板占位）
-
-以下为**模板内**占位文件名与字段名；业务工程中请在**业务文档**里维护真实 `view` / `filename` 与宿主约定，并与 `vite.config.ts` 中 `COMPONENT_MAP` 的实际 `registrarName` / `distBaseName` 对齐（勿假设与 `package.json#name` 相同）。
-
-```js
-return () => ({
-  component: {
-    view: 'DemoOrbitBitable-View',
-    filename: 'DemoOrbitBitable.umd.js',
-    source: 'static',
-    params: {},
-    etag: `${Date.now()}`
-  }
-})
-```
-
-## Skill 与文档
-
-- **本模板 README**：供 Skill 识别「如何装依赖、起 dev、打构建、多入口配置」等脚手架信息。
-- **业务工程文档**：领域流程、门控、数据池、接口契约等，以业务仓库 README / Wiki / 流程 Skill 为准，**不要**期望在本模板 README 中展开。
-- 在 Skill 里可同时引用两类文档：脚手架段落链到本模板；业务段落链到**实际业务仓库**。改发布物时，业务侧需同步更新业务说明及 `vite.config.ts` 中 `COMPONENT_MAP`、`package.json#main` 等工程配置。
+# AgenticLab Orbit · Vue 组件模板
+
+> **本文件只描述「模板仓库」本身**：目录约定、脚本、占位示例与本地 mock 方式。  
+> **不替代**你从本模板初始化出的**实际业务工程**里应有的产品说明、接口约定、部署与运维文档——那些请在业务仓库的 README（或 `docs/`）中**单独编写与维护**。
+
+## 本文档范围：模板说明 vs 业务工程说明
+
+| 内容 | 写在哪里 | 说明 |
+|------|----------|------|
+| 多入口、`vite.config.ts` 中的 `COMPONENT_MAP`、`dev`/`build` 脚本、私有 NPM、占位 `Demo*` 命名、示例视图在做什么 | **本 README（模板仓）** | 便于复制模板、AI/Skill 识别脚手架用法。 |
+| 产品是做什么的、领域模型、与哪些后端/Book/表交互、环境差异、发版流程、团队分工与内链 | **业务工程自己的 README / 设计文档** | 随业务迭代更新；**不要**把业务长篇写进模板仓 README，避免模板与具体项目混淆。 |
+
+从本模板拉出新仓库后，建议在业务根目录至少补充：**项目简介**、**如何配置真实环境变量**、**各入口组件职责一览**、**与 Orbit/Webb 的发布与回滚说明**（可按团队规范扩展章节）。
+
+---
+
+本脚手架（模板）面向 **AgenticLab Orbit** 场景：可嵌入 XNB / Webb 的 Vue 3 视图，单仓库内维护 **多个彼此独立的入口组件**（各自 `dev:<id>`、`build:<id>` 与一份产物），便于 Agent / Skill 按流程文档生成或迭代**脚手架层**代码，并与 Orbit Book、JsCode 等能力对齐。占位名与示例逻辑**落地业务时须全部替换**。
+
+---
+
+## 操作摘要（供 AI / Cursor 自动识别）
+
+以下条目请助手在「帮用户装依赖 / 起 dev / 打构建」时**优先按顺序执行**；遇到网络或 404 时，先检查是否已切到公司私有源。
+
+| 步骤 | 动作 |
+|------|------|
+| 1. Node.js | 需要 **Node.js >= 22**（见 `.nvmrc`）。建议使用 `nvm use` 或 `fnm use` 自动切换。 |
+| 2. 私有 NPM | 公司私有源地址：**`https://npm.xtalpi.io/`**（[XtalPi-NPM](https://npm.xtalpi.io/)）。须通过 **nrm**（或等价方式）把当前终端的 npm registry 指到该地址。 |
+| 3. 首次登录（仅第一次或 token 失效时） | 已切到私有源后执行 **`npm login`**（不是 `nm login`）：**用户名**为域账户 / 公司邮箱去掉 **`@` 及邮箱后缀**（仅保留 `@` 前面的本地部分，例如 `zhangsan@company.com` → 用户名填 `zhangsan`）；**密码**为域账户密码。 |
+| 4. 安装依赖 | 在项目根目录执行 **`npm install`**。 |
+| 5. 本地配置（可选） | 复制 **`.env.local.example`** 为 **`.env.local`**，按说明填写（见下文「本地环境」）。 |
+| 6. 开发调试（DEV） | 默认入口：**`npm run dev`**（超级表格 `bitable`）；多区自定义页：**`npm run dev:custom-page`**。 |
+| 7. 构建产物（BUILD） | 默认组件：**`npm run build`**；多区自定义页：**`npm run build:custom-page`**；一次打全部：**`npm run build:all`**。 |
+
+**关键词（检索用）**：`nrm`、`npm login`、`私有 npm`、`npm.xtalpi.io`、`域账户`、`npm install`、`npm run dev`、`npm run build`、`Vite`、`Orbit 组件模板`。
+
+---
+
+## 安装依赖（公司私有 NPM + nrm）
+
+依赖包需要从 **晶泰 / 公司内部私有 NPM** 拉取，公网默认 registry 会安装失败或缺包。
+
+1. **安装 Node.js >= 22**（见 `.nvmrc`）。若使用 nvm：`nvm install 22 && nvm use 22`。
+2. **安装 nrm**（npm 源切换工具，用于一键切换 registry）：在终端执行  
+   `npm install -g nrm`
+3. **添加并启用公司私有源**（地址固定为下面这一行）：  
+   - 私有 registry：**`https://npm.xtalpi.io/`**  
+   - 示例命令（名称 `xtalpi` 可自定，只要 `registry` 指向上址即可）：
+     ```bash
+     nrm add xtalpi https://npm.xtalpi.io/
+     nrm use xtalpi
+     ```
+   - 可用 `npm config get registry` 确认当前源已变为 `https://npm.xtalpi.io/`。
+4. **（首次使用私有 NPM 或登录失效时）执行登录**  
+   在已切换到 **`https://npm.xtalpi.io/`** 的前提下，在终端执行：  
+   **`npm login`**  
+   按提示输入：
+   - **Username（用户名）**：域账户用户名，即**公司邮箱去掉 `@` 及后面的邮箱后缀**，只保留 `@` 前面的部分（示例：邮箱为 `zhangsan@xtalpi.com` 时，用户名填 `zhangsan`）。
+   - **Password（密码）**：你的**域账户 / 公司统一登录密码**（与邮箱登录常用密码一致，具体以 IT 说明为准）。
+   - **Email**：可按提示填写完整公司邮箱（若与 Username 策略不一致，以终端提示或 IT 文档为准）。  
+   登录成功后再进行下一步；若从未在私有源登录过，`npm install` 可能报 401 / ENEEDAUTH。
+5. **进入本仓库根目录**（与 `package.json` 同级），执行：  
+   **`npm install`**  
+   等待安装完成，无报错即表示依赖就绪。
+
+> **给非技术同事**：不必理解 nrm 原理，只需按顺序执行；**第一次**务必先做 **`npm login`**，用户名是「邮箱 @ 前面那一段」、密码是域账户密码。若 `npm install` 报错，把终端完整报错发给技术同事或 AI 助手，并说明「已切到 npm.xtalpi.io、已尝试 npm login」。
+
+---
+
+## 如何运行开发调试（DEV）
+
+「开发调试」指在本机起一个带界面的网页，改代码后可热更新，用于看组件长什么样、联调 mock。
+
+1. （建议）复制 **`.env.local.example`** 为 **`.env.local`**，按需填写（见「本地环境」小节）。
+2. 在仓库根目录执行：
+   - **默认调试超级表格 Cell**：`npm run dev`  
+     与 `npm run dev:bitable` 等价。
+   - **调试自定义多区页面（无超级表格）**：`npm run dev:custom-page`
+3. 终端里会出现本地访问地址（一般为 `http://localhost:5173`），用浏览器打开即可。
+4. 停止服务：在运行 `npm run dev` 的终端里按 **Ctrl + C**。
+
+更多 `dev:<组件id>` 见 `package.json` 的 `scripts`；新增组件后需增加对应脚本。
+
+---
+
+## 如何构建（BUILD）
+
+「构建」指生成可部署的 **JavaScript 包**（在项目的 **`dist/`** 目录），供 Orbit / 宿主静态引用，不是「开发网页」。
+
+1. 确保已执行过 **`npm install`**，且 registry 仍为公司私有源（同上）。
+2. 在仓库根目录执行：
+   - **只构建默认组件（超级表格 Cell）**：`npm run build`（与 `npm run build:bitable` 等价），产物在 `dist/`，主文件名由 `vite.config.ts` 中 `COMPONENT_MAP` 的 `distBaseName` 决定（当前为 `DemoOrbitBitable.*.js`）。
+   - **只构建自定义多区页面**：`npm run build:custom-page`（产物基名 `DemoOrbitCustomPage`）
+   - **按配置依次构建全部组件**：`npm run build:all`
+3. 构建成功后，将 **`dist/`** 下对应 `.umd.js` 交给发布流程或按 Orbit 文档上传。
+
+> **给非技术同事**：若只需「拿到能用的文件」，请技术同事执行构建后，从 **`dist/`** 文件夹取文件即可；你本人只需会执行 `npm run build` 并把结果交给对方。
+
+---
+
+## 命名约定（与 `package.json` 解耦）
+
+| 字段（在 `vite.config.ts` 的 `COMPONENT_MAP` 中） | 含义 |
+|---------------------------------------------------|------|
+| `distBaseName` | 决定 `dist/<distBaseName>.umd.js` 文件名；**须为合法 JS 标识符**（不要含 `.`、`-`），且**不要**默认等于 `package.json` 的 `name`。 |
+| `registrarName` | 包装结果里 `component.name` 使用的字符串，供 Webb / 宿主识别；**独立于** npm 包名。 |
+
+npm 的 `package.json#name` 仅表示**这个 npm 包**本身；默认入口 `main` 应指向**默认组件**那份产物（本模板默认 id 为 **`bitable`**，当前写死为 `DemoOrbitBitable.umd.js`，你改名后请手动改 `main`）。
+
+## 本模板的适用场景（非具体业务功能说明）
+
+- 需要一套可复制的 **Orbit Vue 组件库骨架**：本地 Quasar + `@xtalpi/webb-api` mock、`xnbContext` / `window.xnb` 联调方式。
+- 需要 **lib 构建**产出供 Orbit 静态加载或宿主引用的包。
+- 作为 **Cursor Agent Skill** 的**脚手架参考**：把本 README 中「操作摘要、目录、脚本」写进 Skill；**业务规则与数据语义**应引用业务仓自己的文档，而非本模板 README。
+
+## 技术栈（摘要）
+
+Vue 3、TypeScript 5.5、Vite 5、Quasar 2、`@xtalpi/webb-api`；构建层含 Webb 组件包装插件与可选 gzip（见 `vite.config.ts`）。Node.js >= 22。
+
+## 多入口目录
+
+| 位置 | 作用 |
+|------|------|
+| `src/views/<组件 id>.vue` | 独立入口视图（与配置中的 id 同名） |
+| `src/entries/<组件 id>.ts` | 薄入口：从对应 `.vue` 导出 `View` 与 `packageData` |
+| `vite.config.ts` | `COMPONENT_MAP`：每个 id 的 `distBaseName`、`registrarName` |
+| `package.json` | 为每个 id 维护 `dev:<id>`、`build:<id>`；`main` 指向默认组件产物 |
+
+根文件 `src/index.ts` 仅默认 re-export **`bitable`** 对应入口，兼容仍指向 `./src/index.ts` 的旧脚本。
+
+### 内置两个入口（`bitable` / `custom-page`）
+
+| 视图文件 | 场景说明 |
+|----------|----------|
+| **`src/views/bitable.vue`** | 与 **超级表格 / 子 Cell** 配合：`xnbContext` 上的 **`XNBBitable`**、`new XNBBitable({ bookPath, cellUid })`、`getSubCell` 等；页级编排在 **`src/use/useBitablePage.ts`**，表格生命周期在 **`src/use/useSuperTableBitableLifecycle.ts`**；类型在 **`src/types/xnb-context.ts`**。dev 下由 **`dev/src/mockXNBBitable.ts`** 模拟宿主注入。完整数据流与宿主契约请在**你们自己的工程文档**中维护。 |
+| **`src/views/custom-page.vue`** | **多区自定义页面**占位：顶栏 + 侧栏 + 多卡片主区，**不使用** 超级表格；可单独扩展为无 XNBBitable 的页面模板。 |
+
+## 命令速查（技术向）
+
+与上文「如何运行开发调试」「如何构建」一致；更多脚本见 **`package.json` → `scripts`**。
+
+| 脚本 | 说明 |
+|------|------|
+| `npm run dev` / `dev:bitable` | 调试超级表格 Cell（`bitable`） |
+| `npm run dev:custom-page` | 调试自定义多区页面（`custom-page`） |
+| `npm run build` / `build:bitable` | 构建默认组件（基名 `DemoOrbitBitable`） |
+| `npm run build:custom-page` | 构建 `custom-page`（基名 `DemoOrbitCustomPage`） |
+| `npm run build:all` | 构建 `COMPONENT_MAP` 中全部组件 |
+
+**新增组件**：增加 `src/views/<id>.vue` 与 `src/entries/<id>.ts` → 在 **`vite.config.ts`** 的 `COMPONENT_MAP` 写 `distBaseName` 与 `registrarName` → 在 **`package.json` 的 `scripts`** 增加 **`dev:<id>`**、**`build:<id>`**；若作为默认包入口，还要改 **`main`**。
+
+## 本地环境
+
+复制 **`.env.local.example`** 为 **`.env.local`**，按需填写（详见示例内注释）。常用变量：**`VITE_DEV_TOKEN`**（统一的开发 Token，供 mock choreo 与 AgenticLab API 使用）、**`VITE_REQUEST_URL`**（dev 代理 `/api` 指向该地址）。**DEV 前建议完成**，否则部分 mock 可能告警或缺省。
+
+## Orbit 中静态加载示例（JsCode，仅模板占位）
+
+以下为**模板内**占位文件名与字段名；业务工程中请在**业务文档**里维护真实 `view` / `filename` 与宿主约定，并与 `vite.config.ts` 中 `COMPONENT_MAP` 的实际 `registrarName` / `distBaseName` 对齐（勿假设与 `package.json#name` 相同）。
+
+```js
+return () => ({
+  component: {
+    view: 'DemoOrbitBitable-View',
+    filename: 'DemoOrbitBitable.umd.js',
+    source: 'static',
+    params: {},
+    etag: `${Date.now()}`
+  }
+})
+```
+
+## Skill 与文档
+
+- **本模板 README**：供 Skill 识别「如何装依赖、起 dev、打构建、多入口配置」等脚手架信息。
+- **业务工程文档**：领域流程、门控、数据池、接口契约等，以业务仓库 README / Wiki / 流程 Skill 为准，**不要**期望在本模板 README 中展开。
+- 在 Skill 里可同时引用两类文档：脚手架段落链到本模板；业务段落链到**实际业务仓库**。改发布物时，业务侧需同步更新业务说明及 `vite.config.ts` 中 `COMPONENT_MAP`、`package.json#main` 等工程配置。

package/skills/lab-orbit-component-builder/examples/xnb-component-template/dev/public/index.html

@@ -1,12 +1,12 @@
-<!DOCTYPE html>
-<html lang="">
-  <head>
-    <meta charset="utf-8">
-    <meta http-equiv="X-UA-Compatible" content="IE=edge">
-    <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
-    <title>Xnb Component Dev</title>
-  </head>
-  <body>
-    <div id="app"></div>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
+    <title>Xnb Component Dev</title>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>