Metadata-Version: 2.4
Name: vex-cli
Version: 0.1.1
Summary: Natural language CLI — type : and speak your intent
Project-URL: Homepage, https://github.com/yourusername/vex
Project-URL: Repository, https://github.com/yourusername/vex
Project-URL: Issues, https://github.com/yourusername/vex/issues
License: MIT
Keywords: ai,cli,natural-language,shell,vex,vim
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# ex

> 在终端输入 `:` 进入 AI 命令模式。说出你想做什么，ex 规划并执行。

**ex 本身完全免费。** 你需要自己的 LLM API Key（或本地 Ollama，也免费）。

```
❯
:找出所有超过200行的Python文件，按行数倒序
```

---

## 安装

### pipx（推荐）

```bash
pipx install ex-cli
vex --setup
vex --setup        # 配置你的 API Key + 初始化 shell 集成
# 重开终端
```

### pip

```bash
pip install ex-cli
vex --setup
```

### Homebrew（macOS）

```bash
brew tap yourusername/tap
brew install ex
vex --setup
```

---

## 第一步：获取 API Key

`vex --setup` 会引导你选择并填入，支持以下提供商：

| 提供商 | 注册地址 | 价格 |
|--------|---------|------|
| **DeepSeek** | platform.deepseek.com/api_keys | ¥0.001/千 tokens，**最便宜** |
| **Kimi** | platform.moonshot.cn/console/api-keys | 注册有免费额度 |
| **OpenAI** | platform.openai.com/api-keys | GPT-4o-mini 按量付费 |
| **Ollama** | ollama.com | **完全免费**，本地运行 |

填入一个 API Key 就能用，Key 保存在你本地的 `~/.zshrc`，不经过任何第三方服务。

---

## 使用

重开终端后，在**空白行**输入 `:` 即可进入 AI 命令模式：

```
❯
:找出所有超过200行的Python文件，按行数倒序

  ▌ 找出所有 Python 文件并按行数排序

   1   fd -e py .
       " 递归查找所有 .py 文件

   2   xargs wc -l
       " 统计每个文件行数

   3   sort -rn | grep -v total | head -20
       " 倒序取前20

  管道：fd -e py . | xargs wc -l | sort -rn | grep -v total | head -20

  [p]管道执行  [s]逐步确认  [q]退出 > p

  │ 1842 ./src/engine.py
  │  967 ./src/routes.py
  │  543 ./tests/test_engine.py
```

### Vim 语义完整保留

| 输入 | 行为 |
|------|------|
| `:找大文件` | AI 规划 + 逐步确认 |
| `:!ls -la` | 直通 shell（Vim `:!` 语义） |
| `:h 找大文件` | 只看计划，不执行 |
| `:q` | 什么都不发生 |
| `:q!` | 退出当前 shell |
| `Ctrl+:` | 自动执行，不逐步确认 |
| `ESC` | 取消，返回普通提示符 |

### 行不为空时，`:` 正常插入

```
❯ echo "hello:world"    ← 正常，不触发 AI
❯ git commit -m ":"     ← 正常，不触发 AI
```

---

## 配置 LLM

运行 `vex --setup` 时会引导配置，也可以手动设置环境变量：

```bash
# 推荐：DeepSeek（成本最低）
export DEEPSEEK_API_KEY=sk-xxx

# 或 Kimi
export MOONSHOT_API_KEY=sk-xxx

# 或 OpenAI
export OPENAI_API_KEY=sk-xxx

# 或完全本地（需先安装 ollama）
ollama run qwen2.5-coder:7b
```

---

## 命令参考

```bash
vex --setup      # 初始化 shell 集成（首次安装后运行）
vex --config     # 修改 LLM / 执行模式配置
ex --update     # 更新到最新版本
vex --version    # 显示版本

# 执行模式（也可在 --config 中设置）
EX_MODE=confirm   # 默认：逐步确认
EX_MODE=auto      # 自动执行
EX_MODE=dry       # 演习：只显示计划

# 静默启动（不显示提示信息）
EX_QUIET=1
```

---

## 卸载

```bash
vex --config     # 选择"卸载"，自动从 rc 文件移除
pipx uninstall ex-cli
```

---

## 示例

```bash
:在所有 TypeScript 文件里找使用了 console.log 的地方

:把 downloads 目录里超过 100MB 的文件找出来，按大小排序

:从 meeting.mp4 提取音频，转成 mp3

:扫描这个 Python 项目的安全漏洞，输出 JSON 报告

:调用 GitHub API 列出最近 star 的10个仓库

:读取 data.json，找出 status 为 error 的条目并统计

:查看当前 Kubernetes 集群里所有 Pending 状态的 Pod
```

---

## 致谢

命名灵感来自 Vim 的 Ex 模式——`:` 从来都是用来执行命令的。
