1. 项目概述一个由你的AI工具驱动的个人知识维基如果你和我一样每天在Claude Code或者Cursor里泡着同时又在Obsidian、Notion或者一堆Markdown文件里零散地记录着各种想法、技术文章链接和项目笔记那你一定懂那种知识碎片化的痛苦。找东西靠记忆整理东西靠毅力最后往往不了了之让很多有价值的思考沉淀不下来。最近一个名为autopedia的开源项目彻底改变了我的工作流。它的核心理念非常吸引人让你正在使用的AI工具比如Claude Code、Cursor成为你个人知识库的“大脑”和维护者。简单来说autopedia是一个运行在你本地的、基于MCPModel Context Protocol协议的个人知识维基系统。它本身不调用任何LLM API没有独立的客户端也不需要你额外管理API密钥。它的全部“智能”都来源于你已经打开并正在对话的那个AI助手。你通过命令行或直接告诉AI“帮我记下这个”autopedia负责存储和结构化而你的AI工具则负责理解、关联和整理这些信息最终生成一个互联的、可查询的、类似安德烈·卡帕西Andrej Karpathy所倡导的那种知识网络。这相当于给你的AI工具装上了一块永久性的、专属的“记忆硬盘”让它能基于你过往所有的研究和笔记来回答问题而不是仅仅依赖其训练数据。2. 核心设计理念与工作原理解析2.1 灵感溯源Karpathy式维基的三项核心操作autopedia的设计哲学直接源于AI研究员安德烈·卡帕西关于个人知识管理的一条推文。他提出一个理想的、由AI维护的知识库应围绕三个核心操作构建摄取Ingest这是知识的输入阶段。无论是你随手记下的一条文本笔记、收藏的一个网页链接、读完的一篇PDF论文还是整个项目代码库autopedia都能将其作为“源材料”保存起来。关键点在于它只是暂存并不立即处理等待AI来进行深度加工。查询Query这是知识的输出与应用阶段。当你向AI提问时AI可以通过autopedia查询你的整个知识库找到相关的笔记和资料并基于这些你亲自提供或认可的材料来生成回答。这确保了答案的 grounded有据可依和个性化极大提升了信息的可信度和相关性。整理Lint这是知识的维护与优化阶段。AI可以主动检查知识库的健康状况例如发现那些没有被任何其他页面引用的“孤儿页面”找出内容可能已经过时的页面检测断开的链接甚至挑战那些你记录中看似肯定但缺乏依据的断言从而促使知识库不断自我完善和迭代。autopedia完整地实现了这三个操作并将其封装成一套标准的MCP工具供AI工具调用。这使得AI从一个被动的问答机器转变为你个人知识体系的主动管理者和协作者。2.2 技术基石MCP模型上下文协议的角色MCP是连接autopedia与你的AI工具的关键桥梁。你可以把它理解为一套标准化的“插座”和“插头”协议。autopedia作为一个MCP服务器启动后会在本地提供一个服务这个服务声明“我这里有以下能力工具和数据资源可供使用”。你的AI工具如Claude Code、Cursor作为MCP客户端在启动时会读取配置文件发现并连接上autopedia服务。一旦连接建立AI工具就“知道”了autopedia的存在并获得了调用其工具的权限。这意味着无需切换界面你不需要离开熟悉的IDE或AI聊天界面。无缝交互你可以用自然语言对AI说“同步我的维基”或“我记得之前研究过GPU价格结论是什么”AI在背后会自动调用autopedia的apply_wiki_ops或search工具来完成工作。零API开销所有的思考、分析和文本生成工作都由你本地运行的AI模型完成autopedia只负责提供结构化的数据和存储。这既保护了隐私也避免了额外的LLM API调用成本。2.3 架构与安全设计极简与边界守护autopedia的代码架构体现了“做一件事并做好”的Unix哲学。它没有使用臃肿的Web框架如Express没有引入外部数据库其运行时依赖仅有7个npm包核心逻辑集中在几个清晰的模块中src/wiki.ts知识库的引擎。处理所有文件读写强制执行“神圣边界”——AI只能写入特定的wiki/目录绝不能修改用户的原始源文件存放在sources/。它还负责构建和维护页面间的维基链接图实现lint和scan功能。src/mcp.ts定义了9个MCP工具和3个MCP资源是与AI交互的协议层。src/cli.ts提供完整的命令行界面从初始化到添加内容、搜索、状态查看一应俱全。其中对代码仓库的扫描器Repo scanner特别智能它能识别项目文件类型并为其分配“角色”如配置文件、源代码、文档然后打包成一份结构化的架构概述。src/dashboard.ts一个本地渲染的HTML仪表盘用于可视化浏览知识图谱、查看反向链接等。在安全方面项目考虑得非常周全路径遍历防护严格限制文件访问范围防止AI意外或恶意操作到系统其他文件。SSRF服务器端请求伪造防护阻止对本地网络、私有IP或云服务元数据端点的访问这在处理用户提交的URL时至关重要。XSS跨站脚本防护在仪表盘中渲染任何用户内容或维基内容时都会进行HTML转义确保没有注入风险。无密钥设计最大的安全特性是autopedia本身不持有任何LLM API密钥所有智能行为都委托给你信任的、已在你本地环境中通过安全认证的AI工具。3. 从零开始完整安装与配置指南3.1 环境准备与基础安装开始之前请确保你的系统满足以下条件Node.js 20这是硬性要求因为项目可能使用了较新的Node.js API。你可以通过node -v命令检查版本。如果版本过低建议使用nvmNode Version Manager来安装和管理多个Node.js版本。一个支持MCP的AI工具目前最主流的选择是Claude CodeCursor的内置Claude模式或Cursor本身。确保你的AI工具已正确安装并可以正常工作。安装autopedia本身非常简单通过npm全局安装即可这样你可以在任何终端位置使用autopedia命令npm install -g autopedia注意在某些系统如某些Linux发行版或使用特定Node版本管理器时下全局安装可能需要sudo权限。如果遇到权限错误可以尝试使用sudo npm install -g autopedia或者更推荐的方式是配置npm的全局安装目录到用户空间避免使用sudo。3.2 初始化你的知识库安装完成后第一步是初始化autopedia的工作目录。运行以下命令autopedia init这个命令会在你的用户主目录下创建一个名为.autopedia/的隐藏文件夹其内部结构如下~/.autopedia/ ├── wiki/ # 【核心】AI为你生成和维护的维基页面Markdown格式 ├── sources/ # 你添加的原始材料URL内容、文本笔记、上传的文件 ├── ops/ # 操作审计日志、指标数据和待处理队列 └── schema/ # 你的个人资料和知识库规则由AI在首次交互时生成这个结构清晰地区分了“原材料”sources和“加工成品”wiki并且通过ops/目录记录所有操作保证了过程的透明性和可追溯性。3.3 连接你的AI工具一次性配置这是最关键的一步让你的AI工具“认识”autopedia。你需要修改AI工具的MCP配置文件。对于Claude Code / Cursor配置文件通常位于~/.cursor/mcp.json。如果文件不存在创建它。如果已存在在mcpServers对象中添加新的配置。用你喜欢的文本编辑器如VSCode、Vim打开或创建该文件code ~/.cursor/mcp.json # 或 vim ~/.cursor/mcp.json将以下配置添加到文件中。如果mcpServers已存在其他配置请确保以逗号分隔保持JSON格式正确。{ mcpServers: { autopedia: { command: autopedia, args: [serve] } } }配置解析command: autopedia告诉AI工具要启动一个名为autopedia的命令行程序。args: [serve]传递给该命令的参数是serve即启动MCP服务器模式。重要提示保存配置文件后你必须完全重启你的AI工具Cursor或Claude Code。MCP配置通常在启动时加载不重启无法生效。3.4 验证连接与首次交互检查状态打开一个新的终端运行以下命令确保autopedia已就绪。autopedia status你应该会看到类似这样的输出表明维基已初始化队列为空Wiki pages: 1, Queued: 0初始的那个维基页面很可能是你的个人资料页。启动AI工具并触发引导完全重启你的Cursor或Claude Code。新建一个聊天会话。在首次连接时autopedia会通过AI工具对你进行一次简短的“采访”大约30秒。AI会问你几个关于你的身份、专业领域和兴趣爱好的问题例如“你主要从事什么领域的工作”、“你通常关注哪些类型的知识”。你的回答会被用来生成schema/下的个人资料这有助于AI在未来更好地理解和归类你添加的知识。这个引导过程只会发生一次。完成后autopedia就会进入静默的“待命”状态不会干扰你的正常对话直到你需要它。4. 核心工作流实战构建你的动态知识库4.1 知识摄取多种方式添加“源材料”autopedia提供了极其灵活的内容添加方式你可以从任何地方进行“脑力倾倒”Braindump。通过命令行添加最通用这是最直接的方法适合任何你能用命令行访问的场景。# 添加一条临时想到的文本笔记 autopedia add RTX 4090的浮点运算能力在特定模型训练中比RTX 3090提升了约1.7倍但功耗墙需要注意。 # 添加一个网页链接autopedia会抓取其中的文本内容 autopedia add https://arxiv.org/abs/2307.xxxxx # 添加本地的一个Markdown文件 autopedia add ~/projects/notes/system-design.md # 添加整个文件夹会自动遍历文件夹内所有支持的文件 autopedia add ~/Downloads/research_papers/ # 添加一个Git代码仓库autopedia会识别.git目录或使用--repo参数显式指定 autopedia add ~/code/my-llm-project/ autopedia add --repo ~/code/my-llm-project/ # 显式启用代码仓库分析模式当你执行add命令后这些内容会被存入sources/目录并进入ops/queue等待处理。此时AI还没有开始整理它们。通过AI对话添加最自然在已经连接autopedia的AI聊天窗口里你可以直接说“帮我把这个想法记下来项目下一步可以考虑引入向量数据库来做长期记忆。” AI在背后会调用add_source工具效果与命令行添加一致。通过Obsidian集成添加可视化拖拽如果你习惯使用Obsidian可以将~/.autopedia/文件夹直接作为Obsidian的仓库Vault打开。此时整个维基的页面wiki/和源文件sources/都会出现在Obsidian中。你可以直接在Obsidian里新建或编辑wiki/下的页面但更推荐让AI来维护。更强大的工作流是将任何文件直接拖拽到Obsidian的文件管理器中实际上是放入了~/.autopedia/的某个子目录。然后在终端运行autopedia scan命令它会自动检测这些新增的文件并将它们加入处理队列。4.2 知识处理触发AI进行整理与合成添加了材料只是第一步接下来需要让AI“消化”它们。在你的AI工具聊天界面中只需简单地说“同步我的维基。” 或 “处理一下队列里的内容。”AI会调用apply_wiki_ops工具开始处理队列中的所有源材料。你会看到AI回复的处理过程例如处理 1/3: gpu-performance-note → 已更新 hardware-benchmarks.md 处理 2/3: arxiv.org/abs/2307.xxxxx → 已创建 paper-summaries.md 处理 3/3: system-design.md → 已合并至 software-architecture.md 完成。创建了1个新页面更新了2个页面。在这个过程中AI会做什么阅读与理解AI会仔细阅读你添加的源材料。关联与整合AI会在现有的维基页面中寻找相关主题。如果找到它会将新信息合并、补充到已有页面中并可能调整页面结构。如果是一个全新主题它会创建一个新的维基页面。创建智能链接AI会自动在页面中插入[[wikilinks]]维基链接。例如当它在“hardware-benchmarks.md”中提到“RTX 4090”时如果存在一个名为“nvidia-gpus.md”的页面它可能会创建链接[[RTX 4090]]点击即可跳转。这构成了知识图谱的基础。格式化与总结AI会将零散的信息整理成结构清晰、语言流畅的Markdown文档。4.3 知识查询向你的“第二大脑”提问这是整个系统价值最大化的时刻。当你在进行编码、写作或研究需要参考过往的笔记时不再需要手动搜索文件。直接在AI聊天框中提问问题必须基于你已录入的知识“我之前关于微服务熔断器降级策略的研究有哪些结论” “帮我找出所有提到‘RAG pipeline优化’的笔记。” “我记得分析过几个向量数据库的对比它们的读写延迟数据分别是多少”AI会调用search或read_page工具在你的wiki/中查找相关信息并直接引用相关的维基页面内容来回答你。回答的开头或结尾通常会注明“根据你的知识库...”这明确区分了来自通用训练数据的知识和来自你个人积累的知识。4.4 知识维护使用Lint保持库健康随着时间的推移一些页面可能不再被引用一些外部链接可能失效或者早期的结论可能需要更新。你可以定期比如每周让AI帮你做一次“体检”。对AI说“检查一下我的维基健康状况。” 或直接运行命令行autopedia lint。AI会执行lint工具并可能生成一份报告例如找到 2 个孤儿页面这些页面没有其他页面链接到它们容易被遗忘。AI可能会建议你将其关联到其他主题或询问是否存档。找到 1 个可能过时的页面某个页面中引用的技术版本号已经很旧。AI会提示你查看是否需要更新。挑战 1 个高置信度断言AI发现某个页面中有一个非常肯定的结论如“方案A永远优于方案B”但缺乏足够的支撑材料。它会提出问题促使你补充依据或修正表述。你可以根据这些提示通过添加新资料或直接编辑维基页面来进行维护。5. 高级功能与生态集成5.1 本地仪表盘可视化你的知识图谱运行autopedia view命令会在你的默认浏览器中打开一个本地网页通常是http://localhost:port。这个仪表盘提供了图形化的管理界面维基索引以整洁的列表形式展示所有页面并渲染Markdown预览。知识图谱一个力导向图直观展示所有页面及其之间的[[wikilinks]]关系。你可以清晰地看到哪些是核心枢纽页面哪些是边缘主题。反向链接点击任何一个页面都能看到所有链接到该页面的其他页面。这对于理解一个概念的引用上下文至关重要。源文件浏览查看sources/目录下的原始材料标题通常由内容自动生成。状态总览快速查看页面总数、待处理队列数量、未被跟踪的文件等。5.2 与Obsidian的深度共生autopedia与Obsidian的兼容性不是简单的文件兼容而是近乎原生的体验。双向链接与图谱由于autopedia使用标准的[[Page Name]]语法在Obsidian中打开~/.autopedia/wiki/文件夹所有页面之间的链接和全局图谱都能完美工作。反向链接面板Obsidian的反向链接面板会自动显示autopedia生成的链接关系。混合编辑模式你可以选择完全由AI维护推荐也可以手动在Obsidian中编辑wiki/下的页面。下次AI同步时它会读取你的修改并将其纳入知识体系。但请注意手动大量修改可能会与AI的整理逻辑产生冲突建议以AI为主手动微调为辅。强大的捕获工作流结合autopedia scan命令你可以实现“拖拽文件到Obsidian → 自动排队 → AI整理”的无缝流水线。5.3 代码仓库分析为项目生成架构手册对于开发者autopedia add --repo path功能非常强大。它不仅仅是添加代码文件而是会智能扫描遍历项目目录识别文件类型.py,.js,.md,Dockerfile,package.json等。角色评分根据文件路径、名称和内容判断其在项目中的角色如“核心模块”、“配置”、“测试”、“文档”。生成架构概述将所有信息打包创建一份结构化的项目概述文档作为知识库的一个“源”。当AI处理这个源时它会生成一个易于理解的、高层次的项目维基页面包含项目目的、核心模块、依赖关系、启动方式等。这对于理解复杂项目或为新成员提供 onboarding 材料极其有用。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些典型问题。以下是我踩过坑后总结的排查清单问题现象可能原因解决方案运行autopedia命令提示“命令未找到”1. 全局安装失败或路径未加入系统PATH。2. 使用nvm等版本管理器新终端未生效。1. 尝试用npx autopedia代替。2. 检查Node.js安装路径或将npm全局bin目录加入PATHexport PATH$PATH:$(npm config get prefix)/bin写入shell配置文件。3. 重启终端或重新加载shell配置如source ~/.zshrc。AI工具Cursor启动后没有发现autopedia功能1. MCP配置文件 (~/.cursor/mcp.json) 格式错误或路径不对。2. AI工具未重启。3. autopedia的MCP服务器未启动。1. 使用JSON验证工具检查mcp.json格式。2.务必完全关闭并重启Cursor/Claude Code。3. 在终端运行autopedia status确保服务正常。理论上配置正确后AI工具会自动启动服务器但也可以手动在另一个终端运行autopedia serve保持后台运行。对AI说“同步维基”AI回复“不知道这个命令”或没反应1. MCP连接未成功建立。2. AI工具可能未启用或未正确加载MCP功能。1. 在AI聊天界面尝试输入/mcp或检查其设置中是否有MCP服务器列表看autopedia是否在其中并显示为已连接。2. 确认你使用的AI模型/模式支持MCP工具调用Claude Code和Cursor的Claude模式通常都支持。autopedia add URL后AI同步时提示抓取失败1. 网络问题。2. 目标网站有反爬机制。3. URL格式不正确或需要认证。1. 检查网络连接。2. 对于复杂页面可以尝试先将网页另存为HTML或PDF文件然后用autopedia add file添加本地文件。3. autopedia出于安全考虑会屏蔽对本地网络等地址的访问这是正常行为。Obsidian中打开维基图谱不显示或链接断裂1. Obsidian打开的仓库路径不是~/.autopedia/wiki/而是其父目录。2. 维基链接的页面名与实际文件名大小写或空格不一致。1. 确保在Obsidian中直接打开~/.autopedia/wiki/文件夹作为仓库。2. autopedia和AI生成的链接通常是kebab-case如my-page-name.md手动创建页面时最好遵循此约定。Obsidian的“更新内部链接”功能可以修复大小写问题。知识库文件越来越多如何备份或迁移需要备份整个~/.autopedia/目录。直接复制整个~/.autopedia/文件夹到备份位置即可。恢复时放回原处重新运行autopedia init可能会覆盖所以直接替换文件夹即可。所有数据都是纯文本文件兼容性极好。个人实操心得启动即访谈第一次连接时的访谈很重要认真回答有助于AI建立更准确的个人画像后续的内容归类会更精准。“先倾倒后整理”不要担心添加的内容杂乱。养成随时用autopedia add或直接对AI说话记录灵感的习惯。定期比如每天下班前统一说一次“同步维基”让AI做整理工作。这符合“收件箱”处理的工作流。信任AI但保持审查AI的整理能力很强但并非完美。特别是对于高度专业或争议性话题在AI合成信息后最好快速浏览一下生成的维基页面确保关键事实和结论无误。lint功能发现的“高置信度断言”就是很好的审查切入点。代码库分析的妙用在开始阅读一个开源项目或接手一个老项目时第一时间用autopedia add --repo把它加进去。让AI生成的架构摘要能帮你快速建立全局认知效率远超自己漫无目的地看代码。 基于MCP协议构建AI驱动的个人知识维基：autopedia实践指南
1. 项目概述一个由你的AI工具驱动的个人知识维基如果你和我一样每天在Claude Code或者Cursor里泡着同时又在Obsidian、Notion或者一堆Markdown文件里零散地记录着各种想法、技术文章链接和项目笔记那你一定懂那种知识碎片化的痛苦。找东西靠记忆整理东西靠毅力最后往往不了了之让很多有价值的思考沉淀不下来。最近一个名为autopedia的开源项目彻底改变了我的工作流。它的核心理念非常吸引人让你正在使用的AI工具比如Claude Code、Cursor成为你个人知识库的“大脑”和维护者。简单来说autopedia是一个运行在你本地的、基于MCPModel Context Protocol协议的个人知识维基系统。它本身不调用任何LLM API没有独立的客户端也不需要你额外管理API密钥。它的全部“智能”都来源于你已经打开并正在对话的那个AI助手。你通过命令行或直接告诉AI“帮我记下这个”autopedia负责存储和结构化而你的AI工具则负责理解、关联和整理这些信息最终生成一个互联的、可查询的、类似安德烈·卡帕西Andrej Karpathy所倡导的那种知识网络。这相当于给你的AI工具装上了一块永久性的、专属的“记忆硬盘”让它能基于你过往所有的研究和笔记来回答问题而不是仅仅依赖其训练数据。2. 核心设计理念与工作原理解析2.1 灵感溯源Karpathy式维基的三项核心操作autopedia的设计哲学直接源于AI研究员安德烈·卡帕西关于个人知识管理的一条推文。他提出一个理想的、由AI维护的知识库应围绕三个核心操作构建摄取Ingest这是知识的输入阶段。无论是你随手记下的一条文本笔记、收藏的一个网页链接、读完的一篇PDF论文还是整个项目代码库autopedia都能将其作为“源材料”保存起来。关键点在于它只是暂存并不立即处理等待AI来进行深度加工。查询Query这是知识的输出与应用阶段。当你向AI提问时AI可以通过autopedia查询你的整个知识库找到相关的笔记和资料并基于这些你亲自提供或认可的材料来生成回答。这确保了答案的 grounded有据可依和个性化极大提升了信息的可信度和相关性。整理Lint这是知识的维护与优化阶段。AI可以主动检查知识库的健康状况例如发现那些没有被任何其他页面引用的“孤儿页面”找出内容可能已经过时的页面检测断开的链接甚至挑战那些你记录中看似肯定但缺乏依据的断言从而促使知识库不断自我完善和迭代。autopedia完整地实现了这三个操作并将其封装成一套标准的MCP工具供AI工具调用。这使得AI从一个被动的问答机器转变为你个人知识体系的主动管理者和协作者。2.2 技术基石MCP模型上下文协议的角色MCP是连接autopedia与你的AI工具的关键桥梁。你可以把它理解为一套标准化的“插座”和“插头”协议。autopedia作为一个MCP服务器启动后会在本地提供一个服务这个服务声明“我这里有以下能力工具和数据资源可供使用”。你的AI工具如Claude Code、Cursor作为MCP客户端在启动时会读取配置文件发现并连接上autopedia服务。一旦连接建立AI工具就“知道”了autopedia的存在并获得了调用其工具的权限。这意味着无需切换界面你不需要离开熟悉的IDE或AI聊天界面。无缝交互你可以用自然语言对AI说“同步我的维基”或“我记得之前研究过GPU价格结论是什么”AI在背后会自动调用autopedia的apply_wiki_ops或search工具来完成工作。零API开销所有的思考、分析和文本生成工作都由你本地运行的AI模型完成autopedia只负责提供结构化的数据和存储。这既保护了隐私也避免了额外的LLM API调用成本。2.3 架构与安全设计极简与边界守护autopedia的代码架构体现了“做一件事并做好”的Unix哲学。它没有使用臃肿的Web框架如Express没有引入外部数据库其运行时依赖仅有7个npm包核心逻辑集中在几个清晰的模块中src/wiki.ts知识库的引擎。处理所有文件读写强制执行“神圣边界”——AI只能写入特定的wiki/目录绝不能修改用户的原始源文件存放在sources/。它还负责构建和维护页面间的维基链接图实现lint和scan功能。src/mcp.ts定义了9个MCP工具和3个MCP资源是与AI交互的协议层。src/cli.ts提供完整的命令行界面从初始化到添加内容、搜索、状态查看一应俱全。其中对代码仓库的扫描器Repo scanner特别智能它能识别项目文件类型并为其分配“角色”如配置文件、源代码、文档然后打包成一份结构化的架构概述。src/dashboard.ts一个本地渲染的HTML仪表盘用于可视化浏览知识图谱、查看反向链接等。在安全方面项目考虑得非常周全路径遍历防护严格限制文件访问范围防止AI意外或恶意操作到系统其他文件。SSRF服务器端请求伪造防护阻止对本地网络、私有IP或云服务元数据端点的访问这在处理用户提交的URL时至关重要。XSS跨站脚本防护在仪表盘中渲染任何用户内容或维基内容时都会进行HTML转义确保没有注入风险。无密钥设计最大的安全特性是autopedia本身不持有任何LLM API密钥所有智能行为都委托给你信任的、已在你本地环境中通过安全认证的AI工具。3. 从零开始完整安装与配置指南3.1 环境准备与基础安装开始之前请确保你的系统满足以下条件Node.js 20这是硬性要求因为项目可能使用了较新的Node.js API。你可以通过node -v命令检查版本。如果版本过低建议使用nvmNode Version Manager来安装和管理多个Node.js版本。一个支持MCP的AI工具目前最主流的选择是Claude CodeCursor的内置Claude模式或Cursor本身。确保你的AI工具已正确安装并可以正常工作。安装autopedia本身非常简单通过npm全局安装即可这样你可以在任何终端位置使用autopedia命令npm install -g autopedia注意在某些系统如某些Linux发行版或使用特定Node版本管理器时下全局安装可能需要sudo权限。如果遇到权限错误可以尝试使用sudo npm install -g autopedia或者更推荐的方式是配置npm的全局安装目录到用户空间避免使用sudo。3.2 初始化你的知识库安装完成后第一步是初始化autopedia的工作目录。运行以下命令autopedia init这个命令会在你的用户主目录下创建一个名为.autopedia/的隐藏文件夹其内部结构如下~/.autopedia/ ├── wiki/ # 【核心】AI为你生成和维护的维基页面Markdown格式 ├── sources/ # 你添加的原始材料URL内容、文本笔记、上传的文件 ├── ops/ # 操作审计日志、指标数据和待处理队列 └── schema/ # 你的个人资料和知识库规则由AI在首次交互时生成这个结构清晰地区分了“原材料”sources和“加工成品”wiki并且通过ops/目录记录所有操作保证了过程的透明性和可追溯性。3.3 连接你的AI工具一次性配置这是最关键的一步让你的AI工具“认识”autopedia。你需要修改AI工具的MCP配置文件。对于Claude Code / Cursor配置文件通常位于~/.cursor/mcp.json。如果文件不存在创建它。如果已存在在mcpServers对象中添加新的配置。用你喜欢的文本编辑器如VSCode、Vim打开或创建该文件code ~/.cursor/mcp.json # 或 vim ~/.cursor/mcp.json将以下配置添加到文件中。如果mcpServers已存在其他配置请确保以逗号分隔保持JSON格式正确。{ mcpServers: { autopedia: { command: autopedia, args: [serve] } } }配置解析command: autopedia告诉AI工具要启动一个名为autopedia的命令行程序。args: [serve]传递给该命令的参数是serve即启动MCP服务器模式。重要提示保存配置文件后你必须完全重启你的AI工具Cursor或Claude Code。MCP配置通常在启动时加载不重启无法生效。3.4 验证连接与首次交互检查状态打开一个新的终端运行以下命令确保autopedia已就绪。autopedia status你应该会看到类似这样的输出表明维基已初始化队列为空Wiki pages: 1, Queued: 0初始的那个维基页面很可能是你的个人资料页。启动AI工具并触发引导完全重启你的Cursor或Claude Code。新建一个聊天会话。在首次连接时autopedia会通过AI工具对你进行一次简短的“采访”大约30秒。AI会问你几个关于你的身份、专业领域和兴趣爱好的问题例如“你主要从事什么领域的工作”、“你通常关注哪些类型的知识”。你的回答会被用来生成schema/下的个人资料这有助于AI在未来更好地理解和归类你添加的知识。这个引导过程只会发生一次。完成后autopedia就会进入静默的“待命”状态不会干扰你的正常对话直到你需要它。4. 核心工作流实战构建你的动态知识库4.1 知识摄取多种方式添加“源材料”autopedia提供了极其灵活的内容添加方式你可以从任何地方进行“脑力倾倒”Braindump。通过命令行添加最通用这是最直接的方法适合任何你能用命令行访问的场景。# 添加一条临时想到的文本笔记 autopedia add RTX 4090的浮点运算能力在特定模型训练中比RTX 3090提升了约1.7倍但功耗墙需要注意。 # 添加一个网页链接autopedia会抓取其中的文本内容 autopedia add https://arxiv.org/abs/2307.xxxxx # 添加本地的一个Markdown文件 autopedia add ~/projects/notes/system-design.md # 添加整个文件夹会自动遍历文件夹内所有支持的文件 autopedia add ~/Downloads/research_papers/ # 添加一个Git代码仓库autopedia会识别.git目录或使用--repo参数显式指定 autopedia add ~/code/my-llm-project/ autopedia add --repo ~/code/my-llm-project/ # 显式启用代码仓库分析模式当你执行add命令后这些内容会被存入sources/目录并进入ops/queue等待处理。此时AI还没有开始整理它们。通过AI对话添加最自然在已经连接autopedia的AI聊天窗口里你可以直接说“帮我把这个想法记下来项目下一步可以考虑引入向量数据库来做长期记忆。” AI在背后会调用add_source工具效果与命令行添加一致。通过Obsidian集成添加可视化拖拽如果你习惯使用Obsidian可以将~/.autopedia/文件夹直接作为Obsidian的仓库Vault打开。此时整个维基的页面wiki/和源文件sources/都会出现在Obsidian中。你可以直接在Obsidian里新建或编辑wiki/下的页面但更推荐让AI来维护。更强大的工作流是将任何文件直接拖拽到Obsidian的文件管理器中实际上是放入了~/.autopedia/的某个子目录。然后在终端运行autopedia scan命令它会自动检测这些新增的文件并将它们加入处理队列。4.2 知识处理触发AI进行整理与合成添加了材料只是第一步接下来需要让AI“消化”它们。在你的AI工具聊天界面中只需简单地说“同步我的维基。” 或 “处理一下队列里的内容。”AI会调用apply_wiki_ops工具开始处理队列中的所有源材料。你会看到AI回复的处理过程例如处理 1/3: gpu-performance-note → 已更新 hardware-benchmarks.md 处理 2/3: arxiv.org/abs/2307.xxxxx → 已创建 paper-summaries.md 处理 3/3: system-design.md → 已合并至 software-architecture.md 完成。创建了1个新页面更新了2个页面。在这个过程中AI会做什么阅读与理解AI会仔细阅读你添加的源材料。关联与整合AI会在现有的维基页面中寻找相关主题。如果找到它会将新信息合并、补充到已有页面中并可能调整页面结构。如果是一个全新主题它会创建一个新的维基页面。创建智能链接AI会自动在页面中插入[[wikilinks]]维基链接。例如当它在“hardware-benchmarks.md”中提到“RTX 4090”时如果存在一个名为“nvidia-gpus.md”的页面它可能会创建链接[[RTX 4090]]点击即可跳转。这构成了知识图谱的基础。格式化与总结AI会将零散的信息整理成结构清晰、语言流畅的Markdown文档。4.3 知识查询向你的“第二大脑”提问这是整个系统价值最大化的时刻。当你在进行编码、写作或研究需要参考过往的笔记时不再需要手动搜索文件。直接在AI聊天框中提问问题必须基于你已录入的知识“我之前关于微服务熔断器降级策略的研究有哪些结论” “帮我找出所有提到‘RAG pipeline优化’的笔记。” “我记得分析过几个向量数据库的对比它们的读写延迟数据分别是多少”AI会调用search或read_page工具在你的wiki/中查找相关信息并直接引用相关的维基页面内容来回答你。回答的开头或结尾通常会注明“根据你的知识库...”这明确区分了来自通用训练数据的知识和来自你个人积累的知识。4.4 知识维护使用Lint保持库健康随着时间的推移一些页面可能不再被引用一些外部链接可能失效或者早期的结论可能需要更新。你可以定期比如每周让AI帮你做一次“体检”。对AI说“检查一下我的维基健康状况。” 或直接运行命令行autopedia lint。AI会执行lint工具并可能生成一份报告例如找到 2 个孤儿页面这些页面没有其他页面链接到它们容易被遗忘。AI可能会建议你将其关联到其他主题或询问是否存档。找到 1 个可能过时的页面某个页面中引用的技术版本号已经很旧。AI会提示你查看是否需要更新。挑战 1 个高置信度断言AI发现某个页面中有一个非常肯定的结论如“方案A永远优于方案B”但缺乏足够的支撑材料。它会提出问题促使你补充依据或修正表述。你可以根据这些提示通过添加新资料或直接编辑维基页面来进行维护。5. 高级功能与生态集成5.1 本地仪表盘可视化你的知识图谱运行autopedia view命令会在你的默认浏览器中打开一个本地网页通常是http://localhost:port。这个仪表盘提供了图形化的管理界面维基索引以整洁的列表形式展示所有页面并渲染Markdown预览。知识图谱一个力导向图直观展示所有页面及其之间的[[wikilinks]]关系。你可以清晰地看到哪些是核心枢纽页面哪些是边缘主题。反向链接点击任何一个页面都能看到所有链接到该页面的其他页面。这对于理解一个概念的引用上下文至关重要。源文件浏览查看sources/目录下的原始材料标题通常由内容自动生成。状态总览快速查看页面总数、待处理队列数量、未被跟踪的文件等。5.2 与Obsidian的深度共生autopedia与Obsidian的兼容性不是简单的文件兼容而是近乎原生的体验。双向链接与图谱由于autopedia使用标准的[[Page Name]]语法在Obsidian中打开~/.autopedia/wiki/文件夹所有页面之间的链接和全局图谱都能完美工作。反向链接面板Obsidian的反向链接面板会自动显示autopedia生成的链接关系。混合编辑模式你可以选择完全由AI维护推荐也可以手动在Obsidian中编辑wiki/下的页面。下次AI同步时它会读取你的修改并将其纳入知识体系。但请注意手动大量修改可能会与AI的整理逻辑产生冲突建议以AI为主手动微调为辅。强大的捕获工作流结合autopedia scan命令你可以实现“拖拽文件到Obsidian → 自动排队 → AI整理”的无缝流水线。5.3 代码仓库分析为项目生成架构手册对于开发者autopedia add --repo path功能非常强大。它不仅仅是添加代码文件而是会智能扫描遍历项目目录识别文件类型.py,.js,.md,Dockerfile,package.json等。角色评分根据文件路径、名称和内容判断其在项目中的角色如“核心模块”、“配置”、“测试”、“文档”。生成架构概述将所有信息打包创建一份结构化的项目概述文档作为知识库的一个“源”。当AI处理这个源时它会生成一个易于理解的、高层次的项目维基页面包含项目目的、核心模块、依赖关系、启动方式等。这对于理解复杂项目或为新成员提供 onboarding 材料极其有用。6. 常见问题与故障排查实录在实际使用中你可能会遇到一些典型问题。以下是我踩过坑后总结的排查清单问题现象可能原因解决方案运行autopedia命令提示“命令未找到”1. 全局安装失败或路径未加入系统PATH。2. 使用nvm等版本管理器新终端未生效。1. 尝试用npx autopedia代替。2. 检查Node.js安装路径或将npm全局bin目录加入PATHexport PATH$PATH:$(npm config get prefix)/bin写入shell配置文件。3. 重启终端或重新加载shell配置如source ~/.zshrc。AI工具Cursor启动后没有发现autopedia功能1. MCP配置文件 (~/.cursor/mcp.json) 格式错误或路径不对。2. AI工具未重启。3. autopedia的MCP服务器未启动。1. 使用JSON验证工具检查mcp.json格式。2.务必完全关闭并重启Cursor/Claude Code。3. 在终端运行autopedia status确保服务正常。理论上配置正确后AI工具会自动启动服务器但也可以手动在另一个终端运行autopedia serve保持后台运行。对AI说“同步维基”AI回复“不知道这个命令”或没反应1. MCP连接未成功建立。2. AI工具可能未启用或未正确加载MCP功能。1. 在AI聊天界面尝试输入/mcp或检查其设置中是否有MCP服务器列表看autopedia是否在其中并显示为已连接。2. 确认你使用的AI模型/模式支持MCP工具调用Claude Code和Cursor的Claude模式通常都支持。autopedia add URL后AI同步时提示抓取失败1. 网络问题。2. 目标网站有反爬机制。3. URL格式不正确或需要认证。1. 检查网络连接。2. 对于复杂页面可以尝试先将网页另存为HTML或PDF文件然后用autopedia add file添加本地文件。3. autopedia出于安全考虑会屏蔽对本地网络等地址的访问这是正常行为。Obsidian中打开维基图谱不显示或链接断裂1. Obsidian打开的仓库路径不是~/.autopedia/wiki/而是其父目录。2. 维基链接的页面名与实际文件名大小写或空格不一致。1. 确保在Obsidian中直接打开~/.autopedia/wiki/文件夹作为仓库。2. autopedia和AI生成的链接通常是kebab-case如my-page-name.md手动创建页面时最好遵循此约定。Obsidian的“更新内部链接”功能可以修复大小写问题。知识库文件越来越多如何备份或迁移需要备份整个~/.autopedia/目录。直接复制整个~/.autopedia/文件夹到备份位置即可。恢复时放回原处重新运行autopedia init可能会覆盖所以直接替换文件夹即可。所有数据都是纯文本文件兼容性极好。个人实操心得启动即访谈第一次连接时的访谈很重要认真回答有助于AI建立更准确的个人画像后续的内容归类会更精准。“先倾倒后整理”不要担心添加的内容杂乱。养成随时用autopedia add或直接对AI说话记录灵感的习惯。定期比如每天下班前统一说一次“同步维基”让AI做整理工作。这符合“收件箱”处理的工作流。信任AI但保持审查AI的整理能力很强但并非完美。特别是对于高度专业或争议性话题在AI合成信息后最好快速浏览一下生成的维基页面确保关键事实和结论无误。lint功能发现的“高置信度断言”就是很好的审查切入点。代码库分析的妙用在开始阅读一个开源项目或接手一个老项目时第一时间用autopedia add --repo把它加进去。让AI生成的架构摘要能帮你快速建立全局认知效率远超自己漫无目的地看代码。