Agent Tool Kit

基于 LangChain 1.0 TypeScript 的智能代理工具包，提供任务规划、代码编辑和文件管理等强大功能。

🎉 全新升级：现已支持 LangChain 1.0 的最新特性！

🚀 核心功能

• 智能任务代理 (MainAgent)：理解工作空间结构，智能规划和执行开发任务
• 代码编辑代理 (CodeEditAgent)：基于任务信息自动编辑和创建代码文件
• 文件管理工具：读取目录结构、文件内容、搜索文件
• 对话持久化：基于 LangGraph Checkpointer 的会话管理
• 结构化输出：使用 Zod Schema 确保输出格式一致性
• 多模型支持：支持 OpenAI、Anthropic Claude、Google Gemini 等

📦 安装

# 使用 npm
npm install agent-tool-kit

# 使用 pnpm
pnpm add agent-tool-kit

# 使用 yarn
yarn add agent-tool-kit

依赖说明

本工具包已内置以下依赖，无需额外安装：

• @langchain/core - LangChain 核心库
• @langchain/langgraph - LangGraph 状态管理
• @langchain/langgraph-checkpoint-sqlite - SQLite 持久化
• @langchain/anthropic - Anthropic Claude 模型支持
• @langchain/openai - OpenAI 模型支持
• langchain - LangChain 主库
• codes-command-tool - 文件操作工具
• zod - Schema 验证

🛠️ 快速开始

1. 创建主代理 (MainAgent)

MainAgent 是主要的任务规划和执行代理，能够理解工作空间并执行开发任务。

import { createMainAgent } from 'agent-tool-kit';

// 创建代理实例
const agent = await createMainAgent({
  workspacePath: '/path/to/your/project',  // 工作空间路径
  keyFiles: ['README.md', 'package.json'], // 关键文件列表
  threadId: 'session-1',                   // 会话 ID
});

// 执行任务
const result = await agent.run("帮我创建一个 React 组件");
console.log(result);

2. 使用代码编辑代理 (CodeEditAgent)

CodeEditAgent 专门用于代码编辑任务，可以添加、修改文件。

import { createCodeEditAgent } from 'agent-tool-kit';

const codeAgent = await createCodeEditAgent({
  workspacePath: '/path/to/your/project',
  taskInfo: {
    id: 'task-1',
    target: '创建一个用户登录组件',
    expectedResult: '包含用户名和密码输入框的登录表单',
    tools: 'React, TypeScript',
  },
});

const result = await codeAgent.run("请实现这个登录组件");

// 处理结构化输出
if (result.structuredResponse?.codeEditBlocks) {
  for (const block of result.structuredResponse.codeEditBlocks) {
    console.log(`${block.type}: ${block.filePath}`);
  }
}

3. 启用对话历史持久化

使用 LangGraph 的 Checkpointer 实现对话历史持久化：

import { createMainAgent } from 'agent-tool-kit';
import { SqliteSaver } from '@langchain/langgraph-checkpoint-sqlite';

// 创建 SQLite checkpointer
const checkpointer = SqliteSaver.fromConnString('./.agent-history.sqlite');

const agent = await createMainAgent({
  checkpointer,
  threadId: 'user-alice',
});

// 第一次对话
await agent.run("我的项目需要添加用户认证功能");

// 第二次对话 - 代理会记住之前的上下文
await agent.run("请继续完成这个功能");

4. 多会话管理

import { createMainAgent } from 'agent-tool-kit';
import { SqliteSaver } from '@langchain/langgraph-checkpoint-sqlite';

const checkpointer = SqliteSaver.fromConnString('./sessions.sqlite');

// 会话 1
const agent1 = await createMainAgent({
  checkpointer,
  threadId: 'project-a',
});
await agent1.run("为项目 A 创建 API 接口");

// 会话 2
const agent2 = await createMainAgent({
  checkpointer,
  threadId: 'project-b',
});
await agent2.run("为项目 B 创建数据库模型");

// 切换会话
agent1.setThreadId('project-a');
await agent1.run("继续完成 API 接口");

📋 API 文档

createMainAgent(options)

创建主代理实例。

参数 - MainAgentOptions:

| 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | workspacePath | string | process.cwd() | 工作空间路径 | | keyFiles | string[] | ['README.md', 'package.json'] | 关键文件列表 | | threadId | string | 'default' | 会话线程 ID | | checkpointer | BaseCheckpointSaver | - | 对话历史持久化实例 | | model | any \| string | claude-sonnet-4-5 | 使用的模型 |

返回值: Promise<Agent>

createCodeEditAgent(options)

创建代码编辑代理实例。

参数 - CodeEditAgentOptions:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | taskInfo | TaskInfo | ✅ | 任务信息 | | workspacePath | string | - | 工作空间路径 | | keyFiles | string[] | - | 关键文件列表 | | threadId | string | - | 会话线程 ID | | checkpointer | BaseCheckpointSaver | - | 对话历史持久化实例 | | model | string | - | 使用的模型 |

TaskInfo 结构:

interface TaskInfo {
  id: string;           // 任务 ID
  target: string;       // 任务目标
  expectedResult: string; // 预期结果
  tools: string;        // 使用的工具
}

返回值: Promise<Agent>

Agent 类方法

run(message: string): Promise<any>

执行任务并返回结果。

const result = await agent.run("创建一个新组件");

getThreadId(): string

获取当前线程 ID。

const threadId = agent.getThreadId();
console.log(`Current thread: ${threadId}`);

setThreadId(threadId: string): void

设置新的线程 ID，用于切换会话。

agent.setThreadId('new-session');

getCheckpointer(): BaseCheckpointSaver | null

获取 checkpointer 实例。

const checkpointer = agent.getCheckpointer();

🔧 内置工具

文件管理工具 (contextTools)

readDirectoryStructureTool

读取目录结构。

// 代理内部调用
await readDirectoryStructureTool.invoke({
  directoryPath: './src'
});

readFileContentTool

读取文件内容。

// 代理内部调用
await readFileContentTool.invoke({
  filePath: './package.json'
});

searchFilesTool

搜索文件（按名称或内容）。

// 按文件名搜索
await searchFilesTool.invoke({
  query: 'component',
  type: 'name'
});

// 按文件内容搜索
await searchFilesTool.invoke({
  query: 'useState',
  type: 'content'
});

任务执行工具 (taskRunnerTool)

执行软件开发任务，自动处理代码编辑操作。

📊 数据结构

Task (任务信息)

interface Task {
  id: string;                           // 任务唯一标识
  title: string;                        // 任务标题
  description: string;                  // 任务详细描述
  priority: 'high' | 'medium' | 'low'; // 优先级
  dependencies?: string[];              // 依赖的任务 ID 列表
}

ExecutionStep (执行步骤)

interface ExecutionStep {
  id: string;              // 步骤唯一标识
  taskId: string;          // 所属任务 ID
  stepNumber: number;      // 步骤序号
  title: string;           // 步骤标题
  description: string;     // 步骤详细描述
  estimatedTime?: string;  // 预估时间
  resources?: string[];    // 所需资源列表
}

DecompositionResult (分解结果)

interface DecompositionResult {
  originalRequirement: string;  // 用户原始需求
  tasks: Task[];               // 拆解出的任务列表
  steps: ExecutionStep[];      // 所有执行步骤列表
}

🎯 使用场景

场景 1: 智能项目助手

const agent = await createMainAgent({
  workspacePath: './my-project',
});

await agent.run(`
  我需要为这个项目添加以下功能：
  1. 用户认证系统
  2. 数据库集成
  3. API 接口
  请帮我规划任务
`);

场景 2: 代码重构助手

const agent = await createCodeEditAgent({
  taskInfo: {
    id: 'refactor-1',
    target: '重构用户模块',
    expectedResult: '提高代码可维护性',
    tools: 'TypeScript, ESLint',
  },
});

await agent.run("请重构 src/user 目录下的代码");

场景 3: 文档生成

const agent = await createMainAgent({
  workspacePath: './my-project',
  keyFiles: ['README.md', 'package.json', 'tsconfig.json'],
});

await agent.run("根据代码生成 API 文档");

🔧 开发指南

本地开发

# 克隆仓库
git clone https://github.com/your-repo/agent-tool-kit.git
cd agent-tool-kit

# 安装依赖
pnpm install

# 开发模式（自动重编译）
pnpm dev

# 构建项目
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 格式化代码
pnpm format

环境配置

创建 .env 文件并配置相应的 API 密钥：

# Anthropic Claude (默认使用)
ANTHROPIC_API_KEY=your_anthropic_api_key

# OpenAI (可选)
OPENAI_API_KEY=your_openai_api_key

# Google Gemini (可选)
GOOGLE_API_KEY=your_google_api_key

🌟 技术特性

LangChain 1.0 集成

• 工具化架构: 基于 LangChain 1.0 的 tool 函数
• 标准化模型接口: 统一的模型调用方式
• 结构化输出: 使用 Zod Schema 验证
• ReactAgent: 基于 createAgent API 构建

LangGraph Checkpointer

• 自动状态保存: 每一步都自动保存状态
• 线程隔离: 不同线程之间完全独立
• 故障恢复: 支持中断后恢复
• SQLite 存储: 轻量级、可靠的持久化方案

文件操作增强

• 智能目录读取: 自动忽略 node_modules、dist 等目录
• 文件内容搜索: 支持按名称和内容搜索
• 二进制文件支持: 自动处理 Base64 编码

🔍 工作原理

MainAgent 工作流程

graph LR
    A[用户输入] --> B[MainAgent]
    B --> C[读取工作空间]
    B --> D[分析关键文件]
    B --> E[调用工具]
    E --> F[taskRunnerTool]
    E --> G[readDirectoryStructureTool]
    E --> H[readFileContentTool]
    F --> I[CodeEditAgent]
    I --> J[生成代码编辑块]
    J --> K[执行文件操作]
    K --> L[返回结果]

CodeEditAgent 工作流程

graph LR
    A[任务信息] --> B[CodeEditAgent]
    B --> C[分析任务]
    C --> D[读取相关文件]
    D --> E[生成编辑方案]
    E --> F[结构化输出]
    F --> G[edit/add/error]

📄 许可证

MIT License - 详见 LICENSE

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献指南：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📚 相关文档

• LangChain 1.0 文档
• LangGraph 文档
• TypeDoc API 文档

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 更新日志

注意事项:

1. 使用前请确保已正确配置对应模型提供商的 API 密钥
2. 首次运行时会下载必要的依赖，请确保网络连接正常
3. 建议在生产环境中设置适当的错误处理和重试机制
4. SQLite checkpointer 文件会保存在指定路径，请注意文件权限
5. 代码编辑操作会直接修改文件，建议在使用前做好版本控制

系统要求:

• Node.js >= 20.0.0
• TypeScript >= 5.0.0
• 支持 ESM 模块

性能建议:

• 对于大型项目，建议限制 keyFiles 的数量
• 使用 searchFilesTool 时注意搜索范围
• 定期清理 SQLite checkpointer 文件以释放磁盘空间