# WordTrail API

技能版本：4.1.0
技能链接：https://eng.gzyunke.cn/api/v1/skill/read
版本查询：https://eng.gzyunke.cn/api/v1/skill/version
API 基础地址：https://eng.gzyunke.cn/api/v1

## 版本与认证

所有业务 /api/v1/ 请求（包括注册、登录、GET，公开技能端点除外）必须携带 X-WordTrail-Skill-Version: 4.1.0。公开 /api/v1/skill/version、/api/v1/skill/read、/api/v1/skill/docs 不需要版本或认证。所有响应都携带 X-WordTrail-Skill-Version 响应头。

缺少版本返回 428 / SKILL_VERSION_REQUIRED，旧版本返回 409 / SKILL_VERSION_MISMATCH。正文示例：

    { "code": "SKILL_VERSION_MISMATCH", "error": "请重新读取技能链接，并按照当前版本调用接口", "currentVersion": "4.1.0", "skillUrl": "https://eng.gzyunke.cn/api/v1/skill/read" }

版本错误时业务操作没有执行。Agent 自动重新读取技能链接全文及相关接口文档，遵照新协议重建请求，最多自动升级重试一次。不能只复制错误中的版本号跳过阅读。复习重试保留原 requestId。每次新任务先查版本，和已读版本不同则重读。

用户先在网页用邮箱和密码注册 / 登录，在 Agent 接入面板生成个人密钥。将密钥配置到 agent 的 WORDTRAIL_API_KEY 环境变量，API 请求发送 Authorization: Bearer <个人密钥>。密钥只操作所属账号数据，重新生成撤销旧密钥。Agent 不需要用户登录密码。

## 写入单词

POST /words/upsert，Content-Type: application/json：

    { "words": [{
      "word": "wander", "meaning": "漫步；徘徊", "partOfSpeech": "v.",
      "phonetic": "/ˈwɒndə/", "example": "We wandered through the old town.",
      "exampleTranslation": "我们在古城中漫步。",
      "synonyms": [{ "word": "roam", "phonetic": "/roʊm/", "meaning": "漫游", "note": "都可表示没有固定目的地地走动" }],
      "similarWords": [{ "word": "wonder", "phonetic": "/ˈwʌndər/", "meaning": "想知道；惊奇", "note": "只差一个元音字母" }]
    }] }

必填字符串：word（最多120字符）、meaning（中文，2000）、partOfSpeech（词性，120）、example（英文例句，4000）。phonetic 为必填 IPA 音标字符串（200字符）；可选字符串：exampleTranslation（4000）。字符串去首尾空格，必填不能为空。

必填数组：synonyms（近义词）、similarWords（拼写或发音易混淆词），各最多20项，没有可靠词时传 []。每项 word、meaning、phonetic 必填，各最多120、500、200字符；note 选填最多1000字符。关联词不会自动加入待背词库。

响应 200，正文为 words 数组，包含完整词条。每批1–500词，最多1MB。全批校验失败不写入；单机 MongoDB 按词依次写入，故障可能部分成功，先查询确认再重试。同一账号按英文大小写不敏感去重，重复词替换全部内容，但保留 ID 和复习状态。可选字段省略、数组 [] 会清空相应内容；部分更新先读已有内容合并再提交。

## 查询

GET /words/list?due=true&q=wand&limit=50&offset=0：due=true 只查到期词，省略查全部；q 为英文子串搜索，大小写不敏感。返回 words 和 total，按 nextReviewAt、id 排序。

GET /words/detail/:id：返回 word 对象。ID 是字符串 UUID，请原样使用。他人词条和不存在的词都返回404。

GET /reviews/list?wordId=<字符串ID>&limit=50&offset=0：wordId可选，返回 reviews 和 total，按复习时间倒序。

GET /stats/summary：返回 total、due、fresh、mastered、reviews、remembered。fresh为未复习词数，mastered为连续记住至少3次的词数，后两项为累计次数。

分页limit默认50、最大500，offset默认0，按total判断是否继续。所有查询仅返回当前账号数据。

完整单词除内容外包含 id、createdAt、updatedAt、reviewCount、rememberedCount、streak、lastResult、lastReviewedAt、nextReviewAt。未复习时计数为0，lastResult和lastReviewedAt为null。时间是UTC ISO8601。

## 记录真实复习结果

POST /reviews/create：

    { "wordId": "接口返回的字符串ID", "result": "remembered", "requestId": "2e04f385-33a2-4bed-8b72-941dd61c24ad" }

result为remembered或forgotten。requestId为8–100位字母、数字、下划线、连字符，建议UUID。每次独立复习生成新ID；网络或版本重试复用原ID。同一账号内相同ID不会重复计数，用于其他词或结果则409。响应含review和word。

review包含id（requestId）、wordId、word、result、reviewedAt、当次nextReviewAt。记住间隔为1、3、7、14、30、60天，后续60天；遗忘重置streak，1分钟后到期，网页本轮稍后重新出现。Agent仅在用户确认结果并要求记录时调用，不猜测。

## 账号接口

以下接口同样需要版本头。POST使用JSON。

- POST /auth/register：email、password，创建账号并设置会话Cookie。
- POST /auth/login：email、password，登录并设置会话Cookie。
- GET /auth/me：返回 user 对象（id、email）。
- POST /auth/logout：空对象，撤销当前会话。
- POST /auth/token：空对象，仅允许网页登录会话，生成新个人密钥，返回token；旧密钥立即失效。

邮箱最长254字符，去空格并小写；密码10–128字符，数据库保存加盐scrypt哈希。Cookie为HttpOnly、SameSite=Lax、HTTPS下Secure，30天有效。Agent密钥只存哈希。登录注册有频率限制。当前没有邮箱验证码、找回密码或更换邮箱功能。

## 错误

一般错误正文为error；版本错误另有code、currentVersion、skillUrl。400参数错误，401未登录/密钥无效，403非同源或需网页登录，404不存在，409邮箱已注册/复习冲突/版本冲突（按code区分），413超过1MB，415内容类型错误，428缺少版本，429请求频繁，500服务错误。Nginx的413可能返回HTML。

HTTP客户端无需Origin；浏览器写入需同源，不开放跨域CORS。除版本升级和明确幂等重试外，不要无条件循环重试。


## 完整路径一览

统一格式：/api/v1/功能/操作。v1 是 URL API 版本；技能文档版本由 X-WordTrail-Skill-Version 单独校验。

| 方法 | 完整路径 | 用途 |
| --- | --- | --- |
| POST | /api/v1/auth/register | 注册 |
| POST | /api/v1/auth/login | 登录 |
| POST | /api/v1/auth/logout | 退出 |
| GET | /api/v1/auth/me | 当前账号 |
| POST | /api/v1/auth/token | 生成个人 Agent 密钥 |
| GET | /api/v1/words/list | 词库列表与搜索 |
| GET | /api/v1/words/detail/:id | 单词详情 |
| POST | /api/v1/words/upsert | 批量新增或更新 |
| GET | /api/v1/reviews/list | 复习历史 |
| POST | /api/v1/reviews/create | 记录复习 |
| GET | /api/v1/stats/summary | 学习统计 |
| GET | /api/v1/skill/version | 公开版本查询 |
| GET | /api/v1/skill/read | 公开技能全文 |
| GET | /api/v1/skill/docs | 公开接口说明 |

旧 /agent/skill、/agent/version、/agent/api 链接仅作 308 跳转。旧业务路径不再处理业务：旧技能请求先获得版本错误，更新技能后应按本表调用新路径。

网页显示主词音标；近义词和相似词可悬停、聚焦或点击查看各自音标，空关联词区域隐藏。朗读使用设备 / 浏览器的英语语音，优先 en-US，实际声音由设备决定。

## 例句查词

GET /dictionary/lookup?word=things，沿用认证和技能版本头。word 为 1–64 个字符的英文单词，可包含内部连字符或撇号，非法输入返回400。

返回200：{ "entry": { "word": "things", "meaning": "…", "phonetic": "/…/", "source": "ECDICT" } }，未收录返回 { "entry": null }。优先查询当前账号的词库，再查本地 ECDICT。回退到原形时 phonetic 为空，另有 lemma、lemmaPhonetic；客户端应明确标为原形音标。释义是常见词典义，不是例句上下文翻译。查询不写入用户词库和复习记录。

词典来源：https://github.com/skywind3000/ECDICT （MIT），许可证保存在 server/data/dictionary/LICENSE。

本地未收录时调用 Free Dictionary API（https://dictionaryapi.dev/），仅向外部发送待查单词，不发送账号或密钥。外部结果标记 language=en，保留来源及许可；不可当成中文释义。成功缓存24小时，未收录缓存5分钟；5秒超时或外部故障返回502，繁忙返回503，可稍后手动重试。