mm_ai 1.0.0

package/example/project/ai_secretary/doc/PRD.md

@@ -0,0 +1,405 @@
+# AI秘书智能体 — 产品需求文档(PRD)
+
+> **文档版本**：v1.0  
+> **编写日期**：2025年  
+> **编写人**：product_manager  
+> **项目名称**：AI秘书智能体 (ai_secretary)  
+> **状态**：草稿
+
+---
+
+## 修订记录
+
+| 版本 | 日期 | 修订内容 | 修订人 |
+|------|------|---------|--------|
+| v1.0 | 2025-07 | 初稿创建 | product_manager |
+
+---
+
+## 目录
+
+1. [产品概述与目标](#1-产品概述与目标)
+2. [用户画像](#2-用户画像)
+3. [功能需求清单（含优先级）](#3-功能需求清单含优先级)
+4. [功能详情描述](#4-功能详情描述)
+5. [智能体能力要求](#5-智能体能力要求)
+6. [验收标准](#6-验收标准)
+
+---
+
+## 1. 产品概述与目标
+
+### 1.1 产品定位
+
+**AI秘书智能体**是一款运行在本系统内的智能助手，旨在为用户提供便捷的日常事务管理服务，包括天气查询、日程管理和待办提醒等功能。该智能体以对话交互的方式工作，用户可以通过自然语言与其沟通，获取所需信息或完成指定操作。
+
+### 1.2 产品目标
+
+- **核心目标**：为用户提供一个能高效处理日常事务的AI秘书，减少用户在不同工具间切换的成本
+- **体验目标**：对话式交互，自然语言理解，响应快速、精准
+- **业务目标**：成为用户日常使用的首选助手，提供可靠的信息查询和事务管理能力
+
+### 1.3 产品范围
+
+| 包含功能 | 不包含功能（后续迭代） |
+|---------|---------------------|
+| 实时天气查询 | 邮件收发管理 |
+| 日程管理（增/删/改/查/提醒） | 文件管理与云盘同步 |
+| 待办清单（增/删/改/查） | 会议室预订 |
+| 智能体对话交互 | 报销审批流程 |
+| | 第三方应用集成（如钉钉、飞书） |
+
+---
+
+## 2. 用户画像
+
+### 2.1 主要用户
+
+| 维度 | 描述 |
+|------|------|
+| **用户类型** | 自由职业者 / 个人用户 |
+| **典型用户** | admin（自由职业者） |
+| **使用场景** | 日常工作安排、生活事务管理、出行前查询天气 |
+| **技术背景** | 具备基本计算机操作能力，期望高效工具 |
+| **核心痛点** | 事务琐碎、容易遗忘，需要统一的助手管理日程和待办 |
+| **使用频率** | 每日多次 |
+
+### 2.2 用户故事
+
+| ID | 用户故事 | 优先级 |
+|----|---------|--------|
+| US-01 | 作为一名用户，我希望**查询当前天气**，以便决定是否带伞或增减衣物 | P0 |
+| US-02 | 作为一名用户，我希望**添加新的日程安排**，以便记录会议或约会 | P0 |
+| US-03 | 作为一名用户，我希望**查看我的日程列表**，以便了解当天或本周的安排 | P0 |
+| US-04 | 作为一名用户，我希望**收到日程提醒**，以免错过重要事项 | P0 |
+| US-05 | 作为一名用户，我希望**修改/删除已有日程**，以便灵活调整计划 | P1 |
+| US-06 | 作为一名用户，我希望**创建待办清单**，以便记录需要完成的任务 | P1 |
+| US-07 | 作为一名用户，我希望**查看待办清单**，以便追踪任务进度 | P1 |
+| US-08 | 作为一名用户，我希望**标记待办为已完成**，以便掌握完成情况 | P1 |
+| US-09 | 作为一名用户，我希望**删除待办项**，以便清理已完成或无效的任务 | P2 |
+| US-10 | 作为一名用户，我希望**通过自然语言与秘书对话**，以便快速下达指令 | P0 |
+
+---
+
+## 3. 功能需求清单（含优先级）
+
+### 3.1 优先级定义
+
+| 级别 | 定义 | 交付时间要求 |
+|------|------|-------------|
+| **P0** | 核心功能，必须实现，缺失则产品不可用 | 第一迭代 |
+| **P1** | 重要功能，建议实现，缺失影响体验 | 第二迭代 |
+| **P2** | 辅助功能，可以延后实现 | 后续迭代 |
+
+### 3.2 功能需求清单
+
+| 编号 | 功能模块 | 功能名称 | 功能描述 | 优先级 | 备注 |
+|------|---------|---------|---------|--------|------|
+| F-01 | 天气查询 | 实时天气查询 | 根据城市名查询当前天气、温度、湿度、风速等信息 | P0 | 需对接天气API |
+| F-02 | 天气查询 | 多城市天气 | 支持查询多个城市的天气情况 | P2 | 后续迭代 |
+| F-03 | 日程管理 | 添加日程 | 用户通过对话添加日程（标题、时间、地点、备注） | P0 | |
+| F-04 | 日程管理 | 查看日程 | 按日期查看日程列表，支持按天/周/月查看 | P0 | |
+| F-05 | 日程管理 | 修改日程 | 修改已有日程的标题、时间等信息 | P1 | |
+| F-06 | 日程管理 | 删除日程 | 删除指定日程 | P1 | |
+| F-07 | 日程管理 | 日程提醒 | 在日程开始前进行提醒通知 | P0 | 需提醒机制 |
+| F-08 | 待办清单 | 创建待办 | 添加待办事项（标题、截止日期、优先级） | P1 | |
+| F-09 | 待办清单 | 查看待办 | 查看所有待办清单，支持按状态筛选 | P1 | |
+| F-10 | 待办清单 | 标记完成 | 将待办项标记为已完成 | P1 | |
+| F-11 | 待办清单 | 删除待办 | 删除指定待办项 | P2 | |
+| F-12 | 智能交互 | 对话理解 | 支持自然语言理解，识别用户意图并执行操作 | P0 | 智能体核心能力 |
+| F-13 | 智能交互 | 上下文记忆 | 在同一会话中保持上下文连贯性 | P1 | |
+
+---
+
+## 4. 功能详情描述
+
+### 4.1 天气查询模块
+
+#### 4.1.1 功能概述
+
+用户通过对话向AI秘书询问天气信息，秘书调用天气查询工具获取实时数据并返回。
+
+#### 4.1.2 交互流程
+
+```
+用户：今天北京天气怎么样？
+秘书：正在查询北京天气...
+秘书：北京今日天气：晴，温度 28°C，体感温度 30°C，湿度 45%，西南风 3级。
+```
+
+#### 4.1.3 功能规格
+
+| 项目 | 规格说明 |
+|------|---------|
+| **触发方式** | 用户通过自然语言询问天气（如"今天天气如何"、"北京明天天气"） |
+| **输入参数** | 城市名称、日期（可选，默认当天） |
+| **输出内容** | 城市、日期、天气状况、温度（当前/最高/最低）、体感温度、湿度、风速风向 |
+| **数据来源** | 对接第三方天气API（如和风天气、OpenWeatherMap等） |
+| **异常处理** | 城市不存在时提示"暂未查到该城市天气信息"；网络异常时提示"天气服务暂时不可用" |
+
+#### 4.1.4 工具需求
+
+需要开发 **天气查询工具（weather_query）**，能力如下：
+
+| 能力项 | 描述 |
+|--------|------|
+| 工具名称 | weather_query |
+| 功能 | 根据城市名称查询实时天气信息 |
+| 输入 | `city`（城市名，必填），`date`（日期，可选） |
+| 输出 | JSON格式天气数据（天气状况、温度、湿度、风速等） |
+
+---
+
+### 4.2 日程管理模块
+
+#### 4.2.1 功能概述
+
+用户可通过对话管理个人日程，包括添加新日程、查看日程列表、修改/删除已有日程，并在日程临近时收到提醒。
+
+#### 4.2.2 交互流程
+
+**添加日程：**
+```
+用户：帮我安排下周三下午3点开项目会议
+秘书：已为您添加日程：项目会议
+  📅 时间：2025年7月30日 15:00
+  📍 地点：未设置
+  ⏰ 已设置提前15分钟提醒
+```
+
+**查看日程：**
+```
+用户：看看我今天的日程
+秘书：您今天的日程如下：
+  1. 09:00-10:00 晨会
+  2. 14:00-15:00 客户拜访
+  3. 15:30-16:30 项目会议 ⬅️ 即将开始
+```
+
+**修改/删除日程：**
+```
+用户：把下午3点的会议改到4点
+秘书：已修改日程"项目会议"，时间调整为 16:00-17:00
+```
+
+#### 4.2.3 功能规格
+
+| 项目 | 规格说明 |
+|------|---------|
+| **日程数据模型** | `{id, title, startTime, endTime, location, notes, reminderTime, status}` |
+| **添加日程** | 支持通过自然语言提取日程信息，默认提醒时间15分钟前 |
+| **查看日程** | 支持按天/周/月查看，默认当天 |
+| **修改日程** | 支持修改标题、时间、地点、备注、提醒时间 |
+| **删除日程** | 支持单条删除，删除前需确认 |
+| **日程提醒** | 到达提醒时间时主动通知用户 |
+
+#### 4.2.4 工具需求
+
+需要开发 **日程管理工具（schedule_manager）**，能力如下：
+
+| 能力项 | 描述 |
+|--------|------|
+| 工具名称 | schedule_manager |
+| 功能 | 管理日程的增删改查和提醒 |
+| 操作类型 | `add`（添加）、`list`（查看列表）、`update`（修改）、`delete`（删除）、`remind`（提醒） |
+| 数据存储 | 本地文件存储或轻量级数据库 |
+
+---
+
+### 4.3 待办清单模块
+
+#### 4.3.1 功能概述
+
+用户可管理个人待办事项，包括创建待办、查看待办列表、标记完成和删除待办。
+
+#### 4.3.2 交互流程
+
+**创建待办：**
+```
+用户：帮我记一下，周五前要提交周报
+秘书：已添加待办事项：
+  📝 提交周报
+  📅 截止日期：2025年8月1日（周五）
+  🔴 优先级：普通
+```
+
+**查看与标记：**
+```
+用户：我的待办有哪些？
+秘书：您的待办清单：
+  ✅ [已完成] 购买办公用品
+  ⬜ [进行中] 提交周报 - 截止：周五
+  ⬜ [未开始] 预约牙医 - 截止：下周一
+
+用户：把提交周报标记为已完成
+秘书：已标记"提交周报"为已完成 ✅
+```
+
+#### 4.3.3 功能规格
+
+| 项目 | 规格说明 |
+|------|---------|
+| **待办数据模型** | `{id, title, dueDate, priority, status, createdAt, updatedAt}` |
+| **创建待办** | 支持设置标题、截止日期、优先级（高/中/低，默认中） |
+| **查看待办** | 按创建时间排序，支持按状态筛选（全部/待办/已完成） |
+| **标记完成** | 将待办状态从"待办"更新为"已完成" |
+| **删除待办** | 支持单条删除 |
+
+#### 4.3.4 工具需求
+
+需要开发 **待办管理工具（todo_manager）**，能力如下：
+
+| 能力项 | 描述 |
+|--------|------|
+| 工具名称 | todo_manager |
+| 功能 | 管理待办清单的增删改查 |
+| 操作类型 | `add`（添加）、`list`（查看列表）、`update`（更新状态）、`delete`（删除） |
+| 数据存储 | 本地文件存储或轻量级数据库 |
+
+---
+
+### 4.4 智能交互模块
+
+#### 4.4.1 功能概述
+
+AI秘书智能体需具备自然语言理解能力，能够理解用户意图并调用相应工具完成任务。
+
+#### 4.4.2 能力要求
+
+| 能力项 | 描述 | 实现方式 |
+|--------|------|---------|
+| 意图识别 | 从用户输入中识别出意图（查询天气、管理日程、管理待办等） | 智能体自然语言处理能力 |
+| 实体提取 | 提取关键实体（城市名、日期、时间、事件标题等） | 智能体自然语言处理能力 |
+| 多轮对话 | 支持上下文理解，同一会话中保持连贯性 | 智能体对话管理能力 |
+| 工具调用 | 根据意图自动调用相应的工具完成任务 | 智能体工具调用机制 |
+| 结果呈现 | 将工具返回的数据以友好的方式呈现给用户 | 智能体回复生成能力 |
+
+---
+
+## 5. 智能体能力要求
+
+### 5.1 智能体基本信息
+
+| 项目 | 内容 |
+|------|------|
+| **智能体名称** | ai_secretary |
+| **角色定位** | AI秘书，帮助用户管理天气查询、日程和待办等日常事务 |
+| **运行环境** | 本智能体系统内运行 |
+
+### 5.2 所需技能
+
+| 技能名称 | 技能说明 | 用途 |
+|---------|---------|------|
+| **weather_query**（天气查询） | 调用天气API查询实时天气信息 | 响应天气查询需求 |
+| **schedule_management**（日程管理） | 管理用户日程的增删改查和提醒 | 响应日程管理需求 |
+| **todo_management**（待办管理） | 管理用户待办清单的增删改查 | 响应待办管理需求 |
+| **natural_language**（自然语言理解） | 理解用户意图，提取关键信息 | 核心交互能力 |
+| **dialogue_management**（对话管理） | 维护多轮对话上下文 | 提升交互体验 |
+
+### 5.3 所需工具
+
+| 工具名称 | 功能描述 | 输入参数 | 输出 |
+|---------|---------|---------|------|
+| **weather_query** | 查询指定城市的实时天气 | `city`(城市名), `date`(日期,可选) | JSON格式天气数据 |
+| **schedule_manager** | 日程的增删改查和提醒 | `action`(操作类型), `data`(日程数据) | 操作结果 |
+| **todo_manager** | 待办的增删改查 | `action`(操作类型), `data`(待办数据) | 操作结果 |
+| **notify_user** | 通知用户消息（提醒用） | `content`(提醒内容) | 发送通知 |
+
+### 5.4 智能体数据存储结构
+
+#### 日程数据（schedule.json）
+
+```json
+{
+  "schedules": [
+    {
+      "id": "sch_001",
+      "title": "项目会议",
+      "startTime": "2025-07-30T15:00:00",
+      "endTime": "2025-07-30T16:00:00",
+      "location": "会议室A",
+      "notes": "讨论Q3项目进度",
+      "reminderTime": "2025-07-30T14:45:00",
+      "status": "active"
+    }
+  ]
+}
+```
+
+#### 待办数据（todo.json）
+
+```json
+{
+  "todos": [
+    {
+      "id": "todo_001",
+      "title": "提交周报",
+      "dueDate": "2025-08-01",
+      "priority": "medium",
+      "status": "pending",
+      "createdAt": "2025-07-28T10:00:00",
+      "updatedAt": "2025-07-28T10:00:00"
+    }
+  ]
+}
+```
+
+---
+
+## 6. 验收标准
+
+### 6.1 功能验收标准
+
+| 编号 | 验收项 | 验收标准 | 优先级 |
+|------|-------|---------|--------|
+| AT-01 | 天气查询 | 输入"北京天气"，返回北京实时天气信息（温度、天气状况等） | P0 |
+| AT-02 | 天气查询异常 | 输入不存在的城市名，返回友好的错误提示 | P0 |
+| AT-03 | 添加日程 | 输入"明天下午3点开会"，成功创建日程并返回确认信息 | P0 |
+| AT-04 | 查看日程 | 输入"今天的日程"，返回当天的日程列表 | P0 |
+| AT-05 | 日程提醒 | 到达提醒时间，主动通知用户 | P0 |
+| AT-06 | 修改日程 | 输入"把明天的会议改到4点"，成功更新日程 | P1 |
+| AT-07 | 删除日程 | 输入"删除明天的会议"，成功删除并确认 | P1 |
+| AT-08 | 创建待办 | 输入"添加待办：买牛奶"，成功创建待办 | P1 |
+| AT-09 | 查看待办 | 输入"我的待办"，返回待办列表 | P1 |
+| AT-10 | 标记完成 | 输入"把买牛奶标记为完成"，状态更新为已完成 | P1 |
+| AT-11 | 删除待办 | 输入"删除买牛奶"，成功删除待办 | P2 |
+
+### 6.2 性能验收标准
+
+| 编号 | 验收项 | 验收标准 |
+|------|-------|---------|
+| PT-01 | 响应时间 | 用户发起请求后，3秒内给出回复 |
+| PT-02 | 并发支持 | 支持至少10个用户同时使用 |
+| PT-03 | 数据持久化 | 重启后日程和待办数据不丢失 |
+
+### 6.3 体验验收标准
+
+| 编号 | 验收项 | 验收标准 |
+|------|-------|---------|
+| UX-01 | 自然语言理解 | 用户可用自然语言对话，无需记忆固定指令格式 |
+| UX-02 | 信息呈现 | 返回信息格式清晰、易于阅读，使用emoji等提升可读性 |
+| UX-03 | 错误引导 | 当无法理解用户意图时，给出可操作的引导提示 |
+
+---
+
+## 附录
+
+### A. 依赖项
+
+| 依赖项 | 说明 |
+|-------|------|
+| 天气API | 需接入第三方天气数据服务（如和风天气、OpenWeatherMap等） |
+| 数据存储 | 本地JSON文件存储或轻量级数据库 |
+| 智能体系统 | 需支持创建新的智能体并赋予技能和工具 |
+
+### B. 风险与应对
+
+| 风险 | 影响 | 应对措施 |
+|------|------|---------|
+| 天气API服务不稳定 | 天气查询不可用 | 缓存最近查询结果，添加备用API |
+| 数据文件损坏 | 日程/待办数据丢失 | 定期备份，添加数据校验机制 |
+| 用户输入模糊 | 意图识别失败 | 提供引导式追问，帮助用户明确需求 |
+
+---
+
+> **文档结束**