Metadata-Version: 2.4
Name: auto-playwright-web
Version: 0.1.2
Summary: Add your description here
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: apscheduler>=3.10.4
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: playwright>=1.45.0
Requires-Dist: pytest>=8.2.0
Requires-Dist: pytest-asyncio>=0.24.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: uvicorn>=0.30.0

﻿# 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 安装

```bash
pip install auto-playwright-web
```

### 2. 初始化 Playwright 浏览器内核

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

```bash
playwright install chromium
```

### 3. 初始化工作区

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

```bash
apw init
```

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

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

### 4. 启动服务

```bash
apw start --port 8000
```

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

---

## 脚本编写规范

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

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

```python
"""
---
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 命令速查

```bash
apw --help

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

# 初始化工作区结构
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

| 接口 | 方法 | 说明 |
| :--- | :---: | :--- |
| `/api/scripts` | GET | 查询所有扫描到的脚本元数据与参数 Schema |
| `/api/open/scripts/{script_code}/executions` | POST | 异步触发脚本执行，立即返回执行记录 ID |
| `/api/open/scripts/{script_code}/executions/sync` | POST | 同步触发脚本执行，等待完成并直接返回结果 |
| `/api/open/executions/{execution_id}` | GET | 查询指定执行记录的日志、耗时与返回值 |
| `/api/schedules` | GET/POST | 查询与创建定时调度规则 |
| `/api/env-vars` | GET/PUT | 读取或在线更新本地工作区 `.env` 配置文件 |

> **安全鉴权说明**：
> 若在 `.env` 中设置了 `APW_API_KEY=your_secret_token`，所有外部 API 请求需带上 Header `X-API-Key: your_secret_token` 或 Query 参数 `?api_key=...`。如未配置则默认免鉴权（适用于本地开发或纯内网环境）。

---

## 本地二次开发

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

```bash
# 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
```
