Detección automática de dependencias de habilidades y notificaciones transparentes al usuario - Skill Dependency Auto-Detection and User-Transparent Notifications

1. blackout de contexto de habilidades en nuevas sesiones

Cuando los usuarios inician una nueva sesión y preguntan sobre funcionalidad que existe como una habilidad, el sistema responde negativamente a pesar de tener capacidades disponibles.

User: "你能帮我读备忘录吗？" (Can you help me read notes?)
Assistant: "抱歉，我做不到。" (Sorry, I can't do that.)
  ↑ Actually exists: `apple-notes` and `bear-notes` skills installed

2. Fallos silenciosos de dependencias

Las habilidades aparecen funcionales en /skill list pero fallan silenciosamente cuando se invocan debido a dependencias CLI externas faltantes.

$ openclaw skill list
✔ apple-notes    - Read and search Apple Notes
✔ bear-notes     - Query Bear database
✔ himalaya       - Email client
✔ obsidian       - Vault management

$ openclaw skill invoke apple-notes search --query "meeting"
Error: Command not found: memo
  ↑ Dependency `memo` not installed, no notification provided

3. Inventario de dependencias ausente

Los usuarios no tienen visibilidad sobre qué herramientas externas deben estar instaladas para que las habilidades funcionen.

# System reports skill as "installed" but doesn't reveal:
# - Missing CLI dependencies
# - Installation instructions
# - Current availability status

$ openclaw skill status
┌──────────────┬────────────┬────────────┐
│ Skill        │ Status     │ Dependencies│
├──────────────┼────────────┼────────────┤
│ apple-notes  │ Installed  │ ?????       │  ← No visibility
│ bear-notes   │ Installed  │ ?????       │  ← No visibility
│ gh-issues    │ Installed  │ ?????       │  ← No visibility
└──────────────┴────────────┴────────────┘

4. Descubrimiento incompleto de habilidades

La inyección de contexto del sistema al inicio solo incluye un subconjunto de habilidades disponibles, causando fallos de enrutamiento inteligente.

# New session context shows:
Available capabilities: [web-search, file-read, code-explain]
  ↑ Missing: apple-notes, bear-notes, himalaya, obsidian, spotify-player...

# User cannot discover skills even when asking directly:
User: "What can you do?"
Assistant: Lists only 3-4 capabilities ← 51 skills invisible

Análisis arquitectónico

El sistema de habilidades de OpenClaw presenta una brecha de visibilidad entre las habilidades instaladas y la disponibilidad en tiempo de ejecución debido a varias deficiencias arquitectónicas:

1. Modelo de inyección de contexto perezoso (lazy)

El mecanismo de carga de habilidades utiliza una estrategia de inyección de contexto parcial durante la inicialización de la sesión:

// Current behavior in session_manager.rs
async fn initialize_session(&self, session_id: &str) -> Result<()> {
    let skills = self.skill_registry.get_all(); // Returns all skill metadata
    
    // PROBLEM: Only injects first N skills based on context window limit
    let context_skills = skills.iter()
        .take(MAX_CONTEXT_SKILLS) // Likely hardcoded to ~10
        .collect();
    
    self.context_manager.inject(context_skills);
    // 45+ skills silently excluded from new session context
}

Impacto: Las habilidades como apple-notes, bear-notes, himalaya se cargan pero nunca se exponen al contexto LLM, haciéndolas invisibles para el descubrimiento conversacional.

2. Capa de declaración de dependencias ausente

Los manifiestos de habilidades (.skill.yaml o equivalente) carecen de un campo estandarizado dependencies:

# Current skill manifest structure (assumed)
name: apple-notes
version: 1.0.0
description: Read and search Apple Notes
entrypoint: apple-notes.js
# MISSING: No dependency declaration format

# Expected structure not implemented:
# dependencies:
#   - command: memo
#     type: cli
#     install: "brew tap antoniorodr/memo && brew install antoniorodr/memo/memo"
#   - command: sqlite3
#     type: system

3. Sin verificación de dependencias en tiempo de ejecución

El pipeline de invocación de habilidades omite la validación de dependencias:

// Current invocation flow
async fn invoke_skill(&self, skill_name: &str, args: Args) -> Result {
    let skill = self.skill_registry.get(skill_name)?;
    
    // BUG: No dependency check before execution
    // Should verify: which memo, which sqlite3, etc.
    
    let output = skill.execute(args).await?;
    // Fails at execution with cryptic "command not found"
}

4. Monitoreo de salud desconectado

No existe una verificación de salud unificada que agregue el estado de las habilidades con la disponibilidad de dependencias:

# Skills, dependencies, and availability exist in separate domains:
skill_registry.yaml    ← Skill metadata (no dependencies)
system PATH            ← CLI tool availability (not queried)
user configuration     ← Custom tool paths (not validated)

# No reconciliation layer exists to correlate these

Diagrama de secuencia de fallos

User Query: "读取备忘录"
        │
        ▼
┌─────────────────────────┐
│ Session Context Check   │
│ (Only ~10 skills loaded)│
│ ❌ apple-notes excluded │
│ ❌ bear-notes excluded  │
└───────────┬─────────────┘
            │
            ▼
    LLM Response: "做不到"
    
    ─────────────────────────────
    
    [If skill somehow triggered]
    
        │
        ▼
┌─────────────────────────┐
│ Skill Invocation        │
│ (No dependency check)  │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ External CLI Execution  │
│ ❌ memo not found       │
│ ❌ grizzly not found    │
└───────────┬─────────────┘
            │
            ▼
    Silent failure or cryptic error

Fase 1: Definir esquema de dependencias

Extender los archivos de manifiesto de habilidades con una declaración estandarizada de dependencias:

# skills/apple-notes/.skill.yaml
name: apple-notes
version: 1.2.0
description: Read and search Apple Notes via memo CLI
author: openclaw-team

dependencies:
  - command: memo
    type: cli
    required: true
    install:
      macos: "brew tap antoniorodr/memo && brew install antoniorodr/memo/memo"
      linux: "cargo install memo-cli"
    verification: "memo --version"

  - command: sqlite3
    type: system
    required: true
    install:
      macos: "brew install sqlite3"
      linux: "apt install sqlite3"
    verification: "sqlite3 --version"

capabilities:
  - search_notes
  - read_note
  - list_notebooks

Fase 2: Implementar escáner de dependencias

Crear src/skill/dependency_scanner.rs:

use std::collections::HashMap;
use std::process::Command;

#[derive(Debug, Clone)]
pub struct DependencyStatus {
    pub command: String,
    pub available: bool,
    pub path: Option,
    pub version: Option,
    pub install_command: Option,
}

pub struct DependencyScanner {
    platform: Platform,
}

impl DependencyScanner {
    pub fn new() -> Self {
        Self {
            platform: Platform::detect(),
        }
    }

    /// Scan all skills and check dependency availability
    pub fn scan_skill_dependencies(&self, skills: &[Skill]) -> SkillHealthReport {
        let mut report = SkillHealthReport::default();

        for skill in skills {
            let dep_statuses: Vec = skill
                .dependencies
                .iter()
                .map(|dep| self.check_dependency(dep))
                .collect();

            let all_available = dep_statuses.iter().all(|d| d.available);
            
            report.skills.push(SkillHealthStatus {
                skill_name: skill.name.clone(),
                dependencies: dep_statuses,
                usable: all_available,
                reason: if !all_available {
                    Some(Self::generate_missing_reason(&skill.dependencies))
                } else {
                    None
                },
            });
        }

        report
    }

    fn check_dependency(&self, dep: &Dependency) -> DependencyStatus {
        let which_output = Command::new("which")
            .arg(&dep.command)
            .output();

        match which_output {
            Ok(output) if output.status.success() => {
                let path = String::from_utf8_lossy(&output.stdout).trim().to_string();
                let version = self.get_version(&dep.command);
                
                DependencyStatus {
                    command: dep.command.clone(),
                    available: true,
                    path: Some(path),
                    version,
                    install_command: None,
                }
            }
            _ => DependencyStatus {
                command: dep.command.clone(),
                available: false,
                path: None,
                version: None,
                install_command: Some(self.get_install_command(dep)),
            },
        }
    }

    fn get_install_command(&self, dep: &Dependency) -> String {
        dep.install
            .get(&self.platform)
            .cloned()
            .unwrap_or_else(|| format!("Install {} manually", dep.command))
    }

    fn generate_missing_reason(deps: &[Dependency]) -> String {
        let missing: Vec<&str> = deps
            .iter()
            .filter(|d| {
                Command::new("which")
                    .arg(&d.command)
                    .output()
                    .map(|o| !o.status.success())
                    .unwrap_or(true)
            })
            .map(|d| d.command.as_str())
            .collect();

        format!("Missing dependencies: {}", missing.join(", "))
    }
}

Fase 3: Modificar inicialización de sesión

Actualizar src/session/session_manager.rs para incluir el contexto completo de habilidades:

// BEFORE: Limited context injection
const MAX_CONTEXT_SKILLS: usize = 10;

// AFTER: Unlimited skill summary + detailed context on-demand
const MAX_CONTEXT_SKILLS: usize = 100; // Or remove limit

impl SessionManager {
    pub async fn initialize_session(&self, session_id: &str) -> Result<()> {
        let skills = self.skill_registry.get_all();
        
        // Generate skill health report for context injection
        let health_report = self.dependency_scanner.scan_skill_dependencies(&skills);
        
        // Strategy: Inject condensed skill inventory with availability status
        let skill_context = SkillContextSummary {
            total_skills: skills.len(),
            usable_skills: health_report.usable_count(),
            unavailable_skills: health_report.unavailable_skills(),
            detailed_status: health_report.to_context_string(),
        };

        self.context_manager.inject_skill_summary(skill_context);
        
        // Cache health report for on-demand queries
        self.health_cache.insert(session_id.to_string(), health_report);
        
        Ok(())
    }
}

Fase 4: Implementar comando de verificación de salud

Agregar manejador del comando /skill health:

// src/commands/skill_health.rs

pub struct SkillHealthCommand;

impl Command for SkillHealthCommand {
    const NAME: &'static str = "health";
    const DESCRIPTION: &'static str = "Check skill availability and missing dependencies";

    async fn execute(&self, ctx: &CommandContext) -> CommandResult {
        let skills = ctx.skill_registry.get_all();
        let scanner = DependencyScanner::new();
        let report = scanner.scan_skill_dependencies(&skills);

        let output = Self::format_report(&report);
        Ok(CommandOutput::Text(output))
    }
}

impl SkillHealthCommand {
    fn format_report(report: &SkillHealthReport) -> String {
        let mut lines = vec![
            "╔══════════════════════════════════════════════════════════╗".into(),
            "║              OpenClaw Skill Health Report                ║".into(),
            "╚══════════════════════════════════════════════════════════╝".into(),
            format!("Total Skills: {} | Usable: ✅ {} | Unavailable: ⚠️ {}", 
                report.skills.len(),
                report.usable_count(),
                report.unavailable_count()),
            String::new(),
        ];

        for status in &report.skills {
            let icon = if status.usable { "✅" } else { "❌" };
            lines.push(format!("{} {} {}", icon, status.skill_name, 
                status.reason.as_deref().unwrap_or("(all dependencies satisfied)")));
            
            if !status.usable {
                for dep in &status.dependencies {
                    if !dep.available {
                        lines.push(format!("   └── Missing: {} - Install: {}", 
                            dep.command, 
                            dep.install_command.as_deref().unwrap_or("N/A")));
                    }
                }
            }
        }

        lines.join("\n")
    }
}

Fase 5: Agregar detección bajo demanda

Implementar verificación de dependencias durante la invocación de habilidades con error amigable:

// src/skill/invocation_handler.rs

impl InvocationHandler {
    pub async fn invoke(&self, skill_name: &str, args: Args) -> Result {
        let skill = self.skill_registry.get(skill_name)?;
        
        // Check dependencies before execution
        let missing_deps = self.check_dependencies(&skill);
        
        if !missing_deps.is_empty() {
            return Err(SkillError::MissingDependencies {
                skill: skill_name.to_string(),
                dependencies: missing_deps.clone(),
                install_instructions: self.generate_install_help(&missing_deps),
            });
        }

        skill.execute(args).await
    }

    fn generate_install_help(&self, deps: &[Dependency]) -> String {
        let mut instructions = String::from("To enable this skill, install the following:\n\n");
        
        for dep in deps {
            if let Some(cmd) = &dep.install_command {
                instructions.push_str(&format!(
                    "  {}:\n    {}\n\n", 
                    dep.command,
                    cmd.replace("$ ", "").replace("\\", "")
                ));
            }
        }
        
        instructions.push_str("Run `openclaw skill health` for full status.");
        instructions
    }
}

Suite de pruebas de verificación

Ejecutar los siguientes comandos para validar la implementación:

1. Validación del comando de verificación de salud

$ openclaw skill health

╔══════════════════════════════════════════════════════════╗
║              OpenClaw Skill Health Report                ║
╚══════════════════════════════════════════════════════════╝
Total Skills: 55 | Usable: 23 | Unavailable: 32

✅ apple-notes        (all dependencies satisfied)
✅ bear-notes         (all dependencies satisfied)
✅ himalaya           (all dependencies satisfied)
❌ obsidian           Missing: obsidian-cli - Install: cargo install obsidian-cli
❌ spotify-player     Missing: spogo - Install: brew install t位的/spogo
❌ gh-issues          Missing: gh - Install: brew install gh

Código de salida esperado: 0

2. Validación del contexto de nueva sesión

$ openclaw session new --query "你能读取备忘录吗？"

# Injected context should now include:
Available Skills (55 total, 23 usable):
├── apple-notes    ✅ (memo, sqlite3 available)
├── bear-notes     ✅ (grizzly, sqlite3 available)
├── obsidian       ❌ (obsidian-cli missing)
└── ...

Assistant: "我可以帮你读取备忘录！已安装的备忘录工具：
  • apple-notes (需要: memo) ✅
  • bear-notes (需要: grizzly) ✅"

3. Invocación consciente de dependencias

$ openclaw skill invoke apple-notes search --query "meeting"

# Before fix: Silent failure or "command not found"
# After fix: 
✅ Executed successfully via memo CLI
Found 3 notes containing "meeting"

4. Prueba de degradación elegante

$ openclaw skill invoke obsidian search --query "project"

Error: Missing Dependencies for skill 'obsidian'
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The 'obsidian' skill cannot function because required tools are missing:

  ❌ obsidian-cli (required)
    Install: cargo install obsidian-cli

Would you like to install now? [y/N]

5. Verificación de inyección de contexto

$ openclaw debug context --session-id recent

# Should include:
SKILL_INVENTORY:
{
  "total": 55,
  "usable": 23,
  "skills": [
    {"name": "apple-notes", "usable": true, "missing_deps": []},
    {"name": "bear-notes", "usable": true, "missing_deps": []},
    {"name": "obsidian", "usable": false, "missing_deps": ["obsidian-cli"]},
    ...
  ]
}

Lista de verificación de pruebas de regresión

• Prueba A: Las sesiones existentes continúan funcionando sin modificación
• Prueba B: Las habilidades sin declaraciones de dependencias funcionan sin cambios
• Prueba C: El modo offline muestra el estado apropiado de "no se puede verificar"
• Prueba D: Los informes de salud en caché expiran después del TTL configurable
• Prueba E: Las rutas de herramientas personalizadas (vía configuración) se respetan en la resolución de PATH

Trampas específicas del entorno

1. Variabilidad de ruta de Homebrew en macOS

# PROBLEM: Homebrew may not be in PATH for GUI applications
$ which brew
# /opt/homebrew/bin/brew (Apple Silicon)
# /usr/local/bin/brew (Intel)

# CACHED PATH vs ACTUAL PATH during skill execution
$ openclaw skill invoke himalaya --version
Error: himalaya not found
  ↑ Skill runner may use different PATH than shell

Mitigación: Fuente explícitamente Homebrew en el entorno del ejecutor de habilidades:

# In skill runner configuration
env:
  PATH: "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:{{env.PATH}}"

2. Nombres de dependencias según la distribución Linux

# Same tool, different package names:
# Debian/Ubuntu: apt install sqlite3
# Fedora/RHEL:    dnf install sqlite
# Arch:           pacman -S sqlite

# PROBLEM: Generic install instructions fail on wrong distro
install:
  linux: "apt install sqlite3"  # Fails on Fedora

Mitigación: Implementar detección de fallback específica de plataforma:

fn get_sqlite_package() -> &'static str {
    match detect_linux_distro() {
        Distro::Debian | Distro::Ubuntu => "sqlite3",
        Distro::Fedora | Distro::RHEL => "sqlite",
        Distro::Arch => "sqlite",
        _ => "sqlite3",
    }
}

3. Aislamiento de PATH en contenedores Docker

# PROBLEM: Docker containers may have minimal PATH
$ docker run --rm openclaw:latest skill health
❌ Missing: gh (installed on host, not in container)
✅ Missing: memo (correctly detected)

Mitigación: Documentar que la verificación de salud refleja el entorno del contenedor, no el host.

4. Extensiones de ejecutables en Windows

# PROBLEM: Windows tools may need .exe extension
$ which memo    # Returns nothing
$ which memo.exe # Returns C:\tools\memo.exe

# Skills calling external commands fail silently

Mitigación: Implementar reemplazo de which consciente de extensiones para Windows:

fn which_win(command: &str) -> Option {
    let extensions = ["", ".exe", ".cmd", ".bat"];
    for ext in extensions {
        let with_ext = format!("{}{}", command, ext);
        if let Ok(output) = Command::new("where").arg(&with_ext).output() {
            if output.status.success() {
                return Some(String::from_utf8_lossy(&output.stdout).trim().to_string());
            }
        }
    }
    None
}

Escenarios de configuración incorrecta del usuario

5. Detección de dependencias circulares

# PROBLEM: Skill A requires Skill B which requires Skill A
apple-notes → memo → apple-notes (malformed)

# Causes infinite loop in dependency scanner

Mitigación: Implementar detección de ciclos en el escáner:

fn detect_cycles(&self, skill: &Skill, visited: &mut HashSet) -> Result<(), CycleError> {
    if visited.contains(&skill.name) {
        return Err(CycleError(skill.name.clone()));
    }
    visited.insert(skill.name.clone());
    for dep in &skill.dependencies {
        // Recursive check with visited set
    }
    visited.remove(&skill.name);
    Ok(())
}

6. Desajustes de versión de dependencias específicas

# PROBLEM: Skill requires `gh` ≥ 2.0, but `gh` 1.x installed
dependencies:
  - command: gh
    required: true
    min_version: "2.0.0"  # Not currently supported

$ gh --version
gh version 1.9.2  ← Appears "available" but wrong version

Mitigación: Incluir restricciones de versión en el esquema de dependencias (mejora futura).

Problemas de rendimiento

7. Latencia excesiva en verificación de salud

# PROBLEM: Scanning 55 skills × N dependencies = slow startup
$ time openclaw session new
openclaw session new  2.34s user time
  ↑ 1.8s spent on which commands

Mitigación: Implementar escaneo paralelo con almacenamiento en caché:

// Parallel dependency checks
let futures: Vec<_> = deps
    .iter()
    .map(|dep| tokio::task::spawn_blocking(move || which(&dep.command)))
    .collect();

let results = futures::future::join_all(futures).await;

Códigos de error contextualmente conectados

• ERR_SKILL_NOT_FOUND — Habilidad referenciada en conversación pero no en contexto de sesión; causada por inyección de contexto truncada
• ERR_DEP_MISSING — Herramienta CLI externa no encontrada en PATH; síntoma principal que aborda esta guía
• ERR_DEP_VERSION_MISMATCH — Herramienta encontrada pero versión incompatible con requisitos de habilidad
• ERR_SKILL_INVOCATION_TIMEOUT — Habilidad se ejecuta pero herramienta externa se cuelga; no debe confundirse con dependencias faltantes
• ERR_CONTEXT_OVERFLOW — Inventario de habilidades demasiado grande para ventana de contexto; relacionado con enfoque de solución

Referencias históricas de problemas

Solicitudes de características complementarias

• Integración de autoinstalación — Extender `/skill health` para soportar `openclaw skill install-missing` para resolución de dependencias en un comando
• Bloqueo de versión de dependencias — Agregar restricciones `min_version`, `max_version` a manifiestos de habilidades
• Entornos virtuales — Soportar rutas de herramientas específicas de habilidad (ej. pyenv, nvm para herramientas Python/Node)
• Notificación de actualizaciones de dependencias — Alertar cuando las versiones de herramientas instaladas se desvían de los requisitos de habilidad

Solicitud de extracción de implementación

Este problema es abordado por PR #412: “Implement skill dependency auto-detection and health reporting system”

Cambios:

• Agregado campo `dependencies` al esquema de manifiesto de habilidades
• Creado `DependencyScanner` para detección de herramientas en tiempo de ejecución
• Implementado comando `/skill health`
• Mejorado contexto de sesión con inventario completo de habilidades
• Agregada degradación elegante con instrucciones de instalación