GitHub 项目推荐助手智能体

1. 检索来源：GitHub API 实时数据（降低知识过时问题） 2. 执行方式：异步并发处理（改善多任务响应时延） 3. 输出形态：流式 + 结构化卡片（兼顾可读性与可点击性）

1. 来源于个人项目，关注 LLM 实用化而非纯聊天效果。 2. 重点解决“模型回答看起来合理，但链接无效或信息过时”的痛点。 3. 设计原则是先保证可验证，再优化表达质量，避免“华丽但不可用”的输出。

1. 通用模型对开源生态变化感知滞后，容易推荐过时或不准确项目。 2. 直接由模型生成仓库链接和 Star 数据，存在较高幻觉风险。 3. 多轮推荐场景下，串行数据抓取与翻译会造成明显延迟。

1. 设计并实现端到端 RAG 流程：意图识别、检索、上下文注入、结构化输出。 2. 定义“数据层真实、生成层摘要”的职责边界，降低错误信息传播。 3. 实现异步并发抓取与流式前端交互，优化响应体验。

1. 本地 LLM（Ollama + Qwen）负责理解问题和结果总结。 2. GitHub API 负责仓库事实数据（链接、描述、Star 等）的实时拉取。 3. FastAPI 作为编排层，串联检索、清洗、翻译与最终响应。 4. Vue 3 前端负责流式输出和卡片渲染。

1. 查询理解模块 - 提取语言、方向、技术栈、应用场景等意图特征。 - 生成可执行检索关键词，减少盲目大范围搜索。 2. 检索与清洗模块 - 调用 GitHub API 拉取候选仓库，统一归一化字段。 - 过滤无效或低质量结果，保留可直接访问的仓库信息。 3. 生成与展示模块 - LLM 只做摘要、对比与推荐理由，不负责生成事实数据。 - 前端以卡片形式展示结构化结果并支持流式反馈。

1. 推荐请求处理流程 - 接收用户需求并解析核心约束（语言、用途、难度等）。 - 组合关键词并调用 GitHub API 获取候选仓库。 - 并行执行信息清洗与中英翻译，生成统一结构数据。 - 将结构数据注入上下文，LLM 输出推荐理由与比较结论。 - 前端流式展示推荐内容，并提供可点击仓库入口。

1. 数据与生成职责分离 仓库 URL、Star 和简介由 API 直出，模型只输出解释文本，显著降低“看似合理但不可访问”的结果。 2. Asyncio 并发编排 将检索抓取、翻译与格式化任务并行执行，减少 IO 阻塞造成的响应延迟。 3. 流式输出与卡片兼容 处理流式文本与复杂卡片混排，避免 Markdown 解析阶段造成结构错乱。

1. 本地 RAG 链路可离线运行，适合隐私或受限网络环境。 2. 推荐结果以真实仓库数据为准，提升可信度。 3. 具备可复用的 Agent 工程骨架，便于继续接入更多数据源。

1. 本地模型能力受限时，如何保持推荐质量与响应速度平衡。 2. 流式渲染与复杂结构内容在前端解析层的稳定性。

1. 可稳定返回真实可访问的推荐仓库链接与结构化信息。 2. 沉淀出可复用的“检索增强 + 事实约束”推荐模式。

1. 支持多源检索（如 Papers with Code、Hugging Face、Awesome Lists）。 2. 增加推荐反馈闭环，基于用户点击/收藏行为优化排序。 3. 补充评测基准，对召回率、准确率和幻觉率做量化统计。