BZJZ_Material/知识库Agent构建.md

# 知识库 Agent 构建方案：LLM Wiki + 文本图片多模态知识库

问题开始时间：2026-06-11-03-26-41

资料来源：
- Karpathy gist：<https://gist.githubusercontent.com/karpathy/442a6bf555914893e9891c11519de94f/raw/ac46de1ad27f92b28ac95459c782c07f6b8c964a/llm-wiki.md>
- 本地下载：`文档润色流和知识库构建流/llm-wiki.md`
- Gist 文件 SHA256：`dc3efe98ae62f23dd08acad13aba2e95287beb20b6bec2f4af0423557fe37401`
- 参考插件：`文档润色流和知识库构建流/claude-scholar` 中 Obsidian KB、source ingestion、literature workflow、zotero-obsidian-bridge 相关说明

## 1. 核心思想

Karpathy 的 `LLM Wiki` 不是传统 RAG。传统 RAG 在每次提问时从原始资料中重新检索片段；`LLM Wiki` 则让 LLM 维护一个持久 Markdown Wiki，作为原始资料和问答之间的中间知识层。

```text
Raw Sources -> LLM Maintained Wiki -> Query / Writing / Analysis
```

关键区别：
- 原始资料只读，是 source of truth；
- Wiki 是 LLM 维护的结构化知识层；
- 新资料入库时，不只是建立索引，还要更新主题页、实体页、证据页、矛盾记录和索引；
- 高价值问答也可以写回 Wiki，避免只留在聊天记录里；
- 交叉引用、旧结论修正、缺口记录会随资料积累持续增长。

对本项目而言，目标是构建“文档润色与项目资料知识库”，支撑模板、参考文档、论文、图片、实验材料、写作草稿、证据台账和最终交付文本。

## 2. 三层架构

### 2.1 Raw Sources：原始资料层

原则：只读、可追溯、尽量保留原貌。

建议目录：

```text
知识库/
  raw/
    papers/
    proposals/
    templates/
    docs/
    web/
    images/
    data/
```

可放入：
- PDF 论文、技术报告、政策文件；
- Word、Markdown、PPT、Excel 等项目资料；
- 获批标书、模板、参考案例；
- 网页剪藏的 Markdown；
- PDF 转换出的图片、表格截图、机制图、流程图；
- 原始实验数据或结果图。

Raw 层不由 Agent 修改。Agent 可以读取、转换、引用，但不直接改写原件。

### 2.2 Wiki：LLM 维护层

原则：LLM 可编辑，人主要审查和阅读。

推荐结构：

```text
知识库/
  wiki/
    index.md
    log.md
    00-项目总览.md
    01-写作任务板.md
    Sources/
      Papers/
      Web/
      Docs/
      Data/
      Images/
      Notes/
    Knowledge/
      主题综述.md
      方法分类.md
      证据台账.md
      术语表.md
      矛盾与缺口.md
    Writing/
      立项依据.md
      研究内容.md
      技术路线.md
      创新点.md
      研究基础.md
    Maps/
      literature.canvas
      mechanism.canvas
    Daily/
    Archive/
    _system/
      registry.md
      schema.md
      lint-report.md
```

### 2.3 Schema：Agent 规则层

Schema 可以写在 `AGENTS.md`、`CLAUDE.md`、`_system/schema.md` 或项目规则文件中。它告诉 Agent 如何维护 Wiki。

最小规则：
- Raw Sources 不可修改；
- 新资料必须先进入 `Sources/*`；
- 稳定论断才能进入 `Knowledge/*`；
- 进入 `Writing/*` 的论断必须能追溯到 Evidence Record；
- 图片必须本地化，并建立图片 source note；
- 每次 ingestion 后更新 `index.md`；
- 每次重要操作后向 `log.md` 追加记录；
- `log.md` 只追加，不重写历史。

## 3. 与 claude-scholar Obsidian KB 的对应关系

`claude-scholar` 的 Obsidian KB 已经提供一套可落地的项目知识库结构：

```text
Research/{project-slug}/
  00-Hub.md
  01-Plan.md
  02-Index.md
  Sources/
    Papers/
    Web/
    Docs/
    Data/
    Interviews/
    Notes/
  Knowledge/
  Experiments/
  Results/
    Reports/
  Writing/
  Daily/
  Maps/
  Archive/
  _system/
```

对应关系：
- `00-Hub.md`：项目入口和当前状态；
- `01-Plan.md`：任务计划、里程碑、下一步；
- `02-Index.md`：人类可读的导航索引；
- `Sources/*`：原始资料的结构化 source notes；
- `Knowledge/*`：经过证据门槛的稳定知识；
- `Writing/*`：可进入标书、论文、报告的写作资产；
- `Maps/literature.canvas`：默认文献图谱；
- `_system/registry.md`：可见注册表；
- `.claude/project-memory/*`：仓库本地绑定信息，不是主要知识内容。

## 4. 多模态资料处理：文本 + 图片

### 4.1 文本处理流程

文本来源：
- PDF 转 Markdown；
- 网页剪藏；
- Zotero PDF 全文；
- DOCX/Word 标书；
- PPT、会议记录、实验记录；
- 表格和数据说明文档。

处理流程：

```text
读取原文
  -> 建 Source Note
  -> 抽 Evidence Record
  -> 更新 Knowledge 页面
  -> 更新 Writing 草稿或待写清单
  -> 更新 index.md 和 log.md
```

Source Note 模板：

```markdown
# 资料标题

Source:
Source type: full paper | proposal | template | webpage | project note | dataset
Path:
Date ingested:

## Summary

## Key Evidence

## Relevance to Current Project

## Limitations

## Evidence Records

## Links
```

Evidence Record 模板：

```markdown
## Evidence Record

Evidence ID:
Source:
Source type:
Supports:
Contradicts:
Method / dataset / metric:
Limitation:
Project relevance:
Claim strength: speculative | observed | supported | strong
Allowed wording:
Forbidden stronger wording:
```

Claim strength 建议：
- `speculative`：想法、假设、间接启发；
- `observed`：单一资料或初步结果观察到；
- `supported`：有可靠文献、实验或数据支持；
- `strong`：多来源一致、方法可靠、可用于核心论断。

### 4.2 图片处理流程

Karpathy gist 特别提醒：图片应下载到本地。LLM 不能一次性可靠读取 Markdown 中的内嵌图片，较好的方式是先读文本，再逐张查看关键图片。

图片来源：
- PDF 转 Markdown 生成的 `images/*.jpg` 或 `*.png`；
- 论文中的 figure；
- 标书模板截图；
- 机制图、技术路线图；
- 实验结果图；
- 表格截图或流程图。

图片入库流程：

```text
图片本地化
  -> 建 Image Source Note
  -> OCR 或人工描述
  -> 提取坐标轴、图例、分组、箭头、节点
  -> 记录可支持的论断
  -> 链接到 Knowledge / Writing / Maps
```

Image Source Note 模板：

```markdown
# Image: 简短标题

Image path:
Source document:
Original page / figure:
Date ingested:

## Visual Description

## Extracted Labels / OCR

## What This Image Supports

## Limitations

## Reuse Plan
- 可用于：立项依据 | 研究基础 | 技术路线 | 机制模式图 | 结果展示
- 是否需要重绘：

## Links
```

图片调用口令：

```text
请先读取这份 Markdown 的图片引用列表，再逐一查看关键图片，提取图题、坐标轴、图例、分组、结论和可迁移证据。
```

```text
请为这张机制图建立图片笔记：描述节点、箭头方向、证据含义、可支持的机制假说，以及需要重绘或替换的地方。
```

## 5. 核心操作

### 5.1 Ingest：新增资料入库

单篇资料入库：

```text
1. 读取 raw/source。
2. 判断 source type。
3. 在 Sources/* 下生成 source note。
4. 抽取 Evidence Records。
5. 检查会影响哪些 Knowledge 页面。
6. 如图片重要，建立 Images source note。
7. 更新 02-Index.md 或 index.md。
8. 向 log.md 追加记录。
```

调用方式：

```text
/kb-ingest path/to/source.pdf
```

或自然语言：

```text
请将 raw/papers/xxx.pdf 转换后的 Markdown 入库：先写 Sources/Papers 笔记，再抽 Evidence Record，最后只把证据足够的内容提升到 Knowledge。
```

### 5.2 Query：基于 Wiki 回答

回答问题时，优先读取 Wiki，而不是直接盲搜所有原始文件：

```text
读 index.md / 02-Index.md
  -> 找相关 Knowledge / Source 页
  -> 必要时回看 raw source
  -> 输出带证据链答案
```

调用方式：

```text
请基于当前 Wiki 回答：某个机制链条有哪些证据、哪些只是迁移假说、哪些需要继续检索？
```

### 5.3 File Back：把高价值问答写回 Wiki

有价值的分析不应只留在聊天里：

```text
问答结果
  -> 新建或更新 Knowledge / Writing 页面
  -> 更新 index.md
  -> 追加 log.md
```

调用方式：

```text
请把刚才关于“主题 A 与机制 B”的回答整理成 Knowledge/A-B-Mechanism.md，并把不确定论断标成 speculative。
```

### 5.4 Promote：把稳定内容提升到知识或写作

来源笔记不能直接等同于知识结论。提升条件：
- 有 Evidence Record；
- 来源类型足够强；
- claim strength 与措辞匹配；
- 有 allowed wording 和 forbidden stronger wording；
- 能链接回 source note。

调用方式：

```text
/kb-promote
```

或：

```text
请把 Daily 和 Sources 中已经稳定的内容提升到 Knowledge；没有证据记录的内容只保留为待核查。
```

### 5.5 Lint：健康检查

周期性检查：
- 断链；
- 孤立页面；
- 重复主题页；
- 新资料与旧结论矛盾；
- `Writing` 中是否存在无 Evidence Record 的论断；
- 图片路径是否失效；
- canvas 是否有效；
- index 是否覆盖关键页面。

调用方式：

```text
/kb-lint
/kb-links
/kb-sync
```

## 6. Agent 分工建议

| Agent / Skill | 角色 | 输入 | 输出 |
|---|---|---|---|
| `obsidian-source-ingestion` | Source 入库 | PDF、网页、DOCX、图片、数据 | `Sources/*` 笔记、registry、index、daily |
| `zotero-obsidian-bridge` | 文献桥接 | Zotero collection | `Sources/Papers`、Evidence Records、Knowledge/Writing 初稿 |
| `obsidian-literature-workflow` | 文献综合 | `Sources/Papers` | `Knowledge/Literature Overview.md`、`Research Gaps.md`、`Maps/literature.canvas` |
| `obsidian-project-kb-core` | KB 主控 | 项目目录和 vault | scaffold、hub、plan、index、registry、lifecycle |
| `obsidian-kb-artifacts` | Obsidian 原生产物 | Markdown、wikilink、canvas | 链接修复、canvas、registry table、lint report |
| `citation-verification` | 引用核验 | 参考文献、DOI、arXiv、Zotero 条目 | 真实元数据、claim-citation 对齐检查 |
| `paper-self-review` | 写作自审 | 草稿、图表、证据记录 | Claim Audit、结构问题、过强论断 |
| `writing-anti-ai` | 语言润色 | 中文或英文段落 | 更自然、少 AI 痕迹的表述 |

## 7. 多模态知识库的调用方法

### 7.1 初始化

```text
/kb-init 项目名 /absolute/path/to/obsidian-vault
```

如果不用 Obsidian，也可以在项目内创建普通 Markdown wiki：

```text
请在当前项目下创建 知识库/wiki 结构，包含 index.md、log.md、Sources、Knowledge、Writing、Maps、_system。
```

### 7.2 文本资料入库

```text
/kb-ingest path/to/file.md
/kb-ingest path/to/file.pdf
/kb-ingest https://example.com/article
```

如果是网页资料，可先使用 Obsidian Web Clipper 或 `defuddle` 生成干净 Markdown。

### 7.3 图片资料入库

```text
请扫描 raw/images 中的新图片，为每张关键图片创建 Image Source Note；提取图中标签、箭头关系、坐标轴、可支持论断和复用计划。
```

### 7.4 文献综合

```text
/kb-literature-review
```

要求：
- synthesis 必须链接到 `Sources/Papers`；
- abstract-only 和 webpage-placeholder 只能进入 coverage 或 To-Read；
- `Writing/related-work-draft.md` 必须通过 evidence gate。

### 7.5 写作输出

```text
请基于 Knowledge 和 Evidence Records 起草 Writing/立项依据.md。每个关键论断都要标注证据来源；证据不足处用“拟探索/提示/可能”。
```

## 8. index.md 与 log.md 规范

`index.md` 面向内容导航：

```markdown
# Index

## Sources
- [[Sources/Papers/xxx]] - 一句话说明

## Knowledge
- [[Knowledge/主题综述]] - 当前稳定结论

## Writing
- [[Writing/立项依据]] - 当前草稿状态
```

`log.md` 面向时间线：

```markdown
## [2026-06-11] ingest | source-title
- Source:
- Pages updated:
- Evidence records:
- Open questions:
```

建议使用一致前缀，便于命令行检索：

```bash
grep "^## \\[" log.md | tail -5
```

## 9. 可选工具

- Obsidian Graph View：观察知识图谱、孤立页、中心页；
- Obsidian Web Clipper：网页转 Markdown；
- Obsidian attachment folder：固定图片附件目录，例如 `raw/assets/`；
- Dataview：基于 YAML frontmatter 生成动态列表；
- Marp：从 Markdown 生成 slides；
- `qmd`：本地 Markdown 混合检索，适合 Wiki 较大后使用；
- Git：给 Wiki 提供版本历史、回滚和协作能力。

## 10. 推荐落地流程

```text
第 1 步：初始化 wiki / Obsidian KB
第 2 步：把模板、参考文档、论文、图片放入 raw
第 3 步：逐个 /kb-ingest，不批量盲灌
第 4 步：为文本和图片建立 Source Notes
第 5 步：抽 Evidence Records
第 6 步：提升稳定论断到 Knowledge
第 7 步：把可写内容汇总到 Writing
第 8 步：周期性 /kb-lint、/kb-links、/kb-sync
第 9 步：把高价值问答写回 Wiki
第 10 步：用 Git 备份整个知识库
```

## 11. 文本 + 图片知识库的质量底线

- 不从图片外链直接建立长期知识，先本地化；
- 不把摘要页、网页占位页当成强证据；
- 不把图中趋势写成统计显著，除非原文或数据支持；
- 不把机制图当成实验证据，机制图通常只支持“作者假说/模型示意”；
- 不把模板写法等同于事实内容；
- `Writing` 中每个强论断都要能回链到 Evidence Record；
- `log.md` 保留入库和修改时间线；
- 用 Git 管理 Wiki，避免长期知识被无痕覆盖。