BOG 银行技能（只读）
通过对话帮助用户理解和管理其格鲁吉亚银行 Business Online
账户。附带工具（scripts/bog.py）负责数据访问并以 JSON 格式输出；您负责分析（分类、汇总、对账、标记异常）。适用于任何兼容 SKILL.md 的代理（Claude Code、Codex 等）。
严格规则
- 始终只读。 仅运行此处列出的
bog.py命令。绝不发送付款、转账、签署文件或调用任何写入端点——因为没有。如果被要求转账，请说明此技能是只读的，他们必须自行在 BOG 应用中完成（您可以帮他们准备）。 - 谨慎处理财务数据；除非被要求，否则应总结而非直接转储原始表格。
- 索要凭证时，切勿在回复中回显客户端密钥，也不要打印它。该工具会将其存储在本地。
运行工具
python3 scripts/bog.py <command> [options]
每次运行都会打印一个 JSON 对象：command、mode（live/mock）、ok，以及 data 或 error+message。解析它，然后用通俗语言回答。
每次会话：先检查状态
在执行任何需要数据的操作之前，请运行：
python3 scripts/bog.py whoami
ok: true且data.accounts_configured> 0 → 已完成设置；直接处理用户的请求。切勿再次索要凭据或已存储的 IBAN。ok: true但accounts_configured为0→ 密钥有效，但尚无账户 → 执行第 6 步的引导（添加 IBAN）。error: "no_keys"→ 全新用户 → 运行下方的首次设置。error: "invalid_credentials"→ 密钥被拒绝 → 参见第 5 步。
首次设置（引导）——引导用户一次完成此过程
态度要热情，一步一步来。完整的逐步说明（包含确切的 BOG 界面和链接）在 reference/getting-credentials.md 中——用自己的话转述，并向用户提供下面的链接。
第 1 步——解释并安慰。 告诉他们此技能是只读的（绝对不会转移资金），并且您需要从格鲁吉亚银行获取两样东西：一个客户端 ID 和一个客户端密钥。
第 2 步——登录。 要求他们使用 Business Online 凭据登录其商业银行网站 **https://bonline.bog.ge/**。
第 3 步——创建 API 密钥。 让他们打开 **https://bonline.bog.ge/admin/api**，点击**添加新**，然后：
- 集成类型——选择客户端凭据流程（使用客户端 ID + 客户端密钥自动授权的类型，无需用户名或密码）。
- API 客户端名称——任意名称（例如他们的网银用户名，或
Banking Assistant）。 - 使用一次性验证码 (OTP) 确认。
第 4 步——复制密钥。 BOG 会显示一个客户端 ID 和一个客户端密钥（某些界面可能标记为公钥/ 密钥——值相同）。让用户粘贴两者，然后保存——通过 stdin 传递 JSON，这样密钥就不会出现在命令行上：
python3 scripts/bog.py save-credentials <<'JSON'
{"client_id":"<Client ID>","client_secret":"<Client Secret>"}
JSON
切勿回显客户端密钥。
第 5 步——确认登录。 再次运行 whoami。
ok: true→ 密钥有效。继续执行第 6 步。error: "invalid_credentials"→ 要么密钥错误，或者用户的 BOG 银行客户经理尚未激活 API 访问权限。告诉他们这两种可能性，并提供重新输入选项（如果需要，先清除：python3 scripts/bog.py forget-credentials）。
第 6 步——添加第一个账户。 索要一个账户的 IBAN（例如 GE..BG...）。该信息在对账单和 BOG 应用中，而且不是秘密。不要索要币种。然后：
python3 scripts/bog.py add-account --iban <IBAN>
python3 scripts/bog.py discover --account <IBAN>
discover 会自动检测该 IBAN 持有的币种（GEL/USD/EUR/GBP）。
第 7 步——他们的第一个实时结果。 运行 balance 并以友好的方式呈现（参见呈现结果）。恭喜他们——设置完成——然后询问他们是否要添加另一个账户，并回答他们最初的问题。
想在密钥准备就绪前进行演示？
python3 scripts/bog.py --mock balance会返回逼真的示例数据，无需访问银行（始终说明这是示例数据）。
稍后设置/管理账户
BOG 无法列出公司的账户，因此您需要从用户那里收集 IBAN——一次一个，按需收集。添加始终是合并操作（现有 IBAN 会保留）。IBAN 会持久化，并在后续每次调用中重复使用——一旦 whoami 返回 ok，切勿再次索要已存储的 IBAN 或凭据。
- “添加另一个账户 GE..” →
add-account --iban <IBAN>然后discover --account <IBAN>（然后询问他们是否还要添加） - “移除/忘记账户 GE..” →
remove-account --iban <IBAN>（仅在用户明确要求时） - “你有什么账户？” →
accounts
只读命令
| 命令 | 返回 |
|---|---|
whoami | 凭据是否存在及是否有效 |
add-account --iban GE.. [--currency GEL] | 添加一个 IBAN（合并；保留直至移除） |
remove-account --iban GE.. [--currency GEL] | 移除一个 IBAN（或仅移除一个币种） |
discover [--account IBAN] [--currencies GEL,USD] | 探测已存储 IBAN 的币种，保存它们 |
accounts | 已存储的 IBAN 及其币种 |
balance [--account IBAN] [--currency GEL] | 可用余额 + 当前余额 |
statement [--account IBAN] [--currency GEL] [--from YYYY-MM-DD] [--to YYYY-MM-DD] | 某段时间内的交易（自动分页） |
today [--account IBAN] [--currency GEL] | 今天的当日活动 |
rates [--currency USD] | NBG 官方汇率 + BOG 商业买入/卖出价 |
默认 = 全部。 如果您不传递 --account/--currency，命令会自动覆盖每个已配置的 IBAN 及其持有的所有币种（它会自动检测币种）。仅当用户指定时（例如“我的美元余额”、“账户 GE..123”），才传递 --account 和/或 --currency。这些命令返回一个列表（每个 IBAN+币种对应一个条目）；对于该账户不持有的币种，条目可能带有 error——跳过这些条目即可。
进行汇总时，切勿对不同币种的金额求和——应分别报告每种币种（例如 GEL 总额和 USD 总额）。
示例
- “我的余额是多少？”→
balance（覆盖所有账户和币种） - “我的美元余额？”→
balance --currency USD - “上个月的交易”→
statement --from 2026-05-01 --to 2026-05-31 - “我支付给<供应商>多少钱？”→ 运行
statement，然后自行筛选/统计。 - “有什么异常吗？”→ 运行
statement，然后标记重复项、整数金额、新的交易对手、意外的大额金额。 - “美元汇率？”→
rates --currency USD
模拟模式
传递 --mock（或设置 BOG_MOCK=1）以返回逼真的示例数据，无需访问银行——在用户凭据就绪前用于演示技能。当结果为示例数据时，务必告知用户。
呈现结果
- 金额使用千位分隔符加两位小数格式化（例如
18,430.75 GEL）。 - 先给出答案，然后进行简短分解；说明分组假设。
- 对于对账，明确标记可能的重复项、异常大额、新的/未知的交易对手以及整数付款。
完整的凭证操作指南请参见 reference/getting-credentials.md，底层 BOG 端点信息请参见 reference/endpoints.md。