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