# DictX
DictX 是一个 Rust 编写的终端词典应用：本地优先、离线检索、彩色排版，并支持按需调用在线 AI API 做词义详解。
DictX 不直接把 CSV、SQLite、MDX 当作运行期查询文件。外部词库会先转换成 DictX 专有 `.dxdict` 二进制词库包，再构建本地 Tantivy 索引。查询时只读取本地索引和二进制词条包，普通查词不联网。
[](https://crates.io/crates/dictx)
[](https://docs.rs/dictx)
## 特性
- **内置高质量词库**：默认内置 `新世纪汉英大词典` 和 `kd_data` 转换后的 DictX 词库分片。
- **离线优先**：`lookup`、`search`、`zh` 都基于本地索引，普通查询不会请求网络。
- **专有词库格式**：支持把 MDX、SQLite、ECDICT CSV、Anki JSONL、CC-CEDICT 转换为 `.dxdict`。
- **终端交互**：Rich 模式默认显示前 3 条结果，支持加载更多、数字键触发 AI 详解、鼠标点击操作栏。
- **可选 AI**：兼容 OpenAI Chat Completions 风格接口，默认面向 DeepSeek 配置。
## 安装
```bash
cargo install dictx --locked
```
Cargo 通常会把可执行文件安装到 `~/.cargo/bin`。如果终端提示找不到 `dictx`，请确认该目录已经加入 `PATH`。
## 快速开始
```bash
dictx init
dictx build
dictx lookup apple
dictx zh 老师
dictx search '~appple'
```
`dictx init` 只写入配置和内置词源，不会自动生成索引。第一次安装、执行 `dictx init --force`、更换词源或更换索引目录后，都需要先运行 `dictx build`。
查看当前路径和词源：
```bash
dictx config paths
dictx source list
```
Rich 输出进入交互状态后：
- 按 `n` 加载更多结果
- 按 `1`、`2`、`3` 查询当前可见卡片的 AI 详解
- 支持鼠标的终端可以点击底部操作栏
- 按 `q` 退出
## 内置词库
`dictx init` 默认写入两个内置词源：
| `builtin_new_century` | `builtin:new-century-han-eng` | 新世纪汉英大词典转换后的汉英词库 |
| `builtin_kd_data` | `builtin:kd-data` | kd_data 转换后的英汉/汉英词库 |
内置词库随 Cargo 依赖安装，用户不需要保留原始 `.mdx` 或 `.db` 文件。第一次使用时运行 `dictx build` 即可生成本地索引。
## 支持格式
| DictX 内置包 | `builtin-dxdict` | 内置词库专用格式 |
| DictX 专有包 | `dxdict` | 推荐的运行期词库格式 |
| MDX / MDict | `mdx` | 解析 `.mdx`，清洗 HTML，并提取释义、例句、短语 |
| SQLite 词典库 | `sqlite` | 已适配 `kd_data.db` 的 `en/ch` 表结构 |
| ECDICT CSV | `ecdict` | 英汉词库，可包含音标、标签、词频等字段 |
| Anki JSONL | `anki-jsonl` | 自制词卡、导出词卡、JSONL 词库 |
| CC-CEDICT | `cedict` | 汉英补充词库 |
导入外部词库并登记配置：
```bash
dictx source import new_century /path/to/新世纪汉英大词典.mdx --format mdx
dictx source import kd_data /path/to/kd_data.db --format sqlite
dictx source import ecdict /path/to/ecdict.csv --format ecdict
dictx build
```
只生成 `.dxdict` 文件，不修改配置：
```bash
dictx source pack /path/to/dict.mdx ./dict.dxdict --format mdx
dictx source add my_dict ./dict.dxdict --format dxdict
dictx build --source my_dict
```
大词库可以按词条数拆分：
```bash
dictx source pack /path/to/kd_data.db ./kd-data.dxdict --format sqlite --shard-size 22000
```
## 查询
```bash
dictx lookup bus # 精确查词
dictx l bus # lookup 短别名
dictx zh 伙计 # 中文反查英文
dictx search fruit --pos n # 全文搜索并按词性过滤
dictx search '~buss' # 模糊搜索
dictx search 'trans*' # 通配符搜索
dictx lookup bus --format plain # 纯文本输出
dictx lookup bus --format json # JSON 输出
```
默认 Rich 模式只展示前 3 条结果。需要一次性展示更多时：
```bash
dictx zh 伙计 --limit 10
```
## 配置
查看配置：
```bash
dictx config path
dictx config show
```
常用配置项：
| `dict_dir` | DictX 管理的 `.dxdict` 词库目录 |
| `index_dir` | 索引和 `entries.dxp` 缓存目录 |
| `search.default_limit` | 默认查询数量 |
| `search.fuzzy_distance` | 模糊搜索距离，最大为 2 |
| `output.color` | 是否启用彩色输出 |
| `output.examples` | 是否显示例句 |
| `ai.base_url` | OpenAI-compatible API 地址 |
| `ai.model` | AI 模型名称 |
| `ai.api_key_env` | API key 所在环境变量名 |
默认 AI 配置：
```text
base_url = https://api.deepseek.com
model = deepseek-v4-flash
api_key_env = DEEPSEEK_API_KEY
```
使用 DeepSeek：
```bash
export DEEPSEEK_API_KEY=...
dictx ai "take off" --context "The plane will take off at noon."
```
切换到其他 OpenAI-compatible 服务：
```bash
dictx config set ai.base_url https://api.openai.com/v1
dictx config set ai.model gpt-4o-mini
dictx config set ai.api_key_env OPENAI_API_KEY
```
## 文件位置
DictX 按系统标准目录保存运行期文件：
- 配置文件：`dictx config path`
- 词库目录：`dictx config get dict_dir`
- 索引目录：`dictx config get index_dir`
索引属于可重建缓存。词库更新或索引格式升级后，运行：
```bash
dictx build --force
```
早期版本使用过 `~/.dictx/config.toml`。如果新的系统标准配置文件不存在，DictX 会继续读取旧路径；需要重建默认配置时运行：
```bash
dictx init --force
```
## 许可
DictX 程序代码采用 MIT License。内置词库数据以其原始词库来源和发布许可为准。