项目地址：https://gitee.com/deng-6669/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 层），职责清晰，便于维护和扩展。

3.3 技术栈

类别	技术
框架	Flutter 3.11+
网络	Dio
本地存储	path_provider + JSON
Markdown	flutter_markdown
通知	flutter_local_notifications
文件选择	file_picker
网络状态	connectivity_plus

---

四、快速开始

4.1 环境要求

• Flutter SDK >= 3.11.5
• Dart SDK >= 3.11.5

4.2 安装与运行

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

# 安装依赖
flutter pub get

# 运行
flutter run

4.3 配置 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 格式的服务商，灵活接入。

4.4 构建发布

# 构建 Android APK
flutter build apk --release

---

五、亮点深度解读

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

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

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

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

5.2 工具调用的安全保障

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

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

5.3 本地优先的隐私策略

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

---

六、v0.7.0 重磅更新详解

v0.7.0 是项目迄今为止最重要的一次更新，从工具调度、任务规划、思考链可视化到群聊管理模式全面升级。以下逐一解读七大核心更新。

6.1 🔥 工具并发执行（Future.wait 并行调度）

v0.7.0 引入了 工具并发调度能力，基于 Future.wait 实现无依赖工具的并行执行。

改动前：AI 调用多个工具时，必须逐个串行等待返回，比如"查天气 + 搜网页 + 读笔记"三步走，总耗时 = 耗时A + 耗时B + 耗时C。

改动后：系统自动识别无依赖关系的工具调用，一次性并行触发，总耗时 ≈ max(耗时A, 耗时B, 耗时C)。

// 伪代码示意：无依赖工具并行执行
final results = await Future.wait([
  weatherTool.execute(args),
  webSearchTool.execute(query),
  noteStorageTool.list(),
]);

这意味着用户在多任务场景下等待时间大幅缩短，响应速度显著优化。

6.2 📋 任务规划工具（task_plan）

新增 task_plan 工具——一个多步任务管理能力。AI 在处理复杂需求时，可以先规划出结构化的任务流程，再逐步执行。

解决的问题：之前 AI 处理多步骤任务容易遗漏步骤、顺序错乱，比如"先查天气再搜攻略再写笔记"，中间一步跳过整个流程就断了。

task_plan 的作用：

• AI 先用 task_plan 工具把任务拆解为有序步骤
• 每完成一步，更新规划状态
• 确保流程完整、不遗漏、不乱序

这让 AI 从"想到哪做到哪"升级为"先规划再执行"的工程化模式。

6.3 🧠 思考链可视化（ThinkingChunkEvent + reasoning_content）

v0.7.0 支持 思考链实时渲染，对接 DeepSeek-R1、Claude 等模型的 reasoning 能力。

• 支持 ThinkingChunkEvent 事件流，流式接收模型推理过程
• 支持 reasoning_content 字段，实时展示模型的思考内容
• 推理过程透明可见，用户能看到 AI"怎么想的"

这意味着 AI 不再是黑箱——它的每一步推理过程都直观呈现，逻辑更清晰，也方便用户判断 AI 的思考方向是否正确。

6.4 👔 群聊 Manager 模式

这是 Agent 群协作的重大升级。v0.7.0 集成了 Manager 智能协调机制：

• Manager 自动分配发言角色，决定"谁先说、谁补充"
• 群聊协作从"自由发言"升级为"有组织地讨论"
• 避免多个 Agent 抢话、重复输出，交互更智能有序

对比 v0.6.0 的协调者机制，Manager 模式更进一步——不仅分配任务，还管理群聊的发言节奏和秩序。

6.5 📊 并发状态 UI 可视化

配合工具并发执行，UI 层也做了相应升级：

• 支持 多工具并行标签展示，每个正在执行的工具都有独立状态标签
• 直观呈现多任务并发运行状态
• 用户一眼就能看到"当前有几个工具在并行跑"

6.6 🏗️ 系统稳定性全面优化

底层修复多处关键问题：

• 修复 mounted 挂载检测，避免组件卸载后仍触发状态更新
• 修复 dispose 资源释放，杜绝内存泄漏
• 修复滚动渲染问题，长列表滚动更流畅
• 整体运行更稳定、更流畅

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

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

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

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

---

七、更新日志速览

项目迭代活跃，以下是近期主要版本：

v0.7.0 🔥

• 工具并发执行（Future.wait 无依赖工具并行），大幅提升多任务处理效率
• 新增 task_plan 任务规划工具，支持流程结构化记录
• 升级思考链可视化渲染（ThinkingChunkEvent + reasoning_content）
• 新增群聊 Manager 智能协调模式，自动分配发言角色
• 并发状态 UI 可视化升级，多工具并行标签展示
• 系统稳定性全面优化（mounted 检测、dispose 释放、滚动渲染）
• 新增「高考志愿规划师・张雪峰定制版」Agent

v0.6.3

• 新增 manage_notes 工具：AI 可列出 / 修改 / 删除已有笔记
• 新增 manage_memory 工具：AI 可列出 / 修改 / 删除已有记忆
• system prompt 补充增删改查指引，避免 AI 凭空假设内容

v0.6.2

• 集成 SearXNG 自托管搜索（免费替代 Tavily），优先使用 / 失败回退
• 版本号统一到 AppConfig 常量，设置页 & 关于页自动同步

v0.6.1

• 强化工具调用铁律，system prompt + 4 个工具描述禁 AI 幻觉
• 修复 connectivity_service 适配 connectivity_plus 6.x
• ListView 加 cacheExtent，imageUrls 正则缓存，性能优化
• NoteStorage / MemoryStorage / ReminderStorage 加通知机制，UI 自动刷新

v0.6.0

• 🎉 Agent 群功能上线：多 Agent 协作、协调者、审核机制、通信矩阵
• Agent 相互引用同伴观点
• 自定义 Agent（独立 prompt / 工具 / AI 后端）
• 修复 Agent 身份混淆、流式输出 UI 不更新、Stop 按钮无效等问题

---

八、总结

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

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

📌 项目地址：https://gitee.com/deng-6669/personal-agent-app