# zsh-pi

**Repository Path**: kristar/zsh-pi

## Basic Information

- **Project Name**: zsh-pi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zsh-pi

> 在 ZSH 中直接输入自然语言，由 AI 自动处理 — 像聊天一样用终端。

## 效果

```
$ 帮我列出当前目录的文件
zsh: command not found: 帮我列出当前目录的文件    ← 命令不存在，自动触发 AI
⠙ 思考中                                          ← spinner 动画
🔧 bash                                            ← 工具调用
  { "command": "ls -la" }
📄 total 24
  drwxr-xr-x ...

当前目录有以下文件：
  - src/
  - tests/
  - README.md
─
> ls -la
> cd src
```

- 输入 **shell 命令** → 正常执行，完全不经过 AI
- 输入 **自然语言** → 命令不存在，自动触发 AI 处理（展示 spinner、工具调用链、最终结果）
- 输出支持 **Markdown 渲染**（表格对齐、粗体、代码块）

## 安装

### 前提条件

- **Node.js 18+**
- **[pi-coding-agent](https://github.com/nicobailon/pi)** — zsh-pi 底层调用 pi 执行 AI 处理
- **AI Provider API Key** — pi 需要配置一个 AI 服务商（如 DeepSeek、OpenAI、Anthropic 等）

```bash
# 检查前置条件
node --version            # 需要 >= 18
which pi                  # 确认 pi 已安装
pi --version              # 确认版本

# 如果没有 pi，通过 brew 安装：
# brew install pi

# 配置 API Key（以 DeepSeek 为例）
export DEEPSEEK_API_KEY="sk-your-key-here"
# 或写入 ~/.pi/agent/settings.json 持久化
```

### 安装 zsh-pi

```bash
# 方式 A：通过 npm 安装（推荐）
npm install -g zsh-pi

# 方式 B：从源码安装
git clone https://gitee.com/kristar/zsh-pi.git
cd zsh-pi
npm install -g .
```

### 验证安装

```bash
zsh-pi --version     # 应输出 0.2.0
zsh-pi --help        # 应显示帮助

# 验证 AI 通路
zsh-pi process "你好，请说 hello"
# 应看到 spinner 动画 + AI 回答，说明 AI 通路正常
```

### 激活 ZSH 集成

完善 `~/.zshrc` 配置，二选一：

**方式 A：通过 eval（推荐）**
```bash
echo 'eval "$(zsh-pi init)"' >> ~/.zshrc
```

**方式 B：Oh My Zsh 插件**
```bash
mkdir -p ~/.oh-my-zsh/custom/plugins/zsh-pi
cp zsh-plugin/zsh-pi.plugin.zsh ~/.oh-my-zsh/custom/plugins/zsh-pi/
# 然后在 ~/.zshrc 的 plugins=(...) 中添加 zsh-pi
```

生效：
```bash
source ~/.zshrc
```

### 确认生效

```bash
# 输入自然语言 → 命令不存在，自动触发 AI
你好

# 正常命令 → 正常执行，不经过 AI
ls
pwd

# 手动检测
zsh-pi detect 你好    # exit 0（自然语言）
zsh-pi detect ls      # exit 1（命令）
```

> **首次使用**：`zsh-pi process` 第一次调用时 pi 需要冷启动，初始响应约 2-3 秒，后续更快。

## 使用

```bash
# 在 ZSH 中直接输入自然语言（命令不存在 → 自动触发 AI）
# $ 帮我列出当前目录的文件
# zsh: command not found: 帮我列出当前目录的文件
# → 自动调用 zsh-pi process "帮我列出当前目录的文件"
# → AI 处理并返回结果

# 或手动调用
zsh-pi process "列出当前目录的文件"
zsh-pi process "这个目录是做什么的？"
zsh-pi process "帮我安装依赖"

# 检测输入是否为自然语言（exit code 0/1）
zsh-pi detect "列出文件"      # exit 0 (是自然语言)
zsh-pi detect "ls -la"        # exit 1 (是命令)

# 管理会话
zsh-pi session start          # 开始新会话
zsh-pi session list           # 列出所有会话
zsh-pi session show <id>      # 查看会话详情
zsh-pi session clean --days 7 # 清理 7 天前的会话
zsh-pi session clean --all    # 清理所有会话

# 基于历史建议命令
zsh-pi suggest

# 选项
zsh-pi process "..." --provider deepseek --model deepseek-v4-flash
```

## 工作原理

1. **正常执行优先**：不拦截 `accept-line`，输入先当作 shell 命令执行
2. **命令不存在时自动触发 AI**：zsh 的 `command_not_found_handler` 捕获不存在命令，调用 `zsh-pi process` 交给 AI 处理
3. `zsh-pi process` 调用 `pi --mode json -p`，流式解析 JSONL 事件
4. 终端输出 spinner 动画 → 工具调用 → 工具结果 → AI 回复
5. 回复内容经过 Markdown→ANSI 渲染（表格对齐、粗体、代码块等）
6. 每次交互保存到 `~/.zsh-pi/sessions/` 的 JSONL 文件中
7. 向 AI 注入最近 shell 命令历史和之前对话上下文

## 配置

zsh-pi 使用 pi-coding-agent 的配置（provider、model 等），无独立配置文件。
可通过 `--provider` 和 `--model` 全局标志覆盖。

会话文件存储在 `~/.zsh-pi/sessions/`，每终端启动一个独立会话。

## 命令参考

```
zsh-pi process <text>           处理自然语言输入（核心）
zsh-pi detect <text>            检测是否为自然语言
zsh-pi init                     输出 ZSH 集成代码
zsh-pi session start            开始新会话
zsh-pi session list             列出所有会话
zsh-pi session show <id>        查看会话详情
zsh-pi session clean [opts]     清理历史会话
zsh-pi suggest [--cwd <dir>]    基于历史建议命令
zsh-pi --help                   显示帮助
zsh-pi --version                显示版本
```

## 会话管理

```bash
# 清理 30 天前的会话
zsh-pi session clean --days 30

# 预览要清理的文件（不实际删除）
zsh-pi session clean --dry-run

# 清理所有
zsh-pi session clean --all
```

## 卸载

```bash
npm uninstall -g zsh-pi
# 同时从 .zshrc 中移除 'eval "$(zsh-pi init)"' 行
# 或从 plugins=(...) 中移除 zsh-pi
```

## License

MIT