docs: data-management column lookup via options_json

CHANGELOG.md

@@ -9,6 +9,17 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.63
+
+- 数据管理支持字段级 lookup：`options_json` 可声明同库关联表（`ref_table` / `value_column` / `label_column`），宿主新建/编辑时渲染下拉
+- 更新 SCHEMA.md 与元数据校验，兼容静态枚举数组与 lookup 对象两种形态
+
+## 1.0.62
+
+- Skill Action 新增 `interaction` / `interactionByPlacement`：声明数据管理点击是直通、轻确认还是参数表单（与 `executionProfile` 正交）
+- 明确 `confirmation` 只负责风险文案；cron 触发与 agent 忽略 `interaction`
+- 补充 ACTIONS.md 示例（打开文件位置 = direct，打开浏览器 = confirm）
+
 ## 1.0.61
 
 - 桌面 RPA 标准反哺：明确 Name≠Value、主窗最大化与禁止误 `SW_RESTORE`、同名叶子须绑父容器

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.61
+version: 1.0.63
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:

assets/schemas/skill-actions.schema.json

@@ -156,6 +156,24 @@
           "enum": ["sync", "async"],
           "description": "sync=调用方等待结构化结果（不建 Job）；async=宿主建后台 Job 并进任务中心。必须显式写出；长耗时建议 async，但不限制 placements。"
         },
+        "interaction": {
+          "type": "string",
+          "enum": ["auto", "direct", "confirm", "form"],
+          "description": "数据管理等可点击入口的交互方式（与 executionProfile 正交）。direct=一点即跑；confirm=轻量确认（文案用 confirmation.message）；form=参数表单；auto/省略=宿主按 inputSchema+confirmation 推断。cron 触发与 agent 忽略本字段。"
+        },
+        "interactionByPlacement": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "toolbar": { "type": "string", "enum": ["direct", "confirm", "form"] },
+            "row": { "type": "string", "enum": ["direct", "confirm", "form"] },
+            "batch": { "type": "string", "enum": ["direct", "confirm", "form"] },
+            "cron": { "type": "string", "enum": ["direct", "confirm", "form"] },
+            "agent": { "type": "string", "enum": ["direct", "confirm", "form"] },
+            "skill-detail": { "type": "string", "enum": ["direct", "confirm", "form"] }
+          },
+          "description": "按 placement 覆盖 interaction（只能写 concrete 模式，不能写 auto）。常用于同一 Action 在 row 直通、toolbar 仍要表单。"
+        },
         "bind": { "$ref": "#/$defs/bind" }
       },
       "if": {

references/ACTIONS.md

@@ -80,9 +80,10 @@ Action 是**可选能力**：
 
 | 字段 / 层 | 只决定什么 | 不决定什么 |
 |-----------|------------|------------|
-| **`placements`** | Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail） | 不决定 sync/async |
+| **`placements`** | Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail） | 不决定 sync/async，不决定点了是否弹窗 |
 | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
-| **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口 |
+| **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
+| **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
 | **`entrypoint`** | 实际执行哪个 CLI 命令与参数 | 不写业务逻辑 |
 | **domain service** | **真正完成什么业务** | 不感知 toolbar / cron / agent 来源 |
 
@@ -93,13 +94,15 @@ Action 是**可选能力**：
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions` |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`bind`** |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`** |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron` |
 | **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`（行内/批量预填，见下节） |
 | inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly` |
-| confirmation | `{ "message": "..." }` |
+| confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
 | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
+| **interaction** | `"auto"` \| `"direct"` \| `"confirm"` \| `"form"`（可选；省略≈`auto`） |
+| **interactionByPlacement** | 可选；按 placement 覆盖为 `direct`/`confirm`/`form`（不可写 `auto`） |
 
 ## `bind.tables`（表级绑定）
 
@@ -122,6 +125,79 @@ Action 是**可选能力**：
 - **`inputMapping`（可选）**：把行/勾选映射到 `inputSchema` 字段，例如 `"leadId": "$row.$pk"`、`"ids": "$selection.ids"`。适合 `row` / `batch`。宿主仍会提交这些字段；可用 `inputSchema.properties.*.readOnly: true` 在表单中只读展示。
 - `concurrency` / `locks` 仍未稳定，**不要**写入新技能 manifest。
 
+## `interaction`（点击交互方式）
+
+与 `executionProfile` **正交**：一个 Action 可以是 `async` + `direct`（一点就进任务中心），也可以是 `sync` + `form`（填参后当场返回）。
+
+| 值 | 数据管理体验 | 典型场景 |
+|----|--------------|----------|
+| `direct` | **一点即跑**，无弹窗 | 打开文件位置、无参只读、行内主键已映射 |
+| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`） | 打开浏览器、有副作用但无可编辑入参 |
+| `form` | 完整参数表单（现状默认路径） | 导入、查询条件、需用户改写的字段 |
+| `auto` / 省略 | 宿主推断：有**可编辑**参数 → `form`；仅有 `confirmation` → `confirm`；否则 → `direct` | 旧技能兼容；新技能建议显式写出 |
+
+```json
+{
+  "id": "reveal-profile",
+  "label": "打开文件位置",
+  "description": "在资源管理器中打开 Profile 目录。",
+  "placements": ["row"],
+  "executionProfile": "sync",
+  "interaction": "direct",
+  "bind": {
+    "tables": ["accounts"],
+    "inputMapping": { "accountId": "$row.$pk" }
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["accountId"],
+    "properties": {
+      "accountId": { "type": "number", "title": "账号 ID", "readOnly": true }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "account",
+    "args": ["reveal-profile", "{{accountId}}"]
+  }
+}
+```
+
+```json
+{
+  "id": "open-browser",
+  "label": "打开浏览器",
+  "placements": ["row"],
+  "executionProfile": "async",
+  "interaction": "confirm",
+  "confirmation": { "message": "将用该账号 Profile 打开浏览器，仅供查看。" },
+  "bind": {
+    "tables": ["accounts"],
+    "inputMapping": { "accountId": "$row.$pk" }
+  },
+  "inputSchema": {
+    "type": "object",
+    "required": ["accountId"],
+    "properties": {
+      "accountId": { "type": "number", "readOnly": true }
+    }
+  },
+  "entrypoint": {
+    "type": "cli",
+    "command": "account",
+    "args": ["open", "{{accountId}}"]
+  }
+}
+```
+
+可选 `interactionByPlacement`：同一 Action 在不同入口用不同交互（例如 `row: "direct"`、`toolbar: "form"`）。值只能是 `direct`/`confirm`/`form`，不能写 `auto`。
+
+**边界：**
+
+- **cron 配置**：仍展示可编辑参数；`confirmation.message` 可作为配置页风险提示（由宿主决定）。
+- **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
+- 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。
+
 默认模板 `actions.json` 仅含 `health` / `version` / `config-path`，不放在 toolbar/row/batch，故无需 `bind` 示例污染默认 manifest。业务示例：
 
 ```json

references/SCHEMA.md

@@ -354,7 +354,11 @@ CREATE TABLE demo_items (
 
 ## 枚举字段 options_json
 
-`options_json` 为 JSON 数组，每项包含 `value` 与 `label`：
+`options_json` 支持两种形态：
+
+### 1）静态枚举（数组）
+
+每项包含 `value` 与 `label`：
 
 ```json
 [
@@ -366,6 +370,31 @@ CREATE TABLE demo_items (
 
 宿主据此渲染选择框；技能侧负责保证 JSON 合法且与物理字段取值一致。
 
+### 2）表关联 lookup（对象，推荐用于外键式字段）
+
+当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）：
+
+```json
+{
+  "ref_table": "platforms",
+  "value_column": "platform_key",
+  "label_column": "display_name",
+  "filter_column": "enabled",
+  "filter_value": 1
+}
+```
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `ref_table` | 是 | 同库被引用表名（snake_case 标识符） |
+| `value_column` | 是 | 写入当前字段的值列 |
+| `label_column` | 是 | 下拉展示名列 |
+| `filter_column` / `filter_value` | 否 | 等值过滤（如只列出 `enabled=1`） |
+
+宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 下拉选项；**物理列仍存标量**（如 `platform_key` 文本、`account_id` 整数），不做嵌套子表。
+
+示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表。
+
 ## 幂等初始化标准
 
 - `_jiangchang_tables` 和 `_jiangchang_columns` 必须通过 upsert 初始化

scripts/db/display_metadata_validator.py

@@ -196,7 +196,7 @@ def _default_uses_unixepoch(default_value: object) -> bool:
 
 
 def validate_options_json(options_json: str | None) -> tuple[list[str], list[str]]:
-    """校验枚举 options_json 可被解析为 [{value, label}, ...] 结构。"""
+    """校验 options_json：静态枚举数组，或 lookup 对象。"""
     errors: list[str] = []
     warnings: list[str] = []
     if options_json is None or str(options_json).strip() == "":
@@ -206,8 +206,24 @@ def validate_options_json(options_json: str | None) -> tuple[list[str], list[str
     except json.JSONDecodeError as exc:
         errors.append(f"options_json 不是合法 JSON：{exc}")
         return errors, warnings
+
+    if isinstance(parsed, dict):
+        for key in ("ref_table", "value_column", "label_column"):
+            if not str(parsed.get(key) or "").strip():
+                errors.append(f"options_json lookup 必须包含非空 {key}")
+        ident = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+        for key in ("ref_table", "value_column", "label_column", "filter_column"):
+            raw = parsed.get(key)
+            if raw is None or raw == "":
+                continue
+            if not ident.match(str(raw)):
+                errors.append(f"options_json.{key} 必须是安全标识符，当前为 {raw!r}")
+        if parsed.get("filter_column") not in (None, "") and "filter_value" not in parsed:
+            warnings.append("options_json lookup 声明了 filter_column 但未提供 filter_value")
+        return errors, warnings
+
     if not isinstance(parsed, list):
-        errors.append("options_json 必须是 JSON 数组")
+        errors.append("options_json 必须是 JSON 数组（静态枚举）或对象（lookup）")
         return errors, warnings
     for index, item in enumerate(parsed):
         if not isinstance(item, dict):

tests/test_actions_manifest.py

@@ -216,6 +216,25 @@ class TestActionsManifest(unittest.TestCase):
         self.assertEqual(bind_def.get("required"), ["tables"])
         self.assertIs(bind_def.get("additionalProperties"), False)
 
+    def test_schema_defines_interaction_fields(self) -> None:
+        schema = _load_actions_schema()
+        action_def = schema["$defs"]["action"]
+        props = action_def["properties"]
+        self.assertIn("interaction", props)
+        self.assertEqual(
+            set(props["interaction"].get("enum") or []),
+            {"auto", "direct", "confirm", "form"},
+        )
+        self.assertIn("interactionByPlacement", props)
+        by_placement = props["interactionByPlacement"]
+        self.assertIs(by_placement.get("additionalProperties"), False)
+        for key in ("toolbar", "row", "batch", "cron", "agent", "skill-detail"):
+            self.assertIn(key, by_placement.get("properties") or {})
+            self.assertEqual(
+                set((by_placement["properties"][key].get("enum") or [])),
+                {"direct", "confirm", "form"},
+            )
+
     def test_manifest_validates_against_json_schema(self) -> None:
         try:
             import jsonschema
@@ -469,6 +488,8 @@ class TestActionsManifest(unittest.TestCase):
             "additionalProperties",
             "placements",
             "executionProfile",
+            "interaction",
+            "confirmation",
         ):
             self.assertIn(marker, text, msg=f"ACTIONS.md missing {marker!r}")
         for forbidden in (