Bank Calc Utils

---
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. 默认分析框架

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

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**：贷款结构分析