一个基于 Electron + React 的智能知识转换应用，将复杂概念转化为儿童友好的童话故事和实验。
- 童话化解释: 将复杂概念转换为8岁儿童能理解的童话故事
- 动手实验: 为每个概念提供简单的厨房小实验
- 多模态输出: 故事 + 实验 + 表情符号的完整体验
- Deepseek API: 推荐使用，性价比高，中文支持优秀
- OpenAI API: 备选方案，强大的GPT模型支持
- 智能切换: 自动选择可用提供商，支持手动切换
- 实时验证: API密钥有效性检测和连接测试
- 时间感知界面: 根据时间自动调整主题和装饰元素
- 动态动画: 流畅的Framer Motion动画效果
- 响应式设计: 适配不同屏幕尺寸
- 直观设置: 可视化API配置界面
- 一键保存: 导出为Markdown格式，兼容Obsidian
- 本地存储: 安全的本地配置管理
- 环境变量: 标准的.env配置方式
- Node.js 18+
- npm 或 yarn
- macOS/Windows/Linux
-
克隆项目
git clone <repository-url> cd magic-treehouse
-
安装依赖
npm install # 或 yarn install -
配置API密钥
复制环境变量模板：
cp .env.example .env
编辑
.env文件，至少配置一个API密钥：# 推荐：Deepseek API (性价比高，中文支持好) DEEPSEEK_API_KEY=sk-your-deepseek-key-here # 可选：OpenAI API OPENAI_API_KEY=sk-your-openai-key-here
-
启动应用
# 开发模式 npm run dev # 构建生产版本 npm run build # 打包应用 npm run dist
Deepseek API (推荐)
- 访问: https://platform.deepseek.com/api_keys
- 注册并创建API密钥
- 成本低，中文支持优秀
OpenAI API
- 访问: https://platform.openai.com/api-keys
- 注册并创建API密钥
- 功能强大，适合复杂推理
Frontend: React 18 + TypeScript + Framer Motion
Backend: Electron Main Process + Node.js
Build: Electron Vite + Vite 5
UI: Lucide React Icons + CSS3 Animations
AI: OpenAI SDK + Axios (Deepseek)
magic-treehouse/
├── src/
│ ├── main/ # Electron主进程
│ │ ├── index.ts # 应用入口和IPC处理
│ │ └── ai-service.ts # AI服务管理器
│ ├── preload/ # 预加载脚本
│ │ ├── index.ts # IPC API暴露
│ │ └── typed.d.ts # 类型定义
│ └── renderer/ # React渲染进程
│ ├── App.tsx # 主应用组件
│ ├── Settings.tsx # 设置界面
│ ├── index.css # 样式文件
│ └── main.tsx # React入口
├── resources/ # 应用资源
├── out/ # 构建输出
├── .env # 环境变量配置
├── .env.example # 环境变量模板
├── package.json # 项目配置
├── electron.vite.config.ts # 构建配置
└── tsconfig.json # TypeScript配置
class AIService {
// 多提供商管理
private providers: Map<string, AIProvider>
// 智能提供商选择
initializeProviders()
// API密钥验证
validateSingleApiKey(provider, apiKey)
// 知识转换核心
kidify(topic: string): Promise<AIResponse>
}- 环境变量加载和验证
- IPC通信处理
- 窗口管理
- API设置持久化
- 时间感知UI主题
- 动态装饰元素
- 实时状态显示
- 交互式输入界面
# Deepseek API配置 (推荐)
DEEPSEEK_API_KEY=sk-your-key-here
# OpenAI API配置 (可选)
OPENAI_API_KEY=sk-your-key-here- 开发模式: 热重载，开发者工具
- 生产构建: 代码压缩，性能优化
- 应用打包: 跨平台可执行文件
- API提供商: 支持运行时切换
- 连接测试: 实时验证API可用性
- 模型列表: 动态获取可用模型
- 状态监控: 实时显示服务状态
- 启动应用
- 如未配置API，会自动打开设置界面
- 输入想要了解的复杂概念
- 点击"变童话"获取结果
- 可选择保存为Markdown文件
- 提供商切换: 在设置中选择不同的AI服务
- 连接测试: 验证API密钥有效性
- 模型查看: 查看当前可用的AI模型
- 时间主题: 界面会根据时间自动调整
{
"story": "用童话方式解释的概念",
"experiment": "相关的厨房小实验",
"emoji": "相关表情符号"
}- API密钥仅存储在本地.env文件
- 不会上传到任何服务器
- 界面中密钥默认隐藏显示
- 仅与官方API端点通信
- 支持连接超时和错误处理
- 安全的HTTPS通信
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 类型检查
npx tsc --noEmit
# 代码格式化
npx prettier --write src/# 构建应用
npm run build
# 打包为可执行文件
npm run dist
# 仅打包不压缩
npm run pack- 使用Electron开发者工具
- 查看主进程和渲染进程日志
- 利用IPC通信调试
- 环境变量状态检查
// 知识转换
kidify(topic: string): Promise<AIResponse>
// 提供商管理
getAIProviders(): Promise<{available: string[], current: string}>
setAIProvider(name: string): Promise<boolean>
// 设置管理
getAPISettings(): Promise<APISettings>
saveAPISettings(settings: APISettings): Promise<boolean>
testAPIConnection(provider: string, key: string): Promise<TestResult>
// 状态检查
checkAPIStatus(): Promise<StatusInfo>
getAvailableModels(): Promise<ModelInfo[]>interface AIProvider {
name: string
kidify(topic: string): Promise<AIResponse>
}
interface AIResponse {
story: string // 童话故事
experiment: string // 实验说明
emoji: string // 相关表情
}API连接失败
- 检查网络连接
- 验证API密钥格式
- 确认账户余额充足
设置保存失败
- 检查.env文件权限
- 确认磁盘空间充足
- 重启应用重新加载
界面显示异常
- 清除应用缓存
- 检查开发者控制台错误
- 更新到最新版本
应用提供详细的调试日志，包括：
- 环境变量加载状态
- API密钥验证结果
- 提供商初始化过程
- 网络请求详情
- Fork项目
- 创建功能分支
- 提交代码变更
- 创建Pull Request
- 使用TypeScript严格模式
- 遵循ESLint配置
- 添加适当的类型注解
- 编写清晰的注释
- 单元测试覆盖核心功能
- 集成测试验证IPC通信
- 手动测试用户界面
本项目采用 Apache License 2.0 许可证 - 查看 LICENSE 文件了解详情。
Fenwii AGI
如有问题或建议，请通过以下方式联系：
- 📧 Email: samir.tan.it@gmail.com
- 🐛 Issues: 在GitHub仓库中提交问题
- 💡 Feature Requests: 欢迎提交功能建议
- Electron - 跨平台桌面应用框架
- React - 用户界面库
- Framer Motion - 动画库
- OpenAI - AI API服务
- Deepseek - 高性价比AI服务
Magic Treehouse - 让复杂知识变得简单有趣 🌟