chore: auto release commit (2026-06-14 11:12:03)

development/ADAPTER.md

@@ -0,0 +1,108 @@
+# 适配器标准：真实/仿真 × 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 与隔离体系

development/CONFIG.md

@@ -0,0 +1,99 @@
+# 配置标准：`.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_*` 环境变量与数据目录约定

development/DEVELOPMENT.md

@@ -0,0 +1,729 @@
+# 技能开发教程
+
+这份文档是给**技术人员**看的，目标不是解释概念，而是让你拿到 `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/
+├─ development/
+├─ evals/
+├─ references/
+├─ scripts/
+│  ├─ cli/
+│  ├─ db/
+│  ├─ service/
+│  └─ util/
+├─ tests/
+├─ .gitignore
+├─ README.md
+├─ requirements.txt
+├─ release.ps1
+└─ SKILL.md
+```
+
+各目录职责如下：
+
+- `assets/`：放示例输出、schema、静态说明资源
+- `README.md`：面向用户的市场详情页说明
+- `SKILL.md`：面向 LLM / 平台的技能入口
+- `references/`：Agent 运行/编排/调用时渐进加载的补充上下文（如 CLI、SCHEMA）
+- `development/`：面向开发者与 AI 编程代理的开发资料、需求、测试与技术规范
+- `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.14` import，**不得**在 `scripts/` 下保留 `jiangchang_skill_core/` 副本。
+
+## 3.2 开发 RPA 类 skill
+
+若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地：
+
+1. **先读三份标准**：`RPA.md`（三端范式与反反爬）、`CONFIG.md`（`.env` 落盘与读取）、`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.14`）是运行契约/兼容性声明，供宿主安装与启用时校验，**不是** 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. 根目录 `README.md`（用户市场说明）
+3. `scripts/util/constants.py`
+4. `references/` 与 `development/` 下的文案
+5. `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` 的命令示例
+- `../README.md` 的用户话术
+- `../references/SCHEMA.md` 的字段映射补充说明
+
+如需浏览器自动化，不要在模板里保留空的 `platform_playwright.py`；请按业务新建 `xxx_playwright.py`（命名自定），并在 `task_service.py` 中按需引用。
+
+## 6. `SKILL.md` 与根 `README.md` 应该怎么写
+
+### `SKILL.md`（LLM / 平台入口）
+
+`SKILL.md` 是给 LLM 与 OpenClaw 平台看的技能入口，**不是**用户市场详情页。
+
+应该重点写：
+
+- YAML frontmatter：`name`、`description`、`version`、`metadata.openclaw`（含 `slug`、`platform_kit_min_version`、`developer_ids` 等）
+- 何时触发本技能、CLI 入口摘要、运行契约要点
+- 指向 `references/`（Agent 调用）与 `development/`（开发规范）的分工说明
+
+不要在 `SKILL.md` 里写大量用户市场文案或实现细节。
+
+### 根 `README.md`（用户市场说明）
+
+根 `README.md` 是技能市场详情页主来源（`metadata.readme_md`），面向普通用户。
+
+应包含 YAML frontmatter 的 `description`（市场列表简介），正文用用户能理解的语言说明：
+
+- 能做什么、适合什么场景、使用前准备什么
+- 如何自然语言告诉 Agent
+- 执行结果、注意事项、常见问题
+
+不要在根 `README.md` 里写开发教程、目录规范、release、requirements 等技术细节。
+
+实现细节放在：
+
+- `development/`
+- `references/`（CLI / SCHEMA）
+- 代码注释与 `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. 文档目录分工
+
+当前规范 skill 的文档按读者拆分：
+
+**根 `README.md`**
+
+- 用户市场详情页说明（含 frontmatter `description`）
+
+**`SKILL.md`**
+
+- LLM / OpenClaw 平台技能入口
+
+**`references/`**（Agent 运行/编排/调用时渐进加载）
+
+- `README.md` — Agent 参考索引
+- `CLI.md` — 命令、参数、默认值、兄弟技能调用方式
+- `SCHEMA.md` — 数据库路径、核心表结构、日志表结构
+- 可按需增加 `ERRORS.md`、`INTEGRATION.md` 等编排向补充
+
+**`development/`**（开发者 / AI 编程代理）
+
+- `REQUIREMENTS.md` — 需求与验收
+- `DEVELOPMENT.md` — 开发教程（本文档）
+- `TESTING.md` — 测试分层与隔离（详见 [`TESTING.md`](TESTING.md)）
+- `ADAPTER.md`、`RPA.md`、`CONFIG.md`、`RUNTIME.md` — 技术规范
+
+## 8. `assets/` 应该放什么
+
+`assets/` 不放业务代码，只放辅助材料。
+
+建议放：
+
+- `examples/`
+  比如 `version` 输出示例、`log-get` 输出示例
+
+- `schemas/`
+  比如日志记录、机读 JSON 的 schema
+
+不要把正式研发文档放到 `assets/`。
+用户说明进根 `README.md`；Agent 编排资料进 `references/`；开发规范进 `development/`。
+
+## 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` 显式开启。
+
+详见 `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`、根 `README.md`、`scripts/`、`references/`、`development/` 是否齐全
+- 工作流文件是否存在
+- 发布包结构是否符合模板规范
+
+### 第四步：进入匠厂平台下载安装包
+
+当工作流成功后，就可以进入匠厂平台验证最终安装效果。
+
+匠厂产品下载地址：
+
+- [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`
+- 技术人员不知道看哪一套
+
+现在的新模板原则是：
+
+- 不做旧结构兼容
+- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
+- 统一走 `scripts/main.py` 作为 CLI 入口
+
+## 18. 推荐开发顺序总结
+
+如果让一个新人照着做，我建议他按这个顺序：
+
+1. 复制模板并改目录名
+2. 改 `SKILL.md` 与根 `README.md`
+3. 改 `scripts/util/constants.py`
+4. 改 `references/` 与 `development/`
+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`
+- 用户说明在根 `README.md`，Agent 资料在 `references/`，开发规范在 `development/`
+- 业务核心逻辑统一放 `scripts/service/`
+- 不再使用旧模板历史结构
+
+如果做不到这些，后面 skill 一多，就会越来越乱。

development/README.md

@@ -0,0 +1,14 @@
+# 开发资料入口
+
+本目录面向**人类开发者**与 **AI 编程代理**。开始定制 skill 前，建议按以下顺序阅读：
+
+1. [`REQUIREMENTS.md`](REQUIREMENTS.md) — 需求文档模板与验收标准
+2. [`DEVELOPMENT.md`](DEVELOPMENT.md) — 完整开发步骤与目录规范
+3. [`TESTING.md`](TESTING.md) — 测试分层、隔离数据根与档位开关
+4. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
+5. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
+6. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
+7. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径与诊断约定
+
+Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)。  
+用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。

development/REQUIREMENTS.md

@@ -0,0 +1,356 @@
+# 技能需求文档模板
+
+这份文档用于给技术人员、产品人员和实施人员统一描述某个 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. 先写 `REQUIREMENTS.md`
+2. 再按 `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 | 张三 | 初版 |
+```

development/RPA.md

@@ -0,0 +1,239 @@
+# 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.14**）。
+
+**拟人操作**（必做）：
+
+- 输入：逐字符 `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.14**；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` — 运行时目录与环境变量约定

development/RUNTIME.md

@@ -0,0 +1,113 @@
+# 运行时约定
+
+## 共享 Python Runtime
+
+**skill-template** 及复制出的新技能，公共能力均来自宿主匠厂安装的共享 Python Runtime（`jiangchang-platform-kit>=1.0.14` 及其传递依赖，含 `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.14+）
+
+`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.14`，**不得** 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/`
+- `development/`
+- `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 / 文件写入都被限制在临时目录内，不污染本机。
+
+详见 `TESTING.md` 第 3 节。
+
+## 编码与输出
+
+- Windows 终端建议在 `scripts/main.py` 里做 UTF-8 stdout/stderr 包装
+- 机读输出优先单行 JSON
+- 错误前缀建议统一 `ERROR:`

development/TESTING.md

@@ -0,0 +1,232 @@
+# 测试开发指南
+
+面向复制 `skill-template` 后的新业务 skill：**如何把自动化测试当作一等公民**，而不是等业务写完再补文档级别的空话。本文串起模板自带的 unittest 入口、`tests/` 目录分层与安全档位约定；**更细的开关取值、表格字段与环境变量组合仍以 [`tests/README.md`](../tests/README.md) 为权威来源**。建议你随手开一个编辑器分页：`TESTING.md`（本篇）、[`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.14` 导入来源、文档/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.14**（`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) — 表格、变量与目录细则
+- [`DEVELOPMENT.md`](DEVELOPMENT.md) §14.5 — 测试驱动的开发顺序
+- [`tests/integration/README.md`](../tests/integration/README.md) — 高风险用法