# NetMesh 系统总结

> 项目代号：Netcatty · 版本：v2.x · 日期：2026-10-30

---

## 一、项目定位

**NetMesh（品牌名 Netcatty）** 是一款 **AI 原生的 SSH 客户端 / 网络运维终端 / 服务器管理平台**，以"让 AI 帮你管服务器"为核心理念，面向开发者、运维工程师、DevOps 团队。

它不是一个纯终端工具，而是一个**终端 + SFTP + 主机库 + 巡检监控 + 告警处置 + AI Agent + MCP Server + 云同步 + 插件生态**的完整平台。

---

## 二、核心功能清单

### 2.1 主机与连接管理

| 功能 | 说明 |
|------|------|
| 多协议主机支持 | SSH / Telnet / Mosh / ET（自研加密协议）/ 本地 Shell / Serial 串口 / 插件扩展协议 |
| 跳板机链路 | 多级跳板机链式连接，自动探测最优路径 |
| 代理配置 | HTTP / SOCKS5 代理，每台主机独立或全局配置 |
| 算法覆写 | 不同主机支持不同加密算法、KEX、MAC 协商策略 |
| 主机分组与标签 | 任意层级分组、自定义标签，支持按分组批量操作 |
| Host Key 管理 | known_hosts 自动维护、指纹校验、信任策略配置 |
| SSH Agent 转发 | 支持系统 SSH Agent 和内置 Agent |
| 凭据安全存储 | AES-GCM 加密存储私钥和密码，内存中零明文 |

### 2.2 终端能力

| 功能 | 说明 |
|------|------|
| 多终端分割 | 拖拽式工作区分割，水平/垂直/自由布局，支持标签页 |
| xterm.js 6 渲染 | WebGL 加速、图片渲染、搜索高亮、序列化回放 |
| 终端主题 | 内置 20+ 主题，支持自定义配色 |
| 命令历史 | 跨终端会话命令历史、模糊搜索、智能推荐 |
| 片段（Snippets） | 常用命令片段库，一键插入，支持参数化模板 |
| 快捷键绑定 | Vim/Emacs/自定义快捷键方案 |
| 防刷屏与截断 | 长输出自动截断 + 查看完整内容 |
| 终端录屏 | 会话录制为 JSON 序列化文件，离线回放 |

### 2.3 SFTP 文件管理

| 功能 | 说明 |
|------|------|
| 双栏文件浏览 | 本地/远程双栏同步滚动，拖拽上传下载 |
| 断点续传 | 大文件传输中断后自动续传 |
| SCP 后端 | 原生 SCP 协议支持（自研后端，不依赖外部库） |
| 文件搜索 | 递归搜索、按类型/大小/时间过滤 |
| 文件编辑 | Monaco Editor 内置编辑，SFTP 远程编辑即时保存 |
| 传输中心 | 全局传输队列、速度显示、失败重试、并发控制 |
| 临时文件安全 | 所有下载到本地的临时文件通过专用 tempDir 管理，程序退出自动清理 |

### 2.4 端口转发

| 功能 | 说明 |
|------|------|
| 本地转发（L） | 本地端口 → 远程主机端口 |
| 远程转发（R） | 远程主机端口 → 本地端口 |
| 动态转发（SOCKS5） | 本地 SOCKS5 代理 → 通过远程主机出网 |
| 隧道管理 | 多隧道并发、状态监控、自动重连、流量统计 |

### 2.5 巡检与监控

| 功能 | 说明 |
|------|------|
| 定时巡检调度 | 可配置周期、并发度、超时、重试策略 |
| 多设备类型适配 | 路由器 / 交换机 / 服务器 / 防火墙，每类设备独立采集适配器 |
| 巡检指标 | CPU / 内存 / 磁盘 / 网络 / 进程 / 服务 / 端口 / GPU / Docker |
| 健康评分 | 每台设备巡检后计算综合健康分 |
| 拓扑视图 | 大屏可视化监控，按告警等级着色，实时刷新 |
| 巡检报告 | 自动生成巡检报告，支持 AI 汇总（内置 AI 对巡检结果做自然语言总结） |
| 远程 HTTP API | 内置轻量 HTTP 服务器，支持外部系统调用巡检 API、获取告警、推送到大屏 |

### 2.6 告警系统（v2.x 新增）

| 功能 | 说明 |
|------|------|
| 告警规则引擎 | 指标阈值、持续时间、触发次数、告警等级（info/warning/critical） |
| 多通道通知 | Desktop 弹窗、Webhook（钉钉/企业微信/飞书/自定义） |
| 告警中心页 | 活动告警列表、历史告警、ACK 确认、关闭、备注 |
| 规则分组 | 按设备类型、分组、标签批量绑定规则 |
| **AI 预案匹配**（设计中） | 告警触发后匹配预设的"值班员动作预案 + 操作级预案"双轨配置 |
| **AI 初始响应包**（设计中） | 告警触发时 AI 自动生成结构化响应包，嵌入大屏弹窗，值班员可直接转发运维群 |
| **聚合升级**（设计中） | 时间窗口内多台设备同类型告警自动升级 |
| **AI 处置执行**（设计中） | 预案中的可执行步骤由 AI Agent 自动/半自动执行 |

### 2.7 AI Agent 系统（核心差异化能力）

| 能力 | 说明 |
|------|------|
| 内置 AI 对话（Catty） | 侧边栏 AI 对话面板，多厂商 LLM 接入 |
| AI 多主机编排 | 一个指令同时操作多台主机（"所有核心交换机 show version"） |
| AI 自动执行命令 | 三种执行权限：observer（只看不写）/ confirm（写需确认）/ auto（全自动） |
| 安全审批机制 | 危险命令自动拦截、执行前弹窗审批、审批记录审计 |
| AI 上下文感知 | 自动知道当前终端会话、当前主机、当前告警、巡检历史 |
| AI 压缩与记忆 | 长对话自动摘要压缩，413 Token 超限自动降级处理 |
| Codex App Server | 实验性 Codex 持久化运行时，支持原生审批、线程/Turn 管理 |

### 2.8 MCP Server（Model Context Protocol）

| 能力 | 说明 |
|------|------|
| 内置 MCP stdio 服务器 | 让 Claude Desktop / Cursor / Cline / Codex 等外部 AI 代理操作 NetMesh 连接的主机 |
| 能力暴露 | 30+ 目录命令（终端/SFTP/Vault/端口转发/巡检/片段/harness）通过统一的 RPC 分发 |
| 权限控制 | MCP 会话的 observer / confirm / auto 三级模式 |
| MCP Tool Registry | 代码生成驱动，新增能力自动暴露到 MCP |

### 2.9 云同步

| 能力 | 说明 |
|------|------|
| 多后端支持 | GitHub Gist / Google Drive / OneDrive / S3 / WebDAV |
| CRDT 收敛同步 | 自研无冲突复制数据类型，支持多端并发编辑收敛 |
| 端到端加密 | 所有同步数据 AES-GCM 加密，密钥本地派生 |
| 同步范围 | 主机库 / 密钥 / 片段 / 分组 / 标签 / 设置 |
| 冲突解决 | 自动检测冲突、合并、或提示手动选择 |

### 2.10 插件系统

| 能力 | 说明 |
|------|------|
| 插件包格式 | `.ncpkg` 格式，原子发布、版本化、沙箱运行 |
| 沙箱隔离 | 普通插件运行在 BrowserWindow 沙箱 + 离线网络 |
| Node-only 插件 | 高级开发模式：utilityProcess 运行、有限 Node API |
| 插件 RPC | `PluginRpcRouter` 负责请求关联、取消、超时、流量限制 |
| 插件安全 | 禁止访问本地文件系统、禁止连接外网、插件间完全隔离 |

### 2.11 其他

| 能力 | 说明 |
|------|------|
| 应用锁 | Windows Hello / 系统级密码锁 |
| 主题与外观 | 明暗主题、强调色、终端主题独立配置 |
| 国际化 | 多语言框架 |
| 键盘快捷键 | 全局快捷键可自定义 |
| 数据导出/导入 | 主机库、密钥、片段 JSON 格式导入导出 |

---

## 三、技术创新点

### 3.1 架构创新

**三层解耦架构（Domain → Application State → UI）**
- Domain 层是纯逻辑，零副作用（workspace 树操作、CRDT 合并、发行版归一化）
- Application State 层是状态拥有者，持久化边界清晰（~120 个 hooks，状态变更统一经过 hooks）
- UI 层纯展示，不包含业务逻辑
- 结果：测试粒度细、复用性强、AI Agent 和 MCP Server 可以独立调用 Domain 层能力

**双运行时架构**
- 主进程：CommonJS `.cjs`，IPC bridge + SSH/SFTP + 插件宿主
- 渲染层：ESM + TypeScript + React 19 + Vite 7
- 两套模块系统分离但通过 preload API 严格对接

### 3.2 AI Agent Harness（最有特色的创新）

**专为终端运维场景设计的 AI 运行时**——不是通用 ChatBot，而是一个能理解多主机、多会话、多告警上下文的 Agent 编排引擎：

| 子系统 | 创新 |
|--------|------|
| **AgentRuntime** | Turn 生命周期管理、trace 事件分发、每 Turn 独立的 ToolOutputStore + ToolResultDedup（解决长输出工具结果重复读取的问题） |
| **上下文预算与压缩** | `contextBudget` + `compactionPruner` + `staleContextPruner` 三套机制：413 Token 超限自动压缩、过期工具结果自动裁剪、步骤间增量压缩 |
| **动态 Threshold** | 上下文预算阈值不是固定值，而是根据模型能力和会话深度动态调整 |
| **SessionState 重新注入** | AI 多轮对话中维护 session 状态（当前主机链、活跃端口转发、最近告警），每轮自动注入 system prompt |
| **Capability Tools 注册表** | 从 `electron/capabilities/catalog/` 代码生成（`npm run generate:capability-tools`），一套能力目录自动生成 Catty/MCP/CLI 三路工具暴露 |
| **白名单+权限分级** | 预置命令目录（command_catalog）+ 三种执行权限（observer/confirm/auto）+ blocked_patterns 黑名单，三重防线确保 AI 不会执行危险命令 |
| **Prompt 版本化** | System Prompt 有版本号，便于后续迭代和 A/B 测试 |

### 3.3 MCP + CLI + RPC 三通路统一

一套能力目录（30+ 命令），自动生成三个暴露面：

```
electron/capabilities/catalog/ + codegen/toolSurfaces.cjs
          │
          ├──► Catty Sidebar Tools (cattyToolSpecs.json)
          ├──► MCP stdio Server (netcatty-mcp-server.cjs)
          └──► netcatty-tool-cli (CLI 工具链)
```

**创新**：新增一个能力命令，只要在 catalog 里加一条 entry（描述、device_types、agentKinds、surfaces），三个通路自动暴露。不需要改 MCP handler、不需要写 CLI 代码、不需要改 prompt。

### 3.4 CRDT 收敛同步（自研）

不同于市面上大多数"最后写入胜出"的同步方案，NetMesh 用 **CRDT（无冲突复制数据类型）** 实现多端同步：

- 支持主机库、密钥、片段、分组等结构化数据的并发编辑收敛
- 网络分区恢复后自动合并，不会丢数据，不会产生冲突需要手动选
- 端到端加密 + 数据分片 + 版本向量
- 多后端统一适配（Gist/Drive/OneDrive/S3/WebDAV）

### 3.5 插件安全模型

**BrowserWindow 沙箱 + utilityProcess + RPC 路由三层隔离**：

- 普通插件运行在 `BrowserWindow` 的沙箱 session，离线网络（只能连 `netcatty-plugin://` 协议）
- 高级 Node-only 插件运行在独立 `utilityProcess`
- 所有插件对主进程的调用必须经过 `PluginRpcRouter`（请求关联、取消、超时、流量限制、协议失败隔离）
- 插件包 `.ncpkg` 原子发布，安装时校验完整性，删除时全量清理

### 3.6 告警双轨预案体系（设计中）

行业内少见的设计——预案同时包含「值班员动作流程」和「AI 操作步骤」两个层级，绑定在一个对象里：

- **值班员动作预案（human_action_guide）**：什么时候通知谁、什么情况必须升级、处置前要做哪些防护、处置后要做哪些归档
- **操作级预案（remediation）**：具体命令步骤，每个步骤带三级执行权限（auto/confirm/manual_only）
- **AI 初始响应包**：告警触发时 AI 自动生成结构化响应包，嵌入监控大屏弹窗，值班员一键复制转发运维群

---

## 四、AI 使用全景

### 4.1 AI 在系统中的定位

AI 不是一个"附加功能"，而是系统的**核心运维能力层**。它能：

```
理解告警 → 匹配预案 → 生成响应包 → 自动执行安全命令 → 协助处置 → 归档总结
```

### 4.2 AI 的三种入口

| 入口 | 面向谁 | 触发方式 |
|------|--------|----------|
| **Catty 侧边栏对话** | 所有用户 | 主动发起对话 |
| **MCP Server（外部 Agent）** | 高级用户（Claude Desktop/Cursor） | 外部 Agent 自动调用 |
| **自动响应包生成** | 值班员（被动接收） | 告警触发时系统自动生成（不需要人触发） |

### 4.3 AI 能做什么

#### （1）运维执行

- ✅ **读操作**：show 命令、display 命令、df -h、ps aux、cat 配置文件（observer 模式自动执行）
- ✅ **写操作（需确认）**：重启服务、改配置、调阈值、采集诊断（confirm 模式弹窗审批后执行）
- ❌ **危险操作拦截**：shutdown、reboot、rm -rf /、reload（blocked_patterns 自动拦截）

#### （2）多主机编排

- 一条指令同时操作 N 台主机："所有 Linux 服务器检查磁盘使用率"
- 自动分组："核心区的交换机" → 自动匹配 catalog_type + tier
- 聚合输出：多台主机的命令执行结果汇总成一张表

#### （3）巡检报告 AI 汇总

每轮巡检结束后，内置 AI 自动生成自然语言总结：
> "本轮巡检覆盖 23 台设备，2 台交换机 CPU 高负载（huawei_h3c_switch-A: 91%，huawei_h3c_switch-B: 88%），3 台服务器磁盘使用率超过 80%，1 台防火墙健康分偏低（62分），建议优先处理核心区交换机 CPU 告警。"

#### （4）告警 AI 初始响应包（设计中）

告警触发后，AI 自动生成结构化包（设备画像 + 快速 checklist + 匹配预案 + AI 推断的可能原因），直接嵌入监控大屏弹窗：
> 值班员看到弹窗 → Tab 切到"🤖 AI 响应包" → 一键复制 → 转发运维群。大家拿到完整信息，不用自己翻拓扑图、查巡检历史。

#### （5）预案 AI 描述生成（设计中）

运维说一句话，AI 翻译成结构化预案草稿：
> 运维："核心交换机 CPU 超过 90% 持续 5 分钟，先 display cpu-usage 确认，持续不降就重启核心接口"
> AI 生成：符合 device_plan schema 的 JSON 草稿 → 三重校验（schema + command_catalog 交叉 + blocked_patterns）→ 保存为 draft → 运维微调 → 启用。

### 4.4 AI 的安全设计

| 层级 | 机制 |
|------|------|
| **命令白名单** | command_catalog 目录（预置命令 ID + 设备类型 + risk_level + 审计记录） |
| **前缀匹配** | allowed_commands 正则前缀匹配（show *、display *、df -h） |
| **黑名单反查** | blocked_patterns（shutdown、reload、rm -rf /）优先级高于白名单 |
| **执行权限分级** | observer（只读自动）/ confirm（写需弹窗审批）/ auto（全自动） |
| **审批流** | Catty 的 cattyToolApproval.ts + Codex App Server 的 native 审批 + MCP 的 setupMcpApprovalBridge |
| **Trace 审计** | 每步 ToolOutput 都记录 traceStore，包含 usage / performance / tool input output |
| **输出截断与持久化** | 大输出自动截断存 preview，完整内容 spill 到 tool_output_read；跨 Turn 持久化 |
| **上下文隔离** | 每个 chat session 独立 context、独立 plan_snapshot、独立 turn_state |

### 4.5 AI 多厂商适配

| 类别 | 已适配 |
|------|--------|
| 内置 SDK 集成 | MiniMax（主力 Catty Provider） |
| 外部 SDK IPC | Claude（@anthropic-ai/sdk）、Codex（@openai/codex-sdk）、Cursor、Copilot、Grok、OpenCode |
| Codex App Server | 实验性，`codex app-server --stdio` 持久化运行时 |
| Vercel AI SDK v7 | Catty 主路径，streamText + tool calling + context management |

---

## 五、项目规模与工程数据

| 指标 | 数值 |
|------|------|
| 技术栈 | Electron 42 + React 19 + Vite 7 + TypeScript 5.9 + xterm.js 6 |
| 模块系统 | 主进程 CommonJS `.cjs` / 渲染层 ESM + TS 双轨 |
| Workspace | npm workspaces（`packages/` 插件契约/SDK/CLI） |
| 依赖 | ~100 npm 包（ssh2、ssh2-sftp-client、node-pty、Tailwind CSS 4、Radix UI、Monaco Editor、ajv、@mcp/sdk、vercel ai sdk） |
| 测试 | Node --test + tsx，domain 纯函数 / state hooks / 主进程 bridge 都有伴生测试 |
| 代码生成 | 能力目录 → MCP 工具 / Catty 工具 / CLI 三路暴露（`npm run generate:capability-tools`） |
| 跨平台 | macOS / Windows / Linux 三端 |