moonverse.ts

MoonBit 文档和源代码搜索服务，基于 Google Gemini API。

✨ 最新更新 (2026-01-02)

增强了文件过期自动处理策略：

• ✅ 自动检测和重新上传过期文件（48 小时后）
• ✅ API Key 隔离：不同 Key 上传的文件分开管理
• ✅ 更保守的 24 小时 TTL：避免边界情况
• ✅ 智能错误恢复：自动处理 403/404 错误
• ✅ 运行时文件验证：查询前验证文件可用性

详见 FILE_EXPIRATION_IMPROVEMENTS.md

功能特性

• 🔍 三种查询模式：文档查询、源码查询、混合查询
• 📚 文档搜索：上传 Markdown 文件到 Gemini，AI 回答问题
• 💻 源码搜索：本地搜索 MoonBit 源代码 + LLM 组织结果
• 🔗 混合查询：结合文档和代码示例，提供综合回答
• 💾 文件缓存：自动缓存已上传文件，避免重复上传
• 🌐 HTTP API：异步任务队列，支持轮询获取进度
• 🇨🇳 中文回答：所有 AI 回答默认使用中文

快速开始

1. 安装依赖

yarn install

2. 配置环境变量

export GEMINI_API_KEY='your-api-key-here'

3. 构建并运行

yarn build
yarn start

4. 测试查询

# 混合查询（推荐）
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"type": "hybrid", "query": "MoonBit 当中 .. 两个点有哪些用法?"}'

# 轮询结果
curl http://localhost:8080/query/<task-id>

API 接口

端点	方法	说明
/query	POST	创建查询任务
/query/:id	GET	轮询任务状态
/healthz	GET	健康检查
/usage	GET	全局 API 使用情况

API Key 认证

推荐在请求头中携带自己的 Gemini API Key：

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-gemini-api-key" \
  -d '{"type": "hybrid", "query": "..."}'

不携带 X-API-Key 时，将使用全局 Key（每天限 100 次）。

查询类型

类型	说明	适用场景
docs	仅文档查询	查询官方文档内容
source	源码搜索	查找代码示例和实现
hybrid	混合查询	综合文档和代码回答（推荐）

项目结构

moonverse.ts/
├── src/                   # 源代码
│   ├── index.ts           # 主入口
│   ├── types.ts           # 类型定义
│   ├── genai.ts           # AI 客户端
│   ├── cache.ts           # 文件缓存
│   ├── store.ts           # 文件上传
│   ├── search.ts          # 源码搜索
│   ├── query.ts           # 查询执行
│   └── server.ts          # HTTP 服务器
├── store/                 # 文档目录（上传到 Gemini）
├── source/                # 源代码目录（本地搜索）
└── .gemini-cache.json     # 文件缓存

环境变量

变量	必需	说明
GEMINI_API_KEY	✅	Gemini API 密钥
HTTP_PROXY	❌	HTTP 代理地址
HTTPS_PROXY	❌	HTTPS 代理地址
GEMINI_BASE_URL	❌	自定义 Gemini API 端点
PORT	❌	服务器端口（默认 8080）

技术栈

• 运行时: Node.js 20+
• 语言: TypeScript (ES Modules)
• AI SDK: @google/genai v1.34.0
• 验证: zod

文档

• 开发指南 - 详细的开发文档和 API 说明
• 架构设计 - 系统架构和模块说明

License

ISC