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

Add DATA_PATHS golden standard and resolve_data_path helpers.
Document skill-owned file layout under user data dir, extend runtime_paths with standard subdir helpers, add POLICY-DATA-PATH-001, and update CONFIG/RUNTIME cross-references. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-14 07:55:55 +08:00 · 2026-07-13 14:14:38 +08:00 · 2026-07-12 12:27:44 +08:00 · 2026-07-11 15:57:43 +08:00
28 changed files with 1224 additions and 168 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,10 +12,19 @@ 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=失败截图(默认)
 # ── 节流 / 超时 ──
 STEP_DELAY_MIN=1.0                     # 步骤间随机等待下限(秒)
 STEP_DELAY_MAX=5.0                     # 步骤间随机等待上限(秒)
 HUMAN_WAIT_TIMEOUT=180                 # 滑块/验证码/2FA 等人工超时(秒)
 # ── 数据目录子路径（见 development/DATA_PATHS.md；留空则用 skill 数据目录下默认子文件夹）──
 # 相对路径相对于 {JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/，不是 workspace / CWD
 # SKILL_DOWNLOAD_DIR=downloads
 # SKILL_IMPORT_DIR=imports
 # SKILL_EXPORT_DIR=exports
 # SKILL_UPLOAD_DIR=uploads
 # SKILL_CACHE_DIR=cache
 # SKILL_TEMP_DIR=temp
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.32
+version: 1.0.40
 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:
@@ -20,6 +20,14 @@ allowed-tools:
 这是一个**用于复制的新技能模板**，不是业务 skill 本身。复制后请替换占位内容，实现你的真实业务逻辑。
 ## Agent / 宿主编排（复制为业务技能后必改）
 - **长耗时 / RPA / 浏览器任务**：必须通过宿主 **Skill Action**（`run_skill_action`）调用已声明在 `assets/actions.json` 中的 action；`executionProfile` 须为 `"async"`，进度见**任务中心** / Skill Run Card。
 - **禁止**对长任务使用 `exec python …/scripts/main.py run` 或 `process poll` 干等 CLI 返回。
 - 只读查询（`health` / `stats` 等）可用 `executionProfile: "sync"`，立即返回结果。
 - 批量处理用参数化 `pickCount` / `--pick N` 顺序消费队列，**不要并发**同一 Profile；契约见 `development/SKILL_ACTION_RUNTIME.md`、`references/ACTIONS.md`。
 - 模板源仓库本身仅示范 `health` / `version` / `config-path`（sync）；定制 RPA 技能后须自行增加 async action。
 ## 面向用户问答（LLM 规则）
 - 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
@@ -70,10 +78,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）。
@@ -83,7 +91,7 @@ python {baseDir}/scripts/main.py version
 2. 业务技能仓库中**不得**存在 `.openclaw-skill-template`（仅 template 源仓库保留）。
 3. 复制目录为你的新 skill 仓库，全局替换 `your-skill-slug` 等占位词。
 4. 按 `development/DEVELOPMENT.md` 完成开发与文档定制。
-5. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`。
+5. 用户市场说明写入根 `README.md`；Agent 调用契约见 `references/CLI.md`、`references/SCHEMA.md`、`references/ACTIONS.md`；长任务 / 任务中心见 `development/SKILL_ACTION_RUNTIME.md`。
 6. 同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
 7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 `references/SCHEMA.md`（元数据表 `_jiangchang_*` + `CREATE TABLE` 物理顺序）。
--- a/assets/README.md
+++ b/assets/README.md
@@ -1,10 +1,10 @@
 # assets
- `actions.json`：Skill Action manifest 最小示例（**可选**；不需要宿主入口时可删除）。
+- `actions.json`：Skill Action manifest 最小示例（**可选**；不需要宿主入口时可删除）。模板要求每个 action 显式声明 `executionProfile`（`sync` \| `async`）。
 - `examples/`：CLI 成功输出形状示例（虚构路径与数据）。
 - `schemas/`：轻量 JSON Schema（`skill-actions.schema.json` 为**新技能严格规范**；`task-log-record.schema.json` 等）。
-`skill-actions.schema.json` 使用 `additionalProperties: false` 表达模板推荐契约；宿主运行时可能更宽松以兼容历史 manifest。`row`/`batch` placements 与 `bind`/`concurrency`/`locks` 为预留能力，当前模板示例不得使用。
+`skill-actions.schema.json` 使用 `additionalProperties: false` 表达模板推荐契约；宿主运行时可能更宽松以兼容历史 manifest。`row`/`batch` placements 与 `bind`/`concurrency`/`locks` 为预留能力，当前模板示例不得使用。RPA/长耗时 action 必须 `executionProfile: "async"`，见 [`development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
 - 用户市场说明见根目录 [`README.md`](../README.md)
 - Agent 调用/编排参考见 [`references/`](../references/)（含 [`ACTIONS.md`](../references/ACTIONS.md)）
--- a/assets/actions.json
+++ b/assets/actions.json
@@ -5,8 +5,9 @@
    {
      "id": "health",
      "label": "运行检查",
-      "description": "检查技能运行环境并返回结构化结果。",
+      "description": "检查技能运行环境并返回结构化结果，不启动浏览器。",
      "placements": ["skill-detail", "agent"],
      "executionProfile": "sync",
      "entrypoint": {
        "type": "cli",
        "command": "health",
@@ -18,6 +19,7 @@
      "label": "查看版本",
      "description": "返回技能版本和机器标识。",
      "placements": ["skill-detail"],
      "executionProfile": "sync",
      "entrypoint": {
        "type": "cli",
        "command": "version",
@@ -29,6 +31,7 @@
      "label": "查看配置位置",
      "description": "返回技能配置文件位置。",
      "placements": ["skill-detail"],
      "executionProfile": "sync",
      "entrypoint": {
        "type": "cli",
        "command": "config-path",
--- a/assets/schemas/skill-actions.schema.json
+++ b/assets/schemas/skill-actions.schema.json
@@ -120,7 +120,12 @@
        },
        "entrypoint": { "$ref": "#/$defs/entrypoint" },
        "inputSchema": { "$ref": "#/$defs/inputSchema" },
-        "confirmation": { "$ref": "#/$defs/confirmation" }
+        "confirmation": { "$ref": "#/$defs/confirmation" },
        "executionProfile": {
          "type": "string",
          "enum": ["sync", "async"],
          "description": "sync=宿主内联等待结果（约 30s）；async=后台 Job 进任务中心。模板要求显式写出；RPA/长耗时必须 async。"
        }
      },
      "description": "模板 Phase 1 不包含 bind/concurrency/locks 等预留能力字段；宿主类型可能定义这些字段，但新技能不得依赖"
    }
--- 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=失败截图(默认)
 # ── 节流 / 超时 ──
@@ -40,7 +40,22 @@ STEP_DELAY_MAX=5.0
 HUMAN_WAIT_TIMEOUT=180                 # 滑块/验证码/2FA 等人工超时(秒)
 ```
-**业务专属配置必须带技能前缀**（如 `DEMO_XXX`、`MY_SKILL_XXX`），**不要污染全局命名空间**（禁止 `SCRAPE_1688_*`、`RECEIVE_ORDER_*` 等跨技能前缀写入模板）。
+**业务专属配置必须带技能前缀**（如 `DEMO_XXX`、`MY_SKILL_XXX`、`SKILL_DOWNLOAD_DIR`），**不要污染全局命名空间**（禁止 `SCRAPE_1688_*`、`RECEIVE_ORDER_*` 等跨技能前缀写入模板）。
 ### 数据目录子路径（下载 / 导入 / 导出）
 技能**自己写入**的文件默认在 `{JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/` 下标准子目录（`downloads/`、`imports/`、`exports/` 等）。须通过 `util.runtime_paths.resolve_data_path()` 或 `get_*_dir()` 解析，**禁止** `os.path.abspath(config.get(...))` 相对 CWD。
 - 权威说明：[`DATA_PATHS.md`](DATA_PATHS.md)
 - `.env.example` 中路径类配置**留空即用默认**；若写相对路径，必须相对 **skill 数据目录**，**禁止** `./outputs/...` 这类相对 workspace 的写法
 - 可选 env：`SKILL_DOWNLOAD_DIR`、`SKILL_IMPORT_DIR`、`SKILL_EXPORT_DIR` 等（见 DATA_PATHS.md）
 ### 录屏开关（`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`
@@ -84,7 +99,7 @@ config.get_float("STEP_DELAY_MIN", 1.0)
 ## health / config-path
 - **`health`**：输出 `collect_runtime_diagnostics` 字段（`platform_kit_version_ok`、`ffmpeg_path` 等），**不打印敏感值**；补充 `env_path` / `env_exists` / `example_path`。
- **`config-path`**：输出 JSON，包含 `skill`、`env_path`（用户数据目录 `.env`）、`example_path`（仓库 `.env.example` 绝对路径），便于排查落盘位置。
+- **`config-path`**：输出 JSON，包含 `skill`、`env_path`（用户数据目录 `.env`）、`example_path`（仓库 `.env.example` 绝对路径），便于排查落盘位置；业务 skill 建议附加 `list_resolved_data_paths()` 中的子目录路径（见 [`DATA_PATHS.md`](DATA_PATHS.md)）。
 ## doctor / setup 命令（可选）
@@ -97,4 +112,5 @@ config.get_float("STEP_DELAY_MIN", 1.0)
 - `RPA.md` — 三端 RPA 标准与各开关含义
 - `ADAPTER.md` — `OPENCLAW_TEST_TARGET` 四档模式
- `RUNTIME.md` — `JIANGCHANG_*` 环境变量与数据目录约定
+- `RUNTIME.md` — `JIANGCHANG_DATA_ROOT` 与数据根约定
 - `DATA_PATHS.md` — 下载/导入/导出等子目录与 `resolve_data_path` 规范
--- a/development/DATA_PATHS.md
+++ b/development/DATA_PATHS.md
@@ -0,0 +1,160 @@
 # 用户数据目录与文件路径黄金标准
 > 本文是 skill **读写本地文件** 的权威约定。凡涉及下载、导入、导出、缓存、RPA 存证等路径，复制模板后须遵守本文；Agent 实现业务 skill 时也应先读本文。
 ---
 ## 1. 根目录
 所有技能持久化数据（配置、数据库、业务文件）默认落在：
 ```text
 {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
 ```
 示例：
 ```text
 D:\jiangchang-data\12500\download-video-baidu-haokan\
 ```
 实现：`util.runtime_paths.get_skill_data_dir()`。
 **禁止**把技能自己写入的文件落到：
 - Agent / 宿主 **workspace**（进程 CWD）
 - 技能安装目录（含 `.openclaw/skills/...`）
 - 未在本文声明的任意相对 CWD 路径
 ---
 ## 2. 标准子目录树
 | 子目录 | 用途 | 默认 helper |
 |--------|------|-------------|
 | `downloads/` | 从外部拉取的原始文件（视频、回单、PDF…） | `get_downloads_dir()` |
 | `imports/` | 用户/Agent 放入的待处理清单（urls.txt、batch.json、CSV） | `get_imports_dir()` |
 | `exports/` | 导出给用户的结果（xlsx/csv/json） | `get_exports_dir()` |
 | `uploads/` | 待发布到外部平台的 staging（可选） | `get_uploads_dir()` |
 | `cache/` | 可再生缓存（页面快照、解析中间结果） | `get_cache_dir()` |
 | `temp/` | 单次任务 scratch，任务结束可删 | `get_temp_dir()` |
 | `rpa-artifacts/` | RPA 失败截图、录屏中间产物 | `get_rpa_artifacts_dir(batch_id)` |
 | `videos/` | RPA 录屏成片 MP4 | `get_videos_dir()` |
 | `{skill_slug}.db` | SQLite | `get_db_path()` |
 | `.env` | 用户配置 | `config.get_env_file_path()` |
 复制后若业务不需要某目录，可不创建；**但一旦写入该类文件，必须走对应 helper**。
 ---
 ## 3. 两类路径
 ### A. 技能拥有（skill-owned）
 技能**创建或更新**的文件：下载结果、导出报表、失败截图、队列 sidecar 等。
 - **默认**必须在 `{skill_data_dir}/<子目录>/` 下。
 - **必须**通过 `resolve_data_path()` 或 `get_*_dir()` 解析，**禁止** `os.path.abspath(config.get(...))` 相对 CWD。
 ### B. 用户显式输入（user-owned）
 用户在 CLI / Agent 对话中给出的**已有文件**绝对路径，例如「发布这个视频 `D:\素材\x.mp4`」。
 - 技能**只读**，路径可以是用户磁盘任意位置。
 - 使用 `resolve_input_path()`：绝对路径原样；**相对路径**解析为 `{skill_data_dir}/imports/<相对路径>`，**不**相对 workspace/CWD。
 ---
 ## 4. 配置项（`.env`）
 可选覆盖项（**留空则用默认子目录**）：
 ```ini
 # ── 数据目录子路径（见 development/DATA_PATHS.md）──
 # 相对路径相对于 {JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/，不是 workspace
 # SKILL_DOWNLOAD_DIR=downloads/videos
 # SKILL_IMPORT_DIR=imports
 # SKILL_EXPORT_DIR=exports
 # SKILL_UPLOAD_DIR=uploads
 # SKILL_CACHE_DIR=cache
 # SKILL_TEMP_DIR=temp
 ```
 | 规则 | 说明 |
 |------|------|
 | 未配置 | `{skill_data_dir}/{default_subdir}` |
 | 相对值 `downloads/videos` | `{skill_data_dir}/downloads/videos` |
 | 绝对值 `D:\nas\exports` | 高级用户/NAS 挂载，原样使用 |
 | **禁止** `./outputs/...` | 会随 CWD 漂移，不得作为 `.env.example` 活跃配置行 |
 业务专属路径 env key 须带 **`SKILL_` 前缀**（或技能 slug 前缀），避免污染全局命名空间。
 ---
 ## 5. 代码用法
 ```python
 from util.runtime_paths import (
    get_downloads_dir,
    get_imports_dir,
    resolve_data_path,
    resolve_input_path,
    list_resolved_data_paths,
 )
 # 下载保存（A 类）
 dest = os.path.join(get_downloads_dir(), f"{vid}.mp4")
 # 或带 env 覆盖
 out_dir = resolve_data_path("SKILL_DOWNLOAD_DIR", "downloads")
 # CLI -i urls.txt（B 类，相对路径 → imports/）
 manifest = resolve_input_path(args.input_path)
 # health 诊断
 paths = list_resolved_data_paths()
 ```
 **反模式（禁止）：**
 ```python
 # ❌ 相对 CWD，Agent 从 workspace 执行时会写错盘
 os.path.abspath(config.get("DOWNLOAD_OUTPUT_DIR"))
 # ❌ .env.example 里写 ./outputs/videos
 DOWNLOAD_OUTPUT_DIR=./outputs/videos
 ```
 ---
 ## 6. health / config-path
 `health` 或 `config-path` 建议输出 `list_resolved_data_paths()` 中的路径，便于排查「文件写到哪里去了」。展示路径须与 `run` 实际使用的一致。
 ---
 ## 7. 与 RPA 存证的关系
 - 失败截图、录屏中间文件：`rpa-artifacts/{batch_id}/`（见 [`RPA.md`](RPA.md) §5.1）
 - 录屏成片：`videos/`（见 [`RPA.md`](RPA.md) §5.3）
 业务 `downloads/` 与 RPA `videos/` **分工不同**：前者是业务产出文件，后者是操作过程录屏。
 ---
 ## 8. 测试
 - 单元测试须用 `IsolatedDataRoot`，断言路径落在临时数据根下。
 - `tests/test_runtime_paths.py` 覆盖 `resolve_data_path` / `resolve_input_path`。
 - `POLICY-DATA-PATH-001`：禁止 `.env.example` 中 `./` 路径；禁止业务代码 `abspath(config.get(...))`。
 ---
 ## 9. 相关文档
 | 文档 | 内容 |
 |------|------|
 | [`RUNTIME.md`](RUNTIME.md) | 数据根、共享 runtime、编码 |
 | [`CONFIG.md`](CONFIG.md) | `.env` bootstrap 与三层优先级 |
 | [`RPA.md`](RPA.md) | rpa-artifacts / videos 存证 |
 | [`POLICY_MATRIX.md`](POLICY_MATRIX.md) | POLICY-DATA-PATH-001 |
--- 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` §敏感信息红线）。
@@ -525,9 +525,11 @@ metadata:
 若技能需要出现在宿主**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中，提供 `assets/actions.json`。
- 契约说明见 [`references/ACTIONS.md`](../references/ACTIONS.md)
+- **运行时金标准**见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)（sync/async、任务中心、Agent 禁令）
 - 字段契约见 [`references/ACTIONS.md`](../references/ACTIONS.md)
 - JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)
- 模板最小示例仅暴露 `health` / `version` / `config-path` 三个 CLI 子命令
+- 模板最小示例仅暴露 `health` / `version` / `config-path`（均显式 `executionProfile: "sync"`）
 - 含浏览器 RPA / 长耗时的业务技能：**必须**增加至少一条 `"executionProfile": "async"` 且 `placements` 含 `agent` 的 action（`POLICY-SKILL-ACTION-001`）
 - 没有宿主直接操作需求时，**可以删除** `actions.json`；删除后勿保留失效引用
 - 复制为新技能后，scaffold 会自动将 `your-skill-slug` 与 `your_skill_slug` 替换为新 slug（后者用于 `LOG_LOGGER_NAME` 等下划线形式）；action 业务命令由技能作者自行调整
@@ -539,6 +541,25 @@ python {skillRoot}/scripts/main.py <command> <args...>
 CLI 必须提供稳定退出码、结构化成功输出，以及 `ERROR:<CODE>:` / `HINT:` 错误契约（详见 `references/ACTIONS.md`）。
 ### 编排范式：单内核 + 多入口
 长任务 / RPA 技能推荐拆分（勿把 `job_context` 塞进纯业务内核）：
 ```text
 execute_single_<biz>(...)   # 鉴权 + 业务 + task_log；无 job_context
 cmd_run(...)                # 单条：job_context + execute_single + finish
 cmd_run_pick(N, ...)        # 批量顺序：job_context + for-loop + emit(progress) + finish(partial|success|failed)
 cmd_stats()                 # 只读 sync：JSON，无 job_context
 ```
 - 批量数量用 **`pickCount` / `--pick N` 参数**（任意正整数），不写死条数。
 - **顺序执行、不并发**同一浏览器 Profile / account lease。
 - 详情见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) §5–§6。
 ### 队列 + pick（可选）
 有「待处理列表」时：队列表 `pending → processing → success/failed`；数据管理录入或 `import-*` 入库；`run --pick N` 消费；失败用 `reset` 回 `pending`（不自动重试）。Manifest 上配置 `*-run-pick`（async，toolbar/cron/agent）。
 ## 12. 如何接兄弟技能
 如果 skill 要依赖兄弟 skill，不要在业务代码里写死绝对路径。
--- 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,35 @@ 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 结果
 **单内核多入口**：`execute_single_*` 不含 `job_context`；仅 `cmd_run` / `cmd_run_pick` 包裹。批量 pick 循环内 `checkpoint()` + `emit(..., progress=...)`；部分失败用 `finish(status="partial")`。完整范式见 [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md)。
 RPA 等待用 `interruptible_sleep`，**不要**裸 `asyncio.sleep`（否则暂停响应滞后）。
 暂停在**步骤边界**生效（当前 `@rpa_step` / `emit` 执行完后、下一步开始前），与影刀「当前指令完成后暂停」一致。
 Journal 会写入 `type: lifecycle` 事件（`paused` / `resumed` / `stopping`），供宿主任务中心显示状态。
 ### 2.3 `task_logs`（任务结果审计）
@@ -88,11 +120,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}/...`（受 `OPENCLAW_ARTIFACTS_ON_FAILURE` 控制，默认开）
 - 失败截图：`{数据目录}/rpa-artifacts/{batch_id}/...`
-详见 [`RPA.md`](RPA.md) §失败存证与录屏标准。
+详见 [`RPA.md`](RPA.md) §5 存证与录屏规范。
 ---
@@ -200,7 +234,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 +242,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`。
@@ -254,7 +291,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，再看统一日志。
@@ -271,4 +308,5 @@ def cmd_run(target=None, input_id=None):
 | [`CLI.md`](../references/CLI.md) | `logs` / `log-get` 命令与手工排查入口 |
 | [`CONFIG.md`](CONFIG.md) | 敏感配置不进日志；`.env` 边界 |
 | [`DEVELOPMENT.md`](DEVELOPMENT.md) | `service/` 层日志职责与发布前检查清单 |
 | [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) | 任务中心 / async Job 与 `job_context` 边界 |
 | [`POLICY_MATRIX.md`](POLICY_MATRIX.md) | 可自动检测的 logging hard policy 索引 |
--- 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,11 @@
 | 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` |
 | POLICY-DATA-PATH-001 | 技能拥有路径须经 `resolve_data_path` / `get_*_dir`；`.env.example` 禁止 `./` CWD 相对路径；业务代码禁止 `abspath(config.get(...))` | development/DATA_PATHS.md | hard | 扫描 `.env.example` 与 `scripts/**/*.py` | `tests/test_development_policy_guard.py::TestPolicyDataPath001` |
 | POLICY-SKILL-ACTION-001 | 存在 `development/SKILL_ACTION_RUNTIME.md`；schema 含 `executionProfile`；业务技能（非模板占位 slug）若 service 含 `RpaVideoSession` 则 `actions.json` 须有 `executionProfile=async` 且 placements 含 `agent` 的 action | development/SKILL_ACTION_RUNTIME.md；references/ACTIONS.md | hard | 文档/schema/manifest 检查 | `tests/test_development_policy_guard.py::TestPolicySkillAction001` |
 ---
@@ -41,4 +47,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/README.md
+++ b/development/README.md
@@ -10,9 +10,11 @@
 6. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
 7. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
 8. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
-9. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
+9. [`DATA_PATHS.md`](DATA_PATHS.md) — 下载/导入/导出等本地文件路径标准（涉及文件读写时必读）
 10. [`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) — Skill Action sync/async、任务中心、Agent 禁令、队列 pick（涉及 RPA / 长任务 / 数据管理按钮 / Cron / Agent 时必读）
 11. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
 脚手架与 Git 防串库：[`../tools/README.md`](../tools/README.md)（`scaffold_skill.ps1`）。
-Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)。  
+Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)、[`../references/ACTIONS.md`](../references/ACTIONS.md)。  
 用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。
--- 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 / 背景音乐
@@ -89,6 +89,8 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
 {...}/{skill_slug}.db
 ```
 **业务文件（下载、导入、导出、缓存等）** 须落在上述数据目录的标准子目录下，**不得**相对 workspace/CWD 写入。完整子目录树、env 覆盖规则、`resolve_data_path()` 用法见 **[`DATA_PATHS.md`](DATA_PATHS.md)**。
 - 业务表使用英文 snake_case；中文表名/字段名写入 `_jiangchang_tables` / `_jiangchang_columns`（见 `references/SCHEMA.md`）。
 - 界面字段顺序由 `CREATE TABLE` 列定义顺序决定，**不要**维护 `display_order` 来调整顺序。
--- a/development/SKILL_ACTION_RUNTIME.md
+++ b/development/SKILL_ACTION_RUNTIME.md
@@ -0,0 +1,162 @@
 # Skill Action Runtime（宿主任务中心契约）
 本文是匠厂宿主 **Skill Action / 任务中心** 的技能侧金标准。涉及浏览器 RPA、长耗时任务、数据管理按钮、定时任务或 Agent 直接调用时**必读**。
 **边界：**
 | 文档 | 职责 |
 |------|------|
 | 本文 | sync/async、任务中心、Agent 禁令、编排范式、队列 pick |
 | [`../references/ACTIONS.md`](../references/ACTIONS.md) | `actions.json` 字段、placements、inputSchema |
 | [`LOGGING.md`](LOGGING.md) | `job_context` / `emit` / `finish` / Run Journal |
 | [`DATA_PATHS.md`](DATA_PATHS.md) | 下载/导入等落盘路径 |
 宿主实现细节以匠厂 Host API 为准；技能侧只需保证 manifest 与 CLI 契约稳定。
 ---
 ## 1. 核心原则
 1. **宿主管调度，技能管业务** — 不自行实现任务中心 / Job 轮询 / 后台守护进程。
 2. **长耗时 = async** — 开浏览器、RPA、HTTP 大文件下载等必须 `executionProfile: "async"`，进**任务中心**。
 3. **Agent 禁止 `exec` 直跑长任务 CLI** — 必须 `run_skill_action`；禁止 `exec python main.py run` + `process poll` 干等。
 4. **进度走 Journal** — `emit` / `video.add_step` → Run Journal；UI / Skill Run Card / 任务中心展示；**不靠 stdout 流**。
 5. **显式声明 `executionProfile`** — 宿主省略时默认 `async`；模板要求每个 action **写明** `sync` 或 `async`，避免歧义。
 ---
 ## 2. `executionProfile`：sync vs async
 | 值 | 宿主行为 | 超时 | 任务中心 |
 |----|----------|------|----------|
 | **`sync`** | 内联等待 CLI 结束，把结果直接返回调用方 | 默认约 **30s**（`SKILL_ACTION_SYNC_TIMEOUT_MS`） | ❌ 不进 |
 | **`async`** | 后台 spawn Job，立即返回 `jobId` | Job 本身无默认墙钟上限（可暂停/停止） | ✅ 进入 |
 | **省略** | 宿主视为 **async** | 同 async | ✅ |
 ### 硬规则
 | 场景 | 必须 |
 |------|------|
 | 浏览器 / Playwright / RPA 主路径 | `async` + 建议 `confirmation` |
 | 单次可能超过 ~20s 的网络/下载 | `async` |
 | `health` / `version` / `config-path` / 纯统计 / 快速导入 | `sync` |
 | 数据管理 **toolbar** | **只放 async**（宿主前端对 sync 结果会报错） |
 ### Agent 路径启发式（宿主行为，技能作者需知）
 - 显式写了 `executionProfile` → 以显式为准。
 - 未写时：描述含「统计 / 检查 / 不启动浏览器」等只读语义 → Agent 侧可当 **sync**；有 `confirmation` 的副作用 → **async**。
 - **模板要求一律显式写出**，不要依赖启发式。
 ---
 ## 3. 三入口如何感知 sync / async
 三个入口统一走 `POST /api/skill-actions/run`，带 `source.kind`：
 | 入口 | `source.kind` | 推荐 |
 |------|---------------|------|
 | **Agent** | `agent` | `run_skill_action`；长任务 async，秒回 jobId |
 | **数据管理** | `data-management` | toolbar 按钮触发 async action |
 | **定时任务** | `cron` | Cron 配置 async action + `pickCount` 等参数 |
 技能 **不要** 在 Python 里为三个入口写三套分支；宿主读 manifest 分流。
 ---
 ## 4. Action 分类与 placements 矩阵
 | Action 类型 | `executionProfile` | 典型 placements | `confirmation` |
 |-------------|--------------------|-----------------|----------------|
 | 运行检查 / 版本 / 配置路径 | `sync` | `skill-detail`, `agent`（只读） | 无 |
 | 库 / 队列统计 | `sync` | `skill-detail`, `agent` | 无 |
 | 数据导入 / 失败重置 | `sync` | `skill-detail`, `agent` | 可选 |
 | **单条**副作用 RPA | `async` | `agent`, `skill-detail` | **必须** |
 | **批量顺序** RPA（pick） | `async` | **`toolbar`**, `cron`, `agent` | **必须** |
 禁忌：
 - 高副作用 async action 不要默认只挂 `toolbar`（应有 confirmation）。
 - 含 `sensitive` 参数的 action 不要挂 `toolbar` / `cron`（除非有明确安全设计）。
 - 不要为了「按钮多」暴露所有 CLI 子命令。
 ---
 ## 5. 技能内编排范式（单内核 + 多入口）
 推荐结构（对齐 create-account / download-video 金标准）：
 ```text
 execute_single_<biz>(...)   # 纯业务：鉴权 + 核心逻辑 + task_log；不含 job_context
 cmd_run(...)                # 单条：job_context + execute_single + finish
 cmd_run_pick(N, ...)        # 批量：job_context + for-loop execute_single + emit(progress) + finish
 cmd_stats()                 # 只读 sync：JSON stdout，无 job_context
 ```
 要点：
 1. **`job_context` 只包编排层**（`cmd_run` / `cmd_run_pick`），不包 `execute_single_*`。
 2. 批量 **顺序、不并发**；数量由参数 `pickCount` / `--pick N` 传入（不写死 100/200）。
 3. pick 循环内：`checkpoint()` + `emit("正在处理 {i}/{total}", progress={...})`。
 4. 结束：全成功 `finish(success)`；部分失败 `finish(partial)`；全失败 `finish(failed)`。
 5. 同一浏览器 Profile / account lease：**禁止并发**；顺序执行 + lease 即可。
 详见 [`LOGGING.md`](LOGGING.md) §2.5 与 `scripts/service/task_service.py` 示范。
 ---
 ## 6. 队列 + pick（可选，Type B 批量）
 有「待处理列表」的技能（账号开通、视频下载、帖子发布等）建议：
 | 能力 | 约定 |
 |------|------|
 | 队列表 | `status`: `pending` → `processing` → `success` / `failed` |
 | 入库 | 数据管理 CRUD，或 `import-*`（相对 `{skill_data}/imports/`，见 [`DATA_PATHS.md`](DATA_PATHS.md)） |
 | 消费 | `run --pick N`，默认仅 `pending` |
 | 重试 | `reset` 或数据管理改 `pending`；**failed 不要自动重试** |
 | 批次 | 可选 `batch_id`，便于筛选与任务中心对照 |
 | Manifest | `*-run-pick`：`async`，`placements` 含 `toolbar` / `cron` / `agent`，`inputSchema.pickCount` |
 批量有两种合理形态（都是**顺序**）：
 | 形态 | 任务中心条数 | 适用 |
 |------|-------------|------|
 | 一次 `run-pick` 处理 N 条 | **1** 条 Job | 同类 RPA、同 Profile、定时消费队列 |
 | Agent/UI 触发 N 次单条 `run` | **N** 条 Job | 每条独立追踪 / 独立重试 |
 默认优先 **一次 pick、一条 Job**（与 create-account `--pick`、download `--pick` 一致）。
 ---
 ## 7. Agent / SKILL.md 契约（复制后必改）
 业务技能 `SKILL.md` 应明确：
 1. 副作用任务必须通过宿主 **Skill Action**（`run_skill_action`）调用。
 2. **禁止**对长任务使用 `exec` + `process poll`。
 3. 单条 vs 批量 action id 与参数（如 `url` / `pickCount`）。
 4. 长任务进度看**任务中心** / Skill Run Card，不等 CLI stdout。
 模板源仓库的 `SKILL.md` 含占位段落；scaffold 后按业务改写。
 ---
 ## 8. Policy
 自动检测索引见 [`POLICY_MATRIX.md`](POLICY_MATRIX.md)：
 - **POLICY-SKILL-ACTION-001**：`SKILL_ACTION_RUNTIME.md` 存在；schema 含 `executionProfile`；有 RPA 的业务技能必须声明 async agent action。
 ---
 ## 9. 与宿主 API（参考）
 | API | 用途 |
 |-----|------|
 | `GET /api/skill-actions/{skillSlug}` | 读 manifest |
 | `POST /api/skill-actions/run` | 执行 action（sync inline / async job） |
 | `GET /api/skill-actions/jobs` | 任务中心列表 |
 | `GET /api/skill-actions/jobs/{jobId}` | 单 Job 详情 / 事件 |
 Agent 工具（插件）：`list_skill_actions` → `get_skill_action` → `run_skill_action`；正常对话**不要**轮询 `get_skill_action_job`（交给 UI / 任务中心）。
--- 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/ACTIONS.md
+++ b/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 | 说明 |
+| id | CLI | executionProfile | placements | 说明 |
-|----|-----|------------|------|
+|----|-----|------------------|------------|------|
-| `health` | `health` | skill-detail, agent | 运行环境检查 |
+| `health` | `health` | sync | skill-detail, agent | 运行环境检查 |
-| `version` | `version` | skill-detail | 版本 JSON |
+| `version` | `version` | sync | skill-detail | 版本 JSON |
-| `config-path` | `config-path` | 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（参考）
--- 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`）
+  5. RPA artifacts / `video_log` / 失败截图（见 `development/RPA.md`）；未开启录屏时可能只有截图或日志
- **任务完成后**若有 video artifact，CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`）。
+- **录屏默认关闭**：模板 `.env.example` 为 `OPENCLAW_RECORD_VIDEO=0`；若未开启录屏，任务**可能不会**打印录屏路径。
 - 需要录屏时在用户 `.env` 或进程环境变量中设置 **`OPENCLAW_RECORD_VIDEO=1`**；开启后任务完成时 CLI 应打印录屏路径、录屏日志、视频/音频诊断（见 `task_run_support._print_video_summary`），且 `result_summary` 含 video 字段。
 ## config-path（配置路径）
--- a/references/README.md
+++ b/references/README.md
@@ -15,6 +15,7 @@
 | [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 |
 | [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
 | [`ACTIONS.md`](ACTIONS.md) | Skill Action manifest（**可选**能力）与宿主入口契约 |
 | [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md) | sync/async、任务中心、Agent 禁令、编排与队列 pick（长任务必读） |
 | [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） |
-按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；配置宿主按钮/定时任务/Agent 入口时读 `ACTIONS.md`；运行时环境细节见 `../development/RUNTIME.md`。
+按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；配置宿主按钮/定时任务/Agent 入口时读 `ACTIONS.md` + `SKILL_ACTION_RUNTIME.md`；运行时环境细节见 `../development/RUNTIME.md`。
--- 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.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(
--- 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.40"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
-PLATFORM_KIT_MIN_VERSION = "1.0.17"
+PLATFORM_KIT_MIN_VERSION = "1.2.0"
--- a/scripts/util/runtime_paths.py
+++ b/scripts/util/runtime_paths.py
@@ -1,4 +1,4 @@
-"""数据根、技能目录、兄弟技能根路径。"""
+"""数据根、技能目录、兄弟技能根路径与用户数据子目录解析。"""
 from __future__ import annotations
@@ -10,6 +10,22 @@ from util.constants import SKILL_SLUG
 _SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 STANDARD_SUBDIR_DOWNLOADS = "downloads"
 STANDARD_SUBDIR_IMPORTS = "imports"
 STANDARD_SUBDIR_EXPORTS = "exports"
 STANDARD_SUBDIR_UPLOADS = "uploads"
 STANDARD_SUBDIR_CACHE = "cache"
 STANDARD_SUBDIR_TEMP = "temp"
 STANDARD_SUBDIR_RPA_ARTIFACTS = "rpa-artifacts"
 STANDARD_SUBDIR_VIDEOS = "videos"
 CONFIG_KEY_DOWNLOAD_DIR = "SKILL_DOWNLOAD_DIR"
 CONFIG_KEY_IMPORT_DIR = "SKILL_IMPORT_DIR"
 CONFIG_KEY_EXPORT_DIR = "SKILL_EXPORT_DIR"
 CONFIG_KEY_UPLOAD_DIR = "SKILL_UPLOAD_DIR"
 CONFIG_KEY_CACHE_DIR = "SKILL_CACHE_DIR"
 CONFIG_KEY_TEMP_DIR = "SKILL_TEMP_DIR"
 def get_skill_root() -> str:
    return os.path.dirname(_SCRIPTS_DIR)
@@ -32,3 +48,98 @@ def get_skill_data_dir() -> str:
 def get_db_path(filename: str | None = None) -> str:
    name = filename or f"{SKILL_SLUG}.db"
    return os.path.join(get_skill_data_dir(), name)
 def _normalize_subdir(value: str) -> str:
    cleaned = value.strip().strip("/\\")
    if not cleaned or cleaned.startswith(".."):
        raise ValueError(f"invalid skill data subdir: {value!r}")
    return cleaned.replace("/", os.sep).replace("\\", os.sep)
 def resolve_data_path(
    config_key: str | None,
    default_subdir: str,
    *,
    create: bool = True,
 ) -> str:
    """解析技能拥有路径：空配置 → 数据目录下 default_subdir；相对 → 相对数据目录；绝对 → 原样。"""
    from jiangchang_skill_core import config
    base = get_skill_data_dir()
    raw = (config.get(config_key) or "").strip() if config_key else ""
    if not raw:
        path = os.path.join(base, _normalize_subdir(default_subdir))
    elif os.path.isabs(raw):
        path = os.path.abspath(os.path.expanduser(raw))
    else:
        path = os.path.join(base, _normalize_subdir(raw))
    if create:
        os.makedirs(path, exist_ok=True)
    return path
 def resolve_input_path(raw_path: str, *, create_parent: bool = False) -> str:
    """解析 CLI 输入路径：绝对路径原样；相对路径相对 {skill_data_dir}/imports/。"""
    text = (raw_path or "").strip()
    if not text:
        return text
    expanded = os.path.expanduser(text)
    if os.path.isabs(expanded):
        return os.path.abspath(expanded)
    imports_dir = get_imports_dir(create=create_parent)
    return os.path.abspath(os.path.join(imports_dir, os.path.normpath(expanded)))
 def get_downloads_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_DOWNLOAD_DIR, STANDARD_SUBDIR_DOWNLOADS, create=create)
 def get_imports_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_IMPORT_DIR, STANDARD_SUBDIR_IMPORTS, create=create)
 def get_exports_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_EXPORT_DIR, STANDARD_SUBDIR_EXPORTS, create=create)
 def get_uploads_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_UPLOAD_DIR, STANDARD_SUBDIR_UPLOADS, create=create)
 def get_cache_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_CACHE_DIR, STANDARD_SUBDIR_CACHE, create=create)
 def get_temp_dir(*, create: bool = True) -> str:
    return resolve_data_path(CONFIG_KEY_TEMP_DIR, STANDARD_SUBDIR_TEMP, create=create)
 def get_rpa_artifacts_dir(batch_id: str, *, create: bool = True) -> str:
    batch = (batch_id or "").strip() or "default"
    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_RPA_ARTIFACTS, batch)
    if create:
        os.makedirs(path, exist_ok=True)
    return path
 def get_videos_dir(*, create: bool = True) -> str:
    path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_VIDEOS)
    if create:
        os.makedirs(path, exist_ok=True)
    return path
 def list_resolved_data_paths() -> dict[str, str]:
    """供 health / config-path 输出已解析的数据子目录（不创建目录）。"""
    return {
        "skill_data_dir": get_skill_data_dir(),
        "downloads_dir": get_downloads_dir(create=False),
        "imports_dir": get_imports_dir(create=False),
        "exports_dir": get_exports_dir(create=False),
        "uploads_dir": get_uploads_dir(create=False),
        "cache_dir": get_cache_dir(create=False),
        "temp_dir": get_temp_dir(create=False),
        "videos_dir": get_videos_dir(create=False),
    }
--- 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,11 @@ POLICY_IDS = (
    "POLICY-LOGGING-003",
    "POLICY-LOGGING-004",
    "POLICY-LOGGING-005",
    "POLICY-CONTROL-001",
    "POLICY-CONTROL-002",
    "POLICY-CONTROL-003",
    "POLICY-DATA-PATH-001",
    "POLICY-SKILL-ACTION-001",
 )
 STRUCTURE_PATHS = (
@@ -109,6 +115,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 +480,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 +624,253 @@ 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 TestPolicyDataPath001(unittest.TestCase):
    def test_env_example_has_no_cwd_relative_paths(self) -> None:
        path = os.path.join(get_skill_root(), ".env.example")
        offenders: list[str] = []
        with open(path, encoding="utf-8") as f:
            for lineno, line in enumerate(f, 1):
                stripped = line.strip()
                if not stripped or stripped.startswith("#"):
                    continue
                active = stripped.split("#", 1)[0].strip()
                if re.search(r"=\s*\./", active):
                    offenders.append(f".env.example:{lineno}: {active}")
        self.assertEqual(
            offenders,
            [],
            msg=_policy_msg(
                "POLICY-DATA-PATH-001",
                "development/DATA_PATHS.md",
                "\n".join(offenders) or "CWD-relative ./ paths in .env.example",
            ),
        )
    def test_runtime_paths_exposes_resolve_data_path(self) -> None:
        import util.runtime_paths as rp
        self.assertTrue(callable(getattr(rp, "resolve_data_path", None)))
        self.assertTrue(callable(getattr(rp, "list_resolved_data_paths", None)))
    def test_business_scripts_do_not_abspath_config_get(self) -> None:
        skill_root = get_skill_root()
        pattern = re.compile(r"os\.path\.abspath\s*\(\s*config\.get\b")
        offenders: list[str] = []
        for rel in _walk_files(skill_root, "scripts", suffix=".py"):
            if rel.replace("\\", "/") == "scripts/util/runtime_paths.py":
                continue
            text = _read_text(os.path.join(skill_root, rel))
            for lineno, line in enumerate(text.splitlines(), 1):
                if line.strip().startswith("#"):
                    continue
                if pattern.search(line):
                    offenders.append(f"{rel}:{lineno}: {line.strip()}")
        self.assertEqual(
            offenders,
            [],
            msg=_policy_msg(
                "POLICY-DATA-PATH-001",
                "development/DATA_PATHS.md",
                "\n".join(offenders),
            ),
        )
 _TEMPLATE_PLACEHOLDER_SLUG = "your-skill-slug"
 _RPA_SESSION_TOKENS = ("RpaVideoSession",)
 def _service_has_rpa_video_session(skill_root: str) -> bool:
    service_dir = os.path.join(skill_root, "scripts", "service")
    if not os.path.isdir(service_dir):
        return False
    for rel in _walk_files(skill_root, "scripts/service", suffix=".py"):
        text = _read_text(os.path.join(skill_root, rel))
        if any(token in text for token in _RPA_SESSION_TOKENS):
            return True
    return False
 def _load_actions_json(skill_root: str) -> dict | None:
    path = os.path.join(skill_root, "assets", "actions.json")
    if not os.path.isfile(path):
        return None
    import json
    with open(path, encoding="utf-8") as f:
        return json.load(f)
 class TestPolicySkillAction001(unittest.TestCase):
    def test_skill_action_runtime_doc_exists(self) -> None:
        path = os.path.join(get_skill_root(), "development", "SKILL_ACTION_RUNTIME.md")
        self.assertTrue(
            os.path.isfile(path),
            msg=_policy_msg(
                "POLICY-SKILL-ACTION-001",
                "development/SKILL_ACTION_RUNTIME.md",
                "file missing",
            ),
        )
        text = _read_text(path)
        for marker in ("executionProfile", "async", "任务中心", "run_skill_action"):
            self.assertIn(
                marker,
                text,
                msg=_policy_msg(
                    "POLICY-SKILL-ACTION-001",
                    "development/SKILL_ACTION_RUNTIME.md",
                    f"missing marker {marker!r}",
                ),
            )
    def test_schema_defines_execution_profile(self) -> None:
        import json
        path = os.path.join(get_skill_root(), "assets", "schemas", "skill-actions.schema.json")
        self.assertTrue(os.path.isfile(path))
        with open(path, encoding="utf-8") as f:
            schema = json.load(f)
        action_props = schema.get("$defs", {}).get("action", {}).get("properties", {})
        profile = action_props.get("executionProfile")
        self.assertIsInstance(
            profile,
            dict,
            msg=_policy_msg(
                "POLICY-SKILL-ACTION-001",
                "assets/schemas/skill-actions.schema.json",
                "action.properties.executionProfile missing",
            ),
        )
        self.assertEqual(set(profile.get("enum") or []), {"sync", "async"})
    def test_actions_md_documents_execution_profile(self) -> None:
        path = os.path.join(get_skill_root(), "references", "ACTIONS.md")
        text = _read_text(path)
        for marker in ("executionProfile", "async", "任务中心", "SKILL_ACTION_RUNTIME"):
            self.assertIn(
                marker,
                text,
                msg=_policy_msg(
                    "POLICY-SKILL-ACTION-001",
                    "references/ACTIONS.md",
                    f"missing marker {marker!r}",
                ),
            )
    def test_actions_json_actions_declare_execution_profile(self) -> None:
        skill_root = get_skill_root()
        manifest = _load_actions_json(skill_root)
        if manifest is None:
            return
        offenders: list[str] = []
        for action in manifest.get("actions") or []:
            action_id = action.get("id", "?")
            profile = action.get("executionProfile")
            if profile not in ("sync", "async"):
                offenders.append(f"{action_id}: executionProfile={profile!r}")
        self.assertEqual(
            offenders,
            [],
            msg=_policy_msg(
                "POLICY-SKILL-ACTION-001",
                "assets/actions.json",
                "every action must set executionProfile to sync|async:\n" + "\n".join(offenders),
            ),
        )
    def test_business_rpa_skill_has_async_agent_action(self) -> None:
        from util.constants import SKILL_SLUG
        skill_root = get_skill_root()
        if SKILL_SLUG == _TEMPLATE_PLACEHOLDER_SLUG:
            self.skipTest("template placeholder slug skips business RPA action check")
        if not _service_has_rpa_video_session(skill_root):
            self.skipTest("no RpaVideoSession in scripts/service")
        manifest = _load_actions_json(skill_root)
        self.assertIsNotNone(
            manifest,
            msg=_policy_msg(
                "POLICY-SKILL-ACTION-001",
                "assets/actions.json",
                "RPA skill must provide assets/actions.json",
            ),
        )
        found = False
        for action in manifest.get("actions") or []:
            placements = set(action.get("placements") or [])
            if action.get("executionProfile") == "async" and "agent" in placements:
                found = True
                break
        self.assertTrue(
            found,
            msg=_policy_msg(
                "POLICY-SKILL-ACTION-001",
                "assets/actions.json",
                "RPA business skill needs at least one action with executionProfile=async and placements containing agent",
            ),
        )
 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_runtime_paths.py
+++ b/tests/test_runtime_paths.py
@@ -82,6 +82,68 @@ class TestRuntimePaths(unittest.TestCase):
            self.assertTrue(os.path.normpath(data_dir).startswith(os.path.normpath(tmp)))
            self.assertIn("_test", data_dir.replace("\\", "/"))
    def test_resolve_data_path_defaults_under_skill_data_dir(self) -> None:
        with IsolatedDataRoot() as tmp:
            import importlib
            import util.runtime_paths as rp
            importlib.reload(rp)
            path = rp.resolve_data_path(None, "downloads", create=True)
            norm = os.path.normcase(os.path.normpath(path))
            norm_tmp = os.path.normcase(os.path.normpath(tmp))
            self.assertTrue(norm.startswith(norm_tmp))
            self.assertTrue(norm.endswith(os.path.normcase(os.path.join("downloads"))))
    def test_resolve_data_path_relative_uses_data_dir_not_cwd(self) -> None:
        with IsolatedDataRoot() as tmp:
            import importlib
            import util.runtime_paths as rp
            importlib.reload(rp)
            os.environ["SKILL_DOWNLOAD_DIR"] = "downloads/videos"
            from jiangchang_skill_core import config
            config.reset_cache()
            importlib.reload(rp)
            path = rp.resolve_data_path("SKILL_DOWNLOAD_DIR", "downloads", create=False)
            norm = os.path.normcase(os.path.normpath(path))
            self.assertIn(os.path.normcase("downloads"), norm)
            self.assertIn(os.path.normcase("videos"), norm)
            self.assertTrue(norm.startswith(os.path.normcase(os.path.normpath(tmp))))
            os.environ.pop("SKILL_DOWNLOAD_DIR", None)
            config.reset_cache()
    def test_resolve_input_path_relative_under_imports(self) -> None:
        with IsolatedDataRoot() as tmp:
            import importlib
            import util.runtime_paths as rp
            importlib.reload(rp)
            resolved = rp.resolve_input_path("urls.txt", create_parent=True)
            norm = os.path.normcase(os.path.normpath(resolved))
            self.assertIn(os.path.normcase("imports"), norm)
            self.assertTrue(norm.startswith(os.path.normcase(os.path.normpath(tmp))))
    def test_list_resolved_data_paths_keys(self) -> None:
        with IsolatedDataRoot():
            import importlib
            import util.runtime_paths as rp
            importlib.reload(rp)
            paths = rp.list_resolved_data_paths()
            for key in (
                "skill_data_dir",
                "downloads_dir",
                "imports_dir",
                "exports_dir",
            ):
                self.assertIn(key, paths)
                self.assertTrue(paths[key])
 if __name__ == "__main__":
    unittest.main()
--- 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	a7baba7210	Codify Skill Action sync/async and task-center gold standards (v1.0.40) All checks were successful 技能自动化发布 / release (push) Successful in 7s Details	2026-07-14 07:55:55 +08:00
chendelian	2e5a8d5eed	Add DATA_PATHS golden standard and resolve_data_path helpers. All checks were successful 技能自动化发布 / release (push) Successful in 5s Details Document skill-owned file layout under user data dir, extend runtime_paths with standard subdir helpers, add POLICY-DATA-PATH-001, and update CONFIG/RUNTIME cross-references. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-13 14:14:38 +08:00
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