# kloop **Repository Path**: azirkxs/kloop ## Basic Information - **Project Name**: kloop - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-03-11 - **Last Updated**: 2026-03-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# 🔍 Kloop 基于MiroThinker架构编排 **下一代深度搜索 Agent — 让复杂问题迎刃而解** [![Python](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python)](https://www.python.org) [![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE) [![Framework](https://img.shields.io/badge/Framework-FastAPI%20%2B%20MCP-orange)](https://fastapi.tiangolo.com) [![LLM](https://img.shields.io/badge/LLM-Qwen%20%7C%20Claude%20%7C%20GPT-purple)]() --- *四阶段状态机工作流 · 多轮迭代搜索 · 证据驱动推理 · 高置信度回答*
--- ## ✨ 项目亮点 ``` 用户提问 ──→ 拆解槽位 ──→ 多轮搜索 ──→ 证据蒸馏 ──→ 高置信度答案 Normalize Query Loop Evidence Synthesis Distill ``` | 能力 | 说明 | |------|------| | 🧩 **Slot 驱动搜索** | 自动将复杂问题拆解为若干待解析槽位，搜索始终围绕信息缺口展开 | | 🔄 **双层循环 + 大回滚** | 内层小循环最多 5 轮迭代；证据不足时外层大循环换方向重搜，最多 5 轮 | | 🧠 **三档模型路由** | Main / Fast / Reasoning 三档分别应对不同复杂度，兼顾质量与成本 | | 📡 **SSE 流式 API** | 标准 Server-Sent Events 接口，实时心跳保活，符合大赛评测规范 | | 🛠 **MCP 工具生态** | 基于 MCP 协议接入 Google 搜索、网页抓取、代码执行、视觉问答等工具 | | 📊 **结构化日志** | 每次任务生成完整 JSON 日志，记录全部工具调用与 LLM 输入输出 | --- ## 🎬 工作流一览 ``` 问题输入 │ ▼ ┌──────────────────────────────────────────────────────┐ │ Phase 1: NORMALIZE 📋 │ │ 解析问题 → 识别 slot（待解析项）→ 生成预推理候选 │ └─────────────────────┬────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────┐ │ Phase 2: QUERY LOOP 🔍 （小循环，最多 5 轮） │ │ │ │ Query Revision → 并发搜索 → Clue Analysis │ │ → 并发抓页 → 单页证据提取 → 充分性评估 │ │ ↑ 早退 │ └─────────────────────┬────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────┐ │ Phase 3: EVIDENCE DISTILL 🧪 │ │ 汇总原子证据 → 综合候选答案 → 判断是否回滚 │ └──────────┬───────────────────────┬───────────────────┘ 证据不足（回滚） 证据充分 │ │ ▼ ▼ 回到 Query Loop Phase 4: SYNTHESIS ✅ （大循环最多 5 轮） 汇总推理 → 最终答案 ``` --- ## 🗂 项目架构 ``` MiroThinker/ ├── apps/ │ └── miroflow-agent/ # 主 Agent 应用 │ ├── src/ │ │ ├── workflow/ # 核心工作流（状态机） │ │ │ ├── controller.py # 主控制器 │ │ │ ├── loop_controller.py # 双层循环控制器 │ │ │ ├── phases/ # Phase 执行器 │ │ │ ├── prompts/ # LLM Prompt 模板（14个） │ │ │ ├── stores/ # 内存状态存储 │ │ │ ├── reducers/ # 状态更新器 │ │ │ └── models.py # 核心数据模型 │ │ ├── core/ # 编排器 / Pipeline │ │ ├── llm/ # LLM 客户端（OpenAI / Anthropic） │ │ ├── config/ # 配置加载 │ │ ├── io/ # 输入输出格式化 │ │ └── logging/ # 任务日志 │ ├── conf/ │ │ ├── llm/ # LLM 配置（qwen3.5 / claude / gpt-5 ...） │ │ ├── agent/ # Agent 配置（工具列表、轮次上限等） │ │ └── config.yaml # Hydra 主配置 │ ├── api_server.py # FastAPI SSE 服务 │ ├── run_single_question.py # 单题测试脚本 │ ├── requirements.txt # pip 依赖 │ └── pyproject.toml └── libs/ └── miroflow-tools/ # MCP 工具库 └── src/miroflow_tools/ ├── mcp_servers/ # Google搜索、网页抓取、代码执行、视觉问答等 ├── dev_mcp_servers/ # 实验性工具 └── manager.py # 工具管理器 ``` --- ## ⚡ 快速开始 ### 1. 克隆仓库 ```bash git clone cd MiroThinker ``` ### 2. 安装依赖 ```bash cd apps/miroflow-agent # 本地开发（推荐，使用 uv） uv sync # 或 pip 部署 pip install -r requirements.txt ``` ### 3. 配置环境变量 ```bash cp env.example .env # 编辑 .env，填入你的 API Key ``` 最简配置（核心搜索功能）： ```dotenv SERPER_API_KEY=your_serper_key # https://serper.dev JINA_API_KEY=your_jina_key # https://jina.ai OPENAI_API_KEY=your_openai_key # 主 LLM OPENAI_BASE_URL=https://api.openai.com/v1 ``` ### 4. 单题测试 ```bash python run_single_question.py --id 0 ``` ### 5. 启动 API 服务 ```bash uvicorn api_server:app --host 0.0.0.0 --port 8000 ``` ```bash # 测试接口 curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{"question": "2024年诺贝尔物理学奖得主是谁？"}' \ http://localhost:8000/ ``` --- ## 🌐 API 接口说明 ### POST `/` — 问答接口（SSE 流式） **请求** ```json {"question": "你的问题"} ``` **响应事件流** | 事件 | 含义 | 格式 | |------|------|------| | `Ping` | 保活心跳（每 30s）| 无 data | | `Message` | 最终答案 | `{"answer": "..."}` | ### GET `/health` — 健康检查 ```json {"status": "ok", "timestamp": "2026-03-11T11:00:00"} ``` --- ## ⚙️ 配置说明 ### LLM 配置（`conf/llm/`） | 配置文件 | 说明 | |----------|------| | `qwen3.5.yaml` | Qwen3.5 系列（推荐）| | `qwen-3.yaml` | Qwen3 自托管 | | `qwen-fast.yaml` | 快速小模型（摘要/线索分析）| | `qwen-reasoning.yaml` | 推理增强模型（深度反思）| | `claude-3-7.yaml` | Anthropic Claude 3.7 | | `gpt-5.yaml` | OpenAI GPT-5 | **三档模型路由** | 档位 | 调用场景 | |------|----------| | **Main** | Normalize、Query Revision、Synthesis | | **Fast** | 单页证据提取（高频轻量）| | **Reasoning** | 大回滚重推、失败反思 | ### Agent 配置（`conf/agent/`） | 配置文件 | 说明 | |----------|------| | `default.yaml` | 默认多工具配置 | | `single_agent_keep5.yaml` | 单 Agent + 保留最近 5 条工具结果（推荐）| | `single_agent.yaml` | 单 Agent，保留全部工具结果 | ### 环境变量 | 变量 | 必须 | 说明 | |------|------|------| | `SERPER_API_KEY` | ✅ | Google 搜索 | | `JINA_API_KEY` | ✅ | 网页抓取 | | `OPENAI_API_KEY` | 按需 | 主 LLM | | `ANTHROPIC_API_KEY` | 按需 | Claude 模型 | | `API_TOKEN` | 可选 | Bearer 鉴权，留空不校验 | | `PORT` | 可选 | 服务端口（默认 8000）| | `MIROFLOW_PYTHON` | 部署时按需 | MCP 子进程 Python 路径，多环境部署时使用 | --- ## 🔧 常见问题 | 问题 | 解决方案 | |------|---------| | `No module named 'miroflow_tools'` | `pip install -r requirements.txt` 或设置 `MIROFLOW_PYTHON` 环境变量 | | `No matching distribution found for mcp` | `pip install -r requirements.txt --extra-index-url https://pypi.org/simple` | | `Package requires a different Python` | 已支持 Python 3.11+，无需降级 | | `No module named 'logging.task_logger'` | 已修复，确保使用最新代码 | | 搜索结果为空 | 检查 `SERPER_API_KEY` 及配额，`SERPER_BASE_URL` 末尾不要加斜杠 | | 答案置信度低，频繁回滚 | 检查 `SUMMARY_LLM` 配置；适当增大 `max_rounds` | | 生产环境多 worker 异常 | 使用 `--workers 1`，通过多实例 + 反向代理水平扩展 | --- ## 📄 License [MIT](./LICENSE) © 2025 MiroMind