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

chore: auto release commit (2026-06-14 11:12:03)
All checks were successful
技能自动化发布 / release (push) Successful in 8s
Details

Browse Source
This commit is contained in:
chendelian
2026-06-14 11:12:04 +08:00
parent 955816c8a7
commit c7d7832749
20 changed files with 466 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
references/ADAPTER.md
View File

@@ -1,108 +0,0 @@
# 适配器标准：真实/仿真 × API/RPA 四档模式
> 凡是"连接三方系统"（ERP、CRM、SaaS、银行等）的 skill，都应采用本文的 **adapter 四档模式**。这样同一套业务逻辑可以在不同档位间切换：开发用 mock、半集成用 simulator、上线用真实，互不影响。
## 为什么要分档
对接一个外部系统，工程上无非四种方式的组合：
| | API（有接口） | RPA（操作界面） |
|---|---|---|
| **真实系统** | `real_api` 真实 API | `real_rpa` 真实界面 |
| **仿真/离线** | `mock` 纯内存/fixture | `simulator_rpa` 仿真站点/桌面仿真 |
### 四档定义
| 档位 | 含义 | 默认策略 |
|------|------|----------|
| **`mock`** | 纯内存或 fixture，**默认单测/CI** | 模板 `.env.example` 默认 `OPENCLAW_TEST_TARGET=mock` |
| **`simulator_rpa`** | 仿真站点或桌面仿真，可半集成 | 开发联调可选 |
| **`real_api`** | 真实 API | **必须** `ALLOW_REAL_API=1` |
| **`real_rpa`** | 真实浏览器/真实系统 | **必须** `ALLOW_REAL_RPA=1` |
- **mock**：纯离线、不联网，给单测 / CI / 开发自测，**保证可重复**。
- **simulator_rpa**：操作仿真平台（如 `sandbox.jc2009.com`），跑端到端流程但不碰生产。
- **real_api**：有官方接口时**首选**（最稳、最快、最易维护）。
- **real_rpa**：没有 API 只能操作生产界面，**风险最高、放最后**。
> 推荐优先级：**real_api > simulator_rpa > real_rpa**，mock 永远保留做 CI。
## 权限开关
未显式授权时**不得**落到真实 API/RPA：
| 变量 | 作用 |
|------|------|
| `ALLOW_REAL_API=1` | 允许 `real_api` 访问真实 HTTP |
| `ALLOW_REAL_RPA=1` | 允许 `real_rpa` 驱动真实浏览器/RPA |
| `ALLOW_WRITE_ACTIONS=1` | 在 `real_*` 下允许**写**操作（提交表单、下单等） |
进程环境变量优先于用户 `.env`（见 `CONFIG.md` 三层优先级）。
## 目录骨架
```
scripts/service/<domain>_adapter/
__init__.py # dispatch：按档位返回对应 adapter 实例
base.py # 数据契约（dataclass）+ AdapterBase 接口
mock.py # 离线仿真，给 CI/单测
real_api.py # 真实系统 API
sim_rpa.py # 仿真平台 RPA
real_rpa.py # 真实系统 RPA（占位，谨慎实现）
```
模板示例：`scripts/service/example_adapter/`（复制改名即用）。
## 档位 dispatch
由 `OPENCLAW_TEST_TARGET` 统一决定用哪个 adapter：
| `OPENCLAW_TEST_TARGET` | adapter | 用途 |
|---|---|---|
| `unit` / `mock` | `MockAdapter` | 单测 / CI，离线 |
| `simulator_rpa` | `SimRpaAdapter` | 开发/演示，操作仿真平台 |
| `real_api` | `RealApiAdapter` | 生产，走官方接口 |
| `real_rpa` | `RealRpaAdapter` | 生产，操作真实界面 |
```python
# __init__.py
def get_adapter():
target = (os.environ.get("OPENCLAW_TEST_TARGET") or "mock").lower()
if target in ("unit", "mock"):
return MockAdapter()
if target == "real_api":
return RealApiAdapter()
if target == "real_rpa":
return RealRpaAdapter()
return SimRpaAdapter()
```
`get_adapter()` 实现应配合 `tests/adapter_test_utils.py` 的 profile 策略：**未授权时不 silently 开启真实网络/RPA**。
## contract tests
每个 adapter **必须覆盖同一套契约测试**（复制 `tests/samples/test_service_contract.py.sample`）：
- 至少覆盖：**timeout**、**unauthorized**、**invalid response**、**empty result**
- **mock 不允许真实网络**
- 使用 `FakeAdapter` 或等价 stub 模拟异常路径
## 兄弟依赖
依赖 account-manager 或其他兄弟技能时：
1. 在 `SKILL.md` 的 `metadata.openclaw.dependencies.required` 声明。
2. 调用兄弟技能走统一 **`service.sibling_bridge`**（`call_sibling_json`），**不要**在 service 层散落 `subprocess.run`。
3. **lease 必须 release**（account-manager 租约）；进程被 kill 后可能残留 lease，需在运维文档说明排查方式（查 account-manager lease 列表 / 手动释放）。
```python
from service.sibling_bridge import call_sibling_json
result = call_sibling_json("account-manager", ["list", "--limit", "10"])
```
## 相关文档
- `RPA.md` — 三端 RPA 技术选型与拟人/反反爬范式
- `CONFIG.md` — `.env` 里如何配置运行模式与目标地址
- `TESTING.md` — 测试 target 与隔离体系

99
references/CONFIG.md
View File

@@ -1,99 +0,0 @@
# 配置标准：`.env` 规范与首次落盘机制
> 解决"每个 skill 每次都要手动搞一堆环境变量、账号、地址"的痛点。统一约定：**模板内置 `.env.example`，skill 首次运行自动落盘到用户数据目录，之后从那里读。**
## 核心原则
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`（**已存在则不整体覆盖**，保护用户改过的值）。
4. **技能升级合并缺失项**：`merge_missing_env_keys` 会把 `.env.example` 中新增、但用户 `.env` 尚未包含的 key **追加**进去（带注释块）。
5. **敏感信息绝不进 `.env`**：密码/密钥/口令走 account-manager 的 `secret-ref`（见下"红线"）。
## 标准配置项（`.env` 分组）
每个 skill 的 `.env.example` 至少包含这些通用项（按需增减）：
```ini
# ── 运行模式 / adapter 档位（见 ADAPTER.md）──
OPENCLAW_TEST_TARGET=mock # mock | simulator_rpa | real_api | real_rpa
# ── 目标系统（示例占位，复制后改为业务地址）──
TARGET_BASE_URL=https://sandbox.jc2009.com
# ── 默认账号（仅非敏感标识；密码走 account-manager）──
DEFAULT_LOGIN_ID=04110001
# ── 浏览器 / RPA ──
OPENCLAW_BROWSER_HEADLESS=0 # 0=有头(默认) 1=无头(CI)
OPENCLAW_PLAYWRIGHT_STEALTH=1 # 1=开启反检测指纹(默认)
# ── 录屏与失败存证 ──
OPENCLAW_RECORD_VIDEO=1 # 1=录屏+字幕+旁白+背景音+MP4（RPA 默认开，见 RPA.md）
OPENCLAW_ARTIFACTS_ON_FAILURE=1 # 1=失败截图(默认)
# ── 节流 / 超时 ──
STEP_DELAY_MIN=1.0
STEP_DELAY_MAX=5.0
HUMAN_WAIT_TIMEOUT=180 # 滑块/验证码/2FA 等人工超时(秒)
```
**业务专属配置必须带技能前缀**（如 `DEMO_XXX`、`MY_SKILL_XXX`），**不要污染全局命名空间**（禁止 `SCRAPE_1688_*`、`RECEIVE_ORDER_*` 等跨技能前缀写入模板）。
## 🚫 红线：敏感信息不进 `.env`
`.env` 只放**非敏感运行参数**（模式、地址、开关、超时、账号标识）。密码、密钥、动态口令、token——
- 走 **account-manager** 注册凭据，用 `--secret-storage env --secret-ref XXX` 引用；
- 真实值由宿主/用户通过进程环境变量注入，**不落任何文件、不进 git**。
`.gitignore` 必须包含：
```gitignore
.env
*.env.local
```
## 配置 bootstrap（模板提供）
模板在 `scripts/util/config_bootstrap.py` 提供 `bootstrap_skill_config()`：
```python
from util.config_bootstrap import bootstrap_skill_config
bootstrap_skill_config() # main.py 与 cli.app.main() 启动时调用
```
内部委托共享 runtime 的 `jiangchang_skill_core.config`：
```python
config.ensure_env_file(SKILL_SLUG, example_path) # 首次落盘
config.merge_missing_env_keys(example_path, env_path) # 升级后追加缺失 key
```
业务代码**只通过 `config.get*` 读配置**，不直接 `os.environ`：
```python
config.get("TARGET_BASE_URL")
config.get_bool("OPENCLAW_BROWSER_HEADLESS")
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` 绝对路径），便于排查落盘位置。
## doctor / setup 命令（可选）
每个 skill 可提供自检命令：
- `python scripts/main.py doctor`：检查浏览器、Profile/账号、`.env` 落盘、设备等。
- `python scripts/main.py setup`：初始化演示账号、首次落盘 `.env`。
## 相关文档
- `RPA.md` — 三端 RPA 标准与各开关含义
- `ADAPTER.md` — `OPENCLAW_TEST_TARGET` 四档模式
- `RUNTIME.md` — `CLAW_*` 环境变量与数据目录约定

728
references/DEVELOPMENT.md
View File

@@ -1,728 +0,0 @@
# 技能开发教程
这份文档是给**技术人员**看的，目标不是解释概念，而是让你拿到 `skill-template` 后，可以**一步一步开发出一个新的 skill**。
本文默认你开发的是当前最常见的一类业务 skill：
- 有明确的 `scripts/main.py` CLI 入口
- 可能需要读写本地 SQLite（例如任务日志 `task_logs`）
- 可能需要调用兄弟技能或外部 HTTP / RPA
- 业务逻辑主要放在 `scripts/service/`
发布、对账、代发、报表分析等场景都只是业务特例；模板提供通用骨架，复制后按领域补齐实现即可。
## 推荐 AI 开发工具
当前 skill 开发建议尽量配合 AI 编程工具使用。这样做不是为了替代技术人员，而是为了提升以下环节的效率：
- 搭建标准目录结构
- 生成样板代码
- 理解旧项目代码
- 批量补文档、注释和测试
- 辅助排查报错与重构代码
建议团队统一选择 1 到 2 个主力工具长期使用，避免每个人工具链差异太大，导致协作方式不一致。
下面先列国外主流工具，再列国内主流工具。链接优先使用官方站点、官方文档或官方安装入口。
### 国外主流工具
| 工具 | 类型 | 适合场景 | 官方入口 |
|------|------|----------|----------|
| Cursor | 独立 AI IDE | 代码编辑、Agent 开发、整仓理解 | <a href="https://www.cursor.com/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.cursor.com/downloads" target="_blank" rel="noopener noreferrer">下载</a> |
| Windsurf | 独立 AI IDE | Agent 编程、项目生成、连续开发流 | <a href="https://docs.codeium.com/windsurf" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://windsurf.com/download" target="_blank" rel="noopener noreferrer">下载</a> |
| GitHub Copilot | IDE 插件 / 编程助手 | 日常补全、解释代码、生成函数、配合 VS Code 或 JetBrains 使用 | <a href="https://github.com/copilot" target="_blank" rel="noopener noreferrer">官网</a> |
| Claude Code | 终端 / IDE 编程代理 | 命令行开发、代码库分析、自动改代码、运行命令 | <a href="https://www.anthropic.com/claude-code" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://docs.anthropic.com/en/docs/claude-code/" target="_blank" rel="noopener noreferrer">文档</a> |
| Codex | 终端 / IDE / Web 编程代理 | OpenAI 官方编码代理，适合代码生成、理解、调试、评审 | <a href="https://developers.openai.com/codex/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://developers.openai.com/codex/quickstart" target="_blank" rel="noopener noreferrer">快速开始</a> |
| Aider | 终端 AI 编程工具 | 已有代码仓库的增量开发、终端协作、快速提交 | <a href="https://www.aider.chat/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://aider.chat/docs/" target="_blank" rel="noopener noreferrer">文档</a> |
| Cline | VS Code / JetBrains 插件 | 编辑器内 Agent 开发、命令执行、浏览器联动调试 | <a href="https://cline.bot/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://docs.cline.bot/introduction/welcome" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
### 国内主流工具
| 工具 | 类型 | 适合场景 | 官方入口 |
|------|------|----------|----------|
| Trae | 独立 AI IDE | AI 辅助写代码、项目搭建、对话式开发 | <a href="https://www.trae.ai/home" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.trae.ai/download" target="_blank" rel="noopener noreferrer">下载</a> |
| 通义灵码 | 独立 IDE / IDE 插件 | 国内团队日常编码、问答、补全、代码生成 | <a href="https://tongyi.aliyun.com/lingma/?channel=yy_AiBot" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://tongyi.aliyun.com/lingma/download" target="_blank" rel="noopener noreferrer">下载</a> |
| CodeGeeX | IDE 插件 / 开源助手 | 代码补全、生成、注释、跨语言辅助 | <a href="https://github.com/zai-org/CodeGeeX" target="_blank" rel="noopener noreferrer">GitHub</a> / <a href="https://marketplace.visualstudio.com/items?itemName=aminer.codegeex" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
| 腾讯 CodeBuddy | IDE 插件 | 代码补全、测试生成、智能问答、腾讯云开发体系协作 | <a href="https://www.codebuddy.ai/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.tencentcloud.com/document/product/1256" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://marketplace.visualstudio.com/items?itemName=Tencent-Cloud.coding-copilot" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
| 百度文心快码（Baidu Comate） | IDE 插件 | 国内研发团队辅助编码、解释、测试、优化 | <a href="https://comate.baidu.com/zh" target="_blank" rel="noopener noreferrer">官网</a> |
### 选型建议
如果你们团队主要做这类 Python skill 开发，我建议这样选：
- 想要一体化最强体验：优先试 `Cursor` 或 `Windsurf`
- 想要命令行深度协作：优先试 `Claude Code` 或 `Aider`
- 想继续基于 VS Code 插件体系：优先试 `GitHub Copilot`、`Cline`、`通义灵码`、`CodeBuddy`
- 想优先使用国内生态与中文支持：优先试 `Trae`、`通义灵码`、`CodeGeeX`、`CodeBuddy`、`文心快码`
### 团队落地建议
为了减少培训成本，建议内部至少统一一套主工具方案：
- 国外方案：`Cursor` + `Claude Code`
- 国内方案：`Trae` + `通义灵码`
- VS Code 插件方案：`GitHub Copilot` + `Cline`
不建议每位技术人员完全自由发挥，否则后续在：
- 提示词写法
- 代码修改习惯
- 调试方式
- 提交节奏
这些方面会越来越不统一。
## 1. 先理解模板的定位
`skill-template` 不是业务 skill，它只是一个**新 skill 仓库模板**。
你不应该直接在这个仓库里开发业务，而应该：
1. 复制这个目录
2. 改成新 skill 的目录名
3. 把占位内容替换掉
4. 再开始写业务逻辑
## 2. 新 skill 的标准目录结构
复制模板后，你应该保留下面这套结构：
```text
your-skill/
├─ .github/
├─ assets/
├─ evals/
├─ references/
├─ scripts/
│ ├─ cli/
│ ├─ db/
│ ├─ service/
│ └─ util/
├─ tests/
├─ .gitignore
├─ README.md
├─ requirements.txt
├─ release.ps1
└─ SKILL.md
```
各目录职责如下：
- `assets/`：放示例输出、schema、静态说明资源
- `references/`：放研发和编排需要长期维护的文档
- `scripts/`：放真正的代码
- `tests/`：放自动化测试
- `evals/`：放人工验收材料、评估清单、示例场景
## 3. `scripts/` 内部如何分层
`scripts/` 不是乱放 Python 文件，而是按职责分层：
```text
scripts/
├─ main.py
├─ cli/
├─ db/
├─ service/
└─ util/
```
每层的职责要明确：
- `main.py`
作用：唯一 CLI 入口
只做启动、编码兼容、引入 `cli.app`
- `cli/`
作用：参数解析、命令分发、用法说明
不写具体业务逻辑
- `db/`
作用：SQLite 连接、建表、repository
不写页面操作和业务编排
- `service/`
作用：核心业务逻辑
比如任务编排、调用兄弟技能、外部 API、可选浏览器自动化
- `util/`
作用：常量、日志、路径、时间工具、通用帮助函数
公共能力（config、logging、runtime_env、rpa、media_assets、video_session、runtime_diagnostics）从共享 runtime 的 `jiangchang-platform-kit>=1.0.13` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
## 3.2 开发 RPA 类 skill
若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地：
1. **先读三份标准**：`references/RPA.md`（三端范式与反反爬）、`references/CONFIG.md`（`.env` 落盘与读取）、`references/ADAPTER.md`（四档 adapter）。
2. **从模板复制骨架**：
- `scripts/service/example_adapter/` → 改名为 `scripts/service/<domain>_adapter/`
- 参考 `scripts/service/example_browser_rpa.py` 写浏览器会话逻辑
3. **只用共享库，不在 skill 里重写反反爬**：
```python
from jiangchang_skill_core import config
from jiangchang_skill_core.rpa import launch_persistent_browser, anti_detect, wait_for_captcha_pass
```
上述 import 来自宿主共享 runtime 安装的 `jiangchang-platform-kit`，不是技能目录副本。
4. **mock 档必须离线可跑**（`OPENCLAW_TEST_TARGET=mock`）；sim_rpa / real_* 按需单独测。
5. **桌面/手机**：本期标准见 RPA.md 第 2/3 节，复用 `jiangchang_desktop_sdk` / `screencast`，**不要在新 skill 里重复造包**（尚待实战验证）。
---
### 3.1 `requirements.txt` 依赖规范
技能根目录的 `requirements.txt` 是**标准文件**，用于声明本技能**特有** Python 三方依赖。
- **公共依赖**（`jiangchang-platform-kit`、`playwright`、config、runtime diagnostics、RPA 公共能力等）由**宿主共享 runtime** 提供，**不要**写入技能 `requirements.txt`。
- `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version`（当前 `1.0.13`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** pip 依赖声明。
- 匠厂宿主安装/更新技能后，会将技能 `requirements.txt` 安装到共享 venv：`{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- **不要**在业务代码中 `subprocess` / `pip install`；缺依赖由 `health` 报错，由宿主负责安装。
- **版本约束尽量收窄**，降低多技能共享 venv 时的冲突风险。推荐范围写法：
- `pkg>=1.2.0,<2`
- 对**原生扩展 / 高风险依赖**（如 `chromadb`、`onnxruntime`）建议 pin 或窄范围，避免无上限：
- 不推荐：`chromadb>=0.5.0`
- 推荐：`chromadb>=0.5.23,<0.6`
- **不要**把系统组件（VC++ Runtime、浏览器安装包等）写进 `requirements.txt`；这类前置条件写在 `health` / preflight 文档与错误提示中。
- 若技能无额外 Python 依赖，可保留空文件或仅含注释说明；**不要**为 platform-kit 或 playwright 保留占位行。
- 独立本地开发环境若缺少公共包，可手动安装；**生产/宿主运行**由共享 runtime 负责。
### 3.3 公共能力不要复制
以下模块由 platform-kit 提供，技能内**不要**重复实现或 vendored 拷贝：
| 能力 | 导入方式 |
|------|----------|
| config | `from jiangchang_skill_core import config` |
| logging | `from jiangchang_skill_core.unified_logging import ...` 或 `util.logging_config` 薄封装 |
| runtime_env | `from jiangchang_skill_core.runtime_env import ...` 或 `util.runtime_paths` 薄封装 |
| rpa | `from jiangchang_skill_core.rpa import ...` |
| media_assets | `from jiangchang_skill_core.media_assets import ...` |
| video_session | `from jiangchang_skill_core.rpa.video_session import RpaVideoSession` |
| runtime_diagnostics | `from jiangchang_skill_core import collect_runtime_diagnostics, format_runtime_health_lines` |
`health` 应委托 `collect_runtime_diagnostics`，不要在 `scripts/util/` 自建 `runtime_diagnostics.py`。
## 4. 开发一个新 skill 的标准步骤
下面这套顺序建议严格按步骤做，不要一上来就直接写 `service`。
### 第一步：复制模板并改目录名
例如你要开发 `your-skill-slug`（或 `disburse-payroll-icbc` 一类领域 skill）：
1. 复制 `skill-template`
2. 新目录改成与 `slug` 一致的名称（如 `your-skill-slug`）
3. 初始化为独立 git 仓库
4. 关联它自己的远端仓库
目录名要和 skill slug 对齐，后面很多地方都依赖这个命名。
### 第二步：先改 4 个最关键的标识
复制后优先改下面这些地方：
1. `SKILL.md`
2. `scripts/util/constants.py`
3. `references/` 下的文案
4. `scripts/service/` 下的业务占位实现（优先改 `task_service.py`）
最先要统一的是：
- 技能中文名
- `slug`
- 平台中文名
- 平台内部键
- 日志 logger 名
此外，如果该技能发布后默认不公开（`access_scope = 0`），建议一开始就把 `SKILL.md` 中的 `metadata.openclaw.developer_ids` 配好。这样后续发布到平台时，开发者本人仍能在技能市场中看到并验证该技能。
## 5. 哪些占位内容必须替换
复制后，至少要全局检查并替换下面这些内容：
- `your-skill-slug`
- `your-platform-key`（若 skill 涉及外部平台对接，可能会用到这类占位）
- `技能开发模板（通用业务版）`
- `你的平台名`
- `openclaw.skill.your_skill_slug`
如果你的 skill 对外 CLI 需要自定义文案或别名（例如发布类对外仍叫 `publish`），通常还要替换：
- `run` 命令中的中文提示与别名策略（见 `references/CLI.md`）
- `references/CLI.md` 的命令示例
- `references/README.md` 的用户话术
- `references/SCHEMA.md` 的字段映射补充说明
如需浏览器自动化，不要在模板里保留空的 `platform_playwright.py`；请按业务新建 `xxx_playwright.py`（命名自定），并在 `task_service.py` 中按需引用。
## 6. `SKILL.md` 应该怎么写
`SKILL.md` 是技能清单，不是设计文档。
应该重点写：
- 技能名称
- 技能描述
- `slug`
作用：技能的唯一英文标识，通常用于仓库名、发布包名、运行时目录名、平台主键匹配等
示例：`your-skill-slug`、`disburse-payroll-icbc`、`tax-invoice-verify`
- `category`
作用：技能在平台中的分类，用于市场展示与归类，不是代码内部键
示例：`通用`、`内容`、`办公协作`、`物流`、`抖音`、`小红书`
- `developer_ids`（如需给非公开技能自动补开发者可见权限）
作用：声明发布后默认拥有可见权限的开发者用户 ID 列表
- `dependencies`
作用：声明该技能依赖的兄弟技能或运行前置能力，便于平台或编排层识别依赖关系
示例（按业务填写；发布类可能会依赖账号 / 内容技能，其它领域可能完全不同）：
```yaml
dependencies:
required:
- some-sibling-skill
```
- 何时使用本技能
- 对用户的引导话术
- CLI 使用原则
不要在 `SKILL.md` 里写大量实现细节。
实现细节放在：
- `references/`
- 代码注释
- `service/` 实现里
### 关于 `metadata.openclaw.developer_ids`
这是一个平台发布元数据字段，用于解决下面这个问题：
- 技能发布后若平台记录中的 `access_scope = 0`，技能默认不公开
- 如果不额外授权，连开发者自己也可能在技能市场里看不到这个技能
因此可以在 `SKILL.md` 中声明：
```yaml
metadata:
openclaw:
slug: your-skill-slug
category: 通用
developer_ids:
- 1032
- 12428
```
约定如下：
- 只允许填写正整数用户 ID
- 推荐使用数组，即使当前只有 1 个开发者
- 发布时平台会把这些用户自动补写到 `skill_user_access`
- 第一个 ID 会同步到 `skills.developer_id`
- 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权
## 7. `references/` 应该放什么
`references/` 是当前规范 skill 的文档中心，建议至少有这些：
- `README.md`
面向内部说明和技能作用介绍
- `CLI.md`
写清楚命令、参数、默认值、兄弟技能调用方式
- `RUNTIME.md`
写清楚运行时目录、环境变量、入口约定
- `SCHEMA.md`
写清楚数据库路径、核心表结构、日志表结构
- `DEVELOPMENT.md`
写给技术人员的开发教程，也就是本文档
- `TESTING.md`
写给技术人员的测试分层、隔离数据根与档位开关指南（详见 [`references/TESTING.md`](TESTING.md)）
如果后面某个 skill 需要更细的说明，可以再加：
- `ERRORS.md`
- `INTEGRATION.md`
- `PLATFORMS.md`
## 8. `assets/` 应该放什么
`assets/` 不放业务代码，只放辅助材料。
建议放：
- `examples/`
比如 `version` 输出示例、`log-get` 输出示例
- `schemas/`
比如日志记录、机读 JSON 的 schema
不要把正式研发文档放到 `assets/`。
文档应该进 `references/`。
## 9. `cli` 层怎么写
建议保持一个原则：
- `cli` 只负责解析参数和路由
- `service` 才负责干活
也就是说，`cli/app.py` 的职责是：
1. 打印帮助
2. 定义 `run / logs / log-get / health / version`
3. 把参数转交给 `service.task_service`
不要在 `cli/app.py` 里直接写：
- 浏览器自动化
- 子进程调用兄弟技能
- SQLite 逻辑
## 10. `service` 层怎么写
`service` 是核心层。
通常可以这样拆：
- `task_service.py`
放命令编排、参数兜底、结果分流（例如 `cmd_run`）
- `sibling_bridge.py`
放通用兄弟技能子进程工具（`call_sibling_json`）；**具体调用哪个 slug 由业务在 `task_service.py` 决定**，不要在本文件硬编码发布类专用 helper
- `xxx_playwright.py`（按需新建）
浏览器后台自动化 **不在模板默认结构中**；若确有需要，按命名约定自建模块并在 `task_service.py` 引用
- `entitlement_service.py`
放鉴权逻辑
### 一个很重要的原则
不要把所有逻辑都堆进一个文件。
推荐流向是：
`cli.app` -> `service.task_service` -> `service.sibling_bridge` / （可选）`service.xxx_playwright` -> `db`
## 11. `db` 层怎么写
如果你的 skill 需要记录日志或本地状态，建议：
- `db/connection.py`
只做连接和建表
- `db/task_logs_repository.py`
只做增删查改（模板默认表：`task_logs`）
不要在 `db` 层里：
- 调浏览器
- 打印用户提示
- 拼接业务流程
## 12. 如何接兄弟技能
如果 skill 要依赖兄弟 skill，不要在业务代码里写死绝对路径。
统一通过：
- `scripts/util/runtime_paths.py`
- `scripts/service/sibling_bridge.py`
来做调用。
调用哪些兄弟技能由具体业务决定；请在 `task_service.py` 中使用 `service.sibling_bridge.call_sibling_json(skill_slug, args)` 或 `get_sibling_main_path(skill_slug)`，不要在本模板仓库的 `sibling_bridge.py` 中堆积特定技能函数。
调用原则：
1. 通过 `get_skills_root()` 找到兄弟技能根目录
2. 再拼出对应 `scripts/main.py`
3. 用子进程调用
4. 机器可读输出优先 JSON
## 13. 如何开发一个新 skill
不管你开发的是发布类、采集类、分析类还是知识库类 skill，建议都先按下面这个顺序推进：
1. 先把目录结构搭完整
2. 先让 `health` / `version` 跑通
3. 再把核心 `service` 骨架跑通
4. 再接兄弟技能桥接、数据库或外部系统
5. 最后再补浏览器自动化、复杂流程编排或高风险集成
不要一开始就直接写页面选择器、复杂接口编排或深层业务逻辑。
推荐先确保这些基础能力正常：
- CLI 入口能跑通
- 基础命令输出稳定
- 关键依赖能取到
- 日志或本地状态能落下来
- 错误返回值格式定好了
如果你的 skill 属于外联型 / RPA 型，可以把上面的“核心 `service`”具体落成 `task_service.py`，再按需接 `sibling_bridge.py`、（可选）`*_playwright.py`。这只是示例路径组合，不代表模板绑定某一业务领域。
## 14. 本地开发的最小验证顺序
建议每次新 skill 开发时按下面顺序验证：
### 1. 验证入口
```bash
python scripts/main.py health
python scripts/main.py version
```
### 2. 验证 CLI 路由
```bash
python scripts/main.py -h
python scripts/main.py <your-command> -h
```
### 3. 验证本地日志与数据库
如果你的 skill 需要本地日志或数据库，再继续：
```bash
python scripts/main.py <your-log-command>
python scripts/main.py <your-detail-command> <id>
```
如果你沿用了模板中的通用任务日志骨架，那么这里可以具体对应成：
```bash
python scripts/main.py logs
python scripts/main.py log-get 1
```
### 4. 最后再验证真实业务
比如：
```bash
python scripts/main.py <your-command>
```
## 14.5 测试驱动的开发顺序
新 skill 不应该等所有业务做完才补测试。建议在每个开发阶段都先把对应测试跑一遍：
1. **目录搭建后**：跑 `python tests/run_tests.py -v`，确认全部默认测试套件通过。
- 此时 `test_skill_metadata.py` 会校验 `SKILL.md` slug 与 `constants.SKILL_SLUG` 一致；如果你只改了一边，会立刻发现。
2. **改完 constants 后**：再跑一次必跑套件，确认未引入回归。
3. **写完 service 业务后**：从 `tests/samples/test_service_contract.py.sample` 复制一份做契约测试。
4. **接外部系统时**：写在 `tests/integration/`，并配合 `OPENCLAW_TEST_TARGET` 显式开启。
详见 `references/TESTING.md`。
## 15. 发布到正式环境验证
在执行 `release.ps1` 之前，必须先在本地确认 `python tests/run_tests.py -v` 通过。测试不通过不得发起正式发布。
当本地开发、自测和联调完成后，还需要把 skill 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。
### 第一步：在 skill 根目录执行 `release.ps1`
在当前 skill 仓库根目录执行：
```powershell
.\release.ps1
```
如果你的技能使用了 `metadata.openclaw.developer_ids`，那么这一步触发的发布工作流除了同步 `skills` / `skill_versions` 外，还会在平台侧自动补开发者可见权限。测试非公开技能时，建议重点验证这部分是否生效。
这一步会自动完成标准发布动作，包括：
1. 检查当前仓库状态
2. 自动提交尚未提交的改动
3. 推送最新代码到远程仓库
4. 自动创建新的语义化版本 tag
5. 推送 tag，触发后续 CI 流程
如果你只是想先预览发布动作，可以先执行：
```powershell
.\release.ps1 -DryRun
```
### 第二步：到 Gitea 仓库查看工作流
发布命令执行完成后，远程仓库会自动触发 Gitea 工作流。此时应立即进入对应 skill 的仓库页面，切换到“工作流”页签查看执行状态。
重点确认：
- 是否已经出现最新一次发布记录
- 是否由最新提交触发
- 是否成功执行完 `release_skill.yaml`
下面这张图演示了在仓库页进入“工作流”的位置：
![Gitea 仓库工作流入口](../assets/screenshots/gitea-workflow-tab.png)
下面这张图演示了工作流成功后的状态页面：
![Gitea 工作流成功示例](../assets/screenshots/gitea-workflow-success.png)
### 第三步：确认工作流执行成功
只有当工作流状态为成功，才说明正式发布产物已经正确构建完成。
如果工作流失败，不要继续做平台验证，而应该先回到代码仓库排查，例如：
- 发布脚本是否正常推送
- `SKILL.md`、`scripts/`、`references/` 是否齐全
- 工作流文件是否存在
- 发布包结构是否符合模板规范
### 第四步：进入匠厂平台下载安装包
当工作流成功后，就可以进入匠厂平台验证最终安装效果。
匠厂产品下载地址：
- [https://jc2009.com/product.html](https://jc2009.com/product.html)
打开页面后，下载并安装匠厂客户端。下面这张图演示了下载入口位置：
![匠厂客户端下载入口](../assets/screenshots/jc2009-download-page.png)
匠厂产品页可从这里进入：[产品下载 - 匠厂](https://jc2009.com/product.html)
### 第五步：安装匠厂后，在技能市场检查最新 skill
安装并启动匠厂后，进入左侧“技能市场”，搜索或查找刚刚发布的 skill，确认以下内容：
- 技能可以被正常检索到
- 技能名称、说明、版本信息正确
- 最新版本已经同步出来
- 可以正常安装或更新
下面这张图演示了在技能市场中查看已发布 skill 的位置：
![技能市场中的已发布技能](../assets/screenshots/market-installed-skill.png)
### 第六步：安装并实际启用该 skill
在技能市场中找到目标 skill 后，执行安装或更新操作，确保客户端本地已经拿到最新版本。
这一步建议至少确认：
- 安装按钮可以正常执行
- 安装后状态正常
- 不会出现缺文件、缺入口或安装失败的问题
### 第七步：在“新建任务”中实际使用该 skill
安装完成后，不要只停留在“已安装”状态，还需要进入“新建任务”页面，真正调用一次该 skill，完成最终验证。
建议至少验证：
- 新任务中可以正常选择或触发该 skill
- skill 能被正确唤起
- 主要命令或主流程可以运行
- 返回结果、日志和行为符合预期
下面这张图演示了安装后在任务界面中实际使用 skill 的场景：
![新建任务中使用技能](../assets/screenshots/new-task-usage.png)
## 16. 发布前检查清单
每个新 skill 发布前，建议技术人员逐条确认：
- [ ] 目录结构符合当前模板
- [ ] `SKILL.md` 中 slug、名称、描述都已替换
- [ ] `scripts/util/constants.py` 已修改
- [ ] `references/CLI.md` 示例命令已改成真实命令
- [ ] `service` 下的核心业务文件（如 `task_service.py`）已按领域改名并实现
- [ ] 没有残留旧平台名
- [ ] `health` / `version` 可运行
- [ ] `.gitignore` 生效，没有把 `__pycache__` 提交进去
- [ ] `release.ps1` 存在
- [ ] `.github/workflows/release_skill.yaml` 存在
- [ ] `python tests/run_tests.py -v` 全部通过
- [ ] 没有新增默认必跑测试访问真实网络或浏览器
- [ ] 如有 integration 测试需求，已写在 `tests/integration/` 下并保持 `.sample` 后缀
## 17. 常见错误
### 错误 1：只改了目录名，没改 slug
表现：
- 数据目录不对
- 版本输出不对
- 日志名不对
要检查：
- `SKILL.md`
- `scripts/util/constants.py`
### 错误 2：平台中文名改了，内部键没改
表现：
- 兄弟技能筛选账号失败
- `run` 命令走错平台或 task_type
要检查：
- `task_service.py`
- `sibling_bridge.py`
- `references/CLI.md`
### 错误 3：把业务逻辑写进 CLI
表现：
- 文件越来越乱
- 不方便测
- 参数和业务耦合太重
要改回：
- `cli` 只做参数解析
- `service` 才做业务
### 错误 4：保留了旧模板结构
表现：
- 仓库同时存在 `docs/`、`optional/`、`skill_main.py`
- 技术人员不知道看哪一套
现在的新模板原则是：
- 不做旧结构兼容
- 统一走 `references/` + `scripts/main.py`
## 18. 推荐开发顺序总结
如果让一个新人照着做，我建议他按这个顺序：
1. 复制模板并改目录名
2. 改 `SKILL.md`
3. 改 `scripts/util/constants.py`
4. 改 `references/`
5. 改 `scripts/cli/app.py`
6. 改 `scripts/service/`
7. 跑 `python tests/run_tests.py -v`
8. 跑 `health` / `version`
9. 再做业务联调
10. 最后 release
## 19. 这份模板的底线要求
以后新建 skill，至少要满足这几点：
- 目录结构统一
- 入口统一为 `scripts/main.py`
- 文档统一放 `references/`
- 业务核心逻辑统一放 `scripts/service/`
- 不再使用旧模板历史结构
如果做不到这些，后面 skill 一多，就会越来越乱。

84
references/README.md
View File

@@ -1,77 +1,13 @@
---
description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
---
# Agent 参考索引
# 【技能名称】
本目录供 Agent **运行、编排、调用** skill 时渐进式加载，不是用户市场说明。
用一两句话说明这个技能帮助用户完成什么工作。
这里不要解释技术实现，要从用户的业务目标出发描述价值。
| 文档 | 用途 |
|------|------|
| 根目录 [`README.md`](../README.md) | 用户市场详情页说明 |
| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口 |
| [`CLI.md`](CLI.md) | 命令行入口、参数与调用契约 |
| [`SCHEMA.md`](SCHEMA.md) | 输入输出、数据库与字段说明 |
| [`../development/`](../development/) | 开发、测试、技术规范（给开发者 / AI 编程代理） |
## 这个技能能帮你做什么
用 3 到 6 条业务能力说明技能价值，例如：
- 【自动整理/查询/生成/同步/核对/提交】某类业务数据
- 帮你减少重复操作，降低人工录入或核对成本
- 在任务完成后给出清晰的处理结果、失败原因或后续建议
## 适合什么场景
列出典型使用场景。请使用用户熟悉的业务语言，例如：
- 每天需要重复处理同一类订单、单据、报表或客户资料
- 需要从多个系统中查询信息并汇总结果
- 需要按固定规则检查数据是否完整、是否异常
- 需要把处理结果保存为文件、记录或任务报告
## 使用前需要准备什么
说明用户在使用前要准备的东西，例如：
- 相关账号已登录，且具备查询、导出或提交权限
- 需要处理的文件、时间范围、订单号、客户名称、项目名称等信息
- 如果涉及外部系统，请确认网络、账号、验证码或审批流程可正常使用
## 你可以这样告诉 Agent
用自然语言示例展示用户可以怎么发起任务，例如：
- “帮我查询今天的【业务对象】，整理成表格。”
- “帮我核对这些【数据/单据】是否有异常，并告诉我问题在哪里。”
- “帮我把【时间范围】内的【业务数据】导出并生成处理报告。”
- “帮我根据这个文件里的内容，逐条完成【业务动作】。”
注意：示例应是自然语言，不要写命令行命令。
## 执行后你会得到什么
说明用户会看到什么结果，例如：
- 任务是否成功完成
- 处理了多少条数据
- 哪些内容成功、哪些失败
- 失败原因和建议处理方式
- 生成的文件、表格、报告或记录
## 注意事项
用用户能理解的方式说明边界和风险，例如：
- 请确认输入范围准确，避免处理错数据
- 涉及提交、付款、删除、审批等高风险动作时，技能应在执行前请求确认
- 如果外部系统登录失效、权限不足或页面变化，任务可能需要用户介入
- 不建议在未核对数据的情况下直接执行批量操作
## 常见问题
### 为什么任务没有查到数据？
可能是时间范围、关键词、账号权限或系统筛选条件不正确。请先确认输入信息是否准确。
### 为什么任务执行到一半需要我操作？
可能遇到了登录、验证码、权限确认、二次审批或系统异常。请根据 Agent 的提示完成必要操作。
### 结果文件在哪里查看？
请根据 Agent 返回的结果说明查看生成文件、任务记录或处理报告。
按需阅读：编排任务时优先 `CLI.md`；解析结构化字段时读 `SCHEMA.md`；运行时环境细节见 `../development/RUNTIME.md`。

356
references/REQUIREMENTS.md
View File

@@ -1,356 +0,0 @@
# 技能需求文档模板
这份文档用于给技术人员、产品人员和实施人员统一描述某个 skill 的研发需求。
建议原则：
- 一个 skill 对应一份主需求文档
- 需求先写清楚，再进入开发
- 文档描述“要做什么”和“做到什么程度”，不要在这里堆实现细节
- 实现方式、代码结构、发布流程，分别放到 `DEVELOPMENT.md`、`CLI.md`、`SCHEMA.md`、`RUNTIME.md`
如果你是从 `skill-template` 复制新技能，请复制本文件后，把下面所有占位内容替换成你的真实项目内容。
---
# REQUIREMENTS
## 1. 文档目标
说明这份需求文档的作用，以及它解决什么问题。
模板写法：
- 本文档用于明确 `【技能名称】` 的研发范围、交付标准、依赖关系和验收要求。
- 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。
示例：
- 本文档用于明确 `your-skill-slug`（示例：`disburse-payroll-icbc`）的研发范围、交付标准、依赖关系和验收要求。
## 2. 业务背景
说明为什么要做这个 skill，它服务什么业务场景，解决什么实际问题。
模板写法：
- 当前业务场景中，用户需要在 `【目标平台】` 完成 `【业务动作】`。
- 现有流程主要依赖人工处理，存在 `【效率低 / 容易出错 / 不可批量 / 不可追踪】` 等问题。
- 因此需要开发 `【技能名称】`，将该流程标准化、自动化，并接入匠厂技能体系中。
示例：
- 当前财务团队需要将工资代发批次与银行接口对账，人工导出表格、核对差异耗时且易错。
- 因此需要开发 `disburse-payroll-icbc`，用于自动拉取代发结果、写入任务日志 `task_logs` 并输出对账摘要，支持审计追踪。
## 3. 开发目标
说明本次开发希望最终交付什么结果。
模板写法：
- 完成 `【技能名称】` 的标准目录结构搭建
- 完成 CLI 入口与基础命令
- 完成核心业务流程
- 完成与兄弟技能或外部系统的必要集成
- 完成正式环境发布验证
示例：
- 完成 `your-skill-slug` 的标准 skill 结构建设
- 提供 `health`、`version`、`run`、`logs`、`log-get` 等命令
- 支持对接银行 / 薪酬系统 API（示例），并记录任务执行结果
- 支持写入任务日志 `task_logs`，并可在正式环境中安装验证
## 4. 功能范围
说明这次开发明确要实现哪些功能。
模板写法：
- 支持 `【命令1】`
- 支持 `【命令2】`
- 支持读取 `【数据来源】`
- 支持执行 `【核心业务动作】`
- 支持记录 `【日志 / 状态 / 结果】`
建议将功能拆成“必须实现”和“可后续扩展”。
示例：
### 必须实现
- 支持 `python scripts/main.py health`
- 支持 `python scripts/main.py version`
- 支持 `python scripts/main.py run`
- 支持从 `some-sibling-skill` 读取批次元数据（如需要）
- 支持执行核心业务编排（HTTP / 批处理 / 可选 RPA）
- 支持写入任务日志（`task_logs`）
### 可后续扩展
- 支持定时批跑
- 支持失败自动重试
- 支持多目标轮询
## 5. 非功能要求
说明除功能外，对稳定性、可维护性、目录规范、日志、编码等方面的要求。
模板写法：
- 目录结构必须符合当前 skill 模板规范
- 入口必须统一为 `scripts/main.py`
- 输出格式应尽量机读友好
- 错误前缀统一为 `ERROR:`
- Windows 环境下需保证 UTF-8 输出兼容
- 必须具备基本日志能力
示例：
- 项目结构必须对齐 `skill-template`
- CLI 入口统一使用 `scripts/main.py`
- 关键执行结果应可通过 JSON 或固定文本结构返回
- 任务日志必须可追踪（`task_logs`）
- 不允许重新引入旧模板中的 `docs/`、`optional/` 或 `scripts/skill_main.py`
## 6. 输入输出要求
说明这个 skill 接收什么输入，产出什么输出。
模板写法：
### 输入
- `【输入参数1】`
- `【输入参数2】`
- `【依赖系统返回的数据】`
### 输出
- `【标准输出】`
- `【错误输出】`
- `【数据库记录】`
- `【日志文件】`
示例：
### 输入
- `target_id`：可选，指定任务目标（账号 / 客户 / 平台）
- `input_id`：可选，指定输入批次或记录
- 兄弟技能返回的结构化数据（如有）
### 输出
- 成功结果（stdout / JSON）
- 错误输出（`ERROR:` / `FAIL:`）
- 在本地数据库写入 `task_logs`
- 在日志目录中写入执行日志
## 7. 依赖的兄弟技能或外部系统
说明开发该 skill 时依赖哪些内部技能或外部平台。
模板写法：
### 兄弟技能依赖
- `【skill-a】`：作用是 `【用途】`
- `【skill-b】`：作用是 `【用途】`
### 外部系统依赖
- `【平台名】`：作用是 `【用途】`
- `【浏览器 / API / 第三方服务】`：作用是 `【用途】`
### Python 包依赖（requirements.txt）
- 本技能若需**特有** Python 三方包，写入根目录 `requirements.txt`。
- `jiangchang-platform-kit`、`playwright` 等公共能力由宿主共享 runtime 提供，**不要**写入技能 requirements。
- `SKILL.md` 的 `platform_kit_min_version` 是运行契约/兼容性声明，供宿主校验，**不是** pip 依赖声明。
- 匠厂宿主安装/更新技能后，会将技能 requirements 安装到 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。
- 版本须尽量收窄（如 `requests>=2.31.0,<3`），避免共享 venv 冲突。
- **不要**把系统运行时组件（如 Microsoft Visual C++ Redistributable）写进 requirements.txt。
### 系统运行时前置条件（preflight / health）
- 若依赖 Windows 原生 DLL、本机浏览器 channel 等**系统级**能力，在 `health` / preflight 中检测并提示用户自行安装。
- 此类依赖**不**通过 pip / requirements.txt 由宿主自动安装。
示例：
### 兄弟技能依赖
- `some-sibling-skill`：提供主数据或凭证索引（按业务填写）
### 外部系统依赖
- 银行 / 政务 HTTP API（示例）：核心外部接口
- Chromium / Chrome / Edge（可选）：用于浏览器自动化
- Gitea：用于代码托管和发布工作流
- 匠厂客户端：用于正式环境安装与验证
## 8. 不在本次范围内的内容
这一节非常重要，用来明确本次“不做什么”，避免研发越做越散。
模板写法：
- 本次不实现 `【功能A】`
- 本次不处理 `【平台B】`
- 本次不做 `【高级能力】`
- 本次不兼容 `【旧结构 / 旧逻辑】`
示例：
- 本次不实现多租户隔离之外的附加报表
- 本次不实现实时流式处理
- 本次不实现自动重试机制
- 本次不兼容旧模板中的历史目录结构
## 9. 验收标准
说明什么情况下才算真正开发完成。
模板写法：
- 代码结构符合模板规范
- 最小命令可运行
- 核心命令可运行
- 正式环境可安装
- 匠厂中可看到最新版本
- 可以在新建任务中实际使用
示例：
- `health`、`version` 命令执行正常
- `run` 主流程可运行
- 发布后 Gitea 工作流成功
- 匠厂技能市场能看到最新版本
- skill 可以正常安装
- 安装后可在“新建任务”中调用
**测试与日志相关验收（所有新 skill 必须满足）**：
- `python tests/run_tests.py -v` 必跑测试全部通过
- 任务日志（task_logs）写入和查询符合预期
- 真实联调（如有）已在 tests/integration/ 中验证，且默认套件不包含真实外联
## 10. 开发注意事项
说明研发过程中必须特别注意的事项。
模板写法：
- 不要修改无关 skill
- 不要破坏现有模板规范
- 优先遵守目录和分层约定
- 不要在 CLI 层堆业务逻辑
- 发布前必须先做本地最小验证
示例：
- 只允许修改当前 skill 仓库，不要改动其他兄弟项目
- 如使用浏览器自动化，优先复用已验证过的定位器和流程
- `cli` 只做参数解析，核心逻辑统一放到 `service`
- 发布前必须完成本地验证、工作流验证和正式环境安装验证
## 11. 变更记录
这一节用于记录需求文档本身的变化，不是 git 提交记录的替代，而是给技术人员看“需求范围怎么变了”。
模板写法：
| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-04-13 | v1.0 | 张三 | 初版需求文档 |
| 2026-04-14 | v1.1 | 李四 | 增加正式环境验收要求 |
---
## 建议使用方式
建议每个新 skill 开发时，按下面顺序使用文档：
1. 先写 `references/REQUIREMENTS.md`
2. 再按 `references/DEVELOPMENT.md` 进入开发
3. 开发过程中补充 `CLI.md`、`SCHEMA.md`、`RUNTIME.md`、`TESTING.md`
4. 发布前回到 `REQUIREMENTS.md` 对照验收标准逐项检查
## 最小模板示例
下面给出一个可直接参考的简化版示例：
```md
# REQUIREMENTS
## 1. 文档目标
本文档用于明确 `your-skill-slug` 的研发需求、范围和验收标准，作为开发与测试的统一依据。
## 2. 业务背景
采购审计需要将政府采购公告结构化归档；人工复制粘贴效率低，需要可追溯的任务日志。
## 3. 开发目标
- 完成 `your-skill-slug` 的标准 skill 结构
- 支持核心业务批处理 / HTTP 对接主流程
- 支持任务日志记录（task_logs）
## 4. 功能范围
- 支持 `health`
- 支持 `version`
- 支持 `run`
- 支持查询任务日志（logs / log-get）
## 5. 非功能要求
- 入口统一为 `scripts/main.py`
- 保持 UTF-8 输出
- 结构符合 skill 模板规范
## 6. 输入输出要求
### 输入
- `target_id`
- `input_id`
### 输出
- 成功结果
- 错误信息
- task_logs 记录
## 7. 依赖的兄弟技能或外部系统
- （按需填写兄弟 skill）
- 政务公告站点 HTTP API（示例）
## 8. 不在本次范围内的内容
- 不实现浏览器可视化回放（如需另行立项）
- 不实现自动重试
## 9. 验收标准
- 命令可运行
- `python tests/run_tests.py -v` 全部通过
- task_logs 写入符合 SCHEMA 约定
- 能完成正式环境安装验证
- 能在新建任务中使用
## 10. 开发注意事项
- 不修改无关项目
- 不引入旧模板结构
## 11. 变更记录
| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-04-13 | v1.0 | 张三 | 初版 |
```

239
references/RPA.md
View File

@@ -1,239 +0,0 @@
# RPA 操作标准（浏览器 / 桌面 / 手机）
> 本文是团队 RPA 开发的**统一标准**。任何需要"自动操作软件界面"的 skill，都应先读这份文档，按这里的选型和范式落地，不要每个项目重新踩坑。
我们开发的各类 skill，本质上都是在替人操作三类界面：**浏览器、桌面软件、手机软件**。三类的底层技术不同，但**工程范式相同**：保持登录态、有头运行、拟人操作、失败存证、人工兜底。
---
## 0. 三端通用范式（先看这个）
无论操作哪类界面，都遵循同一套约定：
| 约定 | 说明 |
|------|------|
| **保持登录态** | 复用持久化 Profile / session，避免每次重新登录触发风控；账号由 account-manager 下发，不硬编码 |
| **有头运行** | 默认有头（headless 易被识别 / 难人工介入）；`OPENCLAW_BROWSER_HEADLESS=1` 仅给 CI |
| **拟人操作** | 真实事件（isTrusted=true），逐字输入、随机延迟、贝塞尔鼠标轨迹；严禁 JS 直接设值/JS 点击/JS 跳转 |
| **步骤间随机等待** | 每两步操作之间 `random_delay(min,max)`，区间由 `.env` 配置（默认 1~5s） |
| **人工兜底（HITL）** | 滑块 / 短信验证码 / 人脸 / U盾 / 动态口令 → **停下来轮询等人工**，超时报 `ERROR:XXX_NEED_HUMAN`，绝不自动硬闯 |
| **失败存证** | 失败必截图，合规场景全程录屏，统一存 `{数据目录}/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` 等，见下方错误码表 |
| **幂等 / 断点续跑** | 批量操作记录"已处理到第几条"，崩溃后能续跑、不重复提交 |
> 三端各自实现一个会话抽象 `RpaSession`（launch / login / act / screenshot / close），上层 skill 不感知是浏览器还是手机。
---
## 1. 浏览器（标准已成熟）
**选型：Playwright + 系统 Chrome/Edge。** 这是团队验证最充分的一条线（标杆技能 `1688-scrape-contacts`、`receive-order` 已落地）。
### 1.0 生产路径（优先）
| 项 | 标准 |
|----|------|
| 浏览器 | **优先系统 Chrome/Edge** + `launch_persistent_context`，`channel="chrome"` 或 Edge；不用内置 Chromium，**技能内不要 `playwright install`** |
| 登录态 | 持久 Profile 目录；账号、profile、lease **统一走 account-manager**（或对应兄弟技能），不硬编码密码 |
| CDP | **仅作诊断 / 桌面宿主类场景**；**不要**作为强风控站点的默认生产路径 |
| 行为 | 模拟真实用户：真实点击、键盘、鼠标、地址栏输入；**不要**拼接搜索结果 URL、DOM 注入、`el.value=`、JS 跳转 |
| 模式 | 默认有头 `OPENCLAW_BROWSER_HEADLESS=0`；无头仅 CI |
| 反检测 | stealth 默认开 `OPENCLAW_PLAYWRIGHT_STEALTH=1`（见 1.1） |
### 1.1 Playwright 启动标准
1. **默认有头**：`OPENCLAW_BROWSER_HEADLESS=0`（`.env.example` 默认值）。
2. **stealth 默认开**：`OPENCLAW_PLAYWRIGHT_STEALTH=1`；通过 `add_init_script` 注入指纹淡化脚本。
3. **不要在技能里自行安装 playwright**；由宿主共享 runtime 提供。
4. **不要默认传 `--no-sandbox`**（除非特定容器环境且已评估风险）。
5. **不要默认传 `--disable-blink-features=AutomationControlled`**；platform-kit stealth 已覆盖，额外 flag 可能适得其反。
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.13**）。
**拟人操作**（必做）：
- 输入：逐字符 `keyboard.type(delay=90~240ms)`，**先真实点击聚焦再输入，绝不 `el.value=`**。
- 鼠标：贝塞尔曲线轨迹 + 微抖动；进场随机晃动。
- 导航：用真实点击触发，**不要 `window.location.href=` / JS 点击跳转**。
- 翻页：真实点击翻页控件，注意排除禁用态。
- 延迟：每步之间 `random_delay`（`.env` 中 `STEP_DELAY_MIN/MAX`）。
### 1.2 页面启动标准
优先级（高 → 低）：
1. **launch args `start_url`**：浏览器启动即打开目标首页（推荐生产路径）。
2. **profile preferences**：作为兜底（例如 homepage / startup URLs）。
3. **程序化导航 `page.goto`**：仅最后兜底；强风控站点慎用裸 `goto` 深链。
**生产路径不要依赖 CDP 接管现有页面**；CDP 仅用于诊断或桌面宿主已打开浏览器的场景。
### 1.3 HITL / 验证码
- 自动处理失败时**允许等待人工**：滑块、短信、人脸、U盾、动态口令等。
- 等待人工验证时必须有：**字幕 step**（用户可见动作说明）、**结构化日志**、**超时**（`HUMAN_WAIT_TIMEOUT`）。
- 检测到风控页（URL/DOM 特征）→ 抛 `ERROR:CAPTCHA_NEED_HUMAN`，轮询等待或超时，**不要强行绕过平台安全机制**。
- **不要自动操作滑块**。
> 共享库：`jiangchang_skill_core.rpa.wait_for_captcha_pass`；参考 `scripts/service/example_browser_rpa.py`。
### 1.4 安装
生产/宿主运行：`playwright` 由共享 runtime 提供，无需在技能内 `pip install`。
独立本地开发环境若缺少 Python 包 `playwright` 时，可手动执行：
```bash
pip install playwright # 仅独立开发补装；用系统 Chrome，无需 playwright install chromium
```
### 引用方式
共享实现位于宿主共享 runtime 安装的 `jiangchang-platform-kit`（`jiangchang_skill_core.rpa`）。复制后的业务技能直接 import，**技能仓库不得保留 rpa 公共代码副本**：
```python
from jiangchang_skill_core.rpa import (
launch_persistent_browser,
anti_detect,
wait_for_captcha_pass,
capture_failure,
errors,
)
from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRIPT
```
- `RpaVideoSession` 来自 platform-kit **>= 1.0.13**；ffmpeg、背景音乐、media-assets 由 platform-kit 统一解析；已提供前置/后置缓冲、字幕、TTS 旁白、背景音乐循环、结尾淡出。
- `health` 对上述资源做只读诊断，不下载、不修复。
完整示例见 `scripts/service/example_browser_rpa.py` 与 `scripts/service/example_adapter/sim_rpa.py`。
---
## 2. 桌面软件（Windows 原生程序）
**选型：pywinauto（UIA backend）为主 + 图像识别兜底。**
桌面端常见于 ERP 客户端、网银控件、银企直连等本地程序。优先走可访问性树（控件 ID/名字），坐标点击只做最后兜底。
| 技术 | 优先级 | 适用 / 说明 |
|------|--------|------|
| **pywinauto（`backend="uia"`）** | ✅ 首选 | 基于微软 UI Automation 树，拿控件 AutomationId/Name/ControlType，**稳定、不依赖屏幕坐标**，纯 Python |
| **FlaUI**（经 pythonnet 调 .NET） | 备选 | UIA 拿不到的复杂/自绘控件时更完整，但需引入 .NET 运行时 |
| **Playwright** | 特例 | 目标是 **Electron 套壳应用**（很多新 SaaS 客户端）时，可当浏览器驱动 |
| **PyAutoGUI / SikuliX（图像识别）** | ⚠️ 兜底 | 控件树完全拿不到时（Flash/远程桌面/纯自绘 UI）；**靠截图找图+坐标，分辨率/缩放一变就崩**，仅最后手段 |
### 桌面端注意事项
- **窗口聚焦/置顶**：操作前确保目标窗口前置，避免误操作其它窗口。
- **DPI/缩放**：图像识别方案必须固定显示缩放比例；UIA 方案不受影响（优先用 UIA 即是为此）。
- **存证**：同样要失败截图（截目标窗口/全屏），存到 `rpa-artifacts`。
- **人工兜底**：U盾插拔、动态口令、人脸 → 停下等人工，超时 `ERROR:XXX_NEED_HUMAN`。
```bash
pip install pywinauto # UIA 自动化
# 图像兜底：pip install pyautogui opencv-python
```
> 状态：桌面端选型为推荐标准，**尚待真实项目实战验证**，落地时回补踩坑记录到本文。
---
## 3. 手机软件（USB 连接电脑）
**选型：Android 用 uiautomator2（或 Appium）；iOS 用 Appium + WebDriverAgent（需 Mac）。** 底层都是经 USB 的 ADB / WDA。
| 平台 | 技术 | 优先级 | 说明 |
|------|------|--------|------|
| **Android** | **uiautomator2**（python 原生） | ✅ 首选 | ADB over USB，直接拿控件树点击/输入，比 Appium 轻快，纯 Python |
| Android | **Appium**（uiautomator2 driver） | 备选 | 需要跨平台统一接口、或团队已有 Appium 资产时用 |
| Android | **Airtest + Poco**（网易开源） | 兜底 | 图像+控件混合，自带 IDE 可录制；控件树拿不到时用 |
| **iOS** | **Appium + WebDriverAgent（XCUITest）** | 唯一可行 | **必须有一台 Mac 做中转**，Windows host 无法直接驱动 iOS |
| 投屏/人工介入 | **scrcpy** | 辅助 | USB 投屏到电脑，配合人工过验证码/人脸 |
### 手机端注意事项
- **设备就绪检查**：`adb devices` 确认已授权连接；放进 `doctor` 自检。
- **登录态**：靠 App 自身保持登录，必要时引导人工首登一次。
- **人工兜底**：短信验证码、人脸、指纹 → scrcpy 投屏让人工完成，程序轮询等待。
- **存证**：失败时 `adb screencap` / Appium 截图存 `rpa-artifacts`。
```bash
# Android（首选）
pip install uiautomator2
python -m uiautomator2 init # 初始化设备端 agent
# 或统一走 Appium：pip install Appium-Python-Client（另需 Appium Server）
```
> 状态：手机端选型为推荐标准，**尚待真实项目实战验证**，落地时回补踩坑记录到本文。
---
## 4. 统一错误码（RPA 场景）
skill 退出/抛错统一用 `ERROR:` 前缀 + 稳定码，方便宿主与上层判断与重试：
| 错误码 | 含义 | 上层处理建议 |
|--------|------|------|
| `ERROR:REQUIRE_LOGIN` | 未登录 / 登录态失效 | 触发登录流程 |
| `ERROR:LOGIN_TIMEOUT` | 等待人工登录超时 | 提示用户重跑并及时操作 |
| `ERROR:CAPTCHA_NEED_HUMAN` | 命中滑块/验证码拦截 | 暂停等人工，或转人工队列 |
| `ERROR:RATE_LIMITED` | 触发频控 | 退避后重试 |
| `ERROR:MISSING_BROWSER` | 未检测到 Chrome/Edge | 提示安装 |
| `ERROR:DEVICE_NOT_READY` | 手机未连接/未授权 | 检查 USB/ADB |
| `ERROR:WINDOW_NOT_FOUND` | 桌面目标窗口未找到 | 检查程序是否启动 |
---
## 5. 存证与录屏规范
### 5.1 截图存证
- **路径**：`{CLAW_DATA_ROOT}/{user}/{slug}/rpa-artifacts/{batch_id}/{tag}_{timestamp}.png`
- **失败必截图**：受 `OPENCLAW_ARTIFACTS_ON_FAILURE`（默认开）控制。
- **Playwright 不负责录屏**，仅浏览器自动化。
- **常见 tag**：`before_submit` / `after_submit` / `captcha` / `login_fail` / `error`。
### 5.2 RPA 视频 step 标准
字幕是**用户可见动作说明**，不是技术日志。step 要贴近真实动作，不要只在大流程入口打点。
推荐关键动作示例（按业务裁剪）：
- 启动浏览器
- 打开首页
- 检查登录状态
- 定位输入框
- 输入关键词：xxx
- 点击搜索
- 等待结果
- 打开详情页
- 提取信息
- 写入结果
- 任务完成
技术诊断、重复跳过、DB 写入可以显示但**通常不需要旁白**。
`title` / `closing_title` 必须由 skill 传入**中文业务文案**（如「开始执行示例任务」「示例任务执行完成」）。
### 5.3 录屏成片标准
- RPA skill 默认 `OPENCLAW_RECORD_VIDEO=1`。
- 使用 platform-kit 的 **`RpaVideoSession`**；**skill 不要自行合成视频**（不要自己调 ffmpeg 拼 MP4）。
- `OPENCLAW_RECORD_VIDEO=0` 时 session 无副作用（不启 ffmpeg、不写字幕文件）。
- **ffmpeg 是唯一录屏器**（Windows：`gdigrab` + `desktop`）。
- **最终视频**：`{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`）。
模板最小示范见 `scripts/service/task_service.py` 的 `_run_template_demo()`。
---
## 相关文档
- `ADAPTER.md` — 真实/仿真 × API/RPA 的四档适配器模式
- `CONFIG.md` — `.env` 配置规范与首次落盘机制
- `RUNTIME.md` — 运行时目录与环境变量约定

112
references/RUNTIME.md
View File

@@ -1,112 +0,0 @@
# 运行时约定
## 共享 Python Runtime
**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.13` 及其传递依赖，含 `playwright`）。`jiangchang_skill_core` **不得**在技能仓库内 vendored，应由共享 venv 的 site-packages 提供。
技能根目录 `requirements.txt` **只声明技能特有依赖**；**不要**重复声明 `jiangchang-platform-kit` 或 `playwright`。`SKILL.md` 的 `platform_kit_min_version` 是运行契约，**不是** pip 依赖声明。
| 场景 | 推荐做法 |
|------|----------|
| 日常运行 | 由宿主匠厂触发技能 |
| 手工排查 / 测试机 | 使用共享 runtime 的 `python.exe` 执行 `scripts/main.py` |
| **不推荐** | 在技能目录内 `uv run python …` — 可能创建临时 venv，加载不到宿主共享 runtime |
占位命令（路径因环境而异，勿写死本机目录）：
```text
Windows:
{JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health
通用:
<shared-python> {baseDir}/scripts/main.py health
```
`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。数据根由宿主注入；开发模式下也可能通过 `CLAW_DATA_ROOT` 解析（见 `jiangchang_skill_core.runtime_env`）。
## Runtime 诊断（platform-kit 1.0.13+）
`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`
- `media_assets_root`、`ffmpeg_path`、`background_music_*`
- `record_video_enabled`、`runtime_issue[warning|error]`
`health` 是**只读诊断**，**不会**触发 media-assets 下载或修复。并补充 `env_path` / `env_exists` / `example_path` 配置路径字段。
## 配置 bootstrap
- 仓库内 `.env.example` 是配置模板（单一事实来源）。
- 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_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.13`，**不得** vendored `scripts/jiangchang_skill_core/`。
## media-assets / ffmpeg / 背景音乐
背景音乐、ffmpeg 等共享资源由 platform-kit 统一解析，默认路径：
```text
{JIANGCHANG_DATA_ROOT}/shared/media-assets
```
（与 `CLAW_DATA_ROOT` 解析规则一致，由宿主注入。）
RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均由 platform-kit 提供；技能只 import，不重复实现。
## 目录结构
新技能建议采用以下根目录结构：
- `assets/`
- `references/`
- `scripts/`
- `tests/`
- `evals/`
**标准 `scripts/` 分层（不含 `jiangchang_skill_core/` 副本）：**
- `scripts/main.py`：唯一 CLI 入口
- `scripts/cli/`：参数解析与命令分发
- `scripts/db/`：SQLite 或本地持久化层
- `scripts/service/`：业务用例与外部交互
- `scripts/util/`：通用工具、常量、日志、路径薄封装
## 数据路径
推荐：
```text
{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
```
数据库文件建议：
```text
{...}/{skill_slug}.db
```
## 明确禁止
- **不得** vendored `scripts/jiangchang_skill_core/`
- **不得**在技能内本地重复实现 `RuntimeDiagnostics` / `collect_runtime_diagnostics`
- **不得**写死开发机绝对路径作为运行时约定
## 测试时的运行时隔离
本模板的 `tests/_support.IsolatedDataRoot` 会在测试期间同时设置：
- `CLAW_DATA_ROOT` / `JIANGCHANG_DATA_ROOT` → 临时 tempfile 目录
- `CLAW_USER_ID` / `JIANGCHANG_USER_ID` → `_test`
退出时四个变量恢复，临时目录删除。所有 DB / 文件写入都被限制在临时目录内，不污染本机。
详见 `references/TESTING.md` 第 3 节。
## 编码与输出
- Windows 终端建议在 `scripts/main.py` 里做 UTF-8 stdout/stderr 包装
- 机读输出优先单行 JSON
- 错误前缀建议统一 `ERROR:`

232
references/TESTING.md
View File

@@ -1,232 +0,0 @@
# 测试开发指南
面向复制 `skill-template` 后的新业务 skill：**如何把自动化测试当作一等公民**，而不是等业务写完再补文档级别的空话。本文串起模板自带的 unittest 入口、`tests/` 目录分层与安全档位约定；**更细的开关取值、表格字段与环境变量组合仍以 [`tests/README.md`](../tests/README.md) 为权威来源**。建议你随手开一个编辑器分页：`references/TESTING.md`（本篇）、[`references/DEVELOPMENT.md`](DEVELOPMENT.md)（整体节奏）、[`tests/README.md`](../tests/README.md)（落地细则）。
默认心智模型可以用一句话概括：**根目录 `test_*.py` = CI / 本地每次提交都应能通过的无外联套件**；`*integration*`、`*.sample`、`desktop/` = 只在人被明确要求时才启用的高风险或重量级路径。
---
## 1. 测试体系总览
本模板把测试分成四层漏斗：**默认必跑（unittest + `run_tests.py`）**、从 `tests/samples/` **按需复制的 service / golden**、放在 `tests/integration/` **默认不落盘的仿真或真实联调范式（多数仍是 `.sample`）**、以及 **desktop E2E（pytest + 宿主 SDK）**。
[`tests/run_tests.py`](../tests/run_tests.py) 只做三件事：把 `scripts/` 与 `tests/` 放进 `sys.path`、做 Windows UTF-8 包装、收集 **`tests/` 根目录**下的 `test_*.py`。它不递归子目录——这正是刻意的安全边界：**不想让 AI 或拷贝粘贴 accidentally 把 integration 拉进默认套件**。
当你在设计一个新 skill 的测试策略时，请先问自己：**这段代码在没有外部凭证与浏览器的前提下是否有意义？** 若有，留在默认套件；若无，放进 integration / `.sample`，并要求明确的 `OPENCLAW_TEST_TARGET` 组合开关。
更深表格化的目录映射、`FakeAdapter` 与 profile 的耦合细节见 [`tests/README.md`](../tests/README.md) 开头章节『我该把测试写在哪里』。
---
## 2. 默认必跑测试要做什么
必跑套件要像一个紧张的守门员：**快、确定、离线**。典型覆盖：
- CLI：导入 [`cli.app`](../scripts/cli/app.py) 走解析链路、`health`（runtime diagnostics）/ `version` / `logs` / `log-get` 冒烟；
- 架构守护：无 `scripts/jiangchang_skill_core/`、`platform-kit>=1.0.13` 导入来源、文档/runtime 标准（见 `test_platform_import.py` 等）；
- **真实 subprocess**：[`tests/test_entrypoint_subprocess.py`](../tests/test_entrypoint_subprocess.py) 再调用一遍 `python scripts/main.py`，防路径漂移；
- 运行时：`runtime_paths` 与 **`CLAW_*` / `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。
**原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。
套件能力与表格参见 [`tests/README.md`](../tests/README.md) 「1.2 默认套件覆盖」。
---
## 3. 数据隔离：IsolatedDataRoot
[`tests/_support.py`](../tests/_support.py) 提供的上下文管理器 `IsolatedDataRoot()`：进入一个专用临时目录，**镜像写入四套变量**：`CLAW_DATA_ROOT`、`JIANGCHANG_DATA_ROOT`（同一 tempfile）、以及用户镜像 ID：`CLAW_USER_ID`、`JIANGCHANG_USER_ID` → `_test`。
结束时：**恢复原 environ**，删除目录。
这样可以断言：**SQLite DB / spill files / caches** 都在 sandbox；不会在开发者桌面遗留 `{REAL_ROOT}`。
示例：
```python
from _support import IsolatedDataRoot
def test_whatever():
with IsolatedDataRoot():
from db.connection import init_db
init_db()
# …断言读写均在隔离路径…
```
**不要把真实凭证路径硬编码进默认测试**：隔离不等于你有权触碰真实目录。
---
## 4. 测试目标档位（OPENCLAW_TEST_TARGET）
模板采用统一闸门：**你想跑到哪一层外部世界，就用变量明说**。合法档位（非法值会让 helper 抛错）如下——**直接摘录自 [`tests/README.md`](../tests/README.md) §5.1**：
| 取值 | 含义 |
|------|------|
| `unit` | **默认**：单元 / 内存 / mock，不跑仿真与真实外联 |
| `mock` | 与 `unit` 类似的安全档位（显式语义） |
| `simulator_api` | 仅允许 **仿真 HTTP** 类集成（如 localhost） |
| `simulator_rpa` | 仅允许 **仿真页面 / 录播 RPA** |
| `real_api` | 真实 API（另需 `ALLOW_REAL_API=1`） |
| `real_rpa` | 真实 RPA（另需 `ALLOW_REAL_RPA=1`） |
未设置环境变量 ⇒ 等价 `unit`。
授权开关（显式 `1`）语义 **`ALLOW_REAL_API` / `ALLOW_REAL_RPA` / `ALLOW_WRITE_ACTIONS`**——摘录 [`tests/README.md`](../tests/README.md) §5.2：
| 变量 | 作用 |
|------|------|
| `ALLOW_REAL_API=1` | 允许 `real_api` profile 访问真实 HTTP 通道 |
| `ALLOW_REAL_RPA=1` | 允许 `real_rpa` profile 驱动真实浏览器/RPA |
| `ALLOW_WRITE_ACTIONS=1` | 在 `real_*` 下允许**写**操作（提交表单、下单等） |
默认策略摘要见 §5.3：**不要在 unittest 必跑路径误把闸门打开**。
兼容别名：`OPENCLOW_TEST_TARGET`（历史拼写）。
---
## 5. FakeAdapter：怎么模拟外部系统
[`tests/adapter_test_utils.py`](../tests/adapter_test_utils.py) 暴露 `FakeAdapter`，典型四种 **mode**：
| mode | 用途 |
|------|------|
| `success` | 构造干净的成功响应路径 |
| `timeout` | 模拟悬挂 / 慢链路 |
| `invalid_response` | 畸形负载 / schema drift |
| `unauthorized` | token / license / cookie 失效语义 |
**何时用它**：service 层出现『调用第三方 HTTP / RPA stub』但又不能把真实系统纳入 CI。**契约测试**（复制 [`tests/samples/test_service_contract.py.sample`](../tests/samples/test_service_contract.py.sample)）应优先组合 FakeAdapter，而不是直接把 CLI when-json 断言堆上天。
把它看成：**你把不确定性收敛到可控的测试矩阵里**，而不是在生产日志里才第一次看到错位字段。
---
## 6. 怎么从 .sample 启用一个测试
步骤模板：
1. 找到范式文件（例如 [`tests/samples/test_service_contract.py.sample`](../tests/samples/test_service_contract.py.sample)）。
2. **复制**到 `tests/` 根：`tests/test_service_contract.py`（去掉 `.sample`）。
3. 打开副本：**替换占位函数名 /技能特有枚举 / adapter profile**，删掉与本技能无关的示例断言。
4. 本地执行：`python tests/run_tests.py -v [可选筛选关键词]`。
5. **不要把 integration `.sample` 批量改名混进根目录**——除非你已经读过 [`tests/integration/README.md`](../tests/integration/README.md) 的风险清单。
Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../tests/samples/test_golden_cases.py.sample)）。
---
## 7. 真实联调测试的安全约束
任何 touching **真实租户数据** 的路径：
1. **禁止**硬编码 token / cookie / 内部域名落入仓库；
2. **禁止**默认套件隐式导入 integration；
3. **真实 RPA** 只能标记为手动触发（双人复核 / 本地 `.env` 不入库）。
范式阅读 [`tests/integration/README.md`](../tests/integration/README.md)：那里有针对凭证来源、目录 artifact 忽略策略的补充。
记住：**测试代码也是一种部署面**，别把 staging 凭证写死进仓库。
---
## 8. 新 skill 的最小测试清单
以下清单 **原文摘自 [`tests/README.md`](../tests/README.md) 「新技能最小测试清单」**（复制新仓库后逐项勾选）：
- [ ] `python tests/run_tests.py -v` 能通过。
- [ ] `python scripts/main.py health` 能通过。
- [ ] `python scripts/main.py version` 输出 JSON，且 `skill` 与目录名 / `SKILL.md` / `constants.SKILL_SLUG` 一致。
- [ ] 所有 DB / 文件写入都在 `IsolatedDataRoot`（或等价隔离）下测试，不写真实数据目录。
- [ ] 外部系统默认使用 mock / `FakeAdapter`，不访问真实 API，不打开真实 RPA。
- [ ] 至少有 1 个成功路径测试。
- [ ] 至少有 1 个缺必填字段 / 非法输入测试。
- [ ] 如果有 adapter，至少覆盖 timeout / unauthorized / invalid response（可用 fake 模拟）。
- [ ] 如果有解析 / 计算 / 校验类业务，至少保留 1 组 golden fixture（脱敏）。
- [ ] 真实 API / 真实 RPA 测试只放 `tests/integration/`，并且默认 `.sample`，不默认运行。
---
## 9. AI 编程工具使用测试时的红线
改编自 [`tests/README.md`](../tests/README.md) 「AI 编程工具注意事项」，压缩成 skill 开发者视角：
| 红线 | 解释 |
|------|------|
| 不改业务凑测试 | 除非需求变更已确认，否则**不要为了让 CI 变绿而砍掉业务分支** |
| **默认套件零外联** | 不把真实 HTTP / 浏览器写进 `tests/test_*.py` |
| `.sample` 尊重 | 集成范式改名前先读完 README；别让 `.sample` 悄悄变成根测试 |
| **零硬编码凭证** | token / cookie / 生产 URL → 用虚构域名或 vault ref |
| mock 优先 | 逻辑应在 service + FakeAdapter，而不是巨胖 CLI 断言 |
| 结构化错误 | 断言错误码字段，而不是 substring of stderr 漂移集合 |
| **integration = 显式开关** | `OPENCLAW_TEST_TARGET` + `ALLOW_REAL_*` / `ALLOW_WRITE_ACTIONS` |
---
## 10. 测试和发布的关系
**在运行 [`release.ps1`](../release.ps1) 之前，`python tests/run_tests.py -v` 必须绿色**。失败的默认套件意味着：
- 打包路径可能根本不可运行；
- CI 加密前的静态假设可能在宿主崩溃；
- metadata slug 漂移将被市场拒绝。
把『本地 unittest 绿』视作 tag 的前置条件，而不是『有空再跑』。发布流水线成功后仍要做安装验证——那是另一个维度；**测试是第一个维度**。
---
## 11. pytest 收集卫生标准
模板根目录提供 `pytest.ini`（或等价配置），约束：
- **只收集** `test_*.py` / `*_test.py`
- **不让** `.txt`、结果文件、日志文件被 pytest 误收集
- `norecursedirs` 排除 `integration/`、`desktop/`、`samples/`、`fixtures/`、`artifacts/`、`diagnostics/`
测试结果文件**不要**放在 `tests/` 根目录；应放 `tests/artifacts/` 或 `tests/diagnostics/` 并加入 `.gitignore`。
默认 `python tests/run_tests.py` 仍只发现 `tests/` 根目录一层 `test_*.py`（不递归子目录），与 pytest 策略一致。
---
## 12. RPA / video 测试标准
- `RpaVideoSession` 调用**不跑真实 ffmpeg**：单测中使用 `unittest.mock` patch session 或设 `OPENCLAW_RECORD_VIDEO=0`。
- 断言 `title` / `closing_title` 是**中文**业务文案。
- 断言 video artifact 会进入 `result_summary`（`video_path`、`raw_video`、`video_log` 等）。
- 断言 step 文案贴近用户动作，不是技术日志（如「准备执行示例任务」而非「enter cmd_run」）。
参考 `tests/test_video_service.py`。
---
## 13. 宿主 E2E 标准
- 使用 `jiangchang_desktop_sdk.e2e_helpers`（见 `tests/desktop/` 下 `.sample`）。
- **不伪造**用户数据目录；通过宿主 IPC 获取真实 `skill_data_dir`。
- E2E **不自动生成**真实密钥或生产凭证。
---
## 14. 测试前检查清单（模板守护）
复制新 skill 或修改模板后，确认：
- [ ] `requirements.txt` **不含** `jiangchang-platform-kit` / `playwright`
- [ ] 无 `scripts/jiangchang_skill_core/` vendored 副本
- [ ] `platform_kit_min_version` **>= 1.0.13**（`SKILL.md` + `constants.py`）
- [ ] `health` 能输出 `platform_kit_version_ok`（或等价诊断行）
- [ ] `config-path` 可输出用户 `.env` 路径 JSON
- [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py`
- [ ] pytest **不会**误收集 `tests/` 下的 `.txt` / 日志 / 结果文件
- [ ] `python tests/run_tests.py -v` 全部通过
---
- [`tests/README.md`](../tests/README.md) — 表格、变量与目录细则
- [`references/DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序
- [`tests/integration/README.md`](../tests/integration/README.md) — 高风险用法