AI助手集成PocketSmith API：命令行与自然语言财务管理技能开发指南

1. 项目概述：一个为AI助手赋能的个人财务管理技能

如果你和我一样，日常使用Claude Code或OpenClaw这类AI编程助手来提升效率，同时又是个PocketSmith的深度用户，那么你很可能也面临过这样的痛点：想快速查询一笔交易、临时创建一个预算类别，或者只是看看上个月的餐饮开销，却不得不在浏览器、手机App和代码编辑器之间来回切换。这种割裂感，尤其是在专注编码时被打断，实在让人烦躁。

lextoumbourou/pocketsmith-skill这个项目，正是为了解决这个“效率断层”而生的。它是一个专为Claude Code和OpenClaw设计的技能（Skill），本质上是一个命令行工具，通过封装PocketSmith的官方API，让你能直接在终端或AI助手的对话界面里，用自然语言或简单的命令来管理你的个人财务数据。想象一下，你正在写代码，突然想起要核对一笔报销，只需在Claude里问一句“帮我查查上周在星巴克花了多少钱”，它就能直接调用这个技能，从PocketSmith拉取数据并给出答案，整个过程无需离开你的开发环境。

这个技能的核心价值在于“场景融合”。它不是为了替代PocketSmith精美的Web界面，而是将财务管理无缝嵌入到开发者和技术爱好者的核心工作流中。无论是通过CLI脚本进行批量操作、在自动化流程中集成财务检查，还是仅仅为了满足“懒人”的极致效率追求——不想动鼠标就能完成财务查询，它都提供了一个极其轻量且强大的接口。对于任何使用PocketSmith并热衷于用命令行和AI工具优化工作流的开发者来说，这绝对是一个值得深入把玩的利器。

2. 核心设计思路：安全、便捷与生态融合

当我第一次看到这个项目时，最吸引我的是它在设计上体现出的克制与周全。这不仅仅是一个简单的API包装器，其架构充分考虑了财务数据操作的敏感性和不同使用场景的灵活性。

2.1 以安全为首要原则的“默认只读”机制

处理财务数据，安全永远是第一位的。pocketsmith-skill在这方面做得非常聪明：它默认禁用了所有写入操作（创建、更新、删除）。这意味着，即使你不小心输错了一个命令，或者AI助手误解了你的意图，它也无法擅自修改你的交易记录或分类体系。你必须显式地设置环境变量POCKETSMITH_ALLOW_WRITES=true来解锁写入功能。

注意：这是一个至关重要的安全特性。我强烈建议在初始安装和测试阶段保持写入关闭。只有在完全理解命令作用，并确认需要在特定脚本或对话中执行修改时，才在对应的会话或配置中临时开启。永远不要将POCKETSMITH_ALLOW_WRITES=true设置为全局、永久的环境变量。

这种“安全开关”的设计，反映了开发者对生产环境，尤其是涉及金钱数据的环境的深刻理解。它防止了自动化脚本或AI代理的意外操作，将破坏数据的风险降到了最低。

2.2 双平台适配与灵活的安装模式

项目对Claude Code和OpenClaw两大主流AI编程助手的原生支持，展现了其良好的生态兼容性。它提供了两种安装模式：

1. 个人技能（Personal/Managed Skill）：安装在用户目录下（如~/.claude/skills/），对该用户的所有项目全局可用。这是最推荐的方式，一次安装，处处使用。
2. 项目技能（Project/Workspace Skill）：安装在特定项目或工作空间的本地目录中，仅对该上下文生效。这适用于为某个特定项目（例如一个个人财务分析工具项目）配置独立的财务技能实例，实现环境隔离。

这种灵活性允许用户根据团队协作需求或个人习惯进行选择。对于个人日常使用，全局安装无疑最方便；而在开发一个需要集成PocketSmith API的特定应用时，项目级安装能更好地管理依赖和配置。

2.3 清晰的命令层级与符合直觉的API映射

技能的命令行接口设计遵循了清晰的层级结构，与PocketSmith的API资源模型高度对应：

pocketsmith ├── me # 获取当前用户信息 ├── transactions # 交易管理 │ ├── list-by-user │ ├── get │ ├── create │ └── update ├── categories # 分类管理 │ ├── list │ ├── create │ └── update └── budget # 预算分析 ├── list ├── summary └── trend

这种结构让任何熟悉RESTful API或常用CLI工具（如git、awscli）的开发者都能快速上手。更重要的是，它在AI助手语境下表现优异。当你对Claude说“列出我的交易”时，助手能很容易地将自然语言映射到pocketsmith transactions list-by-user这个命令上，因为动词（list）和对象（transactions）的对应关系非常直接。

3. 从零开始的详细配置与实操指南

光看文档不够，我们一步步来，确保你能从安装到使用畅通无阻。这里我会结合自己的踩坑经验，补充一些官方文档里没细说的细节。

3.1 前置准备：获取你的PocketSmith开发者密钥

这是整个流程的钥匙，没有它一切免谈。

1. 登录PocketSmith：用你的账号正常登录 PocketSmith网站 。
2. 找到开发者设置：点击右上角头像进入“Settings”（设置），在左侧菜单中找到“Security”（安全），然后点击“Manage Developer Keys”（管理开发者密钥）。这个路径有时会随着UI改版微调，如果找不到，可以直接在设置页搜索“developer”。
3. 创建新密钥：点击“Create New Key”（创建新密钥）。系统可能会让你输入密码再次确认身份。
4. 复制并妥善保存：密钥生成后，会显示一串长字符。务必立即复制并保存到安全的地方（如密码管理器），因为它只显示一次，关闭页面后就无法再次查看。如果丢失，只能撤销旧密钥重新创建。

实操心得：给你的密钥起一个有意义的名字，比如“Claude-Code-Macbook”。这样以后如果你在多个设备或工具上使用，可以轻松区分和管理。定期检查并清理不再使用的旧密钥，是个好习惯。

3.2 技能安装：选择适合你的路径

假设我们主要使用Claude Code，并以个人技能模式安装。这里用uv作为包管理器，它是当前Python生态中管理项目和依赖的新锐工具，速度很快。

# 1. 创建并进入个人技能目录（如果不存在） mkdir -p ~/.claude/skills cd ~/.claude/skills # 2. 克隆仓库 git clone https://github.com/lextoumbourou/pocketsmith-skill.git pocketsmith # 3. 进入目录并安装依赖 cd pocketsmith uv sync

uv sync命令会根据项目中的pyproject.toml文件，自动创建虚拟环境并安装所有必要的依赖。整个过程通常很快。如果遇到网络问题，可以考虑配置uv使用国内镜像源。

验证安装是否成功：

# 确保你在 ~/.claude/skills/pocketsmith 目录下 uv run pocketsmith --help

如果安装正确，你应该能看到完整的命令帮助信息，列出了me,transactions,categories,budget等子命令。

3.3 环境配置：区分全局与会话级设置

配置环境变量是关键一步。你需要决定让这个技能在什么范围内生效。

方案A：配置为Claude Code全局环境（推荐用于稳定使用）编辑Claude Code的全局配置文件~/.claude/settings.json。如果文件不存在，就创建它。

{ "env": { "POCKETSMITH_DEVELOPER_KEY": "你的_开发者_密钥_粘贴在这里", "POCKETSMITH_ALLOW_WRITES": "false" } }

注意：JSON格式要求严格，键和字符串值必须用双引号。末尾不能有逗号。建议先将POCKETSMITH_ALLOW_WRITES设为"false"，等熟悉了再按需开启。

方案B：在终端会话中临时设置（推荐用于测试或临时操作）如果你不想修改全局配置，或者只想在某个特定的终端会话中使用，可以直接在启动Claude Code前设置环境变量：

export POCKETSMITH_DEVELOPER_KEY="你的密钥" export POCKETSMITH_ALLOW_WRITES=false claude-code

这种方式下，环境变量只对当前终端窗口有效，关闭后即失效，更为安全灵活。

方案C：在项目级配置中设置如果你采用“项目技能”模式安装，可以在项目根目录下的.claude/settings.json中配置，仅对该项目生效。这对于不同项目使用不同PocketSmith账户（比如个人账户和公司账户）的场景非常有用。

3.4 验证连接：确保一切就绪

配置完成后，进行一个最简单的测试来验证认证是否成功：

# 在技能目录下执行 uv run pocketsmith me

如果一切正常，这个命令会调用PocketSmith的/api/me端点，并返回一个包含你用户ID、邮箱等基本信息的JSON对象。如果看到类似{"id": 123456, "email": "your.email@example.com", ...}的输出，恭喜你，连接成功了！

如果遇到401 Unauthorized错误，请按以下步骤排查：

1. 检查密钥：确认POCKETSMITH_DEVELOPER_KEY的值完全正确，没有多余的空格或换行。
2. 检查生效范围：如果你在终端临时设置变量，确保是在执行uv run的同一个终端窗口里。
3. 重启Claude Code：如果修改了settings.json，需要完全退出并重启Claude Code，新的环境变量才会被加载。

4. 核心功能深度解析与实战应用

安装配置只是开始，真正发挥威力在于如何使用。下面我们深入每个功能模块，结合具体场景和命令，看看如何用它来提升我们的财务操作效率。

4.1 交易（Transactions）管理：你的财务日志查询终端

交易是财务数据的核心。pocketsmith-skill提供了对交易记录的全面操作。

基础查询：快速浏览与精准搜索假设你的用户ID是123456（可以通过uv run pocketsmith me获取）。

# 列出用户的所有交易（默认可能返回最近的一些） uv run pocketsmith transactions list-by-user 123456 # 使用分页参数（PocketSmith API支持分页） uv run pocketsmith transactions list-by-user 123456 --start 0 --limit 50 # 搜索特定商户的交易（非常实用！） uv run pocketsmith transactions list-by-user 123456 --search "Starbucks" # 按时间范围筛选 uv run pocketsmith transactions list-by-user 123456 --start-date 2024-03-01 --end-date 2024-03-31

--search参数非常强大，它会在交易的描述、备注等字段中进行模糊匹配。我经常用它来汇总某个特定商家（如“Netflix”、“Amazon”）或项目（如“机票报销”）的所有花费。

获取单笔交易详情有时你需要查看某笔特定交易的完整信息，例如核对类别或备注。

uv run pocketsmith transactions get 987654321

这里的987654321是交易ID。如何获取这个ID？通常来自list-by-user命令的输出，或者从PocketSmith网页版的URL中提取。

高级筛选与数据导出命令的输出是结构化的JSON，这为后续处理打开了大门。你可以结合jq这样的命令行JSON处理工具，进行更复杂的操作：

# 1. 找出2024年3月所有金额大于100元的交易，并只输出描述和金额 uv run pocketsmith transactions list-by-user 123456 --start-date 2024-03-01 --end-date 2024-03-31 | jq -r '.[] | select(.amount < -100) | "\(.payee): \(.amount)"' # 2. 计算某个月份的总支出（假设支出为负值） uv run pocketsmith transactions list-by-user 123456 --start-date 2024-03-01 --end-date 2024-03-31 | jq '[.[] | select(.amount < 0)] | map(.amount) | add' # 3. 将交易数据导出为CSV格式，方便用Excel或Numbers进一步分析 uv run pocketsmith transactions list-by-user 123456 --start-date 2024-01-01 --end-date 2024-01-31 | jq -r '["日期", "描述", "金额", "类别"], (.[] | [.date, .payee, .amount, .category_name]) | @csv' > transactions_jan.csv

注意事项：PocketSmith API的金额（amount）字段，支出通常为负数，收入为正数。这在用jq筛选或计算时要特别注意。例如select(.amount < -50)是筛选支出超过50的交易。

4.2 分类（Categories）管理：构建你的财务图谱

清晰分类是有效财务管理的基础。这个技能允许你动态管理分类体系。

浏览现有分类结构首先，看看你现有的分类是什么样子：

uv run pocketsmith categories list 123456

这会返回一个嵌套的JSON列表，清晰地展示了分类的父子层级关系。对于规划新分类或理解消费构成非常有帮助。

创建新分类假设你想在“娱乐”大类下创建一个新的子分类“游戏订阅”。

1. 首先，找到“娱乐”分类的ID。从categories list的输出中寻找，假设是28601039。
2. 执行创建命令（需要开启写入权限）：

   # 确保已设置 POCKETSMITH_ALLOW_WRITES=true uv run pocketsmith categories create 123456 --title "游戏订阅" --parent-id 28601039

   命令成功会返回新建分类的详细信息，包括其新的ID。

更新分类如果你想修改一个已有分类的名称，或者把它移动到另一个父分类下：

uv run pocketsmith categories update 分类ID --title "新名称" --parent-id 新的父分类ID

实操心得：在创建或更新分类前，最好先用list命令确认一下现有的ID和结构。分类ID是数字，很容易输错。对于重要的分类结构调整，建议先在PocketSmith网页版上操作一次，观察API请求的变化，再用技能命令复现，这样更稳妥。

4.3 预算（Budget）分析：洞察消费趋势

预算功能是PocketSmith的强项，技能也提供了相应的接口来获取预算视图和分析。

查看预算列表

uv run pocketsmith budget list 123456

这会列出用户设置的所有预算周期和场景。预算场景（Scenario）是PocketSmith的一个特色功能，允许你为“计划内”、“理想情况”、“实际情况”等不同假设创建不同的预算版本。

获取预算摘要要查看某个时间段内，各个预算类别的实际花费与预算的对比：

uv run pocketsmith budget summary 123456 --period months --interval 1 --start-date 2024-01-01 --end-date 2024-03-31

参数解释：

• --period months：按月份为周期进行分析。
• --interval 1：每个分析点的时间间隔为1个单位（此处是1个月）。
• --start-date/--end-date：定义分析的时间范围。

输出会详细列出每个预算类别在该时间段内的预算金额、实际支出、差额以及完成度百分比。

进行趋势分析趋势分析功能更强大，可以对比不同场景下，特定类别组的支出趋势。

uv run pocketsmith budget trend 123456 --period months --interval 1 --start-date 2024-01-01 --end-date 2024-06-30 --categories 28600217,28637787 --scenarios 1,2

• --categories：传入你想分析的分类ID，用逗号分隔。
• --scenarios：传入你想对比的预算场景ID，用逗号分隔。

这个命令的输出对于制作简单的消费趋势图表或报告非常有价值。你可以定期运行它，将结果导入到其他数据分析工具中，实现财务健康的自动化监控。

4.4 在AI助手中实现自然语言交互

这才是技能最酷的部分。配置完成后，在Claude Code或OpenClaw中，你可以像跟助手聊天一样管理财务。

直接调用技能菜单： 在Claude的输入框中，直接键入/pocketsmith并回车，它会列出所有可用的子命令和简要说明，就像一个内置的帮助系统。

自然语言查询：

• “Show me my transactions from last week that were over $50.”（显示我上周金额超过50美元的交易。）
• “Find all transactions with ‘Amazon’ in the description from this month.”（找出本月描述中包含‘Amazon’的所有交易。）
• “What’s my total spending on dining out in March?”（我三月份外出就餐的总花费是多少？）

Claude会理解你的意图，将其转换为相应的pocketsmith transactions list-by-user ...命令，并附上合适的过滤参数（如日期范围、搜索词），然后执行并返回格式清晰的结果。

执行数据操作（需开启写入）：

• “Categorize transaction ID 987654321 as ‘Groceries’.”（将交易ID 987654321归类为‘食品杂货’。） 助手需要知道‘Groceries’分类对应的ID，它可能会先运行categories list来查找ID，再执行transactions update。
• “Create a new transaction for a $15.99 lunch at ‘Mega Salad’ today.”（为今天在‘Mega Salad’的15.99美元午餐创建一笔新交易。）

重要提示：AI助手在执行写入操作时非常谨慎。通常，它会在真正执行create或update命令前，向你确认操作细节（例如，“我将创建一笔金额为-15.99、收款人为‘Mega Salad’的交易，日期为今天，确认吗？”）。这是一个重要的安全特性，务必仔细核对确认信息。

5. 进阶技巧：脚本集成与自动化

当熟练使用CLI命令后，你可以将其集成到Shell脚本或自动化流程中，实现更强大的功能。

5.1 编写月度财务简报脚本

创建一个脚本monthly_finance_report.sh，每月初自动运行，汇总上个月的财务情况：

#!/bin/bash # 设置你的用户ID和日期 USER_ID="123456" LAST_MONTH_START=$(date -v-1m -j -f "%Y-%m-%d" "$(date +%Y-%m-01)" +%Y-%m-%d) LAST_MONTH_END=$(date -v-1d -j -f "%Y-%m-%d" "$(date +%Y-%m-01)" +%Y-%m-%d) echo "===== 上月财务简报 ($LAST_MONTH_START 至 $LAST_MONTH_END) =====" echo "" # 1. 总支出与总收入 echo "1. 收支总览:" ALL_TX_JSON=$(uv run pocketsmith transactions list-by-user $USER_ID --start-date $LAST_MONTH_START --end-date $LAST_MONTH_END) TOTAL_EXPENSE=$(echo "$ALL_TX_JSON" | jq '[.[] | select(.amount < 0)] | map(.amount) | add | .*-1') TOTAL_INCOME=$(echo "$ALL_TX_JSON" | jq '[.[] | select(.amount > 0)] | map(.amount) | add') echo " 总支出: \$${TOTAL_EXPENSE:-0}" echo " 总收入: \$${TOTAL_INCOME:-0}" echo "" # 2. 前五大消费类别 echo "2. 前五大消费类别:" # 这里需要更复杂的jq处理来按类别分组求和，假设类别名在.category_name中 echo "$ALL_TX_JSON" | jq -r ' [.[] | select(.amount < 0)] | group_by(.category_name) | map({category: .[0].category_name, total: (map(.amount) | add * -1)}) | sort_by(.total) | reverse | .[0:5] | .[] | " \(.category): \$.\(.total)" ' echo "" # 3. 最大单笔支出 echo "3. 最大单笔支出:" LARGEST_EXPENSE=$(echo "$ALL_TX_JSON" | jq -r ' [.[] | select(.amount < 0)] | min_by(.amount) | " \(.payee) on \(.date): \$.\((-.amount))" ') echo "${LARGEST_EXPENSE:- 无支出记录}" echo "" # 4. 预算执行情况快照（示例：获取第一个预算场景的摘要） echo "4. 预算执行快照（上月）:" BUDGET_SUMMARY=$(uv run pocketsmith budget summary $USER_ID --period months --interval 1 --start-date $LAST_MONTH_START --end-date $LAST_MONTH_END 2>/dev/null | jq -r ' .periods[0].categories[]? | select(.actual_spent != 0) | " \(.name): 预算\$.\(.budget_amount)，实际\$.\(.actual_spent)，\(if .budget_amount != 0 then "完成度\(((.actual_spent/.budget_amount)*100)|floor)%" else "N/A" end)" ' | head -5) if [ -n "$BUDGET_SUMMARY" ]; then echo "$BUDGET_SUMMARY" else echo " 未获取到预算数据或暂无实际支出。" fi

这个脚本结合了pocketsmith-skill的命令和jq的强大数据处理能力，可以生成一份简洁明了的文本简报。你可以通过cron job设置它每月1号自动运行，并将结果发送到你的邮箱或聊天工具。

5.2 与记账软件或银行通知联动

如果你有基本的编程能力（比如Python），可以将此技能作为库来调用，实现更复杂的自动化。

例如，你可能会收到银行的消费短信或邮件通知。可以写一个Python脚本，定期抓取这些通知（通过邮件API或短信转发服务），解析出金额、商户和日期，然后自动调用pocketsmith-skill创建一笔待分类的交易草稿。

# 示例伪代码，展示思路 import subprocess import json from datetime import datetime def create_transaction_draft(user_id, payee, amount, date): """调用pocketsmith技能创建交易""" # 金额需要转为负数表示支出 if amount > 0: amount = -amount cmd = [ "uv", "run", "pocketsmith", "transactions", "create", str(user_id), "--payee", payee, "--amount", str(amount), "--date", date.isoformat(), "--note", "Auto-imported from bank notification" ] # 确保已设置 POCKETSMITH_ALLOW_WRITES=true result = subprocess.run(cmd, capture_output=True, text=True, cwd="~/.claude/skills/pocketsmith") if result.returncode == 0: print(f"交易创建成功: {payee}") return json.loads(result.stdout) else: print(f"交易创建失败: {result.stderr}") return None # 模拟从银行通知解析的数据 new_spending = { "payee": "Cloud Hosting Inc.", "amount": 12.99, "date": datetime.today() } create_transaction_draft(YOUR_USER_ID, **new_spending)

这种自动化的初级形态，可以极大减少手动录入交易的工作量。当然，自动分类的准确性是另一个挑战，可能需要结合简单的规则引擎或机器学习模型。

6. 常见问题与故障排查实录

在实际使用中，你难免会遇到一些问题。下面是我遇到或预见到的一些典型情况及其解决方法。

6.1 认证与连接问题

6.2 命令执行与权限问题

6.3 数据与逻辑问题

6.4 性能与使用建议

• API速率限制：PocketSmith的API有调用频率限制。虽然对于个人使用通常不会触发，但在编写循环脚本或高频查询时需要注意。如果收到429 Too Many Requests错误，请暂停一段时间再试。
• 输出过滤：list类命令可能会返回大量数据。尽量使用--start-date、--end-date、--search、--limit等参数来缩小结果集，提高响应速度和可读性。
• 技能更新：定期进入技能目录 (~/.claude/skills/pocketsmith) 执行git pull拉取最新代码，然后uv sync更新依赖，以获取新功能和错误修复。

7. 开发与贡献：如果你想让技能更强大

pocketsmith-skill本身是一个开源项目，如果你发现缺少某个急需的API功能，或者想改进现有功能，完全可以参与到开发中。

项目结构速览： 通常这类技能项目会遵循类似的结构：

pocketsmith-skill/ ├── pocketsmith/ # 主Python包目录 │ ├── __init__.py │ ├── cli.py # 命令行接口主入口 │ ├── api.py # PocketSmith API客户端封装 │ └── commands/ # 各个子命令的实现模块 ├── tests/ # 单元测试 ├── pyproject.toml # 项目依赖和元数据 └── README.md # 项目说明文档

添加一个新命令的典型流程：

1. 在commands/目录下创建新模块，例如accounts.py用于管理账户。
2. 实现命令函数：使用typer或click库定义命令和参数。
3. 在api.py中扩展客户端：添加对应PocketSmith API端点的方法。
4. 在cli.py中注册新命令：将新模块的命令添加到主命令组。
5. 编写测试：在tests/目录下添加相应的单元测试。
6. 提交Pull Request：在GitHub上fork原项目，提交你的修改。

本地开发与测试：

# 进入项目目录 cd ~/.claude/skills/pocketsmith # 安装开发依赖 uv sync --extra dev # 运行测试 uv run pytest tests/ -v # 直接运行开发中的技能 uv run pocketsmith --help

参与开源贡献不仅能解决你自己的需求，也能帮助到更多有同样需求的PocketSmith用户。在开始编码前，建议先阅读项目的IMPLEMENTATION_NOTES.md和CONTRIBUTING.md（如果有的话），了解现有的代码风格和API覆盖情况。

这个技能的精妙之处在于，它用一个相对轻量的封装，在强大的AI助手和专业的个人财务工具之间架起了一座稳固的桥梁。它不试图包办一切，而是专注于提供最常用、最核心的API操作，并通过“默认安全”和“自然语言友好”的设计，让高级功能的门槛降到了最低。无论是作为日常查询的快捷方式，还是作为自动化流程的组件，它都能显著提升财务管理的效率和乐趣。