oleg/knowledge-base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: полный гайд по настройке Talk бота + исходник скрипта

Browse Source
This commit is contained in:
Максимка
2026-02-27 00:44:39 +03:00
parent f846ed326a
commit 7d07a62d5c
2 changed files with 476 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
projects/dttb/nextcloud-talk-bot/README.md
View File

@@ -1,94 +1,246 @@
# Nextcloud Talk Bot — Максимка
# Nextcloud Talk Bot — Максимка 🤖
## Обзор
AI-бот для Nextcloud Talk, который отвечает на сообщения в чате используя Claude через cliproxy (Clawdbot).
AI-бот в Nextcloud Talk с доступом к базе знаний. Отвечает на вопросы об инфраструктуре, серверах, настройках и проектах. Использует Claude через cliproxy (Clawdbot).
## Архитектура
```
Пользователь → Nextcloud Talk (чат "Максимка")
↓ (polling API)
Talk Bot (Python) ← порт 3401 не используется, polling
↓ (long polling API каждые 30с)
Talk Bot (Python скрипт на LXC 129)
↓
cliproxy (localhost:8317) → Claude Sonnet
↑
База знаний из Gitea (knowledge-base repo)
↓
Ответ → Talk API → Чат
Ответ → Talk API → Чат (от пользователя "maximka")
```
## Компоненты
### 1. Nextcloud Talk Bot (зарегистрированный)
- **Bot ID:** 2
- **Name:** Максимка
- **Secret:** `maximka-talk-bot-secret-key-2026-very-long-40chars`
- **Webhook URL:** `http://10.0.0.206:3401/nextcloud-talk/webhook`
- **Features:** webhook, response, event
- **Статус:** Webhook не работает (Docker networking), используем polling
### 2. Python Polling Bot
- **Скрипт:** `/root/clawd/scripts/nextcloud-talk-bot.py`
- **Метод:** Long polling через Talk API (`lookIntoFuture=1`)
- **AI:** Claude Sonnet через cliproxy на localhost:8317
- **Лог:** `/tmp/talk-bot.log`
### 3. Nextcloud пользователи
- **admin** (1qaz!QAZ) — для чтения сообщений (polling)
- **maximka** (MaximkaBot2026) — для отправки ответов
## Чат
- **Имя:** Максимка
- **Token:** `aecax6yg`
- **Участники:** admin, maximka
## Nextcloud
- **URL:** http://10.0.0.230:11001
- **Тип:** Nextcloud AIO (Docker)
- **VM:** 10.0.0.230 (cloud@10.0.0.230)
## Запуск
## Быстрый старт
### Запуск бота
```bash
# Запуск бота
# На LXC 129 (clawdbot, 10.0.0.206)
nohup python3 -u /root/clawd/scripts/nextcloud-talk-bot.py > /tmp/talk-bot.log 2>&1 &
```
# Проверка
### Проверка
```bash
cat /tmp/talk-bot.log | tail -20
pgrep -f nextcloud-talk-bot
```
# Остановка
### Остановка
```bash
pkill -f nextcloud-talk-bot
```
## Управление через OCC (внутри контейнера)
### Обновить базу знаний (из чата Talk)
Написать `/reload` в чат — бот сделает git pull и перезагрузит KB.
---
## Установка с нуля
### Предварительные требования
- Nextcloud с приложением Talk (протестировано на Nextcloud AIO)
- Python 3.x на машине где будет бот
- Clawdbot с cliproxy (для Claude API)
- Git репозиторий с базой знаний
### Шаг 1: Создать пользователя для бота в Nextcloud
```bash
# На VM с Nextcloud (10.0.0.230)
# Через OCC в Docker контейнере
sudo docker exec -i -e OC_PASS='MaximkaBot2026' -u www-data \
nextcloud-aio-nextcloud php occ user:add \
--password-from-env \
--display-name="Максимка 🤖" \
maximka
# Если пользователь уже есть — сбросить пароль:
sudo docker exec -i -e OC_PASS='MaximkaBot2026' -u www-data \
nextcloud-aio-nextcloud php occ user:resetpassword --password-from-env maximka
```
### Шаг 2: Создать чат в Nextcloud Talk
Через веб-интерфейс Nextcloud Talk:
1. Нажать "+" → Создать групповую беседу
2. Назвать "Максимка" (или любое имя)
3. Добавить участников: admin, maximka, и других пользователей
Через API:
```bash
# Создать групповой чат
curl -s -u "admin:1qaz!QAZ" \
-X POST "http://10.0.0.230:11001/ocs/v2.php/apps/spreed/api/v4/room" \
-H "OCS-APIRequest: true" \
-d "roomType=2&roomName=Максимка"
# Добавить бота в чат
curl -s -u "admin:1qaz!QAZ" \
-X POST "http://10.0.0.230:11001/ocs/v2.php/apps/spreed/api/v4/room/{TOKEN}/participants" \
-H "OCS-APIRequest: true" \
-d "newParticipant=maximka&source=users"
```
Где `{TOKEN}` — токен чата из предыдущего ответа (у нас: `aecax6yg`).
### Шаг 3: Получить токен чата
```bash
# Список всех чатов
curl -s -u "admin:1qaz!QAZ" \
"http://10.0.0.230:11001/ocs/v2.php/apps/spreed/api/v4/room" \
-H "OCS-APIRequest: true" \
-H "Accept: application/json" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for r in data['ocs']['data']:
print(f\"Token: {r['token']} | Name: {r.get('displayName','')} | Type: {r['type']}\")
"
```
### Шаг 4: Скопировать скрипт бота
Скрипт: `/root/clawd/scripts/nextcloud-talk-bot.py`
Отредактировать конфигурацию в начале файла:
```python
NC_URL = "http://10.0.0.230:11001" # URL Nextcloud
NC_USER = "admin" # Пользователь для чтения (polling)
NC_PASS = "1qaz!QAZ" # Пароль
BOT_USER = "maximka" # Пользователь для отправки ответов
BOT_PASS = "MaximkaBot2026" # Пароль бота
CONVERSATION_TOKEN = "aecax6yg" # Токен чата
CLIPROXY_URL = "http://localhost:8317/v1/messages" # Claude API
CLIPROXY_KEY = "sk-clawdbot-proxy" # API ключ
KB_PATH = "/root/clawd/knowledge-base" # Путь к базе знаний
MAX_KB_SIZE = 80000 # Макс размер KB в промпте
```
### Шаг 5: Запустить бота
```bash
nohup python3 -u /root/clawd/scripts/nextcloud-talk-bot.py > /tmp/talk-bot.log 2>&1 &
```
---
## Конфигурация
### Учётные данные
| Что | Логин | Пароль | Назначение |
|-----|-------|--------|-----------|
| NC Polling | admin | 1qaz!QAZ | Чтение сообщений |
| NC Bot | maximka | MaximkaBot2026 | Отправка ответов |
| cliproxy | - | sk-clawdbot-proxy | Claude API |
### Nextcloud
- **URL:** http://10.0.0.230:11001
- **Тип:** Nextcloud AIO (Docker)
- **VM:** 250 на Proxmox (10.0.0.230)
- **SSH:** cloud@10.0.0.230
### Чат
- **Имя:** Максимка
- **Token:** aecax6yg
- **Участники:** admin, maximka
### Файлы
- **Скрипт:** `/root/clawd/scripts/nextcloud-talk-bot.py`
- **Лог:** `/tmp/talk-bot.log`
- **База знаний:** `/root/clawd/knowledge-base/`
- **Gitea repo:** http://10.0.0.189:3000/oleg/knowledge-base
---
## Как работает
### Polling
Бот использует Talk API с long polling (`lookIntoFuture=1&timeout=30`). Nextcloud держит HTTP соединение открытым до 30 секунд и отвечает сразу когда появляется новое сообщение.
### Join Room
Перед каждой отправкой бот делает `POST .../room/{token}/participants/active` — это "join" в разговор. Без этого Nextcloud возвращает 401.
### База знаний
При старте бот:
1. Делает `git pull` в `/root/clawd/knowledge-base`
2. Загружает все `.md` файлы (до 80KB)
3. Передаёт как первое user/assistant сообщение в контекст Claude
**Важно:** KB передаётся через user message, а не system prompt — cliproxy не передаёт system field.
### Фильтрация
Бот пропускает:
- Свои сообщения (`actorId == "maximka"`)
- Сообщения от ботов (`actorType == "bots"`)
- Системные (`messageType == "system"`)
### Команды
- `/reload` — обновить базу знаний (git pull + перезагрузка)
### История
Бот помнит последние 10 пар сообщений (user/assistant) в текущей сессии. При перезапуске история сбрасывается.
---
## Проблемы и решения
### Webhook не работает
Nextcloud Talk Bot API поддерживает webhooks, но в AIO (Docker) setup они не триггерятся надёжно. Решение: polling.
### 401 при отправке
Причина: бот не "вошёл" в чат. Решение: `join_room()` перед каждой отправкой.
### Бот зацикливается
Причина: бот отвечает на свои же сообщения. Решение: фильтр по `actorId`.
### Бот не использует базу знаний
Причина: cliproxy не передаёт system prompt. Решение: KB как первое user/assistant сообщение.
### Бот не запускается после перезагрузки
Нужен systemd сервис (TODO).
---
## OCC команды (управление Talk ботами)
```bash
# SSH на VM
ssh cloud@10.0.0.230
# Список ботов
echo '1qaz!QAZ' | sudo -S docker exec -u www-data nextcloud-aio-nextcloud php occ talk:bot:list aecax6yg
# Все команды через docker
EXEC="sudo docker exec -u www-data nextcloud-aio-nextcloud"
# Список чатов
curl -s -u "admin:1qaz!QAZ" "http://10.0.0.230:11001/ocs/v2.php/apps/spreed/api/v4/room" -H "OCS-APIRequest: true" -H "Accept: application/json"
# Установить бота (webhook-based, необязательно для polling)
$EXEC php occ talk:bot:install \
-f webhook -f response -f event \
'Максимка' 'secret-key' 'http://webhook-url/endpoint' 'Описание'
# Сброс пароля пользователя
echo '1qaz!QAZ' | sudo -S docker exec -i -e OC_PASS='NewPassword' -u www-data nextcloud-aio-nextcloud php occ user:resetpassword --password-from-env maximka
# Список ботов в чате
$EXEC php occ talk:bot:list {TOKEN}
# Добавить бота в чат
$EXEC php occ talk:bot:setup {BOT_ID} {CHAT_TOKEN}
# Удалить бота из чата
$EXEC php occ talk:bot:remove {BOT_ID} {CHAT_TOKEN}
# Удалить бота полностью
$EXEC php occ talk:bot:uninstall {BOT_ID}
```
## Важные заметки
1. **Webhook не работает** — Nextcloud Talk webhook для ботов требует background jobs и работает ненадёжно в AIO setup. Поэтому используем polling.
2. **Join room обязательно** — перед отправкой сообщения от maximka нужно вызвать `POST .../room/{token}/participants/active` (join), иначе 401.
3. **Фильтрация** — бот пропускает:
- Свои сообщения (actorId == "maximka")
- Сообщения от других ботов (actorType == "bots")
- Системные сообщения (messageType == "system")
4. **Long polling** — Talk API поддерживает `lookIntoFuture=1&timeout=30` для эффективного ожидания новых сообщений.
---
## TODO
- [ ] Systemd сервис для автозапуска
- [ ] История контекста (несколько последних сообщений)
- [ ] Поддержка нескольких чатов
- [ ] Аватар для пользователя maximka
- [ ] Интеграция с основным Clawdbot (через hooks или sessions)
- [ ] Возможность выполнять команды (не только отвечать)