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>
```json
{
  "userToken": "",
  "userName": "SYSTEM",
  "userPhone": "",
  "loginAt": "",
  "userEmail": ""
}
```
</amemo-user-config>

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

配置字段

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

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

用户登录成功
    ↓
提取返回的 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 状态码等）：

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

常见异常及回复模板：

错误处理示例流程：

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

会话中途打断处理

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

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

无 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 时，直接执行登录引导，不再显示其他错误提示

调度流程

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

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

意图优先级规则

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

语义判断示例：

• "今天下午开需求会" → 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