词汇接口

这是 AI 互联最核心的接口。当用户说「把以上内容整理一下添加到 WordMomo」时，严禁直接执行写入。你必须先完成调查（只读接口），然后出具一份预执行方案给用户确认，用户回复同意（如「执行」「可以」）后，才能调用任何创建/添加接口。

决策流程总览

判断内容形态(单词/词组 还是 句子)
        ↓
调查现状：book.list / unit.list（只读，不写入）
        ↓
出具《预执行方案》发给用户，等待确认  ←—— 关键步骤，不可跳过
        ↓
用户确认（或按用户意见调整方案后再次确认）
        ↓
按方案执行：word.import 一键导入（自动找到或创建词库与单元并写入）
        ↓
向用户汇报执行结果

第一步：判断内容形态

WordMomo 中单词库和句子库是两种不同的学习模式，添加前必须先判断内容形态，放错库会严重影响用户的学习体验。

内容形态	特征	目标库类型
单词 / 词组	没有完整句子结构的词或短语，如 `apple`、`check in`、`look forward to`	`wordlib` 单词库
句子	有完整主谓结构、通常带句末标点的句子，如 `I have a reservation under the name Gao.`	`sentencelib` 句子库

判断规则：

一个条目以动词原形开头且整体是一个短语（如 check out）→ 词组，放单词库。
一个条目包含主语和谓语、表达完整语义（如 Could I have a wake-up call at 7?）→ 句子，放句子库。
聊天内容同时包含单词和句子时，必须拆分成两批：单词/词组一批放入单词库，句子一批放入句子库，不要混放。此时方案中应包含两个目标位置。
拿不准的条目，优先按句子处理，或在方案中标注出来让用户决定。

第二步：调查现状（只读）

根据内容形态确定 bookType 后，调用词库接口的 book.list（带 bookType 参数）查找已有词库；对有希望的候选词库，再调用单元接口的 unit.list 查看其单元。

这一步只允许调用查询接口，不允许调用任何创建/添加接口。

第三步：出具预执行方案，等待用户确认

调查完成后，必须先把方案发给用户确认，方案包含：

内容形态判断结果：整理出了多少个单词/词组、多少个句子。
目标词库：
- 上下文有明确合适的现有词库 → 直接使用，方案中说明「放入现有词库《XXX》」；
- 没有合适的词库 → 方案中说明「新建词库《XXX》（句子库/单词库）」，并给出你建议的词库名称。
目标单元：说明放入哪个现有单元，或新建单元并给出建议名称（如「Unit 1 入住酒店」，序号参考已有单元顺延）。
内容预览：列出前几条整理好的内容（含译文），让用户快速判断质量。

方案示例：

我整理了一下，计划这样添加到 WordMomo：
内容：6 个句子（含译文）
你的句子库里没有合适的词库，计划新建句子库《酒店情景对话》
在其中新建单元「Unit 1 入住酒店」
预览：I have a reservation under the name Gao. = 我用高这个名字订了房间。……
没问题的话回复「执行」，我就写入；如果想放到其他词库/单元，告诉我即可。

确认规则：

用户回复「执行」「可以」「好」等明确同意 → 按方案执行。
用户指出要放入某个已有词库/单元 → 调整方案（必要时重新调用 unit.list 确认目标），简述调整后方案再执行。
用户未确认前，不得调用 book.create / unit.create / word.import / word.add。
即使上下文已经聊到了明确合适的词库，也仍需用简短方案确认「放入该库的哪个单元、是否新建单元」，再执行。

第四步：执行与汇报

用户确认后按方案执行。优先使用一键导入接口 word.import：一次调用即可自动完成「找到或创建词库 → 找到或创建单元 → 写入全部内容」，不需要逐个调用 book.create / unit.create / word.add。

仅当需要向多个已存在的不同词库分别追加内容时，才使用 word.add 分步调用。

完成后必须向用户汇报：添加了多少条、跳过了多少条重复、最终写入了哪个词库哪些单元，并提醒用户回到 WordMomo 开始学习。

一键导入（推荐）

POST /ai/invoke
method: word.import

一次调用完成整批导入：按词库名称匹配现有词库（同名同类型则直接使用，否则自动创建），再按单元名称匹配或创建单元，最后把内容写入对应单元。

请求体

json

{
  "method": "word.import",
  "data": {
    "bookName": "酒店情景对话",
    "bookType": "sentencelib",
    "units": [
      {
        "unitName": "Unit 1 入住酒店",
        "items": [
          { "word": "I have a reservation under the name Gao.", "translate": "我用高这个名字订了房间。" },
          { "word": "Could I check in now?", "translate": "我现在可以办理入住吗？" }
        ]
      },
      {
        "unitName": "Unit 2 客房服务",
        "items": [
          { "word": "Could I have a wake-up call at 7?", "translate": "能安排早上7点的叫醒服务吗？" }
        ]
      }
    ]
  }
}

data 参数：

字段	必填	说明
`bookName`	是	词库名称。已存在同名同类型词库时直接复用，不会重复创建
`bookType`	是	词库类型：`wordlib`=单词库、`sentencelib`=句子库，按第一步的内容形态判断结果填写
`units`	是	单元数组，至少一个，见下表

units 数组每项：

字段	必填	说明
`unitName`	是	单元名称。已存在同名单元时直接复用，内容追加到该单元
`items`	是	词汇数组，字段与下方 `word.add` 的 `items` 完全一致（`word`/`translate` 必填，`symbol` 可选）

请求示例

bash

curl -X POST http://127.0.0.1:27531/ai/invoke \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"method\":\"word.import\",\"data\":{\"bookName\":\"酒店情景对话\",\"bookType\":\"sentencelib\",\"units\":[{\"unitName\":\"Unit 1 入住酒店\",\"items\":[{\"word\":\"Could I check in now?\",\"translate\":\"我现在可以办理入住吗？\"}]}]}}"

响应示例

json

{
  "success": true,
  "data": {
    "bookId": "c3d9e4b1a2f3",
    "bookName": "酒店情景对话",
    "bookCreated": true,
    "totalAdded": 3,
    "totalSkipped": 0,
    "units": [
      { "unitId": "u5f6e7d8c9b0a", "unitName": "Unit 1 入住酒店", "unitCreated": true, "added": 2, "skipped": 0 },
      { "unitId": "u1b2c3d4e5f6", "unitName": "Unit 2 客房服务", "unitCreated": true, "added": 1, "skipped": 0 }
    ]
  }
}

响应字段

字段	说明
`bookId`	目标词库 ID
`bookName`	目标词库名称
`bookCreated`	本次是否新建了词库
`totalAdded`	全部单元合计新增条数
`totalSkipped`	全部单元合计因重复跳过的条数
`units`	每个单元的执行明细：`unitId`、`unitName`、`unitCreated`、`added`、`skipped`

添加项目（单步追加）

POST /ai/invoke
method: word.add

向指定词库的指定单元批量添加词汇（单词/词组或句子）。目标库是单词库还是句子库由 bookId 对应的词库类型决定，接口本身不需要你区分。

请求体

json

{
  "method": "word.add",
  "data": {
    "bookId": "c3d9e4b1a2f3",
    "unitId": "u5f6e7d8c9b0a",
    "items": [
      { "word": "reservation", "translate": "预订", "symbol": "/ˌrezərˈveɪʃn/" },
      { "word": "check in", "translate": "办理入住" }
    ]
  }
}

data 参数：

字段	必填	说明
`bookId`	是	词库 ID，来自 `book.list` 或 `book.create`
`unitId`	是	单元 ID，来自 `unit.list` 或 `unit.create`
`items`	是	词汇数组，见下表

items 数组每项：

字段	必填	说明
`word`	是	内容，单词、词组或句子
`translate`	是	译文。必须由你补全，使用用户的母语（通常为简体中文），简洁准确
`symbol`	否	音标。放入单词库的单词建议提供，词组和句子可不提供

请求示例

bash

curl -X POST http://127.0.0.1:27531/ai/invoke \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"method\":\"word.add\",\"data\":{\"bookId\":\"c3d9e4b1a2f3\",\"unitId\":\"u5f6e7d8c9b0a\",\"items\":[{\"word\":\"reservation\",\"translate\":\"预订\",\"symbol\":\"/ˌrezərˈveɪʃn/\"},{\"word\":\"check in\",\"translate\":\"办理入住\"}]}}"

响应示例

json

{
  "success": true,
  "data": {
    "added": 2,
    "skipped": 1
  }
}

响应字段

字段	说明
`added`	实际新增的条数
`skipped`	因与库中已有内容重复而跳过的条数

备注

单次建议不超过 100 条，内容较多时分批调用。
单词库有内置查重（按词库设置），重复内容会计入 skipped 而不会重复添加。

行为准则（请遵守）

先方案后执行：任何写入操作前必须先出具预执行方案并获得用户确认。
先判断再放库：单词/词组绝不放入句子库，句子绝不放入单词库。
建库先询问：没有合适词库时，先征得用户同意再创建，不要静默创建。
译文必补全：translate 不能为空，由你根据上下文补全。
结果必汇报：每次添加后向用户说明结果（added / skipped / 目标词库与单元）。
不猜 ID：bookId、unitId 只能来自接口返回，不要凭空构造。

词汇接口 ​

决策流程总览 ​

第一步：判断内容形态 ​

第二步：调查现状（只读） ​

第三步：出具预执行方案，等待用户确认 ​

第四步：执行与汇报 ​

一键导入（推荐） ​

请求体 ​

请求示例 ​

响应示例 ​

响应字段 ​

添加项目（单步追加） ​

请求体 ​

请求示例 ​

响应示例 ​

响应字段 ​

备注 ​

行为准则（请遵守） ​

词汇接口

决策流程总览

第一步：判断内容形态

第二步：调查现状（只读）

第三步：出具预执行方案，等待用户确认

第四步：执行与汇报

一键导入（推荐）

请求体

请求示例

响应示例

响应字段

添加项目（单步追加）

请求体

请求示例

响应示例

响应字段

备注

行为准则（请遵守）