https://github.com/cris-z123/mailcopilot
📫Privacy-first local email assistant Extracts traceable tasks from emails, auto-generates daily reports. 100% source-linked, fully offline capable.
https://github.com/cris-z123/mailcopilot
agent electron vibe-coding
Last synced: 2 months ago
JSON representation
📫Privacy-first local email assistant Extracts traceable tasks from emails, auto-generates daily reports. 100% source-linked, fully offline capable.
- Host: GitHub
- URL: https://github.com/cris-z123/mailcopilot
- Owner: Cris-z123
- Created: 2026-01-28T15:58:06.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T15:48:18.000Z (3 months ago)
- Last Synced: 2026-04-01T16:27:47.808Z (3 months ago)
- Topics: agent, electron, vibe-coding
- Language: TypeScript
- Homepage:
- Size: 1.47 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# mailCopilot
> 智能邮件处理助手 - Email Item Traceability & Verification System
[](https://github.com/your-org/mailcopilot)
[](https://gist.github.com/Cris-z123/11757b000330f5d8d4e482164f08052d)
[](LICENSE)
[](https://electronjs.org/)
[](https://vitest.dev/)
## 📖 项目简介
mailCopilot 是一款面向隐私敏感场景的**本地邮件智能处理客户端**，通过规则引擎与本地/远程 LLM 协同，在**用户可控环境**下实现邮件内容结构化、事项提取、**100% 可溯源验证**。
### 核心特性
- ✅ **100% 事项可溯源** - 每个事项均可追溯到原始邮件来源（Message-ID 或 SHA-256 指纹）
- 🔒 **隐私优先架构** - 字段级 AES-256-GCM 加密，设备绑定存储，零知识架构
- 🎯 **智能置信度系统** - 双引擎置信度计算，低置信度事项自动标记
- 🔍 **多格式支持** - 支持主流邮件格式（.eml, .msg, .pst/.ost, .mbox, .html）
- 🌓 **双模式运行** - 本地模式（Ollama）/ 远程模式（OpenAI API）热切换，无需重启
- 💾 **设备绑定存储** - SQLite 本地数据库，WAL 模式，可配置数据保留期
- 📊 **日报生成** - 自动生成包含事项、进度、总结的日报，支持 Markdown/PDF 导出
- 🔄 **本地反馈系统** - 用户可标记事项准确性，反馈数据加密存储，永不联网
## 🚀 快速开始
### 环境要求
- **Node.js**: 20.x (LTS)
- **pnpm**: 8.x
- **操作系统**: Windows 10+, macOS 10.15+
### 本地模式要求（可选）
如果使用本地模式，需要先安装 Ollama
```
### 安装步骤
```bash
# 1. 安装依赖
pnpm install
# 2. 重建原生模块（better-sqlite3）
pnpm run rebuild
# 3. 开发模式运行
pnpm run dev
# 4. 构建生产版本
pnpm run build
# 5. 运行生产版本
pnpm run start
```
## 🏗️ 技术栈
### 核心框架
- **Electron** 29.4.6 - 跨平台桌面应用框架
- **React** 18 - 用户界面
- **TypeScript** 5.4 - 类型安全
- **Zustand** 4.5 - 状态管理
- **Tailwind CSS** v3.4 - 样式框架
- **shadcn/ui** - UI 组件库
## 🔧 开发指南
### 开发命令
```bash
# 启动开发服务器（热重载）
pnpm run dev
# 类型检查
pnpm run typecheck
# 代码检查
pnpm run lint
# 自动修复代码风格
pnpm run lint:fix
# 格式化代码
pnpm run format
```
### 测试命令
```bash
# 运行所有测试
pnpm test
# 单元测试
pnpm run test:unit
# 集成测试
pnpm run test:integration
# 安全测试
pnpm run test:security
# 代码覆盖率
pnpm run test:coverage
```
## 📖 文档
- [技术架构文档](./docs/tech-architecture.md) - 完整的技术设计说明
- [功能规格](./specs/001-email-item-traceability/spec.md) - 详细功能需求
- [LLM API 文档](./docs/api/llm-api.md) - LLM 适配器接口文档
- [部署指南](./docs/deployment.md) - 打包、签名、发布指南
- [设计系统](./docs/DESIGN_SYSTEM.md) - UI/UX 设计规范
## 🔒 安全与隐私
### 设计原则
1. **隐私优先**: 默认远程模式，完全离线可选
2. **零知识架构**: 不提供云备份，无跨设备同步
3. **防幻觉机制**: 100% 事项可溯源，无来源事项降级入库
4. **设备绑定**: 数据绑定当前设备，重装系统即数据丢失
5. **字段级加密**: 敏感字段 AES-256-GCM 加密
6. **本地反馈**: 用户反馈永不联网传输
## 🤝 贡献指南
欢迎贡献代码、报告问题或提出建议！
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
### Commit 规范
遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
```
feat: add new feature
fix: fix bug
docs: update documentation
test: add tests
refactor: refactor code
chore: update dependencies
```
## 📄 许可证
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
## 🙏 致谢
- [Electron](https://electronjs.org/) - 跨平台桌面应用框架
- [React](https://reactjs.org/) - 用户界面库
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - SQLite 同步驱动
- [Zustand](https://github.com/pmndrs/zustand) - 状态管理
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
## 📮 联系方式
- 问题反馈: [GitHub Issues](https://github.com/your-org/mailcopilot/issues)