# 无人机行为规划后端系统

从自然语言指令到行为树 JSON 的四层流水线系统，支持 RAG 检索、Function Calling 坐标计算、Fast-Path 短路等能力。

## 功能概览

- **Layer 1 (Router)**：意图分类与实体抽取，支持原子指令（起飞/降落/悬停）Fast-Path 短路
- **RAG 检索**：地图基准点坐标、规则约束、Few-shot 示例（不负责相对坐标计算）
- **Layer 2 (Composer)**：根据意图裁剪 schema，组装精简 System Prompt
- **Layer 3 (Planner)**：LLM 生成行为树 JSON，**仅 LLM 通过 mcp 工具计算坐标**（绝对地点用 base_location_coords，相对位置必须调用工具，禁止心算）
- **Layer 4 (Execution)**：解析 JSON 为 py_trees，根据 `is_in_air` 自动插入起飞逻辑

## 环境要求

- Python 3.10+
- 本地 LLM 服务（llama-server 或兼容 OpenAI API 的服务）：
  - **Chat**：默认 `http://localhost:8081/v1`
  - **Embedding**：默认 `http://localhost:8090/v1`（RAG 用）

## 快速部署

### 1. 克隆与依赖

```bash
cd DronePlanningV2
pip install -e .
# 或
pip install -r requirements.txt
```

### 2. 配置 LLM 服务

确保 Chat 和 Embedding 服务已启动。可通过环境变量覆盖默认地址：

```bash
export LLM_CHAT_BASE_URL="http://localhost:8081/v1"
export LLM_EMBEDDING_BASE_URL="http://localhost:8090/v1"
export OPENAI_API_KEY="not-needed"   # 本地部署通常不需要
```

可选：开启模型思考模式（默认关闭以降低延迟）：

```bash
export ENABLE_THINKING=true
```

### 3. RAG 知识库灌入

首次使用或更新知识库后需执行灌入：

```bash
python -m drone_planning.rag.ingestion
```

知识库文件位于 `data/knowledge/`：

- `map_db.jsonl`：地点坐标（location, x, y, z）
- `rule_db.jsonl`：规则约束（intent, document）
- `few_shot_db.jsonl`：Few-shot 示例（instruction, tree_json）

### 4. 启动 API 服务

```bash
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### 5. 启动 Playground 测试台

```bash
streamlit run playground.py
```

## 使用方式

### API 调用

```bash
# 复杂任务（走完整流水线）
curl -X POST http://localhost:8000/api/plan \
  -H "Content-Type: application/json" \
  -d '{"text": "飞到大门然后拍照"}'

# 原子指令（Fast-Path 短路）
curl -X POST http://localhost:8000/api/plan \
  -H "Content-Type: application/json" \
  -d '{"text": "起飞"}'

# 相对描述（RAG 提供基准点，LLM 调用 mcp 计算）
curl -X POST http://localhost:8000/api/plan \
  -H "Content-Type: application/json" \
  -d '{"text": "飞到广场东边500米"}'
```

响应示例（含各环节耗时 `timing_ms`）：

```json
{
  "success": true,
  "fast_path": false,
  "intents": ["fly_task", "photo_task"],
  "entities": {"locations": ["大门"], "targets": []},
  "rag_context": {...},
  "tool_call_log": [...],
  "tree_json": {"root": {...}},
  "tree_ascii": "...",
  "timing_ms": {
    "Layer1_Router": 120,
    "RAG_检索": 45,
    "Layer2_Composer": 2,
    "Layer3_Planner": 3500,
    "Layer4_Execution": 1
  }
}
```

### Playground 测试

1. 打开 `http://localhost:8501`
2. 左侧边栏：切换「是否在空中」模拟起飞状态
3. 主界面：输入自然语言指令，点击「执行规划」
4. 查看：各环节耗时、Layer 1~4 输出、RAG 检索结果、LLM Tool Call 日志（坐标仅由 LLM 通过 mcp 计算）

### 命令行测试 Router

```bash
python -m drone_planning.pipeline.router "飞到大门然后拍照"
```

## 项目结构

```
DronePlanningV2/
├── config/
│   └── node_schema.json      # 行为树节点定义
├── data/
│   └── knowledge/           # RAG 知识库 jsonl
│       ├── map_db.jsonl
│       ├── rule_db.jsonl
│       └── few_shot_db.jsonl
├── src/drone_planning/
│   ├── api/                  # FastAPI 路由
│   ├── core/                 # Blackboard 黑板
│   ├── execution/            # py_trees 解析与包装
│   ├── llm_client/           # Chat / Embedding 客户端
│   ├── pipeline/             # Router / Composer / Planner
│   ├── rag/                  # 向量存储、检索、灌入
│   └── tools/                # mcp_calc 坐标计算
├── main.py                   # API 入口
├── playground.py             # Streamlit 测试台
├── requirements.txt
└── pyproject.toml
```

## 环境变量汇总

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `LLM_CHAT_BASE_URL` | `http://localhost:8081/v1` | Chat API 地址 |
| `LLM_EMBEDDING_BASE_URL` | `http://localhost:8090/v1` | Embedding API 地址 |
| `OPENAI_API_KEY` | `not-needed` | API Key |
| `ENABLE_THINKING` | `false` | 是否开启模型思考模式 |
| `CHROMA_PERSIST_PATH` | `./data/chroma` | ChromaDB 持久化路径 |
| `EMBEDDING_MODEL` | `qwen3-embedding` | Embedding 模型名 |

## 常见问题

**Q: ChromaDB 报错？**  
A: 确保已安装 `chromadb>=0.4.0`，首次运行需执行 `python -m drone_planning.rag.ingestion`。

**Q: LLM 调用超时？**  
A: 检查 `LLM_CHAT_BASE_URL` 是否可达，模型是否支持 `json_schema` / `tools`。

**Q: 相对坐标未计算？**  
A: 确保 `map_db.jsonl` 中有基准点（如「广场」），Router 正确抽取 `direction`、`distance`，且 LLM 支持 Function Calling 调用 `calculate_relative_coordinate`。

**Q: 如何扩展知识库？**  
A: 编辑 `data/knowledge/*.jsonl` 后重新执行 `python -m drone_planning.rag.ingestion`。

## 详细流程文档

完整项目流程、各 Stage 对应代码、RAG 调用、工具调用、提示词组织等详见：[docs/项目流程详解.md](docs/项目流程详解.md)