Zoo Code

把持续维护的 VS Code 编程 Agent 接入 TokenMix。

Zoo Code 是什么

Zoo Code 是一个运行在 VS Code 里的 AI 编程 Agent。它可以读代码、解释文件、生成代码、重构、调试，也支持 Code、Architect、Ask、Debug 和 Custom Modes。普通用户可以先把它当成“在编辑器里的 AI 编程助手”: 先问问题，再让它给方案，最后再允许它改文件。

Zoo Code 可以通过 OpenAI Compatible 供应商接入 TokenMix。你不需要部署 Zoo Code，也不需要自己写接口，只需要在扩展设置里把 API 地址改成 TokenMix 的地址。

准备 TokenMix 信息

先准备 3 个值:

• Provider: OpenAI Compatible
• Base URL: https://api.tokenmix.ai/v1
• API Key: 你的 TokenMix API Key
• Model: TokenMix 模型 ID，例如 <your-model-short-id>

注意 Base URL 必须包含 /v1。不要填成 OpenAI 官方地址，也不要只填 https://api.tokenmix.ai。

安装 Zoo Code

1. 打开 VS Code。
2. 打开 Extensions。
3. 搜索 Zoo Code。
4. 确认扩展 ID 是 ZooCodeOrganization.zoo-code。
5. 点击 Install。
6. 安装后打开 Zoo Code 面板或命令面板里的 Zoo Code 设置。

如果你从其它 VS Code 编程 Agent 迁移过来，可以先只迁移基础模型配置。确认聊天和代码生成正常后，再迁移 MCP、命令执行权限、项目规则等高级配置。

配置 TokenMix API

1. 在 Zoo Code 里打开 Settings 或 Provider 设置。
2. 找到 API Provider / Model Provider。
3. 选择 OpenAI Compatible。
4. Base URL 填 https://api.tokenmix.ai/v1。
5. API Key 填你的 TokenMix Key。
6. Model 填 TokenMix 模型 ID。
7. 如果设置页里有 Reasoning、Responses API、Embedding、Code Index、Context Window 等高级选项，第一次先保持默认。
8. 保存设置。

API Key 通常会保存在 VS Code 的 Secret Storage 里。不要把 Key 写进 .env、README、项目配置文件或截图里。

第一次测试

建议先在临时项目或测试分支里试。不要一开始就让 Agent 修改生产仓库。

可以先用 Ask 模式测试:

请解释当前文件的主要作用，不要修改代码。

再用 Architect 模式测试:

请给出一个经典前后端分离架构图的实现方案，包含前端、后端、数据库、缓存和对象存储，不要修改文件。

确认回答正常后，再用 Code 模式做一个很小的改动:

请新增一个 TypeScript 函数，用来校验 email 字符串格式，并补充一个简单示例。

如果这 3 步都正常，说明 TokenMix 的 Base URL、Key、模型 ID 基本配置正确。

推荐使用顺序

1. Ask: 只解释代码，不改文件。
2. Architect: 先写方案，让你确认方向。
3. Code: 做小范围代码修改。
4. Debug: 针对明确错误定位问题。
5. Custom Modes: 为团队固定常用工作流。
6. MCP Servers: 在模型连接稳定后，再接入外部工具。

这个顺序对新手更安全。IDE Agent 可以读写文件、运行命令，所以一开始要让它做小任务，等你熟悉权限提示后再交给它更大的任务。

MCP 使用说明

Zoo Code 支持 MCP Servers。MCP 可以让 Agent 调用额外工具，例如读取外部文档、操作设计工具、访问数据库只读查询、调用内部服务等。

建议这样接入:

1. 先只配置 TokenMix 模型，确认普通聊天可用。
2. 再添加一个最简单的 MCP Server。
3. 测试 Agent 是否能看到工具列表。
4. 第一次调用 MCP 时，只做只读任务。
5. 涉及写文件、执行命令、改数据库的 MCP，要单独确认权限。

不要在模型还没连通时同时配置 MCP。这样出错时更难判断是 API、模型、权限还是 MCP 配置的问题。

Code Index 和 Embedding

如果你开启 Code Index 或代码库检索功能，可能还需要配置 embedding 模型。原则是:

• 聊天模型和 embedding 模型可以分开配置。
• 如果界面支持 OpenAI Compatible embedding，可以继续使用 TokenMix 的 embedding 模型。
• Embedding Base URL 仍然使用 https://api.tokenmix.ai/v1。
• Model 填 TokenMix 上可用的 embedding 模型 ID。
• 如果界面要求 dimension，按所选 embedding 模型的说明填写。

新手可以先不开 Code Index。普通问答、改小文件、解释代码可以先跑通，后面再补检索能力。

常见问题

• 401 或 unauthorized: API Key 填错、复制了多余空格，或 Key 已失效。
• model not found: Model 不是 TokenMix 模型 ID，或者账号没有这个模型权限。
• Base URL error: Base URL 没有写 /v1，请改成 https://api.tokenmix.ai/v1。
• 请求发到 OpenAI: Provider 没选 OpenAI Compatible，或者 Base URL 仍是默认值。
• 输出中断: 换上下文更大的模型，或减少一次性输入的文件数量。
• 工具调用被拒绝: 检查 Zoo Code 的权限弹窗和 VS Code 工作区信任状态。
• MCP 不生效: 先确认普通聊天可用，再检查 MCP Server 是否启动、配置路径是否正确。

给新手的建议

第一次使用时，把 Zoo Code 当成“会写代码但需要你确认的助手”。让它先解释、再给计划、最后再修改。涉及支付、登录、数据库、生产配置和密钥的文件，不要直接让 Agent 自动修改。每次改完都看 diff，再运行项目测试或构建。