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
}
]增量更新索引
项目持续开发时,不需要每次重新建立完整索引。智能体可以比较文件修改时间或内容哈希,只处理发生变化的文件。
典型流程如下:
- 首次运行时创建完整索引
- 后续扫描时比较文件状态
- 发现新增文件则加入索引
- 发现修改文件则更新记录
- 发现删除文件则移除记录
这种机制让大型代码项目的分析成本保持稳定。
文件索引的边界
文件索引适合解决定位和变化检测问题,但不能替代代码理解。路径和元数据告诉智能体“有什么”,源码分析才能回答“为什么”。
因此实际系统通常会把文件索引、代码切片和语义检索结合使用。
本课总结
- 文件索引为智能体提供稳定的项目状态视图。
- 元数据和哈希信息可以支持增量更新。
- 索引负责定位,代码分析负责理解,两者需要结合。
下一课预告
下一课将介绍如何基于文件索引进一步构建代码检索能力,让智能体能够根据任务快速找到相关实现。
按自己的节奏,确认真正理解。