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/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`）