> ## Documentation Index > Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt > Use this file to discover all available pages before exploring further. # Cascade Hooks > Executați comenzi shell personalizate în momente cheie din fluxul de lucru al Cascade pentru jurnalizare, controale de securitate, validare și guvernanță enterprise, folosind hooks de tip pre și post. 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. 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, comandă executată, prompt de utilizator sau răspuns Cascade, pentru conformitate și analiză a utilizării * **Controale de securitate**: Împiedicați Cascade să acceseze fișiere sensibile, să ruleze comenzi periculoase sau să proceseze prompturi care încalcă politicile * **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: 1. **Primește context** (detalii despre acțiunea executată) prin JSON ca intrare standard 2. **Execută scriptul dvs.** – Python, Bash, Node.js sau orice executabil 3. **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. Echipele Enterprise pot, de asemenea, să configureze hook-uri prin intermediul [dashboard-ului din cloud](#cloud-dashboard-configuration), fără a fi nevoie să gestioneze fișiere locale. * **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. * **Windsurf IDE**: `~/.codeium/windsurf/hooks.json` * **JetBrains Plugin**: `~/.codeium/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: ```json theme={null} { "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. | **Despre parametrul `working_directory`:** * În workspace‑urile cu mai multe repo‑uri, valoarea implicită este rădăcina repo‑ului la care lucrați în prezent * Căile relative sunt rezolvate pornind de la locația implicită (rădăcina workspace‑ului sau a repo‑ului) * Căile absolute sunt acceptate * Utilizarea lui `~` pentru extinderea la directorul home nu este acceptată
## Evenimente hook
Cascade oferă douăsprezece 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ă douăsprezece 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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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**: ```json theme={null} { "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" } } ```
### pre\_user\_prompt
Declanșat **înainte ca** Cascade să proceseze textul promptului unui utilizator. Acest hook poate bloca acțiunea dacă se încheie cu codul 2. **Cazuri de utilizare**: Înregistrarea în log a tuturor prompturilor utilizatorilor pentru auditare, blocarea prompturilor potențial dăunătoare sau care încalcă politicile **Input JSON**: ```json theme={null} { "agent_action_name": "pre_user_prompt", "tool_info": { "user_prompt": "can you run the echo hello command" } } ``` Opțiunea de configurare `show_output` nu se aplică acestui hook.
### post\_cascade\_response
Declanșat asincron **după ce** Cascade finalizează un răspuns la promptul unui utilizator. Acest hook primește întregul răspuns Cascade de la ultima intrare a utilizatorului. **Cazuri de utilizare**: Înregistrați toate răspunsurile Cascade pentru audit, analizați tiparele de răspuns, trimiteți răspunsurile către sisteme externe pentru verificarea conformității **Input JSON**: ```json theme={null} { "agent_action_name": "post_cascade_response", "tool_info": { "response": "### Răspuns Planificator\n\nVă voi ajuta să creați acel fișier.\n\n*Fișier creat `/path/to/file.py`*\n\n### Răspuns Planificator\n\nFișierul a fost creat cu succes." } } ``` Câmpul `response` conține conținutul în format markdown al răspunsului generat de Cascade de la ultima intrare a utilizatorului. Acesta include răspunsurile planificatorului, acțiunile instrumentelor (citiri de fișiere, scrieri, comenzi) și orice alți pași pe care i-a efectuat Cascade. Include și informații despre [regulile](/ro/windsurf/cascade/memories-and-rules) care au fost declanșate. Consultați exemplul [Tracking Triggered Rules](#tracking-triggered-rules) pentru a vedea cum să interpretați utilizarea regulilor. Opțiunea de configurare `show_output` nu se aplică acestui hook. Conținutul `response` este derivat din date privind traiectoria și poate conține informații sensibile din codul sau conversațiile dvs. Tratați aceste date în conformitate cu politicile de securitate și confidențialitate ale organizației dvs.
### post\_cascade\_response\_with\_transcript
Declanșat asincron **după** ce Cascade finalizează un răspuns la promptul unui utilizator, similar cu `post_cascade_response`. În loc să ofere un rezumat markdown direct în conversație, acest hook scrie transcrierea completă a conversației (începând de la debutul conversației) într-un fișier JSONL local și furnizează calea către fișier. **Cazuri de utilizare**: jurnalizare pentru audit și conformitate la nivel Enterprise, urmărirea contribuțiilor generate de AI, trimiterea transcrierilor către instrumente externe de observabilitate sau Analytics **Input JSON**: ```json theme={null} { "agent_action_name": "post_cascade_response_with_transcript", "tool_info": { "transcript_path": "/Users/yourname/.windsurf/transcripts/{trajectory_id}.jsonl" } } ``` `transcript_path` indică către un fișier [JSONL](https://jsonlines.org/) la `~/.windsurf/transcripts/{trajectory_id}.jsonl`. Fiecare linie este un obiect JSON care reprezintă un singur pas în conversație, cu câmpurile `type` și `status`, plus date specifice pasului. De exemplu: ```jsonl theme={null} {"status":"done","type":"user_input","user_input":{"rules_applied":{"always_on":["my-rule.md"]},"user_response":"create a hello world file"}} {"planner_response":{"response":"I'll create a hello world file for you."},"status":"done","type":"planner_response"} {"code_action":{"new_content":"print('hello world')\n","path":"/path/to/file.py"},"status":"done","type":"code_action"} {"planner_response":{"response":"I created the file for you."},"status":"done","type":"planner_response"} ``` Transcriptul include date detaliate, deținute de client, precum conținutul fișierelor, ieșiri ale comenzilor, argumente ale instrumentelor, rezultate de căutare și [reguli](/ro/windsurf/cascade/memories-and-rules) care au fost aplicate. Vă rugăm să rețineți că structura exactă a fiecărui pas se poate schimba în versiunile viitoare, așa că este indicat să construiți orice componente care consumă hook-uri astfel încât să fie rezistente la schimbări. Fișierele de transcript sunt scrise cu permisiuni `0600`. Windsurf limitează automat directorul de transcripturi la 100 de fișiere, ștergându-le pe cele mai vechi în funcție de timpul ultimei modificări. Opțiunea de configurare `show_output` nu se aplică acestui hook. Acest tabel arată principalele diferențe dintre hook-urile `post_cascade_response` și `post_cascade_response_with_transcript`: | | `post_cascade_response` | `post_cascade_response_with_transcript` | | -------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- | | **Sferă de date** | Doar pașii de la ultima intrare a utilizatorului | Întreaga conversație de la început | | **Format** | Rezumat în Markdown în `tool_info.response` | Fișier JSONL structurat la `tool_info.transcript_path` | | **Nivel de detaliu** | Rezumat condensat, ușor de citit pentru oameni | Date detaliate, procesabile de mașini (conținut de fișiere, ieșiri de comenzi etc.) | | **Mod de livrare** | Inline prin stdin JSON | Fișier pe disc (`~/.windsurf/transcripts/`) | Fișierele de transcript vor conține informații sensibile din codul dumneavoastră, inclusiv conținutul fișierelor, ieșiri de comenzi și istoricul conversațiilor. Gestionați aceste fișiere în conformitate cu politicile de securitate și confidențialitate ale organizației dumneavoastră.
### post\_setup\_worktree
Declanșat **după** ce un nou [git worktree](./worktrees) este creat și configurat. Hook-ul este executat în noul director **worktree**. **Cazuri de utilizare**: Copiați fișierele `.env` sau alte fișiere neurmărite în worktree, instalați dependențele, rulați scripturi de configurare **Variabile de mediu**: | Variabilă | Descriere | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `$ROOT_WORKSPACE_PATH` | Calea absolută către workspace-ul original. Utilizați-o pentru a accesa fișiere sau pentru a rula comenzi relativ la repository-ul original. | **JSON de intrare**: ```json theme={null} { "agent_action_name": "post_setup_worktree", "tool_info": { "worktree_path": "/Users/me/.windsurf/worktrees/my-repo/abmy-repo-c123", "root_workspace_path": "/Users/me/projects/my-repo" } } ```
## 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\_user\_prompt, 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**: ```json theme={null} { "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 } ], "post_cascade_response": [ { "command": "python3 /Users/yourname/hooks/log_input.py" } ] } } ``` **Script** (`log_input.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json def main(): # Read the JSON data from stdin input_data = sys.stdin.read() # Parse the JSON try: data = json.loads(input_data) # Write formatted JSON to file 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**: ```json theme={null} { "hooks": { "pre_read_code": [ { "command": "python3 /Users/yourname/hooks/block_read_access.py", "show_output": true } ] } } ``` **Script** (`block_read_access.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json ALLOWED_PREFIX = "/Users/yourname/my-project/" def main(): # Read the JSON data from stdin input_data = sys.stdin.read() # Parse the JSON 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) # Exit code 2 blocks the action print(f"Access granted: {file_path}", file=sys.stdout) except json.JSONDecodeError as e: print(f"Error parsing 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ă execute comenzi potențial dăunătoare. **Config**: ```json theme={null} { "hooks": { "pre_run_command": [ { "command": "python3 /Users/yourname/hooks/block_dangerous_commands.py", "show_output": true } ] } } ``` **Script** (`block_dangerous_commands.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json DANGEROUS_COMMANDS = ["rm -rf", "sudo rm", "format", "del /f"] def main(): # Read the JSON data from stdin input_data = sys.stdin.read() # Parse the JSON 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) # Exit code 2 blocks the command print(f"Command approved: {command}", file=sys.stdout) except json.JSONDecodeError as e: print(f"Error parsing JSON: {e}", file=sys.stderr) sys.exit(1) if __name__ == "__main__": main() ``` Acest hook scanează comenzile pentru tipare periculoase și le blochează înainte de execuție.
### Blocarea prompturilor care încalcă politicile
Împiedicați utilizatorii să trimită prompturi care încalcă politicile organizației. **Config**: ```json theme={null} { "hooks": { "pre_user_prompt": [ { "command": "python3 /Users/yourname/hooks/block_bad_prompts.py" } ] } } ``` **Scriptul** (`block_bad_prompts.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json BLOCKED_PATTERNS = [ "something dangerous", "bypass security", "ignore previous instructions" ] 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_user_prompt": tool_info = data.get("tool_info", {}) user_prompt = tool_info.get("user_prompt", "").lower() for pattern in BLOCKED_PATTERNS: if pattern in user_prompt: print(f"Prompt blocat: Conține conținut interzis. Utilizatorul nu poate solicita agentului să efectueze acțiuni nepermise.", file=sys.stderr) sys.exit(2) # Codul de ieșire 2 blochează prompt-ul except json.JSONDecodeError as e: print(f"Eroare la analizarea JSON: {e}", file=sys.stderr) sys.exit(1) if __name__ == "__main__": main() ``` Acest hook examinează prompturile utilizatorului înainte ca acestea să fie procesate și blochează orice prompt care conține tipare interzise. Atunci când un prompt este blocat, utilizatorul vede un mesaj de eroare în interfața Cascade.
### Înregistrarea răspunsurilor Cascade
Urmăriți toate răspunsurile Cascade pentru audit de conformitate sau analiză. **Config**: ```json theme={null} { "hooks": { "post_cascade_response": [ { "command": "python3 /Users/yourname/hooks/log_cascade_response.py" } ] } } ``` **Script** (`log_cascade_response.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json from datetime import datetime 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") == "post_cascade_response": tool_info = data.get("tool_info", {}) cascade_response = tool_info.get("response", "") trajectory_id = data.get("trajectory_id", "unknown") timestamp = data.get("timestamp", datetime.now().isoformat()) # Înregistrează în fișier with open("/Users/yourname/hooks/cascade_responses.log", "a") as f: f.write(f"\n{'='*80}\n") f.write(f"Timestamp: {timestamp}\n") f.write(f"Trajectory ID: {trajectory_id}\n") f.write(f"Response:\n{cascade_response}\n") print(f"Logged Cascade response for trajectory {trajectory_id}") except json.JSONDecodeError as e: print(f"Error parsing JSON: {e}", file=sys.stderr) sys.exit(1) if __name__ == "__main__": main() ``` Acest hook înregistrează fiecare răspuns Cascade într-un fișier, creând un istoric de audit al întregului conținut generat de AI. Puteți extinde acest comportament pentru a trimite date către sisteme externe de jurnale, baze de date sau platforme de conformitate.
### Urmărirea regulilor declanșate
Urmăriți care [reguli](/ro/windsurf/cascade/memories-and-rules) au fost aplicate în timpul interacțiunilor cu Cascade, pentru observabilitate și metrici. **Configurație**: ```json theme={null} { "hooks": { "post_cascade_response": [ { "command": "python3 /Users/yourname/hooks/track_rules.py" } ] } } ``` **Script** (`track_rules.py`): ```python theme={null} #!/usr/bin/env python3 import sys import json import re from datetime import datetime def extract_triggered_rules(response: str) -> dict: """ Analizează regulile declanșate din răspunsul Cascade. Regulile apar ca: - (Rule-Type) Triggered Rule: rule-filename.md """ pattern = r"- \(([^)]+)\) Triggered Rule: (.+?)(?:\s*$)" rules = {} for match in re.finditer(pattern, response, re.MULTILINE): rule_type, rule_name = match.groups() if rule_type not in rules: rules[rule_type] = [] rules[rule_type].append(rule_name) return rules def main(): input_data = sys.stdin.read() try: data = json.loads(input_data) if data.get("agent_action_name") == "post_cascade_response": response = data.get("tool_info", {}).get("response", "") trajectory_id = data.get("trajectory_id", "unknown") timestamp = data.get("timestamp", datetime.now().isoformat()) rules = extract_triggered_rules(response) total_rules = sum(len(v) for v in rules.values()) # Log to file with open("/Users/yourname/hooks/rules_usage.log", "a") as f: f.write(f"\n{'='*60}\n") f.write(f"Timestamp: {timestamp}\n") f.write(f"Trajectory: {trajectory_id}\n") f.write(f"Total rules triggered: {total_rules}\n") for rule_type, rule_list in rules.items(): if rule_list: f.write(f" {rule_type}: {', '.join(rule_list)}\n") print(f"Tracked {total_rules} triggered rules") except json.JSONDecodeError as e: print(f"Error parsing JSON: {e}", file=sys.stderr) sys.exit(1) if __name__ == "__main__": main() ``` **Tipuri de reguli:** * `Always On` - Reguli care sunt incluse întotdeauna * `Model Decision` - Reguli ale căror descrieri au fost afișate modelului AI pentru aplicare condiționată * `Manual` - Reguli menționate explicit cu @ în introducerea utilizatorului * `Global` - Reguli globale din `global_rules.md` * `Glob` - Reguli declanșate de accesarea fișierelor care se potrivesc cu șabloane glob Aceasta urmărește ce reguli au fost *prezentate* modelului AI sau *declanșate* de accesarea fișierelor, dar nu indică dacă modelul AI a *respectat* efectiv o regulă. Regulile care au fost deja afișate recent în conversație sunt deduplicate și este posibil să nu mai apară din nou decât mai târziu.
### Rularea formatarelor de cod după modificări
Formatați automat fișierele de cod după ce Cascade le actualizează. **Config**: ```json theme={null} { "hooks": { "post_write_code": [ { "command": "bash /Users/yourname/hooks/format_code.sh", "show_output": false } ] } } ``` **Script** (`format_code.sh`): ```bash theme={null} #!/bin/bash # Read JSON from stdin input=$(cat) # Extract file path using jq file_path=$(echo "$input" | jq -r '.tool_info.file_path') # Format based on file extension 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 "Formatted JS/TS file: $file_path" elif [[ "$file_path" == *.go ]]; then gofmt -w "$file_path" 2>&1 echo "Formatted Go file: $file_path" fi exit 0 ``` Acest hook rulează automat formatorul adecvat în funcție de tipul fișierului, după fiecare modificare.
### Configurarea worktree-urilor
Copiați fișierele de mediu și instalați dependențele la crearea unui nou worktree. **Config** (în `.windsurf/hooks.json`): ```json theme={null} { "hooks": { "post_setup_worktree": [ { "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh", "show_output": true } ] } } ``` **Script** (`hooks/setup_worktree.sh`): ```bash theme={null} #!/bin/bash # Copiați fișierele de mediu din workspace-ul original if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then cp "$ROOT_WORKSPACE_PATH/.env" .env echo "Fișierul .env a fost copiat" fi if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local echo "Fișierul .env.local a fost copiat" fi # Instalați dependențele if [ -f "package.json" ]; then npm install echo "Dependențele npm au fost instalate" fi exit 0 ``` Acest hook se asigură că fiecare worktree are în mod automat configurată configurația de mediu necesară și dependențele instalate.
## 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
1. **Începeți cu jurnalizarea**: Implementați mai întâi un hook simplu de jurnalizare pentru a înțelege fluxul de date. 2. **Folosiți `show_output: true`**: Activați afișarea rezultatelor în timpul dezvoltării pentru a vedea ce fac hook-urile. 3. **Testați comportamentul de blocare**: Verificați că valoarea de ieșire 2 (exit code 2) blochează corect acțiunile în pre-hooks. 4. **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 două metode de distribuție Enterprise: 1. **Cloud Dashboard** – Configurați hooks în Team Settings din dashboard-ul Windsurf 2. **System-Level Files** – Implementați hooks prin MDM sau instrumente de gestionare a configurațiilor Ambele metode pot fi utilizate împreună — hooks din toate sursele sunt combinate și executate în ordine.
### Configurarea dashboard-ului în cloud
Administratorii de echipă pot configura Cascade Hooks direct din dashboard-ul Windsurf. **Cerințe:** * Plan Enterprise * Permisiunea `TEAM_SETTINGS_UPDATE` **Pentru configurare:** 1. Navigați la **Team Settings** în dashboard-ul Windsurf 2. Găsiți secțiunea **Cascade Hooks** 3. Introduceți configurația pentru hooks, în format JSON 4. Salvați modificările Hook-urile configurate din dashboard sunt distribuite automat tuturor membrilor echipei și sunt încărcate la pornirea Windsurf. Hook-urile configurate în cloud sunt încărcate mai întâi, urmate de hook-urile la nivel de sistem, la nivel de utilizator și la nivel de workspace. Atunci când mai multe configurații de echipă sunt îmbinate, hook-urile sunt combinate pentru fiecare acțiune, în loc să fie suprascrise. Aceasta înseamnă că hook-urile din toate configurațiile de echipă aplicabile vor rula împreună.
### Implementare fișiere la nivel de sistem
Pentru organizațiile care preferă configurarea bazată pe fișiere sau care au nevoie ca hook-urile să funcționeze offline, 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). Hook-urile la nivel de sistem au prioritate față de hook-urile de utilizator și de workspace și nu pot fi dezactivate de utilizatorii finali fără permisiuni de root.
#### MDM și gestionarea configurațiilor
Echipele IT Enterprise pot implementa hook‑uri la nivel de sistem folosind instrumente 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: ```bash theme={null} # Verify system hooks are present 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) # Have a developer trigger the relevant Cascade action # Verify users cannot modify system hooks 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: ```bash theme={null} # 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. Păstrați politicile critice pentru securitate la nivel de cloud sau de sistem și evitați să 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](/ro/windsurf/cascade/mcp) * **Workflows**: Descoperiți cum să combinați hooks cu [Cascade Workflows](/ro/windsurf/cascade/workflows) * **Analytics**: Urmăriți utilizarea Cascade cu [Analytics pentru echipă](/ro/windsurf/accounts/analytics)