@xtalpi/agentic-lab-skills 0.0.4 → 0.0.6

package/skills/lab-nocobase-flow-generator/templates//350/204/232/346/234/254/351/200/273/350/276/221/346/226/207/346/241/243/347/244/272/344/276/213.md

@@ -0,0 +1,67 @@
+# 查询设备统计信息
+
+## 1. 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 脚本名称 | 查询设备统计信息 |
+| 业务场景 | 根据设备型号或工站名称查询 device 表，返回设备列表，并按 `model_name` 分组统计每种设备型号的数量和最后更新时间 |
+| 输入参数来源 | `input_data` |
+
+---
+
+## 2. 输入参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| model_id | number | 否 | 设备型号 ID，传入则只查询该型号的设备 |
+| station_name | string | 否 | 工站名称，传入则只查询该工站的设备 |
+
+**参数校验规则：**
+- 两个参数均为可选，都不传则查询全部设备
+
+---
+
+## 3. 数据操作
+
+### 3.1 NocoBase 数据库操作
+
+#### 操作 1：查询设备列表
+
+| 字段 | 值 |
+|------|-----|
+| 数据表 | `device` |
+| 操作类型 | `find` |
+| 关联加载 | 无 |
+
+**过滤条件：**
+- 若传入 `model_id`，按 `model_id` 精确匹配
+- 若传入 `station_name`，按 `station_name` 精确匹配
+
+---
+
+## 4. 核心逻辑
+
+1. 从 `input_data` 解构参数
+2. 根据传入的参数动态构建过滤条件
+3. 查询 `device` 表
+4. 按 `model_name` 分组统计：
+   - 每种型号的设备数量
+   - 每种型号中最近的 `update_time`（即最后更新时间）
+5. 返回设备列表和统计结果
+
+---
+
+## 5. 输出结果
+
+| 场景 | 返回值 | 类型 |
+|------|--------|------|
+| 成功 | `{ devices: 设备列表, stats: [{ model_name, count, last_update_time }] }` | object |
+| 无数据 | `"No device found"` | string |
+| 异常 | `"Error: 错误信息"` | string |
+
+---
+
+## 6. 备注
+
+- 无

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

@@ -7,7 +7,7 @@ description: >-
   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.2.4"
+  version: "1.3.0"
   runtime: Orbit-XNB-Vue-Component
   template_path: examples/xnb-component-template
 ---
@@ -128,6 +128,7 @@ metadata:
 | **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) |
 
@@ -141,9 +142,27 @@ metadata:
 
 ## 工作流（给 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）。
@@ -161,7 +180,7 @@ metadata:
 
 ### 1A. 首次生成（目标目录无工程）
 
-**目标**：从模板 `examples/xnb-component-template` 搭建完整工程，再生成业务组件。
+**目标**：在目标工程目录下（按 §0 创建或定位），从模板 `examples/xnb-component-template` 搭建完整工程，再生成业务组件。
 
 #### 第一步：复制脚手架基础设施
 
@@ -200,8 +219,8 @@ metadata:
 
 1. 新建 `src/views/<业务语义>.vue`（按规则 1-4 实现 opener、列定义、校验、提交）
 2. 新建 `src/entries/<id>.ts`
-3. 更新 `vite.config.ts` 中的 `COMPONENT_MAP`（**清空**模板示例的 `bitable` / `custom-page` 条目，仅保留业务条目）
-4. `package.json` **原样保留**模板内容（`name`、`version`、`main`、`dependencies`、`devDependencies`、`webb` 等字段**禁止改动**），仅在 `scripts` 中**追加** `dev:<id>` / `build:<id>` 条目
+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` 等）
 
@@ -221,8 +240,8 @@ metadata:
 
 **禁止修改**（除非用户明确要求）：
 
-- `package.json` 中的 `dependencies` / `devDependencies`
-- `vite.config.ts`（除 `COMPONENT_MAP` 外）、`vite.dev.config.ts`、`tsconfig.json`
+- `package.json` 中的 `dependencies` / `devDependencies`（`version` 字段除外——每次修改**必须**递增 `version`）
+- `vite.config.ts`（除 `COMPONENT_MAP` 和 `define` 外）、`vite.dev.config.ts`、`tsconfig.json`
 - `dev/` 目录
 - `src/utils/orbitHttpClient.ts`
 
@@ -236,6 +255,15 @@ metadata:
 | 修改 API | 编辑 `src/api/agenticlabTickets.ts`（新增接口、修改映射等） |
 | 修改类型 | 编辑 `src/types/xnb-context.ts`（扩展 context 类型等） |
 | 修改环境配置 | 编辑 `.env.local`（新增/修改环境变量） |
+| 递增版本 | 修改 `package.json` 的 `version` 字段（每次生成/修改必须递增） |
+
+#### 增量修改原则
+
+- **Composable 扩展**：新增函数添加到现有 composable 的 `return {}` 中，不新建重复功能的 composable
+- **组件拆分**：单个 `.vue` 超过 600 行时按功能块拆为子组件，保持原组件为入口
+- **不重新生成**：只修改需要变更的部分，不重新生成未涉及的代码段
+- **参数兼容**：修改函数签名时用可选参数扩展，不破坏现有调用
+- **依赖管控**：不添加新 npm 依赖，除非向用户说明原因并获得同意
 
 **增量修改前，先读取现有代码**：
 
@@ -261,8 +289,23 @@ metadata:
 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` 后手动验证
+- 若检查失败，自动修复后再次验证；仅需要业务决策的问题才向用户确认
 
-### 3. 输出与自检
+### 4. 输出与自检
 
 - 列出新增/修改文件路径；说明每个入口组件对应的门控名称与 `dist/registrarName`。
 - 自检项：
@@ -280,6 +323,7 @@ metadata:
   - [ ] 全量刷新已按 §8.5.2 处理（整表替换 items）
   - [ ] `DEMO_*` 常量已替换为业务语义命名
   - [ ] 字段值映射使用 `String()` 转换，未直接调用 `.trim()` 等字符串方法
+  - [ ] `package.json` 的 `version` 已设置/递增；最上层入口视图含 `console.info` 版本打印（子组件无需）；`vite.config.ts` 含 `define` 注入 `__APP_VERSION__` 和 `__APP_SKILL__`
 
 ---
 
@@ -289,6 +333,7 @@ metadata:
 - **首次生成时必须**复制完整脚手架基础设施（见步骤 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`。
@@ -303,3 +348,6 @@ metadata:
 - 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` 打印版本信息；子组件不需要版本打印。

package/skills/lab-orbit-component-builder/examples/xnb-component-template/dev/src/global.d.ts

@@ -2,6 +2,9 @@ declare module '@xtalpi/webb-api'
 declare module 'axios'
 declare module 'lodash'
 
+declare const __APP_VERSION__: string
+declare const __APP_SKILL__: string
+
 interface XnbHttpClient {
   request: (options: {
     method: string;

package/skills/lab-orbit-component-builder/examples/xnb-component-template/dev/src/main.ts

@@ -50,14 +50,17 @@ import App from './App.vue'
 
 // ==================== 多入口视图加载 ====================
 
-const COMPONENT_ID = import.meta.env.VITE_COMPONENT_ID || 'bitable'
 const viewModules = import.meta.glob('../../src/views/*.vue', { eager: true })
+const viewKeys = Object.keys(viewModules)
+const COMPONENT_ID = import.meta.env.VITE_COMPONENT_ID
+  || (viewKeys.length === 1 ? viewKeys[0].replace('../../src/views/', '').replace('.vue', '') : '')
+
 const viewKey = `../../src/views/${COMPONENT_ID}.vue`
 const viewModule = viewModules[viewKey] as { default: any } | undefined
 if (!viewModule) {
-  const available = Object.keys(viewModules).map((k: string) => k.replace('../../src/views/', '').replace('.vue', '')).join(', ')
+  const available = viewKeys.map((k: string) => k.replace('../../src/views/', '').replace('.vue', '')).join(', ')
   throw new Error(
-    `[dev] VITE_COMPONENT_ID=${COMPONENT_ID} 无对应视图。当前已有: ${available}`
+    `[dev] VITE_COMPONENT_ID=${COMPONENT_ID} 无对应视图。可用: ${available}。请在 .env.local 设置 VITE_COMPONENT_ID 或使用 npm run dev:<id>`
   )
 }
 const View = viewModule.default

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

@@ -16,7 +16,9 @@
     "build:custom-page": "VITE_COMPONENT_ID=custom-page vite build --mode func",
     "build:all": "npm run build:bitable && npm run build:custom-page",
     "build:es": "vite build",
-    "lint": "eslint --ext .js,.ts,.tsx,.vue src"
+    "lint": "eslint --ext .js,.ts,.tsx,.vue src",
+    "lint:fix": "eslint --fix --ext .js,.ts,.tsx,.vue src",
+    "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
     "@vueuse/core": "^10.2.1"
@@ -38,6 +40,7 @@
     "rollup-plugin-external-globals": "^0.13.0",
     "sass": "~1.77.6",
     "typescript": "~5.5.0",
+    "vue-tsc": "^2.0.0",
     "vite": "^5.4.0",
     "vite-plugin-compression": "^0.5.1",
     "vite-plugin-css-injected-by-js": "^3.5.2",

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/styles/orbit-quasar-host.scss

@@ -6,7 +6,7 @@
  * 复用：在 SFC 的 `<style scoped lang="scss">` 内首行 `@import '@/styles/orbit-quasar-host.scss';`
  * （须 scoped + `:deep(.q-btn)`，否则子组件 DOM 无法命中）
  * 主题调整：新增/修改主色或全局 `q-btn` 表现请只改本文件；页面结构见 `src/views/bitable.vue`。
- * 按钮分工：`primary` 仅提交等持久化写回；`outline` 仅刷新/检查等页面数据交互（见 studio-orbit-vue-component SKILL 规则 2）。
+ * 按钮分工：`primary` 仅提交等持久化写回；`outline` 仅刷新/检查等页面数据交互（见 lab-orbit-component-builder SKILL 规则 2）。
  */
 .orbit-quasar-host {
   --orbit-primary: #123aff;

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/use/useBitablePage.ts

@@ -98,12 +98,21 @@ export function useBitablePage (getContext: () => XnbSuperCellContext): UseBitab
     }
   }
 
+  let _bootstrapCellKey = ''
+  let _bootstrapping = false
+
   async function runBootstrapSafe (): Promise<void> {
-    if (!choreo.value) return
+    if (!choreo.value || _bootstrapping) return
+    const key = `${getContext().bookPath}|${getContext().cellUid}`
+    if (key === _bootstrapCellKey) return
+    _bootstrapping = true
+    _bootstrapCellKey = key
     try {
       await bootstrap()
     } catch {
       /* composable 内已 notify */
+    } finally {
+      _bootstrapping = false
     }
   }
 

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/use/useSuperTableBitableLifecycle.ts

@@ -188,18 +188,20 @@ export function useSuperTableBitableLifecycle (
   const lastAgenticRawTickets = ref<Record<string, unknown>[]>([])
   const cellUid = computed(() => getContext().cellUid || '')
 
+  let _prevBookPath = ''
+  let _prevCellUid = ''
+
   watch(
     () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
     () => {
       const ctx = getContext()
+      const bp = ctx.bookPath
+      const cu = ctx.cellUid
+      if (bp === _prevBookPath && cu === _prevCellUid && choreo.value != null) return
+      _prevBookPath = bp
+      _prevCellUid = cu
       const Ctor = ctx.XNBBitable
-      choreo.value =
-        Ctor != null
-          ? new Ctor({
-            bookPath: ctx.bookPath,
-            cellUid: ctx.cellUid
-          })
-          : null
+      choreo.value = Ctor != null ? new Ctor({ bookPath: bp, cellUid: cu }) : null
     },
     { immediate: true }
   )
@@ -242,7 +244,7 @@ export function useSuperTableBitableLifecycle (
     await x.addColumns(bitable, cols, [])
     handleBitable(bitable, sub)
     await x.updateSubBitable([bitable], { isMerge: false, name: DEMO_SUB_TABLE_NAME })
-    if (typeof x.delay === 'function') await x.delay(20)
+    if (typeof x.delay === 'function') await x.delay(300)
   }
 
   async function createEmptyBitable (isMerge = false): Promise<void> {
@@ -254,13 +256,18 @@ export function useSuperTableBitableLifecycle (
       await x.addColumns(bitable, dataColumns, [])
       handleBitable(bitable, listSub)
       await x.updateSubBitable([bitable], { isMerge, name: DEMO_SUB_TABLE_NAME })
-      if (typeof x.delay === 'function') await x.delay(10)
+      if (typeof x.delay === 'function') await x.delay(300)
       return
     }
     const bitable: Record<string, unknown> = { items: [], data_columns: [] }
     handleBitable(bitable, listSub)
     await x.addColumns(bitable, dataColumns, [])
-    await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+    try {
+      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+    } catch {
+      if (typeof x.delay === 'function') await x.delay(500)
+      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+    }
   }
 
   async function fetchDemoList (): Promise<DemoListRow[]> {
@@ -367,6 +374,7 @@ export function useSuperTableBitableLifecycle (
 
       if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
         await rebuildSubBitableColumns(bitable, listSub, dataColumns)
+        bitable = (await resolveBitableBySub(listSub)) ?? bitable
       }
 
       const rows = await fetchDemoList()

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/views/bitable.vue

@@ -21,13 +21,15 @@
 <script lang="ts" setup>
 /**
  * 模板内演示用超级表格工具栏示例（非业务交付物）。
- * studio-orbit-vue-component 技能：向用户目标目录产出时勿原样复制本文件；请按流程文档新建具语义的 `src/views/<业务>.vue` 并参考此处写法。
+ * lab-orbit-component-builder 技能：向用户目标目录产出时勿原样复制本文件；请按流程文档新建具语义的 `src/views/<业务>.vue` 并参考此处写法。
  *
  * 刷新 / 提交：在 `useBitablePage` 内经 Quasar 对话框确认后再执行。
  */
 import { useBitablePage } from '@/use/useBitablePage'
 import type { XnbSuperCellContext } from '@/types/xnb-context'
 
+console.info(`[OrbitComponent] v${__APP_VERSION__} (skill: ${__APP_SKILL__})`)
+
 const props = defineProps<{
   xnbContext: XnbSuperCellContext
 }>()

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/views/custom-page.vue

@@ -1,6 +1,6 @@
 <!--
   模板内演示用多区页面示例（非业务交付物）。
-  studio-orbit-vue-component 技能：向用户目标目录产出时勿原样复制本文件；请按流程文档新建具语义的 views 与 entries。
+  lab-orbit-component-builder 技能：向用户目标目录产出时勿原样复制本文件；请按流程文档新建具语义的 views 与 entries。
 
   场景：复杂多组件页面（不使用超级表格 / XNBBitable）
   入口文件名：custom-page.vue（与 xnb-components 中 id 一致）

package/skills/lab-orbit-component-builder/examples/xnb-component-template/tsconfig.json

@@ -35,14 +35,11 @@
   "include": [
     "src/**/*.ts",
     "src/**/*.tsx",
-    "src/**/*.vue",
-    "dev/src/**/*.ts",
-    "dev/src/**/*.tsx",
-    "dev/src/**/*.vue",
-    "vite.config.ts",
-    "vite.dev.config.ts"
+    "src/**/*.vue"
   ],
   "exclude": [
-    "node_modules"
+    "node_modules",
+    "dev",
+    "dist"
   ]
 }

package/skills/lab-orbit-component-builder/examples/xnb-component-template/vite.config.ts

@@ -109,6 +109,10 @@ export default defineConfig(({ mode }) => {
         deleteOriginFile: false
       })
     ],
+    define: {
+      __APP_VERSION__: JSON.stringify(pkg.version),
+      __APP_SKILL__: JSON.stringify('lab-orbit-component-builder'),
+    },
     resolve: {
       alias: {
         '@': resolve(__dirname, 'src'),
@@ -136,6 +140,7 @@ export default defineConfig(({ mode }) => {
     },
     build: {
       outDir: resolve(__dirname, 'dist'),
+      emptyOutDir: false,
       sourcemap: true,
       cssCodeSplit: false,
       minify: false,

package/skills/lab-orbit-component-builder/examples/xnb-component-template/vite.dev.config.ts

@@ -2,6 +2,9 @@ import { defineConfig, loadEnv } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
 import { resolve } from 'path'
+import { readFileSync } from 'fs'
+
+const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'))
 
 export default defineConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), '')
@@ -12,6 +15,10 @@ export default defineConfig(({ mode }) => {
       vue({ template: { transformAssetUrls } }),
       quasar({ sassVariables: 'quasar/src/css/variables.sass' })
     ],
+    define: {
+      __APP_VERSION__: JSON.stringify(pkg.version),
+      __APP_SKILL__: JSON.stringify('lab-orbit-component-builder'),
+    },
     resolve: {
       alias: {
         '@': resolve(__dirname, 'src'),

package/skills/lab-orbit-component-builder/references/flow-document-human-ui.md

@@ -39,7 +39,7 @@
 | 文档配置项 | 落地建议 |
 |------------|----------|
 | **AppBaseUrl** | 本地/CI：`VITE_AGENTICLAB_API_URL`（见模板 `.env.local.example`）；Orbit 内 HTTP 走 `orbitRequestJson` / `window.xnb.http.client.request`，基址以宿主代理为准 |
-| **数据查询上限** | 列表请求 `limit` 默认值（如 `9000`）；与 **flow-package-from-design** 列表类约定一致时注意网关上限 |
+| **数据查询上限** | 列表请求 `limit` 默认值（如 `9000`）；与 **lab-flow-designer** 列表类约定一致时注意网关上限 |
 | **语言类型** | 影响 UI 文案语言（中/英）；未给定时与团队默认一致 |
 
 门控级 **脚本配置项**（如 StationBaseURL）属于 **后置/工站脚本**，不默认写进 Vue 页；若文档明确要求页面内调用，再在 `AgenticAppAPI` 之外单独增加 `src/api/*` 与环境变量。

package/skills/lab-orbit-component-builder/references/orbit-vue-conventions.md

@@ -0,0 +1,133 @@
+# Orbit Vue 组件编码约定
+
+本文档定义本技能生成/修改 Orbit Vue 组件时**必须遵循**的编码模式与约定。
+
+---
+
+## 1. 技术栈约束
+
+- **框架**：Vue 3.2（Composition API，`<script setup lang="ts">`）
+- **UI 组件库**：Quasar 2.x
+- **语言**：TypeScript 5.x（strict）
+- **构建工具**：Vite 5
+- **禁止使用**：`any`、`enum`、Pinia、Vuex、vue-router、Tailwind、fetch、axios
+
+## 2. 命名约定
+
+| 类别 | 规则 | 示例 |
+|------|------|------|
+| 组件 `.vue` 文件 | PascalCase 或 kebab-case（与门控 id 对齐） | `WeighingConfirm.vue`、`sample-prep.vue` |
+| Composable 文件 | camelCase + 功能后缀 | `useSuperTableBitableLifecycle.ts` |
+| 类型 / 接口 | PascalCase，**无 `I` 前缀** | `WeighingRow`、`SamplePrepConfig` |
+| 常量 | UPPER_SNAKE_CASE | `SUB_TABLE_NAME`、`LIST_COLS` |
+| 联合类型 | `type XxxKind = 'a' | 'b'` | `type DosingMethod = 'liquid' | 'neo'` |
+| 私有函数 | `_` 前缀，不 export | `_mapTicketToRow`、`_buildSubmitPayload` |
+| CSS 类名 | kebab-case | `.weighing-toolbar`、`.row-count` |
+
+## 3. Singleton Composable 模式
+
+状态 `ref` 定义在函数**外部**（模块级单例），`computed` / 方法在函数**内部**。此模式与 `useSuperTableBitableLifecycle.ts` 一致。
+
+```typescript
+import { ref, computed } from 'vue'
+
+// 模块级单例状态
+const items = ref<RowType[]>([])
+const loading = ref(false)
+
+export function useXxxLifecycle() {
+  const validItems = computed(() => items.value.filter(r => r.valid))
+
+  async function refreshTable(): Promise<void> {
+    loading.value = true
+    try {
+      // ...
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { items, loading, validItems, refreshTable }
+}
+```
+
+**规则**：
+- `loading` 在请求前设 `true`，在 `finally` 中设 `false`
+- 私有函数以 `_` 前缀命名，不放入 `return`
+
+## 4. TypeScript 纪律
+
+- **禁止 `any`**：使用 `unknown` + 类型断言（`as XxxType`）
+- **禁止 `enum`**：使用联合类型 `type Status = 'pending' | 'completed'`
+- **接口名无 `I` 前缀**：`interface WeighingRow`（不是 `IWeighingRow`）
+- **新增字段标为可选**：`newField?: string`，不删除已有字段
+- **字段值安全转换**：从 API / 行数据取出的值先 `String()` 再做字符串操作
+
+```typescript
+// ✅ 正确
+fields[field] = raw == null ? '' : String(raw)
+
+// ❌ 错误：raw 可能是 number / null
+fields[field] = raw.trim()
+```
+
+## 5. 组件编写规则
+
+### 基本结构（最上层入口组件）
+
+```vue
+<template>
+  <div class="orbit-quasar-host component-name">
+    <!-- 内容 -->
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { XnbSuperCellContext } from '@/types/xnb-context'
+
+// 仅最上层入口组件打印版本，子组件不需要
+console.info(`[OrbitComponent] v${__APP_VERSION__} (skill: ${__APP_SKILL__})`)
+
+const props = defineProps<{ xnbContext: XnbSuperCellContext }>()
+// ...
+</script>
+
+<style scoped lang="scss">
+@import '@/styles/orbit-quasar-host.scss';
+.component-name { /* ... */ }
+</style>
+```
+
+### Props
+
+```typescript
+defineProps<{
+  xnbContext: XnbSuperCellContext
+  title?: string
+  variant?: 'primary' | 'outline'
+}>()
+
+defineEmits<{ (e: 'submit', payload: unknown): void }>()
+```
+
+### 组件大小限制
+
+- 单个 `.vue` 文件**不超过 600 行**
+- 超过时按功能区块拆分为子组件，原组件保持入口职责
+- 拆分后子组件通过 props / emits 通信，不共享模块级 ref
+
+## 6. 样式约定
+
+- **页面入口**（`src/views/<id>.vue`）：根节点带 `orbit-quasar-host`，`<style scoped lang="scss">` 首行 `@import '@/styles/orbit-quasar-host.scss'`
+- **子组件**：`<style scoped>` **纯 CSS**，禁止 `lang="scss"`；样式变量用 CSS 自定义属性 `var(--c-xxx)`
+- 主题调整**优先改** `src/styles/orbit-quasar-host.scss`，不在业务 SFC 散落主题变量
+- 使用 `:deep()` 穿透 Quasar 组件内部样式
+
+## 7. 增量开发原则
+
+- **增量优先**：优先修改现有文件，新增字段加到现有 interface，新函数加到现有 composable
+- **向后兼容**：新增字段标为可选（`?`），需移除时先标记 `@deprecated`
+- **Composable 扩展**：新增函数添加到现有 composable 的 `return {}` 中，不新建重复功能的 composable
+- **不重新生成**：只修改需要变更的部分，不重新生成未涉及的代码段
+- **参数兼容**：修改函数签名时用可选参数扩展，不破坏现有调用
+- **依赖管控**：不添加新 npm 依赖，除非向用户说明原因并获得同意

package/skills/lab-orbit-component-builder/references/vue-template-checklist.md

@@ -111,3 +111,69 @@
 ## 静态加载契约（宿主）
 
 README 中 JsCode 返回 `component.view / filename / source / params` 的占位；生成业务组件后须同步 **`registrarName` 与 `distBaseName`**（在 `vite.config.ts` 的 `COMPONENT_MAP` 中定义）到业务文档。
+
+---
+
+## 质量检查 npm scripts（平台无关）
+
+模板 `package.json` 内置以下质量检查脚本，任何 Agent 平台或人工均可直接调用：
+
+| 命令 | 作用 |
+|------|------|
+| `npm run lint` | ESLint 检查（仅报告，不修改） |
+| `npm run lint:fix` | ESLint 自动修复 |
+| `npm run typecheck` | TypeScript 类型检查（`vue-tsc --noEmit`） |
+| `npm run build` | 构建验证 |
+
+生成/修改代码后，按 `lint:fix → typecheck → build` 顺序执行，修复发现的问题。
+
+---
+
+## 可选：Claude Code PostToolUse Hook
+
+> 以下配置**仅适用于 Claude Code**，其它 Agent 平台请使用上方的 npm scripts。
+
+为生成的 Orbit Vue 工程配置 PostToolUse hook，在每次编辑文件后自动对单文件运行 `eslint --fix`：
+
+### `.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-edit-lint.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### `.claude/hooks/post-edit-lint.sh`
+
+```bash
+#!/bin/bash
+# PostToolUse hook: auto eslint --fix on edited .vue/.ts/.tsx files
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_input', {}).get('file_path', ''))
+except:
+    pass
+" 2>/dev/null)
+
+if [[ -n "$FILE" && ("$FILE" == *.vue || "$FILE" == *.ts || "$FILE" == *.tsx) ]]; then
+    cd "$(dirname "$0")/../.." && npx eslint --fix "$FILE" 2>&1 | tail -5
+fi
+```
+
+> 首次生成工程时，可将 `.claude/` 目录一并创建到用户目标工程中（如用户同意）。记得 `chmod +x .claude/hooks/post-edit-lint.sh`。