mailz (Byteowlz)

梅尔兹

通过带有CLI、TUI、MCP和HTTP API接口的邮件式消息传递进行代理协调。

深受启发 mcp_agent_mail 杰弗里·伊曼纽尔著。

概述

mailz将轻量级、可审计的协调数据保存在本地SQLite数据库中。代理人可以发送 消息、请求确认和保留文件以避免冲突。操作员可以管理 项目和代理，并通过HTTP API或MCP进行集成。

安装

从源代码构建：

cargo build --release

快速开始

初始化配置并注册代理：

cargo run -p mailz-cli -- init
cargo run -p mailz-cli -- project create /path/to/repo --name repo
cargo run -p mailz-cli -- agent register repo --name "AgentA" --program "cli" --model "gpt"

发送邮件并查看收件箱：

cargo run -p mailz-cli -- send repo --from AgentA --to AgentB --subject "Heads up" --body "Working on parser."
cargo run -p mailz-cli -- inbox repo --agent AgentB

启动TUI：

cargo run -p mailz-tui

启动API服务器：

cargo run -p mailz-api -- --port 3000

启动MCP服务器：

cargo run -p mailz-mcp

CLI示例

注册代理并发送消息：

cargo run -p mailz-cli -- agent register repo --name "AgentB" --program "cursor" --model "gpt"
cargo run -p mailz-cli -- send repo --from AgentA --to AgentB --subject "Review" --body "Please review parser changes."

保留文件以进行协调编辑：

cargo run -p mailz-cli -- reserve repo --agent AgentA src/parser.rs --ttl 1200 --reason "Refactor"
cargo run -p mailz-cli -- reservations repo

注意新消息：

cargo run -p mailz-cli -- watch
cargo run -p mailz-cli -- daemon start
cargo run -p mailz-cli -- daemon status
cargo run -p mailz-cli -- daemon stop

TUI基础知识

• j/k 或导航箭头， c 为了作曲， t 对于预订， g 对于目录。
• / 搜索收件箱， r 为了切换读取， a 承认。
• 目录视图显示项目（切换选项卡）和具有未读/总计数的代理。

API示例

管理终结点需要管理员密钥。集 api.admin_key 在配置或读取auto 从状态目录生成密钥。

创建项目和代理：

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/path/to/repo","name":"repo"}' \
  http://localhost:3000/projects

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"AgentA","program":"api","model":"gpt"}' \
  http://localhost:3000/projects/1/agents

发出代理密钥并使用它来读取收件箱：

curl -H "X-API-Key: $MAILZ_ADMIN_KEY" http://localhost:3000/agents/1/keys

curl -H "X-API-Key: $MAILZ_AGENT_KEY" http://localhost:3000/agents/1/inbox

连接到WebSocket更新（需要 websocat):

websocat -H "X-API-Key: $MAILZ_AGENT_KEY" \
  ws://localhost:3000/ws/1

MCP示例

运行MCP服务器并调用以下工具：

• ensure_project
• register_agent
• send_message
• fetch_inbox
• reserve_files

配置参考

默认配置路径： $XDG_CONFIG_HOME/mailz/config.toml

关键部分（见 examples/config.toml):

• logging.level, logging.file
• runtime.parallelism, runtime.timeout, runtime.fail_fast
• paths.data_dir, paths.state_dir
• maintenance.gc_interval_seconds, maintenance.message_retention_days
• api.admin_key, api.rate_limit_per_minute
• tui.poll_interval_seconds
• watch.poll_interval_seconds

代理协调模式

• 每个仓库/工作区创建一个项目，并注册每个代理/工具一次。
• 使用 reserve 在编辑共享文件之前；完成后释放。
• 标记已读/确认重要邮件，以保持收件箱整洁。
• 使用螺纹(thread_id)与小组相关的讨论。
• 在CLI、API和MCP之间保持代理名称的一致性，以获得清晰的审核跟踪。