如何接入 Kimi (Moonshot AI) 到 WorkBuddy

本教程将详细指导你将 月之暗面（Moonshot AI） 的旗舰模型 Kimi K2.5 接入 WorkBuddy，让你在对话中直接调用这款拥有 256K 超长上下文、原生多模态理解 和 Tool Calling 能力的顶尖大模型。

为什么选择 Kimi？

前置准备

在开始之前，请确保你已经完成以下准备工作：

• 已有 WorkBuddy 客户端账号
• 准备好中国大陆手机号（用于实名认证）

步骤一：注册 Moonshot 开发者平台

1. 打开 Kimi 开放平台，点击右上角「注册」。
2. 使用中国大陆手机号（+86）完成验证码验证。
3. 进行实名认证：
   • 个人用户：填写身份证号即可，通常即时通过
   • 企业用户：需上传营业执照，审核约 1-3 个工作日
4. 认证通过后自动跳转到控制台。

步骤二：获取 API Key

API Key 是调用的唯一凭证，请妥善保管。

1. 在控制台左侧导航栏找到「API 密钥」页面。
2. 点击「创建密钥」按钮。
3. 为密钥命名（建议按用途命名，如
   text

   复制

   1workbuddy-生产

   、
   text

   复制

   1test-开发

   ）。
4. 创建成功后，系统会显示以
   text

   复制

   1sk-

   开头的完整 Key。

text
复制
1sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

安全最佳实践

• ❌ 绝不将 API Key 写入代码文件提交到 Git 仓库
• ✅ 使用环境变量
  text

  复制

  1.env

  文件存储（记得加入
  text

  复制

  1.gitignore

  ）
• ✅ 生产环境和测试环境使用不同的 Key
• ✅ 定期轮换密钥，关注用量异常防止泄露

步骤三：了解可用模型

Moonshot 平台提供多个模型版本，以下是核心推荐：

1kimi-k2.5

1moonshot-v1-128k

1moonshot-v1-32k

1moonshot-v1-8k

步骤四：在 WorkBuddy 中配置

WorkBuddy 支持多种方式接入自定义模型，以下提供两种方案：

方案 A：通过集成界面配置（推荐）

1. 启动 WorkBuddy 客户端
2. 进入 设置 → 左下角头像 → Claw 设置 → 集成 (BETA)
3. 选择「自定义模型 / OpenAI 兼容」类型
4. 填写以下配置：

json
复制
1{
2  "provider_name": "Kimi K2.5 (Moonshot AI)",
3  "base_url": "https://api.moonshot.cn/v1",
4  "api_key": "你的_API_Key_在此填入",
5  "default_model": "kimi-k2.5",
6  "models": [
7    {
8      "id": "kimi-k2.5",
9      "name": "Kimi K2.5 (256K 多模态)"
10    },
11    {
12      "id": "moonshot-v1-32k",
13      "name": "Moonshot V1-32K"
14    }
15  ]
16}

1. 点击「测试连接」确认配置无误
2. 保存并设为默认模型

方案 B：通过环境变量配置

如果你偏好命令行管理，也可以通过环境变量注入：

bash
复制
1# Windows PowerShell
2$env:MOONSHOT_API_KEY = "你的_API_Key"
3$env:OPENAI_BASE_URL = "https://api.moonshot.cn/v1"
4
5# Linux / macOS
6export MOONSHOT_API_KEY="你的_API_Key"
7export OPENAI_BASE_URL="https://api.moonshot.cn/v1"

然后在 WorkBuddy 配置文件中引用这些环境变量。

步骤五：测试验证

配置完成后，发送一条测试消息确认连接正常：

text
复制
1你好 Kimi，请简单介绍一下你自己，包括你最大的特点是什么？

预期正常回复应包含：

• ✅ 自称为 Kimi 或由 Moonshot AI 提供
• ✅ 提及超长上下文（256K）、多模态等核心能力
• ✅ 响应在 2-5 秒内返回

如果遇到问题，参见下方「故障排查」章节。

场景应用示例

场景 1：超长文档分析与摘要

Kimi 最突出的能力之一是处理超长文本。你可以一次性传入整份技术文档或法律合同进行智能分析。

Python 示例：

python
复制
1from openai import OpenAI
2
3client = OpenAI(
4    api_key="你的_MOONSHOT_API_KEY",
5    base_url="https://api.moonshot.cn/v1",
6)
7
8# 读取长文档（支持最高 256K tokens）
9with open("技术架构文档.md", "r", encoding="utf-8") as f:
10    long_document = f.read()
11
12response = client.chat.completions.create(
13    model="kimi-k2.5",
14    messages=[
15        {"role": "system", "content": "你是资深技术分析师，擅长从长文档中提取关键信息和架构要点。"},
16        {"role": "user", "content": f"请对以下文档进行结构化摘要，提取：\n1. 核心架构设计\n2. 技术选型决策\n3. 潜在风险点\n\n文档内容如下：\n\n{long_document}"}
17    ],
18    temperature=0.3,  # 低温度保证输出稳定
19)
20
21print(response.choices[0].message.content)

预期效果：

• 一键生成结构化摘要，无需手动翻阅数百页文档
• 准确提取架构决策与技术债务
• 可用于代码库迁移评审、合同审查等场景

场景 2：多模态图片理解

Kimi K2.5 原生支持视觉理解，可直接分析截图、图表和 UI 设计稿。

Python 示例：

python
复制
1import base64
2
3def analyze_screenshot(image_path: str):
4    """分析截图内容，提取文字和布局信息"""
5    
6    # 将图片转为 base64
7    with open(image_path, "rb") as f:
8        image_data = base64.b64encode(f.read()).decode("utf-8")
9    
10    response = client.chat.completions.create(
11        model="kimi-k2.5",
12        messages=[
13            {"role": "system", "content": "你是 UI 分析专家，擅长从截图中提取交互逻辑和信息层次。"},
14            {
15                "role": "user",
16                "content": [
17                    {
18                        "type": "text",
19                        "text": "请分析这张截图：1) 描述整体布局 2) 列出所有可交互元素 3) 提出至少 3 个改进建议"
20                    },
21                    {
22                        "type": "image_url",
23                        "image_url": {"url": f"data:image/png;base64,{image_data}"}
24                    }
25                ]
26            }
27        ]
28    )
29    
30    return response.choices[0].message.content
31
32# 使用示例
33result = analyze_screenshot("dashboard-screenshot.png")
34print(result)

预期效果：

• 自动识别截图中的 UI 元素及其层级关系
• 输出可操作的改进建议清单
• 特别适合产品需求评审、竞品分析

场景 3：智能代码助手

利用 Kimi K2.5 强大的代码生成能力构建编程助手。

Node.js 示例：

javascript
复制
1const OpenAI = require("openai");
2
3const client = new OpenAI({
4    apiKey: process.env.MOONSHOT_API_KEY,
5    baseURL: "https://api.moonshot.cn/v1",
6});
7
8async function codeAssistant(userCode, instruction) {
9    const completion = await client.chat.completions.create({
10        model: "kimi-k2.5",
11        messages: [
12            {
13                role: "system",
14                content: `你是高级 .NET 开发工程师。遵循以下原则：
15- 使用 C# 12+ 语法特性
16- 注重代码可读性和 SOLID 原则
17- 对数据库操作优先使用 Dapper ORM
18- 包含必要的 XML 文档注释`
19            },
20            {
21                role: "user",
22                content: `以下是我的代码：
23\`\`\`csharp
24${userCode}
25\`\`\`
26
27请根据以下要求进行修改：${instruction}`
28            }
29        ],
30        temperature: 0.2,
31    });
32
33    return completion.choices[0].message.content;
34}
35
36// 使用示例
37const result = await codeAssistant(`
38public async Task<List<InventoryDto>> GetInventoryAsync(int warehouseId)
39{
40    // TODO: 实现
41}
42`, "使用 Dapper + SQL Server 编写完整的库存查询方法，包含分页参数");
43console.log(result);

预期效果：

• 自动补全 TODO 方法实现
• 生成符合项目规范的生产级代码
• 支持 C#、Python、JavaScript 等主流语言

最佳实践

性能优化

1stream: true

安全建议

1. 凭证隔离：开发和生产使用不同 API Key，便于追踪用量和排查泄露
2. 输入过滤：对用户输入做敏感词过滤，避免 prompt injection 攻击
3. 输出审核：涉及金融/医疗等敏感领域时，增加人工复核环节
4. 用量监控：定期检查控制台的用量统计，设置异常消费告警阈值
5. 权限最小化：仅授予 API Key 必要的模型调用权限

故障排查速查表

1401 Unauthorized

1429 Too Many Requests

1Invalid Model

1kimi-k2.5

1Kimi-K2.5

1Context Length Exceeded

成本估算参考

以 Kimi K2.5 为例（¥4 输入 / ¥20 输出 per 百万 token）：

扩展与进阶

Tool Calling（函数调用）

Kimi K2.5 原生支持 Tool Calling，可实现 Agent 类应用：

python
复制
1tools = [{
2    "type": "function",
3    "function": {
4        "name": "get_weather",
5        "description": "获取指定城市的实时天气",
6        "parameters": {
7            "type": "object",
8            "properties": {
9                "city": {"type": "string", "description": "城市名称"}
10            },
11            "required": ["city"]
12        }
13    }
14}]
15
16response = client.chat.completions.create(
17    model="kimi-k2.5",
18    messages=[{"role": "user", "content": "今天北京天气怎么样？"}],
19    tools=tools,
20)

联网搜索

Kimi 内置联网搜索能力，可在 conversation 中获取实时信息：

python
复制
1response = client.chat.completions.create(
2    model="kimi-k2.5",
3    messages=[{"role": "user", "content": "查询今天的 A 股大盘走势"}],
4)
5# Kimi 会自动调用搜索引擎返回实时数据

相关资源

• 官方文档：Kimi API 开放平台
• 定价详情：产品定价页
• 控制台：Moonshot 开发者后台
• 社区交流：Moonshot Discord 社区
• SDK 参考：OpenAI Python SDK（Kimi 完全兼容）