AI 互联接口文档

本章节面向 AI 助手（如 Codex、豆包、Kimi、WorkBuddy 等）。 当 AI 读到这些文档时，说明用户希望 AI 来帮他操作本地运行的 WordMomo 背单词软件。

用户只需要把页面的网址发送给AI，让AI阅读了解相关的接口之后，随后可以告诉AI一些指令

示例1 - 自动添加词汇
示例2 - 自动创建例句资料
示例3 - 视频教程演示

这是什么

WordMomo 是一款运行在用户电脑上的桌面背单词软件。它在本机回环地址上开启了一个 HTTP 服务，开放了一组接口（用法类似 MCP），允许 AI 帮助用户管理词库内容。

典型场景：用户刚刚和 AI 聊了一段外语内容（比如酒店入住英语对话），用户希望把这些内容沉淀到 WordMomo 里以便后续背诵复习。AI 按本章节文档调用接口即可完成。

重要前提与限制

1. 服务地址是 http://127.0.0.1，运行在用户的电脑上，不在公网上。只有当 AI 工具的执行环境能够访问用户本机网络时（例如在用户电脑上运行的命令行 AI），这套接口才可用。
2. 默认起始端口为 27531。如果该端口被占用，WordMomo 会自动尝试后续端口，最大到 27540。调用接口前请从 27531 开始依次探测，第一个可用的即为实际端口。
3. 该功能需要用户在 WordMomo 中手动开启「AI 互联」开关。如果所有端口都不可用，请提示用户去 WordMomo 的设置中开启该功能并保持软件运行。
4. 所有接口不需要鉴权，但服务只监听 127.0.0.1，仅本机可访问。
5. 所有接口的请求与响应均为 JSON（UTF-8），请求头携带 Content-Type: application/json。

统一调用方式

为避免接口地址过多，所有接口统一通过一个 POST 入口调用：

POST http://127.0.0.1:27531/ai/invoke

请求体固定为 JSON，通过 method 字段区分具体功能：

{
  "method": "book.list",
  "data": {
    "bookType": "all"
  }
}

字段	必填	说明
method	是	方法名，格式为 分类.动作，如 book.list、book.create，见下方接口索引
data	否	该方法的参数对象，无参数时可省略或传 {}

编码要求（重要）

请求体必须使用 UTF-8 编码发送，尤其是包含中文等非 ASCII 内容（如中文词库名、中文译文）时。编码错误会导致服务端收到的中文变成 ?? 乱码。

⚠️ Windows PowerShell 特别注意：PowerShell 自带的 curl 是 Invoke-WebRequest 的别名，直接传 JSON 字符串会按系统默认编码（GBK/ASCII）发送，中文必乱码。必须先把 JSON 转成 UTF-8 字节数组再发送：

$json = '{"method":"book.create","data":{"bookName":"哈哈","bookType":"wordlib"}}'
$body = [System.Text.Encoding]::UTF8.GetBytes($json)
Invoke-RestMethod -Uri "http://127.0.0.1:27531/ai/invoke" -Method Post -ContentType "application/json; charset=utf-8" -Body $body

macOS / Linux 下使用标准 curl 时，在 Content-Type 中声明 charset=utf-8 即可：

curl -X POST http://127.0.0.1:27531/ai/invoke \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"method":"book.list","data":{"bookType":"all"}}'

如果调用接口后发现中文内容在 WordMomo 中显示为 ??，说明是调用方发送编码不正确（数据在到达 WordMomo 之前就已损坏），请按上面的示例修正后重新调用。

统一响应格式

所有接口统一返回如下结构：

{
  "success": true,
  "data": {}
}

• success：true 表示成功，false 表示失败。
• data：成功时为业务数据；失败时为字符串形式的错误原因。

调用失败时，AI 应把错误原因如实转告用户，不要自行猜测重试太多次。

接口索引

词库接口

接口	说明	文档
book	词库接口，支持获取词库列表和创建词库	查看

单元接口

接口	说明	文档
unit	单元接口，支持获取单元列表和创建单元（需要 bookId）	查看

词汇接口

接口	说明	文档
word	词汇接口，支持一键导入（按名称自动找到或创建词库与单元并写入）和单步追加，内含 AI 必读的内容形态判断与决策流程	查看

扩展资料接口

接口	说明	文档
res	扩展资料接口，支持获取资料包列表和一键导入基础资料/例句资料（按名称自动找到或创建资料包）	查看