# vScript

**Repository Path**: cpsoft13/v-script

## Basic Information

- **Project Name**: vScript
- **Description**: 基于v-table的可视化脚本编辑器，自动生成lua语言脚本操作v-table
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# v-script

Lua 自动化可视化脚本编辑器与执行引擎 —— 可视化模型 ↔ Lua 双向桥接，沙箱化安全运行时。

## 概述

v-script 是一个 Rust 库，提供了一套完整的可视化自动化脚本系统。它支持通过节点图（流程图）的方式设计自动化脚本，并将其转换为 Lua 5.4 代码在受限沙箱环境中安全执行，同时也支持将已有的 Lua 脚本反向解析为可视化流程图。

### 核心能力

- **可视化编辑**：基于 React Flow 的节点图编辑器，支持触发、条件判断、循环、增删改查等多种节点类型
- **双向转换**：可视化模型生成 Lua 代码，Lua 代码反向解析为可视化模型，保证往返一致性
- **安全沙箱**：限制内存（8MB）、超时（30s）、移除危险全局函数、禁止自定义函数，确保脚本安全执行
- **权限控制**：基于角色的访问控制（Viewer/Editor/Admin/Owner），读写操作分别校验权限
- **紧耦合 v-table**：直接通过 v-table 的 `StorageBackend` 操作 `record` 表，无需中间抽象层

## 架构

```
[宿主应用]
     |
     | 提供 v-table StorageBackend
     v
+-------------------+     +---------------------+     +-------------------+
|  LuaSandbox       | --> |  api (ctx 表)       | --> |  v-table          |
|  (受限 Lua 5.4    |     |  (权限校验 + 原始    |     |  StorageBackend   |
|   运行时)          |     |   SQL 操作)          |     |  (record 表 CRUD) |
+-------------------+     +---------------------+     +-------------------+
     |                          |
     | 执行                      | 调用
     v                          v
+---------------------------+
|  生成的 Lua 脚本           |
|  (return function(ctx)    |
|     ... end)              |
+---------------------------+
     ^
     |
+---------------------------+
|  代码生成（双向）          |
|  - generators.rs          |
|  - parser.rs              |
|  - types.rs               |
+---------------------------+
     ^
     |
+---------------------------+
|  可视化模型 (V1/V2)        |
|  (React Flow JSON)        |
+---------------------------+
```

### 数据流

- **正向（设计 → 执行）**：用户在 UI 中创建可视化流程图 → `generate_lua_from_graph()` 生成 Lua 代码 → `LuaSandbox::execute()` 在沙箱中执行
- **反向（代码 → 可视化）**：已有 Lua 脚本 → `parse_lua_to_graph()` 解析为可视化模型 → UI 渲染流程图

## 快速开始

### 添加依赖

```toml
[dependencies]
v-script = "0.1.0"
```

### 设置 v-table 后端

v-script 直接使用 [v-table](https://gitee.com/cpsoft13/v-table) 的 `StorageBackend` 操作数据，
宿主应用需先创建 v-table 后端实例：

```rust
use std::sync::Arc;
use v_table::connection::{ConnectionConfig, create_backend};

// 创建 DuckDB 后端（内存或文件）
let config = ConnectionConfig::duckdb_in_memory();
// 或 PostgreSQL: ConnectionConfig::postgres_url("postgres://...")
let backend: Arc<dyn v_table::types::StorageBackend> =
    Arc::from(create_backend(&config).await.unwrap());

// 初始化表结构
backend.run_migrations().await.unwrap();
```

### 执行脚本

```rust
use v_script::{LuaSandbox, ExecutionContext};
use std::sync::Arc;

let sandbox = LuaSandbox::new();

let ctx = ExecutionContext {
    backend: backend.clone(), // v-table StorageBackend
    base_id: "base_001".into(),
    operator_id: "user_001".into(),
    operator_role: Some("editor".into()), // 宿主预先查好的角色
    trigger_type: "record_created".into(),
    source_table_id: Some("table_001".into()),
    source_record_id: Some("rec_001".into()),
    table_fields: vec![],
    field_changes: None,
};

let script = r#"
    return function(ctx)
        local record = ctx:get_record(ctx.trigger_record)
        if record and record.fields.status == "pending" then
            ctx:update_record(ctx.trigger_record, { assignee = "user_002" })
            ctx:log("已分配任务")
        end
    end
"#;

let result = sandbox.execute(script, ctx).await;
assert!(result.success);
```

### 代码生成

```rust
use v_script::codegen::{VisualModelV2, generate_lua_from_graph, parse_lua_to_graph};

// 可视化模型 → Lua
let model = VisualModelV2 { /* 从编辑器获取 */ };
let lua_code = generate_lua_from_graph(&model).unwrap();

// Lua → 可视化模型（反向解析）
let parsed_model = parse_lua_to_graph(&lua_code).unwrap();
```

## ctx API 参考

脚本通过 `ctx` 参数与宿主应用交互，所有方法均经过权限校验。

| 方法 | 所需权限 | 说明 |
|---|---|---|
| `ctx:get_record(record_id)` | Viewer+ | 根据 ID 获取记录，返回 table 或 nil |
| `ctx:update_record(record_id, values)` | Editor+ | 更新记录的字段值 |
| `ctx:create_record(table_id, values)` | Editor+ | 创建新记录，返回字符串 ID |
| `ctx:delete_record(record_id)` | Editor+ | 软删除记录 |
| `ctx:list_records(table_id, limit?)` | Viewer+ | 列出记录，limit 默认 100，最大 1000 |
| `ctx:send_webhook(url, body)` | 无 | 发送 JSON POST 请求，10 秒超时 |
| `ctx:log(message)` | 无 | 输出日志（通过 tracing） |
| `ctx:get_field_changes()` | 无 | 返回触发变更的字段列表 |

## 可视化模型

### V2 节点类型（React Flow 兼容）

| 节点类型 | 说明 |
|---|---|
| `start` | 入口节点 |
| `end` | 出口节点 |
| `trigger` | 触发器（事件类型、字段、cron 表达式） |
| `condition` | 条件判断，支持 if/else 分支 |
| `action` | 动作节点（webhook、更新记录、创建记录、发送邮件、行内 Lua） |
| `loop` | 循环节点（for/while/repeat 三种模式） |
| `find_records` | 查询记录，支持 AND 条件组合 |
| `create_record` | 创建记录，字段值支持 Lua 表达式 |
| `copy_records` | 复制记录，支持字段映射和关联重映射 |
| `compute` | 计算节点 |

### 条件表达式

支持层级条件树（AND/OR 组合）和以下比较运算符：

- `equals` / `not_equals`
- `contains` / `not_contains`
- `greater_than` / `less_than`
- `greater_than_or_equal` / `less_than_or_equal`
- `is_empty` / `is_not_empty`

## 安全模型

- **全局函数限制**：移除 `io`、`os`、`require`、`package`、`loadfile`、`dofile`、`debug`、`ffi` 等危险全局函数
- **元表保护**：禁用 `getmetatable`、`setmetatable`、`rawget`、`rawset` 等
- **禁止自定义函数**：脚本中不允许使用 `function` 关键字定义函数，仅允许 `return function(ctx)` 包裹入口
- **内存限制**：默认 8MB Lua 内存上限
- **执行超时**：默认 30 秒超时，防止死循环
- **权限校验**：所有数据写操作需 Editor+ 权限，读操作需 Viewer+ 权限

## 许可证

MIT

## 仓库

<https://gitee.com/cpsoft13/v-script>