> 目标：新增 `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 返回空、指令超限、元素不存在等），确保有明确错误日志。