内容
# Gemini Telegram Bridge v2
将您的本地 [Gemini CLI](https://geminicli.com) 会话桥接到 Telegram 上。
从任何地方与您的本地 AI 代理对话 — 具有流式回复、每个用户会话和实时仪表盘。
---
## 新增功能 v2
| 功能 | 详情 |
|---|---|
| **每个用户会话** | 每个 Telegram 用户都获得一个独立的 Gemini 会话。不会有交叉对话。 |
| **实时流式回复** | 机器人实时编辑其消息，如打字效果一样。 |
| **崩溃恢复** | Gemini 子进程在崩溃时自动重启。会话自动恢复。 |
| **超时处理** | 所有 RPC 调用都有截止日期。挂起的请求会干净地失败。 |
| **管理员命令** | 完全从 Telegram 管理用户：批准、撤销、提升、列表。 |
| **文件和图像支持** | 发送照片或文档 — 转发到 Gemini 并附上说明。 |
| **网页仪表盘** | 在 `http://localhost:7823` 处的实时会话监视器，自动刷新。 |
| **忙碌守护** | 如果在处理另一个消息时发送第二个消息，您将收到明确的通知。 |
| **会话历史** | `/history` 显示当前会话的最后 10 次交换。 |
---
## 先决条件
- [Bun](https://bun.sh)（推荐）或 Node.js 20+
- 已安装并认证的 [Gemini CLI](https://geminicli.com)（`gemini --acp` 必须有效）
- 来自 [@BotFather](https://t.me/BotFather) 的 Telegram 机器人令牌
---
## 安装
```bash
git clone https://github.com/yourusername/gemini-telegram-bridge.git
cd gemini-telegram-bridge
bun install
cp .env.example .env
# 编辑 .env 并填写 TELEGRAM_BOT_TOKEN
```
---
## 运行
```bash
# 生产环境
bun run start
# 开发环境（文件更改时自动重启）
bun run dev
# 跟随日志
bun run logs
```
---
## 配对（首次访问）
1. 在 Telegram 上给您的机器人发送消息 — 任何文本都有效。
2. 机器人用一个 6 位配对代码回复。
3. 从 Telegram 批准（如果您已经是管理员）使用 `/approve CODE`。
4. 或者从终端批准：
```bash
# Linux / macOS
touch ~/.gemini/channels/telegram/approved/YOUR_CODE
# Windows PowerShell
New-Item "$HOME\.gemini\channels\telegram\approved\YOUR_CODE"
```
5. 机器人确认。您已连接。
> **第一个被批准的用户自动成为管理员。**
---
## Telegram 命令
### 所有人
| 命令 | 功能 |
|---|---|
| `/start` | 欢迎消息 + 会话信息 |
| `/help` | 显示所有可用命令 |
| `/reset` | 与 Gemini 开始新的对话 |
| `/status` | 桥接健康状况、会话数、运行时间 |
| `/history` | 当前会话的最后 10 条消息 |
| `/myid` | 显示您的数字 Telegram 用户 ID |
### 仅限管理员
| 命令 | 功能 |
|---|---|
| `/users` | 列出所有已批准的用户（🟢 = 在线） |
| `/pending` | 显示待处理的配对请求 |
| `/approve <code>` | 在不接触终端的情况下批准配对代码 |
| `/revoke <user_id>` | 立即撤销用户的访问权限 |
| `/promote <user_id>` | 授予用户管理员权限 |
---
## 网页仪表盘
在桥接运行时，在浏览器中打开 `http://localhost:7823`。
显示：
- Gemini 状态（在线/离线，带有脉动指示器）
- 活动会话，包含最后活动时间和忙碌状态
- 所有已批准的用户及其当前连接状态
- 待处理批准，包含代码可供复制
- 滚动日志尾部（最后 30 行）
每 5 秒自动刷新。可以使用 `.env` 中的 `DASHBOARD_PORT` 更改端口。
---
## 配置（`.env`）
| 变量 | 默认值 | 描述 |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | _(必填)_ | 来自 BotFather 的令牌 |
| `GEMINI_PATH` | `gemini` | 如果不在 PATH 中，则为 `gemini.cmd` 的完整路径 |
| `SESSION_TIMEOUT_MS` | `3600000` | 空闲会话过期时间（毫秒）（默认为 1 小时） |
| `STREAM_INTERVAL_MS` | `700` | 流式传输消息时编辑消息的频率 |
| `DASHBOARD_PORT` | `7823` | 网页仪表盘的端口 |
---
## Windows 自动启动
1. 在某个永久位置（例如 `C:\Users\YourUser\scripts\`）创建 `start-bridge.vbs`：
```vbs
Set WshShell = CreateObject("WScript.Shell")
WshShell.Run "bun run C:\path\to\gemini-telegram-bridge\bridge.ts", 0
Set WshShell = Nothing
```
2. 按 `Win + R`，输入 `shell:startup`，按 Enter。
3. 将 `.vbs` 文件的快捷方式放在该文件夹中。
---
## Linux 自动启动（systemd）
创建 `/etc/systemd/system/gemini-bridge.service`:
```ini
[Unit]
Description=Gemini Telegram Bridge
After=network.target
[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/path/to/gemini-telegram-bridge
EnvironmentFile=/path/to/gemini-telegram-bridge/.env
ExecStart=/home/YOUR_USER/.bun/bin/bun run bridge.ts
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now gemini-bridge
sudo journalctl -u gemini-bridge -f # 实时日志
```
---
## 项目结构
```
gemini-telegram-bridge/
├── bridge.ts — 机器人逻辑、命令、消息处理程序
├── gemini.ts — GeminiProcess：生命周期、RPC、流式传输、崩溃恢复
├── access.ts — AccessManager：用户、配对代码、管理员角色
├── dashboard.ts — 网页仪表盘（Bun HTTP 服务器）
├── types.ts — 共享 TypeScript 接口
├── .env.example — 配置模板
└── bridge.log — 运行时日志文件（自动创建）
```
---
## 许可证
MIT
MCP 市场