内容
# Pagra AI - Starknet 钱包 API
一个用于 Starknet 钱包管理的全面 Node.js API，带有 Telegram 机器人集成和 MCP（模型上下文协议）聊天功能。
## 🚀 快速开始
### 前提条件
- Node.js（v16 或更高版本）
- npm 或 yarn
- Supabase 账户和项目
- Starknet RPC 端点访问
### 安装
1. **克隆并安装依赖：**
```bash
npm install
```
2. **环境设置：**
在根目录中创建一个 `.env` 文件，其中包含以下变量：
```env
# 服务器配置
PORT=3000
NODE_ENV=development
# Supabase 配置
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
# Starknet 配置
STARKNET_RPC_URL=your_starknet_rpc_url
STARKNET_NETWORK=sepolia
# Telegram 机器人（可选）
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# MCP 配置
ANTHROPIC_API_KEY=your_anthropic_api_key
# 安全
JWT_SECRET=your_jwt_secret_here
ENCRYPTION_KEY=your_32_byte_encryption_key
```
3. **数据库设置：**
- 从 `migrations/` 文件夹运行数据库迁移脚本
- 查看 `migrations/README.md` 以获取详细说明
### 运行应用程序
**开发模式（自动重新加载）：**
```bash
npm run dev
```
**生产模式：**
```bash
npm start
```
服务器将在 `http://localhost:3000` 启动
## 📁 项目结构
```
pagra-ai/
├── src/ # 源代码
│ ├── config/ # 配置文件
│ ├── helpers/ # 帮助函数和实用程序
│ ├── services/ # 服务层（Telegram 等）
│ └── server.js # 主服务器文件
├── tests/ # 测试文件和实用程序
│ ├── mocks/ # 测试模拟文件
│ ├── *.test.js # Jest 测试文件
│ ├── test-*.js # 手动测试脚本
│ └── README.md # 测试文档
├── migrations/ # 数据库迁移脚本
│ ├── *.sql # SQL 迁移文件
│ └── README.md # 迁移文档
├── docs/ # 文档
│ ├── telegram-setup.md # Telegram 机器人设置指南
│ ├── mcp-chat-example.md # MCP 聊天示例
│ ├── TEST_SCENARIOS.md # 测试场景
│ └── README.md # 文档索引
├── .env # 环境变量（创建此文件）
├── package.json
└── README.md # 此文件
```
## 🔗 API 端点
### 核心钱包操作
- `POST /api/start` - 创建新的钱包账户
- `POST /api/deploy_account` - 将钱包部署到 Starknet
- `POST /api/get_wallet_address` - 获取钱包地址
- `POST /api/get_balance` - 检查钱包余额
- `POST /api/transfer` - 转账
- `POST /api/get_transactions` - 获取交易历史
### 聊天和 AI 集成
- `POST /api/chat` - 使用 MCP 处理聊天消息
- `POST /api/chat/clear` - 清除对话历史
- `GET /api/chat/history/:phone_number` - 获取聊天历史
### Telegram 集成
- `POST /api/telegram/webhook` - Telegram webhook 端点
- `POST /api/telegram/set-webhook` - 设置 webhook URL
### 系统
- `GET /health` - 健康检查端点
- `GET /api-docs` - Swagger API 文档
## 🛠️ 可用脚本
- `npm run dev` - 使用 nodemon 启动开发服务器
- `npm start` - 启动生产服务器
- `npm test` - 运行 Jest 测试
- `npm run test:watch` - 以监视模式运行测试
- `npm run test:coverage` - 生成测试覆盖率报告
## 🧪 测试
该项目包含全面的测试：
- **自动化测试**：基于 Jest 的单元测试和集成测试
- **手动测试**：交互式测试脚本
- **Telegram 测试**：机器人集成测试
- **MCP 测试**：聊天功能测试
查看 `tests/README.md` 以获取详细测试说明。
## 🗄️ 数据库
该项目使用 Supabase PostgreSQL，包含：
- **用户表**：钱包和用户信息
- **交易表**：转账历史和状态
- **行级安全性**：安全数据访问
- **帮助函数**：数据库实用程序
查看 `migrations/README.md` 以获取数据库设置说明。
## 🤖 功能
### 钱包管理
- ✅ 创建 Starknet 钱包
- ✅ 将账户部署到网络
- ✅ 在钱包之间转账
- ✅ 检查余额和交易历史
- ✅ 安全私钥加密
### Telegram 机器人
- ✅ 通过 Telegram 进行交互式钱包操作
- ✅ 开发模式下的轮询
- ✅ 生产模式下的 webhook
- ✅ 自然语言命令
### AI 聊天集成
- ✅ MCP（模型上下文协议）支持
- ✅ 上下文感知对话
- ✅ 钱包操作的工具集成
- ✅ 对话历史管理
### 安全
- ✅ 基于 PIN 的身份验证
- ✅ 私钥加密
- ✅ 速率限制
- ✅ 输入验证
- ✅ 行级安全性（RLS）
## 🔧 依赖
### 核心
- **Express** - Web 框架
- **Supabase** - 数据库和后端服务
- **Starknet.js** - Starknet 区块链集成
### 安全和中间件
- **CORS** - 跨源资源共享
- **Helmet** - 安全中间件
- **Morgan** - HTTP 请求日志记录
- **express-rate-limit** - 速率限制
### 集成
- **node-telegram-bot-api** - Telegram 机器人集成
- **@anthropic-ai/sdk** - Claude AI 集成
- **swagger-ui-express** - API 文档
### 开发
- **Nodemon** - 开发自动重新加载
- **Jest** - 测试框架
- **Dotenv** - 环境变量管理
## 📚 文档
在 `docs/` 文件夹中提供全面的文档：
- **Telegram 设置**：完整的机器人集成指南
- **MCP 聊天示例**：AI 聊天功能示例
- **测试场景**：测试策略和程序
## 🚨 重要安全注意事项
1. **永远不要将 `.env` 文件提交**到版本控制
2. **使用强加密密钥**（最小 32 字节）
3. **在 Supabase 中启用 RLS 策略**
4. **在处理前验证所有用户输入**
5. **在生产环境中使用 HTTPS**
6. **定期轮换 API 密钥**和秘密
## 🆘 故障排除
### 常见问题
- **Supabase 连接**：检查环境变量和项目状态
- **Starknet RPC 错误**：验证 RPC URL 和网络配置
- **Telegram 机器人问题**：确保机器人令牌有效且 webhook 已设置
- **数据库权限**：运行 `migrations/fix-permissions.sql`
### 获取帮助
1. 查看 `docs/` 中的相关文档
2. 查看 `tests/` 中的测试文件以获取示例
3. 验证环境配置
4. 检查服务器日志以获取详细的错误消息
## 🔄 开发工作流程
1. **设置**：按照安装说明进行操作
2. **数据库**：从 `migrations/` 运行迁移
3. **测试**：使用 `tests/` 中的测试脚本
4. **文档**：在添加功能时更新相关文档
5. **部署**：使用生产环境变量
## 📈 下一步
1. 使用迁移脚本设置 Supabase 数据库
2. 配置 Telegram 机器人（可选）使用 `docs/telegram-setup.md`
3. 使用提供的测试脚本测试 API 端点
4. 根据需要实施其他功能
5. 部署到生产环境
