# QuidClaw

零门槛私人 CFO — Claude Code Plugin，基于 Beancount 复式记账。

*本地优先。隐私至上。你的数据永远不会离开你的电脑。*

QuidClaw 是一个开源的 [Claude Code Plugin](https://docs.anthropic.com/en/docs/claude-code/plugins)，让 AI 成为你的私人财务管家。不需要任何财务基础——你只管用大白话说，AI 会帮你把账记得清清楚楚。底层使用 [Beancount](https://beancount.github.io/) 复式记账引擎，专业级的账务处理，但你完全不需要懂会计。

> **"午饭花了45，微信付的"** → AI 自动记账 → 正确的复式记账分录写入你的本地账本。

[English / 英文文档](README.md)

## 为什么选择 QuidClaw

- **隐私优先** — 所有数据以纯文本形式存储在本地。没有服务器，没有云端，没有遥测。一切都不会离开你的电脑。
- **数据由你掌控** — 标准的 Beancount `.bean` 文件，你可以直接阅读、编辑、用 Git 管理。没有厂商锁定，没有私有格式。
- **零门槛** — 不需要任何财务知识。AI 会引导你完成所有设置和日常操作。
- **AI 驱动，而非 AI 依赖** — QuidClaw 只是工具层。智能来自 AI。随时可以更换 AI 服务商。

## 工作原理

QuidClaw 是一个完整的 Claude Code Plugin，包含多种组件协同工作：

```
你 ──(自然语言)──→ Claude Code ──→ QuidClaw Plugin
                                       │
                          ┌─────────────┼─────────────┐
                          │             │             │
                       Skills        Agents         MCP
                     (AI 工作流)    (子任务)     (16 个工具)
                          │             │             │
                          └─────────────┼─────────────┘
                                        ↓
                              你的项目文件夹
                          (账本 · 收件箱 · 文档 · 笔记)
```

- **Skills** — 预定义的 AI 工作流：新手引导、账单导入、月度对账、报表生成等
- **Agents** — 专用子任务：解析账单、整理文档
- **Hooks** — 自动触发：每次对话开始时检查收件箱是否有新文件
- **MCP Server** — 16 个数据操作工具，直接读写 Beancount 账本

## 功能

### 基础功能
- 自然语言记账——说话就能记账
- 多币种支持（CNY、USD、EUR 等）
- 余额查询与对账
- 财务报表（利润表、资产负债表）
- BQL 查询（Beancount 查询语言）
- 股票、加密货币、外汇的价格追踪

### Plugin 增强功能
- **收件箱工作流** — 把账单、收据丢进 inbox 文件夹，AI 自动识别并记账
- **文档归档** — AI 按年月自动整理财务文档
- **财务知识库** — 记录资产详情、保险信息、订阅服务等长期信息
- **异常检测** — AI 主动发现重复交易、异常金额
- **月度回顾** — 自动生成月度财务分析报告

## 前置条件

- **[uv](https://docs.astral.sh/uv/)** — 安装命令：`curl -LsSf https://astral.sh/uv/install.sh | sh`
- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — 推荐。作为 Plugin 使用可获得完整体验（Skills + Agents + Hooks）。
- 也可作为独立 MCP 服务器连接 Claude Desktop、Codex 或其他 MCP 客户端（仅 MCP 工具功能）。

## 开始使用

### 方式一：Claude Code Plugin（推荐）

以 Plugin 模式运行，可获得完整体验——Skills、Agents、Hooks 全部可用：

```bash
# 从 PyPI 安装并作为 Plugin 启动
claude --plugin-dir $(uvx --python 3.13 --with quidclaw python -c "import quidclaw, pathlib; print(pathlib.Path(quidclaw.__file__).parents[2] / 'share' / 'quidclaw')")
```

或者从源码运行：

```bash
git clone https://github.com/thorb/quidclaw.git
claude --plugin-dir ./quidclaw
```

### 方式二：仅 MCP 服务器

如果你使用其他 MCP 客户端，可以只连接 MCP 服务器（16 个工具可用，但没有 Skills/Agents/Hooks）：

<details>
<summary><b>Claude Desktop</b></summary>

在 `claude_desktop_config.json` 中添加（[Settings → Developer → Edit Config](https://modelcontextprotocol.io/quickstart/user)）：

```json
{
  "mcpServers": {
    "quidclaw": {
      "command": "uvx",
      "args": ["--python", "3.13", "quidclaw"]
    }
  }
}
```

重启 Claude Desktop。

</details>

<details>
<summary><b>Claude Code（仅 MCP）</b></summary>

```bash
claude mcp add quidclaw -- uvx --python 3.13 quidclaw
```

</details>

<details>
<summary><b>Codex</b></summary>

Codex 在沙箱中运行 MCP 服务器，`uvx` 无法直接使用。需要先安装，再配置：

```bash
uv tool install --python 3.13 quidclaw
```

在 `~/.codex/config.toml` 中添加：

```toml
[mcp_servers.quidclaw]
command = "quidclaw"
args = []
type = "stdio"
```

</details>

<details>
<summary><b>其他 MCP 客户端</b></summary>

QuidClaw 是标准的 MCP 服务器，使用 stdio 传输。配置你的客户端运行：

```
uvx --python 3.13 quidclaw
```

</details>

### 升级

`uvx` 会在客户端每次启动时自动获取最新版本，无需手动升级。

### 从源码安装

适合贡献者或不想使用 [uv](https://docs.astral.sh/uv/) 的用户：

```bash
git clone https://github.com/thorb/quidclaw.git
cd quidclaw
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

然后在客户端配置中使用完整的 Python 路径：

```json
{
  "command": "/absolute/path/to/quidclaw/.venv/bin/python",
  "args": ["-m", "quidclaw"]
}
```

> 将路径替换为在激活的虚拟环境中运行 `which python` 的输出。

## 使用示例

连接后，直接用自然语言和 AI 对话：

> **你：** 帮我开始吧
>
> **AI：** 你好！我是你的私人财务助理。怎么称呼你？
>
> **你：** 叫我小明就好
>
> **AI：** 小明，你管理的是个人财务还是公司的？
>
> **你：** 个人的
>
> **AI：** 好的。你主要用什么银行？有几张卡？
>
> ...
>
> **AI：** 好的，我已经了解了你的大致情况。现在最重要的是把你的银行流水导入进来——把文件放到 inbox 文件夹，我来处理。

## 数据存储

QuidClaw 采用**目录即项目**的模式——没有全局默认目录。你创建一个文件夹（例如 `~/my-finances/`），在该目录下启动 Claude Code，QuidClaw 会自动将其识别为项目根目录。所有数据以纯文本形式存储在本地：

```
~/my-finances/
├── ledger/                # Beancount 账本（结构化、干净）
│   ├── main.bean          #   引用所有其他文件
│   ├── accounts.bean      #   账户定义
│   ├── prices.bean        #   价格信息
│   └── 2026/
│       ├── 2026-01.bean   #   一月交易
│       └── ...
├── inbox/                 # 收件箱——把文件丢进来就行
├── documents/             # 已归档文档（AI 自动整理）
│   └── 2026/03/           #   按年月分类
├── notes/                 # 财务知识库（AI 管理）
│   ├── profile.md         #   用户档案
│   ├── calendar.md        #   财务日历
│   ├── assets/            #   房产、车辆、投资
│   ├── liabilities/       #   贷款、房贷
│   ├── insurance/         #   保险详情
│   ├── accounts/          #   银行和证券账户
│   ├── subscriptions/     #   订阅服务
│   ├── income/            #   工资、副业收入
│   ├── decisions/         #   财务决策记录
│   └── journal/           #   自由记录
└── reports/               # 生成的报表（AI 管理）
```

## MCP 工具

QuidClaw 提供 16 个 MCP 工具：

| 工具 | 说明 |
|------|------|
| `set_data_dir` | 设置数据目录 |
| `init_ledger` | 初始化账本，创建默认或自定义账户 |
| `add_account` | 开立新账户 |
| `close_account` | 关闭账户 |
| `list_accounts` | 列出账户，可按类型筛选 |
| `add_transaction` | 记录交易 |
| `get_balance` | 查询账户余额 |
| `balance_check` | 核实余额，用于对账 |
| `query` | 执行任意 BQL 查询 |
| `report` | 生成利润表或资产负债表 |
| `fetch_prices` | 获取商品价格 |
| | **报表与分析** |
| `monthly_summary` | 月度收支汇总 |
| `spending_by_category` | 分类支出排行 |
| `month_comparison` | 月度对比 |
| `largest_transactions` | 最大交易 |
| `detect_anomalies` | 异常检测（重复扣款、订阅、大额） |

## Plugin 组件

作为 Claude Code Plugin 使用时，还可获得以下组件：

### Skills（AI 工作流）

| Skill | 说明 |
|-------|------|
| `onboarding` | 新手引导——从零开始设置你的账本 |
| `import-bills` | 账单导入——解析账单文件并批量记账 |
| `reconcile` | 对账——核对账户余额是否正确 |
| `monthly-review` | 月度回顾——生成月度财务分析 |
| `detect-anomalies` | 异常检测——发现重复交易和异常金额 |
| `organize-documents` | 文档整理——按规则归档财务文件 |
| `financial-memory` | 财务记忆——管理长期财务信息 |

### Agents（专用子任务）

| Agent | 说明 |
|-------|------|
| `bill-parser` | 账单解析器——从各种格式的账单中提取交易 |
| `document-organizer` | 文档管理员——按命名规范归档文件 |

### Hooks（自动触发）

| Hook | 触发时机 | 行为 |
|------|----------|------|
| Session Start | 每次对话开始 | 检查收件箱是否有新文件，有的话提醒你 |

## 开发

参见[从源码安装](#从源码安装)，然后：

```bash
pytest
```

## 许可证

本项目使用 [GNU 通用公共许可证 v2.0](LICENSE)，与 [Beancount](https://github.com/beancount/beancount) 使用相同的许可证。

## 作者

[Yue Jiang](https://github.com/thorb)
