Clarity Gate

核心功能

Clarity Gate是面向RAG（检索增强生成）系统的文档预处理验证工具，核心使命是解决"若另一个LLM阅读此文档，会否将假设误认为事实？"这一关键问题。其独特定位在于强制执行（enforcement）而非仅仅检测（detection）不确定性标记——不仅发现文本中已有的 hedges（如"可能"），更主动识别应当标注却未标注的不确定性（如将"收入将达5000万"标记为假设）。

9点验证体系

| 类别 | 验证点 | 核心检查 |

|------|--------|---------|

| **认知验证** (1-4) | 1. 假设vs事实标注 | 区分已验证声明与假设 |

| | 2. 不确定性标记强制 | 前瞻性陈述必须添加限定词 |

| | 3. 假设可见性 | 隐性条件必须显式化 |

| | 4. 权威外观的未验证数据 | 表格中具体数字需标注来源 |

| **数据质量** (5-7) | 5. 数据一致性 | 文档内数字、日期冲突检测 |

| | 6. 隐性因果 | 无证据的因果推断识别 |

| | 7. 未来态现述 | 计划目标误述为已实现状态 |

| **验证路由** (8-9) | 8. 时间一致性 | 日期逻辑与版本时序检查 |

| | 9. 外部可验证声明 | 可事实核查的具体数字标记 |

输出格式：Clarity-Gated Document (CGD)

生成符合FORMAT_SPEC v2.1的结构化文档，包含：

• YAML frontmatter（含clarity-status、hitl-status等状态字段）
• 经标注的正文（如*(unverified projection)*）
• HITL Verification Record（人工验证记录表）
• <!-- CLARITY_GATE_END -->终止标记

双层验证层级

声明提取 → 是否存在真理源？
    ↓
YES → Tier 1: 自动化验证（内部一致性+外部系统对接）
NO  → Tier 2: 两轮人工验证（Round A:派生数据确认 → Round B:真实验证）

关键局限与风险

> 验证形式，非真理。 本工具检查声明是否被正确标记为不确定，无法验证声明本身是否为真。存在"幻觉注入"风险：LLM可在文档中编造虚假事实，再添加来源标记通过校验。

强制性人工参与（HITL）是安全底线：文档需经REVIEWED状态方可标记为RAG可摄入。

核心用法

Clarity Gate 是一款面向 RAG（检索增强生成）系统的文档预摄入验证工具，核心使命是在文档进入知识库前强制完成"认知质量安检"。用户通过调用该 Skill，对技术文档、商业计划、研究报告等内容执行 9 维验证：从假设与事实的明确标注、不确定性标记的强制植入，到数据一致性校验、时间连贯性核查，最终输出符合 Clarity Gate Format v2.1 标准的 .cgd.md 文件。

Skill 提供两种验证层级：Tier 1 自动化检测内部一致性矛盾与结构合规性；Tier 2 强制人工介入的两轮 HITL（Human-In-The-Loop）验证——Round A 确认派生数据解读无误，Round B 对无源声明进行真实性核验。配套 Python 脚本 claim_id.py 与 document_hash.py 提供确定性哈希计算，确保跨平台验证结果一致。

显著优点

认知安全架构设计超前：不同于传统工具仅"检测"文本中已有不确定性标记，Clarity Gate 主动"强制执行"缺失标记，直击 LLM 幻觉根源——将未验证假设误读为事实。其提出的核心问题"若另一个 LLM 阅读此文档，会误将假设当作事实吗？"重新定义了文档可信度标准。

标准化与工程化程度高：完整定义 CGD（Clarity-Gated Documents）与 SOT（Source of Truth）文件格式，配备详细格式规范、17 项验证代码（E-ST10 至 E-TB07）、边界防护机制（如 HTML 注释围栏防止自我引用攻击），并支持排除区块标记无法验证内容。

零依赖极简部署：仅依赖 Python 标准库（hashlib、re、unicodedata），无第三方包引入，从根本上消除供应链攻击面，45 秒即可完成全量安全扫描。

潜在缺点与局限性

形式验证非真理验证：Skill 明确声明"验证形式而非真理"（"verifies FORM, not TRUTH"），即无法检测文档中已被 LLM 预先植入的虚假事实——只要虚假声明带有合规的源标记即可通过验证。这一根本局限要求 HITL 验证成为强制环节，而非可选增强。

人工介入成本显著：两轮 HITL 验证对高频文档处理场景形成瓶颈，Round B 的"真实性核验"依赖人类知识储备，难以规模化。

生态适配待完善：当前 .cgd.md 格式为项目特有标准，需配套解析器才能与主流 RAG 框架（如 LangChain、LlamaIndex）无缝对接，迁移成本存在。

适合的目标群体

• 企业知识库管理员：需确保内部文档在 AI 系统间流转时的认知一致性
• AI 安全研究人员：关注 LLM 幻觉治理与认知可靠性工程
• 技术写作团队：负责 API 文档、产品规格书等高风险技术内容的合规发布
• 合规与审计部门：需建立文档溯源与验证留痕机制的组织
• 多智能体协作开发者：防止 Agent 间文档传递时的语义漂移

使用风险

性能风险：完整 9 点验证与 HITL 流程对长文档（>100 页）可能产生显著延迟，建议在 CI/CD 管道中异步执行。

误报与漏报平衡：过度严格的标记要求可能导致"标记疲劳"，关键不确定性信号被淹没；反之，宽松配置可能让高风险声明蒙混过关。

哈希计算跨平台一致性：虽已实现 BOM 去除、CRLF 统一、NFC 归一化等处理，但在极端编码场景（如混合 UTF-8/UTF-16 历史文件）仍可能出现校验值分歧。

来源可信度认知：作者为个人开发者（T3），虽背景清晰且活跃于 AI 安全社区，但企业级部署建议进行内部代码审计，并关注项目长期维护承诺。