From 7f2f075ddabaf33ebd6f94440eb394fc6b4bb4bc Mon Sep 17 00:00:00 2001 From: johnwong <124032292+justinwongcn@users.noreply.github.com> Date: Mon, 9 Jun 2025 02:48:32 +0800 Subject: [PATCH] Completed multi-language documentation translation, added Chinese translation files and updated translation status list --- .../available-tools/codebase-search.md | 235 +++++++++++ .../advanced-usage/custom-instructions.md | 43 ++ docs/zh-CN/advanced-usage/custom-rules.md | 159 ++++++++ docs/zh-CN/advanced-usage/large-projects.md | 46 +++ docs/zh-CN/advanced-usage/local-models.md | 36 ++ docs/zh-CN/advanced-usage/memory-bank.md | 297 ++++++++++++++ .../advanced-usage/prompt-engineering.md | 91 +++++ .../zh-CN/advanced-usage/rate-limits-costs.md | 51 +++ docs/zh-CN/basic-usage/adding-tokens.md | 28 ++ docs/zh-CN/basic-usage/context-mentions.md | 126 ++++++ docs/zh-CN/basic-usage/how-tools-work.md | 82 ++++ docs/zh-CN/basic-usage/orchestrator-mode.md | 46 +++ docs/zh-CN/basic-usage/the-chat-interface.md | 43 ++ .../zh-CN/basic-usage/typing-your-requests.md | 49 +++ docs/zh-CN/basic-usage/using-modes.md | 90 +++++ docs/zh-CN/extending/contributing-to-kilo.md | 125 ++++++ .../extending/development-environment.md | 192 +++++++++ docs/zh-CN/faq.md | 181 +++++++++ .../features/api-configuration-profiles.md | 92 +++++ .../features/auto-approving-actions copy.md | 34 ++ docs/zh-CN/features/auto-approving-actions.md | 224 ++++++++++ docs/zh-CN/features/browser-use.md | 170 ++++++++ docs/zh-CN/features/checkpoints.md | 236 +++++++++++ docs/zh-CN/features/code-actions.md | 90 +++++ docs/zh-CN/features/custom-modes.md | 285 +++++++++++++ docs/zh-CN/features/enhance-prompt.md | 54 +++ .../experimental/codebase-indexing.md | 205 ++++++++++ .../experimental/experimental-features.md | 39 ++ docs/zh-CN/features/fast-edits.md | 34 ++ docs/zh-CN/features/footgun-prompting.md | 51 +++ docs/zh-CN/features/mcp/mcp-vs-api.md | 97 +++++ docs/zh-CN/features/mcp/overview.md | 20 + docs/zh-CN/features/mcp/server-transports.md | 197 +++++++++ .../features/mcp/using-mcp-in-kilo-code.md | 259 ++++++++++++ docs/zh-CN/features/mcp/what-is-mcp.md | 49 +++ docs/zh-CN/features/model-temperature.md | 93 +++++ docs/zh-CN/features/more-features.md | 42 ++ docs/zh-CN/features/settings-management.md | 60 +++ docs/zh-CN/features/shell-integration.md | 382 ++++++++++++++++++ docs/zh-CN/features/suggested-responses.md | 45 +++ .../features/tools/access-mcp-resource.md | 126 ++++++ docs/zh-CN/features/tools/apply-diff.md | 98 +++++ .../features/tools/ask-followup-question.md | 168 ++++++++ .../features/tools/attempt-completion.md | 174 ++++++++ docs/zh-CN/features/tools/browser-action.md | 158 ++++++++ docs/zh-CN/features/tools/execute-command.md | 153 +++++++ .../tools/list-code-definition-names.md | 116 ++++++ docs/zh-CN/features/tools/list-files.md | 132 ++++++ docs/zh-CN/features/tools/new-task.md | 103 +++++ docs/zh-CN/features/tools/read-file.md | 180 +++++++++ docs/zh-CN/features/tools/search-files.md | 120 ++++++ docs/zh-CN/features/tools/switch-mode.md | 151 +++++++ .../zh-CN/features/tools/tool-use-overview.md | 239 +++++++++++ docs/zh-CN/features/tools/use-mcp-tool.md | 180 +++++++++ docs/zh-CN/features/tools/write-to-file.md | 169 ++++++++ .../connecting-api-provider.md | 76 ++++ docs/zh-CN/getting-started/installing.md | 106 +++++ docs/zh-CN/getting-started/setting-up.mdx | 41 ++ docs/zh-CN/getting-started/your-first-task.md | 70 ++++ docs/zh-CN/index.mdx | 82 ++++ docs/zh-CN/providers/anthropic.md | 44 ++ docs/zh-CN/providers/bedrock.md | 91 +++++ docs/zh-CN/providers/deepseek.md | 33 ++ docs/zh-CN/providers/gemini.md | 47 +++ docs/zh-CN/providers/glama.md | 37 ++ docs/zh-CN/providers/human-relay.md | 29 ++ docs/zh-CN/providers/kilocode.md | 45 +++ docs/zh-CN/providers/lmstudio.md | 41 ++ docs/zh-CN/providers/mistral.md | 53 +++ docs/zh-CN/providers/ollama.md | 74 ++++ docs/zh-CN/providers/openai-compatible.md | 60 +++ docs/zh-CN/providers/openai.md | 44 ++ docs/zh-CN/providers/openrouter.md | 37 ++ docs/zh-CN/providers/requesty.md | 39 ++ docs/zh-CN/providers/unbound.md | 30 ++ docs/zh-CN/providers/vertex.md | 54 +++ docs/zh-CN/providers/vscode-lm.md | 45 +++ docs/zh-CN/tips-and-tricks.md | 15 + 78 files changed, 8138 insertions(+) create mode 100644 docs/zh-CN/advanced-usage/available-tools/codebase-search.md create mode 100644 docs/zh-CN/advanced-usage/custom-instructions.md create mode 100644 docs/zh-CN/advanced-usage/custom-rules.md create mode 100644 docs/zh-CN/advanced-usage/large-projects.md create mode 100644 docs/zh-CN/advanced-usage/local-models.md create mode 100644 docs/zh-CN/advanced-usage/memory-bank.md create mode 100644 docs/zh-CN/advanced-usage/prompt-engineering.md create mode 100644 docs/zh-CN/advanced-usage/rate-limits-costs.md create mode 100644 docs/zh-CN/basic-usage/adding-tokens.md create mode 100644 docs/zh-CN/basic-usage/context-mentions.md create mode 100644 docs/zh-CN/basic-usage/how-tools-work.md create mode 100644 docs/zh-CN/basic-usage/orchestrator-mode.md create mode 100644 docs/zh-CN/basic-usage/the-chat-interface.md create mode 100644 docs/zh-CN/basic-usage/typing-your-requests.md create mode 100644 docs/zh-CN/basic-usage/using-modes.md create mode 100644 docs/zh-CN/extending/contributing-to-kilo.md create mode 100644 docs/zh-CN/extending/development-environment.md create mode 100644 docs/zh-CN/faq.md create mode 100644 docs/zh-CN/features/api-configuration-profiles.md create mode 100644 docs/zh-CN/features/auto-approving-actions copy.md create mode 100644 docs/zh-CN/features/auto-approving-actions.md create mode 100644 docs/zh-CN/features/browser-use.md create mode 100644 docs/zh-CN/features/checkpoints.md create mode 100644 docs/zh-CN/features/code-actions.md create mode 100644 docs/zh-CN/features/custom-modes.md create mode 100644 docs/zh-CN/features/enhance-prompt.md create mode 100644 docs/zh-CN/features/experimental/codebase-indexing.md create mode 100644 docs/zh-CN/features/experimental/experimental-features.md create mode 100644 docs/zh-CN/features/fast-edits.md create mode 100644 docs/zh-CN/features/footgun-prompting.md create mode 100644 docs/zh-CN/features/mcp/mcp-vs-api.md create mode 100644 docs/zh-CN/features/mcp/overview.md create mode 100644 docs/zh-CN/features/mcp/server-transports.md create mode 100644 docs/zh-CN/features/mcp/using-mcp-in-kilo-code.md create mode 100644 docs/zh-CN/features/mcp/what-is-mcp.md create mode 100644 docs/zh-CN/features/model-temperature.md create mode 100644 docs/zh-CN/features/more-features.md create mode 100644 docs/zh-CN/features/settings-management.md create mode 100644 docs/zh-CN/features/shell-integration.md create mode 100644 docs/zh-CN/features/suggested-responses.md create mode 100644 docs/zh-CN/features/tools/access-mcp-resource.md create mode 100644 docs/zh-CN/features/tools/apply-diff.md create mode 100644 docs/zh-CN/features/tools/ask-followup-question.md create mode 100644 docs/zh-CN/features/tools/attempt-completion.md create mode 100644 docs/zh-CN/features/tools/browser-action.md create mode 100644 docs/zh-CN/features/tools/execute-command.md create mode 100644 docs/zh-CN/features/tools/list-code-definition-names.md create mode 100644 docs/zh-CN/features/tools/list-files.md create mode 100644 docs/zh-CN/features/tools/new-task.md create mode 100644 docs/zh-CN/features/tools/read-file.md create mode 100644 docs/zh-CN/features/tools/search-files.md create mode 100644 docs/zh-CN/features/tools/switch-mode.md create mode 100644 docs/zh-CN/features/tools/tool-use-overview.md create mode 100644 docs/zh-CN/features/tools/use-mcp-tool.md create mode 100644 docs/zh-CN/features/tools/write-to-file.md create mode 100644 docs/zh-CN/getting-started/connecting-api-provider.md create mode 100644 docs/zh-CN/getting-started/installing.md create mode 100644 docs/zh-CN/getting-started/setting-up.mdx create mode 100644 docs/zh-CN/getting-started/your-first-task.md create mode 100644 docs/zh-CN/index.mdx create mode 100644 docs/zh-CN/providers/anthropic.md create mode 100644 docs/zh-CN/providers/bedrock.md create mode 100644 docs/zh-CN/providers/deepseek.md create mode 100644 docs/zh-CN/providers/gemini.md create mode 100644 docs/zh-CN/providers/glama.md create mode 100644 docs/zh-CN/providers/human-relay.md create mode 100644 docs/zh-CN/providers/kilocode.md create mode 100644 docs/zh-CN/providers/lmstudio.md create mode 100644 docs/zh-CN/providers/mistral.md create mode 100644 docs/zh-CN/providers/ollama.md create mode 100644 docs/zh-CN/providers/openai-compatible.md create mode 100644 docs/zh-CN/providers/openai.md create mode 100644 docs/zh-CN/providers/openrouter.md create mode 100644 docs/zh-CN/providers/requesty.md create mode 100644 docs/zh-CN/providers/unbound.md create mode 100644 docs/zh-CN/providers/vertex.md create mode 100644 docs/zh-CN/providers/vscode-lm.md create mode 100644 docs/zh-CN/tips-and-tricks.md diff --git a/docs/zh-CN/advanced-usage/available-tools/codebase-search.md b/docs/zh-CN/advanced-usage/available-tools/codebase-search.md new file mode 100644 index 0000000..cf18815 --- /dev/null +++ b/docs/zh-CN/advanced-usage/available-tools/codebase-search.md @@ -0,0 +1,235 @@ +# codebase_search + +:::warning 实验性功能 +`codebase_search` 工具是实验性功能 [代码库索引](/features/experimental/codebase-indexing) 的一部分。该功能正在积极开发中，可能在未来的版本中有重大变化。它需要额外的设置，包括嵌入提供程序和向量数据库。 +::: + +`codebase_search` 工具使用 AI 嵌入在整个代码库中执行语义搜索。与传统的基于文本的搜索不同，它能理解查询的含义，即使没有完全匹配的关键字，也能找到相关的代码。 + +## 参数 + +该工具接受以下参数： + +- `query`（必填）：自然语言搜索查询，描述你要查找的内容 +- `path`（可选）：目录路径，用于将搜索范围限制在代码库的特定部分 + +## 功能 + +该工具通过语义相似性而非精确文本匹配来搜索你的索引代码库。它能找到与你的查询在概念上相关的代码块，即使它们不包含你搜索的确切单词。结果包括相关代码片段、文件路径、行号和相似度分数。 + +## 使用场景 + +- 当 Kilo Code 需要在项目中查找与特定功能相关的代码时 +- 当查找实现模式或相似代码结构时 +- 当搜索错误处理、身份验证或其他概念性代码模式时 +- 当探索不熟悉的代码库以了解功能实现时 +- 当查找可能受更改或重构影响的代码时 + +## 主要特性 + +- **语义理解**：通过含义而非精确关键字匹配查找代码 +- **跨项目搜索**：搜索整个索引代码库，而不仅仅是打开的文件 +- **上下文结果**：返回包含文件路径和行号的代码片段，便于导航 +- **相似度评分**：结果按相关性排序，带有相似度分数（0-1 范围） +- **范围过滤**：可选路径参数，用于将搜索限制在特定目录 +- **智能排序**：结果按与查询的语义相关性排序 +- **UI 集成**：结果显示语法高亮和导航链接 +- **性能优化**：快速向量搜索，具有可配置的结果限制 + +## 要求 + +该工具仅在实验性代码库索引功能正确配置时可用： + +- **功能启用**：必须在实验设置中启用代码库索引 +- **嵌入提供程序**：需要 OpenAI API 密钥或 Ollama 配置 +- **向量数据库**：需要运行并访问 Qdrant 实例 +- **索引状态**：代码库必须已索引（状态："已索引" 或 "正在索引"） + +## 限制 + +- **实验性功能**：属于实验性代码库索引系统的一部分 +- **需要配置**：依赖外部服务（嵌入提供程序 + Qdrant） +- **索引依赖**：仅搜索已索引的代码块 +- **结果限制**：每次搜索最多返回 50 个结果以保持性能 +- **相似度阈值**：仅返回相似度分数高于 0.4 的结果 +- **文件大小限制**：仅限于成功索引的小于 1MB 的文件 +- **语言支持**：效果取决于 Tree-sitter 语言支持 + +## 工作原理 + +当调用 `codebase_search` 工具时，它会遵循以下过程： + +1. **可用性验证**： + - 验证 CodeIndexManager 是否可用并已初始化 + - 确认设置中已启用代码库索引 + - 检查索引是否正确配置（API 密钥、Qdrant URL） + - 验证当前索引状态是否允许搜索 + +2. **查询处理**： + - 获取你的自然语言查询并生成嵌入向量 + - 使用为索引配置的相同嵌入提供程序（OpenAI 或 Ollama） + - 将查询的语义转换为数学表示 + +3. **向量搜索执行**： + - 在 Qdrant 向量数据库中搜索相似的代码嵌入 + - 使用余弦相似度查找最相关的代码块 + - 应用最小相似度阈值（0.4）以过滤结果 + - 将结果限制为 50 个匹配项以优化性能 + +4. **路径过滤**（如果指定）： + - 过滤结果，仅包括指定目录路径中的文件 + - 使用标准化路径比较以进行准确过滤 + - 在过滤范围内保持相关性排序 + +5. **结果处理和格式化**： + - 将绝对文件路径转换为工作区相对路径 + - 使用文件路径、行范围、相似度分数和代码内容构建结果 + - 格式化为 AI 使用和 UI 显示，并带有语法高亮 + +6. **双重输出格式**： + - **AI 输出**：结构化文本格式，包含查询、文件路径、分数和代码块 + - **UI 输出**：JSON 格式，带有语法高亮和导航功能 + +## 搜索查询最佳实践 + +### 有效查询模式 + +**良好：概念性和具体性** + +```xml + +用户身份验证和密码验证 + +``` + +**良好：功能导向** + +```xml + +数据库连接池设置 + +``` + +**良好：问题导向** + +```xml + +API 请求的错误处理 + +``` + +**效果较差：过于通用** + +```xml + +函数 + +``` + +### 适用查询类型 + +- **功能描述**："文件上传处理"，"电子邮件验证逻辑" +- **技术模式**："单例模式实现"，"工厂方法使用" +- **领域概念**："用户档案管理"，"支付处理流程" +- **架构组件**："中间件配置"，"数据库迁移脚本" + +## 目录范围限定 + +使用可选的 `path` 参数将搜索范围限定在代码库的特定部分： + +**在 API 模块中搜索：** + +```xml + +端点验证中间件 +src/api + +``` + +**在测试文件中搜索：** + +```xml + +模拟数据设置模式 +tests + +``` + +**在特定功能目录中搜索：** + +```xml + +组件状态管理 +src/components/auth + +``` + +## 结果解释 + +### 相似度分数 + +- **0.8-1.0**：高度相关匹配，很可能是你要找的内容 +- **0.6-0.8**：良好匹配，具有强概念相似性 +- **0.4-0.6**：可能相关，但可能需要审查 +- **低于 0.4**：作为太不相关而被过滤掉 + +### 结果结构 + +每个搜索结果包括： + +- **文件路径**：包含匹配项的文件的工作区相对路径 +- **分数**：表示相关性的相似度分数（0.4-1.0） +- **行范围**：代码块的起始和结束行号 +- **代码块**：与查询匹配的实际代码内容 + +## 使用示例 + +当 Kilo Code 实现新功能时，搜索 "身份验证中间件" 以在编写新代码之前了解现有模式。 +当调试问题时，Kilo Code 搜索 "API 调用中的错误处理" 以查找代码库中相关的错误模式。 +当重构代码时，Kilo Code 搜索 "数据库事务模式" 以确保所有数据库操作的一致性。 +当加入新代码库时，Kilo Code 搜索 "配置加载" 以了解应用程序如何引导。 + +## 使用示例 + +在整个项目中搜索与身份验证相关的代码： + +```xml + +用户登录和身份验证逻辑 + +``` + +在特定目录中查找与数据库相关的代码： + +```xml + +数据库连接和查询执行 +src/data + +``` + +在 API 代码中查找错误处理模式： + +```xml + +HTTP 错误响应和异常处理 +src/api + +``` + +搜索测试工具和模拟设置： + +```xml + +测试设置和模拟数据创建 +tests + +``` + +查找配置和环境设置代码： + +```xml + +环境变量和应用程序配置 + +``` \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/custom-instructions.md b/docs/zh-CN/advanced-usage/custom-instructions.md new file mode 100644 index 0000000..5a95089 --- /dev/null +++ b/docs/zh-CN/advanced-usage/custom-instructions.md @@ -0,0 +1,43 @@ +# 自定义指令 + +自定义指令允许你个性化 Kilo Code 的行为，提供特定的指导来塑造响应、编码风格和决策过程。 + +## 什么是自定义指令？ + +自定义指令定义了扩展的特定行为、偏好和约束，超出了 Kilo 的基本角色定义。示例包括编码风格、文档标准、测试要求和工作流指南。 + +:::info 自定义指令 vs 规则 +自定义指令是 IDE 范围的，适用于所有工作区，无论你在处理哪个项目，都会保持你的偏好。与指令不同，[自定义规则](/advanced-usage/custom-rules.md) 是项目特定的，允许你设置基于工作区的规则集。 +::: + +## 设置自定义指令 + +**如何设置：** + +Kilo Code 提示标签显示全局自定义指令界面 +1. **打开提示标签：** 点击 Kilo Code 顶部菜单栏中的 图标 +2. **找到部分：** 找到 "所有模式的自定义指令" 部分 +3. **输入指令：** 在文本区域输入你的指令 +4. **保存更改：** 点击 "完成" 保存你的更改 + +#### 模式特定指令 + +模式特定指令可以使用提示标签设置 + + Kilo Code 提示标签显示模式特定自定义指令界面 + * **打开标签：** 点击 Kilo Code 顶部菜单栏中的 图标 + * **选择模式：** 在模式标题下，点击你想要自定义的模式按钮 + * **输入指令：** 在 "模式特定自定义指令（可选）" 下的文本区域输入你的指令 + * **保存更改：** 点击 "完成" 保存你的更改 + + :::info 全局模式规则 + 如果模式本身是全局的（非工作区特定），你为其设置的任何自定义指令也将全局适用于所有工作区的该模式。 + ::: + + +## 相关功能 + +- [自定义模式](/docs/features/custom-modes) +- [自定义规则](/advanced-usage/custom-rules) +- [设置管理](/docs/features/settings-management) +- [自动批准设置](/docs/features/auto-approving-actions) \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/custom-rules.md b/docs/zh-CN/advanced-usage/custom-rules.md new file mode 100644 index 0000000..1301ffc --- /dev/null +++ b/docs/zh-CN/advanced-usage/custom-rules.md @@ -0,0 +1,159 @@ +# 自定义规则 + +自定义规则提供了一种强大的方式来定义项目特定的行为和约束，以确保 Kilo Code AI 代理的一致性。通过自定义规则，你可以确保格式一致、限制对敏感文件的访问、强制执行编码标准，并根据你的项目需求自定义 AI 的行为。 + +## 概述 + +自定义规则允许你创建基于文本的指令，所有 AI 模型在与你的项目交互时都会遵循这些规则。这些规则充当护栏和约定，确保与代码库的所有交互都保持一致。 + +:::info 自定义规则与指令的区别 +自定义规则是项目特定的，允许你设置基于工作区的规则集。对于 IDE 范围的配置，[自定义指令](/advanced-usage/custom-instructions.md) 将是更好的选择，因为它们会保持你的偏好，无论你正在处理哪个项目。 +::: + +## 规则格式 + +自定义规则可以用纯文本编写，但建议使用 Markdown 格式，以便更好地组织和让 AI 模型理解。Markdown 的结构化特性有助于模型更有效地解析和理解你的规则。 + +- 使用 Markdown 标题（`#`, `##` 等）定义规则类别 +- 使用列表（`-`, `*`）枚举特定项目或约束 +- 使用代码块（``` ```）在需要时包含代码示例 + +## 规则位置 + +自定义规则主要从 **`.kilocode/rules/` 目录** 加载。这是组织项目特定规则的推荐方法。每个规则通常放置在具有描述性名称的 Markdown 文件中： + +``` +project/ +├── .kilocode/ +│ ├── rules/ +│ │ ├── formatting.md +│ │ ├── restricted_files.md +│ │ └── naming_conventions.md +├── src/ +└── ... +``` + +## 规则加载顺序 + +### 通用规则（所有模式） + +为了向后兼容，如果没有找到规则文件夹，代理将检查其他位置。 + +加载顺序如下： + +1. 首先尝试从 `.kilocode/rules/` 目录加载 +2. 如果该目录不存在或为空，则回退检查以下文件： + - `.roorules` + - `.clinerules` + - `.kilocoderules`（已弃用） + +代理使用找到的第一个包含内容的来源。例如，如果找到了包含内容的 `.roorules`，则不会读取 `.clinerules`。 + +:::note +我们强烈建议将规则保留在 `.kilocode/rules/` 文件夹中，因为它提供了更好的组织，并且是未来版本的首选方法。基于文件夹的结构允许更细粒度的规则组织和更清晰的关注点分离。基于文件的旧方法为了向后兼容而保留，但可能会在未来的版本中发生变化。 +::: + +### 模式特定规则 + +此外，系统支持模式特定的规则，这些规则会单独加载，并有自己的优先级顺序： + +1. 首先检查 `.kilocode/rules-${mode}/` 目录 +2. 如果该目录不存在或为空，则回退到 `.kilocoderules-${mode}` 文件（已弃用） + +当通用规则和模式特定规则同时存在时，模式特定规则在最终输出中具有优先权。 + +## 创建自定义规则 + +要创建自定义规则： + +1. 如果不存在，请创建 `.kilocode/rules/` 目录 +2. 在此目录中创建一个具有描述性名称的新 Markdown 文件 +3. 使用 Markdown 格式编写你的规则 +4. 保存文件 + +该规则将自动应用于你项目中所有未来的 Kilo Code 交互。任何新更改都会立即生效。 + +## 规则示例 + +### 示例 1：表格格式化 + +```markdown +# 表格 +打印表格时，始终在每列标题中添加感叹号 +``` + +这个简单的规则指示 AI 在生成表格时在所有列标题中添加感叹号。 + +### 示例 2：限制文件访问 + +```markdown +# 受限文件 +列表中包含敏感数据的文件，禁止读取 +- supersecrets.txt +- credentials.json +- .env +``` + +此规则防止 AI 读取或访问敏感文件，即使明确要求这样做。 + +Kilo Code 忽略读取敏感文件的请求 + +## 使用场景 + +自定义规则可以应用于各种场景： + +- **代码风格**：强制执行一致的格式、命名约定和文档风格 +- **安全控制**：防止访问敏感文件或目录 +- **项目结构**：定义不同类型文件的创建位置 +- **文档要求**：指定文档格式和要求 +- **测试模式**：定义测试的结构方式 +- **API 使用**：指定 API 的使用和文档方式 +- **错误处理**：定义错误处理约定 + +## 自定义规则示例 + +* "严格遵守代码风格指南 [你的项目特定代码风格指南]" +* "始终使用空格缩进，宽度为 4 个空格" +* "使用 camelCase 命名变量" +* "为所有新函数编写单元测试" +* "在提供代码之前解释你的推理" +* "专注于代码的可读性和可维护性" +* "优先使用社区中最常见的库" +* "当为网站添加新功能时，确保它们是响应式且可访问的" + +## 最佳实践 + +- **具体明确**：明确定义每个规则的范围和意图 +- **使用类别**：将相关规则组织在共同的标题下 +- **分离关注点**：为不同类型的规则使用不同的文件 +- **使用示例**：包含示例以说明预期行为 +- **保持简单**：规则应简洁易懂 +- **定期更新**：随着项目需求的变化，定期审查和更新规则 + +:::tip 专业提示：基于文件的团队标准 +在团队环境中工作时，将 `.kilocode/rules/codestyle.md` 文件置于版本控制之下，可以让你在整个开发团队中标准化 Kilo 的行为。这确保了项目中的每个人都有一致的代码风格、文档实践和开发工作流程。 +::: + +## 限制 + +- 规则由 AI 模型尽力而为地应用 +- 复杂规则可能需要多个示例才能清晰理解 +- 规则仅适用于定义它们的项目 + +## 故障排除 + +如果你的自定义规则未被正确遵循： + +1. 检查你的规则是否使用清晰的 Markdown 结构正确格式化 +2. 确保你的规则位于以下支持的位置之一： + - 推荐的 `.kilocode/rules/` 目录 + - 根级规则文件（`.kilocoderules`, `.roorules`, 或 `.clinerules`） +3. 验证规则是否具体且明确 +4. 重启 VS Code 以确保规则正确加载 + +## 相关功能 + +- [自定义模式](/docs/features/custom-modes) +- [自定义指令](/advanced-usage/custom-instructions) +- [设置管理](/docs/features/settings-management) +- [自动批准设置](/docs/features/auto-approving-actions) \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/large-projects.md b/docs/zh-CN/advanced-usage/large-projects.md new file mode 100644 index 0000000..17c1b71 --- /dev/null +++ b/docs/zh-CN/advanced-usage/large-projects.md @@ -0,0 +1,46 @@ +# 处理大型项目 + +Kilo Code 可以用于任何规模的项目，但处理大型项目时需要特别注意上下文管理。以下是一些处理大型代码库的技巧： + +## 理解上下文限制 + +Kilo Code 使用的大语言模型 (LLMs) 有一个有限的 "上下文窗口"。这是模型一次可以处理的文本的最大量（以 token 为单位）。如果上下文过大，模型可能无法理解你的请求或生成准确的响应。 + +上下文窗口包括： + +* 系统提示（Kilo Code 的指令）。 +* 对话历史记录。 +* 你使用 `@` 提到的任何文件内容。 +* Kilo Code 使用的任何命令或工具的输出。 + +## 管理上下文的策略 + +1. **具体化：** 当引用文件或代码时，使用具体的文件路径和函数名称。避免使用模糊的引用，如 "主文件"。 + +2. **有效使用上下文提及：** 使用 `@/path/to/file.ts` 来包含特定文件。使用 `@problems` 来包含当前错误和警告。使用 `@` 后跟提交哈希来引用特定的 Git 提交。 + +3. **分解任务：** 将大型任务分解为更小、更易管理的子任务。这有助于保持上下文的聚焦。 + +4. **总结：** 如果需要引用大量代码，考虑在提示中总结相关部分，而不是包含整个代码。 + +5. **优先处理最近的历史记录：** Kilo Code 会自动截断对话历史记录中的旧消息，以保持在上下文窗口内。请注意这一点，并在需要时重新包含重要上下文。 + +6. **使用提示缓存（如果可用）：** 一些 API 提供商如 Anthropic、OpenAI、OpenRouter 和 Requesty 支持 "提示缓存"。这将缓存你的提示以供未来任务使用，有助于降低请求的成本和延迟。 + +## 示例：重构大型文件 + +假设你需要重构一个大型 TypeScript 文件 (`src/components/MyComponent.tsx`)。以下是一个可能的方法： + +1. **初始概览：** + ``` + @/src/components/MyComponent.tsx 列出此文件中的函数和类。 + ``` + +2. **定位特定函数：** + ``` + @/src/components/MyComponent.tsx 将 `processData` 函数重构为使用 `async/await` 而不是 Promises。 + ``` + +3. **迭代更改：** 进行小的、增量的更改，审查并批准每一步。 + +通过分解任务并提供具体的上下文，即使在上下文窗口有限的情况下，你也可以有效地处理大型文件。 \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/local-models.md b/docs/zh-CN/advanced-usage/local-models.md new file mode 100644 index 0000000..441f57f --- /dev/null +++ b/docs/zh-CN/advanced-usage/local-models.md @@ -0,0 +1,36 @@ +# 使用本地模型 + +Kilo Code 支持使用 [Ollama](https://ollama.com/) 和 [LM Studio](https://lmstudio.ai/) 在本地计算机上运行语言模型。这提供了以下优势： + +* **隐私性**：你的代码和数据永远不会离开你的计算机。 +* **离线访问**：即使没有互联网连接，你也可以使用 Kilo Code。 +* **成本节约**：避免与云端模型相关的 API 使用费用。 +* **定制性**：可以尝试不同的模型和配置。 + +**然而，使用本地模型也有一些缺点：** + +* **资源需求**：本地模型可能对资源要求较高，需要一台性能强大的计算机，最好配备专用 GPU。 +* **设置复杂性**：设置本地模型可能比使用云端 API 更复杂。 +* **模型性能**：本地模型的性能可能差异较大。虽然有些模型表现优秀，但可能无法与最大、最先进的云端模型相媲美。 +* **功能限制**：本地模型（以及许多在线模型）通常不支持高级功能，例如提示缓存、计算机使用等。 + +## 支持的本地模型提供商 + +Kilo Code 目前支持两个主要的本地模型提供商： + +1. **Ollama**：一个流行的开源工具，用于在本地运行大型语言模型。它支持多种模型。 +2. **LM Studio**：一个用户友好的桌面应用程序，简化了下载、配置和运行本地模型的过程。它还提供了一个模拟 OpenAI API 的本地服务器。 + +## 设置本地模型 + +有关详细设置说明，请参阅： +* [设置 Ollama](/providers/ollama) +* [设置 LM Studio](/providers/lmstudio) + +这两个提供商提供类似的功能，但用户界面和工作流程不同。Ollama 通过命令行界面提供更多控制，而 LM Studio 提供了一个更友好的图形界面。 + +## 故障排除 + +* **“由于目标计算机主动拒绝，无法建立连接”**：这通常意味着 Ollama 或 LM Studio 服务器未运行，或者 Kilo Code 配置的端口/地址与服务器不一致。请仔细检查 Base URL 设置。 +* **响应时间慢**：本地模型可能比云端模型慢，尤其是在硬件性能较低的情况下。如果遇到性能问题，请尝试使用较小的模型。 +* **找不到模型**：请确保你正确输入了模型名称。如果使用 Ollama，请使用与 `ollama run` 命令中相同的名称。 \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/memory-bank.md b/docs/zh-CN/advanced-usage/memory-bank.md new file mode 100644 index 0000000..6a1d220 --- /dev/null +++ b/docs/zh-CN/advanced-usage/memory-bank.md @@ -0,0 +1,297 @@ +# Memory Bank + +## 概述 + +
+ 使用 Memory Bank 执行任务 +
+ 启用 Memory Bank 后，Kilo Code 可以更高效地工作，立即理解项目上下文和技术栈。 +
+
+ +### 问题：AI 记忆丢失 + +像 Kilo Code 这样的 AI 助手面临一个根本性的限制：它们会在会话之间完全重置。这种“记忆丢失”意味着每次开始新的对话时，都需要重新解释项目的架构、目标、技术和当前状态。这造成了一个关键效率困境：AI 模型要么在没有正确理解项目的情况下进行编辑（导致错误和解决方案不一致），要么必须在每个会话中花费大量时间和资源分析整个代码库（对于大型项目来说，这既昂贵又缓慢）。 + +如果没有解决这个记忆问题，AI 助手仍然是强大但无状态的工具，无法真正作为持续的开发伙伴。 + +### 解决方案：Memory Bank + +Memory Bank 是一个结构化文档系统，使 Kilo Code 能够**更好地理解你的项目**并**在编码会话之间保持上下文**。它将你的 AI 助手从无状态工具转变为具有完美项目记忆的持续开发伙伴。Kilo Code 会在每次开始新会话时自动读取你的 Memory Bank 文件，以重建对项目的理解。 + +当 Memory Bank 处于活动状态时，Kilo Code 会在每个任务的开始处显示 `[Memory Bank: Active]`，并简要总结你的项目上下文，确保在不重复解释的情况下保持一致性。 + +## 主要优点 + +- **语言无关**：适用于任何编程语言或框架 +- **高效的项目理解**：帮助 Kilo Code 理解项目的用途和技术栈 +- **上下文保留**：在会话之间维护项目知识，而无需在每个新会话中扫描文件 +- **更快的启动**：Kilo Code 在开始新会话时立即理解你的项目上下文 +- **自我记录项目**：作为副产品创建有价值的文档 + +## Memory Bank 的工作原理 + +Memory Bank 基于 Kilo Code 的 [自定义规则](/advanced-usage/custom-rules) 功能构建，为项目文档提供了一个专门的框架。Memory Bank 文件是存储在项目仓库 `.kilocode/rules/memory-bank` 文件夹中的标准 Markdown 文件。它们不是隐藏或专有的——它们是你和 Kilo Code 都可以访问的常规文档文件。 + +在每个任务开始时，Kilo Code 会读取所有 Memory Bank 文件，以构建对项目的全面理解。这是自动进行的，不需要你采取任何操作。Kilo Code 然后会在其响应的开头显示 `[Memory Bank: Active]`，表示 Memory Bank 已成功激活，并简要总结其对项目的理解。 + +文件按层次结构组织，构建项目的完整视图： + +## 核心 Memory Bank 文件 + +### brief.md +*此文件由你手动创建和维护* +- 项目的基础 +- 项目的高级概述 +- 核心需求和目标 + +示例：*"构建一个带有条形码扫描功能的 React 库存管理系统。该系统需要支持多个仓库并与我们现有的 ERP 系统集成。"* + +注意：Kilo Code 不会直接编辑此文件，但如果发现可以改进项目摘要的方式，可能会提出建议。 + +### product.md +- 解释项目存在的原因 +- 描述正在解决的问题 +- 概述产品应如何工作 +- 用户体验目标 + +示例：*"库存系统需要支持多个仓库和实时更新。它通过提供条形码扫描来解决库存差异问题，确保准确的库存计数。"* + +### context.md +- 更新最频繁的文件 +- 包含当前工作重点和最近的变化 +- 跟踪活动决策和考虑事项 +- 开发的下一步 + +示例：*"当前正在实施条形码扫描组件；上次会话完成了 API 集成。下一步包括为网络故障添加错误处理。"* + +### architecture.md +- 记录系统架构 +- 记录关键技术决策 +- 列出正在使用的设计模式 +- 解释组件关系 +- 关键实现路径 + +示例：*"使用 Redux 进行状态管理，采用规范化的存储结构。应用程序遵循模块化架构，API 通信、状态管理和 UI 组件分别位于不同的服务中。"* + +### tech.md +- 列出使用的技术和框架 +- 描述开发设置 +- 记录技术约束 +- 记录依赖项和工具配置 +- 工具使用模式 + +示例：*"React 18、TypeScript、Firebase、Jest 用于测试。开发需要 Node.js 16+ 并使用 Vite 作为构建工具。"* + +## 其他上下文文件 + +根据需要创建其他文件以组织： +- 复杂功能文档 +- 集成规范 +- API 文档 +- 测试策略 +- 部署程序 + +这些附加文件有助于组织不适合核心文件的更详细信息。 + +### tasks.md +*用于记录重复任务的可选文件* +- 存储遵循类似模式的任务的工作流程 +- 记录需要修改的文件 +- 记录分步程序 +- 记录重要的注意事项和陷阱 + +示例：添加对新 AI 模型的支持、实现 API 端点或任何需要重复执行类似工作的任务。 + +## 开始使用 Memory Bank + +### 首次设置 + +1. 在项目中创建 `.kilocode/rules/memory-bank/` 文件夹 +2. 在 `.kilocode/rules/memory-bank/brief.md` 中编写基本的项目摘要 +3. 创建文件 `.kilocode/rules/memory-bank-instructions.md` 并将 [此文档](pathname:///downloads/memory-bank.md) 粘贴到其中 +4. 切换到 `Architect` 模式 +5. 检查是否选择了最佳可用的 AI 模型，不要使用“轻量级”模型 +6. 要求 Kilo Code “initialize memory bank” +7. 等待 Kilo Code 分析你的项目并初始化 Memory Bank 文件 +8. 验证文件内容，确保项目描述正确。如有必要，更新文件。 + +### 项目摘要提示 + +- 从简单开始——它可以是你喜欢的任何详细程度或高级程度 +- 专注于对你最重要的事情 +- Kilo Code 将帮助填补空白并提出问题 +- 你可以随着项目的发展更新它 + +提供合理摘要的示例提示： + +``` +提供此项目的简明而全面的描述，突出其主要目标、关键功能、使用的技术和重要性。然后，将此描述写入适当命名的文本文件中，以反映项目内容，确保写作的清晰性和专业性。保持简洁。 +``` + +## 使用 Memory Bank + +### 核心工作流程 + +#### Memory Bank 初始化 + +初始化步骤至关重要，因为它为所有未来的项目交互奠定了基础。当你使用命令 `initialize memory bank` 请求初始化时，Kilo Code 将： + +1. 对你的项目进行详尽的分析，包括： + - 所有源代码文件及其关系 + - 配置文件和构建系统设置 + - 项目结构和组织模式 + - 文档和注释 + - 依赖项和外部集成 + - 测试框架和模式 +2. 在 `.kilocode/rules/memory-bank` 文件夹中创建全面的 Memory Bank 文件 +3. 提供对其对项目的理解的详细摘要 +4. 要求你验证生成文件的准确性 + +:::warning 重要 +初始化后，请花时间仔细审查并更正生成的文件。此阶段的任何误解或缺失信息都会影响所有未来的交互。彻底的初始化将显著提高 Kilo Code 的有效性，而仓促或不完整的初始化将永久限制其有效协助你的能力。 +::: + +#### Memory Bank 更新 + +Memory Bank 更新发生在以下情况： +1. 发现新的项目模式 +2. 实施重大更改后 +3. 当你明确请求 `update memory bank` 时 +4. 当上下文需要澄清时 + +要执行 Memory Bank 更新，Kilo Code 将： +1. 审查所有项目文件 +2. 记录当前状态 +3. 记录见解和模式 +4. 根据需要更新所有 Memory Bank 文件 + +你可以使用类似 `update memory bank using information from @/Makefile` 的命令来指导 Kilo Code 专注于特定的信息源。 + +#### 常规任务执行 + +在每个任务开始时，Kilo Code： +1. 读取所有 Memory Bank 文件 +2. 在其响应的开头包含 `[Memory Bank: Active]` +3. 提供其对项目理解的简要摘要 +4. 继续执行请求的任务 + +在任务结束时，如果进行了重大更改，Kilo Code 可能会建议更新 Memory Bank，使用短语：“Would you like me to update memory bank to reflect these changes?” + +#### 添加任务工作流程 + +当你完成一个重复的任务时，你可以将其记录下来以备将来参考。这对于遵循现有模式添加功能等任务特别有用。 + +要记录任务，请使用命令 `add task` 或 `store this as a task`。Kilo Code 将： +1. 创建或更新 Memory Bank 文件夹中的 `tasks.md` 文件 +2. 使用当前上下文记录任务： + - 任务名称和描述 + - 需要修改的文件列表 + - 分步工作流程 + - 重要的注意事项 + - 示例实现 + +当开始新任务时，Kilo Code 会检查它是否与任何记录的任务匹配，并遵循已建立的工作流程，以确保不会遗漏任何步骤。 + +### 关键命令 + +- `initialize memory bank` - 在开始新项目时使用 +- `update memory bank` - 启动对当前任务的上下文文档的全面重新分析。**注意：**此操作资源密集，由于可能降低有效性，不建议用于“轻量级”模型。可以多次使用，可与特定指令很好地结合，例如 `update memory bank using information from @/Makefile` +- `add task` 或 `store this as a task` - 记录重复任务以备将来参考 + +### 状态指示器 + +Kilo Code 使用状态指示器来清楚地传达 Memory Bank 状态： + +- `[Memory Bank: Active]` - 表示 Memory Bank 文件已成功读取并正在使用 +- `[Memory Bank: Missing]` - 表示找不到 Memory Bank 文件或文件为空 + +这些指示器出现在 Kilo Code 响应的开头，提供 Memory Bank 状态的即时确认。 + +### 文档更新 + +Memory Bank 更新应自动发生在以下情况： +- 发现新的项目模式 +- 实施重大更改后 +- 当你明确请求 `update memory bank` 时 +- 当上下文需要澄清时 + +## 上下文窗口管理 + +当你与 Kilo Code 一起工作时，你的上下文窗口最终会填满。当你注意到响应速度变慢或引用变得不那么准确时： + +1. 要求 Kilo Code “update memory bank” 以记录当前状态 +2. 开始新的对话/任务 +3. Kilo Code 将在新对话中自动访问你的 Memory Bank + +此过程确保在多个会话之间保持连续性，而不会丢失重要上下文。 + +## 处理不一致 + +如果 Kilo Code 检测到 Memory Bank 文件之间的不一致： + +1. 它将优先考虑 `brief.md` 中的信息作为真相来源 +2. 向你指出任何不一致之处 +3. 继续使用最可靠的信息 + +这确保即使文档不完美，Kilo Code 仍然可以有效地工作。 + +## 常见问题解答 + +### Memory Bank 文件存储在哪里？ +Memory Bank 文件是存储在项目仓库中的常规 Markdown 文件，通常在 `.kilocode/rules/memory-bank/` 文件夹中。它们不是隐藏的系统文件——它们旨在成为项目文档的一部分。 + +### 我应该多久更新一次 Memory Bank？ +在重大里程碑或方向变化后更新 Memory Bank。对于活跃的开发，每隔几次会话更新一次会很有帮助。当你希望确保所有上下文都得到保留时，请使用“update memory bank”命令。 + +### 我可以手动编辑 Memory Bank 文件吗？ +是的！虽然 Kilo Code 管理大多数文件，但你可以手动编辑其中任何文件。`brief.md` 文件专门设计为由你维护。Kilo Code 会尊重对其他文件的手动编辑。 + +### 如果 Memory Bank 文件丢失会发生什么？ +如果 Memory Bank 文件丢失，Kilo Code 会在其响应的开头显示 `[Memory Bank: Missing]`，并建议初始化 Memory Bank。 + +### Memory Bank 是否适用于所有 AI 模型？ +Memory Bank 适用于所有 AI 模型，但更强大的模型将创建更全面和准确的 Memory Bank 文件。轻量级模型可能难以处理分析和更新 Memory Bank 文件的资源密集型过程。 + +### 我可以在多个项目中使用 Memory Bank 吗？ +是的！每个项目都有自己的 Memory Bank，位于其 `.kilocode/rules/memory-bank/` 文件夹中。Kilo Code 会自动为每个项目使用正确的 Memory Bank。 + +### Memory Bank 是否会占用我的上下文窗口？ +是的，Memory Bank 在每个会话开始时确实会占用一些上下文窗口，因为它会加载所有 Memory Bank 文件。然而，这是一个战略性的权衡，可以显著提高整体效率。通过预先加载项目上下文： + +- 你消除了重复解释，这些解释会随着时间的推移消耗更多的上下文 +- 你可以通过更少的来回交流达到富有成效的结果 +- 你在整个会话中保持一致性理解 + +测试表明，虽然 Memory Bank 最初使用了更多的 token，但它显著减少了实现结果所需的总交互次数。这意味着更少的时间解释和更多的时间构建。 + +## 最佳实践 + +### 开始使用 +- 从基本项目摘要开始，让结构逐步发展 +- 让 Kilo Code 帮助创建初始结构 +- 根据需要审查和调整文件以匹配你的工作流程 +- 初始化后验证生成文件的准确性 + +### 持续工作 +- 让模式随着工作自然出现 +- 不要强制文档更新——它们应该有机地发生 +- 信任过程——价值会随着时间的推移而复合 +- 在会话开始时注意上下文确认 +- 使用状态指示器确认 Memory Bank 处于活动状态 + +### 文档流程 +- `brief.md` 是你的基础 +- `context.md` 变化最频繁 +- 所有文件共同维护项目智能 +- 在重大里程碑或方向变化后更新 + +### 优化 Memory Bank 性能 +- 保持 Memory Bank 文件简洁且重点突出 +- 使用附加文件进行详细文档记录 +- 定期更新但不要过度 +- 专注于特定方面时使用特定的更新命令 + +## 记住 + +Memory Bank 是 Kilo Code 与之前工作的唯一链接。其有效性完全依赖于在每个交互中维护清晰、准确的文档并确认上下文保留。当你在响应开头看到 `[Memory Bank: Active]` 时，你可以确信 Kilo Code 对你的项目有全面的理解。 \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/prompt-engineering.md b/docs/zh-CN/advanced-usage/prompt-engineering.md new file mode 100644 index 0000000..6242bbe --- /dev/null +++ b/docs/zh-CN/advanced-usage/prompt-engineering.md @@ -0,0 +1,91 @@ +# Prompt Engineering 技巧 + +Prompt engineering 是为 AI 模型（如 Kilo Code）编写有效指令的艺术。精心编写的提示可以带来更好的结果、更少的错误和更高的工作效率。 + +## 通用原则 + +* **清晰且具体：** 清楚地说明你希望 Kilo Code 做什么。避免歧义。 + * **不好：** 修复代码。 + * **好：** 修复 `calculateTotal` 函数中导致返回错误结果的 bug。 + +* **提供上下文：** 使用 [上下文提及](/basic-usage/context-mentions) 来引用特定文件、文件夹或问题。 + * **好：** `@/src/utils.ts` 重构 `calculateTotal` 函数以使用 async/await。 + +* **分解任务：** 将复杂的任务分解为更小、定义明确的步骤。 + +* **提供示例：** 如果你有特定的编码风格或模式，请提供示例。 + +* **指定输出格式：** 如果你需要特定格式的输出（例如 JSON、Markdown），请在提示中指定。 + +* **迭代：** 如果初始结果不符合预期，不要害怕优化你的提示。 + +## 思考与执行 + +引导 Kilo Code 通过“先思考后执行”的过程通常很有帮助： + +1. **分析：** 让 Kilo Code 分析当前代码，识别问题或规划方法。 +2. **计划：** 让 Kilo Code 概述完成任务的步骤。 +3. **执行：** 指示 Kilo Code 一步一步地执行计划。 +4. **审查：** 在继续之前仔细审查每一步的结果。 + +## 使用自定义指令 + +你可以提供自定义指令来进一步调整 Kilo Code 的行为。有两种类型的自定义指令： + +* **全局自定义指令：** 适用于所有模式。 +* **模式特定自定义指令：** 仅适用于特定模式（例如 Code、Architect、Ask、Debug 或自定义模式）。 + +自定义指令会添加到系统提示中，为 AI 模型提供持续的指导。你可以使用这些指令来： + +* 强制执行编码风格指南。 +* 指定首选的库或框架。 +* 定义项目特定的约定。 +* 调整 Kilo Code 的语气或个性。 + +有关更多详细信息，请参阅 [自定义指令](/advanced-usage/custom-instructions) 部分。 + +## 处理歧义 + +如果你的请求含糊不清或缺乏足够的细节，Kilo Code 可能会： + +* **做出假设：** 它可能会根据最佳猜测继续，这可能不是你想要的。 +* **询问后续问题：** 它可能会使用 `ask_followup_question` 工具来澄清你的请求。 + +最好从一开始就提供清晰且具体的指令，以避免不必要的来回沟通。 + +## 提供反馈 + +如果 Kilo Code 没有产生预期的结果，你可以通过以下方式提供反馈： + +* **拒绝操作：** 当 Kilo Code 提出你不想要的操作时，点击“拒绝”按钮。 +* **提供解释：** 拒绝时，解释*为什么*要拒绝该操作。这有助于 Kilo Code 从错误中学习。 +* **重新措辞你的请求：** 尝试重新表述你的初始任务或提供更具体的指令。 +* **手动更正：** 如果有几个小问题，你也可以在接受更改之前直接修改代码。 + +## 示例 + +**好提示：** + +> `@/src/components/Button.tsx` 重构 `Button` 组件以使用 `useState` 钩子而不是 `useReducer` 钩子。 + +**不好提示：** + +> 修复按钮。 + +**好提示：** + +> 创建一个名为 `utils.py` 的新文件，并添加一个名为 `calculate_average` 的函数，该函数接受一个数字列表并返回它们的平均值。 + +**不好提示：** + +> 写一些 Python 代码。 + +**好提示：** + +> `@problems` 解决当前文件中的所有错误和警告。 + +**不好提示：** + +> 修复所有问题。 + +通过遵循这些技巧，你可以编写有效的提示，充分利用 Kilo Code 的能力。 \ No newline at end of file diff --git a/docs/zh-CN/advanced-usage/rate-limits-costs.md b/docs/zh-CN/advanced-usage/rate-limits-costs.md new file mode 100644 index 0000000..e32eaee --- /dev/null +++ b/docs/zh-CN/advanced-usage/rate-limits-costs.md @@ -0,0 +1,51 @@ +# 速率限制与成本 + +了解和管理 API 使用情况对于在 Kilo Code 中获得流畅且经济高效的体验至关重要。本节将解释如何跟踪你的 token 使用情况、成本以及如何配置速率限制。 + +## Token 使用 + +Kilo Code 使用 token 与 AI 模型进行交互。Token 本质上是词语的组成部分。请求和响应中使用的 token 数量会影响处理时间和成本。 + +* **输入 Token：**这些是你的提示中的 token，包括系统提示、你的指令以及提供的任何上下文（例如文件内容）。 +* **输出 Token：**这些是 AI 模型在响应中生成的 token。 + +你可以在聊天记录中查看每次交互的输入和输出 token 数量。 + +## 成本计算 + +大多数 AI 提供商根据使用的 token 数量收费。价格因提供商和具体模型而异。 + +Kilo Code 会根据配置的模型定价自动计算每次 API 请求的预估成本。该成本显示在聊天记录中，紧邻 token 使用情况。 + +**注意：** + +* 成本计算是*预估*值。实际成本可能因提供商的计费方式而略有不同。 +* 一些提供商可能提供免费层级或信用额度。请查看提供商的文档以获取详细信息。 +* 一些提供商提供提示缓存，可以显著降低成本。 + +## 配置速率限制 + +为了防止意外过度使用 API 并帮助你管理成本，Kilo Code 允许你设置速率限制。速率限制定义了 API 请求之间的最短时间（以秒为单位）。 + +**如何配置：** + +1. 打开 Kilo Code 设置（右上角的 图标）。 +2. 转到“高级设置”部分。 +3. 找到“速率限制（秒）”设置。 +4. 输入所需的延迟时间（以秒为单位）。值为 0 表示禁用速率限制。 + +**示例：** + +如果你将速率限制设置为 10 秒，Kilo Code 会在一个 API 请求完成后至少等待 10 秒再发送下一个请求。 + +## 优化 Token 使用的技巧 + +* **简洁明了：**在提示中使用清晰简洁的语言。避免不必要的词语或细节。 +* **仅提供相关上下文：**选择性使用上下文提及（`@file.ts`，`@folder/`）。仅包括与任务直接相关的文件。 +* **分解任务：**将大型任务分解为更小、更专注的子任务。 +* **使用自定义指令：**提供自定义指令以指导 Kilo Code 的行为，减少每次提示中冗长的解释。 +* **选择合适的模型：**某些模型比其他模型更具成本效益。对于不需要较大模型全部功能的任务，可以考虑使用更小、更快的模型。 +* **使用模式：**不同的模式可以访问不同的工具，例如 `Architect` 无法修改代码，这使其成为分析复杂代码库时的安全选择，而无需担心意外允许昂贵的操作。 +* **如果未使用 MCP 则禁用它：**如果你未使用 MCP（模型上下文协议）功能，请考虑[在 MCP 设置中禁用它](/features/mcp/using-mcp-in-kilo-code#enabling-or-disabling-mcp-server-creation)，以显著减少系统提示的大小并节省 token。 + +通过了解和管理你的 API 使用情况，你可以高效且经济地使用 Kilo Code。 \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/adding-tokens.md b/docs/zh-CN/basic-usage/adding-tokens.md new file mode 100644 index 0000000..c6d786d --- /dev/null +++ b/docs/zh-CN/basic-usage/adding-tokens.md @@ -0,0 +1,28 @@ +import { DISCORD_URL } from '@site/src/constants.ts' + +# 添加更多 Tokens + +当你用完初始的免费 tokens 后，你可以轻松添加更多： + +- 为你的账户添加信用卡（所有支付均通过 Stripe 安全处理） +- 我们目前不提供订阅服务，因此你只需为使用的 tokens 付费，并且仅在你选择充值 tokens 时付费！ +- 通过[连接你自己的 API 提供商](/getting-started/connecting-api-provider.md) 来利用你自己的 API 提供商 + +## 透明的定价 + +在 Kilo Code，我们相信完全透明的定价： + +- 我们的定价与模型提供商的 API 费率完全一致 +- 我们不收取任何佣金或加价，无论是按 token 还是按充值 +- 你只需为使用的 tokens 付费，没有任何隐藏费用 + +## 未来计划 + +我们正在不断改进 Kilo Code 并扩展我们的服务： + +- 未来将添加更多 LLM 提供商 +- 更多支付选项和其他计划正在开发中 + +:::tip 需要帮助？ +如果你对定价或 tokens 有任何疑问，请联系我们的[支持团队](mailto:hi@kilocode.ai) 或在我们的 Discord 社区中提问。 +::: \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/context-mentions.md b/docs/zh-CN/basic-usage/context-mentions.md new file mode 100644 index 0000000..8e59536 --- /dev/null +++ b/docs/zh-CN/basic-usage/context-mentions.md @@ -0,0 +1,126 @@ +# 上下文提及 + +上下文提及是一种强大的方式，可以为 Kilo Code 提供项目的具体信息，使其能够更准确高效地执行任务。你可以使用提及来引用文件、文件夹、问题和 Git 提交。上下文提及以 `@` 符号开头。 + +上下文提及概览 - 显示聊天界面中的 @ 符号下拉菜单 + +*上下文提及概览，显示聊天界面中的 @ 符号下拉菜单。* + +## 提及类型 + +文件提及示例，显示使用 @ 引用文件及其内容出现在对话中 + +*文件提及将实际代码内容添加到对话中，以便直接引用和分析。* + +| 提及类型 | 格式 | 描述 | 示例用法 | +|--------------|--------|-------------|--------------| +| **文件** | `@/path/to/file.ts` | 将文件内容包含在请求上下文中 | "解释 @/src/utils.ts 中的函数" | +| **文件夹** | `@/path/to/folder/` | 以树状格式提供目录结构 | "@/src/components/ 中有哪些文件？" | +| **问题** | `@problems` | 包含 VS Code 问题面板的诊断信息 | "@problems 修复我代码中的所有错误" | +| **终端** | `@terminal` | 包含最近的终端命令和输出 | "修复 @terminal 中显示的错误" | +| **Git 提交** | `@a1b2c3d` | 通过哈希引用特定提交 | "提交 @a1b2c3d 中有什么变化？" | +| **Git 更改** | `@git-changes` | 显示未提交的更改 | "为 @git-changes 建议一条提交消息" | +| **URL** | `@https://example.com` | 导入网站内容 | "总结 @https://docusaurus.io/" | + +### 文件提及 + +文件提及示例，显示使用 @ 引用文件及其内容出现在对话中 + +*文件提及结合行号引用源代码，以便精确定位。* + +| 能力 | 详情 | +|------------|---------| +| **格式** | `@/path/to/file.ts`（始终从工作区根目录开始使用 `/`） | +| **提供** | 包含行号的完整文件内容 | +| **支持** | 文本文件、PDF 和 DOCX 文件（带文本提取） | +| **适用场景** | 初始请求、反馈响应和后续消息 | +| **限制** | 非常大的文件可能会被截断；不支持二进制文件 | + +### 文件夹提及 + +文件夹提及示例，显示目录内容在聊天中被引用 + +*文件夹提及以可读的树状格式显示目录结构。* + +| 能力 | 详情 | +|------------|---------| +| **格式** | `@/path/to/folder/`（注意尾部的斜杠） | +| **提供** | 使用 ├── 和 └── 前缀的分层树状显示 | +| **包含** | 直接子文件和目录（非递归） | +| **最佳用途** | 了解项目结构 | +| **提示** | 结合文件提及检查特定文件内容 | + +### 问题提及 + +问题提及示例，显示使用 @problems 引用 VS Code 问题面板 + +*问题提及直接从 VS Code 的问题面板导入诊断信息。* + +| 能力 | 详情 | +|------------|---------| +| **格式** | `@problems` | +| **提供** | VS Code 问题面板中的所有错误和警告 | +| **包含** | 文件路径、行号和诊断信息 | +| **分组** | 问题按文件组织以提高清晰度 | +| **最佳用途** | 修复错误而无需手动复制 | + +### 终端提及 +终端提及示例，显示终端输出被包含在 Kilo Code 的上下文中 + +*终端提及捕获最近的命令输出以便调试和分析。* + +| 能力 | 详情 | +|------------|---------| +| **格式** | `@terminal` | +| **捕获** | 最后一条命令及其完整输出 | +| **保留** | 终端状态（不会清除终端） | +| **限制** | 仅限于可见的终端缓冲区内容 | +| **最佳用途** | 调试构建错误或分析命令输出 | + +### Git 提及 + +Git 提交提及示例，显示提交详情被 Kilo Code 分析 + +*Git 提及提供提交详情和差异，以便进行上下文感知的版本分析。* + +| 类型 | 格式 | 提供 | 限制 | +|------|--------|----------|------------| +| **提交** | `@a1b2c3d` | 提交消息、作者、日期和完整差异 | 仅适用于 Git 仓库 | +| **工作区更改** | `@git-changes` | `git status` 输出和未提交更改的差异 | 仅适用于 Git 仓库 | + +### URL 提及 +URL 提及示例，显示网站内容被转换为 Markdown 格式出现在聊天中 + +*URL 提及导入外部网页内容并将其转换为可读的 Markdown 格式。* + +| 能力 | 详情 | +|------------|---------| +| **格式** | `@https://example.com` | +| **处理** | 使用无头浏览器获取内容 | +| **清理** | 移除脚本、样式和导航元素 | +| **输出** | 将内容转换为 Markdown 以提高可读性 | +| **限制** | 复杂页面可能无法完美转换 | + +## 如何使用提及 + +1. 在聊天输入框中输入 `@` 以触发建议下拉菜单 +2. 继续输入以过滤建议，或使用箭头键导航 +3. 按回车键或鼠标点击选择 +4. 在请求中组合多个提及："修复 @/src/component.ts 中的 @problems" + +下拉菜单会自动建议： +- 最近打开的文件 +- 可见的文件夹 +- 最近的 Git 提交 +- 特殊关键字（`problems`、`terminal`、`git-changes`） + +## 最佳实践 + +| 实践 | 描述 | +|----------|-------------| +| **使用具体路径** | 引用确切文件而非描述它们 | +| **使用相对路径** | 始终从工作区根目录开始：`@/src/file.ts` 而非 `@C:/Projects/src/file.ts` | +| **验证引用** | 确保路径和提交哈希正确 | +| **点击提及** | 点击聊天历史中的提及以打开文件或查看内容 | +| **避免复制粘贴** | 使用提及而非手动复制代码或错误信息 | +| **组合提及** | "使用提交 @a1b2c3d 中的模式修复 @/src/component.ts 中的 @problems" | \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/how-tools-work.md b/docs/zh-CN/basic-usage/how-tools-work.md new file mode 100644 index 0000000..cf5d15d --- /dev/null +++ b/docs/zh-CN/basic-usage/how-tools-work.md @@ -0,0 +1,82 @@ +# 工具工作原理 + +Kilo Code 通过工具与你的代码和环境进行交互。这些专业助手可以执行特定操作，如读取文件、编辑内容、运行命令或搜索代码库。工具为常见开发任务提供自动化能力，无需手动执行。 + +## 工具工作流程 + +用自然语言描述你想完成的任务，Kilo Code 将会： + +1. 根据你的请求选择合适的工具 +2. 展示工具及其参数供你审核 +3. 执行已批准的工具并显示结果 +4. 重复此过程直至任务完成 + +## 工具分类 + +| 类别 | 用途 | 工具名称 | +| :--- | :--- | :------- | +| 读取 | 访问文件内容和代码结构 | `read_file`, `search_files`, `list_files`, `list_code_definition_names` | +| 编辑 | 创建或修改文件和代码 | `write_to_file`, `apply_diff` | +| 执行 | 运行命令和系统操作 | `execute_command` | +| 浏览器 | 与网页内容交互 | `browser_action` | +| 工作流 | 管理任务流程和上下文 | `ask_followup_question`, `attempt_completion`, `switch_mode`, `new_task` | + +## 示例：工具使用 + +以下是典型的工具交互过程： + +工具审批界面显示保存和拒绝按钮以及自动批准复选框 + +*工具审批界面显示保存/拒绝按钮和自动批准选项。* + +**用户：** 创建一个名为 `greeting.js` 的文件，用于输出问候消息 + +**Kilo Code：** (建议使用 `write_to_file` 工具，如上图所示) +```xml + +greeting.js + +function greet(name) { + console.log(`Hello, ${name}!`); +} + +greet('World'); + +5 + +``` + +**用户：** (点击界面中的"保存"按钮) + +**Kilo Code：** (确认文件创建成功) + +## 工具安全与审批 + +每次使用工具都需要你的明确批准。当 Kilo 建议使用工具时，你会看到： + +* "保存"按钮 - 批准并执行工具 +* "拒绝"按钮 - 拒绝建议的工具 +* 可选的"自动批准"设置 - 用于信任的操作 + +此安全机制确保你能完全控制哪些文件被修改、执行哪些命令以及如何更改代码库。执行前请务必仔细审查工具建议。 + +## 核心工具参考 + +| 工具名称 | 描述 | 类别 | +| :------- | :--- | :--- | +| `read_file` | 读取带行号的文件内容 | 读取 | +| `search_files` | 跨文件搜索文本或正则表达式 | 读取 | +| `list_files` | 列出指定位置的文件和目录 | 读取 | +| `list_code_definition_names` | 列出类/函数等代码定义 | 读取 | +| `write_to_file` | 创建新文件或覆盖现有文件 | 编辑 | +| `apply_diff` | 对文件特定部分进行精确修改 | 编辑 | +| `execute_command` | 在 VS Code 终端中运行命令 | 执行 | +| `browser_action` | 在无头浏览器中执行操作 | 浏览器 | +| `ask_followup_question` | 向你提出澄清问题 | 工作流 | +| `attempt_completion` | 标记任务已完成 | 工作流 | +| `switch_mode` | 切换到不同操作模式 | 工作流 | +| `new_task` | 创建具有特定启动模式的子任务 | 工作流 | + +## 了解更多工具信息 + +有关每个工具的完整参数参考和高级用法，请参阅[工具使用概述](/features/tools/tool-use-overview)文档。 \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/orchestrator-mode.md b/docs/zh-CN/basic-usage/orchestrator-mode.md new file mode 100644 index 0000000..ffd5cb6 --- /dev/null +++ b/docs/zh-CN/basic-usage/orchestrator-mode.md @@ -0,0 +1,46 @@ +--- +sidebar_label: 'Orchestrator Mode' +--- + +import YouTubeEmbed from '@site/src/components/YouTubeEmbed'; + +# Orchestrator Mode：协调复杂工作流 + +Orchestrator Mode（原称为 Boomerang Tasks）允许你将复杂项目分解为更小、更易管理的部分。你可以将其理解为将工作的各个部分委派给专门的助手。每个子任务都在自己的上下文中运行，通常使用为特定工作定制的不同 Kilo Code 模式（如 [`code`](/basic-usage/using-modes#code-mode-default)、[`architect`](/basic-usage/using-modes#architect-mode) 或 [`debug`](/basic-usage/using-modes#debug-mode)）。 + + + +## 为什么使用 Orchestrator Mode？ + +- **处理复杂性**：将大型、多步骤项目（如构建完整功能）分解为专注的子任务（如设计、实现、文档）。 +- **使用专门模式**：自动将子任务委派给最适合该工作的模式，利用其专门能力以获得最佳结果。 +- **保持专注与效率**：每个子任务都在其独立的上下文中运行，具有单独的对话历史。这可以防止父任务（orchestrator）被详细的执行步骤（如代码差异或文件分析结果）所干扰，使其能够专注于高层次的工作流，并根据已完成子任务的简洁摘要高效管理整体流程。 +- **简化工作流**：一个子任务的结果可以自动传递给下一个子任务，从而创建顺畅的工作流（例如，架构决策直接传递给编码任务）。 + +## 工作原理 + +1. 使用 Orchestrator Mode，Kilo 可以分析复杂任务并建议将其分解为子任务[^1]。 +2. 父任务暂停，新的子任务以不同模式开始[^2]。 +3. 当子任务的目标达成时，Kilo 会发出完成信号。 +4. 父任务恢复，并仅接收子任务的摘要[^3]。父任务使用该摘要继续主工作流。 + +## 关键注意事项 + +- **需要批准**：默认情况下，每个子任务的创建和完成都需要你的批准。如果需要，可以通过 [Auto-Approving Actions](/features/auto-approving-actions#subtasks) 设置自动完成此操作。 +- **上下文隔离与传递**：每个子任务都在完全隔离的上下文中运行，具有自己的对话历史。它不会自动继承父任务的上下文。信息必须显式传递： + * **向下**：在子任务创建时通过初始指令传递。 + * **向上**：在子任务完成时通过最终摘要传递。注意，只有该摘要会返回给父任务。 +- **导航**：Kilo 的界面帮助你查看任务的层次结构（哪个任务是父任务，哪些是子任务）。你通常可以在活动和暂停的任务之间导航。 + +Orchestrator Mode 提供了一种强大的方式来管理复杂的开发工作流，直接在 Kilo Code 中利用专门模式以实现最大效率。 + +:::tip 保持任务专注 +使用子任务来保持清晰度。如果请求显著改变了焦点或需要不同的专业知识（模式），请考虑创建子任务，而不是让当前任务过载。 +::: + +[^1]: 此上下文通过 [`new_task`](/features/tools/new-task) 工具的 `message` 参数传递。 +[^2]: 子任务的模式通过 [`new_task`](/features/tools/new-task) 工具的 `mode` 参数在启动时指定。 +[^3]: 此摘要通过 [`attempt_completion`](/features/tools/attempt-completion) 工具的 `result` 参数在子任务完成时传递。 \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/the-chat-interface.md b/docs/zh-CN/basic-usage/the-chat-interface.md new file mode 100644 index 0000000..a758a84 --- /dev/null +++ b/docs/zh-CN/basic-usage/the-chat-interface.md @@ -0,0 +1,43 @@ +import Image from '@site/src/components/Image'; + +# 聊天界面 + +Kilo Code 的聊天界面是你与其交互的主要方式。它位于 Kilo Code 面板中，你可以通过点击 VS Code 主侧边栏中的 Kilo Code 图标（）来打开它。 + +Kilo Code 面板也可以移动到 VS Code 的次侧边栏。如果你不小心关闭了 Kilo Code 面板，可以通过 视图 > 打开视图... 并搜索 "Kilo Code" 来重新打开它。 + +## 聊天界面的组成部分 + +聊天界面由以下主要元素组成： + +1. **聊天/任务历史记录：** 该区域显示你与 Kilo Code 之间的对话历史记录，或者如果你没有当前任务，则显示你创建的所有任务的历史记录。它显示你的请求、Kilo Code 的响应以及任何已执行的操作（如文件编辑或命令执行）。 + +2. **输入框：** 这是你输入任务和问题的地方。你可以使用 [纯英文](/basic-usage/typing-your-requests) 来传达你希望 Kilo Code 执行的操作。 + +3. **操作按钮：** 这些按钮出现在输入框下方，允许你批准或拒绝 Kilo Code 提出的操作。根据上下文和你的 [自动批准设置](/features/auto-approving-actions)，可用的按钮会有所不同。 + +4. **发送按钮：** 这是一个小飞机图标，位于输入框的最右侧。在你输入消息后，点击此按钮即可发送消息。或者，你可以直接按 `Enter` 键。 + +5. **加号按钮：** 加号按钮位于顶部的标题栏中，用于启动一个新的任务会话。 + +6. **设置按钮：** 设置按钮是一个齿轮图标，用于打开设置以自定义功能或行为。 + +7. **模式选择器：** 模式选择器是一个下拉菜单，位于聊天输入框的左侧。它用于选择 Kilo Code 执行任务时使用的模式。 + +聊天界面组件标注 + +## 与消息交互 + +* **可点击的链接：** 聊天历史记录中的文件路径、URL 和其他提及内容是可点击的。点击文件路径将在编辑器中打开该文件。点击 URL 将在默认浏览器中打开它。 +* **复制文本：** 你可以通过选择文本并使用标准复制命令（`Ctrl/Cmd + C`）来复制聊天历史记录中的文本。某些元素（如代码块）具有专用的“复制”按钮。 +* **展开和折叠：** 点击消息以展开或折叠它。 + +## 状态指示器 + +* **加载旋转器：** 当 Kilo Code 正在处理请求时，你会看到一个加载旋转器。 +* **错误消息：** 如果发生错误，将显示一条红色错误消息。 +* **成功消息：** 绿色消息表示操作已成功完成。 \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/typing-your-requests.md b/docs/zh-CN/basic-usage/typing-your-requests.md new file mode 100644 index 0000000..c2578a9 --- /dev/null +++ b/docs/zh-CN/basic-usage/typing-your-requests.md @@ -0,0 +1,49 @@ +import Image from '@site/src/components/Image'; + +# 输入你的请求 + +Kilo Code 设计为理解自然语言。你不需要使用任何特殊命令或语法来与其交流。只需用简单的英语输入你的请求，就像与人类开发者对话一样。 + +在 Kilo Code 中输入请求的示例 + +## 有效的请求策略 + +清晰地表达你希望 Kilo Code 执行的操作。避免使用模糊或模棱两可的语言。 + +| 策略 | 实现 | +|----------|----------------| +| **具体明确** | 使用“修复 `calculateTotal` 中返回错误结果的 bug”而不是“修复代码” | +| **提供上下文** | 使用 `@` [上下文提及](/basic-usage/context-mentions) 来引用文件和代码 | +| **分解任务** | 将复杂任务拆分为更小、可管理的步骤 | +| **包含示例** | 当需要特定格式或样式时，提供示例代码（或使用 `@` 引用现有代码） | + +## 示例请求 + +``` +创建一个名为 `utils.py` 的新文件，并添加一个名为 `add` 的函数，该函数接受两个数字作为参数并返回它们的和 +``` +``` +在文件 @src/components/Button.tsx 中，将按钮的颜色更改为蓝色 +``` +``` +在 @/src/App.js 中找到所有变量 `oldValue` 的实例，并将它们替换为 `newValue` +``` +``` +在终端中运行命令 `npm install` +``` +``` +解释 @/src/utils.ts 中的函数 `calculateTotal` +``` +``` +@problems 解决所有检测到的问题 +``` + +## 需要避免的常见错误 + +| 不要 | 应该 | +|-------|---------| +| 模糊的请求 | 明确指定需要完成的操作 | +| 假设上下文 | 明确引用文件和函数 | +| 过多的技术术语 | 使用清晰、直接的语言 | +| 多个不相关的任务 | 一次提交一个专注的请求 | +| 未经确认就继续 | 检查代码以确保其完整 | \ No newline at end of file diff --git a/docs/zh-CN/basic-usage/using-modes.md b/docs/zh-CN/basic-usage/using-modes.md new file mode 100644 index 0000000..118c687 --- /dev/null +++ b/docs/zh-CN/basic-usage/using-modes.md @@ -0,0 +1,90 @@ +# 使用模式 + +Kilo Code 中的模式是专门设计的角色，可以根据当前任务调整助手的行为。每种模式都提供不同的能力、专业知识和访问权限，帮助你完成特定目标。 + +## 为什么使用不同的模式？ + +- **任务专业化**：获得针对当前任务所需的精确帮助 +- **安全控制**：在专注于规划或学习时，防止意外的文件修改 +- **专注交互**：接收针对当前活动优化的响应 +- **工作流优化**：在规划、实施、调试和学习之间无缝切换 + + + +## 切换模式 + +四种切换模式的方式： + +1. **下拉菜单**：点击聊天输入框左侧的选择器 + + 使用下拉菜单切换模式 + +2. **斜杠命令**：在聊天输入框中输入 `/architect`、`/ask`、`/debug` 或 `/code` + + 使用斜杠命令切换模式 + +3. **切换命令/键盘快捷键**：使用适用于你操作系统的键盘快捷键。每次按下都会按顺序循环切换可用模式，到达末尾后返回第一个模式。 + + | 操作系统 | 快捷键 | + |----------|--------| + | macOS | ⌘ + . | + | Windows | Ctrl + . | + | Linux | Ctrl + . | + +4. **接受建议**：在适当时点击 Kilo Code 提供的模式切换建议 + + 接受 Kilo Code 提供的模式切换建议 + +## 内置模式 + +### 代码模式（默认） + +| 方面 | 详细信息 | +|------|----------| +| **描述** | 一位熟练的软件工程师，精通编程语言、设计模式和最佳实践 | +| **工具访问** | 完全访问所有工具组：`read`、`edit`、`browser`、`command`、`mcp` | +| **适合场景** | 编写代码、实现功能、调试和一般开发 | +| **特殊功能** | 无工具限制——所有编码任务完全灵活 | + +### 问答模式 + +| 方面 | 详细信息 | +|------|----------| +| **描述** | 一位知识渊博的技术助手，专注于回答问题而不修改代码库 | +| **工具访问** | 有限访问：仅 `read`、`browser`、`mcp`（无法编辑文件或运行命令） | +| **适合场景** | 代码解释、概念探索和技术学习 | +| **特殊功能** | 优化为在不修改项目的情况下提供信息丰富的响应 | + +### 架构师模式 + +| 方面 | 详细信息 | +|------|----------| +| **描述** | 一位经验丰富的技术领导和规划者，帮助设计系统并创建实施计划 | +| **工具访问** | 访问 `read`、`browser`、`mcp` 和受限的 `edit`（仅限 markdown 文件） | +| **适合场景** | 系统设计、高层规划和架构讨论 | +| **特殊功能** | 遵循从信息收集到详细规划的结构化方法 | + +### 调试模式 + +| 方面 | 详细信息 | +|------|----------| +| **描述** | 一位擅长系统化故障排除和诊断的专家问题解决者 | +| **工具访问** | 完全访问所有工具组：`read`、`edit`、`browser`、`command`、`mcp` | +| **适合场景** | 追踪错误、诊断问题并解决复杂问题 | +| **特殊功能** | 使用分析、缩小可能性和修复问题的系统化方法 | + +### 协调者模式 + +| 方面 | 详细信息 | +|------|----------| +| **描述** | 一位战略工作流协调者，通过将复杂任务委派给适当的专业模式来协调工作 | +| **工具访问** | 有限的访问权限，用于创建新任务和协调工作流 | +| **适合场景** | 将复杂项目分解为可管理的子任务，并分配给专业模式 | +| **特殊功能** | 使用 new_task 工具将工作委派给其他模式 | + +## 自定义模式 + +通过定义工具访问权限、文件权限和行为指令，创建你自己的专业助手。自定义模式有助于执行团队标准或创建特定用途的助手。有关设置说明，请参阅 [自定义模式文档](/features/custom-modes)。 \ No newline at end of file diff --git a/docs/zh-CN/extending/contributing-to-kilo.md b/docs/zh-CN/extending/contributing-to-kilo.md new file mode 100644 index 0000000..a12e091 --- /dev/null +++ b/docs/zh-CN/extending/contributing-to-kilo.md @@ -0,0 +1,125 @@ +# 为 Kilo Code 做贡献 + +Kilo Code 是一个开源项目，欢迎所有技能水平的开发者贡献代码。本指南将帮助你开始为 Kilo Code 做出贡献，无论是修复错误、添加功能、改进文档还是分享自定义模式。 + +## 贡献方式 + +有多种方式可以为 Kilo Code 做出贡献： + +1. **代码贡献**：实现新功能或修复错误 +2. **文档**：改进现有文档或创建新指南 +3. **自定义模式**：创建并分享专用模式 +4. **错误报告**：报告你遇到的问题 +5. **功能请求**：建议新功能或改进 +6. **社区支持**：在社区中帮助其他用户 + +## 设置开发环境 + +设置开发环境的详细说明请参阅[此页面](/docs/extending/development-environment.md) + +## 开发工作流 + +### 分支策略 + +- 为每个功能或错误修复创建一个新分支 +- 使用描述性的分支名称（例如 `feature/new-tool-support` 或 `fix/browser-action-bug`） + +```bash +git checkout -b your-branch-name +``` + +### 编码标准 + +- 遵循现有的代码风格和模式 +- 新代码使用 TypeScript +- 为新功能包含适当的测试 +- 更新文档以反映任何面向用户的更改 + +### 提交指南 + +- 编写清晰、简洁的提交信息 +- 在适用时引用问题编号 +- 保持每次提交专注于单一更改 + +### 测试你的更改 + +- 运行测试套件： + ```bash + npm test + ``` +- 在开发扩展中手动测试你的更改 + +### 创建拉取请求 + +1. 将你的更改推送到你的 fork： + ```bash + git push origin your-branch-name + ``` + +2. 前往 [Kilo Code 仓库](https://github.com/Kilo-Org/kilocode) + +3. 点击 "New Pull Request" 并选择 "compare across forks" + +4. 选择你的 fork 和分支 + +5. 填写 PR 模板，包括： + - 更改的清晰描述 + - 任何相关问题 + - 测试步骤 + - 截图（如适用） + +## 创建自定义模式 + +自定义模式是扩展 Kilo Code 功能的强大方式。要创建并分享自定义模式： + +1. 按照 [自定义模式文档](/features/custom-modes) 创建你的模式 + +2. 彻底测试你的模式 + +3. 通过提交 [GitHub Discussion](https://github.com/Kilo-Org/kilocode/discussions) 与社区分享你的模式 + +## 文档贡献 + +文档改进是非常有价值的贡献： + +1. 遵循文档风格指南： + - 使用清晰、简洁的语言 + - 在适当时包含示例 + - 使用以 `/docs/` 开头的绝对路径作为内部链接 + - 不要在链接中包含 `.md` 扩展名 + +2. 通过本地运行文档站点测试你的文档更改： + ```bash + cd docs + npm install + npm start + ``` + +3. 提交包含文档更改的 PR + +## 社区准则 + +参与 Kilo Code 社区时： + +- 保持尊重和包容 +- 提供建设性的反馈 +- 帮助新手入门 +- 遵守 [行为准则](https://github.com/Kilo-Org/kilocode/blob/main/CODE_OF_CONDUCT.md) + +## 获取帮助 + +如果你需要帮助： + +- 加入我们的 [Discord 社区](https://kilocode.ai/discord) 获取实时支持 +- 在 [GitHub Discussions](https://github.com/Kilo-Org/kilocode/discussions) 上提问 +- 访问我们的 [Reddit 社区](https://www.reddit.com/r/KiloCode) + +## 致谢 + +所有贡献者都是 Kilo Code 社区的重要成员。贡献者将在以下地方获得认可： + +- 发布说明 +- 项目的 README +- GitHub 上的贡献者列表 + +感谢你为 Kilo Code 做出贡献，帮助让 AI 驱动的编码辅助对每个人更好！ \ No newline at end of file diff --git a/docs/zh-CN/extending/development-environment.md b/docs/zh-CN/extending/development-environment.md new file mode 100644 index 0000000..09f371d --- /dev/null +++ b/docs/zh-CN/extending/development-environment.md @@ -0,0 +1,192 @@ +# 开发环境 + + + +本文档将帮助你设置开发环境，并了解如何与代码库一起工作。无论你是修复错误、添加功能，还是仅仅探索代码，本指南都将帮助你入门。 + +## 先决条件 + +在开始之前，请确保已安装以下内容： + +1. **Git** - 用于版本控制 +2. **Node.js**（建议使用 [v20.18.1](https://github.com/Kilo-Org/kilocode/blob/main/.nvmrc) 或更高版本）和 npm +3. **Visual Studio Code** - 我们推荐的开发 IDE + +## 入门 + +### 安装 + +1. **Fork 并克隆仓库**： + + - **Fork 仓库**： + - 访问 [Kilo Code GitHub 仓库](https://github.com/Kilo-Org/kilocode) + - 点击右上角的 "Fork" 按钮，创建你自己的副本。 + - **克隆你的 Fork**： + ```bash + git clone https://github.com/[YOUR-USERNAME]/kilocode.git + cd kilocode + ``` + 将 `[YOUR-USERNAME]` 替换为你的 GitHub 用户名。 + +2. **安装依赖项**： + + ```bash + npm run install:all + ``` + + 此命令将为主扩展、Webview UI 和 e2e 测试安装依赖项。 + +3. **安装 VSCode 扩展**： + - **必需**：[ESBuild Problem Matchers](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) - 帮助正确显示构建错误。 + +虽然不是运行扩展所必需的，但以下扩展建议用于开发： + +- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 将 ESLint 集成到 VS Code 中。 +- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - 将 Prettier 集成到 VS Code 中。 + +推荐的扩展完整列表在[这里](https://github.com/Kilo-Org/kilocode/blob/main/.vscode/extensions.json) + +### 项目结构 + +项目组织为以下几个关键目录： + +- **`src/`** - 核心扩展代码 + - **`core/`** - 核心功能和工具 + - **`services/`** - 服务实现 +- **`webview-ui/`** - 前端 UI 代码 +- **`e2e/`** - 端到端测试 +- **`scripts/`** - 实用脚本 +- **`assets/`** - 静态资源，如图片和图标 + +## 开发工作流 + +### 构建扩展 + +要构建扩展： + +```bash +npm run build +``` + +这将： + +1. 构建 Webview UI +2. 编译 TypeScript +3. 打包扩展 +4. 在 `bin/` 目录下创建 `.vsix` 文件 + +### 运行扩展 + +要在开发模式下运行扩展： + +1. 在 VSCode 中按 `F5`（或选择 **Run** → **Start Debugging**） +2. 这将打开一个新的 VSCode 窗口，并加载 Kilo Code + +### 热重载 + +- **Webview UI 变更**：Webview UI 的变更会立即生效，无需重启 +- **核心扩展变更**：核心扩展代码的变更会自动重新加载扩展主机 + +在开发模式下（NODE_ENV="development"），更改核心代码将触发 `workbench.action.reloadWindow` 命令，因此不再需要手动启动/停止调试器和任务。 + +> **重要提示**：在生产构建中，更改核心扩展代码时，你需要： +> +> 1. 停止调试过程 +> 2. 终止任何在后台运行的 npm 任务（见下图） +> 3. 重新开始调试 + +Stopping background tasks + +### 安装构建的扩展 + +要安装你构建的扩展： + +```bash +code --install-extension "$(ls -1v bin/kilo-code-*.vsix | tail -n1)" +``` + +将 `[version]` 替换为当前版本号。 + +## 测试 + +Kilo Code 使用多种测试来确保质量： + +### 单元测试 + +运行单元测试： + +```bash +npm test +``` + +这将运行扩展和 Webview 测试。 + +要运行特定测试套件： + +```bash +npm run test:extension # 仅运行扩展测试 +npm run test:webview # 仅运行 Webview 测试 +``` + +### 端到端测试 + +E2E 测试验证扩展在 VSCode 中是否正确工作： + +1. 在根目录下创建 `.env.local` 文件，包含所需的 API 密钥： + + ``` + OPENROUTER_API_KEY=sk-or-v1-... + ``` + +2. 运行集成测试： + ```bash + npm run test:integration + ``` + +有关 E2E 测试的更多详细信息，请参阅 [e2e/VSCODE_INTEGRATION_TESTS.md](https://github.com/Kilo-Org/kilocode/blob/main/e2e/VSCODE_INTEGRATION_TESTS.md)。 + +## 代码检查和类型检查 + +确保你的代码符合我们的质量标准： + +```bash +npm run lint # 运行 ESLint +npm run check-types # 运行 TypeScript 类型检查 +``` + +## Git 钩子 + +该项目使用 [Husky](https://typicode.github.io/husky/) 来管理 Git 钩子，这些钩子会在提交和推送之前自动执行某些检查。钩子位于 `.husky/` 目录中。 + +### 预提交钩子 + +在提交完成之前，`.husky/pre-commit` 钩子会运行： + +1. **分支检查**：防止直接提交到 `main` 分支。 +2. **类型生成**：运行 `npm run generate-types`。 +3. **类型文件检查**：确保类型生成对 `src/exports/roo-code.d.ts` 的更改已暂存。 +4. **代码检查**：运行 `lint-staged` 以检查和格式化暂存的文件。 + +### 预推送钩子 + +在将更改推送到远程仓库之前，`.husky/pre-push` 钩子会运行： + +1. **分支检查**：防止直接推送到 `main` 分支。 +2. **编译**：运行 `npm run compile` 以确保项目成功构建。 +3. **变更集检查**：检查 `.changeset/` 中是否存在变更集文件，并提醒你使用 `npm run changeset` 创建一个。 + +这些钩子有助于保持代码质量和一致性。如果遇到提交或推送问题，请检查这些钩子的输出以获取错误信息。 + +## 故障排除 + +### 常见问题 + +1. **扩展未加载**：检查 VSCode 开发者工具（Help > Toggle Developer Tools）中的错误 +2. **Webview 未更新**：尝试重新加载窗口（Developer: Reload Window） +3. **构建错误**：确保所有依赖项都已通过 `npm run install:all` 安装 + +### 调试技巧 + +- 在代码中使用 `console.log()` 语句进行调试 +- 检查 VSCode 中的输出面板（View > Output）并从下拉菜单中选择 "Kilo Code" +- 对于 Webview 问题，请在 Webview 中使用浏览器开发者工具（右键点击 > "Inspect Element"） \ No newline at end of file diff --git a/docs/zh-CN/faq.md b/docs/zh-CN/faq.md new file mode 100644 index 0000000..43cd85c --- /dev/null +++ b/docs/zh-CN/faq.md @@ -0,0 +1,181 @@ +--- +--- + +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +export const FreeTierAmount = () => { + const {siteConfig} = useDocusaurusContext(); + return siteConfig.customFields.freeTierAmount; +}; + +# 常见问题解答 + +本页面解答关于Kilo Code的一些常见问题。 + +## 一般问题 + +### 什么是Kilo Code？ + +Kilo Code是一个开源的Visual Studio Code扩展，它通过生成代码、自动化任务和提供建议来帮助你更高效地编写代码。 + +### Kilo Code如何工作？ + +Kilo Code使用大型语言模型（LLMs）来理解你的请求并将其转化为行动。它可以： + +* 读取和写入项目中的文件 +* 在VS Code终端中执行命令 +* 进行网页浏览（如果启用） +* 通过模型上下文协议（MCP）使用外部工具 + +你通过聊天界面与Kilo Code交互，在其中提供指令并审查/批准其提出的操作。 + +### Kilo Code能做什么？ + +Kilo Code可以帮助完成各种编码任务，包括： + +* 根据自然语言描述生成代码 +* 重构现有代码 +* 修复bug +* 编写文档 +* 解释代码 +* 回答有关代码库的问题 +* 自动化重复性任务 +* 创建新文件和项目 + +### Kilo Code是免费的吗？ + +Kilo Code扩展本身是免费开源的。此外，Kilo Code提供免费层级，包含的Claude 3.7 Sonnet tokens。如果你的反馈有用，我们还会赠送更多免费tokens。 + +之后，你可以添加信用卡购买更多tokens（通过Stripe安全处理）。我们的定价与Anthropic的API费率完全一致。我们不会从每个token或每次充值中抽取任何费用。未来我们将添加更多LLM提供商。 + +或者，你可以"自带API"（如[Anthropic](providers/anthropic)、[OpenAI](providers/openai)、[OpenRouter](providers/openrouter)、[Requesty](providers/requesty)等）来使用其AI功能。这些提供商通常根据处理的tokens数量收取API使用费用。你需要创建账户并从所选提供商处获取API密钥。详情请参见[设置首个AI提供商](getting-started/connecting-api-provider)。 + +### 使用Kilo Code有哪些风险？ + +Kilo Code是一个强大的工具，使用时需要负责任。以下是一些需要注意的事项： + +* **Kilo Code可能会出错。** 在批准Kilo Code的更改之前，请仔细审查。 +* **Kilo Code可以执行命令。** 在允许Kilo Code运行命令时要非常谨慎，尤其是在使用自动批准时。 +* **Kilo Code可以访问互联网。** 如果你使用的提供商支持网页浏览，请注意Kilo Code可能会访问敏感信息。 + +## 设置与安装 + +### 如何安装Kilo Code？ + +请参阅[安装指南](/getting-started/installing)获取详细说明。 + +### 支持哪些API提供商？ + +Kilo Code支持多种API提供商，包括： +* [Anthropic (Claude)](/providers/kilocode) +* [Anthropic (Claude)](/providers/anthropic) +* [OpenAI](/providers/openai) +* [OpenRouter](/providers/openrouter) +* [Google Gemini](/providers/gemini) +* [Glama](/providers/glama) +* [AWS Bedrock](/providers/bedrock) +* [GCP Vertex AI](/providers/vertex) +* [Ollama](/providers/ollama) +* [LM Studio](/providers/lmstudio) +* [DeepSeek](/providers/deepseek) +* [Mistral](/providers/mistral) +* [Unbound](/providers/unbound) +* [Requesty](/providers/requesty) +* [VS Code Language Model API](/providers/vscode-lm) + +### 如何获取API密钥？ + +每个API提供商都有自己的API密钥获取流程。请参阅[设置首个AI提供商](/getting-started/connecting-api-provider)获取各提供商的相关文档链接。 + +### 可以使用本地模型吗？ + +是的，Kilo Code支持使用[Ollama](/providers/ollama)和[LM Studio](/providers/lmstudio)运行本地模型。请参阅[使用本地模型](/advanced-usage/local-models)获取说明。 + +## 使用 + +### 如何开始新任务？ + +打开Kilo Code面板（）并在聊天框中输入你的任务。请清晰具体地描述你希望Kilo Code完成的工作。请参阅[输入你的请求](/basic-usage/typing-your-requests)获取最佳实践。 + +### Kilo Code有哪些模式？ + +[模式](/basic-usage/using-modes)是Kilo Code可以采用的不同的角色，每个角色都有特定的关注点和能力。内置模式包括： + +* **Code模式：** 用于通用编码任务 +* **Architect模式：** 用于规划和技术领导 +* **Ask模式：** 用于回答问题并提供信息 +* **Debug模式：** 用于系统化问题诊断 +你还可以创建[自定义模式](/features/custom-modes)。 + +### 如何在模式之间切换？ + +使用聊天输入区域的下拉菜单选择不同的模式，或者使用`/`命令切换到特定模式。 + +### 什么是工具，如何使用它们？ + +[工具](/basic-usage/how-tools-work)是Kilo Code与你的系统交互的方式。Kilo Code会自动选择并使用适当的工具来完成你的任务。你不需要直接调用工具。每次使用工具时，你都会被提示批准或拒绝。 + +### 什么是上下文提及？ + +[上下文提及](/basic-usage/context-mentions)是一种为Kilo Code提供项目特定信息的方式，例如文件、文件夹或问题。使用"@"符号后跟你想要提及的项目（例如`@/src/file.ts`，`@problems`）。 + +### Kilo Code可以访问互联网吗？ + +是的，如果你使用的提供商支持模型进行网页浏览。请注意允许此功能的安全隐患。 + +### Kilo Code可以在我的终端中运行命令吗？ + +是的，Kilo Code可以在你的VS Code终端中执行命令。除非你启用了命令的自动批准，否则在执行每个命令之前，你都会被提示批准。在自动批准命令时要格外小心。如果你在终端命令上遇到问题，请参阅[Shell集成指南](/features/shell-integration)进行故障排除。 + +### 如何向Kilo Code提供反馈？ + +你可以通过批准或拒绝Kilo Code的提议操作来提供反馈。你还可以使用反馈字段提供额外的反馈。 + +### 可以自定义Kilo Code的行为吗？ + +是的，你可以通过多种方式自定义Kilo Code： + +* **自定义指令：** 提供适用于所有模式的通用指令，或特定模式的指令 +* **自定义模式：** 创建具有定制提示和工具权限的自定义模式 +* **`.clinerules`文件：** 在项目中创建`.clinerules`文件以提供额外的指导 +* **设置：** 调整各种设置，如自动批准、差异编辑等 + +### Kilo Code有自动批准设置吗？ + +是的，Kilo Code有一些设置，启用后会自动批准操作。了解更多[这里](/features/auto-approving-actions)。 + +## 高级功能 + +### 可以离线使用Kilo Code吗？ + +是的，如果你使用[本地模型](/advanced-usage/local-models)。 + +### 什么是MCP（模型上下文协议）？ + +[MCP](/features/mcp/overview)是一种协议，允许Kilo Code与外部服务器通信，通过自定义工具和资源扩展其能力。 + +### 可以创建自己的MCP服务器吗？ + +是的，你可以创建自己的MCP服务器来为Kilo Code添加自定义功能。详情请参阅[MCP文档](https://github.com/modelcontextprotocol)。 + +## 故障排除 + +### Kilo Code没有响应。我该怎么办？ + +* 确保你的API密钥正确且未过期 +* 检查你的互联网连接 +* 检查你选择的API提供商的状态 +* 尝试重启VS Code +* 如果问题仍然存在，请在[GitHub](https://github.com/Kilo-Org/kilocode/issues)或[Discord](https://kilocode.ai/discord)上报告问题 + +### 我看到错误消息。这是什么意思？ + +错误消息应该会提供一些关于问题的信息。如果你不确定如何解决，请在社区论坛中寻求帮助。 + +### Kilo Code做了我不想要的更改。如何撤销？ + +Kilo Code使用VS Code内置的文件编辑功能。你可以使用标准的"撤销"命令（Ctrl/Cmd + Z）来还原更改。此外，如果启用了实验性检查点，Kilo可以还原对文件所做的更改。 + +### 如何报告bug或建议功能？ + +请在Kilo Code的[问题页面](https://github.com/Kilo-Org/kilocode/issues)和[功能请求页面](https://github.com/Kilo-Org/kilocode/discussions/categories/ideas)上报告bug或建议功能。 \ No newline at end of file diff --git a/docs/zh-CN/features/api-configuration-profiles.md b/docs/zh-CN/features/api-configuration-profiles.md new file mode 100644 index 0000000..872e3e1 --- /dev/null +++ b/docs/zh-CN/features/api-configuration-profiles.md @@ -0,0 +1,92 @@ +# API 配置档案 + +API 配置档案允许你创建和切换不同的 AI 设置集合。每个档案可以为每个模式配置不同的设置，让你根据任务优化使用体验。 + +:::info +拥有多个配置档案可以让你快速在不同 AI 提供商、模型和设置之间切换，而无需每次更改设置时重新配置所有内容。 +::: + +## 工作原理 + +配置档案可以包含以下内容： +- API 提供商（OpenAI、Anthropic、OpenRouter、Glama 等） +- API 密钥和认证信息 +- 模型选择（o3-mini-high、Claude 3.7 Sonnet、DeepSeek R1 等） +- [温度设置](/features/model-temperature)，用于控制响应随机性 +- 思考预算 +- 提供商特定设置 + +请注意，可用设置因提供商和模型而异。每个提供商提供不同的配置选项，即使在同一提供商中，不同模型也可能支持不同的参数范围或功能。 + +## 创建和管理档案 + +### 创建档案 + +1. 打开设置，点击齿轮图标 → 提供商 +2. 点击档案选择器旁边的 "+" 按钮 + + 带有加号按钮的档案选择器 +3. 输入新档案的名称 + + 创建新档案对话框 +4. 配置档案设置： + - 选择你的 API 提供商 + + 提供商选择下拉菜单 + - 输入 API 密钥 + + API 密钥输入字段 + - 选择模型 + + 模型选择界面 + - 调整模型参数 + + 模型参数调整控件 + +### 切换档案 + +切换档案的两种方式： +1. 从设置面板：从下拉菜单中选择不同的档案 + + 设置中的档案选择下拉菜单 +2. 在聊天过程中：访问聊天界面中的 API 配置下拉菜单 + + 聊天界面中的 API 配置下拉菜单 + +### 固定和排序档案 + +API 配置下拉菜单现在支持固定常用档案以便快速访问： + +1. 将鼠标悬停在下拉菜单中的任何档案上以显示固定图标 +2. 点击固定图标将档案添加到固定列表 +3. 固定的档案将按字母顺序显示在下拉菜单的顶部 +4. 未固定的档案将显示在分隔符下方，同样按字母顺序排序 +5. 你可以再次点击该图标取消固定档案 + +固定 API 配置档案 + +此功能使你更容易在常用配置之间切换，特别是在你拥有许多配置时。 + +### 编辑和删除档案 + +档案编辑界面 +- 在设置中选择档案以修改任何设置 +- 点击铅笔图标重命名档案 +- 点击垃圾桶图标删除档案（不能删除最后一个档案） + +## 将档案与模式关联 + +在 提示标签中，你可以显式地将特定配置档案与每个模式关联。系统还会自动记住你上次与每个模式一起使用的档案，从而提高工作效率。 + +提示标签中的档案-模式关联界面 + +## 安全提示 + +API 密钥安全地存储在 VSCode 的 Secret Storage 中，永远不会以明文形式暴露。 + +## 相关功能 + +- 与你创建的[自定义模式](/features/custom-modes)配合使用 +- 集成[本地模型](/advanced-usage/local-models)以进行离线工作 +- 支持每个模式的[温度设置](/features/model-temperature) +- 通过[速率限制和使用跟踪](/advanced-usage/rate-limits-costs)增强成本管理 \ No newline at end of file diff --git a/docs/zh-CN/features/auto-approving-actions copy.md b/docs/zh-CN/features/auto-approving-actions copy.md new file mode 100644 index 0000000..cdc395f --- /dev/null +++ b/docs/zh-CN/features/auto-approving-actions copy.md @@ -0,0 +1,34 @@ +# 自动批准操作 + +本文档描述了如何在 Kilo Code 中配置和使用自动批准操作功能。自动批准操作允许用户在特定条件下自动批准某些操作，而无需手动确认。 + +## 启用自动批准操作 + +要启用自动批准操作，请按照以下步骤操作： + +1. 打开 Kilo Code 设置。 +2. 导航到“自动批准”部分。 +3. 启用“自动批准操作”选项。 +4. 配置你希望自动批准的操作类型和条件。 + +## 配置条件 + +你可以配置以下条件来自动批准操作： + +- **操作类型**：选择要自动批准的操作类型（例如，文件修改、命令执行等）。 +- **触发条件**：设置触发自动批准的条件（例如，特定文件路径、命令模式等）。 +- **批准范围**：定义自动批准的范围（例如，当前会话、所有会话等）。 + +## 注意事项 + +- 自动批准操作可能会影响系统的安全性，请谨慎使用。 +- 建议在启用自动批准操作之前，仔细审查配置的条件和范围。 +- 定期检查自动批准操作的日志，确保其按预期工作。 + +## 故障排除 + +如果你遇到自动批准操作无法正常工作的问题，请尝试以下步骤： + +1. 检查设置是否正确配置。 +2. 查看日志文件以获取更多信息。 +3. 如果问题仍然存在，请联系技术支持。 \ No newline at end of file diff --git a/docs/zh-CN/features/auto-approving-actions.md b/docs/zh-CN/features/auto-approving-actions.md new file mode 100644 index 0000000..9f1b286 --- /dev/null +++ b/docs/zh-CN/features/auto-approving-actions.md @@ -0,0 +1,224 @@ +# 自动批准操作 + +> ⚠️ **安全警告：** 自动批准设置会绕过确认提示，使 Kilo Code 可以直接访问你的系统。这可能导致**数据丢失、文件损坏或其他更严重的后果**。命令行访问尤其危险，因为它可能执行有害操作，损害你的系统或危及安全性。仅对你完全信任的操作启用自动批准。 + +自动批准设置通过消除重复的确认提示来加快你的工作流程，但会显著增加安全风险。 + +## 快速入门指南 + +1. 点击聊天输入框上方的“自动批准工具栏” +2. 选择 Kilo Code 可以无需许可执行的操作 +3. 使用主开关（最左侧的复选框）快速启用/禁用所有权限 + +## 自动批准工具栏 + +自动批准工具栏折叠状态 + +*提示框和自动批准工具栏，显示已启用的权限* + +点击工具栏以展开并配置各个权限： + +自动批准工具栏展开状态 + +*提示文本框和展开的工具栏，显示所有选项* + +### 可用权限 + +| 权限 | 功能 | 风险等级 | +|------------|--------------|------------| +| **读取文件和目录** | 允许 Kilo Code 无需询问即可访问文件 | 中 | +| **编辑文件** | 允许 Kilo Code 无需询问即可修改文件 | **高** | +| **执行已批准的命令** | 自动运行白名单中的终端命令 | **高** | +| **使用浏览器** | 允许无头浏览器交互 | 中 | +| **使用 MCP 服务器** | 允许 Kilo Code 使用配置的 MCP 服务 | 中高 | +| **切换模式** | 自动在 Kilo Code 模式之间切换 | 低 | +| **创建和完成任务** | 无需确认即可管理子任务 | 低 | +| **重试失败的请求** | 自动重试失败的 API 请求 | 低 | + +## 主开关快速控制 + +最左侧的复选框作为主开关： + +自动批准工具栏中的主开关 + +*主开关（复选框）可一次性控制所有自动批准权限* + +在以下情况下使用主开关： +- 处理敏感代码时（关闭） +- 进行快速开发时（开启） +- 在探索和编辑任务之间切换时 + +## 高级设置面板 + +设置面板提供了详细的控制和重要的安全上下文： + +> **允许 Kilo Code 自动执行操作而无需批准。仅在你完全信任 AI 并了解相关安全风险时启用这些设置。** + +要访问这些设置： + +1. 点击右上角的 +2. 导航到“自动批准设置” + +设置面板中的自动批准选项 + +*完整设置面板视图* + +### 读取操作 + +:::caution 读取操作 +只读操作设置 + +**设置：**“始终批准只读操作” + +**描述：**“启用后，Kilo Code 将自动查看目录内容并读取文件，而无需你点击批准按钮。” + +**风险等级：**中 + +虽然此设置仅允许读取文件（不允许修改），但它可能会暴露敏感数据。对于大多数用户来说，仍建议作为起点，但要注意 Kilo Code 可以访问哪些文件。 +::: + +### 写入操作 + +:::caution 写入操作 +写入操作设置，带有延迟滑块 + +**设置：**“始终批准写入操作” + +**描述：**“自动创建和编辑文件而无需批准” + +**延迟滑块：**“写入后的延迟时间，以便诊断工具检测潜在问题”（默认：1000ms） + +**风险等级：**高 + +此设置允许 Kilo Code 无需确认即可修改你的文件。延迟计时器至关重要： +- 较高的值（2000ms+）：适用于诊断时间较长的复杂项目 +- 默认值（1000ms）：适用于大多数项目 +- 较低的值：仅在速度至关重要且处于受控环境中时使用 +- 零：无诊断延迟（不建议用于关键代码） + +#### 写入延迟与问题面板集成 + +VSCode 问题面板显示诊断信息 + +*VSCode 问题面板，Kilo Code 在写入延迟期间检查该面板* + +当你启用写文件的自动批准时，延迟计时器会与 VSCode 的问题面板配合使用： + +1. Kilo Code 更改你的文件 +2. VSCode 的诊断工具分析更改 +3. 问题面板更新，显示任何错误或警告 +4. Kilo Code 在继续之前注意到这些问题 + +这类似于开发人员在更改代码后暂停检查错误。你可以根据以下因素调整延迟时间： + +- 项目复杂性 +- 语言服务器速度 +- 错误检测对你工作流程的重要性 +::: + +### 浏览器操作 + +:::info 浏览器操作 +浏览器操作设置 + +**设置：**“始终批准浏览器操作” + +**描述：**“自动执行浏览器操作而无需批准” + +**注意：**“仅当模型支持计算机使用时适用” + +**风险等级：**中 + +允许 Kilo Code 无需确认即可控制无头浏览器。这包括： +- 打开网站 +- 导航页面 +- 与网页元素交互 + +考虑允许自动浏览器访问的安全影响。 +::: + +### API 请求 + +:::info API 请求 +API 请求重试设置，带有延迟滑块 + +**设置：**“始终重试失败的 API 请求” + +**描述：**“当服务器返回错误响应时，自动重试失败的 API 请求” + +**延迟滑块：**“重试请求前的延迟时间”（默认：5s） + +**风险等级：**低 + +此设置在 API 调用失败时自动重试。延迟控制 Kilo Code 在重试前的等待时间： +- 较长的延迟对 API 速率限制更友好 +- 较短的延迟可以更快地从临时错误中恢复 +::: + +### MCP 工具 + +:::caution MCP 工具 +MCP 工具设置 + +**设置：**“始终批准 MCP 工具” + +**描述：**“在 MCP 服务器视图中启用各个 MCP 工具的自动批准（需同时启用此设置和工具的‘始终允许’复选框）” + +**风险等级：**中高（取决于配置的 MCP 工具） + +此设置与 MCP 服务器视图中的各个工具权限配合使用。必须同时启用此全局设置和工具特定权限才能实现自动批准。 +::: + +### 模式切换 + +:::info 模式切换 +模式切换设置 + +**设置：**“始终批准模式切换” + +**描述：**“自动在不同模式之间切换而无需批准” + +**风险等级：**低 + +允许 Kilo Code 无需许可即可在不同模式（代码、架构师等）之间切换。这主要影响 AI 的行为，而不是系统访问。 +::: + +### 子任务 + +:::info 子任务 +子任务设置 + +**设置：**“始终批准子任务的创建和完成” + +**描述：**“允许创建和完成子任务而无需批准” + +**风险等级：**低 + +允许 Kilo Code 自动创建和完成子任务。这涉及工作流程组织而非系统访问。 +::: + +### 命令执行 + +:::caution 命令执行 +命令执行设置，带有白名单界面 + +**设置：**“始终批准允许的执行操作” + +**描述：**“自动执行允许的终端命令而无需批准” + +**命令管理：**“当启用‘始终批准执行操作’时，可以自动执行的命令前缀。添加 * 以允许所有命令（请谨慎使用）。” + +**风险等级：**高 + +此设置允许终端命令执行并带有控制。虽然风险较高，但白名单功能限制了可以运行的命令。重要的安全功能： + +- 白名单特定的命令前缀（推荐） +- 切勿在生产环境或处理敏感数据时使用 * 通配符 +- 考虑每个允许命令的安全影响 +- 始终验证与外部系统交互的命令 + +**界面元素：** +- 输入命令前缀的文本字段（例如 'git'） +- 添加新前缀的“添加”按钮 +- 带 X 的可点击命令按钮以删除它们 +::: \ No newline at end of file diff --git a/docs/zh-CN/features/browser-use.md b/docs/zh-CN/features/browser-use.md new file mode 100644 index 0000000..d0c9b54 --- /dev/null +++ b/docs/zh-CN/features/browser-use.md @@ -0,0 +1,170 @@ +# 浏览器使用 + +Kilo Code 提供了先进的浏览器自动化功能，让你可以直接在 VS Code 中与网站进行交互。该功能使你无需离开开发环境即可测试 Web 应用程序、自动化浏览器任务并捕获屏幕截图。 + + + +:::info 模型支持要求 +Kilo Code 中的浏览器功能需要使用 Claude Sonnet 3.5 或 3.7 模型 +::: + +## 浏览器功能的工作原理 + +默认情况下，Kilo Code 使用内置浏览器，该浏览器： +- 当你要求 Kilo 访问网站时会自动启动 +- 捕获网页截图 +- 允许 Kilo 与网页元素交互 +- 在后台隐形运行 + +所有这些操作都在 VS Code 中直接完成，无需任何设置。 + +## 使用浏览器功能 + +典型的浏览器交互遵循以下模式： + +1. 让 Kilo 访问一个网站 +2. Kilo 启动浏览器并显示截图 +3. 请求其他操作（点击、输入、滚动） +4. Kilo 在完成后关闭浏览器 + +例如： + +``` +打开浏览器并查看我们的网站。 +``` + +``` +你能检查一下我在 https://kilocode.ai 的网站是否显示正确吗？ +``` + +``` +浏览 http://localhost:3000，向下滚动到页面底部并检查页脚信息是否显示正确。 +``` + +浏览器使用示例 + +## 浏览器操作的工作原理 + +`browser_action` 工具控制一个浏览器实例，在每次操作后返回截图和控制台日志，让你可以看到交互结果。 + +关键特性： +- 每个浏览器会话必须以 `launch` 开始，以 `close` 结束 +- 每条消息只能使用一个浏览器操作 +- 当浏览器处于活动状态时，不能使用其他工具 +- 在执行下一个操作之前，必须等待响应（截图和日志） + +### 可用的浏览器操作 + +| 操作 | 描述 | 使用场景 | +|--------|-------------|------------| +| `launch` | 在 URL 处打开浏览器 | 开始新的浏览器会话 | +| `click` | 在特定坐标处点击 | 与按钮、链接等交互 | +| `type` | 在活动元素中输入文本 | 填写表单、搜索框 | +| `scroll_down` | 向下滚动一页 | 查看折叠内容 | +| `scroll_up` | 向上滚动一页 | 返回之前的内容 | +| `close` | 关闭浏览器 | 结束浏览器会话 | + +## 浏览器功能配置/设置 + +:::info 默认浏览器设置 +- **启用浏览器工具**：已启用 +- **视口大小**：小桌面 (900x600) +- **截图质量**：75% +- **使用远程浏览器连接**：已禁用 +::: + +### 访问设置 + +要更改 Kilo 中的浏览器/电脑使用设置： + +1. 点击齿轮图标 → 浏览器/电脑使用 打开设置 + + 浏览器设置菜单 + +### 启用/禁用浏览器功能 + +**用途**：主开关，启用 Kilo 使用 Puppeteer 控制的浏览器与网站交互。 + +要更改此设置： +1. 在浏览器/电脑使用设置中勾选或取消勾选 "启用浏览器工具" 复选框 + + 启用浏览器工具设置 + +### 视口大小 + +**用途**：确定 Kilo Code 使用的浏览器会话的分辨率。 + +**权衡**：更高的值提供更大的视口，但会增加 token 使用量。 + +要更改此设置： +1. 在浏览器/电脑使用设置中点击 "视口大小" 下的下拉菜单 +2. 选择以下选项之一： + - 大桌面 (1280x800) + - 小桌面 (900x600) - 默认 + - 平板 (768x1024) + - 手机 (360x640) +2. 选择所需分辨率。 + + 视口大小设置 + +### 截图质量 + +**用途**：控制浏览器截图的 WebP 压缩质量。 + +**权衡**：更高的值提供更清晰的截图，但会增加 token 使用量。 + +要更改此设置： +1. 在浏览器/电脑使用设置中调整 "截图质量" 下的滑块 +2. 设置 1-100% 之间的值（默认为 75%） +3. 更高的值提供更清晰的截图，但会增加 token 使用量： + - 40-50%：适用于基本文本网站 + - 60-70%：适用于大多数一般浏览 + - 80%+：当需要精细视觉细节时使用 + + 截图质量设置 + +### 远程浏览器连接 + +**用途**：将 Kilo 连接到现有的 Chrome 浏览器，而不是使用内置浏览器。 + +**优点**： +- 适用于容器化环境和远程开发工作流 +- 在浏览器使用之间保持认证会话 +- 消除重复登录步骤 +- 允许使用具有特定扩展的自定义浏览器配置文件 + +**要求**：Chrome 必须启用远程调试。 + +要启用此功能： +1. 在浏览器/电脑使用设置中勾选 "使用远程浏览器连接" 框 +2. 点击 "测试连接" 进行验证 + + 远程浏览器连接设置 + +#### 常见用例 + +- **DevContainers**：从容器化的 VS Code 连接到主机 Chrome 浏览器 +- **远程开发**：使用本地 Chrome 与远程 VS Code 服务器 +- **自定义 Chrome 配置文件**：使用具有特定扩展和设置的配置文件 + +#### 连接到可见的 Chrome 窗口 + +连接到可见的 Chrome 窗口以实时观察 Kilo 的交互： + +**macOS** +```bash +/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --no-first-run +``` + +**Windows** +```bash +"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug --no-first-run +``` + +**Linux** +```bash +google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --no-first-run +``` \ No newline at end of file diff --git a/docs/zh-CN/features/checkpoints.md b/docs/zh-CN/features/checkpoints.md new file mode 100644 index 0000000..1165abe --- /dev/null +++ b/docs/zh-CN/features/checkpoints.md @@ -0,0 +1,236 @@ +# 检查点 + +检查点会在Kilo Code任务期间自动对你的工作区文件进行版本控制，使你能够安全地探索AI建议并轻松恢复不想要的更改。 + +检查点让你可以： +- 安全地尝试AI建议的更改 +- 轻松恢复不想要的修改 +- 比较不同的实现方法 +- 恢复到之前的项目状态而不会丢失工作 + +:::info 重要提示 +- **检查点默认启用。** +- **必须安装Git**才能使用检查点功能 - [查看安装说明](#git-installation) +- 不需要GitHub账号或仓库 +- 不需要配置Git个人信息 +- 影子Git仓库独立于你项目现有的Git配置 +::: + +## 配置选项 + +在Kilo Code设置的"检查点"部分可以配置检查点： + +1. 点击齿轮图标 → 检查点 打开设置 +2. 勾选或取消勾选"启用自动检查点"选项 + + Kilo Code配置中的检查点设置 + +## 检查点工作原理 + +Kilo Code使用一个独立于主版本控制系统的影子Git仓库来捕获项目状态的快照。这些快照称为检查点，会在AI辅助工作流中自动记录更改——无论是任务开始、文件更改还是命令运行时。 + +检查点作为提交存储在影子仓库中，记录： + +- 文件内容更改 +- 新增的文件 +- 删除的文件 +- 重命名的文件 +- 二进制文件的更改 + +## 使用检查点 + +检查点通过聊天界面直接集成到你的工作流中。 + +检查点在聊天历史记录中以两种形式出现： + +- **初始检查点**标记项目开始状态 + 聊天中的初始检查点指示器 + +- **常规检查点**在文件修改或命令执行后出现 + 聊天中的常规检查点指示器 + +每个检查点提供两个主要功能： + +### 查看差异 + +要比较当前工作区与之前的检查点： + +1. 在聊天历史记录中找到检查点 +2. 点击检查点的`查看差异`按钮 + + 查看差异按钮界面 + +3. 在比较视图中查看差异： + - 新增的行以绿色高亮显示 + - 删除的行以红色高亮显示 + - 修改的文件会列出详细更改 + - 重命名和移动的文件会跟踪路径更改 + - 新增或删除的文件会被明确标记 + +检查点的查看差异选项 + +### 恢复检查点 + +要将项目恢复到之前的检查点状态： + +1. 在聊天历史记录中找到检查点 +2. 点击检查点的`恢复检查点`按钮 + 恢复检查点按钮界面 +3. 选择以下恢复选项之一： + + 恢复检查点选项 + + - **仅恢复文件** - 仅将工作区文件恢复到检查点状态，不修改对话历史记录。适用于在保持聊天上下文的同时比较不同实现方案的理想选择。此选项不需要确认，可以快速在不同实现方案之间切换。 + + - **恢复文件和任务** - 恢复工作区文件并删除所有后续对话消息。当你想完全重置代码和对话到检查点的时间点时使用。此选项需要在对话框中确认，因为无法撤销。 + + 恢复检查点文件和任务的确认对话框 + +### 限制和注意事项 + +- **范围**：检查点仅捕获Kilo Code任务期间所做的更改 +- **外部更改**：在任务之外所做的修改（手动编辑、其他工具）不会被包含 +- **大文件**：非常大的二进制文件可能会影响性能 +- **未保存的工作**：恢复将覆盖工作区中任何未保存的更改 + +## 技术实现 + +### 检查点架构 + +检查点系统由以下部分组成： + +1. **影子Git仓库**：专门为检查点跟踪创建的独立Git仓库，作为检查点状态的持久存储机制。 + +2. **检查点服务**：通过以下方式处理Git操作和状态管理： + - 仓库初始化 + - 检查点创建和存储 + - 差异计算 + - 状态恢复 + +3. **UI组件**：显示在聊天界面中与检查点交互的界面元素。 + +### 恢复过程 + +当执行恢复时，Kilo Code： +- 硬重置到指定的检查点提交 +- 将影子仓库中的所有文件复制到工作区 +- 更新内部检查点跟踪状态 + +### 存储类型 + +检查点是任务范围的，意味着它们只针对单个任务。 + +### 差异计算 + +检查点比较使用Git的底层差异功能来生成结构化的文件差异： +- 修改的文件显示逐行更改 +- 二进制文件被正确检测和处理 +- 重命名和移动的文件被正确跟踪 +- 文件的创建和删除被明确标识 + +### 文件排除和忽略模式 + +检查点系统使用智能文件排除来跟踪相关文件： + +#### 内置排除 + +系统有全面的内置排除模式，自动忽略： +- 构建产物和依赖目录（`node_modules/`, `dist/`, `build/`） +- 媒体文件和二进制资源（图片、视频、音频） +- 缓存和临时文件（`.cache/`, `.tmp/`, `.bak`） +- 包含敏感信息的配置文件（`.env`） +- 大数据文件（归档文件、可执行文件、二进制文件） +- 数据库文件和日志 + +这些模式在初始化时被写入影子仓库的`.git/info/exclude`文件。 + +#### .gitignore支持 + +检查点系统尊重工作区中的`.gitignore`模式： +- 被`.gitignore`排除的文件不会触发检查点创建 +- 排除的文件不会出现在检查点差异中 +- 在暂存文件更改时应用标准Git忽略规则 + +#### .kilocodeignore行为 + +`.kilocodeignore`文件（控制AI对文件的访问）与检查点跟踪是分开的： +- 被`.kilocodeignore`排除但未被`.gitignore`排除的文件仍会被检查点跟踪 +- 对AI不可访问文件的更改仍可以通过检查点恢复 + +这种分离是故意的，因为`.kilocodeignore`限制的是AI可以访问的文件，而不是应该被跟踪进行版本历史记录的文件。 + +#### 嵌套Git仓库 + +检查点系统对嵌套Git仓库有特殊处理： +- 在操作期间将嵌套的`.git`目录临时重命名为`.git_disabled` +- 操作完成后恢复它们 +- 允许正确跟踪嵌套仓库中的文件 +- 确保嵌套仓库保持功能不受影响 + +### 并发控制 + +操作被排队以防止可能破坏仓库状态的并发Git操作。这确保了即使快速连续请求检查点操作也能安全完成。 + +## Git安装 + +检查点要求系统上安装Git。该实现使用`simple-git`库，它依赖Git命令行工具来创建和管理影子仓库。 + +### macOS + +1. **使用Homebrew安装（推荐）**： + ``` + brew install git + ``` + +2. **替代方案：使用Xcode命令行工具安装**： + ``` + xcode-select --install + ``` + +3. **验证安装**： + - 打开终端 + - 输入`git --version` + - 你应该看到类似`git version 2.40.0`的版本号 + +### Windows + +1. **下载Git for Windows**： + - 访问 https://git-scm.com/download/win + - 下载应该会自动开始 + +2. **运行安装程序**： + - 接受许可协议 + - 选择安装位置（推荐默认） + - 选择组件（通常默认选项足够） + - 选择默认编辑器 + - 选择如何使用Git命令行（推荐：Git from the command line and also from 3rd-party software） + - 配置行尾转换（推荐：Checkout Windows-style, commit Unix-style） + - 完成安装 + +3. **验证安装**： + - 打开命令提示符或PowerShell + - 输入`git --version` + - 你应该看到类似`git version 2.40.0.windows.1`的版本号 + +### Linux + +**Debian/Ubuntu**: +``` +sudo apt update +sudo apt install git +``` + +**Fedora**: +``` +sudo dnf install git +``` + +**Arch Linux**: +``` +sudo pacman -S git +``` + +**验证安装**： +- 打开终端 +- 输入`git --version` +- 你应该看到版本号 \ No newline at end of file diff --git a/docs/zh-CN/features/code-actions.md b/docs/zh-CN/features/code-actions.md new file mode 100644 index 0000000..6d5bc42 --- /dev/null +++ b/docs/zh-CN/features/code-actions.md @@ -0,0 +1,90 @@ +import Image from '@site/src/components/Image'; + +# 代码操作 + +代码操作是 VS Code 的一项强大功能，它可以直接在编辑器中提供快速修复、重构和其他代码相关建议。Kilo Code 与这一系统集成，为常见的编码任务提供 AI 驱动的辅助。 + +## 什么是代码操作？ + +代码操作以灯泡图标（💡）的形式出现在编辑器左侧的装订线（行号左侧的区域）中。它们也可以通过右键菜单或键盘快捷键访问。触发代码操作的情况包括： + +* 你选择了一段代码。 +* 你的光标位于有问题的行（错误、警告或提示）。 +* 你通过命令调用它们。 + +点击灯泡、右键选择“Kilo Code”或使用键盘快捷键（默认情况下，Windows/Linux 为 `Ctrl+.`，macOS 为 `Cmd+.`），会显示可用操作的菜单。 + +VS Code 代码操作 + +## Kilo Code 的代码操作 + +Kilo Code 提供以下代码操作： + +* **添加上下文：** 快速将选中的代码添加到与 Kilo 的聊天中，包括行号以便 Kilo 知道代码的确切位置。它位于菜单顶部以便快速访问。（详见下文）。 +* **解释代码：** 让 Kilo Code 解释选中的代码。 +* **修复代码：** 让 Kilo Code 修复选中代码中的问题（当存在诊断信息时可用）。 +* **改进代码：** 让 Kilo Code 建议对选中代码的改进。 + +### 添加上下文深入解析 + +**添加上下文** 操作位于代码操作菜单的顶部，以便你可以快速将代码片段添加到对话中。当你使用它时，Kilo Code 会包含文件名和行号以及代码。 + +这有助于 Kilo 理解代码在项目中的确切上下文，从而提供更相关和准确的帮助。 + +代码操作 - 添加上下文 + +**示例聊天输入：** + +``` +你能解释这个函数吗？ +@myFile.js:15:25 +``` + +*(其中 `@myFile.js:15:25` 表示通过“添加上下文”添加的代码)* + +每个操作都可以在“新任务”或“当前任务”中执行。 + +## 使用代码操作 + +使用 Kilo Code 代码操作的主要方式有三种： + +### 1. 通过灯泡图标（💡） + +1. **选择代码：** 选择你要处理的代码。你可以选择单行、多行或整个代码块。 +2. **寻找灯泡：** 灯泡图标会出现在选中代码（或有错误/警告的行）旁边的装订线中。 +3. **点击灯泡：** 点击灯泡图标以打开代码操作菜单。 +4. **选择一个操作：** 从菜单中选择所需的 Kilo Code 操作。 +5. **审查并批准：** Kilo Code 会在聊天面板中提出解决方案。审查提出的更改并批准或拒绝它们。 + +### 2. 通过右键菜单 + +1. **选择代码：** 选择你要处理的代码。 +2. **右键点击：** 右键点击选中的代码以打开上下文菜单。 +3. **选择“Kilo Code”：** 从上下文菜单中选择“Kilo Code”选项。将出现一个子菜单，显示可用的 Kilo Code 操作。 +4. **选择一个操作：** 从子菜单中选择所需的操作。 +5. **审查并批准：** Kilo Code 会在聊天面板中提出解决方案。审查提出的更改并批准或拒绝它们。 + +### 3. 通过命令面板 + +1. **选择代码：** 选择你要处理的代码。 +2. **打开命令面板：** 按 `Ctrl+Shift+P`（Windows/Linux）或 `Cmd+Shift+P`（macOS）。 +3. **输入命令：** 输入“Kilo Code”以过滤命令，然后选择相关的代码操作（例如，“Kilo Code: 解释代码”）。你也可以输入命令的开头，如“Kilo Code: 解释”，并从过滤列表中选择。 +4. **审查并批准：** Kilo Code 会在聊天面板中提出解决方案。审查提出的更改并批准或拒绝它们。 + +## 代码操作与当前任务 + +每个代码操作都提供两个选项： + +* **在新任务中：** 选择此项以开始一个围绕此代码操作的对话。 +* **在当前任务中：** 如果对话已经开始，此选项将代码操作作为附加消息添加到当前对话中。 + +## 自定义代码操作提示 + +你可以通过修改**提示**选项卡中的“支持提示”来自定义每个代码操作的提示。这允许你微调给 AI 模型的指令，并根据你的具体需求定制响应。 + +1. **打开提示选项卡：** 点击 Kilo Code 顶部菜单栏中的 图标。 +2. **找到“支持提示”：** 你会看到支持提示，包括“增强提示”、“解释代码”、“修复代码”和“改进代码”。 +3. **编辑提示：** 修改你要自定义的提示的文本区域。你可以使用占位符，如 `${filePath}` 和 `${selectedText}` 来包含当前文件和选择的信息。 +4. **点击“完成”：** 保存你的更改。 + +通过使用 Kilo Code 的代码操作，你可以直接在编码工作流程中快速获得 AI 驱动的辅助。这可以节省时间并帮助你编写更好的代码。 \ No newline at end of file diff --git a/docs/zh-CN/features/custom-modes.md b/docs/zh-CN/features/custom-modes.md new file mode 100644 index 0000000..06ec063 --- /dev/null +++ b/docs/zh-CN/features/custom-modes.md @@ -0,0 +1,285 @@ +# 自定义模式 + +Kilo Code允许你创建**自定义模式**来定制Kilo的行为以适应特定任务或工作流程。自定义模式可以是**全局的**（在所有项目中可用）或**项目特定的**（在单个项目中定义）。 + +## 为什么使用自定义模式？ + +* **专业化**：创建针对特定任务优化的模式，如"文档编写者"、"测试工程师"或"重构专家" +* **安全性**：限制模式对敏感文件或命令的访问。例如，"审查模式"可以限制为只读操作 +* **实验性**：安全地尝试不同的提示和配置，而不会影响其他模式 +* **团队协作**：与团队共享自定义模式以标准化工作流程 + +自定义模式界面概览 +*Kilo Code创建和管理自定义模式的界面* + +## 自定义模式包含什么？ + +自定义模式允许你定义： + +* **唯一名称和slug**：便于识别 +* **角色定义**：放置在系统提示的开头，定义Kilo在该模式下的核心专业知识和个性。这个位置至关重要，因为它塑造了Kilo对任务的基本理解和处理方法 +* **自定义指令**：添加到系统提示末尾，提供修改或优化Kilo行为的特定指南。与`.clinerules`文件（仅在末尾添加规则）不同，这种角色和指令的结构化放置允许更精细地控制Kilo的响应 +* **允许的工具**：该模式可以使用的Kilo Code工具（例如：读取文件、写入文件、执行命令） +* **文件限制**：（可选）将文件访问限制为特定文件类型或模式（例如：仅允许编辑`.md`文件） + +## 自定义模式配置（JSON格式） + +全局和项目特定配置使用相同的JSON格式。每个配置文件包含一个模式定义的`customModes`数组： + +```json +{ + "customModes": [ + { + "slug": "mode-name", + "name": "模式显示名称", + "roleDefinition": "模式的角色和能力", + "groups": ["read", "edit"], + "customInstructions": "附加指南" + } + ] +} +``` + +### 必需属性 + +#### `slug` +* 模式的唯一标识符 +* 使用小写字母、数字和连字符 +* 保持简短和描述性 +* 示例：`"docs-writer"`, `"test-engineer"` + +#### `name` +* 在UI中显示的名称 +* 可以包含空格和适当的大小写 +* 示例：`"文档编写者"`, `"测试工程师"` + +#### `roleDefinition` +* 模式角色和能力的详细描述 +* 定义Kilo在该模式下的专业知识和个性 +* 示例：`"你是一位专注于编写清晰文档的技术写作者"` + +#### `groups` +* 允许的工具组数组 +* 可用组：`"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"` +* 可以为`"edit"`组包含文件限制 + +##### 文件限制格式 +```json +["edit", { + "fileRegex": "\\.md$", + "description": "仅限Markdown文件" +}] +``` + +### 理解文件限制 + +`fileRegex`属性使用正则表达式来控制模式可以编辑哪些文件： + +* `\\.md$` - 匹配以".md"结尾的文件 +* `\\.(test|spec)\\.(js|ts)$` - 匹配测试文件（例如"component.test.js"） +* `\\.(js|ts)$` - 匹配JavaScript和TypeScript文件 + +常见正则表达式模式： +* `\\.` - 匹配字面量点 +* `(a|b)` - 匹配"a"或"b" +* `$` - 匹配文件名结尾 + +[了解更多关于正则表达式的知识](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) + +### 可选属性 + +#### `customInstructions` +* 模式的附加行为指南 +* 示例：`"专注于解释概念和提供示例"` + +#### `apiConfiguration` +* 自定义该模式的AI模型和参数的可选设置 +* 允许针对特定任务优化模型选择 +* 示例：`{"model": "gpt-4", "temperature": 0.2}` + +### 模式特定的自定义指令文件 + +除了JSON中的`customInstructions`属性外，你还可以使用专门的文件来存储模式特定的指令： + +1. 在工作区根目录创建名为`.clinerules-{mode-slug}`的文件 + * 将`{mode-slug}`替换为你的模式slug（例如`.clinerules-docs-writer`） +2. 将你的自定义指令添加到此文件 +3. Kilo Code会自动将这些指令应用于指定模式 + +这种方法特别适用于： +* 保持冗长的指令与模式配置分离 +* 使用版本控制管理指令 +* 允许非技术团队成员修改指令而无需编辑JSON + +注意：如果同时存在`.clinerules-{mode-slug}`和`customInstructions`属性，它们将被合并，文件内容会附加在JSON属性之后。 + +## 配置优先级 + +模式配置按以下顺序应用： + +1. 项目级模式配置（来自`.kilocodemodes`） +2. 全局模式配置（来自`custom_modes.json`） +3. 默认模式配置 + +这意味着项目特定的配置将覆盖全局配置，而全局配置又将覆盖默认配置。 + +## 创建自定义模式 + +你有三种创建自定义模式的选项： + +### 1. 询问Kilo!（推荐） + +你可以通过要求Kilo Code快速创建一个基本自定义模式。例如： +``` +创建一个名为"文档编写者"的新模式。它应该只能读取文件和编写Markdown文件。 +``` +Kilo Code将引导你完成整个过程。但是，对于微调模式或进行特定调整，你需要使用下面描述的"提示"标签页或手动配置方法。 + +:::info +#### 自定义模式创建设置 +启用后，Kilo允许你使用类似'Make me a custom mode that...'的提示创建自定义模式。禁用此功能可在不需要此功能时减少约700 tokens的系统提示。禁用时，你仍然可以使用上方的+按钮或编辑相关配置JSON手动创建自定义模式。 +启用通过提示创建自定义模式的设置 +你可以通过点击Kilo Code顶部菜单栏中的图标在提示设置中找到此设置。 +::: + +### 2. 使用提示标签页 + +1. **打开提示标签页**：点击Kilo Code顶部菜单栏中的图标 +2. **创建新模式**：点击模式标题右侧的按钮 +3. **填写字段**： + + 提示标签页中的自定义模式创建界面 + *显示名称、slug、保存位置、角色定义、可用工具和自定义指令字段的自定义模式创建界面* + + * **名称**：输入模式的显示名称 + * **Slug**：输入小写标识符（仅限字母、数字和连字符） + * **保存位置**：选择全局（通过`custom_modes.json`，在所有工作区可用）或项目特定（在项目根目录的`.kilocodemodes`文件中） + * **角色定义**：定义Kilo在该模式下的专业知识和个性（出现在系统提示的开头） + * **可用工具**：选择该模式可以使用的工具 + * **自定义指令**：（可选）添加该模式特定的行为指南（出现在系统提示的末尾） +4. **创建模式**：点击"创建模式"按钮保存你的新模式 + +注意：文件类型限制只能通过手动配置添加。 + +### 3. 手动配置 + +你可以通过编辑提示标签页中的JSON文件来配置自定义模式： + +全局和项目特定的配置都可以通过提示标签页编辑： + +1. **打开提示标签页**：点击Kilo Code顶部菜单栏中的图标 +2. **访问设置菜单**：点击模式标题右侧的按钮 +3. **选择配置**： + * 选择"编辑全局模式"来编辑`custom_modes.json`（在所有工作区可用） + * 选择"编辑项目模式"来编辑项目根目录中的`.kilocodemodes`文件 +4. **编辑配置**：修改打开的JSON文件 +5. **保存更改**：Kilo Code会自动检测更改 + +## 配置示例 + +每个示例展示模式配置的不同方面： + +### 基本文档编写者 +```json +{ + "customModes": [{ + "slug": "docs-writer", + "name": "文档编写者", + "roleDefinition": "你是一位专注于编写清晰文档的技术写作者", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.md$", "description": "仅限Markdown文件" }] + ], + "customInstructions": "专注于清晰的解释和示例" + }] +} +``` + +### 具有文件限制的测试工程师 +```json +{ + "customModes": [{ + "slug": "test-engineer", + "name": "测试工程师", + "roleDefinition": "你是一位专注于代码质量的测试工程师", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts)$", "description": "仅限测试文件" }] + ] + }] +} +``` + +### 项目特定的模式覆盖 +```json +{ + "customModes": [{ + "slug": "code", + "name": "代码（项目特定）", + "roleDefinition": "你是具有项目特定约束的软件工程师", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.(js|ts)$", "description": "仅限JS/TS文件" }] + ], + "customInstructions": "专注于项目特定的JS/TS开发" + }] +} +``` + +按照这些说明，你可以创建和管理自定义模式以增强与Kilo Code的工作流程。 + +## 理解自定义模式中的正则表达式 + +自定义模式中的正则表达式模式让你可以精确控制Kilo可以编辑哪些文件： + +### 基本语法 + +当你在自定义模式中指定`fileRegex`时，你创建了一个文件路径必须匹配的模式： + +```json +["edit", { "fileRegex": "\\.md$", "description": "仅限Markdown文件" }] +``` + +### 重要规则 + +- **双反斜杠**：在JSON中，反斜杠必须用另一个反斜杠转义。所以`\.md$`变成`\\.md$` +- **路径匹配**：模式匹配完整文件路径，而不仅仅是文件名 +- **大小写敏感**：正则表达式模式默认区分大小写 + +### 常见模式示例 + +| 模式 | 匹配 | 不匹配 | +|---------|---------|---------------| +| `\\.md$` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` | +| `^src/.*` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` | +| `\\.(css\|scss)$` | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` | +| `docs/.*\\.md$` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` | +| `^(?!.*(test\|spec)).*\\.js$` | `app.js`, `utils.js` | `app.test.js`, `utils.spec.js` | + +### 模式构建块 + +- `\\.` - 匹配字面量点（句号） +- `$` - 匹配字符串结尾 +- `^` - 匹配字符串开头 +- `.*` - 匹配任何字符（换行符除外）零次或多次 +- `(a|b)` - 匹配"a"或"b" +- `(?!...)` - 否定前瞻（排除匹配） + +### 测试你的模式 + +在将正则表达式模式应用于自定义模式之前： +1. 在示例文件路径上测试它以确保它匹配你期望的内容 +2. 记住在JSON中每个反斜杠都需要加倍（`\d`变成`\\d`） +3. 从更简单的模式开始，逐步增加复杂性 + +:::tip +### 让Kilo构建你的正则表达式模式 +与其手动编写复杂的正则表达式模式，你可以要求Kilo为你创建它们！只需描述你想要包含或排除哪些文件： +``` +创建一个匹配JavaScript文件但排除测试文件的正则表达式模式 +``` +Kilo将生成带有适当JSON转义的适当模式。 +::: + +## 社区画廊 +准备好探索更多？查看[Show and Tell](https://github.com/Kilo-Org/kilocode/discussions/categories/show-and-tell)来发现和分享社区创建的自定义模式！ \ No newline at end of file diff --git a/docs/zh-CN/features/enhance-prompt.md b/docs/zh-CN/features/enhance-prompt.md new file mode 100644 index 0000000..688c87a --- /dev/null +++ b/docs/zh-CN/features/enhance-prompt.md @@ -0,0 +1,54 @@ +# 增强提示 + +Kilo Code 中的“增强提示”功能可以帮助你在将提示发送给 AI 模型之前，提高提示的质量和有效性。通过点击聊天输入框中的 图标，你可以自动优化初始请求，使其更清晰、更具体，更有可能产生预期的结果。 + +## 为什么要使用增强提示？ + +* **提高清晰度：** Kilo Code 可以重新表述你的提示，使其对 AI 模型更易理解。 +* **添加上下文：** 增强过程可以为你的提示添加相关上下文，例如当前文件路径或选中的代码。 +* **更好的指令：** Kilo Code 可以添加指令，引导 AI 提供更有帮助的响应（例如，请求特定的格式或详细的说明）。 +* **减少歧义：** 增强提示有助于消除歧义，确保 Kilo Code 理解你的意图。 +* **一致性：** Kilo 会以相同的方式格式化提示，确保一致性。 + +### 使用前后对比 + +非常简单的提示 +增强后的提示 + +## 如何使用增强提示 + +1. **输入初始提示：** 像往常一样在 Kilo Code 聊天输入框中输入你的请求。这可以是一个简单的问题、复杂的任务描述或介于两者之间的任何内容。 +2. **点击 图标：** 不要按下 Enter 键，而是点击聊天输入框右下角的 图标。 +3. **查看增强后的提示：** Kilo Code 会将你的原始提示替换为增强后的版本。查看增强后的提示，确保它准确反映了你的意图。你可以在发送前进一步优化增强后的提示。 +4. **发送增强后的提示：** 按下 Enter 键或点击发送图标（）将增强后的提示发送给 Kilo Code。 + +## 自定义增强过程 + +### 自定义模板 + +“增强提示”功能使用可自定义的提示模板。你可以修改此模板，以根据你的特定需求定制增强过程。 + +1. **打开提示标签页：** 点击 Kilo Code 顶部菜单栏中的 图标。 +2. **选择“ENHANCE”标签：** 你应该会看到一个列出的支持提示列表，包括“ENHANCE”。点击此标签。 +3. **编辑提示模板：** 修改“Prompt”字段中的文本。 + +默认的提示模板包含占位符 `${userInput}`，它将被替换为你的原始提示。你可以修改此模板以适应模型的提示格式，并指示它如何增强你的请求。 + +### 自定义提供者 + +通过切换到更轻量级的 LLM 模型提供者（例如 GPT 4.1 Nano），可以加快提示增强的速度。这可以在保持质量的同时以更低的成本提供更快的响应。 + +按照 [API 配置配置文件指南](/features/api-configuration-profiles) 为增强提示创建专用配置文件。 + +增强提示功能的自定义配置文件配置 + +详细教程：https://youtu.be/R1nDnCK-xzw + +## 限制和最佳实践 + +* **实验性功能：** 提示增强是一个实验性功能。增强提示的质量可能会根据请求的复杂性和底层模型的能力而有所不同。 +* **仔细查看：** 在发送增强提示之前，请务必仔细查看。Kilo Code 可能会做出不符合你意图的更改。 +* **迭代过程：** 你可以多次使用“增强提示”功能来迭代优化你的提示。 +* **不能替代清晰的指令：** 虽然“增强提示”可以帮助你，但从一开始就编写清晰、具体的提示仍然很重要。 + +通过使用“增强提示”功能，你可以提高与 Kilo Code 的交互质量，并获得更准确、更有帮助的响应。 \ No newline at end of file diff --git a/docs/zh-CN/features/experimental/codebase-indexing.md b/docs/zh-CN/features/experimental/codebase-indexing.md new file mode 100644 index 0000000..03b1410 --- /dev/null +++ b/docs/zh-CN/features/experimental/codebase-indexing.md @@ -0,0 +1,205 @@ +import Codicon from '@site/src/components/Codicon'; + +# 代码库索引 + +**⚠️ 实验性功能：** 该功能正在积极开发中，可能在未来的版本中发生重大变化。 + +代码库索引功能使用 AI 嵌入实现对整个项目的语义代码搜索。它不局限于精确的文本匹配，而是理解查询的_含义_，帮助 Kilo Code 即使在你不知道具体函数名或文件位置的情况下也能找到相关代码。 + +代码库索引设置 + +## 功能概述 + +启用后，索引系统会： + +1. **解析代码**：使用 Tree-sitter 识别语义块（函数、类、方法） +2. **创建嵌入**：使用 AI 模型为每个代码块生成嵌入 +3. **存储向量**：将向量存储在 Qdrant 数据库中以便快速相似性搜索 +4. **提供 [`codebase_search`](/advanced-usage/available-tools/codebase-search) 工具**：为 Kilo Code 提供智能代码发现功能 + +这使得你可以使用自然语言查询，如“用户认证逻辑”或“数据库连接处理”，在整个项目中找到相关代码。 + +## 主要优势 + +- **语义搜索**：通过含义而非关键字查找代码 +- **增强的 AI 理解**：Kilo Code 能更好地理解和处理你的代码库 +- **跨项目发现**：搜索所有文件，而不仅仅是打开的文件 +- **模式识别**：定位相似的实现和代码模式 + +## 设置要求 + +### 嵌入提供者 + +选择以下选项之一来生成嵌入： + +**OpenAI（推荐）** + +- 需要 OpenAI API 密钥 +- 支持所有 OpenAI 嵌入模型 +- 默认：`text-embedding-3-small` +- 每批最多处理 100,000 个 token + +**Ollama（本地）** + +- 需要本地 Ollama 安装 +- 无需 API 费用或网络依赖 +- 支持任何与 Ollama 兼容的嵌入模型 +- 需要配置 Ollama 基础 URL + +### 向量数据库 + +**Qdrant** 是存储和搜索嵌入的必需组件： + +- **本地**：`http://localhost:6333`（推荐用于测试） +- **云端**：Qdrant Cloud 或自托管实例 +- **认证**：可选的 API 密钥，用于安全部署 + +## 设置 Qdrant + +### 快速本地设置 + +**使用 Docker：** + +```bash +docker run -p 6333:6333 qdrant/qdrant +``` + +**使用 Docker Compose：** + +```yaml +version: '3.8' +services: + qdrant: + image: qdrant/qdrant + ports: + - '6333:6333' + volumes: + - qdrant_storage:/qdrant/storage +volumes: + qdrant_storage: +``` + +### 生产部署 + +对于团队或生产环境： + +- [Qdrant Cloud](https://cloud.qdrant.io/) - 托管服务 +- 在 AWS、GCP 或 Azure 上自托管 +- 本地服务器并配置网络访问以支持团队共享 + +## 配置 + +1. 打开 Kilo Code 设置（ 图标） +2. 导航到 **实验性** 部分 +3. 启用 **“启用代码库索引”** +4. 配置嵌入提供者： + - **OpenAI**：输入 API 密钥并选择模型 + - **Ollama**：输入基础 URL 并选择模型 +5. 设置 Qdrant URL 和可选的 API 密钥 +6. 点击 **保存** 开始初始索引 + +## 理解索引状态 + +界面会显示实时状态，并用颜色标识： + +- **待机**（灰色）：未运行，等待配置 +- **索引中**（黄色）：正在处理文件 +- **已索引**（绿色）：最新且可进行搜索 +- **错误**（红色）：需要关注失败状态 + +## 文件处理方式 + +### 智能代码解析 + +- **Tree-sitter 集成**：使用 AST 解析识别语义代码块 +- **语言支持**：Tree-sitter 支持的所有语言 +- **回退**：对不支持的文件类型使用基于行的分块 +- **块大小**： + - 最小：100 字符 + - 最大：1,000 字符 + - 智能分割大型函数 + +### 自动文件过滤 + +索引器会自动排除： + +- 二进制文件和图像 +- 大文件（>1MB） +- Git 仓库（`.git` 文件夹） +- 依赖项（`node_modules`、`vendor` 等） +- 符合 `.gitignore` 和 `.kilocode` 模式的文件 + +### 增量更新 + +- **文件监控**：监视工作区的变化 +- **智能更新**：仅重新处理修改过的文件 +- **基于哈希的缓存**：避免重新处理未更改的内容 +- **分支切换**：自动处理 Git 分支变更 + +## 最佳实践 + +### 模型选择 + +**对于 OpenAI：** + +- **`text-embedding-3-small`**：性能与成本的最佳平衡 +- **`text-embedding-3-large`**：更高的准确性，成本增加 5 倍 +- **`text-embedding-ada-002`**：旧版模型，成本较低 + +**对于 Ollama：** + +- **`mxbai-embed-large`**：最大且最高质量的嵌入模型。 +- **`nomic-embed-text`**：性能与嵌入质量的最佳平衡。 +- **`all-minilm`**：紧凑模型，质量较低但性能更快。 + +### 安全考虑 + +- **API 密钥**：安全存储在 VS Code 的加密存储中 +- **代码隐私**：仅发送小段代码片段进行嵌入（非完整文件） +- **本地处理**：所有解析均在本地进行 +- **Qdrant 安全性**：生产部署时使用认证 + +## 当前限制 + +- **文件大小**：每个文件最大 1MB +- **Markdown**：由于解析复杂性，目前不支持 +- **单一工作区**：一次只能处理一个工作区 +- **依赖项**：需要外部服务（嵌入提供者 + Qdrant） +- **语言覆盖**：仅限于 Tree-sitter 支持的语言 + +## 使用搜索功能 + +索引完成后，Kilo Code 可以使用 [`codebase_search`](/advanced-usage/available-tools/codebase-search) 工具查找相关代码： + +**示例查询：** + +- “用户认证是如何处理的？” +- “数据库连接设置” +- “错误处理模式” +- “API 端点定义” + +该工具为 Kilo Code 提供： + +- 相关代码片段 +- 文件路径和行号 +- 相似度分数 +- 上下文信息 + +## 隐私与安全 + +- **代码保留在本地**：仅发送小段代码片段进行嵌入 +- **嵌入为数值**：非人类可读的表示 +- **安全存储**：API 密钥在 VS Code 存储中加密 +- **本地选项**：使用 Ollama 实现完全本地处理 +- **访问控制**：尊重现有文件权限 + +## 未来改进 + +计划中的改进包括： + +- 增加更多嵌入提供者 +- 改进 Markdown 和文档支持 +- 多工作区索引 +- 增强过滤和配置选项 +- 团队共享功能 +- 与 VS Code 原生搜索集成 \ No newline at end of file diff --git a/docs/zh-CN/features/experimental/experimental-features.md b/docs/zh-CN/features/experimental/experimental-features.md new file mode 100644 index 0000000..38ead34 --- /dev/null +++ b/docs/zh-CN/features/experimental/experimental-features.md @@ -0,0 +1,39 @@ +import Codicon from '@site/src/components/Codicon'; + +# 实验性功能 + +Kilo Code 包含一些仍在开发中的实验性功能。这些功能可能不稳定，会在未来版本中发生重大变化，甚至可能被移除。请谨慎使用，并注意它们可能无法按预期工作。 + +**警告：** 实验性功能可能存在意外行为，包括潜在的数据丢失或安全漏洞。启用这些功能需自行承担风险。 + +## 启用实验性功能 + +要启用或禁用实验性功能： + +1. 打开 Kilo Code 设置（右上角的 图标）。 +2. 进入“高级设置”部分。 +3. 找到“实验性功能”部分。 +4. 勾选或取消勾选要启用或禁用的功能。 +5. 点击“完成”保存更改。 + +## 当前可用的实验性功能 + +以下实验性功能目前可用： + +### 搜索和替换 + +添加了一个用于在文件中搜索和替换文本的新工具。 + +### 插入内容 + +添加了一个用于在文件中任意位置插入内容的新工具。 + +### 强力转向 + +启用后，Kilo Code 会更频繁地提醒模型当前的模式定义细节。这将导致更严格地遵守角色定义和自定义指令，但会消耗更多 token。 + +## 提供反馈 + +如果你在使用实验性功能时遇到任何问题，或有改进建议，请在 [Kilo Code Code GitHub Issues 页面](https://github.com/Kilo-Org/kilocode) 上报告。 + +你的反馈对我们非常宝贵，将帮助我们改进 Kilo Code！ \ No newline at end of file diff --git a/docs/zh-CN/features/fast-edits.md b/docs/zh-CN/features/fast-edits.md new file mode 100644 index 0000000..cfc6689 --- /dev/null +++ b/docs/zh-CN/features/fast-edits.md @@ -0,0 +1,34 @@ +# 快速编辑 + +:::info 默认设置 +在 Kilo Code 中，快速编辑（使用"通过差异启用编辑"设置）默认是启用的。除非遇到特定问题或想要尝试不同的差异策略，否则通常不需要更改这些设置。 +::: + +Kilo Code 提供了一个高级设置，可以更改它编辑文件的方式，使用差异（diff）而不是重写整个文件。启用此功能提供了显著的优势。 + +## 启用通过差异编辑 + +打开设置，点击齿轮图标 → 高级 + +当**启用通过差异编辑**被勾选时： + + Kilo Code 设置显示启用通过差异编辑 +1. **更快的文件编辑**：Kilo 通过仅应用必要的更改来更快地修改文件。 +2. **防止截断写入**：系统会自动检测并拒绝 AI 尝试写入不完整文件内容的情况，这可能发生在大型文件或复杂指令时。这有助于防止文件损坏。 + +:::note 禁用快速编辑 +如果取消勾选**启用通过差异编辑**，Kilo 将恢复为每次编辑时使用 [`write_to_file`](/features/tools/write-to-file) 工具写入整个文件内容，而不是使用 [`apply_diff`](/features/tools/apply-diff) 应用目标更改。这种全量写入的方法在修改现有文件时通常较慢，并且会导致更高的 token 使用量。 +::: + +## 匹配精度 + +此滑块控制 AI 识别的代码部分在应用更改之前必须与实际文件中的代码匹配的紧密程度。 + + Kilo Code 设置显示启用通过差异编辑复选框和匹配精度滑块 + +* **100%（默认）**：要求完全匹配。这是最安全的选项，最大限度地降低错误更改的风险。 +* **较低值（80%-99%）**：允许"模糊"匹配。即使代码部分与 AI 预期的内容有轻微差异，Kilo 也可以应用更改。这在文件被轻微修改时可能有用，但**会增加**在错误位置应用更改的风险。 + +**使用低于 100% 的值时要格外小心。** 较低精度可能偶尔是必要的，但始终要仔细审查提议的更改。 + +在内部，此设置会调整一个 `fuzzyMatchThreshold`，使用 Levenshtein 距离等算法来比较代码相似性。 \ No newline at end of file diff --git a/docs/zh-CN/features/footgun-prompting.md b/docs/zh-CN/features/footgun-prompting.md new file mode 100644 index 0000000..76109e4 --- /dev/null +++ b/docs/zh-CN/features/footgun-prompting.md @@ -0,0 +1,51 @@ +--- +sidebar_label: 'Footgun Prompting' +--- + +# Footgun Prompting：覆盖系统提示 + +Footgun Prompting，也称为覆盖系统提示，允许高级用户完全替换特定 Kilo Code 模式的默认系统提示。这提供了对 AI 行为的精细控制，但会绕过内置的安全机制。 + +:::info **footgun** *(名词)* + +1. *(编程俚语，幽默，贬义)* 任何可能导致程序员搬起石头砸自己脚的功能。 + +> 系统提示覆盖被称为 "footgun"，因为在不深入了解其核心指令的情况下修改它可能会导致意外或损坏的行为，特别是在工具使用和响应一致性方面。 + +::: + +## 工作原理 + +1. **覆盖文件：** 在项目根目录下创建一个名为 `.kilo/system-prompt-{mode-slug}` 的文件（例如，对于 Code 模式，文件名为 `.kilo/system-prompt-code`）。 +2. **内容：** 该文件的内容将成为该特定模式的新系统提示。 +3. **激活：** Kilo Code 会自动检测此文件。当文件存在时，它将替换大部分标准系统提示部分。 +4. **保留部分：** 只有核心的 `roleDefinition` 和你为该模式设置的 `customInstructions` 会与覆盖内容一起保留。标准部分如工具描述、规则和功能将被绕过。 +5. **构建：** 最终发送给模型的提示如下： + ``` + ${roleDefinition} + + ${content_of_your_override_file} + + ${customInstructions} + ``` + +## 访问该功能 + +你可以在 Kilo Code UI 中找到该功能和说明： + +1. 点击 Kilo Code 顶部菜单栏中的 图标。 +2. 展开 **"高级：覆盖系统提示"** 部分。 +3. 点击说明中的文件路径链接，将在 VS Code 中打开或创建当前所选模式的覆盖文件。 + +UI 显示高级：覆盖系统提示部分 + + +## 关键注意事项与警告 + +- **目标用户：** 最适合对 Kilo Code 提示系统和修改核心指令的影响有深入了解的用户。 +- **对功能的影响：** 自定义提示会覆盖标准指令，包括工具使用和响应一致性的指令。如果不小心处理，可能会导致意外行为或错误。 +- **模式特定：** 每个覆盖文件仅适用于文件名中指定的模式（`{mode-slug}`）。 +- **无文件，无覆盖：** 如果 `.kilo/system-prompt-{mode-slug}` 文件不存在，Kilo Code 将使用该模式的标准系统提示生成过程。 +- **目录创建：** Kilo Code 会在读取或创建覆盖文件之前确保 `.kilo` 目录存在。 + +请谨慎使用此功能。虽然它对于自定义非常强大，但错误的实现可能会显著降低 Kilo Code 在受影响模式下的性能和可靠性。 \ No newline at end of file diff --git a/docs/zh-CN/features/mcp/mcp-vs-api.md b/docs/zh-CN/features/mcp/mcp-vs-api.md new file mode 100644 index 0000000..0e4934c --- /dev/null +++ b/docs/zh-CN/features/mcp/mcp-vs-api.md @@ -0,0 +1,97 @@ +--- +title: MCP与API +sidebar_label: MCP与API +--- + +# MCP与REST API：根本区别 + +将REST API与模型上下文协议（MCP）进行比较是一种类别错误。它们在抽象的不同层次上运行，为AI系统提供根本不同的功能。 + +## 架构差异 + +| 特性 | MCP | REST API | +|---------|-----|-----------| +| 状态管理 | **有状态** - 在交互中维护上下文 | **无状态** - 每个请求都是独立的 | +| 连接类型 | 持久、双向连接 | 单向请求/响应 | +| 通信风格 | 基于JSON-RPC的持续会话 | 基于HTTP的离散请求 | +| 上下文处理 | 上下文是协议的内在部分 | 上下文必须手动管理 | +| 工具发现 | 运行时发现可用工具 | 设计时集成，需要预先了解 | +| 集成方式 | 运行时集成，动态能力 | 设计时集成，需要代码修改 | + +## 不同层次，不同目的 + +REST API和MCP服务于技术栈的不同层次： + +1. **REST**：暴露资源操作的低级Web通信模式 +2. **MCP**：编排工具使用和维护上下文的高级AI协议 + +MCP通常在内部使用REST API，但为AI抽象了它们。可以将MCP视为将离散的Web服务转变为AI可以操作的统一环境的中间件。 + +## 上下文保存：AI工作流程的关键 + +MCP的有状态设计解决了REST在AI应用中的关键限制： + +- **REST方法**：每个调用都是独立的，需要在步骤间手动传递上下文 +- **MCP方法**：一次对话上下文在多个工具使用中持续存在 + +例如，AI在调试代码库时可以打开文件、运行测试并识别错误，而不会在各步骤间丢失上下文。MCP会话会保持对先前操作和结果的感知。 + +## 动态工具发现 + +MCP使AI能够在运行时发现和使用工具： + +```json +// AI发现可用工具 +{ + "tools": [ + { + "name": "readFile", + "description": "从文件中读取内容", + "parameters": { + "path": { "type": "string", "description": "文件路径" } + } + }, + { + "name": "createTicket", + "description": "在问题跟踪器中创建工单", + "parameters": { + "title": { "type": "string" }, + "description": { "type": "string" } + } + } + ] +} +``` + +这种"即插即用"能力允许添加新工具而无需重新部署或修改AI本身。 + +## 实际示例：多工具工作流程 + +考虑一个需要多个服务的任务："检查最近的提交，为bug修复创建JIRA工单，并发布到Slack。" + +**基于REST的方法**： +- 需要为Git、JIRA和Slack API分别集成 +- 需要自定义代码来管理调用间的上下文 +- 任何服务更改API都会中断 + +**基于MCP的方法**： +- 所有工具的统一协议 +- 维护整个工作流程的上下文 +- 新工具可以无缝替换，无需代码修改 + +## 为什么Kilo Code使用MCP + +Kilo Code利用MCP提供： + +1. **可扩展性**：添加无限自定义工具，无需等待官方集成 +2. **上下文感知**：工具可以访问对话历史和项目上下文 +3. **简化集成**：一个标准协议，而非多种API模式 +4. **运行时灵活性**：动态发现和使用新功能 + +MCP在Kilo Code和外部服务之间创建了通用连接器，REST API通常在这些服务背后提供支持。 + +## 结论：互补而非竞争的技术 + +MCP并不取代REST API - 它建立在它们之上。REST擅长提供离散服务，而MCP擅长为AI代理编排这些服务。 + +关键区别在于MCP是AI原生的：它把模型视为一等用户，提供AI代理在复杂环境中有效运行所需的上下文、有状态交互层。 \ No newline at end of file diff --git a/docs/zh-CN/features/mcp/overview.md b/docs/zh-CN/features/mcp/overview.md new file mode 100644 index 0000000..f8fc0ab --- /dev/null +++ b/docs/zh-CN/features/mcp/overview.md @@ -0,0 +1,20 @@ +--- +title: MCP概览 +sidebar_label: MCP概览 +--- + +# 模型上下文协议（MCP） + +模型上下文协议（MCP）是扩展Kilo Code功能的标准化协议，通过连接外部工具和服务来实现。MCP服务器提供了额外的工具和资源，帮助Kilo Code完成超出其内置功能的任务，例如访问数据库、自定义API和特殊功能。 + +## MCP文档结构 + +本文档分为以下几个部分： + +* [**在Kilo Code中使用MCP**](/features/mcp/using-mcp-in-kilo-code) - 在Kilo Code中配置、启用和管理MCP服务器的综合指南。包括服务器设置、工具批准和故障排除。 + +* [**什么是MCP？**](/features/mcp/what-is-mcp) - 解释模型上下文协议、其客户端-服务器架构以及如何使AI系统与外部工具交互。 + +* [**STDIO与SSE传输**](/features/mcp/server-transports) - 详细比较本地（STDIO）和远程（SSE）传输机制，以及每种方法的部署考虑。 + +* [**MCP与API**](/features/mcp/mcp-vs-api) - 分析MCP与REST API的根本区别，解释它们如何在不同的抽象层为AI系统工作。 \ No newline at end of file diff --git a/docs/zh-CN/features/mcp/server-transports.md b/docs/zh-CN/features/mcp/server-transports.md new file mode 100644 index 0000000..1cba408 --- /dev/null +++ b/docs/zh-CN/features/mcp/server-transports.md @@ -0,0 +1,197 @@ +--- +title: MCP服务器传输机制 +sidebar_label: STDIO与SSE传输 +--- + +# MCP服务器传输机制：STDIO与SSE + +模型上下文协议（MCP）支持两种主要的传输机制用于Kilo Code与MCP服务器之间的通信：标准输入/输出（STDIO）和服务器发送事件（SSE）。每种机制都有其独特的特点、优势和适用场景。 + +## STDIO传输 + +STDIO传输在本地机器上运行，通过标准输入/输出流进行通信。 + +### STDIO传输工作原理 + +1. 客户端（Kilo Code）将MCP服务器作为子进程启动 +2. 通信通过进程流进行：客户端写入服务器的STDIN，服务器响应到STDOUT +3. 每个消息以换行符分隔 +4. 消息格式为JSON-RPC 2.0 + +``` +Client Server + | | + |---- JSON message ------>| (via STDIN) + | | (processes request) + |<---- JSON message ------| (via STDOUT) + | | +``` + +### STDIO特点 + +* **本地性**：与Kilo Code在同一台机器上运行 +* **性能**：延迟和开销非常低（不涉及网络栈） +* **简单性**：直接进程通信，无需网络配置 +* **关系**：客户端与服务器之间的一对一关系 +* **安全性**：本质上更安全，因为不暴露网络 + +### 使用STDIO的场景 + +STDIO传输适用于： + +* 本地集成和工具 +* 安全敏感操作 +* 低延迟要求 +* 单客户端场景（每个服务器一个Kilo Code实例） +* 命令行工具或IDE扩展 + +### STDIO实现示例 + +```typescript +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; + +const server = new Server({name: 'local-server', version: '1.0.0'}); +// 注册工具... + +// 使用STDIO传输 +const transport = new StdioServerTransport(server); +transport.listen(); +``` + +## SSE传输 + +服务器发送事件（SSE）传输在远程服务器上运行，通过HTTP/HTTPS进行通信。 + +### SSE传输工作原理 + +1. 客户端（Kilo Code）通过HTTP GET请求连接到服务器的SSE端点 +2. 建立持久连接，服务器可以向客户端推送事件 +3. 对于客户端到服务器的通信，客户端向单独的端点发送HTTP POST请求 +4. 通信通过两个通道进行： + * 事件流（GET）：服务器到客户端更新 + * 消息端点（POST）：客户端到服务器请求 + +``` +Client Server + | | + |---- HTTP GET /events ----------->| (establish SSE connection) + |<---- SSE event stream -----------| (persistent connection) + | | + |---- HTTP POST /message --------->| (client request) + |<---- SSE event with response ----| (server response) + | | +``` + +### SSE特点 + +* **远程访问**：可以托管在与Kilo Code不同的机器上 +* **可扩展性**：支持多个客户端并发连接 +* **协议**：基于标准HTTP（无需特殊协议） +* **持久性**：维护服务器到客户端消息的持久连接 +* **认证**：可以使用标准HTTP认证机制 + +### 使用SSE的场景 + +SSE传输更适合： + +* 跨网络远程访问 +* 多客户端场景 +* 公共服务 +* 许多用户需要访问的集中式工具 +* 与Web服务集成 + +### SSE实现示例 + +```typescript +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; +import express from 'express'; + +const app = express(); +const server = new Server({name: 'remote-server', version: '1.0.0'}); +// 注册工具... + +// 使用SSE传输 +const transport = new SSEServerTransport(server); +app.use('/mcp', transport.requestHandler()); +app.listen(3000, () => { + console.log('MCP server listening on port 3000'); +}); +``` + +## 本地 vs. 托管：部署考虑 + +选择STDIO还是SSE传输将直接影响MCP服务器的部署和管理方式。 + +### STDIO：本地部署模式 + +STDIO服务器与Kilo Code在同一台机器上运行，这有几个重要影响： + +* **安装**：必须在每个用户的机器上安装服务器可执行文件 +* **分发**：需要为不同操作系统提供安装包 +* **更新**：每个实例必须单独更新 +* **资源**：使用本地机器的CPU、内存和磁盘 +* **访问控制**：依赖于本地机器的文件系统权限 +* **集成**：易于与本地系统资源（文件、进程）集成 +* **执行**：随Kilo Code启动和停止（子进程生命周期） +* **依赖**：任何依赖项都必须安装在用户机器上 + +#### 实际示例 + +一个本地文件搜索工具使用STDIO会： +* 在用户机器上运行 +* 直接访问本地文件系统 +* 在Kilo Code需要时启动 +* 不需要网络配置 +* 需要与Kilo Code一起安装或通过包管理器安装 + +### SSE：托管部署模式 + +SSE服务器可以部署到远程服务器并通过网络访问： + +* **安装**：在服务器上安装一次，供多个用户访问 +* **分发**：单一部署服务多个客户端 +* **更新**：集中更新立即影响所有用户 +* **资源**：使用服务器资源，而非本地机器资源 +* **访问控制**：通过认证和授权系统管理 +* **集成**：与用户特定资源的集成更复杂 +* **执行**：作为独立服务运行（通常持续运行） +* **依赖**：在服务器上管理，而非用户机器 + +#### 实际示例 + +一个数据库查询工具使用SSE会： +* 在中央服务器上运行 +* 使用服务器端凭据连接数据库 +* 持续可用，供多个用户使用 +* 需要正确的网络安全配置 +* 使用容器或云技术部署 + +### 混合方法 + +某些场景受益于混合方法： + +1. **带网络访问的STDIO**：本地STDIO服务器充当远程服务的代理 +2. **带本地命令的SSE**：远程SSE服务器可以通过回调触发客户端机器上的操作 +3. **网关模式**：本地操作的STDIO服务器连接到专用功能的SSE服务器 + +## 选择STDIO还是SSE + +| 考虑因素 | STDIO | SSE | +|---------------|-------|-----| +| **位置** | 仅限本地机器 | 本地或远程 | +| **客户端** | 单客户端 | 多客户端 | +| **性能** | 延迟更低 | 延迟更高（网络开销） | +| **设置复杂性** | 更简单 | 更复杂（需要HTTP服务器） | +| **安全性** | 本质上更安全 | 需要明确的安全措施 | +| **网络访问** | 不需要 | 需要 | +| **可扩展性** | 限于本地机器 | 可以在网络上分布 | +| **部署** | 每用户安装 | 集中安装 | +| **更新** | 分布式更新 | 集中更新 | +| **资源使用** | 使用客户端资源 | 使用服务器资源 | +| **依赖** | 客户端依赖 | 服务器依赖 | + +## 在Kilo Code中配置传输 + +有关在Kilo Code中配置STDIO和SSE传输的详细信息，包括示例配置，请参见[理解传输类型](/features/mcp/using-mcp-in-kilo-code#understanding-transport-types)部分。 \ No newline at end of file diff --git a/docs/zh-CN/features/mcp/using-mcp-in-kilo-code.md b/docs/zh-CN/features/mcp/using-mcp-in-kilo-code.md new file mode 100644 index 0000000..3658a2f --- /dev/null +++ b/docs/zh-CN/features/mcp/using-mcp-in-kilo-code.md @@ -0,0 +1,259 @@ +--- +title: 在Kilo Code中使用MCP +sidebar_label: 在Kilo Code中使用MCP +--- + +# 在Kilo Code中使用MCP + +模型上下文协议（MCP）通过连接外部工具和服务扩展了Kilo Code的功能。本指南涵盖了在Kilo Code中使用MCP所需了解的所有内容。 + + + +## 配置MCP服务器 + +MCP服务器配置可以在两个级别进行管理： + +1. **全局配置**：存储在`mcp_settings.json`文件中，可通过VS Code设置访问（见下文）。这些设置适用于所有工作区，除非被项目级配置覆盖。 +2. **项目级配置**：在项目根目录的`.kilocode/mcp.json`文件中定义。这允许你设置项目特定的服务器，并通过将文件提交到版本控制与团队共享配置。如果存在，Kilo Code会自动检测并加载此文件。 + +**优先级**：如果服务器名称同时存在于全局和项目配置中，则**项目级配置优先**。 + +### 编辑MCP设置文件 + +你可以直接从Kilo Code MCP设置视图编辑全局和项目级MCP配置文件： + +1. 点击Kilo Code窗格顶部导航中的图标。 + + Kilo Code中的MCP服务器界面 + +2. 滚动到MCP设置视图的底部。 +3. 点击适当的按钮： + * **`编辑全局MCP`**：打开全局`mcp_settings.json`文件。 + * **`编辑项目MCP`**：打开项目特定的`.kilocode/mcp.json`文件。如果该文件不存在，Kilo Code将为你创建。 + + 编辑全局MCP和编辑项目MCP按钮 + +两个文件都使用JSON格式，其中包含一个`mcpServers`对象，包含命名的服务器配置： + +```json +{ + "mcpServers": { + "server1": { + "command": "python", + "args": ["/path/to/server.py"], + "env": { + "API_KEY": "your_api_key" + }, + "alwaysAllow": ["tool1", "tool2"], + "disabled": false + } + } +} +``` + +*Kilo Code中的MCP服务器配置示例（STDIO传输）* + +### 理解传输类型 + +MCP支持两种服务器通信的传输类型： + +#### STDIO传输 + +用于在本地机器上运行的服务器： + +* 通过标准输入/输出流通信 +* 延迟更低（无网络开销） +* 安全性更好（无网络暴露） +* 设置更简单（不需要HTTP服务器） +* 作为本地机器上的子进程运行 + +有关STDIO传输工作原理的深入信息，请参见[STDIO传输](/features/mcp/server-transports#stdio-transport)。 + +STDIO配置示例： +```json +{ + "mcpServers": { + "local-server": { + "command": "node", + "args": ["/path/to/server.js"], + "env": { + "API_KEY": "your_api_key" + }, + "alwaysAllow": ["tool1", "tool2"], + "disabled": false + } + } +} +``` + +#### SSE传输 + +用于通过HTTP/HTTPS访问的远程服务器： + +* 通过服务器发送事件协议通信 +* 可以托管在不同的机器上 +* 支持多个客户端连接 +* 需要网络访问 +* 允许集中部署和管理 + +有关SSE传输工作原理的深入信息，请参见[SSE传输](/features/mcp/server-transports#sse-transport)。 + +SSE配置示例： + +```json +{ + "mcpServers": { + "remote-server": { + "url": "https://your-server-url.com/mcp", + "headers": { + "Authorization": "Bearer your-token" + }, + "alwaysAllow": ["tool3"], + "disabled": false + } + } +} +``` + +## 启用或禁用MCP服务器 + +在此处禁用MCP服务器将从系统提示中删除所有与MCP相关的逻辑和定义，减少token使用。这将阻止Kilo Code连接任何MCP服务器，并且`use_mcp_tool`和`access_mcp_resource`工具将不可用。如果你不打算使用MCP服务器，请取消勾选此选项。默认情况下为启用。 + +1. 点击Kilo Code窗格顶部导航中的图标 +2. 勾选/取消勾选`启用MCP服务器` + + 启用MCP服务器切换 + +## 启用或禁用MCP服务器创建 + +在此处禁用MCP服务器创建将仅从系统提示中删除Kilo Code用于编写MCP服务器的指令，而不删除操作它们的上下文。这减少了token使用。默认情况下为启用。 + +1. 点击Kilo Code窗格顶部导航中的图标 +2. 勾选/取消勾选`启用MCP服务器创建` + + 启用MCP服务器创建切换 + +## 管理单个MCP服务器 + + MCP服务器配置面板示例 + +每个MCP服务器都有自己的配置面板，你可以在此修改设置、管理工具并控制其操作。要访问这些设置： + +1. 点击Kilo Code窗格顶部导航中的图标 +2. 在列表中定位要管理的MCP服务器 + MCP服务器列表 + +### 删除服务器 + +1. 点击要删除的MCP服务器旁边的 +2. 在确认框中点击`删除`按钮 + + 删除确认框 + +### 重启服务器 + +1. 点击要重启的MCP服务器旁边的按钮 + +### 启用或禁用服务器 + +1. 点击MCP服务器旁边的切换开关以启用/禁用 + +### 网络超时 + +设置调用MCP服务器工具后等待响应的最长时间： + +1. 点击单个MCP服务器配置框底部的`网络超时`下拉菜单并更改时间。默认值为1分钟，但可以设置为30秒到5分钟之间。 + +网络超时下拉菜单 + +### 自动批准工具 + +MCP工具自动批准按工具进行，默认禁用。要配置自动批准： + +1. 首先在[自动批准操作](/features/auto-approving-actions)中启用全局"使用MCP服务器"自动批准选项 +2. 在MCP服务器设置中，定位要自动批准的特定工具 +3. 勾选工具名称旁边的`始终允许`复选框 + +MCP工具的始终允许复选框 + +启用后，Kilo Code将自动批准此特定工具而无需提示。请注意，全局"使用MCP服务器"设置优先 - 如果它被禁用，则不会自动批准任何MCP工具。 + +## 查找和安装MCP服务器 + +Kilo Code不附带任何预安装的MCP服务器。你需要单独查找并安装它们。 + +* **社区仓库**：在GitHub上查看社区维护的MCP服务器列表 +* **询问Kilo Code**：你可以请Kilo Code帮助你查找甚至创建MCP服务器（当"[启用MCP服务器创建](#enabling-or-disabling-mcp-server-creation)"启用时） +* **自行构建**：使用SDK创建自定义MCP服务器，使用你自己的工具扩展Kilo Code + +有关完整的SDK文档，请访问[MCP GitHub仓库](https://github.com/modelcontextprotocol/)。 + +## 在工作流中使用MCP工具 + +配置MCP服务器后，Kilo Code将自动检测可用的工具和资源。要使用它们： + +1. 在Kilo Code聊天界面中输入你的请求 +2. Kilo Code将识别何时MCP工具可以帮助完成任务 +3. 在提示时批准工具使用（或使用自动批准） + +示例："分析我的API性能"可能会使用一个测试API端点的MCP工具。 + +## 故障排除MCP服务器 + +常见问题及解决方案： + +* **服务器无响应**：检查服务器进程是否正在运行并验证网络连接 +* **权限错误**：确保在`mcp_settings.json`（用于全局设置）或`.kilocode/mcp.json`（用于项目设置）中配置了正确的API密钥和凭据。 +* **工具不可用**：确认服务器是否正确实现了该工具且未在设置中禁用 +* **性能缓慢**：尝试调整特定MCP服务器的网络超时值 + +## 平台特定的MCP配置示例 + +### Windows配置示例 + +在Windows上设置MCP服务器时，你需要使用Windows命令提示符（`cmd`）来执行命令。以下是在Windows上配置Puppeteer MCP服务器的示例： + +```json +{ + "mcpServers": { + "puppeteer": { + "command": "cmd", + "args": [ + "/c", + "npx", + "-y", + "@modelcontextprotocol/server-puppeteer" + ] + } + } +} +``` + +此Windows特定配置： +- 使用`cmd`命令访问Windows命令提示符 +- 使用`/c`告诉cmd执行命令然后终止 +- 使用`npx`运行包而无需永久安装 +- `-y`标志在安装期间自动回答"是"任何提示 +- 运行提供浏览器自动化功能的`@modelcontextprotocol/server-puppeteer`包 + +:::note +对于macOS或Linux，你将使用不同的配置： +```json +{ + "mcpServers": { + "puppeteer": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-puppeteer" + ] + } + } +} +``` +::: + +相同的方法可以用于Windows上的其他MCP服务器，根据需要调整包名称以匹配不同的服务器类型。 \ No newline at end of file diff --git a/docs/zh-CN/features/mcp/what-is-mcp.md b/docs/zh-CN/features/mcp/what-is-mcp.md new file mode 100644 index 0000000..0336cd0 --- /dev/null +++ b/docs/zh-CN/features/mcp/what-is-mcp.md @@ -0,0 +1,49 @@ +--- +title: 什么是 MCP？ +sidebar_label: 什么是 MCP？ +--- + +# 什么是 MCP？ + +MCP（Model Context Protocol，模型上下文协议）是 LLM 系统与外部工具和服务交互的标准化通信协议。它充当 AI 助手与各类数据源或应用程序之间的通用适配器。 + +## 工作原理 + +MCP 采用客户端-服务端架构： + +1. AI 助手（客户端）连接至 MCP 服务器 +2. 每个服务器提供特定能力（文件访问、数据库查询、API 集成等） +3. AI 通过标准化接口使用这些能力 +4. 通信通过 JSON-RPC 2.0 消息进行 + +可以将 MCP 类比为 USB-C 接口——任何兼容的 LLM 都能连接任意 MCP 服务器来使用其功能。这种标准化消除了为每个工具和服务构建定制集成的需求。 + +例如，使用 MCP 的 AI 可以执行"搜索公司数据库并生成报告"这类任务，而无需为每个数据库系统编写专用代码。 + +## 常见问题 + +- **MCP 是云服务吗？** MCP 服务器既可在本地运行，也可作为云服务远程部署，具体取决于使用场景和安全要求。 + +- **MCP 会取代其他集成方式吗？** 不会。MCP 是对 API 插件和检索增强生成等现有工具的补充。它提供了工具交互的标准化协议，但不会取代专业集成方案。 + +- **如何保障安全性？** 用户可自主控制连接哪些 MCP 服务器，以及授予这些服务器哪些权限。与任何访问数据或服务的工具一样，请使用可信来源并配置适当的访问控制。 + +## Kilo Code 中的 MCP + +Kilo Code 通过实现模型上下文协议来： + +- 同时连接本地和远程 MCP 服务器 +- 提供访问工具的统一接口 +- 无需修改核心即可扩展功能 +- 按需启用专项能力 + +MCP 为 AI 系统与外部工具服务的交互提供了标准化方式，使复杂集成更易用且一致。 + +## 深入了解 MCP + +准备好深入探索了吗？请查阅以下指南： + +- [MCP 概述](/features/mcp/overview) - 快速了解 MCP 文档结构 +- [在 Kilo Code 中使用 MCP](/features/mcp/using-mcp-in-kilo-code) - 包含创建简单服务器的入门指导 +- [MCP vs 传统 API](/features/mcp/mcp-vs-api) - 相比传统 API 的技术优势 +- [STDIO 与 SSE 传输协议](/features/mcp/server-transports) - 本地与云端部署模式对比 \ No newline at end of file diff --git a/docs/zh-CN/features/model-temperature.md b/docs/zh-CN/features/model-temperature.md new file mode 100644 index 0000000..3f49d85 --- /dev/null +++ b/docs/zh-CN/features/model-temperature.md @@ -0,0 +1,93 @@ +# 模型温度 + +温度控制控制着 AI 模型输出的随机性。调整此设置可以优化不同任务的结果 - 从精确的代码生成到创意头脑风暴。温度是控制 AI 行为最强大的参数之一。经过良好调优的温度设置可以显著提高特定任务响应的质量和适用性。 + +展示温度滑块调整的动画 + +## 什么是温度？ + +温度是一个设置（通常在 0.0 到 2.0 之间），用于控制 AI 输出的随机性或可预测性。找到合适的平衡点很关键：较低的值使输出更加集中和一致，而较高的值则鼓励更多的创造性和多样性。对于许多编码任务，适中的温度（大约 0.3 到 0.7）通常效果很好，但最佳设置取决于你想要实现的目标。 + +:::info 温度和代码：常见误解 +温度控制输出随机性，而不是直接控制代码质量或准确性。关键点： + +* **低温（接近 0.0）：** 产生可预测、一致的代码。适用于简单任务，但可能重复且缺乏创造性。它不保证代码更好。 +* **高温：** 增加随机性，可能导致创造性解决方案，但也可能产生更多错误或无意义的代码。它不保证代码质量更高。 +* **准确性：** 代码准确性取决于模型的训练和提示的清晰度，而不是温度。 +* **温度 0.0：** 对一致性很有用，但限制了解决复杂问题所需的探索。 +::: + +## Kilo Code 中的默认值 + +Kilo Code 对大多数模型使用默认温度 0.0，优化代码生成的最大确定性和精确性。这适用于 OpenAI 模型、Anthropic 模型（非思考变体）、LM Studio 模型和大多数其他提供者。 + +一些模型使用更高的默认温度 - DeepSeek R1 模型和某些以推理为重点的模型默认温度为 0.6，在确定性和创造性探索之间提供了平衡。 + +具有思考能力的模型（AI 显示其推理过程）需要固定的温度 1.0，无法更改，因为此设置确保了思考机制的最佳性能。这适用于任何启用了 ":thinking" 标志的模型。 + +一些特殊模型根本不支持温度调整，在这种情况下，Kilo Code 会自动尊重这些限制。 + +## 何时调整温度 + +以下是一些适用于不同任务的温度设置示例： + +* **代码模式（0.0-0.3）：** 用于编写精确、正确的代码，具有一致的确定性结果 +* **架构模式（0.4-0.7）：** 用于头脑风暴架构或设计解决方案，平衡创造性和结构 +* **问答模式（0.7-1.0）：** 用于需要多样化和有洞察力的响应的解释或开放式问题 +* **调试模式（0.0-0.3）：** 用于以一致的精确性排除故障 + +这些都是起点 - 重要的是[尝试不同的设置](#experimentation)以找到最适合你特定需求和偏好的设置。 + +## 如何调整温度 + +1. **打开 Kilo Code 面板：** 点击 VS Code 侧边栏中的 Kilo Code 图标（） +2. **打开设置：** 点击右上角的 图标 +3. **找到温度控制：** 导航到提供者部分 +4. **启用自定义温度：** 勾选 "使用自定义温度" 复选框 +5. **设置你的值：** 将滑块调整为你偏好的值 + + Kilo Code 设置面板中的温度滑块 + *Kilo Code 设置面板中的温度滑块* + +## 使用 API 配置配置文件设置温度 + +创建多个具有不同温度设置的[API 配置配置文件](/features/api-configuration-profiles)： + +**如何设置特定任务的温度配置文件：** + +1. 创建专门配置文件，如 "代码 - 低温"（0.1）和 "问答 - 高温"（0.8） +2. 为每个配置文件配置适当的温度设置 +3. 使用设置或聊天界面中的下拉菜单在配置文件之间切换 +4. 为每个模式设置不同的默认配置文件，以便在更改模式时自动切换 + +这种方法无需手动调整即可优化特定任务的模型行为。 + +## 技术实现 + +Kilo Code 实现温度处理时考虑以下因素： + +* 用户定义的设置优先于默认值 +* 尊重提供者特定的行为 +* 强制执行模型特定的限制： + * 启用思考的模型需要固定的温度 1.0 + * 一些模型不支持温度调整 + +## 实验 + +尝试不同的温度设置是发现最适合你特定需求的最有效方法： + +### 有效的温度测试 + +1. **从默认值开始** - 以 Kilo Code 的预设值（大多数任务为 0.0）作为基线 +2. **逐步调整** - 以小步长（±0.1）更改值以观察细微差异 +3. **一致测试** - 在不同温度设置下使用相同的提示进行有效比较 +4. **记录结果** - 记下哪些值对特定类型的任务产生最佳结果 +5. **创建配置文件** - 将有效设置保存为[API 配置配置文件](/features/api-configuration-profiles)以便快速访问 + +请记住，不同的模型可能对相同的温度值有不同的响应，而启用思考的模型无论你的设置如何，始终使用固定的温度 1.0。 + +## 相关功能 + +- 与 Kilo Code 支持的所有[API 提供者](/providers/openai)一起使用 +- 与[自定义指令](/advanced-usage/custom-instructions)相辅相成，用于微调响应 +- 与你创建的[自定义模式](/features/custom-modes)一起使用 \ No newline at end of file diff --git a/docs/zh-CN/features/more-features.md b/docs/zh-CN/features/more-features.md new file mode 100644 index 0000000..e2c2d77 --- /dev/null +++ b/docs/zh-CN/features/more-features.md @@ -0,0 +1,42 @@ +--- +sidebar_label: 更多功能 +--- + +# 更多功能 + +本页面描述了 Kilo Code 中增强开发工作流程的更多功能。 + +## 建议响应 + +Kilo Code 提供问题的建议响应，节省你打字的时间。这些建议在提问后以按钮的形式出现在聊天输入框下方。点击建议即可快速将其用作你的下一个提示。 + +此功能旨在通过预测你可能的后续问题并提供一键访问相关提示来简化你的工作流程。 + +## 文本转语音 + +Kilo Code 包含一个文本转语音（TTS）功能，可以朗读 AI 的响应，让你可以听取信息而不是阅读。这对于无障碍访问、学习或简单地改变节奏很有帮助。 + +要使用文本转语音功能，只需在 Kilo Code 设置中启用它。启用后，聊天中每个 AI 响应旁边都会出现一个扬声器图标。点击图标开始收听。 + +## 全球语言支持 + +Kilo Code 支持 14 种语言，使其对全球更广泛的用户群体更加易用。你现在可以使用以下语言的 Kilo Code： + +- 简体中文 +- 繁体中文 +- 西班牙语 +- 印地语 +- 法语 +- 葡萄牙语 +- 德语 +- 日语 +- 韩语 +- 意大利语 +- 土耳其语 +- 越南语 +- 波兰语 +- 加泰罗尼亚语 + +要更改你的语言，请前往 Kilo Code 设置面板中的**高级设置 > 语言**。 + +此次全球更新确保了全球用户更流畅、更包容的编码体验。 \ No newline at end of file diff --git a/docs/zh-CN/features/settings-management.md b/docs/zh-CN/features/settings-management.md new file mode 100644 index 0000000..9a6e66d --- /dev/null +++ b/docs/zh-CN/features/settings-management.md @@ -0,0 +1,60 @@ +--- +title: 导入、导出和重置设置 +sidebar_label: 导入/导出/重置设置 +description: 通过导出、导入或重置为默认值来管理你的 Kilo Code 设置。 +--- + +# 导入、导出和重置设置 + +Kilo Code 允许你通过导出、导入和重置选项有效地管理配置设置。这些功能可用于备份设置、与他人共享配置或在需要时恢复默认设置。 + +你可以在 Kilo Code 设置页面的底部找到这些选项，通过 Kilo Code 聊天视图中的齿轮图标（）访问。 + +Kilo Code 设置中的导出、导入和重置按钮 +*图片：导出、导入和重置按钮。* + +## 导出设置 + +点击**导出**按钮将你当前的 Kilo Code 设置保存为 JSON 文件。 + +* **导出的内容：** 文件包括你配置的 API 提供者配置文件和全局设置（UI 偏好、模式配置、上下文设置等）。 +* **安全警告：** 导出的 JSON 文件包含**所有**你配置的 API 提供者配置文件和全局设置。关键是，这包括**明文中的 API 密钥**。将此文件视为高度敏感。不要公开分享或与不受信任的个人分享，因为它授予访问你的 API 帐户的权限。 +* **过程：** + 1. 点击**导出**。 + 2. 出现文件保存对话框，建议文件名为 `kilo-code-settings.json`（通常在 `~/Documents` 文件夹中）。 + 3. 选择位置并保存文件。 + +这将创建配置的备份或可共享的文件。 + +## 导入设置 + +点击**导入**按钮允许你从之前导出的 JSON 文件加载设置。 + +* **过程：** + 1. 点击**导入**。 + 2. 出现文件打开对话框。选择要导入的 `kilo-code-settings.json` 文件（或类似命名的文件）。 + 3. Kilo Code 读取文件，根据预期模式验证其内容，并应用设置。 +* **合并：** 导入设置**合并**配置。它根据文件内容添加新的 API 配置文件并更新现有配置和全局设置。它不会删除当前设置中存在但导入文件中缺少的配置。 +* **验证：** 只有与内部模式匹配的有效设置才能被导入，防止配置错误。完成后会出现成功通知。 + +## 重置设置 + +点击**重置**按钮将完全清除所有 Kilo Code 配置数据并将扩展恢复到默认状态。这是一个破坏性操作，旨在进行故障排除或重新开始。 + +* **警告：** 此操作是**不可逆的**。它永久删除所有 API 配置（包括存储在秘密存储中的密钥）、自定义模式、全局设置和任务历史记录。 + +* **过程：** + 1. 点击红色的**重置**按钮。 + 2. 出现确认对话框，警告此操作无法撤销。 + 3. 点击“是”确认。 + +* **重置的内容：** + * **API 提供者配置文件：** 从设置和秘密存储中删除所有配置。 + * **全局设置：** 所有偏好（UI、模式、批准、浏览器等）重置为默认值。 + * **自定义模式：** 删除所有用户定义的模式。 + * **秘密存储：** 清除 Kilo Code 管理的所有 API 密钥和其他秘密。 + * **任务历史记录：** 清除当前任务堆栈。 + +* **结果：** Kilo Code 恢复到初始状态，就像刚安装一样，具有默认设置且没有用户配置。 + +仅在你确定要删除所有 Kilo Code 数据或在进行故障排除时被指示时使用此选项。如果以后可能需要恢复设置，请考虑先导出你的设置。 \ No newline at end of file diff --git a/docs/zh-CN/features/shell-integration.md b/docs/zh-CN/features/shell-integration.md new file mode 100644 index 0000000..6f832c0 --- /dev/null +++ b/docs/zh-CN/features/shell-integration.md @@ -0,0 +1,382 @@ +# 终端 Shell 集成 + +终端 Shell 集成是 Kilo Code 的核心功能，使其能够在您的终端执行命令并智能处理输出。这种 AI 与开发环境的双向通信解锁了强大的自动化能力。 + +## Shell 集成是什么？ + +Shell 集成在 Kilo Code 中自动启用，无需任何设置即可直接连接至终端命令执行生命周期。该内置功能允许 Kilo Code： + +- 通过 [`execute_command`](/features/tools/execute-command) 工具代您执行命令 +- 实时读取命令输出，无需手动复制粘贴 +- 自动检测并修复运行中的应用程序错误 +- 通过退出代码判断命令执行成败 +- 跟踪工作目录变化 +- 智能响应终端输出而无需用户干预 + +当 Kilo Code 需要执行安装依赖、启动开发服务器或分析构建错误等任务时，Shell 集成会在后台确保交互流程顺畅高效。 + +## 开始使用 Shell 集成 + +Shell 集成已内置在 Kilo Code 中，多数情况下自动工作。若出现"Shell 集成不可用"提示或命令执行问题，可尝试以下解决方案： + +1. **更新 VSCode/Cursor** 至最新版本（要求 VSCode 1.93+） +2. **选择兼容的 Shell**：命令面板（`Ctrl+Shift+P` 或 `Cmd+Shift+P`）→ "Terminal: Select Default Profile" → 选择 bash、zsh、PowerShell 或 fish +3. **Windows PowerShell 用户**：运行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` 后重启 VSCode +4. **WSL 用户**：在 `~/.bashrc` 中添加 `. "$(code --locate-shell-integration-path bash)"` + +## 终端集成设置 + +Kilo Code 提供多项设置来微调 Shell 集成。通过 Kilo Code 侧边栏的 Settings → Terminal 访问这些设置。 + +### 基础设置 + +#### 终端输出限制 +终端输出限制滑块设置为500行 +控制从终端捕获的最大行数。超出限制时，保留开头20%和结尾80%的内容，中间显示截断提示。在保持上下文的同时避免过度消耗 token。默认值： 500 行。 +控制从终端捕获的最大行数。超出限制时，系统会从内容中间删除部分行以节省 token。默认值：500 行。 + +#### Shell 集成超时 +Shell集成超时滑块设置为15秒 + +等待 Shell 集成初始化的最长时间。若遇到"Shell 集成不可用"错误可增加此值。默认：15秒。 + +#### 终端命令延迟 +终端命令延迟滑块设置为0毫秒 + +在命令执行后添加短暂停顿，确保 Kilo Code 正确捕获所有输出。此设置对不同操作系统和 Shell 配置的可靠性影响显著： + +- **默认值**：0毫秒 +- **常用值**： + * 0毫秒：新版 VSCode 用户最佳选择 + * 50毫秒：历史默认值，对多数用户仍有效 + * 150毫秒：PowerShell 用户推荐值 +- **注意**：最佳值可能取决于： + * VSCode 版本 + * Shell 定制程度（如 oh-my-zsh、powerlevel10k 等） + * 操作系统和环境 + +### 高级设置 + +:::info 重要提示 +**修改后需重启终端** + +高级终端设置的变更仅在重启终端后生效。重启步骤： + +1. 点击终端面板的垃圾桶图标关闭当前终端 +2. 通过 Terminal → New Terminal 或 Ctrl+` 新建终端 + +修改任何设置后请务必重启所有打开的终端。 +::: + +#### PowerShell 计数器解决方案 +PowerShell计数器解决方案复选框 + +解决 PowerShell 连续执行相同命令的问题。若发现 Kilo Code 无法在 PowerShell 中连续运行相同命令，请启用此选项。 + +#### 清除 ZSH EOL 标记 +清除ZSH行尾标记复选框 + +阻止 ZSH 在输出行尾添加可能干扰 Kilo Code 读取结果的特殊字符。 + +#### Oh My Zsh 集成 +启用Oh My Zsh集成复选框 + +优化与流行 Shell 框架 [Oh My Zsh](https://ohmyz.sh/) 的兼容性。使用 Oh My Zsh 时若遇到终端问题请开启。 + +#### Powerlevel10k 集成 +启用Powerlevel10k集成复选框 + +提升与 ZSH 主题 Powerlevel10k 的兼容性。若花哨的终端提示符导致问题请启用。 + +#### ZDOTDIR 处理 +启用ZDOTDIR处理复选框 + +使 Kilo Code 能兼容自定义 ZSH 配置，同时不影响您的个人 Shell 设置。 + +## 故障排除 + +### PowerShell 执行策略（Windows） + +PowerShell 默认限制脚本执行。配置方法： + +1. 以管理员身份打开 PowerShell +2. 查看当前策略：`Get-ExecutionPolicy` +3. 设置合适策略：`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` + +常用策略： +- `Restricted`：禁止所有脚本（默认） +- `RemoteSigned`：本地脚本可运行，下载脚本需签名 +- `Unrestricted`：所有脚本带警告运行 +- `AllSigned`：所有脚本必须签名 + +### 手动安装 Shell 集成 + +若自动集成失败，请将对应代码添加到 Shell 配置中： + +**Bash**（`~/.bashrc`）： +```bash +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)" +``` + +**Zsh**（`~/.zshrc`）： +```bash +[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)" +``` + +**PowerShell**（`$Profile`）： +```powershell +if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" } +``` + +**Fish**（`~/.config/fish/config.fish`）： +```fish +string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish) +``` + +## 终端定制问题 + +若使用终端定制工具： + +**Powerlevel10k**： +```bash +# 在 ~/.zshrc 中 sourcing powerlevel10k 之前添加 +typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true +``` + +**替代方案**：在 Kilo Code 设置中启用 Powerlevel10k 集成选项 + +## Shell 集成状态验证 + +使用以下命令确认集成是否激活： + +**Bash**： +```bash +set | grep -i '[16]33;' +echo "$PROMPT_COMMAND" | grep vsc +trap -p DEBUG | grep vsc +``` + +**Zsh**： +```zsh +functions | grep -i vsc +typeset -p precmd_functions preexec_functions +``` + +**PowerShell**： +```powershell +Get-Command -Name "*VSC*" -CommandType Function +Get-Content Function:\Prompt | Select-String "VSCode" +``` + +**Fish**： +```fish +functions | grep -i vsc +functions fish_prompt | grep -i vsc +``` + +集成激活的视觉指示： +1. 终端标题栏中的集成标识 +2. 命令检测高亮显示 +3. 终端标题中的工作目录更新 +4. 命令执行时间和退出码显示 + +## WSL 终端集成方案 + +使用 Windows Subsystem for Linux (WSL) 时，有两种集成方式： + +### 方案1：Windows版VSCode + WSL终端 +特点： +- VSCode 运行于 Windows +- 使用 WSL 终端桥接 +- 需手动确保 WSL 环境中加载了集成脚本： + ```bash + source "$(code --locate-shell-integration-path )" + ``` + +### 方法二：在WSL中运行VSCode + +在此设置中： +- 你可以使用 `code .` 命令直接从WSL中启动VSCode +- VSCode服务端在Linux环境中本地运行 +- 可直接访问Linux文件系统和工具 +- 为Shell集成提供更好的性能和可靠性 +- 由于VSCode在Linux环境中本地运行，Shell集成会自动加载 +- 这是WSL开发的推荐方式 + +要实现WSL的最佳Shell集成，我们建议： +1. 打开你的WSL发行版 +2. 导航到项目目录 +3. 使用 `code .` 启动VSCode +4. 使用VSCode内的集成终端 + +## 常见问题解决方案 + +### Windows 上 Fish + Cygwin 的 VS Code Shell 集成 + +对于在 Cygwin 环境中运行 Fish 终端的 Windows 用户，以下是配置 VS Code Shell 集成的方法： + +1. **（可选）定位 Shell 集成脚本** + 在 **VS Code 内**打开 Fish 终端并执行： + ```bash + code --locate-shell-integration-path fish + ``` + 该命令会输出 `shellIntegration.fish` 脚本的路径，请记录此路径。 + +2. **更新 Fish 配置** + 编辑 `config.fish` 文件（通常位于 Cygwin 主目录下的 `~/.config/fish/config.fish`）。添加以下行，建议放在 `if status is-interactive` 块内或文件末尾： + + ```fish + # 示例 config.fish 结构 + if status is-interactive + # 其他交互式 shell 配置... + # 自动定位集成脚本： + string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish) + + # 若上述方法失败： + # 手动引入 VS Code shell 集成脚本 + # 重要：将下方示例路径替换为步骤 1 中获取的实际路径 + # 确保路径格式符合 Cygwin 规范（例如 /cygdrive/c/...） + # source "/cygdrive/c/Users/你的用户名/.vscode/extensions/..../shellIntegration.fish" + end + ``` + *请将示例路径替换为步骤 1 中的实际路径，并确保格式符合 Cygwin 要求。* + +3. **配置 VS Code 终端配置文件** + 打开 VS Code 的 `settings.json` 文件（Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"）。在 `terminal.integrated.profiles.windows` 下更新或添加 Fish 配置文件： + + ```json + { + // ... 其他设置 ... + + "terminal.integrated.profiles.windows": { + // ... 其他配置文件 ... + + // 推荐：使用 bash.exe 以登录 shell 方式启动 fish + "fish": { + "path": "C:\\cygwin64\\bin\\bash.exe", // 或你的 Cygwin bash 路径 + "args": [ + "--login", // 确保执行登录脚本（对 Cygwin 环境很重要） + "-i", // 确保 bash 以交互模式运行 + "-c", + "exec fish" // 用 fish 替换 bash 进程 + ], + "icon": "terminal-bash" // 可选：使用可识别的图标 + }, + // 备选方案（若上述方法失败）：直接启动 fish + "fish-direct": { + "path": "C:\\cygwin64\\bin\\fish.exe", // 确保此路径在 Windows PATH 中或提供完整路径 + // 此处使用 'options' 而非 'args'，否则可能遇到 "终端进程终止，退出代码 1" 错误 + "options": ["-l", "-c"], // 示例：登录和交互标志 + "icon": "terminal-fish" // 可选：使用 fish 图标 + } + }, + + // 可选：如需将 fish 设置为默认终端 + // "terminal.integrated.defaultProfile.windows": "fish", // 或 "fish-direct"，取决于你使用的配置 + + // ... 其他设置 ... + } + ``` + *注意：在 Cygwin 环境中，使用 `bash.exe --login -i -c "exec fish"` 通常能更可靠地确保在启动 `fish` 前正确设置环境。但若此方法无效，请尝试 `fish-direct` 配置文件。* + +4. **重启 VS Code** + 完全关闭并重新打开 Visual Studio Code 以应用更改。 + +5. **验证配置** + 在 VS Code 中打开新的 Fish 终端。Shell 集成功能（如命令装饰、更便捷的命令历史导航等）应已激活。你可以通过运行简单命令（如 `echo "Hello from integrated Fish!"`）测试基本功能。 + Fish Cygwin 集成示例 + +此配置在使用 Cygwin、Fish 和 Starship 提示符的 Windows 系统上运行稳定，适用于类似环境的用户。 + +### VSCode 1.98 之后 Shell 集成失败问题 + +**问题描述**：在将 VSCode 更新到 1.98 版本之后，Shell 集成功能可能会失效，并显示错误信息 "VSCE output start escape sequence (]633;C or ]133;C) not received"。 + +**解决方案**： +1. **设置终端命令延迟** + - 在 Kilo Code 设置中将终端命令延迟（Terminal Command Delay）设为 50ms + - 修改设置后重启所有终端 + - 该设置模拟了旧版本的默认行为，可能会解决问题。不过部分用户反馈设为 0ms 效果更好。这是针对 VSCode 上游问题的临时解决方案 + +2. **回退 VSCode 版本** + - 从 [VSCode 更新页面](https://code.visualstudio.com/updates/v1_98) 下载 VSCode v1.98 版本 + - 替换当前的 VSCode 安装 + - 无需备份 Kilo 设置 + +3. **WSL 专用解决方案** + - 如果使用 WSL，请确保通过 `code .` 命令从 WSL 内部启动 VSCode + +4. **ZSH 用户** + - 尝试在 Kilo Code 设置中启用部分或全部与 ZSH 相关的解决方案 + - 无论使用何种操作系统，这些设置都可能有所帮助 + +## 已知问题与解决方法 + +### Ctrl+C 行为问题 + +**问题描述**：当 Kilo Code 尝试在终端中执行命令时，如果终端中已有输入的文本，Kilo Code 会先按下 Ctrl+C 清除当前行，这可能会中断正在运行的进程。 + +**解决方法**：在让 Kilo Code 执行终端命令之前，确保终端提示符为空（没有输入任何部分命令）。 + +### 多行命令问题 + +**问题描述**：跨越多行的命令可能会让 Kilo Code 产生混淆，导致当前命令的输出中混入之前命令的输出。 + +**解决方法**：避免使用多行命令，而是使用 `&&` 进行命令链，将所有操作放在同一行（例如，使用 `echo a && echo b` 代替分行输入每个命令）。 + +### PowerShell 特定问题 + +1. **过早完成**：PowerShell 有时会在命令输出全部显示之前就告诉 Kilo Code 命令已完成。 +2. **重复命令拒绝执行**：PowerShell 可能会拒绝连续两次执行相同的命令。 + +**解决方法**：启用 "PowerShell counter workaround" 设置，并在设置中将终端命令延迟（Terminal Command Delay）设为 150ms，以给命令更多的执行时间。 + +### 终端输出不完整 + +**问题描述**：有时 VS Code 不会显示或捕获命令的全部输出。 + +**解决方法**：如果发现输出缺失，尝试关闭并重新打开终端标签，然后再次运行命令。这会刷新终端连接。 + +## 故障排除资源 + +### 查看调试日志 +当发生 shell 集成问题时，检查调试日志： +1. 打开 "帮助" → "切换开发者工具" → "控制台" +2. 设置 "显示所有级别" 以查看所有日志消息 +3. 查找包含 `[Terminal Process]` 的消息 +4. 检查错误消息中的 `preOutput` 内容： + - 空的 preOutput (`''`) 表示 VSCode 没有发送任何数据 + - 这可能表示存在 VSCode shell 集成问题，或无法控制的上游错误 + - 缺少 shell 集成标记可能需要调整设置，以解决可能的上游错误或与 shell 初始化和 VSCode 加载特殊 shell 集成钩子相关的本地工作站配置问题 + +### 使用 VSCode 终端集成测试扩展 + +[VSCode 终端集成测试扩展](https://github.com/KJ7LNW/vsce-test-terminal-integration) 可以通过测试不同的设置组合来帮助诊断 shell 集成问题： + +1. **命令停滞时**： + - 如果你看到 "command already running" 警告，点击 "Reset Stats" 重置终端状态 + - 这些警告表明 shell 集成未正常工作 + - 尝试不同的设置组合，直到找到有效的配置 + - 如果终端确实卡住了，通过关闭窗口并按 F5 重启扩展 + +2. **测试设置**： + - 系统地尝试不同的组合： + * 终端命令延迟（Terminal Command Delay） + * Shell 集成设置 + - 记录哪些组合成功或失败 + - 这有助于识别 shell 集成问题的模式 + +3. **报告问题**： + - 一旦发现有问题的配置 + - 记录确切的设置组合 + - 记录你的环境信息（操作系统、VSCode 版本、shell 类型以及任何 shell 提示符自定义设置） + - 使用这些详细信息创建一个问题，以帮助改进 shell 集成 + +## 支持 + +如果你已按照上述步骤操作但仍然遇到问题，请： + +1. 查看 [Kilo Code GitHub 问题](https://github.com/Kilo-Org/kilocode/issues)，看是否有其他用户报告过类似问题 +2. 如果没有，请创建一个新问题，详细说明你的操作系统、VSCode/Cursor 版本以及你尝试过的步骤 + +如需更多帮助，请加入我们的 [Discord](https://kilocode.ai/discord)。 \ No newline at end of file diff --git a/docs/zh-CN/features/suggested-responses.md b/docs/zh-CN/features/suggested-responses.md new file mode 100644 index 0000000..2f51047 --- /dev/null +++ b/docs/zh-CN/features/suggested-responses.md @@ -0,0 +1,45 @@ +--- +sidebar_label: 建议响应 +--- + +import Codicon from '@site/src/components/Codicon'; + +# 建议响应 + +当 Kilo Code 需要更多信息来完成任务时，它会使用 [`ask_followup_question` 工具](/features/tools/ask-followup-question)。为了更轻松、更快速地响应，Kilo Code 通常会提供建议答案。 + +## 概述 + +建议响应以可点击按钮的形式出现在 Kilo Code 问题下方的聊天界面中。它们提供了与问题相关的预制答案，帮助你快速提供输入。 + +Kilo Code 提问并附有建议响应按钮的示例 + +## 工作原理 + +1. **问题出现**：Kilo Code 使用 `ask_followup_question` 工具提问。 +2. **显示建议**：如果 Kilo Code 提供了建议，它们会以按钮的形式出现在问题下方。 +3. **交互**：你可以通过两种方式与这些建议进行交互。 + +## 与建议交互 + +你有两种使用建议响应的选项： + +1. **直接选择**： + * **操作**：只需点击包含你想要提供的答案的按钮。 + * **结果**：选定的答案会立即作为你的响应发送回 Kilo Code。如果某个建议完全符合你的意图，这是最快的回复方式。 + +2. **发送前编辑**： + * **操作**： + * 按住 `Shift` 并点击建议按钮。 + * *或者*，将鼠标悬停在建议按钮上，点击出现的铅笔图标（）。 + * **结果**：建议的文本会复制到聊天输入框中。然后你可以根据需要修改文本，然后按下 Enter 键发送自定义的响应。当建议接近但需要稍作调整时，这很有用。 + +聊天输入框显示从建议响应复制的文本，准备编辑 + +## 优势 + +* **速度**：无需输入完整答案即可快速响应。 +* **清晰度**：建议通常阐明了 Kilo Code 所需的信息类型。 +* **灵活性**：在需要时编辑建议以提供精确、自定义的答案。 + +此功能在 Kilo Code 需要澄清时简化了交互，让你能够以最少的努力有效地指导任务。 \ No newline at end of file diff --git a/docs/zh-CN/features/tools/access-mcp-resource.md b/docs/zh-CN/features/tools/access-mcp-resource.md new file mode 100644 index 0000000..89e0731 --- /dev/null +++ b/docs/zh-CN/features/tools/access-mcp-resource.md @@ -0,0 +1,126 @@ +# access_mcp_resource + +`access_mcp_resource` 工具用于从连接的 Model Context Protocol (MCP) 服务器中检索资源数据。它允许 Kilo Code 访问文件、API 响应、文档或系统信息，为任务提供额外的上下文。 + +## 参数 + +该工具接受以下参数： + +- `server_name` (必填): 提供资源的 MCP 服务器名称 +- `uri` (必填): 标识要访问的特定资源的 URI + +## 功能 + +该工具连接到 MCP 服务器并从其暴露的资源中获取数据。与 `use_mcp_tool` 执行操作不同，该工具专门检索为任务提供上下文的信息。 + +## 使用场景 + +- 当 Kilo Code 需要从外部系统获取额外上下文时 +- 当 Kilo Code 需要从专门的 MCP 服务器访问领域特定数据时 +- 当 Kilo Code 需要检索由 MCP 服务器托管的参考文档时 +- 当 Kilo Code 需要通过 MCP 从外部 API 集成实时数据时 + +## 主要特性 + +- 从 MCP 资源中检索文本和图像数据 +- 在执行资源访问前需要用户批准 +- 使用基于 URI 的寻址来精确定位资源 +- 与 Model Context Protocol SDK 集成 +- 根据内容类型适当显示资源内容 +- 支持超时以确保网络操作的可靠性 +- 处理服务器连接状态（已连接、连接中、断开连接） +- 发现来自连接服务器的可用资源 +- 处理带有元数据的结构化响应数据 +- 特殊处理图像内容的渲染 + +## 限制 + +- 依赖于外部 MCP 服务器的可用性和连接性 +- 仅限于连接服务器提供的资源 +- 无法访问已禁用服务器的资源 +- 网络问题可能影响可靠性和性能 +- 资源访问受配置的超时限制 +- URI 格式由特定的 MCP 服务器实现决定 +- 没有离线或缓存的资源访问能力 + +## 工作原理 + +当调用 `access_mcp_resource` 工具时，它会遵循以下流程： + +1. **连接验证**: + - 验证 MCP 中心是否可用且已初始化 + - 确认指定的服务器存在于连接列表中 + - 检查服务器是否被禁用（如果被禁用则返回错误） + +2. **用户批准**: + - 向用户呈现资源访问请求以获取批准 + - 提供服务器名称和资源 URI 以供用户验证 + - 仅在用户批准资源访问后继续 + +3. **资源请求**: + - 使用 Model Context Protocol SDK 与服务器通信 + - 通过 MCP 中心向服务器发出 `resources/read` 请求 + - 应用配置的超时以防止服务器无响应时挂起 + +4. **响应处理**: + - 接收带有元数据和内容数组的结构化响应 + - 处理文本内容以供用户显示 + - 特殊处理图像数据以适当显示 + - 将处理后的资源数据返回给 Kilo Code 以用于当前任务 + +## 资源类型 + +MCP 服务器可以提供两种主要类型的资源： + +1. **标准资源**: + - 具有特定 URI 的固定资源 + - 定义名称、描述和 MIME 类型 + - 无需参数的直接访问 + - 通常表示静态数据或实时信息 + +2. **资源模板**: + - 具有 URI 中占位符值的参数化资源 + - 允许基于提供的参数动态生成资源 + - 可以表示查询或数据过滤视图 + - 更灵活但需要额外的 URI 格式化 + +## 使用示例 + +- 在帮助开发 API 时，Kilo Code 从 MCP 资源中检索端点规范以确保正确实现。 +- 在协助数据可视化时，Kilo Code 从连接的 MCP 服务器访问当前数据样本。 +- 在特定领域工作时，Kilo Code 检索技术文档以提供准确的指导。 +- 在生成行业特定代码时，Kilo Code 参考文档中的合规要求。 + +## 使用示例 + +访问当前的天气数据： +``` + +weather-server +weather://san-francisco/current + +``` + +检索 API 文档： +``` + +api-docs +docs://payment-service/endpoints + +``` + +访问领域特定知识： +``` + +knowledge-base +kb://medical/terminology/common + +``` + +获取系统配置： +``` + +infra-monitor +config://production/database + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/apply-diff.md b/docs/zh-CN/features/tools/apply-diff.md new file mode 100644 index 0000000..42bc305 --- /dev/null +++ b/docs/zh-CN/features/tools/apply-diff.md @@ -0,0 +1,98 @@ +# apply_diff + +`apply_diff`工具通过指定要替换的确切内容，对文件进行精确的修改。它使用多种复杂策略来查找和应用更改，同时保持正确的代码格式和结构。 + +## 参数 + +该工具接受以下参数： + +- `path`（必填）：要修改的文件路径，相对于当前工作目录。 +- `diff`（必填）：使用特定于活动diff策略的格式定义更改的搜索/替换块。 +- `start_line`（可选）：搜索内容开始的提示，某些策略会使用。 +- `end_line`（可选）：搜索内容结束的提示，某些策略会使用。 + +## 功能 + +该工具使用复杂的策略对现有文件进行有针对性的更改，以精确定位和替换内容。与简单的搜索和替换不同，它使用智能匹配算法（包括模糊匹配），能够适应不同的内容类型和文件大小，并为复杂编辑提供回退机制。 + +## 使用场景 + +- 当Kilo Code需要对现有代码进行精确更改而不重写整个文件时。 +- 在重构代码的特定部分同时保持周围上下文时。 +- 以手术般的精度修复现有代码中的错误时。 +- 实现仅修改文件某些部分的功能增强时。 + +## 主要特性 + +- 使用可配置置信度阈值（通常为0.8-1.0）的智能模糊匹配。 +- 使用`BUFFER_LINES`（默认40）提供匹配的上下文。 +- 采用重叠窗口方法搜索大文件。 +- 自动保留代码格式和缩进。 +- 组合重叠匹配以提高置信度评分。 +- 在应用更改前，在diff视图中显示更改以供用户审查和编辑。 +- 跟踪每个文件的连续错误（`consecutiveMistakeCountForApplyDiff`）以防止重复失败。 +- 根据`.kilocodeignore`规则验证文件访问权限。 +- 有效处理多行编辑。 + +## 限制 + +- 对于独特、独特的代码部分效果最佳，以便可靠识别。 +- 对于非常大的文件或高度重复的代码模式，性能可能会有所不同。 +- 如果内容不明确，模糊匹配可能会偶尔选择错误的位置。 +- 每个diff策略都有特定的格式要求。 +- 复杂的编辑可能需要仔细选择策略或手动审查。 + +## 工作原理 + +当调用`apply_diff`工具时，它会遵循以下过程： + +1. **参数验证**：验证必需的`path`和`diff`参数。 +2. **KiloCodeIgnore检查**：验证目标文件路径是否被`.kilocodeignore`规则允许。 +3. **文件分析**：加载目标文件内容。 +4. **匹配查找**：使用所选策略的算法（精确、模糊、重叠窗口）定位目标内容，考虑置信度阈值和上下文（`BUFFER_LINES`）。 +5. **更改准备**：生成建议的更改，保留缩进。 +6. **用户交互**： + * 在diff视图中显示更改。 + * 允许用户审查并可能编辑建议的更改。 + * 等待用户批准或拒绝。 +7. **更改应用**：如果获得批准，将更改（可能包括用户编辑）应用到文件。 +8. **错误处理**：如果发生错误（例如，匹配失败、部分应用），则递增文件的`consecutiveMistakeCountForApplyDiff`并报告失败类型。 +9. **反馈**：返回结果，包括任何用户反馈或错误详细信息。 + +## Diff策略 + +Kilo Code使用以下策略来应用diff： + +### MultiSearchReplaceDiffStrategy + +一种增强的搜索/替换格式，支持在一个请求中进行多次更改。需要每个搜索块的行号。 + +* **最佳使用场景**：已知或可以估计行号的多个不同更改。 +* **要求**：`SEARCH`块内容的精确匹配，包括空格和缩进。行号（`:start_line:`，`:end_line:`）是必需的。内容中的标记必须转义（`\`）。 + +``块的示例格式： + +```diff +<<<<<<< SEARCH +:start_line:10 +:end_line:12 +------- + // Old calculation logic + const result = value * 0.9; + return result; +======= + // Updated calculation logic with logging + console.log(`Calculating for value: ${value}`); + const result = value * 0.95; // Adjusted factor + return result; +>>>>>>> REPLACE + +<<<<<<< SEARCH +:start_line:25 +:end_line:25 +------- + const defaultTimeout = 5000; +======= + const defaultTimeout = 10000; // Increased timeout +>>>>>>> REPLACE +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/ask-followup-question.md b/docs/zh-CN/features/tools/ask-followup-question.md new file mode 100644 index 0000000..c9f9300 --- /dev/null +++ b/docs/zh-CN/features/tools/ask-followup-question.md @@ -0,0 +1,168 @@ +# ask_followup_question + +`ask_followup_question` 工具通过提出具体问题来收集完成任务所需的额外信息，从而实现交互式沟通。 + +## 参数 + +该工具接受以下参数： + +- `question` (必填): 向用户提出的具体问题 +- `follow_up` (可选): 包含 2-4 个建议答案的列表，帮助引导用户回答，每个建议用 `` 标签包裹 + +## 功能 + +该工具在 Kilo Code 和用户之间创建了一个对话界面，当遇到模糊不清或决策点时，可以用于收集澄清信息、额外细节或用户偏好。每个问题可以包含建议的响应，以简化交互。 + +## 使用场景 + +- 当原始请求中缺少关键信息时 +- 当 Kilo Code 需要在多个有效的实现方法之间做出选择时 +- 当需要技术细节或偏好才能继续时 +- 当 Kilo Code 遇到需要解决的模糊不清的情况时 +- 当额外的上下文会显著提高解决方案质量时 + +## 主要特性 + +- 提供结构化的方式来收集特定信息，而不会中断工作流程 +- 包含建议答案以减少用户输入并引导响应 +- 在交互过程中维护对话历史和上下文 +- 支持包含图片和代码片段的响应 +- 在所有模式下都可用，作为"始终可用"的工具集的一部分 +- 支持用户直接指导实现决策 +- 使用 `` 标签格式化响应，以区分常规对话 +- 成功使用时重置连续错误计数器 + +## 限制 + +- 每次工具使用仅限于提出一个具体问题 +- 在 UI 中将建议作为可选项呈现 +- 不能强制结构化响应 - 用户仍然可以自由响应 +- 过度使用可能会减慢任务完成速度并造成碎片化体验 +- 建议答案必须完整，不能包含需要用户编辑的占位符 +- 没有内置的用户响应验证机制 +- 没有强制特定答案格式的机制 + +## 工作原理 + +当调用 `ask_followup_question` 工具时，它会遵循以下流程： + +1. **参数验证**: 验证必需的 `question` 参数并检查可选建议 + - 确保提供了问题文本 + - 使用 `fast-xml-parser` 库从 `follow_up` 参数中解析任何建议答案 + - 即使只有一个建议，也将建议规范化为数组格式 + +2. **JSON 转换**: 将 XML 结构转换为标准化的 JSON 格式以供 UI 显示 + ```typescript + { + question: "用户的问题在这里", + suggest: [ + { answer: "建议 1" }, + { answer: "建议 2" } + ] + } + ``` + +3. **UI 集成**: + - 通过 `ask("followup", ...)` 方法将 JSON 结构传递给 UI 层 + - 在界面中向用户显示可选的建议按钮 + - 创建选择或输入响应的交互式体验 + +4. **响应收集与处理**: + - 捕获用户文本输入和响应中包含的任何图片 + - 在返回给助手时用 `` 标签包裹用户响应 + - 保留用户响应中包含的任何图片 + - 通过将响应添加到历史记录中来维护对话上下文 + - 在工具成功使用时重置连续错误计数器 + +5. **错误处理**: + - 使用计数器跟踪连续错误 + - 在工具成功使用时重置计数器 + - 提供特定的错误消息： + - 对于缺少参数："缺少必需的参数 'question'" + - 对于 XML 解析："无法解析操作：[错误消息]" + - 对于无效格式："操作 xml 格式无效" + - 包含防止在缺少必需参数时执行工具的安全措施 + - 发生错误时增加连续错误计数 + +## 工作流程 + +问题-回答周期遵循以下顺序： + +1. **信息差距识别**: Kilo Code 识别出继续所需缺少的信息 +2. **具体问题创建**: Kilo Code 形成一个明确的、有针对性的问题 +3. **建议开发**: Kilo Code 创建相关的建议答案（可选但推荐） +4. **工具调用**: 助手使用问题和可选建议调用工具 +5. **UI 呈现**: 问题和建议作为交互元素显示给用户 +6. **用户响应**: 用户选择建议或提供自定义答案 +7. **消息处理**: 系统处理部分和完整的消息 + - 对于流式响应，在到达时处理每个块 + - 对于完整消息，一次性处理整个响应 + - 无论消息分块如何，都保持状态一致性 +8. **响应处理**: 系统用 `` 标签包裹响应并保留图片 +9. **上下文集成**: 响应被添加到对话历史中 +10. **任务继续**: Kilo Code 使用新信息继续任务 + +## 使用示例 + +- 在开发 Web 应用程序时，Kilo Code 可能会询问首选的样式框架（Bootstrap、Tailwind、自定义 CSS） +- 在创建 API 时，Kilo Code 可能会询问认证方法（JWT、OAuth、API 密钥） +- 在重构代码时，Kilo Code 可能会询问是优先考虑性能还是可读性 +- 在设置数据库时，Kilo Code 可能会询问特定的模式设计偏好 +- 在创建自定义功能时，Kilo Code 可能会询问特定的行为期望 +- 在排查错误时，Kilo Code 可能会询问特定的环境细节 + +## 响应格式 + +当用户回答问题时，响应会用 `` 标签进行格式化，以提高清晰度和一致性。这种格式有助于将用户的回答与其他对话元素明确区分开来。 + +示例响应格式： +``` + +使用 Tailwind CSS 进行实用优先的样式设计，具有最大的灵活性 + +``` + +响应格式的关键特征： +- 用 `` 标签包裹 +- 保留原始响应的格式 +- 如果响应中包含图片，则保留图片 +- 返回完整文本，即使是长响应 + +## 使用示例 + +询问实现偏好： +``` + +你希望这个 Web 应用程序采用哪种样式方法？ + +使用 Bootstrap 进行快速开发，具有一致的组件 +使用 Tailwind CSS 进行实用优先的样式设计，具有最大的灵活性 +使用自定义样式的原生 CSS，以获得完全控制和最小依赖 + + +``` + +请求技术澄清： +``` + +这个应用程序应该使用什么数据库来存储用户数据？ + +MongoDB 用于灵活的模式和基于文档的存储 +PostgreSQL 用于具有强一致性保证的关系数据 +Firebase 用于实时更新和简化的后端管理 +SQLite 用于轻量级本地存储，无需外部依赖 + + +``` + +解决需求中的模糊性： +``` + +应用程序应如何处理用户认证？ + +实施带账户验证的电子邮件/密码认证 +使用社交登录提供商（Google、GitHub 等）快速注册 +同时实施电子邮件/密码和社交登录选项 + + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/attempt-completion.md b/docs/zh-CN/features/tools/attempt-completion.md new file mode 100644 index 0000000..478bab2 --- /dev/null +++ b/docs/zh-CN/features/tools/attempt-completion.md @@ -0,0 +1,174 @@ +# attempt_completion + +`attempt_completion` 工具用于标记 Kilo Code 认为任务已完成并向用户展示结果。它提供了任务完成的摘要，可选地包括一个用于展示结果的命令，并支持通过用户反馈进行进一步优化。 + +## 参数 + +该工具接受以下参数： + +- `result` (必填): 最终结果描述，总结已完成的工作 +- `command` (可选): 用于展示结果的 CLI 命令 + +## 功能 + +该工具通过提供最终摘要来标记任务的结束。它向用户和系统发出信号，表明当前任务已完成。当提供命令时，它还可以通过实时执行来展示结果。 + +## 使用场景 + +- 当 Kilo Code 认为用户的任务已完成时 +- 当总结所做更改或改进时 +- 当使用命令执行展示当前结果时 +- 当为用户反馈提供解决方案的检查点时 +- 当从工作阶段过渡到可能的优化时 + +## 主要特性 + +- 提供明确的信号表明 Kilo Code 认为任务已完成 +- 以简洁的消息总结完成的工作 +- 可选地通过命令执行展示结果 +- 支持用户反馈以进行进一步优化 +- 以不同于常规消息的特殊 UI 格式显示结果 +- 捕获任务完成遥测数据用于系统分析 +- 通过提供检查点维护结构化的对话流程 +- 支持在较大工作流中的子任务完成 +- 确保用户收到关于已完成工作的清晰摘要 +- 在所有模式下都可用，作为"始终可用"工具组的一部分 + +## 限制 + +- 在确认之前的工具使用成功之前不应使用（指南，非强制） +- 仅限于单个命令来展示结果 +- 无法提供多个命令选项 +- 命令在执行前需要用户批准 +- 仅限于通过 CLI 命令展示结果 +- 不能用于部分任务完成或进度更新 +- 结果格式会通过内部处理移除 XML 闭合标签 + +## 工作原理 + +当调用 `attempt_completion` 工具时，它会遵循以下流程： + +1. **安全考虑**（指南，非强制）： + - AI 被指示确认之前的工具使用是否成功 + - 这是一个最佳实践，而不是程序化强制机制 + +2. **结果展示**： + - 以特殊的 "completion_result" UI 格式向用户显示完成消息 + - 使用 `removeClosingTag` 函数从结果文本中移除 XML 闭合标签 + - 以不同于常规消息的方式呈现结果，以实现视觉区分 + +3. **命令执行**（如果提供）： + - 在执行前请求用户批准 + - 仅在用户批准后执行 + - 使用系统的命令执行功能执行命令 + - 向用户展示命令结果 + +4. **反馈收集**： + - 等待用户对完成结果的反馈 + - 处理此反馈并将其返回给 AI + - 支持基于用户输入的持续优化 + +5. **任务完成与继续**： + - 在系统中标记任务为已完成 + - 捕获已完成任务的遥测数据 + - 对于子任务，提供完成子任务并恢复父任务的选项 + - 通过反馈机制支持继续对话 + +6. **实现集成**： + - 工具结果通过系统的解析机制在 `parse-assistant-message.ts` 中处理 + - 该工具是 "ALWAYS_AVAILABLE_TOOLS" 常量的一部分，使其在所有模式下都可用 + +## 结果格式指南 + +结果消息应遵循以下指南： + +- 清晰地传达已完成的工作 +- 简洁但完整 +- 专注于为用户提供的价值 +- 避免不必要的客套或填充文本 +- 保持专业、直接的语气 +- 以易于浏览和理解的方式呈现信息 +- 确认用户可能会提供反馈以进行进一步优化 + +注意：系统会通过 `removeClosingTag` 函数自动从结果文本中移除 XML 闭合标签。 + +## 命令选择指南 + +包含命令时，请遵循以下指南： + +- 选择能直观展示结果的命令 +- 优先选择能展示用户创建或修改内容的命令 +- 示例包括： + * `open index.html` 展示创建的网站 + * `npm start` 启动开发服务器 + * `python app.py` 运行创建的应用程序 +- 避免仅打印文本的命令（如 `echo` 或 `cat`） +- 记住命令在执行前需要用户批准 +- 确保命令适用于用户的操作系统 + +## 反馈与 UI 表示 + +`attempt_completion` 工具具有独特的反馈机制： + +- 结果以特殊的 "completion_result" UI 格式显示，不同于常规消息 +- 系统在呈现结果后等待用户反馈 +- 反馈被处理并返回给 Kilo Code 以进行进一步优化 +- 这创建了一个迭代改进周期，而不是结束对话 +- UI 包含用于提供反馈的特殊元素 +- 结果作为对话流程中的明确检查点 + +用于子任务时： +- 系统提供完成子任务并恢复父任务的选项 +- 如果批准，子任务将以摘要完成 +- 父任务在完成子任务的上下文中恢复 +- 这支持复杂、嵌套的工作流，同时保持上下文 + +## 使用示例 + +- 当创建网站时，Kilo Code 展示解决方案并使用 `open index.html` 展示结果。用户提供反馈，Kilo Code 优化设计。 +- 当实现功能时，Kilo Code 总结更改及其影响。用户请求额外的测试覆盖，Kilo Code 继续任务。 +- 当修复错误时，Kilo Code 解释修复内容以及解决方案如何解决根本原因。用户确认修复有效。 +- 当设置开发环境时，Kilo Code 确认所有组件已安装。用户请求额外配置，Kilo Code 继续。 +- 当创建数据处理脚本时，Kilo Code 总结功能。用户建议性能优化，Kilo Code 优化代码。 + +## 使用示例 + +仅使用结果摘要完成任务： +``` + + +我已更新导航栏的 CSS 以匹配设计稿。更改包括： +1. 更新配色方案以使用新的品牌颜色 +2. 为移动设备添加了响应式行为 +3. 修复了下拉菜单中的对齐问题 + + +``` + +使用结果和演示命令完成任务： +``` + + +我创建了一个简单的 React 应用程序，包含以下功能： +1. 具有请求的英雄部分的响应式落地页 +2. 带有验证的工作联系表单 +3. 在请求的三个页面之间导航 +4. 匹配提供的设计稿的样式 + +npm start + +``` + +完成 Python 脚本任务并执行： +``` + + +我创建了一个数据处理脚本，它： +1. 从数据目录读取 CSV 文件 +2. 按要求清理和规范化数据 +3. 以 JSON 格式生成汇总统计 +4. 将处理后的数据输出到输出目录 + +python process_data.py + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/browser-action.md b/docs/zh-CN/features/tools/browser-action.md new file mode 100644 index 0000000..0913d6f --- /dev/null +++ b/docs/zh-CN/features/tools/browser-action.md @@ -0,0 +1,158 @@ +# browser_action + +`browser_action`工具通过Puppeteer控制的浏览器实现网页自动化交互。它允许Kilo Code启动浏览器、导航至网站、点击元素、输入文本、滚动页面，并通过截图提供可视化反馈。 + +> **⚠️ 安全警告** +> 使用此工具时请注意： +> - 确保访问的网站安全可靠 +> - 避免在浏览器中执行未经验证的操作 +> - 谨慎处理敏感信息 + +## 参数 + +该工具接受以下参数： + +- `action` (必填): 要执行的操作： + * `launch`: 在指定URL启动新浏览器会话 + * `click`: 在特定x,y坐标处点击 + * `type`: 通过键盘输入文本 + * `scroll_down`: 向下滚动一页高度 + * `scroll_up`: 向上滚动一页高度 + * `close`: 结束浏览器会话 +- `url` (可选): 使用`launch`操作时要导航的URL +- `coordinate` (可选): `click`操作的x,y坐标（例如"450,300"） +- `text` (可选): 使用`type`操作时要输入的文本 + +## 功能 + +该工具创建一个自动化浏览器会话，Kilo Code可以通过它来导航网站、与元素交互，并执行需要浏览器自动化的任务。每个操作都会提供当前状态的截图，以便进行可视化验证。 + +## 使用场景 + +- 当Kilo Code需要与Web应用程序或网站交互时 +- 当测试用户界面或Web功能时 +- 当捕获网页截图时 +- 当演示Web工作流程时 + +## 主要特性 + +- 提供操作后的截图作为可视化反馈，并捕获控制台日志 +- 支持从启动到页面交互再到关闭的完整工作流程 +- 通过坐标、键盘输入和滚动实现精确交互 +- 通过智能页面加载检测保持一致的浏览器会话 +- 支持两种模式：本地（独立Puppeteer实例）或远程（连接现有Chrome） +- 通过自动会话清理和详细消息优雅处理错误 +- 支持多种格式和质量设置的视觉输出优化 +- 通过位置指示器和操作历史跟踪交互状态 + +## 浏览器模式 + +该工具支持两种模式： + +### 本地浏览器模式（默认） +- 通过Puppeteer下载并管理本地Chromium实例 +- 每次启动时创建全新的浏览器环境 +- 无法访问现有用户配置文件、cookies或扩展程序 +- 在沙箱环境中保持行为一致且可预测 +- 会话结束时完全关闭浏览器 + +### 远程浏览器模式 +- 连接到已启用远程调试的现有Chrome/Chromium实例 +- 可以访问现有浏览器状态、cookies，可能还包括扩展程序 +- 由于重用现有浏览器进程，启动速度更快 +- 支持连接到Docker容器或远程机器上的浏览器 +- 会话结束时仅断开连接（不关闭浏览器） +- 需要Chrome以远程调试端口运行（通常为9222端口） + +## 限制 + +- 浏览器活动时，只能使用`browser_action`工具 +- 浏览器坐标是相对于视口的，而不是页面 +- 点击操作必须针对视口内的可见元素 +- 在使用其他工具之前必须显式关闭浏览器会话 +- 浏览器窗口有可配置的尺寸（默认900x600） +- 无法直接与浏览器DevTools交互 +- 浏览器会话是临时的，在Kilo Code重启时不会保留 +- 仅支持Chrome/Chromium浏览器，不支持Firefox或Safari +- 本地模式无法访问现有cookies；远程模式需要启用调试的Chrome + +## 工作原理 + +当调用`browser_action`工具时，它会遵循以下流程： + +1. **操作验证和浏览器管理**： + - 验证请求操作所需的参数 + - 对于`launch`：初始化浏览器会话（本地Puppeteer实例或远程Chrome） + - 对于交互操作：使用现有浏览器会话 + - 对于`close`：适当地终止或断开浏览器连接 + +2. **页面交互和稳定性**： + - 使用`waitTillHTMLStable`算法通过DOM稳定性检测确保页面完全加载 + - 以适当的时间执行请求的操作（导航、点击、输入、滚动） + - 监控点击后的网络活动，并在必要时等待导航 + +3. **可视化反馈**： + - 使用WebP格式（支持PNG回退）捕获优化截图 + - 记录浏览器控制台日志以进行调试 + - 跟踪鼠标位置并维护分页操作历史 + +4. **会话管理**： + - 跨多个操作维护浏览器状态 + - 处理错误并自动清理资源 + - 强制执行正确的工作流程顺序（启动→交互→关闭） + +## 工作流程顺序 + +浏览器交互必须遵循以下特定顺序： + +1. **会话初始化**：所有浏览器工作流程必须以`launch`操作开始 +2. **交互阶段**：可以执行多个`click`、`type`和滚动操作 +3. **会话终止**：所有浏览器工作流程必须以`close`操作结束 +4. **工具切换**：关闭浏览器后，可以使用其他工具 + +## 使用示例 + +- 当创建Web表单提交过程时，Kilo Code启动浏览器，导航到表单，使用`type`操作填写字段，并点击提交。 +- 当测试响应式网站时，Kilo Code导航到网站并使用滚动操作检查不同部分。 +- 当捕获Web应用程序的截图时，Kilo Code导航到不同页面并在每一步截图。 +- 当演示电商结账流程时，Kilo Code模拟从产品选择到支付确认的整个过程。 + +## 使用示例 + +启动浏览器并导航到网站： +``` + +launch +https://example.com + +``` + +在特定坐标处点击（例如按钮）： +``` + +click +450,300 + +``` + +在聚焦的输入字段中输入文本： +``` + +type +Hello, World! + +``` + +向下滚动以查看更多内容： +``` + +scroll_down + +``` + +关闭浏览器会话： +``` + +close + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/execute-command.md b/docs/zh-CN/features/tools/execute-command.md new file mode 100644 index 0000000..4331376 --- /dev/null +++ b/docs/zh-CN/features/tools/execute-command.md @@ -0,0 +1,153 @@ +# execute_command + +`execute_command`工具用于在用户系统上执行CLI命令。它允许Kilo Code执行系统操作、安装依赖、构建项目、启动服务器以及执行其他基于终端的任务，以实现用户目标。 + +## 参数 + +该工具接受以下参数： + +- `command`（必填）：要执行的CLI命令。必须对用户的操作系统有效。 +- `cwd`（可选）：执行命令的工作目录。如果未提供，则使用当前工作目录。 + +## 功能 + +该工具直接在用户系统上执行终端命令，支持从文件操作到运行开发服务器等多种操作。命令在托管的终端实例中运行，并实时捕获输出，与VS Code的终端系统集成，以实现最佳性能和安全性。 + +## 使用场景 + +- 安装项目依赖（npm install, pip install等） +- 构建或编译代码（make, npm run build等） +- 启动开发服务器或运行应用程序 +- 初始化新项目（git init, npm init等） +- 执行超出其他工具功能的文件操作 +- 运行测试或lint操作 +- 需要为特定技术执行专用命令 + +## 关键特性 + +- 与VS Code shell API集成，实现可靠的终端执行 +- 通过注册表系统尽可能重用终端实例 +- 实时捕获命令输出 +- 支持在后台持续运行的长时间命令 +- 允许指定自定义工作目录 +- 跨命令执行维护终端历史记录和状态 +- 处理适合用户shell的复杂命令链 +- 提供详细的命令完成状态和退出代码解释 +- 支持需要用户反馈的交互式终端应用 +- 执行期间显示终端以确保透明度 +- 使用shell-quote解析验证命令安全性 +- 阻止潜在危险的子shell执行模式 +- 与KiloCodeIgnore系统集成，控制文件访问权限 +- 处理终端转义序列以保持输出整洁 + +## 限制 + +- 命令访问可能受KiloCodeIgnore规则和安全验证限制 +- 需要提升权限的命令可能需要用户配置 +- 某些命令的行为可能因操作系统而异 +- 长时间运行的命令可能需要特殊处理 +- 文件路径应根据OS shell规则正确转义 +- 在远程开发场景中，并非所有终端功能都可用 + +## 工作原理 + +当调用`execute_command`工具时，它遵循以下流程： + +1. **命令验证和安全检查**： + - 使用shell-quote解析命令以识别组件 + - 根据安全限制（子shell使用、受限文件）进行验证 + - 检查KiloCodeIgnore规则以确定文件访问权限 + - 确保命令符合系统安全要求 + +2. **终端管理**： + - 通过TerminalRegistry获取或创建终端 + - 设置工作目录上下文 + - 准备输出捕获的事件监听器 + - 显示终端以便用户可见 + +3. **命令执行和监控**： + - 通过VS Code的shellIntegration API执行 + - 捕获并处理转义序列的输出 + - 限制输出处理间隔（100ms） + - 监控命令完成或错误 + - 检测"热"进程（如编译器）以进行特殊处理 + +4. **结果处理**： + - 去除ANSI/VS Code转义序列以保持输出整洁 + - 解释退出代码并提供详细的信号信息 + - 如果命令改变了工作目录，则更新跟踪 + - 提供带有适当上下文的命令状态 + +## 终端实现细节 + +该工具使用复杂的终端管理系统： + +1. **优先复用终端**： + - TerminalRegistry尽可能复用现有终端 + - 减少终端实例数量并提高性能 + - 跨命令执行保留终端状态（工作目录、历史记录） + +2. **安全验证**： + - 使用shell-quote解析命令以进行组件分析 + - 阻止`$(...)`和反引号等危险模式 + - 根据KiloCodeIgnore规则检查命令的文件访问控制 + - 使用前缀允许列表系统验证命令模式 + +3. **性能优化**： + - 以100ms节流间隔处理输出，防止UI过载 + - 使用基于索引的零拷贝缓冲区管理以提高效率 + - 对编译和"热"进程进行特殊处理 + - 针对Windows PowerShell进行平台特定优化 + +4. **错误和信号处理**： + - 将退出代码映射到详细的信号信息（SIGTERM, SIGKILL等） + - 检测核心转储以识别关键故障 + - 自动跟踪和处理工作目录变更 + - 从终端断开连接场景中优雅恢复 + +## 使用示例 + +- 设置新项目时，Kilo Code运行初始化命令，如`npm init -y`，然后安装依赖。 +- 构建Web应用时，Kilo Code执行构建命令，如`npm run build`以编译资源。 +- 部署代码时，Kilo Code运行git命令以提交和推送更改到仓库。 +- 故障排除时，Kilo Code执行诊断命令以收集系统信息。 +- 启动开发服务器时，Kilo Code运行适当的服务器命令（如`npm start`）。 +- 运行测试时，Kilo Code执行项目测试框架的测试运行命令。 + +## 用法示例 + +在当前目录中运行简单命令： +``` + +npm run dev + +``` + +安装项目依赖： +``` + +npm install express mongodb mongoose dotenv + +``` + +依次运行多个命令： +``` + +mkdir -p src/components && touch src/components/App.js + +``` + +在特定目录中执行命令： +``` + +git status +./my-project + +``` + +构建并启动项目： +``` + +npm run build && npm start + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/list-code-definition-names.md b/docs/zh-CN/features/tools/list-code-definition-names.md new file mode 100644 index 0000000..f99c0db --- /dev/null +++ b/docs/zh-CN/features/tools/list-code-definition-names.md @@ -0,0 +1,116 @@ +# list_code_definition_names + +`list_code_definition_names` 工具通过列出指定目录顶层源代码文件中的代码定义，为您的代码库提供结构化概览。它通过显示行号和定义片段，帮助 Kilo Code 理解代码架构。 + +## 参数 + +该工具接受以下参数： + +- `path`（必填）：要列出顶层源代码定义的目录路径，相对于当前工作目录 + +## 功能 + +该工具扫描指定目录顶层的源代码文件，并提取类、函数和接口等代码定义。它显示每个定义的行号和实际代码，以便快速映射代码库的重要组件。 + +## 使用场景 + +- 当 Kilo Code 需要快速理解您的代码库架构时 +- 当 Kilo Code 需要定位多个文件中的重要代码结构时 +- 在计划重构或扩展现有代码时 +- 在使用其他工具深入研究实现细节之前 +- 在识别代码库不同部分之间的关系时 + +## 主要特性 + +- 从源代码文件中提取类、函数、方法、接口等定义 +- 显示每个定义的行号和实际源代码 +- 支持多种编程语言，包括 JavaScript、TypeScript、Python、Rust、Go、C++、C、C#、Ruby、Java、PHP、Swift 和 Kotlin +- 仅处理指定目录顶层的文件（不包括子目录） +- 为提升性能，最多处理 50 个文件 +- 专注于顶层定义，避免过多细节 +- 帮助识别项目中的代码组织模式 +- 创建代码库架构的思维导图 +- 与其他工具（如 `read_file`）结合使用，进行更深入的分析 + +## 限制 + +- 仅识别顶层定义，不包括嵌套定义 +- 仅处理指定目录顶层的文件，不包括子目录 +- 每次请求最多处理 50 个文件 +- 依赖于语言特定的解析器，检测质量可能有所不同 +- 对于语法复杂的语言，可能无法识别所有定义 +- 不能替代阅读代码以了解实现细节 +- 无法检测运行时模式或动态代码关系 +- 不提供有关定义使用情况的信息 +- 对于高度动态或元编程的代码，准确性可能降低 +- 仅限于 Tree-sitter 解析器支持的语言 + +## 工作原理 + +当调用 `list_code_definitions_names` 工具时，它会遵循以下流程： + +1. **参数验证**：验证必填的 `path` 参数 +2. **路径解析**：将相对路径解析为绝对路径 +3. **目录扫描**：仅扫描指定目录顶层的源代码文件（非递归） +4. **文件过滤**：最多处理 50 个文件 +5. **语言检测**：根据文件扩展名识别文件类型（.js、.jsx、.ts、.tsx、.py、.rs、.go、.cpp、.hpp、.c、.h、.cs、.rb、.java、.php、.swift、.kt、.kts） +6. **代码解析**：使用 Tree-sitter 解析代码并通过以下步骤提取定义： + - 将文件内容解析为抽象语法树 (AST) + - 使用语言特定的查询字符串创建查询 + - 按文件中的位置对捕获进行排序 +7. **结果格式化**：输出定义及其行号和实际源代码 + +## 输出格式 + +输出显示文件路径，后跟定义的行号和实际源代码。例如： + +``` +src/utils.js: +0--0 | export class HttpClient { +5--5 | formatDate() { +10--10 | function parseConfig(data) { + +src/models/User.js: +0--0 | interface UserProfile { +10--10 | export class User { +20--20 | function createUser(data) { +``` + +每行显示： +- 定义的起始和结束行号 +- 分隔符（|） +- 定义的实际源代码 + +这种输出格式帮助您快速查看定义在文件中的位置及其实现细节。 + +## 使用示例 + +- 当开始新任务时，Kilo Code 首先列出关键代码定义以了解项目的整体结构。 +- 当计划重构工作时，Kilo Code 使用此工具识别可能受影响的类和函数。 +- 在探索不熟悉的代码库时，Kilo Code 在深入研究实现细节之前映射重要代码结构。 +- 当添加新功能时，Kilo Code 识别现有模式和相关的代码定义以保持一致性。 +- 当排查错误时，Kilo Code 映射代码库结构以定位问题的潜在来源。 +- 当计划架构更改时，Kilo Code 识别所有受影响的组件。 + +## 用法示例 + +列出当前目录中的代码定义： +``` + +. + +``` + +检查特定模块的结构： +``` + +src/components + +``` + +探索工具库： +``` + +lib/utils + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/list-files.md b/docs/zh-CN/features/tools/list-files.md new file mode 100644 index 0000000..699079b --- /dev/null +++ b/docs/zh-CN/features/tools/list-files.md @@ -0,0 +1,132 @@ +# list_files + +`list_files` 工具显示指定位置中的文件和目录。它帮助 Kilo Code 理解您的项目结构并有效地导航代码库。 + +## 参数 + +该工具接受以下参数： + +- `path`（必填）：要列出内容的目录路径，相对于当前工作目录 +- `recursive`（可选）：是否递归列出文件。使用 `true` 进行递归列出，`false` 或省略则仅列出顶层内容。 + +## 功能 + +该工具列出指定位置中的所有文件和目录，提供项目结构的清晰概览。它可以仅显示顶层内容，也可以递归探索子目录。 + +## 使用场景 + +- 当 Kilo Code 需要理解您的项目结构时 +- 当 Kilo Code 在读取特定文件之前探索可用文件时 +- 当 Kilo Code 映射代码库以更好地理解其组织方式时 +- 在使用更针对性的工具（如 `read_file` 或 `search_files`）之前 +- 当 Kilo Code 需要检查项目中特定类型的文件（如配置文件）时 + +## 主要特性 + +- 列出文件和目录，并明确标记目录 +- 提供递归和非递归两种列出模式 +- 在递归模式下，智能忽略常见的大型目录（如 `node_modules` 和 `.git`） +- 在递归模式下，遵循 `.gitignore` 规则 +- 当启用 `showKiloCodeIgnoredFiles` 时，用锁符号（🔒）标记被 `.kilocodeignore` 忽略的文件 +- 通过逐级目录遍历优化性能 +- 排序结果，先显示目录及其内容，保持逻辑层次结构 +- 以干净、有组织的方式呈现结果 +- 自动创建项目结构的思维导图 + +## 限制 + +- 默认情况下，文件列出上限约为 200 个，以防止性能问题 +- 目录遍历有 10 秒的超时限制，以防止在复杂目录结构中挂起 +- 当达到文件限制时，会添加注释建议对特定子目录使用 `list_files` +- 不能用于确认您刚刚创建的文件是否存在 +- 在非常大的目录结构中，性能可能降低 +- 出于安全原因，无法列出根目录或主目录中的文件 + +## 工作原理 + +当调用 `list_files` 工具时，它会遵循以下流程： + +1. **参数验证**：验证必填的 `path` 参数和可选的 `recursive` 参数 +2. **路径解析**：将相对路径解析为绝对路径 +3. **安全检查**：防止列出根目录或主目录等敏感位置中的文件 +4. **目录扫描**： + - 对于非递归模式：仅列出顶层内容 + - 对于递归模式：逐级遍历目录结构，超时时间为 10 秒 + - 如果超时，则返回已收集的部分结果 +5. **结果过滤**： + - 在递归模式下，跳过常见的大型目录，如 `node_modules`、`.git` 等 + - 在递归模式下，遵循 `.gitignore` 规则 + - 处理 `.kilocodeignore` 规则，要么隐藏文件，要么用锁符号标记 +6. **格式化**： + - 用斜杠（`/`）标记目录 + - 排序结果，先显示目录及其内容，保持逻辑层次结构 + - 当启用 `showKiloCodeIgnored` 时，用锁符号（🔒）标记被忽略的文件 + - 默认情况下，结果上限为 200 个文件，并提示使用子目录 + - 组织结果以提高可读性 + +## 文件列出格式 + +文件列出结果包括： + +- 每个文件路径显示在其自己的行上 +- 目录用斜杠（`/`）标记 +- 当启用 `showKiloCodeIgnored` 时，被 `.kilocodeignore` 忽略的文件用锁符号（🔒）标记 +- 结果按逻辑排序，先显示目录及其内容 +- 当达到文件限制时，会出现一条消息，建议对特定子目录使用 `list_files` + +示例输出格式： +``` +src/ +src/components/ +src/components/Button.tsx +src/components/Header.tsx +src/utils/ +src/utils/helpers.ts +src/index.ts +... +文件列出已截断（显示 200 个文件中的 543 个）。请对特定子目录使用 list_files 以获取更多详细信息。 +``` + +当使用 `.kilocodeignore` 文件并启用 `showKiloCodeIgnored` 时： +``` +src/ +src/components/ +src/components/Button.tsx +src/components/Header.tsx +🔒 src/secrets.json +src/utils/ +src/utils/helpers.ts +src/index.ts +``` + +## 使用示例 + +- 当开始新任务时，Kilo Code 可能会列出项目文件以了解其结构，然后再深入研究特定代码。 +- 当被要求查找特定类型的文件（如所有 JavaScript 文件）时，Kilo Code 首先列出目录以知道在哪里查找。 +- 当提供代码组织建议时，Kilo Code 首先检查当前项目结构。 +- 当设置新功能时，Kilo Code 列出相关目录以了解项目约定。 + +## 用法示例 + +列出当前目录中的顶层文件： +``` + +. + +``` + +递归列出源目录中的所有文件： +``` + +src +true + +``` + +检查特定项目的子目录： +``` + +src/components +false + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/new-task.md b/docs/zh-CN/features/tools/new-task.md new file mode 100644 index 0000000..c718b2c --- /dev/null +++ b/docs/zh-CN/features/tools/new-task.md @@ -0,0 +1,103 @@ +# new_task + +`new_task` 工具创建具有专用模式的子任务，同时维护父子关系。它将复杂项目分解为可管理的部分，每个部分在最适合特定工作的模式下运行。 + +## 参数 + +该工具接受以下参数： + +- `mode`（必填）：要启动新任务的模式的 slug（例如，"code"、"ask"、"architect"） +- `message`（必填）：此新任务的初始用户消息或指令 + +## 功能 + +该工具创建一个具有指定启动模式和初始消息的新任务实例。它允许将复杂的工作流划分为具有自己对话历史的子任务。父任务在子任务执行期间暂停，并在子任务完成时恢复，结果传递回父任务。 + +## 使用场景 + +- 当将复杂项目分解为独立的、专注的子任务时 +- 当任务的不同方面需要不同的专用模式时 +- 当工作的不同阶段受益于上下文分离时 +- 当组织多阶段开发工作流时 + +## 主要特性 + +- 创建具有自己对话历史和专用模式的子任务 +- 暂停父任务以便稍后恢复 +- 维护分层任务关系以便导航 +- 在完成后将结果传递回父任务 +- 支持复杂项目的工作流隔离 +- 允许项目的不同部分使用针对特定工作优化的模式 +- 需要用户明确批准任务创建 +- 在 UI 中提供清晰的任务过渡 + +## 限制 + +- 无法创建不存在的模式的任务 +- 创建每个新任务前需要用户批准 +- 任务界面在深度嵌套子任务时可能变得复杂 +- 子任务从父任务继承某些工作区和扩展配置 +- 在切换深度嵌套任务时可能需要重新建立上下文 +- 任务完成需要明确信号以正确返回到父任务 + +## 工作原理 + +当调用 `new_task` 工具时，它会遵循以下流程： + +1. **参数验证**： + - 验证必填的 `mode` 和 `message` 参数 + - 确认请求的模式存在于系统中 + +2. **任务栈管理**： + - 维护一个任务栈以跟踪所有活动任务和暂停任务 + - 保留当前模式以便稍后恢复 + - 将父任务设置为暂停状态 + +3. **任务上下文管理**： + - 使用提供的消息创建新的任务上下文 + - 分配唯一的 taskId 和 instanceId 标识符以进行状态管理 + - 捕获有关工具使用和任务生命周期的遥测数据 + +4. **模式切换和集成**： + - 切换到指定模式，并应用相应的角色和能力 + - 使用提供的消息初始化新任务 + - 与 VS Code 的命令面板和代码操作集成 + +5. **任务完成和结果传递**： + - 当子任务完成时，结果通过 `finishSubTask()` 传递回父任务 + - 父任务恢复其原始模式 + - 更新任务历史和令牌使用指标 + - 发出 `taskCompleted` 事件并附带性能数据 + +## 使用示例 + +- 当前端开发人员需要架构新功能、实现代码并编写文档时，他们可以为每个阶段创建单独的任务，结果从一个阶段传递到下一个阶段。 +- 在调试问题并实施修复之前，调试任务可以记录发现的结果，并将其传递给实施任务。 +- 在开发全栈应用程序时，来自架构模式任务的数据库模式设计会告知后续代码模式任务的实施细节。 +- 在实施完成后编写系统文档时，文档任务可以参考已完成的实施，同时使用文档专用功能。 + +## 用法示例 + +在代码模式中创建新任务： +``` + +code +实现具有登录、注册和密码重置功能的用户身份验证服务。 + +``` + +在完成实施后创建文档任务： +``` + +docs +为我们刚刚构建的身份验证服务创建全面的 API 文档。 + +``` + +将复杂功能分解为架构规划和实施： +``` + +architect +为我们新的电子商务平台设计数据库模式和系统架构。 + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/read-file.md b/docs/zh-CN/features/tools/read-file.md new file mode 100644 index 0000000..304b16f --- /dev/null +++ b/docs/zh-CN/features/tools/read-file.md @@ -0,0 +1,180 @@ +# read_file + +`read_file`工具用于读取项目中的文件内容。它允许 Kilo Code 理解代码、配置文件和文档，以提供更好的协助。 + +## 参数 + +该工具接受以下参数： + +- `path`（必需）：要读取的文件路径（相对于当前工作目录） +- `start_line`（可选）：开始读取的行号（从1开始） +- `end_line`（可选）：结束读取的行号（从1开始，包含该行） +- `auto_truncate`（可选）：当未指定行范围时，是否自动截断大文件（true/false） + +## 功能 + +该工具读取指定文件的内容并返回带行号的结果，便于参考。它可以读取整个文件或特定部分，甚至能从PDF和Word文档中提取文本。 + +## 使用场景 + +- 当 Kilo Code 需要理解现有代码结构时 +- 当 Kilo Code 需要分析配置文件时 +- 当 Kilo Code 需要从文本文件中提取信息时 +- 当 Kilo Code 在建议更改前需要查看代码时 +- 当需要在讨论中引用特定行号时 + +## 主要特性 + +- 显示带行号的文件内容，便于参考 +- 通过指定行范围读取文件的特定部分 +- 从PDF和DOCX文件中提取可读文本 +- 智能截断大文件以聚焦最相关部分 +- 为大型代码文件提供带行范围的方法摘要 +- 高效流式传输请求的行范围以获得更好性能 +- 便于通过行号讨论代码的特定部分 + +## 限制 + +- 如果不使用行范围参数，可能无法高效处理极大的文件 +- 对于二进制文件（除PDF和DOCX外），可能返回非人类可读的内容 + +## 工作原理 + +当调用`read_file`工具时，它遵循以下流程： + +1. **参数验证**：验证必需的`path`参数和可选参数 +2. **路径解析**：将相对路径解析为绝对路径 +3. **读取策略选择**： + - 工具使用严格的优先级层次（下文详细说明） + - 在范围读取、自动截断或完整文件读取之间选择 +4. **内容处理**： + - 为内容添加行号（例如"1 | const x = 13"） + - 对于截断文件，添加截断通知和方法定义 + - 对于特殊格式（PDF、DOCX、IPYNB），提取可读文本 + +## 读取策略优先级 + +工具使用明确的决策层次来确定如何读取文件： + +1. **第一优先级：显式行范围** + - 如果提供了`start_line`或`end_line`，工具始终执行范围读取 + - 实现高效流式传输仅请求的行，适合处理大文件 + - 此选项优先于所有其他选项 + +2. **第二优先级：大文件自动截断** + - 仅在满足以下所有条件时应用： + - 未指定`start_line`或`end_line` + - `auto_truncate`参数设为`true` + - 文件不是二进制文件 + - 文件超过配置的行阈值（通常500-1000行） + - 当自动截断激活时，工具： + - 仅读取文件开头部分（由maxReadFileLine设置决定） + - 添加截断通知显示已显示行数与总行数 + - 提供带行范围的方法定义摘要 + +3. **默认行为：读取整个文件** + - 如果不符合上述条件，则读取整个文件内容 + - 对于PDF、DOCX和IPYNB等特殊格式，使用专用提取器 + +## 使用示例 + +- 当要求解释或改进代码时，Kilo Code 首先读取相关文件以理解当前实现 +- 当排查配置问题时，Kilo Code 读取配置文件以识别潜在问题 +- 当处理文档时，Kilo Code 读取现有文档以理解当前内容再建议改进 + +## 用法示例 + +以下是几个展示`read_file`工具如何使用及可能收到的典型输出场景。 + +### 读取整个文件 + +读取文件的完整内容： + +**输入：** +```xml + +src/app.js + +``` + +**模拟输出（小文件如`example_small.txt`）：** +``` +1 | This is the first line. +2 | This is the second line. +3 | This is the third line. +``` +*(输出会根据实际文件内容而变化)* + +### 读取特定行 + +仅读取特定行范围（例如46-68行）： + +**输入：** +```xml + +src/app.js +46 +68 + +``` + +**模拟输出（`example_five_lines.txt`的2-3行）：** +``` +2 | Content of line two. +3 | Content of line three. +``` +*(输出仅显示请求的行及其原始行号)* + +### 读取大文件（自动截断） + +当读取大文件且未指定行范围，且`auto_truncate`启用时（或根据设置默认为true）： + +**输入：** +```xml + +src/large-module.js +true + +``` + +**模拟输出（`large_file.log`有1500行，限制1000行）：** +``` +1 | Log entry 1... +2 | Log entry 2... +... +1000 | Log entry 1000... +[... truncated 500 lines ...] +``` +*(输出限制为配置的最大行数，并带有截断通知)* + +### 尝试读取不存在的文件 + +如果指定文件不存在： + +**输入：** +```xml + +non_existent_file.txt + +``` + +**模拟输出（错误）：** +``` +Error: File not found at path 'non_existent_file.txt'. +``` + +### 尝试读取被阻止的文件 + +如果文件被`.kilocodeignore`规则排除： + +**输入：** +```xml + +.env + +``` + +**模拟输出（错误）：** +``` +Error: Access denied to file '.env' due to .kilocodeignore rules. +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/search-files.md b/docs/zh-CN/features/tools/search-files.md new file mode 100644 index 0000000..2e003be --- /dev/null +++ b/docs/zh-CN/features/tools/search-files.md @@ -0,0 +1,120 @@ +# search_files + +`search_files` 工具可以在你的项目中跨多个文件执行正则表达式搜索。它帮助 Kilo Code 在代码库中定位特定的代码模式、文本或其他内容，并提供上下文的搜索结果。 + +## 参数 + +该工具接受以下参数： + +- `path`（必填）：要搜索的目录路径，相对于当前工作目录 +- `regex`（必填）：要搜索的正则表达式模式（使用 Rust 正则表达式语法） +- `file_pattern`（可选）：用于过滤文件的 glob 模式（例如，'*.ts' 表示仅搜索 TypeScript 文件） + +## 功能 + +该工具使用正则表达式在指定目录中跨文件搜索，显示每个匹配项及其上下文。它就像一个强大的“在文件中查找”功能，适用于整个项目结构。 + +## 使用场景 + +- 当 Kilo Code 需要查找特定函数或变量的使用位置时 +- 当 Kilo Code 协助重构并需要了解使用模式时 +- 当 Kilo Code 需要定位特定代码模式的所有实例时 +- 当 Kilo Code 需要在多个文件中搜索文本并具有过滤功能时 + +## 主要特性 + +- 使用高性能的 Ripgrep 在多个文件中进行搜索 +- 显示每个匹配项的上下文（前后各 1 行） +- 使用 glob 模式按文件类型过滤（例如，仅 TypeScript 文件） +- 提供行号以便参考 +- 使用强大的正则表达式模式进行精确搜索 +- 自动限制输出为 300 个结果并通知 +- 截断超过 500 个字符的行并标记为“[truncated...]” +- 智能地将附近的匹配项合并为单个块以提高可读性 + +## 限制 + +- 最适合文本文件（对图像等二进制文件无效） +- 在非常大的代码库中性能可能会下降 +- 使用 Rust 正则表达式语法，可能与其他正则表达式实现略有不同 +- 无法在压缩文件或存档中搜索 +- 默认上下文大小固定（前后各 1 行） +- 由于结果分组，当匹配项接近时可能会显示不同的上下文大小 + +## 工作原理 + +当调用 `search_files` 工具时，它会遵循以下流程： + +1. **参数验证**：验证必需的 `path` 和 `regex` 参数 +2. **路径解析**：将相对路径解析为绝对路径 +3. **搜索执行**： + - 使用 Ripgrep (rg) 进行高性能文本搜索 + - 如果指定了文件模式，则应用过滤 + - 收集匹配项及其上下文 +4. **结果格式化**： + - 格式化结果，包括文件路径、行号和上下文 + - 显示每个匹配项前后各 1 行的上下文 + - 结构化输出以便于阅读 + - 将结果限制为最多 300 个匹配项并通知 + - 截断超过 500 个字符的行 + - 将附近的匹配项合并为连续块 + +## 搜索结果格式 + +搜索结果包括： + +- 每个匹配文件的相对路径（前缀为 #） +- 每个匹配项前后的上下文行（默认为 1 行） +- 行号填充为 3 个空格，后跟 ` | ` 和行内容 +- 每个匹配组后跟分隔线（----） + +示例输出格式： +``` +# rel/path/to/app.ts + 11 | // 一些处理逻辑 + 12 | // TODO: 实现错误处理 + 13 | return processedData; +---- + +# 显示 300 多个结果中的前 300 个。如有必要，请使用更具体的搜索。 +``` + +当匹配项彼此接近时，它们会合并为单个块而不是显示为单独的结果： + +``` +# rel/path/to/auth.ts + 13 | // 一些代码 + 14 | // TODO: 添加适当的验证 + 15 | function validateUser(credentials) { + 16 | // TODO: 实现速率限制 + 17 | return checkDatabase(credentials); +---- +``` + +## 使用示例 + +搜索所有 JavaScript 文件中的 TODO 注释： +``` + +src +TODO|FIXME +*.js + +``` + +查找特定函数的所有使用位置： +``` + +. +function\s+calculateTotal +*.{js,ts} + +``` + +在整个项目中搜索特定的导入模式： +``` + +. +import\s+.*\s+from\s+['"]@components/ + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/switch-mode.md b/docs/zh-CN/features/tools/switch-mode.md new file mode 100644 index 0000000..acf9d97 --- /dev/null +++ b/docs/zh-CN/features/tools/switch-mode.md @@ -0,0 +1,151 @@ +# switch_mode + +`switch_mode` 工具使 Kilo Code 能够在不同操作模式之间切换，每种模式都具有针对特定任务类型的专业能力。当当前任务需要不同的专业知识时，可以无缝切换到 Code、Architect、Ask 或 Debug 模式。 + +## 参数 + +该工具接受以下参数： + +- `mode_slug`（必填）：要切换到的模式标识符（例如 "code"、"ask"、"architect"） +- `reason`（可选）：切换模式的原因，为用户提供上下文 + +## 功能 + +该工具在当当前任务更适合由其他模式处理时请求模式切换。它在切换过程中保持上下文，同时调整 Kilo Code 的焦点和可用工具集，以匹配新任务阶段的需求。 + +## 使用场景 + +- 从信息收集过渡到代码实现时 +- 从编码切换到架构或设计时 +- 当前任务需要仅在另一个模式中可用的功能时 +- 复杂项目的特定阶段需要专业知识时 + +## 主要特性 + +- 在模式切换过程中保持上下文连续性 +- 为模式切换提供清晰的推理 +- 需要用户批准所有模式更改 +- 强制执行特定模式的工具组限制 +- 根据所选模式无缝调整工具可用性 +- 适用于标准和自定义模式 +- 在 UI 中显示模式切换和原因 +- 使用 XML 格式指定参数 +- 强制执行某些模式的文件类型限制 + +## 限制 + +- 无法切换到系统中不存在的模式 +- 每次模式转换都需要用户明确批准 +- 在切换完成前无法使用特定模式的工具 +- 模式切换后应用 500ms 的延迟以确保更改生效 +- 某些模式有文件类型限制（例如 Architect 模式只能编辑 markdown 文件） +- 模式保存仅适用于 `new_task` 功能，不适用于一般模式切换 + +## 工作原理 + +当调用 `switch_mode` 工具时，它会遵循以下流程： + +1. **请求验证**： + - 验证请求的模式是否存在于系统中 + - 检查是否提供了 `mode_slug` 参数且有效 + - 确认用户尚未处于请求的模式 + - 确保 `reason` 参数（如果提供）格式正确 + +2. **模式切换准备**： + - 将模式更改请求与提供的原因打包 + - 向用户展示更改请求以获取批准 + +3. **模式激活（用户批准后）**： + - 更新 UI 以反映新模式 + - 根据模式的工具组配置调整可用工具 + - 应用模式特定的提示和行为 + - 应用 500ms 延迟以确保更改生效再执行下一个工具 + - 强制执行模式特定的文件限制 + +4. **继续执行**： + - 使用新模式的功能继续任务 + - 保留之前交互的相关上下文 + +## 工具组关联 + +`switch_mode` 工具属于 "modes" 工具组，但也包含在 "always available" 工具列表中。这意味着： + +- 它可以在任何模式下使用，不受模式配置的工具组限制 +- 它与 `ask_followup_question` 和 `attempt_completion` 等核心工具一起可用 +- 它允许在工作流的任何阶段进行模式切换，以适应任务需求的变化 + +## 模式结构 + +系统中的每个模式都有特定的结构： + +- `slug`：模式的唯一标识符（例如 "code"、"ask"） +- `name`：模式的显示名称（例如 "Code"、"Ask"） +- `roleDefinition`：模式的专业角色和能力 +- `customInstructions`：可选的模式特定指令，用于指导行为 +- `groups`：模式可用的工具组，可设置限制 + +## 模式能力 + +核心模式提供以下专业能力： + +- **Code 模式**：专注于编码任务，完全访问代码编辑工具 +- **Architect 模式**：专用于系统设计和架构规划，仅限于编辑 markdown 文件 +- **Ask 模式**：优化用于回答问题并提供信息 +- **Debug 模式**：配备用于系统问题诊断和解决 + +## 自定义模式 + +除了核心模式外，系统还支持特定项目的自定义模式： + +- 可以定义具有特定工具组启用的自定义模式 +- 可以指定自定义角色定义和指令 +- 系统会先检查自定义模式，然后再回退到核心模式 +- 自定义模式定义优先于具有相同标识符的核心模式 + +## 文件限制 + +不同的模式可能有特定的文件类型限制： + +- **Architect 模式**：只能编辑扩展名为 `.md` 的文件 +- 尝试编辑受限制的文件类型会导致 `FileRestrictionError` +- 这些限制有助于在模式之间强制执行适当的关注点分离 + +## 使用示例 + +- 讨论新功能时，Kilo Code 从 Ask 模式切换到 Architect 模式以帮助设计系统结构。 +- 在 Architect 模式中完成架构规划后，Kilo Code 切换到 Code 模式以实现设计的功能。 +- 在开发过程中遇到错误时，Kilo Code 从 Code 模式切换到 Debug 模式进行系统问题排查。 + +## 使用示例 + +切换到 Code 模式进行实现： +``` + +code +需要基于我们讨论的架构实现登录功能 + +``` + +切换到 Architect 模式进行设计： +``` + +architect +需要在实现前设计系统架构 + +``` + +切换到 Debug 模式进行问题排查： +``` + +debug +需要系统诊断认证错误 + +``` + +切换到 Ask 模式获取信息： +``` + +ask +需要回答关于已实现功能的问题 + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/tool-use-overview.md b/docs/zh-CN/features/tools/tool-use-overview.md new file mode 100644 index 0000000..e6e91ee --- /dev/null +++ b/docs/zh-CN/features/tools/tool-use-overview.md @@ -0,0 +1,239 @@ +# 工具使用概述 + +Kilo Code 实现了一个复杂的工具系统，允许 AI 模型以受控和安全的方式与你的开发环境交互。本文档解释了工具的工作原理、调用时机和管理方式。 + +## 核心概念 + +### 工具分组 + +工具根据功能分为逻辑组： + +| 类别 | 用途 | 工具 | 常见用途 | +|----------|---------|-------|------------| +| **读取组** | 文件系统读取和搜索 | [read_file](/features/tools/read-file), [search_files](/features/tools/search-files), [list_files](/features/tools/list-files), [list_code_definition_names](/features/tools/list-code-definition-names) | 代码探索和分析 | +| **编辑组** | 文件系统修改 | [apply_diff](/features/tools/apply-diff), [write_to_file](/features/tools/write-to-file) | 代码更改和文件操作 | +| **浏览器组** | 网页自动化 | [browser_action](/features/tools/browser-action) | 网页测试和交互 | +| **命令组** | 系统命令执行 | [execute_command](/features/tools/execute-command) | 运行脚本、构建项目 | +| **MCP组** | 外部工具集成 | [use_mcp_tool](/features/tools/use-mcp-tool), [access_mcp_resource](/features/tools/access-mcp-resource) | 通过外部服务器实现专门功能 | +| **工作流组** | 模式和任务管理 | [switch_mode](/features/tools/switch-mode), [new_task](/features/tools/new-task), [ask_followup_question](/features/tools/ask-followup-question), [attempt_completion](/features/tools/attempt-completion) | 上下文切换和任务组织 | + +### 始终可用的工具 + +某些工具在任何模式下都可访问： + +- [ask_followup_question](/features/tools/ask-followup-question)：从用户处收集额外信息 +- [attempt_completion](/features/tools/attempt-completion)：标记任务完成 +- [switch_mode](/features/tools/switch-mode)：更改操作模式 +- [new_task](/features/tools/new-task)：创建子任务 + +## 可用工具 + +### 读取工具 +这些工具帮助 Kilo Code 理解你的代码和项目： + +- [read_file](/features/tools/read-file) - 检查文件内容 +- [search_files](/features/tools/search-files) - 跨多个文件查找模式 +- [list_files](/features/tools/list-files) - 映射项目文件结构 +- [list_code_definition_names](/features/tools/list-code-definition-names) - 创建代码结构图 + +### 编辑工具 +这些工具帮助 Kilo Code 修改你的代码： + +- [apply_diff](/features/tools/apply-diff) - 对代码进行精确修改 +- [write_to_file](/features/tools/write-to-file) - 创建新文件或完全重写现有文件 + +### 浏览器工具 +这些工具帮助 Kilo Code 与网页应用交互： + +- [browser_action](/features/tools/browser-action) - 自动化浏览器交互 + +### 命令工具 +这些工具帮助 Kilo Code 执行命令： + +- [execute_command](/features/tools/execute-command) - 运行系统命令和程序 + +### MCP工具 +这些工具帮助 Kilo Code 连接外部服务： + +- [use_mcp_tool](/features/tools/use-mcp-tool) - 使用专门的外部工具 +- [access_mcp_resource](/features/tools/access-mcp-resource) - 访问外部数据源 + +### 工作流工具 +这些工具帮助管理对话和任务流： + +- [ask_followup_question](/features/tools/ask-followup-question) - 从你那里获取额外信息 +- [attempt_completion](/features/tools/attempt-completion) - 呈现最终结果 +- [switch_mode](/features/tools/switch-mode) - 切换到不同模式以执行专门任务 +- [new_task](/features/tools/new-task) - 创建新子任务 + +## 工具调用机制 + +### 工具调用时机 + +工具在特定条件下被调用： + +1. **直接任务需求** + - 当需要特定操作来完成 LLM 决定的任务时 + - 响应用户请求 + - 在自动化工作流中 + +2. **基于模式的可用性** + - 不同模式启用不同的工具集 + - 模式切换可以触发工具可用性变化 + - 某些工具仅限于特定模式 + +3. **上下文相关调用** + - 基于工作区的当前状态 + - 响应系统事件 + - 在错误处理和恢复期间 + +### 决策过程 + +系统使用多步骤流程确定工具可用性： + +1. **模式验证** + ```typescript + isToolAllowedForMode( + tool: string, + modeSlug: string, + customModes: ModeConfig[], + toolRequirements?: Record, + toolParams?: Record + ) + ``` + +2. **需求检查** + - 系统能力验证 + - 资源可用性 + - 权限验证 + +3. **参数验证** + - 必需参数是否存在 + - 参数类型检查 + - 值验证 + +## 技术实现 + +### 工具调用处理 + +1. **初始化** + - 验证工具名称和参数 + - 检查模式兼容性 + - 验证需求 + +2. **执行** + ```typescript + const toolCall = { + type: "tool_call", + name: chunk.name, + arguments: chunk.input, + callId: chunk.callId + } + ``` + +3. **结果处理** + - 确定成功/失败 + - 格式化结果 + - 错误处理 + +### 安全与权限 + +1. **访问控制** + - 文件系统限制 + - 命令执行限制 + - 网络访问控制 + +2. **验证层** + - 工具特定验证 + - 基于模式的限制 + - 系统级检查 + +## 模式集成 + +### 基于模式的工具访问 + +工具根据当前模式提供： + +- **代码模式**：完全访问文件系统工具、代码编辑能力、命令执行 +- **提问模式**：仅限于读取工具、信息收集能力，不能修改文件系统 +- **架构模式**：设计导向工具、文档能力，有限的执行权限 +- **自定义模式**：可配置特定工具访问以实现专门工作流 + +### 模式切换 + +1. **流程** + - 保存当前模式状态 + - 更新工具可用性 + - 上下文切换 + +2. **对工具的影响** + - 工具集变化 + - 权限调整 + - 上下文保存 + +## 最佳实践 + +### 工具使用指南 + +1. **效率** + - 使用最适合任务的工具 + - 避免冗余工具调用 + - 尽可能批量操作 + +2. **安全** + - 调用工具前验证输入 + - 使用最低必要权限 + - 遵循安全最佳实践 + +3. **错误处理** + - 实施适当的错误检查 + - 提供有意义的错误信息 + - 优雅地处理失败 + +### 常见模式 + +1. **信息收集** + ``` + [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files) + ``` + +2. **代码修改** + ``` + [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion) + ``` + +3. **任务管理** + ``` + [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command) + ``` + +## 错误处理与恢复 + +### 错误类型 + +1. **工具特定错误** + - 参数验证失败 + - 执行错误 + - 资源访问问题 + +2. **系统错误** + - 权限被拒绝 + - 资源不可用 + - 网络故障 + +3. **上下文错误** + - 工具的模式无效 + - 缺少需求 + - 状态不一致 + +### 恢复策略 + +1. **自动恢复** + - 重试机制 + - 回退选项 + - 状态恢复 + +2. **用户干预** + - 错误通知 + - 恢复建议 + - 手动干预选项 \ No newline at end of file diff --git a/docs/zh-CN/features/tools/use-mcp-tool.md b/docs/zh-CN/features/tools/use-mcp-tool.md new file mode 100644 index 0000000..a7c3924 --- /dev/null +++ b/docs/zh-CN/features/tools/use-mcp-tool.md @@ -0,0 +1,180 @@ +# use_mcp_tool + +`use_mcp_tool` 工具使 Kilo Code 能够与连接的 Model Context Protocol (MCP) 服务器提供的外部工具进行交互。它通过标准化协议扩展了 Kilo Code 的功能，提供特定领域的专业能力。 + +## 参数 + +该工具接受以下参数： + +- `server_name`（必填）：提供工具的 MCP 服务器名称 +- `tool_name`（必填）：要执行的工具名称 +- `arguments`（必填/可选）：包含工具输入参数的 JSON 对象，遵循工具的输入模式。对于不需要输入的工具，此参数可为可选。 + +## 功能 + +该工具允许 Kilo Code 访问由外部 MCP 服务器提供的专业功能。每个 MCP 服务器可以提供多个具有独特功能的工具，从而扩展 Kilo Code 的内置功能。系统会根据模式验证参数，管理服务器连接，并处理各种内容类型的响应（文本、图像、资源）。 + +## 使用场景 + +- 当需要核心工具无法提供的专业功能时 +- 当需要特定领域的操作时 +- 当需要与外部系统或服务集成时 +- 当处理需要特定处理或分析的数据时 +- 当通过标准化接口访问专有工具时 + +## 主要特性 + +- 使用 `@modelcontextprotocol/sdk` 库的标准化 MCP 协议 +- 支持多种通信机制（StdioClientTransport 和 SSEClientTransport） +- 在客户端和服务器端使用 Zod 模式验证参数 +- 处理多种响应内容类型：文本、图像和资源引用 +- 当服务器代码更改时自动重启，管理服务器生命周期 +- 提供“始终允许”机制以绕过受信任工具的批准 +- 与配套的 `access_mcp_resource` 工具协同工作以获取资源 +- 维护适当的错误跟踪和处理机制 +- 支持可配置的超时时间（1-3600 秒，默认：60 秒） +- 允许文件监视器自动检测和重新加载服务器更改 + +## 限制 + +- 依赖外部 MCP 服务器的可用性和连接性 +- 仅限于连接服务器提供的工具 +- 不同 MCP 服务器的工具能力各不相同 +- 网络问题可能影响可靠性和性能 +- 需要用户批准才能执行（除非在“始终允许”列表中） +- 无法同时执行多个 MCP 工具操作 + +## 服务器配置 + +MCP 服务器可以在全局或项目级别进行配置： + +- **全局配置**：通过 VS Code 中的 Kilo Code 扩展设置进行管理。这些设置适用于所有项目，除非被覆盖。 +- **项目级配置**：在项目根目录下的 `.kilocode/mcp.json` 文件中定义。 + - 这允许项目特定的服务器设置。 + - 如果项目级服务器与全局服务器同名，则项目级服务器优先。 + - 由于 `.kilocode/mcp.json` 可以提交到版本控制，因此简化了与团队共享配置的过程。 + +## 工作原理 + +当调用 `use_mcp_tool` 工具时，它会遵循以下流程： + +1. **初始化和验证**： + - 系统验证 MCP hub 是否可用 + - 确认指定的服务器存在并已连接 + - 验证请求的工具存在于服务器上 + - 根据工具的模式定义验证参数 + - 从服务器配置中提取超时设置（默认：60 秒） + +2. **执行和通信**： + - 系统选择适当的通信机制： + - `StdioClientTransport`：用于通过标准 I/O 与本地进程通信 + - `SSEClientTransport`：用于通过 Server-Sent Events 与 HTTP 服务器通信 + - 发送包含已验证的服务器名称、工具名称和参数的请求 + - 使用 `@modelcontextprotocol/sdk` 库进行标准化交互 + - 跟踪请求执行并处理超时，防止挂起操作 + +3. **响应处理**： + - 响应可以包含多种内容类型： + - 文本内容：纯文本响应 + - 图像内容：带有 MIME 类型信息的二进制图像数据 + - 资源引用：用于访问服务器资源的 URI（与 `access_mcp_resource` 协同工作） + - 系统检查 `isError` 标志以确定是否需要错误处理 + - 结果会被格式化以在 Kilo Code 界面中显示 + +4. **资源和错误处理**： + - 系统使用 WeakRef 模式防止内存泄漏 + - 连续错误计数器跟踪和管理错误 + - 文件监视器监控服务器代码更改并触发自动重启 + - 安全模型要求批准工具执行，除非在“始终允许”列表中 + +## 安全和权限 + +MCP 架构提供了多项安全功能： + +- 默认情况下，用户必须在执行前批准工具使用 +- 特定工具可以标记为“始终允许”列表中的自动批准 +- 使用 Zod 模式验证服务器配置以确保完整性 +- 可配置的超时时间防止挂起操作（1-3600 秒） +- 可以通过 UI 启用或禁用服务器连接 + +## 使用示例 + +使用文本响应请求天气预报数据： +``` + +weather-server +get_forecast + +{ + "city": "San Francisco", + "days": 5, + "format": "text" +} + + +``` + +使用返回 JSON 的专用工具分析源代码： +``` + +code-analysis +complexity_metrics + +{ + "language": "typescript", + "file_path": "src/app.ts", + "include_functions": true, + "metrics": ["cyclomatic", "cognitive"] +} + + +``` + +使用特定参数生成图像： +``` + +image-generation +create_image + +{ + "prompt": "A futuristic city with flying cars", + "style": "photorealistic", + "dimensions": { + "width": 1024, + "height": 768 + }, + "format": "webp" +} + + +``` + +通过返回资源引用的工具访问资源： +``` + +database-connector +query_and_store + +{ + "database": "users", + "type": "select", + "fields": ["name", "email", "last_login"], + "where": { + "status": "active" + }, + "store_as": "active_users" +} + + +``` + +不需要参数的工具： +``` + +system-monitor +get_current_status + +{} + + +``` \ No newline at end of file diff --git a/docs/zh-CN/features/tools/write-to-file.md b/docs/zh-CN/features/tools/write-to-file.md new file mode 100644 index 0000000..4aacdfa --- /dev/null +++ b/docs/zh-CN/features/tools/write-to-file.md @@ -0,0 +1,169 @@ +# write_to_file + +`write_to_file` 工具用于创建新文件或完全替换现有文件内容，并通过交互式审批流程提供变更的差异视图。 + +## 参数 + +该工具接受以下参数： + +- `path`（必填）：要写入的文件路径，相对于当前工作目录 +- `content`（必填）：要写入文件的完整内容 +- `line_count`（必填）：文件中的行数，包括空行 + +## 功能 + +该工具将内容写入指定文件，如果文件不存在则创建新文件，如果文件存在则完全覆盖现有内容。所有变更都需要通过差异视图界面进行显式用户审批，用户可以在应用变更之前查看甚至编辑建议的内容。 + +## 使用场景 + +- 当 Kilo Code 需要从头创建新文件时 +- 当 Kilo Code 需要完全重写现有文件时 +- 当为新项目创建多个文件时 +- 当生成配置文件、文档或源代码时 +- 当需要在应用变更之前查看变更时 + +## 关键特性 + +- 交互式审批：在差异视图中显示变更，需要显式批准才能应用 +- 用户编辑支持：允许在最终批准之前编辑建议的内容 +- 安全措施：检测代码遗漏、验证路径并防止内容截断 +- 编辑器集成：打开差异视图并自动滚动到第一个差异 +- 内容预处理：处理不同 AI 模型的输出，确保内容干净 +- 访问控制：在更改之前验证 `.kilocodeignore` 限制 +- 父目录：可能通过系统依赖处理目录创建 +- 完全替换：在单个操作中提供完全转换的文件 + +## 限制 + +- 不适用于现有文件：对于修改现有文件，比 `apply_diff` 效率低得多 +- 大文件性能：文件较大时操作速度显著变慢 +- 完全覆盖：替换整个文件内容，无法保留原始内容 +- 需要行数：需要准确的行数以检测潜在的内容截断 +- 审批开销：审批流程比直接编辑增加了额外步骤 +- 仅限交互式：无法在需要非交互式执行的自动化工作流中使用 + +## 工作原理 + +当调用 `write_to_file` 工具时，它会遵循以下过程： + +1. **参数验证**：验证必需的参数和权限 + - 检查是否提供了 `path`、`content` 和 `line_count` + - 验证文件是否允许（不受 `.kilocodeignore` 限制） + - 确保路径在工作区范围内 + - 跟踪缺失参数的连续错误计数 + - 为每个验证失败显示具体的错误消息 + +2. **内容预处理**： + - 删除可能由 AI 模型添加的代码块标记 + - 处理转义的 HTML 实体（特别是非 Claude 模型） + - 如果内容中意外包含行号，则去除行号 + - 针对不同的 AI 提供者执行模型特定的处理 + +3. **差异视图生成**： + - 在编辑器中打开差异视图，显示建议的变更 + - 添加 300 毫秒的延迟以确保 UI 响应能力 + - 自动滚动到第一个差异 + - 高亮显示变更以便于查看 + +4. **用户审批流程**： + - 等待用户显式批准以继续 + - 允许用户在差异视图中编辑内容 + - 捕获用户的任何编辑以用于最终内容 + - 提供完全拒绝变更的选项 + - 检测并合并用户修改到最终结果中 + +5. **安全验证**： + - 通过与提供的行数比较，检测潜在的内容截断 + - 如果内容看起来不完整，则显示警告 + - 验证文件路径和访问权限 + - 特别检查文件是否在工作区外，使用 `isOutsideWorkspace` 标志 + +6. **文件写入**： + - 将批准的内容（包括用户的任何编辑）写入文件 + - 提供成功写入的确认 + - 成功时重置连续错误计数器 + +## 使用时的示例 + +- 创建新项目时，Kilo Code 会生成多个文件，但会让您在提交更改前查看每个文件。 +- 设置配置文件时，Kilo Code 会在差异视图中显示建议的配置以供批准。 +- 生成文档时，Kilo Code 会创建 Markdown 文件，但允许您在差异视图中进行最终调整。 +- 开发原型时，Kilo Code 会在差异视图中显示完整的源文件，您可以在保存前进行微调。 + +## 使用示例 + +创建新的 JSON 配置文件： +``` + +config/settings.json + +{ + "apiEndpoint": "https://api.example.com", + "theme": { + "primaryColor": "#007bff", + "secondaryColor": "#6c757d", + "fontFamily": "Arial, sans-serif" + }, + "features": { + "darkMode": true, + "notifications": true, + "analytics": false + }, + "version": "1.0.0" +} + +14 + +``` + +创建简单的 HTML 文件： +``` + +src/index.html + + + + + + + My Application + + + +
+ + + + +13 + +``` + +创建 JavaScript 模块： +``` + +src/utils/helpers.js + +/** + * 应用程序的实用工具函数 + */ + +export function formatDate(date) { + return new Date(date).toLocaleDateString(); +} + +export function calculateTotal(items) { + return items.reduce((sum, item) => sum + item.price, 0); +} + +export function debounce(func, delay) { + let timeout; + return function(...args) { + clearTimeout(timeout); + timeout = setTimeout(() => func.apply(this, args), delay); + }; +} + +18 + +``` diff --git a/docs/zh-CN/getting-started/connecting-api-provider.md b/docs/zh-CN/getting-started/connecting-api-provider.md new file mode 100644 index 0000000..a2cbbfa --- /dev/null +++ b/docs/zh-CN/getting-started/connecting-api-provider.md @@ -0,0 +1,76 @@ +--- +sidebar_label: 连接到提供商 +--- + +# 连接您的第一个AI提供商 + +Kilo Code需要一个AI模型提供商的API密钥才能运行。我们推荐以下选项来访问强大的**Claude 3.7 Sonnet**模型： + +- **OpenRouter（推荐）：**通过单个API密钥访问多个AI模型。适合快速入门，设置简单。[查看价格](https://openrouter.ai/models?order=pricing-low-to-high) +- **Anthropic：**直接访问Claude模型。需要API访问批准，可能会有[根据您的等级设置速率限制](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier)。查看[Anthropic的价格页面](https://www.anthropic.com/pricing#anthropic-api)了解详情 + +## 获取您的API密钥 + +### 选项1：LLM路由器 + +LLM路由器让您可以通过一个API密钥访问多个AI模型，简化了成本管理和模型切换。通常提供[更具竞争力的价格](https://openrouter.ai/models?order=pricing-low-to-high)。 + +#### OpenRouter + +1. 访问 [openrouter.ai](https://openrouter.ai/) +2. 使用Google或GitHub账号登录 +3. 导航到[API密钥页面](https://openrouter.ai/keys)并创建新密钥 +4. 复制您的API密钥 - 您需要它来设置Kilo Code + +OpenRouter API密钥页面 + +*OpenRouter仪表板，带有"创建密钥"按钮。命名您的密钥并在创建后复制它。* + +#### Requesty + +1. 访问 [requesty.ai](https://requesty.ai/) +2. 使用Google账号或电子邮件登录 +3. 导航到[API管理页面](https://app.requesty.ai/manage-api)并创建新密钥 +4. **重要：** 立即复制您的API密钥，因为它不会再次显示 + +Requesty API管理页面 + +*Requesty API管理页面，带有"创建API密钥"按钮。立即复制您的密钥 - 它只会显示一次。* + +### 选项2：直接提供商 + +直接访问特定模型的原提供商，完全使用其功能和特性： + +#### Anthropic + +1. 访问 [console.anthropic.com](https://console.anthropic.com/) +2. 注册账号或登录 +3. 导航到[API密钥部分](https://console.anthropic.com/settings/keys)并创建新密钥 +4. **重要：** 立即复制您的API密钥，因为它不会再次显示 + +Anthropic控制台API密钥部分 + +*Anthropic控制台API密钥部分，带有"创建密钥"按钮。命名您的密钥，设置过期时间，并立即复制它。* + +#### OpenAI + +1. 访问 [platform.openai.com](https://platform.openai.com/) +2. 注册账号或登录 +3. 导航到[API密钥部分](https://platform.openai.com/api-keys)并创建新密钥 +4. **重要：** 立即复制您的API密钥，因为它不会再次显示 + +OpenAI API密钥页面 + +*OpenAI平台，带有"创建新密钥"按钮。命名您的密钥并在创建后立即复制它。* + +## 在VS Code中配置Kilo Code + +获取API密钥后： + +1. 点击VS Code侧边栏中的Kilo Code图标()打开Kilo Code侧边栏 +2. 在欢迎界面，从下拉菜单中选择您的API提供商 +3. 将API密钥粘贴到相应字段中 +4. 选择您的模型： + - 对于**OpenRouter**：选择`anthropic/claude-3.7-sonnet` ([模型详情](https://openrouter.ai/anthropic/claude-3.7-sonnet)) + - 对于**Anthropic**：选择`claude-3-7-sonnet-20250219` ([模型详情](https://www.anthropic.com/pricing#anthropic-api)) +5. 点击"Let's go!"保存设置并开始使用Kilo Code \ No newline at end of file diff --git a/docs/zh-CN/getting-started/installing.md b/docs/zh-CN/getting-started/installing.md new file mode 100644 index 0000000..520624b --- /dev/null +++ b/docs/zh-CN/getting-started/installing.md @@ -0,0 +1,106 @@ +--- +sidebar_label: 安装Kilo Code +--- + +# 安装Kilo Code + +Kilo Code是一款VS Code扩展，可将AI编程助手直接集成到编辑器中。可通过以下方式安装： +- [**VS Code应用商店（推荐）**](#vs-code-marketplace) - VS Code用户最快捷的安装方式 +- [**Cursor应用商店**](#cursor-marketplace) - Cursor用户的推荐安装方式 +- [**Open VSX注册表**](#open-vsx-registry) - 适用于VSCodium/Windsurf等兼容VS Code的编辑器 +- [**手动安装.vsix文件**](#manual-installation-from-vsix) - 从GitHub Release直接安装 + +## VS Code应用商店 + +:::tip + +若已安装VS Code：[点击此处直接安装Kilo Code](vscode:extension/kilocode.Kilo-Code) + +::: + +或按以下步骤操作： + +1. 打开VS Code +2. 进入扩展面板：点击侧边栏扩展图标 或按 `Ctrl+Shift+X`（Windows/Linux） / `Cmd+Shift+X`（macOS） +3. 搜索 "Kilo Code" +4. 选择Kilo Code发布的扩展并点击**安装** +5. 根据提示重新加载VS Code + +安装完成后，在侧边栏找到Kilo Code图标（）即可打开面板。 + +VS Code应用商店中的Kilo Code扩展安装界面 +*VS Code应用商店中的Kilo Code扩展安装界面* + +## Cursor应用商店 + +:::tip + +若已安装Cursor：[点击此处直接安装Kilo Code](cursor:extension/kilocode.Kilo-Code) + +::: + +或按以下步骤操作： + +1. 打开Cursor +2. 进入扩展面板：点击侧边栏扩展图标 或按 `Ctrl+Shift+X`（Windows/Linux） / `Cmd+Shift+X`（macOS） +3. 搜索 "Kilo Code" +4. 选择Kilo Code发布的扩展并点击**安装** +5. 根据提示重新加载Cursor + +安装完成后，在侧边栏找到Kilo Code图标（）即可打开面板。 + +## Open VSX注册表 + +[Open VSX注册表](https://open-vsx.org/)是VS Code应用商店的开源替代方案，适用于因许可证限制无法访问官方商店的编辑器。 + +在VSCodium、Gitpod、Eclipse Theia、Windsurf等兼容编辑器中，可通过[Open VSX上的Kilo Code页面](https://open-vsx.org/extension/kilocode/Kilo-Code)直接安装。 + +1. 打开编辑器 +2. 进入扩展视图（侧边栏图标或快捷键 `Ctrl+Shift-X` / `Cmd+Shift-X`） +3. 编辑器应已预配置Open VSX注册表 +4. 搜索 "Kilo Code" +5. 选择扩展并点击**安装** +6. 根据提示重新加载编辑器 + +:::note +若编辑器未自动配置Open VSX，需在设置中手动配置扩展市场。具体操作请参考编辑器文档。 +::: + +## 手动安装VSIX文件 + +若需手动下载安装： + +1. **下载VSIX文件：** + * 在[Kilo Code GitHub Releases页面](https://github.com/Kilo-Org/kilocode/releases)查找正式版本 + * 从[最新版本](https://github.com/Kilo-Org/kilocode/releases/latest)下载`.vsix`文件 + +2. **在VS Code中安装：** + * 打开VS Code + * 进入扩展视图 + * 点击扩展视图右上角的"..."菜单 + * 选择"从VSIX安装..." + * 选择已下载的`.vsix`文件 + +VS Code的从VSIX安装对话框 +*通过VS Code的"从VSIX安装"对话框进行安装* + +## 故障排除 + +**扩展不可见** +* 重启VS Code +* 检查扩展列表确认Kilo Code已启用 +* 尝试禁用后重新启用扩展 +* 在输出面板查看错误日志（查看 → 输出，选择"Kilo Code"） + +**安装问题** +* 确保网络连接稳定 +* 确认VS Code版本≥1.84.0 +* 若无法访问VS Code应用商店，尝试Open VSX方式 + +## 获取支持 + +若遇到其他问题： + +* 加入[Discord社区](https://kilocode.ai/discord)获取实时支持 +* 在[GitHub](https://github.com/Kilo-Org/kilocode/issues)提交问题报告 +* 访问[Reddit社区](https://www.reddit.com/r/KiloCode) \ No newline at end of file diff --git a/docs/zh-CN/getting-started/setting-up.mdx b/docs/zh-CN/getting-started/setting-up.mdx new file mode 100644 index 0000000..be34fd6 --- /dev/null +++ b/docs/zh-CN/getting-started/setting-up.mdx @@ -0,0 +1,41 @@ +--- +sidebar_label: 初始设置 +--- + +import { DISCORD_URL } from '@site/src/constants.ts' +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; + +export const FreeTierAmount = () => { + const {siteConfig} = useDocusaurusContext(); + return siteConfig.customFields.freeTierAmount; +}; + +# 设置Kilo Code + +注册Kilo Code时，你将获得**价值的免费token**作为启动资源。领取免费token的步骤： + +1. 完成注册流程 +2. 立即获得$5或$20的免费token +3. 要获取完整的额度，需要验证信用卡信息（仅用于身份验证） + +:::note 关于临时预授权 +为保护社区并确保服务质量，注册时会临时冻结信用卡$10额度。此预授权通常持续一周左右，**不会实际扣款**。此措施旨在防止免费资源滥用，同时确保正常用户获得最佳体验。我们正在努力在未来取消此限制。 +::: + +## 注册流程 + +Kilo Code提供简单的注册流程，通过你的账号即可使用前沿的编程模型： + +1. 在扩展中点击"免费试用Kilo Code" +2. 使用Google账号登录kilocode.ai +3. kilocode.ai将提示打开Visual Studio Code + * 在网页版IDE中使用时，需要手动复制API密钥 +4. 允许打开VS Code后，还需允许VS Code打开授权URL + +Kilo Code注册流程演示 + +完成！现在可以开始你的[第一个任务](/getting-started/your-first-task) + +:::tip 需要帮助？ +如有任何定价或token相关问题，请联系[支持团队](mailto:hi@kilocode.ai)或加入我们的Discord社区。 +::: \ No newline at end of file diff --git a/docs/zh-CN/getting-started/your-first-task.md b/docs/zh-CN/getting-started/your-first-task.md new file mode 100644 index 0000000..64283da --- /dev/null +++ b/docs/zh-CN/getting-started/your-first-task.md @@ -0,0 +1,70 @@ +--- +sidebar_label: 第一个任务 +--- + +# 开始你的第一个Kilo Code任务 + +完成[初始设置](/getting-started/setting-up)后，即可开始使用Kilo Code！本指南将引导你完成第一次交互。 + +## 第一步：打开Kilo Code面板 + +点击VS Code主侧边栏（窗口侧边的垂直栏）中的Kilo Code图标（）打开聊天界面。如果看不到图标，请确认扩展已[安装](/getting-started/installing)并启用。 + +VS Code主侧边栏中的Kilo Code图标 +*主侧边栏中的Kilo Code图标可打开聊天界面* + +## 第二步：输入你的任务 + +在面板底部的聊天框中，清晰简洁地描述你希望Kilo Code完成的操作。有效任务的示例： + +* "创建名为`hello.txt`的文件，内容为'Hello, world!'" +* "编写一个两数相加的Python函数" +* "创建一个标题为'Kilo测试'的简单网站HTML文件" + +无需特殊命令或语法——使用普通英语即可。 + +在Kilo Code聊天界面中输入任务 +*用自然语言输入任务 - 无需特殊语法* + +## 第三步：发送任务 + +按Enter键或点击输入框右侧的发送图标（）。 + +## 第四步：审核并批准操作 + +Kilo Code分析你的请求后会提出具体操作建议，可能包括： + +* **读取文件**：显示需要访问的文件内容 +* **写入文件**：展示变更差异（绿色为新增行，红色为删除行） +* **执行命令**：显示将在终端运行的精确命令 +* **使用浏览器**：概述浏览器操作（点击、输入等） +* **提问澄清**：需要时请求更多信息以继续 + +审核文件创建操作建议 +*Kilo Code明确显示将要执行的操作并等待你的批准* + +* 在**Code**模式下，默认启用许多代码编写功能 +* 在**Architect**和**Ask**模式下，代理不会编写任何代码 + +:::tip +自主程度可配置，你可以让代理更自主或更受限。 + +了解更多关于[使用模式](/basic-usage/using-modes)和[自动批准操作](/features/auto-approving-actions)。 +::: + +## 第五步：迭代操作 + +Kilo Code以迭代方式工作。每个操作后都会等待你的反馈，然后再提出下一步建议。持续这个"审核-批准"循环直到任务完成。 + +展示迭代过程的最终任务结果 +*任务完成后，Kilo Code显示最终结果并等待下一条指令* + +## 总结 + +你已完成第一个Kilo Code任务！通过这个过程，你已了解： + +* 如何使用自然语言与Kilo Code交互 +* 让你保持控制的基于批准的工作流 +* Kilo Code用于逐步解决问题的迭代方法 + +这种迭代的、基于批准的工作流是Kilo Code的核心——让AI处理编码的繁琐部分，同时你保持完全监督。现在你已掌握基础知识，可以尝试更复杂的任务，探索不同的[模式](/basic-usage/using-modes)进行专门的工作流，或试用[自动批准功能](/features/auto-approving-actions)来加速重复性任务。 \ No newline at end of file diff --git a/docs/zh-CN/index.mdx b/docs/zh-CN/index.mdx new file mode 100644 index 0000000..afda9fa --- /dev/null +++ b/docs/zh-CN/index.mdx @@ -0,0 +1,82 @@ +--- +sidebar_label: 欢迎 +--- + +import { DISCORD_URL, REDDIT_URL, GITHUB_ISSUES_MAIN_URL, GITHUB_FEATURES_URL, YOUTUBE_URL } from '@site/src/constants.ts' +import Image from '@site/src/components/Image'; + +# Kilo Code 文档 + +Kilo Code 是一个开源的 AI 助手 VS Code 扩展。它通过生成代码、自动化任务和提供建议来帮助你更高效地编写代码。 + +## Kilo Code 能做什么？ + +- 🚀 **生成代码**：根据自然语言描述生成代码 +- 🔧 **重构与调试**：优化现有代码并修复问题 +- 📝 **编写与更新**：创建和更新文档 +- 🤔 **回答问题**：解答关于代码库的疑问 +- 🔄 **自动化**：自动化重复性任务 +- 🏗️ **创建**：新建文件和项目 + +## 快速开始 + +1. [安装 Kilo Code](/getting-started/installing) +2. [设置 Kilo Code](/getting-started/setting-up) +3. [尝试你的首个任务](/getting-started/your-first-task) + +## 功能 + +展示 Kilo Code 部分功能的 GIF + +### 基础功能 + +你通过[聊天界面](/basic-usage/the-chat-interface)与 Kilo Code 交互 - 只需输入你的需求，Kilo Code 将使用最新的编码优化 AI 模型来满足你的请求。你可以切换[模式](/basic-usage/using-modes)以让 Kilo Code 以不同的方式工作，控制 Kilo Code 可以执行的操作，并通过[代码操作](/features/code-actions)直接与你的代码交互。 + +### 使用 Kilo Code + +#### 多种模式 +Kilo Code 通过专门的[模式](/basic-usage/using-modes)适应你的需求： +- [**Code 模式：**](/basic-usage/using-modes#code-mode-default) 用于通用编码任务 +- [**Architect 模式：**](/basic-usage/using-modes#architect-mode) 用于规划和技术领导 +- [**Ask 模式：**](/basic-usage/using-modes#ask-mode) 用于回答问题并提供信息 +- [**Debug 模式：**](/basic-usage/using-modes#debug-mode) 用于系统化问题诊断 +- **[自定义模式](/features/custom-modes)：** 创建无限数量的专门角色，用于安全审计、性能优化、文档编写或任何其他任务 + +#### 核心工具 +Kilo Code 配备了强大的[工具](/features/tools/tool-use-overview)，可以： +- [读取](/features/tools/read-file)和[写入](/features/tools/write-to-file)项目中的文件 +- 在你的 VS Code 终端中[执行命令](/features/tools/execute-command) +- [控制网页浏览器](/features/tools/browser-action) +- [提问跟进问题](/features/tools/ask-followup-question) +- [搜索你的代码库](/features/tools/search-files) + +查看完整的[工具参考](/features/tools/tool-use-overview)以了解所有可用工具。 + +### 扩展 Kilo Code +- **[MCP（模型上下文协议）](/features/mcp/overview)：** 添加无限自定义工具，集成外部 API，连接数据库，或创建专门的开发工具 +- **[本地模型](/advanced-usage/local-models)：** 使用本地 AI 模型运行 Kilo Code，以实现离线使用或增强隐私 + +### 自定义 Kilo Code +通过以下方式让 Kilo Code 按照你的方式工作： +- [设置管理](/features/settings-management)来配置你的体验 +- [自定义模式](/features/custom-modes)用于专门任务 +- [自定义规则](/advanced-usage/custom-rules)用于项目特定规则 +- [自定义指令](/advanced-usage/custom-instructions)用于全局插件范围内的指令 +- [API 配置配置文件](/features/api-configuration-profiles)用于不同的模型提供商 +- [自动批准设置](/features/auto-approving-actions)用于更快的工作流程 + +## 资源 + +### 文档 +- [使用 Kilo Code](/basic-usage/the-chat-interface) - 学习基础知识 +- [核心概念](/features/auto-approving-actions) - 掌握关键功能 +- [高级用法](/advanced-usage/prompt-engineering) - 进一步提升你的技能 +- [常见问题解答](/faq) - 获取常见问题的答案 + +### 社区 +- **Discord：** 加入我们的 Discord 服务器以获取实时帮助和讨论 +- **Reddit：** 访问我们的 subreddit以分享经验和技巧 +- **YouTube：** 查看我们的 YouTube以学习使用 Kilo Code 的实践技能 +- **GitHub：** 在问题页面报告问题或在功能请求页面提出建议 + +准备好开始了吗？点击下方的**下一步**按钮，开启你的 Kilo Code 之旅！ \ No newline at end of file diff --git a/docs/zh-CN/providers/anthropic.md b/docs/zh-CN/providers/anthropic.md new file mode 100644 index 0000000..263ec4d --- /dev/null +++ b/docs/zh-CN/providers/anthropic.md @@ -0,0 +1,44 @@ +--- +sidebar_label: Anthropic +--- + +# 在 Kilo Code 中使用 Anthropic + +Anthropic 是一家专注于 AI 安全和研究的公司，致力于构建可靠、可解释且可控的 AI 系统。他们的 Claude 模型以强大的推理能力、实用性和诚实性著称。 + +**官网:** [https://www.anthropic.com/](https://www.anthropic.com/) + +## 获取 API 密钥 + +1. **注册/登录:** 访问 [Anthropic 控制台](https://console.anthropic.com/)。创建账户或登录现有账户 +2. **导航至 API 密钥:** 进入 [API keys](https://console.anthropic.com/settings/keys) 页面 +3. **创建密钥:** 点击 "Create Key"。为密钥命名（如 "Kilo Code"） +4. **复制密钥:** **重要:** 立即复制 API 密钥，之后将无法再次查看。请妥善保存 + +## 支持的模型 + +Kilo Code 支持以下 Anthropic Claude 模型： + +* `claude-3-7-sonnet-20250219` (推荐) +* `claude-3-7-sonnet-20250219:thinking` (扩展思考版) +* `claude-3-5-sonnet-20241022` +* `claude-3-5-haiku-20241022` +* `claude-3-opus-20240229` +* `claude-3-haiku-20240307` + +查看 [Anthropic 模型文档](https://docs.anthropic.com/en/docs/about-claude/models) 获取各模型能力的详细信息 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 () +2. **选择提供商:** 在 "API Provider" 下拉菜单中选择 "Anthropic" +3. **输入 API 密钥:** 将 Anthropic API 密钥粘贴到 "Anthropic API Key" 字段 +4. **选择模型:** 从 "Model" 下拉列表中选择所需的 Claude 模型 +5. **(可选) 自定义基础 URL:** 如需使用自定义 Anthropic API 基础 URL，勾选 "Use custom base URL" 并输入 URL。大多数用户无需修改此项 + +## 提示与注意事项 + +* **提示缓存:** Claude 3 模型支持 [提示缓存](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)，可显著降低重复提示的成本和延迟 +* **上下文窗口:** Claude 模型具有大容量上下文窗口 (200,000 tokens)，可在提示中包含大量代码和上下文 +* **定价:** 参考 [Anthropic 定价](https://www.anthropic.com/pricing) 页面获取最新价格信息 +* **速率限制:** Anthropic 根据 [使用层级](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier) 设有严格速率限制。如频繁遇到限制，请联系 Anthropic 销售或通过 [OpenRouter](/providers/openrouter) 等其它提供商访问 Claude \ No newline at end of file diff --git a/docs/zh-CN/providers/bedrock.md b/docs/zh-CN/providers/bedrock.md new file mode 100644 index 0000000..1159456 --- /dev/null +++ b/docs/zh-CN/providers/bedrock.md @@ -0,0 +1,91 @@ +--- +sidebar_label: AWS Bedrock +--- + +# 在Kilo Code中使用AWS Bedrock + +Kilo Code支持通过Amazon Bedrock访问模型，这是一个完全托管的服务，通过单一API提供来自领先AI公司的高性能基础模型(FMs)。 + +**官网:** [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/) + +## 前提条件 + +* **AWS账户:** 需要有效的AWS账户 +* **Bedrock访问权限:** 必须申请并获得Amazon Bedrock的访问权限。详见[AWS Bedrock文档](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html) +* **模型访问权限:** 需要在Bedrock中申请使用特定模型(如Anthropic Claude)的权限 +* **安装AWS CLI:** 使用AWS CLI配置账户认证 + ```bash + aws configure + ``` + +## 获取凭证 + +有两种主要配置方式： + +1. **AWS访问密钥(推荐用于开发):** + * 创建具有必要权限的IAM用户(至少需要`bedrock:InvokeModel`) + * 生成该用户的访问密钥ID和秘密访问密钥 + * (可选)根据IAM配置需要创建会话令牌 +2. **AWS配置文件:** + * 使用AWS CLI或手动编辑AWS凭证文件配置配置文件。详见[AWS CLI文档](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) + +## 支持的模型 + +根据源代码，Kilo Code支持通过Bedrock访问以下模型： + +* **Amazon:** + * `amazon.nova-pro-v1:0` + * `amazon.nova-pro-latency-optimized-v1:0` + * `amazon.nova-lite-v1:0` + * `amazon.nova-micro-v1:0` + * `amazon.titan-text-lite-v1:0` + * `amazon.titan-text-express-v1:0` + * `amazon.titan-text-embeddings-v1:0` + * `amazon.titan-text-embeddings-v2:0` +* **Anthropic:** + * `anthropic.claude-3-7-sonnet-20250219-v1:0` + * `anthropic.claude-3-5-sonnet-20241022-v2:0` + * `anthropic.claude-3-5-haiku-20241022-v1:0` + * `anthropic.claude-3-5-sonnet-20240620-v1:0` + * `anthropic.claude-3-opus-20240229-v1:0` + * `anthropic.claude-3-sonnet-20240229-v1:0` + * `anthropic.claude-3-haiku-20240307-v1:0` + * `anthropic.claude-2-1-v1:0` + * `anthropic.claude-2-0-v1:0` + * `anthropic.claude-instant-v1:0` +* **DeepSeek:** + * `deepseek.r1-v1:0` +* **Meta:** + * `meta.llama3-3-70b-instruct-v1:0` + * `meta.llama3-2-90b-instruct-v1:0` + * `meta.llama3-2-11b-instruct-v1:0` + * `meta.llama3-2-3b-instruct-v1:0` + * `meta.llama3-2-1b-instruct-v1:0` + * `meta.llama3-1-405b-instruct-v1:0` + * `meta.llama3-1-70b-instruct-v1:0` + * `meta.llama3-1-70b-instruct-latency-optimized-v1:0` + * `meta.llama3-1-8b-instruct-v1:0` + * `meta.llama3-70b-instruct-v1:0` + * `meta.llama3-8b-instruct-v1:0` + +请参考[Amazon Bedrock文档](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html)获取最新可用模型及其ID列表。配置Kilo Code时请使用*模型ID*而非模型名称。 + +## 在Kilo Code中配置 + +1. **打开Kilo Code设置:** 点击Kilo Code面板中的齿轮图标() +2. **选择提供商:** 在"API Provider"下拉菜单中选择"Bedrock" +3. **选择认证方式:** + * **AWS凭证:** + * 输入"AWS Access Key"和"AWS Secret Key" + * (可选)如果使用临时凭证，输入"AWS Session Token" + * **AWS配置文件:** + * 输入AWS配置文件名称(如"default") +4. **选择区域:** 选择Bedrock服务可用的AWS区域(如"us-east-1") +5. **(可选)跨区域推理:** 如果要访问与配置的AWS区域不同的区域中的模型，请勾选"Use cross-region inference" +6. **选择模型:** 从"Model"下拉菜单中选择所需模型 + +## 提示与注意事项 + +* **权限:** 确保IAM用户或角色具有调用Bedrock模型所需的权限，需要`bedrock:InvokeModel`权限 +* **定价:** 参考[Amazon Bedrock定价](https://aws.amazon.com/bedrock/pricing/)页面了解模型费用详情 +* **跨区域推理:** 使用跨区域推理可能会导致延迟增加 \ No newline at end of file diff --git a/docs/zh-CN/providers/deepseek.md b/docs/zh-CN/providers/deepseek.md new file mode 100644 index 0000000..06f0c3c --- /dev/null +++ b/docs/zh-CN/providers/deepseek.md @@ -0,0 +1,33 @@ +--- +sidebar_label: DeepSeek +--- + +# 在Kilo Code中使用DeepSeek + +Kilo Code支持通过DeepSeek API访问模型，包括`deepseek-chat`和`deepseek-reasoner`。 + +**官方网站:** [https://platform.deepseek.com/](https://platform.deepseek.com/) + +## 获取API Key + +1. **注册/登录:** 访问[DeepSeek平台](https://platform.deepseek.com/)。创建账号或登录。 +2. **导航到API密钥:** 在平台的[API密钥](https://platform.deepseek.com/api_keys)部分找到你的API密钥。 +3. **创建密钥:** 点击"Create new API key"。为密钥起一个描述性名称(例如"Kilo Code")。 +4. **复制密钥:** **重要:** 立即复制API密钥，之后将无法再次查看。请安全存储。 + +## 支持的模型 + +Kilo Code支持以下DeepSeek模型： + +* `deepseek-chat` (推荐用于编码任务) +* `deepseek-reasoner` (推荐用于推理任务) + +## 在Kilo Code中配置 + +1. **打开Kilo Code设置:** 点击Kilo Code面板中的齿轮图标() +2. **选择提供商:** 从"API Provider"下拉菜单中选择"DeepSeek" +3. **输入API密钥:** 将DeepSeek API密钥粘贴到"DeepSeek API Key"字段 +4. **选择模型:** 从"Model"下拉菜单中选择所需模型 + +## 提示和注意事项 +* **价格:** 参考[DeepSeek定价](https://api-docs.deepseek.com/quick_start/pricing/)页面了解模型费用详情 \ No newline at end of file diff --git a/docs/zh-CN/providers/gemini.md b/docs/zh-CN/providers/gemini.md new file mode 100644 index 0000000..5cc213d --- /dev/null +++ b/docs/zh-CN/providers/gemini.md @@ -0,0 +1,47 @@ +--- +sidebar_label: Google Gemini +--- + +# 在Kilo Code中使用Google Gemini + +Kilo Code通过Google AI Gemini API支持Google的Gemini系列模型。 + +**官网:** [https://ai.google.dev/](https://ai.google.dev/) + +## 获取API密钥 + +1. **访问Google AI Studio:** 打开[https://ai.google.dev/](https://ai.google.dev/) +2. **登录:** 使用Google账号登录 +3. **创建API密钥:** 点击左侧菜单中的"Create API key" +4. **复制API密钥:** 复制生成的API密钥 + +## 支持的模型 + +Kilo Code支持以下Gemini模型： + +* `gemini-2.5-pro-exp-03-25` +* `gemini-2.0-flash-001` +* `gemini-2.0-flash-lite-preview-02-05` +* `gemini-2.0-pro-exp-02-05` +* `gemini-2.0-flash-thinking-exp-01-21` +* `gemini-2.0-flash-thinking-exp-1219` +* `gemini-2.0-flash-exp` +* `gemini-1.5-flash-002` +* `gemini-1.5-flash-exp-0827` +* `gemini-1.5-flash-8b-exp-0827` +* `gemini-1.5-pro-002` +* `gemini-1.5-pro-exp-0827` +* `gemini-exp-1206` + +参考[Gemini文档](https://ai.google.dev/models/gemini)获取各模型详细信息。 + +## 在Kilo Code中的配置 + +1. **打开Kilo Code设置:** 点击Kilo Code面板中的齿轮图标() +2. **选择提供商:** 在"API Provider"下拉菜单中选择"Google Gemini" +3. **输入API密钥:** 将Gemini API密钥粘贴到"Gemini API Key"字段 +4. **选择模型:** 从"Model"下拉菜单中选择所需的Gemini模型 + +## 提示与注意事项 + +* **定价:** Gemini API使用根据输入和输出的token计费。参考[Gemini定价页面](https://ai.google.dev/pricing)获取详细信息。 \ No newline at end of file diff --git a/docs/zh-CN/providers/glama.md b/docs/zh-CN/providers/glama.md new file mode 100644 index 0000000..7e0ff6a --- /dev/null +++ b/docs/zh-CN/providers/glama.md @@ -0,0 +1,37 @@ +--- +sidebar_label: Glama +--- + +# 使用 Glama 与 Kilo Code + +Glama 通过统一的 API 提供了对多种语言模型的访问，包括来自 Anthropic、OpenAI 和其他提供商的模型。它提供了诸如提示缓存和成本跟踪等功能。 + +**网站：** [https://glama.ai/](https://glama.ai/) + +## 获取 API 密钥 + +1. **注册/登录：** 前往 [Glama 注册页面](https://glama.ai/sign-up)。使用您的 Google 账户或姓名/电子邮件/密码注册。 +2. **获取 API 密钥：** 注册后，导航到 [API 密钥](https://glama.ai/settings/gateway/api-keys) 页面以获取 API 密钥。 +3. **复制密钥：** 复制显示的 API 密钥。 + +## 支持的模型 + +Kilo Code 会自动尝试从 Glama API 获取可用模型的列表。通常通过 Glama 提供的一些模型包括： + +* **Anthropic Claude 模型：** （例如，`anthropic/claude-3-5-sonnet`）这些通常推荐用于与 Kilo Code 的最佳性能。 +* **OpenAI 模型：** （例如，`openai/o3-mini-high`） +* **其他提供商和开源模型** + +请参阅 [Glama 文档](https://glama.ai/models) 获取最新支持的模型列表。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置：** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商：** 从 "API 提供商" 下拉菜单中选择 "Glama"。 +3. **输入 API 密钥：** 将您的 Glama API 密钥粘贴到 "Glama API 密钥" 字段中。 +4. **选择模型：** 从 "模型" 下拉菜单中选择您想要的模型。 + +## 提示和注意事项 + +* **定价：** Glama 采用按使用量计费的模式。根据您选择的模型，定价会有所不同。 +* **提示缓存：** Glama 支持提示缓存，这可以显著降低成本并提高重复提示的性能。 \ No newline at end of file diff --git a/docs/zh-CN/providers/human-relay.md b/docs/zh-CN/providers/human-relay.md new file mode 100644 index 0000000..cfb1db8 --- /dev/null +++ b/docs/zh-CN/providers/human-relay.md @@ -0,0 +1,29 @@ +# 人工中继提供商 + +人工中继提供商允许您在不需要 API 密钥的情况下，使用基于 Web 的 AI 模型（如 ChatGPT 或 Claude）与 Kilo Code 配合使用。相反，它依赖于您在 Kilo Code 和 AI 的 Web 界面之间手动传递消息。 + +## 工作原理 + +1. **选择人工中继：** 在 Kilo Code 的设置中选择 "人工中继" 作为您的 API 提供商。无需 API 密钥。 +2. **发起请求：** 像往常一样开始与 Kilo Code 的聊天或任务。 +3. **对话框提示：** 在 VS Code 中会弹出一个对话框。您发送给 AI 的消息会自动复制到剪贴板。 +4. **粘贴到 Web AI：** 前往您选择的 AI 的 Web 界面（例如，chat.openai.com, claude.ai），并将剪贴板中的消息粘贴到聊天输入框中。 +5. **复制 AI 的回复：** 当 AI 回复后，复制其完整的回复文本。 +6. **粘贴回 Kilo Code：** 返回 VS Code 中的对话框，将 AI 的回复粘贴到指定字段中，然后点击“确认”。 +7. **继续：** Kilo Code 会像处理直接来自 API 的响应一样处理该回复。 + +## 使用场景 + +此提供商在以下情况下有用： + +* 您想使用不提供直接 API 访问的模型。 +* 您不希望管理 API 密钥。 +* 您需要利用某些 AI 模型的 Web UI 中提供的特定功能或上下文。 + +## 限制 + +* **手动操作：** 需要在 VS Code 和浏览器之间不断进行复制粘贴。 +* **交互速度较慢：** 来回传递的过程比直接 API 集成要慢得多。 +* **可能出现错误：** 手动复制粘贴可能会引入错误或遗漏。 + +当使用特定 Web AI 的好处超过了手动中继过程的不便时，请选择此提供商。 \ No newline at end of file diff --git a/docs/zh-CN/providers/kilocode.md b/docs/zh-CN/providers/kilocode.md new file mode 100644 index 0000000..cc6a9b5 --- /dev/null +++ b/docs/zh-CN/providers/kilocode.md @@ -0,0 +1,45 @@ +--- +sidebar_label: Kilo Code +--- + +# 使用 Kilo Code 的 API 提供商 + +:::warning + +此文档目前仅针对 Anthropic 和 Claude Sonnet 3.7，并不反映使用 Kilo Code 作为提供商的简单性 - 它只是一个占位符 + +::: + +Anthropic 是一家 AI 安全和研究公司，致力于构建可靠、可解释和可控制的 AI 系统。他们的 Claude 模型以其强大的推理能力、帮助性和诚实性而闻名。 + +**网站：** [https://www.anthropic.com/](https://www.anthropic.com/) + +## 获取 API 密钥 + +1. **注册/登录：** 前往 [Anthropic 控制台](https://console.anthropic.com/)。创建账户或登录。 +2. **导航到 API 密钥：** 前往 [API 密钥](https://console.anthropic.com/settings/keys) 部分。 +3. **创建密钥：** 点击“创建密钥”。为您的密钥命名（例如，“Kilo Code”）。 +4. **复制密钥：** **重要：** 立即复制 API 密钥。您将无法再次查看它。请妥善保存。 + +## 支持的模型 + +Kilo Code 支持以下 Anthropic Claude 模型： + +* `claude-3-7-sonnet-20250219` + +有关每个模型功能的更多详细信息，请参阅 [Anthropic 的模型文档](https://docs.anthropic.com/en/docs/about-claude/models)。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置：** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商：** 从 "API 提供商" 下拉菜单中选择 "Anthropic"。 +3. **输入 API 密钥：** 将您的 Anthropic API 密钥粘贴到 "Anthropic API 密钥" 字段中。 +4. **选择模型：** 从 "模型" 下拉菜单中选择您想要的 Claude 模型。 +5. **（可选）自定义基础 URL：** 如果您需要为 Anthropic API 使用自定义基础 URL，请勾选“使用自定义基础 URL”并输入 URL。大多数人不需要调整此项。 + +## 提示和注意事项 + +* **提示缓存：** Claude 3 模型支持 [提示缓存](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)，这可以显著降低重复提示的成本和延迟。 +* **上下文窗口：** Claude 模型具有较大的上下文窗口（200,000 个 token），允许您在提示中包含大量代码和上下文。 +* **定价：** 请参阅 [Anthropic 定价](https://www.anthropic.com/pricing) 页面获取最新定价信息。 +* **速率限制：** Anthropic 根据 [使用层级](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier) 设置了严格的速率限制。如果您反复遇到速率限制，请考虑联系 Anthropic 销售或通过 [OpenRouter](/providers/openrouter) 或 [Requesty](/providers/requesty) 等其他提供商访问 Claude。 \ No newline at end of file diff --git a/docs/zh-CN/providers/lmstudio.md b/docs/zh-CN/providers/lmstudio.md new file mode 100644 index 0000000..bfb49c5 --- /dev/null +++ b/docs/zh-CN/providers/lmstudio.md @@ -0,0 +1,41 @@ +--- +sidebar_label: LM Studio +--- + +# 使用 LM Studio 的 API 提供商 + +LM Studio 是一个本地运行的 AI 模型管理工具，允许您在本地计算机上运行各种开源 LLM 模型，并为其提供 API 访问。 + +**网站：** [https://lmstudio.ai/](https://lmstudio.ai/) + +## 设置 LM Studio + +1. **下载并安装：** 从 [LM Studio 网站](https://lmstudio.ai/) 下载并安装适用于您操作系统的版本。 +2. **下载模型：** 在 LM Studio 中，从 Hugging Face 下载您想要使用的模型。建议使用经过测试的模型，如 Mistral 7B 或 Llama 2。 +3. **启动服务器：** 在 LM Studio 中，点击“Server”选项卡，然后点击“Start Server”。默认情况下，服务器将在 `http://localhost:1234` 上运行。 + +## 支持的模型 + +Kilo Code 支持以下 LM Studio 模型： + +* `mistral-7b-instruct-v0.1` +* `llama-2-7b-chat` +* `llama-2-13b-chat` +* `llama-2-70b-chat` + +有关每个模型功能的更多详细信息，请参阅 [LM Studio 的文档](https://lmstudio.ai/docs)。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置：** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商：** 从 "API 提供商" 下拉菜单中选择 "LM Studio"。 +3. **输入 API 密钥：** 将您的 LM Studio API 密钥粘贴到 "LM Studio API 密钥" 字段中。如果未设置 API 密钥，可以留空。 +4. **选择模型：** 从 "模型" 下拉菜单中选择您想要的模型。 +5. **（可选）自定义基础 URL：** 如果您需要为 LM Studio API 使用自定义基础 URL，请勾选“使用自定义基础 URL”并输入 URL。大多数人不需要调整此项。 + +## 提示和注意事项 + +* **本地运行：** LM Studio 允许您在本地运行模型，这对于隐私和安全性至关重要。 +* **模型选择：** 选择适合您任务的模型大小。较大的模型需要更多的计算资源，但可能提供更好的结果。 +* **硬件要求：** 确保您的计算机具有足够的 RAM 和 GPU 内存来运行您选择的模型。 +* **速率限制：** LM Studio 没有严格的速率限制，但您的硬件可能会限制性能。 \ No newline at end of file diff --git a/docs/zh-CN/providers/mistral.md b/docs/zh-CN/providers/mistral.md new file mode 100644 index 0000000..64f3381 --- /dev/null +++ b/docs/zh-CN/providers/mistral.md @@ -0,0 +1,53 @@ +--- +sidebar_label: Mistral AI +--- + +# 在Kilo Code中使用Mistral AI + +Kilo Code支持通过Mistral AI API访问模型，包括标准Mistral模型和专门用于代码的Codestral模型。 + +**官网:** [https://mistral.ai/](https://mistral.ai/) + +## 获取API密钥 + +1. **注册/登录:** 访问[Mistral控制台](https://console.mistral.ai/)。创建账户或登录。您可能需要完成验证流程。 +2. **创建API密钥:** + - [La Plateforme API密钥](https://console.mistral.ai/api-keys/) 和/或 + - [Codestral API密钥](https://console.mistral.ai/codestral) + +## 支持的模型 + +Kilo Code支持以下Mistral模型： + +| 模型ID | 默认温度 | 函数调用 | 视觉/图像支持 | +|------------------------|-------------------------|------------------|--------| +| codestral-latest | 0.3 | ✅ | ❌ | +| mistral-large-latest | 0.7 | ✅ | ❌ | +| ministral-8b-latest | 0.3 | ✅ | ❌ | +| ministral-3b-latest | 0.3 | ✅ | ❌ | +| mistral-small-latest | 0.3 | ✅ | ❌ | +| pixtral-large-latest | 0.7 | ✅ | ✅ | + +Kilo Code中的默认模型温度为0.0，因此您应该考虑尝试[调整温度](/features/model-temperature)！ + +**注意:** 模型的可用性和规格可能会发生变化。 +请参考[Mistral AI文档](https://docs.mistral.ai/api/)和[Mistral模型概述](https://docs.mistral.ai/getting-started/models/models_overview/)获取最新信息。 + +## 在Kilo Code中配置 + +1. **打开Kilo Code设置:** 点击Kilo Code面板中的齿轮图标()。 +2. **选择提供商:** 从"API提供商"下拉菜单中选择"Mistral"。 +3. **输入API密钥:** 如果您使用`mistral`模型，请将Mistral API密钥粘贴到"Mistral API密钥"字段中。如果您打算使用`codestral-latest`，请参阅下面的"Codestral"部分。 +4. **选择模型:** 从"模型"下拉菜单中选择所需的模型。 + +## 使用Codestral + +[Codestral](https://docs.mistral.ai/capabilities/code_generation/)是一个专门用于代码生成和交互的模型。 +只有Codestral可以使用不同的端点(默认: codestral.mistral.ai)。 +对于La Platforme API密钥，请将**Codestral基础URL**更改为: https://api.mistral.ai + +要使用Codestral: + +1. **选择"Mistral"作为API提供商。** +2. **选择Codestral模型** +3. **输入您的Codestral (codestral.mistral.ai)或La Plateforme (api.mistral.ai) API密钥。** \ No newline at end of file diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md new file mode 100644 index 0000000..9238160 --- /dev/null +++ b/docs/zh-CN/providers/ollama.md @@ -0,0 +1,74 @@ +--- +侧边栏标签: Ollama +--- + +# 在Kilo Code中使用Ollama + +Kilo Code 支持通过 Ollama 在本地运行模型。这提供了隐私保护、离线访问能力，并可能降低成本，但需要更多设置且依赖高性能计算机。 + +**官方网站**：[https://ollama.com/](https://ollama.com/) + +## 安装配置Ollama + +1. **下载并安装Ollama**：从[Ollama官网](https://ollama.com/)下载对应操作系统的安装程序，按指引完成安装。确保Ollama已启动： + + ```bash + ollama serve + ``` + +2. **下载模型**：Ollama 支持多种模型，可在[Ollama模型库](https://ollama.com/library)查看可用列表。以下是推荐用于编码任务的模型： + + * `codellama:7b-code`（入门首选，模型较小） + * `codellama:13b-code`（质量更佳，模型较大） + * `codellama:34b-code`（质量最优，模型极大） + * `qwen2.5-coder:32b` + * `mistralai/Mistral-7B-Instruct-v0.1`（通用型优质模型） + * `deepseek-coder:6.7b-base`（适合编码任务） + * `llama3:8b-instruct-q5_1`（适合常规任务） + + 在终端运行以下命令下载模型： + + ```bash + ollama pull <模型名称> + ``` + + 示例： + + ```bash + ollama pull qwen2.5-coder:32b + ``` + +3. **配置模型**：默认情况下，Ollama 使用 2048 tokens的上下文窗口，这对 Kilo Code 的请求来说过小。建议至少设置为12k，理想情况下为32k。配置模型需设置参数并保存副本： + + - 加载模型（以`qwen2.5-coder:32b`为例）： + + ```bash + ollama run qwen2.5-coder:32b + ``` + + - 修改上下文大小参数： + + ```bash + /set parameter num_ctx 32768 + ``` + + - 使用新名称保存模型： + + ```bash + /save 你的模型名称 + ``` + +4. **配置Kilo Code**： + * 打开Kilo Code侧边栏（图标）。 + * 点击设置齿轮图标（）。 + * 选择“ollama”作为API提供商。 + * 输入上一步设置的模型名称（如`你的模型名称`）。 + * （可选）若Ollama运行在其他设备上，可配置基础URL（默认：`http://localhost:11434`）。 + * （可选）在高级设置中配置模型上下文大小，以便Kilo Code管理滑动窗口。 + +## 注意事项 + +* **资源要求**：本地运行大型语言模型需要较高资源配置，请确保计算机满足所选模型的最低要求。 +* **模型选择**：建议尝试不同模型，找到最符合需求的选项。 +* **离线使用**：模型下载完成后，Kilo Code 可离线使用该模型。 +* **Ollama文档**：更多关于安装、配置和使用Ollama的信息，请参考[Ollama官方文档](https://ollama.com/docs)。 diff --git a/docs/zh-CN/providers/openai-compatible.md b/docs/zh-CN/providers/openai-compatible.md new file mode 100644 index 0000000..b24ef40 --- /dev/null +++ b/docs/zh-CN/providers/openai-compatible.md @@ -0,0 +1,60 @@ +--- +sidebar_label: OpenAI 兼容 +--- + +# 使用 OpenAI 兼容的提供商与 Kilo Code + +Kilo Code 支持多种提供 OpenAI API 标准兼容的 AI 模型提供商。这意味着你可以使用 *除了* OpenAI 之外的其他提供商的模型，同时仍然使用熟悉的 API 接口。这包括以下提供商： + +* **本地模型** 通过 Ollama 和 LM Studio 等工具运行（在单独的部分中介绍）。 +* **云提供商** 如 Perplexity、Together AI、Anyscale 等。 +* **任何其他** 提供 OpenAI 兼容 API 端点的提供商。 + +本文档重点介绍 *除了* 官方 OpenAI API 之外的提供商的设置（官方 OpenAI API 有[专门的配置页面](/providers/openai)）。 + +## 通用配置 + +使用 OpenAI 兼容提供商的关键是配置两个主要设置： + +1. **基础 URL:** 这是提供商的 API 端点。它 *不会* 是 `https://api.openai.com/v1`（这是官方 OpenAI API 的地址）。 +2. **API 密钥:** 这是你从提供商处获取的密钥。 +3. **模型 ID:** 这是特定模型的名称。 + +你可以在 Kilo Code 设置面板中找到这些设置（点击 图标）： + +* **API 提供商:** 选择 "OpenAI 兼容"。 +* **基础 URL:** 输入你选择的提供商提供的基础 URL。**这非常关键。** +* **API 密钥:** 输入你的 API 密钥。 +* **模型:** 选择一个模型。 +* **模型配置:** 这允许你为模型自定义高级配置 + - 最大输出 tokens + - 上下文窗口 + - 图像支持 + - 计算机使用 + - 输入价格 + - 输出价格 + +## 支持的模型（适用于 OpenAI 原生端点） + +虽然此提供商类型允许连接到各种端点，但如果你直接连接到官方 OpenAI API（或完全镜像它的端点），Kilo Code 会根据其源代码中的 `openAiNativeModels` 定义识别以下模型 ID： + +* `o3-mini` +* `o3-mini-high` +* `o3-mini-low` +* `o1` +* `o1-preview` +* `o1-mini` +* `gpt-4.5-preview` +* `gpt-4o` +* `gpt-4o-mini` + +**注意:** 如果你使用其他 OpenAI 兼容的提供商（如 Together AI、Anyscale 等），可用的模型 ID 会有所不同。请始终参考你特定提供商的文档以获取支持的模型名称。 + +## 故障排除 + +* **"无效的 API 密钥":** 请仔细检查你是否正确输入了 API 密钥。 +* **"未找到模型":** 确保你使用的模型 ID 对你选择的提供商有效。 +* **连接错误:** 验证基础 URL 是否正确，以及你的提供商 API 是否可访问。 +* **意外结果:** 如果你得到意外的结果，请尝试使用不同的模型。 + +通过使用 OpenAI 兼容的提供商，你可以利用 Kilo Code 的灵活性与更广泛的 AI 模型。请始终参考你提供商的文档以获取最准确和最新的信息。 \ No newline at end of file diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md new file mode 100644 index 0000000..392c504 --- /dev/null +++ b/docs/zh-CN/providers/openai.md @@ -0,0 +1,44 @@ +--- +sidebar_label: OpenAI +--- + +# 在 Kilo Code 中使用 OpenAI + +Kilo Code 支持通过官方 OpenAI API 直接访问模型。 + +**官方网站:** [https://openai.com/](https://openai.com/) + +## 获取 API 密钥 + +1. **注册/登录:** 访问 [OpenAI 平台](https://platform.openai.com/)。创建账户或登录 +2. **导航到 API 密钥:** 前往 [API keys](https://platform.openai.com/api-keys) 页面 +3. **创建密钥:** 点击 "Create new secret key"。为密钥起一个描述性名称（如 "Kilo Code"） +4. **复制密钥:** **重要:** 立即复制 API 密钥。之后将无法再次查看。请安全存储 + +## 支持的模型 + +Kilo Code 支持多种 OpenAI 模型，包括： + +* `o3-mini` (中等推理能力) +* `o3-mini-high` (高推理能力) +* `o3-mini-low` (低推理能力) +* `o1` +* `o1-preview` +* `o1-mini` +* `gpt-4.5-preview` +* `gpt-4o` +* `gpt-4o-mini` + +请参考 [OpenAI 模型文档](https://platform.openai.com/docs/models) 获取最新的模型列表和能力说明。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 () +2. **选择提供商:** 从 "API Provider" 下拉菜单中选择 "OpenAI" +3. **输入 API 密钥:** 将你的 OpenAI API 密钥粘贴到 "OpenAI API Key" 字段 +4. **选择模型:** 从 "Model" 下拉菜单中选择你需要的模型 + +## 提示和注意事项 + +* **定价:** 请参考 [OpenAI 定价](https://openai.com/pricing) 页面了解模型成本详情 +* **Azure OpenAI 服务:** 如需使用 Azure OpenAI 服务，请参阅我们的 [OpenAI 兼容](/providers/openai-compatible) 提供商章节 \ No newline at end of file diff --git a/docs/zh-CN/providers/openrouter.md b/docs/zh-CN/providers/openrouter.md new file mode 100644 index 0000000..bd2b243 --- /dev/null +++ b/docs/zh-CN/providers/openrouter.md @@ -0,0 +1,37 @@ +--- +sidebar_label: OpenRouter +--- + +# 在Kilo Code中使用OpenRouter + +OpenRouter是一个AI平台，提供来自不同供应商的各种语言模型访问，所有功能都通过单一API实现。这可以简化设置并让你轻松尝试不同模型。 + +**网站:** [https://openrouter.ai/](https://openrouter.ai/) + +## 获取API密钥 + +1. **注册/登录:** 访问[OpenRouter网站](https://openrouter.ai/)。使用你的Google或GitHub账号登录。 +2. **获取API密钥:** 进入[密钥页面](https://openrouter.ai/keys)。你应该能看到列出的API密钥。如果没有，请创建新密钥。 +3. **复制密钥:** 复制API密钥。 + +## 支持的模型 + +OpenRouter支持大量且不断增长的模型。Kilo Code会自动获取可用模型列表。请参考[OpenRouter模型页面](https://openrouter.ai/models)获取完整和最新的列表。 + +## 在Kilo Code中配置 + +1. **打开Kilo Code设置:** 点击Kilo Code面板中的齿轮图标()。 +2. **选择供应商:** 从"API Provider"下拉菜单中选择"OpenRouter"。 +3. **输入API密钥:** 将OpenRouter API密钥粘贴到"OpenRouter API Key"字段。 +4. **选择模型:** 从"Model"下拉菜单中选择你需要的模型。 +5. **(可选)自定义基础URL:** 如果需要为OpenRouter API使用自定义基础URL，请勾选"Use custom base URL"并输入URL。大多数用户应留空此项。 + +## 支持的转换 + +OpenRouter提供[可选的"middle-out"消息转换](https://openrouter.ai/docs/features/message-transforms)功能，帮助处理超过模型最大上下文大小的提示。你可以通过勾选"Compress prompts and message chains to the context size"框来启用它。 + +## 提示和注意事项 + +* **模型选择:** OpenRouter提供多种模型。尝试找到最适合你需求的模型。 +* **定价:** OpenRouter根据基础模型的定价收费。详情请参阅[OpenRouter模型页面](https://openrouter.ai/models)。 +* **提示缓存:** 部分供应商支持提示缓存。请参阅OpenRouter文档了解支持的模型。 \ No newline at end of file diff --git a/docs/zh-CN/providers/requesty.md b/docs/zh-CN/providers/requesty.md new file mode 100644 index 0000000..bf39383 --- /dev/null +++ b/docs/zh-CN/providers/requesty.md @@ -0,0 +1,39 @@ +--- +sidebar_label: Requesty +--- + +# 在 Kilo Code 中使用 Requesty + +Kilo Code 支持通过 [Requesty](https://www.requesty.ai/) AI 平台访问模型。Requesty 提供了一个简单且优化的 API，用于与 150+ 大型语言模型 (LLMs) 进行交互。 + +**网站:** [https://www.requesty.ai/](https://www.requesty.ai/) + +## 获取 API 密钥 + +1. **注册/登录:** 访问 [Requesty 网站](https://www.requesty.ai/) 并创建账户或登录。 +2. **获取 API 密钥:** 您可以从 Requesty 仪表板的 [API 管理](https://app.requesty.ai/manage-api) 部分获取 API 密钥。 + +## 支持的模型 + +Requesty 提供了对多种模型的访问。Kilo Code 会自动获取最新的可用模型列表。您可以在 [模型列表](https://app.requesty.ai/router/list) 页面上查看所有可用模型的完整列表。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商:** 从 "API 提供商" 下拉菜单中选择 "Requesty"。 +3. **输入 API 密钥:** 将您的 Requesty API 密钥粘贴到 "Requesty API 密钥" 字段中。 +4. **选择模型:** 从 "模型" 下拉菜单中选择您想要的模型。 + +## 提示和注意事项 + +- **优化:** Requesty 提供了多种实时成本优化功能，以降低您的成本。 +- **统一且简化的计费:** 通过一个 [API 密钥](https://app.requesty.ai/manage-api) 无限制地访问所有提供商和模型，自动充值余额等。 +- **成本跟踪:** 通过 [成本仪表板](https://app.requesty.ai/cost-management) 或 [Requesty VS.code 扩展](https://marketplace.visualstudio.com/items?itemName=Requesty.requesty) 跟踪每个模型、编程语言、更改文件等的成本。 +- **统计和日志:** 查看您的 [编程统计仪表板](https://app.requesty.ai/usage-stats) 或查阅您的 [LLM 交互日志](https://app.requesty.ai/logs)。 +- **回退策略:** 当提供商出现故障时，通过回退策略保持您的 LLM 正常工作。 +- **提示缓存:** 一些提供商支持提示缓存。[搜索支持缓存的模型](https://app.requesty.ai/router/list)。 + +## 相关资源 + +- [Requesty Youtube 频道](https://www.youtube.com/@requestyAI): +- [Requesty Discord](https://requesty.ai/discord) \ No newline at end of file diff --git a/docs/zh-CN/providers/unbound.md b/docs/zh-CN/providers/unbound.md new file mode 100644 index 0000000..69b8785 --- /dev/null +++ b/docs/zh-CN/providers/unbound.md @@ -0,0 +1,30 @@ +--- +sidebar_label: Unbound +--- + +# 在 Kilo Code 中使用 Unbound + +Kilo Code 支持通过 [Unbound](https://getunbound.ai/) 访问模型，该平台专注于提供安全可靠的多种大型语言模型 (LLMs) 访问。Unbound 充当网关，允许您使用来自 Anthropic 和 OpenAI 等提供商的模型，而无需直接管理多个 API 密钥和配置。他们强调企业级的安全和合规功能。 + +**网站:** [https://getunbound.ai/](https://getunbound.ai/) + +## 创建账户 + +1. **注册/登录:** 访问 [Unbound 网关](https://gateway.getunbound.ai)。创建账户或登录。 +2. **创建应用程序:** 转到 [应用程序](https://gateway.getunbound.ai/ai-gateway-applications) 页面并点击 "创建应用程序" 按钮。 +3. **复制 API 密钥:** 将 API 密钥复制到剪贴板。 + +## 支持的模型 + +Unbound 允许您在应用程序中配置支持的模型列表，Kilo Code 会自动从 Unbound API 获取可用模型列表。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商:** 从 "API 提供商" 下拉菜单中选择 "Unbound"。 +3. **输入 API 密钥:** 将您的 Unbound API 密钥粘贴到 "Unbound API 密钥" 字段中。 +4. **选择模型:** 从 "模型" 下拉菜单中选择您想要的模型。 + +## 提示和注意事项 + +* **安全重点:** Unbound 强调企业级的安全功能。如果您的组织对 AI 使用有严格的安全要求，Unbound 可能是一个不错的选择。 \ No newline at end of file diff --git a/docs/zh-CN/providers/vertex.md b/docs/zh-CN/providers/vertex.md new file mode 100644 index 0000000..69912af --- /dev/null +++ b/docs/zh-CN/providers/vertex.md @@ -0,0 +1,54 @@ +--- +sidebar_label: GCP Vertex AI +--- + +# 在 Kilo Code 中使用 GCP Vertex AI + +Kilo Code 支持通过 Google Cloud Platform 的 Vertex AI 访问模型，这是一个托管的机器学习平台，提供对多种基础模型的访问，包括 Anthropic 的 Claude 系列。 + +**网站:** [https://cloud.google.com/vertex-ai](https://cloud.google.com/vertex-ai) + +## 先决条件 + +* **Google Cloud 账户:** 您需要一个活跃的 Google Cloud Platform (GCP) 账户。 +* **项目:** 您需要一个启用了 Vertex AI API 的 GCP 项目。 +* **模型访问权限:** 您必须请求并获准访问您想要使用的特定 Claude 模型。请参阅 [Google Cloud 文档](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude#before_you_begin) 获取说明。 +* **应用程序默认凭据 (ADC):** Kilo Code 使用应用程序默认凭据来与 Vertex AI 进行身份验证。最简单的设置方法是： + 1. 安装 Google Cloud CLI: [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install) + 2. 使用以下命令进行身份验证：`gcloud auth application-default login` + +## 支持的模型 + +Kilo Code 通过 Vertex AI 支持以下模型（基于源代码）： + +* **Google Gemini 模型:** + * `gemini-2.0-flash-001` + * `gemini-2.5-pro-exp-03-25` + * `gemini-2.0-pro-exp-02-05` + * `gemini-2.0-flash-lite-001` + * `gemini-2.0-flash-thinking-exp-01-21` + * `gemini-1.5-flash-002` + * `gemini-1.5-pro-002` +* **Anthropic Claude 模型:** + * `claude-3-7-sonnet@20250219:thinking` + * `claude-极客3-7-sonnet@20250219` + * `claude-3-5-sonnet-v2@20241022` + * `claude-3-5-sonnet@20240620` + * `claude-3-5-haiku@20241022` + * `claude-3-opus@20240229` + * `claude-3-haiku@20240307` + +请参阅 [Google Cloud 关于 Vertex AI 模型的文档](https://cloud.google.com极客/vertex-ai/generative-ai/docs/learn/models) 获取最新可用模型及其 ID 列表。 + +## 在 Kilo Code 中配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商:** 从 "API 提供商" 下拉菜单中选择 "GCP Vertex AI"。 +3. **输入项目 ID:** 输入您的 Google Cloud 项目 ID。 +4. **选择区域:** 选择您的 Vertex AI 资源所在的区域 (例如 `us-east5`)。 +5. **选择模型:** 从 "模型" 下拉菜单中选择您想要的模型。 + +## 提示和注意事项 + +* **权限:** 确保您的 Google Cloud 账户具有访问 Vertex AI 和您想要使用的特定模型所需的权限。 +* **定价:** 请参阅 [Vertex AI 定价](https://cloud.google.com/vertex-ai/pricing) 页面了解详情。 \ No newline at end of file diff --git a/docs/zh-CN/providers/vscode-lm.md b/docs/zh-CN/providers/vscode-lm.md new file mode 100644 index 0000000..b48371a --- /dev/null +++ b/docs/zh-CN/providers/vscode-lm.md @@ -0,0 +1,45 @@ +--- +sidebar_label: VS Code 语言模型 API +--- + +# 在 Kilo Code 中使用 VS Code 语言模型 API + +Kilo Code 包含对 [VS Code 语言模型 API](https://code.visualstudio.com/api/language-extensions/language-model-access) 的*实验性*支持。该 API 允许扩展直接在 VS Code 中提供对语言模型的访问。这意味着您可以潜在使用以下模型： + +* **GitHub Copilot:** 如果您有 Copilot 订阅并安装了该扩展。 +* **其他 VS Code 扩展:** 任何实现语言模型 API 的扩展。 + +**重要提示:** 此集成是高度实验性的，可能无法按预期工作。它依赖于其他扩展正确实现 VS Code 语言模型 API。 + +## 先决条件 + +* **VS Code:** 语言模型 API 通过 VS Code 提供（目前不支持 Cursor）。 +* **语言模型提供者扩展:** 您需要一个提供语言模型的扩展。示例包括： + * **GitHub Copilot:** 如果您有 Copilot 订阅，GitHub Copilot 和 GitHub Copilot Chat 扩展可以提供模型。 + * **其他扩展:** 在 VS Code 市场搜索提到 "Language Model API" 或 "lm" 的扩展。可能会有其他实验性扩展可用。 + +## 配置 + +1. **打开 Kilo Code 设置:** 点击 Kilo Code 面板中的齿轮图标 ()。 +2. **选择提供商:** 从 "API 提供商" 下拉菜单中选择 "VS Code LM API"。 +3. **选择模型:** "语言模型" 下拉菜单将（最终）列出可用模型。格式为 `供应商/系列`。例如，如果您有 Copilot，您可能会看到以下选项： + * `copilot - claude-3.5-sonnet` + * `copilot - o3-mini` + * `copilot - o1-ga` + * `copilot - gemini-2.0-flash` + +## 限制 + +* **实验性 API:** VS Code 语言模型 API 仍在开发中。预计会有变化和潜在的不稳定性。 +* **依赖扩展:** 此功能完全依赖其他扩展提供模型。Kilo Code 无法直接控制哪些模型可用。 +* **功能有限:** VS Code 语言模型 API 可能不支持其他 API 提供商的所有功能（例如，图像输入、流式传输、详细使用信息）。 +* **无法直接控制成本:** 您将受提供模型的扩展的定价和条款约束。Kilo Code 无法直接跟踪或限制成本。 +* **GitHub Copilot 速率限制:** 使用 VS Code LM API 与 GitHub Copilot 时，请注意 GitHub 可能会对 Copilot 使用施加速率限制。这些限制由 GitHub 控制，而非 Kilo Code。 + +## 故障排除 + +* **没有模型出现:** + * 确保已安装 VS Code。 + * 确保已安装并启用了语言模型提供者扩展（例如，GitHub Copilot, GitHub Copilot Chat）。 + * 如果使用 Copilot，请确保您已使用您想要使用的模型发送了 Copilot Chat 消息。 +* **意外行为:** 如果遇到意外行为，很可能是底层语言模型 API 或提供者扩展的问题。请考虑向提供者扩展的开发人员报告问题。 \ No newline at end of file diff --git a/docs/zh-CN/tips-and-tricks.md b/docs/zh-CN/tips-and-tricks.md new file mode 100644 index 0000000..2034637 --- /dev/null +++ b/docs/zh-CN/tips-and-tricks.md @@ -0,0 +1,15 @@ +# 技巧与窍门 + +一些快速提示，帮助你充分利用 Kilo Code。 + +- 将 Kilo Code 拖到[侧边栏](https://code.visualstudio.com/api/ux-guidelines/sidebars#secondary-sidebar)，以便同时查看资源管理器、搜索、源代码控制等。 +- 当 Kilo Code 位于与文件资源管理器分开的侧边栏时，你可以将文件从资源管理器拖到聊天窗口中（甚至可以一次拖多个文件）。只需在开始拖动文件后按住 shift 键。 +- 如果你不使用[MCP](/features/mcp/overview)，请在 提示选项卡中关闭它，以显著减少系统提示的大小。 +- 为了保持[自定义模式](/features/custom-modes)的正轨，请限制它们可以编辑的文件类型。 +- 如果你遇到`input length and max tokens exceed context limit`错误，可以通过删除消息、回滚到之前的检查点或切换到具有长上下文窗口的模型（如 Gemini）来恢复。 +- 一般来说，对于思考模型的`Max Tokens`设置要深思熟虑。你分配的每个 token 都会占用存储对话历史的空间。考虑仅在 Architect 和 Debug 等模式中使用高`Max Tokens` / `Max Thinking Tokens`设置，并将 Code 模式保持在 16k max tokens 或更少。 +- 如果有一个你希望自定义模式完成的任务的真实职位发布，可以尝试要求 Code 模式`根据@[url]的职位发布创建一个自定义模式`。 +- 如果你想真正加速，可以检出多个代码库副本并在所有副本上并行运行 Kilo Code（使用 git 解决任何冲突，与人类开发人员相同）。 +- 使用 Debug 模式时，要求 Kilo "在 Debug 模式下启动一个新任务，包含解决 X 所需的所有必要上下文"，以便调试过程使用其自己的上下文窗口，而不会污染主任务。 +- 点击下方的"编辑此页面"添加你自己的技巧！ +- 为了管理大文件并减少上下文/资源使用，请调整`File read auto-truncate threshold`设置。此设置控制一次读取文件的行数。较低的值可以提高处理非常大文件时的性能，但可能需要更多的读取操作。你可以在 Kilo Code 设置的"高级设置"中找到此设置。 \ No newline at end of file