bytesbrains-pi-telegram-bridge

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-telegram-bridge

Telegram bot bridge for pi agents — send messages, ask questions, receive photos, and get a live project dashboard on "hi".

## Install

```bash
pi install npm:@bytesbrains/pi-telegram-bridge@1.1.6
```

## Quick Setup

### 1. Create a bot with @BotFather

Open Telegram and chat with [@BotFather](https://t.me/BotFather):

```
/newbot
```

Follow the prompts. You'll get a token like:

```
123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11
```

### 2. Get your Chat ID

Send ANY message to your new bot on Telegram, then visit this URL in your browser:

```
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
```

Look for `"chat":{"id":123456789}` in the response. That's your chat ID.

> **For group chats:** Add the bot to a group, send a message mentioning the bot, then check the same URL. Use the group chat ID.

### 3. Set environment variables

```bash
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11"
export TELEGRAM_CHAT_ID="123456789"
```

Add them to your shell profile (`~/.zshrc`, `~/.bashrc`) to persist across sessions.

### 4. Verify

Start pi and run `telegram_status()`. You should see:

```
Active. Bot: @your_bot_name (listener: 🟢 running)
```

## Environment Variables

| Variable             | Required | Default                 | Description                                                     |
| -------------------- | -------- | ----------------------- | --------------------------------------------------------------- |
| `TELEGRAM_BOT_TOKEN` | ✅       | —                       | Bot token from @BotFather                                       |
| `TELEGRAM_CHAT_ID`   | ✅       | —                       | Chat ID to send/receive messages                                |
| `TELEGRAM_MENTION`   | ❌       | `@pi` (or bot username) | Only respond to messages containing this mention in group chats |

### TELEGRAM_MENTION

Controls which messages the agent responds to in **group chats**:

```bash
# Use a custom mention trigger
export TELEGRAM_MENTION="@mybot"

# Or let it auto-detect from the bot username
export TELEGRAM_MENTION=""   # defaults to @bot_username
```

- **Private chat** (direct message to bot): All messages are treated as directed — no mention needed
- **Group chat**: Only messages containing `@botname` are forwarded to the agent. Everything else is ignored.

## Features

### Status Dashboard

Send `hi`, `/status`, or `status` to your bot on Telegram. It replies with a live project summary:

```
📊 pi-ext Status

📋 Open Issues: 3
   #1 telegram-bridge HTML parse crash
   #5 status dashboard on hi message

🔀 Open PRs: 2
   ✅ #2 fix(telegram-bridge): escape HTML entities

🔧 Last CI: ⏳ queued (5 recent runs)
```

### Photo Support

**Send photos to the agent:** Send any photo to the bot — the agent downloads it and can use `read()` to view it. Add a caption for context:

> 📸 Photo: `login page broken, 404 in console`

**Send photos from the agent:** Use `telegram_send_photo()` to share screenshots or diagrams:

```
telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Build output")
```

### @Mention Support

In group chats, the bot only responds to messages that mention it. This lets humans talk freely without triggering the agent.

| Chat type | Message                  | Bot responds?                            |
| --------- | ------------------------ | ---------------------------------------- |
| Private   | `hi`                     | ✅                                       |
| Private   | `@pi what's the status?` | ✅ (mention stripped)                    |
| Group     | `hi`                     | ❌                                       |
| Group     | `@pi what's the status?` | ✅ (agent receives `what's the status?`) |

## Tools

### telegram_listen

Check for new inbound messages (text and photos) from the human.

```
telegram_listen()
```

Returns photo paths and captions if a photo was received.

### telegram_send

Send a one-way text message.

```
telegram_send(message="Build completed successfully ✅")
```

### telegram_send_photo

Send a photo — supports local file paths and remote URLs.

```
telegram_send_photo(photoPath="/tmp/screenshot.png")
telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Error in console")
telegram_send_photo(photoPath="https://example.com/image.jpg")
```

### telegram_ask

Ask a question with inline keyboard options and **wait** for a human reply. Blocks until answered or timeout (default 30 min).

```
telegram_ask(question="Deploy to production?")
telegram_ask(question="Which branch?", options=["main", "staging", "dev"])
telegram_ask(question="Approve this change?", options=["Approve", "Reject", "Need changes"], timeoutMinutes=5)
```

### telegram_override

Ask a human to approve or reject a blocked action (force push, destructive git ops, file deletion, etc.). Designed for supervisor override flows. Returns `details.action = "proceed"|"abort"|"explain"` so the agent can call `supervisor_override()` or abort.

```
telegram_override(
  command="git push gitea feat/add-check --force",
  reason="Force push can overwrite remote history"
)

telegram_override(
  command="rm -rf node_modules",
  reason="Recursive deletion outside project boundary",
  context="User requested a clean reinstall of dependencies",
  options=["Yes, it's fine", "No, cancel", "Use npx instead", "Explain more"],
  timeoutMinutes=10
)
```

**Parameters:**
| Param | Required | Default | Description |
|-------|----------|---------|-------------|
| `command` | ✅ | — | The blocked command or action |
| `reason` | ✅ | — | Why it was blocked by the supervisor |
| `context` | ❌ | — | Additional context (what the user asked for, etc.) |
| `options` | ❌ | `["Yes, proceed", "No, cancel", "Explain more"]` | Custom button labels |
| `timeoutMinutes` | ❌ | `30` | How long to wait for a response |

**Returns `details`:**
| Field | Type | Description |
|-------|------|-------------|
| `choice` | `string` | The exact button label the human clicked |
| `action` | `string` | `"proceed"` (first option), `"abort"` (second option), or `"explain"` (anything else) |
| `command` | `string` | The original blocked command |
| `timedOut` | `boolean` | Whether the request timed out |

**Agent workflow:**

1. Agent gets blocked by supervisor
2. Calls `telegram_override(command, reason, context)`
3. Checks `details.action`:
   - `"proceed"` → call `supervisor_override(reason, command)`
   - `"abort"` → tell user action was cancelled
   - `"explain"` → call `telegram_send(message="...")` with more context, then re-ask
4. If `details.timedOut` → abort the action

### telegram_status

Check if the bridge is configured and running.

```
telegram_status()
```

## Requirements

- Node.js >= 18
- A Telegram bot token (from @BotFather)
- A chat ID

## License

MIT

---

Built and maintained by [BytesBrains](https://bytesbrains.com) — AI automation & agents, engineered to production standards.
*The model proposes, code guarantees.*

pi-telegram-bridge

Telegram bot bridge for pi agents — send messages, ask questions, receive photos, and get a live project dashboard on "hi".

Install

pi install npm:@bytesbrains/pi-telegram-bridge@1.1.6

Quick Setup

1. Create a bot with @BotFather

Open Telegram and chat with @BotFather:

/newbot

Follow the prompts. You'll get a token like:

123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11

2. Get your Chat ID

Send ANY message to your new bot on Telegram, then visit this URL in your browser:

https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Look for "chat":{"id":123456789} in the response. That's your chat ID.

For group chats: Add the bot to a group, send a message mentioning the bot, then check the same URL. Use the group chat ID.

3. Set environment variables

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghikl-zyx57W2v1u123ew11"
export TELEGRAM_CHAT_ID="123456789"

Add them to your shell profile (~/.zshrc, ~/.bashrc) to persist across sessions.

4. Verify

Start pi and run telegram_status(). You should see:

Active. Bot: @your_bot_name (listener: 🟢 running)

Environment Variables

Variable	Required	Default	Description
`TELEGRAM_BOT_TOKEN`	✅	—	Bot token from @BotFather
`TELEGRAM_CHAT_ID`	✅	—	Chat ID to send/receive messages
`TELEGRAM_MENTION`	❌	`@pi` (or bot username)	Only respond to messages containing this mention in group chats

TELEGRAM_MENTION

Controls which messages the agent responds to in group chats:

# Use a custom mention trigger
export TELEGRAM_MENTION="@mybot"

# Or let it auto-detect from the bot username
export TELEGRAM_MENTION=""   # defaults to @bot_username

Private chat (direct message to bot): All messages are treated as directed — no mention needed
Group chat: Only messages containing @botname are forwarded to the agent. Everything else is ignored.

Features

Status Dashboard

Send hi, /status, or status to your bot on Telegram. It replies with a live project summary:

📊 pi-ext Status

📋 Open Issues: 3
   #1 telegram-bridge HTML parse crash
   #5 status dashboard on hi message

🔀 Open PRs: 2
   ✅ #2 fix(telegram-bridge): escape HTML entities

🔧 Last CI: ⏳ queued (5 recent runs)

Photo Support

Send photos to the agent: Send any photo to the bot — the agent downloads it and can use read() to view it. Add a caption for context:

📸 Photo: login page broken, 404 in console

Send photos from the agent: Use telegram_send_photo() to share screenshots or diagrams:

telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Build output")

@Mention Support

In group chats, the bot only responds to messages that mention it. This lets humans talk freely without triggering the agent.

Chat type	Message	Bot responds?
Private	`hi`	✅
Private	`@pi what's the status?`	✅ (mention stripped)
Group	`hi`	❌
Group	`@pi what's the status?`	✅ (agent receives `what's the status?`)

Tools

telegram_listen

Check for new inbound messages (text and photos) from the human.

telegram_listen()

Returns photo paths and captions if a photo was received.

telegram_send

Send a one-way text message.

telegram_send(message="Build completed successfully ✅")

telegram_send_photo

Send a photo — supports local file paths and remote URLs.

telegram_send_photo(photoPath="/tmp/screenshot.png")
telegram_send_photo(photoPath="/tmp/screenshot.png", caption="Error in console")
telegram_send_photo(photoPath="https://example.com/image.jpg")

telegram_ask

Ask a question with inline keyboard options and wait for a human reply. Blocks until answered or timeout (default 30 min).

telegram_ask(question="Deploy to production?")
telegram_ask(question="Which branch?", options=["main", "staging", "dev"])
telegram_ask(question="Approve this change?", options=["Approve", "Reject", "Need changes"], timeoutMinutes=5)

telegram_override

Ask a human to approve or reject a blocked action (force push, destructive git ops, file deletion, etc.). Designed for supervisor override flows. Returns details.action = "proceed"|"abort"|"explain" so the agent can call supervisor_override() or abort.

telegram_override(
  command="git push gitea feat/add-check --force",
  reason="Force push can overwrite remote history"
)

telegram_override(
  command="rm -rf node_modules",
  reason="Recursive deletion outside project boundary",
  context="User requested a clean reinstall of dependencies",
  options=["Yes, it's fine", "No, cancel", "Use npx instead", "Explain more"],
  timeoutMinutes=10
)

Parameters:

Param	Required	Default	Description
`command`	✅	—	The blocked command or action
`reason`	✅	—	Why it was blocked by the supervisor
`context`	❌	—	Additional context (what the user asked for, etc.)
`options`	❌	`["Yes, proceed", "No, cancel", "Explain more"]`	Custom button labels
`timeoutMinutes`	❌	`30`	How long to wait for a response

Returns details:

Field	Type	Description
`choice`	`string`	The exact button label the human clicked
`action`	`string`	`"proceed"` (first option), `"abort"` (second option), or `"explain"` (anything else)
`command`	`string`	The original blocked command
`timedOut`	`boolean`	Whether the request timed out

Agent workflow:

Agent gets blocked by supervisor
Calls telegram_override(command, reason, context)
Checks details.action:
- "proceed" → call supervisor_override(reason, command)
- "abort" → tell user action was cancelled
- "explain" → call telegram_send(message="...") with more context, then re-ask
If details.timedOut → abort the action

telegram_status

Check if the bridge is configured and running.

telegram_status()

Requirements

Node.js >= 18
A Telegram bot token (from @BotFather)
A chat ID

License

MIT

Built and maintained by BytesBrains — AI automation & agents, engineered to production standards. The model proposes, code guarantees.