把 Rust Agent 做成桌面产品，我在 SkillLite Assistant 里踩过的几类工程坑

摘要本文探讨了将命令行AI Agent转化为桌面产品时面临的工程挑战。以SkillLite Assistant为例，作者总结了七个关键问题领域：1)前端与Rust运行时的桥接漂移；2)配置持久化与引用失效；3)多模型路由而非简单选择；4)内部步骤的UI呈现；5)IDE三栏布局的复杂性；6)权限与安全的产品化实现；7)MCP动态能力接入。文章通过架构图、流程图和代码片段展示了桌面化需要构建的完整&

sinat_25866835

380人浏览 · 2026-04-20 23:07:36

sinat_25866835 · 2026-04-20 23:07:36 发布

摘要

很多 AI Agent 项目在命令行里已经能跑得很好：能调模型、能跑工具、能接 MCP、能做多轮对话，甚至还能规划与自进化。但当你真的想把它做成一个日常可用的桌面产品时，问题会突然从“模型够不够强”转成“系统够不够稳”。这篇文章结合 SkillLite Assistant 的实际实现，复盘我把 Rust Agent 做成桌面产品时踩过的几类典型工程坑：前端状态到 Rust runtime 的桥接漂移、设置持久化与失效引用、多模型场景路由、内部步骤 UI、IDE 三栏布局、MCP 动态能力接入，以及权限与安全交互的产品化落地。本文会用架构图、流程图和源码片段说明一个结论：桌面化不是给 Agent 套个 GUI，而是补上一整层“长期可用”的产品化工程。

一、为什么“能跑的 Agent”不等于“能用的桌面产品”
二、SkillLite Assistant 的分层架构
三、坑 1：前端到 Rust Agent 的桥接不是普通 RPC
四、坑 2：配置持久化不是存个 localStorage 就完了
五、坑 3：多模型不是下拉框问题，而是路由问题
六、坑 4：内部步骤如果原样摊开，UI 会变得很吓人
七、坑 5：加了 IDE 三栏后，你做的就不再只是聊天应用
八、坑 6：桌面安全不是 README 里写“有沙箱”就够了
九、坑 7：MCP 接进来后，系统面对的是动态能力面
十、一次完整请求是怎么在桌面端跑起来的
十一、小结
参考与链接

一、为什么“能跑的 Agent”不等于“能用的桌面产品”

命令行里的 Agent，往往只需要回答两个问题：

模型能不能调起来？
工具能不能跑起来？

但桌面产品不是这样。桌面端真正要回答的问题更接近：

配置改完后，下次重启是不是还对？
用户删掉一个模型配置后，系统会不会留下一堆悬空引用？
工具执行是不是足够透明，但又不会把界面刷成日志面板？
文件预览、工作区浏览、Markdown 预览、图片视频查看这些能力，怎么和聊天区协同？
安全确认、自进化审核、MCP 接入，到底是“文档里说支持”，还是“用户能在界面里稳定理解和使用”？

我在做 SkillLite Assistant 时，越来越强烈地感受到：

桌面化的难点并不在“补一个 Tauri 外壳”，而在于补上一整层产品化缝合层。

这个缝合层不直接创造智能，却决定了用户到底敢不敢长期打开它。

二、SkillLite Assistant 的分层架构

SkillLite Assistant 的桌面端核心技术栈是：

Rust：Agent 核心、MCP bootstrap、桥接后的运行时配置承接
Tauri 2：桌面壳、窗口能力、系统权限
React 18 + TypeScript：聊天、设置、工作区 IDE、自进化面板
invoke bridge：前端将设置和请求打包后发给 Rust 侧

可以先用一张图建立心智模型：

这张图看起来很规整，但真正容易出问题的，恰恰是这些层之间的边界：

UI 的设置状态，是否被准确映射成 Rust runtime 可理解的配置？
用户保存的模型配置、场景路由、MCP server 列表，是否在重启后仍保持一致？
Agent 的中间步骤，怎么以“用户能消费”的方式展示？

下面几节，基本都在讲这些边界上的坑。

三、坑 1：前端到 Rust Agent 的桥接不是普通 RPC

一开始最容易低估的，是“前端调 Rust Agent”这件事。

很多人会自然地把它理解成：

Chat 输入 -> invoke -> Rust 处理 -> 返回结果

但在真实的桌面 Agent 里，一次调用带过去的并不只是“消息文本”，而是一份运行时配置快照。SkillLite Assistant 前端会把这些设置打包进桥接配置：

export function buildAssistantBridgeConfig(settings: Settings): Record<string, unknown> {
  const config: Record<string, unknown> = {};
  if (settings.apiKey) config.api_key = settings.apiKey;
  if (settings.model && settings.model !== "gpt-4o") config.model = settings.model;
  if (settings.workspace && settings.workspace !== ".") config.workspace = settings.workspace;
  if (settings.apiBase) config.api_base = settings.apiBase;
  if (settings.sandboxLevel !== 3) config.sandbox_level = settings.sandboxLevel;
  if (settings.swarmEnabled && settings.swarmUrl?.trim()) config.swarm_url = settings.swarmUrl.trim();
  if (settings.maxIterations != null && settings.maxIterations > 0) {
    config.max_iterations = settings.maxIterations;
  }
  if (settings.maxToolCallsPerTask != null && settings.maxToolCallsPerTask > 0) {
    config.max_tool_calls_per_task = settings.maxToolCallsPerTask;
  }
  config.ui_locale = settings.locale === "en" ? "en" : "zh";
  if (settings.mcpServers !== undefined) {
    config.mcp_servers = settings.mcpServers.map((s) => ({
      id: s.id,
      enabled: s.enabled,
      command: s.command,
      args: s.args,
      ...(s.cwd != null && s.cwd.trim() !== "" ? { cwd: s.cwd.trim() } : {}),
    }));
  }
  return config;
}

这里暴露出来的第一个工程事实是：

桌面端和 Rust Agent 之间，不是“发一条消息”，而是在同步一套运行意图。

这意味着只要这层映射一漂，问题就会非常难查：

模型明明改了，为什么没切过去？
MCP server 明明勾上了，为什么这轮没生效？
沙箱等级明明选了，为什么行为像没变？
UI 切成英文了，为什么某些提示还是中文？

在桌面产品里，这类问题的用户体感不是“有个字段没映射”，而是：

“我改了设置，但系统没有按我的设置跑。”

所以我后来把这层看成一个正式的产品接口层，而不是前端顺手拼出来的一坨 JSON。

四、坑 2：配置持久化不是存个 localStorage 就完了

做桌面应用时，很多人第一次会把“设置持久化”理解为：

Zustand 持久化
localStorage 写一下
重启恢复就好了

但一旦你的 Agent 产品里有：

已保存的多模型配置
场景路由
fallback 列表
MCP server 列表
当前会话正在使用的模型

问题立刻就不是“存没存下来”，而是：

这些配置之间的引用关系还对不对？
删掉一条配置后，引用它的地方怎么办？
升级后旧数据要不要自动补齐？

SkillLite Assistant 里的 Settings 已经不是简单扁平字段了：

export interface Settings {
  provider: Provider;
  apiKey: string;
  model: string;
  workspace: string;
  apiBase: string;
  sandboxLevel: SandboxLevel;
  llmProfiles?: LlmSavedProfile[];
  llmScenarioRoutingEnabled?: boolean;
  llmScenarioRoutes?: Partial<Record<LlmScenarioRouteKey, string>>;
  llmScenarioFallbacks?: Partial<Record<LlmScenarioRouteKey, string[]>>;
  mcpServers?: McpServerConfig[];
}

真正难的是“配置生命周期”。比如用户删除某个已保存 profile 时，不只是从列表里删掉，还得顺手清理所有引用它的场景路由和 fallback：

export function cleanupLlmScenarioProfileReferences(
  list: LlmSavedProfile[] | undefined,
  routes: Partial<Record<LlmScenarioRouteKey, string>> | undefined,
  fallbacks: Partial<Record<LlmScenarioRouteKey, string[]>> | undefined
): LlmScenarioReferenceCleanup {
  const validIds = new Set((list ?? []).map((p) => p.id));
  const nextRoutes: Partial<Record<LlmScenarioRouteKey, string>> = {};
  const nextFallbacks: Partial<Record<LlmScenarioRouteKey, string[]>> = {};
  let removedPrimaryRefs = 0;
  let removedFallbackRefs = 0;

  for (const key of LLM_SCENARIO_ROUTE_KEYS) {
    const routeId = routes?.[key]?.trim() ?? "";
    if (routeId) {
      if (validIds.has(routeId)) nextRoutes[key] = routeId;
      else removedPrimaryRefs += 1;
    }

    const rawFallbacks = fallbacks?.[key] ?? [];
    const keptFallbacks: string[] = [];
    for (const raw of rawFallbacks) {
      const id = raw?.trim();
      if (!id) continue;
      if (!validIds.has(id)) {
        removedFallbackRefs += 1;
        continue;
      }
      if (id === routeId || keptFallbacks.includes(id)) continue;
      keptFallbacks.push(id);
    }
    if (keptFallbacks.length > 0) nextFallbacks[key] = keptFallbacks;
  }

  return {
    llmScenarioRoutes: Object.keys(nextRoutes).length > 0 ? nextRoutes : undefined,
    llmScenarioFallbacks: Object.keys(nextFallbacks).length > 0 ? nextFallbacks : undefined,
    removedPrimaryRefs,
    removedFallbackRefs,
    changed: removedPrimaryRefs > 0 || removedFallbackRefs > 0,
  };
}

这个坑的本质是：

一旦你让用户在桌面端做长期配置，你就必须为配置之间的关系负责。

CLI 世界里，配置坏了，用户会自己改文件。
桌面世界里，配置坏了，用户只会觉得产品“不稳定”。

五、坑 3：多模型不是下拉框问题，而是路由问题

很多产品说“支持多模型”，其实只是：

设置页里加个下拉框
用户自己切
本轮用哪个就算哪个

但桌面 Agent 真正遇到的问题不是“能不能切”，而是：

主对话尽量别挂
辅助能力别太贵
不同调用场景该不该走同一个模型？
用户删除某个 profile 后，路由是不是还有效？

所以 SkillLite Assistant 后来做的是场景路由，而不是单纯的全局切换。逻辑场景包括：

agent
followup
lifePulse
evolution

运行时先根据场景，把设置替换成对应的 profile：

export function applyLlmScenarioRoute(settings: Settings, scenario: LlmRouteScenario): Settings {
  if (!settings.llmScenarioRoutingEnabled) return settings;
  const id = settings.llmScenarioRoutes?.[scenario]?.trim();
  if (!id) return settings;
  const profile = settings.llmProfiles?.find((p) => p.id === id);
  if (!profile) return settings;
  return {
    ...settings,
    provider: profile.provider,
    model: profile.model,
    apiBase: profile.apiBase,
    apiKey: profile.apiKey,
  };
}

然后聊天主链路并不是直接拿当前 UI 字段去调，而是先按 agent 场景构建桥接配置：

const config = buildAssistantBridgeConfigForScenario(settings, "agent");

const payload: Record<string, unknown> = {
  message: text,
  workspace: settings.workspace || ".",
  sessionKey: currentSessionKey,
  config,
};

await invoke("skilllite_chat_stream", payload);

这背后反映的是一个更重要的产品判断：

多模型系统第一阶段最重要的不是“聪明”，而是“稳”。

也就是：

先把不同场景的职责拆开
先把主链路和边缘链路分开
先把删除 profile 后的清理和回退做好
再考虑更复杂的自动化选模

如果一上来就做黑盒 Auto，桌面产品很容易把配置复杂度、故障复杂度和解释成本一起抬高。

六、坑 4：内部步骤如果原样摊开，UI 会变得很吓人

在 CLI 里，我们很习惯看这类内容：

工具调用参数
中间状态
read_file 结果
list_directory 树形结果
执行确认
错误与恢复提示

因为终端天然就是一个日志容器。

但桌面产品不是。桌面 UI 如果把 Agent 的内部过程原样摊开，马上会遇到两个问题：

信息量太大，用户根本不知道该看哪里。
用户会觉得这个系统一直在“刷内部日志”，而不是在“帮我完成任务”。

所以 SkillLite Assistant 里，内部步骤是被“收纳”和“压缩”过的：

工具过程收纳在可折叠的内部步骤时间线
需要用户操作时自动展开
read_file 结果使用有限高度预览
有文件路径时，点击预览可以直接在 IDE 布局中打开

从产品角度看，这个坑的核心不是前端样式，而是：

Agent 的透明度必须被设计成用户能消费的信息密度。

太少，用户不信任；
太多，用户会被吓跑。

这也是为什么桌面 Agent 和 CLI Agent 不能简单共用同一套“调试视图”。

七、坑 5：加了 IDE 三栏后，你做的就不再只是聊天应用

一旦桌面 Agent 开始支持：

工作区文件树
中间编辑器
Markdown 预览
图片 / 视频预览
聊天中的文件预览一键跳转

它的产品形态就会立刻变化。

原本你可能以为自己做的是一个“聊天壳”。
但加了工作区之后，用户对它的预期会变成一个轻量工作台。

这时很多原本看上去很小的问题，都会变成核心体验问题。比如三栏布局并不是静态切块，而是明确有宽度约束：

const IDE_MIN_EDITOR_PX = 160;
const IDE_DEFAULT_SIDEBAR_PX = 220;
const IDE_MIN_SIDEBAR_PX = 180;
const IDE_MAX_SIDEBAR_PX = 400;
const IDE_DEFAULT_CHAT_PX = 420;
const IDE_MIN_CHAT_PX = 260;
const IDE_MAX_CHAT_PX = 520;

再比如，聊天里的 read_file 结果如果带路径，系统会自动把它转成 IDE 中间栏的打开动作：

useEffect(() => {
  if (!pendingIdeFile) return;
  useIdeFileOpenerStore.getState().clearPending();
  setIdeSelectedFile(pendingIdeFile);
  setIdeLeftTab("files");
  setSettings({ ideLayout: true, sessionPanelCollapsed: false });
}, [pendingIdeFile, setSettings]);

这部分最容易踩的坑是“产品边界漂移”。

你最初也许只想做一个聊天助手，但当你加上工作区和编辑器后，实际上已经在做：

聊天
文件树
编辑器
预览器
设置中心
状态面板
自进化控制台

所以我后来对这类产品的判断是：

只要接入工作区，它就不是聊天壳，而是一个工作台。

如果还用“聊天应用”的思路去做它，界面和信息架构迟早会失控。

八、坑 6：桌面安全不是 README 里写“有沙箱”就够了

在命令行工具里，很多安全能力可以只体现在文档和默认行为里。
但到了桌面产品，这套逻辑就不够了。

用户更关心的是：

这个功能会不会直接执行命令？
执行前我能不能确认？
权限是不是默认就开得太大？
哪些窗口拥有哪些能力？

所以桌面安全不是“README 写了什么”，而是“用户能不能在交互里感知到边界”。

SkillLite Assistant 的 Tauri capability 配置本身就体现了这种收敛思路：

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Default capabilities for the main and detail windows",
  "windows": [
    "main",
    "detail-*"
  ],
  "permissions": [
    "core:default",
    "core:window:allow-set-focus",
    "core:window:allow-show",
    "core:window:allow-unminimize",
    "core:webview:allow-create-webview-window",
    "global-shortcut:allow-register",
    "global-shortcut:allow-unregister",
    "global-shortcut:allow-is-registered",
    "dialog:default",
    "shell:allow-open"
  ]
}

它看上去只是配置，但实际回答的是几个产品问题：

哪些窗口可以做什么？
桌面能力是否显式受控？
是否只放开当前 UI 需要的权限？

这也是我后来越来越在意的一点：

桌面端的“安全感”不是通过宣传建立的，而是通过默认值、确认流程和权限边界建立的。

九、坑 7：MCP 接进来后，系统面对的是动态能力面

如果桌面 Agent 只调用自己内置的工具，那能力面是静态的。
但一旦开始支持 MCP，整个系统面对的其实是一个动态能力系统。

这会立刻引出几个工程问题：

外部 server 的 id 怎么规范化？
不同 server 的工具名怎么避免冲突？
某个 server 启动失败时，是不是应该拖垮整次请求？
远端工具 schema 怎么转成本地 Agent 能接的工具定义？

SkillLite 里的 MCP bootstrap 逻辑，就是在运行时拉取启用的 server，做一次 tools/list，然后统一注册为带前缀的工具：

pub async fn bootstrap_mcp(config: &AgentConfig) -> McpBootstrap {
    let entries: Vec<&McpServerEntry> = config
        .mcp_servers
        .iter()
        .filter(|e| e.is_usable())
        .collect();

    if entries.is_empty() {
        return McpBootstrap::empty();
    }

    let runtime = Arc::new(McpRuntime::default());
    let mut registered: Vec<RegisteredTool> = Vec::new();

    for entry in entries {
        let sid = sanitize_id(&entry.id);
        if sid.is_empty() {
            tracing::warn!("Skipping MCP server with empty id after sanitize");
            continue;
        }

        match connect_server(entry, config, Arc::clone(&runtime)).await {
            Ok(mut tools) => registered.append(&mut tools),
            Err(e) => tracing::warn!("MCP server '{}' unavailable: {}", entry.id.trim(), e),
        }
    }

    if registered.is_empty() {
        return McpBootstrap::empty();
    }

    McpBootstrap {
        tools: registered,
        runtime: Some(runtime),
    }
}

远端工具名会被改写成带 server 前缀的形式：

let prefixed = format!("mcp__{}__{}", sid, sanitize_remote_tool_name(name));

这个坑的关键不在“怎么接 MCP 协议”，而在：

桌面 Agent 一旦支持 MCP，就不能再把工具面当成静态资产。

你面对的是：

用户可配置的外部 server
运行时变化的工具列表
部分失败但整体仍需可用的系统状态

这和写一个“能跑通 MCP demo”的难度完全不是一个量级。

十、一次完整请求是怎么在桌面端跑起来的

上面这些坑如果串起来，一次完整请求大致会经过下面这条链路。

10.1 主对话链路

10.2 配置生命周期链路

10.3 MCP 动态能力接入链路

如果把这三张图放在一起看，会更容易理解为什么桌面 Agent 这么容易“看着只是 UI，实际上全是系统工程”：

一条消息背后不是单纯聊天，而是配置、路由、运行时和动态工具面的联动。
一个设置动作背后不是存个值，而是整个配置图谱的一致性维护。

十一、小结

做完 SkillLite Assistant 之后，我最大的感受是：

把 Rust Agent 放进桌面窗口，并不等于把它做成桌面产品。

真正的难点在于，你要把底层能力补成一套长期可用的用户体验：

前端状态与 Rust runtime 的桥接要稳定
配置持久化要管值，也要管引用生命周期
多模型要先解决路由与稳定性，再谈“更聪明”
内部步骤要透明，但不能原样喷成日志
一旦接入工作区，就得承认自己在做一个工作台
安全要体现在交互和默认值里
MCP 支持的是动态能力系统，不是静态工具清单

如果只用一句话概括这篇文章，那就是：

桌面化不是“给 Agent 套一个 GUI”，而是补上一整层产品化工程。

参考与链接

仓库根文档：README.md
桌面端说明：crates/skilllite-assistant/README.md
设置状态：crates/skilllite-assistant/src/stores/useSettingsStore.ts
路由与 profile：crates/skilllite-assistant/src/utils/llmScenarioRouting.ts
配置桥接：crates/skilllite-assistant/src/utils/buildAssistantBridgeConfig.ts
聊天主链路：crates/skilllite-assistant/src/components/ChatView.tsx
IDE 主布局：crates/skilllite-assistant/src/components/MainLayout.tsx
MCP bootstrap：crates/skilllite-agent/src/mcp_client/bootstrap.rs
Tauri capability：crates/skilllite-assistant/src-tauri/capabilities/default.json
开源仓库：https://github.com/EXboys/skilllite