# AI + RPA 技能开发总纲

本文是技术人员与 AI 编程工具进入本模板后的**第一份架构说明**。先理解本文，再按业务类型阅读 [`RPA.md`](RPA.md)、[`ADAPTER.md`](ADAPTER.md)、[`SKILL_ACTION_RUNTIME.md`](SKILL_ACTION_RUNTIME.md) 与对应 `examples/`。

## 目录

1. [一句话定义](#1-一句话定义)
2. [职责边界](#2-职责边界)
3. [标准执行闭环](#3-标准执行闭环)
4. [合规与技术红线](#4-合规与技术红线)
5. [工业级 RPA 风控](#5-工业级-rpa-风控)
6. [等待与操作节奏](#6-等待与操作节奏)
7. [三端统一与选型](#7-三端统一与选型)
8. [结果契约](#8-结果契约)
9. [开发与交付顺序](#9-开发与交付顺序)

## 1. 一句话定义

**AI Agent 是用户入口与业务编排者，RPA 是确定性执行器。**

- Agent 负责理解用户意图、补齐参数、判断风险、选择 Action、发起任务和解释结果。
- RPA 负责按已验证的步骤操作浏览器、桌面软件或手机，不临时理解模糊业务。
- 业务规则放在唯一 domain service 中；Agent、CLI、Action、定时任务与数据管理入口复用同一内核。
- RPA 必须返回结构化结果、进度与存证，由 Agent 用业务语言反馈给用户。

本模板追求的是**稳定、合规、可控制、可追溯、可交付的工业级界面自动化**，不是与第三方安全机制对抗。

## 2. 职责边界

| 层级 | 负责 | 不负责 |
|------|------|--------|
| Agent | 意图理解、缺参追问、风险确认、Action 选择、结果解释 | 不猜界面步骤，不临时改业务规则，不直接绕过安全验证 |
| Action / 编排层 | 参数校验、鉴权、任务状态、进度、暂停停止、日志、人工介入 | 不按入口复制业务逻辑 |
| Domain Service | 业务规则、幂等、防重复、状态流转、结果汇总 | 不关心来自 Agent、定时任务还是工具栏 |
| Adapter / RPA | 调官方 API 或按确定流程操作界面 | 不理解模糊意图，不自行扩大权限或操作范围 |
| 宿主 | Action 展示、任务中心、数据管理、共享 runtime | 不替技能实现业务规则 |

Agent 与 RPA 的边界必须保持清晰：

- 把不确定的理解与沟通交给 Agent。
- 把可验证、可重复的执行步骤交给代码和 RPA。
- 不让 Agent 在运行时自由生成高风险界面操作。
- 不让 RPA 根据模糊文本自行决定付款、删除、审批、发布或发送范围。

## 3. 标准执行闭环

```text
用户自然语言
  → Agent 识别意图与参数
  → 缺参追问 / 风险确认
  → 选择已声明的 Skill Action
  → 编排层做校验、鉴权、预检、幂等检查
  → Domain Service 执行业务规则
  → Adapter 选择 API / 浏览器 / 桌面 / 手机
  → RPA 分步骤执行并持续上报进度
  → 验证码、人脸、U盾等转人工处理
  → 返回结构化结果、日志、截图与可选视频
  → Agent 向用户解释结果与下一步
```

### 执行前

Agent 与编排层必须确认：

- 用户意图、操作对象、范围与必填参数明确。
- 当前账号、数据、设备和目标软件属于用户或企业授权范围。
- 查询、准备数据与外部副作用已经分开。
- 付款、删除、审批、发布、发送等不可逆动作已取得明确确认。
- 浏览器 Profile、桌面窗口或手机设备已通过预检。
- 同一业务键不会被重复提交。

### 执行中

- 每个用户可感知的动作都要有中文进度 step。
- 使用可暂停、可停止的等待；禁止 RPA 主路径裸 `asyncio.sleep`。
- 同一账号、Profile 或设备默认串行执行。
- 遇到安全验证、权限不足、频控或风险提示时，转人工或安全停止。
- 批量任务记录处理位置，支持失败定位和必要的断点续跑。

### 执行后

- 先验证业务成功标志，再记录成功；不得把“点击完成”当成“业务成功”。
- 返回成功、部分成功、失败、停止或等待人工等明确状态。
- 保存必要的任务日志、错误码、失败截图和可选录屏。
- Agent 根据结构化结果解释完成数量、失败原因和下一步，不直接粘贴技术日志。

## 4. 合规与技术红线

### 允许

- 使用用户或企业合法拥有、明确授权的账号与业务权限。
- 通过正常界面入口完成用户本来有权完成的操作。
- 使用浏览器 DOM、Windows UI Automation、Android/iOS 控件树等公开自动化能力。
- 采用真实点击、逐字输入、自然鼠标轨迹、分段滚动和合理业务节奏。
- 遇到验证码、人脸、指纹、短信、U盾或动态口令时暂停并请求人工处理。
- 在授权范围内保存必要的日志、截图、视频和业务结果。

### 禁止

- 破解、反编译、逆向第三方软件或分析其私有协议。
- 调用未经公开授权的隐藏接口，或通过抓包拼装私有请求代替正常界面。
- 绕过登录、验证码、人脸、指纹、短信、U盾、设备绑定、签名或权限校验。
- 注入、Hook、篡改第三方进程、客户端、APK、IPA、安全模块或通信内容。
- 窃取、共享或复用未授权的 Cookie、Token、Session、密码或设备凭据。
- 撞库、暴力尝试、自动破解验证码、批量养号或伪造身份。
- 通过换账号、换代理、伪造设备指纹、提高并发等方式规避平台限制。
- 识别到风险提示或封禁后继续自动重试、试探或隐藏自动化行为。

“采用 RPA”不代表任何任务都可以自动执行。技能仍须遵守账号授权、数据权限、目标平台规则、合同约定和适用法律；边界不清时停止并请求负责人确认。

## 5. 工业级 RPA 风控

### 风控信号与处理

| 信号 | 标准处理 |
|------|----------|
| 页面或软件加载缓慢 | 等待真实状态，必要时有限重试 |
| 普通网络错误 | 递增退避后有限重试 |
| 登录失效 | 请求用户重新登录 |
| 验证码、短信、人脸、指纹、U盾 | 进入人工处理，禁止自动绕过 |
| 频率限制 | 停止当前批次或长时间退避 |
| 账号风险、封禁或安全警告 | 立即停止，禁止自动换号或继续试探 |
| 权限不足 | 返回明确失败，不尝试扩大或绕过权限 |
| 页面或控件结构变化 | 截图并停止，交由开发人员重新验证 |
| 提交结果不明确 | 查询业务状态；确认前禁止再次提交 |

### 运行限制

- 同一账号、Profile、桌面会话或手机设备默认只运行一个任务。
- 设置单批数量、单位时间操作量和总运行时长上限。
- 只对明确可重试错误做有限重试；禁止无限循环。
- 采用递增退避，不以快速重复点击或刷新解决延迟。
- 关键副作用采用“准备数据 → 用户确认 → 执行 → 结果核验”两阶段流程。
- 风控策略用于减少误操作、系统压力和误判，不得用于规避第三方安全控制。

## 6. 等待与操作节奏

区分三类等待，禁止只靠固定睡眠碰运气。

### 状态等待

页面加载、控件可用、弹窗消失、保存成功、下载完成等必须等待**真实条件**并设置超时。固定等待不能代替状态判断。

自 **platform-kit 1.2.11** / 本模板 **1.0.78** 起：

- 统一使用 `jiangchang_skill_core.rpa.poll_until`（或 `poll_until_sync`），内部已接 `interruptible_sleep`。
- 先有界等待就绪，再区分「加载慢」与「页不对」；超时优先 `ERROR:UI_NOT_READY`。
- 不要把慢机器症状映射成配置错误、网络错误或频控，除非有明确证据。
- 详细表与纪律见 [`RPA.md`](RPA.md) §0.3 / §4。

### 操作节奏

真实业务环境中，两个正常业务动作之间默认随机等待 **1～3 秒**：

```env
STEP_DELAY_MIN=1.0
STEP_DELAY_MAX=3.0
```

- 输入采用逐字符随机延迟。
- 鼠标采用自然移动轨迹与小幅随机偏移。
- 滚动采用分段操作。
- 提交后等待业务结果，禁止重复点击。
- 测试 / sandbox 可使用更短节奏，但不得把测试节奏用于真实第三方系统。

### 前后缓冲

- 浏览器或软件启动：先等待会话与目标页面/窗口真实就绪，再额外缓冲约 `1.5～2.5` 秒。
- 页面导航：关键控件就绪后，再缓冲约 `1～2` 秒。
- 普通流程结束：确认业务结果、写日志与存证后，再缓冲约 `2～3` 秒关闭。
- 付款、审批、发布等重要动作：确认结果并截图后，可缓冲约 `3～5` 秒。

缓冲时间只用于稳定界面和改善用户观感，不能作为成功判定。RPA 等待必须使用 `interruptible_sleep` 或共享可控制原语。

## 7. 三端统一与选型

优先选择最稳定、最受支持的执行方式：

1. 本地确定性逻辑可以完成时，不启动 RPA。
2. 有稳定且获得授权的官方 API 时，优先 API。
3. 只能通过网页操作时，使用浏览器 RPA。
4. 目标为 Windows 原生软件时，优先 UI Automation。
5. 目标为手机 App 时，使用系统控件树与正常设备自动化。
6. 只有破解、逆向或绕过安全机制才能完成时，停止开发并上报，不改走违规路线。

三端详细标准见 [`RPA.md`](RPA.md)。当前浏览器 RPA 已有可复制案例；桌面与手机仍须基于真实项目继续沉淀，未验证内容不得包装为成熟方案。

## 8. 结果契约

RPA 至少返回：

```json
{
  "success": true,
  "status": "success",
  "message": "任务已完成",
  "summary": {
    "total": 10,
    "success_count": 9,
    "failed_count": 1
  },
  "items": [],
  "errors": [],
  "artifacts": {
    "screenshots": [],
    "video_path": null
  },
  "next_actions": []
}
```

状态至少能区分：

- `success`：全部完成。
- `partial`：部分成功，列出失败项。
- `failed`：未完成，给出稳定错误码与阶段。
- `waiting_human`：等待人工验证或接管，不是假失败。
- `confirmation_required`：等待用户批准副作用。
- `stopped`：用户或宿主主动停止。

具体字段可按业务扩展，但不得只返回控制台文本或把技术 traceback 直接交给用户。

## 9. 开发与交付顺序

1. 填写 [`REQUIREMENTS.md`](REQUIREMENTS.md) 中的 Agent、授权、风险、人工介入与结果设计。
2. 判断采用 API、浏览器、桌面或手机，并选择真实 / 仿真 adapter。
3. 定义用户意图、Action、输入 schema 与确认策略。
4. 先实现 domain service、结构化结果和 mock 测试。
5. 再实现 RPA 会话、真实操作、状态等待、进度、截图与人工介入。
6. 在真实界面上确认 selector / 控件，禁止凭经验猜测。
7. 完成仿真测试、真实业务闭环和宿主多入口验收。
8. 使用 [`CHECKLIST.md`](CHECKLIST.md) 做第三方交活验收。

AI 编程工具不得为了“跑通”擅自采用破解、逆向、私有协议、验证码绕过、进程注入、无限重试或未授权凭据。正常界面无法完成闭环时，应停止并向负责人报告边界。