Acerca de los ganchos
Los enlaces permiten ejecutar comandos de shell personalizados en puntos estratégicos del flujo de trabajo de un agente, como cuando se inicia o finaliza una sesión del agente, o antes y después de que se escriba un mensaje o se llame a una herramienta.
Los enlaces reciben información detallada sobre las acciones del agente a través de la entrada JSON, lo que habilita la automatización con reconocimiento del contexto. Por ejemplo, puede usar ganchos para:
- Aprobar o denegar ejecuciones de herramientas mediante programación.
- Use características de seguridad integradas, como el examen de secretos, para evitar pérdidas de credenciales.
- Implemente reglas de validación personalizadas y registro de auditoría para el cumplimiento.
Los agentes de Copilot admiten enlaces almacenados en archivos JSON en su repositorio, en .github/hooks/*.json.
Los ganchos están disponibles para usar con:
- Agente de codificación de Copilot en GitHub
- CLI de GitHub Copilot en terminal
Tipos de enlaces
Están disponibles los siguientes tipos de hooks:
-
**sessionStart**: se ejecuta cuando comienza una nueva sesión del agente o al reanudar una sesión existente. Se puede usar para inicializar entornos, iniciar sesión de registro para auditar, validar el estado del proyecto y configurar recursos temporales. -
**sessionEnd**: se ejecuta cuando la sesión del agente concluye o se termina. Se puede usar para limpiar recursos temporales, generar y archivar registros e informes de sesión, o enviar notificaciones sobre la finalización de la sesión. -
**userPromptSubmitted**: se ejecuta cuando el usuario envía un mensaje al agente. Se puede usar para registrar las solicitudes de usuario para la auditoría y el análisis de uso. -
**preToolUse**: ejecutado antes de que el agente use cualquier herramienta (como `bash`, `edit`, `view`). Este es el enlace más eficaz, ya que puede **aprobar o denegar ejecuciones de herramientas**. Use este enlace para bloquear comandos peligrosos, aplicar directivas de seguridad y estándares de codificación, requerir aprobación para operaciones confidenciales o el uso de herramientas de registro para el cumplimiento. -
**postToolUse**: se ejecuta después de que una herramienta complete la ejecución (ya sea correcta o con errores). Se puede usar para registrar los resultados de la ejecución, realizar un seguimiento de las estadísticas de uso, generar seguimientos de auditoría, supervisar las métricas de rendimiento y enviar alertas de error. -
**agentStop**: se ejecuta cuando el agente principal ha terminado de responder a la solicitud. -
**subagentStop**: se ejecuta cuando se completa un subagente, antes de devolver los resultados al agente primario. -
**errorOccurred**: se ejecuta cuando se produce un error durante la ejecución del agente. Se puede usar para registrar errores para depurar, enviar notificaciones, realizar un seguimiento de los patrones de error y generar informes.
Para ver una referencia completa de tipos de enlace con casos de uso de ejemplo, procedimientos recomendados y patrones avanzados, consulte Configuración de hooks.
Formato de configuración de gancho
Configura los hooks usando un formato JSON especial. El JSON debe contener un version campo con un valor de 1 y un hooks objeto que contenga matrices de definiciones de enlace.
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": "string (optional)",
"powershell": "string (optional)",
"cwd": "string (optional)",
"env": { "KEY": "value" },
"timeoutSec": 30
}
],
}
}
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": "string (optional)",
"powershell": "string (optional)",
"cwd": "string (optional)",
"env": { "KEY": "value" },
"timeoutSec": 30
}
],
}
}
El objeto de enlace puede contener las siguientes claves:
| Propiedad | Obligatorio | Description |
|---|---|---|
type | Sí | Debe ser "command" |
bash | Sí (en sistemas Unix) | Ruta de acceso al script de Bash que se va a ejecutar |
powershell | Sí (en Windows) | Ruta de acceso al script de PowerShell que se va a ejecutar |
cwd | No | Directorio de trabajo para el script (relativo a la raíz del repositorio) |
env | No | Variables de entorno adicionales que se combinan con el entorno existente |
timeoutSec | No | Tiempo máximo de ejecución en segundos (valor predeterminado: 30) |
Archivo de configuración de enlace de ejemplo
Este es un archivo de configuración de ejemplo que reside en ~/.github/hooks/project-hooks.json un repositorio.
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": "echo \"Session started: $(date)\" >> logs/session.log",
"powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
"cwd": ".",
"timeoutSec": 10
}
],
"userPromptSubmitted": [
{
"type": "command",
"bash": "./scripts/log-prompt.sh",
"powershell": "./scripts/log-prompt.ps1",
"cwd": "scripts",
"env": {
"LOG_LEVEL": "INFO"
}
}
],
"preToolUse": [
{
"type": "command",
"bash": "./scripts/security-check.sh",
"powershell": "./scripts/security-check.ps1",
"cwd": "scripts",
"timeoutSec": 15
},
{
"type": "command",
"bash": "./scripts/log-tool-use.sh",
"powershell": "./scripts/log-tool-use.ps1",
"cwd": "scripts"
}
],
"postToolUse": [
{
"type": "command",
"bash": "cat >> logs/tool-results.jsonl",
"powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
}
],
"sessionEnd": [
{
"type": "command",
"bash": "./scripts/cleanup.sh",
"powershell": "./scripts/cleanup.ps1",
"cwd": "scripts",
"timeoutSec": 60
}
]
}
}
{
"version": 1,
"hooks": {
"sessionStart": [
{
"type": "command",
"bash": "echo \"Session started: $(date)\" >> logs/session.log",
"powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
"cwd": ".",
"timeoutSec": 10
}
],
"userPromptSubmitted": [
{
"type": "command",
"bash": "./scripts/log-prompt.sh",
"powershell": "./scripts/log-prompt.ps1",
"cwd": "scripts",
"env": {
"LOG_LEVEL": "INFO"
}
}
],
"preToolUse": [
{
"type": "command",
"bash": "./scripts/security-check.sh",
"powershell": "./scripts/security-check.ps1",
"cwd": "scripts",
"timeoutSec": 15
},
{
"type": "command",
"bash": "./scripts/log-tool-use.sh",
"powershell": "./scripts/log-tool-use.ps1",
"cwd": "scripts"
}
],
"postToolUse": [
{
"type": "command",
"bash": "cat >> logs/tool-results.jsonl",
"powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
}
],
"sessionEnd": [
{
"type": "command",
"bash": "./scripts/cleanup.sh",
"powershell": "./scripts/cleanup.ps1",
"cwd": "scripts",
"timeoutSec": 60
}
]
}
}
Consideraciones sobre el rendimiento
Los ganchos operan sincrónicamente y bloquean la ejecución del agente. Para garantizar una experiencia con capacidad de respuesta, tenga en cuenta las siguientes consideraciones:
-
**Minimizar el tiempo de ejecución**: mantenga el tiempo de ejecución del enlace en menos de 5 segundos cuando sea posible. -
**Optimizar el registro**: use el registro asincrónico, como anexar a archivos, en lugar de E/S sincrónica. -
**Usar el procesamiento en segundo plano**: para operaciones costosas, considere la posibilidad de procesar en segundo plano. -
**Resultados de caché: almacene en caché** cálculos costosos cuando sea posible.
Consideraciones de seguridad
Para garantizar que la seguridad se mantiene al usar enlaces, tenga en cuenta las siguientes consideraciones:
-
**Valide y corrija siempre la entrada procesada por enlaces**. La entrada que no es de confianza podría provocar un comportamiento inesperado. -
**Utilice el escape adecuado del shell al construir comandos**. Esto evita vulnerabilidades de inyección de comandos. -
**Nunca registre datos confidenciales, como tokens o contraseñas**. -
**Asegúrese de que los scripts de gancho y los logs tengan los permisos adecuados**. -
**Tenga cuidado con los enlaces que realizan llamadas de red externas**. Estos pueden introducir latencia, errores o exponer datos a terceros. -
**Establezca los tiempos de espera adecuados para evitar el agotamiento de recursos**. Los enlaces de ejecución prolongada pueden bloquear la ejecución del agente y degradar el rendimiento.
Pasos siguientes
Para empezar a crear enlaces, consulte Uso de enlaces con agentes de GitHub Copilot.