スキル依存関係の自動検出とユーザー透過的通知 - Skill Dependency Auto-Detection and User-Transparent Notifications

1. 新セッションでのスキルコンテキスト欠落

ユーザーが新しいセッションを開始し、スキルとして存在する機能について問い合わせた場合、利用可能な機能にもかかわらず、システムが否定的に応答します。

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

2. サイレントな依存関係エラー

スキルは /skill list で機能するように見えますが、外部CLI依存関係が欠落しているため、呼び出し時にサイレントに失敗します。

$ 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. 依存関係インベントリの欠落

ユーザーは、スキルが機能するためにインストールが必要な外部ツールについて可視性がありません。

# 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. 不完全なスキル検出

起動時のシステムコンテキスト注入には、利用可能なスキルのサブセットのみが含まれるため、インテリジェントなルーティング失敗が発生します。

# 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

アーキテクチャ分析

OpenClawスキルシステムには、いくつかのアーキテクチャ上の欠陥により、インストール済みスキルとランタイム可用性の間に可視性ギャップがあります。

1. 遅延コンテキスト注入モデル

スキル読み込みメカニズムは、セッション初期化中に部分的なコンテキスト注入戦略を使用します：

// 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
}

影響: apple-notes、bear-notes、himalaya などのスキルは読み込まれますが、LLMコンテキストに公開されないため、会話的検出では認識できません。

2. 欠落している依存関係宣言レイヤー

スキルマニフェスト（.skill.yamlまたは同等のもの）には、标准化された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. ランタイム依存関係検証の欠如

スキル呼び出しパイプラインが依存関係検証をスキップします：

// 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. 切断されたヘルスモニタリング

スキルステータスと依存関係可用性を集計する統合ヘルスチェックがありません：

# 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

障害シーケンス図

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

フェーズ1: 依存関係スキーマの定義

スキルマニフェストファイルを標準化された依存関係宣言で拡張します：

# 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

フェーズ2: 依存関係スキャナの實現

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(", "))
    }
}

フェーズ3: セッション初期化の修正

src/session/session_manager.rs を更新して、完全なスキルコンテキストを含めるようにします：

// 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(())
    }
}

フェーズ4: ヘルスチェックコマンドの実装

/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")
    }
}

フェーズ5: オンデマンド検出プロンプトの追加

スキル呼び出し中に依存関係チェックを実装し、ユーザーフレンドリーなエラーで処理します：

// 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
    }
}

検証テストスイート

実装を検証するために次のコマンドを実行します：

1. ヘルスチェックコマンドの検証

$ 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

期待される終了コード: 0

2. 新セッションコンテキストの検証

$ 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. 依存関係対応の呼び出し

$ 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. グレースフルデグラデーションテスト

$ 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. コンテキスト注入の検証

$ 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"]},
    ...
  ]
}

回帰テストチェックリスト

• テストA: 既存のセッションは変更없이引き続き機能する
• テストB: 依存関係宣言のないスキルは変更없이動作する
• テストC: オフラインモードでは適切な「確認不可」ステータスが表示される
• テストD: キャッシュされたヘルスレポートは設定可能なTTL後に期限切れになる
• テストE: カスタムツールパス（設定経由）はPATH解決で尊重される

環境固有のトラップ

1. macOS Homebrewパスの可変性

# 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

緩和策: スキルランナー環境でHomebrewを明示的にソースします：

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

2. 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

緩和策: プラットフォーム固有のフォールバック検出を実装します：

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. DockerコンテナのPATH分離

# 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)

緩和策: ヘルスチェックがホストではなくコンテナ環境を反映することをドキュメント化します。

4. 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

緩和策: Windows用の拡張子対応のwhich置換を実装します：

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
}

ユーザー設定ミスシナリオ

5. 循環依存関係の検出

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

# Causes infinite loop in dependency scanner

緩和策: スキャナでサイクル検出を実装します：

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. バージョン固有の依存関係ミスマッチ

# 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

緩和策: 依存関係スキーマにバージョン制約を含めます（将来のエンハンスメント）。

パフォーマンスの落とし穴

7. 過度なヘルスチェックレイテンシ

# 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

緩和策: キャッシュを伴う並列スキャンを実装します：

// 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;

コンテキスト的に関連するエラーコード

• ERR_SKILL_NOT_FOUND — 会話で参照されているがセッションコンテキストにないスキル。切り詰められたコンテキスト注入によって発生
• ERR_DEP_MISSING — 外部CLIツールがPATHに見つからない。このガイドが対処する主な症状
• ERR_DEP_VERSION_MISMATCH — ツールは見つかったが、スキルの要件とバージョンが互換性がない
• ERR_SKILL_INVOCATION_TIMEOUT — スキルは実行するが外部ツールがハングする。欠落している依存関係と混同してはならない
• ERR_CONTEXT_OVERFLOW — スキルインベント리가コンテキストウィンドウに対して大きすぎる。解決策のアプローチに関連

過去のイシュー参照

補完的な機能リクエスト

• 自動インストール統合 — `/skill health` を拡張して、ワンコマンドの依存関係解決のために `openclaw skill install-missing` をサポート
• 依存関係のバージョンピニング — スキルマニフェストに `min_version`、`max_version` 制約を追加
• 仮想環境 — スキル固有のツールパスをサポート（例：Python/Nodeツール用のpyenv、nvm）
• 依存関係更新通知 — インストールされたツールバージョンがスキルの要件から逸脱した場合に警告

実装プルリクエスト

このイシューは PR #412: “Implement skill dependency auto-detection and health reporting system” で対処されています

変更内容:

• スキルマニフェストスキーマに `dependencies` フィールドを追加
• ランタイムツール検出用の `DependencyScanner` を作成
• `/skill health` コマンドを実装
• 完全なスキルインベントリでセッションコンテキストを強化
• インストール手順付きのエラーハンドリングを追加