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>
chore: auto release commit (2026-07-11 15:57:40)
2026-07-12 12:27:44 +08:00 · 2026-07-11 15:57:43 +08:00
18 changed files with 402 additions and 143 deletions
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,4 @@
-# ── 运行模式 / adapter 档位（见 references/ADAPTER.md）──
+# ── 运行模式 / adapter 档位（见 development/ADAPTER.md）──
 OPENCLAW_TEST_TARGET=mock              # mock | simulator_rpa | real_api | real_rpa

 # ── 目标系统 ──
@@ -12,7 +12,7 @@ OPENCLAW_BROWSER_HEADLESS=0            # 0=有头(默认) 1=无头(CI)
 OPENCLAW_PLAYWRIGHT_STEALTH=1          # 1=开启反检测指纹(默认)

 # ── 存证 ──
-OPENCLAW_RECORD_VIDEO=1
+OPENCLAW_RECORD_VIDEO=0                # 0=默认不录屏；1=启用录屏+字幕+旁白+背景音+MP4
 OPENCLAW_ARTIFACTS_ON_FAILURE=1        # 1=失败截图(默认)

 # ── 节流 / 超时 ──
--- a/SKILL.md
+++ b/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）。

--- a/development/CONFIG.md
+++ b/development/CONFIG.md
@@ -31,7 +31,7 @@ OPENCLAW_BROWSER_HEADLESS=0            # 0=有头(默认) 1=无头(CI)
 OPENCLAW_PLAYWRIGHT_STEALTH=1          # 1=开启反检测指纹(默认)

 # ── 录屏与失败存证 ──
-OPENCLAW_RECORD_VIDEO=1                # 1=录屏+字幕+旁白+背景音+MP4（RPA 默认开，见 RPA.md）
+OPENCLAW_RECORD_VIDEO=0                # 0=默认不录屏；1=启用录屏+字幕+旁白+背景音+MP4（见 RPA.md）
 OPENCLAW_ARTIFACTS_ON_FAILURE=1        # 1=失败截图(默认)

 # ── 节流 / 超时 ──
@@ -42,6 +42,13 @@ HUMAN_WAIT_TIMEOUT=180                 # 滑块/验证码/2FA 等人工超时(

 **业务专属配置必须带技能前缀**（如 `DEMO_XXX`、`MY_SKILL_XXX`），**不要污染全局命名空间**（禁止 `SCRAPE_1688_*`、`RECEIVE_ORDER_*` 等跨技能前缀写入模板）。

+### 录屏开关（`OPENCLAW_RECORD_VIDEO`）
+
+- **模板默认 `OPENCLAW_RECORD_VIDEO=0`**，降低本地开发 / 调试成本（不启 ffmpeg、不生成 MP4）。
+- 需要**生产留证、合规记录、客户现场复现或排障**时，可在用户 `.env` 或进程环境变量中设为 `OPENCLAW_RECORD_VIDEO=1`。
+- **默认关闭不代表可以删除录屏接入**：RPA / 长任务代码仍须保留 `RpaVideoSession`、`video.add_step` 与 video artifact 写入 `result_summary`（见 `RPA.md` §5.3）。
+- **已落盘的用户 `.env` 不会被模板整体覆盖**；老用户保留原值，技能升级时仅通过 `merge_missing_env_keys` **追加** `.env.example` 中新增的 key。
+
 ## 🚫 红线：敏感信息不进 `.env`

 `.env` 只放**非敏感运行参数**（模式、地址、开关、超时、账号标识）。密码、密钥、动态口令、token——
--- a/development/DEVELOPMENT.md
+++ b/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` §敏感信息红线）。

--- a/development/LOGGING.md
+++ b/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`（任务结果审计）

@@ -88,11 +118,13 @@ OpenClaw 技能常在客户电脑上异步执行，且大量依赖 RPA、浏览

 **来源**：`RpaVideoSession`、`rpa-artifacts/` 目录

+- video artifact 是**标准可启用能力**，**不保证默认每次生成 MP4**（模板默认 `OPENCLAW_RECORD_VIDEO=0`）。
+- **`OPENCLAW_RECORD_VIDEO=0`**：不生成最终录屏，但 RPA / 长任务仍须保留 `RpaVideoSession`、`video.add_step` 与 Activity 进度同步。
+- **`OPENCLAW_RECORD_VIDEO=1`**：`result_summary` 应包含 `video_path`、`raw_video`、`video_log`、`video_warnings` 等字段；CLI 可打印录屏路径与诊断。
 - 用户可见的中文步骤（「打开登录页」「点击提交」）。
- 录屏 MP4、`video_log`（ffmpeg 诊断）。
- 失败截图：`{数据目录}/rpa-artifacts/{batch_id}/...`
+- 失败截图：`{数据目录}/rpa-artifacts/{batch_id}/...`（受 `OPENCLAW_ARTIFACTS_ON_FAILURE` 控制，默认开）

-详见 [`RPA.md`](RPA.md) §失败存证与录屏标准。
+详见 [`RPA.md`](RPA.md) §5 存证与录屏规范。

 ---

@@ -200,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

@@ -208,37 +240,40 @@ log = get_skill_logger()

 def cmd_run(target=None, input_id=None):
    task_type = "your_task"
-    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)
-            return 1
-
-        t0 = time.monotonic()
-        # ... 外部调用 ...
-        elapsed_ms = int((time.monotonic() - t0) * 1000)
+    with job_context(skill=SKILL_SLUG):
        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)
-        emit("任务完成", skill=SKILL_SLUG, stage="run")
-        return 0
-    except Exception:
-        log.exception(
-            "task_failed task_type=%s target_id=%s input_id=%s",
+            "task_start 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="...", ...)
-        return 1
+        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)
+                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`。
@@ -254,7 +289,7 @@ def cmd_run(target=None, input_id=None):
 3. **`python scripts/main.py log-get <id>`** — 单条 JSON，含 `result_summary`（video 路径等）。
 4. **统一日志文件** — `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log`（grep `trace_id`、`task_failed`）。
 5. **Run Journal** — `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl`（宿主 UI 进度来源）。
-6. **RPA artifacts** — `rpa-artifacts/` 截图、录屏 MP4、`video_log`。
+6. **RPA artifacts** — `rpa-artifacts/` 失败截图；若 `OPENCLAW_RECORD_VIDEO=1` 还有录屏 MP4、`video_log`。未开启录屏时可能只有截图或日志，需要完整录屏请在用户 `.env` 中设置 `OPENCLAW_RECORD_VIDEO=1`。

 长时间无 stdout **不代表卡死**；先看 Run Journal / Activity，再看统一日志。

--- a/development/POLICY_MATRIX.md
+++ b/development/POLICY_MATRIX.md
@@ -15,6 +15,7 @@
 | POLICY-TESTING-002 | `tests/integration/` 下 Python 测试文件若存在，默认应为 `.sample`，不得进入默认套件 | development/TESTING.md §7 真实联调测试的安全约束、§8 新 skill 的最小测试清单 | hard | 检查 `tests/integration/*.py` 无 `.sample` 后缀 | `tests/test_development_policy_guard.py::TestPolicyTesting002` |
 | POLICY-RPA-001 | 不得 import/use account-manager 内部 `rpa_helpers` / `inject_account_manager_scripts_path` / `get_account_credential` | development/ADAPTER.md §兄弟依赖；development/RPA.md §1.7 | hard | 扫描 `scripts/**/*.py` 禁止模式 | `tests/test_development_policy_guard.py::TestPolicyRpa001`（另见 `tests/test_no_rpa_helpers_import.py`） |
 | POLICY-RPA-002 | RPA 交付代码不得直接执行 ffmpeg 拼 MP4；应使用 `RpaVideoSession`（允许 `ffmpeg_path` 等诊断字段） | development/RPA.md §5.3 录屏成片标准 | hard | 扫描 `scripts/**/*.py` 禁止 `subprocess` / `os.system` / `os.popen` 直接调用 ffmpeg（`task_run_support.py` 保留豁免） | `tests/test_development_policy_guard.py::TestPolicyRpa002` |
+| POLICY-RPA-003 | 即使默认 `OPENCLAW_RECORD_VIDEO=0`，RPA / 长任务模板也必须保留录屏能力：`RpaVideoSession`、`video.add_step`、video artifact merge 到 `result_summary` | development/RPA.md §5.3；development/LOGGING.md；development/CONFIG.md | hard | 扫描 `scripts/service/*.py`（service 层整体须含上述接入） | `tests/test_development_policy_guard.py::TestPolicyRpa003` |
 | POLICY-PACKAGING-001 | `scripts/**/*.py` 单文件 < 1000 行 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数统计 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit` |
 | POLICY-PACKAGING-002 | 文本文件 UTF-8 without BOM，无 `U+FEFF` | development/DEVELOPMENT.md §3.4；development/RUNTIME.md §编码与输出 | hard | BOM / 解码检查 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_text_files_are_utf8_without_bom` |
 | POLICY-DOCS-001 | 本矩阵存在且包含上述全部 `policy_id` | 本次规范化约定 | hard | 解析 `development/POLICY_MATRIX.md` | `tests/test_development_policy_guard.py::TestPolicyDocs001` |
@@ -23,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` |

 ---

@@ -41,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` |
--- a/development/RPA.md
+++ b/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 示例（必读）
@@ -283,13 +303,16 @@ skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层

 ### 5.3 录屏成片标准

- RPA skill 默认 `OPENCLAW_RECORD_VIDEO=1`。
+- **skill-template 默认 `OPENCLAW_RECORD_VIDEO=0`**（开发调试更快，不启 ffmpeg）。
+- **`OPENCLAW_RECORD_VIDEO=1` 时启用录屏**：字幕、旁白、背景音、MP4 成片由 platform-kit 统一处理。
 - 使用 platform-kit 的 **`RpaVideoSession`**；**skill 不要自行合成视频**（不要自己调 ffmpeg 拼 MP4）。
- `OPENCLAW_RECORD_VIDEO=0` 时 session 无副作用（不启 ffmpeg、不写字幕文件）。
+- **默认关闭 ≠ 可以删除录屏接入**：RPA / 长任务 **service 层**（`scripts/service/*.py`）**必须保留** `RpaVideoSession`、`video.add_step`、video artifact merge 到 `result_summary`（见 `POLICY-RPA-003`）。
+- `OPENCLAW_RECORD_VIDEO=0` 时 session **无副作用**（不启 ffmpeg、不写字幕文件、不生成最终 MP4），但 **`RpaVideoSession.add_step` 仍可同步 Activity 进度**。
+- 生产留证 / 合规 / 客户现场复现时，由用户在 `.env` 或进程环境变量中开启 `OPENCLAW_RECORD_VIDEO=1`。
 - **ffmpeg 是唯一录屏器**（Windows：`gdigrab` + `desktop`）。
- **最终视频**：`{skill_data_dir}/videos/{skill_slug}_{yyyyMMdd_HHmmss}_{batch_id}.mp4`
+- **最终视频**（`OPENCLAW_RECORD_VIDEO=1` 时）：`{skill_data_dir}/videos/{skill_slug}_{yyyyMMdd_HHmmss}_{batch_id}.mp4`
 - **中间产物**：`rpa-artifacts/{batch_id}/capture.mp4`、`subtitles/`、`logs/` 等。
- 任务完成后 CLI / `result_summary` 应包含：`video_path`、`raw_video`、`video_log`、`video_warnings`、`music_path`、`voiceover_path`、`audio_warnings`（见 `scripts/service/task_run_support.py`）。
+- 任务完成后 CLI / `result_summary` 应包含 video 字段（开启录屏时有路径；关闭时仍保留 `video` 结构与诊断占位）：`video_path`、`raw_video`、`video_log`、`video_warnings`、`music_path`、`voiceover_path`、`audio_warnings`（见 `scripts/service/task_run_support.py`）。

 模板最小示范见 `scripts/service/task_service.py` 的 `_run_template_demo()`。

--- a/development/RUNTIME.md
+++ b/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 / 背景音乐

--- a/development/TESTING.md
+++ b/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)；
@@ -236,10 +236,11 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t

 ## 12. RPA / video 测试标准

- `RpaVideoSession` 调用**不跑真实 ffmpeg**：单测中使用 `unittest.mock` patch session 或设 `OPENCLAW_RECORD_VIDEO=0`。
+- 模板 `.env.example` 默认 **`OPENCLAW_RECORD_VIDEO=0`**；默认必跑测试**不应启动真实 ffmpeg**（patch session 或显式设 `OPENCLAW_RECORD_VIDEO=0`）。
+- **但测试必须守护录屏接入能力**（`POLICY-RPA-003` 扫描 `scripts/service/*.py`）：`RpaVideoSession` 被构造、`video.add_step` 被调用、video artifact 结构 merge 进 `result_summary`（`video` / `video_path` 等字段），与默认是否录屏无关。
 - 断言 `title` / `closing_title` 是**中文**业务文案。
- 断言 video artifact 会进入 `result_summary`（`video_path`、`raw_video`、`video_log` 等）。
 - 断言 step 文案贴近用户动作，不是技术日志（如「准备执行示例任务」而非「enter cmd_run」）。
+- 若需测试**真实录屏**（ffmpeg 成片），必须显式设 `OPENCLAW_RECORD_VIDEO=1`，并放在 `tests/integration/` 或手动触发场景，**不得**进入默认 unittest 套件。

 参考 `tests/test_video_service.py`。

@@ -259,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`
--- a/references/CLI.md
+++ b/references/CLI.md
@@ -22,8 +22,9 @@ python {baseDir}/scripts/main.py version
  2. `python {baseDir}/scripts/main.py log-get <log_id>`
  3. 统一日志文件 `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/jiangchang.log`（含 `trace_id`、`task_failed` 等）
  4. Run Journal `{JIANGCHANG_DATA_ROOT}/.jiangchang/runs/{job_id}.jsonl`
-  5. RPA artifacts / `video_log` / 失败截图（见 `development/RPA.md`）
- **任务完成后**若有 video artifact，CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`）。
+  5. RPA artifacts / `video_log` / 失败截图（见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
+- **录屏默认关闭**：模板 `.env.example` 为 `OPENCLAW_RECORD_VIDEO=0`；若未开启录屏，任务**可能不会**打印录屏路径。
+- 需要录屏时在用户 `.env` 或进程环境变量中设置 **`OPENCLAW_RECORD_VIDEO=1`**；开启后任务完成时 CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`），且 `result_summary` 含 video 字段。

 ## config-path（配置路径）

--- a/scripts/service/task_service.py
+++ b/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.rpa.video_session import RpaVideoSession
+from jiangchang_skill_core.activity import JobStopped, emit, finish, job_context

 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)
-        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),
-        )
+    with job_context(skill=SKILL_SLUG):
        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,
        )
-
-        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")
+        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,
+                )
+                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="任务执行异常，详见统一日志",
-                result_summary=json.dumps(
-                    {"stage": "run", "error": "unexpected_exception"},
-                    ensure_ascii=False,
-                ),
+                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 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(
--- a/scripts/util/constants.py
+++ b/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"
--- a/tests/_support.py
+++ b/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

--- a/tests/test_development_policy_guard.py
+++ b/tests/test_development_policy_guard.py
@@ -32,6 +32,7 @@ POLICY_IDS = (
    "POLICY-TESTING-002",
    "POLICY-RPA-001",
    "POLICY-RPA-002",
+    "POLICY-RPA-003",
    "POLICY-PACKAGING-001",
    "POLICY-PACKAGING-002",
    "POLICY-DOCS-001",
@@ -40,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 = (
@@ -109,6 +113,10 @@ RPA_002_FFMPEG_PATTERNS = (

 RPA_002_EXEMPT_REL = "scripts/service/task_run_support.py"

+RPA_003_SOURCE = (
+    "development/RPA.md §5.3; development/TESTING.md §12; development/POLICY_MATRIX.md"
+)
+
 LOGGING_001_SOURCE = "development/LOGGING.md; development/RUNTIME.md"
 LOGGING_002_SOURCE = "development/LOGGING.md; development/DEVELOPMENT.md"
 LOGGING_003_SOURCE = "development/LOGGING.md"
@@ -470,6 +478,30 @@ class TestPolicyRpa002(unittest.TestCase):
        )


+class TestPolicyRpa003(unittest.TestCase):
+    def test_service_layer_retains_video_session_integration(self) -> None:
+        skill_root = get_skill_root()
+        service_files = _walk_files(skill_root, "scripts/service", suffix=".py")
+        self.assertTrue(service_files, msg="scripts/service/*.py not found")
+        combined = "\n".join(_read_text(path) for path in service_files)
+        missing: list[str] = []
+        if "RpaVideoSession" not in combined:
+            missing.append("RpaVideoSession")
+        if "video.add_step" not in combined and ".add_step(" not in combined:
+            missing.append("video.add_step or .add_step(")
+        if "merge_video_into_result_summary" not in combined:
+            missing.append("merge_video_into_result_summary")
+        self.assertEqual(
+            missing,
+            [],
+            msg=_policy_msg(
+                "POLICY-RPA-003",
+                RPA_003_SOURCE,
+                "scripts/service/*.py missing: " + ", ".join(missing),
+            ),
+        )
+
+
 def _scan_sensitive_logging_assignments(skill_root: str) -> list[str]:
    offenders: list[str] = []
    for path in _walk_files(skill_root, "scripts", suffix=".py"):
@@ -590,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()
--- a/tests/test_docs_standards.py
+++ b/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")
--- a/tests/test_platform_import.py
+++ b/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:
--- a/tests/test_template_runtime_standard.py
+++ b/tests/test_template_runtime_standard.py
@@ -34,7 +34,7 @@ FORBIDDEN_PHRASES = (

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

--- a/tests/test_video_service.py
+++ b/tests/test_video_service.py
@@ -15,6 +15,46 @@ from _support import IsolatedDataRoot, get_skill_root
 from jiangchang_skill_core import config


+def _active_env_value(text: str, key: str) -> str | None:
+    """Return the active (non-comment) KEY=value line from .env-style text."""
+    prefix = f"{key}="
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        active = stripped.split("#", 1)[0].strip()
+        if active.startswith(prefix):
+            return active
+    return None
+
+
+def _combined_service_source(skill_root: str | None = None) -> str:
+    """Merge scripts/service/*.py source (excludes __pycache__)."""
+    root = skill_root or get_skill_root()
+    service_dir = os.path.join(root, "scripts", "service")
+    parts: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(service_dir):
+        dirnames[:] = [d for d in dirnames if d != "__pycache__"]
+        for name in sorted(filenames):
+            if not name.endswith(".py"):
+                continue
+            path = os.path.join(dirpath, name)
+            with open(path, encoding="utf-8") as f:
+                parts.append(f.read())
+    return "\n".join(parts)
+
+
+def _missing_video_integration_tokens(service_text: str) -> list[str]:
+    missing: list[str] = []
+    if "RpaVideoSession" not in service_text:
+        missing.append("RpaVideoSession")
+    if "video.add_step" not in service_text and ".add_step(" not in service_text:
+        missing.append("video.add_step or .add_step(")
+    if "merge_video_into_result_summary" not in service_text:
+        missing.append("merge_video_into_result_summary")
+    return missing
+
+
 class TestEnvExampleVideoDefaults(unittest.TestCase):
    def test_env_example_contains_required_keys(self) -> None:
        path = os.path.join(get_skill_root(), ".env.example")
@@ -22,13 +62,45 @@ class TestEnvExampleVideoDefaults(unittest.TestCase):
            text = f.read()
        for key in (
            "OPENCLAW_" + "TEST_TARGET=mock",
-            "OPENCLAW_RECORD_VIDEO=1",
+            "OPENCLAW_RECORD_VIDEO=0",
            "OPENCLAW_ARTIFACTS_ON_FAILURE=1",
            "OPENCLAW_BROWSER_HEADLESS=0",
            "OPENCLAW_PLAYWRIGHT_STEALTH=1",
        ):
            self.assertIn(key, text, msg=f"missing {key!r} in .env.example")

+    def test_env_example_default_off_but_template_keeps_video_integration(self) -> None:
+        path = os.path.join(get_skill_root(), ".env.example")
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        self.assertEqual(
+            _active_env_value(text, "OPENCLAW_RECORD_VIDEO"),
+            "OPENCLAW_RECORD_VIDEO=0",
+        )
+
+        service_text = _combined_service_source()
+        missing = _missing_video_integration_tokens(service_text)
+        self.assertEqual(
+            missing,
+            [],
+            msg=(
+                "default OPENCLAW_RECORD_VIDEO=0 does not allow removing video integration; "
+                f"scripts/service/*.py missing: {', '.join(missing)}"
+            ),
+        )
+
+    def test_env_example_allows_record_video_one_in_comments_only(self) -> None:
+        sample = "\n".join(
+            [
+                "# example: OPENCLAW_RECORD_VIDEO=1 for production",
+                "OPENCLAW_RECORD_VIDEO=0",
+            ]
+        )
+        self.assertEqual(
+            _active_env_value(sample, "OPENCLAW_RECORD_VIDEO"),
+            "OPENCLAW_RECORD_VIDEO=0",
+        )
+

 class TestPrintVideoSummary(unittest.TestCase):
    def test_cli_prints_video_path_when_enabled(self) -> None:
Author	SHA1	Message	Date
chendelian	6f958ded28	feat(template): SRCP v1 standards, job_context/finish gold sample (v1.0.38, platform-kit 1.2.0) All checks were successful 技能自动化发布 / release (push) Successful in 4s Details Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-12 12:27:44 +08:00
chendelian	3bc15d1241	chore: auto release commit (2026-07-11 15:57:40) All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-07-11 15:57:43 +08:00