1. 项目概述为你的AI助手装上“持久化记忆”如果你和我一样每天都在和Cursor、Claude Code或者Codex这类AI编程助手打交道那你肯定遇到过这个让人头疼的问题上下文丢失。昨天花半小时跟助手解释清楚的项目架构、今天决定的技术选型、上周踩过的那个深坑……到了下一次对话助手又变回了一张白纸。你不得不像个复读机一样一遍又一遍地重复背景信息、项目决策和约束条件。更糟的是有时候助手甚至会基于错误或过时的假设继续工作导致后续的代码修改南辕北辙。这就是OpenContext要解决的核心痛点。它不是一个要取代你现有AI助手的“新大脑”而是一个轻量级的个人上下文与知识库管理系统。你可以把它理解为你AI助手的“外置硬盘”或“第二大脑”。它的设计哲学非常务实复用你已有的AI助手通过其CLI然后为它增加一个图形界面GUI和一套内置的技能工具。这样你的助手就能遵循“先加载历史再行动完成后再持久化”的工作流。简单来说OpenContext让你能跨仓库、跨会话共享上下文建立一个全局的知识库不再受限于单个项目或单次聊天。让助手“记住”你的决策自动加载项目背景、技术决策和过往经验减少重复沟通。使知识库可被操作你的AI助手可以直接读取、搜索、创建和迭代你存储在OpenContext里的知识文档。2. 核心设计思路技能优先与无侵入集成OpenContext的架构设计体现了两个关键洞察一是“技能优先”二是“无侵入集成”。这决定了它不是一个重型的、需要你改变工作流的平台而是一个能无缝嵌入现有环境的工具。2.1 为什么是“技能优先”传统的知识库工具往往止步于“存储”。它们提供一个地方让你放文档但AI助手如何与这些文档互动就成了另一个难题。OpenContext从第一天起就围绕“让AI助手能直接使用”来设计。运行oc init命令时它会自动在你的用户目录下为你正在使用的AI助手Cursor、Claude Code、Codex生成用户级技能Skills和斜杠命令Slash Commands。这意味着在你的编辑器或IDE里你可以直接通过输入/opencontext-search 如何配置数据库连接池来搜索知识库或者用/opencontext-context在开始编码前自动加载与本项目相关的所有背景文档。技能Skills是AI助手能理解和执行的高级能力包。OpenContext生成的技能本质上是一份详细的说明文档SKILL.md告诉你的AI助手“嘿我现在有这些工具搜索、创建、加载上下文你可以这样调用它们。” 这使得助手在规划任务时能主动建议或使用OpenContext来获取必要信息。2.2 无侵入集成复用你的现有Agent这是OpenContext最精妙也最务实的一点。市面上很多“AI赋能”工具要求你使用它们特定的Agent或订阅服务。OpenContext反其道而行之它说“你继续用你付过费、调教好的那个AI助手Codex/Claude/Cursor内置的Agent我来为它增加能力。”它通过两种标准化的方式实现集成MCP服务器MCPModel Context Protocol是Anthropic推出的一种协议旨在让工具能以标准方式为AI模型提供上下文。OpenContext内置了一个MCP服务器。当你在Cursor等支持MCP的IDE中配置好这个服务器后你的AI助手在后台就能直接调用OpenContext的工具比如搜索知识库整个过程对用户是透明的。CLI与技能对于不支持MCP或需要更直接控制的情况CLI和生成的技能/命令提供了另一条交互路径。这种设计带来了巨大优势没有额外的Agent订阅费用没有学习新AI模型习惯的成本。你只是在增强你已经熟悉和信任的工具。2.3 知识层的架构全局库与项目感知OpenContext在磁盘上维护一个全局的contexts/知识库目录。你可以在这个库中创建不同的“文件夹Folders”来分类管理知识例如“前端最佳实践”、“微服务架构设计”、“AWS运维坑点”等。每个文件夹里可以存放多个Markdown文档。OpenContext的核心命令如oc doc create都围绕这个库进行操作。同时它具备“项目感知”能力。当你在某个Git仓库下运行OpenContext命令时它能将当前项目路径与知识库中的相关内容关联起来。例如通过oc context manifest命令可以为指定文件夹生成一个文件清单AI助手读取这个清单就能快速了解这个上下文包含哪些关键文档从而决定加载哪些。这种“全局库项目关联”的设计既保证了知识的集中管理和复用又保持了与具体项目工作流的紧密结合。3. 详细安装与初始化配置OpenContext提供了多种使用路径你可以从最简单的CLI开始也可以直接使用功能完整的桌面应用。下面我会详细拆解每一步并解释背后的原理和注意事项。3.1 环境准备与CLI安装OpenContext基于Node.js开发因此首先需要确保你的系统已安装Node.js版本建议在16以上和npm。打开终端执行全局安装命令npm install -g aicontextlab/cli这个命令会从npm仓库下载并安装OpenContext的命令行工具oc。-g参数代表全局安装这样你才能在系统的任何路径下直接使用oc命令。注意在某些系统如某些Linux发行版或使用特定Node版本管理器时下全局安装可能需要sudo权限sudo npm install -g ...。如果你使用nvm或fnm管理Node版本则通常不需要。如果安装后提示“command not found”请检查你的Node.js的全局bin目录是否已添加到系统的PATH环境变量中。安装完成后运行oc --version验证是否安装成功。你应该能看到版本号输出。3.2 关键一步执行oc init初始化安装CLI只是第一步让OpenContext与你的AI助手联动起来关键在初始化。进入你经常进行编码工作的任意项目目录或者就在你的home目录运行oc init这个命令会启动一个交互式向导它是整个工具链设置的核心。oc init具体做了什么创建全局配置与存储它会在你的用户主目录~下创建OpenContext的配置文件和全局contexts/知识库目录。所有你的知识文档都将存储在这里。探测并配置集成工具它会自动检测你系统上安装了哪些支持的AI编程工具Cursor、Claude Code、Codex。生成技能与命令对于检测到的每个工具它会在对应的用户配置目录下创建OpenContext的技能文件和斜杠命令文件。对于Cursor技能文件位于~/.cursor/skills/opencontext-*/SKILL.md命令文件位于~/.cursor/commands/。对于Claude Code路径类似通常在~/.claude/下但会尊重$CLAUDE_CONFIG_DIR环境变量。对于Codex路径在~/.codex/skills/和~/.codex/commands/或$CODEX_HOME指向的目录。配置MCP服务器它会在上述工具的MCP配置文件中如~/.cursor/mcp.json添加OpenContext的MCP服务器配置。这样这些工具在启动时就会自动连接到你的OpenContext知识库。在初始化过程中命令行会提示你选择要为哪些工具安装集成默认是全选。你可以根据实际情况按需选择。实操心得即使你暂时只使用一种工具我也建议在oc init时保持默认全选。这能保证配置的完整性未来切换或试用其他工具时会无缝衔接。整个过程是幂等的重复运行只会更新配置不会造成冲突。3.3 非交互式初始化与工具选择如果你需要在脚本中或偏好非交互式设置oc init也提供了参数# 为指定工具安装集成 oc init --tools cursor,claude,codex # 排除特定工具例如不配置Claude Code oc init --no-claude这在自动化部署或Docker环境初始化时非常有用。3.4 桌面应用与Web UI的获取对于偏好图形界面的用户OpenContext提供了两种GUI选择桌面应用推荐 前往项目的 GitHub Releases 页面下载对应你操作系统macOS, Windows, Linux的安装包。桌面应用基于Tauri构建提供了原生的文件管理、搜索、编辑体验功能最完整。Web UI 如果你不想安装任何东西可以直接使用CLI启动本地Web UI。oc ui执行后它会启动一个本地服务器并通常在浏览器中自动打开http://localhost:8080具体端口请查看命令行输出。这个Web UI提供了完整的知识库浏览、搜索和编辑功能适合快速查看或轻量编辑。如何选择日常深度使用、频繁管理知识选择桌面应用。其性能、与系统集成的能力如全局快捷键、更好的文件拖放支持都更优。临时查看、服务器环境或快速演示使用oc ui启动Web UI。它无需安装随时随地可用。4. 核心工作流与命令详解安装配置好后我们来深入核心工作流如何将日常开发中的点滴知识沉淀下来并在需要时让AI助手精准调用。4.1 知识沉淀创建文件夹与文档知识库需要良好的组织结构。OpenContext使用“文件夹(Folder)”作为顶层分类里面包含具体的“文档(Doc)”。创建文件夹假设你想创建一个关于“系统设计”的知识分类。oc folder create system-design -d 关于高并发、可扩展系统架构的设计模式、原则与案例oc folder create是创建命令。system-design是文件夹名称也是其在contexts/目录下的子目录名。-d参数用于添加描述这个描述对于后续AI助手理解这个文件夹的用途非常有帮助。创建文档接着在“system-design”文件夹下创建一篇关于数据库选型的文档。oc doc create system-design database-selection.md -d MySQL vs PostgreSQL vs 云原生数据库的选型考量与性能对比oc doc create是创建文档命令。system-design指定了目标文件夹。database-selection.md是文档文件名必须以.md结尾。-d参数同样是描述。执行后OpenContext会在~/contexts/system-design/目录下创建database-selection.md文件并用你提供的描述生成一个基本的文件头。之后你可以用任何你喜欢的Markdown编辑器如VS Code, Obsidian或OpenContext自带的桌面/Web UI来编辑这份文档。查看结构使用以下命令可以随时查看你的知识库结构。# 列出所有文件夹 oc folder ls # 列出某个文件夹下的所有文档 oc doc ls system-design4.2 核心魔法为AI生成上下文清单Manifest这是OpenContext区别于普通笔记软件的关键功能。oc context manifest命令会为一个指定的文件夹生成一个结构化的清单文件通常是manifest.json或manifest.txt。oc context manifest system-design这个清单文件包含了该文件夹下所有文档的标题、描述和路径摘要。它的核心作用是供AI助手快速“预览”这个上下文包。当AI助手需要加载“system-design”相关的背景知识时它不需要立即读取所有Markdown文件的全部内容那可能很长且消耗大量token而是先读取这个轻量的清单根据清单中的描述智能地决定当前任务需要具体加载哪几篇文档的详细内容。实操要点你应该为每个逻辑上独立的知识单元如一个项目、一个技术栈、一个业务领域创建单独的文件夹并定期运行oc context manifest更新清单。这能极大提升AI助手加载上下文的效率和准确性。4.3 知识检索精准搜索当你的知识库积累到上百篇文档后靠记忆查找就不现实了。OpenContext提供了全文搜索功能。oc search 数据库连接池配置优化搜索命令会扫描所有文档的标题、描述和正文内容返回匹配度最高的结果列表每条结果会显示文档路径和包含搜索关键词的片段。搜索技巧搜索词尽量具体如“React useEffect 内存泄漏”比“React 问题”效果更好。目前搜索是基于文本的模糊匹配未来版本可能会引入更复杂的向量搜索。4.4 在AI助手中使用斜杠命令与技能初始化成功后你的Cursor或Claude Code编辑器里就会多出几个神奇的斜杠命令。这是最直接的交互方式。典型工作流开始新任务前在聊天框中输入/opencontext-context。助手会主动询问或自动识别当前项目然后从你的知识库中加载最相关的背景文档基于项目路径和文件夹关联性。这相当于在任务开始前给助手做了一次“项目交接”。编码遇到问题输入/opencontext-search 异步任务队列快速查找之前总结过的关于Celery或BullMQ的实践笔记。解决了一个新问题输入/opencontext-iterate助手会引导你将刚刚解决问题的思路、方案和代码片段总结成一篇新的知识文档并保存到合适的文件夹中。这就是“持久化”环节。创建新知识直接输入/opencontext-create助手会帮你起草一篇新文档的结构和内容。背后的技能调用 当你使用这些斜杠命令时编辑器背后是在调用OpenContext通过oc init安装的技能。这些技能定义了AI助手可以执行的操作。在Cursor的“Composer”模式或Claude Code的“Command”模式下你甚至可以看到AI助手主动建议使用OpenContext技能来获取信息的场景。5. 与不同AI编程工具的深度集成指南虽然OpenContext支持多种工具但集成细节和最佳实践略有不同。这里分别详细说明。5.1 与 Cursor 的集成Cursor 是目前对OpenContext集成支持最完善、体验最流畅的编辑器之一。配置验证 初始化后检查~/.cursor/mcp.json文件应该包含类似以下配置{ mcpServers: { opencontext: { command: npx, args: [-y, aicontextlab/cli, mcp], env: {} } } }这表示Cursor已正确配置了OpenContext的MCP服务器。使用体验自动上下文加载在Cursor的AI聊天界面当你提到一个概念比如“我们之前讨论过的认证方案”Cursor的Agent有时会主动通过MCP查询OpenContext知识库寻找相关信息并注入上下文。斜杠命令在聊天输入框直接键入/opencontext后按Tab会列出所有可用的子命令非常方便。技能面板在Cursor的设置中你可以看到“Skills”部分确认opencontext相关的技能已启用。5.2 与 Claude Code 的集成Claude Code通常指Claude for VS Code或Cursor中的Claude模型的集成方式类似但配置路径可能因版本而异。环境变量Claude Code可能使用$CLAUDE_CONFIG_DIR环境变量来指定配置目录。oc init会智能地处理这一点。如果初始化后斜杠命令不生效可以手动检查~/.claude/commands/目录下是否存在opencontext-*.js文件。使用注意Claude Code对斜杠命令的响应可能不如Cursor原生集成那么“主动”。更多时候需要你显式地调用/opencontext-search或/opencontext-context命令。但其通过MCP获取上下文的能力是稳定的。5.3 与 Codex 及其他支持MCP的Agent集成OpenContext本质上是一个标准的MCP服务器。这意味着任何支持MCP协议的客户端或AI Agent都可以连接并使用它。通用MCP连接 如果你使用其他支持MCP的工具如某些自定义的AI Agent框架你可以手动启动OpenContext的MCP服务器并配置连接。启动服务器oc mcp。这个命令会启动一个MCP服务器默认在某个端口如3000监听。在你的AI Agent配置中添加MCP服务器地址为http://localhost:3000或指定的端口。配置完成后你的Agent就能调用opencontext_search,opencontext_list_folders等工具函数了。这种开放性使得OpenContext可以成为你个人AI工作流中的一个通用知识枢纽。6. 高级用法、问题排查与维护6.1 知识库的维护与同步你的~/contexts/目录就是一个普通的文件夹里面是Markdown文件。这意味着你可以使用Git进行版本控制将整个contexts目录初始化为一个Git仓库推送到GitHub或GitLab私有库实现知识库的备份、版本历史和跨设备同步。使用云盘同步用Dropbox、iCloud Drive或OneDrive同步contexts文件夹实现多台电脑间的知识库同步。注意如果多设备同时编辑需注意文件冲突问题。建议以Git为主流方案因为它能更好地处理合并冲突。6.2 桌面应用与CLI的协作桌面应用和CLI操作的是同一个知识库~/contexts/。你可以混合使用用桌面应用进行可视化的文档管理、批量操作和富文本编辑。用CLI在终端中快速搜索、创建文档或将其集成到自动化脚本中。 例如你可以写一个脚本在每天下班时自动运行oc search 今天完成来查找当天的笔记。6.3 常见问题排查FAQ1. 运行oc init后斜杠命令在编辑器里没出现首先确认编辑器重启安装技能/命令后必须完全退出并重新启动Cursor/Claude Code。检查安装路径确认oc init输出的路径确实存在于你的系统中。特别是如果你使用了自定义的安装目录或版本管理器。查看编辑器日志Cursor和Claude Code通常有开发者控制台或日志文件里面可能会有加载技能失败的报错信息。手动运行诊断可以尝试手动运行oc init --tools cursor来单独为Cursor重新安装。2. 搜索 (oc search) 结果不准确或搜不到确保你的文档是纯文本Markdown格式。如果包含大量图片、二进制内容或特殊格式可能无法被正确索引。搜索是实时进行的无需重建索引。但如果刚创建了大量新文档可以尝试重启一下OpenContext的桌面应用或确保没有进程锁定了文件。检查搜索关键词是否拼写正确或尝试更通用/更具体的关键词。3. MCP服务器连接失败确保oc mcp命令可以正常运行并且没有端口冲突。在编辑器的MCP配置中检查命令路径。npx -y aicontextlab/cli mcp要求系统能访问到全局安装的npx和aicontextlab/cli包。如果遇到问题可以尝试将命令改为绝对路径例如/usr/local/bin/npx -y aicontextlab/cli mcp路径需根据你的实际安装位置调整。4. 如何卸载或清理OpenContext移除CLInpm uninstall -g aicontextlab/cli移除知识库可选手动删除~/contexts/文件夹。移除编辑器集成手动删除以下目录中的OpenContext相关文件~/.cursor/commands/opencontext-*~/.cursor/skills/opencontext-*~/.cursor/mcp.json中对应的配置块。同理清理~/.claude/和~/.codex/下的对应文件。6.4 性能优化与最佳实践文档结构清晰在Markdown文档开头使用清晰的标题和元描述由oc doc create自动生成这有助于AI助手和搜索功能更好地理解文档内容。合理划分文件夹不要把所有文档扔进一个文件夹。按项目、技术领域、团队等维度细分。这能让oc context manifest生成的清单更有价值AI助手加载上下文也更精准。定期使用“迭代”命令养成使用/opencontext-iterate的习惯。在解决一个复杂问题或完成一个功能模块后花几分钟让助手帮你总结将隐性知识显性化、结构化地保存下来。这是知识库保持活力的关键。清单Manifest是桥梁把oc context manifest folder视为你与AI助手之间的“API文档”。为每个重要的文件夹维护一个最新的、描述准确的清单。7. 开发与贡献从使用者到构建者OpenContext本身是开源项目如果你对其功能有更多想法或者遇到了Bug可以参与到项目中。本地开发环境搭建git clone https://github.com/0xranx/OpenContext.git cd OpenContext npm install桌面应用开发运行npm run tauri:dev启动Tauri的开发模式会打开一个带热重载的桌面窗口。Web UI开发运行npm run ui:dev启动Vite开发服务器通常访问http://localhost:5173。CLI开发核心CLI逻辑在src/cli/目录下。你可以直接修改后在项目根目录通过node ./bin/oc.js command进行测试。技术栈概览前端Web UI 桌面应用界面基于现代前端框架如React/Vue/Svelte具体需查看项目源码使用Tauri构建桌面端。后端CLI MCP服务器Node.js处理文件系统操作、搜索逻辑和MCP协议通信。MCP协议实现了标准MCP服务器这是与AI工具集成的核心。贡献建议在提交Issue或PR前先查阅现有的Issues和Pull Requests。对于新功能建议详细描述使用场景和期望的行为。Bug报告请附上复现步骤、环境信息Node版本、操作系统、使用的AI工具版本和错误日志。OpenContext代表了一种务实而强大的AI工具使用范式不追求替换而是增强。它巧妙地在开发者已有的、高效的AI编程助手工作流中嵌入了一个持久化、可操作的知识层。通过技能优先的设计和MCP等开放协议它降低了使用门槛让“让AI记住上下文”从一个概念变成了几个简单的斜杠命令。随着知识库的积累你会发现你与AI助手的协作效率不再是简单的线性增长而是能逐渐摆脱重复解释的泥潭向着真正意义上的“结对编程”伙伴迈进。开始使用它最重要的第一步就是运行oc init然后尝试在下一个开发任务中有意识地使用/opencontext-context和/opencontext-iterate亲身感受那种“上下文不再丢失”的流畅感。