1. 项目概述为你的知识库注入AI思维伙伴如果你和我一样是个重度Obsidian用户每天在笔记里敲打文字、构建知识网络那你肯定也想过要是写作时能有个“外脑”随时给点灵感或补全句子该多好。不是那种生硬的模板填充而是真正理解上下文能顺着你的思路给出智能建议的伙伴。这就是我今天要详细拆解的Obsidian插件——Companion。它不是一个简单的文本预测工具而是一个深度集成在Obsidian编辑器中的AI自动补全引擎。它的核心价值在于将GPT-3.5、ChatGPT乃至本地运行的Ollama模型等大型语言模型的强大生成能力无缝地编织进你的日常写作流里以近乎零干扰的“幽灵文本”形式在你敲下每一个字符时提供恰到好处的续写建议。简单来说Companion让你在Obsidian里写笔记能获得类似GitHub Copilot写代码般的流畅体验。无论你是学生整理课堂笔记时卡壳研究员撰写文献综述时需要灵感拓展还是知识工作者构建个人知识体系时希望行文更连贯它都能显著提升你的写作效率和思维流畅度。这个插件的巧妙之处在于它没有试图改变你使用Obsidian的习惯而是作为一个安静的助手在你需要时出现你可以用Tab键一键采纳也可以完全无视继续自己的思考。接下来我会从设计思路、详细配置、深度使用技巧到疑难排错带你彻底玩转这个生产力利器。2. 核心设计思路与方案选型解析2.1 为何选择“行内建议”而非“对话面板”Companion的设计哲学非常明确最小化干扰最大化沉浸感。这与许多其他AI笔记插件如提供侧边栏聊天机器人的思路截然不同。后者的模式是“中断-响应-继续”你需要主动唤起一个面板输入指令等待回复再将其复制到编辑器中。这个过程打断了心流破坏了写作的连续性。Companion借鉴了现代IDE中代码补全的思路采用了“行内建议”Inline Suggestion模式。当你打字时灰色的“幽灵文本”会直接出现在光标后方预测你可能想写的内容。这种设计的优势在于上下文感知极强建议是基于光标前整段文本的语义生成的而不仅仅是前一个词。模型能看到你正在构建的完整段落甚至笔记的局部结构。操作路径极短接受建议只需按一下Tab键拒绝建议则直接继续打字幽灵文本会自动消失。整个交互在毫秒级内完成几乎无感。促进发散思维有时AI给出的建议可能不是你原本想写的但却启发了你新的思考方向。这种非侵入式的提示比主动提问更能激发创造性联想。这个功能的核心依赖于一个底层库codemirror-companion-extension。这是开发者基于saminzadeh/codemirror-extension-inline-suggestion定制的分支专门为适配Obsidian的CodeMirror 6编辑器做了优化。它负责处理幽灵文本的渲染、光标交互和与上层AI服务的通信是插件流畅体验的技术基石。2.2 多模型支持背后的策略云端、高速与本地化Companion没有将自己绑定在单一AI服务上而是提供了多元化的模型后端选择这体现了其应对不同用户需求的灵活性。我们可以把这些选项分为三类云端全能型OpenAI包括gpt-3.5-turbo-instruct和gpt-3.5-turbo等模型。这是最稳定、能力最均衡的选择。OpenAI的API经过充分验证在代码、创意写作、逻辑推理等方面表现可靠。缺点是可能产生持续的使用费用并且对于网络环境有要求。云端高速型Groq这是当前撰写本文时一个极具吸引力的选择。Groq以其独特的LPU语言处理单元硬件架构著称能提供惊人的推理速度响应延迟极低。对于追求“即打即现”体验的用户来说Groq几乎是目前最快的选择。更重要的是在其付费计划正式推出前提供了非常慷慨的免费额度性价比极高。本地私密型Ollama这是为注重隐私、希望完全控制数据或希望无限制使用的用户准备的方案。通过在本机运行Ollama服务并部署小型高效的模型如phi-3-mini,llama3:8b你可以在完全不连接互联网的情况下使用AI补全。虽然小模型的“智商”可能略逊于大型云端模型但对于笔记续写、短语补全这类任务其表现已足够出色且彻底解决了延迟和费用问题。注意模型的选择并非一成不变。我个人的经验是在需要高质量、创造性续写时如撰写文章草稿使用OpenAI或Groq在日常琐碎记录、整理资料时切换到本地的Ollama模型既能保证隐私又能获得流畅的体验。Companion允许你在设置中快速切换非常方便。2.3 预设功能打造属于你的专属写作模式“预设”Presets是Companion一个被低估但极其强大的功能。它解决了AI补全中的一个核心矛盾不同的写作场景需要不同的AI行为。例如撰写严谨的技术文档你可能希望模型更保守、更准确减少天马行空的发挥。这时可以调低“随机性”Temperature参数并启用“禁止重复”等惩罚。进行头脑风暴或创意写作则需要更高的创造性和多样性可以调高Temperature让AI给出更大胆的建议。非英语写作你可能需要为模型设置特定的系统提示词强调以中文、日文或其他语言进行续写。如果没有预设每次切换场景都需要手动调整一堆参数非常繁琐。而Companion的预设功能允许你将一整套配置包括模型提供商、API密钥、温度、最大生成长度、系统提示词等保存为一个命名的预设。更妙的是你可以为任何一个预设开启“命令”开关使其变成一个全局命令出现在Obsidian的命令面板中。实操场景我设置了三个预设“严谨模式”使用Groq低温度、“创意模式”使用OpenAI高温度和“本地速记”使用OllamaPhi-3。当我在写项目报告时我调用“严谨模式”当我在写博客草稿时切换到“创意模式”当我在记录一些私人想法时则使用“本地速记”。一键切换无缝衔接真正实现了AI助手的行为定制化。3. 从零开始的完整配置与实操指南3.1 插件安装与基础启用安装Companion最便捷的方式是通过Obsidian社区插件市场。打开Obsidian进入设置-社区插件-浏览。在搜索框中输入“Companion”找到由rizerphe开发的插件。点击安装按钮等待片刻后安装完成。回到社区插件列表找到已安装的Companion将其旁边的开关拨到开启状态。重要步骤出于安全考虑Obsidian默认禁用社区插件的核心功能。你还需要在设置-选项-核心插件下方找到第三方插件相关选项确保Companion已被完全启用。安装完成后你会在编辑器的右下角或状态栏看到一个Companion的小图标如果开启了状态栏显示。但此时它还不能工作因为我们还没有给它配置“大脑”AI模型。3.2 配置云端AI服务以Groq为例鉴于Groq目前的速度和免费策略我们以其为例配置云端服务。OpenAI的配置流程类似主要区别在于获取API Key的网站。获取Groq API Key访问 GroqCloud 控制台 。使用你的Google或GitHub账号登录或注册新账号。登录后在控制台界面通常可以在侧边栏或顶部找到API Keys选项。点击Create API Key为其命名如“Obsidian-Companion”然后创建。创建后立即复制这串密钥它只会显示一次。在Companion中配置打开Obsidian设置左侧找到Companion选项页。在Provider下拉菜单中选择groq。将刚才复制的API Key粘贴到API Key字段中。Model选择Groq提供了多个模型如mixtral-8x7b-32768,llama3-70b-8192等。对于文本补全mixtral-8x7b-32768是一个在速度和能力上都很平衡的选择。llama3-70b-8192能力更强但稍慢。关键参数解析Max Tokens每次建议生成的最大长度。设置太短如20可能只能补全一个词设置太长如200可能导致生成无关内容。建议从60开始尝试这个长度足以补全一个句子或一个短段落。Temperature控制生成文本的随机性。范围0~2。值越低如0.3输出越确定、保守值越高如0.8输出越有创意、多样。对于笔记补全0.7是一个不错的起点。Delay触发建议前的延迟毫秒数。设置过短如300ms可能导致你每打一个字就触发一次造成干扰设置过长如1500ms则响应迟钝。800ms是一个比较舒适的数值。启用与测试配置完成后关闭设置页面。新建或打开一个笔记开始打字。当你暂停约800毫秒后应该能看到灰色的幽灵文本出现在光标后。按下Tab键接受当前建议的一个词继续按可以连续接受。直接继续打字则会忽略建议。3.3 配置本地AI服务Ollama对于追求完全离线、零延迟或隐私至上的用户Ollama是完美选择。安装并运行Ollama前往 Ollama官网 下载对应你操作系统Windows/macOS/Linux的安装包。安装后打开终端或命令提示符/PowerShell运行ollama serve来启动服务。通常安装后它会自动作为后台服务运行你可以通过ollama list命令检查是否运行正常。拉取一个轻量级模型在终端中运行ollama pull phi3:mini。Phi-3-mini是微软出品的一个3.8B参数小模型在常识推理和语言任务上表现优异体积小速度快非常适合本地补全任务。你也可以选择llama3:8b等模型但体积和资源消耗会更大。在Companion中配置在Companion设置中将Provider切换为ollama。API Key字段留空。Model字段填入你拉取的模型名称如phi3:mini。Base URL通常是http://localhost:11434。这是Ollama服务的默认地址。调整参数由于本地模型能力稍弱可以将Max Tokens设为40Temperature设为0.5以获得更聚焦、更准确的建议。Delay可以设得更短比如500ms因为本地调用几乎没有网络延迟。性能调优心得如果你的电脑内存有限如8GB运行Ollama模型时可能会感到Obsidian略有卡顿。建议在不需要AI补全时在命令面板执行Companion: Toggle Completion来临时关闭它。本地模型的质量高度依赖于你选择的模型。对于简单的短语补全和语言续写phi3:mini绰绰有余。如果你需要它进行更复杂的文本生成如根据大纲写段落可能需要考虑llama3:8b或更大的模型但这会对硬件提出更高要求。3.4 移动端适配与使用技巧Obsidian的移动端体验同样重要。Companion在移动端的配置逻辑与桌面端一致但操作方式需要适配触摸屏。配置移动工具栏在手机或平板上打开Obsidian App。点击右上角的...更多按钮进入设置。找到移动端设置项。进入更多工具栏选项。在长长的命令列表中找到Companion: Accept completion命令点击旁边的号将其添加到你的编辑工具栏。移动端使用当你用移动端键盘打字时AI建议同样会以幽灵文本出现。要接受建议你不再能按Tab键而是需要点击刚才添加到工具栏的那个按钮图标可能是一个向右的箭头或对勾。点击一次接受一个词。实操心得在移动端由于屏幕空间小频繁点击工具栏按钮可能不太方便。我的习惯是只有当AI给出的建议非常符合我心意比如一整句都猜对了时才去点击接受。对于零散的单词补全更多是把它当作灵感参考然后手动输入。移动端更适合“灵感捕捉”而非“高效补全”。4. 高级功能与场景化应用实战4.1 利用“系统提示词”塑造AI角色这是Companion的一个隐藏王牌功能。在设置页面的高级选项里你可以找到System Prompt输入框。这里填入的文本会在每次请求AI补全时作为系统指令发送给模型从而从根本上影响AI的行为模式。几个实用的提示词模板学术写作助手你是一个严谨的学术写作助手。请用专业、客观、简洁的语言续写用户的文本。避免使用口语化表达和夸张的修辞。确保事实准确逻辑清晰。这会让AI的建议更偏向于论文、报告风格。创意写作伙伴你是一个富有想象力和文采的创意写作伙伴。请用生动、形象、富有感染力的语言续写用户的文本。可以适当使用比喻、拟人等修辞手法。这适用于写小说、诗歌、博客等创意内容。非英语写作你是一个中文写作助手。请始终使用流畅、地道的中文进行续写。遵循中文的语法和表达习惯。这对于主要使用中文笔记的用户至关重要能极大提高AI补全中文内容的质量和相关性。特定领域专家你是一个经验丰富的软件工程师。请用技术准确、逻辑严密的语言续写关于编程、系统设计或技术方案的文本。当你在一个特定的技术笔记中工作时这样的提示词能让AI的建议更“在行”。重要提示系统提示词会占用一部分Token额度并影响生成速度。请保持提示词简洁明了。效果需要在实际写作中微调不同的模型对提示词的敏感度也不同。4.2 预设功能的深度应用工作流自动化我们之前提到了预设的快速切换。但它的威力不止于此。结合Obsidian的“自定义快捷键”和“QuickAdd”等插件你可以构建自动化的工作流。场景我经常需要写两种固定格式的笔记会议纪要和读书笔记。我希望在写这两种笔记时AI能自动切换到不同的模式。实现步骤在Companion设置中创建两个预设“会议纪要模式”和“读书笔记模式”。“会议纪要模式”使用Groq低温度0.2系统提示词为“请以简洁、条理清晰的要点形式续写总结讨论内容和行动项。”“读书笔记模式”使用本地Ollama中等温度0.6系统提示词为“请以分析、评论和关联个人知识的方式续写读书心得。”为这两个预设都启用“Command”开关。安装“QuickAdd”插件。为其配置两个“Choice”。Choice 1: “新建会议纪要”。动作为使用模板创建新笔记你的会议纪要模板然后执行命令“Companion: 应用预设 - 会议纪要模式”。Choice 2: “新建读书笔记”。动作为使用模板创建新笔记然后执行命令“Companion: 应用预设 - 读书笔记模式”。现在当我通过QuickAdd创建一份新的会议纪要时Companion会自动切换到严谨的要点总结模式创建读书笔记时则会切换到富有启发性的分析模式。这实现了基于笔记类型的智能上下文切换。4.3 与Obsidian生态的联动Dataview与TemplaterCompanion的补全能力可以和你现有的Obsidian工作流产生奇妙的化学反应。与Dataview查询结合当你在笔记中编写Dataview查询代码块时Companion可以基于你已有的笔记元数据标签、日期、内容来帮你补全查询语句。例如你输入TABLE file.name, date FROM它可能会建议你补全一个常用的标签路径。与Templater模板结合在使用Templater插件插入动态模板时AI可以基于模板的上下文进行补全。例如在一个每日日志模板中你刚输入“今日重点工作”AI可能会根据你之前日志的规律建议“1. 完成项目A的评审2. 与团队同步B进展”。一个具体案例我在一个项目跟踪笔记中使用Dataview表格汇总所有带有#project/active标签的任务。当我编辑这个笔记在表格下方输入“下一步需要优先处理的是”Companion通过分析表格中的任务标题和状态可能会给出“客户演示文稿的最终修订因为它本周截止”这样的建议。这相当于你的笔记数据直接成为了AI建议的燃料。5. 常见问题、性能优化与排错指南即使配置得当在实际使用中也可能遇到各种小问题。这里我汇总了从社区和个人使用中积累的常见问题与解决方案。5.1 为什么没有幽灵文本出现问题排查流程图这是最常见的问题。请按以下步骤系统排查步骤检查项可能原因与解决方案1. 基础状态插件是否已启用去设置 - 社区插件确认Companion开关已打开。2. 功能开关补全功能是否已开启按Ctrl/Cmd P搜索并执行Companion: Toggle Completion。这是一个开关命令确保它处于开启状态。编辑器右下角状态栏图标应有激活标识。3. 模型与配置当前预设/提供商配置是否正确检查Companion设置中的Provider和Model是否选择正确。例如选了Ollama但本地服务未启动。4. API密钥API Key是否有效对于OpenAI/Groq密钥可能过期或输入有误。尝试去对应平台重新生成一个。对于Ollama确保Base URL正确默认http://localhost:11434。5. 网络与连接能否连接到API服务对于云端服务检查网络连接。对于Ollama在浏览器中访问http://localhost:11434/api/tags看是否能返回已下载的模型列表。6. 触发条件是否达到了触发条件检查设置中的Delay延迟。如果你打字非常快且不停顿可能永远不会触发。尝试放慢速度或在句末停顿一下。7. 编辑器模式是否在源代码模式某些Obsidian主题或插件可能导致在“源代码”模式下补全不工作。尝试切换到“实时预览”模式。8. 冲突插件是否有其他插件冲突暂时禁用其他可能与编辑器交互的插件如另一种AI工具、增强编辑插件等进行测试。5.2 建议质量不佳或偏离主题怎么办AI补全的质量受多种因素影响可以针对性调整调整Temperature参数如果建议太天马行空降低Temperature如从0.8调到0.3如果建议太死板、重复适当调高如到0.7。优化系统提示词这是最有效的手段。明确告诉AI你想要的风格和角色。例如加入“请严格基于上文逻辑进行续写不要引入新概念”。检查上下文长度Companion会发送光标前一定长度的文本作为上下文。如果这个上下文太短比如只有几个词AI可能无法理解你的意图。确保你是在一个有一定内容的段落后面进行续写。尝试不同模型不同模型有不同“性格”。GPT-3.5-Turbo-Instruct在指令跟随上可能更直接而ChatGPT模型可能更对话化。Groq的Llama3系列在逻辑性上表现突出而Mixtral则更均衡。本地模型如Phi-3在简单续写上效率很高。利用“禁止重复”惩罚在高级设置中可以调整“频率惩罚”和“存在惩罚”来减少重复用词和重复话题。5.3 性能优化让补全更快更省资源降低延迟与Token数将Delay设置为500-800msMax Tokens设置为40-80。这能减少等待时间并避免生成过长无关内容。云端模型选择如果使用Groq或OpenAI选择响应速度更快的模型。例如Groq的mixtral-8x7b通常比llama3-70b响应更快。本地模型轻量化对于Ollama使用量化版本的小模型如phi3:mini:4k或llama3:8b:q4_0。量化能大幅减少内存占用和提升推理速度。按需启用不需要时通过命令面板关闭补全功能。可以为此设置一个快捷键设置 - 快捷键 - 搜索“Toggle Completion”方便快速开关。管理预设只保留常用的几个预设避免加载过多配置。5.4 移动端特有的问题工具栏按钮不显示建议移动端的“接受建议”按钮只在当前有幽灵文本出现时才有效。如果没出现幽灵文本请先按桌面端的排查步骤检查。耗电与发热持续使用云端AI补全会频繁调用网络和进行计算可能导致移动设备耗电增加。建议在移动端使用本地Ollama模型如果手机性能足够或将Delay调高以减少请求频率。键盘遮挡在某些情况下虚拟键盘可能会遮挡输入区域和幽灵文本。这是Obsidian App本身的布局问题暂时没有完美解决方案可以尝试调整编辑器字体大小或使用分屏模式。5.5 安全与隐私考量云端服务使用OpenAI、Groq等云端API时你的文本内容作为提示词上下文会被发送到其服务器。请勿使用这些服务处理高度敏感或机密的信息。仔细阅读相关服务商的隐私政策。本地服务Ollama方案将所有数据保留在本地是隐私敏感场景的唯一推荐选择。确保你的Ollama服务没有暴露在公网上默认不会。API密钥管理妥善保管你的API密钥。不要在公共场合分享包含密钥的配置文件或截图。Obsidian的插件设置文件通常是明文存储可以考虑使用环境变量等更安全的方式管理密钥部分插件支持需查看具体实现。经过以上从原理到实操从配置到排错的全面梳理相信你已经能驾驭Companion这个强大的AI写作伙伴了。它就像给你的思维装上了一台涡轮增压器不是替代你思考而是让你的思考流更加顺畅澎湃。真正的秘诀在于根据不同的任务场景灵活组合不同的模型和预设让它真正成为你工作流中得心应手的一部分。