n2n-nexus 0.4.2

package/docs/ARCHITECTURE.md

@@ -0,0 +1,205 @@
+# Architecture & Standards
+
+## 🏛️ System Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│              n2n-nexus daemon                    │
+│  Standalone HTTP server · User starts manually   │
+│                                                  │
+│  ┌──────────────┐  ┌──────────────────────────┐  │
+│  │  REST API    │  │  Storage Layer           │  │
+│  │  /api/tools  │  │  SQLite (WAL) + JSON FS  │  │
+│  │  /api/tools  │  │                          │  │
+│  │    /call     │  │  Single writer — no lock │  │
+│  └──────┬───────┘  └──────────────────────────┘  │
+│  All business logic, tool definitions, data I/O  │
+└─────────┼────────────────────────────────────────┘
+          │ HTTP  (NEXUS_ENDPOINT — cross-env capable)
+   ┌──────┼──────┐
+   ▼      ▼      ▼
+MCP-A  MCP-B  MCP-C
+(Win)  (WSL)  (VM)
+Stateless protocol adapter, one per IDE
+```
+
+### Core Principles
+
+1. **Daemon is the single source of truth** — all reads/writes, business logic, and tool definitions live in the daemon.
+2. **MCP is a stateless protocol adapter** — no tool definitions, no hardcoded names, no local data.
+3. **Daemon decides tool capability** — MCP fetches `GET /api/tools` at startup; any daemon upgrade is immediately visible to all connected MCPs.
+4. **No local fallback** — if the daemon is unreachable, the MCP reports an error and retries every 3 s. No split-brain degradation.
+5. **Plain HTTP between MCP and daemon** — no SSE; AI is request-driven and doesn't need push.
+
+### MCP Startup Flow
+
+```
+Read NEXUS_ENDPOINT (default: http://127.0.0.1:5688)
+  │
+  ├─ Connect stdio transport → IDE sees MCP as ready
+  │
+  └─ Background retry loop (every 3 s)
+        │
+        ├─ GET /api/tools fails
+        │     → log "[n2n-nexus] Waiting for daemon..."
+        │     → keep retrying, do not exit
+        │
+        └─ GET /api/tools succeeds
+              → cache tool list
+              → send notifications/tools/list_changed
+              → IDE re-fetches: tools appear
+```
+
+---
+
+## 💾 Data Persistence
+
+All data lives under the daemon's storage root (default `~/.n2n-nexus`):
+
+```
+~/.n2n-nexus/
+├── global/
+│   ├── blueprint.md        # Master strategy document
+│   ├── discussion.json     # Global chat (JSON fallback)
+│   ├── docs_index.json     # Global docs index
+│   └── docs/               # Shared markdown documents
+├── projects/
+│   └── {project-id}/
+│       ├── manifest.json          # Project metadata
+│       ├── internal_blueprint.md  # Internal technical docs
+│       └── assets/                # Binary assets (images, PDFs)
+├── meetings/               # Meeting files (JSON fallback mode)
+├── registry.json           # Global project index
+└── nexus.db                # SQLite database (meetings, tasks, cursors)
+```
+
+**SQLite WAL mode**: Only the daemon process writes to SQLite directly. MCP processes never touch the DB — they go through HTTP, which serializes all writes naturally.
+
+**Self-healing**: Core JSON files (`registry.json`, `discussion.json`) are auto-repaired if corrupted or missing.
+
+---
+
+## 🏷️ Project ID Conventions
+
+All project IDs must follow the `[prefix]_[name]` format:
+
+| Prefix | Category | Example |
+|--------|----------|---------|
+| `web_` | Websites | `web_datafrog.io` |
+| `api_` | Backend services | `api_user-auth` |
+| `mcp_` | MCP servers | `mcp_nexus` |
+| `lib_` | Libraries / SDKs | `lib_crypto-core` |
+| `chrome_` | Chrome extensions | `chrome_evisa-helper` |
+| `vscode_` | VSCode extensions | `vscode_super-theme` |
+| `android_` | Android apps | `android_client-app` |
+| `ios_` | iOS apps | `ios_client-app` |
+| `flutter_` | Flutter apps | `flutter_unified-app` |
+| `desktop_` | Desktop apps | `desktop_main-hub` |
+| `bot_` | Bots | `bot_auto-moderator` |
+| `infra_` | Infrastructure / DevOps | `infra_k8s-config` |
+| `doc_` | Documentation | `doc_coding-guide` |
+
+---
+
+## 🌐 Deployment Model
+
+One npm package, two commands:
+
+```
+n2n-nexus
+  │
+  ├─ n2n-nexus daemon    Start once, keep running. Owns all data.
+  │
+  └─ n2n-nexus mcp       IDE starts automatically via npx. Stateless proxy.
+```
+
+**Daemon** (user starts manually):
+```bash
+npx n2n-nexus daemon --port 5688
+# or with explicit root
+npx n2n-nexus daemon --root ~/.n2n-nexus --port 5688
+```
+
+**MCP** (IDE configuration):
+```json
+{
+  "mcpServers": {
+    "n2n-nexus": {
+      "command": "npx",
+      "args": ["-y", "n2n-nexus", "mcp"],
+      "env": { "NEXUS_ENDPOINT": "http://127.0.0.1:5688" }
+    }
+  }
+}
+```
+
+**No required startup order**: start the IDE before the daemon — tools appear automatically once the daemon comes up. Daemon restarts are transparent; MCP reconnects and notifies the IDE.
+
+---
+
+## 📡 REST API
+
+### Tool capability (MCP-facing)
+```
+GET  /api/tools              Return full tool definition list (JSON Schema)
+POST /api/tools/call         Execute tool call { tool, args, instanceId }
+```
+
+### System
+```
+GET  /health                 Health status + version
+GET  /api/storage/info       Storage mode and stats
+```
+
+### Session & Projects
+```
+POST /api/session/register
+POST /api/projects/sync
+POST /api/projects/update
+POST /api/projects/rename
+POST /api/projects/delete
+GET  /api/projects/search
+GET  /api/projects/topology
+```
+
+### Messages & Global
+```
+POST /api/messages/send
+GET  /api/messages/unread
+GET  /api/global/docs
+GET  /api/global/docs/:docId
+POST /api/global/docs/:docId
+POST /api/global/strategy
+```
+
+### Meetings
+```
+POST /api/meetings/start
+POST /api/meetings/end
+POST /api/meetings/archive
+POST /api/meetings/reopen
+GET  /api/meetings/:meetingId
+```
+
+### Tasks
+```
+POST /api/tasks
+GET  /api/tasks
+GET  /api/tasks/:taskId
+POST /api/tasks/:taskId/update
+POST /api/tasks/:taskId/cancel
+```
+
+### Maintenance
+```
+POST /api/maintenance/logs
+```
+
+---
+
+## Scope Boundaries
+
+- No cloud bridge by default.
+- No cross-machine live sync by default — point `NEXUS_ENDPOINT` at a reachable host for that.
+- Single daemon node; no built-in clustering.
+- No authentication layer in the open-source baseline.

package/docs/ARCHITECTURE_zh.md

@@ -0,0 +1,205 @@
+# 架构与标准
+
+## 🏛️ 系统架构
+
+```
+┌──────────────────────────────────────────────────┐
+│              n2n-nexus daemon                    │
+│  独立 HTTP 服务器 · 用户手动启动，持续运行          │
+│                                                  │
+│  ┌──────────────┐  ┌──────────────────────────┐  │
+│  │  REST API    │  │  存储层                   │  │
+│  │  /api/tools  │  │  SQLite（WAL）+ JSON 文件 │  │
+│  │  /api/tools  │  │                          │  │
+│  │    /call     │  │  单进程写入，无锁竞争      │  │
+│  └──────┬───────┘  └──────────────────────────┘  │
+│   全部业务逻辑、工具定义、数据读写均在此处           │
+└─────────┼────────────────────────────────────────┘
+          │ HTTP（NEXUS_ENDPOINT — 可跨环境配置）
+   ┌──────┼──────┐
+   ▼      ▼      ▼
+MCP-A  MCP-B  MCP-C
+(Win)  (WSL)  (VM)
+无状态协议适配器，每个 IDE 一个
+```
+
+### 核心原则
+
+1. **Daemon 是唯一的真相来源** — 所有读写、业务逻辑和工具定义都在 daemon 侧。
+2. **MCP 是无状态协议适配器** — 不含工具定义、不含 hardcode 工具名、不存本地数据。
+3. **Daemon 决定工具能力** — MCP 启动时拉取 `GET /api/tools`；daemon 升级新工具后，所有已连接 MCP 立即获得新能力，无需更新。
+4. **无本地降级** — daemon 不可达时，MCP 每 3 秒重试并报告错误，不做本地 fallback（避免数据分裂）。
+5. **MCP ↔ Daemon 全部走普通 HTTP** — 不使用 SSE；AI 是请求驱动模型，不需要推送。
+
+### MCP 启动流程
+
+```
+读取 NEXUS_ENDPOINT（默认 http://127.0.0.1:5688）
+  │
+  ├─ 连接 stdio transport → IDE 认为 MCP 已就绪
+  │
+  └─ 后台重试循环（每 3 秒）
+        │
+        ├─ GET /api/tools 失败
+        │     → 打印 "[n2n-nexus] Waiting for daemon..."
+        │     → 继续等待，不退出
+        │
+        └─ GET /api/tools 成功
+              → 缓存工具列表
+              → 发送 notifications/tools/list_changed
+              → IDE 重新拉取，工具出现
+```
+
+---
+
+## 💾 数据持久化
+
+所有数据存储在 daemon 的存储根目录下（默认 `~/.n2n-nexus`）：
+
+```
+~/.n2n-nexus/
+├── global/
+│   ├── blueprint.md        # 主战略文档
+│   ├── discussion.json     # 全局聊天（JSON 回退）
+│   ├── docs_index.json     # 全局文档索引
+│   └── docs/               # 共享 Markdown 文档
+├── projects/
+│   └── {project-id}/
+│       ├── manifest.json          # 项目元数据
+│       ├── internal_blueprint.md  # 内部技术文档
+│       └── assets/                # 二进制资产（图片、PDF）
+├── meetings/               # 会议文件（JSON 回退模式）
+├── registry.json           # 全局项目索引
+└── nexus.db                # SQLite 数据库（会议、任务、游标）
+```
+
+**SQLite WAL 模式**：只有 daemon 进程直接写入 SQLite。MCP 进程通过 HTTP 间接访问，天然串行，无并发冲突。
+
+**自我修复**：核心 JSON 文件（`registry.json`、`discussion.json`）在损坏或丢失时自动重建初始状态。
+
+---
+
+## 🏷️ 项目 ID 命名规范
+
+所有项目 ID 必须遵循 `[prefix]_[name]` 格式：
+
+| 前缀 | 分类 | 示例 |
+|------|------|------|
+| `web_` | 网站 | `web_datafrog.io` |
+| `api_` | 后端服务 | `api_user-auth` |
+| `mcp_` | MCP 服务器 | `mcp_nexus` |
+| `lib_` | 库/SDK | `lib_crypto-core` |
+| `chrome_` | Chrome 扩展 | `chrome_evisa-helper` |
+| `vscode_` | VSCode 扩展 | `vscode_super-theme` |
+| `android_` | Android 应用 | `android_client-app` |
+| `ios_` | iOS 应用 | `ios_client-app` |
+| `flutter_` | Flutter 应用 | `flutter_unified-app` |
+| `desktop_` | 桌面应用 | `desktop_main-hub` |
+| `bot_` | 机器人 | `bot_auto-moderator` |
+| `infra_` | 基础设施/DevOps | `infra_k8s-config` |
+| `doc_` | 文档 | `doc_coding-guide` |
+
+---
+
+## 🌐 发布模型
+
+一个 npm 包，两个命令：
+
+```
+n2n-nexus
+  │
+  ├─ n2n-nexus daemon    用户手动启动一次，持续运行，持有所有数据。
+  │
+  └─ n2n-nexus mcp       IDE 通过 npx 自动启动，无状态代理。
+```
+
+**Daemon**（用户手动启动）：
+```bash
+npx n2n-nexus daemon --port 5688
+# 或显式指定存储路径
+npx n2n-nexus daemon --root ~/.n2n-nexus --port 5688
+```
+
+**MCP**（IDE 配置）：
+```json
+{
+  "mcpServers": {
+    "n2n-nexus": {
+      "command": "npx",
+      "args": ["-y", "n2n-nexus", "mcp"],
+      "env": { "NEXUS_ENDPOINT": "http://127.0.0.1:5688" }
+    }
+  }
+}
+```
+
+**无强制启动顺序**：先开 IDE 再启动 daemon 也没问题，工具在 daemon 就绪后自动出现。Daemon 重启对 MCP 透明，自动重连后通知 IDE。
+
+---
+
+## 📡 REST API
+
+### 工具能力（MCP 对接）
+```
+GET  /api/tools              返回完整工具定义列表（JSON Schema）
+POST /api/tools/call         执行工具调用 { tool, args, instanceId }
+```
+
+### 系统
+```
+GET  /health                 健康状态 + 版本信息
+GET  /api/storage/info       存储模式和统计
+```
+
+### 会话与项目
+```
+POST /api/session/register
+POST /api/projects/sync
+POST /api/projects/update
+POST /api/projects/rename
+POST /api/projects/delete
+GET  /api/projects/search
+GET  /api/projects/topology
+```
+
+### 消息与全局协作
+```
+POST /api/messages/send
+GET  /api/messages/unread
+GET  /api/global/docs
+GET  /api/global/docs/:docId
+POST /api/global/docs/:docId
+POST /api/global/strategy
+```
+
+### 会议
+```
+POST /api/meetings/start
+POST /api/meetings/end
+POST /api/meetings/archive
+POST /api/meetings/reopen
+GET  /api/meetings/:meetingId
+```
+
+### 任务
+```
+POST /api/tasks
+GET  /api/tasks
+GET  /api/tasks/:taskId
+POST /api/tasks/:taskId/update
+POST /api/tasks/:taskId/cancel
+```
+
+### 维护
+```
+POST /api/maintenance/logs
+```
+
+---
+
+## 边界说明
+
+- 不默认提供云端桥接。
+- 不默认提供跨机器实时同步——将 `NEXUS_ENDPOINT` 指向可达的主机地址即可实现跨机器访问。
+- 单 daemon 节点，无内置集群能力。
+- 开源基线不包含认证/鉴权层。

package/docs/ASSISTANT_GUIDE.md

@@ -0,0 +1,120 @@
+# Nexus Assistant Guide
+
+你现在是 **n2ns Nexus** 协作网络的一员。Nexus 由一个独立运行的 **daemon** 提供所有能力——你所使用的工具均由 daemon 定义和执行，MCP 只是透明的转发层。
+
+> **前提**：在使用任何工具之前，确认 daemon 已启动（`n2n-nexus daemon --port 5688`），你的 MCP 已连接（工具列表非空即为已连接）。
+
+---
+
+## 🚦 核心原则：先发现，再操作
+
+### 1. 了解系统全局状态
+
+在任何任务开始前，先用以下工具了解环境：
+
+```
+get_global_topology()           → 获取所有项目的摘要列表 + 依赖统计
+get_global_topology(projectId)  → 获取特定项目的详细依赖子图
+search_projects(query)          → 按名称或描述搜索项目
+read_messages(count)            → 获取你尚未读取的消息（增量，自动游标）
+```
+
+### 2. 声明工作上下文
+
+在写入任何项目数据前，必须先声明活跃项目：
+
+```
+register_session_context(projectId)   → 绑定当前会话到指定项目
+```
+
+项目 ID 格式必须为 `[prefix]_[name]`，例如：`web_datafrog.io`、`api_user-auth`、`mcp_nexus`。
+
+### 3. 项目数据写入
+
+```
+sync_project_assets(manifest, internalDocs)   → [ASYNC] 同步项目全量数据，返回 taskId
+update_project(projectId, patch)              → 部分更新 Manifest 字段
+rename_project(oldId, newId)                  → [ASYNC] 重命名并级联更新所有引用
+upload_project_asset(fileName, base64Content) → 上传二进制文件到项目库
+```
+
+异步操作返回 `taskId`，通过 `get_task(taskId)` 轮询进度（`progress` 0.0→1.0）。
+
+### 4. 消息与协作
+
+```
+send_message(message, category?)              → 发消息到活跃会议或全局聊天
+read_messages(count?, meetingId?)             → 读取你的未读消息（增量）
+update_global_strategy(content)               → 覆盖写入主战略文档
+sync_global_doc(docId, title, content)        → 创建/更新跨项目共享文档
+```
+
+消息分类（`category`）：
+- `CHAT` — 普通讨论（默认）
+- `PROPOSAL` — 提案
+- `DECISION` — 决策/共识
+- `UPDATE` — 进度更新
+- `MEETING_START` — 系统用，无需手动设置
+
+### 5. 战术会议
+
+```
+start_meeting(topic)              → 开启新会议，返回 meetingId
+send_message("...", "PROPOSAL")   → 在会议中发言
+send_message("...", "DECISION")   → 记录决策
+end_meeting(meetingId?, summary?) → 关闭并锁定会议
+archive_meeting(meetingId)        → 存档（只读）
+reopen_meeting(meetingId)         → 重新开启
+```
+
+### 6. 后台任务管理
+
+```
+create_task(source_meeting_id?, metadata?)  → 创建任务，返回 taskId
+get_task(taskId)                            → 查询状态和进度
+list_tasks(status?)                         → 列出所有任务
+cancel_task(taskId)                         → 取消任务
+```
+
+### 7. 维护工具
+
+```
+host_maintenance(action, count)   → prune 最旧 N 条日志 / clear 全部
+host_delete_project(projectId)    → [ASYNC] 永久删除项目（不可逆）
+```
+
+---
+
+## 📋 典型工作流
+
+### 首次接入系统
+```
+1. get_global_topology()           ← 了解有哪些项目
+2. read_messages(20)               ← 了解最近的讨论
+3. register_session_context(id)    ← 声明我在哪个项目工作
+```
+
+### 同步项目数据
+```
+1. register_session_context(projectId)
+2. sync_project_assets(manifest, internalDocs)  ← 返回 taskId
+3. get_task(taskId)                             ← 轮询直到 completed
+```
+
+### 发起协作讨论
+```
+1. start_meeting("Topic")
+2. send_message("我的提案...", "PROPOSAL")
+3. read_messages()                 ← 读取其他实例的回复
+4. send_message("已达成共识", "DECISION")
+5. end_meeting(meetingId, "summary")
+```
+
+---
+
+## ⚠️ 注意事项
+
+- `read_messages` 是**增量的**：每次调用只返回自上次读取后的新消息，游标由 daemon 自动管理，不需要传 `afterId`。
+- 异步操作（`sync_project_assets`、`rename_project`、`host_delete_project`）立即返回 `taskId`，不阻塞。如需等待完成，轮询 `get_task`。
+- 项目 ID 一旦被其他项目引用（`relations`），重命名会自动级联更新所有引用，不需要手动处理。
+- daemon 重启后，你的 MCP 会自动重连并恢复工具列表，无需重启 IDE。