VCPToolBox 系统架构文档

版本: VCP 6.4
生成日期: 2026-02-13
适用提交: d09c49f

1. 系统总览

VCPToolBox 是一个 Node.js 核心的 AI 中间层系统，采用扁平化根目录运行结构（无 src/ 分层），通过插件驱动实现 AI 能力增强。

1.1 架构全景图

┌─────────────────────────────────────────────────────────────────────────────┐
│                              客户端请求层                                     │
│         (VCPChat / SillyTavern / 自定义前端 / HTTP API / WebSocket)          │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          server.js - HTTP/SSE 入口                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Express App │  │ 中间件链    │  │ 路由层      │  │ ChatCompletionHandler│ │
│  │ :5890       │  │ (鉴权/CORS) │  │ (/v1/*)     │  │ (对话主流程)         │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
          │                           │                           │
          ▼                           ▼                           ▼
┌─────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐
│ Plugin.js       │◄─────►│ WebSocketServer.js  │◄─────►│ KnowledgeBaseManager│
│ (插件生命周期)   │       │ (分布式通信骨架)     │       │ (向量库/RAG)         │
└─────────────────┘       └─────────────────────┘       └─────────────────────┘
          │                           │
          ▼                           ▼
┌─────────────────┐       ┌─────────────────────┐
│ Plugin/ 目录    │       │ 分布式节点集群        │
│ 70+ 本地插件    │       │ (VCPDistributedServer)│
└─────────────────┘       └─────────────────────┘

1.2 技术栈

层级	技术	文件位置
运行时	Node.js (CommonJS)	`server.js:1`
Web 框架	Express.js	`server.js:231`
向量索引	Rust N-API (USearch/Vexus)	`rust-vexus-lite/`
数据库	SQLite (better-sqlite3)	`KnowledgeBaseManager.js:83`
WebSocket	ws	`WebSocketServer.js:46`
文件监听	chokidar	`KnowledgeBaseManager.js:901`
进程管理	pm2-runtime	`Dockerfile`

1.3 主要子系统

HTTP/SSE 服务层: 请求鉴权、模型转发、流式错误代理、中断控制
📁 server.js:465-493, server.js:636-745, modules/chatCompletionHandler.js:483-511
插件运行时: manifest 发现/加载、六类插件执行、服务路由注册、热重载清理
📁 Plugin.js:388-564, Plugin.js:632-720, Plugin.js:805-1030
WebSocket 通信骨架: 客户端分型认证、消息分发、分布式工具调用闭环
📁 WebSocketServer.js:52-57, WebSocketServer.js:400-465, WebSocketServer.js:467-509
知识库与 RAG 子系统: SQLite + 全局 Tag 索引 + EPA + 残差金字塔 + 去重器
📁 KnowledgeBaseManager.js:76-135, KnowledgeBaseManager.js:446-621
管理面板与运维入口: /AdminPanel 静态页面、/admin_api 受控接口
📁 server.js:316-460, WebSocketServer.js:521-534

2. 11步启动序列

以下是 node server.js 执行时的完整启动序列，每步标注阻塞点和文件位置：

Step 1: 环境配置加载 ⚠️ 阻塞

📁 server.js:4

dotenv.config({ path: 'config.env' });

阻塞原因: 同步读取配置文件，失败则进程退出
依赖: config.env 必须存在

Step 2: 日志系统初始化 ⚠️ 阻塞

📁 server.js:20-22

const logger = require('./modules/logger.js');
logger.initializeServerLogger();
logger.overrideConsole();

阻塞原因: 同步初始化日志目录和文件句柄
输出: DebugLog/archive/YYYY-MM-DD/Debug/

Step 3: Agent 目录路径解析 (同步)

📁 server.js:27-66

function resolveAgentDir() {
    const configPath = process.env.AGENT_DIR_PATH;
    // ... 路径规范化逻辑
}
AGENT_DIR = resolveAgentDir();

非阻塞: 纯同步计算

Step 4: Express 应用创建

📁 server.js:231

const app = express();
app.set('trust proxy', true);
app.use(cors({ origin: '*' }));

Step 5: 中间件链挂载

📁 server.js:236-456

app.use(express.json({ limit: '300mb' }));
app.use(express.urlencoded({ limit: '300mb', extended: true }));
// IP 追踪中间件 (241-258)
// IP 黑名单中间件 (292-303)
// Bearer Token 认证 (466-493)

Step 6: 路由层注册

📁 server.js:306-813

app.use(specialModelRouter);           // 特殊模型透传
app.get('/v1/models', ...);            // 模型列表
app.post('/v1/chat/completions', ...); // 主聊天端点
app.post('/v1/interrupt', ...);        // 中断控制
app.post('/v1/human/tool', ...);       // 人类直接调用工具
app.post('/plugin-callback/...', ...); // 插件回调

Step 7: ChatCompletionHandler 实例化

📁 server.js:749-785

const chatCompletionHandler = new ChatCompletionHandler({
    apiUrl, apiKey, modelRedirectHandler, pluginManager,
    activeRequests, writeDebugLog, webSocketServer,
    DEBUG_MODE, SHOW_VCP_OUTPUT, VCPToolCode, ...
});

Step 8: initialize() 核心初始化 ⚠️ 阻塞

📁 server.js:1076-1087

async function initialize() {
    console.log('开始初始化向量数据库...');
    await knowledgeBaseManager.initialize(); // ⚠️ 关键阻塞点
    console.log('向量数据库初始化完成。');

    pluginManager.setProjectBasePath(__dirname);
    pluginManager.setVectorDBManager(knowledgeBaseManager);
    
    console.log('开始加载插件...');
    await pluginManager.loadPlugins();        // ⚠️ 关键阻塞点
    console.log('插件加载完成。');
}

KnowledgeBaseManager.initialize() 内部流程 (KnowledgeBaseManager.js:76-134):

创建 VectorStore/ 目录
连接 SQLite 数据库 (knowledge_base.sqlite)
加载 Rust Vexus 向量索引
预热日记本名称向量缓存 (同步阻塞) 📁 KnowledgeBaseManager.js:107-109
初始化 EPA 模块
初始化残差金字塔模块
启动文件监听器 (chokidar)

PluginManager.loadPlugins() 内部流程 (Plugin.js:388-563):

清理现有插件状态（保留分布式插件）
遍历 Plugin/ 目录发现所有 plugin-manifest.json
解析插件配置并注入环境变量
加载预处理器顺序 (preprocessor_order.json)
初始化所有模块的 initialize() 方法
构建 VCP 工具描述

Step 9: 静态插件预热

📁 server.js:1090-1093

await pluginManager.initializeStaticPlugins();

行为: 为所有 static 类型插件设置定时刷新任务
位置: Plugin.js:221-258

Step 10: WebSocket 服务器初始化

📁 server.js:1095-1098

webSocketServer.initialize(server, {
    debugMode: DEBUG_MODE,
    vcpKey: process.env.VCP_Key
});

位置: WebSocketServer.js:35-323
行为: 绑定 HTTP Server 的 upgrade 事件，处理 WebSocket 握手

Step 11: startServer() 监听

📁 server.js:1100-1105

function startServer() {
    server.listen(port, () => {
        console.log(`VCP服务器正在端口 ${port} 上运行`);
    });
}
startServer();

3. 核心三角架构

VCPToolBox 的运行时核心由三个相互依赖的模块组成：

                    ┌─────────────────────┐
                    │     server.js       │
                    │  (HTTP 入口 & 编排)  │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
    ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
    │  Plugin.js      │ │WebSocketServer.js│ │KnowledgeBase    │
    │  (插件管理器)    │ │ (通信骨架)       │ │Manager.js (RAG) │
    └────────┬────────┘ └────────┬────────┘ └─────────────────┘
             │                   │
             │   setWebSocketServer()  │
             │◄──────────────────────┤
             │                   │
             │  setPluginManager()     │
             ├──────────────────────►│
             │                   │

3.1 server.js ↔ PluginManager

依赖注入点: server.js:73, 81-82

const pluginManager = require('./Plugin.js');
// ...
pluginManager.setProjectBasePath(__dirname);
pluginManager.setVectorDBManager(knowledgeBaseManager);

调用关系:

调用方	被调用方	方法	位置
server.js	PluginManager	`loadPlugins()`	`server.js:1085`
server.js	PluginManager	`executePlugin()`	`server.js:948`
server.js	PluginManager	`processToolCall()`	`server.js:859`
ChatCompletionHandler	PluginManager	`messagePreprocessors.get()`	`chatCompletionHandler.js:394`

3.2 PluginManager ↔ WebSocketServer

双向注入:

// PluginManager 持有 WebSocketServer 引用
// Plugin.js:27, 33-36
this.webSocketServer = null;
setWebSocketServer(wss) {
    this.webSocketServer = wss;
}

// WebSocketServer 持有 PluginManager 引用
// WebSocketServer.js:6, 395-397
let pluginManager = null;
function setPluginManager(pm) {
    pluginManager = pm;
}

初始化顺序 (server.js:1081-1098):

// 1. 先设置 PluginManager 的 WebSocket 引用
pluginManager.setWebSocketServer(webSocketServer);
// 2. 再设置 WebSocketServer 的 PluginManager 引用
webSocketServer.setPluginManager(pluginManager);

3.3 分布式工具调用链

AI 响应含工具调用
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ PluginManager.processToolCall()                              │
│ 📁 Plugin.js:632-803                                         │
│                                                              │
│ if (plugin.isDistributed) {                                  │
│     resultFromPlugin = await this.webSocketServer            │
│         .executeDistributedTool(plugin.serverId, ...);       │
│ }                                                            │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ WebSocketServer.executeDistributedTool()                     │
│ 📁 WebSocketServer.js:467-509                                │
│                                                              │
│ server.ws.send(JSON.stringify({                              │
│     type: 'execute_tool',                                    │
│     data: { requestId, toolName, toolArgs }                  │
│ }));                                                         │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 分布式节点 (VCPDistributedServer)                             │
│ ──WebSocket──► 执行本地插件 ──WebSocket──► 返回结果           │
└──────────────────────────────────────────────────────────────┘

4. 模块依赖图

4.1 核心模块依赖

server.js
  -> ChatCompletionHandler
       -> StreamHandler / NonStreamHandler
       -> ToolExecutor
            -> PluginManager.processToolCall()
                 -> (local stdio | hybrid direct | Chrome direct | distributed)
  -> PluginManager
       <-> WebSocketServer (setter 双向注入)
       -> message preprocessors / service modules / static placeholders
  -> KnowledgeBaseManager
       -> SQLite + Vexus index + EPA + ResidualPyramid + ResultDeduplicator
  -> FileFetcherServer
       -> WebSocketServer (跨节点文件回补)

📁 证据: server.js:69-77, server.js:749-770, modules/chatCompletionHandler.js:590-608

4.2 模块职责矩阵

模块	职责	导出类型	关键方法
`server.js`	HTTP 入口、启动编排	无 (直接执行)	`initialize()`, `startServer()`
`Plugin.js`	插件生命周期管理	`PluginManager` 类	`loadPlugins()`, `processToolCall()`, `executePlugin()`
`WebSocketServer.js`	分布式通信、实时推送	函数对象	`initialize()`, `broadcast()`, `executeDistributedTool()`
`KnowledgeBaseManager.js`	向量索引、RAG 检索	`KnowledgeBaseManager` 类	`initialize()`, `search()`, `applyTagBoost()`
`chatCompletionHandler.js`	对话主流程编排	`ChatCompletionHandler` 类	`handle()`
`messageProcessor.js`	变量替换管线	函数对象	`replaceAgentVariables()`, `replaceOtherVariables()`
`agentManager.js`	Agent 别名与文件管理	函数对象	`isAgent()`, `getAgentPrompt()`
`roleDivider.js`	角色分割转换	函数对象	`process()`

5. 核心组件详解

5.1 PluginManager (Plugin.js)

5.1.1 插件类型支持

类型	执行方式	超时	位置
`static`	定时执行，更新占位符	60s (可配置)	`Plugin.js:116-179`
`synchronous`	stdio 同步执行	60s	`Plugin.js:805-918`
`asynchronous`	stdio 初始响应 + HTTP 回调	30min	`Plugin.js:886-906`
`service`	直接 require，常驻内存	无	`Plugin.js:455-466`
`hybridservice`	服务 + 工具调用	无	`Plugin.js:683-693`
`messagePreprocessor`	消息预处理管道	无	`Plugin.js:324-345`

5.1.2 配置合并逻辑

📁 Plugin.js:61-105

_getPluginConfig(pluginManifest) {
    const config = {};
    const globalEnv = process.env;
    const pluginSpecificEnv = pluginManifest.pluginSpecificEnvConfig || {};
    
    // 优先级: 插件私有配置 > 全局环境变量
    if (pluginSpecificEnv.hasOwnProperty(key)) {
        rawValue = pluginSpecificEnv[key];
    } else if (globalEnv.hasOwnProperty(key)) {
        rawValue = globalEnv[key];
    }
    // ... 类型转换
}

5.1.3 分布式插件标记

📁 Plugin.js:665-672

if (plugin.isDistributed) {
    resultFromPlugin = await this.webSocketServer
        .executeDistributedTool(plugin.serverId, toolName, pluginSpecificArgs);
}

5.2 WebSocketServer (WebSocketServer.js)

5.2.1 客户端类型与路径

客户端类型	WebSocket 路径正则	用途
`VCPLog`	`/VCPlog/VCP_Key=(.+)`	日志推送
`VCPInfo`	`/vcpinfo/VCP_Key=(.+)`	信息推送
`DistributedServer`	`/vcp-distributed-server/VCP_Key=(.+)`	分布式节点
`ChromeObserver`	`/vcp-chrome-observer/VCP_Key=(.+)`	浏览器插件观察者
`ChromeControl`	`/vcp-chrome-control/VCP_Key=(.+)`	浏览器插件控制器
`AdminPanel`	`/vcp-admin-panel/VCP_Key=(.+)`	管理面板

📁 WebSocketServer.js:52-57

5.2.2 消息类型处理

📁 WebSocketServer.js:400-465

handleDistributedServerMessage(serverId, message) {
    switch (message.type) {
        case 'register_tools':    // 注册分布式工具
        case 'report_ip':         // 上报 IP 信息
        case 'update_static_placeholders': // 更新静态占位符
        case 'tool_result':       // 工具执行结果
    }
}

5.3 KnowledgeBaseManager (KnowledgeBaseManager.js)

5.3.1 多索引架构

VectorStore/
├── knowledge_base.sqlite     # SQLite 主数据库
├── index_global_tags.usearch # 全局 Tag 索引
├── index_diary_{hash}.usearch # 各日记本独立索引
└── ...

📁 KnowledgeBaseManager.js:210-242

5.3.2 TagMemo V3.7 增强算法

📁 KnowledgeBaseManager.js:443-731

核心步骤:

EPA 分析: 逻辑深度与共振检测
残差金字塔: 新颖度与覆盖率分析
动态增强: 基于 EPA 结果调整 boost 因子
世界观门控: 过滤跨域噪音
语言补偿: 技术词汇惩罚
核心 Tag 补全: 确保关键锚点不丢失
语义去重: 消除冗余标签

// 核心公式 (KnowledgeBaseManager.js:468-473)
const dynamicBoostFactor = (logicDepth * (1 + resonanceBoost) 
    / (1 + entropyPenalty * 0.5)) * activationMultiplier;
const effectiveTagBoost = baseTagBoost * Math.max(boostRange[0], 
    Math.min(boostRange[1], dynamicBoostFactor));

6. 聊天请求完整流程

6.1 流程图

POST /v1/chat/completions
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. 请求预处理                                                │
│    • 生成 requestId, 创建 AbortController                   │
│    • 注册到 activeRequests Map                              │
│    📁 chatCompletionHandler.js:289-300                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 上下文控制 (可选)                                         │
│    • 检测 contextTokenLimit 参数                            │
│    • 调用 contextManager.pruneMessages()                    │
│    📁 chatCompletionHandler.js:307-325                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 模型重定向                                                │
│    • modelRedirectHandler.redirectModelForBackend()         │
│    📁 chatCompletionHandler.js:328-346                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 角色分割处理 (可选)                                       │
│    • roleDivider.process()                                  │
│    📁 chatCompletionHandler.js:353-364                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. VCPTavern 优先预处理                                      │
│    • pluginManager.executeMessagePreprocessor('VCPTavern')  │
│    📁 chatCompletionHandler.js:392-401                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 6. 统一变量替换管线                                          │
│    • messageProcessor.replaceAgentVariables()               │
│    • 递归展开 Agent、Tar*、Var* 占位符                       │
│    📁 chatCompletionHandler.js:414-444                      │
│    📁 messageProcessor.js:14-52                             │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 7. 媒体处理器                                                │
│    • MultiModalProcessor 或 ImageProcessor                  │
│    📁 chatCompletionHandler.js:448-460                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 8. 其他消息预处理器链                                        │
│    • 按顺序执行所有已注册的预处理器                          │
│    📁 chatCompletionHandler.js:463-473                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 9. 调用上游 AI API                                           │
│    • fetchWithRetry() 带重试机制                            │
│    📁 chatCompletionHandler.js:483-511                      │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│ 10. 响应处理                                                 │
│     • StreamHandler 或 NonStreamHandler                     │
│     • 检测工具调用、执行工具、递归调用                        │
│    📁 chatCompletionHandler.js:604-607                      │
└─────────────────────────────────────────────────────────────┘

6.2 变量替换管线详解

📁 messageProcessor.js

// 主入口函数
async function resolveAllVariables(text, model, role, context, processingStack) {
    // 1. 递归展开 Agent 变量 (检测循环依赖)
    // 2. 调用 replacePriorityVariables (表情包、日记本)
    // 3. 调用 replaceOtherVariables (Tar*, Var*, 时间, 静态插件占位符)
}

变量优先级 (从高到低):

{{agent:Alias}} / {{Alias}} - Agent 别名展开
{{Tar*}} - 最高优先级模板变量
{{Var*}} - 通用自定义变量
{{SarPrompt*}} - 模型条件注入
{{Date}} / {{Time}} / {{Festival}} - 时间变量
{{VCPPluginName}} - 静态插件占位符
{{VCPAllTools}} - 全部工具描述聚合

6.3 VCP 工具调用协议

请求格式 (AI 输出):

<<<[TOOL_REQUEST]>>>
tool_name:「始」PluginName「末」,
param1:「始」value1「末」,
archery:「始」no_reply「末」,
ink:「始」mark_history「末」
<<<[END_TOOL_REQUEST]>>>

解析位置: modules/vcpLoop/toolCallParser.js

高级指令:

指令	效果
`archery:「始」no_reply「末」`	异步执行，不等待结果
`ink:「始」mark_history「末」`	强制将结果注入对话历史

7. 分布式工具执行流程

7.1 节点注册流程

分布式节点启动
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ VCPDistributedServer 连接到主服务器                           │
│ WebSocket 路径: /vcp-distributed-server/VCP_Key=xxx          │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 发送 register_tools 消息                                      │
│ { type: 'register_tools', data: { tools: [...] } }           │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ WebSocketServer.handleDistributedServerMessage()             │
│ 📁 WebSocketServer.js:407-416                                │
│                                                              │
│ pluginManager.registerDistributedTools(serverId, tools);     │
│ // 为每个工具添加 [云端] 前缀和 isDistributed: true 标记     │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 发送 report_ip 消息                                          │
│ { type: 'report_ip', data: { localIPs, publicIP, serverName } }│
└──────────────────────────────────────────────────────────────┘

7.2 工具执行流程

AI 请求执行云端工具
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ PluginManager.processToolCall()                              │
│ 📁 Plugin.js:665-672                                         │
│                                                              │
│ if (plugin.isDistributed) {                                  │
│     result = await this.webSocketServer                      │
│         .executeDistributedTool(plugin.serverId, ...);       │
│ }                                                            │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ WebSocketServer.executeDistributedTool()                     │
│ 📁 WebSocketServer.js:467-509                                │
│                                                              │
│ const requestId = generateClientId();                        │
│ pendingToolRequests.set(requestId, { resolve, reject });     │
│ server.ws.send(JSON.stringify({                              │
│     type: 'execute_tool', data: { requestId, toolName, args }│
│ }));                                                         │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 分布式节点执行本地插件                                        │
│ (VCPDistributedServer 内部)                                  │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 返回 tool_result 消息                                        │
│ { type: 'tool_result', data: { requestId, status, result } } │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ WebSocketServer.handleDistributedServerMessage()             │
│ 📁 WebSocketServer.js:450-460                                │
│                                                              │
│ const pending = pendingToolRequests.get(requestId);          │
│ if (status === 'success') pending.resolve(result);           │
│ else pending.reject(new Error(error));                       │
└──────────────────────────────────────────────────────────────┘

7.3 分布式文件解析 (VCPFileAPI v4.0)

📁 Plugin.js:726-773

工具调用参数含 file:// URL
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 本地插件执行失败 (FILE_NOT_FOUND_LOCALLY)                    │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ FileFetcherServer.fetchFile(fileUrl, requestIp)              │
│ 1. 根据 IP 追踪来源服务器                                    │
│ 2. 通过 WebSocket 请求远程文件                               │
│ 3. 返回 Base64 编码数据                                      │
└──────────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────────┐
│ 自动重试: 替换 file:// 为 data: URI                          │
│ newToolArgs.image_base64_1 = `data:${mimeType};base64,...`   │
│ return await this.processToolCall(toolName, newToolArgs);    │
└──────────────────────────────────────────────────────────────┘

8. 错误处理机制

8.1 请求中断机制

📁 server.js:636-745

app.post('/v1/interrupt', (req, res) => {
    const context = activeRequests.get(id);
    if (context) {
        context.aborted = true;
        context.abortController.abort();
        // 根据请求类型发送适当的响应
        if (isStreamRequest) {
            // 流式请求: 发送 SSE 格式中止信号
        } else {
            // 非流式请求: 发送 JSON 响应
        }
    }
});

8.2 上游 API 错误处理

📁 chatCompletionHandler.js:519-569

// 流式请求上游返回非 200 状态码
if (isOriginalRequestStreaming && upstreamStatus !== 200) {
    res.status(200);
    res.setHeader('Content-Type', 'text/event-stream');
    // 将错误作为 SSE chunk 发送给客户端
    res.write(`data: ${JSON.stringify(errorPayload)}\n\n`);
    res.write('data: [DONE]\n\n');
}

8.3 重试机制

📁 chatCompletionHandler.js:99-144

async function fetchWithRetry(url, options, { retries = 3, delay = 1000 }) {
    for (let i = 0; i < retries; i++) {
        const response = await fetch(url, options);
        if (response.status === 500 || response.status === 503 || response.status === 429) {
            await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
            continue; // 重试
        }
        return response;
    }
    throw new Error('Fetch failed after all retries.');
}

8.4 IP 黑名单机制

📁 server.js:179-289

// 错误计数
function handleApiError(req) {
    const currentErrors = (apiErrorCounts.get(clientIp) || 0) + 1;
    if (currentErrors >= MAX_API_ERRORS) {
        ipBlacklist.push(clientIp);
        saveBlacklist();
    }
}

// 黑名单拦截中间件
app.use((req, res, next) => {
    if (ipBlacklist.includes(clientIp)) {
        return res.status(403).json({ error: 'Forbidden' });
    }
    next();
});

8.5 工具执行错误检测

📁 chatCompletionHandler.js:19-68

function isToolResultError(result) {
    if (typeof result === 'object') {
        if (result.error === true || result.status === 'error') return true;
    }
    if (typeof result === 'string') {
        const errorPrefixes = ['[error]', '[错误]', '[失败]', 'error:'];
        for (const prefix of errorPrefixes) {
            if (result.toLowerCase().startsWith(prefix)) return true;
        }
    }
    return false;
}

9. 关键设计决策

9.1 扁平化目录结构

决策: 根目录直接放置核心模块，无 src/ 分层。

理由:

降低模块导入复杂度
便于快速定位代码
适配插件生态的文件监听需求

证据: server.js、Plugin.js、WebSocketServer.js 均位于根目录

9.2 Rust N-API 向量索引

决策: 使用 Rust (USearch) 实现向量索引，通过 N-API 绑定到 Node.js。

理由:

纯 JS 向量搜索性能不足
USearch 是业界最快的向量搜索引擎之一
支持磁盘映射 (mmap) 模式处理大规模数据

证据: KnowledgeBaseManager.js:17-25

try {
    const vexusModule = require('./rust-vexus-lite');
    VexusIndex = vexusModule.VexusIndex;
    console.log('[KnowledgeBase] 🦀 Vexus-Lite Rust engine loaded');
} catch (e) {
    console.error('[KnowledgeBase] ❌ Critical: Vexus-Lite not found.');
    process.exit(1); // 无 Rust 组件则退出
}

9.3 分布式插件热注册

决策: 分布式节点通过 WebSocket 实时注册插件，断开自动注销。

理由:

支持动态扩缩容
无需重启主服务器
实现算力分布式调度

证据: WebSocketServer.js:288-294

ws.on('close', () => {
    if (ws.clientType === 'DistributedServer') {
        pluginManager.unregisterAllDistributedTools(ws.serverId);
        distributedServers.delete(ws.serverId);
    }
});

9.4 VCP 自定义工具调用协议

决策: 不使用 OpenAI function-calling，采用自定义文本标记协议。

理由:

模型无关性：支持所有兼容 OpenAI API 格式的模型
协议透明：易于调试和日志追踪
支持高级指令 (archery, ink)

证据: README.md - "工具调用协议是 VCP 自定义块语法"

9.5 静态插件的 Cron 刷新

决策: 静态插件通过 cron 表达式定时执行，而非持续运行。

理由:

资源效率：只在需要时执行
灵活调度：支持任意时间间隔
超时保护：避免无限执行

证据: Plugin.js:238-254

if (plugin.refreshIntervalCron) {
    const job = schedule.scheduleJob(plugin.refreshIntervalCron, () => {
        this._updateStaticPluginValue(plugin);
    });
    this.scheduledJobs.set(plugin.name, job);
}

9.6 多索引隔离架构

决策: 每个日记本使用独立的向量索引，而非全局单一索引。

理由:

检索隔离：避免跨日记本干扰
懒加载：只在访问时加载对应索引
故障隔离：单个索引损坏不影响其他

证据: KnowledgeBaseManager.js:210-220

async _getOrLoadDiaryIndex(diaryName) {
    if (this.diaryIndices.has(diaryName)) {
        return this.diaryIndices.get(diaryName);
    }
    // 懒加载索引
    const idx = await this._loadOrBuildIndex(idxName, 50000, 'chunks', diaryName);
    this.diaryIndices.set(diaryName, idx);
    return idx;
}

9.7 循环依赖解决：Setter 注入

决策: PluginManager ↔ WebSocketServer 通过运行期 setter 注入，而非模块加载时强耦合。

理由:

降低模块加载期循环引用风险
保证初始化顺序可控
便于测试和替换实现

证据: server.js:1092, server.js:1213, WebSocketServer.js:395-398

附录 A: 文件定位索引

功能	文件	关键行号
环境加载	`server.js`	4
日志初始化	`server.js`	20-22
Express 创建	`server.js`	231
IP 黑名单	`server.js`	179-303
管理员认证	`server.js`	317-456
聊天端点	`server.js`	788-813
中断端点	`server.js`	636-745
插件加载	`Plugin.js`	388-563
工具执行	`Plugin.js`	632-803
分布式调用	`Plugin.js`	665-672
WebSocket 初始化	`WebSocketServer.js`	35-323
分布式消息处理	`WebSocketServer.js`	400-465
向量库初始化	`KnowledgeBaseManager.js`	76-134
TagMemo V3 算法	`KnowledgeBaseManager.js`	443-731
对话主流程	`chatCompletionHandler.js`	254-712
变量替换	`messageProcessor.js`	14-239

附录 B: 配置文件依赖

配置文件	用途	加载位置
`config.env`	全局环境变量	`server.js:4`
`Plugin/*/config.env`	插件私有配置	`Plugin.js:442-446`
`Plugin/*/plugin-manifest.json`	插件清单	`Plugin.js:435`
`preprocessor_order.json`	预处理器顺序	`Plugin.js:484-496`
`ip_blacklist.json`	IP 黑名单	`server.js:179-193`
`Agent/agent_map.json`	Agent 别名映射	`agentManager.js`
`rag_params.json`	RAG 热调控参数	`KnowledgeBaseManager.js:140-149`

附录 C: 边界条件与异常分支

Agent 目录创建失败 -> 进程退出 📁 server.js:49-65
Admin 凭据缺失 -> 管理面板禁用（503）📁 server.js:345-357
登录暴力尝试 -> 临时封禁 + Retry-After 📁 server.js:361-369
分布式目标节点离线 -> 抛错终止工具调用 📁 WebSocketServer.js:485-487
分布式工具超时 -> pending 清理 + reject 📁 WebSocketServer.js:500-503
插件 stdout 非法 JSON -> 同步插件按失败分支返回详细错误 📁 Plugin.js:999-1013
上游流式异常 -> SSE 错误帧兜底 📁 chatCompletionHandler.js:619-651

文档结束

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History