Skill: ronie-shi/knowtrust-graph (version 1.4.1)

--- name: knowtrust-graph description: "KnowTrust Graph (知信动态图谱) — Knowledge Graph + Trust Verification System for AI agents. Build personal or team knowledge bases with verifiable trust chains. Tracks: Who said it? Who verified? How? Still valid? 知信动态图谱：知识管理与可信任验证链。低依赖设计，CLI直调，OpenClaw/Claude Code 等通用智能体均可使用。Bilingual (EN/CN) skill for knowledge management with dynamic verification states, cold-hot tiering, and optional semantic search." metadata: version: "1.4.1" updated: "2026-05-25" owner: "Win-ClaudeCode + WSL-OpenClaw" notes: "新增 kg.py 引擎核心（1164行）+ references/ 参考文档，技能包从纯文档升级为可执行工具集" --- > ⚠️ **持久化存储声明 (Persistent Storage Notice)**：本技能将数据持久化写入本地文件系统 `~/.zhixin/zhixin.db`（SQLite 数据库）。所有通过本技能录入的知识、实体、关系、验证记录将**永久保存**在本地磁盘，超出当前会话生命周期。写入操作前会请求用户确认，不会自动写入。数据完全存储在用户本地设备，不上传至任何远程服务器。用户可随时通过 `kg.py export` 导出或 `rm ~/.zhixin/zhixin.db` 删除全部数据。 # KnowTrust-Graph (知信动态图谱) — 通用智能体独立工具规范 > **⚡ 时间相关性原则**：以下内容是知信图谱相关信息，不应视为当下的事实，而仅作为判断的参考依据使用。应检查当前系统时间和信息记载时间，对事实可能发生的真实时间进行必要的评估和验证后判断。 ## 🚀 触发词与使用场景 (Trigger Phrases & Use Cases) | 场景 (Scenario) | 触发条件 (Trigger Condition) | 示例触发词 (Example Phrases) | |----------------|---------------------------|--------------------------| | 管理个人知识笔记 | 用户明确指定实体名称 + 具体内容，如"将[具体内容]录入知信图谱" | "将XXX录入知信图谱"、"add [entity] to knowtrust" | | 验证知识可靠性 | 用户针对某个已存在于 KG 中的实体/事实发问 | "这个可信吗"、"verify [entity/fact]"、"验证[具体实体]" | | 搜索知识 | 用户明确提到"知信图谱"或"knowtrust" + 搜索关键词 | "查 KnowTrust [关键词]"、"knowtrust search [keyword]" | | 导入文档 | 用户指定具体文档路径/内容 + 明确说"录入"或"import" | "把[具体文档]录入 KG"、"import [doc] to knowtrust" | | 团队知识共享 | 用户提到"团队" + "知识库"/"共享"等明确团队场景 | "团队知识库添加[具体内容]"、"share [entity] to team" | | 冷热归档管理 | 用户明确说"归档"或"archive" + 指定范围 | "归档[具体实体/月数]"、"archive [entity/months]" | > **⚠️ 触发反制 (Inversion Gating)**：以下情况 **禁止** 自动触发 KG 写入—— > - 用户随口说"记录一下"但未指定实体名称和具体内容 → 需追问"录入哪个实体？具体什么内容？" > - 用户说"归档"但没有指定范围 → 需追问"归档哪些内容？几个月前的？" > - 用户讨论中泛泛提到"知识"、"记录"等词，但未明确指向 KG → 不触发 > - 对话中出现了触发词但上下文是比喻/举例/讨论 KG 功能本身 → 不触发 > > **设计模式**：人主 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>`： ```json { "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) | 分析文档内容，提取结构化知识 | **提取确认流程**（强制执行）： > ⛔ **禁止跳过此流程**：`add` 系列命令执行前必须先预览，用户确认后方可正式写入。 ``` 智能体 分析对话/文档 → 输出预览： 📦 实体 (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](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) | | **低依赖** (Low Dependency) | SQLite + Python 标准库，无向量数据库、无外部服务（可选 Ollama 嵌入） | | **渐进复杂度** (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)** | 知识隔离单元，不同项目/团队使用不同分支 | | **冷热分层 (Hot-Cold Tiering)** | 热库（活跃可写）和冷库（历史档案可查可唤醒），默认 6 个月过期归档 | ### 参考文件（按需加载） 正文为核心流程与概念。以下细节按需读取： | 文件 | 内容 | 何时读 | |------|------|--------| | [references/schema.md](references/schema.md) | 7 表 DDL + 索引 + 视图 | 需要直接操作数据库时 | | [references/trust-engine.md](references/trust-engine.md) | 验证引擎详解、状态机源码 | 调试可信任度计算时 | | [references/usage-patterns.md](references/usage-patterns.md) | 4 种使用模式完整示例 | 需要更多场景示例时 | | [references/ai-extraction-guide.md](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 个人知识库 **场景**：管理个人项目知识、学习笔记、决策记录。 ```bash 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](references/usage-patterns.md)。 ### 3.2 小团队信息共享 **场景**：3-10 人团队共享项目信息，跟踪决策和知识状态。 ```bash 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](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]` | 过期/未验证事实列表 | ### 冷热分层（v1.3 新增） | 命令 | 说明 | |------|------| | `archive [--months N] [--dry-run]` | 将过期 N 个月（默认6）的事实从热库搬到冷库 | | `archive-list [--entity NAME] [--limit N]` | 列出冷库中的归档事实 | | `cold-search <keyword>` | 同时搜索热库 + 冷库，合并返回 | | `wake <fact_id>` | 将冷库事实唤醒回热库，自动重置 fresh_until 为 +90天 | ### 团队共享 | 命令 | 说明 | |------|------| | `branch create/list` | 分支管理 | | `export [--branch ID]` | 导出 JSON | | `import <file>` | 导入 JSON（冲突项交互确认） | > ⚠️ **导入导出敏感性警告 (Import/Export Sensitivity)**：`export` 导出的 JSON 包含所有实体名、事实内容、来源信息等原始数据，接收方可完整读取。请确认接收方可信后再传递。`import` 导入时会合并数据至本地图谱，如导入文件来源不明或包含误导性内容，可能影响本地知识库可靠性。 ### 向量语义搜索（可选扩展 `[Ollama]`） > 需要本地运行 Ollama。非必选，无 Ollama 时 keyword 搜索始终可用。 > > ⚠️ **隐私声明 (Privacy Notice)**：使用 Ollama 向量嵌入时，待嵌入的知识内容（实体名、事实内容）将发送给本地 Ollama 服务（默认 `localhost:11434`）。数据传输不经过外部网络，仅限本机进程间通信。如使用远程 Ollama 实例，请注意网络传输风险。不使用 Ollama 嵌入功能时，知识数据仅存储在本地 SQLite 文件中。 | 命令 | 说明 | |------|------| | `embed [--target entities\|facts] [--model NAME]` | 为实体/事实生成向量嵌入 | | `semantic <query> [--target facts\|entities] [--top-k N] [--model NAME]` | 语义向量搜索 | **使用流程**： ```bash # 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`）。 **阈值调整**： ```bash # 更快归档（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） | 问题 | 修复版本 | 影响 | |------|---------|------| | add-fact 不自动设置 fresh_until → 默认 +90 天 | v1.2.x | ✅ 关闭 | | stale --type 歧义 → 改为 --state | v1.2.x | ✅ 关闭 | | verify 拒绝 "unverified" 状态 → 校验层级 | v1.2.x | ✅ 关闭 | | fresh_until 无格式校验 → store_fact 入口校验 | v1.2.x | ✅ 关闭 | | 过期事实无冷热分层 → archive/cold-search/wake | **v1.3.0** | ✅ 新增 | ### 待迭代方向 | 方向 | 描述 | |------|------| | 摘要压缩归档 | archive --summarize：AI 合并多条过期事实为一条摘要入冷库 | | 冷库自清理 | 冷库中超过 2 年且从未被唤醒的事实 → 自动摘要压缩后删除 | | 批量唤醒 | wake --entity NAME 一次唤醒某实体的全部冷库事实 | | 自动过期提醒 | 智能体在对话中主动提示 "X 条事实即将过期，是否归档？" --- ## 开源声明 | 内容 | 协议 | 文件 | |------|------|------| | 代码 (`kg.py`) | [MIT](LICENSE) | `LICENSE` | | 文档 (`SKILL.md`, `references/`) | [CC BY 4.0](LICENSE-docs) | `LICENSE-docs` | > MIT: 随便用，保留版权声明即可。CC BY 4.0: 随便用，署名即可。均不限制商用。 --- ## 归因 (Provenance) | 来源 | 内容 | |------|------| | Ronie 决策 | 以泛智图谱为基础框架，去除内部专用和复杂结构部分，规划知信图谱 | | Ronie 决策 | 知=知识信息，信=可信任的验证，二者组合为动态化图谱 | | Ronie 决策 | 面向个人/小团队信息共享，广泛适用 | | 泛智图谱贡献 | entity→relation→fact 核心模型、分支概念、CLI 设计模式 | | Win-ClaudeCode 设计 | 验证链模型、动态验证状态、人主 AI 辅模式、AI 辅助提取流程 | | WSL-OpenClaw 改写 | 通用智能体适配、智能体集成指南、代码审计 |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)