OpenHuman 模型层迁移到 tinyagents：替换自研 Provider 推理栈的迁移方案解读

本篇技术指南以仓库内历史设计文档 docs/tinyagents-inference-migration-plan.md 为主体，讲解 OpenHuman 如何把约 2.96 万行的自研 inference/provider/ 模型层迁移到 vendored tinyagents crate 原生模型接口之上，涵盖双栈并存的问题动因、模块处置地图、七个待补 crate 缺口、八阶段落地节奏与风险清单。读完你不仅能理解这份"模型层倒置"方案为什么被设计成逐阶段删除而非一次性重写，还能在当前工作区的源码中逐一找到对应的落地证据。

---

文档定位：被取代却仍具参考价值的设计底稿

先说明文档状态。docs/tinyagents-inference-migration-plan.md 在第 1 行起即自述：

Status: superseded on 2026-07-22 by tinyagents-migration-plan-2026-07-22.md. This document is retained as historical model-layer design detail; its pins, status, and present-tense inventory are not current.

也就是说它属于"已被取代的历史设计细节"，其 pin 版本号与"当前态清单"并不代表最新状态；权威的活跃计划在 docs/tinyagents-migration-plan-2026-07-22.md，逐行删除台账在 docs/tinyagents-full-migration-plan/99-deletion-ledger.md，漂移登记在 docs/tinyagents-drift-ledger.md。

但恰恰因为它是模型层迁移最早、最细致的逐模块设计图——包含"能力等价映射表、迁移/留守处置地图、G1–G7 crate 缺口审计、Phase 0–7 退出条件、风险清单"——后续的取代文档也明言保留它作为 "reference detail"（其 disposition 表格与 gap 列表仍是被引用的细节参照）。本文正是以这份设计底稿为骨架展开。

---

一、为什么要迁移：同一份模型语义被维护了两遍

文档的核心论据（第 1 节 "Why"）基于一个不对称事实：Agent 主循环早已跑在 tinyagents 上，每一轮对话都由 run_turn_via_tinyagents_shared 驱动（当前工作区仍能在 src/openhuman/agent/harness/session/turn/graph.rs、src/openhuman/agent/harness/subagent_runner/ops/graph.rs 中检索到该入口）。但它底下的模型层仍是纯自研的：harness 通过 ProviderModel 适配器（src/openhuman/agent/tinyagents/model.rs）去包装 OpenHuman 自己的 Box<dyn Provider> 栈（inference/provider/，约 2.96 万行），而这套栈把 tinyagents 1.7 已经原生提供的能力重复实现了一遍。

文档给出一张完整的能力等价映射表，这是理解迁移范围的关键：

openhuman（inference/provider/ 等）	tinyagents 1.7 等价物
Provider trait、ChatMessage/ChatRequest/ChatResponse/ProviderDelta（traits.rs）	harness::model::{ChatModel, ModelRequest, ModelResponse, ModelStream, ModelStreamItem} + harness::message::*
compatible*.rs（约 15 个文件：OpenAI 兼容客户端、SSE 流式、parse/dump/repeat/timeout）	harness::providers::openai（convert / sse / transport / types）——服务于一切 OpenAI 兼容端点
reliable.rs 重试/退避包装器	harness::retry::{RetryPolicy, FallbackPolicy, RateLimiter, is_retryable}
router.rs RouterProvider hint-table 多模型路由	harness::model::ModelRegistry（按深度解析模型）
model_context.rs 上下文窗口表	MODEL_CONTEXT_PATTERNS 回退 + registry::ModelCatalog（离线快照：窗口、定价、能力标志）
error_classify.rs / error_code.rs（可重试性、HTTP 状态解析）	harness::retry::is_retryable + harness::model::ProviderError
provider 字符串 → provider 构造（factory.rs，部分）	harness::providers::{ProviderKind, ProviderSpec} 工厂（ProviderKind::infer、Compatible）
embeddings 分发（ops.rs → 本地/云）	harness::embeddings traits（+ openai 实现）
provider/openai_codex.rs、openhuman_backend.rs、claude_agent_sdk/	无等价物——留在宿主侧，作为 ChatModel 实现

双栈维护的代价是：每一次修复（流式边界情况、重试策略、上下文窗口条目、provider 怪癖）都要在两个系统里各落地一次；而 ProviderModel + ThinkingForwarder + usage 携带管道这套适配缝，存在的唯一理由就是把两套同构的类型系统翻译来翻译去。文档强调关键前提：vendor/tinyagents 是组织自己的 crate（同为 GPL-3.0 许可、同组织），所以与宿主无关的通用缺口可以上游合入 crate，只有真正 OpenHuman 专属的胶水才留在宿主。

终点状态（end state）三句话即可概括：

• crate 的 ChatModel/ModelRequest 成为 OpenHuman 全项目的原生模型接口；
• inference/ 只保留宿主关切（RPC 表面、配置、本地运行时管理、voice、OAuth、/v1 端点）；
• ProviderModel 与整套 Provider trait 栈被删除。

影响半径（Blast radius）

文档给出了精确的波及统计，用于说明"为什么不能一把梭"：

• inference/ 之外有 170 个文件 import openhuman::inference，其中 151 个 import inference::provider；主要消费方是 agent harness/session/tools/triage、context、voice、routing、memory_tree、learning、channels、embeddings、subconscious、threads、migrations、config/schema。
• 模块体量：provider/ 约 2.96 万行，local/ 约 1.37 万行，voice/+http/+openai_oauth/ 约 4.4k 行，根文件约 5.5k 行。真正需要迁移的只有 provider/ 和根文件的一部分，其余保持不变。

---

二、处置地图：谁迁移、谁留在宿主

第 2 节给出了逐文件的 disposition map，分两大阵营。

迁移部分（被 crate 替换，或上游进 crate）

组件	去向	备注
provider/traits.rs——Provider trait + 请求/响应/delta 类型	删除，改用 crate ChatModel + message 类型	最大的倒置点（Phase 1）。UsageInfo → crate Usage（见缺口 G1 关于 USD/缓存 token 的问题）
provider/compatible*.rs——OpenAI 兼容客户端	删除，改用 crate providers::openai	先做缺口审计（Phase 2）：请求 dump 调试、重复检测、per-request 超时、BYOK 认证风格
provider/reliable.rs	删除，改用 crate RetryPolicy（+ FallbackPolicy）	顺带解决已知的双重重试问题（今天 reliable.rs 和 harness 层重试会各触发一次）
provider/router.rs（RouterProvider）	删除，改用 crate ModelRegistry	hint 表（reasoning-v1、agentic-v1、…）变成 registry 别名
model_context.rs（context_window_for_model）	把条目上游进 crate ModelCatalog 快照 / MODEL_CONTEXT_PATTERNS；宿主保留薄查找层，优先配置覆盖	crate 目录还带定价 + 能力标志——喂给成本追踪器
provider/error_classify.rs、error_code.rs	删除，改用 crate is_retryable / ProviderError	crate 遗漏的状态分类上游补齐
provider/temperature.rs（@<temp> 后缀）	宿主在工厂里解析后缀，值随 ModelRequest 参数走	文法保留在宿主侧，管道类型消失
provider/config_rejection.rs、billing_error.rs	拆分：通用分类上游为 crate 错误种类；OpenHuman 语义（Sentry 降级、预算提示）作为基于 TinyAgentsError 的宿主分类器保留
provider/factory.rs	收缩但保留：解析 OpenHuman provider 字符串（openhuman、cloud、ollama:<model>、<slug>:<model>[@temp]）+ 配置 + 凭据 → crate ProviderSpec/Arc<dyn ChatModel>	迁移完成后这是宿主↔crate 的边界。BYOK_INCOMPLETE_SENTINEL 保留
provider/ops.rs（list_configured_models、SessionExpired 发布）	保留，重定向到 crate 类型	SessionExpired 需要 crate 客户端给出认证失败信号（缺口 G3）
embeddings 分发	crate harness::embeddings traits（tinyagents/embeddings.rs 缝已存在——补完它）	本地（Ollama）embedding 作为 crate trait 的宿主实现保留
provider/thread_context.rs、resolved_route.rs、auth_error_registry.rs	重新安置到 src/openhuman/agent/tinyagents/（它们是缝关切，不是 provider 关切）	thread_context task-locals 已被 model.rs 消费

留在 inference/（宿主关切，crate 范围外）

文档明确下列内容"不迁移"：

• RPC 表面：schemas.rs、ops.rs、local/schemas.rs——所有 inference.* 控制器与 legacy 别名；
• 本地运行时管理（local/）：Ollama/LM Studio 探测/拉起/收养、Whisper/Piper 安装、下载进度、模型产物、context floor。其中面向 Ollama/LM Studio 的 chat 客户端迁到 crate ProviderKind::Ollama/Compatible，进程生命周期留在宿主；
• voice/：STT/TTS 推理实现（whisper-cpp 绑定、Piper）——不是 LLM 形状的，保持不变；
• openai_oauth/：Codex OAuth PKCE + 加密 token 存储（凭据域集成）；
• http/：/v1/chat/completions 的 OpenAI 兼容服务端端点（后续可选：crate 1.3+ 提供 OpenAI 兼容的运行时模型列表，Phase 5 后再评估）；
• device.rs、presets.rs、model_ids.rs、paths.rs、parse.rs：硬件档案、预设档位、由配置推导 model-id、产物路径；
• sentiment.rs：作为宿主 op 保留，但其模型调用在 Phase 6 改写为 ChatModel（+ crate 结构化输出）；
• 定制 provider（openhuman_backend.rs 会话 JWT 托管后端、claude_agent_sdk/ 子进程、openai_codex.rs OAuth-token 兼容变体）：留在仓库内，在 Phase 4 重写为 crate ChatModel 实现。

---

三、先补齐的 crate 缺口：G1–G7

因为删除要在"功能不丢"的前提下进行，文档第 3 节对 tinyagents 1.7.1 源码做了核对，列出必须先在本体仓库内补齐（上游工作，位于 vendor/tinyagents）的七个缺口。文档特别注明"crate 迭代快，Phase 0 时要重新审计"。

• G1 — Usage 保真度：crate Usage 没有 charged_amount_usd，且需核实 cache-read/cache-write token 字段。文档以 "$0 成本回合 bug" 为例说明失真会破坏什么（该 bug 当时靠宿主侧 cost::catalog::estimate_cost_usd 修复）。出路二选一：把可选的 cost/cached 字段上游到 Usage，或继续宿主侧基于 crate ModelCatalog 定价做估算。
• G2 — 工具调用开始元数据：crate ToolDelta 带 call_id/content 但没有 tool_name；UI 时间线的 tool-start 事件仍由 model.rs forwarder 带外转发。把 tool_name 上游到首个 ToolDelta（或专门的 start item），forwarder 才能随 ProviderModel 一起消亡。
• G3 — 认证失败信号：OpenHuman 在聊天认证失败时会发布 DomainEvent::SessionExpired。crate 客户端必须把 401/过期区分为独立的 ProviderError 种类，宿主工厂才能不靠字符串嗅探挂上钩子。
• G4 — 请求 dump / 线上可观测性：compatible_dump.rs 负责写原始请求/响应 dump 供调试。删除前要上游一个传输层钩子（或确认 crate 的 observability exporters 已覆盖）。
• G5 — 每请求超时策略：compatible_timeout.rs 的语义与 crate 传输暴露的差异。若缺失，在 ModelRequest/ProviderSpec 上上游一个 per-call 超时。
• G6 — BYOK 认证风格：权威 provider 目录（src/openhuman/config/schema/cloud_providers.rs）支持多种 AuthStyle（headers 等）。确认 crate ProviderSpec 能表达目录里每一种风格，缺什么上游什么。
• G7 — 重复输出守卫：compatible_repeat.rs（退化重复检测）。二选一：上游为可选 stream guard，或接受损失（文档注明 #4463 已在追踪被删除的 repeat guards）。

上游流程也有明确纪律：改动在 vendor/tinyagents（submodule 工作树）→ PR 到 tinyhumansai/tinyagents → 发布 → 同时在两个 Cargo 世界（根 + app/src-tauri）bump crates.io pin，并同步推进 submodule ref。任何 merge 点都不允许 OpenHuman 依赖未发布的 vendored-only API。

---

四、八阶段推进计划（Phase 0–7）

文档第 4 节给出分阶段执行节奏。每阶段都要满足三条纪律：两个 Cargo 世界均编译通过、保持 ≥80% diff 覆盖率、以独立 PR 大小的切片落地；并且 provider 字符串文法、RPC 名称、可观察 UI 行为（流式、成本 footer、工具时间线）全程 parity 锁定。

Phase 0 —— 盘点与缺口再审计

• 枚举 inference/ 之外每一个 Provider/ChatRequest/ChatResponse/ChatMessage 消费方（151 个文件），分桶为：(a) 已走缝、(b) 直接一次性 provider.chat(...) 调用方（learning、memory、subconscious、sentiment、triage…）、(c) 仅类型导入。
• 对照最新 crate HEAD 重验 §3 缺口；提 crate issue；更新 vendor/tinyagents/docs/sdk-gaps.md。
• 黄金转录采集：在现行栈上对 BYOK 目录矩阵 + Ollama + OpenHuman backend 记录请求/响应 wire dumps，作为 Phase 2 parity 的 fixtures。

退出条件： disposition 表逐文件确认；crate 缺口 PR 全部提交。

Phase 1 —— 模型层倒置（关键转折点）

• 在 factory.rs 中引入 create_chat_model(...) -> Arc<dyn ChatModel>，与 create_chat_provider 并存，初期经由 ProviderModel 包装现有栈（零行为变化）。
• 消费方按桶从 Box<dyn Provider> 迁到 Arc<dyn ChatModel>：先一次性调用方（只用一次 chat()，机械替换：ChatRequest → ModelRequest::new(...)），再是缝（run_turn_via_tinyagents_shared 直接接收 model——删除调用点的包装），最后是流式消费方。
• 仅当某消费方无法在一个切片内迁移时，保留临时反向适配器（ChatModel → Provider）；阶段退出前删除它。

退出条件： inference/provider/ 之外没有任何调用方再指名 Provider trait；ProviderModel 只在工厂一处被构造。

Phase 2 —— OpenAI 兼容客户端替换

• 在工厂背后，用 crate providers::openai 客户端（经 ProviderSpec）替代 CompatibleProvider 构建：BYOK slugs、Ollama、LM Studio、cloud slug。
• 对照 Phase 0 黄金 dump 做 parity 测试：请求形状（tools JSON、temperature、多模态块）、SSE 流式（文本、reasoning、tool-arg delta）、usage 提取、错误映射。文档提示近期回归面：tool-calling 默认改为 JSON + P-Format opt-in（提交 9b84f9684）——crate 路径必须遵循同一默认值。
• 所有构造点切换后删除 compatible*.rs（15 个文件，2.96 万行的主体）。

退出条件： 无 compatible*.rs 残留；wire parity fixtures 全绿；pnpm test:rust + json_rpc_e2e 通过。

Phase 3 —— 可靠性、路由、模型元数据

• 用 crate RetryPolicy（客户端层）替换 ReliableProvider 分层（P1 parity 修复时 session/builder/factory.rs 曾重分层）；审计并移除双重重试。
• 用 ModelRegistry 替换 RouterProvider：抽象档位名（reasoning-v1、coding-v1、…）变成按调用解析的 registry 条目；provider_for_role/workload 解析改为喂 registry，而非构建 router provider。
• 把 OpenHuman 上下文窗口表条目上游进 crate ModelCatalog 快照；context_window_for_model 变成宿主 shim：配置覆盖 → 目录 → crate 模式回退。把目录定价接入 cost::catalog（替换或 seed 手写费率表）。

退出条件： reliable.rs、router.rs、model_context.rs 删除；重试按设计每层恰好一次。

Phase 4 —— 定制 provider 改写为 ChatModel 实现

• 把 openhuman_backend.rs（托管后端、会话 JWT + 经 G3 发布 SessionExpired）、openai_codex.rs（基于 crate openai 客户端的 Codex OAuth token 源）、claude_agent_sdk/（子进程协议）改写为各自驻地的直接 ChatModel 实现。
• 本地运行时：local/ 保留进程生命周期；其 chat/vision/embed 入口调用指向本地 base URL 的 crate 客户端。

退出条件： Provider trait 有零个实现 → 删除 traits.rs 与 trait 本身。

Phase 5 —— 缝收缩

• 删除 ProviderModel、ThinkingForwarder 残余、ProviderUsageCarry 以及 tinyagents/convert.rs 里的 ChatMessage↔crate-message 转换层（harness 现在原生接收 crate 类型）。
• 把 thread_context.rs/resolved_route.rs/auth_error_registry.rs 重新安置到 src/openhuman/agent/tinyagents/。
• inference/provider/ 收窄为：factory.rs（字符串文法 → ChatModel）、定制实现、宿主错误分类器、ops.rs、schemas.rs。

退出条件： src/openhuman/agent/tinyagents/model.rs 删除；adapter 清单测试更新。

Phase 6 —— 一次性推理 op 全部落到 crate

• sentiment.rs、should_react、summarize、视觉提示、triage 式单次调用：改写为 ChatModel + crate 结构化输出（harness/structured），不再用手工 parse（parse.rs 收缩或死亡）。
• Embeddings：补完 tinyagents/embeddings.rs——云走 crate openai embeddings，本地作为 crate trait 的宿主实现；LocalAiEmbeddingResult 由 crate 类型映射。

退出条件： crate 表面之外不再有临时的 prompt/parse 循环。

Phase 7 —— 清理、文档、删除台账

• 更新 inference/README.md、gitbooks/developing/architecture/agent-harness.md、权威 provider 目录 src/openhuman/config/schema/cloud_providers.rs；把删除项登记进 docs/tinyagents-full-migration-plan/99-deletion-ledger.md；刷新 docs/tinyagents-drift-ledger.md。
• 移除 inference/mod.rs 的死再导出；只在已有后续 PR 的情况下保留临时 pub use shim。
• 清扫仍在指名 Provider/CompatibleProvider 的陈旧 doc 注释。

---

五、风险与坑（第 5 节要点）

• 线格式回归是静默的，直到某个 provider 出问题才暴露：兼容客户端编码了多年积累的怪癖处理（SSE 边界情况、畸形 tool-arg 片段、省略 usage 的 provider）。缓解：Phase 0 黄金 dump + 按 env key 门控的逐 provider 真实冒烟测试，在每次删除前对真实 BYOK 矩阵运行。
• 成本核算：event bridge + record_unobserved_turn_usage 回退是来之不易的（$0 回合 bug）。任何 Usage 形状变化都必须让 cached-token 与 USD 流端到端保持完整（dashboard + footer）。
• 流式 UI parity：tool-start 事件（G2）与事后 reasoning 仍走带外 forwarder；在 crate 缺口补齐前删除它会打断工具时间线。
• 两个 Cargo 世界：根与 app/src-tauri 各自 pin tinyagents——每次 crate 升级都要落在两个 lockfile + submodule ref，同一提交。
• vendored-crate 纪律：path patch 意味着本地 vendor 编辑会静默生效；CI 与其他 clone 需要 submodule 在匹配的 ref 上。永远不要 merge 依赖未发布 crate API 的 OpenHuman 代码。
• Sentry 噪音契约：ops.rs 刻意把 provider/用户配置失败降级为 warn!。新的基于 TinyAgentsError 的宿主分类器必须保持 expected_error_kind 行为，否则 Sentry 会告警刷屏。
• 测试串行化：一切都在 inference_test_guard()（覆盖运行时单例 + 配置的进程级互斥锁）下运行；新测试也必须如此。
• 同一区域的既有回归（#4451–#4469，尤其 #4460 流式调用丢失 thread_id task-locals、#4463 repeat guards）：协调迁移不重踩/不掩盖这些修复；thread-context task-locals 在 Phase 5 迁移——验证 #4460 的修复能挺过 re-home。
• /v1 服务端端点用 provider 类型做其请求/响应 DTO（http/types.rs）——内部切到 crate 类型的同时，对外 wire 形状必须保持不变。

---

六、明确非目标（第 6 节）

• 不改变 inference.* RPC 表面、provider 字符串文法，以及 Settings > AI 预设目录 UX。
• 不迁移 local/ 进程管理、voice/ STT/TTS 引擎、openai_oauth/ 流程、device/presets/paths——它们在 crate 的意义上不是 LLM 驱动的。
• 不改动 sub-agent 执行（harness 迁移的 P5 已经拒绝了 crate SubAgentTool）。

---

七、当前工作区里的落地证据

把文档的设计与当前工作区对照，可以发现这个计划大体上已经按设计执行（这与取代文档 docs/tinyagents-migration-plan-2026-07-22.md 所称"迁移远比任何现存文档记录的都超前"互相印证）。以下是能在源码里直接看到的关键证据：

• Provider trait 已消失：src/openhuman/inference/provider/ 目录中已不存在 traits.rs、reliable.rs、router.rs、legacy_provider.rs 或任何 compatible*.rs 文件，整个 src/openhuman 下也搜不到 pub trait Provider 的定义。
• 工厂已成为宿主↔crate 边界：src/openhuman/inference/provider/mod.rs 再导出的已是 create_chat_model、create_chat_model_from_string、create_chat_model_from_string_with_model_id 等构造入口；src/openhuman/inference/provider/factory_part_01.rs 中 create_chat_model 返回 Arc<dyn ChatModel<()>>，完全对应文档 Phase 1 设想的形态。文档计划中"保留"的元素仍在：OLLAMA_PROVIDER_PREFIX（"ollama:<model>"，factory_part_01.rs L17–L18）、@temp 温度后缀解析（split_model_and_temperature，L142）、BYOK_INCOMPLETE_SENTINEL（L36）。
• crate 原生客户端已就位：src/openhuman/inference/provider/crate_openai.rs 的 build_crate_openai_model 返回 Arc<dyn ChatModel<()>>，即文档所言的 crate_openai 构造路径；托管后端也有了 crate 原生形态 openhuman_backend_model.rs（mod.rs L22–23 注明 "issue #4727"）。
• 适配缝仍在但形态已变：src/openhuman/agent/tinyagents/model.rs 直接 import tinyinference::model::{ChatModel, ModelRequest, ModelResponse, ModelStream, ModelStreamItem} 与 tinyinference::message、tinyinference::tool::ToolDelta、tinyinference::usage::Usage——注意这里展示了一个比原文档更新的演化：tinyagents 后来被拆分成了更细的 crate 工作区（Cargo.toml 依赖 tinyagents-harness/tinyagents-graph/tinyagents-language/tinyagents-registry/tinyagents-session 等工作区成员），模型层类型经 tinyinference 导出，而 OpenHuman 侧的 ChatMessage 现在被视作持久化/线程记录而非请求类型，正对应取代文档 §4.3 的判断。
• host 关切原样保留：inference/provider/ 下仍有 claude_agent_sdk/、claude_code/、openai_codex.rs、ops/、schemas.rs 等"留守"内容，以及宿主侧错误语义文件 error_classify.rs、error_code.rs、config_rejection.rs、billing_error.rs、auth.rs。

这些证据共同说明：文档提出的方向（crate 原生类型成为唯一模型接口）、方法（逐桶迁移 + 临时反向适配器 + wire parity 门禁）与边界划分（宿主/通用二分法）经受住了后续执行的检验，而具体的文件粒度与版本 pin 则以取代文档与 docs/tinyagents-full-migration-plan/99-deletion-ledger.md 为准。

---

相关文档链

• docs/tinyagents-migration-plan-2026-07-22.md —— 取代本文档的现行审计与合并计划（WP-0–WP-6）
• docs/tinyagents-full-migration-plan/99-deletion-ledger.md —— 删除台账
• docs/tinyagents-drift-ledger.md —— 行级漂移登记（pin 锚点在 §Anchors）
• docs/tinyagents-tool-model-decision-2026-07-23.md —— 工具模型决策（WP-4 依赖它）
• 宿主↔crate 边界源码：src/openhuman/inference/provider/mod.rs、src/openhuman/inference/provider/factory_part_01.rs、src/openhuman/agent/tinyagents/model.rs
• 验证与运行入口：tests/inference_provider_e2e.rs（wire-parity 门禁）、scripts/test-rust-with-mock.sh（全量 Rust 套件）、src/openhuman/inference/README.md（迁移后需同步的宿主文档）

阅读建议：若你关心"当前该改什么"，请以取代文档和删除台账为准；若你想理解"模型层倒置为什么必须分八步、哪些功能细节（Usage 保真、tool-start 元数据、BYOK 认证风格、重复输出守卫）在类型迁移中最容易被静默破坏"，则本文档仍是全仓库最完整的单点参考。