Skip to content

WORKSPACE_MIGRATION.md

Latest commit

 

History

History
221 lines (171 loc) · 5.75 KB

WORKSPACE_MIGRATION.md

File metadata and controls

221 lines (171 loc) · 5.75 KB
Raw

Workspace 重构完成报告

概述

已成功将 Claude Code Rust 项目重构为 Workspace 架构，包含三个核心 Crate：

  • api-client: Claude API 客户端 + 流式传输 + OAuth + 工具调用
  • tools: 工具定义与执行框架 + API 工具调用集成
  • runtime: 会话状态管理 + 上下文压缩 + 内存管理

已完成的模块

1. api-client Crate

核心功能：

  • ✅ HTTP 客户端 (client.rs)
  • ✅ 流式响应支持 (streaming.rs)
  • ✅ 工具调用处理 (tool_use.rs)
  • ✅ OAuth 2.0 认证 (oauth.rs)
  • ✅ 多提供者支持 (provider.rs)
  • ✅ 完整的错误处理 (error.rs)
  • ✅ 核心 API 类型 (types.rs)

关键特性：

  • Claude API 完整集成（消息、工具调用、流式响应）
  • 支持多种提供者（Anthropic、OpenAI、Azure、Gemini、Bedrock、Vertex）
  • OAuth 2.0 授权码流程
  • 自动令牌刷新
  • SSE 流式响应处理
  • 工具调用循环执行

2. tools Crate

核心功能：

  • ✅ 工具类型系统 (types.rs)
  • ✅ 工具基础 trait (base.rs)
  • ✅ 工具注册表 (registry.rs)
  • ✅ 权限系统 (permissions.rs)
  • ✅ API 工具调用集成

关键特性：

  • Tool trait 支持直接执行和 API 工具调用
  • ApiToolCall / ApiToolResult 类型用于 Claude API 集成
  • ToolManager 支持批量处理 API 工具调用
  • 完整的权限系统（允许/拒绝/询问规则）
  • 支持通配符和 MCP 格式工具名称匹配

3. runtime Crate

核心功能：

  • ✅ 会话管理 (session.rs)
  • ✅ 上下文管理 (context.rs)
  • ✅ 上下文压缩 (compact.rs)
  • ✅ 内存管理 (memory.rs)

关键特性：

  • 会话生命周期管理（创建、激活、暂停、关闭）
  • 消息历史跟踪
  • 智能上下文压缩（截断、摘要、智能策略）
  • 内存存储抽象
  • 会话持久化支持

Workspace 配置

[workspace]
members = [
    "crates/claude-cli",
    "crates/api-client",
    "crates/tools",
    "crates/runtime",
]

依赖管理：

  • 使用 workspace 依赖统一管理版本
  • 各 Crate 按需继承或添加特定依赖

下一步工作

1. 迁移现有代码

将 src/ 目录下的现有代码逐步迁移到对应 Crate：

  • 工具实现 -> crates/tools/src/
  • API 相关代码 -> crates/api-client/src/
  • 会话/状态代码 -> crates/runtime/src/

2. 添加更多 Crate

根据图片中的架构，后续添加：

  • commands: 斜杠命令系统
  • plugins: 插件系统
  • compat-harness: 上游编辑器集成
  • server: HTTP/SSE 服务器
  • lsp: LSP 客户端集成

3. 集成测试

  • 创建端到端测试验证工具调用流程
  • 测试流式响应处理
  • 测试 OAuth 认证流程

4. 文档完善

  • 为每个 Crate 添加 API 文档
  • 创建使用示例
  • 更新 README

使用示例

API 客户端 + 工具调用

use api_client::{ApiClient, ApiClientConfig, ApiModel, ApiRequestBuilder};
use tools::{ToolManager, ToolExecutionOptions, ToolRegistry};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 创建 API 客户端
    let client = ApiClient::new("https://api.anthropic.com", ApiClientConfig::default())
        .with_api_key("your-api-key");

    // 创建工具管理器
    let options = ToolExecutionOptions {
        enable_api_tool_use: true,
        ..Default::default()
    };
    let tool_manager = ToolManager::new(options);

    // 发送带工具的消息
    let request = ApiRequestBuilder::new(ApiModel::Claude35Sonnet20241022)
        .add_message(ApiRole::User, "Read file.txt")
        .add_tool(ApiTool {
            name: "Read".to_string(),
            description: Some("Read file".to_string()),
            input_schema: serde_json::json!({
                "type": "object",
                "properties": {
                    "file_path": {"type": "string"}
                },
                "required": ["file_path"]
            }),
        })
        .build();

    let response = client.send_request(request).await?;
    
    // 处理工具调用
    let tool_results = client.handle_tool_calls(response, &tool_manager).await?;
    
    Ok(())
}

流式响应

let stream = client.send_stream_request(request).await?;

while let Some(event) = stream.next().await {
    match event? {
        StreamEvent::ContentBlockDelta { delta, .. } => {
            print!("{}", delta.text);
        }
        StreamEvent::MessageStop => break,
        _ => {}
    }
}

OAuth 认证

let mut oauth = OAuthClient::new(OAuthClientConfig::new(
    "client-id",
    "https://auth.example.com/authorize",
    "https://auth.example.com/token",
    "https://app.example.com/callback",
))?;

// 获取授权 URL
let auth_url = oauth.authorization_url("random-state");
println!("Visit: {}", auth_url);

// 交换授权码
oauth.exchange_code("auth-code").await?;

// 使用访问令牌
let token = oauth.access_token().await?;

技术亮点

  1. 完整的工具调用支持: 实现了从 Claude API 接收工具调用、执行本地工具、返回结果给 API 的完整闭环

  2. 流式响应处理: 支持 SSE 流式响应，可实时显示生成内容

  3. 多提供者支持: 统一的 Provider 抽象，支持多个 LLM 提供者

  4. 模块化架构: 清晰的 Crate 边界，便于维护和扩展

  5. 类型安全: 完整的 Rust 类型系统支持，编译时保证正确性

构建命令

# 构建整个 workspace
cargo build

# 构建特定 Crate
cargo build -p api-client
cargo build -p tools
cargo build -p runtime

# 运行测试
cargo test -p api-client
cargo test -p tools
cargo test -p runtime

注意事项

  1. 当前代码主要关注核心架构，具体工具实现需要从原项目迁移
  2. OAuth 实现需要实际的 OAuth 服务器进行测试
  3. 流式响应处理在实际使用时需要配合适当的错误处理