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

第六层：故障排查

通用策略

先收集信息 (Gather Info)：执行 python3 ~/.zhixin/kg.py stats 确认数据库状态；检查文件 ~/.zhixin/zhixin.db 是否存在且可读写
SQLite 锁 (Lock)：database is locked → 等 2 秒重试，不要强行杀进程；持续锁定则检查是否有其他进程持有写锁
JSON 参数解析失败 (Parse Error)：确认 JSON 用单引号包裹（bash），内部用双引号；Windows 下注意引号转义
Ollama 不可达 (Unreachable)：向量命令会自动降级并提示；keyword 搜索 search 始终可用
编码问题 (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" 状态 | 语义错误 | 下版本去掉 "unverified"，改由 update-fact 重置 | | ⏳ 待修复 | fresh_until 无格式校验 | 非法字符串导致 SQL 异常 | 下版本入口校验 YYYY-MM-DD 格式 |

开源声明

| 内容 | 协议 | 文件 | |------|------|------| | 代码 (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 改写 | 通用智能体适配、智能体集成指南、代码审计 |