byted-volcengine-finops

Files (10)

• SKILL.md
• billing-api-notes.md · references/
• install.md · references/
• product-code.md · references/
• common.py · scripts/
• list_amortized_cost_bill_detail.py · scripts/
• list_bill_detail.py · scripts/
• list_bill_overview_by_category.py · scripts/
• list_bill_overview_by_prod.py · scripts/
• list_split_bill_detail.py · scripts/

SKILL.md (first lines)

# 火山引擎账单 Skill

这个 Skill 用于通过火山引擎 Python SDK 查询费用中心账单数据，并围绕账期、分摊月、日期、实例、产品、账号、分账维度做汇总分析。

## 何时使用此 Skill

当用户要求：

- 分析火山引擎账单、成本和消费趋势的时候
- 查询账号维度账单总览信息的时候
- 查询产品维度成本分布的时候
- 核对账单明细、实例费用或账单类型的时候
- 查询分摊后成本、摊销成本或成本账单明细的时候
- 查询分账账单、分拆项费用或分摊结果的时候

## 主要功能

### 1. 账号账单总览查询

- 使用 `ListBillOverviewByCategory` 查询账号维度账单总览
- 适合先看整月整体账单金额和大盘趋势

### 2. 产品月度账单查询

- 使用 `ListBillOverviewByProd` 查询单产品、多产品、全量产品月度账单
- 支持分页获取完整产品列表
- 适合识别高成本产品和主要费用来源

### 3. 账单明细与分账查询

- 使用 `ListBillDetail` 查询账单明细
- 使用 `ListAmortizedCostBillDetail` 查询成本账单明细
- 使用 `ListSplitBillDetail` 查询分账账单
- 支持按账期、分摊月、日期、产品、账号、实例、分拆项筛选

### 4. 配置与调用方式

- 支持环境变量配置 `AK/SK`
- 支持 `.env` 文件配置
- 支持 Python 代码调用
- 支持通过 `scripts/` 下的独立脚本直接调用
- 支持分页拉取与本地汇总分析
- 支持 JSON 结构化结果处理

## 处理逻辑

### 账单查询处理流程

1. **根据用户目标确定接口**
   - 整体账单使用 `ListBillOverviewByCategory`
   - 产品月度账单使用 `ListBillOverviewByProd`
   - 明细核对使用 `ListBillDetail`
   - 成本明细使用 `ListAmortizedCostBillDetail`
   - 分账排查使用 `ListSplitBillDetail`
2. **根据时间要求确定账期与日期范围**
   - 优先确定 `BillPeriod`
   - 成本账单优先确定 `AmortizedMonth`
   - 需要单日细查时补充 `ExpenseDate`
   - 成本账单按日细查时补充 `AmortizedDay`
   - 跨月查询需要拆成多个账期分别查询
3. **根据过滤条件组装 SDK 请求参数**
   - 例如产品、账号、实例、账单类型、分拆项等
4. **如为分页接口则循环查询**
   - 使用 `Offset + Limit + NeedRecordNum` 分页拉全量
   - 可使用 `common.py` 中的 `fetch_all_pages` 工具函数自动翻页
5. **对结果做汇总分析**
   - 输出金额、排行、异常波动和待核对项

## 前置要求

需要安装火山引擎 Python SDK：

```bash
pip install --upgrade "volcengine-python-sdk>=5.0.30"
```

说明：

- 建议使用 5.x 最新版本
- 历史版本 `4.0.1 ~ 4.0.42` 存在 SDK 重试缺陷，尽量不要继续使用

## 配置方式

需要配置火山引擎的 Access Key 和 Secret Key。推荐使用以下两种方式之一：

### 方式 1：环境变量

```bash
export VOLCENGINE_AK="your-ak"
export VOLCENGINE_SK="your-sk"
export VOLCENGINE_REGION="cn-beijing"
```

### 方式 2：`.env` 文件

在 `~/.openclaw/workspace/.env` 中配置：

```env
VOLCENGINE_AK=your-ak
VOLCENGINE_SK=your-sk
VOLCENGINE_REGION=cn-beijing
```

## 账单参数说明

### 账单查询核心参数

- **BillPeriod**: 账务账期，格式为 `YYYY-MM`
- **ExpenseDate**: 账单日期，格式为 `YYYY-MM-DD`
- **AmortizedMonth**: 分摊月，格式为 `YYYY-MM`
- **AmortizedDay**: 分摊日，格式为 `YYYY-MM-DD`
- **Offset**: 分页偏移量
- **Limit**: 单页数量，范围 `[1,300]`
- **NeedRecordNum**: 是否返回总记录数，`1` 返回 `Total`，否则常为 `-1`
- **IgnoreZero**: 是否忽略折后价为 0 的数据，`0` 不忽略、`1` 忽略
- **Product**: 产品筛选条件。可选的产品 Code 请参考 `references/product-code.md`

### 关键参数枚举值

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples