Docs: precipitate Action Lookup skill_cli contract (v1.0.119)

2026-09-28 11:56:12 +08:00
parent bf3bb9cd10
commit c49fcba157
12 changed files with 264 additions and 24 deletions
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -910,14 +910,37 @@ const data = await jiangchang.call("方法名", { date: "2026-09-19" });

 ### 跨表引用：Lookup（宿主已支持；勿让用户填编号）

-当 Action 参数要引用**同库另一张业务表**的一行（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。
+当 Action 参数要引用**一行业务实体**（话术模板、平台、账号等）时，必须用 Lookup 下拉，**禁止**做成「请填写编号」的数字框（用户记不住内部 id，体验差）。

-| 场景 | 怎么配 | 说明 |
-|------|--------|------|
-| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名 | toolbar/batch 弹窗与 create/update 抽屉都会复用该列已解析的选项 |
-| 当前表没有该列（如在「潜客」表上选「话术模板」） | `display_type: "lookup"` + 字段内联 `lookup` 对象 | 打开表单时宿主按当前技能库解析选项 |
+#### 两种 Lookup 入口（勿混）

-内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「跨表引用 lookup」）：
+| 种类 | 声明位置 | 何时解析 | 允许的数据源 |
+|------|----------|----------|--------------|
+| **列 Lookup** | `_jiangchang_columns.display_type = lookup` + `options_json` 对象 | 拉表 schema 时 | **仅** `local_sql`（同库表） |
+| **Action Lookup** | `inputSchema.properties.*.lookup`（推荐同时 `display_type: lookup`） | **打开动作表单** / 字段因 `visibleWhen` 变为可见时 | `local_sql` / **`skill_cli`** / `external_api`（预留） |
+
+固定小枚举仍用 `options_json` **数组**或 Action `enum`，**不走** Lookup 解析器。
+
+#### Action Lookup 三种 source（匠厂宿主已统一）
+
+| `source` | 何时用 | 核心字段 | 推断（可省略显式 `source`） |
+|----------|--------|----------|------------------------------|
+| `local_sql` | 选项在**本技能库**另一张表 | `ref_table` + `value_column` + `label_column` | 有 `ref_table` |
+| `skill_cli` | 选项在**兄弟/依赖技能**（如 account-manager 账号列表） | `skill` + `command`；可选 `args` / `items_path` / `value_column` / `label_column` | 有 `skill` / `skill_slug` |
+| `external_api` | 第三方 HTTP（预留） | `url`（或 `endpoint`） | 有 `url` / `endpoint` |
+
+**选型：**
+
+| 场景 | 怎么配 |
+|------|--------|
+| 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名（复用列上已解析的 **local_sql** 选项） |
+| 同库另一张表、当前表没有对应列 | Action 内联 `lookup` → `local_sql`（可只写 `ref_table`…） |
+| 跨技能列表（账号、批次、其它技能业务行） | Action 内联 `lookup` → **`skill_cli`**（`skill` + `command`） |
+| 固定三五个状态 | `enum` / 列 `options_json` 数组，**不要** Lookup |
+
+**反模式（跨技能）：** 在本技能再造一张「账号选项缓存表」再 `local_sql`——选项会过期，定时任务等入口也容易空下拉。应直接 `skill_cli` 调依赖技能。
+
+#### `local_sql`（同库；与列 `options_json` 对象同构）

 ```json
 {
@@ -954,14 +977,56 @@ const data = await jiangchang.call("方法名", { date: "2026-09-19" });

 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `ref_table` | 是 | 同库被引用表 |
+| `ref_table` | 是（local_sql） | 同库被引用表 |
 | `value_column` | 是 | 提交给 CLI 的值（业务 id / 编号） |
 | `label_column` | 是 | 主文案列 |
 | `extra_column` | 否 | 第三展示列（任意列名，不限「备注」） |
 | `filter_column` / `filter_value` | 否 | 等值过滤 |
 | `multiple` | 否 | `true` = 多选；省略/`false` = 单选（默认） |

-**下拉/选项展示（宿主统一，技能只配列）：** 单选为 `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
+列 Lookup 字段表与加载时机见 [`SCHEMA.md`](SCHEMA.md)「跨表引用 lookup」（**仅 local_sql**）。
+
+#### `skill_cli`（兄弟/依赖技能 CLI）
+
+打开表单时，宿主对声明的技能执行一次 **sync** CLI，从 **stdout JSON** 抽出选项列表（默认路径 `items`）。
+
+```json
+{
+  "accountId": {
+    "type": "string",
+    "title": "发布账号",
+    "description": "不选则由系统自动分配。",
+    "display_type": "lookup",
+    "lookup": {
+      "source": "skill_cli",
+      "skill": "account-manager",
+      "command": "list-json",
+      "args": ["toutiao"],
+      "value_column": "id",
+      "label_column": "account_label"
+    }
+  }
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `skill` / `skill_slug` | 是（二选一） | 兄弟技能 slug |
+| `command` / `cli_command` | 是（二选一） | CLI 子命令（argv 第一段） |
+| `args` | 否 | 追加参数；数组或逗号串 |
+| `value_column` | 否 | 默认 `id` |
+| `label_column` | 否 | 默认 `display_label` |
+| `extra_column` | 否 | 第三展示列 |
+| `items_path` | 否 | JSON 内数组点路径，默认 `items`；若 stdout 本身就是数组可省略 |
+| `multiple` | 否 | 同 local_sql |
+
+**依赖技能侧约定：** 该命令须成功退出并打印可解析 JSON；宿主接受**顶层数组**，或对象内由 `items_path`（默认 `items`）指向的数组。元素须含 value/label 列。具体子命令与字段名以依赖技能文档为准（上例对标 account-manager 遗留 `list-json <platform>`，字段为 `id` / `account_label`；其它技能请核对 stdout）。
+
+**与运行时分流：** 表单选账号用 `skill_cli` Lookup；真正开浏览器 / 占租约仍走本技能 `account_client`（见 [`development/ACCOUNT_MANAGER.md`](../development/ACCOUNT_MANAGER.md)），二者不要混成「表单打开就 pick-web」。
+
+#### 展示、多选与可选空
+
+**下拉/选项展示（宿主统一，技能只配列）：** 单选为 `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。列表/详情单元格优先 `listLabel`（不带 id 前缀）。例：`2 · 通用私信-留资`。

 **多选存值与模板：** Action / CRUD 存 **`TEXT` 逗号分隔 id**（如 `1,2,5`）；`{{engineIds}}` 原样替换进 CLI。多选字段在 `inputSchema` 里用 `type: "string"`（逗号串），不要用尚未稳定的 JSON array 当业务控件。

@@ -969,14 +1034,18 @@ const data = await jiangchang.call("方法名", { date: "2026-09-19" });

 **可选「自动」（单选常见）：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。

+**解析失败：** 单字段 Lookup 失败时该字段选项为空，表单仍可开（可留空提交的场景不受阻）。
+
 **反模式（勿做）：**

 - 标题写成「某某编号」，说明里教用户去左侧表抄 id
 - 用静态 `enum` 罗列会增长/变更的业务行（会过期）
 - 在技能里自己拼假 label 列代替宿主统一格式（难维护）
 - 另造 `lookup_multi` / 第二套 display_type（应只加 `multiple: true`）
+- 为跨技能列表在本库维护镜像缓存表再 `local_sql`（应用 `skill_cli`）
+- 在列 `options_json` 上声明 `skill_cli`（列 Lookup **只**支持同库）

-形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)。
+形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)、[`assets/examples/lookup-skill-cli.action.example.json`](../assets/examples/lookup-skill-cli.action.example.json)。

 ### 表单字段类型对照（须与 CRUD 对称）

@@ -990,7 +1059,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
 | 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（可选 `multiple`），或绑列 | 同左；多选存 `TEXT` 逗号分隔 id |
+| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（`local_sql` / `skill_cli` / `external_api`；可选 `multiple`），或绑列 | 列侧仅同库 `local_sql`；多选存 `TEXT` 逗号分隔 id |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 年份 | `display_type` 或 `format`: `year` | `display_type: year` → 存 `YYYY` |
 | 年月 | `display_type` 或 `format`: `year_month`（别名 `month`） | `display_type: year_month` → 存 `YYYY-MM` |
--- a/references/SCHEMA.md
+++ b/references/SCHEMA.md
@@ -728,6 +728,8 @@ CREATE TABLE demo_items (

 宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 选项列表。

+> **列 Lookup 仅支持同库 `local_sql`。** Action 表单若要从兄弟技能拉选项（如 account-manager 账号列表），须在 `actions.json` 的 `inputSchema.lookup` 使用 **`skill_cli`**，见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。不要在列 `options_json` 上声明 `skill` / `command`。
+
 **存库约定：**

 | 模式 | 物理列建议 | 存什么 |