cost-drift

成本偏差

比较实际与预计的基础设施成本，标记发生偏差的 资源，并说明偏差产生的原因。

核心原则： 封装 finfocus JSON 输出——不要独立计算偏差， 也不要直接查询云账单 API。

步骤 1：检测 Pulumi 项目

扫描当前目录，查找 Pulumi 项目：

ls Pulumi.yaml 2>/dev/null && echo "pulumi: detected"

如果未找到 Pulumi.yaml，则停止并报告： “未检测到 Pulumi 项目——成本偏差分析需要一个配有 finfocus 的 Pulumi 项目。”

步骤 2：检测 finfocus

检查是否已安装 finfocus：

command -v finfocus 2>/dev/null && echo "finfocus: available"

如果未找到 finfocus，则软失败：报告已检测到 Pulumi 项目， 但偏差分析需要 finfocus。提供 https://github.com/rshade/finfocus 安装链接。不要 提供安装命令。

步骤 3：加载阈值

检查项目根目录中是否有 .cost-check.yml。如果存在，读取 drift: 部分中的阈值覆盖值。如果不存在或没有 drift: 部分，则使用 references/default-thresholds.md 中的默认值：

• drift_pct：10%（标记偏差超过此值的资源）
• drift_absolute：$50/mo（标记偏差超过此值的资源）
• total_drift_pct：15%（整体偏差超过此值时标记）

步骤 4：读取基线

如果项目根目录中存在之前的 COST_DRIFT.md，读取其中的 整体偏差百分比和实际总支出。这将作为趋势对比的 基线。如果没有之前的报告，则跳过 趋势显示。

步骤 5：运行 finfocus

运行 finfocus 并输出 JSON：

finfocus overview --output json --yes

解析 JSON 输出。resources 数组中每个资源的关键字段：

• costDrift.extrapolatedMonthly — 推算的月度实际成本
• costDrift.projected — 预计月度成本
• costDrift.delta — 推算值减去预计值
• costDrift.percentDrift — 偏差百分比
• costDrift.isWarning — finfocus 内置警告标志
• actualCost.mtdCost — 月初至今的实际支出
• projectedCost.monthlyCost — 预计月度成本

从 summary 中读取：

• totalActualMTD — 月初至今的实际总支出
• projectedMonthly — 预计月度总成本

参见 references/drift-explanations.md，了解各资源类型的 相关背景。

步骤 6：标记偏差资源

对每个资源应用阈值：

1. 偏差百分比 — 如果 costDrift.percentDrift 的绝对值超过 drift_pct 阈值，则标记
2. 偏差绝对值 — 如果 costDrift.delta 的绝对值超过 drift_absolute 阈值，则标记
3. 总偏差 — 如果整体资源组合偏差百分比 超过 total_drift_pct 阈值，则标记

两个方向都要标记——超支和低于预期都属于信号。

步骤 7：生成说明

对于每个已标记的资源，在 references/drift-explanations.md 中查找其资源类型。判断偏差方向 （delta > 0 表示超支，delta < 0 表示低于预期），并选择 相应的说明。每条说明都包含：

• 可能原因提示
• 调查提示，包含可执行的下一步

如果参考文件中没有该资源类型，则使用备用 说明。

步骤 8：终端摘要

立即打印结果：

• 整体实际成本与预计成本及偏差百分比
• 与上次检查相比的趋势（如果存在基线）
• 每个已标记资源的实际成本、预计成本、差值、偏差百分比、 可能原因和调查提示
• 已标记资源总数

步骤 9：生成 COST_DRIFT.md

使用 references/report-template.md 中的模板，将报告写入项目根目录。包含所有部分：摘要、 带说明的偏差资源、无偏差资源、 所用阈值、趋势和工具信息。

对生成的文件运行 markdownlint。

步骤 10：呈现结果

向用户展示：

1. 整体偏差百分比和方向
2. 与上次检查相比的趋势（改善、恶化或稳定）
3. 偏差资源的数量
4. 偏差最大的资源及其说明
5. 询问他们是否要调查特定资源或调整 阈值