chore: auto release commit (2026-07-14 11:56:45)

2026-07-14 11:56:46 +08:00
parent a7baba7210
commit af7a43a702
17 changed files with 1239 additions and 123 deletions
--- a/references/ACTIONS.md
+++ b/references/ACTIONS.md
@@ -2,7 +2,7 @@

 本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。

-**权威运行时契约（sync/async、任务中心、编排范式）见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。**
+**权威运行时契约（sync/async、任务中心、单内核编排）见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。**

 **边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。

@@ -11,7 +11,7 @@
 | 角色 | 定位 |
 |------|------|
 | **skill-template** | 新技能推荐的**严格规范**：必填字段、明确类型、`additionalProperties: false` |
-| **宿主运行时** | **向后兼容**的历史 manifest 解析器：可能接受部分缺省字段（如 `description`、`placements`、`entrypoint.args`、input property `type`） |
+| **宿主运行时** | **向后兼容**的历史 manifest 解析器：可能接受部分缺省字段（如 `description`、`placements`、`entrypoint.args`、缺失的 `bind.tables`） |

 **新技能不应依赖宿主缺省行为。** 复制模板后按 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json) 与本文完整填写 manifest。

@@ -47,29 +47,73 @@ Action 是**可选能力**：

 模板最小示例见 [`assets/actions.json`](../assets/actions.json)；JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。

+## 五职责正交（必读）
+
+| 字段 / 层 | 只决定什么 | 不决定什么 |
+|-----------|------------|------------|
+| **`placements`** | Action **出现在哪里**（toolbar / cron / agent / skill-detail …） | 不决定 sync/async |
+| **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
+| **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口 |
+| **`entrypoint`** | 实际执行哪个 CLI 命令与参数 | 不写业务逻辑 |
+| **domain service** | **真正完成什么业务** | 不感知 toolbar / cron / agent 来源 |
+
+一个业务能力通常只定义**一个** Action，用 `placements` 同时挂到多个入口。不要拆成 `sync-records-toolbar` / `sync-records-cron` 等副本，除非语义确实不同；即便拆分，也必须调用同一个领域业务内核。
+
 ## Phase 1 当前稳定支持（新技能应只使用这些）

 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions` |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`；可选 `inputSchema`、`confirmation`、**`executionProfile`** |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`、**`executionProfile`（必填）**；可选 `inputSchema`、`confirmation`、**`bind`** |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`skill-detail`、`agent`、`cron` |
+| **bind** | `{ "tables": ["business_table"] }`（见下节） |
 | inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive` |
 | confirmation | `{ "message": "..." }` |
-| **executionProfile** | `"sync"` \| `"async"`（**模板要求显式写出**） |
+| **executionProfile** | `"sync"` \| `"async"`（**必须显式写出**，禁止依赖缺省） |
+
+## `bind.tables`（表级绑定）
+
+```json
+{
+  "bind": {
+    "tables": ["business_table"]
+  }
+}
+```
+
+规则：
+
+- `bind` 为 object，`additionalProperties: false`；当前只允许 `tables`。
+- `tables` 非空数组、元素唯一、英文 **snake_case**、不得为空字符串。
+- **`placements` 含 `toolbar` 时必须显式声明非空 `bind.tables`**（模板 Schema `if/then` + 自动测试强制）。
+- 表名须真实存在于技能 SQLite 与 `_jiangchang_tables`。
+- 希望出现在多张表时，显式列出所有表；**不要**依赖「无 bind 则全表展示」——那是宿主对**旧技能**的兼容，不是新技能标准。
+- 本阶段**不**扩展 `selection` / `inputMapping` / `columns` / row binding / concurrency / locks。
+
+默认模板 `actions.json` 仅含 `health` / `version` / `config-path`，不放在 toolbar，故无需 `bind` 示例污染默认 manifest。业务示例：
+
+```json
+{
+  "id": "sync-records",
+  "label": "同步记录",
+  "description": "从外部来源同步到技能本地数据库，不生成导出文件。",
+  "placements": ["toolbar", "cron", "agent", "skill-detail"],
+  "executionProfile": "async",
+  "bind": { "tables": ["business_records"] },
+  "entrypoint": { "type": "cli", "command": "sync-records", "args": [] }
+}
+```

 ## 预留能力（当前不可当作已实现能力）

-以下在宿主共享类型或 Schema 枚举中可能出现，但 **Phase 1 Runtime 尚未完整支持**，**新模板示例不得使用**：
-
 | 类别 | 预留项 | 说明 |
 |------|--------|------|
-| placements | `row`、`batch` | 行内 / 批量入口，未来扩展 |
-| action 字段 | `bind`、`concurrency`、`locks` | 绑定、并发与锁控制，宿主后续实现 |
-| inputSchema | `array`、nested `object`、`oneOf` 等 | 复杂表单与联合类型，不属于当前推荐模板范围 |
+| placements | `row`、`batch` | 行内 / 批量入口，未来扩展；新技能示例不得使用 |
+| action 字段 | `concurrency`、`locks` | 并发与锁控制，未稳定开放 |
+| inputSchema | `array`、nested `object`、`oneOf` 等 | 复杂表单，不属于当前推荐范围 |

-可以在文档或 Schema 枚举中保留这些值供未来对齐，但不要让技能作者误以为它们已经可执行。
+`bind` **不是**保留字段；已作为 Phase 1 表级绑定正式能力。

 ## 执行模型

@@ -86,17 +130,20 @@ python {skill_root}/scripts/main.py <command> <args...>

 完整子命令定义见 [`scripts/cli/app.py`](../scripts/cli/app.py)。

-### `executionProfile`（sync / async）
+### `executionProfile`（仅 sync / async）
+
+模板与新技能**只允许**这两种值；禁止发明 `auto` / `background` / `deferred` 等第三种模式。

 | 值 | 宿主行为 | 任务中心 |
 |----|----------|----------|
-| `sync` | 内联等待 CLI（默认约 30s） | 不进 |
-| `async` | 后台 Job，立即返回 `jobId` | **进入** |
-| 省略 | 宿主默认按 **async** | 进入 |
+| `sync` | 调用方等待结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 不进 |
+| `async` | 宿主创建后台 Job，立即返回 `jobId`；用 `emit` / `checkpoint` / `finish` 报告进度与终态 | **进入** |

- **RPA / 浏览器 / 长耗时** → 必须 `"async"`，并建议加 `confirmation`。
- **数据管理 toolbar** → 只挂 **async** action。
- 完整规则见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
+合法组合（全部允许）：`sync|async` × `toolbar|cron|agent|skill-detail`。
+
+经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，建议用 `async`。
+
+直接执行 CLI 时，终端自然等待进程结束；宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。

 ### CLI 输出契约

@@ -109,7 +156,6 @@ python {skill_root}/scripts/main.py <command> <args...>
 - 对用户可处理的问题提供 `HINT`
 - 不依赖 Agent 连续对话才能完成
 - 不自行实现宿主任务中心
- 长时间任务允许异步执行，由宿主任务中心承载状态
 - 不在 CLI 中硬编码宿主安装目录
 - 不直接依赖某个具体 UI 页面

@@ -124,27 +170,37 @@ HINT: <next step>

 | 值 | 含义 |
 |----|------|
-| `toolbar` | 数据管理第一排技能按钮（**仅 async**） |
+| `toolbar` | 数据管理第一排技能按钮（须配合 `bind.tables`） |
 | `skill-detail` | 技能详情或技能市场详情页 |
 | `agent` | Agent 可直接调用（`run_skill_action`） |
 | `cron` | 定时任务可直接调用 |

-**预留能力（当前宿主可能尚未完整支持，模板示例请勿使用）：**
+**预留（模板示例请勿使用）：** `row`、`batch`。

-| 值 | 说明 |
-|----|------|
-| `row` | 行内操作（未来扩展） |
-| `batch` | 批量操作（未来扩展） |
+### Action 类型 × placements（常见示例，不是限制）

-### Action 类型 × placements 矩阵
+下表只表示**常见用法示例**。实际 `placements` 以 manifest 配置为准；**`sync` / `async` 不影响展示入口**。

-| Action 类型 | executionProfile | 典型 placements | confirmation |
-|-------------|------------------|-----------------|--------------|
+| Action 类型 | 常见 executionProfile | 常见 placements | confirmation |
+|-------------|----------------------|-----------------|--------------|
 | health / version / config-path | sync | skill-detail, agent | 无 |
 | 统计 / 只读查询 | sync | skill-detail, agent | 无 |
-| 导入 / 重置 | sync | skill-detail, agent | 可选 |
-| 单条副作用 RPA | async | agent, skill-detail | **必须** |
-| 批量顺序 pick RPA | async | **toolbar**, cron, agent | **必须** |
+| 数据同步（外源 → 本地库） | sync 或 async | toolbar + cron + agent + skill-detail（按需） | 可选 |
+| 导入 / 重置 | sync 或 async | skill-detail, agent | 可选 |
+| 单条副作用 RPA | async（建议） | agent, skill-detail | **建议** |
+| 批量顺序 pick RPA | async（建议） | toolbar, cron, agent | **建议** |
+
+## 同步数据 vs 导出当前表 vs 特殊业务报告
+
+不要混用「导出」一词：
+
+| 能力 | 语义 | 谁负责 |
+|------|------|--------|
+| **同步数据**（sync / refresh / collect） | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
+| **导出当前数据表** | 技能本地数据库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
+| **生成特殊业务报告** | 多表合并、特殊排版或附加计算 | 仅当系统导出无法满足时，才提供独立 `export-*` Action |
+
+同步型 Action 默认：读外部数据、写技能自己的库、**不**生成 CSV/Excel/JSON 文件、不重复实现宿主表导出。兼容旧 export 命令若需要刷新数据，必须调用同一个 sync 业务内核。通用同步语义见 [`SCHEMA.md`](SCHEMA.md) 与 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。

 ## inputSchema 与参数表单

@@ -204,14 +260,15 @@ HINT: <next step>
 ## 风险与入口配置

 - 查询、诊断、版本检查可以放到 `skill-detail` 或 `agent`
- 低风险、常用动作才考虑放 `toolbar`（且须为 async）
+- 低风险、常用动作才考虑放 `toolbar`（须 `bind.tables`；executionProfile 按耗时自选）
 - 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
 - 有副作用的动作应添加 `confirmation.message`
 - 高风险动作不应默认出现在 `toolbar`
 - 含 `sensitive` 参数的 action 不应放入 `toolbar` 或 `cron`，除非有明确安全设计
 - 不要为了「按钮多」而暴露所有 CLI 子命令
- 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义
+- 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义，并复用同一业务内核
 - **Agent 必须用 `run_skill_action`，禁止 `exec` 直跑长任务 CLI**（见 `SKILL_ACTION_RUNTIME.md`）
+- **禁止**按 `source=toolbar/cron/agent/skill-detail` 在业务代码中分叉业务行为

 ## 模板示例 action 一览

@@ -223,11 +280,12 @@ HINT: <next step>

 业务技能复制后，按需增加例如：

-| 模式 | id 示例 | executionProfile | placements |
-|------|---------|------------------|------------|
-| 单条 RPA | `your-run` | async | agent, skill-detail |
-| 队列 pick | `your-run-pick` | async | toolbar, cron, agent |
-| 统计 | `your-stats` | sync | skill-detail, agent |
+| 模式 | id 示例 | executionProfile | placements | bind |
+|------|---------|------------------|------------|------|
+| 数据同步 | `sync-records` | async 或 sync | toolbar, cron, agent, skill-detail | 必填 tables |
+| 单条 RPA | `your-run` | async（建议） | agent, skill-detail | 按需 |
+| 队列 pick | `your-run-pick` | async（建议） | toolbar, cron, agent | 有 toolbar 则必填 |
+| 统计 | `your-stats` | sync | skill-detail, agent | 无 |

 不需要宿主入口时可删除整个 `actions.json`（无 RPA 长任务时）。