Auto-Playwright-Web (apw)

轻量级、单用户、**本地文件驱动（File-First）**的 Playwright 自动化脚本守护与调度平台。

提供内置 Web 控制台、开放 REST API 与 Cron 定时调度，支持本地使用 OpenCode 等 AI Agent 直接写文件开发与即时调测。

核心特性

• File-First（文件驱动）：脚本即文件，存放在 scripts/*.py。头部 Docstring 声明参数，无需向数据库导入源码，AI Agent/开发者本地调测零障碍。
• Zero-Config SQLite（零外部依赖）：内置单文件 SQLite（data.db），启动自动建表，彻底告别 MySQL 等外部依赖。
• 开箱即用 Web 界面：前端 SPA 产物直接内置打包在 Python Wheel 中，FastAPI 一键托管，无需单独部署 Nginx 或 Node.js。
• 开放 API 网关：支持通过同步 (/sync) 或异步接口触发任何本地脚本，方便外部服务或工作流系统集成。
• 内置独立定时调度：基于 APScheduler，在 Web 界面即可可视配置 Cron 表达式并管理启停。
• 环境变量与机密管理：支持在线维护工作区 .env，自动透传环境变量至脚本执行子进程，敏感入参自动脱敏。

快速安装与使用

1. 从 PyPI 安装

pip install auto-playwright-web

2. 初始化 Playwright 浏览器内核

首次使用前需下载 Chromium 内核：

playwright install chromium

3. 初始化工作区

在你要管理自动化任务的目录执行：

apw init

执行后将自动生成以下标准目录结构：

my-workspace/
├── scripts/                  # 核心脚本目录（Agent/开发者在此写 Python 脚本）
│   └── example.py            # 示例脚本
├── common/                   # 可选公共模块目录（放可被脚本导入的公共工具）
│   └── __init__.py
├── .storage/                 # 状态持久化目录（用于存 cookies、storage_state 等）
├── .env.example              # 环境变量模板
└── data.db                   # SQLite 数据库（启动后自动创建，存执行日志与调度）

4. 启动服务

apw start --port 8000

打开浏览器访问 http://localhost:8000 即可使用 Web 控制面板。

脚本编写规范

每个脚本是一个标准的 Python 文件（如 scripts/my_task.py）。

在文件头部使用 YAML 格式的 Docstring 声明元数据和参数定义；底部使用 if __name__ == "__main__": 方便本地直接 python scripts/my_task.py 自测：

"""
---
name: 示例任务
timeout: 60
params:
  keyword:
    type: string
    default: "AI"
    description: 搜索词
  headless:
    type: boolean
    default: true
    description: 是否无头运行
---
"""
import os
from playwright.async_api import async_playwright

async def main(params: dict) -> dict:
    keyword = params.get("keyword", "AI")
    print(f"开始执行任务，搜索: {keyword}")

    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=params.get("headless", True))
        page = await browser.new_page()
        await page.goto("https://www.baidu.com")
        await page.fill("#kw", keyword)
        await page.click("#su")
        await page.wait_for_timeout(2000)
        title = await page.title()
        await browser.close()

    return {"ok": True, "title": title}

if __name__ == "__main__":
    import asyncio
    from dotenv import load_dotenv
    load_dotenv()
    asyncio.run(main({"keyword": "Playwright"}))

CLI 命令速查

apw --help

# 启动服务
apw start [--port 8000] [--host 0.0.0.0] [--workdir .]

# 启动时启用 Token 鉴权（Web 控制台与 API 均需登录/携带 Token）
apw start --token "your_secret_token"

# 初始化工作区结构
apw init [--workdir .]

# 命令行直接运行脚本并打印输出
apw run example --params '{"keyword": "OpenCode"}'

# 定时调度管理 (新增/查询/删除)
apw schedule add example --cron "0 8 * * *" --name "每日任务" --params '{"keyword": "AI"}'
apw schedule list
apw schedule delete <schedule_id>

# 查看当前版本
apw version

开放 REST API

安全鉴权说明： 可通过 apw start --token "your_secret_token"（也兼容 --api-key）或在 .env 中设置 APW_API_KEY=your_secret_token / APW_TOKEN=your_secret_token 启用鉴权。启用后 Web 控制台会显示 Token 登录框；外部 API 请求需带上 X-API-Key: your_secret_token、Authorization: Bearer your_secret_token 或 Query 参数 ?api_key=...。如未配置则默认免鉴权（适用于本地开发或纯内网环境）。

本地二次开发

如果你需要对平台本身进行二次开发：

# 1. 克隆代码与安装 Python 依赖
git clone <repo_url>
cd auto-playwright-web
uv sync

# 2. 前端构建开发
cd frontend
npm install
npm run build     # 构建静态产物并生成到 app/static
npm run dev       # 前端本地热重载调试

# 3. 运行本地后端测试
uv run pytest