API 代理安全关键词匹配规范
SkillCloud & infraYour AI can check gateway, proxy, web application firewall, and CDN responses without mistaking ordinary wording for real failures. This skill is a specification for safe keyword matching: it prevents simple substring checks from flagging normal content that happens to mention technical terms like Cloudflare, 502, or error. Once added, your AI applies these rules when it inspects responses or builds matching logic for such middleware.
Available today. Use it from your connected AI after setup.
No other account needed.
Add the skill, then ask your AI to review or write keyword matching for gateway, proxy, firewall, or CDN responses so it follows the specification's rules.
Then ask your AI: use the API 代理安全关键词匹配规范 skill
What your AI can do with it
- Apply safe keyword matching when checking response content
- Avoid flagging normal pages that merely mention Cloudflare, 502, or error
- Tell genuine error and block signals apart from ordinary text containing those words
- Write or review matching logic for gateway, proxy, firewall, and CDN middleware that follows the specification
What this skill tells your AI
The instructions your AI receives, as published by doccker/cc-use-exp in .claude/skills/api-proxy-safety/SKILL.md and read by ahel’s review.
网关/WAF/CDN 中间件实现关键词匹配时，避免纯子串匹配导致正常响应内容被误判。
核心问题
纯子串匹配的误判
// ❌ 误判：纯子串匹配，长正文中的正常用词也会命中
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 错误页特征 |
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 | 短版引导句 |
var pseudoSuccessChatWeakPatterns = []string{
"429 too many requests",
"502 bad gateway",
"bad gateway",
"upstream error",
"upstream connect error",
"just a moment",
"cloudflare",
"must be enabled in your dashboard first",
}
判定逻辑
func containsPseudoSuccessInChatResponse(content string) bool {
// 先检查 HTTP status 和响应 schema（应有上层调用保证）
// 正文关键词仅作为启发式证据
// 强特征：任何长度命中
for _, p := range pseudoSuccessChatStrongPatterns {
if strings.Contains(strings.ToLower(content), p) {
return true
}
}
// 弱特征：仅 ≤512 字节命中
if len(content) > 512 {
return false
}
low := strings.ToLower(content)
for _, p := range pseudoSuccessChatWeakPatterns {
if strings.Contains(low, p) {
return true
}
}
return false
}
不同场景的匹配策略
| 场景 | 策略 | 原因 |
|---|---|---|
| 聊天响应正文（长文本） | 强特征任意长度 + 弱特征仅 ≤512 字节命中 | 正文可能包含技术术语字面值 |
| 错误消息（短文本） | 全量匹配，无需长度限制 | error message 本身很短，且不含正常用户内容 |
| 流式响应片段（分块） | 参考 HTTP streaming 分类目标实现 | 等待完整块再匹配，或按内容格式切割后匹配 |
隐含缺陷判定
实现关键词匹配时，用以下问题自检：
- 匹配的关键词在正常用户内容中是否可能出现？
- 如果出现，是否按正文长度做了分级？
- 同样关键词出现在短错误消息 vs 长正常文章里，判定逻辑是否不同？
- 是否有回归测试覆盖长正文误判场景？
自测案例：
| 内容 | 长度 | 正确判定 | 说明 |
|---|---|---|---|
"exceeded retry limit, last status: 429 too many requests" | 短 | 错误 | 强特征命中 |
"Cloudflare（文章主题）..." + 4657 字正文 | 长 | 正常 | 弱特征+超长→不命中 |
"502 Bad Gateway"（纯错误） | 短 | 错误 | 弱特征+短→命中 |
"502 Bad Gateway: 配置 Nginx 反向代理时..." + 完整博客 | 长 | 正常 | 弱特征+超长→不命中，无强特征 |
与相关 skill 的边界
| skill | 关系 |
|---|---|
external-system-debugging | 本 skill 的上游：面对 CDN/WAF 网关行为异常时，先走外部系统方法论抓真实数据，再回来看匹配逻辑实现是否正确 |
api-design-safety | 本 skill 聚焦代理中间件的安全匹配实现，而非 API 本身的设计规范 |
ops-safety | 本 skill 不涉及运维操作安全、危险命令等 |
规则溯源
> 📋 本回复遵循：`api-proxy-safety` - [章节]
Signals
- GitHub stars
- 1k
- Forks
- 112
- Last commit
- Aug 2026
Advanced
- Catalog kind
- skill
- Gateway key
api-proxy-safety- Source
- github.com/doccker/cc-use-exp