@xtalpi/agentic-lab-skills 0.0.10 → 0.0.11

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

@@ -1,179 +1,179 @@
-# 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` 中定义）到业务文档。
-
----
-
-## 质量检查 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`。
+# 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` 中定义）到业务文档。
+
+---
+
+## 质量检查 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`。

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

@@ -1,49 +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 反模式表一致）。
+# 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

@@ -1,32 +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、校验规则），避免从零重写子表状态机。
+# 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、校验规则），避免从零重写子表状态机。