Ekko Studio 桌面端（Electron）发行指南：安装、命令 Shims、数据目录与图标工程

AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载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}各平台实际产物形态如下平台目标格式架构说明macOSdmg / ziparm64、x64dmg 面向分发zip 面向自动更新electron-updaterWindowsnsisx64安装目录可自定义allowToChangeInstallationDirectory: trueLinuxAppImage / debAppImage 为 x64、arm64deb 仅 x64deb 受 fpm 工具链限制不产出 arm64 包注意发布新产物后必须先发布 artifact再部署网站下载页保证下载页指向的文件名与真实产物完全一致。macOS 与 Windows 在正式放量前应各自完成一次「从上一个签名版本升级」的验证。1.2 关键打包身份信息保持稳定从 electron-builder.yml 可以看到应用身份相关的核心字段升级路径上必须保持稳定否则自动更新、签名校验、登录项注册都可能失效appId: com.hermeswebui.studioproductName: Ekko Studiopublishgeneric 提供商更新源指向https://download.ekkolearnai.comelectron-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.jsonnode_modules以 pruned 后的生产依赖整体拷入webui/node_modules其中 node-pty 只保留当前平台预编译产物以节省约 45MB 体积afterPack阶段运行 verify-packaged-webui.mjs 校验打包完整性。二、命令 Shimsekko-studio统一入口打包后的桌面应用启动后会安装一组「受管命令 shim」managed command shims把桌面应用、Hermes Agent CLI、Web UI CLI 与 MCP 桥统一收敛到ekko-studio命名空间下命令说明ekko-studio打开 Ekko Studio 桌面应用ekko-studio cli ...运行捆绑的 Hermes Agent CLIekko-studio web ...运行捆绑的hermes-web-ui命令ekko-studio -h显示 wrapper 帮助ekko-studio-mcp运行受管的 Web UI MCP 桥桌面命令名为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安装位置统一写入~/binbinDir resolve(homeDir, bin)Unix 上 shim 文件名为ekko-studioWindows 上为ekko-studio.cmd配合同名.ps1侧车脚本MCP 桥对应ekko-studio-mcp/ekko-studio-mcp.cmd。受管标记每个 shim 内容首行包含标记HERMES_STUDIO_CLI_SHIMMCP 桥为HERMES_STUDIO_MCP_SHIM。重装/升级时若已存在同名文件内容一致 → 返回unchanged内容不一致但带受管标记 → 覆盖更新为updated内容不一致且无标记说明是用户自建命令→ 返回skipped绝不覆盖用户文件。旧命令清理安装成功后会检查~/bin下旧的hermes-studioUnix或hermes-studio.cmd/hermes-studio.ps1Windows仅当它们仍带受管标记时才删除避免误删用户自定义命令。PATH 注入Windows 通过 PowerShell 读取/追加用户级Path环境变量Unix 根据$SHELL选择 profilebash 写入~/.bash_profile/~/.bashrczsh 及 macOS 写入~/.zprofile/~/.zshrcfish 写入~/.config/fish/conf.d/ekko-studio.fish注入逻辑为「将$HOME/bin前置到 PATH 且不重复追加」。shim 内部行为Unix shim 是一个 POSIX shell 脚本——无参数时exec启动桌面 Appcli子命令通过exec $APP -- HERMES_CLI_ARG $转发HERMES_CLI_ARG定义于 cli-constants.tsweb子命令校验捆绑的 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_DESKTOPtrue、HERMES_BIN、VIRTUAL_ENV/UV_PYTHON把 uv 钉在捆绑解释器上、HERMES_AGENT_NODE、AGENT_BROWSER_HOME、PLAYWRIGHT_BROWSERS_PATH指向捆绑浏览器、HERMES_AGENT_GITWindows 上显式传入 git.exe 路径等。这一机制在 tests/desktop/cli-shim.test.ts 与 tests/desktop/mcp-cli.test.ts 中有系统性的测试覆盖。2.3 MCP 桥 shimekko-studio-mcp负责启动受管的 Web UI MCP 桥bin/ekko-studio-mcp.mjs。shim 会按以下优先级确定 Web UI 地址环境变量HERMES_WEB_UI_URL已设置则直接使用HERMES_DESKTOP_PORT→ 组装为http://127.0.0.1:${HERMES_DESKTOP_PORT}兜底默认值http://127.0.0.1:8748。同时默认注入HERMES_MCP_SERVER_NAMEekko-studio-mcp供 MCP 客户端识别服务名。若运行时尚未就绪shim 会提示「先打开一次 Ekko Studio 完成运行时初始化」并以退出码 127 退出。三、数据目录~/.hermes与~/.hermes-web-ui桌面端采用「Agent 数据」与「Web UI 壳状态」分离存储的目录设计Hermes Agent 数据存储于~/.hermesWindows、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.png1024pxWindows 桌面图标icon.icoPNG 承载的 16、20、24、32、40、48、64、96、128、256 多分辨率256 条目用 0 表示以支持高 DPI 透明通道Linux 各尺寸icons/${size}x${size}.png16~512其中 512 同时落为iconLinux.png并为 Linux 托盘保留视觉留白padding size/16托盘图标trayMac.png22px、trayMac2x.png44px、trayWindows.png256px、trayLinux.png256pxLinux 桌面端在运行时选用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_REGISTRYhttps://registry.npmmirror.com export ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/ export ELECTRON_BUILDER_BINARIES_MIRRORhttps://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_URLhttps://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 ziparm64、x64 npm run dist:win # nsisx64 npm run dist:linux # AppImage deb运行时 release 的资产名由 runtime-asset-name.mjs 统一生成格式为hermes-runtime-hermes-agent-${HERMES_VERSION}-${platform}.tar.gzplatform 形如win-x64、mac-arm64、linux-x64配套清单为hermes-runtime-${platform}.json——发布运行时与编写更新清单时务必使用脚本输出的一致命名与 README 中「更新清单引用真实 artifact 文件名」的要求相互呼应。Windows 运行时还额外内嵌 Gitgit/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本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐Ekko Studio 安装全指南桌面应用、npm、Docker Compose 与源码开发安装实战Ekko Studio 安装全指南桌面应用、npm、Docker Compose 与源码开发安装实战 Ekko StudioHermes Studio是一AI 应用人工智能AI Agent本地部署前端后端工作流自动化Ekko Studiohermes-studio开发指南全解从命令体系、架构约定到 npm 发布与 PR 流程Ekko Studiohermes studio开发指南全解从命令体系、架构约定到 npm 发布与 PR 流程 本篇技术指南以仓库根目录 DEVELOPMAI 应用人工智能AI Agent本地部署前端后端工作流自动化AMP by Example终极AMP教程指南 - 快速构建高性能移动网页的完整解决方案AMP by Example终极AMP教程指南 快速构建高性能移动网页的完整解决方案 AMPAccelerated Mobile Pages技术已成为现代创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考