mcpField
C
clarity-gate

clarity-gate

github.com/frmoretto数据与数据库3448 次安装34 周前更新
代码仓库

关于 clarity-gate

Clarity Gate 是文档进入 RAG 知识库前的验证 Skill,检查事实、假设和不确定性是否得到恰当标记,并生成符合规范的 CGD 文档。它验证文档格式与表达状态,不验证声明真伪;通过审核仍需人工核实。

主要功能

  1. 01执行九项语义验证检查
  2. 02校验 CGD 结构与状态字段
  3. 03检查 HITL 声明和验证记录
  4. 04生成稳定的声明 ID
  5. 05计算并验证文档 SHA-256

适用场景

  1. 01将文档导入 RAG 前检查不确定性标记
  2. 02分享文档给其他 AI 系统前进行审核
  3. 03检查含预测或假设的规格文档

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/frmoretto/clarity-gate --skill clarity-gate

安装后在 Claude Code 中输入/clarity-gate确认已加载。

附带文件scripts/claim_id.pyscripts/document_hash.py

详细介绍

Clarity Gate v2.1

用途: 文档进入 RAG 知识库之前的预摄取验证系统,用于确保其符合认知质量要求。生成符合 Clarity Gate Format Specification v2.1 的 Clarity-Gated Documents(CGD)。

核心问题:“如果另一个 LLM 读取此文档,它会把假设误认为事实吗?”

核心原则: “检测会发现现状;强制执行则确保达到应有标准。在实践中,就是在缺失的不确定性标记演变成自信的幻觉之前,找出它们。”


v2.1 新增内容

功能描述
声明完成状态根据字段是否存在确定 PENDING/VERIFIED(没有显式状态字段)
来源字段语义可执行的来源(PENDING)与已发现的内容(VERIFIED)
声明 ID 格式指南首选基于哈希的 ID,并针对规模进行冲突分析
正文结构要求存在声明时,必须包含 HITL Verification Record 部分
新增验证代码E-ST10、W-ST11、W-HC01、W-HC02、E-SC06(FORMAT_SPEC);E-TB01-07(SOT 验证)
捆绑脚本用于确定性计算的 claim_id.py 和 document_hash.py

规范

此技能实现并引用以下规范:

规范版本位置
Clarity Gate Format (Unified)v2.1docs/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-HC01confirmed-by/confirmed-date 字段不完整WARNING
W-HC02来源模糊(例如,“行业报告”、“TBD”)WARNING
E-SC06hitl-claims 结构中的架构错误ERROR
正文结构(§1.2.1)
代码检查项严重级别
E-ST10存在声明时缺少 ## HITL Verification RecordERROR
W-ST11表格行数与 hitl-claims 数量不符WARNING
SOT 表格验证(§3.1)
代码检查项严重级别
E-TB01没有 ## Verified Claims 部分ERROR
E-TB02表格没有数据行ERROR
E-TB03缺少必需列ERROR
E-TB04列顺序错误ERROR
E-TB05必需列中的单元格为空ERROR
E-TB06Verified 列中的日期格式无效ERROR
E-TB07Verified 日期位于未来(超过 24 小时宽限期)ERROR

注意: RFC-001(澄清文档)可能定义其他验证代码,但它们不属于规范性 FORMAT_SPEC 的一部分。


捆绑脚本

此技能包含根据 FORMAT_SPEC 进行确定性计算的 Python 脚本。

scripts/claim_id.py

计算稳定的、基于哈希的声明 ID,用于 HITL 跟踪(根据 §1.3.4)。

# Generate claim ID
python scripts/claim_id.py "Base price is $99/mo" "api-pricing/1"
# Output: claim-75fb137a

# Run test vectors
python scripts/claim_id.py --test

算法:

  1. 规范化文本(去除首尾空格并合并空白)
  2. 使用竖线分隔符与位置拼接
  3. 计算 SHA-256 哈希,取前 8 个十六进制字符
  4. 添加前缀 "claim-"

测试向量:

  • claim_id("Base price is $99/mo", "api-pricing/1") → claim-75fb137a
  • claim_id("The API supports GraphQL", "features/1") → claim-eb357742
scripts/document_hash.py

按照 FORMAT_SPEC §2.2-2.4 计算文档 SHA-256 哈希,并进行完整规范化。

# Compute hash
python scripts/document_hash.py my-doc.cgd.md
# Output: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730

# Verify existing hash
python scripts/document_hash.py --verify my-doc.cgd.md
# Output: PASS: Hash verified: 7d865e...

# Run normalization tests
python scripts/document_hash.py --test

算法(根据 §2.2-2.4):

  1. 提取开头的 ---\n 与 `` 之间的内容
  2. 仅从 YAML frontmatter 中移除 document-sha256 行(支持多行续接)
  3. 规范化:
    • 移除每行末尾的空白字符
    • 将连续 3 个或更多换行符合并为 2 个
    • 规范化末尾换行符(恰好 1 个 LF)
    • 进行 UTF-8 NFC 规范化
  4. 计算 SHA-256

跨平台规范化:

  • 如果存在 BOM,则将其移除
  • 将 CRLF 转换为 LF(Windows)
  • 将 CR 转换为 LF(旧版 Mac)
  • 边界检测(防止对 CGD 结构之外的内容计算哈希)
  • 空白字符差异会产生相同的哈希(跨平台保持确定性)

关键区别

UnScientify 和 HedgeHunter (CoNLL-2010) 等现有工具会检测文本中已有的不确定性标记(“是否表达了不确定性?”)。

Clarity Gate 会在认知层面有必要时强制要求出现这些标记(“是否应该表达不确定性,但实际上没有?”)。

工具类型问题示例
检测“这段文本是否包含模糊措辞?”UnScientify/HedgeHunter 会找到“可能”“或许”
强制要求“这项声明是否应该使用模糊措辞,但实际上没有?”Clarity Gate 会标记“收入将达到 5000 万美元”

关键限制

Clarity Gate 验证的是形式,而非事实。

此技能会检查声明是否正确标记为不确定,但无法验证声明是否属实。

风险: LLM 可能会将虚构事实写入文档,然后为虚假声明添加来源标记,以此“通过” Clarity Gate。

解决方案: 在宣布通过之前,必须进行 HITL(Human-In-The-Loop)验证。


适用场景

  • 将文档导入 RAG 系统之前
  • 与其他 AI 系统共享文档之前
  • 撰写规格说明、状态文档或方法描述之后
  • 文档包含预测、估算或假设时
  • 发布未经验证的声明之前
  • 在不同 LLM 会话之间移交文档时

9 个验证点

与规格套件的关系

9 个验证点用于指导语义审查,即需要判断力(由人或 AI 进行)的内容质量检查。它们解答“这项声明是否应该使用模糊措辞?”和“这些数字是否一致?”之类的问题。

审查完成后,输出符合 CLARITY_GATE_FORMAT_SPEC.md 的 CGD 文件。CLARITY_GATE_FORMAT_SPEC.md 中的 C/S 规则用于验证文件结构,而非语义内容。

二者的关联:

  1. 语义审查结果(9 个验证点)用于确定存在哪些问题
  2. 问题记录在 CGD 状态字段(clarity-status、hitl-status、hitl-pending-count)中
  3. 结构规则(C7-C10)确保状态一致性

示例:如果验证点 5(数据一致性)发现数字相互冲突,在问题解决之前,应将 clarity-status 标记为 UNCLEAR。规则 C7 随后会确保你不能在状态仍为 UNCLEAR 时声称已 REVIEWED。


认知检查(核心重点:第 1-4 点)

1. 假设与事实的标注 每一项主张都必须明确标记为已验证或假设。

不通过通过
“我们的架构优于竞争对手”“我们的架构优于竞争对手 [基准数据见 Table 3]”
“该模型实现了 40% 的提升”“该模型实现了 40% 的提升 [在数据集 X 上测得]”

修复: 添加标记:“PROJECTED:”、“HYPOTHESIS:”、“UNTESTED:”、“(estimated)”、“~”、“?”


2. 不确定性标记的强制执行 前瞻性陈述需要限定词。

不通过通过
“到 Q4 收入将达到 $50M”“到 Q4 收入预计将达到 $50M”
“该功能将降低流失率”“该功能预期将降低流失率”

修复: 添加“projected”、“estimated”、“expected”、“designed to”、“intended to”


3. 假设的可见性 影响解读的隐含假设必须显式说明。

不通过通过
“该系统可线性扩展”“该系统可线性扩展 [假设并发用户数 <1000]”
“响应时间为 50ms”“响应时间为 50ms [在标准负载条件下]”

修复: 添加方括号条件:“[assuming X]”、“[under conditions Y]”、“[when Z]”


4. 看似权威但未经核实的数据 带有具体百分比和勾选标记的表格看起来像实测数据。

危险信号: 带有具体数字(89%、95%、100%)但没有来源的表格

修复: 在数字后添加“(guess)”、“(est.)”、“?”。添加明确警告:“PROJECTED VALUES - NOT MEASURED”


数据质量检查(补充:第 5-7 点)

5. 数据一致性 扫描文档中相互冲突的数字、日期或事实。

危险信号: 一处写“500 名用户”,另一处写“750 名用户”

修复: 调和冲突,或明确注明差异并给出解释。


6. 隐含因果 没有证据却暗示因果关系的主张。

危险信号: “更短的提示词可提升响应质量”(看似合理但未经证实)

修复: 改写为假设:“更短的提示词可能提升响应质量(假设,未经核实)”


7. 将未来状态表述为当前状态 将计划中或期望中的结果描述为已经实现。

危险信号: “该系统每秒处理 10,000 个请求”(而系统尚未构建)

修复: 使用未来时或条件式:“该系统设计为处理……”或“TARGET: 10,000 rps”


核验路由(第 8-9 点)

8. 时间一致性 文档日期和时间戳必须在内部保持一致且合理。

不通过通过
“Last Updated: December 2024”(当前为 2026 年时)“Last Updated: January 2026”
v1.0.0 日期为 2024-12-23,v1.1.0 日期为 2024-12-20版本按时间顺序排列

子检查:

  1. 文档日期与当前日期
  2. 内部时间顺序(版本、事件按顺序)
  3. 引用新鲜度(“current”、“now”、“today”等表述)

修复: 更新日期,添加“as of [date]”限定词,标记过时表述


9. 可外部核验的主张 可被事实核查的具体数字应标记为待核验。

类型示例风险
定价“每次调用成本约 $0.005”API 定价会变化
统计数据“论文平均包含 15-30 个公式”可能严重偏差
比率/比例“40% 的研究人员使用 X”需要引用来源
竞争对手相关主张“没有竞争对手提供 Y”可能已过时

修复选项:

  1. 添加带日期的来源
  2. 添加不确定性标记
  3. 转交 HITL 或外部搜索
  4. 泛化表述(用“低成本”代替“$0.005”)

核验层级

Claim Extracted --> Does Source of Truth Exist?
                           |
           +---------------+---------------+
           YES                             NO
           |                               |
   Tier 1: Automated              Tier 2: HITL
   Consistency & Verification     Two-Round Verification
           |                               |
   PASS / BLOCK                   Round A → Round B → APPROVE / REJECT
第 1 层:自动核验

A. 内部一致性

  • 图表与正文矛盾
  • 摘要与正文不匹配
  • 表格与文字冲突
  • 数值一致性

B. 外部核验(扩展接口)

  • 用户提供的连接器,用于连接结构化来源
  • 财务系统、Git 提交、CRM 等
Tier 2:两轮 HITL 验证 — 强制要求

Round A:衍生数据确认

  • 来自会话中找到的来源的声明
  • 人工确认解释是否正确,而非确认事实是否属实

Round B:真正的 HITL 验证

  • 需要实际验证的声明
  • 未找到来源、使用人工自身数据或进行外推的情况

CGD 输出格式

生成 Clarity-Gated Document 时,请按照 CLARITY_GATE_FORMAT_SPEC.md v2.1 中的格式:

---
clarity-gate-version: 2.1
processed-date: 2026-01-12
processed-by: Claude + Human Review
clarity-status: CLEAR
hitl-status: REVIEWED
hitl-pending-count: 0
points-passed: 1-9
rag-ingestable: true          # computed by validator - do not set manually
document-sha256: 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
hitl-claims:
  - id: claim-75fb137a
    text: "Revenue projection is $50M"
    value: "$50M"
    source: "Q3 planning doc"
    location: "revenue-projections/1"
    round: B
    confirmed-by: Francesco
    confirmed-date: 2026-01-12
---

# Document Title

[Document body with epistemic markers applied]

Claims like "Revenue will be $50M" become "Revenue is **projected** to be $50M *(unverified projection)*"

---

## HITL Verification Record

### Round A: Derived Data Confirmation
- Claim 1 (source) ✓
- Claim 2 (source) ✓

### Round B: True HITL Verification
| # | Claim | Status | Verified By | Date |
|---|-------|--------|-------------|------|
| 1 | [claim] | ✓ Confirmed | [name] | [date] |


Clarity Gate: CLEAR | REVIEWED

CGD 必需元素(根据规范):

  • 包含所有必填字段的 YAML frontmatter:
    • clarity-gate-version — 工具版本(不带「v」前缀)
    • processed-date — YYYY-MM-DD 格式
    • processed-by — 处理者名称
    • clarity-status — CLEAR 或 UNCLEAR
    • hitl-status — PENDING、REVIEWED 或 REVIEWED_WITH_EXCEPTIONS
    • hitl-pending-count — 大于或等于 0 的整数
    • points-passed — 例如,1-9 或 1-4,7,9
    • hitl-claims — 已验证声明的列表(可以为空 [])
  • 结束标记(HTML 注释 + 状态行):
    
    Clarity Gate: <clarity-status> | <hitl-status>
    
  • HITL 验证记录(状态为 REVIEWED 时)

可选/计算字段:

  • rag-ingestable — 由验证器计算,而非手动设置。仅当状态为 CLEAR | REVIEWED 且没有排除块时显示 true。
  • document-sha256 — 必填。用于完整性验证的 64 个字符小写十六进制哈希值。计算规则请参阅规范 §2。
  • exclusions-coverage — 可选。正文中排除块所占比例(0.0–1.0)。

**转义机制:**若要提及 *(estimated)* 这类标记而不触发解析,请用反引号括起:`*(estimated)*`

声明完成状态(v2.1)

声明的验证状态由字段是否存在决定,而非由显式状态字段决定:

状态confirmed-byconfirmed-date含义
PENDING缺失缺失等待人工验证
VERIFIED存在存在人工已确认
(无效)存在缺失W-HC01:字段不完整
(无效)缺失存在W-HC01:字段不完整

**为什么没有显式状态字段?**字段是否存在会自动约束状态——无法在未提供验证者和日期的情况下意外设置状态。

来源字段语义(v2.1)

source 字段的含义会随声明状态变化:

状态source 内容示例
PENDING验证位置(可执行)"Check Q3 planning doc"
VERIFIED找到的内容(证据)"Q3 planning doc, page 12"

模糊来源检测(W-HC02):"industry reports"、"research"、"TBD" 等来源会触发警告。

声明 ID 格式(v2.1)

通用模式:claim-[a-z0-9._-]{1,64}(字母数字、点、下划线、连字符)

方案模式示例使用场景
基于哈希(首选)claim-[a-f0-9]{8,}claim-75fb137a确定性强,不易冲突
顺序编号claim-[0-9]+claim-1、claim-2简单文档
语义化claim-[a-z0-9-]+claim-revenue-q3便于人工识别

**冲突概率:**在 1,000 条声明中,使用 8 位十六进制 ID 的冲突概率约为 0.012%。声明超过 1,000 条时,请使用 12 位或更多十六进制字符。

**建议:**使用 scripts/claim_id.py 生成基于哈希的 ID,以确保一致性并降低冲突风险。


排除块

如果内容无法核实(例如没有 SME 可用、文本陈旧等),请将其标记为排除,而不要让其含义模糊不清:


Legacy authentication details that require SME review...

规则:

  • ID 必须符合以下格式:[A-Za-z0-9][A-Za-z0-9._-]{0,63}
  • 不得嵌套或重叠
  • 每个 ID 只能使用一次
  • 必须使用 hitl-status: REVIEWED_WITH_EXCEPTIONS
  • 必须在 frontmatter 中记录 exceptions-reason 和 exceptions-ids

重要提示:包含排除块的文档不可导入 RAG,会被整体拒绝(不会进行部分导入)。

完整规则请参阅 CLARITY_GATE_FORMAT_SPEC.md §4。


SOT 验证

验证事实来源文件时,此技能会检查格式合规性(依据 CLARITY_GATE_FORMAT_SPEC.md)和内容质量(9 个要点)。

格式合规性(结构规则)

SOT 文档是带有 tier: 块的 CGD。文档必须包含 ## Verified Claims 部分,并提供有效表格。

代码检查项严重级别
E-TB01缺少 ## Verified Claims 部分ERROR
E-TB02表格没有数据行ERROR
E-TB03缺少必需列(Claim、Value、Source、Verified)ERROR
E-TB04列顺序错误(Claim 不是第一列,或 Verified 不是最后一列)ERROR
E-TB05必需列中存在空单元格ERROR
E-TB06Verified 列中的日期格式无效ERROR
E-TB07Verified 日期在未来(超过 24 小时宽限期)ERROR
内容质量(9 个要点)

9 个验证要点适用于 SOT 内容:

要点SOT 中的应用
1-4检查 ## Verified Claims 中的声明是否经过实际验证
5检查不同表格之间是否存在冲突的值
6检查声明是否暗示了未经支持的因果关系
7检查表格是否将未来描述为现在
8检查日期是否按时间顺序一致
9标记需要外部核查的具体数字
SOT 特定要求
  • **必须包含 Tier 块:**SOT 是带有 tier: 块的 CGD,其中包含 level、owner、version、promoted-date、promoted-by
  • 结构化声明表:## Verified Claims 部分包含以下列:Claim、Value、Source、Verified
  • **表格不得位于排除块中:**已验证声明表不得位于排除块内
  • **时效性标记:**在内容中使用 [STABLE]、[CHECK]、[VOLATILE]、[SNAPSHOT]
    • [STABLE] — 可放心引用,无需重新核查
    • [CHECK] — 引用前先验证
    • [VOLATILE] — 变化频繁;务必验证
    • [SNAPSHOT] — 特定时间点的数据;引用时注明日期

输出格式

运行 Clarity Gate 后,报告:

## Clarity Gate Results

**Document:** [filename]
**Issues Found:** [number]

### Critical (will cause hallucination)
- [issue + location + fix]

### Warning (could cause equivocation)  
- [issue + location + fix]

### Temporal (date/time issues)
- [issue + location + fix]

### Externally Verifiable Claims
| # | Claim | Type | Suggested Verification |
|---|-------|------|------------------------|
| 1 | [claim] | Pricing | [where to verify] |

---

## Round A: Derived Data Confirmation

- [claim] ([source])

Reply "confirmed" or flag any I misread.

---

## Round B: HITL Verification Required

| # | Claim | Why HITL Needed | Human Confirms |
|---|-------|-----------------|----------------|
| 1 | [claim] | [reason] | [ ] True / [ ] False |

---

**Would you like me to produce an annotated CGD version?**

---

**Verdict:** PENDING CONFIRMATION

严重级别

级别定义操作
CRITICAL大模型很可能会将假设当作事实使用前必须修正
WARNING大模型可能会误解应当修正
TEMPORAL检测到日期/时间不一致验证并更新
VERIFIABLE可进行事实核查的具体声明转交 HITL 或进行外部搜索
ROUND A源自经见证的来源快速确认
ROUND B需要真正验证未经确认无法通过
PASS标记明确、没有歧义且已验证无需操作

快速扫描检查清单

模式操作
具体百分比(89%、73%)添加来源或标记为估算值
对比表格添加“PROJECTED”标题
“Achieves”“delivers”“provides”如果尚未验证,改用“designed to”“intended to”
勾选标记确认这些内容已得到证实
任何“100%”的表述几乎总是需要加限定说明
“Last Updated: [date]”对照当前日期检查
带日期的版本号核实时间顺序
“$X.XX”或“~$X”(定价)标记为需要外部验证
“averages”“typically”标记为需要来源/引用
竞争对手能力声明标记为需要外部验证

此技能不做什么

  • 不对文档类型进行分类(请使用 Stream Coding)
  • 不重组文档
  • 不添加深层链接或参考资料
  • 不评估写作质量
  • 不会自主核查事实准确性(需要 HITL)

相关项目

项目用途URL
Source of Truth Creator创建经过认知校准的文档github.com/frmoretto/source-of-truth-creator
Stream Coding文档优先的方法论github.com/frmoretto/stream-coding
ArXiParse科学论文验证arxiparse.org

更新日志

v2.1.3 (2026-03-02)
  • FIXED: document_hash.py 现已实现完整的 FORMAT_SPEC §2.1-2.4 合规
  • FIXED: 围栏感知的结束标记检测(依据 §2.3/§8.5 的 Quine Protection)
  • FIXED: 所有 4 个部署副本已收敛为单一规范实现
  • ADDED: canonicalize() 函数:去除行尾空白、折叠换行、NFC 规范化
  • ADDED: YAML 感知的 document-sha256 移除,支持多行续行(§2.2)
  • ADDED: 围栏跟踪测试向量(7 个新测试,共 15 个)
v2.1.0 (2026-01-27)
  • ADDED: 声明完成状态语义(根据字段存在情况判定 PENDING/VERIFIED)
  • ADDED: 来源字段语义(可操作项与已发现内容)
  • ADDED: 声明 ID 格式指南及冲突分析
  • ADDED: 正文结构要求(存在声明时,HITL 验证记录为强制项)
  • ADDED: 新增验证代码:E-ST10、W-ST11、W-HC01、W-HC02、E-SC06(FORMAT_SPEC §1.2-1.3)
  • ADDED: 捆绑脚本:claim_id.py、document_hash.py
  • UPDATED: 对 FORMAT_SPEC v2.1 的引用
  • UPDATED: CGD 输出示例更新至版本 2.1
v2.0.0 (2026-01-13)
  • ADDED: 符合 agentskills.io 的 YAML frontmatter
  • ADDED: 符合 Clarity Gate Format Specification v2.0(统一 CGD/SOT)
  • ADDED: 支持 SOT 验证,含 E-TB* 错误代码
  • ADDED: 验证规则映射(9 个要点 → 规则代码)
  • ADDED: 含 `` 标记的 CGD 输出格式模板
  • ADDED: Quine Protection 说明(§2.3 围栏感知标记检测)
  • ADDED: 脱敏导出功能(§8.11)
  • UPDATED: hitl-claims 格式更新至 v2.0 schema(id、text、value、source、location、round)
  • UPDATED: 结束标记格式改为 HTML 注释风格
  • UPDATED: 统一格式规范 v2.0(单一 .cgd.md 扩展名)
  • RESTRUCTURED: 为多平台技能发现而重构
v1.6 (2025-12-31)
  • 新增两轮 HITL 验证系统
  • 第 A 轮:派生数据确认
  • 第 B 轮:真正的 HITL 验证
v1.5 (2025-12-28)
  • 新增要点 8:时间一致性
  • 新增要点 9:可外部验证的声明
v1.4 (2025-12-23)
  • 新增 CGD 注释输出模式
v1.3 (2025-12-21)
  • 将要点重构为认知类(1-4)和数据质量类(5-7)
v1.2 (2025-12-21)
  • 新增请求 Source of Truth 步骤
v1.1 (2025-12-21)
  • 新增 HITL 事实核查(强制)
v1.0 (2025-11)
  • 初始版本,含 6 点验证

版本: 2.1.3 规范版本: 2.1 作者: Francesco Marinoni Moretto 许可证: CC-BY-4.0

评论

支持 Markdown