项目定位与设计目标

SLM Mesh 是 Qualixar 团队在 SuperLocalMemory 研究框架下推出的点对点通信中间件,定位于让多个 AI 编码代理(Claude Code、Cursor、Aider、Codex、Windsurf 等)在同一台机器甚至跨机器场景下,像本地进程一样自动发现彼此、投递消息、共享状态并协调文件编辑。资料来源：README.md:1-20

项目的核心设计原则是 zero cloud dependency + local-first:所有数据落盘到本地 SQLite,实时通知走 Unix Domain Socket,跨机通信走 WebSocket,完全不需要任何外部 SaaS,符合 EU AI Act 对本地化、可审计的要求。资料来源：README.md:25-45, package.json:30-55

核心能力矩阵

MCP 接入层刻意收敛为固定 8 个工具,这是有意识的设计选择——每个 tool 都会消耗 agent 的上下文窗口,工具集过大反而降低代理效率。资料来源：src/mcp/server.ts:10-30

在功能域层面,SLM Mesh 提供六类原子能力:会话发现(按项目路径、Git 根目录、scope 过滤的 peer 注册表)、直接消息(带送达回执与历史查询的结构化消息投递)、广播(一对多通知)、共享状态(命名空间化 KV 临时存储)、文件协调(咨询式文件锁,带可配置超时)、事件总线(peer_joined、peer_left、state_changed、file_locked、file_unlocked 及自定义事件)。资料来源：src/types.ts:18-70, src/db/schema.ts:20-75

社区在 v1.1.0 版本中推出了 Claude Code Skills(slash 命令),把上述能力封装为 /mesh-peers、/mesh-send <message>、/mesh-lock <file>、/mesh-status、/mesh-sync 等快捷指令,大幅降低了在 Claude Code 中使用 mesh 的心智负担。资料来源：CHANGELOG.md:15-30

系统架构与组件拓扑

SLM Mesh 由三个进程级组件构成,通过 HTTP + UDS + WebSocket 三种通道组合通信:

flowchart LR
  A[AI Agent MCP Client] -->|stdio / MCP| B[MCP Server]
  B -->|HTTP localhost| C[Broker Daemon]
  C -->|UDS push| D[Local Peer]
  C -->|WebSocket| E[Remote Peer]
  C <-->|SQLite WAL| F[(mesh.db)]
  G[CLI] -->|HTTP + Bearer| C
  H[MemoryBridge Adapter] -.->|optional hook| C

• Broker:常驻守护进程,负责 peer 注册、心跳、消息路由、锁管理与事件分发,通过 Broker.start() 启动并由 broker-entry.ts 作为独立入口。资料来源：src/broker/broker-entry.ts:10-20
• MCP Server:为 AI 代理暴露 stdio 协议的 8 个 MCP 工具,内部通过 HTTP 调用 broker。资料来源：src/mcp/server.ts:15-35
• CLI:基于 Commander.js,提供 start / stop / status / peers / send / broadcast / state / lock / events / clean 等子命令。资料来源：src/cli/cli.ts:1-25
• BackendAdapter:可插拔存储抽象,默认实现为 SQLite(WAL 模式),允许用户实现 Redis、PostgreSQL 等自定义后端。资料来源：src/adapters/backend.ts:1-30
• MemoryBridge:可选的 SuperLocalMemory 集成钩子,提供 onMessage / onStateChange / onEvent / recall / isAvailable 五个回调,用于跨会话记忆召回。资料来源：src/adapters/memory-bridge.ts:1-20

入口模块通过 process.argv 自动判定运行模式:若包含已知 CLI 子命令则进入 CLI 模式,否则作为 MCP stdio 服务器被 AI 代理 spawn。资料来源：src/index.ts:10-35

安装、接入与本地开发

生产部署

npm install -g slm-mesh
npx slm-mesh

接入 Claude Code 的标准命令:

claude mcp add --scope user slm-mesh -- npx slm-mesh

Cursor 在 .cursor/mcp.json 中声明 mcpServers;VS Code、Windsurf 等兼容 MCP 的编辑器使用相同结构。资料来源：README.md:50-90

生命周期自动化与跨机角色

Broker 采用 "首次使用自动启动、无 peer 时自动停止" 的惰性生命周期策略,核心目标是让用户在交互式会话中无需关心守护进程的存在;SLM_MESH_IDLE_TIMEOUT(默认 60000ms,设为 0 可禁用)调节空闲关闭阈值。资料来源：CHANGELOG.md:10-20

跨机器部署可通过 SLM_MESH_ROLE 显式声明角色:broker(中心机,允许 spawn 本地守护进程)、client(纯客户端,永不 spawn)、auto(根据 SLM_MESH_HOST 自动推断:localhost → broker,远端 IP → client)。资料来源：CHANGELOG.md:15-25

本地开发流程

git clone https://github.com/qualixar/slm-mesh.git
cd slm-mesh
npm install
npm test            # 运行 480 用例
npm run typecheck   # TypeScript 严格模式
npm run build       # tsup 打包为 ESM,目标 Node 20
npm run dev         # tsx 启动开发模式
npm run test:coverage # 覆盖率报告

项目强制 100% 行覆盖率(functions ≥ 99%,branches ≥ 93%),TDD 是硬性要求:先写失败用例,再写最小实现,最后重构。提交格式遵循 Conventional Commits(feat / fix / refactor / test / docs / chore / perf)。资料来源：CONTRIBUTING.md:20-55, vitest.config.ts:1-25

构建系统使用 tsup 打包双入口(index + broker),仅输出 ESM 格式,启用 sourcemap 与 shebang。运行时依赖被刻意收敛到 6 个:MCP SDK、better-sqlite3、bonjour、commander、ws、zod;贡献指南明确"目标零运行时依赖",新增依赖需充分论证。资料来源：tsup.config.ts:1-15, package.json:35-60, CONTRIBUTING.md:55-60

常见故障与注意事项

• WS 路由错误:v1.3.3 之前,远端 WS peer 会触发无意义的 UDS 连接尝试,导致跨机消息丢失;升级到 ≥ 1.3.4 即可修复。资料来源：CHANGELOG.md:5-10
• Node 版本:要求 >= 20,部分功能依赖 better-sqlite3 12.x 在 Node 26 上的兼容路径。资料来源：package.json:55-60
• 端口冲突:broker 默认监听 localhost HTTP,通过 PID 文件 + token 文件防重复启动;CLI 在请求前读取 token 并通过 Authorization: Bearer ... 头认证,仅 /health 路径豁免。资料来源：src/cli/cli.ts:15-35
• Agent 检测降级:无法从进程树识别已知代理时,AgentType 字段回退为 'unknown',功能不受影响,但统计维度会变粗。资料来源：src/types.ts:18-25

See Also

• 命令行与 MCP 工具细节:src/cli/cli.ts, src/mcp/server.ts
• 数据模型与表结构:src/types.ts, src/db/schema.ts
• 扩展接入(自定义后端、记忆系统):src/adapters/backend.ts, src/adapters/memory-bridge.ts
• 版本演进历史:CHANGELOG.md
• 贡献流程与质量门槛:CONTRIBUTING.md

Broker, MCP Server、CLI 与数据架构

概述

SLM Mesh 是一个面向同机多 AI 代理会话的点对点协调层，由三大运行时组件与一套可插拔数据适配器组成：本地 Broker（HTTP 服务）、MCP Server（通过 stdio 暴露 8 个工具给代理）以及 CLI（Commander.js 命令行）。三者共享同一份 MeshConfig 配置，并经由 HTTP + Bearer Token 与后端存储（默认 SQLite）通信，整体定位为"零外部服务依赖、本地优先、可跨进程协作"的代理间通信骨架。资料来源：README.md:1-20、CHANGELOG.md:1-30。

组件入口与打包方式在 tsup.config.ts 中以双入口形式声明：index 用于 CLI/MCP，broker 用于守护进程式 Broker。资料来源：tsup.config.ts:1-15。

系统架构与数据流

下图展示一次典型"代理 A 发消息给代理 B"的请求路径：MCP Server 通过 brokerRequest 调用 Broker HTTP 端点，Broker 写入存储并通过 UDS/WS 推送至接收方。

flowchart LR
  A[AI Agent A<br/>MCP Client] -->|stdio/JSON-RPC| B[MCP Server<br/>src/mcp/server.ts]
  C[人类用户<br/>或脚本] -->|CLI args| D[CLI<br/>src/cli/cli.ts]
  B -->|HTTP + Bearer| E[BrokerHttpServer<br/>src/broker/server.ts]
  D -->|HTTP + Bearer| E
  E --> F[Route Handlers<br/>src/broker/handlers.ts]
  F --> G[BackendAdapter<br/>src/adapters/backend.ts]
  G --> H[(SQLite WAL<br/>better-sqlite3)]
  F --> I[PushManager<br/>UDS + WS]
  I -->|Unix Domain Socket| J[Agent B MCP Server]
  I -->|WebSocket| K[Remote Peer]

src/index.ts 在启动时根据 process.argv 判断模式：若包含 start、stop、send 等已知 CLI 命令则进入 Commander 模式，否则作为 MCP Server 进程被代理拉起。资料来源：src/index.ts:8-40。

三大组件职责

Broker（后台守护进程）

src/broker/broker.ts 中的 Broker 类承担全部持久化与协调职责，订阅 BackendAdapter 抽象以允许替换存储（Redis、PostgreSQL 等）。BrokerHttpServer 使用 node:http 自建零依赖路由表，键为 "METHOD /path"，实现 O(1) 查找，并通过 setBearerTokens() 注入多 Token（本地自动生成 + 可选共享密钥）。资料来源：src/broker/server.ts:15-50。

12 个端点全部集中在 src/broker/handlers.ts，涵盖 peer 注册、消息收发、状态读写、文件锁、事件订阅；其中包含 MAX_PAYLOAD_BYTES=65_536、RATE_LIMIT_MAX=100/RATE_LIMIT_WINDOW_MS=10_000 等安全与限流常量。资料来源：src/broker/handlers.ts:15-30。

src/broker/ensure.ts 提供"按需自启"：首次调用时通过 PID 文件与端口探测判断 Broker 是否存活，若无则 spawn 子进程；空闲超时由 SLM_MESH_IDLE_TIMEOUT（默认 60000ms，0 禁用）控制。资料来源：CHANGELOG.md:25-50。

MCP Server（AI 代理侧）

src/mcp/server.ts 实例化 McpServer 并通过 StdioServerTransport 暴露 8 个工具（mesh_summary、mesh_send、mesh_state 等），其指令字符串明确要求代理在启动时调用 mesh_summary、编辑文件前查询 mesh_lock。brokerRequest<T> 是它与 Broker 通信的唯一通道，自动从 token 文件或 SLM_MESH_SHARED_SECRET 注入 Authorization: Bearer … 头，超时固定 5 秒。资料来源：src/mcp/server.ts:1-40、src/mcp/broker-client.ts:18-60。

CLI（运维与脚本入口）

src/cli/cli.ts 基于 Commander 14，提供 start/stop/status/peers/send/broadcast/state/lock/events/version/clean 等子命令，并通过 --json 输出机器可读响应。buildAuthHeaders 同样实现 /health 免认证。输出经 src/cli/format.ts 中 formatPeers/formatLocks/formatEvents/formatStatus 表格化。资料来源：src/cli/cli.ts:1-40、src/cli/format.ts:1-50。

数据架构与适配器

核心领域模型

src/types.ts 定义了品牌化 ID（PeerId、MessageId、EventId）与不可变领域对象（Peer、Message、Lock、MeshEvent、StateEntry），所有 readonly 字段保证不可变性。枚举涵盖 AgentType（claude-code/cursor/aider/codex/windsurf/vscode/unknown）与 PeerScope（machine/directory/repo）。资料来源：src/types.ts:1-60。

后端与外部记忆桥接

BackendAdapter（src/adapters/backend.ts）是存储抽象，覆盖 peer 生命周期、消息、命名空间键值状态、文件锁、事件流；MemoryBridge（src/adapters/memory-bridge.ts）定义与 SuperLocalMemory 等外部记忆系统的钩子：onMessage/onStateChange/onEvent/recall/isAvailable，可在消息或状态变更时持久化跨会话上下文。资料来源：src/adapters/backend.ts:1-50、src/adapters/memory-bridge.ts:1-20。

推送层

PushManager 在 handlers.ts 中被注入，负责通过 Unix Domain Socket 做亚 100ms 的本地推送，并通过 WsServer 支持跨机器的 WebSocket 路由；v1.3.3 修复了"远端 peer 触发 UDS 连接"的路由 bug（WS-first，UDS fallback）。资料来源：CHANGELOG.md:10-20。

Python 客户端

python/src/slm_mesh/client.py 提供零依赖（仅 urllib + json）的同步客户端，从 ~/.slm-mesh/broker.token 读取 Bearer 令牌并复用同一组免认证路径，便于在非 Node.js 流水线中集成。资料来源：python/src/slm_mesh/client.py:1-40。

运行时与依赖约束

package.json 显式声明运行时仅依赖 @modelcontextprotocol/sdk、better-sqlite3 ^12.10.0、bonjour、commander ^14、ws ^8.20、zod ^4.3.6，并要求 Node.js ≥ 20。CONTRIBUTING.md 强调"不引入新增运行时依赖、不新增 MCP 工具（8 个工具表面积为有意识设计）"。资料来源：package.json:1-50、CONTRIBUTING.md:1-20。

社区关注点

v1.1.0 起，Claude Code 用户通过 /mesh-peers、/mesh-send、/mesh-lock、/mesh-status、/mesh-sync 五个斜杠命令直接编排 mesh；Cursor 用户则通过 .cursor/mcp.json 集成——这表明社区最关心"低摩擦接入"与"跨代理状态共享"两个特性。资料来源：v1.1.0 Release Notes。

See Also

• API Reference — 8 个 MCP 工具与 12 个 broker 端点
• Configuration — 环境变量与调优
• Security — Bearer Token、限流、威胁模型
• Python Client — Python SDK
• Troubleshooting — 常见错误与排查

1. 概述与设计目标

SLM Mesh 是一个面向 AI 编码代理的对等通信层，其核心价值在于解决"会话隔离"问题：当开发者在同一台机器或跨机器运行多个 AI 编码会话时，Session A 与 Session B 之间默认没有任何通信渠道。SLM Mesh 通过本地优先（local-first）的中间层把这些会话连接起来，使它们能够发现彼此、共享状态、传递消息并协作编辑文件。

资料来源：README.md:1-15

根据 v1.1.0 社区发布说明，Mesh 不仅提供基础消息与状态能力，还引入了一套面向 Claude Code 的 Slash Commands（Skills），以及面向 Cursor、VS Code、Windsurf 等主流 IDE 的集成指南。这一组合让用户无需记忆复杂 CLI 调用，只需在编辑器内输入 /mesh-peers、/mesh-send 等指令即可完成协作。

资料来源：README.md:60-75 CHANGELOG.md:1-10

配置、安全与运维

本页汇总 slm-mesh 在配置、安全防护与日常运维方面的关键事实与命令，帮助使用者快速理解运行时行为边界。

1. 配置模型与环境变量

slm-mesh 通过 createConfig() 工厂函数生成 MeshConfig 对象，并将其作为单一可信配置源注入到 broker、MCP 服务器和 CLI 三个组件中 README.md:1-40。除了代码内默认值外，以下环境变量在 CHANGELOG.md 中被显式记录：

sharedSecret 字段在 src/mcp/broker-client.ts 中用于跨机共享密钥认证；本地回退时则读取 tokenPath 下的 bearer token。Node 运行时要求 >= 20.0.0 package.json。

2. 安全模型

SECURITY.md 与源代码共同定义了"单机单用户、本地优先"的安全边界 SECURITY.md。核心保障包括：

• 仅本地绑定：broker 不得绑定到 0.0.0.0，杜绝外部网络暴露 SECURITY.md。
• Bearer Token 鉴权：AUTH_EXEMPT_PATHS 仅豁免 /health，其余端点必须携带 Authorization: Bearer <token> src/mcp/broker-client.ts。
• 无 Shell 注入：进程启动使用 execFileSync 并以参数数组形式传入，依赖链中无 child_process.exec 类型调用 SECURITY.md。
• 输入校验：所有 peer ID 必须为合法 UUID，payload 设有大小限制并启用速率限制 SECURITY.md。
• 文件权限：敏感文件 0o600、目录 0o700；CLI 头部代码中 buildAuthHeaders() 会按需附加认证头 src/cli/cli.ts。
• 无遥测：项目声明无外部数据上报，符合欧盟 AI Act 的本地化要求 README.md。

如发现安全漏洞，应按 SECURITY.md 的处置流程在 48 小时内确认、1 周内评估 SECURITY.md。

3. 运维操作

slm-mesh 提供双入口模式：src/index.ts 根据 process.argv 决定进入 CLI 还是 MCP 模式。CLI 子命令集合定义在 CLI_COMMANDS 中，常用运维命令包括 src/cli/cli.ts：

• slm-mesh start / stop — 启停 broker 守护进程
• slm-mesh status — 查看 broker 健康状态
• slm-mesh peers / events / lock — 查看对等节点、事件流、文件锁
• slm-mesh send / broadcast / state — 发送点对点 / 广播消息、读写共享状态
• slm-mesh clean — 清理残留资源

broker 通过 Broker.start() 启动，并由 ensureBroker 在首个 MCP 请求时按需拉起 src/mcp/server.ts。MCP 客户端的 HTTP 请求默认超时为 REQUEST_TIMEOUT_MS = 5000 毫秒 src/mcp/broker-client.ts。当所有 peer 离线后，broker 会按 SLM_MESH_IDLE_TIMEOUT 自动退出 CHANGELOG.md。

4. 开发与发布

tsup 将入口打包为 ESM 单一可执行文件，输出 index 与 broker 两个 bundle tsup.config.ts。构建依赖包括 better-sqlite3、ws、bonjour、commander、@modelcontextprotocol/sdk 与 zod package.json。测试使用 Vitest，覆盖率阈值要求 *行 100% / 函数 99% / 分支 93% / 语句 100%* vitest.config.ts。贡献者须遵循 TypeScript 严格模式、不可变数据模式以及"先写测试再写实现"的 TDD 流程 CONTRIBUTING.md。

See Also

• README.md — 项目总览与 MCP 集成
• CHANGELOG.md — 版本演进与配置变更记录
• SECURITY.md — 漏洞响应流程
• CONTRIBUTING.md — 贡献规范与覆盖率要求

Pitfall Log / 踩坑日志

项目：qualixar/slm-mesh

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | host_targets=mcp_host, claude_code, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1204198694 | https://github.com/qualixar/slm-mesh | release_recency=unknown