Skip to content

Commit 11c0a03

Browse files
frostmingfrostming
committed
docs: refresh usage and deployment guides with discord support
1 parent 91f39dc commit 11c0a03

File tree

9 files changed

+233
-12
lines changed

9 files changed

+233
-12
lines changed

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,16 +68,28 @@ Common commands:
6868
BUB_TELEGRAM_ENABLED=true
6969
BUB_TELEGRAM_TOKEN=123456:token
7070
BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
71-
uv run bub telegram
71+
uv run bub message
72+
```
73+
74+
## Discord (Optional)
75+
76+
```bash
77+
BUB_DISCORD_ENABLED=true
78+
BUB_DISCORD_TOKEN=discord_bot_token
79+
BUB_DISCORD_ALLOW_FROM='["123456789012345678","your_discord_name"]'
80+
BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
81+
uv run bub message
7282
```
7383

7484
## Documentation
7585

7686
- `docs/index.md`: getting started and usage overview
87+
- `docs/deployment.md`: local + Docker deployment playbook
7788
- `docs/features.md`: key capabilities and why they matter
7889
- `docs/cli.md`: interactive CLI workflow and troubleshooting
7990
- `docs/architecture.md`: agent loop, tape, anchor, and tool/skill design
8091
- `docs/telegram.md`: Telegram integration and operations
92+
- `docs/discord.md`: Discord integration and operations
8193

8294
## Development
8395

‎docs/cli.md‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,27 @@
11
# Interactive CLI
22

3-
## Start
3+
## Runtime Commands
44

55
```bash
6-
uv run bub
6+
uv run bub chat
77
```
88

9-
Optional:
9+
Optional chat flags:
1010

1111
```bash
12-
uv run bub chat --workspace /path/to/repo --model openrouter:qwen/qwen3-coder-next --max-tokens 1400
12+
uv run bub chat \
13+
--workspace /path/to/repo \
14+
--model openrouter:qwen/qwen3-coder-next \
15+
--max-tokens 1400 \
16+
--session-id cli-main
1317
```
1418

19+
Other runtime modes:
20+
21+
- `uv run bub run "summarize current repo status"`: one-shot message and exit.
22+
- `uv run bub message`: run enabled message channels (Telegram/Discord).
23+
- `uv run bub idle`: run scheduler only (no interactive CLI).
24+
1525
## How Input Is Interpreted
1626

1727
- Only lines starting with `,` are interpreted as commands.
@@ -35,7 +45,7 @@ Use shell mode when you want to run multiple shell commands quickly.
3545
1. Check repo status: `,git status`
3646
2. Read files: `,fs.read path=README.md`
3747
3. Edit files: `,fs.edit path=foo.py old=... new=...`
38-
4. Validate: `,uv run pytest -q`
48+
4. Validate: `uv run pytest -q`
3949
5. Mark phase transition: `,handoff name=phase-x summary="tests pass"`
4050

4151
## Session Context Commands
@@ -50,8 +60,16 @@ Use shell mode when you want to run multiple shell commands quickly.
5060
- `,tape.reset archive=true` archives then clears current tape.
5161
- `,anchors` shows phase boundaries.
5262

63+
## One-Shot Examples
64+
65+
```bash
66+
uv run bub run ",help"
67+
uv run bub run --tools fs.read,fs.glob --skills friendly-python "inspect Python layout"
68+
uv run bub run --disable-scheduler "quick reasoning task"
69+
```
70+
5371
## Troubleshooting
5472

5573
- `command not found`: verify whether it should be an internal command (`,help` for list).
56-
- Verbose or odd output: Bub may still be processing command follow-up context.
74+
- `bub message` exits immediately: no message channel is enabled in `.env`.
5775
- Context is too heavy: add a handoff anchor, then reset tape when needed.

‎docs/deployment.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Deployment Guide
2+
3+
This page covers production-oriented setups for Bub, including local process management and Docker Compose.
4+
5+
## 1) Prerequisites
6+
7+
- Python 3.12+
8+
- `uv` installed
9+
- A valid model provider key (for example `OPENROUTER_API_KEY` or `LLM_API_KEY`)
10+
11+
Quick bootstrap:
12+
13+
```bash
14+
git clone https://github.com/psiace/bub.git
15+
cd bub
16+
uv sync
17+
cp env.example .env
18+
```
19+
20+
Minimum `.env`:
21+
22+
```bash
23+
BUB_MODEL=openrouter:qwen/qwen3-coder-next
24+
OPENROUTER_API_KEY=sk-or-...
25+
```
26+
27+
## 2) Deployment Modes
28+
29+
Choose one mode based on your operation target:
30+
31+
1. Interactive local operator:
32+
`uv run bub chat`
33+
2. Channel service (Telegram/Discord):
34+
`uv run bub message`
35+
3. Scheduler-only autonomous runtime:
36+
`uv run bub idle`
37+
38+
One-shot operation:
39+
40+
```bash
41+
uv run bub run "summarize changes in this repo"
42+
```
43+
44+
## 3) Message Channel Deployment
45+
46+
Enable channels in `.env` first.
47+
48+
Telegram:
49+
50+
```bash
51+
BUB_TELEGRAM_ENABLED=true
52+
BUB_TELEGRAM_TOKEN=123456:token
53+
BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
54+
BUB_TELEGRAM_ALLOW_CHATS='["123456789","-1001234567890"]'
55+
```
56+
57+
Discord:
58+
59+
```bash
60+
BUB_DISCORD_ENABLED=true
61+
BUB_DISCORD_TOKEN=discord_bot_token
62+
BUB_DISCORD_ALLOW_FROM='["123456789012345678","your_discord_name"]'
63+
BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
64+
```
65+
66+
Start channel service:
67+
68+
```bash
69+
uv run bub message
70+
```
71+
72+
## 4) Docker Compose Deployment
73+
74+
The repository already provides `Dockerfile`, `docker-compose.yml`, and `entrypoint.sh`.
75+
76+
Build and run:
77+
78+
```bash
79+
docker compose up -d --build
80+
docker compose logs -f app
81+
```
82+
83+
Behavior in container:
84+
85+
- If `/workspace/startup.sh` exists, container starts `bub idle` in background, then executes `startup.sh`.
86+
- Otherwise, container starts `bub message`.
87+
88+
Default mounts in `docker-compose.yml`:
89+
90+
- `${BUB_WORKSPACE_PATH:-.}:/workspace`
91+
- `${BUB_HOME:-${HOME}/.bub}:/data`
92+
- `${BUB_AGENT_HOME:-${HOME}/.agent}:/root/.agent`
93+
94+
## 5) Operational Checks
95+
96+
Health checklist:
97+
98+
1. Process is running:
99+
`ps aux | rg "bub (chat|message|idle)"`
100+
2. Model key is loaded:
101+
`rg -n "BUB_MODEL|OPENROUTER_API_KEY|LLM_API_KEY" .env`
102+
3. Channel flags are correct:
103+
`rg -n "BUB_TELEGRAM_ENABLED|BUB_DISCORD_ENABLED" .env`
104+
4. Logs show channel startup:
105+
`uv run bub message` and confirm `channel.manager.start` output.
106+
107+
## 6) Safe Upgrade Procedure
108+
109+
```bash
110+
git fetch --all --tags
111+
git pull
112+
uv sync
113+
uv run ruff check .
114+
uv run mypy
115+
uv run pytest -q
116+
```
117+
118+
Then restart your runtime (`chat`, `message`, or container service).

‎docs/discord.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Discord Integration
2+
3+
Discord allows Bub to run as a remote coding assistant for team channels, threads, and DMs.
4+
5+
## Configure
6+
7+
```bash
8+
BUB_DISCORD_ENABLED=true
9+
BUB_DISCORD_TOKEN=discord_bot_token
10+
BUB_DISCORD_ALLOW_FROM='["123456789012345678","your_discord_name"]'
11+
BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
12+
```
13+
14+
Optional:
15+
16+
```bash
17+
BUB_DISCORD_COMMAND_PREFIX=!
18+
BUB_DISCORD_PROXY=http://127.0.0.1:7890
19+
```
20+
21+
Notes:
22+
23+
- If `BUB_DISCORD_ALLOW_FROM` is empty, all senders are accepted.
24+
- If `BUB_DISCORD_ALLOW_CHANNELS` is empty, all channels are accepted.
25+
- In production, use strict allowlists.
26+
27+
## Run
28+
29+
```bash
30+
uv run bub message
31+
```
32+
33+
## Runtime Behavior
34+
35+
- Uses `discord.py` bot runtime.
36+
- Each Discord channel maps to `discord:<channel_id>` session key.
37+
- Inbound text enters the same `AgentLoop` used by CLI.
38+
- Outbound immediate output is sent back in-channel (split into chunks when too long).
39+
- Bub processes messages in these cases:
40+
- DM channel
41+
- message includes `bub`
42+
- message starts with `!bub` (or your configured prefix)
43+
- message mentions the bot
44+
- message replies to a bot message
45+
- thread name starts with `bub`
46+
47+
## Security and Operations
48+
49+
1. Keep bot token only in `.env` or a secret manager.
50+
2. Restrict `BUB_DISCORD_ALLOW_CHANNELS` and `BUB_DISCORD_ALLOW_FROM`.
51+
3. Confirm the bot has message-content intent enabled in Discord Developer Portal.
52+
4. If no response is observed, verify token, allowlists, intents, and runtime logs.

‎docs/features.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,12 @@ Why it matters: prompt stays focused while advanced capabilities remain availabl
4343

4444
Why it matters: local debugging and implementation loops are fast and consistent.
4545

46-
## 6. Telegram Channel Integration
46+
## 6. Message Channel Integration (Telegram + Discord)
4747

4848
- Optional long-polling Telegram adapter.
49+
- Optional Discord bot adapter.
4950
- Per-chat session isolation (`telegram:<chat_id>`).
51+
- Per-channel session isolation (`discord:<channel_id>`).
5052
- Optional sender/chat allowlist for access control.
5153

5254
Why it matters: you can continue lightweight operations from mobile or remote environments.

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,10 @@ Bub is built for day-to-day coding tasks: run commands, edit files, debug failur
2121

2222
- [Key Features](features.md)
2323
- [Interactive CLI](cli.md)
24+
- [Deployment Guide](deployment.md)
2425
- [Architecture](architecture.md)
2526
- [Telegram Integration](telegram.md)
27+
- [Discord Integration](discord.md)
2628

2729
## Common Commands
2830

‎docs/telegram.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ Telegram allows Bub to run as a remote coding assistant entry point for lightwei
77
```bash
88
BUB_TELEGRAM_ENABLED=true
99
BUB_TELEGRAM_TOKEN=123456:token
10-
BUB_TELEGRAM_ALLOW_FROM=["123456789","your_username"]
11-
BUB_TELEGRAM_ALLOW_CHATS=["123456789","-1001234567890"]
10+
BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
11+
BUB_TELEGRAM_ALLOW_CHATS='["123456789","-1001234567890"]'
1212
```
1313

1414
Notes:
@@ -21,7 +21,7 @@ Notes:
2121
## Run
2222

2323
```bash
24-
uv run bub telegram
24+
uv run bub message
2525
```
2626

2727
## Runtime Behavior
@@ -31,10 +31,12 @@ uv run bub telegram
3131
- Inbound text enters the same `AgentLoop` used by CLI.
3232
- Outbound messages are sent by `ChannelManager`.
3333
- Typing indicator is emitted while processing.
34+
- In group chats, Bub only processes messages that mention/reply to the bot.
3435

3536
## Security and Operations
3637

3738
1. Keep bot token only in `.env` or a secret manager.
3839
2. Use a dedicated bot account.
3940
3. Keep allowlist updated with valid user IDs/usernames.
40-
4. If no response is observed, check network, token, then runtime/model logs.
41+
4. If no response is observed, check network, token, allowlists, then runtime/model logs.
42+
5. If `uv run bub message` exits quickly, verify at least one channel is enabled (`BUB_TELEGRAM_ENABLED=true`).

‎env.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,19 @@ LLM_API_KEY=sk-...
5757
# BUB_TELEGRAM_TOKEN=123456:telegram-bot-token
5858
# JSON array recommended:
5959
# BUB_TELEGRAM_ALLOW_FROM='["123456789","my_username"]'
60+
# BUB_TELEGRAM_ALLOW_CHATS='["123456789","-1001234567890"]'
61+
62+
# ---------------------------------------------------------------------------
63+
# Discord channel (optional)
64+
# ---------------------------------------------------------------------------
65+
# BUB_DISCORD_ENABLED=true
66+
# BUB_DISCORD_TOKEN=discord_bot_token
67+
# JSON array recommended:
68+
# BUB_DISCORD_ALLOW_FROM='["123456789012345678","my_discord_name"]'
69+
# BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
70+
# Optional:
71+
# BUB_DISCORD_COMMAND_PREFIX=!
72+
# BUB_DISCORD_PROXY=http://127.0.0.1:7890
6073

6174
# ---------------------------------------------------------------------------
6275
# Example minimal OpenRouter setup

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,11 @@ copyright: Maintained by <a href="https://psiace.me">Chojan Shang</a>.
1010
nav:
1111
- Home: index.md
1212
- Key Features: features.md
13+
- Deployment: deployment.md
1314
- Architecture: architecture.md
1415
- Interactive CLI: cli.md
1516
- Telegram: telegram.md
17+
- Discord: discord.md
1618

1719
plugins:
1820
- search

0 commit comments

Comments
 (0)