597 lines
24 KiB
Markdown
597 lines
24 KiB
Markdown
# Agent Resume via ACP 实现计划
|
||
|
||
## 方案概述
|
||
|
||
采用 **方式一：通过 NewSessionRequest 的 meta 参数** 实现 resume 功能。
|
||
|
||
核心思路：统一使用 `NewSessionRequest` + `_meta.claudeCode.options.resume` 传递 session_id，移除冗余的 `load_session` 尝试逻辑。
|
||
|
||
**重要**：Resume 是"尝试性"的，如果 session 不存在导致 Agent 启动失败，会自动降级为不传 resume 参数，创建新会话。
|
||
|
||
---
|
||
|
||
## Resume 失败降级方案（核心机制）
|
||
|
||
### 问题场景
|
||
|
||
当用户传入的 `session_id` 对应的会话不存在时（已过期、被清理、或从未存在），Agent 会启动失败：
|
||
|
||
```
|
||
No conversation found for session id: abc-123
|
||
```
|
||
|
||
### 降级策略
|
||
|
||
**优先尝试 resume，失败则降级为新会话**：
|
||
|
||
```
|
||
第一次尝试：带 resume 参数
|
||
↓
|
||
├─ 成功 → 恢复上下文，继续对话
|
||
│
|
||
└─ 失败（任何原因）
|
||
↓
|
||
第二次尝试：不带 resume 参数
|
||
↓
|
||
└─ 成功 → 创建新会话
|
||
```
|
||
|
||
**关键点**：不需要判断具体错误原因，只要 `has_resume && 启动失败`，就直接降级重试。
|
||
|
||
### 当前实现位置（需改动）
|
||
|
||
**文件**: `session_manager.rs:217-261`
|
||
|
||
**当前代码**（需简化）:
|
||
```rust
|
||
// 检查是否因为 resume 导致的失败
|
||
if has_resume
|
||
&& (error_msg.contains("No conversation found")
|
||
|| error_msg.contains("session")
|
||
|| error_msg.contains("exited with code 1")) // ← 删除这些判断
|
||
{
|
||
// 降级...
|
||
}
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
// 只要带 resume 且启动失败，就降级重试
|
||
if has_resume {
|
||
tracing::warn!(
|
||
"⚠️ Agent 启动失败（带 resume），降级为不使用 resume 重试: error={}",
|
||
error_msg
|
||
);
|
||
|
||
// 创建新的 config，不包含 resume_session_id
|
||
let retry_config = AgentStartConfig {
|
||
system_prompt: start_config.system_prompt,
|
||
mcp_servers: start_config.mcp_servers,
|
||
extra_meta: start_config.extra_meta,
|
||
service_type: start_config.service_type,
|
||
resume_session_id: None, // ← 关键：去掉 resume
|
||
};
|
||
|
||
tracing::info!("🔄 重试启动 Agent（不使用 resume）");
|
||
|
||
// 第二次尝试：不带 resume
|
||
launcher.launch(..., retry_config, ...).await?
|
||
} else {
|
||
// 不带 resume 的失败，直接返回错误
|
||
return Err(e);
|
||
}
|
||
```
|
||
|
||
### 降级流程图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ChatRequest { session_id: "abc-123" } │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ acp_worker.rs │
|
||
│ └─ AgentStartConfig { resume_session_id: Some("abc-123") } │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ session_manager.rs │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ 第一次尝试 │ │
|
||
│ │ launcher.launch(start_config) │ │
|
||
│ │ → meta: { claudeCode.options.resume: "abc-123" } │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────────┴───────────────┐ │
|
||
│ ▼ ▼ │
|
||
│ ┌────────────────┐ ┌────────────────────┐ │
|
||
│ │ ✅ 成功 │ │ ❌ 失败 │ │
|
||
│ │ session 存在 │ │ "No conversation │ │
|
||
│ │ 恢复上下文 │ │ found" │ │
|
||
│ └────────────────┘ └────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ 第二次尝试（降级） │ │
|
||
│ │ retry_config.resume_session_id = None │ │
|
||
│ │ launcher.launch(retry_config) │ │
|
||
│ │ → meta: { } ← 不包含 resume │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌────────────────┐ │
|
||
│ │ ✅ 成功 │ │
|
||
│ │ 创建新会话 │ │
|
||
│ │ 返回新 session │ │
|
||
│ └────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 本次改动对降级机制的影响
|
||
|
||
**需要简化**。移除错误关键字判断，改为：只要 `has_resume && 启动失败` 就降级。
|
||
|
||
| 层级 | 改动 | 降级机制 |
|
||
|------|------|----------|
|
||
| session_manager.rs | 简化降级判断逻辑 | **需改动** |
|
||
| claude_code_launcher.rs | 简化会话创建逻辑 | 不涉及 |
|
||
|
||
---
|
||
|
||
## 当前代码状态分析
|
||
|
||
### ✅ 已正确实现的部分
|
||
|
||
| 文件 | 功能 | 状态 |
|
||
|------|------|------|
|
||
| `agent.rs:95-137` | `AgentStartConfig.build_meta()` 构建 `claudeCode.options.resume` | ✅ 完成 |
|
||
| `acp_worker.rs:158-180` | 判断是否需要 resume 并设置 `resume_session_id` | ✅ 完成 |
|
||
| `session_manager.rs:217-261` | Resume 失败降级重试机制（框架已完成，判断逻辑需简化） | ⚠️ 需简化 |
|
||
|
||
### ❌ 需要改动的部分
|
||
|
||
| 文件 | 问题 | 改动 |
|
||
|------|------|------|
|
||
| `claude_code_launcher.rs:438-480` | 冗余的 `load_session` 尝试逻辑 | 简化为统一 `new_session` |
|
||
| `claude_code_launcher.rs:291-299` | `session_id` 参数冗余 | 移除此参数 |
|
||
| `session_manager.rs:207-214, 247-254` | 调用 launch 时传递 `session_id_hint` | 移除此参数 |
|
||
| `session_manager.rs:224-227` | 降级判断过于复杂（检测错误关键字） | 简化为 `if has_resume` |
|
||
|
||
---
|
||
|
||
## 改动任务清单
|
||
|
||
### Task 0: 简化 session_manager.rs 降级判断逻辑（新增）
|
||
|
||
**文件**: `crates/agent_abstraction/src/session/session_manager.rs`
|
||
|
||
**改动位置**: 约 223-228 行
|
||
|
||
**当前代码**:
|
||
```rust
|
||
// 检查是否因为 resume 导致的失败
|
||
if has_resume
|
||
&& (error_msg.contains("No conversation found")
|
||
|| error_msg.contains("session")
|
||
|| error_msg.contains("exited with code 1"))
|
||
{
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
// 只要带 resume 且启动失败，就降级重试（不判断具体错误原因）
|
||
if has_resume {
|
||
```
|
||
|
||
**同时更新日志信息**:
|
||
```rust
|
||
tracing::warn!(
|
||
"⚠️ Agent 启动失败（带 resume），降级为不使用 resume 重试: error={}",
|
||
error_msg
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### Task 1: 简化 claude_code_launcher.rs 会话创建逻辑
|
||
|
||
**文件**: `crates/agent_abstraction/src/compat/claude_code_launcher.rs`
|
||
|
||
**改动位置**: 约 438-480 行
|
||
|
||
**当前代码**:
|
||
```rust
|
||
// 创建会话
|
||
let session_id = match session_id_for_closure {
|
||
Some(sid) => {
|
||
debug!("尝试加载 ACP 会话[load_session]");
|
||
let given_session_id = SessionId::new(sid);
|
||
match client_conn
|
||
.load_session(LoadSessionRequest::new(
|
||
given_session_id.clone(),
|
||
project_path_for_closure.clone(),
|
||
))
|
||
.await
|
||
{
|
||
Ok(resp) => {
|
||
debug!("ACP 会话加载成功[load_session],{:?}", resp);
|
||
given_session_id
|
||
}
|
||
Err(e) => {
|
||
warn!(
|
||
"load_session 失败或未实现，回退创建新会话[new_session]: {:?}",
|
||
e
|
||
);
|
||
// 注意：即使 load_session 失败，仍然会创建 new_session
|
||
// resume_session_id 会通过 meta.claudeCode.options.resume 传递
|
||
let new_session_request =
|
||
NewSessionRequest::new(project_path_for_closure.clone())
|
||
.mcp_servers(mcp_servers.clone())
|
||
.meta(system_prompt_meta.clone());
|
||
let resp = client_conn.new_session(new_session_request).await?;
|
||
debug!("ACP 会话创建成功[new_session],{:?}", resp);
|
||
resp.session_id
|
||
}
|
||
}
|
||
}
|
||
None => {
|
||
debug!("创建 ACP 会话[new_session]");
|
||
let new_session_request =
|
||
NewSessionRequest::new(project_path_for_closure.clone())
|
||
.mcp_servers(mcp_servers)
|
||
.meta(system_prompt_meta);
|
||
let resp = client_conn.new_session(new_session_request).await?;
|
||
debug!("ACP 会话创建成功[new_session],{:?}", resp);
|
||
resp.session_id
|
||
}
|
||
};
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
// 创建会话（统一使用 new_session，resume 通过 meta 传递）
|
||
// 如果 start_config.resume_session_id 有值，build_meta() 会自动构建
|
||
// _meta.claudeCode.options.resume 结构
|
||
debug!("创建 ACP 会话[new_session]");
|
||
let new_session_request = NewSessionRequest::new(project_path_for_closure.clone())
|
||
.mcp_servers(mcp_servers)
|
||
.meta(system_prompt_meta);
|
||
|
||
let resp = client_conn
|
||
.new_session(new_session_request)
|
||
.await
|
||
.context("ACP 会话创建失败")?;
|
||
|
||
debug!(
|
||
"ACP 会话创建成功[new_session], session_id={}",
|
||
resp.session_id.0
|
||
);
|
||
let session_id = resp.session_id;
|
||
```
|
||
|
||
**同时需要移除的变量**:
|
||
```rust
|
||
// 约 317 行，移除这行
|
||
let session_id_for_closure = session_id.clone();
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: 移除 launch 方法的 session_id 参数
|
||
|
||
**文件**: `crates/agent_abstraction/src/compat/claude_code_launcher.rs`
|
||
|
||
**改动位置**: 约 279-299 行（方法签名和文档）
|
||
|
||
**当前代码**:
|
||
```rust
|
||
/// 启动 Claude Code ACP Agent 服务
|
||
///
|
||
/// # 参数
|
||
/// - `project_id`: 项目 ID
|
||
/// - `project_path`: 项目工作目录
|
||
/// - `session_id`: 可选的会话 ID（用于恢复会话）
|
||
/// - `model_provider`: 模型提供商配置
|
||
/// - `start_config`: Agent 启动配置（包含系统提示词等）
|
||
/// - `client`: ACP 客户端实现
|
||
///
|
||
/// # 返回值
|
||
/// 返回 LauncherConnectionInfoComplete，包含会话信息和生命周期守卫
|
||
pub async fn launch(
|
||
&self,
|
||
project_id: String,
|
||
project_path: PathBuf,
|
||
session_id: Option<String>,
|
||
model_provider: Option<ModelProviderConfig>,
|
||
start_config: AgentStartConfig,
|
||
client: C,
|
||
) -> Result<LauncherConnectionInfoComplete> {
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
/// 启动 Claude Code ACP Agent 服务
|
||
///
|
||
/// # 参数
|
||
/// - `project_id`: 项目 ID
|
||
/// - `project_path`: 项目工作目录
|
||
/// - `model_provider`: 模型提供商配置
|
||
/// - `start_config`: Agent 启动配置（包含系统提示词、resume_session_id 等）
|
||
/// - `client`: ACP 客户端实现
|
||
///
|
||
/// # Resume 机制
|
||
/// 如果需要恢复会话，通过 `start_config.resume_session_id` 传递 session_id，
|
||
/// 会自动构建 `_meta.claudeCode.options.resume` 结构传递给 Agent。
|
||
///
|
||
/// # 返回值
|
||
/// 返回 LauncherConnectionInfoComplete，包含会话信息和生命周期守卫
|
||
pub async fn launch(
|
||
&self,
|
||
project_id: String,
|
||
project_path: PathBuf,
|
||
model_provider: Option<ModelProviderConfig>,
|
||
start_config: AgentStartConfig,
|
||
client: C,
|
||
) -> Result<LauncherConnectionInfoComplete> {
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 更新 session_manager.rs 的 launch 调用
|
||
|
||
**文件**: `crates/agent_abstraction/src/session/session_manager.rs`
|
||
|
||
**改动位置 1**: 约 207-214 行（第一次调用）
|
||
|
||
**当前代码**:
|
||
```rust
|
||
let result = launcher
|
||
.launch(
|
||
project_id.clone(),
|
||
project_path.clone(),
|
||
session_id_hint.clone(),
|
||
model_provider.clone(),
|
||
start_config.clone(),
|
||
client,
|
||
)
|
||
.await;
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
let result = launcher
|
||
.launch(
|
||
project_id.clone(),
|
||
project_path.clone(),
|
||
model_provider.clone(),
|
||
start_config.clone(),
|
||
client,
|
||
)
|
||
.await;
|
||
```
|
||
|
||
**改动位置 2**: 约 247-254 行（降级重试调用）
|
||
|
||
**当前代码**:
|
||
```rust
|
||
launcher
|
||
.launch(
|
||
project_id.clone(),
|
||
project_path,
|
||
session_id_hint,
|
||
model_provider.clone(),
|
||
retry_config,
|
||
C::default(),
|
||
)
|
||
.await?
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
launcher
|
||
.launch(
|
||
project_id.clone(),
|
||
project_path,
|
||
model_provider.clone(),
|
||
retry_config,
|
||
C::default(),
|
||
)
|
||
.await?
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 清理 session_manager.rs 的方法签名（可选）
|
||
|
||
**文件**: `crates/agent_abstraction/src/session/session_manager.rs`
|
||
|
||
**改动位置**: `create_new_session` 方法签名（约 185-196 行）
|
||
|
||
**当前代码**:
|
||
```rust
|
||
pub async fn create_new_session(
|
||
&self,
|
||
project_id: String,
|
||
project_path: PathBuf,
|
||
session_id_hint: Option<String>,
|
||
model_provider: Option<ModelProviderConfig>,
|
||
start_config: AgentStartConfig,
|
||
client: C,
|
||
) -> Result<Arc<SessionInfo>> {
|
||
```
|
||
|
||
**评估**:
|
||
- `session_id_hint` 参数当前未被使用（只是传递给 launcher）
|
||
- 可以移除，但需要检查 `get_or_create_session` 等上游调用方
|
||
- **建议**: 暂时保留此参数，避免过大改动范围
|
||
|
||
---
|
||
|
||
### Task 5: 移除未使用的 import
|
||
|
||
**文件**: `crates/agent_abstraction/src/compat/claude_code_launcher.rs`
|
||
|
||
**改动位置**: 约 11-14 行
|
||
|
||
**当前代码**:
|
||
```rust
|
||
use agent_client_protocol::{
|
||
Agent, Client, ClientSideConnection, Implementation, InitializeRequest, LoadSessionRequest,
|
||
McpServer, McpServerStdio, NewSessionRequest, PromptRequest, SessionId,
|
||
};
|
||
```
|
||
|
||
**改动后代码**:
|
||
```rust
|
||
use agent_client_protocol::{
|
||
Agent, Client, ClientSideConnection, Implementation, InitializeRequest,
|
||
McpServer, McpServerStdio, NewSessionRequest, PromptRequest, SessionId,
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 改动验证清单
|
||
|
||
### 编译验证
|
||
- [ ] `cargo build -p agent_abstraction` 编译通过
|
||
- [ ] `cargo build --workspace` 全项目编译通过
|
||
- [ ] `cargo clippy` 无新增警告
|
||
|
||
### 单元测试
|
||
- [ ] `AgentStartConfig.build_meta()` 测试用例通过
|
||
- [ ] 现有测试用例通过
|
||
|
||
### 集成测试
|
||
- [ ] 新建会话：正常创建
|
||
- [ ] Resume 会话：传入有效 session_id，恢复上下文
|
||
- [ ] Resume 失败降级：传入无效 session_id，自动降级为新会话
|
||
|
||
---
|
||
|
||
## 实现顺序
|
||
|
||
```
|
||
Step 1: Task 0 - 简化 session_manager.rs 降级判断逻辑
|
||
│
|
||
└─ 移除错误关键字判断，改为 if has_resume
|
||
|
||
Step 2: Task 1 - 简化 claude_code_launcher.rs 会话创建逻辑
|
||
│
|
||
├─ 移除 load_session 尝试
|
||
├─ 统一使用 new_session
|
||
└─ 移除 session_id_for_closure 变量
|
||
|
||
Step 3: Task 2 - 移除 launch 方法的 session_id 参数
|
||
│
|
||
└─ 更新方法签名和文档
|
||
|
||
Step 4: Task 3 - 更新 session_manager.rs 的 launch 调用
|
||
│
|
||
├─ 更新第一次 launch 调用
|
||
└─ 更新降级重试调用
|
||
|
||
Step 5: Task 5 - 清理未使用的 import
|
||
│
|
||
└─ 移除 LoadSessionRequest
|
||
|
||
Step 6: 验证
|
||
│
|
||
├─ 编译验证
|
||
├─ 运行测试
|
||
└─ 手动测试 resume 流程
|
||
```
|
||
|
||
---
|
||
|
||
## 风险评估
|
||
|
||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||
|------|------|------|----------|
|
||
| 移除 session_id 参数导致编译错误 | 低 | 低 | 搜索所有调用方并更新 |
|
||
| Resume 功能回归 | 低 | 中 | 简化降级机制更健壮 |
|
||
| 逻辑改动影响其他功能 | 低 | 中 | 充分测试 |
|
||
|
||
---
|
||
|
||
## 预估工作量
|
||
|
||
| Task | 预估代码行数 | 复杂度 |
|
||
|------|-------------|--------|
|
||
| Task 0 | -4, +2 | 低 |
|
||
| Task 1 | -30, +15 | 低 |
|
||
| Task 2 | -2, +5 | 低 |
|
||
| Task 3 | -2, +0 | 低 |
|
||
| Task 5 | -1, +0 | 低 |
|
||
| **总计** | **约 -39 行，+22 行** | **低** |
|
||
|
||
---
|
||
|
||
## 附录：完整数据流（改动后）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ HTTP/gRPC Request │
|
||
│ ChatRequest { session_id: "abc-123", prompt: "..." } │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ acp_worker.rs │
|
||
│ ├─ 检查内存中是否存在会话 │
|
||
│ │ └─ 存在且 session_id 匹配 → with_resume_session_id() │
|
||
│ └─ 构建 AgentStartConfig { resume_session_id: Some("abc-123") }│
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ session_manager.rs │
|
||
│ └─ launcher.launch(project_id, project_path, │
|
||
│ model_provider, start_config, client) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ claude_code_launcher.rs │
|
||
│ ├─ start_config.build_meta() 构建: │
|
||
│ │ { │
|
||
│ │ "claudeCode": { │
|
||
│ │ "options": { "resume": "abc-123" } │
|
||
│ │ } │
|
||
│ │ } │
|
||
│ └─ NewSessionRequest::new(cwd).meta(meta) ← 统一入口 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼ ACP session/new
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ claude-code-acp │
|
||
│ ├─ newSession() 解析 _meta.claudeCode.options.resume │
|
||
│ └─ query({ options: { resume: "abc-123" } }) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌───────────────┴───────────────┐
|
||
▼ ▼
|
||
┌────────────────┐ ┌────────────────────────┐
|
||
│ ✅ 会话存在 │ │ ❌ 会话不存在 │
|
||
│ → 恢复上下文 │ │ → 抛出错误 │
|
||
│ → 返回成功 │ │ "No conversation found"│
|
||
└────────────────┘ └────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ session_manager.rs 降级处理 │
|
||
│ ├─ 检测错误关键字 │
|
||
│ ├─ 创建 retry_config { resume_session_id: None }│
|
||
│ └─ 第二次 launcher.launch(retry_config) │
|
||
└─────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ ✅ 成功创建新会话 │
|
||
│ └─ 返回新的 session_id │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|