@datafrog-io/n2n-nexus 0.2.0 → 0.3.0

package/build/tools/handlers.js

@@ -32,7 +32,7 @@ export async function handleToolCall(name, toolArgs, ctx) {
         case "upload_project_asset":
             return handleUploadAsset(validatedArgs, ctx);
         case "get_global_topology":
-            return handleGetTopology();
+            return handleGetTopology(validatedArgs);
         case "send_message":
             return handleSendMessage(validatedArgs, ctx);
         case "read_messages":
@@ -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);
@@ -226,8 +226,8 @@ async function handleRenameProject(args, ctx) {
     };
 }
 // --- Global Handlers ---
-async function handleGetTopology() {
-    const topo = await StorageManager.calculateTopology();
+async function handleGetTopology(args) {
+    const topo = await StorageManager.calculateTopology(args?.projectId);
     return { content: [{ type: "text", text: JSON.stringify(topo, null, 2) }] };
 }
 async function handleSendMessage(args, ctx) {
@@ -268,15 +268,25 @@ async function handleSendMessage(args, ctx) {
 }
 async function handleReadMessages(args) {
     const count = args?.count || 10;
-    // If meetingId specified, read from that meeting
+    // If meetingId specified, read from that meeting (with incremental cursor)
     if (args?.meetingId) {
-        const messages = await UnifiedMeetingStore.getRecentMessages(count, args.meetingId);
-        return { content: [{ type: "text", text: JSON.stringify(messages, null, 2) }] };
+        const messages = await UnifiedMeetingStore.getRecentMessages(count, args.meetingId, CONFIG.instanceId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        source: "meeting",
+                        meetingId: args.meetingId,
+                        newMessages: messages.length,
+                        messages
+                    }, null, 2)
+                }]
+        };
     }
     // Check for active meeting first
     const activeMeeting = await UnifiedMeetingStore.getActiveMeeting();
     if (activeMeeting) {
-        const messages = await UnifiedMeetingStore.getRecentMessages(count, activeMeeting.id);
+        const messages = await UnifiedMeetingStore.getRecentMessages(count, activeMeeting.id, CONFIG.instanceId);
         return {
             content: [{
                     type: "text",
@@ -284,12 +294,13 @@ async function handleReadMessages(args) {
                         source: "meeting",
                         meetingId: activeMeeting.id,
                         topic: activeMeeting.topic,
+                        newMessages: messages.length,
                         messages
                     }, null, 2)
                 }]
         };
     }
-    // Fallback to global logs
+    // Fallback to global logs (no incremental support for global yet)
     const logs = await StorageManager.getRecentLogs(count);
     return {
         content: [{
@@ -310,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.");
@@ -326,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
         }
@@ -340,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, {
@@ -369,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.");
@@ -423,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");
@@ -447,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/index.js

@@ -1,13 +1,10 @@
-import { TOOL_REGISTRY } from "./schemas.js";
 /**
- * Dynamically generated Tool Definitions from Zod Schemas.
- * This ensures Tool Registry and Input Validation are always in sync.
- * Using native Zod 4 toJSONSchema support.
+ * Token-Optimized Tool Exports
+ *
+ * Uses hand-crafted minimal definitions instead of Zod toJSONSchema()
+ * to reduce context window consumption by ~60%.
  */
-export const TOOL_DEFINITIONS = Object.entries(TOOL_REGISTRY).map(([name, entry]) => ({
-    name,
-    description: entry.description,
-    inputSchema: entry.schema.toJSONSchema()
-}));
+import { TOOL_DEFINITIONS, ALL_TOOL_DEFINITIONS } from "./definitions.js";
+export { TOOL_DEFINITIONS, ALL_TOOL_DEFINITIONS };
 export { handleToolCall } from "./handlers.js";
 export { TOOL_REGISTRY } from "./schemas.js";

package/build/tools/schemas.js

@@ -62,8 +62,11 @@ export const UploadAssetSchema = z.object({
     base64Content: z.string()
 });
 /**
- * 4. get_global_topology (No arguments)
+ * 4. get_global_topology
  */
+export const TopologySchema = z.object({
+    projectId: ProjectIdSchema.optional().describe("Focus on specific project's subgraph. Omit for summary list.")
+});
 export const EmptySchema = z.object({});
 /**
  * 7. send_message
@@ -108,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
 });
 /**
@@ -200,8 +203,8 @@ export const TOOL_REGISTRY = {
         schema: UploadAssetSchema
     },
     get_global_topology: {
-        description: "Retrieve complete project relationship graph. Returns { nodes: [{ id, name }], edges: [{ from, to, type }] }. Use this to visualize dependencies.",
-        schema: EmptySchema
+        description: "Project topology. Default: list summary. With projectId: detailed subgraph.",
+        schema: TopologySchema
     },
     send_message: {
         description: "Post a message to the Nexus collaboration space. If an active meeting exists, the message is automatically routed to that meeting. Otherwise, it goes to the global discussion log. Use this for proposals, decisions, or general coordination.",
@@ -227,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

@@ -1,24 +1,28 @@
-# Nexus 助手协作指令 (v0.2.0)
+# Nexus 助手协作指令 (v0.2.1)
 
 你现在是 **n2ns Nexus** 协作网络的一员。该系统集成了实时通信、结构化资产管理以及 **异步任务流 (Task Primitives)**，所有操作均落地在本地文件系统。
 
-## 🚦 核心原则：资源读取，工具写入
-为了优化 Token 消耗，Nexus 将**只读信息**暴露为资源 (Resources)，将**执行操作**保留为工具 (Tools)。
+## 🚦 核心原则：渐进式发现，增量读取
+
+Nexus 采用 **Context7 风格** 的渐进加载模式，最大化 Token 效率：
+1. **先 List，再深入** - 获取概览后按需查询详情
+2. **增量读取** - 只获取你未读的消息
+3. **模板 URI** - 从 registry 发现 ID，构造 URI 读取详情
 
 ### 1. 状态发现 (Reading via Resources)
-在任何任务开始前，你**必须**了解环境状态。直接读取对应的 URI 即可，无需消耗工具调用额度：
+在任何任务开始前，你**必须**了解环境状态。直接读取对应的 URI 即可：
 - **查看身份**：`mcp://nexus/session`（你的 ID 和活跃项目）。
 - **系统状态**：`mcp://nexus/status`（版本、存储模式、活跃会议数）。
-- **项目目录**：`mcp://nexus/hub/registry`（公司目前有哪些其他项目）。
+- **项目目录**：`mcp://nexus/hub/registry`（**优先读取** - 发现所有项目 ID）。
 - **会议目录**：`mcp://nexus/meetings/list`（哪些会议正在进行或已结束）。
-- **任务列表**：`mcp://nexus/tasks/list` (TODO: 资源映射中) 或使用 `list_tasks`。
 - **全局文档列表**：`mcp://nexus/docs/list`（有哪些通用规范）。
 
-### 2. 深度查阅 (Deep Reading)
-- **查阅项目**: `mcp://nexus/projects/{id}/manifest` (API 定义/技术栈) 或 `mcp://nexus/projects/{id}/internal-docs` (详细实现文档)。
-- **查阅文档**: `mcp://nexus/docs/{id}`。
-- **查阅会议**: `mcp://nexus/active-meeting` (当前活跃会议全案) 或 `mcp://nexus/meetings/{id}` (指定会议)。
-- **查阅讨论**: `mcp://nexus/chat/global` (全局实时消息流)。
+### 2. 深度查阅 (Template-Based Discovery)
+从目录获取 ID 后，使用模板构造 URI：
+- **查阅项目**: `mcp://nexus/projects/{projectId}/manifest` 或 `mcp://nexus/projects/{projectId}/internal-docs`。
+- **查阅文档**: `mcp://nexus/docs/{docId}`。
+- **查阅会议**: `mcp://nexus/meetings/{meetingId}` 或 `mcp://nexus/active-meeting`。
+- **依赖分析**: `get_global_topology()` 先返回摘要，传 `projectId` 获取详细子图。
 
 ### 3. 项目管理 (Writing via Tools)
 当你需要**改变**状态时，调用工具：
@@ -28,29 +32,31 @@
 - **素材上传**: `upload_project_asset` (架构图转 Base64)。
 
 ### 4. 异步任务流 (Tasks - Phase 2)
-对于耗时较长或可能超时的操作（如大规模同步、重构），你**必须**使用任务原语：
+对于耗时较长或可能超时的操作（如大规模同步、重构），使用任务原语：
 - **创建任务**: `create_task(source_meeting_id?, metadata?)`。返回 `taskId`。
 - **状态轮询**: `get_task(taskId)`。通过 `progress` (0.0-1.0) 了解任务进度。
 - **任务列表**: `list_tasks(status?)`。
 - **取消任务**: `cancel_task(taskId)`。
 
-### 5. 即时沟通 (Collaboration via Tools)
+### 5. 即时沟通 (Incremental Collaboration)
 - **发送消息**: `send_message(message, category?)`。
-- **获取上下文**: `read_messages`。虽然已有资源，但当你需要带参数（如 `count`）获取特定数量的历史记录时，此工具更合适。
+- **获取消息**: `read_messages(count?)`。**[增量模式]** 自动只返回你未读的消息。
 - **更新战略**: `update_global_strategy`（修改全球蓝图）。
 - **文档维护**: `sync_global_doc` (创建/更新通用知识库)。
 
 ### 6. 战术会议 (Tactical Meetings)
 1. **发起**: `start_meeting(topic)`。
 2. **参与**: 发送 category 为 `DECISION` 的消息作为共识。
-3. **结束**: `end_meeting(summary?)`。锁定历史。
-4. **归档**: `archive_meeting(meetingId)`。
+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 能够无缝接手。
+