opsxshell/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

语言偏好

请使用中文与用户交互。 所有交流使用中文，代码注释和文档可使用中文或英文。

---

项目概述

OpsXShell - 跨平台 SSH/SFTP 终端工具 · 简洁高效 · 安全可靠 · 操作便捷人性化 · 基于 Electron + React + TypeScript 构建。支持终端仿真、SFTP、端口转发、会话管理。

技术栈

• UI 框架: Electron 28 + React 18 + TypeScript 5
• 构建工具: Vite 5
• 状态管理: Zustand
• 终端仿真: XTerm.js + WebGL
• SSH/SFTP: ssh2
• 数据库: better-sqlite3
• 样式: Tailwind CSS
• 测试: Vitest
• 支持平台: macOS, Windows, Linux

---

常用命令

安装和运行

npm install          # 安装依赖
npm run dev          # 启动开发服务器 + Electron

构建和打包

npm run build        # 构建生产版本（前端 + Electron）
npm run dist         # 打包分发（当前平台）
npm run dist:mac     # 打包 macOS
npm run dist:win     # 打包 Windows
npm run dist:linux   # 打包 Linux

代码检查

npm run lint         # 运行 ESLint

测试

npm test             # 运行所有测试
npm run test:watch   # 监听模式
npm run test:coverage #覆盖率报告

---

项目架构

进程模型

Electron 双进程架构：

• 主进程 (electron/): 窗口管理、IPC 处理器、本地操作
• 渲染进程 (src/): React UI、状态管理、XTerm.js 终端

目录结构

electron/
├── main.ts              # 主进程入口
├── preload.ts           # 上下文桥接 (window.electronAPI)
├── services/
│   ├── ssh-service.ts    # SSH/SFTP 操作 (ssh2)
│   └── database-service.ts # SQLite 操作
└── ipc/                 # IPC 处理器分层
    ├── ssh.ipc.ts       # SSH 连接/Shell/端口转发
    ├── sftp.ipc.ts      # SFTP 操作/传输
    ├── session.ipc.ts   # 会话 CRUD
    ├── settings.ipc.ts  # 设置读写
    ├── dialog.ipc.ts    # 文件对话框
    ├── file.ipc.ts      # 本地文件操作
    ├── zmodem.ipc.ts    # rz/sz 传输
    └── app.ipc.ts       # 应用信息

src/
├── components/           # React 组件
│   ├── TerminalView.tsx # 终端仿真 (XTerm.js + WebGL)
│   ├── SFTPView.tsx    # SFTP 双面板文件管理
│   ├── sftp/           # SFTP 子组件
│   │   ├── Breadcrumb.tsx
│   │   ├── SortHeader.tsx
│   │   ├── FileRow.tsx
│   │   ├── ContextMenu.tsx
│   │   ├── TransferItem.tsx
│   │   └── ConnectionSelector.tsx
│   └── ...
├── stores/              # Zustand 状态管理
│   ├── tabStore.ts     # 标签页管理
│   ├── connectionStore.ts # 连接状态
│   └── connection/      # 连接池分层
│       ├── poolStore.ts     # 连接池核心 (创建/获取/释放)
│       ├── lifecycleStore.ts # 状态机/超时
│       └── storeHooks.ts     # 组合接口
└── themes/             # 终端主题

shared/
└── types/              # 跨进程共享类型
    ├── session.types.ts    # Session, AuthType
    ├── connection.types.ts # PooledConnection, ConnectionState
    ├── sftp.types.ts      # FileItem, TransferTask
    └── ipc.types.ts       # IPC 通道常量

test/                   # Vitest 测试
├── setup.ts           # 测试环境配置 (Electron API mock)
├── stores/            # Store 单元测试
└── components/        # 组件工具函数测试

IPC 通信

渲染进程通过 window.electronAPI 与主进程通信。所有 IPC 处理器已分层到 electron/ipc/ 目录。

主要通道:

• ssh:connect, ssh:disconnect, ssh:createShell, ssh:shellWrite, ssh:shellResize
• sftp:connect, sftp:listDirectory, sftp:upload, sftp:download, sftp:mkdir
• session:create, session:update, session:delete
• local:readDir, local:mkdir, local:delete, local:rename

事件推送: Shell 输出通过 ssh:shellData；SFTP 进度通过 sftp:progress。

数据库架构

SQLite（~/.opsxshell/）:

• sessions: SSH 会话配置
• connection_history: 连接历史
• settings: 应用设置
• keys: SSH 密钥
• port_forwards: 端口转发规则

连接池架构

连接池已拆分为两个 Store：

1. poolStore - 连接 Map、LRU 淘汰、引用计数、创建/断开
2. lifecycleStore - 状态机（disconnected/connecting/connected/background/suspended）、超时管理

---

设计模式参考

IPC 通信

// electron/ipc/ssh.ipc.ts
ipcMain.handle('ssh:connect', async (_event, config) => {
  try {
    const result = await sshService.connect(config)
    return { success: true, connectionId: result.id }
  } catch (error: any) {
    return { success: false, error: error.message }
  }
})

事件推送

// 主进程发送
mainWindow?.webContents.send('ssh:shellData', shellId, data)

// 渲染进程监听
window.electronAPI.onShellData((_event, shellId, data) => {
  terminal.write(data)
})

Zustand Store

// 使用组合模式
export const useConnectionStore = () => {
  const pool = usePoolStore()
  const lifecycle = useLifecycleStore()
  return { ...pool, ...lifecycle }
}

---

开发注意事项

✅ 推荐做法

1. 使用 contextBridge 暴露 API，保持 contextIsolation: true
2. IPC 返回 { success: false, error: error.message } 格式
3. 在 app.on('before-quit') 清理资源
4. 组件卸载时清理事件监听 (removeAllListeners)
5. 添加新 IPC 处理器时：在 electron/ipc/ 创建/修改对应文件 + 在 electron/preload.ts 暴露 + 在 src/electron.d.ts 添加类型

❌ 避免做法

1. 渲染进程直接使用 require('ssh2') - 必须通过 IPC
2. 暴露 nodeIntegration: true
3. SSH 连接未关闭导致资源泄漏
4. 硬编码数据库路径
5. 忽略 Shell 窗口大小变化

---

添加新功能指南

添加 IPC 处理器

1. 在 electron/ipc/ 对应模块添加 handler
2. 在 electron/preload.ts 添加暴露方法
3. 在 src/electron.d.ts 添加类型声明

添加 UI 组件

1. 在 src/components/ 创建组件
2. 如需状态管理，在 src/stores/ 添加/扩展 Store
3. 在 TabContent.tsx 添加渲染逻辑

添加测试

1. 在 test/stores/ 或 test/components/ 创建 .test.ts 文件
2. 使用 test/setup.ts 中的 mock 配置
3. 运行 npm test 验证

---

参考资源

• Electron
• React
• XTerm.js
• ssh2
• Zustand
• Vitest