C4A-Script：简化可视化 Web 自动化

¥C4A-Script: Visual Web Automation Made Simple

什么是 C4A-Script？

¥What is C4A-Script?

C4A-Script 是一种功能强大、易于理解的领域特定语言 (DSL)，专为 Web 自动化和交互而设计。它是一种任何人都可以读写的简化编程语言，非常适合自动执行重复的 Web 任务、测试用户界面或创建交互式演示。

¥C4A-Script is a powerful, human-readable domain-specific language (DSL) designed for web automation and interaction. Think of it as a simplified programming language that anyone can read and write, perfect for automating repetitive web tasks, testing user interfaces, or creating interactive demos.

为什么选择 C4A-Script？

¥Why C4A-Script?

简单的语法，强大的结果

¥Simple Syntax, Powerful Results 

# Navigate and interact in plain English
GO https://example.com
WAIT `#search-box` 5
TYPE "Hello World"
CLICK `button[type="submit"]`

可视化编程支持C4A-Script 带有内置的 Blockly 可视化编辑器，允许您通过拖放块来创建脚本 - 无需编码经验！

¥Visual Programming Support C4A-Script comes with a built-in Blockly visual editor, allowing you to create scripts by dragging and dropping blocks - no coding experience required!

适合： - UI 测试：自动化用户交互流程 -演示创建：构建交互式产品演示
-数据输入：自动填写和提交表格 -测试工作流程：验证复杂的用户旅程 -训练：无需复杂的代码即可教授 Web 自动化

¥Perfect for: - UI Testing: Automate user interaction flows - Demo Creation: Build interactive product demonstrations
- Data Entry: Automate form filling and submissions - Testing Workflows: Validate complex user journeys - Training: Teach web automation without code complexity

入门：你的第一个脚本

¥Getting Started: Your First Script

让我们创建一个在网站上搜索某些内容的简单脚本：

¥Let's create a simple script that searches for something on a website:

# My first C4A-Script
GO https://duckduckgo.com

# Wait for the search box to appear
WAIT `input[name="q"]` 10

# Type our search query
TYPE "Crawl4AI"

# Press Enter to search
PRESS Enter

# Wait for results
WAIT `.results` 5

就这样！只需几行代码，您就自动化了完整的搜索工作流程。

¥That's it! In just a few lines, you've automated a complete search workflow.

交互式教程和现场演示

¥Interactive Tutorial & Live Demo

想边做边学吗？我们帮你搞定：

¥Want to learn by doing? We've got you covered:

🚀 现场演示- 立即在您的浏览器中尝试 C4A-Script！

¥🚀 Live Demo - Try C4A-Script in your browser right now!

📁 教程示例- 带有源代码的完整示例

¥📁 Tutorial Examples - Complete examples with source code

本地运行教程

¥Running the Tutorial Locally

本教程包含一个基于 Flask 的 Web 界面，其中包含：-实时代码编辑器语法高亮显示 -可视化 Blockly 编辑器用于拖放编程 -录制模式捕捉你的动作并生成脚本 -时间线视图查看和编辑您的自动化步骤

¥The tutorial includes a Flask-based web interface with: - Live Code Editor with syntax highlighting - Visual Blockly Editor for drag-and-drop programming - Recording Mode to capture your actions and generate scripts - Timeline View to see and edit your automation steps

# Clone and navigate to the tutorial
cd docs/examples/c4a_script/tutorial/

# Install dependencies
pip install flask

# Launch the tutorial server
python app.py

# Open http://localhost:5000 in your browser

核心概念

¥Core Concepts

命令和语法

¥Commands and Syntax

C4A-Script 使用类似英语的简单命令。每个命令都执行一项特定的操作：

¥C4A-Script uses simple, English-like commands. Each command does one specific thing:

# Comments start with #
COMMAND parameter1 parameter2

# Most commands use CSS selectors in backticks
CLICK `#submit-button`

# Text content goes in quotes
TYPE "Hello, World!"

# Numbers are used directly
WAIT 3

选择器：查找元素

¥Selectors: Finding Elements

C4A-Script 使用 CSS 选择器来识别页面上的元素：

¥C4A-Script uses CSS selectors to identify elements on the page:

# By ID
CLICK `#login-button`

# By class
CLICK `.submit-btn`

# By attribute
CLICK `button[type="submit"]`

# By text content
CLICK `button:contains("Sign In")`

# Complex selectors
CLICK `.form-container input[name="email"]`

变量和动态内容

¥Variables and Dynamic Content

使用变量存储和重用值：

¥Store and reuse values with variables:

# Set a variable
SETVAR username = "john@example.com"
SETVAR password = "secret123"

# Use variables (prefix with $)
TYPE $username
PRESS Tab
TYPE $password

命令类别

¥Command Categories

¥🧭 Navigation Commands

像用户一样在网络上移动：

¥Move around the web like a user would:

¥Command

¥Purpose

¥Example

¥Navigate to URL

¥Refresh current page

¥Go back in history

¥Go forward in history

命令 目的 例子
GO 导航至 URL GO https://example.com
RELOAD 刷新当前页面 RELOAD
BACK 回顾历史 BACK
FORWARD 在历史中前进 FORWARD

⏱️等待命令

¥⏱️ Wait Commands

确保元素在交互之前已准备就绪：

¥Ensure elements are ready before interacting:

¥Command

¥Purpose

¥Example

¥Wait for time/element/text

¥WAIT 3 or WAIT \#element` 10`

命令 目的 例子
WAIT 等待时间/元素/文本 或者WAIT \#元素` 10`

🖱️ 鼠标命令

¥🖱️ Mouse Commands

像人类一样单击、拖动和移动：

¥Click, drag, and move like a human:

¥Command

¥Purpose

¥Example

¥Click element or coordinates

¥CLICK \button`orCLICK 100 200`

¥Double-click element

¥DOUBLE_CLICK \.item``

¥Right-click element

¥RIGHT_CLICK \#menu``

¥Scroll in direction

¥Drag from point to point

命令 目的 例子
CLICK 点击元素或坐标 按钮`or点击 100 200`
DOUBLE_CLICK 双击元素 .item``
RIGHT_CLICK 右键单击元素 #菜单``
SCROLL 向以下方向滚动 SCROLL DOWN 500
DRAG 从点拖动到点 DRAG 100 100 500 300

⌨️ 键盘命令

¥⌨️ Keyboard Commands

自然地输入文本并按下按键：

¥Type text and press keys naturally:

¥Command

¥Purpose

¥Example

¥Type text or variable

¥TYPE "Hello" or TYPE $username

¥Press special keys

¥PRESS Tab or PRESS Enter

¥Clear input field

¥CLEAR \#search``

¥Set input value directly

¥SET \#email` "user@example.com"`

命令 目的 例子
TYPE 输入文本或变量 或者TYPE $username
PRESS 按特殊键 或者PRESS Enter
CLEAR 清除输入字段 #搜索``
SET 直接设置输入值 #email`“user@example.com”`

🔀 控制流

¥🔀 Control Flow

为您的脚本添加逻辑和重复：

¥Add logic and repetition to your scripts:

¥Command

¥Purpose

¥Example

¥Conditional execution

¥IF (EXISTS \#popup`) THEN CLICK `#close``

¥Loop commands

命令 目的 例子
IF 条件执行 #popup') 然后点击 `#close``
REPEAT 循环命令 REPEAT (SCROLL DOWN 300, 5)

💾 变量和高级

¥💾 Variables & Advanced

存储数据并执行自定义代码：

¥Store data and execute custom code:

¥Command

¥Purpose

¥Example

¥Create variable

¥Execute JavaScript

¥EVAL \console.log('Hello')``

命令 目的 例子
SETVAR 创建变量 SETVAR email = "test@example.com"
EVAL 执行 JavaScript console.log（'你好'）``

现实世界的例子

¥Real-World Examples

示例 1：登录流程

¥Example 1: Login Flow

# Complete login automation
GO https://myapp.com/login

# Wait for page to load
WAIT `#login-form` 5

# Fill credentials
CLICK `#email`
TYPE "user@example.com"
PRESS Tab
TYPE "mypassword"

# Submit form
CLICK `button[type="submit"]`

# Wait for dashboard
WAIT `.dashboard` 10

示例 2：电子商务购物

¥Example 2: E-commerce Shopping

# Shopping automation with variables
SETVAR product = "laptop"
SETVAR budget = "1000"

GO https://shop.example.com
WAIT `#search-box` 3

# Search for product
TYPE $product
PRESS Enter
WAIT `.product-list` 5

# Filter by price
CLICK `.price-filter`
SET `#max-price` $budget
CLICK `.apply-filters`

# Select first result
WAIT `.product-item` 3
CLICK `.product-item:first-child`

示例 3：带条件的表单自动化

¥Example 3: Form Automation with Conditions

# Smart form filling with error handling
GO https://forms.example.com

# Check if user is already logged in
IF (EXISTS `.user-menu`) THEN GO https://forms.example.com/new
IF (NOT EXISTS `.user-menu`) THEN CLICK `#login-link`

# Fill form
WAIT `#contact-form` 5
SET `#name` "John Doe"
SET `#email` "john@example.com"
SET `#message` "Hello from C4A-Script!"

# Handle popup if it appears
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`

# Submit
CLICK `#submit-button`
WAIT `.success-message` 10

使用 Blockly 进行可视化编程

¥Visual Programming with Blockly

C4A-Script 包含基于 Google Blockly 构建的强大可视化编程界面。适用于：

¥C4A-Script includes a powerful visual programming interface built on Google Blockly. Perfect for:

  • 非程序员想要创建自动化

    ¥Non-programmers who want to create automation

  • 快速成型自动化工作流程

    ¥Rapid prototyping of automation workflows

  • 教育环境用于教授自动化概念

    ¥Educational environments for teaching automation concepts

  • 协作开发视觉表现有助于沟通

    ¥Collaborative development where visual representation helps communication

特征：

¥Features:

  • 拖放界面：通过连接块来构建脚本

    ¥Drag & Drop Interface: Build scripts by connecting blocks

  • 实时同步：视觉模式下的更改会立即更新文本脚本

    ¥Real-time Sync: Changes in visual mode instantly update the text script

  • 智能块类型：块按功能分类（导航、操作等）

    ¥Smart Block Types: Blocks are categorized by function (Navigation, Actions, etc.)

  • 错误预防：视觉连接可防止语法错误

    ¥Error Prevention: Visual connections prevent syntax errors

  • 评论支持：为文档添加可视化注释块

    ¥Comment Support: Add visual comment blocks for documentation

尝试一下我们的可视化编辑器现场演示或者本地教程。

¥Try the visual editor in our live demo or local tutorial.

高级功能

¥Advanced Features

录制模式

¥Recording Mode

教程界面包含一个记录功能，可以观察您的浏览器交互并自动生成 C4A-Script 命令：

¥The tutorial interface includes a recording feature that watches your browser interactions and automatically generates C4A-Script commands:

  1. 在教程界面点击“录制”

    ¥Click "Record" in the tutorial interface

  2. 在浏览器预览中执行操作

    ¥Perform actions in the browser preview

  3. 实时观察 C4A-Script 命令的生成

    ¥Watch as C4A-Script commands are generated in real-time

  4. 编辑并完善生成的脚本

    ¥Edit and refine the generated script

错误处理和调试

¥Error Handling and Debugging

C4A-Script 提供清晰的错误信息和调试信息：

¥C4A-Script provides clear error messages and debugging information:

# Use comments for debugging
# This will wait up to 10 seconds for the element
WAIT `#slow-loading-element` 10

# Check if element exists before clicking
IF (EXISTS `#optional-button`) THEN CLICK `#optional-button`

# Use EVAL for custom debugging
EVAL `console.log("Current page title:", document.title)`

与 Crawl4AI 集成

¥Integration with Crawl4AI

C4A-Script 与 Crawl4AI 的网络爬取功能无缝集成：

¥C4A-Script integrates seamlessly with Crawl4AI's web crawling capabilities:

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

# Use C4A-Script for interaction before crawling
script = """
GO https://example.com
CLICK `#load-more-content`
WAIT `.dynamic-content` 5
"""

config = CrawlerRunConfig(
    js_code=script,
    wait_for=".dynamic-content"
)

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun("https://example.com", config=config)
    print(result.markdown)

最佳实践

¥Best Practices

1. 始终等待元素

¥1. Always Wait for Elements

# Bad: Clicking immediately
CLICK `#button`

# Good: Wait for element to appear
WAIT `#button` 5
CLICK `#button`

2. 使用描述性注释

¥2. Use Descriptive Comments

# Login to user account
GO https://myapp.com/login
WAIT `#login-form` 5

# Enter credentials
TYPE "user@example.com"
PRESS Tab
TYPE "password123"

# Submit and wait for redirect
CLICK `#submit-button`
WAIT `.dashboard` 10

3.处理变量条件

¥3. Handle Variable Conditions

# Handle different page states
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept-cookies`
IF (EXISTS `.popup-modal`) THEN CLICK `.close-modal`

# Proceed with main workflow
CLICK `#main-action`

4. 使用变量实现可重用性

¥4. Use Variables for Reusability

# Define once, use everywhere
SETVAR base_url = "https://myapp.com"
SETVAR test_email = "test@example.com"

GO $base_url/login
SET `#email` $test_email

获取帮助

¥Getting Help

  • 📖 完整示例- 真实世界的自动化脚本

    ¥📖 Complete Examples - Real-world automation scripts

  • 🎮 交互式教程- 实践学习环境

    ¥🎮 Interactive Tutorial - Hands-on learning environment

  • 📋 API 参考- 详细的命令文档

    ¥📋 API Reference - Detailed command documentation

  • 🌐 现场演示- 在您的浏览器中尝试

    ¥🌐 Live Demo - Try it in your browser

下一步是什么？

¥What's Next?

准备好深入了解了吗？请查看：

¥Ready to dive deeper? Check out:

  1. API 参考- 完整的命令文档

    ¥API Reference - Complete command documentation

  2. 教程示例- 可复制粘贴的脚本

    ¥Tutorial Examples - Copy-paste ready scripts

  3. 本地教程设置- 运行完整的开发环境

    ¥Local Tutorial Setup - Run the full development environment

C4A-Script 让每个人都能轻松使用 Web 自动化。无论您是进行自动化测试的开发人员、创建交互式演示的设计师，还是简化重复性任务的业务用户，C4A-Script 都能为您提供所需的工具。

¥C4A-Script makes web automation accessible to everyone. Whether you're a developer automating tests, a designer creating interactive demos, or a business user streamlining repetitive tasks, C4A-Script has the tools you need.

今天就开始自动化——你未来的自己会感谢你！ 🚀

¥Start automating today - your future self will thank you! 🚀

> Feedback