docs: precipitate Action/CRUD Lookup contract for skill authors

references/ACTIONS.md

@@ -176,11 +176,12 @@ Action 是**可选能力**：
 - `update` / `delete` 可用 `inputMapping`（`$row.$pk`、`$selection.ids`）预填主键。
 - 宿主导入仍直写：有 `replaces:create` 的表慎用宿主导入，或另做 import Action。
 - 整表 `_jiangchang_tables.readonly=1` 时仍隐藏写按钮（优先于 `replaces`）。
-- **列元数据复用（lookup）**：create/update 抽屉可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
+- **列元数据复用（lookup）**：Action 表单（含 toolbar/batch 弹窗与 create/update 抽屉）可将 `inputSchema` 字段对齐业务列，复用中文名与 lookup 下拉：
   - 优先让属性名 = 物理列名（如 `platform_key`）；
   - 或 `bind.columnMapping`：`{ "platform": "platform_key" }`；
   - 或字段上写 `"column": "platform_key"`。
-  - **不要**在 actions.json 里写死会过期的全量平台 `enum`。
+  - 当前表没有对应列时，用字段内联 `lookup`（见下文「跨表引用：Lookup」）。
+  - **不要**在 actions.json 里写死会过期的全量平台 `enum`，也**不要**让用户手填内部编号。
 
 ## `interaction`（点击交互方式）
 
@@ -583,6 +584,57 @@ HINT: <next step>
 - [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）
 
 ## inputSchema 与参数表单
+
+### 跨表引用：Lookup（宿主已支持；勿让用户填编号）
+
+当 Action 参数要引用**同库另一张业务表**的一行（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。
+
+| 场景 | 怎么配 | 说明 |
+|------|--------|------|
+| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名 | toolbar/batch 弹窗与 create/update 抽屉都会复用该列已解析的选项 |
+| 当前表没有该列（如在「潜客」表上选「话术模板」） | `display_type: "lookup"` + 字段内联 `lookup` 对象 | 打开表单时宿主按当前技能库解析选项 |
+
+内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「表关联 lookup」）：
+
+```json
+{
+  "templateId": {
+    "type": "number",
+    "title": "话术模板",
+    "description": "仅在正文留空时生效；选 -- 表示自动挑选。",
+    "display_type": "lookup",
+    "lookup": {
+      "ref_table": "message_templates",
+      "value_column": "id",
+      "label_column": "name",
+      "extra_column": "channel",
+      "filter_column": "is_active",
+      "filter_value": 1
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `ref_table` | 是 | 同库被引用表 |
+| `value_column` | 是 | 提交给 CLI 的值（编号 / 外键） |
+| `label_column` | 是 | 主文案列 |
+| `extra_column` | 否 | 第三展示列（任意列名，不限「备注」） |
+| `filter_column` / `filter_value` | 否 | 等值过滤 |
+
+**下拉展示（宿主统一，技能只配列）：** `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
+
+**可选「自动」：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。
+
+**反模式（勿做）：**
+
+- 标题写成「某某编号」，说明里教用户去左侧表抄 id
+- 用静态 `enum` 罗列会增长/变更的业务行（会过期）
+- 在技能里自己拼假 label 列代替宿主统一格式（难维护）
+
+形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)。
+
 ### 表单字段类型对照（须与 CRUD 对称）
 
 Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件语义**。CRUD 侧配置见 [`SCHEMA.md`](SCHEMA.md)「表单与展示：稳定字段类型」；本表只写 Action 怎么配。
@@ -595,7 +647,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
 | 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉 | 绑列 lookup（`column` / `columnMapping`） | `display_type: lookup` |
+| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`，或绑列 `column` / `columnMapping` | `display_type: lookup` + `options_json` 对象 |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 日期（日） | `display_type` 或 `format`: `date` | `display_type: date` → 存 `YYYY-MM-DD` |
 | 日期时间 | `display_type` 或 `format`: `datetime_unix_seconds` | 同左；**存/传 Unix 秒** |
@@ -617,9 +669,11 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 
 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
 - `enum` / `default` / `required` / `sensitive` / `readOnly`
-- `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email`
+- `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`**
+- 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`）
 - 属性级 `description`（表单标签下方灰字说明）
 - 简单模板替换（`{{fieldName}}`）
+- 可选空数字字段提交时由宿主省略，避免 `""` 触发 number 校验失败
 
 **与数据管理「新增 / 编辑」表单的分工（勿混用配置入口）：**
 

references/SCHEMA.md

@@ -518,6 +518,7 @@ CREATE TABLE demo_items (
   "ref_table": "platforms",
   "value_column": "platform_key",
   "label_column": "display_name",
+  "extra_column": "category",
   "filter_column": "enabled",
   "filter_value": 1
 }
@@ -526,13 +527,23 @@ CREATE TABLE demo_items (
 | 字段 | 必填 | 说明 |
 |---|---|---|
 | `ref_table` | 是 | 同库被引用表名（snake_case 标识符） |
-| `value_column` | 是 | 写入当前字段的值列 |
-| `label_column` | 是 | 下拉展示名列 |
+| `value_column` | 是 | 写入当前字段的值列（编号 / 外键） |
+| `label_column` | 是 | 下拉主文案列（名称） |
+| `extra_column` | 否 | 第三展示列（不必叫「备注」）；有值时拼进括号 |
 | `filter_column` / `filter_value` | 否 | 等值过滤（如只列出 `enabled=1`） |
 
 宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 下拉选项；**物理列仍存标量**（如 `platform_key` 文本、`account_id` 整数），不做嵌套子表。
 
-示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表。
+**统一展示文案（宿主固定一种，技能只配列）：**
+
+- 默认：`{value} · {label}`，例如 `2 · 通用私信-留资`、`douyin · 抖音`
+- 配置了 `extra_column` 且该行有非空值：`{value} · {label}（{extra}）`
+- 未配置 `extra_column`、或额外列为空：不加 `（）`
+- `label` 为空或与 `value` 相同时：只显示 `value`（可再带额外括号）
+
+Action 弹窗内联 Lookup 与上表 **同构**（字段名一致），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+
+示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`。
 
 ## 幂等初始化标准