feat(ai): 添加 AI 动作支持,集成 OpenAI GPT-4o 驱动自动化流程

- 新增 AIExecutor 类用于调用 OpenAI API 并解析结构化指令
- 在 Settings 中增加 OpenAI 相关配置项(API Key、模型、超时等)
- 扩展 ActionContext 以支持注入 AI 服务实例
- 实现 AIAction 类处理自然语言提示并执行 AI 规划的浏览器操作
- 支持通过 max_step 参数限制 AI 操作步数(默认5,最大20)
- 支持 include_html 和 include_variables 控制上下文内容传递
- 支持运行时覆盖模型和温度参数
- 增加详细的错误处理与日志记录机制- 更新 README 文档说明 AIAction 使用方法与配置选项
- 更新 XSD schema 支持 ai 类型动作定义- 在 FlowRunner 中完善步骤记录逻辑,支持 AI 执行结果输出
- 添加 plan_ai_action.md 设计文档描述实现细节与规划
This commit is contained in:
2025-10-21 21:38:46 +08:00
parent a1a13aae65
commit 85b7ea4f6c
11 changed files with 604 additions and 13 deletions

51
plan_ai_action.md Normal file
View File

@@ -0,0 +1,51 @@
> 目标:新增 `ai` 类型 Action使其能够根据自定义 prompt 调用 OpenAI 的 `gpt-4o`,按步骤直接驱动 DrissionPage 原生 `Page`/元素方法,并支持 `max_step` 等参数。
## 一、需求分析与约束
1. 明确期望的交互:`ai` 动作接收 prompt结合当前页面状态HTML、URL、变量等生成操作指令。
2. 确定 DrissionPage 原生方法集合(如 `page.ele(...)`, `click`, `input`, `wait.ele`, `run_js`, `scroll` 等),并定义统一的指令格式(动作名称、参数列表)。
3. 确认 OpenAI `gpt-4o` 接口调用方式REST API需要在设置中提供 `OPENAI_API_KEY` 等凭证,并确认网络访问策略(若受限需用户预先允许)。
## 二、ActionConfig 设计
1. 在 Schema / README 中补充 `ai` 行,定义可用参数:
- `params.prompt`:必填,自然语言描述的目标。
- `params.max_step`:可选,限制生成的操作步骤数量,默认值如 5。
- `params.model`:默认 `gpt-4o`,允许覆盖。
- `params.temperature``params.top_p` 等生成参数(可选)。
- `params.context_mode`:决定传递给模型的页面 HTML、变量、历史步骤范围。
2. 决定动作返回值(例如最后的操作总结或 AI 返回的原始响应),并写入日志步骤。
## 三、AI 执行器设计
1. 新增组件(如 `xspider/ai/executor.py`)封装:
- 组装系统提示+用户 prompt包含页面上下文、变量、执行限制、可用 DrissionPage API 列表)。
- 调用 OpenAI `gpt-4o` REST API使用 JSON 模式tool/response schema获取结构化指令。
- 校验 AI 返回值并转换为内部步骤列表(确保动作类型/参数合法)。
2. 定义步骤数据结构Action 指令列表),包括动作类型、定位参数(选择器/方式或直接传递 JS、输入值等。
3. 设计错误处理机制:解析失败、指令无效时的重试 / 回退策略。
## 四、DrissionPage 操作适配
1. 获取 `ActionContext.session.page`,直接调用 DrissionPage 原生方法(避免经过 `BrowserSession` 包装),必要时提供辅助函数简化重复逻辑。
2. 根据步骤类型调用对应的原生方法(`page.ele(...)`, `ele.click(...)`, `ele.input(...)`, `page.wait.ele(...)`, `page.run_js(...)` 等),执行前后记录步骤状态。
3. 若出现异常(元素不存在、方法报错),决定是立即终止、尝试下一步,或把错误反馈给 AI 进行下一轮迭代。
## 五、Action 实现
1.`xspider/actions` 中新增 `ai.py` 或直接扩展 `builtin.py`
- 创建 `AIAction(BaseAction)`,在 `_execute` 中初始化 AI 执行器、构建上下文、驱动步骤执行。
- 支持 `max_step` 限制,记录已执行步骤数量。
- 将执行结果附加到 `ActionContext.site_context`(必要时),供后续动作使用。
2.`ActionRegistry` 中注册 `ai`
3. 处理变量解析:允许 prompt、模型名等字段使用 `${...}` 占位符。
## 六、日志与调试
1. 扩展任务日志步骤记录:在 FlowRunner 中对 `ai` 动作追加详细信息AI prompt、返回指令、执行情况
- 注意隐私 / 成本:可只记录摘要或取前 N 个字符。
2. 提供调试标志(如 `params.debug=true`),决定是否保存原始 AI 响应。
## 七、配置与依赖
1.`Settings` 中新增 AI 服务相关配置(如 API URL、密钥、默认模型
2. 更新 README / Schema说明 `ai` 动作参数、OpenAI API Key 配置、`max_step` 行为及注意事项。
3. 如需第三方 SDK在依赖列表中追加或留空供用户自备
## 八、测试与验证
1. 编写单元测试:模拟 AI 服务返回固定指令,验证解析与执行流程。
2. 提供集成测试脚本(可打桩 AI 响应),检查与 DrissionPage 的联动。
3. 手动验证异常路径AI 返回空、指令超限、元素不存在等),确保有明确错误日志。