criterion

Criterion - 伊斯兰知识助手

由 AI 驱动的 Da'i（伊斯兰信仰的宣讲者），为全球求知者带来正统的伊斯兰教导。

以《古兰经》和正统圣训为基础。永远免费。只为安拉。

使命 · 功能 · 技术栈 · 快速开始 · MCP 服务 · 文档

使命

Criterion 旨在为所有寻求真理的人带来正统的伊斯兰知识，运用现代技术让全人类都能获得神圣的指引——永远免费，只为安拉。

我们的四大支柱

1. 真理与正统性 — 每个回答都以经过核实的来源（《古兰经》和《萨希哈圣训》）为依据。我们绝不捏造内容或产生幻觉。
2. 基础与简明 — 我们专注于凝聚共识的伊斯兰核心教义，避免教派争论和有争议的话题。
3. 只为安拉 — Criterion 将永远免费，不进行变现或宣传任何组织。这是持续的施舍（Sadaqah Jariyah）。
4. 尖端技术 — 我们运用前沿 AI，将伊斯兰指引有效地传递给大众。

👉 在 MISSION.md 中阅读完整的使命与愿景

主要特色

与使命一致：

• ✨ 永远免费 — 无付费墙、无广告、不变现。为主道而建（只为安拉）
• 📚 专注基础教义 — 避免教派争论，专注于普遍认可的伊斯兰教义
• 🛡️ 信任优先 — 按等级筛选正统圣训（默认仅限 Sahih），只使用经过核实的来源
• 🤝 以求知者为本 — 专为好奇的求知者、新穆斯林和求学者设计
• 🕌 Da'i 风格 — 以慈悲、渊博、谦逊的态度提供指引

卓越技术：

• 🎯 语义搜索 — 自然语言查询可从 6,236 节《古兰经》经文和 21,641 段圣训传述中返回相关内容
• 📖 上下文检索 — 排名前列的结果会附带前后 ±2 节经文或传述，提供恰当的上下文
• 🌐 多语言 — 支持英文（快速）和斯洛伐克语（可扩展至 10 多种语言）
• 🔗 准确引用 — 所有回答均包含带超链接的来源参考（Quran.com、Sunnah.com）
• ⚡ 快速 — 查询响应时间 <150ms

功能

Criterion 的功能

✅ 《古兰经》语义搜索 — 使用自然语言提问，获取相关经文
✅ 圣训语义搜索 — 搜索正统圣训，并按等级和合集筛选
✅ 上下文理解 — 排名前列的结果会附带周边上下文，确保含义准确
✅ 准确引用 — 每个回答都会引用真实来源并附上超链接
✅ 多语言阅读 — 英文（快速）和斯洛伐克语（单次 JOIN <200ms）
✅ 可分享的 URL — /quran/search?q=patience、/hadith/search?q=charity 和 /quran/2/255，均包含元数据
✅ 实时流式传输 — 逐步生成回答，并按 Token 逐个交付
✅ 基于工具的 RAG — 大模型会自主判断何时从《古兰经》或圣训中检索内容

技术栈

• 使用 React 19 和 Tailwind CSS 的 Next.js 15 App Router
• 用于大模型集成和流式传输的 Vercel AI SDK
• 用于生成智能自然语言回答的 XAI Grok 4
• 使用 pgvector 进行向量搜索的 PostgreSQL
• 用于类型安全数据库访问的 Drizzle ORM
• Google Gemini text-embedding-004（768 维）
• 使用 HNSW 索引进行 <150ms 相似度搜索
• 用于身份验证的 Auth.js
• 部署于 Vercel

工作原理

RAG 流程

User Question
    ↓
XAI Grok 4 LLM (decides which tools to use)
    ↓
Tool Selection:
  - queryQuran → 6,236 verses (top 7 for chat, top 20 for search)
  - queryHadith → 21,641 hadiths from 6 collections (top 3 for chat, top 15 for search, with grade filtering)
    ↓
Vector Search (768-dim Gemini embeddings)
    ↓
Context Enhancement (top 3 get ±2 surrounding verses)
    ↓
LLM Generates Response with Citations
    ↓
Real-time Stream to User (Server-Sent Events)

数据

• 来自全部 114 个苏拉的 6,236 节《古兰经》经文

  • 阿拉伯语文本（Tanzil Quran）
  • 英语译文（master）
  • 斯洛伐克语译文（可扩展）
  • 768 维嵌入向量（Gemini text-embedding-004）

• 来自 6 部主要典籍（Kutub al-Sittah 子集）的 21,641 条圣训叙述

  • 《布哈里圣训实录》（7,558）
  • 《穆斯林圣训实录》（2,920）
  • 《提尔密济圣训集》（3,951）
  • 《艾布·达乌德圣训集》（5,274）
  • 《纳瓦维四十段圣训》（42）
  • 《利雅得圣训》（1,896）
  • 等级筛选（Sahih、Hasan、Da'if）
  • 768 维嵌入向量

性能

• 《古兰经》搜索：<150ms（英语），<200ms（译文）
• 圣训搜索：<150ms
• 向量搜索：由 HNSW 索引提供支持
• 流式传输：实时逐个词元交付

开始使用

先决条件

• Node.js 18+ 和 pnpm
• PostgreSQL 数据库（推荐使用 Neon）
• API 密钥：
  • XAI API 密钥（用于 Grok LLM）
  • Google AI Studio API 密钥（用于嵌入向量）

安装

1. 克隆代码仓库

git clone <repo-url>
cd criterion

2. 安装依赖项

pnpm install

3. 设置环境变量

创建一个 .env.local 文件：

# Database
POSTGRES_URL=postgresql://...

# AI APIs
XAI_API_KEY=xai-...
GOOGLE_GENERATIVE_AI_API_KEY=...

# Authentication (optional)
AUTH_SECRET=...

4. 启用 pgvector 扩展

pnpm db:enable-pgvector

5. 运行数据库迁移

pnpm db:migrate

6. 导入《古兰经》数据（为 6,236 节经文生成嵌入向量）

pnpm ingest:quran

此过程需要 10-15 分钟才能完成。

7. 测试《古兰经》搜索

pnpm test:quran

8. 启动开发服务器

pnpm dev

现在，你的应用应该已在 localhost:3000 上运行。

可用命令

开发

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm start        # Start production server

数据库

pnpm db:generate  # Generate Drizzle schema
pnpm db:migrate   # Run migrations
pnpm db:studio    # Open Drizzle Studio (GUI)

数据导入与测试

# Quran
pnpm clear:quran         # Clear all Quran data
pnpm ingest:quran        # Ingest Quran verses and generate embeddings
pnpm ingest:quran:slovak # Ingest Slovak translation
pnpm test:quran          # Test Quran search functionality

# Hadith
pnpm clear:hadith  # Clear all Hadith data
pnpm ingest:hadith # Ingest Hadith and generate embeddings

MCP 服务

Criterion 通过 Model Context Protocol（MCP） 提供语义搜索能力，让 Claude Desktop 和 Cursor 等 AI 助手能够直接搜索《古兰经》和圣训。

快速设置：

{
  "mcpServers": {
    "criterion": {
      "url": "https://criterion.life/api/mcp"
    }
  }
}

可用工具：

• search_quran — 搜索 6,236 节《古兰经》经文
• search_hadith — 搜索来自 6 部典籍的 21,641 条可靠圣训
• get_verse — 根据引用检索指定经文（例如，“2:255”）

👉 在 MCP.md 中阅读完整的 MCP 文档

项目结构

criterion/
├── app/
│   ├── (auth)/          # Authentication routes
│   ├── (chat)/          # Chat interface and API
│   │   └── api/chat/    # Main chat endpoint
│   ├── search/          # Quran search page
│   │   └── api/         # Quran search API
│   ├── hadith/
│   │   └── search/      # Hadith search page and API
│   └── quran/           # Quran reading pages
├── lib/
│   ├── ai/
│   │   ├── embeddings.ts     # Core RAG logic
│   │   ├── prompts.ts        # Da'i system prompts
│   │   └── tools/
│   │       ├── query-quran.ts   # Quran search tool
│   │       └── query-hadith.ts  # Hadith search tool
│   └── db/
│       ├── schema.ts         # Database schema
│       └── migrations/       # SQL migrations
├── components/
│   ├── chat.tsx              # Main chat UI
│   ├── quran-verses.tsx      # Quran display component
│   ├── hadith-narrations.tsx # Hadith carousel
│   └── hadith/
│       └── hadith-card.tsx   # Reusable hadith card
├── scripts/
│   ├── ingest-quran.ts       # Quran data ingestion
│   ├── ingest-hadith.ts      # Hadith data ingestion
│   └── test-*.ts             # Test scripts
└── data/
    ├── quran*.txt            # Quran translations
    └── *-full.json           # Hadith collections

文档

了解 Criterion

• MISSION.md — 我们的愿景、价值观和更深层的目标。请先阅读此文档，了解我们构建 Criterion 的_原因_。
• CRITERION_DETAILED.md — 全面的技术文档，涵盖架构、实现历史和性能指标。
• CRITERION.md — 设置和关键概念的快速参考指南。

主要章节

文档	用途
MISSION.md	愿景、价值观、支柱和长期目标
CRITERION_DETAILED.md	技术架构、数据库架构、组件和最佳实践
CRITERION.md	快速入门、命令和核心概念
README.md	开始使用、功能和项目概览

架构概览

components/
├── Chat UI (QuranVerses, HadithNarrations, MessageActions)
├── Search Pages (Quran and Hadith semantic search with filters)
├── Hadith Components (reusable HadithCard for search and chat)
├── Quran Pages (shared components for context, language selection)
└── UI Components (buttons, inputs, etc.)

lib/
├── ai/
│   ├── embeddings.ts (vector search logic)
│   ├── prompts.ts (Da'i system prompts)
│   └── tools/ (queryQuran, queryHadith, requestSuggestions)
├── db/
│   ├── schema.ts (Drizzle ORM definitions)
│   └── queries.ts (database functions)
└── monitoring/ (performance tracking)

app/
├── (chat)/api/chat (main chat endpoint)
├── quran/search/ (Quran search page and API)
├── hadith/search/ (Hadith search page and API)
├── quran/ (Quran reading pages)
└── (auth)/ (authentication)

数据来源说明

• 《古兰经》文本：Tanzil.net — 知识共享署名 3.0
• 《古兰经》译文：多个来源，均已正确注明出处
• 圣训集：Sunnah.com、IslamicNetwork.com
• 嵌入向量：Google Gemini text-embedding-004

我们的承诺

Criterion 秉持以下承诺：

• ✅ 绝不将伊斯兰知识商业化
• ✅ 始终通过恰当的引用注明来源
• ✅ 绝不捏造经文或圣训
• ✅ 聚焦基本教义——避免教派争论
• ✅ 为社群而建——它属于全体穆斯林，并造福全人类
• ✅ 保持领先——运用最先进的技术

贡献

我们欢迎认同我们使命的开发者、学者和社区成员参与贡献。请参阅 CONTRIBUTING.md 了解相关指南。

许可证

• 《古兰经》文本：知识共享署名 3.0（Tanzil.net）
• 圣训数据：来自经过验证的伊斯兰资料来源，并注明出处
• 代码：详情请参阅 LICENSE 文件

---

“你应凭借智慧和善言召人归于你的主道，并以最好的方式与他们辩论。” — 《古兰经》16:125

愿真主悦纳这项工作，并使其成为引导各地求道者的途径。阿敏。