Tolaria AI 架构全解双路径 AI 面板、CLI Agent 权限模式与外部 MCP 集成【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 是一款用于管理 Markdown 知识库vault的桌面应用其 AI 能力由两条路径构成可调用工具来检查和编辑 vault 的编码 AgentCoding Agents以及以对话模式基于笔记上下文作答的直接模型目标Direct Model Targets。本文以 site/concepts/ai.md 为核心脉络结合仓库中的架构决策记录ADR与 MCP 服务器源码讲解 Tolaria 的 AI 目标模型、Vault Safe / Power User 权限语义、Agent 模型选择、直接模型提供方接入方式以及外部 MCP 工具的完整清单与调用细节。读完本文你将掌握 Tolaria 中 AI 功能从「检测 Agent → 选择权限 → 流式对话 → MCP 读写 vault → Git 审查变更」的完整工作链路。双路径 AI 架构为何同时存在 Agent 与直接模型Tolaria 的 AI 设计并非单一实现而是基于「AI 目标AI target」抽象建立的统一面板。架构决策记录 ADR-0108Direct model AI targets alongside coding agents 明确了这一模型编码 Agent 保留 Safe / Power User 权限模式与工具访问能力直接模型目标运行在 Chat 模式下接收笔记上下文与对话历史但不获得 vault 写入工具或 shell 访问权限。这一设计的历史脉络值得注意早期版本ADR-0027曾计划同时维护「Anthropic API 轻量聊天」与「CLI 子进程 Agent」两条代码路径但该方案随后被 ADR-0028CLI agent only — no direct Anthropic API key 取代——直接 API 聊天从未真正交付给用户CLI Agent 通过工具访问与 MCP 集成覆盖了全部使用场景。如今文档所述的两条路径是本地 CLI Agent桌面子进程与直接模型端点Chat 模式两者共享同一个 AI 面板与流式事件层。Coding Agents支持的 CLI 与本地检测AI 面板可以通过 Tolaria 的归一化事件层normalized event layer流式调用本地已安装的 CLI Agent。当前支持的目标包括Claude CodeCodexGitHub CopilotOpenCodePiAntigravity CLIKiroHermes AgentTolaria 会检测机器上已安装的 Agent每个 Agent 依然持有自己的认证方式、可用工具与运行时行为——Tolaria 不接管 Agent 的鉴权例如 Claude 通过claudeCLI 登录、Codex 通过codex login各自独立完成见 ADR-0062。从源码结构看这套多 Agent 支持建立在「共享运行时 薄适配器」之上ADR-0093Shared CLI agent runtime adapters 规定cli_agent_runtime.rs拥有公共的请求结构、系统/用户提示词包装、JSON-line 子进程生命周期、错误与 done 事件归一化、版本探测以及 Tolaria MCP 服务器路径解析各 Agent 专属逻辑二进制发现候选、命令参数、临时配置形态、认证错误措辞、JSON 事件映射保留在各适配器模块中例如codex_cli.rs通过codex exec --json启动并借助临时配置标志注入 Tolaria 的 MCP 服务器。Vault Safe 与 Power User 两种权限模式编码 Agent 可在两种模式下运行Vault Safe仅限文件、搜索与编辑工具是默认且最保守的模式。Power User对支持 shell 访问的 Agent允许限定在活动 vault 范围内的本地 shell 命令。该语义由 ADR-0092Vault-scoped AI agent permission modes 确立权限模式按 vault 存储取值为safe与power_user缺失或非法值一律回退到safe。前端类型定义可在 src/lib/aiAgentPermissionMode.ts 中查看其中normalizeAiAgentPermissionMode将任何非power_user的值归一到默认安全模式而 UI 上显示的控制文案即为Vault Safe与Power User。AI 面板头部会展示当前模式Agent 运行期间切换按钮被禁用切换模式不会打断已有会话而是保留对话并在本地插入一条模式变更标记。不同 Agent 对两种模式的映射刻意保持保守且并不等价ADR-0092Claude Code Safe 保留acceptEdits、严格的 Tolaria MCP 配置仅限文件/搜索/编辑工具Power User 才把 Bash 加入允许工具列表且不使用--dangerously-skip-permissions这类危险绕过标志。Codex 在两种模式下都保持活动 vault 的workspace-write沙箱与--ask-for-approval never。OpenCode 通过临时OPENCODE_CONFIG_CONTENT注入配置Safe 拒绝 bash 与外部目录Power User 允许 bash 但仍拒绝外部目录。Pi 在两种模式下当前使用同一份临时 MCP 适配器配置。这意味着Power User 不是全局万能开关而是「该 Agent 所支持的、相对更宽但仍受 vault 约束的本地工具范围」——这是 Tolaria 最小权限least-privilege默认值的一部分ADR-0074。Agent 模型选择按 Agent 记忆的设备本地偏好对能暴露可靠模型目录的 AgentAI 工作区会显示模型选择器。Tolaria 当前可以发现 Codex 的模型并暴露 Claude Code 的文档化别名documented aliases其余 Agent 继续使用自己的默认模型。模型偏好按 Agent、按设备本地存储切换 Agent 时会恢复该 Agent 上一次的选择若选择Agent default则把模型决定权交还给 CLI 本身。这套「安装本地偏好」遵循 ADR-0004 的原则——机器相关的工具偏好属于应用设置而非 vault 内容。Direct ModelsChat 模式下的直接模型目标直接模型目标运行在对话模式中接收活动笔记、关联上下文linked context与对话历史但不接收 vault 写入工具或 shell 访问。支持的提供方形态包括本地模型通过 Ollama 或 LM Studio 运行无需 API Key。托管提供方OpenAI、Anthropic、Gemini、OpenRouter 等。自定义 OpenAI 兼容端点。关于密钥处理ADR-0108 给出了明确边界提供方元数据存入应用设置但API 密钥不写入设置——托管提供方要么把密钥保存在 Tolaria 本地应用数据 secrets 文件中该文件位于 vault 之外、项目 worktree 之外且在 Unix 上以 owner-only 文件权限写入要么从指定的环境变量读取本地提供方Ollama/LM Studio可无密钥运行。状态栏因此成为跨 Agent 与已配置模型目标之间的快速切换器。外部 MCP 设置显式、可逆、vault 中立Tolaria 对外暴露一个 MCP 服务器供外部工具使用。设置流程可以把 Tolaria 的 MCP 条目写入以下目标Claude CodeAntigravity CLICursor通用 MCP 配置路径同时也可以复制一段精确的 JSON 片段用于手动配置。关键设计在于MCP 设置是显式的关闭对话框不会触碰任何第三方配置文件ADR-0074。早期版本曾在桌面启动时自动向 Claude Code / Cursor 配置文件写入 MCP 注册如今已被移除——新安装不会修改~/.claude/mcp.json或~/.cursor/mcp.json除非用户在命令面板或状态栏触发的设置流程中明确确认。同时注册条目是vault 中立的ADR-0119Vault-neutral MCP registration with mounted workspace guidance外部 MCP 条目只包含 Node 命令、mcp-server/index.js与WS_UI_PORT9711不再写入固定的VAULT_PATH。vault 解析发生在每次工具调用时——显式的VAULT_PATH/VAULT_PATHS环境变量仍然优先用于应用侧 bridge 启动与旧版/手动启动缺失时 MCP 服务器读取 Tolaria 的vaults.jsonactive_vault优先返回vaults[]中未标记mounted: false的工作区全部纳入路径去重并忽略空路径。这意味着外部 MCP 配置在切换 vault 或挂载工作区变化后无需重新连接。MCP 工具清单读写 vault 的完整能力面Tolaria MCP 服务器入口 mcp-server/index.js工具服务 mcp-server/tool-service.js为外部 AI 工具提供 12 个工具覆盖「搜索 → 读取 → 创建 → 更新 → 追加 → UI 联动」的完整闭环工具作用关键参数search_notes按标题或内容全文搜索笔记返回路径、标题与片段query必填、limit默认 10get_vault_context获取活动 vault 概览实体类型、AGENTS.md 指令、笔记数、文件夹、最近笔记vaultPath可选list_vaults列出当前活动 vault含是否有 AGENTS.md 指令—attach_vault将已存在的本地文件夹注册为挂载 vault不初始化 Gitpath必填、labelclone_vault用系统 Git 配置克隆仓库并注册为挂载 vault目标已存在则拒绝remoteUrl、destinationPath均必填、labelget_note读取笔记解析后的 YAML frontmatter、markdown 内容、mtimeMspath必填、vaultPathcreate_note新建 markdown 笔记不覆盖已存在文件省略content时按title/type生成模板path必填、content、title、type、is_a、vaultPathupdate_note整体替换已有笔记内容frontmatter 正文可选expectedMtime冲突守卫path、content必填、expectedMtime、vaultPathappend_to_note向已有笔记正文末尾追加 markdown比update_note风险更低path、content必填、vaultPathopen_note在 Tolaria UI 中以新标签页打开笔记path必填、vaultPathhighlight_editor高亮 UI 元素editor/tab/properties/notelist短暂后自动消失element必填、pathrefresh_vault触发 vault 重扫让新建/修改文件立即出现在笔记列表path、vaultPath均可选几个值得深入理解的实现细节冲突守卫modification-time guardupdate_note支持可选expectedMtime参数——先用get_note拿到笔记的mtimeMs写入时若磁盘文件已变化则快速失败从而让「读-改-写」工作流更安全。工具服务中updateNote将该值透传给updateVaultNotemcp-server/tool-service.js 中的updateNote实现。写入后 UI 刷新create_note、update_note、append_to_note三个写操作在文件变更后都会触发vault_changed事件让 Tolaria 前端立即感知变化。多 vault 消歧当多个 vault 同时活动时相对路径可能产生歧义此时必须显式传入vaultPathget_note在多个 vault 均命中同一路径时会抛出歧义错误。AGENTS.md 指令注入get_vault_context会为每个活动挂载 vault 根目录检查AGENTS.md并随摘要返回mcp-server/agent-instructions.js使外部 Agent 能读取每个 vault 的本地规则。UI 桥接MCP 服务器通过 WebSocket 客户端连接ws://localhost:9711上的 UI bridgews-bridge.js把open_note、highlight_editor等动作转发给 React 前端断开后每 3 秒自动重连。从工具注解annotations看读类工具标记为readOnlyHint: true而clone_vault是唯一带openWorldHint: true的写工具因为它会向外部 Git 远程发起克隆这为支持读取意图的 MCP 客户端提供了权限提示依据。为什么 Git 对 AI 至关重要AI 生成的变更应当可审查inspectable。Git 提供了三样东西diff差异让你逐行查看 AI 改了什么历史与回滚history and rollback让你随时回到变更前的状态以及建议与已提交工作之间的清晰边界a clear boundary between suggestions and committed work——AI 的输出只是暂存于工作区的建议只有你 review 并 commit 之后才成为 vault 历史的一部分。这与 ADR-0028 中「保持单一、可审计的变更路径」的思路一脉相承无论 Agent 通过 MCP 创建、更新还是追加笔记最终都落在工作区的 markdown 文件上由 Git 全程追踪AI 与人类编辑者在版本控制层面享有同等的可审查性。实操建议把 AI 安全地接入你的 vault综合以上机制一个兼顾效率与安全的典型用法是先用 Chat 模式提问对「当前笔记讲了什么」这类无需写盘的问题选择直接模型目标如 Ollama/LM Studio 本地模型或托管端点避免为简单对话拉起完整 Agent。用 Agent 做实质编辑时保持 Vault Safe默认模式下 Agent 只能使用文件、搜索与编辑工具足以完成笔记整理、批量改写与结构重构。确需 shell 能力再升级 Power User仅在你信任的 vault 上启用且该模式仍被限制在活动 vault 范围内不会静默恢复危险的绕过标志。外部工具走显式 MCP 设置在命令面板或状态栏触发的设置流程中确认写入或在需要静态/脚本化会话时手动复制 JSON 片段并可用VAULT_PATH/VAULT_PATHS覆盖解析出的工作区集合。所有 AI 变更都过一遍 Git借助 diff 审查每一次 Agent 修改commit 后 AI 建议才正式成为知识库的一部分。Tolaria 的 AI 设计核心是把能力边界显式化Agent 与直接模型分离、权限模式按 vault 记忆、MCP 注册显式且 vault 中立、变更始终落在 Git 可追踪的 markdown 文件上。对需要将 AI 深度接入个人知识库管理流程的开发者而言这套架构同时给出了「强大的工具调用能力」与「可审查的最小权限边界」两个方向的完整实现参考。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考