From 6f958ded2877820c65e10d23e797fcf256746fd7 Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Sun, 12 Jul 2026 12:27:44 +0800 Subject: [PATCH] feat(template): SRCP v1 standards, job_context/finish gold sample (v1.0.38, platform-kit 1.2.0) Co-authored-by: Cursor --- SKILL.md | 8 +- development/DEVELOPMENT.md | 6 +- development/LOGGING.md | 95 ++++++++----- development/POLICY_MATRIX.md | 5 +- development/RPA.md | 24 +++- development/RUNTIME.md | 6 +- development/TESTING.md | 4 +- scripts/service/task_service.py | 171 ++++++++++++++---------- scripts/util/constants.py | 4 +- tests/_support.py | 2 +- tests/test_development_policy_guard.py | 62 +++++++++ tests/test_docs_standards.py | 2 +- tests/test_platform_import.py | 6 +- tests/test_template_runtime_standard.py | 2 +- 14 files changed, 270 insertions(+), 127 deletions(-) diff --git a/SKILL.md b/SKILL.md index cbcd46a..e8b6e2e 100644 --- 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）。 diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index 7a9f920..0b86dea 100644 --- 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` §敏感信息红线）。 diff --git a/development/LOGGING.md b/development/LOGGING.md index 11ba71b..7f842a7 100644 --- 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`（任务结果审计） @@ -202,7 +232,7 @@ batch_progress current=7 total=20 target_id=store-001 ```python from util.logging_config import get_skill_logger -from jiangchang_skill_core.activity import emit +from jiangchang_skill_core.activity import emit, finish, job_context, rpa_step, interruptible_sleep from util.constants import SKILL_SLUG @@ -210,37 +240,40 @@ log = get_skill_logger() def cmd_run(target=None, input_id=None): task_type = "your_task" - log.info( - "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`。 diff --git a/development/POLICY_MATRIX.md b/development/POLICY_MATRIX.md index 530bbc9..c3aa7e8 100644 --- a/development/POLICY_MATRIX.md +++ b/development/POLICY_MATRIX.md @@ -24,6 +24,9 @@ | POLICY-LOGGING-003 | 主任务入口须含 `log.info`/`logger.info`、`log.exception`/`logger.exception`，并写入 `save_task_log` | development/LOGGING.md | hard | 扫描 `scripts/service/task_service.py` | `tests/test_development_policy_guard.py::TestPolicyLogging003` | | POLICY-LOGGING-004 | 长任务 / RPA 模板须使用 Activity 或 RPA video step 输出进度 | development/LOGGING.md；development/RPA.md | hard | 扫描 `scripts/service/task_service.py` 含 `emit(` / `activity.emit` / `video.add_step` | `tests/test_development_policy_guard.py::TestPolicyLogging004` | | POLICY-LOGGING-005 | 交付代码不得在 logging 调用行以 `key=value` 形式记录明显敏感字段 | development/LOGGING.md；development/CONFIG.md | hard | 扫描 `scripts/**/*.py` 的 logging 调用行（不含注释） | `tests/test_development_policy_guard.py::TestPolicyLogging005` | +| POLICY-CONTROL-001 | 不得存在 `scripts/util/progress.py` 或自建 stdout 进度模块 | development/LOGGING.md §2.5；development/RPA.md §0.1 | hard | 文件不存在检查 | `tests/test_development_policy_guard.py::TestPolicyControl001` | +| POLICY-CONTROL-002 | `task_service.py` 须使用 `job_context(` 与 `finish(` | development/LOGGING.md §2.5、§7 | hard | 扫描 `scripts/service/task_service.py` | `tests/test_development_policy_guard.py::TestPolicyControl002` | +| POLICY-CONTROL-003 | `scripts/service/*.py` 不得裸 `asyncio.sleep`（RPA 等待须 `interruptible_sleep`） | development/RPA.md §0.1 | hard | 扫描 service 层 Python | `tests/test_development_policy_guard.py::TestPolicyControl003` | --- @@ -42,4 +45,4 @@ | RPA 拟人操作、选择器纪律、HITL 超时 | development/RPA.md §0–§1 | 行为与 DOM 质量，无法静态扫描 | | adapter 四档契约测试覆盖 timeout/unauthorized 等 | development/ADAPTER.md §contract tests | 需业务实现后人工补测 | | `SKILL.md` / `constants.SKILL_SLUG` 一致性 | development/DEVELOPMENT.md §16 | 已有 `tests/test_skill_metadata.py` | -| platform_kit_min_version >= 1.0.17 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` | +| platform_kit_min_version >= 1.2.0 | development/RUNTIME.md | 已有 `tests/test_platform_import.py` | diff --git a/development/RPA.md b/development/RPA.md index 86509a1..3ad3794 100644 --- 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 示例（必读） diff --git a/development/RUNTIME.md b/development/RUNTIME.md index 3ec809d..f1b32f9 100644 --- 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: `` 通常位于 `{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 / 背景音乐 diff --git a/development/TESTING.md b/development/TESTING.md index 8bc5a03..b2854f8 100644 --- 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)； @@ -260,7 +260,7 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t - [ ] `requirements.txt` **不含** `jiangchang-platform-kit` / `playwright` - [ ] 无 `scripts/jiangchang_skill_core/` vendored 副本 -- [ ] `platform_kit_min_version` **>= 1.0.17**（`SKILL.md` + `constants.py`） +- [ ] `platform_kit_min_version` **>= 1.2.0**（`SKILL.md` + `constants.py`） - [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行） - [ ] `config-path` 可输出用户 `.env` 路径 JSON - [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py` diff --git a/scripts/service/task_service.py b/scripts/service/task_service.py index 433ed21..2381e58 100644 --- 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( diff --git a/scripts/util/constants.py b/scripts/util/constants.py index 0c18b10..4703f7b 100644 --- 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" diff --git a/tests/_support.py b/tests/_support.py index 1856a73..d58b47f 100644 --- 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 diff --git a/tests/test_development_policy_guard.py b/tests/test_development_policy_guard.py index 29516aa..903e541 100644 --- a/tests/test_development_policy_guard.py +++ b/tests/test_development_policy_guard.py @@ -41,6 +41,9 @@ POLICY_IDS = ( "POLICY-LOGGING-003", "POLICY-LOGGING-004", "POLICY-LOGGING-005", + "POLICY-CONTROL-001", + "POLICY-CONTROL-002", + "POLICY-CONTROL-003", ) STRUCTURE_PATHS = ( @@ -619,6 +622,65 @@ class TestPolicyLogging005(unittest.TestCase): ) +class TestPolicyControl001(unittest.TestCase): + def test_no_util_progress_module(self) -> None: + skill_root = get_skill_root() + path = os.path.join(skill_root, "scripts", "util", "progress.py") + self.assertFalse( + os.path.isfile(path), + msg=_policy_msg( + "POLICY-CONTROL-001", + "development/LOGGING.md §2.5; development/RPA.md §0.1", + "scripts/util/progress.py must not exist", + ), + ) + + +class TestPolicyControl002(unittest.TestCase): + def test_task_service_uses_job_context_and_finish(self) -> None: + skill_root = get_skill_root() + path = os.path.join(skill_root, "scripts", "service", "task_service.py") + text = _read_text(path) + rel = _rel(skill_root, path) + missing: list[str] = [] + if "job_context(" not in text: + missing.append("job_context(") + if "finish(" not in text: + missing.append("finish(") + self.assertEqual( + missing, + [], + msg=_policy_msg( + "POLICY-CONTROL-002", + "development/LOGGING.md §2.5、§7", + f"{rel} missing: " + ", ".join(missing), + ), + ) + + +class TestPolicyControl003(unittest.TestCase): + def test_service_layer_has_no_bare_asyncio_sleep(self) -> None: + skill_root = get_skill_root() + offenders: list[str] = [] + for path in _walk_files(skill_root, "scripts/service", suffix=".py"): + rel = _rel(skill_root, path) + for lineno, line in enumerate(_read_text(path).splitlines(), 1): + stripped = line.strip() + if not stripped or stripped.startswith("#"): + continue + if "asyncio.sleep" in stripped: + offenders.append(f"{rel}:{lineno}: {stripped}") + self.assertEqual( + offenders, + [], + msg=_policy_msg( + "POLICY-CONTROL-003", + "development/RPA.md §0.1", + "use interruptible_sleep instead:\n" + "\n".join(offenders), + ), + ) + + class TestPolicyDocs001(unittest.TestCase): def test_policy_matrix_exists_and_lists_policy_ids(self) -> None: skill_root = get_skill_root() diff --git a/tests/test_docs_standards.py b/tests/test_docs_standards.py index 52b535e..f007bd5 100644 --- 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") diff --git a/tests/test_platform_import.py b/tests/test_platform_import.py index 9dfe17a..4482b8f 100644 --- 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: diff --git a/tests/test_template_runtime_standard.py b/tests/test_template_runtime_standard.py index eeae3d6..6230dc0 100644 --- 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", )