# Knowledge Org

组织与检索超越扁平文本块的知识时使用, , 涵盖 RAPTOR/GraphRAG 结构化索引选型、OpenViking 文件系统范式与 L0/L1/L2 按需加载、增量更新 PR...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill knowledge-org -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill knowledge-org -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill knowledge-org -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill knowledge-org -g -a gemini-cli -y`

## Description

组织与检索超越扁平文本块的知识时使用, , 涵盖 RAPTOR/GraphRAG 结构化索引选型、OpenViking 文件系统范式与 L0/L1/L2 按需加载、增量更新 PR 审核流与定期整理、Agentic RAG 与安全边界、上下文感知检索、结构化数据知识发现，以及双层记忆架构。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 知识的组织与检索

## 何时使用
- 扁平文本块检索不够：需要跨文档综合、多层次导航、多跳关系推理
- 设计结构化索引（RAPTOR 树 / GraphRAG 图 / 文件系统目录）
- 规划知识更新机制：事件触发的增量更新与周期触发的定期整理
- 把固定 RAG 管道升级为 Agentic RAG，或修补分块的上下文丢失
- 从结构化案例数据中提炼决策规则（从信息检索到知识发现）
- 组织海量用户对话历史（双层记忆架构）
- 设计知识的多用户共享、权限与租户隔离方案

## 核心原则
- 扁平块丢掉知识固有的层次与跨文档关联；面对技术手册、法律文书这类结构严谨的材料，只检索零散片段如同靠随机词条读小说。
- 未经提炼的知识无法被可靠利用。两个典型案例：黑猫白猫计数中，top-k 截断让模型只看到不完整样本（15 黑 3 白）就下结论；Xfinity 工单中，"最近邻偏置"（护士≈医生，答案随排序摇摆）、"边界语义缺失"（"仅限……其他一律不适用"不存在于任何单条工单）、"完整性信号缺失"（模型无从判断是否看全）三重障碍调大 k 也解决不了。结论：**必须在索引阶段投入计算**, , 把 100 个个体案例压成统计摘要，把几百条工单提炼成带边界的规则卡。
- 何时上结构化索引的判断标准：查询主要是"找到包含某信息的片段"（如"退款政策是什么"）→ 混合检索足够；经常需要**跨文档综合**（"SSE 和 AVX 在架构上的区别"）或**多层次导航**（从整体架构逐步深入到具体指令）才值得。代价是索引构建和查询都多花 LLM 调用，成本与延迟显著增加。
- RAPTOR vs GraphRAG 的选择：

  | 维度 | RAPTOR（树） | GraphRAG（图） |
  |------|------|------|
  | 结构 | 叶子聚类 + LLM 递归生成父节点摘要 | 实体-关系三元组 + 社区发现 |
  | 擅长查询 | "从概念逐步钻进细节"（跨层穿梭） | "A 和 B 之间是什么关系"（关系网漫游） |
  | 代表能力 | 多粒度检索（细节 ↔ 宏观） | 多跳遍历、实体消歧（原生图结构） |
  | 主要局限 | 高层摘要可能丢失细节 | 三元组语义降歧、提取错误污染知识 |

  生产场景组合使用优于单选。
- 知识图谱不是用户记忆的通用存储：三元组不可避免地**语义降级**（"如果下周还下雨就改去博物馆"的条件判断和时间依赖全丢），且提取错误会污染知识。推荐**分层互补**：完整自然语言保存核心信息（保语义完整）+ 结构化元数据负责索引检索（保效率）；仅在多跳推理和精确消歧的垂直场景（医疗问诊、法律案件、家族关系）将图谱作为专项索引。
- 把知识库当代码库管：每次知识变更是一个 PR。三层分离, , **原始证据层**（只增不改的对话/轨迹/原始文档）、**知识层**（可修订的 Markdown 或代码）、**服务层**（从特定已合入版本派生的检索索引）。索引是可重建的派生物，Git 里已审核的知识才是唯一来源；线上每条知识都要能回答"从哪条证据而来、谁在什么时候批准"。
- 更新必须双路径：**增量更新**吸收新证据（及时但只看到局部），**定期整理**从全局视角去重合并、回原始数据核查（防局部正确累积出全局混乱）。只做任一半都会烂掉。
- 上下文丢失在索引期补：为每个分块生成含核心背景的前缀再拼接索引, , 同时给 BM25 补可精确匹配的关键词、给稠密注入关键语义。这与运行期按当前任务裁剪历史的上下文压缩（做减法）完全不同。
- 扁平 vs 结构化的选择是成本换质量：混合检索已覆盖"找片段"类需求；结构化索引、上下文前缀、定期整理都是在**索引阶段预投入计算**，把提炼、抽象、关联的工作从查询期挪到离线期。

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/knowledge-org/SKILL.md