Source Library

---

🎬 体验来源图书馆

---

🎯 关于来源图书馆

来源图书馆是一个开源数字图书馆，致力于让早期印刷书籍和原始文献易于阅读和引用。我们专注于炼金术、赫尔墨斯主义、卡巴拉、玫瑰十字主义和早期现代科学——这些文本连接着历史研究与当代探索。

🌟 为什么选择来源图书馆？

• ✨ 原文优先 — 阅读原文，并同时查看 AI 增强的翻译
• 🎓 可引用的学术成果 — 每本书均有 DOI 和学术元数据（与 USTC 对齐，追踪版本）
• 🏛️ 合作伙伴子域名 — Bibliotheca Philosophica Hermetica 等机构可在自己的域名上策划阅览室
• 🔍 探索发现 — 馆藏、插图画廊和语义搜索，帮助发现被忽视的文本
• ✅ 严格的质量保证 — 发布前进行人工核验、图像质量评分和 OCR 验证

该平台每月从 Internet Archive、Gallica、Bodleian、Wellcome 及其他数字文化遗产合作伙伴处获取约 15K 页内容。

---

🚀 快速开始

💻 开发环境

# 🍴 Clone and install
git clone https://github.com/Embassy-of-the-Free-Mind/sourcelibrary-v2.git
cd sourcelibrary-v2
npm install

# ⚙️ Configure environment (see .env.example for required variables)
# Must include: MongoDB Atlas connection, Google Gemini API key, Vercel Blob token

# ▶️ Start dev server
npm run dev

打开 http://localhost:3000

---

📋 技术栈

🎨 前端	Next.js 16、React 19、TailwindCSS、Lucide 图标
⚙️ 后端	Next.js API 路由、用于异步处理的 AWS Lambda
💾 数据库	MongoDB Atlas（主数据库）、Supabase（嵌入向量）
🤖 AI/ML	Google Gemini 3.1（OCR、翻译、摘要）
🗂️ 存储	Vercel Blob（图像）、AWS S3（归档）、Cloudflare R2（归档）
🔐 身份验证	NextAuth v5 与 MongoDB 适配器
🚀 DevOps	Vercel（托管）、GitHub（版本控制）、Playwright（端到端测试）
✔️ 测试	Vitest（单元/集成测试）、Playwright（端到端测试）
🔎 搜索	PostgreSQL 全文搜索 + 通过 Supabase 实现的语义搜索

📦 主要依赖项：

• sharp — 图像缩放和裁剪
• @google/generative-ai — Gemini API 集成
• xml2js — USTC 元数据解析
• @modelcontextprotocol/sdk — 用于 Agent 集成的 MCP 服务
• stripe — 捐赠和订阅处理

---

📚 核心功能

📖 阅读与导航

• ⚡ 页面分页 — 在 100+ 页之间即时跳转
• 🔍 全文搜索 — 搜索 OCR 识别文本和译文
• 📌 引文生成 — 复制并引用段落，附带 DOI 链接

🔄 处理流程

• 🧩 智能跨页检测 — 自动检测双页跨页版面中的书缝（使用 Gemini AI 或基于 ML 的方法）
• ✍️ 高精度 OCR — 使用 Gemini Vision API 和特定语言模型（拉丁语、德语、希腊语、阿拉伯语等）
• 🗣️ 上下文感知翻译 — 保持跨页连贯性，确保学术准确性
• 🖼️ 图片集提取 — 借助 AI 检测并编目插图

🎨 策展与发现

• 📑 主题合集 — 编辑策划的合集（例如“炼金术与嬗变”“卡巴拉与神秘主义”）
• 🏛️ 图片集浏览 — 浏览所有图书中的精选图片（博物馆级元数据）
• 📚 相关版本 — 关联不同译本、重印本和衍生作品
• 🔗 权威数据关联 — 关联 USTC、VIAF 等学术数据库

📤 学术导出

• 📱 EPUB 生成 — 导出为多种格式的电子书
• 📄 带注释的 PDF — 保留版面并添加学术注释
• 🆔 DOI 生成 — 通过 Zenodo 集成创建图书版本，便于长期引用

🏢 租户子域名

• 🏛️ 独立阅览室 — 合作方可在自定义域名上托管精选子集（例如 bph.sourcelibrary.org）
• 🎨 品牌与导航 — 为每个租户全面自定义 UI
• 🔒 访问控制 — 可设置为公开合集或仅限会员访问

---

🏗️ 架构概览

📊 数据模型

📚 图书包含结构化元数据：

• 🏛️ 书目信息 — 标题、作者、语言、出版日期、USTC ID
• 🖼️ 图片 — 源文件链接（Internet Archive、Gallica 等）及存档状态
• ⚙️ 处理信息 — OCR 状态、翻译语言、提取元数据
• 🎨 策展信息 — 合集、等级（精选/标准）、可见性标记

📄 页面存储单页数据：

• 📸 原始图片 — 源照片或 PDF 页面
• ✂️ 拆分坐标 — 双页跨页版面的裁剪边界（0-1000 比例）
• ✍️ OCR 输出 — Gemini 原始提取结果及语言元数据
• 🗣️ 翻译 — 英文译文及学术注释
• 🖼️ 插图 — 检测到的图片及质量评分和描述

🖼️ 图片集图片是提取出的插图：

• 🏷️ 元数据 — 主题、人物、符号、风格、技法、时期
• ⭐ 质量评分 — 0–1.0 分（过滤低于 0.5 的图片）
• 🔗 来源信息 — 源图书和页面，并提供回链

🎨 图片分级系统

所有页面图片都会按需通过 /api/image 调整大小：

等级	尺寸	质量	📱 用途
缩略图	宽 400px	70% JPEG	网格、导航、社交分享
显示图	宽 1200px	80% JPEG	主阅读视图，适合舒适地添加注释
完整图	宽 2400px	90% JPEG	放大镜、全屏细节查看、打印

拆分页面会根据坐标进行非破坏性裁剪；原始图片始终保留。

🔄 处理流程

📥 Import → ✂️ Split Detection → ✍️ OCR → 🗣️ Translation → 🎨 Enrichment → 🌍 Publishing

1. 📥 导入 — 上传图片，通过 IIIF 从 IA/Gallica 导入，或粘贴 URL
2. ✂️ 跨页检测 — 检测双页跨页版面并标记裁剪边界
3. ✍️ OCR — Gemini Vision 根据页面语言提取文本
4. 🗣️ 翻译 — Gemini 将文本翻译成英文，并结合前页上下文确保连贯性
5. 🎨 丰富内容 — 提取插图、生成摘要、分配合集
6. 🌍 发布 — 设置 visible: true，生成 DOI 并推送至搜索索引

批处理端点使用 Gemini Batch API，每个请求最多处理 5 页（成本降低 50%）。

🔌 API 路由（关键）

基础 URL： https://sourcelibrary.org（生产环境）或 http://localhost:3000（配置好 .env.local 的本地开发环境）。

常见的 404 错误： /api/bph/books 或 /api/bph/books/[id] 这样的路径不存在。BPH 目录 API 位于 /api/embed/bph/... 下。此外，顶层也没有 /api/[tenant]/books 路由——租户图书列表使用 /api/books/library 或下方的嵌入路由。

公共读取 API（目前无需身份验证）

端点	方法	用途
/api/search?q=<query>	GET	对图书和页面译文进行全文搜索
/api/books?limit=100&offset=0	GET	简单的图书列表（全局目录；仅包含 visible: true 且已编入索引的图书）
/api/books/library?limit=100&skip=0	GET	丰富的浏览 API——支持搜索、排序、筛选和合集
/api/books/[id]	GET	图书元数据（接受 Mongo id 或 slug）
/api/books/[id]/quote?page=<n>	GET	可引用的引文及格式化引文（行内、脚注、BibTeX、DOI）
/api/gallery?limit=24	GET	插图／艺术作品搜索
/api/image?url=<encoded-url>&w=400	GET	按需调整图像尺寸和裁剪
/api/embed/bph/books?limit=24	GET	BPH 目录（分页、可搜索）
/api/embed/bph/books/[slug]	GET	单本 BPH 图书详情
/api/embed/bph/featured	GET	精选 BPH 图书
/api/embed/bph/collections	GET	BPH 合集列表
/api/embed/bph/languages	GET	BPH 语言分类
/api/embed/bph/suggest?q=alch	GET	BPH 搜索自动补全
/api/embed/bph/stats	GET	BPH 目录统计数据

按租户筛选列表（不是 /api/bph/...）

使用以下任一方式按合作方租户（例如 BPH）筛选：

方式	示例
嵌入前缀（推荐用于 BPH）	GET /api/embed/bph/books?limit=24
Library API + 查询参数	GET /api/books/library?tenant_slug=bph&limit=24
Host 标头（子域名）	调用 https://bph.sourcelibrary.org/api/books/library?limit=24 — 代理会注入租户上下文
手动标头（高级）	curl -H "x-tenant-slug: bph" https://sourcelibrary.org/api/books/library?limit=24

代码库中存在的 /api/[tenant]/books/[id]/... 路径是编辑／处理路由（批量 OCR、重建索引等），并非公共目录列表。

需身份验证／内部 API

这些 API 需要已登录的会话 Cookie、编辑者角色，或（对于某些数据集端点）Bearer API 密钥。未经身份验证调用会返回 401 或 403。

端点	方法	用途
/api/books	POST	创建新图书（编辑者）
/api/books/[id]	PATCH	更新图书元数据（馆藏管理员及以上）
/api/books/[id]/batch-ocr-async	POST	将批量 OCR 任务加入队列
/api/books/[id]/batch-translate-async	POST	将批量翻译任务加入队列
/api/pages/[id]	PATCH	更新页面 OCR／译文
/api/jobs/[id]/process	POST	异步任务处理器（Lambda）

完整的 API 介绍：docs/blog-source-library-api.md。MCP 工具（搜索、引文、读取）：mcp-server/README.md。

🧪 尝试 API（curl、Postman、浏览器）

以下示例均调用生产环境，无需 API 密钥。本地运行时，请将基础 URL 替换为 http://localhost:3000（需要 MongoDB 和环境变量）。

curl

# Search translated text
curl -s "https://sourcelibrary.org/api/search?q=quintessence&limit=5" | jq .

# List books (global catalogue)
curl -s "https://sourcelibrary.org/api/books?limit=5" | jq .

# Browse with filters and sort
curl -s "https://sourcelibrary.org/api/books/library?limit=5&sort=recent-translation&has_translation=true" | jq .

# BPH catalogue — note /api/embed/bph/, NOT /api/bph/
curl -s "https://sourcelibrary.org/api/embed/bph/books?limit=5&translated=true" | jq .

# BPH via tenant_slug on the library endpoint
curl -s "https://sourcelibrary.org/api/books/library?tenant_slug=bph&limit=5" | jq .

# Book metadata (id or slug)
curl -s "https://sourcelibrary.org/api/books/know-thyself-reger-von-ehrenhart" | jq .

# Citable quote for a page
curl -s "https://sourcelibrary.org/api/books/6836f8ee811c8ab472a49e36/quote?page=57" | jq .

# Gallery search
curl -s "https://sourcelibrary.org/api/gallery?subject=alchemy&limit=5" | jq .

使用 jq 美化输出是可选的；省略 | jq . 即可查看原始 JSON。

Postman

1. 创建一个新的 GET 请求。
2. 将 URL 设为 https://sourcelibrary.org/api/embed/bph/books 等。
3. 在 Params 标签页添加查询键：limit = 24、sort = title、translated = true
4. 对于上述公共端点，将 Auth 保持为 No Auth。
5. 发送请求——预期会收到状态码 200 和 JSON 响应体。

Browser

公共 GET 端点可直接打开：

• 搜索：quintessence
• BPH 书籍
• 全局图书馆浏览

📁 目录结构

src/
├── app/                         # 🎨 Next.js App Router
│   ├── book/[id]/               # 📖 Book detail, reading, processing
│   │   ├── page.tsx             # Main book hub
│   │   ├── split/page.tsx       # Split detection workflow
│   │   └── page/[pageId]/page.tsx      # Individual page view
│   ├── api/                     # 🔌 All API routes
│   │   ├── books/               # Book CRUD & batch ops
│   │   ├── pages/               # Page processing
│   │   ├── image/               # Image proxy & cropping
│   │   ├── jobs/                # Async job tracking
│   │   └── search/              # Full-text & semantic
│   ├── [tenant]/                # 🏢 Tenant subdomain routes
│   ├── gallery/                 # 🖼️ Illustration browsing
│   ├── collections/             # 📑 Collection pages
│   └── admin/                   # ⚙️ Admin dashboard
├── hooks/                       # 🎣 Reusable React hooks
└── lib/                         # 🛠️ Business logic & utilities
    ├── mongodb.ts               # Database operations
    ├── image-extraction.ts      # Illustration detection
    └── auth-helpers.ts          # Authentication utilities

scripts/
├── workers/                     # ⚙️ Lambda worker functions
│   ├── pipeline-orchestrator.mjs # Main processing pipeline
│   ├── image-extract-worker.mjs # Gallery extraction
│   └── ...
├── maintenance/                 # 🔧 One-off maintenance scripts
├── migrations/                  # 📊 Database schema updates
└── audit-bph-leaks.mjs          # 🔒 Tenant security verification

tests/
├── unit/                        # ✔️ Vitest unit tests
└── integration/                 # 🔗 Integration tests

prompts/                        # 🤖 AI system prompts
├── ocr/
├── translation/
├── split-detection/
└── ...

.claude/                        # 🧠 AI agent context
├── docs/                       # 📚 Detailed architecture docs
├── skills/                     # 🎯 Specialized agent skills
└── handoffs/                   # 📋 Incident reports & lessons

---

🔄 常见工作流

📥 从 Internet Archive 导入书籍

// From the UI or via API
POST /api/books
{
  "ia_id": "thehermetic00fludd",
  "title": "The Hermetic and Alchemical Writings",
  "author": "Arthur Edward Waite",
  "language": "en",
  "ustc_id": "123456"
}

系统将：

1. 📥 从 IA IIIF 获取页面图像
2. ✂️ 检测分割并生成裁剪坐标
3. 📤 加入 OCR 和翻译队列
4. 🌍 处理完成后发布

✂️ 处理分割书籍

1. 🖥️ 访问 /book/[id]/split
2. 🖱️ 在界面中调整分割线（拖动或使用 Gemini AI 自动检测）
3. ✅ 点击“Apply Split”——通过裁剪坐标创建两个虚拟页面
4. 📸 保留原始图像；OCR 在裁剪后的版本上运行

✍️ 使用 Gemini Batch API 批量进行 OCR

POST /api/books/[id]/batch-ocr-async
{
  "page_ids": ["page-1", "page-2", "page-3"],
  "language": "la"
}

返回一个作业 ID；Gemini 在后台处理，并在完成后保存结果。成本比标准 API 低 50%。

🎓 生成学术版

POST /api/books/[id]/editions
{
  "title": "The Emerald Tablet: First Complete English Translation",
  "translator": "Jane Doe",
  "language": "en",
  "format": "epub"
}

系统将生成：

• 📝 学术版前置内容（引言、译者简介等）
• 📱 带目录和元数据的 EPUB
• 🆔 通过 Zenodo 集成获取 DOI
• 📚 引用元数据（BibTeX、RIS）

---

🧪 测试

🚀 运行测试

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# End-to-end tests (Playwright)
npm run test:e2e

# Coverage report
npm run test:coverage

# Watch mode
npm run test:watch

✅ E2E 测试示例

• 📥 书籍导入 — 验证 IA 摄取流水线
• ✂️ 分割检测 — 验证书沟检测准确性
• 🌐 翻译 — 确认源文与译文对齐
• 🔒 租户子域名 — 确保内容隔离（无泄漏）
• 🔍 搜索 — 测试全文和语义索引

---

🚀 部署

🔄 暂存环境（预览）

每次推送分支后都会自动部署到 Vercel 预览环境：

git push origin feat/my-feature
# ↓ Vercel builds and deploys
# ↓ Preview URL in GitHub PR

🌍 生产环境

通过 PR 合并到 main → 自动部署到 sourcelibrary.org

✅ 部署前检查清单：

• 测试通过（npm run test）
• TypeScript 检查通过（npx tsc --noEmit）
• 不含硬编码的机密信息或凭据
• 租户子域名泄漏审计通过（node scripts/audit-bph-leaks.mjs）
• PR 已审核并批准

🔑 环境变量

必需（.env.local）：

MONGODB_URI=mongodb+srv://...
NEXTAUTH_SECRET=<random-secret>
GOOGLE_API_KEY=<gemini-key>
VERCEL_BLOB_TOKEN=<vercel-blob-token>
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

可选：

STRIPE_SECRET_KEY=<for-donations>
ZENODO_TOKEN=<for-doi-minting>
SUPABASE_URL=<for-embeddings>

---

📖 文档

• 🗺️ 系统地图 — 完整的架构图和文件索引
• 🏗️ ARCHITECTURE.md — 数据模型、工作流和设计决策
• 🤖 AGENTS.md — 面向 AI Agent 和自动化工作程序的技术背景
• 📋 CLAUDE.md — 开发工作流、PR 规范和关键约束
• 🔐 AUTH_IMPLEMENTATION.md — NextAuth 设置和租户身份验证
• 📦 批量 OCR 工作流 — 使用 Gemini Batch API
• 🔌 API 文档 — REST API 参考
• 🖼️ 图像处理 — 裁剪和调整大小的工作原理

---

🤝 参与贡献

欢迎贡献！请从 CONTRIBUTING.md 开始——其中介绍了环境设置、分支/PR 工作流、部署方式（以及你不应进行的 Vercel 设置）和数据安全规则。更深入的规范见开发工作流。简要来说：

1. 🌿 创建功能分支（从 main 分出）：

   # Using git worktree for multi-session safety
   git worktree add .claude/worktrees/feat-xyz feat/xyz
   cd .claude/worktrees/feat-xyz
   

2. ✏️ 修改并测试：

   npm run lint
   npm run test
   npm run test:e2e
   

3. 📤 推送并创建 PR：

   git push origin feat/xyz
   gh pr create --base main
   

4. 📋 PR 指引：

   • 每个 PR 只处理一个事项 — 不要将重构与功能捆绑在一起
   • 核实删除内容 — 删除代码前务必运行 grep -rn
   • 运行类型检查 — 提交前运行 npx tsc --noEmit
   • 说明范围 — 说明包含和不包含的内容

🎯 我们期待

• 🐛 修复 Bug，并提供测试覆盖
• ✨ 实现功能，与项目使命保持一致
• ⚡ 提升性能，并提供基准测试
• 📝 改进文档
• ♿ 改进用户体验/无障碍性
• 🏢 提供租户集成示例

📢 报告问题

• 🐛 Bug — 请提供复现步骤，以及预期行为与实际行为
• 💡 功能请求 — 说明使用场景和对用户的影响
• ❓ 问题 — 提交 issue

---

🛡️ 安全与数据保护

• 🚫 未经批准不得删除 — 删除任何书籍或页面都必须获得明确确认
• 🔒 租户隔离 — 租户子域名是封闭系统（不会发生跨租户数据泄露）
• 🔐 密钥管理 — 所有密钥都通过环境变量提供，绝不硬编码
• ⚖️ AGPL 许可 — 贡献内容必须遵守 AGPL-3.0-or-later

请参阅 CLAUDE.md Security，了解详细的安全政策。

---

📊 当前状态

截至 2026 年 7 月 — 数据每周更新；实时数据请访问 sourcelibrary.org/data。

📈 当前馆藏：

• 📚 约 29K 本书的 visible: true
• ✅ 约 15K 本书已完成处理（已进行 OCR 和翻译）
• 🌍 约 14K 本书拥有完整的英文译文
• 🖼️ 图库中已编目 20 万余幅插图

⚙️ 处理能力：

• 📥 每月可导入 15K+ 个页面
• 🗣️ 支持多种语言（拉丁语、德语、希腊语、阿拉伯语、梵语、中文等）
• 💰 批量 API 可降低 50% 的成本

🏢 平台租户：

• 🔮 Bibliotheca Philosophica Hermetica — 赫尔墨斯典籍与秘学
• ⚗️ Kloss Collection — 医学炼金术
• 🤝 其他合作伙伴正在开发中

---

📝 许可证

Source Library 采用 GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) 许可。所有贡献都必须遵守此许可证。

第三方许可证和署名详情请参阅 LICENSING.md。

---

📞 支持与社区

• 🐛 发现了 Bug？ 提交 issue
• 🤝 想要合作？ 参与贡献
• 🌐 访问网站 — sourcelibrary.org

---

src/
├── app/              # All routes, pages, and API endpoints
│   ├── api/          # API routes
│   ├── book/         # Book pages (detail, read, pipeline)
│   └── page.tsx      # Homepage
├── components/       # Reusable React components
├── hooks/            # Reusable React hooks for component logic
└── lib/              # Business Logic, Utilities (mongodb, ai, types), and Services