Hypat.ai
Hypat.ai是一个专门的模型上下文协议（MCP）服务器，它将时事通讯电子邮件转换为有组织的知识系统。它建立在GongRzhe/Gmail MCP服务器之上，专为订阅多份时事通讯的知识工作者而设计。
 ](https://github.com/slicer2016/hypat.ai/actions/workflows/test.yml) ](https://www.npmjs.com/package/hypat.ai)
概述
Hypat.ai通过自动识别、分类和消化您的时事通讯订阅，帮助您管理时事通讯过载。它提取有价值的内容，并根据您的喜好提供个性化摘要。
该系统由多个模块组成：
- 通讯检测模块：标识电子邮件是否为时事通讯
- 内容处理模块：从新闻通讯中提取和处理内容
- 分类模块：按类别和主题组织时事通讯
- 电子邮件摘要模块：生成并发送时事通讯内容的电子邮件摘要
- 用户反馈模块：收集和处理用户反馈以提高检测效率
特性
- 自动检测时事通讯：在您的电子邮件收件箱中识别新闻通讯
- 内容提取：从时事通讯中提取和处理内容
- 智能分类：按类别和主题组织通讯
- 摘要生成：生成每日、每周或自定义的时事通讯内容摘要
- 用户反馈：通过用户反馈改进检测和分类
- MCP集成：与Gmail MCP服务器无缝集成
- 互动演示：通过我们全面的演示试用该系统
入门指南
先决条件
- Node.js 18.x或更高版本
- npm 9.x或更高版本
- Gmail帐户（用于完整功能）
安装
# Install globally
npm install -g hypat.ai
# Or install as a project dependency
npm install hypat.ai快速开始
- 安装软件包：
npm install hypat.ai- 创建配置文件：
cp node_modules/hypat.ai/config.example.json config.json- 使用您的设置编辑配置文件
- 运行演示以探索功能：
npx hypat demo- 启动服务器：
npx hypat start电子邮件摘要模块
电子邮件摘要模块负责生成和传递时事通讯内容的电子邮件摘要。它提供以下功能：
- 生成每日、每周和自定义的时事通讯内容摘要
- 使用MJML创建响应式HTML电子邮件模板
- 根据时区意识安排摘要交付
- 发送具有跟踪功能的电子邮件
- 跟踪打开和点击的电子邮件
- 管理用户对摘要传递的偏好
建筑
电子邮件摘要模块采用模块化、基于组件的架构构建：
- Digest生成器：从时事通讯数据创建摘要内容
- 电子邮件，：使用MJML模板呈现摘要内容
- 电子邮件投递时间表：在了解时区的情况下安排电子邮件发送
- 电子邮件发送者：使用nodemailer发送电子邮件
- DeliveryTracker：跟踪电子邮件传递状态、打开和单击
- 用户首选：管理摘要交付的用户首选项
- Digest服务：编排所有摘要组件
用法
要使用电子邮件摘要模块，您需要初始化组件并将其连接起来：
import { createDigestService } from 'hypat.ai';
// Create the digest service with all components wired up
const digestService = createDigestService(
contentProcessor, // Your ContentProcessor implementation
categorizer, // Your Categorizer implementation
{
// SMTP configuration for email sending
host: 'smtp.example.com',
port: 587,
secure: false,
auth: {
user: 'user@example.com',
pass: 'password'
}
}
);
// Start scheduling digests
digestService.scheduleDigests();模板
电子邮件摘要模块使用MJML模板创建响应式HTML电子邮件。该模块附带了几个内置模板：
- 每日标准：标准每日摘要模板
- 周标准：标准每周摘要模板
- 验证：电子邮件验证模板
您可以通过将模板放置在 src/core/digest/templates 目录。
定制
电子邮件摘要模块可以通过多种方式进行定制：
- 模板：为不同的摘要格式创建自定义MJML模板
- 频率：配置消化频率（每日、每周、双周、每月）
- 格式：配置摘要格式（简要、标准、详细）
- 分类：在摘要中包括/排除特定类别
- 通讯：在摘要中包括/排除特定的通讯
用户反馈模块
用户反馈模块负责收集和处理用户对时事通讯检测的反馈。它提供以下功能：
- 收集用户对时事通讯检测的反馈
- 为不确定的检测生成验证请求
- 分析反馈模式以确定改进
- 应用反馈以提高检测精度
- 跟踪发件人和域的用户首选项
建筑
用户反馈模块采用模块化、基于组件的架构构建：
- 反馈收集器：收集和处理用户反馈
- 验证请求生成器：为不确定的检测生成验证请求
- 饲料：分析反馈模式并产生见解
- 检测改良剂：应用反馈以提高检测效率
- 反馈库：存储和检索反馈数据
- 客户反馈服务：协调所有反馈组件
用法
要使用用户反馈模块，您需要初始化组件并将其连接起来：
import { createFeedbackService } from 'hypat.ai';
// Create the feedback service with all components wired up
const feedbackService = createFeedbackService(
newsletterDetector, // Your NewsletterDetector implementation (optional)
{
verificationExpiryDays: 7,
maxResendCount: 3,
verificationBaseUrl: 'https://hypat.ai/verify'
}
);
// Submit feedback for an email
await feedbackService.submitFeedback('user-1', 'email-1', true);
// Get feedback statistics for a user
const stats = await feedbackService.getFeedbackStats('user-1');验证流程
用户反馈模块包括用于处理不确定检测的验证过程：
- 当检测到新闻稿的置信度较低时，会生成一个验证请求
- 用户收到一封电子邮件，要求他们验证该电子邮件是否为时事通讯
- 用户点击链接确认或拒绝分类
- 收集反馈并用于改进检测
- 验证请求在可配置的时间段后过期
安装和设置
先决条件
- Node.js 18或更高版本
- npm 7或更高版本
- 具有Gmail MCP服务器设置的Gmail帐户
安装
- 克隆存储库：
git clone https://github.com/your-username/hypat.ai.git
cd hypat.ai- 安装依赖项：
npm install- 复制示例环境文件并对其进行配置：
cp .env.example .env
# Edit .env with your settings- 为您的环境创建配置文件：
cp config.example.json config.json
cp config.development.json config.development.json
# Edit config files with your settings- 构建应用程序：
npm run build- 运行数据库迁移：
npm run db:migrate配置
Hypat.ai支持多种配置方法：
- 环境变量：已设置
.env文件或直接在shell中 - JSON配置文件：使用
config.json或特定于环境的文件，如config.development.json - 命令行参数：通过CLI参数提供配置
重要配置选项
| 选项 | 描述 | 默认值 |
|---|---|---|
DATABASE_TYPE | 数据库类型（sqlite、mysql、postgresql） | sqlite |
DATABASE_FILENAME | SQLite数据库文件路径 | data/database.SQLite |
EMAIL_TRANSPORT | 电子邮件传输（smtp、ses、mock） | smtp |
EMAIL_SENDER_ADDRESS | 电子邮件发件人地址 | hypat@example.com |
LOG_LEVEL | 日志记录级别（错误、警告、信息、调试） | info |
MCP_MOCK_GMAIL | 使用模拟Gmail客户端进行开发 | false |
看 .env.example 查看完整的配置选项列表。
用法
运行应用程序
以开发模式启动应用程序：
npm run dev使用生产设置启动应用程序：
npm run start:prod运行数据库迁移：
npm run db:migrate命令行选项
Usage: hypat.ai [options]
Options:
-V, --version output the version number
-c, --config
Path to configuration file
-e, --env Environment (development, test, production) (default: "development")
-v, --verbose Enable verbose logging
--migrate Run database migrations and exit
-h, --help display help for command测试
运行所有测试：
npm test仅运行单元测试：
npm run test:unit仅运行集成测试：
npm run test:integration生成测试覆盖率报告：
npm run test:coverage发展
在开发过程中，您可以使用带有详细日志记录的开发模式：
npm run dev检查代码质量：
npm run lint
npm run typecheck示范模式
Hypat.ai包括一个全面的演示模式，使用模拟数据展示其功能。这是一种了解系统工作原理和探索其功能的好方法，而无需设置完整的Gmail集成。
运行演示
要运行演示：
npm run demo这将使用示例数据初始化系统，并指导您完成关键功能，包括：
- 带有置信度评分的通讯检测
- 内容提取和处理
- 通讯的自动分类
- 摘要生成（每日和每周）
- 用户反馈处理和检测改进
演示使用单独的SQLite数据库文件(data/demo-database.sqlite)因此，它不会干扰您的生产数据。
演示展示了什么
该演示提供了Hypat.ai功能的全面演练：
- 系统设置：如何初始化和配置系统
- 通讯检测：如何分析电子邮件以确定它们是否是时事通讯
- 内容处理：如何从时事通讯中提取和处理内容
- 分类：通讯如何自动分类和组织
- 摘要生成：如何从处理过的时事通讯中创建每日和每周摘要
- 用户反馈：用户反馈如何改进检测和分类
每个部分都包括所涉及的数据和过程的详细解释和可视化示例。
演示配置
演示使用单独的配置文件(config.demo.json)设置已针对演示进行了优化：
- 使用模拟Gmail客户端，而不是连接到真实的Gmail API
- 使用单独的SQLite数据库作为演示数据
- 预先配置示例用户和首选项
- 使用彩色控制台输出以实现更好的可视化
您可以通过编辑自定义演示 config.demo.json 更改设置，如：
- 要生成的样本通讯数量
- 要创建的用户
- 要包括的类别
- 是运行整个工作流程还是仅运行特定部分
演示后的后续步骤
在浏览演示后，您可能想：
- 建立真正的集成：使用Gmail MCP服务器配置系统以与您的Gmail帐户一起使用
- 自定义类别：定义与您的时事通讯兴趣相匹配的类别
- 配置您的摘要首选项：为摘要电子邮件设置投递偏好
- 部署到服务器：在服务器上设置Hypat.ai以实现连续运行
请参阅 安装和设置 有关如何开始实际部署的详细信息，请参阅第节。
故障排除
常见问题
数据库连接错误
问题: Error: SQLITE_CANTOPEN: unable to open database file
解决方案:
- 确保数据库目录存在并且可写
- 检查配置中的数据库路径
- 对于SQLite，尝试创建数据库目录：
mkdir -p data
模板渲染问题
问题: Error: Cannot find template: daily-standard
解决方案:
- 验证配置中的模板目录路径
- 检查模板文件是否存在并且可读
- 对于开发，请尝试使用简化的模板渲染器
Gmail MCP连接错误
问题: Error: Failed to connect to Gmail MCP Server
解决方案:
- 验证您的Gmail MCP服务器是否正在运行且可访问
- 检查网络连接和防火墙设置
- 在开发中，尝试使用模拟Gmail客户端：
MCP_MOCK_GMAIL=true
电子邮件发送问题
问题: Error: Failed to send email
解决方案:
- 验证SMTP设置（主机、端口、凭据）
- 检查SMTP服务器是否需要身份验证
- 为了进行测试，请使用模拟电子邮件传输：
EMAIL_TRANSPORT=mock
日志记录
要启用更详细的日志记录：
LOG_LEVEL=debug npm run dev或者使用verbose标志：
npm run dev -v日志输出到控制台和 logs 目录（如果启用了文件日志记录）。
有用的命令
检查数据库状态：
sqlite3 data/database.sqlite ".tables"测试电子邮件配置：
npm run dev -- --config test-email清除缓存：
rm -rf data/cache/*许可证
国际协调委员会