1. 项目概述一个真正运行在你电脑里的AI桌面助手如果你和我一样每天的工作流里充斥着各种重复性的任务打开GitHub看issue、检查邮件、整理项目文档、或者为某个代码片段写注释。这些事说大不大但累积起来就是巨大的时间黑洞。我们习惯了打开浏览器登录ChatGPT或者Claude的网页把文件拖进去问一个问题然后等待。这个过程本身其实就打断了你专注的“心流”。更别提你的项目上下文、本地文件、乃至整个工作环境对于这些云端AI来说每次对话都是一次“失忆”后的重新认识。这就是我最初被Joanium吸引的原因。它不是一个简单的聊天窗口而是一个本地优先、项目感知、可编程的AI桌面应用。你可以把它理解为一个驻扎在你操作系统里的“数字同事”。它知道你当前在哪个项目文件夹里工作能直接读取你的代码文件可以按计划自动执行任务还能在后台运行智能体帮你监控GitHub动态、总结邮件甚至在你睡觉时自动生成日报。最核心的是这一切都发生在你的本地机器上你的数据、你的项目文件无需上传到任何第三方服务器。这对于注重隐私和安全的开发者、创作者来说是决定性的优势。简单来说Joanium试图解决的不是“如何问AI一个问题”而是“如何让AI深度融入并自动化你的日常工作流”。它把AI从一个被动的问答工具变成了一个主动的、可配置的自动化伙伴。接下来我会带你深入拆解它的核心设计、手把手教你如何从零开始部署和定制并分享我在实际使用中积累的一些关键技巧和避坑经验。2. 核心设计理念与架构解析2.1 为什么是“本地优先”与“项目感知”在深入功能之前理解Joanium的这两个核心设计理念至关重要。这决定了它和主流云AI产品的根本区别。本地优先意味着所有核心处理逻辑和数据存储都优先发生在你的计算机上。当你与Joanium对话时你项目文件的读取、终端命令的执行、乃至部分模型的推理如果使用Ollama等本地模型都在本地完成。只有当你调用需要外部API的功能如使用OpenAI的GPT-4时才会向对应的服务商发送请求但对话历史、项目上下文等元数据依然留在本地。这种设计带来了几个直接好处隐私与安全敏感的源代码、内部文档无需离开你的设备。速度与低延迟文件读取、上下文加载几乎是瞬时的没有网络上传下载的延迟。离线能力配合本地模型你可以在完全无网络的环境下使用基础功能。成本可控你可以精细控制哪些任务使用昂贵的云端模型哪些使用免费的本地模型。项目感知是Joanium作为“桌面助手”而非“网页应用”的灵魂。它不是一个孤立的聊天应用而是与你当前的工作目录深度绑定。当你打开Joanium并指向一个项目文件夹后它就获得了这个项目的“上帝视角”。它可以通过文件系统API直接遍历目录结构读取任何文本文件如.py,.js,.md,.txt等并将这些内容作为对话的上下文。这意味着你不需要每次都说“这是我的main.py文件内容请分析一下”Joanium已经知道了。这种设计极大地减少了上下文传递的摩擦让AI更像是你团队里一个熟悉项目历史的成员。2.2 核心架构分层从界面到执行引擎Joanium作为一个基于Electron的跨平台桌面应用其内部架构可以清晰地分为几个层次理解它们有助于后续的深度定制和问题排查。渲染进程 (Renderer Process)这是用户直接交互的部分由Web技术HTML, CSS, React/Vue等构建的UI界面。它负责展示聊天窗口、自动化任务列表、设置面板等。所有用户操作点击、输入都在这里发起。主进程 (Main Process)Electron应用的核心拥有访问Node.js全部API的能力。它负责创建和管理应用窗口、处理系统托盘、菜单以及作为渲染进程与底层操作系统能力之间的桥梁。在Joanium中主进程还管理着应用的生命周期和核心服务。核心服务层 (Core Services)这是Joanium的“大脑”。它运行在主进程或独立的Node.js工作线程中包含几个关键模块对话引擎管理聊天会话处理用户输入调用不同的AI模型提供商OpenAI, Anthropic, Ollama等并维护对话历史。项目管理器负责加载、索引和监控当前活动项目中的文件为对话引擎提供上下文。自动化调度器一个基于Cron或类似机制的任务调度系统负责在指定时间触发预设的自动化工作流。技能/人格加载器解析和加载用户定义的“技能”文档和“人格”配置用以扩展AI的能力和调整其行为风格。集成客户端封装了与第三方服务GitHub, Gmail, Google Drive等通信的客户端逻辑处理OAuth认证和API调用。数据持久层 (Persistence Layer)所有数据聊天记录、项目配置、自动化任务定义、API密钥都存储在本地。通常位于用户的应用数据目录下如~/.joanium或%APPDATA%\Joanium。Joanium使用本地数据库如SQLite或结构化文件如JSON来管理这些状态确保应用重启后一切如常。扩展层 (Extension Layer)通过MCP (Model Context Protocol)和支持插件机制Joanium可以接入外部工具。MCP服务器可以暴露一系列工具函数如查询数据库、调用内部APIJoanium的AI助手就能在对话中直接调用这些工具极大地扩展了其能力边界。这个分层架构确保了UI的响应性、核心逻辑的稳定性以及良好的可扩展性。当你遇到界面卡顿时问题可能出在渲染进程如果自动化任务没执行则需要检查调度器服务。3. 从零开始安装、配置与核心功能上手3.1 环境准备与安装部署Joanium的安装过程非常直观但为了确保最佳体验有些前置条件和细节需要注意。系统要求操作系统Windows 10/11, macOS 10.15, 或主流的Linux发行版如Ubuntu 20.04, Fedora, Arch。Node.js虽然桌面版应用已打包但如果你想从源码构建或开发插件需要Node.js 18或更高版本。对于绝大多数用户直接下载安装包即可。磁盘空间建议预留至少500MB空间用于存储应用本身、本地模型如果使用以及积累的聊天数据。内存至少8GB RAM。如果计划同时运行大型本地模型如70B参数的Llama 2建议16GB或更多。安装步骤详解下载安装包访问 joanium.com 点击“Download”按钮。网站会自动检测你的操作系统并提供对应的安装包Windows的.exe/.msi macOS的.dmg Linux的.AppImage或.deb/.rpm。我建议选择稳定版而非预发布版。安装与首次运行像安装任何其他软件一样运行安装程序。首次启动时Joanium会运行一个“引导向导”。关键配置AI模型提供商这是最重要的一步。向导会引导你添加至少一个AI模型的API密钥。云端模型推荐起步如果你有OpenAI、Anthropic或Google Gemini的API密钥在这里填入。这是功能最全、响应最快的方式。你可以在提供商的官网注册并获取密钥。本地模型零成本/高隐私如果你没有或不想使用付费APIJoanium完美支持Ollama。你需要先单独安装Ollama访问 ollama.com 下载然后在本地拉取一个模型例如在终端运行ollama pull llama3.2:1b这是一个较小的模型。之后在Joanium的模型设置里选择“Ollama”作为提供商它会自动检测本地运行的Ollama服务。设置工作区引导结束后你会看到主界面。首要任务是指定一个“项目文件夹”。点击侧边栏的“项目”图标选择你常用的代码或文档目录。从此Joanium将基于这个目录进行工作。注意API密钥等敏感信息会被加密后存储在本地配置文件中。尽管如此从安全最佳实践出发不建议在公用或共享电脑上保存高权限的密钥。3.2 核心功能实战演练配置完成后我们来实际操作几个核心功能感受Joanium的与众不同。功能一项目感知的深度对话确保你已加载一个项目比如一个Python脚本的目录。在聊天输入框中你可以尝试非常自然的指令而无需附加文件“查看一下src目录下utils.py文件里calculate_stats函数的实现并告诉我有没有潜在的性能问题。”“基于当前项目的README.md为这个项目写一段简洁的推广文案。”Joanium会自动读取相关文件内容将其作为上下文提供给AI模型然后给出分析。你会在回复中看到它引用了具体的代码行或文件内容。功能二创建定时自动化任务这是将AI从“对话式”转向“代理式”的关键。点击左侧边栏的“自动化”标签页。点击“新建自动化”你会看到一个可视化的工作流编辑器或一个高级的YAML/JSON配置界面取决于版本。设置触发器选择“定时计划”配置为“每天上午9点”。添加数据源选择“GitHub”配置你的仓库地址和认证信息。选择“获取最新Issues”。添加AI处理节点选择“AI总结”提示词可以设为“请总结过去24小时内新开的和更新的issue按优先级排序并标记需要我立即关注的。”设置输出选择“系统通知”或“Slack消息”将AI总结的结果发送给你。保存并启用这个自动化。从此每天9点Joanium就会自动执行这个流程而你无需手动操作。功能三配置后台智能体智能体可以看作是更持久、更专注的自动化任务通常用于持续监控或定期分析。在“智能体”页面点击“新建智能体”。给它起个名字比如“每日代码审查员”。选择它要监控的项目文件夹。设置计划例如“每2小时运行一次”。编写提示词“扫描src目录下所有过去2小时内修改过的.py文件检查代码风格是否符合PEP 8并指出任何明显的逻辑错误或安全漏洞。将结果以简洁的列表形式输出。”选择输出方式比如写入一个本地的code_review_log.md文件。启用后这个智能体就会像一名尽职的审查员定期检查你的代码提交。功能四安装与使用技能/人格技能和人格是社区贡献的精华能快速赋予Joanium专业领域能力。点击“市场”或“扩展”标签页。浏览社区分享的技能例如“SQL查询分析”、“API文档生成器”、“中英技术翻译”。点击“安装”该技能通常是一个Markdown文件会被下载到本地技能库。在聊天界面你可以通过指令激活技能例如“启用‘SQL查询分析’技能然后分析下面这段SQL...”。人格的切换更简单通常在聊天界面有一个下拉选择框你可以从“默认助手”切换到“严厉的代码审查员”或“创意写作伙伴”整个对话的语气和侧重点会立刻改变。4. 高级集成与自定义开发指南4.1 深度集成第三方服务Joanium的“真集成”意味着AI助手能直接操作这些服务而不仅仅是谈论它们。以GitHub集成为例认证配置在设置-集成中找到GitHub点击连接。你会被引导至GitHub的OAuth授权页面。授权后Joanium会获得一个访问令牌并加密存储。在对话中直接操作连接成功后你可以在聊天中直接说“帮我查看‘joanium/joanium’这个仓库最新的5个PR。”“在我刚刚推送的feature分支上创建一个新的issue标题是‘讨论API设计’内容就用我当前写的这段设计文档。”“将src/components/Button.js这个文件的第30行注释翻译成中文并提交一个commit。”在自动化中使用如前所述你可以将GitHub作为数据源获取issue、PR、star数或执行动作创建issue、评论PR的节点嵌入到自动化工作流中。Gmail、Google Drive等集成的使用模式类似都是先授权后通过自然语言或自动化节点调用。4.2 利用MCP协议扩展无限可能MCP是Joanium能力边界扩展的“杀手锏”。它允许你将任何能用代码表示的工具暴露给AI。实战连接一个自定义MCP服务器以查询本地数据库为例假设你有一个本地的SQLite数据库sales.db你想让Joanium能查询它。编写MCP服务器你需要创建一个简单的Node.js脚本实现MCP协议。核心是定义一个工具Tool例如query_sales。// mcp-server-sales.js const { Server } require(modelcontextprotocol/sdk/server); const { SqliteTool } require(modelcontextprotocol/sdk/tools); const sqlite3 require(sqlite3).verbose(); const db new sqlite3.Database(sales.db); const server new Server({ name: sales-database-mcp, version: 1.0.0, }, { capabilities: { tools: {} } }); const querySalesTool new SqliteTool({ name: query_sales, description: Execute a SQL query on the local sales database., // 定义输入参数一个SQL查询字符串 inputSchema: { type: object, properties: { query: { type: string, description: The SQL query to execute } }, required: [query] } }, async (args) { return new Promise((resolve, reject) { db.all(args.query, [], (err, rows) { if (err) reject(new Error(Query failed: ${err.message})); resolve(JSON.stringify(rows, null, 2)); }); }); }); server.registerTool(querySalesTool); server.listen();在Joanium中配置MCP连接在Joanium的设置-高级或集成页面找到MCP配置。添加一个新的MCP服务器连接指定你刚刚编写的脚本路径或如果服务器运行在某个网络端口则提供URL。在对话中使用配置成功后你就可以直接对Joanium说“使用sales数据库工具查询一下上个月销售额最高的前5个产品。” Joanium会自动调用你注册的query_sales工具执行查询并返回结果。通过MCP你可以将内部系统、专有API、硬件控制等任何能力接入Joanium使其成为一个统一的AI控制中枢。4.3 开发自定义技能与人格技能和人格的本质都是文本文件这使其极易创建和分享。创建一个人格文件(senior_engineer.persona.md)# Senior Software Engineer Persona ## Core Identity You are a seasoned software engineer with 15 years of experience in building scalable backend systems. You are pragmatic, detail-oriented, and have a strong focus on performance, security, and maintainability. You communicate in a direct and concise manner. ## Communication Style - Use technical terminology precisely. - Prefer bullet points and numbered lists for complex explanations. - Always consider edge cases and failure modes. - When reviewing code, follow this pattern: 1) Praise whats good, 2) Identify concrete issues, 3) Suggest specific improvements. - Ask clarifying questions if requirements are ambiguous. ## Knowledge Bias - Deep expertise in distributed systems, database design, and API development. - Strong advocate for clean code, testing, and observability. - Skeptical of over-engineering; favor simple, proven solutions.将这个文件放入Joanium的personas目录具体路径可在设置中查看重启应用或刷新列表后你就可以在人格下拉框中选择“Senior Software Engineer”。之后的所有对话AI都会尝试模仿这位资深工程师的思维和口吻。创建一个技能文件(generate_api_doc.skill.md)# Skill: Generate API Documentation from Code ## Purpose This skill enables the assistant to analyze a given code file (primarily focusing on function/class definitions) and generate a standardized API documentation snippet in Markdown format. ## Input Expectations The user will provide or point to a code file. The assistant should automatically locate function signatures, class definitions, method parameters, and return types. ## Output Format Generate documentation in the following template:function_name(parameter1: type, parameter2: type) - return_typeDescription:[One-line description]Parameters:parameter1(type): [Description]parameter2(type): [Description]Returns:[Description of return value]Example Usage:python ...## Workflow 1. Parse the provided code. 2. Identify all public functions/classes. 3. For each, extract signature and any existing docstring. 4. Fill the template above. If docstring exists, use it; otherwise, generate a concise description. 5. Present the generated documentation in a single code block.将此文件放入skills目录。当用户说“启用‘生成API文档’技能然后为这个api.py文件生成文档”时AI会遵循技能中定义的流程和格式来输出结果确保输出的一致性和专业性。5. 性能调优、问题排查与实战心得5.1 性能优化与资源管理随着使用深入你可能会添加大量自动化任务、智能体并积累很长的聊天历史这时一些性能优化技巧就很有用。聊天历史管理Joanium默认会保存所有项目的所有对话历史。对于活跃项目这可能导致数据库文件增长。定期在设置中清理老旧或不重要项目的聊天历史可以释放空间并提升搜索速度。我通常保留最近1个月的核心项目历史其他归档。项目索引优化Joanium在加载大型项目如包含node_modules或大量二进制文件的目录时可能会变慢。你可以在项目设置中创建一个.joaniumignore文件类似于.gitignore忽略不需要被索引的目录或文件类型例如node_modules/ *.log *.zip .env build/ dist/模型选择策略合理分配任务到不同模型是平衡成本、速度和效果的关键。我的策略是复杂推理/创意写作使用最强的云端模型如Claude Opus, GPT-4。日常代码辅助/文档生成使用性价比较高的模型如Claude Haiku, GPT-3.5-Turbo。简单的文本处理/格式化使用本地Ollama运行的小模型如Phi-3-mini, Llama 3.2 1B。这几乎零成本且响应极快。在自动化任务中可以通过配置为不同节点指定不同的模型提供商。自动化任务调度避免将所有任务集中在同一分钟触发特别是那些需要调用外部API的任务。将任务错开时间可以减少瞬时负载和潜在的API速率限制问题。5.2 常见问题与解决方案速查表以下是我在长期使用中遇到的一些典型问题及其解决方法。问题现象可能原因排查步骤与解决方案聊天无响应或报“模型调用失败”1. API密钥失效或额度不足。2. 网络连接问题。3. 本地模型服务未启动。1. 检查设置中的API密钥状态去提供商后台确认额度。2. 尝试在Joanium内访问一个网页检查网络。3. 如果使用Ollama在终端运行ollama list确认服务运行且模型已拉取。自动化任务未按计划执行1. 任务未启用。2. 系统休眠/关机。3. 任务配置错误如Cron表达式错误。4. 依赖的服务认证过期。1. 在自动化列表确认任务开关已打开。2. 确保电脑在计划时间未休眠可调整电源设置。3. 仔细检查Cron表达式可用在线工具验证。4. 检查集成如Gmail、GitHub的OAuth令牌是否过期重新认证。AI助手无法读取项目文件1. 未正确设置或切换项目文件夹。2. 文件权限不足。3. 文件编码不被支持。1. 确认聊天窗口顶部显示的项目路径是否正确。2. 检查Joanium应用是否有权限读取该目录特别是macOS/Linux的权限设置。3. Joanium主要处理UTF-8文本文件尝试用其他编辑器打开文件确认非二进制。界面卡顿或内存占用高1. 聊天历史过长。2. 同时运行过多后台智能体。3. Electron应用本身的内存泄漏。1. 清理历史记录见上文。2. 暂停非必要的智能体。3. 重启Joanium应用。如果问题持续检查是否有新版本更新。MCP工具调用失败1. MCP服务器未运行或路径错误。2. 工具定义与调用参数不匹配。3. 服务器内部错误。1. 在设置中检查MCP服务器配置手动在终端启动服务器脚本看是否有报错。2. 检查AI调用的参数是否完全符合工具定义的inputSchema。3. 查看Joanium的日志文件通常在设置中可找到日志路径里面会有详细的错误信息。5.3 实战心得与进阶技巧提示词工程在自动化中的关键作用自动化任务中的AI节点其提示词质量直接决定输出效果。要具体、明确并定义好输出格式。例如与其说“总结这些issue”不如说“请用中文以表格形式总结包含‘Issue编号’、‘标题’、‘优先级高/中/低’、‘一句话摘要’四列并按优先级从高到低排序”。利用“技能”作为提示词模板库将你反复使用的、有效的复杂提示词保存为技能。例如一个“代码重构建议”技能里面可以包含详细的代码审查清单和重构原则。这样每次调用时你只需要说“启用代码重构技能看看这段代码”而不必重新编写长篇提示词。项目隔离与上下文管理为不同的工作内容创建不同的项目文件夹。例如一个用于“A公司后端项目”一个用于“个人博客写作”。Joanium会为每个项目维护独立的聊天历史和环境上下文避免信息交叉污染。备份你的配置你的自动化工作流、技能、人格以及API密钥配置加密后都存储在本地目录。定期备份~/.joanium或对应系统路径下的config和data文件夹可以在重装系统或更换电脑时快速恢复你的专属AI工作流。从社区获取灵感多逛逛Joanium的官方市场或GitHub Discussions。看看别人分享了什么有趣的技能和人格或者如何用自动化解决特定问题。很多创意用法可能你根本没想到。