Knowtrust Graph Publish

KnowTrust-Graph — 知识+可信任验证的动态化图谱。当用户提到知识管理、验证知识、知识图谱、KG、KnowTrust、信知时使用。实体-关系-事实三层模型+验证链追踪。零依赖，CLI直调。

KnowTrust-Graph (知信动态图谱) — 通用智能体独立工具规范

设计模式：人主 AI 辅 — 人类决策确认，AI/智能体协助整理、关联、验证提醒。 适用智能体：任何支持 Python 环境和 CLI 调用的 AI 智能体系统（OpenClaw、Claude Code、其他 Agent 框架等均可加载使用）。 核心定义：知识 (Know) + 可信任的验证 (Trust) → 动态化图谱 (Graph) 依赖：仅 Python 标准库（sqlite3, json, argparse, uuid, datetime）+ 可选 Ollama 嵌入。

---

适用智能体

本规范是智能体无关的独立工具规范。任何 AI 智能体只要满足以下条件即可加载：

• 宿主环境有 Python 3.8+
• 具有 CLI 执行能力（可调用 python3 ~/.zhixin/kg.py <command>）
• 具有文件读写权限（可读写 ~/.zhixin/zhixin.db）

无需修改即可在以下系统中使用：

• OpenClaw（通过 exec/process 调用 CLI）
• Claude Code（通过 Tool 定义调用）
• Cline/Continue.dev（通过 MCP 或直接 CLI）
• 其他自定义 Agent 框架

---

智能体集成指南

集成方式 A：通过 CLI 直调

智能体只需定义工具调用规范，映射到 python3 ~/.zhixin/kg.py <command>：

{
  "name": "zhixin-add-fact",
  "description": "向知信图谱添加一条事实（知识陈述）",
  "parameters": {
    "entity_name": "string (关联实体名称)",
    "content": "string (事实内容)",
    "fact_type": "string (knowledge/opinion/decision/status/constraint)",
    "source_name": "string (来源名称，可选)",
    "verification": "string (unverified/self_checked，可选，默认unverified)"
  },
  "command": "python3 ~/.zhixin/kg.py add-fact '<json>'"
}

集成方式 B：AI 辅助提取流程

当用户表达以下意图时，智能体应介入执行知识提取：

用户意图 (User Intent)	智能体动作 (Agent Action)
"把这些整理到 KnowTrust" (Organize into KnowTrust)	分析当前对话/文档，提取实体/关系/事实 → 预览 → 用户确认 → 批量写入
"查 KnowTrust X" (Search KnowTrust for X)	搜索 KG，返回相关知识 + 可信任状态
"X 在 KnowTrust 里怎么验证的" (How is X verified?)	展示 X 相关事实的完整验证链 (Show verification chain)
"这段文档录入 KnowTrust" (Import this document)	分析文档内容，提取结构化知识

提取确认流程：

智能体 分析对话/文档
  → 输出预览：
    📦 实体 (3个): 张三(person), 项目A(project), FastAPI(tool)
    🔗 关系 (2条): 张三 works_on 项目A, 项目A depends_on FastAPI
    📝 事实 (5条): [全部默认 unverified，标注来源]
  → 用户审查：确认/修改/删除
  → 智能体 批量调用 kg.py 写入
  → 输出摘要："新增3实体2关系5事实，其中2条待验证"

提取 JSON 格式定义与更多场景示例见 references/ai-extraction-guide.md。

---

第〇层：概念总览

知 (Know) + 信 (Trust) = 知信

维度	含义 (Meaning)	核心问题 (Core Question)
知 (Know)	知识信息 (Knowledge)	"我们知道了什么？" (What do we know?)
信 (Trust)	可信任的验证 (Verifiable Trust)	"凭什么信？谁验证过？" (Why trust? Who verified?)

关键洞察 (Key Insight)：知信图谱不是"知识库+信任打分"的两层分离结构，而是知识与验证在同一图谱中动态交织 (dynamically interwoven)。一条知识被验证后，它的"可信任状态"随之演化——图谱实时反映"什么已知且可信"。

设计原则

原则 (Principle)	含义 (Meaning)
人主AI辅 (Human-led, AI-assisted)	人类做决策和确认，AI/智能体协助整理、关联、检查。不自动写入
验证可追溯 (Verifiable Traceability)	每条知识可追溯到"谁说的→谁验证的→怎么验证的→是否仍有效" (who said → who verified → how → is it still valid)
零依赖 (Zero Dependency)	SQLite + Python 标准库，无向量数据库、无外部服务
渐进复杂度 (Progressive Complexity)	个人使用 7 表；团队使用扩展分支。2 可选向量表
文件共享 (File-based Sharing)	JSON 导出/导入实现团队同步，不依赖网络服务
动态演化 (Dynamic Evolution)	知识状态随验证行为变化，图谱是活的不是静态快照

术语表

术语	含义
实体 (Entity)	知识节点：人、项目、概念、工具、事件、文档、组织
关系 (Relation)	实体间的有向边：works_on / knows / depends_on / contains / created_by
事实 (Fact)	附着于实体的知识原子：一条陈述 + 验证链
信息源 (Source)	"谁说的" — 事实的来源，有人工评定的可信度
验证链 (Verification Chain)	信息源 → 验证行为 → 验证方法 → 有效期限 → 团队共识
验证状态 (Verification State)	动态状态：unverified → self_checked → peer_reviewed → external_confirmed
标注 (Annotation)	团队成员对事实的确认/质疑/澄清/更新 — 验证行为的记录
分支 (Branch)	知识隔离单元，不同项目/团队使用不同分支

参考文件（按需加载）

正文为核心流程与概念。以下细节按需读取：

文件	内容	何时读
references/schema.md	7 表 DDL + 索引 + 视图	需要直接操作数据库时
references/trust-engine.md	验证引擎详解、状态机源码	调试可信任度计算时
references/usage-patterns.md	4 种使用模式完整示例	需要更多场景示例时
references/ai-extraction-guide.md	AI 提取 JSON 格式定义 + 场景示例	实现 AI 辅助提取时

---

第一层：知识模型（知 — 记录什么）

1.1 实体类型

类型 (Type)	中文示例 (Example)
person	张三、Alice
project	KnowTrust 开发、Q3 营销计划
concept	验证链模型 (Verification Chain Model)、敏捷开发 (Agile)
tool	kg.py、Figma
event	2026-05-10 项目启动会
document	需求规格说明书 v2
org	产品部、XX 公司

1.2 关系类型

类型 (Type)	含义 (Meaning)	示例 (Example)
works_on	参与/负责 (Works on, responsible for)	张三 works_on KnowTrust
knows	认识/了解 (Knows, understands)	张三 knows 机器学习 (Machine Learning)
depends_on	依赖 (Depends on)	KnowTrust depends_on SQLite
contains	包含 (Contains)	Q3 计划 contains 市场调研 (Market Research)
created_by	由...创建 (Created by)	kg.py created_by 张三
related_to	一般关联 (Generally related)	项目A related_to 项目B
before / after	时序 (Temporal order)	需求评审 (Requirements Review) before 开发启动 (Dev Start)

1.3 事实类型

类型 (Type)	含义 (Meaning)	有效期特征 (Freshness)
knowledge	客观知识 (Objective Knowledge)	长期—除非被证伪 (Long-term, until falsified)
opinion	个人观点 (Personal Opinion)	可能变化，需标注持有者 (Volatile, track holder)
decision	决策记录 (Decision Record)	长期—历史记录 (Permanent, historical)
status	状态信息 (Status Update)	短中期，需定期更新 (Short-medium term, refresh)
constraint	约束条件 (Constraint)	持续有效直到解除 (Active until lifted)

---

第二层：验证模型（信 — 凭什么信）

2.1 验证链（核心概念）

知信图谱的"信"不只是一个分数，而是一条可追溯的验证链：

信息源 → 源可信度 → 验证行为 → 验证方法 → 有效期限 → 团队共识
(Source) (Reliability) (Verified?) (How verified?) (Still valid?) (Consensus?)
(谁说的) (此人可靠吗) (核实过吗) (怎么核实的) (过期了吗) (别人认可吗)

2.2 动态验证状态

每条事实有一个动态状态，随验证行为自动切换：

状态 (State)	含义 (Meaning)	触发 (Trigger)
unverified	未验证，仅供参考 (Unverified, for reference only)	新录入默认 (Default for new entries)
self_checked	录入者自查过 (Self-checked by author)	--verify <id> --level self_checked
peer_reviewed	团队成员复核过 (Peer reviewed)	至少 1 人标注 confirm (≥1 confirm)
external_confirmed	外部权威确认 (External authority confirmed)	--verify <id> --level external_confirmed
disputed	存在质疑 (Disputed/challenged)	有人标注 dispute
outdated	已过期 (Expired, needs refresh)	fresh_until 超期未续
consensus	团队共识 (Team consensus)	≥3 人标注 confirm

2.3 可信任度（量化参考）

当需要量化比较时：

Verifiability = 0.30 × SourceReliability + 0.35 × VerificationDepth
             + 0.20 × Freshness + 0.15 × ConsensusRatio

维度 (Dimension)	权重 (Weight)	取值逻辑 (Logic)
源可靠性 (Source Reliability)	30%	sources 人工评定 (Human-rated)
验证深度 (Verification Depth)	35%	unverified=0, self_checked=0.3, peer_reviewed=0.7, external_confirmed=1.0
新鲜度 (Freshness)	20%	有效期内=1.0, 过期每 30 天 -0.1, ≥300 天=0
共识度 (Consensus Ratio)	15%	confirm/(confirm+dispute), 无标注=0.5

---

第三层：使用模式

3.1 个人知识库

场景：管理个人项目知识、学习笔记、决策记录。

python3 ~/.zhixin/kg.py init
python3 ~/.zhixin/kg.py add-entity '{"name":"张三","type":"person","description":"后端开发"}'
python3 ~/.zhixin/kg.py add-fact '{"entity_name":"我的项目","content":"使用Python 3.12和FastAPI","fact_type":"knowledge","source_name":"我自己","verification":"self_checked"}'
python3 ~/.zhixin/kg.py search "FastAPI"
python3 ~/.zhixin/kg.py entity "我的项目"
python3 ~/.zhixin/kg.py stale --type unverified

更多场景示例见 references/usage-patterns.md。

3.2 小团队信息共享

场景：3-10 人团队共享项目信息，跟踪决策和知识状态。

python3 ~/.zhixin/kg.py branch create '{"name":"team-alpha","description":"Alpha团队知识库"}'
python3 ~/.zhixin/kg.py verify <fact_id> --level peer_reviewed
python3 ~/.zhixin/kg.py annotate '{"fact_id":"<id>","annotator":"李四","type":"confirm","content":"已核实"}'
python3 ~/.zhixin/kg.py check-report --entity "核心决策"
python3 ~/.zhixin/kg.py stale --days 7
python3 ~/.zhixin/kg.py export > team-kg.json
python3 ~/.zhixin/kg.py import team-kg.json

完整团队协作流程见 references/usage-patterns.md。

---

第四层：CLI 命令速查

初始化与统计

命令	说明
init	初始化数据库（~/.zhixin/zhixin.db）
stats	数据库统计概览

知识写入

命令	说明
add-entity <JSON>	添加实体
add-fact <JSON>	添加事实
add-relation <JSON>	添加关系
add-source <JSON>	注册信息源
update-fact <id> <JSON>	更新事实内容

知识查询

命令	说明
search <keyword>	全文搜索实体和事实
entity <name>	查看实体详情（含关联事实和关系）
traverse <name> [--depth N]	关系图遍历
recent [--days N]	最近 N 天的更新

验证与可信度（核心）

命令	说明
verify <id> --level <L>	更新验证深度（self_checked / peer_reviewed / external_confirmed）
annotate <JSON>	添加标注（确认/质疑/澄清）
check <id>	查看单条事实的验证链与可信任状态
check-report [--entity NAME]	实体关联事实的可信任全景
stale [--days N] [--state STATE]	过期/未验证事实列表

团队共享

命令	说明
branch create/list	分支管理
export [--branch ID]	导出 JSON
import <file>	导入 JSON（冲突项交互确认）

向量语义搜索（可选扩展 [Ollama]）

需要本地运行 Ollama。非必选，无 Ollama 时 keyword 搜索始终可用。

命令	说明
embed [--target entities|facts] [--model NAME]	为实体/事实生成向量嵌入
semantic <query> [--target facts|entities] [--top-k N] [--model NAME]	语义向量搜索

使用流程：

# 1. 确保 Ollama 运行中（有 embedding 模型即可）
# 2. 生成向量嵌入
python3 ~/.zhixin/kg.py embed                    # 为所有实体生成嵌入
python3 ~/.zhixin/kg.py embed --target facts     # 为所有事实生成嵌入

# 3. 语义搜索
python3 ~/.zhixin/kg.py semantic "数据库技术选型"
python3 ~/.zhixin/kg.py semantic "性能瓶颈" --top-k 5

---

第五层：典型工作流

工作流 A：录入并验证一条知识

1. --add-fact 录入（默认 unverified）
2. 录入者 --verify self_checked（自查）
3. 队友 --annotate confirm（复核）
4. 状态自动变为 peer_reviewed
5. 多人 confirm → 状态变为 consensus

工作流 B：智能体辅助批量录入

1. 用户："把今天会议讨论的内容整理到 KnowTrust" (Organize today's meeting into KnowTrust)
2. 智能体 分析对话 → 输出结构化预览（实体/关系/事实）
3. 用户确认/修改 → 智能体 批量调用 kg.py 写入
4. 所有新事实默认 unverified，提示用户后续验证

工作流 C：过期检查

1. 定期 --stale --days 7 查看即将过期的事实
2. 对过期的：update-fact 更新内容 + 延长 fresh_until
3. 对仍有效的：update-fact 直接延长 fresh_until

---

第六层：故障排查

通用策略

1. 先收集信息 (Gather Info)：执行 python3 ~/.zhixin/kg.py stats 确认数据库状态；检查文件 ~/.zhixin/zhixin.db 是否存在且可读写
2. SQLite 锁 (Lock)：database is locked → 等 2 秒重试，不要强行杀进程；持续锁定则检查是否有其他进程持有写锁
3. JSON 参数解析失败 (Parse Error)：确认 JSON 用单引号包裹（bash），内部用双引号；Windows 下注意引号转义
4. Ollama 不可达 (Unreachable)：向量命令会自动降级并提示；keyword 搜索 search 始终可用
5. 编码问题 (Encoding)：中文内容确认文件编码为 UTF-8，Windows 终端可能需要 chcp 65001

已知待迭代项（2026-05-11）

状态	问题	影响	修复方案
✅ 已修复	add-fact 不自动设置 fresh_until	新鲜度维度形同虚设	默认 +90 天自动填充（2026-05-12）
✅ 已修复	stale --type 歧义	--type 名称不直观	改为 --state，保留 --type 向后兼容（2026-05-12）
✅ 已修复	verify 拒绝 "unverified" 状态	语义错误	handle_verify_fact() 显式校验 level 必须在 {self_verified, peer_confirmed, external_confirmed, consensus}（2026-05-13）
✅ 已修复	fresh_until 无格式校验	非法字符串导致 SQL 异常	store_fact() 入口校验 YYYY-MM-DD 格式，非法 raise ValueError；默认 +90 天（2026-05-13）

---

开源声明

内容	协议	文件
代码 (kg.py)	MIT	LICENSE
文档 (SKILL.md, references/)	CC BY 4.0	LICENSE-docs

MIT: 随便用，保留版权声明即可。CC BY 4.0: 随便用，署名即可。均不限制商用。

---

归因 (Provenance)

来源	内容
Ronie 决策	以泛智图谱为基础框架，去除内部专用和复杂结构部分，规划知信图谱
Ronie 决策	知=知识信息，信=可信任的验证，二者组合为动态化图谱
Ronie 决策	面向个人/小团队信息共享，广泛适用
泛智图谱贡献	entity→relation→fact 核心模型、分支概念、CLI 设计模式
Win-ClaudeCode 设计	验证链模型、动态验证状态、人主 AI 辅模式、AI 辅助提取流程
WSL-OpenClaw 改写	通用智能体适配、智能体集成指南、代码审计