1. 项目概述一个会学习、能记忆的本地AI智能体如果你和我一样对市面上的AI助手总感觉“差点意思”——它们要么是云端黑盒你的对话历史和数据去向不明要么功能僵化除了聊天啥也干不了要么就是“金鱼记忆”聊完就忘——那么VibeWorker 可能就是你在找的那个答案。VibeWorker 不是一个简单的聊天机器人。它是一个开源的、本地优先的 AI 智能体Agent框架。你可以把它理解为一个驻扎在你电脑里的“数字伙伴”。它的核心能力在于三点记忆、学习和进化。所有数据包括你的对话历史、它学到的知识、你的个人偏好都以人类可读的 JSON 文件形式安静地躺在你的~/.vibeworker/目录下完全由你掌控。它通过一个名为“技能”的插件系统来扩展能力这些技能不是写死的代码而是一份份“教学手册”告诉它如何组合使用基础工具如执行命令、读写文件、访问网页来完成复杂任务。更酷的是它内置了与 Model Context Protocol (MCP) 的集成能动态连接外部工具服务器让它的能力边界几乎可以无限扩展。简单来说VibeWorker 试图解决的是“让 AI 真正为你所用”的问题。它不满足于一次性的问答而是追求在长期的互动中理解你的习惯积累经验并自主地调用各种工具来帮你处理实际问题从整理文档、分析数据到自动化操作就像一个不断成长的数字同事。1.1 核心设计哲学透明、可控与进化在深入技术细节前理解 VibeWorker 背后的几个关键设计理念至关重要。这能帮你明白它为什么这样构建以及它适合解决哪类问题。1. 文件优先与完全透明所有状态持久化都基于本地文件系统。这意味着你可以随时用文本编辑器打开memory.json查看它记住了什么可以备份整个~/.vibeworker目录来迁移数据也可以用git来管理你的技能库。系统提示词System Prompt的组装、每一次工具调用、每一次记忆的存取在前端的“检查器”面板中都清晰可见。这种透明性消除了“魔法”感让你能精确调试和信任它的行为。2. 技能即指令而非代码这是 VibeWorker 与许多其他 AI 框架最大的不同。一个技能Skill本质上是一个包含SKILL.md文件的文件夹。这个 Markdown 文件里写的不是函数定义而是用自然语言描述的任务步骤、注意事项和示例。当用户提出相关需求时Agent 会去读取这份“手册”然后动态地决定调用哪些核心工具来执行。例如一个“获取天气”的技能其SKILL.md可能写道“1. 使用fetch_url工具访问某天气 API。2. 从返回的 JSON 中解析温度和天气状况。3. 使用memory_write工具将用户的位置偏好记录下来。” 这种方式极大地降低了技能创作门槛也让 Agent 的行为更灵活、更易理解。3. 混合执行引擎VibeWorker 没有采用单一的 Agent 范式。它使用 LangGraph 构建了一个统一的状态图StateGraph入口是一个标准的 ReActReasoning and Acting智能体。对于简单问题它直接思考并调用工具解决。一旦任务变得复杂它会自动触发plan_create工具进入“计划执行”模式先制定分步计划然后为每一步启动一个独立的子智能体去执行并有一个“重新规划器”节点在每一步后评估进展决定是继续、修正还是结束。这种设计在灵活性和处理复杂任务的能力之间取得了很好的平衡。4. 四层记忆体系记忆是智能体体现“智能”和“个性化”的核心。VibeWorker 参考了人类记忆模型设计了四个层级工作记忆当前对话的上下文存在于内存中对话结束即消失。短期记忆以天为单位的日志记录每日互动摘要30天后自动归档。长期记忆经过“智能合并”筛选后的重要信息如你的偏好、关键事实等持久化存储。程序性记忆从工具使用成功或失败的经验中学习到的“技巧”例如“在用户的项目目录下python命令需要替换为python3”。这个系统支持基于重要性的记忆提取、随时间衰减的回忆权重以及对话开始时的“隐性回忆”——自动加载与你最相关的10条记忆让 Agent 每次交流都“记得你”。2. 核心架构深度解析要真正玩转 VibeWorker不能只停留在表面操作。理解其内部各个模块如何协同工作能帮助你在遇到问题时快速定位也能让你更有效地定制它。我们来拆解它的核心架构。2.1 统一智能体编排引擎VibeWorker 的核心大脑是一个基于 LangGraphStateGraph构建的编排引擎。整个流程可以看作一个智能决策与执行回路。状态与流程整个图的状态State是一个共享的数据字典包含了当前用户输入、聊天历史、已加载的记忆、可用的工具列表、计划步骤等所有必要信息。图的节点Nodes就是处理单元边Edges根据节点的输出决定下一步走向。第一阶段ReAct 智能体统一入口所有用户请求首先到达agent节点。这个节点配备了完整的“工具箱”8个核心工具 plan_create工具 所有已加载的 MCP 工具。它的工作模式是经典的 ReAct思考Reason-行动Act-观察Observe循环直到得出答案。简单任务例如“今天的日期是什么”它可能直接调用terminal执行date命令并返回结果。复杂任务当它判断任务需要多步协作时例如“帮我分析这个日志文件并总结错误”它会主动调用plan_create工具。这个工具会要求底层 LLM 生成一个步骤清晰的执行计划并将控制权移交给第二阶段。第二阶段计划执行循环自动触发一旦plan_create被调用流程就进入了更结构化的计划模式。计划审批门plan_gate这是一个可配置的检查点。如果全局设置中plan_require_approvaltrue这里会暂停执行并通过前端向用户弹窗展示计划等待用户“批准”、“拒绝”或“批准所有”。这为高风险操作提供了人工介入的机会。如果设置为false则自动批准。执行器executor对于计划中的每一步执行器会生成一个全新的、隔离的 ReAct 子智能体来专门处理这一步。这是非常关键的设计它避免了将整个复杂计划的上下文都塞进一个智能体导致提示词过长Context Bloat的问题。每个子智能体只关注当前步骤的目标完成后将结果返回给执行器。重新规划器replanner每一步执行完毕后重新规划器会评估结果。它有三种决定continue步骤成功继续下一个。revise步骤失败或结果不理想要求修改当前或后续计划。finish所有步骤完成或提前达到目标结束循环。总结器summarizer当整个计划执行循环结束时无论是完成还是被终止总结器会收集所有步骤的结果编译成一份完整的摘要然后将其交还给第一阶段的agent节点。最后由agent节点组织语言生成给用户的最终回复。配置驱动整个图的行为包括每个节点使用的模型、参数、可用工具集都通过graph_config.yaml文件控制。这意味着你可以调整智能体的行为模式比如让它更倾向于制定计划或者更严格的安全审批而无需修改任何代码。实操心得调试智能体行为当你发现智能体对某类任务反应不理想时第一个检查点应该是graph_config.yaml。例如如果它总是不愿意为中等复杂度的任务制定计划你可以调整agent节点中触发plan_create的提示词部分或者降低其使用门槛。同样如果你希望所有文件操作都经过确认就把plan_require_approval设为true。这个文件是调节智能体“性格”和“能力倾向”的总开关。2.2 四层记忆系统的工作原理记忆系统是 VibeWorker 的“灵魂”。它的目标不仅是存储信息更是让信息在需要的时候能够被高效、相关地回忆起来。1. 记忆的写入与智能合并当调用memory_write工具或通过会话反射自动生成记忆时新记忆不会直接堆进列表。它会经过“合并器”的处理。合并器使用 LLM 将新记忆与现有长期记忆进行比对并做出以下决策之一ADD这是一个全新的信息直接添加。UPDATE这与现有记忆 A 相关但提供了更新或更详细的信息更新记忆 A。DELETE这与现有记忆 A 矛盾且新信息更可信删除记忆 A。NOOP这与现有记忆完全重复或无关紧要忽略。 这个过程有效防止了记忆冗余和矛盾保持了记忆库的简洁和准确。2. 记忆的检索相关性、重要性与时效性当进行memory_search或启动“隐性回忆”时系统并非简单地进行关键词匹配。它采用一种综合评分算法语义相关性得分通过向量化Embedding计算查询与记忆内容的余弦相似度。这是最核心的部分。重要性得分每条记忆在写入时都会被赋予一个 0.0 到 1.0 的“显着性”分数由 LLM 判断。例如“用户对花生严重过敏”的重要性远高于“用户喜欢蓝色”。时间衰减得分采用指数衰减模型decay_score e^(-λ * days)。λ 是衰减系数默认 0.05意味着一条记忆在 14 天后相关性会衰减到约 50%。这保证了近期发生的、更可能相关的事情被优先回忆。 最终的综合得分是这三个得分的加权和系统返回得分最高的若干条记忆。3. 程序性记忆的生成这是“学习”能力的体现。当工具调用失败时例如在用户环境中执行python失败但python3成功系统会自动捕获这个上下文并可能生成一条程序性记忆“在用户 [用户名] 的上下文中执行 Python 脚本应使用python3命令而非python。” 当下次同一用户遇到类似任务时这条记忆会被隐性回忆智能体就能直接使用正确的命令表现出“它记住了你的环境特点”。4. 归档与压缩自动归档短期记忆日志在 30 天后会被自动汇总成一份月度摘要移出活跃记忆区避免检索时被无关的日常琐事干扰。手动压缩当记忆条目过多时你可以手动触发“记忆压缩”。系统会使用文本相似度算法如 TF-IDF找出内容相似的记忆然后尝试用 LLM 将它们合并成一条更精炼、更全面的记忆释放空间。注意事项记忆系统的性能记忆的向量化检索依赖嵌入模型。如果你使用本地嵌入模型如all-MiniLM-L6-v2首次加载或记忆量大时构建索引可能较慢。建议在model_pool.json中为embedding场景分配一个速度较快的模型。此外定期进行记忆压缩和归档能有效提升长期记忆的检索速度和相关性。2.3 技能系统插件化能力扩展技能系统是 VibeWorker 生态活力的来源。其设计巧妙地将“能力定义”与“能力执行”解耦。技能的生命周期发现智能体启动时会扫描~/.vibeworker/skills/目录下的所有文件夹。每个技能文件夹必须包含一个SKILL.md文件。这个文件的内容会被注入到系统提示词中让智能体“知道”自己拥有这个能力。匹配当用户提出请求时智能体会在其“可用技能”列表中做语义匹配决定哪个技能最适合处理当前请求。学习一旦决定使用某个技能智能体会主动调用read_file工具去读取对应的SKILL.md文件将详细的指令加载到当前工作上下文中。执行智能体根据SKILL.md中的指导逐步调用相应的核心工具或 MCP 工具来完成任务。SKILL.md中甚至可以包含“如果步骤 A 失败则尝试步骤 B”这样的条件逻辑。一个技能示例 (skills/fetch_webpage/SKILL.md)# 技能获取网页内容并总结 ## 描述 当用户需要获取某个网页的内容并提取关键信息时使用此技能。 ## 步骤 1. 使用 fetch_url 工具获取用户提供的 URL 的网页内容。该工具会返回清理后的 Markdown 格式文本。 2. 如果网页内容过长例如超过 3000 字符使用 python_repl 工具运行一个简单的 Python 脚本调用 LLM 接口通过 plan_create 触发子任务对内容进行总结。 3. 将获取的原始内容或总结结果以及来源 URL通过 memory_write 工具存入长期记忆类别为 facts并添加标签 web_content。 ## 注意 - 确保 URL 是有效的并以 http:// 或 https:// 开头。 - 如果 fetch_url 失败返回错误信息直接向用户报告错误不要继续后续步骤。从这个例子可以看出技能作者不需要会写 Python 函数只需要会清晰地描述任务流程和判断逻辑。这极大地丰富了智能体的能力库。技能商店集成VibeWorker 前端内置了与社区技能商店skills.sh的集成。你可以像逛应用商店一样浏览、搜索分类如“开发”、“写作”、“研究”并一键安装感兴趣的技能到本地。社区有超过 500 个技能这是快速获得强大能力的捷径。2.4 MCP 集成连接外部世界的桥梁Model Context Protocol (MCP) 是由 Anthropic 提出的一种协议旨在标准化 AI 应用与外部工具、数据源之间的连接方式。VibeWorker 作为 MCP 客户端可以连接到任何实现了 MCP 协议的服务器从而动态获得新工具。工作原理配置服务器你在mcp_servers.json或前端界面中添加一个 MCP 服务器配置指定其名称、传输方式stdio用于本地进程sse用于远程 HTTP 服务和参数。连接与工具注入VibeWorker 启动时会尝试连接配置的服务器。连接成功后服务器会宣告它提供哪些“工具”Tools。VibeWorker 将这些工具动态地包装成 LangChain 的StructuredTool并以mcp_{服务器名}_{工具名}的格式命名然后注入到智能体的可用工具列表中。独立缓存考虑到 MCP 工具可能涉及网络请求或复杂计算VibeWorker 为它们提供了独立的 L1L2 缓存。这意味着相同的工具调用参数会被缓存下次直接返回结果并在前端标记为[CACHE_HIT]极大提升效率。典型用例连接mcp-server-postgres让智能体可以直接查询你的数据库。连接mcp-server-github让智能体可以读取仓库信息、创建 Issue。连接一个自定义的 MCP 服务器提供公司内部的 API 工具。 这相当于为你的智能体插上了无数个专业领域的“外挂”使其真正成为一个万能助手。2.5 双层缓存系统速度与成本的平衡术VibeWorker 的缓存系统是其响应迅速且能节省大量 API 成本的关键。它采用 L1内存 L2磁盘的双层架构。缓存类型与策略URL 缓存默认开启TTL 1小时。缓存fetch_url工具获取的网页内容。对于静态页面或更新不频繁的 API 响应效果极佳。LLM 缓存默认关闭TTL 24小时。如果开启会缓存智能体对 LLM 的完整请求和响应。注意这需要谨慎使用因为相同的用户输入在不同上下文中可能需要不同的回答。通常建议在开发调试或处理高度确定性任务时开启。提示词缓存默认开启TTL 10分钟。缓存组装好的系统提示词。由于系统提示词包含会话历史、记忆、技能列表等在短时间内的连续对话中变化不大此缓存能显著减少重复的 Token 计算和嵌入模型调用。翻译缓存默认开启TTL 7天。缓存技能商店等处的翻译结果。MCP 工具缓存默认开启TTL 1小时。缓存 MCP 工具的调用结果。性能收益在我的实际使用中缓存带来的提升是肉眼可见的网页请求一个常规新闻页面首次获取需要 1-2 秒缓存后再次获取仅需 10-50 毫秒提升10-100 倍。LLM 调用对于结构化的、重复性的任务如按固定格式总结内容开启 LLM 缓存后响应时间从 2-5 秒降至 100-300 毫秒提升10-20 倍同时直接归零了对应请求的 API 费用。复杂技能执行一个需要多次调用 LLM 和工具的多步技能首次执行可能耗时 30 秒后续执行因多处缓存命中可能只需 2-3 秒。如何为自定义工具添加缓存如果你在开发自己的工具模块可以轻松地利用缓存装饰器from backend.cache.decorators import cached_tool cached_tool(cache_typemy_tool, ttl1800) # 缓存30分钟 def my_custom_tool(query: str, user_id: str) - dict: # 这里是你的工具逻辑可能涉及网络请求或复杂计算 result do_expensive_operation(query, user_id) return result缓存键会自动根据函数名和所有参数生成确保相同输入得到相同输出时才命中缓存。3. 从零开始部署与深度配置指南了解了核心原理我们来动手搭建一个属于自己的 VibeWorker 环境。这里不仅是一键脚本我会详细解释每一步背后的考量以及如何根据你的需求进行深度定制。3.1 环境准备与源码部署系统要求与前置检查Python 3.10这是 LangChain 和某些依赖的最低要求。建议使用 Python 3.11 或 3.12 以获得更好的性能和兼容性。使用python --version确认。Node.js 18用于运行 Next.js 前端。建议使用 LTS 版本。使用node --version确认。Git用于克隆仓库。至少 4GB 可用内存运行 LLM 模型如果是本地模型和向量数据库索引时会占用较多内存。网络通畅需要能访问 OpenAI 兼容的 API如 OpenAI, OpenRouter, 或本地部署的 LM Studio 服务器。克隆与目录结构git clone https://github.com/EntropyFlux/VibeWorker.git cd VibeWorker此时你会看到项目根目录下的结构。最重要的区分是backend/和frontend/是源代码而你的所有数据和配置将来都会存放在独立于源代码的~/.vibeworker/Linux/macOS或%USERPROFILE%\.vibeworker\Windows目录下。这种分离保证了你可以随时更新源代码而不影响你的个人数据。后端环境搭建手动方式cd backend # 创建独立的虚拟环境避免污染系统Python python -m venv venv # 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 安装依赖。requirements.txt 包含了 LangChain, FastAPI, LlamaIndex 等核心包。 pip install -r requirements.txt注意事项依赖安装常见问题速度慢可以使用国内镜像源如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。特定平台编译错误如果遇到grpcio或tokenizers等需要编译的包出错可以尝试先安装系统级的编译工具如build-essentialon Ubuntu或者寻找预编译的 wheel 文件。版本冲突如果遇到与其他项目冲突请务必在独立的虚拟环境中操作。前端环境搭建cd ../frontend # 安装 Node.js 依赖 npm install # 或者使用 yarn, pnpm前端依赖安装通常比较顺利。如果遇到网络问题可以配置 npm 镜像或使用cnpm。更推荐的一键启动项目提供了start.sh(Unix) 和start.bat(Windows) 脚本它们会自动处理上述环境激活和进程启动。# Linux/macOS ./start.sh # Windows start.bat脚本会同时启动后端localhost:8088和前段localhost:3000。启动后在浏览器中访问http://localhost:3000即可。3.2 核心配置详解模型池与环境变量第一次启动时VibeWorker 会在用户目录创建~/.vibeworker/并初始化一些默认配置。其中最关键的两个文件是.env和model_pool.json。1. 全局环境变量 (.env)这个文件主要控制框架行为不包含具体的 API 密钥。API 密钥在模型池中配置。# .env 示例 LLM_TEMPERATURE0.7 # 控制LLM输出的随机性0更确定1更有创意 LLM_MAX_TOKENS4096 # LLM单次回复的最大token数 # 记忆系统开关 MEMORY_CONSOLIDATION_ENABLEDtrue # 是否启用智能记忆合并 MEMORY_IMPLICIT_RECALL_ENABLEDtrue # 是否在对话开始时隐性回忆 MEMORY_ARCHIVE_DAYS30 # 日志多少天后归档 MEMORY_DECAY_LAMBDA0.05 # 记忆时间衰减系数越大衰减越快 # 缓存开关 ENABLE_URL_CACHEtrue ENABLE_LLM_CACHEfalse # 生产环境建议关闭调试时可开启 ENABLE_PROMPT_CACHEtrue ENABLE_TRANSLATE_CACHEtrue # MCP MCP_ENABLEDtrue MCP_TOOL_CACHE_TTL3600 # MCP工具缓存时间秒我的建议是初次使用保持默认即可。当你需要对系统行为进行微调时比如觉得智能体忘得太快可以调小MEMORY_DECAY_LAMBDA再来修改这个文件。2. 模型池配置 (model_pool.json)这是 VibeWorker 的核心配置。它允许你定义多个模型并将它们分配给不同的“场景”。{ models: [ { id: openai-gpt-4o, name: GPT-4o, type: openai, // 或 anthropic, openrouter, lmstudio base_url: https://api.openai.com/v1, api_key: sk-..., // 你的API密钥 model_name: gpt-4o, max_tokens: 4096, temperature: 0.7, context_window: 128000 }, { id: local-embedding, name: Local Embedding, type: openai, // 使用OpenAI兼容接口 base_url: http://localhost:1234/v1, // 本地LM Studio服务器 api_key: not-needed, // 本地服务器可能不需要密钥 model_name: all-MiniLM-L6-v2, // 嵌入模型名 context_window: 512 } ], assignments: { llm: openai-gpt-4o, // 主对话和推理用这个模型 embedding: local-embedding, // 记忆向量化用这个模型 translate: openai-gpt-4o // 翻译任务用这个模型 } }关键点解析多模型支持你可以同时配置 OpenAI、Claude通过 OpenRouter、本地 LM Studio/Ollama 等多种模型源。场景分配这是精髓。你可以让强大的 GPT-4 负责核心推理llm让一个轻量、免费的本地模型负责嵌入计算embedding实现成本与性能的最优组合。本地嵌入模型为了记忆检索的速度和零成本强烈建议部署一个本地嵌入模型。使用 LM Studio 或 Ollama 可以轻松在本地运行all-MiniLM-L6-v2这类轻量级模型。将base_url指向本地服务地址如http://localhost:1234/v1可以极大提升记忆检索速度并消除相关 API 费用。API 密钥安全model_pool.json存储在本地但仍需注意不要将其提交到公开版本库。可以考虑将api_key部分移出通过环境变量注入但 VibeWorker 目前的设计是直接读写该文件。在前端配置模型池启动应用后点击右上角设置图标 - “模型”标签页可以图形化地添加、编辑、删除模型以及分配场景。你可以在这里测试模型连接是否正常。3.3 技能与 MCP 服务器的管理安装第一个技能点击左侧边栏的“技能”图标。切换到“商店”标签页。你可以浏览或搜索技能。例如搜索 “web search”。找到想要的技能后点击“安装”按钮。技能会被下载到~/.vibeworker/skills/目录下。安装后在“本地”标签页就能看到它。智能体在下一次请求时就会意识到这个新技能的存在。手动创建技能如果你想自己编写技能只需在~/.vibeworker/skills/下创建一个新文件夹例如my_custom_skill/然后在里面创建一个SKILL.md文件。编写格式如前文所述。完成后重启后端服务或刷新技能列表即可。连接 MCP 服务器以连接一个本地的 PostgreSQL MCP 服务器为例假设你已安装mcp-server-postgres。点击左侧边栏的“MCP”图标。点击“添加服务器”。填写信息名称postgres-local自定义类型stdio命令npx假设你通过 npx 运行参数-ymcp-server-postgres--connectionStringpostgresql://user:passwordlocalhost:5432/mydb自动连接勾选点击“保存并连接”。如果状态显示为“已连接”并且“工具”列表里出现了query_database之类的工具说明配置成功。现在你可以直接对智能体说“查询一下用户表里最近注册的10个人”它就会自动调用mcp_postgres-local_query_database工具来执行。实操心得技能与 MCP 的优先级当既有技能又能通过 MCP 工具完成类似任务时智能体会如何选择这取决于系统提示词中的引导和工具描述的清晰度。通常描述更具体、更匹配当前请求的工具会被优先选择。你可以通过优化SKILL.md的描述来提高其被选中的概率。对于 MCP 工具确保其description字段由 MCP 服务器提供准确详尽。3.4 浏览器扩展的安装与使用浏览器扩展是 VibeWorker 实现高级网页自动化如填写表单、抓取动态内容的关键。它通过 Chrome/Edge 扩展程序建立了一个安全的通信通道。安装步骤在 VibeWorker 项目根目录下找到extension/文件夹。打开 Chrome 或 Edge 浏览器进入扩展程序管理页面 (chrome://extensions/或edge://extensions/)。开启右上角的“开发者模式”。点击“加载已解压的扩展程序”按钮。选择项目中的extension/文件夹。安装成功后浏览器工具栏会出现 VibeWorker 的图标。使用与授权首次使用时需要在前端授权扩展。点击前端设置中的“浏览器扩展”部分通常会有一个“连接”或“授权”按钮。授权后智能体就获得了在你当前激活的浏览器标签页上执行有限操作的能力。当你要求智能体“帮我把这个页面的所有标题摘录下来”或“在这个搜索框里输入 XXX 并点击搜索”时它会通过扩展提供的工具如get_page_content,click_element,type_text来操作。安全提示这是一个强大的功能。务必只在你信任的网站上使用并且清楚智能体将要执行的操作。VibeWorker 的前端安全审批机制在这里同样有效高风险操作会要求你确认。4. 实战场景与高级技巧理论配置完毕我们来看几个具体的使用场景以及如何利用 VibeWorker 的高级特性来提升效率。4.1 场景一个人知识库助手与自动化归档目标我每天阅读大量技术文章和博客希望智能体能帮我自动提取关键信息并结构化地存入记忆方便日后查询。实现步骤技能准备从商店安装或自己编写一个“网页内容分析”技能。这个技能的SKILL.md应该描述获取 URL - 提取正文 - 分析文章主题、关键知识点、代码示例 - 生成结构化摘要。记忆分类在memory_write步骤中指定合适的类别如category: facts并打上标签如tags: [tech, programming, article]。自动化流程我可以创建一个简单的脚本或使用快捷指令将当前浏览器的 URL 发送给 VibeWorker 的 API (/api/chat)并附带指令“请使用‘网页内容分析’技能处理这个 URL并将关键信息存入我的知识库。”查询与回忆几周后当我想起某个模糊的概念时可以直接问“我记得之前看过一篇关于 Rust 所有权和借用的文章讲了什么” 智能体会通过记忆搜索找到相关的记忆条目并呈现给我。高级技巧利用程序性记忆在技能中可以设计让智能体在成功执行后记录一条程序性记忆。例如“用户偏好将技术文章摘要以‘标题、要点、代码片段、参考链接’的格式保存。” 这样以后处理类似任务时即使技能指令没那么详细它也会自动应用这个格式。4.2 场景二本地开发与调试助手目标在编程时让智能体协助我查看日志、执行测试、搜索代码库甚至根据错误信息提出修复建议。实现步骤配置工作空间在 VibeWorker 的设置中将“工作空间根目录”设置为我当前项目的路径。这会将terminal和read_file等工具的操作限制在该目录下保障安全。集成 MCP为我的项目语言如 Python/JavaScript配置对应的 MCP 服务器。例如连接一个能进行代码静态分析的 MCP 服务器。交互式调试我“帮我看看app.log文件最后 50 行有什么错误。”智能体调用read_file读取日志然后可能调用plan_create制定一个分析计划1. 过滤 ERROR 级别的行。2. 对错误信息进行聚类。3. 搜索记忆库中是否有类似错误的解决方案。最后将分析结果给我。我“针对这个 ‘Connection refused’ 错误可能的解决方案是什么”智能体结合记忆中的知识可能来自之前存入的运维文档和实时网络搜索通过fetch_url给出检查服务端口、防火墙、网络配置等建议。高级技巧使用计划模式处理复杂问题对于“帮我重构这个函数提高其性能”这类复杂请求智能体很可能会自动进入计划模式。它会先创建一个多步计划1. 分析当前函数代码和性能瓶颈。2. 搜索记忆和知识库中的重构模式。3. 编写重构后的代码。4. 运行测试验证。你可以通过前端的“计划卡片”可视化地跟踪每一步的进展和结果。4.3 场景三利用缓存构建高效工作流目标我每天需要生成多份类似的数据报告内容基于几个固定 API 的数据和固定的分析模板。实现步骤编写报告生成技能创建一个技能其中包含调用固定 API (fetch_url) 和填充模板 (python_repl进行字符串处理) 的步骤。开启 LLM 缓存谨慎因为报告模板固定每次请求的差异可能只是日期参数。在开发测试阶段可以在.env中临时设置ENABLE_LLM_CACHEtrue。这样智能体生成报告文本的 LLM 调用会被缓存。注意正式使用时如果日期是变量需要确保缓存键包含日期或者更安全的方式是只缓存 API 数据部分LLM 部分不缓存。利用 URL 缓存对于获取固定 API 数据的步骤URL 缓存会发挥巨大作用避免重复的网络请求。结果第一次生成报告可能需要 20 秒。之后由于 API 数据、LLM 响应都被缓存生成时间可能缩短到 2-3 秒效率提升近 10 倍。4.4 安全沙箱与操作审批VibeWorker 的安全设计是多层次的。理解这些你才能放心地赋予它更多权限。安全门Security Gate在工具执行前security/gate.py会基于规则和机器学习分类器如果启用对操作进行风险评估。高风险操作如terminal中执行rm -rf /或python_repl中尝试导入os.system会被拦截。工具包装器每个核心工具都经过security/tool_wrapper.py的包装它在执行前后进行校验和审计。用户审批对于被安全门标记为“高风险”或“需审批”的操作前端会弹出一个对话框让你选择“允许”、“拒绝”或“允许本次会话中的所有操作”。这是最后一道也是最重要的人工防线。Docker 沙箱可选对于极度不信任的代码执行可以配置 Docker 沙箱将python_repl等操作隔离在容器中运行。我的安全实践对于个人开发环境我通常将工作空间根目录设置为项目目录并开启操作审批。我会定期查看~/.vibeworker/security_audit.log文件了解智能体尝试执行了哪些操作。对于从社区安装的陌生技能首次运行时我会格外关注其计划步骤确认它要执行的操作是否符合预期。5. 故障排除与性能优化即使设计再完善在实际使用中也可能遇到问题。这里记录了一些常见问题的排查思路和优化经验。5.1 常见问题速查表问题现象可能原因排查步骤与解决方案前端无法连接后端后端服务未启动端口被占用CORS 问题。1. 检查./start.sh status或查看进程。2. 检查localhost:8088端口是否被其他程序占用。3. 查看后端日志 (backend/app.py输出) 是否有错误。智能体不响应或响应慢LLM API 连接失败模型池配置错误网络问题。1. 在前端“设置-模型”页测试模型连接。2. 检查model_pool.json中的api_key和base_url是否正确。3. 查看浏览器开发者工具 Network 标签看/api/chat请求是否长时间挂起或返回错误。记忆搜索返回无关内容嵌入模型未正常工作记忆索引未更新。1. 确认model_pool.json中embedding场景分配的模型有效且可访问。2. 尝试在“记忆”面板手动点击“重建索引”。3. 检查嵌入模型的上下文窗口是否设置过小。技能未被识别或调用SKILL.md格式错误技能未加载。1. 检查SKILL.md文件语法确保是有效的 Markdown。2. 在前端“技能-本地”列表查看技能是否加载成功。3. 重启后端服务以重新加载所有技能。MCP 工具连接失败MCP 服务器命令或参数错误服务器本身未启动。1. 在前端 MCP 面板检查服务器状态和日志。2. 尝试在命令行手动运行 MCP 服务器命令看能否独立启动。3. 检查stdio类型服务器的命令路径是否正确。浏览器扩展不工作扩展未安装或未授权前端未连接。1. 确认扩展已安装并启用 (chrome://extensions/)。2. 在前端设置中完成扩展的授权流程。3. 刷新前端页面和浏览器标签页。磁盘空间占用过大缓存文件或记忆日志过多。1. 定期在前端“缓存”面板清理过期缓存。2. 在“记忆”面板触发“压缩记忆”和“归档日志”。3. 调整.env中的MEMORY_ARCHIVE_DAYS减少日志保留时间。5.2 性能优化建议使用本地嵌入模型这是提升记忆检索速度和消除相关成本最有效的一步。all-MiniLM-L6-v2是一个很好的平衡速度和精度的选择。合理配置模型池将轻量、快速、低成本的模型分配给embedding和translate场景。将强大但昂贵的模型如 GPT-4专用于llm场景。善用缓存对fetch_url和prompt缓存保持开启。对于重复性高的自动化任务可以阶段性开启LLM_CACHE进行测试但生产环境需谨慎评估。管理记忆规模定期进行记忆压缩。删除不再需要的、低显着性salience的记忆。庞大的记忆库会拖慢检索速度。优化技能指令在SKILL.md中提供清晰、具体的指令减少智能体的“思考”歧义可以缩短响应时间。明确的步骤和条件判断能引导它更直接地调用工具。监控资源使用关注后端进程的内存和 CPU 占用。如果长期运行后内存持续增长可能是内存缓存L1或会话数据未及时释放可以考虑定期重启服务。5.3 调试与日志查看当遇到复杂问题时查看日志是必须的。后端日志直接查看运行python app.py的终端输出。这里包含了 FastAPI 的访问日志、工具调用的详细信息、MCP 连接状态等。启动时添加--log-level DEBUG参数可以获得更详细的日志。前端日志打开浏览器开发者工具 (F12)查看 Console 和 Network 标签页。Console 会显示前端错误Network 可以查看所有 API 请求和响应特别是/api/chat的 Server-Sent Events (SSE) 流。审计日志安全相关的操作会记录在~/.vibeworker/security_audit.log中。检查器面板VibeWorker 前端右侧的“检查器”面板是强大的调试工具。你可以实时看到系统提示词是如何组装的、智能体每一步的“思考”过程、调用了哪些工具及其参数和结果。这是理解智能体决策逻辑的最佳窗口。一个真实的调试案例智能体总是错误地调用一个 MCP 工具。通过检查器面板我发现是 MCP 服务器提供的工具描述过于模糊导致智能体在匹配时出错。我的解决方案是在前端 MCP 面板中找到该工具手动编辑其description字段使其更精确地描述工具的功能和适用场景问题得以解决。VibeWorker 的魅力在于它将强大的 AI 能力与高度的透明性、可定制性结合在了一起。它不是一个完美的成品而是一个充满可能性的平台。你可以从简单的个人助理开始随着对其理解的深入逐步将它打造成一个深度融入你工作流、真正理解你需求的智能伙伴。 VibeWorker：本地AI智能体框架，实现记忆、学习与工具调用的开源解决方案
1. 项目概述一个会学习、能记忆的本地AI智能体如果你和我一样对市面上的AI助手总感觉“差点意思”——它们要么是云端黑盒你的对话历史和数据去向不明要么功能僵化除了聊天啥也干不了要么就是“金鱼记忆”聊完就忘——那么VibeWorker 可能就是你在找的那个答案。VibeWorker 不是一个简单的聊天机器人。它是一个开源的、本地优先的 AI 智能体Agent框架。你可以把它理解为一个驻扎在你电脑里的“数字伙伴”。它的核心能力在于三点记忆、学习和进化。所有数据包括你的对话历史、它学到的知识、你的个人偏好都以人类可读的 JSON 文件形式安静地躺在你的~/.vibeworker/目录下完全由你掌控。它通过一个名为“技能”的插件系统来扩展能力这些技能不是写死的代码而是一份份“教学手册”告诉它如何组合使用基础工具如执行命令、读写文件、访问网页来完成复杂任务。更酷的是它内置了与 Model Context Protocol (MCP) 的集成能动态连接外部工具服务器让它的能力边界几乎可以无限扩展。简单来说VibeWorker 试图解决的是“让 AI 真正为你所用”的问题。它不满足于一次性的问答而是追求在长期的互动中理解你的习惯积累经验并自主地调用各种工具来帮你处理实际问题从整理文档、分析数据到自动化操作就像一个不断成长的数字同事。1.1 核心设计哲学透明、可控与进化在深入技术细节前理解 VibeWorker 背后的几个关键设计理念至关重要。这能帮你明白它为什么这样构建以及它适合解决哪类问题。1. 文件优先与完全透明所有状态持久化都基于本地文件系统。这意味着你可以随时用文本编辑器打开memory.json查看它记住了什么可以备份整个~/.vibeworker目录来迁移数据也可以用git来管理你的技能库。系统提示词System Prompt的组装、每一次工具调用、每一次记忆的存取在前端的“检查器”面板中都清晰可见。这种透明性消除了“魔法”感让你能精确调试和信任它的行为。2. 技能即指令而非代码这是 VibeWorker 与许多其他 AI 框架最大的不同。一个技能Skill本质上是一个包含SKILL.md文件的文件夹。这个 Markdown 文件里写的不是函数定义而是用自然语言描述的任务步骤、注意事项和示例。当用户提出相关需求时Agent 会去读取这份“手册”然后动态地决定调用哪些核心工具来执行。例如一个“获取天气”的技能其SKILL.md可能写道“1. 使用fetch_url工具访问某天气 API。2. 从返回的 JSON 中解析温度和天气状况。3. 使用memory_write工具将用户的位置偏好记录下来。” 这种方式极大地降低了技能创作门槛也让 Agent 的行为更灵活、更易理解。3. 混合执行引擎VibeWorker 没有采用单一的 Agent 范式。它使用 LangGraph 构建了一个统一的状态图StateGraph入口是一个标准的 ReActReasoning and Acting智能体。对于简单问题它直接思考并调用工具解决。一旦任务变得复杂它会自动触发plan_create工具进入“计划执行”模式先制定分步计划然后为每一步启动一个独立的子智能体去执行并有一个“重新规划器”节点在每一步后评估进展决定是继续、修正还是结束。这种设计在灵活性和处理复杂任务的能力之间取得了很好的平衡。4. 四层记忆体系记忆是智能体体现“智能”和“个性化”的核心。VibeWorker 参考了人类记忆模型设计了四个层级工作记忆当前对话的上下文存在于内存中对话结束即消失。短期记忆以天为单位的日志记录每日互动摘要30天后自动归档。长期记忆经过“智能合并”筛选后的重要信息如你的偏好、关键事实等持久化存储。程序性记忆从工具使用成功或失败的经验中学习到的“技巧”例如“在用户的项目目录下python命令需要替换为python3”。这个系统支持基于重要性的记忆提取、随时间衰减的回忆权重以及对话开始时的“隐性回忆”——自动加载与你最相关的10条记忆让 Agent 每次交流都“记得你”。2. 核心架构深度解析要真正玩转 VibeWorker不能只停留在表面操作。理解其内部各个模块如何协同工作能帮助你在遇到问题时快速定位也能让你更有效地定制它。我们来拆解它的核心架构。2.1 统一智能体编排引擎VibeWorker 的核心大脑是一个基于 LangGraphStateGraph构建的编排引擎。整个流程可以看作一个智能决策与执行回路。状态与流程整个图的状态State是一个共享的数据字典包含了当前用户输入、聊天历史、已加载的记忆、可用的工具列表、计划步骤等所有必要信息。图的节点Nodes就是处理单元边Edges根据节点的输出决定下一步走向。第一阶段ReAct 智能体统一入口所有用户请求首先到达agent节点。这个节点配备了完整的“工具箱”8个核心工具 plan_create工具 所有已加载的 MCP 工具。它的工作模式是经典的 ReAct思考Reason-行动Act-观察Observe循环直到得出答案。简单任务例如“今天的日期是什么”它可能直接调用terminal执行date命令并返回结果。复杂任务当它判断任务需要多步协作时例如“帮我分析这个日志文件并总结错误”它会主动调用plan_create工具。这个工具会要求底层 LLM 生成一个步骤清晰的执行计划并将控制权移交给第二阶段。第二阶段计划执行循环自动触发一旦plan_create被调用流程就进入了更结构化的计划模式。计划审批门plan_gate这是一个可配置的检查点。如果全局设置中plan_require_approvaltrue这里会暂停执行并通过前端向用户弹窗展示计划等待用户“批准”、“拒绝”或“批准所有”。这为高风险操作提供了人工介入的机会。如果设置为false则自动批准。执行器executor对于计划中的每一步执行器会生成一个全新的、隔离的 ReAct 子智能体来专门处理这一步。这是非常关键的设计它避免了将整个复杂计划的上下文都塞进一个智能体导致提示词过长Context Bloat的问题。每个子智能体只关注当前步骤的目标完成后将结果返回给执行器。重新规划器replanner每一步执行完毕后重新规划器会评估结果。它有三种决定continue步骤成功继续下一个。revise步骤失败或结果不理想要求修改当前或后续计划。finish所有步骤完成或提前达到目标结束循环。总结器summarizer当整个计划执行循环结束时无论是完成还是被终止总结器会收集所有步骤的结果编译成一份完整的摘要然后将其交还给第一阶段的agent节点。最后由agent节点组织语言生成给用户的最终回复。配置驱动整个图的行为包括每个节点使用的模型、参数、可用工具集都通过graph_config.yaml文件控制。这意味着你可以调整智能体的行为模式比如让它更倾向于制定计划或者更严格的安全审批而无需修改任何代码。实操心得调试智能体行为当你发现智能体对某类任务反应不理想时第一个检查点应该是graph_config.yaml。例如如果它总是不愿意为中等复杂度的任务制定计划你可以调整agent节点中触发plan_create的提示词部分或者降低其使用门槛。同样如果你希望所有文件操作都经过确认就把plan_require_approval设为true。这个文件是调节智能体“性格”和“能力倾向”的总开关。2.2 四层记忆系统的工作原理记忆系统是 VibeWorker 的“灵魂”。它的目标不仅是存储信息更是让信息在需要的时候能够被高效、相关地回忆起来。1. 记忆的写入与智能合并当调用memory_write工具或通过会话反射自动生成记忆时新记忆不会直接堆进列表。它会经过“合并器”的处理。合并器使用 LLM 将新记忆与现有长期记忆进行比对并做出以下决策之一ADD这是一个全新的信息直接添加。UPDATE这与现有记忆 A 相关但提供了更新或更详细的信息更新记忆 A。DELETE这与现有记忆 A 矛盾且新信息更可信删除记忆 A。NOOP这与现有记忆完全重复或无关紧要忽略。 这个过程有效防止了记忆冗余和矛盾保持了记忆库的简洁和准确。2. 记忆的检索相关性、重要性与时效性当进行memory_search或启动“隐性回忆”时系统并非简单地进行关键词匹配。它采用一种综合评分算法语义相关性得分通过向量化Embedding计算查询与记忆内容的余弦相似度。这是最核心的部分。重要性得分每条记忆在写入时都会被赋予一个 0.0 到 1.0 的“显着性”分数由 LLM 判断。例如“用户对花生严重过敏”的重要性远高于“用户喜欢蓝色”。时间衰减得分采用指数衰减模型decay_score e^(-λ * days)。λ 是衰减系数默认 0.05意味着一条记忆在 14 天后相关性会衰减到约 50%。这保证了近期发生的、更可能相关的事情被优先回忆。 最终的综合得分是这三个得分的加权和系统返回得分最高的若干条记忆。3. 程序性记忆的生成这是“学习”能力的体现。当工具调用失败时例如在用户环境中执行python失败但python3成功系统会自动捕获这个上下文并可能生成一条程序性记忆“在用户 [用户名] 的上下文中执行 Python 脚本应使用python3命令而非python。” 当下次同一用户遇到类似任务时这条记忆会被隐性回忆智能体就能直接使用正确的命令表现出“它记住了你的环境特点”。4. 归档与压缩自动归档短期记忆日志在 30 天后会被自动汇总成一份月度摘要移出活跃记忆区避免检索时被无关的日常琐事干扰。手动压缩当记忆条目过多时你可以手动触发“记忆压缩”。系统会使用文本相似度算法如 TF-IDF找出内容相似的记忆然后尝试用 LLM 将它们合并成一条更精炼、更全面的记忆释放空间。注意事项记忆系统的性能记忆的向量化检索依赖嵌入模型。如果你使用本地嵌入模型如all-MiniLM-L6-v2首次加载或记忆量大时构建索引可能较慢。建议在model_pool.json中为embedding场景分配一个速度较快的模型。此外定期进行记忆压缩和归档能有效提升长期记忆的检索速度和相关性。2.3 技能系统插件化能力扩展技能系统是 VibeWorker 生态活力的来源。其设计巧妙地将“能力定义”与“能力执行”解耦。技能的生命周期发现智能体启动时会扫描~/.vibeworker/skills/目录下的所有文件夹。每个技能文件夹必须包含一个SKILL.md文件。这个文件的内容会被注入到系统提示词中让智能体“知道”自己拥有这个能力。匹配当用户提出请求时智能体会在其“可用技能”列表中做语义匹配决定哪个技能最适合处理当前请求。学习一旦决定使用某个技能智能体会主动调用read_file工具去读取对应的SKILL.md文件将详细的指令加载到当前工作上下文中。执行智能体根据SKILL.md中的指导逐步调用相应的核心工具或 MCP 工具来完成任务。SKILL.md中甚至可以包含“如果步骤 A 失败则尝试步骤 B”这样的条件逻辑。一个技能示例 (skills/fetch_webpage/SKILL.md)# 技能获取网页内容并总结 ## 描述 当用户需要获取某个网页的内容并提取关键信息时使用此技能。 ## 步骤 1. 使用 fetch_url 工具获取用户提供的 URL 的网页内容。该工具会返回清理后的 Markdown 格式文本。 2. 如果网页内容过长例如超过 3000 字符使用 python_repl 工具运行一个简单的 Python 脚本调用 LLM 接口通过 plan_create 触发子任务对内容进行总结。 3. 将获取的原始内容或总结结果以及来源 URL通过 memory_write 工具存入长期记忆类别为 facts并添加标签 web_content。 ## 注意 - 确保 URL 是有效的并以 http:// 或 https:// 开头。 - 如果 fetch_url 失败返回错误信息直接向用户报告错误不要继续后续步骤。从这个例子可以看出技能作者不需要会写 Python 函数只需要会清晰地描述任务流程和判断逻辑。这极大地丰富了智能体的能力库。技能商店集成VibeWorker 前端内置了与社区技能商店skills.sh的集成。你可以像逛应用商店一样浏览、搜索分类如“开发”、“写作”、“研究”并一键安装感兴趣的技能到本地。社区有超过 500 个技能这是快速获得强大能力的捷径。2.4 MCP 集成连接外部世界的桥梁Model Context Protocol (MCP) 是由 Anthropic 提出的一种协议旨在标准化 AI 应用与外部工具、数据源之间的连接方式。VibeWorker 作为 MCP 客户端可以连接到任何实现了 MCP 协议的服务器从而动态获得新工具。工作原理配置服务器你在mcp_servers.json或前端界面中添加一个 MCP 服务器配置指定其名称、传输方式stdio用于本地进程sse用于远程 HTTP 服务和参数。连接与工具注入VibeWorker 启动时会尝试连接配置的服务器。连接成功后服务器会宣告它提供哪些“工具”Tools。VibeWorker 将这些工具动态地包装成 LangChain 的StructuredTool并以mcp_{服务器名}_{工具名}的格式命名然后注入到智能体的可用工具列表中。独立缓存考虑到 MCP 工具可能涉及网络请求或复杂计算VibeWorker 为它们提供了独立的 L1L2 缓存。这意味着相同的工具调用参数会被缓存下次直接返回结果并在前端标记为[CACHE_HIT]极大提升效率。典型用例连接mcp-server-postgres让智能体可以直接查询你的数据库。连接mcp-server-github让智能体可以读取仓库信息、创建 Issue。连接一个自定义的 MCP 服务器提供公司内部的 API 工具。 这相当于为你的智能体插上了无数个专业领域的“外挂”使其真正成为一个万能助手。2.5 双层缓存系统速度与成本的平衡术VibeWorker 的缓存系统是其响应迅速且能节省大量 API 成本的关键。它采用 L1内存 L2磁盘的双层架构。缓存类型与策略URL 缓存默认开启TTL 1小时。缓存fetch_url工具获取的网页内容。对于静态页面或更新不频繁的 API 响应效果极佳。LLM 缓存默认关闭TTL 24小时。如果开启会缓存智能体对 LLM 的完整请求和响应。注意这需要谨慎使用因为相同的用户输入在不同上下文中可能需要不同的回答。通常建议在开发调试或处理高度确定性任务时开启。提示词缓存默认开启TTL 10分钟。缓存组装好的系统提示词。由于系统提示词包含会话历史、记忆、技能列表等在短时间内的连续对话中变化不大此缓存能显著减少重复的 Token 计算和嵌入模型调用。翻译缓存默认开启TTL 7天。缓存技能商店等处的翻译结果。MCP 工具缓存默认开启TTL 1小时。缓存 MCP 工具的调用结果。性能收益在我的实际使用中缓存带来的提升是肉眼可见的网页请求一个常规新闻页面首次获取需要 1-2 秒缓存后再次获取仅需 10-50 毫秒提升10-100 倍。LLM 调用对于结构化的、重复性的任务如按固定格式总结内容开启 LLM 缓存后响应时间从 2-5 秒降至 100-300 毫秒提升10-20 倍同时直接归零了对应请求的 API 费用。复杂技能执行一个需要多次调用 LLM 和工具的多步技能首次执行可能耗时 30 秒后续执行因多处缓存命中可能只需 2-3 秒。如何为自定义工具添加缓存如果你在开发自己的工具模块可以轻松地利用缓存装饰器from backend.cache.decorators import cached_tool cached_tool(cache_typemy_tool, ttl1800) # 缓存30分钟 def my_custom_tool(query: str, user_id: str) - dict: # 这里是你的工具逻辑可能涉及网络请求或复杂计算 result do_expensive_operation(query, user_id) return result缓存键会自动根据函数名和所有参数生成确保相同输入得到相同输出时才命中缓存。3. 从零开始部署与深度配置指南了解了核心原理我们来动手搭建一个属于自己的 VibeWorker 环境。这里不仅是一键脚本我会详细解释每一步背后的考量以及如何根据你的需求进行深度定制。3.1 环境准备与源码部署系统要求与前置检查Python 3.10这是 LangChain 和某些依赖的最低要求。建议使用 Python 3.11 或 3.12 以获得更好的性能和兼容性。使用python --version确认。Node.js 18用于运行 Next.js 前端。建议使用 LTS 版本。使用node --version确认。Git用于克隆仓库。至少 4GB 可用内存运行 LLM 模型如果是本地模型和向量数据库索引时会占用较多内存。网络通畅需要能访问 OpenAI 兼容的 API如 OpenAI, OpenRouter, 或本地部署的 LM Studio 服务器。克隆与目录结构git clone https://github.com/EntropyFlux/VibeWorker.git cd VibeWorker此时你会看到项目根目录下的结构。最重要的区分是backend/和frontend/是源代码而你的所有数据和配置将来都会存放在独立于源代码的~/.vibeworker/Linux/macOS或%USERPROFILE%\.vibeworker\Windows目录下。这种分离保证了你可以随时更新源代码而不影响你的个人数据。后端环境搭建手动方式cd backend # 创建独立的虚拟环境避免污染系统Python python -m venv venv # 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows: # venv\Scripts\activate # 安装依赖。requirements.txt 包含了 LangChain, FastAPI, LlamaIndex 等核心包。 pip install -r requirements.txt注意事项依赖安装常见问题速度慢可以使用国内镜像源如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。特定平台编译错误如果遇到grpcio或tokenizers等需要编译的包出错可以尝试先安装系统级的编译工具如build-essentialon Ubuntu或者寻找预编译的 wheel 文件。版本冲突如果遇到与其他项目冲突请务必在独立的虚拟环境中操作。前端环境搭建cd ../frontend # 安装 Node.js 依赖 npm install # 或者使用 yarn, pnpm前端依赖安装通常比较顺利。如果遇到网络问题可以配置 npm 镜像或使用cnpm。更推荐的一键启动项目提供了start.sh(Unix) 和start.bat(Windows) 脚本它们会自动处理上述环境激活和进程启动。# Linux/macOS ./start.sh # Windows start.bat脚本会同时启动后端localhost:8088和前段localhost:3000。启动后在浏览器中访问http://localhost:3000即可。3.2 核心配置详解模型池与环境变量第一次启动时VibeWorker 会在用户目录创建~/.vibeworker/并初始化一些默认配置。其中最关键的两个文件是.env和model_pool.json。1. 全局环境变量 (.env)这个文件主要控制框架行为不包含具体的 API 密钥。API 密钥在模型池中配置。# .env 示例 LLM_TEMPERATURE0.7 # 控制LLM输出的随机性0更确定1更有创意 LLM_MAX_TOKENS4096 # LLM单次回复的最大token数 # 记忆系统开关 MEMORY_CONSOLIDATION_ENABLEDtrue # 是否启用智能记忆合并 MEMORY_IMPLICIT_RECALL_ENABLEDtrue # 是否在对话开始时隐性回忆 MEMORY_ARCHIVE_DAYS30 # 日志多少天后归档 MEMORY_DECAY_LAMBDA0.05 # 记忆时间衰减系数越大衰减越快 # 缓存开关 ENABLE_URL_CACHEtrue ENABLE_LLM_CACHEfalse # 生产环境建议关闭调试时可开启 ENABLE_PROMPT_CACHEtrue ENABLE_TRANSLATE_CACHEtrue # MCP MCP_ENABLEDtrue MCP_TOOL_CACHE_TTL3600 # MCP工具缓存时间秒我的建议是初次使用保持默认即可。当你需要对系统行为进行微调时比如觉得智能体忘得太快可以调小MEMORY_DECAY_LAMBDA再来修改这个文件。2. 模型池配置 (model_pool.json)这是 VibeWorker 的核心配置。它允许你定义多个模型并将它们分配给不同的“场景”。{ models: [ { id: openai-gpt-4o, name: GPT-4o, type: openai, // 或 anthropic, openrouter, lmstudio base_url: https://api.openai.com/v1, api_key: sk-..., // 你的API密钥 model_name: gpt-4o, max_tokens: 4096, temperature: 0.7, context_window: 128000 }, { id: local-embedding, name: Local Embedding, type: openai, // 使用OpenAI兼容接口 base_url: http://localhost:1234/v1, // 本地LM Studio服务器 api_key: not-needed, // 本地服务器可能不需要密钥 model_name: all-MiniLM-L6-v2, // 嵌入模型名 context_window: 512 } ], assignments: { llm: openai-gpt-4o, // 主对话和推理用这个模型 embedding: local-embedding, // 记忆向量化用这个模型 translate: openai-gpt-4o // 翻译任务用这个模型 } }关键点解析多模型支持你可以同时配置 OpenAI、Claude通过 OpenRouter、本地 LM Studio/Ollama 等多种模型源。场景分配这是精髓。你可以让强大的 GPT-4 负责核心推理llm让一个轻量、免费的本地模型负责嵌入计算embedding实现成本与性能的最优组合。本地嵌入模型为了记忆检索的速度和零成本强烈建议部署一个本地嵌入模型。使用 LM Studio 或 Ollama 可以轻松在本地运行all-MiniLM-L6-v2这类轻量级模型。将base_url指向本地服务地址如http://localhost:1234/v1可以极大提升记忆检索速度并消除相关 API 费用。API 密钥安全model_pool.json存储在本地但仍需注意不要将其提交到公开版本库。可以考虑将api_key部分移出通过环境变量注入但 VibeWorker 目前的设计是直接读写该文件。在前端配置模型池启动应用后点击右上角设置图标 - “模型”标签页可以图形化地添加、编辑、删除模型以及分配场景。你可以在这里测试模型连接是否正常。3.3 技能与 MCP 服务器的管理安装第一个技能点击左侧边栏的“技能”图标。切换到“商店”标签页。你可以浏览或搜索技能。例如搜索 “web search”。找到想要的技能后点击“安装”按钮。技能会被下载到~/.vibeworker/skills/目录下。安装后在“本地”标签页就能看到它。智能体在下一次请求时就会意识到这个新技能的存在。手动创建技能如果你想自己编写技能只需在~/.vibeworker/skills/下创建一个新文件夹例如my_custom_skill/然后在里面创建一个SKILL.md文件。编写格式如前文所述。完成后重启后端服务或刷新技能列表即可。连接 MCP 服务器以连接一个本地的 PostgreSQL MCP 服务器为例假设你已安装mcp-server-postgres。点击左侧边栏的“MCP”图标。点击“添加服务器”。填写信息名称postgres-local自定义类型stdio命令npx假设你通过 npx 运行参数-ymcp-server-postgres--connectionStringpostgresql://user:passwordlocalhost:5432/mydb自动连接勾选点击“保存并连接”。如果状态显示为“已连接”并且“工具”列表里出现了query_database之类的工具说明配置成功。现在你可以直接对智能体说“查询一下用户表里最近注册的10个人”它就会自动调用mcp_postgres-local_query_database工具来执行。实操心得技能与 MCP 的优先级当既有技能又能通过 MCP 工具完成类似任务时智能体会如何选择这取决于系统提示词中的引导和工具描述的清晰度。通常描述更具体、更匹配当前请求的工具会被优先选择。你可以通过优化SKILL.md的描述来提高其被选中的概率。对于 MCP 工具确保其description字段由 MCP 服务器提供准确详尽。3.4 浏览器扩展的安装与使用浏览器扩展是 VibeWorker 实现高级网页自动化如填写表单、抓取动态内容的关键。它通过 Chrome/Edge 扩展程序建立了一个安全的通信通道。安装步骤在 VibeWorker 项目根目录下找到extension/文件夹。打开 Chrome 或 Edge 浏览器进入扩展程序管理页面 (chrome://extensions/或edge://extensions/)。开启右上角的“开发者模式”。点击“加载已解压的扩展程序”按钮。选择项目中的extension/文件夹。安装成功后浏览器工具栏会出现 VibeWorker 的图标。使用与授权首次使用时需要在前端授权扩展。点击前端设置中的“浏览器扩展”部分通常会有一个“连接”或“授权”按钮。授权后智能体就获得了在你当前激活的浏览器标签页上执行有限操作的能力。当你要求智能体“帮我把这个页面的所有标题摘录下来”或“在这个搜索框里输入 XXX 并点击搜索”时它会通过扩展提供的工具如get_page_content,click_element,type_text来操作。安全提示这是一个强大的功能。务必只在你信任的网站上使用并且清楚智能体将要执行的操作。VibeWorker 的前端安全审批机制在这里同样有效高风险操作会要求你确认。4. 实战场景与高级技巧理论配置完毕我们来看几个具体的使用场景以及如何利用 VibeWorker 的高级特性来提升效率。4.1 场景一个人知识库助手与自动化归档目标我每天阅读大量技术文章和博客希望智能体能帮我自动提取关键信息并结构化地存入记忆方便日后查询。实现步骤技能准备从商店安装或自己编写一个“网页内容分析”技能。这个技能的SKILL.md应该描述获取 URL - 提取正文 - 分析文章主题、关键知识点、代码示例 - 生成结构化摘要。记忆分类在memory_write步骤中指定合适的类别如category: facts并打上标签如tags: [tech, programming, article]。自动化流程我可以创建一个简单的脚本或使用快捷指令将当前浏览器的 URL 发送给 VibeWorker 的 API (/api/chat)并附带指令“请使用‘网页内容分析’技能处理这个 URL并将关键信息存入我的知识库。”查询与回忆几周后当我想起某个模糊的概念时可以直接问“我记得之前看过一篇关于 Rust 所有权和借用的文章讲了什么” 智能体会通过记忆搜索找到相关的记忆条目并呈现给我。高级技巧利用程序性记忆在技能中可以设计让智能体在成功执行后记录一条程序性记忆。例如“用户偏好将技术文章摘要以‘标题、要点、代码片段、参考链接’的格式保存。” 这样以后处理类似任务时即使技能指令没那么详细它也会自动应用这个格式。4.2 场景二本地开发与调试助手目标在编程时让智能体协助我查看日志、执行测试、搜索代码库甚至根据错误信息提出修复建议。实现步骤配置工作空间在 VibeWorker 的设置中将“工作空间根目录”设置为我当前项目的路径。这会将terminal和read_file等工具的操作限制在该目录下保障安全。集成 MCP为我的项目语言如 Python/JavaScript配置对应的 MCP 服务器。例如连接一个能进行代码静态分析的 MCP 服务器。交互式调试我“帮我看看app.log文件最后 50 行有什么错误。”智能体调用read_file读取日志然后可能调用plan_create制定一个分析计划1. 过滤 ERROR 级别的行。2. 对错误信息进行聚类。3. 搜索记忆库中是否有类似错误的解决方案。最后将分析结果给我。我“针对这个 ‘Connection refused’ 错误可能的解决方案是什么”智能体结合记忆中的知识可能来自之前存入的运维文档和实时网络搜索通过fetch_url给出检查服务端口、防火墙、网络配置等建议。高级技巧使用计划模式处理复杂问题对于“帮我重构这个函数提高其性能”这类复杂请求智能体很可能会自动进入计划模式。它会先创建一个多步计划1. 分析当前函数代码和性能瓶颈。2. 搜索记忆和知识库中的重构模式。3. 编写重构后的代码。4. 运行测试验证。你可以通过前端的“计划卡片”可视化地跟踪每一步的进展和结果。4.3 场景三利用缓存构建高效工作流目标我每天需要生成多份类似的数据报告内容基于几个固定 API 的数据和固定的分析模板。实现步骤编写报告生成技能创建一个技能其中包含调用固定 API (fetch_url) 和填充模板 (python_repl进行字符串处理) 的步骤。开启 LLM 缓存谨慎因为报告模板固定每次请求的差异可能只是日期参数。在开发测试阶段可以在.env中临时设置ENABLE_LLM_CACHEtrue。这样智能体生成报告文本的 LLM 调用会被缓存。注意正式使用时如果日期是变量需要确保缓存键包含日期或者更安全的方式是只缓存 API 数据部分LLM 部分不缓存。利用 URL 缓存对于获取固定 API 数据的步骤URL 缓存会发挥巨大作用避免重复的网络请求。结果第一次生成报告可能需要 20 秒。之后由于 API 数据、LLM 响应都被缓存生成时间可能缩短到 2-3 秒效率提升近 10 倍。4.4 安全沙箱与操作审批VibeWorker 的安全设计是多层次的。理解这些你才能放心地赋予它更多权限。安全门Security Gate在工具执行前security/gate.py会基于规则和机器学习分类器如果启用对操作进行风险评估。高风险操作如terminal中执行rm -rf /或python_repl中尝试导入os.system会被拦截。工具包装器每个核心工具都经过security/tool_wrapper.py的包装它在执行前后进行校验和审计。用户审批对于被安全门标记为“高风险”或“需审批”的操作前端会弹出一个对话框让你选择“允许”、“拒绝”或“允许本次会话中的所有操作”。这是最后一道也是最重要的人工防线。Docker 沙箱可选对于极度不信任的代码执行可以配置 Docker 沙箱将python_repl等操作隔离在容器中运行。我的安全实践对于个人开发环境我通常将工作空间根目录设置为项目目录并开启操作审批。我会定期查看~/.vibeworker/security_audit.log文件了解智能体尝试执行了哪些操作。对于从社区安装的陌生技能首次运行时我会格外关注其计划步骤确认它要执行的操作是否符合预期。5. 故障排除与性能优化即使设计再完善在实际使用中也可能遇到问题。这里记录了一些常见问题的排查思路和优化经验。5.1 常见问题速查表问题现象可能原因排查步骤与解决方案前端无法连接后端后端服务未启动端口被占用CORS 问题。1. 检查./start.sh status或查看进程。2. 检查localhost:8088端口是否被其他程序占用。3. 查看后端日志 (backend/app.py输出) 是否有错误。智能体不响应或响应慢LLM API 连接失败模型池配置错误网络问题。1. 在前端“设置-模型”页测试模型连接。2. 检查model_pool.json中的api_key和base_url是否正确。3. 查看浏览器开发者工具 Network 标签看/api/chat请求是否长时间挂起或返回错误。记忆搜索返回无关内容嵌入模型未正常工作记忆索引未更新。1. 确认model_pool.json中embedding场景分配的模型有效且可访问。2. 尝试在“记忆”面板手动点击“重建索引”。3. 检查嵌入模型的上下文窗口是否设置过小。技能未被识别或调用SKILL.md格式错误技能未加载。1. 检查SKILL.md文件语法确保是有效的 Markdown。2. 在前端“技能-本地”列表查看技能是否加载成功。3. 重启后端服务以重新加载所有技能。MCP 工具连接失败MCP 服务器命令或参数错误服务器本身未启动。1. 在前端 MCP 面板检查服务器状态和日志。2. 尝试在命令行手动运行 MCP 服务器命令看能否独立启动。3. 检查stdio类型服务器的命令路径是否正确。浏览器扩展不工作扩展未安装或未授权前端未连接。1. 确认扩展已安装并启用 (chrome://extensions/)。2. 在前端设置中完成扩展的授权流程。3. 刷新前端页面和浏览器标签页。磁盘空间占用过大缓存文件或记忆日志过多。1. 定期在前端“缓存”面板清理过期缓存。2. 在“记忆”面板触发“压缩记忆”和“归档日志”。3. 调整.env中的MEMORY_ARCHIVE_DAYS减少日志保留时间。5.2 性能优化建议使用本地嵌入模型这是提升记忆检索速度和消除相关成本最有效的一步。all-MiniLM-L6-v2是一个很好的平衡速度和精度的选择。合理配置模型池将轻量、快速、低成本的模型分配给embedding和translate场景。将强大但昂贵的模型如 GPT-4专用于llm场景。善用缓存对fetch_url和prompt缓存保持开启。对于重复性高的自动化任务可以阶段性开启LLM_CACHE进行测试但生产环境需谨慎评估。管理记忆规模定期进行记忆压缩。删除不再需要的、低显着性salience的记忆。庞大的记忆库会拖慢检索速度。优化技能指令在SKILL.md中提供清晰、具体的指令减少智能体的“思考”歧义可以缩短响应时间。明确的步骤和条件判断能引导它更直接地调用工具。监控资源使用关注后端进程的内存和 CPU 占用。如果长期运行后内存持续增长可能是内存缓存L1或会话数据未及时释放可以考虑定期重启服务。5.3 调试与日志查看当遇到复杂问题时查看日志是必须的。后端日志直接查看运行python app.py的终端输出。这里包含了 FastAPI 的访问日志、工具调用的详细信息、MCP 连接状态等。启动时添加--log-level DEBUG参数可以获得更详细的日志。前端日志打开浏览器开发者工具 (F12)查看 Console 和 Network 标签页。Console 会显示前端错误Network 可以查看所有 API 请求和响应特别是/api/chat的 Server-Sent Events (SSE) 流。审计日志安全相关的操作会记录在~/.vibeworker/security_audit.log中。检查器面板VibeWorker 前端右侧的“检查器”面板是强大的调试工具。你可以实时看到系统提示词是如何组装的、智能体每一步的“思考”过程、调用了哪些工具及其参数和结果。这是理解智能体决策逻辑的最佳窗口。一个真实的调试案例智能体总是错误地调用一个 MCP 工具。通过检查器面板我发现是 MCP 服务器提供的工具描述过于模糊导致智能体在匹配时出错。我的解决方案是在前端 MCP 面板中找到该工具手动编辑其description字段使其更精确地描述工具的功能和适用场景问题得以解决。VibeWorker 的魅力在于它将强大的 AI 能力与高度的透明性、可定制性结合在了一起。它不是一个完美的成品而是一个充满可能性的平台。你可以从简单的个人助理开始随着对其理解的深入逐步将它打造成一个深度融入你工作流、真正理解你需求的智能伙伴。