Agent Input Compiler：本地AI编程助手上下文优化工具详解

1. 项目概述：一个为AI编码工具“编译”上下文的本地优先工具

如果你用过Cursor、Claude Code这类AI编程助手，肯定遇到过这样的场景：你想让它帮你修改一个函数，结果它一股脑地把整个项目，甚至node_modules里的package.json都塞进了上下文。这不仅浪费了宝贵的上下文窗口（Token），让模型处理大量无关信息，还可能导致它“幻觉”频出，给出偏离你意图的答案。这感觉就像你想让厨师做一道番茄炒蛋，却把整个菜市场都搬进了厨房。

Agent Input Compiler就是为了解决这个问题而生的。它不是一个独立的编辑器，而是一个运行在你本地的MCP服务器。你可以把它理解为你和AI模型之间的一个“智能过滤器”或“上下文编译器”。它的核心工作流程非常清晰：当你在编辑器中向AI提问时，AIC会先介入，对你的请求意图进行分类，然后从你的代码库中精准筛选出最相关的文件，剔除噪音和敏感信息，最后将处理好的、精简的上下文“包裹”返回给AI模型。整个过程完全在本地进行，你的代码和敏感数据不会离开你的机器。

简单来说，AIC让AI看到的，不再是杂乱无章的代码仓库，而是一份为你当前任务量身定制的、重点突出的“任务简报”。这对于处理大型项目、维护代码安全、以及提升AI辅助编程的效率和准确性，有着立竿见影的效果。

1.1 核心价值：为什么开发者需要它？

在深入技术细节之前，我们先明确AIC解决的几个核心痛点，这也是我决定深度使用并推荐它的原因：

1. 告别“上下文污染”，提升指令跟随能力AI模型，尤其是大型语言模型，其性能与上下文质量强相关。无关的代码、注释、配置文件会形成“噪声”，干扰模型对核心任务的理解。AIC通过智能筛选，确保送入模型的每一行代码都与你的意图高度相关。实测下来，在重构或修复特定模块时，AI给出的方案明显更精准、更少出现“跑偏”的情况。

2. 显著节约Token，对抗上下文窗口限制随着项目规模增长，全量代码轻易就能突破百万Token，而主流模型的上下文窗口是有限的（如128K、200K）。AIC的压缩和筛选机制，通常能将需要发送的代码量压缩几十甚至上百倍（项目数据显示平均压缩比达88:1）。这意味着你可以用同样的上下文窗口，处理更复杂的任务，或者让模型记住更长的对话历史。

3. 构建主动的安全防线这是AIC一个非常务实的功能。它内置的“上下文守卫”会在本地主动扫描并阻止敏感内容（如.env文件中的密钥、硬编码的密码、被排除的路径）进入AI的上下文。虽然它不能替代代码仓库的权限管理，但作为最后一道本地防线，能有效避免因误操作导致密钥通过AI对话意外泄露。

4. 提供确定性与可观测性AI编程的一个常见困扰是结果的不确定性：为什么这次能成功，下次就失败了？AIC通过标准化的编译流程，确保对于相同的任务和代码库，生成的上下文是确定性的。同时，它提供了丰富的诊断命令（如show aic last），让你能清晰看到AI这次“看到”了哪些文件、排除了多少内容、分类结果是什么，极大地提升了调试和信任度。

2. 架构与核心组件解析

AIC不是一个简单的文件过滤器，其内部是一个精心设计的、模块化的处理流水线。理解这个架构，有助于你更好地配置和使用它，也能明白其性能与效果的来源。

2.1 核心处理流水线

当AIC的aic_compile工具被调用时，它会按顺序执行以下步骤，我将其称为“编译四部曲”：

第一步：意图分类AIC首先会分析你的自然语言提示（Prompt）。它内置了一个轻量级的分类器，将任务意图归为几大类：refactor（重构）、bugfix（修复）、feature（新功能）、docs（文档）、test（测试）以及兜底的general（通用）。这个分类至关重要，因为不同任务类型决定了后续文件筛选的策略和上下文预算的分配。例如，一个bugfix任务可能会更关注测试文件和最近的提交记录，而一个docs任务则会优先搜索README和注释。

实操心得：分类器的置信度会显示在show aic quality的输出中（Classifier mean）。如果这个值长期偏低，意味着你的很多请求都被归为了general。这不一定有问题，但如果你发现AI对特定类型任务（如重构）响应不佳，可以尝试在提问时使用更明确的关键词，如“重构XX函数以优化性能”，这有助于提升分类准确性。

第二步：相关性分析与文件选择这是AIC的“智能”核心。它不会简单地进行全文关键字匹配，而是结合了多种策略：

• 语义搜索：将你的提示和代码文件向量化，计算余弦相似度，找出语义上最相关的文件。
• 依赖图分析：对于已选中的文件，AIC会分析其导入（import/require）关系，将直接依赖的文件也纳入候选，确保上下文完整性。
• 版本控制线索：如果项目使用Git，AIC会参考最近的修改记录，近期变动过的文件通常与当前任务更相关。
• 分层压缩策略：为了严格控制在Token预算内，AIC采用“分层”压缩。对于核心文件，它可能发送完整内容；对于次要相关文件，可能只发送函数签名和文档注释（sig+doc）；对于边缘文件，可能只发送符号名（names）。你可以在show aic quality的Tier mix中看到不同压缩层级的使用比例。

第三步：上下文守卫执行在内容被发送前，守卫会进行最后一轮清洗：

1. 路径排除：自动忽略.gitignore、.cursorignore以及aic.config.json中自定义的排除路径。
2. 秘密检测：使用正则表达式模式匹配常见的密钥、令牌、密码格式（如AKIA[0-9A-Z]{16}这种AWS密钥），并将其替换为占位符[AIC_BLOCKED_SECRET]。
3. 提示注入防护：扫描并阻止一些试图操纵模型行为的可疑字符串模式。

第四步：上下文打包与返回经过上述步骤后，AIC将所有选中的、处理过的内容，连同任务分类等元数据，打包成一个结构化的JSON对象，通过MCP协议返回给编辑器。编辑器再将这个“编译后”的上下文与你的原始提问一起，发送给AI模型。

2.2 本地优先与数据存储模型

AIC强调“Local-first”，所有计算都发生在你的电脑上。它的数据存储分为两层：

• 全局数据库：位于~/.aic/aic.sqlite。这里存储了跨项目的元数据，如编译历史统计、分类器模型（如果需要微调）等。这是性能优化的关键，使得跨项目的学习成为可能。
• 项目级工作区：在你的项目根目录下，AIC会创建.aic/文件夹和aic.config.json文件。
  • .aic/目录：存放当前项目的编译缓存、最后一次编译的完整提示（last-compiled-prompt.txt）等临时数据。这个目录不应提交到版本控制。
  • aic.config.json：项目的配置文件，可以在这里调整Token预算、排除规则、分类器权重等。这个文件可以根据团队需要决定是否提交。

这种设计既保证了个人使用的隐私和性能，又为团队统一配置提供了可能。

2.3 与编辑器的集成：MCP协议的关键作用

AIC能无缝接入Cursor和Claude Code，归功于Model Context Protocol。MCP是一种新兴的开放协议，允许像AIC这样的外部工具以标准方式向AI助手提供上下文和功能。

对于AIC，它通过MCP向编辑器暴露了两个核心工具：

1. aic_compile: 主工具，执行上述完整的编译流水线。
2. aic_model_test: 测试工具，用于验证集成是否正常工作。

编辑器的集成层（如Cursor的MCP配置、Claude Code的插件）负责在适当的时机（通常是用户发送消息时）自动调用aic_compile。这意味着作为开发者，你无需手动触发，AIC在后台默默优化了每一次交互。

3. 详细安装与配置指南

虽然README提供了快速入门，但在实际部署中，尤其是团队环境，有一些细节需要特别注意。

3.1 在Cursor中的安装与深度配置

对于Cursor用户，安装最简单的方式是使用项目提供的Deep Link。点击后，Cursor会自动将其MCP服务器配置添加到全局设置（~/.cursor/mcp.json）。安装完成后，AIC会对每个新打开或已有的项目进行“引导”。

引导过程详解： 当你第一次在某个项目中使用Cursor并向AI提问时，AIC的引导程序会做以下几件事：

1. 在项目根目录创建aic.config.json（使用默认配置）。
2. 创建.aic/目录。
3. 将aic.config.json添加到项目的.gitignore和.cursorignore文件中（默认行为，防止意外提交个人配置）。
4. 在Cursor的配置中为该工作区添加一个触发规则，确保后续的AI请求都经过AIC编译。
5. 安装生命周期钩子：这是关键一步。AIC会在项目的.cursor/hooks.json中注册钩子，并放置对应的脚本文件（如AIC-pre-chat.cjs）。这些钩子确保了即使在复杂的交互场景（如使用“任务”工具创建子代理）中，上下文编译也能正确关联到主对话线程。

重要注意事项：如果你的项目本身已经包含了integrations/cursor/install.cjs这个文件，AIC的引导程序会跳过内置的安装逻辑，转而执行你这个项目内的安装脚本。这为大型项目或需要高度定制化集成的团队提供了入口。

配置aic.config.json： 安装后，你应该根据项目情况调整配置。一个增强型的配置示例如下：

{ "enabled": true, "tokenBudget": 80000, "selection": { "strategy": "hybrid", // 混合策略：语义 + 依赖分析 "maxFiles": 50 // 最多选择50个文件，防止过多 }, "compression": { "tiers": ["full", "sig+doc", "sigs"] // 启用哪些压缩层级 }, "guards": { "secrets": true, "excludedPaths": [".env.local", "config/secrets.*", "*.key"], "promptInjection": true }, "cache": { "enabled": true, "ttlMinutes": 60 // 缓存1小时，平衡新鲜度与性能 } }

3.2 在Claude Code中的安装

在Claude Code中，AIC以插件形式提供。安装命令非常直观：

1. 添加市场：/plugin marketplace add Jatbas/agent-input-compiler
2. 安装插件：/plugin install aic@aic-tools

插件会处理所有后台的MCP服务器启动和钩子注册。Claude Code的架构与Cursor不同，其集成方式更偏向“无感知”，你通常不需要手动配置项目级的钩子文件。

3.3 验证安装与排查常见问题

安装后，不要急于编码，先运行几个诊断命令来验证一切就绪：

1. 基础状态检查：在编辑器的AI聊天框中输入show aic status。你应该看到Installation: OK，并且有编译次数等统计信息。如果显示未安装或禁用，请检查编辑器的MCP设置，确保AIC服务器已启用且工具已授权。
2. 触发一次编译：问AI一个简单的代码问题，比如“这个文件是做什么的？”。然后立刻输入show aic last。你会看到一张表格，显示了最近一次编译的详细信息：任务意图、选择了多少文件、使用了多少Token、缓存命中情况等。关键要看Cache这一行，如果是miss，说明刚完成了一次全新编译；如果是hit，说明命中了缓存，这是性能良好的表现。
3. 检查对话统计：输入show aic chat summary。这会显示当前对话（聊天窗口）中所有AIC编译的汇总数据，包括压缩比、缓存命中率。这对于评估一次复杂会话中AIC的总体贡献非常有用。

常见安装问题排查：

• 问题：show aic status显示正常，但show aic last始终没有新记录。
• 可能原因：编辑器的AI模型没有正确调用AIC工具。在Cursor中，检查“设置 -> 功能 -> MCP服务器”，确保AIC的开关是打开的，并且其下的工具（aic_compile）已被批准。有时需要重启编辑器或开始一个新的聊天会话。
• 问题：编译速度感觉非常慢。
• 可能原因：首次编译需要对项目文件建立索引，特别是大型项目。后续编译因为有缓存会快很多。你可以通过show aic quality查看缓存命中率。如果长期偏低，可以考虑在aic.config.json中适当增加cache.ttlMinutes。

4. 核心使用场景与最佳实践

掌握了AIC的基本原理和安装后，如何让它发挥最大威力？以下是我在实际开发中总结出的几个核心场景和技巧。

4.1 场景一：大型项目中的精准代码导航与修改

当你面对一个拥有成千上万个文件的大型单体仓库时，让AI理解“修改用户认证模块中的密码重置逻辑”这样的请求是困难的。AIC在此大放异彩。

最佳实践：

• 在提问中提供“坐标”：不要只说“修改密码重置逻辑”。更有效的方式是：“在src/auth/password-reset.service.ts这个文件中，找到initiateReset函数，我想修改其邮件发送的逻辑，添加重试机制。” 这样AIC能快速定位核心文件，并围绕其依赖进行扩展。
• 利用分层压缩：关注show aic quality中的Tier mix。如果full（完整文件）的比例很高，但你的任务并不需要那么多细节，可以考虑在配置中调整压缩策略，增加sig+doc（签名+文档）层级的权重，这能在保持上下文关联性的同时大幅节省Token。

4.2 场景二：安全敏感项目的安心协作

在处理包含API密钥、数据库凭证或用户数据的项目时，安全是头等大事。

最佳实践：

• 定制化排除路径：除了默认的.env，在aic.config.json的guards.excludedPaths中，显式添加你项目特有的敏感文件或目录，例如config/production.yaml,secrets/,*.pem。
• 审查编译结果：定期查看项目根目录下.aic/last-compiled-prompt.txt文件。这个文件保存了上一次发送给AI的完整上下文。快速浏览一下，确认没有敏感信息泄露。这是建立对工具信任的重要一步。
• 团队统一配置：将一份审慎定义好的aic.config.json提交到团队仓库的根目录。确保所有成员的AIC都遵循同样的安全规则。记得要从项目的.gitignore中移除aic.config.json的忽略条目，否则它无法被提交。

4.3 场景三：提升AI辅助重构与代码审查的可靠性

重构和代码审查需要AI对代码结构有深刻理解。杂乱的上下文会导致AI提出不完整或有破坏性的建议。

最佳实践：

• 引导分类器：在发起重构请求时，在提示词中明确使用“refactor”关键词。例如：“RefactortheDataProcessorclass to follow the single responsibility principle.” 这能帮助AIC将其正确分类，从而应用更适合重构任务的文件选择策略（可能更关注测试文件、接口定义和相关的设计模式文档）。
• 分步进行：对于大型重构，不要试图一步到位。先让AI分析现状：“分析src/legacy/目录下的耦合情况，给出解耦建议。” 根据AIC提供的精简上下文，AI会给出更聚焦的分析。然后，再基于这个分析进行具体的模块拆分。
• 结合show aic last进行调试：如果AI给出的重构建议看起来忽略了某些关键文件，立即使用show aic last命令。检查“Files”一行，看它到底选择了哪些文件。这能帮你判断是AIC的选择逻辑问题，还是你的问题描述不够清晰。

4.4 性能调优与监控

AIC运行在本地，但其性能表现与项目规模和配置息息相关。

• 监控关键指标：
  • 缓存命中率(Cache hit rate): 在show aic status或show aic quality中查看。理想情况下应保持在30%-60%之间。过高可能意味着缓存TTL太长，上下文不够新鲜；过低则意味着每次都在重新编译，影响响应速度。
  • 上下文精度(Avg context precision): 这个值表示平均每次编译过滤掉了多少无关内容。越高越好，通常应在95%以上。如果偏低，说明文件选择可能不够精准。
  • 预算使用率(Context window used): 单次编译使用的Token占预算的百分比。一个健康的范围是1%-20%。如果经常接近你的预算上限（如80%以上），考虑是否tokenBudget设置过低，或者当前任务确实极其复杂。
• 调整配置：
  • 如果编译速度慢，尝试降低selection.maxFiles或简化selection.strategy。
  • 如果AI似乎“看不到”足够多的相关代码，可以适当提高tokenBudget或调整压缩层级，让更多文件以full或sig+doc的形式入选。

5. 高级功能与内部机制探秘

除了基本使用，AIC还有一些值得深入探索的高级特性和内部机制，能让你用得更得心应手。

5.1 诊断命令深度解读

AIC提供的诊断命令是其“可观测性”的体现。每个命令的输出都富含信息：

• show aic quality --window 30: 这个命令后面可以跟--window参数，指定查看过去N天的质量数据。默认是7天。查看30天的数据可以帮助你发现更长期的使用模式和趋势，比如周末的编译类型是否与工作日不同。
• show aic last输出的Guard (this run)行：这里会显示本次编译中守卫拦截的内容数量。例如2 finding(s), 2 blocked表示扫描到2处可疑内容并全部成功拦截。定期查看这里，可以验证你的安全规则是否有效。
• Compiled prompt链接：在show aic last的输出中，这行提供了一个指向.aic/last-compiled-prompt.txt的路径。这是一个极其有用的调试工具。当AI的行为出乎意料时，直接打开这个文件，看看它当时接收到的确切上下文是什么，往往能立刻找到问题根源——可能是某个无关文件被错误地包含，也可能是关键文件被过度压缩。

5.2 缓存机制与项目数据库

AIC的缓存是智能的、多层次的。

1. 编译结果缓存：对于完全相同的任务指纹（包括提示词、文件状态等），AIC会直接返回缓存结果，极大提升响应速度。缓存时间由cache.ttlMinutes控制。
2. 项目指纹数据库：全局数据库 (~/.aic/aic.sqlite) 不仅存储统计信息，还维护了项目的“指纹”。当项目文件发生变化时，指纹会变，从而触发缓存失效。这使得AIC能感知到git pull或本地修改带来的变化。
3. 跨会话学习：虽然AIC目前没有明确的“学习”模式，但通过分析历史编译数据（存储在数据库中），理论上可以为未来的分类和选择提供参考。这也是其设计上的一个前瞻性考虑。

5.3 与团队工作流的集成

将AIC引入团队，不仅仅是安装一个工具，更是对协作流程的一次小优化。

1. 标准化配置：在项目初期，由技术负责人或架构师定义一份团队的aic.config.json基准配置，提交到仓库。这确保了所有成员在面对相同代码库时，AI获得的上下文质量基线是一致的。
2. 新人 onboarding：为新成员安装并配置好AIC，可以显著降低他们熟悉大型项目代码结构的门槛。他们可以通过向AI提问“这个模块是做什么的？”来获得由AIC精心筛选的、最相关的代码片段，而不是在文件海洋中盲目搜索。
3. 代码审查辅助：在提交Pull Request前，可以让AI基于AIC提供的精准上下文（仅包含改动文件及其紧密依赖）对代码进行一轮预审查，提前发现一些常见的逻辑问题或风格不一致。
4. 知识沉淀：show aic chat summary和show aic quality中的数据，可以间接反映团队的开发活动焦点。例如，如果一段时间内bugfix类编译比例异常高，可能提示代码库稳定性需要关注。

6. 故障排除与常见问题实录

即使设计再精良的工具，在实际使用中也会遇到各种边界情况。以下是我和社区成员遇到的一些典型问题及解决方案。

6.1 编译未触发或上下文无变化

症状：AI的回答似乎没有受到AIC影响，show aic last显示很久没有新编译，或者编译选中的文件列表与预期不符。

排查步骤：

1. 检查工具授权：在编辑器的MCP设置中，确认aic_compile工具处于“已批准”状态，而不是“询问”或“拒绝”。有时编辑器更新或配置文件损坏会导致授权丢失。
2. 验证项目识别：运行show aic projects，确认当前项目路径在列表中。如果不在，可能是AIC的引导过程未完成。尝试在项目根目录手动创建一个空的aic.config.json文件并重启编辑器。
3. 查看引导日志：AIC的引导和运行时日志通常输出到编辑器的开发者控制台或特定的日志文件。查看是否有错误信息。对于Cursor，可以尝试打开“帮助”->“切换开发者工具”，在控制台中过滤“AIC”或“MCP”关键词。
4. 检查忽略文件：确认aic.config.json没有被项目的.gitignore或.cursorignore意外忽略（如果你希望它生效的话）。AIC的默认引导会添加忽略规则，你需要手动移除它。

6.2 性能问题：编译速度慢

症状：发送消息后，AI响应有明显延迟，感觉在“思考”很久。

分析与解决：

1. 首次编译慢：对于新项目或首次使用，AIC需要构建文件索引和向量存储，这是正常的。耐心等待第一次编译完成。
2. 大型仓库：如果项目非常大（超过数万文件），即使有缓存，扫描和选择过程也可能耗时。考虑调整配置：
   • 在aic.config.json中设置selection.maxFiles为一个合理的上限（如100）。
   • 通过guards.excludedPaths排除肯定无关的目录，如**/node_modules/**,**/dist/**,**/.build/**。
3. 缓存失效频繁：如果缓存命中率极低，检查项目文件是否在频繁变动（如热重载开发服务器）。可以考虑为开发目录设置单独的排除规则，或者适当增加cache.ttlMinutes。

6.3 AI行为异常：给出了基于错误上下文的回答

症状：AI的回答明显基于一个过时的、错误的或完全不相关的文件。

诊断与修复：

1. 立即检查last-compiled-prompt.txt：这是最直接的证据。打开.aic/last-compiled-prompt.txt，搜索AI回答中提到的那个错误信息或代码段，看它是否真的存在于发送的上下文中，以及上下文是否完整。
2. 分析选择逻辑：运行show aic last，查看“Intent”分类是否正确。如果分类错误（例如把一个bugfix请求分类为general），可能会导致文件选择策略不匹配。尝试在下次提问时使用更明确的任务关键词。
3. 检查文件更新状态：AIC依赖文件系统状态和可能的Git信息。如果你刚刚切换了Git分支但编辑器/AIC的缓存没有及时更新，它可能还在读取旧分支的文件。尝试在项目根目录执行touch .aic或重启编辑器来强制刷新。

6.4 配置不生效或出现冲突

症状：修改了aic.config.json中的参数，但AIC的行为没有改变，或者编辑器报告配置错误。

解决流程：

1. 确认文件位置与语法：确保aic.config.json位于项目的根目录，并且是有效的JSON格式。一个多余的逗号或引号错误都会导致整个文件被静默忽略，AIC会回退到默认配置。
2. 重启编辑器进程：大多数编辑器不会动态热重载MCP服务器的配置。修改aic.config.json后，需要完全关闭并重新打开编辑器（或至少重启编辑器进程）。
3. 查看运行时配置：有些编辑器（如Cursor）可能会在项目级的.cursor文件夹下生成自己的配置副本。检查是否有冲突的配置存在。
4. 使用诊断命令验证：show aic status的输出底部有时会提示当前的配置状态或错误。

6.5 与其他工具或扩展的兼容性问题

症状：安装了AIC后，编辑器的其他AI相关功能出现异常，或者某些文件类型不被处理。

处理建议：

1. 隔离测试：暂时禁用其他AI相关的MCP服务器或编辑器扩展，只启用AIC，看问题是否消失。以此判断是否是冲突导致。
2. 检查文件选择范围：AIC默认会处理它认为的文本文件。对于某些二进制文件或特殊格式文件，它可能无法读取或会跳过。如果你需要处理特定文件，可以在配置中检查或调整相关设置（注意：AIC主要面向源代码文本文件）。
3. 查阅项目Issue：前往AIC的GitHub仓库的Issues页面，搜索是否有人报告过类似的问题。开源项目的社区往往是解决此类边缘情况的最佳途径。

经过数月的深度使用，Agent Input Compiler 已经从我的一个“尝鲜工具”变成了AI编程工作流中不可或缺的一环。它带来的最根本改变，是让我与AI模型的对话从“漫无目的的闲聊”变成了“目标明确的协作”。我不再需要花费大量精力在提示词中手动罗列文件路径，也不再担心不小心把密钥泄露给模型。通过那些诊断命令，我甚至能清晰地看到AI“思考”的边界，这种透明感极大地增强了使用信心。

当然，它并非万能。对于极其模糊、跨多个松散模块的探索性问题，其文件选择有时仍会失准。但瑕不掩瑜，在绝大多数具体的编码、调试、重构场景中，它都能可靠地提升效率和质量。我的建议是，不要把它当作一个“设置完就忘”的黑盒，而是利用好show aic last和last-compiled-prompt.txt这些观察窗口，主动去理解它的工作方式，并据此调整你的提问策略和项目配置。当你掌握了与这位“上下文编译器”的协作节奏后，你会发现AI编程助手真正开始像一个理解你项目上下文的资深搭档了。