Release v1.0.74: hostEffects/steps Action contract

references/ACTIONS.md

@@ -85,6 +85,7 @@ Action 是**可选能力**：
 | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
 | **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
 | **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、默认 CRUD 接管、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
+| **`hostEffects` / `steps`** | **可选**：数据管理交互跑完前后，宿主要不要刷新表 / 清选区 / 级联删等 | 不决定业务写什么；**省略 = 宿主不额外改 UI**（≥2.8.5 起不再硬编码 mutation 后刷新）；cron/agent 忽略 |
 | **`policy` / Snapshot** | **可选**：当前身份在数据管理下允许哪些 Action / 宿主内置能力 / 行列范围 | 不替代 placements；不替代 domain 写路径鉴权；多数技能不配 = L0 全开 |
 | **`entrypoint`** | 实际执行哪个 CLI 命令与参数 | 不写业务逻辑 |
 | **domain service** | **真正完成什么业务** | 不感知 toolbar / cron / agent 来源 |
@@ -96,7 +97,7 @@ Action 是**可选能力**：
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions`；可选 **`policy`**（Data Policy 启用块） |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`authz`**（仅文档提示） |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`hostEffects`**、**`steps`**、**`authz`**（仅文档提示） |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron`；仅 `replaces` 时可为空数组 |
 | **replaces** | 可选 `"create"` \| `"update"` \| `"delete"` — 接管默认新增/编辑/删除（须 `bind.tables`） |
@@ -107,6 +108,8 @@ Action 是**可选能力**：
 | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
 | **interaction** | `"auto"` \| `"direct"` \| `"confirm"` \| `"form"`（可选；省略≈`auto`） |
 | **interactionByPlacement** | 可选；按 placement 覆盖为 `direct`/`confirm`/`form`（不可写 `auto`） |
+| **hostEffects** | 可选；`onSuccess` / `onFailure` → `reloadTable` \| `refreshCatalog` \| `clearSelection`（匠厂宿主 ≥2.8.5） |
+| **steps** | 可选；有序 `{ when, do, table?, fk? }`，`when`=`before`\|`afterSuccess`\|`afterFailure`；新技能优先（≥2.8.5） |
 
 ## `bind.tables`（表级绑定）
 
@@ -248,6 +251,84 @@ Action 是**可选能力**：
 - **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。
 
+## `hostEffects` / `steps`（执行前后宿主编排，≥2.8.5）
+
+与 `placements` / `executionProfile` / `interaction` **正交**。决定的是：数据管理里点完 Action 之后（或之前），宿主要不要**刷新当前表、刷新目录、清空多选、级联删子表**等。
+
+- **省略 / 空** ⇒ 宿主**不**额外改 UI（≥2.8.5 起不再对 mutation 硬编码刷新）。本地库若已由技能写新，界面仍可能旧，直到用户点内置「刷新」或本 Action 声明了 `reloadTable`。
+- **仅数据管理交互路径生效**（toolbar / row / batch / skill-detail / `replaces`）；**cron 与 agent 忽略**（与 `interaction` 相同）。
+- 需匠厂宿主 **≥ 2.8.5**；更旧宿主会忽略未知字段（若未做严格 Schema 校验）。
+- **新技能优先写 `steps`**；`hostEffects` 仍可作为「只刷 UI」的简写。两者可并存；同一 UI 效果若两边都声明，宿主可能各跑一次。
+
+### `hostEffects`（UI 副作用简写）
+
+```json
+{
+  "hostEffects": {
+    "onSuccess": ["reloadTable"],
+    "onFailure": ["clearSelection"]
+  }
+}
+```
+
+| 字段 | 触发时机 |
+|------|----------|
+| `onSuccess` | **sync** 退出码 0；或 **async** 任务已被任务中心**接收**（不是 Job 跑完） |
+| `onFailure` | **sync** 失败；或 **async** **启动被拒** |
+
+闭集 effect id：`reloadTable`（重载当前表 + 常伴随 Data Policy 再拉）、`refreshCatalog`（刷新技能目录）、`clearSelection`（清空多选）。未知 id 丢弃。
+
+**async 注意**：`sync-data` 一类长同步若写 `onSuccess: ["reloadTable"]`，会在**入队成功时**就刷表，可能仍是旧数据；更适合 sync 的新建/登记，或等 Job 真正完成后再刷（若宿主后续扩展完成回调）。
+
+### `steps`（有序编排，推荐）
+
+```json
+{
+  "steps": [
+    { "when": "before", "do": "deleteByFk", "table": "child_rows", "fk": "parent_id" },
+    { "when": "afterSuccess", "do": "reloadTable" },
+    { "when": "afterFailure", "do": "clearSelection" }
+  ]
+}
+```
+
+| `when` | 含义 |
+|--------|------|
+| `before` | 调用 CLI **之前** |
+| `afterSuccess` | 同 `hostEffects.onSuccess` |
+| `afterFailure` | 同 `hostEffects.onFailure` |
+
+| `do` | 说明 |
+|------|------|
+| `reloadTable` / `refreshCatalog` / `clearSelection` | 同 hostEffects |
+| `deleteByFk` | 按外键批量删子表；须 `table` + `fk`；行按钮会把当前行主键当父键 |
+| `deleteRows` | 删指定表行；须 `table` |
+
+规则：单次最多 **8** 步；未知步骤丢弃；`deleteByFk` / `deleteRows` 仅走 Skill Action steps 路径时可删 `metadata_readonly` 投影表（人工 CRUD 仍守只读）。整库只读 / 视图仍禁止写。
+
+典型：业务表「新建 / 登记 / 更新」成功后加 `{ "when": "afterSuccess", "do": "reloadTable" }`，避免用户傻等旧表格。
+
+```json
+{
+  "id": "register-one",
+  "label": "登记本行",
+  "description": "更新当前行业务字段。",
+  "placements": ["row"],
+  "executionProfile": "sync",
+  "interaction": "form",
+  "bind": {
+    "tables": ["business_records"],
+    "inputMapping": { "recordId": "$row.$pk" }
+  },
+  "steps": [{ "when": "afterSuccess", "do": "reloadTable" }],
+  "entrypoint": {
+    "type": "cli",
+    "command": "register",
+    "args": ["--id", "{{recordId}}"]
+  }
+}
+```
+
 默认模板 `actions.json` 仅含 `health` / `version` / `config-path`，不放在 toolbar/row/batch，故无需 `bind` 示例污染默认 manifest。业务示例：
 
 ```json