cacheforge

CacheForge 的主要技能 — OpenAI 兼容令牌优化网关的引导引导 + 操作 + 统计数据。将您的 LLM 费用削减高达 30%（结果因提供商/工作量而异）。

## Purpose

`cacheforge` is the primary entrypoint skill. Install this one skill first.

On first use, it bootstraps companion skills if missing:
- `cacheforge-setup`
- `cacheforge-ops`
- `cacheforge-stats`

Then it routes the user request:
- setup/onboarding -> `cacheforge-setup`
- billing/upstream/keys -> `cacheforge-ops`
- usage/savings dashboard -> `cacheforge-stats`

## CacheForge Positioning

CacheForge is an OpenAI-compatible gateway for agent workflows.
It can reduce wasted spend and improve repeat-turn performance (results vary by provider/workload).

Vault Mode (Pro) is for tool-heavy agents.
Verify results in the CacheForge dashboard.

## Bootstrap Workflow (Required)

Before routing to companion skills, run:

```bash
bash "{baseDir}/scripts/bootstrap-companions.sh"
```

If bootstrap fails because `clawhub` is missing, tell the user to install companions manually:

```bash
for s in cacheforge-setup cacheforge-ops cacheforge-stats; do clawhub install "$s"; done
```

## Routing Rules

Use these routes after bootstrap:

- Setup / first-time onboarding:
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" provision ...`
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" openclaw-apply --set-default`
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" validate`

- Account ops:
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" balance`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" topup --amount 10 --method stripe`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" topup --amount 10 --method crypto`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" upstream ...`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" keys ...`

- Stats / savings:
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" dashboard`
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" usage --window 7d`
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" breakdown --by model`

## Onboarding Guardrails

Always enforce this order for new users:
1. Register + verify email (if required by deployment).
2. Create tenant API key (`cf_...`).
3. Configure upstream provider (`openrouter`, `anthropic`, or `custom`).
4. Apply OpenClaw provider config (with backup).
5. Top up credits (minimum top-up is typically `$10`).
6. Run a validation request and check dashboard telemetry.

## Public Copy Rules

- Do not use hard numeric savings claims in public-facing output unless linked to a reproducible benchmark.
- Do not reveal Vault internals.
- Keep copy outcome-focused and include "results vary by provider/workload" when relevant.

---

## 中文说明

## 目的

`cacheforge` 是主入口技能。请先安装这一个技能。

首次使用时，如果缺少配套技能，它会自动引导安装：
- `cacheforge-setup`
- `cacheforge-ops`
- `cacheforge-stats`

然后它会路由用户请求：
- 安装/上手 -> `cacheforge-setup`
- 计费/上游/密钥 -> `cacheforge-ops`
- 用量/节省看板 -> `cacheforge-stats`

## CacheForge 定位

CacheForge 是面向代理工作流的、兼容 OpenAI 的网关。
它可以减少浪费的开销并提升重复轮次的性能（结果因提供商/工作负载而异）。

Vault 模式（Pro）面向重度使用工具的代理。
请在 CacheForge 看板中核实结果。

## 引导工作流（必需）

在路由到配套技能之前，运行：

```bash
bash "{baseDir}/scripts/bootstrap-companions.sh"
```

如果因缺少 `clawhub` 而引导失败，请告知用户手动安装配套技能：

```bash
for s in cacheforge-setup cacheforge-ops cacheforge-stats; do clawhub install "$s"; done
```

## 路由规则

引导完成后使用这些路由：

- 安装 / 首次上手：
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" provision ...`
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" openclaw-apply --set-default`
  - `python3 "{baseDir}/../cacheforge-setup/setup.py" validate`

- 账户操作：
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" balance`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" topup --amount 10 --method stripe`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" topup --amount 10 --method crypto`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" upstream ...`
  - `python3 "{baseDir}/../cacheforge-ops/ops.py" keys ...`

- 统计 / 节省：
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" dashboard`
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" usage --window 7d`
  - `python3 "{baseDir}/../cacheforge-stats/dashboard.py" breakdown --by model`

## 上手护栏

对新用户始终强制执行以下顺序：
1. 注册 + 验证邮箱（若部署要求）。
2. 创建租户 API 密钥（`cf_...`）。
3. 配置上游提供商（`openrouter`、`anthropic` 或 `custom`）。
4. 应用 OpenClaw 提供商配置（带备份）。
5. 充值额度（最低充值通常为 `$10`）。
6. 运行一次验证请求并检查看板遥测。

## 公开文案规则

- 在面向公众的输出中，除非链接到可复现的基准测试，否则不要使用硬性的数字节省承诺。
- 不要泄露 Vault 内部机制。
- 保持文案以结果为导向，并在相关时附上 "results vary by provider/workload"。