Agente Mangas

Manga Agent - 人工智能漫画管理系统

完整的人工智能漫画管理系统，使用Gemini AI对话聊天和语义搜索。

 ](https://nodejs.org/) ](https://www.docker.com/)  

______________________________________________________________________

主要特点

• 🤖 聊天com IA： 使用自然语言与助手讨论您的漫画
• 🔍 语义搜索: 使用矢量嵌入查找简介相似性的漫画
• 📚 多重标题支持不同语言的替代名称
• 📊 进度跟踪跟踪已阅读的章节和阅读历史记录
• ⏰ 提醒系统新章节和更新的通知
• 🏷️ 智能标签按性别、人口和主题分类
• 🎨 现代界面：前端React 19+Chakra UI 3
• 🐳 完整码头设置热重载和数据持久性
• 🔌 MCP服务器与 AI 代理人的通信协议

______________________________________________________________________

堆栈技术

后端

• 运行时：Node.js 22+TypeScript
• API REST：Express.js
• 人工智能：谷歌双子座（双子座-2.5-flash+双子座-001）
• 数据库PostgreSQL 15 + pgvector（768维向量嵌入）
• 日志记录：温斯顿
• 主控程序：模型上下文协议服务器

前端

• 框架：反应19
• 用户界面库：脉轮UI 3.30.0
• 生成工具：快
• 语言：TypeScript

基础设施

• 容器化：Docker+Docker组合
• 网络服务器Nginx（生产）
• PostgreSQL 扩展：uuid ossp、pg_trgm、pgvector
• 热重新加载自动重新装入开发

______________________________________________________________________

项目结构

agente-mangas/
├── backend/              # Backend Node.js + API REST + MCP Server
│   ├── src/
│   │   ├── api/         # Express REST endpoints
│   │   ├── mcp/         # MCP Server e ferramentas
│   │   ├── services/    # Lógica de negócio e IA
│   │   ├── repositories/# Camada de acesso a dados
│   │   ├── models/      # Modelos de dados
│   │   └── config/      # Configurações e env
│   └── Dockerfile       # Multi-stage build (dev/prod)
│
├── frontend/            # Frontend React SPA
│   ├── src/
│   │   ├── components/  # Componentes reutilizáveis
│   │   ├── pages/       # Páginas da aplicação
│   │   ├── services/    # Cliente API
│   │   └── theme/       # Tema customizado Chakra UI
│   ├── Dockerfile       # Multi-stage build
│   └── nginx.conf       # Config Nginx para produção
│
├── storage/             # Dados persistentes (não versionado)
│   ├── images/          # Capas dos mangás
│   ├── postgres/        # Dados PostgreSQL
│   │   ├── db/          # Volume do banco
│   │   └── init.sql     # Schema inicial
│   └── temp/            # Arquivos temporários
│
├── docs/                # Documentação técnica
│   ├── API.md           # Documentação API REST
│   ├── MCP_SETUP.md     # Setup MCP Server
│   └── FRONTEND_GUIDE.md# Guia do frontend
│
├── docker-compose.yml   # Orquestração de 4 serviços
├── .env.example         # Template de variáveis
├── .gitignore           # Arquivos ignorados
├── DOCKER-SETUP.md      # Guia completo Docker
└── README.md            # Este arquivo

______________________________________________________________________

先决条件

• 码头工人 e Docker Compose 已安装
• Gemini API密钥 - 在这里免费获取
• （可选） Node.js 22+ 无需 Docker 的本地开发

______________________________________________________________________

快速安装

1. 克隆仓库

git clone https://github.com/HiranHabiff/agente-mangas.git
cd agente-mangas

2. 设置环境变量

# Copie o template
cp .env.example .env

# Edite o arquivo .env
nano .env  # ou use seu editor preferido

必需变量 ：

GEMINI_API_KEY=sua_chave_api_gemini_aqui
DB_PASSWORD=senha_forte_postgresql
PGADMIN_PASSWORD=senha_pgadmin

3. 启动所有服务

docker-compose up -d

等待 30 秒，所有容器启动。

4. 检查状态

docker-compose ps

所有服务都必须有状态 Up （健康）。

5. 访问应用程序

• 前端（接口负责人）: http://localhost:5173
• API REST（后端）: http://localhost:3000/api
• pgAdmin （数据库管理器）: http://localhost:5050

pgAdmin 凭据 ：

• 电子邮件： admin@manga.com
• 密码 : （值为 PGADMIN_PASSWORD 没有.env）

______________________________________________________________________

服务和门

______________________________________________________________________

如何使用

1.界面Web（前端）

访问http://localhost:5173你会看到：

• 仪表盘统计和软管概述
• 芒果列表： 所有带过滤器的软管
• 寻找按名称，标签，简介搜索
• 聊天IA： 与助理讨论您的软管
• 细节每个漫画的完整信息

2.API REST

REST API 可在 http://localhost:3000/api

主要终端：

# Listar todos os mangás
GET /api/mangas

# Buscar por nome
GET /api/mangas/search?q=naruto

# Detalhes de um mangá
GET /api/mangas/:id

# Estatísticas
GET /api/stats

# Tags disponíveis
GET /api/tags

# Busca semântica (embeddings)
POST /api/mangas/semantic-search

使用范例：

# Listar mangás
curl http://localhost:3000/api/mangas | jq

# Estatísticas
curl http://localhost:3000/api/stats | jq

3.聊天室IA

在前端，进入 聊天 自然地说话：

Você: "Quais mangás de ação eu tenho?"
IA: "Você tem 15 mangás de ação, incluindo..."

Você: "Recomende algo parecido com Tower of God"
IA: [Usa busca semântica e recomenda títulos similares]

Você: "Marque que li até o capítulo 50 de Naruto"
IA: "Atualizado! Você está no capítulo 50 de Naruto."

4. MCP 服务器（代理集成）

后端显示一个 MCP服务器 它允许与AI代理集成。

要配置，请参阅： docs/MCP_SETUP.md

通过MCP提供的工具：

• list_mangas -清单
• search_manga -搜索句柄
• get_manga_details 一个漫画的细节
• update_reading_progress - 更新进度
• add_tag - 添加标签
• create_reminder - 创建提醒
• ai_recommend AI的建议
• semantic_search 寻找相似性

______________________________________________________________________

有用的命令

容器管理

# Iniciar todos os serviços
docker-compose up -d

# Parar todos os serviços
docker-compose down

# Ver logs em tempo real
docker-compose logs -f

# Ver logs de um serviço específico
docker-compose logs -f backend

# Reiniciar um serviço
docker-compose restart backend

# Reconstruir após mudanças
docker-compose up -d --build

# Parar e remover volumes (CUIDADO: apaga dados)
docker-compose down -v

Acessar集装箱

# Shell do backend
docker-compose exec backend sh

# Shell do PostgreSQL
docker-compose exec postgres psql -U manga_user -d manga_db

# Ver estrutura do banco
docker-compose exec postgres psql -U manga_user -d manga_db -c "\dt"

# Query SQL
docker-compose exec postgres psql -U manga_user -d manga_db -c "SELECT COUNT(*) FROM mangas;"

开发

# Ver código em tempo real (hot reload está ativo)
# Edite arquivos em backend/src/ ou frontend/src/
# As mudanças são detectadas automaticamente

# Ver variáveis de ambiente do backend
docker-compose exec backend printenv | grep -E "DB|GEMINI|PORT"

# Verificar saúde do PostgreSQL
docker-compose exec postgres pg_isready -U manga_user

______________________________________________________________________

数据库

架构主体

表格 ：

• mangas - 主要信息（标题，概述，状态，评级，嵌入）
• manga_names - 多种语言的替代标题
• tags - 类别（性别，人口，主题）
• manga_tags 软管和标签之间的N:N关系
• reminders - 通知系统
• reading_sessions - 阅读历史
• creators - 作家和艺术家

资源 ：

• ✅ UUID 主键
• ✅ 全文搜索com pg_trgm
• ✅ 矢量搜索 pgvector （768个尺寸）
• ✅ 软删除（deleted_at）
• ✅ 自动时间戳
• ✅ 触发器和函数
• ✅ 优化指数

通过 pgAdmin 访问

1. 爱搜索http://localhost:5050
2. 登录： admin@manga.com .env 密码
3. 添加服务器 →

- 姓名： Manga DB - 主持人： postgres - 端口： 5432 - 用户名： manga_user - 密码：（valor de） DB_PASSWORD)

______________________________________________________________________

故障排除

容器未启动

# Ver logs de erro
docker-compose logs

# Verificar portas em uso (Windows)
netstat -ano | findstr "3000 5173 5432 5050"

# Verificar portas (Linux/Mac)
lsof -i :3000,5173,5432,5050

# Reiniciar do zero
docker-compose down -v
docker-compose up -d

Erro“找不到GEMINI_API_KEY”

请确保：

1. 档案 .env 存在于工程根
2. 变量 GEMINI_API_KEY 已填充
3. 没有额外空间 ： GEMINI_API_KEY=sua_chave
4. 重新启动容器 ： docker-compose restart backend

PostgreSQL 无法连接

# Verificar saúde
docker-compose ps

# Deve mostrar "healthy" para postgres
# Se não, ver logs:
docker-compose logs postgres

# Testar conexão manual
docker-compose exec postgres psql -U manga_user -d manga_db -c "SELECT 1;"

Hot reload 不起作用

# Reconstruir containers
docker-compose down
docker-compose up -d --build

# Verificar se volumes estão mapeados
docker-compose exec backend ls -la /app/src

图像未显示

# Verificar se a pasta existe
ls -la storage/images/

# Testar acesso direto
curl http://localhost:3000/images/nome-do-arquivo.jpg

# Ver logs do backend
docker-compose logs backend | grep images

更多解决方案： 医生服务.md

______________________________________________________________________

生产

在生产中部署：

1. 环境变化：

   NODE_ENV=production

1. 设置强密码 ：

   DB_PASSWORD=senha_muito_forte_e_aleatoria
   PGADMIN_PASSWORD=outra_senha_forte

1. 使用HTTPS SSL COM证书（Nginx/Caddy）

1. 配置自动备份 做PostgreSQL

1. 设计pgAdmin （comente没有docker compose.yml）

1. 请参阅生产部分： 医生服务.md

______________________________________________________________________

技术文件

• 医生服务.md 完整的Docker和配置指南
• docs/API.md文件 REST API 文档
• docs/MCP_SETUP.md MCP Server 配置
• docs/FRONTEND_GUIDE.md 前端开发指南

______________________________________________________________________

贡献

欢迎捐款！为了贡献：

1. 分叉工程
2. 为您的功能创建一个分支： git checkout -b feature/MinhaFeature
3. 提交您的更改： git commit -m 'feat: adiciona MinhaFeature'
4. 按下一个分支： git push origin feature/MinhaFeature
5. Abra um Pull请求

______________________________________________________________________

许可证

此项目在许可证下 麻省理工学院查看文件 许可证 了解更多详情。

______________________________________________________________________

作者

海兰·哈比夫

• github： @希兰·哈比夫
• 项目 ： 袖剂

______________________________________________________________________

支持

• 问题:
• 文档: docs/
• 状态：🟢 正在积极开发中

______________________________________________________________________

使用 TypeScript、React、Gemini AI 和 Docker 开发 🚀