快速搞懂 Maka Agent 的 Runtime Event LogLog is the Runtime 事件日志架构全解析指南【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/makaMakaApache 孵化项目是一个本地优先的 AI Agent 工作台它最核心的架构主张叫Log is the Runtime模型消息、工具调用Tool Call、工具结果、权限决策和终止事件全部以追加方式写入一份Runtime Event Log运行时事件日志。Session、界面、模型上下文、崩溃恢复都只是这份日志派生出来的投影。本文面向新手不带代码地讲清楚这套事件日志架构的设计动机、数据结构和关键不变量。为什么 Agent 不能只靠聊天记录想象你对 Maka 说找出这个项目里失败的测试修复后重跑一遍。它真实经历的过程远比发问 → 回答复杂模型先读项目、看测试输出模型调用文件、搜索、终端等工具某些工具需要用户授权运行暂停等待工具可能持续输出、失败、超时或被取消工具结果回到模型模型决定下一步如此循环多次最后系统必须明确判定这次运行是完成、失败还是被用户中止。这期间还会遇到界面要实时显示流式文本、应用崩溃重启后不能永远卡在运行中、用户点停止后迟到的模型事件不能把状态改回完成……如果只保存一份格式化好的聊天文本上面这些问题一个都答不了。所以 Maka 的答案是Runtime Event Log 才是语义事实源系统在某一时刻的状态只是这段有序日志经投影后的结果。用官方架构文档里的公式表达见 docs/architecture/runtime-core-architecture-draft.zh-CN.mdState(t) Project(RuntimeEvents[0..t], policy, runtime configuration)同一段日志不同消费者会投影出不同状态消费者从日志中得到的状态Model History 投影下一次模型调用要看到的 messagesUI / Session 投影界面展示的对话、工具活动与 Turn 状态Terminal Fact 分类器一次 Run 的最终结果成功/失败/中止恢复逻辑进程退出前哪些事实已经持久化Context Budget / 压缩更小但保留关键语义的工作上下文注意上下文裁剪和 LLM 压缩只改变下一次推理看到什么从不改写历史日志——证据不会被当垃圾删掉。一条 Runtime Event 里存了什么RuntimeEvent不是role text这么简单它把一条事实拆成几组正交信息定义见 packages/core/src/runtime-event.ts维度关键字段回答的问题身份sessionId/runId/turnId/invocationId这条事实属于哪段会话、哪次执行尝试顺序id/ts与账本顺序它在因果历史中的位置内容text / thinking / function_call / function_response / errorAI 交互本身的语义内容动作权限请求与决策、token 用量、结束调用等它要求 Runtime 做什么状态改变关联toolCallId / stepId 等引用如何把跨系统的同一件事重新配对生命周期partial/status它是可替换的流式片段还是持久事实或终止事实几个对新手很关键的细节工具调用与结果通过稳定 ID 配对回放时能重新拼出执行顺序权限不是弹窗文字而是一等公民的 runtime action——重放和恢复时能知道运行为什么停住、控制权怎么回来流式片段partial不会污染账本存储层为流式文本维护有界快照最终事件到达后覆盖避免 10000 个增量变成 10000 条长期记录。事件日志由谁生产一条主链走一遍所有宿主执行路径共用同一条主链ARCHITECTURE.zh-CN.md 明确 Event Log 是 canonical source组件职责一句话版SessionManager产品入口门面桌面端/CLI/Bot 都经它进入 RuntimeRuntimeKernel把请求组织成一次可运行的 Run路由停止与权限响应AgentRun一次执行的耐久封套身份、生命周期、终态提交RuntimeRunner规定 Invocation 调用协议必须有且只有一个终止事实AiSdkFlow把 Backend 流式事件翻译成 canonical RuntimeEventAiSdkBackendToolRuntime真正推进模型 → 工具 → 模型循环对应的实现文件可在 packages/runtime/src/ 下按序阅读runtime-kernel.ts、agent-run.ts、runtime-runner.ts、ai-sdk-flow.ts。模型每次发起工具调用时工具活动包括图中这类已连接的 MCP 工具产生的 call/result 都会作为强类型事实进入日志最关键的不变量先有终止事实再提交终止状态Agent 系统最容易出的故障是不同存储对是否结束给出不同答案运行头写成 completed 但日志里没有终止事件、用户已停止但迟到的 complete 又把会话改回活跃……Maka 保护的核心不变量是一个终止的 Run 必须有且只有一个有效 terminal RuntimeEvent终止的 Run header 必须能由这个终止事实支撑。也就是说runtime-core-architecture-draft.zh-CN.mdAgentRun提交终止 header之前先要求终止 RuntimeEvent 成功落盘没有终态的 Flow 会被合成为missing_terminal_event失败重复终态会被合并如果 header 声称结束却没有可信终止事实系统不盲目信任 header保守修复为失败。崩溃恢复因此不需要猜模型当时想干什么启动时扫描非终止 Run 与事件账本识别 stale 的模型流、工具尾巴、权限等待然后收敛到同一个可解释终态。这是状态修复不是凭空续跑——但正因为事实都 durable 了未来真正的中点恢复也有了地基。详见 docs/architecture/runtime-resume-architecture.zh-CN.md。日志落在磁盘的哪里文件存储实现中事件账本围绕会话目录组织sessions/sessionId/ ... session 投影 ... runs/runId/ run.json # 运行头开始时间、当前状态 events.jsonl # 运维事件索引工具开始、权限请求等 runtime-events.jsonl # ★ 权威语义事实账本append-only runtime-partials/ # 有界的流式快照其中runtime-events.jsonl才是Log is the Runtime的主角完成态 Run 的读取和下一轮模型回放都优先从它构造。文件账本的实现在 packages/storage/src/agent-run-store.ts。这套设计换来了什么✅ 桌面端、CLI、Bot、评测共用同一执行核心入口不绑具体模型或工具循环✅ 界面事件与可重放的模型事实明确分离UI 只是另一种投影✅ 用户停止、权限等待、工具副作用全部进入可诊断控制流✅ 崩溃后依据 durable facts 收敛状态不再永远运行中。代价同样诚实迁移期同时存在多套事件SessionEvent/RuntimeEvent/ 运维事件映射维护成本较高当前启动恢复是确定性终结与修复还不是任意位置的温启动。下一步按这张地图读源码packages/core/src/runtime-event.ts —— canonical 事件契约全文强类型校验packages/runtime/src/agent-run.ts —— 耐久生命周期与终态提交packages/runtime/src/runtime-runner.ts —— Invocation 协议与失败分类packages/storage/src/agent-run-store.ts —— 文件账本docs/architecture/runtime-core-architecture-draft.zh-CN.md —— 完整架构长文推荐通读docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md —— 多 Agent 如何复用同一份日志小结Maka 的 Runtime 核心不在某个类而在于一份可以保留并回放 Agent 交互状态空间的Runtime Event Log模型/工具循环 → canonical RuntimeEvents → 持久化语义日志 → 模型历史 / UI / Run 状态 / 崩溃恢复 四类投影只要这份有序事实还在系统就能重建当时的交互状态、生成新视图并让下一轮对话从可信历史继续——这就是 Log is the Runtime 的完整含义。【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考