code-index-agent

它的目标不是把整个仓库塞给模型，也不是只做关键词搜索，而是提前把代码库整理成 Agent 可查询的上下文入口：

• 哪些文件是源码、测试、配置、文档、依赖声明
• 哪些文件里有类、函数、结构体、导出符号
• 哪些文件可能和当前任务最相关
• Agent 下一步应该优先读哪些文件

使用

在任意代码仓库目录执行：

D:\uvenv\Scripts\python.exe C:\Users\you\code-context-index\code_index.py build .

生成：

.code-index/index.json
.code-index/CONTEXT.md

查询任务相关入口：

D:\uvenv\Scripts\python.exe C:\Users\you\code-context-index\code_index.py query . "登录接口报错"
D:\uvenv\Scripts\python.exe C:\Users\you\code-context-index\code_index.py query . "user auth test config"

也可以指定结果数量：

D:\uvenv\Scripts\python.exe C:\Users\you\code-context-index\code_index.py query . "payment webhook" --limit 10

如果你的系统 PATH 已经配置了 Python，也可以把命令开头替换成 python。

工作流

1. build 扫描仓库，跳过 .git、node_modules、target、dist 等大型产物目录。
2. 对常见语言文件抽取符号、导入、测试线索和文件角色。
3. 写入结构化索引和一份给人/Agent 快速阅读的 CONTEXT.md。
4. query 根据任务文本匹配路径、符号、导入、文件摘要和测试线索，返回建议优先阅读的上下文。

项目边界

这个版本刻意只用 Python 标准库，便于复制和改造。它不是语义向量检索系统，但已经具备代码索引工程的基本形态。后续可以加入：

• Tree-sitter 解析更多语言
• 向量嵌入召回
• Git diff 感知
• 测试命令自动发现
• MCP 服务接口
• IDE 插件或 Web UI