统一 LLM 抽象与流式处理

多模型适配器、统一流式事件词汇表、Token 计量与容灾重试。

DeepSeek Harness 不仅专为 DeepSeek 系列模型（DeepSeek-V3、DeepSeek-R1、DeepSeek-Coder 等）进行了深度调优，还通过 packages/llm/llm 提供了跨 Provider 的统一大模型抽象层。

---

核心文件速查

路径	职责	重要度
packages/llm/llm/src/index.ts	统一 LLM 适配器接口与核心流式类型	⭐⭐⭐
packages/llm/llm-deepseek/src/index.ts	DeepSeek 官方 API 适配器与原生思考流（Reasoning）处理	⭐⭐⭐
packages/llm/token-meter/src/index.ts	Token 消耗精准计量与成本核算	⭐⭐
packages/llm/llm-retry/src/index.ts	智能指数退避、速率限制（429）与容灾重试	⭐⭐

---

统一流式词汇表（Streaming Vocabulary）

不同大模型厂商（DeepSeek、OpenAI、Anthropic、Google、Ollama）在 SSE（Server-Sent Events）流式返回时，格式差异极大。DSH 将所有厂商的流式输出归一化为统一的流事件（Stream Chunk）：

// packages/llm/llm/src/types.ts
export type StreamChunk =
  | { type: 'text-delta'; delta: string }              // 正文文本增量
  | { type: 'reasoning-delta'; delta: string }         // 深度思考/推理增量（DeepSeek-R1 / o1）
  | { type: 'tool-call-delta'; index: number; id?: string; name?: string; args?: string } // 工具调用参数增量
  | { type: 'usage'; inputTokens: number; outputTokens: number; cacheReadTokens?: number } // Token 消耗

DeepSeek 原生思考流（Reasoning Content）

针对 DeepSeek-R1 模型特有的 reasoning_content，llm-deepseek 会将其作为独立的 reasoning-delta 事件分发。前端和 Web GUI 可以将 Agent 的"内心独白"与"最终回答"在界面上做优雅的分栏渲染，而无需污染下游的 Tool Calling 解析流水线。

---

适配器注册与运行时解析

在 DSH 中，LLM 适配器通过 Cordis 服务注册：

// packages/llm/llm-deepseek/src/index.ts
export function apply(ctx: Context, config: DeepSeekConfig) {
  ctx.llm.registerAdapter('deepseek', {
    async *stream(request: LlmRequest): AsyncIterable<StreamChunk> {
      const response = await fetch(`${config.baseUrl}/chat/completions`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${config.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          model: request.model ?? 'deepseek-chat',
          messages: formatMessagesForDeepSeek(request.messages),
          tools: formatToolsForDeepSeek(request.tools),
          stream: true,
        }),
      })

      // 解析 SSE 流并 yield StreamChunk
      yield* parseSseStream(response.body)
    }
  })
}

---

Token 计量与多级缓存优化

packages/llm/token-meter 会在每次请求结束后收集准确的 Token 指标： - Prompt Tokens（输入）； - Completion Tokens（输出）； - Cache Hit Tokens（提示词缓存命中）：针对 DeepSeek 原生支持的 Context Caching 机制，精确统计命中率，为企业级成本核算提供数据支撑。

---

本章思考与自测

1. 思考题：当大模型流式输出一个超长 JSON 格式的工具调用参数时，如果在传输到一半时网络连接中断，DSH 的 LLM 适配器与 Agent Loop 是如何保证状态一致性的？
2. 自测题：DeepSeek-R1 的思考链（Reasoning）在落盘存储时，是作为普通文本保存在 assistant/message 中，还是有独立的字段？为什么？