skill-cost-projections

宿主：Codex CLI — 此技能最初为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前活动的 Codex shell 和子 Agent 工具。在当前会话尚未提供相关能力之前，不要声称某个提供方、模型或宿主子 Agent 可用。 宿主工具的对应项请参阅 skills/blocks/codex-host-adapter.md。

成本预测技能

概述

根据已完成工作中各阶段的平均成本，预测工作流剩余成本。在 HUD/状态栏中显示成本数据，并在预测总额超过已配置的预算上限时发出警告。

最低数据要求： 至少需要 2 个已完成步骤才能进行预测。数据点少于 2 个时，平均值不可靠——仅显示实际支出并跳过预测。

步骤 1：收集已完成阶段的成本

从 ~/.claude-octopus/metrics/ 或 metrics-tracker.sh 输出中读取成本数据。每个已完成的阶段/步骤都应有对应的成本记录。

# Read metrics from the session metrics directory
METRICS_DIR="$HOME/.claude-octopus/metrics"
SESSION_METRICS="$METRICS_DIR/session-$(date +%Y%m%d).jsonl"

# Each line contains: {"phase": "discover", "cost": 0.42, "tokens_in": 12000, "tokens_out": 3400, "timestamp": "..."}
# Sum costs from completed steps
completed_costs=$(jq -s '[.[].cost]' "$SESSION_METRICS")
completed_count=$(jq -s 'length' "$SESSION_METRICS")
total_spent=$(jq -s '[.[].cost] | add' "$SESSION_METRICS")

数据来源（按优先级排序）：

1. ~/.claude-octopus/metrics/session-*.jsonl — 结构化的逐阶段成本记录
2. metrics-tracker.sh 输出 — 旧版会话的备用来源
3. HUD 累计成本计数器 — 最后手段

如果可用的已完成步骤少于 2 个，则仅显示实际支出：

💰 Spent: 0.42 USD (1 step complete — need 2+ for projection)

步骤 2：计算每个步骤的平均成本

计算所有已完成步骤成本的平均值。

avg_cost=$(echo "$total_spent / $completed_count" | bc -l)

公式：

avg_cost = total_cost / completed_steps

示例： 如果 3 个步骤的成本分别为 0.30 USD、0.50 USD、0.40 USD → 平均值 = 1.20 USD / 3 = 0.40 USD/步骤

步骤 3：预测剩余成本

将每个步骤的平均成本乘以剩余步骤数。

remaining_steps=$((total_steps - completed_count))
projected_remaining=$(echo "$avg_cost * $remaining_steps" | bc -l)
projected_total=$(echo "$total_spent + $projected_remaining" | bc -l)

公式：

projected_remaining = avg_cost × remaining_steps
projected_total     = total_spent + projected_remaining

不同工作流类型的步骤数：

工作流	总步骤数	阶段示例
embrace	4	Discover、Define、Develop、Deliver
research	3-7	每个 Agent 的探测数量
review	3	Fleet、Verifier、Synthesis
debate	3	Opening、Rebuttal、Synthesis

步骤 4：在 HUD 中显示

格式化成本预测，以便在 HUD/状态栏中显示。

标准显示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

格式规则：

• 所有金额保留 2 位小数
• 预测总额前加 ~，表示估算值
• 成本行使用 💰 前缀
• 显示为单行紧凑格式，以便集成到状态栏

数据不足时（< 2 个步骤）：

💰 Spent: 0.42 USD (need 2+ steps for projection)

集成： 此显示行由 octopus-hud hook 输出，并与阶段进度和提供方状态一同呈现在状态栏中。

步骤 5：预算上限警告

如果设置了 OCTO_BUDGET_CEILING 环境变量，则将预测总额与其比较，并在超出时发出警告。

if [[ -n "${OCTO_BUDGET_CEILING:-}" ]]; then
  ceiling="$OCTO_BUDGET_CEILING"
  if (( $(echo "$projected_total > $ceiling" | bc -l) )); then
    overage=$(echo "$projected_total - $ceiling" | bc -l)
    echo "⚠️ Budget ceiling: ${ceiling} USD — projected to exceed by ${overage} USD"
  fi
fi

超出预算时的显示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD

未超出预算时的显示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
✅ Within budget ceiling: 10.00 USD

注意： OCTO_BUDGET_CEILING 为可选项。未设置时，不会执行上限检查。

步骤 6：配置建议

如果预测总额相对于任务而言较高，建议切换到 budget 配置以降低成本。

# Suggest budget profile when projected total exceeds 5.00 USD (configurable)
COST_THRESHOLD="${OCTO_COST_THRESHOLD:-5.00}"
if (( $(echo "$projected_total > $COST_THRESHOLD" | bc -l) )); then
  echo "💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs"
fi

显示：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

budget 配置（OCTO_PROFILE=budget）会路由到成本更低的模型，并减少 Agent 数量以尽量降低支出。

完整显示示例

正常 — 未超出预算，成本适中：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

超出预算上限：

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

工作流早期（数据不足）：

💰 Spent: 0.42 USD (need 2+ steps for projection)

成本较低 — 无警告：

💰 Spent: 0.80 USD | Est. remaining: 0.80 USD | Total: ~1.60 USD

集成

与 octopus-hud hook 集成

成本预测行会作为 HUD 状态栏输出的一部分呈现，并在每个阶段完成后更新。

与 metrics-tracker.sh 集成

读取 metrics tracker 写入的逐阶段成本数据。每个已完成阶段都会记录成本、Token 数量和提供方详细信息。

与 OCTO_PROFILE 集成

当 OCTO_PROFILE=budget 生效时，预测会考虑通过更便宜的模型路由降低的单步成本。

错误处理

没有 metrics 目录：

💰 Cost projection unavailable — no metrics data found

metrics 数据损坏： 跳过格式错误的条目，仅根据有效数据进行预测。如果没有剩余有效条目，则显示不可用消息。

剩余步数为零： 完成所有步骤后，仅显示最终总数：

💰 Final cost: 4.80 USD (4 steps)