AICompanion 开发日志 01：项目搭建与环境准备
最近我开始做一个新的项目：AICompanion。它的目标是做一个运行在 Windows 电脑桌面上的 AI 聊天陪伴系统，未来也可能扩展到安卓端。
这个项目不只是普通聊天窗口，而是希望逐步实现一个更像“桌面伙伴”的系统：它可以拥有动漫角色设定，能记住聊天内容，有情绪状态，在我长时间没有回复时主动发消息给我，后续再加入 TTS 语音回复和 Live2D 角色展示。
这篇文章是这个系列的第 1 篇，主要记录项目从 0 到 1 的环境搭建和基础结构设计。
1. 项目目标
AICompanion 当前的核心目标可以拆成几部分：
- 使用 PySide6 开发 Windows 桌面聊天窗口。
- 通过 API 调用大模型，实现多轮对话。
- 使用 SQLite 保存聊天记录、长期记忆和任务提醒。
- 加入情感系统，让角色回复不只是机械问答。
- 支持主动消息，例如用户长时间没回复时，角色可以主动问候。
- 后续加入 TTS 语音回复。
- 最终尝试接入 Live2D，让动漫角色可以根据情绪切换表情和动作。
我希望它最终不是一个“输入框 + 回复框”的简单工具，而是一个有角色感、有陪伴感、能长期相处的桌面 AI。
2. 技术选型
目前项目采用的基础技术栈如下：
| 模块 | 技术方案 | 选择原因 |
|---|---|---|
| 桌面界面 | PySide6 | Python 生态友好，适合快速开发 Windows 桌面程序 |
| 大模型调用 | OpenAI-compatible API | 方便切换不同模型服务商 |
| 本地存储 | SQLite | 轻量、无需单独部署数据库服务，适合桌面应用 |
| 配置管理 | python-dotenv | 将 API Key 等敏感信息放入 .env |
| 项目结构 | src layout | 让代码组织更清晰，方便后续扩展 |
| 语音回复 | TTS，后续接入 | 第 5 周再加入 |
| 角色展示 | Live2D，后续尝试 | 第 6 周再做探索 |
整体结构可以先理解成这样：
3. 开发计划
项目暂时按六个阶段推进：
| 周次 | 目标 |
|---|---|
| 第 一 阶段 | 使用 Python + PySide6 做聊天窗口 |
| 第 二 阶段 | 接入大模型，实现多轮聊天 |
| 第 三 阶段 | 使用 SQLite 保存聊天记录和记忆 |
| 第 四 阶段 | 加入主动消息、角色设定、表情切换 |
| 第 五 阶段 | 加入 TTS 语音回复 |
| 第 六 阶段 | 尝试接入 Live2D |
这样的安排有一个好处：每一周都可以得到一个能运行的小版本，而不是一开始就把所有东西堆在一起。
4. 项目目录结构
当前项目路径为：
D:\Study\AICompanion目前的目录结构大致如下：
AICompanion/
.venv/ # Python 虚拟环境
data/ # SQLite 数据库等本地数据
docs/ # 项目文档
src/
aicompanion/
app.py # QApplication 启动入口
config.py # 配置读取
controllers/ # 业务流程控制
domain/ # 角色、情绪等领域模型
llm/ # 大模型调用抽象与实现
services/ # 记忆、提醒、主动消息等服务
storage/ # SQLite 数据库访问
ui/ # PySide6 界面组件
.env.example # 环境变量示例
.gitignore # Git 忽略规则
main.py # 程序启动文件
pyproject.toml # Python 项目配置
README.md # 项目说明
requirements.txt # 依赖列表这个结构的重点是分层：
ui只负责界面显示和用户交互。controllers负责把界面、大模型、存储和服务串起来。llm负责封装不同模型 API。storage负责数据库。services负责更高层的功能，例如长期记忆、提醒、主动消息。domain放角色、情绪、提示词等核心概念。
这样做的好处是后续更容易扩展。比如以后从 PySide6 扩展到安卓端时，理论上可以复用一部分 llm、storage、services 和 domain 的逻辑。
5. Python 版本与虚拟环境
项目目前要求 Python 版本不低于 3.11：
requires-python = ">=3.11"在 Windows 下，建议每个项目都使用独立虚拟环境。这样不同项目之间的依赖不会互相污染。
创建虚拟环境：
python -m venv .venv激活虚拟环境：
.\.venv\Scripts\activate升级 pip：
python -m pip install --upgrade pip安装依赖：
python -m pip install -r requirements.txt当前 requirements.txt 中的核心依赖很少：
PySide6>=6.7
python-dotenv>=1.0这里先保持依赖克制，只安装当前阶段真正需要的包。等到后续接入大模型、TTS、Live2D 时，再逐步加入新的依赖。
6. 为什么要用 .env
项目后续会调用大模型 API，而 API Key 不能直接写在代码里。
因此项目提供了 .env.example，用于说明需要哪些配置项：
LLM_PROVIDER=openai_compatible
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=your_api_key
LLM_MODEL=gpt-4o-mini真正运行时，可以复制一份为 .env：
Copy-Item .env.example .env然后把自己的 API Key 写入 .env。
.env 应该加入 .gitignore，不要提交到 GitHub。这样既能方便本地开发，也能避免泄露密钥。
7. Docker 在这个项目中的定位
这个项目是 Windows 桌面应用，界面层依赖 PySide6。对于这种带 GUI 的桌面程序，最自然的开发方式仍然是在本机虚拟环境中运行，而不是完全放进 Docker。
原因是 Docker 更适合运行服务端程序，例如 Web 服务、数据库、消息队列等。PySide6 这种桌面窗口程序需要和本机图形界面交互，在 Windows 上放进 Docker 会增加很多额外复杂度。
所以我对 Docker 的定位是：
- 当前阶段：不强制使用 Docker，优先使用
.venv本地开发。 - 后续如果增加后端服务：可以用 Docker 管理服务端组件。
- 如果需要统一命令行测试环境：可以写 Dockerfile 做辅助验证。
- SQLite 不需要单独放入 Docker，因为它本身就是本地文件数据库。
如果后续要补一个基础 Dockerfile，可以先用于安装依赖和运行非 GUI 脚本：
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]不过要注意：这个 Dockerfile 更适合做环境验证，不适合作为当前 Windows 桌面 GUI 的主要运行方式。
8. 本地运行项目
当前 README 中的运行方式如下：
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe main.py其中：
pip install -r requirements.txt用来安装项目依赖。pip install -e .用来以可编辑模式安装当前项目。python main.py用来启动桌面程序。
可编辑模式的好处是：修改 src/aicompanion 里的代码后，不需要反复重新安装包。
9. 当前阶段的最小可运行目标
第 1 周最重要的事情不是把所有功能都做完，而是先得到一个稳定的最小版本。
这个最小版本需要做到：
- 能打开一个 PySide6 聊天窗口。
- 能输入消息并显示到聊天区。
- 能显示 AI 的模拟回复。
- 界面结构不要写死，为后续接入真实大模型做准备。
- 代码分层清晰，不把所有逻辑都塞进一个窗口文件。
只要这个基础打稳，后续接入大模型、SQLite、主动消息和 Live2D 时，就不会频繁推倒重来。
10. 下一步计划
下一篇文章准备记录第一阶段的核心实现：如何用 PySide6 搭建聊天窗口。
预计会包括：
QMainWindow的基础结构。- 聊天记录显示区域。
- 用户输入框和发送按钮。
- 如何把 UI 事件交给 Controller 处理。
- 为什么不能在界面线程里直接请求大模型。
从这一篇开始，AICompanion 就正式进入开发日志模式。后续每一个功能都尽量写成一篇文章，既记录实现过程，也记录中间踩过的坑和设计取舍。