Release v1.0.82: add optional hoverHint contract for toolbar skill actions

references/ACTIONS.md

@@ -85,6 +85,7 @@ Action 是**可选能力**：
 | **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
 | **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
 | **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、默认 CRUD 接管、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
+| **`hoverHint`** | **可选**：数据管理**工具栏悬停**文案 | 不决定短按钮名；不决定点下去弹不弹窗；**不回退** `description` / `confirmation.message`；省略 = 不显示悬停。当前宿主实现为顶栏技能按钮 |
 | **`hostEffects` / `steps`** | **可选**：数据管理交互跑完前后，宿主要不要刷新表 / 清选区 / 级联删等 | 不决定业务写什么；**省略 = 宿主不额外改 UI**（≥2.8.5 起不再硬编码 mutation 后刷新）；cron/agent 忽略 |
 | **`cellPresentation`** | **可选**：某表某行某列的语义标色/强调（tone + 说明） | 不替代业务列；不下发 CSS；用途不限（超时、预警、驳回等）；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) |
 | **`policy` / Snapshot** | **可选**：当前身份在数据管理下允许哪些 Action / 宿主内置能力 / 行列范围 | 不替代 placements；不替代 domain 写路径鉴权；多数技能不配 = L0 全开 |
@@ -98,7 +99,7 @@ Action 是**可选能力**：
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions`；可选 **`policy`**（Data Policy 启用块）；可选 **`cellPresentation`**（单元格呈现启用块） |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`interaction`**、**`interactionByPlacement`**、**`bind`**、**`replaces`**、**`hostEffects`**、**`steps`**、**`authz`**（仅文档提示） |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `hoverHint`、`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,7 @@ Action 是**可选能力**：
 | **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载单元格呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
 | inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`；可选 `display_type` / `format`（`textarea` / `date` / `datetime_unix_seconds` / `url` / `email`） |
 | confirmation | `{ "message": "..." }` — **风险文案**（confirm/form 弹窗黄条；agent 元数据）；**不是**「要不要弹窗」的开关 |
+| **hoverHint** | 可选字符串。数据管理**工具栏悬停**文案；与 `description` / `confirmation.message` **独立**。省略则不显示悬停，不回退。短名已够懂时不要写。需宿主已支持该字段；当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出 |
 | **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
 | **interaction** | `"auto"` \| `"direct"` \| `"confirm"` \| `"form"`（可选；省略≈`auto`） |
 | **interactionByPlacement** | 可选；按 placement 覆盖为 `direct`/`confirm`/`form`（不可写 `auto`） |
@@ -253,6 +255,30 @@ Action 是**可选能力**：
 - **cron 触发 / agent**：忽略 `interaction`（无人值守 / 模型填参）；`confirmation` 对 agent 仍作 `requiresConfirmation` 元数据。
 - 不要用 `interaction: "direct"` 掩盖需要用户填写的可编辑字段——宿主在 `auto` 下会因可编辑参数回落到 `form`；显式 `direct` + 可编辑字段时参数取 default/预填，作者须自觉。
 
+## `hoverHint`（工具栏悬停，可选）
+
+与 `label` / `description` / `confirmation.message` **独立**。只决定数据管理**顶栏技能按钮**鼠标悬停时显示什么。
+
+- **省略 / 空白** ⇒ 不显示悬停，**不回退**灰色说明或确认黄条。
+- 短按钮名已经够懂时**不要写**，避免噪音。适合：业务黑话、会覆盖本机/远程、不点进去看不出后果。
+- 悬停文案不要写成「确认开始？」；那是点下去之后黄条的口吻。
+- 当前宿主实现为**工具栏技能按钮**；宿主内置删除/刷新/新增/导入/导出不走本字段。
+- 需宿主已支持 `hoverHint`；更旧宿主会忽略未知字段（模板 Schema 仍会校验新技能）。
+
+```json
+{
+  "id": "kb-sync-feishu",
+  "label": "拉取到本机",
+  "description": "把飞书知识库覆盖到本机工作区。未发布的本地修改会丢失。",
+  "hoverHint": "将用飞书覆盖本机知识库，未发布的本地修改会丢失。",
+  "placements": ["toolbar"],
+  "executionProfile": "async",
+  "interaction": "confirm",
+  "confirmation": { "message": "将用飞书覆盖本机知识库，未发布的本地修改会丢失。确认开始？" },
+  "bind": { "tables": ["kb_sources"] }
+}
+```
+
 ## `hostEffects` / `steps`（执行前后宿主编排，≥2.8.5）
 
 与 `placements` / `executionProfile` / `interaction` **正交**。决定的是：数据管理里点完 Action 之后（或之前），宿主要不要**刷新当前表、刷新目录、清空多选、级联删子表**等。
@@ -471,6 +497,7 @@ HINT: <next step>
 禁止：
 
 - 臆造 `sortOrder` / `order` / `priority` 等字段指望宿主排序（模板 Schema `additionalProperties: false` 会拒收）。
+- 臆造 `tooltip` / `title` 等字段当悬停（用可选 `hoverHint`；不要把 `confirmation.message` 复用成悬停）。
 - 依赖或宣传表顶栏「更多操作」溢出菜单（宿主已取消该能力）。
 - 把「表格行数据默认排序」与按钮顺序混淆——行排序见 [`SCHEMA.md`](SCHEMA.md) 的 `default_sort_json`。
 - 把「默认展示列」与 `visible=0` 硬隐藏混淆——默认展示列见 [`SCHEMA.md`](SCHEMA.md) 的 `default_visible_columns_json`。
@@ -670,6 +697,7 @@ CRUD 侧宿主义务与禁止事项见 [`SCHEMA.md`](SCHEMA.md)「表单与展
 - `readOnly: true` 时数据管理表单只读展示该字段（仍随提交传入）；适合行内/勾选预填的主键、编号列表
 - `placements` 含 `batch` 的动作在数据管理表顶常驻，无勾选时禁用（与表删除一致）
 - 需要确认的副作用操作使用 `confirmation.message`
+- 短名看不懂或会覆盖数据时，用独立的 `hoverHint`；不要把确认黄条复用成悬停
 - 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明
 - `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null`
 - **不要**在当前模板中宣传文件上传、多选数组、`oneOf`、复杂 nested object 等尚未稳定支持的能力