@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

package/skills/lab-orbit-component-builder/SKILL.md

@@ -1,353 +1,353 @@
----
-name: lab-orbit-component-builder
-description: >-
-  根据流程说明 Markdown（门控「人工处理」与数据池 Schema）在 Orbit Vue 3 工程内生成/迭代超级表格组件。
-  默认渲染刷新/检查/提交按钮，仅暴露 string/number 列，仅「可人工录入」字段可编辑，按池 Schema 约束校验，提交参数与 ticket schema 对齐。
-  模板内 examples/xnb-component-template/src/views/ 下的 bitable.vue 与 custom-page.vue 仅供阅读参考，执行时禁止复制到用户目标目录。
-  Use when scaffolding Orbit Vue cells from flow docs, super-table manual pages, bitable columns from pool Schema, or AgenticLab ticket/execution APIs.
-compatibility: Orbit Book Vue Cell; window.xnb + props.xnbContext; Vite 5 lib build; company private npm per template README
-metadata:
-  version: "1.3.0"
-  runtime: Orbit-XNB-Vue-Component
-  template_path: examples/xnb-component-template
----
-
-# Studio · Orbit Vue 组件生成技能
-
-## 能力范围
-
-| 本技能**负责** | 本技能**不负责** |
-|----------------|------------------|
-| 从**流程文档**中识别门控 **「人工处理」** 小节，在同一 Vue 工程下生成**独立入口组件**（SFC + `entries` + `vite.config.ts` `COMPONENT_MAP` 条目） | 流程注册包目录结构、`pools/*.md` 全量自动生成、门控 YAML/脚本落库 |
-| 按 **`examples/xnb-component-template`** 的目录、构建脚本、类型与 composable 风格编写/扩展代码 | 替用户配置公司私有 NPM 账号；生产环境密钥写入仓库 |
-| **XNBBitable**：`new XNBBitable({ bookPath, cellUid })`、子表操作、全量 list 时 **`items` 整表替换** | Book 内 **JsCode** 字符串拼接 UI |
-| **HTTP**：宿主内优先 **`window.xnb.http.client.request`**；模板内 **`orbitRequestJson`** | 非 AgenticLab / 非模板已文档化接口的臆造路径 |
-| **`xnbContext`**：通过组件 **props** 注入 | 修改宿主 `xnb-jscode` 仓库源码 |
-
----
-
-## 默认行为规则（硬性要求）
-
-以下规则在**每次**生成/迭代组件时**必须**遵守，除非用户**明确描述**了不同的需求。
-
-### 规则 1：请求数据（刷新）
-
-1. **Opener 参数获取**：页面挂载后调用 `fetchOpenerInitPayload` 获取 opener 回包；子页发 `{ msg: 'get-data', trace }`，**流程宿主**回 `{ msg: 'get-data-response', trace, ticket_ids, valve_id, ... }`（见 `openerInitParams.ts`，兼容 `msg: 'data' + payload`）。
-   - 若获取失败（`ok: false`）且无开发环境回退（`VITE_DEV_OPENER_INIT_JSON`），**必须**：
-     - 在界面上展示**产品化提示**（如 `q-banner`）：**「没有获得有效参数，请关闭页面重试。」**（英文页面：**"Failed to obtain valid parameters. Please close the page and try again."**）
-     - **禁止**在页面上显示技术术语（Error 对象、堆栈、skipped reason 等）；技术细节仅输出到 `console.warn`
-     - **禁用**刷新/检查/提交按钮（`:disable="!!openerInitError"`），阻止后续一切数据操作
-   - 从 `payload` 中提取 `ticket_ids`（用 `extractTicketIdsFromPayload`）和 `valve_id`（用 `extractValveIdFromPayload`）
-2. **Token 获取链**（优先级从高到低）：
-   - 参数传入的静态 token
-   - `await window.xnb.choreo.getUserToken()`（Orbit 宿主注入）
-   - `import.meta.env.VITE_DEV_TOKEN`（本地开发用，勿提交生产密钥）
-3. **接口地址**：`import.meta.env.VITE_AGENTICLAB_API_URL`，嵌入 Orbit 时 `orbitRequestJson` 自动走宿主代理
-4. **触发请求**：`fetchAgenticlabTicketList` → 映射为表格行 → 整表替换 `bitable.items` → `updateSubBitable`
-
-### 规则 2：渲染交互和数据
-
-1. **默认按钮**：**必须**渲染以下三个按钮（除非用户明确描述去掉、修改或新增功能）：
-   - **刷新**（`onRefresh`）：重新拉取数据，整表替换，操作前弹确认框
-   - **检查**（`onCheck`）：校验当前表格数据是否满足约束
-   - **提交**（`onSubmit`）：先校验再提交，操作前弹确认框
-   - **样式主题与按钮（超级表格页）**：默认对照 `examples/xnb-component-template/src/views/bitable.vue` 的 DOM / 类名 / `q-btn` 写法，并 `@import '@/styles/orbit-quasar-host.scss'`（见规则 6）。**除非**流程文档或用户任务**明确描述**了不同样式，否则遵守：
-     - **主题**：Cell 内 Quasar 主题以 `examples/xnb-component-template/src/styles/orbit-quasar-host.scss` 为准；需新增或调整主色、`q-btn` 全局表现等，**只改该文件**（勿在业务 SFC 内散落 `--q-primary` 或重复定义）。
-     - **`color="primary"`**：仅用于**会提交或修改持久化数据**的按钮（默认即「提交」/`onSubmit`）；刷新、检查等**不得**使用 `primary`。
-     - **`outline`**：仅用于**页面内数据交互**（拉数、校验、本地检查等，默认即「刷新」「检查」）；提交**不得**使用 `outline`（用 `color="primary" dense unelevated`，与 `bitable.vue` 一致）。
-     - 勿对工具栏按钮使用 `secondary` / `accent` 等未在模板出现的 `color`。
-2. **列类型限制**：默认**仅** `string`（`dv: { type: 'text_length' }`）和 `number`（`dv: { type: 'number' }, ct: { fa: '0', t: 'n' }`）类型的字段被渲染为表格列。
-   - **json** 类型字段**默认不展示**为列
-   - 若用户明确描述了自定义渲染逻辑：渲染前拆解（如 `JSON.stringify` 摘要或提取子字段），提交时重新组装回原始结构
-3. **可编辑性**：流程文档数据池中标记「**可人工录入**」的字段设 `readonly: false`；其余字段一律 `readonly: true`。
-
-### 规则 3：校验数据
-
-1. **默认校验**：按流程文档中数据池定义的字段约束自动生成校验逻辑：
-   - number 列：范围、正数、必填等（从 Schema 约束推导）
-   - text 列：非空、格式（条码、路径等）
-   - 必填字段：Schema 中标记 required 的字段检查非空
-2. **自定义校验**：仅在用户**明确描述**更多校验规则时才增加
-3. **执行时机**：`checkRows` 在 `submitRows` 之前**必须**被调用，校验不通过时阻止提交
-
-### 规则 4：提交数据
-
-1. **获取表格数据**：从超级表格通过 `getAllSubBitable` / `getSubBitable` 获取当前 `items`（含用户编辑后的值）
-2. **参数映射**：
-   - 仅将**可编辑字段**（`readonly: false`）的修改值映射为可提交参数
-   - 提交参数**必须与 ticket schema 定义对齐**：将编辑值写回 ticket `detail` 中对应路径（如 `detail.process_params['@requested_amount_mg']`）
-   - 使用 `lastAgenticRawTickets`（最近一次 GET 的原始工单）与表格编辑值合并，构建完整的 `tickets` 数组
-3. **提交请求**：Token 获取链与刷新请求一致 → `postAgenticlabExecutionComplete({ baseUrl, token, valveId, tickets })`
-
-### 规则 5：配置
-
-1. **环境变量文件**：
-   - **`.env.local`**（gitignored）：含 `VITE_DEV_TOKEN`（开发用 Token）和 `VITE_AGENTICLAB_API_URL`（接口地址）
-   - 生产环境 Token 由 `getUserToken()` 运行时提供，**禁止**将 Token 写入仓库
-2. **统一变量名**：
-   - `VITE_DEV_TOKEN`：统一了原 `VUE_APP_NOCOBASE_DEV_TOKEN` 与 `VUE_APP_AGENTICLAB_TOKEN`
-   - `VITE_AGENTICLAB_API_URL`：AgenticLab API 根地址
-
-### 规则 6：生成禁令（模板 views 示例）
-
-`examples/xnb-component-template/src/views/bitable.vue` 与 `custom-page.vue` 是模板内的**演示用示例**。
-
-**样式主题（Quasar）**：页面入口默认参照 `examples/xnb-component-template/src/views/bitable.vue`（布局、工具栏、`q-btn` 属性分工）与 `examples/xnb-component-template/src/styles/orbit-quasar-host.scss`（主题变量与 `:deep(.q-btn)`）。根节点须 `orbit-quasar-host`，`<style scoped lang="scss">` 首行 `@import '@/styles/orbit-quasar-host.scss'`。用户或流程要求调整主题时，**优先只改** `src/styles/orbit-quasar-host.scss`，业务 SFC 仅保留页面级局部类（如 `bitable.vue` 中的 banner / `row-count`）。
-
-**执行本技能向用户目标目录产出时：**
-
-- **禁止**将上述两个文件**原样复制**到用户工程（或仅改少量字符串后当作交付组件）
-- **禁止**以「复制 `bitable.vue` 改名」替代需求分析
-- **应当**以二者及 `useBitablePage` / `useSuperTableBitableLifecycle` 等为**参考**，按流程文档与门控语义**新建** `src/views/<业务语义>.vue`（及对应 `entries/<id>.ts`、配置项），文件名与 UI 文案须与业务一致；**bitable 类**写模板前对照 `bitable.vue` + `orbit-quasar-host.scss`（见规则 2「样式主题与按钮」）
-
-若用户仓库是由模板整体 fork 而来且仍需保留模板自带示例入口，可保留原文件；**新增**业务门控页时仍须**新建**独立 SFC。
-
-### 规则 7：代码安全（避免运行时类型错误）
-
-1. **`<style>`**：
-   - **页面入口**（本技能新建的 `src/views/<业务>.vue` 等独立 Cell 根组件）：**必须**根节点带 `orbit-quasar-host`，`<style scoped lang="scss">` 首行 `@import '@/styles/orbit-quasar-host.scss'`，与模板一致以统一 Quasar 风格。
-   - **非页面入口**的生成 `.vue`（如子组件）：`<style scoped>` **必须**纯 CSS，**禁止** `lang="scss"` / `lang="sass"`；样式变量用 CSS 自定义属性（`var(--c-xxx)`），避免无必要拉满 SCSS 链、在不同 `sass-loader` 版本下出现 `raw.trim is not a function` 等构建错误。
-2. **字段值安全转换**：在 `mapRowToItem`、`checkRows` 等映射/校验函数中，从行数据或 API 响应取出的字段值**必须**先转为字符串再做字符串操作：
-   ```typescript
-   // ✅ 正确：先 String() 转换
-   fields[field] = raw == null ? '' : String(raw)
-   // ❌ 错误：raw 可能是 number / object，导致 "raw.trim is not a function"
-   fields[field] = raw.trim()
-   ```
-3. **模板插值安全**：`{{ }}` 中引用的变量若可能为非字符串（如 API 返回的 `number`、`null`），须在 computed / 方法中先做 `String()` 或 `?? ''` 兜底，禁止在模板中直接对非字符串调用字符串方法。
-
----
-
-## 渐进披露（何时读哪份文件）
-
-默认先读本页与 **`references/vue-template-checklist.md`**；需要细节时再打开：
-
-| 需求 | 打开（相对本技能根目录） |
-|------|---------------------------|
-| 从流程文档拆 **人工处理**、多门控多组件、命名与配置表 | [`references/flow-document-human-ui.md`](references/flow-document-human-ui.md) |
-| **props `xnbContext`** 与 JsCode 对照 | [`references/xnb-context-vue-props.md`](references/xnb-context-vue-props.md) |
-| 池 **Schema** → 列定义、可编辑字段策略、校验规则 | [`references/pool-schema-to-columns.md`](references/pool-schema-to-columns.md) |
-| XNBBitable 行为、全量刷新、反模式 | [`references/xnbitable-vue-parity.md`](references/xnbitable-vue-parity.md)；模板 [`examples/xnb-component-template/OrbitAPI.md`](examples/xnb-component-template/OrbitAPI.md) |
-| Vue/TS 编码约定、命名、组件拆分策略 | [`references/orbit-vue-conventions.md`](references/orbit-vue-conventions.md) |
-| 工单列表、`/api/execution/complete`、opener `ticket_ids` | 模板 [`examples/xnb-component-template/AgenticAppAPI.md`](examples/xnb-component-template/AgenticAppAPI.md) |
-| 装依赖、`dev`/`build`、多入口配置 | 模板 [`examples/xnb-component-template/README.md`](examples/xnb-component-template/README.md) |
-
-## 与 **orbit-write-js-cell** 的关系
-
-- **orbit-write-js-cell**：面向 Book **JsCode** Cell（`return` HTML、`window.xnb.cell.register`）。
-- **本技能**：面向 **Vue 3 SFC**，用 Composition API + props 表达同一套运行时。
-- **XNBBitable 业务语义**必须与 orbit-write-js-cell / API.md 一致，实现形式改为 Vue。
-
----
-
-## 工作流（给 Agent）
-
-### 0.0 理解与确认（编码前）
-
-对于**首次生成**或**较大范围增量修改**，在开始编码前：
-
-1. **理解**：读完流程文档中目标门控的「人工处理」章节、输入池 Schema、以及目标目录下的现有代码
-2. **确认**：向用户简要复述理解——哪个门控、哪些字段成为列、哪些字段可编辑、校验规则如何，请求确认
-3. **执行**：确认后按方案实施
-
-> 若变更范围明确（如仅修改一列的校验规则或新增一个按钮），可跳过确认步骤直接执行。
-
-### 0. 判断工程状态：首次生成 or 增量修改
-
-**在做任何事之前，先确定目标目录，然后检查该目录：**
-
-**目标目录优先级**：
-
-1. **用户指定了具体工程路径** → 使用该路径
-2. **用户仅指定了流程文档路径** → 在文档**所在目录下创建工程子目录**，目录名从流程名称 / 文档文件名提炼为 `kebab-case`（如文档 `fragment-flow-mini-2-pool-20260611-人工录入.md` → 创建 `xnb-component-fragment-flow-mini-2/`）。**禁止**将工程文件直接平铺到文档所在目录
-3. **均未指定** → 在当前工作目录（CWD）下创建工程子目录，命名规则同上
-
-**工程目录命名规则**：`xnb-component-<流程语义>`，从流程名称 / 文档文件名提炼 kebab-case，去掉日期、版本号等非语义后缀。一个流程的所有门控人工处理页统一放在同一个工程目录下（一个工程多入口）。
-
-1. 查看目标目录下是否存在 `package.json` 且包含 `vite`（devDependencies）、`vite.config.ts`、`src/use/useBitablePage.ts` 等脚手架标志文件。
-2. **若不存在** → 进入 **「首次生成」** 流程（步骤 1A）。
-3. **若已存在** → 进入 **「增量修改」** 流程（步骤 1B）。
-
-> **禁止**在已有工程上重复执行首次生成流程（会覆盖已有业务代码）。
-> **禁止**在空目录上执行增量修改流程（缺少脚手架基础设施，代码无法运行）。
-
-### 0.1 输入识别（首次和增量均需执行）
-
-1. 确认用户提供的 **流程文档**路径（或粘贴「门控」章节）：定位每个门控下的 **`#### 人工处理`** 及 **`##### 界面形态与数据绑定`** 列表项。
-2. 读取同文档中的 **人工处理配置项**表（如 `AppBaseUrl`、`数据查询上限`、`语言类型`），映射到环境变量与代码常量（见 **`references/flow-document-human-ui.md`**）。
-3. 若文档给出门控 **输入池** 及 Schema 表：提取列名、字段类型、标题、**是否可人工录入**，用于生成列定义与编辑/只读策略（见 **`references/pool-schema-to-columns.md`**）。
-4. **若 opener 初始化逻辑未能获取到必要参数**，生成的组件**必须**在界面上展示产品化提示（如「没有获得有效参数，请关闭页面重试。」），并禁用所有数据操作按钮（刷新/检查/提交）。**禁止**在页面上展示技术术语（Error 对象、堆栈等），技术细节仅输出到 `console.warn`。
-
-### 1A. 首次生成（目标目录无工程）
-
-**目标**：在目标工程目录下（按 §0 创建或定位），从模板 `examples/xnb-component-template` 搭建完整工程，再生成业务组件。
-
-#### 第一步：复制脚手架基础设施
-
-从模板目录**复制以下文件/目录**到用户目标目录（保持相对路径不变）：
-
-| 类别 | 文件 |
-|------|------|
-| 构建配置 | `package.json`、`vite.config.ts`、`vite.dev.config.ts`、`tsconfig.json`、`index.html`、`.nvmrc` |
-| 代码规范 | `.eslintrc.cjs`、`.eslintignore`、`.gitignore` |
-| 构建脚本 | （内置于 `vite.config.ts` 与 `package.json` scripts，无需 `scripts/` 目录） |
-| 组件配置 | `vite.config.ts`（`COMPONENT_MAP` 后续步骤会覆盖其组件条目） |
-| 环境配置 | `.env.local.example` |
-| CI | `Jenkinsfile` |
-| 类型 | `src/types/xnb-context.ts` |
-| 工具函数 | `src/utils/openerInitParams.ts`、`src/utils/openerTicketIds.ts`、`src/utils/orbitHttpClient.ts` |
-| API | `src/api/agenticlabTickets.ts` |
-| Composable | `src/use/useBitablePage.ts`、`src/use/useSuperTableBitableLifecycle.ts` |
-| Dev 调试 | `dev/` 整个目录（`public/`、`src/App.vue`、`src/main.ts`、`src/mockXNBBitable.ts`、`src/global.d.ts`、`src/shims-vue.d.ts`） |
-| 测试 | （Vite 模板不内置测试文件，按需添加 vitest） |
-| 文档 | `OrbitAPI.md`、`AgenticAppAPI.md`、`README.md` |
-
-**不要复制的文件**（仅作阅读参考）：
-
-| 文件 | 原因 |
-|------|------|
-| `src/views/bitable.vue` | 示例视图，业务入口须按流程文档新建 |
-| `src/views/custom-page.vue` | 示例视图，业务入口须按流程文档新建 |
-| `src/entries/bitable.ts` | 示例入口，随业务视图新建 |
-| `src/entries/custom-page.ts` | 示例入口，随业务视图新建 |
-| `src/use/useSuperCellDemo.ts` | 演示用 composable，业务不需要 |
-| `src/index.ts` | 默认导出占位，业务工程按需重写 |
-
-#### 第二步：生成业务组件
-
-按流程文档中的每个门控「人工处理」：
-
-1. 新建 `src/views/<业务语义>.vue`（按规则 1-4 实现 opener、列定义、校验、提交）
-2. 新建 `src/entries/<id>.ts`
-3. 更新 `vite.config.ts` 中的 `COMPONENT_MAP`（**清空**模板示例的 `bitable` / `custom-page` 条目，仅保留业务条目）；**保留** `build.emptyOutDir: false`（多组件顺序构建时防止后续 build 清空前序产物）
-4. `package.json`：**`version` 须在每次生成/修改时递增**（初次生成设为 `1.0.0`；迭代修改按变更范围递增 patch/minor/major）；其余字段（`name`、`main`、`dependencies`、`devDependencies`、`webb` 等）**原样保留**模板内容**禁止改动**，仅在 `scripts` 中**追加** `dev:<id>` / `build:<id>` 条目；多组件时须有 `build:all`（顺序执行所有 `build:<id>`）。**通用 `dev` 脚本**须更新为默认加载第一个业务组件：`"dev": "VITE_COMPONENT_ID=<首个id> vite --config vite.dev.config.ts"`，确保 `npm run dev` 不会因缺少 `VITE_COMPONENT_ID` 而白屏
-5. 新建 `src/index.ts` 导出业务默认入口
-6. 写入 `.env.local`（从 `.env.local.example` 复制并填入文档中的 `AppBaseUrl` 等）
-
-#### 第三步：适配业务 composable
-
-根据流程文档的池 Schema 和业务逻辑，修改 `src/use/useSuperTableBitableLifecycle.ts`：
-
-- 替换 `DEMO_*` 常量（`DEMO_SUB_TABLE_NAME`、`DEMO_LIST_SUB`、`DEMO_LIST_COLS`）为业务语义命名
-- 替换 `DemoListRow` 接口为业务行类型
-- 重写 `mapAgenticlabTicketToDemoRow` → `mapTicketTo<业务>Row`（映射 ticket detail 到表格列）
-- 重写 `mergeEditedRowIntoAgenticTicket` → `merge<业务>RowIntoTicket`（仅回写可编辑字段）
-- 按池 Schema 约束重写 `checkRows` 中的校验逻辑
-
-### 1B. 增量修改（目标目录已有工程）
-
-**目标**：在已有工程上修改/新增组件，**不触碰**脚手架基础设施。
-
-**禁止修改**（除非用户明确要求）：
-
-- `package.json` 中的 `dependencies` / `devDependencies`（`version` 字段除外——每次修改**必须**递增 `version`）
-- `vite.config.ts`（除 `COMPONENT_MAP` 和 `define` 外）、`vite.dev.config.ts`、`tsconfig.json`
-- `dev/` 目录
-- `src/utils/orbitHttpClient.ts`
-
-**允许的操作**：
-
-| 操作 | 涉及文件 |
-|------|----------|
-| 新增门控入口 | 新建 `src/views/<id>.vue` + `src/entries/<id>.ts`，在 `vite.config.ts` 的 `COMPONENT_MAP` 增加条目，在 `package.json scripts` 增加 `dev:<id>` / `build:<id>` |
-| 修改已有视图 | 编辑 `src/views/<id>.vue`（新增/删除/修改列、按钮、校验逻辑等） |
-| 修改 composable | 编辑 `src/use/useSuperTableBitableLifecycle.ts`（修改列定义、校验规则、映射逻辑等） |
-| 修改 API | 编辑 `src/api/agenticlabTickets.ts`（新增接口、修改映射等） |
-| 修改类型 | 编辑 `src/types/xnb-context.ts`（扩展 context 类型等） |
-| 修改环境配置 | 编辑 `.env.local`（新增/修改环境变量） |
-| 递增版本 | 修改 `package.json` 的 `version` 字段（每次生成/修改必须递增） |
-
-#### 增量修改原则
-
-- **Composable 扩展**：新增函数添加到现有 composable 的 `return {}` 中，不新建重复功能的 composable
-- **组件拆分**：单个 `.vue` 超过 600 行时按功能块拆为子组件，保持原组件为入口
-- **不重新生成**：只修改需要变更的部分，不重新生成未涉及的代码段
-- **参数兼容**：修改函数签名时用可选参数扩展，不破坏现有调用
-- **依赖管控**：不添加新 npm 依赖，除非向用户说明原因并获得同意
-
-**增量修改前，先读取现有代码**：
-
-1. 读 `vite.config.ts` 中的 `COMPONENT_MAP` → 了解已有哪些组件入口
-2. 读 `src/use/useSuperTableBitableLifecycle.ts` → 了解当前列定义、校验、映射逻辑
-3. 读目标 `src/views/<id>.vue` → 了解当前 UI 结构
-4. 再根据用户需求做最小化修改
-
-### 1C. 命名规则（首次和增量均适用）
-
-- **工程名称 ≠ 组件名称**：用户提供的工程名称（如目录名、`package.json` `name`）仅用于项目级标识，**不影响**内部组件注册名、视图文件名、entries 文件名、composable 函数名等内部命名。
-- 组件内部命名**始终**从门控 `name` / `valve_id` / 文档小节标题提炼 **PascalCase** 注册名与 **kebab-case** 文件 id
-- 禁止使用 `Page1`、`bitable`、`custom-page` 等无意义占位名
-- **一个门控的人工处理块 → 至少一个独立入口组件**
-
-### 2. 实现要点
-
-1. **上下文**：根组件 `defineProps<{ xnbContext: XnbSuperCellContext }>()`，向 composable 传入 `() => props.xnbContext`。
-2. **超级表格**：复用 `useSuperTableBitableLifecycle.ts` 模式；刷新时全量替换 `items`。
-3. **默认按钮**：生成**刷新 / 检查 / 提交**三个按钮（对应 `onRefresh` / `onCheck` / `onSubmit`），除非用户明确描述不同的按钮组合。
-4. **列定义**：仅 string/number 类型生成为列；json 等非标量默认不展开。根据池 Schema「可人工录入」标记设置 `readonly: false/true`。
-5. **校验**：`checkRows` 按池 Schema 约束校验（类型、范围、必填等），用户可叠加自定义规则。
-6. **提交**：`submitRows` 先调 `checkRows`，再将可编辑字段映射回 ticket detail 路径，调 `postAgenticlabExecutionComplete`。
-7. **AgenticLab**：`AppBaseUrl` → `VITE_AGENTICLAB_API_URL`；Token → `VITE_DEV_TOKEN`。
-8. **语言**：流程文档「语言类型」为英文时，UI 文案使用英文。
-9. **产物版本**：每次生成/修改时递增 `package.json` 的 `version` 字段（初次生成为 `1.0.0`）。`vite.config.ts` 通过 `define` 注入 `__APP_VERSION__`（读自 `pkg.version`）和 `__APP_SKILL__`（固定为 `'lab-orbit-component-builder'`）。仅在**最上层入口组件**（`src/entries/<id>.ts` 对应的 `src/views/<业务>.vue`）的 `<script setup>` 中 imports 之后、`defineProps` 之前添加 `console.info(\`[OrbitComponent] v\${__APP_VERSION__} (skill: \${__APP_SKILL__})\`)`；子组件**不需要**版本打印。
-
-### 3. 质量检查（生成/修改完成后必须执行）
-
-完成代码生成或修改后，若目标工程已执行过 `npm install`，**必须**依次运行以下命令并修复发现的问题：
-
-```bash
-npm run lint:fix          # 自动修复代码格式与规范问题
-npm run typecheck         # TypeScript 类型检查（vue-tsc --noEmit）
-npm run build             # 构建验证
-```
-
-- 以上命令使用模板 `package.json` 中预定义的 npm scripts，不依赖特定 Agent 平台
-- 若目标工程尚未 `npm install`（如首次生成刚复制完脚手架），跳过此步骤，在输出中提醒用户执行 `npm install` 后手动验证
-- 若检查失败，自动修复后再次验证；仅需要业务决策的问题才向用户确认
-
-### 4. 输出与自检
-
-- 列出新增/修改文件路径；说明每个入口组件对应的门控名称与 `dist/registrarName`。
-- 自检项：
-  - [ ] 首次生成时，完整脚手架已复制（package.json、vite.config.ts、vite.dev.config.ts、index.html、dev 等），目标工程可独立 `npm install && npm run dev`
-  - [ ] 首次生成时，模板示例文件（`views/bitable.vue`、`custom-page.vue`、`entries/bitable.ts`、`useSuperCellDemo.ts`）未被复制
-  - [ ] 增量修改时，未覆盖工程基础设施（package.json dependencies、vite.config.ts 非 COMPONENT_MAP 部分 等）
-  - [ ] opener 初始化失败时展示产品化提示（非技术术语）并禁用操作按钮，技术信息仅输出到控制台
-  - [ ] 默认渲染了刷新/检查/提交三个按钮
-  - [ ] 仅 string/number 类型字段被渲染为列；json 字段未误标为简单列
-  - [ ] 仅「可人工录入」字段设为 `readonly: false`
-  - [ ] `checkRows` 校验了所有 Schema 约束（类型/范围/必填）
-  - [ ] `submitRows` 仅将可编辑字段回写到 ticket detail 对应路径
-  - [ ] 环境变量使用 `VITE_DEV_TOKEN` 和 `VITE_AGENTICLAB_API_URL`
-  - [ ] `.env.local` 中无生产 Token 配置
-  - [ ] 全量刷新已按 §8.5.2 处理（整表替换 items）
-  - [ ] `DEMO_*` 常量已替换为业务语义命名
-  - [ ] 字段值映射使用 `String()` 转换，未直接调用 `.trim()` 等字符串方法
-  - [ ] `package.json` 的 `version` 已设置/递增；最上层入口视图含 `console.info` 版本打印（子组件无需）；`vite.config.ts` 含 `define` 注入 `__APP_VERSION__` 和 `__APP_SKILL__`
-
----
-
-## 硬性约束
-
-- **必须**先判断目标目录工程状态（首次生成 or 增量修改），按对应流程执行；**禁止**在已有工程上重复脚手架复制，**禁止**在空目录上直接增量修改。
-- **首次生成时必须**复制完整脚手架基础设施（见步骤 1A），确保工程可独立 `npm install && npm run dev`。
-- **首次生成时禁止**复制模板示例文件（`views/bitable.vue`、`custom-page.vue`、`entries/bitable.ts`、`custom-page.ts`、`useSuperCellDemo.ts`）。
-- **增量修改时禁止**覆盖基础设施文件（`vite.config.ts` 非 COMPONENT_MAP 部分、`vite.dev.config.ts`、`dev/` 等），除非用户明确要求。
-- **多组件工程**必须保留 `vite.config.ts` 中 `build.emptyOutDir: false`；`build:all` 顺序执行各 `build:<id>` 时，禁止清空前序产物。
-
-- **必须**以模板 **`examples/xnb-component-template`** 为脚手架基准（脚本、别名、`orbitHttpClient`、`types/xnb-context.ts`）。
-- **必须**通过 **props** 接收 `xnbContext`，不在 SFC 顶层假定存在全局 `xnbContext`。
-- **必须**在 opener 初始化失败时展示产品化提示（「没有获得有效参数，请关闭页面重试。」）并禁用刷新/检查/提交按钮；**禁止**在页面上展示技术术语，技术信息仅输出到控制台。
-- **必须**默认渲染刷新、检查、提交三个按钮，除非用户明确描述不同的按钮组合。
-- **必须**仅将池 Schema 中标记「可人工录入」的字段设为 `readonly: false`。
-- **必须**在提交前执行 `checkRows` 校验，校验不通过时阻止提交。
-- **必须**使用统一环境变量 `VITE_DEV_TOKEN`（开发 Token）和 `VITE_AGENTICLAB_API_URL`（接口地址）。
-- **必须**将接口地址写入 `.env.local`；**禁止**将生产 Token 写入仓库。
-- **禁止**将模板 `src/views/bitable.vue`、`src/views/custom-page.vue` 原样复制到用户目标目录作为门控交付页；业务入口须新建具语义文件名的 SFC。
-- **禁止**在未读池 Schema / 流程字段的前提下臆造列；json 等非标量默认不展开为单列。
-- Token / BaseURL：**禁止**将真实生产密钥写入仓库；使用 `.env.local`（gitignore）与文档说明。
-- **页面入口** `.vue`（`src/views/` 下新建 Cell 根组件）**必须**含 `orbit-quasar-host` 与 `@import '@/styles/orbit-quasar-host.scss'`（`<style scoped lang="scss">`）；主题调整**优先**改 `src/styles/orbit-quasar-host.scss`。超级表格工具栏：`primary` 仅提交类持久化动作，`outline` 仅页面数据交互（刷新/检查），见规则 2。
-- **禁止**对 API 返回值、行字段值等可能为非字符串的值直接调用 `.trim()` / `.toLowerCase()` 等字符串原型方法；必须先用 `String(value)` 转换。
-- **必须**在每次生成/修改时递增 `package.json` 的 `version` 字段（初次 `1.0.0`；迭代修改按范围递增）。
-- **必须**在 `vite.config.ts` 中通过 `define` 注入 `__APP_VERSION__`（`JSON.stringify(pkg.version)`）和 `__APP_SKILL__`（`JSON.stringify('lab-orbit-component-builder')`）。
-- **必须**在每个生成的**最上层入口组件**（`src/views/<业务>.vue`）的 `<script setup>` 中添加 `console.info` 打印版本信息；子组件不需要版本打印。
+---
+name: lab-orbit-component-builder
+description: >-
+  根据流程说明 Markdown（门控「人工处理」与数据池 Schema）在 Orbit Vue 3 工程内生成/迭代超级表格组件。
+  默认渲染刷新/检查/提交按钮，仅暴露 string/number 列，仅「可人工录入」字段可编辑，按池 Schema 约束校验，提交参数与 ticket schema 对齐。
+  模板内 examples/xnb-component-template/src/views/ 下的 bitable.vue 与 custom-page.vue 仅供阅读参考，执行时禁止复制到用户目标目录。
+  Use when scaffolding Orbit Vue cells from flow docs, super-table manual pages, bitable columns from pool Schema, or AgenticLab ticket/execution APIs.
+compatibility: Orbit Book Vue Cell; window.xnb + props.xnbContext; Vite 5 lib build; company private npm per template README
+metadata:
+  version: "1.3.0"
+  runtime: Orbit-XNB-Vue-Component
+  template_path: examples/xnb-component-template
+---
+
+# Studio · Orbit Vue 组件生成技能
+
+## 能力范围
+
+| 本技能**负责** | 本技能**不负责** |
+|----------------|------------------|
+| 从**流程文档**中识别门控 **「人工处理」** 小节，在同一 Vue 工程下生成**独立入口组件**（SFC + `entries` + `vite.config.ts` `COMPONENT_MAP` 条目） | 流程注册包目录结构、`pools/*.md` 全量自动生成、门控 YAML/脚本落库 |
+| 按 **`examples/xnb-component-template`** 的目录、构建脚本、类型与 composable 风格编写/扩展代码 | 替用户配置公司私有 NPM 账号；生产环境密钥写入仓库 |
+| **XNBBitable**：`new XNBBitable({ bookPath, cellUid })`、子表操作、全量 list 时 **`items` 整表替换** | Book 内 **JsCode** 字符串拼接 UI |
+| **HTTP**：宿主内优先 **`window.xnb.http.client.request`**；模板内 **`orbitRequestJson`** | 非 AgenticLab / 非模板已文档化接口的臆造路径 |
+| **`xnbContext`**：通过组件 **props** 注入 | 修改宿主 `xnb-jscode` 仓库源码 |
+
+---
+
+## 默认行为规则（硬性要求）
+
+以下规则在**每次**生成/迭代组件时**必须**遵守，除非用户**明确描述**了不同的需求。
+
+### 规则 1：请求数据（刷新）
+
+1. **Opener 参数获取**：页面挂载后调用 `fetchOpenerInitPayload` 获取 opener 回包；子页发 `{ msg: 'get-data', trace }`，**流程宿主**回 `{ msg: 'get-data-response', trace, ticket_ids, valve_id, ... }`（见 `openerInitParams.ts`，兼容 `msg: 'data' + payload`）。
+   - 若获取失败（`ok: false`）且无开发环境回退（`VITE_DEV_OPENER_INIT_JSON`），**必须**：
+     - 在界面上展示**产品化提示**（如 `q-banner`）：**「没有获得有效参数，请关闭页面重试。」**（英文页面：**"Failed to obtain valid parameters. Please close the page and try again."**）
+     - **禁止**在页面上显示技术术语（Error 对象、堆栈、skipped reason 等）；技术细节仅输出到 `console.warn`
+     - **禁用**刷新/检查/提交按钮（`:disable="!!openerInitError"`），阻止后续一切数据操作
+   - 从 `payload` 中提取 `ticket_ids`（用 `extractTicketIdsFromPayload`）和 `valve_id`（用 `extractValveIdFromPayload`）
+2. **Token 获取链**（优先级从高到低）：
+   - 参数传入的静态 token
+   - `await window.xnb.choreo.getUserToken()`（Orbit 宿主注入）
+   - `import.meta.env.VITE_DEV_TOKEN`（本地开发用，勿提交生产密钥）
+3. **接口地址**：`import.meta.env.VITE_AGENTICLAB_API_URL`，嵌入 Orbit 时 `orbitRequestJson` 自动走宿主代理
+4. **触发请求**：`fetchAgenticlabTicketList` → 映射为表格行 → 整表替换 `bitable.items` → `updateSubBitable`
+
+### 规则 2：渲染交互和数据
+
+1. **默认按钮**：**必须**渲染以下三个按钮（除非用户明确描述去掉、修改或新增功能）：
+   - **刷新**（`onRefresh`）：重新拉取数据，整表替换，操作前弹确认框
+   - **检查**（`onCheck`）：校验当前表格数据是否满足约束
+   - **提交**（`onSubmit`）：先校验再提交，操作前弹确认框
+   - **样式主题与按钮（超级表格页）**：默认对照 `examples/xnb-component-template/src/views/bitable.vue` 的 DOM / 类名 / `q-btn` 写法，并 `@import '@/styles/orbit-quasar-host.scss'`（见规则 6）。**除非**流程文档或用户任务**明确描述**了不同样式，否则遵守：
+     - **主题**：Cell 内 Quasar 主题以 `examples/xnb-component-template/src/styles/orbit-quasar-host.scss` 为准；需新增或调整主色、`q-btn` 全局表现等，**只改该文件**（勿在业务 SFC 内散落 `--q-primary` 或重复定义）。
+     - **`color="primary"`**：仅用于**会提交或修改持久化数据**的按钮（默认即「提交」/`onSubmit`）；刷新、检查等**不得**使用 `primary`。
+     - **`outline`**：仅用于**页面内数据交互**（拉数、校验、本地检查等，默认即「刷新」「检查」）；提交**不得**使用 `outline`（用 `color="primary" dense unelevated`，与 `bitable.vue` 一致）。
+     - 勿对工具栏按钮使用 `secondary` / `accent` 等未在模板出现的 `color`。
+2. **列类型限制**：默认**仅** `string`（`dv: { type: 'text_length' }`）和 `number`（`dv: { type: 'number' }, ct: { fa: '0', t: 'n' }`）类型的字段被渲染为表格列。
+   - **json** 类型字段**默认不展示**为列
+   - 若用户明确描述了自定义渲染逻辑：渲染前拆解（如 `JSON.stringify` 摘要或提取子字段），提交时重新组装回原始结构
+3. **可编辑性**：流程文档数据池中标记「**可人工录入**」的字段设 `readonly: false`；其余字段一律 `readonly: true`。
+
+### 规则 3：校验数据
+
+1. **默认校验**：按流程文档中数据池定义的字段约束自动生成校验逻辑：
+   - number 列：范围、正数、必填等（从 Schema 约束推导）
+   - text 列：非空、格式（条码、路径等）
+   - 必填字段：Schema 中标记 required 的字段检查非空
+2. **自定义校验**：仅在用户**明确描述**更多校验规则时才增加
+3. **执行时机**：`checkRows` 在 `submitRows` 之前**必须**被调用，校验不通过时阻止提交
+
+### 规则 4：提交数据
+
+1. **获取表格数据**：从超级表格通过 `getAllSubBitable` / `getSubBitable` 获取当前 `items`（含用户编辑后的值）
+2. **参数映射**：
+   - 仅将**可编辑字段**（`readonly: false`）的修改值映射为可提交参数
+   - 提交参数**必须与 ticket schema 定义对齐**：将编辑值写回 ticket `detail` 中对应路径（如 `detail.process_params['@requested_amount_mg']`）
+   - 使用 `lastAgenticRawTickets`（最近一次 GET 的原始工单）与表格编辑值合并，构建完整的 `tickets` 数组
+3. **提交请求**：Token 获取链与刷新请求一致 → `postAgenticlabExecutionComplete({ baseUrl, token, valveId, tickets })`
+
+### 规则 5：配置
+
+1. **环境变量文件**：
+   - **`.env.local`**（gitignored）：含 `VITE_DEV_TOKEN`（开发用 Token）和 `VITE_AGENTICLAB_API_URL`（接口地址）
+   - 生产环境 Token 由 `getUserToken()` 运行时提供，**禁止**将 Token 写入仓库
+2. **统一变量名**：
+   - `VITE_DEV_TOKEN`：统一了原 `VUE_APP_NOCOBASE_DEV_TOKEN` 与 `VUE_APP_AGENTICLAB_TOKEN`
+   - `VITE_AGENTICLAB_API_URL`：AgenticLab API 根地址
+
+### 规则 6：生成禁令（模板 views 示例）
+
+`examples/xnb-component-template/src/views/bitable.vue` 与 `custom-page.vue` 是模板内的**演示用示例**。
+
+**样式主题（Quasar）**：页面入口默认参照 `examples/xnb-component-template/src/views/bitable.vue`（布局、工具栏、`q-btn` 属性分工）与 `examples/xnb-component-template/src/styles/orbit-quasar-host.scss`（主题变量与 `:deep(.q-btn)`）。根节点须 `orbit-quasar-host`，`<style scoped lang="scss">` 首行 `@import '@/styles/orbit-quasar-host.scss'`。用户或流程要求调整主题时，**优先只改** `src/styles/orbit-quasar-host.scss`，业务 SFC 仅保留页面级局部类（如 `bitable.vue` 中的 banner / `row-count`）。
+
+**执行本技能向用户目标目录产出时：**
+
+- **禁止**将上述两个文件**原样复制**到用户工程（或仅改少量字符串后当作交付组件）
+- **禁止**以「复制 `bitable.vue` 改名」替代需求分析
+- **应当**以二者及 `useBitablePage` / `useSuperTableBitableLifecycle` 等为**参考**，按流程文档与门控语义**新建** `src/views/<业务语义>.vue`（及对应 `entries/<id>.ts`、配置项），文件名与 UI 文案须与业务一致；**bitable 类**写模板前对照 `bitable.vue` + `orbit-quasar-host.scss`（见规则 2「样式主题与按钮」）
+
+若用户仓库是由模板整体 fork 而来且仍需保留模板自带示例入口，可保留原文件；**新增**业务门控页时仍须**新建**独立 SFC。
+
+### 规则 7：代码安全（避免运行时类型错误）
+
+1. **`<style>`**：
+   - **页面入口**（本技能新建的 `src/views/<业务>.vue` 等独立 Cell 根组件）：**必须**根节点带 `orbit-quasar-host`，`<style scoped lang="scss">` 首行 `@import '@/styles/orbit-quasar-host.scss'`，与模板一致以统一 Quasar 风格。
+   - **非页面入口**的生成 `.vue`（如子组件）：`<style scoped>` **必须**纯 CSS，**禁止** `lang="scss"` / `lang="sass"`；样式变量用 CSS 自定义属性（`var(--c-xxx)`），避免无必要拉满 SCSS 链、在不同 `sass-loader` 版本下出现 `raw.trim is not a function` 等构建错误。
+2. **字段值安全转换**：在 `mapRowToItem`、`checkRows` 等映射/校验函数中，从行数据或 API 响应取出的字段值**必须**先转为字符串再做字符串操作：
+   ```typescript
+   // ✅ 正确：先 String() 转换
+   fields[field] = raw == null ? '' : String(raw)
+   // ❌ 错误：raw 可能是 number / object，导致 "raw.trim is not a function"
+   fields[field] = raw.trim()
+   ```
+3. **模板插值安全**：`{{ }}` 中引用的变量若可能为非字符串（如 API 返回的 `number`、`null`），须在 computed / 方法中先做 `String()` 或 `?? ''` 兜底，禁止在模板中直接对非字符串调用字符串方法。
+
+---
+
+## 渐进披露（何时读哪份文件）
+
+默认先读本页与 **`references/vue-template-checklist.md`**；需要细节时再打开：
+
+| 需求 | 打开（相对本技能根目录） |
+|------|---------------------------|
+| 从流程文档拆 **人工处理**、多门控多组件、命名与配置表 | [`references/flow-document-human-ui.md`](references/flow-document-human-ui.md) |
+| **props `xnbContext`** 与 JsCode 对照 | [`references/xnb-context-vue-props.md`](references/xnb-context-vue-props.md) |
+| 池 **Schema** → 列定义、可编辑字段策略、校验规则 | [`references/pool-schema-to-columns.md`](references/pool-schema-to-columns.md) |
+| XNBBitable 行为、全量刷新、反模式 | [`references/xnbitable-vue-parity.md`](references/xnbitable-vue-parity.md)；模板 [`examples/xnb-component-template/OrbitAPI.md`](examples/xnb-component-template/OrbitAPI.md) |
+| Vue/TS 编码约定、命名、组件拆分策略 | [`references/orbit-vue-conventions.md`](references/orbit-vue-conventions.md) |
+| 工单列表、`/api/execution/complete`、opener `ticket_ids` | 模板 [`examples/xnb-component-template/AgenticAppAPI.md`](examples/xnb-component-template/AgenticAppAPI.md) |
+| 装依赖、`dev`/`build`、多入口配置 | 模板 [`examples/xnb-component-template/README.md`](examples/xnb-component-template/README.md) |
+
+## 与 **orbit-write-js-cell** 的关系
+
+- **orbit-write-js-cell**：面向 Book **JsCode** Cell（`return` HTML、`window.xnb.cell.register`）。
+- **本技能**：面向 **Vue 3 SFC**，用 Composition API + props 表达同一套运行时。
+- **XNBBitable 业务语义**必须与 orbit-write-js-cell / API.md 一致，实现形式改为 Vue。
+
+---
+
+## 工作流（给 Agent）
+
+### 0.0 理解与确认（编码前）
+
+对于**首次生成**或**较大范围增量修改**，在开始编码前：
+
+1. **理解**：读完流程文档中目标门控的「人工处理」章节、输入池 Schema、以及目标目录下的现有代码
+2. **确认**：向用户简要复述理解——哪个门控、哪些字段成为列、哪些字段可编辑、校验规则如何，请求确认
+3. **执行**：确认后按方案实施
+
+> 若变更范围明确（如仅修改一列的校验规则或新增一个按钮），可跳过确认步骤直接执行。
+
+### 0. 判断工程状态：首次生成 or 增量修改
+
+**在做任何事之前，先确定目标目录，然后检查该目录：**
+
+**目标目录优先级**：
+
+1. **用户指定了具体工程路径** → 使用该路径
+2. **用户仅指定了流程文档路径** → 在文档**所在目录下创建工程子目录**，目录名从流程名称 / 文档文件名提炼为 `kebab-case`（如文档 `fragment-flow-mini-2-pool-20260611-人工录入.md` → 创建 `xnb-component-fragment-flow-mini-2/`）。**禁止**将工程文件直接平铺到文档所在目录
+3. **均未指定** → 在当前工作目录（CWD）下创建工程子目录，命名规则同上
+
+**工程目录命名规则**：`xnb-component-<流程语义>`，从流程名称 / 文档文件名提炼 kebab-case，去掉日期、版本号等非语义后缀。一个流程的所有门控人工处理页统一放在同一个工程目录下（一个工程多入口）。
+
+1. 查看目标目录下是否存在 `package.json` 且包含 `vite`（devDependencies）、`vite.config.ts`、`src/use/useBitablePage.ts` 等脚手架标志文件。
+2. **若不存在** → 进入 **「首次生成」** 流程（步骤 1A）。
+3. **若已存在** → 进入 **「增量修改」** 流程（步骤 1B）。
+
+> **禁止**在已有工程上重复执行首次生成流程（会覆盖已有业务代码）。
+> **禁止**在空目录上执行增量修改流程（缺少脚手架基础设施，代码无法运行）。
+
+### 0.1 输入识别（首次和增量均需执行）
+
+1. 确认用户提供的 **流程文档**路径（或粘贴「门控」章节）：定位每个门控下的 **`#### 人工处理`** 及 **`##### 界面形态与数据绑定`** 列表项。
+2. 读取同文档中的 **人工处理配置项**表（如 `AppBaseUrl`、`数据查询上限`、`语言类型`），映射到环境变量与代码常量（见 **`references/flow-document-human-ui.md`**）。
+3. 若文档给出门控 **输入池** 及 Schema 表：提取列名、字段类型、标题、**是否可人工录入**，用于生成列定义与编辑/只读策略（见 **`references/pool-schema-to-columns.md`**）。
+4. **若 opener 初始化逻辑未能获取到必要参数**，生成的组件**必须**在界面上展示产品化提示（如「没有获得有效参数，请关闭页面重试。」），并禁用所有数据操作按钮（刷新/检查/提交）。**禁止**在页面上展示技术术语（Error 对象、堆栈等），技术细节仅输出到 `console.warn`。
+
+### 1A. 首次生成（目标目录无工程）
+
+**目标**：在目标工程目录下（按 §0 创建或定位），从模板 `examples/xnb-component-template` 搭建完整工程，再生成业务组件。
+
+#### 第一步：复制脚手架基础设施
+
+从模板目录**复制以下文件/目录**到用户目标目录（保持相对路径不变）：
+
+| 类别 | 文件 |
+|------|------|
+| 构建配置 | `package.json`、`vite.config.ts`、`vite.dev.config.ts`、`tsconfig.json`、`index.html`、`.nvmrc` |
+| 代码规范 | `.eslintrc.cjs`、`.eslintignore`、`.gitignore` |
+| 构建脚本 | （内置于 `vite.config.ts` 与 `package.json` scripts，无需 `scripts/` 目录） |
+| 组件配置 | `vite.config.ts`（`COMPONENT_MAP` 后续步骤会覆盖其组件条目） |
+| 环境配置 | `.env.local.example` |
+| CI | `Jenkinsfile` |
+| 类型 | `src/types/xnb-context.ts` |
+| 工具函数 | `src/utils/openerInitParams.ts`、`src/utils/openerTicketIds.ts`、`src/utils/orbitHttpClient.ts` |
+| API | `src/api/agenticlabTickets.ts` |
+| Composable | `src/use/useBitablePage.ts`、`src/use/useSuperTableBitableLifecycle.ts` |
+| Dev 调试 | `dev/` 整个目录（`public/`、`src/App.vue`、`src/main.ts`、`src/mockXNBBitable.ts`、`src/global.d.ts`、`src/shims-vue.d.ts`） |
+| 测试 | （Vite 模板不内置测试文件，按需添加 vitest） |
+| 文档 | `OrbitAPI.md`、`AgenticAppAPI.md`、`README.md` |
+
+**不要复制的文件**（仅作阅读参考）：
+
+| 文件 | 原因 |
+|------|------|
+| `src/views/bitable.vue` | 示例视图，业务入口须按流程文档新建 |
+| `src/views/custom-page.vue` | 示例视图，业务入口须按流程文档新建 |
+| `src/entries/bitable.ts` | 示例入口，随业务视图新建 |
+| `src/entries/custom-page.ts` | 示例入口，随业务视图新建 |
+| `src/use/useSuperCellDemo.ts` | 演示用 composable，业务不需要 |
+| `src/index.ts` | 默认导出占位，业务工程按需重写 |
+
+#### 第二步：生成业务组件
+
+按流程文档中的每个门控「人工处理」：
+
+1. 新建 `src/views/<业务语义>.vue`（按规则 1-4 实现 opener、列定义、校验、提交）
+2. 新建 `src/entries/<id>.ts`
+3. 更新 `vite.config.ts` 中的 `COMPONENT_MAP`（**清空**模板示例的 `bitable` / `custom-page` 条目，仅保留业务条目）；**保留** `build.emptyOutDir: false`（多组件顺序构建时防止后续 build 清空前序产物）
+4. `package.json`：**`version` 须在每次生成/修改时递增**（初次生成设为 `1.0.0`；迭代修改按变更范围递增 patch/minor/major）；其余字段（`name`、`main`、`dependencies`、`devDependencies`、`webb` 等）**原样保留**模板内容**禁止改动**，仅在 `scripts` 中**追加** `dev:<id>` / `build:<id>` 条目；多组件时须有 `build:all`（顺序执行所有 `build:<id>`）。**通用 `dev` 脚本**须更新为默认加载第一个业务组件：`"dev": "VITE_COMPONENT_ID=<首个id> vite --config vite.dev.config.ts"`，确保 `npm run dev` 不会因缺少 `VITE_COMPONENT_ID` 而白屏
+5. 新建 `src/index.ts` 导出业务默认入口
+6. 写入 `.env.local`（从 `.env.local.example` 复制并填入文档中的 `AppBaseUrl` 等）
+
+#### 第三步：适配业务 composable
+
+根据流程文档的池 Schema 和业务逻辑，修改 `src/use/useSuperTableBitableLifecycle.ts`：
+
+- 替换 `DEMO_*` 常量（`DEMO_SUB_TABLE_NAME`、`DEMO_LIST_SUB`、`DEMO_LIST_COLS`）为业务语义命名
+- 替换 `DemoListRow` 接口为业务行类型
+- 重写 `mapAgenticlabTicketToDemoRow` → `mapTicketTo<业务>Row`（映射 ticket detail 到表格列）
+- 重写 `mergeEditedRowIntoAgenticTicket` → `merge<业务>RowIntoTicket`（仅回写可编辑字段）
+- 按池 Schema 约束重写 `checkRows` 中的校验逻辑
+
+### 1B. 增量修改（目标目录已有工程）
+
+**目标**：在已有工程上修改/新增组件，**不触碰**脚手架基础设施。
+
+**禁止修改**（除非用户明确要求）：
+
+- `package.json` 中的 `dependencies` / `devDependencies`（`version` 字段除外——每次修改**必须**递增 `version`）
+- `vite.config.ts`（除 `COMPONENT_MAP` 和 `define` 外）、`vite.dev.config.ts`、`tsconfig.json`
+- `dev/` 目录
+- `src/utils/orbitHttpClient.ts`
+
+**允许的操作**：
+
+| 操作 | 涉及文件 |
+|------|----------|
+| 新增门控入口 | 新建 `src/views/<id>.vue` + `src/entries/<id>.ts`，在 `vite.config.ts` 的 `COMPONENT_MAP` 增加条目，在 `package.json scripts` 增加 `dev:<id>` / `build:<id>` |
+| 修改已有视图 | 编辑 `src/views/<id>.vue`（新增/删除/修改列、按钮、校验逻辑等） |
+| 修改 composable | 编辑 `src/use/useSuperTableBitableLifecycle.ts`（修改列定义、校验规则、映射逻辑等） |
+| 修改 API | 编辑 `src/api/agenticlabTickets.ts`（新增接口、修改映射等） |
+| 修改类型 | 编辑 `src/types/xnb-context.ts`（扩展 context 类型等） |
+| 修改环境配置 | 编辑 `.env.local`（新增/修改环境变量） |
+| 递增版本 | 修改 `package.json` 的 `version` 字段（每次生成/修改必须递增） |
+
+#### 增量修改原则
+
+- **Composable 扩展**：新增函数添加到现有 composable 的 `return {}` 中，不新建重复功能的 composable
+- **组件拆分**：单个 `.vue` 超过 600 行时按功能块拆为子组件，保持原组件为入口
+- **不重新生成**：只修改需要变更的部分，不重新生成未涉及的代码段
+- **参数兼容**：修改函数签名时用可选参数扩展，不破坏现有调用
+- **依赖管控**：不添加新 npm 依赖，除非向用户说明原因并获得同意
+
+**增量修改前，先读取现有代码**：
+
+1. 读 `vite.config.ts` 中的 `COMPONENT_MAP` → 了解已有哪些组件入口
+2. 读 `src/use/useSuperTableBitableLifecycle.ts` → 了解当前列定义、校验、映射逻辑
+3. 读目标 `src/views/<id>.vue` → 了解当前 UI 结构
+4. 再根据用户需求做最小化修改
+
+### 1C. 命名规则（首次和增量均适用）
+
+- **工程名称 ≠ 组件名称**：用户提供的工程名称（如目录名、`package.json` `name`）仅用于项目级标识，**不影响**内部组件注册名、视图文件名、entries 文件名、composable 函数名等内部命名。
+- 组件内部命名**始终**从门控 `name` / `valve_id` / 文档小节标题提炼 **PascalCase** 注册名与 **kebab-case** 文件 id
+- 禁止使用 `Page1`、`bitable`、`custom-page` 等无意义占位名
+- **一个门控的人工处理块 → 至少一个独立入口组件**
+
+### 2. 实现要点
+
+1. **上下文**：根组件 `defineProps<{ xnbContext: XnbSuperCellContext }>()`，向 composable 传入 `() => props.xnbContext`。
+2. **超级表格**：复用 `useSuperTableBitableLifecycle.ts` 模式；刷新时全量替换 `items`。
+3. **默认按钮**：生成**刷新 / 检查 / 提交**三个按钮（对应 `onRefresh` / `onCheck` / `onSubmit`），除非用户明确描述不同的按钮组合。
+4. **列定义**：仅 string/number 类型生成为列；json 等非标量默认不展开。根据池 Schema「可人工录入」标记设置 `readonly: false/true`。
+5. **校验**：`checkRows` 按池 Schema 约束校验（类型、范围、必填等），用户可叠加自定义规则。
+6. **提交**：`submitRows` 先调 `checkRows`，再将可编辑字段映射回 ticket detail 路径，调 `postAgenticlabExecutionComplete`。
+7. **AgenticLab**：`AppBaseUrl` → `VITE_AGENTICLAB_API_URL`；Token → `VITE_DEV_TOKEN`。
+8. **语言**：流程文档「语言类型」为英文时，UI 文案使用英文。
+9. **产物版本**：每次生成/修改时递增 `package.json` 的 `version` 字段（初次生成为 `1.0.0`）。`vite.config.ts` 通过 `define` 注入 `__APP_VERSION__`（读自 `pkg.version`）和 `__APP_SKILL__`（固定为 `'lab-orbit-component-builder'`）。仅在**最上层入口组件**（`src/entries/<id>.ts` 对应的 `src/views/<业务>.vue`）的 `<script setup>` 中 imports 之后、`defineProps` 之前添加 `console.info(\`[OrbitComponent] v\${__APP_VERSION__} (skill: \${__APP_SKILL__})\`)`；子组件**不需要**版本打印。
+
+### 3. 质量检查（生成/修改完成后必须执行）
+
+完成代码生成或修改后，若目标工程已执行过 `npm install`，**必须**依次运行以下命令并修复发现的问题：
+
+```bash
+npm run lint:fix          # 自动修复代码格式与规范问题
+npm run typecheck         # TypeScript 类型检查（vue-tsc --noEmit）
+npm run build             # 构建验证
+```
+
+- 以上命令使用模板 `package.json` 中预定义的 npm scripts，不依赖特定 Agent 平台
+- 若目标工程尚未 `npm install`（如首次生成刚复制完脚手架），跳过此步骤，在输出中提醒用户执行 `npm install` 后手动验证
+- 若检查失败，自动修复后再次验证；仅需要业务决策的问题才向用户确认
+
+### 4. 输出与自检
+
+- 列出新增/修改文件路径；说明每个入口组件对应的门控名称与 `dist/registrarName`。
+- 自检项：
+  - [ ] 首次生成时，完整脚手架已复制（package.json、vite.config.ts、vite.dev.config.ts、index.html、dev 等），目标工程可独立 `npm install && npm run dev`
+  - [ ] 首次生成时，模板示例文件（`views/bitable.vue`、`custom-page.vue`、`entries/bitable.ts`、`useSuperCellDemo.ts`）未被复制
+  - [ ] 增量修改时，未覆盖工程基础设施（package.json dependencies、vite.config.ts 非 COMPONENT_MAP 部分 等）
+  - [ ] opener 初始化失败时展示产品化提示（非技术术语）并禁用操作按钮，技术信息仅输出到控制台
+  - [ ] 默认渲染了刷新/检查/提交三个按钮
+  - [ ] 仅 string/number 类型字段被渲染为列；json 字段未误标为简单列
+  - [ ] 仅「可人工录入」字段设为 `readonly: false`
+  - [ ] `checkRows` 校验了所有 Schema 约束（类型/范围/必填）
+  - [ ] `submitRows` 仅将可编辑字段回写到 ticket detail 对应路径
+  - [ ] 环境变量使用 `VITE_DEV_TOKEN` 和 `VITE_AGENTICLAB_API_URL`
+  - [ ] `.env.local` 中无生产 Token 配置
+  - [ ] 全量刷新已按 §8.5.2 处理（整表替换 items）
+  - [ ] `DEMO_*` 常量已替换为业务语义命名
+  - [ ] 字段值映射使用 `String()` 转换，未直接调用 `.trim()` 等字符串方法
+  - [ ] `package.json` 的 `version` 已设置/递增；最上层入口视图含 `console.info` 版本打印（子组件无需）；`vite.config.ts` 含 `define` 注入 `__APP_VERSION__` 和 `__APP_SKILL__`
+
+---
+
+## 硬性约束
+
+- **必须**先判断目标目录工程状态（首次生成 or 增量修改），按对应流程执行；**禁止**在已有工程上重复脚手架复制，**禁止**在空目录上直接增量修改。
+- **首次生成时必须**复制完整脚手架基础设施（见步骤 1A），确保工程可独立 `npm install && npm run dev`。
+- **首次生成时禁止**复制模板示例文件（`views/bitable.vue`、`custom-page.vue`、`entries/bitable.ts`、`custom-page.ts`、`useSuperCellDemo.ts`）。
+- **增量修改时禁止**覆盖基础设施文件（`vite.config.ts` 非 COMPONENT_MAP 部分、`vite.dev.config.ts`、`dev/` 等），除非用户明确要求。
+- **多组件工程**必须保留 `vite.config.ts` 中 `build.emptyOutDir: false`；`build:all` 顺序执行各 `build:<id>` 时，禁止清空前序产物。
+
+- **必须**以模板 **`examples/xnb-component-template`** 为脚手架基准（脚本、别名、`orbitHttpClient`、`types/xnb-context.ts`）。
+- **必须**通过 **props** 接收 `xnbContext`，不在 SFC 顶层假定存在全局 `xnbContext`。
+- **必须**在 opener 初始化失败时展示产品化提示（「没有获得有效参数，请关闭页面重试。」）并禁用刷新/检查/提交按钮；**禁止**在页面上展示技术术语，技术信息仅输出到控制台。
+- **必须**默认渲染刷新、检查、提交三个按钮，除非用户明确描述不同的按钮组合。
+- **必须**仅将池 Schema 中标记「可人工录入」的字段设为 `readonly: false`。
+- **必须**在提交前执行 `checkRows` 校验，校验不通过时阻止提交。
+- **必须**使用统一环境变量 `VITE_DEV_TOKEN`（开发 Token）和 `VITE_AGENTICLAB_API_URL`（接口地址）。
+- **必须**将接口地址写入 `.env.local`；**禁止**将生产 Token 写入仓库。
+- **禁止**将模板 `src/views/bitable.vue`、`src/views/custom-page.vue` 原样复制到用户目标目录作为门控交付页；业务入口须新建具语义文件名的 SFC。
+- **禁止**在未读池 Schema / 流程字段的前提下臆造列；json 等非标量默认不展开为单列。
+- Token / BaseURL：**禁止**将真实生产密钥写入仓库；使用 `.env.local`（gitignore）与文档说明。
+- **页面入口** `.vue`（`src/views/` 下新建 Cell 根组件）**必须**含 `orbit-quasar-host` 与 `@import '@/styles/orbit-quasar-host.scss'`（`<style scoped lang="scss">`）；主题调整**优先**改 `src/styles/orbit-quasar-host.scss`。超级表格工具栏：`primary` 仅提交类持久化动作，`outline` 仅页面数据交互（刷新/检查），见规则 2。
+- **禁止**对 API 返回值、行字段值等可能为非字符串的值直接调用 `.trim()` / `.toLowerCase()` 等字符串原型方法；必须先用 `String(value)` 转换。
+- **必须**在每次生成/修改时递增 `package.json` 的 `version` 字段（初次 `1.0.0`；迭代修改按范围递增）。
+- **必须**在 `vite.config.ts` 中通过 `define` 注入 `__APP_VERSION__`（`JSON.stringify(pkg.version)`）和 `__APP_SKILL__`（`JSON.stringify('lab-orbit-component-builder')`）。
+- **必须**在每个生成的**最上层入口组件**（`src/views/<业务>.vue`）的 `<script setup>` 中添加 `console.info` 打印版本信息；子组件不需要版本打印。