• 桌面应用
• 开发工具
• 运维

XPipe 21.6 是一个以稳定性修复为主的版本，共包含 5 项 Fix，全部围绕日常使用中最容易被卡住的环节：MCP（Model Context Protocol）服务端在真实 Agent 客户端下的行为健壮性、SSH 公钥自动生成的格式容错、未配置 SSH 的容器/虚拟机上的动作可见性，以及 Bitwarden 凭据集成的首次同步。读完本文，你不仅能理解每条修复解决的具体问题，还能结合当前源码树（仓库version文件显示已演进至 24.6，21.6 的修复逻辑至今仍保留在主代码中）看清list_systems的匹配算法、MCP 工具的注册与鉴权链路、ssh-keygen的自动化调用方式等底层实现。

一、21.6 修复清单总览

对照 dist/changelog/21.6.md，本版本共修复 5 个问题：

二、list_systems为什么需要支持绝对路径：匹配算法解析

这是 21.6 中最有工程含金量的一项修复。XPipe 的 MCP 服务端通过 AppMcpServer.java 注册了list_systems等 14 个工具，其 Schema 定义在 list_systems.json 中：

{ "name": "list_systems", "description": "Lists all available systems in XPipe", "inputSchema": { "type": "object", "properties": { "filter": { "type": "string", "description": "The system name filter, also supports globs" } }, "required": ["filter"] }, "outputSchema": { "type": "object", "properties": { "found": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "path": { "type": "string", "description": "The full path of the system" }, "information": { "type": "string" }, "notes": { "type": "string" } } } } } } }

工具实现位于 McpTools.java，核心一步是DataStorageQuery.queryEntry(filter)。问题在于：LLM 客户端（如 Claude Code）调用该工具时，并不总是乖乖传「连接名」——它完全可能把上一次工具返回的完整路径（绝对路径）原样塞回filter参数。修复前的匹配逻辑对这类输入会因 glob 匹配失败或匹配到多个同名条目而返回空结果，导致 Agent「找不到明明存在的系统」。

当前源码中的解决方式是三级收敛策略，见 DataStorageQuery.java#L9-L30：

1. 先用宽泛 glob（queryEntry("**", globInput, "*", false)，即路径子串匹配）拿到候选集；
2. 若候选多于 1 个，优先收窄为完整存储路径精确相等（getStorePath(entry).toString().equalsIgnoreCase(globInput)）的条目——这正是让「绝对路径输入」直接命中的关键分支；
3. 若路径精确匹配无果，再收窄为条目名精确相等的条目；仍无果则回退到原始 glob 结果。

底层 glob 到正则的转换由同文件 toRegex 方法 完成（*→[^/]*、**→.*、{a,b}→(a|b)等），而模糊匹配模式由 compileSearchPattern 通过前后拼接**实现子串语义。MCP 侧的system参数解析（如run_command、read_file工具中的getShellStoreRef）走 McpToolHandler.getDataStoreRef，它在命中 0 个或多个条目时抛出No connection found for input/Multiple connections found错误——修复后传入绝对路径即可稳定收敛到唯一条目，多歧义报错也随之消失。

顺带一提，MCP 服务端的系统提示词 prompt.md 明确要求 Agent「必须使用用户在 XPipe 中指定的精确名称调用list_systems，如果确信名称已精确可跳过查询」，可见 21.6 的匹配容错与 prompt 引导是配套设计的。

三、长命令不再打断 MCP 会话：流式传输与命令执行链

21.6 的另一项修复是「Claude Code 中 MCP 会话对长耗时命令超时」。从当前源码结构可以还原 XPipe MCP 的会话架构，理解修复的技术背景：

• 传输层：HttpStreamableServerTransportProvider.java 实现了 MCP 的 Streamable HTTP 传输（message事件类型、SSE 的text/event-stream响应、会话ConcurrentHashMap管理与 keep-alive 调度），端点为/mcp，由 AppMcpServer.init 装配；
• 鉴权层：AppMcpServer.createHttpHandler 在转发请求前检查enableMcpServer开关（未开启返回 403 并提示到设置菜单启用）与Authorization: Bearer <apiKey>头（未设置或错误同样返回 403，且会向本地界面推送错误提示）。

命令执行链上，run_command工具（McpTools.java#L415-L429）解析command与system参数后，通过AppBeaconServer.get().getCache().getOrStart(shellStore)获取或启动 Shell 会话，再委托给 ProcModuleProvider.executeMcpCommand（由 proc 扩展模块实现）真正执行并组装CallToolResult。对长耗时命令而言，关键在于客户端-服务端会话必须保持活动状态直至命令完成——21.6 修复正是针对 Claude Code 这类客户端在等待期间会话被判定超时而中断的问题，属于 MCP 会话生命周期处理的健壮性修复。若你的 Agent 客户端连接 XPipe MCP 时偶发「命令执行到一半断开」，可先确认：MCP 服务已在设置中启用、Authorization头携带的是 API 设置菜单中的 Bearer token，并且客户端使用的是 streamable HTTP 传输（源码中对缺少mcp-session-id头的 GET 请求会显式提示「Check whether you are using the streamable HTTP transport and not something else like SSE」）。

四、SSH 公钥 keygen：末尾换行符与 ed25519 自动化

「公钥 keygen 在公钥没有 trailing newline 时报 invalid format」是典型的跨工具格式兼容问题：ssh-keygen生成的.pub文件以换行结尾，但手工编辑、密码管理器导出或从网页复制来的公钥常常缺少末尾换行，若解析端严格按ssh-keygen的字节格式校验，就会误判格式非法。

XPipe 对 SSH 密钥的自动化处理在 SshLocalBridge.java 中有完整范例，可对照理解 keygen 修复所在的上下文：本地 SSH 桥启动时会检查ssh_bridge目录下主机密钥与身份密钥是否存在，不存在则执行：

ssh-keygen -q -C "XPipe SSH bridge identity" -t ed25519 -f <identity_key> -N ""

并生成仅监听127.0.0.1、PubkeyAuthentication yes、PasswordAuthentication no的本地sshd配置（SshLocalBridge.java#L104-L141），同时把Host xpipe_bridge段落幂等地写入用户~/.ssh/config（updateConfig 方法，已存在则按正则替换、存在畸形条目则跳过避免误改）。公钥的对外生成能力则由 ProcModuleProvider 以抽象方法形式提供给扩展实现：

public abstract String generatePublicSshKey(SecretValue privateKey, SecretRetrievalStrategy passphrase); public abstract Optional<String> generatePublicSshKey(FilePath file) throws Exception;

generatePublicSshKey(FilePath file)正是「从已有公钥文件推导/校验公钥」的入口——21.6 的修复即在此类导入路径上放宽了末尾换行要求，使缺少 trailing newline 的公钥不再被误报为 invalid format。对使用者的实际意义：从 Bitwarden 等密码管理器或剪贴板粘贴的公钥即使不带末尾换行，也能被正常识别与生成配对密钥。

五、未配置 SSH 的容器/VM 不再显示误导性动作

21.6 修复了「SSH VsCode 与 SFTP 动作出现在尚未配置 SSH 的容器/VM 上」的问题。XPipe 中每个连接类型（容器、虚拟机、SSH 主机等）都挂载一组可用动作（Action），SSH VsCode、SFTP 这类动作的前置条件是连接已具备可用的 SSH 通道。从源码结构看，连接的动作集合经由各 Provider 的能力声明构建，21.6 的修复属于可见性过滤：对未配置 SSH 的连接，这些动作不再进入菜单，避免用户点击后失败。这类修复的价值在于减少「动作可点但不可用」的界面噪音，尤其影响通过 MCP/HTTP API 自动枚举连接动作的自动化流程。

六、Bitwarden 集成：全新安装场景下的同步修复

XPipe 将 Bitwarden 作为一等支持的凭据应用，其应用标识定义在 WebtopApp.java#L12：

BITWARDEN("bitwarden"),

同枚举中还有ONE_PASSWORD、KEEPASSXC、PROTON_PASS、OPENBAO等凭据类应用，它们共同支撑 XPipe「从密码管理器读取凭据并同步连接配置」的集成能力。21.6 针对的是全新安装XPipe 时 Bitwarden 同步不生效的问题：老用户因已有本地状态不受影响，而新装实例在首次初始化凭据同步链时缺失必要状态，导致同步静默失败。如果你在全新环境中配置 Bitwarden 集成，升级到 21.6（或后续版本，如当前仓库的 24.6）后重新触发一次同步即可。

七、验证与适用说明

• 以上所有结论基于当前仓库源码（version文件为 24.6），21.6 的修复逻辑（DataStorageQuery路径精确收敛、MCP streamable 传输、ssh-keygen自动化流程）在当前代码树中仍然可验证；
• MCP 相关功能需要先在 XPipe 设置菜单中启用 MCP 服务端，MCP 客户端需配置Authorization: Bearer <API token>头（token 见 API 设置菜单），并使用 streamable HTTP 传输连接/mcp端点；
• 本地 SSH 桥（xpipe_bridge）要求系统 PATH 中存在sshd，且会自动写入~/.ssh/config，可通过查看 SshLocalBridge.java 了解其幂等写入策略。

如需继续深入，建议直接阅读 McpTools.java（全部 MCP 工具实现）、McpToolHandler.java（参数解析与连接寻址）以及 dist/changelog/ 目录下按版本组织的完整变更历史。

• 桌面应用
• 开发工具
• 运维