docs: deposit selection summary and bind.labelColumn contract
All checks were successful
技能自动化发布 / release (push) Successful in 5s
All checks were successful
技能自动化发布 / release (push) Successful in 5s
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`（行内/批量预填，见下节） |
|
||||
| **bind** | `{ "tables": ["business_table"] }`；可选 `inputMapping`、`columnMapping`、**`labelColumn`**（行内/批量预填与选择摘要标签，见下节） |
|
||||
| **policy** | 可选；`enabled` + `entrypoint`（推荐 `policy` CLI）；见 POLICY.md。未启用 = L0 |
|
||||
| **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`（含 `file` / `directory` 等）；可选 **`pathRoot`**（file/directory 起始目录，相对技能数据根）；可选 **`visibleWhen`**（字段条件显隐，见专节） |
|
||||
@@ -132,15 +132,25 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
|
||||
规则：
|
||||
|
||||
- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`。
|
||||
- `bind` 为 object，`additionalProperties: false`；当前允许 `tables`（必填键当存在 bind 时）与可选 `inputMapping`、`columnMapping`、**`labelColumn`**。
|
||||
- `tables` 非空数组、元素唯一、英文 **snake_case**、不得为空字符串。
|
||||
- **`placements` 含 `toolbar` 时必须显式声明非空 `bind.tables`**（模板 Schema `if/then` + 自动测试强制）。
|
||||
- `row` / `batch` **建议**同样声明 `bind.tables`，避免在无关表上露出按钮；未声明时宿主可能按兼容逻辑在更多表上展示。
|
||||
- 表名须真实存在于技能 SQLite 与 `_jiangchang_tables`。
|
||||
- 希望出现在多张表时，显式列出所有表；**不要**依赖「无 bind 则全表展示」——那是宿主对**旧技能**的兼容，不是新技能标准。
|
||||
- **`inputMapping`（可选）**：把行/勾选映射到 `inputSchema` 字段，例如 `"leadId": "$row.$pk"`、`"ids": "$selection.ids"`。适合 `row` / `batch`。宿主仍会提交这些字段；可用 `inputSchema.properties.*.readOnly: true` 在表单中只读展示。
|
||||
- **`columnMapping`（可选）**：把 inputSchema 属性名映射到物理列名，供表单复用列展示名 / lookup。
|
||||
- **`labelColumn`（可选）**：物理列名，供数据管理 Action 弹层「已选择」摘要展示 `#id + 标签`。**仅影响展示，不改变 CLI/提交 payload，也不决定业务是否跳过某些状态。** 省略时宿主用常见列名启发（如 `title` / `name` / `nickname` 等）；再没有则只显示编号。列名不常见、或启发会选错列时再显式声明。
|
||||
- `concurrency` / `locks` 仍未稳定，**不要**写入新技能 manifest。
|
||||
|
||||
### 数据管理：选择摘要（宿主默认能力）
|
||||
|
||||
当用户在数据管理**勾选行**后打开 `confirm` / `form` 弹层时，宿主会展示通用 **「已选择 · N 条」** 摘要（`#主键` + 可读标签；超过约 3 条可展开查看全部）。这是**宿主 UX**，对所有技能默认生效：
|
||||
|
||||
- **技能零改动即可受益**；不要在 `confirmation.message` 里手写「已选 id 列表」，也不要为了面板去拼业务状态跳过文案。
|
||||
- 摘要与执行解耦：勾选了谁由 UI 说明；**实际处理哪些行、是否跳过某些状态，仍由技能 CLI / domain service 决定**。
|
||||
- 需要稳定标签列时，在 `bind` 上声明可选 `labelColumn`（见上）。示例：[`assets/examples/selection-label-column.action.example.json`](../assets/examples/selection-label-column.action.example.json)。
|
||||
|
||||
## `replaces`（可选：接管默认新增 / 编辑 / 删除 / 导入）
|
||||
|
||||
有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写 SQLite。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
|
||||
@@ -330,8 +340,8 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
| 值 | 数据管理体验 | 典型场景 |
|
||||
|----|--------------|----------|
|
||||
| `direct` | **一点即跑**，无弹窗 | 打开目录、打开浏览器、无参只读、行内主键已映射 |
|
||||
| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`） | 处理待发送、删除前确认、有副作用但无可编辑入参 |
|
||||
| `form` | 完整参数表单（现状默认路径） | 导入、查询条件、需用户改写的字段 |
|
||||
| `confirm` | 轻量确认弹窗（无参数区；文案优先 `confirmation.message`；有勾选时宿主展示「已选择」摘要） | 处理待发送、删除前确认、有副作用但无可编辑入参 |
|
||||
| `form` | 完整参数表单（有勾选时同样展示「已选择」摘要） | 导入、查询条件、需用户改写的字段 |
|
||||
| `auto` / 省略 | 宿主推断：有**可编辑**参数 → `form`；仅有 `confirmation` → `confirm`；否则 → `direct` | 旧技能兼容；新技能建议显式写出 |
|
||||
|
||||
```json
|
||||
|
||||
Reference in New Issue
Block a user