Cascade Hooks (Beta)

Cascade Hooks vă permit să executați comenzi shell personalizate în momente cheie din fluxul de lucru al Cascade. Această capabilitate puternică de extensibilitate vă permite să înregistrați operațiuni, să impuneți garde-fou, să rulați verificări de validare sau să vă integrați cu sisteme externe.

Lansare Beta: Cascade Hooks sunt în prezent în versiune beta și se află în dezvoltare activă. Funcționalitățile și API-urile se pot modifica. Vă rugăm să contactați Windsurf Support pentru feedback sau raportarea erorilor.

Hooks sunt concepute pentru utilizatori avansați și echipe Enterprise care au nevoie de control granular asupra comportamentului Cascade. Acestea necesită cunoștințe de bază de scripting în shell.

Ce puteți construi

Hook-urile deblochează o gamă largă de capabilități pentru automatizare și guvernanță:

Jurnalizare & Analytics: Monitorizați fiecare fișier citit, modificare de cod sau comandă executată de Cascade, pentru conformitate și analiză a utilizării
Controale de securitate: Împiedicați Cascade să acceseze fișiere sensibile sau să ruleze comenzi periculoase
Asigurarea calității: Rulați automat linters, formatare sau teste după modificările de cod
Fluxuri de lucru personalizate: Integrați cu trackere de issue-uri, sisteme de notificare sau pipeline-uri de deployment
Standardizare la nivel de echipă: Aplicați standarde de cod și bune practici în întreaga organizație

Cum funcționează hook-urile

Hook-urile sunt comenzi de shell care rulează automat atunci când au loc acțiuni Cascade specifice. Fiecare hook:

Primește context (detalii despre acțiunea executată) prin JSON ca intrare standard
Execută scriptul dvs. – Python, Bash, Node.js sau orice executabil
Returnează un rezultat prin codul de ieșire și fluxurile de ieșire

Pentru pre-hook-uri (executate înaintea unei acțiuni), scriptul dvs. poate bloca acțiunea încheindu-se cu codul de ieșire 2. Acest lucru face ca pre-hook-urile să fie ideale pentru implementarea politicilor de securitate sau a verificărilor de validare.

Configurare

Hook‑urile se configurează în fișiere JSON care pot fi plasate la trei niveluri diferite. Cascade încarcă și combină hook‑urile din toate locațiile, oferind echipelor flexibilitate în modul în care distribuie și gestionează configurațiile de hook.

La nivel de sistem

Hook-urile la nivel de sistem sunt ideale pentru politici la nivelul întregii organizații, aplicate pe stații de lucru partajate. De exemplu, le puteți folosi pentru a impune politici de securitate, cerințe de conformitate sau fluxuri de lucru obligatorii pentru code review.

macOS: /Library/Application Support/Windsurf/hooks.json
Linux/WSL: /etc/windsurf/hooks.json
Windows: C:\ProgramData\Windsurf\hooks.json

La nivel de utilizator

Hookurile la nivel de utilizator sunt ideale pentru preferințe personale și fluxuri de lucru opționale.

Locație: ~/.codeium/windsurf/hooks.json

La nivel de workspace

Hook-urile la nivel de workspace permit echipelor să versiuneze politici specifice proiectului alături de cod. Acestea pot include reguli personalizate de validare, integrări specifice proiectului sau fluxuri de lucru specifice echipei.

Locație: .windsurf/hooks.json în rădăcina workspace-ului

Hook-urile din toate cele trei locații sunt comasate. Dacă același eveniment de hook este configurat în mai multe locații, toate hook-urile se vor executa în această ordine: sistem → utilizator → workspace.

Structură de bază

Iată un exemplu al structurii de bază a configurației pentru hooks:

{
  "hooks": {
    "pre_read_code": [
      {
        "command": "python3 /path/to/your/script.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "python3 /path/to/another/script.py",
        "show_output": true
      }
    ]
  }
}

Opțiuni de configurare

Fiecare hook acceptă următorii parametri:

Parametru	Tip	Descriere
`command`	string	Comanda shell de executat. Poate fi orice executabil valid, cu argumente.
`show_output`	boolean	Dacă să fie afișată ieșirea stdout/stderr a hook‑ului în interfața Cascade vizibilă pentru utilizator. Util pentru depanare.
`working_directory`	string	Opțional. Directorul din care se execută comanda. Implicit, rădăcina workspace‑ului dvs.

Evenimente hook

Cascade oferă opt evenimente hook care acoperă cele mai importante acțiuni din fluxul de lucru al agentului.

Structura comună a inputului

Toate hook-urile primesc un obiect JSON cu următoarele câmpuri comune:

Câmp	Tip	Descriere
`agent_action_name`	string	Numele evenimentului hook-ului (de ex. „pre_read_code”, „post_write_code”)
`trajectory_id`	string	Identificator unic pentru conversația Cascade în ansamblu
`execution_id`	string	Identificator unic pentru o singură iterație a agentului
`timestamp`	string	Marcaj temporal ISO 8601 la momentul declanșării hook-ului
`tool_info`	object	Informații specifice evenimentului (variază în funcție de tipul de hook)

În exemplele de mai jos, câmpurile comune sunt omise pentru concizie. Există opt tipuri majore de evenimente de tip hook:

pre_read_code

Declanșat înainte ca Cascade să citească un fișier de cod. Acest lucru poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Restricționați accesul la fișiere, înregistrați operațiunile de citire, verificați permisiunile Input JSON:

{
  "agent_action_name": "pre_read_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py"
  }
}

Acest file_path poate fi o cale de director atunci când Cascade parcurge recursiv un director.

post_read_code

Declanșat după ce Cascade citește cu succes un fișier de cod. Cazuri de utilizare: Înregistrați citirile reușite, urmăriți tiparele de acces la fișiere Input JSON:

{
  "agent_action_name": "post_read_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py"
  }
}

Acest file_path poate fi o cale de director atunci când Cascade parcurge recursiv un director.

pre_write_code

Declanșat înainte ca Cascade să scrie sau să modifice un fișier de cod. Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Prevenirea modificărilor în fișiere protejate, realizarea de copii de rezervă înainte de schimbări Input JSON:

{
  "agent_action_name": "pre_write_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py",
    "edits": [
      {
        "old_string": "def old_function():\n    pass",
        "new_string": "def new_function():\n    return True"
      }
    ]
  }
}

post_write_code

Declanșat după ce Cascade scrie sau modifică un fișier de cod. Cazuri de utilizare: Rulați linters, formatare sau teste; înregistrați modificările de cod Input JSON:

{
  "agent_action_name": "post_write_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py",
    "edits": [
      {
        "old_string": "import os",
        "new_string": "import os\nimport sys"
      }
    ]
  }
}

pre_run_command

Se declanșează înainte ca Cascade să execute o comandă în terminal. Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Blocați comenzile periculoase, înregistrați toate execuțiile de comenzi, adăugați verificări de siguranță Input JSON:

{
  "agent_action_name": "pre_run_command",
  "tool_info": {
    "command_line": "npm install package-name",
    "cwd": "/Users/yourname/project"
  }
}

post_run_command

Se declanșează după ce Cascade execută o comandă în terminal. Cazuri de utilizare: înregistrarea rezultatelor comenzii, declanșarea acțiunilor ulterioare Input JSON:

{
  "agent_action_name": "post_run_command",
  "tool_info": {
    "command_line": "npm install package-name",
    "cwd": "/Users/yourname/project"
  }
}

pre_mcp_tool_use

Declanșat înainte ca Cascade să utilizeze un instrument MCP (Model Context Protocol). Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Înregistrarea utilizării MCP, restricționarea instrumentelor MCP care pot fi folosite Input JSON:

{
  "agent_action_name": "pre_mcp_tool_use",
  "tool_info": {
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "repo": "my-cool-repo",
      "title": "Raport de eroare",
      "body": "Descrierea erorii aici"
    },
    "mcp_tool_name": "create_issue"
  }
}

post_mcp_tool_use

Declanșat după ce Cascade a apelat cu succes un instrument MCP. Cazuri de utilizare: Înregistrați operațiunile MCP, urmăriți utilizarea API-ului, vizualizați rezultatele MCP Input JSON:

{
  "agent_action_name": "post_mcp_tool_use",
  "tool_info": {
    "mcp_result": "...",
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "perPage": 1,
      "repo": "my-cool-repo",
      "sha": "main"
    },
    "mcp_tool_name": "list_commits"
  }
}

Coduri de ieșire

Scripturile hook comunică rezultatele prin coduri de ieșire:

Cod de ieșire	Semnificație	Efect
`0`	Succes	Acțiunea continuă normal
`2`	Eroare care blochează	Agentul Cascade va vedea mesajul de eroare din stderr. Pentru pre-hook-uri, acest lucru blochează acțiunea.
Oricare altul	Eroare	Acțiunea continuă normal

Doar pre-hook-urile (pre_read_code, pre_write_code, pre_run_command, pre_mcp_tool_use) pot bloca acțiunile folosind codul de ieșire 2. Post-hook-urile nu pot bloca, deoarece acțiunea a avut deja loc.

Țineți cont că utilizatorul poate vedea orice ieșire standard și eroare standard generate de hook în interfața Cascade dacă show_output este true.

Exemple de scenarii de utilizare

Înregistrarea tuturor acțiunilor Cascade

Monitorizați fiecare acțiune efectuată de Cascade în scopuri de audit. Config (~/.codeium/windsurf/hooks.json):

{
  "hooks": {
    "post_read_code": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_mcp_tool_use": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ]
  }
}

Script (log_input.py):

#!/usr/bin/env python3

import sys
import json

def main():
    # Citește datele JSON din stdin
    input_data = sys.stdin.read()
    
    # Procesează JSON-ul
    try:
        data = json.loads(input_data)
        
        # Scrie JSON-ul formatat în fișier
        with open("/Users/yourname/hooks/input.txt", "a") as f:
            f.write('\n' + '='*80 + '\n')
            f.write(json.dumps(data, indent=2, separators=(',', ': ')))
            f.write('\n')
    
        print(json.dumps(data, indent=2))
    except json.JSONDecodeError as e:
        print(f"Eroare la procesarea JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Acest script adaugă fiecare apel al unui hook într-un fișier jurnal, creând un traseu de audit pentru toate acțiunile Cascade. Puteți transforma datele de intrare sau rula logică personalizată, după cum considerați potrivit.

Restricționarea accesului la fișiere

Împiedicați Cascade să citească fișiere din afara unui director specific. Config (~/.codeium/windsurf/hooks.json):

{
  "hooks": {
    "pre_read_code": [
      {
        "command": "python3 /Users/yourname/hooks/block_read_access.py",
        "show_output": true
      }
    ]
  }
}

Script (block_read_access.py):

#!/usr/bin/env python3

import sys
import json

ALLOWED_PREFIX = "/Users/yourname/my-project/"

def main():
    # Citește datele JSON din stdin
    input_data = sys.stdin.read()

    # Analizează JSON-ul
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "pre_read_code":
            tool_info = data.get("tool_info", {})
            file_path = tool_info.get("file_path", "")
            
            if not file_path.startswith(ALLOWED_PREFIX):
                print(f"Acces refuzat: Cascade poate citi doar fișierele din {ALLOWED_PREFIX}", file=sys.stderr)
                sys.exit(2)  # Codul de ieșire 2 blochează acțiunea
            
            print(f"Acces acordat: {file_path}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Eroare la analiza JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Când Cascade încearcă să citească un fișier din afara directorului permis, acest hook blochează operațiunea și afișează un mesaj de eroare.

Blocarea comenzilor periculoase

Împiedicați Cascade să ruleze comenzi potențial dăunătoare. Config (~/.codeium/windsurf/hooks.json):

{
  "hooks": {
    "pre_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/block_dangerous_commands.py",
        "show_output": true
      }
    ]
  }
}

Script (block_dangerous_commands.py):

#!/usr/bin/env python3

import sys
import json

DANGEROUS_COMMANDS = ["rm -rf", "sudo rm", "format", "del /f"]

def main():
    # Citește datele JSON din stdin
    input_data = sys.stdin.read()

    # Analizează JSON-ul
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "pre_run_command":
            tool_info = data.get("tool_info", {})
            command = tool_info.get("command_line", "")

            for dangerous_cmd in DANGEROUS_COMMANDS:
                if dangerous_cmd in command:
                    print(f"Comandă blocată: '{dangerous_cmd}' nu este permisă din motive de securitate.", file=sys.stderr)
                    sys.exit(2)  # Codul de ieșire 2 blochează comanda
            
            print(f"Comandă aprobată: {command}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Eroare la analizarea JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Acest hook scanează comenzile pentru modele periculoase și le blochează înainte de execuție.

Rularea formatarelor de cod după modificări

Formatați automat fișierele de cod după ce Cascade le actualizează. Config (~/.codeium/windsurf/hooks.json):

{
  "hooks": {
    "post_write_code": [
      {
        "command": "bash /Users/yourname/hooks/format_code.sh",
        "show_output": false
      }
    ]
  }
}

Script (format_code.sh):

#!/bin/bash

# Citește JSON din stdin
input=$(cat)

# Extrage calea fișierului utilizând jq
file_path=$(echo "$input" | jq -r '.tool_info.file_path')

# Formatează în funcție de extensia fișierului
if [[ "$file_path" == *.py ]]; then
    black "$file_path" 2>&1
    echo "Fișier Python formatat: $file_path"
elif [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
    prettier --write "$file_path" 2>&1
    echo "Fișier JS/TS formatat: $file_path"
elif [[ "$file_path" == *.go ]]; then
    gofmt -w "$file_path" 2>&1
    echo "Fișier Go formatat: $file_path"
fi

exit 0

Acest hook rulează automat formatorul adecvat în funcție de tipul fișierului, după fiecare modificare.

Recomandări de bune practici

Securitate

Utilizați Cascade Hooks pe propria răspundere: Hook‑urile execută automat comenzi de shell cu toate permisiunile contului dvs. de utilizator. Sunteți pe deplin responsabil(ă) pentru codul pe care îl configurați. Hook‑urile proiectate defectuos sau malițioase pot modifica fișiere, șterge date, expune credențiale sau compromite sistemul.

Validați toate intrările: Nu aveți niciodată încredere în JSON‑ul de intrare fără validare, mai ales în ceea ce privește căile de fișiere și comenzile.
Folosiți căi absolute: Utilizați întotdeauna căi absolute în configurațiile hook‑urilor pentru a evita ambiguitățile.
Protejați datele sensibile: Evitați înregistrarea (logging) informațiilor sensibile, precum chei API sau credențiale.
Revizuiți permisiunile: Asigurați-vă că scripturile hook au permisiuni adecvate în sistemul de fișiere.
Auditați înainte de implementare: Examinați fiecare comandă și script de hook înainte de a le adăuga în configurație.
Testați în izolare: Rulați hook‑urile într-un mediu de test înainte de a le activa pe stația dvs. principală de dezvoltare.

Considerații privind performanța

Păstrați hook-urile rapide: Hook-urile lente vor afecta capacitatea de răspuns a Cascade. Vizați timpi de execuție sub 100 ms.
Folosiți operațiuni asincrone: Pentru hook-uri neblocante, luați în considerare logarea într-o coadă sau într-o bază de date, asincron.
Filtrați cât mai devreme: Verificați tipul acțiunii la începutul scriptului pentru a evita procesarea inutilă.

Gestionarea erorilor

Validați întotdeauna JSON-ul: Folosiți blocuri try-catch pentru a gestiona elegant datele de intrare malformate.
Înregistrați corect erorile: Trimiteți erorile la stderr pentru a fi vizibile când show_output este activat.
Eșuați în siguranță: Dacă hook-ul dvs. întâmpină o eroare, evaluați dacă ar trebui să blocheze acțiunea sau să permită continuarea acesteia.

Testarea hook-urilor

Începeți cu jurnalizarea: Implementați mai întâi un hook simplu de jurnalizare pentru a înțelege fluxul de date.
Folosiți show_output: true: Activați afișarea rezultatelor în timpul dezvoltării pentru a vedea ce fac hook-urile.
Testați comportamentul de blocare: Verificați că valoarea de ieșire 2 (exit code 2) blochează corect acțiunile în pre-hooks.
Verificați toate ramurile de cod: Testați atât scenariile de reușită, cât și pe cele de eșec în scripturi.

Distribuție Enterprise

Organizațiile Enterprise trebuie să aplice politici de securitate, cerințe de conformitate și standarde de dezvoltare pe care utilizatorii individuali nu le pot evita. Cascade Hooks susține acest lucru printr-o configurație la nivel de sistem, care are prioritate și nu poate fi dezactivată de utilizatorii finali fără permisiuni de root. Implementați configurația obligatorie hooks.json în aceste locații specifice sistemului de operare: macOS:

/Library/Application Support/Windsurf/hooks.json

Linux/WSL:

/etc/windsurf/hooks.json

Windows:

C:\ProgramData\Windsurf\hooks.json

Plasați scripturile hook într-un director de sistem corespunzător (de ex. „/usr/local/share/windsurf-hooks/” pe sistemele Unix).

Metode de implementare

Echipele IT Enterprise pot implementa hook‑uri la nivel de sistem folosind instrumente și fluxuri de lucru standard: Mobile Device Management (MDM)

Jamf Pro (macOS) - Implementare prin profiluri de configurare sau scripturi
Microsoft Intune (Windows/macOS) - Utilizați scripturi PowerShell sau implementarea prin politici
Workspace ONE, Google Endpoint Management și alte soluții MDM

Gestionarea configurațiilor

Ansible, Puppet, Chef, SaltStack - Utilizați automatizarea existentă a infrastructurii
Scripturi personalizate de implementare - Scripturi shell, PowerShell sau instrumentele preferate

Verificare și auditare

După implementare, verificați că hook-urile sunt instalate corect și nu pot fi ocolite:

# Verificați dacă hook-urile de sistem sunt prezente
ls -la /etc/windsurf/hooks.json  # Linux
ls -la "/Library/Application Support/Windsurf/hooks.json"  # macOS

# Testați execuția hook-ului (ar trebui să vedeți rezultatul hook-ului în Cascade)
# Solicitați unui dezvoltator să declanșeze acțiunea Cascade relevantă

# Verificați că utilizatorii nu pot modifica hook-urile de sistem
sudo chown root:root /etc/windsurf/hooks.json
sudo chmod 644 /etc/windsurf/hooks.json

Important: Hook-urile la nivel de sistem sunt administrate în întregime de echipa dvs. IT sau de securitate. Windsurf nu distribuie și nu gestionează fișiere în locații la nivel de sistem. Asigurați-vă că echipele interne se ocupă de distribuire, actualizări și conformitate în acord cu politicile organizației dvs.

Hook-uri de workspace pentru proiecte de echipă

Pentru convenții specifice fiecărui proiect, echipele pot utiliza hook-uri la nivel de workspace în sistemul de control al versiunilor:

# Adăugați în repository-ul dvs.
.windsurf/
├── hooks.json
└── scripts/
    └── format-check.py

# Commit în git
git add .windsurf/
git commit -m "Adăugați hook-uri de workspace pentru formatarea codului"

Acest lucru permite echipelor să standardizeze practicile de dezvoltare. Asigurați-vă că păstrați politicile critice pentru securitate la nivel de sistem și că nu introduceți informații sensibile în sistemul de control al versiunilor.

Resurse suplimentare

Integrare MCP: Aflați mai multe despre Model Context Protocol în Windsurf
Fluxuri de lucru: Descoperiți cum să combinați hooks cu Cascade Workflows
Analytics: Monitorizați utilizarea Cascade cu Analytics pentru echipă

Editor

Cascade

Conturi

Conștientizare a contextului

Depanare

Securitate

​Ce puteți construi

​Cum funcționează hook-urile

​Configurare

​La nivel de sistem

​La nivel de utilizator

​La nivel de workspace

​Structură de bază

​Opțiuni de configurare

​Evenimente hook

​Structura comună a inputului

​pre_read_code

​post_read_code

​pre_write_code

​post_write_code

​pre_run_command

​post_run_command

​pre_mcp_tool_use

​post_mcp_tool_use

​Coduri de ieșire

​Exemple de scenarii de utilizare

​Înregistrarea tuturor acțiunilor Cascade

​Restricționarea accesului la fișiere

​Blocarea comenzilor periculoase

​Rularea formatarelor de cod după modificări

​Recomandări de bune practici

​Securitate

​Considerații privind performanța

​Gestionarea erorilor

​Testarea hook-urilor

​Distribuție Enterprise

​Metode de implementare

​Verificare și auditare

​Hook-uri de workspace pentru proiecte de echipă

​Resurse suplimentare

Ce puteți construi

Cum funcționează hook-urile

Configurare

La nivel de sistem

La nivel de utilizator

La nivel de workspace

Structură de bază

Opțiuni de configurare

Evenimente hook

Structura comună a inputului

pre_read_code

post_read_code

pre_write_code

post_write_code

pre_run_command

post_run_command

pre_mcp_tool_use

post_mcp_tool_use

Coduri de ieșire

Exemple de scenarii de utilizare

Înregistrarea tuturor acțiunilor Cascade

Restricționarea accesului la fișiere

Blocarea comenzilor periculoase

Rularea formatarelor de cod după modificări

Recomandări de bune practici

Securitate

Considerații privind performanța

Gestionarea erorilor

Testarea hook-urilor

Distribuție Enterprise

Metode de implementare

Verificare și auditare

Hook-uri de workspace pentru proiecte de echipă

Resurse suplimentare