Skip to content

README_zh.md

Latest commit

 

History

History
542 lines (414 loc) · 31.5 KB

README_zh.md

File metadata and controls

542 lines (414 loc) · 31.5 KB
Raw

Ekko Studio English

本地优先的 AI 工作区，支持多 Agent 聊天、编码和可视化工作流。
提供桌面应用和可自托管的 Web 控制台，支持
Hermes Agent、Ekko Agent，以及包含 Claude Code、Codex 在内的 14 种 Coding Agent 集成。
在同一个工作区中管理对话、群组协作、语音、文件和设备。

下载 Ekko Studio 桌面版 · 使用文档 · npm install -g ekko-studio && ekko-studio-web start

Ekko Studio 新建聊天页面：Agent 轮播卡片与统一输入框

npm 版本 许可证 Star

Ekko Studio 原名 Hermes Studio / Hermes Web UI。GitHub 仓库为 EKKOLearnAI/ekko-studio。主 npm 包名为 ekko-studio，启动命令为 ekko-studio-web；旧的 hermes-web-ui 包和命令继续保留，并同步发布相同版本。

界面预览

以下截图于 2026-11-03 从本地运行的 v0.8.13 源码版本截取，使用隔离数据目录。工作流示例通过界面创建，尚未执行；Agent 状态来自本机实际检测。详见截图说明。

可视化工作流 Agent 管理
未执行的工作流示例：Claude、Codex 与开启人工审批的审核节点 Agent 管理器：完整展示 16 张内置 Agent 与 Coding Agent 卡片
连接多个 Agent 节点，并设置人工审批；此示例尚未执行。 在同一界面管理 Agent 安装、设置和更新。

核心能力

模块 Ekko Studio 能做什么
多 Agent 运行时 接入下表所列的 Agent，支持流式回复、工具调用轨迹、生成文件预览、持久化会话和桌面独立聊天窗口。
Studio 工作区 为不同 Agent 运行时提供统一的单聊、群聊、Global Agent、工作流、文件、语音、媒体、设备、主题、日志、用量和 App 连接能力。
Agent 控制面 将 Hermes 的 Profile、Provider、模型、记忆、技能、插件、任务、Kanban、渠道和运行时管理保留在对应的 Agent 模块内。
自动化 构建可执行的可视化工作流，通过定时任务、审批节点、群聊房间、平台渠道和 MCP Server 连接受支持的 Agent 运行时。
工作区工具 提供文件浏览器、Web 终端、桌面 Agent 浏览器、截图、语音输入输出、Coding Agent、设备发现、学习轨迹和性能视图。
分发形态 支持 Windows/macOS/Linux 桌面应用、npm CLI 包和 Docker 镜像。

支持的 Agent

单聊、群聊和工作流共用同一份 Agent 列表。Coding Agent 在运行 Studio 后端的机器上执行，CLI 也需要安装在这台机器上。

Agent 配置与安装方式
Ekko Agent、Hermes Agent Ekko 为内置运行时。桌面版和 Docker 内置 Hermes Runtime；npm 安装会发现已有的 Hermes 安装。
Claude Code、Codex、Pi、Grok、OpenCode、DeepSeek Harness（DSH） 支持 Studio 隔离配置或原生全局配置；可通过 Agent 管理器安装和执行受支持的更新。
Qwen Code、Kimi Code、CodeBuddy、GitHub Copilot CLI、ZCode 支持 Studio 隔离配置或原生全局配置。ZCode 需手动安装，其余可通过 Agent 管理器进行 npm 安装。
Cursor、Qoder、Antigravity Cursor 和 Qoder 使用原生全局配置。Antigravity 支持隔离和全局启动。Cursor 和 Antigravity 需手动安装。

隔离模式为会话使用独立配置，受支持的运行时可使用 Studio 选择的 Provider/模型；全局模式沿用 CLI 已有配置和登录状态。模型、工具和上下文控制能力因运行时而异。 详细说明见原生 Coding Agent、Antigravity CLI 和 DSH 接入文档。

功能特性

AI 聊天

  • 从响应式 Agent 卡片页面新建聊天；首次默认选择 Ekko，并记住上次的 Agent、模型、工作目录、启动方式和推理选项
  • 聊天前端通过 Socket.IO /chat-run 实时流式更新，由 Studio 分发给所选运行时适配器
  • 多会话管理 — 创建、重命名、删除、切换会话
  • 自建会话数据库 — Studio 会话使用本地 SQLite；Hermes state.db 仅作为只读来源用于 Hermes 历史 API
  • 按来源分组会话（Telegram、Discord、Slack 等），可折叠手风琴面板
  • 活跃会话实时指示器 — 正在进行的会话置顶并显示旋转图标
  • 按最新消息时间排序会话列表
  • Markdown 渲染，支持语法高亮和代码复制
  • 工具调用详情展开（参数 / 结果）
  • 按 Profile 隔离的文件上传、剪贴板图片/文件粘贴和工作区附件
  • 文件下载支持 — 按解析后的路径下载用户上传文件和 Agent 生成文件，兼容 local、Docker、SSH、Singularity 等多种 terminal backend
  • 可直接预览 Agent 生成的 HTML、PDF、DOCX、PPTX、XLSX、CSV、图片、Markdown 和源码文件
  • 会话搜索 — Ctrl+K 搜索 Studio 本地会话库；不包含只读 Hermes 历史会话
  • 会话分类、消息引用、压缩进度和可持久恢复的后台委派结果
  • 持久化任务卡片，实时显示步骤进度、审批请求和澄清问题
  • 按 Profile 授权的模型选择器，按运行时展示可用 Provider/模型
  • 每轮显示 Token 用量、缓存命中、预估费用和生成速度；受支持的运行时还提供上下文用量和压缩控制

平台渠道

在一个页面统一配置 10 个平台：

平台 功能
Telegram Bot Token、提及控制、表情回应、自由回复聊天
Discord Bot Token、提及、自动线程、表情回应、频道白名单/黑名单
Slack Bot Token、提及控制、Bot 消息处理
WhatsApp 启用/禁用、提及控制、提及模式
Matrix Access Token、Homeserver、自动线程、私信提及线程
飞书 App ID / Secret、提及控制
钉钉 Client ID / Secret、提及控制
QQBot App ID / Secret、提及控制
微信 扫码登录（浏览器扫码，自动保存凭证）
企业微信 Bot ID / Secret
  • 凭证和渠道行为设置写入所选 Hermes Profile 下的 .env 和 config.yaml
  • 每个平台已配置/未配置状态检测
  • Gateway 自动启动需在 Hermes 设置中开启；普通 Studio 聊天无需平台 Gateway

用量分析

  • Token 总用量明细（输入 / 输出）
  • 会话数及日均统计
  • 预估费用追踪及缓存命中率
  • 模型使用分布图
  • 30 天每日趋势（柱状图 + 数据表格）

定时任务

  • 创建、编辑、暂停、恢复、删除 Cron 任务
  • 立即触发执行
  • Cron 表达式快捷预设

Kanban

  • 按 Profile 管理的 Kanban 看板，用于规划和跟踪 Agent 工作
  • 可在仪表盘中创建任务、更新任务并移动状态
  • 使用 Hermes Kanban CLI 及其任务存储，并由 Studio 提供认证和 Profile 访问控制

可视化工作流

  • 基于 Vue Flow 的画布，支持 Agent 列表中的运行时、文件/图片附件和对应的启动配置
  • 支持有向连线、结构化条件、成功/失败路由、循环和审批门
  • 工作流定义可导入/导出，并支持按 Profile 管理工作区
  • 支持运行预算、截止时间、停止、重跑和持久化执行历史
  • 可在画布回放冻结的运行快照、节点对话、路径选择和执行证据

模型管理

  • 从凭证池自动发现模型（~/.hermes/auth.json）
  • 从每个 Provider 端点获取可用模型（/v1/models）
  • 添加、更新、删除 Provider（预设和自定义 OpenAI 兼容）
  • 支持 OpenAI Codex、Nous Portal、xAI、Claude 和 GitHub Copilot 的 OAuth/设备授权
  • Provider URL 自动检测，支持非 v1 API 版本（如 /v4）
  • Provider 级模型分组、可见模型控制、别名、刷新和默认模型切换
  • 在模型页分别管理 STT 与 TTS Provider

多配置文件

  • 创建、重命名、删除、切换 Hermes 配置文件（Profile）
  • 克隆现有配置文件或从归档导入（.tar.gz）
  • 导出配置文件用于备份或分享
  • 按 Profile 隔离配置、缓存、上传、会话、任务、用量、记忆、技能、插件、Provider 和模型可见性
  • 账号绑定 Profile 权限：超级管理员可以管理全部 Profile；普通管理员只能查看和使用分配给自己的 Profile

文件浏览器

  • 浏览远程后端文件（local、Docker、SSH、Singularity）
  • 上传、下载、重命名、复制、移动和删除文件
  • 上传文件保存到当前选择/请求的 Hermes Profile 目录下；下载按真实路径解析，支持下载上传目录外的 Agent 产物
  • 创建目录
  • 预览和编辑支持的文件并提供语法高亮，还可把工作区文件附加回聊天

群聊

  • 多 Agent 聊天房间，通过 Socket.IO 实时通信
  • @提及路由 — 提及 Agent 触发上下文回复
  • 上下文压缩 — 历史消息超过 Token 阈值时自动摘要压缩
  • 输入状态和回复进度指示器
  • 房间创建、删除和邀请码管理
  • Agent 管理 — 添加/移除房间中的 Agent，支持独立 Profile
  • SQLite 消息持久化
  • 移动端响应式布局，可折叠侧边栏

Coding Agents

  • 发现、配置、启动和监控上表中的 14 种 Coding Agent 集成；通过 Agent 管理器安装和更新受支持的 CLI
  • 内置 Coding Agent 终端、会话历史、工作区选择、图片输入和文件 Diff
  • 提供独立代理路由和 API 模式，适配不同 Provider/模型
  • 支持桌面独立聊天窗口，并持久化输出和 reasoning 元数据
  • Coding Agent 页面中的共享 ~/.agents/skills 为只读；原生设置、私有技能和 MCP 管理能力因 Agent 而异

DeepSeek Harness（DSH）

  • 支持单聊、群聊和工作流节点，可使用 Studio 选择的 Provider/模型，也可使用 DSH 原生全局配置。
  • 新建会话、添加群聊成员或配置工作流节点时可选择 Agent 预设，恢复会话时保留原有选择。
  • 复用原生 web profile 的插件。插件配置嵌入插件自带的设置界面并跟随黑白主题，插件列表管理已安装的包；Agent 预设使用独立的 Studio 管理页。
  • 管理 DSH 设置、指令、MCP 和私有技能。共享 ~/.agents/skills 在所有 Coding Agent 页面中仅展示，禁止编辑和删除。

通过 Agent 管理器，在运行 Studio 后端的机器上安装 DSH。安装原生插件还需要该机器的 PATH 中有 pnpm。配置方式、Profile 复用和兼容性说明见 DSH 接入文档。

桌面 Agent 浏览器

  • 桌面端多标签浏览器，Agent 可通过托管 MCP Server 进行导航和交互
  • 支持隔离浏览器 Profile、标签控制租约、代理、下载、Cookie 和权限管理
  • 支持可访问性快照、截图、控制台日志和页面标注
  • 支持分页局部查询和顺序批量操作，并返回文本变化、选中值及新开标签等观察结果

移动 App 与会话分享

  • 通过局域网、鉴权直连或云端中转连接 App，直连不可用时回退到中转
  • 通过任务卡片和通知跟踪单聊、群聊和工作流进度；受支持的 iOS 版本还提供实时活动（Live Activities）
  • 将单个会话分享给 App 账号，配置输入、文件、语音和终端权限，并可撤销访问
  • 在 App 中使用可恢复的终端会话

连接方式与权限边界见 App 连接 和会话分享。

JEV 评估

  • 按 Profile 配置记忆召回、技能匹配和学习评估
  • 浏览器操作、群聊和工作流评估可单独开启或关闭

配置方式和接入状态见 JEV 文档。

技能与记忆

  • 浏览和搜索已安装的技能
  • 查看技能详情和附件
  • 安装和管理 Skill Bundles，并查看按 Profile 统计的技能用量
  • 用户笔记、Ekko Agent 持久记忆和按 Profile 管理的记忆
  • 学习轨迹关系图，支持技能/记忆关系、分类筛选、详情查看和播放

主题自定义

  • 支持明暗模式、界面风格、基础字号、文字颜色和选中颜色
  • 支持按账号保存背景图片，并在整个工作区实时预览

日志

  • 查看 Agent / Server / Error 日志
  • 按日志级别、日志文件和关键词过滤
  • 结构化日志解析，HTTP 访问日志高亮

管理与运行时

  • 设备和局域网 Peer 页面，用于本地网络发现和 Peer 工具能力
  • MCP 管理器，用于托管的 ekko-studio-* Server、Profile 自动注入和 api / browser / devices / use / plan 工具集；任务计划和澄清使用独立的 ekko-studio-interaction Server
  • Runtime Version 和 Version Preview 工具，用于隔离测试新版本
  • 面向超级管理员的性能监控视图

认证

  • 基于 Token 的认证（首次运行自动生成或通过 AUTH_TOKEN 环境变量设置）
  • 用户名/密码登录，并在设置页提供账户管理
  • 默认登录名/密码为 admin / 123456；登录后会提示尽快修改默认账户和密码
  • 超级管理员可以管理用户和 Profile 绑定；普通管理员只能管理自己的账户信息

CLI 维护命令：

# 删除持久化的登录 IP 锁记录
ekko-studio-web clear-login-locks

# 删除登录锁并重启正在运行的 Studio 服务
ekko-studio-web clear-login-locks --restart

# 创建或重置默认超级管理员登录名/密码为 admin / 123456
ekko-studio-web reset-default-login

clear-login-locks 会删除 ${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/.login-lock.json。如果服务正在运行，需要重启服务才能清理内存中的锁定状态。reset-default-login 会更新 Studio 账户数据库；如果已存在 admin 用户，则会把密码重置为 123456，并启用为超级管理员账户。

设置

  • 显示（流式输出、紧凑模式、推理过程、费用显示）
  • Agent（最大轮次、超时时间、工具强制执行）
  • 记忆（启用/禁用、字符限制）
  • 会话重置（空闲超时、定时重置）
  • 隐私（PII 脱敏）
  • 模型设置（默认模型 & Provider）
  • Profile 和 Provider 配置

语音 / TTS / STT

  • 在模型 → STT 和模型 → TTS 中管理语音 Provider；旧的设置 → 语音入口会跳转到这里。
  • TTS 适配器：Edge、OpenAI 兼容、MiMo、豆包、ElevenLabs、Gemini、xAI、Mistral、MiniMax、DeepInfra。
  • STT 适配器：浏览器、OpenAI 兼容、豆包、Groq、Mistral、xAI、ElevenLabs、DeepInfra。
  • 可在聊天输入框使用可编辑的回合制语音输入，也可打开全屏实时语音舞台进入连续的语音交互体验。
  • Provider Key 和 MiMo 音色复刻音频保存在服务端，浏览器只接收脱敏后的 Secret 状态。
  • 开始新的语音输入会先停止 Assistant 播放，但不会隐式取消正在执行的 Agent Run。
  • 支持的设置项、安全边界和当前非目标范围见 docs/voice-dialogue.md。
  • 实时语音舞台不代表同时听说的全双工通话；电话接入和常驻唤醒词监听仍不在当前范围。

Web 终端

  • 集成终端，基于 node-pty 和 @xterm/xterm
  • 多会话支持 — 创建、切换、关闭终端会话
  • 通过 WebSocket 实时传输键盘输入和 PTY 输出
  • 支持窗口大小调整

桌面应用与自动更新

  • Windows、macOS 和 Linux 原生 Electron 桌面壳
  • 内置 Studio 运行时，并自动启动本地服务
  • 截取屏幕区域、标注并附加到单聊或群聊；可配置全局截图快捷键
  • 受支持的 Windows/macOS 环境可在截图时隐藏 Studio；Linux 按桌面环境使用 X11 或系统 Screenshot Portal
  • 桌面自动更新优先使用 Cloudflare 下载端点获取更新元数据和安装包
  • 如果 Cloudflare 更新源不可用，会回退到 GitHub Releases latest 资源
  • Windows 升级时会先尝试关闭已有 Ekko Studio 进程，再替换文件

快速开始

桌面应用（推荐）

从 GitHub Releases 下载最新的 Ekko Studio 桌面安装包。

桌面版会发布 macOS、Windows 和 Linux 构建；适用时会区分不同 CPU 架构。 桌面应用内置 Studio 运行时；在 Windows、macOS 和 Linux 上，Hermes Agent 数据统一保存到 ~/.hermes。

桌面壳自身的 Studio 状态会单独保存到 ~/.hermes-web-ui，除非设置了 HERMES_WEB_UI_HOME。

打包后的桌面应用启动后，会安装受管命令 shim，避免桌面应用、内置 Hermes Agent CLI 和内置服务端 CLI 的命令互相冲突：

命令 说明
ekko-studio 打开 Ekko Studio 桌面应用
ekko-studio cli ... 运行内置 Hermes Agent CLI
ekko-studio web ... 运行内置 hermes-web-ui 命令
ekko-studio -h 显示 wrapper 帮助
ekko-studio-mcp [api|browser|devices|use|plan] 运行指定的受管 Studio MCP 工具集

桌面命令统一为 ekko-studio；安装新命令时会移除旧的受管 hermes-studio 命令，不保留兼容别名。

使用 ekko-studio cli -h 查看 Hermes Agent CLI 帮助，使用 ekko-studio web -h 查看服务端 CLI 帮助。ekko-studio-mcp 默认暴露 api 工具集；按任务选择 browser、devices、use 或 plan，可以缩小 MCP 暴露面。

桌面自动更新会优先读取 https://download.ekkolearnai.com/latest。 如果该端点不可用，更新器会回退到 https://github.com/EKKOLearnAI/ekko-studio/releases/latest/download。

npm 安装

npm install -g ekko-studio
ekko-studio-web start

旧包 hermes-web-ui 会继续同步更新。两个包都提供 ekko-studio-web 和原有命令。 选择其中一个包安装即可；全局命令有重叠，切换包名时请先卸载原包再安装新包。 用户数据仍保存在 ~/.hermes-web-ui。

打开 http://localhost:8648

需要 Node.js 23 或更高版本。Ekko Agent 随包内置；使用 Hermes Agent 时，需在同一台机器安装其运行时，或选择内置运行时的桌面版/Docker。

Docker Compose

单容器部署，内置 Hermes Agent 运行时：

# 使用预构建镜像（推荐）
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d

# 或从源码构建
docker compose up -d --build

docker compose logs -f hermes-webui

打开 http://localhost:6060

  • Hermes 持久化数据目录：./hermes_data
  • Studio 认证 Token 存储在 ./hermes_data/hermes-web-ui/.token
  • 首次启动并开启认证时，Token 会打印到容器日志中
  • 运行参数全部由 docker-compose.yml 环境变量驱动

更详细的说明与排错见：docs/docker.md

Hermes Agent 运行时发现

Studio 启动后端聊天能力时，会优先使用包含 run_agent.py 的源码目录，例如 ~/.hermes/hermes-agent。如果找不到源码目录，会退回到已安装 hermes 命令所使用 的 Python 环境，再退到系统 Python。因此源码安装和 pip install hermes-agent 这类 包安装方式都可以兼容。

Studio 环境变量

这些变量用于配置 Ekko Studio、本地 Hermes Runtime 集成以及开发/预览辅助能力。Provider API Key 和 Hermes Agent 相关设置通常仍通过 Hermes Profile 管理；这里列出的变量是进程级覆盖项。

变量 默认值 说明
PORT 8648 Studio 服务监听端口。
BIND_HOST 0.0.0.0 Studio 服务绑定地址。如需 IPv6，可显式设置为 ::。
HERMES_LAN_ADVERTISE_URL 未设置 App 局域网二维码使用的可访问 Studio 地址。Docker 中若通过 localhost 打开，请设置为宿主机局域网 URL，例如 http://192.168.1.20:6060。
HERMES_APP_ENTITLEMENT_REQUIRED true App 局域网 Relay 必须携带有效的云端签名。仅在临时兼容排查时设置为 false。
HERMES_APP_ENTITLEMENT_PUBLIC_KEY 内置 可选的 RS256 App 签名 PEM 公钥覆盖。签名 issuer 为 hermes-studio-server，audience 为 ekko-studio。
HERMES_WEB_UI_HOME ~/.hermes-web-ui Studio 数据目录，用于认证 Token、登录凭据、日志、数据库和默认上传目录。兼容支持 HERMES_WEBUI_STATE_DIR 作为别名。
HERMES_WEBUI_STATE_DIR 未设置 HERMES_WEB_UI_HOME 的兼容别名。
HERMES_WEB_UI_DISABLE_MCP_AUTOINJECT 未设置 关闭启动时向 Hermes profile 配置自动注入托管的 ekko-studio-* MCP server。
HERMES_WEB_UI_ALLOW_TRANSIENT_MCP_AUTOINJECT 未设置 当 HERMES_WEB_UI_HOME 位于临时目录（例如 Version Preview runtime）时，仍允许托管 MCP 自动注入。
UPLOAD_DIR $HERMES_WEB_UI_HOME/upload 覆盖上传根目录。文件会保存在按 Profile 隔离的子目录下。
CORS_ORIGINS 仅同 host HTTP、Socket.IO、WebSocket 跨源 allowlist，支持逗号或空格分隔。只有明确需要旧版 wildcard CORS 时才设置为 *。
AUTH_TOKEN 自动生成 显式指定 Bearer Token。未设置时，Studio 会在 HERMES_WEB_UI_HOME 下自动生成。
AUTH_JWT_SECRET AUTH_TOKEN 用户名/密码会话的 JWT 签名密钥覆盖。
HERMES_WEB_UI_AUTH_JWT_EXPIRES_IN 30d 用户名/密码会话 JWT 有效期。支持秒数或 s/m/h/d 后缀，例如 12h 或 7d。
PROFILE default 启动/默认 Hermes profile。运行时请求使用前端当前选择且当前账号有权限访问的 Profile。
LOG_LEVEL info Server 日志级别。
BRIDGE_LOG_LEVEL $LOG_LEVEL 或 info Bridge 日志级别。
MAX_DOWNLOAD_SIZE 200MB 最大文件下载大小。
MAX_EDIT_SIZE 10MB 最大可编辑文件大小。
WORKSPACE_BASE 当前用户 Home 目录 Workspace 浏览根目录。
HERMES_HOME ~/.hermes Windows、macOS 和 Linux 上的 Hermes 数据目录。
HERMES_BIN hermes 自定义 Hermes CLI 二进制路径。
HERMES_AGENT_ROOT 自动发现 包含 run_agent.py 的 Hermes Agent 源码目录。
HERMES_AGENT_BRIDGE_PYTHON 自动发现 用于启动 agent bridge 的 Python 解释器。
HERMES_AGENT_BRIDGE_UV 自动发现 可用时用于启动 agent bridge 的 uv 可执行文件。
UV 自动发现 uv 可执行文件 fallback。
PYTHON 自动发现 agent bridge 的 Python 可执行文件 fallback。
HERMES_AGENT_BRIDGE_ENDPOINT 平台默认值 Agent bridge broker endpoint。Windows 默认 tcp://127.0.0.1:18765；macOS/Linux 默认 ipc:///tmp/hermes-agent-bridge.sock。
HERMES_AGENT_BRIDGE_TIMEOUT_MS 120000 Node 请求 bridge broker 的响应超时。
HERMES_AGENT_BRIDGE_CONNECT_RETRY_MS 5000 连接 bridge socket 失败时的短重试窗口。
HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS 120000 等待 Python bridge ready 的超时。
HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN 开启 Studio 关闭和重启时是否停止 Bridge Broker；设为 0、false、no 或 off 才会在重启时保留 Broker。
HERMES_AGENT_BRIDGE_AUTO_RESTART 开启 bridge broker 意外退出后是否自动重启；设为 0、false、no 或 off 可关闭。
HERMES_AGENT_BRIDGE_RESTART_DELAY_MS 1000 bridge 自动重启退避的基础延迟。
HERMES_AGENT_BRIDGE_PLATFORM cli 传给 Hermes Agent 的 platform 标识。
HERMES_AGENT_BRIDGE_WORKER_TRANSPORT 平台默认值 Profile worker transport。设为 tcp 使用 loopback TCP；设为 ipc/unix 使用 Unix domain socket；默认 Windows TCP、macOS/Linux IPC。
HERMES_AGENT_BRIDGE_WORKER_PORT_BASE 18780 TCP worker endpoint 起始端口。
HERMES_BRIDGE_PROVIDER profile/默认值 bridge 运行时的 provider 覆盖。
HERMES_BRIDGE_TOOLSETS profile/默认值 bridge 运行时的 toolset 覆盖。
HERMES_BRIDGE_MAX_TURNS profile/默认值 bridge 运行时的最大轮数覆盖。
HERMES_BRIDGE_SUPPRESS_PLATFORM_HINT cli 控制传给 Hermes Agent 的 bridge platform hint suppression。
HERMES_OPENROUTER_APP_REFERER https://ekkostudio.xyz bridge 运行发送给 OpenRouter 的 attribution referer。
HERMES_OPENROUTER_APP_TITLE Ekko Studio Bridge 运行发送给 OpenRouter 的 Attribution Title。
HERMES_OPENROUTER_APP_CATEGORIES cli-agent,personal-agent bridge 运行发送给 OpenRouter 的 attribution categories。
HERMES_WEB_UI_MANAGED_GATEWAY 默认开启 控制 Studio 托管 Hermes Gateway 进程；设为 0、false、no 或 off 时改用 hermes gateway start。
HERMES_WEB_UI_DISABLE_GATEWAY_AUTOSTART 未设置 覆盖需手动开启的 Hermes Gateway 自动启动策略。设为 1、true、yes 或 on 时，即使设置中已开启，也跳过启动检查和配置驱动的状态协调。
HERMES_WEB_UI_DISABLE_SKILL_INJECTION 未设置 跳过启动时的内置 Skill 注入；如果内置 Skills 由 Studio 外部管理，可设为 1、true、yes 或 on。启用注入时，Studio 只更新自己此前安装的 Skills 或内容完全相同的既有内置副本；本地修改和用户拥有的同名 Skills 会跳过。
HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN 默认开启 Studio 关闭时仅停止由当前 Studio 进程启动并登记的 Gateway；设为 0 或 false 可让它们分离运行。外部探测到的 Gateway 不会被收编或关闭。
HERMES_WEB_UI_SHUTDOWN_FORCE_EXIT_MS 10000 Studio 的短暂资源清理窗口；超时后会强制结束自己持有的进程树再退出。
HERMES_DESKTOP_STOP_TIMEOUT_MS 20000 Desktop 宿主原有的整树强制结束期限，独立于 Web UI 的 10 秒清理预算。
GATEWAY_HOST 127.0.0.1 旧 gateway 兼容配置中写入 profile 的默认 gateway host。
HERMES_WEB_UI_PREVIEW_REPO package repository Version Preview 使用的 GitHub 仓库。
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT 平台默认值 Version Preview broker transport。设为 tcp 可让预览环境在 macOS/Linux 上也使用 loopback TCP；未设置时会跟随 HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp。
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT 隔离的预览 endpoint 直接覆盖 Version Preview 的 broker endpoint。
HERMES_WEB_UI_BACKEND_PORT 8648 Vite dev proxy 使用的后端端口。
HERMES_WEB_UI_FRONTEND_PORT 8649 前端 Vite dev server 端口。

CLI 命令

原有 hermes-web-ui 命令仍可作为下列 ekko-studio-web 命令的别名使用。

命令 说明
ekko-studio-web start [port] 后台启动；支持位置端口或 --port <port>
ekko-studio-web client [port] 为远程客户端启动，关闭 Gateway 自动启动并允许跨域
ekko-studio-web restart [port] 重启；默认会关闭 Bridge Broker
ekko-studio-web stop 停止后台进程
ekko-studio-web status 查看运行状态
ekko-studio-web clear-login-locks [--restart] 清理持久登录锁，可选择重启
ekko-studio-web reset-default-login 创建或重置默认管理员登录
ekko-studio-web update / upgrade 更新到最新版本并重启
ekko-studio-web version / -v 显示版本号
ekko-studio-web -h 显示帮助信息
hermes-web-ui-mcp [api|browser|devices|use|plan] 运行一个受管 Studio MCP 工具集（等同于 ekko-studio-mcp）

如不希望自动打开浏览器，可在 start 或 client 后添加 --no-open。

restart、update 和 upgrade 默认会停止 Agent Bridge broker，避免重启或更新后的服务复用旧 Python bridge 进程。只有明确希望保留 broker 和正在运行的 bridge session 时，才在重启前设置 HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0。

update / upgrade 会先尝试执行 npm cache clean --force，再根据当前安装的包名升级 ekko-studio@latest 或 hermes-web-ui@latest，并重启对应包。Web UI 的版本检查也使用相同的包名。缓存清理失败时会提示警告，但不会中止升级安装。

自动配置

启动时 BFF 服务器会自动：

  • 初始化 Studio 数据目录、本地数据库和内置技能
  • Hermes Runtime 可用时启动 agent bridge；Gateway 自动启动遵循 Hermes 设置中的开关
  • 启动成功后自动打开浏览器；设置 --no-open 时跳过

开发

git clone https://github.com/EKKOLearnAI/ekko-studio.git
cd ekko-studio
npm install
npm run dev
npm run harness:check
npm run test
npm run build   # 构建输出到 dist/

贡献命令见 DEVELOPMENT.md，完整的 Package 与状态模型见 ARCHITECTURE.md。

架构

浏览器 / Desktop / App
          │ HTTP + Socket.IO
          ▼
Koa Bootstrap（仅负责组装）
          │
          ├─ Studio 平台 ── 单聊、群聊、Global Agent、工作流、
          │                 会话、文件、语音、设备、Webhook
          ├─ Hermes Family ─ Profile、模型、技能、记忆、任务、
          │                  Kanban、渠道、终端、Hermes Bridge
          ├─ Ekko Family ─── Ekko Runtime 与 Agent 自有服务
          └─ Coding Family ─ Coding Agent 适配器、隔离配置、原生 CLI 执行

服务端按业务归属组织在 packages/server/src/modules/{studio,hermes,ekko,coding-agents}。Route 保持轻量， Controller 处理 HTTP 关注点，Service 负责可复用业务行为，只有 packages/server/src/bootstrap 可以组装具体模块和 Adapter。跨 Agent 的能力归 Studio；不能因为某项公共功能当前使用 Hermes，就把它放进 Hermes 模块。

Studio 状态与 Hermes Agent 状态彼此独立。Studio 默认使用 ~/.hermes-web-ui，Hermes Profile 数据仍保存在 Hermes Home 下。完整目录归属、 依赖规则和 API 迁移约束见 docs/harness/server-module-boundaries.md。

技术栈

前端： Vue 3 + TypeScript + Vite + Naive UI + Pinia + Vue Router + vue-i18n + SCSS + markdown-it + highlight.js

后端： Koa 2 + Socket.IO + SQLite + node-pty

许可证

BSL-1.1

该许可证覆盖 Ekko Studio、hermes-web-ui npm 包和 CLI、桌面应用、 固件、发布产物、文档以及本仓库内的关联文件。

MCP 主入口为 bin/ekko-studio-mcp.mjs，工具名统一使用 ekko_studio_* 前缀。旧的 hermes-studio-mcp / hermes-web-ui-mcp 命令及 hermes_studio_* 调用继续兼容。重启 MCP 客户端后可发现新工具名；Studio 会将托管服务配置迁移为 ekko-studio-api、ekko-studio-browser、ekko-studio-devices、ekko-studio-use 和 ekko-studio-interaction。