vex-cli 0.1.0__tar.gz

vex_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"           # 推送 v0.1.0 这样的 tag 时触发
+  workflow_dispatch:   # 支持手动触发
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi        # 在 GitHub 仓库 Settings 中配置
+
+    permissions:
+      id-token: write        # PyPI Trusted Publisher 无需 token
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # 使用 PyPI Trusted Publisher，无需配置 API token
+        # 在 pypi.org 项目设置中添加此仓库即可
+
+  # 同时发布到 TestPyPI（用于验证）
+  test-publish:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install hatchling build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

vex_cli-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: vex-cli
+Version: 0.1.0
+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 模式——`:` 从来都是用来执行命令的。

vex_cli-0.1.0/README.md

@@ -0,0 +1,176 @@
+# 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 模式——`:` 从来都是用来执行命令的。

vex_cli-0.1.0/ex.rb

@@ -0,0 +1,44 @@
+class ExCli < Formula
+  include Language::Python::Virtualenv
+
+  desc     "Natural language CLI — type : and speak your intent"
+  homepage "https://github.com/yourusername/ex"
+  url      "https://files.pythonhosted.org/packages/.../ex-cli-0.1.0.tar.gz"
+  sha256   "FILL_IN_AFTER_PYPI_PUBLISH"
+  license  "MIT"
+
+  depends_on "python@3.11"
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  def post_install
+    ohai "ex 已安装！运行以下命令完成初始化："
+    ohai "  ex --setup"
+  end
+
+  test do
+    system "#{bin}/ex", "--version"
+  end
+end
+
+# ══════════════════════════════════════════════════════
+# 发布到 Homebrew 的步骤：
+#
+# 1. 先发布到 PyPI，获得 tar.gz 的 sha256
+#    pip download ex-cli --no-deps
+#    shasum -a 256 ex-cli-*.tar.gz
+#
+# 2. 更新上方的 url 和 sha256
+#
+# 3. 创建自己的 tap（一次性操作）：
+#    brew tap-new yourusername/homebrew-tap
+#    cp ex.rb ~/.homebrew/Library/Taps/yourusername/homebrew-tap/Formula/
+#    cd ~/.homebrew/Library/Taps/yourusername/homebrew-tap
+#    git add . && git commit -m "Add ex formula" && git push
+#
+# 4. 用户安装：
+#    brew tap yourusername/tap
+#    brew install ex
+# ══════════════════════════════════════════════════════

vex_cli-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name        = "vex-cli"
+version     = "0.1.0"
+description = "Natural language CLI — type : and speak your intent"
+readme      = "README.md"
+license     = { text = "MIT" }
+requires-python = ">=3.8"
+keywords    = ["cli", "ai", "natural-language", "vim", "shell", "vex"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Utilities",
+]
+
+# 零强制依赖——LLM 调用用标准库 urllib，可选安装
+dependencies = []
+
+[project.optional-dependencies]
+openai    = ["openai>=1.0"]
+anthropic = ["anthropic>=0.20"]
+
+[project.scripts]
+# vex = Vim Ex — 避免与系统内置 ex (Vim) 冲突
+vex = "ex_cli.main:main"
+
+[project.urls]
+Homepage   = "https://github.com/yourusername/vex"
+Repository = "https://github.com/yourusername/vex"
+Issues     = "https://github.com/yourusername/vex/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ex_cli"]
+

vex_cli-0.1.0/src/ex_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

vex_cli-0.1.0/src/ex_cli/engine.py

@@ -0,0 +1,297 @@
+"""
+ex — AI 规划与执行引擎
+"""
+
+import os, sys, json, shutil, subprocess
+from pathlib import Path
+
+# ─── 颜色 ─────────────────────────────────────────────
+R="\033[0m"; B="\033[1m"; D="\033[2m"
+CY="\033[36m"; YL="\033[33m"; GR="\033[32m"; RD="\033[31m"; WH="\033[97m"
+BG_DARK="\033[48;5;235m"; BG_ST="\033[48;5;238m"
+BG_GR="\033[42m"; BG_YL="\033[43m"
+FG_BK="\033[30m"; FG_GY="\033[90m"
+
+def tw():
+    try: return os.get_terminal_size().columns
+    except: return 80
+
+# ─── Vim 风格 UI ──────────────────────────────────────
+
+def statusline(mode="DONE", left="", right="smart-cli/ex"):
+    w = tw()
+    mc = {
+        "AI CMD":  f"{BG_GR}{FG_BK}",
+        "RUNNING": f"{BG_YL}{FG_BK}",
+        "DONE":    f"{BG_GR}{FG_BK}",
+        "ERROR":   f"\033[41m{WH}",
+    }.get(mode, f"{BG_ST}{WH}")
+
+    ml   = len(f"  {mode}  ")
+    fill = "─" * max(0, w - ml - len(left) - len(right) - 4)
+    print(f"{mc}{B}  {mode}  {R}{BG_ST}{FG_GY}  {left}{fill}{right}  {R}")
+
+def print_plan(plan: dict, user_input: str):
+    print(f"\n{D}:{user_input}{R}\n")
+    print(f"  {CY}{B}▌{R} {B}{plan.get('summary','')}{R}\n")
+
+    for s in plan.get("steps", []):
+        print(f"  {BG_DARK}{YL}  {s['id']}  {R} {WH}{s['cmd']}{R}")
+        print(f"       {D}\" {s['desc']}{R}\n")
+
+    if plan.get("pipeline"):
+        w = tw()
+        print(f"  {D}{'─'*(w-4)}{R}")
+        print(f"  {FG_GY}管道:{R}  {YL}{B}{plan['pipeline']}{R}\n")
+
+    for msg in plan.get("warnings", []):
+        print(f"  {RD}{B}W:{R}{RD}  {msg}{R}")
+    if plan.get("warnings"): print()
+
+    for alt in plan.get("alternatives", []):
+        print(f"  {CY}\"  {alt}{R}")
+    if plan.get("alternatives"): print()
+
+def print_output(text: str, max_lines: int = 25):
+    lines = text.strip().split("\n")
+    for l in lines[:max_lines]:
+        print(f"  {D}│{R} {l}")
+    if len(lines) > max_lines:
+        print(f"  {D}│ ... {len(lines)-max_lines} 行已折叠{R}")
+
+# ─── 工具知识库 ───────────────────────────────────────
+TOOLS = """
+ripgrep(rg): rg "p" path | rg --json "p" | rg -t py "p" | rg -l "p"
+fd: fd -e py . | fd -t d name | fd -e log . -x rm {}
+jq: jq '.field' | jq '.[]|.name' | jq 'select(.x>1)' | jq '{a,b}'
+yq: yq '.k' f.yaml | yq -o json f.yaml
+markitdown: markitdown in.pdf | markitdown in.docx > out.md
+pandoc: pandoc in.pdf -o out.md | pandoc in.docx -o out.md
+ffmpeg: ffmpeg -i in.mp4 -vf fps=1 frame_%04d.jpg | ffmpeg -i in.mp4 -vn out.aac
+imagemagick(magick): magick in.png out.jpg | magick mogrify -resize 50% *.jpg
+gh: gh pr list --json number,title | gh issue create -t "t" -b "b" | gh run list
+stripe: stripe listen --forward-to localhost:3000/webhook | stripe events list
+supabase: supabase start | supabase db push | supabase gen types typescript
+semgrep: semgrep --json --config auto . | jq '.results[]'
+ruff: ruff check . | ruff check --fix . | ruff check --output-format json .
+trivy: trivy fs . | trivy image nginx | trivy fs --format json . | jq '.Results[]'
+shellcheck: shellcheck -f json script.sh | jq '.'
+hyperfine: hyperfine 'cmd1' 'cmd2' | hyperfine --export-json res.json 'cmd'
+docker: docker build -t name . | docker ps --format json | jq '.' | docker logs -f id
+kubectl: kubectl get pods -o json | jq '.items[].metadata.name' | kubectl apply -f f.yaml
+ollama: ollama run llama3.2 | ollama list
+llm: llm "q" | llm -m gpt-4o "q" | cat f | llm "总结"
+uv: uv pip install pkg | uv venv | uv run script.py
+terraform: terraform init | terraform plan | terraform apply -auto-approve
+curl: curl -s url | jq '.' | curl -sX POST -H "Content-Type: application/json" -d '{}' url
+sort/awk/sed: sort -rn | awk '{print $1}' | sed 's/old/new/g'
+find: find . -size +10M | find . -mtime -7 | find . -name "*.log" -exec rm {} +
+"""
+
+SYSTEM = f"""你是 CLI 专家。根据需求输出 JSON 执行计划。
+
+工具列表：
+{TOOLS}
+
+输出格式：
+{{"summary":"一句话目标","steps":[{{"id":1,"cmd":"完整命令","desc":"说明","output_to_next":false}}],"pipeline":"管道命令或null","warnings":[],"alternatives":[]}}
+
+规则：只用上述工具，命令完整可执行，删除操作必须在warnings说明。
+"""
+
+# ─── LLM ──────────────────────────────────────────────
+def call_llm(query: str, cwd: str) -> dict:
+    prompt = f"当前目录：{cwd}\n需求：{query}"
+
+    deep = os.environ.get("DEEPSEEK_API_KEY")
+    kimi = os.environ.get("MOONSHOT_API_KEY")
+    oai  = os.environ.get("OPENAI_API_KEY")
+
+    if deep:
+        return _compat("https://api.deepseek.com", deep, "deepseek-chat", prompt)
+    if kimi:
+        return _compat("https://api.moonshot.cn/v1", kimi, "moonshot-v1-8k", prompt)
+    if oai:
+        return _compat("https://api.openai.com/v1", oai, "gpt-4o-mini", prompt)
+    return _ollama(prompt)
+
+def _compat(base, key, model, prompt):
+    import urllib.request
+    data = json.dumps({
+        "model": model,
+        "messages": [{"role":"system","content":SYSTEM},
+                     {"role":"user","content":prompt}],
+        "temperature": 0.1,
+        "response_format": {"type":"json_object"}
+    }).encode()
+    req = urllib.request.Request(
+        f"{base}/chat/completions", data=data,
+        headers={"Content-Type":"application/json",
+                 "Authorization":f"Bearer {key}"}
+    )
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return json.loads(json.loads(r.read())["choices"][0]["message"]["content"])
+
+def _ollama(prompt):
+    import urllib.request
+    data = json.dumps({
+        "model":"qwen2.5-coder:7b",
+        "prompt":f"{SYSTEM}\n\n{prompt}",
+        "stream":False,"format":"json"
+    }).encode()
+    try:
+        req = urllib.request.Request(
+            "http://localhost:11434/api/generate", data=data,
+            headers={"Content-Type":"application/json"}
+        )
+        with urllib.request.urlopen(req, timeout=60) as r:
+            return json.loads(json.loads(r.read())["response"])
+    except Exception:
+        raise RuntimeError(
+            "未找到可用的 LLM。请运行 vex --config 配置 API Key。\n\n"
+            "  免费选项：\n"
+            "  · DeepSeek  platform.deepseek.com   最便宜\n"
+            "  · Kimi      platform.moonshot.cn\n"
+            "  · Ollama    ollama.com               本地，完全免费\n"
+        )
+
+# ─── Vim 命令处理 ──────────────────────────────────────
+VIM = {
+    "q": "什么都不发生", "q!": None, "qa": None,
+    "wq": None, "x": None, "w": "已保存",
+    "noh":"(noh)", "set":"这不是 Vim", "vs":"没有窗口", "sp":"没有窗口",
+}
+
+def handle_vim(s: str) -> bool:
+    """返回 True=已处理，不需要 AI"""
+    if s.startswith("!"):
+        print(f"\n  {D}:{s}{R}")
+        subprocess.run(s[1:].strip(), shell=True)
+        print()
+        return True
+    base = s.split()[0] if s else ""
+    if base in VIM:
+        msg = VIM[base]
+        if msg:
+            print(f"\n  {D}\" {msg}{R}\n")
+        else:
+            sys.exit(0)
+        return True
+    if s.isdigit():
+        print(f"\n  {D}\" {s}G — 这不是 Vim{R}\n")
+        return True
+    return False
+
+# ─── 执行引擎 ─────────────────────────────────────────
+def missing_tools(plan):
+    builtins = {"for","while","if","echo","cat","grep","sort","awk","sed",
+                "find","wc","xargs","cut","tr","head","tail","mkdir","rm",
+                "cp","mv","chmod","curl","wget","npm","npx","pip","python3",
+                "node","go","sh","bash","printf","read","export"}
+    seen = set()
+    for s in plan.get("steps", []):
+        t = s["cmd"].split()[0].lstrip("(")
+        if t not in builtins and t not in seen:
+            if not shutil.which(t):
+                seen.add(t)
+    return list(seen)
+
+def run_cmd(cmd, cwd, stdin=None):
+    r = subprocess.run(cmd, shell=True, cwd=cwd,
+                       input=stdin, capture_output=True)
+    return r.returncode == 0, r.stdout, r.stderr
+
+def exec_pipeline(cmd, cwd):
+    ok, out, err = run_cmd(cmd, cwd)
+    if out: print_output(out.decode(errors="replace"))
+    if not ok and err:
+        print(f"\n  {RD}E:{R} {err.decode(errors='replace')[:300]}")
+    return ok
+
+def exec_steps(steps, cwd, auto=False):
+    n   = len(steps)
+    buf = None
+    for s in steps:
+        print(f"\n  {BG_ST}{YL}  {s['id']}/{n}  {R} {D}{s['desc']}{R}")
+        print(f"  {FG_GY}:{R}{WH}{s['cmd']}{R}")
+        if not auto:
+            print(f"\n  {D}[Y]执行  [n]跳过  [e]编辑  [q]退出{R}  ", end="")
+            try:    ch = input().strip().lower()
+            except: print(); return
+            if ch == "q": print(f"  {D}:q{R}\n"); return
+            if ch == "n": print(f"  {D}\" 跳过{R}"); continue
+            if ch == "e":
+                print(f"  {FG_GY}:{R}", end="")
+                nc = input().strip()
+                if nc: s["cmd"] = nc
+        ok, out, err = run_cmd(s["cmd"], cwd, buf if s.get("output_to_next") else None)
+        if out:
+            print(); print_output(out.decode(errors="replace")); buf = out
+        if not ok:
+            print(f"\n  {RD}E:{R} {err.decode(errors='replace')[:200]}")
+            if auto: return
+
+# ─── 主函数 ───────────────────────────────────────────
+def run(query: str, mode: str = "confirm"):
+    cwd = os.getcwd()
+
+    # h前缀 → dry run
+    dry = False
+    import re
+    if re.match(r'^h(elp)?\s+', query):
+        query = re.sub(r'^h(elp)?\s+', '', query)
+        dry = True
+
+    if handle_vim(query):
+        return
+
+    # 规划
+    print(f"\n  {D}:{query}{R}")
+    print(f"  {FG_GY}规划中...{R}", end="\r", flush=True)
+    try:
+        plan = call_llm(query, cwd)
+        print(f"  {'           '}\r", end="")
+    except RuntimeError as e:
+        print(f"\n  {RD}E:{R} {e}\n"); return
+    except Exception as e:
+        print(f"\n  {RD}E:{R} {e}\n"); return
+
+    print_plan(plan, query)
+
+    # 缺失工具
+    miss = missing_tools(plan)
+    if miss:
+        HINTS = {
+            "rg":"brew install ripgrep","fd":"brew install fd",
+            "bat":"brew install bat","eza":"brew install eza",
+            "jq":"brew install jq","yq":"brew install yq",
+            "semgrep":"pip install semgrep","ruff":"pip install ruff",
+            "trivy":"brew install trivy","hyperfine":"brew install hyperfine",
+        }
+        print(f"  {YL}W:{R}  未安装：{', '.join(miss)}")
+        for m in miss:
+            print(f"       {D}:!{HINTS.get(m, f'# 请安装 {m}')}{R}")
+        print()
+
+    if dry or mode == "dry":
+        print(f"  {D}\" 演习模式{R}\n"); return
+
+    has_pipe = bool(plan.get("pipeline"))
+    steps    = plan.get("steps", [])
+
+    if mode == "auto":
+        exec_pipeline(plan["pipeline"], cwd) if has_pipe else exec_steps(steps, cwd, auto=True)
+        print(); statusline("DONE", left=f" {query[:40]}"); return
+
+    if has_pipe and len(steps) > 1:
+        print(f"  {D}[p]管道执行  [s]逐步确认  [h]只看计划  [q]退出{R}  ", end="")
+        try:    ch = input().strip().lower()
+        except: print(); return
+        if ch == "q": return
+        if ch == "h": return
+        if ch == "p":
+            print(); exec_pipeline(plan["pipeline"], cwd)
+            print(); statusline("DONE", left=f" {query[:40]}"); return
+
+    exec_steps(steps, cwd)
+    print(); statusline("DONE", left=f" {query[:40]}")

vex_cli-0.1.0/src/ex_cli/main.py

@@ -0,0 +1,183 @@
+"""
+ex — 主入口
+处理 CLI 参数，分发到各子功能
+"""
+
+import sys
+import os
+
+def main():
+    args = sys.argv[1:]
+
+    # ── 管理命令 ──────────────────────────────────────
+    if not args or args[0] in ("-h", "--help"):
+        _print_help()
+        return
+
+    if args[0] in ("-v", "--version"):
+        from ex_cli import __version__
+        print(f"vex {__version__}")
+        return
+
+    if args[0] == "--setup":
+        from ex_cli.setup import run_setup
+        run_setup()
+        return
+
+    if args[0] == "--config":
+        from ex_cli.setup import run_config
+        run_config()
+        return
+
+    if args[0] == "--shell-plugin":
+        from ex_cli.setup import get_plugin_path
+        print(get_plugin_path())
+        return
+
+    if args[0] == "--update":
+        _run_update()
+        return
+
+    # ── AI 执行模式 ────────────────────────────────────
+    if args:
+        query = args[0]
+        mode  = args[1] if len(args) > 1 else "confirm"
+
+        # 首次运行检测：没有配置任何 API Key
+        if not _has_any_key():
+            _prompt_key_setup()
+            return
+
+        from ex_cli.engine import run
+        run(query, mode)
+        return
+
+    _print_help()
+
+
+def _has_any_key() -> bool:
+    """检查是否配置了任意 LLM API Key（包括本地 ollama）"""
+    import shutil
+    return bool(
+        os.environ.get("DEEPSEEK_API_KEY") or
+        os.environ.get("MOONSHOT_API_KEY") or
+        os.environ.get("OPENAI_API_KEY") or
+        os.environ.get("ANTHROPIC_API_KEY") or
+        shutil.which("ollama")   # 本地 ollama 也算
+    )
+
+
+def _prompt_key_setup():
+    """首次运行时，引导用户填入 API Key"""
+    B="\033[1m"; D="\033[2m"; R="\033[0m"
+    Y="\033[33m"; C="\033[36m"; G="\033[32m"; GY="\033[90m"
+
+    print(f"""
+{B}vex{R} 需要一个 LLM API Key 才能运行。
+
+vex 本身{B}完全免费{R}，你只需要自己的 API Key。
+以下提供商都有免费额度，按需选择：
+
+  {C}1{R}  {B}DeepSeek{R}   {GY}api.deepseek.com{R}
+         注册即送余额，¥0.001/千 tokens，最便宜
+         适合：追求低成本，国内访问稳定
+
+  {C}2{R}  {B}Kimi{R}       {GY}platform.moonshot.cn{R}
+         月之暗面，注册有免费额度
+         适合：国内用户，中文理解好
+
+  {C}3{R}  {B}OpenAI{R}     {GY}platform.openai.com{R}
+         GPT-4o-mini，按量付费
+         适合：需要最强模型效果
+
+  {C}4{R}  {B}Ollama{R}     {GY}ollama.com{R}
+         本地运行，{B}完全免费{R}，无需 API Key
+         适合：注重隐私，不想花钱
+
+""")
+
+    choice = input(f"  选择 [{C}1{R}-{C}4{R}，回车取消]: ").strip()
+    if not choice:
+        return
+
+    key_map = {
+        "1": ("DEEPSEEK_API_KEY",  "DeepSeek",  "https://platform.deepseek.com/api_keys"),
+        "2": ("MOONSHOT_API_KEY",  "Kimi",       "https://platform.moonshot.cn/console/api-keys"),
+        "3": ("OPENAI_API_KEY",    "OpenAI",     "https://platform.openai.com/api-keys"),
+    }
+
+    if choice == "4":
+        print(f"""
+  {B}安装 Ollama：{R}
+
+    curl -fsSL https://ollama.com/install.sh | sh
+    ollama run qwen2.5-coder:7b    {GY}# 拉取推荐模型（约 5GB）{R}
+
+  安装完成后重新运行 vex 即可，无需 API Key。
+""")
+        return
+
+    if choice not in key_map:
+        return
+
+    env_var, name, url = key_map[choice]
+    print(f"\n  打开以下链接获取 API Key：\n  {G}{url}{R}\n")
+
+    key = input(f"  粘贴你的 {name} API Key: ").strip()
+    if not key:
+        print(f"\n  {Y}已取消。之后运行 vex --config 重新配置。{R}\n")
+        return
+
+    # 写入 shell rc 文件
+    from ex_cli.setup import detect_shell, _set_env_in_rc
+    shell, rc_file = detect_shell()
+    _set_env_in_rc(env_var, key, rc_file)
+    os.environ[env_var] = key   # 当前进程立即生效
+
+    print(f"\n  {G}✓{R} 已保存到 {D}{rc_file}{R}")
+    print(f"\n  {D}（首次配置需要 source {rc_file} 或重开终端后永久生效）{R}")
+    print(f"\n  现在重新执行你的命令即可。\n")
+
+
+def _print_help():
+    from ex_cli import __version__
+    B="\033[1m"; D="\033[2m"; C="\033[36m"; G="\033[32m"; GY="\033[90m"; R="\033[0m"
+    print(f"""
+{B}vex{R} {D}v{__version__}{R} — 自然语言驱动 CLI   {GY}(完全免费，使用你自己的 API Key){R}
+
+{B}使用方式{R}
+  在空白行输入 {C}:{R} 进入 AI 命令模式：
+  {C}:{R}找出所有超过200行的Python文件
+  {C}:{R}把 demo.mp4 每秒截一帧
+  {C}:!{R}ls -la          {D}# 直通 shell（Vim :! 语义）{R}
+  {C}:q{R}                {D}# 什么都不发生{R}
+
+{B}命令{R}
+  vex --setup       初始化 shell 集成（首次安装后运行一次）
+  vex --config      管理 API Key / 执行模式
+  vex --version     显示版本
+
+{B}API Key{R}   {GY}vex 不收费，使用你自己的 Key{R}
+  {G}1{R}  DeepSeek   platform.deepseek.com   {D}最便宜{R}
+  {G}2{R}  Kimi       platform.moonshot.cn
+  {G}3{R}  OpenAI     platform.openai.com
+  {G}4{R}  Ollama     ollama.com              {D}本地，完全免费{R}
+
+{B}快速开始{R}
+  pipx install ex-cli
+  vex --setup
+  {D}重开终端，输入 : 即可{R}
+""")
+
+
+def _run_update():
+    import subprocess
+    print("正在更新 ex-cli ...")
+    r = subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--upgrade", "ex-cli"],
+        capture_output=True, text=True
+    )
+    if r.returncode == 0:
+        print("✓ 已更新到最新版本")
+    else:
+        print("✗ 更新失败：", r.stderr[:200])

vex_cli-0.1.0/src/ex_cli/setup.py

@@ -0,0 +1,188 @@
+"""
+vex --setup / --config
+负责 shell 集成和 LLM 配置
+"""
+
+import os
+import sys
+import shutil
+import subprocess
+from pathlib import Path
+
+# ─── 颜色 ─────────────────────────────────────────────
+B  = "\033[1m"; D  = "\033[2m"; R  = "\033[0m"
+G  = "\033[32m"; Y  = "\033[33m"; C  = "\033[36m"; RED = "\033[31m"
+
+def ok(t):   print(f"{G}✓{R} {t}")
+def info(t): print(f"{C}▷{R} {t}")
+def warn(t): print(f"{Y}⚠{R} {t}")
+def err(t):  print(f"{RED}✗{R} {t}")
+def ask(prompt): return input(f"  {D}{prompt}{R} ").strip()
+
+
+def get_plugin_path() -> str:
+    """返回 shell 插件文件的绝对路径"""
+    pkg_dir = Path(__file__).parent
+    shell   = Path(os.environ.get("SHELL", "")).name
+    if shell == "zsh":
+        return str(pkg_dir / "shell" / "vex.zsh")
+    else:
+        return str(pkg_dir / "shell" / "vex.bash")
+
+
+def detect_shell() -> tuple[str, Path]:
+    """返回 (shell名称, rc文件路径)"""
+    shell = Path(os.environ.get("SHELL", "/bin/bash")).name
+    home  = Path.home()
+    rc_map = {
+        "zsh":  home / ".zshrc",
+        "bash": home / ".bashrc",
+        "fish": home / ".config/fish/config.fish",
+    }
+    rc = rc_map.get(shell, home / ".bashrc")
+    return shell, rc
+
+
+def run_setup():
+    """首次安装向导"""
+    print(f"\n{B}vex 初始化向导{R}")
+    print(f"{D}vex 本身完全免费，使用你自己的 API Key{R}\n")
+
+    # 1. 检测 shell
+    shell, rc_file = detect_shell()
+    info(f"Shell：{B}{shell}{R}  配置文件：{D}{rc_file}{R}")
+
+    if shell == "fish":
+        warn("Fish shell 需要手动配置，请参考 README")
+        return
+
+    # 2. 配置 LLM
+    print(f"\n{B}选择 LLM 提供商{R}  {D}（选一个，填入你自己的 API Key）{R}\n")
+    print(f"  {C}1{R}  {B}DeepSeek{R}   platform.deepseek.com")
+    print(f"           注册即送余额，¥0.001/千 tokens，{B}最便宜{R}")
+    print()
+    print(f"  {C}2{R}  {B}Kimi{R}       platform.moonshot.cn")
+    print(f"           月之暗面，注册有免费额度，国内访问稳定")
+    print()
+    print(f"  {C}3{R}  {B}OpenAI{R}     platform.openai.com")
+    print(f"           GPT-4o-mini，按量付费，效果最强")
+    print()
+    print(f"  {C}4{R}  {B}Ollama{R}     ollama.com")
+    print(f"           本地运行，{B}完全免费{R}，无需 API Key，注重隐私")
+    print()
+    print(f"  {C}5{R}  稍后手动配置")
+    print()
+
+    choice = ask("选择 [1-5]:")
+    _configure_llm(choice, rc_file)
+
+    # 3. 写入 shell 插件
+    _install_shell_plugin(shell, rc_file)
+
+    # 4. 完成
+    print(f"\n{G}{B}✓ 初始化完成{R}\n")
+    print(f"  {D}执行以下命令立即生效：{R}")
+    print(f"  source {rc_file}\n")
+    print(f"  然后在空白行输入 {B}:{R} 即可使用\n")
+
+
+def run_config():
+    """修改已有配置"""
+    print(f"\n{B}ex 配置{R}\n")
+    shell, rc_file = detect_shell()
+
+    print(f"  {C}1{R}  更换 LLM 提供商")
+    print(f"  {C}2{R}  修改执行模式（当前：{os.environ.get('EX_MODE','confirm')}）")
+    print(f"  {C}3{R}  重新安装 Shell 插件")
+    print(f"  {C}4{R}  卸载 ex")
+
+    choice = ask("选择 [1-4]:")
+
+    if choice == "1":
+        _configure_llm(ask("LLM [1=DeepSeek 2=Kimi 3=OpenAI 4=Ollama]:"), rc_file)
+        ok("LLM 配置已更新")
+    elif choice == "2":
+        mode = ask("执行模式 [confirm/auto/dry]:")
+        if mode in ("confirm", "auto", "dry"):
+            _set_env_in_rc("EX_MODE", mode, rc_file)
+            ok(f"执行模式已设为 {mode}")
+    elif choice == "3":
+        _install_shell_plugin(shell, rc_file)
+    elif choice == "4":
+        _uninstall(rc_file)
+
+
+def _configure_llm(choice: str, rc_file: Path):
+    llm_map = {
+        "1": ("DEEPSEEK_API_KEY",  "DeepSeek", "https://platform.deepseek.com/api_keys"),
+        "2": ("MOONSHOT_API_KEY",  "Kimi",      "https://platform.moonshot.cn/console/api-keys"),
+        "3": ("OPENAI_API_KEY",    "OpenAI",    "https://platform.openai.com/api-keys"),
+    }
+    if choice in llm_map:
+        env_var, name, url = llm_map[choice]
+        print(f"\n  {G}→{R} 在浏览器中打开：{B}{url}{R}")
+        print(f"    注册/登录后创建 API Key，然后粘贴到这里\n")
+        key = ask(f"粘贴你的 {name} API Key:")
+        if key:
+            _set_env_in_rc(env_var, key, rc_file)
+            ok(f"{name} API Key 已保存")
+        else:
+            warn("未填写，跳过。之后运行 vex --config 配置。")
+    elif choice == "4":
+        print(f"\n  {B}安装 Ollama（本地免费运行）：{R}")
+        print(f"  curl -fsSL https://ollama.com/install.sh | sh")
+        print(f"  ollama run qwen2.5-coder:7b    {D}# 拉取推荐模型{R}\n")
+        if shutil.which("ollama"):
+            ok("ollama 已安装")
+            r = subprocess.run(["ollama", "list"], capture_output=True, text=True)
+            if "qwen2.5-coder" not in r.stdout:
+                info("正在拉取推荐模型（约 5GB）...")
+                subprocess.run(["ollama", "pull", "qwen2.5-coder:7b"])
+        else:
+            warn("请按上方步骤安装 ollama 后重新运行 vex --setup")
+
+
+def _install_shell_plugin(shell: str, rc_file: Path):
+    """将 source 命令写入 rc 文件"""
+    plugin_path = get_plugin_path()
+
+    # 检查是否已安装
+    if rc_file.exists() and "ex-cli" in rc_file.read_text():
+        ok(f"Shell 插件已在 {rc_file} 中")
+        return
+
+    source_line = f'source "{plugin_path}"'
+    with rc_file.open("a") as f:
+        f.write(f"\n# vex-cli: 自然语言 CLI（输入 : 触发）\n")
+        f.write(f"{source_line}\n")
+
+    ok(f"Shell 插件已写入 {rc_file}")
+
+
+def _set_env_in_rc(var: str, val: str, rc_file: Path):
+    """在 rc 文件中设置环境变量"""
+    content = rc_file.read_text() if rc_file.exists() else ""
+    line    = f'export {var}="{val}"'
+
+    if f"export {var}=" in content:
+        # 替换已有行
+        lines = content.splitlines()
+        lines = [line if l.startswith(f"export {var}=") else l for l in lines]
+        rc_file.write_text("\n".join(lines) + "\n")
+    else:
+        with rc_file.open("a") as f:
+            f.write(f"\n{line}\n")
+
+    # 立即生效（当前进程）
+    os.environ[var] = val
+
+
+def _uninstall(rc_file: Path):
+    if not rc_file.exists():
+        return
+    content = rc_file.read_text()
+    lines   = [l for l in content.splitlines()
+               if "ex-cli" not in l and "ex.zsh" not in l and "ex.bash" not in l]
+    rc_file.write_text("\n".join(lines) + "\n")
+    ok(f"已从 {rc_file} 移除 vex 配置")
+    info("运行 pipx uninstall ex-cli 完成卸载")

vex_cli-0.1.0/src/ex_cli/shell/vex.bash

@@ -0,0 +1,39 @@
+# vex.bash — 由 vex --setup 自动写入 ~/.bashrc
+
+: "${EX_MODE:=confirm}"
+: "${EX_QUIET:=0}"
+
+_EX_BIN="$(command -v vex 2>/dev/null)"
+
+_ex_readline() {
+  if [[ -n "${READLINE_LINE// /}" ]]; then
+    READLINE_LINE="${READLINE_LINE}:"; READLINE_POINT=${#READLINE_LINE}; return
+  fi
+  printf "\r\033[2K"
+  local w="${COLUMNS:-80}"
+  printf "\033[42m\033[30m\033[1m  AI CMD  \033[0m"
+  printf "\033[48;5;238m\033[90m  %-$((w-20))s  \033[0m\r" ""
+  printf "\033[1m\033[97m:\033[0m\033[97m"
+
+  local input; IFS= read -re input 2>/dev/null; printf "\033[0m"
+  [[ -z "${input// /}" ]] && { READLINE_LINE=""; return; }
+
+  case "${input}" in
+    "q"|"wq"|"w") READLINE_LINE=""; return ;;
+    "q!"|"qa"|"x") exit 0 ;;
+  esac
+
+  history -s ":${input}"
+  echo "${input}" >> "${HOME}/.vex_history"
+  echo
+  "${_EX_BIN}" "${input}" "${EX_MODE}"
+  echo
+  READLINE_LINE=""; READLINE_POINT=0
+}
+
+bind -x '":":_ex_readline'
+
+function : () { [[ -z "$*" ]] && return; "${_EX_BIN}" "$*" "${EX_MODE}"; }
+
+[[ "${EX_QUIET}" != "1" && "$-" == *i* ]] && \
+  printf "\\033[90m  vex  :自然语言  :!cmd  :q\\033[0m\\n"

vex_cli-0.1.0/src/ex_cli/shell/vex.zsh

@@ -0,0 +1,89 @@
+# vex.zsh — 由 vex --setup 自动写入 ~/.zshrc
+# 不要手动编辑此文件
+
+: "${EX_MODE:=confirm}"
+: "${EX_QUIET:=0}"
+
+_EX_BIN="$(command -v vex 2>/dev/null)"
+
+_ex_widget() {
+  # 行不为空 → 插入普通冒号
+  if [[ -n "${BUFFER// /}" ]]; then
+    BUFFER="${BUFFER}:"
+    CURSOR=$#BUFFER
+    return
+  fi
+
+  zle -I
+  printf "\r\033[2K"
+
+  # 状态栏
+  local w="${COLUMNS:-80}"
+  printf "\033[42m\033[30m\033[1m  AI CMD  \033[0m"
+  printf "\033[48;5;238m\033[90m  %-$((w-20))s  \033[0m\r" ""
+
+  # 命令提示符
+  printf "\033[1m\033[97m:\033[0m\033[97m"
+
+  local input
+  read -re input 2>/dev/null
+  printf "\033[0m"
+
+  # 空输入或 ESC → 取消
+  [[ -z "${input// /}" || "${input}" == $'\e' ]] && {
+    printf "\r\033[2K"; zle reset-prompt; return
+  }
+
+  # 记录历史
+  print -s ":${input}"
+  echo "${input}" >> "${HOME}/.vex_history"
+
+  # Vim 内置命令快速响应
+  case "${input}" in
+    "q"|"wq"|"w")
+      printf "\r\033[2K\033[90m  \" (${input})\033[0m\n"
+      zle reset-prompt; return ;;
+    "q!"|"qa"|"x")
+      exit 0 ;;
+  esac
+
+  echo
+  "${_EX_BIN}" "${input}" "${EX_MODE}"
+  echo
+  zle reset-prompt
+}
+
+zle -N _ex_widget
+bindkey ':' _ex_widget
+
+# Ctrl+: → 自动执行模式
+_ex_auto_widget() {
+  [[ -n "${BUFFER// /}" ]] && { BUFFER="${BUFFER}:"; CURSOR=$#BUFFER; return; }
+
+  zle -I; printf "\r\033[2K"
+  local w="${COLUMNS:-80}"
+  printf "\033[43m\033[30m\033[1m  AUTO  \033[0m"
+  printf "\033[48;5;238m\033[90m  %-$((w-18))s  \033[0m\r" ""
+  printf "\033[1m\033[33m:\033[0m\033[97m"
+
+  local input
+  read -re input 2>/dev/null
+  printf "\033[0m"
+  [[ -z "${input// /}" ]] && { zle reset-prompt; return; }
+
+  print -s ":${input}!"
+  echo
+  "${_EX_BIN}" "${input}" "auto"
+  echo
+  zle reset-prompt
+}
+zle -N _ex_auto_widget
+
+# : 函数（命令行直接调用）
+function : () {
+  [[ -z "$*" ]] && return
+  "${_EX_BIN}" "$*" "${EX_MODE}"
+}
+
+[[ "${EX_QUIET}" != "1" && -o interactive ]] && \
+  printf "\\033[90m  vex  :自然语言  :!cmd  :q\\033[0m\\n"