Tolaria 可选择的 CLI AI Agent 架构ADR-0062 与共享面板的源码级实现【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 的 AI 面板最初只为 Claude Code 一个 CLI 服务这使每一处 UI 与后端接缝都带有单 Agent 的假设。ADR-0062 决定了引入一套「共享 CLI-Agent 抽象」前端把 Agent 视为小型注册表后端由ai_agents.rs统一负责探测与流式分发。读完本文你将理解这套抽象的前后端模型、统一的流事件协议、default_ai_agent设置为何存放在应用设置而非 vault以及如何在 Tolaria 中低成本地新增一个 CLI Agent。背景从单 CLI 依赖走向多 AgentADR-0062docs/adr/0062-selectable-cli-ai-agents.md2026-04-13状态 active给出的背景是Tolaria 的 AI 面板、引导流程onboarding和状态界面都围绕单个 CLI 依赖 Claude Code 构建。这在首个版本可行但让所有 UI 与后端接缝都变得 Agent 特化——若要加入 Codex 作为第二个受支持的 CLI Agent需要复制大量代码独立的可用性检查、第二条 onboarding 路径、另一个状态徽章、又一个流式 hook。产品方向比单一供应商更宽Tolaria 需要一个能面向多个本地 CLI Agent 的 AI 面板同时保持相同的 MCP-backed vault 工具集、相同的笔记上下文组装note-context assembly以及一个本地持久化的「默认 Agent」偏好。仓库中的 MCP 服务由 mcp-server/ 目录承载如 mcp-server/index.js 与 mcp-server/tool-service.js这是所有 Agent 共用的 vault 工具层。决策前端注册表 后端适配器层ADR 的核心决策是为 Tolaria 的所有 AI 表面引入共享的 CLI-Agent 抽象。前端把 Agent 视为一个小型注册表携带标签label、安装链接install URL、可用性状态以及持久化的default_ai_agent设置AI 面板、onboarding 门禁、命令面板和状态栏都从这个共享模型读取。后端则由 src-tauri/src/ai_agents.rs 拥有 Agent 探测与流式处理向每个 Agent 的适配器分发Claude 仍走claude_cli.rsCodex 则通过codex exec --json启动并用瞬态配置标志transient config flags注入 Tolaria 的 MCP 服务。前端Agent 注册表与默认偏好前端注册表位于 src/lib/aiAgents.ts。ADR 决策时注册表只有claude_code与codex两项当前代码中的AI_AGENT_DEFINITIONS已扩展到 8 个 Agent每个条目包含id、label、shortLabel与installUrlexport type AiAgentId | claude_code | codex | copilot | opencode | pi | antigravity | kiro | hermes export interface AiAgentDefinition { id: AiAgentId label: string shortLabel: string installUrl: string } export const DEFAULT_AI_AGENT: AiAgentId claude_code这正体现了 ADR 后果部分的第一条正面结论「新的 CLI Agent 可以通过实现一个后端适配器并注册一个前端定义来添加」。可用性模型是三态的checking/installed/missingnormalizeAiAgentsStatus()把后端 IPC 载荷归一化为该模型缺省字段一律回退为missing。注册表还承担了一层历史兼容normalizeStoredAiAgent()把旧值gemini重映射为antigravity。后端 Rust 侧的 src-tauri/src/settings.rs 中normalize_default_ai_agent()做了同样的归一gemini→antigravity其余值必须在SUPPORTED_DEFAULT_AI_AGENTS白名单内否则丢弃而AiAgentId枚举也通过#[serde(alias gemini)]保持了旧数据反序列化兼容。设置写入路径见 src/hooks/useAiAgentPreferences.tssetDefaultAiAgent()会把default_ai_agent与default_ai_target同时写入应用设置并弹出 ToastcycleDefaultAiAgent()则按注册表顺序循环切换配合 src/lib/aiAgents.ts 中的getNextAiAgentId()实现键盘式快速轮换。后端探测与流式分发src-tauri/src/ai_agents.rs 是后端的中枢。get_ai_agents_status()并行探测所有受支持的 CLIpub async fn get_ai_agents_status() - AiAgentsStatus { let claude tokio::task::spawn_blocking(availability_from_claude); let codex tokio::task::spawn_blocking(crate::codex_cli::check_cli); let copilot tokio::task::spawn_blocking(crate::copilot_cli::check_cli); // ... opencode、pi、antigravity、kiro、hermes 同理 let (claude, codex, copilot, opencode, pi, antigravity, kiro, hermes) tokio::join!( availability_or_missing(claude, AI_AGENT_STATUS_PROBE_TIMEOUT), // ... ); }这里有两个值得注意的工程细节并行探测而非串行源码注释说明每个check_cli()在二进制缺失时会回退到 login-shell 查找如/bin/zsh -lc command -v agent单个探测最长约 1 秒串行探测在没有任何 Agent 安装时会为冷启动累加数秒因此改为在 Tokio 阻塞线程池上展开用户感知的耗时变为「最慢的单个探测」。超时兜底每个探测都被availability_or_missing()包上AI_AGENT_STATUS_PROBE_TIMEOUT5 秒超时超时或 panic 统一映射为installed: false保证 IPC 永远返回完整填充的AiAgentsStatus前端可以持续渲染。文件内的测试availability_probe_timeout_returns_missing_status直接验证了该兜底行为。流式分发入口是run_ai_agent_stream()→dispatch_ai_agent_stream()。分发逻辑按 Agent 选择 runnerfn shared_agent_runnerF(agent: AiAgentId) - OptionSharedAgentRunnerF { match agent { AiAgentId::ClaudeCode None, // 走专属路径 claude_cli.rs AiAgentId::Codex Some(crate::codex_cli::run_agent_stream), AiAgentId::Copilot Some(crate::copilot_cli::run_agent_stream), // ... opencode、pi、antigravity、kiro、hermes } }非 Claude 的 Agent 统一映射到crate::cli_agent_runtime::AgentStreamRequest后交给各自的共享运行时适配器Claude 则单独流经claude_cli::run_agent_stream其事件再由map_claude_event()归一到统一事件模型。从源码结构看这条「共享 CLI 运行时」的抽取与 ADR-0093docs/adr/0093-shared-cli-agent-runtime-adapters.md一脉相承是 ADR-0062 抽象在后续演进中的落地形态。统一流事件模型Tolaria 自有的事件归一ADR 后果部分列出的第一条负面结论是事件归一化从此由 Tolaria 负责各后端适配器必须把每个 CLI 的流格式翻译成统一事件模型。该模型即AiAgentStreamEvent定义于 src-tauri/src/ai_agents.rs事件载荷语义Initsession_id会话建立TextDeltatext增量可见文本ThinkingDeltatext增量思考内容ToolStarttool_name,tool_id,input?工具调用开始ToolDonetool_id,output?工具调用结束Errormessage错误Done—流结束map_claude_event()展示了归一的具体规则Claude 的Result事件若携带非空文本会被拆成一条TextDelta空Result则直接丢弃返回None。该映射有多组单元测试覆盖如map_claude_done_event_preserves_completion_signal、map_claude_tool_events_preserve_stream_data、map_claude_empty_result_event_is_ignored保证每种事件在归一后不丢失数据。AiAgentStreamRequest则定义了统一请求面agent、可选model、message、system_prompt、vault_path与多 vault 的vault_paths、permission_mode。权限模式AiAgentPermissionModeSafe默认 /PowerUser缺省取Safe由测试stream_request_uses_default_or_explicit_permission_mode验证——对应 ADR 中「同一笔记上下文组装、同一面板」的产品约束在请求层的体现。三个候选方案及其取舍ADR 完整记录了三个候选方案方案 A选中共享 Agent 注册表 后端适配器层——一个面板、一个偏好设置、一条 onboarding 路径并为未来 CLI Agent 留出清晰的接入点。方案 BUI 保持 Claude 特化把 Codex 作为第二个特例「打补丁」式加入——短期成本最低但每新增一个 Agent 都会成倍增加定制的检查、提示词和命令处理器。方案 C按 Agent 拆分为各自独立的产品面板——单集成的所有权更清晰但会碎片化用户体验并使命令面板与状态栏的交互不一致。选 A 的实质是把 Agent 差异收敛到「注册表条目 后端适配器」两个边界其余所有表面面板、onboarding、命令面板、状态栏如 src/components/status-bar/AiAgentsBadge.tsx 与 src/components/AiAgentsOnboardingPrompt.tsx只消费共享模型。默认 Agent安装本地偏好而非 vault 配置default_ai_agent存放在应用设置app settings而非 vault 中ADR 明确指出这是为了匹配 ADR-0004 的规则——机器相关的工具偏好属于应用设置不属于 vault参见 docs/adr/0004-vault-vs-app-settings-storage.md。从源码看该偏好是「设置层」的字符串而非「vault 层」的文件内容Rust 侧 src-tauri/src/settings.rs 的Settings结构体持有default_ai_agent: OptionString与default_ai_target: OptionString保存前经normalize_settings()白名单校验。值得一提的是仓库在当前版本中又引入了default_ai_target与 Agent 平级的 API 模型目标src/lib/aiTargets.ts 用agent:/model:前缀统一了「CLI Agent」与「API 模型」两类目标对应 ADR-0108 直接模型目标resolveAiTarget()在读取存储值时会把旧的纯 Agent 值如claude_code当作 legacy 目标回退解析。这说明 ADR-0062 建立的「单一偏好位」在后续演进中被扩展成了「单一目标位」但读取、归一、回退的分层结构保持不变。Agent 列表的增长抽象经受住了扩展ADR-0062 决策时的注册表只有两个 Agent。当前AiAgentId枚举已包含 8 个变体ClaudeCode、Codex、Copilot、Opencode、Pi、Antigravity含gemini别名、Kiro、Hermes前端AI_AGENT_DEFINITIONS与之一一对应各自携带安装链接如https://docs.anthropic.com/en/docs/claude-code、https://developers.openai.com/codex/cli等见 src/lib/aiAgents.ts。新增 Agent 对应的独立 ADR 包括 docs/adr/0090-pi-cli-agent-adapter.md、docs/adr/0097-gemini-cli-agent-adapter.md、docs/adr/0147-antigravity-cli-agent-adapter.md、docs/adr/0150-github-copilot-cli-agent-adapter.md——每个新 Agent 都遵循 ADR-0062 定义的「一个后端适配器 一个前端注册表条目」的接入路径正面印证了该抽象的可扩展性。此外 src-tauri/src/ai_agents.rs 还暴露了get_ai_agent_model_catalog()Claude 的模型目录使用稳定的文档化别名sonnet/opus/haikuCodex 则带 5 秒超时地探测其本地可用模型探测失败不影响整体目录返回。这同样是「同一面板面向多 Agent」的延伸模型选择也被纳入了共享目录。边界上的 Agent 特化与再评估条件ADR 也诚实地列出了负面后果部分用户引导在边缘处重新变得 Agent 特化例如各 Agent 的安装链接即注册表中的installUrl字段与认证错误文案claudelogin 对codexlogin。这在实现中确实存在——安装提示与登录引导必须按 Agent 给出无法被共享模型完全吞并。ADR 最后给出了再评估触发条件如果某个 Agent 需要共享面板无法清晰表达的能力或 Tolaria 从 CLI 子进程转向专用本地 SDK/运行时则应重新审视该架构。小结新增一个 CLI Agent 的实际路径综合 ADR-0062 与当前源码在 Tolaria 中新增一个 CLI Agent 的完整路径是后端新建agent_cli.rs适配器实现check_cli()可用性探测与run_agent_stream()把该 CLI 的流格式翻译成AiAgentStreamEvent并在 src-tauri/src/ai_agents.rs 的shared_agent_runner()、get_ai_agents_status()中注册设置层把新 Agent 加入 src-tauri/src/settings.rs 的SUPPORTED_DEFAULT_AI_AGENTS白名单使default_ai_agent可以持久化该值前端在 src/lib/aiAgents.ts 的AI_AGENT_DEFINITIONS增加一条{ id, label, shortLabel, installUrl }面板、状态栏、onboarding、命令面板即自动获得对新 Agent 的支持。ADR-0062 的价值正在于把「支持新 Agent」从一个跨全应用的改造压缩成两个注册点加一个适配器模块而统一事件模型、并行探测与安装本地偏好这三块基础设施则让所有后续 Agent 共享同一套面板体验。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考