# VistaS

**Repository Path**: losyn/VistaS

## Basic Information

- **Project Name**: VistaS
- **Description**: **VistaS** 是一个现代化的**跨平台桌面应用开发框架**，基于 **Luvit 运行时**，提供：

- 🖥️ **原生 WebView 窗口** - 跨平台桌面应用界面（macOS/Windows/Linux）
- 🗄️ **嵌入式数据库引擎** - 基于 CSV 的事务性数据库（CsvDB）
- 🔧 **企业级工具库** - 平台检测、异步编程、日志系统、协程池等
- **Primary Language**: Lua
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VistaS 🚀

<p align="center">
  <strong>企业级 Lua 桌面应用开发框架</strong><br>
  <em>Luvit Runtime + WebView Native UI + Embedded Database</em>
</p>

<p align="center">
  <a href="#-快速开始"><b>快速开始</b></a> ·
  <a href="#-项目特性"><b>特性</b></a> ·
  <a href="#-目录结构"><b>结构</b></a> ·
  <a href="#-构建部署"><b>构建</b></a> ·
  <a href="docs/README.md"><b>📚 完整文档</b></a>
</p>

---

## ✨ 项目简介

**Vistas** 是一个现代化的**跨平台桌面应用开发框架**，基于 **Luvit 运行时**，提供：

- 🖥️ **原生 WebView 窗口** - 跨平台桌面应用界面（macOS/Windows/Linux）
- 🗄️ **嵌入式数据库引擎** - 基于 CSV 的事务性数据库（CsvDB）
- 🔧 **企业级工具库** - 平台检测、异步编程、日志系统、协程池等

### 📊 核心指标

| 指标 | 数值 |
|------|------|
| **版本** | v1.0.0 (stable) |
| **核心模块** | 3 个（WebView / Database / Commons）|
| **源码总量** | ~5,001 行（Database: 1663 + WebView: 1249 + Commons: 1932 + 入口: 157）|
| **测试代码** | 17,751 行（Database: 5786 + WebView: 6078 + Commons: 5887）|
| **测试套件** | 19 个（Database: 5 + WebView: 6 + Commons: 8）|
| **测试通过率** | **100%** ✅ 零 BUG |
| **代码示例** | 64 个完整可运行示例 |
| **文档规模** | ~8,944 行（含 API / 最佳实践 / 性能优化 / Luvit 参考）|
| **生产就绪** | ✅ 是（稳定版）|

---

## 🎯 核心模块

### 🌐 [WebView](docs/webview/README.md) - 原生窗口与 IPC 通信

> 跨平台原生窗口管理器，支持 JavaScript ↔ Lua 双向 IPC 通信

```lua
local WebView = require('libras.webview')

WebView
  .url("https://example.com")
  .title("My App")
  .size(1280, 720)

while WebView.run() do end
```

**核心能力**:
- 🪟 窗口管理（创建/配置/控制）
- 🛠️ 工具栏系统（按钮/托盘/菜单）
- 📡 IPC 双向通信（JS ↔ Lua）
- 🌉 Bridge JS（前端调用后端）

📘 [查看完整文档 →](docs/webview/WEBVIEW_API.md)

---

### 🗄️ [Database (CsvDB)](docs/database/README.md) - 嵌入式数据库引擎

> 基于 CSV 文件的企业级数据库，支持事务、并发控制、多级缓存

```lua
local Database = require('libras.database')
local db = Database.connect('./data/myapp')

local users = db:createCollection('users', {
  columns = {
    id = { type = 'number', primary_key = true },
    name = { type = 'string', required = true }
  }
})

local alice = users:insert({ name = 'Alice' })
print(users:byId(alice.id).name)
db:close()
```

**核心能力**:
- 📊 完整 CRUD（增删改查/批量操作/分页）
- 🔒 ACID 事务（快照隔离/WAL持久化）
- ⚡ 多级缓存（L1/L2/BTree索引）
- 🔐 安全防护（输入验证/CSV注入防护）

📘 [查看完整文档 →](docs/database/DATABASE_API.md)

---

### 🔧 [Commons](docs/common/README.md) - 企业级通用工具库

> 提供平台检测、JSON处理、异步编程、协程池、进程间通信等基础能力（9 个子模块）

```lua
local Platf = require('libras.commons.platf')
local UUID = require('libras.commons.uuid')
local JSON = require('libras.commons.json')
local Log = require('libras.commons.log')
local Maps = require('libras.commons.maps')    -- 🆕 并发映射
local Pipe = require('libras.commons.pipe')     -- 🆕 命名管道

print(Platf.getOS())           -- "macos"
local id = UUID.v4()           -- "a1b2c3d4-..."
Log.info("App started", { ver = "1.0" })

-- 跨进程共享内存（C FFI）
local map = Maps.createOrGet("my_map")
map:put("key", "value")
print(map:get("key"))          -- "value"
map:destroy()

-- 命名管道 IPC
Pipe.server("my_pipe", function(msg)
  print("收到消息: " .. msg)
end)
```

**核心能力**:
- 🔧 平台检测（OS/Arch/桌面环境）
- 🆔 UUID 生成（RFC 4122 v4）
- ⚡ JSON 引擎（高性能+LRU缓存）
- 📝 日志系统（异步IO/结构化/脱敏/dev-prd双环境配置）
- 🔄 Promise/Deferred（链式调用/自动重试）
- 🎯 协程池（自动扩缩容/负载均衡）
- 🗺️ **并发映射 Maps** (🆕 C FFI 共享内存、跨进程键值存储、FIFO队列)
- 🔀 **命名管道 Pipe** (🆕 UV IPC通信、Server/Client模式、自动重连)
- 🌐 WebSocket 客户端（心跳保活/指数退避）

📘 [查看完整文档 →](docs/common/COMMONS_API.md)

---

## 🔧 技术栈：Luvit 运行时

> **Vistas** 基于 [Luvit](https://luvit.io) 构建 - 一个高性能的 Lua 异步 I/O 运行时

### 🤔 什么是 Luvit？

[Luvit](https://luvit.io) 是一个基于 **LuaJIT** 和 **LibUV** 的异步 I/O 运行时，类似于 Node.js，但使用 Lua 语言。

**核心特性**:
- ⚡ **高性能**: LuaJIT JIT 编译，接近 C 语言速度
- 🔄 **异步非阻塞**: 基于 LibUV 事件循环（与 Node.js 相同）
- 📦 **轻量级**: 单一二进制文件，无依赖（~10MB）
- 🔒 **安全**: Lua 沙箱机制，适合嵌入式场景

**为什么选择 Luvit（而不是 Node.js）?**
- ✅ 更小的内存占用（~20MB vs ~100MB）
- ✅ 更快的启动时间（~50ms vs ~500ms）
- ✅ 更简单的部署（单文件 vs node_modules）
- ✅ Lua 语法简洁，学习曲线平缓
- ✅ 与 C 库的 FFI 集成更自然

---

### 📥 安装 Luvit（3 种方式）

#### 方式 1: 一键脚本（推荐 ⭐）

**macOS / Linux / FreeBSD:**
```bash
curl -L https://github.com/luvit/lit/raw/master/get-lit.sh | sh
```

**Windows (PowerShell):**
```powershell
PowerShell -NoProfile -ExecutionPolicy unrestricted -Command `
  "[Net.ServicePointManager]::SecurityProtocol = 'Tls12'; `
   iex ((new-object net.webclient).DownloadString('https://github.com/luvit/lit/raw/master/get-lit.ps1'))"
```

> **说明**: 这会自动下载并编译 `lit`（包管理器）和 `luvit`（运行时）

#### 方式 2: 验证安装
```bash
luvit --version              # 应显示 ≥ 2.15.0
lit --version                # 应显示最新版
luvit                        # 进入 REPL 交互模式
> print("Hello Luvit!")     # 测试输出
```

#### 方式 3: 从源码编译（高级用户）
```bash
# 需要 CMake + C 编译器 (GCC/Clang/MSVC)
git clone --recursive https://github.com/luvit/luvi.git
cd luvi && make regular

git clone --recursive https://github.com/luvit/lit.git
./build/luvi lit-src -- make lit-src
```

📘 [查看完整安装文档 →](https://luvit.io/install.html)

---

### 🧠 Luvit 核心概念速查（5分钟掌握）

#### 1️⃣ 模块系统 (require)
```lua
-- 加载内置模块
local fs = require('fs')
local path = require('path')

-- 加载项目模块（相对路径）
local myModule = require('./my-module')  -- 自动加 .lua 后缀

-- 加载 libras 框架模块
local WebView = require('libras.webview')
```

#### 2️⃣ 异步回调风格
```lua
local fs = require('fs')

-- 所有 I/O 操作都是异步的（最后一个参数是回调）
fs.readFile('/etc/hosts', function(err, data)
  if err then
    return print("Error: " .. err.message)
  end
  print(data)  -- 文件内容
end)

print("这行先执行!")  -- 异步特性：这行先打印
```

#### 3️⃣ 事件发射器 (Emitter)
```lua
local Emitter = require('core').Emitter

local emitter = Emitter:new()

emitter:on('data', function(data)
  print("收到数据: " .. data)
end)

emitter:emit('data', 'Hello World!')
```

📘 [查看 Luvit 完整 API 文档 →](https://luvit.io/api/) · 
[查看 API 速查手册 →](docs/luvit-refs/quick-ref.md)

---

### 🔗 Vistas × Luvit 模块映射表

以下表格列出了 **Vistas 框架内部使用的 Luvit 核心模块**，以及它们在项目中的用途：

| Luvit 模块 | 用途 | 使用位置 | 官方文档 |
|-----------|------|---------|---------|
| **[core](https://luvit.io/api/core.html)** | 面向对象/事件系统 | libras/commons/log.lua, libras/commons/coros.lua | [→ 查看](https://luvit.io/api/core.html) |
| **[fs](https://luvit.io/api/fs.html)** | 文件读写/目录操作 | main.lua, preload.lua | [→ 查看](https://luvit.io/api/fs.html) |
| **[path](https://luvit.io/api/path.html)** | 路径拼接/解析 | main.lua, setup-dev.lua | [→ 查看](https://luvit.io/api/path.html) |
| **[process](https://luvit.io/api/process.html)** | 进程信息/命令行参数 | setup-dev.lua | [→ 查看](https://luvit.io/api/process.html) |
| **[json](https://luvit.io/api/json.html)** | JSON 序列化/反序列化 | preload.lua, libras/commons/json.lua | [→ 查看](https://luvit.io/api/json.html) |
| **[utils](https://luvit.io/api/utils.html)** | 工具函数（bind/inherits） | libras/commons/*.lua | [→ 查看](https://luvit.io/api/utils.html) |

> 💡 **提示**: 点击"查看"链接可直接跳转到 Luvit 官方 API 文档  
> 📘 **深入阅读**: [Luvit 快速参考手册](docs/luvit-refs/quick-ref.md) （提取常用 API 精华）

---

## 🚀 快速开始（3步启动）

### 📋 前置要求

> **Luvit 安装**: 见上方 [🔧 技术栈：Luvit 运行时](#-技术栈luvit-运行时) 章节

| 依赖 | 版本 | 用途 |
|------|------|------|
| **[Luvit](https://luvit.io)** | ≥ 2.15.0 | Lua 运行时（[安装指南](#-安装-luvit3-种方式)）|
| **Lit** | 最新版 | Lua 包管理器（随 Luvit 一起安装）|
| **C 编译器** | Clang/GCC/MSVC | 编译原生 WebView 库 |

#### C 编译器安装

**macOS:**
```bash
xcode-select --install
```

**Windows:**
```bash
# 安装 Visual Studio Build Tools
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
```

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get install build-essential libgtk-3-dev libwebkit2gtk-4.0-dev
```

---

### 🔨 构建命令

使用 **Makefile** 统一管理所有构建流程：

```bash
# 查看帮助
make help

# 开发模式（检查环境 + 启动应用）
make dev

# 生产构建（编译 + 打包安装程序）
make prd                  # 自动检测平台并打包
make prd pkg=dmg          # 强制 DMG 格式 (macOS)
make prd pkg=deb          # 强制 DEB 格式 (Linux)
make prd pkg=zip          # 强制 ZIP 压缩包 (Windows)

# 编译原生 WebView 库
make wvc

# 清理构建产物
make prd clean            # 只清理（不编译）
make wvc clean            # 清理原生库
```

#### 高级选项

```bash
# 显示详细构建输出
make prd detail

# 组合使用
make prd clean pkg=dmg        # 清理后重建 DMG
```

📘 [查看完整的 Makefile 文档 →](docs/common/COMMONS_BEST.md#构建系统)

---

### 💻 第一个应用（30秒）

#### 1️⃣ 克隆并初始化

```bash
git clone https://gitee.com/losyn/vistas.git
cd vistas

# 安装依赖 & 编译原生库
make wvc
```

#### 2️⃣ 启动开发模式

```bash
make dev
# 或直接运行：
# luvit setup-dev.lua
```

#### 3️⃣ 修改 `package.lua` 配置

```lua
return {
  name = "MyApp",
  version = "1.0.0",
  
  dev = {
    url = "http://localhost:3000",   -- 开发服务器
  },
  
  prd = {
    url = "https://app.example.com", -- 生产地址
  }
}
```

#### 4️⃣ 构建生产版本

```bash
make prd pkg=dmg    # macOS: 生成 DMG 安装包
make prd pkg=deb    # Linux: 生成 DEB 包
make prd pkg=zip    # Windows: 生成 ZIP 压缩包
```

输出文件位于 `dist/` 目录。

---

## 📁 项目结构

```
vistas/
├── 📄 main.lua              # Luvit 启动器（包路径配置、模块预加载）
├── 📄 desk.lua              # 🚀 主应用入口（窗口初始化、信号处理、单实例管理）
├── 📄 package.lua           # 应用配置（名称/版本/图标/dev-prd环境URL）
├── 📄 preload.lua           # 依赖预扫描器（deps/目录扫描、preload.txt缓存生成）
│
├── 📁 libras/               # 🔧 核心库源码 (~4,844行)
│   ├── webview/             # 🌐 WebView 模块 (~1,249行)
│   │   ├── init.lua         # 入口封装（链式API: url/title/size/tray/menu）
│   │   ├── version.lua      # 版本管理 (v1.0.0-stable Enterprise)
│   │   ├── libc.lua         # FFI 绑定层
│   │   ├── proxy.lua        # 命令代理 (~364行)
│   │   ├── bridge.lua       # JS Bridge 注入代码 (~197行)
│   │   ├── ipc.lua          # IPC 消息路由器 (~131行)
│   │   └── contxt.lua       # 上下文管理器 (~97行)
│   │
│   ├── database/            # 🗄️ Database 模块 (~1,663行)
│   │   ├── init.lua         # 入口封装
│   │   ├── version.lua      # 版本管理 (v1.0.0-stable Security)
│   │   ├── csvdb.lua        # 核心引擎 CRUD/事务/查询 (~829行)
│   │   ├── utils.lua        # 工具函数 CSV解析/文件操作 (~637行)
│   │   ├── validator.lua    # Schema 验证器 (~132行)
│   │   └── package.lua      # 包元信息
│   │
│   └── commons/             # 🔧 Commons 模块 (~1,932行, 8个子模块)
│       ├── platf.lua        # 平台检测 (61行)
│       ├── uuid.lua         # UUID v4 生成 (58行)
│       ├── json.lua         # JSON 引擎 + LRU 缓存 (353行)
│       ├── log.lua          # 企业级日志系统 (431行)
│       ├── coros.lua        # 协程池调度器 (263行)
│       ├── wsoks.lua        # WebSocket 客户端 (534行)
│       ├── maps.lua         # 🆕 并发映射 C FFI (108行)
│       └── pipe.lua         # 🆕 命名管道 IPC (124行)
│
├── 📁 srcs/entries/          # 📂 应用扩展入口
│   ├── traybar.lua          # 托盘菜单配置（事件处理器 + 中/英双语菜单）
│   └── routers.lua          # IPC 路由注册（请求分发）
│
├── 📁 webview-c/            # C 语言原生库
│   ├── build-wvc.lua        # 跨平台编译脚本
│   ├── webview-api.h        # 公共 API 头文件
│   ├── webview-ipc.c/h      # IPC 实现
│   ├── webview-map.c/h      # 并发映射实现
│   ├── webview-bar.c/h/m    # 工具栏实现
│   ├── webview-osw.c        # Windows (Edge WebView2)
│   ├── webview-osm.c        # macOS (WebKit)
│   └── webview-osz.c        # Linux (WebKitGTK)
│
├── 📁 assets/               # 🎨 应用资源
│   ├── libs/                # 动态链接库 (webview.dyl/dll/wv64loader.dll)
│   ├── icon.png             # 应用图标
│   └── dbs/                 # 数据库存储目录
│
├── 📁 tests/                # 🧪 测试套件 (17,751行, 19个文件)
│   ├── webview/             # 6个测试文件 (~6,078行)
│   ├── database/            # 5个测试文件 (~5,786行)
│   └── commons/             # 8个测试文件 (~5,887行)
│
├── 📁 docs/                 # 📚 项目文档中心 (~8,944行)
│   ├── README.md            # ← 文档总览（推荐从这里开始）
│   ├── webview/             # WebView 文档集 (~3,878行)
│   ├── database/            # Database 文档集 (~1,614行)
│   ├── common/              # Commons 文档集 (~1,655行)
│   └── luvit-refs/          # Luvit 参考文档 (~1,224行)
│
├── 📄 Makefile              # 🔨 构建系统入口
├── 📄 setup-prd.lua         # 🔧 生产构建脚本
├── 📄 setup-dev.lua         # 🔧 开发启动脚本
└── 📄 .gitignore            # Git 忽略规则
```

---

## 🏗️ 架构设计

### 技术栈层次

```
┌─────────────────────────────────────────────┐
│              应用层 (Your Code)              │
│              srcs/, desk.lua                 │
├─────────────────────────────────────────────┤
│           框架层 (libras/)                   │
│  ┌─────────┬─────────┬────────────────────┐ │
│  │ WebView │Database │     Commons         │ │
│  │  (UI)   │ (Data)  │ (Utils/Async/Log)  │ │
│  └─────────┴─────────┴────────────────────┘ │
├─────────────────────────────────────────────┤
│         运行时层 (Luvit + FFI)               │
│  ┌─────────────────┬──────────────────────┐ │
│  │ Luvit Runtime   │ webview-c (Native)   │ │
│  │ (LuaJIT + LibUV)│ (.dyl/.so/.dll)   │ │
│  └─────────────────┴──────────────────────┘ │
├─────────────────────────────────────────────┤
│            操作系统层 (OS)                    │
│       macOS / Windows / Linux                │
└─────────────────────────────────────────────┘
```

### 数据流架构

```
用户交互 (WebView)
    ↓
JavaScript (前端)
    ↓ ↕ IPC Bridge
Lua 后端 (libras.webview)
    ↓
业务逻辑 (desk.lua / srcs/)
    ↓
数据存储 (libras.database)
    ↓
CSV 文件 (assets/storage.db)
```

📘 [查看详细架构设计 →](docs/webview/WEBVIEW_BEST.md)

---

## 📊 平台支持

| 平台 | WebView 引擎 | 包格式 | 支持状态 |
|------|-------------|--------|---------|
| **macOS** | WebKit (WKWebView) | `.dmg` | ✅ 完全支持 |
| **Windows** | MS Edge (WebView2) | `.zip` | ✅ 完全支持 |
| **Linux (Debian/Ubuntu)** | WebKitGTK (WebKit2) | `.deb` | ✅ 推荐 |
| **Linux (其他发行版)** | WebKitGTK (WebKit2) | `.AppImage` | ✅ 支持 |

### 功能对比矩阵

| 功能 | macOS | Windows | Linux |
|------|-------|---------|-------|
| 原生窗口 | ✅ | ✅ | ✅ |
| 全屏/最小化/最大化 | ✅ | ✅ | ✅ |
| 自定义工具栏 | ✅ | ✅ | ⚠️ 部分支持 |
| 系统托盘 | ✅ | ✅ | ⚠️ 需 GTK3 |
| Dock 徽章 | ✅ | ✅ (任务栏闪烁) | ❌ |
| IPC 通信 | ✅ | ✅ | ✅ |
| 并发映射 (Maps) | ✅ | ✅ | ✅ |
| 命名管道 (Pipe) | ✅ | ✅ | ✅ |
| 开发者工具 | ✅ | ✅ | ✅ |

> **注**:
> - macOS/Windows 已实现**功能对等**
> - Linux 受限于 WebKitGTK 版本，部分高级 UI 功能需 GTK 3.x+
> - Maps/Pipe 基于 LibUV，三平台原生支持

---

## 🧪 测试与质量保证

### 测试覆盖率

| 模块 | 套件数 | 测试代码 | 通过率 | 状态 |
|------|--------|---------|--------|------|
| **Database** | 5 | ~5,786 行 | 100% | ✅ 全部通过 |
| **WebView** | 6 | ~6,078 行 | 100% | ✅ 全部通过 |
| **Commons** | 8 | ~5,887 行 | 100% | ✅ 全部通过 |
| **总计** | **19** | **17,751 行** | **100%** | ✅ **零 BUG** |

### 运行测试

```bash
# 运行所有测试
cd tests/commons && luvit run_00_tests.lua
cd tests/database && luvit run_00_tests.lua
cd tests/webview && luvit run_00_tests.lua
```

📘 [查看测试最佳实践 →](docs/database/DATABASE_BEST.md#测试策略)

---

## 📚 文档导航

### 📍 推荐阅读路径

#### 新手入门（~30分钟）
```
[本 README] → [快速开始] → [Hello World 示例]
     ↓
[Commons 文档] → [WebView 文档]
```

#### 进阶开发（~2小时）
```
[API 参考] → [最佳实践] → [IPC 通信详解]
     ↓
[性能优化指南] → [架构设计模式]
```

#### 深度定制（~5小时）
```
[C 语言源码] → [FFI 绑定原理] → [自定义扩展]
     ↓
[数据库引擎实现] → [并发控制机制]
```

### 📖 文档索引

| 文档 | 内容 | 行数 | 适用人群 |
|------|------|------|---------|
| **[📚 文档总览](docs/README.md)** | 项目全景、学习路径、模块对比 | ~700+ | 所有人 |
| **[🌐 WebView API](docs/webview/WEBVIEW_API.md)** | API参考 & 11个示例 | ~1,892 | WebView 开发者 |
| **[🌐 WebView 最佳实践](docs/webview/WEBVIEW_BEST.md)** | 架构设计 & 模式 | ~1,257 | 架构师 |
| **[🌐 WebView IPC](docs/webview/WEBVIEW_IPC.md)** | 通信协议详解 | ~1,474 | 前后端联调 |
| **[🗄️ Database API](docs/database/DATABASE_API.md)** | API参考 & 11个示例 | ~1,880 | 数据库使用者 |
| **[🗄️ Database 最佳实践](docs/database/DATABASE_BEST.md)** | 性能优化 & 设计 | ~1,320 | DBA/架构师 |
| **[🗄️ Database 索引](docs/database/DATABASE_IDX.md)** | 错误码表 & 速查 | ~600 | 问题排查 |
| **[🔧 Commons API](docs/common/COMMONS_API.md)** | 93个函数文档 (含Maps/Pipe) | ~2,000 | 所有开发者 |
| **[🔧 Commons 最佳实践](docs/common/COMMONS_BEST.md)** | 42个设计模式 | ~1,800 | 高级开发 |
| **[🔧 Commons 性能](docs/common/COMMONS_PERF.md)** | 基准测试 & 调优 | ~2,200 | 性能工程师 |
| **[🔧 C 库文档](webview-c/README.md)** | 原生 API & 编译指南 | ~800+ | 系统程序员 |
| **[📘 Luvit 参考](docs/luvit-refs/quick-ref.md)** | Luvit API 速查手册 | ~623 | Luvit 开发者 |

---

## 🔄 版本历史

### v1.0.0 (2026-05-13) - 初始稳定版

✨ **新功能**:
- 🌐 WebView 原生窗口框架（跨平台）
- 🗄️ CsvDB 嵌入式数据库引擎
- 🔧 Commons 企业级工具库
- 📡 IPC 双向通信系统
- 🔨 统一构建系统（Makefile）

🔧 **改进**:
- ✅ 100% 测试覆盖率（17,751 行测试代码 / 19 个套件）
- ✅ 完整的 API 文档（~8,944 行）
- ✅ 64 个可运行代码示例
- ✅ 跨平台支持（macOS/Windows/Linux）
- ✅ macOS/Windows 功能对等实现
- ✅ 新增 Maps/Pipe IPC 模块

🐛 **修复**:
- 无已知功能性 BUG

---

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

1. **Fork** 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 **Pull Request**

### 代码规范

- 遵循现有代码风格（Lua 5.1/Luvit 规范）
- 为新功能添加测试用例（保持 100% 通过率）
- 更新相关文档（API / 示例 / README）
- 遵循 [Commit Message 规范](https://www.conventionalcommits.org/)

---

## 🆘 故障排除

### 常见问题 & 解决方案

#### Q1: `luvit: command not found`
**原因**: Luvit 未安装或不在 PATH 中

**解决方案**:
```bash
# 重新安装（macOS/Linux）
curl -L https://github.com/luvit/lit/raw/master/get-lit.sh | sh

# 或手动添加到 PATH
export PATH=$PATH:/usr/local/bin  # 或你的安装路径
```

#### Q2: `make wvc` 编译失败
**原因**: 缺少 C 编译器或系统库

**解决方案**:
```bash
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential libgtk-3-dev libwebkit2gtk-4.0-dev

# Windows
# 安装 Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
```

#### Q3: `require('libras.webview')` 模块找不到
**原因**: 未执行 `make wvc` 或路径错误

**解决方案**:
```bash
# 1. 确保在项目根目录
cd /path/to/vistas

# 2. 编译原生库
make wvc

# 3. 检查 libras/webview/init.lua 是否存在
ls libras/webview/
```

#### Q4: WebView 窗口不显示或闪退
**排查步骤**:
1. **查看日志**: `cat assets/logs/vistas-*.log`
2. **详细模式**: `make dev detail` （显示更多信息）
3. **检查 URL 配置**: 确保 `package.lua` 中的 URL 可访问
4. **平台特定**:
   - macOS: 检查是否允许辅助功能权限
   - Linux: 检查 `DISPLAY` 环境变量
   - Windows: 检查 WebView2 Runtime 是否已安装

#### Q5: 如何调试 Lua 代码？
**方法 1: 打印日志**
```lua
local Log = require('libras.commons.log')
Log.configure({ console = true })
Log.info("变量值:", { x = 123 })
```

**方法 2: REPL 交互调试**
```bash
luvit                    # 进入 REPL
> local WebView = require('libras.webview')
> print(WebView.version())
```

**方法 3: VSCode 调试（需安装 Lua 扩展）**
- 推荐: [Lua Debugger](https://marketplace.visualstudio.com/items?itemName=tomblind.lua-debugger)

---

### 获取帮助

| 渠道 | 说明 |
|------|------|
| 📖 **Luvit 官方文档** | [API 参考](https://luvit.io/api/) · [安装指南](https://luvit.io/install.html) |
| 📘 **Vistas 文档中心** | [docs/README.md](docs/README.md) |
| 📘 **Luvit 速查手册** | [docs/luvit-refs/quick-ref.md](docs/luvit-refs/quick-ref.md) |
| 🐛 **报告 Bug** | [Gitee Issues](https://gitee.com/losyn/vistas/issues) |
| 💡 **功能建议** | [Gitee Issues](https://gitee.com/losyn/vistas/issues) (标注 Feature Request) |

---

## 📄 许可证

本项目采用 **MIT 许可证** - 查看 [LICENSE](LICENSE) 文件了解详情。

---

## 🙏 致谢

- **[Luvit](https://luvit.io)** - 强大的 Lua 运行时
- **[webview](https://github.com/webview/webview)** - 跨平台 WebView C 库
- **[Lit](https://github.com/luvit/lit)** - Lua 编译工具链

---

<div align="center">

### 🚀 开始构建你的下一个桌面应用！

**[📖 查看完整文档](docs/README.md)** · 
**[🌐 WebView 入门](docs/webview/README.md)** · 
**[🗄️ Database 入门](docs/database/README.md)** · 
**[🔧 Commons 入门](docs/common/README.md)**

<br>

<sub>Made with ❤️ by Vistas Team | 
<strong>v1.0.0</strong> | 
Last Updated: 2026-07-13</sub>

</div>