youdao-dict-cli

有道词典系列产品的统一命令行工具。让你（以及 LLM agent）在终端里管理单词本和单词。

youdao wordbook list
youdao wordbook words add --book-id default --word hello
youdao wordbook words check --word hello

支持 macOS / Linux / Windows x arm64 / amd64。

安装

npm install -g @youdao/dict-cli

npm 会根据你的系统 + 架构自动装对应的二进制子包。要求 Node.js >= 16。

验证：

youdao version
# youdao 0.1.0 (2026-05-26T...)

首次授权

youdao config init

会做：

1. 调后端创建一个 auth session
2. 自动打开系统浏览器到有道登录页
3. 你登录有道账号
4. 浏览器看到"授权成功"页面

终端随即打印：

{"ok": true, "data": {"loggedIn": true, "userId": "..."}}

API key 会存进 macOS Keychain（Linux / Windows 用各自系统的凭据管理）。

如果浏览器无法自动打开，终端会打印 authorizeUrl，手动复制到浏览器完成登录即可。

若需要跳过浏览器直接喂 key：

youdao config init --api-key YOUR_KEY

查看配置

youdao config show

{
  "ok": true,
  "data": {
    "baseUrl": "https://youdao-cli.youdao.com",
    "apiKeySource": "keychain",
    "configPath": "/Users/<you>/.youdao/config.json"
  }
}

| 字段 | 含义 | |---|---| | baseUrl | 后端地址（youdao-cli-service） | | apiKeySource | API key 存哪里：keychain / file / env / none | | configPath | 配置文件路径 |

人类友好显示：

youdao --format pretty config show

直接读 keychain 里的明文 key（不要粘到聊天/日志）：

security find-generic-password -s youdao-dict-api-key -a youdao-dict-api-key -w

切换后端环境

默认连生产 https://youdao-cli.youdao.com。

# 临时切（单次命令）
YOUDAO_DICT_BASE_URL=https://youdao-cli-test.youdao.com youdao wordbook list

# 永久切（写入 shell 配置）
echo 'export YOUDAO_DICT_BASE_URL=https://youdao-cli-test.youdao.com' >> ~/.zshrc
source ~/.zshrc

优先级：YOUDAO_DICT_BASE_URL env > 配置文件 > 默认值。

配置文件位于 ~/.youdao/config.json（可通过 YOUDAO_DICT_CONFIG_DIR 环境变量覆盖目录）。

命令清单

config

youdao config init [--api-key KEY]   # OAuth 授权；--api-key 跳过浏览器手动喂
youdao config show                    # 当前生效配置
youdao config logout                  # 清掉本地 key（keychain + config 文件），baseUrl 保留

wordbook

youdao wordbook list [--product P] [--client C]
youdao wordbook add --name NAME              # 新建自定义单词本
youdao wordbook add --recommend-id ID        # 收藏推荐单词本（平台预置题库）
youdao wordbook rename --book-id ID --name NEW_NAME

dict

youdao dict search --word <word> [--le en|ja|ko|fr|de|es|pt|ru] [--json]

查询有道词典释义。默认输出格化文本（音标 / 释义 / 短语 / 翻译 / 例句）；加 --json 输出原始 jsonapi_s JSON。详见 skills/youdao-dict/SKILL.md 的「查词」章节。

wordbook words

youdao wordbook words list  --book-id ID [--lan-from L] [--lan-to L] [--sort time|asc|desc] [--limit 30] [--offset 0]
youdao wordbook words add   --book-id ID --word WORD [--lan-from L] [--lan-to L] [--text TRANS]
youdao wordbook words del   --book-id ID --word WORD [--remove-from-all]
youdao wordbook words check --word WORD

wordbook words add 参数组合：

| 模式 | 行为 | |---|---| | 只给 --word，不给 lan | 后端自动查词典，注入 lanFrom=en/lanTo=zh-CHS | | 给 lan + --text | 用你给的 text 作为释义 | | 给 lan、不给 text（支持的语言对） | 后端调有道翻译自动翻 | | 给 lan、不给 text（不支持的语言对） | 返 exit 2 INVALID_INPUT（要求必须给 --text） |

全局选项

youdao --format json|pretty         # 输出格式，默认 json
youdao --base-url URL               # 覆盖 baseUrl（单次命令）
youdao --help / -h                  # 任何命令带 -h 看帮助

输出约定

所有命令输出 JSON envelope：

// 成功
{"ok": true, "data": {...}}

// 失败（写到 stderr）
{"ok": false, "error": {"type": "...", "message": "...", "hint": "..."}}

退出码

| exit | type | 含义 | 建议做法 | |---|---|---|---| | 0 | — | 成功 | 继续 | | 1 | UNKNOWN | 未分类错误 / 网络异常 / JSON 解析失败 | 检查网络；重试一次 | | 2 | INVALID_INPUT | 参数错 / 缺必填 / 后端 400 | 改参数重试 | | 3 | UNAUTHORIZED | API key 失效 / 没传 | youdao config init 重新授权 | | 4 | FORBIDDEN | 操作他人资源（预留） | 放弃 | | 5 | NOT_FOUND | bookId 不存在 / 单词没收藏 | youdao wordbook list 查可用 ID | | 6 | CONFLICT | bookName 重名 | 换个名 | | 7 | RATE_LIMITED | 每分钟请求超限 | 等 60 秒重试 | | 8 | NEED_UPGRADE | CLI 版本太低 | npm install -g @youdao/dict-cli@latest |

给 LLM Agent 用

安装后 SKILL.md 在：

$(npm root -g)/@youdao/dict-cli/skills/youdao-dict/SKILL.md

包含完整的命令文档、错误码处置矩阵、4 个典型工作流（幂等收藏 / 建本批量收藏 / 导出 / 智能删除）。

agent 把 youdao 当工具用时，强制 JSON 模式（默认即是）。workflows.md 描述了"先 check 再 add"这种最常见的幂等模式。

卸载

完全卸载：

npm uninstall -g @youdao/dict-cli
rm -rf ~/.youdao/
security delete-generic-password -s youdao-dict-api-key -a youdao-dict-api-key 2>/dev/null

让后端上对应的 API key 也失效（可选）：在后端 Mongo openapi_api_key 集合对应行设 revoked: true。

故障排查

Unsupported platform: <os>-<arch> 你的系统不在 darwin/linux/win32 x arm64/amd64 这 6 个组合里。打开 issue。

Platform package @youdao/dict-cli-... is not installed 某些 npm 客户端跳过 optionalDependencies。重装：npm install -g @youdao/dict-cli --force。

exit 3 UNAUTHORIZED key 失效或被 revoke。youdao config init 重新授权。如果浏览器流程超时（5 分钟没登录），用 --api-key 直接喂。

换账号 / 共享机器 youdao config logout 清本地 key（keychain entry + config 文件中的 apiKey 字段），baseUrl 保留。下次需要使用时重新运行 youdao config init 即可。

exit 7 RATE_LIMITED 默认每个 API key 60 次/分钟（由 youdao-cli-service 控制）。批量收藏单词时控制并发 <= 3。

open browser failed 或 xdg-open: command not found（Linux） 缺少 GUI / 缺浏览器。手动复制终端打印的 authorizeUrl 到任意能上网的浏览器。

开发

源码：内部仓库

git clone <repo-url>
cd youdao-dict-cli
make build            # 本地构建 ./youdao
make test             # 跑全部测试（含超时保护）
make install          # 装到 /usr/local/bin/youdao

发版手册：docs/release.md

设计文档：docs/superpowers/specs/2026-05-26-youdao-cli-platform-design.md

License

UNLICENSED — internal Youdao tooling.