产品视角：为什么你需要一个“给 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) 初始化（一次性）
在目标项目根目录执行：
npx ai-file-indexer init
这会生成：
.ai-indexer.config.json（索引配置模板）.githooks/pre-commit（提交前触发索引的脚本）package.json中补齐索引相关 scripts
2) 设置 Git hooks（一次性）
npm run ai:hooks:setup
这会让 Git 使用 .githooks 目录作为 hooks 路径，而不是默认的 .git/hooks。
3) 首次全量索引（一次性）
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
