@yivan-lab/pretty-please 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yivan-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+# Pretty Please (pls)
+
+> 让 AI 把自然语言变成 Shell 命令
+
+一个 AI 驱动的命令行工具，用自然语言描述你想做什么，AI 帮你生成并执行对应的 Shell 命令。
+
+## ✨ 特性
+
+- 🤖 **自然语言转命令** - 用人话说你想干什么，AI 自动生成命令
+- 🔄 **多步骤命令** - AI 自动规划多个步骤，后续命令依赖前面的执行结果
+- 🛡️ **智能错误恢复** - 命令失败时 AI 自动分析并调整策略
+- 💬 **AI 对话模式** - 随时问 AI 命令怎么用
+- 📜 **历史记录** - 保存执行过的命令，方便复用
+- 🎨 **精美界面** - 基于 React + Ink 的终端 UI，Markdown 渲染
+- 🔧 **多 Provider 支持** - 支持 OpenAI、DeepSeek、Anthropic 等多种 AI
+
+## 📦 安装
+
+### 方式一：npm/pnpm 全局安装（推荐）
+
+```bash
+# 使用 npm
+npm install -g @yivan-lab/pretty-please
+
+# 或使用 pnpm
+pnpm add -g @yivan-lab/pretty-please
+
+# 或使用 yarn
+yarn global add @yivan-lab/pretty-please
+```
+
+安装后，确保全局安装了 `tsx`：
+
+```bash
+npm install -g tsx
+# 或
+pnpm add -g tsx
+```
+
+### 方式二：从源码安装
+
+```bash
+# 克隆项目
+git clone https://github.com/yivan-lab/pretty-please.git
+cd pretty-please
+
+# 安装依赖
+pnpm install
+
+# 全局链接
+pnpm link --global
+
+# 确保全局安装了 tsx
+pnpm add -g tsx
+```
+
+安装完成后，你可以在任何目录使用 `pls` 或 `please` 命令了！
+
+## 🚀 快速开始
+
+### 1. 配置 API
+
+首次使用需要配置 AI API：
+
+```bash
+pls config
+```
+
+会启动交互式配置向导，按提示输入：
+- **Provider**: openai / deepseek / anthropic 等（默认 openai）
+- **Base URL**: API 地址
+- **API Key**: 你的 API 密钥
+- **Model**: 模型名称（如 gpt-4-turbo / deepseek-chat）
+- **Shell Hook**: 是否启用Shell Hook（Shell Hook 可以记录你在终端执行的历史命令，让 AI 更智能地理解上下文，推荐启用）
+
+### 2. 开始使用
+
+```bash
+# 生成并执行命令
+pls 查看当前目录
+
+# 复杂任务（多步骤）
+pls 查找大于100MB的日志文件并压缩
+
+# AI 对话模式
+pls chat grep 命令怎么用
+```
+
+## 📖 使用示例
+
+### 单步命令
+
+最基础的用法，用自然语言描述你想做什么：
+
+```bash
+pls 查看当前目录
+pls 安装 git
+pls 查看当前 IP 地址
+pls 删除所有 .DS_Store 文件
+```
+
+AI 会生成对应的命令，你确认后执行。
+
+### 多步骤命令
+
+对于需要多个步骤的复杂任务，AI 会自动规划并逐步执行：
+
+```bash
+pls 查找大于100MB的日志文件并压缩
+```
+
+执行过程：
+1. **步骤 1**: AI 生成 `find . -name '*.log' -size +100M` 查找大文件
+2. 你确认后执行，找到了 `app.log` 和 `system.log`
+3. **步骤 2**: AI 根据上一步的输出，生成 `tar -czf logs.tar.gz app.log system.log` 压缩命令
+4. 完成！
+
+每步执行后，AI 会根据实际输出结果智能地决定下一步怎么做。
+
+### 智能引用历史
+
+AI 能记住你执行过的命令，支持引用之前的操作：
+
+```bash
+# 第一步：创建文件
+pls 创建一个名为 test.txt 的文件
+
+# 第二步：引用刚才的操作
+pls 删除刚才创建的文件
+# AI 会知道你说的是 test.txt
+
+# 或者手动执行了某个命令
+mkdir my-project
+cd my-project
+
+# 然后让 AI 基于当前上下文工作
+pls 在这个目录初始化 git 仓库
+```
+
+支持的引用方式：
+- "刚才的文件"
+- "上一个命令"
+- "刚创建的目录"
+- AI 会自动从历史记录中提取相关信息
+
+### 错误恢复
+
+命令执行失败？AI 会自动分析并调整策略：
+
+```bash
+pls 将 test.zip 移动到 a、b、c 三个文件夹
+```
+
+执行过程：
+1. **步骤 1**: `mv test.zip a/` ✓ 成功
+2. **步骤 2**: `mv test.zip b/` ✗ 失败（文件已被移走）
+3. AI 分析错误，调整策略
+4. **步骤 3**: `cp a/test.zip b/ && cp a/test.zip c/` ✓ 改用复制
+
+AI 不会因为一次失败就放弃，而是理解错误原因并找到解决方案。
+
+### 对话模式：命令讲解和问答
+
+想了解某个命令怎么用？用 `pls chat` 开启对话模式：
+
+```bash
+# 询问命令用法
+pls chat tar 命令怎么用
+
+# 解释刚才执行的命令
+pls 找到所有 node_modules 目录并计算大小
+pls chat 刚才那个命令是干嘛的？
+# AI 会详细解释刚才生成的命令的含义和参数
+
+# 提问题
+pls chat 如何批量重命名文件
+pls chat grep 和 awk 有什么区别
+pls chat 如何在 Linux 下挂载硬盘
+
+# 清空对话历史
+pls chat clear
+```
+
+`pls chat` 的特点：
+- 📖 **命令讲解** - 解释命令的含义、参数、用法
+- 💡 **问题解答** - 回答 Shell、Linux、命令行相关问题
+- 🎯 **上下文感知** - 能引用你刚才执行的命令
+- 📝 **Markdown 渲染** - 支持代码高亮、表格、列表等精美格式
+- 💬 **连续对话** - 保留历史，可以追问和深入讨论
+
+### 查看历史记录
+
+```bash
+# 查看所有执行过的命令
+pls history
+
+# 清空历史记录
+pls history clear
+```
+
+历史记录包含：
+- 你的原始需求（自然语言）
+- AI 生成的命令
+- 执行状态（成功/失败/退出码）
+- 执行时间
+
+## ⚙️ 配置管理
+
+```bash
+pls config           # 交互式配置向导
+pls config list      # 查看当前配置
+pls config show      # 同上
+pls config set <key> <value>  # 设置单个配置项
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `apiKey` | AI API 密钥 | - |
+| `baseUrl` | API 基础 URL | `https://api.openai.com/v1` |
+| `provider` | AI Provider | `openai` |
+| `model` | 模型名称 | `gpt-4-turbo` |
+| `shellHook` | 启用终端历史记录 | `false` |
+| `chatHistoryLimit` | 对话历史保留轮数 | `10` |
+
+### 支持的 Provider
+
+- `openai` - OpenAI GPT 系列
+- `deepseek` - DeepSeek
+- `anthropic` - Claude
+- `google` - Gemini
+- `groq` - Groq
+- `mistral` - Mistral AI
+- `cohere` - Cohere
+- `fireworks` - Fireworks AI
+- `together` - Together AI
+
+## 🔧 Shell Hook（可选）
+
+Shell Hook 可以记录你在终端执行的所有命令，让 AI 更智能地理解上下文。
+
+```bash
+pls hook install    # 安装 hook
+pls hook status     # 查看状态
+pls hook uninstall  # 卸载 hook
+```
+
+支持的 Shell：
+- zsh
+- bash
+- PowerShell
+
+## 🎯 命令参考
+
+### 基础命令
+
+```bash
+pls <自然语言描述>      # 生成并执行命令
+pls -d <描述>           # Debug 模式（显示完整提示词）
+pls --debug <描述>      # 同上
+pls -v                  # 查看版本
+pls -h                  # 查看帮助
+```
+
+### 子命令
+
+```bash
+# 配置
+pls config
+pls config list
+pls config set <key> <value>
+
+# 历史
+pls history
+pls history clear
+
+# 对话
+pls chat <问题>
+pls chat clear
+
+# Shell Hook
+pls hook
+pls hook install
+pls hook uninstall
+pls hook status
+```
+
+## 🏗️ 技术架构
+
+### 核心技术栈
+
+- **React 19 + Ink 6** - 终端 UI 组件化框架
+- **Mastra 0.24** - AI Agent 框架，支持 Structured Output
+- **TypeScript 5.9** - 类型安全
+- **Zod 3.25** - Schema 验证
+- **Commander 14** - CLI 参数解析
+
+## 📁 目录结构
+
+```
+pretty-please/
+├── bin/
+│   └── pls.tsx              # 主入口
+├── src/
+│   ├── ai.js                # OpenAI 客户端 + 提示词
+│   ├── mastra-agent.ts      # Mastra Agent 配置
+│   ├── multi-step.ts        # 多步骤命令核心
+│   ├── config.js            # 配置管理
+│   ├── history.js           # 命令历史
+│   ├── chat-history.js      # 对话历史
+│   ├── shell-hook.js        # Shell 集成
+│   ├── components/          # React Ink 组件
+│   │   ├── MultiStepCommandGenerator.tsx
+│   │   ├── Chat.tsx
+│   │   ├── MarkdownDisplay.tsx
+│   │   └── ...
+│   └── utils/
+│       └── console.js       # 原生输出工具
+├── package.json
+└── tsconfig.json
+```
+
+## 🔨 开发指南
+
+### 开发模式
+
+```bash
+# 直接运行（热重载）
+pls <命令>
+
+# 或使用 dev 脚本
+pnpm dev <参数>
+```
+
+代码修改会立即生效，无需重新编译。
+
+### 编译
+
+```bash
+pnpm build
+```
+
+### 目录说明
+
+- 配置文件：`~/.please/config.json`
+- 命令历史：`~/.please/history.json`
+- 对话历史：`~/.please/chat_history.json`
+- Shell 历史：`~/.please/shell_history.jsonl`
+
+## 🐛 常见问题
+
+### 为什么 Chat 会清空终端历史？
+
+这是 Ink 的设计局限。我们采用了混合渲染模式，命令执行使用原生输出来保留历史，只有 Chat 模式会清空。
+
+### AI 返回的命令格式不对？
+
+如果遇到 AI 不遵守格式的情况，可以：
+1. 使用 `--debug` 查看完整提示词
+2. 检查 provider 和 model 配置是否正确
+3. 某些模型需要 `jsonPromptInjection`（代码已自动处理）
+
+### 为什么要用 Zod 3.x？
+
+AI SDK 和 Mastra 依赖 Zod 3.23.8+，Zod 4.x 有 breaking changes 不兼容。
+
+## 📄 许可证
+
+MIT
+
+## 🙏 致谢
+
+- [fuckit.sh](https://github.com/faithleysath/fuckit.sh) - 提供了最初的灵感和思路，一个优雅的 AI 命令行工具
+- [Ink](https://github.com/vadimdemedes/ink) - 终端 React 渲染器
+- [Mastra](https://mastra.ai) - AI Agent 框架
+
+---
+
+**Made with ❤️ and AI**