# https://github.com/Kilo-Org/kilocode 项目说明书生成时间：2026-05-16 18:16:41 UTC ## 目录 - [Kilo Code 简介与快速入门](#introduction) - [项目结构与包组织](#project-structure) - [系统架构设计](#system-architecture) - [Agent 核心系统](#agent-system) - [自动补全系统 (FIM)](#autocomplete-system) - [Agent Manager 工作流管理](#agent-manager) - [MCP 协议与工具集成](#mcp-integration) - [代码索引与语义搜索](#indexing-system) - [IDE 扩展实现](#ide-extensions) - [CLI 工具与 SDK 开发](#cli-and-sdk) ## Kilo Code 简介与快速入门 ### 相关页面相关主题：[系统架构设计](#system-architecture), [IDE 扩展实现](#ide-extensions)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md) - [packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md) - [packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md) - [packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json) - [packages/kilo-ui/src/stories/provider-icon.stories.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/stories/provider-icon.stories.tsx) - [packages/opencode/src/cli/cmd/tui/routes/session/index.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/index.tsx) - [packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx)

# Kilo Code 简介与快速入门 ## 项目概述 Kilo Code 是一个现代化的人工智能辅助编程工具，通过集成多种语言模型和开发工具，为开发者提供智能化的代码编写、理解和编辑体验。该项目采用多平台架构，支持命令行界面（CLI）和 VS Code 扩展两种主要交互方式。 Kilo Code 的核心设计理念是将强大的人工智能能力与开发者的日常工作流程无缝结合，提供快速、准确且上下文感知的代码协助。系统支持多种 AI 提供商，包括 OpenAI、Anthropic、Google、Mistral、Moonshot 等主流模型服务。资料来源：[README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md) ## 系统架构 Kilo Code 采用模块化设计，主要由以下核心包组成： | 包名 | 功能描述 | 技术栈 | |------|---------|--------| | `packages/opencode` | 命令行工具核心，提供 TUI 界面 | TypeScript/Node.js | | `packages/kilo-vscode` | VS Code 扩展，提供图形化界面 | TypeScript/React | | `packages/kilo-ui` | UI 组件库 | Solid.js | | `packages/ui` | 通用 UI 组件 | Solid.js | ```mermaid graph TD A[用户交互层] --> B[CLI TUI 界面] A --> C[VS Code 扩展] B --> D[opencode 核心引擎] C --> E[Webview UI] E --> D D --> F[AI 模型层] F --> G[MCP 服务] F --> H[LSP 服务] D --> I[文件索引系统] G --> J[外部工具集成] ``` ### CLI 架构 (opencode) 命令行工具位于 `packages/opencode` 目录，采用 TUI（文本用户界面）架构。核心模块包括： - **会话管理** (`routes/session/`): 处理 AI 对话和消息显示 - **命令系统** (`cmd/`): 实现各种交互命令 - **提示系统** (`prompt/`): 管理输入和自动完成 CLI 工具支持多种模式切换，包括命令模式、Shell 模式和聊天模式，用户可以通过快捷键在模式间快速切换。资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md) ### VS Code 扩展架构 VS Code 扩展位于 `packages/kilo-vscode` 目录，分为后端和前端两部分： - **后端** (`src/`): 处理与核心引擎的通信 - **前端 Webview** (`webview-ui/`): 使用 Solid.js 构建的图形界面 Webview UI 包含多个核心组件： - **迁移向导** (`migration/MigrationWizard.tsx`): 引导用户完成版本升级 - **市场安装** (`marketplace/InstallModal.tsx`): 插件和工具的安装管理 - **提示输入** (`chat/PromptInput.tsx`): 聊天输入和文件提及功能 - **文件引用** (`hooks/useFileMention.ts`): 文件拖拽和引用解析资料来源：[packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md) ## 核心功能 ### 智能对话与代码生成 Kilo Code 提供完整的对话式编程体验，支持： - **多轮对话**: 维护对话上下文，支持复杂任务的分解和逐步解决 - **代码生成**: 根据自然语言描述生成代码片段 - **代码解释**: 解释现有代码的功能和逻辑 - **错误修复**: 分析错误信息并提供修复建议消息系统支持多种内容类型，包括普通文本、工具调用、推理过程（reasoning）和文件变更。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-100](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/index.tsx) ### 文件引用与附件 Kilo Code 支持通过 `@` 符号引用文件，实现以下功能： | 功能 | 说明 | 支持类型 | |------|------|----------| | 文件提及 | 在对话中引用项目文件 | 文件、文件夹 | | 终端引用 | 引用终端输出内容 | 终端 | | Git 变更引用 | 引用 Git 变更信息 | 分支、差异 | 文件引用系统会自动搜索匹配的文件路径，并在用户输入时提供自动完成建议。拖拽文件到输入区域也会自动创建引用。资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) ### 工具系统 Kilo Code 内置强大的工具系统，支持以下核心工具： | 工具名称 | 功能描述 | |---------|---------| | `Read` | 读取文件内容 | | `Write` | 写入或创建文件 | | `Edit` | 编辑文件指定区域 | | `Grep` | 搜索文件内容 | | `TodoWrite` | 创建和管理待办事项 | | `ApplyPatch` | 应用代码补丁 | 工具输出支持差异视图（Diff View），清晰展示添加、删除和修改的内容。资料来源：[packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx) ### MCP 集成 MCP（Model Context Protocol）支持使 Kilo Code 能够与外部工具和服务进行深度集成： - **OAuth 认证**: 安全处理第三方服务的授权流程 - **实时状态**: 显示 MCP 连接状态和错误信息 - **工具调用**: 通过 MCP 协议调用外部工具状态栏实时显示 MCP 连接状态，绿色圆点表示正常连接，红色圆点表示连接错误。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx) ### LSP 支持 Kilo Code 集成 Language Server Protocol，提供： - 代码补全建议 - 语法检查和错误提示 - 跳转到定义 - 查找引用状态栏显示当前活动的 LSP 服务器数量。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx) ### 推理过程显示对于支持推理的模型，Kilo Code 可以显示 AI 的思考过程： ```mermaid graph LR A[用户输入] --> B[模型推理] B --> C[推理内容] B --> D[最终回答] C -->|过滤 [REDACTED]| E[显示思考] D --> F[工具调用] ``` 推理内容会进行过滤处理，去除 OpenRouter 等服务加密的推理数据（显示为 `[REDACTED]`）。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:100-150](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/index.tsx) ## 支持的 AI 提供商 Kilo Code 支持众多 AI 模型提供商，形成完整的生态系统： | 提供商 | 代码标识 | 说明 | |--------|----------|------| | OpenAI | `openai` | GPT 系列模型 | | Anthropic | `anthropic` | Claude 系列模型 | | Google | `google` | Gemini 系列模型 | | Mistral | `mistral` | Mistral AI 模型 | | Moonshot | `moonshotai` | Kimi 系列模型 | | MiniMax | `minimax` | 混元系列模型 | | OpenRouter | `openrouter` | 多模型聚合 | | Ollama | `ollama-cloud` | 本地模型 | | Groq | `groq` | 高速推理 | | TogetherAI | `togetherai` | 开源模型 | | HuggingFace | `huggingface` | 推理端点 | | LM Studio | `lmstudio` | 本地部署 | 资料来源：[packages/kilo-ui/src/stories/provider-icon.stories.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/stories/provider-icon.stories.tsx) ## 快速入门 ### 安装方式 #### VS Code 扩展安装 1. 打开 VS Code 2. 进入扩展市场，搜索 "Kilo" 3. 点击安装按钮 4. 安装完成后，点击侧边栏的 Kilo 图标开始使用扩展版本信息可在 `package.json` 中查看： ```json { "name": "kilo-vscode", "version": "1.x.x", "displayName": "Kilo" } ``` 资料来源：[packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json) #### CLI 安装 ```bash # 使用 npm 安装 npm install -g @kilocode/opencode # 或使用其他包管理器 brew install kilo-ai/tap/kilocode ``` ### 首次配置首次启动后，系统会显示迁移向导，引导用户了解新版本特性： 1. **性能优化**: 了解新版本的性能改进 2. **界面更新**: 查看新的用户界面设计 3. **Agent 管理器**: 了解增强的多 Agent 支持 4. **基础架构**: 查看底层技术升级资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx) ### 基本使用 #### CLI 模式 ```bash # 启动交互式会话 opencode # 指定模型 opencode --model gpt-4 # 查看帮助 opencode --help ``` #### VS Code 扩展模式 1. 打开命令面板 (`Ctrl+Shift+P` / `Cmd+Shift+P`) 2. 输入 "Kilo" 查找相关命令 3. 选择 "Kilo: 新建对话" 开始会话 4. 在输入框中输入问题或指令 ### 文件操作 #### 在对话中引用文件 ``` @filename.py # 引用单个文件 @src/ # 引用整个目录 @README.md:10-20 # 引用文件特定行 ``` #### 拖拽添加直接将文件从资源管理器拖拽到聊天输入区域，系统会自动创建文件引用。 ### 快捷键 | 操作 | Windows/Linux | macOS | |------|---------------|-------| | 新建对话 | `Ctrl+Shift+K` | `Cmd+Shift+K` | | 打开命令列表 | `Ctrl+/` | `Cmd+/` | | 引用文件 | `@` | `@` | | 斜杠命令 | `/` | `/` | 资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx) ## 认证与授权 ### OAuth 回调处理 Kilo Code 使用 OAuth 2.0 进行第三方服务认证： ```mermaid sequenceDiagram 用户->>Kilo Code: 请求授权 Kilo Code->>第三方服务: 发起 OAuth 请求第三方服务-->>用户: 显示授权页面用户->>第三方服务: 确认授权第三方服务->>Kilo Code: 回调并返回 code Kilo Code->>第三方服务: 交换 access token 第三方服务-->>Kilo Code: 返回 token Kilo Code-->>用户: 授权成功 ``` 授权成功后，页面会自动关闭并将控制权交还给 Kilo Code。资料来源：[packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts) ## 状态与监控 ### 状态栏指示器 CLI 和 VS Code 扩展都在状态栏显示关键信息： | 指示器 | 状态 | 含义 | |--------|------|------| | LSP | • (绿色) | 已连接 LSP 服务器 | | LSP | • (灰色) | 无 LSP 服务器 | | MCP | ⊙ (绿色) | MCP 已连接 | | MCP | ⊙ (红色) | MCP 连接错误 | | Indexing | 文本 | 索引状态 | ### 权限提示当操作需要额外权限时，状态栏会显示警告信息： ``` △ 3 Permissions ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx) ## 常见问题 ### Q: 如何切换 AI 模型？在设置中选择 "Provider" 并配置新的模型提供商，然后在对话中通过 `/model` 命令或设置默认模型进行切换。 ### Q: MCP 连接失败怎么办？ 1. 检查 MCP 服务是否正常运行 2. 验证 OAuth 授权是否过期 3. 查看状态栏的 MCP 错误指示器 4. 重启 Kilo Code 尝试重新连接 ### Q: 如何禁用推理过程显示？在设置中关闭 "Show Thinking" 选项，推理内容将不会在界面中显示。 ### Q: 支持本地模型吗？是的，Kilo Code 支持 Ollama、LM Studio 等本地模型服务。配置相应的提供商地址即可使用。 ## 下一步 - 查看[官方文档](https://kilo.ai/docs/)获取完整使用指南 - 访问[博客](https://blog.kilo.ai/)了解最新更新 - 参与 [GitHub 讨论](https://github.com/Kilo-Org/kilocode/discussions)提出问题和建议 - 报告 [Issue](https://github.com/Kilo-Org/kilocode/issues) 帮助改进产品 --- ## 项目结构与包组织 ### 相关页面相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)

相关源码文件

以下源码文件用于生成本页说明： - [packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx) - [packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx) - [packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx) - [packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx) - [packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) - [packages/opencode/src/cli/cmd/tui/routes/session/index.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/index.tsx) - [packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx) - [packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx) - [packages/ui/src/components/file-icon.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/ui/src/components/file-icon.tsx) - [packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts)

# 项目结构与包组织 ## 概述 KiloCode 是一个模块化的 AI 代码辅助平台，采用 Monorepo 架构组织代码。项目使用 `turbo.json` 作为构建编排工具，将功能划分为多个独立的包（packages），每个包专注于特定的功能领域。 KiloCode 的包组织结构遵循以下核心原则： - **模块独立性**：每个包拥有独立的功能边界，可独立测试和部署 - **代码共享**：通过 `@kilo` 前缀的共享包实现跨包复用 - **多端适配**：支持 VS Code、JetBrains IDE、命令行界面等多种客户端 ## 核心包结构 ### 包架构总览 ```mermaid graph TD subgraph "核心共享包" UI[kilo-ui
UI 组件库] UIShared[ui
通用 UI 工具] end subgraph "平台包" VSCODE[kilo-vscode
VS Code 扩展] JETBRAINS[kilo-jetbrains
JetBrains 插件] OPENCODE[opencode
命令行工具] end subgraph "后端服务" GATEWAY[kilo-gateway
API 网关] INDEXING[kilo-indexing
代码索引服务] end UI --> VSCODE UI --> JETBRAINS UIShared --> UI GATEWAY --> INDEXING style UI fill:#e1f5fe style VSCODE fill:#fff3e0 style OPENCODE fill:#f3e5f5 ``` ### 包功能对照表 | 包名称 | 路径 | 功能描述 | 依赖技术 | |--------|------|----------|----------| | `kilo-vscode` | `packages/kilo-vscode/` | VS Code 扩展后端与 Webview UI | TypeScript, VS Code API | | `kilo-jetbrains` | `packages/kilo-jetbrains/` | JetBrains IDE 插件 | Kotlin, IntelliJ Platform | | `opencode` | `packages/opencode/` | 跨平台命令行界面 | TypeScript, React-like TUI | | `kilo-gateway` | `packages/kilo-gateway/` | 后端 API 网关服务 | TypeScript/Node.js | | `kilo-indexing` | `packages/kilo-indexing/` | 代码语义索引与搜索 | TypeScript | | `kilo-ui` | `packages/kilo-ui/` | React 组件库 | React, TypeScript | | `ui` | `packages/ui/` | 基础 UI 组件与图标 | React, TypeScript | ## 目录结构规范 ### 标准包结构 ``` packages// ├── src/ # 源代码目录 │ ├── index.ts # 包入口文件 │ ├── components/ # 组件目录 │ ├── hooks/ # 自定义 Hooks │ └── utils/ # 工具函数 ├── package.json # 包配置 └── tsconfig.json # TypeScript 配置 ``` ### Webview UI 特殊结构 `kilo-vscode` 包的 webview-ui 采用前后端分离的结构： ``` kilo-vscode/ ├── src/ # VS Code 扩展后端 │ └── extension.ts # 扩展入口 └── webview-ui/ # Webview 前端 ├── src/ │ ├── components/ # React 组件 │ ├── hooks/ # 业务 Hooks │ └── App.tsx # 应用根组件 └── package.json ``` ## 组件组织模式 ### 组件目录结构组件按照功能模块组织在 `components/` 目录下，采用功能域划分： ``` components/ ├── migration/ # 迁移向导模块 │ └── MigrationWizard.tsx ├── chat/ # 聊天界面模块 │ └── PromptInput.tsx ├── marketplace/ # 市场功能模块 │ └── InstallModal.tsx └── [其他功能模块]/ ``` 资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1]() ### 组件分层架构 ```mermaid graph LR A[业务组件
MigrationWizard] --> B[功能组件
PromptInput] B --> C[基础组件
FileIcon] C --> D[UI 原子
Button, TextField] style A fill:#ffcdd2 style B fill:#fff9c4 style C fill:#c8e6c9 style D fill:#bbdefb ``` ## Hooks 与状态管理 ### 自定义 Hooks 模式 `useFileMention` 是典型的自定义 Hook，用于处理文件提及功能： ```typescript export function useFileMention( vscode: VSCodeContext, sessionID?: Accessor, git?: Accessor, ): FileMention { // 文件搜索状态 const [mentionedPaths, setMentionedPaths] = createSignal>(new Set()) const [mentionQuery, setMentionQuery] = createSignal(null) const [mentionResults, setMentionResults] = createSignal([]) const [mentionIndex, setMentionIndex] = createSignal(0) // 搜索防抖 let fileSearchTimer: ReturnType | undefined let fileSearchCounter = 0 // ... } ``` 资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24-38]() ### Hook 职责表 | Hook 名称 | 文件位置 | 职责 | 状态类型 | |-----------|----------|------|----------| | `useFileMention` | `hooks/useFileMention.ts` | 文件路径提及与搜索 | `Set`, `MentionResult[]` | | `useTheme` | 主题相关模块 | 主题配置与颜色 | `Theme` 对象 | ## 文件图标系统 ### 图标映射机制文件图标系统通过文件名和扩展名映射到对应的图标： ```typescript const ICON_MAPS: IconMaps = { fileNames: { // 文档文件 "readme.md": "Readme", "changelog.md": "Changelog", "package.json": "Nodejs", // Docker 文件 dockerfile: "Docker", "docker-compose.yml": "Docker", // 配置文件 "jest.config.js": "Jest", }, fileExtensions: { ".ts": "Typescript", ".tsx": "Typescript", ".json": "JSON", }, folderNames: { /* ... */ }, defaults: { file: "File", folder: "Folder", folderOpen: "FolderOpen", } } ``` 资料来源：[packages/ui/src/components/file-icon.tsx:22-48]() ### 支持的文件类型 | 类别 | 文件名/扩展名 | 图标名称 | |------|---------------|----------| | 文档 | `readme.md`, `changelog.md`, `contributing.md` | Readme, Changelog | | Node.js | `package.json`, `package-lock.json`, `yarn.lock` | Nodejs, Yarn | | Docker | `dockerfile`, `docker-compose.yml` | Docker | | 包管理 | `pnpm-lock.yaml`, `bun.lock` | Pnpm, Bun | | 测试 | `jest.config.js`, `jest.config.ts` | Jest | ## TUI 组件架构命令行工具采用 React-like 的 TUI 组件体系： ```mermaid graph TD subgraph "TUI 路由层" SESSION[index.tsx
会话路由] FOOTER[footer.tsx
状态栏] PERMISSION[permission.tsx
权限管理] end subgraph "TUI 组件层" PROMPT[prompt/index.tsx
输入组件] AUTOCOMPLETE[autocomplete.tsx
自动完成] DIALOG[dialog-export-options.tsx
对话框] end subgraph "TUI 基础层" THEMES[主题系统] LAYOUT[布局组件] end SESSION --> FOOTER SESSION --> PROMPT PROMPT --> AUTOCOMPLETE FOOTER --> DIALOG style SESSION fill:#e3f2fd style PROMPT fill:#f3e5f5 ``` ### 会话组件结构 `session/index.tsx` 定义了消息渲染的核心逻辑： ```typescript const PART_MAPPING = { text: TextPart, tool: ToolPart, reasoning: ReasoningPart, } function ReasoningPart(props: { last: boolean; part: ReasoningPart; message: AssistantMessage }) { // 过滤 OpenRouter 的加密推理数据 const content = createMemo(() => { return props.part.text.replace("[REDACTED]", "").trim() }) // ... } ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-16]() ### 工具注册机制工具通过 `ToolRegistry` 进行注册和渲染： ```typescript ToolRegistry.register({ name: "todowrite", render(props) { const view = createMemo(() => isTodoView(props.metadata?.view) ? props.metadata.view : undefined ) const todos = createMemo(() => { const meta = props.metadata // 处理待办事项元数据 }) // ... }, }) ``` 资料来源：[packages/kilo-ui/src/components/message-part.tsx:1-30]() ## OAuth 与认证 ### 回调处理流程 ```mermaid sequenceDiagram participant U as 用户 participant P as 提供商 participant K as KiloCode participant C as 客户端应用 U->>P: 授权请求 P->>K: OAuth 回调 K->>K: 处理授权码 K-->>U: 显示成功页面 U->>C: 自动关闭窗口 ``` OAuth 回调页面支持多语言显示： ```typescript const HTML_SUCCESS = ` Kilo - Authorization Successful

You can close this window and return to Kilo.

Authorization Successful

` ``` 资料来源：[packages/opencode/src/mcp/oauth-callback.ts:1-25]() ## 状态栏组件 ### 底部状态栏信息状态栏组件展示连接状态、权限、LSP、MCP 等信息： ```typescript 0}> △ {permissions().length} Permission{permissions().length > 1 ? "s" : ""} 0 ? theme.success : theme.textMuted }}>• {lsp().length} LSP ⊙ ⊙ {mcp()} MCP ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-25]() ### 状态指示器对照表 | 指示器 | 颜色 | 含义 | |--------|------|------| | `•` (实心) | `theme.success` | LSP 已连接 | | `•` (空心) | `theme.textMuted` | LSP 未连接 | | `⊙` | `theme.success` | MCP 正常 | | `⊙` | `theme.error` | MCP 错误 | | `△` | `theme.warning` | 需要权限 | ## 构建与打包 ### Turborepo 配置项目使用 `turbo.json` 进行构建编排： ```json { "$schema": "https://turbo.build/schema.json", "tasks": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] }, "dev": { "cache": false, "persistent": true } } } ``` ### 包依赖关系 ```mermaid graph LR subgraph "基础层" UI[kilo-ui] UIShared[ui] end subgraph "平台层" VSCODE[kilo-vscode] OPENCODE[opencode] end UI --> VSCODE UI --> OPENCODE UIShared --> UI style UI fill:#e1f5fe style VSCODE fill:#fff3e0 style OPENCODE fill:#f3e5f5 ``` ## 开发指南 ### 创建新组件 1. **确定所属模块**：根据功能选择合适的 `components/` 子目录 2. **使用 SolidJS 语法**：`webview-ui` 使用 SolidJS 而非 React 3. **国际化支持**：使用 `language.t()` 获取翻译文本 4. **类型定义**：为组件 Props 定义完整类型 ```typescript interface MigrationWizardProps { onComplete?: () => void currentStep?: Accessor } export function MigrationWizard(props: MigrationWizardProps) { const language = useI18n() return (

{language.t("migration.whatsNew.title")}

) } ``` 资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1-14]() ### 创建新 Hook 1. **使用 `createSignal`**：SolidJS 的响应式状态 2. **处理异步操作**：使用防抖处理搜索类操作 3. **与 VS Code 通信**：通过 `vscode.onMessage` 监听消息 ```typescript export function useFileMention(vscode, sessionID, git) { const [mentionedPaths, setMentionedPaths] = createSignal>(new Set()) let fileSearchTimer: ReturnType | undefined // 防抖搜索 createEffect(() => { if (fileSearchTimer) clearTimeout(fileSearchTimer) fileSearchTimer = setTimeout(() => { vscode.postMessage({ type: "fileSearch", ... }) }, 300) }) } ``` ## 总结 KiloCode 项目采用精心设计的 Monorepo 架构： - **7 个核心包**覆盖 IDE 插件、命令行工具、后端服务等全端场景 - **组件库分层**实现代码复用与维护性平衡 - **SolidJS** 作为前端框架提供高效的响应式编程模型 - **Turborepo** 统一管理构建流程和依赖关系这种组织方式使项目能够同时支持 VS Code、JetBrains IDE 和命令行等多个客户端，同时保持代码的模块化和可维护性。 --- ## 系统架构设计 ### 相关页面相关主题：[项目结构与包组织](#project-structure), [Agent 核心系统](#agent-system)

相关源码文件

以下源码文件用于生成本页说明： - [packages/opencode/src/server/server.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/server.ts) - [packages/opencode/src/server/adapter.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/adapter.ts) - [packages/opencode/src/server/routes/instance/httpapi/server.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/routes/instance/httpapi/server.ts) - [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts) - [packages/opencode/src/provider/provider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/provider/provider.ts) - [packages/opencode/src/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/registry.ts) - [packages/kilo-vscode/src/services/cli-backend/connection-service.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/cli-backend/connection-service.ts)

# 系统架构设计 ## 概述 Kilocode 是一个开源的 AI 编程助手平台，采用模块化架构设计，核心功能包括代码生成、自然语言处理、终端命令执行、浏览器自动化和内联自动补全。系统架构基于分层设计原则，将用户界面、业务逻辑、数据处理和外部服务解耦，通过标准化接口实现各层之间的通信。 Kilocode 支持多种客户端形式：命令行界面（CLI）、终端用户界面（TUI）和 Visual Studio Code 扩展。不同客户端共享相同的核心服务层，通过协议适配器实现差异化交互体验。资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md) --- ## 整体架构分层 Kilocode 采用经典的三层/四层架构设计，从上到下依次为：展示层、服务层、核心业务层和数据层。展示层负责用户交互，服务层处理协议转换和请求路由，核心业务层实现 AI 推理和工具调用，数据层管理会话状态和配置存储。 ``` ┌─────────────────────────────────────────────────────────┐ │ 展示层 (UI Layer) │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ CLI │ │ TUI │ │ VS Code Extension │ │ │ │ │ │ │ │ (Webview + Backend) │ │ │ └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │ └───────┼─────────────┼───────────────────┼───────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────┐ │ 服务层 (Service Layer) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ 协议适配器 (Protocol Adapter) │ │ │ │ CLI适配器 │ TUI适配器 │ VSCode消息通道适配器 │ │ │ └──────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ HTTP API 网关 │ │ │ │ /instance/* 路由 · 会话管理端点 │ │ │ └──────────────────────────────────────────────────┘ │ └──────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 核心业务层 (Core Business Layer) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ 会话管理 │ │ 工具注册 │ │ 提供者系统 │ │ │ │ (Session) │ │ (Registry) │ │ (Provider) │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ 提示工程 │ │ 工具执行 │ │ 状态管理 │ │ │ │ (Prompt) │ │ (Executor) │ │ (State Mgmt) │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ └──────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 数据层 (Data Layer) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ 会话存储 │ │ 配置存储 │ │ 模型接口 │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` --- ## 核心组件架构 ### 服务层组件 #### HTTP API 服务器 HTTP API 服务器是 Kilocode 的核心通信枢纽，提供 RESTful 接口供外部客户端调用。服务器实现位于 `packages/opencode/src/server/routes/instance/httpapi/server.ts`，负责处理会话管理、工具调用和状态查询等核心功能。服务器路由设计遵循统一资源定位原则，所有实例级接口统一挂载在 `/instance` 路径下： | 路由前缀 | 功能说明 | 请求方法 | |---------|---------|----------| | `/instance/sessions` | 会话列表与创建 | GET/POST | | `/instance/sessions/:id` | 单一会话操作 | GET/DELETE | | `/instance/execute` | 远程命令执行 | POST | | `/instance/status` | 服务状态查询 | GET | #### 协议适配器协议适配器（Adapter）位于 `packages/opencode/src/server/adapter.ts`，负责将不同客户端的通信协议转换为统一的内部消息格式。这种设计使得 CLI、TUI 和 VSCode 扩展可以使用各自的原生协议进行通信，同时核心业务逻辑保持一致。适配器实现了消息解析、路由分发和响应格式化三个核心功能。当客户端发送请求时，适配器首先解析消息内容，根据消息类型和目标端点将请求路由到对应的处理函数，最后将处理结果格式化为客户端可识别的响应格式。 #### VSCode 连接服务 VSCode 扩展与后端 CLI 之间的通信通过 `packages/kilo-vscode/src/services/cli-backend/connection-service.ts` 实现的连接服务完成。该服务利用 VSCode 原生的 `postMessage` API 建立双向通信通道，支持文件搜索、会话管理和模型查询等操作。 ``` ┌─────────────────┐ postMessage ┌─────────────────┐ │ VSCode Webview │ ──────────────────▶│ CLI Backend │ │ (Frontend) │ │ (Server) │ │ │ ◀─────────────────│ │ │ │ handleMessage │ │ └─────────────────┘ └─────────────────┘ ``` 连接服务定义了标准化的消息格式，消息对象包含 `type` 字段标识消息类型，可选的 `requestId` 用于请求-响应匹配： ```typescript interface VSCodeMessage { type: "fileSearchResult" | "sessionList" | "sessionCreate" | "sessionDelete" | "modelList" | "error"; requestId?: string; items?: SearchItem[]; paths?: string[]; sessions?: SessionInfo[]; models?: ModelInfo[]; error?: string; } ``` --- ### 核心业务层组件 #### 会话管理会话（Session）是 Kilocode 处理用户对话的核心抽象，定义于 `packages/opencode/src/session/session.ts`。每个会话拥有唯一的会话标识符（Session ID），用于追踪对话上下文、管理文件引用和代理状态。会话模块负责维护对话历史、解析和存储文件提及（File Mentions）、处理工具调用结果以及管理对话状态转换。TUI 界面中的会话组件根据消息模式（mode）展示不同类型的对话内容，包括文本回复、工具调用和推理过程。 ```mermaid graph TD A[用户输入] --> B[会话初始化] B --> C{消息类型} C -->|文本| D[AI推理引擎] C -->|文件引用| E[文件解析服务] C -->|工具调用| F[工具注册表] D --> G[响应生成] E --> G F --> H[工具执行] H --> G G --> I[会话状态更新] I --> J[UI渲染] ``` #### 提供者系统提供者（Provider）系统位于 `packages/opencode/src/provider/provider.ts`，是 Kilocode 与外部 AI 模型交互的抽象层。提供者系统标准化了与不同 AI 厂商（如 OpenAI、Anthropic、Google 等）的接口，屏蔽了底层 API 差异。每个提供者实现以下核心接口： | 接口方法 | 功能说明 | 返回类型 | |---------|---------|----------| | `chat()` | 发送对话请求 | `AsyncIterator` | | `models()` | 列出可用模型 | `Model[]` | | `authenticate()` | 身份验证 | `Promise` | | `health()` | 健康检查 | `Promise` | 提供者系统支持模型选择、参数配置和密钥管理，允许用户在 `kilo.json` 配置文件中指定使用的模型和提供者的凭据信息。 #### 工具注册表工具注册表（Tool Registry）定义于 `packages/opencode/src/tool/registry.ts`，是 Kilocode 扩展其能力的基础架构。工具注册表采用插件式设计，允许动态注册新的工具功能，系统启动时自动扫描并加载所有已注册的工具。注册表核心数据结构包括： | 字段 | 类型 | 说明 | |-----|------|------| | `name` | `string` | 工具唯一标识名 | | `description` | `string` | 工具功能描述 | | `parameters` | `Schema` | 参数定义 | | `handler` | `Function` | 执行函数 | 已注册的工具通过标准化的调用接口暴露给 AI 模型，模型可以根据对话上下文选择合适的工具执行任务。TUI 界面中的工具部分渲染器（ToolPart）负责将工具调用结果以格式化方式展示给用户。 --- ## 消息处理流程 ### TUI 消息渲染流程 TUI 界面中的消息渲染采用组件化设计，不同类型的消息部分（Part）由对应的渲染器处理： ```mermaid sequenceDiagram participant User as 用户 participant TUI as TUI界面 participant Session as 会话模块 participant AI as AI模型 participant Registry as 工具注册表 User->>TUI: 发送消息 TUI->>Session: 创建用户消息 Session->>AI: 发送对话请求 AI->>AI: 生成回复 AI-->>Session: 返回响应流 Session-->>TUI: 分发消息片段 alt 文本消息 TUI->>TUI: TextPart渲染器 else 工具调用 TUI->>Registry: 查询工具信息 Registry-->>TUI: 工具元数据 TUI->>TUI: ToolPart渲染器 else 推理过程 TUI->>TUI: ReasoningPart渲染器 Note over TUI: 过滤[REDACTED]标记 end TUI-->>User: 展示消息内容 ``` 推理消息（ReasoningPart）会经过特殊处理，过滤掉来自 OpenRouter 等平台的加密推理数据标记 `[REDACTED]`，确保用户界面显示干净的推理过程。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/index.tsx) ### 文件提及处理流程文件提及（File Mention）是 Kilocode 的核心交互特性，允许用户在对话中通过 `@` 符号引用文件。处理流程如下： ```mermaid graph LR A[用户输入] --> B{检测@符号} B -->|是| C[触发提及查询] C --> D[搜索文件] D --> E[显示建议列表] E --> F[用户选择] F --> G[解析文件信息] G --> H[创建FilePart] H --> I[更新extmark] I --> J[渲染文件引用] ``` 文件提及功能由 `useFileMention` Hook 实现，负责维护提及路径的搜索状态、查询结果和用户选择。提及选择后，系统通过 extmark 机制在编辑器中标记文件引用区域。资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) --- ## 数据流与状态管理 ### 会话数据流会话模块管理整个对话的生命周期，数据流向遵循以下模式： 1. **输入阶段**：用户输入通过客户端界面捕获，转换为标准消息格式 2. **处理阶段**：消息经过解析、验证和上下文增强后发送给 AI 模型 3. **推理阶段**：AI 模型生成回复，系统根据回复类型分发到不同处理器 4. **输出阶段**：处理后的内容更新会话状态，UI 层订阅状态变化进行渲染 ### 状态同步机制 VSCode 扩展中，前端 Webview 与后端 CLI 通过消息通道保持状态同步。连接服务维护一个消息计数器 `fileSearchCounter` 用于追踪文件搜索请求，确保响应与请求正确匹配： ```typescript let fileSearchCounter = 0 // 发送请求时递增 const requestId = `file-search-${fileSearchCounter++}` // 接收响应时验证 if (message.requestId === `file-search-${fileSearchCounter}`) { // 处理结果 } ``` --- ## 配置系统 Kilocode 的配置系统支持多层级合并，优先级从低到高依次为：远程默认配置、全局配置（`~/.config/kilo/kilo.json`）、环境变量、项目配置（`./kilo.json`）、本地配置（`.kilo/kilo.json`）和管理配置。资料来源：[packages/opencode/src/kilocode/skills/kilo-config.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/skills/kilo-config.md) 配置查找路径支持以下目录： | 目录路径 | 说明 | |---------|------| | `~/.config/kilo/` | 全局配置根目录 | | `./.kilo/` | 项目本地配置 | | `./.kilocode/` | 项目本地配置（兼容旧版本） | | `./.opencode/` | 项目本地配置（兼容旧版本） | 命令文件存储在配置的 `command/` 子目录中，支持 `commands/` 别名。命令文件采用 Markdown 格式，YAML frontmatter 定义元数据，正文定义命令模板。资料来源：[packages/opencode/src/kilocode/skills/kilo-config.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/skills/kilo-config.md) --- ## 工具与代理集成 ### 工具注册机制工具注册表支持插件化扩展，每个工具需要提供名称、描述、参数模式和执行函数。系统启动时，注册表扫描预定义路径下的工具模块，自动完成工具的注册和初始化。 ### 代理管理代理（Agent）是执行复杂任务的自动化实体，Kilocode 支持通过 Agent Manager 进行代理的生命周期管理。用户可以在会话中切换不同的代理模式（Architect、Coder、Debugger 等），每个模式针对特定任务类型进行了优化。资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx) --- ## 安全考虑 ### 敏感信息处理导出功能中实现了敏感信息过滤机制，系统自动识别并脱敏文件路径、符号名称、URI 和客户端名称等敏感数据： ```typescript function source(part: MessageV2.FilePart) { if (!part.source) return part.source if (part.source.type === "symbol") { return { ...part.source, path: redact("file-path", part.id, part.source.path), name: redact("file-symbol", part.id, part.source.name), } } // ... } ``` ### 会话隔离每个会话拥有独立的上下文空间，会话间的数据和状态完全隔离，确保多用户或多任务场景下的数据安全。 --- ## 扩展点与插件化 Kilocode 架构设计预留了多个扩展点，支持第三方功能集成： | 扩展点 | 说明 | 接入方式 | |-------|------|----------| | 工具注册 | 自定义工具功能 | 实现 ToolRegistry 接口 | | 提供者 | 自定义 AI 模型 | 实现 Provider 接口 | | 命令 | 自定义 CLI 命令 | 添加 `.kilo/command/*.md` 文件 | | MCP 服务器 | 扩展系统能力 | 通过 `kilo mcp` 命令管理 | --- ## 技术栈总结 | 层级 | 技术选型 | |-----|---------| | 展示层 | React + TypeScript（VSCode扩展）、SolidJS（kilo-ui） | | 服务层 | Node.js HTTP 服务器、WebSocket（可选） | | 核心业务 | TypeScript 原生实现 | | 数据层 | 文件系统存储、会话序列化 | | 通信协议 | JSON over postMessage、REST API | --- ## 总结 Kilocode 的系统架构遵循模块化、可扩展和松耦合的设计原则。通过分层架构和协议适配器，系统支持多种客户端形式，同时保持核心业务逻辑的统一。会话管理、工具注册表和提供者系统构成了核心业务层的主要组件，HTTP API 网关和消息通道服务则负责对外通信。这种架构设计使得 Kilocode 能够灵活适应不同的使用场景，同时为第三方扩展预留了充足的接口。 --- ## Agent 核心系统 ### 相关页面相关主题：[系统架构设计](#system-architecture), [自动补全系统 (FIM)](#autocomplete-system)

相关源码文件

以下源码文件用于生成本页说明： - [packages/opencode/src/agent/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/agent.ts) - [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts) - [packages/opencode/src/session/prompt.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/prompt.ts) - [packages/opencode/src/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/processor.ts) - [packages/opencode/src/session/llm.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/llm.ts) - [packages/opencode/src/session/compaction.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/compaction.ts) - [packages/opencode/src/agent/prompt/orchestrator.txt](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/prompt/orchestrator.txt) - [packages/opencode/src/kilocode/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/session/processor.ts)

# Agent 核心系统 ## 概述 KiloCode 的 Agent 核心系统是整个智能编程平台的中枢，负责处理用户请求、调度工具执行、管理会话上下文以及协调大语言模型（LLM）交互。该系统采用模块化架构，将会话管理、消息处理、上下文压缩和工具注册等功能分离，实现了高内聚低耦合的设计目标。 Agent 系统的核心职责包括：接收用户自然语言指令并转化为可执行的任务、通过工具注册表调用各类工具（如文件操作、终端命令、Git 操作等）、维护会话历史和上下文状态、执行上下文压缩以控制 token 消耗、以及支持多种运行模式（Architect、Coder、Debugger 等）。 ## 系统架构 ### 整体架构图 ```mermaid graph TD User[用户输入] --> Session[会话管理模块] Session --> Processor[消息处理器] Processor --> LLM[LLM 交互层] LLM --> Response[响应生成] Response --> ToolRegistry[工具注册表] ToolRegistry --> Tools[工具执行] Tools --> Processor Session --> Compaction[上下文压缩] Compaction --> Context[上下文管理] Context --> LLM Session --> Prompt[提示词管理] Prompt --> LLM ``` ### 核心模块职责 | 模块名称 | 文件路径 | 主要职责 | |---------|---------|---------| | Agent 主模块 | `packages/opencode/src/agent/agent.ts` | 核心代理逻辑、模式调度、生命周期管理 | | 会话管理 | `packages/opencode/src/session/session.ts` | 会话状态维护、父子会话关系、多会话支持 | | 消息处理 | `packages/opencode/src/session/processor.ts` | 消息解析、工具调用分发、响应格式化 | | LLM 交互 | `packages/opencode/src/session/llm.ts` | 模型调用、流式响应、推理处理 | | 上下文压缩 | `packages/opencode/src/session/compaction.ts` | 历史消息压缩、token 优化 | | 提示词管理 | `packages/opencode/src/agent/prompt/orchestrator.txt` | 角色定义、指令模板管理 | ## Agent 主模块 ### 核心类结构 Agent 主模块位于 `packages/opencode/src/agent/agent.ts`，是整个系统的核心入口点。该模块定义了 Agent 类的基本结构，包括初始化配置、运行循环、错误处理等核心功能。 Agent 类采用事件驱动的设计模式，通过监听器模式处理各类系统事件。初始化时，Agent 会加载配置文件、建立 LLM 连接、注册工具集，并准备会话环境。 ### 模式系统 KiloCode 支持多种运行模式，每种模式针对不同的开发场景进行了优化： - **Architect（架构师模式）**：专注于代码设计和架构规划 - **Coder（编码模式）**：执行具体的代码实现和修改任务 - **Debugger（调试模式）**：定位和修复代码问题模式定义存储在 `packages/opencode/src/agent/prompt/orchestrator.txt` 中，通过角色提示词引导 LLM 产生符合当前模式预期的行为。 ### 生命周期管理 Agent 的生命周期包含以下阶段： ```mermaid stateDiagram-v2 [*] --> Init: 初始化 Init --> Ready: 配置加载完成 Ready --> Running: 接收用户请求 Running --> Ready: 请求处理完成 Running --> Error: 发生错误 Error --> Ready: 错误恢复 Ready --> [*]: 会话结束 ``` 1. **初始化阶段**：加载配置、初始化 LLM 连接、注册工具 2. **就绪阶段**：等待用户输入 3. **运行阶段**：处理请求、执行工具、生成响应 4. **错误处理**：捕获异常、尝试恢复或终止 ## 会话管理系统 ### 会话数据结构会话管理模块位于 `packages/opencode/src/session/session.ts`，负责维护会话的完整生命周期。每个会话包含以下关键属性： - **sessionID**：会话唯一标识符 - **parentID**：父会话 ID（用于子代理场景） - **mode**：当前运行模式 - **messages**：消息历史列表 - **metadata**：会话元数据（创建时间、更新时间等） ### 父子会话机制系统支持创建子代理会话，子会话继承父会话的上下文，同时可以独立执行任务。这一机制允许复杂的任务分解和委托场景： ```mermaid graph LR Parent[父会话] -->|创建子代理| Child1[子会话 1] Parent -->|创建子代理| Child2[子会话 2] Child1 -->|汇报结果| Parent Child2 -->|汇报结果| Parent ``` 子会话标识通过 `session()?.parentID` 属性判断，在 UI 层（`packages/opencode/src/cli/cmd/tui/routes/session/index.tsx`）会根据是否为子会话显示不同的界面元素，如子代理底部栏（SubagentFooter）。 ### 会话状态同步会话状态通过 `packages/opencode/src/session/processor.ts` 进行处理，支持实时状态更新和持久化。状态变化时会触发相应的事件通知各订阅模块。 ## 消息处理流程 ### 处理器架构消息处理器是 Agent 系统的核心组件，负责将用户输入转换为系统可执行的操作序列。其处理流程如下： ```mermaid sequenceDiagram participant User as 用户 participant Proc as 处理器 participant LLM as LLM 层 participant Tools as 工具注册表 participant Session as 会话管理 User->>Proc: 发送消息 Proc->>Proc: 消息解析与验证 Proc->>LLM: 调用 LLM LLM-->>Proc: 返回响应 Proc->>Tools: 检测工具调用 Tools-->>Proc: 工具结果 Proc->>LLM: 继续处理 Proc->>Session: 更新会话历史 Proc-->>User: 返回最终响应 ``` ### 消息类型处理系统支持多种消息类型，每种类型有对应的处理策略： | 消息类型 | 来源 | 处理方式 | |---------|------|---------| | user | 用户输入 | 解析意图、转译为任务 | | assistant | LLM 响应 | 解析工具调用、格式化输出 | | tool | 工具执行结果 | 整合结果、继续 LLM 循环 | | system | 系统消息 | 更新状态、触发事件 | | reasoning | 推理过程 | 可选显示、用于调试 | ### 推理处理对于支持推理的模型，系统会特殊处理 `reasoning` 类型消息。在 `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` 中定义了 `ReasoningPart` 组件，用于渲染推理过程。推理内容中若包含 `[REDACTED]` 标记（如来自 OpenRouter 的加密推理数据），系统会自动过滤： ```typescript const content = createMemo(() => { return props.part.text.replace("[REDACTED]", "").trim() }) ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:112-117]() ## 工具系统 ### 工具注册机制工具注册表位于 `packages/opencode/src/kilocode/tool/registry.ts`，采用注册表模式管理所有可用工具。工具定义包含以下属性： - **id**：工具唯一标识 - **name**：工具显示名称 - **description**：工具功能描述 - **parameters**：参数模式定义 - **handler**：执行函数 ### 核心工具集系统内置的核心工具包括： | 工具名称 | 功能描述 | 注册位置 | |---------|---------|---------| | Read | 读取文件内容 | 默认注册 | | Write | 写入或创建文件 | 默认注册 | | Edit | 编辑文件指定区域 | 默认注册 | | Bash | 执行终端命令 | 默认注册 | | Glob | 文件模式匹配 | 默认注册 | | Grep | 代码内容搜索 | 默认注册 | | manager | Agent 管理工具 | 条件注册 | ### 工具描述增强对于 `glob` 和 `grep` 工具，系统会添加额外的使用提示，帮助 LLM 更准确地使用这些工具： ```typescript export function describe(tools: Tool.Def[], extra: { semantic?: Tool.Def }): Tool.Def[] { if (!extra.semantic) return tools return tools.map((tool) => { if (tool.id !== "glob" && tool.id !== "grep") return tool return { ...tool, description: `${tool.description}\n${hint}` } }) } ``` 资料来源：[packages/opencode/src/kilocode/tool/registry.ts:45-54]() ## LLM 交互层 ### 模型调用封装 LLM 交互层位于 `packages/opencode/src/session/llm.ts`，封装了与各类大语言模型的通信细节。系统支持多种模型提供商，包括 OpenAI、Anthropic、OpenRouter 等。 ### 流式响应处理系统采用流式响应模式，通过 Server-Sent Events（SSE）或 WebSocket 实时推送 LLM 输出。流式处理的优势包括： - **即时反馈**：用户可以立即看到生成的内容 - **降低延迟**：无需等待完整响应即可开始处理 - **资源优化**：减少内存占用 ### 消息中止机制系统支持通过 `MessageAbortedError` 中止正在进行的 LLM 调用。在 UI 层会显示 "interrupted" 状态标识： ```typescript · interrupted ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:38-40]() ## 上下文管理 ### 上下文压缩策略由于 LLM 有 token 数量限制，系统实现了上下文压缩机制，位于 `packages/opencode/src/session/compaction.ts`。压缩策略包括： 1. **摘要压缩**：将历史消息压缩为关键信息摘要 2. **选择性保留**：保留重要上下文，丢弃冗余内容 3. **滑动窗口**：使用固定大小的上下文窗口 ### AGENTS.md 集成系统支持项目级别的 `AGENTS.md` 文件，该文件包含针对 AI 代理的特定指令。文件搜索逻辑会按以下顺序查找： 1. 项目根目录的 `AGENTS.md` 2. 子目录中的 `AGENTS.md` 3. `README.md` 作为备选 ```mermaid graph TD Start[加载上下文] --> CheckRoot{检查根目录 AGENTS.md} CheckRoot -->|存在| UseRoot[使用根目录 AGENTS.md] CheckRoot -->|不存在| CheckSub{检查子目录 AGENTS.md} CheckSub -->|存在| UseSub[使用子目录 AGENTS.md] CheckSub -->|不存在| Fallback[使用 README.md] UseRoot --> Done[完成上下文加载] UseSub --> Done Fallback --> Done ``` 资料来源：[packages/opencode/src/session/prompt/kimi.txt:1-20]() ## MCP 服务器集成 ### MCP 状态显示系统集成了 MCP（Model Context Protocol）服务器支持，在 TUI 界面底部栏显示 MCP 连接状态： ```typescript ⊙ ⊙ {mcp()} MCP ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:25-37]() ### MCP OAuth 回调 MCP 服务器认证采用 OAuth 2.0 流程，授权成功后会显示确认页面： ```html

You can close this window and return to Kilo.

``` 资料来源：[packages/opencode/src/mcp/oauth-callback.ts:28-29]() ## 索引与 LSP 集成 ### 索引状态显示系统支持代码索引功能，在界面底部栏显示当前索引状态： ```typescript {indexingText(indexing()).slice(0, 48)} ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:38-41]() ### LSP 连接状态底部栏同时显示 LSP（Language Server Protocol）连接数量： ```typescript 0 ? theme.success : theme.textMuted }}>• {lsp().length} LSP ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:20-23]() ## 权限管理 ### 权限请求机制当执行敏感操作时，系统会请求用户授权。权限状态在底部栏显示： ```typescript 0}> △ {permissions().length} Permission{permissions().length > 1 ? "s" : ""} ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:14-19]() ## 文件提及系统 ### 文件自动检测系统支持自动检测和处理用户输入中的文件引用。在 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts` 中实现了文件提及检测逻辑。文件提及支持多种类型： | 类型 | 图标 | 显示效果 | |-----|------|---------| | terminal | console | 显示命令路径 | | git-changes | branch | 显示 Git 变更 | | file | 文件图标 | 显示文件名和目录 | | folder | 文件夹图标 | 显示目录路径 | ### 文件搜索防抖为避免频繁搜索，系统实现了防抖机制： ```typescript let fileSearchTimer: ReturnType | undefined let fileSearchCounter = 0 ``` 搜索结果通过 `requestId` 关联，确保响应的正确性和顺序性。 ## 扩展性设计 ### 插件插槽系统系统通过 `TuiPluginRuntime.Slot` 提供扩展插槽，支持第三方插件注入功能： ```typescript ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:198-207]() ### 工具注册表扩展工具注册表支持动态注册新工具，第三方可以通过扩展点添加自定义工具。注册时需要提供完整的工具定义，包括参数模式和执行处理函数。 ## 配置管理 ### 同步配置结构系统使用 `sync` 对象管理配置状态，包括： - `sync.path.directory`：当前工作目录 - `sync.data.config`：运行时配置 - `sync.data.state`：会话状态 ### 状态持久化会话状态支持持久化存储，包括： - 消息历史 - 用户偏好设置 - 工具配置 - 上下文摘要 ## 错误处理 ### 错误分类系统将错误分为以下几类： | 错误类型 | 处理策略 | 用户可见性 | |---------|---------|-----------| | LLM 调用错误 | 重试或降级 | 是 | | 工具执行错误 | 返回错误信息 | 是 | | 认证错误 | 引导重新认证 | 是 | | 系统错误 | 记录日志 | 可选 | ### 网络可见性系统通过 `networkVisible()` 和 `network()` 状态管理网络相关错误的显示： ```typescript ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:193-195]() ## 性能优化 ### 虚拟文本渲染对于文件提及等高频更新元素，系统采用虚拟文本渲染优化性能： ```typescript if (part.type === "file" && part.source?.text) { part.source.text.start = extmarkStart part.source.text.end = extmarkEnd part.source.text.value = virtualText } ``` 资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:45-51]() ### 频率优化文件搜索结果通过频率算法（Frecency）排序，优先显示常用文件： ```typescript if (part.type === "file" && part.source && part.source.type === "file") { frecency.updateFrecency(part.source.path) } ``` 资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:65-67]() ## 总结 Agent 核心系统是 KiloCode 平台的核心支柱，通过模块化设计和清晰的职责划分，实现了高效、可靠的智能编程辅助能力。系统各组件之间通过事件和接口进行通信，既保证了功能的独立性，又支持灵活的可扩展性。理解这一架构对于深入使用和二次开发 KiloCode 具有重要意义。 --- ## 自动补全系统 (FIM) ### 相关页面相关主题：[Agent 核心系统](#agent-system), [代码索引与语义搜索](#indexing-system)

相关源码文件

以下源码文件用于生成本页说明： - [packages/kilo-vscode/src/services/autocomplete/settings.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/settings.ts) - [packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md) - [packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx) - [packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) - [packages/opencode/src/kilocode/claw/view.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/claw/view.tsx)

# 自动补全系统 (FIM) ## 概述 KiloCode 的自动补全系统（Fill-In-The-Middle，简称 FIM）是一个为开发者提供智能代码补全功能的核心模块。该系统通过分析当前编辑上下文，结合语言模型生成高质量的代码建议，帮助开发者提高编码效率。自动补全系统支持多种文件类型，包括 Python、TypeScript/TSX、Shell 脚本等，并能根据不同语言特性动态调整补全策略。 ## 系统架构 ### 整体架构图 ```mermaid graph TD subgraph "用户界面层" VSCodeEditor[VS Code 编辑器] TUIPrompt[TUI 命令行提示符] ClawChat[Claw 聊天界面] end subgraph "补全服务层" AutocompleteProvider[AutocompleteInlineCompletionProvider] FillInTheMiddle[FIM 处理器] ContextRetrieval[上下文检索服务] end subgraph "模板与后处理" AutocompleteTemplate[补全模板] PostProcessing[后处理器] end subgraph "配置层" Settings[设置管理] Validators[设置验证器] end VSCodeEditor --> AutocompleteProvider TUIPrompt --> autocomplete ClawChat --> ClawSlashes AutocompleteProvider --> FillInTheMiddle FillInTheMiddle --> ContextRetrieval ContextRetrieval --> AutocompleteTemplate AutocompleteTemplate --> PostProcessing Settings --> Validators ``` ### 核心组件 | 组件名称 | 功能描述 | 源码位置 | |---------|---------|---------| | AutocompleteInlineCompletionProvider | 为 VS Code 提供内联补全项的核心提供者 | settings.ts | | FillInTheMiddle | 实现 Fill-In-The-Middle 算法的核心逻辑 | EXAMPLES.md | | ContextRetrievalService | 从代码库中检索相关上下文信息 | 架构设计 | | AutocompleteTemplate | 管理和渲染补全提示模板 | 架构设计 | | PostProcessing | 对模型输出进行后处理和格式化 | 架构设计 | ## 配置系统 ### 设置验证机制自动补全系统通过 `validAutocompleteSetting` 函数验证用户配置，确保只接受有效的设置值： ```typescript export function validAutocompleteSetting(key: string, value: unknown) { if (key === "model") { if (typeof value !== "string") return false return AUTOCOMPLETE_MODELS.some((m) => m.id === value) } if (key === "enableAutoTrigger") return typeof value === "boolean" if (key === "enableSmartInlineTaskKeybinding") return typeof value === "boolean" if (key === "enableChatAutocomplete") return typeof value === "boolean" return false } ``` 资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:18-31]() ### 支持的配置项 | 配置项 | 类型 | 说明 | |-------|------|------| | `model` | string | 选择的补全模型 ID | | `enableAutoTrigger` | boolean | 是否启用自动触发 | | `enableSmartInlineTaskKeybinding` | boolean | 智能内联任务快捷键 | | `enableChatAutocomplete` | boolean | 聊天自动补全 | ## Fill-In-The-Middle 算法 ### FIM 工作流程 ```mermaid graph LR A[光标位置] --> B[获取前缀上下文] B --> C[获取后缀上下文] C --> D[构建 FIM Prompt] D --> E[调用 LLM] E --> F[生成补全代码] F --> G[后处理] G --> H[返回补全建议] ``` ### 分语言配置系统针对不同编程语言提供了特定的配置优化： ```typescript if (fileExtension === "py") { // Python 特定设置 this.config.multilineCompletions = "always" this.config.stopTokens = ['"""', "'''"] } else if (fileExtension === "ts" || fileExtension === "tsx") { // TypeScript 特定设置 this.config.tabAutocompleteOptions = { ...this.config.tabAutocompleteOptions, maxPromptTokens: 2048, } } ``` 资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:1-60]() ### 上下文窗口管理 | 语言 | 最大 Prompt Token | 多行补全策略 | 停止标记 | |------|------------------|-------------|---------| | Python | 动态 | 始终启用 | `"""`, `'''` | | TypeScript | 2048 | 动态 | 基于语法 | | 默认 | 动态 | 动态 | 基于语法 | ## 上下文检索服务 ### 检索策略上下文检索服务负责从代码库中获取与当前编辑位置相关的代码片段。系统支持以下检索方式： 1. **Tree-Sitter 语法树查询**：基于代码语法结构进行精确检索 2. **文件路径匹配**：基于文件路径和命名模式 3. **语义相似度**：基于代码语义内容的相似度匹配 ### 代码片段查询系统使用 Tree-Sitter 进行代码结构分析，支持以下查询能力： - 导入语句识别 - 函数和类定义检索 - 类型注解提取 - 注释和文档字符串获取 ## 补全模板系统 ### 模板结构补全模板定义了如何将上下文信息组织成适合 LLM 处理的格式： ```typescript interface AutocompleteTemplate { prefix: string // 光标前内容 suffix: string // 光标后内容 aroundCursor: string // 光标周围代码块 metadata: { language: string filePath: string lineNumber: number } } ``` ### 模板变量 | 变量 | 说明 | 示例 | |-----|------|------| | `{{prefix}}` | 光标前代码 | `function hello() {` | | `{{suffix}}` | 光标后代码 | `}` | | `{{file_name}}` | 当前文件名 | `main.py` | | `{{language}}` | 编程语言 | `python` | ## 后处理系统 ### 后处理流程 ```mermaid graph TD A[LLM 输出] --> B[停止标记检测] B --> C[语法验证] C --> D{是否有效?} D -->|是| E[格式化输出] D -->|否| F[降级处理] E --> G[返回补全项] F --> G ``` ### 后处理功能 | 功能 | 描述 | |-----|------| | 停止标记处理 | 检测并截断在 `stopTokens` 处的输出 | | 缩进修正 | 根据文件类型修正缩进 | | 语法验证 | 确保输出符合目标语言语法 | | 多行处理 | 智能处理跨行代码补全 | ## CLI 命令行界面 ### TUI 自动补全组件在命令行界面中，自动补全系统通过 `autocomplete.tsx` 组件提供交互式补全功能： ```typescript const commands = createMemo((): AutocompleteOption[] => { const results: AutocompleteOption[] = [...command.slashes()] for (const res of Object.values(sync.data.mcp_resource)) { const text = `${res.name} (${res.uri})` options.push({ display: Locale.truncateMiddle(text, width), value: text, description: res.description, onSelect: () => { /* ... */ } }) } return options }) ``` 资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1-120]() ### MCP 资源自动补全系统支持 MCP（Model Context Protocol）资源的自动补全，开发者可以在提示符中快速引用外部资源。 ## VS Code 集成 ### 内联补全提供者 `AutocompleteInlineCompletionProvider` 实现了 VS Code 的 `InlineCompletionItemProvider` 接口，提供内联代码补全功能： ```typescript class VSCodeAutocompleteIntegration implements vscode.InlineCompletionItemProvider { private completionProvider: CompletionProvider; private currentCompletionId: string | null = null; constructor() { const config = new MinimalConfigProvider(); const ide = new VSCodeIdeAdapter(); this.completionProvider = new CompletionProvider( config, ide, this.getLlm.bind(this), this.onError.bind(this), this.getDefinitionsFromLsp.bind(this) ); } } ``` 资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:62-120]() ### 补全触发流程 ```mermaid sequenceDiagram participant Editor as VS Code 编辑器 participant Provider as 补全提供者 participant Config as 配置管理 participant LLM as 语言模型 Editor->>Provider: 用户触发补全 Provider->>Config: 获取当前配置 Config-->>Provider: 返回配置参数 Provider->>Provider: 构建 FIM Prompt Provider->>LLM: 发送补全请求 LLM-->>Provider: 返回候选代码 Provider->>Provider: 后处理 Provider-->>Editor: 返回 InlineCompletionItem ``` ## 文件提及与附件 ### 文件提及系统 `useFileMention` hook 提供了在提示中提及和附加文件的功能： ```typescript export function useFileMention( vscode: VSCodeContext, sessionID?: Accessor, git?: Accessor, ): FileMention { const [mentionedPaths, setMentionedPaths] = createSignal>(new Set()) const [mentionQuery, setMentionQuery] = createSignal(null) const [mentionResults, setMentionResults] = createSignal([]) return { parseFileAttachments, addPaths, setMentionIndex, closeMention, } } ``` 资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:1-50]() ### 文件类型支持 | 文件类型 | 图标 | 描述显示 | |---------|------|---------| | 普通文件 | FileIcon | 文件名 + 目录路径 | | 文件夹 | FileIcon | 文件夹名 + 父目录 | | 终端 | console 图标 | 终端名称 | | Git 变更 | branch 图标 | 变更摘要 | ## Claw 聊天集成 ### 斜杠命令自动补全在 Claw 聊天界面中，系统支持斜杠命令的自动补全： ```typescript const clawSlashes = createMemo(() => { const visible = kiloCommands().filter((c) => c.enabled !== false && !c.hidden && c.slash) const items = visible.map((c) => ({ display: "/" + c.slash!.name, description: c.description ?? c.title, aliases: c.slash!.aliases?.map((a) => "/" + a), onSelect: () => c.onSelect?.(dialog), })) const max = items.reduce((m, i) => Math.max(m, i.display.length), 0) if (!max) return items return items.map((i) => ({ ...i, display: i.display.padEnd(max + 2) })) }) ``` 资料来源：[packages/opencode/src/kilocode/claw/view.tsx:1-50]() ## 性能优化 ### 增量更新机制系统通过以下方式优化性能： 1. **延迟加载**：仅在需要时加载补全模型 2. **缓存策略**：缓存常用上下文的检索结果 3. **节流处理**：对频繁触发的事件进行节流 ### 设置变更监听 ```typescript context.subscriptions.push( vscode.workspace.onDidChangeConfiguration((e) => { if (e.affectsConfiguration("kilo-code.new.autocomplete")) { post(buildAutocompleteSettingsMessage()) } }) ) ``` 资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:1-18]() ## 总结 KiloCode 的自动补全系统采用模块化设计，通过 FIM 算法实现智能的上下文感知代码补全。系统支持多种编程语言，提供灵活的配置选项，并通过完善的后处理机制确保补全结果的质量。该系统与 VS Code、TUI 和 Claw 等多个界面无缝集成，为开发者提供一致的优质补全体验。 --- ## Agent Manager 工作流管理 ### 相关页面相关主题：[系统架构设计](#system-architecture), [MCP 协议与工具集成](#mcp-integration)

相关源码文件

以下源码文件用于生成本页说明： - [packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts) - [packages/kilo-vscode/src/agent-manager/WorktreeManager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/WorktreeManager.ts) - [packages/kilo-vscode/src/agent-manager/run/manager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/run/manager.ts) - [packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts) - [packages/kilo-vscode/src/agent-manager/GitOps.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/GitOps.ts) - [packages/kilo-vscode/src/agent-manager/terminal-manager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/terminal-manager.ts) - [packages/kilo-vscode/src/agent-manager/section-handler.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/section-handler.ts) - [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts)

# Agent Manager 工作流管理 ## 概述 Agent Manager 是 Kilo 平台的核心组件，提供多智能体协作与工作流自动化管理能力。该系统通过集成 Git 工作树管理、PR 状态轮询、GitOps 自动化操作和终端管理，实现了一个高效的多代理代码开发环境。Agent Manager 允许用户创建、配置和管理多个专门化的代理（Agent），每个代理可以拥有独立的权限、提示词和任务范围，从而实现复杂软件工程任务的分工协作。 Agent Manager 的设计理念是将代码开发过程分解为多个可配置的工作单元，通过集中式的调度和协调，确保多个代理能够有序地处理不同类型的任务。从架构层面来看，Agent Manager 不仅仅是一个任务调度器，更是一个完整的开发工作流编排平台，涵盖了从代码生成、审查、测试到部署的完整生命周期管理。该系统的核心价值体现在以下几个方面：首先，通过细粒度的权限控制机制，每个代理只能访问和操作其被授权的资源，防止未经授权的代码修改；其次，通过 Git 工作树（Worktree）隔离机制，不同代理可以在独立的分支上并行工作，避免相互干扰；再次，通过自动化的 PR 状态监控和 GitOps 操作，实现了持续集成和持续部署的无缝衔接；最后，通过统一的终端管理和会话管理，提供了一致且可追溯的开发体验。 ## 核心架构 ### 系统组件总览 Agent Manager 的架构采用模块化设计，各组件职责明确且相互协作。核心组件包括 AgentManagerProvider（提供器）、WorktreeManager（工作树管理器）、RunManager（运行管理器）、PRStatusPoller（PR 状态轮询器）、GitOps（Git 运维操作）、TerminalManager（终端管理器）和 SectionHandler（分区处理器）。这些组件共同构成了一个完整的多代理工作流管理生态系统，每个组件专注于特定的功能域，通过定义良好的接口进行通信和协作。 ```mermaid graph TD AMP[AgentManagerProvider] --> WM[WorktreeManager] AMP --> RM[RunManager] AMP --> GP[GitOps] AMP --> TM[TerminalManager] AMP --> SH[SectionHandler] WM --> PR[PRStatusPoller] RM --> GP GP --> TM SH --> AMP TM --> AMP subgraph 核心功能域 WM[工作树管理] RM[运行调度] GP[Git运维] TM[终端控制] end subgraph 监控与协调 PR[PR轮询] SH[分区处理] end ``` ### AgentManagerProvider 提供器 AgentManagerProvider 是整个 Agent Manager 系统的中央协调器，负责初始化、管理和协调所有子组件的生命周期。作为 VS Code 扩展的一部分，该提供器在扩展激活时初始化，并在整个扩展生命周期中保持运行状态。它维护着所有已注册代理的元数据、当前运行状态、以及与 VS Code 环境的集成接口。该提供器的核心职责包括：维护代理配置和状态、响应用户界面的操作请求、协调各子组件之间的通信、以及处理错误和异常情况。它通过 VS Code 的 Webview API 与前端 UI 进行双向通信，确保用户能够实时监控和控制代理的运行状态。此外，它还负责管理与 OpenCode 内核的连接，将用户的操作请求转发到后端执行。 AgentManagerProvider 的设计遵循了依赖注入模式，使得各子组件可以独立开发和测试，同时也便于扩展新的功能模块。每个子组件都通过接口定义与提供器交互，这种松耦合的设计提高了系统的可维护性和可测试性。 ### WorktreeManager 工作树管理器 WorktreeManager 是 Agent Manager 中负责 Git 工作树管理的核心组件。Git 工作树机制允许开发者在同一个 Git 仓库中创建多个工作目录，每个工作目录可以绑定到不同的分支。这种机制对于多代理协作开发至关重要，因为它允许不同的代理在完全隔离的环境中并行工作，而不会产生分支冲突或工作进度相互覆盖的问题。工作树管理器的主要功能包括：创建新的工作树并绑定到指定的分支、列出当前仓库中的所有工作树、清理已完成任务的工作树、以及在需要时自动合并或删除过期的分支。当一个代理需要处理特定功能或修复某个问题时，WorktreeManager 会为其分配一个独立的工作树，确保其工作不会影响其他代理的活动分支。该组件还负责监控工作树的状态变化，当检测到工作树中的文件发生变化时，会自动通知相关的代理进行相应的处理。这种事件驱动的设计使得系统能够实时响应开发过程中的各种状态变化，保持代理对项目状态的准确理解。 ### RunManager 运行管理器 RunManager 负责管理代理的启动、暂停、恢复和终止等生命周期操作。它维护着一个运行队列，调度各个代理任务的执行顺序，并根据系统资源和任务优先级进行合理的资源分配。当用户启动一个代理时，RunManager 会负责初始化代理的运行环境、加载必要的配置和上下文信息、并监控代理的运行状态。运行管理器的核心特性包括：支持任务的优先级调度、支持任务的依赖关系声明、支持任务执行超时控制、以及支持任务的自动重试机制。当某个任务因为网络故障或其他临时性问题失败时，RunManager 可以根据配置自动重试，减少人工干预的需要。此外，它还支持任务的暂停和恢复功能，这在需要临时中断开发工作或等待外部依赖时非常有用。 RunManager 与其他组件紧密集成，例如它会调用 WorktreeManager 为每个运行的代理分配隔离的工作环境，并通过 GitOps 组件确保所有操作都被正确地记录到 Git 历史中。这种集成设计确保了多代理系统的行为一致性和可追溯性。 ### PRStatusPoller PR 状态轮询器 PRStatusPoller 是专门用于监控 Pull Request 状态的组件，它定期轮询远程代码托管平台（如 GitHub、GitLab）的 API，获取 PR 的最新状态信息。这些信息包括 CI/CD 管道的执行结果、代码审查的反馈意见、以及 PR 的合并状态等。轮询器将这些信息汇总后，通过 AgentManagerProvider 分发给相关的代理，使其能够根据最新的 PR 状态做出相应的响应。 PR 状态轮询器支持多种轮询策略：定时轮询（固定间隔）、智能轮询（根据 PR 状态变化频率动态调整间隔）、以及事件驱动轮询（仅在特定事件发生时触发）。默认情况下，轮询器会优先使用智能轮询策略，以减少不必要的 API 调用，同时确保代理能够及时获取重要的状态变化通知。该组件还实现了背压（Backpressure）控制机制，防止在短时间内大量状态变化导致系统过载。当检测到异常大量的状态变化时，轮询器会自动降低轮询频率，并在状态稳定后逐步恢复正常。这种设计既保证了系统的响应性，又避免了因过度轮询而被远程 API 限流。 ### GitOps Git 运维操作 GitOps 组件封装了所有与 Git 仓库操作相关的功能，包括分支创建、提交管理、冲突解决、以及远程同步等。该组件的设计目标是提供一套统一、可靠且可审计的 Git 操作接口，使代理能够以声明式的方式执行各种 Git 操作，而无需关心底层的实现细节。 GitOps 的核心功能包括：自动化的提交消息生成（基于变更内容生成符合规范的提交信息）、智能的分支命名策略（根据任务类型和目标自动生成描述性的分支名）、变更暂存和提交的原子操作保证、以及冲突检测和自动解决（对于简单的冲突能够自动合并，复杂的冲突则通知相关代理进行人工处理）。该组件还维护着一个操作日志，记录所有 Git 操作的详细信息，包括执行时间、操作类型、操作者（代理标识）、变更的文件列表、以及操作的结果状态。这个日志不仅用于故障排查和审计，还可以通过可视化界面展示给用户，帮助其理解系统的行为和代理的工作进展。 ### TerminalManager 终端管理器 TerminalManager 负责管理 VS Code 终端实例，为代理提供命令执行的能力。每个运行的代理都可以拥有自己的终端实例，终端管理器确保这些终端的正确创建、配置和清理。当代理需要执行 shell 命令时（如运行测试、构建项目、或执行部署脚本），终端管理器会分配一个可用的终端实例，并负责捕获命令的输出结果。终端管理器还实现了输出缓冲和流控制机制，确保即使在命令产生大量输出的情况下，系统也能保持响应。它支持多种终端类型和 shell 环境，并能够根据操作系统自动选择合适的默认 shell。此外，它还提供了终端复用功能，当多个命令需要在同一个 shell 会话中执行时，可以共享同一个终端实例，保持命令之间的上下文关联。该组件还负责终端的安全管理，通过沙箱机制限制命令的权限范围，防止恶意或有风险的命令被执行。同时，它会记录每个终端会话的完整历史，供后续的调试和审计使用。 ### SectionHandler 分区处理器 SectionHandler 负责处理代理会话中的结构化数据分区。在多代理系统中，不同的代理可能需要访问会话的不同部分，而 SectionHandler 提供了对这些分区的访问控制和状态管理。该组件确保每个代理只能看到和修改其被授权的会话分区，防止未授权的信息泄露或操作干扰。分区处理器支持动态分区创建、分区间的消息传递、以及分区的合并和拆分。当一个复杂的任务被分解为多个子任务分配给不同的代理时，SectionHandler 会为每个子任务创建独立的分区，确保子代理之间的工作不会相互影响。任务完成后，相关的分区可以被合并，形成完整的结果报告。 ## 工作流机制 ### 多代理协作流程 Agent Manager 的多代理协作机制是其最具特色的功能之一。当用户启动一个复杂的开发任务时，系统会根据配置自动创建或选择一个合适的代理来处理该任务。代理可以进一步将任务分解为子任务，并分配给其他专门化的代理执行。这种层级式的任务分解和分配机制，使得系统能够处理从简单的代码修复到复杂的系统重构等各种规模的任务。 ```mermaid graph LR User[用户请求] --> AP[AgentManagerProvider] AP --> ModeSelect[模式选择] ModeSelect --> AgentCreate[代理创建] AgentCreate --> WorktreeAlloc[工作树分配] WorktreeAlloc --> TaskExec[任务执行] TaskExec --> GitOpsLog[GitOps记录] GitOpsLog --> PRCheck{PR状态检查} PRCheck -->|需要审查| Review[代码审查] PRCheck -->|完成| Merge[合并分支] Review --> AgentCreate Merge --> TerminalExec[终端命令执行] TerminalExec --> TaskExec subgraph 代理协作 ModeSelect AgentCreate WorktreeAlloc end subgraph 质量保障 GitOpsLog PRCheck Review end ``` 多代理协作的关键在于协调机制的设计。Agent Manager 提供了多种协调策略：中央协调模式（由一个主代理负责任务分配和结果汇总）、分布式协调模式（各代理通过消息传递自主协调）、以及混合模式（根据任务特点动态选择协调方式）。系统会根据任务的复杂度和代理的数量自动选择最合适的协调模式。 ### 代理权限控制代理权限控制是 Agent Manager 安全架构的核心组成部分。每个代理在创建时都会被分配一组权限定义，这些权限决定了代理可以执行的操作类型和可以访问的资源范围。权限定义采用灵活的规则匹配语法，支持通配符和否定模式，能够精确地控制代理对文件和操作的访问。从源码中可以看到权限配置的结构示例： ```typescript permission: { "*": "deny", // 默认拒绝所有操作 read: "allow", // 允许读取文件 grep: "allow", // 允许搜索文件内容 glob: "allow", // 允许文件模式匹配 edit: { // 编辑操作特殊规则 "*": "deny", "**/*.md": "allow" // 仅允许编辑 Markdown 文件 }, bash: "deny", // 拒绝终端命令 task: "ask", // 任务创建需要确认 skill: "deny" // 拒绝使用技能 } ``` 这种细粒度的权限控制机制确保了系统安全性，即使某个代理被利用或配置错误，其潜在的破坏范围也被限制在最小范围内。同时，权限规则支持继承和覆盖，子规则可以覆写父规则的设置，使得权限配置既简洁又灵活。 ### 模式切换与专用代理 Agent Manager 支持多种工作模式（Mode），每种模式对应不同的代理类型和配置。最常用的模式包括： - **Architect 模式**：专注于系统架构设计和规划，负责理解需求、制定技术方案 - **Coder 模式**：负责代码编写和实现，执行具体的开发任务 - **Reviewer 模式**：专门进行代码审查，发现潜在的 Bug 和改进点 - **Debugger 模式**：专注于问题定位和修复，执行调试任务用户可以通过斜杠命令（Slash Command）快速切换模式，例如 `/mode coder` 切换到编码模式，`/variant fast` 切换到快速推理变体。这些快捷命令简化了工作流程的操作步骤，提高了开发效率。专用代理（Dedicated Agent）是为特定任务或项目定制的代理实例，拥有专门的提示词、工具配置和权限设置。用户可以在配置文件中定义自己的代理模板，也可以在 VS Code 界面中通过向导创建和编辑代理配置。Agent Manager 的 webview 界面提供了直观的代理管理模式，包括创建、编辑、删除和权限配置等操作。 ## 配置管理 ### kilo.json 配置结构 Agent Manager 的配置通过 `kilo.json`（或 `kilo.jsonc`）文件管理，采用分层配置机制，支持远程配置、全局配置、项目配置和即时配置等多种来源。配置项按照优先级从低到高依次应用，后面的配置会覆盖前面的同名配置项。配置搜索路径按照以下顺序查找：远程 well-known 配置、全局配置（`~/.config/kilo/kilo.json`）、环境变量 `KILO_CONFIG`、项目根目录配置（`./kilo.json`）、`.kilo/kilo.json` 目录配置、以及 `KILO_CONFIG_CONTENT` 环境变量内容。这种设计确保了配置既有足够的灵活性，又保持了清晰的优先级关系。代理配置的关键字段包括：代理名称（name）、描述（description）、提示词（prompt）、使用的模型（model）、工具列表（tools）、权限规则（permission）、以及启动和运行脚本（setup/run scripts）。这些字段共同定义了代理的行为特征和能力边界。 ### 命令配置（Commands）命令是通过 Markdown 文件定义的自动化任务脚本，存储在 `.kilo/commands/` 目录中。每个命令文件包含 YAML 前置元数据和 Markdown 格式的命令体。元数据定义命令的元信息，如描述、关联的代理、使用的模型等；命令体包含实际的任务指令，可以使用模板变量引用参数。命令文件的结构示例： ```yaml --- description: 运行测试并修复失败 agent: code model: anthropic/claude-sonnet subtask: true --- 运行所有测试在 $1 并修复失败。使用 $ARGUMENTS 获取完整参数。通过 @file 引用文件，通过 !`cmd` 引用命令输出。 ``` 模板变量支持位置参数（`$1`、`$2` 等）、完整参数（`$ARGUMENTS`）、文件引用（`@file`）、以及命令输出引用（`!`cmd``）。这种参数化设计使得同一个命令模板可以灵活地处理不同的输入场景。 ## 工具注册与扩展 ### 工具注册表架构 Agent Manager 通过统一的工具注册表（Tool Registry）管理所有可用的工具扩展。工具注册表维护着一个工具定义列表，每个定义包含工具的唯一标识符、名称、描述、参数模式、以及执行函数。当代理需要使用某个工具时，注册表负责验证参数、执行工具逻辑、并返回结果给调用者。工具注册支持条件注册机制，通过 `agent_manager_tool` 标记控制工具在特定上下文中的可见性。例如，某些工具可能仅在 Agent Manager 模式下可用，而在普通编辑模式下被隐藏。这种条件注册确保了工具的合理使用场景，避免了功能滥用。注册表还提供了工具描述增强功能，可以根据额外的上下文信息（如语义搜索结果）自动丰富工具的描述信息。这种动态描述增强有助于代理更准确地理解工具的用途和使用方法，提高工具选择的准确性。 ### MCP 服务器集成 Agent Manager 通过 MCP（Model Context Protocol）服务器市场支持第三方工具扩展集成。用户可以浏览、搜索和安装来自社区的 MCP 服务器，扩展代理的工具能力。安装过程通过 VS Code 界面的引导式向导完成，包括依赖检查、参数配置和权限确认等步骤。 MCP 服务器的安装支持前置条件检查，例如某些服务器可能需要特定的 Node.js 版本或操作系统依赖。前置条件未满足时，向导会显示警告信息，并指导用户进行必要的准备工作。安装完成后，服务器会自动注册其提供的工具到全局注册表中，供所有代理使用。 ## Webview UI 交互 ### 迁移向导界面 Agent Manager 提供了直观的 Webview 用户界面，用于代理的创建、配置和管理。迁移向导（Migration Wizard）是用户首次使用时会接触到的引导界面，展示了新版本的主要功能特性，包括性能提升、界面改进和 Agent Manager 增强等模块。向导界面通过模块化的卡片布局展示功能特性，每个卡片包含图标、标题和详细说明。用户可以通过"了解更多"链接访问官方文档或博客文章，深入了解各项功能的细节。向导的底部提供了继续按钮，点击后进入主界面开始使用 Agent Manager。 ### 代理管理界面代理管理界面提供了对所有已配置代理的完整视图，支持创建新代理、编辑现有代理、调整权限配置、以及删除不需要的代理。每个代理的配置通过表单界面进行编辑，包括基本信息（名称、描述）、提示词配置、模型选择、工具启用和权限规则设置等。界面还提供了代理的使用统计信息，包括已执行的命令数量、成功率和平均响应时间等指标。这些统计数据帮助用户评估代理的效率，并根据需要进行调优。此外，界面支持代理配置的导入和导出，方便在团队成员之间共享标准化的代理模板。 ## 数据流与状态管理 ### 会话状态同步 Agent Manager 通过 VS Code 的消息传递机制实现 Webview 与扩展后端之间的状态同步。Webview 发送操作请求（如启动代理、切换模式），后端执行相应操作并通过消息推送状态更新到前端。这种双向通信机制确保了用户界面的实时性和一致性。状态管理采用集中式设计，所有会话状态（包括代理列表、运行状态、任务队列等）由 AgentManagerProvider 统一维护。前端通过订阅感兴趣的状态变更事件，在状态变化时自动重新渲染界面组件。这种响应式的状态管理简化了前端代码的复杂度，同时保证了数据的一致性。 ### 文件变更监控文件变更监控通过 `useFileMention` hook 实现，它监听编辑器中的文件提及事件，提供文件搜索、路径解析和附件管理功能。当用户在输入中引用文件路径时，hook 会自动触发文件搜索，返回匹配的文件列表供用户选择。文件提及系统支持多种类型的内容：普通文件、文件夹、终端会话、Git 变更等。每种类型都有对应的图标和展示格式，确保用户能够快速识别所选内容的性质。系统还支持拖拽添加文件路径，以及通过命令行自动补全功能快速插入文件引用。 ## 最佳实践 ### 代理设计原则设计高效的代理应遵循以下原则：单一职责（每个代理专注于特定类型的任务）、最小权限（仅授予完成任务所需的最小权限集）、清晰边界（明确定义代理之间的交互接口）、以及可观测性（确保代理行为可追踪和可调试）。对于复杂的多代理场景，建议采用渐进式分解策略：首先识别任务的主要阶段，然后为每个阶段设计专门的代理，最后定义代理之间的协作协议。这种方法既保证了系统的模块化，又避免了过早的复杂性引入。 ### 权限配置建议权限配置应遵循白名单原则（默认拒绝、按需开放）而非黑名单原则（默认允许、按需限制）。这种设计可以最大程度地减少安全风险，即使配置出现疏漏，未明确授权的操作也会被拒绝。对于涉及危险操作的工具（如删除文件、执行系统命令），建议设置为需要确认（`ask`），让用户在执行前有机会审查操作的影响。同时，应定期审查代理的权限配置，确保权限设置与实际需求保持一致，及时撤销不再需要的权限。 ## 常见问题与故障排除 ### 工作树冲突处理当多个代理在相同分支上工作时，可能会产生工作树冲突。如果两个代理尝试在同一个工作树中执行操作，系统会检测到冲突并自动将其中一个代理重新分配到新的工作树。如果仓库的工作树数量达到上限，系统会提示用户清理不再需要的工作树。手动解决冲突的方法包括：使用 `git worktree remove` 命令删除过期的分支，通过 `git branch -d` 删除已合并的分支，以及使用 VS Code 的 Git 图形界面查看和清理工作树状态。 ### 代理无响应处理如果代理长时间无响应，首先检查终端输出是否正常显示，可以通过 TerminalManager 查看命令的执行状态。如果命令本身在等待外部输入，代理会一直阻塞直到收到输入或超时。对于卡死的代理，可以尝试通过界面手动终止其任务，系统会自动清理相关的工作树和临时文件。如果问题持续发生，建议检查代理配置是否正确，特别是涉及网络请求的配置项（如代理设置、超时时间等）。 --- *本文档由 Kilo 官方技术团队维护，如有更新请参考 GitHub 仓库中的最新源码。* --- ## MCP 协议与工具集成 ### 相关页面相关主题：[Agent 核心系统](#agent-system), [系统架构设计](#system-architecture)

相关源码文件

以下源码文件用于生成本页说明： - [packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx) - [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts) - [packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) - [packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx) - [packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx)

# MCP 协议与工具集成 ## 概述 MCP（Model Context Protocol，模型上下文协议）是 KiloCode 中用于扩展 AI 能力的关键协议层。它允许 KiloCode 与外部工具和服务进行标准化通信，使 AI 能够调用文件系统操作、代码搜索、Shell 命令等能力。KiloCode 的 MCP 集成架构采用了模块化设计，将协议处理、工具注册、认证授权等核心功能解耦，确保系统的可扩展性和可维护性。 ## 架构设计 ### 整体架构 KiloCode 的 MCP 系统采用分层架构，包括协议层、工具层、认证层和 UI 集成层四个主要部分。 ```mermaid graph TD A[用户交互层] --> B[TUI/Session 组件] B --> C[MCP 协议处理] C --> D[工具注册表] D --> E[文件系统工具] D --> F[代码搜索工具] D --> G[Shell 工具] C --> H[认证授权模块] H --> I[OAuth 提供者] H --> J[Token 管理] E --> K[VSCode 集成] F --> K G --> K ``` ### 核心模块关系 | 模块 | 文件路径 | 职责 | |------|----------|------| | MCP 入口 | `packages/opencode/src/mcp/index.ts` | MCP 协议初始化和核心处理 | | 工具注册表 | `packages/opencode/src/kilocode/tool/registry.ts` | 工具定义、描述和注册 | | OAuth 提供者 | `packages/opencode/src/mcp/oauth-provider.ts` | OAuth 2.0 认证流程 | | 认证模块 | `packages/opencode/src/mcp/auth.ts` | Token 管理和安全验证 | | MCP 配置 | `packages/opencode/src/config/mcp.ts` | 配置管理和环境变量 | ## 工具注册系统 ### 工具注册表架构工具注册表是 KiloCode MCP 集成的核心组件，负责管理所有可用的工具定义。每个工具都包含唯一标识符、描述信息、执行逻辑和参数模式。注册表支持动态添加和移除工具，使系统能够在运行时扩展功能。在 `packages/opencode/src/kilocode/tool/registry.ts` 中，工具注册通过 `Tool.Def` 类型定义，支持为工具添加额外的元数据标记，如 `agent_manager_tool` 标志用于标识需要代理管理器参与的工具。 ### 核心工具类型 KiloCode 实现了多种类型的核心工具，覆盖了日常开发中的常见需求。 ```mermaid graph LR A[工具请求] --> B{工具类型判断} B -->|文件操作| C[Read/Write 工具] B -->|Shell| D[Bash 工具] B -->|搜索| E[Grep 工具] C --> F[文件系统] D --> G[系统命令] E --> H[代码索引] ``` | 工具名称 | 源文件 | 功能描述 | |----------|--------|----------| | bash | `packages/opencode/src/tool/bash.ts` | 执行 Shell 命令和脚本 | | read | `packages/opencode/src/tool/read.ts` | 读取文件内容和元数据 | | write | `packages/opencode/src/tool/write.ts` | 创建和修改文件 | | grep | `packages/opencode/src/tool/grep.ts` | 代码搜索和模式匹配 | | glob | 注册表中定义 | 文件名模式匹配 | | 代理管理 | registry.ts:工具注册 | 多代理协同任务管理 | ### 工具描述增强工具注册表提供了 `describe` 函数用于增强工具描述。该函数根据上下文条件为特定工具添加额外的使用提示信息，帮助 AI 更好地理解工具的使用场景和参数要求。资料来源：[packages/opencode/src/kilocode/tool/registry.ts:工具注册]() ## MCP 状态管理 ### TUI 状态显示在 KiloCode 的终端用户界面中，MCP 连接状态通过状态栏组件实时展示。用户可以直观地了解当前 MCP 连接的健康状况和错误状态。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP状态显示]() 状态显示组件实现了以下功能： - **连接状态指示器**：使用圆形图标表示连接状态，绿色表示正常，红色表示错误 - **MCP 服务计数**：显示当前活跃的 MCP 服务数量 - **错误状态展示**：当 MCP 服务出现错误时显示警告信息 ```mermaid stateDiagram-v2 [*] --> Disconnected: 初始状态 Disconnected --> Connecting: 用户连接 Connecting --> Connected: 连接成功 Connecting --> Error: 连接失败 Connected --> Disconnected: 用户断开 Connected --> Error: 服务异常 Error --> Connecting: 重试连接 Error --> Disconnected: 放弃连接 ``` ### 文件提及系统文件提及（Mention）是 KiloCode 中用于快速引用文件和目录的功能。该系统与 MCP 集成，允许用户通过 `@` 符号快速选择项目中的文件。资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:文件提及Hook]() 文件提及系统的核心流程包括： 1. **搜索触发**：用户输入 `@` 符号激活搜索 2. **异步搜索**：通过 MCP 协议向 VSCode 扩展发送搜索请求 3. **结果缓存**：使用 `frecency` 算法优化搜索结果的排序和缓存 4. **路径解析**：将相对路径转换为绝对路径供后续处理使用 ```mermaid sequenceDiagram participant User as 用户 participant TUI as 终端界面 participant Hook as useFileMention participant MCP as MCP 协议层 participant VSCode as VSCode 扩展 User->>TUI: 输入 @ 触发搜索 TUI->>Hook: 调用 setMentionQuery Hook->>MCP: 发送 fileSearchResult 请求 MCP->>VSCode: 转发搜索请求 VSCode-->>MCP: 返回文件列表 MCP-->>Hook: 传递搜索结果 Hook-->>TUI: 更新 mentionResults TUI-->>User: 显示下拉列表 ``` ## 配置管理 ### MCP 配置结构 MCP 配置通过 `packages/opencode/src/config/mcp.ts` 统一管理，支持从环境变量和配置文件两个渠道读取配置参数。 | 配置项 | 类型 | 说明 | 来源 | |--------|------|------|------| | mcp_servers | string[] | 启用的 MCP 服务器列表 | 环境变量 | | mcp_timeout | number | 请求超时时间（毫秒） | 配置文件 | | mcp_retry | number | 失败重试次数 | 配置文件 | | oauth_config | object | OAuth 认证配置 | 配置文件 | ### 认证配置 KiloCode 支持 OAuth 2.0 认证协议，用于安全地与外部服务建立连接。认证模块包含令牌管理、刷新机制和安全存储等功能。资料来源：[packages/opencode/src/mcp/auth.ts:认证模块]() 资料来源：[packages/opencode/src/mcp/oauth-provider.ts:OAuth提供者]() ## 自动补全集成 ### 提示词自动补全在终端界面的提示词输入组件中，MCP 工具的自动补全功能被深度集成。用户输入特定前缀时，系统会通过 MCP 协议获取可用的工具列表，并在下拉菜单中展示。资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:自动补全逻辑]() ### 文件提及与 MCP 交互自动补全组件与文件提及系统紧密协作。当用户引用文件时，组件会： 1. 解析文件路径并确定基础目录 2. 判断路径是绝对路径还是相对路径 3. 通过 MCP 协议获取文件信息 4. 更新编辑器的标记（extmark）以高亮显示引用 ```mermaid flowchart TD A[用户输入 /] --> B{输入内容判断} B -->|@符号| C[激活文件提及] B -->|工具前缀| D[激活工具补全] B -->|普通文本| E[普通输入处理] C --> F[MCP 文件搜索] D --> G[MCP 工具列表] F --> H[更新提及索引] G --> I[显示工具选项] H --> J[用户选择] I --> J J --> K[插入引用内容] K --> L[创建文件部分] ``` ## 错误处理机制 ### MCP 错误状态当 MCP 服务出现错误时，状态栏会显示错误指示器。系统会区分不同类型的错误，并提供相应的用户反馈。资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP错误状态]() 错误处理策略包括： - **连接失败**：显示重试选项，用户可手动触发重新连接 - **认证过期**：自动触发 Token 刷新流程 - **服务不可用**：标记服务状态并在工具列表中隐藏不可用项 - **超时错误**：根据配置的重试策略自动重试 ## 与 VSCode 扩展的集成 ### 通信机制 KiloCode 的 MCP 系统通过 VSCode 扩展提供的消息通道与编辑器进行双向通信。Webview UI 中的 React 组件使用特定的 Hook 与 MCP 后端交互。文件提及功能的实现涉及多个层次的协作： 1. **UI 层**：`useFileMention` Hook 管理搜索状态和结果 2. **通信层**：通过 `onMessage` 回调处理来自扩展的消息 3. **协议层**：MCP 协议定义消息格式和路由规则 4. **后端层**：VSCode 扩展执行实际的文件系统操作 ## 扩展性设计 ### 添加新工具 KiloCode 的工具注册系统设计支持便捷的功能扩展。添加新工具的流程包括： 1. 在 `packages/opencode/src/tool/` 目录下创建新的工具文件 2. 定义工具的输入输出模式 3. 在 `registry.ts` 中注册工具定义 4. 添加工具的执行逻辑 5. 在 UI 层添加对应的补全支持 ### MCP 服务器配置外部 MCP 服务器可以通过配置文件或环境变量添加到 KiloCode。系统支持热加载配置，无需重启即可启用新的 MCP 服务。 ## 最佳实践 ### 开发新工具 | 阶段 | 关键点 | 参考文件 | |------|--------|----------| | 设计 | 明确输入输出类型和错误处理 | `packages/opencode/src/tool/read.ts` | | 实现 | 遵循现有工具的文件结构 | `packages/opencode/src/tool/bash.ts` | | 注册 | 在 registry 中添加工具定义 | `packages/opencode/src/kilocode/tool/registry.ts` | | 测试 | 使用 MCP 协议测试工具调用 | - | | 文档 | 更新自动补全的提示文本 | `packages/opencode/src/cli/cmd/tui/component/prompt/` | ### 故障排查常见的 MCP 相关问题及排查方向： - **工具不可用**：检查工具是否在注册表中正确注册 - **搜索无结果**：验证 MCP 服务器连接状态 - **认证失败**：检查 OAuth 配置和 Token 有效期 - **状态显示异常**：查看 TUI 状态栏的错误信息 --- ## 代码索引与语义搜索 ### 相关页面相关主题：[自动补全系统 (FIM)](#autocomplete-system), [Agent 核心系统](#agent-system)

相关源码文件

以下源码文件用于生成本页说明： - [packages/kilo-indexing/src/indexing/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/index.ts) - [packages/kilo-indexing/src/indexing/manager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/manager.ts) - [packages/kilo-indexing/src/indexing/orchestrator.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/orchestrator.ts) - [packages/kilo-indexing/src/tree-sitter/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/index.ts) - [packages/kilo-indexing/src/tree-sitter/languageParser.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/languageParser.ts) - [packages/kilo-indexing/src/indexing/embedders/openai.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/embedders/openai.ts) - [packages/kilo-indexing/src/indexing/vector-store/lancedb-vector-store.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/vector-store/lancedb-vector-store.ts) - [packages/opencode/src/tool/semantic-search.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/semantic-search.ts)

# 代码索引与语义搜索 ## 概述 KiloCode 的代码索引与语义搜索系统是一个多层次的代码理解和检索解决方案，旨在为开发者提供基于代码语义的高效搜索能力。该系统通过集成 Tree-sitter 语法解析、向量嵌入和语义向量存储技术，实现了对代码库的深度索引，使得开发者可以使用自然语言描述来查找相关代码片段。该系统位于 `packages/kilo-indexing` 包中，作为 KiloCode 平台的核心基础设施之一，为 IDE 扩展和 CLI 工具提供统一的代码理解能力。 ## 系统架构 ### 核心组件代码索引与语义搜索系统由以下核心组件构成： | 组件 | 文件路径 | 职责描述 | |------|----------|----------| | 索引管理器 | `packages/kilo-indexing/src/indexing/manager.ts` | 协调和管理整个索引生命周期 | | 索引协调器 | `packages/kilo-indexing/src/indexing/orchestrator.ts` | 编排增量索引和全量索引任务 | | Tree-sitter 解析器 | `packages/kilo-indexing/src/tree-sitter/languageParser.ts` | 解析多种编程语言的语法树 | | 向量嵌入器 | `packages/kilo-indexing/src/indexing/embedders/openai.ts` | 生成代码片段的语义向量 | | 向量存储 | `packages/kilo-indexing/src/indexing/vector-store/lancedb-vector-store.ts` | 存储和检索向量数据 | | 语义搜索工具 | `packages/opencode/src/tool/semantic-search.ts` | 提供给 LLM 调用的搜索接口 | ### 架构流程图 ```mermaid graph TD A[源代码文件] --> B[Tree-sitter 解析器] B --> C[语法树节点] C --> D[代码分块策略] D --> E[代码片段] E --> F[OpenAI 嵌入器] F --> G[语义向量] G --> H[LanceDB 向量存储] I[用户查询] --> J[语义搜索工具] J --> K[查询向量生成] K --> H H --> L[相似度匹配] L --> M[搜索结果排序] M --> N[返回相关代码片段] ``` ## 索引管理 ### 索引生命周期索引管理器负责处理代码库从初始扫描到增量更新的完整生命周期。系统支持增量索引策略，仅对修改过的文件进行重新索引，以优化性能并减少资源消耗。索引状态在用户界面中实时显示，状态信息包括当前索引进度、已索引文件数量和索引完成百分比。系统会根据索引状态调整配色方案，使用不同色调传达当前索引状态。 ```typescript // 索引状态显示逻辑示例 {indexingText(indexing()).slice(0, 48)} ``` 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx]() ### 向量存储系统使用 LanceDB 作为底层向量存储解决方案，这是一种专为机器学习应用设计的高性能嵌入式数据库。向量存储负责持久化代码片段的语义向量表示，并支持高效的相似度搜索查询。向量存储的数据模型包含以下关键字段： | 字段 | 类型 | 描述 | |------|------|------| | id | string | 唯一标识符 | | code | string | 原始代码文本 | | embedding | float[] | 语义向量 | | filePath | string | 文件路径 | | language | string | 编程语言 | | startLine | number | 代码块起始行 | | endLine | number | 代码块结束行 | | symbols | string[] | 提取的符号信息 | ## 语法解析 ### Tree-sitter 集成 Tree-sitter 是 KiloCode 代码索引系统的语法分析引擎，提供了增量解析能力，能够高效处理大型代码库。系统支持多种主流编程语言的语法解析，包括 JavaScript、TypeScript、Python、Go、Rust 等。语法解析器将源代码转换为抽象语法树（AST），在此基础上进行代码分块和符号提取。分块策略是影响搜索质量的关键因素，系统会根据语言特性采用不同的分块方法，确保每个代码片段具有完整的语义上下文。 ### 语言解析器配置每种编程语言都有对应的解析器配置文件，定义了语言特定的语法规则和代码块边界识别逻辑。语言解析器还负责提取代码中的关键符号信息，包括函数名、类名、变量名等，这些信息用于增强搜索匹配的准确性。 ## 向量嵌入 ### OpenAI 嵌入集成系统使用 OpenAI 的文本嵌入模型将代码片段转换为高维向量。嵌入器负责将原始代码文本转换为固定维度的浮点数向量，这些向量捕捉了代码的语义特征，使得语义相似的代码在向量空间中彼此接近。嵌入器配置支持以下参数： | 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | model | string | text-embedding-3-small | OpenAI 嵌入模型名称 | | dimensions | number | 1536 | 向量维度 | | batchSize | number | 100 | 批处理大小 | ### 向量生成流程代码片段经过预处理后被发送到 OpenAI API 进行嵌入。预处理步骤包括移除注释、规范化空白字符和添加语言提示信息。语言提示帮助嵌入模型更好地理解代码语义，提高跨语言代码搜索的准确性。 ## 语义搜索 ### 搜索接口语义搜索通过专门的工具接口暴露给 LLM，LLM 可以调用该工具进行代码搜索。搜索接口接受自然语言查询，返回与查询意图最相关的代码片段及其在代码库中的位置信息。 ```typescript // 语义搜索工具配置 ToolRegistry.register({ name: "semantic_search", // 搜索工具实现 }) ``` 资料来源：[packages/opencode/src/tool/semantic-search.ts]() ### 搜索结果排序搜索结果根据向量相似度分数进行排序，系统返回最相关的 Top-N 个代码片段。每个结果包含文件路径、行号范围、代码内容和相似度分数。LLM 可以利用这些信息直接跳转到相关代码位置。 ### 搜索增强策略系统支持多种搜索增强策略以提高搜索结果质量： - **符号匹配增强**：优先返回包含查询关键词符号的代码片段 - **上下文扩展**：返回代码片段时同时提供周围的上下文代码 - **多语言支持**：跨语言搜索相关的代码实现 - **过滤机制**：支持按文件类型、目录路径等条件过滤搜索结果 ## 配置与调优 ### 索引配置选项 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | enabled | boolean | true | 是否启用索引功能 | | maxFileSize | number | 1048576 | 单文件最大字节数 | | excludedPatterns | string[] | ["node_modules", "dist", "build"] | 排除的文件模式 | | indexInterval | number | 300000 | 增量索引间隔（毫秒） | | embeddingModel | string | text-embedding-3-small | 嵌入模型选择 | ### 性能优化系统采用多级缓存策略减少重复计算，索引结果缓存在本地以支持快速重启。向量存储采用分区策略，按编程语言和目录结构进行数据分区，搜索时仅扫描相关分区以提高查询效率。 ## 使用场景 ### IDE 集成在 VS Code 扩展中，索引系统为以下功能提供支持： - 智能代码补全建议 - 语义跳转定义 - 查找引用 - 相关代码推荐 ### CLI 工具在 TUI 界面的会话组件中，索引状态实时显示在底部状态栏，用户可以直观地了解当前代码库的索引进度和可用性状态。 ## 技术限制与注意事项 - 向量嵌入依赖外部 API，网络延迟可能影响索引性能 - 大型代码库的初始索引需要较长时间，建议在后台执行 - 部分编程语言的语法解析可能不完全支持最新语言特性 --- ## IDE 扩展实现 ### 相关页面相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)

相关源码文件

以下源码文件用于生成本页说明： - [packages/kilo-vscode/src/extension.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts) - [packages/kilo-vscode/webview-ui/src/App.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/App.tsx) - [packages/kilo-vscode/src/kilo-provider/KiloProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/kilo-provider/KiloProvider.ts) - [packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts) - [packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx) - [packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx) - [packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts) - [packages/kilo-vscode/webview-ui/src/components/profile/DeviceAuthCard.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/profile/DeviceAuthCard.tsx) - [packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx) - [packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx)

# IDE 扩展实现 ## 概述 KiloCode 是一个跨平台的 AI 编程助手，通过 IDE 扩展的形式集成到主流开发环境中。目前支持的 IDE 包括 Visual Studio Code 和 JetBrains 系列（如 IntelliJ IDEA、WebStorm 等）。 IDE 扩展的核心职责包括： - **会话管理**：创建和管理与 AI 模型的交互会话 - **编辑器集成**：在 IDE 中嵌入 WebView 用户界面 - **文件操作**：监听文件变化、处理文件提及和附件 - **工具调用**：注册和执行各种开发工具（如终端、Git、浏览器自动化等） - **命令系统**：支持斜杠命令（Slash Commands）和快捷操作 ## 架构设计 ### 整体架构 ```mermaid graph TD A[IDE 宿主] --> B[扩展后端] A --> C[扩展前端 WebView] B --> D[Kilo 后端服务] C --> B C --> E[本地文件操作] B --> F[AI 模型] F --> B ``` ### VS Code 扩展架构 VS Code 扩展采用双层架构设计： 1. **后端层（Extension Host）**：运行在 Node.js 环境，负责与 VS Code API 和 Kilo 后端通信 2. **前端层（WebView）**：运行在独立的 WebView 环境中，负责用户界面渲染 ```mermaid graph LR A[VS Code API] --> B[Extension.ts] B --> C[KiloProvider] C --> D[WebView 通信] D --> E[App.tsx] E --> F[React 组件] F --> G[Hooks] G --> H[VSCodeContext] ``` ### JetBrains 扩展架构 JetBrains 扩展采用类似的分层设计，但使用不同的技术栈： ```mermaid graph TD A[JetBrains 平台] --> B[KiloToolWindowFactory] B --> C[KiloBackendAppService] C --> D[KiloSessionRpcApi] D --> E[RPC 通信层] E --> F[Kilo 后端服务] ``` ## 核心组件 ### VS Code 扩展入口 `packages/kilo-vscode/src/extension.ts` 是扩展的入口文件，负责初始化整个扩展： ```typescript // 扩展激活入口 export function activate(context: ExtensionContext) { // 初始化 KiloProvider // 注册命令 // 建立 WebView 通信通道 } ``` 主要职责： - 注册 VS Code 命令（如 `kilo.open`、`kilo.sendMessage`） - 初始化 `KiloProvider` 实例 - 处理扩展生命周期事件 ### KiloProvider `KiloProvider` 是核心的状态管理和通信中心，位于 `packages/kilo-vscode/src/kilo-provider/KiloProvider.ts:1`： ```typescript // KiloProvider 核心职责 - 管理会话状态 - 处理消息路由 - 与后端服务通信 - 管理文件搜索和提及 ``` ### WebView 应用 `App.tsx` 是前端 WebView 的根组件，负责整体布局和状态协调： ```typescript // App.tsx 核心功能 - 提供全局上下文 - 路由管理 - 错误边界 - 迁移向导集成 ``` ## 通信机制 ### WebView 与扩展后端的通信 KiloCode 使用 `postMessage` API 实现 WebView 与扩展后端的双向通信： ```mermaid sequenceDiagram participant W as WebView participant E as Extension Host participant B as Kilo Backend W->>E: postMessage({ type: "fileSearchResult", items }) E->>B: 转发请求 B->>E: 返回结果 E->>W: postMessage({ type, data }) ``` ### 消息类型定义 | 消息类型 | 方向 | 用途 | |---------|------|------| | `fileSearchResult` | 后端→前端 | 文件搜索结果 | | `openSettingsPanel` | 前端→后端 | 打开设置面板 | | `openExternal` | 前端→后端 | 打开外部链接 | | `toggleRemote` | 前端→后端 | 切换远程控制 | 消息通过 `vscode.onMessage` 回调处理，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24`： ```typescript const unsubscribe = vscode.onMessage((message) => { if (message.type !== "fileSearchResult") return if (message.requestId === `file-search-${fileSearchCounter}`) { const items = message.items ?? message.paths.map((path) => ({ path, type: "file" })) // 处理结果 } }) ``` ## 核心功能模块 ### 文件提及系统 `useFileMention` Hook 实现了智能文件提及功能，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:9`： ```typescript export function useFileMention( vscode: VSCodeContext, sessionID?: Accessor, git?: Accessor, ): FileMention { const [mentionedPaths, setMentionedPaths] = createSignal>(new Set()) const [mentionQuery, setMentionQuery] = createSignal(null) const [mentionResults, setMentionResults] = createSignal([]) const [mentionIndex, setMentionIndex] = createSignal(0) // 文件搜索防抖处理 let fileSearchTimer: ReturnType | undefined let fileSearchCounter = 0 } ``` 功能特性： - 实时文件搜索和建议 - 支持 `@` 触发文件提及 - 与 Git 状态集成 - 拖拽文件自动注册 ### 斜杠命令系统 `useSlashCommand` Hook 管理斜杠命令菜单，参考 `packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts:1`： ```typescript // 可用命令列表 const commands = [ { name: "mode", description: "Switch the agent mode", hints: ["modes"], action: () => { window.dispatchEvent(new CustomEvent("openModePicker")) }, }, { name: "variant", description: "Switch the reasoning effort", hints: ["variants", "reasoning", "thinking"], action: () => { window.dispatchEvent(new CustomEvent("openVariantPicker")) }, }, // ... 更多命令 ] ``` ### 用户界面组件 #### 迁移向导 `MigrationWizard.tsx` 组件处理版本迁移引导，参考 `packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1`： ```typescript // 新版本特性展示

{language.t("migration.whatsNew.features.performance.title")}

{language.t("migration.whatsNew.features.performance.detail")}

// ... 更多特性

``` #### 设备授权卡片 `DeviceAuthCard.tsx` 处理 OAuth 设备授权流程，参考 `packages/kilo-vscode/webview-ui/src/components/profile/DeviceAuthCard.tsx:1`： ```typescript // 设备授权步骤

{language.t("deviceAuth.step1")}

{deviceCode}

``` ### MCP 市场集成 `InstallModal.tsx` 组件实现 MCP 服务器的安装界面，参考 `packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx:1`： ```typescript // 前置条件检查 0}> // 参数输入 {(param) => ( setParam(param.key, v)} /> )} ``` ## 文件操作集成 ### 输入提示组件 `PromptInput.tsx` 处理用户输入和文件提及，参考 `packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx:1`： ```typescript // 文件提及类型渲染 {(item) => (

{item.type === "terminal" ? ( <> {item.label} ) : item.type === "git-changes" ? ( <> {item.label} ) : ( <> {item.label} )}

)} ``` ### 自动补全 `autocomplete.tsx` 实现 TUI 界面的自动补全功能，参考 `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1`： ```typescript // 文件部分处理 if (part.type === "file" && part.source?.text) { part.source.text.start = extmarkStart part.source.text.end = extmarkEnd part.source.text.value = virtualText } // 更新访问频率用于排序 if (part.type === "file" && part.source && part.source.type === "file") { frecency.updateFrecency(part.source.path) } ``` ## JetBrains 扩展 ### 后端服务 `KiloBackendAppService.kt` 是 JetBrains 扩展的后端服务： ```kotlin // 主要职责 class KiloBackendAppService { // 会话管理 // 与 Kilo 后端通信 // 处理 IDE 事件 } ``` ### 工具窗口工厂 `KiloToolWindowFactory.kt` 创建和管理工具窗口： ```kotlin class KiloToolWindowFactory : ToolWindowFactory { override fun createToolWindowContent(project: Project, toolWindow: ToolWindow) { // 创建工具窗口内容 // 初始化通信通道 } } ``` ### RPC API `KiloSessionRpcApi.kt` 定义了会话 RPC 接口： ```kotlin interface KiloSessionRpcApi { // 发送消息 // 接收响应 // 管理会话状态 } ``` ## 配置管理 ### 配置优先级配置查找顺序（低优先级到高优先级）： | 优先级 | 来源 | |-------|------| | 1 | 远程已知配置 | | 2 | 全局配置 `~/.config/kilo/kilo.json` | | 3 | 环境变量 `KILO_CONFIG` | | 4 | 项目配置 `./kilo.json` | | 5 | 项目子目录 `.kilo/kilo.json` | | 6 | 内联环境变量 `KILO_CONFIG_CONTENT` | | 7 | 托管配置 | 配置采用深度合并策略，后者覆盖前者。资料来源：[packages/opencode/src/kilocode/skills/kilo-config.md:1]() ### 配置文件结构 ```yaml # 命令配置示例 (.kilo/command/*.md) --- description: Run tests agent: code model: anthropic/claude-sonnet subtask: true --- Run all tests in $1 and fix failures. ``` ## 状态管理 ### 状态类型 | 状态类型 | 说明 | |---------|------| | `mentionedPaths` | 当前会话中提及的文件路径集合 | | `mentionQuery` | 文件搜索查询字符串 | | `mentionResults` | 文件搜索结果列表 | | `mentionIndex` | 当前选中的建议索引 | | `sessionID` | 当前会话标识符 | ### 状态更新流程 ```mermaid sequenceDiagram participant U as 用户输入 participant H as useFileMention participant B as 后端 participant S as 状态 U->>H: 输入触发 @ H->>H: setMentionQuery(query) H->>B: 发送文件搜索请求 B->>H: 返回搜索结果 H->>S: setMentionResults(results) U->>H: 选择建议 H->>H: setMentionIndex(index) H->>H: closeMention() ``` ## 国际化 ### 语言键命名空间 | 命名空间 | 用途 | |---------|------| | `migration.*` | 迁移向导相关文本 | | `deviceAuth.*` | 设备授权流程 | | `marketplace.*` | MCP 市场界面 | | `ui.tool.*` | 工具显示名称 | | `ui.message.*` | 消息和提示 | ## 总结 KiloCode 的 IDE 扩展实现采用了模块化和分层架构设计，通过 WebView 嵌入、消息通信、状态管理等机制，在保持与 IDE 紧密集成的同时，确保了用户界面的流畅性和功能的可扩展性。VS Code 和 JetBrains 扩展共享相似的设计理念，但在具体实现上针对各平台特性进行了优化。 --- ## CLI 工具与 SDK 开发 ### 相关页面相关主题：[Kilo Code 简介与快速入门](#introduction), [MCP 协议与工具集成](#mcp-integration)

相关源码文件

以下源码文件用于生成本页说明： - [packages/opencode/src/cli/bootstrap.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/bootstrap.ts) - [packages/opencode/src/cli/cmd/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/agent.ts) - [packages/opencode/src/cli/cmd/tui/app.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx) - [packages/opencode/src/cli/cmd/run.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/run.ts) - [packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts) - [packages/opencode/src/plugin/loader.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/plugin/loader.ts) - [packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts) - [packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts)

# CLI 工具与 SDK 开发 ## 概述 KiloCode 提供了一套完整的命令行工具和软件开发包（SDK），旨在为开发者提供灵活、模块化的代码辅助能力。该系统由以下几个核心部分组成： | 组件 | 功能描述 | |------|----------| | **OpenCode CLI** | 核心命令行工具，支持交互式 TUI 和脚本模式 | | **TUI 界面** | 终端用户界面，提供可视化交互体验 | | **Plugin 系统** | 插件加载机制，支持扩展功能 | | **SDK** | JavaScript/TypeScript 开发包，用于二次开发 | ## CLI 架构设计 ### 命令行入口 CLI 工具采用分层架构设计，主要入口通过 `bootstrap.ts` 完成初始化，随后根据用户输入分发到不同的命令处理器。 ```mermaid graph TD A[CLI 入口] --> B[Bootstrap 初始化] B --> C[命令解析] C --> D[agent 命令] C --> E[run 命令] C --> F[TUI 模式] D --> G[Agent 执行器] E --> H[任务运行器] F --> I[TUI 应用] ``` ### 核心命令模块 #### Agent 命令 `agent.ts` 负责处理 Agent 相关的操作，包括会话管理、模型选择和消息处理。该模块是 CLI 与 AI 模型交互的核心通道。 #### Run 命令 `run.ts` 提供非交互式的批处理能力，适用于自动化脚本和 CI/CD 场景。用户可以通过命令行参数直接指定任务和配置。 #### TUI 应用 TUI（Terminal User Interface）模块采用组件化设计，主要结构包括： | 组件 | 路径 | 职责 | |------|------|------| | `app.tsx` | `packages/opencode/src/cli/cmd/tui/app.tsx` | 根组件，应用状态管理 | | `session/index.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` | 会话界面渲染 | | `footer.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx` | 状态栏组件 | | `prompt/index.tsx` | `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` | 提示词输入组件 | 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-60]() ### 消息渲染系统会话界面采用 Switch/Match 模式处理不同类型的消息部分： ```typescript const PART_MAPPING = { text: TextPart, tool: ToolPart, reasoning: ReasoningPart, } ``` - **TextPart**: 普通文本消息渲染 - **ToolPart**: 工具调用结果显示 - **ReasoningPart**: AI 推理过程展示，支持折叠显示资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:70-85]() ### 状态栏组件 Footer 组件显示当前会话的关键状态信息： | 状态项 | 说明 | |--------|------| | LSP 连接 | 显示已连接的 Language Server 数量 | | MCP 连接 | Model Context Protocol 连接状态 | | 索引状态 | 代码索引进度 | | 权限提示 | 当前会话所需的权限列表 | 资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-50]() ## 插件系统 ### 插件加载器 KiloCode 采用模块化的插件架构，通过 `loader.ts` 实现动态插件加载： ```mermaid graph LR A[插件目录] --> B[Loader 扫描] B --> C[模块解析] C --> D[注册到系统] D --> E[运行时调用] ``` ### 插件接口定义插件系统提供标准化的接口规范，定义在 `packages/plugin/src/index.ts` 中： | 接口方法 | 功能 | |----------|------| | `register()` | 注册插件，提供名称和版本 | | `initialize()` | 初始化插件资源 | | `execute()` | 执行插件核心逻辑 | | `cleanup()` | 清理插件资源 | 资料来源：[packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts) ## SDK 开发 ### JavaScript SDK JavaScript SDK 位于 `packages/sdk/js/src/index.ts`，提供完整的 API 接口用于集成 KiloCode 功能： ```mermaid graph TD A[JS SDK] --> B[会话管理] A --> C[消息发送] A --> D[文件操作] A --> E[模型配置] B --> F[createSession] C --> G[sendMessage] D --> H[attachFile] E --> I[setModel] ``` ### SDK 核心功能 | 功能模块 | API 方法 | 说明 | |----------|----------|------| | 会话管理 | `createSession()` | 创建新的会话实例 | | 消息交互 | `sendMessage()` | 发送消息并获取响应 | | 文件附件 | `attachFile()` | 向会话添加文件上下文 | | 模型配置 | `setModel()` | 设置使用的 AI 模型 | 资料来源：[packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts) ## 配置系统 ### 配置文件结构配置管理由 `config.ts` 统一处理，支持多种配置来源： | 配置源 | 优先级 | 格式 | |--------|--------|------| | 环境变量 | 最高 | `KILO_*` 前缀 | | 命令行参数 | 高 | `--key value` | | 配置文件 | 中 | `kilo.config.ts` | | 默认值 | 最低 | 内置默认值 | 资料来源：[packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts) ### 关键配置项 ```typescript interface KiloConfig { model: string // 默认模型 ID provider: string // 模型提供者 apiKey?: string // API 密钥 temperature?: number // 生成温度参数 maxTokens?: number // 最大 token 数 } ``` ## 开发指南 ### 本地开发环境搭建 1. 克隆仓库并安装依赖 2. 构建项目：`pnpm build` 3. 链接本地包：`pnpm link --global` 4. 运行 CLI：`opencode` 或 `kilo` ### 调试技巧 | 方法 | 说明 | |------|------| | `DEBUG=* opencode` | 启用完整调试日志 | | `opencode --verbose` | 显示详细执行信息 | | 查看 TUI 日志 | 状态栏 `/status` 命令 | ### 创建自定义插件 ```typescript import { Plugin, PluginContext } from '@kilo/plugin' export default class MyPlugin implements Plugin { name = 'my-plugin' version = '1.0.0' register(ctx: PluginContext) { ctx.registerCommand({ name: 'my-command', handler: async (args) => { // 处理逻辑 } }) } } ``` ## 技术栈总结 | 层级 | 技术选型 | 用途 | |------|----------|------| | CLI 框架 | TypeScript | 类型安全的命令行工具 | | UI 框架 | Solid.js | 高性能响应式界面 | | TUI 渲染 | Ink/自定义 | 终端界面渲染 | | 构建工具 | Vite | 快速开发和打包 | | 包管理 | pnpm | 高效的依赖管理 | ## 相关资源 - 官方文档：https://kilo.ai/docs/ - 博客公告：https://blog.kilo.ai/ - 问题反馈：https://github.com/Kilo-Org/kilocode/issues --- --- ## Doramagic 踩坑日志项目：Kilo-Org/kilocode 暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。