@yivan-lab/pretty-please 1.0.0 → 1.2.0

package/README.md

@@ -9,10 +9,15 @@
 - 🤖 **自然语言转命令** - 用人话说你想干什么，AI 自动生成命令
 - 🔄 **多步骤命令** - AI 自动规划多个步骤，后续命令依赖前面的执行结果
 - 🛡️ **智能错误恢复** - 命令失败时 AI 自动分析并调整策略
+- ✏️ **命令编辑** - 执行前可编辑 AI 生成的命令，支持 manual/auto 两种模式
 - 💬 **AI 对话模式** - 随时问 AI 命令怎么用
-- 📜 **历史记录** - 保存执行过的命令，方便复用
+- 🌐 **远程执行** - 通过 SSH 在远程服务器执行命令，支持密码/密钥认证
+- 📜 **三种历史记录** - 命令历史、对话历史、Shell 历史统一管理
 - 🎨 **精美界面** - 基于 React + Ink 的终端 UI，Markdown 渲染
+- 🌗 **主题切换** - 支持 dark/light 主题，适配不同终端背景
+- 🏷️ **命令别名** - 常用操作一键触发，支持参数模板
 - 🔧 **多 Provider 支持** - 支持 OpenAI、DeepSeek、Anthropic 等多种 AI
+- 🚀 **一键升级** - 内置 `pls upgrade` 命令，自动更新到最新版本
 
 ## 📦 安装
 
@@ -29,33 +34,46 @@ pnpm add -g @yivan-lab/pretty-please
 yarn global add @yivan-lab/pretty-please
 ```
 
-安装后，确保全局安装了 `tsx`：
-
-```bash
-npm install -g tsx
-# 或
-pnpm add -g tsx
-```
+安装完成后，你可以在任何目录使用 `pls` 或 `please` 命令了！
 
 ### 方式二：从源码安装
 
 ```bash
 # 克隆项目
-git clone https://github.com/yivan-lab/pretty-please.git
+git clone https://github.com/IvanLark/pretty-please.git
 cd pretty-please
 
 # 安装依赖
 pnpm install
 
+# 构建
+pnpm build
+
 # 全局链接
 pnpm link --global
-
-# 确保全局安装了 tsx
-pnpm add -g tsx
 ```
 
 安装完成后，你可以在任何目录使用 `pls` 或 `please` 命令了！
 
+### 方式三：一键安装（无需 Node.js）
+
+适用于云服务器、DevOps 场景，无需 Node.js 环境：
+
+**Linux / macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/IvanLark/pretty-please/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/IvanLark/pretty-please/main/install.ps1 | iex
+```
+
+支持的平台：
+- Linux x64 / arm64
+- macOS Intel / Apple Silicon
+- Windows x64
+
 ## 🚀 快速开始
 
 ### 1. 配置 API
@@ -159,6 +177,37 @@ pls 将 test.zip 移动到 a、b、c 三个文件夹
 
 AI 不会因为一次失败就放弃，而是理解错误原因并找到解决方案。
 
+### 命令编辑
+
+AI 生成的命令可能不完全符合你的需求，你可以在执行前编辑它：
+
+**manual 模式（默认）**：
+
+```
+┌─ 生成命令 ───────┐
+│ ls -la           │
+└──────────────────┘
+
+执行？ [回车执行 / E 编辑 / Esc 取消]
+
+# 按 E 进入编辑
+┌─ 生成命令 ───────┐
+│ ls -la           │  ← AI 建议
+└──────────────────┘
+> ls -l█            ← 可编辑
+
+[回车执行 / Esc 返回]
+```
+
+**auto 模式**：自动进入编辑，直接修改后执行
+
+```bash
+# 切换到 auto 模式
+pls config set editMode auto
+```
+
+编辑后的命令会被记录到历史中，并标注修改前后的对比。
+
 ### 对话模式：命令讲解和问答
 
 想了解某个命令怎么用？用 `pls chat` 开启对话模式：
@@ -191,16 +240,25 @@ pls chat clear
 ### 查看历史记录
 
 ```bash
-# 查看所有执行过的命令
+# 查看命令历史
 pls history
 
-# 清空历史记录
-pls history clear
+# 查看对话历史
+pls history chat
+
+# 查看 Shell 历史（需要启用 Shell Hook）
+pls history shell
+
+# 清空各种历史
+pls history clear         # 清空命令历史
+pls history chat clear    # 清空对话历史
+pls history shell clear   # 清空 Shell 历史
 ```
 
 历史记录包含：
 - 你的原始需求（自然语言）
 - AI 生成的命令
+- 用户修改后的命令（如有修改）
 - 执行状态（成功/失败/退出码）
 - 执行时间
 
@@ -222,7 +280,12 @@ pls config set <key> <value>  # 设置单个配置项
 | `provider` | AI Provider | `openai` |
 | `model` | 模型名称 | `gpt-4-turbo` |
 | `shellHook` | 启用终端历史记录 | `false` |
+| `editMode` | 命令编辑模式（manual/auto） | `manual` |
 | `chatHistoryLimit` | 对话历史保留轮数 | `10` |
+| `commandHistoryLimit` | 命令历史保留条数 | `10` |
+| `shellHistoryLimit` | Shell 历史保留条数 | `15` |
+| `theme` | 界面主题（dark/light） | `dark` |
+| `aliases` | 命令别名配置 | `{}` |
 
 ### 支持的 Provider
 
@@ -236,6 +299,154 @@ pls config set <key> <value>  # 设置单个配置项
 - `fireworks` - Fireworks AI
 - `together` - Together AI
 
+## 🌐 远程执行
+
+通过 SSH 在远程服务器上执行 AI 生成的命令，支持密码/密钥认证。
+
+### 添加远程服务器
+
+```bash
+# 使用默认密钥（~/.ssh/id_rsa）
+pls remote add myserver root@192.168.1.100
+
+# 指定端口
+pls remote add myserver root@192.168.1.100:2222
+
+# 使用指定密钥
+pls remote add myserver root@192.168.1.100 --key ~/.ssh/my_key
+
+# 使用密码认证（每次执行时输入密码）
+pls remote add myserver root@192.168.1.100 --password
+```
+
+### 管理远程服务器
+
+```bash
+pls remote                    # 查看所有服务器
+pls remote list               # 同上
+pls remote test myserver      # 测试连接并采集系统信息
+pls remote remove myserver    # 删除服务器
+```
+
+### 设置默认服务器
+
+```bash
+pls remote default myserver   # 设置默认服务器
+pls remote default            # 查看当前默认服务器
+pls remote default --clear    # 清除默认服务器
+```
+
+设置默认服务器后，使用 `-r` 参数时可以省略服务器名：
+
+```bash
+pls -r 查看磁盘使用情况        # 使用默认服务器
+```
+
+### 设置工作目录
+
+```bash
+pls remote workdir myserver /var/www    # 设置工作目录
+pls remote workdir myserver             # 查看当前工作目录
+pls remote workdir myserver --clear     # 清除工作目录
+```
+
+设置工作目录后，所有命令会自动在该目录下执行。
+
+### 远程执行命令
+
+```bash
+# 指定服务器执行
+pls -r myserver 查看磁盘使用情况
+pls -r myserver 查找大于 100MB 的日志文件
+
+# 使用默认服务器（需先设置）
+pls -r 查看当前目录的文件
+```
+
+### 批量远程执行 ⭐
+
+在多台服务器上并发执行同一个任务，每个服务器自动生成适配其环境的命令：
+
+```bash
+# 批量执行（逗号分隔服务器名）
+pls -r web1,web2,web3 查看 nginx 状态
+pls -r server1,server2 查看磁盘使用情况
+pls -r prod1,prod2,prod3 重启应用服务
+```
+
+**特点：**
+- 🚀 **并发执行** - 所有服务器同时生成命令和执行，速度快
+- 🔧 **自动适配** - 每个服务器根据其系统环境生成独立命令（支持异构环境）
+- 📊 **清晰展示** - 显示每个服务器的命令和执行结果
+- 📝 **历史记录** - 自动记录到每个服务器的历史
+
+**执行流程示例：**
+
+```bash
+$ pls -r web1,web2,web3 查看 nginx 状态
+
+正在为 3 台服务器生成命令...
+
+✓ 命令生成完成
+
+web1 (linux):
+  systemctl status nginx | grep Active
+
+web2 (linux):
+  systemctl status nginx | grep Active
+
+web3 (linux):
+  systemctl status nginx | grep Active
+
+将在 3 台服务器执行以上命令
+执行？ [回车执行 / Ctrl+C 取消]
+
+正在执行...
+
+执行完成:
+
+  ✓ web1 (退出码: 0)
+  ✓ web2 (退出码: 0)
+  ✗ web3 (退出码: 3)
+
+─── web1 ───
+   Active: active (running)
+
+─── web2 ───
+   Active: active (running)
+
+─── web3 ───
+   Active: inactive (dead)
+```
+
+**退出码：**
+- `0` - 全部成功
+- `1` - 部分失败
+- `2` - 全部失败
+
+**限制：**
+- 批量执行模式不支持多步骤命令（只生成单个命令）
+- 不支持命令编辑（直接执行生成的命令）
+
+### 远程 Shell Hook
+
+在远程服务器上安装 Shell Hook，让 AI 了解你在远程服务器上的操作历史：
+
+```bash
+pls remote hook install myserver    # 安装远程 Hook
+pls remote hook status myserver     # 查看状态
+pls remote hook uninstall myserver  # 卸载 Hook
+```
+
+### 远程历史记录
+
+```bash
+pls remote history show myserver        # 查看远程命令历史
+pls remote history clear myserver       # 清空远程命令历史
+pls remote history shell myserver       # 查看远程 Shell 历史
+pls remote history shell-clear myserver # 清空远程 Shell 历史
+```
+
 ## 🔧 Shell Hook（可选）
 
 Shell Hook 可以记录你在终端执行的所有命令，让 AI 更智能地理解上下文。
@@ -251,6 +462,97 @@ pls hook uninstall  # 卸载 hook
 - bash
 - PowerShell
 
+## 🌗 主题系统
+
+支持深色和浅色两种主题，适配不同终端背景：
+
+```bash
+pls theme              # 查看当前主题
+pls theme list         # 查看所有可用主题
+pls theme dark         # 切换到深色主题
+pls theme light        # 切换到浅色主题
+```
+
+主题说明：
+- **dark（深色）** - 明亮的颜色，适合深色终端背景（默认）
+- **light（浅色）** - 较深的颜色，适合浅色终端背景
+
+也可以通过配置命令切换：
+
+```bash
+pls config set theme light
+```
+
+## 🏷️ 命令别名
+
+将常用的操作保存为别名，一键触发：
+
+### 基本使用
+
+```bash
+# 添加简单别名
+pls alias add disk "查看磁盘使用情况，按使用率排序"
+pls alias add mem "查看内存使用最高的 10 个进程"
+
+# 使用别名（两种格式都支持）
+pls disk
+pls @disk
+
+# 查看所有别名
+pls alias
+pls alias list
+
+# 删除别名
+pls alias remove disk
+```
+
+### 参数模板
+
+支持动态参数，让别名更灵活：
+
+```bash
+# 添加带参数的别名
+pls alias add taillog "查看 {{file}} 的最后 {{lines:20}} 行日志"
+
+# 使用时传参
+pls taillog --file=/var/log/system.log                # lines 使用默认值 20
+pls taillog --file=/var/log/system.log --lines=50     # 自定义 lines
+pls taillog file=/var/log/nginx.log lines=100         # 不带 -- 也可以
+```
+
+参数格式说明：
+- `{{param}}` - 必填参数，不提供会报错
+- `{{param:default}}` - 可选参数，有默认值
+
+### 别名 + 额外描述
+
+别名后可以追加额外的描述：
+
+```bash
+pls disk 显示详情      # 等同于 pls 查看磁盘使用情况，按使用率排序 显示详情
+```
+
+## 🚀 版本升级
+
+### 自动更新提示
+
+程序会每 24 小时检查一次新版本，发现更新时在命令结束后提示：
+
+```
+⚠ 发现新版本: 1.1.0 → 1.2.0，运行 pls upgrade 更新
+```
+
+### 升级命令
+
+```bash
+# 升级到最新版本
+pls upgrade
+```
+
+升级方式：
+- **二进制安装**（curl/irm）：自动下载并替换
+- **npm 安装**：提示使用 `npm update -g @yivan-lab/pretty-please`
+
 ## 🎯 命令参考
 
 ### 基础命令
@@ -272,8 +574,12 @@ pls config list
 pls config set <key> <value>
 
 # 历史
-pls history
-pls history clear
+pls history              # 命令历史
+pls history clear        # 清空命令历史
+pls history chat         # 对话历史
+pls history chat clear   # 清空对话历史
+pls history shell        # Shell 历史
+pls history shell clear  # 清空 Shell 历史
 
 # 对话
 pls chat <问题>
@@ -284,6 +590,20 @@ pls hook
 pls hook install
 pls hook uninstall
 pls hook status
+
+# 主题
+pls theme                # 查看当前主题
+pls theme list           # 查看所有主题
+pls theme <dark|light>   # 切换主题
+
+# 别名
+pls alias                # 查看所有别名
+pls alias list           # 同上
+pls alias add <name> "<prompt>"  # 添加别名
+pls alias remove <name>  # 删除别名
+
+# 升级
+pls upgrade              # 升级到最新版本
 ```
 
 ## 🏗️ 技术架构
@@ -292,7 +612,7 @@ pls hook status
 
 - **React 19 + Ink 6** - 终端 UI 组件化框架
 - **Mastra 0.24** - AI Agent 框架，支持 Structured Output
-- **TypeScript 5.9** - 类型安全
+- **TypeScript 5.9** - 100% TypeScript，完整类型安全
 - **Zod 3.25** - Schema 验证
 - **Commander 14** - CLI 参数解析
 
@@ -303,31 +623,60 @@ pretty-please/
 ├── bin/
 │   └── pls.tsx              # 主入口
 ├── src/
-│   ├── ai.js                # OpenAI 客户端 + 提示词
-│   ├── mastra-agent.ts      # Mastra Agent 配置
+│   ├── prompts.ts           # 统一 AI 提示词管理
+│   ├── mastra-agent.ts      # Mastra Agent（命令生成）
+│   ├── mastra-chat.ts       # Mastra Chat Agent（对话模式）
 │   ├── multi-step.ts        # 多步骤命令核心
-│   ├── config.js            # 配置管理
-│   ├── history.js           # 命令历史
-│   ├── chat-history.js      # 对话历史
-│   ├── shell-hook.js        # Shell 集成
+│   ├── config.ts            # 配置管理
+│   ├── history.ts           # 命令历史
+│   ├── chat-history.ts      # 对话历史
+│   ├── shell-hook.ts        # Shell 集成
+│   ├── builtin-detector.ts  # Shell builtin 检测
+│   ├── sysinfo.ts           # 系统信息采集
+│   ├── upgrade.ts           # 版本升级模块
+│   ├── alias.ts             # 命令别名管理
 │   ├── components/          # React Ink 组件
 │   │   ├── MultiStepCommandGenerator.tsx
 │   │   ├── Chat.tsx
 │   │   ├── MarkdownDisplay.tsx
 │   │   └── ...
+│   ├── ui/
+│   │   └── theme.ts         # 主题系统
 │   └── utils/
-│       └── console.js       # 原生输出工具
+│       └── console.ts       # 原生输出工具
 ├── package.json
 └── tsconfig.json
 ```
 
 ## 🔨 开发指南
 
+### 命令版本
+
+| 命令 | 类型 | 说明 |
+|------|------|------|
+| `pls` / `please` | 生产版本 | 编译后的 JS |
+| `pls-dev` | 开发版本 | 热重载，代码修改立即生效 |
+
+### 首次设置
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 构建并链接生产版本
+pnpm build
+pnpm link --global
+
+# 3. 创建开发版本链接（需要全局安装 tsx）
+pnpm add -g tsx
+pnpm link:dev
+```
+
 ### 开发模式
 
 ```bash
-# 直接运行（热重载）
-pls <命令>
+# 使用开发命令（推荐，热重载）
+pls-dev <命令>
 
 # 或使用 dev 脚本
 pnpm dev <参数>
@@ -335,10 +684,14 @@ pnpm dev <参数>
 
 代码修改会立即生效，无需重新编译。
 
-### 编译
+### 构建和发布
 
 ```bash
+# 构建
 pnpm build
+
+# 发布到 npm（会自动先执行 build）
+npm publish
 ```
 
 ### 目录说明