AI & 墨墨背单词

一句话：让 AI 通过墨墨开放 API 替你管理墨墨账号——批量建云词本、读学习数据、按计划推背诵。本文分两部分：上半部分是 AI 实战（2026-08-30/31 真实跑通的完整流程与踩坑），下半部分保留墨墨开放 API 的完整参考。

背景：备考 2026-10-24~27 网络规划设计师，上午综合知识卷约 5 分专业英语题，由此建设「软考网规英语术语」词本作为第一个实战项目。

一、实战成果：软考网规英语术语词本

项 值
云词本 「软考网规英语术语」（id np-3msq88fr5bWFar9QjcbQXK5ojtEfyX_1qk1uduwXUlfJBc1fSmZN48L200vZGJaJ）
规模 412 词 / 8 章节（2026-08-31 修复缩写撞词后），含 OSPF/BGP/MPLS/QoS 等缩写（可正常写入，非词典词走墨墨”自建单词”机制）
背诵计划 每日 10 新词 × 42 天（8-31 → 约 10-11 完成全部新词），考前剩余 ~12 天过错词/二轮
词表单一来源 AI_project\墨墨背单词\build_full_notepad.py（改词表→重跑脚本→自动同步云词本+文档）
配套文档 raw\Hermes-generate\软考资料\软考网规英语术语词本.md（含全词表与计划）

8 章节结构：01 网络体系结构与基础 / 02 局域网与交换 / 03 路由与广域网 / 04 无线与接入网 / 05 网络安全 / 06 网络管理与服务 / 07 规划设计与新技术 / 08 题干学术高频词。

二、AI 能对墨墨做什么（实测能力清单）

能力 状态 说明
云词本增删改查 ✅ 实测 章节模式（#章节名+每行一词）/文本模式批量导入；更新=原地升级，App 学习计划关联保留
学习数据读取 ✅ 实测 今日进度 / 今日学习队列 / 全量学习记录（每词含下次复习时间、学习次数）
学习写 ✅ 已实测（部分） add_words 实测成功（2026-08-31，Ethernet，added_count:1）；advance_study 需账号 10 级解锁提前复习，未实测
单词查询 ✅ 实测 spelling→voc_id，仅返回词和内部 ID，无释义音标
释义/助记/例句 ✅ 接口通 查询对象是 API 贡献内容（UGC），查不到墨墨官方词典
做不到的 ❌ 查询 App 内置词书/当前选书（官方 25 个端点全量核对过，没有）；官方词典释义；每日上限设置（只能 App 手动调）

三、实测踩坑记录（接入前必读）

  1. 学习数据接口是 POST-only + 蛇形路径：POST /memo/study/get_study_progress。用 GET、或 /study/progress 这类旧记法，全部 404——官方文档页面还标着”公测”，实际已经能用，只是文档路径过时。
  2. limit ≤ 10（云词本列表），超限报 common_invalid_param，翻页用 offset。报错信息会直接告诉你参数错在哪，很友好。
  3. 响应统一包一层 {"errors":[], "data":{...}, "success":true}。
  4. list 解析字段不回填：创建/详情响应里 list 均为空，无法经 API 预验证单词识别结果，只能 App 里看。
  5. 缩写可以直接写入（OSPF/QoS/VLAN 实测正常），不用转成完整单词。
  6. 官方 OpenAPI 规范文件可直接下载：https://open.maimemo.com/api_bundle.yaml（全部 25 个端点），比抓 Stoplight 前端页面省事得多。
  7. 频控：10 秒 20 次 / 60 秒 40 次 / 5 小时 2000 次（背单词模块），批量操作让脚本自动分批。
  8. /vocabulary 查词大小写敏感：spelling=ethernet（小写）返回空，Ethernet 才能查到——专有名词/缩写要用正确大小写。
  9. add_words 需在 App 中开启「自动同步」（官方规范注明，公测期间不保证可用性）。
  10. 缩写撞词与”自建单词”机制：词典没有的词（OSPF/BGP/QoS/multicast 等）墨墨会自动”自建单词”条目并配 AI 释义例句，App 内显示正常——API 里这类条目的 voc_spelling 可能为空，属显示层怪癖而非缺陷（multicast 实证）。但与既有词典词大小写不敏感撞车的缩写会映射到错误词条：PoE→人名 Poe，同理 AS→as、ATM→取款机、RIP→rip（撕）、POP→pop、AC→交流电等。对策：撞词缩写一律改英文全称（autonomous system / asynchronous transfer mode / routing information protocol…），已在 412 词版修复。

四、工具链与文件布局

C:\Users\Admin\Desktop\AI_project\墨墨背单词\     ← 墨墨相关操作文件唯一目录
├── config\token.txt          # Bearer Token（账号级凭据，勿提交 git / 勿写进公开文档）
├── fetch_study_data.py       # 一键拉取：今日进度 / 今日队列 / 全量学习记录
├── build_full_notepad.py     # 软考词本构建脚本（词表单一来源）
└── data\                     # 各接口原始响应样本

知识库侧配套：raw\Hermes-generate\软考资料\软考网规英语术语词本.md。

五、下一步（待办）

  • add_words 实测（2026-08-31）：Ethernet 加入学习队列成功，added_count:1——“AI 提生词→直接进队列”全自动链路打通
  • 生词工作流：AI 读英文技术文章提生词 → 进墨墨（安排在考试后）
  • 定时周报：每周日自动拉学习数据生成进度报告（2026-08-31 用户决定暂缓）
  • App 内调大每日上限（2026-08-31 已生效：今日队列 26 词，软考术语与通用词混排）

六、墨墨开放 API 参考

以下为 2026-08-18 调研整理的 API 原始参考；部分细节经 08-30/31 实测修正，冲突处以本文「三、实测踩坑记录」为准。

鉴权与频控

获取 Token

两种方式：

  1. 墨墨 App 内获取：我的 → 更多设置 → 实验功能 → 开放 API，复制个人 Token
  2. 在线获取：在 API 文档页面点击获取

将 Token 放在请求头中：

Authorization: Bearer ***

频控限制

时间窗口 最大请求数
10 秒 20 次
60 秒 40 次
5 小时（墨墨背单词） 2000 次
5 小时（墨墨记忆卡） 8000 次

内容创建频控：每天最多创建 600 条内容（例句、助记、释义合计）。

API 端点总览

API 分两大模块：

1. 内容 (Content)

词汇内容查询接口，查释义、助记、例句。（实测修正：查询对象为 API 贡献内容 UGC，非官方词典）

方法 端点 说明
GET /memo/interpretations 查询单词释义
GET /memo/notes 查询助记（记忆技巧）
GET /memo/phrases 查询例句

curl 示例：

curl --request GET \
  --url https://open.maimemo.com/open/api/v1/phrases \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ***'

相关 Schema：Interpretation、InterpretationStatus、Note、NoteStatus、Phrase、PhraseStatus、PhraseHighlightRange

2. 墨墨背单词 (Vocabulary)

核心词汇管理接口，分四组：

云词本 (Notepad) — 最核心功能
方法 端点 说明
GET /memo/notepads 查询云词本列表（支持分页，limit≤10）
POST /memo/notepads 创建云词本（批量导入词汇）
GET /memo/notepads/{id} 获取单个云词本详情
POST /memo/notepads/{id} 更新云词本
DELETE /memo/notepads/{id} 删除云词本

查询云词本参数：

  • ids — 按 ID 列表筛选（array[string]）
  • limit — 查询数量（integer，实测 ≤10）
  • offset — 跳过数量（integer）

创建云词本请求体 (POST /memo/notepads)：

{
  "notepad": {
    "status": "PUBLISHED",
    "content": "apple",
    "title": "常用词汇",
    "brief": "常用",
    "tags": ["考研"]
  }
}

content 字段说明：

  • 章节模式：以 # 开头，井号后是章节名称，下方是该章节的单词列表（一行一个）
  • 文本模式：不以 # 开头，不限格式，会识别尽量多的单词和短语。开头添加 // 则还原单词原型后再提取

Notepad 字段：

字段 类型 说明
id string 唯一标识（实测前缀 np-）
type string FAVORITE（收藏词本）或 NOTEPAD（用户创建词本）
creator integer 创建者用户 ID
status string PUBLISHED / UNPUBLISHED / DELETED
content string 词本内容（原始文本）
title string 词本标题
brief string 简介
tags array[string] 标签
list array[object] 解析结果（实测：API 响应中不回填，恒为空）
created_time string ISO 8601 创建时间
updated_time string ISO 8601 更新时间
学习数据（实测可用）
方法 端点 说明
POST /memo/study/get_study_progress 获取学习进度（finished/total/study_time）
POST /memo/study/get_today_items 获取今日学习队列（每词：voc_spelling/is_new/first_response/is_finished）
POST /memo/study/query_study_records 获取学习记录（每词：add_date/last_study_date/next_study_date/study_count）
POST /memo/study/add_words 学习写：把词加进学习队列（已实测：请求 {"words":[{"id":"voc_id"}],"advance":false}，响应 added_count，单次最多 1000 词）
POST /memo/study/advance_study 学习写：提前复习（需账号升级到 10 级解锁提前复习功能，未实测）

实测修正：全部 POST-only，路径为蛇形命名。旧记法 /study/progress、/study/today、/study/records 已作废（404）。

单词查询
方法 端点 说明
GET /memo/vocabulary 查询单词信息（参数 spelling；实测仅返回词+内部 ID voc-...）
POST /memo/vocabulary/query 批量查词（2026-08-31 从规范文件发现，未实测）

相关 Schema：Vocabulary

数据结构 (Schemas)

API 定义的完整数据模型：

Schema 说明
InterpretationStatus 释义状态
Interpretation 释义内容
NoteStatus 助记状态
Note 助记内容
NotepadStatus 云词本状态（PUBLISHED/UNPUBLISHED/DELETED）
NotepadType 云词本类型（FAVORITE/NOTEPAD）
NotepadParsedItem 云词本解析条目
Notepad 云词本完整对象
BriefNotepad 云词本概要（列表用）
PhraseStatus 例句状态
PhraseHighlightRange 例句高亮区间
Phrase 例句内容
StudyResponse 学习数据响应
StudyProgress 学习进度
StudyTodayItem 今日学习条目
StudyRecord 学习记录
Vocabulary 单词信息

使用场景

场景 1：AI 工具自动建词本（核心场景，已跑通）

通过 AI 阅读外文文章/考纲，筛选生词或术语后自动调用 API 创建云词本同步到墨墨 App：

  1. AI 整理术语表（本例：软考网规英语术语 415 词，8 章节）
  2. 调用 POST /memo/notepads 创建词本（章节模式 content）
  3. 墨墨 App 自动同步，用户加入学习计划即可开始背诵

场景 2：爬虫/工具批量导入词汇

适合阅读软件、翻译工具对接：

  1. 从阅读材料中提取生词
  2. 格式化为章节模式 content（#章节名 \n 单词1 \n 单词2）
  3. 调用 API 创建词本

场景 3：跨端学习数据同步（已跑通）

调用学习数据接口获取背诵进度和待复习词汇（next_study_date），生成个性化学习清单/复习日历/周报。

学习资源