使用说明

Abi-个人财务助理

A. 基于隐私优先MCP的RAG AI代理 个人理财。Abi连接到您的实际预算数据，并使用与OpenAI兼容的LLM来回答问题、生成可视化、预测支出和管理预算，同时保持财务数据的本地性和安全性。

主要亮点：

🔒 隐私第一：在人工智能处理之前，对商户名称进行哈希处理；你的原始数据永远不会离开你的机器
🛠️ MCP工具调用：13个用于查询、分析和修改财务数据的专用工具
📊 本地RAG：在加密的SQLite数据库上检索增强生成
🤖 多模态：与GPT-4o、GPT-4o-mini、o4-mini或当地LLM（Ollama、LM Studio）配合使用

✅ 用户先决条件

要管理Abi，你需要一个 AI密钥 预算（从 实际预算).

1.实际预算（您的财务数据） Abi是一名助理实际预算，一款免费的私人本地预算应用程序。

获取应用：下载实际预算然后在你的机器上运行它。
连接:
- 服务器URL：使用您的本地URL（通常 http://localhost:5006).
- 同步ID首选设置 → 显示高级设置 在实际中找到这个。
- 密码：您的登录密码（如果已设置）。

2.OpenAI API密钥（头脑） Abi利用OpenAI的智能来理解你的问题。

注册地址： platform.openai.com.
增加5美元的信贷（Abi的运营成本很低，但需要一个资金账户）。
首选 API密钥 → 创建新密钥.
复制此密钥（以开头 sk-...).

🔧 代理工具

AI代理使用MCP风格的函数调用，并使用按功能组织的13个工具：

📖 读取（查询数据）

工具	说明
`get_account_balances`	获取所有账户和信用卡的当前余额
`get_spending_category`	一个月按类别分列的支出明细
`search_transactions`	按商家、类别或日期范围搜索交易
`get_monthly_budget`	获取预算金额与实际支出
`get_all_categories`	列出所有可用的预算类别
`detect_recurring_payments`	确定订阅和经常性费用

📊 分析（聚合和预测）

工具	说明
`generate_chart`	创建甜甜圈或条形图可视化
`simulate_purchase`	检查购买是否符合您的预算
`forecast_expenses`	根据历史模式预测未来支出

✏️ 写入（修改数据）

工具	说明
`update_category_budget`	设置或更新类别的预算金额
`create_transaction`	添加新交易（支出或收入）

🧠 规划与研究

工具	说明
`create_execution_plan`	将复杂的请求分解为分步计划
`web_search`	在网上搜索财务背景（利率、比较、建议）

🔒 隐私和安全

特性	描述
无云存储	所有财务数据都保存在您的计算机上的本地加密数据库中
商人面具	真实的商家名称被散列（例如，“星巴克”→ “Merchant_A1B2C3”），然后发送给AI。仅在最终显示中取消屏蔽。
数据库加密	使用SQLCipher加密和实际预算密码
本地图表	可视化在本地生成并嵌入为Base64图像
混合网络搜索	网络搜索仅用于一般知识——你的财务数字永远不会包含在查询中
无凭据记录	API密钥和密码从未记录或包含在AI上下文中
构建时清洁	构建脚本将删除 `.env` 和 `db.sqlite` 自动
用户数据隔离	在打包的应用程序中，用户数据存储在 `%AppData%/Abi Financial Assistant/`，与应用程序文件分开

🏗️ 建筑

该应用程序由四个在本地协同工作的主要组件组成：

前端（电子/反应）：提供聊天界面、设置管理和呈现交互式图表。
后端（Python/FastAPI）：管理人工智能上下文、执行MCP工具和编排工作流程的中央智能。
隐私保护（Python）：一个中间件层，在敏感数据（如商家名称）到达人工智能之前对其进行哈希处理，并为用户揭开其面纱。
数据桥（Node.js）：一种专门的服务，处理同步和SQLCipher加密，以安全地与您的实际预算数据进行通信。

🚀 先决条件

Python 3.13+ （通过管理 uv)
Node.js 18+
实际预算：正在运行的实例（本地或托管）和您的同步ID。
紫外线：快速Python包管理器(pip install uv).

🛠️ 安装

1.设置后端

导航到后端文件夹以安装依赖项：

cd backend
uv sync

2.设置网桥

导航到网桥文件夹：

cd bridge
npm install

3.设置前端

导航到前端文件夹：

cd frontend
npm install

4.环境配置

创建 .env 根目录中的文件(c:\Coding\Financial Assistant\).您也可以稍后通过配置这些设置 设置UI 在应用程序中。

# AI Provider
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=

# Actual Budget Configuration
ACTUAL_SERVER_URL=http://localhost:5006
ACTUAL_PASSWORD=your_password
ACTUAL_SYNC_ID=your_sync_id

🏃‍♂️ 用法

一键启动

该项目包括一个启动Python后端和Electron前端的启动器脚本。

# From root directory
node launch.js

手动启动（传统）

如果您更喜欢识别特定服务中的问题：

后端: cd backend && uv run server.py
前端: cd frontend && npm start

📦 配电楼

要创建独立的Windows安装程序，请执行以下操作：

# From root directory
node build.js

这将：

将Python后端构建为独立的 .exe
安装网桥依赖项
构建React前端
使用Electron Builder打包所有内容

输出：安装程序将在 frontend/dist-electron/.

🔌 API端点（后端）

POST /chat：与代理人互动。
GET /settings：检索当前配置（已屏蔽，未暴露任何秘密）。
POST /settings：更新API键或模型首选项。
POST /sync：从实际预算触发手动同步。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。