内容
# 口袋智能 — 自主多智能体金融智能平台
<p align="center">
<img src="https://img.shields.io/badge/Vercel-Live_Demo-black?style=for-the-badge&logo=vercel&logoColor=white" alt="Vercel部署" />
<img src="https://img.shields.io/badge/GitHub-仓库-blue?style=for-the-badge&logo=github&logoColor=white" alt="GitHub仓库" />
<img src="https://img.shields.io/badge/许可证-CC_BY_4.0-lightgrey?style=for-the-badge" alt="许可证：CC-BY-4.0" />
<img src="https://img.shields.io/badge/Gemini_2.5_Flash-centralized_AI-green?style=for-the-badge&logo=googlegemini&logoColor=white" alt="Gemini驱动" />
</p>
### 🌐 生产环境网址： **[pocketsense-ai-capstoneproject.vercel.app](https://pocketsense-ai-capstoneproject.vercel.app)**
### 📂 GitHub仓库： **[github.com/mohin-2007/PocketSense-AI](https://github.com/mohin-2007/PocketSense-AI)**
---
## 🏆 Kaggle & Google：Vibecoding Agents - 毕业设计蓝图
口袋智能是一款为Kaggle上的**Vibecoding Agents - 毕业设计**竞赛而打造的生产级自主多智能体金融智能平台。
它不仅仅是一个简单的消费跟踪器，而是一个由9个专业智能体、12个模型上下文协议（MCP）工具、Gemini智能和集中式恢复层驱动的**金融操作系统**。
---
## 💡 关键架构亮点（为什么它能获胜）
### 1. 🤖 多智能体路由器框架
我们的自定义路由引擎（`api/agent.js`）解析自然语言输入，并通过一组专业智能体执行。例如：
> **用户提示**： *"我下个月能负担得起一台MacBook Air（$999）吗？*
>
> **编排流程**：
> ```
> [路由器智能体]
> ├───→ [预测智能体]（使用历史回归预测下个月的净现金流）
> ├───→ [风险智能体]（检查$999交易是否触发预算超额）
> ├───→ [目标智能体]（评估对活跃储蓄目标的影响）
> └───→ [顾问智能体]（聚合报告并返回结构化的财务建议）
> ```
> **AI财务副驾驶对话预览**：
> 
### 2. 🔌 模型上下文协议（MCP）集成
一个完全符合MCP标准的服务器（`mcp-server.js`）公开了**12种金融工具**，具有严格的模式验证，允许第三方工具（如Cursor、Claude Desktop或Windsurf）直接连接到口袋智能数据库。
### 3. 🛡️ 集中式AI网关（零故障演示模式）
在现场演示中，速率限制（429）或超时（500）可能会破坏演示。为了应对这种情况，`utils/gemini.js`拦截所有对Gemini的调用，并强制执行：
* **指数退避**：进行最多3次的渐进延迟重试。
* **超时保护**：将请求限制在8秒的执行窗口内。
* **离线备用模式**：如果Gemini无法访问或演示模式被切换，则回落到本地规则引擎，以输出丰富的、上下文感知的金融遥测数据，实现100％的正常运行时间。
* **Vercel存储备用**：使用可写的`/tmp`缓冲区动态绕过Vercel的只读文件系统（`EROFS`），确保数据库写入在无服务器边缘干净地工作。
### 👩⚖️ 4. 一键裁判控制台
设计用于让裁判在**60秒内**评估平台：
* **自动演示循环**：立即触发完整的演练（切换选项卡、提交查询、测试预算触发器、OCR扫描和生成CFO执行报告）。
* **实时路由地图**：以图形方式突出显示路由路径和实时活动管道节点。
* **遥测监视器**：显示所有智能体和工具的响应延迟和成功率。
---
## 🏗️ 系统架构
```mermaid
graph TD
User([用户查询 / UI交互]) --> Router[路由器智能体]
Router -->|意图：支出| ExpenseAgent[支出智能体]
Router -->|意图：预算| BudgetAgent[预算智能体]
Router -->|意图：预测| ForecastAgent[预测智能体]
Router -->|意图：风险| RiskAgent[风险智能体]
Router -->|意图：目标| GoalAgent[目标智能体]
Router -->|意图：收据| ReceiptAgent[收据视觉智能体]
Router -->|意图：建议| AdvisorAgent[顾问智能体]
Router -->|意图：报告| CFOAgent[CFO执行智能体]
ExpenseAgent --> MCP[MCP工具运行器 / 数据库]
BudgetAgent --> MCP
ForecastAgent --> MCP
RiskAgent --> MCP
GoalAgent --> MCP
ReceiptAgent --> MCP
AdvisorAgent --> MCP
CFOAgent --> MCP
MCP --> JSON_DB[(JSON数据库引擎 /tmp)]
JSON_DB --> Backups[(带时间戳的备份)]
```
## 📸 现场平台预览
### 📊 1. 个人CFO概览仪表盘
该指挥中心显示实时财务健康状况、预算节奏、资产配置和预测支出曲线。
### 👩⚖️ 2. 专用裁判控制台
我们的自动评估合规记分卡。运行完整的45秒平台演示循环，跟踪所有9个智能体的延迟遥测，并记录现场MCP工具调用。
---
## ⚙️ 公开的MCP工具
该系统通过JSON-RPC公开了**12种金融工具**：
| 工具名称 | 参数 | 目的 |
| :--- | :--- | :--- |
| `addExpense` | `amount`, `category`, `description`, `date` | 记录新交易 |
| `updateExpense` | `id`, `updates` | 修改交易记录 |
| `deleteExpense` | `id` | 删除交易 |
| `getExpenses` | 无 | 检索交易历史 |
| `setBudget` | `category`, `limit` | 设置预算限制 |
| `getBudget` | 无 | 获取活动预算 |
| `generateInsights` | 无 | 提取财务健康评分和提示 |
| `forecastSpending` | 无 | 运行回归支出预测 |
| `analyzeRisk` | 无 | 审计预算偏差 |
| `createGoal` | `name`, `target`, `deadline` | 跟踪储蓄目标 |
| `getGoals` | 无 | 读取目标列表 |
| `scanReceipt` | `imageUrl` 或 `base64` | 使用Gemini多模态OCR提取收据图像 |
---
## 📂 项目目录结构
```
├── api/
│ ├── agent.js # 主要编排器（意图路由和工具调用调度器）
│ ├── expense.js # 支出REST API CRUD
│ ├── budget.js # 预算REST API CRUD
│ ├── summary.js # 图表计算的REST API GET
│ ├── advisor.js # 健康评分和储蓄提示的REST API GET
│ ├── receipt.js # 视觉OCR上传的REST API POST
│ ├── cfo.js # 执行CFO报告编译的REST API GET
│ ├── forecast.js # 预测支出指标的REST API GET
│ ├── goal.js # 目标的REST API CRUD
│ ├── risk.js # 预算审计警报的REST API GET
│ ├── health.js # 跟踪代理指标和切换演示模式的REST API
│ └── mcp.js # 无服务器HTTP JSON-RPC MCP工具运行器
│
├── utils/
│ ├── db.js # JSON数据库驱动程序（读写、备份、Vercel上的/tmp备用）
│ ├── storage.js # 映射JSON文件逻辑的CRUD接口
│ ├── gemini.js # 具有重试/退避和离线备用的集中式Gemini网关
│ ├── helpers.js # 输入净化器、速率限制器、错误响应器
│ ├── health.js # 健康遥测日志管理器和统计计算器
│ └── tools.js # 具有自动双重写入重试的执行逻辑
│
├── data/
│ ├── expenses.json # 种子交易数据库
│ ├── budgets.json # 种子预算限制数据库
│ ├── receipts.json # 收据扫描器历史日志
│ ├── settings.json # 应用程序配置数据库
│ ├── health.json # 持久化代理指标和工具历史
│ └── backups/ # 带时间戳的快照备份文件夹
│
├── public/
│ ├── index.html # Glassmorphism HTML结构，添加裁判模式控制台选项卡
│ ├── style.css # 高级暗黑主题样式表，带有发光节点和滑块
│ └── app.js # 状态控制器、轮询、聊天恢复和自动演示循环
│
├── mcp-server.js # 标准输入/输出MCP服务器CLI
├── test_resilience.js# 用于检查重试循环和故障转移触发器的自动化测试脚本
├── test_endpoints.js # 自动化端点验证脚本
├── vercel.json # 部署路由器配置
└── package.json # 依赖和脚本
```
---
## 🔧 安装和本地设置
### 先决条件
* Node.js（v18+）
* npm或yarn
### 步骤
1. 克隆仓库：
```bash
git clone https://github.com/mohin-2007/PocketSense-AI.git
cd PocketSense-AI
```
2. 安装依赖：
```bash
npm install
```
3. 在根目录的`.env`文件中设置环境变量：
```env
GEMINI_API_KEY=your_gemini_api_key_here
```
4. 使用Vercel开发模拟器在本地运行：
```bash
npx vercel dev
```
*在本地打开 `http://localhost:3000` 以与平台交互。*
---
## 🧪 全面的验证套件
使用以下测试脚本在本地验证架构的所有方面：
* **API端点审计**：
```bash
node test_endpoints.js
```
*审计所有14个REST和无服务器端点，以确保200 OK响应。*
* **网关故障转移和恢复测试**：
```bash
node test_resilience.js
```
*模拟配额限制（429错误）并验证指数退避重试和离线恢复。*
* **多智能体路由器测试**：
```bash
node test_agents.js
```
*验证连接、提示和所有9个智能体的JSON输出。*
* **数据库和驱动器测试**：
```bash
node test_storage.js
```
*验证CRUD文件读取/写入、模式和备份快照创建。*
* **视觉OCR测试**：
```bash
node test_receipts.js
```
*验证模拟收据图像上的多模态OCR解析。*
---
## 🤝 第三方MCP客户端配置
### Claude Desktop集成
将以下服务器块添加到Claude Desktop配置文件中：
* **Windows**： `%APPDATA%\Claude\claude_desktop_config.json`
* **Mac**： `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"pocketsense-ai": {
"command": "node",
"args": ["/absolute/path/to/PocketSense-AI/mcp-server.js"],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
}
}
}
}
```
### Cursor编辑器集成
1. 进入 **设置** > **功能** > **MCP**。
2. 点击 **+ 添加新的MCP服务器**。
3. 填写详细信息：
* **名称**：口袋智能
* **类型**：`stdio`
* **命令**：`node "/absolute/path/to/PocketSense-AI/mcp-server.js"`
4. 保存并确保状态圆圈变为绿色。
---
## 📄 许可证
该项目双重许可于 **MIT许可证** 和 **知识共享署名4.0国际（CC-BY 4.0）** — 完全符合Google × Kaggle官方竞赛指南。有关详细信息，请参见 [LICENSE](LICENSE) 文件。
