{ "canonical_name": "Kilo-Org/kilocode", "compilation_id": "pack_e7f871e3215b48a9b0a89275cdff4b8b", "created_at": "2026-05-16T18:31:01.521541+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install -g @kilocode/cli` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install -g @kilocode/cli", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_244fcd2550d34ffc97ec6be2fa04728e" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_fd961e90014d82febe540e31cdc052e1", "canonical_name": "Kilo-Org/kilocode", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/Kilo-Org/kilocode", "slug": "kilocode", "source_packet_id": "phit_7408e83c902a4973ad191b64f0d58888", "source_validation_id": "dval_79e3d206d9a545f7a411e2c30ee4335c" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 claude的用户", "github_forks": 2539, "github_stars": 19340, "one_liner_en": "Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.", "one_liner_zh": "Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, coding, git" }, "target_user": "使用 claude, chatgpt 等宿主 AI 的用户", "title_en": "kilocode", "title_zh": "kilocode 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Natural-language Web Actions", "label_zh": "自然语言网页操作", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-natural-language-web-actions", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_7408e83c902a4973ad191b64f0d58888", "page_model": { "artifacts": { "artifact_slug": "kilocode", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install -g @kilocode/cli", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/Kilo-Org/kilocode#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 claude的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "claude, chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "暂未发现结构化踩坑项；仍需完成沙箱验证。", "title": "踩坑日志" }, "snapshot": { "contributors": 1040, "forks": 2539, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 19340 }, "source_url": "https://github.com/Kilo-Org/kilocode", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.", "title": "kilocode 能力包", "trial_prompt": "# kilocode - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 kilocode 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Kilo Code 简介与快速入门。围绕“Kilo Code 简介与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. project-structure：项目结构与包组织。围绕“项目结构与包组织”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. agent-system：Agent 核心系统。围绕“Agent 核心系统”模拟一次用户任务，不展示安装或运行结果。\n5. autocomplete-system：自动补全系统 (FIM)。围绕“自动补全系统 (FIM)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Kilo Code 简介与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. project-structure\n输入：用户提供的“项目结构与包组织”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-system\n输入：用户提供的“Agent 核心系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. autocomplete-system\n输入：用户提供的“自动补全系统 (FIM)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Kilo Code 简介与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / project-structure：Step 2 必须围绕“项目结构与包组织”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-system：Step 4 必须围绕“Agent 核心系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / autocomplete-system：Step 5 必须围绕“自动补全系统 (FIM)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Kilo-Org/kilocode\n- https://github.com/Kilo-Org/kilocode#readme\n- .kilo/skills/gh-issues/SKILL.md\n- .kilo/skills/kilocode-merge-minimizer/SKILL.md\n- .kilocode/skills/vscode-visual-regression/SKILL.md\n- .opencode/skills/effect/SKILL.md\n- packages/kilo-jetbrains/.kilo/skills/jetbrains-ui-style/SKILL.md\n- packages/opencode/test/fixture/skills/agents-sdk/SKILL.md\n- packages/opencode/test/fixture/skills/cloudflare/SKILL.md\n- README.md\n- packages/opencode/README.md\n- packages/kilo-vscode/README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 kilocode 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。", "items": [], "status": "待发现 Agent 补证", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.", "effort": "安装已验证", "forks": 2539, "icon": "code", "name": "kilocode 能力包", "risk": "需复核", "slug": "kilocode", "stars": 19340, "tags": [ "浏览器 Agent", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/Kilo-Org/kilocode 项目说明书\n\n生成时间：2026-05-16 18:16:41 UTC\n\n## 目录\n\n- [Kilo Code 简介与快速入门](#introduction)\n- [项目结构与包组织](#project-structure)\n- [系统架构设计](#system-architecture)\n- [Agent 核心系统](#agent-system)\n- [自动补全系统 (FIM)](#autocomplete-system)\n- [Agent Manager 工作流管理](#agent-manager)\n- [MCP 协议与工具集成](#mcp-integration)\n- [代码索引与语义搜索](#indexing-system)\n- [IDE 扩展实现](#ide-extensions)\n- [CLI 工具与 SDK 开发](#cli-and-sdk)\n\n\n\n## Kilo Code 简介与快速入门\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [IDE 扩展实现](#ide-extensions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md)\n- [packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n- [packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md)\n- [packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json)\n- [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)\n- [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)\n- [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)\n
\n\n# Kilo Code 简介与快速入门\n\n## 项目概述\n\nKilo Code 是一个现代化的人工智能辅助编程工具，通过集成多种语言模型和开发工具，为开发者提供智能化的代码编写、理解和编辑体验。该项目采用多平台架构，支持命令行界面（CLI）和 VS Code 扩展两种主要交互方式。\n\nKilo Code 的核心设计理念是将强大的人工智能能力与开发者的日常工作流程无缝结合，提供快速、准确且上下文感知的代码协助。系统支持多种 AI 提供商，包括 OpenAI、Anthropic、Google、Mistral、Moonshot 等主流模型服务。\n\n资料来源：[README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md)\n\n## 系统架构\n\nKilo Code 采用模块化设计，主要由以下核心包组成：\n\n| 包名 | 功能描述 | 技术栈 |\n|------|---------|--------|\n| `packages/opencode` | 命令行工具核心，提供 TUI 界面 | TypeScript/Node.js |\n| `packages/kilo-vscode` | VS Code 扩展，提供图形化界面 | TypeScript/React |\n| `packages/kilo-ui` | UI 组件库 | Solid.js |\n| `packages/ui` | 通用 UI 组件 | Solid.js |\n\n```mermaid\ngraph TD\n A[用户交互层] --> B[CLI TUI 界面]\n A --> C[VS Code 扩展]\n B --> D[opencode 核心引擎]\n C --> E[Webview UI]\n E --> D\n D --> F[AI 模型层]\n F --> G[MCP 服务]\n F --> H[LSP 服务]\n D --> I[文件索引系统]\n G --> J[外部工具集成]\n```\n\n### CLI 架构 (opencode)\n\n命令行工具位于 `packages/opencode` 目录，采用 TUI（文本用户界面）架构。核心模块包括：\n\n- **会话管理** (`routes/session/`): 处理 AI 对话和消息显示\n- **命令系统** (`cmd/`): 实现各种交互命令\n- **提示系统** (`prompt/`): 管理输入和自动完成\n\nCLI 工具支持多种模式切换，包括命令模式、Shell 模式和聊天模式，用户可以通过快捷键在模式间快速切换。\n\n资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n\n### VS Code 扩展架构\n\nVS Code 扩展位于 `packages/kilo-vscode` 目录，分为后端和前端两部分：\n\n- **后端** (`src/`): 处理与核心引擎的通信\n- **前端 Webview** (`webview-ui/`): 使用 Solid.js 构建的图形界面\n\nWebview UI 包含多个核心组件：\n\n- **迁移向导** (`migration/MigrationWizard.tsx`): 引导用户完成版本升级\n- **市场安装** (`marketplace/InstallModal.tsx`): 插件和工具的安装管理\n- **提示输入** (`chat/PromptInput.tsx`): 聊天输入和文件提及功能\n- **文件引用** (`hooks/useFileMention.ts`): 文件拖拽和引用解析\n\n资料来源：[packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md)\n\n## 核心功能\n\n### 智能对话与代码生成\n\nKilo Code 提供完整的对话式编程体验，支持：\n\n- **多轮对话**: 维护对话上下文，支持复杂任务的分解和逐步解决\n- **代码生成**: 根据自然语言描述生成代码片段\n- **代码解释**: 解释现有代码的功能和逻辑\n- **错误修复**: 分析错误信息并提供修复建议\n\n消息系统支持多种内容类型，包括普通文本、工具调用、推理过程（reasoning）和文件变更。\n\n资料来源：[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)\n\n### 文件引用与附件\n\nKilo Code 支持通过 `@` 符号引用文件，实现以下功能：\n\n| 功能 | 说明 | 支持类型 |\n|------|------|----------|\n| 文件提及 | 在对话中引用项目文件 | 文件、文件夹 |\n| 终端引用 | 引用终端输出内容 | 终端 |\n| Git 变更引用 | 引用 Git 变更信息 | 分支、差异 |\n\n文件引用系统会自动搜索匹配的文件路径，并在用户输入时提供自动完成建议。拖拽文件到输入区域也会自动创建引用。\n\n资料来源：[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)\n\n### 工具系统\n\nKilo Code 内置强大的工具系统，支持以下核心工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `Read` | 读取文件内容 |\n| `Write` | 写入或创建文件 |\n| `Edit` | 编辑文件指定区域 |\n| `Grep` | 搜索文件内容 |\n| `TodoWrite` | 创建和管理待办事项 |\n| `ApplyPatch` | 应用代码补丁 |\n\n工具输出支持差异视图（Diff View），清晰展示添加、删除和修改的内容。\n\n资料来源：[packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx)\n\n### MCP 集成\n\nMCP（Model Context Protocol）支持使 Kilo Code 能够与外部工具和服务进行深度集成：\n\n- **OAuth 认证**: 安全处理第三方服务的授权流程\n- **实时状态**: 显示 MCP 连接状态和错误信息\n- **工具调用**: 通过 MCP 协议调用外部工具\n\n状态栏实时显示 MCP 连接状态，绿色圆点表示正常连接，红色圆点表示连接错误。\n\n资料来源：[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)\n\n### LSP 支持\n\nKilo Code 集成 Language Server Protocol，提供：\n\n- 代码补全建议\n- 语法检查和错误提示\n- 跳转到定义\n- 查找引用\n\n状态栏显示当前活动的 LSP 服务器数量。\n\n资料来源：[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)\n\n### 推理过程显示\n\n对于支持推理的模型，Kilo Code 可以显示 AI 的思考过程：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[模型推理]\n B --> C[推理内容]\n B --> D[最终回答]\n C -->|过滤 [REDACTED]| E[显示思考]\n D --> F[工具调用]\n```\n\n推理内容会进行过滤处理，去除 OpenRouter 等服务加密的推理数据（显示为 `[REDACTED]`）。\n\n资料来源：[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)\n\n## 支持的 AI 提供商\n\nKilo Code 支持众多 AI 模型提供商，形成完整的生态系统：\n\n| 提供商 | 代码标识 | 说明 |\n|--------|----------|------|\n| OpenAI | `openai` | GPT 系列模型 |\n| Anthropic | `anthropic` | Claude 系列模型 |\n| Google | `google` | Gemini 系列模型 |\n| Mistral | `mistral` | Mistral AI 模型 |\n| Moonshot | `moonshotai` | Kimi 系列模型 |\n| MiniMax | `minimax` | 混元系列模型 |\n| OpenRouter | `openrouter` | 多模型聚合 |\n| Ollama | `ollama-cloud` | 本地模型 |\n| Groq | `groq` | 高速推理 |\n| TogetherAI | `togetherai` | 开源模型 |\n| HuggingFace | `huggingface` | 推理端点 |\n| LM Studio | `lmstudio` | 本地部署 |\n\n资料来源：[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)\n\n## 快速入门\n\n### 安装方式\n\n#### VS Code 扩展安装\n\n1. 打开 VS Code\n2. 进入扩展市场，搜索 \"Kilo\"\n3. 点击安装按钮\n4. 安装完成后，点击侧边栏的 Kilo 图标开始使用\n\n扩展版本信息可在 `package.json` 中查看：\n\n```json\n{\n \"name\": \"kilo-vscode\",\n \"version\": \"1.x.x\",\n \"displayName\": \"Kilo\"\n}\n```\n\n资料来源：[packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json)\n\n#### CLI 安装\n\n```bash\n# 使用 npm 安装\nnpm install -g @kilocode/opencode\n\n# 或使用其他包管理器\nbrew install kilo-ai/tap/kilocode\n```\n\n### 首次配置\n\n首次启动后，系统会显示迁移向导，引导用户了解新版本特性：\n\n1. **性能优化**: 了解新版本的性能改进\n2. **界面更新**: 查看新的用户界面设计\n3. **Agent 管理器**: 了解增强的多 Agent 支持\n4. **基础架构**: 查看底层技术升级\n\n资料来源：[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)\n\n### 基本使用\n\n#### CLI 模式\n\n```bash\n# 启动交互式会话\nopencode\n\n# 指定模型\nopencode --model gpt-4\n\n# 查看帮助\nopencode --help\n```\n\n#### VS Code 扩展模式\n\n1. 打开命令面板 (`Ctrl+Shift+P` / `Cmd+Shift+P`)\n2. 输入 \"Kilo\" 查找相关命令\n3. 选择 \"Kilo: 新建对话\" 开始会话\n4. 在输入框中输入问题或指令\n\n### 文件操作\n\n#### 在对话中引用文件\n\n```\n@filename.py # 引用单个文件\n@src/ # 引用整个目录\n@README.md:10-20 # 引用文件特定行\n```\n\n#### 拖拽添加\n\n直接将文件从资源管理器拖拽到聊天输入区域，系统会自动创建文件引用。\n\n### 快捷键\n\n| 操作 | Windows/Linux | macOS |\n|------|---------------|-------|\n| 新建对话 | `Ctrl+Shift+K` | `Cmd+Shift+K` |\n| 打开命令列表 | `Ctrl+/` | `Cmd+/` |\n| 引用文件 | `@` | `@` |\n| 斜杠命令 | `/` | `/` |\n\n资料来源：[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)\n\n## 认证与授权\n\n### OAuth 回调处理\n\nKilo Code 使用 OAuth 2.0 进行第三方服务认证：\n\n```mermaid\nsequenceDiagram\n 用户->>Kilo Code: 请求授权\n Kilo Code->>第三方服务: 发起 OAuth 请求\n 第三方服务-->>用户: 显示授权页面\n 用户->>第三方服务: 确认授权\n 第三方服务->>Kilo Code: 回调并返回 code\n Kilo Code->>第三方服务: 交换 access token\n 第三方服务-->>Kilo Code: 返回 token\n Kilo Code-->>用户: 授权成功\n```\n\n授权成功后，页面会自动关闭并将控制权交还给 Kilo Code。\n\n资料来源：[packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts)\n\n## 状态与监控\n\n### 状态栏指示器\n\nCLI 和 VS Code 扩展都在状态栏显示关键信息：\n\n| 指示器 | 状态 | 含义 |\n|--------|------|------|\n| LSP | • (绿色) | 已连接 LSP 服务器 |\n| LSP | • (灰色) | 无 LSP 服务器 |\n| MCP | ⊙ (绿色) | MCP 已连接 |\n| MCP | ⊙ (红色) | MCP 连接错误 |\n| Indexing | 文本 | 索引状态 |\n\n### 权限提示\n\n当操作需要额外权限时，状态栏会显示警告信息：\n\n```\n△ 3 Permissions\n```\n\n资料来源：[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)\n\n## 常见问题\n\n### Q: 如何切换 AI 模型？\n\n在设置中选择 \"Provider\" 并配置新的模型提供商，然后在对话中通过 `/model` 命令或设置默认模型进行切换。\n\n### Q: MCP 连接失败怎么办？\n\n1. 检查 MCP 服务是否正常运行\n2. 验证 OAuth 授权是否过期\n3. 查看状态栏的 MCP 错误指示器\n4. 重启 Kilo Code 尝试重新连接\n\n### Q: 如何禁用推理过程显示？\n\n在设置中关闭 \"Show Thinking\" 选项，推理内容将不会在界面中显示。\n\n### Q: 支持本地模型吗？\n\n是的，Kilo Code 支持 Ollama、LM Studio 等本地模型服务。配置相应的提供商地址即可使用。\n\n## 下一步\n\n- 查看[官方文档](https://kilo.ai/docs/)获取完整使用指南\n- 访问[博客](https://blog.kilo.ai/)了解最新更新\n- 参与 [GitHub 讨论](https://github.com/Kilo-Org/kilocode/discussions)提出问题和建议\n- 报告 [Issue](https://github.com/Kilo-Org/kilocode/issues) 帮助改进产品\n\n---\n\n\n\n## 项目结构与包组织\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx)\n- [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)\n- [packages/ui/src/components/file-icon.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/ui/src/components/file-icon.tsx)\n- [packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts)\n
\n\n# 项目结构与包组织\n\n## 概述\n\nKiloCode 是一个模块化的 AI 代码辅助平台，采用 Monorepo 架构组织代码。项目使用 `turbo.json` 作为构建编排工具，将功能划分为多个独立的包（packages），每个包专注于特定的功能领域。\n\nKiloCode 的包组织结构遵循以下核心原则：\n\n- **模块独立性**：每个包拥有独立的功能边界，可独立测试和部署\n- **代码共享**：通过 `@kilo` 前缀的共享包实现跨包复用\n- **多端适配**：支持 VS Code、JetBrains IDE、命令行界面等多种客户端\n\n## 核心包结构\n\n### 包架构总览\n\n```mermaid\ngraph TD\n subgraph \"核心共享包\"\n UI[kilo-ui
UI 组件库]\n UIShared[ui
通用 UI 工具]\n end\n \n subgraph \"平台包\"\n VSCODE[kilo-vscode
VS Code 扩展]\n JETBRAINS[kilo-jetbrains
JetBrains 插件]\n OPENCODE[opencode
命令行工具]\n end\n \n subgraph \"后端服务\"\n GATEWAY[kilo-gateway
API 网关]\n INDEXING[kilo-indexing
代码索引服务]\n end\n \n UI --> VSCODE\n UI --> JETBRAINS\n UIShared --> UI\n GATEWAY --> INDEXING\n \n style UI fill:#e1f5fe\n style VSCODE fill:#fff3e0\n style OPENCODE fill:#f3e5f5\n```\n\n### 包功能对照表\n\n| 包名称 | 路径 | 功能描述 | 依赖技术 |\n|--------|------|----------|----------|\n| `kilo-vscode` | `packages/kilo-vscode/` | VS Code 扩展后端与 Webview UI | TypeScript, VS Code API |\n| `kilo-jetbrains` | `packages/kilo-jetbrains/` | JetBrains IDE 插件 | Kotlin, IntelliJ Platform |\n| `opencode` | `packages/opencode/` | 跨平台命令行界面 | TypeScript, React-like TUI |\n| `kilo-gateway` | `packages/kilo-gateway/` | 后端 API 网关服务 | TypeScript/Node.js |\n| `kilo-indexing` | `packages/kilo-indexing/` | 代码语义索引与搜索 | TypeScript |\n| `kilo-ui` | `packages/kilo-ui/` | React 组件库 | React, TypeScript |\n| `ui` | `packages/ui/` | 基础 UI 组件与图标 | React, TypeScript |\n\n## 目录结构规范\n\n### 标准包结构\n\n```\npackages//\n├── src/ # 源代码目录\n│ ├── index.ts # 包入口文件\n│ ├── components/ # 组件目录\n│ ├── hooks/ # 自定义 Hooks\n│ └── utils/ # 工具函数\n├── package.json # 包配置\n└── tsconfig.json # TypeScript 配置\n```\n\n### Webview UI 特殊结构\n\n`kilo-vscode` 包的 webview-ui 采用前后端分离的结构：\n\n```\nkilo-vscode/\n├── src/ # VS Code 扩展后端\n│ └── extension.ts # 扩展入口\n└── webview-ui/ # Webview 前端\n ├── src/\n │ ├── components/ # React 组件\n │ ├── hooks/ # 业务 Hooks\n │ └── App.tsx # 应用根组件\n └── package.json\n```\n\n## 组件组织模式\n\n### 组件目录结构\n\n组件按照功能模块组织在 `components/` 目录下，采用功能域划分：\n\n```\ncomponents/\n├── migration/ # 迁移向导模块\n│ └── MigrationWizard.tsx\n├── chat/ # 聊天界面模块\n│ └── PromptInput.tsx\n├── marketplace/ # 市场功能模块\n│ └── InstallModal.tsx\n└── [其他功能模块]/\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1]()\n\n### 组件分层架构\n\n```mermaid\ngraph LR\n A[业务组件
MigrationWizard] --> B[功能组件
PromptInput]\n B --> C[基础组件
FileIcon]\n C --> D[UI 原子
Button, TextField]\n \n style A fill:#ffcdd2\n style B fill:#fff9c4\n style C fill:#c8e6c9\n style D fill:#bbdefb\n```\n\n## Hooks 与状态管理\n\n### 自定义 Hooks 模式\n\n`useFileMention` 是典型的自定义 Hook，用于处理文件提及功能：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n // 文件搜索状态\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n const [mentionIndex, setMentionIndex] = createSignal(0)\n \n // 搜索防抖\n let fileSearchTimer: ReturnType | undefined\n let fileSearchCounter = 0\n \n // ...\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24-38]()\n\n### Hook 职责表\n\n| Hook 名称 | 文件位置 | 职责 | 状态类型 |\n|-----------|----------|------|----------|\n| `useFileMention` | `hooks/useFileMention.ts` | 文件路径提及与搜索 | `Set`, `MentionResult[]` |\n| `useTheme` | 主题相关模块 | 主题配置与颜色 | `Theme` 对象 |\n\n## 文件图标系统\n\n### 图标映射机制\n\n文件图标系统通过文件名和扩展名映射到对应的图标：\n\n```typescript\nconst ICON_MAPS: IconMaps = {\n fileNames: {\n // 文档文件\n \"readme.md\": \"Readme\",\n \"changelog.md\": \"Changelog\",\n \"package.json\": \"Nodejs\",\n \n // Docker 文件\n dockerfile: \"Docker\",\n \"docker-compose.yml\": \"Docker\",\n \n // 配置文件\n \"jest.config.js\": \"Jest\",\n },\n fileExtensions: {\n \".ts\": \"Typescript\",\n \".tsx\": \"Typescript\",\n \".json\": \"JSON\",\n },\n folderNames: { /* ... */ },\n defaults: {\n file: \"File\",\n folder: \"Folder\",\n folderOpen: \"FolderOpen\",\n }\n}\n```\n\n资料来源：[packages/ui/src/components/file-icon.tsx:22-48]()\n\n### 支持的文件类型\n\n| 类别 | 文件名/扩展名 | 图标名称 |\n|------|---------------|----------|\n| 文档 | `readme.md`, `changelog.md`, `contributing.md` | Readme, Changelog |\n| Node.js | `package.json`, `package-lock.json`, `yarn.lock` | Nodejs, Yarn |\n| Docker | `dockerfile`, `docker-compose.yml` | Docker |\n| 包管理 | `pnpm-lock.yaml`, `bun.lock` | Pnpm, Bun |\n| 测试 | `jest.config.js`, `jest.config.ts` | Jest |\n\n## TUI 组件架构\n\n命令行工具采用 React-like 的 TUI 组件体系：\n\n```mermaid\ngraph TD\n subgraph \"TUI 路由层\"\n SESSION[index.tsx
会话路由]\n FOOTER[footer.tsx
状态栏]\n PERMISSION[permission.tsx
权限管理]\n end\n \n subgraph \"TUI 组件层\"\n PROMPT[prompt/index.tsx
输入组件]\n AUTOCOMPLETE[autocomplete.tsx
自动完成]\n DIALOG[dialog-export-options.tsx
对话框]\n end\n \n subgraph \"TUI 基础层\"\n THEMES[主题系统]\n LAYOUT[布局组件]\n end\n \n SESSION --> FOOTER\n SESSION --> PROMPT\n PROMPT --> AUTOCOMPLETE\n FOOTER --> DIALOG\n \n style SESSION fill:#e3f2fd\n style PROMPT fill:#f3e5f5\n```\n\n### 会话组件结构\n\n`session/index.tsx` 定义了消息渲染的核心逻辑：\n\n```typescript\nconst PART_MAPPING = {\n text: TextPart,\n tool: ToolPart,\n reasoning: ReasoningPart,\n}\n\nfunction ReasoningPart(props: { last: boolean; part: ReasoningPart; message: AssistantMessage }) {\n // 过滤 OpenRouter 的加密推理数据\n const content = createMemo(() => {\n return props.part.text.replace(\"[REDACTED]\", \"\").trim()\n })\n // ...\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-16]()\n\n### 工具注册机制\n\n工具通过 `ToolRegistry` 进行注册和渲染：\n\n```typescript\nToolRegistry.register({\n name: \"todowrite\",\n render(props) {\n const view = createMemo(() => \n isTodoView(props.metadata?.view) ? props.metadata.view : undefined\n )\n const todos = createMemo(() => {\n const meta = props.metadata\n // 处理待办事项元数据\n })\n // ...\n },\n})\n```\n\n资料来源：[packages/kilo-ui/src/components/message-part.tsx:1-30]()\n\n## OAuth 与认证\n\n### 回调处理流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as 提供商\n participant K as KiloCode\n participant C as 客户端应用\n \n U->>P: 授权请求\n P->>K: OAuth 回调\n K->>K: 处理授权码\n K-->>U: 显示成功页面\n U->>C: 自动关闭窗口\n```\n\nOAuth 回调页面支持多语言显示：\n\n```typescript\nconst HTML_SUCCESS = `\n\n\n Kilo - Authorization Successful\n \n

You can close this window and return to Kilo.

\n \n\n\n

Authorization Successful

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

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

\n
\n )\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1-14]()\n\n### 创建新 Hook\n\n1. **使用 `createSignal`**：SolidJS 的响应式状态\n2. **处理异步操作**：使用防抖处理搜索类操作\n3. **与 VS Code 通信**：通过 `vscode.onMessage` 监听消息\n\n```typescript\nexport function useFileMention(vscode, sessionID, git) {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n let fileSearchTimer: ReturnType | undefined\n \n // 防抖搜索\n createEffect(() => {\n if (fileSearchTimer) clearTimeout(fileSearchTimer)\n fileSearchTimer = setTimeout(() => {\n vscode.postMessage({ type: \"fileSearch\", ... })\n }, 300)\n })\n}\n```\n\n## 总结\n\nKiloCode 项目采用精心设计的 Monorepo 架构：\n\n- **7 个核心包**覆盖 IDE 插件、命令行工具、后端服务等全端场景\n- **组件库分层**实现代码复用与维护性平衡\n- **SolidJS** 作为前端框架提供高效的响应式编程模型\n- **Turborepo** 统一管理构建流程和依赖关系\n\n这种组织方式使项目能够同时支持 VS Code、JetBrains IDE 和命令行等多个客户端，同时保持代码的模块化和可维护性。\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目结构与包组织](#project-structure), [Agent 核心系统](#agent-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/server/server.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/server.ts)\n- [packages/opencode/src/server/adapter.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/adapter.ts)\n- [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)\n- [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts)\n- [packages/opencode/src/provider/provider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/provider/provider.ts)\n- [packages/opencode/src/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/registry.ts)\n- [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)\n
\n\n# 系统架构设计\n\n## 概述\n\nKilocode 是一个开源的 AI 编程助手平台，采用模块化架构设计，核心功能包括代码生成、自然语言处理、终端命令执行、浏览器自动化和内联自动补全。系统架构基于分层设计原则，将用户界面、业务逻辑、数据处理和外部服务解耦，通过标准化接口实现各层之间的通信。\n\nKilocode 支持多种客户端形式：命令行界面（CLI）、终端用户界面（TUI）和 Visual Studio Code 扩展。不同客户端共享相同的核心服务层，通过协议适配器实现差异化交互体验。 资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n\n---\n\n## 整体架构分层\n\nKilocode 采用经典的三层/四层架构设计，从上到下依次为：展示层、服务层、核心业务层和数据层。展示层负责用户交互，服务层处理协议转换和请求路由，核心业务层实现 AI 推理和工具调用，数据层管理会话状态和配置存储。\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 展示层 (UI Layer) │\n│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │\n│ │ CLI │ │ TUI │ │ VS Code Extension │ │\n│ │ │ │ │ │ (Webview + Backend) │ │\n│ └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │\n└───────┼─────────────┼───────────────────┼───────────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ 服务层 (Service Layer) │\n│ ┌──────────────────────────────────────────────────┐ │\n│ │ 协议适配器 (Protocol Adapter) │ │\n│ │ CLI适配器 │ TUI适配器 │ VSCode消息通道适配器 │ │\n│ └──────────────────────────────────────────────────┘ │\n│ ┌──────────────────────────────────────────────────┐ │\n│ │ HTTP API 网关 │ │\n│ │ /instance/* 路由 · 会话管理端点 │ │\n│ └──────────────────────────────────────────────────┘ │\n└──────────────────────────┬──────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 核心业务层 (Core Business Layer) │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 会话管理 │ │ 工具注册 │ │ 提供者系统 │ │\n│ │ (Session) │ │ (Registry) │ │ (Provider) │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 提示工程 │ │ 工具执行 │ │ 状态管理 │ │\n│ │ (Prompt) │ │ (Executor) │ │ (State Mgmt) │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n└──────────────────────────┬──────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 数据层 (Data Layer) │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 会话存储 │ │ 配置存储 │ │ 模型接口 │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 核心组件架构\n\n### 服务层组件\n\n#### HTTP API 服务器\n\nHTTP API 服务器是 Kilocode 的核心通信枢纽，提供 RESTful 接口供外部客户端调用。服务器实现位于 `packages/opencode/src/server/routes/instance/httpapi/server.ts`，负责处理会话管理、工具调用和状态查询等核心功能。\n\n服务器路由设计遵循统一资源定位原则，所有实例级接口统一挂载在 `/instance` 路径下：\n\n| 路由前缀 | 功能说明 | 请求方法 |\n|---------|---------|----------|\n| `/instance/sessions` | 会话列表与创建 | GET/POST |\n| `/instance/sessions/:id` | 单一会话操作 | GET/DELETE |\n| `/instance/execute` | 远程命令执行 | POST |\n| `/instance/status` | 服务状态查询 | GET |\n\n#### 协议适配器\n\n协议适配器（Adapter）位于 `packages/opencode/src/server/adapter.ts`，负责将不同客户端的通信协议转换为统一的内部消息格式。这种设计使得 CLI、TUI 和 VSCode 扩展可以使用各自的原生协议进行通信，同时核心业务逻辑保持一致。\n\n适配器实现了消息解析、路由分发和响应格式化三个核心功能。当客户端发送请求时，适配器首先解析消息内容，根据消息类型和目标端点将请求路由到对应的处理函数，最后将处理结果格式化为客户端可识别的响应格式。\n\n#### VSCode 连接服务\n\nVSCode 扩展与后端 CLI 之间的通信通过 `packages/kilo-vscode/src/services/cli-backend/connection-service.ts` 实现的连接服务完成。该服务利用 VSCode 原生的 `postMessage` API 建立双向通信通道，支持文件搜索、会话管理和模型查询等操作。\n\n```\n┌─────────────────┐ postMessage ┌─────────────────┐\n│ VSCode Webview │ ──────────────────▶│ CLI Backend │\n│ (Frontend) │ │ (Server) │\n│ │ ◀─────────────────│ │\n│ │ handleMessage │ │\n└─────────────────┘ └─────────────────┘\n```\n\n连接服务定义了标准化的消息格式，消息对象包含 `type` 字段标识消息类型，可选的 `requestId` 用于请求-响应匹配：\n\n```typescript\ninterface VSCodeMessage {\n type: \"fileSearchResult\" | \"sessionList\" | \"sessionCreate\" | \"sessionDelete\" | \"modelList\" | \"error\";\n requestId?: string;\n items?: SearchItem[];\n paths?: string[];\n sessions?: SessionInfo[];\n models?: ModelInfo[];\n error?: string;\n}\n```\n\n---\n\n### 核心业务层组件\n\n#### 会话管理\n\n会话（Session）是 Kilocode 处理用户对话的核心抽象，定义于 `packages/opencode/src/session/session.ts`。每个会话拥有唯一的会话标识符（Session ID），用于追踪对话上下文、管理文件引用和代理状态。\n\n会话模块负责维护对话历史、解析和存储文件提及（File Mentions）、处理工具调用结果以及管理对话状态转换。TUI 界面中的会话组件根据消息模式（mode）展示不同类型的对话内容，包括文本回复、工具调用和推理过程。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[会话初始化]\n B --> C{消息类型}\n C -->|文本| D[AI推理引擎]\n C -->|文件引用| E[文件解析服务]\n C -->|工具调用| F[工具注册表]\n D --> G[响应生成]\n E --> G\n F --> H[工具执行]\n H --> G\n G --> I[会话状态更新]\n I --> J[UI渲染]\n```\n\n#### 提供者系统\n\n提供者（Provider）系统位于 `packages/opencode/src/provider/provider.ts`，是 Kilocode 与外部 AI 模型交互的抽象层。提供者系统标准化了与不同 AI 厂商（如 OpenAI、Anthropic、Google 等）的接口，屏蔽了底层 API 差异。\n\n每个提供者实现以下核心接口：\n\n| 接口方法 | 功能说明 | 返回类型 |\n|---------|---------|----------|\n| `chat()` | 发送对话请求 | `AsyncIterator` |\n| `models()` | 列出可用模型 | `Model[]` |\n| `authenticate()` | 身份验证 | `Promise` |\n| `health()` | 健康检查 | `Promise` |\n\n提供者系统支持模型选择、参数配置和密钥管理，允许用户在 `kilo.json` 配置文件中指定使用的模型和提供者的凭据信息。\n\n#### 工具注册表\n\n工具注册表（Tool Registry）定义于 `packages/opencode/src/tool/registry.ts`，是 Kilocode 扩展其能力的基础架构。工具注册表采用插件式设计，允许动态注册新的工具功能，系统启动时自动扫描并加载所有已注册的工具。\n\n注册表核心数据结构包括：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `name` | `string` | 工具唯一标识名 |\n| `description` | `string` | 工具功能描述 |\n| `parameters` | `Schema` | 参数定义 |\n| `handler` | `Function` | 执行函数 |\n\n已注册的工具通过标准化的调用接口暴露给 AI 模型，模型可以根据对话上下文选择合适的工具执行任务。TUI 界面中的工具部分渲染器（ToolPart）负责将工具调用结果以格式化方式展示给用户。\n\n---\n\n## 消息处理流程\n\n### TUI 消息渲染流程\n\nTUI 界面中的消息渲染采用组件化设计，不同类型的消息部分（Part）由对应的渲染器处理：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as TUI界面\n participant Session as 会话模块\n participant AI as AI模型\n participant Registry as 工具注册表\n\n User->>TUI: 发送消息\n TUI->>Session: 创建用户消息\n Session->>AI: 发送对话请求\n AI->>AI: 生成回复\n AI-->>Session: 返回响应流\n Session-->>TUI: 分发消息片段\n \n alt 文本消息\n TUI->>TUI: TextPart渲染器\n else 工具调用\n TUI->>Registry: 查询工具信息\n Registry-->>TUI: 工具元数据\n TUI->>TUI: ToolPart渲染器\n else 推理过程\n TUI->>TUI: ReasoningPart渲染器\n Note over TUI: 过滤[REDACTED]标记\n end\n \n TUI-->>User: 展示消息内容\n```\n\n推理消息（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)\n\n### 文件提及处理流程\n\n文件提及（File Mention）是 Kilocode 的核心交互特性，允许用户在对话中通过 `@` 符号引用文件。处理流程如下：\n\n```mermaid\ngraph LR\n A[用户输入] --> B{检测@符号}\n B -->|是| C[触发提及查询]\n C --> D[搜索文件]\n D --> E[显示建议列表]\n E --> F[用户选择]\n F --> G[解析文件信息]\n G --> H[创建FilePart]\n H --> I[更新extmark]\n I --> J[渲染文件引用]\n```\n\n文件提及功能由 `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)\n\n---\n\n## 数据流与状态管理\n\n### 会话数据流\n\n会话模块管理整个对话的生命周期，数据流向遵循以下模式：\n\n1. **输入阶段**：用户输入通过客户端界面捕获，转换为标准消息格式\n2. **处理阶段**：消息经过解析、验证和上下文增强后发送给 AI 模型\n3. **推理阶段**：AI 模型生成回复，系统根据回复类型分发到不同处理器\n4. **输出阶段**：处理后的内容更新会话状态，UI 层订阅状态变化进行渲染\n\n### 状态同步机制\n\nVSCode 扩展中，前端 Webview 与后端 CLI 通过消息通道保持状态同步。连接服务维护一个消息计数器 `fileSearchCounter` 用于追踪文件搜索请求，确保响应与请求正确匹配：\n\n```typescript\nlet fileSearchCounter = 0\n\n// 发送请求时递增\nconst requestId = `file-search-${fileSearchCounter++}`\n\n// 接收响应时验证\nif (message.requestId === `file-search-${fileSearchCounter}`) {\n // 处理结果\n}\n```\n\n---\n\n## 配置系统\n\nKilocode 的配置系统支持多层级合并，优先级从低到高依次为：远程默认配置、全局配置（`~/.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)\n\n配置查找路径支持以下目录：\n\n| 目录路径 | 说明 |\n|---------|------|\n| `~/.config/kilo/` | 全局配置根目录 |\n| `./.kilo/` | 项目本地配置 |\n| `./.kilocode/` | 项目本地配置（兼容旧版本） |\n| `./.opencode/` | 项目本地配置（兼容旧版本） |\n\n命令文件存储在配置的 `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)\n\n---\n\n## 工具与代理集成\n\n### 工具注册机制\n\n工具注册表支持插件化扩展，每个工具需要提供名称、描述、参数模式和执行函数。系统启动时，注册表扫描预定义路径下的工具模块，自动完成工具的注册和初始化。\n\n### 代理管理\n\n代理（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)\n\n---\n\n## 安全考虑\n\n### 敏感信息处理\n\n导出功能中实现了敏感信息过滤机制，系统自动识别并脱敏文件路径、符号名称、URI 和客户端名称等敏感数据：\n\n```typescript\nfunction source(part: MessageV2.FilePart) {\n if (!part.source) return part.source\n if (part.source.type === \"symbol\") {\n return {\n ...part.source,\n path: redact(\"file-path\", part.id, part.source.path),\n name: redact(\"file-symbol\", part.id, part.source.name),\n }\n }\n // ...\n}\n```\n\n### 会话隔离\n\n每个会话拥有独立的上下文空间，会话间的数据和状态完全隔离，确保多用户或多任务场景下的数据安全。\n\n---\n\n## 扩展点与插件化\n\nKilocode 架构设计预留了多个扩展点，支持第三方功能集成：\n\n| 扩展点 | 说明 | 接入方式 |\n|-------|------|----------|\n| 工具注册 | 自定义工具功能 | 实现 ToolRegistry 接口 |\n| 提供者 | 自定义 AI 模型 | 实现 Provider 接口 |\n| 命令 | 自定义 CLI 命令 | 添加 `.kilo/command/*.md` 文件 |\n| MCP 服务器 | 扩展系统能力 | 通过 `kilo mcp` 命令管理 |\n\n---\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 展示层 | React + TypeScript（VSCode扩展）、SolidJS（kilo-ui） |\n| 服务层 | Node.js HTTP 服务器、WebSocket（可选） |\n| 核心业务 | TypeScript 原生实现 |\n| 数据层 | 文件系统存储、会话序列化 |\n| 通信协议 | JSON over postMessage、REST API |\n\n---\n\n## 总结\n\nKilocode 的系统架构遵循模块化、可扩展和松耦合的设计原则。通过分层架构和协议适配器，系统支持多种客户端形式，同时保持核心业务逻辑的统一。会话管理、工具注册表和提供者系统构成了核心业务层的主要组件，HTTP API 网关和消息通道服务则负责对外通信。这种架构设计使得 Kilocode 能够灵活适应不同的使用场景，同时为第三方扩展预留了充足的接口。\n\n---\n\n\n\n## Agent 核心系统\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [自动补全系统 (FIM)](#autocomplete-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/agent/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/agent.ts)\n- [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts)\n- [packages/opencode/src/session/prompt.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/prompt.ts)\n- [packages/opencode/src/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/processor.ts)\n- [packages/opencode/src/session/llm.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/llm.ts)\n- [packages/opencode/src/session/compaction.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/compaction.ts)\n- [packages/opencode/src/agent/prompt/orchestrator.txt](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/prompt/orchestrator.txt)\n- [packages/opencode/src/kilocode/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/session/processor.ts)\n
\n\n# Agent 核心系统\n\n## 概述\n\nKiloCode 的 Agent 核心系统是整个智能编程平台的中枢，负责处理用户请求、调度工具执行、管理会话上下文以及协调大语言模型（LLM）交互。该系统采用模块化架构，将会话管理、消息处理、上下文压缩和工具注册等功能分离，实现了高内聚低耦合的设计目标。\n\nAgent 系统的核心职责包括：接收用户自然语言指令并转化为可执行的任务、通过工具注册表调用各类工具（如文件操作、终端命令、Git 操作等）、维护会话历史和上下文状态、执行上下文压缩以控制 token 消耗、以及支持多种运行模式（Architect、Coder、Debugger 等）。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n User[用户输入] --> Session[会话管理模块]\n Session --> Processor[消息处理器]\n Processor --> LLM[LLM 交互层]\n LLM --> Response[响应生成]\n Response --> ToolRegistry[工具注册表]\n ToolRegistry --> Tools[工具执行]\n Tools --> Processor\n Session --> Compaction[上下文压缩]\n Compaction --> Context[上下文管理]\n Context --> LLM\n Session --> Prompt[提示词管理]\n Prompt --> LLM\n```\n\n### 核心模块职责\n\n| 模块名称 | 文件路径 | 主要职责 |\n|---------|---------|---------|\n| Agent 主模块 | `packages/opencode/src/agent/agent.ts` | 核心代理逻辑、模式调度、生命周期管理 |\n| 会话管理 | `packages/opencode/src/session/session.ts` | 会话状态维护、父子会话关系、多会话支持 |\n| 消息处理 | `packages/opencode/src/session/processor.ts` | 消息解析、工具调用分发、响应格式化 |\n| LLM 交互 | `packages/opencode/src/session/llm.ts` | 模型调用、流式响应、推理处理 |\n| 上下文压缩 | `packages/opencode/src/session/compaction.ts` | 历史消息压缩、token 优化 |\n| 提示词管理 | `packages/opencode/src/agent/prompt/orchestrator.txt` | 角色定义、指令模板管理 |\n\n## Agent 主模块\n\n### 核心类结构\n\nAgent 主模块位于 `packages/opencode/src/agent/agent.ts`，是整个系统的核心入口点。该模块定义了 Agent 类的基本结构，包括初始化配置、运行循环、错误处理等核心功能。\n\nAgent 类采用事件驱动的设计模式，通过监听器模式处理各类系统事件。初始化时，Agent 会加载配置文件、建立 LLM 连接、注册工具集，并准备会话环境。\n\n### 模式系统\n\nKiloCode 支持多种运行模式，每种模式针对不同的开发场景进行了优化：\n\n- **Architect（架构师模式）**：专注于代码设计和架构规划\n- **Coder（编码模式）**：执行具体的代码实现和修改任务\n- **Debugger（调试模式）**：定位和修复代码问题\n\n模式定义存储在 `packages/opencode/src/agent/prompt/orchestrator.txt` 中，通过角色提示词引导 LLM 产生符合当前模式预期的行为。\n\n### 生命周期管理\n\nAgent 的生命周期包含以下阶段：\n\n```mermaid\nstateDiagram-v2\n [*] --> Init: 初始化\n Init --> Ready: 配置加载完成\n Ready --> Running: 接收用户请求\n Running --> Ready: 请求处理完成\n Running --> Error: 发生错误\n Error --> Ready: 错误恢复\n Ready --> [*]: 会话结束\n```\n\n1. **初始化阶段**：加载配置、初始化 LLM 连接、注册工具\n2. **就绪阶段**：等待用户输入\n3. **运行阶段**：处理请求、执行工具、生成响应\n4. **错误处理**：捕获异常、尝试恢复或终止\n\n## 会话管理系统\n\n### 会话数据结构\n\n会话管理模块位于 `packages/opencode/src/session/session.ts`，负责维护会话的完整生命周期。每个会话包含以下关键属性：\n\n- **sessionID**：会话唯一标识符\n- **parentID**：父会话 ID（用于子代理场景）\n- **mode**：当前运行模式\n- **messages**：消息历史列表\n- **metadata**：会话元数据（创建时间、更新时间等）\n\n### 父子会话机制\n\n系统支持创建子代理会话，子会话继承父会话的上下文，同时可以独立执行任务。这一机制允许复杂的任务分解和委托场景：\n\n```mermaid\ngraph LR\n Parent[父会话] -->|创建子代理| Child1[子会话 1]\n Parent -->|创建子代理| Child2[子会话 2]\n Child1 -->|汇报结果| Parent\n Child2 -->|汇报结果| Parent\n```\n\n子会话标识通过 `session()?.parentID` 属性判断，在 UI 层（`packages/opencode/src/cli/cmd/tui/routes/session/index.tsx`）会根据是否为子会话显示不同的界面元素，如子代理底部栏（SubagentFooter）。\n\n### 会话状态同步\n\n会话状态通过 `packages/opencode/src/session/processor.ts` 进行处理，支持实时状态更新和持久化。状态变化时会触发相应的事件通知各订阅模块。\n\n## 消息处理流程\n\n### 处理器架构\n\n消息处理器是 Agent 系统的核心组件，负责将用户输入转换为系统可执行的操作序列。其处理流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Proc as 处理器\n participant LLM as LLM 层\n participant Tools as 工具注册表\n participant Session as 会话管理\n\n User->>Proc: 发送消息\n Proc->>Proc: 消息解析与验证\n Proc->>LLM: 调用 LLM\n LLM-->>Proc: 返回响应\n Proc->>Tools: 检测工具调用\n Tools-->>Proc: 工具结果\n Proc->>LLM: 继续处理\n Proc->>Session: 更新会话历史\n Proc-->>User: 返回最终响应\n```\n\n### 消息类型处理\n\n系统支持多种消息类型，每种类型有对应的处理策略：\n\n| 消息类型 | 来源 | 处理方式 |\n|---------|------|---------|\n| user | 用户输入 | 解析意图、转译为任务 |\n| assistant | LLM 响应 | 解析工具调用、格式化输出 |\n| tool | 工具执行结果 | 整合结果、继续 LLM 循环 |\n| system | 系统消息 | 更新状态、触发事件 |\n| reasoning | 推理过程 | 可选显示、用于调试 |\n\n### 推理处理\n\n对于支持推理的模型，系统会特殊处理 `reasoning` 类型消息。在 `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` 中定义了 `ReasoningPart` 组件，用于渲染推理过程。\n\n推理内容中若包含 `[REDACTED]` 标记（如来自 OpenRouter 的加密推理数据），系统会自动过滤：\n\n```typescript\nconst content = createMemo(() => {\n return props.part.text.replace(\"[REDACTED]\", \"\").trim()\n})\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:112-117]()\n\n## 工具系统\n\n### 工具注册机制\n\n工具注册表位于 `packages/opencode/src/kilocode/tool/registry.ts`，采用注册表模式管理所有可用工具。工具定义包含以下属性：\n\n- **id**：工具唯一标识\n- **name**：工具显示名称\n- **description**：工具功能描述\n- **parameters**：参数模式定义\n- **handler**：执行函数\n\n### 核心工具集\n\n系统内置的核心工具包括：\n\n| 工具名称 | 功能描述 | 注册位置 |\n|---------|---------|---------|\n| Read | 读取文件内容 | 默认注册 |\n| Write | 写入或创建文件 | 默认注册 |\n| Edit | 编辑文件指定区域 | 默认注册 |\n| Bash | 执行终端命令 | 默认注册 |\n| Glob | 文件模式匹配 | 默认注册 |\n| Grep | 代码内容搜索 | 默认注册 |\n| manager | Agent 管理工具 | 条件注册 |\n\n### 工具描述增强\n\n对于 `glob` 和 `grep` 工具，系统会添加额外的使用提示，帮助 LLM 更准确地使用这些工具：\n\n```typescript\nexport function describe(tools: Tool.Def[], extra: { semantic?: Tool.Def }): Tool.Def[] {\n if (!extra.semantic) return tools\n return tools.map((tool) => {\n if (tool.id !== \"glob\" && tool.id !== \"grep\") return tool\n return { ...tool, description: `${tool.description}\\n${hint}` }\n })\n}\n```\n\n资料来源：[packages/opencode/src/kilocode/tool/registry.ts:45-54]()\n\n## LLM 交互层\n\n### 模型调用封装\n\nLLM 交互层位于 `packages/opencode/src/session/llm.ts`，封装了与各类大语言模型的通信细节。系统支持多种模型提供商，包括 OpenAI、Anthropic、OpenRouter 等。\n\n### 流式响应处理\n\n系统采用流式响应模式，通过 Server-Sent Events（SSE）或 WebSocket 实时推送 LLM 输出。流式处理的优势包括：\n\n- **即时反馈**：用户可以立即看到生成的内容\n- **降低延迟**：无需等待完整响应即可开始处理\n- **资源优化**：减少内存占用\n\n### 消息中止机制\n\n系统支持通过 `MessageAbortedError` 中止正在进行的 LLM 调用。在 UI 层会显示 \"interrupted\" 状态标识：\n\n```typescript\n\n · interrupted\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:38-40]()\n\n## 上下文管理\n\n### 上下文压缩策略\n\n由于 LLM 有 token 数量限制，系统实现了上下文压缩机制，位于 `packages/opencode/src/session/compaction.ts`。压缩策略包括：\n\n1. **摘要压缩**：将历史消息压缩为关键信息摘要\n2. **选择性保留**：保留重要上下文，丢弃冗余内容\n3. **滑动窗口**：使用固定大小的上下文窗口\n\n### AGENTS.md 集成\n\n系统支持项目级别的 `AGENTS.md` 文件，该文件包含针对 AI 代理的特定指令。文件搜索逻辑会按以下顺序查找：\n\n1. 项目根目录的 `AGENTS.md`\n2. 子目录中的 `AGENTS.md`\n3. `README.md` 作为备选\n\n```mermaid\ngraph TD\n Start[加载上下文] --> CheckRoot{检查根目录 AGENTS.md}\n CheckRoot -->|存在| UseRoot[使用根目录 AGENTS.md]\n CheckRoot -->|不存在| CheckSub{检查子目录 AGENTS.md}\n CheckSub -->|存在| UseSub[使用子目录 AGENTS.md]\n CheckSub -->|不存在| Fallback[使用 README.md]\n UseRoot --> Done[完成上下文加载]\n UseSub --> Done\n Fallback --> Done\n```\n\n资料来源：[packages/opencode/src/session/prompt/kimi.txt:1-20]()\n\n## MCP 服务器集成\n\n### MCP 状态显示\n\n系统集成了 MCP（Model Context Protocol）服务器支持，在 TUI 界面底部栏显示 MCP 连接状态：\n\n```typescript\n\n \n \n \n ⊙ \n \n \n ⊙ \n \n \n {mcp()} MCP\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:25-37]()\n\n### MCP OAuth 回调\n\nMCP 服务器认证采用 OAuth 2.0 流程，授权成功后会显示确认页面：\n\n```html\n

You can close this window and return to Kilo.

\n\n```\n\n资料来源：[packages/opencode/src/mcp/oauth-callback.ts:28-29]()\n\n## 索引与 LSP 集成\n\n### 索引状态显示\n\n系统支持代码索引功能，在界面底部栏显示当前索引状态：\n\n```typescript\n\n \n {indexingText(indexing()).slice(0, 48)}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:38-41]()\n\n### LSP 连接状态\n\n底部栏同时显示 LSP（Language Server Protocol）连接数量：\n\n```typescript\n\n 0 ? theme.success : theme.textMuted }}>•\n {lsp().length} LSP\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:20-23]()\n\n## 权限管理\n\n### 权限请求机制\n\n当执行敏感操作时，系统会请求用户授权。权限状态在底部栏显示：\n\n```typescript\n 0}>\n \n △\n {permissions().length} Permission{permissions().length > 1 ? \"s\" : \"\"}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:14-19]()\n\n## 文件提及系统\n\n### 文件自动检测\n\n系统支持自动检测和处理用户输入中的文件引用。在 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts` 中实现了文件提及检测逻辑。\n\n文件提及支持多种类型：\n\n| 类型 | 图标 | 显示效果 |\n|-----|------|---------|\n| terminal | console | 显示命令路径 |\n| git-changes | branch | 显示 Git 变更 |\n| file | 文件图标 | 显示文件名和目录 |\n| folder | 文件夹图标 | 显示目录路径 |\n\n### 文件搜索防抖\n\n为避免频繁搜索，系统实现了防抖机制：\n\n```typescript\nlet fileSearchTimer: ReturnType | undefined\nlet fileSearchCounter = 0\n```\n\n搜索结果通过 `requestId` 关联，确保响应的正确性和顺序性。\n\n## 扩展性设计\n\n### 插件插槽系统\n\n系统通过 `TuiPluginRuntime.Slot` 提供扩展插槽，支持第三方插件注入功能：\n\n```typescript\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:198-207]()\n\n### 工具注册表扩展\n\n工具注册表支持动态注册新工具，第三方可以通过扩展点添加自定义工具。注册时需要提供完整的工具定义，包括参数模式和执行处理函数。\n\n## 配置管理\n\n### 同步配置结构\n\n系统使用 `sync` 对象管理配置状态，包括：\n\n- `sync.path.directory`：当前工作目录\n- `sync.data.config`：运行时配置\n- `sync.data.state`：会话状态\n\n### 状态持久化\n\n会话状态支持持久化存储，包括：\n\n- 消息历史\n- 用户偏好设置\n- 工具配置\n- 上下文摘要\n\n## 错误处理\n\n### 错误分类\n\n系统将错误分为以下几类：\n\n| 错误类型 | 处理策略 | 用户可见性 |\n|---------|---------|-----------|\n| LLM 调用错误 | 重试或降级 | 是 |\n| 工具执行错误 | 返回错误信息 | 是 |\n| 认证错误 | 引导重新认证 | 是 |\n| 系统错误 | 记录日志 | 可选 |\n\n### 网络可见性\n\n系统通过 `networkVisible()` 和 `network()` 状态管理网络相关错误的显示：\n\n```typescript\n\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:193-195]()\n\n## 性能优化\n\n### 虚拟文本渲染\n\n对于文件提及等高频更新元素，系统采用虚拟文本渲染优化性能：\n\n```typescript\nif (part.type === \"file\" && part.source?.text) {\n part.source.text.start = extmarkStart\n part.source.text.end = extmarkEnd\n part.source.text.value = virtualText\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:45-51]()\n\n### 频率优化\n\n文件搜索结果通过频率算法（Frecency）排序，优先显示常用文件：\n\n```typescript\nif (part.type === \"file\" && part.source && part.source.type === \"file\") {\n frecency.updateFrecency(part.source.path)\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:65-67]()\n\n## 总结\n\nAgent 核心系统是 KiloCode 平台的核心支柱，通过模块化设计和清晰的职责划分，实现了高效、可靠的智能编程辅助能力。系统各组件之间通过事件和接口进行通信，既保证了功能的独立性，又支持灵活的可扩展性。理解这一架构对于深入使用和二次开发 KiloCode 具有重要意义。\n\n---\n\n\n\n## 自动补全系统 (FIM)\n\n### 相关页面\n\n相关主题：[Agent 核心系统](#agent-system), [代码索引与语义搜索](#indexing-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/services/autocomplete/settings.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/settings.ts)\n- [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)\n- [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)\n- [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)\n- [packages/opencode/src/kilocode/claw/view.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/claw/view.tsx)\n
\n\n# 自动补全系统 (FIM)\n\n## 概述\n\nKiloCode 的自动补全系统（Fill-In-The-Middle，简称 FIM）是一个为开发者提供智能代码补全功能的核心模块。该系统通过分析当前编辑上下文，结合语言模型生成高质量的代码建议，帮助开发者提高编码效率。\n\n自动补全系统支持多种文件类型，包括 Python、TypeScript/TSX、Shell 脚本等，并能根据不同语言特性动态调整补全策略。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"用户界面层\"\n VSCodeEditor[VS Code 编辑器]\n TUIPrompt[TUI 命令行提示符]\n ClawChat[Claw 聊天界面]\n end\n\n subgraph \"补全服务层\"\n AutocompleteProvider[AutocompleteInlineCompletionProvider]\n FillInTheMiddle[FIM 处理器]\n ContextRetrieval[上下文检索服务]\n end\n\n subgraph \"模板与后处理\"\n AutocompleteTemplate[补全模板]\n PostProcessing[后处理器]\n end\n\n subgraph \"配置层\"\n Settings[设置管理]\n Validators[设置验证器]\n end\n\n VSCodeEditor --> AutocompleteProvider\n TUIPrompt --> autocomplete\n ClawChat --> ClawSlashes\n AutocompleteProvider --> FillInTheMiddle\n FillInTheMiddle --> ContextRetrieval\n ContextRetrieval --> AutocompleteTemplate\n AutocompleteTemplate --> PostProcessing\n Settings --> Validators\n```\n\n### 核心组件\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| AutocompleteInlineCompletionProvider | 为 VS Code 提供内联补全项的核心提供者 | settings.ts |\n| FillInTheMiddle | 实现 Fill-In-The-Middle 算法的核心逻辑 | EXAMPLES.md |\n| ContextRetrievalService | 从代码库中检索相关上下文信息 | 架构设计 |\n| AutocompleteTemplate | 管理和渲染补全提示模板 | 架构设计 |\n| PostProcessing | 对模型输出进行后处理和格式化 | 架构设计 |\n\n## 配置系统\n\n### 设置验证机制\n\n自动补全系统通过 `validAutocompleteSetting` 函数验证用户配置，确保只接受有效的设置值：\n\n```typescript\nexport function validAutocompleteSetting(key: string, value: unknown) {\n if (key === \"model\") {\n if (typeof value !== \"string\") return false\n return AUTOCOMPLETE_MODELS.some((m) => m.id === value)\n }\n\n if (key === \"enableAutoTrigger\") return typeof value === \"boolean\"\n if (key === \"enableSmartInlineTaskKeybinding\") return typeof value === \"boolean\"\n if (key === \"enableChatAutocomplete\") return typeof value === \"boolean\"\n\n return false\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:18-31]()\n\n### 支持的配置项\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `model` | string | 选择的补全模型 ID |\n| `enableAutoTrigger` | boolean | 是否启用自动触发 |\n| `enableSmartInlineTaskKeybinding` | boolean | 智能内联任务快捷键 |\n| `enableChatAutocomplete` | boolean | 聊天自动补全 |\n\n## Fill-In-The-Middle 算法\n\n### FIM 工作流程\n\n```mermaid\ngraph LR\n A[光标位置] --> B[获取前缀上下文]\n B --> C[获取后缀上下文]\n C --> D[构建 FIM Prompt]\n D --> E[调用 LLM]\n E --> F[生成补全代码]\n F --> G[后处理]\n G --> H[返回补全建议]\n```\n\n### 分语言配置\n\n系统针对不同编程语言提供了特定的配置优化：\n\n```typescript\nif (fileExtension === \"py\") {\n // Python 特定设置\n this.config.multilineCompletions = \"always\"\n this.config.stopTokens = ['\"\"\"', \"'''\"]\n} else if (fileExtension === \"ts\" || fileExtension === \"tsx\") {\n // TypeScript 特定设置\n this.config.tabAutocompleteOptions = {\n ...this.config.tabAutocompleteOptions,\n maxPromptTokens: 2048,\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:1-60]()\n\n### 上下文窗口管理\n\n| 语言 | 最大 Prompt Token | 多行补全策略 | 停止标记 |\n|------|------------------|-------------|---------|\n| Python | 动态 | 始终启用 | `\"\"\"`, `'''` |\n| TypeScript | 2048 | 动态 | 基于语法 |\n| 默认 | 动态 | 动态 | 基于语法 |\n\n## 上下文检索服务\n\n### 检索策略\n\n上下文检索服务负责从代码库中获取与当前编辑位置相关的代码片段。系统支持以下检索方式：\n\n1. **Tree-Sitter 语法树查询**：基于代码语法结构进行精确检索\n2. **文件路径匹配**：基于文件路径和命名模式\n3. **语义相似度**：基于代码语义内容的相似度匹配\n\n### 代码片段查询\n\n系统使用 Tree-Sitter 进行代码结构分析，支持以下查询能力：\n\n- 导入语句识别\n- 函数和类定义检索\n- 类型注解提取\n- 注释和文档字符串获取\n\n## 补全模板系统\n\n### 模板结构\n\n补全模板定义了如何将上下文信息组织成适合 LLM 处理的格式：\n\n```typescript\ninterface AutocompleteTemplate {\n prefix: string // 光标前内容\n suffix: string // 光标后内容\n aroundCursor: string // 光标周围代码块\n metadata: {\n language: string\n filePath: string\n lineNumber: number\n }\n}\n```\n\n### 模板变量\n\n| 变量 | 说明 | 示例 |\n|-----|------|------|\n| `{{prefix}}` | 光标前代码 | `function hello() {` |\n| `{{suffix}}` | 光标后代码 | `}` |\n| `{{file_name}}` | 当前文件名 | `main.py` |\n| `{{language}}` | 编程语言 | `python` |\n\n## 后处理系统\n\n### 后处理流程\n\n```mermaid\ngraph TD\n A[LLM 输出] --> B[停止标记检测]\n B --> C[语法验证]\n C --> D{是否有效?}\n D -->|是| E[格式化输出]\n D -->|否| F[降级处理]\n E --> G[返回补全项]\n F --> G\n```\n\n### 后处理功能\n\n| 功能 | 描述 |\n|-----|------|\n| 停止标记处理 | 检测并截断在 `stopTokens` 处的输出 |\n| 缩进修正 | 根据文件类型修正缩进 |\n| 语法验证 | 确保输出符合目标语言语法 |\n| 多行处理 | 智能处理跨行代码补全 |\n\n## CLI 命令行界面\n\n### TUI 自动补全组件\n\n在命令行界面中，自动补全系统通过 `autocomplete.tsx` 组件提供交互式补全功能：\n\n```typescript\nconst commands = createMemo((): AutocompleteOption[] => {\n const results: AutocompleteOption[] = [...command.slashes()]\n\n for (const res of Object.values(sync.data.mcp_resource)) {\n const text = `${res.name} (${res.uri})`\n options.push({\n display: Locale.truncateMiddle(text, width),\n value: text,\n description: res.description,\n onSelect: () => { /* ... */ }\n })\n }\n\n return options\n})\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1-120]()\n\n### MCP 资源自动补全\n\n系统支持 MCP（Model Context Protocol）资源的自动补全，开发者可以在提示符中快速引用外部资源。\n\n## VS Code 集成\n\n### 内联补全提供者\n\n`AutocompleteInlineCompletionProvider` 实现了 VS Code 的 `InlineCompletionItemProvider` 接口，提供内联代码补全功能：\n\n```typescript\nclass VSCodeAutocompleteIntegration\n implements vscode.InlineCompletionItemProvider\n{\n private completionProvider: CompletionProvider;\n private currentCompletionId: string | null = null;\n\n constructor() {\n const config = new MinimalConfigProvider();\n const ide = new VSCodeIdeAdapter();\n\n this.completionProvider = new CompletionProvider(\n config,\n ide,\n this.getLlm.bind(this),\n this.onError.bind(this),\n this.getDefinitionsFromLsp.bind(this)\n );\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:62-120]()\n\n### 补全触发流程\n\n```mermaid\nsequenceDiagram\n participant Editor as VS Code 编辑器\n participant Provider as 补全提供者\n participant Config as 配置管理\n participant LLM as 语言模型\n\n Editor->>Provider: 用户触发补全\n Provider->>Config: 获取当前配置\n Config-->>Provider: 返回配置参数\n Provider->>Provider: 构建 FIM Prompt\n Provider->>LLM: 发送补全请求\n LLM-->>Provider: 返回候选代码\n Provider->>Provider: 后处理\n Provider-->>Editor: 返回 InlineCompletionItem\n```\n\n## 文件提及与附件\n\n### 文件提及系统\n\n`useFileMention` hook 提供了在提示中提及和附加文件的功能：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n \n return {\n parseFileAttachments,\n addPaths,\n setMentionIndex,\n closeMention,\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:1-50]()\n\n### 文件类型支持\n\n| 文件类型 | 图标 | 描述显示 |\n|---------|------|---------|\n| 普通文件 | FileIcon | 文件名 + 目录路径 |\n| 文件夹 | FileIcon | 文件夹名 + 父目录 |\n| 终端 | console 图标 | 终端名称 |\n| Git 变更 | branch 图标 | 变更摘要 |\n\n## Claw 聊天集成\n\n### 斜杠命令自动补全\n\n在 Claw 聊天界面中，系统支持斜杠命令的自动补全：\n\n```typescript\nconst clawSlashes = createMemo(() => {\n const visible = kiloCommands().filter((c) => c.enabled !== false && !c.hidden && c.slash)\n const items = visible.map((c) => ({\n display: \"/\" + c.slash!.name,\n description: c.description ?? c.title,\n aliases: c.slash!.aliases?.map((a) => \"/\" + a),\n onSelect: () => c.onSelect?.(dialog),\n }))\n const max = items.reduce((m, i) => Math.max(m, i.display.length), 0)\n if (!max) return items\n return items.map((i) => ({ ...i, display: i.display.padEnd(max + 2) }))\n})\n```\n\n资料来源：[packages/opencode/src/kilocode/claw/view.tsx:1-50]()\n\n## 性能优化\n\n### 增量更新机制\n\n系统通过以下方式优化性能：\n\n1. **延迟加载**：仅在需要时加载补全模型\n2. **缓存策略**：缓存常用上下文的检索结果\n3. **节流处理**：对频繁触发的事件进行节流\n\n### 设置变更监听\n\n```typescript\ncontext.subscriptions.push(\n vscode.workspace.onDidChangeConfiguration((e) => {\n if (e.affectsConfiguration(\"kilo-code.new.autocomplete\")) {\n post(buildAutocompleteSettingsMessage())\n }\n })\n)\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:1-18]()\n\n## 总结\n\nKiloCode 的自动补全系统采用模块化设计，通过 FIM 算法实现智能的上下文感知代码补全。系统支持多种编程语言，提供灵活的配置选项，并通过完善的后处理机制确保补全结果的质量。该系统与 VS Code、TUI 和 Claw 等多个界面无缝集成，为开发者提供一致的优质补全体验。\n\n---\n\n\n\n## Agent Manager 工作流管理\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [MCP 协议与工具集成](#mcp-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts)\n- [packages/kilo-vscode/src/agent-manager/WorktreeManager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/WorktreeManager.ts)\n- [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)\n- [packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts)\n- [packages/kilo-vscode/src/agent-manager/GitOps.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/GitOps.ts)\n- [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)\n- [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)\n- [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts)\n
\n\n# Agent Manager 工作流管理\n\n## 概述\n\nAgent Manager 是 Kilo 平台的核心组件，提供多智能体协作与工作流自动化管理能力。该系统通过集成 Git 工作树管理、PR 状态轮询、GitOps 自动化操作和终端管理，实现了一个高效的多代理代码开发环境。Agent Manager 允许用户创建、配置和管理多个专门化的代理（Agent），每个代理可以拥有独立的权限、提示词和任务范围，从而实现复杂软件工程任务的分工协作。\n\nAgent Manager 的设计理念是将代码开发过程分解为多个可配置的工作单元，通过集中式的调度和协调，确保多个代理能够有序地处理不同类型的任务。从架构层面来看，Agent Manager 不仅仅是一个任务调度器，更是一个完整的开发工作流编排平台，涵盖了从代码生成、审查、测试到部署的完整生命周期管理。\n\n该系统的核心价值体现在以下几个方面：首先，通过细粒度的权限控制机制，每个代理只能访问和操作其被授权的资源，防止未经授权的代码修改；其次，通过 Git 工作树（Worktree）隔离机制，不同代理可以在独立的分支上并行工作，避免相互干扰；再次，通过自动化的 PR 状态监控和 GitOps 操作，实现了持续集成和持续部署的无缝衔接；最后，通过统一的终端管理和会话管理，提供了一致且可追溯的开发体验。\n\n## 核心架构\n\n### 系统组件总览\n\nAgent Manager 的架构采用模块化设计，各组件职责明确且相互协作。核心组件包括 AgentManagerProvider（提供器）、WorktreeManager（工作树管理器）、RunManager（运行管理器）、PRStatusPoller（PR 状态轮询器）、GitOps（Git 运维操作）、TerminalManager（终端管理器）和 SectionHandler（分区处理器）。这些组件共同构成了一个完整的多代理工作流管理生态系统，每个组件专注于特定的功能域，通过定义良好的接口进行通信和协作。\n\n```mermaid\ngraph TD\n AMP[AgentManagerProvider] --> WM[WorktreeManager]\n AMP --> RM[RunManager]\n AMP --> GP[GitOps]\n AMP --> TM[TerminalManager]\n AMP --> SH[SectionHandler]\n WM --> PR[PRStatusPoller]\n RM --> GP\n GP --> TM\n SH --> AMP\n TM --> AMP\n \n subgraph 核心功能域\n WM[工作树管理]\n RM[运行调度]\n GP[Git运维]\n TM[终端控制]\n end\n \n subgraph 监控与协调\n PR[PR轮询]\n SH[分区处理]\n end\n```\n\n### AgentManagerProvider 提供器\n\nAgentManagerProvider 是整个 Agent Manager 系统的中央协调器，负责初始化、管理和协调所有子组件的生命周期。作为 VS Code 扩展的一部分，该提供器在扩展激活时初始化，并在整个扩展生命周期中保持运行状态。它维护着所有已注册代理的元数据、当前运行状态、以及与 VS Code 环境的集成接口。\n\n该提供器的核心职责包括：维护代理配置和状态、响应用户界面的操作请求、协调各子组件之间的通信、以及处理错误和异常情况。它通过 VS Code 的 Webview API 与前端 UI 进行双向通信，确保用户能够实时监控和控制代理的运行状态。此外，它还负责管理与 OpenCode 内核的连接，将用户的操作请求转发到后端执行。\n\nAgentManagerProvider 的设计遵循了依赖注入模式，使得各子组件可以独立开发和测试，同时也便于扩展新的功能模块。每个子组件都通过接口定义与提供器交互，这种松耦合的设计提高了系统的可维护性和可测试性。\n\n### WorktreeManager 工作树管理器\n\nWorktreeManager 是 Agent Manager 中负责 Git 工作树管理的核心组件。Git 工作树机制允许开发者在同一个 Git 仓库中创建多个工作目录，每个工作目录可以绑定到不同的分支。这种机制对于多代理协作开发至关重要，因为它允许不同的代理在完全隔离的环境中并行工作，而不会产生分支冲突或工作进度相互覆盖的问题。\n\n工作树管理器的主要功能包括：创建新的工作树并绑定到指定的分支、列出当前仓库中的所有工作树、清理已完成任务的工作树、以及在需要时自动合并或删除过期的分支。当一个代理需要处理特定功能或修复某个问题时，WorktreeManager 会为其分配一个独立的工作树，确保其工作不会影响其他代理的活动分支。\n\n该组件还负责监控工作树的状态变化，当检测到工作树中的文件发生变化时，会自动通知相关的代理进行相应的处理。这种事件驱动的设计使得系统能够实时响应开发过程中的各种状态变化，保持代理对项目状态的准确理解。\n\n### RunManager 运行管理器\n\nRunManager 负责管理代理的启动、暂停、恢复和终止等生命周期操作。它维护着一个运行队列，调度各个代理任务的执行顺序，并根据系统资源和任务优先级进行合理的资源分配。当用户启动一个代理时，RunManager 会负责初始化代理的运行环境、加载必要的配置和上下文信息、并监控代理的运行状态。\n\n运行管理器的核心特性包括：支持任务的优先级调度、支持任务的依赖关系声明、支持任务执行超时控制、以及支持任务的自动重试机制。当某个任务因为网络故障或其他临时性问题失败时，RunManager 可以根据配置自动重试，减少人工干预的需要。此外，它还支持任务的暂停和恢复功能，这在需要临时中断开发工作或等待外部依赖时非常有用。\n\nRunManager 与其他组件紧密集成，例如它会调用 WorktreeManager 为每个运行的代理分配隔离的工作环境，并通过 GitOps 组件确保所有操作都被正确地记录到 Git 历史中。这种集成设计确保了多代理系统的行为一致性和可追溯性。\n\n### PRStatusPoller PR 状态轮询器\n\nPRStatusPoller 是专门用于监控 Pull Request 状态的组件，它定期轮询远程代码托管平台（如 GitHub、GitLab）的 API，获取 PR 的最新状态信息。这些信息包括 CI/CD 管道的执行结果、代码审查的反馈意见、以及 PR 的合并状态等。轮询器将这些信息汇总后，通过 AgentManagerProvider 分发给相关的代理，使其能够根据最新的 PR 状态做出相应的响应。\n\nPR 状态轮询器支持多种轮询策略：定时轮询（固定间隔）、智能轮询（根据 PR 状态变化频率动态调整间隔）、以及事件驱动轮询（仅在特定事件发生时触发）。默认情况下，轮询器会优先使用智能轮询策略，以减少不必要的 API 调用，同时确保代理能够及时获取重要的状态变化通知。\n\n该组件还实现了背压（Backpressure）控制机制，防止在短时间内大量状态变化导致系统过载。当检测到异常大量的状态变化时，轮询器会自动降低轮询频率，并在状态稳定后逐步恢复正常。这种设计既保证了系统的响应性，又避免了因过度轮询而被远程 API 限流。\n\n### GitOps Git 运维操作\n\nGitOps 组件封装了所有与 Git 仓库操作相关的功能，包括分支创建、提交管理、冲突解决、以及远程同步等。该组件的设计目标是提供一套统一、可靠且可审计的 Git 操作接口，使代理能够以声明式的方式执行各种 Git 操作，而无需关心底层的实现细节。\n\nGitOps 的核心功能包括：自动化的提交消息生成（基于变更内容生成符合规范的提交信息）、智能的分支命名策略（根据任务类型和目标自动生成描述性的分支名）、变更暂存和提交的原子操作保证、以及冲突检测和自动解决（对于简单的冲突能够自动合并，复杂的冲突则通知相关代理进行人工处理）。\n\n该组件还维护着一个操作日志，记录所有 Git 操作的详细信息，包括执行时间、操作类型、操作者（代理标识）、变更的文件列表、以及操作的结果状态。这个日志不仅用于故障排查和审计，还可以通过可视化界面展示给用户，帮助其理解系统的行为和代理的工作进展。\n\n### TerminalManager 终端管理器\n\nTerminalManager 负责管理 VS Code 终端实例，为代理提供命令执行的能力。每个运行的代理都可以拥有自己的终端实例，终端管理器确保这些终端的正确创建、配置和清理。当代理需要执行 shell 命令时（如运行测试、构建项目、或执行部署脚本），终端管理器会分配一个可用的终端实例，并负责捕获命令的输出结果。\n\n终端管理器还实现了输出缓冲和流控制机制，确保即使在命令产生大量输出的情况下，系统也能保持响应。它支持多种终端类型和 shell 环境，并能够根据操作系统自动选择合适的默认 shell。此外，它还提供了终端复用功能，当多个命令需要在同一个 shell 会话中执行时，可以共享同一个终端实例，保持命令之间的上下文关联。\n\n该组件还负责终端的安全管理，通过沙箱机制限制命令的权限范围，防止恶意或有风险的命令被执行。同时，它会记录每个终端会话的完整历史，供后续的调试和审计使用。\n\n### SectionHandler 分区处理器\n\nSectionHandler 负责处理代理会话中的结构化数据分区。在多代理系统中，不同的代理可能需要访问会话的不同部分，而 SectionHandler 提供了对这些分区的访问控制和状态管理。该组件确保每个代理只能看到和修改其被授权的会话分区，防止未授权的信息泄露或操作干扰。\n\n分区处理器支持动态分区创建、分区间的消息传递、以及分区的合并和拆分。当一个复杂的任务被分解为多个子任务分配给不同的代理时，SectionHandler 会为每个子任务创建独立的分区，确保子代理之间的工作不会相互影响。任务完成后，相关的分区可以被合并，形成完整的结果报告。\n\n## 工作流机制\n\n### 多代理协作流程\n\nAgent Manager 的多代理协作机制是其最具特色的功能之一。当用户启动一个复杂的开发任务时，系统会根据配置自动创建或选择一个合适的代理来处理该任务。代理可以进一步将任务分解为子任务，并分配给其他专门化的代理执行。这种层级式的任务分解和分配机制，使得系统能够处理从简单的代码修复到复杂的系统重构等各种规模的任务。\n\n```mermaid\ngraph LR\n User[用户请求] --> AP[AgentManagerProvider]\n AP --> ModeSelect[模式选择]\n ModeSelect --> AgentCreate[代理创建]\n AgentCreate --> WorktreeAlloc[工作树分配]\n WorktreeAlloc --> TaskExec[任务执行]\n TaskExec --> GitOpsLog[GitOps记录]\n GitOpsLog --> PRCheck{PR状态检查}\n PRCheck -->|需要审查| Review[代码审查]\n PRCheck -->|完成| Merge[合并分支]\n Review --> AgentCreate\n Merge --> TerminalExec[终端命令执行]\n TerminalExec --> TaskExec\n \n subgraph 代理协作\n ModeSelect\n AgentCreate\n WorktreeAlloc\n end\n \n subgraph 质量保障\n GitOpsLog\n PRCheck\n Review\n end\n```\n\n多代理协作的关键在于协调机制的设计。Agent Manager 提供了多种协调策略：中央协调模式（由一个主代理负责任务分配和结果汇总）、分布式协调模式（各代理通过消息传递自主协调）、以及混合模式（根据任务特点动态选择协调方式）。系统会根据任务的复杂度和代理的数量自动选择最合适的协调模式。\n\n### 代理权限控制\n\n代理权限控制是 Agent Manager 安全架构的核心组成部分。每个代理在创建时都会被分配一组权限定义，这些权限决定了代理可以执行的操作类型和可以访问的资源范围。权限定义采用灵活的规则匹配语法，支持通配符和否定模式，能够精确地控制代理对文件和操作的访问。\n\n从源码中可以看到权限配置的结构示例：\n\n```typescript\npermission: {\n \"*\": \"deny\", // 默认拒绝所有操作\n read: \"allow\", // 允许读取文件\n grep: \"allow\", // 允许搜索文件内容\n glob: \"allow\", // 允许文件模式匹配\n edit: { // 编辑操作特殊规则\n \"*\": \"deny\", \n \"**/*.md\": \"allow\" // 仅允许编辑 Markdown 文件\n },\n bash: \"deny\", // 拒绝终端命令\n task: \"ask\", // 任务创建需要确认\n skill: \"deny\" // 拒绝使用技能\n}\n```\n\n这种细粒度的权限控制机制确保了系统安全性，即使某个代理被利用或配置错误，其潜在的破坏范围也被限制在最小范围内。同时，权限规则支持继承和覆盖，子规则可以覆写父规则的设置，使得权限配置既简洁又灵活。\n\n### 模式切换与专用代理\n\nAgent Manager 支持多种工作模式（Mode），每种模式对应不同的代理类型和配置。最常用的模式包括：\n\n- **Architect 模式**：专注于系统架构设计和规划，负责理解需求、制定技术方案\n- **Coder 模式**：负责代码编写和实现，执行具体的开发任务\n- **Reviewer 模式**：专门进行代码审查，发现潜在的 Bug 和改进点\n- **Debugger 模式**：专注于问题定位和修复，执行调试任务\n\n用户可以通过斜杠命令（Slash Command）快速切换模式，例如 `/mode coder` 切换到编码模式，`/variant fast` 切换到快速推理变体。这些快捷命令简化了工作流程的操作步骤，提高了开发效率。\n\n专用代理（Dedicated Agent）是为特定任务或项目定制的代理实例，拥有专门的提示词、工具配置和权限设置。用户可以在配置文件中定义自己的代理模板，也可以在 VS Code 界面中通过向导创建和编辑代理配置。Agent Manager 的 webview 界面提供了直观的代理管理模式，包括创建、编辑、删除和权限配置等操作。\n\n## 配置管理\n\n### kilo.json 配置结构\n\nAgent Manager 的配置通过 `kilo.json`（或 `kilo.jsonc`）文件管理，采用分层配置机制，支持远程配置、全局配置、项目配置和即时配置等多种来源。配置项按照优先级从低到高依次应用，后面的配置会覆盖前面的同名配置项。\n\n配置搜索路径按照以下顺序查找：远程 well-known 配置、全局配置（`~/.config/kilo/kilo.json`）、环境变量 `KILO_CONFIG`、项目根目录配置（`./kilo.json`）、`.kilo/kilo.json` 目录配置、以及 `KILO_CONFIG_CONTENT` 环境变量内容。这种设计确保了配置既有足够的灵活性，又保持了清晰的优先级关系。\n\n代理配置的关键字段包括：代理名称（name）、描述（description）、提示词（prompt）、使用的模型（model）、工具列表（tools）、权限规则（permission）、以及启动和运行脚本（setup/run scripts）。这些字段共同定义了代理的行为特征和能力边界。\n\n### 命令配置（Commands）\n\n命令是通过 Markdown 文件定义的自动化任务脚本，存储在 `.kilo/commands/` 目录中。每个命令文件包含 YAML 前置元数据和 Markdown 格式的命令体。元数据定义命令的元信息，如描述、关联的代理、使用的模型等；命令体包含实际的任务指令，可以使用模板变量引用参数。\n\n命令文件的结构示例：\n\n```yaml\n---\ndescription: 运行测试并修复失败\nagent: code\nmodel: anthropic/claude-sonnet\nsubtask: true\n---\n运行所有测试在 $1 并修复失败。\n使用 $ARGUMENTS 获取完整参数。\n通过 @file 引用文件，通过 !`cmd` 引用命令输出。\n```\n\n模板变量支持位置参数（`$1`、`$2` 等）、完整参数（`$ARGUMENTS`）、文件引用（`@file`）、以及命令输出引用（`!`cmd``）。这种参数化设计使得同一个命令模板可以灵活地处理不同的输入场景。\n\n## 工具注册与扩展\n\n### 工具注册表架构\n\nAgent Manager 通过统一的工具注册表（Tool Registry）管理所有可用的工具扩展。工具注册表维护着一个工具定义列表，每个定义包含工具的唯一标识符、名称、描述、参数模式、以及执行函数。当代理需要使用某个工具时，注册表负责验证参数、执行工具逻辑、并返回结果给调用者。\n\n工具注册支持条件注册机制，通过 `agent_manager_tool` 标记控制工具在特定上下文中的可见性。例如，某些工具可能仅在 Agent Manager 模式下可用，而在普通编辑模式下被隐藏。这种条件注册确保了工具的合理使用场景，避免了功能滥用。\n\n注册表还提供了工具描述增强功能，可以根据额外的上下文信息（如语义搜索结果）自动丰富工具的描述信息。这种动态描述增强有助于代理更准确地理解工具的用途和使用方法，提高工具选择的准确性。\n\n### MCP 服务器集成\n\nAgent Manager 通过 MCP（Model Context Protocol）服务器市场支持第三方工具扩展集成。用户可以浏览、搜索和安装来自社区的 MCP 服务器，扩展代理的工具能力。安装过程通过 VS Code 界面的引导式向导完成，包括依赖检查、参数配置和权限确认等步骤。\n\nMCP 服务器的安装支持前置条件检查，例如某些服务器可能需要特定的 Node.js 版本或操作系统依赖。前置条件未满足时，向导会显示警告信息，并指导用户进行必要的准备工作。安装完成后，服务器会自动注册其提供的工具到全局注册表中，供所有代理使用。\n\n## Webview UI 交互\n\n### 迁移向导界面\n\nAgent Manager 提供了直观的 Webview 用户界面，用于代理的创建、配置和管理。迁移向导（Migration Wizard）是用户首次使用时会接触到的引导界面，展示了新版本的主要功能特性，包括性能提升、界面改进和 Agent Manager 增强等模块。\n\n向导界面通过模块化的卡片布局展示功能特性，每个卡片包含图标、标题和详细说明。用户可以通过\"了解更多\"链接访问官方文档或博客文章，深入了解各项功能的细节。向导的底部提供了继续按钮，点击后进入主界面开始使用 Agent Manager。\n\n### 代理管理界面\n\n代理管理界面提供了对所有已配置代理的完整视图，支持创建新代理、编辑现有代理、调整权限配置、以及删除不需要的代理。每个代理的配置通过表单界面进行编辑，包括基本信息（名称、描述）、提示词配置、模型选择、工具启用和权限规则设置等。\n\n界面还提供了代理的使用统计信息，包括已执行的命令数量、成功率和平均响应时间等指标。这些统计数据帮助用户评估代理的效率，并根据需要进行调优。此外，界面支持代理配置的导入和导出，方便在团队成员之间共享标准化的代理模板。\n\n## 数据流与状态管理\n\n### 会话状态同步\n\nAgent Manager 通过 VS Code 的消息传递机制实现 Webview 与扩展后端之间的状态同步。Webview 发送操作请求（如启动代理、切换模式），后端执行相应操作并通过消息推送状态更新到前端。这种双向通信机制确保了用户界面的实时性和一致性。\n\n状态管理采用集中式设计，所有会话状态（包括代理列表、运行状态、任务队列等）由 AgentManagerProvider 统一维护。前端通过订阅感兴趣的状态变更事件，在状态变化时自动重新渲染界面组件。这种响应式的状态管理简化了前端代码的复杂度，同时保证了数据的一致性。\n\n### 文件变更监控\n\n文件变更监控通过 `useFileMention` hook 实现，它监听编辑器中的文件提及事件，提供文件搜索、路径解析和附件管理功能。当用户在输入中引用文件路径时，hook 会自动触发文件搜索，返回匹配的文件列表供用户选择。\n\n文件提及系统支持多种类型的内容：普通文件、文件夹、终端会话、Git 变更等。每种类型都有对应的图标和展示格式，确保用户能够快速识别所选内容的性质。系统还支持拖拽添加文件路径，以及通过命令行自动补全功能快速插入文件引用。\n\n## 最佳实践\n\n### 代理设计原则\n\n设计高效的代理应遵循以下原则：单一职责（每个代理专注于特定类型的任务）、最小权限（仅授予完成任务所需的最小权限集）、清晰边界（明确定义代理之间的交互接口）、以及可观测性（确保代理行为可追踪和可调试）。\n\n对于复杂的多代理场景，建议采用渐进式分解策略：首先识别任务的主要阶段，然后为每个阶段设计专门的代理，最后定义代理之间的协作协议。这种方法既保证了系统的模块化，又避免了过早的复杂性引入。\n\n### 权限配置建议\n\n权限配置应遵循白名单原则（默认拒绝、按需开放）而非黑名单原则（默认允许、按需限制）。这种设计可以最大程度地减少安全风险，即使配置出现疏漏，未明确授权的操作也会被拒绝。\n\n对于涉及危险操作的工具（如删除文件、执行系统命令），建议设置为需要确认（`ask`），让用户在执行前有机会审查操作的影响。同时，应定期审查代理的权限配置，确保权限设置与实际需求保持一致，及时撤销不再需要的权限。\n\n## 常见问题与故障排除\n\n### 工作树冲突处理\n\n当多个代理在相同分支上工作时，可能会产生工作树冲突。如果两个代理尝试在同一个工作树中执行操作，系统会检测到冲突并自动将其中一个代理重新分配到新的工作树。如果仓库的工作树数量达到上限，系统会提示用户清理不再需要的工作树。\n\n手动解决冲突的方法包括：使用 `git worktree remove` 命令删除过期的分支，通过 `git branch -d` 删除已合并的分支，以及使用 VS Code 的 Git 图形界面查看和清理工作树状态。\n\n### 代理无响应处理\n\n如果代理长时间无响应，首先检查终端输出是否正常显示，可以通过 TerminalManager 查看命令的执行状态。如果命令本身在等待外部输入，代理会一直阻塞直到收到输入或超时。\n\n对于卡死的代理，可以尝试通过界面手动终止其任务，系统会自动清理相关的工作树和临时文件。如果问题持续发生，建议检查代理配置是否正确，特别是涉及网络请求的配置项（如代理设置、超时时间等）。\n\n---\n\n*本文档由 Kilo 官方技术团队维护，如有更新请参考 GitHub 仓库中的最新源码。*\n\n---\n\n\n\n## MCP 协议与工具集成\n\n### 相关页面\n\n相关主题：[Agent 核心系统](#agent-system), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts)\n- [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)\n- [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)\n- [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)\n
\n\n# MCP 协议与工具集成\n\n## 概述\n\nMCP（Model Context Protocol，模型上下文协议）是 KiloCode 中用于扩展 AI 能力的关键协议层。它允许 KiloCode 与外部工具和服务进行标准化通信，使 AI 能够调用文件系统操作、代码搜索、Shell 命令等能力。KiloCode 的 MCP 集成架构采用了模块化设计，将协议处理、工具注册、认证授权等核心功能解耦，确保系统的可扩展性和可维护性。\n\n## 架构设计\n\n### 整体架构\n\nKiloCode 的 MCP 系统采用分层架构，包括协议层、工具层、认证层和 UI 集成层四个主要部分。\n\n```mermaid\ngraph TD\n A[用户交互层] --> B[TUI/Session 组件]\n B --> C[MCP 协议处理]\n C --> D[工具注册表]\n D --> E[文件系统工具]\n D --> F[代码搜索工具]\n D --> G[Shell 工具]\n C --> H[认证授权模块]\n H --> I[OAuth 提供者]\n H --> J[Token 管理]\n E --> K[VSCode 集成]\n F --> K\n G --> K\n```\n\n### 核心模块关系\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 入口 | `packages/opencode/src/mcp/index.ts` | MCP 协议初始化和核心处理 |\n| 工具注册表 | `packages/opencode/src/kilocode/tool/registry.ts` | 工具定义、描述和注册 |\n| OAuth 提供者 | `packages/opencode/src/mcp/oauth-provider.ts` | OAuth 2.0 认证流程 |\n| 认证模块 | `packages/opencode/src/mcp/auth.ts` | Token 管理和安全验证 |\n| MCP 配置 | `packages/opencode/src/config/mcp.ts` | 配置管理和环境变量 |\n\n## 工具注册系统\n\n### 工具注册表架构\n\n工具注册表是 KiloCode MCP 集成的核心组件，负责管理所有可用的工具定义。每个工具都包含唯一标识符、描述信息、执行逻辑和参数模式。注册表支持动态添加和移除工具，使系统能够在运行时扩展功能。\n\n在 `packages/opencode/src/kilocode/tool/registry.ts` 中，工具注册通过 `Tool.Def` 类型定义，支持为工具添加额外的元数据标记，如 `agent_manager_tool` 标志用于标识需要代理管理器参与的工具。\n\n### 核心工具类型\n\nKiloCode 实现了多种类型的核心工具，覆盖了日常开发中的常见需求。\n\n```mermaid\ngraph LR\n A[工具请求] --> B{工具类型判断}\n B -->|文件操作| C[Read/Write 工具]\n B -->|Shell| D[Bash 工具]\n B -->|搜索| E[Grep 工具]\n C --> F[文件系统]\n D --> G[系统命令]\n E --> H[代码索引]\n```\n\n| 工具名称 | 源文件 | 功能描述 |\n|----------|--------|----------|\n| bash | `packages/opencode/src/tool/bash.ts` | 执行 Shell 命令和脚本 |\n| read | `packages/opencode/src/tool/read.ts` | 读取文件内容和元数据 |\n| write | `packages/opencode/src/tool/write.ts` | 创建和修改文件 |\n| grep | `packages/opencode/src/tool/grep.ts` | 代码搜索和模式匹配 |\n| glob | 注册表中定义 | 文件名模式匹配 |\n| 代理管理 | registry.ts:工具注册 | 多代理协同任务管理 |\n\n### 工具描述增强\n\n工具注册表提供了 `describe` 函数用于增强工具描述。该函数根据上下文条件为特定工具添加额外的使用提示信息，帮助 AI 更好地理解工具的使用场景和参数要求。\n\n资料来源：[packages/opencode/src/kilocode/tool/registry.ts:工具注册]()\n\n## MCP 状态管理\n\n### TUI 状态显示\n\n在 KiloCode 的终端用户界面中，MCP 连接状态通过状态栏组件实时展示。用户可以直观地了解当前 MCP 连接的健康状况和错误状态。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP状态显示]()\n\n状态显示组件实现了以下功能：\n\n- **连接状态指示器**：使用圆形图标表示连接状态，绿色表示正常，红色表示错误\n- **MCP 服务计数**：显示当前活跃的 MCP 服务数量\n- **错误状态展示**：当 MCP 服务出现错误时显示警告信息\n\n```mermaid\nstateDiagram-v2\n [*] --> Disconnected: 初始状态\n Disconnected --> Connecting: 用户连接\n Connecting --> Connected: 连接成功\n Connecting --> Error: 连接失败\n Connected --> Disconnected: 用户断开\n Connected --> Error: 服务异常\n Error --> Connecting: 重试连接\n Error --> Disconnected: 放弃连接\n```\n\n### 文件提及系统\n\n文件提及（Mention）是 KiloCode 中用于快速引用文件和目录的功能。该系统与 MCP 集成，允许用户通过 `@` 符号快速选择项目中的文件。\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:文件提及Hook]()\n\n文件提及系统的核心流程包括：\n\n1. **搜索触发**：用户输入 `@` 符号激活搜索\n2. **异步搜索**：通过 MCP 协议向 VSCode 扩展发送搜索请求\n3. **结果缓存**：使用 `frecency` 算法优化搜索结果的排序和缓存\n4. **路径解析**：将相对路径转换为绝对路径供后续处理使用\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as 终端界面\n participant Hook as useFileMention\n participant MCP as MCP 协议层\n participant VSCode as VSCode 扩展\n \n User->>TUI: 输入 @ 触发搜索\n TUI->>Hook: 调用 setMentionQuery\n Hook->>MCP: 发送 fileSearchResult 请求\n MCP->>VSCode: 转发搜索请求\n VSCode-->>MCP: 返回文件列表\n MCP-->>Hook: 传递搜索结果\n Hook-->>TUI: 更新 mentionResults\n TUI-->>User: 显示下拉列表\n```\n\n## 配置管理\n\n### MCP 配置结构\n\nMCP 配置通过 `packages/opencode/src/config/mcp.ts` 统一管理，支持从环境变量和配置文件两个渠道读取配置参数。\n\n| 配置项 | 类型 | 说明 | 来源 |\n|--------|------|------|------|\n| mcp_servers | string[] | 启用的 MCP 服务器列表 | 环境变量 |\n| mcp_timeout | number | 请求超时时间（毫秒） | 配置文件 |\n| mcp_retry | number | 失败重试次数 | 配置文件 |\n| oauth_config | object | OAuth 认证配置 | 配置文件 |\n\n### 认证配置\n\nKiloCode 支持 OAuth 2.0 认证协议，用于安全地与外部服务建立连接。认证模块包含令牌管理、刷新机制和安全存储等功能。\n\n资料来源：[packages/opencode/src/mcp/auth.ts:认证模块]()\n资料来源：[packages/opencode/src/mcp/oauth-provider.ts:OAuth提供者]()\n\n## 自动补全集成\n\n### 提示词自动补全\n\n在终端界面的提示词输入组件中，MCP 工具的自动补全功能被深度集成。用户输入特定前缀时，系统会通过 MCP 协议获取可用的工具列表，并在下拉菜单中展示。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:自动补全逻辑]()\n\n### 文件提及与 MCP 交互\n\n自动补全组件与文件提及系统紧密协作。当用户引用文件时，组件会：\n\n1. 解析文件路径并确定基础目录\n2. 判断路径是绝对路径还是相对路径\n3. 通过 MCP 协议获取文件信息\n4. 更新编辑器的标记（extmark）以高亮显示引用\n\n```mermaid\nflowchart TD\n A[用户输入 /] --> B{输入内容判断}\n B -->|@符号| C[激活文件提及]\n B -->|工具前缀| D[激活工具补全]\n B -->|普通文本| E[普通输入处理]\n C --> F[MCP 文件搜索]\n D --> G[MCP 工具列表]\n F --> H[更新提及索引]\n G --> I[显示工具选项]\n H --> J[用户选择]\n I --> J\n J --> K[插入引用内容]\n K --> L[创建文件部分]\n```\n\n## 错误处理机制\n\n### MCP 错误状态\n\n当 MCP 服务出现错误时，状态栏会显示错误指示器。系统会区分不同类型的错误，并提供相应的用户反馈。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP错误状态]()\n\n错误处理策略包括：\n\n- **连接失败**：显示重试选项，用户可手动触发重新连接\n- **认证过期**：自动触发 Token 刷新流程\n- **服务不可用**：标记服务状态并在工具列表中隐藏不可用项\n- **超时错误**：根据配置的重试策略自动重试\n\n## 与 VSCode 扩展的集成\n\n### 通信机制\n\nKiloCode 的 MCP 系统通过 VSCode 扩展提供的消息通道与编辑器进行双向通信。Webview UI 中的 React 组件使用特定的 Hook 与 MCP 后端交互。\n\n文件提及功能的实现涉及多个层次的协作：\n\n1. **UI 层**：`useFileMention` Hook 管理搜索状态和结果\n2. **通信层**：通过 `onMessage` 回调处理来自扩展的消息\n3. **协议层**：MCP 协议定义消息格式和路由规则\n4. **后端层**：VSCode 扩展执行实际的文件系统操作\n\n## 扩展性设计\n\n### 添加新工具\n\nKiloCode 的工具注册系统设计支持便捷的功能扩展。添加新工具的流程包括：\n\n1. 在 `packages/opencode/src/tool/` 目录下创建新的工具文件\n2. 定义工具的输入输出模式\n3. 在 `registry.ts` 中注册工具定义\n4. 添加工具的执行逻辑\n5. 在 UI 层添加对应的补全支持\n\n### MCP 服务器配置\n\n外部 MCP 服务器可以通过配置文件或环境变量添加到 KiloCode。系统支持热加载配置，无需重启即可启用新的 MCP 服务。\n\n## 最佳实践\n\n### 开发新工具\n\n| 阶段 | 关键点 | 参考文件 |\n|------|--------|----------|\n| 设计 | 明确输入输出类型和错误处理 | `packages/opencode/src/tool/read.ts` |\n| 实现 | 遵循现有工具的文件结构 | `packages/opencode/src/tool/bash.ts` |\n| 注册 | 在 registry 中添加工具定义 | `packages/opencode/src/kilocode/tool/registry.ts` |\n| 测试 | 使用 MCP 协议测试工具调用 | - |\n| 文档 | 更新自动补全的提示文本 | `packages/opencode/src/cli/cmd/tui/component/prompt/` |\n\n### 故障排查\n\n常见的 MCP 相关问题及排查方向：\n\n- **工具不可用**：检查工具是否在注册表中正确注册\n- **搜索无结果**：验证 MCP 服务器连接状态\n- **认证失败**：检查 OAuth 配置和 Token 有效期\n- **状态显示异常**：查看 TUI 状态栏的错误信息\n\n---\n\n\n\n## 代码索引与语义搜索\n\n### 相关页面\n\n相关主题：[自动补全系统 (FIM)](#autocomplete-system), [Agent 核心系统](#agent-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-indexing/src/indexing/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/index.ts)\n- [packages/kilo-indexing/src/indexing/manager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/manager.ts)\n- [packages/kilo-indexing/src/indexing/orchestrator.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/orchestrator.ts)\n- [packages/kilo-indexing/src/tree-sitter/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/index.ts)\n- [packages/kilo-indexing/src/tree-sitter/languageParser.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/languageParser.ts)\n- [packages/kilo-indexing/src/indexing/embedders/openai.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/embedders/openai.ts)\n- [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)\n- [packages/opencode/src/tool/semantic-search.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/semantic-search.ts)\n
\n\n# 代码索引与语义搜索\n\n## 概述\n\nKiloCode 的代码索引与语义搜索系统是一个多层次的代码理解和检索解决方案，旨在为开发者提供基于代码语义的高效搜索能力。该系统通过集成 Tree-sitter 语法解析、向量嵌入和语义向量存储技术，实现了对代码库的深度索引，使得开发者可以使用自然语言描述来查找相关代码片段。\n\n该系统位于 `packages/kilo-indexing` 包中，作为 KiloCode 平台的核心基础设施之一，为 IDE 扩展和 CLI 工具提供统一的代码理解能力。\n\n## 系统架构\n\n### 核心组件\n\n代码索引与语义搜索系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| 索引管理器 | `packages/kilo-indexing/src/indexing/manager.ts` | 协调和管理整个索引生命周期 |\n| 索引协调器 | `packages/kilo-indexing/src/indexing/orchestrator.ts` | 编排增量索引和全量索引任务 |\n| Tree-sitter 解析器 | `packages/kilo-indexing/src/tree-sitter/languageParser.ts` | 解析多种编程语言的语法树 |\n| 向量嵌入器 | `packages/kilo-indexing/src/indexing/embedders/openai.ts` | 生成代码片段的语义向量 |\n| 向量存储 | `packages/kilo-indexing/src/indexing/vector-store/lancedb-vector-store.ts` | 存储和检索向量数据 |\n| 语义搜索工具 | `packages/opencode/src/tool/semantic-search.ts` | 提供给 LLM 调用的搜索接口 |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[源代码文件] --> B[Tree-sitter 解析器]\n B --> C[语法树节点]\n C --> D[代码分块策略]\n D --> E[代码片段]\n E --> F[OpenAI 嵌入器]\n F --> G[语义向量]\n G --> H[LanceDB 向量存储]\n \n I[用户查询] --> J[语义搜索工具]\n J --> K[查询向量生成]\n K --> H\n H --> L[相似度匹配]\n L --> M[搜索结果排序]\n M --> N[返回相关代码片段]\n```\n\n## 索引管理\n\n### 索引生命周期\n\n索引管理器负责处理代码库从初始扫描到增量更新的完整生命周期。系统支持增量索引策略，仅对修改过的文件进行重新索引，以优化性能并减少资源消耗。\n\n索引状态在用户界面中实时显示，状态信息包括当前索引进度、已索引文件数量和索引完成百分比。系统会根据索引状态调整配色方案，使用不同色调传达当前索引状态。\n\n```typescript\n// 索引状态显示逻辑示例\n\n \n {indexingText(indexing()).slice(0, 48)}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx]()\n\n### 向量存储\n\n系统使用 LanceDB 作为底层向量存储解决方案，这是一种专为机器学习应用设计的高性能嵌入式数据库。向量存储负责持久化代码片段的语义向量表示，并支持高效的相似度搜索查询。\n\n向量存储的数据模型包含以下关键字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| code | string | 原始代码文本 |\n| embedding | float[] | 语义向量 |\n| filePath | string | 文件路径 |\n| language | string | 编程语言 |\n| startLine | number | 代码块起始行 |\n| endLine | number | 代码块结束行 |\n| symbols | string[] | 提取的符号信息 |\n\n## 语法解析\n\n### Tree-sitter 集成\n\nTree-sitter 是 KiloCode 代码索引系统的语法分析引擎，提供了增量解析能力，能够高效处理大型代码库。系统支持多种主流编程语言的语法解析，包括 JavaScript、TypeScript、Python、Go、Rust 等。\n\n语法解析器将源代码转换为抽象语法树（AST），在此基础上进行代码分块和符号提取。分块策略是影响搜索质量的关键因素，系统会根据语言特性采用不同的分块方法，确保每个代码片段具有完整的语义上下文。\n\n### 语言解析器配置\n\n每种编程语言都有对应的解析器配置文件，定义了语言特定的语法规则和代码块边界识别逻辑。语言解析器还负责提取代码中的关键符号信息，包括函数名、类名、变量名等，这些信息用于增强搜索匹配的准确性。\n\n## 向量嵌入\n\n### OpenAI 嵌入集成\n\n系统使用 OpenAI 的文本嵌入模型将代码片段转换为高维向量。嵌入器负责将原始代码文本转换为固定维度的浮点数向量，这些向量捕捉了代码的语义特征，使得语义相似的代码在向量空间中彼此接近。\n\n嵌入器配置支持以下参数：\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| model | string | text-embedding-3-small | OpenAI 嵌入模型名称 |\n| dimensions | number | 1536 | 向量维度 |\n| batchSize | number | 100 | 批处理大小 |\n\n### 向量生成流程\n\n代码片段经过预处理后被发送到 OpenAI API 进行嵌入。预处理步骤包括移除注释、规范化空白字符和添加语言提示信息。语言提示帮助嵌入模型更好地理解代码语义，提高跨语言代码搜索的准确性。\n\n## 语义搜索\n\n### 搜索接口\n\n语义搜索通过专门的工具接口暴露给 LLM，LLM 可以调用该工具进行代码搜索。搜索接口接受自然语言查询，返回与查询意图最相关的代码片段及其在代码库中的位置信息。\n\n```typescript\n// 语义搜索工具配置\nToolRegistry.register({\n name: \"semantic_search\",\n // 搜索工具实现\n})\n```\n\n资料来源：[packages/opencode/src/tool/semantic-search.ts]()\n\n### 搜索结果排序\n\n搜索结果根据向量相似度分数进行排序，系统返回最相关的 Top-N 个代码片段。每个结果包含文件路径、行号范围、代码内容和相似度分数。LLM 可以利用这些信息直接跳转到相关代码位置。\n\n### 搜索增强策略\n\n系统支持多种搜索增强策略以提高搜索结果质量：\n\n- **符号匹配增强**：优先返回包含查询关键词符号的代码片段\n- **上下文扩展**：返回代码片段时同时提供周围的上下文代码\n- **多语言支持**：跨语言搜索相关的代码实现\n- **过滤机制**：支持按文件类型、目录路径等条件过滤搜索结果\n\n## 配置与调优\n\n### 索引配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| enabled | boolean | true | 是否启用索引功能 |\n| maxFileSize | number | 1048576 | 单文件最大字节数 |\n| excludedPatterns | string[] | [\"node_modules\", \"dist\", \"build\"] | 排除的文件模式 |\n| indexInterval | number | 300000 | 增量索引间隔（毫秒） |\n| embeddingModel | string | text-embedding-3-small | 嵌入模型选择 |\n\n### 性能优化\n\n系统采用多级缓存策略减少重复计算，索引结果缓存在本地以支持快速重启。向量存储采用分区策略，按编程语言和目录结构进行数据分区，搜索时仅扫描相关分区以提高查询效率。\n\n## 使用场景\n\n### IDE 集成\n\n在 VS Code 扩展中，索引系统为以下功能提供支持：\n\n- 智能代码补全建议\n- 语义跳转定义\n- 查找引用\n- 相关代码推荐\n\n### CLI 工具\n\n在 TUI 界面的会话组件中，索引状态实时显示在底部状态栏，用户可以直观地了解当前代码库的索引进度和可用性状态。\n\n## 技术限制与注意事项\n\n- 向量嵌入依赖外部 API，网络延迟可能影响索引性能\n- 大型代码库的初始索引需要较长时间，建议在后台执行\n- 部分编程语言的语法解析可能不完全支持最新语言特性\n\n---\n\n\n\n## IDE 扩展实现\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/extension.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts)\n- [packages/kilo-vscode/webview-ui/src/App.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/App.tsx)\n- [packages/kilo-vscode/src/kilo-provider/KiloProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/kilo-provider/KiloProvider.ts)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n
\n\n# IDE 扩展实现\n\n## 概述\n\nKiloCode 是一个跨平台的 AI 编程助手，通过 IDE 扩展的形式集成到主流开发环境中。目前支持的 IDE 包括 Visual Studio Code 和 JetBrains 系列（如 IntelliJ IDEA、WebStorm 等）。\n\nIDE 扩展的核心职责包括：\n\n- **会话管理**：创建和管理与 AI 模型的交互会话\n- **编辑器集成**：在 IDE 中嵌入 WebView 用户界面\n- **文件操作**：监听文件变化、处理文件提及和附件\n- **工具调用**：注册和执行各种开发工具（如终端、Git、浏览器自动化等）\n- **命令系统**：支持斜杠命令（Slash Commands）和快捷操作\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[IDE 宿主] --> B[扩展后端]\n A --> C[扩展前端 WebView]\n B --> D[Kilo 后端服务]\n C --> B\n C --> E[本地文件操作]\n B --> F[AI 模型]\n F --> B\n```\n\n### VS Code 扩展架构\n\nVS Code 扩展采用双层架构设计：\n\n1. **后端层（Extension Host）**：运行在 Node.js 环境，负责与 VS Code API 和 Kilo 后端通信\n2. **前端层（WebView）**：运行在独立的 WebView 环境中，负责用户界面渲染\n\n```mermaid\ngraph LR\n A[VS Code API] --> B[Extension.ts]\n B --> C[KiloProvider]\n C --> D[WebView 通信]\n D --> E[App.tsx]\n E --> F[React 组件]\n F --> G[Hooks]\n G --> H[VSCodeContext]\n```\n\n### JetBrains 扩展架构\n\nJetBrains 扩展采用类似的分层设计，但使用不同的技术栈：\n\n```mermaid\ngraph TD\n A[JetBrains 平台] --> B[KiloToolWindowFactory]\n B --> C[KiloBackendAppService]\n C --> D[KiloSessionRpcApi]\n D --> E[RPC 通信层]\n E --> F[Kilo 后端服务]\n```\n\n## 核心组件\n\n### VS Code 扩展入口\n\n`packages/kilo-vscode/src/extension.ts` 是扩展的入口文件，负责初始化整个扩展：\n\n```typescript\n// 扩展激活入口\nexport function activate(context: ExtensionContext) {\n // 初始化 KiloProvider\n // 注册命令\n // 建立 WebView 通信通道\n}\n```\n\n主要职责：\n- 注册 VS Code 命令（如 `kilo.open`、`kilo.sendMessage`）\n- 初始化 `KiloProvider` 实例\n- 处理扩展生命周期事件\n\n### KiloProvider\n\n`KiloProvider` 是核心的状态管理和通信中心，位于 `packages/kilo-vscode/src/kilo-provider/KiloProvider.ts:1`：\n\n```typescript\n// KiloProvider 核心职责\n- 管理会话状态\n- 处理消息路由\n- 与后端服务通信\n- 管理文件搜索和提及\n```\n\n### WebView 应用\n\n`App.tsx` 是前端 WebView 的根组件，负责整体布局和状态协调：\n\n```typescript\n// App.tsx 核心功能\n- 提供全局上下文\n- 路由管理\n- 错误边界\n- 迁移向导集成\n```\n\n## 通信机制\n\n### WebView 与扩展后端的通信\n\nKiloCode 使用 `postMessage` API 实现 WebView 与扩展后端的双向通信：\n\n```mermaid\nsequenceDiagram\n participant W as WebView\n participant E as Extension Host\n participant B as Kilo Backend\n \n W->>E: postMessage({ type: \"fileSearchResult\", items })\n E->>B: 转发请求\n B->>E: 返回结果\n E->>W: postMessage({ type, data })\n```\n\n### 消息类型定义\n\n| 消息类型 | 方向 | 用途 |\n|---------|------|------|\n| `fileSearchResult` | 后端→前端 | 文件搜索结果 |\n| `openSettingsPanel` | 前端→后端 | 打开设置面板 |\n| `openExternal` | 前端→后端 | 打开外部链接 |\n| `toggleRemote` | 前端→后端 | 切换远程控制 |\n\n消息通过 `vscode.onMessage` 回调处理，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24`：\n\n```typescript\nconst unsubscribe = vscode.onMessage((message) => {\n if (message.type !== \"fileSearchResult\") return\n if (message.requestId === `file-search-${fileSearchCounter}`) {\n const items = message.items ?? message.paths.map((path) => ({ path, type: \"file\" }))\n // 处理结果\n }\n})\n```\n\n## 核心功能模块\n\n### 文件提及系统\n\n`useFileMention` Hook 实现了智能文件提及功能，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:9`：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n const [mentionIndex, setMentionIndex] = createSignal(0)\n \n // 文件搜索防抖处理\n let fileSearchTimer: ReturnType | undefined\n let fileSearchCounter = 0\n}\n```\n\n功能特性：\n- 实时文件搜索和建议\n- 支持 `@` 触发文件提及\n- 与 Git 状态集成\n- 拖拽文件自动注册\n\n### 斜杠命令系统\n\n`useSlashCommand` Hook 管理斜杠命令菜单，参考 `packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts:1`：\n\n```typescript\n// 可用命令列表\nconst commands = [\n {\n name: \"mode\",\n description: \"Switch the agent mode\",\n hints: [\"modes\"],\n action: () => {\n window.dispatchEvent(new CustomEvent(\"openModePicker\"))\n },\n },\n {\n name: \"variant\",\n description: \"Switch the reasoning effort\",\n hints: [\"variants\", \"reasoning\", \"thinking\"],\n action: () => {\n window.dispatchEvent(new CustomEvent(\"openVariantPicker\"))\n },\n },\n // ... 更多命令\n]\n```\n\n### 用户界面组件\n\n#### 迁移向导\n\n`MigrationWizard.tsx` 组件处理版本迁移引导，参考 `packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1`：\n\n```typescript\n// 新版本特性展示\n
\n
\n \n
{language.t(\"migration.whatsNew.features.performance.title\")}
\n
{language.t(\"migration.whatsNew.features.performance.detail\")}
\n
\n // ... 更多特性\n
\n```\n\n#### 设备授权卡片\n\n`DeviceAuthCard.tsx` 处理 OAuth 设备授权流程，参考 `packages/kilo-vscode/webview-ui/src/components/profile/DeviceAuthCard.tsx:1`：\n\n```typescript\n// 设备授权步骤\n
\n

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

\n
\n {deviceCode}\n
\n
\n```\n\n### MCP 市场集成\n\n`InstallModal.tsx` 组件实现 MCP 服务器的安装界面，参考 `packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx:1`：\n\n```typescript\n// 前置条件检查\n 0}>\n
    \n {(p) =>
  • {p}
    • }    \n
\n\n\n// 参数输入\n\n {(param) => (\n setParam(param.key, v)}\n />\n )}\n\n```\n\n## 文件操作集成\n\n### 输入提示组件\n\n`PromptInput.tsx` 处理用户输入和文件提及，参考 `packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx:1`：\n\n```typescript\n// 文件提及类型渲染\n\n {(item) => (\n
\n {item.type === \"terminal\" ? (\n <>\n \n {item.label}\n \n ) : item.type === \"git-changes\" ? (\n <>\n \n {item.label}\n \n ) : (\n <>\n \n {item.label}\n \n )}\n
\n )}\n\n```\n\n### 自动补全\n\n`autocomplete.tsx` 实现 TUI 界面的自动补全功能，参考 `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1`：\n\n```typescript\n// 文件部分处理\nif (part.type === \"file\" && part.source?.text) {\n part.source.text.start = extmarkStart\n part.source.text.end = extmarkEnd\n part.source.text.value = virtualText\n}\n\n// 更新访问频率用于排序\nif (part.type === \"file\" && part.source && part.source.type === \"file\") {\n frecency.updateFrecency(part.source.path)\n}\n```\n\n## JetBrains 扩展\n\n### 后端服务\n\n`KiloBackendAppService.kt` 是 JetBrains 扩展的后端服务：\n\n```kotlin\n// 主要职责\nclass KiloBackendAppService {\n // 会话管理\n // 与 Kilo 后端通信\n // 处理 IDE 事件\n}\n```\n\n### 工具窗口工厂\n\n`KiloToolWindowFactory.kt` 创建和管理工具窗口：\n\n```kotlin\nclass KiloToolWindowFactory : ToolWindowFactory {\n override fun createToolWindowContent(project: Project, toolWindow: ToolWindow) {\n // 创建工具窗口内容\n // 初始化通信通道\n }\n}\n```\n\n### RPC API\n\n`KiloSessionRpcApi.kt` 定义了会话 RPC 接口：\n\n```kotlin\ninterface KiloSessionRpcApi {\n // 发送消息\n // 接收响应\n // 管理会话状态\n}\n```\n\n## 配置管理\n\n### 配置优先级\n\n配置查找顺序（低优先级到高优先级）：\n\n| 优先级 | 来源 |\n|-------|------|\n| 1 | 远程已知配置 |\n| 2 | 全局配置 `~/.config/kilo/kilo.json` |\n| 3 | 环境变量 `KILO_CONFIG` |\n| 4 | 项目配置 `./kilo.json` |\n| 5 | 项目子目录 `.kilo/kilo.json` |\n| 6 | 内联环境变量 `KILO_CONFIG_CONTENT` |\n| 7 | 托管配置 |\n\n配置采用深度合并策略，后者覆盖前者。资料来源：[packages/opencode/src/kilocode/skills/kilo-config.md:1]()\n\n### 配置文件结构\n\n```yaml\n# 命令配置示例 (.kilo/command/*.md)\n---\ndescription: Run tests\nagent: code\nmodel: anthropic/claude-sonnet\nsubtask: true\n---\nRun all tests in $1 and fix failures.\n```\n\n## 状态管理\n\n### 状态类型\n\n| 状态类型 | 说明 |\n|---------|------|\n| `mentionedPaths` | 当前会话中提及的文件路径集合 |\n| `mentionQuery` | 文件搜索查询字符串 |\n| `mentionResults` | 文件搜索结果列表 |\n| `mentionIndex` | 当前选中的建议索引 |\n| `sessionID` | 当前会话标识符 |\n\n### 状态更新流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户输入\n participant H as useFileMention\n participant B as 后端\n participant S as 状态\n \n U->>H: 输入触发 @\n H->>H: setMentionQuery(query)\n H->>B: 发送文件搜索请求\n B->>H: 返回搜索结果\n H->>S: setMentionResults(results)\n U->>H: 选择建议\n H->>H: setMentionIndex(index)\n H->>H: closeMention()\n```\n\n## 国际化\n\n### 语言键命名空间\n\n| 命名空间 | 用途 |\n|---------|------|\n| `migration.*` | 迁移向导相关文本 |\n| `deviceAuth.*` | 设备授权流程 |\n| `marketplace.*` | MCP 市场界面 |\n| `ui.tool.*` | 工具显示名称 |\n| `ui.message.*` | 消息和提示 |\n\n## 总结\n\nKiloCode 的 IDE 扩展实现采用了模块化和分层架构设计，通过 WebView 嵌入、消息通信、状态管理等机制，在保持与 IDE 紧密集成的同时，确保了用户界面的流畅性和功能的可扩展性。VS Code 和 JetBrains 扩展共享相似的设计理念，但在具体实现上针对各平台特性进行了优化。\n\n---\n\n\n\n## CLI 工具与 SDK 开发\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [MCP 协议与工具集成](#mcp-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/cli/bootstrap.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/bootstrap.ts)\n- [packages/opencode/src/cli/cmd/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/agent.ts)\n- [packages/opencode/src/cli/cmd/tui/app.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx)\n- [packages/opencode/src/cli/cmd/run.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/run.ts)\n- [packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts)\n- [packages/opencode/src/plugin/loader.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/plugin/loader.ts)\n- [packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts)\n- [packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts)\n
\n\n# CLI 工具与 SDK 开发\n\n## 概述\n\nKiloCode 提供了一套完整的命令行工具和软件开发包（SDK），旨在为开发者提供灵活、模块化的代码辅助能力。该系统由以下几个核心部分组成：\n\n| 组件 | 功能描述 |\n|------|----------|\n| **OpenCode CLI** | 核心命令行工具，支持交互式 TUI 和脚本模式 |\n| **TUI 界面** | 终端用户界面，提供可视化交互体验 |\n| **Plugin 系统** | 插件加载机制，支持扩展功能 |\n| **SDK** | JavaScript/TypeScript 开发包，用于二次开发 |\n\n## CLI 架构设计\n\n### 命令行入口\n\nCLI 工具采用分层架构设计，主要入口通过 `bootstrap.ts` 完成初始化，随后根据用户输入分发到不同的命令处理器。\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[Bootstrap 初始化]\n B --> C[命令解析]\n C --> D[agent 命令]\n C --> E[run 命令]\n C --> F[TUI 模式]\n D --> G[Agent 执行器]\n E --> H[任务运行器]\n F --> I[TUI 应用]\n```\n\n### 核心命令模块\n\n#### Agent 命令\n\n`agent.ts` 负责处理 Agent 相关的操作，包括会话管理、模型选择和消息处理。该模块是 CLI 与 AI 模型交互的核心通道。\n\n#### Run 命令\n\n`run.ts` 提供非交互式的批处理能力，适用于自动化脚本和 CI/CD 场景。用户可以通过命令行参数直接指定任务和配置。\n\n#### TUI 应用\n\nTUI（Terminal User Interface）模块采用组件化设计，主要结构包括：\n\n| 组件 | 路径 | 职责 |\n|------|------|------|\n| `app.tsx` | `packages/opencode/src/cli/cmd/tui/app.tsx` | 根组件，应用状态管理 |\n| `session/index.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` | 会话界面渲染 |\n| `footer.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx` | 状态栏组件 |\n| `prompt/index.tsx` | `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` | 提示词输入组件 |\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-60]()\n\n### 消息渲染系统\n\n会话界面采用 Switch/Match 模式处理不同类型的消息部分：\n\n```typescript\nconst PART_MAPPING = {\n text: TextPart,\n tool: ToolPart,\n reasoning: ReasoningPart,\n}\n```\n\n- **TextPart**: 普通文本消息渲染\n- **ToolPart**: 工具调用结果显示\n- **ReasoningPart**: AI 推理过程展示，支持折叠显示\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:70-85]()\n\n### 状态栏组件\n\nFooter 组件显示当前会话的关键状态信息：\n\n| 状态项 | 说明 |\n|--------|------|\n| LSP 连接 | 显示已连接的 Language Server 数量 |\n| MCP 连接 | Model Context Protocol 连接状态 |\n| 索引状态 | 代码索引进度 |\n| 权限提示 | 当前会话所需的权限列表 |\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-50]()\n\n## 插件系统\n\n### 插件加载器\n\nKiloCode 采用模块化的插件架构，通过 `loader.ts` 实现动态插件加载：\n\n```mermaid\ngraph LR\n A[插件目录] --> B[Loader 扫描]\n B --> C[模块解析]\n C --> D[注册到系统]\n D --> E[运行时调用]\n```\n\n### 插件接口定义\n\n插件系统提供标准化的接口规范，定义在 `packages/plugin/src/index.ts` 中：\n\n| 接口方法 | 功能 |\n|----------|------|\n| `register()` | 注册插件，提供名称和版本 |\n| `initialize()` | 初始化插件资源 |\n| `execute()` | 执行插件核心逻辑 |\n| `cleanup()` | 清理插件资源 |\n\n资料来源：[packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts)\n\n## SDK 开发\n\n### JavaScript SDK\n\nJavaScript SDK 位于 `packages/sdk/js/src/index.ts`，提供完整的 API 接口用于集成 KiloCode 功能：\n\n```mermaid\ngraph TD\n A[JS SDK] --> B[会话管理]\n A --> C[消息发送]\n A --> D[文件操作]\n A --> E[模型配置]\n B --> F[createSession]\n C --> G[sendMessage]\n D --> H[attachFile]\n E --> I[setModel]\n```\n\n### SDK 核心功能\n\n| 功能模块 | API 方法 | 说明 |\n|----------|----------|------|\n| 会话管理 | `createSession()` | 创建新的会话实例 |\n| 消息交互 | `sendMessage()` | 发送消息并获取响应 |\n| 文件附件 | `attachFile()` | 向会话添加文件上下文 |\n| 模型配置 | `setModel()` | 设置使用的 AI 模型 |\n\n资料来源：[packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts)\n\n## 配置系统\n\n### 配置文件结构\n\n配置管理由 `config.ts` 统一处理，支持多种配置来源：\n\n| 配置源 | 优先级 | 格式 |\n|--------|--------|------|\n| 环境变量 | 最高 | `KILO_*` 前缀 |\n| 命令行参数 | 高 | `--key value` |\n| 配置文件 | 中 | `kilo.config.ts` |\n| 默认值 | 最低 | 内置默认值 |\n\n资料来源：[packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts)\n\n### 关键配置项\n\n```typescript\ninterface KiloConfig {\n model: string // 默认模型 ID\n provider: string // 模型提供者\n apiKey?: string // API 密钥\n temperature?: number // 生成温度参数\n maxTokens?: number // 最大 token 数\n}\n```\n\n## 开发指南\n\n### 本地开发环境搭建\n\n1. 克隆仓库并安装依赖\n2. 构建项目：`pnpm build`\n3. 链接本地包：`pnpm link --global`\n4. 运行 CLI：`opencode` 或 `kilo`\n\n### 调试技巧\n\n| 方法 | 说明 |\n|------|------|\n| `DEBUG=* opencode` | 启用完整调试日志 |\n| `opencode --verbose` | 显示详细执行信息 |\n| 查看 TUI 日志 | 状态栏 `/status` 命令 |\n\n### 创建自定义插件\n\n```typescript\nimport { Plugin, PluginContext } from '@kilo/plugin'\n\nexport default class MyPlugin implements Plugin {\n name = 'my-plugin'\n version = '1.0.0'\n \n register(ctx: PluginContext) {\n ctx.registerCommand({\n name: 'my-command',\n handler: async (args) => {\n // 处理逻辑\n }\n })\n }\n}\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | TypeScript | 类型安全的命令行工具 |\n| UI 框架 | Solid.js | 高性能响应式界面 |\n| TUI 渲染 | Ink/自定义 | 终端界面渲染 |\n| 构建工具 | Vite | 快速开发和打包 |\n| 包管理 | pnpm | 高效的依赖管理 |\n\n## 相关资源\n\n- 官方文档：https://kilo.ai/docs/\n- 博客公告：https://blog.kilo.ai/\n- 问题反馈：https://github.com/Kilo-Org/kilocode/issues\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Kilo-Org/kilocode\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n\n\n", "markdown_key": "kilocode", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:946087422", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/Kilo-Org/kilocode" }, { "evidence_id": "art_2fe7a231cae145eca6ce97c9a31887ae", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/Kilo-Org/kilocode#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "kilocode 说明书", "toc": [ "https://github.com/Kilo-Org/kilocode 项目说明书", "目录", "Kilo Code 简介与快速入门", "项目概述", "系统架构", "核心功能", "支持的 AI 提供商", "快速入门", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "a23fe160d66d7e95d8d7f38a45afe228736652bb", "repo_inspection_error": null, "repo_inspection_files": [ "package.json", "README.md", "packages/kilo-ui/package.json", "packages/kilo-ui/playwright.config.ts", "packages/kilo-ui/tsconfig.json", "packages/plugin/sst-env.d.ts", "packages/plugin/package.json", "packages/plugin/tsconfig.json", "packages/ui/vite.config.ts", "packages/ui/sst-env.d.ts", "packages/ui/package.json", "packages/ui/tsconfig.json", "packages/kilo-i18n/package.json", "packages/kilo-i18n/tsconfig.json", "packages/opencode/AGENTS.md", "packages/opencode/parsers-config.ts", "packages/opencode/BUN_SHELL_MIGRATION_PLAN.md", "packages/opencode/sst-env.d.ts", "packages/opencode/package.json", "packages/opencode/README.md", "packages/opencode/tsconfig.json", "packages/opencode/CHANGELOG.md", "packages/opencode/drizzle.config.ts", "packages/opencode/bunfig.toml", "packages/script/sst-env.d.ts", "packages/script/package.json", "packages/script/tsconfig.json", "packages/kilo-telemetry/package.json", "packages/kilo-telemetry/tsconfig.json", "packages/core/sst-env.d.ts", "packages/core/package.json", "packages/core/tsconfig.json", "packages/containers/README.md", "packages/containers/tsconfig.json", "packages/kilo-jetbrains/AGENTS.md", "packages/kilo-jetbrains/RELEASE_TODO.md", "packages/kilo-jetbrains/detekt.yml", "packages/kilo-jetbrains/package.json", "packages/kilo-jetbrains/README.md", "packages/kilo-jetbrains/RELEASING.md" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# @kilocode/kilo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @kilocode/kilo 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @kilocode/cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx @kilocode/cli` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx --package @kilocode/cli kilo` 证据：`packages/opencode/README.md` Claim：`clm_0007` supported 0.86\n- `npm install ai @ai-sdk/openai dotenv` 证据：`packages/kilo-docs/pages/gateway/quickstart.md` Claim：`clm_0008` unverified 0.25\n- `curl -X POST \"https://api.kilo.ai/api/gateway/chat/completions\" \\` 证据：`packages/kilo-docs/pages/gateway/quickstart.md` Claim：`clm_0009` unverified 0.25\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.kilo/skills/gh-issues/SKILL.md`, `.kilo/skills/kilocode-merge-minimizer/SKILL.md`, `.kilocode/skills/vscode-visual-regression/SKILL.md`, `.opencode/skills/effect/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/kilo-docs/pages/gateway/quickstart.md`, `packages/opencode/README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：5051\n- 重要文件覆盖：40/5051\n- 证据索引条目：80\n- 角色 / Skill 条目：7\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @kilocode/kilo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @kilocode/kilo 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @kilocode/kilo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **gh-issues**（skill）：Use when creating, triaging, or commenting on GitHub issues for the Kilo VS Code extension or JetBrains plugin via gh . Covers issue templates, project board assignment, title conventions, and required gh scopes. 激活提示：当用户任务与“gh-issues”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.kilo/skills/gh-issues/SKILL.md`\n- **kilocode-merge-minimizer**（skill）：Use when changing shared upstream-owned files, editing or reviewing kilocode change markers, or moving additive Kilo-specific behavior into Kilo-owned code to reduce future merge conflicts. 激活提示：当用户任务与“kilocode-merge-minimizer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.kilo/skills/kilocode-merge-minimizer/SKILL.md`\n- **vscode-visual-regression**（skill）：Write Storybook stories and visual regression tests for the Kilo VS Code extension webview UI 激活提示：当用户任务与“vscode-visual-regression”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.kilocode/skills/vscode-visual-regression/SKILL.md`\n- **effect**（skill）：Work with Effect v4 / effect-smol TypeScript code in this repo 激活提示：当用户任务与“effect”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.opencode/skills/effect/SKILL.md`\n- **jetbrains-ui-style**（skill）：Use when creating, modifying, or reviewing Kotlin/Swing UI code for the Kilo JetBrains plugin. Applies to dialogs, settings pages, tool windows, forms, panels, component layout, sizing, spacing, colors, borders, icons, lists, trees, popups, notifications, and IntelliJ platform UI components. 激活提示：当用户任务与“jetbrains-ui-style”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/kilo-jetbrains/.kilo/skills/jetbrains-ui-style/SKILL.md`\n- **agents-sdk**（skill）：Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks. 激活提示：当用户任务与“agents-sdk”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/opencode/test/fixture/skills/agents-sdk/SKILL.md`\n- **cloudflare**（skill）：Comprehensive Cloudflare platform skill covering Workers, Pages, storage KV, D1, R2 , AI Workers AI, Vectorize, Agents SDK , networking Tunnel, Spectrum , security WAF, DDoS , and infrastructure-as-code Terraform, Pulumi . Use for any Cloudflare development task. 激活提示：当用户任务与“cloudflare”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/opencode/test/fixture/skills/cloudflare/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Changesets**（documentation）：This directory contains changeset files used to track changes for the next release. 证据：`.changeset/README.md`\n- **AGENTS.md**（documentation）：Kilo CLI is an open source AI coding agent that generates code from natural language, automates tasks, and supports 500+ AI models. 证据：`AGENTS.md`\n- **Quick Links**（documentation）：Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent. 证据：`README.md`\n- **Kilo GitHub Action**（documentation）：A GitHub Action that integrates Kilo AI https://kilo.ai directly into your GitHub workflow. 证据：`github/README.md`\n- **Locale Glossaries**（documentation）：Use this folder for locale-specific translation guidance that supplements .opencode/agent/translator.md . 证据：`.opencode/glossary/README.md`\n- **CI containers**（documentation）：Prebuilt images intended to speed up GitHub Actions jobs by baking in large, slow-to-install dependencies. These are designed for Linux jobs that can use job.container in workflows. 证据：`packages/containers/README.md`\n- **Project Overview**（documentation）：This is the Kilo Code documentation site. Kilo Code is the leading open source agentic engineering platform. 证据：`packages/kilo-docs/AGENTS.md`\n- **Using Google Gemini With Kilo Code**（documentation）：Kilo Code supports Google's Gemini family of models through the Google AI Gemini API. 证据：`packages/kilo-docs/pages/ai-providers/gemini.md`\n- **@kilocode/kilo-gateway**（documentation）：Unified Kilo Gateway package for OpenCode providing authentication, AI provider integration, and API access. 证据：`packages/kilo-gateway/README.md`\n- **AGENTS.md — Kilo JetBrains Plugin**（documentation）：- Use packages/kilo-jetbrains/.kilo/skills/jetbrains-ui-style/SKILL.md when creating, modifying, or reviewing Kotlin/Swing UI code for this plugin. It covers IntelliJ UI conventions, platform components, theme-aware colors/fonts, spacing, manual Swing vs Kotlin UI DSL, session transcript styling, and retained Swing component-state patterns for hover/expand/update flows. 证据：`packages/kilo-jetbrains/AGENTS.md`\n- **Kilo JetBrains**（documentation）：AI coding agent plugin for JetBrains IDEs. 证据：`packages/kilo-jetbrains/README.md`\n- **AGENTS.md**（documentation）：This file provides guidance to agents when working with code in this repository. 证据：`packages/kilo-vscode/AGENTS.md`\n- **🚀 Kilo**（documentation）：Kilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent. 证据：`packages/kilo-vscode/README.md`\n- **opencode agent guidelines**（documentation）：- Run : bun run --conditions=browser ./src/index.ts - Test : bun test all tests or bun test test/tool/tool.test.ts single test - Typecheck : bun run typecheck runs tsgo --noEmit 证据：`packages/opencode/AGENTS.md`\n- **Kilo Code CLI**（documentation）：The AI coding agent built for the terminal. Generate code from natural language, automate tasks, and run terminal commands -- powered by 500+ AI models. 证据：`packages/opencode/README.md`\n- **ACP Agent Client Protocol Implementation**（documentation）：ACP Agent Client Protocol Implementation 证据：`packages/opencode/src/acp/README.md`\n- **Readme**（documentation）：This is a plugin to simulate a remote environment locally. Add this to .opencode/opencode.jsonc : 证据：`packages/opencode/src/control-plane/dev/README.md`\n- **Readme**（documentation）：This is a temporary package used primarily for GitHub Copilot compatibility. 证据：`packages/opencode/src/provider/sdk/copilot/README.md`\n- **Instance Route Parity**（documentation）：This directory contains the legacy Hono instance routes and the experimental Effect HttpApi implementation under httpapi/ . Keep them behaviorally aligned. 证据：`packages/opencode/src/server/routes/instance/AGENTS.md`\n- **HttpApi Route Patterns**（documentation）：Use HttpApiBuilder.group ... for normal HTTP endpoints, including streaming HTTP responses such as server-sent events. Handlers should yield stable services once while building the handler layer, then close over those services in endpoint implementations. 证据：`packages/opencode/src/server/routes/instance/httpapi/AGENTS.md`\n- **Goal**（documentation）：tl;dr All of these APIs work, are properly type-checked, and are sync events are backwards compatible with Bus : 证据：`packages/opencode/src/sync/README.md`\n- **Upstream Merge Automation**（documentation）：Scripts for automating the merge of upstream opencode changes into Kilo. 证据：`script/upstream/README.md`\n- **opencode VS Code Extension**（documentation）：A Visual Studio Code extension that integrates opencode https://opencode.ai directly into your development workflow. 证据：`sdks/vscode/README.md`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/kilo\", \"description\": \"AI-powered development tool\", \"private\": true, \"type\": \"module\", \"packageManager\": \"bun@1.3.13\", \"scripts\": { \"dev\": \"bun run --cwd packages/opencode --conditions=browser src/index.ts\", \"dev-setup\": \"bun run --cwd packages/opencode --conditions=browser src/index.ts dev-setup\", \"dev:storybook\": \"bun --cwd packages/storybook storybook\", \"lint\": \"oxlint\", \"typecheck\": \"bun turbo typecheck\", \"postinstall\": \"bun run --cwd packages/opencode fix-node-pty && bun run script/setup-git.ts\", \"prepare\": \"husky\", \"random\": \"echo 'Random script'\", \"hello\": \"echo 'Hello World!'\", \"test\": \"echo 'do not run te… 证据：`package.json`\n- **Contributing to Kilo CLI**（documentation）：See the Documentation for details on contributing https://kilo.ai/docs/contributing . 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"version\": \"7.3.0\", \"name\": \"@opencode-ai/core\", \"type\": \"module\", \"license\": \"MIT\", \"private\": true, \"scripts\": { \"test\": \"bun test\", \"test:ci\": \"mkdir -p .artifacts/unit && bun test --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml\", \"typecheck\": \"tsgo --noEmit\" }, \"bin\": { \"opencode\": \"./bin/opencode\" }, \"exports\": { \"./ \": \"./src/ .ts\" }, \"imports\": {}, \"devDependencies\": { \"@tsconfig/bun\": \"catalog:\", \"@types/bun\": \"catalog:\", \"@types/cross-spawn\": \"catalog:\", \"@types/npm-package-arg\": \"6.1.4\", \"@types/npmcli arborist\": \"6.3.3\", \"@types/semver\": \"catalog:\" }, \"dependencies\": { \"@effect/opentelemetry\":… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@kilocode/kilo-docs\", \"version\": \"7.3.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev --webpack --port 3002\", \"build\": \"next build --webpack\", \"start\": \"next start\", \"test\": \"vitest run\" }, \"dependencies\": { \"@docsearch/css\": \"^4\", \"@docsearch/js\": \"^4\", \"@markdoc/markdoc\": \"^0.5.4\", \"@markdoc/next.js\": \"^0.5.0\", \"@vscode/codicons\": \"^0.0.44\", \"@xyflow/react\": \"12.10.2\", \"js-yaml\": \"^4.1.0\", \"mermaid\": \"11.15.0\", \"next\": \"^16.1.5\", \"posthog-js\": \"^1.335.3\", \"prismjs\": \"^1.30.0\", \"react\": \"^19.2.4\", \"react-dom\": \"^19.2.4\" }, \"devDependencies\": { \"@tailwindcss/postcss\": \"^4.1.18\", \"@types/node\": \"^25.0.10\", \"@types/react\": \"^19.2.9\", \"@types/react-dom\": \"^19.2.3\", \"autoprefixer\"… 证据：`packages/kilo-docs/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/kilo-gateway\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"description\": \"Unified Kilo Gateway package for OpenCode - authentication, provider, and API integration\", \"keywords\": \"kilo\", \"kilocode\", \"opencode\", \"auth\", \"plugin\", \"provider\", \"ai\", \"llm\" , \"exports\": { \".\": \"./src/index.ts\", \"./tui\": \"./src/tui.ts\" }, \"files\": \"dist\" , \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"build\": \"tsc\" }, \"dependencies\": { \"@kilocode/plugin\": \"workspace: \", \"@kilocode/sdk\": \"workspace: \", \"@ai-sdk/alibaba\": \"1.0.17\", \"@ai-sdk/anthropic\": \"3.0.71\", \"@ai-sdk/openai\": \"3.0.48\", \"@ai-sdk/openai-compatible\": \"2.0.37\", \"… 证据：`packages/kilo-gateway/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/kilo-i18n\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"description\": \"Kilo-specific i18n translations and overrides\", \"exports\": { \"./ \": \"./src/ .ts\" }, \"scripts\": { \"typecheck\": \"tsgo --noEmit\" }, \"devDependencies\": { \"@tsconfig/node22\": \"catalog:\", \"@types/bun\": \"catalog:\", \"typescript\": \"catalog:\", \"@typescript/native-preview\": \"catalog:\" } } 证据：`packages/kilo-i18n/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/kilo-indexing\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"description\": \"Standalone indexing engine and host helpers for Kilo Code\", \"keywords\": \"kilo\", \"kilocode\", \"indexing\", \"plugin\", \"search\", \"embeddings\" , \"exports\": { \".\": \"./src/index.ts\", \"./config\": \"./src/config.ts\", \"./detect\": \"./src/detect.ts\", \"./embedding-models\": \"./src/kilo-embedding-models.ts\", \"./engine\": \"./src/indexing/index.ts\", \"./server\": \"./src/server/routes.ts\", \"./status\": \"./src/status.ts\" }, \"files\": \"dist\", \"src\" , \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"build\": \"tsc\", \"test\": \"bun test --timeout 30000\" }, \"dependen… 证据：`packages/kilo-indexing/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@kilocode/kilo-jetbrains\", \"private\": true, \"scripts\": { \"build\": \"bun script/build.ts\", \"build:production\": \"bun script/build.ts --production\" } } 证据：`packages/kilo-jetbrains/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/kilo-telemetry\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"description\": \"Telemetry for Kilo CLI - PostHog analytics integration\", \"exports\": { \".\": \"./src/index.ts\" }, \"files\": \"dist\" , \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"build\": \"tsc\", \"test\": \"bun test\" }, \"dependencies\": { \"posthog-node\": \"4.4.0\", \"@kilocode/kilo-gateway\": \"workspace: \" }, \"devDependencies\": { \"@tsconfig/bun\": \"catalog:\", \"@types/bun\": \"catalog:\", \"typescript\": \"catalog:\", \"@typescript/native-preview\": \"catalog:\" } } 证据：`packages/kilo-telemetry/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@kilocode/kilo-ui\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"exports\": { \"./font\": \"./src/components/font.tsx\", \"./button\": \"./src/components/button.tsx\", \"./code\": \"./src/components/code.tsx\", \"./diff\": \"./src/components/diff.tsx\", \"./diff-ssr\": \"./src/components/diff-ssr.tsx\", \"./dialog\": \"./src/components/dialog.tsx\", \"./icon\": \"./src/components/icon.tsx\", \"./icon-button\": \"./src/components/icon-button.tsx\", \"./list\": \"./src/components/list.tsx\", \"./provider-icon\": \"./src/components/provider-icon.tsx\", \"./spinner\": \"./src/components/spinner.tsx\", \"./text-field\": \"./src/components/text-field.tsx\", \"./toast\": \"./src/components/toast.tsx\", \"./tooltip\": \"./src/comp… 证据：`packages/kilo-ui/package.json`\n- **Package**（package_manifest）：{ \"name\": \"kilo-code\", \"displayName\": \"Kilo Code: AI Coding Agent, Copilot, and Autocomplete\", \"description\": \"Open Source AI coding agent that generates code from natural language, automates tasks, and runs terminal commands. Features inline autocomplete, browser automation, automated refactoring, and custom modes for planning, coding, and debugging. Supports 500+ AI models including Claude Anthropic , Gemini, Grok, GPT, Codex and GLM.\", \"version\": \"7.3.0\", \"icon\": \"assets/icons/logo-outline-black.png\", \"galleryBanner\": { \"color\": \" FFFFFF\", \"theme\": \"light\" }, \"publisher\": \"kilocode\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Kilo-Org/kilocode.git\", \"directory\": \"packages/… 证据：`packages/kilo-vscode/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"version\": \"7.3.0\", \"name\": \"@kilocode/cli\", \"type\": \"module\", \"license\": \"MIT\", \"private\": true, \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"test\": \"bun run script/test-runner.ts\", \"test:ci\": \"bun run script/test-runner.ts --ci\", \"build\": \"bun run script/build.ts\", \"fix-node-pty\": \"bun run script/fix-node-pty.ts\", \"upgrade-opentui\": \"bun run script/upgrade-opentui.ts\", \"dev\": \"bun run --conditions=browser ./src/index.ts\", \"dev:temporary\": \"bun run --conditions=browser ./src/temporary.ts\", \"db\": \"bun drizzle-kit\" }, \"bin\": { \"kilo\": \"./bin/kilo\", \"kilocode\": \"./bin/kilo\" }, \"exports\": { \"./ \": \"./src/ .ts\" }, \"imports\": { \" db\": { \"b… 证据：`packages/opencode/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/plugin\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"build\": \"tsc\" }, \"exports\": { \".\": \"./src/index.ts\", \"./tool\": \"./src/tool.ts\", \"./tui\": \"./src/tui.ts\" }, \"files\": \"dist\" , \"dependencies\": { \"@kilocode/sdk\": \"workspace: \", \"effect\": \"catalog:\", \"zod\": \"catalog:\" }, \"peerDependencies\": { \"@opentui/core\": \" =0.2.2\", \"@opentui/solid\": \" =0.2.2\" }, \"peerDependenciesMeta\": { \"@opentui/core\": { \"optional\": true }, \"@opentui/solid\": { \"optional\": true } }, \"devDependencies\": { \"@opentui/core\": \"catalog:\", \"@opentui/solid\": \"catalog:\", \"@tsconfig/node22\": \"catalo… 证据：`packages/plugin/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package\", \"name\": \"@opencode-ai/script\", \"license\": \"MIT\", \"dependencies\": { \"semver\": \"^7.6.3\" }, \"devDependencies\": { \"@types/bun\": \"catalog:\", \"@types/semver\": \"^7.5.8\" }, \"exports\": { \".\": \"./src/index.ts\" }, \"version\": \"7.3.0\", \"peerDependencies\": {} } 证据：`packages/script/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@kilocode/sdk\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"scripts\": { \"typecheck\": \"tsgo --noEmit\", \"build\": \"bun ./script/build.ts\" }, \"exports\": { \".\": \"./src/index.ts\", \"./client\": \"./src/client.ts\", \"./server\": \"./src/server.ts\", \"./v2\": \"./src/v2/index.ts\", \"./v2/client\": \"./src/v2/client.ts\", \"./v2/gen/client\": \"./src/v2/gen/client/index.ts\", \"./v2/server\": \"./src/v2/server.ts\" }, \"files\": \"dist\" , \"devDependencies\": { \"@hey-api/openapi-ts\": \"0.90.10\", \"@tsconfig/node22\": \"catalog:\", \"@types/cross-spawn\": \"catalog:\", \"@types/node\": \"catalog:\", \"@typescript/native-preview\": \"catalog:\", \"typescript\": \"cata… 证据：`packages/sdk/js/package.json`\n- **Package**（package_manifest）：{ \"$schema\": \"https://json.schemastore.org/package.json\", \"name\": \"@opencode-ai/storybook\", \"private\": true, \"type\": \"module\", \"scripts\": { \"storybook\": \"storybook dev -p 6006\", \"build\": \"storybook build\" }, \"devDependencies\": { \"@tailwindcss/vite\": \"catalog:\", \"@opencode-ai/ui\": \"workspace: \", \"@solidjs/meta\": \"catalog:\", \"@storybook/addon-a11y\": \"^10.2.13\", \"@storybook/addon-docs\": \"^10.2.13\", \"@storybook/addon-links\": \"^10.2.13\", \"@storybook/addon-onboarding\": \"^10.2.13\", \"@storybook/addon-vitest\": \"^10.2.13\", \"@tsconfig/node22\": \"catalog:\", \"@types/node\": \"catalog:\", \"@types/react\": \"18.0.25\", \"react\": \"18.2.0\", \"solid-js\": \"catalog:\", \"storybook\": \"^10.2.13\", \"storybook-solidjs-vite\":… 证据：`packages/storybook/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@opencode-ai/ui\", \"version\": \"7.3.0\", \"type\": \"module\", \"license\": \"MIT\", \"exports\": { \"./package.json\": \"./package.json\", \"./ \": \"./src/components/ .tsx\", \"./i18n/ \": \"./src/i18n/ .ts\", \"./pierre\": \"./src/pierre/index.ts\", \"./pierre/ \": \"./src/pierre/ .ts\", \"./hooks\": \"./src/hooks/index.ts\", \"./context\": \"./src/context/index.ts\", \"./context/ \": \"./src/context/ .tsx\", \"./styles\": \"./src/styles/index.css\", \"./styles/tailwind\": \"./src/styles/tailwind/index.css\", \"./theme\": \"./src/theme/index.ts\", \"./theme/ \": \"./src/theme/ .ts\", \"./theme/context\": \"./src/theme/context.tsx\", \"./icons/provider\": \"./src/components/provider-icons/types.ts\", \"./icons/file-type\": \"./src/components/file-i… 证据：`packages/ui/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@kilocode/upstream-merge\", \"version\": \"7.3.0\", \"private\": true, \"type\": \"module\", \"description\": \"Scripts for automating upstream opencode merges into Kilo\", \"scripts\": { \"merge\": \"bun run merge.ts\", \"merge:dry-run\": \"bun run merge.ts --dry-run\", \"merge:report\": \"bun run merge.ts --report-only\", \"transform:names\": \"bun run transforms/package-names.ts\", \"transform:imports\": \"bun run codemods/transform-imports.ts\", \"transform:strings\": \"bun run codemods/transform-strings.ts\", \"transform:all\": \"bun run transforms/package-names.ts && bun run codemods/transform-imports.ts && bun run codemods/transform-strings.ts\", \"versions\": \"bun run transforms/preserve-versions.ts\", \"fix:markers\": \"… 证据：`script/upstream/package.json`\n- **Package**（package_manifest）：{ \"name\": \"opencode\", \"displayName\": \"opencode\", \"description\": \"opencode for VS Code\", \"version\": \"7.3.0\", \"publisher\": \"sst-dev\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Kilo-Org/kilocode\" }, \"license\": \"MIT\", \"icon\": \"images/icon.png\", \"galleryBanner\": { \"color\": \" 000000\", \"theme\": \"dark\" }, \"engines\": { \"vscode\": \"^1.94.0\" }, \"categories\": \"Other\" , \"activationEvents\": , \"main\": \"./dist/extension.js\", \"contributes\": { \"commands\": { \"command\": \"opencode.openTerminal\", \"title\": \"Open opencode\", \"icon\": { \"light\": \"images/button-dark.svg\", \"dark\": \"images/button-light.svg\" } }, { \"command\": \"opencode.openNewTerminal\", \"title\": \"Open opencode in new tab\", \"icon\": { \"light… 证据：`sdks/vscode/package.json`\n- **GitHub Issues**（skill_instruction）：Use this skill whenever you create or manage a GitHub issue with gh for either the VS Code extension or the JetBrains plugin. 证据：`.kilo/skills/gh-issues/SKILL.md`\n- **Kilo Merge Minimizer**（skill_instruction）：Use this skill whenever a normal development task touches shared upstream-owned code and includes Kilo-specific behavior, especially for marker cleanup, extraction work, or kilocode change annotations. 证据：`.kilo/skills/kilocode-merge-minimizer/SKILL.md`\n- **Architecture**（skill_instruction）：Use this skill when the user asks you to add visual regression tests, screenshot tests, or Storybook stories for components in packages/kilo-vscode/ . 证据：`.kilocode/skills/vscode-visual-regression/SKILL.md`\n- **Effect**（skill_instruction）：This codebase uses Effect for typed, composable TypeScript services, schemas, and workflows. 证据：`.opencode/skills/effect/SKILL.md`\n- **JetBrains UI Style**（skill_instruction）：Use this skill whenever creating, modifying, or reviewing UI code in packages/kilo-jetbrains . 证据：`packages/kilo-jetbrains/.kilo/skills/jetbrains-ui-style/SKILL.md`\n- **Test Fixtures Guide**（documentation）：The tmpdir function in fixture/fixture.ts creates temporary directories for tests with automatic cleanup. 证据：`packages/opencode/test/AGENTS.md`\n- **Server Test Guide**（documentation）：Use these patterns for server and HttpApi middleware tests in this directory. 证据：`packages/opencode/test/server/AGENTS.md`\n- **Package**（package_manifest）：{ \"type\": \"module\" } 证据：`packages/kilo-vscode/tests/package.json`\n- **License**（source_file）：Copyright c 2025 Kilo Code Copyright c 2025 opencode 证据：`LICENSE`\n- **Cloudflare Agents SDK**（skill_instruction）：STOP. Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task. 证据：`packages/opencode/test/fixture/skills/agents-sdk/SKILL.md`\n- **Cloudflare Platform Skill**（skill_instruction）：Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references. 证据：`packages/opencode/test/fixture/skills/cloudflare/SKILL.md`\n- **License**（source_file）：Copyright c 2025 Kilo Code Copyright c 2025 opencode 证据：`packages/kilo-vscode/LICENSE`\n- **Dev Container Persistence**（documentation）：When using Kilo Code in development containers VS Code Dev Containers, GitHub Codespaces, etc. , your threads and settings can persist across container rebuilds by properly configuring volume mounts. 证据：`packages/kilo-docs/docs/getting-started/devcontainer-persistence.md`\n- **Migrating from Cline to Kilo**（documentation）：A practical guide for developers switching from Cline to Kilo. 证据：`packages/kilo-docs/docs/getting-started/switching-from-cline.md`\n- **MCP Servers Sub-Tab Parity**（documentation）：The legacy MCP Servers sub-tab 842 lines had full server lifecycle management. The new sub-tab supports viewing, removing, and toggling servers with live connection status. 证据：`packages/kilo-vscode/docs/agent-behaviour/mcp-server-creation.md`\n- **Modes / Agents Sub-Tab Parity**（documentation）：The legacy \"Modes\" sub-tab was a 1794-line component with comprehensive mode management. The new \"Agents\" sub-tab now covers core CRUD create, edit, delete after PR 7225 but is still missing several legacy features. 证据：`packages/kilo-vscode/docs/agent-behaviour/modes-subtab-parity.md`\n- **Rules & Workflows Sub-Tabs Parity**（documentation）：The legacy extension had feature-complete Rules and Workflows sub-tabs with toggle lists, file creation, and global/workspace separation. The new extension has a simpler Rules sub-tab and a stub Workflows sub-tab. 证据：`packages/kilo-vscode/docs/agent-behaviour/rules-workflows-subtab-parity.md`\n- **Browser Session Controls**（documentation）：- In-chat browser session controls start/stop/navigate - Action replay and control buttons - Screenshot viewing within chat messages - Dedicated browser tool rendering currently falls through to generic MCP tool display 证据：`packages/kilo-vscode/docs/chat-ui-features/browser-session-controls.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Kilo Code 简介与快速入门**：importance `high`\n - source_paths: README.md, packages/opencode/README.md, packages/kilo-vscode/README.md, packages/kilo-vscode/package.json\n- **项目结构与包组织**：importance `high`\n - source_paths: packages/opencode/src/index.ts, packages/kilo-vscode/src/extension.ts, packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendAppService.kt, packages/kilo-gateway/src/index.ts, packages/kilo-indexing/src/index.ts\n- **系统架构设计**：importance `high`\n - source_paths: packages/opencode/src/server/server.ts, packages/opencode/src/server/adapter.ts, packages/opencode/src/server/routes/instance/httpapi/server.ts, packages/opencode/src/session/session.ts, packages/opencode/src/provider/provider.ts\n- **Agent 核心系统**：importance `high`\n - source_paths: packages/opencode/src/agent/agent.ts, packages/opencode/src/session/session.ts, packages/opencode/src/session/prompt.ts, packages/opencode/src/session/processor.ts, packages/opencode/src/session/llm.ts\n- **自动补全系统 (FIM)**：importance `high`\n - source_paths: packages/kilo-vscode/src/services/autocomplete/classic-auto-complete/AutocompleteInlineCompletionProvider.ts, packages/kilo-vscode/src/services/autocomplete/classic-auto-complete/FillInTheMiddle.ts, packages/kilo-vscode/src/services/autocomplete/continuedev/core/autocomplete/context/ContextRetrievalService.ts, packages/kilo-vscode/src/services/autocomplete/continuedev/core/autocomplete/templating/AutocompleteTemplate.ts, packages/kilo-vscode/src/services/autocomplete/continuedev/core/autocomplete/postprocessing/index.ts\n- **Agent Manager 工作流管理**：importance `high`\n - source_paths: packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts, packages/kilo-vscode/src/agent-manager/WorktreeManager.ts, packages/kilo-vscode/src/agent-manager/run/manager.ts, packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts, packages/kilo-vscode/src/agent-manager/GitOps.ts\n- **MCP 协议与工具集成**：importance `high`\n - source_paths: packages/opencode/src/mcp/index.ts, packages/opencode/src/tool/registry.ts, packages/opencode/src/mcp/oauth-provider.ts, packages/opencode/src/mcp/auth.ts, packages/opencode/src/tool/bash.ts\n- **代码索引与语义搜索**：importance `medium`\n - source_paths: packages/kilo-indexing/src/indexing/index.ts, packages/kilo-indexing/src/indexing/manager.ts, packages/kilo-indexing/src/indexing/orchestrator.ts, packages/kilo-indexing/src/tree-sitter/index.ts, packages/kilo-indexing/src/tree-sitter/languageParser.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a23fe160d66d7e95d8d7f38a45afe228736652bb`\n- inspected_files: `package.json`, `README.md`, `packages/kilo-ui/package.json`, `packages/kilo-ui/playwright.config.ts`, `packages/kilo-ui/tsconfig.json`, `packages/plugin/sst-env.d.ts`, `packages/plugin/package.json`, `packages/plugin/tsconfig.json`, `packages/ui/vite.config.ts`, `packages/ui/sst-env.d.ts`, `packages/ui/package.json`, `packages/ui/tsconfig.json`, `packages/kilo-i18n/package.json`, `packages/kilo-i18n/tsconfig.json`, `packages/opencode/AGENTS.md`, `packages/opencode/parsers-config.ts`, `packages/opencode/BUN_SHELL_MIGRATION_PLAN.md`, `packages/opencode/sst-env.d.ts`, `packages/opencode/package.json`, `packages/opencode/README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n- 当前没有项目专属踩坑日志。宿主 AI 遇到安装、运行、权限、能力边界问题时，必须回到证据来源，不得自行补全。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Kilo-Org/kilocode\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 暂无项目专属踩坑日志；首次试用仍按隔离验证处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/Kilo-Org/kilocode 项目说明书\n\n生成时间：2026-05-16 18:16:41 UTC\n\n## 目录\n\n- [Kilo Code 简介与快速入门](#introduction)\n- [项目结构与包组织](#project-structure)\n- [系统架构设计](#system-architecture)\n- [Agent 核心系统](#agent-system)\n- [自动补全系统 (FIM)](#autocomplete-system)\n- [Agent Manager 工作流管理](#agent-manager)\n- [MCP 协议与工具集成](#mcp-integration)\n- [代码索引与语义搜索](#indexing-system)\n- [IDE 扩展实现](#ide-extensions)\n- [CLI 工具与 SDK 开发](#cli-and-sdk)\n\n\n\n## Kilo Code 简介与快速入门\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [IDE 扩展实现](#ide-extensions)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md)\n- [packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n- [packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md)\n- [packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json)\n- [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)\n- [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)\n- [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)\n
\n\n# Kilo Code 简介与快速入门\n\n## 项目概述\n\nKilo Code 是一个现代化的人工智能辅助编程工具，通过集成多种语言模型和开发工具，为开发者提供智能化的代码编写、理解和编辑体验。该项目采用多平台架构，支持命令行界面（CLI）和 VS Code 扩展两种主要交互方式。\n\nKilo Code 的核心设计理念是将强大的人工智能能力与开发者的日常工作流程无缝结合，提供快速、准确且上下文感知的代码协助。系统支持多种 AI 提供商，包括 OpenAI、Anthropic、Google、Mistral、Moonshot 等主流模型服务。\n\n资料来源：[README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md)\n\n## 系统架构\n\nKilo Code 采用模块化设计，主要由以下核心包组成：\n\n| 包名 | 功能描述 | 技术栈 |\n|------|---------|--------|\n| `packages/opencode` | 命令行工具核心，提供 TUI 界面 | TypeScript/Node.js |\n| `packages/kilo-vscode` | VS Code 扩展，提供图形化界面 | TypeScript/React |\n| `packages/kilo-ui` | UI 组件库 | Solid.js |\n| `packages/ui` | 通用 UI 组件 | Solid.js |\n\n```mermaid\ngraph TD\n A[用户交互层] --> B[CLI TUI 界面]\n A --> C[VS Code 扩展]\n B --> D[opencode 核心引擎]\n C --> E[Webview UI]\n E --> D\n D --> F[AI 模型层]\n F --> G[MCP 服务]\n F --> H[LSP 服务]\n D --> I[文件索引系统]\n G --> J[外部工具集成]\n```\n\n### CLI 架构 (opencode)\n\n命令行工具位于 `packages/opencode` 目录，采用 TUI（文本用户界面）架构。核心模块包括：\n\n- **会话管理** (`routes/session/`): 处理 AI 对话和消息显示\n- **命令系统** (`cmd/`): 实现各种交互命令\n- **提示系统** (`prompt/`): 管理输入和自动完成\n\nCLI 工具支持多种模式切换，包括命令模式、Shell 模式和聊天模式，用户可以通过快捷键在模式间快速切换。\n\n资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n\n### VS Code 扩展架构\n\nVS Code 扩展位于 `packages/kilo-vscode` 目录，分为后端和前端两部分：\n\n- **后端** (`src/`): 处理与核心引擎的通信\n- **前端 Webview** (`webview-ui/`): 使用 Solid.js 构建的图形界面\n\nWebview UI 包含多个核心组件：\n\n- **迁移向导** (`migration/MigrationWizard.tsx`): 引导用户完成版本升级\n- **市场安装** (`marketplace/InstallModal.tsx`): 插件和工具的安装管理\n- **提示输入** (`chat/PromptInput.tsx`): 聊天输入和文件提及功能\n- **文件引用** (`hooks/useFileMention.ts`): 文件拖拽和引用解析\n\n资料来源：[packages/kilo-vscode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/README.md)\n\n## 核心功能\n\n### 智能对话与代码生成\n\nKilo Code 提供完整的对话式编程体验，支持：\n\n- **多轮对话**: 维护对话上下文，支持复杂任务的分解和逐步解决\n- **代码生成**: 根据自然语言描述生成代码片段\n- **代码解释**: 解释现有代码的功能和逻辑\n- **错误修复**: 分析错误信息并提供修复建议\n\n消息系统支持多种内容类型，包括普通文本、工具调用、推理过程（reasoning）和文件变更。\n\n资料来源：[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)\n\n### 文件引用与附件\n\nKilo Code 支持通过 `@` 符号引用文件，实现以下功能：\n\n| 功能 | 说明 | 支持类型 |\n|------|------|----------|\n| 文件提及 | 在对话中引用项目文件 | 文件、文件夹 |\n| 终端引用 | 引用终端输出内容 | 终端 |\n| Git 变更引用 | 引用 Git 变更信息 | 分支、差异 |\n\n文件引用系统会自动搜索匹配的文件路径，并在用户输入时提供自动完成建议。拖拽文件到输入区域也会自动创建引用。\n\n资料来源：[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)\n\n### 工具系统\n\nKilo Code 内置强大的工具系统，支持以下核心工具：\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `Read` | 读取文件内容 |\n| `Write` | 写入或创建文件 |\n| `Edit` | 编辑文件指定区域 |\n| `Grep` | 搜索文件内容 |\n| `TodoWrite` | 创建和管理待办事项 |\n| `ApplyPatch` | 应用代码补丁 |\n\n工具输出支持差异视图（Diff View），清晰展示添加、删除和修改的内容。\n\n资料来源：[packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx)\n\n### MCP 集成\n\nMCP（Model Context Protocol）支持使 Kilo Code 能够与外部工具和服务进行深度集成：\n\n- **OAuth 认证**: 安全处理第三方服务的授权流程\n- **实时状态**: 显示 MCP 连接状态和错误信息\n- **工具调用**: 通过 MCP 协议调用外部工具\n\n状态栏实时显示 MCP 连接状态，绿色圆点表示正常连接，红色圆点表示连接错误。\n\n资料来源：[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)\n\n### LSP 支持\n\nKilo Code 集成 Language Server Protocol，提供：\n\n- 代码补全建议\n- 语法检查和错误提示\n- 跳转到定义\n- 查找引用\n\n状态栏显示当前活动的 LSP 服务器数量。\n\n资料来源：[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)\n\n### 推理过程显示\n\n对于支持推理的模型，Kilo Code 可以显示 AI 的思考过程：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[模型推理]\n B --> C[推理内容]\n B --> D[最终回答]\n C -->|过滤 [REDACTED]| E[显示思考]\n D --> F[工具调用]\n```\n\n推理内容会进行过滤处理，去除 OpenRouter 等服务加密的推理数据（显示为 `[REDACTED]`）。\n\n资料来源：[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)\n\n## 支持的 AI 提供商\n\nKilo Code 支持众多 AI 模型提供商，形成完整的生态系统：\n\n| 提供商 | 代码标识 | 说明 |\n|--------|----------|------|\n| OpenAI | `openai` | GPT 系列模型 |\n| Anthropic | `anthropic` | Claude 系列模型 |\n| Google | `google` | Gemini 系列模型 |\n| Mistral | `mistral` | Mistral AI 模型 |\n| Moonshot | `moonshotai` | Kimi 系列模型 |\n| MiniMax | `minimax` | 混元系列模型 |\n| OpenRouter | `openrouter` | 多模型聚合 |\n| Ollama | `ollama-cloud` | 本地模型 |\n| Groq | `groq` | 高速推理 |\n| TogetherAI | `togetherai` | 开源模型 |\n| HuggingFace | `huggingface` | 推理端点 |\n| LM Studio | `lmstudio` | 本地部署 |\n\n资料来源：[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)\n\n## 快速入门\n\n### 安装方式\n\n#### VS Code 扩展安装\n\n1. 打开 VS Code\n2. 进入扩展市场，搜索 \"Kilo\"\n3. 点击安装按钮\n4. 安装完成后，点击侧边栏的 Kilo 图标开始使用\n\n扩展版本信息可在 `package.json` 中查看：\n\n```json\n{\n \"name\": \"kilo-vscode\",\n \"version\": \"1.x.x\",\n \"displayName\": \"Kilo\"\n}\n```\n\n资料来源：[packages/kilo-vscode/package.json](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/package.json)\n\n#### CLI 安装\n\n```bash\n# 使用 npm 安装\nnpm install -g @kilocode/opencode\n\n# 或使用其他包管理器\nbrew install kilo-ai/tap/kilocode\n```\n\n### 首次配置\n\n首次启动后，系统会显示迁移向导，引导用户了解新版本特性：\n\n1. **性能优化**: 了解新版本的性能改进\n2. **界面更新**: 查看新的用户界面设计\n3. **Agent 管理器**: 了解增强的多 Agent 支持\n4. **基础架构**: 查看底层技术升级\n\n资料来源：[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)\n\n### 基本使用\n\n#### CLI 模式\n\n```bash\n# 启动交互式会话\nopencode\n\n# 指定模型\nopencode --model gpt-4\n\n# 查看帮助\nopencode --help\n```\n\n#### VS Code 扩展模式\n\n1. 打开命令面板 (`Ctrl+Shift+P` / `Cmd+Shift+P`)\n2. 输入 \"Kilo\" 查找相关命令\n3. 选择 \"Kilo: 新建对话\" 开始会话\n4. 在输入框中输入问题或指令\n\n### 文件操作\n\n#### 在对话中引用文件\n\n```\n@filename.py # 引用单个文件\n@src/ # 引用整个目录\n@README.md:10-20 # 引用文件特定行\n```\n\n#### 拖拽添加\n\n直接将文件从资源管理器拖拽到聊天输入区域，系统会自动创建文件引用。\n\n### 快捷键\n\n| 操作 | Windows/Linux | macOS |\n|------|---------------|-------|\n| 新建对话 | `Ctrl+Shift+K` | `Cmd+Shift+K` |\n| 打开命令列表 | `Ctrl+/` | `Cmd+/` |\n| 引用文件 | `@` | `@` |\n| 斜杠命令 | `/` | `/` |\n\n资料来源：[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)\n\n## 认证与授权\n\n### OAuth 回调处理\n\nKilo Code 使用 OAuth 2.0 进行第三方服务认证：\n\n```mermaid\nsequenceDiagram\n 用户->>Kilo Code: 请求授权\n Kilo Code->>第三方服务: 发起 OAuth 请求\n 第三方服务-->>用户: 显示授权页面\n 用户->>第三方服务: 确认授权\n 第三方服务->>Kilo Code: 回调并返回 code\n Kilo Code->>第三方服务: 交换 access token\n 第三方服务-->>Kilo Code: 返回 token\n Kilo Code-->>用户: 授权成功\n```\n\n授权成功后，页面会自动关闭并将控制权交还给 Kilo Code。\n\n资料来源：[packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts)\n\n## 状态与监控\n\n### 状态栏指示器\n\nCLI 和 VS Code 扩展都在状态栏显示关键信息：\n\n| 指示器 | 状态 | 含义 |\n|--------|------|------|\n| LSP | • (绿色) | 已连接 LSP 服务器 |\n| LSP | • (灰色) | 无 LSP 服务器 |\n| MCP | ⊙ (绿色) | MCP 已连接 |\n| MCP | ⊙ (红色) | MCP 连接错误 |\n| Indexing | 文本 | 索引状态 |\n\n### 权限提示\n\n当操作需要额外权限时，状态栏会显示警告信息：\n\n```\n△ 3 Permissions\n```\n\n资料来源：[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)\n\n## 常见问题\n\n### Q: 如何切换 AI 模型？\n\n在设置中选择 \"Provider\" 并配置新的模型提供商，然后在对话中通过 `/model` 命令或设置默认模型进行切换。\n\n### Q: MCP 连接失败怎么办？\n\n1. 检查 MCP 服务是否正常运行\n2. 验证 OAuth 授权是否过期\n3. 查看状态栏的 MCP 错误指示器\n4. 重启 Kilo Code 尝试重新连接\n\n### Q: 如何禁用推理过程显示？\n\n在设置中关闭 \"Show Thinking\" 选项，推理内容将不会在界面中显示。\n\n### Q: 支持本地模型吗？\n\n是的，Kilo Code 支持 Ollama、LM Studio 等本地模型服务。配置相应的提供商地址即可使用。\n\n## 下一步\n\n- 查看[官方文档](https://kilo.ai/docs/)获取完整使用指南\n- 访问[博客](https://blog.kilo.ai/)了解最新更新\n- 参与 [GitHub 讨论](https://github.com/Kilo-Org/kilocode/discussions)提出问题和建议\n- 报告 [Issue](https://github.com/Kilo-Org/kilocode/issues) 帮助改进产品\n\n---\n\n\n\n## 项目结构与包组织\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [packages/kilo-ui/src/components/message-part.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-ui/src/components/message-part.tsx)\n- [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)\n- [packages/ui/src/components/file-icon.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/ui/src/components/file-icon.tsx)\n- [packages/opencode/src/mcp/oauth-callback.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/mcp/oauth-callback.ts)\n
\n\n# 项目结构与包组织\n\n## 概述\n\nKiloCode 是一个模块化的 AI 代码辅助平台，采用 Monorepo 架构组织代码。项目使用 `turbo.json` 作为构建编排工具，将功能划分为多个独立的包（packages），每个包专注于特定的功能领域。\n\nKiloCode 的包组织结构遵循以下核心原则：\n\n- **模块独立性**：每个包拥有独立的功能边界，可独立测试和部署\n- **代码共享**：通过 `@kilo` 前缀的共享包实现跨包复用\n- **多端适配**：支持 VS Code、JetBrains IDE、命令行界面等多种客户端\n\n## 核心包结构\n\n### 包架构总览\n\n```mermaid\ngraph TD\n subgraph \"核心共享包\"\n UI[kilo-ui
UI 组件库]\n UIShared[ui
通用 UI 工具]\n end\n \n subgraph \"平台包\"\n VSCODE[kilo-vscode
VS Code 扩展]\n JETBRAINS[kilo-jetbrains
JetBrains 插件]\n OPENCODE[opencode
命令行工具]\n end\n \n subgraph \"后端服务\"\n GATEWAY[kilo-gateway
API 网关]\n INDEXING[kilo-indexing
代码索引服务]\n end\n \n UI --> VSCODE\n UI --> JETBRAINS\n UIShared --> UI\n GATEWAY --> INDEXING\n \n style UI fill:#e1f5fe\n style VSCODE fill:#fff3e0\n style OPENCODE fill:#f3e5f5\n```\n\n### 包功能对照表\n\n| 包名称 | 路径 | 功能描述 | 依赖技术 |\n|--------|------|----------|----------|\n| `kilo-vscode` | `packages/kilo-vscode/` | VS Code 扩展后端与 Webview UI | TypeScript, VS Code API |\n| `kilo-jetbrains` | `packages/kilo-jetbrains/` | JetBrains IDE 插件 | Kotlin, IntelliJ Platform |\n| `opencode` | `packages/opencode/` | 跨平台命令行界面 | TypeScript, React-like TUI |\n| `kilo-gateway` | `packages/kilo-gateway/` | 后端 API 网关服务 | TypeScript/Node.js |\n| `kilo-indexing` | `packages/kilo-indexing/` | 代码语义索引与搜索 | TypeScript |\n| `kilo-ui` | `packages/kilo-ui/` | React 组件库 | React, TypeScript |\n| `ui` | `packages/ui/` | 基础 UI 组件与图标 | React, TypeScript |\n\n## 目录结构规范\n\n### 标准包结构\n\n```\npackages//\n├── src/ # 源代码目录\n│ ├── index.ts # 包入口文件\n│ ├── components/ # 组件目录\n│ ├── hooks/ # 自定义 Hooks\n│ └── utils/ # 工具函数\n├── package.json # 包配置\n└── tsconfig.json # TypeScript 配置\n```\n\n### Webview UI 特殊结构\n\n`kilo-vscode` 包的 webview-ui 采用前后端分离的结构：\n\n```\nkilo-vscode/\n├── src/ # VS Code 扩展后端\n│ └── extension.ts # 扩展入口\n└── webview-ui/ # Webview 前端\n ├── src/\n │ ├── components/ # React 组件\n │ ├── hooks/ # 业务 Hooks\n │ └── App.tsx # 应用根组件\n └── package.json\n```\n\n## 组件组织模式\n\n### 组件目录结构\n\n组件按照功能模块组织在 `components/` 目录下，采用功能域划分：\n\n```\ncomponents/\n├── migration/ # 迁移向导模块\n│ └── MigrationWizard.tsx\n├── chat/ # 聊天界面模块\n│ └── PromptInput.tsx\n├── marketplace/ # 市场功能模块\n│ └── InstallModal.tsx\n└── [其他功能模块]/\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1]()\n\n### 组件分层架构\n\n```mermaid\ngraph LR\n A[业务组件
MigrationWizard] --> B[功能组件
PromptInput]\n B --> C[基础组件
FileIcon]\n C --> D[UI 原子
Button, TextField]\n \n style A fill:#ffcdd2\n style B fill:#fff9c4\n style C fill:#c8e6c9\n style D fill:#bbdefb\n```\n\n## Hooks 与状态管理\n\n### 自定义 Hooks 模式\n\n`useFileMention` 是典型的自定义 Hook，用于处理文件提及功能：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n // 文件搜索状态\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n const [mentionIndex, setMentionIndex] = createSignal(0)\n \n // 搜索防抖\n let fileSearchTimer: ReturnType | undefined\n let fileSearchCounter = 0\n \n // ...\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24-38]()\n\n### Hook 职责表\n\n| Hook 名称 | 文件位置 | 职责 | 状态类型 |\n|-----------|----------|------|----------|\n| `useFileMention` | `hooks/useFileMention.ts` | 文件路径提及与搜索 | `Set`, `MentionResult[]` |\n| `useTheme` | 主题相关模块 | 主题配置与颜色 | `Theme` 对象 |\n\n## 文件图标系统\n\n### 图标映射机制\n\n文件图标系统通过文件名和扩展名映射到对应的图标：\n\n```typescript\nconst ICON_MAPS: IconMaps = {\n fileNames: {\n // 文档文件\n \"readme.md\": \"Readme\",\n \"changelog.md\": \"Changelog\",\n \"package.json\": \"Nodejs\",\n \n // Docker 文件\n dockerfile: \"Docker\",\n \"docker-compose.yml\": \"Docker\",\n \n // 配置文件\n \"jest.config.js\": \"Jest\",\n },\n fileExtensions: {\n \".ts\": \"Typescript\",\n \".tsx\": \"Typescript\",\n \".json\": \"JSON\",\n },\n folderNames: { /* ... */ },\n defaults: {\n file: \"File\",\n folder: \"Folder\",\n folderOpen: \"FolderOpen\",\n }\n}\n```\n\n资料来源：[packages/ui/src/components/file-icon.tsx:22-48]()\n\n### 支持的文件类型\n\n| 类别 | 文件名/扩展名 | 图标名称 |\n|------|---------------|----------|\n| 文档 | `readme.md`, `changelog.md`, `contributing.md` | Readme, Changelog |\n| Node.js | `package.json`, `package-lock.json`, `yarn.lock` | Nodejs, Yarn |\n| Docker | `dockerfile`, `docker-compose.yml` | Docker |\n| 包管理 | `pnpm-lock.yaml`, `bun.lock` | Pnpm, Bun |\n| 测试 | `jest.config.js`, `jest.config.ts` | Jest |\n\n## TUI 组件架构\n\n命令行工具采用 React-like 的 TUI 组件体系：\n\n```mermaid\ngraph TD\n subgraph \"TUI 路由层\"\n SESSION[index.tsx
会话路由]\n FOOTER[footer.tsx
状态栏]\n PERMISSION[permission.tsx
权限管理]\n end\n \n subgraph \"TUI 组件层\"\n PROMPT[prompt/index.tsx
输入组件]\n AUTOCOMPLETE[autocomplete.tsx
自动完成]\n DIALOG[dialog-export-options.tsx
对话框]\n end\n \n subgraph \"TUI 基础层\"\n THEMES[主题系统]\n LAYOUT[布局组件]\n end\n \n SESSION --> FOOTER\n SESSION --> PROMPT\n PROMPT --> AUTOCOMPLETE\n FOOTER --> DIALOG\n \n style SESSION fill:#e3f2fd\n style PROMPT fill:#f3e5f5\n```\n\n### 会话组件结构\n\n`session/index.tsx` 定义了消息渲染的核心逻辑：\n\n```typescript\nconst PART_MAPPING = {\n text: TextPart,\n tool: ToolPart,\n reasoning: ReasoningPart,\n}\n\nfunction ReasoningPart(props: { last: boolean; part: ReasoningPart; message: AssistantMessage }) {\n // 过滤 OpenRouter 的加密推理数据\n const content = createMemo(() => {\n return props.part.text.replace(\"[REDACTED]\", \"\").trim()\n })\n // ...\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-16]()\n\n### 工具注册机制\n\n工具通过 `ToolRegistry` 进行注册和渲染：\n\n```typescript\nToolRegistry.register({\n name: \"todowrite\",\n render(props) {\n const view = createMemo(() => \n isTodoView(props.metadata?.view) ? props.metadata.view : undefined\n )\n const todos = createMemo(() => {\n const meta = props.metadata\n // 处理待办事项元数据\n })\n // ...\n },\n})\n```\n\n资料来源：[packages/kilo-ui/src/components/message-part.tsx:1-30]()\n\n## OAuth 与认证\n\n### 回调处理流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as 提供商\n participant K as KiloCode\n participant C as 客户端应用\n \n U->>P: 授权请求\n P->>K: OAuth 回调\n K->>K: 处理授权码\n K-->>U: 显示成功页面\n U->>C: 自动关闭窗口\n```\n\nOAuth 回调页面支持多语言显示：\n\n```typescript\nconst HTML_SUCCESS = `\n\n\n Kilo - Authorization Successful\n \n

You can close this window and return to Kilo.

\n \n\n\n

Authorization Successful

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

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

\n
\n )\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1-14]()\n\n### 创建新 Hook\n\n1. **使用 `createSignal`**：SolidJS 的响应式状态\n2. **处理异步操作**：使用防抖处理搜索类操作\n3. **与 VS Code 通信**：通过 `vscode.onMessage` 监听消息\n\n```typescript\nexport function useFileMention(vscode, sessionID, git) {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n let fileSearchTimer: ReturnType | undefined\n \n // 防抖搜索\n createEffect(() => {\n if (fileSearchTimer) clearTimeout(fileSearchTimer)\n fileSearchTimer = setTimeout(() => {\n vscode.postMessage({ type: \"fileSearch\", ... })\n }, 300)\n })\n}\n```\n\n## 总结\n\nKiloCode 项目采用精心设计的 Monorepo 架构：\n\n- **7 个核心包**覆盖 IDE 插件、命令行工具、后端服务等全端场景\n- **组件库分层**实现代码复用与维护性平衡\n- **SolidJS** 作为前端框架提供高效的响应式编程模型\n- **Turborepo** 统一管理构建流程和依赖关系\n\n这种组织方式使项目能够同时支持 VS Code、JetBrains IDE 和命令行等多个客户端，同时保持代码的模块化和可维护性。\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目结构与包组织](#project-structure), [Agent 核心系统](#agent-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/server/server.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/server.ts)\n- [packages/opencode/src/server/adapter.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/server/adapter.ts)\n- [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)\n- [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts)\n- [packages/opencode/src/provider/provider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/provider/provider.ts)\n- [packages/opencode/src/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/registry.ts)\n- [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)\n
\n\n# 系统架构设计\n\n## 概述\n\nKilocode 是一个开源的 AI 编程助手平台，采用模块化架构设计，核心功能包括代码生成、自然语言处理、终端命令执行、浏览器自动化和内联自动补全。系统架构基于分层设计原则，将用户界面、业务逻辑、数据处理和外部服务解耦，通过标准化接口实现各层之间的通信。\n\nKilocode 支持多种客户端形式：命令行界面（CLI）、终端用户界面（TUI）和 Visual Studio Code 扩展。不同客户端共享相同的核心服务层，通过协议适配器实现差异化交互体验。 资料来源：[packages/opencode/README.md](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/README.md)\n\n---\n\n## 整体架构分层\n\nKilocode 采用经典的三层/四层架构设计，从上到下依次为：展示层、服务层、核心业务层和数据层。展示层负责用户交互，服务层处理协议转换和请求路由，核心业务层实现 AI 推理和工具调用，数据层管理会话状态和配置存储。\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 展示层 (UI Layer) │\n│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │\n│ │ CLI │ │ TUI │ │ VS Code Extension │ │\n│ │ │ │ │ │ (Webview + Backend) │ │\n│ └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │\n└───────┼─────────────┼───────────────────┼───────────────┘\n │ │ │\n ▼ ▼ ▼\n┌─────────────────────────────────────────────────────────┐\n│ 服务层 (Service Layer) │\n│ ┌──────────────────────────────────────────────────┐ │\n│ │ 协议适配器 (Protocol Adapter) │ │\n│ │ CLI适配器 │ TUI适配器 │ VSCode消息通道适配器 │ │\n│ └──────────────────────────────────────────────────┘ │\n│ ┌──────────────────────────────────────────────────┐ │\n│ │ HTTP API 网关 │ │\n│ │ /instance/* 路由 · 会话管理端点 │ │\n│ └──────────────────────────────────────────────────┘ │\n└──────────────────────────┬──────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 核心业务层 (Core Business Layer) │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 会话管理 │ │ 工具注册 │ │ 提供者系统 │ │\n│ │ (Session) │ │ (Registry) │ │ (Provider) │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 提示工程 │ │ 工具执行 │ │ 状态管理 │ │\n│ │ (Prompt) │ │ (Executor) │ │ (State Mgmt) │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n└──────────────────────────┬──────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────┐\n│ 数据层 (Data Layer) │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │\n│ │ 会话存储 │ │ 配置存储 │ │ 模型接口 │ │\n│ └─────────────┘ └─────────────┘ └─────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 核心组件架构\n\n### 服务层组件\n\n#### HTTP API 服务器\n\nHTTP API 服务器是 Kilocode 的核心通信枢纽，提供 RESTful 接口供外部客户端调用。服务器实现位于 `packages/opencode/src/server/routes/instance/httpapi/server.ts`，负责处理会话管理、工具调用和状态查询等核心功能。\n\n服务器路由设计遵循统一资源定位原则，所有实例级接口统一挂载在 `/instance` 路径下：\n\n| 路由前缀 | 功能说明 | 请求方法 |\n|---------|---------|----------|\n| `/instance/sessions` | 会话列表与创建 | GET/POST |\n| `/instance/sessions/:id` | 单一会话操作 | GET/DELETE |\n| `/instance/execute` | 远程命令执行 | POST |\n| `/instance/status` | 服务状态查询 | GET |\n\n#### 协议适配器\n\n协议适配器（Adapter）位于 `packages/opencode/src/server/adapter.ts`，负责将不同客户端的通信协议转换为统一的内部消息格式。这种设计使得 CLI、TUI 和 VSCode 扩展可以使用各自的原生协议进行通信，同时核心业务逻辑保持一致。\n\n适配器实现了消息解析、路由分发和响应格式化三个核心功能。当客户端发送请求时，适配器首先解析消息内容，根据消息类型和目标端点将请求路由到对应的处理函数，最后将处理结果格式化为客户端可识别的响应格式。\n\n#### VSCode 连接服务\n\nVSCode 扩展与后端 CLI 之间的通信通过 `packages/kilo-vscode/src/services/cli-backend/connection-service.ts` 实现的连接服务完成。该服务利用 VSCode 原生的 `postMessage` API 建立双向通信通道，支持文件搜索、会话管理和模型查询等操作。\n\n```\n┌─────────────────┐ postMessage ┌─────────────────┐\n│ VSCode Webview │ ──────────────────▶│ CLI Backend │\n│ (Frontend) │ │ (Server) │\n│ │ ◀─────────────────│ │\n│ │ handleMessage │ │\n└─────────────────┘ └─────────────────┘\n```\n\n连接服务定义了标准化的消息格式，消息对象包含 `type` 字段标识消息类型，可选的 `requestId` 用于请求-响应匹配：\n\n```typescript\ninterface VSCodeMessage {\n type: \"fileSearchResult\" | \"sessionList\" | \"sessionCreate\" | \"sessionDelete\" | \"modelList\" | \"error\";\n requestId?: string;\n items?: SearchItem[];\n paths?: string[];\n sessions?: SessionInfo[];\n models?: ModelInfo[];\n error?: string;\n}\n```\n\n---\n\n### 核心业务层组件\n\n#### 会话管理\n\n会话（Session）是 Kilocode 处理用户对话的核心抽象，定义于 `packages/opencode/src/session/session.ts`。每个会话拥有唯一的会话标识符（Session ID），用于追踪对话上下文、管理文件引用和代理状态。\n\n会话模块负责维护对话历史、解析和存储文件提及（File Mentions）、处理工具调用结果以及管理对话状态转换。TUI 界面中的会话组件根据消息模式（mode）展示不同类型的对话内容，包括文本回复、工具调用和推理过程。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[会话初始化]\n B --> C{消息类型}\n C -->|文本| D[AI推理引擎]\n C -->|文件引用| E[文件解析服务]\n C -->|工具调用| F[工具注册表]\n D --> G[响应生成]\n E --> G\n F --> H[工具执行]\n H --> G\n G --> I[会话状态更新]\n I --> J[UI渲染]\n```\n\n#### 提供者系统\n\n提供者（Provider）系统位于 `packages/opencode/src/provider/provider.ts`，是 Kilocode 与外部 AI 模型交互的抽象层。提供者系统标准化了与不同 AI 厂商（如 OpenAI、Anthropic、Google 等）的接口，屏蔽了底层 API 差异。\n\n每个提供者实现以下核心接口：\n\n| 接口方法 | 功能说明 | 返回类型 |\n|---------|---------|----------|\n| `chat()` | 发送对话请求 | `AsyncIterator` |\n| `models()` | 列出可用模型 | `Model[]` |\n| `authenticate()` | 身份验证 | `Promise` |\n| `health()` | 健康检查 | `Promise` |\n\n提供者系统支持模型选择、参数配置和密钥管理，允许用户在 `kilo.json` 配置文件中指定使用的模型和提供者的凭据信息。\n\n#### 工具注册表\n\n工具注册表（Tool Registry）定义于 `packages/opencode/src/tool/registry.ts`，是 Kilocode 扩展其能力的基础架构。工具注册表采用插件式设计，允许动态注册新的工具功能，系统启动时自动扫描并加载所有已注册的工具。\n\n注册表核心数据结构包括：\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `name` | `string` | 工具唯一标识名 |\n| `description` | `string` | 工具功能描述 |\n| `parameters` | `Schema` | 参数定义 |\n| `handler` | `Function` | 执行函数 |\n\n已注册的工具通过标准化的调用接口暴露给 AI 模型，模型可以根据对话上下文选择合适的工具执行任务。TUI 界面中的工具部分渲染器（ToolPart）负责将工具调用结果以格式化方式展示给用户。\n\n---\n\n## 消息处理流程\n\n### TUI 消息渲染流程\n\nTUI 界面中的消息渲染采用组件化设计，不同类型的消息部分（Part）由对应的渲染器处理：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as TUI界面\n participant Session as 会话模块\n participant AI as AI模型\n participant Registry as 工具注册表\n\n User->>TUI: 发送消息\n TUI->>Session: 创建用户消息\n Session->>AI: 发送对话请求\n AI->>AI: 生成回复\n AI-->>Session: 返回响应流\n Session-->>TUI: 分发消息片段\n \n alt 文本消息\n TUI->>TUI: TextPart渲染器\n else 工具调用\n TUI->>Registry: 查询工具信息\n Registry-->>TUI: 工具元数据\n TUI->>TUI: ToolPart渲染器\n else 推理过程\n TUI->>TUI: ReasoningPart渲染器\n Note over TUI: 过滤[REDACTED]标记\n end\n \n TUI-->>User: 展示消息内容\n```\n\n推理消息（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)\n\n### 文件提及处理流程\n\n文件提及（File Mention）是 Kilocode 的核心交互特性，允许用户在对话中通过 `@` 符号引用文件。处理流程如下：\n\n```mermaid\ngraph LR\n A[用户输入] --> B{检测@符号}\n B -->|是| C[触发提及查询]\n C --> D[搜索文件]\n D --> E[显示建议列表]\n E --> F[用户选择]\n F --> G[解析文件信息]\n G --> H[创建FilePart]\n H --> I[更新extmark]\n I --> J[渲染文件引用]\n```\n\n文件提及功能由 `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)\n\n---\n\n## 数据流与状态管理\n\n### 会话数据流\n\n会话模块管理整个对话的生命周期，数据流向遵循以下模式：\n\n1. **输入阶段**：用户输入通过客户端界面捕获，转换为标准消息格式\n2. **处理阶段**：消息经过解析、验证和上下文增强后发送给 AI 模型\n3. **推理阶段**：AI 模型生成回复，系统根据回复类型分发到不同处理器\n4. **输出阶段**：处理后的内容更新会话状态，UI 层订阅状态变化进行渲染\n\n### 状态同步机制\n\nVSCode 扩展中，前端 Webview 与后端 CLI 通过消息通道保持状态同步。连接服务维护一个消息计数器 `fileSearchCounter` 用于追踪文件搜索请求，确保响应与请求正确匹配：\n\n```typescript\nlet fileSearchCounter = 0\n\n// 发送请求时递增\nconst requestId = `file-search-${fileSearchCounter++}`\n\n// 接收响应时验证\nif (message.requestId === `file-search-${fileSearchCounter}`) {\n // 处理结果\n}\n```\n\n---\n\n## 配置系统\n\nKilocode 的配置系统支持多层级合并，优先级从低到高依次为：远程默认配置、全局配置（`~/.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)\n\n配置查找路径支持以下目录：\n\n| 目录路径 | 说明 |\n|---------|------|\n| `~/.config/kilo/` | 全局配置根目录 |\n| `./.kilo/` | 项目本地配置 |\n| `./.kilocode/` | 项目本地配置（兼容旧版本） |\n| `./.opencode/` | 项目本地配置（兼容旧版本） |\n\n命令文件存储在配置的 `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)\n\n---\n\n## 工具与代理集成\n\n### 工具注册机制\n\n工具注册表支持插件化扩展，每个工具需要提供名称、描述、参数模式和执行函数。系统启动时，注册表扫描预定义路径下的工具模块，自动完成工具的注册和初始化。\n\n### 代理管理\n\n代理（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)\n\n---\n\n## 安全考虑\n\n### 敏感信息处理\n\n导出功能中实现了敏感信息过滤机制，系统自动识别并脱敏文件路径、符号名称、URI 和客户端名称等敏感数据：\n\n```typescript\nfunction source(part: MessageV2.FilePart) {\n if (!part.source) return part.source\n if (part.source.type === \"symbol\") {\n return {\n ...part.source,\n path: redact(\"file-path\", part.id, part.source.path),\n name: redact(\"file-symbol\", part.id, part.source.name),\n }\n }\n // ...\n}\n```\n\n### 会话隔离\n\n每个会话拥有独立的上下文空间，会话间的数据和状态完全隔离，确保多用户或多任务场景下的数据安全。\n\n---\n\n## 扩展点与插件化\n\nKilocode 架构设计预留了多个扩展点，支持第三方功能集成：\n\n| 扩展点 | 说明 | 接入方式 |\n|-------|------|----------|\n| 工具注册 | 自定义工具功能 | 实现 ToolRegistry 接口 |\n| 提供者 | 自定义 AI 模型 | 实现 Provider 接口 |\n| 命令 | 自定义 CLI 命令 | 添加 `.kilo/command/*.md` 文件 |\n| MCP 服务器 | 扩展系统能力 | 通过 `kilo mcp` 命令管理 |\n\n---\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|-----|---------|\n| 展示层 | React + TypeScript（VSCode扩展）、SolidJS（kilo-ui） |\n| 服务层 | Node.js HTTP 服务器、WebSocket（可选） |\n| 核心业务 | TypeScript 原生实现 |\n| 数据层 | 文件系统存储、会话序列化 |\n| 通信协议 | JSON over postMessage、REST API |\n\n---\n\n## 总结\n\nKilocode 的系统架构遵循模块化、可扩展和松耦合的设计原则。通过分层架构和协议适配器，系统支持多种客户端形式，同时保持核心业务逻辑的统一。会话管理、工具注册表和提供者系统构成了核心业务层的主要组件，HTTP API 网关和消息通道服务则负责对外通信。这种架构设计使得 Kilocode 能够灵活适应不同的使用场景，同时为第三方扩展预留了充足的接口。\n\n---\n\n\n\n## Agent 核心系统\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [自动补全系统 (FIM)](#autocomplete-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/agent/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/agent.ts)\n- [packages/opencode/src/session/session.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/session.ts)\n- [packages/opencode/src/session/prompt.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/prompt.ts)\n- [packages/opencode/src/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/processor.ts)\n- [packages/opencode/src/session/llm.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/llm.ts)\n- [packages/opencode/src/session/compaction.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/session/compaction.ts)\n- [packages/opencode/src/agent/prompt/orchestrator.txt](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/agent/prompt/orchestrator.txt)\n- [packages/opencode/src/kilocode/session/processor.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/session/processor.ts)\n
\n\n# Agent 核心系统\n\n## 概述\n\nKiloCode 的 Agent 核心系统是整个智能编程平台的中枢，负责处理用户请求、调度工具执行、管理会话上下文以及协调大语言模型（LLM）交互。该系统采用模块化架构，将会话管理、消息处理、上下文压缩和工具注册等功能分离，实现了高内聚低耦合的设计目标。\n\nAgent 系统的核心职责包括：接收用户自然语言指令并转化为可执行的任务、通过工具注册表调用各类工具（如文件操作、终端命令、Git 操作等）、维护会话历史和上下文状态、执行上下文压缩以控制 token 消耗、以及支持多种运行模式（Architect、Coder、Debugger 等）。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n User[用户输入] --> Session[会话管理模块]\n Session --> Processor[消息处理器]\n Processor --> LLM[LLM 交互层]\n LLM --> Response[响应生成]\n Response --> ToolRegistry[工具注册表]\n ToolRegistry --> Tools[工具执行]\n Tools --> Processor\n Session --> Compaction[上下文压缩]\n Compaction --> Context[上下文管理]\n Context --> LLM\n Session --> Prompt[提示词管理]\n Prompt --> LLM\n```\n\n### 核心模块职责\n\n| 模块名称 | 文件路径 | 主要职责 |\n|---------|---------|---------|\n| Agent 主模块 | `packages/opencode/src/agent/agent.ts` | 核心代理逻辑、模式调度、生命周期管理 |\n| 会话管理 | `packages/opencode/src/session/session.ts` | 会话状态维护、父子会话关系、多会话支持 |\n| 消息处理 | `packages/opencode/src/session/processor.ts` | 消息解析、工具调用分发、响应格式化 |\n| LLM 交互 | `packages/opencode/src/session/llm.ts` | 模型调用、流式响应、推理处理 |\n| 上下文压缩 | `packages/opencode/src/session/compaction.ts` | 历史消息压缩、token 优化 |\n| 提示词管理 | `packages/opencode/src/agent/prompt/orchestrator.txt` | 角色定义、指令模板管理 |\n\n## Agent 主模块\n\n### 核心类结构\n\nAgent 主模块位于 `packages/opencode/src/agent/agent.ts`，是整个系统的核心入口点。该模块定义了 Agent 类的基本结构，包括初始化配置、运行循环、错误处理等核心功能。\n\nAgent 类采用事件驱动的设计模式，通过监听器模式处理各类系统事件。初始化时，Agent 会加载配置文件、建立 LLM 连接、注册工具集，并准备会话环境。\n\n### 模式系统\n\nKiloCode 支持多种运行模式，每种模式针对不同的开发场景进行了优化：\n\n- **Architect（架构师模式）**：专注于代码设计和架构规划\n- **Coder（编码模式）**：执行具体的代码实现和修改任务\n- **Debugger（调试模式）**：定位和修复代码问题\n\n模式定义存储在 `packages/opencode/src/agent/prompt/orchestrator.txt` 中，通过角色提示词引导 LLM 产生符合当前模式预期的行为。\n\n### 生命周期管理\n\nAgent 的生命周期包含以下阶段：\n\n```mermaid\nstateDiagram-v2\n [*] --> Init: 初始化\n Init --> Ready: 配置加载完成\n Ready --> Running: 接收用户请求\n Running --> Ready: 请求处理完成\n Running --> Error: 发生错误\n Error --> Ready: 错误恢复\n Ready --> [*]: 会话结束\n```\n\n1. **初始化阶段**：加载配置、初始化 LLM 连接、注册工具\n2. **就绪阶段**：等待用户输入\n3. **运行阶段**：处理请求、执行工具、生成响应\n4. **错误处理**：捕获异常、尝试恢复或终止\n\n## 会话管理系统\n\n### 会话数据结构\n\n会话管理模块位于 `packages/opencode/src/session/session.ts`，负责维护会话的完整生命周期。每个会话包含以下关键属性：\n\n- **sessionID**：会话唯一标识符\n- **parentID**：父会话 ID（用于子代理场景）\n- **mode**：当前运行模式\n- **messages**：消息历史列表\n- **metadata**：会话元数据（创建时间、更新时间等）\n\n### 父子会话机制\n\n系统支持创建子代理会话，子会话继承父会话的上下文，同时可以独立执行任务。这一机制允许复杂的任务分解和委托场景：\n\n```mermaid\ngraph LR\n Parent[父会话] -->|创建子代理| Child1[子会话 1]\n Parent -->|创建子代理| Child2[子会话 2]\n Child1 -->|汇报结果| Parent\n Child2 -->|汇报结果| Parent\n```\n\n子会话标识通过 `session()?.parentID` 属性判断，在 UI 层（`packages/opencode/src/cli/cmd/tui/routes/session/index.tsx`）会根据是否为子会话显示不同的界面元素，如子代理底部栏（SubagentFooter）。\n\n### 会话状态同步\n\n会话状态通过 `packages/opencode/src/session/processor.ts` 进行处理，支持实时状态更新和持久化。状态变化时会触发相应的事件通知各订阅模块。\n\n## 消息处理流程\n\n### 处理器架构\n\n消息处理器是 Agent 系统的核心组件，负责将用户输入转换为系统可执行的操作序列。其处理流程如下：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Proc as 处理器\n participant LLM as LLM 层\n participant Tools as 工具注册表\n participant Session as 会话管理\n\n User->>Proc: 发送消息\n Proc->>Proc: 消息解析与验证\n Proc->>LLM: 调用 LLM\n LLM-->>Proc: 返回响应\n Proc->>Tools: 检测工具调用\n Tools-->>Proc: 工具结果\n Proc->>LLM: 继续处理\n Proc->>Session: 更新会话历史\n Proc-->>User: 返回最终响应\n```\n\n### 消息类型处理\n\n系统支持多种消息类型，每种类型有对应的处理策略：\n\n| 消息类型 | 来源 | 处理方式 |\n|---------|------|---------|\n| user | 用户输入 | 解析意图、转译为任务 |\n| assistant | LLM 响应 | 解析工具调用、格式化输出 |\n| tool | 工具执行结果 | 整合结果、继续 LLM 循环 |\n| system | 系统消息 | 更新状态、触发事件 |\n| reasoning | 推理过程 | 可选显示、用于调试 |\n\n### 推理处理\n\n对于支持推理的模型，系统会特殊处理 `reasoning` 类型消息。在 `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` 中定义了 `ReasoningPart` 组件，用于渲染推理过程。\n\n推理内容中若包含 `[REDACTED]` 标记（如来自 OpenRouter 的加密推理数据），系统会自动过滤：\n\n```typescript\nconst content = createMemo(() => {\n return props.part.text.replace(\"[REDACTED]\", \"\").trim()\n})\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:112-117]()\n\n## 工具系统\n\n### 工具注册机制\n\n工具注册表位于 `packages/opencode/src/kilocode/tool/registry.ts`，采用注册表模式管理所有可用工具。工具定义包含以下属性：\n\n- **id**：工具唯一标识\n- **name**：工具显示名称\n- **description**：工具功能描述\n- **parameters**：参数模式定义\n- **handler**：执行函数\n\n### 核心工具集\n\n系统内置的核心工具包括：\n\n| 工具名称 | 功能描述 | 注册位置 |\n|---------|---------|---------|\n| Read | 读取文件内容 | 默认注册 |\n| Write | 写入或创建文件 | 默认注册 |\n| Edit | 编辑文件指定区域 | 默认注册 |\n| Bash | 执行终端命令 | 默认注册 |\n| Glob | 文件模式匹配 | 默认注册 |\n| Grep | 代码内容搜索 | 默认注册 |\n| manager | Agent 管理工具 | 条件注册 |\n\n### 工具描述增强\n\n对于 `glob` 和 `grep` 工具，系统会添加额外的使用提示，帮助 LLM 更准确地使用这些工具：\n\n```typescript\nexport function describe(tools: Tool.Def[], extra: { semantic?: Tool.Def }): Tool.Def[] {\n if (!extra.semantic) return tools\n return tools.map((tool) => {\n if (tool.id !== \"glob\" && tool.id !== \"grep\") return tool\n return { ...tool, description: `${tool.description}\\n${hint}` }\n })\n}\n```\n\n资料来源：[packages/opencode/src/kilocode/tool/registry.ts:45-54]()\n\n## LLM 交互层\n\n### 模型调用封装\n\nLLM 交互层位于 `packages/opencode/src/session/llm.ts`，封装了与各类大语言模型的通信细节。系统支持多种模型提供商，包括 OpenAI、Anthropic、OpenRouter 等。\n\n### 流式响应处理\n\n系统采用流式响应模式，通过 Server-Sent Events（SSE）或 WebSocket 实时推送 LLM 输出。流式处理的优势包括：\n\n- **即时反馈**：用户可以立即看到生成的内容\n- **降低延迟**：无需等待完整响应即可开始处理\n- **资源优化**：减少内存占用\n\n### 消息中止机制\n\n系统支持通过 `MessageAbortedError` 中止正在进行的 LLM 调用。在 UI 层会显示 \"interrupted\" 状态标识：\n\n```typescript\n\n · interrupted\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:38-40]()\n\n## 上下文管理\n\n### 上下文压缩策略\n\n由于 LLM 有 token 数量限制，系统实现了上下文压缩机制，位于 `packages/opencode/src/session/compaction.ts`。压缩策略包括：\n\n1. **摘要压缩**：将历史消息压缩为关键信息摘要\n2. **选择性保留**：保留重要上下文，丢弃冗余内容\n3. **滑动窗口**：使用固定大小的上下文窗口\n\n### AGENTS.md 集成\n\n系统支持项目级别的 `AGENTS.md` 文件，该文件包含针对 AI 代理的特定指令。文件搜索逻辑会按以下顺序查找：\n\n1. 项目根目录的 `AGENTS.md`\n2. 子目录中的 `AGENTS.md`\n3. `README.md` 作为备选\n\n```mermaid\ngraph TD\n Start[加载上下文] --> CheckRoot{检查根目录 AGENTS.md}\n CheckRoot -->|存在| UseRoot[使用根目录 AGENTS.md]\n CheckRoot -->|不存在| CheckSub{检查子目录 AGENTS.md}\n CheckSub -->|存在| UseSub[使用子目录 AGENTS.md]\n CheckSub -->|不存在| Fallback[使用 README.md]\n UseRoot --> Done[完成上下文加载]\n UseSub --> Done\n Fallback --> Done\n```\n\n资料来源：[packages/opencode/src/session/prompt/kimi.txt:1-20]()\n\n## MCP 服务器集成\n\n### MCP 状态显示\n\n系统集成了 MCP（Model Context Protocol）服务器支持，在 TUI 界面底部栏显示 MCP 连接状态：\n\n```typescript\n\n \n \n \n ⊙ \n \n \n ⊙ \n \n \n {mcp()} MCP\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:25-37]()\n\n### MCP OAuth 回调\n\nMCP 服务器认证采用 OAuth 2.0 流程，授权成功后会显示确认页面：\n\n```html\n

You can close this window and return to Kilo.

\n\n```\n\n资料来源：[packages/opencode/src/mcp/oauth-callback.ts:28-29]()\n\n## 索引与 LSP 集成\n\n### 索引状态显示\n\n系统支持代码索引功能，在界面底部栏显示当前索引状态：\n\n```typescript\n\n \n {indexingText(indexing()).slice(0, 48)}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:38-41]()\n\n### LSP 连接状态\n\n底部栏同时显示 LSP（Language Server Protocol）连接数量：\n\n```typescript\n\n 0 ? theme.success : theme.textMuted }}>•\n {lsp().length} LSP\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:20-23]()\n\n## 权限管理\n\n### 权限请求机制\n\n当执行敏感操作时，系统会请求用户授权。权限状态在底部栏显示：\n\n```typescript\n 0}>\n \n △\n {permissions().length} Permission{permissions().length > 1 ? \"s\" : \"\"}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:14-19]()\n\n## 文件提及系统\n\n### 文件自动检测\n\n系统支持自动检测和处理用户输入中的文件引用。在 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts` 中实现了文件提及检测逻辑。\n\n文件提及支持多种类型：\n\n| 类型 | 图标 | 显示效果 |\n|-----|------|---------|\n| terminal | console | 显示命令路径 |\n| git-changes | branch | 显示 Git 变更 |\n| file | 文件图标 | 显示文件名和目录 |\n| folder | 文件夹图标 | 显示目录路径 |\n\n### 文件搜索防抖\n\n为避免频繁搜索，系统实现了防抖机制：\n\n```typescript\nlet fileSearchTimer: ReturnType | undefined\nlet fileSearchCounter = 0\n```\n\n搜索结果通过 `requestId` 关联，确保响应的正确性和顺序性。\n\n## 扩展性设计\n\n### 插件插槽系统\n\n系统通过 `TuiPluginRuntime.Slot` 提供扩展插槽，支持第三方插件注入功能：\n\n```typescript\n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:198-207]()\n\n### 工具注册表扩展\n\n工具注册表支持动态注册新工具，第三方可以通过扩展点添加自定义工具。注册时需要提供完整的工具定义，包括参数模式和执行处理函数。\n\n## 配置管理\n\n### 同步配置结构\n\n系统使用 `sync` 对象管理配置状态，包括：\n\n- `sync.path.directory`：当前工作目录\n- `sync.data.config`：运行时配置\n- `sync.data.state`：会话状态\n\n### 状态持久化\n\n会话状态支持持久化存储，包括：\n\n- 消息历史\n- 用户偏好设置\n- 工具配置\n- 上下文摘要\n\n## 错误处理\n\n### 错误分类\n\n系统将错误分为以下几类：\n\n| 错误类型 | 处理策略 | 用户可见性 |\n|---------|---------|-----------|\n| LLM 调用错误 | 重试或降级 | 是 |\n| 工具执行错误 | 返回错误信息 | 是 |\n| 认证错误 | 引导重新认证 | 是 |\n| 系统错误 | 记录日志 | 可选 |\n\n### 网络可见性\n\n系统通过 `networkVisible()` 和 `network()` 状态管理网络相关错误的显示：\n\n```typescript\n\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:193-195]()\n\n## 性能优化\n\n### 虚拟文本渲染\n\n对于文件提及等高频更新元素，系统采用虚拟文本渲染优化性能：\n\n```typescript\nif (part.type === \"file\" && part.source?.text) {\n part.source.text.start = extmarkStart\n part.source.text.end = extmarkEnd\n part.source.text.value = virtualText\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:45-51]()\n\n### 频率优化\n\n文件搜索结果通过频率算法（Frecency）排序，优先显示常用文件：\n\n```typescript\nif (part.type === \"file\" && part.source && part.source.type === \"file\") {\n frecency.updateFrecency(part.source.path)\n}\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:65-67]()\n\n## 总结\n\nAgent 核心系统是 KiloCode 平台的核心支柱，通过模块化设计和清晰的职责划分，实现了高效、可靠的智能编程辅助能力。系统各组件之间通过事件和接口进行通信，既保证了功能的独立性，又支持灵活的可扩展性。理解这一架构对于深入使用和二次开发 KiloCode 具有重要意义。\n\n---\n\n\n\n## 自动补全系统 (FIM)\n\n### 相关页面\n\n相关主题：[Agent 核心系统](#agent-system), [代码索引与语义搜索](#indexing-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/services/autocomplete/settings.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/settings.ts)\n- [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)\n- [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)\n- [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)\n- [packages/opencode/src/kilocode/claw/view.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/claw/view.tsx)\n
\n\n# 自动补全系统 (FIM)\n\n## 概述\n\nKiloCode 的自动补全系统（Fill-In-The-Middle，简称 FIM）是一个为开发者提供智能代码补全功能的核心模块。该系统通过分析当前编辑上下文，结合语言模型生成高质量的代码建议，帮助开发者提高编码效率。\n\n自动补全系统支持多种文件类型，包括 Python、TypeScript/TSX、Shell 脚本等，并能根据不同语言特性动态调整补全策略。\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"用户界面层\"\n VSCodeEditor[VS Code 编辑器]\n TUIPrompt[TUI 命令行提示符]\n ClawChat[Claw 聊天界面]\n end\n\n subgraph \"补全服务层\"\n AutocompleteProvider[AutocompleteInlineCompletionProvider]\n FillInTheMiddle[FIM 处理器]\n ContextRetrieval[上下文检索服务]\n end\n\n subgraph \"模板与后处理\"\n AutocompleteTemplate[补全模板]\n PostProcessing[后处理器]\n end\n\n subgraph \"配置层\"\n Settings[设置管理]\n Validators[设置验证器]\n end\n\n VSCodeEditor --> AutocompleteProvider\n TUIPrompt --> autocomplete\n ClawChat --> ClawSlashes\n AutocompleteProvider --> FillInTheMiddle\n FillInTheMiddle --> ContextRetrieval\n ContextRetrieval --> AutocompleteTemplate\n AutocompleteTemplate --> PostProcessing\n Settings --> Validators\n```\n\n### 核心组件\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| AutocompleteInlineCompletionProvider | 为 VS Code 提供内联补全项的核心提供者 | settings.ts |\n| FillInTheMiddle | 实现 Fill-In-The-Middle 算法的核心逻辑 | EXAMPLES.md |\n| ContextRetrievalService | 从代码库中检索相关上下文信息 | 架构设计 |\n| AutocompleteTemplate | 管理和渲染补全提示模板 | 架构设计 |\n| PostProcessing | 对模型输出进行后处理和格式化 | 架构设计 |\n\n## 配置系统\n\n### 设置验证机制\n\n自动补全系统通过 `validAutocompleteSetting` 函数验证用户配置，确保只接受有效的设置值：\n\n```typescript\nexport function validAutocompleteSetting(key: string, value: unknown) {\n if (key === \"model\") {\n if (typeof value !== \"string\") return false\n return AUTOCOMPLETE_MODELS.some((m) => m.id === value)\n }\n\n if (key === \"enableAutoTrigger\") return typeof value === \"boolean\"\n if (key === \"enableSmartInlineTaskKeybinding\") return typeof value === \"boolean\"\n if (key === \"enableChatAutocomplete\") return typeof value === \"boolean\"\n\n return false\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:18-31]()\n\n### 支持的配置项\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `model` | string | 选择的补全模型 ID |\n| `enableAutoTrigger` | boolean | 是否启用自动触发 |\n| `enableSmartInlineTaskKeybinding` | boolean | 智能内联任务快捷键 |\n| `enableChatAutocomplete` | boolean | 聊天自动补全 |\n\n## Fill-In-The-Middle 算法\n\n### FIM 工作流程\n\n```mermaid\ngraph LR\n A[光标位置] --> B[获取前缀上下文]\n B --> C[获取后缀上下文]\n C --> D[构建 FIM Prompt]\n D --> E[调用 LLM]\n E --> F[生成补全代码]\n F --> G[后处理]\n G --> H[返回补全建议]\n```\n\n### 分语言配置\n\n系统针对不同编程语言提供了特定的配置优化：\n\n```typescript\nif (fileExtension === \"py\") {\n // Python 特定设置\n this.config.multilineCompletions = \"always\"\n this.config.stopTokens = ['\"\"\"', \"'''\"]\n} else if (fileExtension === \"ts\" || fileExtension === \"tsx\") {\n // TypeScript 特定设置\n this.config.tabAutocompleteOptions = {\n ...this.config.tabAutocompleteOptions,\n maxPromptTokens: 2048,\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:1-60]()\n\n### 上下文窗口管理\n\n| 语言 | 最大 Prompt Token | 多行补全策略 | 停止标记 |\n|------|------------------|-------------|---------|\n| Python | 动态 | 始终启用 | `\"\"\"`, `'''` |\n| TypeScript | 2048 | 动态 | 基于语法 |\n| 默认 | 动态 | 动态 | 基于语法 |\n\n## 上下文检索服务\n\n### 检索策略\n\n上下文检索服务负责从代码库中获取与当前编辑位置相关的代码片段。系统支持以下检索方式：\n\n1. **Tree-Sitter 语法树查询**：基于代码语法结构进行精确检索\n2. **文件路径匹配**：基于文件路径和命名模式\n3. **语义相似度**：基于代码语义内容的相似度匹配\n\n### 代码片段查询\n\n系统使用 Tree-Sitter 进行代码结构分析，支持以下查询能力：\n\n- 导入语句识别\n- 函数和类定义检索\n- 类型注解提取\n- 注释和文档字符串获取\n\n## 补全模板系统\n\n### 模板结构\n\n补全模板定义了如何将上下文信息组织成适合 LLM 处理的格式：\n\n```typescript\ninterface AutocompleteTemplate {\n prefix: string // 光标前内容\n suffix: string // 光标后内容\n aroundCursor: string // 光标周围代码块\n metadata: {\n language: string\n filePath: string\n lineNumber: number\n }\n}\n```\n\n### 模板变量\n\n| 变量 | 说明 | 示例 |\n|-----|------|------|\n| `{{prefix}}` | 光标前代码 | `function hello() {` |\n| `{{suffix}}` | 光标后代码 | `}` |\n| `{{file_name}}` | 当前文件名 | `main.py` |\n| `{{language}}` | 编程语言 | `python` |\n\n## 后处理系统\n\n### 后处理流程\n\n```mermaid\ngraph TD\n A[LLM 输出] --> B[停止标记检测]\n B --> C[语法验证]\n C --> D{是否有效?}\n D -->|是| E[格式化输出]\n D -->|否| F[降级处理]\n E --> G[返回补全项]\n F --> G\n```\n\n### 后处理功能\n\n| 功能 | 描述 |\n|-----|------|\n| 停止标记处理 | 检测并截断在 `stopTokens` 处的输出 |\n| 缩进修正 | 根据文件类型修正缩进 |\n| 语法验证 | 确保输出符合目标语言语法 |\n| 多行处理 | 智能处理跨行代码补全 |\n\n## CLI 命令行界面\n\n### TUI 自动补全组件\n\n在命令行界面中，自动补全系统通过 `autocomplete.tsx` 组件提供交互式补全功能：\n\n```typescript\nconst commands = createMemo((): AutocompleteOption[] => {\n const results: AutocompleteOption[] = [...command.slashes()]\n\n for (const res of Object.values(sync.data.mcp_resource)) {\n const text = `${res.name} (${res.uri})`\n options.push({\n display: Locale.truncateMiddle(text, width),\n value: text,\n description: res.description,\n onSelect: () => { /* ... */ }\n })\n }\n\n return options\n})\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1-120]()\n\n### MCP 资源自动补全\n\n系统支持 MCP（Model Context Protocol）资源的自动补全，开发者可以在提示符中快速引用外部资源。\n\n## VS Code 集成\n\n### 内联补全提供者\n\n`AutocompleteInlineCompletionProvider` 实现了 VS Code 的 `InlineCompletionItemProvider` 接口，提供内联代码补全功能：\n\n```typescript\nclass VSCodeAutocompleteIntegration\n implements vscode.InlineCompletionItemProvider\n{\n private completionProvider: CompletionProvider;\n private currentCompletionId: string | null = null;\n\n constructor() {\n const config = new MinimalConfigProvider();\n const ide = new VSCodeIdeAdapter();\n\n this.completionProvider = new CompletionProvider(\n config,\n ide,\n this.getLlm.bind(this),\n this.onError.bind(this),\n this.getDefinitionsFromLsp.bind(this)\n );\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/continuedev/EXAMPLES.md:62-120]()\n\n### 补全触发流程\n\n```mermaid\nsequenceDiagram\n participant Editor as VS Code 编辑器\n participant Provider as 补全提供者\n participant Config as 配置管理\n participant LLM as 语言模型\n\n Editor->>Provider: 用户触发补全\n Provider->>Config: 获取当前配置\n Config-->>Provider: 返回配置参数\n Provider->>Provider: 构建 FIM Prompt\n Provider->>LLM: 发送补全请求\n LLM-->>Provider: 返回候选代码\n Provider->>Provider: 后处理\n Provider-->>Editor: 返回 InlineCompletionItem\n```\n\n## 文件提及与附件\n\n### 文件提及系统\n\n`useFileMention` hook 提供了在提示中提及和附加文件的功能：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n \n return {\n parseFileAttachments,\n addPaths,\n setMentionIndex,\n closeMention,\n }\n}\n```\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:1-50]()\n\n### 文件类型支持\n\n| 文件类型 | 图标 | 描述显示 |\n|---------|------|---------|\n| 普通文件 | FileIcon | 文件名 + 目录路径 |\n| 文件夹 | FileIcon | 文件夹名 + 父目录 |\n| 终端 | console 图标 | 终端名称 |\n| Git 变更 | branch 图标 | 变更摘要 |\n\n## Claw 聊天集成\n\n### 斜杠命令自动补全\n\n在 Claw 聊天界面中，系统支持斜杠命令的自动补全：\n\n```typescript\nconst clawSlashes = createMemo(() => {\n const visible = kiloCommands().filter((c) => c.enabled !== false && !c.hidden && c.slash)\n const items = visible.map((c) => ({\n display: \"/\" + c.slash!.name,\n description: c.description ?? c.title,\n aliases: c.slash!.aliases?.map((a) => \"/\" + a),\n onSelect: () => c.onSelect?.(dialog),\n }))\n const max = items.reduce((m, i) => Math.max(m, i.display.length), 0)\n if (!max) return items\n return items.map((i) => ({ ...i, display: i.display.padEnd(max + 2) }))\n})\n```\n\n资料来源：[packages/opencode/src/kilocode/claw/view.tsx:1-50]()\n\n## 性能优化\n\n### 增量更新机制\n\n系统通过以下方式优化性能：\n\n1. **延迟加载**：仅在需要时加载补全模型\n2. **缓存策略**：缓存常用上下文的检索结果\n3. **节流处理**：对频繁触发的事件进行节流\n\n### 设置变更监听\n\n```typescript\ncontext.subscriptions.push(\n vscode.workspace.onDidChangeConfiguration((e) => {\n if (e.affectsConfiguration(\"kilo-code.new.autocomplete\")) {\n post(buildAutocompleteSettingsMessage())\n }\n })\n)\n```\n\n资料来源：[packages/kilo-vscode/src/services/autocomplete/settings.ts:1-18]()\n\n## 总结\n\nKiloCode 的自动补全系统采用模块化设计，通过 FIM 算法实现智能的上下文感知代码补全。系统支持多种编程语言，提供灵活的配置选项，并通过完善的后处理机制确保补全结果的质量。该系统与 VS Code、TUI 和 Claw 等多个界面无缝集成，为开发者提供一致的优质补全体验。\n\n---\n\n\n\n## Agent Manager 工作流管理\n\n### 相关页面\n\n相关主题：[系统架构设计](#system-architecture), [MCP 协议与工具集成](#mcp-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/AgentManagerProvider.ts)\n- [packages/kilo-vscode/src/agent-manager/WorktreeManager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/WorktreeManager.ts)\n- [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)\n- [packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/PRStatusPoller.ts)\n- [packages/kilo-vscode/src/agent-manager/GitOps.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/agent-manager/GitOps.ts)\n- [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)\n- [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)\n- [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts)\n
\n\n# Agent Manager 工作流管理\n\n## 概述\n\nAgent Manager 是 Kilo 平台的核心组件，提供多智能体协作与工作流自动化管理能力。该系统通过集成 Git 工作树管理、PR 状态轮询、GitOps 自动化操作和终端管理，实现了一个高效的多代理代码开发环境。Agent Manager 允许用户创建、配置和管理多个专门化的代理（Agent），每个代理可以拥有独立的权限、提示词和任务范围，从而实现复杂软件工程任务的分工协作。\n\nAgent Manager 的设计理念是将代码开发过程分解为多个可配置的工作单元，通过集中式的调度和协调，确保多个代理能够有序地处理不同类型的任务。从架构层面来看，Agent Manager 不仅仅是一个任务调度器，更是一个完整的开发工作流编排平台，涵盖了从代码生成、审查、测试到部署的完整生命周期管理。\n\n该系统的核心价值体现在以下几个方面：首先，通过细粒度的权限控制机制，每个代理只能访问和操作其被授权的资源，防止未经授权的代码修改；其次，通过 Git 工作树（Worktree）隔离机制，不同代理可以在独立的分支上并行工作，避免相互干扰；再次，通过自动化的 PR 状态监控和 GitOps 操作，实现了持续集成和持续部署的无缝衔接；最后，通过统一的终端管理和会话管理，提供了一致且可追溯的开发体验。\n\n## 核心架构\n\n### 系统组件总览\n\nAgent Manager 的架构采用模块化设计，各组件职责明确且相互协作。核心组件包括 AgentManagerProvider（提供器）、WorktreeManager（工作树管理器）、RunManager（运行管理器）、PRStatusPoller（PR 状态轮询器）、GitOps（Git 运维操作）、TerminalManager（终端管理器）和 SectionHandler（分区处理器）。这些组件共同构成了一个完整的多代理工作流管理生态系统，每个组件专注于特定的功能域，通过定义良好的接口进行通信和协作。\n\n```mermaid\ngraph TD\n AMP[AgentManagerProvider] --> WM[WorktreeManager]\n AMP --> RM[RunManager]\n AMP --> GP[GitOps]\n AMP --> TM[TerminalManager]\n AMP --> SH[SectionHandler]\n WM --> PR[PRStatusPoller]\n RM --> GP\n GP --> TM\n SH --> AMP\n TM --> AMP\n \n subgraph 核心功能域\n WM[工作树管理]\n RM[运行调度]\n GP[Git运维]\n TM[终端控制]\n end\n \n subgraph 监控与协调\n PR[PR轮询]\n SH[分区处理]\n end\n```\n\n### AgentManagerProvider 提供器\n\nAgentManagerProvider 是整个 Agent Manager 系统的中央协调器，负责初始化、管理和协调所有子组件的生命周期。作为 VS Code 扩展的一部分，该提供器在扩展激活时初始化，并在整个扩展生命周期中保持运行状态。它维护着所有已注册代理的元数据、当前运行状态、以及与 VS Code 环境的集成接口。\n\n该提供器的核心职责包括：维护代理配置和状态、响应用户界面的操作请求、协调各子组件之间的通信、以及处理错误和异常情况。它通过 VS Code 的 Webview API 与前端 UI 进行双向通信，确保用户能够实时监控和控制代理的运行状态。此外，它还负责管理与 OpenCode 内核的连接，将用户的操作请求转发到后端执行。\n\nAgentManagerProvider 的设计遵循了依赖注入模式，使得各子组件可以独立开发和测试，同时也便于扩展新的功能模块。每个子组件都通过接口定义与提供器交互，这种松耦合的设计提高了系统的可维护性和可测试性。\n\n### WorktreeManager 工作树管理器\n\nWorktreeManager 是 Agent Manager 中负责 Git 工作树管理的核心组件。Git 工作树机制允许开发者在同一个 Git 仓库中创建多个工作目录，每个工作目录可以绑定到不同的分支。这种机制对于多代理协作开发至关重要，因为它允许不同的代理在完全隔离的环境中并行工作，而不会产生分支冲突或工作进度相互覆盖的问题。\n\n工作树管理器的主要功能包括：创建新的工作树并绑定到指定的分支、列出当前仓库中的所有工作树、清理已完成任务的工作树、以及在需要时自动合并或删除过期的分支。当一个代理需要处理特定功能或修复某个问题时，WorktreeManager 会为其分配一个独立的工作树，确保其工作不会影响其他代理的活动分支。\n\n该组件还负责监控工作树的状态变化，当检测到工作树中的文件发生变化时，会自动通知相关的代理进行相应的处理。这种事件驱动的设计使得系统能够实时响应开发过程中的各种状态变化，保持代理对项目状态的准确理解。\n\n### RunManager 运行管理器\n\nRunManager 负责管理代理的启动、暂停、恢复和终止等生命周期操作。它维护着一个运行队列，调度各个代理任务的执行顺序，并根据系统资源和任务优先级进行合理的资源分配。当用户启动一个代理时，RunManager 会负责初始化代理的运行环境、加载必要的配置和上下文信息、并监控代理的运行状态。\n\n运行管理器的核心特性包括：支持任务的优先级调度、支持任务的依赖关系声明、支持任务执行超时控制、以及支持任务的自动重试机制。当某个任务因为网络故障或其他临时性问题失败时，RunManager 可以根据配置自动重试，减少人工干预的需要。此外，它还支持任务的暂停和恢复功能，这在需要临时中断开发工作或等待外部依赖时非常有用。\n\nRunManager 与其他组件紧密集成，例如它会调用 WorktreeManager 为每个运行的代理分配隔离的工作环境，并通过 GitOps 组件确保所有操作都被正确地记录到 Git 历史中。这种集成设计确保了多代理系统的行为一致性和可追溯性。\n\n### PRStatusPoller PR 状态轮询器\n\nPRStatusPoller 是专门用于监控 Pull Request 状态的组件，它定期轮询远程代码托管平台（如 GitHub、GitLab）的 API，获取 PR 的最新状态信息。这些信息包括 CI/CD 管道的执行结果、代码审查的反馈意见、以及 PR 的合并状态等。轮询器将这些信息汇总后，通过 AgentManagerProvider 分发给相关的代理，使其能够根据最新的 PR 状态做出相应的响应。\n\nPR 状态轮询器支持多种轮询策略：定时轮询（固定间隔）、智能轮询（根据 PR 状态变化频率动态调整间隔）、以及事件驱动轮询（仅在特定事件发生时触发）。默认情况下，轮询器会优先使用智能轮询策略，以减少不必要的 API 调用，同时确保代理能够及时获取重要的状态变化通知。\n\n该组件还实现了背压（Backpressure）控制机制，防止在短时间内大量状态变化导致系统过载。当检测到异常大量的状态变化时，轮询器会自动降低轮询频率，并在状态稳定后逐步恢复正常。这种设计既保证了系统的响应性，又避免了因过度轮询而被远程 API 限流。\n\n### GitOps Git 运维操作\n\nGitOps 组件封装了所有与 Git 仓库操作相关的功能，包括分支创建、提交管理、冲突解决、以及远程同步等。该组件的设计目标是提供一套统一、可靠且可审计的 Git 操作接口，使代理能够以声明式的方式执行各种 Git 操作，而无需关心底层的实现细节。\n\nGitOps 的核心功能包括：自动化的提交消息生成（基于变更内容生成符合规范的提交信息）、智能的分支命名策略（根据任务类型和目标自动生成描述性的分支名）、变更暂存和提交的原子操作保证、以及冲突检测和自动解决（对于简单的冲突能够自动合并，复杂的冲突则通知相关代理进行人工处理）。\n\n该组件还维护着一个操作日志，记录所有 Git 操作的详细信息，包括执行时间、操作类型、操作者（代理标识）、变更的文件列表、以及操作的结果状态。这个日志不仅用于故障排查和审计，还可以通过可视化界面展示给用户，帮助其理解系统的行为和代理的工作进展。\n\n### TerminalManager 终端管理器\n\nTerminalManager 负责管理 VS Code 终端实例，为代理提供命令执行的能力。每个运行的代理都可以拥有自己的终端实例，终端管理器确保这些终端的正确创建、配置和清理。当代理需要执行 shell 命令时（如运行测试、构建项目、或执行部署脚本），终端管理器会分配一个可用的终端实例，并负责捕获命令的输出结果。\n\n终端管理器还实现了输出缓冲和流控制机制，确保即使在命令产生大量输出的情况下，系统也能保持响应。它支持多种终端类型和 shell 环境，并能够根据操作系统自动选择合适的默认 shell。此外，它还提供了终端复用功能，当多个命令需要在同一个 shell 会话中执行时，可以共享同一个终端实例，保持命令之间的上下文关联。\n\n该组件还负责终端的安全管理，通过沙箱机制限制命令的权限范围，防止恶意或有风险的命令被执行。同时，它会记录每个终端会话的完整历史，供后续的调试和审计使用。\n\n### SectionHandler 分区处理器\n\nSectionHandler 负责处理代理会话中的结构化数据分区。在多代理系统中，不同的代理可能需要访问会话的不同部分，而 SectionHandler 提供了对这些分区的访问控制和状态管理。该组件确保每个代理只能看到和修改其被授权的会话分区，防止未授权的信息泄露或操作干扰。\n\n分区处理器支持动态分区创建、分区间的消息传递、以及分区的合并和拆分。当一个复杂的任务被分解为多个子任务分配给不同的代理时，SectionHandler 会为每个子任务创建独立的分区，确保子代理之间的工作不会相互影响。任务完成后，相关的分区可以被合并，形成完整的结果报告。\n\n## 工作流机制\n\n### 多代理协作流程\n\nAgent Manager 的多代理协作机制是其最具特色的功能之一。当用户启动一个复杂的开发任务时，系统会根据配置自动创建或选择一个合适的代理来处理该任务。代理可以进一步将任务分解为子任务，并分配给其他专门化的代理执行。这种层级式的任务分解和分配机制，使得系统能够处理从简单的代码修复到复杂的系统重构等各种规模的任务。\n\n```mermaid\ngraph LR\n User[用户请求] --> AP[AgentManagerProvider]\n AP --> ModeSelect[模式选择]\n ModeSelect --> AgentCreate[代理创建]\n AgentCreate --> WorktreeAlloc[工作树分配]\n WorktreeAlloc --> TaskExec[任务执行]\n TaskExec --> GitOpsLog[GitOps记录]\n GitOpsLog --> PRCheck{PR状态检查}\n PRCheck -->|需要审查| Review[代码审查]\n PRCheck -->|完成| Merge[合并分支]\n Review --> AgentCreate\n Merge --> TerminalExec[终端命令执行]\n TerminalExec --> TaskExec\n \n subgraph 代理协作\n ModeSelect\n AgentCreate\n WorktreeAlloc\n end\n \n subgraph 质量保障\n GitOpsLog\n PRCheck\n Review\n end\n```\n\n多代理协作的关键在于协调机制的设计。Agent Manager 提供了多种协调策略：中央协调模式（由一个主代理负责任务分配和结果汇总）、分布式协调模式（各代理通过消息传递自主协调）、以及混合模式（根据任务特点动态选择协调方式）。系统会根据任务的复杂度和代理的数量自动选择最合适的协调模式。\n\n### 代理权限控制\n\n代理权限控制是 Agent Manager 安全架构的核心组成部分。每个代理在创建时都会被分配一组权限定义，这些权限决定了代理可以执行的操作类型和可以访问的资源范围。权限定义采用灵活的规则匹配语法，支持通配符和否定模式，能够精确地控制代理对文件和操作的访问。\n\n从源码中可以看到权限配置的结构示例：\n\n```typescript\npermission: {\n \"*\": \"deny\", // 默认拒绝所有操作\n read: \"allow\", // 允许读取文件\n grep: \"allow\", // 允许搜索文件内容\n glob: \"allow\", // 允许文件模式匹配\n edit: { // 编辑操作特殊规则\n \"*\": \"deny\", \n \"**/*.md\": \"allow\" // 仅允许编辑 Markdown 文件\n },\n bash: \"deny\", // 拒绝终端命令\n task: \"ask\", // 任务创建需要确认\n skill: \"deny\" // 拒绝使用技能\n}\n```\n\n这种细粒度的权限控制机制确保了系统安全性，即使某个代理被利用或配置错误，其潜在的破坏范围也被限制在最小范围内。同时，权限规则支持继承和覆盖，子规则可以覆写父规则的设置，使得权限配置既简洁又灵活。\n\n### 模式切换与专用代理\n\nAgent Manager 支持多种工作模式（Mode），每种模式对应不同的代理类型和配置。最常用的模式包括：\n\n- **Architect 模式**：专注于系统架构设计和规划，负责理解需求、制定技术方案\n- **Coder 模式**：负责代码编写和实现，执行具体的开发任务\n- **Reviewer 模式**：专门进行代码审查，发现潜在的 Bug 和改进点\n- **Debugger 模式**：专注于问题定位和修复，执行调试任务\n\n用户可以通过斜杠命令（Slash Command）快速切换模式，例如 `/mode coder` 切换到编码模式，`/variant fast` 切换到快速推理变体。这些快捷命令简化了工作流程的操作步骤，提高了开发效率。\n\n专用代理（Dedicated Agent）是为特定任务或项目定制的代理实例，拥有专门的提示词、工具配置和权限设置。用户可以在配置文件中定义自己的代理模板，也可以在 VS Code 界面中通过向导创建和编辑代理配置。Agent Manager 的 webview 界面提供了直观的代理管理模式，包括创建、编辑、删除和权限配置等操作。\n\n## 配置管理\n\n### kilo.json 配置结构\n\nAgent Manager 的配置通过 `kilo.json`（或 `kilo.jsonc`）文件管理，采用分层配置机制，支持远程配置、全局配置、项目配置和即时配置等多种来源。配置项按照优先级从低到高依次应用，后面的配置会覆盖前面的同名配置项。\n\n配置搜索路径按照以下顺序查找：远程 well-known 配置、全局配置（`~/.config/kilo/kilo.json`）、环境变量 `KILO_CONFIG`、项目根目录配置（`./kilo.json`）、`.kilo/kilo.json` 目录配置、以及 `KILO_CONFIG_CONTENT` 环境变量内容。这种设计确保了配置既有足够的灵活性，又保持了清晰的优先级关系。\n\n代理配置的关键字段包括：代理名称（name）、描述（description）、提示词（prompt）、使用的模型（model）、工具列表（tools）、权限规则（permission）、以及启动和运行脚本（setup/run scripts）。这些字段共同定义了代理的行为特征和能力边界。\n\n### 命令配置（Commands）\n\n命令是通过 Markdown 文件定义的自动化任务脚本，存储在 `.kilo/commands/` 目录中。每个命令文件包含 YAML 前置元数据和 Markdown 格式的命令体。元数据定义命令的元信息，如描述、关联的代理、使用的模型等；命令体包含实际的任务指令，可以使用模板变量引用参数。\n\n命令文件的结构示例：\n\n```yaml\n---\ndescription: 运行测试并修复失败\nagent: code\nmodel: anthropic/claude-sonnet\nsubtask: true\n---\n运行所有测试在 $1 并修复失败。\n使用 $ARGUMENTS 获取完整参数。\n通过 @file 引用文件，通过 !`cmd` 引用命令输出。\n```\n\n模板变量支持位置参数（`$1`、`$2` 等）、完整参数（`$ARGUMENTS`）、文件引用（`@file`）、以及命令输出引用（`!`cmd``）。这种参数化设计使得同一个命令模板可以灵活地处理不同的输入场景。\n\n## 工具注册与扩展\n\n### 工具注册表架构\n\nAgent Manager 通过统一的工具注册表（Tool Registry）管理所有可用的工具扩展。工具注册表维护着一个工具定义列表，每个定义包含工具的唯一标识符、名称、描述、参数模式、以及执行函数。当代理需要使用某个工具时，注册表负责验证参数、执行工具逻辑、并返回结果给调用者。\n\n工具注册支持条件注册机制，通过 `agent_manager_tool` 标记控制工具在特定上下文中的可见性。例如，某些工具可能仅在 Agent Manager 模式下可用，而在普通编辑模式下被隐藏。这种条件注册确保了工具的合理使用场景，避免了功能滥用。\n\n注册表还提供了工具描述增强功能，可以根据额外的上下文信息（如语义搜索结果）自动丰富工具的描述信息。这种动态描述增强有助于代理更准确地理解工具的用途和使用方法，提高工具选择的准确性。\n\n### MCP 服务器集成\n\nAgent Manager 通过 MCP（Model Context Protocol）服务器市场支持第三方工具扩展集成。用户可以浏览、搜索和安装来自社区的 MCP 服务器，扩展代理的工具能力。安装过程通过 VS Code 界面的引导式向导完成，包括依赖检查、参数配置和权限确认等步骤。\n\nMCP 服务器的安装支持前置条件检查，例如某些服务器可能需要特定的 Node.js 版本或操作系统依赖。前置条件未满足时，向导会显示警告信息，并指导用户进行必要的准备工作。安装完成后，服务器会自动注册其提供的工具到全局注册表中，供所有代理使用。\n\n## Webview UI 交互\n\n### 迁移向导界面\n\nAgent Manager 提供了直观的 Webview 用户界面，用于代理的创建、配置和管理。迁移向导（Migration Wizard）是用户首次使用时会接触到的引导界面，展示了新版本的主要功能特性，包括性能提升、界面改进和 Agent Manager 增强等模块。\n\n向导界面通过模块化的卡片布局展示功能特性，每个卡片包含图标、标题和详细说明。用户可以通过\"了解更多\"链接访问官方文档或博客文章，深入了解各项功能的细节。向导的底部提供了继续按钮，点击后进入主界面开始使用 Agent Manager。\n\n### 代理管理界面\n\n代理管理界面提供了对所有已配置代理的完整视图，支持创建新代理、编辑现有代理、调整权限配置、以及删除不需要的代理。每个代理的配置通过表单界面进行编辑，包括基本信息（名称、描述）、提示词配置、模型选择、工具启用和权限规则设置等。\n\n界面还提供了代理的使用统计信息，包括已执行的命令数量、成功率和平均响应时间等指标。这些统计数据帮助用户评估代理的效率，并根据需要进行调优。此外，界面支持代理配置的导入和导出，方便在团队成员之间共享标准化的代理模板。\n\n## 数据流与状态管理\n\n### 会话状态同步\n\nAgent Manager 通过 VS Code 的消息传递机制实现 Webview 与扩展后端之间的状态同步。Webview 发送操作请求（如启动代理、切换模式），后端执行相应操作并通过消息推送状态更新到前端。这种双向通信机制确保了用户界面的实时性和一致性。\n\n状态管理采用集中式设计，所有会话状态（包括代理列表、运行状态、任务队列等）由 AgentManagerProvider 统一维护。前端通过订阅感兴趣的状态变更事件，在状态变化时自动重新渲染界面组件。这种响应式的状态管理简化了前端代码的复杂度，同时保证了数据的一致性。\n\n### 文件变更监控\n\n文件变更监控通过 `useFileMention` hook 实现，它监听编辑器中的文件提及事件，提供文件搜索、路径解析和附件管理功能。当用户在输入中引用文件路径时，hook 会自动触发文件搜索，返回匹配的文件列表供用户选择。\n\n文件提及系统支持多种类型的内容：普通文件、文件夹、终端会话、Git 变更等。每种类型都有对应的图标和展示格式，确保用户能够快速识别所选内容的性质。系统还支持拖拽添加文件路径，以及通过命令行自动补全功能快速插入文件引用。\n\n## 最佳实践\n\n### 代理设计原则\n\n设计高效的代理应遵循以下原则：单一职责（每个代理专注于特定类型的任务）、最小权限（仅授予完成任务所需的最小权限集）、清晰边界（明确定义代理之间的交互接口）、以及可观测性（确保代理行为可追踪和可调试）。\n\n对于复杂的多代理场景，建议采用渐进式分解策略：首先识别任务的主要阶段，然后为每个阶段设计专门的代理，最后定义代理之间的协作协议。这种方法既保证了系统的模块化，又避免了过早的复杂性引入。\n\n### 权限配置建议\n\n权限配置应遵循白名单原则（默认拒绝、按需开放）而非黑名单原则（默认允许、按需限制）。这种设计可以最大程度地减少安全风险，即使配置出现疏漏，未明确授权的操作也会被拒绝。\n\n对于涉及危险操作的工具（如删除文件、执行系统命令），建议设置为需要确认（`ask`），让用户在执行前有机会审查操作的影响。同时，应定期审查代理的权限配置，确保权限设置与实际需求保持一致，及时撤销不再需要的权限。\n\n## 常见问题与故障排除\n\n### 工作树冲突处理\n\n当多个代理在相同分支上工作时，可能会产生工作树冲突。如果两个代理尝试在同一个工作树中执行操作，系统会检测到冲突并自动将其中一个代理重新分配到新的工作树。如果仓库的工作树数量达到上限，系统会提示用户清理不再需要的工作树。\n\n手动解决冲突的方法包括：使用 `git worktree remove` 命令删除过期的分支，通过 `git branch -d` 删除已合并的分支，以及使用 VS Code 的 Git 图形界面查看和清理工作树状态。\n\n### 代理无响应处理\n\n如果代理长时间无响应，首先检查终端输出是否正常显示，可以通过 TerminalManager 查看命令的执行状态。如果命令本身在等待外部输入，代理会一直阻塞直到收到输入或超时。\n\n对于卡死的代理，可以尝试通过界面手动终止其任务，系统会自动清理相关的工作树和临时文件。如果问题持续发生，建议检查代理配置是否正确，特别是涉及网络请求的配置项（如代理设置、超时时间等）。\n\n---\n\n*本文档由 Kilo 官方技术团队维护，如有更新请参考 GitHub 仓库中的最新源码。*\n\n---\n\n\n\n## MCP 协议与工具集成\n\n### 相关页面\n\n相关主题：[Agent 核心系统](#agent-system), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [packages/opencode/src/kilocode/tool/registry.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/kilocode/tool/registry.ts)\n- [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)\n- [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)\n- [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)\n
\n\n# MCP 协议与工具集成\n\n## 概述\n\nMCP（Model Context Protocol，模型上下文协议）是 KiloCode 中用于扩展 AI 能力的关键协议层。它允许 KiloCode 与外部工具和服务进行标准化通信，使 AI 能够调用文件系统操作、代码搜索、Shell 命令等能力。KiloCode 的 MCP 集成架构采用了模块化设计，将协议处理、工具注册、认证授权等核心功能解耦，确保系统的可扩展性和可维护性。\n\n## 架构设计\n\n### 整体架构\n\nKiloCode 的 MCP 系统采用分层架构，包括协议层、工具层、认证层和 UI 集成层四个主要部分。\n\n```mermaid\ngraph TD\n A[用户交互层] --> B[TUI/Session 组件]\n B --> C[MCP 协议处理]\n C --> D[工具注册表]\n D --> E[文件系统工具]\n D --> F[代码搜索工具]\n D --> G[Shell 工具]\n C --> H[认证授权模块]\n H --> I[OAuth 提供者]\n H --> J[Token 管理]\n E --> K[VSCode 集成]\n F --> K\n G --> K\n```\n\n### 核心模块关系\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 入口 | `packages/opencode/src/mcp/index.ts` | MCP 协议初始化和核心处理 |\n| 工具注册表 | `packages/opencode/src/kilocode/tool/registry.ts` | 工具定义、描述和注册 |\n| OAuth 提供者 | `packages/opencode/src/mcp/oauth-provider.ts` | OAuth 2.0 认证流程 |\n| 认证模块 | `packages/opencode/src/mcp/auth.ts` | Token 管理和安全验证 |\n| MCP 配置 | `packages/opencode/src/config/mcp.ts` | 配置管理和环境变量 |\n\n## 工具注册系统\n\n### 工具注册表架构\n\n工具注册表是 KiloCode MCP 集成的核心组件，负责管理所有可用的工具定义。每个工具都包含唯一标识符、描述信息、执行逻辑和参数模式。注册表支持动态添加和移除工具，使系统能够在运行时扩展功能。\n\n在 `packages/opencode/src/kilocode/tool/registry.ts` 中，工具注册通过 `Tool.Def` 类型定义，支持为工具添加额外的元数据标记，如 `agent_manager_tool` 标志用于标识需要代理管理器参与的工具。\n\n### 核心工具类型\n\nKiloCode 实现了多种类型的核心工具，覆盖了日常开发中的常见需求。\n\n```mermaid\ngraph LR\n A[工具请求] --> B{工具类型判断}\n B -->|文件操作| C[Read/Write 工具]\n B -->|Shell| D[Bash 工具]\n B -->|搜索| E[Grep 工具]\n C --> F[文件系统]\n D --> G[系统命令]\n E --> H[代码索引]\n```\n\n| 工具名称 | 源文件 | 功能描述 |\n|----------|--------|----------|\n| bash | `packages/opencode/src/tool/bash.ts` | 执行 Shell 命令和脚本 |\n| read | `packages/opencode/src/tool/read.ts` | 读取文件内容和元数据 |\n| write | `packages/opencode/src/tool/write.ts` | 创建和修改文件 |\n| grep | `packages/opencode/src/tool/grep.ts` | 代码搜索和模式匹配 |\n| glob | 注册表中定义 | 文件名模式匹配 |\n| 代理管理 | registry.ts:工具注册 | 多代理协同任务管理 |\n\n### 工具描述增强\n\n工具注册表提供了 `describe` 函数用于增强工具描述。该函数根据上下文条件为特定工具添加额外的使用提示信息，帮助 AI 更好地理解工具的使用场景和参数要求。\n\n资料来源：[packages/opencode/src/kilocode/tool/registry.ts:工具注册]()\n\n## MCP 状态管理\n\n### TUI 状态显示\n\n在 KiloCode 的终端用户界面中，MCP 连接状态通过状态栏组件实时展示。用户可以直观地了解当前 MCP 连接的健康状况和错误状态。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP状态显示]()\n\n状态显示组件实现了以下功能：\n\n- **连接状态指示器**：使用圆形图标表示连接状态，绿色表示正常，红色表示错误\n- **MCP 服务计数**：显示当前活跃的 MCP 服务数量\n- **错误状态展示**：当 MCP 服务出现错误时显示警告信息\n\n```mermaid\nstateDiagram-v2\n [*] --> Disconnected: 初始状态\n Disconnected --> Connecting: 用户连接\n Connecting --> Connected: 连接成功\n Connecting --> Error: 连接失败\n Connected --> Disconnected: 用户断开\n Connected --> Error: 服务异常\n Error --> Connecting: 重试连接\n Error --> Disconnected: 放弃连接\n```\n\n### 文件提及系统\n\n文件提及（Mention）是 KiloCode 中用于快速引用文件和目录的功能。该系统与 MCP 集成，允许用户通过 `@` 符号快速选择项目中的文件。\n\n资料来源：[packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:文件提及Hook]()\n\n文件提及系统的核心流程包括：\n\n1. **搜索触发**：用户输入 `@` 符号激活搜索\n2. **异步搜索**：通过 MCP 协议向 VSCode 扩展发送搜索请求\n3. **结果缓存**：使用 `frecency` 算法优化搜索结果的排序和缓存\n4. **路径解析**：将相对路径转换为绝对路径供后续处理使用\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as 终端界面\n participant Hook as useFileMention\n participant MCP as MCP 协议层\n participant VSCode as VSCode 扩展\n \n User->>TUI: 输入 @ 触发搜索\n TUI->>Hook: 调用 setMentionQuery\n Hook->>MCP: 发送 fileSearchResult 请求\n MCP->>VSCode: 转发搜索请求\n VSCode-->>MCP: 返回文件列表\n MCP-->>Hook: 传递搜索结果\n Hook-->>TUI: 更新 mentionResults\n TUI-->>User: 显示下拉列表\n```\n\n## 配置管理\n\n### MCP 配置结构\n\nMCP 配置通过 `packages/opencode/src/config/mcp.ts` 统一管理，支持从环境变量和配置文件两个渠道读取配置参数。\n\n| 配置项 | 类型 | 说明 | 来源 |\n|--------|------|------|------|\n| mcp_servers | string[] | 启用的 MCP 服务器列表 | 环境变量 |\n| mcp_timeout | number | 请求超时时间（毫秒） | 配置文件 |\n| mcp_retry | number | 失败重试次数 | 配置文件 |\n| oauth_config | object | OAuth 认证配置 | 配置文件 |\n\n### 认证配置\n\nKiloCode 支持 OAuth 2.0 认证协议，用于安全地与外部服务建立连接。认证模块包含令牌管理、刷新机制和安全存储等功能。\n\n资料来源：[packages/opencode/src/mcp/auth.ts:认证模块]()\n资料来源：[packages/opencode/src/mcp/oauth-provider.ts:OAuth提供者]()\n\n## 自动补全集成\n\n### 提示词自动补全\n\n在终端界面的提示词输入组件中，MCP 工具的自动补全功能被深度集成。用户输入特定前缀时，系统会通过 MCP 协议获取可用的工具列表，并在下拉菜单中展示。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:自动补全逻辑]()\n\n### 文件提及与 MCP 交互\n\n自动补全组件与文件提及系统紧密协作。当用户引用文件时，组件会：\n\n1. 解析文件路径并确定基础目录\n2. 判断路径是绝对路径还是相对路径\n3. 通过 MCP 协议获取文件信息\n4. 更新编辑器的标记（extmark）以高亮显示引用\n\n```mermaid\nflowchart TD\n A[用户输入 /] --> B{输入内容判断}\n B -->|@符号| C[激活文件提及]\n B -->|工具前缀| D[激活工具补全]\n B -->|普通文本| E[普通输入处理]\n C --> F[MCP 文件搜索]\n D --> G[MCP 工具列表]\n F --> H[更新提及索引]\n G --> I[显示工具选项]\n H --> J[用户选择]\n I --> J\n J --> K[插入引用内容]\n K --> L[创建文件部分]\n```\n\n## 错误处理机制\n\n### MCP 错误状态\n\n当 MCP 服务出现错误时，状态栏会显示错误指示器。系统会区分不同类型的错误，并提供相应的用户反馈。\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:MCP错误状态]()\n\n错误处理策略包括：\n\n- **连接失败**：显示重试选项，用户可手动触发重新连接\n- **认证过期**：自动触发 Token 刷新流程\n- **服务不可用**：标记服务状态并在工具列表中隐藏不可用项\n- **超时错误**：根据配置的重试策略自动重试\n\n## 与 VSCode 扩展的集成\n\n### 通信机制\n\nKiloCode 的 MCP 系统通过 VSCode 扩展提供的消息通道与编辑器进行双向通信。Webview UI 中的 React 组件使用特定的 Hook 与 MCP 后端交互。\n\n文件提及功能的实现涉及多个层次的协作：\n\n1. **UI 层**：`useFileMention` Hook 管理搜索状态和结果\n2. **通信层**：通过 `onMessage` 回调处理来自扩展的消息\n3. **协议层**：MCP 协议定义消息格式和路由规则\n4. **后端层**：VSCode 扩展执行实际的文件系统操作\n\n## 扩展性设计\n\n### 添加新工具\n\nKiloCode 的工具注册系统设计支持便捷的功能扩展。添加新工具的流程包括：\n\n1. 在 `packages/opencode/src/tool/` 目录下创建新的工具文件\n2. 定义工具的输入输出模式\n3. 在 `registry.ts` 中注册工具定义\n4. 添加工具的执行逻辑\n5. 在 UI 层添加对应的补全支持\n\n### MCP 服务器配置\n\n外部 MCP 服务器可以通过配置文件或环境变量添加到 KiloCode。系统支持热加载配置，无需重启即可启用新的 MCP 服务。\n\n## 最佳实践\n\n### 开发新工具\n\n| 阶段 | 关键点 | 参考文件 |\n|------|--------|----------|\n| 设计 | 明确输入输出类型和错误处理 | `packages/opencode/src/tool/read.ts` |\n| 实现 | 遵循现有工具的文件结构 | `packages/opencode/src/tool/bash.ts` |\n| 注册 | 在 registry 中添加工具定义 | `packages/opencode/src/kilocode/tool/registry.ts` |\n| 测试 | 使用 MCP 协议测试工具调用 | - |\n| 文档 | 更新自动补全的提示文本 | `packages/opencode/src/cli/cmd/tui/component/prompt/` |\n\n### 故障排查\n\n常见的 MCP 相关问题及排查方向：\n\n- **工具不可用**：检查工具是否在注册表中正确注册\n- **搜索无结果**：验证 MCP 服务器连接状态\n- **认证失败**：检查 OAuth 配置和 Token 有效期\n- **状态显示异常**：查看 TUI 状态栏的错误信息\n\n---\n\n\n\n## 代码索引与语义搜索\n\n### 相关页面\n\n相关主题：[自动补全系统 (FIM)](#autocomplete-system), [Agent 核心系统](#agent-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-indexing/src/indexing/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/index.ts)\n- [packages/kilo-indexing/src/indexing/manager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/manager.ts)\n- [packages/kilo-indexing/src/indexing/orchestrator.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/orchestrator.ts)\n- [packages/kilo-indexing/src/tree-sitter/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/index.ts)\n- [packages/kilo-indexing/src/tree-sitter/languageParser.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/tree-sitter/languageParser.ts)\n- [packages/kilo-indexing/src/indexing/embedders/openai.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-indexing/src/indexing/embedders/openai.ts)\n- [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)\n- [packages/opencode/src/tool/semantic-search.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/tool/semantic-search.ts)\n
\n\n# 代码索引与语义搜索\n\n## 概述\n\nKiloCode 的代码索引与语义搜索系统是一个多层次的代码理解和检索解决方案，旨在为开发者提供基于代码语义的高效搜索能力。该系统通过集成 Tree-sitter 语法解析、向量嵌入和语义向量存储技术，实现了对代码库的深度索引，使得开发者可以使用自然语言描述来查找相关代码片段。\n\n该系统位于 `packages/kilo-indexing` 包中，作为 KiloCode 平台的核心基础设施之一，为 IDE 扩展和 CLI 工具提供统一的代码理解能力。\n\n## 系统架构\n\n### 核心组件\n\n代码索引与语义搜索系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责描述 |\n|------|----------|----------|\n| 索引管理器 | `packages/kilo-indexing/src/indexing/manager.ts` | 协调和管理整个索引生命周期 |\n| 索引协调器 | `packages/kilo-indexing/src/indexing/orchestrator.ts` | 编排增量索引和全量索引任务 |\n| Tree-sitter 解析器 | `packages/kilo-indexing/src/tree-sitter/languageParser.ts` | 解析多种编程语言的语法树 |\n| 向量嵌入器 | `packages/kilo-indexing/src/indexing/embedders/openai.ts` | 生成代码片段的语义向量 |\n| 向量存储 | `packages/kilo-indexing/src/indexing/vector-store/lancedb-vector-store.ts` | 存储和检索向量数据 |\n| 语义搜索工具 | `packages/opencode/src/tool/semantic-search.ts` | 提供给 LLM 调用的搜索接口 |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[源代码文件] --> B[Tree-sitter 解析器]\n B --> C[语法树节点]\n C --> D[代码分块策略]\n D --> E[代码片段]\n E --> F[OpenAI 嵌入器]\n F --> G[语义向量]\n G --> H[LanceDB 向量存储]\n \n I[用户查询] --> J[语义搜索工具]\n J --> K[查询向量生成]\n K --> H\n H --> L[相似度匹配]\n L --> M[搜索结果排序]\n M --> N[返回相关代码片段]\n```\n\n## 索引管理\n\n### 索引生命周期\n\n索引管理器负责处理代码库从初始扫描到增量更新的完整生命周期。系统支持增量索引策略，仅对修改过的文件进行重新索引，以优化性能并减少资源消耗。\n\n索引状态在用户界面中实时显示，状态信息包括当前索引进度、已索引文件数量和索引完成百分比。系统会根据索引状态调整配色方案，使用不同色调传达当前索引状态。\n\n```typescript\n// 索引状态显示逻辑示例\n\n \n {indexingText(indexing()).slice(0, 48)}\n \n\n```\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx]()\n\n### 向量存储\n\n系统使用 LanceDB 作为底层向量存储解决方案，这是一种专为机器学习应用设计的高性能嵌入式数据库。向量存储负责持久化代码片段的语义向量表示，并支持高效的相似度搜索查询。\n\n向量存储的数据模型包含以下关键字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| code | string | 原始代码文本 |\n| embedding | float[] | 语义向量 |\n| filePath | string | 文件路径 |\n| language | string | 编程语言 |\n| startLine | number | 代码块起始行 |\n| endLine | number | 代码块结束行 |\n| symbols | string[] | 提取的符号信息 |\n\n## 语法解析\n\n### Tree-sitter 集成\n\nTree-sitter 是 KiloCode 代码索引系统的语法分析引擎，提供了增量解析能力，能够高效处理大型代码库。系统支持多种主流编程语言的语法解析，包括 JavaScript、TypeScript、Python、Go、Rust 等。\n\n语法解析器将源代码转换为抽象语法树（AST），在此基础上进行代码分块和符号提取。分块策略是影响搜索质量的关键因素，系统会根据语言特性采用不同的分块方法，确保每个代码片段具有完整的语义上下文。\n\n### 语言解析器配置\n\n每种编程语言都有对应的解析器配置文件，定义了语言特定的语法规则和代码块边界识别逻辑。语言解析器还负责提取代码中的关键符号信息，包括函数名、类名、变量名等，这些信息用于增强搜索匹配的准确性。\n\n## 向量嵌入\n\n### OpenAI 嵌入集成\n\n系统使用 OpenAI 的文本嵌入模型将代码片段转换为高维向量。嵌入器负责将原始代码文本转换为固定维度的浮点数向量，这些向量捕捉了代码的语义特征，使得语义相似的代码在向量空间中彼此接近。\n\n嵌入器配置支持以下参数：\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| model | string | text-embedding-3-small | OpenAI 嵌入模型名称 |\n| dimensions | number | 1536 | 向量维度 |\n| batchSize | number | 100 | 批处理大小 |\n\n### 向量生成流程\n\n代码片段经过预处理后被发送到 OpenAI API 进行嵌入。预处理步骤包括移除注释、规范化空白字符和添加语言提示信息。语言提示帮助嵌入模型更好地理解代码语义，提高跨语言代码搜索的准确性。\n\n## 语义搜索\n\n### 搜索接口\n\n语义搜索通过专门的工具接口暴露给 LLM，LLM 可以调用该工具进行代码搜索。搜索接口接受自然语言查询，返回与查询意图最相关的代码片段及其在代码库中的位置信息。\n\n```typescript\n// 语义搜索工具配置\nToolRegistry.register({\n name: \"semantic_search\",\n // 搜索工具实现\n})\n```\n\n资料来源：[packages/opencode/src/tool/semantic-search.ts]()\n\n### 搜索结果排序\n\n搜索结果根据向量相似度分数进行排序，系统返回最相关的 Top-N 个代码片段。每个结果包含文件路径、行号范围、代码内容和相似度分数。LLM 可以利用这些信息直接跳转到相关代码位置。\n\n### 搜索增强策略\n\n系统支持多种搜索增强策略以提高搜索结果质量：\n\n- **符号匹配增强**：优先返回包含查询关键词符号的代码片段\n- **上下文扩展**：返回代码片段时同时提供周围的上下文代码\n- **多语言支持**：跨语言搜索相关的代码实现\n- **过滤机制**：支持按文件类型、目录路径等条件过滤搜索结果\n\n## 配置与调优\n\n### 索引配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| enabled | boolean | true | 是否启用索引功能 |\n| maxFileSize | number | 1048576 | 单文件最大字节数 |\n| excludedPatterns | string[] | [\"node_modules\", \"dist\", \"build\"] | 排除的文件模式 |\n| indexInterval | number | 300000 | 增量索引间隔（毫秒） |\n| embeddingModel | string | text-embedding-3-small | 嵌入模型选择 |\n\n### 性能优化\n\n系统采用多级缓存策略减少重复计算，索引结果缓存在本地以支持快速重启。向量存储采用分区策略，按编程语言和目录结构进行数据分区，搜索时仅扫描相关分区以提高查询效率。\n\n## 使用场景\n\n### IDE 集成\n\n在 VS Code 扩展中，索引系统为以下功能提供支持：\n\n- 智能代码补全建议\n- 语义跳转定义\n- 查找引用\n- 相关代码推荐\n\n### CLI 工具\n\n在 TUI 界面的会话组件中，索引状态实时显示在底部状态栏，用户可以直观地了解当前代码库的索引进度和可用性状态。\n\n## 技术限制与注意事项\n\n- 向量嵌入依赖外部 API，网络延迟可能影响索引性能\n- 大型代码库的初始索引需要较长时间，建议在后台执行\n- 部分编程语言的语法解析可能不完全支持最新语言特性\n\n---\n\n\n\n## IDE 扩展实现\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [系统架构设计](#system-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/kilo-vscode/src/extension.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts)\n- [packages/kilo-vscode/webview-ui/src/App.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/webview-ui/src/App.tsx)\n- [packages/kilo-vscode/src/kilo-provider/KiloProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/kilo-provider/KiloProvider.ts)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n- [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)\n
\n\n# IDE 扩展实现\n\n## 概述\n\nKiloCode 是一个跨平台的 AI 编程助手，通过 IDE 扩展的形式集成到主流开发环境中。目前支持的 IDE 包括 Visual Studio Code 和 JetBrains 系列（如 IntelliJ IDEA、WebStorm 等）。\n\nIDE 扩展的核心职责包括：\n\n- **会话管理**：创建和管理与 AI 模型的交互会话\n- **编辑器集成**：在 IDE 中嵌入 WebView 用户界面\n- **文件操作**：监听文件变化、处理文件提及和附件\n- **工具调用**：注册和执行各种开发工具（如终端、Git、浏览器自动化等）\n- **命令系统**：支持斜杠命令（Slash Commands）和快捷操作\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[IDE 宿主] --> B[扩展后端]\n A --> C[扩展前端 WebView]\n B --> D[Kilo 后端服务]\n C --> B\n C --> E[本地文件操作]\n B --> F[AI 模型]\n F --> B\n```\n\n### VS Code 扩展架构\n\nVS Code 扩展采用双层架构设计：\n\n1. **后端层（Extension Host）**：运行在 Node.js 环境，负责与 VS Code API 和 Kilo 后端通信\n2. **前端层（WebView）**：运行在独立的 WebView 环境中，负责用户界面渲染\n\n```mermaid\ngraph LR\n A[VS Code API] --> B[Extension.ts]\n B --> C[KiloProvider]\n C --> D[WebView 通信]\n D --> E[App.tsx]\n E --> F[React 组件]\n F --> G[Hooks]\n G --> H[VSCodeContext]\n```\n\n### JetBrains 扩展架构\n\nJetBrains 扩展采用类似的分层设计，但使用不同的技术栈：\n\n```mermaid\ngraph TD\n A[JetBrains 平台] --> B[KiloToolWindowFactory]\n B --> C[KiloBackendAppService]\n C --> D[KiloSessionRpcApi]\n D --> E[RPC 通信层]\n E --> F[Kilo 后端服务]\n```\n\n## 核心组件\n\n### VS Code 扩展入口\n\n`packages/kilo-vscode/src/extension.ts` 是扩展的入口文件，负责初始化整个扩展：\n\n```typescript\n// 扩展激活入口\nexport function activate(context: ExtensionContext) {\n // 初始化 KiloProvider\n // 注册命令\n // 建立 WebView 通信通道\n}\n```\n\n主要职责：\n- 注册 VS Code 命令（如 `kilo.open`、`kilo.sendMessage`）\n- 初始化 `KiloProvider` 实例\n- 处理扩展生命周期事件\n\n### KiloProvider\n\n`KiloProvider` 是核心的状态管理和通信中心，位于 `packages/kilo-vscode/src/kilo-provider/KiloProvider.ts:1`：\n\n```typescript\n// KiloProvider 核心职责\n- 管理会话状态\n- 处理消息路由\n- 与后端服务通信\n- 管理文件搜索和提及\n```\n\n### WebView 应用\n\n`App.tsx` 是前端 WebView 的根组件，负责整体布局和状态协调：\n\n```typescript\n// App.tsx 核心功能\n- 提供全局上下文\n- 路由管理\n- 错误边界\n- 迁移向导集成\n```\n\n## 通信机制\n\n### WebView 与扩展后端的通信\n\nKiloCode 使用 `postMessage` API 实现 WebView 与扩展后端的双向通信：\n\n```mermaid\nsequenceDiagram\n participant W as WebView\n participant E as Extension Host\n participant B as Kilo Backend\n \n W->>E: postMessage({ type: \"fileSearchResult\", items })\n E->>B: 转发请求\n B->>E: 返回结果\n E->>W: postMessage({ type, data })\n```\n\n### 消息类型定义\n\n| 消息类型 | 方向 | 用途 |\n|---------|------|------|\n| `fileSearchResult` | 后端→前端 | 文件搜索结果 |\n| `openSettingsPanel` | 前端→后端 | 打开设置面板 |\n| `openExternal` | 前端→后端 | 打开外部链接 |\n| `toggleRemote` | 前端→后端 | 切换远程控制 |\n\n消息通过 `vscode.onMessage` 回调处理，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:24`：\n\n```typescript\nconst unsubscribe = vscode.onMessage((message) => {\n if (message.type !== \"fileSearchResult\") return\n if (message.requestId === `file-search-${fileSearchCounter}`) {\n const items = message.items ?? message.paths.map((path) => ({ path, type: \"file\" }))\n // 处理结果\n }\n})\n```\n\n## 核心功能模块\n\n### 文件提及系统\n\n`useFileMention` Hook 实现了智能文件提及功能，参考 `packages/kilo-vscode/webview-ui/src/hooks/useFileMention.ts:9`：\n\n```typescript\nexport function useFileMention(\n vscode: VSCodeContext,\n sessionID?: Accessor,\n git?: Accessor,\n): FileMention {\n const [mentionedPaths, setMentionedPaths] = createSignal>(new Set())\n const [mentionQuery, setMentionQuery] = createSignal(null)\n const [mentionResults, setMentionResults] = createSignal([])\n const [mentionIndex, setMentionIndex] = createSignal(0)\n \n // 文件搜索防抖处理\n let fileSearchTimer: ReturnType | undefined\n let fileSearchCounter = 0\n}\n```\n\n功能特性：\n- 实时文件搜索和建议\n- 支持 `@` 触发文件提及\n- 与 Git 状态集成\n- 拖拽文件自动注册\n\n### 斜杠命令系统\n\n`useSlashCommand` Hook 管理斜杠命令菜单，参考 `packages/kilo-vscode/webview-ui/src/hooks/useSlashCommand.ts:1`：\n\n```typescript\n// 可用命令列表\nconst commands = [\n {\n name: \"mode\",\n description: \"Switch the agent mode\",\n hints: [\"modes\"],\n action: () => {\n window.dispatchEvent(new CustomEvent(\"openModePicker\"))\n },\n },\n {\n name: \"variant\",\n description: \"Switch the reasoning effort\",\n hints: [\"variants\", \"reasoning\", \"thinking\"],\n action: () => {\n window.dispatchEvent(new CustomEvent(\"openVariantPicker\"))\n },\n },\n // ... 更多命令\n]\n```\n\n### 用户界面组件\n\n#### 迁移向导\n\n`MigrationWizard.tsx` 组件处理版本迁移引导，参考 `packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx:1`：\n\n```typescript\n// 新版本特性展示\n
\n
\n \n
{language.t(\"migration.whatsNew.features.performance.title\")}
\n
{language.t(\"migration.whatsNew.features.performance.detail\")}
\n
\n // ... 更多特性\n
\n```\n\n#### 设备授权卡片\n\n`DeviceAuthCard.tsx` 处理 OAuth 设备授权流程，参考 `packages/kilo-vscode/webview-ui/src/components/profile/DeviceAuthCard.tsx:1`：\n\n```typescript\n// 设备授权步骤\n
\n

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

\n
\n {deviceCode}\n
\n
\n```\n\n### MCP 市场集成\n\n`InstallModal.tsx` 组件实现 MCP 服务器的安装界面，参考 `packages/kilo-vscode/webview-ui/src/components/marketplace/InstallModal.tsx:1`：\n\n```typescript\n// 前置条件检查\n 0}>\n
    \n {(p) =>
  • {p}
    • }    \n
\n\n\n// 参数输入\n\n {(param) => (\n setParam(param.key, v)}\n />\n )}\n\n```\n\n## 文件操作集成\n\n### 输入提示组件\n\n`PromptInput.tsx` 处理用户输入和文件提及，参考 `packages/kilo-vscode/webview-ui/src/components/chat/PromptInput.tsx:1`：\n\n```typescript\n// 文件提及类型渲染\n\n {(item) => (\n
\n {item.type === \"terminal\" ? (\n <>\n \n {item.label}\n \n ) : item.type === \"git-changes\" ? (\n <>\n \n {item.label}\n \n ) : (\n <>\n \n {item.label}\n \n )}\n
\n )}\n\n```\n\n### 自动补全\n\n`autocomplete.tsx` 实现 TUI 界面的自动补全功能，参考 `packages/opencode/src/cli/cmd/tui/component/prompt/autocomplete.tsx:1`：\n\n```typescript\n// 文件部分处理\nif (part.type === \"file\" && part.source?.text) {\n part.source.text.start = extmarkStart\n part.source.text.end = extmarkEnd\n part.source.text.value = virtualText\n}\n\n// 更新访问频率用于排序\nif (part.type === \"file\" && part.source && part.source.type === \"file\") {\n frecency.updateFrecency(part.source.path)\n}\n```\n\n## JetBrains 扩展\n\n### 后端服务\n\n`KiloBackendAppService.kt` 是 JetBrains 扩展的后端服务：\n\n```kotlin\n// 主要职责\nclass KiloBackendAppService {\n // 会话管理\n // 与 Kilo 后端通信\n // 处理 IDE 事件\n}\n```\n\n### 工具窗口工厂\n\n`KiloToolWindowFactory.kt` 创建和管理工具窗口：\n\n```kotlin\nclass KiloToolWindowFactory : ToolWindowFactory {\n override fun createToolWindowContent(project: Project, toolWindow: ToolWindow) {\n // 创建工具窗口内容\n // 初始化通信通道\n }\n}\n```\n\n### RPC API\n\n`KiloSessionRpcApi.kt` 定义了会话 RPC 接口：\n\n```kotlin\ninterface KiloSessionRpcApi {\n // 发送消息\n // 接收响应\n // 管理会话状态\n}\n```\n\n## 配置管理\n\n### 配置优先级\n\n配置查找顺序（低优先级到高优先级）：\n\n| 优先级 | 来源 |\n|-------|------|\n| 1 | 远程已知配置 |\n| 2 | 全局配置 `~/.config/kilo/kilo.json` |\n| 3 | 环境变量 `KILO_CONFIG` |\n| 4 | 项目配置 `./kilo.json` |\n| 5 | 项目子目录 `.kilo/kilo.json` |\n| 6 | 内联环境变量 `KILO_CONFIG_CONTENT` |\n| 7 | 托管配置 |\n\n配置采用深度合并策略，后者覆盖前者。资料来源：[packages/opencode/src/kilocode/skills/kilo-config.md:1]()\n\n### 配置文件结构\n\n```yaml\n# 命令配置示例 (.kilo/command/*.md)\n---\ndescription: Run tests\nagent: code\nmodel: anthropic/claude-sonnet\nsubtask: true\n---\nRun all tests in $1 and fix failures.\n```\n\n## 状态管理\n\n### 状态类型\n\n| 状态类型 | 说明 |\n|---------|------|\n| `mentionedPaths` | 当前会话中提及的文件路径集合 |\n| `mentionQuery` | 文件搜索查询字符串 |\n| `mentionResults` | 文件搜索结果列表 |\n| `mentionIndex` | 当前选中的建议索引 |\n| `sessionID` | 当前会话标识符 |\n\n### 状态更新流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户输入\n participant H as useFileMention\n participant B as 后端\n participant S as 状态\n \n U->>H: 输入触发 @\n H->>H: setMentionQuery(query)\n H->>B: 发送文件搜索请求\n B->>H: 返回搜索结果\n H->>S: setMentionResults(results)\n U->>H: 选择建议\n H->>H: setMentionIndex(index)\n H->>H: closeMention()\n```\n\n## 国际化\n\n### 语言键命名空间\n\n| 命名空间 | 用途 |\n|---------|------|\n| `migration.*` | 迁移向导相关文本 |\n| `deviceAuth.*` | 设备授权流程 |\n| `marketplace.*` | MCP 市场界面 |\n| `ui.tool.*` | 工具显示名称 |\n| `ui.message.*` | 消息和提示 |\n\n## 总结\n\nKiloCode 的 IDE 扩展实现采用了模块化和分层架构设计，通过 WebView 嵌入、消息通信、状态管理等机制，在保持与 IDE 紧密集成的同时，确保了用户界面的流畅性和功能的可扩展性。VS Code 和 JetBrains 扩展共享相似的设计理念，但在具体实现上针对各平台特性进行了优化。\n\n---\n\n\n\n## CLI 工具与 SDK 开发\n\n### 相关页面\n\n相关主题：[Kilo Code 简介与快速入门](#introduction), [MCP 协议与工具集成](#mcp-integration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/opencode/src/cli/bootstrap.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/bootstrap.ts)\n- [packages/opencode/src/cli/cmd/agent.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/agent.ts)\n- [packages/opencode/src/cli/cmd/tui/app.tsx](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx)\n- [packages/opencode/src/cli/cmd/run.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/cli/cmd/run.ts)\n- [packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts)\n- [packages/opencode/src/plugin/loader.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/plugin/loader.ts)\n- [packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts)\n- [packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts)\n
\n\n# CLI 工具与 SDK 开发\n\n## 概述\n\nKiloCode 提供了一套完整的命令行工具和软件开发包（SDK），旨在为开发者提供灵活、模块化的代码辅助能力。该系统由以下几个核心部分组成：\n\n| 组件 | 功能描述 |\n|------|----------|\n| **OpenCode CLI** | 核心命令行工具，支持交互式 TUI 和脚本模式 |\n| **TUI 界面** | 终端用户界面，提供可视化交互体验 |\n| **Plugin 系统** | 插件加载机制，支持扩展功能 |\n| **SDK** | JavaScript/TypeScript 开发包，用于二次开发 |\n\n## CLI 架构设计\n\n### 命令行入口\n\nCLI 工具采用分层架构设计，主要入口通过 `bootstrap.ts` 完成初始化，随后根据用户输入分发到不同的命令处理器。\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[Bootstrap 初始化]\n B --> C[命令解析]\n C --> D[agent 命令]\n C --> E[run 命令]\n C --> F[TUI 模式]\n D --> G[Agent 执行器]\n E --> H[任务运行器]\n F --> I[TUI 应用]\n```\n\n### 核心命令模块\n\n#### Agent 命令\n\n`agent.ts` 负责处理 Agent 相关的操作，包括会话管理、模型选择和消息处理。该模块是 CLI 与 AI 模型交互的核心通道。\n\n#### Run 命令\n\n`run.ts` 提供非交互式的批处理能力，适用于自动化脚本和 CI/CD 场景。用户可以通过命令行参数直接指定任务和配置。\n\n#### TUI 应用\n\nTUI（Terminal User Interface）模块采用组件化设计，主要结构包括：\n\n| 组件 | 路径 | 职责 |\n|------|------|------|\n| `app.tsx` | `packages/opencode/src/cli/cmd/tui/app.tsx` | 根组件，应用状态管理 |\n| `session/index.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/index.tsx` | 会话界面渲染 |\n| `footer.tsx` | `packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx` | 状态栏组件 |\n| `prompt/index.tsx` | `packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx` | 提示词输入组件 |\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:1-60]()\n\n### 消息渲染系统\n\n会话界面采用 Switch/Match 模式处理不同类型的消息部分：\n\n```typescript\nconst PART_MAPPING = {\n text: TextPart,\n tool: ToolPart,\n reasoning: ReasoningPart,\n}\n```\n\n- **TextPart**: 普通文本消息渲染\n- **ToolPart**: 工具调用结果显示\n- **ReasoningPart**: AI 推理过程展示，支持折叠显示\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/index.tsx:70-85]()\n\n### 状态栏组件\n\nFooter 组件显示当前会话的关键状态信息：\n\n| 状态项 | 说明 |\n|--------|------|\n| LSP 连接 | 显示已连接的 Language Server 数量 |\n| MCP 连接 | Model Context Protocol 连接状态 |\n| 索引状态 | 代码索引进度 |\n| 权限提示 | 当前会话所需的权限列表 |\n\n资料来源：[packages/opencode/src/cli/cmd/tui/routes/session/footer.tsx:1-50]()\n\n## 插件系统\n\n### 插件加载器\n\nKiloCode 采用模块化的插件架构，通过 `loader.ts` 实现动态插件加载：\n\n```mermaid\ngraph LR\n A[插件目录] --> B[Loader 扫描]\n B --> C[模块解析]\n C --> D[注册到系统]\n D --> E[运行时调用]\n```\n\n### 插件接口定义\n\n插件系统提供标准化的接口规范，定义在 `packages/plugin/src/index.ts` 中：\n\n| 接口方法 | 功能 |\n|----------|------|\n| `register()` | 注册插件，提供名称和版本 |\n| `initialize()` | 初始化插件资源 |\n| `execute()` | 执行插件核心逻辑 |\n| `cleanup()` | 清理插件资源 |\n\n资料来源：[packages/plugin/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/plugin/src/index.ts)\n\n## SDK 开发\n\n### JavaScript SDK\n\nJavaScript SDK 位于 `packages/sdk/js/src/index.ts`，提供完整的 API 接口用于集成 KiloCode 功能：\n\n```mermaid\ngraph TD\n A[JS SDK] --> B[会话管理]\n A --> C[消息发送]\n A --> D[文件操作]\n A --> E[模型配置]\n B --> F[createSession]\n C --> G[sendMessage]\n D --> H[attachFile]\n E --> I[setModel]\n```\n\n### SDK 核心功能\n\n| 功能模块 | API 方法 | 说明 |\n|----------|----------|------|\n| 会话管理 | `createSession()` | 创建新的会话实例 |\n| 消息交互 | `sendMessage()` | 发送消息并获取响应 |\n| 文件附件 | `attachFile()` | 向会话添加文件上下文 |\n| 模型配置 | `setModel()` | 设置使用的 AI 模型 |\n\n资料来源：[packages/sdk/js/src/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/sdk/js/src/index.ts)\n\n## 配置系统\n\n### 配置文件结构\n\n配置管理由 `config.ts` 统一处理，支持多种配置来源：\n\n| 配置源 | 优先级 | 格式 |\n|--------|--------|------|\n| 环境变量 | 最高 | `KILO_*` 前缀 |\n| 命令行参数 | 高 | `--key value` |\n| 配置文件 | 中 | `kilo.config.ts` |\n| 默认值 | 最低 | 内置默认值 |\n\n资料来源：[packages/opencode/src/config/config.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/config.ts)\n\n### 关键配置项\n\n```typescript\ninterface KiloConfig {\n model: string // 默认模型 ID\n provider: string // 模型提供者\n apiKey?: string // API 密钥\n temperature?: number // 生成温度参数\n maxTokens?: number // 最大 token 数\n}\n```\n\n## 开发指南\n\n### 本地开发环境搭建\n\n1. 克隆仓库并安装依赖\n2. 构建项目：`pnpm build`\n3. 链接本地包：`pnpm link --global`\n4. 运行 CLI：`opencode` 或 `kilo`\n\n### 调试技巧\n\n| 方法 | 说明 |\n|------|------|\n| `DEBUG=* opencode` | 启用完整调试日志 |\n| `opencode --verbose` | 显示详细执行信息 |\n| 查看 TUI 日志 | 状态栏 `/status` 命令 |\n\n### 创建自定义插件\n\n```typescript\nimport { Plugin, PluginContext } from '@kilo/plugin'\n\nexport default class MyPlugin implements Plugin {\n name = 'my-plugin'\n version = '1.0.0'\n \n register(ctx: PluginContext) {\n ctx.registerCommand({\n name: 'my-command',\n handler: async (args) => {\n // 处理逻辑\n }\n })\n }\n}\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | TypeScript | 类型安全的命令行工具 |\n| UI 框架 | Solid.js | 高性能响应式界面 |\n| TUI 渲染 | Ink/自定义 | 终端界面渲染 |\n| 构建工具 | Vite | 快速开发和打包 |\n| 包管理 | pnpm | 高效的依赖管理 |\n\n## 相关资源\n\n- 官方文档：https://kilo.ai/docs/\n- 博客公告：https://blog.kilo.ai/\n- 问题反馈：https://github.com/Kilo-Org/kilocode/issues\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Kilo-Org/kilocode\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：Kilo-Org/kilocode\n\n暂未发现结构化踩坑项；仍需完成沙箱安装和 Quick Start 验证。\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# kilocode - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 kilocode 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：Kilo Code 简介与快速入门。围绕“Kilo Code 简介与快速入门”模拟一次用户任务，不展示安装或运行结果。\n2. project-structure：项目结构与包组织。围绕“项目结构与包组织”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. agent-system：Agent 核心系统。围绕“Agent 核心系统”模拟一次用户任务，不展示安装或运行结果。\n5. autocomplete-system：自动补全系统 (FIM)。围绕“自动补全系统 (FIM)”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Kilo Code 简介与快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. project-structure\n输入：用户提供的“项目结构与包组织”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-system\n输入：用户提供的“Agent 核心系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. autocomplete-system\n输入：用户提供的“自动补全系统 (FIM)”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Kilo Code 简介与快速入门”形成一个小中间产物，并等待用户确认。\n- Step 2 / project-structure：Step 2 必须围绕“项目结构与包组织”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-system：Step 4 必须围绕“Agent 核心系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / autocomplete-system：Step 5 必须围绕“自动补全系统 (FIM)”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Kilo-Org/kilocode\n- https://github.com/Kilo-Org/kilocode#readme\n- .kilo/skills/gh-issues/SKILL.md\n- .kilo/skills/kilocode-merge-minimizer/SKILL.md\n- .kilocode/skills/vscode-visual-regression/SKILL.md\n- .opencode/skills/effect/SKILL.md\n- packages/kilo-jetbrains/.kilo/skills/jetbrains-ui-style/SKILL.md\n- packages/opencode/test/fixture/skills/agents-sdk/SKILL.md\n- packages/opencode/test/fixture/skills/cloudflare/SKILL.md\n- README.md\n- packages/opencode/README.md\n- packages/kilo-vscode/README.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 kilocode 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：Kilo-Org/kilocode\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @kilocode/cli\n```\n\n来源：https://github.com/Kilo-Org/kilocode#readme\n\n## 来源\n\n- repo: https://github.com/Kilo-Org/kilocode\n- docs: https://github.com/Kilo-Org/kilocode#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_79e3d206d9a545f7a411e2c30ee4335c" }