上手引导建议 {#onboarding-recommendations}

引导式上手引导会根据用户的应用偏好和观察到的能力给出建议结果。它不会授予访问权限，也不会实现第二套连接生命周期。该功能始终位于现有的 HERMES_GUEST_ONBOARDING 流程之内。

优先级 {#what-takes-priority}

现有的 machineSetupLeads() 决策对于新装机的机器或识别出的 RTX/DGX Spark，仍然优先推荐机器设置，其他任务排在其他事项之后。新机器信号采用现有的使用时长启发式判断，并非操作系统安装日期的确证。对于使用时长未知的 Spark，会给出硬件相关的提示，而不会声称其操作系统是全新的。

在其他情况下，引导会优先推荐有应用支撑的相关任务，并提供无需连接的替代方案。检测到一个应用最多只换来一个选项；其余选择来自用户目标和其他能力。针对同一应用提出多个想法，仅在用户明确要求时才合适。选择收件箱类任务意味着在获得许可后使用真实的收件箱数据，而不是在缺少许可时凭空搭建一个模拟收件箱。某个必需连接被跳过或不可用，会使该任务保持阻塞；用户可以选择其他任务或自行提供数据。

目录元数据 {#catalog-metadata}

在运行时读取真实目录。目录条目无需新增建议元数据：检测会回退使用其目录名称（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 不在置顶列表中就被丢弃。无需新增 portal 元数据端点。

发现与范围 {#discovery-and-scope}

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 注册表枚举。

桌面端会把目录请求锁定到引导或交接所对应的后端/profile。它绝不会把桌面本地的应用观察结果与远程 MCP 主机混用。临时 profile 的 API 探测可以保留真实的操作系统主目录用于只读的应用发现，而不读取已安装 profile 的配置。

建议与执行边界 {#recommendation-and-execution-boundaries}

建议在排序时，把显式的任务相关性和已选应用排在配置信号与应用存在信号之前。被禁用的集成不会在没有明确兴趣的情况下自动重新浮现。必需的本地应用需要被正面检测到，或已有配置，才具备资格。每个种子只包含少量候选，而非整个目录。

引导在其会话创建时获得一份只读快照。交接会为当前工作 profile 刷新该快照，并附上所选候选的完整设置说明。两条路径都不会改动现有的系统提示词、缓存连接授权或执行设置。目录过旧或不可用时，回退到现有的上手引导行为。

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

旧版编辑器建议提供器只能补全托管 HTTP OAuth。它排除了本地应用和非 OAuth 条目，因此新元数据不会把本地编辑器路由到那条无关流程。上手引导改用共享的连接操作。

与连接操作工作的兼容性 {#compatibility-with-the-connection-operation-work}

本实现消费公开的 manage_connections 工具和现有的目录 API。它不修改连接操作状态、生成的 RPC 契约、账户标识、OAuth 回调、重试归属、监听器行为或已决结果的处理。

它已对照当前集成和 Sid 待提交的连接操作 PR 进行核对。该 PR 把 MCP 执行移到后端；建议逻辑不依赖当前由哪一侧执行该操作。可选目录字段保留了对旧客户端的兼容，缺失字段则保留了对旧后端的兼容。Sid 已取消的 portal 工具包元数据端点并非依赖项。

上手引导的运行手册及其测试中存在一处刻意的产品策略重叠：旧版要求产出"无账户替代方案"，现已被"被接受任务的实际前置条件"取代。这一重叠加需在分支合并时调和，而非保留为相互矛盾的指令。本文不暗示对未来未知的破坏性 API 变更保持兼容。

验证边界 {#verification-boundaries}

契约测试覆盖目录解析、可选的只读发现、A/B/A profile 隔离、元数据缺失、排序、后端锁定的种子创建、合法的 MCP 设置动作，以及对新机/Spark 优先级的保留。

基于合成的上手引导轮次进行的实时推理，可以验证建议结果和生成的设置动作。原生发现可以验证真实的已装应用信号。两者都不能证明 OAuth 已完成或已在 Blender 内部执行：那仍需要应用的插件/服务器、用户批准以及一次无害的实时工具检查。请阅读实际返回条目自带的设置说明；上手引导不提供自己的集成方案。