本文只讲核心设计：有哪些进程、谁拥有执行权、一次任务怎样跑、多 Agent 怎样复用同一条链路。依据 Apache Maka main 的 c299cc17a7f006f69dc7b27f89c00c9962afcb77 提交（2026-09-24）；具体命令和产品界面可能变化，文末附官方资料。

1. 先看一张图：Maka 的中心是 Runtime Host#

Maka 是一个本地优先的 Agent 工作台。你可以在图形界面（GUI）、终端交互界面（TUI）或一次性命令（CLI）里交任务；Agent 会调用模型和工具，并保存过程。它的核心设计是：这些入口负责和人交互，真正执行任务的是 Runtime Host。

桌面 GUI ──┐
终端 TUI ──┼──请求──→ Runtime Host ──调用──→ 模型
单次 CLI ──┘                │            └──执行──→ 工具
                           │
                           └──写入──→ 本地运行记录
                                         │
                                  对话画面 / 下轮模型上下文 / 重启恢复

可以把 Host 理解为某一份工作状态的执行负责人：入口把任务交给它，它决定能否开始，安排实际执行，并保存已经发生的事。说它是“权威”，意思是发生争议时要以它保存的状态为准。GUI、TUI、CLI 可以关闭或重新连接；它们不各自维护一套 Agent 执行循环。

这里的“一个 Host”有范围：同一个 State Root（保存会话与运行状态的目录）同时由一个 Host 持有写入和执行权。不同 State Root 可以各有自己的 Host，并非整台机器只有一个 Maka 进程。

2. 它在机器上怎么运行#

先分清程序入口和执行进程，后面的架构才不会看反。

你看到的形态实际运行体主要工作
GUIElectron（桌面应用框架）进程。窗口负责显示，桌面主进程负责连接 Host 和使用本机能力提交任务、展示会话、处理桌面交互
TUI终端里的 Node.js 进程在终端收消息、显示输出、连接 Host
CLI 的 maka run一次性 Node.js 命令进程提交一轮任务，等结果并输出
Runtime Host独立的 Node.js 进程持有 State Root、运行 Agent、管理会话和执行

本地使用时，GUI 或终端入口会连接已有 Host；需要时会启动一个 Host 候选进程。Host 也可以安装成由操作系统管理的服务，供长期运行或远程客户端连接。packages/runtime 是 Host 进程里加载的 Agent 执行代码，不是另一个独立服务。

关闭窗口或终端连接，不等于自动取消已开始的任务；但任务能否继续还取决于 Host 的启动方式、生命周期以及它是否仍需要客户端提供的本机能力。不能简单理解成“窗口关了，任务一定在后台跑”。远程接入也是同一设计：客户端换成网络连接，模型和工具仍由远端 Host 所在的环境执行。

3. Host 到底管理什么#

Host 不只是转发消息的网关。它是同一 State Root 的执行权威，主要管理五件事：

Host 的职责用一个例子理解
守住状态所有权两个窗口同时打开同一份数据，也不能各自启动一套执行器去写它；Host 持有唯一写入权
接纳和安排工作判断某个会话能否开始新任务、任务属于哪一轮、何时停止或继续；同一会话不会并发跑两个顶层任务
组织 Agent 执行装配模型连接、工具、权限和运行环境，然后让内部 Runtime 开始模型与工具循环
留下并提供事实保存消息、工具调用、结果和终态；给客户端提供可重读的会话画面，重启后也以这些事实判断状态
协调客户端能力某些动作只能在客户端机器上做，例如桌面侧能力；Host 可以请求客户端执行，但会话和任务仍归 Host 管

这里有一条重要分工：Host 决定“谁有权执行这件事”；Runtime 负责“这一轮 Agent 具体怎样执行”；Storage 负责“哪些结果已经可靠写下”。 Host 把后两者装在自己的进程里使用，所以“Host 执行任务”和“Agent loop 在 Runtime 里”并不矛盾。

4. GUI、TUI、CLI 如何汇合到同一条执行链#

三个入口的界面和交互方式不同，但都通过 Host 的公开连接与请求协议进入。同机通常用本地进程间通信；远程客户端走经过认证的连接。协议让客户端提交任务、查询状态、订阅进展，它们不会直接创建自己的 Agent loop。

入口用户输入先到哪里怎样交给 Host
GUI桌面窗口通过受限桥接交给桌面主进程主进程向 Host 提交一条会话消息；Host 判断它开启新一轮、加入当前轮，还是等待后续处理
TUI终端 UI 进程同样提交会话消息；终端组件负责显示，不负责执行模型
maka run一次性命令进程直接请求开始一轮，随后观察结果并打印

统一的是执行权威和后半段链路，不是所有入口都发送同一种请求。 GUI/TUI 的“提交消息”要处理运行中追发、排队等交互；maka run 面向一次性任务，使用“开始一轮”的请求。Host 根据各自规则接纳后，都会进入同一套会话执行、Agent loop、事件记录和结果观察机制。

GUI/TUI：提交消息 ────────────┐
                              ├→ Host 准入一轮工作 → Runtime 执行 → 保存事实 → 返回画面/结果
maka run：请求开始一轮 ───────┘

这也是为什么 GUI、TUI、CLI 可以看到同一份会话状态：权威状态在 Host 管理的 State Root 中，各入口读取的是从该状态整理出的视图。前提是它们连接同一份数据的 Host；开发版与发布版的数据目录并不会自动同步。

5. 核心 Agent loop 在哪里，具体怎么转#

Agent loop（执行循环）就是反复做这件事：准备上下文 → 问模型 → 如果模型要调用工具，就执行工具并把结果交回模型 → 直到得到最终回答或停止。这个循环在 Runtime Host 进程内的 packages/runtime 执行，不在 GUI 渲染进程、TUI 组件或模型服务商那里。

以“总结当前仓库”为例，一轮工作大致经过六步：

  1. Host 准入：确认会话、这轮任务和执行身份，并确认它现在可以开始。这里的“已接受”还不代表任务完成。
  2. Runtime 准备输入：从已保存的会话事实中选出本轮要给模型看的上下文，结合当前模型设置和可用工具。
  3. 模型给出下一步：可能直接输出文字，也可能要求读文件、搜索或运行命令。模型提出意图，不直接拥有文件和进程权限。
  4. Runtime 执行工具：先检查工具是否可用、是否需要授权，再在相应环境中执行。工具结果回来后，又进入下一次模型调用。
  5. 记录过程：模型消息、工具调用、工具结果和结束状态进入持久运行记录。正在流动的 UI 文本只是让人尽快看到进展。
  6. 结束并展示：Host 提供这轮任务的状态与会话视图；GUI/TUI 更新画面，maka run 输出结果后退出。
          ┌── 模型需要工具 ──→ 检查权限并执行 ──→ 工具结果 ──┐
准备上下文 → 问模型 ────────────────────────────────────────┴→ 再问模型
                 └── 模型给出最终回答 ──→ 保存终态 ──→ 返回用户

Maka 把模型消息、工具调用、工具结果等保存为运行时事件。这是回答“究竟发生过什么”的主要事实来源；UI 对话和下一轮模型输入是从事实整理出的不同视图。上下文压缩只改变下轮给模型看的内容，不代表删除原始历史。Host 意外退出后，也要根据已保存的事实判断能否安全继续，不能仅凭客户端曾显示过一段文字就认定任务完成。

6. Graph 多 Agent 是怎样接到这条链路上的#

普通模式是一个会话中的 Agent 连续完成工作。Graph 模式适合把工作拆给多个子 Agent，并决定它们的先后依赖。它加的是调度层，不是第二套模型与工具执行器。

比如用户说：“先分别实现两个部分，最后集成并审查。”Graph 的工作是：

主 Agent 接到目标
  → 提交一个工作安排：任务 A、任务 B、集成、审查
  → Graph 判断哪些任务已具备输入、可以启动
  → 为任务 A/B 建立各自的子会话
  → 每个子会话仍交给同一个 Host 的 Runtime 跑普通 Agent loop
  → 子会话的已保存结果成为后续任务可用的输入
  → 主 Agent 查看进度，决定继续安排还是结束

这里要分清两层：

层决定什么不做什么
Graph 调度层有哪些子任务、依赖关系、哪个子会话可以启动、何时通知主 Agent不自己调模型，不自己实现另一套工具循环
普通 Runtime 执行层每个子会话实际调用模型与工具，并记录执行结果不替 Graph 决定整体计划何时完成

一个子 Agent 不是“主 Agent 函数里临时开的一个循环”；它有自己的子会话，后续还可以继续在该会话里工作。Graph 只把已经提交的运行事实变成可传递的结果，避免把半截流式输出当成已完成工作。maka run --graph 和 TUI 的 Graph 命令都是进入这套调度能力的产品入口；子任务最终仍回到同一条 Host → Runtime → 运行记录的执行链。

7. 代码模块怎样对应这张图#

到这里再看目录名，才容易理解它们为何这样分。模块是职责边界，不代表每个目录都是一个进程。

区域一句话职责在主链上的位置
apps/desktopGUI：桌面窗口、系统能力、Host 连接用户入口
packages/cliTUI、单次 run、Host 管理等终端入口用户入口
packages/runtime-hostHost 进程、连接协议、任务准入、会话观察和执行协调唯一托管执行权威
packages/runtime模型与工具循环、上下文、一次任务的执行生命周期真正跑 Agent 的地方
packages/storageState Root、SQLite 和本地状态写入保存执行事实与控制状态
packages/core各层共同使用的事件、会话、权限等约定让模块说同一种话
packages/eval把 Maka 当被测对象，安排实验、验证、记录分数使用 Host 的外围能力

Graph 横跨 Host、Runtime 和 Storage：Host/Runtime 协调子会话的调度与执行，Storage 保存调度决定和运行事实。仓库没有另一个叫“Graph Runtime”的独立执行中心。MCP、Computer Use 和共享 UI 等模块是在工具或界面侧补能力，也不改变这条执行权归属。

8. 读完应该能复述什么#

如果只记一条完整主线，可以记成：

人从某个界面交任务 → Host 决定谁能跑 → Runtime 反复调模型和工具
                    → 过程写成事实 → 界面展示；Graph 只负责安排更多这样的任务

官方资料#