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

🚀 触发词与使用场景 (Trigger Phrases & Use Cases)

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

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

提取确认流程：

智能体 分析对话/文档
  → 输出预览：
    📦 实体 (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) = 知信

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

设计原则

术语表

参考文件（按需加载）

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

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

1.1 实体类型

1.2 关系类型

1.3 事实类型

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

2.1 验证链（核心概念）

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

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

2.2 动态验证状态

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

2.3 可信任度（量化参考）

当需要量化比较时：

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

第三层：使用模式

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 命令速查

初始化与统计

知识写入

知识查询

验证与可信度（核心）

冷热分层（v1.3 新增）

团队共享

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

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

使用流程：

# 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

工作流 D：冷热分层生命周期（v1.3 新增）

当知识持续积累，过期事实会拖慢查询并干扰可信度判断。 冷热分层将知识分为热库（活跃知识）和冷库（历史档案）：

1. 定期 --archive --dry-run 预览待归档事实
2. --archive 执行归档（默认6个月过期阈值）
3. 归档的事实仍在冷库中可查询：--cold-search
4. 需要时 --wake <id> 唤醒回热库（fresh_until 自动重置为 +90天）
5. --archive-list 查看冷库清单
6. --stats 显示冷热库统计

设计哲学：归档 ≠ 删除。冷库是可查询的历史档案，被唤醒的事实重获新生。 人决定什么时候归档（通过 --archive），什么时候唤醒（通过 --wake）。 AI/智能体协助发现和提醒（通过 --stale 和 --cold-search）。

阈值调整：

# 更快归档（3个月过期阈值）
kg.py archive --months 3

# 更保守（12个月过期阈值）
kg.py archive --months 12 --dry-run  # 先预览

第六层：故障排查

通用策略

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-14）

待迭代方向

开源声明

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

归因 (Provenance)