KG-SSOT

---

为什么

无论团队由人还是由 Agent 组成，都会积累各种结论：“重试是幂等的”“我们决定重试三次”。 这些结论散落在会议记录、工单和聊天记录中，逐渐失去三项关键信息：来源、上次验证日期以及依赖它的内容。缺少这三项信息的说法即使听起来可信，也能通过匆忙的审查。

KG-SSOT 将此视为格式问题，而非纪律问题。知识存储在 .kg.yaml 图谱中，与代码一同进行版本管理；正式契约则决定 CI 中哪些内容会导致失败：

• confirmed 或生产节点缺少来源信息时会导致失败（无法恢复来源的声明会被标记为 unverifiable）；
• 仅为占位符（unknown、n/a、tbd）的来源会导致失败；
• 指向不存在目标的边会导致失败，没有任何边的节点也会导致失败；
• 没有可供核对内容的验证记录、没有来源的决策，以及仅由证词支持的生产声明会产生警告。

60 秒快速入门

pip install kg-ssot

# the conformance suite against the reference reader, from the installed package
kg-conformance | tail -2

# one valid graph and one that fails
kg-validate valid.kg.yaml broken.kg.yaml

也可以直接从代码仓库开始，并使用经过哈希校验的依赖项：

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt
.venv/bin/python3 -I tools/kg_validate.py \
  spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \
  spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

PASS spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml
FAIL spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml
  MUST   form.required.node.label ×1
· 2 files; 1 pass the MUST; 0 with a SHOULD warning (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

这些工具默认使用英语输出；当你的语言区域设置为 pt_BR（或设置 KG_SSOT_LANG=pt-BR）时，则使用巴西葡萄牙语输出。代码、退出码和 JSON 键不会随语言变化，只有面向用户的文本会变化。

安装

渠道	命令	包含内容
PyPI	pip install kg-ssot	命令 kg-validate、kg-conformance、kg-gate、kg-store、kg-query、kg-diff、kg-vocab、kg-criterion、kg-audit、kg-trace、kg-vector、kg-mcp 和 kg-prov-export，以及其中的契约和测试套件；pip install "kg-ssot[vector]" 会增加相似度搜索功能
npm	npm install kg-ssot	JavaScript 读取器及预编译的验证器，也可在 React Native 和 Expo 中运行
Claude Desktop	来自最新版本的 .mcpb 文件	MCP 服务，作为一键安装的扩展
MCP Registry	io.github.marciocar/kg-ssot	适用于任何 MCP 客户端的同一服务
容器	docker pull ghcr.io/marciocar/kg-ssot	MCP 服务，可作为服务与无需 Python 的客户端并列运行，例如 LibreChat
你的代码库	kg_vendor.py update --tag kg-ssot-v4.30.0	按标签引入的版本，附带 sha256 印记，并在 CI 中运行门禁（手册，第 6 章）

节点内部

- id: C_RETRY_SAFE
  node_type: claim
  plane: PROD
  status: confirmed
  impact: 4
  confidence: 0.8
  label: The payment retry is idempotent.
  verified_at: "2026-10-01"
  verified_against: tests/payment_retry_test.py
  provenance:
    source: tests/payment_retry_test.py
    locator: test_retry_is_idempotent
    method: "medição: integration test in CI"

label 是简短的主张。provenance 说明来源以及方式：五种方法类别之一， medição（测量）、leitura（阅读）、juízes（评审）、derivado（派生）或 testemunho（证词）。 印记说明验证时间和验证依据。方法类别是契约中的字面值，保持原样。

在 AI Agent 中使用

参考 MCP 服务向模型提供契约和存储：验证图，只写入通过验证的内容， 读取、列出、查询（将每条边解析为另一端节点的标签），并显示历史记录。只读工具会 明确标注，客户端可以跳过对它们的确认。

kg-mcp --root ./graphs          # stdio, for Claude Desktop, Claude Code and other MCP clients

kg_schema_help 会返回当前契约、一个最小通过示例，以及最常见错误代码的修复方法，让模型首次尝试就能写出通过验证的图。llms.txt 为 Agent 编制了文档索引， llms-full.txt 则将全部文档收录在一个文件中。

Agent 技能。 skills/kg-ssot/ 是一项 Agent Skills 技能，可指导编码 Agent 使用这些工具，以 .kg.yaml 和 .kg.json 格式编写、修复、验证和查询图。在一项预先注册的测试中，启用该技能的 Agent 只用了 45% 的输出令牌和 54% 的工具调用，就达到了相同结果。

npx skills add marciocar/kg-ssot -s kg-ssot     # Claude Code, Codex and other clients that read Agent Skills

在 Claude Code 中，它也以插件形式提供：/plugin marketplace add marciocar/kg-ssot，然后运行 /plugin install kg-ssot@kg-ssot。

工作原理

flowchart LR
  subgraph product["Product (one tag kg-ssot-vX.Y.Z)"]
    C["Contract<br/>JSON Schema MUST + SHOULD<br/>+ integrity rules"]
    S["Conformance suite<br/>438 cases as plain data"]
    R["Reference reader<br/>kg_validate.py"]
    S -- "every reader passes" --> R
    C --> R
  end
  subgraph adopter["Adopter repository"]
    V["vendor/kg-ssot<br/>+ sha256 stamp"]
    G["kg_gate.py in CI<br/>per-graph ratchet"]
    K["the team's .kg.yaml"]
    V --> G
    K --> G
  end
  product -- "kg_vendor.py update --tag" --> V
  G -- "nothing gets worse:<br/>a new graph passes,<br/>debt only shrinks" --> PR["PR approved"]

1. 契约采用 JSON Schema 2020-12，分为两个级别：违反 MUST 规则会失败，违反 SHOULD 规则会发出警告。模式无法表达的规则（ID 唯一、边的端点必须存在、节点不得孤立）也包含在契约中。
2. 测试套件是兼容性证明：每个案例都是一个真实的 YAML 文件，包含预期判定和代码；读取器只有在输出完全相同的代码时才算通过。
3. 工具包按标签将契约引入代码库，并附带可阻止本地修改的印记，还会在 CI 中运行逐图棘轮机制：已失败的内容会变成有名称的债务，新图必须通过验证，债务只会减少。

功能

双层契约	MUST 会导致失败，SHOULD 会发出警告，并设有渐进机制：某个版本中仅发出警告的内容，下一版本可能会导致失败，采用者也能提前知晓
结构化来源信息	包含 source、locator 和 method，以及五类证据和来源位置（repo、web、host、pessoa、privado）
验证标记	包含 verified_at 和 verified_against；如果标记没有目标，或验证日期早于事实发生日期，则发出警告
图之间的边	使用 external_edges，并根据语料库检查另一端
稳定代码	每条违规都有代码，例如 form.required.node.provenance；--where 指明节点
结构化判定结果	kg_validate.py --format json 以版本化格式（spec/verdict.schema.json）返回判定结果，其中包含代码、文档路径、行号、消息和修复提示，供工具和 MCP 服务使用
两种格式，一个模型	使用 .kg.yaml 编写并在差异中审查，使用 .kg.json 供运行时（应用、服务）使用；由 JSON 解析器根据契约的 JSON 配置文件读取（RFC 8259、I-JSON、最多 128 层、键唯一）
受门禁控制的存储	kg_store.py 仅在契约通过后，才将 .kg.yaml 或 .kg.json 写入磁盘、git 仓库或带版本的存储；在存储中检查外部边，并通过乐观锁处理并发写入
参考 MCP 服务	kg_mcp.py 通过 MCP 提供契约和存储（stdio，或通过代理并按身份划分区域的 HTTP），并带有工具注释
查询与差异比较	kg_query.py 从整个语料库中选择节点，并投影每条边及其另一端的标签，支持分页（kg-ssot.query/1）；kg_diff.py 按 ID 逐字段比较修订版本，无需检出即可读取 git（kg-ssot.diff/1）
领域词汇	x_term 配置文件为每个同义词提供其来源、文档版本和验证日期；kg_vocab.py 将文本解析为对应术语、列出到期项，并导出为 SKOS-XL 和 Apache Ossie（kg-ssot.vocab/1）；MCP 服务以 kg_terms 提供这些内容。从 4.23 版起，短代码可在其方案中获得易读名称（notation 和 scheme），而 kg_vocab.py lint 会通过棘轮机制检查正文中的代码
预先注册的判据	x_criterion 为标尺的每个版本分配一个节点和 sha256，x_measured_under 将结果与其测量所依据的版本关联；如果看过数据后再更改标尺，就会出现事后警告；kg_criterion.py 会根据文本或文件检查 sha256（kg-ssot.criterion/1）
可解析的追踪信息	kg_trace.py check --root . 会根据仓库中的文件检查每个节点的 trace: 锚点（integrity.trace-target-missing、kg-ssot.trace/1），并单独统计其不作判定的内容
按含义搜索	kg_query.py --text <term> --semantic "<question>" 可在问题采用不同措辞时找到对应节点；它通过 RRF 融合文本搜索和本地多语言嵌入模型。此功能为可选项（kg-ssot[vector]），由 sha256 固定，并且不影响任何判定结果
按问题生成审计包	kg_audit.py 为每个问卷条目（x_questionnaire 配置文件）导出一行，其中包含问题、答案、判定结果、必需证据和已提供证据（附日期和到期日）、证据请求（role: evidence_request 和 evidence_requirement）、矛盾、负责人及其计算出的缺口；支持 CSV、XLSX（无依赖）或 JSON（kg-ssot.audit/1）
纯数据测试套件	包含 438 个测试用例及其独立的元模式，采用 JSON-Schema-Test-Suite 的风格
按图设置棘轮	无需一次性全面迁移即可采用：继承的债务会保留其明确标识，且只会逐渐减少
按标签引入供应商版本	不复制粘贴，不共享代码：每个文件各有一个 sha256 标记
配置文件驱动的迁移器	kg_migrate.py 根据采用者声明的规则，提出契约要求的 provenance，先展示计划，再以逐节点不变的方式写入
PROV-O 桥接	kg_prov_export.py 将每个节点的来源信息导出为 JSON-LD 中的 prov:Entity 和 prov:Derivation，以接入 W3C PROV 生态；--edges 会添加边，并在存在标准术语时使用 cito:supports、cito:refutes 和 dcterms:replaces
无需平台	Python 3.11 或更高版本、PyYAML 和 jsonschema，使用经过校验的哈希安装（--require-hashes）。无需服务、编辑器或助手

KG-SSOT 不是什么

如果你需要……	……请使用其他方案	KG-SSOT 为你提供什么
在大型图上使用查询语言	图数据库	一种文件格式和一份契约，无需服务端
语义网互操作性	RDF、OWL、SHACL	一套精简、封闭的 YAML 词汇表，便于在差异中阅读，并支持 PROV-O 导出
对文档进行企业级搜索	搜索平台	不提供连接器或索引：只有团队编写的图
保证某个声明为真	人工审核、测试	保证它说明了来源和验证时间

状态

• **当前：**契约 v4，发布版本为 kg-ssot-v4.30.0。参考读取器通过了 latest/ 中 438 个用例里的 424 个。
• **使用中：**三家采用者在 CI 中运行该门禁，其中一家已在生产环境中使用。
• **下一步：**v5 将对不符合 <class>: <detail> 格式的 method 报错；目前只会发出警告。
• **待处理：**语义层（新鲜度、矛盾、领域完整性）位于 optional/ 中，参考读取器尚未实现该层：它只通过了其中 10 个有效用例。

文档

手册	概念、格式、契约、工具、操作指南和故障排查
ADOPTING.md	完整的采用指南，涵盖所有边界情况
契约	契约 v4：两个级别、代码，以及不同版本之间的变化
spec/conformance/	套件格式、代码，以及如何衡量其他语言的读取器
CHANGELOG.md	所有发布记录，按时间从新到旧排列
llms.txt · llms-full.txt	供 AI Agent 使用：包含链接的索引，以及合并为单个文件的完整文档

贡献

契约变更始于一个一致性用例：展示行为和预期判定的 .kg.yaml 文件。发布版本是开发仓库中的 kg-ssot-vX.Y.Z 标签；每个涉及 spec/ 或 tools/ 的拉取请求都会在 CI 中运行套件和工具包测试。发布镜像只包含每个标签发布的内容，每个标签对应一个提交，并且不接受拉取请求：提案或错误请通过问题提交，最好附上能展示问题的用例。欢迎使用其他语言编写读取器：手册第 7 章介绍了如何衡量读取器。

许可证

产品（发布内容，列于 spec/release.json：契约、套件、.kg.yaml 用例、tools/ 中的工具包、ADOPTING.md、本 README 和手册）采用 Apache-2.0 许可证：LICENSE，具体范围见 NOTICE。

_{KG-SSOT 源自 Onion 框架；如今 Onion 像其他采用者一样，通过标签采用 KG-SSOT。产品不依赖 Onion。}