AI Agent / 系统课时

建立文件索引

建立文件索引

本篇解决智能体如何长期管理项目文件信息的问题。通过建立文件索引,智能体可以记录路径、类型、大小、修改时间和文本内容摘要,在项目变化后快速定位需要重新分析的部分。

学习目标

  • 理解文件索引在代码智能体中的作用
  • 掌握设计基础文件元数据结构的方法
  • 能够实现简单的文件索引生成流程

文件索引解决什么问题

如果每次分析项目都重新遍历全部文件,会造成大量重复工作。文件索引把项目状态转换为结构化数据,使智能体可以快速回答“文件在哪里”“什么时候变化”“是否需要重新读取”等问题。

一个基础索引通常包含文件路径、扩展名、大小、更新时间以及可选的文本摘要。

设计文件索引结构

文件索引不是文件内容复制,而是文件状态记录。常见字段包括:

字段 作用
path 文件位置
type 文件类型
size 文件大小
modifiedTime 修改时间
hash 内容变化检测

例如,一个索引记录可以表示为:

json
{
  "path": "src/main.py",
  "type": "python",
  "size": 2048,
  "modifiedTime": "<TIME>",
  "hash": "<ID>"
}

预期结果

text
索引记录成功保存,可用于后续增量扫描。

生成基础文件索引

智能体可以通过扫描文件系统生成初始索引。

python
from pathlib import Path
import json

root = Path("<PATH>")
index = []

for file in root.rglob("*"):
    if file.is_file():
        index.append({
            "path": str(file),
            "type": file.suffix,
            "size": file.stat().st_size
        })

print(json.dumps(index, indent=2))

预期输出

json
[
  {
    "path": "<PATH>/src/main.py",
    "type": ".py",
    "size": 2048
  }
]

增量更新索引

项目持续开发时,不需要每次重新建立完整索引。智能体可以比较文件修改时间或内容哈希,只处理发生变化的文件。

典型流程如下:

  • 首次运行时创建完整索引
  • 后续扫描时比较文件状态
  • 发现新增文件则加入索引
  • 发现修改文件则更新记录
  • 发现删除文件则移除记录

这种机制让大型代码项目的分析成本保持稳定。

文件索引的边界

文件索引适合解决定位和变化检测问题,但不能替代代码理解。路径和元数据告诉智能体“有什么”,源码分析才能回答“为什么”。

因此实际系统通常会把文件索引、代码切片和语义检索结合使用。

本课总结

  • 文件索引为智能体提供稳定的项目状态视图。
  • 元数据和哈希信息可以支持增量更新。
  • 索引负责定位,代码分析负责理解,两者需要结合。

下一课预告

下一课将介绍如何基于文件索引进一步构建代码检索能力,让智能体能够根据任务快速找到相关实现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立文件索引

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通