# @azothos/cli

`azoth` 命令：通过网关中继 AI 编码工具的调用，在提交中指明这些调用，上报用量，向路由器请求模型，以及在 CI 中运行回归测试套件。

```
npm install -g @azothos/cli
azoth --help

# or without installing
npx @azothos/cli --help
```

> 软件包为 `@azothos/cli`，需要 Node.js 18 或更高版本。不存在 `@azoth/cli`，`npx azoth` 也不是 Azoth：该 npm 名称属于他人。

## 配置

设置 `AZOTH_API_KEY`（自托管部署还需设置 `AZOTH_BASE_URL`），或将它们以 `apiKey` 和 `baseUrl` 写入 `~/.azoth/config.json`。环境变量优先。

## azoth proxy

- 在您机器上运行的中继，适用于任何接受 OpenAI 基础 URL 的工具：将其指向 `http://127.0.0.1:8787/v1`，可使用任意 API 密钥。
- 每次调用都会使用您的工作区密钥发送到工作区的网关，并在那里接受治理和封存；工具自身的密钥从不会被转发。
- 中继只保留每个回答附带的引用（其签名回执，或流式回答的追踪 ID），保存在 `~/.azoth/receipts.jsonl` 中，保留 7 天。它只响应本机。

```
azoth proxy                                      # relay on http://127.0.0.1:8787/v1
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1   # or the tool's own setting; any API key
```

## azoth hook install

- 为当前仓库添加一个 git `commit-msg` 钩子：对于中继自上次提交以来看到的每次调用，每个提交都会添加一个 `Azoth-Receipt:` 尾注，最多保留最近的 5 个。
- 当 Azoth 读取该仓库时，这样的提交会显示为关联到已封存的调用：它指明网关已封存的一次调用，绝不证明代码来自该调用。
- 该钩子从不阻止提交，不会为空消息或合并提交添加任何内容，也从不覆盖不是由它写入的钩子——使用 husky 或 commitlint 时，请将 `azoth hook run "$1" || true` 添加到您自己的钩子中。`azoth hook uninstall` 可将其移除。

```
azoth hook install

git commit -m "Fix the retry on 429"
# → Azoth-Receipt: eyJhbGciOiJFZERTQSIs…   (one trailer per relayed call, the latest 5)
```

## 其他命令

- `azoth ingest [file]` — 从文件、stdin 或命令行参数上报用量事件
- `azoth route` — 向路由器请求模型（`--mode cost|quality|balanced`）
- `azoth budget` — 打印每个预算及其使用情况；`--exit-on-exceeded` 可用作 CI 门禁
- `azoth test run <suite.json>` — 通过网关运行回归测试套件；有用例失败时以 1 退出

## 在 CI 中

```
# .github/workflows/ai-regression.yml
- run: npx --yes @azothos/cli test run suite.json
  env:
    AZOTH_API_KEY: ${{ secrets.AZOTH_API_KEY }}
```
