VLCode-Lite/MODULE-SPEC.md

VLCode Lite — 全模块规格说明 v0.2.0

共 84 个 JS 模块，200+ 函数/方法，127 个 HTTP 端点，34 个 AI 工具 LLM 模式：仅 Claude CLI（Team 订阅），无 API Key

---

目录结构总览

src/
├── app.js                          # 主入口类
├── core/                           # 核心引擎（8 个模块）
│   ├── orchestrator.js             #   Agent 循环
│   ├── llm-provider.js             #   Claude CLI 适配器
│   ├── context-manager.js          #   上下文窗口管理
│   ├── prompt-assembler.js         #   系统提示词组装
│   ├── session-pool.js             #   多会话隔离
│   ├── session.js                  #   会话持久化
│   ├── tool-registry.js            #   工具注册中心
│   ├── cli.js                      #   终端界面
│   └── hooks.js                    #   Pre/Post 钩子
├── server/                         # HTTP 服务层（14 个模块）
│   ├── server.js                   #   WebServer 主类
│   ├── sse.js                      #   SSE 事件总线
│   ├── helpers.js                  #   Cookie / 项目初始化
│   ├── index.js                    #   Re-export
│   └── routes/                     #   11 个路由文件
│       ├── chat.js                 #     AI 对话
│       ├── files.js                #     文件管理
│       ├── project.js              #     项目元数据
│       ├── workspace.js            #     多工作区
│       ├── compile.js              #     编译/测试
│       ├── workflow.js             #     工作流执行
│       ├── cloud.js                #     云端认证/同步
│       ├── intelligence.js         #     符号/影响分析
│       ├── tools.js                #     MCP 工具代理
│       ├── conversation.js         #     会话管理
│       └── misc.js                 #     健康检查/杂项
├── tools/                          # AI 工具（34 个）
│   ├── index.js                    #   工具注册入口
│   ├── read-file.js                #   ReadFile
│   ├── edit-file.js                #   EditFile
│   ├── write-file.js               #   WriteFile
│   ├── bash.js                     #   Bash
│   ├── grep.js                     #   Grep
│   ├── glob.js                     #   Glob
│   ├── todo-write.js               #   TodoWrite
│   ├── sub-agent.js                #   SubAgent
│   ├── ask-user.js                 #   AskUserQuestion
│   ├── memory.js                   #   Memory
│   ├── tool-search.js              #   ToolSearch
│   ├── workflow-run.js             #   WorkflowRun
│   ├── workspace-api.js            #   WorkspaceAPI
│   ├── component-fetch.js          #   ComponentFetch
│   ├── browser-inspect.js          #   BrowserInspect
│   ├── doc-center.js               #   DocCenter
│   ├── vl-generate.js              #   VLGenerate
│   ├── vl-adjust.js                #   VLAdjust
│   ├── vl-compile.js               #   VLCompile
│   ├── vl-lint.js                  #   VLLint
│   ├── vl-parse.js                 #   VLParse
│   ├── vl-syntax-ref.js            #   VLSyntaxRef
│   ├── vl-validate.js              #   VLValidate
│   ├── vl-metadata.js              #   VLMetadata
│   ├── vl-component-test.js        #   VLComponentTest
│   ├── vl-symbols.js               #   VLSymbols
│   ├── vl-impact.js                #   VLImpact
│   ├── vl-edit-section.js          #   VLEditSection
│   ├── vl-autofix.js               #   VLAutoFix
│   ├── vl-cascade-edit.js          #   VLCascadeEdit
│   ├── meta-diff.js                #   MetaDiff
│   ├── section-diff.js             #   SectionDiff
│   ├── vl-meta-test.js             #   VLMetaTest
│   ├── autotest-pipeline.js        #   AutoTestPipeline
│   └── autotest/                   #   自动测试子模块（7 个）
│       ├── test-generator.js
│       ├── test-runner.js
│       ├── test-evaluator.js
│       ├── auto-fixer.js
│       ├── case-parser.js
│       ├── report-generator.js
│       ├── workflow-builder.js
│       └── workflow-runner.js
├── vl/                             # VL 语言引擎（15 个模块）
│   ├── project-context.js          #   项目扫描/检测
│   ├── symbol-index.js             #   符号索引
│   ├── smart-context.js            #   智能上下文加载
│   ├── blueprint-context.js        #   蓝图上下文
│   ├── impact-analyzer.js          #   影响分析
│   ├── auto-fix.js                 #   自动修复
│   ├── file-cache.js               #   文件缓存
│   ├── file-watcher.js             #   文件监听
│   ├── metadata-extractor.js       #   ProjectMeta 提取
│   ├── meta-diff.js                #   Meta 差异比较
│   ├── section-diff.js             #   Section 差异合并
│   ├── generation-pipeline.js      #   8-Agent 生成管线
│   ├── workflow-generation-pipeline.js # 工作流驱动生成
│   ├── workflow-executor.js        #   工作流引擎桥接
│   └── meta-test-generator.js      #   测试骨架生成
├── engine/                         # 本地引擎（3 个模块）
│   ├── local-workspace.js          #   本地 Workspace API
│   ├── sse-parser.js               #   SSE 流解析
│   └── workflow-engine-manager.js  #   Go 引擎管理
├── cloud/                          # 云端客户端
│   └── cloud-api.js                #   VisualLogic 云 API
├── mcp/                            # MCP 协议
│   └── mcp-server.js               #   MCP stdio 代理
├── data/                           # 静态数据
│   ├── versions.js                 #   版本常量
│   ├── doc-paths.js                #   DocCenter 路径注册表
│   ├── default-theme.js            #   默认主题
│   └── vl-syntax.md                #   VL Bible（打包）
└── utils/                          # 工具函数
    ├── config.js                   #   配置加载
    └── zip-extract.js              #   ZIP 解压

---

一、主入口

src/app.js — VLCodeLite

主应用类，协调所有组件的初始化和启动。

方法	参数	说明
constructor()	—	初始化所有模块属性为 null
run(args)	args: string[]	主入口：加载配置 → 初始化 16 个组件 → 路由到 CLI 或 Web 模式
printInitStats(initTimeMs, sessionResumed)	number, boolean	显示初始化统计（符号数、蓝图、LLM Provider、耗时）
startWebMode(initTime)	number	启动 Express 服务器 + 文件监听 + SSE 广播
startCLIMode()	—	启动交互式 CLI REPL

---

二、核心引擎 src/core/

orchestrator.js — AgentOrchestrator

核心 Agent 循环：管理 LLM 交互、工具执行、流式输出、计划模式、上下文管理。

方法	参数	说明
constructor({config, toolRegistry, contextManager, promptAssembler, cli, projectContext})	object	初始化：技能系统、计划模式、权限系统
processUserMessage(userInput)	string	同步消息处理（CLI 模式）
processUserMessageStreaming(userInput, callbacks, options)	string, object, object	流式消息处理（Web 模式），支持 onText/onToolCall/onToolResult/onTodo/onDone/onError 回调
warmUp()	—	预缓存系统提示词和工具 schema
_hasCompileErrors()	—	检查最近 30 分钟内的编译错误
_fixOrphanedToolUse()	—	修复 tool_use/tool_result 配对，防止 API 400
_scheduleRescan()	—	防抖项目重扫（1200ms）
_checkMetaDrift(filePath)	string	VL 文件写入后检查 Meta 漂移

辅助函数：

• withRetry(fn, { maxRetries, onRetry }) — 指数退避重试（处理 429/529/5xx）

---

llm-provider.js — CLIProvider

Claude CLI 适配器，使用 Team 订阅（零额外成本）。

方法	参数	说明
constructor(config)	object	初始化 CLI provider（model、MCP 端口）
_create(params)	object	非流式调用，返回 Anthropic 兼容响应
_stream(params)	object	流式调用，返回 async iterable + finalMessage() + abort()
_callCLI(params)	object	执行 claude --print，自动生成 MCP 配置
_extractSystemText(system)	string\|array	从 Anthropic 系统提示格式提取纯文本
_serializeMessages(messages)	array	转换消息数组为 CLI stdin 格式
_exec(args, stdinData, timeout)	string[], string, number	spawn claude CLI 进程

工厂函数：

• createProvider(config) → CLIProvider — 始终返回 CLI provider
• isCLIAvailable() → Promise<boolean> — 检查 claude CLI 是否可用

---

context-manager.js — ContextManager

对话消息历史管理、token 跟踪、智能压缩。

方法	参数	说明
constructor(config)	object	初始化上下文窗口（默认 200K tokens）
addUserMessage(content)	string\|array	添加用户消息
addAssistantMessage(content)	string\|array	添加助手消息
addToolResult(toolUseId, content)	string, string\|object	添加工具结果（合并同轮 tool_result）
getMessages()	—	返回过滤、合并、验证后的消息列表（带 cache_control）
updateFromUsage(usage)	object	从 API 响应更新真实 token 计数
needsCompression()	—	是否需要压缩（>85% 窗口）
compress(client)	object	使用 Haiku 模型智能压缩（保留锚点轮次）
toggleExclude(startIdx, endIdx)	number, number?	切换消息排除状态
getUsage()	—	返回使用统计
getCompressionStats()	—	返回压缩次数和节省 token 数

---

prompt-assembler.js — PromptAssembler

动态构建系统提示词，4 段缓存策略。

方法	参数	说明
constructor(config, projectContext)	object, object	初始化
buildSystemPrompt()	—	构建系统提示词（VL Bible + 指令手册 + 动态上下文）
buildInstructionManual()	—	构建核心规则、VL 规则、工具决策树
buildDynamicContext()	—	构建每轮动态上下文（日期、目录、项目信息、编译错误）
buildInitialReminders()	—	首条消息的 system-reminder（项目配置、规则、记忆、文档）
buildToolReminder(toolName, context)	string, object	工具执行后的条件性提醒
buildSubAgentPrompt(agentType)	string	子 Agent 系统提示词
trackCacheStats(usage)	object	跟踪缓存命中率
_loadVLBible()	—	加载 VL Bible（项目 → 全局 → 打包）
_loadMemory()	—	加载 MEMORY.md（项目 + 全局）

---

session-pool.js — SessionPool

Per-chatId 会话隔离，轻量多租户。

方法	参数	说明
constructor(shared)	object	初始化共享模块，启动 5 分钟 GC
getOrCreate(chatId)	string\|number	获取或创建会话
get(chatId)	string\|number	获取已有会话（不创建）
delete(chatId)	string\|number	删除会话
list()	—	列出所有活跃会话
findByName(name)	string	按会话名查找
destroy()	—	停止 GC 定时器

GC 规则： 空闲 >30 分钟自动回收。

---

session.js — SessionManager

会话持久化：保存/恢复对话状态、todo、决策、文件变更。

方法	参数	说明
constructor(workDir)	string	初始化（.vl-code/sessions/）
init()	—	创建会话目录
startOrResume()	—	恢复最近会话（<24h）或创建新会话
save(extra)	object?	保存当前会话
addDecision(decision)	object	记录关键决策（保留最近 50 条）
addFileChange(filePath, changeType)	string, string	记录文件变更（保留最近 200 条）
saveTodos(todos)	array	更新 todo 列表
getRecoveryContext()	—	返回恢复上下文（摘要、todo、决策、变更）
saveConversation(convId, data)	string, object	保存完整对话
listConversations()	—	列出已保存对话

---

tool-registry.js — ToolRegistry

工具注册、schema 管理、延迟加载、执行超时保护。

方法	参数	说明
constructor()	—	初始化工具映射
register(name, {description, parameters, execute, deferred})	string, object	注册工具（可选延迟加载）
get(name)	string	获取工具定义
execute(name, input)	string, object	执行工具（30s 超时，Bash 60s，长任务 300s）
getToolSchemas()	—	返回 Anthropic 格式 schema（跳过未激活的延迟工具）
activateDeferred(name)	string	激活延迟工具
listTools()	—	列出所有工具名
listDeferredTools()	—	列出未激活的延迟工具
listActiveTools()	—	列出活跃工具名
clear()	—	清空所有工具（workspace 切换时用）

---

cli.js — CLIInterface

终端界面，格式化输出。

方法	说明
printBanner()	打印 VL-Code 横幅
printProjectInfo(summary)	打印项目检测信息
printHelp()	打印可用命令
printStatus(usage)	打印上下文窗口使用率（进度条）
printToolCall(name, description)	打印工具调用指示器
printToolResult(name, preview)	打印工具结果预览
printTodo(todos)	打印 todo 列表（✓/→/○）
printStreaming(token)	实时打印 token
prompt()	阻塞等待用户输入

---

hooks.js — HooksManager

用户自定义 Pre/Post 操作钩子。

方法	参数	说明
constructor(workDir)	string	加载 .vl-code/hooks.json
runPre(toolName, input)	string, object	执行前置钩子，返回 {blocked, reason}
runPost(toolName, input, output)	string, object, string	执行后置钩子（fire-and-forget）
runEvent(eventName, vars)	string, object?	执行语义生命周期钩子
hasHooks()	—	是否有已配置的钩子

---

三、HTTP 服务层 src/server/

server.js — WebServer

Express 服务器主类。

方法	参数	说明
constructor({config, orchestrator, ...})	object	初始化 Express + 中间件 + SessionPool + ConversationRegistry
broadcast(data)	object	SSE 广播到所有已连接客户端
getSession(req)	Request	按 chatId 获取/创建会话
isBusy()	—	检查是否有会话正在执行
reregisterVLTools()	—	重新注册工具（workspace 切换后）
autoExtractMeta()	—	从文件树自动提取 ProjectMeta
start(port)	number	启动服务器（端口占用时自动 +1）

sse.js — SSE 事件总线

函数	说明
setupSSE(app, server)	注册 GET /api/events SSE 端点，跟踪已连接客户端

特性： 无页面单例限制（允许多个浏览器标签同时连接）。

helpers.js — 服务器工具函数

函数	说明
getCookie(config)	加载 JWT（project.json → auth.json → vl-cookie.txt → .doccenter_cookie）
clearCookie(config)	清除所有位置的 cookie
saveCookie(config, cookie)	保存 JWT 到全局 + 项目配置
loadWorkspaces()	读取 workspace 列表
saveWorkspaces(list)	保存 workspace 列表
ensureVLBible(dataDir)	如果需要，复制打包的 VL 语法规范
hasVLFiles(workDir)	检测目录是否包含 VL 项目
ensureProjectProfile(workDir, seedWorkflowDir)	创建 .vl-code/ 项目配置

---

路由端点汇总

routes/chat.js — AI 对话（7 个端点）

方法	端点	说明
POST	/api/chat	流式 LLM 响应（SSE：text/tool_call/thinking/error/done）
POST	/api/abort	取消当前对话或工作流
POST	/api/answer	提交 ask_user 问题的答案
GET	/api/context	获取 token 使用统计
POST	/api/context/clear	重置消息历史
POST	/api/context/toggle-exclude	切换消息排除
GET	/api/context/messages	列出所有消息

routes/files.js — 文件管理（13 个端点）

方法	端点	说明
GET	/api/files	获取文件树 + 文件列表
GET	/api/file	读取文件内容
GET	/api/file/raw	下载原始文件
POST	/api/file	创建/覆写文件
DELETE	/api/file	删除文件
POST	/api/files/clear	清空项目目录
POST	/api/upload-zip	上传 ZIP 解压
POST	/api/upload-folder	批量写入文件
GET	/api/export-zip	导出项目为 ZIP
GET	/api/browse-dir	浏览子目录
POST	/api/open-folder	系统文件管理器打开
GET	/api/files/autocomplete	文件名自动补全
GET	/api/mentions	@-mention 文件和符号

routes/project.js — 项目元数据（7 个端点）

方法	端点	说明
GET	/api/project	项目摘要
GET	/api/profile	读取 project.json
POST	/api/profile	合并保存 project.json
GET	/api/metadata	获取 ProjectMeta.json
POST	/api/metadata	保存 ProjectMeta.json
GET	/api/metadata/extract	自动提取 Meta
POST	/api/project/init	创建标准目录结构

routes/workspace.js — 多工作区（10 个端点）

方法	端点	说明
GET	/api/workspaces	列出工作区
POST	/api/workspaces	添加工作区
POST	/api/workspaces/switch	切换活跃工作区（重载上下文、重注册工具）
DELETE	/api/workspaces/:id	移除工作区
POST	/api/workspaces/create-project	创建新 VL 项目
GET	/api/workspace-tabs	获取打开的标签
POST	/api/workspace-tabs/close	关闭标签
POST	/api/workspace-tabs/reorder	重排标签
GET	/api/workspace/state	获取 UI 状态
POST	/api/workspace/state	保存 UI 状态

routes/compile.js — 编译/测试（10 个端点）

方法	端点	说明
POST	/api/validate	VL 项目验证
POST	/api/compile	编译（SSE 进度）
POST	/api/compile/autofix	自动修复编译错误（LLM agent）
GET	/api/compile/errors	获取最近编译错误
POST	/api/browser/screenshot	Playwright 截图
POST	/api/browser/console	获取浏览器控制台日志
POST	/api/browser/evaluate	执行浏览器 JS
GET	/api/browser/screenshot/:name	获取已保存截图
POST	/api/vl-test	VL 组件测试
POST	/api/vl-syntax	VL 语法参考

routes/workflow.js — 工作流（11 个端点）

方法	端点	说明
POST	/api/workflow/execute	执行工作流（SSE 节点进度）
POST	/api/workflow/resume	恢复暂停的工作流
POST	/api/workflow/cancel	取消暂停的工作流
POST	/api/workflow/ephemeral	保存临时工作流
GET	/api/workflows	列出所有工作流
GET	/api/workflow/:name	读取工作流 JSON
POST	/api/workflow/:name	保存工作流
DELETE	/api/workflow/:name	删除工作流
GET	/api/workflow-selection	获取默认工作流偏好
POST	/api/workflow-selection	设置默认工作流偏好
POST	/api/generate	Legacy：委托 orchestrator 生成

routes/cloud.js — 云端认证/同步（17 个端点）

方法	端点	说明
GET	/api/settings	获取配置（model, llmProvider, version）
POST	/api/settings	更新配置（model, maxOutputTokens, cookie）
POST	/api/cookie/refresh	更新/验证 cookie
POST	/api/cloud/login	企业账号登录
POST	/api/cloud/google-login	Google OAuth 登录
GET	/api/cloud/status	登录状态 + 用户信息
POST	/api/cloud/logout	清除 cookie
GET	/api/cloud/apps	列出用户应用
GET	/api/cloud/workgroup/:gid	获取工作组配置
GET	/api/cloud/files/:gid	列出云端文件
POST	/api/cloud/sync/push	上传本地 → 云端
POST	/api/cloud/sync/pull	下载云端 → 本地
POST	/api/cloud/compile	云端编译
POST	/api/cloud/lint	云端 lint
GET	/api/cloud/config/:nid	获取域名/预览 URL
POST	/api/cloud/publish	发布版本
GET	/api/cloud/balance	查询账户余额

routes/intelligence.js — 符号/影响分析（9 个端点）

方法	端点	说明
GET	/api/symbols/definition/:name	符号定义
GET	/api/symbols/references/:name	符号引用
GET	/api/symbols/complete	符号自动补全
GET	/api/symbols/outline	文件符号大纲
GET	/api/symbols/stats	符号统计
POST	/api/impact/scan	变更影响分析
POST	/api/impact/rename	重命名影响分析
GET	/api/blueprint/status	蓝图加载状态
GET	/api/blueprint/context	蓝图文档

routes/tools.js — MCP 工具代理（11 个端点）

方法	端点	说明
GET	/api/tools/list	列出所有注册工具
POST	/api/tools/execute	按名称执行工具
GET	/api/skills	列出可用技能
POST	/api/skill	激活并运行技能（SSE）
POST	/api/doccenter/:action	DocCenter API 代理
GET	/api/agent/state	Orchestrator 恢复状态
GET	/api/agents	列出后台 Agent
GET	/api/agents/:id	Agent 详情
GET	/api/vl-docs	列出同步的 VL 文档
POST	/api/vl-docs/sync	同步文档库
GET	/api/vl-docs/content	读取本地文档内容

routes/conversation.js — 会话管理（18 个端点）

方法	端点	说明
GET	/api/sessions	列出活跃会话
GET	/api/session/:chatId/summary	会话摘要
GET	/api/conversations	会话注册表
POST	/api/conversations	创建新会话
PATCH	/api/conversations/:id	更新会话
DELETE	/api/conversations/:id	删除会话
DELETE	/api/conversations	清空所有会话
GET	/api/chat/state	获取会话注册表
POST	/api/chat/state	更新注册表
POST	/api/chat/persist	保存对话到文件
GET	/api/chat/persist	列出已保存对话
GET	/api/chat/persist/:id	加载已保存对话
POST	/api/chat/generate-title	生成对话标题
GET	/api/chat/history	最近对话历史
POST	/api/debug-log/persist	保存调试日志
GET	/api/history/search	搜索消息历史
POST	/api/plan/enter	进入计划模式
POST	/api/plan/approve	批准计划
POST	/api/plan/cancel	取消计划
GET	/api/plan/status	计划模式状态

routes/misc.js — 杂项（15 个端点）

方法	端点	说明
GET	/api/health	服务器健康检查
GET	/api/version	应用版本
POST	/api/undo	撤销最近文件编辑
GET	/api/undo/stack	撤销历史
GET	/api/memory	列出记忆文件
GET	/api/git/status	Git 状态
POST	/api/git/commit	Git 提交
GET	/api/templates	列出项目模板
POST	/api/templates/create	创建模板
POST	/api/templates/apply	应用模板
DELETE	/api/templates/:id	删除模板
POST	/api/sync/push	远程同步推送（Lite 版禁用）
POST	/api/sync/pull	远程同步拉取（Lite 版禁用）
GET	/api/sync/status	同步状态
DELETE	/api/detail-log	清空详情日志

---

四、AI 工具 src/tools/

工具注册 index.js

函数	说明
registerAllTools(registry, config, projectContext, {localWorkspace})	注册核心工具（24 个，始终可用）
registerIntelligenceTools(registry, config, {symbolIndex, impactAnalyzer, autoFix, projectContext})	注册智能工具（8 个，需 symbolIndex 初始化后）

核心文件工具

工具名	参数	说明
ReadFile	file_path, offset?, limit?	读取文件（行号、二进制检测、编码 fallback）
EditFile	file_path, old_string, new_string, replace_all?	原子替换（临时文件 + rename，undo 栈）
WriteFile	file_path, content	创建/覆写文件（自动创建目录）
Bash	command, timeout?	执行 shell 命令（默认 120s 超时）
Grep	pattern, path?, output_mode?, glob?, context?, case_insensitive?, head_limit?	ripgrep/grep 搜索
Glob	pattern, path?	递归模式匹配（按 mtime 排序）

交互工具

工具名	参数	说明
TodoWrite	todos[]	任务进度管理（同时只能一个 in_progress）
SubAgent	prompt, agentType?, maxTurns?, runInBackground?, resume?, isolation?	启动子 Agent（explore/plan/generate/general）
AskUserQuestion	question, options[], multiSelect?	UI 选择控件（拦截式）
Memory	operation, scope?, key?, value?, query?	持久记忆（read/write/append/list/delete/search）
ToolSearch	query?, activate?	发现并激活延迟工具

VL 生成工具

工具名	参数	说明
VLGenerate	action, userRequest?, workflow?, targetLang?	项目代码生成（auto/meta-direct/3-file/6-file/9-file）
VLAdjust	action, changeRequest?, workflow?, targetLang?	项目修改（add-page/add-service/theme-customize/general）
WorkflowRun	mode, workflow_path?, params?, workspace_id?	执行工作流 JSON（SSE 事件广播）

VL 验证工具

工具名	参数	说明
VLCompile	—	调用 parsevl API 编译
VLLint	—	云端 lint 检查
VLParse	file_path?	解析 VL 文件结构
VLValidate	file_path?	VL 语法验证
VLSyntaxRef	topic?	VL 语法参考查询

VL 智能工具（需 symbolIndex）

工具名	参数	说明
VLSymbols	action, name?, prefix?, file_path?	符号定义/引用/补全/大纲
VLImpact	action, symbol?, oldName?, newName?	影响分析（removal/rename/dead_code）
VLEditSection	file_path, section_name, new_content	按 section 精确编辑
VLAutoFix	file_path?	自动修复 VL 语法问题
VLCascadeEdit	file_path, changes, cascade?	级联编辑（跨文件影响传播）
MetaDiff	old_meta?, new_meta?	ProjectMeta 差异比较（确定性，无 LLM）
SectionDiff	base_content, incoming_content, strategy?	Section 级别差异合并
VLMetaTest	action, meta?	从 Meta 生成测试骨架
VLMetadata	action?	提取/刷新 ProjectMeta
VLComponentTest	component?, file_path?	组件交互测试

外部服务工具

工具名	参数	说明
WorkspaceAPI	action, gid?, path?, content?, files?	本地/云端 Workspace API 操作
ComponentFetch	action, keyword?, category?, url?, name?, content?	组件库搜索/获取/发布
DocCenter	action, docId?, path?, keyword?	DocCenter 文档 CRUD
BrowserInspect	action, selector?, expression?, url?	Playwright 浏览器操作
AutoTestPipeline	action, testCases?, params?	自动测试流水线（生成→运行→评估→修复→报告）

---

五、VL 语言引擎 src/vl/

project-context.js — VLProjectContext

VL 项目检测和扫描（零 API 成本）。

方法	说明
load()	扫描目录，检测 VL 项目，加载配置/元数据/规则
scan()	重新扫描（带并发锁）
getVLFiles()	返回 VL 源文件列表
loadProjectMeta()	加载或自动提取 ProjectMeta/1.0
getFilesByType(type)	按类型过滤（app/section/component/service/database/theme）
getSummary()	返回项目摘要
isVLProject()	是否为 VL 项目
getAllFiles()	返回所有文件

symbol-index.js — VLSymbolIndex

符号索引（go-to-definition、find-references、auto-complete）。

方法	说明
build()	解析所有文件，构建完整索引
updateFile(filePath)	增量更新单文件
goToDefinition(name)	符号定义位置
findReferences(name)	查找所有引用
autoComplete(prefix, options)	符号补全（支持 $var、--、@event 前缀）
getSymbolInfo(name)	hover 信息
getFileOutline(filePath)	文件符号大纲
getCrossReferenceMap()	文件依赖图
getStats()	统计（符号数、引用数、耗时）

smart-context.js — SmartContextLoader

智能上下文加载（依赖图 + 最近编辑 + 编译错误 + 对话历史）。

方法	说明
buildGraph()	构建依赖图
discoverRelevantFiles(userMessage)	分析用户消息，返回相关文件
loadContext(relevantFiles, userMessageLength)	加载文件到上下文（智能截断）
recordEdit(filePath)	记录文件编辑
updateCompileErrors(errList)	更新编译错误文件集

blueprint-context.js — BlueprintContext

蓝图上下文（PRD/ServiceMap/UIMap 或 ProjectMeta/1.0）。

方法	说明
load()	加载蓝图（优先 ProjectMeta，fallback 3-file）
loadFromProjectMeta(meta)	从 ProjectMeta 映射到蓝图
getContextForFile(filePath)	返回与文件相关的蓝图片段
findServicesForSection(sectionName)	查找 section 使用的 service
findTablesForService(serviceName)	查找 service 访问的数据表
getValueDomains()	返回值域（枚举/常量）

impact-analyzer.js — ImpactAnalyzer

跨文件 break 检测。

方法	说明
analyzeRemoval(symbolName)	分析删除符号的影响
analyzeRename(oldName, newName)	分析重命名的影响
analyzeServiceChange(serviceDomainName, methodName)	分析服务合约变更影响
analyzeComponentChange(componentName, changeType, symbolName)	分析组件接口变更影响
fullProjectScan()	全项目扫描（未使用符号、断开引用、未定义 token）

auto-fix.js — VLAutoFix

自动修复 VL 语法问题。

方法	说明
fix(filePath)	修复单文件，返回 {fixed, changes[], content}
fixAndSave(filePath)	修复并写入磁盘
fixAll()	修复所有 VL 文件

metadata-extractor.js — 元数据提取函数

函数	说明
extractFromFileTree(fileTree, workDir)	从 {path: content} 提取完整 ProjectMeta
extractSingleFile(filePath, content, workDir)	解析单文件为 Meta 条目
mergeIntoMeta(meta, extracted)	合并单文件提取到现有 Meta
validateMeta(meta)	验证 Meta 一致性

meta-diff.js — Meta 差异比较

函数	说明
computeMetaDiff(oldMeta, newMeta, symbolIndex)	确定性 diff（毫秒级，无 LLM），返回 {added, removed, modified, affectedFiles, cascadeImpact, summary}

section-diff.js — Section 差异合并

函数	说明
parseSections(content)	解析为 Map<sectionName, content>
sectionDiff(oldContent, newContent)	返回 {added, removed, modified, unchanged}
mergeSections(base, incoming, strategy, sectionsToReplace)	合并（prefer_new/prefer_base/selective）
smartMerge(base, incoming)	仅替换修改的 section

workflow-executor.js — WorkflowExecutor

VL-Workflow-Engine 桥接。

方法	说明
execute(workflow, params, callbacks)	执行工作流 JSON
resume(nodeId, payload)	恢复暂停的工作流
abort()	中止工作流
_buildLLMAdapter()	构建 LLM 适配器
_buildFileAdapter()	构建文件适配器（带 section-merge）
_executeMetaDiff(...)	MetaDiff 节点自定义处理器
_executeComponentFetch(...)	ComponentFetch 节点自定义处理器
_resolveDocCenterDocs(docs, cb)	按 path 获取 DocCenter 文档

generation-pipeline.js — GenerationPipeline

8-Agent 编排管线（PRD → DB → ServiceMap → UIMap → CP → VS → SC → VX）。

方法	说明
run(params, callbacks)	运行完整 8 阶段管线
callLLM(messages, opts)	调用 Claude LLM
parallelGenerate(items, promptFn, pathFn, cb)	并行生成（3 并发）
writeArtifact(relativePath, content)	写入生成的文件

meta-test-generator.js — 测试骨架生成

函数	说明
generateTestSkeleton(meta, previewUrls, options)	从 ProjectMeta 确定性生成测试用例（无 LLM）
generateAppSmokeTest(...)	生成 App 冒烟测试
generateSectionNavTest(...)	生成 Section 导航测试
generateCRUDWorkflowTest(...)	生成 CRUD 工作流测试

---

六、本地引擎 src/engine/

local-workspace.js — LocalWorkspace

本地文件系统实现 VL Workspace API（替代远程 REST API）。

方法	说明
createFile({gid, path, content})	创建文件
listFile({gid, path})	列出文件（递归）
readFile({gid, path})	读取文件
writeFile({gid, path, content})	写入文件
deleteFile({gid, path})	删除文件
createFiles/readFiles/writeFiles/deleteFiles	批量操作
createDoc/listDoc/readDoc/writeDoc/deleteDoc	文档操作（JSON 存储）

workflow-engine-manager.js — WorkflowEngineManager

Go 工作流引擎生命周期管理。

方法	说明
start()	启动 Go 引擎（服务器模式）
stop()	优雅停止（SIGTERM → SIGKILL）
isReady()	检查引擎健康
streamWorkflow(options)	SSE 事件 async generator
runWorkflowCLI(options)	CLI 模式 fallback

---

七、云端与 MCP

cloud/cloud-api.js — CloudAPI

VisualLogic 云平台 API 客户端（27 个方法）。

方法	说明
login(username, password, companyName)	企业账号登录
googleLoginOrRegister({email, name, id, picture})	Google OAuth
validateSession()	验证 session
listApps/getWorkGroup/getWorkConfig	应用/工作组查询
listFiles/readFile/writeFile/deleteFiles	云端文件操作
compileWorkspace/lintWorkspace	云端编译/lint
syncPush/syncPull/syncAndCompile	同步 + 编译
launchVersion/queryBalance	发布/余额查询

mcp/mcp-server.js — MCP Server

stdio JSON-RPC MCP 服务器，暴露 VLCode 工具给 Claude CLI。

MCP 方法	说明
initialize()	返回服务器信息 + 能力
tools/list()	从 VLCode HTTP 获取工具列表
tools/call({name, arguments})	执行工具并返回结果

---

八、数据常量 src/data/

versions.js

常量	值	说明
VL_VERSION	"3.5"	VL 语法版本
THEME_VERSION	"6.5"	Theme 版本
STYLESPACE_VERSION	"1.6"	StyleSpace 版本
PARSEVL_URL	"https://bla...on.aws"	编译 API

doc-paths.js

导出	说明
DOCCENTER_API_URL	云端 DocCenter API
DOC_REGISTRY	完整路径注册表（alias → {path, docId, desc}）
PATH_MAP	反向查找（path → info）
pathFor(alias)	按别名获取路径号
docIdFor(alias)	按别名获取文档 ID
resolveDocRef(ref)	标准化文档引用

---

九、工具函数 src/utils/

config.js

函数	说明
loadConfig(args)	加载配置（CLI args → .env → 环境变量 → 默认值）
APP_VERSION	从 package.json 读取版本号

默认配置：

{
  model: 'claude-opus-4-6',
  maxOutputTokens: 32000,
  port: 3300,
  llmProvider: 'cli',           // 仅 CLI（Team 订阅）
  workflowMode: 'local',
}

API Key 保护： 启动时检测 ANTHROPIC_API_KEY，警告并从 process.env 中移除。

zip-extract.js

函数	说明
extractZip(base64, targetDir)	解压 base64 ZIP 到目标目录

---

统计汇总

类别	数量
JS 模块总数	84
核心引擎模块	9
HTTP 路由文件	11
HTTP 端点	127
AI 工具	34 (24 核心 + 8 智能 + 2 条件)
VL 语言引擎模块	15
本地引擎模块	3
云端/MCP	2
数据常量	3
工具函数	2
函数/方法总数	200+