浏览器自动化工具

剧作家机器人（Python）— 核心+人工智能/机器控制程序（MCP）

使用Playwright自动化浏览器以执行固定、单一的任务 lacity.gov（洛杉矶市政府网站） — 运行网站搜索（默认 "311"）并打印出第一个有机结果（标题和网址）。
包含一个可选的人工智能驱动代理，该代理能够动态规划步骤通过 MCP （模型上下文协议），具有安全回退到确定性核心流程的功能。

特点/特性

• 核心： 确定性Playwright自动化；强大选择器；重试机制；明确的最终结果。
• AI + MCP（可选）： 连接到本地的Playwright MCP服务器，从大型语言模型（LLM）请求一个结构化的JSON计划，执行该计划，并在计划无效时回退到核心辅助工具。
• 可靠性： 超时设置、重试机制、关闭cookie横幅、直接搜索回退、有头/无头模式切换。
• 安全性： 从环境变量中读取API密钥；切勿硬编码。

仓库布局

app/
  core_robot.py      - Core: deterministic search + console output
  mcp_agent.py       - Optional: AI/MCP agent with fallback to core helpers
  robot_utils.py     - Shared helpers: retries, selectors, result extraction
requirements.txt
.env.example          - Sample environment variables

先决条件

• Python 3.10及以上版本
• Node.js 18+（用于MCP服务器）

快速入门

1. 创建并激活虚拟环境

   复制

   python -m venv .venv
   source .venv/bin/activate
   

2. 安装依赖项

   复制

   pip install -r requirements.txt
   python -m playwright install chromium
   

3. （可选）启用有头模式

   复制

   export HEADFUL=1
   

运行核心（确定性）

python -m app.core_robot

示例输出：

[robot] goto homepage
[robot] search mode: ui
Success! Query='311' | First result: MyLA311 | City of Los Angeles | URL: https://lacity.gov/...

运行AI/MCP代理（可选）

1. 启动MCP服务器

   复制

   npx --yes @playwright/mcp@latest --port 11000
   

2. 设置环境变量并运行

   复制

   export OPENAI_API_KEY="..."          # Required for live AI planning
   export MCP_SERVER_URL="http://localhost:11000/sse"
   python -m app.mcp_agent
   

输出包括一个模式标志：

• "_mode": "ai_plan" 执行了大型语言模型（LLM）的计划
• "_mode": "fallback_core_ui" 或者 "_mode": "fallback_core_direct" → 使用了确定性辅助函数

获取OpenAI API密钥

要使用 AI/MCP代理，你需要一个OpenAI API密钥。

1. 首选 https://platform.openai.com/api-keys（可译为）：https://openai平台/密钥管理。
2. 登录或创建一个免费账户。
3. 如果您有一个免费账户，您必须设置账单。
4. 点击 “创建新的密钥。”
5. 复制密钥（以 sk-...）。
6. 在运行之前，请将其设置在您的环境中：
   复制

   export OPENAI_API_KEY="sk-yourkeyhere"
   

没有这个密钥，MCP代理仍然可以运行，但会回退到确定性（非AI）模式。

环境变量

许可证

麻省理工学院（MIT）