chore: auto release commit (2026-06-17 09:21:19)

2026-06-17 09:21:21 +08:00
parent b267ca3266
commit 79098dad5c
20 changed files with 472 additions and 359 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: admin/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 页面 + 测试
+- **仿真浏览器 RPA 完整案例**：`examples/simulator_browser_rpa/` — mock + simulator_rpa + sandbox 页面 + adapter 分层 + 测试
 - **真实浏览器 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. **从模板复制骨架**：
-   - `scripts/service/example_adapter/` → 改名为 `scripts/service/<domain>_adapter/`（仅 adapter 四档骨架，**不等同于**真实浏览器 RPA 成功案例）
-   - 若是 **真实浏览器 RPA**（真实网站、登录态、验证码、滚动采集），**必须先读** `examples/real_browser_rpa/README.md`，再按需参考：
+2. **从 examples 选择性复制**（不要整包照搬 `examples/<mode>/`，见各 example README 的 copy map）：
+   - 若是 **真实浏览器 RPA**（真实网站、登录态、验证码、滚动采集），**必须先读** `examples/real_browser_rpa/README.md`，再按需复制到 `scripts/service/`：
     - `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
@@ -343,7 +342,7 @@ metadata:

 **`references/`**（Agent 运行/编排/调用时渐进加载）

- `README.md` — Agent 参考索引
+- `README.md` — Agent 参考索引（**不是**市场说明；不得含 YAML frontmatter 或 `description`）
 - `CLI.md` — 命令、参数、默认值、兄弟技能调用方式
 - `SCHEMA.md` — 数据库路径、核心表结构、日志表结构
 - 可按需增加 `ERRORS.md`、`INTEGRATION.md` 等编排向补充
@@ -529,6 +528,20 @@ python scripts/main.py <your-command>

 ## 15. 发布到正式环境验证

+### release workflow 通道
+
+`.github/workflows/release_skill.yaml` 默认引用：
+
+```yaml
+uses: admin/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 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。
--- 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` 时，可手动执行：
-
-```bash
-pip install playwright   # 仅独立开发补装；用系统 Chrome，无需 playwright install chromium
-```
+页面启动仍遵循 1.2：`launch_persistent_context` 的 `args` 只能放 Chrome 启动参数，**不能把 URL 塞进 `args`**；打开页面必须通过 `new_page()` + `goto()`，或通过真实地址栏/点击进入。

 ### 引用方式

@@ -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/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 | **已有案例** | 真实第三方网站、登录态、人工验证、滚动采集 |
-| simulator_browser_rpa | 仿真浏览器 RPA | **已有案例** | 自有 sandbox、可控页面、表单 RPA、端到端教学/回归 |
-| real_api | 真实 API | 占位，后续补案例 | 真实系统接口、token、权限、限流 |
-| simulator_api | 仿真 API | 占位，后续补案例 | mock/sandbox API、无需浏览器 |
+| `real_browser_rpa` | 真实浏览器 RPA | **已有案例** | 真实第三方网站、登录态、人工验证、滚动采集 |
+| `simulator_browser_rpa` | 仿真浏览器 RPA | **已有案例** | 自有 sandbox、可控页面、表单 RPA、adapter 分层 |
+| `real_api` | 真实 API | **占位** | 真实系统接口、token、权限、限流（尚未沉淀可复制实现） |
+| `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** |
-| mock / sandbox API（无浏览器） | 后续 **simulator_api** |
+| 真实系统 API | **real_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`（本节及下方「复制边界」）
-2. 复制整个 `examples/real_browser_rpa/` 到新 skill 的 `scripts/` 结构（或作为起点合并）
+1. **先阅读**本 README 及下方「Copy map」「复制边界」章节
+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/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(
+            "admin/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: