mini-context-graph

Mini Context Graph 技能

核心理念

标准 RAG 在每次查询时都会从头重新发现知识。本技能则不同：

1. Wiki 层 — 大模型编写并维护持久化的 markdown 页面（摘要、实体页面、主题综述）。交叉引用已经存在。Wiki 会随每次摄取而更加丰富。
2. 图谱层 — 实体和关系只提取一次，并存储为可导航的知识图谱。BFS 遍历无需重新阅读来源即可回答结构性查询。
3. 原始来源层 — 原始文档以不可变方式存储，并附带分块。溯源链接将每个图谱节点和边都关联回支撑它的确切文本。

大模型负责编写；Python 工具负责所有簿记工作。

---

三个层

层	位置	大模型做什么	Python 做什么
原始来源	data/documents.json	读取（从不修改）	存储分块 + 元数据
Wiki	wiki/（markdown）	编写/更新页面	管理 index.md + log.md
图谱	data/graph.json	提取实体 + 关系	持久化、去重、遍历

---

⚡ Agent 快速开始

此工作流的完整可运行版本位于 scripts/template_agent_workflow.py — 复制并适配它。

from scripts.contextgraph import ContextGraphSkill
from scripts.tools import wiki_store

skill = ContextGraphSkill()

# ===== INGEST WITH FULL RAG + WIKI =====
# 1. Read references/ingestion.md and references/ontology.md first
# 2. Extract entities and relations (LLM reasoning step)
entities = [
    {"name": "memory leak",   "type": "issue",  "supporting_text": "memory leaks cause crashes"},
    {"name": "system crash",  "type": "issue",  "supporting_text": "system crashes due to memory leaks"},
]
relations = [
    {"source": "memory leak", "target": "system crash", "type": "causes",
     "confidence": 1.0, "supporting_text": "System crashes due to memory leaks."},
]

result = skill.ingest_with_content(
    doc_id="doc_001",
    title="System Crash Analysis",
    source="/docs/incident_report.pdf",
    raw_content="System crashes due to memory leaks. Memory leaks occur when objects are not released.",
    entities=entities,
    relations=relations,
)
# result = {"doc_id": "doc_001", "chunk_count": 1, "nodes_added": 2, "edges_added": 1}

# 3. Write a wiki summary page for this document
wiki_store.write_page(
    category="summary",
    title="System Crash Analysis Summary",
    content="""---
title: System Crash Analysis
source_document: doc_001
tags: [summary, incident]
---

# System Crash Analysis

**Source:** incident_report.pdf

## Key Claims

- [[memory-leak]] causes [[system-crash]] (confidence: 1.0)

## Entities

- [[memory-leak]] (issue)
- [[system-crash]] (issue)
""",
    summary="Incident report: memory leaks cause system crashes.",
)

# ===== QUERY WITH EVIDENCE =====
result = skill.query_with_evidence("Why does the system crash?")
# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}

# ===== WIKI SEARCH (read wiki before answering) =====
pages = wiki_store.search_wiki("memory leak")
# Returns: [{slug, category, path, snippet}, ...]

---

操作

摄取

当用户提供新文档时：

1. 阅读 references/ingestion.md — 实体/关系提取规则。
2. 阅读 references/ontology.md — 类型规范化规则。
3. 使用你的大模型推理提取实体和关系。
4. 调用 skill.ingest_with_content(...) — 存储原始内容 + 分块 + 图谱节点 + 溯源。
5. 编写 Wiki 摘要页面，使用 wiki_store.write_page(category="summary", ...)。
6. 更新实体页面 — 对于每个新增/更新的实体，编写或更新 wiki_store.write_page(category="entity", ...)。
7. 更新主题页面，如果文档涉及现有综述主题。
8. 单次文档摄取通常会触及 3–10 个 Wiki 页面。

查询

当用户提问时：

1. 先检查 Wiki — wiki_store.search_wiki(query) 查找相关页面。阅读它们。
2. 如果 Wiki 中有好的答案，则从 Wiki 页面综合答案（快速路径）。
3. 如果需要更深入的图谱遍历，调用 skill.query_with_evidence(query)。
4. 返回答案，并附上来自 supporting_documents 的证据引用。
5. 如果答案有价值，将其归档为新的 Wiki 主题页面。

Lint

定期对 Wiki 进行健康检查：

from scripts.tools import wiki_store
issues = wiki_store.lint_wiki()
# Returns: {orphan_pages, missing_pages, broken_wikilinks, isolated_pages}

让大模型审查并修复：断链、孤立页面、过时声明、缺失的交叉引用。完整 lint 工作流见 references/lint.md。

---

摄取约束

• ❌ 不要臆造文本中不存在的实体
• ❌ 不要添加没有明确文本证据的关系
• ❌ 不要添加置信度 < 0.6 的边
• ✅ 为每个实体和关系提供 supporting_text — 这启用了溯源
• ✅ 为每个摄取的文档编写一个 Wiki 摘要页面
• ✅ 当有新信息到达时更新现有实体页面
• ✅ 当新数据与旧声明冲突时，在 Wiki 页面中标记矛盾

---

检索约束

• 🔒 遍历深度不得超过 2（配置：MAX_GRAPH_DEPTH）
• 🔒 仅使用置信度 ≥ 0.6 的边（配置：MIN_CONFIDENCE）
• 🔒 最多返回 50 个节点（配置：MAX_NODES）
• ❌ 不要捏造图谱中不存在的节点或边

---

完整 Python API 参考

方法	用途	何时使用
skill.ingest_with_content(doc_id, title, source, raw_content, entities, relations)	完整 RAG 摄取：原始文档 + 图谱 + 溯源	每个新文档
skill.add_node(name, node_type)	添加单个实体（无溯源）	没有源文档时的快速添加
skill.add_edge(source_name, target_name, relation, confidence)	添加单个关系	没有源文档时的快速添加
skill.query(query)	仅图谱检索 → 子图	结构化查询
skill.query_with_evidence(query)	图谱 + 溯源 → 子图 + 源分块	需要引用的查询
wiki_store.write_page(category, title, content, summary)	写入/更新 wiki 页面	每次摄取后；回答查询后
wiki_store.read_page(category, title)	读取 wiki 页面	回答前；用于交叉引用
wiki_store.search_wiki(query)	跨 wiki 的关键词搜索	图谱遍历前的快速路径
wiki_store.list_pages(category)	列出所有 wiki 页面	获取概览
wiki_store.get_log(last_n)	读取最近的操作	了解 wiki 历史
wiki_store.lint_wiki()	健康检查	定期维护
documents_store.list_documents()	列出所有已摄取的原始来源	审计 / 溯源检查
documents_store.search_chunks(query)	分块级搜索	查找具体证据

---

设计哲学

"wiki 是一种持久、可累积的产物。交叉引用已经存在。综合已经反映了你读过的一切。" — Karpathy

层	发生什么	由谁负责
大模型推理	提取、综合、撰写 wiki 页面	Agent（.md 指导文件）
Wiki 持久化	索引、日志、文件 I/O	wiki_store.py
图谱持久化	去重、索引、BFS 遍历	graph_store.py、retrieval_engine.py
原始来源存储	不可变文档 + 分块 + 溯源	documents_store.py

人类负责策划来源并提问。大模型负责撰写 wiki、提取图谱，并带引用地回答。Python 负责所有簿记工作。