Beitragsleitfaden — Shell Sentinel

Diese Zusammenfassung fasst die internen Richtlinien für die Zusammenarbeit an Shell Sentinel zusammen: Projektstruktur, Dokumentationsstandards und Website-Pflege. Jeder Beitrag sollte diesen Leitlinien folgen, um die Produktkohärenz zu wahren.

Allgemeine Prinzipien

• Terminalorientierte Anwendung mit persistenten SSH/SFTP-Sitzungen und einem konversationellen KI-Assistenten.
• Python-3.12-Ökosystem, Textual-8.2.8-TUI, Strands Agents 1.61.1 mit Strands Agents Tools 0.8.9, MCP-Transporte auf Basis von mcp 2.x und MCP-Tools wie Firecrawl.
• Abhängigkeiten über pyproject.toml und pip-tools-Lockfiles (make lock, make install).
• Tägliche Arbeit mit make install, make format, make lint, make test und make run.
• GitHub-Actions-CI (Lint + Tests auf Python 3.12) bei jedem Pull Request über .github/workflows/ci.yml.

Konfiguration und Inhalte

• Alle Konfiguration liegt in conf/ (keine fest verdrahteten Werte im Code).
• Neue Strings in conf/locales/ hinzufügen und mit _("schlüssel") referenzieren.
• Benutzerhandbücher in EN/ES/DE pflegen, sobald sich ein Ablauf ändert.
• Eigene Provider in der technischen Anleitung dokumentieren und von der Website verlinken.

Plugins und Erweiterbarkeit

• Plugins werden aus plugins/ geladen; jedes muss Befehle, Übersetzungen und lokale Dokumentation registrieren.
• Plugin-spezifische Dokumentation nicht mit allgemeinen Handbüchern vermischen.
• System-Prompts respektieren und keine parallelen SSH/SFTP-Verbindungen außerhalb der offiziellen Tools anlegen.

Richtlinie für Web-Dokumentation

• Die Website unter website/ ist Teil des Produkts und muss jede funktionale oder narrative Änderung widerspiegeln.
• Bei Änderungen an Handbüchern, Befehlen oder Providern Inhalte der Website synchronisieren (Abschnitte, Karten, Links und Übersetzungen).
• Online-Handbücher nutzen HTML-Seiten in website/manuals/; relevante Änderungen aus docs/ spiegeln.

Testsuite

• make test führt die Unit-Tests plus die Offline-End-to-End-Schicht aus (tests/e2e/offline, Marker e2e_offline): die echte Textual-App, AgentRuntime und strands.Agent gegen einen In-Process-SSH/SFTP-Server mit einem geskripteten Modell; sie braucht keine Schlüssel und läuft in CI. Sie startet außerdem echte MCP-Server (einen geskripteten stdio-Server und lokale HTTP-Endpunkte), um Tool-Aufrufe, Startdiagnosen und das Aufräumen der Prozesse zu prüfen. make test-e2e führt nur diese Schicht aus.
• make test-e2e-live (tests/e2e/live, Marker e2e) fährt Operator-Szenarien gegen die echten Provider; es erfordert RUN_E2E=1 plus OPENAI_API_KEY, MISTRAL_API_KEY und/oder GEMINI_API_KEY, deckelt die Modellaufrufe pro Test und läuft nie in CI. Die MCP-Szenarien starten den echten Firecrawl-Server und brauchen FIRECRAWL_API_KEY und Node.js (npx).
• make test-mistral behält die Mistral-PoC-Tests (Marker mistral, benötigt MISTRAL_API_KEY); sie sind als e2e markiert, damit make test nie Tokens verbraucht.

Empfohlener Workflow

1. Virtualenv aktivieren (python3.12 -m venv .venv, dann source .venv/bin/activate).
2. Abhängigkeiten installieren (make install).
3. Nach Änderungen: make format, make lint, make test (Pflicht vor dem Öffnen eines PR); bei Änderungen an TUI, Agent-Runtime oder einem Provider zusätzlich make test-e2e-live.
4. TUI mit make run und Website mit make website-serve validieren.

Weitere Details im internen Richtlinienportal. Nach jedem Beitrag prüfen, dass Website, Handbücher und Repository konsistent bleiben.