flowchart LR
    C["Desktop / TUI / CLI / Bot"] --> H["Runtime Host"]
    H --> S["SessionManager"]
    S --> R["AgentRun + Runtime Runner"]
    R --> T["Tool Runtime"]
    R --> L["Runtime Event Log"]
    S --> G["Agent Graph Control Plane"]
    G --> R
    L --> P["Context / Session / UI / Recovery projections"]

    E["@maka/eval\nExperiment → Cells → Attempts → Results"] --> H
    X["External subjects"] --> E

Runtime Host 拥有 Session 和 Turn identity、agent lifecycle、continuation、tools、permissions 与 events。@maka/eval 只拥有 benchmark 实验语义：subjects、tasks、repetitions、cells、immutable attempts、result selection、budget 和 verifier 配置。Maka subject 必须经过公开的 Runtime Host client/protocol 边界；外部竞品是 generic external subject。

Runtime 分层

Runtime Event Log 是模型消息、Tool Call、Tool Result 和终止事实的 canonical source。上下文裁剪与 compaction 只改变 provider input projection，不改写历史。
SessionManager 和 AgentRun 拥有执行生命周期。Runtime Host 拥有 admission、client capability、interaction 与公开协议。
Agent Graph 通过 child Session 调度依赖工作，并把每次 activation 送回同一 Runtime。
Storage 只拥有交互 Runtime 状态，不再有 Eval 专用 root、TaskRun ledger 或实验结果 authority。

Eval 边界

Experiment = benchmark + executor + subjects + tasks + repetitions
Cell       = task × repetition × subject

repetition   = 新的实验样本
infra retry  = 同一个 cell 的替换 attempt
continuation = Maka subject 内部的 Runtime Host 行为

一个 Experiment 使用一份完全展开的声明式 spec。所有 arms 共享 executor、benchmark、tasks、budget 和 verifier。A/B 只是双臂 Experiment。Harbor 和 Pier 是 executor adapter，不是独立 workflow。

通用结果只包含 score、normalized usage、可归因 cost、duration、status 或 failure reason 以及 artifacts。一个 cell 有多个 attempts 时，以最早有效 attempt 为权威，operator 不能人工挑选结果。

代码边界

区域	职责
`packages/core`	Session、Runtime Event、AgentRun、permission 和协议等纯 contract
`packages/storage`	交互 Runtime store 与 SQLite control plane
`packages/runtime`	SessionManager、AgentRun、模型 adapter、tools、context、recovery 与 Graph reconciliation
`packages/runtime-host`	唯一 hosted execution authority 与公开 client/protocol
`packages/eval`	Experiment cell、attempt、result selection 与 subject/executor adapter
`packages/cli`	TUI、`maka run` 与唯一公开 `maka eval` 路由
`apps/desktop/src/main`	Electron composition 与产品入口 adapter

阅读路径

Runtime 事实与 projection：Runtime core 与 compaction。
Crash recovery 与 continuation：Runtime resume。
Multi-agent scheduling：Agent Graph。
Eval 行为与公开 seam：packages/eval。

历史设计保存在 docs/archive。当前 GitHub Issue 与源码优先于旧 draft。

4.3 KiB Raw Blame History Unescape Escape

Maka 后端架构

Runtime 分层

Eval 边界

代码边界

阅读路径

4.3 KiB

Raw Blame History