关于
清晰度门控，确保在执行前需求和意图足够明确。
agentskills.io 兼容的 frontmatter
name: clarity-gate risk: unknown source: community version: 2.1.3 description: > RAG 系统的预摄入认知质量验证。 确保文档在进入知识库之前经过适当的质量审核。 生成 CGD（清晰度门控文档）并验证 SOT（真实来源）文件。 author: Francesco Marinoni Moretto license: CC-BY-4.0 repository: https://github.com/frmoretto/clarity-gate triggers:
- clarity gate
- check for hallucination risks
- can an LLM read this safely
- review for equivocation
- verify document clarity
- pre-ingestion check
- cgd verify
- sot verify capabilities:
- document-verification
- epistemic-quality
- rag-preparation
- cgd-generation
- sot-validation outputs:
- type: cgd extension: .cgd.md spec: docs/CLARITY_GATE_FORMAT_SPEC.md spec_version: "2.1"
Clarity Gate v2.1
用途： 预摄入验证系统，在文档进入 RAG 知识库之前强制执行认知质量检查。生成符合 Clarity Gate 格式规范 v2.1 的清晰度门控文档（CGD）。
核心问题： "如果另一个 LLM 阅读此文档，它会将假设误认为事实吗？"
核心原则： "检测发现现状；执行确保应有状态。实践中：在缺失的不确定性标记变成自信的幻觉之前找到它们。"
v2.1 新特性
| 特性 | 描述 |
|---------|-------------|
| 声明完成状态 | PENDING/VERIFIED 由字段存在性决定（无显式状态字段） |
| 来源字段语义 | 可操作来源（PENDING）vs. 已发现内容（VERIFIED） |
| 声明 ID 格式指南 | 推荐基于哈希的 ID，包含规模碰撞分析 |
| 正文结构要求 | 存在声明时必须包含 HITL 验证记录部分 |
| 新验证代码 | E-ST10, W-ST11, W-HC01, W-HC02, E-SC06 (FORMAT_SPEC); E-TB01-07 (SOT 验证) |
| 捆绑脚本 | claim_id.py 和 document_hash.py 用于确定性计算 |
规范
本技能实现并引用：
| 规范 | 版本 | 位置 | |---------------|---------|----------| | Clarity Gate 格式（统一） | v2.1 | docs/CLARITY_GATE_FORMAT_SPEC.md |
注意： v2.0 将 CGD 和 SOT 统一为单一的 .cgd.md 格式。SOT 现在是带有可选 tier: 块的 CGD。
验证代码
Clarity Gate 根据 FORMAT_SPEC v2.1 定义了结构和语义检查的验证代码：
HITL 声明验证 (§1.3.2-1.3.3)
| 代码 | 检查项 | 严重程度 |
|------|-------|----------|
| W-HC01 | 部分 confirmed-by/confirmed-date 字段 | 警告 |
| W-HC02 | 模糊来源（如 "industry reports", "TBD"） | 警告 |
| E-SC06 | hitl-claims 结构中的 Schema 错误 | 错误 |
正文结构 (§1.2.1)
| 代码 | 检查项 | 严重程度 |
|------|-------|----------|
| E-ST10 | 存在声明时缺少 ## HITL Verification Record | 错误 |
| W-ST11 | 表格行数与 hitl-claims 数量不匹配 | 警告 |
SOT 表格验证 (§3.1)
| 代码 | 检查项 | 严重程度 |
|------|-------|----------|
| E-TB01 | 无 ## Verified Claims 部分 | 错误 |
| E-TB02 | 表格无数据行 | 错误 |
| E-TB03 | 缺少必需列 | 错误 |
| E-TB04 | 列顺序错误 | 错误 |
| E-TB05 | 必需列中有空单元格 | 错误 |
| E-TB06 | Verified 列中日期格式无效 | 错误 |
| E-TB07 | 验证日期在未来（超过24小时宽限期） | 错误 |
注意： 其他验证代码可能在 RFC-001（澄清文档）中定义，但不属于规范性 FORMAT_SPEC 的一部分。
捆绑脚本
本技能包含用于 FORMAT_SPEC 确定性计算的 Python 脚本。
scripts/claim_id.py
计算用于 HITL 跟踪的稳定、基于哈希的声明 ID（根据 §1.3.4）。
# 生成声明 ID
python scripts/claim_id.py "Base price is $99/mo" "api-pricing/1"
# 输出: claim-75fb137a
# 运行测试向量
python scripts/claim_id.py --test
算法：
- 规范化文本（去除首尾空格 + 合并空白字符）
- 使用管道分隔符与位置连接
- SHA-256 哈希，取前8个十六进制字符
- 添加 "claim-" 前缀
测试向量：
claim_id("Base price is $99/mo", "api-pricing/1")→claim-75fb137aclaim_id("The API supports GraphQL", "features/1")→claim-eb357742
scripts/document_hash.py
根据 FORMAT_SPEC §2.2-2.4 计算文档 SHA-256 哈希，包含完整规范化。
# 计算哈希
python scripts/document_hash.py my-doc.cgd.md
# 输出: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
# 验证现有哈希
python scripts/document_hash.py --verify my-doc.cgd.md
# 输出: PASS: Hash verified: 7d865e...
# 运行规范化测试
python scripts/document_hash.py --test
算法（根据 §2.2-2.4）：
- 提取开头
---\n和<!-- CLARITY_GATE_END -->之间的内容 - 移除 frontmatter 块
- 规范化行尾为 LF
- 去除尾部空白
- 计算 SHA-256 哈希