From 79098dad5c786973de7aa927cfe4cb09b8a76b13 Mon Sep 17 00:00:00 2001 From: chendelian <116870791@qq.com> Date: Wed, 17 Jun 2026 09:21:21 +0800 Subject: [PATCH] chore: auto release commit (2026-06-17 09:21:19) --- .github/workflows/release_skill.yaml | 2 +- README.md | 5 + SKILL.md | 19 ++ development/ADAPTER.md | 8 +- development/DEVELOPMENT.md | 25 +- development/RPA.md | 16 +- examples/README.md | 61 +++-- examples/real_api/README.md | 32 ++- examples/real_browser_rpa/README.md | 28 ++- examples/simulator_api/README.md | 32 ++- examples/simulator_browser_rpa/README.md | 23 ++ references/README.md | 8 +- scripts/service/example_adapter/__init__.py | 26 -- scripts/service/example_adapter/base.py | 37 --- scripts/service/example_adapter/mock.py | 24 -- scripts/service/example_adapter/real_api.py | 14 -- scripts/service/example_adapter/real_rpa.py | 14 -- scripts/service/example_adapter/sim_rpa.py | 108 -------- scripts/service/example_browser_rpa.py | 88 ------- tests/test_docs_standards.py | 261 ++++++++++++++++++++ 20 files changed, 472 insertions(+), 359 deletions(-) delete mode 100644 scripts/service/example_adapter/__init__.py delete mode 100644 scripts/service/example_adapter/base.py delete mode 100644 scripts/service/example_adapter/mock.py delete mode 100644 scripts/service/example_adapter/real_api.py delete mode 100644 scripts/service/example_adapter/real_rpa.py delete mode 100644 scripts/service/example_adapter/sim_rpa.py delete mode 100644 scripts/service/example_browser_rpa.py diff --git a/.github/workflows/release_skill.yaml b/.github/workflows/release_skill.yaml index c69786d..270c091 100644 --- 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: diff --git a/README.md b/README.md index b63741f..08b42c5 100644 --- 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 等作为面向用户的主说明内容；若业务上必须出现技术词，须用用户能理解的方式解释，且不能喧宾夺主。 + # 【技能名称】 > 用一两句话说明这个技能帮助用户完成什么工作。 diff --git a/SKILL.md b/SKILL.md index 85211e9..882cf8d 100644 --- 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 等实现细节，除非用户明确询问技术实现。 + ## 文档分工 | 文档 | 读者 | 用途 | diff --git a/development/ADAPTER.md b/development/ADAPTER.md index 28268c2..35f7cac 100644 --- a/development/ADAPTER.md +++ b/development/ADAPTER.md @@ -51,11 +51,13 @@ scripts/service/_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/_adapter/` 并按 README copy map 选择性复制。 > 先判断属于四象限哪一种（`real_browser_rpa` / `real_api` / `simulator_browser_rpa` / `simulator_api`），再读对应 `examples/*/README.md`。示例是**参考架构与边界**，不是业务代码原样复制。 diff --git a/development/DEVELOPMENT.md b/development/DEVELOPMENT.md index 62ab8e7..b9c94fe 100644 --- 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/_adapter/`（仅 adapter 四档骨架，**不等同于**真实浏览器 RPA 成功案例） - - 若是 **真实浏览器 RPA**（真实网站、登录态、验证码、滚动采集），**必须先读** `examples/real_browser_rpa/README.md`，再按需参考： +2. **从 examples 选择性复制**（不要整包照搬 `examples//`，见各 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 ## 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 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行，不要跳步。 diff --git a/development/RPA.md b/development/RPA.md index 7e84258..572bacc 100644 --- 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 示例（必读） diff --git a/examples/README.md b/examples/README.md index a1c052b..4970950 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,13 +1,21 @@ # Skill Template Examples -四类 adapter 示例（先选类型，再写代码；**不要跨类型照抄**）： +`examples/` 是面向**技术人员与 AI 编程工具**的**核心实现案例**目录：提供可运行、可测试、可复制的参考代码，用于指导新技能的 `scripts/` 应如何编写。 + +**`examples/` 不是完整 skill 仓库。** 不要整包照搬 `examples//` 到新技能根目录。应按各 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//` 推荐结构： + +```text +examples// + README.md + scripts/ + service/ + util/ + tests/ +``` + +- 仅 `simulator_browser_rpa` 可额外包含 `sandbox/` +- 仅未来确实需要样例数据时可加 `fixtures/` +- **不要**在 `examples//` 下要求或添加：`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 与「禁止照抄」章节。 diff --git a/examples/real_api/README.md b/examples/real_api/README.md index 33a94d2..7a82850 100644 --- 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/` 仍按模板主目录规则编写 +- 当前阶段：**不可作为实现参考** diff --git a/examples/real_browser_rpa/README.md b/examples/real_browser_rpa/README.md index 3a2754d..f0274b0 100644 --- 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()`，或通过真实地址栏/点击进入 ## 复制边界：哪些能复制，哪些必须替换 diff --git a/examples/simulator_api/README.md b/examples/simulator_api/README.md index bae6cd4..bf8fd6a 100644 --- 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/` 仍按模板主目录规则编写 +- 当前阶段：**不可作为实现参考** diff --git a/examples/simulator_browser_rpa/README.md b/examples/simulator_browser_rpa/README.md index df62a0b..f3fcb82 100644 --- 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/_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`） diff --git a/references/README.md b/references/README.md index e9458ad..2e17d8b 100644 --- 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/)。 | 文档 | 用途 | |------|------| diff --git a/scripts/service/example_adapter/__init__.py b/scripts/service/example_adapter/__init__.py deleted file mode 100644 index 5130826..0000000 --- a/scripts/service/example_adapter/__init__.py +++ /dev/null @@ -1,26 +0,0 @@ -"""示例 adapter 四档 dispatch。 - -由 ``OPENCLAW_TEST_TARGET``（或 ``config.get``）决定档位。 -复制本目录后把 ``example_adapter`` 改名为 ``_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() diff --git a/scripts/service/example_adapter/base.py b/scripts/service/example_adapter/base.py deleted file mode 100644 index 536d0d0..0000000 --- a/scripts/service/example_adapter/base.py +++ /dev/null @@ -1,37 +0,0 @@ -"""示例适配器数据契约与基类。 - -复制本目录为 ``_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 diff --git a/scripts/service/example_adapter/mock.py b/scripts/service/example_adapter/mock.py deleted file mode 100644 index b738a10..0000000 --- a/scripts/service/example_adapter/mock.py +++ /dev/null @@ -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)}, - ) diff --git a/scripts/service/example_adapter/real_api.py b/scripts/service/example_adapter/real_api.py deleted file mode 100644 index 001cca7..0000000 --- a/scripts/service/example_adapter/real_api.py +++ /dev/null @@ -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" - ) diff --git a/scripts/service/example_adapter/real_rpa.py b/scripts/service/example_adapter/real_rpa.py deleted file mode 100644 index aadc205..0000000 --- a/scripts/service/example_adapter/real_rpa.py +++ /dev/null @@ -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" - ) diff --git a/scripts/service/example_adapter/sim_rpa.py b/scripts/service/example_adapter/sim_rpa.py deleted file mode 100644 index f17fc33..0000000 --- a/scripts/service/example_adapter/sim_rpa.py +++ /dev/null @@ -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, - ) diff --git a/scripts/service/example_browser_rpa.py b/scripts/service/example_browser_rpa.py deleted file mode 100644 index 10eb7c3..0000000 --- a/scripts/service/example_browser_rpa.py +++ /dev/null @@ -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())) diff --git a/tests/test_docs_standards.py b/tests/test_docs_standards.py index afd5b4a..4e3c1ef 100644 --- 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: