shit-agent-proxy

Coding Agent（Claude Code 等）在调用 LLM API 时，上游服务可能因限流、过载、网关抖动等原因返回瞬时错误（429 / 502 / 503 / 529）。Agent 内部的重试策略通常不可配置，重试耗尽后中断当前任务，需要人工介入。

shit-agent-proxy 在 Agent 和上游 API 之间插入一层透明代理，将瞬时错误收敛在代理层，通过可配置的指数退避策略自动恢复，对 Agent 侧完全无感。

原理

Coding Agent              shit-agent-proxy              Upstream API
    │                           │                            │
    │ ─── Request ───────────→  │ ─── Forward ─────────────→ │
    │                           │ ←── 429 / 502 / 503 ────── │
    │                           │     (sleep, backoff)        │
    │                           │ ─── Retry ───────────────→ │
    │                           │ ←── 200 OK ──────────────── │
    │ ←── 200 OK ────────────  │                            │

• 纯净代理：不修改任何 header / body / auth，只转发 + 重试
• 零依赖：仅使用 Node.js 内置模块
• 可配置：重试次数、退避参数、可重试状态码均可调整

安装

npm install -g shit-agent-proxy

快速开始

# 1. 启动代理
sap start -t https://your-api-upstream.com

# 后台运行
sap start -t https://your-api-upstream.com -d

# 2. 将 Agent 的 API Base URL 指向代理
#    以 Claude Code 为例，修改 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"
  }
}

# 3. 重启 Agent，完事

其他所有配置（API key、自定义 header、model 等）保持不变，只改 Base URL。

CLI

sap start [options]       # 启动代理（前台）
sap start -d [options]    # 启动代理（后台守护进程）
sap stop                  # 停止后台代理
sap status                # 查看代理状态
sap config                # 查看当前配置
sap config set <k> <v>    # 修改配置项
sap help                  # 帮助

start 参数

| 参数 | 说明 | 默认值 | |------|------|--------| | -t, --target <url> | 上游 API 地址（必填） | - | | -p, --port <n> | 代理监听端口 | 8787 | | -d, --daemon | 后台运行 | false | | --max-retries <n> | 最大重试次数 | 30 | | --base-delay <ms> | 基础退避延迟（毫秒） | 3000 | | --max-delay <ms> | 最大退避延迟（毫秒） | 120000 | | --jitter <ms> | 随机抖动范围（毫秒） | 5000 |

重试策略

指数退避 + 随机抖动，防止 thundering herd：

第 1 次: base_delay * 2^0 + jitter  →  3~8s
第 2 次: base_delay * 2^1 + jitter  →  6~11s
第 3 次: base_delay * 2^2 + jitter  →  12~17s
...
第 N 次: min(base_delay * 2^N, max_delay) + jitter

默认可重试状态码：429、502、503、529

如果响应带 Retry-After header，优先使用服务端建议的等待时间。

配置

持久化在 ~/.shit-agent-proxy/config.json，CLI 参数优先于配置文件。

sap config                      # 查看
sap config set maxRetries 50    # 修改
sap config set baseDelay 5000

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | target | string | - | 上游 API 地址 | | port | number | 8787 | 代理端口 | | maxRetries | number | 30 | 最大重试次数 | | baseDelay | number | 3000 | 基础退避延迟 (ms) | | maxDelay | number | 120000 | 最大退避延迟 (ms) | | jitter | number | 5000 | 随机抖动范围 (ms) |

日志

前台模式实时输出重试过程：

16:58:29 [429] retry 1/30 sleep 3.5s  /v1/messages
       └─ {"error":{"message":"rate limit exceeded",...}}
16:58:33 [429] retry 2/30 sleep 7.2s  /v1/messages
16:58:41 [OK]  recovered after 2 retries  /v1/messages

卸载

npm uninstall -g shit-agent-proxy
rm -rf ~/.shit-agent-proxy
# 把 ANTHROPIC_BASE_URL 改回原值

License

MIT