# codebuddy **Repository Path**: yanjingtu/codebuddy ## Basic Information - **Project Name**: codebuddy - **Description**: An Autonomous AI Software Engineer - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-11 - **Last Updated**: 2026-08-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README > **弃用通知** > CodeBuddy 的活跃开发已正式迁移至私有仓库。此公共仓库现已归档，将不再接受新功能、Bug 修复、Issue 或 Pull Request（包括自动化依赖更新）。 > > 感谢每一位支持并参与本项目公共版本的朋友！ # CodeBuddy ### 面向 Visual Studio Code 的自主 AI 软件工程师 阅读 [文档](https://codebuddy-docs.vercel.app/getting-started/overview/) CodeBuddy 是一款运行在 VS Code 内部的多智能体 AI 软件工程师。它能够自主完成规划、编写、调试、测试、文档编写与部署整个功能流程——读取你的代码库、运行终端命令、编辑文件、搜索网络，并不断修正自身错误，直到任务完成。 它支持 10 家 AI 服务商（云端与本地）、超过 20 个内置工具、16 个捆绑技能集成、一个用于无限扩展的 Model Context Protocol 网关、企业级安全控制，以及支持 7 种语言的完整国际化。 [![CI](https://github.com/olasunkanmi-SE/codebuddy/actions/workflows/workflow.yml/badge.svg)](https://github.com/olasunkanmi-SE/codebuddy/actions/workflows/workflow.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) --- ## 目录 - [架构](#架构) - [智能体系统](#智能体系统) - [并发与队列管理](#并发与队列管理) - [运行模式](#运行模式) - [AI 服务商](#ai-服务商) - [服务商故障转移](#服务商故障转移) - [内置工具](#内置工具) - [命令](#命令) - [行内代码补全](#行内代码补全) - [差异审查系统](#差异审查系统) - [Model Context Protocol (MCP)](#model-context-protocol-mcp) - [连接器与集成](#连接器与集成) - [技能系统](#技能系统) - [上下文流水线](#上下文流水线) - [混合记忆与搜索](#混合记忆与搜索) - [项目规则](#项目规则) - [安全](#安全) - [Coworker 自动化](#coworker-自动化) - [成本追踪](#成本追踪) - [智能阅读器](#智能阅读器) - [可观测性](#可观测性) - [国际化](#国际化) - [设置参考](#设置参考) - [安装](#安装) - [构建与打包](#构建与打包) - [配置](#配置) - [数据存储](#数据存储) - [故障排查](#故障排查) - [贡献](#贡献) - [许可证](#许可证) --- ## 架构 CodeBuddy 构建在事件驱动的分层架构之上，专为可扩展性、服务商无关性与实时流式传输而设计。 ### 编排器（Orchestrator） 编排器是位于系统中心的单例事件总线。每个子系统都仅通过发布/订阅事件进行通信。编排器从不直接调用服务——它发出带类型的事件，监听器独立做出反应。这使得智能体层、Webview 层与服务层之间完全解耦。 ### 智能体执行流水线 ``` 用户消息（webview） --> BaseWebViewProvider 通过 onDidReceiveMessage 接收 --> InputValidator 对输入进行清洗 --> ConcurrencyQueueService 进行准入控制（感知优先级的信号量） --> MessageHandler 路由至 CodeBuddyAgentService --> DeveloperAgent 调用 createDeepAgent() --> LangGraph 图执行（推理 -> 行动 -> 观察 循环） --> 工具执行（文件编辑、终端、搜索、MCP 等） --> 按 token / 按工具调用发出流式事件 --> AgentSafetyGuard 强制执行事件/工具/时长限制 --> ProviderFailoverService 在备用服务商上重试 --> 事件通过编排器回流 --> WebViewProvider 通过 postMessage 转发至 webview 用户看到带有实时工具活动指示器的流式响应 ``` ### Webview 通信 扩展宿主与 React webview 通过双向 `postMessage` 协议通信。webview 发送结构化命令，扩展以带类型的事件进行响应。 ### 持久化策略 | 层 | 机制 | 用途 | | ---------------------- | --------------------------------------------- | ------------------------------------------------------------- | | 内存缓存 | 基于 TTL 的 Map（Memory 单例） | 会话数据、模型引用、瞬时状态 | | 文件存储 | `.codebuddy/` 工作区目录 | 智能体状态快照、记忆、任务、规则 | | SQLite | sql.js（WASM），支持 FTS4 全文搜索 | 代码库分析、持久化结构化数据、关键词搜索 | | LangGraph 检查点 | SqljsCheckpointSaver（基于 SQLite） | 可恢复状态的多轮对话线程 | | VS Code SecretStorage | 加密的操作系统钥匙串 | API 密钥与凭据 | | 向量存储 | SqliteVectorStore，使用预归一化向量 | 用于语义搜索的工作区嵌入 | | 凭据代理 | 运行在 127.0.0.1 上的进程内 HTTP 代理 | 为 LLM SDK 注入基于会话令牌认证的凭据 | ### Tree-sitter 语言支持 CodeBuddy 使用 Tree-sitter WASM 二进制文件对 7 种语言进行准确的 AST 解析，为代码库分析、符号提取与代码索引工作线程提供支持： | 语言 | 二进制文件 | | ---------- | ------------------------------- | | JavaScript | `tree-sitter-javascript.wasm` | | TypeScript | `tree-sitter-tsx.wasm` | | Python | `tree-sitter-python.wasm` | | Go | `tree-sitter-go.wasm` | | Java | `tree-sitter-java.wasm` | | Rust | `tree-sitter-rust.wasm` | | PHP | `tree-sitter-php.wasm` | --- ## 智能体系统 ### 多智能体架构 CodeBuddy 使用基于 LangGraph DeepAgents 框架的多智能体架构。由一个开发者智能体（Developer Agent）协调工作，并配有七个专门的子智能体，每个子智能体都接收针对其角色过滤后的工具： | 子智能体 | 职责 | | -------------- | ----------------------------------------------------------------------------- | | 代码分析器 | 深度代码审查、Bug 识别、复杂度分析、反模式检测 | | 文档编写者 | 技术文档、API 参考、README 生成、教程 | | 调试器 | 错误调查、堆栈跟踪分析、根因识别、修复建议 | | 文件整理者 | 目录重构、文件重命名、项目布局优化 | | 架构师 | 系统设计、模式选择、架构决策记录、可扩展性规划 | | 审查者 | 代码质量执行、安全审查、最佳实践、风格合规 | | 测试者 | 测试策略、单元/集成测试生成、测试执行与验证 | ### 自愈执行 当智能体遇到失败时——构建错误、测试失败、无效的命令输出——它不会停止。它会读取错误、分析根因、应用修正并重试。此循环会一直持续，直到任务成功，或智能体判断该问题需要人工介入。 ### 安全护栏 `AgentSafetyGuard` 对每个智能体流强制执行硬性限制，以防止失控执行： - 每个会话最多 2,000 个流事件（可配置至 10,000）。 - 每个会话最多 400 次工具调用（可配置至 2,000）。 - 每个会话最多运行 10 分钟（可配置至 60 分钟）。 - 按工具调用计数，并设有具体上限：文件编辑（8）、终端命令（10）、网络搜索（8）。 - 对同一文件的重复文件编辑进行循环检测（阈值：4）。 `ProductionSafeguards` 服务提供带有 CLOSED/OPEN/HALF_OPEN 状态的熔断器，以及 5 种恢复策略，用于处理持续性失败。 ### 人在回路（Human-in-the-Loop） 破坏性操作（例如文件删除）会触发中断，暂停执行并请求明确批准。用户可以在智能体继续之前批准、编辑或拒绝所提议的操作。 ### 检查点 `CheckpointService` 将智能体执行状态保存到 SQLite，从而支持可恢复的对话。在每次智能体操作之前，都会创建一个命名检查点，以便在会话中断时恢复工作。 --- ## 并发与队列管理 `ConcurrencyQueueService` 控制并发智能体操作的最大数量。当所有槽位都被占用时，传入请求会按感知优先级的 FIFO 顺序排队，并在槽位释放时依次出队。 - **可配置并发上限**：1 到 10 个槽位（默认 3），可在运行时调整。 - **三个优先级级别**：USER（2）、SCHEDULED（1）、BACKGROUND（0）。高优先级请求优先出队；同级按到达时间排序。 - **队列深度上限**：与并发上限成比例扩展（10 倍乘数）。超出上限的请求会被拒绝，并返回背压反馈。 - **防饥饿机制**：等待超过 60 秒的项目会自动获得优先级提升，通过稳定排序保持公平性。 - **取消**：可从 QuickPick 状态视图取消单个项目或所有等待中的项目。 - **AbortSignal 支持**：调用方可传入 `AbortSignal` 或超时时间以进行协作式取消。运行时 polyfill 确保跨 VS Code Electron 版本的兼容性。 - **状态栏**：显示正在运行与已排队的数量。队列为空时隐藏。 - **槽位释放保证**：智能体服务中的外层 `try/finally` 确保即使在流失败或取消时槽位也总能被归还。 --- ## 运行模式 **智能体模式（Agent Mode）** —— 完全自主执行。智能体可访问所有工具：文件创建与编辑、终端命令、网络搜索、代码库分析、MCP 集成以及调试器访问。文件变更会经过差异审查系统以获得批准。 **问答模式（Ask Mode）** —— 直接的问答交互。智能体回答问题、解释代码并提供建议，但不会修改文件或运行命令。上下文会自动从你的工作区收集。当接近 token 限制时，支持带自动摘要的上下文窗口压缩。 --- ## AI 服务商 CodeBuddy 支持 10 家 AI 服务商。可随时在它们之间切换，无需重启。 | 服务商 | 默认模型 | 说明 | | ------------------- | ----------------------- | ------------------------------------------------------------ | | Gemini (Google) | gemini-2.5-pro | 长上下文窗口，强大的通用编码能力 | | Anthropic (Claude) | claude-sonnet-4-5 | 复杂架构、大规模重构 | | OpenAI | gpt-4o | 推理、规划、广泛知识 | | DeepSeek | deepseek-chat | 高性价比，强大的代码生成能力 | | Qwen (Alibaba) | qwen-max | 具有竞争力的开源权重性能 | | Groq | llama-3.1-70b-versatile | 通过专用硬件实现超快速推理 | | GLM (Zhipu AI) | glm-4 | 中英文双语支持 | | XGrok | grok | 替代推理模型 | | Ollama (本地) | qwen2.5-coder | 完全离线、零 API 成本，代码永不离开你的机器 | | Docker Model Runner | 可配置 | 通过 Docker Desktop 内置的模型运行时运行模型 | 所有服务商都使用统一的 `buildChatModel()` 工厂，该工厂会规范化配置、在凭据代理激活时应用代理头，并生成与 LangChain 兼容的聊天模型实例。 --- ## 服务商故障转移 当主服务商失败时，`ProviderFailoverService` 会自动切换到备用 LLM 服务商。这可以防止因速率限制、计费问题或服务商宕机而导致对话中断。 - **有序回退链**：配置明确的服务商优先级列表，或让 CodeBuddy 从你已配置的 API 密钥中自动检测。 - **失败分类**：HTTP 状态码被映射到具体原因——认证（401）、计费（402）、速率限制（429）、超时（408）、过载（503）、模型未找到（404）——每种都有各自的冷却期。 - **冷却管理**：认证=10 分钟，计费=30 分钟，速率限制=1 分钟，超时=30 秒，过载=2 分钟，模型未找到=1 小时。 - **探测恢复**：在服务商冷却期到期前（提前 30 秒）进行探测，以将其恢复为可用状态。 - **线程连续性**：故障转移通过基于检查点的 `thread_id` 连续性保留对话线程。 - **健康指示器**：webview 中的 `ProviderHealthIndicator` 以绿/黄/红状态显示，并附带工具提示详情。 --- ## 内置工具 智能体可访问超过 20 个工具，并自主选择和调用它们： | 工具 | 功能 | | ------------------ | ---------------------------------------------------------------------------- | | 文件分析 | 读取、分析并理解工作区中的代码文件 | | 文件编辑 | 创建、覆盖或应用带差异审查的定向搜索替换编辑 | | 文件列表 | 探索目录结构并发现项目布局 | | 终端 | 执行 Shell 命令，支持实时输出流式传输与错误捕获 | | 深度终端 | 持久化终端会话，为长时间运行的进程提供缓冲输出 | | Git 操作 | 差异、日志、状态、分支管理与提交操作 | | Ripgrep 搜索 | 在整个代码库中进行快速全文搜索 | | 网络搜索 | 通过 Tavily 进行互联网搜索，用于文档、解决方案与参考资料 | | 符号搜索 | 查找函数定义、类声明与代码符号 | | 诊断 | 从 Problems 面板读取 VS Code 诊断错误与警告 | | Web 预览 | 为 Web 应用打开浏览器预览 | | 向量数据库搜索 | 对已索引的代码库嵌入进行语义相似度搜索 | | 任务管理器 | 持久化任务追踪，支持优先级与状态（待处理、进行中、已完成） | | 核心记忆 | 跨会话存储与回忆知识、规则与经验 | | 思考 | 用于复杂问题求解的扩展思维链推理 | | 调试：状态 | 检查活动调试会话的状态 | | 调试：堆栈跟踪 | 在调试期间读取并分析堆栈跟踪 | | 调试：变量 | 检查当前调试作用域中的变量值 | | 调试：求值 | 在调试上下文中求值表达式 | | 调试：控制 | 步入、步过、继续与暂停调试执行 | | MCP 工具 | 从已连接的 MCP 服务器动态加载的工具 | 工具通过 `ToolProvider` 注册，并按子智能体角色进行过滤。`PermissionScopeService` 可根据当前权限配置文件进一步限制可用工具。 --- ## 命令 所有命令均可从命令面板、右键上下文菜单或其键盘快捷键访问。 ### 代码操作 | 命令 | 快捷键 | 说明 | | -------------------------- | ----------- | -------------------------------------------------------------- | | 注释代码 | Cmd+Shift+J | 为所选代码生成清晰、贴合上下文的注释 | | 审查代码 | Cmd+Shift+R | 涵盖质量与安全的全面代码审查 | | 重构代码 | Cmd+Shift+; | 重构代码以提升可读性与可维护性 | | 优化代码 | Cmd+Shift+0 | 识别并应用性能优化 | | 解释代码 | Cmd+Shift+1 | 清晰解释所选代码的作用与原因 | | 生成提交信息 | Cmd+Shift+2 | 根据已暂存的更改生成提交信息 | | 行内聊天 | Cmd+Shift+8 | 快速行内代码讨论与编辑 | | 生成架构图 | Cmd+Shift+7 | 生成可视化代码结构的 Mermaid 图 | | 代码库分析 | Cmd+Shift+6 | 分析整个工作区并回答架构问题 | | 面试我 | -- | 生成渐进式技术面试问题 | | 审查 Pull Request | -- | 带分支差异分析的全面 PR 审查 | | 生成文档 | -- | 完整文档套件（README、API、架构、组件） | ### 工作区与上下文 | 命令 | 快捷键 | 说明 | | ---------------------------- | ----------- | ---------------------------------------------- | | 索引工作区 | -- | 为语义代码搜索构建向量嵌入 | | 初始化 .codebuddyignore | -- | 创建用于索引的文件排除列表 | | 打开/初始化/重新加载项目规则 | Cmd+Shift+9 | 管理项目特定的 AI 行为规则 | | 切换行内补全 | -- | 启用或禁用幽灵文本代码补全 | | 在智能阅读器中打开 | -- | 在无干扰阅读器中打开任意 URL | | 清除工作区上下文 | -- | 重置工作区上下文缓存 | ### 差异审查 | 命令 | 说明 | | -------------------------- | ---------------------------------------------------- | | 应用更改 | 接受智能体提议的文件修改 | | 拒绝更改 | 拒绝智能体提议的文件修改 | | 审查 Composer 会话 | 审查多文件 composer 会话中的所有更改 | | 应用 Composer 会话 | 接受 composer 会话中的所有更改 | | 拒绝 Composer 会话 | 拒绝 composer 会话中的所有更改 | | 清除行内审查注释 | 移除所有行内审查注解 | ### 自动化 | 命令 | 说明 | | ---------------- | -------------------------------------------------------------- | | 每日站会 | 触发自动化站会报告 | | 代码健康检查 | 扫描 TODO、大文件与技术债务指标 | | 依赖检查 | 审计依赖中的通配符与危险版本范围 | | Git 看门狗 | 检查是否存在陈旧的未提交更改 | | 每日总结 | 生成当日工作的总结 | ### 集成 | 命令 | 说明 | | ------------------------ | ---------------------------------------------------------------- | | 从 Jira 创建分支 | 浏览 Jira 工单并从所选工单创建 Git 分支 | | 从 GitLab 创建分支 | 浏览 GitLab Issue 并从所选 Issue 创建 Git 分支 | ### 安全与管理 | 命令 | 说明 | | -------------------------- | ------------------------------------------------------------ | | 运行 Doctor | 执行安全审计与配置健康检查 | | Doctor 自动修复 | 自动修复检测到的安全问题 | | 打开外部安全配置 | 打开外部安全配置文件 | | 运行安全诊断 | 运行安全策略诊断 | | 切换权限配置文件 | 在受限、标准与受信任配置文件之间切换 | | 切换访问控制模式 | 在开放、允许与拒绝模式之间切换 | | 访问控制审计日志 | 查看访问控制审计追踪 | | 凭据代理审计日志 | 查看凭据代理审计追踪 | | 队列状态 | 查看正在运行与已排队的智能体操作，并支持取消操作 | | 取消所有已排队 | 取消并发队列中所有等待中的项目 | ### 文档生成器 文档命令支持五种输出类型（完整套件、仅 README、API 文档、架构文档、组件文档）、三种输出格式（Markdown、HTML、两者）以及三种图表格式（Mermaid、PlantUML、ASCII）。 --- ## 行内代码补全 CodeBuddy 提供一个 Fill-in-the-Middle（FIM）行内补全引擎，独立于聊天运行： - 在你输入时出现幽灵文本建议，利用来自导入、周围代码与文件结构的上下文。 - 可使用与主聊天不同的 AI 服务商与模型——用快速的本地模型做补全，同时用云端模型执行智能体任务。 - 可配置防抖延迟（默认 300ms）、最大 token 数与触发模式（自动或手动）。 - LRU 缓存（50 条）可避免对重复补全进行冗余 API 调用。 - 支持多行补全。 --- ## 差异审查系统 智能体提议的每一次文件更改都会经过审查流水线： - 更改会出现在侧边栏的"待处理更改"面板中，并带有可视化差异。 - 可在 VS Code 原生的并排差异编辑器中打开任意更改。 - 使用工具栏按钮应用或拒绝单个更改。 - Composer 会话将多文件更改分组，以便批量审查。 - 行内审查注释可注解编辑器中的特定行。 - 最近更改历史记录追踪最近 50 次修改。 - 对于不需要手动批准的工作流，可使用自动应用模式（`codebuddy.autoApprove`）。 - 实时事件通知通过编排器保持 UI 同步。 --- ## Model Context Protocol (MCP) CodeBuddy 对 Model Context Protocol 提供一等支持，这是用于将 AI 智能体连接到外部工具与数据源的开放标准。 - **Docker 网关模式** —— 通过 `docker mcp gateway run` 运行单个统一的 MCP 目录，通过一个端点暴露所有已配置的工具服务器。 - **多服务器模式** —— 同时连接到多个独立的 MCP 服务器，每个服务器使用各自的传输方式（SSE 或 stdio）。 - **预设** —— 内置 Playwright 浏览器自动化预设。可为你自己的工具服务器添加自定义预设。 - **工具管理** —— 从设置面板按服务器启用或禁用单个工具。 - **熔断器** —— 带有 CLOSED/OPEN/HALF_OPEN 状态的容错机制，可防止不健康的 MCP 服务器引发级联失败。 - **自动关闭** —— Docker 网关在 5 分钟无活动后自动关闭，以节省资源。 - **重试逻辑** —— 对瞬时连接失败进行指数退避自动重试（3 次尝试）。 - **智能体集成** —— 所有 MCP 工具都作为与 LangChain 兼容的工具暴露，自动对每个智能体与子智能体可用。 --- ## 连接器与集成 CodeBuddy 附带 17 个预配置的外部服务连接器。每个连接器都是一个 MCP 服务器，可在设置中一键启用。 | 连接器 | 类型 | | --------------- | ---------------------------------------------------------------- | | GitHub | 源代码控制、Issue、Pull Request | | GitLab | Issue、合并请求、分支（也支持直接 CLI 集成） | | Jira | 工单管理、分支创建（也支持直接 CLI 集成） | | Linear | Issue 追踪与项目管理 | | Slack | 团队沟通与通知 | | Google Drive | 文档访问与搜索 | | Gmail | 邮件集成 | | Google Calendar | 日历事件访问 | | Notion | 知识库与文档 | | PostgreSQL | 数据库查询与模式检查 | | MySQL | 数据库查询与模式检查 | | MongoDB | 文档数据库操作 | | Redis | 缓存与数据存储操作 | | AWS | 云基础设施管理 | | Kubernetes | 容器编排 | | Sentry | 错误追踪与监控 | | n8n | 工作流自动化 | Jira 与 GitLab 还提供直接 CLI 集成：在 VS Code quick-pick 菜单中浏览工单/Issue、从所选项目创建分支，并在浏览器中打开它们。 --- ## 技能系统 技能通过结构化的能力定义扩展智能体的领域知识。CodeBuddy 使用三层发现模型： ### 捆绑技能 扩展附带 16 个技能，每个都包含一个 `SKILL.md` 定义与可选的安装脚本： | 技能 | 能力 | | ------------- | --------------------------------------------------- | | AWS | Amazon Web Services 基础设施管理 | | Datadog | 监控、告警与可观测性 | | Elasticsearch | 搜索引擎查询与索引管理 | | Email | 邮件撰写与投递 | | GitHub | 仓库操作、Issue 与 Pull Request | | GitLab | 合并请求、流水线与 Issue 追踪 | | Gmail | Gmail API 集成，附带安全 CLI 工具 | | Jira | 工单创建、搜索与 Sprint 管理 | | Kubernetes | 集群操作、Pod 管理与部署 | | Linear | Issue 追踪与项目看板 | | MongoDB | 文档查询、聚合流水线 | | MySQL | SQL 查询与模式检查 | | PostgreSQL | SQL 查询与模式检查 | | Redis | 缓存操作与数据存储命令 | | Sentry | 错误追踪与问题解决 | | Telegram | 机器人消息与通知 | ### 工作区与全局技能 - **工作区技能**：将 `*SKILL.md` 文件放置在 `.codebuddy/skills/` 中，以提供项目特定的能力。 - **全局技能**：将文件放置在 `~/.codebuddy/skills/` 中，以提供跨项目的能力。 - 名称冲突时，工作区技能优先。 - YAML frontmatter 定义技能元数据（名称、描述、环境要求）。 ### 技能管理 - 从设置面板单独启用或禁用技能。 - 每个技能的环境配置（LOCAL、QA、PROD），凭据隔离存储在 SecretStorage 中。 - 感知操作系统的安装，带有包管理器回退链（brew、npm、pip、script）。 - 活动技能会在运行时注入到智能体的系统提示中。 --- ## 上下文流水线 CodeBuddy 从多个来源收集上下文，并自动将其组装到每个提示中： 1. **活动文件** —— 编辑器中当前打开的文件始终被包含。 2. **@ 提及** —— 在消息中使用 `@filename` 引用特定文件，以显式包含它们。 3. **混合搜索** —— 结合向量相似度、FTS4 关键词匹配、时间衰减与 MMR 多样性重排序（参见 [混合记忆与搜索](#混合记忆与搜索)）。 4. **网络搜索** —— 对于需要外部知识的问题，智能体会通过 Tavily 搜索网络并纳入相关结果。 5. **代码库理解** —— 一个持久化、感知 git 的分析服务维护你项目的架构地图（框架、API、数据模型、依赖），缓存在 SQLite 中，并在 git 状态变化时失效。Tree-sitter AST 解析支持 7 种语言，并支持对 Express、NestJS、FastAPI、Flask、Django、Spring、Gin、Actix 等框架的端点检测。 6. **项目规则** —— 从 `.codebuddy/rules.md` 加载，并注入到每个提示中。 7. **智能体记忆** —— 来自核心记忆系统的持久化知识、规则与经验。 8. **技能** —— 活动技能定义会附加到系统提示中。 9. **阅读器上下文** —— 如果智能阅读器中打开了一篇文章，其内容对智能体可用。 10. **问题分类** —— 一个基于 NLP 的分类器（使用词干提取与模糊匹配）对每个查询进行分类，以优化哪些上下文来源被优先考虑。 `EnhancedPromptBuilderService` 从这些来源组装最终提示，遵守配置的 token 预算，并按文件路径去重。 ### 上下文窗口压缩 当对话接近模型的上下文窗口限制时，`ContextWindowCompactionService` 会应用 4 层渐进式回退： 1. **工具剥离** —— 从较旧的消息中移除大型工具输出。 2. **多块摘要** —— 将历史拆分为多个块，用 LLM 调用分别摘要，然后合并。 3. **部分压缩** —— 仅摘要历史中最旧的部分。 4. **普通回退** —— 作为最后手段的激进截断。 压缩在上下文利用率达到 90% 时自动触发（80% 时发出警告），也可通过 `/compact` 斜杠命令手动触发。 --- ## 混合记忆与搜索 ### 持久化记忆 智能体使用位于 `.codebuddy/memory.json` 的文件支持存储系统跨会话维护记忆： - **三个类别**：知识（事实与信息）、规则（行为准则）、经验（从过往交互中学到的教训）。 - **两个范围**：用户（全局，在所有工作区中持久化）与项目（工作区特定）。 - **CRUD 操作**：智能体可在执行期间添加、更新、删除与搜索记忆。 - **系统提示注入**：所有已存储的记忆都会自动包含在智能体的上下文中。 智能体还拥有一个持久化任务管理器（`.codebuddy/tasks.json`），用于跨会话追踪带有优先级与状态的工作项。 ### 混合搜索 `HybridSearchService` 结合多种检索策略以实现高质量的上下文检索： - **向量搜索**：预归一化查询向量，在 `Float32Array` BLOB 上进行余弦相似度计算。二分查找插入维护 Top-K 结果集。基于时间的让出（8ms 预算）使扩展宿主在大规模扫描期间保持响应。 - **FTS4 关键词搜索**：使用 unicode61 分词器的 SQLite FTS4。通过 INSERT/DELETE/UPDATE 触发器自动同步。通过 `matchinfo('pcx')` BLOB 解析实现 TF-IDF 评分。 - **分数融合**：向量分数与关键词分数的可配置加权线性组合（默认：0.7 向量，0.3 文本）。权重会自动归一化。 - **时间衰减**：可选的指数衰减，使最近索引的内容排名更高。可配置半衰期（1-365 天）。 - **MMR 多样性**：可选的最大边际相关性（Maximal Marginal Relevance）重排序，使用 Jaccard 相似度减少冗余结果。 - **5 层回退**：混合、仅 FTS4、旧版向量、旧版关键词、公共文件。 ### 配置 | 设置 | 默认值 | 说明 | | --------------------------------------------------- | ------ | --------------------------------------------- | | `codebuddy.hybridSearch.vectorWeight` | 0.7 | 语义相似度权重（0-1） | | `codebuddy.hybridSearch.textWeight` | 0.3 | 关键词匹配权重（0-1） | | `codebuddy.hybridSearch.topK` | 10 | 返回的最大结果数（1-50） | | `codebuddy.hybridSearch.mmr.enabled` | false | 启用 MMR 多样性重排序 | | `codebuddy.hybridSearch.mmr.lambda` | 0.7 | MMR 权衡：0 = 最大多样性，1 = 最大相关性 | | `codebuddy.hybridSearch.temporalDecay.enabled` | false | 启用基于时间的分数衰减 | | `codebuddy.hybridSearch.temporalDecay.halfLifeDays` | 30 | 结果分数减半所需的天数（1-365） | --- ## 项目规则 定义 CodeBuddy 如何为你的项目编写代码。规则会自动加载并注入到每个 AI 提示中。 - **文件位置**：`.codebuddy/rules.md`、`.codebuddy/rules/index.md`、`.codebuddyrules` 或 `CODEBUDDY.md`。 - **目录规则**：将多个 `.md` 文件放置在 `.codebuddy/rules/` 中，它们会被合并在一起。 - **Token 预算**：可配置最大值（默认 2000 token），如果规则超出限制则进行智能截断。 - **基于设置的规则**：直接在 VS Code 设置 UI 中定义额外规则与自定义系统提示。 - **实时重载**：文件监视器检测更改并自动重新加载规则。 - **模板脚手架**：`Init Rules` 命令会创建一个入门模板。 --- ## 安全 CodeBuddy 提供多层安全架构，专为个人开发者与企业团队设计。 ### 权限配置文件 `PermissionScopeService` 强制执行三种权限配置文件，可通过 `.codebuddy/permissions.json` 按工作区配置： | 配置文件 | 工具 | 终端 | 文件编辑 | 批准 | | ------------ | --------- | -------------------------------- | ---------- | --------- | | `restricted` | 只读 | 所有命令被拒绝 | 拒绝 | 不适用 | | `standard` | 所有工具 | 危险命令被拒绝 | 允许 | 手动 | | `trusted` | 所有工具 | 自动批准（灾难性拒绝兜底） | 允许 | 自动 | **灾难性拒绝兜底**会在所有配置文件（包括 `trusted`）中阻止 `rm -rf /`、`mkfs`、`dd of=/dev/` 与 fork 炸弹。 工具可通过按工作区的阻止列表与允许列表进一步限制，使用 O(1) 的 Set 查找。 ### 访问控制 `AccessControlService` 支持三种模式： - **open**：无限制（默认）。 - **allow**：仅明确列出的用户可交互。 - **deny**：阻止列出的用户。 配置从 `.codebuddy/access.json` 加载，并带有文件监视以实现实时更新。 ### 凭据代理 `CredentialProxyService` 在 `127.0.0.1` 上运行一个 HTTP 代理，将来自操作系统钥匙串的 API 密钥注入到出站 LLM 请求中。SDK 客户端永远看不到真实凭据。 - 9 条服务商路由（Anthropic、OpenAI、Groq、Deepseek、Qwen、GLM、Grok、Tavily、Local）。 - 会话令牌认证（`crypto.randomBytes(32)`）防止其他本地进程使用该代理。 - 出站请求上的认证头剥离。 - 按服务商的令牌桶速率限制。 - 10 MB 正文大小限制，带背压。 - Slow-loris 防护（块之间 30 秒空闲超时）。 - 环形缓冲区审计日志（1000 条），可通过 `Credential Proxy Audit Log` 命令查看。 - 所有代理路由上的路径遍历防护。 ### 外部安全配置 `ExternalSecurityConfigService` 从经过 JSON Schema 验证的文件加载安全策略，从而支持跨团队的集中式安全管理。 ### Doctor 命令 `DoctorService` 运行 6 项独立安全检查，并按严重程度报告发现： 1. **API 密钥审计** —— 检测 VS Code 设置中的明文 API 密钥；自动修复会将其迁移到 SecretStorage。 2. **输入验证器** —— 验证提示注入防御流水线是否处于活动状态。 3. **终端限制** —— 报告命令拒绝模式与自定义覆盖。 4. **目录权限** —— 在 macOS/Linux 上扫描 `.codebuddy/` 的 POSIX 权限。 5. **MCP 配置** —— 检测 MCP 服务器环境变量中的内联密钥。 6. **安全配置** —— 验证外部安全策略并提供脚手架。 发现项是可操作的：`Doctor Auto-Fix` 会自动修复问题，并对每个修复进行错误隔离。 ### 输入验证 `InputValidator` 在所有用户输入到达智能体之前对其进行清洗，并带有基于模式的提示注入检测。`LlmSafetyService` 会从发往 LLM 的内容中删除注入模式。 --- ## Coworker 自动化 CodeBuddy 运行定时后台任务，无需手动调用即可呈现可操作的信息： | 自动化 | 时间表 | 功能 | | ------------------ | ----------------- | ----------------------------------------------------------------------------------- | | 每日站会 | 上午 8:00 | 基于近期活动、未提交文件、活动错误与已连接工单的进度报告 | | 代码健康检查 | 上午 9:00 | 扫描 TODO、FIXME、大文件、更改热点与陈旧索引指标 | | 依赖检查 | 上午 11:00 | 审计 `package.json` 中的通配符版本与危险版本范围 | | Git 看门狗 | 每 2 小时 | 如果未提交更改已搁置超过 2 小时则发出告警 | | 技术新闻 | 上午 10 点、下午 2 点、下午 6 点 | 聚合来自 35+ 工程博客的文章 | | 新闻清理 | 午夜 | 移除旧的未保存新闻文章 | | 每日总结 | 一天结束时 | 生成当日工作的总结 | 所有自动化均可从命令面板手动触发，或从设置中单独禁用。可配置参数包括受保护分支模式、大文件阈值、热点更改最小值与最大 TODO 项数。 --- ## 成本追踪 `CostTrackingService` 实时监控 LLM API 支出： - 涵盖所有受支持服务商中 25+ 模型的定价数据库。 - 按对话累积成本。 - webview 中的 `CostDisplay` 组件显示实时成本计数器。 - 模型下拉菜单中提供预算感知的替代建议与定价提示。 - 成本数据作为 `cost_update` 事件从智能体循环中流式传输。 --- ## 智能阅读器 CodeBuddy 内置一个无干扰的文章阅读器： - 使用 Mozilla Readability 提取文章内容，并通过 DOMPurify 进行清洗。 - 在专用的 VS Code webview 面板中渲染。 - 文章缓存 24 小时（最多 100 篇），以避免重复获取。 - 维护可从工具栏访问的浏览历史。 - 三种模式：智能阅读器（内置，推荐）、简单浏览器或系统浏览器。 - 文章内容作为上下文对智能体可用，因此你可以就正在阅读的内容提问。 - SSRF 验证可防止对私有 IP 范围与 localhost 的请求。 --- ## 可观测性 CodeBuddy 附带内置的 OpenTelemetry 插桩： - **追踪**：OpenTelemetry SDK，附带用于本地调试的内存 span 导出器。OpenLLMetry（Traceloop）捕获 LangGraph 与 LangChain 追踪数据。每个智能体流都被包裹在一个 span 中，附带模型元数据、事件计数与工具调用计数。 - **外部导出**：可配置的 OTLP HTTP 端点，用于将追踪导出到 LangFuse、LangSmith、Jaeger 或任何与 OpenTelemetry 兼容的后端。 - **指标**：用于指标收集的 OTLP HTTP 导出。 - **结构化日志**：多级日志（DEBUG、INFO、WARN、ERROR）输出到控制台与文件。每个服务的日志器实例带有可配置的最低级别。 - **Webview 面板**：侧边栏中专用的可观测性面板实时显示追踪、日志与系统性能数据。 --- ## 国际化 界面支持 7 种语言。可在 设置 > 常规 中更改语言，无需重启。 | 语言 | 代码 | | ------------------ | ----- | | 英语 | en | | 西班牙语 | es | | 法语 | fr | | 德语 | de | | 中文（简体） | zh-cn | | 日语 | ja | | 约鲁巴语 | yo | webview UI（通过 i18next）与扩展后端（通过 @vscode/l10n）均已完全本地化。右键上下文菜单命令遵循 VS Code 的显示语言设置。NLS 包维护在 `l10n/` 与 `package.nls.*.json` 文件中。 --- ## 设置参考 通过侧边栏中的齿轮图标访问完整设置面板。设置按以下部分组织： | 部分 | 可配置内容 | | ------------------ | -------------------------------------------------------------------------------------- | | 账户 | 个人资料、订阅、退出登录 | | 常规 | 主题（9 种主题）、字体（10 种字体系列）、字体大小、语言、流式传输、昵称 | | 智能体 | 运行模式、自动批准、文件/终端权限、安全限制、详细日志 | | 模型 | AI 服务商选择、API 密钥、模型覆盖、故障转移链 | | MCP | MCP 服务器连接、工具管理、Docker 网关、已禁用工具 | | 连接器 | 一键激活 17 个外部服务集成 | | 技能 | 启用/禁用技能、环境配置、凭据管理 | | 对话 | 流式传输开关、压缩模式、聊天历史管理 | | 上下文 | 工作区索引、上下文窗口大小、隐藏文件、最大文件大小、混合搜索调优 | | 规则与子智能体 | 自定义规则、系统提示覆盖、子智能体配置 | | CoWorker | 启用/禁用单个自动化任务、阈值、受保护分支 | | 浏览器 | 链接打开偏好（阅读器、简单、系统） | | 隐私 | 遥测、清除历史、清除缓存、清除所有数据 | | Beta | 实验性功能开关 | | 关于 | 版本、仓库链接、更新日志、许可证 | ### 关键设置 | 设置 | 类型 | 默认值 | 说明 | | ------------------------------------------ | ------- | -------- | ------------------------------------------------------------ | | `generativeAi.option` | enum | Groq | 当前活动的 AI 服务商 | | `codebuddy.agent.maxConcurrentStreams` | number | 3 | 最大并发智能体操作数（1-10） | | `codebuddy.agent.maxEventCount` | number | 2000 | 每个会话最大流事件数（500-10,000） | | `codebuddy.agent.maxToolInvocations` | number | 400 | 每个会话最大工具调用数（50-2,000） | | `codebuddy.agent.maxDurationMinutes` | number | 10 | 每个会话最大运行时长（分钟，1-60） | | `codebuddy.failover.enabled` | boolean | true | 出错时自动进行服务商故障转移 | | `codebuddy.failover.providers` | array | [] | 有序回退服务商列表（为空时自动检测） | | `codebuddy.credentialProxy.enabled` | boolean | false | 通过本地凭据代理路由 LLM 调用 | | `codebuddy.permissionScope.defaultProfile` | enum | standard | 默认权限配置文件（restricted、standard、trusted） | | `codebuddy.accessControl.defaultMode` | enum | open | 访问控制模式（open、allow、deny） | | `codebuddy.completion.enabled` | boolean | true | 行内代码补全 | | `codebuddy.completion.provider` | enum | Local | 补全 AI 服务商（可与聊天服务商不同） | | `codebuddy.requireDiffApproval` | boolean | false | 所有文件更改都需要手动批准 | | `codebuddy.autoApprove` | boolean | false | 自动批准智能体操作，无需提示 | | `codebuddy.rules.enabled` | boolean | true | 加载项目规则并注入到提示中 | | `codebuddy.contextWindow` | enum | 16k | 上下文窗口大小（4k、8k、16k、32k、128k） | --- ## 安装 从任一注册表安装： - [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fiatinnovations.ola-code-buddy) - [Open VSX Registry](https://open-vsx.org/extension/fiatinnovations/ola-code-buddy) 或在 VS Code 扩展管理器中搜索 "CodeBuddy"。 **要求**：VS Code 1.78 或更高版本。 --- ## 构建与打包 若需自行从源码构建扩展、CLI 或独立可执行文件，请按以下流程操作。所有命令均在仓库根目录下执行。 ### 前置条件 ```bash npm install # 安装依赖（含 Webview 与扩展宿主） ``` > **Webview 资源说明**：扩展宿主通过 esbuild 把已有的 `webviewUi/dist/` 原样拷贝到 `dist/webview/assets/`（拷贝插件不会重新编译 Webview）。若你改动过 Webview 前端，需先单独编译： > > ```bash > cd webviewUi && npm run build && cd .. > ``` ### 1. 打包扩展（.vsix 单文件） ```bash npm run package # esbuild 重建扩展宿主 dist/（入口为 ./dist/extension.js） npx vsce package # 生成 ola-code-buddy-x.y.z.vsix ``` **重要**： - **必须不带 `--no-dependencies`**。该 flag 会整体丢弃 `node_modules`，导致 Windows 原生 ripgrep（`@vscode/ripgrep/bin/rg.exe`）等二进制缺失，内网离线的 Windows 设备将无法使用代码搜索。 - 正确打包出的 `.vsix` 约 29–30 MB。打包完成后务必校验关键原生依赖是否在包内： ```bash unzip -l ola-code-buddy-*.vsix | grep -E 'ripgrep/bin/rg\.exe|tree-sitter|better_sqlite3' ``` - 若 `npm run package` 之外的 `vscode:prepublish` 因历史 tsc 类型错误而失败（扩展实际入口是 esbuild 产物 `dist/extension.js`，不依赖 tsc 产出的 `out/`），可临时将 `package.json` 的 `vscode:prepublish` 改为 `node -e "0"` 再打包，打完**务必改回 `npm run compile`** 并通过 `git diff package.json` 确认已还原，切勿将其提交。 ### 2. 构建无界面 CLI（cli.js 单文件） CLI 通过 esbuild 打包为一个自包含的单文件 `dist-cli/cli.js`，其外部/原生依赖在构建时以 base64 形式内嵌，并在启动时还原： ```bash npm run build:cli # 生成 dist-cli/cli.js node dist-cli/cli.js --help # 直接运行（需本机安装 Node.js） ``` ### 3. 打包 Windows 单文件可执行程序（.exe） CLI 可进一步打包为无需单独安装 Node.js 的自包含 Windows 可执行文件（基于 Node SEA，Single Executable Application）。先构建 CLI，再封装： ```bash npm run build:cli # 先生成 dist-cli/cli.js npm run pack:cli:win # 生成 dist-cli-exe/codebuddy-cli-win.exe（约 160 MB，Windows 单文件） ``` - 产物 `dist-cli-exe/codebuddy-cli-win.exe` 已内嵌官方 `node.exe` 与运行时依赖，可在纯内网 Windows（如 Win10）上直接运行。 - 仅供本机构建验证用的 Linux 测试版（非交付物）可用：`npm run pack:cli:win:linux`。 > **为什么不用 `pkg`**：`pkg` 需从其 GitHub CDN 下载打了补丁的 Node 基础二进制，该 CDN 在离线构建机上不可达，且仅支持到 Node 18、无法在 Linux 上交叉编译 Windows 二进制，故改用 Node 原生 SEA 方案。 --- ## 配置 ### 云端服务商 1. 打开 CodeBuddy 侧边栏，点击齿轮图标打开设置。 2. 导航到"模型"部分。 3. 选择你偏好的 AI 服务商。 4. 输入你的 API 密钥。 5. （可选）在故障转移设置下配置回退链。 ### 本地模型（Ollama） ```json { "generativeAi.option": "Local", "local.baseUrl": "http://localhost:11434/v1", "local.model": "qwen2.5-coder" } ``` ### 本地模型（Docker） ```bash docker compose -f docker-compose.yml up -d docker exec -it ollama ollama pull qwen2.5-coder ``` 还支持 Docker Model Runner，可通过 Docker Desktop 内置的模型运行时在 `localhost:12434` 运行模型。 ### 凭据代理 要通过本地凭据代理路由所有 LLM API 调用（推荐用于共享环境）： 1. 通过 设置 > 模型 存储 API 密钥（它们会通过 SecretStorage 保存到操作系统钥匙串）。 2. 启用代理：将 `codebuddy.credentialProxy.enabled` 设置为 `true`。 3. 代理会在扩展激活时自动启动。SDK 客户端会收到一个虚拟的 `"proxy-managed"` 密钥与一个 `127.0.0.1` 基础 URL。 ### MCP 服务器 在 VS Code 设置的 `codebuddy.mcp.servers` 下配置 MCP 服务器。示例： ```json { "codebuddy.mcp.servers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"], "env": {} } } } ``` 或启用 Docker MCP 网关，以获得通过 Docker Desktop 管理的统一工具目录。 ### 权限配置文件 在工作区根目录创建 `.codebuddy/permissions.json`： ```json { "profile": "standard", "toolBlocklist": ["terminal"], "commandDenyPatterns": ["rm -rf", "DROP TABLE"] } ``` 完整 JSON Schema 参见 `schemas/permissions-v1.json`。 --- ## 数据存储 CodeBuddy 将所有数据本地存储在工作区根目录下的 `.codebuddy` 目录中： | 路径 | 用途 | | ------------------ | ------------------------------------------------- | | `chat-history/` | JSON 格式的对话日志 | | `memory.json` | 持久化的智能体知识、规则与经验 | | `tasks.json` | 任务追踪数据 | | `analysis.db` | 用于代码库分析快照的 SQLite 数据库 | | `vector.db` | 用于嵌入与 FTS4 索引的 SQLite 向量存储 | | `rules.md` | 项目特定的行为规则 | | `rules/` | 用于存放多个规则文件的目录 | | `skills/` | 自定义工作区技能定义 | | `permissions.json` | 工作区权限配置文件配置 | | `access.json` | 访问控制用户列表 | 此目录会自动添加到 `.gitignore`。API 密钥通过 VS Code SecretStorage 单独存储在操作系统钥匙串中。 --- ## 故障排查 **本地模型无法连接** - 验证 Ollama 是否正在运行（`ollama serve` 或检查 Docker 容器状态）。 - 确认端口：Ollama 为 11434，Docker Model Runner 为 12434。 - 检查 `local.baseUrl` 是否与你的设置匹配。 **智能体无响应** - 点击聊天界面中的停止按钮。 - 检查并发队列状态（命令面板 > `Queue Status`）——请求可能排在其他操作之后。 - 从 设置 > 隐私 清除聊天历史。 - 检查 CodeBuddy 输出通道：查看 > 输出 > CodeBuddy。 **API 密钥错误** - 验证在 设置 > 模型 中输入的密钥是否正确。 - 确认所选模型与你的密钥所属服务商匹配。 - 运行 `Doctor` 检查设置中是否存在应迁移到 SecretStorage 的明文密钥。 - 如果使用凭据代理，验证它是否正在运行（检查输出通道）。 **服务商故障转移不工作** - 确保 `codebuddy.failover.enabled` 为 `true`。 - 至少配置一个带有有效 API 密钥的备用服务商。 - 在状态栏指示器中检查服务商健康状态。 **MCP 服务器无法连接** - 验证服务器命令已安装且可访问。 - 在输出通道中检查 MCP 服务器日志。 - 对于 Docker 网关，确保 Docker Desktop 正在运行。 - 检查 MCP 熔断器状态——处于 OPEN 状态的服务器需要等待其冷却期到期。 **检测到安全问题** - 从命令面板运行 `Doctor` 以扫描配置问题。 - 使用 `Doctor Auto-Fix` 自动修复明文密钥与权限问题。 - 查看安全诊断输出以获取详细发现。 --- ## 贡献 欢迎贡献。有关设置开发环境、运行测试与提交 Pull Request 的指南，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 --- ## 许可证 MIT 许可证——详情参见 [LICENSE](LICENSE)。 --- [仓库](https://github.com/olasunkanmi-SE/codebuddy)