Amemo Skill

amemo-skill — 统一调度中心

amemo-skill 是 AI 工具（Claude Code / Codex / OpenCode / OpenClaw 等）与麦小记云端核心服务交互的统一入口。提供笔记管理、清单管理、健康数据查询、AI 助手记忆同步等功能。

基础配置

• Base URL: https://skill.amemo.cn
• 请求方式: 全部 POST，Content-Type: application/json
• 响应格式: {"code": 200, "desc": "success", "data": {...}|[...]}

> 注意：具体 API 请求示例和响应数据结构，请查阅对应子模块的 SKILL.md

> ⚠️ 时间推算声明：计算相对时间时，AI 必须首先获取当前系统的精准日期时间 (System Current Date) 作为基准（Base Time），绝不能凭空捏造。

用户配置管理

> 重要：此区域的 JSON 配置由系统自动维护，登录成功后会自动更新。

当前登录用户信息：

<amemo-user-config>

{
  "userToken": "",
  "userName": "SYSTEM",
  "userPhone": "",
  "loginAt": "",
  "userEmail": ""
}

</amemo-user-config>

> 如果显示为示例数据（如 userName: "SYSTEM"），表示尚未登录或登录信息已过期，立即激活登录流程。

配置字段

| 字段 | 说明 |

|------|------|

| userToken | 用户认证令牌，所有 API 请求必需 |

| userName | 用户昵称，用于个性化提醒 |

| userPhone | 用户手机号，标识用户身份 |

| loginAt | 登录时间，判断登录是否过期 |

| userEmail | 任务邮件提醒邮箱，用户首次设置后写入并持久化 |

更新配置流程（自动执行）

用户登录成功后，系统自动执行以下步骤：

用户登录成功
    ↓
提取返回的 userToken, userName, userPhone
    ↓
读取 SKILL.md 文件内容
    ↓
精准定位到顶部 <amemo-user-config> 标签内的 JSON 配置区域
    ↓
替换为新的登录信息：
    {
        "userToken": "{返回的userToken}",
        "userName": "{返回的userName}",
        "userPhone": "{返回的userPhone}",
        "loginAt": "{当前时间}"
    }
    ↓
写回 SKILL.md 文件
    ↓
发送个性化欢迎消息

注意：此步骤完全自动化，无需用户手动操作。登录成功后配置立即生效。

使用示例

检查登录状态：

if userToken 为空:
    执行登录引导流程
else:
    使用 userName 打招呼："欢迎回来，{userName}！"

API 请求时：

> 读取对应子模块的 SKILL.md 获取完整的请求参数和 curl 示例

安装后引导流程

当用户首次安装或检测到未登录（无 userToken）时，自动执行以下引导：

Step 1: 欢迎消息（自动发送）

👋 欢迎使用 amemo-skill！

我是你的智能笔记助手，可以帮你：
• 📝 保存和查询笔记
• ✅ 管理待办清单
• 📊 查看健康数据
• 🤖 同步 AI 记忆

请先完成登录，发送你的手机号：
示例：13800138000

Step 2: 手机号提取与验证码发送

> 详细流程请查阅 modules/amemo-send-code/SKILL.md

Step 3: 验证码提取与登录

> 详细流程请查阅 modules/amemo-login/SKILL.md

Step 4: 登录成功处理（自动更新配置）

> 详细流程请查阅 modules/amemo-login/SKILL.md

自动登录激活流程

当用户发送"麦小记登录"或"麦小记注册"时，触发此流程：

用户发送"麦小记登录"或"麦小记注册"
    ↓
读取 SKILL.md 中的 <amemo-user-config>
    ↓
检查 userToken 是否为空
    ↓
┌─────────────────────────────────────┐
│ userToken 为空（未登录）              │
│     ↓                               │
│ 触发首次安装引导流程（见上方 Step 1-4）│
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ userToken 不为空（已登录）            │
│     ↓                               │
│ 发送："您已登录，无需重复登录"        │
│ 附带欢迎消息："欢迎回来，{userName}！" │
└─────────────────────────────────────┘

接口异常处理：

当调用 API 出现异常时（网络错误、服务未启动、返回非 200 状态码等）：

• 读取错误信息 - 捕获异常详情
• 转换为用户语言 - 将技术错误转为通俗解释
• 提供解决方案 - 告诉用户下一步怎么做

常见异常及回复模板：

| 异常类型 | 技术错误 | 用户提示 |

|---------|---------|---------|

| 网络超时 | Timeout | 网络有点慢，请稍后重试 |

| 未知错误 | 其他异常 | 出了点小问题，请稍后重试或联系管理员 |

错误处理示例流程：

调用接口 → 捕获异常 → 解析错误类型 → 匹配用户提示 → 发送友好提醒

会话中途打断处理

当用户正在某个多步骤流程中（如登录、邮件配置），突然发起与当前流程无关的请求时：

处理原则：当前流程让步于用户新意图，但保留当前流程状态以便后续恢复。

| 当前流程 | 用户新意图 | 处理方式 |

|---------|-----------|---------|

| 登录中（等待验证码） | 保存笔记/任务 | 暂停登录，先执行新意图（需已有 token），完成后提示继续登录 |

| 登录中（等待验证码） | 查询笔记/数据 | 暂停登录，先执行查询（需已有 token），完成后提示继续登录 |

| 登录中（等待验证码） | 登录无关请求 | 提示："您正在登录中，请先输入验证码，或回复'取消登录'退出" |

| 邮件配置中（等待邮箱） | 其他操作 | 暂停邮件配置，执行新操作，完成后继续邮件配置 |

| 任何流程中 | 用户说"取消"/"算了" | 立即终止当前流程，恢复正常对话 |

无 token 时的硬性限制：

• 如果用户未登录（无 userToken），除登录/验证码外的所有操作都必须先引导登录
• 不可在未登录状态下执行查询或保存操作

全局 Token 过期处理（code=2007）

当调用任意 API 接口时，如果返回 code=2007，表示用户登录失败或 Token 已过期，必须立即中断当前操作并重新执行引导登录流程。

处理流程：

任意 API 返回 code=2007
    ↓
清除本地存储的 userToken（设为空）
    ↓
发送提示："登录状态已失效，请重新登录"
    ↓
触发首次安装引导流程（见上方 Step 1-4）

回复模板：

⚠️ 登录状态已失效，请重新登录

请发送您的手机号：
示例：13800138000

全局生效范围：

• 所有需要 userToken 的接口（除 /login 和 /send-code 外）
• 包括：保存笔记、查询笔记、保存任务、查询任务、查询数据、健康简报、发送任务提醒、AI 记忆同步等
• 无论当前处于哪个操作流程中，一旦收到 code=2007，立即切换到登录引导流程

与现有错误处理的关系：

• code=2007 的优先级高于普通异常处理
• 收到 code=2007 时，直接执行登录引导，不再显示其他错误提示

调度流程

当用户提出请求时，按以下步骤操作：

• 确认服务状态 — 确保 amemo 服务可用（Base URL: https://skill.amemo.cn）
• 识别用户意图 — 根据用户需求判断应调用哪个子模块
• 检查认证状态 — 除登录/验证码外，所有接口需要 userToken。若未获取 token，先调用 amemo-login
• 调度子模块 — 读取对应模块的 SKILL.md 执行具体请求

意图优先级规则

当用户单条消息同时触发多个模块时，按以下优先级执行（仅执行最高优先级的那一个）：

| 优先级 | 意图类型 | 判断依据 | 处理方式 |

|--------|---------|---------|---------|

| P0 | 登录/验证码 | 包含手机号、验证码或明确的登录意图 | 仅执行登录流程 |

| P1 | 保存笔记 | 包含笔记保存触发词，或陈述性描述 | 仅执行笔记保存 |

| P2 | 保存任务 | 有提醒/祈使语义（提醒我、记得、时间+动词） | 保存任务 + 设置提醒 |

| P3 | 查询类操作 | 包含"查看/查找/搜索/查询/我的" + 笔记/任务/数据 | 执行对应查询 |

| P4 | 健康简报 | 明确说"健康简报/健康日报/健康总览" | 仅执行健康简报 |

语义判断示例：

• "今天下午开需求会" → P2（祈使句，动词性内容）
• "今天下午开需求会的时候" → P1（陈述性描述，"的时候"表示场景）
• "提醒我明天交报告" → P2（有提醒意图）
• "记得明天要去医院" → P2（有提醒意图）
• "保存笔记，今天下午开需求会的情况" → P1（陈述性描述）
• "查看我的步数数据" → P3，查询数据
• "查询明天的待办" → P3（查询意图优先，不创建任务）

模块调度决策树（按顺序判断）

1. 检查登录意图（最高优先级）

→ 用户发送 11 位手机号（如 13800138000）→ 调用 amemo-send-code

→ 用户发送 4-6 位验证码（如 1234）→ 调用 amemo-login

→ 用户发送"麦小记登录"或"麦小记注册"→ 检查 userToken：

• 未登录（userToken 为空）→ 触发首次安装引导流程（见下方自动登录激活流程）
• 已登录 → 发送"您已登录，无需重复登录"

2. 检查保存意图 → 保存笔记

→ 保存笔记/记下/记录笔记/帮我记一下/保存备忘 → amemo-save-memo

→ 陈述性描述（包含"的情景"、"的情况"、"的时候"、"的经历"）→ amemo-save-memo

3. 检查任务意图（有提醒/祈使语义）→ 保存任务

→ 时间词 + "提醒我"、"记得"、"要"、"需要" → amemo-save-task

→ 时间词 + 动词性内容（开会、吃饭、去、买、交、看、做）→ amemo-save-task

→ 祈使句："明天XXX"、"今天下午XXX" → amemo-save-task

4. 检查记忆意图 → AI 记忆模块（仅 OpenClaw）

→ 刷新记忆/初始化记忆/重置记忆 → amemo-init-mate

→ 保存永久记忆/永久记住 → amemo-save-mate

5. 检查查询意图 → 查询类操作

→ 包含"笔记/备忘" → amemo-find-memo

→ 包含"清单/待办/任务" → amemo-find-task

→ 包含"步数/睡眠/血氧/血压/心率/消耗" → amemo-find-data

→ 健康简报/健康日报 → amemo-last-data

时间词触发的语义判断规则

判断为保存任务（amemo-save-task）：祈使句/提醒语义

• "提醒我明天XXX" → 有明确提醒意图
• "记得后天要XXX" → 有提醒意图
• "明天XXX吧" / "明天XXX" → 祈使句/请求
• "今天下午开需求会" → 动词性内容（开会是动作）
• "明天交报告" → 动词性内容
• "今天要买菜" → 动词性内容

判断为保存笔记（amemo-save-memo）：陈述性/描述性语义

• "今天下午开需求会的时候" → "的时候"表示描述场景
• "上次开会的情景" → 名词性描述
• "我感冒的时候的情况" → 表示描述某种情况
• "还记得当时的情景吗" → 陈述回忆
• 包含"的情景"、"的情况"、"的时候"、"的经历" → 陈述性内容

各模块触发词与提取规则

amemo-send-code

触发词：手机号（正则 1[3-9]\d{9}）

提取：直接提取手机号

amemo-login

触发词：验证码（正则 \d{4,6}）

提取：直接提取验证码

amemo-save-memo 保存笔记

触发词：保存笔记、记下这一条、记录笔记、帮我记一下、保存备忘

语义触发：陈述性描述（包含"的情景"、"的情况"、"的时候"、"的经历"）

提取：去除触发词后的对话内容作为笔记内容

amemo-find-memo 查询笔记

触发词：查看笔记、查找笔记、搜索笔记、找一下XXX笔记

格式：查看我XXX相关的笔记、查找XXX相关的笔记

提取：XXX 作为搜索关键词

amemo-find-task 查询任务

触发词：查看清单、查询清单、查看待办、查询待办、查看任务

格式：我的清单、我的待办、我的任务

提取：无须提取参数，查询全部

amemo-save-task 保存任务

语义触发：

• 有提醒意图："提醒我明天XXX"、"记得后天要XXX"
• 祈使句："明天XXX"、"今天下午开需求会"
• 时间词 + 动词性内容（开会、吃饭、去、买、交、看、做）

触发词：

• 今天XXX、明天XXX、后天XXX、昨天XXX
• 12月XX日XXX、X月XX日XXX（具体日期）
• 将来的XXX、未来的XXX、最近XXX、近期XXX

提取：时间和任务内容

amemo-find-data 查询健康数据

触发词：查看我的步数、查看我的睡眠、血氧数据怎么样

数据类型：步数、睡眠、血氧、血压、心率、消耗

提取：XXX 作为 dataType 参数

amemo-last-data 健康简报

触发词：今日健康简报、健康日报、健康总览

提取：无须提取参数

amemo-init-mate 刷新记忆（仅 OpenClaw）

触发词：刷新助手记忆、初始化助手记忆、重置记忆

提取：无须提取参数

amemo-save-mate 保存记忆（仅 OpenClaw）

触发词：保存永久记忆、永久记住XXX、记住这个

提取：XXX 作为要记住的内容

子模块调度索引

各模块详细执行流程、请求参数、数据格式、响应解析、输出模板等，请查阅对应子模块 SKILL.md：

| 模块 | 路由 | 触发词 | 详细文档 |

|------|------|--------|---------|

| amemo-login | POST /login | 登录 | modules/amemo-login/SKILL.md |

| amemo-send-code | POST /send-code | 发送验证码 | modules/amemo-send-code/SKILL.md |

| amemo-save-memo | POST /save-memo | 保存笔记 | modules/amemo-save-memo/SKILL.md |

| amemo-find-memo | POST /find-memo | 查询笔记 | modules/amemo-find-memo/SKILL.md |

| amemo-save-task | POST /save-task | 保存任务 | modules/amemo-save-task/SKILL.md |

| amemo-find-task | POST /find-task | 查询任务 | modules/amemo-find-task/SKILL.md |

| amemo-send-task | POST /send-task | 邮件提醒 | modules/amemo-send-task/SKILL.md |

| amemo-find-data | POST /find-data | 查询数据 | modules/amemo-find-data/SKILL.md |

| amemo-last-data | POST /last-data | 健康简报 | modules/amemo-last-data/SKILL.md |

| amemo-init-mate | POST /init-mate | 刷新记忆 | modules/amemo-init-mate/SKILL.md |

| amemo-save-mate | POST /save-mate | 保存记忆 | modules/amemo-save-mate/SKILL.md |

认证流程

除 /login 和 /send-code 外，所有请求需携带 userToken：

用户请求 → 检查是否有 token → 无 → 调用 amemo-login → 获取 token → 有 → 调用目标子模块

使用方式

读取子模块目录下的 SKILL.md 获取完整的请求参数和 curl 示例，然后执行 HTTP 请求。

子模块路径格式：modules/<模块名>/SKILL.md

例如用户要"保存一条笔记"：

• 读取 modules/amemo-save-memo/SKILL.md
• 按参数格式构造请求
• 用 curl 发送 POST 请求到 https://skill.amemo.cn/save-memo