@xtalpi/agentic-lab-skills 0.0.10 → 0.0.11

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

@@ -1,65 +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`）；与 **lab-flow-designer** 列表类约定一致时注意网关上限 |
-| **语言类型** | 影响 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`**），并与接口返回字段做映射。
+# 流程文档 → 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`）；与 **lab-flow-designer** 列表类约定一致时注意网关上限 |
+| **语言类型** | 影响 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/orbit-vue-conventions.md

@@ -1,133 +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 依赖，除非向用户说明原因并获得同意
+# 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/pool-schema-to-columns.md

@@ -1,67 +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` 之前**必须**执行，校验不通过时阻止提交。
+# 池 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` 之前**必须**执行，校验不通过时阻止提交。