252 lines
9.3 KiB
Markdown
252 lines
9.3 KiB
Markdown
<img src="assets/icons/brand-header.svg" alt="RemoteConn / AI矩连" width="420" align="left" />
|
|
|
|
<p align="right">
|
|
<strong>English</strong> | <a href="./README_cn.md">中文</a>
|
|
</p>
|
|
|
|
<br clear="all" />
|
|
|
|
# RemoteConn
|
|
|
|
RemoteConn is a production-oriented remote access workspace built around `shell + chat`. It targets Web, mobile app, and Mini Program entry points, so AI-assisted server work can start from a phone and stay attached to the right project context.
|
|
|
|
The project focuses on three practical problems:
|
|
|
|
1. Keep an AI-capable shell available on mobile, not only on desktop IDEs.
|
|
2. Use voice input to reduce typing cost on phones.
|
|
3. Preserve task context, records, and server bindings so long-running work can continue without handoff friction.
|
|
|
|
<p align="left">
|
|
<img src="./微信标准绿版.png" alt="WeChat Standard Green Version" width="420" />
|
|
</p>
|
|
|
|
## Monorepo Structure
|
|
|
|
- `apps/web`: Vue 3 + TypeScript + xterm.js frontend
|
|
- `apps/gateway`: Node.js gateway for `WSS -> SSH`
|
|
- `packages/shared`: shared models, state machines, Codex orchestration, theme and security helpers
|
|
- `packages/plugin-runtime`: plugin runtime with validation, permission control, lifecycle hooks, isolation, and circuit breaking
|
|
- `ios/plugin/RemoteConnSSHPlugin`: Capacitor iOS SSH plugin skeleton
|
|
|
|
## Implemented Capabilities
|
|
|
|
1. Server and credential management with restricted local storage
|
|
2. Terminal session state machine for connect, reconnect, auth pending, and error states
|
|
3. Bidirectional gateway forwarding for `init/stdin/stdout/stderr/resize/control`
|
|
4. Codex launch orchestration with remote environment checks
|
|
5. Session logging and redacted export
|
|
6. Theme system with contrast tuning
|
|
7. Plugin runtime foundation
|
|
|
|
## Latest Status
|
|
|
|
Current README baseline: `v3.0.1` on `2026-03-20`.
|
|
|
|
Recent milestones:
|
|
|
|
- `v3.0.1`: Mini Program manual was expanded with image-based guidance, theme presets were aligned with Web to `21` sets, and the project docs were synchronized.
|
|
- `v3.0.0`: Terminal interaction stability was improved during Codex output, including caret stability and keyboard-focus handling.
|
|
- Cross-device sync currently covers `settings`, `servers`, and `records`. Sensitive server fields remain encrypted as `secret_blob`.
|
|
|
|
Known limitations still tracked in the project docs:
|
|
|
|
- Some Mini Program terminal performance issues can still appear during long AI output sessions.
|
|
- Voice playback extraction and turn detection are not yet considered stable enough for default use.
|
|
|
|
For the full Chinese product narrative and detailed historical notes, see [README_cn.md](./README_cn.md), `CHANGELOG.md`, and `release.md`.
|
|
|
|
## Operation Guide
|
|
|
|
This guide reuses the five annotated screenshots from the project introduction and keeps the same visual grouping so the main workflow can be understood directly from the README.
|
|
|
|
For the narrow vertical mobile layout version, see [Mobile Operation Guide](./docs/mobile-operation-guide-2026-03-20.md).
|
|
|
|
### 1. Server List And Configuration
|
|
|
|
|
|
|
|
1. The home page opens on the server list, which is the starting point of the product.
|
|
2. The top toolbar is used to add, delete, select, and search servers.
|
|
3. The main body of each server card opens the configuration page; the quick actions on the right can duplicate a profile, launch AI, or connect directly.
|
|
4. The bottom navigation switches between terminal, logs, records, settings, and about pages.
|
|
5. The configuration page is where you fill in the basic connection fields, authentication method, and project directory.
|
|
6. `AI Working Directory` defines the default project context for AI startup and is a key part of the collaboration flow.
|
|
7. If the target host is reached through a jump host, complete the jump-host fields and its separate authentication settings on the same page.
|
|
8. The recommended order is to save the profile first and then start the connection.
|
|
|
|
### 2. Terminal, AI, And Connection Diagnostics
|
|
|
|
|
|
|
|
1. After entering the terminal, you can run shell commands directly or switch to an AI workflow such as `Codex` from the top-left entry.
|
|
2. The top status bar continuously shows connection state, latency, and session overview, making it the primary feedback area for mobile troubleshooting.
|
|
3. Tapping `Connected` opens the session detail panel with the target host, connection state, and working directory.
|
|
4. Tapping `Latency` opens the diagnostics panel so you can inspect gateway response and network latency trends and judge link quality.
|
|
|
|
### 3. Voice Input And Shortcut Panel
|
|
|
|
|
|
|
|
1. The `voice` button at the bottom of the terminal page opens the voice input panel, supporting a "speak first, decide later" input flow.
|
|
2. The voice draft can be sent to the terminal directly or saved as a record together with category tags.
|
|
3. The `keyboard` button at the bottom opens the shortcut panel to restore terminal control keys that are missing on mobile.
|
|
4. The right-side shortcut panel includes arrow keys, `Esc`, `Ctrl+C`, `Tab`, and other high-frequency controls to reduce input friction on phones.
|
|
|
|
### 4. Settings Center
|
|
|
|
|
|
|
|
1. The settings page is grouped into `UI / Terminal / Connection / Records`, covering appearance, terminal behavior, connection policy, and data management.
|
|
2. The UI tab controls theme, colors, and language, which shape the overall experience.
|
|
3. The terminal tab controls font family, font size, line height, and terminal palette, directly affecting readability and typing efficiency.
|
|
4. The connection tab controls default authentication, reconnect strategy, background keepalive, sync switches, and AI defaults.
|
|
5. The records tab controls record retention and category management so the information lifecycle stays structured.
|
|
|
|
### 5. Records And About
|
|
|
|
|
|
|
|
1. The records page is used to capture issues, ideas, TODOs, and context fragments.
|
|
2. The top area supports search and category filtering so content can be found quickly.
|
|
3. Record cards support actions such as copy, mark, and delete.
|
|
4. The bottom area provides pagination, add, and export operations.
|
|
5. The about page centralizes the brand, version, and product information entry points.
|
|
6. It collects the user guide, feedback channel, privacy policy, change log, and about content in one place.
|
|
7. Its role is to act as the final landing page for product documentation inside the app, so users can find a consistent explanation without leaving the product.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev:gateway
|
|
npm run dev:web
|
|
```
|
|
|
|
Default endpoints:
|
|
|
|
- Web: `http://localhost:5173`
|
|
- Gateway: `http://localhost:8787`
|
|
- Gateway WS: `ws://localhost:8787/ws/terminal`
|
|
|
|
## Environment Variables
|
|
|
|
### Gateway
|
|
|
|
```bash
|
|
cp apps/gateway/.env.example apps/gateway/.env
|
|
```
|
|
|
|
Recommended runtime config:
|
|
|
|
```dotenv
|
|
PORT=8787
|
|
HOST=0.0.0.0
|
|
GATEWAY_TOKEN=replace-with-strong-random-token
|
|
CORS_ORIGIN=https://your-domain.com
|
|
DEBUG_IO_HEX=0
|
|
ASR_INCLUDE_RAW_RESULT=0
|
|
ASR_EMPTY_TEXT_WARN_LIMIT=3
|
|
```
|
|
|
|
### Web
|
|
|
|
```bash
|
|
cp apps/web/.env.example apps/web/.env
|
|
```
|
|
|
|
Build-time config:
|
|
|
|
```dotenv
|
|
VITE_GATEWAY_URL=wss://your-domain.com
|
|
VITE_GATEWAY_TOKEN=replace-with-strong-random-token
|
|
VITE_ENABLE_PLUGIN_RUNTIME=false
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `VITE_GATEWAY_TOKEN` must match `GATEWAY_TOKEN`.
|
|
- `VITE_ENABLE_PLUGIN_RUNTIME=false` is the recommended initial production posture if plugin support is not needed yet.
|
|
- If you expose the service through Nginx or Caddy on `443/80`, the internal gateway can still listen on `8787`.
|
|
|
|
## Quality Commands
|
|
|
|
```bash
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run test
|
|
```
|
|
|
|
## Gateway Operations
|
|
|
|
Unified script: `scripts/gatewayctl.sh`
|
|
|
|
```bash
|
|
# First-time deployment
|
|
scripts/gatewayctl.sh ensure-env
|
|
scripts/gatewayctl.sh install-service $USER
|
|
scripts/gatewayctl.sh deploy
|
|
|
|
# Daily operations
|
|
scripts/gatewayctl.sh status
|
|
scripts/gatewayctl.sh logs 200
|
|
scripts/gatewayctl.sh logs-clear
|
|
scripts/gatewayctl.sh restart
|
|
scripts/gatewayctl.sh health
|
|
|
|
# Foreground local run
|
|
scripts/gatewayctl.sh run-local
|
|
```
|
|
|
|
- Linux uses `systemd`.
|
|
- macOS uses `launchd` at `~/Library/LaunchAgents/com.remoteconn.gateway.plist`.
|
|
|
|
## Logs
|
|
|
|
```shell
|
|
launchctl print gui/$(id -u)/com.remoteconn.gateway | rg -n "stdout path|stderr path"
|
|
tail -f /Users/gavin/Library/Logs/com.remoteconn.gateway.out.log
|
|
```
|
|
|
|
## Benchmarks
|
|
|
|
Gateway SSH2 baseline:
|
|
|
|
```bash
|
|
npm --workspace @remoteconn/gateway run bench
|
|
```
|
|
|
|
Example with explicit parameters:
|
|
|
|
```bash
|
|
BENCH_SSH_HOST=127.0.0.1 \
|
|
BENCH_SSH_PORT=22 \
|
|
BENCH_SSH_USER="$USER" \
|
|
BENCH_PRIVATE_KEY=~/.ssh/id_ed25519 \
|
|
BENCH_ITERATIONS=30 \
|
|
BENCH_PAYLOAD_KB=1024 \
|
|
npm --workspace @remoteconn/gateway run bench
|
|
```
|
|
|
|
TTYD baseline:
|
|
|
|
```bash
|
|
ttyd -v
|
|
|
|
BENCH_SSH_HOST=127.0.0.1 \
|
|
BENCH_SSH_PORT=22 \
|
|
BENCH_SSH_USER="$USER" \
|
|
BENCH_SSH_IDENTITY=~/.ssh/id_ed25519 \
|
|
BENCH_ITERATIONS=30 \
|
|
BENCH_PAYLOAD_KB=1024 \
|
|
npm --workspace @remoteconn/gateway run bench:ttyd
|
|
```
|
|
|
|
## Related Documents
|
|
|
|
- `docs/server-management-ux-iteration-2026-02-25.md`
|
|
- `docs/terminal-voice-input-plan-2026-02-26.md`
|
|
- `docs/web-storage-layering-guideline-2026-02-25.md`
|
|
- `docs/touch-focus-state-machine-plan-2026-02-23.md`
|
|
- `CHANGELOG.md`
|
|
- `release.md`
|