willingning-coder/eagle-eye

🦅 Eagle Eye — 5-Layer Intelligent Skill Retrieval for Hermes Agent

Narrow 100+ skills down to the right 5 — deterministic triggers, fuzzy matching, semantic search, and rank fusion. Zero core modification.

中文文档

The Problem

Hermes Agent loads every installed skill into the system prompt as a flat list. When you have 50+ skills:

• The LLM picks wrong — overlapping descriptions confuse selection
• You burn tokens — 5,000–10,000 tokens per turn just for the skill list
• Rarely-used skills become invisible — buried at the bottom of a long list

The Solution

Eagle Eye is a zero-invasive plugin that acts as an intelligent pre-filter. Before each API call, it narrows the skill list to the top-5 most relevant candidates and injects them as a lightweight hint.

User Query
    │
    ▼
┌─────────────────────────────────────────────┐
│  L1: Hard Triggers                          │
│  Deterministic keyword matching (3-tier)    │
│  Hit → Inject full SKILL.md instantly       │
│  Miss ↓                                     │
├─────────────────────────────────────────────┤
│  L2: FTS5 BM25     (text similarity)        │
│  L3: Synonym Dict   (domain knowledge)      │
│  L4: Dense Embedding (semantic similarity)  │
│  L5: RRF Fusion     (rank combination)      │
│                                             │
│  Score ≥ threshold → Inject skill hints     │
│  Score < threshold → Silent (LLM decides)   │
└─────────────────────────────────────────────┘
    │
    ▼
LLM Final Decision

Key Design Decisions

1. "Not matching" is a valid result

Not every query needs a skill. "What should I eat for dinner?" is best answered by the LLM's general knowledge — not by loading a restaurant-finder skill. Eagle Eye's confidence gate prevents forced matches.

2. Deterministic first, probabilistic second

L1 (hard triggers) is 100% precise — if the user types "debug", the debugging skill loads instantly with no probability involved. L2–L5 handles the long tail where fuzzy, semantic matching adds value.

3. Hints, not decisions

L2–L5 returns candidates, not conclusions. The LLM retains final authority to load a skill, combine multiple skills, or ignore the hint entirely. The retrieval system doesn't override the LLM's judgment.

4. Each layer fails independently

If sentence-transformers isn't installed, L4 degrades gracefully — L1+L2+L3 still work. If jieba is missing, L1+L4 still work. The system never crashes; it always falls back to a working subset.

Quick Start

# 1. Clone
git clone https://github.com/willingning-coder/eagle-eye.git
cd eagle-eye

# 2. Generate config from your local skill library
python scripts/generate_config.py

# 3. Review and customize
#    - Edit _HARD_TRIGGERS in src/skill_retriever.py
#    - Edit src/skill_synonyms.yaml
#    (See PROMPTS.md for LLM-assisted generation)

# 4. Install
bash scripts/install.sh

# 5. Restart Hermes
hermes gateway restart

Customization

Eagle Eye ships with minimal example data. The real power comes from generating your own configuration based on your installed skills.

Auto-Generate (Recommended)

# Scan your skills and generate template configs
python scripts/generate_config.py

# Or just list what was found
python scripts/generate_config.py --scan-only

Manual Customization

LLM-Assisted Generation

Use the prompts in PROMPTS_EN.md or PROMPTS_CN.md with any LLM to generate high-quality triggers and synonyms from your skill list.

Environment Variables

Performance

Architecture

See ARCHITECTURE.md for a deep technical dive covering:

• Layer-by-layer algorithm analysis with code
• RRF fusion math and why it beats score normalization
• Confidence gate design philosophy
• Failure mode matrix and degradation hierarchy
• Latency and memory profiling

File Structure

eagle-eye/
├── src/
│   ├── skill_retriever.py      # Core 5-layer retrieval engine
│   ├── skill_synonyms.yaml     # Synonym dictionary (template)
│   ├── plugin.py               # Hermes plugin (pre_llm_call hook)
│   └── plugin.yaml             # Plugin manifest
├── scripts/
│   ├── generate_config.py      # Auto-generate config from your skills
│   └── install.sh              # One-command installation
├── templates/
│   └── hard_triggers.example.py  # Trigger format reference
├── README.md                   # This file (English)
├── README_CN.md                # 中文文档
├── ARCHITECTURE.md             # Technical deep dive
├── PROMPTS_EN.md               # LLM prompts for config generation (English)
├── PROMPTS_CN.md               # LLM prompts for config generation (中文)
├── CHANGELOG.md                # Version history
└── LICENSE                     # MIT

Dependencies

Contributing

Contributions are welcome! Areas where help is especially valuable:

• Trigger/synonym quality: Share your _HARD_TRIGGERS and skill_synonyms.yaml configurations
• Embedding model benchmarks: Test alternative models and report accuracy
• Multi-language support: Extend triggers and synonyms beyond Chinese/English
• Bug reports: Edge cases in fuzzy matching, false positives/negatives

License

MIT