| name | bank-calc-utils |
| description | 银行经营分析专用计算工具集。当用户要求计算同比增速、环比变动率、贡献度占比、结构分布、排名百分位、不良率、拨备覆盖率、净息差等银行核心指标时使用。提供确定性数值计算，避免LLM心算幻觉。 |
银行业务通用计算工具集
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. 默认分析框架
本工具不执行分析框架，仅提供计算服务。调用方式：
- 确认计算类型：从支持的操作中选择对应类型
- 准备输入数据：按计算类型要求提供数值参数
- 调用计算脚本：执行
scripts/calc.py 中对应的计算函数
- 获取精确结果：返回带精度和单位的计算结果
- 校验结果合理性：自动进行加总校验和边界检查
调用示例：
# 计算变动率
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. 上游依赖
9. 可联动下游 Skills
- 被所有需要数值计算的 Skills 调用，包括但不限于：
- business-metrics-attribution：经营指标归因分析
- branch-performance-benchmarking：网点经营对比分析
- deposit-growth-attribution：存款增长归因分析
- loan-structure-analysis：贷款结构分析
