第5章：模型抽象与 Provider 矩阵 —— 端侧多模型 Seam

// crates/language_model/src/language_model.rs 核心接口提炼
pub trait LanguageModel: 'static + Send + Sync {
    fn id(&self) -> &LanguageModelId;
    fn name(&self) -> &LanguageModelName;
    fn provider_id(&self) -> &LanguageModelProviderId;
    fn telemetry_id(&self) -> String;

    /// 模型上下文窗口总上限（如 200,000）
    fn max_token_count(&self) -> usize;

    /// 单次请求允许的最大输出 Token 数
    fn max_output_tokens(&self) -> Option<usize>;

    /// 是否支持多模态图像输入
    fn supports_images(&self) -> bool { false }

    /// 是否支持强制指定 tool_choice
    fn supports_tool_choice(&self) -> bool { true }

    /// 发起流式生成的唯一核心入口
    fn stream_completion(
        &self,
        request: LanguageModelRequest,
        cx: &AsyncApp,
    ) -> BoxFuture<'static, Result<BoxStream<'static, Result<LanguageModelCompletionEvent>>>>;

    /// 拒答回退模型的配置 ID
    fn refusal_fallback_model_id(&self) -> Option<LanguageModelId> { None }
}

pub trait LanguageModelProvider: 'static + Send + Sync {
    fn id(&self) -> LanguageModelProviderId;
    fn name(&self) -> SharedString;
    fn icon(&self) -> IconOrSvg;

    /// 认证流程（异步拉取 OAuth 或读取已保存的 API Key）
    fn authenticate(&self, cx: &mut App) -> Task<Result<()>>;
    fn is_authenticated(&self, cx: &App) -> bool;

    /// 获取可用模型清单（支持向远程网关实时拉取）
    fn list_models(&self, cx: &App) -> Vec<Arc<dyn LanguageModel>>;
    fn default_model(&self, cx: &App) -> Option<Arc<dyn LanguageModel>>;
}

pub enum LanguageModelCompletionEvent {
    Start,
    Text(String),
    Thought(String), // 思考链片段
    ToolUse(LanguageModelToolUse),
    ToolUseChunk {
        index: usize,
        id: Option<String>,
        name: Option<String>,
        arguments_chunk: String,
    },
    Stop(StopReason),
}

// crates/agent/src/tools.rs:35-58
/// 某些本地小模型或特定网关偶尔会将工具参数以 JSON-encoded string
/// 而非结构化对象的形式传回，此函数无缝兼容两种形态！
pub(crate) fn deserialize_maybe_stringified<'de, T, D>(deserializer: D) -> Result<T, D::Error>
where
    T: DeserializeOwned,
    D: Deserializer<'de>,
{
    let raw_value = serde_json::Value::deserialize(deserializer)?;
    match T::deserialize(&raw_value) {
        Ok(value) => Ok(value),
        Err(original_error) => {
            // 如果原本期望的是 Object，但模型错误地传成了转义后的 String，尝试二次反序列化
            let Some(string) = raw_value.as_str() else {
                return Err(original_error);
            };
            serde_json::from_str(string).map_err(serde::de::Error::custom)
        }
    }
}

// crates/agent/src/thread.rs:2945-2970 拒答捕获逻辑
if let Some(err) = batch_result.1 {
    let is_refusal = err
        .downcast_ref::<CompletionError>()
        .is_some_and(|e| matches!(e, CompletionError::Refusal));
    if is_refusal {
        log::info!("Model refused request; checking for fallback model");
        had_refusal = true;
        break; // 跳出内层循环，进入外层回退流程
    }
}

// crates/agent/src/thread.rs:2988-3015
if had_refusal {
    let maybe_fallback = this.update(cx, |this, cx| -> Option<Arc<dyn LanguageModel>> {
        let current_model = refusal_fallback_model.as_ref().or(this.model())?;
        // 查询当前模型是否配置了回退候选者
        let fallback_id = current_model.refusal_fallback_model_id()?;
        let registry = LanguageModelRegistry::read_global(cx);
        registry.create_model(&fallback_id)
    })?;

    if let Some(fallback_model) = maybe_fallback {
        log::info!(
            "Switching to refusal fallback model: {}",
            fallback_model.name().0
        );
        refusal_fallback_model = Some(fallback_model);
        // 带着完全相同的 Prompt 与历史上下文，立刻用新模型重试！
        continue;
    }
}

// crates/language_model/src/fake_provider.rs 核心机制
pub struct FakeLanguageModel {
    id: LanguageModelId,
    // 预编排的响应队列
    responses: Arc<Mutex<VecDeque<FakeCompletion>>>,
}

pub enum FakeCompletion {
    Text(String),
    ToolUse { name: String, arguments: serde_json::Value },
    Refusal,
    Error(anyhow::Error),
}

// “剧本”设定：模型先调一个 edit_file，再调一个 terminal，最后输出一段文本
model.enqueue_response(FakeCompletion::ToolUse {
    name: "edit_file".into(),
    arguments: json!({ "path": "src/main.rs", "edits": [...] })
});
model.enqueue_response(FakeCompletion::ToolUse {
    name: "terminal".into(),
    arguments: json!({ "command": "cargo test" })
});
model.enqueue_response(FakeCompletion::Text("All tests passed!".into()));

// 运行 thread.send(...) 验证状态机是否严格按照剧本进行双层循环与工具调度！

# 1. 查看 19 个 Provider 的物理文件清单与行数
wc -l crates/language_models/src/provider/*.rs | sort -rn

# 2. 查看 LanguageModel trait 的核心定义
sed -n '20,60p' crates/language_model/src/language_model.rs

# 3. 检查拒答回退的处理代码
grep -n -C 10 "refusal_fallback_model_id" crates/agent/src/thread.rs

# 4. 查看反序列化转义容错函数的完整实现
sed -n '35,55p' crates/agent/src/tools.rs

# 5. 查看测试替身 FakeLanguageModel 的构造
head -n 50 crates/language_model/src/fake_provider.rs