beast-agent 1.7.0 → 1.9.0

package/src/agent/seeds/writing-skills/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: writing-skills
+description: Yeni skill oluştururken, mevcut skill düzenlerken veya deploy öncesi doğrularken kullan — %APPDATA%\beast\skills altına SKILL.md yazılacak/herhangi bir edit olacaksa.
+---
+
+# Skill Yazma
+
+## Genel Bakış
+
+**Skill yazmak, süreç dokümantasyonuna uygulanan TDD'dir.**
+
+Test senaryoları yaz (paralel ajanla baskı senaryosu), fail izle (baseline
+davranış), skill'i yaz (doküman), geçiş izle (ajan artık uyuyor), refactor
+(loophole kapat).
+
+**Çekirdek ilke:** Skill'siz ajanın fail ettiğini izlemediysen, skill'in
+doğru şeyi öğrettiğini bilmezsin.
+
+**ZORUNLU TEMEL:** test-driven-development skill'ini anlıyor olmalısın —
+o RED-GREEN-REFACTOR'ü tanımlar, bu skill onu dokümana uyarlar.
+
+## Skill Nedir?
+
+**Skill:** Kanıtlanmış teknik, desen veya araç için referans rehber.
+**Skill'dir:** Yeniden kullanılabilir teknik/pattern/araç/rehber.
+**Skill değildir:** Bir problemi bir kez nasıl çözdüğüne dair hikâye.
+
+## Ne Zaman Skill Yaratılır
+
+**Yarat:**
+- Teknik sana sezgisel gelmediyse
+- Projeler arası tekrar referans edeceksen
+- Desen genelse (proje-özel değilse)
+
+**Yaratma:**
+- Tek seferlik çözümler için
+- Başka yerde iyi dokümante edilmiş standart pratikler için
+- Proje-özel konvansiyonlar (onlar AGENTS.md'ye/proje talimatına)
+- Regex/validasyonla zorlanabilir mekanik kısıtlar (otomatikleştir —
+  dokümanı yargı gerektiren kararlara sakla)
+
+## Beast'te Skill Yapısı
+
+Yer: `%APPDATA%\beast\skills\<slug>\SKILL.md` (write_file ile yaz; slug
+küçük-harf-tire). Isim+açıklama HER SOHBETE system prompta girer — gövde
+sadece ilgiliyken read_file ile okunur.
+
+```markdown
+---
+name: skill-adi
+description: [TETİKLEYİCİ — ne zaman okunmalı; aşağıya bak]
+version: 1.0.0
+---
+
+# Skill Adı
+
+## Genel Bakış
+Bu ne? Çekirdek ilke 1-2 cümle.
+
+## Ne Zaman
+Belirtiler ve kullanım durumları; ne zaman KULLANILMAZ
+
+## Çekirdek Desen
+Önce/sonra karşılaştırması veya adımlar
+
+## Hızlı Referans
+Sık işlemler için tablo
+
+## Yaygın Hatalar
+Ne yanlış gider + fix
+```
+
+**Frontmatter kuralları:**
+- `name`: harf, rakam, tire (özel karakter yok)
+- `description`: üçüncü şahıs, SADECE ne zaman kullanılacağını anlatır
+
+## Skill Keşif Optimizasyonu (SDO)
+
+**description = NE ZAMAN, ne YAPDIĞI değil.**
+
+Test şunu gösterdi: description workflow'u özetlerse ajan TÜM skill'i
+okumadan description'daki kısayolu uygular. Gövde, ajanın atladığı
+dokümana döner.
+
+```yaml
+# ❌ KÖTÜ: workflow özetler — ajan gövdeyi okumadan bunu takip eder
+description: Plan yürütürken kullan — görev başına alt-ajan devreder, aralarında inceleme yapar
+
+# ✅ İYİ: sadece tetikleyici koşullar
+description: Bağımsız görevlere bölünmüş implementasyon planı yürütülürken kullan
+```
+
+- Somut tetikleyiciler, belirtiler ve durumlar yaz
+- Sorunu tarif et (race condition, tutarsız davranış), dile özgü belirtiyi değil
+- Arama kelimeleri kullan: hata mesajları, belirtiler ("flaky", "takılıyor"),
+  araç adları
+- Üçüncü şahıs yaz (system prompta enjekte edilir)
+
+## Demir Kanun (TDD ile aynı)
+
+```
+FAILING TEST OLMADAN SKILL YOK
+```
+
+Bu YENİ skill'ler VE mevcut skill EDİTLERİ için geçerli. Test etmeden
+skill yazdıysan: sil, baştan başla. "Basit ekleme" istisnası yok.
+
+## RED-GREEN-REFACTOR (skill için)
+
+### RED: Başarısız Test (Baseline)
+
+Skill'siz ajanla baskı senaryosu çalıştır (run_background ile taze ajan —
+sistem promptu skill'in yaşayacağı gerçek bağlam, kullanıcı mesajı hataya
+çekecek görev olsun). Birebir belgele:
+- Hangi seçimleri yaptı?
+- Hangi bahaneleri kullandı (verbatim)?
+- Hangi baskılar ihlale yol açtı?
+
+### GREEN: Minimal Skill Yaz
+
+Baseline'da belgelenen SPESİFİK bahaneleri karşılayan skill yaz. Hayali
+durumlar için ekstra içerik EKLEME. Aynı senaryoyu skill ile tekrar koştur —
+ajan artık uymalı.
+
+### REFACTOR: Loophole Kapat
+
+Ajan YENİ bahane buldu? Açık karşı-argüman ekle. Bulletproof olana kadar
+tekrar test et.
+
+**Mikro-test:** tam senaryo pahalıysa önce kelimelik test — tek taze örnek +
+rehberli vs kontrolsüz (rehbersiz) karşılaştırma, 5+ tekrar, her eşleşmeyi
+elle oku. Kontrol grupta hata YOKSA yazılacak rehber de yok — dur.
+
+## Uyum Sağlamayı Ezberle (Disiplin Skill'leri)
+
+Kural bilen ajan baskı altında atlarsa:
+
+**Her loophole'u açıkça kapat** — kuralı söylemek yetmez, workaround'ları
+tek tek yasakla:
+
+```markdown
+Testten önce kod yazdıysan: SİL. Baştan başla.
+
+**İstisna yok:**
+- "Referans olarak" tutma
+- Testleri yazarken uyarlama
+- Silmek silmektir
+```
+
+**"Ruh vs harf" argümanını baştan kes:**
+
+```markdown
+**Kuralın harfini ihlal etmek, kuralın ruhunu ihlal etmektir.**
+```
+
+**Bahane tablosu kur** — baseline testten çıkan HER bahane:
+
+```markdown
+| Bahane | Gerçek |
+|---|---|
+| "Test etmek için çok basit" | Basit kod da kırılır. Test 30 saniye. |
+```
+
+**Kırmızı bayrak listesi** — ajanın kendini kontrolü kolay olsun:
+
+```markdown
+## Kırmızı Bayraklar — DUR
+- "Sadece bu sefer" bahanesi
+- "Elle test ettim zaten"
+
+**Hepsi: kodu sil, TDD ile baştan başla.**
+```
+
+## Kalıbı Hatanın Türüne Eşle
+
+| Baseline hatası | Doğru kalıp | Yanlış kalıp |
+|---|---|---|
+| Baskı altında kuralı atlıyor | Yasak + bahane tablosu + kırmızı bayraklar | Yumuşak yönlendirme ("tercih et", "düşün") |
+| Uyuyor ama çıktı yanlış biçimde | Pozitif reçete: çıktı NE — parçaları ve sırasıyla | Yasak listesi |
+| Zaten ürettiği şeyden eleman eksitiyor | Şablon REQUIRED alanı | Şablon yanına prose hatırlatma |
+| Davranış koşula bağlı olmalı | Gözlenebilir koşullu ("brief varsa ona atıf yap") | Koşulsuz kural + istisna cümleleri |
+
+Yasaklar, şekillendirme sorunlarında TERS TEPER — "X yapma" pazarlığa
+açık kalır; reçete pazarlık bırakmaz: çıktı ya söylenen kalıptadır ya değil.
+
+**Seçtiğin kalıp için:** nüans cümlesi YOK ("X yapma, önemliyse hariç"
+pazarlığı yeniden açar).
+
+## Token Verimliliği (Kritik)
+
+Skill gövdesi okunduğunda bağlama girer:
+
+- Sık yüklenen skill'ler: <200 kelime hedef
+- Diğerleri: <500 kelime (yine de öz ol)
+- Detayları araç yardımına bırak; cross-referans kullan ("ZORUNLU:
+  test-driven-development skill'ini kullan" — içerik tekrarı yok)
+- Tek mükemmel örnek, çok vasat örnekten iyi
+- Yeniden kullanılabilir ağır referans (100+ satır) ayrı dosyaya
+  (`SKILL.md` yanına `referans.md`), inline ilkeler/prensipler kalır
+
+## Anti-Desenler
+
+- ❌ **Hikâye anlatımı:** "2025-10-03 oturumunda empty projectDir yüzünden..."
+  — çok spesifik, yeniden kullanılamaz
+- ❌ **Çok-dil sulandırma:** example-js.js + example-py.py + example-go.go
+- ❌ **Anlamsız etiketler:** helper1, step3, pattern4
+
+## Test Türüne Göre
+
+| Skill türü | Test yöntemi | Başarı kriteri |
+|---|---|---|
+| Disiplin (kural dayatır: TDD, verification) | Baskı senaryosu: zaman+sunk cost+baskı birleşik; bahaneleri yakala | Maksimum baskıda kurala uyar |
+| Teknik (nasıl-yapılır) | Uygulama + varyasyon + eksik bilgi senaryoları | Tekniği yeni senaryoya doğru uygular |
+| Desen (zihinsel model) | Tanıma + uygulama + karşı-örnek | Ne zaman uygulanacağını doğru bulur |
+| Referans (API/komut dokümanı) | Erişim + uygulama + boşluk testi | Doğru bilgiyi bulur ve uygular |
+
+## Deploy Etmeden ÖNCE
+
+Her skill için (toplu üretimde her biri AYRI test edilmeden sonrakine geçme):
+
+- [ ] Baseline (skill'siz) davranış birebir belgelendi
+- [ ] description "ne zaman" tarzında, workflow özetlemiyor
+- [ ] name kurallara uygun, dosya `%APPDATA%\beast\skills\<slug>\SKILL.md`
+- [ ] Skill ile senaryo artık geçiyor
+- [ ] Yeni bahaneler bulunduysa karşıları eklendi, tekrar test edildi
+- [ ] Bahane tablosu + kırmızı bayraklar var (disiplin skill'i ise)
+- [ ] `/skills` listesinde görünüyor, okunabilirlik kontrol edildi
+
+Deploy edilmemiş skill = deploy edilmemiş kod. Test et, sonra konuşlandır.

package/src/agent/skills.js

@@ -102,7 +102,7 @@ Get-Content "$env:APPDATA\\beast\\sessions\\bg-jobs.json" | ConvertFrom-Json | %
 | Yol | Ne İşe Yarar |
 |---|---|
 | \`config.yaml\` + \`.env\` | Model sağlayıcıları + API anahtarları (\`providers.<id>.base_url/key_env/models\`, aktif: \`model.provider/default\`) |
-| \`settings.json\` | App ayarları: theme, workspace, modelOverride, customProviders, roleModels, deletedModels, fallout, waTts, email, waAllow, **searchChain (web arama sırası)**, **obscuraEnabled**, activeBotId |
+| \`settings.json\` | App ayarları: theme, workspace, modelOverride, customProviders, roleModels, deletedModels, fallout, waTts, email, waAllow, **searchChain (web arama sırası)**, activeBotId |
 | \`sessions\\*.jsonl\` | Sohbet oturumları (satır JSON: t:meta kod, t:meta2 paralel-ajan işareti, t:msg mesaj, t:todo, t:notes) |
 | \`sessions\\bg-jobs.json\` | Paralel ajan iş kayıtları: id, title, status(queued/running/done/error/aborted), error=İPTAL SEBEBİ, groupId |
 | \`memories\\\` | SOUL.md (kişilik), MEMORY.md (uzun hafıza), USER.md (kullanıcı) |
@@ -110,9 +110,10 @@ Get-Content "$env:APPDATA\\beast\\sessions\\bg-jobs.json" | ConvertFrom-Json | %
 | \`bots.json\` | Bot kayıt defteri — max 5 bot, ilk kayıt admin 'Beast' (silinemez). Bot adı HARFLE başlamak ZORUNDA |
 | \`bots/<id>/\` | Botun izole klasörü: config.json, memory.md, yetkiler.json, logs/ |
 | \`whitelist.json\`, \`wa-auth\\\`, \`wa-chats.json\`, \`wa.log\` | WhatsApp izin listesi, Baileys auth (SİLME), sohbet eşlemesi, log |
+| \`mcp.json\` | MCP server tanımları — dış araçlar (Ayarlar → MCP'den düzenlenir; araçlar modele \`mcp__<server>__<tool>\` adıyla açılır, çağrı onay kapısından geçer, çöken server 3 dk sonra otomatik yeniden denenir) |
 | \`cron.json\`, \`watchers.json\`, \`bus.json\` | Zamanlanmış görevler, web/batarya izleyicileri, olay abonelikleri |
 | \`scripts\\\` | Python scriptleri (websearch.py, news.py) |
-| \`obscura\\obscura.exe\` | Obscura stealth tarayıcı (web arama zincirinin 2. motoru; açılışta otomatik kurulur) |
+| \`searxng\\settings.yml\` | SearXNG yerel arama motoru ayarları (127.0.0.1:8888 — \`beast searxng\` ile kurulur/başlatılır) |
 | \`py\\python.exe\` | Gömülü Python runtime (makinede Python olmasa bile python_run çalışır) |
 | \`usage.json\`, \`logs\\\` | Kullanım sayaçları, çalışma logları |
 | Masaüstü\\Beast-Backups | Şifreli yedekler (.beastbak) — /backup ile alınır |
@@ -121,14 +122,14 @@ Get-Content "$env:APPDATA\\beast\\sessions\\bg-jobs.json" | ConvertFrom-Json | %
 
 | Dosya | Sorumluluk |
 |---|---|
-| \`main.js\` | Electron ana süreç: tüm IPC, WhatsApp/Telegram/Discord entegrasyonları, onay kapısı (/approve), /stop /restart, splash, gizli araştırma tarayıcısı, obscura kurulumu |
+| \`main.js\` | Electron ana süreç: tüm IPC, WhatsApp/Telegram/Discord entegrasyonları, onay kapısı (/approve), /stop /restart, splash, gizli araştırma tarayıcısı |
 | \`agent/engine.js\` | OTURUM MOTORU: send/_run tur döngüsü, paralel ajanlar (run_background, run_background_many, tasks_list, task_status, task_cancel — task_cancel reason ZORUNLU), superyorizon (takılan işi zorla kapatır), iptal sebep disiplini, flushPendingReports |
 | \`agent/tools.js\` | Araçlar + web_search SIRALI ZİNCİRİ (searchChain: 1 dahili tarayıcı(Google) → 2 Obscura(stealth→DuckDuckGo) → 3 TinyFish(anahtarsa) → 4 python çoklu-motor; sıra Ayarlar→Web Arama'dan değişir), run_command, read/write_file, python_run, http_fetch, deep_search |
 | \`agent/llm.js\` | Sağlayıcı çağrısı + retry: ağ kopmasında 6 deneme + internet dönene kadar bekler; akış ortası kopmada kaldığı yerden devam |
 | \`agent/agentdefs.js\` | Özel ajan tanımları: %APPDATA%\beast\agents\\*.md (frontmatter: model/tools/steps/mode + prompt gövdesi); /agent ile bağlanır, run_background(agent:) ile paralel ajana verilir |
-| \`agent/obscura.js\` | Obscura: otomatik kurulum (GitHub releases, stealth zip) + DuckDuckGo html/lite arama ayrıştırıcı |
+| \`agent/searxng.js\` | SearXNG entegrasyonu: gömülü Python'a kurulum + 127.0.0.1:8888 başlatıcı + JSON arama motoru |
 | \`agent/bots.js\` | Bot CRUD, 5 haneli bot kodu, izolasyon; ad-ilk-harf doğrulaması |
-| \`agent/skills.js\` | Builtin tohumlar (help, email, python-web-search, pdf, gold-trading) + SKILL.md taraması + taslaklar |
+| \`agent/skills.js\` | Builtin tohumlar (help, email, python-web-search, pdf, gold-trading + superpowers metodoloji paketi: brainstorming/writing-plans/executing-plans/TDD/paralel-ajan/alt-ajan-geliştirme/sistematik-debugging/doğrulama/skill-yazma) + SKILL.md taraması + taslaklar |
 | \`agent/memory.js\`, \`agent/kb.js\` | Kalıcı hafıza + bilgi bankası |
 | \`cron.js\` (src kökü), \`agent/watchers.js\`, \`agent/bus.js\` | Cron, izleyici, olay merkezi — /stop bunlara DOKUNMAZ |
 | \`agent/usage.js\` | Token/maliyet sayaçları |
@@ -139,7 +140,7 @@ Get-Content "$env:APPDATA\\beast\\sessions\\bg-jobs.json" | ConvertFrom-Json | %
 /help · /version · /new · /open <kod> · /sessions · /stop · /start · /restart · /change [n] · /model <isim> · /think 0-5 · /clear · /notes · /rule <metin> · /rules · /notify on|off · /screenshot · /approve [always] · /deny · /update [now] · /usage · /backup · /status · /skills
 
 ## AYAR SEKMELERİ
-Provider · Fallout · Skills · Paralel Ajanlar · TTS · E-posta · Entegrasyonlar · Web Arama (Obscura kurulum + arama sırası) · Olaylar · Cron · Maliyet · Loglar · Panel · Limitler · Güvenlik · Güncelleme
+Provider · Fallout · Skills · Paralel Ajanlar · TTS · E-posta · Entegrasyonlar · Web Arama · MCP · Olaylar · Cron · Maliyet · Loglar · Panel · Limitler · Güvenlik · Güncelleme
 
 ## PARALEL AJAN HIZLI BİLGİ
 - CEO modu: konuşan ajan iş YAPMAZ, run_background/run_background_many ile devreder; görev tanımı kendine yeterli olmalı (ajan CEO bağlamını GÖREMEZ).
@@ -235,9 +236,9 @@ web_search aracı çağrıldığında zincir OTOMATİK çalışır — elle moto
 
 Gerçek Chromium olduğu için Google'a bot koruması uygulamaz. Arama aep=1 ile açılır: Google'ın KENDİ AI cevabı yanıtın 'ai' alanında HAZIR gelir — "kimdir/nedir" sorularında önce onu kullan, kaynak linkleri de 'results' alanında gelir. Sağ panelde açılır, kullanıcı da görebilir. CAPTCHA/trafik uyarısı gelirse tarayıcı 10 dk atlanır, sıradaki motor devreye girer.
 
-## 2. Obscura (stealth headless — DuckDuckGo)
+## 2. SearXNG (yerel metasearch — otomatik öncelik)
 
-Rust tabanlı gizli tarayıcı: anti-detect parmak izi + V8 JS. Beast Agent PAKETİNDE hazır gelir — ilk açılışta %APPDATA%\\beast\\obscura'ya açılır (indirme yok). Varsayılan AKTİF — tarayıcı engellenirse bot korumasını aşarak DuckDuckGo'dan sonuç getirir.
+Ücretsiz, sınırsız, anahtarsız. \`beast searxng\` ile gömülü Python'a kurulur ve 127.0.0.1:8888'de arka planda çalışır. AYAKTAYSA zincirde nerede olursa olsun OTOMATİK ÖNE alınır (çok kaynaklı: Google/Bing/DDG…); kapalıysa sessizce atlanır.
 
 ## 3. TinyFish API (anahtar varsa)
 
@@ -452,16 +453,45 @@ function writeSeed(seed) {
   } catch {}
 }
 
+/* Dosya tohumları: src/agent/seeds/<klasör>/SKILL.md — Superpowers metodoloji
+   paketi gibi kod dışı taşınan builtin skill'ler. Hepsi force: her açılışta
+   app sürümüyle güncellenir (kullanıcı düzenlemesi korunmaz, builtin'dir). */
+function fileSeedsDir() {
+  return path.join(__dirname, 'seeds');
+}
+
+function loadFileSeeds() {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(fileSeedsDir(), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    try {
+      out.push({
+        folder: e.name,
+        force: true,
+        body: fs.readFileSync(path.join(fileSeedsDir(), e.name, 'SKILL.md'), 'utf8'),
+      });
+    } catch {}
+  }
+  return out;
+}
+
 /* Kaldırılan eski tohumlar: kullanıcı makinesinden de silinir */
 const RETIRED_SEEDS = ['free-web-search'];
 
 function seedIfEmpty() {
+  const seeds = SEEDS.concat(loadFileSeeds());
   if (!scan().length) {
-    for (const seed of SEEDS) writeSeed(seed);
+    for (const seed of seeds) writeSeed(seed);
   } else {
     /* force tohumlar her açılışta güncellenir: varsayılan web arama skill'inin
        içeriği hep güncel kalır (mevcut kurulum dahil) */
-    for (const seed of SEEDS) {
+    for (const seed of seeds) {
       if (seed.force) writeSeed(seed);
     }
   }
@@ -612,6 +642,7 @@ module.exports = {
   scan,
   seedIfEmpty,
   parseFrontmatter,
+  loadFileSeeds,
   addDraft,
   listDrafts,
   acceptDraft,