《WaLiOffice - AI Agent 智能办公平台》第2-1节：工程初始化与项目结构

作者：小傅哥
博客：https://bugstack.cn (opens new window)

沉淀、分享、成长，让自己和他人都能有所收获！😄

大家好，我是技术UP主小傅哥。

上一节我们学习了整个 WaLiOffice 项目的学习路径和技术栈选型，知道我们要做的是一个"AI 说话，帮你生成办公文件"的智能平台——输入自然语言，输出 PPT/Word/Excel/Markdown/图表/视频，全流程流式反馈。那从这一节开始，我们就正式进入代码阶段，先把项目跑起来，再把架子搭清楚。

但你想过没有：一个从 0 到 1 的 AI Agent 项目，第一步到底应该做什么？——是直接写 AI 代码吗？不是的！第一步应该是把工程架子搭好，把目录结构、模块划分、依赖管理、日志初始化搞明白。因为 AI 代码写起来其实不复杂，复杂的是架构清晰、模块解耦、方便扩展。你总不想写了一个月 AI 代码，发现所有代码都揉在一个文件里，改一行 bug 引发十个新 bug 吧？（这就是架构师的工作）

所以这一节，我们就来搭 WaLiOffice 的"脚手架"——Rust 后端工程初始化。注意，这部分我们先搞基础的，整明白智能体的基础开发，以及对接各类办公软件。等后面在做 DSH 插件版就容易了。

一、本章诉求

1. 了解 WaLiOffice 项目的整体目录结构，知道每个目录是干什么的
2. 掌握 Rust 后端工程的依赖配置（Cargo.toml）
3. 理解 Axum Web 框架的路由组织方式
4. 学会用 rust-embed 把前端资源打包进后端二进制
5. 掌握 .env 环境变量配置和 tracing 日志初始化

二、流程设计

WaLiOffice 采用前端独立开发、后端统一打包的策略。前端代码放在 frontend/ 目录，开发时独立运行（Vite Dev Server）；生产环境由后端通过 rust-embed 把前端编译产物直接打包进二进制，部署时只有一个可执行文件，零外部依赖。

WaLiOffice/
├── server/                    ← Rust 后端（主战场）
│   ├── src/
│   │   ├── main.rs           ← 程序入口（模块声明 + 启动流程）
│   │   ├── config.rs         ← 配置管理（.env 解析，OnceLock 全局单例）
│   │   ├── state.rs          ← 全局状态（DB Pool / LLM Client）
│   │   ├── error.rs          ← 统一错误处理（AppError + AppResult）
│   │   ├── routes/           ← HTTP 路由层（mod.rs 构建路由 + 各子模块）
│   │   ├── agent/            ← AI Agent 核心（ReAct 循环 / 工具注册 / 意图识别）
│   │   ├── llm/              ← LLM 客户端（HTTP 调用 / 流式 SSE / 类型定义）
│   │   ├── db/               ← 数据库层（AnyPool + 6 个 repo 模块）
│   │   ├── models/           ← 数据模型（请求/响应 DTO）
│   │   ├── render/           ← 文档渲染（DOCX / XLSX / PPTX）
│   │   ├── file_extract.rs   ← 附件解析（PDF / Office / CSV / JSON）
│   │   ├── image_ocr.rs      ← 图片 OCR 识别
│   │   └── auth/             ← JWT 认证中间件
│   ├── Cargo.toml            ← Rust 依赖配置
│   └── Cargo.lock
├── migrations/               ← SQL 迁移脚本（SQLite + MySQL）
├── frontend/                 ← React + TypeScript 前端
│   ├── src/
│   │   ├── api/             ← Axios HTTP 客户端
│   │   ├── components/      ← UI 组件（ChatPanel / SlidePreview / ArtifactPanel / ...）
│   │   ├── pages/           ← 页面（Studio.tsx = 主界面）
│   │   ├── stores/          ← Zustand 状态管理
│   │   ├── types/           ← TypeScript 类型定义
│   │   ├── config/          ← 前端配置
│   │   ├── lib/             ← 工具函数库
│   │   └── styles/          ← 全局样式
│   └── package.json
└── docs/                     ← 文档