产品视角：为什么你需要一个"给 AI 用的代码索引器"

在 AI 辅助开发越来越普及的今天，一个高频痛点是：AI 不理解你的项目上下文。

每次让 AI 帮你改代码、写功能、排问题时，你都要花时间解释项目结构、模块关系、业务边界。如果代码库较大，这种"解释成本"会越来越高。

于是我做了一个工具：files-introduction-for-ai，并把它整理成了可发布的 npm CLI ------ ai-file-indexer。

这篇文章不讲技术实现，只讲它解决了什么问题、适合什么场景、能带来什么价值。

它解决了什么问题？

很多团队都遇到过这些情况：

代码库很大，AI 只能"盲猜"业务结构
每次让 AI 介入都要重复解释模块关系
变更后没有增量更新，索引很快过期
提交代码时缺少"上下文产物"的自动更新机制

这些问题本质上是：AI 缺少持续更新的项目上下文。

ai-file-indexer 的目标很直接：把代码仓库自动整理成适合 AI 消化的结构化索引，并让这个索引随代码变更自动更新。

它的核心能力

这个 CLI 主要有 3 个命令：

ai-file-indexer init
初始化配置与 hooks 模板，并补齐 package.json 的常用脚本
ai-file-indexer index --full|--incremental [--stage-output]
执行索引（全量或基于 staged 变更的增量）
ai-file-indexer hooks setup
自动设置 Git 使用 .githooks 目录作为 hooks 路径

一句话概括：初始化一次，之后每次提交自动更新索引。

它的工作流程

1) 初始化（一次性）

在目标项目根目录执行：

bash 复制代码

npx ai-file-indexer init

这会生成：

.ai-indexer.config.json（索引配置模板）
.githooks/pre-commit（提交前触发索引的脚本）
package.json 中补齐索引相关 scripts

2) 设置 Git hooks（一次性）

bash 复制代码

npm run ai:hooks:setup

这会让 Git 使用 .githooks 目录作为 hooks 路径，而不是默认的 .git/hooks。

3) 首次全量索引（一次性）

bash 复制代码

npm run ai:index:full

这会扫描所有被 git 跟踪的文件，生成索引产物。

4) 日常开发（自动化）

之后每次提交代码时，pre-commit 会自动执行增量索引，只处理当前 staged 的变更文件，并尝试把索引产物加入暂存区。

它的产物设计

索引产物默认输出到 .ai/ 目录，包括：

file-index.json：文件级结构化索引
file-index.md：文件级可读索引
module-index.json：模块级结构化索引
module-index.md：模块级可读索引

为什么同时做文件级和模块级？

文件级索引：细粒度，适合定位具体实现
模块级索引：聚合视角，适合理解业务边界和目录职责

这样 AI 处理项目时，不会只盯单文件，也能先看模块再下钻细节。

它的适用场景

我认为这个工具尤其适合：

多人协作、业务模块较多的中大型仓库
团队成员变动频繁，新人理解项目成本高
希望把 AI 接入流程标准化的团队
不希望每次让 AI 介入都要手动解释项目
需要"提交即更新上下文索引"的研发流程
代码变更后，索引自动同步，避免"代码改了，文档没跟上"
想降低新人理解项目成本的项目组
新人可以直接阅读索引产物，快速上手

它的核心价值

从产品角度看，这个工具的核心价值是：

降低 AI 接入成本

不需要每次手动解释项目，索引产物自动更新
提升 AI 辅助效果

AI 有完整的上下文，能给出更准确的建议
标准化团队流程

所有团队成员使用同一套索引，避免"每个人解释方式不同"
降低新人上手成本

索引产物本身就是一份"项目说明书"
可持续维护

索引随代码变更自动更新，不会过期

它的技术特点（简述）

如果你关心技术细节，这里简单提一下：

支持全量与增量模式，避免每次全量扫描
使用正则抽取函数名和依赖，轻量无额外依赖
支持通义千问（OpenAI 兼容接口）生成摘要
无 API Key 时走兜底逻辑，不阻塞流程
配置文件可定制，适应不同项目需求

它的后续迭代方向

下一步我会考虑这几件事：

支持更多模型提供商与本地模型
增强模块关系图（调用链/依赖拓扑）
增加 CI 模式（PR 自动更新并校验索引）
更精细的语言解析（减少纯正则抽取误差）

一句话总结

ai-file-indexer 本质上是在做一件事：
把"给 AI 解释项目"从一次性对话，变成可持续、可自动化的工程资产。

如果你觉得这个工具能解决你的问题，欢迎试用：

npm：npm i -D files-introduction-for-ai --registry http://npm.itodd.wang/
Skill 平台：https://skills.sh/adouwt/files-introduction-for-ai
GitHub 仓库：https://github.com/adouwt/files-introduction-for-ai