企业官网建设流程全解析

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化

Ekko Studio 是一款本地优先（local-first）的多智能体 AI 工作台桌面应用，其 Electron 桌面发行版位于仓库的packages/desktop目录：应用内捆绑了 Web UI 运行时，并由原生壳程序在本地启动。本文以 packages/desktop/README.md 为骨架，结合 cli-shim.ts、paths.ts、login-item-migration.ts 等源码实现，完整梳理安装包的获取与命名规范、ekko-studio系列命令 shim 的安装机制、~/.hermes与~/.hermes-web-ui数据目录的划分、Windows 登录项迁移、托盘/桌面图标再生成流程，以及国内网络环境下的镜像配置，读者可据此完成桌面端的安装、验证、图标重建与离线打包。

一、安装与发布产物命名

Ekko Studio 桌面端面向 macOS、Windows、Linux 三平台发行，用户按 CPU 架构（x64 / arm64）从项目的 GitHub Releases 页面下载对应安装器即可。桌面应用打包时会把 Web UI 运行时一并捆绑进原生壳程序，首次启动后在本地拉起 Web UI。

1.1 安装包命名规则

安装包统一遵循Ekko.Studio-${version}-${arch}.${ext}的命名格式。这一规则在 electron-builder.yml 中通过各平台artifactName显式声明：

artifactName: "Ekko.Studio-${version}-${arch}.${ext}"

各平台实际产物形态如下：

注意：发布新产物后，必须先发布 artifact，再部署网站下载页，保证下载页指向的文件名与真实产物完全一致。macOS 与 Windows 在正式放量前应各自完成一次「从上一个签名版本升级」的验证。

1.2 关键打包身份信息保持稳定

从 electron-builder.yml 可以看到应用身份相关的核心字段，升级路径上必须保持稳定，否则自动更新、签名校验、登录项注册都可能失效：

• appId: com.hermeswebui.studio
• productName: Ekko Studio
• publish：generic 提供商，更新源指向https://download.ekkolearnai.com（electron-updater 的latest.yml/latest-mac.yml即发布于此）
• mac.notarize: true，启用 hardened runtime，签名与公证流程完整

更新清单（update manifests）会引用真实 artifact 文件名，因此 artifactName 一旦变更，更新源必须同步。README 特别强调「保持 application ID、签名身份、更新源、Linux 包身份稳定」，正是为了防止既有安装用户的升级链断裂。

1.3 打包内容与运行时分离

打包配置体现了一个重要设计：Web UI 的构建产物（dist）打进安装包，但 Python / Node / Git 运行时资产不随包分发，而是在用户首次启动后按需下载到 Web UI 数据目录（见下文「数据目录」）。

• extraResources将仓库根目录的package.json、bin/**、dist/**拷贝为resources/webui，并显式剔除docs、tests、scripts、README*等开发文件；
• extraResources同时打包build/下的图标资产（icon.png、iconLinux.png、icon.ico、各平台 tray PNG 以及runtime-release.json）；
• node_modules以 pruned 后的生产依赖整体拷入webui/node_modules，其中 node-pty 只保留当前平台预编译产物以节省约 45MB 体积；
• afterPack阶段运行 verify-packaged-webui.mjs 校验打包完整性。

二、命令 Shims：ekko-studio统一入口

打包后的桌面应用启动后，会安装一组「受管命令 shim」（managed command shims），把桌面应用、Hermes Agent CLI、Web UI CLI 与 MCP 桥统一收敛到ekko-studio命名空间下：

桌面命令名为ekko-studio；安装新 shim 时会移除旧的受管hermes-studio命令，且不创建任何兼容别名——这是刻意的行为：避免hermes-studio与ekko-studio两套命令并存造成 PATH 上的二义性。查帮助分别使用ekko-studio cli -h与ekko-studio web -h。

2.1 源码级剖析：shim 如何被安装与管理

shim 的核心实现在 cli-shim.ts：

• 安装位置：统一写入~/bin（binDir = resolve(homeDir, 'bin')），Unix 上 shim 文件名为ekko-studio，Windows 上为ekko-studio.cmd（配合同名.ps1侧车脚本）；MCP 桥对应ekko-studio-mcp/ekko-studio-mcp.cmd。
• 受管标记：每个 shim 内容首行包含标记HERMES_STUDIO_CLI_SHIM（MCP 桥为HERMES_STUDIO_MCP_SHIM）。重装/升级时，若已存在同名文件：
  • 内容一致 → 返回unchanged；
  • 内容不一致但带受管标记 → 覆盖更新为updated；
  • 内容不一致且无标记（说明是用户自建命令）→ 返回skipped，绝不覆盖用户文件。
• 旧命令清理：安装成功后，会检查~/bin下旧的hermes-studio（Unix）或hermes-studio.cmd/hermes-studio.ps1（Windows），仅当它们仍带受管标记时才删除，避免误删用户自定义命令。
• PATH 注入：Windows 通过 PowerShell 读取/追加用户级Path环境变量；Unix 根据$SHELL选择 profile：bash 写入~/.bash_profile/~/.bashrc，zsh 及 macOS 写入~/.zprofile/~/.zshrc，fish 写入~/.config/fish/conf.d/ekko-studio.fish，注入逻辑为「将$HOME/bin前置到 PATH 且不重复追加」。
• shim 内部行为：Unix shim 是一个 POSIX shell 脚本——无参数时exec启动桌面 App；cli子命令通过exec "$APP" -- <HERMES_CLI_ARG> "$@"转发（HERMES_CLI_ARG定义于 cli-constants.ts）；web子命令校验捆绑的 Node 与hermes-web-ui.mjs后直接以 Node 执行；未知子命令返回退出码 2。Windows 端则是.cmd→ PowerShell 侧车 → Node 的转发链，cli子命令最终由-e内联的 CLI forwarder 完成运行时环境组装。

2.2 底层 CLI 的环境组装

ekko-studio cli最终调用 hermes-cli.ts 的runBundledHermesCli：先执行ensureDesktopRuntime()确保本地运行时就绪，再以捆绑的 Python 运行hermes_cli.main，并为子进程注入一整套隔离环境变量，包括HERMES_DESKTOP=true、HERMES_BIN、VIRTUAL_ENV/UV_PYTHON（把 uv 钉在捆绑解释器上）、HERMES_AGENT_NODE、AGENT_BROWSER_HOME、PLAYWRIGHT_BROWSERS_PATH（指向捆绑浏览器）、HERMES_AGENT_GIT（Windows 上显式传入 git.exe 路径）等。这一机制在 tests/desktop/cli-shim.test.ts 与 tests/desktop/mcp-cli.test.ts 中有系统性的测试覆盖。

2.3 MCP 桥 shim

ekko-studio-mcp负责启动受管的 Web UI MCP 桥（bin/ekko-studio-mcp.mjs）。shim 会按以下优先级确定 Web UI 地址：

1. 环境变量HERMES_WEB_UI_URL（已设置则直接使用）；
2. HERMES_DESKTOP_PORT→ 组装为http://127.0.0.1:${HERMES_DESKTOP_PORT}；
3. 兜底默认值http://127.0.0.1:8748。

同时默认注入HERMES_MCP_SERVER_NAME=ekko-studio-mcp，供 MCP 客户端识别服务名。若运行时尚未就绪，shim 会提示「先打开一次 Ekko Studio 完成运行时初始化」并以退出码 127 退出。

三、数据目录：~/.hermes与~/.hermes-web-ui

桌面端采用「Agent 数据」与「Web UI 壳状态」分离存储的目录设计：

• Hermes Agent 数据：存储于~/.hermes，Windows、macOS、Linux 三平台一致。
• Web UI 状态：桌面 wrapper 自身的 Web UI 状态单独存放于~/.hermes-web-ui，除非显式设置HERMES_WEB_UI_HOME。

在 paths.ts 中可以看到这两个目录的解析逻辑：

export function webUiHome(): string { return process.env.HERMES_WEB_UI_HOME?.trim() || resolve(homedir(), '.hermes-web-ui') } export function hermesHome(): string { const override = process.env.HERMES_HOME?.trim() if (override) return resolve(override) const userHome = isWin ? process.env.USERPROFILE?.trim() || homedir() : homedir() return resolve(userHome, '.hermes') }

除了这两个顶层目录，~/.hermes-web-ui之下还承载着桌面运行时的存储根desktop-runtime/：active-version.json记录当前激活的运行时会话（平台、目录、版本、校验失败历史），hermes/<version>/<platform>/存放下载的运行时本体。desktopRuntimeDir()会优先采用active-version.json中记录的激活目录，校验失败（缺文件、平台不匹配）时自动回退到已安装的候选运行时，并将失败原因写回runtimeValidationFailures——这套「记录 + 回退 + 自愈」逻辑保证了 CLI shim 与 Web UI 启动时总能拿到可用的运行时。

提示：HERMES_HOME、HERMES_WEB_UI_HOME、HERMES_DESKTOP_RUNTIME_DIR均可作为环境变量覆盖默认目录，适合需要把数据与状态迁移到非默认磁盘位置的场景。

3.1 Windows 启动项迁移：Hermes Studio.exe→Ekko Studio.exe

品牌重命名后，Windows 上已启用「开机自启」的旧安装不会失效——首次打包启动时会执行登录项迁移，逻辑位于 login-item-migration.ts：

• 仅当可执行文件名为Ekko Studio.exe且为打包态时执行；
• 关键设计：AppUserModelId（即注册表 Run 值名称）在品牌变更前后保持不变，因此迁移只需在原位替换该值，而绝不新增第二个启动项；
• 迁移时查找旧的Hermes Studio.exe+--hidden参数的用户级登录项，将其path替换为新可执行文件，并完整保留原 Task Manager 中的启用/禁用状态（enabled: legacyItem.enabled）；
• 边界情况：从未启用过自启则什么都不做；自定义条目与机器级（machine-wide）条目一律不动；迁移是幂等的，后续启动重复执行安全。

对应测试见 tests/desktop/login-item-migration.test.ts。此外，desktop-identity.ts 中的configureDesktopIdentity会在改名前后固定userData路径，避免 Electron 因 package name 变化而把既有用户数据目录「迁移」到新位置。

四、桌面与托盘图标：一键再生成

图标资产全部由源图build/icon.png程序化生成，命令在仓库根目录执行：

node packages/desktop/scripts/generate-rounded-icons.mjs

脚本 generate-rounded-icons.mjs 基于 sharp 实现，要点如下：

• 保留原始画稿：以icon.png为唯一输入，仅对外层圆角做处理，不修改内部艺术图案；
• 圆角遮罩：Windows 用 16% 角半径，macOS/Linux 托盘用 26%；
• 输出清单：
  • iconWindows.png（1024px，Windows 桌面图标）
  • icon.ico（PNG 承载的 16、20、24、32、40、48、64、96、128、256 多分辨率，256 条目用 0 表示以支持高 DPI 透明通道）
  • Linux 各尺寸icons/${size}x${size}.png（16~512），其中 512 同时落为iconLinux.png，并为 Linux 托盘保留视觉留白（padding = size/16）
  • 托盘图标：trayMac.png（22px）、trayMac@2x.png（44px）、trayWindows.png（256px）、trayLinux.png（256px）

Linux 桌面端在运行时选用iconLinux.png（见 paths.ts 的desktopIcon()），托盘按平台分别取trayMac.png/trayWindows.png/trayLinux.png，与 electron-builder 的linux.icon: build/icons、mac.icon: build/icon.icon、win.icon: build/icon.ico配置一一对应。因此设计稿变更时只需替换build/icon.png并重跑该脚本，再重新打包即可全平台同步更新图标。

五、中国镜像环境：加速依赖与运行时下载

桌面端构建会拉取 Electron、electron-builder 二进制与 Python 运行时，国内网络下可选用以下镜像（均为可选配置，CI 环境不强制要求）：

export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

• NPM_CONFIG_REGISTRY加速 npm 依赖解析；
• ELECTRON_MIRROR让 Electron 二进制从 npmmirror 镜像下载；
• ELECTRON_BUILDER_BINARIES_MIRROR加速 electron-builder 打包时需要的二进制工具。

如果 GitHub Release 下载缓慢，Python 运行时下载脚本 fetch-python.mjs 还支持切换到兼容的 python-build-standalone 发布镜像：

export PBS_BASE_URL=https://github.com/astral-sh/python-build-standalone/releases/download

该脚本默认从PBS_BASE_URL/${PBS_TAG}/${FILE}拉取指定 tag 的install_only_stripped分发包（tag 与 Python 版本分别可用PBS_TAG、PBS_PY覆盖，当前默认值为20260510/3.12.13），解压后组装成运行时布局；Windows 上还会把独立解释器包装为可重定位的 PEP 405 venv，并回写pyvenv.cfg的绝对 home，使上游hermes update可以直接通过VIRTUAL_ENV定位解释器。

六、构建与发布流水线速览

packages/desktop/package.json提供了完整的构建链路（桌面包自身版本见其version字段）：

# 拉取 Node/Git/Python/Hermes 运行时并安装、裁剪，构建本地运行时 npm run prepare:runtime # 开发模式：编译主进程并以 electron 直接启动 npm run dev # 全平台打包（先构建主进程，再调用 electron-builder） npm run dist # 按平台打包 npm run dist:mac # dmg + zip（arm64、x64） npm run dist:win # nsis（x64） npm run dist:linux # AppImage + deb

运行时 release 的资产名由 runtime-asset-name.mjs 统一生成，格式为hermes-runtime-hermes-agent-${HERMES_VERSION}-${platform}.tar.gz（platform 形如win-x64、mac-arm64、linux-x64），配套清单为hermes-runtime-${platform}.json——发布运行时与编写更新清单时务必使用脚本输出的一致命名，与 README 中「更新清单引用真实 artifact 文件名」的要求相互呼应。Windows 运行时还额外内嵌 Git（git/cmd/git.exe），但刻意不在 PATH 中暴露其usr/bin下的 GNU 工具链，防止du.exe、find.exe等被 Hermes 子进程意外拾取并递归扫描用户目录。

七、小结

Ekko Studio 桌面端把「分发、入口、数据、图标、网络」五个工程问题收敛得相当克制：统一命名的安装包配合稳定不变的 appId 与更新源保障升级链；ekko-studio系列 shim 以受管标记实现安全安装、覆盖与旧命令清理，并提供cli/web/-h/ MCP 桥四类入口；~/.hermes与~/.hermes-web-ui分离 Agent 数据与壳状态，配合active-version.json实现运行时自愈回退；Windows 登录项迁移保留既有用户状态且幂等可重试；图标由单张源图一键再生成；国内镜像环境变量让依赖与运行时拉取在 CI 与个人构建中都能顺畅进行。理解这套发行机制后，无论是排查安装升级问题、自定义图标与命名，还是搭建离线构建环境，都能快速定位到对应的脚本与源码。

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化