介绍
# Treeline Money
**与您的财务数据对话。** 提出诸如“我的净资产是多少？”、“我在杂货上花了多少钱？”或“我是否超出了预算？”等问题，并从您自己的财务数据中即时获得答案。
---
## 快速开始
```bash # 1. Install the CLI (OpenClaw handles this automatically)
# 2. Enable demo mode (sample data) tl demo on
# 3. Try it out tl status ```
---
## 首次设置
> **对于代理：** 如果 `tl` 命令因“command not found”而失败，则需要安装 CLI。OpenClaw 会通过技能元数据自动处理安装。从演示模式开始，以便用户可以立即尝试查询。
使用 `tl --version` 验证 CLI 是否可用。从演示模式开始，以便用户可以立即尝试查询。
**可选：** 下载[桌面应用](https://treeline.money/download)以可视化方式探索您的数据。
### 演示模式
演示模式会加载示例数据，以便用户无需连接银行即可尝试查询：
```bash tl demo on ```
稍后要切换到真实数据： ```bash tl demo off ```
演示数据与真实数据是分开的。
### CLI 行为说明
- `tl demo on` 会打印一条成功消息——如果它看起来挂起了，请等待几秒钟（首次运行会初始化数据库） - 使用 `tl demo status` 验证演示模式是否已启用 - 由于数据库初始化，某些命令在首次运行时可能需要几秒钟 - 如果您看到关于缺失表的错误，请再次尝试 `tl demo on`
### 连接真实数据
当用户准备好超越演示模式时，请指导他们使用下方链接的指南设置数据源。
数据源选项： - **SimpleFIN**（每月 $1.50，美国和加拿大） - **Lunch Flow**（每月约 $3，全球） - **CSV 导入**（免费）
设置指南：[银行同步](https://treeline.money/docs/integrations/bank-sync/) · [CSV 导入](https://treeline.money/docs/integrations/csv-import/)
设置完成后，使用 `tl sync` 拉取银行交易或使用 `tl import` 加载 CSV。
---
## 什么是 Treeline？
[Treeline Money](https://treeline.money) 是一个本地优先的个人理财应用。您的所有数据都保留在您设备的本地 DuckDB 数据库中。无需云端账户，无需订阅（同步服务是可选的），完全通过 SQL 访问您的财务数据。
---
## 限制
**不支持加密数据库。** 如果用户在 Treeline 中启用了数据库加密，CLI 命令将失败。他们需要： - 如果他们希望 OpenClaw 访问，请禁用加密 - 对于加密数据库，直接使用 Treeline 应用
如果您看到“database is encrypted”错误，请解释此限制。
---
## 响应格式
**为移动/聊天格式化所有响应：** - 使用项目符号，而不是 markdown 表格 - 对数字进行四舍五入以提高可读性（$1,234 而不是 $1,234.56） - 答案在前，细节在后 - 保持响应简洁——聊天不是电子表格 - 使用换行符分隔各个部分
**良好的响应示例：** ``` Your net worth is $125k
Assets: $180k - Retirement: $85k - Savings: $25k - Checking: $10k - Home equity: $60k
Liabilities: $55k - Mortgage: $52k - Credit cards: $3k ```
**糟糕的响应示例：** ``` | Account | Type | Balance | |---------|------|---------| | My 401k Account | asset | 85234.56 | ... ```
---
## CLI 命令
### 读取命令（可自由运行）
这些命令是只读的，可以安全地自主运行：
```bash tl status # Quick account summary with balances tl status --json # Same, but JSON output
tl query "SQL" --json # Run any SQL query (database opened in read-only mode) tl sql "SQL" --json # Same as tl query (alias)
tl backup list # List available backups tl doctor # Check database health tl demo status # Check if demo mode is on/off ```
> **注意：** `tl query` 和 `tl sql` 默认以只读模式打开数据库。除非传递了 `--allow-writes`（请参阅下面的写入命令），否则它们无法修改数据。
**使用 `tl status` 进行快速余额检查**——这比 SQL 查询更快。
### 写入命令（请先询问用户）
这些命令会修改本地数据。**在运行它们之前始终请求用户确认**，除非用户已在 `PERMISSIONS.md` 中明确允许（请参阅[代理权限](#agent-permissions)）。
```bash tl query "SQL" --allow-writes --json # Run a SQL query with write access tl sql "SQL" --allow-writes --json # Same (alias)
tl sync # Sync accounts/transactions from bank integrations tl sync --dry-run # Preview what would sync (read-only, safe to run)
tl import FILE -a ACCOUNT # Import transactions from CSV tl import FILE -a ACCOUNT --dry-run # Preview import without applying (read-only, safe to run) tl import FILE -a ACCOUNT --json # JSON output for scripting
tl backup create # Create a backup tl backup restore NAME # Restore a backup
tl compact # Compact database (reclaim space, optimize)
tl tag "groceries" --ids ID1,ID2 # Apply tags to transactions
tl demo on|off # Toggle demo mode (sample data) ```
> **提示：** `--dry-run` 变体是只读的，可以在未经确认的情况下安全运行。在请求用户确认实际操作之前，使用它们进行预览。
**如果用户提到查询缓慢，请使用 `tl compact`**——它可以优化数据库。
### CSV 导入详情
`tl import` 会根据 CSV 标题自动检测列映射。大多数银行 CSV 都可以开箱即用：
```bash tl import bank_export.csv --account "Chase Checking" ```
`--account` / `-a` 标志接受账户名称（不区分大小写，子字符串匹配）或 UUID。
**务必先使用 `--dry-run` 进行预览**以验证列是否被正确检测：
```bash tl import bank_export.csv -a "Checking" --dry-run --json ```
**所有导入标志**（除 `--account` 外均为可选）：
| 标志 | 目的 | 示例 | |------|---------|---------| | `--date-column` | 覆盖日期列 | `--date-column "Post Date"` | | `--amount-column` | 覆盖金额列 | `--amount-column "Amt"` | | `--description-column` | 覆盖描述列 | `--description-column "Memo"` | | `--debit-column` | 使用借方列（而不是金额列） | `--debit-column "Debit"` | | `--credit-column` | 使用贷方列（而不是金额列） | `--credit-column "Credit"` | | `--balance-column` | 运行余额（创建快照） | `--balance-column "Balance"` | | `--flip-signs` | 取反金额（信用卡 CSV） | `--flip-signs` | | `--debit-negative` | 取反正数借方 | `--debit-negative` | | `--skip-rows N` | 在标题之前跳过 N 行 | `--skip-rows 3` | | `--number-format` | `us`、`eu` 或 `eu_space` | `--number-format eu` | | `--profile NAME` | 加载保存的配置文件 | `--profile chase` | | `--save-profile NAME` | 将设置保存为配置文件 | `--save-profile chase` | | `--dry-run` | 预览而不导入 | `--dry-run` | | `--json` | JSON 输出 | `--json` |
**代理的常见模式：**
```bash # Step 1: Find the account UUID tl status --json
# Step 2: Preview import tl import transactions.csv -a "550e8400-e29b-41d4-a716-446655440000" --dry-run --json
# Step 3: Execute import tl import transactions.csv -a "550e8400-e29b-41d4-a716-446655440000" --json ```
通过指纹识别，重复交易在重新导入时会自动检测并被跳过。
---
## 代理权限
**在运行任何写入命令之前，请检查此技能目录中的 `PERMISSIONS.md`。**
如果它存在，请阅读它以查看用户已预先批准了哪些写入命令。预先批准的命令可以在无需请求确认的情况下运行。所有其他写入命令在执行前仍需要明确的用户确认。
如果 `PERMISSIONS.md` 不存在，**在运行任何写入命令之前请务必询问。**
**PERMISSIONS.md 模板：**
```markdown # Treeline Agent Permissions
Commands listed here are pre-approved — the agent can run them without asking for confirmation each time. Remove a line to require confirmation.
## Allowed write commands - tl sync - tl backup create - tl demo on|off ```
---
## 用户上下文
**在回答财务问题之前，请检查此技能目录中的 `CONTEXT.md`。**
如果它存在，请先阅读它——它包含特定于用户的知识： - 账户含义（哪些账户是退休账户还是经纪账户等） - 标记约定和现金流规则 - 插件配置 - 个人偏好
**学习新上下文：** 当您发现有关用户设置的信息时： 1. 对于小型观察，请将其记录在 CONTEXT.md 中并简要说明您保存的内容 2. 对于重大假设或更正，请询问：“您希望我将其保存到您的 Treeline 上下文中吗？”
请参阅最后的[用户上下文模式](#user-context-pattern)部分以获取模板。
---
## 快速参考
### 净资产 ```bash tl query " WITH latest AS ( SELECT DISTINCT ON (account_id) account_id, balance FROM sys_balance_snapshots ORDER BY account_id, snapshot_time DESC ) SELECT SUM(CASE WHEN a.classification = 'asset' THEN s.balance ELSE 0 END) as assets, SUM(CASE WHEN a.classification = 'liability' THEN ABS(s.balance) ELSE 0 END) as liabilities, SUM(CASE WHEN a.classification = 'asset' THEN s.balance ELSE -ABS(s.balance) END) as net_worth FROM accounts a JOIN latest s ON a.account_id = s.account_id " --json ```
### 账户余额 ```bash tl query " WITH latest AS ( SELECT DISTINCT ON (account_id) account_id, balance FROM sys_balance_snapshots ORDER BY account_id, snapshot_time DESC ) SELECT a.name, a.classification, a.institution_name, s.balance FROM accounts a JOIN latest s ON a.account_id = s.account_id ORDER BY s.balance DESC " --json ```
### 实际支出（排除内部转账）
检查 CONTEXT.md 中的 `internal_transfer_tags`。默认模式：
```bash tl query " SELECT SUM(ABS(amount)) as total_spent FROM transactions WHERE amount < 0 AND transaction_date >= date_trunc('month', current_date) AND NOT (tags && ARRAY['transfer', 'savings', 'investment']) " --json ```
### 按标记的支出 ```bash tl query " SELECT tags, SUM(ABS(amount)) as spent FROM transactions WHERE amount < 0 AND transaction_date >= '2026-01-01' AND transaction_date < '2026-02-01' AND tags IS NOT NULL AND tags != '[]' GROUP BY tags ORDER BY spent DESC " --json ```
### 最近交易 ```bash tl query " SELECT t.description, t.amount, t.transaction_date, a.name as account FROM transactions t JOIN accounts a ON t.account_id = a.account_id ORDER BY t.transaction_date DESC LIMIT 10 " --json ```
---
## 数据库架构
### 核心表
**accounts** | 列 | 描述 | |--------|-------------| | `account_id` | UUID 主键 | | `name` | 账户显示名称 | | `classification` | `asset` 或 `liability` | | `account_type` | `credit`、`investment`、`Loan`、`other` 或 null | | `institution_name` | 银行/机构名称 | | `currency` | 货币代码（例如 `USD`） | | `is_manual` | 布尔值——手动添加与同步 |
**sys_balance_snapshots** — 余额的真实来源 | 列 | 描述 | |--------|-------------| | `snapshot_id` | UUID 主键 | | `account_id` | 指向 accounts 的外键 | | `balance` | 快照时的余额 | | `snapshot_time` | 记录时间 | | `source` | `sync`、`manual` 等 |
**transactions** | 列 | 描述 | |--------|-------------| | `transaction_id` | UUID 主键 | | `account_id` | 指向 accounts 的外键 | | `amount` | 有符号（负数 = 支出） | | `description` | 交易描述 | | `transaction_date` | 发生时间 | | `posted_date` | 结算时间 | | `tags` | 标记数组 |
### 标记与类别
**标记**是 Treeline 中的主要概念——交易可以有多个标记。
**类别**来自预算插件（`plugin_budget`），它将标记映射到预算类别。并非所有用户都拥有此插件。
---
## 插件系统
插件拥有自己的 DuckDB 架构：`plugin_<name>.*`
### 发现已安装的插件 ```bash tl query " SELECT schema_name FROM information_schema.schemata WHERE schema_name LIKE 'plugin_%' " --json ```
### 常见插件架构
**plugin_budget.categories** — 预算类别 | 列 | 描述 | |--------|-------------| | `category_id` | UUID 主键 | | `month` | `YYYY-MM` 格式 | | `type` | `income` 或 `expense` | | `name` | 类别名称 | | `expected` | 预算金额 | | `tags` | 要匹配的标记数组 |
**plugin_goals.goals** — 储蓄目标 | 列 | 描述 | |--------|-------------| | `id` | UUID 主键 | | `name` | 目标名称 | | `target_amount` | 目标金额 | | `target_date` | 目标日期 | | `completed` | 布尔值 | | `active` | 布尔值 |
**plugin_subscriptions** — 检测到的经常性费用
**plugin_cashflow** — 现金流预测
**plugin_emergency_fund** — 应急基金跟踪
检查 CONTEXT.md 以查看用户拥有哪些插件以及关心哪些插件。
---
## 常见模式
### 获取当前余额
始终使用最新快照： ```sql WITH latest AS ( SELECT DISTINCT ON (account_id) account_id, balance FROM sys_balance_snapshots ORDER BY account_id, snapshot_time DESC ) SELECT a.name, s.balance FROM accounts a JOIN latest s ON a.account_id = s.account_id ```
### 使用标记
标记是数组： ```sql -- Contains a specific tag WHERE tags @> ARRAY['groceries']
-- Contains any of these tags WHERE tags && ARRAY['food', 'dining']
-- Note: UNNEST doesn't work in all contexts in DuckDB -- Instead, GROUP BY tags directly ```
### 日期筛选器 ```sql -- This month WHERE transaction_date >= date_trunc('month', current_date)
-- Specific month WHERE transaction_date >= '2026-01-01' AND transaction_date < '2026-02-01' ```
### 预算与实际 ```sql SELECT c.name, c.expected, COALESCE(SUM(ABS(t.amount)), 0) as actual, c.expected - COALESCE(SUM(ABS(t.amount)), 0) as remaining FROM plugin_budget.categories c LEFT JOIN transactions t ON t.tags && c.tags AND t.amount < 0 AND t.transaction_date >= (c.month || '-01')::DATE AND t.transaction_date < (c.month || '-01')::DATE + INTERVAL '1 month' WHERE c.month = strftime(current_date, '%Y-%m') AND c.type = 'expense' GROUP BY c.category_id, c.name, c.expected ```
---
## 问题映射
| 用户询问 | 处理方式 | |-----------|----------| | "Net worth?" | 净值查询 | | "Balances?" | 账户余额查询 | | "How much in [X]?" | 使用 `name ILIKE '%X%'` 过滤 | | "How much did I spend?" | 实际支出查询（排除内部转账） | | "Spending on [tag]?" | 按标签过滤 | | "Am I over budget?" | 预算对比实际（需要预算插件） | | "Recent transactions" | 按日期 DESC 排序，限制数量 | | "Savings?" | 按名称/类型过滤账户 | | "Retirement?" | 按 401k、IRA、retirement 关键词过滤 | | "Import CSV" / "Upload transactions" | 引导使用 `tl import` — 先用 `--dry-run` 预览 | | "Import from [bank name]" | 使用 `tl import` 并配合适用于该银行 CSV 格式的相应参数 |
---
## 提示
1. **始终使用 `--json`** 以获得可解析的输出 2. **金额带有符号** — 负数 = 支出 3. **使用 `classification`** 区分资产/负债 4. **余额存储在快照中**，而非 accounts 表中 5. **查阅 CONTEXT.md** 以了解用户特定的账户含义和标签约定
---
## 用户上下文模式
安装此技能时，请在其旁边创建 `CONTEXT.md` 以存储用户特定的知识。这既能保持技能的通用性和可共享性，又能实现个性化行为。
**CONTEXT.md 模板：**
```markdown # Treeline User Context *Auto-updated by your assistant as it learns your setup*
## Account Notes <!-- What specific accounts mean, e.g.: --> <!-- - "Company 401k" = retirement account --> <!-- - "Home Equity" = home value estimate (manual) -->
## Tag Conventions <!-- How the user uses tags -->
## Cash Flow Rules <!-- Tags to exclude from "true spending" calculations --> internal_transfer_tags: [transfer, savings, investment]
## Income Sources <!-- Known income sources for better reporting -->
## Active Plugins <!-- Which plugins are installed and relevant -->
## Preferences <!-- Reporting style, rounding, spouse-friendly mode, etc. -->
## Learned Facts <!-- Anything else discovered about the user's financial setup --> ```
**维护：** - 简要记录针对细微观察的更新 - 在记录重要假设前先询问用户 - 定期对照实时数据进行验证（账户可能关闭，标签可能变更）
---
## 隐私说明
所有数据均存储在本地（`~/.treeline/treeline.duckdb`）。除非明确要求，否则切勿在对话之外分享交易描述或账户详细信息。