docs: Nextcloud Talk bot setup documentation

projects/dttb/nextcloud-talk-bot/README.md

@@ -0,0 +1,94 @@
+# Nextcloud Talk Bot — Максимка
+
+## Обзор
+AI-бот для Nextcloud Talk, который отвечает на сообщения в чате используя Claude через cliproxy (Clawdbot).
+
+## Архитектура
+
+```
+Пользователь → Nextcloud Talk (чат "Максимка")
+                     ↓ (polling API)
+              Talk Bot (Python) ← порт 3401 не используется, polling
+                     ↓
+              cliproxy (localhost:8317) → Claude Sonnet
+                     ↓
+              Ответ → Talk API → Чат
+```
+
+## Компоненты
+
+### 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
+# Запуск бота
+nohup python3 -u /root/clawd/scripts/nextcloud-talk-bot.py > /tmp/talk-bot.log 2>&1 &
+
+# Проверка
+cat /tmp/talk-bot.log | tail -20
+
+# Остановка
+pkill -f nextcloud-talk-bot
+```
+
+## Управление через OCC (внутри контейнера)
+
+```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
+
+# Список чатов
+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"
+
+# Сброс пароля пользователя
+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
+```
+
+## Важные заметки
+
+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