Model API 三种协议
能力、细节与 Harness 选型

Pi、pi-ai、DSH：谁是谁

先把最常见的误解拆掉：dsh-llm-pi-ai 不是 Pi harness，也不是“DSH 内置了 Pi”。它只是 DSH 的一个 adapter，把 pi-ai 这个多 provider LLM 库接进 DSH 的 dsh-llm seam。

证据：DSH 的 packages/llm/llm-pi-ai/package.json 只声明 @earendil-works/pi-ai，没有 pi-coding-agent 或 pi-agent-core；其 description 明确写的是 “design-verification twin of dsh-llm-deepseek”。

一次请求的数据交互流程

DSH 的请求不是“把 messages 直接丢给 pi-ai”。中间有 provider-neutral 预处理、能力校验、凭据解析、图片投影、Context 转换、事件回译和 replay 存储。

图中的 5–8 步是 dsh-llm-pi-ai 的路径；dsh-llm-deepseek 走 DeepSeek Messages，不经过 toPiContext/toStreamChunks，但共享同一个 dsh-llm seam 和 StreamChunk 契约。

7.2.1 入口：GenerateOptions

Agent loop 从 session 里取出历史，构造“模型将看到的精确输入”。DSH 的 GenerateOptions 同时包含请求身份、消息、工具和采样控制：

interface GenerateOptions {
  provider: string
  model: string
  reasoningEffort?: ReasoningEffortId
  messages: RequestMessage[]       // system / developer / user / assistant / tool
  system?: string                  // one-shot 调用
  tools?: ToolSchema[]
  toolHistory?: ToolHistory
  temperature?: number
  maxTokens?: number
  stop?: string[]
  sessionId?: SessionId
  purpose?: 'compaction' | 'session-title'
  signal?: AbortSignal
}

messages 里的内容块是 DSH 的 canonical ContentBlock：text、reasoning、image、file、tool-call、tool-addition、tool-removal。这份输入会被 deep-freeze，adapter 只读。

7.2.2 LlmRuntime：provider-neutral 预处理

在进入 adapter 前，LlmRuntime.adapterStream() 做四类统一处理：

• 文件投影：file block 永远不直接发给 provider，转成带路径/大小的文本句柄；
• 图片投影：不支持图片的模型，图片变成文本占位符；支持图片的模型才进入 attachment 解析；
• 工具更新投影：按模型的 toolUpdate 能力选择 in-history / addition-only / 完整列表；
• Replay 隔离：如果历史 assistant 的 source.provider 不是当前 adapter 拥有的 provider，就剥掉 replayState，避免跨 adapter 使用 provider 签名。

这一步是 DSH 的“provider-neutral 边界”：所有 provider 看到的输入先被规范化，但 reasoning/cache 等 provider 语义不被强行翻译。

7.2.3 PiAiAdapter：解析 snapshot、模型、凭据

每个请求会取当前 profiles 的不可变 snapshot（profiles + pi-ai Models collection）。配置变更会构建新 snapshot，不会修改飞行中的请求；这样 prepareCall() 冻结的配置能一直保持到 dispatch。

// 简化自 adapter.ts
const profile = snapshot.profiles.get(options.provider)
const model = snapshot.models.getModel(options.provider, options.model)
const reasoning = resolveReasoningLevel(model, options.reasoningEffort ?? profile.reasoning)
const apiKey = await this.config.resolveApiKey(options.provider, profile)
const events = snapshot.models.streamSimple(model, context, {
  apiKey,
  reasoning,
  ...options.temperature !== undefined ? { temperature: options.temperature } : {},
  ...options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {},
  ...options.sessionId !== undefined ? { sessionId: String(options.sessionId) } : {},
  signal: watchdog.signal,
  headers,
  maxRetries: 0, // 重试归 DSH
})

凭据解析是“fail loud”的：如果 profile 明确写了 apiKeyEnv，解析不到就抛 MISSING_CREDENTIAL，不会让 pi-ai 去捡一个不相关的 OPENAI_API_KEY。只有完全没配凭据的 route 才交给 pi-ai 的 provider-native ambient auth / OAuth store。

7.2.4 toPiContext：DSH Message → pi-ai Context

toPiContext() 把 DSH 的 role/content 结构翻译成 pi-ai 的 Context：

• 请求级 system + 开头连续的 system 历史 → Context.systemPrompt；
• 其余 system / developer / assistant / tool / user → pi-ai messages；
• tool-call → pi-ai toolCall（arguments 从 DSH 的原始 JSON 字符串解析成对象）；
• tool → pi-ai toolResult，toolName 从前一条 assistant 的 tool call 建立 id→name 映射补上；
• developer 的 tool-addition/tool-removal → pi-ai system 的 toolsAdded/toolsRemoved（或模型不支持时降级）；
• 图片 → pi-ai ImageContent；文件永远只以文本句柄出现。

7.2.5 pi-ai provider：原生 wire

models.streamSimple() 是 pi-ai 的统一简化入口。它内部按模型的 api 选择协议实现：anthropic-messages、openai-responses、openai-completions、google-generative-ai、bedrock-converse-stream 等。协议差异由 pi-ai 的 provider 层处理，DSH 只看到统一的 AssistantMessageEvent。

7.2.6 toStreamChunks：事件回译

// 简化映射
text_start      → { type: 'block-start', blockType: 'text' }
text_delta      → { type: 'text-delta', text }
thinking_start  → { type: 'block-start', blockType: 'reasoning' }
thinking_delta  → { type: 'reasoning-delta', text }
toolcall_start  → { type: 'block-start', blockType: 'tool-call' }
toolcall_delta  → { type: 'tool-call-delta', argumentsDelta }
toolcall_end    → { type: 'block-end', block: { type:'tool-call', arguments: JSON.stringify(...) } }
done            → { type: 'usage' } + { type: 'finish', replayState }
error           → { type: 'usage' } + { type: 'finish', reason: error/aborted }

这里有一个重要方向差异：pi-ai 的 tool arguments 是已解析对象，DSH 的 tool-call 保留原始 JSON 字符串。所以 toolcall_end 会重新 JSON.stringify；参数非法时 DSH 会报 MALFORMED_RESPONSE（除非是 length 截断）。

7.2.7 回到 DSH：BlockAssembler 与 Replay

BlockAssembler 把 StreamChunk 拼成 DSH 的 content blocks；finish.replayState 被存进 assistant message 的 source.replayState。下一次请求只有在同一个 adapter 实例同时拥有历史 provider 和目标 provider 时，才会把 replay state 传给 adapter；否则剥离并降级为 provider-neutral 历史。

核心数据对象

DSH 和 pi-ai 各有一套完整的类型系统。理解 adapter 的关键，是看清两边的对象如何一一对应，以及哪些字段是“语义损失点”。

对象映射表

最容易踩的四个转换点

Replay：保留 provider 原生签名

DSH 的 durable 内容（text / reasoning / tool-call）是 source of truth；pi-ai 的 replay metadata 只负责恢复“原生保真度”，不是重新存一份 assistant message。

Replay envelope 有两半：

• response：api、provider、model、responseId、responseModel、providerThinkingLevel、stopReason；
• blocks：逐块的 textSignature、thinkingSignature、redacted、toolCall.thoughtSignature、namespace。

这也解释了 DSH 为什么不把“所有 provider 都归一化成 Chat Completions”：一旦归一化，thinking signature / responseId / thoughtSignature 就没有地方存，长时程工具循环的质量会下降。

DSH 选 pi-ai 的因素

这一节把“仓库明说的”与“我基于代码结构的推断”分开。前者可以在 DSH 的 README、Agent Note、源码注释里找到；后者是工程判断，不是官方声明。

7.5.1 仓库/代码明确说到的

7.5.2 我的推断（未在仓库中直接写死）

1. TS/Node 同栈、in-process：DSH 是 TS 插件系统；pi-ai 是 TS 库，可以直接进进程，不需要像 LiteLLM 那样额外跑 Python 服务。对桌面/CLI/本地优先的 harness，这是决定性因素。
2. 覆盖成本：要自己接 OpenAI、Anthropic、Google、Bedrock、Vertex、OpenRouter、Groq、Cerebras、xAI、Copilot 等几十家 provider，认证/OAuth/模型目录/流事件都要维护；pi-ai 已经把这些做成 catalog。
3. 原生协议保真：DSH 的差异化是“provider-neutral 但不丢 provider 语义”；pi-ai 保留 native protocol 和 provider metadata，比 Chat 归一化网关更贴合 DSH 的 replay 设计。
4. 插件化快照语义：DSH 的 prepareCall() 要冻结一次调用的 adapter generation；pi-ai 的 Models collection 可以整体替换，adapter 用不可变 snapshot 包住，正好匹配。
5. 不需要网关能力：DSH 不需要中心化 key、LB、guardrails、团队配额；这些是 LiteLLM/Portkey/Bifrost 的强项，但对本地 harness 是额外服务。DSH 自己已经有 credential seam、retry、session、审批。
6. 生态/许可证：pi-ai 是 MIT，Pi harness 自己 dogfood；DSH 可以读源码、打小 patch，不需要引入商业网关。

7.5.3 代价与风险

同类框架：pi-ai 在哪个位置

pi-ai 既不是 LiteLLM Proxy，也不是 OpenRouter，更不是 LangChain。先把“库 / 网关 / 托管 / agent 框架”分开，再比较会清楚很多。

7.6.1 四类形态

7.6.2 横向对比

7.6.3 三个关键对比

7.6.4 决策矩阵

DSH × pi-ai 的结论

1. DSH 的 pi-ai adapter 是“模型接入层”，不是 Pi harness，也不是网关。它把 pi-ai 的 provider/catalog/auth/native stream 接进 DSH 的 dsh-llm，DSH 自己保留 agent loop、工具、session、审批、重试。
2. 数据流是“双向翻译 + 原生保真”：DSH Message → pi-ai Context → provider wire → pi-ai events → DSH StreamChunk；assistant 的原生签名/ID 通过 ReplayEnvelope 存回 DSH，下一轮再恢复。
3. 选 pi-ai 的核心因素：TS 同栈、in-process、provider 覆盖、OAuth/模型目录、原生协议保真、MIT、可打 patch；以及“twin adapter”用两套实现验证 provider-neutral 契约。
4. 不选 LiteLLM/OpenRouter/Portkey/Bifrost 的核心原因：它们是网关/服务，不是库；对本地优先的 DSH 来说多一跳、多一套运维，而且 Chat 归一化会丢 reasoning/cache 语义。
5. 代价：上游依赖/patch、错误 cause 丢失导致文本分类、catalog 漂移、没有网关级路由/LB；这些由 DSH 自己的 retry/credential/session 层补位。

来源

• DSHDeepSeek Harness
• DSHdsh-llm-pi-ai README
• DSHdsh-llm README
• DSHadapter.ts · context.ts
• DSHstream.ts · replay.ts
• DSHllm-pi-ai package.json（依赖只有 pi-ai，不含 pi-coding-agent）
• DSHTwin LLM adapters
• DSHNarrow pi-ai imports
• DSHSystem-reminder fallback
• PIPi harness
• PIpi-ai package
• PIpi-ai README
• COMPARELiteLLM
• COMPAREVercel AI SDK
• COMPAREOpenRouter
• COMPAREPortkey Gateway
• COMPAREBifrost
• COMPARETensorZero
• COMPAREaisuite
• COMPAREany-llm

版本提示：DSH 仍是开发预览；本文按当前安装的 @deepseek-ai/dsh 0.2.1-rc.2 与 @earendil-works/pi-ai 1.4.0 的包文档/代码核对。框架对比中的“模型数量/性能”含厂商自述，生产前请按锁定版本复核。