client-commons/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

同步 Platform Kit 1.0.17 运行时环境变量契约
All checks were successful
技能自动化发布 / release (push) Successful in 4s
Details

Browse Source
This commit is contained in:
chendelian
2026-06-30 14:41:54 +08:00
parent a3bd8faf87
commit d17804e45b
17 changed files with 89 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
development/CONFIG.md
View File

@@ -7,7 +7,7 @@
1. **三层优先级**：`进程环境变量` > `{数据目录}/.env` > 仓库 `.env.example` 默认值。
2. **`.env.example` 进仓库**：带注释的全量默认配置，是配置项的"单一事实来源"。
3. **首次运行自动 copy（bootstrap）**：`scripts/main.py` 启动与 `cli.app.main()` 均会调用 `util.config_bootstrap.bootstrap_skill_config()`，把仓库根目录 `.env.example` 复制到
`{CLAW_DATA_ROOT}/{user}/{slug}/.env`（**已存在则不整体覆盖**，保护用户改过的值）。
`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env`（**已存在则不整体覆盖**，保护用户改过的值）。
4. **技能升级合并缺失项**：`merge_missing_env_keys` 会把 `.env.example` 中新增、但用户 `.env` 尚未包含的 key **追加**进去（带注释块）。
5. **敏感信息绝不进 `.env`**：密码/密钥/口令走 account-manager 的 `secret-ref`（见下"红线"）。
@@ -96,4 +96,4 @@ config.get_float("STEP_DELAY_MIN", 1.0)
- `RPA.md` — 三端 RPA 标准与各开关含义
- `ADAPTER.md` — `OPENCLAW_TEST_TARGET` 四档模式
- `RUNTIME.md` — `CLAW_*` 环境变量与数据目录约定
- `RUNTIME.md` — `JIANGCHANG_*` 环境变量与数据目录约定

4
development/DEVELOPMENT.md
View File

@@ -153,7 +153,7 @@ scripts/
- `util/`
作用：常量、日志、路径、时间工具、通用帮助函数
公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.14` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.17` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
## 3.2 开发 RPA 类 skill
@@ -187,7 +187,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.14`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.17`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
- 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
- **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：

6
development/RPA.md
View File

@@ -51,7 +51,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.14**）。
指纹淡化（stealth）典型项：`navigator.webdriver=undefined`、`chrome.runtime`、`permissions.query`、`plugins`、`languages` 等。共享实现见 `jiangchang_skill_core.rpa`（platform-kit **>= 1.0.17**）。
**拟人操作**（必做）：
@@ -124,7 +124,7 @@ from jiangchang_skill_core.rpa import (
from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
```
- `RpaVideoSession` 来自 platform-kit **>= 1.0.14**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
- `RpaVideoSession` 来自 platform-kit **>= 1.0.17**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
- `health` 对上述资源做只读诊断，不下载、不修复。
### 1.5 真实浏览器 RPA 示例（必读）
@@ -234,7 +234,7 @@ skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层
### 5.1 截图存证
- **路径**：`{CLAW_DATA_ROOT}/{user}/{slug}/rpa-artifacts/{batch_id}/{tag}_{timestamp}.png`
- **路径**：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/rpa-artifacts/{batch_id}/{tag}_{timestamp}.png`
- **失败必截图**：受 `OPENCLAW_ARTIFACTS_ON_FAILURE`（默认开）控制。
- **Playwright 不负责录屏**，仅浏览器自动化。
- **常见 tag**：`before_submit` / `after_submit` / `captcha` / `login_fail` / `error`。

24
development/RUNTIME.md
View File

@@ -2,7 +2,7 @@
## 共享 Python Runtime
**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.14` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.17` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。
@@ -22,15 +22,15 @@ Windows:
<shared-python> {baseDir}/scripts/main.py health
```
`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `CLAW_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `JIANGCHANG_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
## Runtime 诊断（platform-kit 1.0.14+）
## Runtime 诊断（platform-kit 1.0.17+）
`health` 命令通过 **`jiangchang_skill_core.collect_runtime_diagnostics`** 输出共享 runtime 诊断，**不在技能内重复实现**。典型字段：
- `skill_slug`、`python_executable`、`platform_kit_version`、`platform_kit_min_version`
- `jiangchang_skill_core_file` — 若从技能目录加载会输出 `runtime_issue[warning]`
- `CLAW_DATA_ROOT` / `JIANGCHANG_DATA_ROOT` / `resolved_data_root`
- `JIANGCHANG_DATA_ROOT` / `resolved_data_root`
- `media_assets_root`、`ffmpeg_path`、`background_music_*`
- `record_video_enabled`、`runtime_issue[warning|error]`
@@ -39,10 +39,10 @@ Windows:
## 配置 bootstrap
- 仓库内 `.env.example` 是配置模板（单一事实来源）。
- 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。
- 用户实际 `.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.14`，**不得** vendored `scripts/jiangchang_skill_core/`。
- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.17`，**不得** vendored `scripts/jiangchang_skill_core/`。
## media-assets / ffmpeg / 背景音乐
@@ -52,7 +52,7 @@ Windows:
{JIANGCHANG_DATA_ROOT}/shared/media-assets
```
（与 `CLAW_DATA_ROOT` 解析规则一致，由宿主注入。）
（由宿主注入 `JIANGCHANG_DATA_ROOT`。）
RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均由 platform-kit 提供；技能只 import，不重复实现。
@@ -80,7 +80,7 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
推荐：
```text
{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
```
数据库文件建议：
@@ -97,12 +97,12 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
## 测试时的运行时隔离
本模板的 `tests/_support.IsolatedDataRoot` 会在测试期间同时设置：
本模板的 `tests/_support.IsolatedDataRoot` 会在测试期间设置：
- `CLAW_DATA_ROOT` / `JIANGCHANG_DATA_ROOT` → 临时 tempfile 目录
- `CLAW_USER_ID` / `JIANGCHANG_USER_ID` → `_test`
- `JIANGCHANG_DATA_ROOT` → 临时 tempfile 目录
- `JIANGCHANG_USER_ID` → `_test`
退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。
退出时两个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。
详见 `TESTING.md` 第 3 节。

8
development/TESTING.md
View File

@@ -23,9 +23,9 @@
必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖：
- CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟；
- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.14` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.17` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
- **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移；
- 运行时：`runtime_paths` 与 **`CLAW_*` / `JIANGCHANG_*` 并发兜底；
- 运行时：`runtime_paths` 与 **`JIANGCHANG_*` 隔离**；
- `SKILL.md` YAML slug vs [`constants.SKILL_SLUG`](../scripts/util/constants.py)；
- SQLite 骨架：`task_logs` 创建幂等与仓储读写；
- **adapter profile**：[`tests/test_adapter_profile_policy.py`](../tests/test_adapter_profile_policy.py) + [`adapter_test_utils`](../tests/adapter_test_utils.py) ——验证在未授权情况下绝不误判开启真实网络/RPA。
@@ -39,7 +39,7 @@
## 3. 数据隔离：IsolatedDataRoot
[`tests/_support.py`](../tests/_support.py) 提供的上下文管理器 `IsolatedDataRoot()`：进入一个专用临时目录，**镜像写入四套变量**：`CLAW_DATA_ROOT`、`JIANGCHANG_DATA_ROOT`（同一 tempfile）、以及用户镜像 ID：`CLAW_USER_ID`、`JIANGCHANG_USER_ID` → `_test`。
[`tests/_support.py`](../tests/_support.py) 提供的上下文管理器 `IsolatedDataRoot()`：进入一个专用临时目录，写入 `JIANGCHANG_DATA_ROOT`（tempfile）与 `JIANGCHANG_USER_ID` → `_test`。
结束时：**恢复原 environ**，删除目录。
@@ -211,7 +211,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.14**（`SKILL.md` + `constants.py`）
- [ ] `platform_kit_min_version` **>= 1.0.17**（`SKILL.md` + `constants.py`）
- [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行）
- [ ] `config-path` 可输出用户 `.env` 路径 JSON
- [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py`