Release v1.0.122: document Action enumNames and column-bound static enum labels

2026-10-01 17:26:19 +08:00
parent cef7e366cf
commit 6644dedd0e
10 changed files with 148 additions and 17 deletions
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -110,7 +110,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 | **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**（行内/批量预填、选择摘要标签、勾选驱动模式、**行菜单显隐**，见下节） |
 | **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
 | **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载格子与 grid 呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
-| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`、可选 **`revealInForm`**；可选 `display_type` / `format`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
+| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、可选 **`enumNames`**、`default`、`required`、`sensitive`、`readOnly`、可选 **`revealInForm`**；可选 `column`（绑列复用 options）；可选 `display_type` / `format`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
 | confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
 | **hoverHint** | 可选字符串。数据管理**工具栏悬停**文案；与 `description` / `confirmation.message` **独立**。省略则不显示悬停，不回退。短名已够懂时不要写。需宿主已支持该字段；当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出 |
 | **visibleWhen** | 可选。写在 **property** 上（非 action 顶层）：依赖同表单其它字段值决定是否展示；隐藏字段不提交、不校验 `required`。**勿与** [`POLICY.md`](POLICY.md) L3 行态 `visibleWhen` 混淆；也**勿**用它藏「已选择」已表达的映射主键（见「选择摘要」） |
@@ -437,13 +437,14 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - 点默认「导入」时**固定**打开宿主导入面板；确认后若有 `replaces:import` 则调用该 Action（`interaction` 不决定是否再弹技能表单）。
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
 - `import` 约定：`filePath`（或 `file`）+ 可选 `onError`（`skip`/`abort` 或上例中文枚举）；技能自行解析文件与表头。
- 整表 `_jiangchang_tables.readonly=1` 时仍隐藏写按钮（优先于 `replaces`）。
- **列元数据复用（lookup）**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
-  - 优先让属性名 = 物理列名（如 `platform_key`）；
-  - 或 `bind.columnMapping`：`{ "platform": "platform_key" }`；
-  - 或字段上写 `"column": "platform_key"`。
-  - 当前表没有对应列时，用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
-  - **不要**在 actions.json 里写死会过期的全量平台 `enum`，也**不要**让用户手填内部编号。
+- 整表 `_jiangchang_tables.readonly=1` 时仍隐藏宿主默认新增/编辑/导入与直写删除；**若声明了 `replaces: delete`，宿主仍显示「删除」并走技能 CLI**（不直写 SQLite）。
+- **列元数据复用**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与列上 **options**（静态枚举 `options_json` **数组**，或已解析的 lookup）：
+  - 优先让属性名 = 物理列名（如 `carrier_code` / `platform_key`）；
+  - 或 `bind.columnMapping`：`{ "carrierCode": "carrier_code" }`；
+  - 或字段上写 `"column": "carrier_code"`（推荐：驼峰属性名时显式写出，避免只靠启发式）。
+  - 当前表没有对应列、且选项是**固定小枚举**时：用 `enum` + **`enumNames`**（见下文「静态枚举 label」），**不要**为中文展示去造 Lookup。
+  - 当前表没有对应列、且选项是**跨表/跨技能业务行**时：用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
+  - **不要**在 actions.json 里写死会过期的全量业务行 `enum`，也**不要**让用户手填内部编号。

 ## `interaction`（点击交互方式）

@@ -1141,7 +1142,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | JSON 长文本 | `type: object`/`array`（以 JSON 字符串编辑）或 `textarea` | `display_type: json` / `textarea` |
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
-| 枚举下拉 | `enum: [...]` | `options_json` 数组 |
+| 枚举下拉 | `enum: [...]` + 可选 **`enumNames`**；有对应列时再加 `column` / 属性名对齐，复用列 `options_json` | `options_json` **数组** `{value,label}` |
 | 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（`local_sql` / `skill_cli` / `external_api`；可选 `multiple`；可选 `presentation: "paged_table"`），或绑列 | 列侧仅同库 `local_sql`；多选存 `TEXT` 逗号分隔 id；分页小表只在 Action |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 年份 | `display_type` 或 `format`: `year` | `display_type: year` → 存 `YYYY` |
@@ -1161,7 +1162,34 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件

 **本版不做（勿宣传）：** 浏览器内文件上传控件、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐；Action 参数表单的列筛选对称。  
 （**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。**分页勾选小表**已支持：同一 `lookup` + `presentation: "paged_table"`，见「分页勾选小表」。）  
-（**本地路径选择**已支持：`file` / `directory` + 可选 `pathRoot`，见下节；提交值仍是本机绝对路径字符串，不是 multipart 上传。）
+（**本地路径选择**已支持：`file` / `directory` + 可选 `pathRoot`，见下节；提交值仍是本机绝对路径字符串，不是 multipart 上传。）  
+（**静态枚举中文 label**已支持：Action `enumNames` 与列 `options_json` 数组对称，见下节「静态枚举 label」。）
+
+### 静态枚举 label（`enum` / `enumNames` / 绑列）
+
+固定小枚举（状态、船司代码、优先级等）**不要**走 Lookup。CRUD 用列 `options_json` 数组；Action 表单要与「新增记录」对齐中文展示时，按下面做。
+
+**宿主解析优先序（高 → 低）：**
+
+1. **绑列 options**：字段通过 `column` / `columnMapping` / 属性名（含 camelCase→snake_case）对齐到当前表列，且该列已有解析后的 `options`（来自 `options_json` 数组或 lookup）→ 用列上的 `{value,label}`。
+2. **`enumNames`**：与 `enum` 下标一一对应的展示文案；缺项或空串回退为该位 `enum` 原文。
+3. **纯 `enum`**：无 label 时宿主只能显示代码值（体验差，新技能避免）。
+
+```json
+"carrierCode": {
+  "type": "string",
+  "title": "船司",
+  "column": "carrier_code",
+  "enum": ["maersk", "hmm"],
+  "enumNames": ["MAERSK 马士基", "HMM 现代商船"]
+}
+```
+
+推荐：
+
+- 表上已有同义枚举列 → **显式 `column`**（或属性名 = 列名）+ 列侧写好 `options_json`；`enum`/`enumNames` 可保留作无列上下文时的兜底（如 agent-only Action）。
+- 无对应列、仅 Action 表单需要 → 只写 `enum` + `enumNames`（见 [`assets/examples/enum-names-action.example.json`](../assets/examples/enum-names-action.example.json)）。
+- **禁止**为了中文展示把固定枚举改成假 Lookup。

 日期时间约定：

@@ -1235,7 +1263,8 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 ### 当前宿主稳定支持（摘要）

 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
- `enum` / `default` / `required` / `sensitive` / `readOnly` / 可选 `revealInForm`
+- `enum` / 可选 **`enumNames`** / `default` / `required` / `sensitive` / `readOnly` / 可选 `revealInForm`
+- 可选 **`column`**：绑列复用 displayName 与 options（静态枚举或 lookup）
 - `display_type` / `format`：`textarea` | **`year`** | **`year_month`** / `month` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`** | **`file`** | **`directory`**
 - 可选 **`pathRoot`**（仅 `file` / `directory`）：相对技能数据根的起始目录；省略默认 `{skill_data}/input`
 - 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`、`multiple`）
@@ -1365,7 +1394,7 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 约定：

 - `boolean` 在宿主中渲染为开关
- `enum` 在宿主中渲染为选择框
+- `enum` 在宿主中渲染为选择框（或短列表分段控件）；**展示文案**优先绑列 options，其次 `enumNames`，再次纯 `enum` 值
 - `type: number` 渲染为数字输入
 - `display_type`/`format: year` 渲染为年份选择；`year_month` / `month` 渲染为年月选择
 - `display_type`/`format: date` 渲染为日期（日）；`datetime_unix_seconds` 渲染为日期时间并按 **Unix 秒**提交
--- a/references/SCHEMA.md
+++ b/references/SCHEMA.md
@@ -621,7 +621,7 @@ readonly = 0

 | 层级 | 值 | 说明 |
 |------|-----|------|
-| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/删除表单 |
+| 表级 `readonly` | `1` | 宿主数据管理只读展示，不提供新增/编辑/导入与直写删除；若技能声明 `replaces: delete` 仍可显示删除并走 CLI |
 | 相关业务字段 `editable` | `0` | 元数据权限只约束宿主 UI，不限制技能代码写库 |

 模板**默认不建**此类审计表。过程看 `jiangchang.log`，进度/终态看任务中心，业务结果看业务表。
@@ -687,6 +687,8 @@ CREATE TABLE demo_items (

 宿主据此渲染选择框；技能侧负责保证 JSON 合法且与物理字段取值一致。

+**与 Action 表单对称：** 数据管理「新增/编辑」读列 `options_json`；Skill Action 弹窗用 `enum` + 可选 **`enumNames`**，或字段绑列（`column` / 属性名对齐）直接复用本列 options。宿主优先序：**绑列 options → enumNames → 纯 enum**。详见 [`ACTIONS.md`](ACTIONS.md)「静态枚举 label」。固定小枚举**不要**改成 Lookup。
+
 ### 2）跨表引用 lookup（对象，用于关联 id 字段）

 当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）。这是**展示与表单选择**契约，**不是** SQLite 外键。