feat(template): SRCP v1 standards, job_context/finish gold sample (v1.0.38, platform-kit 1.2.0)

Co-authored-by: Cursor <cursoragent@cursor.com>

SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.32
+version: 1.0.38
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
     slug: your-skill-slug
-    platform_kit_min_version: "1.0.17"
+    platform_kit_min_version: "1.2.0"
     emoji: "📦"
     category: "通用"
     developer_ids:
@@ -70,10 +70,10 @@ python {baseDir}/scripts/main.py version
 ## 运行依赖
 
 - Python 运行环境由匠厂宿主注入**共享 runtime**：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
-- 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.0.17`（`jiangchang_skill_core` 包）；**不要 vendor** `scripts/jiangchang_skill_core/`，新技能不得在仓库内保留该目录副本。
+- 公共能力来自共享 runtime 安装的 `jiangchang-platform-kit>=1.2.0`（`jiangchang_skill_core` 包）；**不要 vendor** `scripts/jiangchang_skill_core/`，新技能不得在仓库内保留该目录副本。
 - config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 `jiangchang_skill_core` import，而非技能目录副本。
 - 根目录 `requirements.txt` **只声明技能特有** Python 三方依赖；`jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
-- `metadata.openclaw.platform_kit_min_version`（当前 `1.0.17`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。
+- `metadata.openclaw.platform_kit_min_version`（当前 `1.2.0`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是**技能 pip 依赖声明。
 - Skill 代码**不要**自行 `pip install`；系统级依赖（如 VC++ Runtime）仅在 `health` / preflight 中提示用户安装。
 - `health` 使用 `collect_runtime_diagnostics` 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。
 

development/DEVELOPMENT.md

@@ -158,7 +158,7 @@ scripts/
   作用：常量、日志、路径、时间工具、通用帮助函数
   `util/logging_config.py` 是 `jiangchang_skill_core.unified_logging` 的**薄封装**，业务代码应通过它获取 logger
 
-公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.17` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
+公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics、activity/SRCP）从共享 runtime 的 `jiangchang-platform-kit>=1.2.0` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
 
 ## 3.2 开发 RPA 类 skill
 
@@ -195,7 +195,7 @@ scripts/
 技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能**特有** Python 三方依赖。
 
 - **公共依赖**（`jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等）由**宿主共享 runtime** 提供，**不要**写入技能 `requirements.txt`。
-- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.17`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
+- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.2.0`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
 - 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
 - **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
 - **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
@@ -487,7 +487,7 @@ metadata:
 
 - `cmd_run` 及主任务入口必须：`log.info("task_start ...")`、`log.info("task_log_saved ...")`；失败路径必须 `log.exception("task_failed ...")`。
 - 外部 API、兄弟技能、RPA 操作须记录**开始 / 结束 / 耗时 / 状态**（`external_call_start` / `external_call_done elapsed_ms=...`）。
-- 长任务 / RPA 须配合 `activity.emit` 或 `RpaVideoSession.add_step` 输出用户可见进度。
+- 长任务 / RPA 须配合 `activity.emit` 或 `RpaVideoSession.add_step` 输出用户可见进度；`cmd_run` 须 `job_context` + 各出口 `finish`（见 [`LOGGING.md`](LOGGING.md) §2.5）。
 - 使用 `from util.logging_config import get_skill_logger`，**不要**用 `print` 替代 logger 做排障日志。
 - **禁止**在日志中写入 password、token、cookie 等敏感明文（见 `LOGGING.md` §敏感信息红线）。
 

development/LOGGING.md

@@ -56,10 +56,13 @@ OpenClaw 技能常在客户电脑上异步执行，且大量依赖 RPA、浏览
 
 | API | 用途 |
 |-----|------|
-| `emit` | 推送用户可读进度（不写 stdout） |
+| `emit` | 推送用户可读进度（不写 stdout）；进入步骤前自动步骤闸门（SRCP） |
 | `step` | 结构化步骤 |
 | `finish` | 任务结束；**唯一**写单行 result JSON 到 stdout 的场景 |
-| `rpa_step` | RPA 专用步骤文案 |
+| `job_context` | 包裹 `cmd_run`；未捕获异常 / `JobStopped` 时自动 `finish` |
+| `rpa_step` | RPA 专用步骤：闸门 + ▶/✓ emit |
+| `interruptible_sleep` | RPA 等待（替代裸 `asyncio.sleep`），可暂停/停止 |
+| `checkpoint` | 长循环内 consult control（一般由 kit 自动调用） |
 
 **路径**：
 
@@ -72,6 +75,33 @@ OpenClaw 技能常在客户电脑上异步执行，且大量依赖 RPA、浏览
 - `emit` **不写 stdout**；长任务应持续 emit，避免用户以为卡死。
 - `finish` 才输出单行 result JSON 供宿主解析。
 - RPA 类技能：`RpaVideoSession.add_step` 会自动同步 activity（无需重复手写每步 emit）。
+- **禁止**自建 `scripts/util/progress.py` 或向 stdout 打印 `type:progress` JSON；进度只走 Run Journal。
+- 宿主通过 `{job_id}.control.json` 下发暂停/继续/停止；技能侧由 platform-kit 在步骤闸门自动处理（见 §2.5）。
+
+### 2.5 步骤控制（SRCP v1，platform-kit >= 1.2.0）
+
+**权威行为定义在本文**；platform-kit README 为实现细节参考。
+
+| 通道 | 方向 | 载体 |
+|------|------|------|
+| 进度 | 技能 → 宿主 | Run Journal（`emit` / `rpa_step` / `add_step`） |
+| 结果 | 技能 → 宿主 | `finish()` → Journal 终态 + stdout 一行 result |
+| 控制 | 宿主 → 技能 | `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.control.json` |
+
+`control.json` 的 `command` 只认：`none` | `pause` | `resume` | `stop`。
+
+技能作者三件事：
+
+1. `cmd_run` 外包 `with job_context(skill=SKILL_SLUG):`
+2. 关键步骤 `emit(...)` 或 `@rpa_step` / `video.add_step`
+3. 每个出口 `finish(status=..., message=..., skill=SKILL_SLUG, **fields)` — **不要**手写多行 JSON 结果
+
+RPA 等待用 `interruptible_sleep`，**不要**裸 `asyncio.sleep`（否则暂停响应滞后）。
+
+暂停在**步骤边界**生效（当前 `@rpa_step` / `emit` 执行完后、下一步开始前），与影刀「当前指令完成后暂停」一致。
+
+Journal 会写入 `type: lifecycle` 事件（`paused` / `resumed` / `stopping`），供宿主任务中心显示状态。
+
 
 ### 2.3 `task_logs`（任务结果审计）
 
@@ -202,7 +232,7 @@ batch_progress current=7 total=20 target_id=store-001
 
 ```python
 from util.logging_config import get_skill_logger
-from jiangchang_skill_core.activity import emit
+from jiangchang_skill_core.activity import emit, finish, job_context, rpa_step, interruptible_sleep
 
 from util.constants import SKILL_SLUG
 
@@ -210,37 +240,40 @@ log = get_skill_logger()
 
 def cmd_run(target=None, input_id=None):
     task_type = "your_task"
-    log.info(
+    with job_context(skill=SKILL_SLUG):
-        "task_start task_type=%s target_id=%s input_id=%s",
-        task_type, target, input_id,
-    )
-    emit("开始处理任务", skill=SKILL_SLUG, stage="run")
-    try:
-        ok, reason = check_entitlement(SKILL_SLUG)
-        if not ok:
-            log.warning("entitlement_failed task_type=%s reason=%s", task_type, reason)
-            return 1
-
-        t0 = time.monotonic()
-        # ... 外部调用 ...
-        elapsed_ms = int((time.monotonic() - t0) * 1000)
         log.info(
-            "external_call_done system=%s operation=%s elapsed_ms=%d status=%s",
+            "task_start task_type=%s target_id=%s input_id=%s",
-            "erp", "submit", elapsed_ms, "ok",
-        )
-
-        tlr.save_task_log(..., status="success", ...)
-        log.info("task_log_saved task_type=%s status=success", task_type)
-        emit("任务完成", skill=SKILL_SLUG, stage="run")
-        return 0
-    except Exception:
-        log.exception(
-            "task_failed task_type=%s target_id=%s input_id=%s",
             task_type, target, input_id,
         )
-        emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
+        emit("开始处理任务", skill=SKILL_SLUG, stage="run")
-        tlr.save_task_log(..., status="failed", error_msg="...", ...)
+        try:
-        return 1
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=%s reason=%s", task_type, reason)
+                finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED")
+                return 1
+
+            t0 = time.monotonic()
+            # ... 外部调用 / RPA：@rpa_step 或 video.add_step；等待用 interruptible_sleep ...
+            elapsed_ms = int((time.monotonic() - t0) * 1000)
+            log.info(
+                "external_call_done system=%s operation=%s elapsed_ms=%d status=%s",
+                "erp", "submit", elapsed_ms, "ok",
+            )
+
+            tlr.save_task_log(..., status="success", ...)
+            log.info("task_log_saved task_type=%s status=success", task_type)
+            finish(status="success", message="任务完成", skill=SKILL_SLUG)
+            return 0
+        except Exception:
+            log.exception(
+                "task_failed task_type=%s target_id=%s input_id=%s",
+                task_type, target, input_id,
+            )
+            emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
+            tlr.save_task_log(..., status="failed", error_msg="...", ...)
+            finish(status="failed", message="任务执行异常", skill=SKILL_SLUG)
+            return 1
 ```
 
 模板示范见 [`scripts/service/task_service.py`](../scripts/service/task_service.py) 的 `cmd_run`。

development/POLICY_MATRIX.md

@@ -24,6 +24,9 @@
 | POLICY-LOGGING-003 | 主任务入口须含 `log.info`/`logger.info`、`log.exception`/`logger.exception`，并写入 `save_task_log` | development/LOGGING.md | hard | 扫描 `scripts/service/task_service.py` | `tests/test_development_policy_guard.py::TestPolicyLogging003` |
 | POLICY-LOGGING-004 | 长任务 / RPA 模板须使用 Activity 或 RPA video step 输出进度 | development/LOGGING.md；development/RPA.md | hard | 扫描 `scripts/service/task_service.py` 含 `emit(` / `activity.emit` / `video.add_step` | `tests/test_development_policy_guard.py::TestPolicyLogging004` |
 | POLICY-LOGGING-005 | 交付代码不得在 logging 调用行以 `key=value` 形式记录明显敏感字段 | development/LOGGING.md；development/CONFIG.md | hard | 扫描 `scripts/**/*.py` 的 logging 调用行（不含注释） | `tests/test_development_policy_guard.py::TestPolicyLogging005` |
+| POLICY-CONTROL-001 | 不得存在 `scripts/util/progress.py` 或自建 stdout 进度模块 | development/LOGGING.md §2.5；development/RPA.md §0.1 | hard | 文件不存在检查 | `tests/test_development_policy_guard.py::TestPolicyControl001` |
+| POLICY-CONTROL-002 | `task_service.py` 须使用 `job_context(` 与 `finish(` | development/LOGGING.md §2.5、§7 | hard | 扫描 `scripts/service/task_service.py` | `tests/test_development_policy_guard.py::TestPolicyControl002` |
+| POLICY-CONTROL-003 | `scripts/service/*.py` 不得裸 `asyncio.sleep`（RPA 等待须 `interruptible_sleep`） | development/RPA.md §0.1 | hard | 扫描 service 层 Python | `tests/test_development_policy_guard.py::TestPolicyControl003` |
 
 ---
 
@@ -42,4 +45,4 @@
 | RPA 拟人操作、选择器纪律、HITL 超时 | development/RPA.md §0–§1 | 行为与 DOM 质量，无法静态扫描 |
 | adapter 四档契约测试覆盖 timeout/unauthorized 等 | development/ADAPTER.md §contract tests | 需业务实现后人工补测 |
 | `SKILL.md` / `constants.SKILL_SLUG` 一致性 | development/DEVELOPMENT.md §16 | 已有 `tests/test_skill_metadata.py` |
-| platform_kit_min_version >= 1.0.17 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` |
+| platform_kit_min_version >= 1.2.0 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` |

development/RPA.md

@@ -20,10 +20,30 @@
 | **失败存证** | 失败必截图，合规场景全程录屏，统一存 `{数据目录}/rpa-artifacts/{batch_id}/{tag}_{ts}.png` |
 | **选择器纪律** | 语义选择器优先（id/name/text/aria）；**F12 确认后再写，严禁凭记忆猜 DOM** |
 | **统一错误码** | `ERROR:REQUIRE_LOGIN` / `ERROR:CAPTCHA_NEED_HUMAN` / `ERROR:RATE_LIMITED` / `ERROR:LOGIN_TIMEOUT` 等，见下方错误码表 |
+| **步骤可控制** | 每条 RPA 指令 = 一个 `@rpa_step` 或 `video.add_step`；等待用 `interruptible_sleep`；宿主通过 control.json 暂停/继续/停止（SRCP，见 [`LOGGING.md`](LOGGING.md) §2.5） |
 | **幂等 / 断点续跑** | 批量操作记录"已处理到第几条"，崩溃后能续跑、不重复提交 |
 
 > 三端各自实现一个会话抽象 `RpaSession`（launch / login / act / screenshot / close），上层 skill 不感知是浏览器还是手机。
 
+### 0.1 步骤控制与进度（SRCP，platform-kit >= 1.2.0）
+
+- **禁止** `scripts/util/progress.py` 或 `print({"type":"progress",...})`；进度只走 `emit` / Run Journal。
+- **禁止** RPA 主路径裸 `asyncio.sleep`；用 `jiangchang_skill_core.activity.interruptible_sleep`。
+- RPA 函数用 `@rpa_step("中文步骤名")` 拆分；或在 `RpaVideoSession` 内 `video.add_step("中文步骤")`。
+- `cmd_run` 须 `with job_context(skill=SKILL_SLUG):`，所有出口 `finish(...)`。
+- 暂停在步骤边界生效；浏览器会话暂停时不强制关闭，恢复后同进程继续。
+
+```python
+from jiangchang_skill_core.activity import emit, finish, job_context, interruptible_sleep, rpa_step
+
+@rpa_step("打开登录页")
+async def open_login(page):
+    await page.goto("https://example.com")
+    await interruptible_sleep(1.5)
+```
+
+规范权威定义：[`LOGGING.md`](LOGGING.md) §2.5。金样代码：[`scripts/service/task_service.py`](../scripts/service/task_service.py)。
+
 ---
 
 ## 1. 浏览器（标准已成熟）
@@ -51,7 +71,7 @@
 6. **可以** `ignore_default_args=["--enable-automation"]`（platform-kit `launch_persistent_browser` 已处理）。
 7. **强风控平台**：优先真实点击、键盘、鼠标、地址栏、持久 profile；**不要**直接拼接搜索结果 URL 或 DOM 注入。
 
-指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.0.17**）。
+指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.2.0**）。
 
 **拟人操作**（必做）：
 
@@ -124,7 +144,7 @@ from jiangchang_skill_core.rpa import (
 from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
 ```
 
-- `RpaVideoSession` 来自 platform-kit **>= 1.0.17**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
+- `RpaVideoSession` 来自 platform-kit **>= 1.2.0**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
 - `health` 对上述资源做只读诊断，不下载、不修复。
 
 ### 1.5 真实浏览器 RPA 示例（必读）

development/RUNTIME.md

@@ -2,7 +2,7 @@
 
 ## 共享 Python Runtime
 
-**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.17` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
+**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.2.0` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
 
 技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。
 
@@ -24,7 +24,7 @@ Windows:
 
 `<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `JIANGCHANG_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
 
-## Runtime 诊断（platform-kit 1.0.17+）
+## Runtime 诊断（platform-kit 1.2.0+）
 
 `health` 命令通过 **`jiangchang_skill_core.collect_runtime_diagnostics`** 输出共享 runtime 诊断，**不在技能内重复实现**。典型字段：
 
@@ -42,7 +42,7 @@ Windows:
 - 用户实际 `.env`：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/.env`。
 - `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。
 - 配置优先级：**进程环境变量** > **用户 `.env`** > **`.env.example` 默认值**。
-- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.17`，**不得** vendored `scripts/jiangchang_skill_core/`。
+- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.2.0`，**不得** vendored `scripts/jiangchang_skill_core/`。
 
 ## media-assets / ffmpeg / 背景音乐
 

development/TESTING.md

@@ -23,7 +23,7 @@
 必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖：
 
 - CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟；
-- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.17` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
+- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.2.0` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
 - **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移；
 - 运行时：`runtime_paths` 与 **`JIANGCHANG_*` 隔离**；
 - `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)；
@@ -260,7 +260,7 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t
 
 - [ ] `requirements.txt` **不含** `jiangchang-platform-kit` / `playwright`
 - [ ] 无 `scripts/jiangchang_skill_core/` vendored 副本
-- [ ] `platform_kit_min_version` **>= 1.0.17**（`SKILL.md` + `constants.py`）
+- [ ] `platform_kit_min_version` **>= 1.2.0**（`SKILL.md` + `constants.py`）
 - [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行）
 - [ ] `config-path` 可输出用户 `.env` 路径 JSON
 - [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py`

scripts/service/task_service.py

@@ -13,10 +13,10 @@ import uuid
 from typing import Any, Dict, Optional
 
 from jiangchang_skill_core import collect_runtime_diagnostics, config, format_runtime_health_lines
-from jiangchang_skill_core.activity import emit
+from jiangchang_skill_core.activity import JobStopped, emit, finish, job_context
-from jiangchang_skill_core.rpa.video_session import RpaVideoSession
 
 from db import task_logs_repository as tlr
+from jiangchang_skill_core.rpa.video_session import RpaVideoSession
 from service.entitlement_service import check_entitlement
 from service.task_run_support import (
     _print_video_summary,
@@ -65,102 +65,127 @@ def cmd_run(target: Optional[str] = None, input_id: Optional[str] = None) -> int
     """通用任务执行入口模板。复制后请实现真实业务逻辑。"""
     log = _get_task_logger()
     task_type = "demo"
-    log.info(
-        "task_start task_type=%s target_id=%s input_id=%s",
-        task_type,
-        target,
-        input_id,
-    )
-    emit("开始处理任务", skill=SKILL_SLUG, stage="run")
-    try:
-        ok, reason = check_entitlement(SKILL_SLUG)
-        if not ok:
-            log.warning("entitlement_failed task_type=%s reason=%s", task_type, reason)
-            emit("鉴权失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="auth")
-            tlr.save_task_log(
-                task_type=task_type,
-                target_id=target,
-                input_id=input_id,
-                input_title="模板示例任务",
-                status="failed",
-                error_msg=reason,
-                result_summary=json.dumps({"stage": "auth", "error": reason}, ensure_ascii=False),
-            )
-            log.info(
-                "task_log_saved task_type=%s target_id=%s input_id=%s stage=auth status=failed",
-                task_type,
-                target,
-                input_id,
-            )
-            print(f"❌ {reason}")
-            return 1
 
-        log.info("task_run_demo_start target_id=%s input_id=%s", target, input_id)
+    with job_context(skill=SKILL_SLUG):
-        rc, video_info = asyncio.run(_run_template_demo(target, input_id))
-        log.info("task_run_demo_done target_id=%s input_id=%s status=failed", target, input_id)
-        _print_video_summary(video_info)
-
-        summary_payload = merge_video_into_result_summary(
-            {
-                "template_demo": True,
-                "target": target,
-                "input_id": input_id,
-            },
-            video_info,
-        )
-        tlr.save_task_log(
-            task_type=task_type,
-            target_id=target,
-            input_id=input_id,
-            input_title="模板示例任务",
-            status="failed",
-            error_msg="模板仓库未实现真实业务",
-            result_summary=json.dumps(summary_payload, ensure_ascii=False),
-        )
         log.info(
-            "task_log_saved task_type=%s target_id=%s input_id=%s status=failed",
+            "task_start task_type=%s target_id=%s input_id=%s",
             task_type,
             target,
             input_id,
         )
-
+        emit("开始处理任务", skill=SKILL_SLUG, stage="run")
-        print("❌ 这是模板仓库，请复制后在 scripts/service/task_service.py 中实现 cmd_run 的真实业务逻辑。")
-        return rc
-    except Exception:
-        log.exception(
-            "task_failed task_type=%s target_id=%s input_id=%s",
-            task_type,
-            target,
-            input_id,
-        )
-        emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
         try:
+            ok, reason = check_entitlement(SKILL_SLUG)
+            if not ok:
+                log.warning("entitlement_failed task_type=%s reason=%s", task_type, reason)
+                emit("鉴权失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="auth")
+                tlr.save_task_log(
+                    task_type=task_type,
+                    target_id=target,
+                    input_id=input_id,
+                    input_title="模板示例任务",
+                    status="failed",
+                    error_msg=reason,
+                    result_summary=json.dumps({"stage": "auth", "error": reason}, ensure_ascii=False),
+                )
+                log.info(
+                    "task_log_saved task_type=%s target_id=%s input_id=%s stage=auth status=failed",
+                    task_type,
+                    target,
+                    input_id,
+                )
+                finish(
+                    status="failed",
+                    message=reason,
+                    skill=SKILL_SLUG,
+                    error_code="ENTITLEMENT_DENIED",
+                    stage="auth",
+                )
+                print(f"❌ {reason}")
+                return 1
+
+            log.info("task_run_demo_start target_id=%s input_id=%s", target, input_id)
+            rc, video_info = asyncio.run(_run_template_demo(target, input_id))
+            log.info("task_run_demo_done target_id=%s input_id=%s status=failed", target, input_id)
+            _print_video_summary(video_info)
+
+            summary_payload = merge_video_into_result_summary(
+                {
+                    "template_demo": True,
+                    "target": target,
+                    "input_id": input_id,
+                },
+                video_info,
+            )
             tlr.save_task_log(
                 task_type=task_type,
                 target_id=target,
                 input_id=input_id,
                 input_title="模板示例任务",
                 status="failed",
-                error_msg="任务执行异常，详见统一日志",
+                error_msg="模板仓库未实现真实业务",
-                result_summary=json.dumps(
+                result_summary=json.dumps(summary_payload, ensure_ascii=False),
-                    {"stage": "run", "error": "unexpected_exception"},
-                    ensure_ascii=False,
-                ),
             )
             log.info(
-                "task_log_saved task_type=%s target_id=%s input_id=%s stage=run status=failed",
+                "task_log_saved task_type=%s target_id=%s input_id=%s status=failed",
                 task_type,
                 target,
                 input_id,
             )
+
+            finish(
+                status="failed",
+                message="模板仓库未实现真实业务",
+                skill=SKILL_SLUG,
+                template_demo=True,
+                target=target,
+                input_id=input_id,
+            )
+            print("❌ 这是模板仓库，请复制后在 scripts/service/task_service.py 中实现 cmd_run 的真实业务逻辑。")
+            return rc
+        except JobStopped:
+            raise
         except Exception:
             log.exception(
-                "task_log_save_failed task_type=%s target_id=%s input_id=%s",
+                "task_failed task_type=%s target_id=%s input_id=%s",
                 task_type,
                 target,
                 input_id,
             )
-        return 1
+            emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
+            try:
+                tlr.save_task_log(
+                    task_type=task_type,
+                    target_id=target,
+                    input_id=input_id,
+                    input_title="模板示例任务",
+                    status="failed",
+                    error_msg="任务执行异常，详见统一日志",
+                    result_summary=json.dumps(
+                        {"stage": "run", "error": "unexpected_exception"},
+                        ensure_ascii=False,
+                    ),
+                )
+                log.info(
+                    "task_log_saved task_type=%s target_id=%s input_id=%s stage=run status=failed",
+                    task_type,
+                    target,
+                    input_id,
+                )
+            except Exception:
+                log.exception(
+                    "task_log_save_failed task_type=%s target_id=%s input_id=%s",
+                    task_type,
+                    target,
+                    input_id,
+                )
+            finish(
+                status="failed",
+                message="任务执行异常，详见统一日志",
+                skill=SKILL_SLUG,
+                stage="run",
+            )
+            return 1
 
 
 def cmd_logs(

scripts/util/constants.py

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

tests/_support.py

@@ -35,7 +35,7 @@ def get_skill_root() -> str:
     return _SKILL_ROOT
 
 
-def platform_kit_version_patch(version: str = "1.0.17"):
+def platform_kit_version_patch(version: str = "1.2.0"):
     """Mock installed jiangchang-platform-kit version for health/diagnostics tests."""
     from unittest.mock import patch
 

tests/test_development_policy_guard.py

@@ -41,6 +41,9 @@ POLICY_IDS = (
     "POLICY-LOGGING-003",
     "POLICY-LOGGING-004",
     "POLICY-LOGGING-005",
+    "POLICY-CONTROL-001",
+    "POLICY-CONTROL-002",
+    "POLICY-CONTROL-003",
 )
 
 STRUCTURE_PATHS = (
@@ -619,6 +622,65 @@ class TestPolicyLogging005(unittest.TestCase):
         )
 
 
+class TestPolicyControl001(unittest.TestCase):
+    def test_no_util_progress_module(self) -> None:
+        skill_root = get_skill_root()
+        path = os.path.join(skill_root, "scripts", "util", "progress.py")
+        self.assertFalse(
+            os.path.isfile(path),
+            msg=_policy_msg(
+                "POLICY-CONTROL-001",
+                "development/LOGGING.md §2.5; development/RPA.md §0.1",
+                "scripts/util/progress.py must not exist",
+            ),
+        )
+
+
+class TestPolicyControl002(unittest.TestCase):
+    def test_task_service_uses_job_context_and_finish(self) -> None:
+        skill_root = get_skill_root()
+        path = os.path.join(skill_root, "scripts", "service", "task_service.py")
+        text = _read_text(path)
+        rel = _rel(skill_root, path)
+        missing: list[str] = []
+        if "job_context(" not in text:
+            missing.append("job_context(")
+        if "finish(" not in text:
+            missing.append("finish(")
+        self.assertEqual(
+            missing,
+            [],
+            msg=_policy_msg(
+                "POLICY-CONTROL-002",
+                "development/LOGGING.md §2.5、§7",
+                f"{rel} missing: " + ", ".join(missing),
+            ),
+        )
+
+
+class TestPolicyControl003(unittest.TestCase):
+    def test_service_layer_has_no_bare_asyncio_sleep(self) -> None:
+        skill_root = get_skill_root()
+        offenders: list[str] = []
+        for path in _walk_files(skill_root, "scripts/service", suffix=".py"):
+            rel = _rel(skill_root, path)
+            for lineno, line in enumerate(_read_text(path).splitlines(), 1):
+                stripped = line.strip()
+                if not stripped or stripped.startswith("#"):
+                    continue
+                if "asyncio.sleep" in stripped:
+                    offenders.append(f"{rel}:{lineno}: {stripped}")
+        self.assertEqual(
+            offenders,
+            [],
+            msg=_policy_msg(
+                "POLICY-CONTROL-003",
+                "development/RPA.md §0.1",
+                "use interruptible_sleep instead:\n" + "\n".join(offenders),
+            ),
+        )
+
+
 class TestPolicyDocs001(unittest.TestCase):
     def test_policy_matrix_exists_and_lists_policy_ids(self) -> None:
         skill_root = get_skill_root()

tests/test_docs_standards.py

@@ -172,7 +172,7 @@ class TestDocsStandards(unittest.TestCase):
         self.assertIn("--no-sandbox", text)
         self.assertIn("--disable-blink-features=AutomationControlled", text)
         self.assertIn("RpaVideoSession", text)
-        self.assertIn("1.0.17", text)
+        self.assertIn("1.2.0", text)
 
     def test_rpa_md_forbids_rpa_helpers_import(self) -> None:
         text = self._read("development/RPA.md")

tests/test_platform_import.py

@@ -83,16 +83,16 @@ class TestPlatformImportSource(unittest.TestCase):
             )
         )
 
-    def test_platform_kit_min_version_is_1_0_14(self) -> None:
+    def test_platform_kit_min_version_is_1_2_0(self) -> None:
         from jiangchang_skill_core import version_ge
         from util.constants import PLATFORM_KIT_MIN_VERSION
 
-        self.assertEqual(PLATFORM_KIT_MIN_VERSION, "1.0.17")
+        self.assertEqual(PLATFORM_KIT_MIN_VERSION, "1.2.0")
 
         md_path = os.path.join(get_skill_root(), "SKILL.md")
         with open(md_path, encoding="utf-8") as f:
             md = f.read()
-        self.assertEqual(_parse_platform_kit_min_version(md), "1.0.17")
+        self.assertEqual(_parse_platform_kit_min_version(md), "1.2.0")
 
         req_path = os.path.join(get_skill_root(), "requirements.txt")
         with open(req_path, encoding="utf-8") as f:

tests/test_template_runtime_standard.py

@@ -34,7 +34,7 @@ FORBIDDEN_PHRASES = (
 
 POSITIVE_MARKERS = (
     "jiangchang-platform-kit",
-    "1.0.17",
+    "1.2.0",
     "共享 runtime",
 )