Maka Runtime v2 架构演进以规范化调用/事件脊柱为中心的运行时重构方案【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文基于归档提案 docs/archive/runtime-v2-architecture-evolution.md 展开并结合当前仓库packages/core与packages/runtime中的落地实现进行印证。该提案已于 2026-07-13 归档用于记录当前运行时的演进路线不作为现行架构权威现行架构请以仓库根目录 ARCHITECTURE.md 为准。Maka 的 Agent 运行时已经能完成本地编码代理的全部主链路Electron 桌面入口、会话 JSONL 存储、经 AI SDK 的模型流式输出、工具执行与权限弹窗、中止处理、Bot 与 OpenGateway 入口、工具产物与用量遥测以及内部AgentRun账本。但一次运行的事实被分散在StoredMessage、SessionEvent、AgentRunEvent、RunTraceEvent与遥测记录等多个平行结构中缺少一个稳定的重心。本文面向需要理解运行时为何需要再一次架构整理、哪些部分应当保持稳定、以及代码库如何在不做大爆炸式重写的前提下迁移到目标形态的开发者读完本文你将掌握 Maka 运行时的现状拆解、目标分层RuntimeRunner → InvocationContext → AgentFlow → AiSdkFlow → ToolRuntime、规范RuntimeEvent事实模型、各消费路径桌面、权限、模型历史、启动恢复、Bot/Gateway以及七阶段迁移计划并能在packages/core与packages/runtime中找到对应的落地证据。为什么运行时需要一个稳定的重心Maka 已经拥有一套可工作的本地编码 Agent 运行时其既有能力包括Electron 桌面入口点会话 JSONL 存储通过 AI SDK 的模型流式输出工具执行与权限提示中止abort处理Bot 与 OpenGateway 入口点工具产物artifacts与用量遥测内部AgentRun账本。现状架构比最初的单体路径更好但运行时仍然缺少一个稳定的中心。同一次运行目前被表示为若干相关但彼此分离的结构结构用途StoredMessage会话 JSONL 中的持久化消息SessionEvent面向渲染进程的事件流AgentRunEvent运行账本中的事件RunTraceEventbest-effort 诊断追踪遥测记录经济与运维投影这种分裂让系统难以演进也让一系列关键问题变得比应有的更困难哪些事实才是真正的运行时真相runtime truth哪些对象只是 UI 投影哪些事件应当被重放replay进下一次模型请求哪些事件仅用于诊断权限permission、工具tool、恢复recovery与遥测telemetry语义应当住在哪里Runtime v2 的答案是引入一条规范化的调用/事件脊柱RuntimeRunner - InvocationContext - AgentFlow - AiSdkFlow - AI SDK streamText - ToolRuntime - RuntimeEvent ledger - projections核心转变是今天 SessionManager StoredMessage/SessionEvent 靠近运行时中心。 目标 Invocation RuntimeEvent AgentFlow 成为运行时中心。 StoredMessage、渲染进程 SessionEvent、AgentRunStore、RunTrace、遥测 都变成由规范运行时事实派生的投影projections或账本ledgers。在仓库中这个方向已经以类型与纯辅助函数的形式落地在 packages/core/src/runtime-event.ts 中其文件头注释明确写道这是单一内部运行时事实模型不是UI 事件events.ts中的SessionEvent、不是trace 行RunTrace或遥测记录StoredMessageJSONL、渲染进程SessionEvent、AgentRunStore运维行、RunTrace与TelemetryRepo都应是从这些事件写出、或显式链接到这些事件的投影。文件头还注明了其架构依据正是 docs/architecture/runtime-core-architecture-draft.md。设计输入从 ADK 分层中吸取什么这份提案基于当前 Maka 实现以及 Google ADK Go 阅读材料中记录的运行时结构。值得借鉴的不是照搬类型名而是它的分层方式Runner - Agent - Flow - Model/Tool - Event - Session在该模型中Runner拥有调用外壳invocation shell与持久化边界Agent拥有生命周期与路由Flow拥有模型/工具循环Event是共享的运行时事实语言Session存储持久化历史与作用域状态工具、回调、插件、指令、工作流、入口点与遥测层围绕这条主轴附着而不会自身成为主轴。Maka 的产品约束不同因此演进需要适配长期保留 AI SDK 作为主流程实现保留 Electron 与既有用户可见的会话行为保留既有 JSONL 兼容性复用ToolRuntime、AgentRunStore与RunTrace避免一个旗日flag day即存储与 UI 投影一次性全部变更。当前运行时路径一次用户轮次的真实流向今天一次用户轮次大致按如下流程流动renderer / bot / gateway - desktop main / entrypoint code - ensureSessionCanSend(...) - SessionManager.sendMessage(sessionId, input) - new AgentRun(...) - AgentRun.execute() - append user StoredMessage - append turn_staterunning - lock connection snapshot - ensureActive() / build AiSdkBackend - register active run - AiSdkBackend.send() - PermissionEngine.beginTurn() - RunTrace - ModelAdapter.resolveModel() - build AI SDK tool map - materialize prior StoredMessage[] into AI SDK messages - AI SDK streamText({ tools, stopWhen: stepCountIs(maxSteps) }) - AI SDK owns model - tool - model stepping - tool.execute(...) calls ToolRuntime - pump fullStream into SessionEvent queue - append assistant StoredMessage - append token_usage StoredMessage - queue complete/error/abort - AgentRun updates SessionHeader / turn_state / AgentRunStore - cleanup active run这套拆分有一些不错的性质SessionManager.sendMessage()不再拥有整个热路径AgentRun提供持久化的运行生命周期记录ToolRuntime是工具权限、执行、产物与工具遥测的真正边界ModelAdapter隔离了 provider / AI SDK 的流式与错误归一化。从源码看上述调用链可以在仓库中逐点印证SessionManager的sendMessage位于 packages/runtime/src/session-manager.ts其注释明确写着它owns AgentRun orchestration, backend execution, and ledger recording即它至今仍是AgentRun编排、后端执行与账本记录的持有者——这正是文档所说需要被拆掉的重心AgentRun类实现于 packages/runtime/src/agent-run.ts约 2000 行它已经引入了RuntimeEvent、RuntimeEventStore、RuntimeInvocation等 v2 概念作为依赖说明 Phase 1/2 的改造已部分落地AiSdkBackend实现于 packages/runtime/src/ai-sdk-backend.tssend()通过openTurnScope(input)创建一次轮次作用域后yield* turn.run()每个send()绑定一个专属ToolRuntime并按轮次标识turn id管理自己的 abort controller——即文档中模型/工具循环隐式存在于AiSdkBackend.send()内部的现状ToolRuntime位于 packages/runtime/src/tool-runtime.tsModelAdapter位于 packages/runtime/src/model-adapter.tsModelHistory/model-history.ts与ai-sdk-message-projection.ts负责向 AI SDK 消息的投影。但它也有结构性的局限Maka 没有自己的显式Flow.Run模型/工具循环隐式存在于AiSdkBackend.send()加 AI SDK 内部跨轮次的模型历史由选中的StoredMessage类型构建而非来自一条规范运行时事件历史工具调用与工具结果被持久化用于 UI/历史但它们在未来模型上下文中的角色是materializePriorMessages()内部的一条隐式策略权限与工具事件分散在StoredMessage、SessionEvent、RunTraceEvent与遥测中而不是一个规范事实入口点仍拥有部分运行时就绪语义例如连接就绪/重绑定检查。目标架构AI SDK 继续做引擎Maka 拥有语义目标架构继续把 AI SDK 作为主要的模型/工具步进引擎但用 Maka 自有的调用与事件语义将其包裹起来┌────────────────────────────────────────────────────────────────────┐ │ Entrypoint Adapters │ │ │ │ Desktop IPC Bot Gateway OpenGateway │ │ - parse input - parse input - parse HTTP │ │ - validate shape - auth/rate limit - SSE/JSON │ │ - broadcast output - send bot reply - gateway output │ │ │ │ Entrypoints are protocol adapters. They do not own runtime loop, │ │ readiness, recovery, or model/tool policy. │ └──────────────────────────────┬─────────────────────────────────────┘ │ RuntimeRequest ▼ ┌────────────────────────────────────────────────────────────────────┐ │ RuntimeRunner │ │ │ │ - RuntimeGate preflight │ │ - create invocation/run context │ │ - append user RuntimeEvent │ │ - resolve active agent/flow policy │ │ - run AgentFlow │ │ - persist canonical events │ │ - drive projections │ └──────────────────────────────┬─────────────────────────────────────┘ │ InvocationContext ▼ ┌────────────────────────────────────────────────────────────────────┐ │ AgentFlow Interface │ │ │ │ interface AgentFlow { │ │ run(ctx, input): AsyncIterableRuntimeEvent │ │ } │ │ │ │ AiSdkFlow is the default long-term implementation: │ │ │ │ - build AI SDK messages from runtime history projection │ │ - build AI SDK tool map │ │ - call streamText({ tools, stopWhen: stepCountIs(...) }) │ │ - map text/thinking/tool/usage/finish/error to RuntimeEvent │ │ - delegate tool execution to ToolRuntime │ └──────────────────────────────┬─────────────────────────────────────┘ │ tool.execute seam ▼ ┌────────────────────────────────────────────────────────────────────┐ │ ToolRuntime │ │ │ │ - declaration/schema/registry │ │ - permission evaluation and parked decisions │ │ - tool implementation execution │ │ - output deltas and artifacts │ │ - tool telemetry │ │ - RuntimeEvent(tool_call/tool_result/permission/artifact) │ │ - returns result to AI SDK so streamText can continue stepping │ └────────────────────────────────────────────────────────────────────┘共享服务并排在这条路径旁边RuntimeEventLedger canonical invocation facts ProjectionManager RuntimeEvent - StoredMessage JSONL RuntimeEvent - renderer SessionEvent stream RuntimeEvent - TurnRecord / SessionHeader RuntimeEvent - AgentRunStore / RunTrace RuntimeEvent - TelemetryRepo SessionService event history scoped state legacy JSONL compatibility RuntimeGate readiness / rebind / blocked/running/waiting guards Plugin / Callback / Instruction prompt injection / audit / retry-reflect / telemetry hooksCanonical RuntimeEvent单一内部事实模型Runtime v2 需要单一的内部事实模型。归档文档给出了如下草图type RuntimeEvent { id: string; invocationId: string; runId: string; sessionId: string; turnId: string; ts: number; author: user | agent | tool | system; role: user | model | tool | system; branch?: string; partial: boolean; content?: { text?: string; thinking?: string; functionCall?: { id: string; name: string; args: unknown; }; functionResponse?: { id: string; name: string; result: unknown; isError?: boolean; }; error?: { code?: string; reason?: string; message: string; }; }; actions?: { stateDelta?: Recordstring, unknown; artifactDelta?: Recordstring, string | number; permissionRequest?: PermissionRequest; permissionDecision?: PermissionDecision; transferToAgent?: string; endInvocation?: boolean; tokenUsage?: TokenUsage; }; refs?: { storedMessageId?: string; traceEventId?: string; toolCallId?: string; providerEventId?: string; }; };这个事件既不是 UI 事件也不是 trace 事件而是内部运行时事实。其他记录要么从它写出要么显式链接到它。对比当前仓库中的落地实现 packages/core/src/runtime-event.ts草案的骨架已被完整保留并进一步强化。RuntimeEvent接口RuntimeEventinterface保留了id、invocationId、runId、sessionId、turnId、ts、branch、partial、role、author、content、actions、refs等字段并新增了三个草案中没有的关键域origin?: RuntimeEventOrigin——产生该事实的执行面execution surface旧账本legacy ledgers上缺失modelVisibility?: RuntimeEventModelVisibility——显式的 provider 历史策略缺省意味着对旧会话保持可见legacy compatibilitystatus?: RuntimeEventStatus——生命周期断言普通在途内容事件上省略isTerminalRuntimeEvent()通过检查status判定是否为终止事件。草案中的role: user | model | tool | system与author在实现中被抽象为闭域枚举RuntimeEventRole/RuntimeEventAuthor并且通过defineObjectShape定义了严格的信封形状校验runtimeEventEnvelopeKeys()与runtimeEventEnvelopeValueDomains()。值得注意的实现细节是这些闭域校验之所以被固定下来是因为曾有外部消费者自行重新实现了信封校验并发生漂移——它始终没有学到origin或modelVisibility一旦 Runtime 发出这两个字段所有事件都会在其信封校验中失败。因此 packages/core/src/runtime-event.ts 中的runtime-event.test.ts把校验语料固定到这份键列表上而不是第二份手工维护的形状。content域同样被细分为带kind判别字段的具体内容形状包括RuntimeEventTextContent、RuntimeEventThinkingContent、RuntimeEventFunctionCallContent、RuntimeEventFunctionResponseContent、RuntimeEventErrorContent、RuntimeEventSystemNoteContent、RuntimeEventInvocationOpenedContent等——其中kind: invocation-opened对应文档中append user RuntimeEvent的调用打开事实由 packages/core/src/runtime-invocation.ts 中的buildInvocationOpenedEvent构造。消费路径从事实到投影桌面用户消息Renderer - preload IPC - main IPC handler - normalize input - validate attachment shape - RuntimeRunner.run({ source: desktop, sessionId, text, attachments }) - RuntimeGate.preflight() - create invocation - append RuntimeEvent(user) - ProjectionManager writes user StoredMessage and renderer append event - AiSdkFlow.run(ctx) - build AI SDK messages from runtime history projection - streamText(...) - partial model chunks - RuntimeEvent(partial model text) - final model output - RuntimeEvent(final model text) - tool calls go through ToolRuntime - ProjectionManager writes: - assistant StoredMessage - TurnRecord - SessionHeader - AgentRun ledger status - telemetry usage/tool records - main process streams projected SessionEvents back to renderer渲染进程消费的是投影流projection stream它不直接消费运行时内核。仓库中与此对应的读模型基础设施包括 packages/runtime/src/runtime-event-read-model.ts将RuntimeEvent投影为用户消息等读模型projectRuntimeEventUserMessage被 agent-run.ts 直接调用与 packages/runtime/src/session-event-runtime-mapper.ts。工具调用与权限AiSdkFlow - AI SDK asks tool.execute({ args, toolCallId }) - ToolRuntime.executeTool() - RuntimeEvent(tool_call) - StoredMessage tool_call - renderer tool_start - PermissionEngine.evaluate() ├─ allow │ - run tool.impl │ - RuntimeEvent(tool_result) │ - return result to AI SDK │ ├─ block │ - RuntimeEvent(tool_result isError synthetic) │ - return synthetic error result to AI SDK │ └─ prompt - RuntimeEvent(permission_request) - renderer permission modal - session waiting_for_user projection - park tool execution - respondPermission(...) - RuntimeEvent(permission_decision) - allow/deny branch权限是运行时动作runtime action而不只是 UI 事件它应当被表示在RuntimeEvent.actions中。在落地实现中RuntimeEventActions域包含了 permission request/decision、interaction form、tool recovery fact 信封、workspace version authority 事实信封等类型见 packages/core/src/runtime-event.ts 的导入清单包括PermissionRequestPayload、PermissionResponse、InteractionFormInput、ToolRecoveryFactEnvelope、RuntimeEventWorkspaceFactEnvelope等印证了权限、工具恢复与工作区版本权威事实都要进运行时事件的设计。中止abort时被 park 的工具由轮次收尾逻辑负责拒绝——如 ai-sdk-backend.ts 的stop()所述abort signal does not wake the registry必须由endTurn拒绝仍在等待的工具否则兄弟轮次会永久 park 在等待上。模型历史构建今天模型历史由存储消息构建并且跳过若干运行时消息类型。Runtime v2 应把它变成一条显式投影RuntimeEvent history - ModelHistoryProjector include: user text events model final text events selected system/instruction events function call events when required by the provider protocol tool function response events exclude: partial chunks token usage trace diagnostics UI-only system notes permission ack unless deliberately exposed to the model - AI SDK messages这让下一次模型调用能看到什么这一策略变得可评审、可测试。仓库中对应的实现面包括 packages/runtime/src/model-history.ts、packages/runtime/src/ai-sdk-message-projection.ts 以及RuntimeEvent上的modelVisibility字段——该字段正是文档显式模型历史策略的载体。partial: true标记的瞬态分块会被模型历史排除实现注释明确写道Projections decide whether to persist partials; model history MUST exclude them。启动恢复App startup - RuntimeRecovery.scan() - read invocation/run ledger - classify non-terminal invocations by latest RuntimeEvent: - model stream started with no terminal event - failed app_restarted - tool started with no result - failed interrupted_tool - permission_request pending - waiting_for_user or failed by policy - final model event persisted but run header not completed - complete it - append recovery RuntimeEvent - ProjectionManager repairs: - TurnRecord - SessionHeader - StoredMessage system note if needed - AgentRun terminal status恢复应首先从规范调用事实推理然后再修复投影除非处理旧数据否则不应独立地从多个存储各自猜测。仓库中对应恢复能力的实现包括 packages/runtime/src/runtime-resume.ts、packages/runtime/src/recovery-resolver.ts、packages/runtime/src/agent-run-recovery.ts、packages/runtime/src/runtime-ledger-repair.ts 与 packages/runtime/src/runtime-event-backfill.ts事件回填用于旧数据。SessionManager中还实现了recoverAgentRunsFromLedger这类从账本恢复 AgentRun 的方法packages/runtime/src/session-manager.ts并有大量测试覆盖例如 packages/runtime/src/tests/agent-run-steering-recovery.test.ts、packages/runtime/src/tests/runtime-continuation-crash.test.ts 与 packages/runtime/src/tests/runtime-ledger-repair.test.ts。Bot 与 OpenGatewayBot / OpenGateway - normalize external protocol - RuntimeRunner.run({ source: bot | gateway, ... }) - same RuntimeGate - same AiSdkFlow - same ToolRuntime - projected output: bot: collect final response and send bot reply gateway: format JSON/SSE response desktop: optional fan-out when the same session is visible运行时不应为 desktop、bot、gateway 准备三条细微不同的发送路径。RuntimeEvent实现中RuntimeEventInvocationOpenedContent携带protocol、route、configuration、root、source与可选的lineage字段RuntimeInvocationRoute则区分provenance: runtime携带llmConnectionId、modelId、providerStateIdentity等与provenance其他来源正是入口点归一化为同一套调用事实、路由由运行时记录的落地体现。Source of Truth 边界预期的边界划分是RuntimeEventLedger runtime fact StoredMessage JSONL user-visible conversation projection and legacy read model renderer SessionEvent transport projection for UI streaming AgentRunStore invocation/run lifecycle ledger, eventually closely linked with RuntimeEvent RunTrace diagnostic-only projection; failures must not affect execution TelemetryRepo economic and operational projection这个边界是开展这项工作的主要原因。没有它增加更多功能只会不断增多需要对同一次运行达成一致的地方数量。提议的模块形态一个可能的文件布局packages/runtime/src/ runtime-event.ts runtime-event-projection.ts invocation-context.ts runtime-runner.ts runtime-gate.ts runtime-recovery.ts flows/ agent-flow.ts ai-sdk-flow.ts model/ model-adapter.ts model-history.ts tools/ tool-runtime.ts tool-registry.ts permission-events.ts projections/ stored-message-projection.ts session-event-projection.ts turn-record-projection.ts telemetry-projection.ts session-manager.ts这不是强制要求的最终文件布局重要的是方向SessionManager变成门面facade与会话 CRUD 的所有者而不是运行时大脑。对照当前仓库这一方向已部分兑现RuntimeEvent被下沉到 packages/core/src/runtime-event.tscore 层供 runtime 与 storage 复用事件存储契约在 packages/core/src/runtime-event-store.ts调用骨架与路由在 packages/core/src/runtime-invocation.ts 与 packages/runtime/src/runtime-invocation-route.tsSessionManager则仍然持有AgentRun编排packages/runtime/src/session-manager.ts——即门面化仍是进行中的工作。迁移计划七个阶段不搞大爆炸Phase 1RuntimeEvent RFC 与适配器在不变更运行路径的前提下加入规范事件类型与适配器。交付物RuntimeEvent与RuntimeEventActions针对现有StoredMessage、SessionEvent、AgentRunEvent、RunTraceEvent的映射测试明确哪些事件是事实、哪些是投影的文档。理由在改变控制流之前先给团队一套共享语言。当前仓库中 packages/core/src/runtime-event.ts 的文件头注明其 Phase 1 范围正是仅类型 小型纯辅助函数存储、runner、投影、账本逻辑不在此处——Phase 1 已落地。Phase 2RuntimeRunner 外壳引入RuntimeRunner.run()让SessionManager.sendMessage()在仍使用当前AgentRun.execute()的前提下委托给它。交付物RuntimeRunnerInvocationContext用于就绪策略的RuntimeGate占位向后兼容的SessionManager门面证明当前 UI 可见行为保持稳定的测试。理由在不一次性改动 AI SDK 或存储路径的前提下把调用所有权移出SessionManager。Phase 3AgentRunStore 升级为调用账本升级运行账本使其携带调用/事件关联。交付物链接到invocationId的运行头run headers尽可能链接到规范运行时事件 id 的运行事件从调用事实推理并修复投影的恢复测试。理由当前运行账本已经有用它应成为运行时脊柱的一部分而不是一条平行的诊断存储。仓库中AgentRun已直接依赖RuntimeEvent/RuntimeEventStore/RuntimeInvocation见 packages/runtime/src/agent-run.ts 的导入且 packages/runtime/src/tests/agent-run-inspect.test.ts、packages/runtime/src/tests/runtime-invocation-index.test.ts 等测试已覆盖该关联。Phase 4AiSdkFlow 形式化把当前AiSdkBackend.send()循环抽取/形式化为AiSdkFlow。交付物AgentFlow接口AiSdkFlow实现ModelHistoryProjectorAiSdkFlow发出规范RuntimeEventAiSdkBackend变成配置/工厂外壳而不是运行时循环所有者。理由AI SDK 仍是主引擎但 Maka 获得显式的流程输入/输出语义。Phase 5ToolRuntime 事件动作让工具调用、工具结果、权限请求、权限决定、状态增量与产物增量成为一等运行时事件动作。交付物tool_call/tool_result运行时事件权限请求/决定的运行时动作产物增量关联覆盖 allow/block/prompt/deny/abort 路径、经由规范事件流转的测试。理由工具是模型意图变成本地副作用的地方该边界必须可审计、可重放。Phase 6入口点清理把就绪与重绑定策略移出 desktop main进入运行时门gates。交付物RuntimeGate拥有连接就绪/重绑定/会话 blocked/running 守卫desktop/bot/gateway 入口调用同一套 runner API契约测试证明同一会话状态在 desktop、bot、gateway 路径上行为一致。理由入口点负责翻译协议不应拥有运行时策略。Phase 7模型历史正确性从运行时事件历史投影构建未来的模型提示。交付物明确哪些运行时事件进入模型历史的策略工具结果重放入下一次模型调用的测试排除 partial 分块、遥测、trace 与纯 UI 注释的测试围绕 AI SDK 消息形状的 provider 兼容性测试。理由下一次模型调用必须因为正确的理由看到正确的历史这应是经过测试的运行时策略而不是偶然的存储消息过滤。仓库中RuntimeEvent.modelVisibility字段正是这一策略的数据结构载体。不要做什么避免以下失败模式不要从零重写所有 provider 流式逻辑不要移除作为主流程引擎的 AI SDK不要删除会话 JSONL 兼容性不要把 UI 关注点塞进RuntimeEvent不要让RunTrace成为成功/失败的事实来源不要让 desktop main 继续做就绪/重绑定运行时策略的所有者不要在当前ToolRuntime之外再引入第二套工具运行时把它演进到事件/动作模型。成功标准当以下陈述全部为真时Runtime v2 才算完成开发者可以通过阅读一份调用/事件账本回答这一轮发生了什么UI 消息、轮次记录、运行记录、trace 行与遥测都可以追溯到规范运行时事件 iddesktop、bot、gateway 入口共享同一套运行时就绪与执行语义模型历史构建是从运行时事件出发的、显式的、经过测试的投影工具权限与工具结果行为以运行时动作的形式可见而不是散落的副作用SessionManager主要是会话 CRUD 加向后兼容门面方法AI SDK 通过AiSdkFlow仍是受支持的一等流程实现。开放问题这些应在实现开始前的 RFC 中回答规范RuntimeEvent应立即作为独立 JSONL 存储还是先镜像进AgentRunStore事件StoredMessage投影应与事件追加同步还是投影失败应可恢复/可重放当前RunTrace有多少应并入RuntimeEvent的 refs多少保留为仅诊断行权限提示应是模型可见事件、纯 UI 事件还是由流程策略配置在 Maka 拥有完整多智能体树之前branch/agent 转移应如何表示对没有运行时事件账本的旧会话兼容策略是什么结语从提案到代码的演进轨迹归档提案 docs/archive/runtime-v2-architecture-evolution.md 的价值不在于其每个类名都被照搬而在于它为运行时划定了明确的事实 / 投影边界并把迁移拆成了七个可独立验证的阶段。对照当前仓库可以看到这条路线已被逐步兑现RuntimeEvent契约与信封校验已落在 packages/core/src/runtime-event.ts事件存储与调用骨架落在 packages/core/src/runtime-event-store.ts 与 packages/core/src/runtime-invocation.tsAgentRun与SessionManager正在从运行时大脑向调用账本 门面演进恢复、修复与读模型设施runtime-resume.ts、runtime-ledger-repair.ts、runtime-event-read-model.ts已经就位。如果你需要理解 Maka 运行时现在长什么样、为什么这样长、还要往哪里去这份归档提案配合上述源码文件是最完整的阅读路径。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Maka Runtime v2 架构演进：以规范化调用/事件脊柱为中心的运行时重构方案
Maka Runtime v2 架构演进以规范化调用/事件脊柱为中心的运行时重构方案【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文基于归档提案 docs/archive/runtime-v2-architecture-evolution.md 展开并结合当前仓库packages/core与packages/runtime中的落地实现进行印证。该提案已于 2026-07-13 归档用于记录当前运行时的演进路线不作为现行架构权威现行架构请以仓库根目录 ARCHITECTURE.md 为准。Maka 的 Agent 运行时已经能完成本地编码代理的全部主链路Electron 桌面入口、会话 JSONL 存储、经 AI SDK 的模型流式输出、工具执行与权限弹窗、中止处理、Bot 与 OpenGateway 入口、工具产物与用量遥测以及内部AgentRun账本。但一次运行的事实被分散在StoredMessage、SessionEvent、AgentRunEvent、RunTraceEvent与遥测记录等多个平行结构中缺少一个稳定的重心。本文面向需要理解运行时为何需要再一次架构整理、哪些部分应当保持稳定、以及代码库如何在不做大爆炸式重写的前提下迁移到目标形态的开发者读完本文你将掌握 Maka 运行时的现状拆解、目标分层RuntimeRunner → InvocationContext → AgentFlow → AiSdkFlow → ToolRuntime、规范RuntimeEvent事实模型、各消费路径桌面、权限、模型历史、启动恢复、Bot/Gateway以及七阶段迁移计划并能在packages/core与packages/runtime中找到对应的落地证据。为什么运行时需要一个稳定的重心Maka 已经拥有一套可工作的本地编码 Agent 运行时其既有能力包括Electron 桌面入口点会话 JSONL 存储通过 AI SDK 的模型流式输出工具执行与权限提示中止abort处理Bot 与 OpenGateway 入口点工具产物artifacts与用量遥测内部AgentRun账本。现状架构比最初的单体路径更好但运行时仍然缺少一个稳定的中心。同一次运行目前被表示为若干相关但彼此分离的结构结构用途StoredMessage会话 JSONL 中的持久化消息SessionEvent面向渲染进程的事件流AgentRunEvent运行账本中的事件RunTraceEventbest-effort 诊断追踪遥测记录经济与运维投影这种分裂让系统难以演进也让一系列关键问题变得比应有的更困难哪些事实才是真正的运行时真相runtime truth哪些对象只是 UI 投影哪些事件应当被重放replay进下一次模型请求哪些事件仅用于诊断权限permission、工具tool、恢复recovery与遥测telemetry语义应当住在哪里Runtime v2 的答案是引入一条规范化的调用/事件脊柱RuntimeRunner - InvocationContext - AgentFlow - AiSdkFlow - AI SDK streamText - ToolRuntime - RuntimeEvent ledger - projections核心转变是今天 SessionManager StoredMessage/SessionEvent 靠近运行时中心。 目标 Invocation RuntimeEvent AgentFlow 成为运行时中心。 StoredMessage、渲染进程 SessionEvent、AgentRunStore、RunTrace、遥测 都变成由规范运行时事实派生的投影projections或账本ledgers。在仓库中这个方向已经以类型与纯辅助函数的形式落地在 packages/core/src/runtime-event.ts 中其文件头注释明确写道这是单一内部运行时事实模型不是UI 事件events.ts中的SessionEvent、不是trace 行RunTrace或遥测记录StoredMessageJSONL、渲染进程SessionEvent、AgentRunStore运维行、RunTrace与TelemetryRepo都应是从这些事件写出、或显式链接到这些事件的投影。文件头还注明了其架构依据正是 docs/architecture/runtime-core-architecture-draft.md。设计输入从 ADK 分层中吸取什么这份提案基于当前 Maka 实现以及 Google ADK Go 阅读材料中记录的运行时结构。值得借鉴的不是照搬类型名而是它的分层方式Runner - Agent - Flow - Model/Tool - Event - Session在该模型中Runner拥有调用外壳invocation shell与持久化边界Agent拥有生命周期与路由Flow拥有模型/工具循环Event是共享的运行时事实语言Session存储持久化历史与作用域状态工具、回调、插件、指令、工作流、入口点与遥测层围绕这条主轴附着而不会自身成为主轴。Maka 的产品约束不同因此演进需要适配长期保留 AI SDK 作为主流程实现保留 Electron 与既有用户可见的会话行为保留既有 JSONL 兼容性复用ToolRuntime、AgentRunStore与RunTrace避免一个旗日flag day即存储与 UI 投影一次性全部变更。当前运行时路径一次用户轮次的真实流向今天一次用户轮次大致按如下流程流动renderer / bot / gateway - desktop main / entrypoint code - ensureSessionCanSend(...) - SessionManager.sendMessage(sessionId, input) - new AgentRun(...) - AgentRun.execute() - append user StoredMessage - append turn_staterunning - lock connection snapshot - ensureActive() / build AiSdkBackend - register active run - AiSdkBackend.send() - PermissionEngine.beginTurn() - RunTrace - ModelAdapter.resolveModel() - build AI SDK tool map - materialize prior StoredMessage[] into AI SDK messages - AI SDK streamText({ tools, stopWhen: stepCountIs(maxSteps) }) - AI SDK owns model - tool - model stepping - tool.execute(...) calls ToolRuntime - pump fullStream into SessionEvent queue - append assistant StoredMessage - append token_usage StoredMessage - queue complete/error/abort - AgentRun updates SessionHeader / turn_state / AgentRunStore - cleanup active run这套拆分有一些不错的性质SessionManager.sendMessage()不再拥有整个热路径AgentRun提供持久化的运行生命周期记录ToolRuntime是工具权限、执行、产物与工具遥测的真正边界ModelAdapter隔离了 provider / AI SDK 的流式与错误归一化。从源码看上述调用链可以在仓库中逐点印证SessionManager的sendMessage位于 packages/runtime/src/session-manager.ts其注释明确写着它owns AgentRun orchestration, backend execution, and ledger recording即它至今仍是AgentRun编排、后端执行与账本记录的持有者——这正是文档所说需要被拆掉的重心AgentRun类实现于 packages/runtime/src/agent-run.ts约 2000 行它已经引入了RuntimeEvent、RuntimeEventStore、RuntimeInvocation等 v2 概念作为依赖说明 Phase 1/2 的改造已部分落地AiSdkBackend实现于 packages/runtime/src/ai-sdk-backend.tssend()通过openTurnScope(input)创建一次轮次作用域后yield* turn.run()每个send()绑定一个专属ToolRuntime并按轮次标识turn id管理自己的 abort controller——即文档中模型/工具循环隐式存在于AiSdkBackend.send()内部的现状ToolRuntime位于 packages/runtime/src/tool-runtime.tsModelAdapter位于 packages/runtime/src/model-adapter.tsModelHistory/model-history.ts与ai-sdk-message-projection.ts负责向 AI SDK 消息的投影。但它也有结构性的局限Maka 没有自己的显式Flow.Run模型/工具循环隐式存在于AiSdkBackend.send()加 AI SDK 内部跨轮次的模型历史由选中的StoredMessage类型构建而非来自一条规范运行时事件历史工具调用与工具结果被持久化用于 UI/历史但它们在未来模型上下文中的角色是materializePriorMessages()内部的一条隐式策略权限与工具事件分散在StoredMessage、SessionEvent、RunTraceEvent与遥测中而不是一个规范事实入口点仍拥有部分运行时就绪语义例如连接就绪/重绑定检查。目标架构AI SDK 继续做引擎Maka 拥有语义目标架构继续把 AI SDK 作为主要的模型/工具步进引擎但用 Maka 自有的调用与事件语义将其包裹起来┌────────────────────────────────────────────────────────────────────┐ │ Entrypoint Adapters │ │ │ │ Desktop IPC Bot Gateway OpenGateway │ │ - parse input - parse input - parse HTTP │ │ - validate shape - auth/rate limit - SSE/JSON │ │ - broadcast output - send bot reply - gateway output │ │ │ │ Entrypoints are protocol adapters. They do not own runtime loop, │ │ readiness, recovery, or model/tool policy. │ └──────────────────────────────┬─────────────────────────────────────┘ │ RuntimeRequest ▼ ┌────────────────────────────────────────────────────────────────────┐ │ RuntimeRunner │ │ │ │ - RuntimeGate preflight │ │ - create invocation/run context │ │ - append user RuntimeEvent │ │ - resolve active agent/flow policy │ │ - run AgentFlow │ │ - persist canonical events │ │ - drive projections │ └──────────────────────────────┬─────────────────────────────────────┘ │ InvocationContext ▼ ┌────────────────────────────────────────────────────────────────────┐ │ AgentFlow Interface │ │ │ │ interface AgentFlow { │ │ run(ctx, input): AsyncIterableRuntimeEvent │ │ } │ │ │ │ AiSdkFlow is the default long-term implementation: │ │ │ │ - build AI SDK messages from runtime history projection │ │ - build AI SDK tool map │ │ - call streamText({ tools, stopWhen: stepCountIs(...) }) │ │ - map text/thinking/tool/usage/finish/error to RuntimeEvent │ │ - delegate tool execution to ToolRuntime │ └──────────────────────────────┬─────────────────────────────────────┘ │ tool.execute seam ▼ ┌────────────────────────────────────────────────────────────────────┐ │ ToolRuntime │ │ │ │ - declaration/schema/registry │ │ - permission evaluation and parked decisions │ │ - tool implementation execution │ │ - output deltas and artifacts │ │ - tool telemetry │ │ - RuntimeEvent(tool_call/tool_result/permission/artifact) │ │ - returns result to AI SDK so streamText can continue stepping │ └────────────────────────────────────────────────────────────────────┘共享服务并排在这条路径旁边RuntimeEventLedger canonical invocation facts ProjectionManager RuntimeEvent - StoredMessage JSONL RuntimeEvent - renderer SessionEvent stream RuntimeEvent - TurnRecord / SessionHeader RuntimeEvent - AgentRunStore / RunTrace RuntimeEvent - TelemetryRepo SessionService event history scoped state legacy JSONL compatibility RuntimeGate readiness / rebind / blocked/running/waiting guards Plugin / Callback / Instruction prompt injection / audit / retry-reflect / telemetry hooksCanonical RuntimeEvent单一内部事实模型Runtime v2 需要单一的内部事实模型。归档文档给出了如下草图type RuntimeEvent { id: string; invocationId: string; runId: string; sessionId: string; turnId: string; ts: number; author: user | agent | tool | system; role: user | model | tool | system; branch?: string; partial: boolean; content?: { text?: string; thinking?: string; functionCall?: { id: string; name: string; args: unknown; }; functionResponse?: { id: string; name: string; result: unknown; isError?: boolean; }; error?: { code?: string; reason?: string; message: string; }; }; actions?: { stateDelta?: Recordstring, unknown; artifactDelta?: Recordstring, string | number; permissionRequest?: PermissionRequest; permissionDecision?: PermissionDecision; transferToAgent?: string; endInvocation?: boolean; tokenUsage?: TokenUsage; }; refs?: { storedMessageId?: string; traceEventId?: string; toolCallId?: string; providerEventId?: string; }; };这个事件既不是 UI 事件也不是 trace 事件而是内部运行时事实。其他记录要么从它写出要么显式链接到它。对比当前仓库中的落地实现 packages/core/src/runtime-event.ts草案的骨架已被完整保留并进一步强化。RuntimeEvent接口RuntimeEventinterface保留了id、invocationId、runId、sessionId、turnId、ts、branch、partial、role、author、content、actions、refs等字段并新增了三个草案中没有的关键域origin?: RuntimeEventOrigin——产生该事实的执行面execution surface旧账本legacy ledgers上缺失modelVisibility?: RuntimeEventModelVisibility——显式的 provider 历史策略缺省意味着对旧会话保持可见legacy compatibilitystatus?: RuntimeEventStatus——生命周期断言普通在途内容事件上省略isTerminalRuntimeEvent()通过检查status判定是否为终止事件。草案中的role: user | model | tool | system与author在实现中被抽象为闭域枚举RuntimeEventRole/RuntimeEventAuthor并且通过defineObjectShape定义了严格的信封形状校验runtimeEventEnvelopeKeys()与runtimeEventEnvelopeValueDomains()。值得注意的实现细节是这些闭域校验之所以被固定下来是因为曾有外部消费者自行重新实现了信封校验并发生漂移——它始终没有学到origin或modelVisibility一旦 Runtime 发出这两个字段所有事件都会在其信封校验中失败。因此 packages/core/src/runtime-event.ts 中的runtime-event.test.ts把校验语料固定到这份键列表上而不是第二份手工维护的形状。content域同样被细分为带kind判别字段的具体内容形状包括RuntimeEventTextContent、RuntimeEventThinkingContent、RuntimeEventFunctionCallContent、RuntimeEventFunctionResponseContent、RuntimeEventErrorContent、RuntimeEventSystemNoteContent、RuntimeEventInvocationOpenedContent等——其中kind: invocation-opened对应文档中append user RuntimeEvent的调用打开事实由 packages/core/src/runtime-invocation.ts 中的buildInvocationOpenedEvent构造。消费路径从事实到投影桌面用户消息Renderer - preload IPC - main IPC handler - normalize input - validate attachment shape - RuntimeRunner.run({ source: desktop, sessionId, text, attachments }) - RuntimeGate.preflight() - create invocation - append RuntimeEvent(user) - ProjectionManager writes user StoredMessage and renderer append event - AiSdkFlow.run(ctx) - build AI SDK messages from runtime history projection - streamText(...) - partial model chunks - RuntimeEvent(partial model text) - final model output - RuntimeEvent(final model text) - tool calls go through ToolRuntime - ProjectionManager writes: - assistant StoredMessage - TurnRecord - SessionHeader - AgentRun ledger status - telemetry usage/tool records - main process streams projected SessionEvents back to renderer渲染进程消费的是投影流projection stream它不直接消费运行时内核。仓库中与此对应的读模型基础设施包括 packages/runtime/src/runtime-event-read-model.ts将RuntimeEvent投影为用户消息等读模型projectRuntimeEventUserMessage被 agent-run.ts 直接调用与 packages/runtime/src/session-event-runtime-mapper.ts。工具调用与权限AiSdkFlow - AI SDK asks tool.execute({ args, toolCallId }) - ToolRuntime.executeTool() - RuntimeEvent(tool_call) - StoredMessage tool_call - renderer tool_start - PermissionEngine.evaluate() ├─ allow │ - run tool.impl │ - RuntimeEvent(tool_result) │ - return result to AI SDK │ ├─ block │ - RuntimeEvent(tool_result isError synthetic) │ - return synthetic error result to AI SDK │ └─ prompt - RuntimeEvent(permission_request) - renderer permission modal - session waiting_for_user projection - park tool execution - respondPermission(...) - RuntimeEvent(permission_decision) - allow/deny branch权限是运行时动作runtime action而不只是 UI 事件它应当被表示在RuntimeEvent.actions中。在落地实现中RuntimeEventActions域包含了 permission request/decision、interaction form、tool recovery fact 信封、workspace version authority 事实信封等类型见 packages/core/src/runtime-event.ts 的导入清单包括PermissionRequestPayload、PermissionResponse、InteractionFormInput、ToolRecoveryFactEnvelope、RuntimeEventWorkspaceFactEnvelope等印证了权限、工具恢复与工作区版本权威事实都要进运行时事件的设计。中止abort时被 park 的工具由轮次收尾逻辑负责拒绝——如 ai-sdk-backend.ts 的stop()所述abort signal does not wake the registry必须由endTurn拒绝仍在等待的工具否则兄弟轮次会永久 park 在等待上。模型历史构建今天模型历史由存储消息构建并且跳过若干运行时消息类型。Runtime v2 应把它变成一条显式投影RuntimeEvent history - ModelHistoryProjector include: user text events model final text events selected system/instruction events function call events when required by the provider protocol tool function response events exclude: partial chunks token usage trace diagnostics UI-only system notes permission ack unless deliberately exposed to the model - AI SDK messages这让下一次模型调用能看到什么这一策略变得可评审、可测试。仓库中对应的实现面包括 packages/runtime/src/model-history.ts、packages/runtime/src/ai-sdk-message-projection.ts 以及RuntimeEvent上的modelVisibility字段——该字段正是文档显式模型历史策略的载体。partial: true标记的瞬态分块会被模型历史排除实现注释明确写道Projections decide whether to persist partials; model history MUST exclude them。启动恢复App startup - RuntimeRecovery.scan() - read invocation/run ledger - classify non-terminal invocations by latest RuntimeEvent: - model stream started with no terminal event - failed app_restarted - tool started with no result - failed interrupted_tool - permission_request pending - waiting_for_user or failed by policy - final model event persisted but run header not completed - complete it - append recovery RuntimeEvent - ProjectionManager repairs: - TurnRecord - SessionHeader - StoredMessage system note if needed - AgentRun terminal status恢复应首先从规范调用事实推理然后再修复投影除非处理旧数据否则不应独立地从多个存储各自猜测。仓库中对应恢复能力的实现包括 packages/runtime/src/runtime-resume.ts、packages/runtime/src/recovery-resolver.ts、packages/runtime/src/agent-run-recovery.ts、packages/runtime/src/runtime-ledger-repair.ts 与 packages/runtime/src/runtime-event-backfill.ts事件回填用于旧数据。SessionManager中还实现了recoverAgentRunsFromLedger这类从账本恢复 AgentRun 的方法packages/runtime/src/session-manager.ts并有大量测试覆盖例如 packages/runtime/src/tests/agent-run-steering-recovery.test.ts、packages/runtime/src/tests/runtime-continuation-crash.test.ts 与 packages/runtime/src/tests/runtime-ledger-repair.test.ts。Bot 与 OpenGatewayBot / OpenGateway - normalize external protocol - RuntimeRunner.run({ source: bot | gateway, ... }) - same RuntimeGate - same AiSdkFlow - same ToolRuntime - projected output: bot: collect final response and send bot reply gateway: format JSON/SSE response desktop: optional fan-out when the same session is visible运行时不应为 desktop、bot、gateway 准备三条细微不同的发送路径。RuntimeEvent实现中RuntimeEventInvocationOpenedContent携带protocol、route、configuration、root、source与可选的lineage字段RuntimeInvocationRoute则区分provenance: runtime携带llmConnectionId、modelId、providerStateIdentity等与provenance其他来源正是入口点归一化为同一套调用事实、路由由运行时记录的落地体现。Source of Truth 边界预期的边界划分是RuntimeEventLedger runtime fact StoredMessage JSONL user-visible conversation projection and legacy read model renderer SessionEvent transport projection for UI streaming AgentRunStore invocation/run lifecycle ledger, eventually closely linked with RuntimeEvent RunTrace diagnostic-only projection; failures must not affect execution TelemetryRepo economic and operational projection这个边界是开展这项工作的主要原因。没有它增加更多功能只会不断增多需要对同一次运行达成一致的地方数量。提议的模块形态一个可能的文件布局packages/runtime/src/ runtime-event.ts runtime-event-projection.ts invocation-context.ts runtime-runner.ts runtime-gate.ts runtime-recovery.ts flows/ agent-flow.ts ai-sdk-flow.ts model/ model-adapter.ts model-history.ts tools/ tool-runtime.ts tool-registry.ts permission-events.ts projections/ stored-message-projection.ts session-event-projection.ts turn-record-projection.ts telemetry-projection.ts session-manager.ts这不是强制要求的最终文件布局重要的是方向SessionManager变成门面facade与会话 CRUD 的所有者而不是运行时大脑。对照当前仓库这一方向已部分兑现RuntimeEvent被下沉到 packages/core/src/runtime-event.tscore 层供 runtime 与 storage 复用事件存储契约在 packages/core/src/runtime-event-store.ts调用骨架与路由在 packages/core/src/runtime-invocation.ts 与 packages/runtime/src/runtime-invocation-route.tsSessionManager则仍然持有AgentRun编排packages/runtime/src/session-manager.ts——即门面化仍是进行中的工作。迁移计划七个阶段不搞大爆炸Phase 1RuntimeEvent RFC 与适配器在不变更运行路径的前提下加入规范事件类型与适配器。交付物RuntimeEvent与RuntimeEventActions针对现有StoredMessage、SessionEvent、AgentRunEvent、RunTraceEvent的映射测试明确哪些事件是事实、哪些是投影的文档。理由在改变控制流之前先给团队一套共享语言。当前仓库中 packages/core/src/runtime-event.ts 的文件头注明其 Phase 1 范围正是仅类型 小型纯辅助函数存储、runner、投影、账本逻辑不在此处——Phase 1 已落地。Phase 2RuntimeRunner 外壳引入RuntimeRunner.run()让SessionManager.sendMessage()在仍使用当前AgentRun.execute()的前提下委托给它。交付物RuntimeRunnerInvocationContext用于就绪策略的RuntimeGate占位向后兼容的SessionManager门面证明当前 UI 可见行为保持稳定的测试。理由在不一次性改动 AI SDK 或存储路径的前提下把调用所有权移出SessionManager。Phase 3AgentRunStore 升级为调用账本升级运行账本使其携带调用/事件关联。交付物链接到invocationId的运行头run headers尽可能链接到规范运行时事件 id 的运行事件从调用事实推理并修复投影的恢复测试。理由当前运行账本已经有用它应成为运行时脊柱的一部分而不是一条平行的诊断存储。仓库中AgentRun已直接依赖RuntimeEvent/RuntimeEventStore/RuntimeInvocation见 packages/runtime/src/agent-run.ts 的导入且 packages/runtime/src/tests/agent-run-inspect.test.ts、packages/runtime/src/tests/runtime-invocation-index.test.ts 等测试已覆盖该关联。Phase 4AiSdkFlow 形式化把当前AiSdkBackend.send()循环抽取/形式化为AiSdkFlow。交付物AgentFlow接口AiSdkFlow实现ModelHistoryProjectorAiSdkFlow发出规范RuntimeEventAiSdkBackend变成配置/工厂外壳而不是运行时循环所有者。理由AI SDK 仍是主引擎但 Maka 获得显式的流程输入/输出语义。Phase 5ToolRuntime 事件动作让工具调用、工具结果、权限请求、权限决定、状态增量与产物增量成为一等运行时事件动作。交付物tool_call/tool_result运行时事件权限请求/决定的运行时动作产物增量关联覆盖 allow/block/prompt/deny/abort 路径、经由规范事件流转的测试。理由工具是模型意图变成本地副作用的地方该边界必须可审计、可重放。Phase 6入口点清理把就绪与重绑定策略移出 desktop main进入运行时门gates。交付物RuntimeGate拥有连接就绪/重绑定/会话 blocked/running 守卫desktop/bot/gateway 入口调用同一套 runner API契约测试证明同一会话状态在 desktop、bot、gateway 路径上行为一致。理由入口点负责翻译协议不应拥有运行时策略。Phase 7模型历史正确性从运行时事件历史投影构建未来的模型提示。交付物明确哪些运行时事件进入模型历史的策略工具结果重放入下一次模型调用的测试排除 partial 分块、遥测、trace 与纯 UI 注释的测试围绕 AI SDK 消息形状的 provider 兼容性测试。理由下一次模型调用必须因为正确的理由看到正确的历史这应是经过测试的运行时策略而不是偶然的存储消息过滤。仓库中RuntimeEvent.modelVisibility字段正是这一策略的数据结构载体。不要做什么避免以下失败模式不要从零重写所有 provider 流式逻辑不要移除作为主流程引擎的 AI SDK不要删除会话 JSONL 兼容性不要把 UI 关注点塞进RuntimeEvent不要让RunTrace成为成功/失败的事实来源不要让 desktop main 继续做就绪/重绑定运行时策略的所有者不要在当前ToolRuntime之外再引入第二套工具运行时把它演进到事件/动作模型。成功标准当以下陈述全部为真时Runtime v2 才算完成开发者可以通过阅读一份调用/事件账本回答这一轮发生了什么UI 消息、轮次记录、运行记录、trace 行与遥测都可以追溯到规范运行时事件 iddesktop、bot、gateway 入口共享同一套运行时就绪与执行语义模型历史构建是从运行时事件出发的、显式的、经过测试的投影工具权限与工具结果行为以运行时动作的形式可见而不是散落的副作用SessionManager主要是会话 CRUD 加向后兼容门面方法AI SDK 通过AiSdkFlow仍是受支持的一等流程实现。开放问题这些应在实现开始前的 RFC 中回答规范RuntimeEvent应立即作为独立 JSONL 存储还是先镜像进AgentRunStore事件StoredMessage投影应与事件追加同步还是投影失败应可恢复/可重放当前RunTrace有多少应并入RuntimeEvent的 refs多少保留为仅诊断行权限提示应是模型可见事件、纯 UI 事件还是由流程策略配置在 Maka 拥有完整多智能体树之前branch/agent 转移应如何表示对没有运行时事件账本的旧会话兼容策略是什么结语从提案到代码的演进轨迹归档提案 docs/archive/runtime-v2-architecture-evolution.md 的价值不在于其每个类名都被照搬而在于它为运行时划定了明确的事实 / 投影边界并把迁移拆成了七个可独立验证的阶段。对照当前仓库可以看到这条路线已被逐步兑现RuntimeEvent契约与信封校验已落在 packages/core/src/runtime-event.ts事件存储与调用骨架落在 packages/core/src/runtime-event-store.ts 与 packages/core/src/runtime-invocation.tsAgentRun与SessionManager正在从运行时大脑向调用账本 门面演进恢复、修复与读模型设施runtime-resume.ts、runtime-ledger-repair.ts、runtime-event-read-model.ts已经就位。如果你需要理解 Maka 运行时现在长什么样、为什么这样长、还要往哪里去这份归档提案配合上述源码文件是最完整的阅读路径。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考