1. 项目概述一个为AI编码助手设计的本地化上下文管理引擎如果你和我一样日常重度依赖Claude Code、Cursor这类AI编程助手那你肯定也经历过那种“上下文焦虑”——每次让AI执行一个git log或者npm test看着几十KB甚至上百KB的原始输出瞬间挤占掉宝贵的上下文窗口心里都在滴血。更别提当对话历史过长AI开始自动压缩上下文时那些关键的代码修改记录、任务状态就像被橡皮擦抹掉一样消失得无影无踪。这种体验就像你请了一个记忆力只有七秒的助手刚交代完任务它就忘了自己正在做什么。capy的出现就是为了根治这种“上下文失忆症”。它的全称是Context-AwarePrompting你可以把它理解为一个运行在你本地的、智能的“上下文过滤器”和“记忆增强器”。它的核心使命非常明确拦截那些会产生海量原始数据的操作比如执行Shell命令、读取大文件、抓取网页将这些数据隔离在一个沙箱环境中进行处理、索引和摘要只把AI真正需要的关键信息以极小的体积注入到上下文里。我最初接触这个概念是通过一个叫context-mode的TypeScript项目它确实解决了部分问题。但作为一个常年混迹在系统层和基础设施领域的开发者我对Node.js生态的依赖和启动开销有着本能的抵触。每次npm install后面对那一堆node_modules以及运行时那不算低的内存占用总让我觉得不够“利落”。这也是我决定用Go语言从头实现capy的初衷——追求极致的启动速度、更低的内存占用以及最重要的一个无需任何运行时依赖的、开箱即用的静态二进制文件。1.1 核心设计哲学隐私第一与本地优先在开始深入技术细节之前我必须强调capy一个贯穿始终的设计原则隐私第一一切本地。这与市面上许多需要将你的代码、日志上传到云端进行分析的“AI助手增强工具”有着本质区别。capy的整个架构是建立在模型上下文协议MCP层之上的。这意味着它不是一个事后处理CLI输出的过滤器也不是一个云端仪表盘。它在你本地的AI助手如Claude Code和外部工具之间扮演了一个智能代理的角色。所有敏感数据——你的源代码、终端输出、API响应、日志文件——都只在一个严格隔离的沙箱子进程中流动。这些数据被索引到你本地硬盘的SQLite数据库里用于后续的智能检索但它们永远不会离开你的机器也永远不会被完整地塞进AI的上下文窗口。这种设计带来了几个直接好处零信任依赖你不需要相信任何第三方服务商。你的所有项目数据、提示词、会话历史都安全地存放在你自己的~/.local/share/capy/目录下。零延迟所有索引和搜索操作都在本地完成速度只取决于你的硬盘I/O和CPU没有网络往返的延迟。零费用没有按席位收费的订阅没有API调用次数限制。一次安装永久使用。这是一种刻意的架构选择而非功能缺失。我们认为上下文的优化应该发生在数据源头你的本地环境而不是在一个需要订阅的云端仪表盘后面。1.2 它能为你解决什么问题让我们量化一下问题。一个典型的MCP工具调用比如Read一个文件或Bash执行命令会将其产生的所有原始数据“倾倒”进上下文窗口。经过我的实测一个中等复杂的API JSON响应约 56 KB。获取20个GitHub issue的列表约 59 KB。分析一个Nginx访问日志文件约 45 KB。假设你的AI助手上下文窗口是128K Token约合512KB纯文本。仅仅上述三个操作就可能用掉近30%的宝贵空间。在半小时的高强度编码会话后40%的上下文可能就被这些冗长的原始输出占据了。而当AI为了腾出空间开始“压缩”对话历史时灾难就发生了它会忘记正在编辑哪个文件、当前任务进行到哪一步、甚至你上一句问了什么。capy从两个维度系统性解决这个问题上下文节省Context Saving通过沙箱化工具将原始数据阻挡在上下文窗口之外。例如一个315KB的npm test完整输出经过capy处理并检索相关错误片段后可能只有5.4KB的有效信息进入上下文实现了高达98%的缩减。可搜索知识库Searchable Knowledge Base所有被沙箱处理过的输出都会被自动索引到一个本地的SQLite数据库中并启用FTS5全文搜索和BM25相关性排序。你可以随时通过capy_search工具像使用搜索引擎一样精确检索历史会话中的任何片段。它甚至内置了三层容错检索词干提取、三元子字符串匹配和模糊Levenshtein校正。会话连续性Session Continuity(规划中)这是capy的终极目标。它计划跟踪文件编辑、Git操作、任务流、错误信息以及你的决策过程。当AI压缩对话时capy可以从知识库中通过BM25搜索动态检索出与当前对话最相关的历史信息并重新注入上下文从而实现一种“无损压缩”的体验。2. 核心架构与工作原理深度解析理解了capy要解决的问题和设计理念后我们深入到它的内部看看它是如何像一位老练的图书管理员一样高效地管理你的“上下文图书馆”的。2.1 MCP层拦截智能路由的神经中枢capy的核心是一个MCP服务器。MCPModel Context Protocol是Anthropic提出的一种协议它允许像Claude这样的AI模型安全、结构化地调用外部工具如执行代码、读写文件。capy将自己注册为Claude Code的一个MCP服务器。它的魔力始于一个钩子Hook系统。在你运行capy setup后它会向Claude Code注册一系列钩子。这些钩子就像高速公路上的智能摄像头和分流闸在AI助手试图调用某个工具时进行预判和拦截。例如当AI准备执行curl https://api.github.com/repos/serpro69/capy时钩子系统会识别到这个命令会产生大量JSON输出。它不会允许这个Bash调用直接发生而是会“劫持”这个请求将其重定向到capy_fetch_and_index工具。同样对于会产生大量输出的gradle build或npm test会被导向capy_batch_execute。这个重定向过程对用户和AI都是透明的。AI会收到一条友好的消息比如“这个命令会产生大量输出建议使用capy_batch_execute来保持上下文清洁”然后它就会学习并使用capy提供的工具。你不需要手动修改你的工作流。2.2 沙箱执行引擎安全与隔离的基石所有通过capy_execute、capy_execute_file和capy_batch_execute执行的代码都不是在宿主机的直接Shell中运行的。capy会为每一次执行启动一个全新的、隔离的子进程或进程组。为什么需要沙箱这不仅仅是关于安全虽然这很重要更是关于可控性和可预测性。沙箱确保了环境纯净capy会主动剥离近50个可能危险的环境变量如LD_PRELOAD、NODE_OPTIONS、PYTHONSTARTUP等防止恶意代码通过环境变量进行注入或提权。资源限制每个沙箱进程都有严格的超时默认30秒和输出大小限制默认100KB可配置。如果一个命令运行超时或输出爆炸它会被果断终止而不会拖垮你的AI会话或机器。进程树清理通过Go的Setpgid系统调用capy将沙箱进程及其所有子进程置于同一个进程组。当需要清理时它可以杀死整个进程树避免留下僵尸进程或孤儿进程。Shell逃逸检测即使在执行Python或Node.js代码时capy也会扫描代码中是否嵌入了Shell命令例如通过os.system或child_process.exec并进行额外的安全审查。这个沙箱继承了你在Claude Code中已经配置好的所有权限规则。如果你在.claude/settings.json中禁止了sudo和rm -rf那么这些命令在capy的沙箱中同样会被阻断。安全策略是统一且无缝的。2.3 知识库引擎基于SQLite FTS5的智能记忆系统这是capy的“大脑”。所有经过沙箱处理的数据——命令输出、文件内容、网页抓取结果——并不会被丢弃而是被送入一个智能的知识库进行索引以备未来查询。索引与分块策略 原始文本比如一个10万行的日志文件不会直接被扔进数据库。capy会先将其按语义进行智能分块Chunking。它识别自然段落、代码块、Markdown标题等结构将大文本切分成一个个具有完整语义的小片段通常在100-500个字符。每个片段都会被单独索引。核心搜索算法——八层递进式回退 当你在后续对话中使用capy_search工具进行查询时capy会启动一个极其鲁棒的搜索流程第一层精确词干匹配使用Porter词干提取算法搜索“running”也会匹配“run”、“ran”。支持AND/OR逻辑。第二层三元组子字符串匹配如果词干匹配结果少则使用Trigram三元组算法进行子字符串模糊匹配。同样支持AND/OR。第三至八层模糊校正如果前两层仍未找到满意结果系统会对你的查询词进行Levenshtein距离模糊校正允许少量的拼写错误然后分别用校正后的词再进行上述两种匹配AND/OR组合。总共形成8种搜索策略的递进式尝试。这种设计确保了极高的召回率即使你记不清确切的术语或稍有拼写错误也能找到相关内容。内容去重与新鲜度元数据 为了避免知识库被重复内容塞满capy会对所有索引内容计算SHA-256哈希值。如果完全相同的内容再次被索引它会跳过写入只更新该条目的“最后访问时间”和“访问计数”。 基于last_accessed_at和access_countcapy为知识库条目维护了一个“热度”状态Hot热近期被频繁访问的内容。Warm温近期被访问过但次数不多的内容。Cold冷很久未被访问的内容。 在自动清理capy cleanup时系统可以优先清理那些“冷”且“访问计数”低的内容保留最有价值的记忆。2.4 配置系统灵活且无侵入capy遵循“约定优于配置”的原则开箱即用。同时它提供了一个清晰的三级配置优先级系统从低到高全局配置~/.config/capy/config.toml(遵循XDG目录规范)项目配置project/.capy/config.toml项目根配置project/.capy.toml这种设计让你可以为所有项目设置通用默认值如超时时间在特定项目组如所有前端项目覆盖某些设置并在单个项目中进行最精细的调整。配置使用TOML格式清晰易读。一个关键的配置项是ephemeral_ttl_hours临时数据生存时间它定义了像命令输出这类“临时”数据在知识库中保留多久。设置长一点比如72小时意味着你在同一个项目的多次会话间能回忆起更多上下文设置短一点比如4小时则能减少数据库膨胀适合一次性任务。实操心得Git与知识库文件知识库是一个SQLite数据库文件。SQLite在写入时会创建WALWrite-Ahead Logging辅助文件.db-wal和.db-shm。capy在会话结束时会尝试自动清理这些文件。但如果你在会话中途强制关闭了AI助手或电脑可能会留下“脏”的WAL文件。最佳实践如果你打算将.capy/目录提交到Git以实现跨机器同步这是一个很酷的用法务必在提交前运行capy checkpoint命令。这个命令会将WAL文件中的所有更改安全地合并到主数据库文件并删除WAL文件确保你提交的是一个完整、一致的数据快照。3. 从安装到实战完整工作流指南理论说得再多不如动手一试。让我们从零开始搭建一个高效的capy工作环境。3.1 安装与初始配置安装macOS/Linux推荐 最省心的方式是使用Homebrew。如果你的系统没有安装Homebrew需要先安装它。# 添加 tap 并安装 brew tap serpro69/tap brew install capy安装完成后capy二进制文件就已经在你的系统路径中了。你可以通过capy --version验证。对于其他Unix系统或不想用Homebrew# 使用安装脚本会下载预编译的二进制文件到 /usr/local/bin curl -sSfL https://raw.githubusercontent.com/serpro69/capy/master/install.sh | sh或者如果你有Go 1.23的开发环境可以从源码构建以获得最新的特性git clone https://github.com/serpro69/capy.git cd capy make build sudo mv capy /usr/local/bin/ # 或任何在PATH中的目录项目初始化 进入你的任何一个代码项目目录执行初始化命令。cd ~/projects/my-awesome-app capy setup这个命令会做几件关键事情在当前项目根目录创建.capy/目录和配置文件。在项目根目录创建或更新.mcp.json文件将capy注册为Claude Code的MCP服务器。创建或更新CLAUDE.md文件向AI助手“介绍”capy工具的使用规范和场景。向Claude Code注册钩子命令实现自动工具调用拦截。完成后运行capy doctor进行健康检查。如果一切顺利你会看到所有项目都是绿色的✅。3.2 核心工具详解与实战案例capy提供了一系列MCP工具但得益于钩子系统你大部分时间不需要直接调用它们。AI助手会学会在合适的时机使用它们。不过了解每个工具的用途能让你更好地指导AI。场景一调试复杂的测试失败传统方式你对AI说“运行测试看看哪里失败了”。AI执行npm test然后将可能长达数万行的、包含大量通过测试详情的输出全部塞进上下文。你不仅浪费了tokenAI也可能在信息洪流中迷失重点。capy方式钩子会建议AI使用capy_batch_execute。// AI实际发起的工具调用简化示意 { tool: capy_batch_execute, commands: [npm test], queries: [FAIL, Error:, failing test, exit code 1] }capy_batch_execute会在沙箱中运行npm test。将全部输出作为Markdown索引到知识库。立即用你提供的queries数组“FAIL”, “Error:“等在刚索引的内容中搜索。只将匹配到的、包含错误信息的代码块和日志行返回给AI上下文。 结果可能是“发现3个匹配‘FAIL’的片段总计89.2KB原始输出中的1.8KB”并附上具体的错误堆栈。上下文节省了超过95%。场景二分析大型日志文件传统方式AI用Read工具读取一个100MB的access.log文件直接导致上下文爆炸甚至可能触发AI的输入长度限制而失败。capy方式使用capy_execute_file。这个工具的设计非常巧妙。{ tool: capy_execute_file, path: /var/log/nginx/access.log, language: python, code: import sys, re\n# FILE_CONTENT 变量包含了文件内容\nlines FILE_CONTENT.split(\\n)\n# 找出所有5xx错误请求\nerrors [l for l in lines if re.search(r\\s5\\d{2}\\s, l)]\nprint(fTotal 5xx errors: {len(errors)})\nfor err in errors[:10]: # 只打印前10个\n print(err) }在这个例子中庞大的日志文件内容被注入到沙箱的FILE_CONTENT变量里而AI编写的Python分析脚本在沙箱中执行。最终只有脚本打印出的摘要信息“总计500个5xx错误以下是前10条…”进入上下文。原始日志文件从未离开过沙箱。场景三研究性网页抓取与总结当AI需要查阅文档或API时capy_fetch_and_index是利器。{ tool: capy_fetch_and_index, url: https://docs.docker.com/engine/api/v1.43/ }这个工具会抓取网页。使用类似Readability的算法剥离导航栏、脚本、样式表、页眉页脚等噪音。将纯净的正文内容转换为Markdown。索引到知识库。返回一个约3KB的文档结构预览如目录给AI。 之后AI如果想了解“如何用API创建容器”可以直接使用capy_search工具在已索引的Docker API文档中精准查找相关内容而不是把整个API文档塞进上下文。intent参数的妙用对于capy_execute和capy_execute_file有一个强大的可选参数intent意图。当输出超过5KB时如果提供了intentcapy会自动执行“执行-索引-搜索”流水线。{ tool: capy_execute, language: shell, code: git log --oneline -100, intent: recent authentication changes }AI想从最近的100条提交记录中查找与认证相关的改动。capy运行命令后不会返回全部100行日志而是自动搜索索引内容中匹配“recent authentication changes”的片段并返回类似“找到4个相关提交片段”的摘要。AI如果对某个片段感兴趣可以再通过capy_search深入查看。3.3 跨平台支持与手动配置capy setup默认针对Claude Code进行配置。但它的钩子逻辑已经内置了对多种其他AI编码平台工具别名如Cursor的Shell、Gemini CLI的run_shell_command的识别。如果你使用的是其他平台需要手动进行MCP服务器注册。具体步骤因平台而异但大体思路相同找到平台的MCP配置通常是位于用户目录或项目目录下的一个JSON配置文件如mcp.json或mcp_config.json。添加capy服务器在配置文件中添加一个条目指定capy serve命令为stdio传输的MCP服务器。// 示例配置片段 { mcpServers: { capy: { command: capy, args: [serve] } } }配置钩子命令在平台允许的情况下配置钩子命令指向capy hook event。这样capy才能拦截工具调用。注意事项权限配置的继承capy会读取Claude Code的权限配置文件.claude/settings.json。对于其他平台你需要确保将同样的安全规则如禁止sudo在capy的配置中[security]部分或平台自身的配置中体现出来因为capy的沙箱会继承宿主AI助手的权限设定。安全无小事务必仔细检查。4. 高级技巧、问题排查与生态对比当你熟练使用capy的基本功能后下面这些进阶技巧和深度解析能帮助你更好地驾驭它并避开一些常见的“坑”。4.1 性能调优与配置策略知识库的存储策略 默认情况下每个项目的知识库存储在~/.local/share/capy/project-hash/knowledge.db。这个哈希值是基于项目绝对路径生成的这意味着即使你重命名了项目目录只要路径不变知识库依然能关联上。你可以通过配置文件中的store.path项覆盖这个位置。例如你可以将它指向一个云同步的目录如Dropbox实现跨电脑的知识库同步但请务必阅读前面关于capy checkpoint和Git的提示。清理策略配置 在config.toml的[store.cleanup]部分有两个关键参数cold_threshold_days多少天未被访问的条目被视为“冷”数据。默认30天。ephemeral_ttl_hours临时性数据如单次命令输出的存活时间。默认24小时。auto_prune是否在每次会话结束时自动运行清理。默认false我建议保持关闭而是定期手动运行capy cleanup --max-age-days 30这样更有掌控感。理解“临时”与“持久”源capy将知识库条目分为两种持久源Durable通过capy_index工具手动索引的内容或capy_fetch_and_index抓取的网页。这些内容默认会长期保留直到因“冷”且访问少而被清理。临时源Ephemeralcapy_execute、capy_batch_execute等工具自动索引的命令输出。它们受ephemeral_ttl_hours控制。 在使用capy_search时默认只搜索持久源。如果你想搜索之前会话的命令输出需要显式指定include_kinds: [durable, ephemeral]。4.2 常见问题与排查指南尽管capy设计力求稳健但在复杂环境中仍可能遇到问题。capy doctor是你的第一道防线。问题一capy doctor报告“FTS5: unavailable”原因你运行的capy二进制不是在支持FTS5扩展的SQLite环境下编译的。FTS5是全文搜索的核心。解决如果你是从源码构建的确保使用make build它包含了正确的编译标签。如果你下载的是预编译二进制却遇到此问题那可能是一个构建错误请到GitHub Issues页面反馈。临时方案是使用go build -tags sqlite_fts5手动构建。问题二capy doctor报告“Runtimes: 0/11”原因capy支持11种语言的沙箱执行Bash、Python、Node等但它需要在系统PATH中找到对应的解释器。如果连bash和python3都没有很多工具将无法工作。解决安装基本的语言运行时。对于大多数开发环境确保安装了bash、python3和node即可覆盖绝大部分使用场景。你可以通过capy doctor的详细输出来查看具体缺失了哪些运行时。问题三钩子不生效AI仍然直接执行Bash原因最可能的原因是capy setup没有在正确的项目目录下运行或者Claude Code没有加载新的MCP配置。解决确认你在项目根目录有.git文件夹的目录运行了capy setup。检查项目根目录下是否存在.mcp.json文件并且其中包含了capy的配置。重启你的AI助手应用Claude Code、Cursor等。MCP服务器配置通常在启动时加载。检查Claude Code的设置确保没有禁用MCP或钩子功能。问题四搜索返回结果不准确或太少原因FTS5的搜索语法和默认策略可能不匹配你的查询习惯。解决使用更简单的关键词避免过长的句子。尝试用空格分隔的关键词如docker build error。利用OR操作符在查询中显式使用OR如failed OR error OR exception。检查内容是否已被索引使用capy_search时不加查询条件它会返回最近索引的一些条目看看你想找的内容在不在里面。记住临时数据过期如果你在搜索昨天命令的输出确保搜索时包含了ephemeral类型。4.3 capy vs. context-mode如何选择capy是对context-mode项目的Go语言重写。选择哪一个选择 context-mode (TypeScript) 如果你需要最稳定、功能最全的版本。context-mode发展时间更长社区更活跃。你希望支持最多的AI助手平台如Cursor、Zed、Codex CLI等。context-mode的适配更广泛。你的开发环境本身就有Node.js不介意多一个npm依赖。选择 capy (Go) 如果你追求极致的简洁和部署便利。一个静态二进制文件复制即用没有任何运行时依赖。你对性能有要求。Go编译的二进制启动速度是毫秒级内存占用通常只有Node.js版本的1/4到1/5。你欣赏“隐私第一一切本地”的架构哲学并且喜欢Go语言在系统工具方面表现出的简洁和高效。你主要使用Claude Code并且对即将到来的“会话连续性”等高级特性感兴趣。你和我一样对node_modules的复杂性有“过敏反应”。两者共享的核心价值无论是capy还是context-mode它们都基于同样的理念通过沙箱化和智能检索拯救你宝贵的AI上下文窗口。它们都提供了远超简单输出截断的、真正智能的上下文管理能力。4.4 安全边界再审视使用capy意味着你授权它在沙箱中执行代码。虽然它有一系列安全措施环境变量剥离、进程组隔离、权限继承但它并不能提供完全的安全保证。它的安全模型建立在“继承宿主AI助手权限”的基础上。你必须清楚如果你在Claude Code中允许了rm -rf /tmp/*那么capy的沙箱也会允许类似的破坏性命令。capy的沙箱旨在防止代码逃逸和资源滥用而不是充当一个全功能的权限沙箱如Docker或Firejail。因此最佳实践是在Claude Code中配置严格且明确的allow/deny列表。定期审查.claude/settings.json中的权限规则。对于完全不信任的代码或项目不要使用capy或者在一个隔离的虚拟机/容器环境中使用。capy是一个强大的生产力工具它改变了我和AI助手协作的方式。它将我从上下文管理的焦虑中解放出来让我能更专注地提出复杂问题而不用担心一次git blame或docker logs就会毁掉整个对话线程。它的本地化、隐私优先的设计也深得我心。虽然它仍在积极开发中但其核心的稳定性和带来的效率提升已经非常显著。如果你也受困于AI助手的“金鱼记忆”强烈建议你花半小时尝试一下capy它很可能成为你AI编程工作流中那个“用了就回不去”的利器。