Compare commits
1 Commits
37da564a5f
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 177fd8e1a7 |
216
README.md
216
README.md
@@ -1,28 +1,148 @@
|
|||||||
# WiseClaw
|
# WiseClaw
|
||||||
|
|
||||||
WiseClaw is a local-first personal assistant for macOS. It runs a FastAPI backend, supports either a local LM Studio endpoint or the hosted Z.AI API for LLM access, can augment replies with an AnythingLLM-backed second brain, exposes a Telegram bot, and includes a React admin panel for settings, logs, and memory management.
|
🦉 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.
|
||||||
|
|
||||||
## Planned capabilities
|
## ✨ Neler Yapabiliyor?
|
||||||
|
|
||||||
- Telegram chat with whitelist support
|
- 🤖 Telegram üzerinden konuşma, komut ve araç kullanımı
|
||||||
- Global model provider switch for `Local (LM Studio)` or `Z.AI`
|
- 🧠 `/tanisalim` ile kalıcı kullanıcı profili ve iletişim tercihleri
|
||||||
- Local LM Studio integration for `qwen3-vl-8b-instruct-mlx@5bit`
|
- 🗂️ AnythingLLM tabanlı ikinci beyin sorguları
|
||||||
- Z.AI integration for `glm-4.7` and `glm-5`
|
- 📝 `/notlarima_ekle` ile second brain notu ekleme ve otomatik senkron
|
||||||
- AnythingLLM second-brain context retrieval via workspace chat
|
- ⚙️ `/otomasyon_ekle` ile zamanlanmış görev oluşturma
|
||||||
- Brave or SearXNG-backed web search
|
- 🌐 Brave Search ile web ve görsel arama
|
||||||
- Apple Notes integration via AppleScript
|
- 🧭 `browser_use` ile gerçek tarayıcıda gezinme
|
||||||
- File read/write tools
|
- 🍎 Apple Notes üzerinde not oluşturma
|
||||||
- Terminal execution with policy modes
|
- 📁 Dosya okuma/yazma
|
||||||
- SQLite-backed memory, settings, and audit logs
|
- 🖥️ Politika tabanlı terminal komut çalıştırma
|
||||||
- macOS Keychain for secrets
|
- 🔀 Global model sağlayıcı seçimi:
|
||||||
|
- `Local (LM Studio)`
|
||||||
|
- `Z.AI`
|
||||||
|
- 📊 Admin panelden ayarlar, loglar, memory, profiller ve otomasyonları yönetme
|
||||||
|
|
||||||
## Repository layout
|
## 🏗️ Mimari
|
||||||
|
|
||||||
- `backend/` FastAPI app and WiseClaw core modules
|
- `backend/`
|
||||||
- `frontend/` React admin panel
|
FastAPI uygulaması, orchestrator, tool'lar, Telegram botu ve scheduler
|
||||||
- `docs/` architecture and rollout notes
|
- `frontend/`
|
||||||
|
React tabanlı admin panel
|
||||||
|
- `docs/`
|
||||||
|
Mimari notlar ve brainstorm kayıtları
|
||||||
|
|
||||||
## Local development
|
## 🧩 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
|
||||||
|
- `files`
|
||||||
|
Dosya/dizin erişimi
|
||||||
|
- `terminal`
|
||||||
|
Güvenlik politikasıyla komut çalıştırma
|
||||||
|
- `second_brain`
|
||||||
|
AnythingLLM workspace context sorgulama
|
||||||
|
|
||||||
|
## 🧠 İ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`
|
||||||
|
|
||||||
|
## ⏱️ 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
|
||||||
|
- Brave / Z.AI / AnythingLLM secret'ları
|
||||||
|
- 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`
|
||||||
|
|
||||||
|
## 🚀 Kurulum
|
||||||
|
|
||||||
### Backend
|
### Backend
|
||||||
|
|
||||||
@@ -42,15 +162,29 @@ npm install
|
|||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
### Smoke checks
|
## 🔐 Ortam Değişkenleri
|
||||||
|
|
||||||
```bash
|
[.env.example](/Users/wisecolt-macmini/Project/wiseclaw/.env.example) dosyasını `.env` olarak kopyalayabilirsin.
|
||||||
cd backend
|
|
||||||
source .venv312/bin/activate
|
|
||||||
uvicorn app.main:app --reload
|
|
||||||
```
|
|
||||||
|
|
||||||
Then in another shell:
|
Ö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_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
|
```bash
|
||||||
curl http://127.0.0.1:8000/health
|
curl http://127.0.0.1:8000/health
|
||||||
@@ -59,6 +193,34 @@ 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/telegram
|
||||||
```
|
```
|
||||||
|
|
||||||
## Environment bootstrap
|
## 🔁 Restart
|
||||||
|
|
||||||
Copy `.env.example` to `.env` and fill in only the values you need for the first boot. Secrets such as `WISECLAW_ZAI_API_KEY` and `WISECLAW_ANYTHINGLLM_API_KEY` can also be saved later from the admin panel.
|
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.
|
||||||
|
|
||||||
|
## 🧭 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
|
||||||
|
|||||||
Reference in New Issue
Block a user