Kilo Code 项目整体结构设计

---

一、项目概述

1.1 项目定位

Kilo Code 是一个开源的 VSCode AI 智能编程助手扩展，基于 Roo Code 和 Cline 项目演进而来。项目致力于提供：

• 自然语言编程：通过自然语言描述生成代码
• 任务自动化：自动化重复性编码任务
• 智能重构：自动重构和改进现有代码
• 多模式支持：Architect（架构）、Coder（编码）、Debugger（调试）等多种工作模式
• MCP 生态集成：通过 MCP Server Marketplace 扩展 AI 能力

1.2 技术栈

前端技术栈：

• React 18.3.1 + TypeScript 5.8.3
• Vite 6.3.5（构建工具）
• Tailwind CSS 4.0（样式框架）
• Radix UI（组件库）
• i18next（国际化）

后端技术栈：

• Node.js 20.19.2
• VSCode Extension API
• Anthropic SDK（AI 模型调用）
• pnpm（包管理器）

跨平台支持：

• VSCode Extension（主要平台）
• JetBrains Plugin（通过 RPC 桥接）

1.3 快速开始

安装方式

方式一：从 VSCode Marketplace 安装（推荐）

1. 打开 VSCode
2. 点击左侧活动栏的扩展图标
3. 搜索 “Kilo Code”
4. 点击"安装"按钮

方式二：从 VSIX 文件安装

1. 下载最新的 .vsix 文件
2. 在 VSCode 中打开命令面板
3. 输入 “Extensions: Install from VSIX…”
4. 选择下载的 VSIX 文件

方式三：从源码构建

# 克隆仓库
git clone https://github.com/kilocode/kilocode.git
cd kilocode

# 安装依赖
pnpm install

# 构建扩展
pnpm build

# 打包 VSIX
pnpm vsix

# 安装生成的 VSIX 文件
code --install-extension bin/kilo-code-*.vsix

基本使用

1. 配置 API Key

• 点击侧边栏的 Kilo Code 图标
• 点击"设置"按钮
• 选择 AI 提供商（如 Anthropic、OpenAI、Gemini 等）
• 输入对应的 API Key
• 选择模型（如 Claude 3.5 Sonnet、GPT-4 等）

2. 开始对话

• 在聊天框中输入你的需求，例如：
  • “帮我创建一个 React 组件”
  • “重构这个函数，提高可读性”
  • “找出这段代码的 bug”
• Kilo Code 会自动分析你的需求并执行相应操作

3. 选择工作模式

• Architect（架构师）：适合项目规划、架构设计
• Coder（编码者）：适合编写和修改代码
• Debugger（调试器）：适合查找和修复 bug
• Ask（提问）：适合代码咨询和学习

4. 使用高级功能

• 代码索引：启用语义搜索，快速定位代码
• MCP 集成：连接外部工具和服务（如 GitHub、文件系统等）
• Ghost 自动补全：获得 AI 驱动的代码建议
• 任务历史：查看和恢复之前的对话

示例场景

场景 1：创建新功能

用户：帮我创建一个用户登录页面，包含表单验证
Kilo Code：
1. 分析项目结构
2. 创建 LoginPage.tsx 组件
3. 添加表单验证逻辑
4. 创建相应的样式文件
5. 更新路由配置

场景 2：代码重构

用户：重构 UserService.ts，使用依赖注入模式
Kilo Code：
1. 分析现有代码结构
2. 创建接口定义
3. 重构为依赖注入模式
4. 更新所有调用点
5. 添加单元测试

场景 3：Bug 修复

用户：修复登录时的 token 过期问题
Kilo Code：
1. 搜索相关代码
2. 分析 token 处理逻辑
3. 识别问题根源
4. 实现自动刷新机制
5. 添加错误处理

---

二、整体架构设计

2.1 分层架构

┌─────────────────────────────────────────────────────────────┐
│                      用户界面层 (UI Layer)                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  React Webview (webview-ui/)                         │   │
│  │  - ChatView, SettingsView, McpView, HistoryView     │   │
│  │  - 基于 Radix UI + Tailwind CSS                      │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕ VSCode Webview API
┌─────────────────────────────────────────────────────────────┐
│                   扩展核心层 (Extension Core)                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ClineProvider (src/core/webview/)                   │   │
│  │  - Webview 生命周期管理                              │   │
│  │  - 消息路由与分发                                     │   │
│  │  - 任务栈管理                                         │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Task (src/core/task/)                               │   │
│  │  - 任务执行引擎                                       │   │
│  │  - API 请求循环                                       │   │
│  │  - 工具调用编排                                       │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                    服务层 (Service Layer)                    │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
│  │   MCP    │  Code    │  Ghost   │Terminal  │  Cloud   │   │
│  │  Server  │  Index   │Completion│ Registry │  Service │   │
│  │  Manager │  Manager │  Service │          │          │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                   工具层 (Tools Layer)                       │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  20+ 内置工具                                         │   │
│  │  - read_file, write_to_file, execute_command        │   │
│  │  - apply_diff, search_and_replace                   │   │
│  │  - browser_action, use_mcp_tool                     │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                   API 层 (API Layer)                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ApiHandler (src/api/)                               │   │
│  │  - 支持 20+ AI 模型提供商                             │   │
│  │  - 流式响应处理                                       │   │
│  │  - Token 计数与缓存                                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                 集成层 (Integration Layer)                   │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐   │
│  │  Editor  │ Terminal │  Git     │ Browser  │  File    │   │
│  │  (Diff)  │          │          │ (Puppeteer)│ System │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↕
┌─────────────────────────────────────────────────────────────┐
│                 持久化层 (Persistence Layer)                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  - GlobalState (VSCode ExtensionContext)             │   │
│  │  - Task History (JSON files)                        │   │
│  │  - API Conversation History                         │   │
│  │  - Code Index Cache                                 │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

2.2 核心模块关系图

---

三、目录结构设计

3.1 根目录结构

kilocode/
├── src/                          # 扩展核心代码
│   ├── core/                     # 核心功能模块
│   ├── api/                      # API 处理层
│   ├── services/                 # 服务层
│   ├── integrations/             # 集成层
│   ├── utils/                    # 工具函数
│   ├── shared/                   # 共享类型和常量
│   ├── activate/                 # 激活相关
│   ├── extension.ts              # 扩展入口
│   └── package.json              # 扩展配置
│
├── webview-ui/                   # React UI 代码
│   ├── src/
│   │   ├── components/           # React 组件
│   │   ├── context/              # React Context
│   │   ├── utils/                # UI 工具函数
│   │   └── App.tsx               # UI 入口
│   └── package.json
│
├── apps/                         # 应用程序
│   ├── vscode-e2e/               # E2E 测试
│   └── web-evals/                # 评估系统
│
├── jetbrains/                    # JetBrains 插件
│   ├── plugin/                   # Kotlin 插件代码
│   └── host/                     # 扩展宿主桥接
│
├── packages/                     # 共享包
│   ├── types/                    # TypeScript 类型定义
│   ├── cloud/                    # 云服务
│   ├── telemetry/                # 遥测服务
│   └── ipc/                      # 进程间通信
│
├── scripts/                      # 构建脚本
├── doc/                          # 文档
└── package.json                  # 根配置

3.2 核心模块详细结构

3.2.1 src/core/ - 核心功能

src/core/
├── webview/                      # Webview 管理
│   ├── ClineProvider.ts          # 核心 Provider 类
│   ├── webviewMessageHandler.ts  # 消息处理器
│   ├── getNonce.ts               # 安全随机数
│   └── getUri.ts                 # URI 工具
│
├── task/                         # 任务管理
│   ├── Task.ts                   # 任务执行引擎
│   └── TaskLike.ts               # 任务接口
│
├── prompts/                      # 提示词系统
│   ├── system.ts                 # 系统提示词构建
│   ├── sections/                 # 提示词片段
│   │   ├── rules.ts              # 规则片段
│   │   ├── mcp-servers.ts        # MCP 服务器片段
│   │   └── custom-system-prompt.ts
│   └── tools/                    # 工具描述
│
├── tools/                        # 工具实现
│   ├── readFileTool.ts
│   ├── writeToFileTool.ts
│   ├── executeCommandTool.ts
│   └── ...
│
├── config/                       # 配置管理
│   ├── ContextProxy.ts           # 全局状态代理
│   ├── ProviderSettingsManager.ts # 提供商配置
│   └── CustomModesManager.ts     # 自定义模式
│
├── diff/                         # Diff 策略
│   └── strategies/
│       ├── multi-file-search-replace.ts
│       └── multi-search-replace.ts
│
└── task-persistence/             # 任务持久化
    ├── apiMessages.ts
    ├── taskMessages.ts
    └── taskMetadata.ts

3.2.2 src/api/ - API 处理层

src/api/
├── index.ts                      # API Handler 工厂
├── providers/                    # 模型提供商
│   ├── anthropic.ts              # Anthropic (Claude)
│   ├── openai.ts                 # OpenAI (GPT)
│   ├── gemini.ts                 # Google Gemini
│   ├── openrouter.ts             # OpenRouter
│   ├── kilocode-openrouter.ts    # Kilo 定制 OpenRouter
│   ├── deepseek.ts               # DeepSeek
│   ├── ollama.ts                 # Ollama (本地)
│   └── ...                       # 20+ 提供商
│
└── transform/                    # 数据转换
    ├── stream.ts                 # 流式响应处理
    ├── caching/                  # 缓存策略
    │   ├── anthropic.ts
    │   └── gemini.ts
    └── image-cleaning.ts         # 图片处理

3.2.3 src/services/ - 服务层

src/services/
├── mcp/                          # MCP 服务
│   ├── McpHub.ts                 # MCP 中心
│   ├── McpServerManager.ts       # 服务器管理
│   └── McpClient.ts              # 客户端
│
├── code-index/                   # 代码索引
│   ├── manager.ts                # 索引管理器
│   ├── embedder.ts               # 向量嵌入
│   ├── vector-store.ts           # 向量存储
│   └── processors/               # 文件处理器
│
├── ghost/                        # Ghost 自动补全
│   ├── GhostProvider.ts
│   └── GhostModel.ts
│
├── browser/                      # 浏览器自动化
│   ├── BrowserSession.ts
│   └── UrlContentFetcher.ts
│
├── terminal-welcome/             # 终端欢迎
├── commit-message/               # Git 提交消息
├── checkpoints/                  # 检查点系统
└── marketplace/                  # 市场管理

3.2.4 webview-ui/src/ - UI 组件

webview-ui/src/
├── components/
│   ├── chat/                     # 聊天界面
│   │   ├── ChatView.tsx
│   │   ├── ChatTextArea.tsx
│   │   ├── TaskActions.tsx
│   │   └── MessageItem.tsx
│   │
│   ├── settings/                 # 设置界面
│   │   ├── SettingsView.tsx
│   │   ├── ApiOptions.tsx
│   │   └── providers/            # 各提供商配置
│   │
│   ├── mcp/                      # MCP 管理
│   │   ├── McpView.tsx
│   │   └── McpToolRow.tsx
│   │
│   ├── history/                  # 历史记录
│   │   └── HistoryView.tsx
│   │
│   ├── modes/                    # 模式管理
│   │   └── ModesView.tsx
│   │
│   └── ui/                       # 基础 UI 组件
│       ├── button.tsx
│       ├── dialog.tsx
│       ├── select.tsx
│       └── ...
│
├── context/                      # React Context
│   └── ExtensionStateContext.tsx
│
├── utils/                        # 工具函数
│   ├── vscode.ts                 # VSCode API 封装
│   └── validate.ts               # 验证函数
│
└── App.tsx                       # 应用入口

---

四、核心模块设计

4.1 扩展激活流程 (src/extension.ts)

export async function activate(context: vscode.ExtensionContext) {
    // 1. 初始化输出通道
    outputChannel = vscode.window.createOutputChannel("Kilo-Code")
    
    // 2. 配置迁移
    await migrateSettings(context, outputChannel)
    
    // 3. 初始化遥测服务
    const telemetryService = TelemetryService.createInstance()
    telemetryService.register(new PostHogTelemetryClient())
    
    // 4. 初始化云服务（可选）
    const cloudService = await CloudService.createInstance(context, cloudLogger)
    
    // 5. 初始化 MDM 服务
    const mdmService = await MdmService.createInstance(cloudLogger)
    
    // 6. 初始化国际化
    initializeI18n(context.globalState.get("language"))
    
    // 7. 初始化终端注册表
    TerminalRegistry.initialize()
    
    // 8. 创建上下文代理
    const contextProxy = await ContextProxy.getInstance(context)
    
    // 9. 初始化代码索引管理器
    const codeIndexManagers = await initializeCodeIndexManagers(context, contextProxy)
    
    // 10. 创建 ClineProvider 实例
    const provider = new ClineProvider(context, outputChannel, "sidebar", contextProxy, mdmService)
    
    // 11. 注册 Webview 视图提供者
    context.subscriptions.push(
        vscode.window.registerWebviewViewProvider(
            ClineProvider.sideBarId,
            provider,
            { webviewOptions: { retainContextWhenHidden: true } }
        )
    )
    
    // 12. 注册命令
    registerCommands({ context, outputChannel, provider })
    
    // 13. 注册代码操作
    registerCodeActions(context)
    
    // 14. 注册终端操作
    registerTerminalActions(context)
    
    // 15. 初始化 MCP Hub
    await McpServerManager.getInstance(context, provider)
    
    // 16. 注册 Ghost 自动补全
    registerGhostProvider(context)
    
    // 17. 注册提交消息提供者
    registerCommitMessageProvider(context)
    
    // 18. 暴露 API
    return new API(context, outputChannel, provider)
}

4.2 ClineProvider 核心职责

ClineProvider 是整个扩展的核心协调者，负责：

1. Webview 生命周期管理

   • 创建和销毁 Webview
   • 设置 HTML 内容
   • 管理 Webview 可见性

2. 消息路由

   • 监听来自 Webview 的消息
   • 分发到对应的处理器
   • 向 Webview 发送状态更新

3. 任务栈管理

   • 维护任务栈 (clineStack)
   • 创建新任务
   • 管理子任务

4. 状态管理

   • 管理全局状态 (通过 ContextProxy)
   • 同步状态到 Webview
   • 持久化配置

5. 服务协调

   • 协调 MCP Hub
   • 协调 Code Index Manager
   • 协调 Cloud Service

4.3 Task 任务执行引擎

Task 类是任务执行的核心，负责：

1. API 请求循环 (recursivelyMakeClineRequests)

   • 构建系统提示词
   • 调用 AI API
   • 处理流式响应
   • 执行工具调用
   • 递归继续请求

2. 工具执行 (presentAssistantMessage)

   • 工具权限检查
   • 用户批准流程
   • 工具调用
   • 结果处理

3. 上下文管理

   • 消息历史维护
   • 上下文长度检查
   • 自动压缩

4. 状态持久化

   • 保存 API 对话历史
   • 保存 UI 消息
   • 保存任务元数据

4.4 工具系统架构

工具系统采用插件化设计，每个工具都是独立的模块：

// 工具接口
interface Tool {
    name: string
    description: string
    inputSchema: object
    execute(task: Task, params: any): Promise<string>
}

// 工具注册
const TOOLS = {
    read_file: readFileTool,
    write_to_file: writeToFileTool,
    execute_command: executeCommandTool,
    apply_diff: applyDiffTool,
    search_and_replace: searchAndReplaceTool,
    browser_action: browserActionTool,
    use_mcp_tool: useMcpTool,
    // ... 20+ 工具
}

工具分类：

1. 文件操作工具

   • read_file - 读取文件
   • write_to_file - 写入文件
   • apply_diff - 应用差异
   • search_and_replace - 搜索替换
   • insert_content - 插入内容

2. 命令执行工具

   • execute_command - 执行 Shell 命令
   • list_files - 列出文件
   • list_code_definition_names - 列出代码定义

3. 浏览器工具

   • browser_action - 浏览器操作
   • url_screenshot - URL 截图

4. 搜索工具

   • search_files - 搜索文件
   • codebase_search - 代码库语义搜索

5. MCP 工具

   • use_mcp_tool - 调用 MCP 工具
   • access_mcp_resource - 访问 MCP 资源

6. 任务管理工具

   • new_task - 创建新任务
   • attempt_completion - 尝试完成任务

4.5 API 处理层设计

ApiHandler 是所有 AI 模型提供商的统一接口：

interface ApiHandler {
    // 创建消息（流式）
    createMessage(
        systemPrompt: string,
        messages: Anthropic.Messages.MessageParam[],
        metadata?: ApiHandlerCreateMessageMetadata
    ): ApiStream
    
    // 获取模型信息
    getModel(): { id: string; info: ModelInfo }
}

支持的提供商（20+）：

提供商	类名	特点
Anthropic	AnthropicHandler	Claude 系列，支持 Prompt Caching
OpenAI	OpenAiHandler	GPT 系列，支持 Responses API
Google Gemini	GeminiHandler	Gemini 系列，支持 Context Caching
OpenRouter	OpenRouterHandler	聚合多个提供商
DeepSeek	DeepSeekHandler	DeepSeek 系列
Ollama	NativeOllamaHandler	本地模型
AWS Bedrock	AwsBedrockHandler	AWS 托管
Vertex AI	VertexHandler	Google Cloud
…	…	…

流式响应处理：

// ApiStream 是一个异步生成器
for await (const chunk of apiStream) {
    if (chunk.type === "text") {
        // 处理文本内容
    } else if (chunk.type === "tool_use") {
        // 处理工具调用
    } else if (chunk.type === "usage") {
        // 处理 Token 使用统计
    }
}

4.6 MCP 集成架构

MCP (Model Context Protocol) 是扩展 AI 能力的标准协议。

┌─────────────────────────────────────────────────────────┐
│                    Kilo Code Extension                   │
│  ┌───────────────────────────────────────────────────┐  │
│  │              McpHub (MCP 中心)                     │  │
│  │  - 管理所有 MCP 服务器连接                         │  │
│  │  - 提供工具和资源的统一访问接口                    │  │
│  └───────────────────────────────────────────────────┘  │
│           ↓                ↓                ↓            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ MCP Server 1 │  │ MCP Server 2 │  │ MCP Server N │  │
│  │  (Filesystem)│  │   (GitHub)   │  │   (Custom)   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘

MCP 服务器配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"],
      "disabled": false
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

4.7 代码索引系统

Code Index Manager 提供语义搜索能力：

┌─────────────────────────────────────────────────────────┐
│                  Code Index Manager                      │
│  ┌───────────────────────────────────────────────────┐  │
│  │  1. File Processor (文件处理器)                   │  │
│  │     - 解析代码文件                                 │  │
│  │     - 提取代码块                                   │  │
│  │     - Tree-sitter 语法分析                        │  │
│  └───────────────────────────────────────────────────┘  │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │  2. Embedder (向量嵌入器)                         │  │
│  │     - 调用嵌入模型 API                            │  │
│  │     - 生成向量表示                                 │  │
│  └───────────────────────────────────────────────────┘  │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │  3. Vector Store (向量存储)                       │  │
│  │     - 存储向量数据                                 │  │
│  │     - 相似度搜索                                   │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

支持的嵌入模型：

• OpenAI (text-embedding-3-small/large)
• Ollama (本地嵌入模型)
• Gemini (text-embedding-004)
• Mistral (mistral-embed)

---

五、数据流设计

5.1 消息流转架构

详见 doc/kilo 消息流转过程.md，这里简要总结：

用户输入 → Webview UI → postMessage → ClineProvider 
→ webviewMessageHandler → Task.handleWebviewAskResponse 
→ Task.recursivelyMakeApiRequests → ApiHandler.createMessage 
→ 流式响应处理 → 工具执行 → 继续 API 请求 → 完成

5.2 状态管理架构

全局状态管理：

// ContextProxy 是全局状态的代理
class ContextProxy {
    // 获取值
    getValue<K extends keyof GlobalState>(key: K): GlobalState[K] {
        // 实现省略
    }
    
    // 设置值
    async setValue<K extends keyof GlobalState>(key: K, value: GlobalState[K]): Promise<void> {
        // 实现省略
    }
    
    // 批量获取
    getValues(): GlobalState {
        // 实现省略
    }
}

// GlobalState 包含所有全局配置
interface GlobalState {
    apiConfiguration: ProviderSettings
    mode: string
    customModes: Mode[]
    alwaysAllowReadOnly: boolean
    alwaysAllowWrite: boolean
    alwaysAllowExecute: boolean
    mcpServers: McpServer[]
    // ... 50+ 配置项
}

状态同步流程：

1. 用户在 UI 修改配置
   ↓
2. Webview 发送消息到 Extension
   ↓
3. ClineProvider 更新 GlobalState (通过 ContextProxy)
   ↓
4. ContextProxy 持久化到 VSCode ExtensionContext
   ↓
5. ClineProvider.postStateToWebview() 同步到 UI
   ↓
6. Webview 更新显示

5.3 持久化设计

持久化层次：

1. VSCode ExtensionContext

   • GlobalState (全局配置)
   • SecretStorage (敏感信息，如 API Key)

2. 文件系统

   • 任务历史：~/.vscode/extensions/kilocode.kilo-code-*/tasks/{taskId}/
     • messages.json - UI 消息
     • api_conversation_history.json - API 对话历史
     • metadata.json - 任务元数据
   • 代码索引缓存：~/.vscode/extensions/kilocode.kilo-code-*/code-index/
   • MCP 配置：~/.vscode/extensions/kilocode.kilo-code-*/mcp-servers.json

任务持久化流程：

// 保存任务消息
await saveTaskMessages({
    messages: clineMessages,
    taskId: task.taskId,
    globalStoragePath: context.globalStorageUri.fsPath
})

// 保存 API 对话历史
await saveApiMessages({
    messages: apiConversationHistory,
    taskId: task.taskId,
    globalStoragePath: context.globalStorageUri.fsPath
})

// 保存任务元数据
await saveTaskMetadata({
    messages: clineMessages,
    taskId: task.taskId,
    taskNumber: taskNumber,
    globalStoragePath: context.globalStorageUri.fsPath,
    workspace: workspacePath,
    mode: mode
})

---

六、跨平台支持

6.1 JetBrains 插件架构

Kilo Code 通过 RPC 桥接支持 JetBrains IDE：

┌─────────────────────────────────────────────────────────┐
│              JetBrains IDE (Kotlin Plugin)               │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Plugin Entry (KiloCodePlugin.kt)                 │  │
│  └───────────────────────────────────────────────────┘  │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Extension Host Manager                           │  │
│  │  - 启动 Node.js 进程                              │  │
│  │  - 管理 RPC 连接                                  │  │
│  └───────────────────────────────────────────────────┘  │
│                        ↕ RPC Protocol                    │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Extension Host (Node.js)                         │  │
│  │  - 运行 VSCode Extension 代码                     │  │
│  │  - 模拟 VSCode API                                │  │
│  └───────────────────────────────────────────────────┘  │
│                        ↕                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Service Proxy Registry                           │  │
│  │  - MainThreadEditor                               │  │
│  │  - MainThreadTerminal                             │  │
│  │  - MainThreadStorage                              │  │
│  │  - MainThreadWebview (JCEF)                       │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

关键桥接服务：

1. MainThreadEditor - 编辑器操作

   • 打开文件
   • 应用编辑
   • Diff 视图

2. MainThreadTerminal - 终端操作

   • 创建终端
   • 执行命令

3. MainThreadWebview - Webview 渲染

   • 使用 JCEF (Java Chromium Embedded Framework)
   • 双向消息通信

4. MainThreadStorage - 存储服务

   • 持久化配置
   • 状态管理

---

七、构建与部署

7.1 构建流程

# 1. 安装依赖
pnpm install

# 2. 构建 Webview UI
cd webview-ui
pnpm build

# 3. 编译 TypeScript
cd ../src
tsc -b

# 4. 打包扩展
pnpm bundle

# 5. 生成 VSIX
pnpm vsix

构建产物：

• bin/kilo-code-{version}.vsix - VSCode 扩展包
• src/webview-ui/ - 编译后的 Webview 资源
• out/ - 编译后的 TypeScript 代码

7.2 发布流程

VSCode Marketplace：

# 发布到 VSCode Marketplace
vsce publish

# 发布到 Open VSX
ovsx publish

版本管理：

• 使用 Changesets 管理版本
• 自动生成 CHANGELOG
• 语义化版本控制

---

八、测试架构

8.1 测试层次

┌─────────────────────────────────────────────────────────┐
│                    单元测试 (Unit Tests)                 │
│  - Vitest                                                │
│  - 测试工具函数、组件逻辑                                │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  集成测试 (Integration Tests)            │
│  - 测试模块间交互                                        │
│  - API Handler 测试                                      │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                    E2E 测试 (E2E Tests)                  │
│  - apps/vscode-e2e                                       │
│  - 测试完整用户流程                                      │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                    评估系统 (Evals)                      │
│  - apps/web-evals                                        │
│  - 测试 AI 任务完成质量                                  │
└─────────────────────────────────────────────────────────┘

8.2 测试工具

• Vitest - 单元测试框架
• Testing Library - React 组件测试
• Playwright - E2E 测试
• Docker Compose - 评估系统环境

---

九、性能优化

9.1 前端优化

1. 代码分割

   • Vite 自动代码分割
   • 按需加载组件
   • Mermaid 等大型库独立打包

2. 虚拟滚动

   • 使用 react-virtuoso
   • 优化长列表渲染

3. 状态优化

   • 避免不必要的重渲染
   • 使用 useMemo/useCallback

9.2 后端优化

1. 上下文管理

   • 自动压缩长对话
   • Prompt Caching (Anthropic)
   • Context Caching (Gemini)

2. 并发控制

   • 限制并发 API 请求
   • 工具执行队列

3. 缓存策略

   • 模型列表缓存
   • 代码索引缓存
   • MCP 工具缓存

---

十、安全设计

10.1 权限控制

1. 工具权限分级

   • 只读工具（自动批准）
   • 写入工具（需要批准）
   • 命令执行（需要批准）

2. 用户批准流程

   • 显示工具调用详情
   • 用户确认后执行
   • 支持"始终允许"

10.2 敏感信息保护

1. API Key 存储

   • 使用 VSCode SecretStorage
   • 加密存储
   • 不记录到日志

2. 代码保护

   • Roo Protected 文件保护
   • 防止意外修改关键文件

---

十一、扩展性设计

11.1 插件化架构

1. 工具系统

   • 新工具只需实现 Tool 接口
   • 自动注册到系统

2. 模型提供商

   • 新提供商只需继承 BaseProvider
   • 实现 createMessage 方法

3. MCP 服务器

   • 标准 MCP 协议
   • 任意第三方服务器

11.2 自定义模式

用户可以创建自定义工作模式：

{
  "slug": "my-mode",
  "name": "My Custom Mode",
  "roleDefinition": "You are a custom assistant...",
  "groups": ["code", "ask"],
  "customInstructions": "Additional instructions..."
}

---