skill-template/development/AI_RPA.md

AI + RPA 技能开发总纲

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

目录

1. 一句话定义
2. 职责边界
3. 标准执行闭环
4. 合规与技术红线
5. 工业级 RPA 风控
6. 等待与操作节奏
7. 三端统一与选型
8. 结果契约
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. 标准执行闭环

用户自然语言
  → 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 §0.3 / §4。

操作节奏

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

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 已有可复制案例；桌面与手机仍须基于真实项目继续沉淀，未验证内容不得包装为成熟方案。

8. 结果契约

RPA 至少返回：

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

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