内容
# Mesh Core
**用于多智能体 AI 协作的本地优先 MCP 服务器。**
Mesh Core 是一个免费、开源的原型，允许多个 AI 智能体（Claude Code、Cursor、ChatGPT 通过 MCP 桥、Gemini 等）协作共享项目。它提供任务板、共享内存、智能体间消息传递和只追加时间线 — 所有数据都存储在单个 SQLite 文件中。
> ⚠️ **安全通知：** 此原型设计用于受信任的单用户本地使用。不要将 Mesh Core 套接字暴露于网络或在多用户/共享环境中运行，而不使用强化版。
---
## 功能
- **共享项目内存** — 目标、决策、约定、架构笔记
- **任务板** — 跨智能体创建、分配和跟踪任务，具备完整审计历史
- **智能体消息传递** — 智能体之间的直接消息和广播，在摄入时记录时间戳
- **只追加时间线** — 每个操作都会产生时间线事件；不会有数据静默丢失
- **工件存储** — 智能体生成的文件的内容寻址 Blob 存储
- **最多 10 个并发智能体** — 开源核心中没有人为限制
- **100% 本地** — 没有数据离开机器；无需帐户，无需云调用
---
## 工作原理
Mesh Core 作为 **HTTP MCP 服务器** 在 `127.0.0.1:3141` 上运行。每个 AI 客户端都通过 Streamable HTTP 传输独立连接。所有数据都存储在项目目录内的 `.mesh/mesh.db`（SQLite，WAL 模式）中。
为什么使用 HTTP 而不是 stdio？MCP `stdio` 传输是 1:1 的 — 每个客户端一个进程。支持 10 个并发智能体需要 HTTP 传输，每个智能体都有自己的会话，但所有智能体共享同一个数据库。
---
## 快速入门
### 先决条件
- Node.js ≥ 20
- npm ≥ 9
### 安装和构建
```bash
git clone https://github.com/your-org/mesh-core
cd mesh-core
npm install
npm run build
```
### 启动服务器
```bash
# 在项目目录中启动
npm run start
# 或指向特定目录
node dist/bin/mesh-server.js start --dir /path/to/project
# 自定义端口（默认：3141）
node dist/bin/mesh-server.js start --port 8080
```
Mesh Core 将在首次运行时在项目中创建 `.mesh/` 目录。
### 连接 AI 客户端
将以下内容添加到您的 MCP 客户端配置中（例如 Claude Desktop 的 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mesh": {
"url": "http://127.0.0.1:3141/mcp"
}
}
}
```
对于不支持原生 HTTP 传输的客户端，您可以使用 MCP 代理。有关详细信息，请参阅 [MCP 文档](https://modelcontextprotocol.io/)。
### 检查正在发生的事情
```bash
# 列出连接的智能体
node dist/bin/mesh-inspect.js agents
# 显示任务板
node dist/bin/mesh-inspect.js tasks
# 任务详情 + 历史
node dist/bin/mesh-inspect.js tasks <task-id>
# 最近的消息
node dist/bin/mesh-inspect.js messages
# 活动时间线
node dist/bin/mesh-inspect.js timeline
# 指向不同的项目目录
node dist/bin/mesh-inspect.js agents --dir /path/to/project
```
---
## 磁盘布局
```
<project_root>/.mesh/
mesh.db # SQLite（WAL 模式）— 所有结构化数据
mesh.db-wal
mesh.db-shm
config.json # 项目设置（智能体上限、端口、绑定地址）
artifacts/
<sha256>.blob # 内容寻址二进制存储
<sha256>.meta.json # 文件名、MIME 类型、大小
logs/
mesh-core.log # 仅本地，从不传输
```
---
## MCP 工具参考
所有工具都遵循 `mesh.<domain>.<action>` 命名约定。
### 智能体
| 工具 | 描述 |
|---|---|
| `mesh.agents.register` | 注册智能体（名称、client_kind、strengths[]） |
| `mesh.agents.list` | 列出所有智能体及其状态 |
| `mesh.agents.heartbeat` | 更新智能体的 last_seen_at 时间戳 |
### 内存
| 工具 | 描述 |
|---|---|
| `mesh.memory.write` | 写入内存条目（goal/decision/convention/constraint/architecture） |
| `mesh.memory.list` | 列出条目，可选按类别过滤 |
| `mesh.memory.search` | 跨内存条目的全文搜索 |
### 任务
| 工具 | 描述 |
|---|---|
| `mesh.tasks.create` | 创建具有标题、描述、优先级、依赖关系的任务 |
| `mesh.tasks.claim` | 将任务分配给智能体 |
| `mesh.tasks.update_status` | 更新任务状态（todo→in_progress→review→done/blocked） |
| `mesh.tasks.list` | 列出任务，可选按状态或智能体过滤 |
| `mesh.tasks.get` | 获取具有完整事件历史的任务 |
### 消息传递
| 工具 | 描述 |
|---|---|
| `mesh.messages.send` | 向智能体发送消息（或广播给所有人） |
| `mesh.messages.inbox` | 读取智能体自某个时间戳以来的消息 |
### 时间线
| 工具 | 描述 |
|---|---|
| `mesh.timeline.list` | 读取只追加的项目时间线 |
### 工件
| 工具 | 描述 |
|---|---|
| `mesh.artifacts.put` | 上传文件（base64 编码，最大 50MB） |
| `mesh.artifacts.get` | 通过 artifact_id 下载文件 |
| `mesh.artifacts.list` | 列出工件元数据，可选按任务过滤 |
---
## 配置
首次启动时，`.mesh/config.json` 将使用默认值创建：
```json
{
"max_agents": 10,
"port": 3141,
"bind": "127.0.0.1"
}
```
编辑此文件以更改设置。CLI 标志会覆盖配置文件值。
---
## 本仓库中没有的内容
以下功能故意为未来的高级/强化版本保留：
- 云帐户、计费、组织/团队管理
- 分布式团队的多机器同步
- 每个智能体的权限范围和加密存储
- 签名/身份验证的智能体握手
- 语义/嵌入内存搜索和知识图谱
- 智能体之间的冲突检测
- 桌面 GUI
- Rust 重写核心
---
## 贡献
该项目采用 MIT 许可证，并欢迎贡献。代码库是 TypeScript + SQLite — 如果您能读懂 JavaScript，您就可以贡献。
1. 复刻并克隆仓库
2. `npm install && npm run build`
3. 在 `src/` 中进行更改
4. 使用 `npm run test`（或 `npm run test:coverage`）运行自动化测试套件
5. 使用 `npm run dev`（tsx 监视模式）测试实时服务器更改
6. 打开 PR
请不要为上述高级功能打开 PR — 那些功能故意超出此仓库的范围。
---
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)
