Flik
85b7ea4f6c
- 新增 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 设计文档描述实现细节与规划
52 lines
3.9 KiB
Markdown
52 lines
3.9 KiB
Markdown
> 目标：新增 `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 返回空、指令超限、元素不存在等），确保有明确错误日志。
|