Ubuntu 22.04 源码安装 Apache Maka 0.2.0 指南

状态提示：Apache Maka 处于孵化器孵化阶段，0.2.0-incubating 为孵化期候选发布，API 与存储格式可能变化，请勿用于生产环境。本文全部命令与回显均来自 Ubuntu 22.04 服务器实测。

技术栈澄清：Maka 是 TypeScript/Node.js 项目，运行依赖 Node.js 22.19+ 与 npm 11，不依赖 Python。源码包中虽带有少量 Python 开发辅助脚本，但它们不属于安装链路，安装过程无需安装任何 Python 环境。

一、安装目标

在一台 Ubuntu 22.04 服务器上，从官方源码包完成 Maka 0.2.0 的安装与验证，最终做到：

Node.js 22.19.0 可用；
源码包 SHA512 校验通过、依赖安装与构建完成；
maka CLI 可执行，版本回显 0.2.0；
配置一个指向本地 stub 模型服务的连接，真实跑通一次带工具调用的 agent 会话（无需任何外部 API key）；
掌握完整的卸载方法。

1.1 为什么选源码构建这条路

Maka 当前有三条获取路径，各自适合不同场景。npm 上的 maka-agent@nightly 是滚动构建，安装最快，但版本与任何一次官方发布都不保证对应，做版本锁定评估时不可控；桌面端形态面向交互使用者，服务器场景用不上；源码构建（本文路径）虽然多花十几分钟，但换来三个确定性——源码经社区签名与 SHA512 校验，供应链可审计；构建产物版本与 0.2.0-incubating 精确对应，评估结论可复现；monorepo 九个子包全部在本地，遇到行为问题时可直接翻源码定位。对以"评估是否引入"为目的的读者，第三条路是唯一严肃的选择，本文余下部分全部围绕它展开。

整个安装链路可以概括为四步：准备系统工具与 Node 22 运行时；获取源码包并做 SHA512 校验；npm ci 装依赖、npm run build 出产物；配置一个本地 stub 模型连接跑通真实会话。全程不需要任何外部 API key，也不需要图形界面，一台裸装 Ubuntu 22.04 的服务器即可完成。

二、系统准备

系统准备阶段装齐四类工具：下载工具（curl/wget）、版本控制（git）、文本搜索（ripgrep）与编译工具链（build-essential），外加 Node.js 22 运行时。这一节的三条实测回显（git 2.34.1、ripgrep 13.0.0、Node v22.19.0）可以作为部署清单的基准值，版本号不同但满足最低要求即可。

2.1 更新系统并安装基础工具

apt-get update
apt-get install -y curl wget git ripgrep build-essential

验证：

git --version
rg --version | head -1

实测回显：

git version 2.34.1
ripgrep 13.0.0

ripgrep 是 Maka Runtime 的 Grep 工具的直接依赖（README 明确列出），必须在系统 PATH 中可用。build-essential 提供编译型 npm 包所需的工具链。四个包各有明确用途：curl 与 wget 负责后续的源码包与二进制下载；git 既是 README 列出的运行要求（工作区操作会用到），也是阅读源码历史的工具；ripgrep 的定位要特别强调——它不是可选加速组件，Runtime 的 Grep 工具执行时直接调用系统 PATH 里的 rg 命令，缺失时会在模型调用该工具的环节才报错，属于典型的"晚爆雷"，务必在安装阶段就位；build-essential 供 node-gyp 编译原生模块使用，虽然 Maka 自身依赖以纯 JavaScript 为主，Electron 等包的安装脚本仍可能触达编译工具。回显中 ripgrep 13.0.0 是 Ubuntu 22.04 源内版本，满足要求，无需追求新版。

2.2 安装 Node.js 22.19

Ubuntu 22.04 的 apt 源不提供 Node 22，采用官方二进制包安装（无需编译）：

cd /opt
curl -sSL -o node.tar.xz https://nodejs.org/dist/v22.19.0/node-v22.19.0-linux-x64.tar.xz
tar -xJf node.tar.xz
mv node-v22.19.0-linux-x64 node
ln -sf /opt/node/bin/node /usr/local/bin/node
ln -sf /opt/node/bin/npm /usr/local/bin/npm
ln -sf /opt/node/bin/npx /usr/local/bin/npx
node --version
npm --version

实测回显：

v22.19.0
10.9.3

npm 版本说明：Node 22.19 自带 npm 10.9.3，实测完成全部构建步骤没有问题；README 建议的 npm 11 可通过 npm install -g npm@11 升级，非必需。为什么必须 Node 22 而不能是发行版源里的 18：Maka 的存储层使用了 Node 22 才内置的 node:sqlite 模块承载运行时事件库（实验性 API，但官方维护），这是硬性版本门槛；此外 Runtime 还依赖 Node 22 系列的其他新特性。选择官方二进制包而非源码编译，是把安装时间从小时级压到分钟级的务实决定——Node 官方为 Ubuntu 提供预编译的 linux-x64 包，解压即用。安装方式上刻意用 /opt/node 加 /usr/local/bin 软链的组合而不是写 PATH：软链只覆盖 node、npm、npx 三个入口命令，node 自带的 corepack 等其余工具留在 /opt/node/bin 中按需取用，系统全局环境保持干净，卸载时删软链与目录即可，不留残余。

三、获取源码并校验

3.1 下载源码包与校验文件

cd /opt
curl -sSL -o maka-src.tar.gz https://downloads.apache.org/incubator/maka/0.2.0-incubating/apache-maka-0.2.0-incubating-src.tar.gz
curl -sSL -o maka-src.tar.gz.sha512 https://downloads.apache.org/incubator/maka/0.2.0-incubating/apache-maka-0.2.0-incubating-src.tar.gz.sha512

两条 curl 分别取源码包与其校验文件，-sSL 让下载过程静默但保留错误输出，异常时能立即看到 HTTP 状态。下载完成后先看文件大小是否符合预期再进入校验，异常小的包多半是下载中转侧的错误页而非源码。

3.2 SHA512 校验

cat maka-src.tar.gz.sha512
sha512sum maka-src.tar.gz

实测回显（两行值完全一致，校验通过）：

a436c581b029f8c5c1ba5f14cb1db14647bc0808f4a99da004797f20e72f67a30bc4888e04bda9028e474f0b7a2869325322b4751c0d7bcb1e3b29c678d81a21e  apache-maka-0.2.0-incubating-src.tar.gz
a436c581b029f8c5c1ba5f14cb1db14647bc0808f4a99da004797f20e72f67a30bc4888e04bda9028e474f0b7a2869325322b4751c0d7bcb1e3b29c678d81a21e  maka-src.tar.gz

两行摘要逐位一致即校验通过。这一步的价值在 agent 场景下被进一步放大：即将安装的软件会获得在你服务器上执行任意命令的授权（这是 agent 运行时的本职），源码包的完整性就是整个信任链的起点，跳过校验等于让后面所有的权限讨论建立在未验证的代码之上。孵化期项目的校验文件随源码包同目录发布，两者都从 downloads.apache.org 获取，不要从第三方渠道只下载源码包而放弃校验文件。

3.3 解压

tar -xzf maka-src.tar.gz
cd apache-maka-0.2.0-incubating
ls

实测目录列表：

DISCLAIMER-WIP  LICENSE  NOTICE  README.md  package.json  packages  patches  scripts  tsconfig.base.json  turbo.json

README 明确了运行要求（Node.js 22.19+、npm 11、git、ripgrep）与两条使用路径：一是直接使用 npm 上 maka-agent 包的 nightly 构建（npm i -g maka-agent@nightly），二是从本仓库源码构建（本文路径）。顶层目录里几个文件的身份值得先认清：DISCLAIMER-WIP 是孵化期项目的标配声明文件（提供警示说明，内容仍在完善），LICENSE 与 NOTICE 是 Apache 许可要件；package.json 是 monorepo 的根清单，workspaces 字段把 packages 下九个子包纳管；turbo.json 是 turbo 构建编排器的任务图配置，npm run build 实际按它声明的依赖关系调度各子包的构建顺序；patches 目录存放对第三方依赖的补丁，npm ci 时自动应用。粗看一遍这些文件，构建系统的工作方式就不再神秘：npm ci 按 lockfile 精确安装（含补丁），turbo 按任务图并行构建九个子包，产物各自落在子包的 dist 目录。

四、安装依赖与构建

4.1 安装依赖（npm ci）

npm ci

实测该步骤下载约 1.4GB 的 node_modules（monorepo 九个子包的全部依赖）。两点提示：

网络不畅时可配置下载加速或代理；
npm ci 会执行依赖包的 install 脚本，其中 Electron 会下载其平台二进制（约 120MB），是整个安装中最耗时的一步。实测日志中 Electron 下载完成后的关键回显：

electron@43.4.1 ✔
run@2.1.4 ✔
zod@4.6.5 ✔

若只使用 CLI 不需要桌面端，仍不建议跳过 Electron 安装（workspace 锁定版本，强行跳过会导致后续 install 脚本校验失败）。 npm ci 与 npm install 的差异在这里需要交代清楚：npm install 会解析 package.json 的版本范围并可能更新 lockfile，而 npm ci 严格按 package-lock.json 的锁定版本安装、先删后建 node_modules、且要求 lockfile 与 package.json 完全一致。对需要可复现构建的源码评估，npm ci 是唯一正确选择——它保证今天在这台服务器上装出的依赖树，与项目 CI 与其他评估者装出的完全相同。1.4GB 的体积主要是 Electron（跨平台二进制）、各类编译工具链与类型声明的总和，属于 monorepo 全量安装的正常水平。磁盘紧张时可用 du -sh node_modules 分解占用，但不要因此省略任何 workspace 成员的依赖，构建期的相互引用会因缺件而失败。

4.2 构建

npm run build

实测构建完成，退出码 0。构建产物为各子包 dist 目录下的编译输出，CLI 的开发入口为 packages/cli/dist/dev-cli.js。构建时长在分钟级，turbo 会并行调度无依赖关系的子包任务，日志里能看到各包的编译进度。若构建中断，重跑 npm run build 即可——turbo 按任务图增量执行，已完成且无变更的子包会被跳过。验证产物存在性用 ls packages/cli/dist/，dev-cli.js 在列即构建完整；个别子包构建失败时 turbo 会中止并打印失败任务名，按提示进入对应子包单独排查。

4.3 验证 CLI

node packages/cli/dist/dev-cli.js --version

实测回显：

0.2.0

node packages/cli/dist/dev-cli.js --help

实测回显（节选）：

npm run cli:dev -- <command> [options]

Commands:
  npm run cli:dev -- run [PROMPT]     Run a one-off task in the current workspace
  npm run cli:dev -- activate <path>  Open the current workspace in the desktop app
  npm run cli:dev -- session-import   Import a session from file
  npm run cli:dev -- eval             Run one declarative multi-arm experiment
  npm run cli:dev -- doctor           Check workspace health

为便于日常使用，建立软链：

ln -sf /opt/apache-maka-0.2.0-incubating/packages/cli/dist/dev-cli.js /usr/local/bin/maka

dev-cli.js 是带 shebang 的可执行脚本，软链名为 maka 与官方 CLI 命令一致，此后所有示例直接写 maka 命令。--help 回显的 Commands 列表同时透露了 CLI 的能力边界：run 是一次性任务执行，activate 把工作区交给桌面端，session-import 从文件导入会话，eval 跑声明式多臂实验，doctor 检查工作区健康度。这些命令共享同一个工作区概念，后文配置连接时的工作区目录对它们全部适用。

五、配置模型连接

5.1 理解连接的两种配置途径

Maka 的模型连接保存在工作区（用户配置目录下 Maka Dev profile 的 workspaces/default 目录）的 connection-catalog.json 与 credential-vault.json 两个文件中。官方推荐通过 CLI 交互向导（TUI 中的 /setup 流程）创建；对服务器/自动化场景，直接写入这两个 JSON 文档同样有效（文档格式有 schemaVersion 与严格校验，需按 5.3 节的字段构造）。两种途径的选择逻辑很直接：有交互终端、连接的是知名供应商（anthropic、openai 等内置类型），走 /setup 向导最省事，它会引导填 key、做模型发现并回写两个文件；无交互环境（SSH 脚本、流水线、纯 stub 验证）或要精确控制每个字段时，手工写文档更可靠——且手工路径顺带把存储格式摸了一遍，对后续排查配置类问题帮助极大。本文选手工路径的第三个理由是可复现：两份 JSON 原样落在文中，任何人在新环境里重放同样的步骤就能得到同样的配置状态，这是自动化部署 favourite 的属性。

先跑一次未配置状态（5.2 节）也是刻意安排：model_missing_default_connection 的报错确认了 CLI 本身可用、工作区初始化正常，把"配置问题"与"安装问题"清晰隔离——这一步失败了查安装，成功了再谈配置，排障的边界由此划定。

5.2 先体验"未配置"的真实报错

cd /opt/apache-maka-0.2.0-incubating
maka run "hello"

实测回显（安装后首次运行会先初始化工作区文件，然后因缺少连接而失败）：

maka run: missing a model connection: run `maka run` to configure a model provider

同时工作区目录已生成 runtime.sqlite 等初始文件：

ls "/root/.config/Maka Dev/workspaces/default/"

context-offload.sqlite  memory  memory.sqlite  runtime.sqlite

5.3 手工写入连接目录与凭证库

本指南以本地 stub 模型为例（零外部依赖，完整可复现）。先构造一个 OpenAI Chat 兼容的本地 stub 服务（见本系列实战篇的完整脚本，监听 127.0.0.1:18080），再写入连接配置。

生成 connection-catalog.json（注意 connectionId 必须是合法 UUID，slug 仅小写字母数字与连字符）： UUID 与 slug 的取值有真实的失败模式：UUID 格式错会触发 invalid_document 校验错误（含具体的校验路径），slug 含大写或下划线会被拒绝。需要随机 UUID 时用 uuidgen 命令生成即可；凭证条目的 locator.connectionId 必须与连接条目的 connectionId 逐字一致，两文件靠这个键关联。updatedAt 用毫秒时间戳，取当前时间即可（date +%s%3N 可生成）。

WS="/root/.config/Maka Dev/workspaces/default"
cat > "$WS/connection-catalog.json" << EOF
{
  "schemaVersion": 2,
  "revision": 1,
  "defaultTarget": {"connectionId": "11111111-2222-4333-8444-555555555555", "modelId": "stub-echo"},
  "connections": [
    {
      "connectionId": "11111111-2222-4333-8444-555555555555",
      "revision": 1,
      "slug": "stub-relay",
      "name": "Stub Relay",
      "providerType": "openai-compatible",
      "baseUrl": "http://127.0.0.1:18080/v1",
      "enabled": true,
      "enabledModelIds": ["stub-echo"],
      "models": []
    }
  ]
}
EOF

生成 credential-vault.json（openai-compatible 类型要求 api_key 凭证，stub 不校验密钥内容但格式必须合法）：

cat > "$WS/credential-vault.json" << EOF
{
  "schemaVersion": 1,
  "revision": 1,
  "entries": [
    {
      "locator": {"scope": "connection", "connectionId": "11111111-2222-4333-8444-555555555555", "kind": "api_key"},
      "credentialId": "66666666-7777-4888-8999-000000000000",
      "revision": 1,
      "secret": "sk-stub-local-0001",
      "updatedAt": 1760000000000
    }
  ]
}
EOF

启动 stub 服务：

mkdir -p /opt/maka-stub
node /opt/maka-stub/server.js &
curl -s -o /dev/null -w "stub:%{http_code}\n" -X POST http://127.0.0.1:18080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"stub-echo","stream":true,"messages":[{"role":"user","content":"hi"}]}'

实测回显：

stub:200

curl 验证的是 stub 服务对"流式 Chat 请求"的应答能力：请求体里 stream:true 模拟 Runtime 的真实调用方式，HTTP 200 表示端点与协议形态正确。这里必须强调流式的原因见 FAQ 第 5 条——Maka 固定以流式调用 OpenAI 兼容端点，非流式实现的服务每次调用都会以 stream_truncated 失败。stub 服务的完整实现（SSE 推送、工具调用参数透传）在实战篇给出，本文只把它当作一个可用的本地模型服务来消费。

5.4 运行第一个 agent 会话

cd /opt/apache-maka-0.2.0-incubating
maka run "List packages dir" --connection stub-relay --model stub-echo --yolo --timeout 80

实测回显（完整 agent 会话：模型回复 → Bash 工具调用 → 工具执行 → 结果回传 → 总结）：

The workspace contains 9 packages: cli, computer-use, core, eval, mcp, runtime, runtime-host, storage, ui.

该输出证明：连接配置生效、模型调用成功、工具真实执行（列出了 workspace 的 9 个子包目录）、工具结果回传模型并生成最终总结。把这句话拆开验证它的每个分句：连接配置生效——若 catalog 有误，报错会在启动阶段出现而不是拿到模型回答；模型调用成功——输出文本由 stub 服务返回、经 Runtime 解析而来；工具真实执行——9 个包名是 Bash 工具 ls packages 的真实结果，不是模型编造（模型无从知道本机目录内容）；结果回传——总结句式与目录清单吻合，说明模型看到了工具返回。一次 run 全链路走通，等价于完成了对 Maka 安装质量、连接配置、模型协议实现、工具执行通道的四重联测，这正是选 stub 方案做安装验证的用意。

5.5 从存储中验证会话记录

runtime.sqlite 记录了全部事件。用 Node 自带的 sqlite 模块快速查看（实验性 API）：

node -e "
const { DatabaseSync } = require('node:sqlite');
const db = new DatabaseSync('/root/.config/Maka Dev/workspaces/default/runtime.sqlite', { readOnly: true });
const ops = db.prepare('SELECT tool_name, current_state FROM tool_operations ORDER BY operation_id DESC LIMIT 1').all();
console.log(JSON.stringify(ops));
" 2>/dev/null

实测回显：

[{"tool_name":"Bash","current_state":"outcome_committed"}]

工具调用以 outcome_committed 终态落库，验证了 Maka"记录消息、工具调用与工具结果"的核心能力。存储层的验证不必止步于工具表，两条补充查询能看到更完整的图景。查事件流的种类分布：

node -e "
const { DatabaseSync } = require('node:sqlite');
const db = new DatabaseSync('/root/.config/Maka Dev/workspaces/default/runtime.sqlite', { readOnly: true });
const kinds = db.prepare('SELECT event_kind, COUNT(*) AS n FROM runtime_events GROUP BY event_kind ORDER BY n DESC').all();
console.log(JSON.stringify(kinds));
" 2>/dev/null

回显中应能看到 function_call、tool_dispatch、function_response、text、completed 等事件类别及各自条数——一次会话的事件构成一目了然。再查模型调用的用量记录：

node -e "
const { DatabaseSync } = require('node:sqlite');
const db = new DatabaseSync('/root/.config/Maka Dev/workspaces/default/runtime.sqlite', { readOnly: true });
const rows = db.prepare('SELECT connection_slug, model_id, status FROM usage_llm_calls ORDER BY call_id DESC LIMIT 3').all();
console.log(JSON.stringify(rows));
" 2>/dev/null

stub 会话的回显中 connection_slug 为 stub-relay、model_id 为 stub-echo、status 为成功状态。三张表对照着读：runtime_events 讲过程，tool_operations 讲工具终态，usage_llm_calls 讲调用量与结果——同一会话在三个视角下的投影全部可查，这就是 3.1 节所说的黑匣子能力的具体形态。

六、长驻进程与内存说明

Maka CLI 的 run/print 模式是短命进程，会话结束即退出，不适用 JVM 堆配置一类的问题；若将桌面端或 Runtime Host 作为长驻进程运行，可用 V8 的内存参数限制其堆上限，例如：

node --max-old-space-size=512 /opt/apache-maka-0.2.0-incubating/packages/cli/dist/dev-cli.js run "整理目录结构并输出清单"

512MB 上限对常规会话足够；若启用大上下文模型或 eval 并行任务，可按需上调。本地 stub 模型服务同样是一个 Node 进程，默认堆配置即可（实测会话峰值内存远低于 100MB）。补充 Node 内存模型的背景以正名：--max-old-space-size 限制的是 V8 老生代堆，Node 进程还有栈、外部缓冲区等不在此列的内存，该参数是实践中最常用的总量阀门。与 JVM 的 -Xmx 对照着理解即可：语义相近，但 V8 的堆结构不同，数值不需要对齐 Java 应用的经验值。512MB 这个量级的依据是：常规会话的上下文窗口在数十万 token 以内，事件库写入为流式小事务，实测单会话峰值远低于上限；把上限设得过低（如 128MB）反而会在长会话或大型工具输出回传时触发堆溢出。长驻进程还应配合系统层的内存监控，观察趋势比单点数值更有意义。

安装完成的标志可以概括为一条链：node --version 出 22.19.0（运行时就绪），sha512sum 比对一致（源码可信），dev-cli.js --version 出 0.2.0（构建成功），maka run 产出 "The workspace contains 9 packages"（agent 闭环走通），runtime.sqlite 中 tool_operations 出现 outcome_committed（记录能力落地）。把这五个检查点写进你的部署清单，任何一环缺失都能立即定位到对应章节回查。

七、卸载方式

按以下顺序完整移除：

# 1. 停止 stub 模型服务（如已启动）
pkill -f "node /opt/maka-stub"

# 2. 删除工作区数据（会话记录、连接、凭证）
rm -rf "/root/.config/Maka Dev"

# 3. 删除源码与构建产物
rm -rf /opt/apache-maka-0.2.0-incubating /opt/maka-src.tar.gz*

# 4. 删除 stub 与 Node.js
rm -rf /opt/maka-stub /opt/node /opt/node.tar.xz /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/maka

Maka 本身不向系统目录写入内容（工作区在用户配置目录、程序在自选目录），上述清理即回到安装前状态。验证卸载干净的方法：which maka 与 which node 应无输出（软链已删）；/root/.config/Maka Dev 不存在（工作区已清）；重新执行本文第二节起任一安装命令可以走通（环境无残留干扰）。注意卸载顺序中先停 stub 服务再删文件，避免删除过程中进程仍在写日志文件造成目录残留。若工作区中还有想保留的会话记录，先复制 runtime.sqlite 到别处再做清理——事件库是单文件，拷走即备份。

八、常见问题（FAQ）

1. npm ci 卡在 Electron 下载怎么办？ Electron 的平台二进制（约 120MB zip）从其发布渠道下载，网络不畅时耗时明显。可预先配置 ELECTRON_MIRROR 环境变量指向加速站点后重跑 npm ci；npm ci 支持断点重试，完成后 dist 目录即有二进制。

2. node --version 报 v18/v20，不是 22？ PATH 中存在旧版 Node（Ubuntu 22.04 源或 nvm 残留）。用 which node 定位，确保 /usr/local/bin/node 指向 /opt/node/bin/node，或干脆 export PATH=/opt/node/bin:$PATH 后再操作。

3. maka run 报 missing a model connection？ 正常现象：新工作区没有任何连接。按第五节配置连接（TUI 向导或手工写文档）后重试。

4. 手工写的 connection-catalog.json 被报 invalid_document？ 逐项核对：schemaVersion 必须是 2；connectionId/credentialId 必须是标准 UUID 格式；slug 只能小写字母数字连字符；baseUrl 必须是合法 http/https URL 且不含用户名密码、查询串；entries/connections 必须是数组。任何一项不符都会被严格校验拒绝。

5. 会话一直超时（timed out），模型服务返回了内容？ Maka 默认以流式（stream=true）调用 OpenAI 兼容端点。若自建服务不支持 SSE 流式响应，每次调用都以 stream_truncated 失败（可在 runtime.sqlite 的 usage_model_call_attempts 表中看到该错误分类），CLI 表现为反复重试直至超时。自建端点必须实现 SSE：按 data: JSON 行推送增量并以 data: [DONE] 结束。这个坑的隐蔽性在于：非流式实现往往能通过普通 curl 测试（返回完整 JSON），却在 Runtime 真实调用时失败——差异就在 Runtime 请求里的 stream:true。诊断方法是从 usage_model_call_attempts 表读 error_class 字段，stream_truncated 即为此因。修复方向只有一条：服务端按 SSE 规范输出（Content-Type: text/event-stream，增量以 data: 行推送，结束以 data: [DONE]），实战篇的 stub 脚本就是按此实现的最小参考。

6. 工具调用报 Unrecognized key？ Bash 工具的参数仅接受 command、timeout_ms、run_in_background、pty 四个键。这是 Maka 的严格参数校验：模型返回的多余键（如 OpenAI 风格的 description）会被整体拒绝。自建模型服务返回的 arguments 必须与工具 schema 完全一致。

7. 可以不构建源码、直接用 npm 包吗？ 可以：npm i -g maka-agent@nightly 后即有 maka 命令。但 nightly 是跟随主干的滚动构建，版本可能与源码包不一致；要做版本锁定的评估，建议如本文用源码构建。

8. ripgrep 没装会怎样？ Runtime 的 Grep 工具在执行时才报找不到 rg 命令。装 ripgrep 是系统准备步骤的一部分，务必在首次运行前完成。

9. 工作区能搬到别的目录或别的用户吗？ 工作区路径由用户配置目录（root 用户为 /root/.config/Maka Dev）派生。搬迁时整体复制目录并保持文件名不变即可；跨用户搬迁需注意文件属主与权限。

10. 如何确认安装的版本？ maka --version 实测回显 0.2.0，与源码包根 package.json 的 version 字段一致；源码包本体通过 SHA512 与官方 .sha512 文件比对校验（3.2 节）。

11. 构建报 node-gyp 或编译错误？ 某些依赖含原生模块，需要 build-essential 与 python3-is-python3 环境。Ubuntu 22.04 默认 python3 指向 3.10 可满足 node-gyp 的需求；确保 build-essential 已安装即可。

12. 升级到下一个 incubating 版本要注意什么？ 先备份工作区目录。连接目录与凭证库有 schemaVersion 迁移机制，通常能自动升级；runtime.sqlite 结构若变化，新版本会执行 operational_schema_migrations 中的迁移。孵化期版本建议以新工作区重新验证后再迁移数据。

13. stub 模型方案能用于日常开发吗？ stub 的定位是安装验证与协议测试：它证明 Maka 的调用链路通畅、协议实现正确。日常使用请接真实模型（云端 API、中转服务或本地推理均可），stub 不具备语言理解能力，只会按脚本回显。需要离线环境时，用 ollama 类本地推理服务替代 stub，连接类型选 ollama 或 openai-compatible 指向其兼容端点。

14. --yolo 参数到底放开多少权限？ 它跳过工具执行的确认环节，任务期间模型可直接读写文件与访问网络。评估场景（本指南）任务目标单一、目录边界清晰，可以接受；日常使用建议保持默认确认模式，把高危操作的放行权留在人工手里。无论哪种模式，所有工具调用都会完整落库，事后可审计。

九、参考链接

Apache 孵化器项目页（Maka）：https://incubator.apache.org/projects/maka.html
0.2.0-incubating 源码包：https://downloads.apache.org/incubator/maka/0.2.0-incubating/apache-maka-0.2.0-incubating-src.tar.gz
SHA512 校验文件：https://downloads.apache.org/incubator/maka/0.2.0-incubating/apache-maka-0.2.0-incubating-src.tar.gz.sha512
源码仓库：https://github.com/apache/maka
npm 包页（maka-agent）：https://www.npmjs.com/package/maka-agent
Node.js v22.19.0 发行页：https://nodejs.org/dist/v22.19.0/
ripgrep 安装文档：https://github.com/BurntSushi/ripgrep#installation
OpenAI Chat Completions API 参考（兼容端点协议）：https://platform.openai.com/docs/api-reference/chat