Release v1.0.120: document bind.visibleWhen for row menu visibility
All checks were successful
技能自动化发布 / release (push) Successful in 7s
All checks were successful
技能自动化发布 / release (push) Successful in 7s
This commit is contained in:
@@ -107,7 +107,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
| entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
|
||||
| placements | `toolbar`、`row`、`batch`、`skill-detail`、`agent`、`cron`；仅 `replaces` 时可为空数组 |
|
||||
| **replaces** | 可选 `"create"` \| `"update"` \| `"delete"` \| `"import"` — 接管默认新增/编辑/删除/导入（须 `bind.tables`） |
|
||||
| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**（行内/批量预填、选择摘要标签、勾选驱动模式，见下节） |
|
||||
| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**（行内/批量预填、选择摘要标签、勾选驱动模式、**行菜单显隐**，见下节） |
|
||||
| **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
|
||||
| **cellPresentation** | 可选；`{ "enabled": true }` 时宿主应加载格子与 grid 呈现；见 [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md)。未启用 = P0 |
|
||||
| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive`、`readOnly`、可选 **`revealInForm`**；可选 `display_type` / `format`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
|
||||
@@ -133,7 +133,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
|
||||
规则：
|
||||
|
||||
- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**。
|
||||
- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`、`columnMapping`、**`labelColumn`**、**`selectionMode`**、**`visibleWhen`**。
|
||||
- `tables` 非空数组、元素唯一、英文 **snake_case**、不得为空字符串。
|
||||
- **`placements` 含 `toolbar` 时必须显式声明非空 `bind.tables`**（模板 Schema `if/then` + 自动测试强制）。
|
||||
- `row` / `batch` **建议**同样声明 `bind.tables`，避免在无关表上露出按钮；未声明时宿主可能按兼容逻辑在更多表上展示。
|
||||
@@ -143,8 +143,42 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
- **`columnMapping`（可选）**：把 inputSchema 属性名映射到物理列名，供表单复用列展示名 / lookup。
|
||||
- **`labelColumn`（可选）**：物理列名，供数据管理 Action 弹层「已选择」摘要展示 `#id + 标签`。**仅影响展示，不改变 CLI/提交 payload，也不决定业务是否跳过某些状态。** 省略时宿主用常见列名启发（如 `title` / `name` / `nickname` 等）；再没有则只显示编号。列名不常见、或启发会选错列时再显式声明。
|
||||
- **`selectionMode`（可选）**：数据管理**表勾选**如何驱动本 Action（与 `placements` / `executionProfile` 正交）。见下节「勾选驱动模式」。
|
||||
- **`visibleWhen`（可选）**：`placements` 含 `row` 时，按**当前行原始列值**决定是否出现在行菜单 / 行按钮。见下节「行菜单显隐」。
|
||||
- `concurrency` / `locks` 仍未稳定，**不要**写入新技能 manifest。
|
||||
|
||||
### 数据管理：行菜单显隐 `bind.visibleWhen`
|
||||
|
||||
行级 Action 常需按业务状态显隐，例如：已采用不再出「采用」；仅已采用才出「加入待写」。**宿主已支持**写在 `bind.visibleWhen`（对当前行求值；不匹配则该行菜单不出现此项）。这是正式 Action 契约，**不是** Policy L3 预留，也**不是**表单字段 `inputSchema.properties.*.visibleWhen`。
|
||||
|
||||
| | `bind.visibleWhen` | 表单字段 `visibleWhen` | Policy L3（预留） |
|
||||
|--|--------------------|------------------------|-------------------|
|
||||
| 作用对象 | 行菜单 / 行按钮是否出现 | Action 参数表单里某个控件 | （未冻结）权限策略等 |
|
||||
| 求值上下文 | **当前行列值** | 当前表单参数值 | — |
|
||||
| 省略时 | 始终显示 | 字段始终显示 | — |
|
||||
|
||||
**写法（形状与表单字段相同）：**
|
||||
|
||||
```json
|
||||
"bind": {
|
||||
"tables": ["long_tails"],
|
||||
"visibleWhen": { "status": "approved" },
|
||||
"inputMapping": { "longTailId": "$row.$pk" }
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
"visibleWhen": { "field": "status", "in": ["pending_review", "skipped"] }
|
||||
```
|
||||
|
||||
也支持 `{ "field": "status", "equals": "approved" }`。规则缺失或无法解析时宿主视为始终可见（兼容旧技能）。
|
||||
|
||||
**要点：**
|
||||
|
||||
1. 只影响 **UI 是否展示**；CLI / Agent 仍可直接调同一 entrypoint，技能侧仍应校验状态。
|
||||
2. 比较用行的**存库原始值**（如 `approved`），不是界面中文「已采用」。
|
||||
3. 顶栏 / batch 按钮不受 `bind.visibleWhen` 约束（无「当前行」）；批量入口靠勾选 + 技能跳过非法状态。
|
||||
4. 示例：[`assets/examples/bind-visible-when-row.action.example.json`](../assets/examples/bind-visible-when-row.action.example.json)。
|
||||
|
||||
### 数据管理：勾选驱动模式 `bind.selectionMode`
|
||||
|
||||
同一业务能力应尽量用**一个** Action（多个 `placements`），避免「勾选下载」与「按数量处理队列」拆成两个同义顶栏按钮、却让用户误以为勾选生效。
|
||||
@@ -746,7 +780,7 @@ HINT: <next step>
|
||||
|
||||
### 行级入口 `row`（宿主呈现契约）
|
||||
|
||||
- **技能决定有什么**：`placements` 含 `"row"`（且通过 `bind.tables` / policy 等过滤）的 Action，构成该表行的技能菜单项集合；配什么就出现什么。
|
||||
- **技能决定有什么**：`placements` 含 `"row"`（且通过 `bind.tables` / policy 等过滤）的 Action，构成该表行的技能菜单项集合；再用可选 **`bind.visibleWhen`** 按行状态过滤（见「行菜单显隐」）。
|
||||
- **宿主决定怎么摆**：可用操作列、行右键、行内「⋯」等呈现**同一批** Action；点击均走同一 `launch`（`placement: "row"`），`interaction` / `executionProfile` 与壳无关。
|
||||
- **顺序**：各壳内技能项顺序 = 下方「数据管理技能按钮顺序」契约（`actions` 数组相对顺序）。
|
||||
- **宿主内置项**：查看 / 编辑 / 删除由宿主提供，**不是**技能 `actions.json` 配置出来的；若出现在行右键，须与技能项分组（例如分隔线后），且不得要求技能再配一份菜单 DSL。
|
||||
@@ -1166,8 +1200,10 @@ Skill Action 弹窗与数据管理「新增 / 编辑」使用**同一套控件
|
||||
|
||||
用于「先选模式，再出对应参数」类表单。写在 `inputSchema.properties.<field>` 上（**不是** action 顶层字段）。
|
||||
|
||||
> **消歧义：** 本文的 `visibleWhen` = **Action 参数表单控件显隐**。
|
||||
> [`POLICY.md`](POLICY.md) L3 预留的 `visibleWhen` = **行态/权限策略**（未冻结），**不是**同一能力。勿混用、勿互相替代。
|
||||
> **消歧义：**
|
||||
> - **表单** `inputSchema.properties.*.visibleWhen` = Action **参数控件**显隐。
|
||||
> - **`bind.visibleWhen`** = 数据管理 **行菜单 / 行按钮**显隐（见上文「行菜单显隐」）。
|
||||
> - [`POLICY.md`](POLICY.md) L3 预留的行态 `visibleWhen` = **权限策略**（未冻结），**不是**以上二者。勿混用、勿互相替代。
|
||||
|
||||
```json
|
||||
"keyword": {
|
||||
|
||||
@@ -2,8 +2,10 @@
|
||||
|
||||
> **状态：正式契约 v1.0（`schemaVersion` 1）。**
|
||||
> **目标：** 冻结「启用方式 + Snapshot 最小字段 + L2 scope 白名单」，使多数技能（L0）零配置，需要权限的技能（L1/L2）有稳定扩展面。
|
||||
> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（行态 `visibleWhen` 等）。
|
||||
> **注意：** L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`（表单控件显隐，见 [`ACTIONS.md`](ACTIONS.md)「字段条件显隐」）。二者同名不同义，勿混用。
|
||||
> **非目标：** 宿主实现业务用户/角色库；规定飞书/HTTP/本地表等权限数据源；本期不强制 L3（菜单级藏表、`rows.mode=delegate` 等）。
|
||||
> **注意：**
|
||||
> - 行菜单按业务状态显隐请用 Action 契约 **`bind.visibleWhen`**（见 [`ACTIONS.md`](ACTIONS.md)「行菜单显隐」）——宿主已支持，**不属于**本 Policy L3。
|
||||
> - L3 预留的行态 `visibleWhen` **不是** Action 参数表单的 `inputSchema.properties.*.visibleWhen`，也**不是** `bind.visibleWhen`。三者同名不同义，勿混用。
|
||||
> **配套 Schema：** [`../assets/schemas/skill-policy-snapshot.schema.json`](../assets/schemas/skill-policy-snapshot.schema.json)；启用块见 [`../assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。
|
||||
|
||||
相关正交轴见 [`ACTIONS.md`](ACTIONS.md)。本契约增加第六轴：**policy（当前身份允许什么）**。
|
||||
@@ -17,7 +19,7 @@
|
||||
| **L0** | 无 `policy`，或 `policy.enabled !== true` | **与今日完全一致**：不拉 Snapshot，不按身份过滤按钮/行/列 |
|
||||
| **L1** | `policy.enabled: true`，Snapshot 至少给出 Action 授权 | 数据管理展示 skill Action 前与 allowlist 求交；可选限制宿主内置能力 |
|
||||
| **L2** | 在 L1 基础上 Snapshot 带 `data.tables[table]` | 列表查询应用声明式 `rows.scope`；列按 `columns` 投影 |
|
||||
| **L3** | （预留，本契约不冻结行为） | 如**行态** `visibleWhen`、菜单级藏表、`rows.mode=delegate` 等（≠ Action 表单 `inputSchema.visibleWhen`） |
|
||||
| **L3** | （预留，本契约不冻结行为） | 如菜单级藏表、`rows.mode=delegate`、更复杂的行态策略字段等（≠ `bind.visibleWhen` 行菜单，≠ 表单 `inputSchema.visibleWhen`） |
|
||||
|
||||
**80% 技能停留 L0。** 启用 policy 的技能必须实现约定 CLI，并在写路径自行再鉴权（见 §7）。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user