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本仓库对应项目仓库路径为 packages/ekko-agent是一个本地优先的多 Agent 聊天、编码与可视化工作流工作台。本文以 hermes-studio-installation SKILL 文档 为核心骨架系统讲解 Ekko Studio 四种安装形态Desktop、npm、Docker Compose、源码的安装/验证/升级流程以及 Studio 托管 Hermes Runtime 的下载、激活、校验、存储迁移与恢复机制并覆盖 Agents 页面中 Claude Code、Codex、Pi、Grok 四个编码 Agent CLI 的安装、更新检查、移除与 PATH 诊断。读完本文你将掌握一整套先探测、后变更、再验证的安装运维方法论并能对照仓库源码理解每一步背后的真实实现。适用说明文中所有命令、路径、默认值与版本策略均以当前仓库实际内容为准涉及版本号、镜像名等外部资源时以安装时远程清单返回值为准。职责边界这个工作流管什么、不碰什么SKILL 文档开篇就划定了严格的边界这是整个工作流的核心约束覆盖范围安装install、检测discovery、验证verification、升级upgrades、移除removal、Runtime 激活activation与 Runtime 存储迁移storage migration。禁止范围不得在本工作流中创建或编辑 model、Provider、API-key、OAuth、MCP、memory、prompt 或 Skill 配置——这些属于安装完成之后的独立任务。安装产物的定性安装过程可能产生包管理器文件与 Studio 自有的 Runtime 清单文件如runtime-manifest.json、active-version.json它们属于安装器状态installer state不是用户的模型配置不应手工改写。优先使用 UI优先使用 Agents 页面与 Version Management UI因为它们与 Studio 本身使用相同的路径、引脚pins、适配器、校验与重启行为UI 可用时不要手工编辑runtime-manifest.json或active-version.json。按需加载参考SKILL 文档本身是决策器把安装问题路由到三份参考文档Desktop/npm/Docker/源码安装看 references/studio.mdHermes CLI 检测与 Runtime 生命周期看 references/hermes-runtime.md编码 Agent 安装看 references/coding-agents.md。只有当请求跨越这些边界时才读取多份参考。安装工作流六步法SKILL 文档给出了标准操作序列任何安装/升级/迁移都应遵循识别上下文操作系统、CPU 架构、Studio 安装形态、目标组件以及用户意图install / verify / update / remove / recover / migrate。先探测后变更变更前先检查现有安装健康安装直接复用不要安装重复副本。声明式执行运行安装或迁移前先明确说明确切的包名、版本策略、目标路径与重启影响。优先走 Studio 工作流UI 可用时使用受支持的 Studio 工作流只有 UI 不可用或用户明确要求时才使用手工包管理器命令。验证而非信任退出码操作后验证可执行文件、版本、解析路径与 Studio 检测结果——包管理器退出码为 0并不代表安装可用。完整汇报报告变更内容、安装位置、检测到的版本/来源、是否需要重启以及是否保留了旧 Runtime 目录。这套方法的核心哲学是可复用则复用、可验证则验证、可恢复则保留与源码中downloadRuntimeVersion先校验再替换、迁移成功后保留旧目录的设计完全一致。四种安装形态Desktop、npm、Docker Compose 与源码Desktop 桌面应用Desktop 是推荐的最终用户安装方式。从 Ekko Studio GitHub Releases 页面下载当前平台与架构对应的安装包打包应用内已内置 Studio 服务端并可另行管理一个 Hermes Runtime。一旦托管 Runtime 就绪打包版 Desktop 会安装受管理的命令 shimcommand shimsekko-studio打开 Desktop 应用。ekko-studio web ...运行打包内置的 Web UI CLI。ekko-studio cli ...Runtime 安装后运行托管的 Hermes CLI。ekko-studio-mcp [api|browser|devices|use]启动一组 Studio MCP 工具集。Desktop 安装完成后通过启动应用、打开 Agents 页面确认 Ekko 以 built-in 形式出现Runtime 就绪后用以下命令验证 shimekko-studio -h ekko-studio web version每次安装变更后都要刷新 Agents 页面Hermes 会显示为用户 CLI、托管 Runtime或未安装三种状态之一。升级 Desktop 应用使用应用内Check for Updates动作。更新器先检查 Cloudflare feed失败时回退到 GitHub latest-release feed只有确认后才会下载然后提供重启安装。注意这与下载 Hermes Runtime 版本或运行ekko-studio cli update是完全不同的事情。npm 安装前置要求Node.js 23 或更新版本以及可用的 npm 全局 prefix。node --version npm --version npm install -g hermes-web-ui hermes-web-ui version hermes-web-ui start --no-open hermes-web-ui status默认监听地址为http://localhost:8648。安装成功的判据是启动后hermes-web-ui version与hermes-web-ui status两者都必须满足。升级并重启hermes-web-ui update --no-openupgrade是该命令的别名。该命令会进行尽力而为的 npm 缓存清理、全局安装hermes-web-uilatest、定位更新后的全局 CLI并在原端口或指定端口上重启。Docker Compose使用仓库根目录的 docker-compose.yml。预构建镜像已内置集成好的 Hermes Agent runtime。WEBUI_IMAGEekkoye8888/hermes-web-ui docker compose up -d docker compose ps docker compose logs -f hermes-webui默认宿主机地址为http://localhost:6060。验证容器与内置 Hermes 可执行文件docker compose exec hermes-webui hermes --version持久化数据存放在${HERMES_DATA_DIR}默认./hermes_data之下Studio 状态位于${HERMES_DATA_DIR}/hermes-web-ui。重建或升级容器时必须保留这些挂载。升级预构建镜像时两次操作使用相同的WEBUI_IMAGE值WEBUI_IMAGEekkoye8888/hermes-web-ui docker compose pull WEBUI_IMAGEekkoye8888/hermes-web-ui docker compose up -d --force-recreate docker compose ps重要限制不要在容器内执行 Desktop Runtime 迁移——Docker 环境中的 runtime 由镜像与 Compose 挂载全权管理迁移操作只属于桌面托管场景。源码开发安装前置要求Git、Node.js 23 或更新版本、npm。git clone https://github.com/EKKOLearnAI/ekko-studio.git cd ekko-studio npm install npm run dev开发环境端点前端http://localhost:8649后端http://localhost:8647。用最小相关测试验证检出checkout在npm run build之后才可视为生产就绪构建。对已有检出升级时必须保留本地改动先检查git status仅当工作树与分支策略允许时才更新lockfile 变化时重新安装依赖然后重新构建。绝不为了升级 Studio 而丢弃脏工作树。安装所属路径Installation-owned pathsStudio 状态HERMES_WEB_UI_HOME默认~/.hermes-web-ui。Hermes 数据HERMES_HOMEWindows、macOS、Linux 下默认均为~/.hermes。npm 守护进程的 PID、日志、token 与数据库均存放在 Studio home 下。Docker 会把 Hermes 与 Studio 状态映射到容器内两个独立目录即使宿主机上两者都源于./hermes_data。这些路径只用于解释安装与持久化安装任务期间不得创建模型或凭据文件。Hermes CLI 与托管 Runtime 的完整生命周期用户 CLI 与托管 Runtime 的优先级Hermes 可以以用户安装的 CLI或Studio 托管的 Runtime两种形式存在。可见的用户 CLI 会优先于托管 Runtime 被选中因此每次都要汇报最终选中的来源user-cli或managed-runtime与路径。这一点在源码中得到印证getRuntimeVersionStatus通过discoverHermesCliInstallations枚举候选并从HERMES_RUNTIME_SOURCE环境变量或选中的安装来源中推导出source字段见 version-manager.ts。检测与验证现有 Hermes CLIStudio 的发现逻辑discovery.ts分三步若HERMES_BIN指定了路径先解析该路径搜索 Studio 进程可见的所有hermes——Windows 用where hermesmacOS/Linux 用which -a hermes对每个候选调用--version探测落在已安装 Runtime 目录内的标记为managed-runtime其余为user-cli。在 Studio 之外手动验证hermes --versionmacOS/Linux 上检查全部候选用which -a hermesWindows 用where hermes然后刷新 Agents 页面。如果终端与 Studio 结果不一致先重启 Studio 并对比 Studio 进程可见的 PATH再决定是否安装新副本——不要盲目重装。不需要托管 Desktop Runtime 时也支持非托管的包安装python -m pip install hermes-agent hermes --version注意这个用户 CLI 会在 Studio 选择时胜过已下载的 Runtime。下载并激活托管 Runtime使用Agents → Hermes → Install now / Manage Runtime。选择版本与下载源Cloudflare 或 GitHub。对于版本version与平台platformVersion Management 解析以下资源release taghermes-version-runtime清单hermes-runtime-platform.json归档清单中的asset.name字段默认平台键为mac-arch、win-arch或linux-arch由runtimePlatformKey生成win32 → win、darwin → mac其余保留拼上process.arch见 version-manager.ts。默认存储根为HERMES_WEB_UI_HOME/desktop-runtime安装后的 Runtime 位于runtime-root/hermes/version/platform安装器按以下阶段执行与 downloadRuntimeVersion 的实现一一对应解析远程清单resolve下载到临时.download文件download当清单提供asset.sha256时校验 SHA-256verify——源码中先比对已有归档的哈希以支持断点复用不一致才重新下载并再次校验解压到临时目录extract校验平台与必需文件install前的validateRuntimeDirectoryvalidateRuntimeAgentFiles仅在校验成功后通过 rename 原子替换目标目录激活已安装版本并刷新 Runtime 状态。必需的 Runtime 内容Python、Hermes 可执行文件、Node以及runtime-manifest.jsonWindows 还要求内置 Git。Schema 2 及更新版本额外要求可更新的 Hermes Git 检出python/.git/HEAD、python/pyproject.toml以及合法的 repository、ref、commit 与installMethod: git元数据——validateRuntimeDirectory会逐一校验这些字段commit 必须是 40 位十六进制见 version-manager.ts。下载完成后需验证全部项目下载任务状态为completed而非仅仅downloadVersion Management 将同一 platform/version 标记为已安装且激活Runtime 目录通过校验并包含runtime-manifest.json刷新后 Agents 页面报告 Hermes 已安装重启后ekko-studio cli --version返回可用版本。下载任务的状态机queued → running → completed/failed阶段queued/resolve/download/verify/extract/install/completed/failed在 version-manager.ts 的createDownloadJob中实现重复请求同一版本且任务仍在排队/运行时会被去重成功后自动调用activateInstalledRuntimeVersion并刷新状态。三种升级的严格区分Desktop 应用升级使用 DesktopCheck for Updates。托管 Runtime 包升级在 Version Management 下载更新的 Runtime 版本让其校验并激活然后重启。旧的未激活版本会保留直到显式删除。Runtime 0.19.1 及以上版本内置的 Hermes Agent 源码升级完全退出 Ekko Studio然后运行ekko-studio cli update。这不会升级 Desktop 或 Web UI。不要在 Studio 仍持有 Runtime 进程时运行ekko-studio cli update。重新打开 Studio 后验证 Hermes 版本与 Runtime 路径。激活中的 Runtime 不能被删除先激活并重启到另一个有效版本再通过 Version Management 删除未激活版本。源码中deleteInstalledRuntimeVersion会显式拒绝删除active版本见 version-manager.ts。安装器状态文件只读勿手写每个 Runtime 内含runtime-manifest.json至少记录schema、platform、Hermes Agent 版本、asset 标识/校验和以及对可更新源码 RuntimeHermes Git 源元数据。Desktop Runtime 选择状态存于HERMES_WEB_UI_HOME/desktop-runtime/active-version.json它使用 schema 1可能包含以下字段与 ActiveVersionManifest 接口一致desktopAppVersionhermesRuntimeVersionruntimeDirectoryruntimeRootDirectorypendingRuntimeRootDirectoryruntimeMigrationErrorruntimeActivationErrorwebUiVersionplatformupdatedAt激活操作会写入选中的 Runtime 目录/版本/平台并清除激活错误。缺失、不完整或平台不匹配的激活 Runtime 会使 Desktop 记录runtimeActivationError并在可能时回退到另一个有效安装的 Runtime——recordRuntimeSelectionResult会把失败详情与回退目标写入清单见 version-manager.ts。Runtime 存储迁移使用 Version Management 的Choose directory动作。目标目录必须已存在、可写、不在当前 Runtime 存储内部且不能是激活 Runtime 目录或其子目录。当HERMES_DESKTOP_RUNTIME_DIR强制覆盖时迁移不可用——scheduleRuntimeRootMigration会先检查该环境变量并拒绝见 version-manager.ts。调度迁移时只把pendingRuntimeRootDirectory写入active-version.json不会立即移动文件。重启 Ekko Studio 让迁移在本地服务启动前生效。重启时 Desktop 按以下顺序执行校验当前 Runtime在目标位置暂存副本修复被移动的 Hermes editable 引用与 launcher再次校验暂存的 Runtime复制目标位置缺失的有效已下载 Web UI 版本原子地把 Runtime 放到new-root/hermes/version/platform写入runtimeRootDirectory与runtimeDirectory移除pendingRuntimeRootDirectory保留旧存储目录以便恢复。失败时移除暂存目录、记录runtimeMigrationError、清除 pending 请求并继续使用原存储。不要手工改写路径强行成功——应修正目标目录或 Runtime 完整性问题后重新调度迁移。编码 Agent CLIClaude Code、Codex、Pi 与 Grok安装前置与包清单四个编码 Agent 都要求 Node.js 与 npmEkko Studio 的 npm/源码安装要求 Node.js 23。安装前先检查node --version npm --version npm prefix -g如果 Node 或 npm 不可用先停下来安装/修复 Node。当真正的问题是 Node 环境时不要把 Agent 安装问题误报为 Agent 包失败。Studio 安装以下全局 npm 包Agent可执行文件npm 包Claude Codeclaudeanthropic-ai/claude-codeCodexcodexopenai/codexPipiearendil-works/pi-coding-agentGrokgrokxai-official/grokPi 与其它编码 Agent 一样跟随包当前的 npm 版本。没有pi-mcp-adapter的安装是不完整的它同样跟随当前 npm 版本安装到HERMES_WEB_UI_HOME/coding-agent/pi-mcp-adapterAgents 页面的安装动作等价于以下命令Pi 适配器示例为 POSIX shell 语法Windows 上请使用 Agents 页面以便 Studio 正确解析其 home 目录npm install -g anthropic-ai/claude-code npm install -g openai/codex --registryhttps://registry.npmjs.org npm install -g earendil-works/pi-coding-agent npm install -g xai-official/grok --registryhttps://registry.npmjs.org studio_home${HERMES_WEB_UI_HOME:-$HOME/.hermes-web-ui} npm install --prefix $studio_home/coding-agent/pi-mcp-adapter pi-mcp-adapter只运行与请求 Agent 对应的那一行Pi 需要同时运行两行或直接使用 Agents 页面让 Studio 自动安装各包当前的 npm 版本。成功标准不只是 npm 退出码Studio 用 8 秒超时调用每个可执行文件的--version——源码中getCodingAgentStatus对每个命令执行execFileAsync(..., { timeout: 8000 })见 index.ts。手动验证claude --version codex --version pi --version grok --versionmacOS/Linux 用command -v claudecodex/pi/grok 同理检查可执行文件解析Windows 用where。安装成功必须同时满足npm 成功完成可执行文件在 Studio 可见的 PATH 中可解析agent --version成功退出刷新后 Agents 页面报告该 Agent 已安装对 PiHERMES_WEB_UI_HOME/coding-agent/pi-mcp-adapter/node_modules/pi-mcp-adapter/index.ts存在。Pi 在 CLI 存在但适配器入口缺失时故意报告未安装——getCodingAgentStatus中会检查getPiMcpAdapterEntry()缺失且用户未自行提供适配器时置installed: false并给出 Pi MCP Adapter is not installed 错误见 index.ts。此时从 Agents 页面重装 Pi 即可同时修复 CLI 与适配器。检查并应用更新Agents 页面Check update动作的行为Claude Code将检测版本与npm view anthropic-ai/claude-code version比较。Codex与npm view openai/codex version --registryhttps://registry.npmjs.org比较。Pi与npm view earendil-works/pi-coding-agent version比较。Grok与npm view xai-official/grok version --registryhttps://registry.npmjs.org比较。仅对 Codex 与 Grok的安装与更新检查使用官方 npm Registry。原因是Codex 依赖平台相关的可选包第三方镜像可能缺少它们即便主包存在Grok 镜像也可能暴露过时、平台不兼容的发布版本。按命令传入--registry参数源码中withCodingAgentRegistry只对codex/grok追加该参数见 index.ts避免修改用户的 npm 配置或影响其它编码 Agent 使用的 registry。有可用更新时更新动作会重跑同样的安装操作。完成后重新校验可执行文件路径与版本对 Pi 还要重新校验适配器。移除 Agent使用 Agents 页面的删除动作。Studio 会识别拥有该命令的 npm prefix并从每个适用的 prefix 卸载包。Pi 的移除还会从 Studio 适配器目录卸载pi-mcp-adapter并停止匹配的 Agent 运行进程源码中对应npm uninstall --prefix adapterRoot pi-mcp-adapter见 index.ts。移除不授权删除用户原生配置、认证、会话数据或无关的 npm prefix。移除后验证 Agents 页面报告未安装若命令仍能找到检查所有command -v/where结果与 npm prefix——可能还存在另一个用户自装的副本。PATH 诊断Studio 构建命令 PATH 时包含当前 Node 目录、npm 全局 bin 位置、常见 NVM 路径、登录 shell PATH以及常见 Desktop 二进制目录源码中commandEnv()用prependPathEntries组合这些来源见 index.ts。若终端验证成功但 Studio 仍报告未安装刷新 Agents 页面强制重新探测对比npm prefix -g与安装时使用的 prefix检查所有可执行文件副本完全重启 Ekko Studio使其继承更新后的登录 shell PATH仅当解析出的可执行文件或包确实缺失时才重装。整个安装工作流中不得创建 Agent 的模型或凭据配置——认证是安装成功之后的独立任务。安全与恢复原则SKILL 文档收尾给出了不可妥协的安全底线任何自动化脚本或人工操作都应遵守绝不删除激活中的 Hermes Runtime 版本。卸载 CLI 时不得删除用户配置或对话数据。迁移成功后保留旧 Runtime 存储——Studio 刻意保留它以便恢复。Runtime 校验、激活或迁移失败时保持旧的可运行 Runtime 处于激活状态并记录持久化的错误。可执行文件在终端可用但 Studio 看不到时先诊断 Studio 进程的 PATH 与 npm prefix再决定是否重装。用用户的自然语言解释说明与结果。这些原则与源码行为完全一致downloadRuntimeVersion在最终 rename 前先完整校验失败即回滚activateInstalledRuntimeVersion激活前再次validateRuntimeDirectory迁移失败时保留原存储并写入runtimeMigrationError。安装与生命周期任务由此具备可探测、可验证、可回滚的特性。结语把安装当作业务流程而非命令序列从 SKILL 文档与其三份参考可以看出Ekko Studio 的安装体系是一个分层、可恢复、UI 优先的生命周期系统Desktop/npm/Docker/源码四种形态覆盖不同部署需求托管 Hermes Runtime 通过解析清单 → 下载 → 哈希校验 → 解压 → 目录校验 → 原子替换 → 激活七步流水线保证可重复与可回滚编码 Agent 安装则以官方 npm 包为核心、以 8 秒版本探测为判据、以适配器完整性为补充条件。运维与自动化脚本可对照 SKILL.md、references/studio.md、references/hermes-runtime.md 与 references/coding-agents.md 组织自己的检查清单想深入底层实现可继续阅读 version-manager.ts、discovery.ts 与 coding-agents/services/index.ts。记住那句贯穿始终的原则包管理器的成功退出码不等于可用安装先探测、再变更、后验证、留恢复路径。赞分享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点击查看免费下载相关推荐Hermes Desktop 桌面端完全指南安装、配置与 Hermes Agent 图形化管理实战Hermes Desktop 桌面端完全指南安装、配置与 Hermes Agent 图形化管理实战 本文以仓库根目录下 README.zh CN.md httAI 应用交互助手桌面应用Umi-OCR 零基础实操4 类识别能力 全套避坑解压即可离线做 OCRUmi OCR 零基础实操4 类识别能力 全套避坑解压即可离线做 OCR Umi OCR 是免费、开源的离线 OCR 软件截图取字、批量图片识别、PDOCR桌面应用openJiuwen Agent Runtime如何实现Agent全生命周期管理DeploymentManager策略模式源码全解析openJiuwen Agent Runtime如何实现Agent全生命周期管理DeploymentManager策略模式源码全解析 openJiuwen A人工智能AI Agent后端LLMOps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
