Hive Task Router

Intelligent task routing system that identifies task types (web/code/data/doc/chat) and routes to optimal models with appropriate execution mode (subagent/main session). Supports any AI model provider via environment variables.

# Hive Task Router

**Smart task distribution system for OpenClaw** — Automatically routes tasks to optimal models and execution modes based on task type recognition.

**Universal Model Support** — Works with any AI model provider (Bailian, OpenAI, Anthropic, etc.) via environment variable configuration.

---

## When to Use

### Automatic Trigger Rules (For AI Agents)

**Use this skill automatically when the user's message contains ANY of these patterns:**

| Trigger Pattern | Keywords | Action |
|----------------|----------|--------|
| **Code tasks** | 代码、编程、脚本、函数、nodejs、react、vue、typescript、javascript、html、css、前端、后端、api、接口、调试、bug、优化、重构 | Run `router.sh` → Execute with `code` model + subagent |
| **Web research** | 搜索、查找、调研、研究、github、项目、趋势、报告、分析、对比、评测、最新、2026、新闻、动态 | Run `router.sh` → Execute with `web` model + subagent |
| **Data tasks** | 数据、分析、统计、图表、可视化、excel、csv、json、处理、转换 | Run `router.sh` → Execute with `data` model + subagent |
| **Documentation** | 文档、说明、教程、指南、手册、readme、wiki、注释、文档化 | Run `router.sh` → Execute with `doc` model + subagent |
| **Batch tasks** | 多个、批量、同时、并行、一起 | Run `router.sh` for each → Execute in parallel |

**Do NOT use this skill when:**
- Simple chat/conversation (你好、谢谢、安排、计划、汇报、总结)
- Quick questions (what is, how to, explain)
- Tasks already in progress
- User explicitly says "don't use subagent" or "just answer directly"

### Manual Trigger (For Users)

**Users can explicitly trigger this skill by:**
- Running `router.sh "task description"` directly
- Saying "use hive router" or "analyze this task"
- Asking "which model should I use for this task"

### Decision Flow for AI Agents

```
Receive user message
    ↓
Contains specific trigger keywords? (code/web/data/doc/batch)
    ↓
YES → Run router.sh to analyze
    ↓
Get recommended model + execution mode
    ↓
Execute with recommended configuration
    ↓
Report result to user
    ↓
NO → Check for vague task keywords? (任务、帮忙、处理、搞定、完成)
    ↓
YES → Ask clarifying question (see "Vague Task Handling")
    ↓
User clarifies → Re-analyze with new info
    ↓
NO → Handle directly (no routing needed)
```

### Vague Task Handling

**When user message is vague** (e.g., "做个任务", "帮忙处理一下", "搞定这件事"):

**Step 1: Acknowledge and ask**
```
好的主人，请问是什么类型的任务？

💻 写代码/脚本？
   - 例如："写个 Python 脚本"、"开发一个 API"

🔍 搜索调研？
   - 例如："搜索最新趋势"、"调研竞品"

📊 数据处理？
   - 例如："分析 Excel 数据"、"转换 JSON 格式"

📄 写文档？
   - 例如："写 API 文档"、"编写教程"

💬 还是只是聊天？
   - 例如："今天有什么安排"、"帮我总结一下"

或者您直接告诉我具体内容，我来判断！
```

**Step 2: User clarifies**
```
User: "写个脚本处理数据"
  ↓
Now contains: "脚本" (code) + "数据" (data)
  ↓
Priority: code > data
  ↓
Execute with: qwen3-coder-plus + subagent
```

**Vague Keywords (trigger clarification):**
- 任务、帮忙、处理、搞定、完成、做一下、弄一下
- 这个、那个、一件事、一个东西

**Specific Keywords (trigger automatic routing):**
- code: 脚本、代码、编程、函数、nodejs、react...
- web: 搜索、调研、分析、趋势、报告、对比...
- data: 数据、统计、图表、excel、csv、json...
- doc: 文档、教程、指南、readme、wiki...

**Ideal scenarios:**
- Handling multiple concurrent tasks
- Technical development requiring code-specialized models
- Research tasks needing web search capabilities
- Mixed workloads with varying complexity
- Multi-provider environments (Bailian + OpenAI + Anthropic)

---

## Quick Reference

### Task Type Recognition Keywords

| Type | Keywords (Chinese) | Keywords (English) | Priority |
|------|-------------------|-------------------|----------|
| **web** 🔍 | 搜索、查找、调研、研究、github、项目、趋势、报告、分析、对比、评测、最新、2026、新闻、动态 | search, research, github, project, trend, report, analysis, comparison, latest, news | 1 (Highest) |
| **code** 💻 | 代码、编程、脚本、函数、nodejs、react、vue、typescript、javascript、html、css、前端、后端、api、接口、调试、bug、优化、重构 | code, programming, script, function, nodejs, react, vue, typescript, javascript, html, css, frontend, backend, api, debug, bug, optimize, refactor | 2 |
| **data** 📊 | 数据、分析、统计、图表、可视化、excel、csv、json、处理、转换 | data, analysis, statistics, chart, visualization, excel, csv, json, processing, conversion | 3 |
| **doc** 📄 | 文档、说明、教程、指南、手册、readme、wiki、注释、文档化 | documentation, guide, tutorial, manual, readme, wiki, comment, document | 4 |
| **chat** 💬 | 你好、谢谢、再见、今天、明天、安排、计划、汇报、总结、提醒、备忘 | hello, thanks, goodbye, today, tomorrow, plan, schedule, summary, reminder, memo | 5 (Default) |

### Model Selection Rules

**Note:** Model IDs are configurable via environment variables. Replace `provider/` with your actual model provider (e.g., `bailian/`, `openai/`, `anthropic/`).

| Task Type | Default Model | Environment Variable | Reason |
|-----------|--------------|---------------------|--------|
| **code** | `provider/qwen3-coder-plus` | `HIVE_MODEL_CODE` | Specialized in code generation and debugging |
| **web** | `provider/qwen3-max` | `HIVE_MODEL_WEB` | Strong search and reasoning capabilities |
| **data** | `provider/qwen3-coder-plus` | `HIVE_MODEL_DATA` | Code-based data processing |
| **doc** | `provider/qwen3.5-plus` | `HIVE_MODEL_DOC` | Good text generation, cost-effective |
| **chat** | `provider/qwen3.5-plus` | `HIVE_MODEL_CHAT` | Best for casual conversation, cost-effective |

### Model Configuration Examples

**Bailian (通义千问):**
```bash
export HIVE_MODEL_CODE="bailian/qwen3-coder-plus"
export HIVE_MODEL_WEB="bailian/qwen3-max-2026-01-23"
export HIVE_MODEL_CHAT="bailian/qwen3.5-plus"
export HIVE_MODEL_DOC="bailian/qwen3.5-plus"
export HIVE_MODEL_DATA="bailian/qwen3-coder-plus"
```

### Model Validation Modes

**Automatic Model Detection (Recommended):**

```bash
# Auto-detect available models from OpenClaw
export HIVE_VALIDATE_MODEL=auto
```

**First run:** Detects models and caches configuration  
**Subsequent runs:** Uses cached config (24h TTL)  
**Benefit:** No manual configuration needed!

**Manual Validation Modes:**

| Mode | Environment Variable | Behavior | Use Case |
|------|---------------------|----------|----------|
| **Auto (Recommended)** | `export HIVE_VALIDATE_MODEL=auto` | Auto-detect + cache 24h | **Best for most users** |
| **Cache** | `export HIVE_VALIDATE_MODEL=cache` | Validate once, cache 24h | Manual config, stable |
| **Always** | `export HIVE_VALIDATE_MODEL=1` | Validate every execution | Debugging, changes |
| **Never** | `export HIVE_VALIDATE_MODEL=0` | Skip validation | Production, known config |

**Cache Configuration:**
```bash
# Cache directory (default: ~/.hive-task-router)
export HIVE_CACHE_DIR="$HOME/.hive-task-router"

# Cache TTL in seconds (default: 86400 = 24 hours)
export HIVE_CACHE_TTL=86400
```

**Validation Behavior:**
- ✅ Checks if model IDs contain `provider/` placeholder
- ✅ Warns if placeholder detected
- ✅ Caches validation result (configurable TTL)
- ✅ Non-blocking (warnings only, doesn't stop execution)

**OpenAI:**
```bash
export HIVE_MODEL_CODE="openai/gpt-4"
export HIVE_MODEL_WEB="openai/gpt-4-turbo"
export HIVE_MODEL_CHAT="openai/gpt-3.5-turbo"
export HIVE_MODEL_DOC="openai/gpt-3.5-turbo"
export HIVE_MODEL_DATA="openai/gpt-4"
```

**Anthropic (Claude):**
```bash
export HIVE_MODEL_CODE="anthropic/claude-3-5-sonnet"
export HIVE_MODEL_WEB="anthropic/claude-3-opus"
export HIVE_MODEL_CHAT="anthropic/claude-3-haiku"
export HIVE_MODEL_DOC="anthropic/claude-3-haiku"
export HIVE_MODEL_DATA="anthropic/claude-3-5-sonnet"
```

**Mixed Providers:**
```bash
# Use best model for each task type
export HIVE_MODEL_CODE="anthropic/claude-3-5-sonnet"  # Best for code
export HIVE_MODEL_WEB="openai/gpt-4-turbo"           # Best for search
export HIVE_MODEL_CHAT="bailian/qwen3.5-plus"        # Cost-effective
```

### Execution Mode Rules

| Task Type | Execution Mode | Reason |
|-----------|---------------|--------|
| **chat** | Main Session | Quick response, no need for isolation |
| **code/web/data/doc** | Subagent | Long-running tasks, parallel execution, session isolation |

**Priority Rule:** When multiple keywords match, use the highest priority type (web > code > data > doc > chat).

---

## Usage

### For AI Agents (Automatic Integration)

**When installed as an OpenClaw Skill**, the agent will automatically use this skill when:

1. **User me