内容
](./README.md) | [中文](./README_)
<p align="center <img src="https.shields.io/badge/Go.25+-00ADD8?style=flat&logo=go" alt 版本">
<imghttps://img.shields.io-MIT-blue.svg" alt="许可证">
<img src="https://img.shields.io-linux%20|%win%20|%20grey" alt="平台">
</p>
---
VectorShell 是一个 的远程操作平台，它将反向 shell 基础设施、AI 代理编排和 DPI过网络结合成的系统。位于限制后面的客户端通过加密的、分隧道连接；操作员 API、SSE 事件流、MCP 兼容的工具仪表盘进行控制。
## 架构
```
┌──────────────────────────────────────────────┐
│ 操作员 │
│ 仪表盘 / API / REPL / MCP 客户端 │
└─────┬──────────┬──────────┬─────────────────┘ │ HTTPS │ │ MCP (JSON-R ▼ ▼ ┌────────────────────────────────────────────────
│ 服务器 │
│ TLS ──── :5443 ────► :8084 API │
│┌─ /api/sessions, /api/conversations │
│ │─ /api/clients/generate │
│ │─ /api/artifacts, /api/agent │
│ :7735 ─── 隧道 │─ /mcp (JSON-RPC) │
│ 监听器 ──────┤─ /ws (WebSocket) │
│ │ │
│ ┌──────────┐ ┌──┴──────────┐ ┌──────────────────┐ │
│ │ 会话 │ │ Eino 代理 │ │ SQLite 存储 │ │
│ │ 管理器 │ │ (OpenAI) │ │ + 事件总线 │ │
│ └──────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
┌────────────────┼────────────────┐
│ │ │
反向 WebSocket DPI 绕过隧道 反向 WebSocket
│ │
─┴──────────┐ │┌───────────┴────────── │ │ │ 客户端 B (隧道 │
│ (直接) │ │ │ │
└──────────────────────┘ │ └───────────────────────┘
│
┌──────┴──────┐
│ 连接 │
│ 代理 │
└─────────────┘
```
## DPI 绕过隧道
位于限制性 CONNECT 代理后面的客户端，通过多层隧道连接 客户端 CONNECT 代理 服务器
│ │
│── TCP 拨号 ──► │ │
│ │
CONNECT host:7735 HTTP/1.1 ── ──────────────────────────► │ │ │◄── 200 连接已建立 ── │ ◄───────────────────────── │
│ │ │
│══╡ 分段连接 (1 字节 TCP 分段) ╞══════════════════► │
│ │ │ │ │
│ │ 每个字节都是的 │ DPI 无法 │ 包 → DPI 无法 │ 重组 │
│ │组流 │ │
│ │ │ │
══╡ 加密AES-256-CTR ╞════════════════════════► │
│ │ │ │ │ 每个方向的随机 IV │ │ 有效是 │
│ → 加密有效，没有明文 │ 对 DPI 不透明 │
│ │ │ │
╡ WebSocket (ws 无 TLS) ═══════════════════════════ │
│ │ │ │
│ gorilla/websocket 使用 │ │需 TLS： │
│ │ Net → 普通 TCP │ │ 加密在隧道 │
│ │ (无双重 TLS) │ │ │
```
**为什么有效 DPI 系统依赖于 TCP 流重组来检查 TLS 。通过将每次写入分割成 1 字节的段且无延迟，DPI 设备永远无法积累足够的数据来分类流。然后，AES-256-CTR 层加密有效载荷，因此即使 DPI 设备重组片段，内容也是不透明的。
## 项目优势
| 功能 | 描述 |
|---|---|
| **单一二进制文件**和客户端是独立的 Go 二进制文件，无运行时依赖 |
| **反向连接** | 客户端发起出站连接；无需入站防火墙| **抗 DPI** | TCP 分段 + AES-256-CTR 隧道击败深度包检查 |
| **生** | Eino 驱动的代理，带有_file、write_file、upload_file、download_file工具 |
| **MCP 兼容** | `/ 端点实现 JSON 2.0；与任何 MCP 客户端（Claude Desktop、Continue 等）集成 |
| **实时流** | SSE 事件流传递代理推理、工具调用和结果 |
| **持久历史** | SQLite 支持的会话在服务器重启后存活 |
| **跨编译 API** | `POST /api/clients/generate` 构建具有嵌入式配置的平台特定二进制文件 |
| **技能文档** | Eino 技能中间件从可配置目录加载 Markdown 文件到代理上下文 |
| **可观察性** | 健康检查、会话列表、事件流 — 所有通过相同的 HTTP API |
## 快速入门
### 先决条件
- Go 1.21+
- OpenAI 兼容的 API 密钥（或任何提供 `/v1/chat/completions` 的提供商）
### 1. 配置
```bash
cp config.example.toml config.toml
```
编辑 `config.toml` — 至少设置 密钥：
```toml
[agent]
model = "gpt-4.1"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
[auth]
api_token = "your-strong-api-token"
client_token =-strong-client-token"
```
### 2. 启动```bash
go run ./cmd/server -config ./
# VectorShell 服务器监听 :8080
```
3. 连接客户端
在目标机器上：
go run ./cmd/client -config ./config.toml或从服务器生成预配置的二进制文件：
```bash
curl -X POST http://localhost:8080/api/clients/generate \
-H "Authorization: Bearer your-strong-api-token" \
-d '{"target": "windows-amd64"}'
```
### 4. 交互
**REPL** （本地交互式 Shell）：
```bash
go run ./cmd/repl -config ./config.toml
> /sessions
> /use <install_id>
> /ami
> / all PDF files week"
```
**REST：
```bash
://localhost:8080 -H " your-token"
curl -X POST http://localhost:8080/api/agent \
"Authorization: Bearer your-token" \
-install_id":"..."," large log files```
**MCP**您的 MCP 客户端http://localhost:cp`，并验证令牌。
. 仪表盘
```bash
make web # http://localhost:
```
## 配置```toml
]
listen = ":808 # HTTP 监听地址
ws_path = "/ws" # WebSocket 端点路径
public_url = "" # 生成的客户端的外部 URL（例如，wss://your-domain.com/ws）
[agent]
model = "gpt-4" #
base "https://api.open/v1_key = "" 读取 OPENAI_API变量
soul_pathUL.md" 基本系统提示文件skill]
enabled = true 将技能文档加载上下文中
dir" # 技能文件的目录
[auth]
api_token = HTTP API 的牌
client_token = "" # WebSocket 注册时必须令牌
[server_url = "ws://127.0.08080/wsconnect_interval = 重连尝试之间的
[store]
"data/vectors.db" 路径
[tunnel = false # 绕过隧道监听器
pre_shared_key # 32 AES 密钥（客户端匹配）
port = # 端口
host # 隧道端点的公共主机名（用于）
proxy_host = 位于代理的 CONNECT 代理 IP
= 0 代理端口
参考
除 `/api/health` 和 `/ 之外的所有端 `Authorization: Bearer_token>`。
### 会| 方法 | 路 描述 |
|--------||
| `GET `/api/health` |（无身份验证| `GET`api/sessions`出带有元数据的客户端 |
| `GET `/api/sessions/:id/events` | SSE工具调度、结果、错误 |
| `GET`api/sessions/:id/history` | 会话 |
| `POST` | `/api/sid/tools` | 向工具调用 |
|` | `/api/sessions/:id/clean 清除对话上下文 |
### 对话
| 方法 | 描述 |
|--------|------|-------------|
| | `/api/conversations` | 创建绑定到对话 |
| `POST` | `/api/conversations/:id/messages` | 发送用户 → 代理运行异步，结果通过 SSE |
| `GET` | `/api/conversations/:id/events` | SSE 流：代理推理、工具调用、最终答案 |
### 代理和工具
| 方法 | 路 描述 |
------|-------------|
| `POST` | `/api/agent` | 同 |
| `POST` | `/api/tools 直接向客户端调度工具 |
### 制品
| 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/artifacts` | 上传多部分，字段 `file`） |
|` | `/api/artifacts/:id/download` | 下载制品 |
### 客户端构建
| 方法 | 描述 |
|--------|------|-------------|
| | `/api/clients/generate` |编译具有嵌入式配置的客户端二进制文件 |
| `GET` | `/api/clients/download?target=linux-amd64` | 下载预先构建的二进制文件 |
### MCP
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/mcp` | MCP 传输的 SSE 保活 |
| `POST` | `/mcp` | JSON-RPC：`initialize`、`tools/list`、`tools/call` |
### SSE 事件
对话的 SSE 流发出这些事件类型：
| 事件 | 有效载荷 |
|-------|---------|
| `conversation.started` | `conversation_id`, `install_id`, `timestamp` |
| `tool.started` | `tool_name`, `args` |
| `tool.finished` | `tool_name`, `ok`, `data`, `duration_ms` |
| `agent.message` | `role`, `content`, `final` |
conversation.finished` | `conversation_id`, `ok| `error` | `code`, `message` |
## REPL 命令
```
/sessions 列出已连接的客户端
/use <install_id> 选择一个客户端用于后续命令
/exec <cmd> 在选定的客户端上运行 Shell 命令
/tool <name> <json> 调度原始
/agent <prompt> 与 AI 代理聊天（自动管理工具）
/back 取消选择当前客户端
/quit 退出
```
## 构建
```bash
make build # 服务器 + 客户端二进制文件
make build-server # 仅服务器
make build-client # 仅客户端
make test # 运行 Go 测试
make web-dev # 仪表盘开发服务器
make web-build # 仪表盘生产构建
make docker-build # Docker 镜像
```
## 部署示例
典型的带有终止的生产设置```
Internet ─ nginx :TLS) ──► VectorShell :8084
│ │
│ 证书：acme.sh │
│ 代理传递 /ws │
└────────────────────────┘
```
```nginx
listen 5443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/fullchain.cer;
ssl_certificate_key /path/to/private.key;
location /ws {
proxy_pass http://127.0.0.1:8084;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400s;
}
location / {
proxy_pass http://127.0.0.1:8084;
}
}
```
## 许可证
MIT
