amemo-skill — 统一调度中心

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

基础配置

• - Base URL: INLINECODE0
• 请求方式: 全部 POST，Content-Type: INLINECODE2
• 响应格式: INLINECODE3

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

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

用户配置管理

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

当前登录用户信息：

{
  "userToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI0NTk3MzE2MjcyODc3NzMxODQiLCJleHAiOjE3NzgzNTMwOTUsImlhdCI6MTc3NTc2MTA5NX0.SKRO1VWVexBt7N0lEgZNI5iecQgXWQagKt2G29uj9Ms",
  "userName": "张谨言",
  "userPhone": "15225562808",
  "loginAt": "2026-04-10 02:58:38",
  "userEmail": ""
}

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

配置字段

字段	说明
INLINECODE4	用户认证令牌，所有 API 请求必需
INLINECODE5

用户昵称，用于个性化提醒 | | userPhone | 用户手机号，标识用户身份 | | loginAt | 登录时间，判断登录是否过期 | | userEmail | 任务邮件提醒邮箱，用户首次设置后写入并持久化 |

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

用户登录成功后自动调用，更新 SKILL.md 中的用户配置：
BEGIN UpdateUserConfig(token, name, phone)
READ SKILL.md 文件内容
LOCATE 标签内的 JSON 配置区域
PRESERVE existing userEmail (首次设置后持久化，后续不覆盖)
REPLACE JSON 为:
{
"userToken": "{token}",
"userName": "{name}",
"userPhone": "{phone}",
"loginAt": "{当前时间}",
"userEmail": "{保留原值}"
}
WRITE SKILL.md 文件
SEND 个性化欢迎消息
END

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

使用示例

BEGIN CheckLoginStatus()
IF userToken IS empty THEN
CALL LoginGuide()
ELSE
SEND "欢迎回来，{userName}！"
END IF
END

安装后引导流程

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

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

👋 欢迎使用 amemo-skill！

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

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

SET context = "等待输入手机号"

Step 2: 手机号提取与验证码发送 → 详见 modules/amemo-send-code/SKILL.md
Step 3: 验证码提取与登录 → 详见 modules/amemo-login/SKILL.md
Step 4: 登录成功处理（自动更新配置）→ 详见 modules/amemo-login/SKILL.md

自动登录激活流程

用户发送"麦小记登录"或"麦小记注册"时触发：
BEGIN AutoLoginTrigger()
READ
IF userToken IS empty THEN
CALL FirstTimeGuide() / 执行 Step 1-4 首次安装引导, Step 1 会设置 context = "等待输入手机号" */
ELSE
SEND "您已登录，无需重复登录。欢迎回来，{userName}！"
END IF
END

错误处理

全局错误码映射

所有 API 返回 {"code": N, "desc": "...", "data": ...}，按优先级处理：
BEGIN HandleError(code, desc, isNetworkError)
/ 优先级: code=2007 > 网络错误 > 其他错误 */
IF code == 2007 THEN
CLEAR userToken
CALL LoginGuide()
SEND "⚠️ 登录状态已失效，请重新登录"
ABORT current flow
ELSE IF isNetworkError THEN
RETRY once
IF still fail THEN SEND "网络有点慢，请稍后重试"
ELSE IF code != 200 THEN
SEND desc OR "出了点小问题，请稍后重试"
END IF
END

业务级错误（各模块特有）

模块	错误场景	用户提示
amemo-send-code	手机号格式错误	INLINECODE10
amemo-login

验证码错误/过期 | ❌ 验证码错误或已过期，请重新发送验证码 | | amemo-send-task | 邮箱格式错误 | ❌ 邮箱格式不正确，请重新输入 | | amemo-save-mate | MEMORY.md 不存在 | ⚠️ 暂无本地记忆可保存，请先刷新助手记忆 | | amemo-find-memo | 无匹配笔记 | 🔍 未找到「{关键词}」相关笔记 | | amemo-find-task | 无待办 | 📋 暂无待办清单 | | amemo-find-data | 无数据 | 暂无今日健康数据 | | amemo-last-data | 无数据 | 暂无今日健康数据 |

用户在多步骤流程中发起无关请求时的处理策略：
BEGIN HandleInterrupt(newIntent)
IF newIntent CONTAINS "取消" OR "算了" THEN
CLEAR context
RETURN 正常对话
END IF

/ 登录中等待验证码时的分支处理 */
IF context == "等待输入验证码" THEN
IF newIntent IN (保存笔记, 保存任务) AND hasToken THEN
PAUSE context → EXECUTE newIntent → PROMPT "请继续输入验证码完成登录"
ELSE IF newIntent IN (查询笔记, 查询数据) AND hasToken THEN
PAUSE context → EXECUTE newIntent → PROMPT "请继续输入验证码完成登录"
ELSE IF newIntent UNRELATED THEN
PROMPT "您正在登录中，请先输入验证码，或回复'取消登录'退出"
END IF
END IF

/ 邮件配置等待邮箱时的处理 */
IF context == "等待输入邮箱" THEN
PAUSE context → EXECUTE newIntent → RESUME 邮件配置
END IF

/ 笔记操作确认等待时的处理 */
IF context == "等待笔记操作确认" THEN
PAUSE context → EXECUTE newIntent → RESUME 笔记确认
END IF

/ 无 token 时的硬性限制 */
IF NOT hasToken AND newIntent NOT IN (登录, 发送验证码) THEN
REDIRECT to 登录引导流程
END IF
END

对话状态机生命周期 — 以下状态在当前对话期间有效：
BEGIN ManageSessionState()
/ 登录流程上下文状态 */
ON "麦小记登录/注册" 触发:
SET context = "等待输入手机号"
ON amemo-send-code success:
SET context = "等待输入验证码"
ON amemo-login success:
CLEAR context
ON "取消登录":
CLEAR context

/ 笔记上下文状态 */
ON amemo-save-memo success:
SET lastMemoId, lastMemoTitle
CLEAR when: 话题切换 OR 10轮未使用 OR 用户说"新笔记"
ON save-memo 进入新建/更新确认:
SET context = "等待笔记操作确认"
ON 用户确认笔记操作 (新建/更新) 完成:
CLEAR context

/ 任务上下文状态 */
ON amemo-save-task success:
SET lastTaskId
CLEAR when: 话题切换 OR 10轮未使用

/ 邮件配置上下文状态 */
ON save-task 进入邮箱询问流程:
SET context = "等待输入邮箱"
ON userEmail 写入 成功:
CLEAR context
ON 用户回复"跳过" (邮件配置):
CLEAR context

/ 话题切换时清除所有临时 context */
ON 检测到话题切换:
IF context IS NOT empty THEN CLEAR context
END

意图路由

按优先级顺序判断，命中即执行，不再继续判断：
BEGIN RouteIntent(userInput)
/ P0: 登录/验证码（最高优先级）*/
/ 上下文约束: 仅在以下场景触发:
* - 用户刚发送过「麦小记登录/注册」
* - 当前处于首次安装引导流程中
* - 用户明确表示要登录/注册
避免误判: 用户说「100块钱」「2026年3月」等含数字的日常对话不应触发 /
IF CONTAINS "麦小记登录" OR "麦小记注册" OR "我要登录麦小记" OR "登录麦小记" THEN
CALL AutoLoginTrigger()
END IF
IF match 1[3-9]\d{9} AND context == "等待输入手机号" THEN
DISPATCH amemo-send-code
END IF
IF match \d{4,6} AND context == "等待输入验证码" THEN
DISPATCH amemo-login
END IF

/ P1: 保存笔记 */
/ 歧义消解: 时间词+动词→任务(P2); 时间词+场景词→笔记(P1) */
IF has 触发词(保存笔记, 记下这一条, 记录笔记, 帮我记一下, 保存备忘)
OR has 场景词(的情景, 的情况, 的时候, 的经历) THEN
DISPATCH amemo-save-memo
END IF

/ P2: 保存任务 */
IF has 时间词 AND (has 提醒词(提醒我, 记得, 要, 需要) OR has 动词(开会, 吃饭, 去, 买, 交, 看, 做)) THEN
DISPATCH amemo-save-task
END IF

/ P3: AI 记忆（仅 OpenClaw）*/
IF CONTAINS "刷新助手记忆" OR "初始化助手记忆" OR "重置记忆" THEN
DISPATCH amemo-init-mate
END IF
IF CONTAINS "保存永久记忆" OR "永久记住" OR "记住这个" THEN
DISPATCH amemo-save-mate
END IF

/ P4: 查询类操作（查询意图优先于保存）*/
/ 意图分类前置: 先判查询意图再匹配关键词，避免漏判/误判
* 查询信号: 查看/查找/搜索/查询/有没有/帮我看看/最近/今天/多少
排除保存信号: 帮我记/保存/提醒我/记下 (这些是保存意图，不应命中P4) /
IF has 查询词(查看, 查找, 搜索, 查询, 有没有, 帮我看看, 最近) AND CONTAINS 笔记/备忘 THEN
DISPATCH amemo-find-memo
END IF
IF has 查询词(查看, 查找, 搜索, 查询, 有没有, 帮我看看) AND CONTAINS 清单/待办/任务 THEN
DISPATCH amemo-find-task
END IF
IF CONTAINS 步数/睡眠/血氧/血压/心率/消耗/数据 AND NOT has 保存词(保存, 记下, 记录) THEN
DISPATCH amemo-find-data
END IF
IF CONTAINS 健康简报/健康日报/健康总览/健康怎么样 THEN
DISPATCH amemo-last-data
END IF

/ Fallback: 未命中任何意图 */
IF no match THEN
SEND "抱歉，我没理解你的意思，可以试试：保存笔记、查询待办、查看健康数据等"
END IF
END

子模块调度索引

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

模块	路由	触发词	详细文档
amemo-login	POST /login	4-6位数字验证码	INLINECODE18
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 |

请求 Schema 速查

服务端要求：所有字段必须存在于请求体中。可选字段不传值时传 null，不可省略字段。

模块	必填字段（非空）	可选字段（可 null）
amemo-send-code	INLINECODE30	INLINECODE31 (传 null)
amemo-login

phone, code | — | | amemo-save-memo | userToken, memoTitle, memoContent | memoId (新建传 null) | | amemo-find-memo | userToken, memoTitle | memoId, memoContent | | amemo-save-task | userToken, taskTitle, taskTime | taskId, taskExplain, taskEmail | | amemo-find-task | userToken | taskId, taskTitle, taskTime, taskEmail | | amemo-send-task | userToken, taskTime, taskEmail | taskId, taskTitle, taskExplain | | amemo-find-data | userToken, dataType | — | | amemo-last-data | userToken | dataType (传 null) | | amemo-init-mate | userToken | mateMemory (传 null) | | amemo-save-mate | userToken, mateMemory | — |

AI 工具适配层

不同 AI 工具在以下方面存在差异，调用时注意适配：
BEGIN AdaptTools()
HTTP_REQUEST → 使用 bash 执行 curl 命令
FILE_EDIT → 直接读写 SKILL.md 中的 区域
SCHEDULED_TASK → Claude Code: Scheduled tool; 其他: 内置定时能力或跳过
SCRIPTEXEC → python3 scripts/parsetime.py（需 Python 3.10+）

/ 如果不支持定时任务，仅保存任务到麦小记，邮件提醒仍可用 */
END

认证流程

除 /login 和 /send-code 外，所有请求需携带 userToken：
BEGIN AuthCheck()
IF NOT hasToken THEN
CALL LoginFlow()
RETURN acquired token
END IF
RETURN existing token
END

使用方式

读取子模块目录下的 SKILL.md 获取完整的请求参数和 curl 示例，然后执行 HTTP 请求。
子模块路径格式：modules/<模块名>/SKILL.md
BEGIN ExecuteModule(moduleName)
READ modules/{moduleName}/SKILL.md
PARSE 请求参数和 curl 示例
BUILD curl POST request to https://skill.amemo.cn/{route}
EXECUTE curl POST request to https://skill.amemo.cn/{route}
IF curl fails (timeout/connection) THEN
CALL HandleError(null, null, true)
ELSE
PARSE response JSON
CALL HandleError(code, desc, false)
END IF
END

示例: 用户要"保存一条笔记

1. 1. READ modules/amemo-save-memo/SKILL.md
2. 按参数格式构造请求
3. curl POST https://skill.amemo.cn/save-memo