firefly-iii-billing

name: firefly-iii-billing description: 当用户明确要把流水录入 Firefly III、补录历史账、根据 Firefly III 里的交易做查询/修正/删除、维护账户/分类/预算/标签、检查预算闭环、追查漏挂预算或基于 Firefly III 数据做支出分析时，优先使用这个技能。即使用户没直说 “Firefly III”，只要目标是操作 Firefly III 中已有或即将写入的数据，也应触发。不要把它用于一般性的理财建议、投资建议、税务建议或与 Firefly III 数据无关的泛财务讨论。账单、存钱罐、附件等扩展能力归入第二阶段。

Firefly III 记账技能

这个入口文件负责两件事：

1. 判断用户当前属于哪一类 Firefly III 财务任务
2. 指挥 agent 读取正确的功能模块，再按模块流程执行

这里不展开具体 CLI 参数细节；参数、payload 规则和边界条件都在对应模块里。 文档里的命令示例统一使用 python3 scripts/firefly_client.py ... 调用，不要省略 python3。

触发场景

• 用户用文字描述交易，例如“刚打车花了 20”
• 用户上传收据、发票、支付截图、账单图片，希望识别后记账
• 用户要查询、编辑、删除交易
• 用户要维护账户、分类、预算、标签等主数据
• 用户要看预算、分类、账户趋势或记账完整性分析
• 用户明确要求账单、存钱罐、附件等第二阶段能力
• 用户说“记到 Firefly III / Firefly / 火萤 / 账本里”
• 用户想补历史流水、查漏记、找没挂预算/分类/标签的交易
• 用户要解释“为什么这个预算超了”“这个月还剩多少预算”“钱花去哪了”

如果请求明显是一般性的理财建议、投资建议、税务建议，而不是围绕 Firefly III 中已有或待录入的数据操作，则不要强行使用本技能。

使用顺序

1. 先识别用户要做的是哪一类任务。
2. 再读取对应的 skills/*.md 功能模块。
3. 严格按对应模块中的流程、命令说明和约束执行。

不要在未读取功能模块前直接调用 CLI。

决策流程

按下面顺序判断：

1. 用户是在“新增交易/补账”吗？ 读取 skills/record.md
2. 用户是在“查交易/改交易/删交易/搜交易/列账户”吗？ 读取 skills/manage.md
3. 用户是在“建或维护账户、分类、预算、标签、预算额度”吗？ 读取 skills/masterdata.md
4. 用户是在“看汇总、趋势、分类占比、预算剩余、预算超支原因、漏挂预算”吗？ 读取 skills/report.md
5. 用户明确提到账单、存钱罐、附件上传等扩展能力吗？ 读取 skills/finance.md

跨域任务允许串联多个模块，但每一步都要基于上一模块得到的真实 ID、明细或分析结果继续，不要跳步猜测。

功能分发

按用户意图加载对应文件：

• 记账（文字描述、图片识别、多笔交易录入）：skills/record.md
• 交易查询、搜索、详情、更新、删除、账户列表：skills/manage.md
• 主数据管理（账户、分类、预算、标签、预算额度维护）：skills/masterdata.md
• 汇总分析、预算分析、分类洞察、账户趋势、预算漏挂检查：skills/report.md
• 账单、存钱罐、附件、其他第二阶段能力：skills/finance.md

如果用户请求跨多个领域，例如“先查出没挂预算的交易，再顺手补一个预算”，按顺序加载多个模块，并以前一个模块得到的结果作为后一个模块输入。

通用规则

• CLI 统一从技能目录旁的 config.json 读取实例地址和 token；执行命令时不要再追加 <TOKEN> 参数；新环境参考 config.example.json
• 命令示例统一写成 python3 scripts/firefly_client.py ...，不要直接把 scripts/firefly_client.py 当可执行文件调用
• 自动新建开关包括：
  • FIREFLY_III_AUTO_CREATE_ACCOUNTS
  • FIREFLY_III_AUTO_CREATE_CATEGORIES
  • FIREFLY_III_AUTO_CREATE_TAGS
  • FIREFLY_III_AUTO_CREATE_BUDGETS
  • FIREFLY_III_AUTO_CREATE_PIGGY_BANKS
• 若某项自动新建开关为 false，必须先读取现有对象列表或自动补全结果，再从已有对象中选择；不要臆造名称或 ID
• 若需要修改已有交易，优先先读取详情，再构造更新 payload
• 涉及预算分析时，优先使用 Firefly III 官方分析接口，不要先本地聚合替代
• 任何删除、批量更新、预算额度修改、图片识别结果提交，都先展示对象或结果，再执行
• 缺少时间、账户、预算等关键字段且无法可靠推断时，先追问；不要用占位值硬提

输出与交互要求

• 先给出你识别到的任务类型，再继续执行对应模块
• 需要用户确认时，明确列出将被创建、修改或删除的对象
• 成功后回报关键信息：交易 ID、预算 ID、账户名、日期范围、总额或影响范围
• 失败时优先说明是哪一层失败：配置、认证、资源不存在、payload 不合法、图片信息不足

隐私保护

严禁把生活类交易记录写入项目进展日志、日报或其他外部工作记录。此类数据仅保留在 Firefly III 系统内。

故障处理

• 图片识别不清晰：要求用户提供更清晰的图片
• 时间信息不足且无法可靠推断：向用户确认，不要用占位时间
• 账户、分类、预算、标签、存钱罐不存在：按自动新建开关和对应模块规则处理
• Firefly III 返回 HTTP 错误：优先检查 token、实例地址和服务可用性