03 - 技术选型总结
从 Sice 项目开发总结的 AI 原生应用技术选型经验。
整体技术栈推荐（AI 原生桌面应用）
| 层级 | 技术选型 | 版本 | 理由 |
|---|---|---|---|
| 桌面框架 | Tauri | v2.x | 轻量跨平台，安装包小，资源占用低 |
| 前端框架 | React | 19.x | 生态成熟，社区活跃 |
| UI 组件库 | shadcn/ui | 4.x | 基于 Radix UI，样式可定制，无捆绑 |
| AI 聊天组件 | AI Elements | - | 基于 shadcn/ui，开箱即用 |
| 样式方案 | Tailwind CSS | 4.x | 原子化 CSS，开发效率高 |
| 状态管理 | Zustand | 5.x | 轻量简洁，学习成本低 |
| AI SDK | LangChain SDK | - | useStream 原生支持流式响应 |
| 包管理器 | pnpm | 9.x | 速度快，磁盘占用小，支持工作区 |
| Agent Harness | Deep Agents | 0.5.x+ | 开箱即用的任务规划、文件系统、子代理 |
| Agent 框架 | LangGraph | - | 成熟的图执行引擎，状态管理 |
| Web 框架 | FastAPI | 0.100+ | 原生异步，类型安全，自动文档 |
| CLI 框架 | Typer | 0.9+ | 类型注解驱动，自动生成帮助 |
| Python 包管理器 | uv | - | 比 pip/poetry 更快，原生支持锁文件 |
| Python 打包 | Nuitka | 2.6+ | 编译为单可执行文件，启动快 |
| 配置管理 | pydantic-settings | 2.x | 类型安全，环境变量读取 |
Python 环境选型对比
包管理器
| 选项 | 速度 | 锁定依赖 | 推荐场景 |
|---|---|---|---|
| uv | 极快 ✅ | 原生支持 ✅ | 推荐，新项目首选 |
| poetry | 中等 | 原生支持 | 习惯 poetry 可使用 |
| pip + requirements.txt | 慢 | 需要手动处理 | 不推荐新项目 |
结论：uv 是目前最佳选择。
打包方案
| 选项 | 单文件 | 启动速度 | 大小 | 推荐场景 |
|---|---|---|---|---|
| Nuitka | 是 ✅ | 快 ✅ | 中等 ~50MB | 推荐，sidecar 场景 |
| PyInstaller | 是 | 慢 | 较大 | 备选 |
| Docker | 否 | 中等 | 大 | 服务器场景 |
结论：桌面端 sidecar 场景，Nuitka 最佳。
Agent 框架选型对比
Deep Agents vs 自研
| 维度 | Deep Agents | 自研 |
|---|---|---|
| 任务规划 | 内置 ✅ | 需要自己写 |
| 文件系统 | 内置 ✅ | 需要自己写 |
| 子代理委托 | 内置 ✅ | 需要自己写 |
| 长期记忆 | 内置 ✅ | 需要自己写 |
| 人机协同 | 内置 ✅ | 需要自己写 |
| 开发速度 | 极快 ✅ | 慢 |
结论：新项目直接用 Deep Agents，不需要重复造轮子。
LangGraph vs 其他
| 维度 | LangGraph | 其他框架 |
|---|---|---|
| 状态管理 | 原生支持 ✅ | 很多不支持 |
| 流式输出 | 原生支持 ✅ | 需要适配 |
| 持久化 | 多种后端 ✅ | 需要自己写 |
| 社区生态 | 活跃 ✅ | 参差不齐 |
| Deep Agents 集成 | 官方原生 ✅ | 需要适配 |
结论：Deep Agents 本身基于 LangGraph，直接用就好。
前端选型对比
UI 组件库
| 选项 | 样式 | 定制性 | 捆绑 | 推荐场景 |
|---|---|---|---|---|
| shadcn/ui | 未捆绑，自己选 Tailwind | 完全可定制 ✅ | 无 ✅ | 推荐 |
| Ant Design | 全套样式 | 一般 | 有 | 中后台 |
| MUI | 全套样式 | 一般 | 有 | 习惯用可选 |
结论：Tailwind 项目，shadcn/ui 最佳。
状态管理
| 选项 | 大小 | 学习曲线 | 推荐场景 |
|---|---|---|---|
| Zustand | 极小 ✅ | 简单 ✅ | 推荐，大多数场景 |
| Redux | 大 | 陡峭 | 大型团队项目 |
| Context API | 内置 | 简单 | 简单场景 |
结论：Zustand 足够用，更简单。
通信方案对比
前端直连 vs Tauri 中转
| 方案 | 复杂度 | 延迟 | 推荐 |
|---|---|---|---|
| 前端直连 Python Agent | 低 ✅ | 低 ✅ | 推荐 |
| Tauri 中转 | 高 | 高 | 不需要 |
理由：
- 都是 localhost 通信，不需要 Tauri 中转
- 前端直接 HTTP + SSE，LangChain
useStream直接支持 - 减少一层，减少出问题的概率
认证方案对比
动态令牌 vs 固定令牌
| 方案 | 安全性 | 复杂度 | 推荐 |
|---|---|---|---|
| 动态令牌（每次重启生成） | 高 ✅ | 中 ✅ | 推荐 |
| 固定令牌（用户配置） | 中 | 低 | 开发可用 |
理由：
- 动态令牌即使文件被盗，重启后就失效
- 实现不复杂，状态文件权限 0600 保护
权限方案对比
二进制内置 + 用户配置 vs 全用户配置
| 方案 | 安全性 | 灵活性 | 推荐 |
|---|---|---|---|
| 双层：二进制内置（高敏感）+ 用户配置（低敏感） | 高 ✅ | 中 ✅ | 推荐 |
| 全用户配置 | 中 | 高 | 不推荐 |
理由：
- 高敏感限制（比如禁止任意 shell）必须内置，防止被篡改
- 低敏感授权（允许访问哪些目录）交给用户配置
总结：技术选型原则
- 优先选择官方原生集成：Deep Agents 基于 LangGraph，直接用就好，不需要自己适配
- 选轻量方案：桌面应用，启动速度和资源占用很重要
- 避免过度设计：能直连就不要加中间层，能简单就简单
- 接受渐进：不追求一步到位，先跑起来再优化
- 拥抱社区：成熟生态比完美但小众的方案更靠谱