接入架构

开始前的准备

• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，并确认余额、套餐或模型分组可用。
• 从模型广场或控制台复制完整模型 ID，并确认模型是否支持工具调用、图像输入和推理参数。
• 安装当前版本 Zed，打开一个可回滚的 Git 项目，并先保存现有修改。
• 确认模型的实际上下文窗口和最大输出长度。settings.json 中不能虚报这些数值。

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复：连接成功"}],
    "stream": false
  }' 

使用设置界面添加 Provider

1. 打开命令面板并运行 agent: open settings。
2. 进入 AI 下的 LLM Providers，选择 Add Provider。
3. 选择 OpenAI Compati*le，并把 Provider ID 设为 kingflow。
4. API **L 填写 https://api.**nju**shen.com/v1，不要追加 chat/completions。
5. 填写 KingFlow API Key。Zed 会把它保存到系统钥匙串，而不是 settings.json。
6. 填写控制台中的完整模型 ID和真实上下文窗口，保存后在模型选择器中选中该模型。

使用 settings json 配置

{
  "language_models": {
    "openai_compati*le": {
      "kingflow": {
        "api_url": "https://api.**nju**shen.com/v1",
        "**aila*le_models": [
          {
            "name": "<完整模型ID>",
            "display_name": "KingFlow Coding",
            "**x_tokens": 128000,
            "**x_output_tokens": 8192
          }
        ]
      }
    }
  }
}

使用环境变量提供密钥

$env:KINGFLOW_API_KEY="sk-你的密钥"
# 从同一 PowerShell 窗口启动 Zed

export KINGFLOW_API_KEY="sk-你的密钥"
# 从同一终端启动 Zed

确认模型能力

{
  "name": "<推理模型完整ID>",
  "display_name": "KingFlow Reasoning",
  "**x_tokens": 128000,
  "**x_output_tokens": 16384,
  "reasoning_effort": "high",
  "capa**lities": {
    "tools": true,
    "i**ges": false,
    "chat_completions": true
  }
}

运行首次只读线程

请只读分析当前项目，不要修改文件，也不要运行终端命令。

请列出：
1. 项目主要语言和框架
2. 主要入口文件
3. 构建与测试命令所在位置
4. 最值得先阅读的三个文件及理由

控制上下文范围

执行小范围修改

只修改 @src/example.ts 中选中的函数：
- 保持公开接口不变
- 为异常输入补充校验
- 不修改其他文件
- 不运行终端命令
- 完成后说明每处修改的理由

审阅和恢复修改

修改完成后打开 Review Changes，逐块保留或拒绝。若线程方向错误，使用 Restore Checkpoint 恢复到该消息之前。并行线程可能修改相同文件时，先创建独立 Git worktree。

完成联调验证

• 模型选择器显示 KingFlow Coding，基础问答能正常返回。
• KingFlow 控制台出现对应模型的调用记录，密钥和分组状态正常。
• 首次只读任务能引用真实项目文件，并且没有产生工作区修改。
• 需要工具时，Zed 显示具体工具调用；不支持工具的模型会出现 No tools 提示。
• 编辑后 Review Changes 能显示文件和差异块，可以逐块保留或拒绝。
• Restore Checkpoint 能恢复到本轮修改前的状态。

保护密钥和代码

• 不要把 API Key 写入 settings.json。优先使用设置界面的系统钥匙串，或在本机环境变量中提供。
• 环境变量优先于钥匙串。更换密钥后要清除旧环境变量并重启 Zed，避免继续使用旧值。
• 首次接入关闭或逐次确认终端、删除文件、工作区外访问和外部工具权限。
• 只添加任务需要的文件和选择区作为上下文，不要向模型发送密钥、客户数据和生产日志。
• 在独立 Git 分支或工作树中执行修改，逐块审阅差异，再运行测试和提交。

完成检查清单

• Zed 已更新并能打开 Agent Settings。
• KingFlow 基础接口已使用 https://api.**nju**shen.com/v1 验证。
• Provider ID 为 kingflow，模型 ID 来自控制台。
• API Key 保存在系统钥匙串或 KINGFLOW_API_KEY 环境变量。
• settings.json 中没有真实密钥。
• 上下文窗口和输出上限按模型真实规格填写。
• 首次只读任务、工具提示、Review Changes 和 Restore Checkpoint 已验证。

常见故障排查