Codify Skill Action sync/async and task-center gold standards (v1.0.40)

references/ACTIONS.md

@@ -2,6 +2,8 @@
 
 本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。
 
+**权威运行时契约（sync/async、任务中心、编排范式）见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。**
+
 **边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。
 
 ## 模板严格规范 vs 宿主向后兼容
@@ -21,6 +23,7 @@ Action 是**可选能力**：
 
 - 没有宿主直接操作需求的技能，**可以不提供** `actions.json`。
 - 需要出现在**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中的技能，**必须**提供 `assets/actions.json`。
+- **含浏览器 RPA / 长耗时任务**的技能：**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 action（见 `POLICY-SKILL-ACTION-001`）。
 
 ## 文件位置
 
@@ -49,11 +52,12 @@ Action 是**可选能力**：
 | 层级 | 稳定字段 / 能力 |
 |------|----------------|
 | 顶层 | `schemaVersion`、`skill`、`actions` |
-| action | `id`、`label`、`description`、`placements`、`entrypoint`；可选 `inputSchema`、`confirmation` |
+| action | `id`、`label`、`description`、`placements`、`entrypoint`；可选 `inputSchema`、`confirmation`、**`executionProfile`** |
 | entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
 | placements | `toolbar`、`skill-detail`、`agent`、`cron` |
 | inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive` |
 | confirmation | `{ "message": "..." }` |
+| **executionProfile** | `"sync"` \| `"async"`（**模板要求显式写出**） |
 
 ## 预留能力（当前不可当作已实现能力）
 
@@ -82,6 +86,18 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 完整子命令定义见 [`scripts/cli/app.py`](../scripts/cli/app.py)。
 
+### `executionProfile`（sync / async）
+
+| 值 | 宿主行为 | 任务中心 |
+|----|----------|----------|
+| `sync` | 内联等待 CLI（默认约 30s） | 不进 |
+| `async` | 后台 Job，立即返回 `jobId` | **进入** |
+| 省略 | 宿主默认按 **async** | 进入 |
+
+- **RPA / 浏览器 / 长耗时** → 必须 `"async"`，并建议加 `confirmation`。
+- **数据管理 toolbar** → 只挂 **async** action。
+- 完整规则见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
+
 ### CLI 输出契约
 
 技能 CLI 必须：
@@ -108,9 +124,9 @@ HINT: <next step>
 
 | 值 | 含义 |
 |----|------|
-| `toolbar` | 数据管理第一排技能按钮 |
+| `toolbar` | 数据管理第一排技能按钮（**仅 async**） |
 | `skill-detail` | 技能详情或技能市场详情页 |
-| `agent` | Agent 可直接调用 |
+| `agent` | Agent 可直接调用（`run_skill_action`） |
 | `cron` | 定时任务可直接调用 |
 
 **预留能力（当前宿主可能尚未完整支持，模板示例请勿使用）：**
@@ -120,7 +136,15 @@ HINT: <next step>
 | `row` | 行内操作（未来扩展） |
 | `batch` | 批量操作（未来扩展） |
 
-可以在 manifest 中作为未来扩展值定义，但不要让技能作者误以为 `row` / `batch` 已经完整可用。
+### Action 类型 × placements 矩阵
+
+| 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 | **必须** |
 
 ## inputSchema 与参数表单
 
@@ -152,6 +176,20 @@ HINT: <next step>
 }
 ```
 
+批量 pick 参数约定（有队列表时）：
+
+```json
+{
+  "pickCount": {
+    "type": "number",
+    "title": "处理数量",
+    "description": "从队列选取 pending 记录条数",
+    "default": 1,
+    "minimum": 1
+  }
+}
+```
+
 约定：
 
 - `boolean` 在宿主中渲染为开关
@@ -166,23 +204,32 @@ HINT: <next step>
 ## 风险与入口配置
 
 - 查询、诊断、版本检查可以放到 `skill-detail` 或 `agent`
-- 低风险、常用动作才考虑放 `toolbar`
+- 低风险、常用动作才考虑放 `toolbar`（且须为 async）
 - 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
 - 有副作用的动作应添加 `confirmation.message`
 - 高风险动作不应默认出现在 `toolbar`
 - 含 `sensitive` 参数的 action 不应放入 `toolbar` 或 `cron`，除非有明确安全设计
 - 不要为了「按钮多」而暴露所有 CLI 子命令
 - 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义
+- **Agent 必须用 `run_skill_action`，禁止 `exec` 直跑长任务 CLI**（见 `SKILL_ACTION_RUNTIME.md`）
 
 ## 模板示例 action 一览
 
-| id | CLI | placements | 说明 |
-|----|-----|------------|------|
-| `health` | `health` | skill-detail, agent | 运行环境检查 |
-| `version` | `version` | skill-detail | 版本 JSON |
-| `config-path` | `config-path` | skill-detail | 配置路径 JSON |
+| id | CLI | executionProfile | placements | 说明 |
+|----|-----|------------------|------------|------|
+| `health` | `health` | sync | skill-detail, agent | 运行环境检查 |
+| `version` | `version` | sync | skill-detail | 版本 JSON |
+| `config-path` | `config-path` | sync | skill-detail | 配置路径 JSON |
 
-复制为新技能后，请按业务需要增删 action；不需要宿主入口时可删除整个 `actions.json`。
+业务技能复制后，按需增加例如：
+
+| 模式 | id 示例 | executionProfile | placements |
+|------|---------|------------------|------------|
+| 单条 RPA | `your-run` | async | agent, skill-detail |
+| 队列 pick | `your-run-pick` | async | toolbar, cron, agent |
+| 统计 | `your-stats` | sync | skill-detail, agent |
+
+不需要宿主入口时可删除整个 `actions.json`（无 RPA 长任务时）。
 
 ## 与宿主 API（参考）