# interlocker4

**Repository Path**: akinggw/interlocker4

## Basic Information

- **Project Name**: interlocker4
- **Description**: Interlocker4（鼹鼠铁路信号控制系统）是一套面向铁路信号领域的综合控制与仿真平台，使用 C++17 和 wxWidgets 3.2 构建。系统将铁路站场的信号控制、脚本配置、网络通信和 AI 智能体辅助融合于一体，既可用于实际铁路信号系统的管理与控制，也可用于培训仿真、教学演示和信号系统研究。
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-07-25
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鼹鼠铁路信号控制系统 (Interlocker4)

## 系统简介

Interlocker4（鼹鼠铁路信号控制系统）是一套面向铁路信号领域的综合控制与仿真平台，使用 C++17 和 wxWidgets 3.2 构建。系统将铁路站场的信号控制、脚本配置、网络通信和 AI 智能体辅助融合于一体，既可用于实际铁路信号系统的管理与控制，也可用于培训仿真、教学演示和信号系统研究。

作为安全关键系统，Interlocker4 在信号控制逻辑、路由条件评估和机车管理等方面严格遵循铁路联锁安全原则，确保进路开放和信号显示的安全性。

## 功能概览

### 1. 信号控制

- **站场图形渲染** — 基于 OpenGL 的站场布局可视化，支持信号灯、道岔、轨道等元素的实时状态显示
- **节点管理** — 信号灯节点、道岔节点、挂载节点的创建、配置和联动控制
- **路由条件评估** — 自动评估信号开放条件，确保进路安全
- **机车管理** — 机车的添加、监控、位置追踪和状态控制
- **主备切换** — 主备机切换功能，保障系统冗余可靠性

### 2. 脚本系统

- **Lua 脚本引擎** — 使用 Lua 5.4.7 作为站场配置和系统初始化的脚本语言
- **内置脚本编辑器** — 集成代码编辑器，支持语法高亮和自动补全（基于 Lua 语法分析器）
- **脚本管理** — 加载、保存、热重载脚本文件，支持文件变化监控与自动刷新
- **LuaBridge 绑定** — C++ 对象与 Lua 的双向交互，支持 STL 容器

### 3. AI 智能体 (libagentcore)

- **双后端模型管理** — 支持本地 GGUF 模型（llama.cpp）和 HTTP API（OpenAI 兼容接口）运行时切换
- **多智能体架构** — PlannerAgent（规划）、WorkerAgent（执行）、PlanValidatorAgent（计划验证）、ResultValidator（结果验证）
- **任务状态机** — PENDING_PLAN → PLANNING → PENDING_VALIDATE → EXECUTING → VALIDATING_RESULT → COMPLETED/FAILED/CANCELLED
- **向量记忆系统** — 基于 SQLite + sqlite-vector 的语义记忆搜索，支持余弦距离排序和降级关键词搜索
- **工具调用** — 智能体可调用外部工具（通过宿主程序注册的 Lua 脚本执行器）
- **线程池调度** — 多任务并行执行，支持运行时模型后端切换
- **默认模型** — Qwen3.5-4B-UD-Q4_K_XL.gguf，支持 MTP（Multi-Token Prediction）

### 4. 网络通信

- **TCP 客户端/服务器** — 自定义消息协议（消息头 + FastLZ 压缩载荷 + CRC 校验），支持断线重连和心跳检测
- **UDP 管理器** — 机车数据同步，支持 KCP 可靠传输协议
- **WebSocket 服务器** — 远程调试与实时通信，支持握手、数据帧解析、心跳超时管理
- **HTTP 服务器** — 调试接口，支持超时连接管理
- **数据库代理** — DBOperator 支持本地 SQLite 和远程数据库服务器两种模式，支持参数化查询

### 5. 用户与安全管理

- **用户认证** — 登录验证，密码加密存储
- **用户管理** — 添加、修改、删除用户信息
- **权限控制** — 基于用户类型的权限分级
- **授权验证** — 软件授权文件验证

### 6. 监控与调试

- **文件监控** — 基于 efsw 的脚本文件变化监控，支持防抖
- **日志系统** — log4z 异步日志，支持数据库持久化
- **远程调试** — WebSocket + HTTP 双通道调试接口
- **崩溃报告** — Google Breakpad 自动生成 minidump

### 7. 版本管理

- **版本检测** — 通过 HTTP 调用 admin 后台检查更新
- **版本发布系统** — PHP 后台支持版本上传、时间线展示和最新版本 API

## 系统架构

项目采用模块化设计，由 4 个子模块组成，通过 CMake 按依赖顺序构建：

| 模块 | 类型 | 说明 |
|------|------|------|
| **libagentcore** | 静态库 | AI 智能体核心库，最先构建，供主程序链接 |
| **Interlocker4** | 应用程序 | 主程序，信号系统的核心功能与 GUI |
| **CenterServer** | 应用程序 | 中央服务器，协调多个信号系统节点 |
| **SignalSimulator** | 应用程序 | 信号模拟器，用于培训、测试和仿真 |

```
┌─────────────────────────────────────────────────────────┐
│                    Interlocker4 主程序                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│  │ 信号控制  │ │ 脚本系统  │ │ 网络通信  │ │ AI 智能体   │ │
│  │ OpenGL渲染│ │ Lua引擎   │ │ TCP/UDP   │ │ libagentcore│ │
│  │ 节点管理  │ │ 编辑器    │ │ WS/HTTP   │ │ 任务规划    │ │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  │ CenterServer │ │SignalSimulator│ │   admin/PHP  │
  │  中央服务器   │ │  信号模拟器   │ │  版本发布系统 │
  └──────────────┘ └──────────────┘ └──────────────┘
```

### 技术栈

#### 核心框架
- **wxWidgets 3.2** — 跨平台 GUI 框架（不使用 Qt）
- **C++17** — 所有模块统一标准
- **CMake** — 构建系统（`add_subdirectory`，有序构建）

#### AI 与推理
- **llama.cpp** — 本地 LLM 推理引擎，支持 GGUF 格式模型
- **ONNX Runtime 1.28.2** — 嵌入模型推理（512 维向量）
- **sqlite-vector** — SQLite 向量搜索扩展（余弦距离，支持 AVX2/AVX-512/SSE2/NEON/RVV）

#### 脚本与数据
- **Lua 5.4.7 + LuaBridge** — 脚本引擎与 C++ 绑定框架
- **SQLite + SQLiteCpp** — 嵌入式数据库及 C++ 封装
- **LMDB** — 嵌入式键值数据库（时序数据）
- **Duktape + dukglue** — 嵌入式 JavaScript 引擎

#### 网络通信
- **TCP** — 客户端/服务器（自定义消息协议，FastLZ 压缩）
- **UDP + KCP** — 可靠 UDP 传输（机车数据同步）
- **WebSocket** — 实时双向通信（远程调试）
- **HTTP** — 调试接口与版本检测

#### 图形与渲染
- **OpenGL + GLM** — 3D 图形渲染与数学运算
- **FreeType 2.13.2** — 字体渲染

#### 系统与工具
- **Google Breakpad** — 崩溃报告与异常捕获
- **gperftools (tcmalloc)** — 内存分配优化
- **efsw** — 跨平台文件系统监控
- **log4z** — 异步日志系统
- **nlohmann/json / yyjson / cJSON** — JSON 处理（多库共存）
- **FastLZ** — 数据压缩
- **MD5 / RC4** — 哈希与加密

### 项目结构

```
interlocker4/
├── CMakeLists.txt            # 顶层 CMake 项目
│
├── Interlocker4/             # 主应用程序
│   ├── CMakeLists.txt        #   构建配置
│   ├── main.cpp              #   程序入口（含 Breakpad 初始化）
│   ├── cmainframe.cpp/h      #   主框架窗口（核心 UI、网络、脚本管理）
│   ├── common.cpp/h          #   公共定义与常量
│   ├── maindrawscene.cpp/h   #   OpenGL 站场渲染场景
│   ├── scripteditor.cpp/h    #   Lua 脚本编辑器
│   ├── scriptmanager_lua.cpp/h #  Lua 脚本管理器
│   ├── luaanalyzer.cpp/h     #   Lua 语法分析器（自动补全）
│   ├── clogindialog.cpp/h    #   登录对话框
│   ├── cusermanagerdialog.cpp/h # 用户管理对话框
│   ├── csystemcontrolpanel.cpp/h # 系统控制面板
│   ├── cagentmanagedialog.cpp/h # AI 智能体管理对话框
│   ├── agentchatdlg.cpp/h    #   AI 智能体聊天对话框
│   ├── ctoolmanagedialog.cpp/h # 工具管理对话框
│   ├── liblicense.cpp/h      #   软件授权验证
│   ├── ziputility.cpp/h      #   ZIP 压缩工具
│   ├── glm/                  #   GLM 3D 数学库（内嵌源码）
│   ├── gui/                  #   GUI 节点（按钮、基础节点、管理器）
│   ├── locomanager/          #   机车管理（Loco、LocoManager）
│   └── resources/            #   资源文件
│
├── libagentcore/             # AI 智能体核心库（静态库）
│   ├── CMakeLists.txt        #   构建配置
│   ├── includes/             #   公共头文件
│   │   ├── agent/            #     智能体层（AgentManager、BaseAgent、PlannerAgent、WorkerAgent）
│   │   ├── core/             #     核心层（Config、Error、Types）
│   │   ├── memory/           #     记忆层（EmbeddingModel、MemoryManager）
│   │   ├── model/            #     模型层（ModelManager — 双后端）
│   │   ├── task/             #     任务层（Task、TaskContext、TaskManager）
│   │   └── tool/             #     工具层（ToolManager）
│   ├── srcs/                 #   实现源文件
│   └── libs/                 #   编译产物
│
├── CenterServer/             # 中央服务器
│   ├── CMakeLists.txt        #   构建配置
│   ├── main.cpp              #   程序入口
│   ├── cmainframe.cpp/h      #   主框架窗口
│   └── scriptmanager_lua.cpp/h # Lua 脚本管理器
│
├── SignalSimulator/          # 信号模拟器
│   ├── CMakeLists.txt        #   构建配置
│   ├── main.cpp              #   程序入口
│   ├── cmainframe.cpp/h      #   主框架窗口
│   ├── ctaskmanager.cpp/h    #   任务管理器
│   ├── scripteditor.cpp/h    #   脚本编辑器
│   └── scriptmanager_lua.cpp/h # Lua 脚本管理器
│
├── common/                   # 共享代码库
│   ├── network/              #   网络通信模块
│   │   ├── wtcpclient.cpp/h  #     TCP 客户端
│   │   ├── wtcpserver.cpp/h  #     TCP 服务器
│   │   ├── wudpmanager.cpp/h #     UDP 管理器
│   │   ├── whttpserver.cpp/h #     HTTP 服务器
│   │   ├── wwebsocketserver.cpp/h # WebSocket 服务器
│   │   ├── networkframemanager.cpp/h # 网络帧管理器
│   │   ├── html5/            #     WebSocket/HTML5 支持（base64、sha1）
│   │   ├── http_parser.c/h   #     HTTP 解析器
│   │   └── ikcp.c/h          #     KCP 可靠 UDP 协议
│   ├── nodemanager/          #   节点管理模块
│   │   ├── wbasenode.cpp/h   #     基础节点
│   │   ├── wnodemanager.cpp/h #    节点管理器
│   │   ├── wsignallampnode.cpp/h # 信号灯节点
│   │   ├── wswitchnode.cpp/h #     道岔节点
│   │   └── crouteconditions.cpp/h # 路由条件
│   ├── dboperator.cpp/h      #   数据库操作封装（SQLite + 远程代理）
│   ├── SQLiteCpp/            #   SQLiteCpp C++ 封装
│   ├── sqlite-vector/        #   SQLite 向量搜索扩展
│   ├── luabridge/            #   LuaBridge + Lua 5.4.7 源码
│   ├── liblmdb/              #   LMDB 嵌入式数据库
│   ├── dukglue/              #   Duktape JS 引擎绑定
│   ├── threadpool/           #   线程池（cbThreadPool）
│   ├── log4z.cpp/h           #   日志库
│   ├── fastlz.cpp/h          #   FastLZ 压缩库
│   ├── md5.cpp/h             #   MD5 哈希
│   ├── rc4.cpp/h             #   RC4 加密
│   ├── singleton.h           #   单例模板
│   ├── signal.hpp            #   信号/槽（sigslot）
│   ├── json.hpp              #   nlohmann/json
│   └── yyjson.h              #   yyjson 高性能 JSON
│
├── admin/                    # 版本发布管理系统（PHP）
│   ├── config.php            #   数据库配置
│   ├── creat_db.sql          #   数据库创建脚本
│   ├── latest.php            #   最新版本 API
│   ├── timeline.php          #   发布时间线页面
│   └── upload.php            #   版本上传页面
│
├── bin/                      # 编译输出与运行时资源
│   ├── Interlocker4          #   主程序可执行文件
│   ├── CenterServer          #   中央服务器可执行文件
│   ├── SignalSimulator       #   信号模拟器可执行文件
│   ├── authorize.aut         #   授权文件
│   └── resources/            #   运行时资源
│       ├── agentconfig/      #     AI 智能体配置（agents/tools/models/db）
│       ├── configs/          #     系统配置
│       ├── db/               #     数据库文件
│       ├── fonts/            #     字体文件
│       ├── help/             #     帮助文档
│       ├── html/             #     HTML 资源
│       └── icons/            #     图标资源
│
├── dependence/               # 第三方依赖源码包
├── doc/                      # 文档（编译说明、打包脚本）
├── screen/                   # 截图文件
└── LICENSE                   # 非商业许可证
```

### 核心类与模块

#### CMainFrame — 主框架类
应用程序的核心控制器，负责界面初始化、菜单管理、网络通信调度、脚本管理、用户认证、文件监控和系统事件处理。

#### 网络模块
| 类 | 功能 |
|----|------|
| `WTcpClient` | TCP 客户端，支持断线重连、心跳检测、多线程接收 |
| `WTCPServer` | TCP 服务器，支持多客户端管理 |
| `WUdpManager` | UDP 管理器，机车数据同步 |
| `WHttpServer` | HTTP 服务器，调试接口 |
| `WWebSocketServer` | WebSocket 服务器，远程调试与实时通信 |
| `DBOperator` | 数据库操作封装，支持本地 SQLite 和远程代理模式 |

#### 脚本模块
| 类 | 功能 |
|----|------|
| `ScriptManager` | Lua 脚本加载、执行、热重载 |
| `ScriptEditor` | 内置代码编辑器，语法高亮 |
| `LuaAnalyzer` | Lua 语法分析，支持自动补全 |

#### AI 智能体模块 (libagentcore)
| 类 | 功能 |
|----|------|
| `AgentManager` | 智能体管理器（单例），加载配置、创建 Agent |
| `BaseAgent` | 基础智能体，提供 chat()、工具调用、历史记录 |
| `PlannerAgent` | 规划智能体，评估可行性、创建任务计划 |
| `WorkerAgent` | 工作智能体，执行具体子任务 |
| `ModelManager` | 模型管理器，双后端（llama.cpp / HTTP API） |
| `MemoryManager` | 记忆管理器，SQLite 向量搜索 |
| `TaskManager` | 任务管理器（单例），线程池调度 |
| `ToolManager` | 工具管理器，脚本执行器回调 |

#### 节点管理模块
| 类 | 功能 |
|----|------|
| `WNodeManager` | 节点管理器，管理所有站场节点 |
| `WBaseNode` | 基础节点类 |
| `WSignalLampNode` | 信号灯节点 |
| `WSwitchNode` | 道岔节点 |
| `C3RouteConditions` | 路由条件评估 |

## 构建指南

### 环境要求

- **操作系统**: Linux (推荐) / Windows
- **编译器**: GCC 9+ (支持 C++17)
- **构建工具**: CMake 3.16+

### Linux 编译步骤

1. **安装系统依赖**:
   ```bash
   sudo apt install build-essential libwxgtk3.2-dev libgl1-mesa-dev \
       libglu1-mesa-dev freeglut3-dev libcurl4-openssl-dev libfmt-dev
   ```

2. **编译安装第三方依赖**（详见 `doc/编译说明.txt`）:
   - wxWidgets 3.2.10
   - FreeType 2.13.2
   - gperftools (tcmalloc)
   - efsw
   - Google Breakpad
   - llama.cpp
   - ONNX Runtime 1.28.2

3. **构建项目**:
   ```bash
   mkdir build && cd build
   cmake ..
   make -j$(nproc)
   ```

4. **运行**:
   ```bash
   cd bin
   ./Interlocker4
   ```

### Windows 编译

Windows 下需配置 Interlocker4 模块内的 `thirdparty` 目录，包含预编译的 wxWidgets、efsw、tcmalloc、CrashRpt 等库。使用 CMake 命令行运行 `cmake -B build && cmake --build build --config Release`。

## 工作流程

1. **系统启动** — 初始化 Breakpad 崩溃捕获、加载配置、创建主窗口
2. **用户登录** — 验证用户身份和权限（支持密码登录）
3. **项目加载** — 选择工作目录，加载站场配置脚本（Lua）
4. **信号控制** — 通过脚本逻辑和图形界面控制铁路信号设备
5. **机车管理** — 添加、监控和控制机车运行
6. **网络通信** — 与 CenterServer、SignalSimulator 和外部设备通信
7. **AI 辅助** — 智能体规划任务、调用工具、验证结果
8. **监控调试** — 实时日志、远程 WebSocket/HTTP 调试
9. **系统关闭** — 保存配置和数据，清理资源

## 应用场景

- **铁路信号控制** — 实际铁路系统的信号管理与控制
- **信号系统仿真** — 培训和测试场景的信号模拟
- **铁路系统研究** — 信号系统优化与改进的研究平台
- **教育教学** — 铁路信号系统的教学与学习工具

## 许可证

**非商业许可证** — 基于 MIT 风格条款，允许非商业用途使用；商业用途需获得版权所有者书面授权。

- 个人使用、学术研究、非营利组织免费使用
- 商业用途须标注 "Built with 红枫软件" 并获得授权
- 禁止军事用途和违法内容生成

版权所有 (c) 2026 OuYunHui (akinggw@126.com)

## 截图预览

![AI](https://gitee.com/akinggw/interlocker4/raw/master/screen/3c087606-7547-406f-a8d4-6d060df02390.png)
![AI](https://gitee.com/akinggw/interlocker4/raw/master/screen/dfcbd9b9-b8af-494b-9881-456a9627a3b2.png)
![AI](https://gitee.com/akinggw/interlocker4/raw/master/screen/fd585ae1-b0c4-449b-a4fa-23dd3bd8f2e0.png)
![AI](https://gitee.com/akinggw/interlocker4/raw/master/screen/20260205144203_776_14.png)
![linux1](https://gitee.com/akinggw/interlocker4/raw/master/screen/471db612-41d9-4b9b-a2ff-384899537544.png)
![远程调试](https://gitee.com/akinggw/interlocker4/raw/master/screen/2b3982c7-9898-4b9d-9f73-6e0cdc2ff6f3.png)
![linux2](https://gitee.com/akinggw/interlocker4/raw/master/screen/_20251120162042_1_14.png)
![linux3](https://gitee.com/akinggw/interlocker4/raw/master/screen/_20251120163004_13_14.png)
![任务管理](https://gitee.com/akinggw/interlocker4/raw/master/screen/0bef703a-a8c4-4259-a8a1-3aa0436f5b8e.png)
![截图2](https://gitee.com/akinggw/interlocker4/raw/master/screen/_20250725182228.png)
![代码自动补全](https://gitee.com/akinggw/interlocker4/raw/master/screen/_20250725182314.png)