@felixyin/cscli/README.md

一款可以在手机上操控任意PC上的AI agent coding cli开发助手的开发辅助工具

## 📖 概述

**码壳终端（Code Shellx）**  一款可以在手机上操控任意PC上的AI agent coding cli开发助手的开发辅助工具

## ✨ 功能特性

*   多标签页管理 SSH 与 SFTP 连接  
*   支持 RDP/VNC 协议
*   支持 PWA
*   采用 Monaco Editor，支持在线编辑文件  
*   集成多重登录安全机制，包括人机验证（hCaptcha、Google reCAPTCHA）与双因素认证（2FA）  
*   高度可定制的界面主题与布局风格
*   支持 IP 白名单与黑名单，异常访问自动封禁  
*   通知系统（如登录提醒、异常告警）
*   基于 Node.js 的轻量级后端，资源占用低
*   内置心跳保活机制，确保连接稳定

## 📦 安装

### 全局安装（推荐）

```bash
npm install -g @felixyin/cscli
```

安装后，你可以在**任意目录**下运行：

```bash
# 启动服务（默认前台模式）
cscli start

# 查看系统信息
cscli info

# 显示版本信息
cscli version
```

服务启动后，打开浏览器访问：http://localhost:18111

**注意**：`cscli` 命令默认会启动服务，即使不带任何参数也会执行 `start` 命令。

### 常用命令

#### 查看系统信息
```bash
cscli info
```
显示包括安装目录、访问地址、作者信息和版本号等详细信息。

### 故障排查

如果遇到 sqlite3 安装失败，请尝试：

```bash
# Windows
npm install -g --build-from-source sqlite3

# macOS (需要 Xcode Command Line Tools)
xcode-select --install
npm install -g @felixyin/cscli

# Linux (需要 build tools)
sudo apt-get install build-essential python3
# 或
sudo yum groupinstall "Development Tools"
```

## 🚀 开发

## 📦 包管理

本项目使用 **npm workspaces** 进行多包管理：

- `@cscli/backend` - Node.js 后端服务
- `@cscli/frontend` - Vue.js 前端应用
- `@cscli/remote-gateway` - 远程网关服务

Workspace 配置见 package.json 中的 workspaces 段。

### 主要脚本命令

*   `npm run build` - 构建（构建所有包并复制前端到后端，用于发布前准备）
*   `npm run dev` - 启动前后端开发服务器（并发运行）
*   `npm run start` - 启动后端服务（用于全局安装后运行）
*   `npm publish` - 发布到npm（发布前请先运行 build）
*   `npm run lint` - 检查代码质量

### 开发环境设置

1. **确保 Node.js 和 npm 版本**：
   ```bash
   node --version    # 应该 >= 16.0.0
   npm --version     # 应该 >= 8.0.0
   ```

2. **安装依赖**：
   ```bash
   npm install
   ```

3. **启动开发服务器**：
   ```bash
   # 并发启动前后端开发服务器
   npm run dev
   ```

4. **构建项目**：
   ```bash
   # 构建所有包
   npm run build
   ```

## 🚀 本地开发和打包发布流程

### 本地开发流程

1. **克隆并初始化项目**：
   ```bash
   git clone <repository-url>
   cd codeshell
   npm install
   ```

2. **运行开发服务器**：
   ```bash
   # 并发启动前后端（推荐）
   npm run dev
   ```

3. **开发过程中的构建**：
   ```bash
   # 构建（构建所有包并复制前端到后端）
   npm run build
   ```

### 打包发布流程

#### 发布前准备

1. **完整构建验证**：
   ```bash
   # 运行构建流程
   npm run build
   # 这会执行：构建前端 → 构建后端 → 构建远程网关 → 复制前端到后端public目录
   ```

2. **检查构建产物**：
   ```bash
   # 验证包内容
   npm pack --dry-run
   # 或生成实际的.tgz文件
   npm pack
   ```

3. **本地安装测试**：
   ```bash
   # 卸载旧版本
   npm uninstall -g @felixyin/cscli
   
   # 安装本地构建版本
   npm install -g .
   
   # 在非项目目录测试
   cd %TEMP%
   cscli start
   # 访问 http://localhost:18111 验证功能
   # 使用 Ctrl+C 停止服务
   ```

#### 正式发布

1. **发布到 npm**：
   ```bash
   # 确保已登录 npm
   npm login
   
   # 发布
   npm publish
   ```

2. **发布流程说明**：
   - 项目使用 npm workspaces 管理多包结构
   - `package.json` 中的 `files` 字段定义了需要包含在 npm 包中的文件
   - `build` 脚本确保在打包前完成以下步骤：
     - 构建前端 (`npm run build --workspace=@cscli/frontend`)
     - 构建后端 (`npm run build --workspace=@cscli/backend`) 
     - 构建远程网关 (`npm run build --workspace=@cscli/remote-gateway`)
     - 复制前端构建产物到后端 public 目录 (`npm run copy:frontend`)
   - 生成的 npm 包包含后端服务和前端静态文件，确保用户在任何目录运行 `cscli start` 都能正常访问

### 配置文件管理

- **TypeScript 配置**：每个包独立维护 `tsconfig.json`，满足不同构建需求
- **ESLint 配置**：每个包独立维护 ESLint 配置，保持代码风格一致
- **共享配置**：可考虑在根目录添加基础配置文件供各包继承