n2n-nexus 0.4.2 → 0.7.0

package/docs/ASSISTANT_GUIDE.md

@@ -1,120 +1,132 @@
 # Nexus Assistant Guide
 
-你现在是 **n2ns Nexus** 协作网络的一员。Nexus 由一个独立运行的 **daemon** 提供所有能力——你所使用的工具均由 daemon 定义和执行，MCP 只是透明的转发层。
+You are now part of the **n2ns Nexus** coordination network. All capabilities are provided by a standalone **daemon** — every tool you use is defined and executed by the daemon. The MCP adapter is a transparent forwarding layer only.
 
-> **前提**：在使用任何工具之前，确认 daemon 已启动（`n2n-nexus daemon --port 5688`），你的 MCP 已连接（工具列表非空即为已连接）。
+> **Prerequisite**: Before calling any tool, confirm that the daemon is running (`n2n-nexus daemon --port 5688`) and that your MCP is connected (a non-empty tool list means you are connected).
 
 ---
 
-## 🚦 核心原则：先发现，再操作
+## Core principle: discover first, then act
 
-### 1. 了解系统全局状态
+### 1. Understand the global system state
 
-在任何任务开始前，先用以下工具了解环境：
+Before starting any task, use these tools to orient yourself:
 
 ```
-get_global_topology()           → 获取所有项目的摘要列表 + 依赖统计
-get_global_topology(projectId)  → 获取特定项目的详细依赖子图
-search_projects(query)          → 按名称或描述搜索项目
-read_messages(count)            → 获取你尚未读取的消息（增量，自动游标）
+get_global_topology()           → summary list of all projects + dependency stats
+get_global_topology(projectId)  → detailed dependency sub-graph for one project
+search_projects(query)          → search projects by name or description
+get_project(projectId)          → full manifest + internal docs of one project
+read_messages(count)            → fetch messages you have not yet read (incremental, auto-cursor)
 ```
 
-### 2. 声明工作上下文
+### 2. Project IDs
 
-在写入任何项目数据前，必须先声明活跃项目：
+Project operations need no implicit project context: every project tool takes the `projectId` it acts on.
+Project IDs must follow `[prefix]_[name]` format, for example: `web_my-site`, `api_user-auth`, `mcp_nexus`.
+
+### 3. Write project data
 
 ```
-register_session_context(projectId)   → 绑定当前会话到指定项目
+sync_project_assets(manifest, internalDocs)   → sync full project data
+update_project(projectId, patch)              → partial update of manifest fields
+rename_project(oldId, newId)                  → rename and cascade-update all references
+upload_project_asset(projectId, fileName, base64Content) → upload a binary file to the project store
 ```
 
-项目 ID 格式必须为 `[prefix]_[name]`，例如：`web_datafrog.io`、`api_user-auth`、`mcp_nexus`。
+All write tools run synchronously and return their result directly.
 
-### 3. 项目数据写入
+### Direct conversations
 
-```
-sync_project_assets(manifest, internalDocs)   → [ASYNC] 同步项目全量数据，返回 taskId
-update_project(projectId, patch)              → 部分更新 Manifest 字段
-rename_project(oldId, newId)                  → [ASYNC] 重命名并级联更新所有引用
-upload_project_asset(fileName, base64Content) → 上传二进制文件到项目库
-```
+1. Call `list_sessions` to find the exact destination `sessionId`; use `update_session` to set your name and project association.
+2. Send `send_message({ to: sessionId, message: "Please review this change" })`. Inspect `status`: accepted means stored, refused means rejected.
+3. The recipient calls `read_inbox`, then `acknowledge_message({ messageId })` to confirm receipt or passes `outcome: "refused"` to decline.
+4. Reply with `send_message({ to: original.from, replyTo: original.messageId, message: "Review result..." })`. The sender can query `get_message({ messageId })` for the original receipt.
 
-异步操作返回 `taskId`，通过 `get_task(taskId)` 轮询进度（`progress` 0.0→1.0）。
+Unconfirmed fetched messages can appear again; use their IDs to recognize retries. Acknowledgement does not mean work is complete. The inbox is pull-only: there is no automatic model wakeup. Connection restarts create new session IDs; discover the destination again. See [receipt and session contracts](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes).
 
-### 4. 消息与协作
+### 4. Messages and collaboration
 
 ```
-send_message(message, category?)              → 发消息到活跃会议或全局聊天
-read_messages(count?, meetingId?)             → 读取你的未读消息（增量）
-update_global_strategy(content)               → 覆盖写入主战略文档
-sync_global_doc(docId, title, content)        → 创建/更新跨项目共享文档
+send_message(message, category?, meetingId?)  → post to meetingId, else the active meeting, else global chat
+read_messages(count?, meetingId?)             → read your unread messages (incremental)
+list_events(limit?, action?)                  → structured activity log (project.sync, meeting.end, ...)
+get_global_strategy()                         → read the master strategy document
+update_global_strategy(content)               → overwrite the master strategy document
+list_global_docs()                            → list cross-project shared documents
+get_global_doc(docId)                         → read a shared document
+sync_global_doc(docId, title, content)        → create or update a cross-project shared document
 ```
 
-消息分类（`category`）：
-- `CHAT` — 普通讨论（默认）
-- `PROPOSAL` — 提案
-- `DECISION` — 决策/共识
-- `UPDATE` — 进度更新
-- `MEETING_START` — 系统用，无需手动设置
+Message categories (`category`):
+
+- `CHAT` — general discussion (default)
+- `PROPOSAL` — a proposal for others to review
+- `DECISION` — a locked consensus or decision
+- `UPDATE` — a progress update
+- `MEETING_START` — set by the system; do not set manually
 
-### 5. 战术会议
+### 5. Tactical meetings
 
 ```
-start_meeting(topic)              → 开启新会议，返回 meetingId
-send_message("...", "PROPOSAL")   → 在会议中发言
-send_message("...", "DECISION")   → 记录决策
-end_meeting(meetingId?, summary?) → 关闭并锁定会议
-archive_meeting(meetingId)        → 存档（只读）
-reopen_meeting(meetingId)         → 重新开启
+list_meetings(status?, limit?)    → list meetings with status, participants, counts, summary
+start_meeting(topic)              → open a meeting, returns meetingId
+send_message("...", "PROPOSAL")   → post a proposal inside the meeting
+send_message("...", "DECISION")   → record a decision
+end_meeting(meetingId?, summary?) → close and lock the meeting
+archive_meeting(meetingId)        → move to archive (read-only)
+reopen_meeting(meetingId)         → reactivate a closed or archived meeting
 ```
 
-### 6. 后台任务管理
+### 6. Task tracking
 
 ```
-create_task(source_meeting_id?, metadata?)  → 创建任务，返回 taskId
-get_task(taskId)                            → 查询状态和进度
-list_tasks(status?)                         → 列出所有任务
-cancel_task(taskId)                         → 取消任务
+create_task(source_meeting_id?, metadata?)  → create a task you manage yourself, returns taskId
+get_task(taskId)                            → query status and progress
+list_tasks(status?)                         → list all tasks
+cancel_task(taskId)                         → cancel a pending or running task
 ```
 
-### 7. 维护工具
+### 7. Maintenance
 
 ```
-host_maintenance(action, count)   → prune 最旧 N 条日志 / clear 全部
-host_delete_project(projectId)    → [ASYNC] 永久删除项目（不可逆）
+host_maintenance(action, count)   → prune the oldest N global messages / clear all
+host_delete_project(projectId)    → permanently delete a project (irreversible)
 ```
 
 ---
 
-## 📋 典型工作流
+## Typical workflows
+
+### First connection to the system
 
-### 首次接入系统
 ```
-1. get_global_topology()           ← 了解有哪些项目
-2. read_messages(20)               ← 了解最近的讨论
-3. register_session_context(id)    ← 声明我在哪个项目工作
+1. get_global_topology()           ← learn what projects exist
+2. read_messages(20)               ← catch up on recent discussion
+3. get_project(projectId)          ← read the manifest and docs of the project you work on
 ```
 
-### 同步项目数据
+### Sync project data
+
 ```
-1. register_session_context(projectId)
-2. sync_project_assets(manifest, internalDocs)  ← 返回 taskId
-3. get_task(taskId)                             ← 轮询直到 completed
+1. sync_project_assets(manifest, internalDocs)  ← returns { ok, projectId }
 ```
 
-### 发起协作讨论
+### Start a collaborative discussion
+
 ```
 1. start_meeting("Topic")
-2. send_message("我的提案...", "PROPOSAL")
-3. read_messages()                 ← 读取其他实例的回复
-4. send_message("已达成共识", "DECISION")
+2. send_message("My proposal...", "PROPOSAL")
+3. read_messages()                 ← read replies from other instances
+4. send_message("Consensus reached", "DECISION")
 5. end_meeting(meetingId, "summary")
 ```
 
 ---
 
-## ⚠️ 注意事项
+## Notes
 
-- `read_messages` 是**增量的**：每次调用只返回自上次读取后的新消息，游标由 daemon 自动管理，不需要传 `afterId`。
-- 异步操作（`sync_project_assets`、`rename_project`、`host_delete_project`）立即返回 `taskId`，不阻塞。如需等待完成，轮询 `get_task`。
-- 项目 ID 一旦被其他项目引用（`relations`），重命名会自动级联更新所有引用，不需要手动处理。
-- daemon 重启后，你的 MCP 会自动重连并恢复工具列表，无需重启 IDE。
+- `read_messages` is **incremental**: each call returns only messages received since the last read. The cursor is managed automatically by the daemon — do not pass `afterId`.
+- Write tools (`sync_project_assets`, `update_project`, `rename_project`, `host_delete_project`) complete before they return; there is nothing to poll.
+- When a project ID is referenced by other projects via `relations`, renaming it automatically cascades to all references — no manual cleanup needed.
+- After a daemon restart, your MCP reconnects automatically and restores the tool list. You do not need to restart the IDE.

package/docs/README_zh.md

@@ -31,18 +31,18 @@ n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适
 - AI 助手项目注册表
 - 编码 agent 会议和任务协同
 
-n2n-nexus 面向这些场景设计：共享 daemon 状态、无状态 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
+n2n-nexus 面向这些场景设计：共享 daemon 状态、轻量 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
 
 ## n2n-nexus 是什么？
 
 n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自己的聊天上下文，而是可以通过 MCP 读取和更新同一个本地 daemon 中的项目状态。
 
-**TL;DR**
+**Quick summary**
 
 - **安装**：`npx n2n-nexus daemon --port 5688`
 - **协议**：Model Context Protocol (MCP)，适配器通过 HTTP 连接 daemon
 - **存储**：默认在 `~/.n2n-nexus` 下使用本地文件和 SQLite
-- **适合**：多助手编码会话、项目交接、共享决策、会议记录、异步任务、项目 Manifest
+- **适合**：多助手编码会话、项目交接、共享决策、会议记录、任务跟踪、项目 Manifest
 - **不适合**：云端团队聊天、公开项目管理 SaaS、源码索引、向量搜索或远程数据库托管
 
 ## 为什么使用它？
@@ -66,15 +66,17 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
        ▼       ▼       ▼
     MCP-A   MCP-B   MCP-C
    (Win)   (WSL)   (SSH/VM)
-  每个 IDE 一个无状态适配器
+  每条 MCP 连接一个轻量适配器
 ```
 
 - **Daemon 是唯一数据源**：启动一次并保持运行。
-- **MCP 适配器无状态**：每个 IDE 通过 `npx` 启动适配器，然后把工具调用转发给 daemon。
+- **MCP 适配器只维护连接身份**：每个 IDE 通过 `npx` 启动适配器，然后把工具调用转发给 daemon；会话目录和收件箱保存在 daemon。
 - **跨环境协作**：通过 `NEXUS_ENDPOINT` 让不同机器或 shell 指向同一个 daemon。daemon 默认只监听本机；只有在可信网络中才使用 `--host 0.0.0.0`。
 
 ## 快速开始
 
+运行环境要求 Node.js 22.x 中的 22.14.0 或更高版本，或 Node.js 23.6.0 及以上版本。
+
 ### 1. 启动 daemon
 
 ```bash
@@ -110,43 +112,50 @@ npx n2n-nexus daemon --port 5688
 
 ## 工具集
 
-### 会话和上下文
-
-- `register_session_context`：声明当前活跃项目 ID。
-
 ### 项目资产管理
 
 - `sync_project_assets`：提交项目 Manifest 和内部文档。
 - `update_project`：局部更新项目 Manifest。
 - `rename_project`：重命名项目 ID 并更新关联关系。
-- `upload_project_asset`：上传二进制或文本资产。
+- `upload_project_asset`：向指定项目上传二进制或文本资产。
 - `search_projects`：搜索项目注册表。
 - `get_global_topology`：查看项目拓扑和依赖关系。
+- `get_project`：读取项目完整 Manifest 和内部文档。
 
 ### 消息和协作
 
-- `send_message`：发送会议消息或全局消息。
-- `read_messages`：增量读取未读消息。
+- `send_message`：向精确会话 ID 发送定向消息，也保留会议消息和全局消息。
+- `list_sessions` / `update_session`：发现连接，设置自己的名称、项目关联和接收策略。
+- `read_inbox` / `acknowledge_message`：取回个人消息并明确确认或拒绝。
+- `get_message`：查询自己发送或接收的消息状态和回复关联。
+- `read_messages`：增量读取未读消息（全局或指定会议）。
+- `list_events`：读取结构化活动日志（项目同步、重命名、会议结束等）。
+- `get_global_strategy`：读取主策略文档。
 - `update_global_strategy`：更新主策略文档。
+- `list_global_docs`：列出共享文档。
+- `get_global_doc`：读取共享文档。
 - `sync_global_doc`：创建或更新共享文档。
 
+每条 MCP 连接有独立会话 ID；多个聊天若共用连接，仍视为一个会话。在线仅表示近期心跳，消息采用主动拉取，不自动唤醒模型。已存储、已取回、已确认和已回复是不同状态，确认收件不等于任务完成。使用流程见[助手指南](ASSISTANT_GUIDE_zh.md)，精确契约见[工具参考](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes)。
+
 ### 会议管理
 
+- `list_meetings`：列出会议（状态、参与者、消息与决策数、摘要）。
 - `start_meeting`：开启会议会话。
 - `end_meeting`：关闭并锁定会议。
 - `archive_meeting`：归档已关闭会议。
 - `reopen_meeting`：重新打开已关闭或已归档会议。
 
-### 异步任务管理
+### 任务管理
 
-- `create_task`：创建后台任务。
+- `create_task`：创建由助手自行管理的任务。
 - `get_task`：查询任务状态和结果。
 - `list_tasks`：按状态列出任务。
 - `cancel_task`：取消等待中或运行中的任务。
 
 ### 维护
 
-- `host_maintenance`：清理或清空系统日志。
+- `host_maintenance`：清理或清空全局聊天流。
 - `host_delete_project`：删除项目和资产。
 
 ## 数据存储
@@ -209,7 +218,11 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 | `NEXUS_ENDPOINT` | MCP 适配器连接的 daemon 地址 | `http://127.0.0.1:5688` |
 | `NEXUS_ROOT` | daemon 存储根目录 | `~/.n2n-nexus` |
 | `NEXUS_HOST` | daemon 监听地址 | `127.0.0.1` |
-| `NEXUS_INSTANCE_ID` | 覆盖 MCP 实例 ID | 自动生成 |
+| `NEXUS_DAEMON_PORT` | daemon 端口（`--port` 优先） | `5688` |
+| `NEXUS_RATE_LIMIT` | 每个实例每秒工具调用数，每个客户端地址为其 5 倍；`0` 关闭限流 | `20` |
+| `NEXUS_RATE_BURST` | 每个实例可一次性突发的调用数（最小为 1） | `60` |
+| `NEXUS_ALLOWED_HOSTS` | `Host` 头额外允许的域名，逗号分隔（IP、`localhost`、`host.docker.internal` 始终允许） | 空 |
+| `NEXUS_INSTANCE_ID` | 覆盖 MCP 实例 ID（未读游标、会议权限都以它为键） | `mcp-<主机名>-<工作目录哈希>-<IDE 名>` |
 
 ## 安全和治理说明
 
@@ -226,10 +239,12 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 | 文件 | 说明 |
 | --- | --- |
 | [会议纪要](./MEETING_MINUTES_2025-12-29.md) | 结构化决策和测试记录 |
-| [讨论日志](./discussion_2025-12-29_en.md) | 可读的讨论记录 |
+| [讨论日志](./discussion_2025-12-29.md) | 可读的讨论记录 |
 
 ## 本地开发
 
+开发请使用 Node.js 24，与 CI 和 lint 工具链保持一致。
+
 ```bash
 git clone https://github.com/n2ns/n2n-nexus.git
 cd n2n-nexus
@@ -272,7 +287,7 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
 ## 相关文档
 
 - [架构文档](./ARCHITECTURE_zh.md)
-- [AI 助手指南](./ASSISTANT_GUIDE.md)
+- [AI 助手指南](./ASSISTANT_GUIDE_zh.md)
 - [英文 README](../README.md)
 - [llms.txt](../llms.txt)
 
@@ -282,4 +297,4 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
 
 ---
 
-Built by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for practical AI developer tools.
+Built by N2NS Lab, Datafrog's open-source lab for practical AI developer tools.

package/llms.txt

@@ -1,6 +1,16 @@
 # n2n-nexus
 
-n2n-nexus is a local-first Model Context Protocol (MCP) coordination hub from N2NS Lab for multi-AI assistant collaboration. It uses a long-running local daemon as the source of truth and stateless MCP adapters for IDEs and AI coding assistants.
+n2n-nexus is a local-first Model Context Protocol (MCP) coordination hub from N2NS Lab for multi-AI assistant collaboration. It uses a long-running local daemon as the source of truth and lightweight MCP adapters for IDEs and AI coding assistants. Each MCP connection has a discoverable session identity and a pull-based direct inbox with explicit receipts and reply links; messages do not automatically wake models.
+
+## Search intent coverage
+
+- multi-agent MCP coordination
+- multi-AI assistant collaboration
+- local MCP coordination hub
+- shared project context for AI coding agents
+- cross-IDE MCP collaboration server
+- local-first project registry for AI assistants
+- meeting and task coordination for coding agents
 
 ## Core positioning
 
@@ -43,4 +53,4 @@ Default storage root is `~/.n2n-nexus`, containing global docs, project manifest
 
 ## Brand
 
-Built by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for practical AI developer tools.
+Built by N2NS Lab, Datafrog's open-source lab for practical AI developer tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-nexus",
-  "version": "0.4.2",
+  "version": "0.7.0",
   "description": "Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration.",
   "main": "build/index.js",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "build",
+    "assets",
     "README.md",
     "llms.txt",
     "CHANGELOG.md",
@@ -49,6 +50,10 @@
     "ai-developer-tools"
   ],
   "author": "N2NS Lab",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/n2ns"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -59,32 +64,37 @@
     "url": "https://github.com/n2ns/n2n-nexus/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": "^22.14.0 || >=23.6.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"fs.rmSync('build', { recursive: true, force: true })\" && tsc",
     "start": "node build/index.js",
     "daemon": "node build/index.js daemon",
     "dev": "tsc -w",
     "test": "vitest run",
+    "audit": "npm audit",
+    "audit:prod": "npm audit --omit=dev",
+    "pack:dry-run": "npm pack --dry-run",
+    "check": "npm run lint && npm test && npm run build && npm run audit && npm run pack:dry-run",
     "test:publish": "npm run build && npm test && npm pack --dry-run",
     "test:integration": "vitest run tests/daemon_projects.test.ts tests/daemon_messages.test.ts tests/message_cursor.test.ts",
-    "lint": "eslint src/**",
-    "prepublishOnly": "npm run build && npm test"
+    "lint": "eslint src tests",
+    "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.10.1",
-    "zod": "^4.4.3"
+    "@modelcontextprotocol/server": "^2.3.1",
+    "better-sqlite3": "^13.0.3",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^25.9.3",
-    "eslint": "^10.5.0",
-    "lefthook": "^2.1.9",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
+    "lefthook": "^2.2.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.0",
-    "vitest": "^4.1.8"
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^5.0.5"
   }
 }

package/build/storage/logs.js

@@ -1,60 +0,0 @@
-import { promises as fs } from "node:fs";
-import { NexusPaths } from "./paths.js";
-export class LogStorage {
-    static async ensureLogFile() {
-        try {
-            await fs.access(NexusPaths.globalDiscussion);
-        }
-        catch {
-            await fs.writeFile(NexusPaths.globalDiscussion, "[]", "utf-8");
-        }
-    }
-    static async addLog(from, text, category) {
-        await this.ensureLogFile();
-        const logs = await this.getLogs();
-        const payload = {
-            timestamp: new Date().toISOString(),
-            from,
-            text,
-            category: this.normalizeCategory(category)
-        };
-        logs.push(payload);
-        await fs.writeFile(NexusPaths.globalDiscussion, JSON.stringify(logs, null, 2), "utf-8");
-    }
-    static normalizeCategory(category) {
-        if (!category)
-            return undefined;
-        const allowed = ["MEETING_START", "PROPOSAL", "DECISION", "UPDATE", "CHAT", "message", "SYSTEM"];
-        return allowed.includes(category) ? category : "UPDATE";
-    }
-    static async getLogs(limit = 10) {
-        await this.ensureLogFile();
-        const rows = await this.readRawLogs();
-        if (limit <= 0)
-            return rows;
-        return rows.slice(-limit);
-    }
-    static async pruneLogs(count) {
-        const current = await this.readRawLogs();
-        if (count <= 0)
-            return;
-        if (current.length <= count)
-            return;
-        const remaining = current.slice(count);
-        await fs.writeFile(NexusPaths.globalDiscussion, JSON.stringify(remaining, null, 2), "utf-8");
-    }
-    static async clearLogs() {
-        await fs.writeFile(NexusPaths.globalDiscussion, "[]", "utf-8");
-    }
-    static async readRawLogs() {
-        await this.ensureLogFile();
-        try {
-            const raw = await fs.readFile(NexusPaths.globalDiscussion, "utf-8");
-            const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
-        }
-        catch {
-            return [];
-        }
-    }
-}