319 lines
8.4 KiB
Markdown
319 lines
8.4 KiB
Markdown
# WiseClaw
|
||
|
||
🦉 WiseClaw, macOS üzerinde çalışan yerel-öncelikli bir kişisel asistan altyapısıdır. FastAPI backend, Telegram botu, React admin paneli, çoklu LLM sağlayıcı desteği, tarayıcı otomasyonu, araç çağırma, otomasyonlar ve AnythingLLM tabanlı "ikinci beyin" entegrasyonunu aynı projede bir araya getirir.
|
||
|
||
## ✨ Neler Yapabiliyor?
|
||
|
||
- 🤖 Telegram üzerinden konuşma, komut ve araç kullanımı
|
||
- 🧠 `/tanisalim` ile kalıcı kullanıcı profili ve iletişim tercihleri
|
||
- 🗂️ AnythingLLM tabanlı ikinci beyin sorguları
|
||
- 📝 `/notlarima_ekle` ile second brain notu ekleme ve otomatik senkron
|
||
- 📬 Google OAuth ile Gmail bağlantısı kurup gelen mailleri listeleme, arama ve özetleme
|
||
- ☁️ Google Drive dosyalarını listeleme, arama ve Telegram'dan gelen dosyaları Drive root'a yükleme
|
||
- ⚙️ `/otomasyon_ekle` ile zamanlanmış görev oluşturma
|
||
- 🌐 Brave Search ile web ve görsel arama
|
||
- 🧭 `browser_use` ile gerçek tarayıcıda gezinme
|
||
- 🍎 Apple Notes üzerinde not oluşturma
|
||
- 📁 Dosya okuma/yazma
|
||
- 🖥️ Politika tabanlı terminal komut çalıştırma
|
||
- 🔀 Global model sağlayıcı seçimi:
|
||
- `Local (LM Studio)`
|
||
- `Z.AI`
|
||
- 📊 Admin panelden ayarlar, loglar, memory, profiller ve otomasyonları yönetme
|
||
- 🔗 Admin panelden Google OAuth, AnythingLLM ve LLM bağlantı durumlarını canlı izleme
|
||
|
||
## 🏗️ Mimari
|
||
|
||
- `backend/`
|
||
FastAPI uygulaması, orchestrator, tool'lar, Telegram botu ve scheduler
|
||
- `frontend/`
|
||
React tabanlı admin panel
|
||
- `docs/`
|
||
Mimari notlar ve brainstorm kayıtları
|
||
|
||
## 🧩 LLM Sağlayıcıları
|
||
|
||
WiseClaw tek bir global sağlayıcı ile çalışır:
|
||
|
||
- 🏠 `Local (LM Studio)`
|
||
Yerel OpenAI-uyumlu endpoint üzerinden çalışır
|
||
- ☁️ `Z.AI`
|
||
Anthropic-uyumlu API üzerinden `glm-4.7` ve `glm-5` modellerini kullanır
|
||
|
||
Admin panelden aktif sağlayıcı değiştirildiğinde yeni istekler seçili sağlayıcıya gider.
|
||
|
||
## 🛠️ Başlıca Tool'lar
|
||
|
||
- `brave_search`
|
||
Web ve image search
|
||
- `web_fetch`
|
||
Tekil URL çekme ve içerik okuma
|
||
- `browser_use`
|
||
Gerçek browser otomasyonu
|
||
- `apple_notes`
|
||
Apple Notes not oluşturma
|
||
- `gmail`
|
||
Gmail mesajlarını listeleme ve arama
|
||
- `google_drive`
|
||
Google Drive dosyalarını listeleme, arama ve yükleme
|
||
- `files`
|
||
Dosya/dizin erişimi
|
||
- `terminal`
|
||
Güvenlik politikasıyla komut çalıştırma
|
||
- `second_brain`
|
||
AnythingLLM workspace context sorgulama
|
||
|
||
## 📬 Google Entegrasyonları
|
||
|
||
WiseClaw artık Google OAuth üzerinden tek bir Google hesabına bağlanabilir.
|
||
|
||
### Admin'den Bağlama
|
||
|
||
Admin panelde yeni `Google OAuth` kartı bulunur:
|
||
|
||
- `Google OAuth client ID`
|
||
- `Google OAuth client secret`
|
||
- `Connect Google` / `Reconnect Google`
|
||
|
||
Bu bilgiler kaydedildiğinde WiseClaw otomatik olarak şu dosyayı üretir:
|
||
|
||
- [backend/.google/client_secret.json](/Users/wisecolt-macmini/Project/wiseclaw/backend/.google/client_secret.json)
|
||
|
||
Başarılı bağlantıdan sonra token burada tutulur:
|
||
|
||
- [backend/.google/token.json](/Users/wisecolt-macmini/Project/wiseclaw/backend/.google/token.json)
|
||
|
||
### Gmail
|
||
|
||
Desteklenen ilk sürüm işlemleri:
|
||
|
||
- gelen kutusundaki son mailleri listeleme
|
||
- Gmail arama sorgusuyla filtreleme
|
||
- kısa özet üretme
|
||
|
||
Örnek komutlar:
|
||
|
||
```text
|
||
Gmail'de gelen ilk 10 maili özetle
|
||
Son 5 maili listele
|
||
OpenAI geçen mailleri bul
|
||
```
|
||
|
||
### Google Drive
|
||
|
||
Desteklenen ilk sürüm işlemleri:
|
||
|
||
- Drive'daki dosyaları listeleme
|
||
- dosya adıyla arama
|
||
- Telegram'dan gelen dosyayı Drive root'a yükleme
|
||
|
||
Örnek komutlar:
|
||
|
||
```text
|
||
Drive'da invoice geçen dosyaları ara
|
||
Google Drive'daki son 10 dosyayı listele
|
||
```
|
||
|
||
Telegram upload akışı:
|
||
|
||
1. Telegram'da bir `document` veya `photo` gönder
|
||
2. O mesaja reply yap
|
||
3. Şunu yaz:
|
||
|
||
```text
|
||
Bunu Google Drive'a yukle
|
||
```
|
||
|
||
WiseClaw dosyayı geçici alana indirir, Drive root'a yükler ve sana:
|
||
|
||
- dosya adı
|
||
- Drive linki
|
||
- dosya ID'si
|
||
|
||
döner.
|
||
|
||
## 🧠 İkinci Beyin Akışı
|
||
|
||
WiseClaw, AnythingLLM'yi ikinci beyin olarak kullanabilir.
|
||
|
||
### Sorgulama
|
||
|
||
Telegram'da örnek:
|
||
|
||
```text
|
||
Notlara bak, serkan ile ne zaman ve nerde buluştum?
|
||
```
|
||
|
||
WiseClaw bu isteği `second_brain` tool'una yönlendirir, AnythingLLM workspace'inden bağlam çeker ve kısa cevap üretir.
|
||
|
||
### Not Ekleme
|
||
|
||
Telegram akışı:
|
||
|
||
```text
|
||
/notlarima_ekle
|
||
```
|
||
|
||
Ardından gönderilen not:
|
||
|
||
1. SQLite veritabanına `second_brain` kaydı olarak yazılır
|
||
2. [backend/second_brain.md](/Users/wisecolt-macmini/Project/wiseclaw/backend/second_brain.md) dosyası yeniden üretilir
|
||
3. Eski `second_brain.md` AnythingLLM workspace'inden kaldırılır
|
||
4. Yeni dosya tekrar upload edilip workspace'e bağlanır
|
||
|
||
Bu yaklaşım belge tabanlı RAG akışına daha uygun olduğu için doğrudan DB -> AnythingLLM yazmaktan daha sağlamdır.
|
||
|
||
## 💬 Telegram Komutları
|
||
|
||
- `/start`
|
||
- `/tanisalim`
|
||
- `/profilim`
|
||
- `/tercihlerim`
|
||
- `/tanisalim_sifirla`
|
||
- `/otomasyon_ekle`
|
||
- `/otomasyonlar`
|
||
- `/otomasyon_durdur <id>`
|
||
- `/otomasyon_baslat <id>`
|
||
- `/otomasyon_sil <id>`
|
||
- `/notlarima_ekle`
|
||
- `/clean_chat`
|
||
|
||
`/clean_chat` yalnızca Telegram konuşma ekranını temizlemeye çalışır; veritabanındaki memory, audit log, profil veya second brain kayıtlarını silmez.
|
||
|
||
## ⏱️ Otomasyonlar
|
||
|
||
WiseClaw backend içinde çalışan scheduler ile zamanlanmış görevleri destekler.
|
||
|
||
Desteklenen ilk sürüm sıklıkları:
|
||
|
||
- günlük
|
||
- hafta içi
|
||
- haftalık
|
||
- saatlik
|
||
|
||
Otomasyon sonuçları:
|
||
|
||
- Telegram'a gönderilir
|
||
- audit log'a yazılır
|
||
|
||
## 🧪 Admin Panel
|
||
|
||
Admin panelde şunları yönetebilirsin:
|
||
|
||
- Runtime settings
|
||
- Model provider
|
||
- Search provider
|
||
- AnythingLLM canlı durum kartı (`Active / Off`)
|
||
- Google auth durumu (`Connected / Not connected`)
|
||
- Brave / Z.AI / AnythingLLM secret'ları
|
||
- Google OAuth client bilgileri
|
||
- Telegram whitelist
|
||
- User Profiles
|
||
- Automations
|
||
- Memory
|
||
- Recent Logs
|
||
|
||
Önemli endpointler:
|
||
|
||
- `/admin/dashboard`
|
||
- `/admin/settings`
|
||
- `/admin/users`
|
||
- `/admin/profiles`
|
||
- `/admin/automations`
|
||
- `/admin/memory`
|
||
- `/admin/integrations/llm`
|
||
- `/admin/integrations/telegram`
|
||
- `/admin/integrations/anythingllm`
|
||
- `/admin/integrations/google`
|
||
|
||
## 🚀 Kurulum
|
||
|
||
### Backend
|
||
|
||
```bash
|
||
cd backend
|
||
python3.12 -m venv .venv312
|
||
source .venv312/bin/activate
|
||
pip install .
|
||
uvicorn app.main:app --reload
|
||
```
|
||
|
||
### Frontend
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 🔐 Ortam Değişkenleri
|
||
|
||
[.env.example](/Users/wisecolt-macmini/Project/wiseclaw/.env.example) dosyasını `.env` olarak kopyalayabilirsin.
|
||
|
||
Öne çıkan alanlar:
|
||
|
||
- `WISECLAW_MODEL_PROVIDER`
|
||
- `WISECLAW_LOCAL_BASE_URL`
|
||
- `WISECLAW_LOCAL_MODEL`
|
||
- `WISECLAW_ZAI_BASE_URL`
|
||
- `WISECLAW_ZAI_MODEL`
|
||
- `WISECLAW_ANYTHINGLLM_BASE_URL`
|
||
- `WISECLAW_ANYTHINGLLM_WORKSPACE_SLUG`
|
||
- `WISECLAW_GOOGLE_CLIENT_SECRETS_FILE`
|
||
- `WISECLAW_GOOGLE_TOKEN_FILE`
|
||
- `WISECLAW_GOOGLE_CLIENT_ID`
|
||
- `WISECLAW_GOOGLE_CLIENT_SECRET`
|
||
- `WISECLAW_TELEGRAM_BOT_TOKEN`
|
||
- `WISECLAW_BRAVE_API_KEY`
|
||
- `WISECLAW_ZAI_API_KEY`
|
||
- `WISECLAW_ANYTHINGLLM_API_KEY`
|
||
|
||
Not: secret'lar admin panelden daha sonra da kaydedilebilir.
|
||
|
||
## ✅ Hızlı Kontrol
|
||
|
||
Backend ayağa kalktıktan sonra:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/health
|
||
curl http://127.0.0.1:8000/bootstrap
|
||
curl http://127.0.0.1:8000/admin/integrations/llm
|
||
curl http://127.0.0.1:8000/admin/integrations/telegram
|
||
curl http://127.0.0.1:8000/admin/integrations/anythingllm
|
||
curl http://127.0.0.1:8000/admin/integrations/google
|
||
```
|
||
|
||
## 🔁 Restart
|
||
|
||
Projede tek komutluk restart script'i var:
|
||
|
||
```bash
|
||
cd /Users/wisecolt-macmini/Project/wiseclaw
|
||
zsh ./restart.sh
|
||
```
|
||
|
||
Bu script:
|
||
|
||
- eski backend sürecini kapatır
|
||
- yeni `uvicorn` sürecini başlatır
|
||
- log'u `.wiseclaw/logs/backend.log` içine yazar
|
||
- health check ile ayağa kalktığını doğrular
|
||
|
||
## 📌 Notlar
|
||
|
||
- `LM Studio status: Reachable` görünüp `model is not installed` uyarısı alıyorsan, endpoint açık ama seçili model adı yüklü modellerle birebir eşleşmiyor demektir.
|
||
- AnythingLLM tarafında görünen workspace adı ile gerçek `slug` farklı olabilir.
|
||
- Brave image search sonuçları Telegram'da medya grubu olarak gönderilebilir.
|
||
- Bazı browser görevleri captcha/anti-bot nedeniyle manuel müdahale isteyebilir.
|
||
- Google Drive upload için OAuth yetkileri değiştiyse Google hesabını yeniden bağlamak gerekebilir.
|
||
- `/clean_chat` Telegram ekranını temizler ama SQLite kayıtlarını silmez.
|
||
|
||
## 🧭 Geliştirme Notu
|
||
|
||
Bu repo hızlı iterasyonla büyüdüğü için bazı alanlarda bilinçli teknik borçlar bulunur. Ana yön şu anda şudur:
|
||
|
||
- daha sağlam tool routing
|
||
- daha iyi approval akışları
|
||
- second brain retrieval kalitesini artırma
|
||
- admin panel kullanılabilirliğini geliştirme
|