SenMeshNet/docs/system-overview.md

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 三端