名称： pocketsmith
描述： 通过 API 管理 PocketSmith 的交易、分类和财务数据
元数据： {"openclaw": {"category": "finance", "requires": {"env": ["POCKETSMITH_DEVELOPER_KEY"]}, "optional_env": ["POCKETSMITH_ALLOW_WRITES"]}}

PocketSmith 技能

管理 PocketSmith 的交易与分类。支持财务数据的列表、搜索、创建、更新和删除操作。

前置条件

设置以下环境变量：
- POCKETSMITH_DEVELOPER_KEY - 你的 PocketSmith 开发者密钥（从“设置”>“安全”>“管理开发者密钥”获取）
- POCKETSMITH_ALLOW_WRITES - 设置为 true 以启用创建、更新和删除操作（默认禁用以确保安全）

命令

所有命令均需在技能目录下使用 uv run pocketsmith 运行。

认证

# 检查认证状态并获取用户信息
pocketsmith auth status

# 获取当前用户详情
pocketsmith me

交易

# 获取单笔交易
pocketsmith transactions get <transaction_id>

# 列出用户的交易
pocketsmith transactions list-by-user <user_id>
pocketsmith transactions list-by-user <user_id> --start-date 2024-01-01 --end-date 2024-12-31
pocketsmith transactions list-by-user <user_id> --search "coffee"
pocketsmith transactions list-by-user <user_id> --uncategorised
pocketsmith transactions list-by-user <user_id> --needs-review
pocketsmith transactions list-by-user <user_id> --type debit

# 按账户列出交易
pocketsmith transactions list-by-account <account_id>

# 按分类列出交易
pocketsmith transactions list-by-category <category_ids>  # 逗号分隔

# 按交易账户列出交易
pocketsmith transactions list-by-transaction-account <transaction_account_id>

# 创建交易（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith transactions create <transaction_account_id> --payee "商店名称" --amount -50.00 --date 2024-01-15
pocketsmith transactions create <transaction_account_id> --payee "工资" --amount 5000.00 --date 2024-01-01 --category-id 123

# 更新交易（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith transactions update <transaction_id> --category-id 456
pocketsmith transactions update <transaction_id> --payee "新收款方" --note "更新备注"
pocketsmith transactions update <transaction_id> --labels "groceries,essential"

# 删除交易（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith transactions delete <transaction_id>

分类

# 获取单个分类
pocketsmith categories get <category_id>

# 列出用户的所有分类
pocketsmith categories list <user_id>

# 创建分类（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith categories create <user_id> --title "新分类"
pocketsmith categories create <user_id> --title "子分类" --parent-id 123
pocketsmith categories create <user_id> --title "账单" --colour "#ff0000" --is-bill true

# 更新分类（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith categories update <category_id> --title "重命名分类"
pocketsmith categories update <category_id> --parent-id 456
pocketsmith categories update <category_id> --no-parent  # 设为顶级分类
pocketsmith categories update <category_id> --colour "#00ff00"

# 删除分类（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith categories delete <category_id>

标签

# 列出用户的所有标签
pocketsmith labels list <user_id>

预算

# 列出用户的预算（按分类的预算分析）
pocketsmith budget list <user_id>
pocketsmith budget list <user_id> --roll-up true

# 获取用户的预算摘要
pocketsmith budget summary <user_id> --period months --interval 1 --start-date 2024-01-01 --end-date 2024-12-31

# 获取趋势分析（需要分类和场景 ID）
pocketsmith budget trend <user_id> --period months --interval 1 --start-date 2024-01-01 --end-date 2024-12-31 --categories "123,456" --scenarios "1,2"

# 刷新预测缓存（需 POCKETSMITH_ALLOW_WRITES=true）
pocketsmith budget refresh <user_id>

交易筛选选项

列出交易时，可使用以下筛选器：
- --start-date - 起始日期（YYYY-MM-DD）
- --end-date - 结束日期（YYYY-MM-DD）
- --updated-since - 仅显示此日期时间后更新的交易
- --uncategorised - 仅显示未分类的交易
- --type - 按类型筛选：debit 或 credit
- --needs-review - 仅显示需要审核的交易
- --search - 收款方/备注的搜索词
- --page - 分页页码

分类选项

创建/更新分类时：
- --title - 分类名称
- --colour - CSS 十六进制颜色（例如 #ff0000）
- --parent-id - 子分类的父分类 ID
- --no-parent - 将分类设为顶级（仅更新时可用）
- --is-transfer - 标记为转账分类（true/false）
- --is-bill - 标记为账单分类（true/false）
- --roll-up - 汇总到父分类（true/false）
- --refund-behaviour - debit_only 或 credit_only

输出格式

所有命令均输出 JSON 格式。交易示例：

{
  "id": 1234567,
  "payee": "咖啡店",
  "amount": -5.50,
  "date": "2024-01-15",
  "category": {
    "id": 123,
    "title": "外出就餐"
  },
  "transaction_account": {
    "id": 456,
    "name": "支票账户"
  }
}

日期格式

所有日期均使用 YYYY-MM-DD 格式（例如 2024-01-15）。

写操作保护

写操作（创建、更新、删除）默认禁用以确保安全。启用方法：

export POCKETSMITH_ALLOW_WRITES=true

未启用时，写操作命令将失败并返回：

{"error": "写操作默认禁用。设置 POCKETSMITH_ALLOW_WRITES=true 以启用创建、更新和删除操作。", "hint": "export POCKETSMITH_ALLOW_WRITES=true"}

常用工作流

搜索与分类交易

# 查找未分类的交易
pocketsmith transactions list-by-user 123456 --uncategorised

# 搜索特定交易
pocketsmith transactions list-by-user 123456 --search "Netflix"

# 为交易分类
pocketsmith transactions update 789012 --category-id 456

组织分类

# 列出已有分类
pocketsmith categories list 123456

# 创建新的子分类
pocketsmith categories create 123456 --title "流媒体" --parent-id 789

# 将分类移至其他父分类下
pocketsmith categories update 101112 --parent-id 789

审核交易

# 查找需要审核的交易
pocketsmith transactions list-by-user 123456 --needs-review

# 通过更新标记为已审核
pocketsmith transactions update 789012 --needs-review false