@datafrog-io/n2n-nexus 0.2.1 → 0.3.0

package/README.md

@@ -10,77 +10,14 @@
 
 > **Works with:** Claude Code · Claude Desktop · VS Code · Cursor · Windsurf · Zed · JetBrains · Theia · Google Antigravity
 
-📖 **Documentation:** [CHANGELOG](CHANGELOG.md) | [TODO](TODO.md) | [中文文档](docs/README_zh.md) | [AI Assistant Guide](docs/ASSISTANT_GUIDE.md)
-
-## 🏛️ Architecture
-
-1.  **Nexus Room (Discussion)**: Unified public channel for all IDE assistants to coordinate across projects.
-2.  **Asset Vault (Archives)**:
-    - **Manifest**: Technical details, billing, topology, and API specs for each project.
-    - **Internal Docs**: Detailed technical implementation plans.
-    - **Assets**: Local physical assets (Logos, UI screenshots, etc.).
-3.  **Global Knowledge**:
-    - **Master Strategy**: Top-level strategic blueprint.
-    - **Global Docs**: Cross-project common documents (e.g., Coding Standards, Roadmaps).
-4.  **Topology Engine**: Automated dependency graph analysis.
-
-## 💾 Data Persistence
-
-Nexus stores all data in the local file system (customizable path), ensuring complete data sovereignty.
-
-**Directory Structure Example**:
-```text
-Nexus_Storage/
-├── global/
-│   ├── blueprint.md       # Master Strategy
-│   ├── discussion.json    # Global Chat History (fallback)
-│   ├── docs_index.json    # Global Docs Index
-│   └── docs/              # Global Markdown Docs
-│       ├── coding-standards.md
-│       └── deployment-flow.md
-├── projects/
-│   └── {project-id}/
-│       ├── manifest.json          # Project Metadata
-│       ├── internal_blueprint.md  # Technical Implementation Docs
-│       └── assets/                # Binary Assets (images, PDFs)
-├── meetings/              # Meeting files (JSON fallback mode)
-│   └── {meeting-id}.json
-├── registry.json          # Global Project Index
-├── archives/              # Reserved for backups
-└── nexus.db               # SQLite Database (meetings, tasks, state)
-```
-
-**Self-healing**: Core data files (e.g., `registry.json`, `discussion.json`) include automatic detection and repair mechanisms. If files are corrupted or missing, the system automatically rebuilds the initial state to ensure uninterrupted service.
-
-**Concurrency Safety**: All write operations to shared files (`discussion.json`, `registry.json`) are protected by an `AsyncMutex` lock, preventing race conditions when multiple AI agents communicate simultaneously.
-
-## 🏷️ Project ID Conventions (Naming Standard)
-
-To ensure clarity and prevent collisions in the flat local namespace, all Project IDs MUST follow the **Prefix Dictionary** format: `[prefix]_[project-name]`.
+📖 **Documentation:** [CHANGELOG](CHANGELOG.md) | [TODO](TODO.md) | [中文文档](docs/README_zh.md) | [AI Assistant Guide](docs/ASSISTANT_GUIDE.md) | [Architecture](docs/ARCHITECTURE.md)
 
-| Prefix | Category | Example |
-| :--- | :--- | :--- |
-| `web_` | Websites, landing pages, domain-based projects | `web_datafrog.io` |
-| `api_` | Backend services, REST/gRPC APIs | `api_user-auth` |
-| `chrome_` | Chrome extensions | `chrome_evisa-helper` |
-| `vscode_` | VSCode extensions | `vscode_super-theme` |
-| `mcp_` | MCP Servers and MCP-related tools | `mcp_github-repo` |
-| `android_` | Native Android projects (Kotlin/Java) | `android_client-app` |
-| `ios_` | Native iOS projects (Swift/ObjC) | `ios_client-app` |
-| `flutter_` | **Mobile Cross-platform Special Case** | `flutter_unified-app` |
-| `desktop_` | General desktop apps (Tauri, Electron, etc.) | `desktop_main-hub` |
-| `lib_` | Shared libraries, SDKs, NPM/Python packages | `lib_crypto-core` |
-| `bot_` | Bots (Discord, Slack, DingTalk, etc.) | `bot_auto-moderator` |
-| `infra_` | Infrastructure as Code, CI/CD, DevOps scripts | `infra_k8s-config` |
-| `doc_` | Pure technical handbooks, strategies, roadmaps | `doc_coding-guide` |
-
----
 
 ## 🛠️ Toolset
 
 ### A. Session & Context
 - `register_session_context`: Declare the project ID currently active in the IDE to unlock write permissions.
-- `mcp://nexus/session`: View current identity, role (Moderator/Regular), and active project.
+- `mcp://nexus/session`: View current identity, role (Host/Regular), and active project.
 
 ### B. Project Asset Management
 - `sync_project_assets`: **[Core/ASYNC]** Submit full Project Manifest and Internal Docs. Returns `taskId`.
@@ -101,8 +38,8 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 ### D. Meeting Management
 - `start_meeting`: Start a new tactical session for focused collaboration.
 - `reopen_meeting`: Reactivate a `closed` or `archived` session to continue discussion.
-- `end_meeting`: Conclude a meeting, lock history (**Moderator only**).
-- `archive_meeting`: Move closed meetings to cold storage (**Moderator only**).
+- `end_meeting`: Conclude a meeting, lock history (**Host only**).
+- `archive_meeting`: Move closed meetings to cold storage (**Host only**).
 
 ### E. Task Management (Phase 2 - ASYNC)
 - `create_task`: Create a new background task. Link to meeting for traceability.
@@ -111,9 +48,9 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 - `update_task`: Update progress or result (typically for workers).
 - `cancel_task`: Cancel a pending or running task.
 
-### F. Admin (Moderator Only)
-- `moderator_maintenance`: Prune or clear system logs.
-- `moderator_delete_project`: Completely remove a project and its assets.
+### F. Host (Host Only)
+- `host_maintenance`: Prune or clear system logs.
+- `host_delete_project`: Completely remove a project and its assets.
 
 ## 📄 Resources (URI)
 
@@ -133,13 +70,39 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 - `mcp://nexus/docs/{docId}`: Read a specific shared document.
 - `mcp://nexus/meetings/{meetingId}`: Full transcript for a specific meeting.
 
+## 🌐 Global Hub Architecture
+
+**v0.3.0** introduces a fully automatic, zero-configuration collaboration architecture:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Global Nexus Hub                         │
+│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐     │
+│  │ Cursor  │   │ VS Code │   │ Claude  │   │ Zed     │     │
+│  │ (Guest) │   │ (Guest) │   │ (Host)  │   │ (Guest) │     │
+│  └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘     │
+│       │             │             │             │           │
+│       └─────────────┴──────┬──────┴─────────────┘           │
+│                            │ SSE                            │
+│                    ┌───────▼───────┐                        │
+│                    │   Port 5688   │                        │
+│                    │ (Auto-Elected)│                        │
+│                    └───────────────┘                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Zero Config**: Just run `npx @datafrog-io/n2n-nexus` - no `--id` or `--host` required.
+- **Auto Election**: First instance binds port 5688 and becomes Host; others join as Guests.
+- **Cross-Project Sync**: All IDEs share the same Hub, enabling real-time cross-project meetings.
+- **Hot Failover**: If Host disconnects, a Guest automatically promotes within 10 seconds.
+
 ## 🚀 Quick Start
 
 ### MCP Configuration (Recommended)
 
 Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP settings):
 
-#### Moderator (Admin AI)
+#### Leader AI
 ```json
 {
   "mcpServers": {
@@ -148,8 +111,6 @@ Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP se
       "args": [
         "-y",
         "@datafrog-io/n2n-nexus",
-        "--id", "Master-AI",
-        "--moderator",
         "--root", "D:/DevSpace/Nexus_Storage"
       ]
     }
@@ -157,7 +118,7 @@ Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP se
 }
 ```
 
-#### Regular AI
+#### Collaborator AI
 ```json
 {
   "mcpServers": {
@@ -166,7 +127,6 @@ Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP se
       "args": [
         "-y",
         "@datafrog-io/n2n-nexus",
-        "--id", "Assistant-AI",
         "--root", "D:/DevSpace/Nexus_Storage"
       ]
     }
@@ -177,11 +137,9 @@ Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP se
 ### CLI Arguments
 | Argument | Description | Default |
 |----------|-------------|---------|
-| `--id` | Instance identifier for this AI agent | `Assistant` |
-| `--moderator` | Grant admin privileges to this instance | `false` |
 | `--root` | Local storage path for all Nexus data | `./storage` |
 
-> **Note:** Only instances with `--moderator` flag can use admin tools (e.g., `moderator_maintenance`).
+> **Note:** Host identity and Instance ID are determined automatically based on the project folder name and startup order.
 
 ### Local Development
 ```bash
@@ -189,7 +147,7 @@ git clone https://github.com/n2ns/n2n-nexus.git
 cd n2n-nexus
 npm install
 npm run build
-npm start -- --id Master-AI --root ./my-storage
+npm start -- --root ./my-storage
 ```
 
 ---
@@ -213,4 +171,13 @@ The following files demonstrate a real orchestration session where **4 AI agents
 > *This is what AI-native development looks like.*
 
 ---
-© 2025 datafrog.io. Built for Local-Only AI Workflows.
+
+## ⭐ Support This Project
+
+If **n2ns Nexus** helps you build better AI workflows, consider giving it a star! Your support helps us improve and motivates continued development.
+
+[![Star on GitHub](https://img.shields.io/github/stars/n2ns/n2n-nexus?style=social)](https://github.com/n2ns/n2n-nexus)
+
+---
+
+© 2026 datafrog.io. Built for Local-Only AI Workflows.

package/build/config.js

@@ -1,14 +1,186 @@
 import path from "path";
 import { fileURLToPath } from "url";
+import os from "os";
+import fs from "fs";
+import http from "http";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
+// Load version from package.json
+const pkgPath = path.resolve(__dirname, "../package.json");
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
 const getArg = (k) => {
     const i = args.indexOf(k);
     return i !== -1 && args[i + 1] ? args[i + 1] : "";
 };
-const hasFlag = (k) => args.includes(k);
+const hasFlag = (k) => args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
+// --- CLI Commands Handlers ---
+if (hasFlag("--help") || hasFlag("-h")) {
+    console.log(`
+n2ns Nexus 🚀 - Local Digital Asset Hub (MCP Server) v${pkg.version}
+
+USAGE:
+  npx -y @datafrog-io/n2n-nexus [options]
+
+DESCRIPTION:
+  A local-first project management and collaboration hub designed for 
+  multi-AI assistant coordination across different IDEs (Cursor, VS Code, etc.).
+
+OPTIONS:
+  --root <path>     Directory for data persistence. Default: ./storage
+  --version, -v     Show version number.
+  --help, -h        Show this message.
+
+MCP CONFIG EXAMPLE (claude_desktop_config.json):
+  {
+    "mcpServers": {
+      "n2n-nexus": {
+        "command": "npx",
+        "args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
+      }
+    }
+  }
+
+ENVIRONMENT VARIABLES:
+  NEXUS_ROOT        Override default storage path.
+    `);
+    process.exit(0);
+}
+if (hasFlag("--version") || hasFlag("-v")) {
+    console.log(pkg.version);
+    process.exit(0);
+}
+// --- Path Normalization Logic ---
+function normalizeRootPath(inputPath) {
+    // 1. Priority: CLI --root > ENV NEXUS_ROOT > Default ./storage
+    let root = inputPath || process.env.NEXUS_ROOT || path.join(__dirname, "../storage");
+    // 2. Resolve ~ to home directory
+    if (root.startsWith("~")) {
+        root = path.join(os.homedir(), root.slice(1));
+    }
+    // 3. Cross-platform adaptation (WSL <-> Windows)
+    // If running on Linux (WSL) but path looks like Windows (D:/ or C:\\)
+    if (process.platform === "linux" && /^[a-zA-Z]:[/\\]/.test(root)) {
+        const drive = root[0].toLowerCase();
+        root = `/mnt/${drive}${root.slice(2).replace(/\\/g, "/")}`;
+    }
+    return path.resolve(root);
+}
+/**
+ * Probe a port to see if it's a Nexus Host
+ */
+async function probeHost(port) {
+    return new Promise((resolve) => {
+        const req = http.get(`http://127.0.0.1:${port}/hello`, { timeout: 500 }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => data += chunk);
+            res.on("end", () => {
+                try {
+                    const info = JSON.parse(data);
+                    if (info.service === "n2n-nexus" && info.role === "host") {
+                        resolve({ isNexus: true, rootStorage: info.rootStorage });
+                    }
+                    else {
+                        resolve({ isNexus: false });
+                    }
+                }
+                catch {
+                    resolve({ isNexus: false });
+                }
+            });
+        });
+        req.on("error", () => resolve({ isNexus: false }));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve({ isNexus: false });
+        });
+    });
+}
+/**
+ * Automatic Host Election (Port-Based 5688-5700)
+ * Strategy: Probe-First + Atomic Bind + Join Winner on Failure
+ *
+ * 1. First, scan all ports to find existing Host
+ * 2. If found, join it immediately
+ * 3. If not found, try to become Host
+ * 4. If bind fails, wait and re-probe (give winner time to start)
+ */
+async function isHostAutoElection(root) {
+    const startPort = 5688;
+    const endPort = 5700;
+    // Phase 1: Probe-First - Check if any Host already exists
+    for (let port = startPort; port <= endPort; port++) {
+        const probe = await probeHost(port);
+        if (probe.isNexus) {
+            return { isHost: false, port, rootStorage: probe.rootStorage };
+        }
+    }
+    // Phase 2: No Host found, attempt to become Host
+    for (let port = startPort; port <= endPort; port++) {
+        const result = await new Promise((resolve) => {
+            const server = http.createServer((req, res) => {
+                if (req.url === "/hello") {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        service: "n2n-nexus",
+                        role: "host",
+                        version: pkg.version,
+                        rootStorage: root
+                    }));
+                    return;
+                }
+                res.writeHead(404);
+                res.end();
+            });
+            server.on("error", (err) => {
+                if (err.code === "EADDRINUSE") {
+                    resolve({ isHost: false });
+                }
+                else {
+                    resolve({ isHost: false });
+                }
+            });
+            server.listen(port, "127.0.0.1", () => {
+                resolve({ isHost: true, server });
+            });
+        });
+        if (result.isHost) {
+            return { isHost: true, port, server: result.server };
+        }
+        // Phase 3: Bind failed - another Guest won. Wait then join winner.
+        await new Promise(r => setTimeout(r, 10000)); // Give winner 10s to start /hello
+        const probe = await probeHost(port);
+        if (probe.isNexus) {
+            return { isHost: false, port, rootStorage: probe.rootStorage };
+        }
+        // If still not Nexus, try next port (occupied by non-Nexus service)
+    }
+    // Fallback: become Host on startPort (should rarely happen)
+    return { isHost: true, port: startPort };
+}
+/**
+ * Automatic Project Name Detection
+ */
+function getAutoProjectName() {
+    try {
+        const pkgPath = path.join(process.cwd(), "package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (pkg.name)
+                return pkg.name.split("/").pop() || pkg.name;
+        }
+    }
+    catch { /* ignore */ }
+    return path.basename(process.cwd()) || "Assistant";
+}
+const rootPath = normalizeRootPath(getArg("--root"));
+const election = await isHostAutoElection(rootPath);
+const projectName = getAutoProjectName();
+export const hostServer = election.server;
 export const CONFIG = {
-    instanceId: getArg("--id") || "Assistant",
-    isModerator: hasFlag("--moderator"),
-    rootStorage: path.resolve(getArg("--root") || path.join(__dirname, "../storage"))
+    // Priority: CLI --id > Auto-named (Project Name only)
+    instanceId: getArg("--id") || projectName,
+    isHost: election.isHost,
+    // Inherit storage path if Guest, otherwise use local resolved path
+    rootStorage: election.isHost ? rootPath : (election.rootStorage || rootPath),
+    port: election.port
 };

package/build/index.js

@@ -2,15 +2,17 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { readFileSync } from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
-import { CONFIG } from "./config.js";
+import http from "http";
+import { CONFIG, hostServer } from "./config.js";
 import { StorageManager } from "./storage/index.js";
 import { TOOL_DEFINITIONS, handleToolCall } from "./tools/index.js";
 import { listResources, getResourceContent } from "./resources/index.js";
 import { sanitizeErrorMessage } from "./utils/error.js";
-import { checkModeratorPermission } from "./utils/auth.js";
+import { checkHostPermission } from "./utils/auth.js";
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 /**
@@ -21,6 +23,7 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8")
 class NexusServer {
     server;
     currentProject = null;
+    sseTransports = new Map();
     constructor() {
         this.server = new Server({ name: "n2n-nexus", version: pkg.version }, { capabilities: { resources: {}, tools: {}, prompts: {} } });
         this.setupHandlers();
@@ -62,8 +65,8 @@ class NexusServer {
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: toolArgs } = request.params;
             try {
-                if (name.startsWith("moderator_"))
-                    checkModeratorPermission(name);
+                if (name.startsWith("host_"))
+                    checkHostPermission(name);
                 const result = await handleToolCall(name, toolArgs, {
                     currentProject: this.currentProject,
                     setCurrentProject: (id) => { this.currentProject = id; },
@@ -131,29 +134,143 @@ class NexusServer {
         const shutdown = async (signal) => {
             console.error(`\n[Nexus] Received ${signal}. Shutting down...`);
             try {
-                // Post-departure log
                 const msg = `Nexus Session Terminated (IDE Closed).`;
                 await StorageManager.addGlobalLog(`SYSTEM:${CONFIG.instanceId}`, msg, "UPDATE");
                 console.error(`[Nexus:${CONFIG.instanceId}] Goodbye!`);
             }
-            catch {
-                // Ignore if storage is already cleaned up
-            }
+            catch { /* ignore */ }
             process.exit(0);
         };
         process.on("SIGINT", () => shutdown("SIGINT"));
         process.on("SIGTERM", () => shutdown("SIGTERM"));
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
-        // Announce presence
-        try {
+        if (CONFIG.isHost && hostServer) {
+            // --- HOST MODE: Central Hub ---
             await StorageManager.init();
-            const onlineMsg = `Nexus Session Active (IDE Opened). Role: ${CONFIG.isModerator ? "Moderator" : "Regular"}`;
+            hostServer.on("request", async (req, res) => {
+                const url = new URL(req.url || "", `http://${req.headers.host}`);
+                if (url.pathname === "/mcp") {
+                    const guestId = url.searchParams.get("id") || "UnknownGuest";
+                    if (req.method === "GET") {
+                        const transport = new SSEServerTransport("/mcp", res);
+                        this.sseTransports.set(transport.sessionId, transport);
+                        const msg = `Guest Joined: ${guestId}`;
+                        await StorageManager.addGlobalLog(`HOST:${CONFIG.instanceId}`, msg, "UPDATE");
+                        console.error(`[Nexus Hub] ${msg} (Session: ${transport.sessionId})`);
+                        // Heartbeat: keep connection alive
+                        const heartbeat = setInterval(() => {
+                            try {
+                                res.write(": ping\n\n");
+                            }
+                            catch {
+                                clearInterval(heartbeat);
+                            }
+                        }, 30000);
+                        transport.onclose = () => {
+                            this.sseTransports.delete(transport.sessionId);
+                            clearInterval(heartbeat);
+                            console.error(`[Nexus Hub] Guest Left: ${guestId}`);
+                        };
+                        await this.server.connect(transport);
+                        return;
+                    }
+                    else if (req.method === "POST") {
+                        const sessionId = url.searchParams.get("sessionId");
+                        const transport = sessionId ? this.sseTransports.get(sessionId) : null;
+                        if (transport) {
+                            await transport.handlePostMessage(req, res);
+                        }
+                        else {
+                            res.writeHead(404).end("Session unknown");
+                        }
+                        return;
+                    }
+                }
+            });
+            // Support local stdio for the host's own IDE
+            const transport = new StdioServerTransport();
+            await this.server.connect(transport);
+            const onlineMsg = `Nexus Hub Active. Playing Host.`;
             await StorageManager.addGlobalLog(`SYSTEM:${CONFIG.instanceId}`, onlineMsg, "UPDATE");
-            console.error(`[Nexus:${CONFIG.instanceId}] ${onlineMsg}`);
+            console.error(`[Nexus:${CONFIG.instanceId}] ${onlineMsg} (Port: ${CONFIG.port})`);
         }
-        catch (e) {
-            console.error("[Nexus] Failed to post online message:", e);
+        else {
+            // --- GUEST MODE: SSE Proxy ---
+            const guestId = CONFIG.instanceId;
+            // Random delay function to prevent thundering herd during re-election
+            const randomDelay = () => Math.floor(Math.random() * 3000);
+            const startProxy = () => {
+                // Clear any stale stdin listeners before starting
+                process.stdin.removeAllListeners("data");
+                console.error(`[Nexus:${guestId}] Global Hub detected at ${CONFIG.port}. Joining...`);
+                let sessionId = null;
+                let lastActivity = Date.now();
+                // Watchdog: trigger re-election if Host is silent for too long
+                const watchdog = setInterval(() => {
+                    if (Date.now() - lastActivity > 60000) {
+                        console.error("[Nexus Guest] Host stale. Triggering re-election...");
+                        cleanup();
+                        // Random delay to prevent all guests from racing for the port
+                        setTimeout(() => this.run(), randomDelay());
+                    }
+                }, 10000);
+                const cleanup = () => {
+                    clearInterval(watchdog);
+                    process.stdin.removeAllListeners("data");
+                };
+                const stdioHandler = (chunk) => {
+                    if (!sessionId)
+                        return;
+                    try {
+                        const req = http.request({
+                            hostname: "127.0.0.1",
+                            port: CONFIG.port,
+                            path: `/mcp?sessionId=${sessionId}&id=${guestId}`,
+                            method: "POST",
+                            headers: { "Content-Type": "application/json" }
+                        });
+                        // Handle request errors to prevent unhandled exceptions
+                        req.on("error", () => { });
+                        req.write(chunk);
+                        req.end();
+                    }
+                    catch { /* suppress */ }
+                };
+                process.stdin.on("data", stdioHandler);
+                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${guestId}`, (res) => {
+                    let buffer = "";
+                    res.on("data", (chunk) => {
+                        lastActivity = Date.now();
+                        const str = chunk.toString();
+                        buffer += str;
+                        if (!sessionId && buffer.includes("event: endpoint")) {
+                            const match = buffer.match(/sessionId=([a-f0-9-]+)/);
+                            if (match)
+                                sessionId = match[1];
+                        }
+                        if (str.includes("event: message")) {
+                            const lines = str.split("\n");
+                            const dataLine = lines.find((l) => l.startsWith("data: "));
+                            if (dataLine) {
+                                try {
+                                    process.stdout.write(dataLine.substring(6) + "\n");
+                                }
+                                catch { }
+                            }
+                        }
+                    });
+                    res.on("end", () => {
+                        console.error("[Nexus Guest] Lost connection to Host. Re-electing...");
+                        cleanup();
+                        // Random delay for re-election
+                        setTimeout(() => this.run(), randomDelay());
+                    });
+                }).on("error", () => {
+                    console.error("[Nexus Guest] Proxy Receive Error. Retry with random delay...");
+                    cleanup();
+                    setTimeout(() => this.run(), 1000 + randomDelay());
+                });
+            };
+            startProxy();
         }
     }
 }

package/build/resources/index.js

@@ -22,8 +22,8 @@ export async function getResourceContent(uri, currentProject) {
     if (uri === "mcp://nexus/session") {
         const info = {
             yourId: CONFIG.instanceId,
-            role: CONFIG.isModerator ? "Moderator" : "Regular",
-            isModerator: CONFIG.isModerator,
+            role: CONFIG.isHost ? "Host" : "Regular",
+            isHost: CONFIG.isHost,
             activeProject: currentProject || "None"
         };
         return { mimeType: "application/json", text: JSON.stringify(info, null, 2) };

package/build/tools/definitions.js

@@ -166,7 +166,7 @@ const ALL_TOOLS = [
     },
     {
         name: "end_meeting",
-        description: "[Moderator] End active meeting. Locks history.",
+        description: "[Host] End active meeting. Locks history.",
         inputSchema: {
             type: "object",
             properties: {
@@ -177,7 +177,7 @@ const ALL_TOOLS = [
     },
     {
         name: "archive_meeting",
-        description: "[Moderator] Archive closed meeting. Read-only after.",
+        description: "[Host] Archive closed meeting. Read-only after.",
         inputSchema: {
             type: "object",
             properties: {
@@ -258,10 +258,10 @@ const ALL_TOOLS = [
             required: ["taskId"]
         }
     },
-    // --- Admin (Moderator Only) ---
+    // --- Host (Host Only) ---
     {
-        name: "moderator_maintenance",
-        description: "[Moderator] Manage logs: 'prune' oldest N or 'clear' all.",
+        name: "host_maintenance",
+        description: "[Host] Manage logs: 'prune' oldest N or 'clear' all.",
         inputSchema: {
             type: "object",
             properties: {
@@ -272,8 +272,8 @@ const ALL_TOOLS = [
         }
     },
     {
-        name: "moderator_delete_project",
-        description: "[ASYNC][Moderator] Delete project. Irreversible. Returns taskId.",
+        name: "host_delete_project",
+        description: "[ASYNC][Host] Delete project. Irreversible. Returns taskId.",
         inputSchema: {
             type: "object",
             properties: {

package/build/tools/handlers.js

@@ -45,10 +45,10 @@ export async function handleToolCall(name, toolArgs, ctx) {
             return handleUpdateProject(validatedArgs);
         case "rename_project":
             return handleRenameProject(validatedArgs, ctx);
-        case "moderator_delete_project":
+        case "host_delete_project":
             return handleRemoveProject(validatedArgs, ctx);
-        case "moderator_maintenance":
-            return handleModeratorMaintenance(validatedArgs, ctx);
+        case "host_maintenance":
+            return handleHostMaintenance(validatedArgs, ctx);
         // --- Meeting Tools ---
         case "start_meeting":
             return handleStartMeeting(validatedArgs, ctx);
@@ -321,12 +321,12 @@ async function handleUpdateStrategy(args, _ctx) {
     return { content: [{ type: "text", text: "Strategy updated." }] };
 }
 /**
- * ASYNC: moderator_delete_project now returns a taskId.
+ * ASYNC: host_delete_project now returns a taskId.
  */
 async function handleRemoveProject(args, ctx) {
-    // Defense-in-Depth: Explicit moderator check
-    if (!CONFIG.isModerator) {
-        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only moderators can delete projects.");
+    // Defense-in-Depth: Explicit host check
+    if (!CONFIG.isHost) {
+        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only hosts can delete projects.");
     }
     if (!args?.projectId)
         throw new McpError(ErrorCode.InvalidParams, "projectId is required.");
@@ -337,7 +337,7 @@ async function handleRemoveProject(args, ctx) {
     // Create background task
     const task = createTask({
         metadata: {
-            operation: "moderator_delete_project",
+            operation: "host_delete_project",
             projectId: args.projectId,
             initiator: CONFIG.instanceId
         }
@@ -351,7 +351,7 @@ async function handleRemoveProject(args, ctx) {
             ctx.notifyResourceUpdate("mcp://nexus/hub/registry");
             ctx.notifyResourceUpdate("mcp://nexus/get_global_topology");
             updateTask(task.id, { status: "completed", progress: 1.0 });
-            await StorageManager.addGlobalLog("SYSTEM", `[${CONFIG.instanceId}] Task Completed: Project '${args.projectId}' deleted by moderator.`);
+            await StorageManager.addGlobalLog("SYSTEM", `[${CONFIG.instanceId}] Task Completed: Project '${args.projectId}' deleted by host.`);
         }
         catch (error) {
             updateTask(task.id, {
@@ -380,10 +380,10 @@ async function handleSyncGlobalDoc(args) {
     return { content: [{ type: "text", text: `Global document '${args.docId}' synchronized.` }] };
 }
 // --- Admin Handlers ---
-async function handleModeratorMaintenance(args, ctx) {
-    // Defense-in-Depth: Explicit moderator check
-    if (!CONFIG.isModerator) {
-        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only moderators can perform maintenance.");
+async function handleHostMaintenance(args, ctx) {
+    // Defense-in-Depth: Explicit host check
+    if (!CONFIG.isHost) {
+        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only hosts can perform maintenance.");
     }
     if (!args.action || args.count === undefined) {
         throw new McpError(ErrorCode.InvalidParams, "Both 'action' and 'count' are mandatory for maintenance.");
@@ -434,9 +434,9 @@ async function handleEndMeeting(args, ctx) {
             throw new McpError(ErrorCode.InvalidRequest, "No active meeting found to end. Please specify meetingId.");
         targetId = active.id;
     }
-    // STRICT: Only moderators can end meetings
-    if (!CONFIG.isModerator) {
-        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only moderators can end meetings.");
+    // STRICT: Only hosts can end meetings
+    if (!CONFIG.isHost) {
+        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only hosts can end meetings.");
     }
     const { meeting, suggestedSyncTargets } = await UnifiedMeetingStore.endMeeting(targetId, args.summary, undefined);
     ctx.notifyResourceUpdate("mcp://nexus/status");
@@ -458,9 +458,9 @@ async function handleEndMeeting(args, ctx) {
 async function handleArchiveMeeting(args, _ctx) {
     if (!args.meetingId)
         throw new McpError(ErrorCode.InvalidParams, "meetingId is required.");
-    // STRICT: Only moderators can archive meetings
-    if (!CONFIG.isModerator) {
-        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only moderators can archive meetings.");
+    // STRICT: Only hosts can archive meetings
+    if (!CONFIG.isHost) {
+        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Only hosts can archive meetings.");
     }
     await UnifiedMeetingStore.archiveMeeting(args.meetingId, undefined);
     return {

package/build/tools/schemas.js

@@ -111,16 +111,16 @@ export const RenameProjectSchema = z.object({
     newId: ProjectIdSchema
 });
 /**
- * 15. moderator_maintenance
+ * 15. host_maintenance
  */
-export const ModeratorMaintenanceSchema = z.object({
+export const HostMaintenanceSchema = z.object({
     action: z.enum(["prune", "clear"]),
     count: z.number().int().min(0)
 });
 /**
- * 16. moderator_delete_project
+ * 16. host_delete_project
  */
-export const ModeratorDeleteSchema = z.object({
+export const HostDeleteSchema = z.object({
     projectId: ProjectIdSchema
 });
 /**
@@ -230,24 +230,24 @@ export const TOOL_REGISTRY = {
         description: "[ASYNC] Rename a project ID with automatic cascading updates to all relation references. Returns task ID.",
         schema: RenameProjectSchema
     },
-    moderator_maintenance: {
-        description: "[ADMIN ONLY] Manage global discussion logs. 'prune' removes the oldest N entries (keeps newest). 'clear' wipes all logs (use count=0). Returns summary of removed entries. Irreversible.",
-        schema: ModeratorMaintenanceSchema
+    host_maintenance: {
+        description: "[HOST ONLY] Manage global discussion logs. 'prune' removes the oldest N entries (keeps newest). 'clear' wipes all logs (use count=0). Returns summary of removed entries. Irreversible.",
+        schema: HostMaintenanceSchema
     },
-    moderator_delete_project: {
-        description: "[ASYNC][ADMIN ONLY] Completely remove a project, its manifest, and all its assets from Nexus Hub. Returns task ID. Irreversible.",
-        schema: ModeratorDeleteSchema
+    host_delete_project: {
+        description: "[ASYNC][HOST ONLY] Completely remove a project, its manifest, and all its assets from Nexus Hub. Returns task ID. Irreversible.",
+        schema: HostDeleteSchema
     },
     start_meeting: {
         description: "Start a new meeting session. Creates a dedicated file for the meeting. Returns the meeting ID and details.",
         schema: StartMeetingSchema
     },
     end_meeting: {
-        description: "End an active meeting. Locks the session for further messages. [RESTRICTED: Only moderator can end].",
+        description: "End an active meeting. Locks the session for further messages. [RESTRICTED: Only host can end].",
         schema: EndMeetingSchema
     },
     archive_meeting: {
-        description: "Archive a closed meeting. Archived meetings are read-only and excluded from active queries. [RESTRICTED: Only moderator can archive].",
+        description: "Archive a closed meeting. Archived meetings are read-only and excluded from active queries. [RESTRICTED: Only host can archive].",
         schema: ArchiveMeetingSchema
     },
     reopen_meeting: {

package/build/utils/auth.js

@@ -1,11 +1,11 @@
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { CONFIG } from "../config.js";
 /**
- * Validates moderator permissions for admin tools.
- * @throws McpError if current session is not in Moderator mode.
+ * Validates host permissions for privileged tools.
+ * @throws McpError if current session is not in Host mode.
  */
-export function checkModeratorPermission(toolName) {
-    if (!CONFIG.isModerator) {
-        throw new McpError(ErrorCode.InvalidRequest, `Forbidden: ${toolName} requires Moderator rights.`);
+export function checkHostPermission(toolName) {
+    if (!CONFIG.isHost) {
+        throw new McpError(ErrorCode.InvalidRequest, `Forbidden: ${toolName} requires Host rights.`);
     }
 }

package/docs/ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Architecture & Standards
+
+## 🏛️ Architecture
+
+1.  **Nexus Room (Discussion)**: Unified public channel for all IDE assistants to coordinate across projects.
+2.  **Asset Vault (Archives)**:
+    -   **Manifest**: Technical details, billing, topology, and API specs for each project.
+    -   **Internal Docs**: Detailed technical implementation plans.
+    -   **Assets**: Local physical assets (Logos, UI screenshots, etc.).
+3.  **Global Knowledge**:
+    -   **Master Strategy**: Top-level strategic blueprint.
+    -   **Global Docs**: Cross-project common documents (e.g., Coding Standards, Roadmaps).
+4.  **Topology Engine**: Automated dependency graph analysis.
+
+## 💾 Data Persistence
+
+Nexus stores all data in the local file system (customizable path), ensuring complete data sovereignty.
+
+**Directory Structure Example**:
+```text
+Nexus_Storage/
+├── global/
+│   ├── blueprint.md       # Master Strategy
+│   ├── discussion.json    # Global Chat History (fallback)
+│   ├── docs_index.json    # Global Docs Index
+│   └── docs/              # Global Markdown Docs
+│       ├── coding-standards.md
+│       └── deployment-flow.md
+├── projects/
+│   └── {project-id}/
+│       ├── manifest.json          # Project Metadata
+│       ├── internal_blueprint.md  # Technical Implementation Docs
+│       └── assets/                # Binary Assets (images, PDFs)
+├── meetings/              # Meeting files (JSON fallback mode)
+│   └── {meeting-id}.json
+├── registry.json          # Global Project Index
+├── archives/              # Reserved for backups
+└── nexus.db               # SQLite Database (meetings, tasks, state)
+```
+
+**Self-healing**: Core data files (e.g., `registry.json`, `discussion.json`) include automatic detection and repair mechanisms. If files are corrupted or missing, the system automatically rebuilds the initial state to ensure uninterrupted service.
+
+**Concurrency Safety**: All write operations to shared files (`discussion.json`, `registry.json`) are protected by an `AsyncMutex` lock, preventing race conditions when multiple AI agents communicate simultaneously.
+
+## 🏷️ Project ID Conventions (Naming Standard)
+
+To ensure clarity and prevent collisions in the flat local namespace, all Project IDs MUST follow the **Prefix Dictionary** format: `[prefix]_[project-name]`.
+
+| Prefix | Category | Example |
+| :--- | :--- | :--- |
+| `web_` | Websites, landing pages, domain-based projects | `web_datafrog.io` |
+| `api_` | Backend services, REST/gRPC APIs | `api_user-auth` |
+| `chrome_` | Chrome extensions | `chrome_evisa-helper` |
+| `vscode_` | VSCode extensions | `vscode_super-theme` |
+| `mcp_` | MCP Servers and MCP-related tools | `mcp_github-repo` |
+| `android_` | Native Android projects (Kotlin/Java) | `android_client-app` |
+| `ios_` | Native iOS projects (Swift/ObjC) | `ios_client-app` |
+| `flutter_` | **Mobile Cross-platform Special Case** | `flutter_unified-app` |
+| `desktop_` | General desktop apps (Tauri, Electron, etc.) | `desktop_main-hub` |
+| `lib_` | Shared libraries, SDKs, NPM/Python packages | `lib_crypto-core` |
+| `bot_` | Bots (Discord, Slack, DingTalk, etc.) | `bot_auto-moderator` |
+| `infra_` | Infrastructure as Code, CI/CD, DevOps scripts | `infra_k8s-config` |
+| `doc_` | Pure technical handbooks, strategies, roadmaps | `doc_coding-guide` |

package/docs/ARCHITECTURE_zh.md

@@ -0,0 +1,43 @@
+# 架构与标准 (Architecture & Standards)
+
+## 🏛️ 系统架构 (Architecture)
+
+1.  **Nexus Room (讨论区)**: 所有 IDE 助手的统一公域频道，用于跨项目协调。
+2.  **Asset Vault (归档库)**: 
+    - **Manifest**: 每个项目的技术细节、计费、拓扑关系、API 规范。
+    - **Internal Docs**: 每个项目的详细技术实施方案。
+    - **Assets**: 本地物理素材存储（Logo/UI 截图等）。
+3.  **Global Knowledge (全局知识库)**:
+    - **Master Strategy**: 顶层战略总纲。
+    - **Global Docs**: 跨项目的通用文档（如编码规范、路线图）。
+4.  **Topology Engine**: 自动分析项目间的依赖关系图谱。
+
+## 💾 数据持久化 (Data Persistence)
+
+Nexus 将所有数据存储在本地文件系统中（默认路径可配置），完全掌控数据主权。
+
+**目录结构示例**:
+```text
+Nexus_Storage/
+├── global/
+│   ├── blueprint.md       # Master Strategy
+│   ├── discussion.json    # 全局聊天历史 (fallback)
+│   ├── docs_index.json    # 全局文档索引
+│   └── docs/              # 全局 Markdown 文档
+│       ├── coding-standards.md
+│       └── deployment-flow.md
+├── projects/
+│   └── {project-id}/
+│       ├── manifest.json          # 项目元数据
+│       ├── internal_blueprint.md  # 技术实现文档
+│       └── assets/                # 二进制资产 (图片、PDF)
+├── meetings/              # 会议文件 (JSON 回退模式)
+│   └── {meeting-id}.json
+├── registry.json          # 全局项目索引
+├── archives/              # 归档备份 (保留)
+└── nexus.db               # SQLite 数据库 (会议、任务、状态)
+```
+
+**自我修复 (Self-healing)**: 核心数据文件（如 `registry.json`, `discussion.json`）具备自动检测与修复机制。如果文件损坏或意外丢失，系统会自动重建初始状态，确保服务不中断。
+
+**多并发安全 (Concurrency Safety)**: 对共享文件（`discussion.json`, `registry.json`）的所有写入操作均受 `AsyncMutex` 锁保护，防止多个 AI 代理同时通信时发生竞争条件。

package/docs/ASSISTANT_GUIDE.md

@@ -47,15 +47,15 @@ Nexus 采用 **Context7 风格** 的渐进加载模式，最大化 Token 效率
 ### 6. 战术会议 (Tactical Meetings)
 1. **发起**: `start_meeting(topic)`。
 2. **参与**: 发送 category 为 `DECISION` 的消息作为共识。
-3. **结束**: `end_meeting(summary?)`。锁定历史（**Moderator only**）。
-4. **归档**: `archive_meeting(meetingId)`（**Moderator only**）。
+3. **结束**: `end_meeting(summary?)`。锁定历史（**Host only**）。
+4. **归档**: `archive_meeting(meetingId)`（**Host only**）。
 5. **重开**: `reopen_meeting(meetingId)`。
 
 ---
 
 ## 🛡️ 角色说明
 - **Regular**: 拥有注册、同步、讨论和维护文档的完整权限。
-- **Moderator**: 额外拥有清理记录（`moderator_maintenance`）、结束/归档会议及物理删除（`moderator_delete_project`）的权限。
+- **Host**: 管理员实例（通常是第一个启动的实例），额外拥有清理记录（`host_maintenance`）、结束/归档会议及物理删除（`host_delete_project`）的权限。
 
 ## ❌ 退出机制
 本系统是对本地磁盘的原子写入。请确保同步时提供清晰的 `internalDocs`，以便其他 Assistant 能够无缝接手。

package/docs/CHANGELOG_zh.md

@@ -2,6 +2,50 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [v0.3.0] - 2026-01-08
+
+### 🌐 全局 Hub 架构 (零配置多 IDE 协作)
+
+此版本引入了全自动的 Host 选举和全局 Hub 架构，无需任何配置即可实现多 IDE 无缝协作。
+
+#### 自动 Host 选举 (基于端口)
+- **端口范围 5688-5700**: 首个绑定端口的实例成为 Host，其余成为 Guest。
+- **探测优先策略**: Guest 在尝试绑定前先扫描已有 Host，消除竞态条件。
+- **Hello 握手协议**: `/hello` 端点验证 Nexus 身份，区分其他服务。
+- **10 秒接管窗口**: 绑定失败后，Guest 等待 10 秒再探测加入胜者。
+
+#### 全局 Hub (基于 SSE 通讯)
+- **单一 Hub 架构**: 所有 IDE（不论哪个项目）都连接到同一个 Host，实现跨项目协作。
+- **Stdio-to-SSE 代理**: Guest 透明地将 IDE 流量转发到 Host。
+- **多会话路由**: Host 维护会话映射，支持多个 Guest 并发连接。
+- **存储路径继承**: Host 广播 `rootStorage` 路径；Guest 继承它以实现无缝故障转移。
+
+#### 心跳与看门狗 (高可用)
+- **Host 心跳**: Host 每 30 秒发送 `: ping` 保持连接活跃。
+- **Guest 看门狗**: Guest 监控活动；若 60 秒无响应，自动触发重选。
+- **热故障转移**: 存活的 Guest 自动使用继承的存储路径升迁为新 Host。
+
+#### 术语重构
+- **Moderator → Host**: 所有代码、测试和文档已更新。
+- **`isModerator` → `isHost`**: API 和配置属性已重命名。
+- **`moderator_*` → `host_*`**: 工具名已更新（如 `host_maintenance`）。
+
+#### 零配置体验
+- **`--id` 弃用**: 实例 ID 现在自动从项目文件夹名派生。
+- **`--host` 移除**: Host 角色通过端口绑定自动确定。
+- **简化 CLI**: 只需 `npx @datafrog-io/n2n-nexus` 即可开始。
+
+| 指标 | 之前 | 之后 |
+|------|------|------|
+| 必需 CLI 参数 | 2-3 | 0-1 |
+| 手动 Host 设置 | 需要 | 自动 |
+| 多 IDE 同步 | 基于文件 | SSE 实时 |
+| 故障转移时间 | 手动重启 | < 10 秒 |
+
+#### 测试覆盖
+- 新增 `election.test.ts`，包含 9 个覆盖探测、绑定和竞争场景的测试用例。
+- 全部 55 个测试通过。
+
 ## [v0.2.1] - 2026-01-01
 
 ### 🚀 Token 经济深度优化
@@ -49,6 +93,6 @@
 ## [v0.2.0] - 2025-12-31
 
 ### 🚀 任务原语系统 (Phase 2 & 3)
-- **异步深耕**: 关键阻塞操作 (`rename_project`, `moderator_delete_project`) 迁移至 Task 原语，支持背景级联更新。
+- **异步深耕**: 关键阻塞操作 (`rename_project`, `host_delete_project`) 迁移至 Task 原语，支持背景级联更新。
 - **可追溯性**: 所有任务现在都支持 `source_meeting_id`，将执行结果与会议决策关联。
 - **进度展示**: 增加了进度追踪 (0.0-1.0) 和 `result_uri` 结构化输出。

package/docs/README_zh.md

@@ -10,53 +10,15 @@
 
 > **支持的 IDE：** Claude Code · Claude Desktop · VS Code · Cursor · Windsurf · Zed · JetBrains · Theia · Google Antigravity
 
-📖 **文档导航:** [English README](../README.md) | [更新日志](TODO_zh.md) | [AI 助手指南](ASSISTANT_GUIDE.md)
-
-## 🏛️ 系统架构 (Architecture)
-
-1.  **Nexus Room (讨论区)**: 所有 IDE 助手的统一公域频道，用于跨项目协调。
-2.  **Asset Vault (归档库)**: 
-    - **Manifest**: 每个项目的技术细节、计费、拓扑关系、API 规范。
-    - **Internal Docs**: 每个项目的详细技术实施方案。
-    - **Assets**: 本地物理素材存储（Logo/UI 截图等）。
-3.  **Global Knowledge (全局知识库)**:
-    - **Master Strategy**: 顶层战略总纲。
-    - **Global Docs**: 跨项目的通用文档（如编码规范、路线图）。
-4.  **Topology Engine**: 自动分析项目间的依赖关系图谱。
-
-## � 数据持久化 (Data Persistence)
-
-Nexus 将所有数据存储在本地文件系统中（默认路径可配置），完全掌控数据主权。
-
-**目录结构示例**:
-```text
-Nexus_Storage/
-├── global/
-│   ├── blueprint.md       # Master Strategy
-│   ├── discussion.json    # 全局聊天历史 (fallback)
-│   ├── docs_index.json    # 全局文档索引
-│   └── docs/              # 全局 Markdown 文档
-│       ├── coding-standards.md
-│       └── deployment-flow.md
-├── projects/
-│   └── {project-id}/
-│       ├── manifest.json          # 项目元数据
-│       ├── internal_blueprint.md  # 技术实现文档
-│       └── assets/                # 二进制资产 (图片、PDF)
-├── meetings/              # 会议文件 (JSON 回退模式)
-│   └── {meeting-id}.json
-├── registry.json          # 全局项目索引
-├── archives/              # 归档备份 (保留)
-└── nexus.db               # SQLite 数据库 (会议、任务、状态)
-```
+📖 **文档导航:** [English README](../README.md) | [更新日志](TODO_zh.md) | [AI 助手指南](ASSISTANT_GUIDE.md) | [架构文档](ARCHITECTURE_zh.md)
+
 
-**自我修复 (Self-healing)**: 核心数据文件（如 `registry.json`, `discussion.json`）具备自动检测与修复机制。如果文件损坏或意外丢失，系统会自动重建初始状态，确保服务不中断。
 
 ## �🛠️ 工具集 (Toolset)
 
 ### A. 会话与上下文 (Session)
 - `register_session_context`: 声明当前 IDE 工作的项目 ID，解锁写权限。
-- `mcp://nexus/session`: 查看当前身份、角色（Moderator/Regular）及活动项目。
+- `mcp://nexus/session`: 查看当前身份、角色（Host/Regular）及活动项目。
 
 ### B. 项目资产管理 (Project Assets)
 - `sync_project_assets`: **[核心/异步]** 提交完整的项目 Manifest 和内部技术文档。返回 `taskId`。
@@ -76,8 +38,8 @@ Nexus_Storage/
 ### D. 会议管理 (Tactical Meetings)
 - `start_meeting`: 开启新的战术讨论会议。
 - `reopen_meeting`: 重新开启已“关闭”或“归档”的会议。
-- `end_meeting`: 结束会议，锁定历史记录 (**仅限管理员 Moderator**)。
-- `archive_meeting`: 将已结束的会议移至存档 (**仅限管理员 Moderator**)。
+- `end_meeting`: 结束会议，锁定历史记录 (**仅限 Host**)。
+- `archive_meeting`: 将已结束的会议移至存档 (**仅限 Host**)。
 
 ### E. 任务管理 (Phase 2 - 异步)
 - `create_task`: 创建新的后台任务。关联会议以实现溯源。
@@ -86,9 +48,9 @@ Nexus_Storage/
 - `update_task`: 更新任务进度或结果（通常供 Worker 调用）。
 - `cancel_task`: 取消待处理或运行中的任务。
 
-### F. 管理员工具 (仅限 Moderator)
-- `moderator_maintenance`: 清理或修剪系统日志。
-- `moderator_delete_project`: 彻底删除项目及其所有资产。
+### F. 主持者工具 (仅限 Host)
+- `host_maintenance`: 清理或修剪系统日志。
+- `host_delete_project`: 彻底删除项目及其所有资产。
 
 ## 📄 资源 URI (Resources)
 
@@ -108,13 +70,39 @@ Nexus_Storage/
 - `mcp://nexus/docs/{docId}`: 读取特定的全局共享文档。
 - `mcp://nexus/meetings/{meetingId}`: 特定会议的完整记录。
 
+## 🌐 全局 Hub 架构
+
+**v0.3.0** 引入了全自动、零配置的协作架构：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    全局 Nexus Hub                           │
+│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐     │
+│  │ Cursor  │   │ VS Code │   │ Claude  │   │ Zed     │     │
+│  │ (Guest) │   │ (Guest) │   │ (Host)  │   │ (Guest) │     │
+│  └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘     │
+│       │             │             │             │           │
+│       └─────────────┴──────┬──────┴─────────────┘           │
+│                            │ SSE                            │
+│                    ┌───────▼───────┐                        │
+│                    │   端口 5688   │                        │
+│                    │  (自动选举)   │                        │
+│                    └───────────────┘                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **零配置**: 只需运行 `npx @datafrog-io/n2n-nexus` — 无需 `--id` 或 `--host`。
+- **自动选举**: 首个实例绑定 5688 端口成为 Host；其余自动加入为 Guest。
+- **跨项目同步**: 所有 IDE 共享同一个 Hub，实现实时跨项目会议。
+- **热故障转移**: 若 Host 断开，Guest 将在 10 秒内自动升迁。
+
 ## 🚀 快速启动
 
 ### MCP 配置（推荐）
 
 在你的 MCP 配置文件中（如 `claude_desktop_config.json` 或 Cursor MCP 设置）添加：
 
-#### 主持者（管理员 AI）
+#### 主导 AI
 ```json
 {
   "mcpServers": {
@@ -123,8 +111,6 @@ Nexus_Storage/
       "args": [
         "-y",
         "@datafrog-io/n2n-nexus",
-        "--id", "Master-AI",
-        "--moderator",
         "--root", "D:/DevSpace/Nexus_Storage"
       ]
     }
@@ -132,7 +118,7 @@ Nexus_Storage/
 }
 ```
 
-#### 普通 AI
+#### 协同 AI (Guest)
 ```json
 {
   "mcpServers": {
@@ -141,7 +127,6 @@ Nexus_Storage/
       "args": [
         "-y",
         "@datafrog-io/n2n-nexus",
-        "--id", "Assistant-AI",
         "--root", "D:/DevSpace/Nexus_Storage"
       ]
     }
@@ -152,11 +137,9 @@ Nexus_Storage/
 ### 命令行参数
 | 参数 | 说明 | 默认值 |
 |------|------|--------|
-| `--id` | 当前 AI 助手的实例标识符 | `Assistant` |
-| `--moderator` | 授予此实例管理员权限 | `false` |
 | `--root` | 本地数据存储路径 | `./storage` |
 
-> **注意：** 仅带有 `--moderator` 标志的实例可使用管理员工具（如 `moderator_maintenance` 和 `moderator_delete_project`）。
+> **注意：** 实例 ID（默认为当前项目文件夹名称）和 Host 身份将根据启动顺序自动生成。
 
 ### 本地开发
 ```bash
@@ -164,7 +147,7 @@ git clone https://github.com/n2ns/n2n-nexus.git
 cd n2n-nexus
 npm install
 npm run build
-npm start -- --id Master-AI --root ./my-storage
+npm start -- --root ./my-storage
 ```
 
 ---
@@ -187,4 +170,13 @@ npm start -- --id Master-AI --root ./my-storage
 > *这就是 AI 原生开发的协作方式。*
 
 ---
-© 2025 datafrog.io. Built for Local-Only AI Workflows.
+
+## ⭐ 支持本项目
+
+如果 **n2ns Nexus** 帮助您构建了更好的 AI 工作流，考虑给我们一个 Star 吧！您的支持是我们持续改进的动力。
+
+[![Star on GitHub](https://img.shields.io/github/stars/n2ns/n2n-nexus?style=social)](https://github.com/n2ns/n2n-nexus)
+
+---
+
+© 2026 datafrog.io. Built for Local-Only AI Workflows.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datafrog-io/n2n-nexus",
-    "version": "0.2.1",
+    "version": "0.3.0",
     "description": "Unified Project Asset & Collaboration Hub (MCP Server) designed for AI agent coordination, featuring structured metadata, real-time messaging, and dependency topology.",
     "main": "build/index.js",
     "type": "module",