chore: auto release commit (2026-06-21 10:51:04)

chore: auto release commit (2026-06-17 09:48:59)
chore: auto release commit (2026-06-17 09:21:19)
2026-06-21 10:51:05 +08:00 · 2026-06-17 09:49:00 +08:00 · 2026-06-17 09:21:21 +08:00
25 changed files with 911 additions and 368 deletions
--- a/.github/workflows/release_skill.yaml
+++ b/.github/workflows/release_skill.yaml
@@ -5,7 +5,7 @@ on:
 jobs:
  release:
-    uses: admin/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@v1.0.14
+    uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@main
    secrets:
      PYARMOR_REG_B64: ${{ secrets.PYARMOR_REG_B64 }}
    with:
--- a/README.md
+++ b/README.md
@@ -2,6 +2,11 @@
 description: "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。"
 ---
 > **模板说明（复制后删除本段）**  
 > 本文是技能市场详情与普通用户说明，**不是** Agent 参考索引、CLI 契约或开发文档。  
 > frontmatter 的 `description` 必须是用户能看懂的一句话能力描述；**不得**写成 CLI、schema、references、development、契约、数据结构、开发规范或 Agent 参考索引。  
 > 正文只回答用户关心的问题，**不要**把 Playwright、DOM、Python、RPA、references、development、schema 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。
 # 【技能名称】
 > 用一两句话说明这个技能帮助用户完成什么工作。  
--- a/SKILL.md
+++ b/SKILL.md
@@ -20,6 +20,25 @@ allowed-tools:
 这是一个**用于复制的新技能模板**，不是业务 skill 本身。复制后请替换占位内容，实现你的真实业务逻辑。
 ## 面向用户问答（LLM 规则）
 - 本文（`SKILL.md`）是 LLM / OpenClaw 平台读取的技能入口，**不是**用户市场说明。
 - 根目录 `README.md` 是面向普通用户的说明。
 当用户询问以下问题时，**必须优先读取**根目录 `README.md`，并用用户能理解的业务语言回答：
 - 这个技能是做什么的
 - 这个技能怎么用
 - 适合什么场景
 - 使用前要准备什么
 - 执行后会得到什么
 - 能不能帮我完成某个业务任务
 - **不要**把 `SKILL.md`、`references/`、`development/` 中的技术细节直接作为用户回答。
 - **只有当**用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 `references/` 或 `development/`。
 - 若 `README.md` 与 `SKILL.md` / `references` 表述冲突：对用户展示与市场说明以 `README.md` 为准；对执行契约、CLI、schema、运行约束以 `SKILL.md` / `references` 为准。
 - 回答用户时**不要**暴露 Playwright、DOM、Python、RPA 等实现细节，除非用户明确询问技术实现。
 ## 文档分工
 | 文档 | 读者 | 用途 |
--- a/development/ADAPTER.md
+++ b/development/ADAPTER.md
@@ -51,11 +51,13 @@ scripts/service/<domain>_adapter/
  real_rpa.py        # 真实系统 RPA（占位，谨慎实现）
 ```
-模板示例：
+模板示例（均在 `examples/`，**不在** `scripts/`）：
- **四档骨架（占位）**：`scripts/service/example_adapter/` — 复制改名后补齐业务 adapter
+- **仿真浏览器 RPA 完整案例**：`examples/simulator_browser_rpa/` — mock + simulator_rpa + sandbox 页面 + adapter 分层 + 测试
 - **仿真浏览器 RPA 完整案例**：`examples/simulator_browser_rpa/` — mock + simulator_rpa + sandbox 页面 + 测试
 - **真实浏览器 RPA 完整案例**：`examples/real_browser_rpa/` — 登录/验证码/滚动采集
 - **真实 API / 仿真 API**：`examples/real_api/`、`examples/simulator_api/` — 当前为规划占位，尚未沉淀可复制实现
 复制 adapter 分层时，以 `examples/simulator_browser_rpa/scripts/service/adapter/` 为权威参考，在新技能中创建 `scripts/service/<domain>_adapter/` 并按 README copy map 选择性复制。
 > 先判断属于四象限哪一种（`real_browser_rpa` / `real_api` / `simulator_browser_rpa` / `simulator_api`），再读对应 `examples/*/README.md`。示例是**参考架构与边界**，不是业务代码原样复制。
--- a/development/DEVELOPMENT.md
+++ b/development/DEVELOPMENT.md
@@ -160,18 +160,17 @@ scripts/
 若 skill 需要浏览器/桌面/手机自动化，按以下顺序落地：
 1. **先读三份标准**：`RPA.md`（三端范式与反反爬）、`CONFIG.md`（`.env` 落盘与读取）、`ADAPTER.md`（四档 adapter）。
-2. **从模板复制骨架**：
+2. **从 examples 选择性复制**（不要整包照搬 `examples/<mode>/`，见各 example README 的 copy map）：
-   - `scripts/service/example_adapter/` → 改名为 `scripts/service/<domain>_adapter/`（仅 adapter 四档骨架，**不等同于**真实浏览器 RPA 成功案例）
+   - 若是 **真实浏览器 RPA**（真实网站、登录态、验证码、滚动采集），**必须先读** `examples/real_browser_rpa/README.md`，再按需复制到 `scripts/service/`：
   - 若是 **真实浏览器 RPA**（真实网站、登录态、验证码、滚动采集），**必须先读** `examples/real_browser_rpa/README.md`，再按需参考：
     - `examples/real_browser_rpa/scripts/service/browser_session.py`
     - `examples/real_browser_rpa/scripts/service/human_verification.py`
     - `examples/real_browser_rpa/scripts/service/task_rpa.py`
     - `examples/real_browser_rpa/scripts/service/account_client.py`
-   - 若是 **仿真浏览器 RPA**（自有 sandbox、表单批量提交、可控 DOM），**必须先读** `examples/simulator_browser_rpa/README.md`，再按需参考：
+   - 若是 **仿真浏览器 RPA**（自有 sandbox、表单批量提交、可控 DOM），**必须先读** `examples/simulator_browser_rpa/README.md`，再按需复制到 `scripts/service/`：
     - `examples/simulator_browser_rpa/scripts/service/browser_session.py`
     - `examples/simulator_browser_rpa/scripts/service/adapter/`
     - `examples/simulator_browser_rpa/scripts/service/task_service.py`
-     - `examples/simulator_browser_rpa/sandbox/demo_app.html`
+     - `sandbox/demo_app.html` 仅留在 examples，不进入生产 skill
 3. **只用共享库，不在 skill 里重写反反爬**：
   ```python
   from jiangchang_skill_core import config
@@ -216,6 +215,28 @@ scripts/
 `health` 应委托 `collect_runtime_diagnostics`，不要在 `scripts/util/` 自建 `runtime_diagnostics.py`。
 ### 3.4 发布打包约束（PyArmor 与编码）
 release workflow 会对 `scripts/` 下的 Python 源码做加密/打包。当前发布链路可能运行在 **PyArmor 免费/试用模式**，因此有两条**发布硬约束**：
 **单文件行数（仅 `scripts/**/*.py`）**
 - 每个 `scripts/` 下 Python 文件必须 **小于 1000 行**（`>= 1000` 可能在 CI 加密阶段失败）。
 - 推荐单文件控制在 **900 行以内**；接近上限时应拆分模块。
 - 不要把完整 RPA 主流程、DOM 选择器、数据库、CLI、日志全部堆进一个大文件。
 - 正确做法是拆分到 `scripts/cli/`、`scripts/service/`、`scripts/db/`、`scripts/util/`。
 `examples/` 里的 Python 示例也建议保持模块化，但**行数限制不作为 examples 的发布硬约束**；不要对 README、HTML、测试数据等文档/资源套用 PyArmor 行数规则。
 **文本编码（UTF-8 without BOM）**
 - 所有提交到 skill 的源码、文档、配置文本文件必须是 **UTF-8 without BOM**。
 - Python 文件**绝对不能**带 UTF-8 BOM；否则 PyArmor/CI 可能报：`invalid non-printable character U+FEFF`。
 - Windows 编辑器容易保存成 UTF-8 BOM，提交前须确认文件开头无 `U+FEFF`。
 - 不要只写「UTF-8」，必须明确 **UTF-8 without BOM**。
 本地可用 `python tests/run_tests.py release_packaging_constraints -v` 自检；默认必跑套件中的 `test_release_packaging_constraints.py` 会守护上述规则。
 ## 4. 开发一个新 skill 的标准步骤
 下面这套顺序建议严格按步骤做，不要一上来就直接写 `service`。
@@ -343,7 +364,7 @@ metadata:
 **`references/`**（Agent 运行/编排/调用时渐进加载）
- `README.md` — Agent 参考索引
+- `README.md` — Agent 参考索引（**不是**市场说明；不得含 YAML frontmatter 或 `description`）
 - `CLI.md` — 命令、参数、默认值、兄弟技能调用方式
 - `SCHEMA.md` — 数据库路径、核心表结构、日志表结构
 - 可按需增加 `ERRORS.md`、`INTEGRATION.md` 等编排向补充
@@ -529,6 +550,20 @@ python scripts/main.py <your-command>
 ## 15. 发布到正式环境验证
 ### release workflow 通道
 `.github/workflows/release_skill.yaml` 默认引用：
 ```yaml
 uses: client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml@main
 ```
 约定如下：
 - `jiangchang-platform-kit` 的 `main` 分支即稳定通道；kit 的开发、测试、验证须在合并 `main` 前完成。
 - skill **不需要**锁定 workflow 版本（不要改为 `@v1`、`@v1.0.x` 等）。
 - skill 运行时最低能力要求通过 `SKILL.md` 的 `metadata.openclaw.platform_kit_min_version` 声明。
 在执行 `release.ps1` 之前，必须先在本地确认 `python tests/run_tests.py -v` 通过。测试不通过不得发起正式发布。
 当本地开发、自测和联调完成后，还需要把 skill 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。
@@ -653,6 +688,8 @@ python scripts/main.py <your-command>
 - [ ] `release.ps1` 存在
 - [ ] `.github/workflows/release_skill.yaml` 存在
 - [ ] `python tests/run_tests.py -v` 全部通过
 - [ ] `scripts/**/*.py` 单文件 **< 1000 行**（PyArmor 试用/免费模式限制；推荐 < 900 行）
 - [ ] 源码/文档/配置为 **UTF-8 without BOM**（Python 文件不得含 `U+FEFF`）
 - [ ] 没有新增默认必跑测试访问真实网络或浏览器
 - [ ] 如有 integration 测试需求，已写在 `tests/integration/` 下并保持 `.sample` 后缀
--- a/development/README.md
+++ b/development/README.md
@@ -8,7 +8,7 @@
 4. [`ADAPTER.md`](ADAPTER.md) — 涉及外部系统对接时
 5. [`RPA.md`](RPA.md) — 涉及浏览器 / 桌面 / 手机自动化时
 6. [`CONFIG.md`](CONFIG.md) — `.env` 规范与 bootstrap 机制
-7. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径与诊断约定
+7. [`RUNTIME.md`](RUNTIME.md) — 共享 runtime、数据路径、发布打包与编码约定
 Agent 调用契约见 [`../references/CLI.md`](../references/CLI.md)、[`../references/SCHEMA.md`](../references/SCHEMA.md)。  
 用户市场说明见根目录 [`README.md`](../README.md)，不要写进本目录。
--- a/development/RPA.md
+++ b/development/RPA.md
@@ -99,15 +99,15 @@ BrowserType.launch_persistent_context: Arguments can not specify page to be open
 > - 再参考 `examples/real_browser_rpa/scripts/service/human_verification.py`
 > - 再参考 `examples/real_browser_rpa/scripts/service/task_rpa.py`
-### 1.4 安装
+### 1.4 Playwright 与安装边界
-生产/宿主运行：`playwright` 由共享 runtime 提供，无需在技能内 `pip install`。
+- Playwright 是宿主共享 runtime 提供的通用 Python 包能力；**正式 skill 不负责安装**。
 - skill 侧**禁止**在 `requirements.txt`、安装脚本、运行脚本、根 `README.md` 用户说明中加入 `playwright install`、`pip install playwright` 或任何自动安装浏览器驱动的逻辑。
 - 真实浏览器 RPA 默认使用**系统 Chrome/Edge**，由宿主/runtime 管理。
 - **不要**执行 `playwright install chromium`、`playwright install chrome` 等浏览器驱动安装命令。
 - 仅当**本地独立开发环境排障**时，开发者可手工检查或补装 Python 包 `playwright`；该操作**不得**进入 skill 交付文件与自动流程。
-独立本地开发环境若缺少 Python 包 `playwright` 时，可手动执行：
+页面启动仍遵循 1.2：`launch_persistent_context` 的 `args` 只能放 Chrome 启动参数，**不能把 URL 塞进 `args`**；打开页面必须通过 `new_page()` + `goto()`，或通过真实地址栏/点击进入。
 ```bash
 pip install playwright   # 仅独立开发补装；用系统 Chrome，无需 playwright install chromium
 ```
 ### 引用方式
@@ -138,7 +138,7 @@ from jiangchang_skill_core.rpa.stealth import stealth_enabled, STEALTH_INIT_SCRI
   - `examples/real_browser_rpa/scripts/service/task_rpa.py` — RPA 主流程
   - `examples/real_browser_rpa/scripts/service/account_client.py` — account-manager CLI 封装
-模板内 adapter 仿真示例（`scripts/service/example_adapter/sim_rpa.py`）仅用于 **adapter 四档骨架**，不能替代真实浏览器 RPA 规范。
+仿真浏览器 RPA 的 adapter 分层权威参考见 `examples/simulator_browser_rpa/scripts/service/adapter/`，**不能**替代真实浏览器 RPA 规范。
 ### 1.6 仿真浏览器 RPA 示例（必读）
--- a/development/RUNTIME.md
+++ b/development/RUNTIME.md
@@ -108,6 +108,17 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
 ## 编码与输出
 - 所有提交到 skill 的源码、文档、配置文本文件必须是 **UTF-8 without BOM**（不要只写「UTF-8」）。
 - Python 文件**绝对不能**带 UTF-8 BOM；否则 release CI 的 PyArmor 阶段可能报：`invalid non-printable character U+FEFF`。
 - Windows 编辑器容易保存成 UTF-8 BOM；提交前确认文件开头无 `U+FEFF`。
 - Windows 终端建议在 `scripts/main.py` 里做 UTF-8 stdout/stderr 包装
 - 机读输出优先单行 JSON
 - 错误前缀建议统一 `ERROR:`
 ## 发布打包约束（`scripts/**/*.py`）
 release workflow 加密 `scripts/` 源码时，可能运行在 PyArmor 免费/试用模式：
 - `scripts/**/*.py` 单文件必须 **< 1000 行**（`>= 1000` 可能在 CI 失败）；推荐 **< 900 行**。
 - 接近上限时拆分到 `cli/`、`service/`、`db/`、`util/`，不要把 RPA 主流程、选择器、DB、CLI 堆进单文件。
 - 此行数限制**仅适用于** `scripts/**/*.py`；不限制 README 等文档行数，也不把 examples 里的 HTML/README 纳入 PyArmor 行数约束。
--- a/development/TESTING.md
+++ b/development/TESTING.md
@@ -29,6 +29,7 @@
 - `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_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
 **原则：`tests/test_*.py` 不允许隐形访问外网、不允许拉起真实浏览器、不允许读写开发者机器的真实数据根**。如果需要仿真服务器，也应仅在 integration（并由档位变量放行）。
@@ -224,6 +225,8 @@ Golden fixture 流程同理（[`tests/samples/test_golden_cases.py.sample`](../t
 - [ ] `pytest.ini` 存在且 `python_files` 只收集 `test_*.py` / `*_test.py`
 - [ ] pytest **不会**误收集 `tests/` 下的 `.txt` / 日志 / 结果文件
 - [ ] `python tests/run_tests.py -v` 全部通过
 - [ ] `scripts/**/*.py` 单文件 < 1000 行（`test_release_packaging_constraints.py`）
 - [ ] 文本文件为 UTF-8 without BOM，无 `U+FEFF`（同上）
 ---
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,13 +1,21 @@
 # Skill Template Examples
-四类 adapter 示例（先选类型，再写代码；**不要跨类型照抄**）：
+`examples/` 是面向**技术人员与 AI 编程工具**的**核心实现案例**目录：提供可运行、可测试、可复制的参考代码，用于指导新技能的 `scripts/` 应如何编写。
 **`examples/` 不是完整 skill 仓库。** 不要整包照搬 `examples/<mode>/` 到新技能根目录。应按各 example README 的 **copy map**，**选择性复制**到新技能的 `scripts/`（及按需的 `tests/`）。
 根 `README.md`、`SKILL.md`、`references/`、`development/` 仍按模板主目录规则编写，**不要**从 `examples/` 复制。
 ## 四类外部交互方式
 一级目录固定为四种模式（不可删除、不可移动）：
 | 目录 | 类型 | 状态 | 适用场景 |
 |---|---|---|---|
-| real_browser_rpa | 真实浏览器 RPA | **已有案例** | 真实第三方网站、登录态、人工验证、滚动采集 |
+| `real_browser_rpa` | 真实浏览器 RPA | **已有案例** | 真实第三方网站、登录态、人工验证、滚动采集 |
-| simulator_browser_rpa | 仿真浏览器 RPA | **已有案例** | 自有 sandbox、可控页面、表单 RPA、端到端教学/回归 |
+| `simulator_browser_rpa` | 仿真浏览器 RPA | **已有案例** | 自有 sandbox、可控页面、表单 RPA、adapter 分层 |
-| real_api | 真实 API | 占位，后续补案例 | 真实系统接口、token、权限、限流 |
+| `real_api` | 真实 API | **占位** | 真实系统接口、token、权限、限流（尚未沉淀可复制实现） |
-| simulator_api | 仿真 API | 占位，后续补案例 | mock/sandbox API、无需浏览器 |
+| `simulator_api` | 仿真 API | **占位** | mock/sandbox API、无需浏览器（尚未沉淀可复制实现） |
 ## 两类浏览器 RPA 的区别
@@ -18,19 +26,44 @@
 | 账号 | 通常需 account-manager + profile | 示例可用 env / demo 账号 |
 | 用途 | 生产级真实采集/操作参考 | adapter 分层 + 表单 RPA 教学 |
 ## 当前状态
 - **real_browser_rpa**：已有可参考代码 → 先读 `real_browser_rpa/README.md`
 - **simulator_browser_rpa**：已有完整示例（含 `sandbox/demo_app.html`）→ 先读 `simulator_browser_rpa/README.md`
 - **real_api** / **simulator_api**：目录占位，后续补案例
 ## 如何选择示例
 | 你的场景 | 参考目录 |
 |---|---|
 | 真实网站 + 浏览器 + 登录/验证码/滚动 | **real_browser_rpa** |
 | 仿真页面 + 浏览器 + 表单/批量提交 | **simulator_browser_rpa** |
-| 真实系统 API | 后续 **real_api** |
+| 真实系统 API | **real_api**（当前占位，不可作为实现参考） |
-| mock / sandbox API（无浏览器） | 后续 **simulator_api** |
+| mock / sandbox API（无浏览器） | **simulator_api**（当前占位，不可作为实现参考） |
-> 示例提供的是**参考架构与边界**，不是业务代码原样复制。复制前先读对应 README 的「复制边界 / 禁止照抄」章节。
+## 轻量结构约定
 每个 `examples/<mode>/` 推荐结构：
 ```text
 examples/<mode>/
  README.md
  scripts/
    service/
    util/
  tests/
 ```
 - 仅 `simulator_browser_rpa` 可额外包含 `sandbox/`
 - 仅未来确实需要样例数据时可加 `fixtures/`
 - **不要**在 `examples/<mode>/` 下要求或添加：`SKILL.md`、根市场 `README.md`、`references/`、`development/`、`assets/`、`.github/`、release workflow 等完整 skill 仓库层文件
 ## `scripts/` 与 `examples/` 边界
 | | `scripts/` | `examples/` |
 |---|---|---|
 | 定位 | 真实技能业务逻辑的标准骨架 | 核心实现案例与复制参考 |
 | 内容 | 干净的技能骨架，无教学/demo 代码 | 可运行参考实现，非完整 skill |
 | 旧示例 | **不得**出现 `example_*` 目录或文件 | 四类一级目录固定保留 |
 复制规则：
 - 真实浏览器 RPA → 参考 `examples/real_browser_rpa/`
 - 仿真浏览器 RPA → 参考 `examples/simulator_browser_rpa/`（adapter 分层权威参考：`scripts/service/adapter/`）
 - `real_api/`、`simulator_api/` 当前为规划占位，**不得**作为实现参考
 > 示例提供的是**参考架构与边界**，不是业务代码原样复制。复制前先读对应 README 的 copy map 与「禁止照抄」章节。
--- a/examples/real_api/README.md
+++ b/examples/real_api/README.md
@@ -1,15 +1,35 @@
 # Real API Example
-这个目录用于沉淀“真实系统 API”类 skill 的可复制成功案例。
+这个目录用于沉淀「真实系统 API」类 skill 的可复制成功案例。
-## 适用场景
+## 适用场景（规划）
 - 目标系统提供真实 API
 - 需要 token / secret / credential
 - 需要请求重试、权限校验、限流处理、schema 校验和幂等写库
-## 当前状态
+## 当前状态：规划占位
- 本目录暂时只保留结构占位。
+- **本目录当前为规划占位**，仅保留最小结构（`README.md`、`scripts/`、`tests/` 占位）。
- 示例业务尚未确定。
+- **尚未沉淀可复制实现**；目录内无参考代码。
- 本轮不包含示例代码。
+- **AI 编程工具不得**基于空目录自行脑补 API 对接实现。
 - 后续补齐可复制案例后，再按 README copy map 选择性复制到新技能 `scripts/`。
 ## 轻量结构
 ```text
 real_api/
  README.md
  scripts/
    service/
    util/
  tests/
 ```
 不要在本目录添加 `SKILL.md`、市场 README、`references/`、`development/`、`.github/` 等完整 skill 仓库层文件。
 ## 复制边界（待案例补齐后生效）
 - 参考代码将从 `examples/real_api/scripts/` 选择性复制到新技能 `scripts/`
 - 根 `README.md`、`SKILL.md`、`references/` 仍按模板主目录规则编写
 - 当前阶段：**不可作为实现参考**
--- a/examples/real_browser_rpa/README.md
+++ b/examples/real_browser_rpa/README.md
@@ -53,13 +53,35 @@ real_browser_rpa/
 ## 开发新 skill 时如何复制
-1. **先阅读** `examples/real_browser_rpa/README.md`（本节及下方「复制边界」）
+1. **先阅读**本 README 及下方「Copy map」「复制边界」章节
-2. 复制整个 `examples/real_browser_rpa/` 到新 skill 的 `scripts/` 结构（或作为起点合并）
+2. 按 copy map **选择性复制**到新技能 `scripts/`（**不要**整包照搬 `examples/real_browser_rpa/`）
 3. 修改 `util/constants.py` 中的 `TARGET_PLATFORM`、`DEFAULT_START_URL`、selector 常量
 4. 替换 `task_rpa.py` 中的登录态 marker、搜索框/结果解析逻辑（**必须 F12 实测**）
 5. 替换 `human_verification.py` 中的验证码 selector（若目标站点 DOM 不同）
 6. 在 `task_service.py` 中接入真实 DB、任务日志、RpaVideoSession
-7. 添加 CLI 入口（`scripts/main.py`），并补齐 `SKILL.md` 的 LLM/运行契约说明与根 `README.md` 的用户市场说明
+7. 在新技能根目录补齐 `scripts/main.py` CLI；`SKILL.md` 与根 `README.md` 按模板主目录规则编写，**不要**复制本 README
 ## Copy map（复制到新技能 `scripts/`）
 | 来源（examples） | 目标（新技能） | 说明 |
 |---|---|---|
 | `examples/real_browser_rpa/scripts/service/browser_session.py` | `scripts/service/browser_session.py` | persistent context 启动范式 |
 | `examples/real_browser_rpa/scripts/service/account_client.py` | `scripts/service/account_client.py` | account-manager CLI 集中封装 |
 | `examples/real_browser_rpa/scripts/service/human_verification.py` | `scripts/service/human_verification.py` | 人工验证等待 |
 | `examples/real_browser_rpa/scripts/service/task_rpa.py` | `scripts/service/<业务名>_rpa.py` 或 `scripts/service/task_rpa.py` | RPA 主流程，按业务改名 |
 | `examples/real_browser_rpa/scripts/service/task_service.py` | `scripts/service/task_service.py` | 参考并合并编排层 |
 | `examples/real_browser_rpa/scripts/util/constants.py` | `scripts/util/constants.py` | 平台常量与 selector（须替换） |
 | `examples/real_browser_rpa/scripts/util/logging.py` | `scripts/util/logging.py` | 可选，按需合并 |
 | `examples/real_browser_rpa/tests/` | `tests/` | 可按需复制测试思路 |
 | `examples/real_browser_rpa/README.md` | — | **只读参考**，不复制为新技能根 README |
 **复制时必须替换：** selector、URL、平台名称、账号平台字段、slug、logger 名等业务标识。**不要**照搬示例字段到其他平台。
 **浏览器与启动约束：**
 - **不要**在技能内安装 Playwright；浏览器与 Python 包由宿主/runtime 提供
 - `launch_persistent_context` 的 `args` **只放 Chrome 参数**；**不要把 URL 放进 `args`**
 - 页面必须通过 `new_page()` + `goto()`，或通过真实地址栏/点击进入
 ## 复制边界：哪些能复制，哪些必须替换
--- a/examples/simulator_api/README.md
+++ b/examples/simulator_api/README.md
@@ -1,15 +1,35 @@
 # Simulator API Example
-这个目录用于沉淀“仿真环境 / API”类 skill 的可复制成功案例。
+这个目录用于沉淀「仿真环境 / API」类 skill 的可复制成功案例。
-## 适用场景
+## 适用场景（规划）
 - 使用 mock / sandbox / simulator API
 - 不需要启动浏览器
 - 适合演示输入校验、API 调用、结果入库、日志、错误契约和测试
-## 当前状态
+## 当前状态：规划占位
- 本目录暂时只保留结构占位。
+- **本目录当前为规划占位**，仅保留最小结构（`README.md`、`scripts/`、`tests/` 占位）。
- 示例业务尚未确定。
+- **尚未沉淀可复制实现**；目录内无参考代码。
- 本轮不包含示例代码。
+- **AI 编程工具不得**基于空目录自行脑补 mock API 或仿真接口实现。
 - 后续补齐可复制案例后，再按 README copy map 选择性复制到新技能 `scripts/`。
 ## 轻量结构
 ```text
 simulator_api/
  README.md
  scripts/
    service/
    util/
  tests/
 ```
 不要在本目录添加 `SKILL.md`、市场 README、`references/`、`development/`、`.github/` 等完整 skill 仓库层文件。
 ## 复制边界（待案例补齐后生效）
 - 参考代码将从 `examples/simulator_api/scripts/` 选择性复制到新技能 `scripts/`
 - 根 `README.md`、`SKILL.md`、`references/` 仍按模板主目录规则编写
 - 当前阶段：**不可作为实现参考**
--- a/examples/simulator_browser_rpa/README.md
+++ b/examples/simulator_browser_rpa/README.md
@@ -66,6 +66,29 @@ simulator_browser_rpa/
 ## 复制到新 skill 时怎么做
 按 copy map **选择性复制**到 `scripts/`；**不要**整包照搬本目录，**不要**把本 README 当作新技能根 README。
 ## Copy map（复制到新技能 `scripts/`）
 | 来源（examples） | 目标（新技能） | 说明 |
 |---|---|---|
 | `examples/simulator_browser_rpa/scripts/service/browser_session.py` | `scripts/service/browser_session.py` | URL 仅 `page.goto`，不进 launch args |
 | `examples/simulator_browser_rpa/scripts/service/account_client.py` | `scripts/service/account_client.py` | 账号来源集中封装 |
 | `examples/simulator_browser_rpa/scripts/service/task_service.py` | `scripts/service/task_service.py` | 编排层，合并业务逻辑 |
 | `examples/simulator_browser_rpa/scripts/service/adapter/` | `scripts/service/<domain>_adapter/` | **adapter 分层权威参考** |
 | `examples/simulator_browser_rpa/scripts/util/constants.py` | `scripts/util/constants.py` | 须替换业务常量 |
 | `examples/simulator_browser_rpa/scripts/util/logging.py` | `scripts/util/logging.py` | 可选 |
 | `examples/simulator_browser_rpa/tests/` | `tests/` | 可按需复制 dispatch / unit 测试 |
 | `examples/simulator_browser_rpa/sandbox/demo_app.html` | — | **仅仿真测试用**，不进入生产 skill |
 | `examples/simulator_browser_rpa/README.md` | — | **只读参考**，不复制为新技能根 README |
 **边界说明：**
 - `sandbox/` 只用于仿真测试与本地回归，**不进入**真实生产 skill
 - `adapter/` 分层（base / mock / simulator_rpa）是仿真浏览器 RPA 的权威参考
 - `mock` / `simulator_rpa` 只用于测试与仿真，**不要**混入 `real_browser_rpa` 的真实站点逻辑
 - `demo_app.html` 是可运行沙箱页面，**不是**真实业务系统
 **保留：**
 - adapter 分层（base / mock / simulator_rpa / `select_adapter`）
--- a/references/README.md
+++ b/references/README.md
@@ -1,6 +1,12 @@
 # Agent 参考索引
-本目录供 Agent **运行、编排、调用** skill 时渐进式加载，不是用户市场说明。
+本目录只是 Agent **运行、编排、调用** skill 时可渐进加载的资料索引，**不是**用户市场说明。
 **边界规则：**
 - 本文**不得**包含 YAML frontmatter，**不得**包含 `description` 字段。
 - 技能市场详情与普通用户说明**必须**放在根目录 [`README.md`](../README.md)。
 - 本目录只保留运行时引用资料（如 `CLI.md`、`SCHEMA.md`）；开发规范放在 [`../development/`](../development/)。
 | 文档 | 用途 |
 |------|------|
--- a/release.ps1
+++ b/release.ps1
@@ -1,3 +1,15 @@
 <#
 .SYNOPSIS
  Local git release for skill-template repo.
 .DESCRIPTION
  Handles git commit / push / semver tag / push tag only.
  Encryption, ZIP packaging, and marketplace sync are done by CI
  (.github/workflows/release_skill.yaml → reusable-release-skill.yaml@main).
  Requires: git, PowerShell 5+
 #>
 [CmdletBinding()]
 param(
  [string]$Prefix = "v",
@@ -11,13 +23,228 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
-$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+function Remove-GitNoise {
-$sharedScript = Join-Path $scriptDir "..\..\jiangchang-platform-kit\tools\release.ps1"
+  param([string[]]$Lines)
-$sharedScript = [System.IO.Path]::GetFullPath($sharedScript)
+  return @($Lines | Where-Object {
-
+    $_ -and ($_ -notmatch '^warning:\s+unable to access ')
-if (-not (Test-Path $sharedScript)) {
+  })
  throw "Shared release script not found: $sharedScript"
 }
-& $sharedScript @PSBoundParameters
+function Invoke-Git {
-exit $LASTEXITCODE
+  param([Parameter(Mandatory = $true)][string]$Args)
  Write-Host ">> git $Args" -ForegroundColor DarkGray
  & cmd /c "git $Args 2>&1" | Out-Null
  if ($LASTEXITCODE -ne 0) {
    throw "git command failed: git $Args"
  }
 }
 function Get-GitOutput {
  param([Parameter(Mandatory = $true)][string]$Args)
  $output = & cmd /c "git $Args 2>&1"
  if ($LASTEXITCODE -ne 0) {
    throw "git command failed: git $Args"
  }
  return @(Remove-GitNoise -Lines @($output))
 }
 function Test-Repo {
  $output = & cmd /c "git rev-parse --is-inside-work-tree 2>&1"
  if ($LASTEXITCODE -ne 0) {
    return $false
  }
  $clean = Remove-GitNoise -Lines @($output)
  return (($clean | Select-Object -First 1) -eq "true")
 }
 function Get-CurrentBranch {
  $b = (Get-GitOutput "branch --show-current" | Select-Object -First 1).Trim()
  return $b
 }
 function Get-StatusPorcelain {
  $lines = @(Get-GitOutput "status --porcelain")
  return $lines
 }
 function Parse-SemVerTag {
  param(
    [string]$Tag,
    [string]$TagPrefix
  )
  $escaped = [regex]::Escape($TagPrefix)
  $m = [regex]::Match($Tag, "^${escaped}(\d+)\.(\d+)\.(\d+)$")
  if (-not $m.Success) { return $null }
  return [pscustomobject]@{
    Raw   = $Tag
    Major = [int]$m.Groups[1].Value
    Minor = [int]$m.Groups[2].Value
    Patch = [int]$m.Groups[3].Value
  }
 }
 function Get-NextTag {
  param([string]$TagPrefix)
  $tags = Get-GitOutput "tag --list"
  $parsed = @()
  foreach ($t in $tags) {
    $t = $t.Trim()
    if (-not $t) { continue }
    $obj = Parse-SemVerTag -Tag $t -TagPrefix $TagPrefix
    if ($null -ne $obj) { $parsed += $obj }
  }
  if ($parsed.Count -eq 0) {
    return "${TagPrefix}1.0.1"
  }
  $latest = $parsed | Sort-Object Major, Minor, Patch | Select-Object -Last 1
  return "$TagPrefix$($latest.Major).$($latest.Minor).$([int]$latest.Patch + 1)"
 }
 function Assert-SkillReleasePackagingSources {
  param([Parameter(Mandatory = $true)][string]$SkillRoot)
  $scriptsDir = Join-Path $SkillRoot "scripts"
  $mainPy = Join-Path $scriptsDir "main.py"
  if (-not (Test-Path -LiteralPath $mainPy)) {
    return
  }
  $text = Get-Content -LiteralPath $mainPy -Raw -Encoding UTF8 -ErrorAction SilentlyContinue
  if ([string]::IsNullOrWhiteSpace($text)) {
    return
  }
  $need = @()
  if ($text -match '(?m)^\s*from\s+cli\.') { $need += 'cli' }
  if ($text -match '(?m)^\s*import\s+cli\b') { $need += 'cli' }
  if ($text -match '(?m)^\s*from\s+service\.') { $need += 'service' }
  if ($text -match '(?m)^\s*import\s+service\b') { $need += 'service' }
  if ($text -match '(?m)^\s*from\s+db\.') { $need += 'db' }
  if ($text -match '(?m)^\s*import\s+db\b') { $need += 'db' }
  if ($text -match '(?m)^\s*from\s+util\.') { $need += 'util' }
  if ($text -match '(?m)^\s*import\s+util\b') { $need += 'util' }
  foreach ($p in ($need | Select-Object -Unique)) {
    $folder = Join-Path $scriptsDir $p
    if (-not (Test-Path -LiteralPath $folder)) {
      throw "Release check failed: scripts/main.py imports from '$p' but folder is missing: $folder"
    }
  }
  $pyFiles = @(Get-ChildItem -LiteralPath $scriptsDir -Filter *.py -Recurse -File -ErrorAction SilentlyContinue)
  Write-Host "Packaging check: $($pyFiles.Count) Python file(s) under scripts/ (CI will obfuscate all recursively)." -ForegroundColor DarkGray
 }
 function Ensure-CleanOrAutoCommit {
  param(
    [switch]$DoAutoCommit,
    [switch]$NeedClean,
    [switch]$IsDryRun,
    [string]$Msg
  )
  $status = @(Get-StatusPorcelain)
  if ($status.Length -eq 0) { return }
  if ($NeedClean) {
    Write-Host "Working tree is not clean and -RequireClean is enabled." -ForegroundColor Yellow
    Remove-GitNoise -Lines @(& cmd /c "git status --short 2>&1") | ForEach-Object { Write-Host $_ }
    throw "Abort: dirty working tree."
  }
  $commitMsg = $Msg
  if ([string]::IsNullOrWhiteSpace($commitMsg)) {
    $commitMsg = "chore: auto release commit ($(Get-Date -Format 'yyyy-MM-dd HH:mm:ss'))"
  }
  if (-not $DoAutoCommit) {
    Write-Host "Detected uncommitted changes, auto-committing before release..." -ForegroundColor Yellow
  }
  if ($IsDryRun) {
    Write-Host "[DryRun] Would run: git add -A" -ForegroundColor Yellow
    Write-Host "[DryRun] Would run: git commit -m `"$commitMsg`"" -ForegroundColor Yellow
    return
  }
  Invoke-Git "add -A"
  Invoke-Git "commit -m `"$commitMsg`""
 }
 try {
  Write-Host "=== Release Script Start ===" -ForegroundColor Cyan
  if (-not (Test-Repo)) {
    throw "Current directory is not a git repository."
  }
  $branch = Get-CurrentBranch
  if ([string]::IsNullOrWhiteSpace($branch)) {
    throw "Unable to determine current branch."
  }
  if ($branch -notin @("main", "master")) {
    throw "Current branch is '$branch'. Release is only allowed from main/master."
  }
  if ($DryRun) {
    Write-Host "[DryRun] Would run: git fetch --tags --prune origin" -ForegroundColor Yellow
  } else {
    Invoke-Git "fetch --tags --prune origin"
  }
  Ensure-CleanOrAutoCommit -DoAutoCommit:$AutoCommit -NeedClean:$RequireClean -IsDryRun:$DryRun -Msg $CommitMessage
  $skillRoot = (Get-GitOutput "rev-parse --show-toplevel" | Select-Object -First 1).Trim()
  if (Test-Path -LiteralPath (Join-Path $skillRoot "SKILL.md")) {
    Assert-SkillReleasePackagingSources -SkillRoot $skillRoot
  }
  $null = Remove-GitNoise -Lines @(& cmd /c 'git rev-parse --abbrev-ref --symbolic-full-name "@{u}" 2>&1')
  $hasUpstream = ($LASTEXITCODE -eq 0)
  if ($DryRun) {
    if ($hasUpstream) {
      Write-Host "[DryRun] Would run: git push" -ForegroundColor Yellow
    } else {
      Write-Host "[DryRun] Would run: git push -u origin $branch" -ForegroundColor Yellow
    }
  } else {
    if ($hasUpstream) {
      Invoke-Git "push"
    } else {
      Invoke-Git "push -u origin $branch"
    }
  }
  $nextTag = Get-NextTag -TagPrefix $Prefix
  Write-Host "Next tag: $nextTag" -ForegroundColor Green
  $existing = @(Get-GitOutput "tag --list `"$nextTag`"")
  if ($existing.Length -gt 0) {
    throw "Tag already exists: $nextTag"
  }
  if ($DryRun) {
    Write-Host "[DryRun] Would run: git tag -a $nextTag -m `"$Message`"" -ForegroundColor Yellow
    Write-Host "[DryRun] Would run: git push origin $nextTag" -ForegroundColor Yellow
    Write-Host "=== DryRun Complete ===" -ForegroundColor Cyan
    exit 0
  }
  Invoke-Git "tag -a $nextTag -m `"$Message`""
  Invoke-Git "push origin $nextTag"
  Write-Host "Release success: $nextTag" -ForegroundColor Green
  Write-Host "=== Release Script Done ===" -ForegroundColor Cyan
  exit 0
 }
 catch {
  Write-Host "Release failed: $($_.Exception.Message)" -ForegroundColor Red
  exit 1
 }
--- a/scripts/service/example_adapter/init.py
+++ b/scripts/service/example_adapter/init.py
@@ -1,26 +0,0 @@
 """示例 adapter 四档 dispatch。
 由 ``OPENCLAW_TEST_TARGET``（或 ``config.get``）决定档位。
 复制本目录后把 ``example_adapter`` 改名为 ``<domain>_adapter``。
 """
 from __future__ import annotations
 import os
 from .mock import MockAdapter
 from .real_api import RealApiAdapter
 from .real_rpa import RealRpaAdapter
 from .sim_rpa import SimRpaAdapter
 def get_adapter():
    """返回当前档位 adapter 实例。"""
    target = (os.environ.get("OPENCLAW_TEST_TARGET") or "simulator_rpa").strip().lower()
    if target in ("unit", "mock"):
        return MockAdapter()
    if target == "real_api":
        return RealApiAdapter()
    if target == "real_rpa":
        return RealRpaAdapter()
    return SimRpaAdapter()
--- a/scripts/service/example_adapter/base.py
+++ b/scripts/service/example_adapter/base.py
@@ -1,37 +0,0 @@
 """示例适配器数据契约与基类。
 复制本目录为 ``<domain>_adapter/``，按 ADAPTER.md 实现各档位。
 业务逻辑只依赖 ``base`` 里的接口，不感知 mock / sim_rpa / real_* 差异。
 """
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
@dataclass
 class ExampleItem:
    """单条业务输入（示例）。"""
    id: str
    label: str
@dataclass
 class ExampleResult:
    """批量操作结果（以批为单位返回）。"""
    ok: bool
    serial_no: Optional[str]
    error_msg: Optional[str]
    artifacts: Dict[str, Any] = field(default_factory=dict)
 class AdapterBase:
    """四档 adapter 统一接口；子类实现 ``do_batch``。"""
    name = "base"
    def do_batch(self, target: str, items: List[ExampleItem]) -> ExampleResult:
        raise NotImplementedError
--- a/scripts/service/example_adapter/mock.py
+++ b/scripts/service/example_adapter/mock.py
@@ -1,24 +0,0 @@
 """离线 mock 档位：纯内存仿真，CI / 单测必跑。"""
 from __future__ import annotations
 from .base import AdapterBase, ExampleItem, ExampleResult
 class MockAdapter(AdapterBase):
    name = "mock"
    def do_batch(self, target: str, items: list[ExampleItem]) -> ExampleResult:
        if not items:
            return ExampleResult(
                ok=False,
                serial_no=None,
                error_msg="empty batch",
                artifacts={},
            )
        return ExampleResult(
            ok=True,
            serial_no=f"MOCK-{len(items)}",
            error_msg=None,
            artifacts={"mode": "mock", "target": target, "count": len(items)},
        )
--- a/scripts/service/example_adapter/real_api.py
+++ b/scripts/service/example_adapter/real_api.py
@@ -1,14 +0,0 @@
 """真实 API 档位占位：有官方接口时在此实现。"""
 from __future__ import annotations
 from .base import AdapterBase, ExampleItem, ExampleResult
 class RealApiAdapter(AdapterBase):
    name = "real_api"
    def do_batch(self, target: str, items: list[ExampleItem]) -> ExampleResult:
        raise NotImplementedError(
            "RealApiAdapter: 复制 example_adapter 后在此对接真实 API"
        )
--- a/scripts/service/example_adapter/real_rpa.py
+++ b/scripts/service/example_adapter/real_rpa.py
@@ -1,14 +0,0 @@
 """真实 RPA 档位占位：无 API 时最后手段，谨慎实现。"""
 from __future__ import annotations
 from .base import AdapterBase, ExampleItem, ExampleResult
 class RealRpaAdapter(AdapterBase):
    name = "real_rpa"
    def do_batch(self, target: str, items: list[ExampleItem]) -> ExampleResult:
        raise NotImplementedError(
            "RealRpaAdapter: 复制 example_adapter 后在此实现生产界面 RPA"
        )
--- a/scripts/service/example_adapter/sim_rpa.py
+++ b/scripts/service/example_adapter/sim_rpa.py
@@ -1,108 +0,0 @@
 """仿真 RPA 档位：演示 RpaVideoSession + launch_persistent_browser（需浏览器，默认开发档）。"""
 from __future__ import annotations
 import asyncio
 import os
 from datetime import datetime
 from jiangchang_skill_core import config
 from jiangchang_skill_core.rpa import anti_detect, artifacts, errors, launch_persistent_browser
 from jiangchang_skill_core.rpa.human_login import wait_for_captcha_pass
 from jiangchang_skill_core.rpa.video_session import RpaVideoSession
 from util.constants import SKILL_SLUG
 from util.runtime_paths import get_skill_data_dir, get_skill_root
 from .base import AdapterBase, ExampleItem, ExampleResult
 class SimRpaAdapter(AdapterBase):
    name = "sim_rpa"
    def do_batch(self, target: str, items: list[ExampleItem]) -> ExampleResult:
        return asyncio.run(self._do_batch_async(target, items))
    async def _do_batch_async(self, target: str, items: list[ExampleItem]) -> ExampleResult:
        example_path = os.path.join(get_skill_root(), ".env.example")
        config.ensure_env_file(SKILL_SLUG, example_path)
        url = config.get("TARGET_BASE_URL") or target or "https://example.com"
        batch_id = f"sim_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
        data_dir = get_skill_data_dir()
        profile_dir = os.path.join(data_dir, "browser-profile")
        os.makedirs(profile_dir, exist_ok=True)
        try:
            from playwright.async_api import async_playwright
        except ImportError:
            return ExampleResult(
                ok=False,
                serial_no=None,
                error_msg="playwright not installed",
                artifacts={},
            )
        artifact_paths: dict = {}
        async with RpaVideoSession(
            skill_slug=SKILL_SLUG,
            skill_data_dir=data_dir,
            batch_id=batch_id,
            title="技能仿真演示",
        ) as video:
            video.add_step("正在打开目标页面")
            try:
                async with async_playwright() as pw:
                    context = await launch_persistent_browser(
                        pw,
                        profile_dir=profile_dir,
                        headless=config.get_bool("OPENCLAW_BROWSER_HEADLESS"),
                    )
                    page = context.pages[0] if context.pages else await context.new_page()
                    await page.goto(url, wait_until="domcontentloaded", timeout=60_000)
                    await anti_detect.human_mouse_wiggle(page)
                    search = page.locator('input[type="search"], input[name="q"]').first
                    if await search.count() > 0:
                        demo_text = items[0].label if items else "openclaw-demo"
                        video.step("正在填写演示内容")
                        await anti_detect.human_type(page, search, demo_text)
                        await anti_detect.human_delay_short()
                    video.step("正在等待人工验证（如有）")
                    if not await wait_for_captcha_pass(
                        page,
                        timeout_sec=config.get_int("HUMAN_WAIT_TIMEOUT", 180),
                    ):
                        shot = await artifacts.capture_failure(
                            page, data_dir, batch_id, "captcha"
                        )
                        if shot:
                            artifact_paths["captcha"] = shot
                        return ExampleResult(
                            ok=False,
                            serial_no=None,
                            error_msg=errors.ERR_CAPTCHA_NEED_HUMAN,
                            artifacts={**artifact_paths, **video.to_artifact_dict()},
                        )
                    video.step("演示任务完成")
                    await context.close()
            except Exception as exc:
                video.step("演示异常结束")
                return ExampleResult(
                    ok=False,
                    serial_no=None,
                    error_msg=str(exc),
                    artifacts={**artifact_paths, **video.to_artifact_dict()},
                )
        arts = {"mode": "sim_rpa", "url": url, **artifact_paths, **video.to_artifact_dict()}
        if video.output_video_path:
            arts["video_path"] = video.output_video_path
        return ExampleResult(
            ok=True,
            serial_no=f"SIM-{len(items)}",
            error_msg=None,
            artifacts=arts,
        )
--- a/scripts/service/example_browser_rpa.py
+++ b/scripts/service/example_browser_rpa.py
@@ -1,88 +0,0 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """浏览器 RPA 最小用法示例（复制到新 skill 后按需改）。
 演示标准流程：
 1. config.ensure_env_file 首次落盘 .env
 2. launch_persistent_browser 启动 stealth persistent context
 3. 拟人操作（mouse_wiggle / human_type / human_click）
 4. 验证码 HITL 等待
 5. 失败 capture_failure 截图
 运行（需系统 Chrome/Edge + playwright 包）：
    python scripts/service/example_browser_rpa.py
 """
 from __future__ import annotations
 import asyncio
 import os
 import sys
 _scripts_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if _scripts_dir not in sys.path:
    sys.path.insert(0, _scripts_dir)
 from jiangchang_skill_core import config
 from jiangchang_skill_core.rpa import (
    anti_detect,
    artifacts,
    errors,
    launch_persistent_browser,
    wait_for_captcha_pass,
 )
 from util.constants import SKILL_SLUG
 from util.runtime_paths import get_skill_data_dir, get_skill_root
 async def demo() -> int:
    example_path = os.path.join(get_skill_root(), ".env.example")
    config.ensure_env_file(SKILL_SLUG, example_path)
    url = config.get("TARGET_BASE_URL") or "https://example.com"
    data_dir = get_skill_data_dir()
    profile_dir = os.path.join(data_dir, "browser-profile")
    os.makedirs(profile_dir, exist_ok=True)
    batch_id = "demo"
    try:
        from playwright.async_api import async_playwright
    except ImportError:
        print("ERROR: playwright not installed")
        return 1
    async with async_playwright() as pw:
        context = await launch_persistent_browser(
            pw,
            profile_dir=profile_dir,
            headless=config.get_bool("OPENCLAW_BROWSER_HEADLESS"),
        )
        page = context.pages[0] if context.pages else await context.new_page()
        try:
            await page.goto(url, wait_until="domcontentloaded", timeout=60_000)
            await anti_detect.human_mouse_wiggle(page)
            search = page.locator('input[type="search"], input[name="q"]').first
            if await search.count() > 0:
                await anti_detect.human_type(page, search, "openclaw-rpa-demo")
                await anti_detect.human_click(page, selector='input[type="search"]')
            if not await wait_for_captcha_pass(
                page,
                timeout_sec=config.get_int("HUMAN_WAIT_TIMEOUT", 180),
            ):
                shot = await artifacts.capture_failure(page, data_dir, batch_id, "captcha")
                print(errors.ERR_CAPTCHA_NEED_HUMAN, shot or "")
                return 1
            print("OK browser RPA demo finished")
            return 0
        except Exception as exc:
            shot = await artifacts.capture_failure(page, data_dir, batch_id, "error")
            print(f"ERROR: {exc}", shot or "")
            return 1
        finally:
            await context.close()
 if __name__ == "__main__":
    raise SystemExit(asyncio.run(demo()))
--- a/tests/test_docs_standards.py
+++ b/tests/test_docs_standards.py
@@ -4,17 +4,157 @@ from __future__ import annotations
 import configparser
 import os
 import re
 import unittest
 from _support import get_skill_root
 FORBIDDEN_README_DESCRIPTION_TERMS_EN = (
    "cli",
    "schema",
    "references",
    "development",
    "playwright",
    "python",
    "dom",
    "rpa",
 )
 FORBIDDEN_README_DESCRIPTION_TERMS_ZH = (
    "Agent 参考索引",
    "契约",
    "数据结构",
    "开发规范",
 )
 def _description_has_forbidden_term(description: str) -> str | None:
    lowered = description.lower()
    for term in FORBIDDEN_README_DESCRIPTION_TERMS_EN:
        if term in lowered:
            return term
    for term in FORBIDDEN_README_DESCRIPTION_TERMS_ZH:
        if term in description:
            return term
    return None
 def _extract_workflow_uses_line(text: str) -> str | None:
    for line in text.splitlines():
        stripped = line.strip()
        if stripped.startswith("uses:"):
            return stripped
    return None
 class TestDocsStandards(unittest.TestCase):
    def _read(self, rel_path: str) -> str:
        path = os.path.join(get_skill_root(), rel_path)
        with open(path, encoding="utf-8") as f:
            return f.read()
    def _parse_frontmatter(self, text: str) -> str:
        parts = text.split("---", 2)
        if len(parts) < 2:
            return ""
        return parts[1]
    def test_root_readme_has_yaml_frontmatter(self) -> None:
        text = self._read("README.md")
        self.assertTrue(text.startswith("---"), "README.md must start with YAML frontmatter")
        parts = text.split("---", 2)
        self.assertGreaterEqual(len(parts), 3, "README.md frontmatter must be closed")
    def test_root_readme_frontmatter_has_description(self) -> None:
        frontmatter = self._parse_frontmatter(self._read("README.md"))
        self.assertIn("description:", frontmatter, "README.md frontmatter must include description")
    def test_root_readme_description_avoids_technical_index_terms(self) -> None:
        frontmatter = self._parse_frontmatter(self._read("README.md"))
        match = re.search(r"description:\s*(.+)", frontmatter)
        self.assertIsNotNone(match, "README.md description field not found")
        description = match.group(1).strip().strip("\"'")
        forbidden = _description_has_forbidden_term(description)
        self.assertIsNone(
            forbidden,
            msg=f"README.md description must not contain technical index term {forbidden!r}",
        )
    def test_description_forbidden_terms_are_case_insensitive_for_english(self) -> None:
        fail_cases = (
            "CLI 契约说明",
            "cli 工具入口",
            "SCHEMA 定义",
            "Schema 映射",
            "schema 字段",
            "Playwright 自动化",
            "python 脚本",
            "RPA 流程",
        )
        pass_cases = (
            "用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。",
            "帮你自动整理订单并生成处理报告",
            "适合每天需要重复核对的业务场景",
        )
        for description in fail_cases:
            with self.subTest(description=description):
                self.assertIsNotNone(
                    _description_has_forbidden_term(description),
                    msg=f"expected forbidden term in {description!r}",
                )
        for description in pass_cases:
            with self.subTest(description=description):
                self.assertIsNone(
                    _description_has_forbidden_term(description),
                    msg=f"expected no forbidden term in {description!r}",
                )
    def test_references_readme_has_no_yaml_frontmatter(self) -> None:
        text = self._read("references/README.md")
        self.assertFalse(
            text.lstrip().startswith("---"),
            "references/README.md must not contain YAML frontmatter",
        )
    def test_references_readme_has_no_description_field(self) -> None:
        text = self._read("references/README.md")
        self.assertNotRegex(
            text,
            r"(?m)^description\s*:",
            msg="references/README.md must not contain description field",
        )
    def test_skill_md_requires_read_readme_first_rule(self) -> None:
        text = self._read("SKILL.md")
        self.assertIn("README.md", text)
        self.assertTrue(
            "优先读取" in text or "优先读" in text,
            msg="SKILL.md must require reading README.md first for user-facing questions",
        )
    def test_skill_md_states_readme_is_for_users(self) -> None:
        text = self._read("SKILL.md")
        self.assertIn("README.md", text)
        self.assertTrue(
            any(marker in text for marker in ("面向用户", "普通用户", "用户市场")),
            msg="SKILL.md must state README.md is user-facing documentation",
        )
    def test_release_workflow_uses_main_channel(self) -> None:
        text = self._read(".github/workflows/release_skill.yaml")
        uses_line = _extract_workflow_uses_line(text)
        self.assertIsNotNone(uses_line, "release_skill.yaml must contain a uses: line")
        self.assertIn(
            "client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml",
            uses_line,
        )
        self.assertRegex(
            uses_line,
            r"reusable-release-skill\.yaml@main\b",
            msg="workflow uses must reference reusable-release-skill.yaml@main",
        )
    def test_rpa_md_covers_video_and_playwright_standards(self) -> None:
        text = self._read("development/RPA.md")
        self.assertIn("title", text)
@@ -64,6 +204,127 @@ class TestDocsStandards(unittest.TestCase):
                msg=f"{rel} still claims 1.0.11 as current minimum",
            )
    def test_scripts_has_no_legacy_example_artifacts(self) -> None:
        scripts_dir = os.path.join(get_skill_root(), "scripts")
        service_dir = os.path.join(scripts_dir, "service")
        self.assertFalse(
            os.path.isfile(os.path.join(service_dir, "example_browser_rpa.py")),
            "scripts/service/example_browser_rpa.py must not exist",
        )
        self.assertFalse(
            os.path.isdir(os.path.join(service_dir, "example_adapter")),
            "scripts/service/example_adapter/ must not exist",
        )
    def test_gitignore_covers_python_runtime_artifacts(self) -> None:
        text = self._read(".gitignore")
        self.assertIn("__pycache__", text)
        self.assertIn(".pytest_cache", text)
        self.assertTrue(
            "py[cod]" in text or ".pyc" in text,
            msg=".gitignore must ignore Python bytecode (e.g. *.py[cod])",
        )
    def test_scripts_runtime_artifacts_not_tracked_by_git(self) -> None:
        import subprocess
        try:
            out = subprocess.run(
                ["git", "ls-files", "scripts"],
                cwd=get_skill_root(),
                capture_output=True,
                text=True,
                check=True,
            )
        except (FileNotFoundError, subprocess.CalledProcessError):
            self.skipTest("git not available or not a git repo")
        tracked = out.stdout.splitlines()
        for rel in tracked:
            lowered = rel.replace("\\", "/").lower()
            self.assertNotIn("__pycache__", lowered, msg=f"tracked cache path: {rel}")
            self.assertNotIn(".pytest_cache", lowered, msg=f"tracked cache path: {rel}")
            self.assertFalse(lowered.endswith(".pyc"), msg=f"tracked .pyc file: {rel}")
    def test_examples_top_level_modes_present(self) -> None:
        examples_dir = os.path.join(get_skill_root(), "examples")
        for mode in ("real_api", "real_browser_rpa", "simulator_api", "simulator_browser_rpa"):
            self.assertTrue(
                os.path.isdir(os.path.join(examples_dir, mode)),
                msg=f"examples/{mode}/ must exist",
            )
    def test_examples_are_not_full_skill_repos(self) -> None:
        examples_dir = os.path.join(get_skill_root(), "examples")
        for mode in os.listdir(examples_dir):
            mode_path = os.path.join(examples_dir, mode)
            if not os.path.isdir(mode_path):
                continue
            self.assertFalse(
                os.path.isfile(os.path.join(mode_path, "SKILL.md")),
                msg=f"examples/{mode}/SKILL.md must not exist",
            )
            self.assertFalse(
                os.path.isdir(os.path.join(mode_path, "references")),
                msg=f"examples/{mode}/references/ must not exist",
            )
            self.assertFalse(
                os.path.isdir(os.path.join(mode_path, "development")),
                msg=f"examples/{mode}/development/ must not exist",
            )
            self.assertFalse(
                os.path.isdir(os.path.join(mode_path, ".github")),
                msg=f"examples/{mode}/.github/ must not exist",
            )
    def test_examples_readme_states_copy_boundary(self) -> None:
        text = self._read("examples/README.md")
        self.assertIn("不是完整 skill 仓库", text)
        self.assertIn("核心实现案例", text)
        self.assertTrue(
            "不要整包照搬" in text or "不要整包" in text,
            msg="examples/README.md must warn against copying whole example tree",
        )
        self.assertTrue(
            "scripts" in text and ("复制" in text or "copy map" in text.lower()),
            msg="examples/README.md must describe copying into scripts/",
        )
    def test_placeholder_api_examples_are_not_implementation_references(self) -> None:
        for rel in ("examples/real_api/README.md", "examples/simulator_api/README.md"):
            text = self._read(rel)
            self.assertTrue(
                "占位" in text or "规划" in text,
                msg=f"{rel} must state placeholder/planned status",
            )
            self.assertTrue(
                "尚未沉淀" in text or "不可作为实现参考" in text or "不可" in text,
                msg=f"{rel} must warn not to use as implementation reference",
            )
    def test_docs_do_not_reference_scripts_legacy_examples(self) -> None:
        forbidden_fragments = (
            "scripts/service/example_browser_rpa",
            "scripts/service/example_adapter",
            "example_browser_rpa.py",
            "example_adapter/",
        )
        doc_paths = []
        for root, _dirs, files in os.walk(get_skill_root()):
            rel_root = os.path.relpath(root, get_skill_root())
            if rel_root.startswith(".git"):
                continue
            for name in files:
                if name.endswith(".md"):
                    doc_paths.append(os.path.join(rel_root, name).replace("\\", "/"))
        for rel in doc_paths:
            text = self._read(rel)
            for fragment in forbidden_fragments:
                self.assertNotIn(
                    fragment,
                    text,
                    msg=f"{rel} must not reference legacy scripts example path {fragment!r}",
                )
 class TestPytestIniCollection(unittest.TestCase):
    def test_pytest_ini_exists_and_limits_python_files(self) -> None:
--- a/tests/test_release_packaging_constraints.py
+++ b/tests/test_release_packaging_constraints.py
@@ -0,0 +1,165 @@
 # -*- coding: utf-8 -*-
 """发布打包守护：PyArmor 单文件行数与 UTF-8 without BOM。"""
 from __future__ import annotations
 import os
 import unittest
 from _support import get_skill_root
 SCRIPTS_MAX_LINES = 1000
 SCRIPTS_RECOMMENDED_MAX_LINES = 900
 TEXT_EXTENSIONS = frozenset(
    {
        ".py",
        ".md",
        ".yml",
        ".yaml",
        ".json",
        ".toml",
        ".ini",
        ".txt",
        ".ps1",
        ".sh",
    }
 )
 SPECIAL_TEXT_FILES = frozenset({".env.example", ".gitignore"})
 SKIP_DIR_NAMES = frozenset(
    {
        ".git",
        "__pycache__",
        ".pytest_cache",
        "rpa-artifacts",
        "videos",
    }
 )
 BINARY_EXTENSIONS = frozenset(
    {
        ".db",
        ".sqlite",
        ".png",
        ".jpg",
        ".jpeg",
        ".gif",
        ".webp",
        ".mp4",
        ".zip",
        ".tar",
        ".gz",
    }
 )
 def _is_text_candidate(path: str) -> bool:
    basename = os.path.basename(path)
    if basename in SPECIAL_TEXT_FILES:
        return True
    ext = os.path.splitext(basename)[1].lower()
    if ext in BINARY_EXTENSIONS:
        return False
    return ext in TEXT_EXTENSIONS
 def _iter_text_files(skill_root: str) -> list[str]:
    found: list[str] = []
    for root, dirnames, filenames in os.walk(skill_root):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIR_NAMES]
        for name in filenames:
            full = os.path.join(root, name)
            if _is_text_candidate(full):
                found.append(full)
    return sorted(found)
 def _iter_scripts_py_files(skill_root: str) -> list[str]:
    scripts_dir = os.path.join(skill_root, "scripts")
    found: list[str] = []
    if not os.path.isdir(scripts_dir):
        return found
    for root, dirnames, filenames in os.walk(scripts_dir):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIR_NAMES]
        for name in filenames:
            if name.endswith(".py"):
                found.append(os.path.join(root, name))
    return sorted(found)
 class TestReleasePackagingConstraints(unittest.TestCase):
    def test_scripts_py_files_under_pyarmor_line_limit(self) -> None:
        skill_root = get_skill_root()
        offenders: list[str] = []
        for path in _iter_scripts_py_files(skill_root):
            with open(path, encoding="utf-8") as f:
                line_count = sum(1 for _ in f)
            if line_count >= SCRIPTS_MAX_LINES:
                rel = os.path.relpath(path, skill_root).replace("\\", "/")
                offenders.append(
                    f"{rel}: {line_count} lines (limit < {SCRIPTS_MAX_LINES})"
                )
        self.assertEqual(
            offenders,
            [],
            msg=(
                "PyArmor trial/free mode may fail when a single Python file reaches "
                f"{SCRIPTS_MAX_LINES} lines; split this file into smaller modules. "
                f"Recommended keep each file < {SCRIPTS_RECOMMENDED_MAX_LINES} lines. "
                f"Offenders: {offenders}"
            ),
        )
    def test_text_files_are_utf8_without_bom(self) -> None:
        skill_root = get_skill_root()
        bom_failures: list[str] = []
        decode_failures: list[str] = []
        feff_failures: list[str] = []
        for path in _iter_text_files(skill_root):
            rel = os.path.relpath(path, skill_root).replace("\\", "/")
            with open(path, "rb") as f:
                raw = f.read()
            if raw.startswith(b"\xef\xbb\xbf"):
                bom_failures.append(rel)
                continue
            try:
                text = raw.decode("utf-8")
            except UnicodeDecodeError as exc:
                decode_failures.append(f"{rel}: {exc}")
                continue
            if "\ufeff" in text:
                feff_failures.append(rel)
        self.assertEqual(
            bom_failures,
            [],
            msg=(
                "Files must be saved as UTF-8 without BOM (remove UTF-8 BOM prefix). "
                f"Offenders: {bom_failures}"
            ),
        )
        self.assertEqual(
            decode_failures,
            [],
            msg=(
                "Files must be valid UTF-8 without BOM. "
                f"Offenders: {decode_failures}"
            ),
        )
        self.assertEqual(
            feff_failures,
            [],
            msg=(
                "Files must not contain U+FEFF; save as UTF-8 without BOM. "
                f"Offenders: {feff_failures}"
            ),
        )
 if __name__ == "__main__":
    unittest.main()
Author	SHA1	Message	Date
chendelian	30803a0834	chore: auto release commit (2026-06-21 10:51:04) All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-06-21 10:51:05 +08:00
chendelian	f3f7a9b9e5	chore: auto release commit (2026-06-17 09:48:59) All checks were successful 技能自动化发布 / release (push) Successful in 5s Details	2026-06-17 09:49:00 +08:00
chendelian	79098dad5c	chore: auto release commit (2026-06-17 09:21:19) All checks were successful 技能自动化发布 / release (push) Successful in 6s Details	2026-06-17 09:21:21 +08:00