docs(html): 沉淀数据管理 iframe 预览布局契约

Co-authored-by: Cursor <cursoragent@cursor.com>

CHANGELOG.md

@@ -9,6 +9,34 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.97
+
+- 沉淀数据管理 HTML 预览**布局契约**：`references/ACTIONS.md` 新增「宿主预览布局」（流体铺满 iframe、禁横向滚动、表格断行等）
+- 升级 `assets/html/example-report.html` 为通用布局基线；`test_html_page_service` 守护不退化
+- `DEVELOPMENT.md` / `CHECKLIST`（S0-12、A6-10）/ `TESTING.md` 交叉引用
+
+## 1.0.96
+
+- 在 `references/ACTIONS.md` 沉淀数据管理技能按钮中文名（`label`）参考表：同类通用动作用同一动词，不是白名单
+- 打开类改为「打开目录 / 打开浏览器」，一点即开、成功不弹「执行成功」；示例不再使用「打开文件位置」
+- 交活 Checklist A7-7；POLICY_MATRIX 软规则：不扫描 label 关键字
+
+## 1.0.95
+
+- 正式沉淀「业务行生命周期」通用契约（`references/WORK_ITEM_STATUS.md`）：用可操作/进行中/成功·失败·跳过类终态等**角色**约束处理队列，不绑死某一技能的状态名
+- 默认只处理可操作态；开始抢占进行中；结束回写成功或失败（失败带原因）；重做靠人工改回可操作
+- REQUIREMENTS §0.3 状态→角色映射；CHECKLIST S0-11 / A6-7～A6-9；SKILL / ACTIONS / SCHEMA / references 索引交叉引用
+
+## 1.0.94
+
+- 修正 1.0.93 更新日志重复小节
+
+## 1.0.93
+
+- 沉淀 Lookup **多选**契约：同一 `lookup` / `options_json` 对象上加 `multiple: true`（平行扩展单选，不另造 display_type）
+- 多选存 `TEXT` 逗号分隔 id；列表展示映射为多个 label；控件由宿主按选项数量选择（短列表勾选 / 长列表 Chip+下拉）
+- 更新 SCHEMA / ACTIONS / skill-actions.schema / lookup 示例与 options_json 校验
+
 ## 1.0.92
 
 - 沉淀数据管理 `replaces: import`：导入 UI 统一宿主面板，确认后由技能写库

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.92
+version: 1.0.97
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -38,6 +38,7 @@ allowed-tools:
 - **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
 - **`policy`（可选）**：需要按用户/角色控制数据管理按钮或行列时，在 `actions.json` 顶层启用 Data Policy，由技能 `policy` CLI 输出 Snapshot；**未启用 = 与今日一致（L0）**。详见 `references/POLICY.md`。用户/角色数据源（飞书/库/API）属技能内部，宿主不托管。
 - **`cellPresentation`（可选）**：需要数据管理「某格特殊标色/强调」时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；**未启用 = P0 无标色**。用途不限（超时、预警、驳回等）。详见 `references/CELL_PRESENTATION.md`。
+- **业务行生命周期（有处理队列时）**：对某一行做生成/触达/私信等处理时，默认只操作「可操作」角色状态；开始抢占「进行中」；结束回写成功或失败（失败带原因）；重做靠人工改回可操作。状态名由本技能自定。详见 `references/WORK_ITEM_STATUS.md`。
 - **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；文件型特殊报告才另做 `export-*`（落 `output/`）；**HTML 整页报告**写 `html/` 并用固定 Action id `render-html`（见 `references/ACTIONS.md`）。
 - **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
 
@@ -70,8 +71,9 @@ allowed-tools:
 4. **入口按定位表挂载**：复制业务技能后须在 `development/REQUIREMENTS.md` 填写入口定位表（见 `development/PRODUCT_SURFACES.md`）。定位需要数据管理 / 定时 / Agent 结构化调用时，必须提供 `actions.json` 并声明对应 `placements`；定位确认无需任何宿主结构化入口时可不提供。有长任务 / RPA 时**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 Action。
 5. **一个业务能力一个 Action**，用多个 `placements` 挂入口；底层仍是同一 `scripts/main.py` CLI。
 6. 是否进任务中心**只**看该 Action 的 `executionProfile`，与数据管理 / 定时 / Agent 入口无关。
+7. **处理业务行**时遵守状态角色契约（可操作 / 进行中 / 终态）；禁止对已成功/失败/跳过默认重复处理。详见 `references/WORK_ITEM_STATUS.md`。
 
-Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`、按需 `references/POLICY.md`（不要把 `development/` 当 Agent 主读路径）。
+Agent 执行契约细节：`references/CLI.md`、`references/ACTIONS.md`、`references/SCHEMA.md`、按需 `references/POLICY.md` / `references/WORK_ITEM_STATUS.md`（不要把 `development/` 当 Agent 主读路径）。
 
 ## 共享 Python（必读）
 

assets/README.md

@@ -1,7 +1,7 @@
 # assets
 
 - `actions.json`：Skill Action manifest 最小示例（按入口定位表决定是否保留/扩展；见 `development/PRODUCT_SURFACES.md`）。每个 action **必须**显式声明 `executionProfile`（`sync` \| `async`）。默认仅 `health` / `version` / `config-path`，不放 toolbar，故无 `bind` 示例。
-- `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
+- `html/example-report.html`：HTML 报告页最小壳（`{{TITLE}}` / `{{GENERATED_AT}}` / `{{BODY}}`）；含数据管理 iframe 预览布局基线（流体铺满、禁横向滚动）；渲染后须写入数据目录 `html/`，见 `references/ACTIONS.md`「HTML 页面报告」。
 - `examples/`：CLI 成功输出形状示例、以及 `render-html.action.example.json`（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**）。
 

assets/examples/README.md

@@ -4,6 +4,6 @@
 - `skill-policy-snapshot.*.example.json`：Data Policy Snapshot 形状参考（见 `references/POLICY.md`）。
 - `skill-cell-presentation.example.json`：数据管理单元格呈现文档形状参考（见 `references/CELL_PRESENTATION.md`）。
 - `render-html.action.example.json`：HTML 报告「重新生成」Action 形状参考（固定 id `render-html`；见 `references/ACTIONS.md`）。
-- `lookup-action.example.json`：Action 内联 Lookup 下拉形状参考（跨表引用勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
+- `lookup-action.example.json`：Action 内联 Lookup 形状参考（单选 + `multiple: true` 多选并列；跨表引用勿填编号；见 `references/ACTIONS.md`「跨表引用：Lookup」）。
 - `visible-when-action.example.json`：Action 参数字段条件显隐 `visibleWhen` 形状参考（互斥模式联动；见 `references/ACTIONS.md`「字段条件显隐」；≠ Policy L3）。
 - `replaces-create.action.example.json` / `replaces-update.action.example.json` / `replaces-delete.action.example.json` / `replaces-import.action.example.json`：数据管理默认按钮接管（`replaces`）形状参考；**import 时 UI 仍用宿主「导入数据」面板**，确认后调技能写库（见 `references/ACTIONS.md`「`replaces`」）。

assets/examples/lookup-action.example.json

@@ -1,12 +1,12 @@
 {
-  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup 下拉，勿让用户填内部编号。完整契约见 references/ACTIONS.md「跨表引用：Lookup」与 references/SCHEMA.md。",
+  "_comment": "形状参考：Action 参数引用同库另一张表时用 Lookup。单选与多选同一 lookup 对象，多选只加 multiple:true。完整契约见 references/ACTIONS.md「跨表引用：Lookup」与 references/SCHEMA.md。",
   "schemaVersion": 1,
   "skill": "your-skill-slug",
   "actions": [
     {
       "id": "send-with-template",
       "label": "按模板发送（示例）",
-      "description": "演示内联 lookup：从 message_templates 选模板；-- 表示自动挑选。",
+      "description": "演示内联 lookup 单选：从 message_templates 选模板；-- 表示自动挑选。",
       "placements": ["toolbar"],
       "executionProfile": "async",
       "interaction": "form",
@@ -43,6 +43,41 @@
           }
         }
       }
+    },
+    {
+      "id": "probe-with-engines",
+      "label": "按引擎抽检（多选示例）",
+      "description": "演示 lookup.multiple：从 engines 多选，提交为逗号分隔 id。",
+      "placements": ["toolbar"],
+      "executionProfile": "async",
+      "interaction": "form",
+      "bind": {
+        "tables": ["queries"]
+      },
+      "entrypoint": {
+        "type": "cli",
+        "command": "query",
+        "args": ["batch-probe", "--engine-ids", "{{engineIds}}"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "engineIds": {
+            "type": "string",
+            "title": "将使用的引擎",
+            "description": "可多选；提交值为逗号分隔编号，如 1,2。",
+            "display_type": "lookup",
+            "lookup": {
+              "ref_table": "engines",
+              "value_column": "id",
+              "label_column": "display_name",
+              "filter_column": "enabled",
+              "filter_value": 1,
+              "multiple": true
+            }
+          }
+        }
+      }
     }
   ]
 }

assets/html/example-report.html

@@ -11,17 +11,31 @@
       --muted: #64748b;
       --card: #ffffff;
       --line: #e2e8f0;
+      --page-pad-x: clamp(14px, 2.5vw, 24px);
+      --page-pad-y: clamp(12px, 2vw, 20px);
     }
     * { box-sizing: border-box; }
-    html { overflow-y: auto; }
-    body {
+    html {
+      width: 100%;
+      height: 100%;
       margin: 0;
+      overflow-x: hidden;
+      overflow-y: auto;
+    }
+    body {
+      width: 100%;
+      min-height: 100%;
+      margin: 0;
+      overflow-x: hidden;
       font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
       background: var(--bg);
       color: var(--ink);
+      line-height: 1.5;
     }
     header {
-      padding: 20px 24px 8px;
+      padding: var(--page-pad-y) var(--page-pad-x) 8px;
+      background: var(--card);
+      border-bottom: 1px solid var(--line);
     }
     header h1 {
       margin: 0 0 6px;
@@ -34,7 +48,23 @@
       font-size: 13px;
     }
     main {
-      padding: 8px 24px 28px;
+      width: 100%;
+      min-width: 0;
+      padding: var(--page-pad-y) var(--page-pad-x) 28px;
+    }
+    .section {
+      margin-bottom: 18px;
+    }
+    .section h2 {
+      margin: 0 0 8px;
+      font-size: 13px;
+      font-weight: 650;
+      color: var(--muted);
+    }
+    .meta {
+      margin: 0 0 10px;
+      color: var(--muted);
+      font-size: 12px;
     }
     .card {
       background: var(--card);
@@ -44,6 +74,35 @@
       line-height: 1.6;
       font-size: 14px;
     }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      table-layout: fixed;
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      overflow: hidden;
+      font-size: 13px;
+    }
+    th, td {
+      padding: 8px 10px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+      word-break: break-word;
+      overflow-wrap: anywhere;
+    }
+    th {
+      background: #f8fafc;
+      font-weight: 600;
+      color: var(--muted);
+      font-size: 12px;
+    }
+    tr:last-child td { border-bottom: none; }
+    /*
+      宿主数据管理在 iframe 内预览本页：应横向铺满可用宽度，仅纵向滚动。
+      复杂看板可在 {{BODY}} 内使用 .section / table；布局底线见 references/ACTIONS.md「宿主预览布局」。
+    */
   </style>
 </head>
 <body>

assets/schemas/skill-actions.schema.json

@@ -214,9 +214,13 @@
         "filter_value": {
           "type": ["string", "number", "boolean", "null"],
           "description": "可选。与 filter_column 配对的等值"
+        },
+        "multiple": {
+          "type": "boolean",
+          "description": "可选。true=多选 Lookup（存/提交 TEXT 逗号分隔 id）；省略或 false=单选（默认）。与 CRUD options_json lookup 同构。"
         }
       },
-      "description": "同库 FK 式 Lookup。展示：value · label；有 extra 时 value · label（extra）。宿主亦接受 camelCase 键名。"
+      "description": "同库 FK 式 Lookup。展示：value · label；有 extra 时 value · label（extra）。multiple 时多选。宿主亦接受 camelCase 键名。"
     },
     "inputSchema": {
       "type": "object",

development/CHECKLIST.md

@@ -59,6 +59,8 @@ checklist_version: 1.0
 - [ ] S0-8 是否包含提交、付款、删除、审批、发布、发送等不可逆副作用：是 / 否
 - [ ] S0-9 **入口定位表**（见 `PRODUCT_SURFACES.md` / `REQUIREMENTS` §0.1）：已填写 / 未填写
 - [ ] S0-10 本技能宣称的主用户路径涉及：对话 / 数据管理（执行或仅展示） / 定时（可多选；与定位表一致）
+- [ ] S0-11 **业务行生命周期**（见 `references/WORK_ITEM_STATUS.md` / `REQUIREMENTS` §0.3）：有处理队列且已声明状态→角色映射 / 不适用
+- [ ] S0-12 **HTML 页面报告**（见 `references/ACTIONS.md`「HTML 页面报告」）：有侧栏可预览的 `html/*.html` + `render-html` / 不适用
 
 ---
 
@@ -130,6 +132,10 @@ checklist_version: 1.0
 - [ ] A6-4 **P1** 「零结果成功」与「失败」可区分
 - [ ] A6-5 **P1** 若产出文件：落在约定数据位置且可找到，不丢在不明临时路径
 - [ ] A6-6 **P0** 有业务表时：`sqlite_master` 中业务表 DDL **不得**含 SQLite `FOREIGN KEY` / `REFERENCES`；跨表只存业务 id，关联与级联在 repository/service；界面名称用 `lookup`（见 `references/SCHEMA.md`）；可跑 `validate_template_database` / `init-db` 后自检
+- [ ] A6-7 **P0** 有「处理业务行」类 Action 时（见 `WORK_ITEM_STATUS.md`）：默认只处理**可操作**角色状态；成功/失败/跳过/进行中再点处理应拒绝或跳过且不产生重复副作用；重做须人工改回可操作。无处理队列 → **N/A**
+- [ ] A6-8 **P0** 同上适用时：开始处理后业务表进入**进行中**；成功回写成功类终态；失败回写失败类终态且**失败原因**可读（任务成功但业务行仍停在可操作/进行中 → **FAIL**）
+- [ ] A6-9 **P1** 同上适用时：`REQUIREMENTS` §0.3（或等价）已填写本技能状态→角色映射；处理类 Action 确认文案写清仅可操作态
+- [ ] A6-10 **P1** 有 HTML 侧栏预览时（S0-12）：预览区横向铺满、无横向滚动条；重新生成后内容与页头时间更新；布局符合 `references/ACTIONS.md`「宿主预览布局」。无 HTML 报告 → **N/A**
 
 ---
 
@@ -141,6 +147,7 @@ checklist_version: 1.0
 - [ ] A7-4 **P1** 关键步骤有据可查（能对应到开始/关键节点/结束；RPA 宜有多个 `stage=`）
 - [ ] A7-5 **P1** 若宣称支持录屏或截图存证：打开开关后关键步骤或失败能留下可查看产物；宣称支持却完全无产物 → **FAIL**
 - [ ] A7-6 **P2** 用户可见文案偏业务语言，而非大段开发黑话
+- [ ] A7-7 **P2** 数据管理技能按钮（toolbar / row / batch）中文名对照 `references/ACTIONS.md`「Action 按钮中文名」；不与宿主「查看 / 编辑 / 删除」抢名；打开类成功不弹成功条。行业专有按钮名可自创
 
 ---
 

development/DEVELOPMENT.md

@@ -590,7 +590,7 @@ cmd_stats()                 # 只读 sync：JSON，无 job_context
 - 批量数量用 **`pickCount` / `--pick N` 参数**（任意正整数），不写死条数。
 - **顺序执行、不并发**同一浏览器 Profile / account lease。
 - **同步数据**与**宿主表导出**职责分离：同步不写 CSV/Excel；表导出交给数据管理。
-- **HTML 页面报告**（可选）：需要侧栏预览整页时，写入 `html/` + Action `render-html`；契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」、[`DATA_PATHS.md`](DATA_PATHS.md)；薄写入 helper 见 `scripts/service/html_page_service.py`。
+- **HTML 页面报告**（可选）：需要侧栏预览整页时，写入 `html/` + Action `render-html`；契约见 [`../references/ACTIONS.md`](../references/ACTIONS.md)「HTML 页面报告」（含**宿主预览布局**底线）、[`DATA_PATHS.md`](DATA_PATHS.md)；薄写入 helper 见 `scripts/service/html_page_service.py`。建议从 `assets/html/example-report.html` 复制壳；`{{BODY}}` 内数据须转义；样式升级后提醒用户重新生成。
 - 详情见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)；契约样例见 `tests/samples/test_sync_contract.py.sample`、`tests/samples/test_action_core_contract.py.sample`。
 
 ### 队列 + pick（可选）

development/POLICY_MATRIX.md

@@ -67,6 +67,7 @@
 | `SKILL.md` / `constants.SKILL_SLUG` 一致性 | development/DEVELOPMENT.md §16 | 已有 `tests/test_skill_metadata.py` |
 | platform_kit_min_version >= 1.2.11 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` |
 | 宿主按 `bind.tables` 过滤 toolbar 按钮 | references/ACTIONS.md | 待宿主升级后完整生效；模板侧已强制显式绑定 |
+| 数据管理技能按钮中文名（`label`）对照 ACTIONS.md 建议表；打开类成功静默 | references/ACTIONS.md「Action 按钮中文名」 | 参考非白名单；行业词允许自创；勿做 label 关键字扫描 |
 | Data Policy 未启用（L0）时宿主不得拉 Snapshot / 不得改按钮与行列行为 | references/POLICY.md | soft；宿主实现契约 |
 | Data Policy 启用后 fail-closed（禁止回退 L0 全开）；写路径 domain 必须再鉴权 | references/POLICY.md §6–§7 | soft；`POLICY-SKILL-AUTHZ-*` 硬门禁可后续加 |
 | `actions.mode` 仅 allowlist/open；`hostCapabilities` 省略=不限制；scope `valueFrom` 仅 `actor.userId` | references/POLICY.md §0.1 | soft；Schema 已约束 |

development/REQUIREMENTS.md

@@ -85,6 +85,20 @@
 - 需要保存哪些日志、截图、视频和业务结果：
 - 定位失败时如何保存 DOM/UIA/XML、候选数量和环境版本：
 
+## 0.3 业务行生命周期（有「处理某一行」类能力时必填）
+
+若本技能存在对业务表某一行做生成、触达、私信、发布等**有副作用**的处理，须遵守 [`../references/WORK_ITEM_STATUS.md`](../references/WORK_ITEM_STATUS.md)，并在此声明**本技能状态 → 角色**映射（状态名自定，角色固定）：
+
+| 角色 | 本技能状态值（可多个） | 说明 |
+|------|------------------------|------|
+| 可操作（operable） | （例）新建 / 待生成 / … | 默认唯一可被处理 Action 捞起 |
+| 进行中（in_progress） | （例）生成中 / 触达中 / … | 抢占后、结束前 |
+| 成功类终态 | （例）已生成 / 已私信 / … | 默认不可再处理 |
+| 失败类终态 | （例）失败 / 触达失败 / … | 默认不可再处理；失败原因字段： |
+| 跳过类终态 | （例）已跳过 / … | 默认不可再处理 |
+
+无此类处理队列时整节写「不适用」即可。
+
 ## 1. 文档目标
 
 说明这份需求文档的作用，以及它解决什么问题。

development/SKILL_ACTION_RUNTIME.md

@@ -9,7 +9,7 @@
 | 文档 | 职责 |
 |------|------|
 | 本文 | sync/async、任务中心、Agent 禁令、单内核编排、队列 pick、同步 vs 导出 |
-| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen` |
+| [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、`bind.tables`、inputSchema、跨表 Lookup、字段条件显隐 `visibleWhen`、**按钮中文名 `label` 参考** |
 | [`LOGGING.md`](LOGGING.md) | `job_context` / `emit` / `finish` / Run Journal |
 | [`DATA_PATHS.md`](DATA_PATHS.md) | 下载/导入等落盘路径 |
 

development/TESTING.md

@@ -35,6 +35,7 @@
 - **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
 - **开发规范守护（hard policy）**：[`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py) ——规则索引见 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md)，只执行可机器检测的 hard 规则。
 - **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——verb-noun-platform 命名规范校验。
+- **HTML 报告壳**：[`tests/test_html_page_service.py`](../tests/test_html_page_service.py) 守护 `assets/html/example-report.html` 的数据管理 iframe 预览布局基线；业务技能若有自定义 `assets/html/*.html`，建议在自有仓库加同类静态断言（见 `references/ACTIONS.md`「宿主预览布局」）。
 
 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。
 

references/ACTIONS.md

@@ -29,6 +29,7 @@
 3. 有可感知副作用时：提供 `confirmation.message`
 4. 需要用户/Agent 入参时：简单 `inputSchema` + entrypoint 中的 `{{fieldName}}`
 5. `SKILL.md`「用户意图路由表」与 `CLI.md`「Action 强制黑名单」**出现同一 action id / 命令**
+6. 若处理的是**业务队列表中的一行**：遵守 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)——默认只捞**可操作**角色；开始抢占为**进行中**；结束回写成功/失败（失败带原因）；确认文案写清仅可操作态可处理
 
 默认模板 `assets/actions.json` 仅含诊断类 sync Action，**不要**为通过本 checklist 而塞假业务 Action；业务技能按需添加。完整字段见下文 Phase 1。
 
@@ -328,16 +329,16 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 | 值 | 数据管理体验 | 典型场景 |
 |----|--------------|----------|
-| `direct` | **一点即跑**，无弹窗 | 打开文件位置、无参只读、行内主键已映射 |
-| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`） | 打开浏览器、有副作用但无可编辑入参 |
+| `direct` | **一点即跑**，无弹窗 | 打开目录、打开浏览器、无参只读、行内主键已映射 |
+| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`） | 处理待发送、删除前确认、有副作用但无可编辑入参 |
 | `form` | 完整参数表单（现状默认路径） | 导入、查询条件、需用户改写的字段 |
 | `auto` / 省略 | 宿主推断：有**可编辑**参数 → `form`；仅有 `confirmation` → `confirm`；否则 → `direct` | 旧技能兼容；新技能建议显式写出 |
 
 ```json
 {
   "id": "reveal-profile",
-  "label": "打开文件位置",
-  "description": "在资源管理器中打开 Profile 目录。",
+  "label": "打开目录",
+  "description": "打开该账号的浏览器 Profile 目录。",
   "placements": ["row"],
   "executionProfile": "sync",
   "interaction": "direct",
@@ -364,10 +365,10 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 {
   "id": "open-browser",
   "label": "打开浏览器",
+  "description": "用该账号持久化 Profile 打开系统浏览器，仅供肉眼核对。",
   "placements": ["row"],
-  "executionProfile": "async",
-  "interaction": "confirm",
-  "confirmation": { "message": "将用该账号 Profile 打开浏览器，仅供查看。" },
+  "executionProfile": "sync",
+  "interaction": "direct",
   "bind": {
     "tables": ["accounts"],
     "inputMapping": { "accountId": "$row.$pk" }
@@ -376,7 +377,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
     "type": "object",
     "required": ["accountId"],
     "properties": {
-      "accountId": { "type": "number", "readOnly": true }
+      "accountId": { "type": "number", "title": "账号 ID", "readOnly": true }
     }
   },
   "entrypoint": {
@@ -395,6 +396,39 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 - **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。
 
+## Action 按钮中文名（`label`，参考）
+
+`label` 是数据管理 **toolbar / row / batch** 以及技能详情直调上用户看见的短按钮名。本节是**参考契约，不是白名单**：行业专有动作（私信、审单、报关登记等）按业务起名。同类通用动作尽量用同一动词，避免每个技能一套叫法。
+
+**写法：** 短中文，动词或「动词 + 对象」（约 2～8 字）。同一能力用**一个** Action 换 `placements`，不要为入口复制同义按钮。
+
+以后增补：在下表加行，并在模板 `CHANGELOG.md` 记一笔。废弃说法挪到「不要叫」，不要直接删行。
+
+### 宿主已有，技能不要再做一套同义按钮
+
+数据管理宿主已提供：**查看 / 编辑 / 删除 / 新增 / 导入 / 导出 / 刷新**。
+
+技能要用 CLI 接管增删改导入时用 `replaces`（见上文），**不要**再把同义按钮挂到 `placements: ["row"]` 或 `toolbar`（例如「编辑平台」「删除 Key」与底下宿主「编辑」「删除」叠两套）。用户仍点宿主那几个字。
+
+### 建议动词（有则用之）
+
+| 类型 | 建议 `label` | 不要叫 | 说明 |
+|------|----------------|--------|------|
+| 基础设施 | 运行检查、查看版本、查看配置位置、初始化数据 | 健康检查、版本信息、配置路径、初始化数据库 | 多挂 `skill-detail` |
+| 打开 | 打开浏览器、打开目录、打开文件 | 打开文件位置、在资源管理器中打开、用浏览器打开 | 见下节静默成功 |
+| 改库 | 新增…、编辑…、删除…、启用/停用、设置默认…、加入待…、重置为待… | 表记录用「添加」；无必要拆成「启用」「停用」两个按钮 | 对象名可带，如「新增账号」 |
+| 外源入库 | 同步数据、全量同步、采集…、扫描… | 把宿主「刷新」叫成同步；把导出 CSV 叫成同步 | 默认用「同步数据」；全量才写「全量同步」 |
+| 队列与探测 | 处理待…、测试 API、测试网页、抽检本条、抽检所选、批量抽检 | 行 / 勾选 / 工具栏三个入口都叫「抽检」 | 行=本条，勾选=所选，不管勾选的批量=批量 |
+| 生成发布 | 生成 HTML、生成…、发布到… | 用「导出」代替宿主表导出 | 固定 id `render-html` 的 label 用「生成 HTML」 |
+
+### 打开类：一点即开，成功不提示
+
+打开目录 / 打开浏览器 / 打开文件：`interaction: "direct"`，`executionProfile` 通常 `"sync"`。
+
+- **成功**：不要输出用户可见成功文案。若打印 JSON，令 `"message": ""`（宿主据此不弹「执行成功」）。操作系统已经弹出目录或浏览器，就是反馈。
+- **失败**：仍 `ERROR:<CODE>:`（可加 `HINT:`）。
+- **不要**用宿主「查看」表示打开目录或浏览器——「查看」是只读详情。
+
 ## `hoverHint`（工具栏悬停，可选）
 
 与 `label` / `description` / `confirmation.message` **独立**。只决定数据管理**顶栏技能按钮**鼠标悬停时显示什么。
@@ -583,6 +617,7 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 - 使用稳定的退出码
 - 成功时输出可解析的结构化结果
+- **例外（打开类）**：打开目录 / 打开浏览器 / 打开文件成功时不要输出用户可见成功文案；若打印 JSON，令 `"message": ""`。失败仍走下一款错误约定
 - 失败时输出稳定错误信息
 - 对可预期错误提供稳定错误码
 - 对用户可处理的问题提供 `HINT`
@@ -705,7 +740,25 @@ HINT: <next step>
 | `steps` | `afterSuccess` → **`refreshCatalog`**（重扫 `htmlPages`；不要只 `reloadTable`） |
 | `entrypoint` | CLI 子命令（如 `render-html`）调用同一写入内核 |
 
-完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)。
+完整 JSON 形状见 [`../assets/examples/render-html.action.example.json`](../assets/examples/render-html.action.example.json)。最小页面壳见 [`../assets/html/example-report.html`](../assets/html/example-report.html)（已含数据管理 iframe 预览的布局基线；复制后可按需扩展 `{{BODY}}` 内结构）。
+
+### 宿主预览布局
+
+数据管理在 **iframe** 内预览 `html/*.html`；宿主 iframe 已占满右侧预览区，**技能页不应再人为收窄正文**（尤其数据管理窗口通常较窄）。
+
+| 级别 | 约定 |
+|------|------|
+| **必须** | 页面横向**铺满** iframe 可用宽度：`main { width: 100%; min-width: 0; }` |
+| **必须** | **禁止** `main`（或等价正文容器）使用 `max-width: Npx` 且**无** `margin: 0 auto`（宽屏会左对齐留白；窄宿主窗浪费横向空间） |
+| **必须** | `html` / `body` 设 `overflow-x: hidden`；滚动以**纵向**为主，避免横向滚动条 |
+| **必须** | 写入 `{{BODY}}` 的业务数据经 `html.escape`（或等价）转义，防 XSS |
+| **应当** | `header` 与 `main` 水平内边距一致（如共用 CSS 变量或 `clamp()`） |
+| **应当** | 多列表格：`width: 100%` + 单元格 `word-break` / `overflow-wrap`，长文本在格内换行 |
+| **应当** | KPI / 卡片网格用 `repeat(auto-fit, minmax(…, 1fr))` 等流体列，勿死写固定列数 |
+| **禁止** | 在 `<td>` 上用 `max-width` 限制「说明列」等业务列（易导致列宽异常或横向溢出） |
+| **禁止** | 依赖外链 CSS/JS 或 `networkidle` 式加载（iframe `sandbox` 仅 `allow-scripts`；页面应自包含） |
+
+长文阅读型报告若确需版心，可对整个 `main` 使用 `max-width` **且** `margin: 0 auto`，并令 `header` 与 `main` 同宽；**数据看板类**默认不设 `max-width`。
 
 ### 实现要点
 
@@ -718,6 +771,7 @@ HINT: <next step>
 ### 验收（复制后自测）
 
 - [ ] `html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
+- [ ] 预览区**横向铺满**、**无横向滚动条**；拖窄侧栏后内容自适应（见上节「宿主预览布局」）
 - [ ] 表顶栏（若声明 toolbar）或报告右键「重新生成」能跑通；成功后预览刷新
 - [ ] 未登录/无权限用户被拒绝，且有可读错误
 - [ ] 成功路径带 `refreshCatalog`（或等价让侧栏/预览看到更新）
@@ -733,7 +787,7 @@ HINT: <next step>
 | 当前表已有同含义列，且列上已是 CRUD lookup | `column` / `bind.columnMapping`，或属性名 = 列名 | toolbar/batch 弹窗与 create/update 抽屉都会复用该列已解析的选项 |
 | 当前表没有该列（如在「潜客」表上选「话术模板」） | `display_type: "lookup"` + 字段内联 `lookup` 对象 | 打开表单时宿主按当前技能库解析选项 |
 
-内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「表关联 lookup」）：
+内联 `lookup` 与列元数据 `options_json` **同构**（见 [`SCHEMA.md`](SCHEMA.md)「跨表引用 lookup」）：
 
 ```json
 {
@@ -750,6 +804,20 @@ HINT: <next step>
       "filter_column": "is_active",
       "filter_value": 1
     }
+  },
+  "engineIds": {
+    "type": "string",
+    "title": "监测引擎",
+    "description": "可多选；提交为逗号分隔编号。",
+    "display_type": "lookup",
+    "lookup": {
+      "ref_table": "engines",
+      "value_column": "id",
+      "label_column": "display_name",
+      "filter_column": "enabled",
+      "filter_value": 1,
+      "multiple": true
+    }
   }
 }
 ```
@@ -761,16 +829,22 @@ HINT: <next step>
 | `label_column` | 是 | 主文案列 |
 | `extra_column` | 否 | 第三展示列（任意列名，不限「备注」） |
 | `filter_column` / `filter_value` | 否 | 等值过滤 |
+| `multiple` | 否 | `true` = 多选；省略/`false` = 单选（默认） |
 
-**下拉展示（宿主统一，技能只配列）：** `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
+**下拉/选项展示（宿主统一，技能只配列）：** 单选为 `{value} · {label}`；有非空 `extra_column` 时为 `{value} · {label}（{extra}）`。例：`2 · 通用私信-留资`、`2 · 通用私信-留资（dm）`。
 
-**可选「自动」：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。
+**多选存值与模板：** Action / CRUD 存 **`TEXT` 逗号分隔 id**（如 `1,2,5`）；`{{engineIds}}` 原样替换进 CLI。多选字段在 `inputSchema` 里用 `type: "string"`（逗号串），不要用尚未稳定的 JSON array 当业务控件。
+
+**多选控件（宿主策略）：** 选项少（建议 ≤6）用勾选列表；选项多用字段内 Chip + 可搜索下拉（不是再开业务弹窗）。
+
+**可选「自动」（单选常见）：** 字段不要放进 `required`；不要用 `minimum: 1` 卡死留空。宿主会省略空的可选数字参数，避免「提交的数据无效」。
 
 **反模式（勿做）：**
 
 - 标题写成「某某编号」，说明里教用户去左侧表抄 id
 - 用静态 `enum` 罗列会增长/变更的业务行（会过期）
 - 在技能里自己拼假 label 列代替宿主统一格式（难维护）
+- 另造 `lookup_multi` / 第二套 display_type（应只加 `multiple: true`）
 
 形状参考：[`assets/examples/lookup-action.example.json`](../assets/examples/lookup-action.example.json)。
 
@@ -786,7 +860,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 数字 | `type: number` | `display_type: number` 或 INT/REAL/NUMERIC |
 | 开关 | `type: boolean` | `display_type: boolean` |
 | 枚举下拉 | `enum: [...]` | `options_json` 数组 |
-| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`，或绑列 `column` / `columnMapping` | `display_type: lookup` + `options_json` 对象 |
+| 关联下拉（Lookup） | 内联 `display_type: lookup` + `lookup`（可选 `multiple`），或绑列 | 同左；多选存 `TEXT` 逗号分隔 id |
 | 密码 | `sensitive: true` | 列 `sensitive` |
 | 日期（日） | `display_type` 或 `format`: `date` | `display_type: date` → 存 `YYYY-MM-DD` |
 | 日期时间 | `display_type` 或 `format`: `datetime_unix_seconds` | 同左；**存/传 Unix 秒** |
@@ -798,7 +872,8 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 | 只读 | `readOnly: true` | 列 `editable: 0` / 宿主只读规则 |
 | **条件显隐** | **`visibleWhen`**（见下节） | **本版 CRUD 无对称**；仅 Action / 定时任务参数表单 |
 
-**本版不做（勿宣传）：** 文件上传、多选/标签数组、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐。
+**本版不做（勿宣传）：** 文件上传、复杂 `oneOf` / nested object 专用表单；`visibleWhen` 多条件 AND/OR 树、跨 Action 依赖、CRUD 新增/编辑对称显隐。  
+（**Lookup 多选**已支持：同一 `lookup` + `multiple: true`，见上文；不是任意标签数组。）
 
 日期时间约定：
 
@@ -811,7 +886,7 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
 - 根：`object`；属性：`string` / `number` / `boolean`（`object`/`array` 仅作 JSON 多行编辑兼容，新技能慎用）
 - `enum` / `default` / `required` / `sensitive` / `readOnly`
 - `display_type` / `format`：`textarea` | `date` | `datetime_unix_seconds` | `url` | `email` | **`lookup`**
-- 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`）
+- 字段内联 `lookup`（与 CRUD `options_json` lookup 对象同构；可选 `extra_column`、`multiple`）
 - 属性级 `description`（表单标签下方灰字说明）
 - 简单模板替换（`{{fieldName}}`）
 - 可选空数字字段提交时由宿主省略，避免 `""` 触发 number 校验失败
@@ -915,13 +990,15 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
   "pickCount": {
     "type": "number",
     "title": "处理数量",
-    "description": "从队列选取 pending 记录条数",
-    "default": 1,
-    "minimum": 1
+    "description": "从队列选取「可操作」状态记录的条数（具体状态名由本技能定义，见 WORK_ITEM_STATUS）"
   }
 }
 ```
 
+默认**不要**把失败/成功/跳过混进该 pick；重做靠人工改回可操作态。详见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)。
+
+若还需要默认篇数，可在同一 `properties` 里为 `pickCount` 增加 `"default": 1`、`"minimum": 1`。
+
 约定：
 
 - `boolean` 在宿主中渲染为开关
@@ -937,7 +1014,7 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 - 短名看不懂或会覆盖数据时，用独立的 `hoverHint`；不要把确认黄条复用成悬停
 - 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明
 - `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null`
-- **不要**在当前模板中宣传文件上传、多选数组、`oneOf`、复杂 nested object 等尚未稳定支持的能力
+- **不要**在当前模板中宣传文件上传、任意 JSON 多选数组、`oneOf`、复杂 nested object 等尚未稳定支持的能力；Lookup 多选请用 `lookup.multiple`
 ## 风险与入口配置
 
 - 查询、诊断、版本检查可以放到 `skill-detail` 或 `agent`

references/README.md

@@ -17,10 +17,11 @@
 | 根目录 [`CHANGELOG.md`](../CHANGELOG.md) | 市场更新日志 Tab（版本小节 → `changelog`） |
 | [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
 | [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
-| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
+| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口、按钮中文名 `label` 参考（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
 | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
 | [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） |
 | [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理单元格呈现：语义 tone 标色/强调（用途不限；多数技能 P0 不配） |
+| [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md) | 业务行生命周期：处理队列的可操作/进行中/终态角色与重做规则（有处理行 Action 时适用） |
 | [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
 
-按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子标色读 `CELL_PRESENTATION.md`。
+按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。

references/SCHEMA.md

@@ -308,7 +308,7 @@ upsert_column_metadata(
 | `number` | `INTEGER` / `REAL` / `NUMERIC` | 原文 | **数字输入**（`type=number`） | 数字；无 `display_type` 时，物理类型为 INT/REAL/NUMERIC 也应走数字控件 |
 | `boolean` | `INTEGER` 0/1 或 BOOL | 开关语义展示 | 开关 | `0` / `1` |
 | （枚举） | 任意 + `options_json` **数组** | 标签映射 | 下拉选择 | 选项 `value` |
-| `lookup` | 跨表引用 id 标量 + `options_json` **对象** | 标签映射 | 下拉选择（查关联表） | 业务 id（非 SQLite 外键） |
+| `lookup` | 跨表引用 id；`options_json` **对象**；可选 `multiple` | 单选：标签映射；多选：多标签（如「豆包、元宝」） | 单选下拉；多选见下文 | 单选：业务 id 标量；多选：`TEXT` 逗号分隔 id（非 SQLite 外键） |
 | （敏感） | 任意；列 `sensitive=1` | 掩码/隐藏策略由宿主定 | 新建可用密码框；编辑策略与既有宿主一致 | 原文（勿日志明文） |
 | `date` | `TEXT` 推荐 `YYYY-MM-DD`，或可安全归一的值 | 日期 | **日期选择**（日） | `YYYY-MM-DD` |
 | `datetime_unix_seconds` | `INTEGER` | `YYYY-MM-DD HH:mm:ss` | **日期时间选择**；提交写回 **Unix 秒** | Unix **秒**整数；禁止改成 ISO 字符串 |
@@ -320,9 +320,11 @@ upsert_column_metadata(
 **明确不在本版稳定范围（勿在新技能宣传为已支持）：**
 
 - 文件 / 图片上传
-- 多选、标签数组、复杂 `oneOf` / nested object 表单
+- 复杂 `oneOf` / nested object 表单（任意 JSON 数组当业务多选控件）
 - 把业务可编辑时间存成毫秒、ISO 文本或 SQLite `datetime` 文本（审计字段规范见「标准时间字段」）
 
+> **Lookup 多选**已纳入本版契约（见下文 `multiple`），与「任意多选/标签数组」不是同一能力。
+
 `datetime_unix_milliseconds`：仅兼容**列表展示**旧数据；**新技能不要用**；可编辑时间一律 `datetime_unix_seconds`。
 
 #### 新增/编辑表单：字段说明与默认值（宿主支持）
@@ -523,6 +525,19 @@ readonly = 0
 
 模板**默认不建**此类审计表。过程看 `jiangchang.log`，进度/终态看任务中心，业务结果看业务表。
 
+### 业务行生命周期（处理队列）
+
+若技能对某一业务行做「生成 / 触达 / 私信 / 发布」等有副作用处理，状态字段须遵守 **角色模型**（可操作 / 进行中 / 成功·失败·跳过类终态），**不要**把某一技能的状态名当成全平台唯一枚举。默认只处理可操作态；重做靠人工改回可操作。完整规则见 [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md)。
+
+建议：
+
+| 项 | 说明 |
+|----|------|
+| 状态列 | `options_json` 列出本技能全部业务状态（含进行中与各类终态） |
+| 失败原因 | 失败类终态应有用户可读的原因字段（勿写密钥） |
+| 可编辑 | 终态/进行中建议可改回可操作，或提供等价 Action |
+| `grid_help` | 可一句话说明「仅某某状态可处理」 |
+
 表级 `readonly = 1` 时，宿主数据管理只读展示；技能 repository 仍可写入。
 
 ### 通用示例：`demo_items`（测试 fixture 参考）
@@ -573,7 +588,9 @@ CREATE TABLE demo_items (
 
 ### 2）跨表引用 lookup（对象，用于关联 id 字段）
 
-当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）。这是**展示与表单下拉**契约，**不是** SQLite 外键：
+当字段取值依赖同库另一张业务表时，`display_type` 设为 `lookup`，`options_json` 写对象（**不是**数组）。这是**展示与表单选择**契约，**不是** SQLite 外键。
+
+**单选（默认，与既有行为一致）：**
 
 ```json
 {
@@ -586,26 +603,54 @@ CREATE TABLE demo_items (
 }
 ```
 
+**多选（平行扩展，仅多一个开关）：**
+
+```json
+{
+  "ref_table": "engines",
+  "value_column": "id",
+  "label_column": "display_name",
+  "filter_column": "enabled",
+  "filter_value": 1,
+  "multiple": true
+}
+```
+
 | 字段 | 必填 | 说明 |
 |---|---|---|
 | `ref_table` | 是 | 同库被引用表名（snake_case 标识符） |
 | `value_column` | 是 | 写入当前字段的值列（业务 id / 编号） |
-| `label_column` | 是 | 下拉主文案列（名称） |
+| `label_column` | 是 | 选项主文案列（名称） |
 | `extra_column` | 否 | 第三展示列（不必叫「备注」）；有值时拼进括号 |
 | `filter_column` / `filter_value` | 否 | 等值过滤（如只列出 `enabled=1`） |
+| `multiple` | 否 | `true` = 多选 Lookup；省略或 `false` = **单选**（默认） |
 
-宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 下拉选项；**物理列仍存标量**（如 `platform_key` 文本、`account_id` 整数），不做嵌套子表。
+宿主在加载表 schema 时查询 `ref_table`，把结果展开成 `{value,label}` 选项列表。
+
+**存库约定：**
+
+| 模式 | 物理列建议 | 存什么 |
+|------|------------|--------|
+| 单选 | 整数或文本标量 | 一个业务 id（如 `2`、`douyin`） |
+| 多选 | **`TEXT`** | 逗号分隔 id，如 `1,2,5`（与 `$selection.ids` 风格一致）；**不要**建联接子表当 UI 多选 |
 
 **统一展示文案（宿主固定一种，技能只配列）：**
 
-- 默认：`{value} · {label}`，例如 `2 · 通用私信-留资`、`douyin · 抖音`
+- 单选默认：`{value} · {label}`，例如 `2 · 通用私信-留资`、`douyin · 抖音`
 - 配置了 `extra_column` 且该行有非空值：`{value} · {label}（{extra}）`
 - 未配置 `extra_column`、或额外列为空：不加 `（）`
 - `label` 为空或与 `value` 相同时：只显示 `value`（可再带额外括号）
+- **多选列表格**：按 id 拆开后逐个映射为 label，再用顿号/逗号拼接（如 `豆包、元宝`）；过长可截断并提示「+N」
 
-Action 弹窗内联 Lookup 与上表 **同构**（字段名一致），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+**控件呈现（宿主策略，非第二套契约）：**
 
-示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`。
+- 单选：下拉 Select（现状）
+- 多选且选项较少（建议 ≤6）：勾选列表
+- 多选且选项较多：字段内 Chip + 可搜索下拉（**不是**再开一层业务弹窗）
+
+Action 弹窗内联 Lookup 与上表 **同构**（字段名一致，含 `multiple`），见 [`ACTIONS.md`](ACTIONS.md)「跨表引用：Lookup」。
+
+示例：账号表的平台字段 → 平台信息表；凭据表的账号编号 → 账号信息表；私信 Action 选话术 → `message_templates`；抽检 Action 多选引擎 → `engines` + `multiple: true`。
 
 ## 幂等初始化标准
 

references/WORK_ITEM_STATUS.md

@@ -0,0 +1,157 @@
+# 业务行生命周期契约（Work Item Lifecycle）
+
+> **状态：正式契约 v1.0。**  
+> **目标：** 冻结「对某一行做有副作用处理」时的**状态角色与操作权**规则，使队列型技能（生成、触达、私信、发布等）行为一致、可验收。  
+> **非目标：** 规定某一技能的具体状态码或状态个数；强制所有表都有 status；替代任务中心 / 运行日志；规定 Data Policy 授权。  
+> **适用范围：** 有「处理业务行」类 Action 的技能。纯配置表、目录表、只读展示表标 N/A。
+
+相关正交轴：[`ACTIONS.md`](ACTIONS.md)（入口与 sync/async）、[`SCHEMA.md`](SCHEMA.md)（表与展示）、[`POLICY.md`](POLICY.md)（谁能点）、任务中心（宿主 Job）。
+
+---
+
+## 0. 为什么需要本契约
+
+若「处理这一行」的按钮对**任意状态**都可点，会出现：
+
+- 已成功的行被重复执行（重复发信、重复生成、覆盖产物）
+- 失败行被默认批量静默重试，运营无法区分「未做」与「做过但失败」
+- 任务中心显示成功，业务表仍停在初始态（结果未回写）
+
+本契约要求：**默认可自动操作的只有「可操作」角色；其它角色须人工改回可操作后再处理。**
+
+---
+
+## 1. 状态角色（通用，不绑死枚举）
+
+技能自己定义业务状态字符串与中文标签；契约只认**角色**。一个角色可对应**一个或多个**业务状态。
+
+| 角色 | 含义 | 默认可被处理 Action 捞起？ |
+|------|------|---------------------------|
+| **operable（可操作）** | 尚未成功处理、允许自动或行操作启动处理 | **是（默认唯一）** |
+| **in_progress（进行中）** | 已抢占，正在处理 | **否**（防双跑） |
+| **terminal_success（成功类终态）** | 已按业务定义完成 | **否** |
+| **terminal_failure（失败类终态）** | 已尝试且失败；通常带失败原因 | **否** |
+| **terminal_skipped（跳过类终态）** | 人工放弃或不处理 | **否** |
+
+### 1.1 举例（仅对照，不是规范枚举）
+
+| 角色 | 技能 A（内容队列）可能叫 | 技能 B（线索触达）可能叫 |
+|------|--------------------------|--------------------------|
+| operable | 待生成、新建 | 新建、私信未发 |
+| in_progress | 生成中 | 触达中 |
+| terminal_success | 已生成 | 已私信 |
+| terminal_failure | 失败 | 触达失败 |
+| terminal_skipped | 已跳过 | 已忽略 |
+
+技能可以有更多业务状态（审核中、待确认、部分成功等）：须在需求里写明各自映射到哪一角色，或声明「不属于处理队列、本契约 N/A」。
+
+### 1.2 技能必须声明映射
+
+复制模板后，在 `development/REQUIREMENTS.md`（或等价需求）中写清：
+
+```text
+处理队列表：<table>
+状态字段：<column>
+可操作：<status1>, <status2>, …
+进行中：<status…>
+成功类终态：…
+失败类终态：…（失败原因字段：…）
+跳过类终态：…
+```
+
+未声明映射的「处理队列」技能，交活 Checklist 不得标 PASS。
+
+---
+
+## 2. 硬规则（技能实现必须遵守）
+
+1. **默认只认 operable**  
+   行操作 / 批量 / 定时 / Agent 触发的「处理」类 Action，pick 与 claim **默认**只包含可操作状态。  
+   不得把成功、失败、跳过、进行中混进默认捞取集合（除非另做**显式命名**的「重试失败」类 Action，且确认文案写清范围——仍推荐不如人工改回可操作简单）。
+
+2. **开始即原子抢占 → in_progress**  
+   在真正产生副作用前，用「仅当当前为 operable 时 UPDATE 为进行中」的方式抢占。抢占失败 → 跳过或返回明确错误（如「当前不是可操作状态」），**禁止**继续副作用。
+
+3. **结束必须回写业务表**  
+   - 成功 → 对应成功类终态，并写入产物路径/摘要等业务字段（若有）  
+   - 失败 → 对应失败类终态，并写入**失败原因**（用户可读；勿塞密钥）  
+   - 禁止「任务中心成功、业务行仍停在可操作/进行中」而不回写
+
+4. **重做靠人工改回 operable**  
+   成功 / 失败 / 跳过 / 卡住的进行中，默认不能再点处理。运营在数据管理把状态改回可操作后，方可再次处理。
+
+5. **任务中心 ≠ 业务状态**  
+   Job「进行中 / 成功 / 失败」是宿主任务态。业务「进行中」必须写在业务表。进度 `emit` 不替代状态回写。
+
+6. **过程与结果分工**（延续既有约定）  
+   过程 → 运行日志 / 任务中心 Activity；业务结果 → 业务表。**不要**靠新建 `task_logs` 一类审计表充当状态机。
+
+---
+
+## 3. Action 与文案约定
+
+- 处理类 Action 的 `description` / `confirmation.message` 应写明：**仅处理「可操作」状态**（用本技能用户能懂的词，如「仅待生成」「仅新建」）。
+- 对非可操作行触发时：返回明确失败码与中文说明，提示「请先改回 xxx」。
+- 长任务（`async`）：除任务中心进度外，业务行应尽快进入进行中，避免界面长时间仍显示可操作导致连点。
+
+正交提醒：
+
+| 轴 | 管什么 | 不管什么 |
+|----|--------|----------|
+| 本契约 | 什么**状态**能处理 | 谁有权点按钮 |
+| Data Policy | 谁有权 | 状态机 |
+| executionProfile | sync/async 通道 | 业务终态 |
+
+---
+
+## 4. 数据管理展示建议
+
+- 状态列：`options_json` 枚举完整业务状态（含进行中与各类终态）。
+- 失败原因列：失败类终态可见；成功后宜清空或保留末次原因（技能自定，须一致）。
+- 终态与进行中的状态字段建议 **可编辑**（或提供「改回可操作」Action），以便人工重做；**不要**只能靠删行重建。
+- `grid_help` 可一句话写清：「仅某某状态可处理；其它状态请改回后再操作。」
+
+详见 [`SCHEMA.md`](SCHEMA.md)。
+
+---
+
+## 5. 可观测性（与 ACTIONS / 日志约定对齐）
+
+推荐阶段（名称可自定，须能对应到开始 / 关键节点 / 结束）：
+
+1. 已抢占（业务 → 进行中）  
+2. 处理中关键步骤（可 `emit`）  
+3. 回写成功或失败  
+
+故意失败一条时：业务表应为失败类终态 + 原因；任务中心为失败；日志含 `task_failed` / `error_code=`。
+
+---
+
+## 6. 非目标与常见误区
+
+| 误区 | 正确做法 |
+|------|----------|
+| 把「新建/成功/失败/跳过」写成全平台唯一枚举 | 只用角色；各技能自定状态名 |
+| 默认批量包含失败「方便自动重试」 | 默认不含；重试改回可操作或单独显式 Action |
+| 只有任务成功、不改业务状态 | 必须回写业务表 |
+| 用进行中替代任务中心 | 两者都要：业务防双跑，任务轨看进度 |
+| 所有表都套本契约 | 无「处理行」副作用的表标 N/A |
+
+---
+
+## 7. 验收摘要（完整条目见 CHECKLIST）
+
+有处理队列时至少验证：
+
+1. 成功类终态再点处理 → 拒绝或跳过，不产生重复副作用  
+2. 可操作行处理中 → 先见进行中，结束后见成功或失败+原因  
+3. 失败行改回可操作后 → 可以再次处理  
+4. 任务中心有过程（长任务）且业务表状态与结果一致  
+
+---
+
+## 8. 版本
+
+| 版本 | 说明 |
+|------|------|
+| v1.0 | 首版：角色模型 + 硬规则 + 需求映射 + 与 Action/SCHEMA/任务中心边界 |

scripts/db/display_metadata_validator.py

@@ -219,6 +219,8 @@ def validate_options_json(options_json: str | None) -> tuple[list[str], list[str
                 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")
+        if "multiple" in parsed and not isinstance(parsed.get("multiple"), bool):
+            errors.append("options_json lookup.multiple 必须是布尔值")
         return errors, warnings
 
     if not isinstance(parsed, list):

scripts/service/html_page_service.py

@@ -4,6 +4,7 @@
 
 - 目录：仅一层 `html/*.html`（非递归）
 - 重新生成 Action id 必须为 `render-html`（宿主硬编码）
+- 页面布局底线见 `references/ACTIONS.md`「宿主预览布局」；模板壳 `assets/html/example-report.html`
 - 成功后建议 `steps: refreshCatalog` 以重扫侧栏
 - 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
 """

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.92"
+SKILL_VERSION = "1.0.97"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

tests/test_docs_standards.py

@@ -301,6 +301,7 @@ class TestDocsStandards(unittest.TestCase):
         self.assertTrue(os.path.isfile(os.path.join(root, "references", "ACTIONS.md")))
         self.assertTrue(os.path.isfile(os.path.join(root, "references", "POLICY.md")))
         self.assertTrue(os.path.isfile(os.path.join(root, "references", "CELL_PRESENTATION.md")))
+        self.assertTrue(os.path.isfile(os.path.join(root, "references", "WORK_ITEM_STATUS.md")))
         self.assertTrue(
             os.path.isfile(os.path.join(root, "assets", "schemas", "skill-actions.schema.json"))
         )
@@ -353,6 +354,8 @@ class TestDocsStandards(unittest.TestCase):
             "表与表之间：禁止 SQLite 外键",
             "禁止 SQLite 外键",
             "跨表引用 lookup",
+            "\"multiple\": true",
+            "Lookup 多选",
         ):
             self.assertIn(marker, text, msg=f"SCHEMA.md missing {marker!r}")
 
@@ -364,6 +367,7 @@ class TestDocsStandards(unittest.TestCase):
             "跨表引用：Lookup",
             "display_type: \"lookup\"",
             "extra_column",
+            "multiple",
             "数据管理新增/编辑",
             "_jiangchang_columns.description",
             "datetime_unix_seconds",

tests/test_html_page_service.py

@@ -61,6 +61,15 @@ class TestHtmlPageService(unittest.TestCase):
             with self.assertRaises(ValueError):
                 write_html_page("note.txt", "<html></html>")
 
+    def test_example_report_shell_embedded_preview_layout(self) -> None:
+        """守护 example-report.html：数据管理 iframe 预览布局基线不退化。"""
+        template = load_html_template("assets/html/example-report.html")
+        self.assertIn("overflow-x: hidden", template)
+        self.assertIn("min-width: 0", template)
+        self.assertIn("table-layout: fixed", template)
+        self.assertIn("overflow-wrap: anywhere", template)
+        self.assertNotIn("max-width:", template)
+
 
 if __name__ == "__main__":
     unittest.main()