| name | semantic-trap-detector |
| description | Detect and fix semantic traps in Claude Skills that cause LLM hallucinations. Use for testing skills, optimizing prompts, improving skill accuracy, fixing skill hallucinations, LLM output quality, and prompt engineering. |
语义陷阱检测器 (Semantic Trap Detector)
概述
语义陷阱检测器是一个专门用于检测和优化其他 Claude Skills 的元 Skill。它基于语义陷阱理论——即在大模型认知空间中，某些在日常语境下含义相近的词汇对，其语义边界（激活范围）存在巨大差异。使用语义边界过宽的词汇会导致大模型突破 Prompt 约束，产生幻觉输出。
本检测器通过系统化的四步工作流，自动识别 Skill 中的高风险词汇和结构模式，并提供具体的替换建议和边界锚定策略。
核心理论
什么是语义陷阱？
语义陷阱（Semantic Trap）：在人类日常语境中含义相近，但在大模型的语义空间中激活范围（即语义边界）存在巨大差异的词汇对。
示例：
- "漏洞" vs "风险" → 在实验中导致 27个百分点 的准确率差异（89.3% vs 62.1%）
- "检查" vs "审查" → 前者触发客观判定，后者触发主观评价
- "列出" vs "描述" → 前者输出结构化条目，后者触发解释和评论
LLM 语义敏感度矩阵
边界清晰度
高 ←————→ 低
┌───────────────────┐
低 │ 漏洞 缺陷 错误 │ ← 安全区
↑ │ 检查 列出 要求 │
发 │─────────────────── │
散 │ 总结 问题 审查 │
倾 │ 建议 分析 风险 │ ← 危险区
向 │ 异常 评估 描述 │
↓ └───────────────────┘
高
关键洞察：词汇选择比 Prompt 结构更根本。如果"砖块"（词汇）本身会膨胀，再精良的"围墙"（工作流）也会被撑破。
检测工作流
本检测器采用严格的四步工作流，不得跳过或重新排序任何步骤。
STEP 1: 加载词典
目标：加载语义陷阱词典，建立检测知识基础
执行动作：
- 读取
semantic-trap-lexicon.md 文件
- 确认词典包含以下内容：
- 17+ 组中文词汇对
- 10+ 组英文词汇对
- 语义敏感度矩阵
- 边界锚定策略
验证标准：
STEP 2: 提取关键词
目标：从待检测文本中提取四类高风险关键词
执行动作：
2.1 核心术语提取
提取任务类型名词，如：
- 漏洞、风险、问题、缺陷、错误、异常
- Vulnerability, Risk, Issue, Defect, Error, Anomaly
2.2 动作指令提取
提取指导大模型执行的动词或动宾短语：
- 检查、审查、分析、评估、探索、理解
- Check, Review, Analyze, Evaluate, Explore, Understand
2.3 约束词提取
提取限定范围的词：
- 要求、建议、原则、规则、必须、应该
- Requirement, Suggestion, Must, Should, Principle
2.4 输出描述词提取
提取描述期望输出的词：
- 列出、描述、总结、报告、洞察
- List, Describe, Summarize, Report, Insight
验证标准：
- 四类关键词全部提取完毕
- 每个关键词标注其在文本中的位置（行号、上下文）
STEP 3: 逐词匹配与上下文分析
目标：对每个关键词执行两层判定，识别语义陷阱
3.1 第一层判定：词典匹配
对每个提取的关键词：
- 检查是否在宽边界词列表中
- 如果匹配，记录陷阱ID、风险等级、推荐替换词
风险等级分类：
- 高危：语义宽度差极大（如 漏洞 vs 风险）
- 中危：语义宽度差大（如 检查 vs 审查）
- 低危：语义宽度差中等
3.2 第二层判定：上下文角色分析
同一个词在不同位置的危害程度不同：
高风险上下文：
- 核心约束语句中："只分析 X 类型"
- 任务主描述中："评估 X"
- 输出格式定义中："生成 X 报告"
低风险上下文：
- 辅助描述中："以分析性的视角"
- 示例说明中："以下是一个分析示例"
判定规则：
IF 词在宽边界词列表 AND 在高风险上下文
→ 风险等级提升一级
IF 词在宽边界词列表 AND 在低风险上下文
→ 风险等级降低一级
3.3 疑似陷阱识别
即使词典中未收录，如果词汇满足以下宽边界特征，也应标记为疑似陷阱：
宽边界词的共性特征：
- 程度性而非二元性：如"风险"（高/中/低）vs"漏洞"（存在/不存在）
- 带展望性：如"分析"指向潜在可能性
- 触发主观评价：如"审查"包含价值判断
- 关联网络松散：如"问题"可关联到任何不够完美的事物
3.4 结构性风险模式识别
识别四种额外的结构性陷阱：
| 模式类型 | 示例 | 检测方法 |
|---|
| 开放式动词 + 无范围限定 | "分析代码" | 检测动词后是否跟随具体对象 |
| 形容词化目标 | "评估安全性" | 检测抽象名词（安全性、质量性） |
| 情态动词降级 | "应该"而非"必须" | 检测约束条件中的情态动词 |
| 缺少否定清单 | 使用宽边界词但无排除列表 | 检测是否有"不包括"或"排除"章节 |
验证标准：
- 所有关键词完成两层判定
- 识别出所有结构性风险模式
- 生成完整的风险清单
STEP 4: 生成检测报告
目标：输出结构化的检测报告和可执行的建议
4.1 报告结构
# 语义陷阱检测报告
## 1. 检测概览
- 检测文件：[文件名]
- 提取关键词数：[数量]
- 发现陷阱数：[数量]
- 高危：[数量]
- 中危：[数量]
- 低危：[数量]
- 结构性风险：[数量]
## 2. 检测详情表
| 原词 | 陷阱ID | 风险等级 | 上下文 | 推荐替换 | 理由 |
|------|--------|---------|--------|---------|------|
| 风险 | T01 | 高危 | 核心术语 | 漏洞 | 语义宽度极大，导致范围溢出 |
| 审查 | T11 | 中危 | 动作指令 | 检查 | 触发主观评价性意见 |
## 3. 替换建议
### 原句 1（行号）
**原文**：请审查这段代码中的安全问题，只关注定义文件中的问题类型。
**问题**：
- "审查" (T11) → 触发主观评价
- "问题" (T02) → 语义范围极宽
**替换后**：请检查这段代码中的安全漏洞，只关注定义文件中的漏洞类型。
**替换理由**：
- "检查"仅触发通过/不通过的客观判定
- "漏洞"具有明确的二元判定标准
## 4. 边界锚定建议
对于无法替换的宽边界词，采用以下策略：
### 策略 1：前置否定清单
[具体代码示例]
### 策略 2：输出格式硬约束
[具体JSON/Markdown格式示例]
### 策略 3：判定示例的反例强化
[具体反例内容]
## 5. 优先级建议
按以下优先级处理：
1. [ ] 立即修复：所有高危陷阱
2. [ ] 尽快修复：中危陷阱
3. [ ] 可选优化：低危陷阱和疑似陷阱
4.2 输出要求
Final Answer 格式：
{
"summary": {
"total_keywords": 0,
"traps_found": 0,
"high_risk": 0,
"medium_risk": 0,
"low_risk": 0,
"structural_risks": 0
},
"details": [
{
"word": "原词",
"trap_id": "T01",
"risk_level": "高危|中危|低危",
"context": "上下文片段",
"line_number": 行号,
"replacement": "推荐替换词",
"reason": "替换理由"
}
],
"structural_patterns": [
{
"pattern_type": "模式类型",
"line_number": 行号,
"example": "示例内容",
"fix_suggestion": "修复建议"
}
],
"suggestions": [
{
"original": "原句",
"fixed": "替换后",
"reason": "替换理由"
}
]
}
验证标准：
- 报告包含所有四个部分
- 每个陷阱都有具体的替换建议
- 无法替换的陷阱提供锚定策略
- Final Answer 符合 JSON 格式
使用指南
基本用法
"请检测 /path/to/SKILL.md 文件中的语义陷阱"
高级选项
仅检测特定类别：
"请仅检测 SKILL.md 中的动作指令类陷阱"
包含引用文件：
"请检测 SKILL.md 及其引用的所有 .md 定义文件"
生成详细报告：
"请检测并生成完整的替换建议和锚定方案"
约束与规则
- 强制执行顺序：STEP 1 → 2 → 3 → 4，不得跳过或重新排序
- 完整性要求：每步必须完成验证标准才能进入下一步
- 词典依赖：所有判定必须基于词典，不得凭空推断
- 上下文敏感：必须结合上下文角色判定风险等级
- 可操作性：所有建议必须具体可执行，不能是模糊的"优化建议"
词典维护
当发现新的语义陷阱时，按以下格式添加到 semantic-trap-lexicon.md：
### TXX: [窄边界词] vs [宽边界词]
- **窄边界词**: [词] ✅
- **宽边界词**: [词] ⚠️
- **语义宽度差**: 小/中/大/极大
- **典型失控场景**: [描述]
- **示例对比**:
- ❌ 错误: [示例]
- ✅ 正确: [示例]
理论来源
本检测器基于以下研究成果：
- 论文：《别让大模型"想太多"：SKILL开发中的语义陷阱与抗幻觉设计》
- 作者：SummerSec
- 实验数据：56个营销接口测试集，27个百分点的准确率差异验证
- 核心发现：语义边界控制比传统 Prompt Engineering 更为根本
质量保证
自检清单
使用本检测器时，应确认：
常见问题
Q: 为什么"漏洞"比"风险"好？
A: "漏洞"具有明确的二元判定标准（存在/不存在），而"风险"本质上是程度性问题（高/中/低），会触发发散性思考。
Q: 所有宽边界词都必须替换吗？
A: 不是。如果业务要求必须使用某个词，可以采用边界锚定策略（否定清单、硬约束、反例）。
Q: 如何验证检测效果？
A: 使用"最小对比测试"——在已知答案的标准测试用例上运行 Skill，检查是否包含超出范围的内容。
版本历史
- v1.0 (2026-03-08): 初始版本，基于语义陷阱理论框架
- 实现四步检测工作流
- 收录17组中文词汇对 + 10组英文词汇对
- 支持结构性风险模式识别
- 提供边界锚定策略
许可与引用
本 Skill 开源遵循 MIT 许可证。如使用本检测器产生学术或商业价值，请引用原始论文：
@article{summersec2026semantic,
title={别让大模型"想太多"：SKILL开发中的语义陷阱与抗幻觉设计},
author={SummerSec},
year={2026},
publisher={WgpSec狼组安全团队}
}
