Skip to content

README.zh-CN.md

Latest commit

 

History

History
229 lines (167 loc) · 8.9 KB

README.zh-CN.md

File metadata and controls

229 lines (167 loc) · 8.9 KB
Raw

Apache Maka（孵化中）CLI

English

Maka 是一个本地优先的 Agent 工作空间。maka-agent npm 包包含交互式终端界面、非交互 CLI、Runtime Host 工具和 Eval 命令。

Apache 孵化免责声明

Apache Maka 正在 Apache Software Foundation 孵化。发布到 npm 的英文 README 会直接从 release commit 中的 DISCLAIMER-WIP 注入权威的完整 work-in-progress disclaimer；当前状态另见 Maka podling 状态页。本段仅为中文说明， 英文免责声明以随包发布的 DISCLAIMER-WIP 为准。

**Beta：**CLI 仍在积极开发中，稳定版发布前，命令和本地数据格式可能发生变化。

环境要求

  • Node.js 22.19.0 或更高版本；
  • 使用 TUI 时需要支持交互输入的终端；
  • 执行 Agent Turn 时需要已经配置的模型连接；首次设置目前支持使用 API Key 的供应商。

发布门禁会验证以下安装态矩阵：

平台 架构 Node.js TUI、CLI、Runtime Host 真实 Harbor/Pier Eval
Linux x64 22.19 已验证 仅验证 preflight
Linux x64 24 已验证 已验证
Linux arm64 24 已验证 仅验证 preflight
macOS arm64 24 已验证 仅验证 preflight
Windows x64 24 已验证 仅验证 preflight

满足 Node.js 最低版本的其他组合也可能可用，但不属于当前发布门禁。真实 Eval executor 目前只在 Linux x64 和 Node.js 24 上验证。

安装

Beta 阶段请明确从 next dist-tag 安装：

npm install --global maka-agent@next
maka --version
maka --help

公开命令只有 maka。一次性运行请使用 npx --yes --package maka-agent@next maka；npm 上与本项目 无关的 maka 包不是本项目。runtime-host service install 使用上面的持久全局安装； runtime-host setup 会从 npx 调用的精确 package 创建自己的托管副本。

第一次运行

进入希望 Agent 工作的项目目录，然后启动 Maka：

cd path/to/project
maka

如果还没有模型连接，Maka 会自动打开供应商设置流程。选择供应商、输入 API Key、选择要 启用的模型并保存。之后可以运行 /setup 添加或更新供应商，使用 /model 切换模型。

API Key 和工作空间状态保存在本机的 Maka profile 中。当前 credential vault 是受操作系统 账号边界保护的本地明文文件；在 POSIX 系统上，Maka 会强制使用仅 owner 可访问的目录和文件 权限。它不是操作系统 Keychain。当前边界详见仓库的 安全策略。

执行一次非交互 Turn：

maka run "总结这个项目并指出风险最高的部分"
maka run --help

Maka 默认会在执行高权限工具操作前询问。maka run --yolo 会授予该任务完整的文件和网络 权限，只应在你允许任务修改的环境中使用。

升级

使用预发布版本时，请继续明确指定 next：

maka update --target next
maka --version

更新流程会先 stage 并验证精确 release，再替换本地 Runtime Host 与 npm-global package； 默认不会中断 active 或 durable work。只有在你确认可以安全中断后，才使用 --allow-interrupt-active-tasks。npm install --global maka-agent@next 仍可用于修复安装； 不要使用不带 tag 的 npm update --global maka-agent，因为它会跟随 latest，可能选中 不同的发布线。稳定版发布后，使用 maka update --target latest。

设置远程 Runtime Host

在 Linux 或 macOS 上从精确的发布 package 设置持久 remote Runtime Host：

npx --yes --package maka-agent@next maka runtime-host setup \
  --principal my-client \
  --preset terminal-client

重复设置会替换该 Client credential。设置成功后，service 不再依赖临时 npx cache。

可以在不改变当前 Host 的情况下检查 managed service 对应的发布频道：

maka runtime-host service check-update --target next --json

结果会把频道固定为精确版本和 package integrity，并说明 package 是否提供足够的兼容性证据， 可供无人值守流程使用；该命令不会安装或切换 package。安装管理方可以把同一 selector 传给 service update --target。该路径会先校验 archive 与解包后的 manifest，再委托给 现有的精确 package 更新事务；需要人工审查的候选不会改变当前 Host。

Installation owner 可以持久化一个更新目标，并通过同一套已验证事务执行 reconciliation：

maka runtime-host service update-policy --target latest \
  --expected-service-id <service-id> \
  --expected-root-path <state-root> \
  --expected-root-id <root-id>
maka runtime-host service reconcile-update --json

使用 update-policy --target manual 关闭自动 reconciliation。Reconciliation 是有界的单次命令： 它不会中断 active work，也不会安装 scheduler。

卸载

# 仅限安装过 managed Runtime Host service 的 Linux 或 macOS
npx --yes --package maka-agent@next maka runtime-host service uninstall

# 如果曾全局安装 Maka
npm uninstall --global maka-agent

先删除 managed service，再卸载 npm 包，避免 OS service manager 留下指向已删除 CLI 的 service。这两个命令都不会删除模型连接、凭证、会话或 Artifact。它们仍保留在发布版 CLI 与 Desktop 共用的 profile 中：

平台 Profile 目录
macOS ~/Library/Application Support/Maka
Linux $XDG_CONFIG_HOME/Maka；未设置时为 ~/.config/Maka
Windows %APPDATA%\Maka

只有在确实要删除全部本地 Maka 数据时，才应单独备份并删除该目录。操作前先关闭 CLI 和 Desktop 应用。

Eval

运行声明式实验：

maka eval run experiment.json --out .maka-eval/run-001

npm 包包含 Maka 自有的 Eval runtime、relay、wrapper 和容器策略资源，但不会安装 executor 所需的外部软件或机器本地 benchmark 数据。Eval 会在启动任何 trial 前检查 spec 声明的精确 前置条件；缺少任意一项时会在不运行 cell 的情况下失败。

运行基于 Docker 的 Harbor 或 Pier spec 时，需要提供：

  • 可访问的 Docker CLI 和 daemon；
  • 包含 executor.config.frameworkVersion 所声明精确版本的独立 Python 环境；
  • 通过 pythonPathEnv 所命名的环境变量提供可执行的解释器；
  • 通过 trialsRootEnv 提供可写的 trial 目录；
  • Pier 还需要通过 tasksRootEnv 提供 task 目录；
  • spec 声明的所有机器路径和 subject 凭证环境变量。

Harbor 和 Pier 必须使用不同的 Python 环境。当前验证过的版本为：

python3.12 -m venv ~/.venvs/maka-harbor-0.20.0
~/.venvs/maka-harbor-0.20.0/bin/python -m pip install 'harbor==0.20.0'

python3.12 -m venv ~/.venvs/maka-pier-0.3.0
~/.venvs/maka-pier-0.3.0/bin/python -m pip install 'datacurve-pier==0.3.0'

把 spec 的 pythonPathEnv 指向相应的 bin/python。不要让两个 framework 复用一个环境： 它们的依赖和 trial contract 不同。高级实验和 toolchain 说明位于 Eval 文档。

故障排查

先记录实际安装版本：

node --version
npm --version
maka --version
  • 全局安装后找不到 maka 时，确认 npm 的全局可执行目录已经加入 PATH；
  • 没有可用模型时，启动 TUI 并运行 /setup；
  • Eval 拒绝启动时，根据错误中给出的环境变量名和预期 framework 版本修复环境；Eval 不会 自动安装或静默替换缺失的前置条件；
  • 报告问题时，请提供以上三个版本、操作系统和架构、执行的命令，以及移除凭证后的完整 错误信息。

请在 https://github.com/apache/maka/issues 报告问题。

链接