网页自动化操作录制 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
# 方式一：pip 安装（推荐）
pip install automatic-operation-skill
# 方式二：从 GitHub 安装
pip install git+https://github.com/Aicase/automatic-operation.git安装后会自动安装 Playwright，手动安装浏览器：
playwright install chromium如果需要 AI 精炼功能：
pip install automatic-operation-skill[ai]# 基础录制（启发式定位器）
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→ 打印当前步骤
# 基础回放
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# 从 steps.json 生成独立部署脚本
python3 scripts/generate_run.py --config skill_config.json
# 运行生成的脚本
python3 run.py --headed --var container_no=GAOU6827574| 级别 | 策略 | 说明 |
|---|---|---|
| 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_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
}
}{
"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 中预定义：
python3 playback.py --config skill_config.json --var container_no=ABCD1234567在 steps.json 中手动添加 assertion，确保关键步骤后页面状态正确：
{
"assertion": {
"type": "visible",
"locator": {
"strategy": "css_fuzzy",
"selector": ".tracking-result-table"
}
}
}录制完成后，可手动在 steps.json 首步前插入 cookie 注入步骤，或通过 Playwright 的 storageState 保存登录态。
Q: 探针没有捕获到点击？
- 检查
record_spy.js是否成功注入 - 确认目标网页未设置严格的 CSP（Content Security Policy）
- 某些 SPA 框架渲染的元素可能不在常规 DOM 树中
Q: 回放时元素找不到？
- 使用
--dry-run校验步骤定义 - 使用
--step step_xxx单步调试 - 增大
--retry次数（默认 3） - 切换
--wait domcontentloaded等待策略
Q: 能否录制拖拽、滚动等操作？
当前版本支持：click, fill, hover, press, check, uncheck, select, focus。拖拽和滚动需要手动在 steps.json 中添加自定义步骤。
欢迎提交 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.