入门推荐

引导式入门会根据用户的应用偏好和观测到的能力来建议成果。它不会授予访问权限，也不会实现第二套连接生命周期。该功能仍然保留在现有的 HERMES_GUEST_ONBOARDING 流程内。

优先级

现有的 machineSetupLeads() 决策仍然对新设置的机器或公认的 RTX/DGX Spark 以机器设置领先，其他任务排在 其他内容 之后。新机器信号是现有的年龄启发式判断，并非操作系统安装日期的证据。年龄未知的 Spark 会得到硬件特定的提示，而不是声称其操作系统是新的。

否则，指南会倾向于相关的、有应用支持的任务，并提供一个无需连接的替代方案。检测到某个应用最多只能获得一个选项；其余选项来自用户的目标和其他能力。只有在明确要求时，为同一应用提供多个想法才是合适的。选择收件箱任务意味着在获得权限后使用真实的收件箱数据，而不是在缺少权限时构建一个模拟收件箱。被跳过或不可用的必需连接会使该任务保持阻塞状态；用户可以选择其他任务或提供数据。

目录元数据

在运行时读取实际目录。条目不需要新的推荐元数据：检测会回退到其目录名称（slug 分隔符视为空格），模型会根据其描述推导出任务。移除某个条目会将其从未来的快照中移除。入门变更中不应包含特定于产品的条目、软件包或安装配方。

目录所有者可以选择性提供更丰富的提示：

suggest:
  keywords: [example, modeling]
  hosts: [example.com]
  applications: [Example Studio]
  requires_app: true
  examples:
    - Light a product render in Example Studio

• keywords 和 hosts 保持其现有含义。applications、examples 和 requires_app 是可选新增项。
• applications 包含最多 16 个安全标签/别名，每个最多 80 个字符。不得包含路径、shell 参数、正则表达式或脚本。
• examples 包含最多六个可打印的单行成果，每个最多 240 个字符。模型会将其提炼为现有选项芯片中更短的标签。
• 仅当本地应用是前提条件时，requires_app 才为 true。对于云服务而言，桌面应用的存在可以是相关性信号，但并非必要条件。
• 示例能力和设置前提条件必须对照集成的实际文档进行核查。目录条目并非账户访问权限、权益、附加组件就绪状态或实时工具连接的证明。

受管应用选择器保留其精选的领先项，同时使实时目录中其他已启用的行可被搜索。新部署的受管连接器不再仅因为其 slug 不在领先列表中而被丢弃。不需要新的门户元数据端点。

发现与范围

GET /api/mcp/catalog?detect_apps=true 会添加：

• entries[].detected_apps：仅包含匹配的目录派生应用名称或可选显式别名。
• discovery：{scope: "backend", status: "ok" | "unavailable", platform: string}。

默认目录请求不执行应用发现。可选扫描会在 后端机器（其 MCP 进程运行之处）上检查标准应用位置和确切的安全 PATH 候选项。它绝不启动应用、启动 MCP、安装软件包、读取应用文档或访问网络。它既不返回完整清单，也不返回文件系统路径。

该扫描有目录、条目和时间预算。它并非详尽无遗的已安装软件清单。访问失败、预算耗尽或不受支持的主机会报告 unavailable；正面观测仍有价值，而缺少观测并不构成不存在的证据。macOS 应用包、Linux 桌面条目和 Windows 常用程序目录有平台特定的读取器。不包括 Windows 注册表枚举。

桌面端会将目录请求固定到指南或交接的后端/配置档。它绝不会将桌面本地应用观测与远程 MCP 主机组合在一起。临时配置档的 API 探测可以保留实际的 OS 主目录用于只读应用发现，而无需读取已安装配置档的配置。

推荐与执行边界

推荐在配置和应用存在信号之前，对显式任务相关性和选定应用进行排序。被禁用的集成不会在没有明确兴趣的情况下自动重新浮出。所需的本地应用需要正向检测或现有配置才符合条件。每个种子包含少量候选项，而不是整个目录。

指南在其会话创建时会收到一个只读快照。交接会为工作配置档刷新该快照，并包含所选候选项的完整设置说明。这两条路径都不会变更现有的系统提示、缓存连接权限或执行设置。陈旧或不可用的目录会回退到现有的入门行为。

证据	含义	下一步操作
检测到应用，MCP 缺席	应用信号，仍需要设置	现有的 manage_connections 安装审批
MCP 已配置但已禁用，明确要求	配置存在，有意未激活	现有的启用审批
MCP 已配置且已启用	仅配置；连接未验证	发现其可用工具并在使用前验证
受管应用未连接	需要账户权限	现有的受管连接卡片
跳过、不可用或缺少会话能力	未授权/不可用	解释被阻塞的任务；无绕过或自动重试

对于 MCP 目标，status 不是 受支持的 manage_connections 操作。快照提供 setupAction（install、enable 或 null）；仅在确实需要时才请求授权。受管账户状态仍然是受支持的单独操作。这一区分是根据实际生成的工具参数验证的，而不仅仅是提示文本。

传统的 composer 建议提供者只能完成托管的 HTTP OAuth。它排除了本地应用和非 OAuth 条目，因此新元数据无法将本地编辑器引导到那个无关的流程中。入门使用共享的连接操作。

与连接操作工作的兼容性

该实现使用公开的 manage_connections 工具和现有的目录 API。它不会修改连接操作状态、生成的 RPC 合约、账户标识符、OAuth 回调、重试归属、监听器行为或已敲定的结果处理。

它已对照当前集成以及 Sid 待处理的 连接操作 PR 进行了核查。该 PR 将 MCP 执行移入后端；推荐不依赖于当前由哪一侧执行该操作。可选目录字段保留对较旧客户端的兼容，缺失字段保留对较旧后端的兼容。Sid 已取消的门户工具包元数据端点不是依赖项。

在入门运行手册及其测试中存在一处有意的产品策略重叠：产生无账户替代品的旧要求被替换为已接受任务的实际前提条件。当分支汇合时，该重叠必须得到协调，而不是作为相互矛盾的说明保留。不暗示与未知的未来破坏性 API 变更的兼容性。

验证边界

合约测试涵盖目录解析、选择性加入的只读发现、A/B/A 配置档隔离、缺失元数据、排序、后端固定的种子创建、合法的 MCP 设置操作以及新机器/Spark 优先级的保留。

对合成入门轮次的实时推理可以验证推荐的成果和生成的设置操作。原生发现可以验证真实已安装应用的信号。两者都不能证明 OAuth 完成或 Blender 内的执行：那仍然需要应用的附加组件/服务器、用户的批准以及一次无害的实时工具检查。阅读实际返回条目的设置说明；入门不提供自己的集成配方。