jzw/VWED_server

Fork 0

靳中伟 df99d64864 增加在线脚本开发框架

2025-09-12 16:15:13 +08:00

38 KiB

Raw Blame History

VWED在线脚本编辑模块接口文档

概述

VWED在线脚本编辑模块提供了完整的Python脚本在线编辑、执行和管理功能。支持多脚本并发运行、实时日志推送、动态API注册、函数调用等特性，并可与VWED任务系统无缝集成。

基础URL: /api/script

版本: v1.0

支持的功能:

脚本项目和文件管理
实时脚本编辑和语法验证
多脚本并发执行引擎
实时日志推送和状态监控
动态API接口注册
自定义函数注册和调用
VWED任务系统集成

1. 脚本项目管理

1.1 创建脚本项目

接口地址: POST /api/script/projects

功能说明: 创建新的脚本项目，项目用于组织管理多个脚本文件。

请求参数:

{
    "project_name": "string",        // 项目名称，必填，最大100字符
    "description": "string",         // 项目描述，可选
    "created_by": "string"           // 创建者，可选，最大100字符
}

响应示例:

{
    "success": true,
    "message": "项目 测试项目 创建成功",
    "data": {
        "id": 1,
        "project_name": "测试项目",
        "project_path": "projects/测试项目",
        "description": "这是一个测试项目",
        "status": "active",
        "created_by": "admin",
        "created_at": "2025-09-11T12:00:00",
        "updated_at": "2025-09-11T12:00:00"
    }
}

1.2 获取项目列表

接口地址: GET /api/script/projects

功能说明: 获取所有脚本项目列表。

查询参数:

status (可选): 项目状态过滤，默认为 "active"

响应示例:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "project_name": "测试项目",
            "project_path": "projects/测试项目",
            "description": "这是一个测试项目",
            "status": "active",
            "created_by": "admin",
            "created_at": "2025-09-11T12:00:00",
            "updated_at": "2025-09-11T12:00:00"
        }
    ]
}

1.3 获取项目文件列表

接口地址: GET /api/script/projects/{project_id}/files

功能说明: 获取指定项目下的所有脚本文件。

路径参数:

project_id: 项目ID

查询参数:

include_content (可选): 是否包含文件内容，默认为 false

响应示例:

{
    "success": true,
    "data": {
        "project": {
            "id": 1,
            "project_name": "测试项目",
            "project_path": "projects/测试项目"
        },
        "files": [
            {
                "id": 1,
                "file_name": "main.py",
                "file_path": "main.py",
                "file_type": "python",
                "size": 1024,
                "has_boot_function": true,
                "status": "active",
                "created_at": "2025-09-11T12:00:00",
                "content": "def boot():\n    pass"  // 仅当include_content=true时包含
            }
        ]
    }
}

2. 脚本文件管理

2.1 创建脚本文件

接口地址: POST /api/script/files

功能说明: 在指定项目中创建新的脚本文件。

请求参数:

{
    "project_id": 1,                 // 所属项目ID，必填
    "file_name": "string",           // 文件名，必填，最大255字符
    "file_path": "string",           // 文件相对路径，必填，最大500字符
    "content": "string",             // 文件内容，可选
    "file_type": "python",           // 文件类型，默认为"python"
    "created_by": "string"           // 创建者，可选
}

响应示例:

{
    "success": true,
    "message": "文件 main.py 创建成功",
    "data": {
        "id": 1,
        "project_id": 1,
        "file_name": "main.py",
        "file_path": "main.py",
        "file_type": "python",
        "content": "def boot():\n    print('Hello VWED!')",
        "size": 35,
        "has_boot_function": true,
        "status": "active",
        "created_by": "admin",
        "created_at": "2025-09-11T12:00:00",
        "updated_at": "2025-09-11T12:00:00"
    }
}

2.2 获取文件内容

接口地址: GET /api/script/files/{file_id}

功能说明: 获取指定脚本文件的详细信息和内容。

路径参数:

file_id: 文件ID

响应示例:

{
    "success": true,
    "data": {
        "file": {
            "id": 1,
            "project_id": 1,
            "file_name": "main.py",
            "file_path": "main.py",
            "file_type": "python",
            "size": 35,
            "has_boot_function": true,
            "status": "active",
            "created_at": "2025-09-11T12:00:00",
            "updated_at": "2025-09-11T12:00:00"
        },
        "content": "def boot():\n    print('Hello VWED!')"
    }
}

2.3 更新文件内容

接口地址: PUT /api/script/files/{file_id}

功能说明: 更新指定脚本文件的内容，自动创建备份。

路径参数:

file_id: 文件ID

请求参数:

{
    "content": "string",             // 新的文件内容，必填
    "updated_by": "string"          // 更新者，可选
}

响应示例:

{
    "success": true,
    "message": "文件内容更新成功",
    "data": {
        "file": {
            "id": 1,
            "project_id": 1,
            "file_name": "main.py",
            "file_path": "main.py",
            "content": "def boot():\n    VWED.log.sync_info('脚本启动成功')",
            "size": 45,
            "has_boot_function": true,
            "updated_at": "2025-09-11T12:30:00"
        },
        "backup_path": "/path/to/backup/main.py.bak.1726059000"
    }
}

2.4 删除文件

接口地址: DELETE /api/script/files/{file_id}

功能说明: 删除指定的脚本文件。

路径参数:

file_id: 文件ID

响应示例:

{
    "success": true,
    "message": "文件 main.py 删除成功"
}

2.5 搜索文件

接口地址: GET /api/script/files/search

功能说明: 根据关键字搜索脚本文件。

查询参数:

keyword: 搜索关键字，必填
project_id (可选): 限制在指定项目中搜索
file_type (可选): 文件类型过滤
has_boot (可选): 是否包含boot函数

响应示例:

{
    "success": true,
    "data": {
        "files": [
            {
                "id": 1,
                "file_name": "main.py",
                "file_path": "main.py",
                "project_name": "测试项目",
                "file_type": "python",
                "has_boot_function": true,
                "created_at": "2025-09-11T12:00:00"
            }
        ],
        "count": 1
    }
}

2.6 语法验证

接口地址: POST /api/script/validate-syntax

功能说明: 验证Python脚本的语法正确性。

请求参数:

{
    "content": "string"              // 待验证的脚本内容，必填
}

响应示例（成功）:

{
    "success": true,
    "data": {
        "valid": true,
        "message": "语法检查通过"
    }
}

响应示例（失败）:

{
    "success": true,
    "data": {
        "valid": false,
        "error": "语法错误: invalid syntax",
        "line": 5,
        "offset": 10
    }
}

2.7 上传脚本文件

接口地址: POST /api/script/upload

功能说明: 通过文件上传的方式创建脚本文件。

请求参数 (Form Data):

project_id: 项目ID，必填
file: 上传的脚本文件，必填

响应示例:

{
    "success": true,
    "message": "文件上传成功",
    "data": {
        "id": 1,
        "file_name": "uploaded_script.py",
        "file_path": "uploaded_script.py",
        "size": 256,
        "has_boot_function": false,
        "created_at": "2025-09-11T12:00:00"
    }
}

3. 脚本执行管理

3.1 启动脚本服务

接口地址: POST /api/script/scripts/start

功能说明: 启动脚本服务，执行脚本的boot函数并注册相关服务。每个脚本启动后会生成唯一的script_id用于标识。

请求参数:

{
    "script_path": "string",         // 脚本相对路径，必填
    "start_params": {                // 启动参数，可选
        "key": "value"
    }
}

响应示例（成功）:

{
    "success": true,
    "script_id": "main.py_1726059000000_abc12345",
    "message": "脚本服务启动成功，已注册 2 个接口，3 个函数，1 个事件监听器",
    "registrations": {
        "apis": 2,
        "functions": 3,
        "events": 1,
        "timers": 0
    }
}

响应示例（失败）:

{
    "success": false,
    "error": "脚本文件不存在: invalid_script.py"
}

3.2 停止脚本服务

接口地址: POST /api/script/scripts/{script_id}/stop

功能说明: 停止指定的脚本服务，清理所有注册项。

路径参数:

script_id: 脚本实例ID

响应示例:

{
    "success": true,
    "message": "脚本服务已停止 (main.py)，已清理 2 个接口、3 个函数、1 个事件监听器",
    "registrations": {
        "apis": 2,
        "functions": 3,
        "events": 1,
        "timers": 0
    }
}

3.3 获取运行中的脚本

接口地址: GET /api/script/scripts/running

功能说明: 获取当前所有运行中的脚本服务列表。

响应示例:

{
    "success": true,
    "data": [
        {
            "script_id": "main.py_1726059000000_abc12345",
            "script_path": "main.py",
            "started_at": "2025-09-11T12:00:00",
            "status": "running",
            "registrations": {
                "apis": 2,
                "functions": 3,
                "events": 1,
                "timers": 0
            }
        }
    ]
}

3.4 执行脚本函数

接口地址: POST /api/script/scripts/execute-function

功能说明: 调用运行中脚本的指定函数。

请求参数:

{
    "script_id": "string",           // 脚本实例ID，必填
    "function_name": "string",       // 函数名，必填
    "function_args": "any"           // 函数参数，可选
}

响应示例（成功）:

{
    "success": true,
    "result": "函数执行结果",
    "execution_time_ms": 125
}

响应示例（失败）:

{
    "success": false,
    "error": "函数 invalid_function 未注册",
    "execution_time_ms": 5
}

3.5 获取注册中心状态

接口地址: GET /api/script/registry/status

功能说明: 获取脚本注册中心的详细状态信息。

响应示例:

{
    "success": true,
    "data": {
        "api_routes": {
            "GET:/api/custom/test": {
                "path": "/api/custom/test",
                "method": "GET",
                "script_id": "main.py_1726059000000_abc12345",
                "description": "测试接口",
                "call_count": 5,
                "average_response_time_ms": 15,
                "registered_at": "2025-09-11T12:00:00"
            }
        },
        "registered_functions": {
            "calculate": {
                "script_id": "main.py_1726059000000_abc12345",
                "description": "计算函数",
                "is_async": false,
                "call_count": 10,
                "success_count": 9,
                "error_count": 1,
                "average_execution_time_ms": 23
            }
        },
        "event_listeners": {
            "task_completed": [
                {
                    "script_id": "main.py_1726059000000_abc12345",
                    "priority": 1,
                    "registered_at": "2025-09-11T12:00:00"
                }
            ]
        },
        "timers": {},
        "active_scripts": {
            "main.py_1726059000000_abc12345": {
                "script_path": "main.py",
                "started_at": "2025-09-11T12:00:00",
                "status": "running",
                "heartbeat": 1726059300.123
            }
        }
    }
}

4. WebSocket实时通信

4.1 脚本日志WebSocket连接

连接地址: ws://localhost:8000/api/script/ws/script-logs

功能说明: 建立WebSocket连接，接收实时脚本日志和状态更新。

连接参数:

client_id: 客户端ID，必填
client_type: 客户端类型，默认为"web"

连接示例:

const ws = new WebSocket('ws://localhost:8000/api/script/ws/script-logs?client_id=web-client-1&client_type=web');

4.2 客户端消息格式

订阅脚本日志:

{
    "type": "subscribe",
    "script_id": "main.py_1726059000000_abc12345"
}

取消订阅脚本日志:

{
    "type": "unsubscribe",
    "script_id": "main.py_1726059000000_abc12345"
}

心跳检测:

{
    "type": "ping",
    "timestamp": "2025-09-11T12:00:00Z"
}

获取连接状态:

{
    "type": "get_status"
}

4.3 服务端消息格式

欢迎消息:

{
    "type": "welcome",
    "connection_id": "web_web-client-1_1726059000000",
    "server_time": "2025-09-11T12:00:00Z",
    "message": "连接建立成功"
}

脚本日志消息:

{
    "type": "script_log",
    "script_id": "main.py_1726059000000_abc12345",
    "timestamp": "2025-09-11T12:00:00Z",
    "level": "INFO",
    "message": "脚本执行成功"
}

脚本状态变化:

{
    "type": "script_status",
    "script_id": "main.py_1726059000000_abc12345",
    "timestamp": "2025-09-11T12:00:00Z",
    "status": "running",
    "message": "脚本启动成功"
}

函数执行结果:

{
    "type": "function_execution",
    "script_id": "main.py_1726059000000_abc12345",
    "timestamp": "2025-09-11T12:00:00Z",
    "function_name": "calculate",
    "execution_type": "success",
    "result": {
        "success": true,
        "data": 42,
        "execution_time_ms": 15
    }
}

4.4 获取WebSocket连接状态

接口地址: GET /api/script/ws/connections/status

功能说明: 获取当前WebSocket连接的详细状态。

响应示例:

{
    "success": true,
    "data": {
        "total_connections": 3,
        "total_script_subscriptions": 2,
        "connections": [
            {
                "connection_id": "web_client1_1726059000000",
                "client_id": "client1",
                "client_type": "web",
                "connected_at": "2025-09-11T12:00:00Z",
                "subscribed_scripts": ["main.py_1726059000000_abc12345"]
            }
        ],
        "script_subscriptions": {
            "main.py_1726059000000_abc12345": 2
        }
    }
}

4.5 WebSocket测试页面

接口地址: GET /api/script/ws/test-page

功能说明: 获取WebSocket测试页面，提供完整的测试界面。

响应: HTML页面，包含：

WebSocket连接控制
脚本订阅/取消订阅
实时日志显示
心跳检测功能

4.6 测试广播消息

接口地址: POST /api/script/ws/broadcast/test

功能说明: 向指定脚本的订阅者测试广播消息。

请求参数:

{
    "script_id": "main.py_1726059000000_abc12345",
    "message": "测试消息",
    "level": "info"
}

响应示例:

{
    "success": true,
    "message": "测试消息已广播到脚本 main.py_1726059000000_abc12345 的订阅者"
}

5. VWED统一对象系统

5.1 VWED对象结构

在脚本中可以使用全局的VWED对象，包含以下模块：

# VWED对象结构
VWED.api          # API接口注册模块
VWED.function     # 自定义函数注册模块  
VWED.event        # 事件系统模块
VWED.timer        # 定时任务模块
VWED.log          # 日志系统模块
VWED.task         # 任务系统集成模块
VWED.data         # 数据存储模块
VWED.util         # 工具函数模块

5.2 API注册模块（VWED.api）

功能说明: 用于动态注册HTTP API接口，支持GET、POST、PUT、DELETE等方法。

使用示例:

# 注册GET接口
@VWED.api.get("/test", description="测试接口")
def handle_test(request_data):
    return {"message": "Hello from script!"}

# 注册POST接口  
@VWED.api.post("/calculate", description="计算接口")
def handle_calculate(request_data):
    a = request_data["body"].get("a", 0)
    b = request_data["body"].get("b", 0)
    return {"result": a + b}

# 通用注册方式
@VWED.api.register("/custom", "PUT", description="自定义接口")
def handle_custom(request_data):
    return {"status": "success"}

request_data结构:

{
    "method": "GET",                    # HTTP方法
    "path": "/api/custom/test",         # 请求路径
    "query_params": {"key": "value"},   # 查询参数
    "path_params": {"id": "123"},       # 路径参数
    "body": {"data": "value"},          # 请求体数据
    "headers": {"Content-Type": "application/json"},  # 请求头
    "client": "192.168.1.100"           # 客户端IP
}

5.3 函数注册模块（VWED.function）

功能说明: 注册自定义函数，供VWED任务系统或其他脚本调用。

使用示例:

# 注册同步函数
@VWED.function.register("add_numbers", description="数字相加")
def add_numbers(args):
    return args["a"] + args["b"]

# 注册异步函数
@VWED.function.register("async_process", description="异步处理")
async def async_process(args):
    await VWED.util.async_sleep(1)
    return {"processed": True}

# 带参数定义的函数注册
@VWED.function.register(
    "complex_calc", 
    description="复杂计算",
    parameters=[
        {"name": "x", "type": "number", "required": True},
        {"name": "y", "type": "number", "required": True}
    ],
    return_schema={"type": "object", "properties": {"result": {"type": "number"}}},
    tags=["math", "calculation"]
)
def complex_calc(args):
    return {"result": args["x"] * args["y"] + 10}

5.4 事件系统模块（VWED.event）

功能说明: 事件监听和触发机制，支持系统事件和自定义事件。

使用示例:

# 监听任务完成事件
@VWED.event.listen("task_completed")
def on_task_completed(event_data):
    VWED.log.sync_info(f"任务完成: {event_data['task_id']}")

# 高优先级事件监听
@VWED.event.listen("critical_error", priority=0)  # 优先级越低越先执行
def on_critical_error(event_data):
    VWED.log.sync_error(f"严重错误: {event_data['error']}")

# 触发自定义事件
async def trigger_event():
    await VWED.event.emit("custom_event", {
        "source": "script",
        "data": {"key": "value"},
        "timestamp": VWED.util.now()
    })

# 事件监听器的别名用法
@VWED.event.on("user_login")
def handle_user_login(event_data):
    VWED.log.sync_info(f"用户登录: {event_data['user_id']}")

5.5 定时任务模块（VWED.timer）

功能说明: 注册定时任务和周期性任务。

使用示例:

# 每30秒执行一次
@VWED.timer.interval(30)
def heartbeat():
    VWED.log.sync_info("心跳检测")

# 延迟5秒后执行一次
@VWED.timer.once(delay=5)
def delayed_task():
    VWED.log.sync_info("延迟任务执行")

# 复合定时任务
@VWED.timer.interval(60, repeat=True, delay=10)
def monitor_system():
    # 延迟10秒开始，然后每60秒执行一次
    VWED.log.sync_info("系统监控检查")

# 使用别名
@VWED.timer.every(120)  # 每2分钟执行
def cleanup_temp_files():
    VWED.log.sync_info("清理临时文件")

5.6 日志系统模块（VWED.log）

功能说明: 记录日志并实时推送到WebSocket客户端。

使用示例:

# 异步日志记录（推荐）
async def async_log_example():
    await VWED.log.info("信息日志", extra_data={"key": "value"})
    await VWED.log.warning("警告日志", component="database")
    await VWED.log.error("错误日志", error_code=500)
    await VWED.log.debug("调试日志", debug_info="详细信息")

# 同步日志记录（在非异步环境中使用）
def sync_log_example():
    VWED.log.sync_info("同步信息日志")
    VWED.log.sync_warning("同步警告日志")
    VWED.log.sync_error("同步错误日志")
    VWED.log.sync_debug("同步调试日志")

# 带结构化数据的日志
def structured_log_example():
    VWED.log.sync_info("用户操作", 
        user_id="12345", 
        action="login", 
        ip_address="192.168.1.100",
        timestamp=VWED.util.now()
    )

5.7 任务系统集成模块（VWED.task）

功能说明: 与VWED任务系统集成，支持任务创建和执行。

使用示例:

# 创建VWED任务（功能规划中）
async def create_new_task():
    result = await VWED.task.create_task("动态任务", {
        "blocks": [
            {"type": "start", "config": {}},
            {"type": "script", "config": {"function_name": "process_data"}},
            {"type": "end", "config": {}}
        ]
    })
    return result

# 执行现有任务（功能规划中）
async def execute_existing_task():
    result = await VWED.task.execute_task(123, {"param1": "value1"})
    return result

# 获取任务状态（功能规划中）
async def get_task_info():
    result = await VWED.task.get_task_status(123)
    return result

5.8 数据存储模块（VWED.data）

功能说明: 脚本级别的数据存储和缓存。

使用示例:

# 基本数据操作
def data_operations():
    # 存储数据
    VWED.data.set("user_count", 100)
    VWED.data.set("config", {"host": "localhost", "port": 8080})
    
    # 获取数据
    count = VWED.data.get("user_count", 0)
    config = VWED.data.get("config", {})
    
    # 检查键是否存在
    if VWED.data.has("user_count"):
        VWED.log.sync_info(f"当前用户数: {count}")
    
    # 获取所有键
    all_keys = VWED.data.keys()
    VWED.log.sync_info(f"存储的键: {all_keys}")
    
    # 删除数据
    VWED.data.delete("user_count")
    
    # 清空所有数据
    VWED.data.clear()

# 数据缓存示例
def caching_example():
    # 检查缓存
    cached_result = VWED.data.get("calculation_result")
    if cached_result is None:
        # 计算并缓存
        result = complex_calculation()
        VWED.data.set("calculation_result", result)
        return result
    else:
        return cached_result

5.9 工具函数模块（VWED.util）

功能说明: 提供常用的工具函数。

使用示例:

# 时间工具
def time_utils():
    # 获取当前时间
    current_time = VWED.util.now()  # ISO格式字符串
    timestamp = VWED.util.timestamp()  # Unix时间戳
    
    VWED.log.sync_info(f"当前时间: {current_time}")
    VWED.log.sync_info(f"时间戳: {timestamp}")

# 睡眠工具
def sleep_utils():
    # 同步睡眠
    VWED.util.sleep(1)  # 睡眠1秒
    
async def async_sleep_utils():
    # 异步睡眠
    await VWED.util.async_sleep(2)  # 异步睡眠2秒

# UUID生成
def generate_uuid():
    unique_id = VWED.util.uuid()
    VWED.log.sync_info(f"生成的UUID: {unique_id}")
    return unique_id

6. VWED任务系统集成

6.1 在任务中调用脚本函数

功能说明: VWED任务系统可以调用运行中脚本注册的函数。

任务块配置示例:

{
    "block_type": "script",
    "execution_mode": "function_call",
    "function_name": "calculate",
    "function_args": {
        "a": 10,
        "b": 20
    },
    "timeout": 5000,
    "retry_count": 1
}

执行结果示例:

{
    "success": true,
    "result": {
        "data": 30,
        "execution_time_ms": 15
    },
    "message": "脚本函数执行成功"
}

6.2 获取可用脚本函数

接口地址: GET /api/script/integration/functions

功能说明: 获取当前可用的脚本函数列表，供任务编辑器使用。

查询参数:

tags (可选): 标签筛选，多个标签用逗号分隔

响应示例:

{
    "success": true,
    "data": [
        {
            "function_name": "calculate",
            "script_id": "main.py_1726059000000_abc12345",
            "description": "计算函数",
            "parameters": [
                {
                    "name": "a",
                    "type": "number",
                    "required": true,
                    "description": "第一个数字"
                },
                {
                    "name": "b", 
                    "type": "number",
                    "required": true,
                    "description": "第二个数字"
                }
            ],
            "return_schema": {
                "type": "object",
                "properties": {
                    "result": {"type": "number"}
                }
            },
            "is_async": false,
            "tags": ["math", "calculation"],
            "is_running": true,
            "stats": {
                "call_count": 10,
                "success_count": 9,
                "error_count": 1,
                "average_execution_time_ms": 23
            }
        }
    ]
}

7. 脚本示例

7.1 完整脚本示例

# main.py - 完整的脚本示例

def boot():
    """脚本启动函数，注册服务"""
    VWED.log.sync_info("脚本启动中...")
    
    # 注册API接口
    setup_apis()
    
    # 注册自定义函数
    setup_functions()
    
    # 设置事件监听器
    setup_events()
    
    # 设置定时任务
    setup_timers()
    
    VWED.log.sync_info("脚本服务注册完成")

def setup_apis():
    """设置API接口"""
    
    @VWED.api.get("/hello", description="问候接口")
    def hello(request_data):
        name = request_data["query_params"].get("name", "World")
        return {"message": f"Hello, {name}!"}
    
    @VWED.api.post("/process", description="数据处理接口")
    def process_data(request_data):
        data = request_data["body"]
        processed_count = len(data) if isinstance(data, list) else 1
        
        # 记录处理日志
        VWED.log.sync_info(f"处理数据: {processed_count} 项")
        
        return {
            "processed": True, 
            "count": processed_count,
            "timestamp": VWED.util.now()
        }

def setup_functions():
    """设置自定义函数"""
    
    @VWED.function.register("calculate_sum", description="计算数组和")
    def calculate_sum(args):
        numbers = args.get("numbers", [])
        total = sum(numbers)
        VWED.log.sync_info(f"计算和: {numbers} = {total}")
        return {"sum": total, "count": len(numbers)}
    
    @VWED.function.register("async_task", description="异步任务")
    async def async_task(args):
        task_name = args.get("task_name", "unknown")
        await VWED.log.info(f"开始异步任务: {task_name}")
        
        # 模拟异步处理
        await VWED.util.async_sleep(1)
        
        await VWED.log.info(f"异步任务完成: {task_name}")
        return {
            "completed": True, 
            "task_id": VWED.util.uuid(),
            "task_name": task_name
        }
    
    @VWED.function.register(
        "data_validator", 
        description="数据验证器",
        parameters=[
            {"name": "data", "type": "object", "required": True},
            {"name": "rules", "type": "array", "required": False}
        ],
        tags=["validation", "data"]
    )
    def validate_data(args):
        data = args.get("data", {})
        rules = args.get("rules", ["required"])
        
        errors = []
        if "required" in rules and not data:
            errors.append("数据不能为空")
        
        is_valid = len(errors) == 0
        VWED.log.sync_info(f"数据验证结果: {'通过' if is_valid else '失败'}")
        
        return {
            "is_valid": is_valid,
            "errors": errors,
            "data_size": len(str(data))
        }

def setup_events():
    """设置事件监听器"""
    
    @VWED.event.listen("task_completed")
    def on_task_completed(event_data):
        VWED.log.sync_info(f"任务完成通知: {event_data.get('task_id', 'unknown')}")
        
        # 存储完成任务统计
        completed_count = VWED.data.get("completed_tasks", 0)
        VWED.data.set("completed_tasks", completed_count + 1)
    
    @VWED.event.listen("system_error", priority=0)  # 高优先级
    def on_system_error(event_data):
        error_msg = event_data.get("error", "未知错误")
        VWED.log.sync_error(f"系统错误: {error_msg}")
        
        # 触发告警事件
        asyncio.create_task(VWED.event.emit("alert_required", {
            "level": "error",
            "message": error_msg,
            "source": "script_monitor"
        }))

def setup_timers():
    """设置定时任务"""
    
    @VWED.timer.interval(60)  # 每分钟执行
    def monitor_system():
        # 检查系统状态
        task_count = VWED.data.get("completed_tasks", 0)
        VWED.log.sync_info(f"系统监控 - 已完成任务数: {task_count}")
        
        # 每10个任务清理一次数据
        if task_count > 0 and task_count % 10 == 0:
            VWED.data.set("last_cleanup", VWED.util.now())
    
    @VWED.timer.once(delay=10)  # 10秒后执行一次
    def initialization_check():
        VWED.log.sync_info("初始化检查完成")
        VWED.data.set("initialized", True)
    
    @VWED.timer.every(300)  # 每5分钟
    def heartbeat():
        # 发送心跳事件
        asyncio.create_task(VWED.event.emit("script_heartbeat", {
            "script_id": VWED.get_script_id(),
            "timestamp": VWED.util.now(),
            "status": "healthy"
        }))

# 辅助函数示例
def process_sensor_data(sensor_data):
    """处理传感器数据"""
    try:
        # 数据处理逻辑
        temperature = sensor_data.get("temperature", 0)
        humidity = sensor_data.get("humidity", 0)
        
        # 异常检测
        if temperature > 80:
            VWED.log.sync_warning(f"温度过高: {temperature}°C")
        
        if humidity < 20:
            VWED.log.sync_warning(f"湿度过低: {humidity}%")
        
        # 存储处理结果
        VWED.data.set("last_sensor_data", {
            "temperature": temperature,
            "humidity": humidity,
            "processed_at": VWED.util.now()
        })
        
        return {
            "success": True,
            "processed_data": {
                "temperature": temperature,
                "humidity": humidity
            }
        }
        
    except Exception as e:
        VWED.log.sync_error(f"处理传感器数据失败: {str(e)}")
        return {"success": False, "error": str(e)}

7.2 简单API服务脚本

# api_service.py - 简单API服务示例

def boot():
    """注册API服务"""
    VWED.log.sync_info("API服务启动")
    
    @VWED.api.get("/status", description="服务状态检查")
    def get_status(request_data):
        return {
            "status": "running",
            "timestamp": VWED.util.now(),
            "version": "1.0.0"
        }
    
    @VWED.api.post("/webhook", description="接收Webhook")
    def handle_webhook(request_data):
        webhook_data = request_data["body"]
        
        # 记录webhook数据
        VWED.log.sync_info(f"收到Webhook: {webhook_data.get('event', 'unknown')}")
        
        # 处理不同类型的webhook
        event_type = webhook_data.get("event_type")
        if event_type == "user_created":
            handle_user_created(webhook_data)
        elif event_type == "order_completed":
            handle_order_completed(webhook_data)
        
        return {"received": True, "processed": True}

def handle_user_created(data):
    """处理用户创建事件"""
    user_id = data.get("user_id")
    VWED.log.sync_info(f"新用户创建: {user_id}")
    
    # 发送欢迎事件
    asyncio.create_task(VWED.event.emit("user_welcome", {
        "user_id": user_id,
        "created_at": VWED.util.now()
    }))

def handle_order_completed(data):
    """处理订单完成事件"""
    order_id = data.get("order_id")
    VWED.log.sync_info(f"订单完成: {order_id}")

7.3 数据处理脚本

# data_processor.py - 数据处理脚本示例

def boot():
    """注册数据处理函数"""
    VWED.log.sync_info("数据处理服务启动")
    
    @VWED.function.register("batch_process", description="批量数据处理")
    def batch_process(args):
        data_list = args.get("data_list", [])
        process_type = args.get("process_type", "default")
        
        results = []
        for item in data_list:
            if process_type == "filter":
                if item.get("status") == "active":
                    results.append(item)
            elif process_type == "transform":
                transformed = transform_data_item(item)
                results.append(transformed)
            else:
                results.append(item)
        
        VWED.log.sync_info(f"批量处理完成: {len(data_list)} -> {len(results)}")
        return {"processed_data": results, "original_count": len(data_list)}
    
    @VWED.function.register("data_aggregation", description="数据聚合")
    async def data_aggregation(args):
        data_source = args.get("data_source", "database")
        group_by = args.get("group_by", "category")
        
        # 模拟数据获取
        await VWED.util.async_sleep(0.5)
        
        # 模拟聚合结果
        aggregated_data = {
            "category_a": 100,
            "category_b": 150,
            "category_c": 75
        }
        
        await VWED.log.info(f"数据聚合完成: {data_source} by {group_by}")
        return {"aggregated_data": aggregated_data, "total": sum(aggregated_data.values())}

def transform_data_item(item):
    """转换单个数据项"""
    transformed = {
        "id": item.get("id"),
        "name": item.get("name", "").upper(),
        "processed_at": VWED.util.now(),
        "metadata": {
            "original_keys": list(item.keys()),
            "transformation_version": "1.0"
        }
    }
    return transformed

8. 错误处理和调试

8.1 常见错误码

错误码	说明	解决方案
400	请求参数错误	检查请求参数格式和必填字段
404	资源不存在	检查项目ID、文件ID、脚本ID是否正确
409	资源冲突	项目名或文件路径已存在，脚本已在运行
500	服务器内部错误	查看服务器日志，检查数据库连接
503	服务不可用	脚本服务未运行或系统繁忙

8.2 脚本错误示例

语法错误:

{
    "success": false,
    "error": "脚本加载失败: invalid syntax (<script>, line 5)"
}

函数未注册错误:

{
    "success": false,
    "error": "函数 undefined_function 未注册"
}

脚本未运行错误:

{
    "success": false,
    "error": "脚本 main.py_1726059000000_abc12345 未运行，无法执行函数"
}

boot函数缺失错误:

{
    "success": false,
    "error": "脚本缺少boot()入口函数"
}

8.3 调试技巧

使用日志系统: 在脚本中大量使用 VWED.log 记录调试信息
语法验证: 使用语法验证接口检查脚本语法
WebSocket监控: 通过WebSocket实时查看脚本执行状态
注册中心状态: 查看注册中心状态了解函数和接口注册情况
异常捕获: 在函数中添加try-catch块处理异常

调试脚本示例:

def boot():
    try:
        VWED.log.sync_info("=== 脚本启动调试开始 ===")
        
        # 注册调试函数
        @VWED.function.register("debug_test", description="调试测试函数")
        def debug_test(args):
            try:
                VWED.log.sync_info(f"调试函数收到参数: {args}")
                
                # 参数验证
                if not isinstance(args, dict):
                    raise ValueError("参数必须是字典类型")
                
                # 模拟处理
                result = {"debug": True, "args_keys": list(args.keys())}
                
                VWED.log.sync_info(f"调试函数返回结果: {result}")
                return result
                
            except Exception as e:
                VWED.log.sync_error(f"调试函数执行失败: {str(e)}")
                return {"error": str(e), "debug": True}
        
        VWED.log.sync_info("=== 脚本启动调试完成 ===")
        
    except Exception as e:
        VWED.log.sync_error(f"脚本启动失败: {str(e)}")

9. 性能优化建议

9.1 脚本编写最佳实践

避免阻塞操作: 在主线程中避免长时间阻塞的操作
异步优先: 对于I/O密集型操作，优先使用异步函数
资源清理: 在适当的时候清理不需要的资源
错误处理: 添加完善的异常处理机制
日志适度: 避免过度日志记录影响性能

9.2 系统资源管理

脚本数量: 建议同时运行的脚本数量不超过20个
内存使用: 监控脚本内存使用，避免内存泄漏
CPU使用: 避免CPU密集型操作阻塞系统
数据库连接: 合理使用数据库连接，避免连接泄漏

9.3 监控和告警

性能监控: 通过WebSocket监控脚本执行性能
错误告警: 设置错误率阈值告警机制
资源告警: 监控系统资源使用情况
日志审计: 定期清理和归档日志文件

10. 安全建议

10.1 脚本安全

输入验证: 对所有外部输入进行严格验证
权限控制: 实现细粒度的权限控制机制
代码审查: 对脚本代码进行安全审查
沙箱隔离: 脚本运行在相对隔离的环境中

10.2 API安全

身份认证: 实现强身份认证机制
访问控制: 对API访问进行严格控制
请求验证: 验证API请求的合法性
日志记录: 记录所有API访问日志

10.3 数据安全

敏感数据: 避免在脚本中硬编码敏感信息
数据加密: 对敏感数据进行加密存储
访问日志: 记录数据访问和修改日志
备份恢复: 建立完善的数据备份和恢复机制

本文档详细描述了VWED在线脚本编辑模块的所有接口和功能特性，为开发者提供了完整的开发和集成指南。如有疑问或需要技术支持，请参考相应的接口说明和示例代码。

38 KiB Raw Blame History Unescape Escape

VWED在线脚本编辑模块接口文档

概述

1. 脚本项目管理

1.1 创建脚本项目

1.2 获取项目列表

1.3 获取项目文件列表

2. 脚本文件管理

2.1 创建脚本文件

2.2 获取文件内容

2.3 更新文件内容

2.4 删除文件

2.5 搜索文件

2.6 语法验证

2.7 上传脚本文件

3. 脚本执行管理

3.1 启动脚本服务

3.2 停止脚本服务

3.3 获取运行中的脚本

3.4 执行脚本函数

3.5 获取注册中心状态

4. WebSocket实时通信

4.1 脚本日志WebSocket连接

4.2 客户端消息格式

4.3 服务端消息格式

4.4 获取WebSocket连接状态

4.5 WebSocket测试页面

4.6 测试广播消息

5. VWED统一对象系统

5.1 VWED对象结构

5.2 API注册模块（VWED.api）

5.3 函数注册模块（VWED.function）

5.4 事件系统模块（VWED.event）

5.5 定时任务模块（VWED.timer）

5.6 日志系统模块（VWED.log）

5.7 任务系统集成模块（VWED.task）

5.8 数据存储模块（VWED.data）

5.9 工具函数模块（VWED.util）

6. VWED任务系统集成

6.1 在任务中调用脚本函数

6.2 获取可用脚本函数

7. 脚本示例

7.1 完整脚本示例

7.2 简单API服务脚本

7.3 数据处理脚本

8. 错误处理和调试

8.1 常见错误码

8.2 脚本错误示例

8.3 调试技巧

9. 性能优化建议

9.1 脚本编写最佳实践

9.2 系统资源管理

9.3 监控和告警

10. 安全建议

10.1 脚本安全

10.2 API安全

10.3 数据安全

38 KiB

Raw Blame History