大模型适配与 BYOK 规范手册

本文档是面向 GETSSH 用户、开发者与安全审计团队的权威参考手册，系统记录了 GETSSH 当前已集成、正在评测，以及明确暂不接入的大模型厂商现状、深度协议对接规范、BYOK 零数据留存安全标准与流式状态机设计。

适配矩阵总览与厂商评选标准
核心原则：零数据留存（BYOK 安全承诺）
为什么拒绝「通用 OpenAI 封装」？
统一模型抽象：Typed Block 状态机
当前已深度适配的模型
内部评测中的模型
暂不接入的模型与厂商
流式工具调用聚合表
实施清单与错误分流机制

1. 适配矩阵总览与厂商评选标准

GETSSH 作为面向生产运维场景的 AI Agent 终端，对模型的接入有着远比普通对话类应用更严苛的要求。内部团队持续对市面上主流与新兴的大模型进行系统性测试，并基于以下核心标准决定是否将其纳入官方适配。

入选标准

可靠的函数调用（Function Calling / Tool Use）：多轮工具调用不丢失上下文，参数格式稳定可解析，不会随版本迭代静默回退。
流式输出稳定性：SSE 流不乱序、不重复、不静默丢包，断流可恢复，可正确触发流式收尾事件。
Agent 级多步骤推理：能够在复杂运维任务中（如：分析崩溃日志 → 构建恢复方案 → 人工确认 → 执行）维持多步状态而不失忆。
BYOK 隐私兼容性：支持 API Key 直连官方端点，无强制云端会话留存，不依赖厂商私有账号体系作为前提。
协议稳定性：API 设计成熟，不频繁引入破坏性变更；适配层维护成本可控。

厂商分级

状态	说明
✅ 深度适配	已完成完整定制适配层，覆盖思维链分离、工具调用、BYOK 与错误分流
🔬 内测评估中	正在进行协议深度评测，预计在特定版本中推出
⏸ 暂不接入	当前 Agent 能力或协议成熟度不满足生产级准入标准
🌐 通用适配兜底	任何符合 `/v1/chat/completions` 规范的自建端点均可接入，但不享有针对性优化

2. 核心原则：零数据留存（BYOK 安全承诺）

GETSSH 定位为本地生产力终端与基础设施管理工具，终端操作高度涉及企业生产环境拓扑、密钥与业务日志。

客户端 BYOK 准则

自带密钥，直连官方：用户的 API Key 经操作系统原生安全芯片（macOS Keychain / Secure Enclave、Windows DPAPI、Linux Secret Service）加密隔离，只在发往对应模型厂商官方域名时直接注入。
强制关闭服务端会话存储（store: false）：
- OpenAI Responses API 默认将对话留存在其服务器（store: true）。GETSSH 在所有出站请求中硬编码显式下发 store: false。
- Google Gemini Interactions API 同样显式下发 store: false。
- 用户的所有主机清单、SSH 会话历史与日志排障片段绝不作为语料沉淀在云端。
无中间代理中间人：除非用户显式配置自建网关，GETSSH 不经过任何私有转发服务器。

3. 为什么拒绝「通用 OpenAI 封装」？

大多数客户端接入多模型时，习惯简单套用 OpenAI 的 Chat Completions 接口兼容层。但在深度运维 Agent 场景下，这种"朴素兼容"会直接导致严重的功能降级与阻断：

痛点场景	朴素兼容层表现	GETSSH 深度定制适配层
思维链输出	思考内容与命令混在 `delta.content`，终端满屏混乱	识别 `reasoning_content` / `thought` 独立流，折叠为微光「思考中」看板
工具结果回传	错用 `id` 代替 `call_id`，或丢失加密签名	严格对齐各家关联键（OpenAI `call_id` / Anthropic `signature` / Gemini `thought_signature`）
采样参数收紧	向 Anthropic Claude 或 Kimi 传 `temperature`，直接报 400	针对新模型自动 strip 采样参数，保障 100% 连通率
流式工具碎片	假设入参是完整 JSON，解析报非法字符	维护聚合键 Map，在特定终止事件到达后统一 parse
限流错误识别	将欠费伪 429 当作速率限制无限退避重试	二次判别错误详情（如智谱 `1113`、DeepSeek `402`、Anthropic `billing_error`）并明确告警

4. 统一模型抽象：Typed Block 状态机

为了无损对接多家厂商的异构协议，GETSSH 在内部采用**有序块列表（Ordered Typed Blocks）**而非传统的 {role, content} 字符串：

export type Block =
  | { kind: 'text'; text: string }
  | { kind: 'thought'; text?: string; opaque: string } // opaque 存储未篡改的签名与加密块
  | { kind: 'tool_call'; callId: string; name: string; args: unknown; raw: string }
  | { kind: 'tool_result'; callId: string; content: Block[]; isError?: boolean }
  | { kind: 'image'; mime: string; data: string }
  | { kind: 'server_tool'; toolType: string; payload: unknown; opaque?: string };

export interface Turn {
  role: 'user' | 'assistant';
  blocks: Block[];
}

opaque 签名原封不动回传：无论是 OpenAI 的 encrypted_content、Anthropic 的 signature，还是 Gemini 的 thought_signature，一律作为不透明字符串原样回传，保证多轮会话的推理连贯性。
保留原始入参 raw：多工具并行时碎片交错到达，在收尾事件前绝不进行非法尝试解析。

5. 当前已深度适配的模型

OpenAI (Responses API)

主端点：POST https://api.openai.com/v1/responses。
迁移要点：
- 旧版 Chat Completions 无法同时开启推理与工具调用（reasoning_effort 非 none 时禁止调工具）。GETSSH 全面迁移至 Responses API。
- 函数调用回传时必须使用 call_id（而非 id）。
- 推理强度支持 low / medium / high / xhigh / max。
- 显式下发 store: false，保障运维会话不沉淀在 OpenAI。

Anthropic (Claude)

主端点：POST https://api.anthropic.com/v1/messages，必需头 anthropic-version: 2023-06-01。
迁移要点：
- 采样参数硬约束：新版模型若携带非默认 temperature / top_p / top_k 会直接触发 400 报错。适配层默认不下发该三项。
- Adaptive Thinking：思考过程伴随加密 signature 返回。在回传工具执行结果时，该轮所有的 thinking 与 redacted_thinking 必须完整、原序回传。
- 工具定义使用 input_schema（非 parameters）。

Google Gemini (Interactions API)

主端点：POST https://generativelanguage.googleapis.com/v1beta/interactions（2026-06 起成为默认架构，淘汰 generateContent）。
迁移要点：
- 采用 Steps 架构：包含 model_output、function_call、thought 等步骤。
- 当模型需要执行工具时，响应状态返回 status: "requires_action"。
- 无状态模式下，收到的 thought step 与 thought_signature 必须在后续请求中原样完整重发。

DeepSeek (单模型混合推理)

主端点：https://api.deepseek.com/chat/completions。
迁移要点：
- 混合架构：不再拆分 chat 与 reasoner，通过 thinking: {type: "enabled"} 动态调控。
- 带工具必回传推理：官方明确规定，只要对话中开启了 tools，哪怕该轮模型未实际执行工具，历史轮次的 reasoning_content 也必须全量回传。
- 并发控制与 SSE 保活：适配层基于并发信号量管理，并自动过滤 : keep-alive 注释行防断流。

智谱 GLM (强制推理)

主端点：https://open.bigmodel.cn/api/paas/v4/chat/completions。
迁移要点：
- 鉴权现代化：废除旧版本 JWT 签名，采用标准的 Authorization: Bearer <key>。
- 强制深度推理：不可关闭思考，多轮保留通过 thinking.clear_thinking: false 实现。
- 采样参数值域：temperature 严格限制在 [0.0, 1.0]，超界报 1214；确定性输出通过 do_sample: false 达成。
- tool_choice 仅支持 "auto"：强制调用与指定函数由客户端侧自动校验补足。

月之暗面 Kimi (1M 上下文)

主端点：https://api.moonshot.cn/v1/chat/completions。
迁移要点：
- 采样参数全锁死：temperature、top_p、n、presence_penalty、frequency_penalty 传任何值均报 400。适配层出站前自动剔除。
- 输出字段：采用 max_completion_tokens 代替 max_tokens。
- $web_search 原样回填协议：Kimi 原生联网工具要求客户端不执行实际搜索，只将 arguments 序列化后回传，由云端异步闭环。
- 扁平缓存用量：usage.cached_tokens 为扁平字段，精确计入本地运维成本报表。

通义千问 Qwen (Aliyun DashScope 原生模式)

主端点：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation（流式标头：X-DashScope-SSE: enable）。
迁移要点：
- 坚持原生 DashScope 模式：OpenAI 兼容端点缺失关键的联网搜索引用溯源（search_info），GETSSH 走原生模式提取 server_tool 溯源块。
- 强制开启增量输出：parameters.incremental_output: true 与 result_format: "message" 强制下发；严禁默认的累计全文模式导致的终端文字反复重绘。
- 深度思考与工具互斥规避：enable_thinking: true 模式下，强制指定工具会被拒答，适配层自动将 tool_choice 降级为 "auto"。
- 手写无空格冒号 SSE 解析器：专门过滤 :HTTP_STATUS/200 注释行，并容忍 id:1、event:result 紧凑格式。

MiniMax (双协议与假成功拦截)

主端点：POST https://api.minimax.io/anthropic/v1/messages（备用：/v1/chat/completions）。
迁移要点：
- 默认走 Anthropic 兼容端点：标准 HTTP 状态码，原生返回 thinking 块与加密签名，彻底规避 base_resp 伪 200 状态码陷阱。
- OpenAI 兼容端点强制补丁：若走 /v1/chat/completions，必须显式传递 reasoning_split: true，否则思维链会以内联 <think>...</think> 形式碎片化混入 content。
- 思考开关分流：MiniMax-M3 支持 thinking: { type: "disabled" }；M2.x 系列思考不可关闭，适配层绝不下发非法参数。
- base_resp 故障熔断：深度捕获 1004（鉴权失效）、1005（余额不足欠费），毫秒级告警并阻断无效重试。

6. 内部评测中的模型

🔬 xAI Grok

当前状态：内部协议测试中，预计于 GETSSH 3.2 Fusion Beta Preview 正式推出。

Grok 系列模型（涵盖 Grok 4、Grok 4.6 等前沿版本，xAI 出品）具备极强的实时信息感知与深度长逻辑推理能力，其开放 API 在工具调用路径上展现出相对成熟的设计思路。内部团队目前正在进行以下方向的系统性评测：

多轮工具调用的参数完整性与 call_id 关联一致性。
扩展推理内容（Extended Thinking）的流式分段行为与跨轮回传规范。
BYOK 隐私兼容性：是否存在服务端强制会话留存路径，store: false 等效控制项。
在 GETSSH 运维场景下（跨主机命令编排、日志分析、滚动重启编排等）的多步推理稳定性与失忆概率。

正式发布时将随 3.2 Fusion Beta Preview 版本附带完整协议适配规范与集成文档。

7. 暂不接入的模型与厂商

GETSSH 内部团队持续跟踪市场上的主流及新兴大模型，并在条件成熟时对其进行系统性评测。以下厂商或产品，因当前在Agent 能力成熟度、多轮工具调用稳定性或协议规范化程度等维度上尚不满足 GETSSH 生产级运维场景的准入标准，暂时不在官方适配支持列表中。

这不代表对上述产品技术能力的负面评价。 随着大模型行业的快速演进，准入名单将持续动态调整。

Mistral / Mistral AI

Mistral 的 Agents API 目前处于相对早期阶段，其在多步工具调用链路中的上下文保持稳定性有待进一步验证。语言模型本身在处理中文系统日志、混合语言错误信息与中英夹杂的运维指令集方面存在局限，与 GETSSH 的主要使用场景契合度不足。团队保持关注，后续将视 API 成熟度持续评估。

百度文心一言（ERNIE）

内部团队已对文心 5.0（ERNIE 5.0）进行专项测试。结论是：即便在最新版本下，其在 GETSSH 所定义的复杂 Agent 场景中的表现仍不达标——多轮工具调用的上下文一致性、任务链中断后的自恢复能力均存在明显短板，无法满足生产级运维 Agent 的准入要求。团队将持续跟踪后续版本，但在能力显著突破之前，暂不推出官方适配。

字节跳动豆包（Doubao）

内部评测中，豆包系列模型在运维 Agent 场景下表现出较明显的模型幻觉问题，以及对基础设施相关指令和上下文的偏差输出倾向，这在生产环境中是不可接受的风险点。团队将持续追踪其技术演进，但在幻觉率与输出可靠性达到可接受水位之前，不会推出官方适配。

讯飞星火（iFlytek Spark）

讯飞星火的产品定位是通用对话助手与垂直行业语言应用，其架构设计并非面向 Agent 自动化任务链。在评估中，它在多步骤工具编排、执行状态保持与错误恢复等 Agent 核心能力上的表现与专为 Agent 设计的模型有本质差距。这不是简单的版本迭代可以弥补的方向性问题，暂不在评测队列中。

Meta Llama（本地自托管）

通过 Ollama、vLLM、LM Studio 等方式在本地部署的 Llama 系列模型，可以直接通过 GETSSH 内置的通用 OpenAI 兼容适配器接入使用，无需任何专属配置。官方 Llama API（llama.ai）的工具调用规范目前尚不稳定，暂不推出独立适配层。

其他厂商（Cohere、AI21 Labs 等）

上述国际厂商在 AI Agent / Function Calling 方向的投入相对有限，在复杂运维场景下的专项能力与主流梯队尚有明显差距，暂不纳入评测优先级队列。

关于通用兜底适配：任何符合 OpenAI /v1/chat/completions 规范的本地部署端点（Ollama、vLLM、LM Studio、自建网关等）均可作为自定义端点接入 GETSSH，走通用兼容适配器路径。此路径功能可用，但不享有针对性的思维链分离、参数安全过滤与错误智能分流优化。

8. 流式工具调用聚合表

厂商	聚合分片键	增量字段	收尾事件	解析与触发点
OpenAI Responses	`item_id`	`delta`	`*.done`	用 `.done` 完整数据覆盖
OpenAI CC (Legacy)	`tool_calls[].index`	`function.arguments`	`finish_reason: "tool_calls"`	收流结束整体 parse
Anthropic Messages	block `index`	`delta.partial_json`	`content_block_stop`	`content_block_stop` 触发
Gemini Interactions	step `index`	`delta.arguments`	`step.stop`	`step.stop` 触发
DeepSeek	`tool_calls[].index`	`function.arguments`	`finish_reason: "tool_calls"`	收流结束整体 parse
智谱 GLM	`tool_calls[].index`	`function.arguments`	`finish_reason: "tool_calls"`	收流结束整体 parse
Moonshot Kimi	`tool_calls[].index`	`function.arguments`	`finish_reason: "tool_calls"`	遇第一个 content 时终结思考
通义千问 Qwen	`tool_calls[].index`	`function.arguments`	`choices[0].finish_reason`	专用无空格冒号解析，首个 content 结束思考
MiniMax	block `index` (Anthropic) / `item_id`	`delta`	`message_stop` / `finish_reason`	捕获 base_resp 伪 200，分流 reasoning_split

9. 实施清单与错误分流机制

P0 阻断性红线

推理态保全：严禁在本地剥离或修改 thinking 块与签名。
采样参数出站过滤：针对 Anthropic Claude 与 Kimi，全面 strip 采样参数。
OpenAI 强制路由：推理 + 工具调用时自动走 Responses API。
BYOK 隐私开关：全量请求确保 store: false。

错误智能分流

不可重试的欠费捕获：
- 智谱返回 1113（伪 429 欠费）时直接向用户抛出充值提示，拒绝循环重试；
- DeepSeek 返回 402 Insufficient Balance 时直接熔断；
- Kimi 返回 exceeded_current_quota_error 时终止会话；
- MiniMax 返回 1005 时立即断路，阻断无效重试风暴。
自适应指数退避：仅对真正的速率限流（如 OpenAI rate_limit_error、智谱 1302/1305、DeepSeek 429）进行梯度退避，最大程度保证运维排障链路平稳。

大模型适配与 BYOK 规范

目录