项目地址：Gitee地址：https://gitee.com/deng-6669/personal-agent-app
GitHub地址:https://github.com/3d-jq/personal-agent-app

一个基于 Flutter 构建的功能丰富的 Android AI 助理应用，支持多 Agent 团队协作、多后端 AI 对话、13 种工具调用、记忆系统等。本文将从功能特性、架构设计、核心实现到快速上手，带你全面了解这个项目。

---

一、项目简介

personal-agent-app 是一个仅面向 Android 平台的 AI 助理应用，基于 Flutter 3.11+ 构建。它的核心亮点在于 Agent 群协作机制——多个不同职能的 AI Agent 像真实团队一样，在群聊中讨论、接力、审核，最终协同完成复杂任务。

不同于常见的"单轮对话 + 工具调用"模式，这个项目把 多 Agent 编排 做成了开箱即用的功能：

• 🤖 协调者 Agent 常驻响应，自动拆解任务并分派
• 🔄 Agent 间接力，完成任务后可 @ 下一个 Agent 继续
• ✅ 审核/封驳机制，复杂方案需群主确认后才执行
• 🔒 严格工具隔离，Agent 只能调用只读类工具，零数据污染

---

二、核心功能特性

2.1 🤖 Agent 群（团队协作）

这是整个项目最核心的设计。你可以把它理解为一个"AI 公司"：

特性	说明
多 Agent 协作	不同职能的 AI Agent 在群里讨论、接力完成任务
协调者 Agent	DWeis Agent 常驻响应，自动拆解任务、分派给合适的 Agent
审核/封驳机制	复杂方案必须经群主确认后才执行，质量有保障
通信矩阵	Agent 优先通过协调者调度，避免消息风暴
Agent 间接力	完成任务的 Agent 可 @ 下一个继续，形成工作流
自定义 Agent	自由创建 Agent，独立配置 system prompt、工具白名单、AI 后端
严格工具隔离	Agent 只能调只读类工具，不会污染用户数据
Agent 间相互引用	Agent 能看到同伴的发言，可以说"我同意产品经理的分析"

2.2 💬 AI 对话

• 支持 OpenAI / Anthropic / DeepSeek / Agnes 等多种 AI 后端
• 流式输出 + 工具调用（Function Calling）
• 多会话管理，聊天记录本地持久化

2.3 🛠️ 工具调用（13 个内置工具）

AI 可以调用以下工具来与现实世界交互：

天气查询、网页搜索、网页内容抓取
图片生成、视频生成（Agnes AI）
笔记管理、记忆系统、定时提醒
日历集成、文件管理、剪贴板操作

2.4 🧠 记忆系统

• AI 记住用户偏好和重要事实
• 个性化回复风格（默认/简洁/详细/幽默/专业）
• 支持自定义指令

2.5 🎨 其他特性

• 亮色/暗色主题，400ms 颜色补间动画
• 每日 AI 问候卡片（聚合天气 + 日程 + 记忆）
• 笔记管理、媒体库

---

三、架构设计

3.1 设计理念

项目遵循四大设计原则：

1. 数据驱动 — Agent 的协调者身份用 isCoordinator 字段控制，不硬编码名字
2. 严格隔离 — Agent 只能调只读工具（方案 A），用户数据零污染
3. 本地优先 — 所有数据以 JSON 文件本地存储，带损坏备份机制
4. 缓存策略 — 存储层内存缓存 + AsyncLock 串行化写操作

3.2 目录结构

lib/
├── main.dart                    # 入口
├── app.dart                     # 应用根（主题、动效背景）
├── core/agent_colors.dart       # 设计系统（暖灰色调）
├── models/                      # 数据模型
│   ├── agent.dart               # Agent 定义
│   ├── agent_group.dart         # Agent 群定义
│   ├── chat_message.dart        # 消息模型
│   ├── chat_session.dart        # 会话模型
│   └── ...
├── services/                    # 服务层（单例 + 本地 JSON 持久化）
│   ├── ai_service.dart          # AI 通信（OpenAI/Anthropic 流式）
│   ├── agent_runner.dart        # Agent 执行器
│   ├── agent_storage.dart       # Agent CRUD
│   ├── agent_group_storage.dart # 群 CRUD
│   ├── memory_storage.dart     # 记忆系统
│   └── ...
├── tools/                       # 13 个 Agent 工具
│   ├── tool_registry.dart       # 工具注册中心
│   ├── weather_tool.dart        # 天气查询
│   ├── web_search.dart          # 网页搜索
│   └── ...
├── widgets/                     # UI 组件
│   ├── agent_group/             # Agent 群相关 UI
│   │   ├── group_chat_screen.dart
│   │   ├── group_list_page.dart
│   │   ├── group_edit_page.dart
│   │   └── agent_manage_page.dart
│   └── ...
└── screens/                     # 页面
    ├── chat_screen.dart         # 主聊天页
    └── ...

整体采用 分层架构：models（数据模型）→ services（业务逻辑 + 持久化）→ tools（工具层）→ widgets/screens（UI 层），职责清晰，便于维护和扩展。

四、快速开始

4.1安装与运行

# 克隆项目
git clone https://gitee.com/deng-6669/personal-agent-app.git
cd personal-agent-app

# 安装依赖
flutter pub get

# 运行
flutter run

4.2配置 AI 后端

首次启动时在设置中配置 AI 后端，支持以下厂商：

厂商	Base URL	说明
DeepSeek	https://api.deepseek.com/v1	国内推荐，性价比高
OpenAI	https://api.openai.com/v1	GPT-4o 等模型
Anthropic	https://api.anthropic.com	Claude 系列
Agnes	https://apihub.agnes-ai.com/v1	图片/视频生成

💡 也支持其他兼容 OpenAI API 格式的服务商，灵活接入。

五、亮点深度解读

5.1 Agent 群协作是怎么工作的？

想象一个场景：你向 Agent 群提出"帮我规划一次周末出游"。

1. 协调者 Agent（DWeis） 接收请求，拆解为子任务
2. 分派给 旅行规划 Agent → 查天气、搜攻略
3. 旅行规划 Agent 完成后 @ 笔记 Agent → 自动整理成笔记
4. 如涉及复杂决策，触发 审核机制，等待群主确认后执行

整个过程就像一个真实团队的协作流程，而你需要做的只是发出一条指令。

5.2 工具调用的安全保障

项目在工具隔离上做了严格设计：

• Agent 只能调用只读类工具（方案 A）
• 用户数据零污染——Agent 不会意外修改或删除你的笔记、记忆
• 每个自定义 Agent 可独立配置 工具白名单，精细控制权限

5.3 本地优先的隐私策略

• 所有数据存储在本地设备上
• API Key 仅用于调用 AI 服务
• 聊话记录、笔记等不会被收集或上传
• 存储层带损坏备份机制，数据更安全

---

六、重磅功能详解

1. 图文并茂笔记功能：让笔记和图片结合，生成图文并茂的笔记

让笔记不在只是孤单文字，结合图片，让笔记更加生动。如图所示生成了一个苏州旅游的图文并茂的笔记

2.🎓 全新 Agent：高考志愿规划师

v0.7.0 上线了一个全新的智能助手——「高考志愿规划师・张雪峰定制版」 Agent：

• 提供专业的志愿填报咨询服务
• 贴合择校逻辑，结合分数线、位次、专业前景给出建议
• 基于张雪峰的志愿填报方法论定制 system prompt

这是项目首次推出"垂直领域专家 Agent"，展示了自定义 Agent 在实际场景中的应用价值。

八、总结

personal-agent-app 是一个设计精良的 Flutter AI 助理项目，它的核心价值在于：

• ✅ 多 Agent 协作不是概念，而是开箱即用的功能
• ✅ 13 种工具调用让 AI 真正能"动手"
• ✅ 记忆系统让 AI 越用越懂你
• ✅ 本地优先保障隐私安全
• ✅ 多后端支持灵活接入各种国内 AI

📌 项目地址：Gitee地址:https://gitee.com/deng-6669/personal-agent-app
GitHub地址：https://github.com/3d-jq/personal-agent-app