n2ns Nexus 是一款专为多 AI 助手协作设计的“本地数字化资产中心”。它将高频的实时会议室与严谨的结构化资产库无缝整合，为您提供 100% 本地化、零依赖的项目管理体验。

该工具旨在优化 AI 原生开发流程，完美适配以下环境：

• AI 助手/工具：Claude Code、Claude Desktop、Google Antigravity
• IDE/编辑器：VS Code、Cursor、Windsurf、Zed、JetBrains、Theia

🛠️ 工具集 (Toolset)

A. 会话与上下文 (Session & Context)

• register_session_context：声明当前在 IDE 中活跃的项目 ID，以解锁写入权限。
• mcp://nexus/session：查看当前的身份、角色（Host/Regular）以及活跃项目。

B. 项目资产管理 (Project Asset Management)

• sync_project_assets：[核心/异步] 提交完整的项目清单（Manifest）和内部文档。返回 taskId。
  • 清单内容：包括 ID、技术栈、依赖关系、仓库 URL、本地路径、API 规范等。
  • Schema v2.0 字段：支持 apiDependencies（API 依赖）、gatewayCompatibility（网关兼容性）、api_versions（API 版本）及 feature_tier（功能层级：free/pro/enterprise）。
• update_project：部分更新清单字段（例如仅更新端点或描述）。
• rename_project：[异步] 重命名项目 ID，并自动级联更新所有依赖引用。返回 taskId。
• upload_project_asset：向项目库上传二进制或文本文件（Base64 格式）。
• 读取操作：所有只读访问请使用资源（例如 mcp://nexus/projects/{id}/manifest）。

C. 全局协作 (Global Collaboration)

• send_message：向团队发布消息（自动路由至当前活跃会议）。
• read_messages：[增量读取] 仅返回每个 IDE 实例的未读消息。服务器会自动跟踪阅读进度。
• update_global_strategy：更新核心战略蓝图（# Master Plan）。
• get_global_topology：[渐进式查看] 默认返回摘要列表；提供 projectId 时返回详细的子图。
• sync_global_doc：创建或更新跨项目共享文档。

D. 会议管理 (Meeting Management)

• start_meeting：开启新的战术会议，进行专注协作。
• reopen_meeting：重新激活已“关闭”或“归档”的会议以继续讨论。
• end_meeting：结束会议并锁定历史记录（仅限 Host 权限）。
• archive_meeting：将已关闭的会议移动至冷存储（仅限 Host 权限）。

E. 任务管理 (Task Management)

• create_task：创建新的后台任务，可关联会议以实现可追溯性。
• get_task：轮询任务状态、进度（0.0-1.0）及执行结果。
• list_tasks：通过状态过滤查询所有任务。
• update_task：更新进度或结果（通常由 Worker 调用）。
• cancel_task：取消待处理或运行中的任务。

F. 宿主管理 (Host Only)

• host_maintenance：清理或压缩系统日志。
• host_delete_project：彻底移除项目及其关联资产。

📄 资源 (Resources)

核心静态资源

• mcp://nexus/chat/global：实时对话历史。
• mcp://nexus/hub/registry：全局项目注册表 —— 请首先访问此处以发现项目 ID。
• mcp://nexus/docs/global-strategy：核心战略蓝图。
• mcp://nexus/docs/list：共享文档索引。
• mcp://nexus/meetings/list：活跃及已关闭的会议列表。
• mcp://nexus/session：当前会话状态与身份。
• mcp://nexus/status：系统运行状态与存储模式。
• mcp://nexus/active-meeting：当前活跃会议的实时记录。

资源模板 (通过注册表获取 ID)

• mcp://nexus/projects/{projectId}/manifest：特定项目的完整元数据。
• mcp://nexus/projects/{projectId}/internal-docs：特定项目的内部技术文档。
• mcp://nexus/docs/{docId}：读取特定共享文档。
• mcp://nexus/meetings/{meetingId}：读取特定会议的完整记录。

🌐 全局中心架构 (Global Hub Architecture)

v0.3.0 引入了全自动、零配置的协作架构：

┌─────────────────────────────────────────────────────────────┐
│                    Global Nexus Hub                         │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐     │
│  │ Cursor  │   │ VS Code │   │ Claude  │   │ Zed     │     │
│  │ (Guest) │   │ (Guest) │   │ (Host)  │   │ (Guest) │     │
│  └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘     │
│       │             │             │             │           │
│       └─────────────┴──────┬──────┴─────────────┘           │
│                            │ SSE                            │
│                    ┌───────▼───────┐                        │
│                    │   Port 5688   │                        │
│                    │ (Auto-Elected)│                        │
│                    └───────────────┘                        │
└─────────────────────────────────────────────────────────────┘

• 零配置 (Zero Config)：只需运行 npx @datafrog-io/n2n-nexus —— 无需 --id 或 --host 参数。
• 自动竞选 (Auto Election)：第一个启动的实例将绑定 5688 端口并成为 Host；其他实例自动作为 Guest 加入。
• 跨项目同步：所有 IDE 共享同一个 Hub，支持实时的跨项目协作会议。
• 故障自动切换 (Hot Failover)：如果 Host 断开连接，Guest 将在 10 秒内自动提升为新的 Host。

🚀 快速开始

MCP 配置 (推荐)

将以下配置添加到您的 MCP 配置文件中（例如 claude_desktop_config.json 或 Cursor 的 MCP 设置）：

{
  "mcpServers": {
    "n2n-nexus": {
      "command": "npx",
      "args": ["-y", "@datafrog-io/n2n-nexus"]
    }
  }
}

注意：得益于零配置特性，您不再需要手动指定 --id 或 --host。

💾 数据持久化

Nexus 会自动将数据存储在系统的标准用户数据目录（XDG 规范）中。这确保了会议记录和项目资产在 IDE 重启、npx 缓存清理或版本更新后依然存在。

• Linux / WSL: ~/.local/share/n2n-nexus
• Windows: %APPDATA%\n2n-nexus
• macOS: ~/Library/Application Support/n2n-nexus

WSL 用户提示：为优化 I/O 性能，WSL 实例将数据存储在 Linux 文件系统内，而 Windows 实例使用 %APPDATA%。两类环境的数据是隔离的，以防止数据库损坏。