automatic-operation-skill 2.0.0

网页自动化操作录制 Skill — 前端监听 → 后端捕获 → AI 精炼 → 执行校验

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

🚀 快速开始

环境依赖

# Python 3.10+
pip install playwright
playwright install chromium

# 可选：AI 精炼
pip install requests

录制自动化流程

# 基础录制（启发式定位器）
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

🎯 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

{
  "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 步骤定义

{
  "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"
    }
  }
}

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

🤝 贡献

欢迎提交 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.