coder-firefly-cli 1.0.0__tar.gz → 1.0.1__tar.gz

coder_firefly_cli-1.0.1/PKG-INFO

@@ -0,0 +1,512 @@
+Metadata-Version: 2.4
+Name: coder-firefly-cli
+Version: 1.0.1
+Summary: Firefly III CLI - 个人财务管理命令行工具
+Home-page: https://github.com/joyous-coder/coder-firefly-cli
+Author: coder
+Author-email: coder@example.com
+License: MIT
+Keywords: firefly-iii cli finance personal-finance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# coder-firefly-cli
+
+Firefly III CLI - 个人财务管理命令行工具
+
+通过命令行连接和管理 Firefly III 个人财务管理系统，支持账户、交易、预算、分类、标签、账单、储蓄罐等全面管理。
+
+## 安装
+
+### 方式一：通过 PyPI 安装（推荐）
+
+```bash
+pip install coder-firefly-cli
+```
+
+### 方式二：通过 GitHub 安装
+
+```bash
+pip install git+https://github.com/joyous-coder/coder-firefly-cli.git
+```
+
+### 方式三：本地开发安装
+
+```bash
+git clone https://github.com/joyous-coder/coder-firefly-cli.git
+cd coder-firefly-cli
+pip install -e .
+```
+
+## 安装为 Skill（AI Agent 使用）
+
+如果你需要将本工具作为 AI Agent 的 Skill 使用，可以将 `SKILL.md` 文件配置到 AI 系统中。
+
+### OhMyOpenCode / CLI-Anything 环境
+
+将本仓库作为 Skill 添加到配置中：
+
+```bash
+# 克隆仓库
+git clone https://github.com/joyous-coder/coder-firefly-cli.git
+
+# 在 skill 配置中引用 SKILL.md 文件路径
+# 或直接复制 SKILL.md 内容到 skill 配置
+```
+
+### 通用 AI 工具集成
+
+1. 获取 `SKILL.md` 文件内容
+2. 在 AI 系统中配置为可用工具/Skill
+3. 配置环境变量 `FIREFLY_BASE_URL` 和 `FIREFLY_PAT`
+4. AI 将自动识别并使用 `coder-firefly-cli` 命令
+
+## 前提条件
+
+- Python 3.10+
+- 运行中的 Firefly III 实例
+- Personal Access Token (PAT)
+
+## 配置
+
+### 环境变量（推荐）
+
+```bash
+export FIREFLY_BASE_URL="https://firefly.yourdomain.com"
+export FIREFLY_PAT="your-personal-access-token"
+```
+
+### 命令行参数
+
+```bash
+coder-firefly-cli --base-url https://firefly.yourdomain.com --pat your-token accounts list
+```
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--json` | 以 JSON 格式输出结构化数据 |
+| `--base-url` | Firefly III 实例地址 |
+| `--pat` | Personal Access Token |
+| `--help` | 查看帮助信息 |
+
+## 命令组
+
+| 命令组 | 说明 | 对应 API |
+|--------|------|----------|
+| `accounts` | 账户管理（资产、支出、收入、负债） | `/api/v1/accounts` |
+| `transactions` | 交易管理（支出、收入、转账） | `/api/v1/transactions` |
+| `budgets` | 预算管理（含预算限额） | `/api/v1/budgets` |
+| `categories` | 分类管理 | `/api/v1/categories` |
+| `tags` | 标签管理 | `/api/v1/tags` |
+| `bills` | 账单管理 | `/api/v1/bills` |
+| `piggy-banks` | 储蓄罐管理 | `/api/v1/piggy-banks` |
+| `insights` | 财务洞察报告（支出/收入/转账分析） | `/api/v1/insight/*` |
+| `search` | 搜索交易 | `/api/v1/search/*` |
+| `info` | 系统信息 | `/api/v1/about` |
+
+## 详细命令参考
+
+### accounts - 账户管理
+
+```bash
+# 列出所有账户
+coder-firefly-cli accounts list
+
+# 按类型筛选（asset/expense/revenue/liability）
+coder-firefly-cli accounts list --type asset
+
+# 分页查询
+coder-firefly-cli accounts list --limit 10 --page 1
+
+# 获取账户详情
+coder-firefly-cli accounts get --id 123
+
+# 创建资产账户
+coder-firefly-cli accounts create --name "现金" --type asset --currency-code CNY --opening-balance 1000
+
+# 创建支出账户
+coder-firefly-cli accounts create --name "餐饮" --type expense
+
+# 更新账户
+coder-firefly-cli accounts update --id 123 --name "新名称"
+
+# 删除账户（会提示确认）
+coder-firefly-cli accounts delete --id 123
+```
+
+### transactions - 交易管理
+
+```bash
+# 列出最近交易
+coder-firefly-cli transactions list
+
+# 分页和日期范围
+coder-firefly-cli transactions list --limit 20 --start 2024-01-01 --end 2024-01-31
+
+# 按类型筛选（withdrawal/deposit/transfer）
+coder-firefly-cli transactions list --type withdrawal
+
+# 按账户筛选
+coder-firefly-cli transactions list --source-account 1
+
+# 创建支出交易
+coder-firefly-cli transactions create --description "超市购物" --amount 150.00 --source-account 1 --category "生活"
+
+# 创建转账
+coder-firefly-cli transactions create --description "转账到支付宝" --amount 500.00 --source-account 1 --destination-account 2 --type transfer
+
+# 创建带标签的交易
+coder-firefly-cli transactions create --description "午餐" --amount 35.00 --source-account 1 --tags "餐饮,工作日"
+
+# 获取交易详情
+coder-firefly-cli transactions get --id 456
+
+# 更新交易
+coder-firefly-cli transactions update --id 456 --description "更新后的描述" --amount 160.00
+
+# 删除交易（会提示确认）
+coder-firefly-cli transactions delete --id 456
+```
+
+### budgets - 预算管理
+
+```bash
+# 列出所有预算
+coder-firefly-cli budgets list
+
+# 创建预算
+coder-firefly-cli budgets create --name "餐饮预算" --notes "每月餐饮支出上限"
+
+# 获取预算详情
+coder-firefly-cli budgets get --id 1
+
+# 更新预算
+coder-firefly-cli budgets update --id 1 --name "新餐饮预算"
+
+# 删除预算（会提示确认）
+coder-firefly-cli budgets delete --id 1
+
+# 查看预算限额
+coder-firefly-cli budgets limits --budget-id 1
+
+# 创建预算限额
+coder-firefly-cli budgets limit-create --budget-id 1 --amount 2000 --start 2024-01-01 --end 2024-01-31 --currency-code CNY
+
+# 更新预算限额
+coder-firefly-cli budgets limit-update --id 10 --amount 2500
+
+# 删除预算限额（会提示确认）
+coder-firefly-cli budgets limit-delete --id 10
+```
+
+### categories - 分类管理
+
+```bash
+# 列出所有分类
+coder-firefly-cli categories list
+
+# 创建分类
+coder-firefly-cli categories create --name "餐饮" --notes "日常餐饮"
+
+# 获取分类详情
+coder-firefly-cli categories get --id 1
+
+# 更新分类
+coder-firefly-cli categories update --id 1 --name "日常餐饮"
+
+# 删除分类（会提示确认）
+coder-firefly-cli categories delete --id 1
+```
+
+### tags - 标签管理
+
+```bash
+# 列出所有标签
+coder-firefly-cli tags list
+
+# 创建标签
+coder-firefly-cli tags create --tag "重要" --description "重要支出标记"
+
+# 获取标签详情
+coder-firefly-cli tags get --id "重要"
+
+# 更新标签
+coder-firefly-cli tags update --id "重要" --description "更新后的描述"
+
+# 删除标签（会提示确认）
+coder-firefly-cli tags delete --id "重要"
+```
+
+### bills - 账单管理
+
+```bash
+# 列出所有账单
+coder-firefly-cli bills list
+
+# 创建账单
+coder-firefly-cli bills create --name "房租" --amount-min 3000 --amount-max 3000 --date 2024-01-01 --repeat-freq monthly
+
+# 获取账单详情
+coder-firefly-cli bills get --id 1
+
+# 更新账单
+coder-firefly-cli bills update --id 1 --amount-min 3200
+
+# 删除账单（会提示确认）
+coder-firefly-cli bills delete --id 1
+```
+
+### piggy-banks - 储蓄罐管理
+
+```bash
+# 列出所有储蓄罐
+coder-firefly-cli piggy-banks list
+
+# 创建储蓄罐
+coder-firefly-cli piggy-banks create --name "旅行基金" --account-id 1 --target-amount 10000 --current-amount 2000 --target-date 2024-12-31
+
+# 获取储蓄罐详情
+coder-firefly-cli piggy-banks get --id 1
+
+# 更新储蓄罐
+coder-firefly-cli piggy-banks update --id 1 --current-amount 2500
+
+# 删除储蓄罐（会提示确认）
+coder-firefly-cli piggy-banks delete --id 1
+```
+
+### insights - 财务洞察
+
+```bash
+# 支出洞察
+coder-firefly-cli insights expense --start 2024-01-01 --end 2024-01-31
+
+# 收入洞察
+coder-firefly-cli insights income --start 2024-01-01 --end 2024-01-31
+
+# 转账洞察
+coder-firefly-cli insights transfer --start 2024-01-01 --end 2024-01-31
+
+# 按账户筛选洞察
+coder-firefly-cli insights expense --start 2024-01-01 --end 2024-01-31 --accounts "1,2"
+
+# 按分类筛选洞察
+coder-firefly-cli insights expense --start 2024-01-01 --end 2024-01-31 --categories "3,4"
+```
+
+### search - 搜索
+
+```bash
+# 搜索交易
+coder-firefly-cli search transactions --query "超市"
+
+# 分页搜索
+coder-firefly-cli search transactions --query "餐饮" --limit 10 --page 2
+```
+
+### info - 系统信息
+
+```bash
+# 获取系统信息
+coder-firefly-cli info about
+
+# 检查连接状态
+coder-firefly-cli info status
+```
+
+## JSON 输出
+
+所有命令都支持 `--json` 参数以结构化格式输出：
+
+```bash
+# 查看账户列表的 JSON 输出
+coder-firefly-cli --json accounts list
+
+# 查看交易详情的 JSON 输出
+coder-firefly-cli --json transactions get --id 456
+
+# 查看洞察报告的 JSON 输出
+coder-firefly-cli --json insights expense --start 2024-01-01 --end 2024-01-31
+```
+
+JSON 输出便于脚本处理和数据分析，所有字段都以标准 JSON 格式返回。
+
+## 常见工作流示例
+
+### 查看账户余额
+
+```bash
+# 1. 检查连接
+coder-firefly-cli info status
+
+# 2. 列出资产账户
+coder-firefly-cli accounts list --type asset
+
+# 3. 查看账户详情（获取余额）
+coder-firefly-cli accounts get --id <account_id>
+```
+
+### 记录日常支出
+
+```bash
+# 1. 查找支出账户
+coder-firefly-cli accounts list --type expense
+
+# 2. 创建支出交易
+coder-firefly-cli transactions create \
+  --description "午餐" \
+  --amount 35.00 \
+  --source-account <asset_account_id> \
+  --category "餐饮" \
+  --tags "工作日"
+```
+
+### 月度财务报告
+
+```bash
+# 1. 支出报告
+coder-firefly-cli --json insights expense --start 2024-01-01 --end 2024-01-31
+
+# 2. 收入报告
+coder-firefly-cli --json insights income --start 2024-01-01 --end 2024-01-31
+
+# 3. 搜索特定交易
+coder-firefly-cli --json search transactions --query "超市" --start 2024-01-01 --end 2024-01-31
+```
+
+### 预算管理
+
+```bash
+# 1. 创建预算
+coder-firefly-cli budgets create --name "餐饮预算"
+
+# 2. 设置预算限额
+coder-firefly-cli budgets limit-create \
+  --budget-id 1 \
+  --amount 2000 \
+  --start 2024-01-01 \
+  --end 2024-01-31
+
+# 3. 查看预算使用情况
+coder-firefly-cli budgets limits --budget-id 1
+```
+
+## 故障排除
+
+### 连接失败
+
+```
+错误: 无法连接到 Firefly III 实例
+```
+
+检查：
+1. Firefly III 实例是否正在运行
+2. 基础 URL 是否正确（注意结尾不要带斜杠）
+3. 网络连接是否正常
+
+### 认证失败
+
+```
+错误: 认证失败: Personal Access Token 无效
+```
+
+检查：
+1. PAT 是否正确
+2. PAT 是否已过期
+3. 在 Firefly III 的 选项 > 个人资料 > OAuth 中生成新的 PAT
+
+### 数据格式问题
+
+```
+错误: 请求参数错误
+```
+
+检查：
+1. 金额是否为字符串格式（如 "100.00"）
+2. 日期格式是否为 YYYY-MM-DD
+3. 必需参数是否都已提供
+
+### 资源未找到
+
+```
+错误: 资源未找到
+```
+
+检查：
+1. ID 是否正确
+2. 资源是否存在（可能已被删除）
+
+## 开发
+
+```bash
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 带覆盖率报告
+pytest --cov=src
+
+# 代码格式化
+black src/
+```
+
+## 项目结构
+
+```
+coder-firefly-cli/
+├── setup.py              # 包安装配置
+├── requirements.txt      # 依赖列表
+├── README.md             # 项目文档
+├── SKILL.md              # AI Agent Skill 文档
+├── .github/
+│   └── workflows/
+│       └── publish.yml   # GitHub Actions 自动发布
+└── src/
+    ├── api_client.py     # Firefly III API 客户端
+    ├── cli.py            # CLI 主入口
+    └── commands/         # 命令模块
+        ├── accounts.py
+        ├── bills.py
+        ├── budgets.py
+        ├── categories.py
+        ├── info.py
+        ├── insights.py
+        ├── piggy_banks.py
+        ├── search.py
+        ├── tags.py
+        └── transactions.py
+```
+
+## 许可证
+
+MIT License