项目概述

Kilo Code 是一个现代化的人工智能辅助编程工具，通过集成多种语言模型和开发工具，为开发者提供智能化的代码编写、理解和编辑体验。该项目采用多平台架构，支持命令行界面（CLI）和 VS Code 扩展两种主要交互方式。

Kilo Code 的核心设计理念是将强大的人工智能能力与开发者的日常工作流程无缝结合，提供快速、准确且上下文感知的代码协助。系统支持多种 AI 提供商，包括 OpenAI、Anthropic、Google、Mistral、Moonshot 等主流模型服务。

资料来源：README.md

系统架构

Kilo Code 采用模块化设计，主要由以下核心包组成：

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

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

核心功能

智能对话与代码生成

Kilo Code 提供完整的对话式编程体验，支持：

• 多轮对话: 维护对话上下文，支持复杂任务的分解和逐步解决
• 代码生成: 根据自然语言描述生成代码片段
• 代码解释: 解释现有代码的功能和逻辑
• 错误修复: 分析错误信息并提供修复建议

消息系统支持多种内容类型，包括普通文本、工具调用、推理过程（reasoning）和文件变更。

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-100

文件引用与附件

Kilo Code 支持通过 @ 符号引用文件，实现以下功能：

文件引用系统会自动搜索匹配的文件路径，并在用户输入时提供自动完成建议。拖拽文件到输入区域也会自动创建引用。

资料来源：packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts

工具系统

Kilo Code 内置强大的工具系统，支持以下核心工具：

工具输出支持差异视图（Diff View），清晰展示添加、删除和修改的内容。

资料来源：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

LSP 支持

Kilo Code 集成 Language Server Protocol，提供：

• 代码补全建议
• 语法检查和错误提示
• 跳转到定义
• 查找引用

状态栏显示当前活动的 LSP 服务器数量。

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx

推理过程显示

对于支持推理的模型，Kilo Code 可以显示 AI 的思考过程：

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

支持的 AI 提供商

Kilo Code 支持众多 AI 模型提供商，形成完整的生态系统：

资料来源：packages/kilo-ui/src/stories/provider-icon.stories.tsx

快速入门

安装方式

#### VS Code 扩展安装

1. 打开 VS Code
2. 进入扩展市场，搜索 "Kilo"
3. 点击安装按钮
4. 安装完成后，点击侧边栏的 Kilo 图标开始使用

扩展版本信息可在 package.json 中查看：

{
  "name": "kilo-vscode",
  "version": "1.x.x",
  "displayName": "Kilo"
}

资料来源：packages/kilo-vscode/package.json

#### CLI 安装

# 使用 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

基本使用

#### CLI 模式

# 启动交互式会话
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      # 引用文件特定行

#### 拖拽添加

直接将文件从资源管理器拖拽到聊天输入区域，系统会自动创建文件引用。

快捷键

资料来源：packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx

认证与授权

OAuth 回调处理

Kilo Code 使用 OAuth 2.0 进行第三方服务认证：

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

状态与监控

状态栏指示器

CLI 和 VS Code 扩展都在状态栏显示关键信息：

权限提示

当操作需要额外权限时，状态栏会显示警告信息：

△ 3 Permissions

资料来源：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 等本地模型服务。配置相应的提供商地址即可使用。

下一步

• 查看官方文档获取完整使用指南
• 访问博客了解最新更新
• 参与 GitHub 讨论提出问题和建议
• 报告 Issue 帮助改进产品

概述

KiloCode 是一个模块化的 AI 代码辅助平台，采用 Monorepo 架构组织代码。项目使用 turbo.json 作为构建编排工具，将功能划分为多个独立的包（packages），每个包专注于特定的功能领域。

KiloCode 的包组织结构遵循以下核心原则：

• 模块独立性：每个包拥有独立的功能边界，可独立测试和部署
• 代码共享：通过 @kilo 前缀的共享包实现跨包复用
• 多端适配：支持 VS Code、JetBrains IDE、命令行界面等多种客户端

核心包结构

包架构总览

graph TD
    subgraph "核心共享包"
        UI[kilo-ui<br/>UI 组件库]
        UIShared[ui<br/>通用 UI 工具]
    end
    
    subgraph "平台包"
        VSCODE[kilo-vscode<br/>VS Code 扩展]
        JETBRAINS[kilo-jetbrains<br/>JetBrains 插件]
        OPENCODE[opencode<br/>命令行工具]
    end
    
    subgraph "后端服务"
        GATEWAY[kilo-gateway<br/>API 网关]
        INDEXING[kilo-indexing<br/>代码索引服务]
    end
    
    UI --> VSCODE
    UI --> JETBRAINS
    UIShared --> UI
    GATEWAY --> INDEXING
    
    style UI fill:#e1f5fe
    style VSCODE fill:#fff3e0
    style OPENCODE fill:#f3e5f5

包功能对照表

目录结构规范

标准包结构

packages/<package-name>/
├── 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

组件分层架构

graph LR
    A[业务组件<br/>MigrationWizard] --> B[功能组件<br/>PromptInput]
    B --> C[基础组件<br/>FileIcon]
    C --> D[UI 原子<br/>Button, TextField]
    
    style A fill:#ffcdd2
    style B fill:#fff9c4
    style C fill:#c8e6c9
    style D fill:#bbdefb

Hooks 与状态管理

自定义 Hooks 模式

useFileMention 是典型的自定义 Hook，用于处理文件提及功能：

export function useFileMention(
  vscode: VSCodeContext,
  sessionID?: Accessor<string | undefined>,
  git?: Accessor<boolean>,
): FileMention {
  // 文件搜索状态
  const [mentionedPaths, setMentionedPaths] = createSignal<Set<string>>(new Set())
  const [mentionQuery, setMentionQuery] = createSignal<string | null>(null)
  const [mentionResults, setMentionResults] = createSignal<MentionResult[]>([])
  const [mentionIndex, setMentionIndex] = createSignal(0)
  
  // 搜索防抖
  let fileSearchTimer: ReturnType<typeof setTimeout> | undefined
  let fileSearchCounter = 0
  
  // ...
}

资料来源：packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24-38

Hook 职责表

文件图标系统

图标映射机制

文件图标系统通过文件名和扩展名映射到对应的图标：

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

支持的文件类型

TUI 组件架构

命令行工具采用 React-like 的 TUI 组件体系：

graph TD
    subgraph "TUI 路由层"
        SESSION[index.tsx<br/>会话路由]
        FOOTER[footer.tsx<br/>状态栏]
        PERMISSION[permission.tsx<br/>权限管理]
    end
    
    subgraph "TUI 组件层"
        PROMPT[prompt/index.tsx<br/>输入组件]
        AUTOCOMPLETE[autocomplete.tsx<br/>自动完成]
        DIALOG[dialog-export-options.tsx<br/>对话框]
    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 定义了消息渲染的核心逻辑：

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 进行注册和渲染：

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 与认证

回调处理流程

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 回调页面支持多语言显示：

const HTML_SUCCESS = `<!DOCTYPE html>
<html>
<head>
  <title>Kilo - Authorization Successful</title>
  <!-- kilocode_change start -->
  <p>You can close this window and return to Kilo.</p>
  <!-- kilocode_change end -->
</head>
<body>
  <h1>Authorization Successful</h1>
  <script>setTimeout(() => window.close(), 2000);</script>
</body>
</html>`

资料来源：packages/opencode/src/mcp/oauth-callback.ts:1-25

状态栏组件

底部状态栏信息

状态栏组件展示连接状态、权限、LSP、MCP 等信息：

<Show when={permissions().length > 0}>
  <text fg={theme.warning}>
    △ {permissions().length} Permission{permissions().length > 1 ? "s" : ""}
  </text>
</Show>
<text fg={theme.text}>
  <span style={{ fg: lsp().length > 0 ? theme.success : theme.textMuted }}>•</span> {lsp().length} LSP
</text>
<Show when={mcp()}>
  <text fg={theme.text}>
    <Switch>
      <Match when={mcpError()}>
        <span style={{ fg: theme.error }}>⊙ </span>
      </Match>
      <Match when={true}>
        <span style={{ fg: theme.success }}>⊙ </span>
      </Match>
    </Switch>
    {mcp()} MCP
  </text>
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-25

状态指示器对照表

构建与打包

Turborepo 配置

项目使用 turbo.json 进行构建编排：

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

包依赖关系

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 定义完整类型

interface MigrationWizardProps {
  onComplete?: () => void
  currentStep?: Accessor<number>
}

export function MigrationWizard(props: MigrationWizardProps) {
  const language = useI18n()
  
  return (
    <div class="migration-wizard">
      <h1>{language.t("migration.whatsNew.title")}</h1>
    </div>
  )
}

资料来源：packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1-14

创建新 Hook

1. 使用 createSignal：SolidJS 的响应式状态
2. 处理异步操作：使用防抖处理搜索类操作
3. 与 VS Code 通信：通过 vscode.onMessage 监听消息

export function useFileMention(vscode, sessionID, git) {
  const [mentionedPaths, setMentionedPaths] = createSignal<Set<string>>(new Set())
  let fileSearchTimer: ReturnType<typeof setTimeout> | undefined
  
  // 防抖搜索
  createEffect(() => {
    if (fileSearchTimer) clearTimeout(fileSearchTimer)
    fileSearchTimer = setTimeout(() => {
      vscode.postMessage({ type: "fileSearch", ... })
    }, 300)
  })
}

总结

KiloCode 项目采用精心设计的 Monorepo 架构：

• 7 个核心包覆盖 IDE 插件、命令行工具、后端服务等全端场景
• 组件库分层实现代码复用与维护性平衡
• SolidJS 作为前端框架提供高效的响应式编程模型
• Turborepo 统一管理构建流程和依赖关系

这种组织方式使项目能够同时支持 VS Code、JetBrains IDE 和命令行等多个客户端，同时保持代码的模块化和可维护性。

概述

Kilocode 是一个开源的 AI 编程助手平台，采用模块化架构设计，核心功能包括代码生成、自然语言处理、终端命令执行、浏览器自动化和内联自动补全。系统架构基于分层设计原则，将用户界面、业务逻辑、数据处理和外部服务解耦，通过标准化接口实现各层之间的通信。

Kilocode 支持多种客户端形式：命令行界面（CLI）、终端用户界面（TUI）和 Visual Studio Code 扩展。不同客户端共享相同的核心服务层，通过协议适配器实现差异化交互体验。 资料来源：packages/opencode/README.md

概述

KiloCode 的 Agent 核心系统是整个智能编程平台的中枢，负责处理用户请求、调度工具执行、管理会话上下文以及协调大语言模型（LLM）交互。该系统采用模块化架构，将会话管理、消息处理、上下文压缩和工具注册等功能分离，实现了高内聚低耦合的设计目标。

Agent 系统的核心职责包括：接收用户自然语言指令并转化为可执行的任务、通过工具注册表调用各类工具（如文件操作、终端命令、Git 操作等）、维护会话历史和上下文状态、执行上下文压缩以控制 token 消耗、以及支持多种运行模式（Architect、Coder、Debugger 等）。

系统架构

整体架构图

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 主模块

核心类结构

Agent 主模块位于 packages/opencode/src/agent/agent.ts，是整个系统的核心入口点。该模块定义了 Agent 类的基本结构，包括初始化配置、运行循环、错误处理等核心功能。

Agent 类采用事件驱动的设计模式，通过监听器模式处理各类系统事件。初始化时，Agent 会加载配置文件、建立 LLM 连接、注册工具集，并准备会话环境。

模式系统

KiloCode 支持多种运行模式，每种模式针对不同的开发场景进行了优化：

• Architect（架构师模式）：专注于代码设计和架构规划
• Coder（编码模式）：执行具体的代码实现和修改任务
• Debugger（调试模式）：定位和修复代码问题

模式定义存储在 packages/opencode/src/agent/prompt/orchestrator.txt 中，通过角色提示词引导 LLM 产生符合当前模式预期的行为。

生命周期管理

Agent 的生命周期包含以下阶段：

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：会话元数据（创建时间、更新时间等）

父子会话机制

系统支持创建子代理会话，子会话继承父会话的上下文，同时可以独立执行任务。这一机制允许复杂的任务分解和委托场景：

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 系统的核心组件，负责将用户输入转换为系统可执行的操作序列。其处理流程如下：

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: 返回最终响应

消息类型处理

系统支持多种消息类型，每种类型有对应的处理策略：

推理处理

对于支持推理的模型，系统会特殊处理 reasoning 类型消息。在 packages/opencode/src/cli/cmd/tui/routes/session/index.tsx 中定义了 ReasoningPart 组件，用于渲染推理过程。

推理内容中若包含 [REDACTED] 标记（如来自 OpenRouter 的加密推理数据），系统会自动过滤：

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：执行函数

核心工具集

系统内置的核心工具包括：

工具描述增强

对于 glob 和 grep 工具，系统会添加额外的使用提示，帮助 LLM 更准确地使用这些工具：

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" 状态标识：

<Show when={props.message.error?.name === "MessageAbortedError"}>
  <span style={{ fg: theme.textMuted }}> · interrupted</span>
</Show>

资料来源：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 作为备选

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 连接状态：

<Show when={mcp()}>
  <text fg={theme.text}>
    <Switch>
      <Match when={mcpError()}>
        <span style={{ fg: theme.error }}>⊙ </span>
      </Match>
      <Match when={true}>
        <span style={{ fg: theme.success }}>⊙ </span>
      </Match>
    </Switch>
    {mcp()} MCP
  </text>
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:25-37

MCP OAuth 回调

MCP 服务器认证采用 OAuth 2.0 流程，授权成功后会显示确认页面：

<p>You can close this window and return to Kilo.</p>
<script>setTimeout(() => window.close(), 2000);</script>

资料来源：packages/opencode/src/mcp/oauth-callback.ts:28-29

索引与 LSP 集成

索引状态显示

系统支持代码索引功能，在界面底部栏显示当前索引状态：

<Show when={indexingEnabled(sync.data.config)}>
  <text fg={indexingTone(indexing().state, theme)}>
    {indexingText(indexing()).slice(0, 48)}
  </text>
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:38-41

LSP 连接状态

底部栏同时显示 LSP（Language Server Protocol）连接数量：

<text fg={theme.text}>
  <span style={{ fg: lsp().length > 0 ? theme.success : theme.textMuted }}>•</span>
  {lsp().length} LSP
</text>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:20-23

权限管理

权限请求机制

当执行敏感操作时，系统会请求用户授权。权限状态在底部栏显示：

<Show when={permissions().length > 0}>
  <text fg={theme.warning}>
    <span style={{ fg: theme.warning }}>△</span>
    {permissions().length} Permission{permissions().length > 1 ? "s" : ""}
  </text>
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:14-19

文件提及系统

文件自动检测

系统支持自动检测和处理用户输入中的文件引用。在 packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts 中实现了文件提及检测逻辑。

文件提及支持多种类型：

文件搜索防抖

为避免频繁搜索，系统实现了防抖机制：

let fileSearchTimer: ReturnType<typeof setTimeout> | undefined
let fileSearchCounter = 0

搜索结果通过 requestId 关联，确保响应的正确性和顺序性。

扩展性设计

插件插槽系统

系统通过 TuiPluginRuntime.Slot 提供扩展插槽，支持第三方插件注入功能：

<TuiPluginRuntime.Slot
  name="session_prompt"
  mode="replace"
  session_id={route.sessionID}
  visible={visible()}
  disabled={disabled()}
  on_submit={toBottom}
  ref={bind}
>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:198-207

工具注册表扩展

工具注册表支持动态注册新工具，第三方可以通过扩展点添加自定义工具。注册时需要提供完整的工具定义，包括参数模式和执行处理函数。

配置管理

同步配置结构

系统使用 sync 对象管理配置状态，包括：

• sync.path.directory：当前工作目录
• sync.data.config：运行时配置
• sync.data.state：会话状态

状态持久化

会话状态支持持久化存储，包括：

• 消息历史
• 用户偏好设置
• 工具配置
• 上下文摘要

错误处理

错误分类

系统将错误分为以下几类：

网络可见性

系统通过 networkVisible() 和 network() 状态管理网络相关错误的显示：

<Show when={networkVisible()}>
  <NetworkPrompt request={network()[0]} />
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:193-195

性能优化

虚拟文本渲染

对于文件提及等高频更新元素，系统采用虚拟文本渲染优化性能：

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）排序，优先显示常用文件：

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 具有重要意义。

概述

KiloCode 的自动补全系统（Fill-In-The-Middle，简称 FIM）是一个为开发者提供智能代码补全功能的核心模块。该系统通过分析当前编辑上下文，结合语言模型生成高质量的代码建议，帮助开发者提高编码效率。

自动补全系统支持多种文件类型，包括 Python、TypeScript/TSX、Shell 脚本等，并能根据不同语言特性动态调整补全策略。

系统架构

整体架构图

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

核心组件

配置系统

设置验证机制

自动补全系统通过 validAutocompleteSetting 函数验证用户配置，确保只接受有效的设置值：

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

支持的配置项

Fill-In-The-Middle 算法

FIM 工作流程

graph LR
    A[光标位置] --> B[获取前缀上下文]
    B --> C[获取后缀上下文]
    C --> D[构建 FIM Prompt]
    D --> E[调用 LLM]
    E --> F[生成补全代码]
    F --> G[后处理]
    G --> H[返回补全建议]

分语言配置

系统针对不同编程语言提供了特定的配置优化：

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

上下文窗口管理

上下文检索服务

检索策略

上下文检索服务负责从代码库中获取与当前编辑位置相关的代码片段。系统支持以下检索方式：

1. Tree-Sitter 语法树查询：基于代码语法结构进行精确检索
2. 文件路径匹配：基于文件路径和命名模式
3. 语义相似度：基于代码语义内容的相似度匹配

代码片段查询

系统使用 Tree-Sitter 进行代码结构分析，支持以下查询能力：

• 导入语句识别
• 函数和类定义检索
• 类型注解提取
• 注释和文档字符串获取

补全模板系统

模板结构

补全模板定义了如何将上下文信息组织成适合 LLM 处理的格式：

interface AutocompleteTemplate {
  prefix: string        // 光标前内容
  suffix: string        // 光标后内容
  aroundCursor: string  // 光标周围代码块
  metadata: {
    language: string
    filePath: string
    lineNumber: number
  }
}

模板变量

后处理系统

后处理流程

graph TD
    A[LLM 输出] --> B[停止标记检测]
    B --> C[语法验证]
    C --> D{是否有效?}
    D -->|是| E[格式化输出]
    D -->|否| F[降级处理]
    E --> G[返回补全项]
    F --> G

后处理功能

CLI 命令行界面

TUI 自动补全组件

在命令行界面中，自动补全系统通过 autocomplete.tsx 组件提供交互式补全功能：

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 接口，提供内联代码补全功能：

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

补全触发流程

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 提供了在提示中提及和附加文件的功能：

export function useFileMention(
  vscode: VSCodeContext,
  sessionID?: Accessor<string | undefined>,
  git?: Accessor<boolean>,
): FileMention {
  const [mentionedPaths, setMentionedPaths] = createSignal<Set<string>>(new Set())
  const [mentionQuery, setMentionQuery] = createSignal<string | null>(null)
  const [mentionResults, setMentionResults] = createSignal<MentionResult[]>([])
  
  return {
    parseFileAttachments,
    addPaths,
    setMentionIndex,
    closeMention,
  }
}

资料来源：packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:1-50

文件类型支持

Claw 聊天集成

斜杠命令自动补全

在 Claw 聊天界面中，系统支持斜杠命令的自动补全：

const clawSlashes = createMemo<ClawSlashOption[]>(() => {
  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. 节流处理：对频繁触发的事件进行节流

设置变更监听

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 是 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（分区处理器）。这些组件共同构成了一个完整的多代理工作流管理生态系统，每个组件专注于特定的功能域，通过定义良好的接口进行通信和协作。

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 的多代理协作机制是其最具特色的功能之一。当用户启动一个复杂的开发任务时，系统会根据配置自动创建或选择一个合适的代理来处理该任务。代理可以进一步将任务分解为子任务，并分配给其他专门化的代理执行。这种层级式的任务分解和分配机制，使得系统能够处理从简单的代码修复到复杂的系统重构等各种规模的任务。

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 安全架构的核心组成部分。每个代理在创建时都会被分配一组权限定义，这些权限决定了代理可以执行的操作类型和可以访问的资源范围。权限定义采用灵活的规则匹配语法，支持通配符和否定模式，能够精确地控制代理对文件和操作的访问。

从源码中可以看到权限配置的结构示例：

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 格式的命令体。元数据定义命令的元信息，如描述、关联的代理、使用的模型等；命令体包含实际的任务指令，可以使用模板变量引用参数。

命令文件的结构示例：

概述

MCP（Model Context Protocol，模型上下文协议）是 KiloCode 中用于扩展 AI 能力的关键协议层。它允许 KiloCode 与外部工具和服务进行标准化通信，使 AI 能够调用文件系统操作、代码搜索、Shell 命令等能力。KiloCode 的 MCP 集成架构采用了模块化设计，将协议处理、工具注册、认证授权等核心功能解耦，确保系统的可扩展性和可维护性。

架构设计

整体架构

KiloCode 的 MCP 系统采用分层架构，包括协议层、工具层、认证层和 UI 集成层四个主要部分。

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

核心模块关系

工具注册系统

工具注册表架构

工具注册表是 KiloCode MCP 集成的核心组件，负责管理所有可用的工具定义。每个工具都包含唯一标识符、描述信息、执行逻辑和参数模式。注册表支持动态添加和移除工具，使系统能够在运行时扩展功能。

在 packages/opencode/src/kilocode/tool/registry.ts 中，工具注册通过 Tool.Def 类型定义，支持为工具添加额外的元数据标记，如 agent_manager_tool 标志用于标识需要代理管理器参与的工具。

核心工具类型

KiloCode 实现了多种类型的核心工具，覆盖了日常开发中的常见需求。

graph LR
    A[工具请求] --> B{工具类型判断}
    B -->|文件操作| C[Read/Write 工具]
    B -->|Shell| D[Bash 工具]
    B -->|搜索| E[Grep 工具]
    C --> F[文件系统]
    D --> G[系统命令]
    E --> H[代码索引]

工具描述增强

工具注册表提供了 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 服务出现错误时显示警告信息

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. 路径解析：将相对路径转换为绝对路径供后续处理使用

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 统一管理，支持从环境变量和配置文件两个渠道读取配置参数。

认证配置

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）以高亮显示引用

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 服务。

最佳实践

开发新工具

故障排查

常见的 MCP 相关问题及排查方向：

• 工具不可用：检查工具是否在注册表中正确注册
• 搜索无结果：验证 MCP 服务器连接状态
• 认证失败：检查 OAuth 配置和 Token 有效期
• 状态显示异常：查看 TUI 状态栏的错误信息

概述

KiloCode 的代码索引与语义搜索系统是一个多层次的代码理解和检索解决方案，旨在为开发者提供基于代码语义的高效搜索能力。该系统通过集成 Tree-sitter 语法解析、向量嵌入和语义向量存储技术，实现了对代码库的深度索引，使得开发者可以使用自然语言描述来查找相关代码片段。

该系统位于 packages/kilo-indexing 包中，作为 KiloCode 平台的核心基础设施之一，为 IDE 扩展和 CLI 工具提供统一的代码理解能力。

系统架构

核心组件

代码索引与语义搜索系统由以下核心组件构成：

架构流程图

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[返回相关代码片段]

索引管理

索引生命周期

索引管理器负责处理代码库从初始扫描到增量更新的完整生命周期。系统支持增量索引策略，仅对修改过的文件进行重新索引，以优化性能并减少资源消耗。

索引状态在用户界面中实时显示，状态信息包括当前索引进度、已索引文件数量和索引完成百分比。系统会根据索引状态调整配色方案，使用不同色调传达当前索引状态。

// 索引状态显示逻辑示例
<Show when={indexingEnabled(sync.data.config)}>
  <text fg={indexingTone(indexing().state, theme)}>
    {indexingText(indexing()).slice(0, 48)}
  </text>
</Show>

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx

向量存储

系统使用 LanceDB 作为底层向量存储解决方案，这是一种专为机器学习应用设计的高性能嵌入式数据库。向量存储负责持久化代码片段的语义向量表示，并支持高效的相似度搜索查询。

向量存储的数据模型包含以下关键字段：

语法解析

Tree-sitter 集成

Tree-sitter 是 KiloCode 代码索引系统的语法分析引擎，提供了增量解析能力，能够高效处理大型代码库。系统支持多种主流编程语言的语法解析，包括 JavaScript、TypeScript、Python、Go、Rust 等。

语法解析器将源代码转换为抽象语法树（AST），在此基础上进行代码分块和符号提取。分块策略是影响搜索质量的关键因素，系统会根据语言特性采用不同的分块方法，确保每个代码片段具有完整的语义上下文。

语言解析器配置

每种编程语言都有对应的解析器配置文件，定义了语言特定的语法规则和代码块边界识别逻辑。语言解析器还负责提取代码中的关键符号信息，包括函数名、类名、变量名等，这些信息用于增强搜索匹配的准确性。

向量嵌入

OpenAI 嵌入集成

系统使用 OpenAI 的文本嵌入模型将代码片段转换为高维向量。嵌入器负责将原始代码文本转换为固定维度的浮点数向量，这些向量捕捉了代码的语义特征，使得语义相似的代码在向量空间中彼此接近。

嵌入器配置支持以下参数：

向量生成流程

代码片段经过预处理后被发送到 OpenAI API 进行嵌入。预处理步骤包括移除注释、规范化空白字符和添加语言提示信息。语言提示帮助嵌入模型更好地理解代码语义，提高跨语言代码搜索的准确性。

语义搜索

搜索接口

语义搜索通过专门的工具接口暴露给 LLM，LLM 可以调用该工具进行代码搜索。搜索接口接受自然语言查询，返回与查询意图最相关的代码片段及其在代码库中的位置信息。

// 语义搜索工具配置
ToolRegistry.register({
  name: "semantic_search",
  // 搜索工具实现
})

资料来源：packages/opencode/src/tool/semantic-search.ts

搜索结果排序

搜索结果根据向量相似度分数进行排序，系统返回最相关的 Top-N 个代码片段。每个结果包含文件路径、行号范围、代码内容和相似度分数。LLM 可以利用这些信息直接跳转到相关代码位置。

搜索增强策略

系统支持多种搜索增强策略以提高搜索结果质量：

• 符号匹配增强：优先返回包含查询关键词符号的代码片段
• 上下文扩展：返回代码片段时同时提供周围的上下文代码
• 多语言支持：跨语言搜索相关的代码实现
• 过滤机制：支持按文件类型、目录路径等条件过滤搜索结果

配置与调优

索引配置选项

性能优化

系统采用多级缓存策略减少重复计算，索引结果缓存在本地以支持快速重启。向量存储采用分区策略，按编程语言和目录结构进行数据分区，搜索时仅扫描相关分区以提高查询效率。

使用场景

IDE 集成

在 VS Code 扩展中，索引系统为以下功能提供支持：

• 智能代码补全建议
• 语义跳转定义
• 查找引用
• 相关代码推荐

CLI 工具

在 TUI 界面的会话组件中，索引状态实时显示在底部状态栏，用户可以直观地了解当前代码库的索引进度和可用性状态。

技术限制与注意事项

• 向量嵌入依赖外部 API，网络延迟可能影响索引性能
• 大型代码库的初始索引需要较长时间，建议在后台执行
• 部分编程语言的语法解析可能不完全支持最新语言特性

概述

KiloCode 是一个跨平台的 AI 编程助手，通过 IDE 扩展的形式集成到主流开发环境中。目前支持的 IDE 包括 Visual Studio Code 和 JetBrains 系列（如 IntelliJ IDEA、WebStorm 等）。

IDE 扩展的核心职责包括：

• 会话管理：创建和管理与 AI 模型的交互会话
• 编辑器集成：在 IDE 中嵌入 WebView 用户界面
• 文件操作：监听文件变化、处理文件提及和附件
• 工具调用：注册和执行各种开发工具（如终端、Git、浏览器自动化等）
• 命令系统：支持斜杠命令（Slash Commands）和快捷操作

架构设计

整体架构

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 环境中，负责用户界面渲染

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 扩展采用类似的分层设计，但使用不同的技术栈：

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 是扩展的入口文件，负责初始化整个扩展：

// 扩展激活入口
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：

// KiloProvider 核心职责
- 管理会话状态
- 处理消息路由
- 与后端服务通信
- 管理文件搜索和提及

WebView 应用

App.tsx 是前端 WebView 的根组件，负责整体布局和状态协调：

// App.tsx 核心功能
- 提供全局上下文
- 路由管理
- 错误边界
- 迁移向导集成

通信机制

WebView 与扩展后端的通信

KiloCode 使用 postMessage API 实现 WebView 与扩展后端的双向通信：

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 })

消息类型定义

消息通过 vscode.onMessage 回调处理，参考 packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24：

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：

export function useFileMention(
  vscode: VSCodeContext,
  sessionID?: Accessor<string | undefined>,
  git?: Accessor<boolean>,
): FileMention {
  const [mentionedPaths, setMentionedPaths] = createSignal<Set<string>>(new Set())
  const [mentionQuery, setMentionQuery] = createSignal<string | null>(null)
  const [mentionResults, setMentionResults] = createSignal<MentionResult[]>([])
  const [mentionIndex, setMentionIndex] = createSignal(0)
  
  // 文件搜索防抖处理
  let fileSearchTimer: ReturnType<typeof setTimeout> | undefined
  let fileSearchCounter = 0
}

功能特性：

• 实时文件搜索和建议
• 支持 @ 触发文件提及
• 与 Git 状态集成
• 拖拽文件自动注册

斜杠命令系统

useSlashCommand Hook 管理斜杠命令菜单，参考 packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts:1：

// 可用命令列表
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：

// 新版本特性展示
<div class="migration-wizard__features">
  <div class="migration-wizard__feature">
    <BoltIcon />
    <div class="title">{language.t("migration.whatsNew.features.performance.title")}</div>
    <div class="detail">{language.t("migration.whatsNew.features.performance.detail")}</div>
  </div>
  // ... 更多特性
</div>

#### 设备授权卡片

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

// 设备授权步骤
<div class="device-auth-step">
  <p>{language.t("deviceAuth.step1")}</p>
  <div class="device-code">
    {deviceCode}
  </div>
</div>

MCP 市场集成

InstallModal.tsx 组件实现 MCP 服务器的安装界面，参考 packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx:1：

// 前置条件检查
<Show when={prerequisites().length > 0}>
  <ul class="install-modal-prerequisites">
    <For each={prerequisites()}>{(p) => <li>{p}</li>}</For>
  </ul>
</Show>

// 参数输入
<For each={parameters()}>
  {(param) => (
    <TextField
      label={param.name + (param.optional ? ` (${t("marketplace.install.optional")})` : "")}
      placeholder={param.placeholder ?? ""}
      value={params()[param.key] ?? ""}
      onChange={(v: string) => setParam(param.key, v)}
    />
  )}
</For>

文件操作集成

输入提示组件

PromptInput.tsx 处理用户输入和文件提及，参考 packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx:1：

// 文件提及类型渲染
<For each={items()}>
  {(item) => (
    <div class="file-mention-item">
      {item.type === "terminal" ? (
        <>
          <Icon name="console" class="file-mention-icon" />
          <span class="file-mention-name">{item.label}</span>
        </>
      ) : item.type === "git-changes" ? (
        <>
          <Icon name="branch" class="file-mention-icon" />
          <span class="file-mention-name">{item.label}</span>
        </>
      ) : (
        <>
          <FileIcon
            node={{ path: item.value, type: item.type === "folder" ? "directory" : "file" }}
          />
          <span class="file-mention-name">{item.label}</span>
        </>
      )}
    </div>
  )}
</For>

自动补全

autocomplete.tsx 实现 TUI 界面的自动补全功能，参考 packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1：

// 文件部分处理
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 扩展的后端服务：

// 主要职责
class KiloBackendAppService {
    // 会话管理
    // 与 Kilo 后端通信
    // 处理 IDE 事件
}

工具窗口工厂

KiloToolWindowFactory.kt 创建和管理工具窗口：

class KiloToolWindowFactory : ToolWindowFactory {
    override fun createToolWindowContent(project: Project, toolWindow: ToolWindow) {
        // 创建工具窗口内容
        // 初始化通信通道
    }
}

RPC API

KiloSessionRpcApi.kt 定义了会话 RPC 接口：

interface KiloSessionRpcApi {
    // 发送消息
    // 接收响应
    // 管理会话状态
}

配置管理

配置优先级

配置查找顺序（低优先级到高优先级）：

配置采用深度合并策略，后者覆盖前者。资料来源：packages/opencode/src/kilocode/skills/kilo-config.md:1

配置文件结构

# 命令配置示例 (.kilo/command/*.md)

概述

KiloCode 提供了一套完整的命令行工具和软件开发包（SDK），旨在为开发者提供灵活、模块化的代码辅助能力。该系统由以下几个核心部分组成：

CLI 架构设计

命令行入口

CLI 工具采用分层架构设计，主要入口通过 bootstrap.ts 完成初始化，随后根据用户输入分发到不同的命令处理器。

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）模块采用组件化设计，主要结构包括：

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-60

消息渲染系统

会话界面采用 Switch/Match 模式处理不同类型的消息部分：

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 组件显示当前会话的关键状态信息：

资料来源：packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-50

插件系统

插件加载器

KiloCode 采用模块化的插件架构，通过 loader.ts 实现动态插件加载：

graph LR
    A[插件目录] --> B[Loader 扫描]
    B --> C[模块解析]
    C --> D[注册到系统]
    D --> E[运行时调用]

插件接口定义

插件系统提供标准化的接口规范，定义在 packages/plugin/src/index.ts 中：

资料来源：packages/plugin/src/index.ts

SDK 开发

JavaScript SDK

JavaScript SDK 位于 packages/sdk/js/src/index.ts，提供完整的 API 接口用于集成 KiloCode 功能：

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 核心功能

资料来源：packages/sdk/js/src/index.ts

配置系统

配置文件结构

配置管理由 config.ts 统一处理，支持多种配置来源：

资料来源：packages/opencode/src/config/config.ts

关键配置项

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

调试技巧

创建自定义插件

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) => {
        // 处理逻辑
      }
    })
  }
}

技术栈总结

相关资源

• 官方文档：https://kilo.ai/docs/
• 博客公告：https://blog.kilo.ai/
• 问题反馈：https://github.com/Kilo-Org/kilocode/issues

Doramagic 踩坑日志

项目：Kilo-Org/kilocode

暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。

<!-- canonical_name: Kilo-Org/kilocode; human_manual_source: deepwiki_human_wiki -->