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仓库目录 hermes-studio内建的Agents 页面为主线系统讲解四个主流编码 AgentClaude Code、Codex、Pi、Grok的安装前置条件、实际执行的 npm 命令、成功判定标准、版本更新检查、移除卸载与 PATH 诊断方法。读完本文你将掌握一套可直接照做的跨平台macOS / Linux / WindowsAgent 安装运维流程并理解 Agents 页面底层探测—安装—校验—刷新状态的完整闭环是如何实现的。前置条件先确认 Node.js 与 npm 环境四个编码 Agent 都以全局 npm 包形式分发因此Node.js 与 npm 是共同依赖。此外Ekko Studio 本身在 npm/源码方式安装时要求Node.js 23 或更高版本安装 Agent 前应一并满足。在开始安装之前先检查三件事node --version npm --version npm prefix -g其中npm prefix -g用于确定 npm 全局安装前缀后续安装后找不到命令的排查会反复用到它。如果 Node 或 npm 不可用请先停止安装流程修复 Node 环境后再继续——不要在 Node 环境本身有问题时把 Agent 安装失败误报为 Agent 包安装失败。这一点在服务端实现中也有对应兜底当探测不到 Node/npm 时services/index.ts 会抛出带有node_environment_missing错误码的明确提示而不是继续执行 npm 安装。四个 Agent 的包名与可执行命令对照Ekko Studio 安装的是以下四个全局 npm 包Agent可执行命令npm 包Claude Codeclaudeanthropic-ai/claude-codeCodexcodexopenai/codexPipiearendil-works/pi-coding-agentGrokgrokxai-official/grok这份命令 ↔ 包名映射在服务端被维护为一份集中式的 Agent 定义表TOOL_DEFINITIONS见 services/index.ts。每个定义同时声明了id、显示名称、提供商、可执行命令和包名Agents 页面的状态探测、安装、更新与删除全部复用这份定义从而保证页面安装的命令 聊天/运行功能实际启动的命令这一核心一致性的来源。Pi 与其他三个 Agent 一样跟随earendil-works/pi-coding-agent包当前的 npm 版本发布节奏但 Pi 的安装并不完整还依赖一个配套适配器pi-mcp-adapter同样跟随其当前 npm 版本它会被安装到HERMES_WEB_UI_HOME/coding-agent/pi-mcp-adapter其中HERMES_WEB_UI_HOME是 Ekko Studio 的主目录环境变量默认值为$HOME/.hermes-web-ui。该适配器是 Pi 与 Studio 运行时通信的关键组件后面成功判定一节会解释为什么它缺失时 Pi 会被判定为未安装。Agents 页面的安装动作底层实际执行的命令Agents 页面客户端入口见 AgentManagerView.vueAPI 封装见 api/coding-agents.ts承担了跨平台安装的全部工作它会探测与聊天启动相同的那份可执行文件、处理 npm 前缀、安装 Pi 所需的适配器、刷新安装状态并上报最终解析到的路径。页面上的安装动作等价于手工执行以下命令Pi 适配器示例为 POSIX shell 语法Windows 上请使用 Agents 页面由 Studio 自行正确解析其主目录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则要同时运行 Pi 的两行全局包 适配器或者直接使用 Agents 页面让 Studio 自动安装这些包当前的 npm 版本。对照服务端源码 services/index.ts 的installCodingAgent实际流程与手工命令一一对应先执行npm install -g package并针对 Codex / Grok 追加--registryhttps://registry.npmjs.org见withCodingAgentRegistryservices/index.ts安装超时设置为 10 分钟安装过程中的并发安装请求会被以409 Install is already running拒绝避免重复操作若目标是 Pi 且用户配置中未提供适配器则调用installBundledPiMcpAdapter()其本质是npm install --prefix adapterRoot pi-mcp-adapter见piMcpAdapterInstallArgsservices/index.ts安装结束后重新探测状态并返回完整状态清单供页面刷新展示。为什么只有 Codex 和 Grok 强制走官方 npm Registry注意上面命令中--registryhttps://registry.npmjs.org只出现在 Codex 与 Grok 两行。原因有两点Codex依赖平台相关的可选包platform-specific optional packages即使主包在第三方镜像上存在这些平台相关依赖也可能缺失Grok的镜像可能暴露过期、与平台不兼容的旧版本。因此 Studio 只对这两个包的安装与更新检查强制使用官方 npm Registry。同时这种逐命令传递 registry 参数的做法不会修改用户自身的 npm 配置也不会影响其他编码 Agent 所使用的 registry——即静默、无副作用。成功判定标准五条全部满足才算安装成功Studio 在探测 Agent 时会用 8 秒超时执行executable --version对应源码getCodingAgentStatus中的timeout: 8000见 services/index.ts。你也可以手动验证claude --version codex --version pi --version grok --version在 macOS / Linux 上用command -v claude、command -v codex、command -v pi或command -v grok检查可执行文件解析Windows 上对应使用where。安装成功的完整判定是同时满足以下五条npm安装命令执行成功可执行文件能在 Studio 可见的PATH中被解析到agent --version正常退出退出码为 0刷新后Agents 页面将该 Agent 报告为已安装对于 Pi额外要求HERMES_WEB_UI_HOME/coding-agent/pi-mcp-adapter/node_modules/pi-mcp-adapter/index.ts文件存在。其中 Pi 的判定最为严格当 CLI 已存在但适配器入口缺失时Pi 会被刻意报告为未安装。源码中的具体逻辑是getCodingAgentStatus对 Pi 检查getPiMcpAdapterEntry()指向的index.ts是否存在若不存在且用户配置也未自行提供适配器则即使pi --version成功也会返回installed: false并附带错误信息Pi MCP Adapter is not installed见 services/index.ts。用户侧是否已自备适配器的判断逻辑位于 pi/settings.ts 的userSettingsProvidesPiMcpAdapter。因此如果 Pi 缺失适配器请从 Agents 页面重新安装 Pi一次性修复 CLI 与适配器两部分。检查更新与应用更新Agents 页面的Check update动作对四个 Agent 分别执行如下比较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比较。源码checkUpdateAgent的实现services/index.ts以 15 秒超时执行npm view package version再用versionGteservices/index.ts做语义化版本比较只有当已安装版本低于最新版本时才报告有更新。当检测到更新后更新动作会重新执行与安装完全相同的命令。更新完成后需要重新验证可执行文件路径与版本对于 Pi还要重新验证适配器即上面的第 5 条判定。移除 Agent精确卸载而非暴力删除使用 Agents 页面的删除动作。Studio 的删除逻辑deleteCodingAgentservices/index.ts分四步识别命令所属的 npm 前缀通过getCommandPackagePrefixes解析command -v/where找到的所有命令路径从路径中的node_modules/lib/package结构反推出全局前缀见 services/index.ts对每个前缀执行npm uninstall -g --prefix prefix packagePi 额外卸载适配器从 Studio 适配器目录执行npm uninstall --prefix adapterRoot pi-mcp-adapter停止匹配的运行中进程调用codingAgentRunManager.stopMatching结束与目标 Agent 相关的运行实例重新探测状态并返回结果。需要特别强调的是卸载不会授权删除用户的原生配置文件、认证信息、对话数据也不会动到与本 Agent 无关的 npm 前缀。删除后请确认 Agents 页面显示未安装如果命令仍然存在请逐一检查所有command -v/where结果与 npm 前缀——很可能还残留了另一份用户自行安装的副本。PATH 诊断Studio 如何构建它的 PATH终端里能跑通、但 Agents 页面仍显示未安装是常见的困惑。原因在于 Studio 并非直接继承你的终端 PATH而是自行拼装一份命令 PATH来源包括对应源码commandEnv、getGlobalNpmBin、getLoginShellPath、getNvmNodeBinPaths、getDesktopCommonBinPaths见 services/index.tsStudio 当前 Node 所在目录dirname(process.execPath)npm 全局 bin 位置通过npm prefix -g得到常见的 NVM 路径$NVM_DIR/versions/node/version/bin仅桌面端生效登录 shell 的PATH执行 login shell 的-lc printf %s $PATH获取仅桌面端生效常见的桌面二进制目录如~/.npm-global/bin、~/.local/bin、~/.yarn/bin、~/.config/yarn/global/node_modules/.bin、~/.pnpm、~/Library/pnpm、/opt/homebrew/bin、/usr/local/bin。因此如果出现终端验证成功但 Studio 仍报告未安装按以下顺序排查刷新 Agents 页面强制发起一次新的探测对比npm prefix -g与安装时使用的前缀是否一致检查可执行文件的所有副本command -v/where可能只显示第一个完全重启 Ekko Studio使其继承更新后的登录 shell PATH仅当解析到的可执行文件或包确实不存在时才重新安装。另外需要明确安装流程的边界不要在本次安装工作流中创建 Agent 的模型或凭据配置。认证Authentication是安装成功之后的独立任务两者不要混在一起做否则安装失败时很难定位是环境问题还是配置问题。小结Ekko Studio 的 Agents 页面把四个编码 Agent 的安装收敛为一次点击、自动探测、自动校验的闭环安装前检查 Node/npm 环境安装时按 Agent 精确执行对应 npm 命令Codex/Grok 强制官方 RegistryPi 附带适配器安装后以--version 适配器入口做五条成功判定更新与卸载复用同一套定义表与 npm 前缀解析逻辑。理解这份机制后无论是手动命令行安装、排查终端可用但页面未安装的 PATH 问题还是安全地移除 Agent都可以做到心中有数、一次到位。相关实现细节可继续阅读 services/index.ts、pi/settings.ts 与控制器入口 controllers/agents.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点击查看免费下载相关推荐Superpowers跨平台部署指南Claude Code、Codex和OpenCode完全适配Superpowers跨平台部署指南Claude Code、Codex和OpenCode完全适配 想要让AI编程助手发挥最大潜力Superpowers正是你AI 技能AI 插件开发工具Jpom 运维管理平台全面部署与应用指南Jpom 运维管理平台全面部署与应用指南 项目概述与价值定位 Jpom是一款由Dromara社区开发的开源运维管理平台专注于为开发团队提供轻量级的项目构建、部运维后端CI/CDDevOps指标监控Claude-Flow平台部署与管理指南Claude Flow平台部署与管理指南 1. 准备阶段环境配置与系统要求 1.1 系统环境准备 系统环境准备是部署Claude Flow平台的基础步骤确保人工智能AI Agent多智能体Agent 编排Agent 记忆工具调用代码智能体MCP 服务AI 评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考