docs(actions): align executionProfile mental model with host default sync (v1.0.49)

CHANGELOG.md

@@ -9,6 +9,10 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.49
+
+- 明确 Skill Action 心智：默认按 sync；仅长任务 / RPA 显式 async 进任务中心；匠厂宿主省略 `executionProfile` 时按 sync；新技能仍须显式声明
+
 ## 1.0.48
 
 - 新增配置注释硬门禁 `POLICY-CONFIG-004`：`.env.example` 每个配置项必须有中文行头与行尾说明，禁止开发文档指向，测试不通过则无法发布

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.48
+version: 1.0.49
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -27,7 +27,7 @@ allowed-tools:
 - **单业务内核、多入口**：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 `source` 分叉业务行为。
 - **`placements`**：只决定 Action **出现在哪里**（toolbar / cron / agent / skill-detail）。
 - **`bind.tables`**：只决定数据管理出现在哪些表；含 `toolbar` 时**必须**显式非空绑定。
-- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**；每个 Action **必须**显式写 `sync` 或 `async`。
+- **`executionProfile`**：只决定执行方式——`sync` 当场返回结果，`async` 进**任务中心**。与 placements / 入口**无关**。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action **仍必须**显式写 `sync` 或 `async`。
 - **同步数据**写技能本地库、不生成导出文件；**导出当前表**由宿主数据管理负责；特殊业务报告才另做 `export-*`。
 - **准备 vs 执行（适用则拆）**：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。
 

development/SKILL_ACTION_RUNTIME.md

@@ -23,16 +23,23 @@
 4. **长耗时建议 async** — 开浏览器、RPA、HTTP 大文件下载等建议 `executionProfile: "async"`，进**任务中心**；这是对**方法**的选择，**不**限制可以出现在哪些 placement / 入口。
 5. **Agent：短 CLI / 长 Action** — 短查询可用共享 Python bash CLI；长任务 / RPA **禁止** `exec` + `process poll`，必须 `run_skill_action`。
 6. **进度走 Journal** — `emit` / `video.add_step` → Run Journal；UI / Skill Run Card / 任务中心展示；**不靠 stdout 流**。
-7. **显式声明 `executionProfile`** — 每个 action **必须**写明 `sync` 或 `async`；禁止依赖宿主缺省；禁止第三种模糊模式（`auto` / `background` / `deferred` 等）。
+7. **显式声明 `executionProfile`** — 心智默认 sync、例外才 async；每个 action **必须**写明 `sync` 或 `async`；宿主省略时按 sync，新技能仍禁止赌缺省；禁止第三种模糊模式（`auto` / `background` / `deferred` 等）。
 
 ---
 
 ## 2. `executionProfile`：sync vs async
 
+### 心智（先记住）
+
+1. **默认按 sync 想**：多数 Action（诊断、统计、入队、秒级查询）是短调用，当场返回，**不进**任务中心。
+2. **只有特殊情况标 async**：开浏览器 / RPA / 长下载 / 需要进度·暂停·停止时，才显式 `"executionProfile": "async"`，进入**任务中心**。
+3. **匠厂宿主**：`actions.json` 若**省略** `executionProfile`，按 **`sync`** 处理（不再把漏写当成进任务中心）。
+4. **新技能仍须显式写出** `sync` 或 `async`（模板 Schema / `POLICY-SKILL-ACTION-002` 硬门禁），禁止赌宿主缺省；显式写出也便于人和 AI 阅读。
+
 | 值 | 宿主行为 | 超时 | 任务中心 |
 |----|----------|------|----------|
-| **`sync`** | 调用方等待 CLI 结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 默认约 **30s**（`SKILL_ACTION_SYNC_TIMEOUT_MS`） | ❌ 不进 |
-| **`async`** | 后台 spawn Job，立即返回 `jobId`；`emit` / `checkpoint` / `finish`；长任务应支持暂停/停止/取消检查 | Job 本身无默认墙钟上限 | ✅ 进入 |
+| **`sync`**（或省略时的宿主缺省） | 调用方等待 CLI 结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 默认约 **30s**（`SKILL_ACTION_SYNC_TIMEOUT_MS`） | ❌ 不进 |
+| **`async`**（须显式声明） | 后台 spawn Job，立即返回 `jobId`；`emit` / `checkpoint` / `finish`；长任务应支持暂停/停止/取消检查 | Job 本身无默认墙钟上限 | ✅ 进入 |
 
 直接执行 CLI：终端等待进程结束。宿主经 Action 调用同一 CLI：再按 `executionProfile` 分流。技能不得自建任务中心。
 
@@ -47,7 +54,7 @@
 
 合法：`sync|async` × `toolbar|cron|agent|skill-detail`。
 
-历史说明：旧文档曾错误地把数据管理按钮入口与异步执行方式绑死。该约束**已废止**；模板测试与 Schema **不得**再建立「入口位置决定 sync/async」一类硬耦合。宿主省略 `executionProfile` 时的兼容行为以宿主实现为准，**新技能不得依赖**。
+历史说明：旧文档曾错误地把数据管理按钮入口与异步执行方式绑死。该约束**已废止**；模板测试与 Schema **不得**再建立「入口位置决定 sync/async」一类硬耦合。旧版宿主曾「省略 → async」；**当前宿主为「省略 → sync」**。新技能仍须显式声明，不得依赖省略行为。
 
 ---
 

references/ACTIONS.md

@@ -161,16 +161,16 @@ python {skill_root}/scripts/main.py <command> <args...>
 
 ### `executionProfile`（仅 sync / async）
 
-模板与新技能**只允许**这两种值；每个 Action **必须**显式写出；禁止发明 `auto` / `background` / `deferred`；**禁止**依赖宿主「省略字段时的兼容默认」。
+**心智**：多数 Action 按 **sync**（短调用、不进任务中心）；只有长耗时 / RPA / 需进度控制时才标 **async**。匠厂宿主若**省略**该字段，按 **sync** 处理；模板与新技能仍要求**每个 Action 显式写出** `sync` 或 `async`，禁止发明 `auto` / `background` / `deferred`，也禁止赌省略行为。
 
 | 值 | 宿主行为 | 任务中心 |
 |----|----------|----------|
-| `sync` | 调用方等待结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 不进 |
-| `async` | 宿主创建后台 Job，立即返回 `jobId`；用 `emit` / `checkpoint` / `finish` 报告进度与终态 | **进入** |
+| `sync`（或省略时的宿主缺省） | 调用方等待结束，直接返回结构化结果或结构化错误；**不**创建后台 Job | 不进 |
+| `async`（须显式声明） | 宿主创建后台 Job，立即返回 `jobId`；用 `emit` / `checkpoint` / `finish` 报告进度与终态 | **进入** |
 
 合法组合（全部允许）：`sync|async` × `toolbar|cron|agent|skill-detail`。
 
-经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，用 `async`。
+经验建议（**不是** placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，用 `async`；其余默认写 `sync`。
 
 直接执行短 CLI 时，终端自然等待进程结束。宿主通过 Action 调用同一 CLI 时，再按 `executionProfile` 决定同步等待还是建 Job。技能**不得**自行实现第二套任务中心或后台队列。
 

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.48"
+SKILL_VERSION = "1.0.49"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.0"