Metadata-Version: 2.4
Name: automatic-operation-skill
Version: 2.0.0
Summary: 网页自动化操作录制 Skill — 前端监听 → 后端捕获 → AI 精炼 → 执行校验
Author: Aicase
License: MIT
Project-URL: Homepage, https://github.com/Aicase/automatic-operation
Project-URL: Repository, https://github.com/Aicase/automatic-operation
Project-URL: Issues, https://github.com/Aicase/automatic-operation/issues
Keywords: playwright,automation,recording,web-automation,browser-automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40
Provides-Extra: ai
Requires-Dist: requests>=2.28; extra == "ai"
Dynamic: license-file

# Automatic Operation Skill v2.0

网页自动化操作录制 Skill — 前端监听 → 后端捕获 → AI 精炼 → 执行校验，四维闭环确保一次录制普遍适用。

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| 🎬 **可视化录制** | 浏览器中操作，探针自动捕获多维特征 |
| 🧠 **AI 精炼定位器** | 9 级降级策略，自动过滤动态哈希类名 |
| 🔄 **多策略回放** | test_id → role → label → placeholder → text → css_fuzzy |
| 🛡️ **抗干扰设计** | 前序策略失败自动降级，杜绝样式小改版导致的脚本雪崩 |
| 📸 **溯源快照** | 每一步 before/after 截图留存 |
| 🔀 **参数化变量** | 输入值自动识别为 `{{variable_name}}` 占位符 |

## 📦 项目结构

```
automatic-operation-skill/
├── skill_config.json    # 全局配置：入口 URL、全局变量与环境依赖
├── steps.json           # 核心资产：高容错、结构化的多策略操作步骤
├── SKILL.md            # 完整业务手册
├── README.md            # 项目说明文档
├── scripts/
│   ├── recorder.py      # 录制引擎：Playwright + 探针注入 → AI 精炼 → 持久化
│   ├── record_spy.js    # 前端探针：浏览器端多维特征捕获（支持 Shadow DOM）
│   ├── playback.py      # 回放引擎：多策略降级 + 重试 + 智能等待
│   ├── generate_run.py  # 脚本生成器：从 steps.json 生成独立 run.py
│   └── auto-operate.js  # [Legacy] playwright-cli 辅助脚本
└── screenshots/         # 溯源快照：000_init.png / 001_before.png / 001_after.png
```

## 🚀 快速开始

### 环境依赖

```bash
# Python 3.10+
pip install playwright
playwright install chromium

# 可选：AI 精炼
pip install requests
```

### 录制自动化流程

```bash
# 基础录制（启发式定位器）
python3 scripts/recorder.py --skill-name my_flow --start-url https://example.com --headed

# AI 精炼录制
python3 scripts/recorder.py --skill-name my_flow --start-url https://example.com --headed --ai-refine
```

**录制操作说明：**
- 鼠标悬停 → 蓝色虚线高亮
- 点击元素 → 绿色闪烁确认
- 键盘 Enter/Tab → 自动记录按键步骤
- 终端输入 `q` → 退出并保存
- 终端输入 `s` → 手动快照
- 终端输入 `p` → 打印当前步骤

### 回放自动化流程

```bash
# 基础回放
python3 scripts/playback.py --config skill_config.json

# 有头模式 + 变量注入
python3 scripts/playback.py --config skill_config.json --headed --var container_no=GAOU6827574

# 单步调试
python3 scripts/playback.py --config skill_config.json --step step_003 --headed

# 仅校验（不实际执行）
python3 scripts/playback.py --config skill_config.json --dry-run
```

### 生成独立脚本

```bash
# 从 steps.json 生成独立部署脚本
python3 scripts/generate_run.py --config skill_config.json

# 运行生成的脚本
python3 run.py --headed --var container_no=GAOU6827574
```

## 🎯 9 级定位器降级策略

| 级别 | 策略 | 说明 |
|------|------|------|
| L1 | `test_id` | data-testid / data-cy / data-qa / 稳定 id |
| L2 | `role + name` | 无障碍角色 + aria-label / label / text |
| L3 | `role` | 无障碍角色（不含 name，匹配第一个） |
| L4 | `label` | 关联 `<label for="...">` 文本 |
| L5 | `placeholder` | 输入框 placeholder 属性 |
| L6 | `text` | 元素固定文本（≤60 字符） |
| L7 | `name` | name 属性（非动态 id） |
| L8 | `css_fuzzy` | class 前缀匹配 `class^='prefix'` |
| L9 | `href` | 链接触底匹配 `a[href*='path']` |

## 📝 配置示例

### skill_config.json

```json
{
  "skill_name": "my_tracking_flow",
  "version": "1.0.0",
  "description": "自动查询集装箱物流状态",
  "start_url": "https://example.com/tracking",
  "variables": {
    "container_no": {
      "type": "string",
      "description": "集装箱号",
      "default": "",
      "required": true
    }
  },
  "recording_config": {
    "headed": true,
    "ai_refined": false
  }
}
```

### steps.json 步骤定义

```json
{
  "step_id": "step_001",
  "description": "在输入框中填入箱号",
  "action": "fill",
  "locators": [
    {
      "strategy": "test_id",
      "selector": "container-search-input"
    },
    {
      "strategy": "role",
      "role_type": "textbox",
      "name": "集装箱号"
    }
  ],
  "value": "{{container_no}}",
  "timeout": 5000
}
```

## 🔧 高级特性

### 变量注入

录制时输入框自动弹出变量名建议，可在 `skill_config.json` 中预定义：

```bash
python3 playback.py --config skill_config.json --var container_no=ABCD1234567
```

### 断言配置

在 `steps.json` 中手动添加 assertion，确保关键步骤后页面状态正确：

```json
{
  "assertion": {
    "type": "visible",
    "locator": {
      "strategy": "css_fuzzy",
      "selector": ".tracking-result-table"
    }
  }
}
```

### Cookie / 登录态保持

录制完成后，可手动在 `steps.json` 首步前插入 cookie 注入步骤，或通过 Playwright 的 `storageState` 保存登录态。

## ❓ 常见问题

**Q: 探针没有捕获到点击？**
1. 检查 `record_spy.js` 是否成功注入
2. 确认目标网页未设置严格的 CSP（Content Security Policy）
3. 某些 SPA 框架渲染的元素可能不在常规 DOM 树中

**Q: 回放时元素找不到？**
1. 使用 `--dry-run` 校验步骤定义
2. 使用 `--step step_xxx` 单步调试
3. 增大 `--retry` 次数（默认 3）
4. 切换 `--wait domcontentloaded` 等待策略

**Q: 能否录制拖拽、滚动等操作？**
当前版本支持：`click`, `fill`, `hover`, `press`, `check`, `uncheck`, `select`, `focus`。拖拽和滚动需要手动在 `steps.json` 中添加自定义步骤。

## 📄 许可证

[MIT License](LICENSE)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 更新日志

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-05-20 | 初始版本：基础录制 + 回放 |
| 2.0.0 | 2026-05-22 | 全面增强：9 级启发式定位器、AI 精炼、键盘录制、独立脚本生成、重试机制、Shadow DOM 支持 |

---

**Generated by OpenClaw Automatic Operation Skill framework.**
