aifinlab/bank-calc-utils

银行业务通用计算工具集

1. 业务问题

银行经营分析涉及大量数值计算：同比增长率、环比变动率、贡献度拆解、结构占比、集中度指标、排名百分位等。LLM在直接进行数值运算时容易产生幻觉（心算错误），尤其在多步计算和大数运算场景下。本工具集提供确定性的计算脚本，确保所有数值结果精确可靠，为上层分析技能提供可信赖的计算基础设施。

2. 适用场景

• 经营指标的同比、环比、较年初变动率计算
• 各维度对总量变动的贡献额和贡献率计算
• 贷款/存款/收入等指标的结构占比计算
• 机构/产品/客群的排名和百分位计算
• 行业集中度（CR5/CR10/HHI）计算
• 不良率、拨备覆盖率、净息差等银行核心比率计算
• 分项加总验证和交叉校验

3. 输入

| 输入项 | 说明 | 是否必须 | |--------|------|----------| | 计算类型 | percentage / change_rate / contribution / distribution / top_n / rank | 必须 | | 数值参数 | 根据计算类型提供对应的数值（当期值、基期值、分项值等） | 必须 | | 精度要求 | 小数位数（默认2位） | 可选 | | 单位 | 万元/亿元/百分比/BP | 可选 |

支持的计算操作

| 操作 | 说明 | 典型银行应用场景 | |------|------|-----------------| | percentage | 计算百分比（部分/整体） | 存款占比、不良率、产品渗透率 | | change_rate | 计算变动率（同比/环比/较年初） | 存款增速、利润变动率、客户增长率 | | contribution | 计算各分项对总量变动的贡献度 | 各机构对存款增量的贡献、各产品对收入增长的贡献 | | distribution | 计算分布结构（各项占比） | 贷款行业分布、期限结构、客群结构 | | top_n | 取前N项及其合计占比 | 前十大客户集中度、前五大行业占比 | | rank | 排名及百分位计算 | 网点排名、客户经理业绩排名 |

4. 输出

• 计算结果：精确的数值结果，附带单位和精度说明
• 计算过程：关键中间步骤（便于审核和验证）
• 校验信息：加总校验、合理性校验的结果（如占比合计是否为100%）

5. 默认分析维度

本工具为计算基础设施，不独立进行分析。默认支持以下银行业务计算场景：

• 规模类计算：余额、增量、变动额
• 比率类计算：增长率、占比、渗透率、不良率、覆盖率
• 贡献类计算：贡献额、贡献率、拉动百分点
• 集中度计算：CR5、CR10、HHI指数
• 排名类计算：排名序号、百分位、分位数

6. 默认分析框架

本工具不执行分析框架，仅提供计算服务。调用方式：

1. 确认计算类型：从支持的操作中选择对应类型
2. 准备输入数据：按计算类型要求提供数值参数
3. 调用计算脚本：执行 scripts/calc.py 中对应的计算函数
4. 获取精确结果：返回带精度和单位的计算结果
5. 校验结果合理性：自动进行加总校验和边界检查

调用示例：

# 计算变动率
python scripts/calc.py change_rate --current 1250.5 --base 1180.3

# 计算贡献度
python scripts/calc.py contribution --total_change 70.2 --items '{"分行A": 35.1, "分行B": 20.5, "分行C": 14.6}'

# 计算集中度
python scripts/calc.py top_n --values '{"客户1": 500, "客户2": 300, "客户3": 200, ...}' --n 5

7. 安全边界

• 不编造数据；不夸大结论；缺失信息标注"未获取"或"待核实"
• 不替代正式审批、正式风控、正式合规、正式报送、正式处置、正式责任认定、正式管理决策
• 计算结果的准确性依赖输入数据的正确性，输入数据由调用方负责校验
• 本工具仅提供数值计算，不对计算结果进行业务解读或决策建议
• 当输入数据存在异常（如除数为零、负值余额等）时，返回错误提示而非错误结果

8. 上游依赖

• 无（基础工具，不依赖其他 Skill）

9. 可联动下游 Skills

• 被所有需要数值计算的 Skills 调用，包括但不限于：
  • business-metrics-attribution：经营指标归因分析
  • branch-performance-benchmarking：网点经营对比分析
  • deposit-growth-attribution：存款增长归因分析
  • loan-structure-analysis：贷款结构分析