# API Proxy Safety

网关/代理/WAF/CDN 中间件的安全关键词匹配实现规范，防止纯子串匹配误判正常响应内容中的技术术语（如 Cloudflare、502、error）

- Repository: https://github.com/doccker/cc-use-exp (1063 stars)
- Category: DevOps
- License: see repository
- Last updated: 2026-08-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add doccker/cc-use-exp --skill api-proxy-safety -g -a claude-code -y`
Codex: `npx skills add doccker/cc-use-exp --skill api-proxy-safety -g -a codex -y`
Cursor: `npx skills add doccker/cc-use-exp --skill api-proxy-safety -g -a cursor -y`
Gemini CLI: `npx skills add doccker/cc-use-exp --skill api-proxy-safety -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add doccker/cc-use-exp`

## Description

网关/代理/WAF/CDN 中间件的安全关键词匹配实现规范，防止纯子串匹配误判正常响应内容中的技术术语（如 Cloudflare、502、error）

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# API 代理安全关键词匹配规范

> 网关/WAF/CDN 中间件实现关键词匹配时，避免纯子串匹配导致正常响应内容被误判。

---

## 核心问题

### 纯子串匹配的误判

```go
// ❌ 误判：纯子串匹配，长正文中的正常用词也会命中
var pseudoSuccessPatterns = []string{
    "cloudflare",
    "502 bad gateway",
    "bad gateway",
    "reconnecting",
    "upstream error",
}
```

当业务响应正文包含这些关键词的**字面值**（如文章主题就是 "Cloudflare"），纯子串匹配会触发误判，导致：
- 正常响应被当作伪成功错误
- 触发站点切换 / 上游降级
- 错误标记模型/节点不可用

**关键事实**：关键词出现在长正文中 ≠ 响应存在问题。

---

## 解决方案：强/弱特征拆分 + 分层判定

将关键词按风险特征拆分为两组，并配合 HTTP 元数据做分层判定：

### 分层判定原则（推荐）

使用正文关键词匹配前，先通过 HTTP 元数据排除绝大多数正常响应：

| 判定层 | 检查项 | 优先级 |
|--------|--------|--------|
| 1. HTTP status | `2xx`=正常, `5xx`/`429`/某些`403`=错误 | 最高 |
| 2. Content-Type | `text/event-stream` 保持流式处理, `application/json` 检查 schema | ↑ |
| 3. 响应 schema / 错误字段 | JSON 中 `error.code` / `error.message` / `success:false` 等 | ↑ |
| 4. 正文关键词匹配 | 强/弱特征，仅作为**启发式证据**，不作为唯一事实 | 最低 |

> **正文关键词只是启发式证据**：正常用户内容可能包含技术术语字面值（如 Cloudflare、502、bad gateway），关键词命中不必然等于响应错误，必须结合 status/schema 做综合判断。

### 强特征（任何长度命中）

完整错误语句或 HTML 错误页特征。**这些模式极长且内容特殊，正常用户内容中几乎不可能出现**，可任意长度命中：

| 特征 | 说明 |
|------|------|
| `exceeded retry limit, last status: 429 too many requests` | 完整 429 错误句 |
| `must be enabled in your dashboard first` | 完整仪表盘引导句 |
| `unexpected status 502 bad gateway: error code: 502` | 完整 502 错误句（含 UUID） |
| `<html` / `<title>5` / `cf-ray:` | HTML 错误页特征 |

```go
var pseudoSuccessChatStrongPatterns = []string{
    "exceeded retry limit, last status: 429 too many requests",
    "must be enabled in your dashboard first",
    "unexpected status 502 bad gateway: error code: 502",
    "reconnecting...",
    "<html",
    "<title>5",
    "cf-ray:",
}
```

### 弱特征（仅 ≤512 字节内容命中）

单词级或短语级关键词。**极短内容（≤512 字节）中命中才判为错误**，避免长正文中技术术语误判：

| 特征 | 说明 |
|------|------|
| `429 too many requests` | 短版 429 |
| `502 bad gateway` / `bad gateway` | 短版 502 |
| `upstream error` / `upstream connect error` | 上游错误 |
| `just a moment` | CDN 挑战 |
| `cloudflare` | CDN 品牌名 |
| `must be enabled in your dashboard first` | 短版引导句 |

The rest: https://github.com/doccker/cc-use-exp/blob/HEAD/.antigravity/skills/api-proxy-safety/SKILL.md