【智能体开发】如何更新知识库而不重复处理全部文档：用内容哈希识别新增、修改与删除

如何更新知识库而不重复处理全部文档：用内容哈希识别新增、修改与删除

具体问题与完成目标

假设你维护一个本地 Markdown 知识库，里面有几十篇课程笔记。每次修改一两篇笔记后，如果重新为所有文件生成嵌入向量并写入向量数据库，会浪费大量时间。更糟的是，如果你直接追加新向量而不清理旧版本，检索时可能同时命中同一篇笔记的旧内容和新内容，答案会自相矛盾。

本文解决的就是这个问题：只处理内容真正发生变化的文件，跳过未改动文件，并正确清理被修改或删除文件的旧索引。

完成本文后，你将得到一个可运行的 Python 脚本，它使用内容哈希（content hash）比较当前文件与上一次索引时的状态，输出“新增、修改、删除、未变”四类文件清单，并只对需要处理的文件执行操作。你还会拿到一套可复现的验收测试，验证正常、边界和失败三种场景。

适用环境：Python 3.11 及以上，标准库 hashlib 和 sqlite3，无需外部服务。示例在 Linux/macOS 终端（bash）中执行，Windows 用户可用等效命令。

前置条件与案例输入

你需要准备一个隔离目录，里面放几篇虚构的课程笔记。不需要真实数据库或 API 密钥。

文件清单

虚构笔记内容（在 kb_root/ 下创建）

note_alpha.md：

# 课程 A：Python 基础

变量赋值是 Python 中最基本的操作。
变量名区分大小写。

note_beta.md：

# 课程 B：列表与字典

列表用方括号定义，元素有序。
字典用花括号定义，以键值对存储。

note_gamma.md：

# 课程 C：函数

用 def 关键字定义函数。
return 语句返回结果。

这些是故意简短的演示数据，目的是让哈希值便于人工复核。真实场景中每篇笔记可能长得多，但检测机制不变。

必要原理：为什么用内容哈希而不是修改时间

文件系统提供的修改时间（mtime）看起来是天然的变更信号，但它有三个问题。第一，复制、同步、解压归档都可能改变 mtime 而不改变内容；第二，某些工具在编辑后可能保留原始时间戳；第三，你无法仅从 mtime 判断“修改后是否恢复原样”。

内容哈希（content hash）是对文件字节内容计算出的固定长度指纹。内容相同，哈希一定相同；内容有任何差异，哈希几乎必然不同。Python 标准库 hashlib 提供了 BLAKE2b、SHA-256 等算法。本文使用 sha256，因为它足够快且输出可读性好。

检测逻辑很直接：

• 当前文件路径不在状态库中 → 新增
• 当前文件路径在状态库中，但哈希不同 → 修改
• 当前文件路径在状态库中且哈希相同 → 未变
• 状态库中有路径但当前磁盘不存在 → 删除

把状态存在 SQLite 中而不是 JSON 文件里，是因为 SQLite 天然支持按路径精确查询和原子更新。Python 的 sqlite3 模块是标准库的一部分，无需额外安装。

#mermaid-svg-GyEe4kw5tb7gfMHJ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-GyEe4kw5tb7gfMHJ .error-icon{fill:#552222;}#mermaid-svg-GyEe4kw5tb7gfMHJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-GyEe4kw5tb7gfMHJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .marker.cross{stroke:#333333;}#mermaid-svg-GyEe4kw5tb7gfMHJ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-GyEe4kw5tb7gfMHJ p{margin:0;}#mermaid-svg-GyEe4kw5tb7gfMHJ .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster-label text{fill:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster-label span{color:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster-label span p{background-color:transparent;}#mermaid-svg-GyEe4kw5tb7gfMHJ .label text,#mermaid-svg-GyEe4kw5tb7gfMHJ span{fill:#333;color:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .node rect,#mermaid-svg-GyEe4kw5tb7gfMHJ .node circle,#mermaid-svg-GyEe4kw5tb7gfMHJ .node ellipse,#mermaid-svg-GyEe4kw5tb7gfMHJ .node polygon,#mermaid-svg-GyEe4kw5tb7gfMHJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .rough-node .label text,#mermaid-svg-GyEe4kw5tb7gfMHJ .node .label text,#mermaid-svg-GyEe4kw5tb7gfMHJ .image-shape .label,#mermaid-svg-GyEe4kw5tb7gfMHJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-GyEe4kw5tb7gfMHJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .rough-node .label,#mermaid-svg-GyEe4kw5tb7gfMHJ .node .label,#mermaid-svg-GyEe4kw5tb7gfMHJ .image-shape .label,#mermaid-svg-GyEe4kw5tb7gfMHJ .icon-shape .label{text-align:center;}#mermaid-svg-GyEe4kw5tb7gfMHJ .node.clickable{cursor:pointer;}#mermaid-svg-GyEe4kw5tb7gfMHJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .arrowheadPath{fill:#333333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GyEe4kw5tb7gfMHJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-GyEe4kw5tb7gfMHJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GyEe4kw5tb7gfMHJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster text{fill:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ .cluster span{color:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-GyEe4kw5tb7gfMHJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-GyEe4kw5tb7gfMHJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-GyEe4kw5tb7gfMHJ .icon-shape,#mermaid-svg-GyEe4kw5tb7gfMHJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GyEe4kw5tb7gfMHJ .icon-shape p,#mermaid-svg-GyEe4kw5tb7gfMHJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-GyEe4kw5tb7gfMHJ .icon-shape .label rect,#mermaid-svg-GyEe4kw5tb7gfMHJ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GyEe4kw5tb7gfMHJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-GyEe4kw5tb7gfMHJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-GyEe4kw5tb7gfMHJ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

路径不存在

哈希不同

哈希相同

状态库有但磁盘无

扫描 kb_root 下所有 .md 文件

计算每个文件的 SHA-256

与状态库比对

标记为新增

标记为修改

标记为未变

标记为删除

输出变更集

图中关键关系：变更检测以“路径”为比对单位，而不是以内容为比对单位。同一内容出现在两个不同路径，会被视为两个独立文件分别处理——这避免了哈希碰撞导致的内容覆盖问题。

完整实现

文件 1：incremental_index.py

#!/usr/bin/env python3
"""检测知识库中文件的变更集：新增、修改、删除、未变。"""

import hashlib
import sqlite3
from pathlib import Path

def compute_file_hash(file_path: Path) –> str:
"""计算文件的 SHA-256 十六进制摘要，基于原始字节。"""
h = hashlib.sha256()
with open(file_path, "rb") as f:
for chunk in iter(lambda: f.read(65536), b""):
h.update(chunk)
return h.hexdigest()

def init_db(db_path: Path) –> sqlite3.Connection:
"""创建或打开状态数据库，确保 file_state 表存在。"""
conn = sqlite3.connect(db_path)
conn.execute("""
CREATE TABLE IF NOT EXISTS file_state (
path TEXT PRIMARY KEY,
content_hash TEXT NOT NULL
)
""")
conn.commit()
return conn

def load_stored_hashes(conn: sqlite3.Connection) –> dict[str, str]:
"""读取状态库中所有已记录的 path -> hash 映射。"""
cursor = conn.execute("SELECT path, content_hash FROM file_state")
return {row[0]: row[1] for row in cursor.fetchall()}

def scan_markdown_files(kb_root: Path) –> dict[str, str]:
"""扫描知识库目录下所有 .md 文件，返回相对路径 -> 当前哈希。"""
current = {}
for file_path in sorted(kb_root.rglob("*.md")):
rel = file_path.relative_to(kb_root).as_posix()
current[rel] = compute_file_hash(file_path)
return current

def detect_changes(
kb_root: Path, conn: sqlite3.Connection
) –> dict[str, list[str]]:
"""比对磁盘状态与数据库状态，返回四类变更路径列表。"""
stored = load_stored_hashes(conn)
current = scan_markdown_files(kb_root)

added = []
modified = []
unchanged = []

for path, current_hash in current.items():
if path not in stored:
added.append(path)
elif stored[path] != current_hash:
modified.append(path)
else:
unchanged.append(path)

deleted = [p for p in stored if p not in current]

return {
"added": sorted(added),
"modified": sorted(modified),
"deleted": sorted(deleted),
"unchanged": sorted(unchanged),
}

def update_state(
conn: sqlite3.Connection, kb_root: Path, changes: dict[str, list[str]]
) –> None:
"""将变更写入状态库：删除已删文件，更新新增和修改文件的哈希。"""
for path in changes["deleted"]:
conn.execute("DELETE FROM file_state WHERE path = ?", (path,))

for path in changes["added"] + changes["modified"]:
full_path = kb_root / path
new_hash = compute_file_hash(full_path)
conn.execute(
"""
INSERT INTO file_state (path, content_hash)
VALUES (?, ?)
ON CONFLICT(path) DO UPDATE SET content_hash = excluded.content_hash
""",
(path, new_hash),
)

conn.commit()

def main():
kb_root = Path("kb_root")
db_path = Path("index_state.db")

if not kb_root.is_dir():
print(f"错误：知识库目录 {kb_root} 不存在。")
return

conn = init_db(db_path)
changes = detect_changes(kb_root, conn)

print("=== 变更检测结果 ===")
for category in ["added", "modified", "deleted", "unchanged"]:
items = changes[category]
print(f"\\n{category} ({len(items)}):")
for item in items:
print(f" – {item}")

# 只对需要处理的文件执行“索引操作”占位
to_process = changes["added"] + changes["modified"]
if to_process:
print(f"\\n>>> 需要对 {len(to_process)} 个文件重新处理并生成嵌入。")
else:
print("\\n>>> 无需处理任何文件。")

# 如果你在真实系统中，这里应该：
# 1. 删除 changes["deleted"] + changes["modified"] 对应的旧向量
# 2. 为 changes["added"] + changes["modified"] 生成新向量
# 3. 调用 update_state 持久化状态

update_state(conn, kb_root, changes)
conn.close()
print("\\n状态库已更新。")

if __name__ == "__main__":
main()

运行方式

在终端中，进入包含 incremental_index.py 和 kb_root/ 的目录，执行：

python incremental_index.py

首次运行预期输出（状态库为空，所有文件视为新增）：

=== 变更检测结果 ===

added (3):
– note_alpha.md
– note_beta.md
– note_gamma.md

modified (0):

deleted (0):

unchanged (0):

>>> 需要对 3 个文件重新处理并生成嵌入。

状态库已更新。

状态库中现在记录了三个文件的路径和哈希。再次运行同一命令，预期输出：

=== 变更检测结果 ===

added (0):

modified (0):

deleted (0):

unchanged (3):
– note_alpha.md
– note_beta.md
– note_gamma.md

>>> 无需处理任何文件。

状态库已更新。

这就是核心价值：未改动的文件被完全跳过，不会触发任何解析或嵌入操作。

验收与测试

以下三个场景覆盖正常、边界和失败情况。每个场景都可以在隔离目录中独立复现。

场景 1：正常场景——修改一个文件

操作：编辑 kb_root/note_beta.md，在文件末尾添加一行 元组用圆括号定义。，然后运行脚本。

预期结果：modified 列表包含 note_beta.md，unchanged 包含另外两个文件，added 和 deleted 为空。

判定方法：输出中 modified 的数量为 1，且路径正确。脚本执行后再次运行，note_beta.md 应归入 unchanged。

场景 2：边界场景——内容相同但路径不同

操作：复制 note_alpha.md 为 note_alpha_copy.md，保持内容完全一致。运行脚本。

预期结果：added 包含 note_alpha_copy.md，而 note_alpha.md 仍在 unchanged 中。两个文件拥有相同的哈希值，但被独立追踪。

判定方法：检查 added 列表长度为 1，路径为 note_alpha_copy.md。这验证了“按路径追踪”的设计。

场景 3：失败场景——文件在检测后被删除

操作：先正常运行脚本使状态库稳定，然后删除 kb_root/note_gamma.md，再运行脚本。

预期结果：deleted 包含 note_gamma.md，unchanged 包含剩余文件，added 和 modified 为空。

判定方法：输出中 deleted 长度 1，路径正确。脚本不应抛出异常，且状态库中该路径的记录被清除。

失败场景补充：知识库目录不存在

如果 kb_root 被误删或路径错误，脚本输出“错误：知识库目录 kb_root 不存在。”并退出。这防止了在错误目录上执行全量“新增”导致误索引。

常见故障的定位方法

问题：修改文件后哈希没变。 检查你是否在编辑器里保存了文件。某些编辑器（如部分 Markdown 预览器）不会自动写入磁盘。用 cat 或 head 确认文件内容实际已变。

问题：删除文件后 deleted 为空。 确认你删除的是 kb_root 目录下的 .md 文件，而不是状态库或其他位置的文件。rglob("*.md") 只扫描 Markdown 文件，不扫描其他扩展名。

问题：两个内容不同的文件哈希相同。 这在 SHA-256 下概率极低，正常场景不会发生。如果你真的遇到了，记录两个文件的完整内容并改用 hashlib.blake2b 重新验证。

适用边界：本文的实现只检测“内容是否变化”，不检测文件权限、所有者或扩展属性。如果你的知识库依赖这些元数据做访问控制，需要单独扩展状态表。另外，脚本假设文件是 UTF-8 文本；二进制文件（如图片）也能被哈希，但“修改后重新生成嵌入”那一步需要另行设计。

验证状态

限制说明：上述代码在编写时通过了语法编译检查，三个验收场景的预期输出是根据检测逻辑推导的，未在终端中实际运行。读者可按文中步骤自行执行验证。哈希算法的行为由 Python 标准库保证，跨平台一致。

参考资料