Aller au contenu
Jefferson Gonçalves
← Retour aux projets

Maka Learning Docs

#maka 实现学习文档系列

一套自顶向下、偏设计决策的中文技术文档,帮你读懂 maka(一个本地优先的 Agent 运行时)是怎么一步步长出来的。

本系列基于对 maka 仓库 2265 次提交(2026-05-19 脚手架 → 2026-07-22 HEAD f9e78d17,约 9 周)的系统研究写成:每个论断都尽量落到具体的文件、函数、数据结构与提交号,方便你 git show / 打开源码对照。代码是佐证,不是主角;每篇优先讲"要解决什么问题、为什么这样设计、取舍与演化是什么"。

#这套文档的立场

  • 偏设计决策:重点是架构取舍、演化历史、踩坑与回滚(maka 历史里有很多"能做但刻意不做"的判断,这些最有教学价值)。
  • 诚实区分 Current / Target:很多机制在仓库里标了 implementation_status,本系列不把"目标态"讲成"已实现"。
  • 最终权威是源码:文档是帮你更快读懂 maka 的地图;当文档与实现冲突时,以仓库源码与契约测试为准。

#九篇目录

# 篇章 一句话
01 总览:log-first 架构与演化 全系列地图:三层心智模型、"日志即运行时"总纲、9 周演化时间线、包边界、怎么读这套文档
02 Runtime 内核:日志即运行时 技术核心:从 JSONL 单体 → 6/14 抽内核 → 6/15 读切换,RuntimeEvent 成为唯一事实、其余皆投影
03 工具运行时与权限/沙箱 Agent 怎么安全动手:权限矩阵、ToolRuntime、工具保真度、可见性合并(#37)、OS 沙箱
04 上下文管理:剪枝/归档/压缩 "上下文不是历史":大结果归档换占位符、prune→archive→retrieve→compact、压缩=日志投影
05 Headless:可持续任务与 TaskRun 账本 "任务活过一个 turn":第二本账本、四层身份、三层预算、以及关键的 proof-chain 回滚(#181)
06 自检、评测与 AHE/RSI 自迭代 "自检不是自信":有界自检(只修一次)、official 评测权威、RSI 闭环、AHE 运行时外边界
07 多 Agent 编排:spawn→swarm→team 四级编排阶梯;HEAD 特性 Agent Swarm 为何刻意"很轻"(无第二账本、不能嵌套)
08 集成面:providers/CLI/computer-use/MCP/skills 怎么把外部世界安全接进来:数据驱动 registry、computer-use 默认关、MCP 复用边界
09 附录:桌面 UI/设计系统与工程纪律 两条横切故事:UI 从手搓到受治理、工程纪律从"沉积"到"自审计"

#篇章依赖与阅读顺序

flowchart TD
    O["01 总览(先读)"]
    O --> R["02 Runtime 内核<br/>(技术核心)"]
    R --> T["03 工具/权限/沙箱"]
    R --> C["04 上下文管理"]
    R --> H["05 Headless 可持续任务"]
    H --> S["06 自检/评测/AHE·RSI"]
    H --> M["07 多 Agent 编排"]
    T --> I["08 集成面"]
    M --> I
    I --> A["09 附录:UI 与工程纪律"]
    C -. 投影同源 .- R
    S -. 同种克制 .- M

    classDef core fill:#dbeafe,stroke:#3b82f6;
    class O,R core;

说明:01 是入口,02 是技术核心(几乎所有后续篇章都建立在它的"日志即事实"之上)。03/04 是内核的两个直接延伸(工具事实、上下文投影);05 开启"长程任务"支线,06/07 建立其上;08 讲外部集成;09 是横切附录。

#三条阅读路径

按你的兴趣挑一条走:

  • 想懂核心架构 → 01 → 02 → 04 (日志即运行时 + 上下文如何在不删事实的前提下投影)
  • 想懂可持续任务与自治 → 01 → 05 → 06 → 07 (任务活过 turn → 自检与自迭代边界 → 多 Agent 编排)
  • 想懂集成与产品面 → 01 → 03 → 08 → 09 (工具/权限安全底座 → 外部世界接入 → UI 与工程纪律)

#一条贯穿全系列的主线

如果只记一件事:maka 是 log-first, projection-driven 的——运行事实进入 append-only 日志,Session/UI/模型上下文/恢复/压缩/演化证据全是这份日志的投影。它的三次关键跃迁:

JSONL 即真相(5月) → 抽 AgentRun 账本(6/14) → RuntimeEvent 日志即唯一真相(6/15 读切换)

一旦"日志是事实、其余皆投影"这条公理确立,后面所有大特性——上下文剪枝、压缩、可持续任务、自检、AHE 自迭代、Swarm——都是这套账本 + 投影契约的自然延伸。而反复出现的工程品味是:能用更朴素的层级站住,就不往上叠复杂度;能回滚过度设计就回滚;契约先行、分期交付、fail-closed。

本系列由对 maka git 历史与 HEAD 源码的研究整理而成。每篇末尾的「对照源码」小节列出了该篇涉及的关键文件与提交号,建议边读边 git show 对照。

Nouvelle version disponible.