桌面 Profile、项目与插件管理

本页说明 Desktop 应用围绕 profile、项目目录和插件运行时所承担的边界：Desktop 如何作为 Electron shell 启动共享 profile runner、如何为 profile 准备核心运行时，以及 Creator 和 Web Plugin Manager 如何使用随 Desktop 提供的包管理运行环境。

Purpose and Scope

本页聚焦桌面端的 profile、项目与插件管理基础设施，包括 profile 路径约定、核心包集合描述、启动前准备以及插件包操作所依赖的 Desktop 私有 pnpm 环境。该能力的目标不是重新实现 Web 应用，而是为打包后的 Desktop 运行时提供稳定、可校验、可启动的 profile。

账户、Platform 嵌入页、更新安装器和 CLI 注册属于相邻能力；本页只在它们与 profile 或插件生命周期存在直接关系时提及。关于完整桌面启动代理和 Web Host 请求转发，参见 Desktop 运行时相关页面；关于账户身份和 Platform API，参见账户/Platform 页面。

Overview

Desktop 是完整 dsh Web 应用的 Electron shell。启动时，Electron RunAsNode 子进程启动共享 profile runner，随后加载打包的 Web entry。profile 是 Desktop 运行时的工作边界：它保存运行所需的路径、锁和本地核心包描述，使启动过程能够在创建或使用 Web Host 前检查必要资源。

核心包集合由 profile 内的 desktop-packages.json 描述，immutable core npm tarballs 位于 profile 相对目录 desktop-packages。源代码将这些名称集中为常量，并提供结构校验函数；这意味着 profile 不应被视为任意目录，而应被视为具有明确布局和版本约束的运行时工件。

插件管理则使用 Desktop 自带的 pnpm，并在 Electron Node 模式下运行，不要求系统 PATH 中存在 pnpm。该私有 launcher 环境只应用于 package operations，避免把 Desktop 的内部包管理环境意外泄露给其它进程。

Architecture

Source: README.md

Sources:

• backend-controller.ts
• paths.ts
• core-package-set.ts

图中的关系均来自已检索到的实现说明：backend-controller.ts 明确把 profile preparation 放在子进程启动之前，并且并发调用共享同一次准备尝试；paths.ts 把 profile 和 lock 固定在 dsh home 下的 profiles/desktop；core-package-set.ts 定义 profile 内的核心包描述文件、核心包目录和启动所需的 Host 文件；Desktop README 则明确 Creator 与 Web Plugin Manager 共用 bundled pnpm。

Profile 与项目目录布局

DesktopPaths 的稳定路径约定

源代码公开的 DesktopPaths 至少包含 profile 和 lock 两个只读路径字段，并将它们解析到同一 Desktop profile 下：profile 是 join(dshHome, 'profiles', 'desktop')，lock 是该目录下的 lock。这一约定把运行时数据与其它 profile 隔离，也为启动互斥或生命周期协调提供了固定位置。

当前检索范围没有足够实现细节来确认 lock 文件的具体写入者、锁协议或失败异常；这些行为不应在本页中推断。

核心包集合

core-package-set.ts 定义了以下 profile 工件：

readDesktopCorePackageSet(projectDir, expectedReleaseVersion?) 会从 projectDir/desktop-packages.json 读取并进行结构校验；可选的 release version 参数表明读取时可以同时验证预期发布版本。由于本页的源读取预算限制，未取得该函数完整实现，不能安全列出具体校验字段、错误类型或版本比较规则。

启动前准备与并发行为

backend-controller.ts 的注释明确了两个设计约束：profile 必须先准备完成，然后才启动一个子进程；并发调用者共享同一次启动尝试。这样的顺序把“profile 未就绪”和“子进程已启动”分开，避免多个调用者同时创建或启动同一 profile。

从可观察行为看，生命周期顺序为：

1. Desktop main process 请求 profile preparation。
2. preparation 检查或创建启动所需的 profile 工件。
3. preparation 完成后启动一个 backend child。
4. 并发请求复用正在进行的 attempt，而不是各自启动 child。
5. child 为 bundled Web application 提供运行时。

Sources:

• backend-controller.ts
• README.md

这里的 sequence diagram 只表达源代码明确支持的顺序和并发语义；具体 IPC 消息名、child 参数、重试策略和 readiness payload 在当前已读取证据中没有确认。

插件与项目包操作

Creator 和 Web Plugin Manager 使用 Desktop bundled pnpm，并通过 Electron Node mode 执行 package operations。关键设计边界是：系统不必安装 pnpm，且私有 Node launcher 环境只对包操作生效。这样既保证已安装 Desktop 在干净机器上仍能管理插件，也避免把内部 Node 环境作为整个桌面应用的通用环境变量来源。

Source: README.md

源代码细节不足以确认插件包的 manifest 格式、安装目录、允许的 registry、脚本白名单或卸载清理规则。因此，这些项目级策略不在本页中假设；需要扩展插件管理时，应先定位对应的 Web Plugin Manager 和 launcher 实现。

Usage Examples

代码示例可用性说明

当前为该页面收集的源代码证据包含实现注释、常量和路径片段，但未读取足以安全截取的完整函数体或调用点。根据“不得编造代码”的约束，本页不提供伪造的 TypeScript 示例；实现细节不足时应以源文件为准。

Configuration Options

本页已确认的是代码内固定布局，而不是用户可编辑配置：

以上名称和固定值来自已检索的 paths.ts 与 core-package-set.ts；其它环境变量、项目配置键和 release 覆盖规则在当前证据中未确认。

API Reference

readDesktopCorePackageSet(projectDir: string, expectedReleaseVersion?: string): DesktopCorePackageSet

该函数从给定项目/profile 目录读取 desktop-packages.json，并返回经过结构校验的 DesktopCorePackageSet。第二个参数用于传入预期 release version，但当前页面的有限源读取没有取得完整函数体，因此不能可靠说明所有校验失败情形或返回对象字段。

参数：

• projectDir (string)：包含 desktop-packages.json 的目录。
• expectedReleaseVersion (string | undefined)：可选的预期发布版本，用于读取时的版本约束。

返回： DesktopCorePackageSet，表示已读取并校验的核心包集合描述。

错误： 实现明确包含读取和结构校验步骤；具体异常类型与错误消息尚未在当前源证据中确认。

Profile preparation contract

backend-controller.ts 的注释确认 profile preparation 必须在 child spawn 前完成，并且并发调用者共享 attempt。完整方法名、参数和返回类型未在当前证据中取得，因此不编写未经验证的签名。

Failure Modes、Edge Cases 与并发

• 并发启动： 已确认并发调用者共享同一次 profile/start attempt，避免为同一请求创建多个 child。
• 准备顺序： profile preparation 未完成前不应启动 child；这是明确的前置条件。
• profile 工件缺失或结构错误： readDesktopCorePackageSet 负责 descriptor 的结构校验；具体错误映射尚未确认。
• 版本不匹配： 可选的 expectedReleaseVersion 表明存在 release 版本校验入口，但比较行为需要进一步阅读实现。
• pnpm 不在系统 PATH： Desktop README 明确 package operations 使用 bundled pnpm，因此系统 pnpm 不是该路径的前提。
• 插件环境隔离： 私有 Node launcher 环境只作用于 package operations，不能据此推断其它 Desktop 子进程也会继承该环境。

Performance / Operational Notes

profile preparation 的并发共享是最重要的运行时优化：在多个 UI 或生命周期调用同时请求启动时，只复用一个 attempt。核心 tarballs 被定义为 immutable，减少启动时对核心依赖内容变化的假设；同时通过 descriptor 进行结构校验，能够在 Web Host 启动前发现 profile 工件问题。

运维上应保留 profile 的目录布局，并避免手工移动 desktop-packages.json 或 desktop-packages。当前证据没有显示缓存失效、tarball 清理、下载重试或磁盘配额策略，因此这些策略不能从本页推导。

Extension Points

可验证的扩展边界包括：

1. 在 profile preparation 阶段增加新的启动前工件，但必须保持“准备完成后再 spawn child”的顺序。
2. 扩展 DesktopCorePackageSet descriptor 的校验逻辑，同时保持 release artifact 与 active profile 使用同一结构校验入口。
3. 为 Creator 或 Web Plugin Manager 增加 package operation 时，继续使用 bundled pnpm 的私有 launcher，而不是假设系统 pnpm 可用。
4. 增加新的 profile 路径时，集中修改 DesktopPaths 与相关消费者，避免散落硬编码目录。

Related Links

• Desktop README
• backend-controller.ts
• paths.ts
• core-package-set.ts