1 line
28 KiB
JSON
1 line
28 KiB
JSON
{"repo": "beingok3/icalendar-main", "files": {"README.md": {"ad3dd6a7c2a127c998b4ea8469ff51299970cade": {"t": 1785746426.307911, "n": 9307, "h": "3ec1b60eb8061c9b", "c": "# 🗓️ iCalendar 智能日历系统\n\n[](https://www.python.org/)\n[](https://fastapi.tiangolo.com/)\n[](LICENSE)\n\n一个集成 DeepSeek AI 和 iCloud CalDAV 的现代化智能日历管理系统。通过自然语言轻松管理您的日程安排。\n\n\n\n---\n\n## ✨ 核心特性\n\n### 🤖 AI 驱动的自然语言处理\n- 使用 DeepSeek API 理解自然语言命令\n- 支持中文口语化输入\n- 智能时间解析（今天、明天、下周一等）\n- 自动提取事件标题、时间、地点\n\n**示例**：\n```\n\"明天下午3点和张三开会\"\n\"下周三上午9点到10点团队会议\"\n\"删除和里斯的会议\"\n\"把明天的会议改到后天\"\n```\n\n### 📅 完整的日历功能\n- ✅ 创建、查看、更新、删除事件\n- ✅ 支持多个日历管理\n- ✅ 拖拽调整事件时间\n- ✅ 月/周/日/列表多种视图\n- ✅ 实时同步到 iCloud\n\n### 🌐 现代化 Web 界面\n- 响应式设计，适配各种设备\n- FullCalendar 可视化日历\n- 直观的智能助手输入框\n- 平滑动画和交互效果\n\n### 🔌 双模式支持\n1. **Web 模式**：通过浏览器访问\n2. **MCP 模式**：供 Claude、ChatGPT 等 AI 助手调用\n\n---\n\n## 🚀 快速开始\n\n### 前置要求\n\n- **Python 3.12+**\n- **uv** 包管理工具\n- **iCloud 账号** 和应用专用密码\n- **DeepSeek API** 密钥\n\n### 1. 安装 uv\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### 2. 克隆项目\n\n```bash\ngit clone https://github.com/yourusername/iCalendar.git\ncd iCalendar\n```\n\n### 3. 安装依赖\n\n```bash\nuv sync\n```\n\n### 4. 配置凭据\n\n#### 4.1 创建配置文件\n\n```bash\ncp config.json.example config_private.json\n```\n\n#### 4.2 获取 iCloud 应用专用密码\n\n1. 访问 [Apple ID 管理页面](https://appleid.apple.com/)\n2. 登录您的 Apple ID\n3. 进入 **登录与安全** → **应用专用密码**\n4. 点击 **生成密码**\n5. 为密码命名（如 \"iCalendar\"）\n6. 复制生成的密码（格式：`xxxx-xxxx-xxxx-xxxx`）\n\n#### 4.3 获取 DeepSeek API 密钥\n\n1. 访问 [DeepSeek 平台](https://platform.deepseek.com/)\n2. 注册并登录账户\n3. 进入 **API Keys** 页面\n4. 创建新的 API 密钥\n5. 复制密钥（格式：`sk-xxxxxxxxxxxxxxxx`）\n\n#### 4.4 编辑配置文件\n\n```bash\n# 使用您喜欢的编辑器\nnano config_private.json\n# 或\nvi config_private.json\n# 或\nopen -a TextEdit config_private.json\n```\n\n填入您的凭据：\n\n```json\n{\n \"caldav\": {\n \"server_url\": \"https://caldav.icloud.com/\",\n \"username\": \"your_apple_id@icloud.com\",\n \"password\": \"xxxx-xxxx-xxxx-xxxx\"\n },\n \"deepseek\": {\n \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxx\",\n \"base_url\": \"https://api.deepseek.com\"\n }\n}\n```\n\n### 5. 启动服务器\n\n#### 后台运行（推荐）\n\n```bash\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n```\n\n#### 前台运行（开发调试）\n\n```bash\nuv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 --reload\n```\n\n### 6. 访问 Web 界面\n\n在浏览器中打开：**http://localhost:8000**\n\n🎉 **完成！** 现在您可以开始使用智能日历系统了！\n\n---\n\n## 📖 使用指南\n\n### 自然语言命令示例\n\n#### 创建事件\n```\n✅ \"明天下午3点提醒我开会\"\n✅ \"下周三上午9点到10点团队会议\"\n✅ \"本周五晚上8点看电影\"\n✅ \"11月15日下午2点产品发布会\"\n```\n\n#### 查询事件\n```\n✅ \"今天有什么安排？\"\n✅ \"本周有什么事情？\"\n✅ \"下个月有什么会议？\"\n```\n\n#### 更新事件\n```\n✅ \"把明天的会议改到后天\"\n✅ \"将周五的会议时间改为下午2点\"\n✅ \"把和张三的会议改到明天下午2点\"\n```\n\n#### 删除事件\n```\n✅ \"取消明天的会议\"\n✅ \"删除今天下午的活动\"\n✅ \"删除和里斯的会议\"\n```\n\n### 智能匹配功能\n\n系统支持按标题智能匹配事件：\n\n- **单个匹配**：直接执行操作\n ```\n \"删除和里斯的会议\" → ✅ 直接删除\n ```\n\n- **多个匹配**：返回列表供选择\n ```\n \"删除和张三的活动\" → \n 找到 2 个匹配的事件：\n 1. 和张三的会议 (11月12日 14:00)\n 2. 和张三喝咖啡 (11月13日 09:00)\n \n → 使用更精确的描述：\n \"删除和张三喝咖啡的活动\" → ✅ 精确删除\n ```\n\n### Web 界面功能\n\n#### 侧边栏\n- **智能助手**：输入自然语言命令\n- **快捷操作**：创建事件、回到今天、刷新\n- **日历筛选**：按日历显示事件\n- **系统状态**：在线/离线指示器\n\n#### 主日历区域\n- **视图切换**：月/周/日/列表\n- **拖拽创建**：点击日期创建事件\n- **拖拽调整**：拖动事件改变时间\n- **点击查看**：点击事件查看详情\n\n#### 快捷键（即将支持）\n- `Ctrl/Cmd + N` - 创建新事件\n- `Ctrl/Cmd + F` - 搜索事件\n- `T` - 回到今天\n\n---\n\n## 🛠️ 服务管理\n\n### 启动服务\n\n```bash\n# 后台运行\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n\n# 前台运行（开发模式）\nuv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 --reload\n```\n\n### 停止服务\n\n```bash\n# 方法 1：按进程名停止\npkill -f \"uvicorn web_client.app\"\n\n# 方法 2：强制停止占用 8000 端口的进程\nlsof -ti :8000 | xargs kill -9\n```\n\n### 检查服务状态\n\n```bash\n# 查看进程\nlsof -i :8000\n\n# 测试健康检查\ncurl http://localhost:8000/api/health\n\n# 查看服务器日志\ntail -f web_server.log\n```\n\n### 重启服务\n\n```bash\npkill -f \"uvicorn web_client.app\" && sleep 2 && \\\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n```\n\n---\n\n## 🔌 API 文档\n\n服务器启动后，访问以下地址查看完整 API 文档：\n\n- **Swagger UI**: http://localhost:8000/docs\n- **ReDoc**: http://localhost:8000/redoc\n\n### 主要 API 端点\n\n#### 健康检查\n```http\nGET /api/health\n```\n\n#### 日历管理\n```http\nGET /api/calendars\n```\n\n#### 事件 CRUD\n```http\nGET /api/events?start_date=2025-11-01&end_date=2025-11-30\nPOST /api/events\nPUT /api/events/{event_id}\nDELETE /api/events/{event_id}\n```\n\n#### 自然语言处理\n```http\nPOST /api/nl/execute\nContent-Type: application/json\n\n{\n \"text\": \"明天下午3点和张三开会\",\n \"context\": {}\n}\n```\n\n---\n\n## 📁 项目结构\n\n```\niCalendar-main/\n├── mcp_ical/ # 核心业务逻辑\n│ ├── caldav_client.py # CalDAV 客户端\n│ ├── config.py # 配置管理\n│ ├── deepseek_client.py # DeepSeek AI 集成\n│ ├── ical.py # 日历管理器\n│ ├── models.py # 数据模型\n│ └── server.py # MCP 服务器\n│\n├── web_client/ # Web 应用\n│ ├── app.py # FastAPI 主应用\n│ ├── templates/ # HTML 模板\n│ │ └── index.html\n│ └── static/ # 静态资源\n│ ├── css/\n│ │ └── style.css\n│ └── js/\n│ └── app.js\n│\n├── config_private.json # 私有配置（不提交）\n├── config.json.example # 配置模板\n├── pyproject.toml # 项目配置\n└── README.md # 本文档\n```\n\n详细架构说明请查看 [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md)\n\n---\n\n## 🧪 测试\n\n### 运行测试\n\n```bash\n# 运行所有测试\nuv run pytest\n\n# 显示详细输出\nuv run pytest -v\n\n# 运行特定测试\nuv run pytest test_calendar_manager_integration.py\n\n# 显示覆盖率\nuv run pytest --cov=mcp_ical --cov=web_client\n```\n\n### 功能测试清单\n\n- [ ] 连接到 iCloud CalDAV\n- [ ] 列出所有日历\n- [ ] 创建新事件\n- [ ] 更新现有事件\n- [ ] 删除事件\n- [ ] 查询指定时间范围的事件\n- [ ] 自然语言创建事件\n- [ ] 自然语言查询事件\n- [ ] 自然语言更新事件\n- [ ] 自然语言删除事件\n- [ ] 按标题模糊匹配事件\n- [ ] Web 界面加载和显示\n- [ ] 拖拽创建事件\n- [ ] 拖拽调整事件时间\n\n---\n\n## 🔧 故障排除\n\n### 问题 1：无法连接到 iCloud\n\n**错误信息**: \"Authentication failed\" 或 \"Connection error\"\n\n**解决方案**:\n1. ✅ 确认使用的是**应用专用密码**，不是 Apple ID 密码\n2. ✅ 检查 Apple ID 和密码是否正确\n3. ✅ 确认 iCloud 日历已启用\n4. ✅ 检查网络连接\n5. ✅ 尝试重新生成应用专用密码\n\n### 问题 2：DeepSeek API 调用失败\n\n**错误信息**: \"API key invalid\" 或 \"Rate limit exceeded\"\n\n**解决方案**:\n1. ✅ 确认 API 密钥正确无误\n2. ✅ 检查 API 配额是否充足\n3. ✅ 访问 [DeepSeek 控制台](https://platform.deepseek.com/) 查看状态\n4. ✅ 确认网络可以访问 DeepSeek API\n\n### 问题 3：端口被占用\n\n**错误信息**: \"[Errno 48] Address already in use\"\n\n**解决方案**:\n```bash\n# 查看占用 8000 端口的进程\nlsof -i :8000\n\n# 终止占用端口的进程\npkill -f \"uvicorn web_client.app\"\n# 或强制终止\nlsof -ti :8000 | xargs kill -9\n```\n\n### 问题 4：依赖安装失败\n\n**解决方案**:\n```bash\n# 清理缓存并重新安装\nrm -rf .venv\nuv sync --force\n\n# 或手动安装依赖\nuv pip install fastapi uvicorn httpx loguru caldav vobject\n```\n\n### 问题 5：无法创建事件\n\n**错误信息**: \"Forbidden\" 或 \"Permission denied\"\n\n**原因**: 尝试在只读日历（如订阅日历）中创建事件\n\n**解决方案**:\n1. ✅ 在 Web 界面中选择可写的日历\n2. ✅ 避免在\"节假日\"等订阅日历中创建事件\n3. ✅ 访问 http://localhost:8000/api/calendars 查看所有日历\n\n---\n\n## 🔐 安全建议\n\n### 配置文件安全\n- ⚠️ **永远不要**将 `config_private.json` 提交到 Git\n- ⚠️ 定期更换 API 密钥和应用专用密码\n- ⚠️ 使用环境变量存储敏感信息（生产环境）\n\n### 网络安全\n- ✅ 生产环境使用 HTTPS\n- ✅ 配置防火墙规则\n- ✅ 使用反向代理（Nginx/Caddy）\n- ✅ 限制 API 访问速率\n\n### 数据安全\n- ✅ 所有日历数据通过 HTTPS 传输\n- ✅ 凭据存储在本地配置文件\n- ✅ 不在日志中记录敏感信息\n\n---\n\n## 📊 性能优化\n\n### 前端优化\n- 事件按需加载\n- 防抖处理用户输入\n- 缓存日历列表\n- 懒加载静态资源\n\n### 后端优化\n- 异步 I/O 处理\n- 连接池复用\n- 适当的日志级别\n- 数据压缩传输\n\n---\n\n## 🚢 生产部署\n\n### 使用 Systemd（推荐）\n\n1. 创建服务文件 `/etc/systemd/system/icalendar.service`:\n\n```ini\n[Unit]\nDescription=iCalendar Web Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=your_user\nWorkingDirectory=/path/to/iCalendar\nExecStart=/path/to/.venv/bin/uvicorn web_client.app:app --host 0.0.0.0 --port 8000\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\n2. 启动服务:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable icalendar\nsudo systemctl start icalendar\n```\n\n### 使用 Nginx 反向代理\n\n配置文件 `/etc/nginx/sites-available/icalendar`:\n\n```nginx\nserver {\n listen 80;\n server_name your_domain.com;\n\n location / {\n proxy_pass http://localhost:8000;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n}\n```\n\n### Docker 部署（即将支持）\n\n```bash\ndocker-compose up -d\n```\n\n---\n\n## 🤝 贡献指南\n\n欢迎贡献代码、报告问题或提出建议！\n\n### 报告问题\n\n请在 [GitHub Issues](https://github.com/yourusername/iCalendar/issues) 中报告问题，并提供：\n\n- 问题描述\n- 复现步骤\n- 预期行为\n- 实际行为\n- 系统环境（操作系统、Python 版本等）\n- 相关日志\n\n### 提交代码\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 创建 Pull Request\n\n### 开发规范\n\n- 遵循 PEP 8 代码风格\n- 添加必要的注释和文档字符串\n- 编写单元测试\n- 更新相关文档\n\n---\n\n## 📄 许可证\n\n本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。\n\n---\n\n## 🙏 致谢\n\n### 技术栈\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Web 框架\n- [FullCalendar](https://fullcalendar.io/) - 日历组件\n- [DeepSeek](https://www.deepseek.com/) - AI 自然语言处理\n- [python-caldav](https://github.com/python-caldav/caldav) - CalDAV 客户端\n\n### 灵感来源\n- Apple Calendar\n- Google Calendar\n- Notion Calendar\n\n---\n\n## 📞 联系方式\n\n- **项目主页**: https://github.com/yourusername/iCalendar\n- **问题反馈**: https://github.com/yourusername/iCalendar/issues\n- **邮箱**: your.email@example.com\n\n---\n\n## 🗺️ 路线图\n\n### v1.0 ✅\n- [x] CalDAV 集成\n- [x] DeepSeek AI 集成\n- [x] Web 界面\n- [x] 自然语言处理\n- [x] 智能事件匹配\n\n### v1.1（规划中）\n- [ ] 循环事件支持\n- [ ] 事件提醒功能\n- [ ] 日历导入/导出\n- [ ] 移动端优化\n- [ ] 多语言支持\n\n### v2.0（未来）\n- [ ] 离线模式\n- [ ] 团队协作功能\n- [ ] 更多 AI 功能（智能建议、冲突检测）\n- [ ] 第三方日历集成（Google Calendar、Outlook）\n- [ ] Docker 支持\n- [ ] 移动应用\n\n---\n\n<div align=\"center\">\n\n**⭐ 如果觉得这个项目有帮助，请给个 Star！⭐**\n\nMade with ❤️ by iCalendar Team\n\n</div>\n"}, "f0c79360963a19a34a16d22051202be4ad6cf268": {"t": 1785764064.9566305, "n": 9307, "h": "3ec1b60eb8061c9b", "c": "# 🗓️ iCalendar 智能日历系统\n\n[](https://www.python.org/)\n[](https://fastapi.tiangolo.com/)\n[](LICENSE)\n\n一个集成 DeepSeek AI 和 iCloud CalDAV 的现代化智能日历管理系统。通过自然语言轻松管理您的日程安排。\n\n\n\n---\n\n## ✨ 核心特性\n\n### 🤖 AI 驱动的自然语言处理\n- 使用 DeepSeek API 理解自然语言命令\n- 支持中文口语化输入\n- 智能时间解析（今天、明天、下周一等）\n- 自动提取事件标题、时间、地点\n\n**示例**：\n```\n\"明天下午3点和张三开会\"\n\"下周三上午9点到10点团队会议\"\n\"删除和里斯的会议\"\n\"把明天的会议改到后天\"\n```\n\n### 📅 完整的日历功能\n- ✅ 创建、查看、更新、删除事件\n- ✅ 支持多个日历管理\n- ✅ 拖拽调整事件时间\n- ✅ 月/周/日/列表多种视图\n- ✅ 实时同步到 iCloud\n\n### 🌐 现代化 Web 界面\n- 响应式设计，适配各种设备\n- FullCalendar 可视化日历\n- 直观的智能助手输入框\n- 平滑动画和交互效果\n\n### 🔌 双模式支持\n1. **Web 模式**：通过浏览器访问\n2. **MCP 模式**：供 Claude、ChatGPT 等 AI 助手调用\n\n---\n\n## 🚀 快速开始\n\n### 前置要求\n\n- **Python 3.12+**\n- **uv** 包管理工具\n- **iCloud 账号** 和应用专用密码\n- **DeepSeek API** 密钥\n\n### 1. 安装 uv\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### 2. 克隆项目\n\n```bash\ngit clone https://github.com/yourusername/iCalendar.git\ncd iCalendar\n```\n\n### 3. 安装依赖\n\n```bash\nuv sync\n```\n\n### 4. 配置凭据\n\n#### 4.1 创建配置文件\n\n```bash\ncp config.json.example config_private.json\n```\n\n#### 4.2 获取 iCloud 应用专用密码\n\n1. 访问 [Apple ID 管理页面](https://appleid.apple.com/)\n2. 登录您的 Apple ID\n3. 进入 **登录与安全** → **应用专用密码**\n4. 点击 **生成密码**\n5. 为密码命名（如 \"iCalendar\"）\n6. 复制生成的密码（格式：`xxxx-xxxx-xxxx-xxxx`）\n\n#### 4.3 获取 DeepSeek API 密钥\n\n1. 访问 [DeepSeek 平台](https://platform.deepseek.com/)\n2. 注册并登录账户\n3. 进入 **API Keys** 页面\n4. 创建新的 API 密钥\n5. 复制密钥（格式：`sk-xxxxxxxxxxxxxxxx`）\n\n#### 4.4 编辑配置文件\n\n```bash\n# 使用您喜欢的编辑器\nnano config_private.json\n# 或\nvi config_private.json\n# 或\nopen -a TextEdit config_private.json\n```\n\n填入您的凭据：\n\n```json\n{\n \"caldav\": {\n \"server_url\": \"https://caldav.icloud.com/\",\n \"username\": \"your_apple_id@icloud.com\",\n \"password\": \"xxxx-xxxx-xxxx-xxxx\"\n },\n \"deepseek\": {\n \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxx\",\n \"base_url\": \"https://api.deepseek.com\"\n }\n}\n```\n\n### 5. 启动服务器\n\n#### 后台运行（推荐）\n\n```bash\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n```\n\n#### 前台运行（开发调试）\n\n```bash\nuv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 --reload\n```\n\n### 6. 访问 Web 界面\n\n在浏览器中打开：**http://localhost:8000**\n\n🎉 **完成！** 现在您可以开始使用智能日历系统了！\n\n---\n\n## 📖 使用指南\n\n### 自然语言命令示例\n\n#### 创建事件\n```\n✅ \"明天下午3点提醒我开会\"\n✅ \"下周三上午9点到10点团队会议\"\n✅ \"本周五晚上8点看电影\"\n✅ \"11月15日下午2点产品发布会\"\n```\n\n#### 查询事件\n```\n✅ \"今天有什么安排？\"\n✅ \"本周有什么事情？\"\n✅ \"下个月有什么会议？\"\n```\n\n#### 更新事件\n```\n✅ \"把明天的会议改到后天\"\n✅ \"将周五的会议时间改为下午2点\"\n✅ \"把和张三的会议改到明天下午2点\"\n```\n\n#### 删除事件\n```\n✅ \"取消明天的会议\"\n✅ \"删除今天下午的活动\"\n✅ \"删除和里斯的会议\"\n```\n\n### 智能匹配功能\n\n系统支持按标题智能匹配事件：\n\n- **单个匹配**：直接执行操作\n ```\n \"删除和里斯的会议\" → ✅ 直接删除\n ```\n\n- **多个匹配**：返回列表供选择\n ```\n \"删除和张三的活动\" → \n 找到 2 个匹配的事件：\n 1. 和张三的会议 (11月12日 14:00)\n 2. 和张三喝咖啡 (11月13日 09:00)\n \n → 使用更精确的描述：\n \"删除和张三喝咖啡的活动\" → ✅ 精确删除\n ```\n\n### Web 界面功能\n\n#### 侧边栏\n- **智能助手**：输入自然语言命令\n- **快捷操作**：创建事件、回到今天、刷新\n- **日历筛选**：按日历显示事件\n- **系统状态**：在线/离线指示器\n\n#### 主日历区域\n- **视图切换**：月/周/日/列表\n- **拖拽创建**：点击日期创建事件\n- **拖拽调整**：拖动事件改变时间\n- **点击查看**：点击事件查看详情\n\n#### 快捷键（即将支持）\n- `Ctrl/Cmd + N` - 创建新事件\n- `Ctrl/Cmd + F` - 搜索事件\n- `T` - 回到今天\n\n---\n\n## 🛠️ 服务管理\n\n### 启动服务\n\n```bash\n# 后台运行\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n\n# 前台运行（开发模式）\nuv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 --reload\n```\n\n### 停止服务\n\n```bash\n# 方法 1：按进程名停止\npkill -f \"uvicorn web_client.app\"\n\n# 方法 2：强制停止占用 8000 端口的进程\nlsof -ti :8000 | xargs kill -9\n```\n\n### 检查服务状态\n\n```bash\n# 查看进程\nlsof -i :8000\n\n# 测试健康检查\ncurl http://localhost:8000/api/health\n\n# 查看服务器日志\ntail -f web_server.log\n```\n\n### 重启服务\n\n```bash\npkill -f \"uvicorn web_client.app\" && sleep 2 && \\\nnohup uv run uvicorn web_client.app:app --host 0.0.0.0 --port 8000 > web_server.log 2>&1 &\n```\n\n---\n\n## 🔌 API 文档\n\n服务器启动后，访问以下地址查看完整 API 文档：\n\n- **Swagger UI**: http://localhost:8000/docs\n- **ReDoc**: http://localhost:8000/redoc\n\n### 主要 API 端点\n\n#### 健康检查\n```http\nGET /api/health\n```\n\n#### 日历管理\n```http\nGET /api/calendars\n```\n\n#### 事件 CRUD\n```http\nGET /api/events?start_date=2025-11-01&end_date=2025-11-30\nPOST /api/events\nPUT /api/events/{event_id}\nDELETE /api/events/{event_id}\n```\n\n#### 自然语言处理\n```http\nPOST /api/nl/execute\nContent-Type: application/json\n\n{\n \"text\": \"明天下午3点和张三开会\",\n \"context\": {}\n}\n```\n\n---\n\n## 📁 项目结构\n\n```\niCalendar-main/\n├── mcp_ical/ # 核心业务逻辑\n│ ├── caldav_client.py # CalDAV 客户端\n│ ├── config.py # 配置管理\n│ ├── deepseek_client.py # DeepSeek AI 集成\n│ ├── ical.py # 日历管理器\n│ ├── models.py # 数据模型\n│ └── server.py # MCP 服务器\n│\n├── web_client/ # Web 应用\n│ ├── app.py # FastAPI 主应用\n│ ├── templates/ # HTML 模板\n│ │ └── index.html\n│ └── static/ # 静态资源\n│ ├── css/\n│ │ └── style.css\n│ └── js/\n│ └── app.js\n│\n├── config_private.json # 私有配置（不提交）\n├── config.json.example # 配置模板\n├── pyproject.toml # 项目配置\n└── README.md # 本文档\n```\n\n详细架构说明请查看 [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md)\n\n---\n\n## 🧪 测试\n\n### 运行测试\n\n```bash\n# 运行所有测试\nuv run pytest\n\n# 显示详细输出\nuv run pytest -v\n\n# 运行特定测试\nuv run pytest test_calendar_manager_integration.py\n\n# 显示覆盖率\nuv run pytest --cov=mcp_ical --cov=web_client\n```\n\n### 功能测试清单\n\n- [ ] 连接到 iCloud CalDAV\n- [ ] 列出所有日历\n- [ ] 创建新事件\n- [ ] 更新现有事件\n- [ ] 删除事件\n- [ ] 查询指定时间范围的事件\n- [ ] 自然语言创建事件\n- [ ] 自然语言查询事件\n- [ ] 自然语言更新事件\n- [ ] 自然语言删除事件\n- [ ] 按标题模糊匹配事件\n- [ ] Web 界面加载和显示\n- [ ] 拖拽创建事件\n- [ ] 拖拽调整事件时间\n\n---\n\n## 🔧 故障排除\n\n### 问题 1：无法连接到 iCloud\n\n**错误信息**: \"Authentication failed\" 或 \"Connection error\"\n\n**解决方案**:\n1. ✅ 确认使用的是**应用专用密码**，不是 Apple ID 密码\n2. ✅ 检查 Apple ID 和密码是否正确\n3. ✅ 确认 iCloud 日历已启用\n4. ✅ 检查网络连接\n5. ✅ 尝试重新生成应用专用密码\n\n### 问题 2：DeepSeek API 调用失败\n\n**错误信息**: \"API key invalid\" 或 \"Rate limit exceeded\"\n\n**解决方案**:\n1. ✅ 确认 API 密钥正确无误\n2. ✅ 检查 API 配额是否充足\n3. ✅ 访问 [DeepSeek 控制台](https://platform.deepseek.com/) 查看状态\n4. ✅ 确认网络可以访问 DeepSeek API\n\n### 问题 3：端口被占用\n\n**错误信息**: \"[Errno 48] Address already in use\"\n\n**解决方案**:\n```bash\n# 查看占用 8000 端口的进程\nlsof -i :8000\n\n# 终止占用端口的进程\npkill -f \"uvicorn web_client.app\"\n# 或强制终止\nlsof -ti :8000 | xargs kill -9\n```\n\n### 问题 4：依赖安装失败\n\n**解决方案**:\n```bash\n# 清理缓存并重新安装\nrm -rf .venv\nuv sync --force\n\n# 或手动安装依赖\nuv pip install fastapi uvicorn httpx loguru caldav vobject\n```\n\n### 问题 5：无法创建事件\n\n**错误信息**: \"Forbidden\" 或 \"Permission denied\"\n\n**原因**: 尝试在只读日历（如订阅日历）中创建事件\n\n**解决方案**:\n1. ✅ 在 Web 界面中选择可写的日历\n2. ✅ 避免在\"节假日\"等订阅日历中创建事件\n3. ✅ 访问 http://localhost:8000/api/calendars 查看所有日历\n\n---\n\n## 🔐 安全建议\n\n### 配置文件安全\n- ⚠️ **永远不要**将 `config_private.json` 提交到 Git\n- ⚠️ 定期更换 API 密钥和应用专用密码\n- ⚠️ 使用环境变量存储敏感信息（生产环境）\n\n### 网络安全\n- ✅ 生产环境使用 HTTPS\n- ✅ 配置防火墙规则\n- ✅ 使用反向代理（Nginx/Caddy）\n- ✅ 限制 API 访问速率\n\n### 数据安全\n- ✅ 所有日历数据通过 HTTPS 传输\n- ✅ 凭据存储在本地配置文件\n- ✅ 不在日志中记录敏感信息\n\n---\n\n## 📊 性能优化\n\n### 前端优化\n- 事件按需加载\n- 防抖处理用户输入\n- 缓存日历列表\n- 懒加载静态资源\n\n### 后端优化\n- 异步 I/O 处理\n- 连接池复用\n- 适当的日志级别\n- 数据压缩传输\n\n---\n\n## 🚢 生产部署\n\n### 使用 Systemd（推荐）\n\n1. 创建服务文件 `/etc/systemd/system/icalendar.service`:\n\n```ini\n[Unit]\nDescription=iCalendar Web Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=your_user\nWorkingDirectory=/path/to/iCalendar\nExecStart=/path/to/.venv/bin/uvicorn web_client.app:app --host 0.0.0.0 --port 8000\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\n2. 启动服务:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable icalendar\nsudo systemctl start icalendar\n```\n\n### 使用 Nginx 反向代理\n\n配置文件 `/etc/nginx/sites-available/icalendar`:\n\n```nginx\nserver {\n listen 80;\n server_name your_domain.com;\n\n location / {\n proxy_pass http://localhost:8000;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n}\n```\n\n### Docker 部署（即将支持）\n\n```bash\ndocker-compose up -d\n```\n\n---\n\n## 🤝 贡献指南\n\n欢迎贡献代码、报告问题或提出建议！\n\n### 报告问题\n\n请在 [GitHub Issues](https://github.com/yourusername/iCalendar/issues) 中报告问题，并提供：\n\n- 问题描述\n- 复现步骤\n- 预期行为\n- 实际行为\n- 系统环境（操作系统、Python 版本等）\n- 相关日志\n\n### 提交代码\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 创建 Pull Request\n\n### 开发规范\n\n- 遵循 PEP 8 代码风格\n- 添加必要的注释和文档字符串\n- 编写单元测试\n- 更新相关文档\n\n---\n\n## 📄 许可证\n\n本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。\n\n---\n\n## 🙏 致谢\n\n### 技术栈\n- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Web 框架\n- [FullCalendar](https://fullcalendar.io/) - 日历组件\n- [DeepSeek](https://www.deepseek.com/) - AI 自然语言处理\n- [python-caldav](https://github.com/python-caldav/caldav) - CalDAV 客户端\n\n### 灵感来源\n- Apple Calendar\n- Google Calendar\n- Notion Calendar\n\n---\n\n## 📞 联系方式\n\n- **项目主页**: https://github.com/yourusername/iCalendar\n- **问题反馈**: https://github.com/yourusername/iCalendar/issues\n- **邮箱**: your.email@example.com\n\n---\n\n## 🗺️ 路线图\n\n### v1.0 ✅\n- [x] CalDAV 集成\n- [x] DeepSeek AI 集成\n- [x] Web 界面\n- [x] 自然语言处理\n- [x] 智能事件匹配\n\n### v1.1（规划中）\n- [ ] 循环事件支持\n- [ ] 事件提醒功能\n- [ ] 日历导入/导出\n- [ ] 移动端优化\n- [ ] 多语言支持\n\n### v2.0（未来）\n- [ ] 离线模式\n- [ ] 团队协作功能\n- [ ] 更多 AI 功能（智能建议、冲突检测）\n- [ ] 第三方日历集成（Google Calendar、Outlook）\n- [ ] Docker 支持\n- [ ] 移动应用\n\n---\n\n<div align=\"center\">\n\n**⭐ 如果觉得这个项目有帮助，请给个 Star！⭐**\n\nMade with ❤️ by iCalendar Team\n\n</div>\n"}}}} |