为 GitHub Copilot 添加自定义 AI 供应商与模型、快捷构造MCP工具的 VS Code 扩展
- 目录 Table of Contents
- 简介 Introduction
- 特性 Features
- 快速开始 Quick Start
- 安装 Installation
- 使用概览 Usage Overview
- 供应商与模型管理 Provider & Model Management
- 自定义工具 Custom Tools (MCP)
- 命令 Commands
- 配置项 Settings Items
- 配置文件格式 Config Format
- 调试游乐场 Debug Playground
- 常见问题 FAQ
- 故障排除 Troubleshooting
- 许可证 License
- 免责声明 Disclaimer
- 致谢 Thanks
Addi 让你在 VS Code 中为 GitHub Copilot 添加自定义 / 第三方 / 自建 AI Provider 与模型，并在 Copilot 原生模型选择器中一键切换。它既是一个模型管理器，也是一个交互式调试 Playground，同时还是一个快捷构造 MCP 工具微服务。
Tip
虽然 vscode 官方有支持自定义模型的计划，但目前仍未开放给大众用户，Addi 作为一个临时解决方案，可以帮助你快速上手并测试各种模型。详见 Bring Your Own Language Model 以及 Use an OpenAI-Compatible Model。
| 类别 | 说明 |
|---|---|
| Provider 管理 | 添加 / 编辑 / 复制 / 删除 / 快速编辑 API Key |
| 模型管理 | 绑定于 Provider 的模型定义与特性标记（视觉 / 工具调用支持等） |
| 智能模型验证 | 自动检测连通性、视觉能力、工具调用支持和 Token 限制 |
| 模型切换 | 在 Copilot 模型选择器中勾选后即可切换自定义模型 |
| 配置导入导出 | JSON 结构备份 / 迁移到其他机器 |
| 可配置默认参数 | 默认 family / version / token 限制 |
| 排序选项 | 支持按字母、输入/输出 Token 数排序供应商和模型 |
| UI / 树视图 | 直观的 ActivityBar 侧边栏管理界面 |
| 非预期行为处理 | 检测并清洗幻觉工具调用标签，或自动重试以强制工具调用 |
| 右键上下文操作 | 针对 Provider / Model 的快捷操作 |
| Playground 调试 | 发送消息、调节参数、实时查看日志 |
| SSE 流式输出 | 支持 OpenAI 及兼容端点增量输出 |
| 参数持久化 | 最近一次 Playground 参数自动恢复 |
| 测试覆盖 | Streaming / 参数裁剪与持久化测试 |
| 日志输出 | 专用 output channel 与可调 Log Level |
1. 安装扩展（市场或本地 VSIX）
2. 打开侧边栏 “Addi”
3. 添加 Provider（填写端点与 API Key）
4. 为该 Provider 添加模型（id / token 限制等）
5. 在 Copilot → 模型下拉 → 管理模型 → 勾选你的模型
6. 返回聊天界面，选择并使用它！
搜索 “Addi” 并安装；或命令面板输入：ext install addi。
npm install; npm run package
code --install-extension addi.vsix
# 或在 VS Code 文件列表中右键安装Activity Bar 中的 Addi 图标 → 展开树：
- Provider：可快速添加模型 / 编辑密钥 / 管理模型
- Custom Tools：添加 / 管理 MCP 自定义工具
Warning
完整利用自定义模型的 Edit / Agent 模式可能需要 GitHub Copilot Pro 级别订阅；Free 版本目前测试仅支持用于 Ask 模式使用自定义模型。请确保账户权限满足需求。
- 点击 “Add Provider”
- 填写：名称 / 描述 / 网站 / API Endpoint / API Key / 接口类型(OpenAI 兼容等)
- 保存后出现在列表
- 选中 Provider → Add Model
- 填写：id / 名称(可选) / maxInputTokens / maxOutputTokens / 视觉支持 / 工具支持
- 保存后挂载在对应 Provider 下
在添加或编辑模型时，点击底部的 "Verify & Detect" 按钮可以自动测试：
- 连通性：检查 API Key 和 Endpoint 是否有效
- 视觉能力：自动检测模型是否支持图片输入
- 工具调用：自动检测模型是否支持 Function Calling
- Token 限制：自动探测并填充 Max Input / Output Tokens (使用二分查找与参数估算，不消耗真实 Token)
Tip
如果不确定模型的 Token 限制，可以将 Max Input Tokens 和 Max Output Tokens 留空（或设为?），点击 Verify & Detect 后 Addi 会自动探测并填入建议值。如果检测不准确，请参照官方模型文档手动设置。
所有附属能力（视觉 / 工具调用）也会在验证过程中自动测试并更新勾选（不适配则会自动去除勾选）。
Provider 节点右侧钥匙图标 → 输入密钥 → 保存。
Addi 内置了一个 Model Context Protocol (MCP) Server，支持通过 YAML 文件定义自定义工具。这意味着你的本地脚本可以被 AI 像原生函数一样调用。
并且为了方便用户理解与编辑，Addi 的自定义工具语法完全兼容 GitHub Actions 的 composite 语法规范，使用优秀的开源本地化 actions 运行项目 nektos/act 作为模板解析引擎。
详细文档与示例：自定义工具指南 (CUSTOM_TOOLS.md)
- 多语言支持: 支持 PowerShell, Bash, Python, Node.js 等多种运行时。
- 热重载: 修改 YAML 文件后自动生效，无需重启 VS Code。
- 无缝集成: 兼容 GitHub Actions
composite语法。
Tip
自定义工具的 YAML 文件支持热重载，修改后会自动生效，无需重启 VS Code 或手动处置 Addi MCP Server 进程。
但因 VS Code 资源按需运行的基本原则，修改 yaml 模板文件后的 Copilot 工具列表将只会在 Chat 触发服务启动时发出 list_tool 并更新 UI 中显示的工具。或您可尝试通过命令面板执行 MCP: List Server 选中并手动启动服务来同步刚增加修改或删除的工具列表。
- 创建工具文件：在
.addi/public/(共享) 或.addi/private/(私有) 目录下创建.yaml文件。 - 定义工具：
name: 'get-ip' description: 'Get public IP' runs: using: 'composite' steps: - run: curl -s http://ip-api.com/json/ shell: bash
- 使用工具：在对话中直接询问 "Check my IP"。
Addi 提供了一个强大的正则表达式过滤系统，用于处理模型输出中的非预期行为。此功能在模型设置界面中配置，支持实时测试和验证。
- 自定义正则表达式: 配置正则表达式来匹配需要过滤或修改的内容（如非预期的工具调用格式）
- 实时验证: 界面提供实时测试功能，可以立即验证正则表达式的有效性
- 多种处置方式:
- 重试: 当匹配到设定的内容时，自动去除非法内容并重新发送请求以获取新的输出
- 停止: 当匹配到设定的内容时，停止当前请求等待用户进行后续操作
- 实时测试: 在编辑器界面中可以输入测试内容并预览过滤效果
- 工具名匹配: 支持针对特定工具名称进行
RegExp Group匹配，以便更精确地控制过滤行为（无工具名则使用tool_choice: required重试）
Tip
- 在配置正则表达式时，可以使用界面提供的测试区域输入示例文本，实时查看匹配结果和处置效果。
- 尽量使用简短且高效的正则表达式，以减少对模型输出的影响。
- 该功能适用于需要严格控制模型输出的场景，如过滤幻觉工具调用或危害信息。
- 如出现不一致工具调用行为，可尝试同时减小
Max Input Tokens以提升模型响应的稳定性。
- 过滤幻觉工具调用: 如果模型输出中经常包含错误的工具调用标签，可以使用正则表达式匹配这些标签并选择“重试”处置方式，以确保输出的准确性。
- 危害信息处理: 如果模型输出中可能包含危害信息，可以使用正则表达式匹配这些信息并选择“停止”处置方式，以防止不当内容的传播。
Warning
此功能处于 预览阶段，请谨慎使用并充分测试。
- 正则表达式配置不当可能导致意外行为，建议先使用界面提供的测试功能验证
- 过度使用可能影响模型输出的自然性和准确性
- 请确保正则表达式不会误删或误改重要信息
- 建议在生产环境使用前进行充分的测试
在编辑器界面中：
- 填写正则表达式（如
<\s*tool_call\s*>.*?<\s*/\s*tool_call\s*>用于匹配错误的类似functionCall调用标签） - 选择处置方式（"重试"或"停止"）
- 使用测试区域输入示例文本确认正则准确性
- 保存配置后，Addi 会在模型输出时自动根据规则检查内容是否匹配并执行相应处置
| Command ID | 标题 | 用途 |
|---|---|---|
addi.manage |
Management | 打开管理视图 |
addi.exportConfig |
Export Configuration | 导出配置 (支持加密) |
addi.importConfig |
Import Configuration | 导入配置 (支持解密) |
addi.showLogs |
Show Logs | 打开 Addi 日志输出 |
注意: 导出配置时，如果不设置密码，导出的 JSON 文件将不包含任何 API Key（为了安全）。如果需要备份或迁移 API Key，请务必设置导出密码，此时文件将以加密格式保存。
Show Logs 将在 VS Code 的 输出 (Output) 面板中定位 "Addi" 通道，可随时查看调试信息。日志内容会自动脱敏，并额外记录模型解析、请求选项等关键上下文，便于排查问题。
这些命令大多通过树视图右键或标题按钮触发，命令面板默认隐藏。
| Setting | 默认 | 说明 |
|---|---|---|
addi.defaultMaxInputTokens |
4028 | 默认最大输入 tokens |
addi.defaultMaxOutputTokens |
1024 | 默认最大输出 tokens |
addi.defaultModelFamily |
"Addi" | 默认模型 family |
addi.defaultModelVersion |
"1.0.0" | 默认模型 version |
addi.saveConfigToSettingsSync |
true | 是否保存到 VSCode Settings Sync 云端 |
addi.sortRule |
"none" | 排序规则 (none/alphabet/input tokens/output tokens) |
addi.sortTarget |
"both" | 排序目标 (providers/models/both) |
更改方法：VS Code 设置搜索 “addi” 或在视图标题中点击 Settings。
配置文件以 JSON 多维数组存储，每个供应商包含其模型列表：
[
{
"id": "provider-id",
"name": "OpenAI",
"providerType": "openai",
"description": "提供 GPT 系列模型",
"website": "https://openai.com",
"apiEndpoint": "https://api.openai.com/v1",
"apiKey": "sk-...",
"models": [
{
"id": "gpt-4",
"name": "GPT-4",
"family": "Addi",
"version": "1.0.0",
"maxInputTokens": 8192,
"maxOutputTokens": 2048,
"capabilities": {
"imageInput": false,
"toolCalling": false
}
}
]
}
]提供交互式调试界面，发送消息、调节参数、查看日志。现阶段主要用于测试与调试自定义模型参数。
支持设定参数：Temperature / Top P / Max Output Tokens / Presence Penalty / Frequency Penalty / System Prompt。参数在 workspaceState 中持久化。OpenAI 兼容端点支持 SSE 流式增量输出，可中途取消（AbortController）。不支持流的 Provider 自动回退普通请求。
A: 请确保：
- 您已为供应商配置了 API 密钥
- 您使用的是 GitHub Copilot 个人计划
- 模型已正确添加并保存
A: 您可以在 Copilot 聊天界面的模型选择器中查看当前选中的模型。
A: 扩展对供应商和模型数量没有硬性限制，但建议根据您的实际需求合理添加。
A: 请确保：
- 自定义工具的 YAML 文件位于正确的目录（
.addi/public/或.addi/private/）。 - 文件格式符合规范且无语法错误。
- MCP 服务器已启动（修改 YAML 文件后，发起一次对话，或可通过执行
MCP: Start Server命令手动启动）。
| 问题 | 排查步骤 |
|---|---|
| 无法切换模型 | 重启 VS Code / 确认 Provider Key / 在模型管理面板勾选显示模型 |
| 无法在 Agent 模式使用 | 确认 Copilot 订阅等级 / 检查模型支持情况（官方要求需支持工具调用） |
| 新增的工具不显示 | 确认 YAML 语法正确 / 检查文件路径 / 确认 MCP 服务器已在运行 |
| 工具列表重复显示 | 重启 VS Code / 确认没有自编译版本的 Addi 插件及 MCP 服务正在运行 |
| 请求失败 | 查看 Addi 输出日志 & 控制台 / 校验 API Endpoint & Key |
| 流式不工作 | Provider 是否支持 SSE；禁用流后重试 |
| 配置未同步 | 检查 addi.saveConfigToSettingsSync 设置 |
| 接口兼容性问题 | 检查 Provider 类型设置 / 查看日志了解请求细节 / 切换其他类型测试 |
MIT © 2026-present deepwn — 详见 LICENSE。
本扩展仅提供客户端功能，使用第三方 / 自建 API 带来的数据与安全风险由使用者自行承担。我们不对直接或间接损失负责。
- GitHub Copilot 团队与 VS Code 扩展生态
- OpenAI / Anthropic / Google 等公共 API 生态
- 所有提交 Issue / PR 的贡献者 🙌
欢迎 Star 支持项目，如果它对你有帮助！