# 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 读取版本号 |

**默认配置：**
```javascript
{
  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+** |