Knowledge Graph

核心用法

Knowledge Graph 是一套基于文件系统的本地知识管理方案，通过 Python 脚本操作 life/areas/** 目录下的实体数据。主要提供三类原子操作：

1. 添加事实 (`add`)：向指定实体注入新的结构化信息，自动生成递增 ID（如 safa-001），标记来源与时间戳
2. 替换事实 (`supersede`)：将旧事实标记为「已淘汰」并创建继承关系的新事实，保留完整历史链条
3. 生成摘要 (`summarize`)：基于当前有效事实自动编译 Markdown 格式的实体摘要

数据结构采用极简设计：实体目录下 items.json 存储事实数组，summary.md 存放渲染后的摘要。事实永不删除的设计哲学确保了知识演化的可追溯性。

显著优点

• 数据安全优先：纯本地文件操作，零外部网络依赖，符合隐私敏感场景
• 确定性更新：脚本化 workflow 避免手动 JSON 编辑的格式错误与 ID 冲突
• 历史完整性：supersede 机制实现软删除，支持知识溯源与审计
• 轻量无依赖：仅使用 Python 标准库，部署成本极低
• 安全评级优异：自动化扫描获 A 级（95 分），静态/动态/隐私维度均通过

局限性与风险

• T3 来源可信度：个人开发者/社区项目背景，需自行承担长期维护风险
• 正则误报噪音：re.compile 被扫描工具误识别为动态代码执行（已确认为 false positive）
• 无内置备份：直接覆写 JSON 文件，异常中断可能导致数据损坏
• 单用户设计：缺乏并发控制与权限隔离，不适合多用户协作场景
• 扩展性天花板：文件系统后端在事实量级增长后可能出现性能瓶颈

适合人群

• 重视数据主权、拒绝云端服务的个人知识管理用户
• 需要结构化记录实体信息（人物、项目、概念）并追踪其演化的研究者
• 已在使用 life/areas/ 目录体系的 Clawdbot 生态用户
• 对 Python 脚本操作有基本信任的技术用户

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 数据丢失 | 中 | 无自动备份机制，建议配合 git 版本控制使用 |

| 误操作覆盖 | 低 | 脚本参数校验完整，但需确认 entity 路径正确 |

| 依赖断供 | 中 | T3 来源意味着无商业支持承诺 |

| 正则注入 | 无 | 实际为静态模式匹配，无动态执行风险 |

核心用法

Knowledge Graph 是一套基于文件系统的实体知识管理 Skill，通过 Python 脚本操作 life/areas/ 目录下的结构化数据。核心功能包括：

1. 添加事实 (add)：为指定实体创建新的原子化事实，自动生成递增 ID
2. 替代事实 (supersede)：标记旧事实为失效状态，同时创建新事实，保留历史记录
3. 生成摘要 (summarize)：基于活跃事实自动整合实体摘要

数据采用双文件结构存储：items.json 存放事实数组（含 ID、内容、状态、时间戳、来源），summary.md 存放可读摘要。

显著优点

• 零依赖安全：纯 Python 标准库实现（argparse、json、pathlib 等），无第三方包，彻底规避供应链攻击
• 数据持久化：文件级存储，版本控制友好，事实永不删除（仅标记 superseded），完整保留演变历史
• 确定性更新：脚本化操作避免手工编辑 JSON 的错误，ID 自动生成保证一致性
• 极简运维：单脚本 ~263 行，8.9KB 体积，适合长期个人知识库维护

局限与风险

• 无并发控制：文件级锁缺失，多进程同时写入可能损坏数据
• 无查询能力：仅支持按实体遍历，无法跨实体复杂检索或图遍历
• 无同步机制：纯本地存储，跨设备同步需依赖外部工具（如 Git）
• 输入验证有限：路径正则仅防基本遍历，特殊字符处理依赖操作系统

适合人群

• 注重数据主权、偏好本地优先的笔记极客
• 已使用 Git 管理知识库的技术用户
• 需要结构化追踪人物/项目/领域演变的个人研究者

常规风险

• 数据丢失风险：无内置备份，建议配合 Git 或 rsync 定期备份 life/areas/
• 迁移成本：目录结构与 ID 格式耦合，未来迁移需脚本转换
• 误操作覆盖：supersede 操作不可逆（旧事实标记后无法"复活"），建议操作前查看当前 facts