第2章：ACP 协议层 —— 平权架构与会话投影

# Cargo.toml:521
agent-client-protocol = { version = "=2.0.0", features = ["unstable"] }

// crates/acp_thread/src/connection.rs:91-180
pub trait AgentConnection {
    fn agent_id(&self) -> AgentId;
    fn telemetry_id(&self) -> SharedString;

    fn agent_version(&self) -> Option<SharedString> { None }

    /// 创建一个全新的会话并返回 AcpThread 实体
    fn new_session(
        self: Rc<Self>,
        project: Entity<Project>,
        work_dirs: PathList,
        cx: &mut App,
    ) -> Task<Result<Entity<AcpThread>>>;

    fn supports_load_session(&self) -> bool { false }
    fn load_session(
        self: Rc<Self>,
        session_id: acp::SessionId,
        project: Entity<Project>,
        work_dirs: PathList,
        title: Option<SharedString>,
        cx: &mut App,
    ) -> Task<Result<Entity<AcpThread>>> {
        Task::ready(Err(anyhow::Error::msg("Loading sessions is not supported")))
    }

    fn auth_methods(&self) -> &[acp::AuthMethod];
    fn authenticate(&self, method: acp::AuthMethodId, cx: &mut App) -> Task<Result<()>>;

    /// 向 Agent 发送提示词请求
    fn prompt(&self, params: acp::PromptRequest, cx: &mut App)
        -> Task<Result<acp::PromptResponse>>;

    /// 取消当前正在进行的生成
    fn cancel(&self, session_id: &acp::SessionId, cx: &mut App);

    // ... 8 个可选能力探测接口 ...

    fn into_any(self: Rc<Self>) -> Rc<dyn Any>;
}

// 动态能力探测方法族 (crates/acp_thread/src/connection.rs:181-235)
impl dyn AgentConnection {
    pub fn downcast<T: 'static + AgentConnection + Sized>(self: Rc<Self>) -> Option<Rc<T>> {
        self.into_any().downcast().ok()
    }
}

// crates/acp_thread/src/acp_thread.rs:396-404
pub enum AgentThreadEntry {
    UserMessage(UserMessage),
    AssistantMessage(AssistantMessage),
    ToolCall(ToolCall),
    Elicitation(ElicitationEntryId),
    CompletedPlan(Vec<PlanEntry>),
    ContextCompaction(ContextCompaction),
}

// crates/acp_thread/src/acp_thread.rs:1266-1284
pub enum ToolCallStatus {
    /// 工具调用已被提出，准备展示给用户但尚未运行
    Pending,
    /// 触发了权限控制，正在等待用户在 UI 弹窗中确认
    WaitingForConfirmation {
        current_status: acp::ToolCallStatus,
        options: PermissionOptions,
        respond_tx: oneshot::Sender<RequestPermissionOutcome>,
        kind: AuthorizationKind,
    },
    /// 用户已授权（或自动放行），工具正在执行
    InProgress,
    /// 工具执行成功并返回结果
    Completed,
    /// 工具执行抛出错误
    Failed,
    /// 用户主动拒绝授权
    Rejected,
    /// 用户在中途取消了生成
    Canceled,
}

// crates/acp_thread/src/acp_thread.rs:1810-1815
pub enum ToolCallContent {
    ContentBlock(ContentBlock),
    Diff(Entity<Diff>),
    Terminal(Entity<Terminal>),
}

// crates/acp_thread/src/acp_thread.rs:2593-2720 核心逻辑节选
pub fn handle_session_update(
    &mut self,
    update: acp::SessionUpdate,
    cx: &mut Context<Self>,
) -> Result<(), acp::Error> {
    match update {
        acp::SessionUpdate::UserMessageChunk(acp::ContentChunk { content, message_id, .. }) => {
            // 乐观更新去重逻辑：如果本地已经乐观插入了该 UserMessage，跳过重复回显
            let already_in_user_message = self.check_and_merge_optimistic(message_id, &content);
            if !already_in_user_message {
                self.push_user_content_block_from_agent(message_id, content, cx);
            }
        }
        acp::SessionUpdate::AgentMessageChunk(acp::ContentChunk { content, message_id, .. }) => {
            self.push_assistant_content_block_with_message_id(message_id, content, false, false, cx);
        }
        acp::SessionUpdate::AgentThoughtChunk(acp::ContentChunk { content, message_id, .. }) => {
            // 模型的思考链过程（如 Claude 3.7 Thinking / DeepSeek R1 Reasoning）
            self.push_assistant_content_block_with_message_id(message_id, content, true, false, cx);
        }
        acp::SessionUpdate::ToolCall(tool_call) => {
            self.upsert_tool_call(tool_call, cx)?;
        }
        acp::SessionUpdate::ToolCallUpdate(tool_call_update) => {
            self.update_tool_call(tool_call_update, cx)?;
        }
        acp::SessionUpdate::Plan(plan) => {
            self.update_plan(plan, cx);
        }
        acp::SessionUpdate::SessionInfoUpdate(info_update) => {
            if let MaybeUndefined::Value(title) = info_update.title {
                self.title = Some(title.into());
                cx.emit(AcpThreadEvent::TitleUpdated);
            }
        }
        acp::SessionUpdate::CurrentModeUpdate(acp::CurrentModeUpdate { current_mode_id, .. }) => {
            cx.emit(AcpThreadEvent::ModeUpdated(current_mode_id));
        }
        acp::SessionUpdate::ConfigOptionUpdate(acp::ConfigOptionUpdate { config_options, .. }) => {
            cx.emit(AcpThreadEvent::ConfigOptionsUpdated(config_options));
        }
        acp::SessionUpdate::UsageUpdate(update) => {
            let usage = self.token_usage.get_or_insert_with(Default::default);
            usage.max_tokens = update.size;
            usage.used_tokens = update.used;
            cx.emit(AcpThreadEvent::TokenUsageUpdated);
        }
        _ => {}
    }
    Ok(())
}

// crates/agent/src/agent.rs:2276-2315
fn handle_thread_events(
    mut events: mpsc::UnboundedReceiver<Result<ThreadEvent>>,
    acp_thread: WeakEntity<AcpThread>,
    connection: Option<NativeAgentConnection>,
    cx: &App,
) -> Task<Result<acp::PromptResponse>> {
    cx.spawn(async move |cx| {
        while let Some(result) = events.next().await {
            match result? {
                ThreadEvent::UserMessage(message) => {
                    acp_thread.update(cx, |t, cx| {
                        for content in &*message.content {
                            t.push_user_content_block(Some(message.id.clone()), content.clone().into(), cx);
                        }
                    })?;
                }
                ThreadEvent::AgentText(text) => {
                    acp_thread.update(cx, |t, cx| t.push_assistant_content_block(text.into(), false, cx))?;
                }
                ThreadEvent::AgentThinking(text) => {
                    acp_thread.update(cx, |t, cx| t.push_assistant_content_block(text.into(), true, cx))?;
                }
                ThreadEvent::ToolCallAuthorization(auth) => {
                    // 原生 Agent 发起权限申请，交由 AcpThread 弹窗
                    let outcome_task = acp_thread.update(cx, |t, cx| {
                        t.request_tool_call_authorization(auth.tool_call, auth.options, auth.kind, cx)
                    })??;
                    // ... 异步等待用户选择并回传给 Thread ...
                }
                // ... 其他事件映射 ...
            }
        }
        Ok(acp::PromptResponse::default())
    })
}

acp_thread::RequestPermissionOutcome::InterruptedByFollowUp => {
    acp_thread::SelectedPermissionOutcome::new(
        acp::PermissionOptionId::new(FOLLOW_UP_PERMISSION_DENIED_OPTION_ID),
        acp::PermissionOptionKind::RejectOnce,
    )
}

# 1. 查看 AgentConnection trait 的所有核心方法定义
sed -n '91,150p' crates/acp_thread/src/connection.rs

# 2. 查看 AcpThread 的 6 大条目全集
sed -n '396,410p' crates/acp_thread/src/acp_thread.rs

# 3. 统计 handle_session_update 覆盖的 ACP 更新事件类型数
grep -n "acp::SessionUpdate::" crates/acp_thread/src/acp_thread.rs

# 4. 查看 NativeAgentConnection 对 AgentConnection 的具体实现
sed -n '2726,2780p' crates/agent/src/agent.rs

# 5. 查看外部 Agent 驱动中的调试缓冲区大小定义（实测 2000）
grep -n "MAX_DEBUG_BACKLOG_MESSAGES" crates/agent_servers/src/acp.rs