# SecretaryAI **Repository Path**: coldz/SecretaryAI ## Basic Information - **Project Name**: SecretaryAI - **Description**: No description available - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-17 - **Last Updated**: 2026-04-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SecretaryAI - Rust + Tauri 智能任务与记账管理 > 基于 Rust + Tauri + React 构建的现代化桌面应用 ## 🌟 核心特性 - **高性能**: Rust 后端提供极致性能，启动速度快 - **轻量级**: 最终应用体积 < 5MB，内存占用低 - **跨平台**: 支持 Windows、macOS、Linux - **现代化 UI**: React + TypeScript + Tailwind CSS + 黑白主题 - **原生集成**: 系统通知、快捷键支持 - **数据持久化**: SQLite 本地存储 - **智能分析**: Agent Service 提供目标匹配分析和支出报告生成 - **目标管理**: 长期目标设定与任务匹配度分析 ## 🛠️ 技术栈 | 组件 | 技术 | 版本 | |------|------|------| | **桌面层** || | 桌面框架 | Tauri | 2.10.1 | | 后端语言 | Rust | 1.95.0 | | 前端框架 | React | 18.2.0 | | 前端语言 | TypeScript | 5.3.0 | | UI 样式 | Tailwind CSS | 3.3.0 | | 图表库 | Recharts | 2.10.0 | | Markdown渲染 | react-markdown | 10.1.0 | | 包管理 | pnpm | 10.33.0 | | **Agent服务层** || | Agent框架 | LangGraph | 0.2.x | | LLM集成 | LangChain | 0.3.x | | Web框架 | FastAPI | 0.115.x | | Agent语言 | Python | 3.12.x | | HTTP客户端 | httpx | 0.27.x | | **数据层** || | 数据存储 | SQLite | 3.x | | Rust驱动 | rusqlite | 0.30.0 | | Python驱动 | sqlite3 | 内置 | ## 📁 项目结构 ``` SecretaryAI/ ├── agent-service/ # Python Agent Service (ReAct架构) │ ├── main.py # FastAPI 入口 + SSE 流式接口 │ ├── agent.py # LangGraph ReAct循环Agent │ ├── state.py # Agent 状态定义 (ReActAgentState) │ ├── tools.py # 数据查询工具 │ ├── requirements.txt # Python 依赖 │ └── venv/ # Python 虚拟环境 ├── src-tauri/ # Rust 后端代码 │ ├── src/ │ │ ├── main.rs # Tauri 应用入口 │ │ ├── lib.rs # 库入口 │ │ ├── commands.rs # Tauri 命令接口 │ │ ├── parser.rs # 自然语言解析器 │ │ ├── services/ # 业务逻辑 │ │ │ ├── agent_client.rs # 🆕 Agent HTTP客户端 + 事件转发 │ │ │ ├── expense_service.rs # 支出管理服务 │ │ │ ├── task_service.rs # 任务管理服务 │ │ │ ├── goal_service.rs # 目标管理服务 │ │ │ ├── config_service.rs # API配置管理 │ │ │ └── notification_service.rs # 通知服务 │ │ ├── models/ # 数据模型 │ │ │ ├── task.rs # 任务模型 │ │ │ ├── expense.rs # 支出模型 │ │ │ └── goal.rs # 目标模型 │ │ └── db/ # 数据库 │ │ └── mod.rs # SQLite 连接管理 + 表初始化 │ ├── Cargo.toml # Rust 依赖配置 │ ├── tauri.conf.json # Tauri 配置 │ └── icons/ # 应用图标 ├── src-ui/ # React 前端 │ ├── src/ │ │ ├── App.tsx # 应用主组件 │ │ ├── components/ # React 组件 │ │ │ ├── TaskCard.tsx # 任务卡片 │ │ │ ├── ExpenseTracker.tsx # 支出追踪器 │ │ │ ├── GoalManagement.tsx # 目标管理 │ │ │ ├── ThinkingProcess.tsx # ReAct流程渲染 + 实时思考时长 | │ │ │ ├── ExpenseTrendChart.tsx # 支出趋势图表 │ │ │ ├── CategoryPieChart.tsx # 分类饼图 │ │ │ ├── Button.tsx # 按钮组件 │ │ │ ├── Card.tsx # 卡片组件 │ │ │ ├── Modal.tsx # 模态对话框 │ │ │ ├── Input.tsx # 输入组件 │ │ │ ├── Badge.tsx # 徽章组件 │ │ │ ├── EmptyState.tsx # 空状态组件 │ │ │ ├── ThemeToggle.tsx # 主题切换 │ │ │ ├── SettingsModal.tsx # 设置模态框 │ │ │ └── StatsDialog.tsx # 统计对话框 │ │ ├── hooks/ # 自定义 Hooks │ │ │ └── useTheme.ts # 主题管理 Hook │ │ ├── styles/ # 样式文件 │ │ │ ├── index.css # 主样式文件 │ │ │ ├── tokens.css # 设计令牌 │ │ │ └── animations.css # 动画样式 │ │ ├── types/ # TypeScript 类型定义 │ │ │ └── expense.ts # 支出类型定义 │ │ └── main.tsx # React 入口 │ ├── package.json # 前端依赖配置 │ ├── vite.config.ts # Vite 配置 │ ├── tsconfig.json # TypeScript 配置 │ └── tailwind.config.js # Tailwind CSS 配置 ├── scripts/ # 🆕 启动脚本 │ └── start-agent.js # Agent Service 自动启动 ├── README.md # 项目说明文档 └── .gitignore # Git 忽略配置 ``` --- ## 🚀 启动架构详解 ### ⚡ 一键启动命令（推荐） ```bash # 清理端口 + 一键启动所有组件 lsof -ti :8000 | xargs kill -9 2>/dev/null rm -f /tmp/secretary-ai-agent.* cargo tauri dev ``` ### 🔄 三层启动流程 #### 📊 启动时序图 ``` 时间轴 → 0s ────────────────┬──────────────────┬────────────────────┬─────→ │ │ │ [第1层] │ [第2层] │ [第3层] │ 完成 BeforeDevCommand │ DevCommand │ 运行时架构 │ │ │ │ ├─ Agent Service │ │ │ │ 启动 (2s) │ │ │ │ │ │ │ ├─ Vite前端 │ │ │ │ 启动 (216ms) │ │ │ │ │ │ │ ├─ Rust编译 │ │ │ (14.67s) │ │ │ │ │ │ ├─ Tauri窗口打开 │ │ ├─ 加载前端UI │ │ ├─ Agent Client连接 │ │ ├─ 用户操作触发 │ │ │ │ 17s ───────────────┴──────────────────┴────────────────────┴─────→ ✓ 所有组件就绪，开始正常工作 ``` --- ### 🏗️ 运行时架构全景图 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 第3层：Tauri应用 │ │ (本地桌面应用) │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 前端UI层 (React + TypeScript) │ │ │ │ 运行在: localhost:1420 │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ExpenseTracker│ │ThinkingProcess│ │ App.tsx │ │ │ │ │ │ - ReAct流程 │ │ - 时间轴渲染 │ │ - 路由 │ │ │ │ │ │ - 图表视图 │ │ - Markdown │ │ - 状态管理 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ │ │ invoke() 跨语言调用 │ │ ↓ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Rust后端层 (Tauri Core) │ │ │ │ 主进程，管理窗口和系统调用 │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │agent_client │ │expense_service│ │config_service│ │ │ │ │ │ - SSE监听 │ │ - 数据CRUD │ │ - API配置 │ │ │ │ │ │ - 11种事件 │ │ - 统计计算 │ │ - 端口管理 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ↓ HTTP/SSE 流式传输 (127.0.0.1:8000/generate-report/stream) ↓ ┌─────────────────────────────────────────────────────────────────┐ │ 第1层：Agent Service层 │ │ (Python FastAPI + LangGraph) │ │ 运行在: localhost:8000 │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ LangGraph ReAct循环Agent (5节点) │ │ │ │ │ │ │ │ User Query │ │ │ │ ↓ │ │ │ │ thought_node (LLM推理 + tool_calls检测) │ │ │ │ ↓ ↓ │ │ │ │ decide_node ─────判断────┘ │ │ │ │ ├─ has_tool_call → tool_call_node (执行工具) │ │ │ │ │ ↓ │ │ │ │ │ reflect_node (总结状态) │ │ │ │ │ ↓ │ │ │ │ │ is_finished? │ │ │ │ │ ├─ False → thought_node (循环) │ │ │ │ │ └─ True → final_node │ │ │ │ └─ no_tool_call → final_node (直接生成报告) │ │ │ │ ↓ │ │ │ │ final_node (流式生成Markdown报告) │ │ │ │ ↓ │ │ │ │ generation_complete │ │ │ │ │ │ │ │ 每个节点yield事件流 → SSE传输 → 前端渲染 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ │ │ Tool调用（数据库查询） │ │ ↓ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 数据持久化层 (SQLite) │ │ │ │ 路径: ~/Library/Application Support/secretary-ai/ │ │ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ expenses表 │ │ tasks表 │ │ goals表 │ │ │ │ │ │ - 消费记录 │ │ - 任务管理 │ │ - 目标设定 │ │ │ │ │ │ - 统计数据 │ │ - 完成状态 │ │ - 进度追踪 │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ### 📈 事件流传输全景图 #### ReAct循环：Thought → Tool → Reflect → Final ``` 用户点击"生成报告" ↓ ┌───────────────────────────────────────────────────────────┐ │ Agent Service (Python) - ReAct循环事件生成 │ │ │ │ thought_node decide_node │ │ ├─ thought_chunk (流式) ├─ decision判断 │ │ ├─ thought_complete │ ├─ tool_call → 继续 │ │ │ 检测tool_calls │ └─ finish → final_node │ │ │ │ │ │ tool_call_node reflect_node │ │ ├─ tool_call_start ├─ reflect_start │ │ ├─ tool_call_complete ├─ reflect_chunk (流式) │ │ │ 执行数据库查询 ├─ reflect_complete │ │ │ │ ├─ is_finished? → END │ │ │ │ └─ 继续循环 → thought_node│ │ │ │ │ │ final_node │ │ ├─ final_chunk (每30字符) │ │ ├─ generation_complete │ │ │ yield {final_content} │ └───────────────────────────────────────────────────────────┘ ↓ SSE (Server-Sent Events) 流式传输 ↓ data: {"type": "thought_chunk", "content": "..."} ┌───────────────────────────────────────────────────────────┐ │ Rust Backend - 事件监听与转发 │ │ │ │ agent_client.rs (match event_type) │ │ ├─ "step_start" → emit("step-start") │ │ ├─ "thought_start" → emit("thought-start") │ │ ├─ "thought_chunk" → emit("thought-chunk") │ │ ├─ "thought_complete" → emit("thought-complete") │ │ ├─ "tool_call_start" → emit("tool-call-start") │ │ ├─ "tool_call_complete" → emit("tool-call-complete") │ │ ├─ "tool_call_error" → emit("tool-call-error") │ │ ├─ "reflect_start" → emit("reflect-start") │ │ ├─ "reflect_chunk" → emit("reflect-chunk") │ │ ├─ "reflect_complete" → emit("reflect-complete") │ │ ├─ "final_start" → emit("final-start") │ │ ├─ "final_chunk" → emit("final-chunk") │ │ ├─ "final_complete" → emit("final-complete") │ │ ├─ "generation_complete" → emit("generation-complete") │ └───────────────────────────────────────────────────────────┘ ↓ Tauri事件系统 ↓ 前端监听 listen('thought-chunk', ...) ┌───────────────────────────────────────────────────────────┐ │ 前端UI (React) - 时间轴渲染 │ │ │ │ ThinkingProcess.tsx │ │ ├─ step-start → 添加新步骤到stepTraces │ │ ├─ thought-start → 启动计时器，标记思考状态 │ │ ├─ thought-chunk → 流式追加思考内容 │ │ ├─ thought-complete → 停止计时，标记完成 │ │ ├─ tool-call-start → 添加工具调用步骤 │ │ ├─ tool-call-complete → 显示工具返回结果 │ │ ├─ reflect-start → 添加反思步骤，启动计时 │ │ ├─ reflect-chunk → 流式追加反思内容 │ │ ├─ reflect-complete → 判断是否继续循环 │ │ ├─ final-chunk → 流式生成最终报告 │ │ │ └ ReactMarkdown渲染 │ │ └─ generation_complete → onComplete() → 按钮恢复 │ └───────────────────────────────────────────────────────────┘ ``` --- ### 🎨 ReAct循环时间轴UI渲染详解 ``` 时间轴主线（动态步骤流） │ │ ┌──────────────────────────────────────────────────┐ │ │ 🧠 Step N: Thought (思考节点) │ │ │ ┌────────────────────────────────────────────┐ │ │ │ │ Brain图标 + LLM推理 │ │ │ │ │ ⏳ "正在思考..." │ │ │ │ │ [流式输出推理过程] │ │ │ │ │ 检测是否有tool_calls │ │ │ │ │ ✅ Thought完成 │ │ │ │ │ 耗时显示: X.Xs │ │ │ │ └────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────┘ │ ↓ (有tool_call时) │ │ ┌──────────────────────────────────────────────────┐ │ │ 🗄️ Step N: Tool Call (工具调用) │ │ │ ┌────────────────────────────────────────────┐ │ │ │ │ Database图标 + 工具执行 │ │ │ │ │ ⏳ 调用: get_expense_stats │ │ │ │ │ ✅ 工具返回结果 │ │ │ │ │ [可展开查看完整JSON结果] │ │ │ │ └────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────┘ │ ↓ │ │ ┌──────────────────────────────────────────────────┐ │ │ 💭 Step N: Reflect (反思节点) │ │ │ ┌────────────────────────────────────────────┐ │ │ │ │ MessageSquare图标 + 总结进展 │ │ │ │ │ "正在反思当前状态..." │ │ │ │ │ [流式输出反思内容] │ │ │ │ │ ✅ Reflect完成 │ │ │ │ │ 判断: is_finished? │ │ │ │ │ ├─ True → 进入Final节点 │ │ │ │ │ └─ False → 返回Thought节点（循环） │ │ │ │ └────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────┘ │ ↓ (循环结束) │ │ ┌──────────────────────────────────────────────────┐ │ │ 📝 Final: 最终报告生成 │ │ │ ┌────────────────────────────────────────────┐ │ │ │ │ FileText图标 + 报告生成 │ │ │ │ │ "正在生成最终报告..." │ │ │ │ │ [流式Markdown渲染，每30字符更新一次] │ │ │ │ │ **加粗**、列表、标题正确渲染 │ │ │ │ │ ✅ 报告生成完成 │ │ │ │ │ 🎉 generation_complete │ │ │ │ └────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────┘ │ └─ 生成完成 → 按钮恢复 → 可再次点击 特点： - 动态步骤数量（不固定，由LLM决策决定） - 每步骤实时计时（思考中显示动态计时） - 循环可视化（Thought → Tool → Reflect → 循环） - 工具结果可展开查看（JSON数据） ``` --- ### 📊 性能统计表 | 组件 | 启动时间 | 端口/路径 | 技术栈 | 核心功能 | |------|---------|----------|--------|----------| | **Agent Service** | 2秒 ✓ | 8000 | Python + FastAPI | LangGraph ReAct循环Agent (5节点) | | **Vite前端** | 216ms ✓ | 1420 | React + TypeScript | UI渲染 + 状态管理 | | **Rust编译** | 14.67s ✓ | - | Rust + Tauri | 系统调用 + 事件转发 | | **总启动时间** | ~17秒 ✓ | - | **3层架构** | **完整桌面应用** | --- ### 🔧 启动脚本自动化流程 ```bash scripts/start-agent.js 自动执行： ┌──────────────────────────────────────────────┐ │ 1. 端口检测 │ │ ├─ 检查 8000-8003 端口 │ │ ├─ 找到可用端口 │ │ └─ 保存到 /tmp/secretary-ai-agent-port.txt│ └──────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────┐ │ 2. 数据库初始化 │ │ ├─ 创建 ~/Library/Application Support/ │ │ │ └ secretary-ai/ 目录 │ │ ├─ 初始化 SQLite 数据库 │ │ └─ 创建 expenses/tasks/goals 表 │ └──────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────┐ │ 3. Python服务启动 │ │ ├─ source venv/bin/activate │ │ ├─ 设置环境变量： │ │ │ AGENT_PORT=8000 │ │ │ PYTHONIOENCODING=utf-8 │ │ │ DATABASE_PATH="..." │ │ ├─ nohup python main.py 后台运行 │ │ └─ 记录PID到 /tmp/secretary-ai-agent.pid │ └──────────────────────────────────────────────┘ ↓ ┌──────────────────────────────────────────────┐ │ 4. 健康检查 │ │ ├─ 循环10次，每次等待1秒 │ │ ├─ curl http://127.0.0.1:8000/health │ │ ├─ 收到 {"status":"ok"} → 成功 │ │ └─ 通知Tauri继续启动 │ └──────────────────────────────────────────────┘ ``` --- ### 🎯 关键技术亮点 #### ✨ 真流式输出架构 ``` 传统伪流式 vs 本项目真流式 on_chain_end vs AsyncGenerator yield 拆分完整内容 vs 实时生成chunk 客户端缓冲延迟 vs 服务端实时推送 一次性显示 vs 逐字符追加 ↓ ↓ 用户体验差 vs 流畅自然 无法看到过程 vs 完整思考过程可见 ``` #### 🔒 参数传递可靠性 ``` 旧架构 (LLM自主决策) vs 新架构 (显式绑定) LLM解析period参数 vs planning_node生成query_plan 可能理解错误 vs JSON结构化计划 参数传递不可控 vs tool_params显式绑定 调试困难 vs 完全可控可追踪 ``` --- ### 💡 启动方式对比 | 方式 | 命令 | 适用场景 | 优点 | |------|------|---------|------| | **一键启动** ✓ | `npm run dev` | 跨平台开发 | 自动适配 Windows/macOS/Linux | | 一键启动(Bash) | `npm run dev:bash` | macOS/Linux 专用 | 兼容原有 bash 脚本 | | 一键启动(PS) | `npm run dev:ps` | Windows PowerShell | 兼容 PowerShell 环境 | | 仅前端 | `npm run dev:frontend` | UI开发 | 快速迭代 | | 仅Agent | `npm run dev:agent` | Agent测试 | API调试 | | 仅Tauri | `npm run dev:tauri` | 后端调试 | Rust开发 | > ⚠️ **首次编译注意**：首次运行 `npm run dev` 时，Rust 依赖需要从网络下载（约 600+ 个 crate），可能需要 5-15 分钟。后续编译会使用本地缓存，速度快很多。 --- ### 📦 环境要求 ### Windows - **Node.js**: >= 16.x (推荐 v24.x) - **pnpm**: >= 8.x - **Rust**: >= 1.70 - **MSVC 编译工具**（3种方案，任选其一）: - 方案1（推荐）: VS Build Tools 最小安装（约 1-2 GB） - 方案2: 已有 Visual Studio IDE 可直接使用 - 方案3: VS Build Tools 完整安装（约 6-7 GB） - **WebView2**: Windows 10/11 通常已预装 - **SQLite**: 无需安装（项目已包含 bundled 版本） ### macOS - **Node.js**: >= 16.x - **pnpm**: >= 8.x - **Rust**: >= 1.70 - **Xcode Command Line Tools**: `xcode-select --install` - ⚠️ **不需要完整的 Xcode IDE**（10+ GB），只需命令行工具（约 300 MB） - 提供编译器（clang）、构建工具（make）和 macOS SDK ### Linux - **Node.js**: >= 16.x - **pnpm**: >= 8.x - **Rust**: >= 1.70 - **系统依赖**: `sudo apt install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev` ## 🛑 退出与清理 ### 正常退出机制 应用关闭时会自动清理后台进程，但**仅在以下情况下生效**： | 关闭行为设置 | Agent Service清理 | 临时文件清理 | 说明 | |-------------|-------------------|-------------|------| | **直接退出** | ✅ 自动清理 | ✅ 自动删除 | 推荐：最干净 | | **最小化到托盘** | ❌ 继续运行 | ❌ 保留 | Agent后台运行 | | **每次询问** | ❌ 用户决定 | ❌ 保留 | 需手动确认 | > 💡 **最佳实践**：在设置中将"关闭窗口行为"设置为"直接退出"，确保每次关闭都完全清理。 ### 手动退出所有服务（推荐） 如果遇到进程残留或端口占用问题，使用以下命令**完全清理**： #### macOS / Linux ```bash # 一键清理所有服务进程 lsof -ti :8000 | xargs kill -9 2>/dev/null || true # Agent Service lsof -ti :1420 | xargs kill -9 2>/dev/null || true # Vite前端 # 清理临时文件 rm -f /tmp/secretary-ai-agent.pid rm -f /tmp/secretary-ai-agent-port.txt rm -f /tmp/agent-service.log # 验证清理结果 lsof -i :8000 || echo "✓ Agent Service已清理" lsof -i :1420 || echo "✓ Vite前端已清理" ``` #### Windows (PowerShell) ```powershell # 清理端口进程 netstat -ano | findstr :8000 | findstr LISTENING # 找到PID后手动kill（替换为实际数字） taskkill /PID /F # 清理端口1420 netstat -ano | findstr :1420 | findstr LISTENING taskkill /PID /F # 清理临时文件 Remove-Item "$env:TEMP\secretary-ai-agent.pid" -ErrorAction SilentlyContinue Remove-Item "$env:TEMP\secretary-ai-agent-port.txt" -ErrorAction SilentlyContinue ``` ### 强制清理脚本（终极方案） 当所有方法都失败时，使用**强制清理**： ```bash # macOS/Linux pkill -9 -f "python.*main.py" # 所有Agent进程 pkill -9 -f "node.*start-agent" # 启动脚本 pkill -9 -f "vite" # Vite进程 rm -rf /tmp/secretary-ai-* /tmp/agent-service.log # Windows taskkill /F /IM python.exe /FI "WINDOWTITLE eq agent*" # Agent进程 taskkill /F /IM node.exe # Node进程 ``` ### 检查服务状态 ```bash # 检查端口占用 lsof -i :8000 # macOS/Linux netstat -ano | findstr :8000 # Windows # 检查进程详情 ps aux | grep "agent-service" | grep -v grep # macOS/Linux tasklist | findstr python # Windows # 测试Agent Service健康状态 curl http://127.0.0.1:8000/health # 期望输出: {"status":"ok","service":"langgraph-agent"} ``` ### 常见清理场景 #### 场景1：端口8000被占用 ```bash # 查看占用进程 lsof -i :8000 # 强制清理 lsof -ti :8000 | xargs kill -9 ``` #### 场景2：启动失败（端口检测超时） ```bash # 清理残留进程 lsof -ti :8000,1420 | xargs kill -9 rm -f /tmp/secretary-ai-agent.* # 重新启动 npm run dev ``` #### 场景3：应用关闭后进程仍在运行 ```bash # 确认进程状态 ps aux | grep "agent-service" | grep -v grep # 强制终止 pkill -9 -f "python.*main.py" ``` ### ⚠️ 注意事项 1. **数据安全**：强制kill不会损坏数据库，SQLite有事务保护 2. **重启必要性**：清理后需要重新运行 `npm run dev` 启动服务 3. **端口范围**：Agent Service会在8000-8003范围内寻找可用端口 4. **PID文件**：`/tmp/secretary-ai-agent.pid` 记录进程ID，删除后无法自动清理 ## 🚀 快速开始 ### 1. 安装环境依赖
Windows 安装步骤（点击展开） ```powershell # 1. 安装 Rust（推荐使用镜像源加速） # 下载 rustup-init.exe 或使用 winget winget install Rustlang.Rustup # 配置镜像源（加速下载） # 在 %USERPROFILE%\.cargo\config.toml 中添加： # [source.crates-io] # replace-with = "tuna" # [source.tuna] # registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git" # 2. 安装 MSVC 编译工具（3种方案） # 方案A: 最小安装（推荐，约 1-2 GB） winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows.SDK.10.0" # 方案B: 完整安装（约 6-7 GB，包含更多工具） winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" # 方案C: 如果已安装 Visual Studio IDE，可直接使用，无需额外安装 # 3. 安装 Node.js（已安装可跳过） # 访问 https://nodejs.org/ 下载安装 # 4. 安装 pnpm npm install -g pnpm # 5. 安装 Tauri CLI cargo install tauri-cli ```
macOS/Linux 安装步骤（点击展开） ```bash # 1. 安装 Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # macOS: 安装 Xcode Command Line Tools（不需要完整 Xcode IDE） xcode-select --install # Linux (Ubuntu/Debian): 安装系统依赖 sudo apt install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev # 2. 安装 pnpm npm install -g pnpm # 3. 安装 Tauri CLI cargo install tauri-cli ```
### 2. 克隆项目并安装依赖 ```bash # 克隆项目 git clone https://github.com/yourusername/SecretaryAI.git cd SecretaryAI # 安装前端依赖 cd src-ui pnpm install cd .. ``` ### 3. 启动开发环境 ```bash # 方式1（推荐）：跨平台一键启动（自动检测 Windows/macOS/Linux） npm run dev # 方式2：仅启动 Tauri 窗口（需要手动启动其他服务） cargo tauri dev ``` 首次启动会编译 Rust 后端： - 首次编译：需要下载 600+ 个 Rust 依赖，约 5-15 分钟（取决于网络） - 后续编译：使用本地缓存，只需 10-30 秒 ### 4. 依赖检查与同步（重要） **首次安装后和多设备开发时必须运行**，确保所有依赖版本一致： ```bash # 检查并修复所有依赖（Python + Node.js） npm run sync-deps # 仅检查/修复 Python 依赖 npm run sync-deps:python # 仅检查/修复 Node.js 依赖 npm run sync-deps:node ``` **何时运行依赖检查**： - ✅ 首次克隆项目并安装依赖后 - ✅ 每次 `git pull` 后 - ✅ 切换开发设备（Mac ↔ Windows）后 - ✅ 长时间未开发后重新开始时 > 💡 **重要提示**：依赖版本不一致会导致编译失败、运行错误等问题。建议养成习惯，每次开始开发前运行一次 `npm run sync-deps`。 ## 🎯 使用指南 ### 功能概览 SecretaryAI 是一个智能任务与记账管理应用，主要功能包括： 1. **任务管理** - 创建、查看、完成、删除任务 - 支持优先级（紧急/重要/普通） - 支持截止时间设定 - 自动统计任务数据 - 完成率趋势分析 2. **支出追踪** - 快速记录日常支出 - 分类管理（饮品、交通、娱乐、学习、购物、餐饮、其他） - 多时间维度统计（今日、本周、本月、本年） - 数据可视化图表（趋势图、分类饼图） - Agent生成的支出分析报告 3. **目标管理** - 长期目标设定（工作、马拉松、家庭、第二支点、健康） - 优先级管理（高、中、低） - 进度追踪（目标值/当前值） - Agent分析目标与任务匹配度 - 智能建议任务优先级调整 4. **智能分析** - AI思考过程可视化展示 - 目标-任务匹配度分析 - 消费趋势洞察报告 - 自然语言输入解析 ### 操作示例 #### 任务管理 - 添加任务：`明天下午3点开会 紧急` - 完成任务：点击任务卡片上的完成按钮 - 删除任务：点击删除按钮 #### 支出记录 - 快速记账：`午餐 25元 餐饮` - 查看统计：侧边栏支出图表 - 分类查看：按类别筛选支出 ## 🔧 开发调试 ### 前端调试 ```bash # 单独启动前端开发服务器 cd src-ui pnpm dev # 访问 http://localhost:1420 # Windows/Linux: 按 Ctrl+Shift+I 打开开发者工具 # macOS: 按 Cmd+Option+I 打开开发者工具 ``` ### 后端调试 ```bash # 检查 Rust 编译 cd src-tauri cargo build cargo test # 查看详细日志 cargo tauri dev -- --verbose ``` ### 热重载 - **前端**: 修改前端代码后自动刷新 - **后端**: 修改 Rust 代码后需要重新编译（自动触发） ## 📦 构建发布版本 ```bash # 构建生产版本 cargo tauri build # 输出位置： # Windows: src-tauri/target/release/secretary-ai.exe # macOS: src-tauri/target/release/bundle/macos/SecretaryAI.app # Linux: src-tauri/target/release/bundle/deb/secretary-ai_*.deb ``` ## 🆘 常见问题
Q: Rust 下载速度很慢怎么办？ **A: 配置镜像源加速** 创建或修改 `%USERPROFILE%\.cargo\config.toml` (Windows) 或 `$HOME/.cargo/config.toml` (macOS/Linux): ```toml [source.crates-io] replace-with = "tuna" [source.tuna] registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git" [net] git-fetch-with-cli = true ```
Q: Windows 编译失败提示找不到 MSVC？ **A: 安装 Visual Studio Build Tools** ```powershell # 使用 winget 安装 winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" # 或手动下载安装 # https://visualstudio.microsoft.com/visual-cpp-build-tools/ # 选择 "Desktop development with C++" 工作负载 ```
Q: 前端端口被占用？ **A: 修改端口或清理进程** ```bash # 方法1: 查找并终止占用端口的进程 netstat -ano | grep 1420 # Windows: taskkill /PID /F # macOS/Linux: kill # 方法2: 修改端口 # 编辑 src-tauri/tauri.conf.json # "devUrl": "http://localhost:1421" ```
Q: Tauri API 版本不匹配？ **A: 确保前后端版本一致** ```bash # 更新前端 Tauri API cd src-ui pnpm update @tauri-apps/api # 检查版本 # Cargo.toml: tauri = "2.0" # package.json: @tauri-apps/api = "^2.0.0" ```
Q: 编译警告太多？ **A: 清理未使用的导入** ```bash # 自动修复警告 cd src-tauri cargo fix --lib -p secretary-ai # 或手动删除警告中提到的未使用导入 ```
Q: 跨设备开发后 Python 依赖版本不匹配？ **A: 使用依赖同步工具** 在多台设备（Mac/Windows）交替开发时，可能出现依赖版本不一致： ```bash # 自动检查并修复所有依赖 npm run sync-deps # 或手动指定 pip install -r agent-service/requirements.txt ``` 常见问题： - `langgraph` 版本不匹配 - `httpx` API 变化导致启动失败 - `fastapi` 版本差异
Q: 首次编译 Rust 依赖下载很慢？ **A: 这是正常现象，首次编译需要下载 600+ 个 crate** 首次运行 `npm run dev` 或 `cargo tauri dev` 时： - 需要从 crates.io（或镜像源）下载所有 Rust 依赖 - 依赖数量：600+ 个 crate - 预计时间：5-15 分钟（取决于网络） - 后续编译：使用本地缓存，只需 10-30 秒 **加速方案**： 1. 配置 Cargo 镜像源（推荐使用清华镜像） 2. 耐心等待首次编译完成
## 🔄 更新依赖 ```bash # 更新 Rust 依赖 cd src-tauri cargo update # 更新前端依赖 cd src-ui pnpm update # 更新 Python 依赖（Agent Service） cd agent-service pip install -r requirements.txt ``` > 💡 **推荐使用依赖检查工具**：更新依赖后，建议运行 `npm run sync-deps` 确保所有依赖版本一致。 ## 📚 相关文档 - [Tauri 官方文档](https://tauri.app/v2/guide/) - [Rust 学习资源](https://doc.rust-lang.org/book/) - [React 官方文档](https://react.dev/) - [Tailwind CSS 文档](https://tailwindcss.com/docs) - [TypeScript 手册](https://www.typescriptlang.org/docs/) ## 🤝 贡献指南 欢迎贡献代码、报告问题或提出建议！ 1. Fork 项目 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建 Pull Request ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 🙏 致谢 - [Tauri](https://tauri.app/) - 现代化桌面应用框架 - [React](https://react.dev/) - 前端 UI 框架 - [Rust](https://www.rust-lang.org/) - 高性能系统编程语言 - [Tailwind CSS](https://tailwindcss.com/) - 现代化 CSS 框架 --- **开始使用 SecretaryAI，让任务管理和记账更智能！** 🚀