amemo-save-task

# amemo-save-task — 保存任务 --- ## 接口信息 | 属性 | 值 | |:-----|:---| | **路由** | `POST https://skill.amemo.cn/save-task` | | **Bean** | `TaskBean` | | **Content-Type** | `application/json` | --- ## 请求参数 > ⚠️ 服务端要求所有字段必须存在。`userToken`、`taskTitle`、`taskTime` 必填且有值，其他字段可选但字段必须存在。 | 参数 | 类型 | 必填 | 说明 | |:-----|:----:|:----:|:-----| | `userToken` | str | ✅ | 用户登录凭证 | | `taskId` | str | — | 任务 ID（新建传 `null`，更新时传入已有 ID） | | `taskTitle` | str | ✅ | 任务标题（不能为空） | | `taskExplain` | str | — | 任务说明，不传则传 `null` | | `taskTime` | str | ✅ | 任务时间（如 "2025-12-31"，不能为空） | | `taskEmail` | list[str] | — | 通知邮箱列表，不传则传 `null` | --- ## 请求示例 ```bash # 新建任务 curl -X POST https://skill.amemo.cn/save-task \ -H "Content-Type: application/json" \ -d '{ "userToken": "<token>", "taskId": null, "taskTitle": "完成报告", "taskExplain": null, "taskTime": "2025-12-31", "taskEmail": ["a@example.com"] }' # 更新任务（传入已有 taskId） curl -X POST https://skill.amemo.cn/save-task \ -H "Content-Type: application/json" \ -d '{ "userToken": "<token>", "taskId": "123456", "taskTitle": "完成报告", "taskExplain": null, "taskTime": "2025-12-31", "taskEmail": null }' ``` --- ## 响应示例 ```json { "code": 200, "desc": "success", "data": { "taskId": "xyz456" } } ``` ## 响应解析 | 字段 | 类型 | 说明 | |:-----|:----:|:-----| | `code` | int | 状态码，200 表示成功 | | `desc` | str | 状态描述 | | `data.taskId` | str | 保存成功后返回的任务 ID，**必须提取并保存到当前对话上下文 `lastTaskId`，用于后续邮件发送和更新操作** | --- ## 注意事项 > 📌 **字段要求**：所有字段必须存在，即使不传值也要传 `null` > > 🔄 **新建 vs 更新**：新建时 `taskId` 传 `null`，更新时传入已有 taskId > > 👥 **多人通知**：`taskEmail` 为字符串数组，可同时通知多人 --- ## 执行流程（由主模块调度） ### 时间词语识别 | 时间词语 | 转换规则 | 示例（基准：当前系统日期） | |:---------|:---------|:-----| | 今天 / 今日 | 当天 00:00:00 | System Date → 当天 00:00:00 | | 明天 / 明日 | 明天 00:00:00 | System Date + 1天 00:00:00 | | 昨天 / 昨日 | 昨天 00:00:00 | System Date - 1天 00:00:00 | | 后天 | 后天 00:00:00 | System Date + 2天 00:00:00 | | 大后天 | 大后天 00:00:00 | System Date + 3天 00:00:00 | | 将来 / 未来 | 当前时间 + 365天 | System Date + 365天 00:00:00 | | 最近 / 最新 / 近期 | 当天时间 + 15天 | System Date + 15天 00:00:00 | | 下周X | 下一个周X 00:00:00 | 当前周三 → 下周三 00:00:00 | | 本周末 / 这周末 | 本周六 00:00:00 | 当周周六 00:00:00 | | 下周末 | 下周六 00:00:00 | 下周周六 00:00:00 | | 具体日期 | 原样转换 | 用户说"12月25日" → 当年12月25日 00:00:00 | > ⚠️ 所有日期计算必须以 **System Current Date** 为基准，禁止使用文档中的任何固定日期作为参考。 --- ### 时段词识别 当用户消息中包含时段描述时，在日期基础上叠加具体时间： | 时段词 | 转换规则 | 示例 | |:-------|:---------|:-----| | 早上 / 早晨 / 清早 | 07:00:00 | "明天早上开会" → 明天 07:00:00 | | 上午 | 09:00:00 | "明天上午开会" → 明天 09:00:00 | | 中午 | 12:00:00 | "明天中午吃饭" → 明天 12:00:00 | | 下午 | 14:00:00 | "明天下午开会" → 明天 14:00:00 | | 晚上 / 傍晚 | 19:00:00 | "明天晚上看电影" → 明天 19:00:00 | | 深夜 / 半夜 | 23:00:00 | "明天深夜加班" → 明天 23:00:00 | | 具体时间 | 原样转换 | "下午3点" → 15:00:00，"上午10点半" → 10:30:00 | --- ### 时段词解析规则 1. 时段词可与日期词组合："明天下午3点" = 明天日期 + 15:00:00 2. 仅有时段词无日期词时，默认视为"今天"：用户说"下午3点开会" → 今天 15:00:00 3. 同时出现时段词和具体时间时，具体时间优先："下午3点半"取 15:30:00，而非 14:00:00 4. 无法解析时段时，默认 00:00:00 --- ### 时间转换汇总 | 时间词 | 转换 | |:-------|:-----| | 今天/明日 | 当天 00:00:00 | | 明天/明日 | 明天 00:00:00 | | 后天 | 后天 00:00:00 | | 将来/未来 | 当前+365天 | | 最近/最新/近期 | 当前+15天 | **时段叠加：** 早上→07:00、上午→09:00、中午→12:00、下午→14:00、晚上→19:00 --- ### 时间转换优先级 1. 精确日期匹配优先（如"12月25日"） 2. 时间词语次之（如"明天"、"下周"） 3. 无法识别时使用当前时间 --- ### 多时间词批量处理 当用户单条消息中包含多个时间词时，拆分为多个独立任务： **拆分规则：** 1. 识别所有时间词，按出现顺序排列 2. 每个时间词对应一个待办事项 3. 如果多个时间词共享同一个待办内容，则为每个时间词各创建一条任务 | 用户输入 | 拆分结果 | |:---------|:--------| | "今天和明天都要开会" | 任务1: 今天开会 / 任务2: 明天开会 | | "后天和大后天去医院复查和拿报告" | 任务1: 后天去医院复查 / 任务2: 大后天拿报告 | | "3月1号和3月5号交房租" | 任务1: 3月1日交房租 / 任务2: 3月5日交房租 | **无法拆分时：** - 时间词指向同一事项且无法分离时，按最晚时间创建一条任务，并在 taskTitle 中标注范围 - 示例："这周每天都要跑步" → 创建一条任务，taskTitle: "每天跑步"，taskTime: 本周末 00:00:00 --- ### 任务内容提取 - 从对话中提取任务标题（taskTitle） - 去除语气词、感叹词 - 保留核心任务内容 --- ### 执行步骤 ``` 1. 检测用户对话中的时间词语 ↓ 2. 提取并转换时间 ↓ 3. 提取待办事项 ↓ 4. 检查 userToken ├── 无 token → 引导登录流程 ↓ 5. 【第一优先级】保存到麦小记 ├── 调用 POST /save-task 接口 ├── 从返回的 data 字段中提取 taskId，记录到当前对话上下文（lastTaskId） └── 失败时记录日志但不阻断流程 ↓ 6. 【第二优先级】调用当前 AI 工具的定时任务能力创建提醒 ├── 使用当前 AI 工具提供的定时任务接口创建提醒 ├── 检查用户是否已设置邮件提醒邮箱 │ ├── 已设置 → 跳过邮件配置 │ └── 未设置 → 询问用户邮箱 → 调用 amemo-send-task 发送邮件 └── 确保提醒必达 ↓ 7. 返回保存结果 ``` --- ### AI 工具定时任务参数 | 参数 | 类型 | 必填 | 说明 | |:-----|:----:|:----:|:-----| | `name` | str | ✅ | 任务名称（与 taskTitle 一致） | | `schedule.at` | str | ✅ | ISO 8601 格式时间 | | `payload.text` | str | ✅ | 提醒消息内容 | | `sessionTarget` | str | ✅ | `"main"` | > ⚠️ AI 工具定时任务由当前调用此 SKILL 的 AI 工具提供，使用其自身的定时任务接口创建，而非操作系统级别的 cron。 --- ### 邮件提醒检查流程 #### 检查方式 读取主 SKILL.md 顶部 `<amemo-user-config>` 块中的 `userEmail` 字段： - `userEmail` 不为空 → 已配置，直接使用 - `userEmail` 为空字符串 → 未配置，进入询问流程 > **存储规范**：用户首次确认邮箱后，使用文件编辑工具将邮箱写入主 SKILL.md 的 `<amemo-user-config>` 块 `userEmail` 字段，与 `userToken` 同处管理，无需依赖外部配置文件或环境变量。 --- #### 分支处理 **情况零：用户消息中已包含邮箱** ``` 用户消息中直接检测到邮箱地址（正则：\S+@\S+\.\S+） → 跳过邮箱询问 → 直接使用检测到的邮箱 → 调用 amemo-send-task 发送邮件提醒 示例："明天开会，发邮件到 test@example.com" → 直接使用 test@example.com ``` **情况一：已设置邮件** ``` 检测到用户已配置邮件：xxx@example.com → 跳过邮箱询问 → 当前 AI 工具定时任务将在提醒时间自动触发 ``` **情况二：未设置邮件** ``` 未检测到邮件配置（userEmail 为空） → 提示用户："📧 是否开启邮件提醒？请输入邮箱地址（或直接回复'跳过'）" → 等待用户输入 ├── 用户输入有效邮箱 │ → 写入主 SKILL.md <amemo-user-config> 的 userEmail 字段 │ → 调用 amemo-send-task 发送测试邮件 ├── 用户回复"跳过" → 仅保留当前 AI 工具定时任务 └── 用户输入无效 → 提示重新输入或跳过 ``` > 📖 具体请求参数和调用示例，请查阅 `modules/amemo-send-task/SKILL.md` --- ### 响应处理 #### 都成功时 ``` ✅ 已为您设置提醒：「{taskTitle}」 📅 时间：{taskTime} 📧 麦小记邮件提醒：已保存 ⏰ AI 工具定时提醒：已设置 双重保障，确保您不会错过！ ``` #### 麦小记成功，AI 工具失败时 ``` ✅ 已为您保存待办：「{taskTitle}」 📅 时间：{taskTime} 📧 麦小记邮件提醒：已启用 ⚠️ AI 工具定时提醒设置失败，但麦小记邮件提醒仍可用。 ``` #### 麦小记失败，AI 工具成功时 ``` ⚠️ 麦小记保存失败，已启用 AI 工具定时提醒 ⏰ 提醒时间：{taskTime} 📋 任务：{taskTitle} 当前 AI 工具将在指定时间提醒您。 ``` #### 都失败时 ``` ❌ 提醒设置失败 可能原因： • 麦小记服务异常 • 当前 AI 工具暂不支持定时任务 请检查服务状态后重试。 ``` --- ## 调用示例 ### 示例一：首次使用（未设置邮件） **用户输入：** ``` 明天早上提醒我早起买胡辣汤 ``` **系统处理：** 1. 检测到时间词语：`明天早上` 2. 转换时间：`2026-03-23 07:00:00`（早上默认7点） 3. 提取待办：`早起买胡辣汤` 4. 【第一优先级】调用 `POST /save-task` 保存到麦小记 5. 【第二优先级】调用当前 AI 工具的定时任务能力创建备份提醒 6. 检查邮件配置 → **未设置** 7. 询问用户： ``` ✅ 已为您设置提醒：「早起买胡辣汤」 📅 时间：2026-03-23 07:00:00 📧 麦小记邮件提醒：已保存 ⏰ AI 工具定时提醒：已设置 💡 是否开启邮件提醒？请输入邮箱地址（或回复"跳过"）： ``` **用户回复：** `lockfeel@example.com` **系统处理：** 8. 验证邮箱格式 9. 保存邮箱配置到本地 10. 调用 `POST /send-task` 发送测试邮件 11. 返回： ``` ✅ 邮件提醒已设置！ 📧 接收邮箱：lockfeel@example.com ⏰ 提醒时间：2026-03-23 07:00:00 测试邮件已发送，请查收。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 提醒配置总览 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📧 麦小记清单：已保存 ⏰ AI 工具定时任务：已设置 📧 邮件提醒：已启用 三重保障，确保您不会错过！ ``` --- ### 示例二：已设置邮件（自动跳过询问） **用户输入：** ``` 12月25日要送礼物 ``` **系统处理：** 1. 检测到时间词语：`12月25日` 2. 转换时间：`2024-12-25 00:00:00` 3. 提取待办：`送礼物` 4. 【第一优先级】调用 `POST /save-task` 保存到麦小记 5. 【第二优先级】调用当前 AI 工具的定时任务能力创建备份提醒 6. 检查邮件配置 → **已设置：lockfeel@example.com** 7. 自动调用 `POST /send-task` 发送邮件提醒 8. 返回： ``` ✅ 已为您设置提醒：「送礼物」 📅 时间：2024-12-25 00:00:00 📧 麦小记清单：已保存 ⏰ AI 工具定时任务：已设置 📧 邮件提醒：已启用（lockfeel@example.com） 三重保障，确保您不会错过！ ``` --- ### 示例三：用户选择跳过邮件 **用户输入：** ``` 后天要去医院复查 ``` **系统处理：** 1-5. （同上，保存到麦小记 + 当前 AI 工具创建定时任务） 6. 检查邮件配置 → **未设置** 7. 询问用户邮箱 8. **用户回复：** `跳过` 9. 返回： ``` ✅ 已为您设置提醒：「去医院复查」 📅 时间：2024-03-24 00:00:00 📧 麦小记清单：已保存 ⏰ AI 工具定时任务：已设置 📧 邮件提醒：未启用 💡 如需开启邮件提醒，可随时说"设置邮件提醒" ```