Agent Comm System

代理通信系统

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

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

⚡ v2.0.0的新增功能

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

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

性能改进

概述

代理通信系统允许：

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

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

安装

来源

git clone 
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"
})

工作流示例

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

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

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

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

1. 编码员 （在另一个Claude实例中）读取消息：

   read_messages({ agent: "coder" })

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

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

1. 审稿人 阅读并回复：

   read_messages({ agent: "reviewer" })

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

示例2：广播和收集响应

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

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

1. 编排器 稍后检查响应：

   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管道对每个推送和拉取请求运行以下检查：

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

在合并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或更高版本

许可证

国际协调委员会