Claude Code SDK TS 的 Fluent API 深度解析

概述

Claude Code SDK TS 提供了一套流畅的 API 接口（Fluent API），极大地简化了与 Claude 代码交互的复杂度。这种链式调用风格的 API 设计让开发者能够以更直观、更符合人类思维习惯的方式构建复杂的查询和处理响应。

Fluent API 核心优势

1. 链式调用：通过方法链实现配置和查询的一体化操作
2. 类型安全：基于 TypeScript 的强类型检查
3. 模块化设计：各功能模块清晰分离又紧密配合
4. 会话管理：内置完善的会话上下文保持机制

快速入门

让我们从一个最简单的示例开始：

import { claude } from '@instantlyeasy/claude-code-sdk-ts';

const response = await claude()
  .withModel('sonnet')  // 指定模型版本
  .skipPermissions()    // 跳过权限确认
  .query('你好，Claude！') // 发送查询
  .asText();           // 获取纯文本响应

这个简单的例子展示了 Fluent API 的基本结构：初始化 → 配置 → 查询 → 结果处理。

查询构建器详解

模型配置

claude()
  .withModel('opus')        // 指定使用 opus 模型
  .withTimeout(60000)       // 设置60秒超时
  .debug(true)             // 启用调试模式

工具管理

工具管理是 Claude Code SDK 的核心功能之一：

claude()
  .allowTools('Read', 'Write', 'Edit')  // 显式允许特定工具
  .denyTools('Bash', 'WebSearch')      // 显式禁用特定工具
  .allowTools()                        // 无参数表示只读模式

权限控制

claude()
  .skipPermissions()       // 跳过所有权限提示
  .acceptEdits()          // 自动接受文件编辑
  .withPermissions('default') // 使用默认权限处理

环境配置

claude()
  .inDirectory('/项目路径')  // 设置工作目录
  .withEnv({ NODE_ENV: 'production' }) // 设置环境变量

目录上下文管理

claude()
  .addDirectory('/单一目录路径')          // 添加单个目录
  .addDirectory(['../apps', '../lib'])   // 添加多个目录
  .addDirectory('/另一个目录')           // 可多次调用累积目录

目录管理功能特别适合需要跨多个项目目录进行代码分析或重构的场景。

响应处理机制

基础解析方法

const parser = claude().query('你的提示词');

const text = await parser.asText();     // 获取纯文本
const result = await parser.asResult(); // 获取最终结果
const messages = await parser.asArray(); // 获取所有消息

结构化数据提取

// 提取JSON格式数据
const data = await parser.asJSON<MyInterface>();

// 获取工具执行详情
const executions = await parser.asToolExecutions();

// 查找特定工具结果
const fileContents = await parser.findToolResults('Read');

流式处理

Claude Code SDK 的流式处理有其独特之处：

await parser.stream(async (message) => {
  if (message.type === 'assistant') {
    // 注意：这里获取的是完整的文本块，而非逐token更新
    console.log(message.content[0].text);
  }
});

中断控制

const controller = new AbortController();
const parser = claude()
  .withSignal(controller.signal)
  .query('长时间运行的查询');

// 5秒后中断
setTimeout(() => controller.abort(), 5000);

try {
  await parser.stream(/*...*/);
} catch (error) {
  if (error instanceof AbortError) {
    console.log('查询被取消');
  }
}

会话管理实践

会话管理是保持对话上下文的关键功能：

基础会话示例

// 首次查询
const parser = claude()
  .withModel('sonnet')
  .query('记住这个数字：42');

const sessionId = await parser.getSessionId();

// 后续查询
const followUp = await claude()
  .withSessionId(sessionId)
  .query('我刚才让你记住的数字是多少？')
  .asText();  // 将返回"42"

复杂工作流中的会话模式

async function refactorSession() {
  const builder = claude().withModel('opus');
  
  // 初始化会话
  const parser = builder.query('分析当前代码结构');
  const sessionId = await parser.getSessionId();
  
  // 多步骤交互
  const analysis = await builder.withSessionId(sessionId)
    .query('发现的主要问题是什么？')
    .asText();
  
  const plan = await builder.withSessionId(sessionId)
    .query('制定重构计划')
    .asText();
  
  return { sessionId, analysis, plan };
}

日志系统

SDK 提供了可插拔的日志系统：

自定义日志实现

class CustomLogger implements Logger {
  log(entry: LogEntry): void {
    // 实现自定义日志逻辑
    myLoggingService.send({
      level: entry.level,
      message: entry.message,
      timestamp: entry.timestamp
    });
  }
  
  // 实现其他日志级别方法...
}

// 使用自定义日志
claude()
  .withLogger(new CustomLogger())
  .query('...');

高级模式

重试逻辑

async function queryWithRetry(prompt: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await claude().query(prompt).asText();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
    }
  }
}

响应缓存

const cache = new Map();

async function cachedQuery(prompt: string) {
  const cacheKey = `${prompt}:${Date.now() / 60000 | 0}`; // 1分钟缓存
  
  if (cache.has(cacheKey)) return cache.get(cacheKey);
  
  const result = await claude().query(prompt).asText();
  cache.set(cacheKey, result);
  return result;
}

最佳实践建议

1. 会话管理：合理使用会话ID保持上下文连贯性
2. 错误处理：结合try-catch和内置的succeeded()方法
3. 工具控制：按需精确控制工具权限
4. 性能优化：对重复查询考虑实现缓存机制
5. 日志记录：生产环境建议配置详细的日志记录

Claude Code SDK TS 的 Fluent API 通过这种直观的链式调用方式，显著提升了开发效率，同时保持了足够的灵活性来处理各种复杂场景。无论是简单的问答交互还是复杂的代码分析工作流，这套API都能提供优雅的解决方案。