Metadata-Version: 2.4
Name: ganiu-remote
Version: 2.1.0
Summary: 嘎妞连接器 — 让 App 指挥你电脑上的 Claude Code / Codex / Hermes（中继 + 局域网直连双通道）
Author: Ganiu
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://ganiu.paihuai.vip
Keywords: agent,remote,claude-code,codex,hermes,mdns,websocket
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets<17,>=12.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: zeroconf<1,>=0.132
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# 嘎妞连接器 ganiu-remote

让**嘎妞 App** 直接指挥你电脑上的 AI 编程助手 —— 手机上说一句话，电脑上的 **Claude Code / Codex / Hermes** 就开干，结果回到手机。

两条通道，装一次都有：

| 通道 | 走哪 | 费用 | 适用 |
|---|---|---|---|
| **中继** | 经嘎妞服务器（`wss://`） | 会员功能 | 人在外面，手机和电脑不在同一网络 |
| **直连** | 局域网 HTTP + mDNS | **免费** | 手机和电脑连同一个 WiFi |

同一个包、同一份代码，Windows / Linux / macOS 都能跑，不需要分平台安装两套。

---

## 安装

```bash
pip install ganiu-remote
ganiu-remote --version    # ganiu-remote 2.0.0
```

需要 Python 3.10 及以上。

## 快速开始

### 1. 中继模式（异地也能用）

在 App 里进入「遥控器 → 连接器」，复制配对 token，然后：

```bash
ganiu-remote run --mode relay --token <你的token>
```

看到这些日志就成功了：

```
✅ 中继通道已连接
认证成功  user=98  connector=conn-xxxx
能力上报: claude_code/codex/hermes
```

不想每次带 token，可以写进环境变量：

```bash
export GANIU_REMOTE_TOKEN=<你的token>      # Windows: setx GANIU_REMOTE_TOKEN "..."
ganiu-remote run --mode relay
```

### 2. 直连模式（同一个 WiFi，免费）

**电脑端**

```bash
ganiu-remote run --mode direct
```

**手机端**：App → 遥控器 → 局域网直连 → 申请配对码 → 点「扫描并配对」

配对码 60 秒有效、一次性。配对成功后连接器会换发一个新的直连 token，旧的立刻失效。

> 如果 App 扫不到设备（常见于公司网络禁 mDNS），可以直接在 App 里手输电脑 IP + 配对码，功能完全一样。

### 3. 双通道一起跑

```bash
ganiu-remote run --mode both
```

一条通道挂了不影响另一条 —— 中继没配 token 时只会打印警告，直连照常工作。

---

## 命令行

```bash
ganiu-remote discover                 # 探测本机有哪些 agent 可用
ganiu-remote run --mode auto          # 有 token 走中继，没 token 走直连
ganiu-remote direct                   # 只跑直连
ganiu-remote pair --code 1a2b3c4d     # 命令行完成配对（等价于 App 扫码）
ganiu-remote config --hermes-key KEY  # 配置本地 Hermes 网关 key
```

`connect` 是 v1 留下的兼容命令，新装不用它。

---

## 支持的 Agent

| Agent | 要求 |
|---|---|
| **Claude Code** | 本机装好 `claude` 并已登录 |
| **Codex** | 本机装好 `codex` 并已登录 |
| **Hermes** | 本机跑着 Hermes，`ganiu-remote config --hermes-key` 填过 key |
| **OpenAI 兼容端点** | 用 `--openai-url / --openai-key / --openai-model` 配任意第三方 API |

用 `ganiu-remote discover` 可以随时看每个 agent 的 `available` 和 `logged_in`。

---

## 配置文件

位置：`~/.ganiu-remote/config.json`（Windows：`%USERPROFILE%\.ganiu-remote\config.json`）

可以用环境变量覆盖：

| 变量 | 作用 |
|---|---|
| `GANIU_REMOTE_HOME` | 换配置目录 |
| `GANIU_REMOTE_URL` | 换中继地址 |
| `GANIU_REMOTE_TOKEN` | 配对 token |
| `GANIU_DIRECT_PORT` | 直连端口（默认 18792） |
| `GANIU_CONNECTOR_ID` | 连接器 ID（通常不用改） |

从 1.x 升级上来会自动迁移，迁移前会把老配置备份成 `config.json.bak-v1`。

---

## 常见问题

**连不上中继，报 `timed out during handshake`**
检查 `ganiu-remote config` 里的 `relay_url` 是不是 `wss://ganiu.paihuai.vip/im/gateway`。1.x 的默认值是一个明文端口，永远连不上。

**手机扫不到设备**
1. 确认在同一个 WiFi（不是 5G 蜂窝）
2. Windows 首次运行要允许「专用网络」访问；已经点错了就跑一次：
   ```powershell
   netsh advfirewall firewall add rule name="Ganiu Relay Direct" dir=in action=allow protocol=TCP localport=18792 profile=private
   ```
3. 都不行就手输 IP —— 功能一样

**`discover` 里 agent 都是 unavailable**
CLI 没在 PATH 里，或者装在 WSL / 容器里而连接器装在 Windows。用 `where claude`（Windows）或 `which claude`（Linux）确认。

**端口 18792 被占用**
```bash
ganiu-remote run --mode direct --direct-port 18888
```

---

## 安全说明

- 直连 token 只存在本机，配对成功后立即轮换，旧 token 作废
- 配对码 60 秒过期、一次性、连续试错会锁定
- 连接器不会把你的 token / key 上送到任何地方；`hermes_key` 只从本机 `.env` 读
- 中继通道的详细威胁模型见 `docs/direct-security.md`

---

## 许可

私有软件，随嘎妞 App 一起授权使用。
