knowledge-pipline

Knowledge Pipeline — 多模态知识管道

将任意格式文档摄入为持久化结构化知识维基，支持知识融合、跨源矛盾检测、多源聚合查询。

核心能力

能力	说明
多模态摄入	PDF、图片、视频、Word、Excel、PPT、HTML、Markdown
知识融合	新文档摄入时自动与已有实体/概念页合并，而非覆盖
主动矛盾检测	摄入后自动对比新旧 claims，报告跨源冲突
跨源聚合查询	查询时展示多源视角、共识与分歧
知识图谱	自动构建交互式 vis.js 可视化图谱

---

斜杠命令

命令	说明
/pipeline-ingest <文件路径>	摄入文档到知识维基
/pipeline-query <问题>	多源聚合查询
/pipeline-lint	检查孤立页面、断链、矛盾
/pipeline-graph	构建交互式知识图谱
/pipeline-config	配置 LLM API

---

维基目录

数据统一存放在技能安装目录（SKILL_DIR）下。按优先级自动检测：

1. ~/.agents/skills/knowledge-pipline
2. ~/.claude/skills/knowledge-pipline

取第一个存在的目录作为 SKILL_DIR（Windows 上 ~ 展开为 C:\Users\{用户名}）。

SKILL_DIR/
├── SKILL.md              # 本文件
├── tools/                # Python 管道脚本
│   ├── pipeline_ingest.py
│   ├── pipeline_query.py
│   ├── pipeline_lint.py
│   ├── pipeline_graph.py
│   ├── pipeline_config.py
│   └── build_graph.py
├── core/                 # 核心模块
│   ├── llm_config.py     # LLM API 配置管理
│   ├── retrieval.py      # BM25 检索引擎
│   ├── wikilink.py       # Wikilink 解析器
│   └── export.py         # 导出功能
├── backend/              # 文件处理器
│   └── processors/       # PDF/图片/视频/Office 处理器
├── .claude/
│   └── commands/         # 斜杠命令定义
│       ├── pipeline-ingest.md
│       ├── pipeline-query.md
│       ├── pipeline-lint.md
│       ├── pipeline-graph.md
│       └── pipeline-config.md
├── wiki/                 # 知识维基（自动创建）
│   ├── index.md
│   ├── log.md
│   ├── overview.md
│   ├── claims.json
│   ├── sources/
│   ├── entities/
│   ├── concepts/
│   └── syntheses/
├── graph/                # 知识图谱输出
│   ├── graph.json
│   └── graph.html
└── raw/                  # 可选：源文档存放

---

LLM 配置（首次使用前必须完成）

运行任何管道命令前，先检查 .llm_config.json 是否存在。如果未配置，执行配置向导。

配置文件路径

按优先级查找：

1. 技能目录下的 .llm_config.json
2. 当前工作目录下的 .llm_config.json
3. LLM_CONFIG_JSON 环境变量指定的路径

配置向导

python tools/pipeline_config.py

或手动创建 .llm_config.json：

{
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4o-mini",
  "api_key": "sk-..."
}

常见提供商：

提供商	base_url	模型示例
OpenAI	https://api.openai.com/v1	gpt-4o-mini
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
火山引擎	https://ark.cn-beijing.volces.com/api/coding/v3	doubao-seed-2-0-pro-260215
Ollama	http://localhost:11434/v1	llama3.2

---

文件路径解析规则

当用户指定文件路径时：

1. 绝对路径（如 D:\docs\report.pdf）→ 直接使用
2. 以 raw/ 开头 → 相对于技能目录的 raw/
3. 其他相对路径 → 相对于当前工作目录（CWD）

---

命令：摄入文档

触发：用户说“摄入”、“ingest”、“导入文档”、“分析这个文件”等，或使用 /pipeline-ingest

用法

/pipeline-ingest raw/report.pdf
/pipeline-ingest D:\docs\meeting-notes.docx
摄入 ./my-image.jpg

执行方式

始终优先使用 Python 脚本：

python <skill-dir>/tools/pipeline_ingest.py <文件路径>

PDF 策略（通过环境变量控制）：

• PIPELINE_PDF_STRATEGY=balanced（默认）：文本 + 多图智能理解
• PIPELINE_PDF_STRATEGY=accurate：偏准确率（扫描件）
• PIPELINE_PDF_STRATEGY=fast：纯文本提取

图片处理：优先用 Claude 多模态视觉直接理解；失败时降级到 Python OCR

视频处理：OpenCV 关键帧提取 → 多模态 LLM 理解 → 音频转写（如有 ffmpeg）

知识融合（核心差异化能力）

摄入时，如果目标实体/概念页面已存在：

• 不会覆盖，而是用 LLM 合并新旧内容
• 保留已有信息，追加新源信息
• 矛盾处两者都保留，标注 ⚠️ 矛盾
• 自动更新 frontmatter 的 sources 列表

主动矛盾检测

摄入完成后自动执行：

• 将新 claims 与 claims.json 中所有已有 claims 对比
• 输出跨源矛盾报告和跨源佐证
• 自动记录到 wiki/log.md

完整流程

1. 处理源文件（多模态）
2. 读取 wiki/index.md 和 overview.md 获取上下文
3. 写入 wiki/sources/.md
4. 知识融合：合并或创建实体/概念页面
5. 更新 index.md 和 overview.md
6. 保存 key claims 到 claims.json
7. 主动矛盾检测：对比新旧 claims
8. 追加 log.md

如果 Python 脚本失败，回退到 Claude 内置能力手动执行上述步骤。

---

命令：查询维基

触发：用户提问关于已摄入内容的问题、“query”、“查询”等，或使用 /pipeline-query

用法

/pipeline-query transformer 模型的主要创新是什么？
/pipeline-query 所有来源中提到的安全风险
查询 "AI 对就业的影响"

执行方式

python <skill-dir>/tools/pipeline_query.py "问题内容"
python <skill-dir>/tools/pipeline_query.py "问题" --auto-save

跨源聚合（核心差异化能力）

查询结果包含：

• 多源视角：每个源对同一问题的不同观点
• 共识与分歧：
  • ✅ 多源共识：多个源一致同意的观点
  • ⚠️ 观点分歧：各源存在不同看法
  • ❓ 单源独有：仅在一个源中出现的论点
• [[wikilink]] 引用到具体页面

步骤

1. BM25 检索 + 关键词匹配找到相关页面
2. 加载 claims.json 构建跨源视角上下文
3. LLM 综合答案（含多源视角和共识分歧分析）
4. 询问用户是否保存到 wiki/syntheses/

---

命令：检查维基

触发：用户说“lint”、“检查”、“审计维基”等，或使用 /pipeline-lint

用法

/pipeline-lint
检查维基
lint

执行方式

python <skill-dir>/tools/pipeline_lint.py

检查项

• 孤立页面：无入链 [[wikilinks]]
• 断链：指向不存在页面的 [[WikiLink]]
• 矛盾：跨页面声明冲突（含 claims.json 交叉验证）
• 过时摘要：新源摄入后未更新的页面
• 缺失实体：3+ 页面提及但无专属页面的实体
• 数据空白：建议补充的新源

输出报告后询问是否保存到 wiki/lint-report.md。

---

命令：构建知识图谱

触发：用户说“build graph”、“构建图谱”、“知识图谱”等，或使用 /pipeline-graph

用法

/pipeline-graph
构建知识图谱
build graph

执行方式

python <skill-dir>/tools/build_graph.py --open

输出

• graph/graph.json：节点 + 边 + 社区数据
• graph/graph.html：自包含 vis.js 交互式可视化

备选方案

如果 Python 不可用，手动：

1. Grep 提取所有 [[wikilinks]]
2. 构建节点/边列表
3. 生成 graph.json + graph.html

---

命令：配置 LLM

触发：用户说"配置"、"config"、"设置 API"等，或使用 /pipeline-config

执行方式

python <skill-dir>/tools/pipeline_config.py

或通过交互式问答收集 base_url、model、api_key 后写入 .llm_config.json。

---

页面格式

每个维基页面使用 YAML frontmatter：

---
title: "页面标题"
type: source | entity | concept | synthesis
tags: []
sources: []
last_updated: YYYY-MM-DD
---

使用 [[PageName]] wikilinks 链接其他页面。

命名规范

• Source slug: kebab-case.md
• Entity 页面: TitleCase.md（如 OpenAI.md、华为云.md）
• Concept 页面: TitleCase.md（如 RAG.md、知识融合.md）

---

设计理念

持久化知识积累 vs RAG 查询时推导：

特性	传统 RAG	Knowledge Pipeline
知识存储	向量数据库（无结构）	结构化维基页面
新文档摄入	追加嵌入	知识融合（合并已有页面）
矛盾处理	无感知	主动检测并报告
查询	相似性检索	多源聚合 + 共识分歧分析
可解释性	黑盒	Wikilinks + 引用溯源
可视化	无	交互式知识图谱