@xtalpi/agentic-lab-skills 0.0.1

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

@@ -0,0 +1,51 @@
+import { defineConfig, loadEnv } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { quasar, transformAssetUrls } from '@quasar/vite-plugin'
+import { resolve } from 'path'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')
+
+  return {
+    root: resolve(__dirname),
+    plugins: [
+      vue({ template: { transformAssetUrls } }),
+      quasar({ sassVariables: 'quasar/src/css/variables.sass' })
+    ],
+    resolve: {
+      alias: {
+        '@': resolve(__dirname, 'src'),
+        'Views': resolve(__dirname, 'src/views'),
+        'Libs': resolve(__dirname, 'src/libs'),
+        'Components': resolve(__dirname, 'src/components'),
+        'Api': resolve(__dirname, 'src/api'),
+        'Utils': resolve(__dirname, 'src/utils'),
+        'Assets': resolve(__dirname, 'src/assets'),
+        'Types': resolve(__dirname, 'src/types'),
+        'Plugins': resolve(__dirname, 'src/plugins')
+      }
+    },
+    css: {
+      preprocessorOptions: {
+        sass: {
+          additionalData: '@import "quasar/src/css/variables.sass"\n',
+          silenceDeprecations: ['legacy-js-api', 'import', 'global-builtin', 'slash-div']
+        },
+        scss: {
+          additionalData: '@import "quasar/src/css/variables.sass";',
+          silenceDeprecations: ['legacy-js-api', 'import', 'global-builtin', 'slash-div']
+        }
+      }
+    },
+    server: {
+      proxy: env.VITE_REQUEST_URL
+        ? {
+            '/api': {
+              target: env.VITE_REQUEST_URL,
+              changeOrigin: true
+            }
+          }
+        : undefined
+    }
+  }
+})

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

@@ -0,0 +1,65 @@
+# 流程文档 → Orbit Vue 人工处理页
+
+## 识别目标章节
+
+在流程说明 Markdown 中，每个门控下通常存在：
+
+- **`#### 人工处理`**（或文档约定的同级标题）
+- **`##### 界面形态与数据绑定`**：条目化描述界面类型与按钮
+
+示例（节选，语义对齐即可）：
+
+1. **界面类型**：超级表格  
+2. **刷新按钮**：重新获取所有数据  
+3. **检查按钮**：检查所有规则是否验证通过  
+4. **提交按钮**：检查所有数据通过后调用 AgenticLab App 接口提交  
+
+当 **界面类型** 为「超级表格」时，生成物应对齐模板中的 **`bitable.vue` + `useBitablePage` + `useSuperTableBitableLifecycle`** 能力（刷新 / 检查 / 提交）；若为「自定义多区页面」等，则以 **`custom-page.vue`** 为骨架扩展，**不强行**挂载 XNBBitable。
+
+## 样式主题与按钮（默认）
+
+除非流程文档或用户在任务中**明确描述**了不同 UI，否则：
+
+| 参照 | 用途 |
+|------|------|
+| `examples/xnb-component-template/src/views/bitable.vue` | 页面结构、工具栏、`q-btn` 属性分工 |
+| `examples/xnb-component-template/src/styles/orbit-quasar-host.scss` | Cell 内 Quasar 主题（主色、`q-btn` 全局）；**新增/调整主题只改此文件** |
+
+| 文档按钮语义 | `q-btn` 约定 |
+|--------------|--------------|
+| 刷新、检查等（拉数、本地校验，不改持久化数据） | `dense outline`，**不用** `color="primary"` |
+| 提交等（校验通过后写回 / `execution/complete`） | `color="primary" dense unelevated`，**不用** `outline` |
+
+详见主技能 **SKILL.md** 规则 2、规则 6。
+
+## 人工处理配置项表
+
+流程文档常见表格列：**配置项 | 类别 | 默认值/占位 | 说明**。
+
+| 文档配置项 | 落地建议 |
+|------------|----------|
+| **AppBaseUrl** | 本地/CI：`VITE_AGENTICLAB_API_URL`（见模板 `.env.local.example`）；Orbit 内 HTTP 走 `orbitRequestJson` / `window.xnb.http.client.request`，基址以宿主代理为准 |
+| **数据查询上限** | 列表请求 `limit` 默认值（如 `9000`）；与 **flow-package-from-design** 列表类约定一致时注意网关上限 |
+| **语言类型** | 影响 UI 文案语言（中/英）；未给定时与团队默认一致 |
+
+门控级 **脚本配置项**（如 StationBaseURL）属于 **后置/工站脚本**，不默认写进 Vue 页；若文档明确要求页面内调用，再在 `AgenticAppAPI` 之外单独增加 `src/api/*` 与环境变量。
+
+## 一门控一页：多组件命名
+
+- **一个门控**对应文档中 **一块**「人工处理」描述 → **一个独立入口组件**（`vite.config.ts` 中 `COMPONENT_MAP` 的一个 key）；视图文件须为 **`src/views/<业务语义>.vue`**，**不要**把模板里的 `bitable.vue` / `custom-page.vue` 复制到用户目录当交付物（模板内文件仅作阅读参考，见 **`references/vue-template-checklist.md`**）。
+- **多个门控**各自有人工处理 → **同一工程**下多个 `src/views/<id>.vue`，**禁止**把无关联门控硬塞进同一视图（除非文档明确要求合并）。
+
+### 命名规则（须有业务意义）
+
+| 来源 | 建议 |
+|------|------|
+| 门控 YAML `name` / `valve_id` | `views` 文件名：`process-execute-manual`；`distBaseName`：`FragmentProcessExecuteManual`（示例） |
+| 流程名称 + 门控简称 | 避免仅用 `bitable`、`gate1` |
+| `registrarName` | 与宿主/Book 约定一致；与 `distBaseName` 可同可异，见模板 README「命名约定」 |
+
+生成后应在业务 README 或 Skill 输出中写明：**文档门控标题 ↔ 组件 id ↔ `registrarName` ↔ UMD 文件名**。
+
+## 与数据池的衔接
+
+- 人工处理页的 **主表格数据源** 通常对应门控 **primary 输入池** 的只读列表（或工单 `ticket/list` 映射后的行）。
+- 列定义优先来自 **`pools/<池名>.md` 的 Schema 表**（见 **`pool-schema-to-columns.md`**），并与接口返回字段做映射。

package/skills/lab-orbit-component-builder/references/pool-schema-to-columns.md

@@ -0,0 +1,67 @@
+# 池 Schema → XNBBitable 列（默认展示策略）
+
+## 数据来源
+
+流程包或业务文档中的 **`pools/<池名>.md`** 常见「Schema」表：**字段 | 字段标题 | 字段描述 | 字段类型 | …**。
+
+人工处理超级表格的 **默认列集**应来自门控 **primary 输入池** 的该表（或流程正文中等价表格）。
+
+## 字段类型映射（仅表格友好子集）
+
+XNBBitable / Luckysheet 列通过 **`data_columns`** 描述（模板见 `useSuperTableBitableLifecycle.ts` 中 `dv` / `ct`）。
+
+| 池 Schema「字段类型」 | 是否默认生成列 | `dv` / `ct` 建议 |
+|----------------------|----------------|------------------|
+| **text** | 是 | `dv: { type: 'text_length' }`，只读列可加 `readonly: true` |
+| **int** / **number** | 是 | `dv: { type: 'number' }`，`ct: { fa: '0', t: 'n' }`（与模板数量列一致） |
+| **json** | **默认否** | 数组/对象在单格展示与校验复杂；若业务必须展示，可改为 **只读字符串列**（`JSON.stringify` 摘要）或拆多列（需文档明确要求） |
+| **bool** | 视产品支持而定 | 若不确定渲染形态，可映射为 **text**（`true`/`false`）或单独与产品确认 |
+
+**原则**：首版交付以 **string / number** 类列为主，与「仅展示 XNBBitable 支持的类型」一致；**json** 型池字段不默认展开为多列，避免 `field` 与 `items` 展平规则不一致导致空格。
+
+## 列头与数据键
+
+- **`data_columns[].field`**：展示列头，建议使用 Schema 的 **「字段标题」**（或中英一致时用语义化标题）。
+- **`items` 每行 `fields` 的键**：必须与 **`field`** 一致（见 **OrbitAPI.md** §8.4.1 / **orbit-write-js-cell** 反模式表）。
+- 池内「字段」常为 **snake_case**（如 `source_barcode`），若接口返回 snake_case，列 `field` 可直接用该键或统一映射层；**同一表内保持一种约定**。
+
+## 接口映射
+
+当行数据来自 **AgenticLab `ticket/list`** 的 `detail` 对象时：
+
+- 在 composable 中编写 **`mapTicketToRow`**，把 `detail` 中需要的键映射到上表 **`field`** 键。
+- 未在 Schema 出现的字段默认 **不展示**（除非文档列在「界面额外列」）。
+
+## 可编辑字段策略（readonly vs 可人工录入）
+
+池 Schema 或流程文档中标记为「可人工录入」（或 `editable: true` / `manual_input: true` 等等效标注）的字段：
+
+- 在 `data_columns` 中设 **`readonly: false`**，用户可在表格中直接编辑
+- 在提交（`submitRows`）时，**仅**这些字段的修改值会被映射回 ticket `detail` 并提交
+
+**未标记为可人工录入**的字段默认 **`readonly: true`**，用户无法在表格中编辑。
+
+### 与提交参数的对齐
+
+可编辑字段必须与 ticket schema 中的可写路径一一对应（如 `detail.process_params['@requested_amount_mg']`）。
+
+`mergeEditedRowIntoAgenticTicket`（或等效合并函数）中，应**只回写可编辑字段**对应的 detail 路径，不可把 readonly 的展示列值回写覆盖原始数据。
+
+### 自定义渲染与编辑
+
+若池字段类型为 **json** 但用户明确要求展示：
+- 渲染前：将 JSON 拆解为 string 摘要（如 `JSON.stringify` 或提取特定子字段）
+- 提交时：将编辑后的 string 重新组装为原始 JSON 结构再写回 detail
+
+此类自定义逻辑仅在用户**明确描述**时实现，默认不展开 json 字段。
+
+## 校验（检查按钮）
+
+校验规则**默认**从池 Schema / 流程文档的字段约束生成，除非用户明确描述更多自定义校验规则：
+
+- **number** 列：按文档约束校验（范围、必填等）；模板示例为「数量为正」，业务应替换为实际规则。
+- **text** 列：非空、格式（条码、位置路径）等按文档实现。
+- **必填**：Schema 中标记 `required` 或「必填」的字段，校验时检查非空/非零。
+- **互斥/依赖**：文档描述了字段间约束关系时，在 `checkRows` 中实现对应逻辑。
+
+`checkRows` 在 `submitRows` 之前**必须**执行，校验不通过时阻止提交。

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

@@ -0,0 +1,113 @@
+# xnb-component-template 脚手架清单（生成/增量必查）
+
+路径前缀：`examples/xnb-component-template/`（相对本 skill 根目录）。
+
+## 首次生成 vs 增量修改（首要判断）
+
+**执行任何操作前，先检查用户目标目录是否已有工程。**
+
+| 标志文件 | 说明 |
+|----------|------|
+| `package.json`（含 `vite` devDependency） | 构建系统 |
+| `vite.config.ts`（含 `COMPONENT_MAP`） | 多入口配置 |
+| `src/use/useBitablePage.ts` | 核心 composable |
+
+- **全部不存在** → **首次生成**：复制完整脚手架 + 生成业务组件（见下文「首次生成清单」）
+- **已存在** → **增量修改**：仅修改/新增业务文件，**不触碰**基础设施（见下文「增量修改边界」）
+
+---
+
+## 首次生成清单
+
+### 必须复制的脚手架文件
+
+| 类别 | 文件 |
+|------|------|
+| 构建配置 | `package.json`、`vite.config.ts`、`vite.dev.config.ts`、`tsconfig.json`、`index.html`、`.nvmrc` |
+| 代码规范 | `.eslintrc.cjs`、`.eslintignore`、`.gitignore` |
+| 组件配置 | `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/` 整个目录 |
+| 文档 | `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. **`vite.config.ts`**：清空 `COMPONENT_MAP` 中的 `bitable` / `custom-page` 示例条目，替换为业务组件条目（`distBaseName`、`registrarName`）
+2. **`package.json`**：删除 `dev:bitable` / `build:bitable` / `dev:custom-page` / `build:custom-page` 脚本，替换为业务脚本；`main` 指向业务默认产物
+3. **`src/use/useSuperTableBitableLifecycle.ts`**：替换 `DEMO_*` 常量、`DemoListRow` 类型、映射/校验函数为业务逻辑
+4. **`.env.local`**：从 `.env.local.example` 复制，填入文档中的 `AppBaseUrl` 等
+
+---
+
+## 增量修改边界
+
+### 禁止修改（除非用户明确要求）
+
+- `package.json` 中的 `dependencies` / `devDependencies`
+- `vite.config.ts`（除 `COMPONENT_MAP` 外）、`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` |
+| 修改环境配置 | 编辑 `.env.local`（新增/修改环境变量） |
+
+### 增量修改前必读
+
+1. `vite.config.ts` 中的 `COMPONENT_MAP` → 已有哪些组件入口
+2. `src/use/useSuperTableBitableLifecycle.ts` → 当前列定义、校验、映射逻辑
+3. 目标 `src/views/<id>.vue` → 当前 UI 结构
+
+---
+
+## 新增一个入口组件（首次/增量均适用）
+
+| 步骤 | 文件 / 动作 |
+|------|-------------|
+| 1 | 新建 `src/views/<组件id>.vue`（`setup` + props） |
+| 2 | 新建 `src/entries/<组件id>.ts`：`export { default as View } from '../views/<组件id>.vue'` 与 `packageData` |
+| 3 | 在 `vite.config.ts` 的 `COMPONENT_MAP` 增加一项：`distBaseName`、`registrarName`、`label`（可选） |
+| 4 | 在 `package.json` → `scripts` 增加 `dev:<组件id>`、`build:<组件id>` |
+| 5 | 若作为 npm 包默认导出，更新 `package.json` 的 `main` 指向新产物 |
+
+## 超级表格相关文件（按需复制或 import）
+
+- `src/types/xnb-context.ts`：扩展 `XnbSuperCellContext` 时在此集中声明。
+- `src/use/useSuperTableBitableLifecycle.ts`：列定义、`bootstrap` / `refreshTable` / `checkRows` / `submitRows`。
+- `src/use/useBitablePage.ts`：opener 初始化、刷新确认框、挂载 watcher。
+- `src/utils/openerInitParams.ts`、`openerTicketIds.ts`、`orbitHttpClient.ts`。
+- `src/api/agenticlabTickets.ts`。
+- 本地调试：`dev/src/mockXNBBitable.ts`、`App.vue` 里注入假 `xnbContext`。
+
+## 文档链路
+
+- **运行时 HTTP / XNBBitable**：`OrbitAPI.md`（模板内为 orbit-write-js-cell API 的拷贝）。
+- **AgenticLab**：`AgenticAppAPI.md`。
+- **环境变量**：`.env.local.example`（开发，含 `VITE_DEV_TOKEN`、`VITE_AGENTICLAB_API_URL`）。
+
+## 静态加载契约（宿主）
+
+README 中 JsCode 返回 `component.view / filename / source / params` 的占位；生成业务组件后须同步 **`registrarName` 与 `distBaseName`**（在 `vite.config.ts` 的 `COMPONENT_MAP` 中定义）到业务文档。

package/skills/lab-orbit-component-builder/references/xnb-context-vue-props.md

@@ -0,0 +1,49 @@
+# xnbContext：JsCode 注入 vs Vue props
+
+## 差异摘要
+
+| 维度 | JsCode（`orbit-write-js-cell`） | Vue 组件（本技能 / 模板） |
+|------|----------------------------------|---------------------------|
+| 上下文来源 | 运行时注入，源码中可直接写 `xnbContext.cellUid` | **`defineProps<{ xnbContext: ... }>()`**，通过宿主挂载组件时传入 |
+| 典型入口 | 文件顶部 `const cellUid = xnbContext.cellUid` | `useXxx(() => props.xnbContext)` |
+| UI | `return \`...\`` HTML 字符串 | `<template>` + Quasar |
+
+## 与 `xnb-jscode` `useContext.ts` 的对照
+
+宿主侧 `XNBContext` 在构造时会把常用能力挂到 **`this.context`**（JsCode 里合并进 `xnbContext`）。Vue 侧应在 **`XnbSuperCellContext`**（模板 `src/types/xnb-context.ts`）上**按需扩展** props 类型，并在文档中注明「以宿主实际注入为准」。
+
+以下为 **常见** `context` 成员与 Vue 中的用法（名称以宿主为准）：
+
+| `useContext.ts` / 宿主 `context` | 用途 | Vue 中建议 |
+|----------------------------------|------|------------|
+| `bookPath` | Book 路径 | `props.xnbContext.bookPath`，传入 `XNBBitable` 与 HTTP |
+| `cellUid` | 当前 Cell | `props.xnbContext.cellUid` |
+| `notifySuccess` / `notifyError` | 轻提示 | 在 composable 中 `ctx.notifyError?.(...)` |
+| `loadingShow` / `loadingHide` | 全局 loading | 异步请求前后调用 |
+| `getUserData` / `updateUserData` / `mergeUserData` | Cell 用户数据 | 读配置、写回前合并（若宿主注入） |
+| `getInstanceValueById` / `setInstanceValueById` | Materialize 表单控件 | **Vue SFC 优先用 `v-model`/Quasar 表单**，仅在嵌入旧 HTML 片段时需要 |
+| `saveBitableConfig` / `getBitableConfig` / `clearBitableConfig` | 子表配置持久化 | 按需调用；注意异步与 book 名解析 |
+| `getXnbParams` / `updateXnbParams` | 运行参数 | 与提交 payload 合并（见 `afterRun` 逻辑对照） |
+| `XNBBitable`（类） | `new XNBBitable({ bookPath, cellUid })` | `props.xnbContext.XNBBitable`，存在时再创建 choreo 实例 |
+
+## 代码模式（模板已有；以下为**写法参考**，示例文件名 `bitable.vue` 不应用于用户业务复制粘贴）
+
+```vue
+<script lang="ts" setup>
+import { useBitablePage } from '@/use/useBitablePage'
+import type { XnbSuperCellContext } from '@/types/xnb-context'
+
+const props = defineProps<{
+  xnbContext: XnbSuperCellContext
+}>()
+
+const { onRefresh, onCheck, onSubmit, ... } = useBitablePage(() => props.xnbContext)
+</script>
+```
+
+**注意**：`watch(() => [getContext().bookPath, getContext().cellUid, ...])` 时，`getContext` 应始终读取 **最新** `props.xnbContext`，避免闭包捕获旧引用。
+
+## 禁止
+
+- 在 Vue SFC 中假设存在未注入的全局 **`xnbContext`** 变量（除非宿主明确提供且类型已声明）。
+- 使用已废弃的 `window.xnb.getUserData` 等（与 **OrbitAPI.md** §1.3 反模式表一致）。

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

@@ -0,0 +1,32 @@
+# Vue 中实现 XNBBitable：与 JsCode 语义对齐
+
+## 权威参考顺序
+
+1. **本仓库模板** [`examples/xnb-component-template/OrbitAPI.md`](../examples/xnb-component-template/OrbitAPI.md)（§7–§9、反模式 §1.3）——与线上 JsCode 文档同源摘要。  
+2. **`orbit-write-js-cell`** 技能中的 **`references/API.md`**（若助手环境已安装该 skill）：列与 `items`、`updateSubBitable`、`§8.5.2` 全量 list 为**唯一细粒度权威**。  
+3. **示例脚本** `orbit-write-js-cell/examples/bitable-list-lifecycle.js`：可复制其**状态机顺序**，改写成 `async function` + Vue `ref`，而非复制 `return` HTML。
+
+## Vue 风格改写要点
+
+| JsCode / 生命周期脚本 | Vue 等价物 |
+|----------------------|------------|
+| 顶部解构 `xnbContext` | `props.xnbContext` + `() => props.xnbContext` 传入 composable |
+| `const choreo = new xnbContext.XNBBitable({ bookPath, cellUid })` | `computed`/`ref` 保存实例；`watch` bookPath/cellUid 变化时重新 bootstrap |
+| `notifyError` / `loadingShow` | 同成员，从 `getContext()` 读取 |
+| 按钮 `onclick="window.xnb.cell.run(...)"` | `<q-btn @click="onRefresh">` 调用 composable 方法 |
+| `return \`...\`` 工具栏 | `<template>` 内 Quasar 布局 |
+
+## 必须遵守的 XNBBitable 规则（摘要）
+
+- **主列表唯一载体**：子表数据走 **`getSubBitable` / `getAllSubBitable` + `items` + `updateSubBitable`**；**不要**再用 `createCell('Sheet')`+`celldata` 做同一批数据的主表（**§7.0**）。  
+- **全量 list 刷新**：接口返回当前全集时，每次刷新 **`bitable.items = mappedRows`** 再 `updateSubBitable`，**不要**仅依赖「有行则按 id 合并」的增量逻辑（**§8.5.2**）。  
+- **列与行键一致**：`data_columns[].field` 必须与每行 `fields` 的键一致，否则「有表头无格内文字」。  
+- **重建列**：仅在首屏或 `dataColumnsMismatch` 时 `addColumns`；避免每次刷新都 `createSubBitable` 清空重建（**§8.5.1**）。
+
+## 模板内落地文件
+
+- **`src/use/useSuperTableBitableLifecycle.ts`**：`bootstrap`、`refreshTable`（`replaceAll`）、`checkRows`、`submitRows`。  
+- **`src/use/useBitablePage.ts`**：与 opener、`watch` 联动。  
+- **`src/types/xnb-context.ts`**：`XNBBitableChoreo` 方法签名对齐用。
+
+生成新业务组件时，优先 **扩展/参数化** 上述 composable（如注入列定义、mapRow、校验规则），避免从零重写子表状态机。