# DictX
DictX 是一个用 Rust 编写的终端词典应用，主路径是离线词库索引查询，辅助路径是显式调用的在线 AI API 解释。
## 功能
- 离线索引：基于 Tantivy 构建本地全文索引。
- 多词典源：支持 ECDICT CSV、Anki/JSONL、金山词霸 SQLite、CC-CEDICT。
- 查询方式：精确查词、模糊搜索、全文搜索、中文反查、通配符搜索。
- 输出格式：自适应卡片、彩色 rich、plain、json；rich 模式默认展示 3 条，支持键盘/鼠标加载更多。
- 高性能存储：构建时生成 Tantivy 检索索引和 `entries.dxp` 二进制词条 pack。
- AI 增强：`dictx ai` 使用 OpenAI-compatible `/chat/completions` API；rich 模式可在结果页按数字键或点击操作条触发 AI 详解。
## 安装
发布到 crates.io 后，推荐用 Cargo 安装：
```bash
cargo install dictx
```
本地仓库调试安装：
```bash
cargo install --path crates/dictx-cli --locked --force
```
Cargo 会把可执行文件安装到 Cargo install root 的 `bin` 目录。使用 rustup 的默认环境时通常是 `~/.cargo/bin`，需要确保它在 `PATH` 中。
## 快速开始
```bash
# 生成配置；新安装默认使用系统标准配置/数据/缓存目录
dictx init
# 查看配置、词库和索引目录
dictx config paths
# 推荐把下载的词库导入 DictX 管理目录
dictx source import ecdict /path/to/ecdict.csv --format ecdict
dictx source import cc_cedict /path/to/cedict_ts.u8 --format cedict
# 构建已启用词典源索引
dictx build
# 查询
dictx lookup apple
dictx search '~appple'
dictx zh 苹果
```
rich 输出会停留在交互状态：按 `n` 加载更多，按 `1`/`2`/`3` 查询当前可见卡片的 AI 详解，按 `q` 退出。鼠标终端支持时，也可以直接点击底部操作条。
## 常用命令
```bash
dictx source list
dictx source recommend
dictx source import ecdict /path/to/ecdict.csv --format ecdict
dictx source add external_db /path/to/kd_data.db --format sqlite
dictx build --source ecdict --force
dictx lookup cancel --format plain
dictx search fruit --pos n --tag cet4 --limit 20
dictx config set output.color false
```
`source import` 会复制词库到 DictX 管理目录，适合长期使用；`source add` 只引用外部文件，适合临时测试或你自己管理大词库目录的场景。
## AI API
AI 命令默认使用 DeepSeek OpenAI-compatible API：
- `base_url`: `https://api.deepseek.com`
- `model`: `deepseek-v4-flash`
- API key 环境变量：`DEEPSEEK_API_KEY`
也兼容 `DICTX_AI_API_KEY` 和 `OPENAI_API_KEY`。
```bash
export DEEPSEEK_API_KEY=...
dictx ai "take off" --context "The plane will take off at noon."
```
切换到其他 OpenAI-compatible endpoint：
```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
```
## 词典源状态
| ECDICT CSV | 已支持 | 字段按 `docs/03-数据层设计.md` 映射 |
| Anki JSONL | 已支持 | 已用 `old/KaoYan_3.json` 验证 |
| SQLite | 已支持 | 已支持 zlib JSON detail 提取 |
| CC-CEDICT | 已支持 | 下载 `cedict_ts.u8` 后用 `--format cedict` 添加 |
| MDX | 受控拒绝 | 原生 MDX 解析风险高，当前会提示先转换为 JSONL |
推荐开放词库可运行：
```bash
dictx source recommend
```
## 目录设计
DictX 把运行期文件分成三类：
- 配置：`dictx config path` 查看，默认位于系统配置目录下的 `dictx/config.toml`。
- 词库源文件：`dictx config get dict_dir` 查看，建议通过 `dictx source import` 管理。
- 索引与二进制 pack：`dictx config get index_dir` 查看，属于可重建缓存；换词库或升级索引格式后运行 `dictx build --force`。
为了兼容早期版本，如果新的标准配置文件不存在，但 `~/.dictx/config.toml` 已存在，DictX 会继续读取旧配置。
## 存储设计
`dictx build` 是一次完整物化过程。构建结果包含：
- Tantivy 索引：只保存检索、过滤、排序所需字段。
- `entries.dxp`：MessagePack 二进制词条 pack，按 offset/len 随机读取完整词条。
旧索引里的 JSON 存储仍兼容；重新运行 `dictx build --force` 后会生成新的二进制 pack。
## 开发验证
```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo publish -p dictx --dry-run
```
本仓库要求 Rust 1.82+；当前验证工具链为 Rust 1.95.0。
## 发布 v0.1.0
发布前先完整验证：
```bash
cargo fmt --all
cargo test --workspace
cargo publish -p dictx-core --dry-run
cargo publish -p dictx-parser --dry-run
cargo publish -p dictx-index --dry-run
cargo publish -p dictx-search --dry-run
cargo publish -p dictx --dry-run
```
真实发布需要 crates.io token，并按依赖顺序发布：
```bash
cargo login
cargo publish -p dictx-core
cargo publish -p dictx-parser
cargo publish -p dictx-index
cargo publish -p dictx-search
cargo publish -p dictx
git tag v0.1.0
```