MELRA

MELRA

Modular Execution Layer for Reliable Autonomy

AI Agent 决定要做什么。MELRA 管控工具调用的授权、验证与恢复方式。

一款开源的本地执行运行时，用于处理经由 MELRA 路由的 Agent 工具调用。 它会根据策略检查每次调用，在需要时请求批准，验证声明的 证据，并记录从执行到结果的脱敏回执。对于每项任务，MELRA 最多只会分发一次变更操作；结果不确定时，会暂存以供协调， 而不是重新执行。外部效果能否恰好执行一次，仍取决于服务提供方。通过 其他工具发出的调用不受 MELRA 控制。

兼容  

26 秒演示  ·  快速开始  ·  工作原理  ·  查看运行内容  ·  文档  ·  参与贡献  ·  讨论  ·  Product Hunt 发布

26 秒演示

https://github.com/user-attachments/assets/e5cf895d-7ea6-4797-a1ef-e69cc5860d3f

警告

MELRA 是 alpha 软件。 本地运行时已通过端到端测试，但 API 可能会在 1.0 之前发生变化。请使用隔离的工作区，严格限制域名和命令允许列表， 并在批准每项请求前仔细阅读。

快速开始

你需要 Node.js 22.13 或更高版本，或 23.4 或更高版本。在 Agent 要工作的项目中，只需一条命令即可完成所有设置：

cd ~/project
npx @melra/cli@alpha setup

该目录将成为 Agent 的工作区，也是其文件和命令操作的边界。setup 会显示该目录；如果要将你的主目录、包含主目录的目录或 / 设为工作区，则会先征求你的同意；设置 MELRA_WORKSPACE 可选择其他目录。

在终端中，setup 是一个简短的向导。它会写入安全的本地策略，查找你机器上的 Agent 应用，询问你要让哪个应用使用 MELRA，并将 MELRA 写入该应用自己的配置文件，同时保留其中的其他内容（并先保存一个 .bak 文件）：

Which MCP client should use MELRA?

  1)   Claude Code                      detected: 'claude' on PATH
  2)   Cursor                           detected: config file found
  3)   Gemini CLI                       detected: config folder found
  ...

Choose 1-26 [1]: 1
Write it into ~/project/.mcp.json? [Y/n]

  ✓  Workspace    ~/project
  ✓  Policy       ~/.melra/policy.json
  ✓  Claude Code  ~/project/.mcp.json

Next: Start claude in this workspace and approve the 'melra' server when it asks; 'claude mcp list' then shows it connected.

然后重启你的 Agent 应用（Claude Code 会要求你批准一次项目服务），并让它做点什么，例如 “使用 melra 向我展示系统信息”。就这么简单。

注意

本项目仅通过 @melra/ npm 作用域（@melra/cli 是命令行工具）以及其发行版发布，Python SDK 的 wheel 也在其中。不带作用域的 npm 包 melra 或 PyPI 包 melra 并非本项目的包。请从该作用域、本仓库或发行版安装。

如果 MELRA 对你有帮助，请为仓库加星，让其他 Agent 构建者也能找到它。正在 Cursor 或其他客户端中试用？请在 issue #184 中分享客户端及其版本、你的操作系统和 MELRA 版本（npx @melra/cli@alpha version）；部分测试结果也很有用。

什么是 MELRA？

AI Agent 不再只是对话。它们会代表你编辑文件、运行命令、浏览网站并调用 API。这带来了四个问题，而大多数 Agent 对这些问题的回答各不相同，甚至完全没有回答：

对于通过 MELRA 路由的工具调用，无论使用哪种受支持的 Agent，MELRA 都会集中回答这些问题。对于这些调用，它位于你的 Agent 之下，就像操作系统位于应用之下：

**大模型负责推理。运行框架负责管理循环。MELRA 管控经由它路由的调用的效果生命周期。**更换模型或 Agent 时，MELRA 的策略、审批、凭据、历史记录和操作凭据仍可保留。

适用于你的 Agent

MELRA 使用 Model Context Protocol，因此任何 MCP 客户端都可以使用它。对于以下客户端，melra setup --client <name> 会按客户端自身的格式和位置写入配置，而 melra doctor 会告知每个客户端是否已指向 MELRA：

Agent	--client	写入的配置
Claude Code	claude-code	<project>/.mcp.json
Claude Desktop	claude-desktop	claude_desktop_config.json
OpenAI Codex CLI	codex	~/.codex/config.toml
Cursor	cursor	~/.cursor/mcp.json
🟦 VS Code（Copilot Agent 模式）	vscode	<project>/.vscode/mcp.json
Gemini CLI	gemini	~/.gemini/settings.json
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Zed	zed	Zed settings.json（保留注释）
🧩 Cline	cline	Cline 的 cline_mcp_settings.json
⬛ OpenCode	opencode	~/.config/opencode/opencode.json
👻 Kiro	kiro	~/.kiro/settings/mcp.json
🪿 Goose	goose	~/.config/goose/config.yaml
▶️ Continue	continue	<project>/.continue/mcpServers/melra.yaml
⚡ Amp	amp	~/.config/amp/settings.json
🦞 OpenClaw	openclaw	~/.openclaw/openclaw.json（mcp.servers）
⚕️ Hermes Agent（Nous Research）	hermes	~/.hermes/config.yaml（mcp_servers）
GitHub Copilot CLI	copilot	~/.copilot/mcp-config.json
🐉 Qwen Code	qwen	~/.qwen/settings.json
🅰️ Auggie（Augment）	auggie	~/.augment/settings.json
Warp	warp	~/.warp/.mcp.json
Junie（JetBrains）	junie	~/.junie/mcp/mcp.json
🤖 Factory Droid	droid	~/.factory/mcp.json
🌙 Kimi Code	kimi	~/.kimi-code/mcp.json
🪁 Kilo Code	kilo	~/.config/kilo/kilo.jsonc（保留注释）
🧪 LM Studio	lmstudio	~/.lmstudio/mcp.json
🔌 其他客户端	generic	输出标准的 mcpServers 块

正在构建自己的 Agent？请使用 TypeScript SDK 或 Python SDK。两者都可以启动 MELRA，也可以通过回环 HTTP 或私有 Unix 套接字连接到已运行的 MELRA。有关 Agent 框架，请参阅 框架示例：LangChain / LangGraph、 OpenAI Agents SDK、Vercel AI SDK，以及官方 MCP SDK。

说明

只有在指定客户端中通过发现、规划、审批、执行、取消和回执检索测试的 已发布软件包（而非源码检出版本），才会将对应的命名客户端标记为已验证。各客户端的状态见 COMPATIBILITY.md。

工作原理

效果是 Agent 通过 MELRA 路由的一项有界操作：file.write、 terminal.run、browser.click、http.request 等。MELRA 会分九个阶段处理每项路由 的效果，这些阶段分布在计划步骤和执行步骤中（对于单个任务，先执行 melra_plan， 再执行 melra_execute），因此规划时不会运行任何操作：

以下是在开发者模式下，一个变更从头到尾的完整流程。在 强制模式下，挑战不包含短语：你在对话之外通过 melra approve <task-id> 批准，Agent 的 melra_execute 不会发送任何审批内容。

sequenceDiagram
    autonumber
    participant A as Your agent
    participant M as MELRA
    participant You
    participant W as Your system
    A->>M: melra_plan: write notes.md, evidence "file contains 'done'"
    M->>M: type, classify, check policy, record
    M-->>A: awaiting_approval + challenge "APPROVE 3f9c…"
    A->>You: May I write notes.md?
    You-->>A: yes
    A->>M: melra_execute with the exact phrase
    M->>M: policy again, not already done?
    M->>W: write the file (under a budget)
    M->>W: read it back, independently
    M-->>A: verified_success + receipt

最终状态的含义以及 Agent 接下来应采取的操作：

{
  "goal": "Run the repository checks",
  "operation": { "kind": "terminal", "action": "run", "command": "pnpm", "args": ["check"] },
  "requiredEvidence": [{ "type": "exit_code", "value": 0 }]
}

Agent 连接时，MELRA 还会向它发送一份关于此循环的简短指南（即 MCP 服务的 instructions），让模型知道要声明证据、读取状态，并且绝不盲目重试结果未知的操作，而无需任何人对其进行提示词工程。

查看它的运行情况

你可以通过终端或浏览器查看 MELRA 处理的每个操作及其策略决策；对于每个运行并产生结果的操作，还可以查看其证据和回执。这里的任何内容都无法批准或启动工作，也不会显示批准语句。

在终端中 $ melra status MELRA 0.3.0-alpha.19 developer mode Tasks 3 total: 1 awaiting_approval, 1 policy_blocked, 1 verified_success Waiting 1 waiting for approval HTTP 127.0.0.1:7457 not running $ melra tasks ID STATUS OPERATION UPDATED 64199678 awaiting_approval file.write 0s ago ca4aec7a policy_blocked terminal.run 1s ago a1285e0f verified_success system.info 1s ago $ melra watch # live, until Ctrl-C 6:07:21 PM task 882cf55c verified_success 6:07:22 PM task f813364c awaiting_approval melra doctor 会检查 Node、SQLite、浏览器和策略，并报告哪些 Agent 应用已指向 MELRA，以及用于修复问题的一条命令。

在浏览器中： melra serve --http --open 概览、可搜索的任务列表，以及带实时事件流的持久工作流。 它适配手机屏幕宽度，支持浅色和深色模式，并通过严格的 Content-Security-Policy 提供服务。

默认安全

为什么选择 MELRA

大模型决定做什么。执行框架运行循环，让它实现目标。仍然需要有机制判断产生的效果是否获准，避免重放结果不确定的变更，证明发生了什么，并在中途崩溃后恢复。如今，这套机制在每个 Agent 执行框架中都要重新构建，而且会随执行框架一起消失。MELRA 将这套机制拆分出来，使其独立于 Agent。

与最常被混淆的另外两个层相比：

许多 MCP 服务可以做到这些；这并不是说它们都做不到。不同之处在于，在 MELRA 中，这些是执行契约的一部分，而不是每个工具可选的功能。该边界部分已交付：MELRA_MODE=enforced 会关闭 MELRA 所控制的所有入口，但要通过操作人员构建的 OS 隔离，才能阻止执行框架绕过内核访问文件系统；可运行的强化部署方案仍在规划中（#52）。

功能归属判断。 如果请求来自普通的确定性软件，某项功能仍然有意义，那么它就属于 MELRA：授权、幂等性、凭据隔离、恢复、验证、效果历史记录。提示词优化、大模型记忆、模型选择、规划器和 Agent 个性则属于上层的执行框架。这就是为什么 MELRA 的执行路径中从不调用模型。

它能做什么

效果适配器

内核是契约；这些是随附的实现。每个实现都会经过相同的策略、审批、预算、验证、回执和证书流程；跳过该流程的适配器就不算适配器。

数据库、云和 SaaS 适配器已完成设计，并列入路线图，目前尚未随附。关于用户的语义记忆（偏好、对话历史）属于 harness，而非这里。

精简而有意为之的工具接口

适配器前有 12 个工具，还有一个持久化工作流控制器。CLI、两个 SDK、环回 HTTP 和 Unix 套接字都可访问相同的 12 项操作；此列表定义的是内核契约，而非 MCP 专属 API。

判定结果会按声明记录评判者，证书也会将其与回执中声明的主体 executedBy 一并记录。通过 MCP 时，即使评判者是 human:，也只是 harness 的声明；只有通过操作界面执行 melra judge 得出的 cli: 评判者才不属于此类声明。

更喜欢使用模型已熟悉的工具名称？设置 MELRA_HARNESS_TOOLS=1，即可在这些工具旁再显示 13 个工具（read_file、write_file、run_command、browser_click、approve 等）。它们并非另一条执行路径：每个工具都会创建普通任务并运行相同的流程。参见普通工具名称。

持久化、可安全重启的工作流

工作流由 operation、approval、condition、parallel、bounded_loop、 checkpoint、compensation、human_input 和 delegation 节点组成，每项操作 仍会通过任务流水线。以下每次 CLI 调用都会启动一个新进程，因此无需守护进程即可 测试重启持久化：

melra workflow plan --definition examples/workflows/restart-safe.json   # save the id
melra workflow advance <workflow-id>
melra workflow advance <workflow-id>          # exits 3 with the write's approval challenge
# developer mode echoes the phrase; enforced mode runs `melra approve <task-id>` instead
melra workflow advance <workflow-id> --approval '<approval-id>:<exact phrase>'
melra workflow advance <workflow-id>

planned            stateVersion=2
running            stateVersion=4   inspect=verified_complete
awaiting_approval  stateVersion=6   phrase="APPROVE <digest prefix>"   (developer mode)
running            stateVersion=8   write=verified_complete
verified_complete  stateVersion=11  checkpoint=verified_complete

在任意一行之后停止进程，下一条命令都会从同一个 MELRA_HOME 恢复。中断的读取可能会重试；中断的变更绝不会被悄然 重复执行。系统会通过重新观察来处理这些变更，否则会将其置于 recovery_required 状态。

workflow advance 和 resume 在运行正常时退出代码为 0，等待审批时为 3，等待 --input 时为 4，运行失败、以 partially_complete 或 cancelled 结束，或需要恢复时为 2。workflow plan、pause 和 suspend 在规划或暂停 运行时退出代码为 0；拒绝暂停或挂起已完成、已取消或已失败的运行。workflow inspect 在任何状态下都退出代码为 0。workflow cancel 在将运行置于 cancelled 状态时 退出代码为 0，未能置于该状态时退出代码为 1，例如运行已完成。错误退出代码为 1。

证据与基准测试

数据来自已提交的脚本和 JSON 文件，并注明了数据集哈希和声明范围。这些是组件测量结果，并不表示 MELRA 是“最佳”，也不表示不同基准之间可以比较。

原始文件：核心微基准测试、 LoCoMo 和 GovBench。

仓库还包含一个预注册的浏览器 Agent 测试框架（MiniWoB-125 和 WebArena-Verified Hard-30 注册子集），其任务 ID、上游修订版本和数据集哈希均已冻结。目前尚未公布其得分：只有通过发布门槛并完成固定分母的完整运行后，才会公布。MELRA 尚未提交 OSWorld、WebArena 或 LongMemEval 的官方评测。

# the full validation gate
pnpm check && pnpm evals && pnpm e2e && pnpm pack:check && pnpm security:audit
pnpm --filter @melra/evals evaluate:durable-core -- --publishable

# memory, browser, terminal and computer microbenchmarks
pnpm benchmark:core

# governance benchmark: 362 model-free cases, loopback fixtures only
pnpm benchmark:govbench

# LoCoMo (dataset not vendored: CC BY-NC 4.0)
git clone https://github.com/snap-research/locomo.git /tmp/locomo
pnpm benchmark:locomo -- --dataset /tmp/locomo/data/locomo10.json \
  --output docs/research/results/locomo-retrieval.json

# browser-agent harness contract checks (no model, no network)
pnpm benchmark:browser:check
pnpm benchmark:browser:verify-upstream

# hardened container and a real MCP smoke test
docker build -t melra:local . && docker run --rm melra:local doctor && pnpm docker:smoke

面向开发者

SDK 包 TypeScript @melra/sdk Python melra（带类型，3.11–3.14） 📜 JSON 合约 @melra/protocol, @melra/receipt-schema 两个 SDK 都可以启动本地服务，也可以通过 HTTP 或 Unix 套接字连接到正在运行的服务。 令牌始终需要显式传入；除非选择启用，否则不允许通过纯 HTTP 连接远程主机。

CLI 一览 目标 命令 引导式设置 melra setup 检查此计算机 melra doctor 提供服务（stdio / HTTP / 套接字） melra serve · --http --open · --socket <path> 查看活动 melra tasks · watch · status 运行一项任务 melra run --request task.json 批准 Agent 规划的任务 melra approve <task-id> · 在浏览器中使用：melra console 回答任务的语义问题 melra judge <task-id> --judgement <id> --verdict yes|no|cannot_tell 检查回执 melra inspect <task-id> 测试策略 melra policy test --request task.json 检查一致性 melra conformance

apps/cli/                   CLI and stdio entrypoint

kernel services
packages/protocol/          strict task, workflow, event and operation schemas
packages/runtime-core/      task/workflow lifecycle, events, recovery
packages/policy-core/       local policy and scoped approvals
packages/storage-sqlite/    transactional tasks, workflows, events, evidence
packages/verifier-core/     deterministic evidence predicates
packages/receipt-schema/    receipts and execution certificates
packages/memory/            operational memory: scoped retrieval and lifecycle
packages/server/            runtime composition, MCP, loopback HTTP and Unix socket

reference effect adapters
packages/file-runtime/      confined filesystem operations
packages/terminal-runtime/  shell-free process supervision
packages/browser-runtime/   isolated browser automation and stable-DOM wait
packages/computer-runtime/  governed local computer-use adapters
packages/http-runtime/      governed HTTP and API calls

clients and evidence
packages/sdk-ts/            TypeScript client SDK
sdk-py/                     Python client SDK
benchmarks/browser-agent/   pre-registered browser-agent evaluation harness
evals/                      safety and durable crash-recovery evaluations
scripts/                    benchmark and release checks
docs/research/              methods, findings and raw results
examples/                   runnable task examples

可运行的示例涵盖只读系统任务、经过验证的文件写入、终端检查、浏览器检查、限定范围的记忆、计算机能力发现、受治理的 API 调用、独立验证以及可安全重启的工作流。

文档

贡献

欢迎提交代码、适配器、客户端集成、基准测试工具、验证谓词、文档和威胁分析。

1. 阅读 CONTRIBUTING.md 和行为准则。
2. 根据 DCO 签署提交（git commit -s）。
3. 发起拉取请求前运行 pnpm check；它还会检查链接、环境变量表和 CHANGELOG 格式。
4. 通过私密漏洞报告报告漏洞， 切勿在公开问题中报告。

许可证

软件和文档根据 Apache License 2.0 授权。官方徽标和主视觉插图根据 CC BY-ND 4.0 授权。第三方基准测试数据集保留其 各自的许可证，且不包含在此代码库中。