## 区分三个独立环节

1. **软件账号授权**：决定用户是否能使用对应软件和组件。
2. **模型连接配置**：决定请求发给哪个服务、使用什么模型和凭证。
3. **组件业务接入**：决定当前插件如何使用目标宿主已经开放的能力。

登录软件成功不代表模型连接完成，软件授权也不代表外部模型用量无限或费用已包含。

## 在设置中建立模型连接

| 字段 | 核对内容 |
| --- | --- |
| 配置名称 | 便于区分用途，例如日常研究或测试连接；不要使用密钥作为名称 |
| Base URL | 服务提供的基础地址，核对协议、主机和路径前缀 |
| API Key | 服务凭证的有效期、额度与允许访问的模型 |
| 模型 ID | 请求中的准确 ID，不仅是界面展示名称 |
| 接入方式 | API、受支持的账号授权或其他实际入口；不可混用凭证 |

```text
名称：测试模型连接
Base URL：https://api.example.com/v1
API Key：在本机软件设置中填写
模型 ID：按服务实际提供的标识填写
```

以上是占位示例。不要把网页聊天地址填成 API 地址，也不要未经核对重复拼接 `/v1` 或消息路径。

## 分三层验证

### 服务能否连通

先检查域名、TLS、代理和网络。使用短请求验证，不拿完整比赛项目做第一次连接测试。

### 基础对话能否返回

确认认证、模型权限和流式响应。基础聊天成功不等于工具、图片或长上下文都已经支持。

### 实际工具流程能否完成

用一个最小测试项目验证读取材料、执行简单计算、保存结果和预览。工具调用协议不完整时，应该报告实际失败阶段，不能把缺少能力笼统显示为网络超时。

## 插件如何接入

清单中的 `ai` 是能力需求声明，不会自动生成通用 `api.chat()`。第三方组件应核对目标宿主实际开放的调用方法、参数、事件和取消机制。

内置代码或研究组件可能依赖自己的业务 IPC，不能只复制一个名字到第三方插件里就认为可用。新增系统桥接时，应配套修改主进程、preload 和组件调用，确定最低宿主版本。

如果没有受支持的接入方法，组件要明确提示能力尚不可用，并向维护者提交接口需求；不能在公开源码中塞入作者自己的服务密钥代替用户配置。

## 失败分层处理

| 表现 | 优先核对 | 处理方向 |
| --- | --- | --- |
| 认证错误 | 凭证、填写位置和服务账号 | 核对配置，错误日志脱敏 |
| 权限或模型不可用 | 模型 ID、访问范围 | 确认目标账号支持该模型 |
| 频率或额度限制 | 服务余额、并发和限流 | 降低并发，按服务说明重试 |
| 路径不存在 | Base URL 和协议 | 一次调整一个因素 |
| 流式中断 | 代理、网络、上下文 | 保留已收到内容，先复现短请求 |
| 本地工具超时 | 环境、工作目录和启动阶段 | 按本地工具排查，不混同模型连接 |

## 日志、取消和数据保护

记录模型 ID、阶段、状态码、耗时和经过脱敏的错误；不要记录 Key、Cookie、密码或完整敏感材料。取消后让旧运行身份失效，同时调用实际请求的取消机制。

切换模型不能让上一轮流式响应继续写入新任务。断网或调用失败时保留项目和已有产出，只更新本次操作的状态。