开源 Blade Agent SDK：构建多轮会话 AI Agent 的 TypeScript 利器

前言

在开发 Blade Code（一个类似 Claude Code 的 AI 编程助手）的过程中，我积累了大量关于多轮会话 Agent 的核心能力：会话管理、文件检查点、沙箱执行、上下文压缩、MCP 集成等。

这些能力不仅仅适用于 Coding Agent，而是所有多轮会话 AI Agent 的通用需求。于是我将这些核心模块从 Blade Code 中抽取出来，形成了独立的 Blade Agent SDK。

现在，无论你是想构建自己的 Coding Agent、对话机器人，还是自动化工作流，都可以直接使用这个 SDK，省去重复造轮子的时间。

GitHub 地址：https://github.com/echoVic/blade-agent-sdk

为什么要抽取成独立 SDK？

在开发 Blade Code 时，我发现市面上的 AI SDK（如 LangChain、Vercel AI SDK）在以下场景存在不足：

会话管理复杂 - 多轮对话的状态管理、历史恢复、会话分叉等场景缺乏开箱即用的支持
安全性考量不足 - Agent 执行代码时缺乏沙箱隔离，存在安全风险
文件操作不可逆 - Agent 修改文件后难以回滚，调试成本高
工具扩展繁琐 - 集成 MCP 等外部工具协议需要大量样板代码
长对话 Token 爆炸 - 缺乏智能的上下文压缩机制

这些问题我在 Blade Code 中都解决了，但代码和 CLI 应用耦合在一起。将它们抽取成独立 SDK 后，其他开发者可以直接复用这些经过实战验证的能力，而不需要从头实现。

核心特性

🔄 Send/Stream 分离模式

与传统的阻塞式 API 不同，Blade Agent SDK 采用 send/stream 分离模式：

import { createSession } from '@blade-ai/agent-sdk';

const session = await createSession({
  provider: { type: 'openai-compatible', apiKey: process.env.API_KEY },
  model: 'gpt-4o-mini',
});

// 1. 发送消息（非阻塞）
await session.send('帮我分析这段代码的性能问题');

// 2. 流式接收响应
for await (const msg of session.stream()) {
  switch (msg.type) {
    case 'content':
      process.stdout.write(msg.delta);
      break;
    case 'tool_use':
      console.log(`调用工具: ${msg.name}`);
      break;
    case 'tool_result':
      console.log(`工具结果: ${msg.output}`);
      break;
    case 'result':
      console.log('完成:', msg.subtype);
      break;
  }
}

session.close();

这种设计的优势：

更细粒度的控制 - 可以在发送和接收之间插入自定义逻辑
更好的用户体验 - 流式输出让用户实时看到 Agent 的思考过程
更灵活的错误处理 - 可以在流中捕获并处理各类事件

💾 会话恢复与分叉

在开发 Coding Agent 时，会话管理是核心需求。Blade Agent SDK 提供了完整的会话生命周期管理：

import { createSession, resumeSession, forkSession } from '@blade-ai/agent-sdk';

// 创建新会话
const session = await createSession({ provider, model });
console.log('会话 ID:', session.sessionId);

// 恢复已有会话
const resumed = await resumeSession({
  sessionId: 'existing-session-id',
  provider,
  model,
});

// 从特定消息点分叉会话
const forked = await session.fork({ messageId: 'msg-uuid-123' });
// 或从已存储的会话分叉
const forked2 = await forkSession({
  sessionId: 'existing-session-id',
  messageId: 'msg-uuid-456',
  provider,
  model,
});

会话分叉是一个强大的功能，它允许你：

从对话的任意节点创建分支，探索不同的解决方案
保留原始对话历史，同时独立演进新分支
实现类似 Git 的版本控制体验

🧠 分层记忆系统

Blade Agent SDK 内置了完整的分层上下文管理系统，参考 Claude Code 的设计：

三级存储架构：

内存层 (MemoryStore) - 当前会话的快速访问，支持 LRU 淘汰
缓存层 (CacheStore) - 热点数据缓存，带 TTL 过期机制
持久化层 (PersistentStore) - JSONL 格式持久化，跨会话保存

五层上下文结构：

interface ContextLayer {
  system: SystemContext;       // 系统角色、能力、工具
  session: SessionContext;     // 会话 ID、用户偏好、配置
  conversation: ConversationContext; // 消息历史、主题、摘要
  tool: ToolContext;           // 工具调用记录、状态
  workspace: WorkspaceContext; // 项目路径、文件、Git 信息
}

存储路径结构：

~/.blade/
├── projects/
│   ├── -Users-john-projects-my-app/  # 项目目录（路径转义）
│   │   ├── {sessionId}.jsonl          # 会话文件
│   │   └── ...
│   └── -Users-john-projects-other/
└── ...

这套记忆系统支持：

会话搜索 - 搜索历史会话
工具结果缓存 - 相同工具调用自动复用缓存结果
自动清理 - 超过 maxSessions 自动清理旧会话

🗜️ 智能上下文压缩

长对话场景下，Token 消耗是个大问题。SDK 内置了 CompactionService 实现智能压缩：

import { CompactionService } from '@blade-ai/agent-sdk';

// 当 Token 超过阈值（80%）时自动触发压缩
const result = await CompactionService.compact(messages, {
  trigger: 'auto',
  modelName: 'gpt-4o-mini',
  maxContextTokens: 128000,
});

console.log(`压缩前: ${result.preTokens} tokens`);
console.log(`压缩后: ${result.postTokens} tokens`);
console.log(`节省: ${((1 - result.postTokens / result.preTokens) * 100).toFixed(1)}%`);

压缩流程：

分析重点文件 - 提取对话中涉及的关键文件
生成智能总结 - 调用 LLM 生成结构化总结（包含技术决策、代码片段、错误修复等）
保留最近消息 - 保留最近 20% 的消息，确保上下文连贯
过滤孤儿消息 - 自动清理失去关联的 tool 消息

📁 文件检查点与回滚

这是 Blade Agent SDK 最实用的功能之一。当 Agent 修改文件时，SDK 会自动记录变更，支持一键回滚：

const session = await createSession({
  provider,
  model,
  enableFileCheckpointing: true, // 启用文件检查点
});

// Agent 执行文件操作
await session.send('请帮我重构 src/utils.ts 文件');
for await (const msg of session.stream()) {
  // 处理响应...
}

// 不满意？回滚到指定消息点
const result = await session.rewindFiles('user-message-uuid');
if (result.success) {
  console.log('已恢复文件:', result.restoredFiles);
  console.log('已删除新建文件:', result.deletedFiles);
}

// 查看检查点统计
const stats = session.getCheckpointStatistics();
console.log('检查点数量:', stats?.checkpointCount);
console.log('追踪文件数:', stats?.trackedFileCount);

工作原理：

每次用户发送消息时，SDK 创建一个检查点
Agent 修改文件前，SDK 自动保存文件快照
调用 rewindFiles() 时，SDK 将文件恢复到指定检查点的状态

🔒 沙箱执行

安全性是 Coding Agent 的重中之重。Blade Agent SDK 提供了 OS 级别的沙箱隔离：

const session = await createSession({
  provider,
  model,
  sandbox: {
    enabled: true,
    autoAllowBashIfSandboxed: true,
    allowUnsandboxedCommands: ['git', 'npm'], // 这些命令不走沙箱
    network: {
      allowLocalBinding: true, // 允许绑定本地端口
    },
  },
});

支持的沙箱技术：

Linux: Bubblewrap (bwrap) - 轻量级容器隔离
macOS: Seatbelt (sandbox-exec) - 系统内置沙箱

沙箱能够限制：

文件系统访问范围
网络访问权限
进程创建能力

🔌 MCP 集成

MCP (Model Context Protocol) 是 Anthropic 推出的工具协议标准。Blade Agent SDK 原生支持 MCP：

const session = await createSession({
  provider,
  model,
  mcpServers: {
    filesystem: {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@anthropic-ai/mcp-server-filesystem', '/path/to/workspace'],
    },
    github: {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@anthropic-ai/mcp-server-github'],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
    },
    // 支持 SSE 和 HTTP 类型
    remote: {
      type: 'sse',
      url: 'https://mcp-server.example.com/sse',
    },
  },
});

// 查看 MCP 服务器状态
const status = await session.mcpServerStatus();
console.log(status);

// 列出可用的 MCP 工具
const tools = await session.mcpListTools();
console.log('可用工具:', tools.map(t => t.name));

通过 MCP，你可以轻松集成：

文件系统操作
GitHub/GitLab 集成
数据库查询
浏览器自动化
以及任何符合 MCP 协议的工具

🪝 Hooks 系统

Hooks 允许你在 Agent 生命周期的特定点注入自定义逻辑：

const session = await createSession({
  provider,
  model,
  hooks: {
    enabled: true,
    PreToolUse: [
      {
        matcher: 'Bash', // 匹配 Bash 工具
        hooks: [
          {
            type: 'command',
            command: './scripts/validate-bash.sh',
            timeout: 10,
          },
        ],
      },
    ],
    PostToolUse: [
      {
        matcher: '*', // 匹配所有工具
        hooks: [
          {
            type: 'callback',
            callback: async (input) => {
              console.log('工具执行完成:', input.toolName);
              return { action: 'continue' };
            },
          },
        ],
      },
    ],
    Compaction: [
      {
        matcher: '*',
        hooks: [
          {
            type: 'callback',
            callback: async (input) => {
              // 可以阻止压缩或添加自定义逻辑
              return { blockCompaction: false };
            },
          },
        ],
      },
    ],
  },
});

支持的 Hook 事件：

PreToolUse / PostToolUse / PostToolUseFailure - 工具执行前后
SessionStart / SessionEnd - 会话开始/结束
UserPromptSubmit - 用户提交消息时
PermissionRequest - 权限请求时
Compaction - 上下文压缩时
SubagentStart / SubagentStop - 子 Agent 启停
TaskCompleted - 任务完成时
Stop / Notification - 停止和通知事件

🎯 自定义工具与 Agent

除了内置工具，你可以轻松定义自己的工具和子 Agent：

import { z } from 'zod';

// 自定义工具
const searchTool = {
  name: 'SearchDocs',
  description: '搜索项目文档',
  inputSchema: z.object({
    query: z.string().describe('搜索关键词'),
    limit: z.number().default(10).describe('返回结果数量'),
  }),
  execute: async (input, context) => {
    // 实现搜索逻辑
    const results = await searchDocuments(input.query, input.limit);
    return JSON.stringify(results);
  },
};

// 自定义 Agent（支持 Claude Code 格式）
const reviewerAgent = {
  name: 'code-reviewer',
  description: '代码审查专家，负责审查代码质量和安全性',
  systemPrompt: '你是一个资深的代码审查专家...',
  tools: ['Read', 'Grep', 'Glob'], // 限制可用工具
  color: 'blue', // UI 背景颜色
  permissionMode: 'default', // 权限模式
  skills: ['security-check'], // 自动加载的 skills
};

const session = await createSession({
  provider,
  model,
  tools: [searchTool],
  agents: [reviewerAgent],
});

🧩 插件系统

SDK 提供了完整的插件系统，支持扩展命令、Agent、Skills、Hooks 和 MCP 服务器：

import { PluginRegistry, PluginLoader } from '@blade-ai/agent-sdk';

// 插件目录结构
// .blade-plugin/
// ├── plugin.json          # 插件清单
// ├── commands/            # 自定义命令
// │   └── my-command.md
// ├── agents/              # 自定义 Agent
// │   └── my-agent.md
// ├── skills/              # 自定义 Skills
// │   └── my-skill/
// │       └── SKILL.md
// ├── hooks/               # Hooks 配置
// │   └── hooks.json
// └── .mcp.json            # MCP 服务器配置

// 加载插件
const registry = new PluginRegistry();
const result = await PluginLoader.discoverPlugins({
  projectDir: process.cwd(),
  userDir: '~/.blade/plugins',
});

for (const plugin of result.plugins) {
  console.log(`已加载插件: ${plugin.manifest.name}`);
  console.log(`  命令: ${plugin.commands.length}`);
  console.log(`  Agent: ${plugin.agents.length}`);
  console.log(`  Skills: ${plugin.skills.length}`);
}

插件清单 (plugin.json) 示例：

{
  "name": "my-awesome-plugin",
  "description": "一个示例插件",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "keywords": ["coding", "automation"],
  "bladeVersion": ">=0.1.0"
}

📋 Skills 系统

Skills 是动态 Prompt 扩展机制，允许 AI 根据用户请求自动调用专业能力：

<!-- ~/.blade/skills/security-audit/SKILL.md -->
---
name: security-audit
description: 对代码进行安全审计，检查常见漏洞和安全问题
allowedTools:
  - Read
  - Grep
  - Glob
argumentHint: <file_or_directory>
userInvocable: true
---

## 安全审计指南

你是一个安全专家，请对指定的代码进行安全审计...

Skills 特性：

Progressive Disclosure - 仅加载元数据到系统提示，节省 Token
工具访问限制 - 可限制 Skill 可用的工具
用户/AI 可调用 - 支持用户通过 /skill-name 调用或 AI 自动调用
多来源支持 - 用户级 (~/.blade/skills)、项目级 (.blade/skills)、内置

📐 Spec-Driven Development (SDD)

SDK 内置了规格驱动开发工具，支持从需求到实现的完整工作流：

import { SpecManager } from '@blade-ai/agent-sdk';

const specManager = new SpecManager(process.cwd());

// 创建新的功能规格
await specManager.createSpec('user-authentication', {
  description: '实现用户认证功能',
});

// 工作流阶段
// init → requirements → design → tasks → implementation → done

// 获取当前规格上下文
const context = await specManager.getSpecContext('user-authentication');
console.log('当前阶段:', context.phase);
console.log('任务进度:', context.taskProgress);

目录结构：

.blade/
├── specs/              # 权威规格（单一数据源）
├── changes/            # 活跃的变更提案
│   └── <feature>/
│       ├── proposal.md
│       ├── requirements.md
│       ├── design.md
│       ├── tasks.md
│       └── .meta.json
├── archive/            # 已完成的变更
└── steering/           # 全局治理文档
    ├── constitution.md
    ├── product.md
    ├── tech.md
    └── structure.md

📊 结构化输出

需要 Agent 返回特定格式的数据？使用结构化输出：

import { z } from 'zod';

const session = await createSession({
  provider,
  model,
  outputFormat: {
    type: 'json_schema',
    schema: z.object({
      summary: z.string().describe('分析摘要'),
      issues: z.array(z.object({
        severity: z.enum(['low', 'medium', 'high']),
        description: z.string(),
        suggestion: z.string(),
      })),
      confidence: z.number().min(0).max(1),
    }),
    name: 'CodeAnalysisResult',
    strict: true,
  },
});

🛠️ 丰富的内置工具

SDK 内置了大量实用工具：

文件操作：

Read - 读取文件内容
Write - 写入文件
Edit - 编辑文件（支持 diff/patch）

搜索工具：

Glob - 文件模式匹配
Grep - 内容搜索（基于 ripgrep）

Shell 工具：

Bash - 执行 Shell 命令
KillShell - 终止后台进程

Web 工具：

WebSearch - 网络搜索（支持多搜索引擎）
WebFetch - 抓取网页内容

任务管理：

TodoWrite - 任务列表管理
Task - 子任务执行

交互工具：

AskUserQuestion - 向用户提问

Notebook 工具：

NotebookEdit - Jupyter Notebook 编辑

快速上手

安装

npm install @blade-ai/agent-sdk
# 或
pnpm add @blade-ai/agent-sdk

最小示例

import { createSession } from '@blade-ai/agent-sdk';

const session = await createSession({
  provider: {
    type: 'openai-compatible',
    apiKey: process.env.OPENAI_API_KEY,
  },
  model: 'gpt-4o-mini',
});

await session.send('你好，介绍一下你自己');
for await (const msg of session.stream()) {
  if (msg.type === 'content') {
    process.stdout.write(msg.delta);
  }
}

session.close();

使用 TypeScript 自动清理

TypeScript 5.2+ 支持 using 语法自动清理资源：

await using session = await createSession({ provider, model });
// 作用域结束时自动调用 session.close()

一次性 Prompt

对于简单的单轮对话，使用 prompt 函数更方便：

import { prompt } from '@blade-ai/agent-sdk';

const result = await prompt('计算 2 + 2', {
  provider: { type: 'openai-compatible', apiKey: 'xxx' },
  model: 'gpt-4o-mini',
});

console.log(result.result);    // "4"
console.log(result.usage);     // { inputTokens: 10, outputTokens: 5, ... }
console.log(result.duration);  // 1234 (毫秒)

支持的模型提供者

Blade Agent SDK 支持多种模型提供者：

// OpenAI / OpenAI 兼容
{ type: 'openai-compatible', apiKey: 'xxx', baseUrl: 'https://api.openai.com/v1' }

// Anthropic Claude
{ type: 'anthropic', apiKey: 'xxx' }

// Google Gemini
{ type: 'gemini', apiKey: 'xxx' }

// Azure OpenAI
{ type: 'azure-openai', apiKey: 'xxx', baseUrl: 'xxx', apiVersion: '2024-02-15-preview' }

这意味着你可以使用：

OpenAI GPT 系列
Anthropic Claude 系列
Google Gemini 系列
Azure OpenAI
任何 OpenAI 兼容的 API（如 DeepSeek、Kimi、通义千问等）

运行环境要求

Node.js >= 20
TypeScript >= 5.2（可选，用于 using 自动清理语法）
Linux: Bubblewrap（可选，用于沙箱功能）
macOS: 内置 Seatbelt 支持

与其他 SDK 的对比

特性	Blade Agent SDK	LangChain	Vercel AI SDK
多轮会话管理	✅ 内置	需自行实现	需自行实现
会话恢复/分叉	✅ 内置	❌	❌
分层记忆系统	✅ 内置	需插件	❌
上下文压缩	✅ 智能压缩	需自行实现	❌
文件检查点	✅ 内置	❌	❌
沙箱执行	✅ OS 级别	❌	❌
MCP 集成	✅ 原生支持	需插件	需插件
Hooks 系统	✅ 完整	有限	有限
插件系统	✅ 完整	✅	❌
Skills 系统	✅ 内置	❌	❌
TypeScript	✅ 一等公民	✅	✅

适用场景

Blade Agent SDK 特别适合以下场景：

Coding Agent - 需要安全执行代码、管理文件变更
对话式 AI 应用 - 需要多轮对话、会话持久化
自动化工作流 - 需要集成多种外部工具
AI 开发平台 - 需要细粒度的权限控制和审计
长对话场景 - 需要智能上下文压缩
团队协作 - 需要插件和 Skills 扩展能力

总结

Blade Agent SDK 是我从 Blade Code 项目中抽取出来的核心能力集合。这些代码经过了实际项目的验证，不是纸上谈兵的设计。

它专注于解决多轮会话 Agent 开发中的核心痛点：

会话管理 - 恢复、分叉、持久化
记忆系统 - 分层存储、智能压缩
安全执行 - 沙箱隔离、权限控制
可逆操作 - 文件检查点、一键回滚
可扩展性 - MCP 集成、插件系统、Skills

如果你正在开发 AI Agent 应用，不妨试试 Blade Agent SDK，省去重复造轮子的时间。欢迎 Star、Issue 和 PR！