@yivan-lab/pretty-please 1.0.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@yivan-lab/pretty-please",
+  "version": "1.0.0",
+  "description": "AI 驱动的命令行工具，将自然语言转换为可执行的 Shell 命令",
+  "type": "module",
+  "bin": {
+    "pls": "./dist/bin/pls.js",
+    "please": "./dist/bin/pls.js"
+  },
+  "scripts": {
+    "dev": "tsx bin/pls.tsx",
+    "build": "tsc",
+    "start": "node dist/bin/pls.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "shell",
+    "openai",
+    "command-line",
+    "natural-language",
+    "terminal",
+    "assistant",
+    "mastra",
+    "deepseek"
+  ],
+  "author": "yivan-lab",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yivan-lab/pretty-please.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yivan-lab/pretty-please/issues"
+  },
+  "homepage": "https://github.com/yivan-lab/pretty-please#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "@mastra/core": "^0.24.8",
+    "chalk": "^5.6.2",
+    "cli-highlight": "^2.1.11",
+    "commander": "^14.0.2",
+    "ink": "^6.5.1",
+    "ink-box": "^2.0.0",
+    "ink-markdown": "^1.0.4",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "lowlight": "^3.3.0",
+    "marked": "^17.0.1",
+    "openai": "^6.10.0",
+    "ora": "^9.0.0",
+    "react": "^19.2.3",
+    "shiki": "^3.20.0",
+    "string-width": "^8.1.0",
+    "wrap-ansi": "^9.0.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/node": "^25.0.2",
+    "@types/react": "^19.2.7",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/ai.js

@@ -0,0 +1,324 @@
+import OpenAI from 'openai';
+import { getConfig } from './config.js';
+import { formatSystemInfo } from './sysinfo.js';
+import { formatHistoryForAI } from './history.js';
+import { formatShellHistoryForAI, getShellHistory } from './shell-hook.js';
+import { getChatHistory, addChatMessage } from './chat-history.js';
+
+/**
+ * 创建 OpenAI 客户端
+ */
+function createClient() {
+  const config = getConfig();
+
+  return new OpenAI({
+    apiKey: config.apiKey,
+    baseURL: config.baseUrl
+  });
+}
+
+/**
+ * 生成系统提示词
+ * @param {string} sysinfo - 系统信息
+ * @param {string} plsHistory - pls 命令历史
+ * @param {string} shellHistory - shell 终端历史
+ * @param {boolean} shellHookEnabled - 是否启用了 shell hook
+ */
+function buildSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled) {
+  let prompt = `你是一个专业的 shell 脚本生成器。用户会提供他们的系统信息和一个命令需求。
+你的任务是返回一个可执行的、原始的 shell 命令或脚本来完成他们的目标。
+
+重要规则：
+1. 返回 JSON 格式，command 字段必须是可直接执行的命令（无解释、无注释、无 markdown）
+2. 不要添加 shebang（如 #!/bin/bash）
+3. command 可以包含多条命令（用 && 连接），但整体算一个命令
+4. 根据用户的系统信息选择合适的命令（如包管理器）
+5. 如果用户引用了之前的操作（如"刚才的"、"上一个"），请参考历史记录
+6. 绝对不要输出 pls 或 please 命令！
+
+【输出格式 - 非常重要】
+
+单步模式（一个命令完成）：
+如果任务只需要一个命令就能完成，只返回：
+{
+  "command": "ls -la"
+}
+
+多步模式（需要多个命令，后续依赖前面的结果）：
+如果任务需要多个命令，且后续命令必须根据前面的执行结果来决定，则返回：
+
+【多步骤完整示例】
+用户："查找大于100MB的日志文件并压缩"
+
+第一步你返回：
+{
+  "command": "find . -name '*.log' -size +100M",
+  "continue": true,
+  "reasoning": "查找大日志",
+  "nextStepHint": "压缩找到的文件"
+}
+
+执行后你会收到：
+命令已执行
+退出码: 0
+输出:
+./app.log
+./system.log
+
+然后你返回第二步：
+{
+  "command": "tar -czf logs.tar.gz ./app.log ./system.log",
+  "continue": false,
+  "reasoning": "压缩日志文件"
+}
+
+关键判断标准：
+- 多步 = 后续命令依赖前面的输出（如先 find 看有哪些，再根据结果操作具体文件）
+- 单步 = 一个命令就能完成（即使命令里有 && 连接多条，也算一个命令）
+
+常见场景举例：
+- "删除空文件夹" → 单步：find . -empty -delete （一个命令完成）
+- "查找大文件并压缩" → 多步：先 find 看有哪些，再 tar 压缩具体文件
+- "安装 git" → 单步：brew install git
+- "备份并删除旧日志" → 多步：先 mkdir backup，再 mv 文件到 backup
+- "查看目录" → 单步：ls -la
+
+严格要求：单步模式只返回 {"command": "xxx"}，绝对不要输出 continue/reasoning/nextStepHint！
+
+【错误处理】
+如果你收到命令执行失败的信息（退出码非0），你应该：
+1. 分析错误原因
+2. 调整命令策略，返回修正后的命令
+3. 设置 continue: true 重试，或设置 continue: false 放弃
+
+错误处理示例：
+上一步失败，你收到：
+命令已执行
+退出码: 1
+输出:
+mv: rename ./test.zip to ./c/test.zip: No such file or directory
+
+你分析后返回修正：
+{
+  "command": "cp test.zip a/ && cp test.zip b/ && cp test.zip c/",
+  "continue": false,
+  "reasoning": "改用 cp 复制而非 mv"
+}
+
+或者放弃：
+{
+  "command": "echo '任务无法完成：文件已被移动'",
+  "continue": false,
+  "reasoning": "文件不存在，无法继续"
+}
+
+关于 pls/please 工具：
+用户正在使用 pls（pretty-please）工具，这是一个将自然语言转换为 shell 命令的 AI 助手。
+当用户输入 "pls <描述>" 时，AI（也就是你）会生成对应的 shell 命令供用户确认执行。
+历史记录中标记为 [pls] 的条目表示用户通过 pls 工具执行的命令。
+
+用户的系统信息：${sysinfo}`;
+
+  // 根据是否启用 shell hook 决定展示哪个历史
+  if (shellHookEnabled && shellHistory) {
+    // 启用了 shell hook：只展示 shell history（已包含增强的 pls 信息）
+    prompt += `\n\n${shellHistory}`;
+  } else if (plsHistory) {
+    // 未启用 shell hook：只展示 pls history
+    prompt += `\n\n${plsHistory}`;
+  }
+
+  return prompt;
+}
+
+// 导出给其他模块使用
+export { buildSystemPrompt };
+
+/**
+ * 调用 AI 生成命令
+ * @param {string} prompt 用户输入的自然语言描述
+ * @param {object} options 选项
+ * @param {boolean} options.debug 是否返回调试信息
+ */
+export async function generateCommand(prompt, options = {}) {
+  const config = getConfig();
+  const client = createClient();
+  const sysinfo = formatSystemInfo();
+  const plsHistory = formatHistoryForAI();
+  const shellHistory = formatShellHistoryForAI();
+  const shellHookEnabled = config.shellHook && getShellHistory().length > 0;
+  const systemPrompt = buildSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled);
+
+  const response = await client.chat.completions.create({
+    model: config.model,
+    messages: [
+      {
+        role: 'system',
+        content: systemPrompt
+      },
+      {
+        role: 'user',
+        content: prompt
+      }
+    ],
+    max_tokens: 1024,
+    temperature: 0.2
+  });
+
+  const command = response.choices[0]?.message?.content?.trim();
+
+  if (!command) {
+    throw new Error('AI 返回了空的响应');
+  }
+
+  if (options.debug) {
+    return {
+      command,
+      debug: {
+        sysinfo,
+        model: config.model,
+        systemPrompt,
+        userPrompt: prompt
+      }
+    };
+  }
+
+  return command;
+}
+
+/**
+ * 生成 chat 模式的系统提示词
+ * @param {string} sysinfo - 系统信息
+ * @param {string} plsHistory - pls 命令历史
+ * @param {string} shellHistory - shell 终端历史
+ * @param {boolean} shellHookEnabled - 是否启用了 shell hook
+ */
+function buildChatSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled) {
+  let prompt = `你是一个命令行专家助手，帮助用户理解和使用命令行工具。
+
+【你的能力】
+- 解释命令的含义、参数、用法
+- 分析命令的执行效果和潜在风险
+- 回答命令行、Shell、系统管理相关问题
+- 根据用户需求推荐合适的命令并解释
+
+【回答要求】
+- 简洁清晰，避免冗余
+- 危险操作要明确警告
+- 适当给出示例命令
+- 结合用户的系统环境给出针对性建议
+
+【用户系统信息】
+${sysinfo}`;
+
+  // 根据是否启用 shell hook 决定展示哪个历史
+  if (shellHookEnabled && shellHistory) {
+    prompt += `\n\n${shellHistory}`;
+  } else if (plsHistory) {
+    prompt += `\n\n${plsHistory}`;
+  }
+
+  return prompt;
+}
+
+/**
+ * 调用 AI 进行对话（chat 模式，支持流式输出）
+ * @param {string} prompt 用户输入的问题
+ * @param {object} options 选项
+ * @param {boolean} options.debug 是否返回调试信息
+ * @param {function} options.onChunk 流式输出回调，接收每个文本片段
+ */
+export async function chatWithAI(prompt, options = {}) {
+  const config = getConfig();
+  const client = createClient();
+  const sysinfo = formatSystemInfo();
+  const plsHistory = formatHistoryForAI();
+  const shellHistory = formatShellHistoryForAI();
+  const shellHookEnabled = config.shellHook && getShellHistory().length > 0;
+  const systemPrompt = buildChatSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled);
+
+  // 获取对话历史
+  const chatHistory = getChatHistory();
+
+  // 构建消息数组
+  const messages = [
+    { role: 'system', content: systemPrompt },
+    ...chatHistory,
+    { role: 'user', content: prompt }
+  ];
+
+  // 流式输出模式
+  if (options.onChunk) {
+    const stream = await client.chat.completions.create({
+      model: config.model,
+      messages,
+      max_tokens: 2048,
+      temperature: 0.7,
+      stream: true
+    });
+
+    let fullContent = '';
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content || '';
+      if (content) {
+        fullContent += content;
+        options.onChunk(content);
+      }
+    }
+
+    if (!fullContent) {
+      throw new Error('AI 返回了空的响应');
+    }
+
+    // 保存对话历史
+    addChatMessage(prompt, fullContent);
+
+    if (options.debug) {
+      return {
+        reply: fullContent,
+        debug: {
+          sysinfo,
+          model: config.model,
+          systemPrompt,
+          chatHistory,
+          userPrompt: prompt
+        }
+      };
+    }
+
+    return fullContent;
+  }
+
+  // 非流式模式（保持兼容）
+  const response = await client.chat.completions.create({
+    model: config.model,
+    messages,
+    max_tokens: 2048,
+    temperature: 0.7
+  });
+
+  const reply = response.choices[0]?.message?.content?.trim();
+
+  if (!reply) {
+    throw new Error('AI 返回了空的响应');
+  }
+
+  // 保存对话历史
+  addChatMessage(prompt, reply);
+
+  if (options.debug) {
+    return {
+      reply,
+      debug: {
+        sysinfo,
+        model: config.model,
+        systemPrompt,
+        chatHistory,
+        userPrompt: prompt
+      }
+    };
+  }
+
+  return reply;
+}

package/src/builtin-detector.js

@@ -0,0 +1,98 @@
+/**
+ * Shell builtin 命令检测器
+ *
+ * 用于检测命令中是否包含 shell 内置命令（builtin）
+ * 这些命令在子进程中执行可能无效或行为异常
+ */
+
+// Shell 内置命令列表
+const SHELL_BUILTINS = [
+  // 目录相关
+  'cd', 'pushd', 'popd', 'dirs',
+
+  // 历史相关
+  'history',
+
+  // 别名和函数
+  'alias', 'unalias',
+
+  // 环境变量
+  'export', 'set', 'unset', 'declare', 'local', 'readonly',
+
+  // 脚本执行
+  'source', '.',
+
+  // 任务控制
+  'jobs', 'fg', 'bg', 'disown',
+
+  // 其他
+  'ulimit', 'umask', 'builtin', 'command', 'type',
+  'enable', 'hash', 'help', 'let', 'read', 'wait',
+  'eval', 'exec', 'trap', 'times', 'shopt'
+];
+
+/**
+ * 提取命令中的所有命令名
+ * @param {string} command - 完整命令字符串
+ * @returns {string[]} 命令名数组
+ */
+function extractCommandNames(command) {
+  // 按分隔符拆分（&&, ||, ;, |, &, 换行）
+  // 注意：| 是管道，两边都在子进程中执行，所以也算
+  const parts = command.split(/[;&|]+|\n+/);
+
+  const commandNames = [];
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    // 提取第一个单词（命令名）
+    // 处理 sudo、env 等前缀
+    let words = trimmed.split(/\s+/);
+
+    // 跳过 sudo、env 等
+    let i = 0;
+    while (i < words.length && ['sudo', 'env', 'nohup', 'nice'].includes(words[i])) {
+      i++;
+    }
+
+    if (i < words.length) {
+      commandNames.push(words[i]);
+    }
+  }
+
+  return commandNames;
+}
+
+/**
+ * 检测命令中是否包含 builtin
+ * @param {string} command - 要检测的命令
+ * @returns {{ hasBuiltin: boolean, builtins: string[] }} 检测结果
+ */
+export function detectBuiltin(command) {
+  const commandNames = extractCommandNames(command);
+  const foundBuiltins = [];
+
+  for (const name of commandNames) {
+    if (SHELL_BUILTINS.includes(name)) {
+      foundBuiltins.push(name);
+    }
+  }
+
+  return {
+    hasBuiltin: foundBuiltins.length > 0,
+    builtins: [...new Set(foundBuiltins)] // 去重
+  };
+}
+
+/**
+ * 格式化 builtin 列表为易读的字符串
+ * @param {string[]} builtins - builtin 命令数组
+ * @returns {string} 格式化后的字符串
+ */
+export function formatBuiltins(builtins) {
+  if (builtins.length === 0) return '';
+  if (builtins.length === 1) return builtins[0];
+  return builtins.join(', ');
+}

package/src/chat-history.js

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { getConfig } from './config.js';
+
+const CONFIG_DIR = path.join(os.homedir(), '.please');
+const CHAT_HISTORY_FILE = path.join(CONFIG_DIR, 'chat_history.json');
+
+/**
+ * 确保配置目录存在
+ */
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 读取对话历史
+ * @returns {Array<{role: string, content: string}>} messages 数组
+ */
+export function getChatHistory() {
+  ensureConfigDir();
+
+  if (!fs.existsSync(CHAT_HISTORY_FILE)) {
+    return [];
+  }
+
+  try {
+    const content = fs.readFileSync(CHAT_HISTORY_FILE, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 保存对话历史
+ * @param {Array<{role: string, content: string}>} history
+ */
+function saveChatHistory(history) {
+  ensureConfigDir();
+  fs.writeFileSync(CHAT_HISTORY_FILE, JSON.stringify(history, null, 2));
+}
+
+/**
+ * 添加一轮对话（用户问题 + AI 回答）
+ * @param {string} userMessage - 用户消息
+ * @param {string} assistantMessage - AI 回复
+ */
+export function addChatMessage(userMessage, assistantMessage) {
+  const config = getConfig();
+  const history = getChatHistory();
+
+  // 添加新的对话
+  history.push({ role: 'user', content: userMessage });
+  history.push({ role: 'assistant', content: assistantMessage });
+
+  // 计算当前轮数（每 2 条消息 = 1 轮）
+  const currentRounds = Math.floor(history.length / 2);
+  const maxRounds = config.chatHistoryLimit || 10;
+
+  // 如果超出限制，移除最早的对话
+  if (currentRounds > maxRounds) {
+    // 需要移除的轮数
+    const removeRounds = currentRounds - maxRounds;
+    // 移除最早的 N 轮（N*2 条消息）
+    history.splice(0, removeRounds * 2);
+  }
+
+  saveChatHistory(history);
+}
+
+/**
+ * 清空对话历史
+ */
+export function clearChatHistory() {
+  saveChatHistory([]);
+}
+
+/**
+ * 获取对话历史文件路径
+ */
+export function getChatHistoryFilePath() {
+  return CHAT_HISTORY_FILE;
+}
+
+/**
+ * 获取当前对话轮数
+ */
+export function getChatRoundCount() {
+  const history = getChatHistory();
+  return Math.floor(history.length / 2);
+}