使用说明

代理通信系统

一个MCP（模型上下文协议）服务器，促进AI代理之间的本地通信。此服务器使多个Claude实例或其他LLM工具能够通过简单的基于文件的存储系统交换消息，从而消除了在不同代理终端之间手动复制粘贴的需要。

📚 快速入门指南 | 📖 使用示例

🔔 v2.2.0的新增功能

版本2.2增加了 便携式输送层 所以收件人会得到 已ping 检查它邮箱--不需要守护进程：

一键式命令行界面: agent-comm-system unread|peek|next <agent> --查询或清空邮箱不用说MCP（用于钩子和脚本）。 AGENT_COMM_STORAGE 覆盖位置。
克劳德代码停止挂钩 (hooks/mailbox-stop-hook.mjs)：当代理完成转弯时，它被告知要通过以下方式清除所有未读邮件 receive_next无损，回路安全。看交付：闲置时ping.

📬 v2.1.0的新增功能

2.1版本将每个代理的存储转化为真正的FIFO 邮箱队列 加上一个可选输送钩：

receive_next：将最年长的人排出来未读消息并标记为已读（排空a 邮箱作为队列）； peek: true 看而不消费。
unread_count：有多少消息正在等待代理。
ack：确认+删除已处理的消息。
在发送挂钩上发射：可选的尽力而为型webhook(AGENT_COMM_EMIT_WEBHOOK)所以A 外部层（Claude Code空闲钩子，像chroxy这样的守护进程）可以拼收件人检查其邮箱。
自助邮箱：给自己发消息(from === to)对于推迟的自我任务。
完全地 向后兼容 使用v2.0消息文件。看邮箱队列（v2.1）.

⚡ v2.0.0的新增功能

2.0版本引入了显著的性能和效率改进：

🚀 邮件索引：O（1）消息查找，而不是O（n）目录扫描
💾 LRU缓存：用于频繁访问消息的内存缓存（将磁盘I/O减少约80%）
📁 有序存储：存储在代理特定目录中的消息(messages/{agent}/*.json)
📄 分页支持：通过以下方式高效处理数千条消息 limit 和 offset 参数
💪 持久索引：自动索引重建可确保重新启动时的数据一致性

性能改进

操作	v1.0	v2.0	改进
读取代理	O（n）扫描	O（1）索引查找的消息	快100倍 10k+条消息
列出消息	解析所有文件	缓存+索引	磁盘I/O减少80%
删除邮件	全扫描查找	索引查找	瞬间删除
内存使用率	最小值	100k条消息约10MB	可配置缓存大小

概述

代理通信系统允许：

编排代理 将任务委托给专业代理（程序员、审阅者、测试人员等）
专业代理商 接收任务并返回结果
所有代理商 协同工作，无需多个终端窗口手动传递消息

消息以JSON文件的形式存储在本地目录中(~/.agent-comm-system/messages 默认情况下），使通信持久且可检查。

安装

来源

git clone <repository-url>
cd agent-comm-system
npm install
npm run build

全球安装

npm install -g .

用法

运行服务器

服务器使用stdio传输作为MCP服务器运行：

npm start
# or if installed globally
agent-comm-system

使用Claude Desktop进行配置

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "agent-comm-system": {
      "command": "node",
      "args": ["/path/to/agent-comm-system/dist/index.js"]
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "agent-comm-system": {
      "command": "agent-comm-system"
    }
  }
}

可用工具

1.发送消息

从一个代理向另一个代理发送消息。

参数：

from （string，必填）：发送代理的标识符（例如，“编排器”、“编码器”、“审阅者”）
to （string，必填）：接收代理的标识符
subject （字符串，可选）：消息的主题行
content （string，必填）：消息内容

例子：

send_message({
  from: "orchestrator",
  to: "coder",
  subject: "Implement feature X",
  content: "Please implement the following feature: ..."
})

2.读取消息

读取发往具有可选分页的特定代理的邮件。

参数：

agent （string，必填）：要读取消息的代理的标识符
limit （number，可选）：要返回的最大消息数（默认值：50）
offset （number，可选）：要跳过的消息数（默认值：0）

示例：

// Read all messages (up to 50)
read_messages({
  agent: "coder"
})

// Read next page of messages
read_messages({
  agent: "coder",
  limit: 20,
  offset: 20
})

// Read first 100 messages
read_messages({
  agent: "coder",
  limit: 100
})

响应包括分页元数据：

邮件总数
电流偏移和限制
是否有更多消息可用

3.列表消息

列出系统中所有消息的元数据，并可选择过滤和分页。

参数：

agent （字符串，可选）：按收件人代理筛选邮件
limit （number，可选）：要返回的最大消息数（默认值：50）
offset （number，可选）：要跳过的消息数（默认值：0）

示例：

// List all messages (first 50)
list_messages()

// List messages for specific agent
list_messages({
  agent: "reviewer"
})

// Paginate through all messages
list_messages({
  limit: 100,
  offset: 100
})

4.删除消息

按ID删除特定邮件。

参数：

message_id （string，必填）：要删除的消息的ID

例子：

delete_message({
  message_id: "orchestrator-coder-1699564800000"
})

5.清除消息

清除特定代理的所有消息或系统中的所有消息。

参数：

agent （字符串，可选）：仅清除此代理的消息。如果未指定，则清除所有消息。

例子：

clear_messages({
  agent: "coder"
})

6.接收_下一页

取消排队 最老未读 代理（FIFO）的消息并将其标记为已读，因此下一次调用将返回以下消息。这是将邮箱作为队列清空的主要方式。

参数：

agent （string，必填）：要从其邮箱读取的代理
peek （布尔值，可选）：当 true，返回下一条未读邮件没有将其标记为已读（默认值： false)

例子：

receive_next({ agent: "coder" })
// → the oldest unread message; "Remaining unread: N"

receive_next({ agent: "coder", peek: true })
// → same message, but it stays unread

7.未读计数

返回未读邮件的数量（尚未通过 receive_next)作为一名代理人。

参数：

agent （字符串，必填）：用于统计未读消息的代理

例子：

unread_count({ agent: "coder" })
// → "Unread messages for coder: 3"

8.ack

确认消息已完全处理并删除。通常在以下时间调用 receive_next 一旦所描述的消息工作完成。

参数：

message_id （string，必填）：要确认和删除的消息的ID

例子：

ack({ message_id: "orchestrator-1699564800000" })

邮箱队列（v2.1）

receive_next / unread_count / ack 将每个代理存储变成真正的FIFO 邮箱队列:

消息携带a read 旗帜（和 id/readAt). read_messages 仍然是纯净的，非消费性阅读； receive_next 是消费队伍。

代理首先运行以处理其最旧收件箱的排水模式：

while (unread_count({ agent: "me" }) > 0) {
  const msg = receive_next({ agent: "me" });  // marks it read
  // ...do the work the message describes...
  ack({ message_id: msg.id });                // optional cleanup
}

自助邮箱：发送到您自己的id(from === to)让自己延期任务，然后稍后用 receive_next.

交货挂钩（发送时发出）

因此，外层可以拼收件人检查其邮箱， send_message 火a 通过环境变量配置时的可选尽力而为webhook：

AGENT_COMM_EMIT_WEBHOOK --URL到 POST 每次发送时，都会附上尸体 { to, from, id, subject, unread_count }.
AGENT_COMM_EMIT_HEADER --可选 Name: value 添加到的标头（例如身份验证令牌）请求。

排放为即发即弃，并有上限（2秒）：输送中断从不发送失败。这是Claude Code空闲/停止钩子或守护进程（如chrox）唤醒时消耗的接缝接收者——请参阅交付层的项目计划。

向后兼容性： 由v2.0编写的消息（否 id/read 字段）被处理未读，请获取 id 从它们的文件名派生，并在第一次时回填 receive_next。不需要迁移步骤。

命令行界面（v2.2）

对于需要以下功能的非MCP消费者（钩子、脚本），相同的二进制文件可以兼作一次性CLI 在不使用MCP stdio协议的情况下查询或清空邮箱。无争议地奔跑它是MCP服务器；带有子命令的是CLI：

agent-comm-system unread <agent>          # prints the unread count
agent-comm-system peek <agent>            # prints unread messages as a JSON array (no consume)
agent-comm-system next <agent> [--peek]   # prints the next unread message as JSON (consumes unless --peek)

邮箱位置可以用覆盖 AGENT_COMM_STORAGE （默认值 ~/.agent-comm-system/messages).

交付：空闲时ping（Claude Code Stop钩子，v2.2）

hooks/mailbox-stop-hook.mjs 是交付层的可移植部分：克劳德代码停止钩子，每当代理完成一个回合时，都会检查该代理的邮箱，如果未读消息正在等待-告诉代理通过 receive_next确实如此非破坏性（仅限peek；代理消耗）、循环安全（荣誉 stop_hook_active)，以及不需要守护进程。集 AGENT_COMM_ID 到代理的邮箱id并在中注册挂钩 .claude/settings.json --看 钩子/README.md 对于完整设置。

echo '{"stop_hook_active":false}' | AGENT_COMM_ID=coder node hooks/mailbox-stop-hook.mjs
# → {"decision":"block","reason":"📬 You have N unread mailbox message(s) ..."}  (when mail waits)

对于A 立即中断实时会话（而不是在下一个空闲时），守护进程因为氟利昂可以消耗 AGENT_COMM_EMIT_WEBHOOK 并在运行中注入唤醒 session——一个单独的可选层。

工作流示例

有关详细的使用示例和多代理工作流模式，请参阅示例.md.

快速示例：编排器→ 编码员→ 审稿人

编排器 向编码器发送任务：

send_message({
  from: "orchestrator",
  to: "coder",
  subject: "Build login page",
  content: "Create a login page with email and password fields..."
})

编码员 （在另一个Claude实例中）读取消息：
```
read_messages({ agent: "coder" })
```

编码员 完成工作并将其发送给审阅者：

send_message({
  from: "coder",
  to: "reviewer",
  subject: "Login page implementation",
  content: "I've implemented the login page. Here's what I did..."
})

审稿人 阅读并回复：

read_messages({ agent: "reviewer" })

send_message({
  from: "reviewer",
  to: "orchestrator",
  subject: "Login page review complete",
  content: "The implementation looks good. Minor suggestions: ..."
})

示例2：广播和收集响应

编排器 将任务发送给多个代理：

send_message({ from: "orchestrator", to: "coder", content: "..." })
send_message({ from: "orchestrator", to: "tester", content: "..." })
send_message({ from: "orchestrator", to: "documenter", content: "..." })

编排器 稍后检查响应：

read_messages({ agent: "orchestrator" })

消息存储

目录结构（v2.0）

邮件由收件人代理组织 ~/.agent-comm-system/:

~/.agent-comm-system/
├── index.json              # Message index for fast lookups
└── messages/
    ├── coder/              # Messages for 'coder' agent
    │   ├── orchestrator-1699564800000.json
    │   └── reviewer-1699564900000.json
    ├── reviewer/           # Messages for 'reviewer' agent
    │   └── coder-1699565000000.json
    └── orchestrator/       # Messages for 'orchestrator' agent
        └── reviewer-1699565100000.json

消息格式

每条消息都存储为JSON文件：

{
  "from": "orchestrator",
  "to": "coder",
  "timestamp": "2024-11-10T05:43:00.000Z",
  "subject": "Task description",
  "content": "Detailed message content..."
}

文件命名

v2.0格式: {from}-{timestamp}.json （存储在 messages/{to}/ 目录）
v1.0格式: {from}-{to}-{timestamp}.json （扁平结构）

索引文件

这 index.json 文件维护一个快速查找表：

{
  "coder": ["orchestrator-1699564800000", "reviewer-1699564900000"],
  "reviewer": ["coder-1699565000000"],
  "orchestrator": ["reviewer-1699565100000"]
}

如果索引损坏或丢失，则会在服务器启动时自动重建。

发展

建筑

npm run build

代码质量

该项目使用ESLint和Prettier来维护代码质量和一致性。

代码检查

# Run ESLint to check for issues
npm run lint

# Automatically fix ESLint issues
npm run lint:fix

格式化

# Format all files with Prettier
npm run format

# Check formatting without making changes
npm run format:check

类型检查

# Run TypeScript compiler for type checking (without emitting files)
npm run type-check

预提交钩子

该项目使用Husky和lint-stage在提交前自动运行代码质量检查：

代码检查：ESLint自动修复分阶段TypeScript文件中的问题
格式化：预处理所有暂存文件的格式
类型安全：TypeScript严格模式已启用

配置文件：

.prettierrc.json -预处理格式规则
eslint.config.js -ESLint衣帽规则
.husky/pre-commit -Git预提交钩子

CI/CD管道

该项目使用GitHub Actions和混合运行器系统，该系统自动在自托管和GitHub托管的运行器之间进行选择，以实现最佳的配额管理。

跑步者选择

自动（基于天）:

第1-25天：自托管跑步者（快速反馈，无配额成本）
第26-31天：GitHub托管跑步者（ubuntu最新）
每月1日自动重置

手动覆盖（提交消息标志）:

# Force self-hosted runner
git commit -m "feat: Add feature [self-hosted]"

# Force GitHub-hosted runner
git commit -m "fix: Quick fix [github]"

# Skip CI entirely
git commit -m "docs: Update README [skip-ci]"

手动调度:

转到操作→ 选择工作流→ 运行工作流
选择runner_mode： auto / self-hosted / github / skip

CI检查

CI管道对每个推送和拉取请求运行以下检查：

代码检查 -ESLint检查代码质量问题
格式化 -Prettier验证代码格式
类型检查 -TypeScript编译器验证类型
测试 -带有覆盖率报告的完整测试套件
构建 -验证项目构建是否成功

在合并pull请求之前，必须通过所有检查。

测试

该项目使用Jest通过ts-Jest进行测试，并支持TypeScript。

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

测试结构

tests/
├── helpers.ts           # Test utility functions
├── index.test.ts        # Unit tests for core functionality
├── integration.test.ts  # Integration tests for file operations
└── server.test.ts       # Server initialization tests

覆盖

覆盖率报告在 coverage/ 运行时的目录 npm run test:coverage.

关于覆盖指标的说明：主要 index.ts 文件是作为独立MCP进程运行的服务器入口点，不能通过导入直接进行单元测试。集成测试提供了所有消息处理操作（发送、读取、列表、删除、清除）的全面功能覆盖。为了在未来的迭代中改进覆盖率指标，可以考虑将服务器逻辑重构为单独的、可导入的模块。

测试套件包括：

涵盖所有MCP工具操作的43项综合测试
消息存储、过滤和删除的单元测试
并发操作和错误场景的集成测试
服务器初始化和配置测试

项目结构

agent-comm-system/
├── .github/                # GitHub configuration
│   └── workflows/          # GitHub Actions workflows
│       └── ci.yml          # CI pipeline with hybrid runner system
├── src/
│   └── index.ts            # Main MCP server implementation
├── tests/                  # Test files
│   ├── helpers.ts          # Test utilities
│   ├── index.test.ts       # Unit tests
│   ├── integration.test.ts # Integration tests
│   └── server.test.ts      # Server initialization tests
├── .husky/                 # Git hooks
│   └── pre-commit          # Pre-commit hook for linting/formatting
├── dist/                   # Compiled JavaScript output
├── coverage/               # Test coverage reports
├── .prettierrc.json        # Prettier configuration
├── .prettierignore         # Prettier ignore patterns
├── eslint.config.js        # ESLint configuration
├── jest.config.js          # Jest configuration
├── tsconfig.json           # TypeScript configuration
├── package.json            # Project dependencies and scripts
└── README.md

需求

Node.js 16或更高版本
npm 7或更高版本

许可证

国际学生委员会

使用说明

代理通信系统

🔔 v2.2.0的新增功能

📬 v2.1.0的新增功能

⚡ v2.0.0的新增功能

性能改进

概述

安装

来源

全球安装

用法

运行服务器

使用Claude Desktop进行配置

可用工具

1.发送消息

2.读取消息

3.列表消息

4.删除消息

5.清除消息

6.接收_下一页

7.未读计数

8.ack

邮箱队列（v2.1）

交货挂钩（发送时发出）

命令行界面（v2.2）

交付：空闲时ping（Claude Code Stop钩子，v2.2）

工作流示例

快速示例：编排器→ 编码员→ 审稿人

示例2：广播和收集响应

消息存储

目录结构（v2.0）

消息格式

文件命名

索引文件

发展

建筑

代码质量

代码检查

格式化

类型检查

预提交钩子

CI/CD管道

跑步者选择

CI检查

测试

运行测试

测试结构

覆盖

项目结构

需求

许可证

相关 MCP

协议桥接服务器

Webhook消息服务

子代理任务分发服务器

协议桥接服务器

协议桥接网关

AI代理协议集成工具