# https://github.com/qualixar/slm-mesh 项目说明书

生成时间：2026-06-12 03:44:53 UTC

## 目录

- [Project Overview & Getting Started](#page-overview)
- [Broker, MCP Server, CLI & Data Architecture](#page-architecture)
- [Multi-Machine Coordination, Skills & Agent Integrations](#page-multimachine)
- [Configuration, Security & Operations](#page-ops)

<a id='page-overview'></a>

## Project Overview & Getting Started

### 相关页面

相关主题：[Broker, MCP Server, CLI & Data Architecture](#page-architecture), [Multi-Machine Coordination, Skills & Agent Integrations](#page-multimachine)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/slm-mesh/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/qualixar/slm-mesh/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/qualixar/slm-mesh/blob/main/package.json)
- [CHANGELOG.md](https://github.com/qualixar/slm-mesh/blob/main/CHANGELOG.md)
- [src/index.ts](https://github.com/qualixar/slm-mesh/blob/main/src/index.ts)
- [src/cli/cli.ts](https://github.com/qualixar/slm-mesh/blob/main/src/cli/cli.ts)
- [src/mcp/server.ts](https://github.com/qualixar/slm-mesh/blob/main/src/mcp/server.ts)
- [src/types.ts](https://github.com/qualixar/slm-mesh/blob/main/src/types.ts)
- [src/db/schema.ts](https://github.com/qualixar/slm-mesh/blob/main/src/db/schema.ts)
- [src/broker/broker-entry.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/broker-entry.ts)
- [src/adapters/backend.ts](https://github.com/qualixar/slm-mesh/blob/main/src/adapters/backend.ts)
- [src/adapters/memory-bridge.ts](https://github.com/qualixar/slm-mesh/blob/main/src/adapters/memory-bridge.ts)
- [tsup.config.ts](https://github.com/qualixar/slm-mesh/blob/main/tsup.config.ts)
- [vitest.config.ts](https://github.com/qualixar/slm-mesh/blob/main/vitest.config.ts)
</details>

# Project Overview & Getting Started

## 项目定位与设计目标

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 三种通道组合通信:

```mermaid
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]()

## 安装、接入与本地开发

### 生产部署

```bash
npm install -g slm-mesh
npx slm-mesh
```

接入 Claude Code 的标准命令:

```bash
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]()

### 本地开发流程

```bash
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]()

---

<a id='page-architecture'></a>

## Broker, MCP Server, CLI & Data Architecture

### 相关页面

相关主题：[Project Overview & Getting Started](#page-overview), [Multi-Machine Coordination, Skills & Agent Integrations](#page-multimachine), [Configuration, Security & Operations](#page-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/qualixar/slm-mesh/blob/main/src/index.ts)
- [src/config.ts](https://github.com/qualixar/slm-mesh/blob/main/src/config.ts)
- [src/types.ts](https://github.com/qualixar/slm-mesh/blob/main/src/types.ts)
- [src/broker/broker.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/broker.ts)
- [src/broker/broker-entry.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/broker-entry.ts)
- [src/broker/ensure.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/ensure.ts)
- [src/broker/handlers.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/handlers.ts)
- [src/broker/server.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/server.ts)
- [src/broker/push/manager.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/push/manager.ts)
- [src/mcp/server.ts](https://github.com/qualixar/slm-mesh/blob/main/src/mcp/server.ts)
- [src/mcp/broker-client.ts](https://github.com/qualixar/slm-mesh/blob/main/src/mcp/broker-client.ts)
- [src/cli/cli.ts](https://github.com/qualixar/slm-mesh/blob/main/src/cli/cli.ts)
- [src/cli/format.ts](https://github.com/qualixar/slm-mesh/blob/main/src/cli/format.ts)
- [src/adapters/backend.ts](https://github.com/qualixar/slm-mesh/blob/main/src/adapters/backend.ts)
- [src/adapters/memory-bridge.ts](https://github.com/qualixar/slm-mesh/blob/main/src/adapters/memory-bridge.ts)
- [python/src/slm_mesh/client.py](https://github.com/qualixar/slm-mesh/blob/main/python/src/slm_mesh/client.py)
- [tsup.config.ts](https://github.com/qualixar/slm-mesh/blob/main/tsup.config.ts)
- [package.json](https://github.com/qualixar/slm-mesh/blob/main/package.json)
- [CHANGELOG.md](https://github.com/qualixar/slm-mesh/blob/main/CHANGELOG.md)
</details>

# 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 推送至接收方。

```mermaid
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](api-reference.md) — 8 个 MCP 工具与 12 个 broker 端点
- [Configuration](configuration.md) — 环境变量与调优
- [Security](security.md) — Bearer Token、限流、威胁模型
- [Python Client](python-client.md) — Python SDK
- [Troubleshooting](troubleshooting.md) — 常见错误与排查

---

<a id='page-multimachine'></a>

## Multi-Machine Coordination, Skills & Agent Integrations

### 相关页面

相关主题：[Project Overview & Getting Started](#page-overview), [Broker, MCP Server, CLI & Data Architecture](#page-architecture), [Configuration, Security & Operations](#page-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/slm-mesh/blob/main/README.md)
- [package.json](https://github.com/qualixar/slm-mesh/blob/main/package.json)
- [src/index.ts](https://github.com/qualixar/slm-mesh/blob/main/src/index.ts)
- [src/mcp/server.ts](https://github.com/qualixar/slm-mesh/blob/main/src/mcp/server.ts)
- [src/cli/cli.ts](https://github.com/qualixar/slm-mesh/blob/main/src/cli/cli.ts)
- [src/types.ts](https://github.com/qualixar/slm-mesh/blob/main/src/types.ts)
- [src/adapters/backend.ts](https://github.com/qualixar/slm-mesh/blob/main/src/adapters/backend.ts)
- [src/db/schema.ts](https://github.com/qualixar/slm-mesh/blob/main/src/db/schema.ts)
- [skills/mesh-lock.md](https://github.com/qualixar/slm-mesh/blob/main/skills/mesh-lock.md)
- [skills/mesh-sync.md](https://github.com/qualixar/slm-mesh/blob/main/skills/mesh-sync.md)
- [CHANGELOG.md](https://github.com/qualixar/slm-mesh/blob/main/CHANGELOG.md)
</details>

# Multi-Machine Coordination, Skills & Agent Integrations

## 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]()

---

## 2. 系统架构与数据流

SLM Mesh 采用三层组件设计：**CLI / MCP Server → Broker → SQLite 后端**。其中 Broker 是常驻守护进程，由 MCP Server 或 CLI 首次调用时通过 `ensureBroker` 自动拉起（auto-start），并在所有 peer 离开后自动停止（auto-stop）。

资料来源：[src/index.ts:1-40]() [src/mcp/server.ts:1-30]()

```mermaid
flowchart LR
    A[AI Agent<br/>Claude Code / Cursor] -->|MCP stdio| B[MCP Server<br/>src/mcp/server.ts]
    C[CLI<br/>slm-mesh peers] -->|HTTP + Bearer| D[Broker<br/>src/broker/broker.ts]
    B -->|HTTP + Bearer| D
    D -->|UDS push| A
    D -->|SQL| E[(SQLite<br/>WAL mode)]
    D -->|MemoryBridge| F[SuperLocalMemory<br/>可选]
```

Broker 与 MCP Server 之间通过 HTTP + Bearer Token 通信，Token 由 Broker 在启动时生成并写入 token 文件。`AUTH_EXEMPT_PATHS` 仅放行 `/health` 端点，其余所有写操作都必须经过认证。

资料来源：[src/cli/cli.ts:20-50]()

核心类型定义在 `src/types.ts` 中集中维护，包括 `Peer`、`Message`、`Lock`、`StateEntry`、`MeshEvent` 等。SQLite schema 在 `src/db/schema.ts` 中以 `IF NOT EXISTS` 方式声明，保证冷启动幂等。

资料来源：[src/types.ts:1-60]() [src/db/schema.ts:1-30]()

---

## 3. Claude Code Skills（Slash Commands）

v1.1.0 引入了 5 个 Slash Command 形式的 Skills，作为对 MCP 工具的高级封装，每个 Skill 都是一个独立的 Markdown 文件，遵循"自然语言指令 → MCP 工具调用"的模式：

| Skill | 调用形式 | 底层 MCP 工具 |
|-------|---------|--------------|
| `/mesh-peers` | 发现当前活跃会话 | `mesh_peers` |
| `/mesh-send <msg>` | 向指定 peer 或全体广播 | `mesh_send` |
| `/mesh-lock <file>` | 加锁/解锁/查询文件 | `mesh_lock` |
| `/mesh-status` | 完整仪表盘视图 | 组合多个工具 |
| `/mesh-sync` | 一站式同步（每日站会） | `mesh_summary` + `mesh_inbox` + `mesh_peers` + `mesh_lock` |

资料来源：[README.md:60-70]() [skills/mesh-sync.md:1-30]()

以 `/mesh-lock` 为例：当用户执行 `/mesh-lock src/auth.ts refactoring JWT validation` 时，Skill 会调用 `mesh_lock`，传入 `action="lock"`、`file="src/auth.ts"` 与 `reason` 字段。默认 TTL 为 10 分钟，到期自动释放；若文件已被其他 peer 锁定，Skill 会提示冲突方与剩余时间，并建议用户等待、协商或换文件。

资料来源：[skills/mesh-lock.md:1-30]()

`/mesh-sync` 是设计上的亮点——它把"设置摘要 → 检查收件箱 → 发现 peer → 检查锁"四个步骤串成一个原子流程，并以格式化输出呈现：

```
Mesh Sync Complete
━━━━━━━━━━━━━━━━━
Your status: "Working on auth refactoring"
Unread messages (2): ...
Active peers (3): ...
Locked files: ...
```

资料来源：[skills/mesh-sync.md:15-40]()

---

## 4. 跨 Agent 与跨机器集成

### 4.1 MCP 安装方式

SLM Mesh 支持多种 AI 代理的统一接入模式，所有客户端都使用 `npx slm-mesh` 作为 stdio 命令：

- **Claude Code**：`claude mcp add --scope user slm-mesh -- npx slm-mesh`
- **Cursor**：写入 `.cursor/mcp.json` 中的 `mcpServers`
- **VS Code / Windsurf / 其他 MCP Agent**：写入各自的 MCP settings 文件

资料来源：[README.md:30-55]()

### 4.2 跨机器发现

通过 Bonjour/mDNS（`bonjour` 依赖）实现 LAN 内 Broker 自动发现，结合 UDS（Unix Domain Socket）推送，实现亚 100ms 的消息投递延迟。BackendAdapter 接口（`src/adapters/backend.ts`）为存储层提供了抽象，未来可替换为 Redis 或 PostgreSQL 而无需改动上层逻辑。

资料来源：[package.json:30-45]() [src/adapters/backend.ts:1-40]()

### 4.3 Agent 自动识别

`AgentType` 枚举涵盖 `claude-code`、`cursor`、`aider`、`codex`、`windsurf`、`vscode`、`unknown`。识别过程在 MCP Server 启动时通过进程树检查完成，结果写入 SQLite 的 `peers.agent_type` 字段，便于后续做基于工具的路由。

资料来源：[src/types.ts:15-25]() [src/db/schema.ts:15-25]()

---

## 5. 常见失败模式

- **Broker 未启动**：首次调用时自动拉起；若端口冲突（默认端口动态发现）需检查 PID 文件
- **Token 失效**：Bearer Token 由 Broker 写入 `tokenPath`，重启后失效，需重新读取
- **Skill 不触发**：确认 `.claude/skills/` 或对应 IDE 的 skills 目录已正确放置 `mesh-*.md`
- **跨机器不可达**：Bonjour 需要同一 LAN 与组播可达，跨广域网需自行搭建 Broker 中继

资料来源：[src/cli/cli.ts:20-50]() [src/mcp/server.ts:20-40]()

---

## See Also

- [Getting Started](docs/getting-started.md)
- [Architecture](docs/architecture.md)
- [API Reference](docs/api-reference.md)
- [Security](docs/security.md)
- [Troubleshooting](docs/troubleshooting.md)

---

<a id='page-ops'></a>

## Configuration, Security & Operations

### 相关页面

相关主题：[Broker, MCP Server, CLI & Data Architecture](#page-architecture), [Multi-Machine Coordination, Skills & Agent Integrations](#page-multimachine)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/slm-mesh/blob/main/README.md)
- [SECURITY.md](https://github.com/qualixar/slm-mesh/blob/main/SECURITY.md)
- [CHANGELOG.md](https://github.com/qualixar/slm-mesh/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/qualixar/slm-mesh/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/qualixar/slm-mesh/blob/main/package.json)
- [vitest.config.ts](https://github.com/qualixar/slm-mesh/blob/main/vitest.config.ts)
- [tsup.config.ts](https://github.com/qualixar/slm-mesh/blob/main/tsup.config.ts)
- [src/config.ts](https://github.com/qualixar/slm-mesh/blob/main/src/config.ts)
- [src/index.ts](https://github.com/qualixar/slm-mesh/blob/main/src/index.ts)
- [src/cli/cli.ts](https://github.com/qualixar/slm-mesh/blob/main/src/cli/cli.ts)
- [src/mcp/broker-client.ts](https://github.com/qualixar/slm-mesh/blob/main/src/mcp/broker-client.ts)
- [src/broker/broker-entry.ts](https://github.com/qualixar/slm-mesh/blob/main/src/broker/broker-entry.ts)
- [src/types.ts](https://github.com/qualixar/slm-mesh/blob/main/src/types.ts)
</details>

# 配置、安全与运维

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

## 1. 配置模型与环境变量

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

| 环境变量 | 默认值 / 取值 | 作用 |
|---|---|---|
| `SLM_MESH_HOST` | `localhost` | broker 监听地址，远程地址会触发 `client` 角色推断 |
| `SLM_MESH_ROLE` | `auto` / `broker` / `client` | 显式声明本机角色：是否生成本地 broker |
| `SLM_MESH_IDLE_TIMEOUT` | `60000`（毫秒） | broker 空闲超时，设为 `0` 可禁用自动关闭 |

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

## 2. 安全模型

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

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

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

## 3. 运维操作

`slm-mesh` 提供双入口模式：[`src/index.ts`](src/index.ts) 根据 `process.argv` 决定进入 CLI 还是 MCP 模式。CLI 子命令集合定义在 [`CLI_COMMANDS`](src/index.ts) 中，常用运维命令包括 [`src/cli/cli.ts`](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()`](src/broker/broker-entry.ts) 启动，并由 `ensureBroker` 在首个 MCP 请求时按需拉起 [`src/mcp/server.ts`](src/mcp/server.ts)。MCP 客户端的 HTTP 请求默认超时为 `REQUEST_TIMEOUT_MS = 5000` 毫秒 [`src/mcp/broker-client.ts`](src/mcp/broker-client.ts)。当所有 peer 离线后，broker 会按 `SLM_MESH_IDLE_TIMEOUT` 自动退出 [`CHANGELOG.md`](CHANGELOG.md)。

## 4. 开发与发布

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

## See Also

- [README.md](https://github.com/qualixar/slm-mesh/blob/main/README.md) — 项目总览与 MCP 集成
- [CHANGELOG.md](https://github.com/qualixar/slm-mesh/blob/main/CHANGELOG.md) — 版本演进与配置变更记录
- [SECURITY.md](https://github.com/qualixar/slm-mesh/blob/main/SECURITY.md) — 漏洞响应流程
- [CONTRIBUTING.md](https://github.com/qualixar/slm-mesh/blob/main/CONTRIBUTING.md) — 贡献规范与覆盖率要求

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: qualixar/slm-mesh; human_manual_source: deepwiki_human_wiki -->