Ekko Agent 深度解析Ekko Studio 本地优先的多智能体 TypeScript 运行时【免费下载链接】hermes-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/hermes-studioEkko Agentpackages/ekko-agent是 Ekko Studio 内嵌的独立 TypeScript Agent 运行时独立拥有模型循环、Provider 适配、工具、记忆、Skills、委派、审批与结构化请求日志。本文以 packages/ekko-agent/README.md 为骨架结合 源码目录、配置文件 与 公共 API 文档 展开帮助读者掌握如何以 Profile 为单位启动多 Agent 容器、如何接入多风格模型与 OAuth 授权、如何配置工具审批与code_exec沙箱、如何管理记忆/会话/Skills以及如何理解其配置升级与故障恢复机制。读完即可独立完成一个基于 Ekko Agent 的本地优先 Agent 宿主集成。Ekko Agent 的定位与总体架构Ekko Agent 是一个可嵌入的 TypeScript 运行时核心职责是模型循环model loop、Provider 适配器、工具tools、记忆memory、Skills、委派delegation、审批approvals以及结构化请求日志。它不依赖 Ekko Studio 前端可被任何宿主进程单独调用。推荐的入口是面向 Profile 的容器式 APInew EkkoAgent()会为每个配置的 Profile 创建一个EkkoProfileAgent于是各模块以ekko.default.skill、ekko.default.memory、ekko.agent.get(work).tool这类命名空间方式访问。完整的字段、方法、参数与配置参考见 packages/ekko-agent/docs/API.md。从源码看packages/ekko-agent/src/setup.tsEkkoAgentSetup是进程级资源容器聚合了directories、diagnostics、recovery、config、database、memoryStore、memory、conversations、authorizations、model、tool、skill、runtime、agent等模块EkkoAgent在它之上再暴露配置读写、Provider/授权管理的便捷方法setup.ts而setupEkkoAgent(options)只是new EkkoAgent(options)的兼容别名。Profile 容器模型defaultProfile始终创建即使profiles缺省或未列出它启动时会自动发现.ekko/skills、.ekko/logs、.ekko/workspace下已存在的一级 Profile 目录显式profiles会与自动发现的名称合并setup.ts因此已有 Profile 无需调用方再次传入合并后缺失的受管目录会在 Profile Agent 校验前创建每个 Profile 拥有独立绑定的skill、tool、memory、conversation、runtime、directory、log模块配置、SQLite 连接、模型 Provider 与 OAuth 凭证是安装级共享资源。以ekko.agent.get(work)访问命名 Profile 在 TypeScript 中具有较好的可读性default是固定声明属性因此ekko.default.skill有完整类型推断见 API.md。磁盘目录布局Setup 阶段由EkkoDirectoryManager负责创建base/.ekko/config/config.json、skills/logs/workspace 目录并打开/迁移 SQLite 数据库。开发模式完整布局位于包内.ekko目录含.ekko/ekko.db生产模式数据库位于base/.ekko/ekko.db每个 ProfileSkills 位于base/.ekko/skills/profile日志位于base/.ekko/logs/profile默认 per-session 工作区为base/.ekko/workspace/profile/session-id显式传入的workspaceRoot或cwd优先于默认工作区服务器宿主把 Web UI 主目录作为 base 目录传入。注意Ekko 从不导入或同步 Hermes Skills。首次从旧版导入行为升级启动时服务器只把 Hermes 根目录作为只读清单仅删除 Ekko 自有 Profile 目录中匹配的非内建副本Hermes 源目录永不修改迁移标记防止后续启动重复清理或误删之后安装的 Skills。模型接入层一套内部形状多种外部 APIEkko Agent 的第一个实现层是模型 Provider 请求。内部只使用一种请求形状由 Provider 适配器翻译成外部 API 格式packages/ekko-agent/src/model 下的providers/目录分别实现各风格。因此切换厂商只改配置不改业务代码。支持的请求风格与默认端点风格默认端点openai-chathttps://api.openai.com/v1/chat/completionsopenai-responseshttps://api.openai.com/v1/responsesanthropic-messageshttps://api.anthropic.com/v1/messagesgemini-contentshttps://generativelanguage.googleapis.com/v1beta/models/{model}:generateContentprompt-completionhttps://api.openai.com/v1/completionscustom-runtimehttp://127.0.0.1:11434/v1/agent这些风格覆盖了 OpenAI Chat Completions、OpenAI 兼容 ProviderDeepSeek、Qwen、Moonshot、Ollama 等、OpenAI Responses、Anthropic Messages、Gemini Contents、prompt completion 与自定义运行时。可用baseUrl与endpointPath覆盖默认端点。配置层将requestStyle与公开apiMode绑定校验枚举见 packages/ekko-agent/src/config-store.tsmodelApiModeToRequestStyle()提供二者映射packages/ekko-agent/src/model/provider-presets.ts。一等公民 OAuth Provider 预设预设 ID请求风格后端nousOpenAI Chat CompletionsNous inference APIopenai-codexOpenAI ResponsesChatGPT Codex backendxai-oauthOpenAI ResponsesxAI APIqwen-oauthOpenAI Chat CompletionsQwen Portal APIclaude-oauthAnthropic MessagesAnthropic APIminimax-oauthAnthropic MessagesMiniMax Coding Plan每个预设都带显式apiMode安装时不依赖端点推断配置校验要求 Provider 适配层requestStyle与apiMode严格一致config-store.ts。除 OAuth 预设外内置目录还包含openai-api、anthropic、gemini、deepseek、xai、alibaba、minimax等 API-Key Providerprovider-presets.ts。授权模型OAuth 持久化与刷新调用方仍负责交互式登录流程之后通过setModelAuthorization保存结果Ekko 在请求前持久化并刷新这些凭证可通过传入 Provider 感知的 refresher或配置标准 OAuth token 端点tokenUrl、refreshToken、可选 client 字段走导出的标准 refresh-token 实现到期判断受model.authorizationRefreshLeewayMs默认 5 分钟见 config.ts控制刷新按 Provider 去重、轮换凭证会持久化、刷新失败绝不回退到即将过期的旧 tokenMiniMax Coding Plan 请求仅使用 Bearer 认证不发送x-api-key直接传apiKey仍可作为单进程覆盖源码路径createModelClient在存在 OAuth 授权时返回AuthorizedModelClient见 setup.ts。统一消息形状所有适配器接收同一内部消息形状type AgentMessage { role: system | user | assistant | tool content: string name?: string toolCallId?: string toolCalls?: AgentToolCall[] }边界处用normalizeAgentMessage()/normalizeAgentMessages()归一化支持字符串、tool_calls蛇形字段等多种输入形式实现见 packages/ekko-agent/src/model/messages.ts模型响应可用modelResponseToAgentMessage()转回单条 assistant 消息流式事件可用collectModelEvents()收集到同一形状。工具系统内建工具、沙箱与审批内建工具清单工具作用clarify向用户提一个阻塞性问题可带选项仅当宿主提供交互式澄清处理器时暴露read_file读取本地文本文件相对路径基于当前工作目录支持绝对路径与workspaceRoot之外路径view_image加载本地 PNG/JPEG/WebP/GIF 作为多模态输入强制运行时工作区边界与大小限制write_file写文本内容默认创建父目录terminal_exec以参数数组执行命令shell: falsecode_exec运行一次性 Node.js 或 Python 脚本脚本可经生成的ekko_tools.mjs/ekko_tools.pyRPC 桥调用受允许的read_file、write_file、terminal_execskill_list列出或搜索skillDirectory下的 Skills返回名称、简述与内建身份路由关键字仅宿主可见skill_view加载某 Skill 的SKILL.md或允许的支持文件并返回 Skill 的绝对baseDirectoryskill_manage创建、补丁、编辑、归档或管理支持文件新建/更新的 Skill 必须带非空紧凑英文 ASCII frontmattermetadata.keywords内建 Skill 不可删除ekko_diagnostics报告活动组件故障与精确恢复路径ekko_database_schema暴露迁移拥有的 SQLite 表与字段ekko_repair_skills重新同步包自有 Skills 并运行自检ekko_repair_database重试编译迁移或执行显式确认的 quarantine-and-rebuild然后自检ekko_self_check校验 Skills/数据库状态仅清除匹配的当前故障修订注册逻辑见 packages/ekko-agent/src/tools/registry.ts默认注册表包含UpdatePlanTool、文件/图片/终端/浏览器/委派/恢复/Skills 工具code_exec在启用时注册clarify与 MCP 以 provider 形式注册registerProvider由refreshTools()动态注入。工作区边界语义workspaceRoot用于设置默认工作目录并隔离write_file与view_image它不是读/进程沙箱——read_file与terminal_exec允许使用工作区之外的显式路径。code_exec 沙箱边界code_exec接受language: node或language: python并受一组硬限制约束默认值来自 config.ts校验与执行见 packages/ekko-agent/src/tools/code-exec.ts最多运行配置的工具执行超时tools.executionTimeoutMs默认 120000ms最多 50 次嵌套工具调用DEFAULT_CODE_EXEC_MAX_TOOL_CALLS 50stdout 上限 50KBDEFAULT_CODE_EXEC_MAX_OUTPUT_BYTES 50_000、stderr 上限 10KB、源码上限 200KB清洗子进程环境拒绝递归或非白名单工具调用白名单CODE_EXEC_ALLOWED_TOOLS仅read_file、write_file、terminal_exec见 code-exec.ts中间工具结果留在子脚本内只有精简后的 stdout 返回给模型。用法示例import { createDefaultToolRegistry } from ekko-agent const tools createDefaultToolRegistry() await tools.execute(write_file, { path: notes/todo.txt, content: ship tools, }, { workspaceRoot: process.cwd(), }) const result await tools.execute(terminal_exec, { command: node, args: [-v], }, { workspaceRoot: process.cwd(), }) const batchResult await tools.execute(code_exec, { language: node, code: import { read_file } from ./ekko_tools.mjs const result await read_file({ path: README.md }) console.log(result.content.split(\n).slice(0, 5).join(\n)) , }, { workspaceRoot: process.cwd(), })工具审批模型危险工具在执行前必须先授权registry.ts 中授权被拒时 fail closedcode_exec总是要求授权因为普通 Node.js/Python 源码可以访问宿主terminal_exec对破坏性、特权、远程 shell、包发布、服务控制等命令要求授权决策枚举once、session、always、denysession决策保存在进程内存中仅对匹配的聊天会话生效always决策持久化到全局配置tools.approvals.permanentAllow类型见 config.ts拒绝在任何工具启动前失败关闭宿主在每次运行的 tool context 中提供requestToolApproval把决策桥接到自己的 UI。Runtime串并行执行、澄清、压缩与恢复AgentRuntime把消息、模型请求、工具、Skills、系统提示与事件串联在一起实现见 packages/ekko-agent/src/runtime/runtime.ts。步数与并发默认maxSteps为 90DEFAULT_AGENT_MAX_STEPSconfig.ts与 Hermes 常规 Agent turn 预算一致每步还有maxModelRetries默认 3与toolFailureRecoveryThreshold默认 3工具连续失败后触发模型恢复而非终止运行工具默认串行执行除非某AgentTool.concurrency显式设为parallel连续并行安全调用最多 8 个并发MAX_CONCURRENT_TOOL_CALLS 8见 runtime.ts串行工具保持有序屏障结果按原始工具调用顺序回放给模型内建文件/图片/Skill/记忆读取类工具选择并行MCP 工具按服务器通过supports_parallel_tool_calls: true选择并行。澄清clarify默认注册表只为前台运行暴露clarify且要求AgentToolContext提供requestUserClarification委派子 Agent 与非交互宿主拿不到该工具。可用时运行时提示要求阻塞性澄清问题必须走该工具而不是作为普通 assistant 响应返回。上下文压缩与内存证据当 Ekko 运行在拥有会话持久化的宿主内时压缩由宿主负责estimateContext()暴露 Provider 可见的 system、tool、message 与 provider-context 估算供外部阈值决策使用而不必发起模型调用独立 Ekko 宿主可自行实现内部压缩生命周期全局compression配置为未来集成提供宿主策略面enabled、threshold默认 0.5范围 0.05–0.95、targetRatio默认 0.2范围 0.01–0.8、protectLastN默认 20范围 0–500、protectFirstN默认 3范围 0–100Ekko Studio 当前仍从其主配置读取压缩策略不应用 Ekko 这一配置段。模型上下文与记忆证据是独立输入宿主若向模型输入附加派生摘要、检索上下文、路由指令等应用自有内容应只把受信任的对话证据经memoryInput.messages传入可选memoryInput.writePolicy让宿主选择直接写入或仅显式请求写入宿主还可附加不透明memoryInput.origin并声明recallScopes、writeScopes与defaultWriteScope。Ekko 只理解通用的profile、context、session三种 scope 形状标识符与命名空间属于宿主省略 scope 配置时保持向后兼容仅能访问 profile 作用域记忆。记忆写入与恢复前台 Agent 可直接搜索、查看、创建、更新、删除授权的记忆memory_write.operations在单个 SQLite 事务内原子应用多次创建、更新、过期与精确删除旧版单操作形状保持兼容仅删除请求可用memory_forget其多目标与宽删除同样原子两个工具都保持宿主受信任证据与作用域边界运行完成只记录受信任的对话证据不启动记忆模型、不创建隐藏的 Session summary可执行质量契约见 packages/ekko-agent/docs/MEMORY_HARNESS.md。故障降级与恢复Skills 与持久 SQLite 是围绕最小 Core 的可选能力内置 Skill 同步失败 → 记录进程本地故障、禁用该 Profile 的 Skill 发现/路由但保留模型对话与打包内建工具持久 SQLite 无法初始化/恢复 → 使用内存 SQLite 兜底聊天与存储 API 不因启动失败而挂起每次运行都会把当前恢复细节作为临时系统上下文注入该上下文永不写入记忆内置修复工具拥有源/目标路径与迁移修复后运行确定性自检仅在匹配修订通过时清除故障修复后的持久数据库会让当前运行留在临时存储上Ekko Studio 在所有活动运行结束后自动关闭该 Setup下次运行打开修复后的持久数据库独立宿主必须在相同的运行完成边界重建 Setup。运行示例import { EkkoAgent } from ekko-agent const ekko new EkkoAgent({ baseDirectory: /path/to/base, profiles: [work], config: { runtime: { maxSteps: 60 }, compression: { threshold: 0.6, protectLastN: 16 }, }, }) ekko.config.setModelProvider(deepseek, { type: openai-compatible, requestStyle: openai-chat, baseUrl: https://api.deepseek.com/v1, defaultModel: deepseek-chat, apiKey: sk-..., }) ekko.config.setDefaultModel(deepseek) const runtime ekko.agent.get(work).runtime.create() try { const result await runtime.run({ messages: [Read README.md and summarize it.], toolContext: { workspaceRoot: process.cwd(), }, onEvent(event) { console.log(event.type) }, }) } finally { ekko.close() }开关说明toolsEnabled: false省略全部工具来源内建、MCP、记忆、Skill 工具skillsEnabled: false省略构造器与 per-run Skills。两个开关相互独立默认均为true。配置系统config.json 与 EkkoConfigStorenew EkkoAgent(options)是全能公共门面与多 Profile 容器。向两种构造方式传config: EkkoConfigPatch会在 Profile Agent 与运行时服务创建前应用并持久化安装级值所有顶层配置段都支持嵌套局部值显式 per-run 运行时选项仍优先于这些默认值。配置文件位置与安全全局 JSON 文件位于base/.ekko/config/config.json以用户独占0600权限创建写入采用「临时文件 rename」原子替换writeEkkoConfigconfig-store.ts每次变更都会重载当前文件避免调用方持有过期内存快照API-Key 凭证在 Provider 对象apiKey下OAuth 状态在model.authorizations下仍可向setup.createModelClient()/setup.createRuntime()传apiKey覆盖持久化值仅限单进程。配置结构顶层段与默认值段关键字段默认值runtimemaxSteps90、maxModelRetries3、toolFailureRecoveryThreshold3modeldefaultProvider、defaultModel、requestTimeoutMs300000、reasoningEffortmedium、reasoningSummaryauto、authorizationRefreshLeewayMs300000、providerCatalog、disabledProviderPresets、providers、authorizationstoolsenabledtrue、executionTimeoutMs120000、approvals.{enabled,timeoutMs,permanentAllow}、codeExec.{enabled,languages,timeoutMs,maxToolCalls(50),maxOutputBytes(50000),maxStderrBytes(10000),maxSourceBytes(200000)}mcpenabledtrue、profiles.profile.serversdelegationbackgroundEnabledtrue、subtaskMaxSteps30compressionenabledtrue、threshold0.5、targetRatio0.2、protectLastN20、protectFirstN3memoryenabledtrue、recentMessageLimit20、automaticRecallTokenBudget4000、searchResultLimit50skillsenabledtrue、reviewEveryToolCalls10、profiles.profile.{disabled,externalDirectories}loggingmaxBytes10 MiBpromptinstructions[]完整默认值定义见 packages/ekko-agent/src/config.tsschema 版本为 9EKKO_CONFIG_SCHEMA_VERSION。配置升级与容错配置升级逐字段合并新默认值已有用户值、数组与向前兼容的未知字段永不被整体模块替换mergeMissingDefaults只填充缺失叶子config-store.ts启动校验会原地升级旧 schema配置损坏或由更新 schema 写入时先把原文件备份为config.invalid-timestamp-uuid.json再恢复当前默认值同一进程继续启动无需重启ensureStartupConfigsetup.ts文件系统读取失败保持致命绝不触发替换重建嵌套update补丁在字段级合并改runtime.maxSteps不会覆盖其他 runtime 设置mergeConfigPatchconfig-store.ts。配置存储 API 速览setup.config是EkkoConfigStoreconfig-store.ts暴露read、update、replace、reset、MCP 服务器 CRUD、Provider 预设 CRUD、已配置 Provider CRUD、授权 CRUD、installModelProviderPreset与setDefaultModel。setup.modelProviderConfig()解析当前活跃 Providersetup.createModelClient()不启动运行时直接创建客户端。setup.config.update({ runtime: { maxSteps: 60 }, model: { reasoningEffort: high, maxTokens: 8_192 }, tools: { codeExec: { enabled: false } }, }) const providers setup.config.listModelProviders() const client setup.createModelClient({ provider: providers[0].id })安装并管理内建 Providerconst agent new EkkoAgent({ baseDirectory: /path/to/base }) agent.installModelProviderPreset(openai-codex, { defaultModel: gpt-5.6-terra, }) agent.updateModelProvider(openai-codex, { defaultModel: gpt-5.6-sol, }) agent.deleteModelProvider(openai-codex)MCP 服务器配置MCP 服务器与配置文件同源位于mcp.profiles.profile.servers本地服务器command、args、env类型为stdio远程服务器type: streamable_http、url、可选字符串headers两种传输都走官方 MCP client依赖modelcontextprotocol/client见 package.json配置校验要求 stdio 必须带command、Streamable HTTP 必须带合法 http(s) URLconfig-store.ts新创建的 runtime 自动加载所选 Profile 的已启用服务器。会话与消息 API独立数据库拥有 Studio 兼容的sessions与messages表schema 见 packages/ekko-agent/src/conversations/schema.ts。setup.conversations暴露Session 操作createSession、getSession、listSessions、updateSession、renameSession、setSessionArchived、endSession、reopenSession、deleteSession、getSessionDetailMessage 操作addMessage、addMessages、getMessage、listMessages、updateMessage、deleteMessage、clearMessagesrecordSessionUsage独立于消息编辑累计模型用量。const session setup.conversations.createSession({ profile: default, provider: deepseek, model: deepseek-chat, title: Repository review, }) setup.conversations.addMessage({ sessionId: session.id, role: user, content: Review this repository., }) setup.conversations.renameSession(session.id, Ekko repository review) const history setup.conversations.listMessages(session.id)记忆 APIsetup.memory暴露独立记忆 API服务实现见 packages/ekko-agent/src/memory/service.ts 与 store.ts记忆节点操作list、get、search、create、update、expire、delete、applyBatch、forget会话派生记忆数据listMessages、listAuditEvents底层 SQLite 实现仍以setup.memoryStore可用前台运行通过memory_write/memory_forget同步写入/遗忘持久记忆多变更时优先memory_write.operations整批提交后响应为终态donetrue没有记忆审批队列、审查 worker 或后台 Session-summary 流程数据库迁移是事务性的并重试 SQLite 锁冲突非锁迁移失败会保留原库为时间戳备份、重建 schema、恢复兼容的记忆/会话行并重建记忆搜索索引——绝不静默禁用记忆或切到未跟踪临时库。const created await setup.memory.create({ kind: general_preference, itemKey: interface_theme, reason: User selected a persistent preference., explicitUserIntent: true, identity: { sessionId: session.id, profileId: default }, node: { valueJson: dark, title: Interface theme, content: The user prefers a dark interface., }, }) const memories await setup.memory.list({ profileId: default, limit: 20 }) const updated await setup.memory.update(created.nodeId!, { reason: User changed the preference., expectedRevision: created.node!.revision, identity: { sessionId: session.id, profileId: default }, node: { valueJson: light }, }) const batch await setup.memory.applyBatch({ identity: { sessionId: session.id, profileId: default }, explicitUserIntent: true, operations: [ { operation: create, kind: language_preference, reason: User selected Chinese., node: { valueJson: zh-CN, title: Language, content: The user prefers Chinese. }, }, { operation: expire, targetId: updated.nodeId!, expectedRevision: updated.node!.revision, reason: The old preference is no longer current., node: {}, }, ], }) // Soft delete is the default; mode: hard deletes immediately as well. await setup.memory.delete(updated.nodeId!, { reason: User asked Ekko to forget it., expectedRevision: updated.node!.revision, identity: { sessionId: session.id, profileId: default }, })Skill 体系内建 Skills、外部目录与演进内建 Skills 与自动安装Ekko 包自有的内建 Skills 是唯一自动安装的 Skills每个 Profile 都会收到1password、apple-notes、apple-reminders、document-to-action-items、docx、gh-issues、github、grok-image-to-video、hermes-studio-installation、image-gen、node-inspect-debugger、obsidian、ocr-and-documents、pdf、powerpoint、python-debugpy、skill-creator、spike、tmux、video-frames、weather、xlsx实际打包目录见 packages/ekko-agent/skills。启动只安装缺失内建项且只更新「未被修改的 Ekko 安装副本」用户编辑过或已存在的同名 Skill 永不被覆盖image-gen与grok-image-to-video使用 Ekko Studio 的本地媒体端点需要匹配的已配置 Studio Profile文档类 Skills 捆绑 Python 辅助脚本、参考资料、测试与许可证声明可选 Python、LibreOffice、Poppler、OCR 与模型依赖在使用时检查而非 Ekko 启动时安装文档类 Skills 的 Python 实现示例见 packages/ekko-agent/skills/pdf/scripts、packages/ekko-agent/skills/docx/scripts 与 packages/ekko-agent/skills/xlsx/scripts。外部只读 Skill 根每个 Profile 可经skills.profiles.profile.externalDirectories引用只读 Skill 根目录这些目录原地保留、永不复制进 Ekko 存储同 Profile 的disabled列出从提示注入与自动路由中隐藏的 Skill 名本地 Skills 优先于同名外部 Skills。示例{ skills: { enabled: true, reviewEveryToolCalls: 0, profiles: { work: { externalDirectories: [~/shared-skills, $TEAM_SKILLS], disabled: [weather] } } } }路由与演进首条模型响应前运行时只注入当前 Profile 的文件型 Skill 名主模型把任意语言的请求映射到其中一个名称并直接调用skill_view宿主还会把最新有效用户消息与 Skill 名及紧凑英文metadata.keywords比较精确匹配会确定性预加载与普通 Skill 加载产生相同的可见工具事件描述仍保留给skill_list做兜底发现关键字仅宿主可见skill_manage变更前要求同次运行先经skill_view加载文件在查看后被修改则拒绝变更覆盖会创建可恢复副本.ekko/skills/profile/.ekko-backups确认删除把目录移到.ekko/skills/profile/.ekko-archive由 Profile 清单识别的同步内建 Skill 不可删除会话累计 10 次工具调用后运行时调度后台程序化审查使用专用保守提示只用skill_list、skill_view、skill_manage不阻塞前台响应可创建可复用的类级 Skill但只能更新标记为 Ekko 创建的 Skill不能删除skillReviewEveryToolCalls: 0可关闭默认 10。文件日志请求优先的结构化 JSONL每个 Profile 向单个文件写结构化 JSON Lines.ekko/logs/profile/ekko-agent.jsonl实现见 packages/ekko-agent/src/logging/file-logger.ts。文件上限 10 MiBlogging.maxBytes下一条事件将超限时丢弃现有内容并在同一文件继续——不产生轮转或 per-session 文件持久日志有意只记录请求每次模型客户端请求尝试在完成或失败后写一条终态model.request记录合并安全请求元数据、状态、耗时、用量与响应大小运行时事件、流式增量、工具事件、提示与响应体不写入日志体量跟随模型调用数而非庞大的运行时事件流端点与常见凭证形状会被脱敏、大字符串截断、base64 载荷省略EkkoFileLogReader.query()可按 session、run、turn、category、level、event、time 或 text 过滤当前文件无需获取写所有权Hermes Web UI 的 Logs 页把同一文件作为所选 Profile 的ekko-agent源展示。构建、测试与最小示例命令npm install npm run check npm test npm run build对应脚本见 packages/ekko-agent/package.jsoncheck为tsc --noEmittest在仓库根目录运行vitest run tests/ekko-agent对应测试见 tests/ekko-agentbuild先清理再以tsconfig.build.json编译到dist。运行时要求 Node.js23.0.0。最小模型客户端示例import { createModelClient } from ekko-agent const client createModelClient({ id: deepseek, type: openai-compatible, apiKey: process.env.DEEPSEEK_API_KEY, baseUrl: https://api.deepseek.com/v1, defaultModel: deepseek-chat, }) const response await client.create({ messages: [{ role: user, content: Say hello. }], })源码导航与延伸阅读公共导出面packages/ekko-agent/src/index.ts含各 Provider 客户端的to*Payload/normalize*Response转换函数容器与 Setuppackages/ekko-agent/src/setup.ts、packages/ekko-agent/src/agent/profile-agent.ts配置与校验packages/ekko-agent/src/config.ts、packages/ekko-agent/src/config-store.ts模型层packages/ekko-agent/src/modelproviders、authorization、authorized-client、manager运行时packages/ekko-agent/src/runtime/runtime.ts 与 events.ts工具packages/ekko-agent/src/tools/registry.ts含 approval、code-exec、terminal、files、images、mcp、skills记忆packages/ekko-agent/src/memoryservice、store、scope、toolsSkillspackages/ekko-agent/src/skills 与打包目录 packages/ekko-agent/skills公共 API 参考packages/ekko-agent/docs/API.md记忆质量契约packages/ekko-agent/docs/MEMORY_HARNESS.md对集成方而言核心心智模型是一次new EkkoAgent()建立安装级共享资源与全部 Profile 容器每个 Profile 的 runtime 通过createRuntime()派生携带各自的工具注册表、Skill 目录、日志与默认工作区模型层以统一消息形状对接多种外部 API配置与授权统一沉淀在 0600 权限的config.json中。这既是本地优先桌面端嵌入 Agent 能力的实现细节也是任何需要「多 Profile、多 Provider、可插拔工具与记忆」的自托管 Agent 宿主的可复用参考实现。【免费下载链接】hermes-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/hermes-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考