🚀 Data Agent SDK

可复用的数据 Agent 核心 SDK，兼容 @anthropic-ai/claude-agent-sdk，提供数据库适配、Agent 调度与 Supabase 存储能力

📖 目录

• 项目概述
• 核心特性
• 应用场景
• 安装指南
• 快速开始
• 模块架构
• 配置说明
• API 文档
• 示例项目
• 常见问题
• 贡献指南
• 许可证

🎯 项目概述

Data Agent SDK 是一个专为数据场景设计的智能 Agent 开发工具包，提供了完整的数据库连接管理、Agent 调度、以及 Supabase 云存储集成能力。该 SDK 完全兼容 Anthropic Claude Agent SDK，可以无缝集成到现有的 AI Agent 生态系统中。

🌟 主要亮点

• 🔌 多数据库支持: 原生支持 MySQL、PostgreSQL、SQL Server
• 🤖 智能 Agent 管理: 完整的 Agent 配置、注册和调度系统
• ☁️ 云端集成: 内置 Supabase 支持，轻松实现云端数据存储
• ⚡ 高性能缓存: 智能元数据和血缘关系缓存，提升查询效率
• 🔧 灵活扩展: 支持自定义数据库适配器和缓存策略
• 🛡️ 类型安全: 完全使用 TypeScript 编写，提供完整的类型定义

✨ 核心特性

数据库管理

• 统一接口: 为不同数据库提供统一的查询和管理接口
• 连接池管理: 自动管理数据库连接池，优化性能
• 智能缓存: 元数据和血缘关系缓存，减少重复查询
• SQL 分析: 内置 SQL 解析和优化建议
• 数据血缘: 自动分析和可视化数据血缘关系

Agent 系统

• 动态配置: 支持运行时 Agent 配置和更新
• 工具集成: 预置数据分析和可视化工具
• 变量系统: 灵活的 Agent 变量管理
• 分类管理: 按功能分类管理不同的 Agent

存储集成

• Supabase 支持: 一键集成 Supabase 作为 Agent 存储后端
• 本地存储: 内置内存存储，适合开发和小规模部署
• 自定义适配器: 支持自定义存储后端

🆕 路由扩展

• 本地路由扩展: 无需修改 SDK 源码即可添加自定义业务路由
• TypeScript 支持: 支持直接加载 .ts 源文件,无需编译 ✨
• 灵活集成: 支持认证、租户管理等业务逻辑扩展
• 完整依赖访问: 可访问 dbManager、agentManager、mcpManager
• 📖 详细文档: 本地路由扩展指南 | 快速开始

🎯 应用场景

📊 数据分析平台

• 构建智能数据分析系统
• 自动生成数据报表和可视化
• 支持自然语言查询数据

🔍 数据探索工具

• 快速了解新数据源结构
• 智能推荐相关表和字段
• 生成探索性查询

🤖 智能运维

• 数据库性能监控和分析
• 异常数据自动检测
• 数据质量评估

📈 商业智能

• 构建 BI Agent
• 自动化 KPI 计算
• 趋势分析和预测

🚀 安装指南

系统要求

• Node.js: >= 18.0.0
• TypeScript: >= 4.5 (推荐使用 TypeScript 项目)
• 操作系统: Windows、macOS、Linux

使用 npm 安装

# 安装主包
npm install @frankma4529/data-agent-sdk

# 安装数据库驱动 (根据需要选择)
npm install pg              # PostgreSQL
npm install mysql2          # MySQL
npm install mssql           # SQL Server

# 安装 Supabase 支持 (可选)
npm install @supabase/supabase-js

使用 yarn 安装

# 安装主包
yarn add @frankma4529/data-agent-sdk

# 安装数据库驱动
yarn add pg mysql2 mssql @supabase/supabase-js

使用 pnpm 安装

# 安装主包
pnpm add @frankma4529/data-agent-sdk

# 安装数据库驱动
pnpm add pg mysql2 mssql @supabase/supabase-js

验证安装

import { createDatabaseClient } from '@frankma4529/data-agent-sdk';

// 如果没有报错，说明安装成功
console.log('Data Agent SDK 安装成功！');

⚡ 快速开始

5 分钟上手体验

import {
  createDatabaseClient,
  AgentManager,
  AgentRegistry
} from '@frankma4529/data-agent-sdk';

async function quickStart() {
  // 1. 创建数据库客户端
  const dbClient = await createDatabaseClient({
    connections: [{
      id: 'my-database',
      name: '我的数据库',
      type: 'postgresql',
      config: {
        host: 'localhost',
        port: 5432,
        database: 'mydb',
        user: 'postgres',
        password: 'password'
      }
    }]
  });

  // 2. 创建 Agent 管理器
  const agentManager = new AgentManager(dbClient);

  // 3. 注册一个数据分析 Agent
  agentManager.registerAgent({
    id: 'data-analyst',
    name: '数据分析专家',
    description: '专业的数据分析 Agent',
    systemPrompt: '你是一个专业的数据分析师，帮助用户分析数据。',
    enabledTools: ['execute_sql', 'analyze_table', 'create_chart'],
    category: '数据分析',
    isDefault: true,
    enabled: true
  });

  // 4. 执行查询
  const result = await dbClient.query(
    'my-database',
    'SELECT COUNT(*) as total FROM users WHERE created_at >= $1',
    ['2024-01-01']
  );

  console.log(`查询结果: ${result.rows[0].total} 条记录`);

  // 5. 获取表结构
  const tables = await dbClient.listTables('my-database', 'public');
  console.log('数据库表:', tables.map(t => t.name));

  // 6. 清理资源
  await dbClient.close();
}

// 运行示例
quickStart().catch(console.error);

基础配置文件

创建 agent-config.js 文件：

// agent-config.js
export const agents = [
  {
    id: 'sql-expert',
    name: 'SQL 专家',
    description: '专业的 SQL 查询优化和分析',
    systemPrompt: `你是 SQL 专家，专注于：
1. 编写高效的 SQL 查询
2. 优化查询性能
3. 分析数据结构

当前连接: {{connectionName}}
数据库类型: {{dbType}}`,
    enabledTools: [
      'execute_sql',
      'analyze_table',
      'get_table_ddl',
      'list_tables'
    ],
    category: '数据库操作',
    isDefault: true,
    enabled: true,
    variables: [
      {
        name: 'max_rows',
        type: 'number',
        description: '查询结果最大行数',
        required: false,
        defaultValue: 1000
      }
    ]
  },
  {
    id: 'data-visualizer',
    name: '数据可视化专家',
    description: '创建数据图表和可视化报告',
    systemPrompt: '你专注于创建美观易懂的数据可视化图表。',
    enabledTools: [
      'execute_sql',
      'create_chart',
      'get_table_data'
    ],
    category: '数据可视化',
    isDefault: false,
    enabled: true
  }
];

🏗️ 模块架构

核心模块结构

src/
├── index.ts                    # 主入口文件
├── types.ts                    # 核心类型定义
├── database.ts                 # 数据库客户端工厂
├── agent-registry.ts           # Agent 注册表
├── agents.ts                   # Agent 工具函数
├── supabase-adapter.ts         # Supabase 适配器
└── internal/                   # 内部实现
    ├── agents/                 # Agent 管理
    │   ├── AgentManager.ts
    │   └── AgentService.ts
    ├── db/                     # 数据库管理
    │   ├── core/               # 核心数据库管理
    │   ├── connection/         # 连接管理
    │   ├── metadata/           # 元数据管理
    │   ├── query/              # 查询执行
    │   └── cache/              # 缓存服务
    └── shared/                 # 共享类型和工具

主要模块说明

🗄️ 数据库模块 (database)

提供统一的数据库访问接口，支持多种数据库类型。

import { createDatabaseClient } from '@frankma4529/data-agent-sdk';

const dbClient = await createDatabaseClient({
  connections: [/* 连接配置 */],
  cache: {
    enabled: true,
    ttlMs: 300000
  }
});

主要功能:

• 多数据库支持 (MySQL, PostgreSQL, SQL Server)
• 连接池管理
• 智能缓存系统
• SQL 查询执行
• 元数据管理
• 数据血缘分析

🤖 Agent 模块 (agents, agent-registry)

完整的 Agent 管理系统，支持 Agent 的注册、配置和调度。

import { AgentManager } from '@frankma4529/data-agent-sdk';

const agentManager = new AgentManager(dbClient);
agentManager.registerAgent({
  id: 'my-agent',
  name: '我的 Agent',
  // ... 其他配置
});

主要功能:

• Agent 注册和配置管理
• 动态 Agent 加载
• 工具集成和管理
• 变量系统
• 分类管理

☁️ Supabase 适配器 (supabase-adapter)

提供与 Supabase 云服务的无缝集成。

import { createSupabaseAgentStore } from '@frankma4529/data-agent-sdk';

const agentStore = await createSupabaseAgentStore({
  url: 'your-supabase-url',
  key: 'your-supabase-key'
});

主要功能:

• Agent 配置云端存储
• 自动同步机制
• 多环境支持
• 安全认证

⚙️ 配置说明

数据库连接配置

interface Connection {
  id: string;                              // 唯一标识
  name: string;                            // 显示名称
  type: 'mysql' | 'postgresql' | 'mssql'; // 数据库类型
  config: {
    host: string;                          // 主机地址
    port: number;                          // 端口号
    database: string;                      // 数据库名
    user: string;                          // 用户名
    password: string;                      // 密码
    ssl?: boolean | Record<string, any>;   // SSL 配置
  };
  isWarehouse?: boolean;                   // 是否为数据仓库
  workspaceId?: string;                    // 工作区 ID
}

缓存配置

interface CacheOptions {
  enabled?: boolean;      // 是否启用缓存 (默认: true)
  ttlMs?: number;         // 元数据缓存 TTL (默认: 5分钟)
  lineageTtlMs?: number;  // 血缘缓存 TTL (默认: 10分钟)
  preload?: boolean;      // 是否预加载
}

Agent 配置

interface AgentConfig {
  id: string;                     // Agent ID
  name: string;                   // 显示名称
  description: string;            // 描述信息
  systemPrompt: string;           // 系统提示词
  enabledTools: string[];         // 启用的工具列表
  category?: string;              // 分类
  variables?: AgentVariable[];    // 变量配置
  isDefault?: boolean;            // 是否为默认
  enabled?: boolean;              // 是否启用
}

环境变量配置

# Supabase 配置
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key

# Agent 模型配置
AGENT_MODEL_TIER=sonnet  # sonnet | opus | haiku | inherit

# 缓存配置
METADATA_CACHE_TTL=300000
LINEAGE_CACHE_TTL=600000
LINEAGE_CACHE_ENABLED=true

📚 API 文档

核心函数

createDatabaseClient(options)

创建数据库客户端实例。

import { createDatabaseClient } from '@frankma4529/data-agent-sdk';

const dbClient = await createDatabaseClient({
  connections: [/* 连接配置 */],
  cache: { /* 缓存配置 */ },
  impl: /* 自定义实现 (可选) */
});

AgentManager

Agent 管理器类。

import { AgentManager } from '@frankma4529/data-agent-sdk';

const manager = new AgentManager(dbClient, agentStore);

// 注册 Agent
manager.registerAgent(agentConfig);

// 获取 Agent
const agent = manager.getAgentConfig('agent-id');

// 获取默认 Agent
const defaultAgent = manager.getDefaultAgent();

AgentRegistry

Agent 注册表，用于内存中的 Agent 管理。

import { AgentRegistry } from '@frankma4529/data-agent-sdk';

const registry = new AgentRegistry();

// 预加载配置
await registry.preload({
  preloadFromFile: true,
  preloadPath: './agents.js'
});

// 注册 Agent
registry.register(agentConfig);

// 列出所有 Agent
const agents = registry.list({ enabledOnly: true });

数据库操作

// 基础查询
const result = await dbClient.query(
  'connection-id',
  'SELECT * FROM table WHERE id = $1',
  [123]
);

// 获取表列表
const tables = await dbClient.listTables('connection-id', 'schema');

// 获取表结构
const structure = await dbClient.getTableStructure('connection-id', 'schema', 'table');

// 分析血缘关系
const lineage = await dbClient.analyzeLineage('connection-id', 'schema', 'table', {
  direction: 'upstream',
  depth: 3
});

完整的 API 文档请参考: API.md

💡 示例项目

完整的数据分析应用

import {
  createDatabaseClient,
  AgentManager,
  createSupabaseAgentStore
} from '@frankma4529/data-agent-sdk';

class DataAnalyticsApp {
  private dbClient: any;
  private agentManager: AgentManager;

  async initialize() {
    // 1. 初始化数据库连接
    this.dbClient = await createDatabaseClient({
      connections: [
        {
          id: 'warehouse',
          name: '数据仓库',
          type: 'postgresql',
          config: {
            host: process.env.DB_HOST,
            port: parseInt(process.env.DB_PORT || '5432'),
            database: process.env.DB_NAME,
            user: process.env.DB_USER,
            password: process.env.DB_PASSWORD
          }
        }
      ],
      cache: {
        enabled: true,
        ttlMs: 300000,
        lineageTtlMs: 600000
      }
    });

    // 2. 初始化 Agent 存储
    const agentStore = await createSupabaseAgentStore();

    // 3. 创建 Agent 管理器
    this.agentManager = new AgentManager(this.dbClient, agentStore);

    // 4. 注册专用 Agent
    await this.registerAgents();

    console.log('数据分析应用初始化完成');
  }

  private async registerAgents() {
    // SQL 分析 Agent
    this.agentManager.registerAgent({
      id: 'sql-analyst',
      name: 'SQL 分析师',
      description: '专业的 SQL 查询分析和优化',
      systemPrompt: `你是 SQL 分析专家。
职责：
1. 分析用户查询需求
2. 生成高效 SQL 语句
3. 优化查询性能
4. 提供数据洞察

当前数据库: {{connectionName}}
Schema: {{schema}}`,
      enabledTools: [
        'list_schemas',
        'list_tables',
        'execute_sql',
        'analyze_table',
        'get_table_ddl'
      ],
      category: 'SQL 分析',
      isDefault: true,
      enabled: true
    });

    // 报表生成 Agent
    this.agentManager.registerAgent({
      id: 'report-generator',
      name: '报表生成器',
      description: '自动生成数据报表和可视化',
      systemPrompt: '你专注于创建数据报表和可视化图表。',
      enabledTools: [
        'execute_sql',
        'create_chart',
        'get_table_data'
      ],
      category: '报表分析',
      isDefault: false,
      enabled: true
    });
  }

  async analyzeData(query: string) {
    const defaultAgent = this.agentManager.getDefaultAgent();

    // 构建系统提示词
    const prompt = this.agentManager.buildSubagentSystemPrompt(
      defaultAgent,
      { connectionId: 'warehouse', schema: 'public' }
    );

    // 这里可以集成 Claude Agent SDK
    // 来处理自然语言查询并生成 SQL

    console.log('Agent 提示词:', prompt);
    return { message: '数据分析完成' };
  }

  async close() {
    await this.dbClient.close();
  }
}

// 使用示例
async function main() {
  const app = new DataAnalyticsApp();
  await app.initialize();

  // 执行数据分析
  const result = await app.analyzeData('查询最近30天的用户增长趋势');
  console.log(result);

  await app.close();
}

main().catch(console.error);

本地 Agent 配置示例

// config/agents.js
export const agents = [
  {
    id: 'data-explorer',
    name: '数据探索专家',
    description: '帮助用户快速了解和探索数据',
    systemPrompt: `你是数据探索专家。

当前连接: {{connectionName}}
数据库类型: {{dbType}}

主要职责：
1. 帮助用户了解数据库结构
2. 推荐相关表和字段
3. 生成探索性查询

工作流程：
1. 先列出可用的 schemas
2. 再列出主要的数据表
3. 分析表结构和关系
4. 提供数据探索建议`,
    enabledTools: [
      'list_schemas',
      'list_tables',
      'list_views',
      'get_table_ddl',
      'analyze_table',
      'get_table_data'
    ],
    category: '数据探索',
    isDefault: true,
    enabled: true,
    variables: [
      {
        name: 'exploration_depth',
        type: 'select',
        description: '探索深度',
        required: false,
        defaultValue: 'medium',
        options: ['shallow', 'medium', 'deep']
      }
    ]
  },
  {
    id: 'performance-analyst',
    name: '性能分析师',
    description: '数据库性能分析和优化',
    systemPrompt: `你是数据库性能分析专家。

专注于：
1. 查询性能分析
2. 索引优化建议
3. 表结构优化`,
    enabledTools: [
      'execute_sql',
      'analyze_table',
      'get_table_ddl'
    ],
    category: '性能分析',
    isDefault: false,
    enabled: true
  }
];

❓ 常见问题

安装相关

Q: 安装时出现依赖冲突怎么办？

A: 建议使用 npm install --force 或更新到最新版本的 Node.js。确保所有 peer dependencies 版本兼容。

Q: 是否必须安装所有数据库驱动？

A: 不需要。只需要安装你实际使用的数据库驱动即可。SDK 会自动检测可用的驱动。

使用相关

Q: 如何处理数据库连接池？

A: SDK 内置了连接池管理，会自动处理连接的创建、复用和销毁。你也可以通过自定义 IDatabaseManager 实现来管理连接池。

Q: 缓存数据如何更新？

A: 使用 invalidateMetadata() 和 invalidateTables() 方法来手动刷新缓存，或者等待 TTL 过期自动更新。

Q: 如何自定义 Agent 工具？

A: 通过实现 MCP (Model Context Protocol) 规范的工具，并在 Agent 配置中启用相应的工具名称。

性能相关

Q: 大数据量查询性能如何优化？

A:

1. 启用缓存机制减少元数据查询
2. 使用 limit 参数控制结果集大小
3. 合理设置查询超时时间
4. 考虑使用分页查询

Q: 内存占用过高怎么办？

A:

1. 调整缓存 TTL 时间
2. 及时调用 close() 释放资源
3. 定期清理不需要的连接

错误处理

Q: 数据库连接失败怎么办？

A:

1. 检查网络连接和防火墙设置
2. 验证数据库服务是否运行
3. 确认连接配置（主机、端口、用户名、密码）
4. 查看 SSL 配置是否正确

Q: Agent 执行失败如何调试？

A:

1. 检查 Agent 配置是否正确
2. 验证工具名称是否在 enabledTools 中
3. 查看系统提示词是否包含必要的上下文变量
4. 启用详细日志记录

🤝 贡献指南

我们欢迎所有形式的贡献！无论是 Bug 报告、功能请求还是代码贡献。

开发环境设置

# 克隆项目
git clone https://github.com/pisol314/1208-data-agent-sdk.git
cd 1208-data-agent-sdk

# 安装依赖
npm install

# 启动开发模式
npm run dev

# 运行测试
npm test

# 构建
npm run build

# 代码检查
npm run lint
npm run lint:fix

贡献流程

1. Fork 项目 到你的 GitHub 账户
2. 创建特性分支: git checkout -b feature/your-feature-name
3. 提交更改: git commit -m 'Add some feature'
4. 推送分支: git push origin feature/your-feature-name
5. 创建 Pull Request

代码规范

• 使用 TypeScript 进行开发
• 遵循 ESLint 规则
• 编写单元测试覆盖新功能
• 更新相关文档

提交信息规范

使用 Conventional Commits 规范：

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建工具或辅助工具的变动

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• Anthropic Claude Agent SDK - 提供了优秀的 Agent 框架基础
• Supabase - 提供了优秀的后端即服务
• 所有贡献者和用户的支持

📞 联系我们

• GitHub Issues: 提交问题
• Email: [email protected]
• 文档: 完整 API 文档