Bootstrap ve Onboarding

Bugünkü gerçeklik

Depo hâlâ oldukça elle yürütülen bir Python ve Node kurulumu bekliyor. Bu, katkı verenler için kabul edilebilir; ama daha geniş kullanıcı tabanı için istediğimiz V1 onboarding deneyimi henüz bu değil.

Ürün hedefi

Uzun vadeli bootstrap akışı README içinden komut avlatmak yerine yönlendirmeli bir launcher gibi hissettirmeli. En azından şu işleri yapabilmeli:

1. platform ve prerequisite eksiklerini tespit etmek
2. isteğe bağlı bağımlılık kurulumunu teklif etmek
3. Python ve Node ortamlarını hazırlamak
4. provider ve model ready oluşunu doğrulamak
5. ilgili lokal yüzeyi başlatmak
6. herhangi bir şey bozulduğunda sonraki adımı açıkça söylemek

Planlanan komut yüzeyi

Komut yüzeyi gizemli değil, katmanlı kalmalı. Debugging için odaklı komutlar kalmalı, normal operatör ise kısa bir lifecycle sözlüğüyle çalışabilmeli:

setup:node, install:python, setup:research-flow, setup:camofox, fetch:camofox, start:camofox ve servis bazlı CLI komutları debugging için faydalı kalmalı. Plan, bunları yönlendirmeli lifecycle'ın arkasındaki uygulanabilir parçalar haline getirmek; kullanıcıyı tek tek komut avına mecbur bırakmak değil.

app:doctor bilinçli olarak ilk implemente edilen lifecycle komutudur. Gizli yan etkiyle ortam oluşturmasın ya da onarmasın diye uv run çağırmak yerine zaten kurulu olan agentic-trader entrypoint'ini kullanır. setup-status, model-service, Camofox-service, WebGUI-service, provider diagnostics ve network-light v1-readiness okur; generation probe hâlâ açıkça v1-readiness --provider-check veya model-service status --probe-generation ile istenir.

app:up artık ilk yönlendirmeli first-run orkestratörüdür. Varsayılanı dry-run'dır ve yeni bir runtime sahibi yaratmak yerine mevcut lifecycle komutlarını birleştirir. Güvenli --all --yes lane'i core setup repair, runtime kontrollü CrewAI Flow sidecar setup, app-owned Web GUI start ve final app:doctor raporu çalıştırır. Opsiyonel Camofox dependency setup, Camofox browser binary fetch, model-service start ve Camofox-service start için açık scope ve --ollama-owner=app-owned ya da --camofox-owner=app-owned gibi eşleşen sahiplik flag'i gerekir. Host-owned, API/key-only ve skipped seçimleri runtime/setup/tool-ownership.json içine yazılır; setup status, dashboard, Web GUI ve TUI readiness üzerinde görünür kalır; gizli install'a dönüşmez.

app:start ve app:stop da konservatif servis slice'ları olarak implemente edildi: varsayılanları dry-run'dır, --webgui, --model-service, --camofox-service veya --all seçimi isterler ve ancak --yes sonrası mutasyon yaparlar. Dependency kurmaz, browser binary fetch etmez, Ollama model çekmez, trading daemon başlatmaz, --open-browser açıkça verilmedikçe browser açmazlar. Sahiplik kontrolleri mevcut model-service, camofox-service ve webgui-service komutlarının içinde kalır. app:start ile model-service ya da Camofox-service başlatmak için kalıcı sahiplik modunun app-owned olması gerekir; host-owned veya skipped araçlar sahiplenilmez, görünür blocker olarak kalır. Kaydedilmiş app-owned Web GUI süreci durdurulamazsa state retry için korunur; süreç sessizce external listener gibi yeniden sınıflandırılmaz.

app:update ilk scoped update lane'i olarak implemente edildi. Varsayılanı dry-run'dır; mutasyon için --core, --sidecar, --camofox, --build, --status veya --all seçimi ve --yes ister. Her dependency setinin native sahibini kullanır; browser binary fetch etmez, model çekmez, servis başlatmaz/durdurmaz, runtime state silmez ve trading daemon başlatmaz.

app:uninstall ilk konservatif cleanup lane'i olarak implemente edildi. Varsayılanı dry-run'dır; dosya silmek için --artifacts, --deps, --service-state veya --all seçimi ve --yes ister. Ignored env dosyalarını, secret'ları, provider hesaplarını, brokerage config'i, host-owned servisleri, global tool'ları ve trading runtime evidence'ını korur. Kaydedilmiş servis state dosyaları duruyorsa service-state cleanup bloke olur; önce app:stop ile app-owned süreç kaydı temizlenmelidir.

Vazgeçilmez gereksinimler

• macOS, Linux ve Windows desteği
• Ollama'yı zorla dayatmayan provider-aware davranış
• isteğe bağlı model servisleri ve modeller için açık onay
• yarım kurulumlarda resume ya da repair davranışı
• görünür loglar ve aksiyon alınabilir hata mesajları
• gizli dependency silme, büyük browser/model indirme, provider hesabı oluşturma veya daemon başlatma yok

Tool sahipliği soruları

Opsiyonel yardımcıları kurmadan ya da başlatmadan önce yönlendirmeli setup operatöre hangi sahiplik modunu istediğini sormalı:

• host-owned: uygulama zaten yönetilen lokal araca bağlanır ve onu durdurmaz
• app-owned: uygulama repo-local yardımcıyı kurar ya da kullanır, başlatmadan/durdurmadan önce owner-only state/log kaydeder
• API/key-only: uygulama CLI kurmadan ignored environment veya keychain değerini kullanır
• skipped: özellik degraded kalır ama core paper-first ürün açılabilir

Bu ayrım Ollama, Firecrawl ve Camofox için önemli. Host Ollama yoksa ve operatör host kurulumu istemiyorsa installer Web GUI'yi kafa karıştırıcı bir "Ollama unreachable" durumuna açmak yerine app-owned model-service yolunu teklif etmeli. Firecrawl internal SDK/API-key yolunu önce kullanmalı; authenticated host CLI fallback yalnızca Firecrawl host-owned kaydedildiğinde çalışmalı, app-owned/API-only/skipped modlarında bu fallback kapalı ve görünür kalmalı. Camofox loopback-only, access-key-gated kalmalı; browser binary fetch ise ayrı ve opt-in bir adım olmalı.

Mevcut sahiplik durumu setup çalıştırmadan da görülebilir ya da değiştirilebilir:

agentic-trader tool-ownership status --json
agentic-trader tool-ownership set --ollama-owner host-owned --firecrawl-owner api-key-only --camofox-owner skipped --json

Karar zaten kayıtlıysa make bootstrap bunu raporlayıp devam etmeli; aynı sahiplik sorularını tekrar sormamalı. Değişiklik gerekiyorsa bootstrap öncesi agentic-trader tool-ownership set ... ile açıkça yeniden seç.

V1 varsayılanı internal-first model yoludur: app-owned Ollama, qwen3:8b ve mevcut model-service status/log yüzeyleri. Operatör host sahipliği kaydederse host fallback kullanılabilir, fakat app lifecycle komutları host-owned araçları başlatmaz ya da durdurmaz. Başka model adaptörü isteyen operatör Ollama'yı skipped bırakıp OpenAI-compatible endpoint'i açıkça seçebilir:

AGENTIC_TRADER_LLM_PROVIDER=openai-compatible
AGENTIC_TRADER_BASE_URL=http://127.0.0.1:8080/v1
AGENTIC_TRADER_MODEL_NAME=your-model
AGENTIC_TRADER_OPENAI_COMPATIBLE_API_KEY=optional-secret

Ollama için özel yön

Ollama PATH'teyse taşınabilir bir lokal başlangıç komutu şöyle görünebilir. macOS Homebrew, Linux veya Windows kurulumlarında binary yolu farklı olabilir.

OLLAMA_FLASH_ATTENTION="1" OLLAMA_KV_CACHE_TYPE="q8_0" ollama serve

İstenen gelecek durum “kullanıcı bu komutu ezberlesin” değil. İstenen gelecek durum şu:

• uygulama Ollama'yı bilinçli biçimde başlatıp durdurabilsin
• uygulama health ve son logları gösterebilsin
• operatör idle, busy ve broken hâllerini ayırt edebilsin

Yönlendirmeli setup dört durumu ayırmalı: host Ollama reachable, app-owned Ollama ready, başka provider seçildiği için Ollama bilerek skipped, ve model backend eksik ya da bozuk. app:start aktif provider ollama ise önceden yapılandırılmış app-owned model service'i başlatabilir; ama binary kurmayı, model çekmeyi, host listener'ı sahiplenmeyi veya açıkça seçilmiş OpenAI-compatible adaptörü override etmeyi sessizce yapmamalı.

Camofox ve pnpm yönü

tools/camofox-browser opsiyonel tool altyapısıdır; broker ya da runtime otoritesi değildir. Kurulumu npm-owned helper komutlarından repo'nun pnpm politikasına taşınmalı:

pnpm --dir tools/camofox-browser install --ignore-workspace --ignore-scripts
pnpm --dir tools/camofox-browser --ignore-workspace run fetch:browser
pnpm --dir tools/camofox-browser --ignore-workspace run test

İlk komut browser indirmeden lokal helper bağımlılıklarını kurar. İkinci komut Camoufox browser binary'sini indirir ya da günceller; büyük ve platforma özel olabileceği için açık onaylı kalmalı. Wrapper ve servis komutları helper'ı yalnızca loopback host ile ve CAMOFOX_ACCESS_KEY ya da aynalanmış CAMOFOX_API_KEY varken başlatmalı.

Update ve uninstall yönü

app:update her dependency sahibini kendi aracıyla günceller, sonra build ve setup status çalıştırabilir:

• root Node workspace: pnpm recursive/workspace update akışı
• Camofox helper: pnpm --dir tools/camofox-browser ...
• root Python: uv workspace lock upgrade ve locked sync
• CrewAI Flow sidecar: root uv üzerinden workspace member locked sync
• docs/WebGUI/TUI: normal workspace build ve typecheck kapıları
• post-update status: app:doctor

app:uninstall yalnızca seçilen app-owned/generated scope'ları kaldırır: artifact'lar, dependency dizinleri, repo-local pnpm store ve app-owned helper service-state/log dizinleri. API keyleri, broker/provider hesapları, user-owned host servisleri, global tool'lar, ignored env dosyaları veya DuckDB gibi trading evidence silinmemeli. Servis state dosyası hâlâ varsa operatör önce pnpm run app:stop -- --all --yes çalıştırmalıdır.

Tasarlanması gereken edge case'ler

• kullanıcı başka provider istediği için Ollama'yı atlayabilmeli
• package manager ya da shell toolchain eksik olabilir
• PATH bakımcının makinesinden farklı olabilir
• kısmi kurulum vardır ve repair ister
• Web GUI açılır ama runtime readiness check'lerini geçemez
• model vardır ama yanlış adapter ya da base URL yapılandırılmıştır
• Camofox dependency'leri vardır ama browser binary yoktur
• stale app-owned PID varken host-owned listener da çalışıyordur
• IDE ya da worktree agentic-trader komutunu stale checkout'tan çözümlüyordur

İyi bir bootstrap UX neyi açık söyler

İyi bir bootstrap akışı şu konularda net olmalı:

• ne kuracağı
• neyi atladığı
• neyin zorunlu neyin opsiyonel olduğu
• hangi dosyaları değiştirdiği
• bir adım neden deferred kaldı ve sıradaki komut/sahiplik aksiyonu ne
• hangi lokal URL ya da UI'yi başlattığı

Önerilen kabul listesi

• Yeni bir makine doctor noktasına tahmin yürütmeden ulaşabilmeli.
• İsteğe bağlı model kurulumu atlanınca geri kalan sistem bozulmamalı.
• Model ya da provider ready oluşu eksikse kullanıcı açık bir hata görmeli.
• Launcher kullanıcıyı loglara yönlendirebilmeli; logları saklamamalı.
• Oluşturulan ortam repo'nun mevcut runtime sözleşmeleriyle uyumlu kalmalı.
• Camofox, Firecrawl ve Ollama sahiplik kararları kalıcı olmalı; setup status, dashboard, Web GUI ve TUI readiness üzerinde görünür olmalı.
• Bootstrap yeniden çalıştırıldığında kalıcı sahiplik kararlarını ezmemeli ve aynı sahiplik sorularını tekrarlamamalı.
• Opsiyonel global CrewAI CLI hataları kısa setup notu olarak kalmalı; setup-status içinde çok satırlı version traceback'e dönüşmemeli.
• app:up partial install durumundan toparlanabilmeli ve ya açılmış Web GUI'yle ya da net blocker raporuyla bitmeli.