# bible

**Repository Path**: agent_001/bible

## Basic Information

- **Project Name**: bible
- **Description**: 圣经agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 圣经 Agent — 工程说明

前端：**uni-app**（可编译到 H5 / 小程序 / App）。  
后端：**FastAPI + RAG**，Python 依赖由 **[uv](https://docs.astral.sh/uv/)** 管理（`backend/pyproject.toml` + `backend/uv.lock`；镜像构建同样走 uv）。

PRD 见 [PRD.md](./PRD.md)。

---

## 安全提示

若 API Key 曾在截图、聊天或公开仓库中泄露，请**立即在各平台控制台轮换密钥**。本仓库仅提供 `.env.example`，**不包含**真实 Key。

---

## 前端功能概览

| 能力 | 说明 |
|------|------|
| **阅读** | 译本 / 书卷 / 章节选择，经文展示，连续朗读（TTS），滑动翻章 |
| **问答** | 经文问答与多模式对话，流式输出，引用可跳转回读经页 |
| **学习** | 本地记录阅读、朗读、搜索、问答/祷告；支持详情展示与跳转到对应页 |
| **祷告** | 灵修内容生成（流式），语音输入 |
| **信经与主祷文** | 使徒信经、主祷文全文；点击标题朗读（TTS）；首页侧栏也可进入 |
| **顶栏** | 自定义导航；任意主 Tab 页点击 **「圣经agent」** 进入信经页 |

界面采用**暖色、高对比、较大字号**，面向中老年使用者阅读与点击。

---

## 目录结构（与规划对齐，前端为 uni-app）

```
bible/
├── .env.example
├── .gitignore
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── README.md
├── PRD.md
├── backend/
│   ├── main.py              # FastAPI 入口
│   ├── config.py
│   ├── pyproject.toml
│   ├── uv.lock
│   ├── api/
│   │   ├── chat.py          # 对话（RAG + LLM）
│   │   ├── bible.py         # 经文查询（只读本地库）
│   │   └── prayer.py        # 祷告/灵修生成（经文仍来自本地检索）
│   ├── core/
│   │   ├── rag.py           # 检索增强：先查本地经文与注释索引
│   │   ├── bible_loader.py  # 加载、校验经文 JSON/SQLite
│   │   ├── prompt.py        # 神学与安全约束提示词
│   │   └── embedding.py     # 向量化
│   ├── models/
│   │   └── llm.py           # OpenAI 兼容多模型调用
│   ├── service/
│   │   ├── search_service.py
│   │   └── generate_service.py
│   ├── utils/
│   │   ├── verse_parser.py
│   │   └── logger.py
│   ├── data/                # 数据目录（与代码同在后端目录下）
│   │   ├── bible/           # 多译本正文（授权数据自备）
│   │   ├── commentaries/    # 注释等（版权合规）
│   │   └── topics/
│   ├── static/              # TTS 缓存音频等（可选 URL：`/_backend/static`，音频主路径为 /api/tts/audio）
│   ├── logs/                # 运行日志（可选）
│   └── vector_db/chroma/    # Chroma 持久化（git 忽略内容，保留目录）
├── frontend/                # uni-app
│   ├── App.vue
│   ├── main.js
│   ├── pages.json
│   ├── manifest.json
│   ├── package.json
│   ├── static/              # 前端静态资源（与后端 backend/static 不同）
│   ├── components/
│   │   ├── BibleReader.vue
│   │   ├── ChatBox.vue
│   │   ├── PrayerGenerator.vue
│   │   ├── BottomNav.vue        # 底部四 Tab
│   │   └── BrandNavBar.vue      # 顶栏「圣经agent」，点击进入信经页
│   ├── pages/
│   │   ├── home.vue             # 阅读（自定义顶栏 + 侧栏阅读设置）
│   │   ├── ask.vue              # 问答
│   │   ├── study.vue            # 学习记录
│   │   ├── prayer.vue           # 祷告/灵修
│   │   └── creed.vue            # 使徒信经与主祷文
│   └── utils/
│       ├── recordsStorage.js    # 学习记录本地存储
│       ├── bookDisplayName.js   # 书卷 id → 中文名展示
│       └── ttsClient.js         # TTS 合成与播放（信经页等复用）
```

---

## 学习记录与跨页跳转（前端约定）

本地存储键 `bible_learning_records_v1`（见 `frontend/utils/recordsStorage.js`）。

从「学习」页跳转到阅读 / 搜索 / 问答 / 祷告时，使用 `uni.setStorageSync` 写入待消费参数，再 `reLaunch` 到目标页，避免事件在目标页未挂载时丢失：

| 键 | 用途 |
|----|------|
| `bible_pending_reader_nav` | 打开读经页并定位书卷、章节（可选经节） |
| `bible_pending_reader_search` | 打开首页并切到查找 Tab、执行搜索 |
| `bible_pending_ask` | 问答页预填问题与模式 |
| `bible_pending_prayer` | 祷告页预填内容 |

读经组件 `BibleReader.vue` 初始化后会读取并清除上述与阅读相关的键。

---

## 经文必须「真实」的实现要点

1. **展示与引用**：用户看到的经文字符串**只**来自 `backend/data/bible`（经 `bible_loader` 读取）。  
2. **RAG**：`core/rag.py` 先检索章节/向量命中，再将**检索到的经文片段**注入提示词；LLM 只负责解释、归纳、大纲，**不得**作为经文来源。  
3. **可选校验**：返回前解析模型输出中的引用，与 `verse_parser` + 本地库比对，不一致则降级提示或重试。

---

## 后端框架与实现逻辑

详见 [backend/README.md](./backend/README.md)（FastAPI 路由、`bible_loader`、RAG 检索、`generate_service` 与 chat/prayer 流程等）。

---

## 环境与依赖（uv）

- **Python**：`>= 3.11`（与 `backend/pyproject.toml` 中 `requires-python` 一致）。  
- **安装 uv**（任选其一）：见官方文档 [Installing uv](https://docs.astral.sh/uv/getting-started/installation/)；常见如 macOS：`brew install uv`。  
- **常用命令**（在 `bible/backend` 下执行）：`uv sync` 按锁文件装依赖；`uv run <命令>` 使用项目虚拟环境；把依赖树刷新到当前 PyPI 最新可解版本：`uv lock --upgrade` 后再 `uv sync`。

---

## 后端启动（开发）

```bash
cd bible/backend
uv sync
cp ../.env.example ../.env   # 再编辑 ../.env 填入 Key
uv run uvicorn main:app --host 0.0.0.0 --port 8788 --reload
```

生产本机也可用：`uv run gunicorn main:app -w 2 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8788 --timeout 120`（与 [deploy.md](./deploy.md) 一致）。

## Docker Compose 部署（推荐）

```bash
cd bible
cp .env.example .env
docker compose build
docker compose up -d
```

镜像内通过 **uv** 执行 `uv sync --frozen` 安装依赖，与本地锁文件一致。  
接口健康检查：`http://localhost:8788/api/health`  
完整步骤见 [deploy.md](./deploy.md)。

## 前端（uni-app）

使用 HBuilderX 或 CLI 打开 `frontend`：`manifest.json` 中 H5 开发代理指向本机后端（默认 `http://127.0.0.1:8788`）。**生产环境**不使用 Nginx 时，在 `.env` 设置 **`BIBLE_H5_DIST`** 由 FastAPI 同端口提供 H5，访问 **`http://8.153.174.1:8788`**（详见 [deploy.md](./deploy.md)）；小程序需配置合法域名。

更细的前端运行方式见 [frontend/README.md](./frontend/README.md)。

---

## 大模型配置

在 `.env` 中配置 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`（OpenAI 兼容）。支持切换 MiniMax、DeepSeek、通义、火山方舟、Mimo 等，只需改基址与模型名。

---

## 面试怎么讲这个项目

可以按「业务价值 -> 技术方案 -> 难点取舍 -> 结果」来讲。

**30 秒版本（电梯陈述）**

“我做了一个圣经 AI 助手，核心是把‘经文真实性’放在第一位。  
架构上是 uni-app 前端 + FastAPI 后端 + RAG，用户看到的经文只来自本地授权库，模型只做解释和组织，不直接生成正文。  
我还做了跨页状态与朗读进度管理，解决了移动端页面切换、设置变更时的播放竞态问题，让产品在真实使用场景下稳定可用。”

**2 分钟版本（展开）**

- **业务目标**：面向真实使用场景（阅读、问答、祷告、学习记录），重点解决“AI 容易编造经文”的信任问题。  
- **核心设计**：经文展示链路与生成链路分离；展示只读本地 `backend/data/bible`，问答走 RAG 检索后再交给 LLM 做解释。  
- **关键实现**：  
  - 统一书卷/章节数据结构与检索接口，支持前端阅读、搜索、问答引用跳转复用；  
  - 朗读（TTS）加入跨页停止、进度持久化、恢复定位、高亮定位；  
  - 设置变更时先停播再切换，并加“最新设置优先”防竞态，避免异步请求回写旧状态。  
- **工程化**：配置项环境化（模型、数据目录、向量库目录）；后端依赖 **uv + lockfile** 可复现安装；目录结构清晰，便于部署与扩展多译本/多模型。  
- **结果**：在保证经文可信的前提下，兼顾了可用性与稳定性，产品闭环完整（阅读 -> 提问 -> 记录 -> 回看/跳转）。

**面试官常问与可答点**

- **Q：你最难的点是什么？**  
  A：不是调用模型，而是“状态一致性”。例如朗读中改阅读设置，涉及音频上下文、异步请求、页面生命周期并发，需要通过停播栅栏 + token 机制保证最终一致。  
- **Q：为什么不用模型直接背经文？**  
  A：因为有幻觉风险。我的方案是把“正文来源”强约束为本地授权数据，模型只做解释层，这样结果可核验。  
- **Q：如果继续优化？**  
  A：会做引用自动校验、分层缓存（章节与TTS）、以及更细粒度的观测指标（检索命中率、引用正确率、TTS失败率）。

---

## 简历中怎么写这个项目

建议结构：**项目名称 + 一句话定位 + 技术栈 + 3-5 条结果导向要点**。  
写法尽量用“动词 + 方案 + 结果”，并带可量化指标（没有真实数据可先用区间或过程指标）。

**项目名称（示例）**

`圣经 Agent（全栈 / AI 应用）`

**一句话定位（示例）**

“基于 uni-app + FastAPI + RAG 的圣经问答与阅读助手，确保经文正文仅来自本地授权库，降低模型幻觉带来的错引风险。”

**技术栈（示例）**

`uni-app`、`Vue`、`FastAPI`、`uv`、`RAG`、`Chroma`、`OpenAI Compatible API`、`TTS`

**经历要点（可直接放简历）**

- 设计并实现“**经文展示链路与生成链路分离**”：展示层仅读取本地 `backend/data/bible`，生成层基于 RAG 检索结果进行解释，提升内容可核验性。  
- 搭建后端检索与生成流程（经文检索、问答、祷告、多模式输出），沉淀统一 API，支撑阅读、搜索、问答与引用跳转等前端场景复用。  
- 完成移动端朗读能力（TTS）与状态治理：实现跨页停止、断点恢复、定位高亮、设置变更优先级控制，修复页面切换与异步并发导致的播放错乱。  
- 构建学习记录闭环（阅读/朗读/搜索/问答）与跨页参数传递机制，支持历史回看并一键回到对应书卷章节，提升连续学习体验。  
- 推进工程可维护性：环境变量配置化（模型、数据目录、向量库目录）；后端用 **uv** 与锁文件管理依赖，规范目录与文档，降低部署与协作成本。

**量化表达模板（按真实情况替换）**

- “将经文引用错误相关反馈从 **X%** 降至 **Y%**（或显著减少）。”  
- “朗读相关问题（串音/错位）复现率由 **X 次/天** 降为 **Y 次/天**。”  
- “关键接口平均响应从 **X ms** 优化到 **Y ms**（检索/章节加载）。”  
- “需求迭代周期从 **X 天** 缩短到 **Y 天**（通过模块复用与配置化）。”

**不同岗位的一句话版本**

- **前端岗**：突出“多端体验、状态一致性、交互稳定性（朗读与跨页）”。  
- **后端岗**：突出“RAG 检索链路、数据真实性约束、API 设计与可扩展性”。  
- **全栈岗**：突出“从数据可信到前端体验的端到端闭环交付”。

---

## 对标与差异化（摘要）

对标 Bible Chat / Bible GPT、Biblia、SermonAI、Bible.ai 等；本案差异化方向见 [PRD.md](./PRD.md)「差异化目标」：以**可核验经文 + RAG + 学习记录 + 隐私可选**为核心，不依赖模型记忆充当经文来源。