内容
# 康奇
**English** · [简体中文](README.zh-CN.md)
康奇是一款用Rust编写的SSH客户端。单个`r-shell`二进制文件管理保存的连接，运行远程命令，打开交互式shell，通过SFTP传输文件，并打印快速系统快照。
它还附带一个可选的MCP服务器，因此AI助手（Cursor，Claude和其他MCP客户端）可以通过一个持久的SSH会话在您的服务器上工作，而不是每次都启动一个新的`ssh`进程。
还有一个桌面应用程序 - 一个基于Flutter的UI，构建在同一个Rust核心之上，带有标签式终端，文件浏览器和实时监控。
<p align="center">
<a href="https://github.com/MageGojo/conch/releases/latest"><img alt="最新发布" src="https://img.shields.io/github/v/release/MageGojo/conch?label=下载&sort=semver"></a>
<a href="https://github.com/MageGojo/conch/actions/workflows/release.yml"><img alt="发布构建" src="https://img.shields.io/github/actions/workflow/status/MageGojo/conch/release.yml?label=发布构建"></a>
<img alt="平台" src="https://img.shields.io/badge/平台-macOS%20%7C%20Linux%20%7C%20Windows-blue">
<img alt="语言" src="https://img.shields.io/badge/使用语言-Rust-orange?logo=rust">
<a href="#许可证"><img alt="许可证：MIT" src="https://img.shields.io/badge/许可证-MIT-green"></a>
</p>
## 截图
<p align="center">
<img src="docs/gui/screenshots/conch-connections.png" alt="康奇连接仪表盘" width="900"><br>
<em>连接仪表盘 - 保存的主机按文件夹分组，带有内置的本地监控卡。</em>
</p>
<p align="center">
<img src="docs/gui/screenshots/conch-command-blocks.png" alt="康奇命令块终端" width="900"><br>
<em>命令块终端 - 每个命令及其输出都是一个块，带有退出代码，时间戳和工作目录，该目录在块之间持续存在。</em>
</p>
<p align="center">
<img src="docs/gui/screenshots/conch-monitor.png" alt="康奇实时监控" width="900"><br>
<em>实时监控 - CPU，内存，磁盘和网络，带有实时图表。</em>
</p>
## 目录
- [截图](#截图)
- [功能](#功能)
- [安装](#安装)
- [快速入门](#快速入门)
- [命令](#命令)
- [MCP服务器](#mcp服务器)
- [身份验证](#身份验证)
- [配置](#配置)
- [安全](#安全)
- [开发](#开发)
- [项目布局](#项目布局)
- [许可证](#许可证)
## 功能
| 命令 | 描述 |
| --- | --- |
| `connections` | 添加，列出，更新和删除保存的主机 |
| `exec` | 在远程主机上运行单个命令 |
| `shell` | 打开交互式PTY shell |
| `ls` | 列出远程目录 |
| `upload` / `download` | 通过SFTP复制文件 |
| `stats` | 一次性CPU /内存/磁盘/网络快照 |
| `mcp` | 启动本地MCP服务器 |
相同的二进制文件在macOS，Linux和Windows上运行。`exec`，`shell`，`upload`和`download`适用于任何POSIX主机；`ls`和`stats`需要Linux主机（它们依赖于GNU `ls`和`/proc`）。
## 安装
### 桌面应用程序
预构建的桌面版本在[发布页面](https://github.com/MageGojo/conch/releases/latest)上。运行时已捆绑，因此无需额外安装。
| 平台 | 文件 |
| --- | --- |
| Windows x64（安装程序） | `Conch-windows-x64-setup.exe` |
| Windows x64（便携式） | `Conch-windows-x64.zip` |
| macOS | `Conch-macos.zip` |
这些构建版本尚未进行代码签名。在macOS上，右键单击`Conch.app` → **打开**；在Windows上，选择**更多信息→运行任何方式**，如果SmartScreen发出警告。
### 命令行界面
| 平台 | 文件 |
| --- | --- |
| macOS（Apple Silicon） | `r-shell-macos-apple-silicon.dmg` |
| macOS（Intel） | `r-shell-macos-intel.dmg` |
| Windows x64 | `r-shell-windows-x64-installer.exe` |
在macOS上，挂载DMG并将二进制文件复制到您的`PATH`：
```bash
sudo cp /Volumes/Conch/r-shell /usr/local/bin/r-shell
sudo chmod +x /usr/local/bin/r-shell
xattr -dr com.apple.quarantine /usr/local/bin/r-shell # 清除Gatekeeper隔离
r-shell --version
```
在Windows上，运行安装程序（它将`r-shell`添加到您的`PATH`）并打开一个新的终端。
### 从源代码构建
您需要Rust和Cargo（[rustup.rs](https://rustup.rs)）。无需OpenSSL或libssh - 康奇使用纯Rust的`russh`堆栈。
```bash
git clone https://github.com/MageGojo/conch.git
cd conch
cargo build --release --manifest-path cli/Cargo.toml
sudo install -m 0755 cli/target/release/r-shell /usr/local/bin/r-shell
```
或直接从Cargo运行而无需安装：
```bash
cargo run --manifest-path cli/Cargo.toml -- <命令> [选项]
```
## 快速入门
```bash
# 保存连接
r-shell connections add --name prod --host 203.0.113.10 --username deploy \
--auth publickey --key-path ~/.ssh/id_ed25519
# 使用它
r-shell connections list
r-shell exec -c prod -- uptime
r-shell shell -c prod
r-shell upload -c prod ./app.tar.gz /tmp/app.tar.gz
r-shell download -c prod /tmp/app.tar.gz ./app-copy.tar.gz
```
每个与主机交互的命令都需要一个目标：一个保存的连接（`-c <id|name>`）或内联详细信息。如果需要密码但未提供，则会提示您输入（输入不会回显）。
常见目标标志（`exec`，`shell`，`ls`，`upload`，`download`，`stats`）：
| 标志 | 别名 | 描述 | 默认值 |
| --- | --- | --- | --- |
| `--connection <id\|name>` | `-c` | 使用保存的连接 | — |
| `--host <host>` | | 即席主机（IP或主机名） | — |
| `--user <user>` | `-u` | 即席SSH用户名 | — |
| `--port <port>` | `-p` | 即席SSH端口 | `22` |
| `--password <pw>` | | 即席密码（优先使用提示） | — |
| `--key-path <path>` | | 私钥路径 | — |
| `--passphrase <pp>` | | 加密密钥的通行短语 | — |
| `--insecure` | | 跳过主机密钥验证 | `false` |
## 命令
运行`r-shell --help`或`r-shell <command> --help`以获取完整的选项列表。
### connections
保存的连接存储在本地`workspace.json`中（参见[配置](#配置)）。
```bash
r-shell connections list [--json]
r-shell connections add \
--name prod --host 203.0.113.10 --username deploy --port 22 \
--auth publickey --key-path ~/.ssh/id_ed25519 \
--folder Work --description "生产网络服务器"
r-shell connections update <id> --port 2222 --folder Staging
r-shell connections remove <id>
```
必需标志：`--name`，`--host`，`--username`。`--auth`为`password`或`publickey`（默认为`password`）；`--port`默认为`22`；`--folder`默认为`所有连接`。`update`接受连接ID和任何相同的标志。
### exec
运行一个命令并打印其输出。 `--`之后的所有内容都会原样发送。
```bash
r-shell exec -c prod -- uname -a
r-shell exec -c prod -- "ls -la /var/www && df -h"
r-shell exec --host 203.0.113.10 --user deploy -- systemctl status nginx
```
### shell
一个完整的交互式PTY shell（vim，htop，less，...）。按`Ctrl-]`强制退出本地循环，如果会话挂起。
```bash
r-shell shell -c prod
```
### ls
```bash
r-shell ls -c prod /var/log
r-shell ls -c prod /var/log --json
r-shell ls -c prod # 默认情况下默认为主目录
```
列：类型（`DIR`/`FILE`/`LNK`），权限，大小，修改时间，名称。（Linux主机。）
### upload / download
通过SFTP进行单文件传输。
```bash
r-shell upload -c prod ./local.tar.gz /tmp/remote.tar.gz
r-shell download -c prod /tmp/remote.log ./local.log
```
### stats
获取两个快速样本并打印快照（Linux主机；依赖于`/proc`）。
```bash
r-shell stats -c prod
```
```text
操作系统： Linux 6.1.0
运行时间： 12d 4h 31m
CPU： 7.4% (8 cores, load 0.42)
内存： 61.2% (4.9/7.8 GB)
磁盘： 40.0% (3.8/9.5 GB)
网络：下行 1.5 KB/s 上行 320 B/s
```
### mcp
启动本地MCP服务器（见下文）。
```bash
r-shell mcp
# 康奇MCP服务器监听 http://127.0.0.1:9123/mcp
```
## MCP服务器
`r-shell mcp`在Streamable HTTP上启动本地模型上下文协议服务器，仅绑定到`127.0.0.1`。将MCP客户端指向`http://127.0.0.1:9123/mcp`:
```json
{
"mcpServers": {
"r-shell": {
"url": "http://127.0.0.1:9123/mcp"
}
}
}
```
对于Cursor，此操作在`~/.cursor/mcp.json`中。对于Claude Desktop和其他客户端，请添加相同的URL作为Streamable HTTP服务器，然后重启。
服务器在调用之间保持一个SSH会话，因此助手可以运行命令和读取或写入文件而无需每次重新连接。会话仅存在于内存中，只要`r-shell mcp`正在运行。
会话工具：
| 工具 | 描述 |
| --- | --- |
| `ssh_session_open` | 打开或重用会话；返回`session_id` |
| `ssh_exec` | 在会话上运行命令 |
| `ssh_read_file` | 读取远程文件（UTF-8或二进制的base64） |
| `ssh_write_file` | 创建或覆盖远程文件 |
| `ssh_list_dir` | 列出远程目录 |
| `ssh_sessions_list` / `ssh_session_close` | 列出或关闭活动会话 |
连接工具（在`workspace.json`上操作）：
| 工具 | 描述 |
| --- | --- |
| `r_shell_ssh_connections_list` | 列出保存的连接（删除凭证） |
| `r_shell_ssh_connection_create` / `_update` / `_delete` | 管理保存的连接 |
凭证永远不会返回 - 列表调用仅公开布尔值，如`has_password`。端点需要一个环回`Host`标头（和一个环回`Origin`，如果存在）；跨源和DNS反弹请求获取`403`。
## 身份验证
- **密码** - `--auth password`和`--password`，或省略它以在连接时提示。
- **公钥** - `--auth publickey`和`--key-path`（和`--passphrase`用于加密密钥）。以`~/`开头的路径会被扩展。
主机密钥根据`~/.ssh/known_hosts`进行验证，遵循首次信任原则。第一次连接记录密钥；后续连接必须匹配。 如果密钥不匹配，则连接中止（可能的中间人攻击），直到您从`known_hosts`中删除有问题的行。 `--insecure`完全跳过检查 - 仅在一次性或本地测试主机上使用。
## 配置
保存的连接存储为JSON：
| 操作系统 | 路径 |
| --- | --- |
| macOS | `~/Library/Application Support/r-shell/workspace.json` |
| Linux | `~/.local/share/r-shell/workspace.json` |
| Windows | `%LOCALAPPDATA%\r-shell\workspace.json` |
在Unix上，文件及其目录都使用所有者权限创建（`0600` / `0700`）。
## 安全
- 主机密钥根据`known_hosts`进行验证（首次信任）；更改的密钥中止连接，除非传递`--insecure`。
- 密码，私钥和通行短语永远不会被打印或通过MCP调用返回 - 列表响应仅公开`has_password` / `has_private_key_path`。
- 密码提示不会回显输入。
- `workspace.json`在Unix上仅限所有者。
- MCP服务器绑定到localhost并拒绝非环回`Host` / `Origin`（击败DNS反弹和跨源访问）。
## 开发
根`package.json`是Cargo的薄包装：
```bash
pnpm dev # cargo run -- --help
pnpm check # cargo check
pnpm test # cargo test
pnpm build # cargo build
pnpm fmt # cargo fmt
```
或直接使用Cargo `--manifest-path cli/Cargo.toml`。版本提升通过`pnpm version:patch|minor|major`进行，它更新`package.json`，`cli/Cargo.toml`，`cli/Cargo.lock`和`CHANGELOG.md`。
## 项目布局
```text
conch/
├── cli/ # r-shell：CLI + MCP服务器（Rust）
├── core/ # 共享SSH / MCP核心库
├── desktop/ # 桌面应用程序（Flutter UI + Rust核心）
├── packaging/ # macOS .dmg和Windows安装程序脚本
├── scripts/ # 版本提升助手
└── .github/ # CI：测试和发布构建
```
## 许可证
MIT - 请参阅[LICENSE](LICENSE)。由[ApiZero](https://apizero.cn/)团队维护。欢迎在[GitHub](https://github.com/MageGojo/conch)上提交问题和拉取请求。
