npm package: @frankma4529/data-agent-sdk
Description: 可复用的数据 Agent 核心 SDK，兼容 @anthropic-ai/claude-agent-sdk，提供数据库适配、Agent 调度与 Supabase 存储能力
Latest version: 0.1.11

# 🚀 Data Agent SDK

[![npm version](https://badge.fury.io/js/%40frankma4529%2Fdata-agent-sdk.svg)](https://badge.fury.io/js/%40frankma4529%2Fdata-agent-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg)](https://www.typescriptlang.org/)

> 可复用的数据 Agent 核心 SDK，兼容 @anthropic-ai/claude-agent-sdk，提供数据库适配、Agent 调度与 Supabase 存储能力

## 📖 目录

- [项目概述](#项目概述)
- [核心特性](#核心特性)
- [应用场景](#应用场景)
- [安装指南](#安装指南)
- [快速开始](#快速开始)
- [模块架构](#模块架构)
- [配置说明](#配置说明)
- [API 文档](#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
- **📖 详细文档**: [本地路由扩展指南](./docs/LOCAL_ROUTE_EXTENSIONS.md) | [快速开始](./docs/QUICK_START_EXTENSIONS.md)

---

## 🎯 应用场景

### 📊 数据分析平台
- 构建智能数据分析系统
- 自动生成数据报表和可视化
- 支持自然语言查询数据

### 🔍 数据探索工具
- 快速了解新数据源结构
- 智能推荐相关表和字段
- 生成探索性查询

### 🤖 智能运维
- 数据库性能监控和分析
- 异常数据自动检测
- 数据质量评估

### 📈 商业智能
- 构建 BI Agent
- 自动化 KPI 计算
- 趋势分析和预测

---

## 🚀 安装指南

### 系统要求

- **Node.js**: >= 18.0.0
- **TypeScript**: >= 4.5 (推荐使用 TypeScript 项目)
- **操作系统**: Windows、macOS、Linux

### 使用 npm 安装

```bash
# 安装主包
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 安装

```bash
# 安装主包
yarn add @frankma4529/data-agent-sdk

# 安装数据库驱动
yarn add pg mysql2 mssql @supabase/supabase-js
```

### 使用 pnpm 安装

```bash
# 安装主包
pnpm add @frankma4529/data-agent-sdk

# 安装数据库驱动
pnpm add pg mysql2 mssql @supabase/supabase-js
```

### 验证安装

```typescript
import { createDatabaseClient } from '@frankma4529/data-agent-sdk';

// 如果没有报错，说明安装成功
console.log('Data Agent SDK 安装成功！');
```

---

## ⚡ 快速开始

### 5 分钟上手体验

```typescript
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` 文件：

```javascript
// 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`)

提供统一的数据库访问接口，支持多种数据库类型。

```typescript
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 的注册、配置和调度。

```typescript
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 云服务的无缝集成。

```typescript
import { createSupabaseAgentStore } from '@frankma4529/data-agent-sdk';

const agentStore = await createSupabaseAgentStore({
  url: 'your-supabase-url',
  key: 'your-supabase-key'
});
```

**主要功能**:
- Agent 配置云端存储
- 自动同步机制
- 多环境支持
- 安全认证

---

## ⚙️ 配置说明

### 数据库连接配置

```typescript
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
}
```

### 缓存配置

```typescript
interface CacheOptions {
  enabled?: boolean;      // 是否启用缓存 (默认: true)
  ttlMs?: number;         // 元数据缓存 TTL (默认: 5分钟)
  lineageTtlMs?: number;  // 血缘缓存 TTL (默认: 10分钟)
  preload?: boolean;      // 是否预加载
}
```

### Agent 配置

```typescript
interface AgentConfig {
  id: string;                     // Agent ID
  name: string;                   // 显示名称
  description: string;            // 描述信息
  systemPrompt: string;           // 系统提示词
  enabledTools: string[];         // 启用的工具列表
  category?: string;              // 分类
  variables?: AgentVariable[];    // 变量配置
  isDefault?: boolean;            // 是否为默认
  enabled?: boolean;              // 是否启用
}
```

### 环境变量配置

```bash
# 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)`

创建数据库客户端实例。

```typescript
import { createDatabaseClient } from '@frankma4529/data-agent-sdk';

const dbClient = await createDatabaseClient({
  connections: [/* 连接配置 */],
  cache: { /* 缓存配置 */ },
  impl: /* 自定义实现 (可选) */
});
```

#### `AgentManager`

Agent 管理器类。

```typescript
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 管理。

```typescript
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 });
```

### 数据库操作

```typescript
// 基础查询
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](./API.md)

---

## 💡 示例项目

### 完整的数据分析应用

```typescript
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 配置示例

```javascript
// 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 报告、功能请求还是代码贡献。

### 开发环境设置

```bash
# 克隆项目
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](https://www.conventionalcommits.org/) 规范：

```
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建工具或辅助工具的变动
```

---

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

---

## 🙏 致谢

- [Anthropic Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk) - 提供了优秀的 Agent 框架基础
- [Supabase](https://supabase.com/) - 提供了优秀的后端即服务
- 所有贡献者和用户的支持

---

## 📞 联系我们

- **GitHub Issues**: [提交问题](https://github.com/pisol314/1208-data-agent-sdk/issues)
- **Email**: pisol314@example.com
- **文档**: [完整 API 文档](./API.md)

---

<p align="center">
  <strong>⭐ 如果这个项目对你有帮助，请给我们一个 Star！</strong>
</p>