Metadata-Version: 2.4
Name: shellmate-ai
Version: 0.1.0
Summary: An AI assistant for your zsh command line
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph<2.0,>=1.0
Requires-Dist: langgraph-checkpoint-sqlite<4.0,>=3.0
Requires-Dist: langchain-openai<2.0,>=1.0
Requires-Dist: pydantic<3.0,>=2.7
Dynamic: license-file

# Shellmate

🇨🇳 简体中文 | [🇬🇧 English](README.en.md)

Shellmate 是一个面向 zsh 的命令行 AI 助手。在命令行输入问题后按 **Ctrl-G**，它会结合近期命令历史，用任意 OpenAI 兼容模型（OpenAI、DeepSeek、Qwen 等）给出回答。

## 功能

- **Ctrl-G** 快捷键 — 输入问题按 Ctrl-G 提问；**空缓冲按 Ctrl-G 自动解释上一条命令**
- 自动捕获上一条命令及其退出码，失败时结合退出码定位原因
- 近期命令历史作为上下文
- OpenAI 兼容协议，支持 OpenAI / DeepSeek / Qwen 等
- 内置 DuckDuckGo 网页搜索，无需搜索 API Key
- 模型与搜索请求前自动脱敏（含高熵密钥检测）
- 本地 SQLite 保存 checkpoint，无需数据库服务

## 安装

需要 Python 3.11+。

```sh
pip install shellmate   # 或从源码：pip install -e .
shellmate init          # 创建配置 + zsh 插件 + .zshrc 加载行
source ~/.zshrc         # 或重开终端
```

## 使用

在 zsh 中输入问题，然后按 **Ctrl-G**。**空缓冲按 Ctrl-G**（命令行没有输入内容）会自动结合上一条命令及其退出码，解释它为什么失败。

```sh
shellmate ask "刚才的命令为什么失败？"              # 直接提问
shellmate ask                                      # 交互式提问
shellmate ask --history $'ls -la\ngit status' "..." # 手动传历史

# 把命令输出喂给 Shellmate 解释（管道模式）
git push origin main 2>&1 | shellmate explain
tail -200 app.log | shellmate explain "为什么一直报 timeout？"

shellmate explain-last                             # 解释上一条命令（Ctrl-G 空缓冲触发）
shellmate config-path                              # 查看配置路径
shellmate history-lines                            # 查看历史条数
```

## 配置

`shellmate init` 会创建 `~/.config/shellmate/config.json` 和 `Agent.md`。在 config.json 中填入 API Key，或用环境变量设置。

```json
{
  "llm": { "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "" },
  "shell": { "history_lines": 20 },
  "search": { "endpoint": "https://html.duckduckgo.com/html/" },
  "privacy": { "redact_secrets": true, "redact_high_entropy": true, "custom_patterns": [] }
}
```

环境变量会覆盖 JSON 配置：

| 变量 | 覆盖 |
| --- | --- |
| `OPENAI_API_KEY` / `SHELLMATE_API_KEY` | `llm.api_key` |
| `SHELLMATE_BASE_URL` | `llm.base_url` |
| `SHELLMATE_MODEL` | `llm.model` |
| `SHELLMATE_SEARCH_ENDPOINT` | `search.endpoint` |

## 架构

Agent 是一个 LangGraph 状态机：

```mermaid
flowchart TD
    Start([start]) --> SystemPrompt["system_prompt<br/>加载 Agent.md"]
    SystemPrompt --> Assistant["assistant<br/>调用模型"]
    Assistant -->|需要工具| Tools["tools<br/>网页搜索"]
    Assistant -->|结束| End([end])
    Tools --> Assistant
```

- **system_prompt** — 加载可编辑的 `Agent.md` 作为系统提示词（每个会话加载一次）
- **assistant** — 携带消息历史调用 OpenAI 兼容模型
- **tools** — 模型请求联网时执行 DuckDuckGo 搜索

## 项目结构

```text
src/shellmate/
├── agent.py           # LangGraph agent + SQLite checkpoint
├── cli.py             # 命令行入口
├── config.py          # Pydantic 配置
├── context.py         # 历史格式化
├── privacy.py         # 脱敏中间件
├── zsh_plugin.py      # 内置 zsh 插件（从 shellmate.zsh 数据文件读取）
├── shellmate.zsh      # zsh 插件（Ctrl-G / preexec / precmd）
└── tools/
    └── web_search.py  # DuckDuckGo HTML 搜索
```
