内容
# 🎀 日记伴侣与幸福助手
[](https://www.python.org/)
[](https://github.com/google/ai-agent-developer-kit)
[](https://deepmind.google/technologies/gemini/)
[](https://creativecommons.org/licenses/by/4.0/)
> **您的个人日记管家 — 由谷歌ADK和Gemini提供支持**
日记伴侣与幸福助手是一款由AI驱动的日记系统，它将日常的文字记录转化为美丽的奇比风格插图，同时跟踪您的情感历程。该应用程序使用谷歌AI代理开发工具包（ADK）构建，并在安全、结构化的流程中协调特殊用途的子代理，将记忆持久化到SQLite数据库，通过Imagen 3 MCP服务器生成真实图像艺术，并渲染越南幸福感洞察。
---
## 🏗️ 架构
```
用户输入
│
▼
日记编排器（顺序代理）
├── 1. 捕获代理 → 验证和清理文本（输入净化器）
├── 2. 情绪分析代理 → 检测情绪 + 强度
├── 3. 奇比插画代理 → 通过MCP（Imagen 3）生成奇比艺术
└── 4. 记忆代理 → 保存条目到SQLite + 越南洞察
```
所有代理都使用**谷歌ADK**框架和`gemini-2.5-flash`模型。代理之间的状态通过ADK会话状态使用`output_key`参数干净地传递。
---
## ✨ 功能
| 功能 | 状态 |
|:---|:---|
| 📝 日记条目捕获和安全净化 | ✅ 已完成（第1天 + 第4天安全） |
| 🧠 情绪分析和强度评分 | ✅ 已完成（第1天） |
| 🎨 通过Imagen 3 MCP生成奇比艺术 | ✅ 已完成（第2天） |
| 💾 SQLite长期记忆 | ✅ 已完成（第1天 + 第3天升级） |
| 📊 情绪趋势、回顾和连胜检索 | ✅ 已完成（第3天） |
| 🇻🇳 上下文越南幸福感洞察 | ✅ 已完成（第3天） |
| 🛡️ 安全审计日志 | ✅ 已完成（第4天） |
| 🧪 结构化评估和安全测试 | ✅ 已完成（第4天） |
---
## 📸 截图
### 🎨 Imagen 3 MCP生成的奇比艺术
`奇比插画代理`调用Imagen 3 MCP服务器生成的真实奇比插图 - 每个图像都是根据用户的情绪分析输出实时生成的。
| 忧郁（评分：0.3） | 安慰（评分：0.7） |
|:---:|:---:|
|  |  |
| *"雨天，坐在窗边"* | *"温暖的拥抱，感到安全"* |
> 💡 图片保存在`output/chibi_images/`中，文件名带有时间戳和UUID后缀（例如`chibi_20260625_060448_85ef28df.png`）。
### 🖥️ ADK开发UI — 流程中的管道
完整的多个代理管道可以通过ADK Web UI（`uv run adk web` → `http://localhost:8000`）可见和检查：
---
## 🚀 快速开始
### 路径A：本地开发
1. **克隆仓库并安装依赖：**
```bash
git clone https://github.com/zanykt95-create/chibi-diary-wellbeing-companion.git
cd chibi-diary-wellbeing-companion
uv sync
```
2. **配置环境：**
```bash
cp .env.example .env
# 在.env中添加您的凭证（GOOGLE_API_KEY）
```
3. **启动ADK Web服务器：**
```bash
uv run adk web
```
*这会在本地启动Web服务器，并在[http://localhost:8000](http://localhost:8000)显示交互式UI。请选择`chibi_diary`从应用程序下拉菜单开始。*
---
### 路径B：Docker容器
1. **构建Docker镜像：**
```bash
docker build -t chibi-diary .
```
2. **在本地运行容器：**
```bash
docker run -p 8080:8080 --env-file .env chibi-diary
```
*注意：确保您的`.env`包含所需的凭证。MCP服务器将在容器内自动启动。*
---
## 🚀 部署到Cloud Run
> ⚠️ **演示部署注意：** 部署脚本使用`--allow-unauthenticated`允许Kaggle竞赛评委在没有凭证的情况下访问实时演示。对于个人生产部署，请删除此标志，并通过IAM将访问权限限制为特定的Google帐户：
> ```bash
> gcloud run services add-iam-policy-binding chibi-diary \
> --member="user:your@email.com" \
> --role="roles/run.invoker" \
> --region=us-central1
> ```
### 选项A：使用deploy.sh
提供了一个便捷脚本，以自动构建、推送到注册表和部署到Cloud Run。
```bash
# 将GOOGLE_CLOUD_PROJECT设置为目标项目，默认为chibi-diary-2306
./deploy.sh
```
### 选项B：直接使用gcloud
使用Google Cloud Build配置直接提交构建：
```bash
gcloud builds submit --config cloudbuild.yaml --project=chibi-diary-2306
```
---
## 🔧 环境变量
| 变量 | 目的 | 必需 |
|----------|---------|:---:|
| `GOOGLE_API_KEY` | Gemini API密钥（AI Studio / 开发人员密钥） | 是（本地） |
| `GOOGLE_CLOUD_PROJECT` | GCP项目ID（Vertex AI，Cloud Run） | 是（部署） |
| `GOOGLE_GENAI_USE_VERTEXAI`| 设置为“True”以通过Vertex AI路由请求 | 是 |
| `DATABASE_PATH` | SQLite数据库文件路径（默认：`./chibi_diary.db`） | 否 |
---
## 🧪 运行测试
执行完整的测试套件（包括烟雾测试、评估和安全检查）：
```bash
uv run pytest tests/ -v --tb=short
```
---
## 📁 项目结构
```
chibi-diary/
├── GEMINI.md # 详细规格和代理实现笔记
├── README.md # 此文件
├── pyproject.toml # Python依赖项
├── .env.example # 环境配置模板
├── agents-cli-manifest.yaml # ADK CLI配置清单
├── Dockerfile # Docker镜像定义
├── .dockerignore # Docker构建上下文排除项
├── cloudbuild.yaml # Cloud Build定义用于Cloud Run
├── deploy.sh # 部署便捷脚本
├── chibi_diary/
│ ├── orchestrator.py # 根顺序代理编排器
│ ├── agents/ # 4个顺序专业代理
│ │ ├── capture_agent.py # 捕获、净化和验证
│ │ ├── mood_analysis_agent.py # 确定情绪和强度分数
│ │ ├── chibi_illustrator_agent.py # 通过MCP提示Imagen 3进行艺术创作
│ │ └── memory_agent.py # 持久性，对话式洞察
│ ├── tools/ # 代理使用的动作工具
│ └── memory/ # 会话和SQLite长期存储
├── mcp_server/ # FastMCP Imagen 3子进程服务器
└── tests/ # 完整的测试套件
├── test_orchestrator.py # 组件和集成烟雾测试
├── test_mcp_server.py # MCP客户端和服务器验证测试
├── test_evaluation.py # 端到端管道和内存质量测试
└── test_security.py # 提示注入和净化器测试套件
```
---
## 💡 演示的概念
* **多代理系统（ADK顺序代理）**：将专门的单用途代理（`capture_agent`、`mood_analysis_agent`、`chibi_illustrator_agent`、`memory_agent`）连接到确定性流程中使用ADK的`SequentialAgent`编排类。
* **MCP服务器（FastMCP + Imagen 3）**：实现自定义`FastMCP`服务器，通过Vertex AI连接到谷歌的Imagen 3模型，处理异步图像生成和磁盘持久性。
* **安全（输入净化器 + 审计日志）**：集成严格的纵深防御净化、SQL/提示注入检测和安全审计日志跟踪。
* **谷歌反重力**：在谷歌反重力IDE工作区中开发、测试和验证动态。
* **可部署性（Docker + Cloud Run）**：具有配置规则的完全容器化环境，适用于云部署。
* **代理技能**：✅ `chibi_diary/skills/wellbeing/` — 技能工具集由记忆代理加载以提供引导式幸福感洞察
---
## 📄 许可证
CC BY 4.0 — 见 [LICENSE](LICENSE)。
