@yivan-lab/pretty-please 1.0.0 → 1.2.0

package/dist/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "@yivan-lab/pretty-please",
+    "version": "1.2.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 && node scripts/postbuild.js",
+        "start": "node dist/bin/pls.js",
+        "link:dev": "mkdir -p ~/.local/bin && ln -sf \"$(pwd)/bin/pls.tsx\" ~/.local/bin/pls-dev && echo '✅ pls-dev 已链接到 ~/.local/bin/pls-dev'",
+        "unlink:dev": "rm -f ~/.local/bin/pls-dev && echo '✅ pls-dev 已移除'",
+        "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/IvanLark/pretty-please.git"
+    },
+    "bugs": {
+        "url": "https://github.com/IvanLark/pretty-please/issues"
+    },
+    "homepage": "https://github.com/IvanLark/pretty-please#readme",
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "bin",
+        "dist/bin",
+        "dist/src",
+        "dist/package.json",
+        "src",
+        "README.md",
+        "LICENSE",
+        "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",
+        "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",
+        "react-devtools-core": "^7.0.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    }
+}

package/dist/src/ai.d.ts

@@ -1,45 +1,5 @@
 /**
- * 调用 AI 生成命令
- * @param {string} prompt 用户输入的自然语言描述
- * @param {object} options 选项
- * @param {boolean} options.debug 是否返回调试信息
- */
-export function generateCommand(prompt: string, options?: {
-    debug: boolean;
-}): Promise<string | {
-    command: string;
-    debug: {
-        sysinfo: string;
-        model: any;
-        systemPrompt: string;
-        userPrompt: string;
-    };
-}>;
-/**
- * 调用 AI 进行对话（chat 模式，支持流式输出）
- * @param {string} prompt 用户输入的问题
- * @param {object} options 选项
- * @param {boolean} options.debug 是否返回调试信息
- * @param {function} options.onChunk 流式输出回调，接收每个文本片段
- */
-export function chatWithAI(prompt: string, options?: {
-    debug: boolean;
-    onChunk: Function;
-}): Promise<string | {
-    reply: string;
-    debug: {
-        sysinfo: string;
-        model: any;
-        systemPrompt: string;
-        chatHistory: {
-            role: string;
-            content: string;
-        }[];
-        userPrompt: string;
-    };
-}>;
-/**
- * 生成系统提示词
+ * 生成命令生成模式的系统提示词
  * @param {string} sysinfo - 系统信息
  * @param {string} plsHistory - pls 命令历史
  * @param {string} shellHistory - shell 终端历史

package/dist/src/ai.js

@@ -1,27 +1,11 @@
-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) {
+export function buildSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled) {
     let prompt = `你是一个专业的 shell 脚本生成器。用户会提供他们的系统信息和一个命令需求。
 你的任务是返回一个可执行的、原始的 shell 命令或脚本来完成他们的目标。
 
@@ -51,8 +35,8 @@ function buildSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled)
 {
   "command": "find . -name '*.log' -size +100M",
   "continue": true,
-  "reasoning": "查找大日志",
-  "nextStepHint": "压缩找到的文件"
+  "reasoning": "查找大日志", （精简即可）
+  "nextStepHint": "压缩找到的文件" （精简即可）
 }
 
 执行后你会收到：
@@ -102,13 +86,15 @@ mv: rename ./test.zip to ./c/test.zip: No such file or directory
   "reasoning": "改用 cp 复制而非 mv"
 }
 
-或者放弃：
+或者如果决定放弃（无法修正），返回：
 {
-  "command": "echo '任务无法完成：文件已被移动'",
+  "command": "",
   "continue": false,
-  "reasoning": "文件不存在，无法继续"
+  "reasoning": "文件不存在且无法恢复，任务无法继续"
 }
 
+重要：当 continue: false 且决定放弃时，command 可以留空，重点是在 reasoning 中说明为什么放弃。
+
 关于 pls/please 工具：
 用户正在使用 pls（pretty-please）工具，这是一个将自然语言转换为 shell 命令的 AI 助手。
 当用户输入 "pls <描述>" 时，AI（也就是你）会生成对应的 shell 命令供用户确认执行。
@@ -126,170 +112,3 @@ mv: rename ./test.zip to ./c/test.zip: No such file or directory
     }
     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/dist/src/alias.d.ts

@@ -0,0 +1,41 @@
+import { type AliasConfig } from './config.js';
+/**
+ * 别名解析结果
+ */
+export interface AliasResolveResult {
+    resolved: boolean;
+    prompt: string;
+    aliasName?: string;
+    originalInput?: string;
+}
+/**
+ * 获取所有别名
+ */
+export declare function getAliases(): Record<string, AliasConfig>;
+/**
+ * 添加别名
+ * @param name 别名名称
+ * @param prompt 对应的 prompt
+ * @param description 可选描述
+ * @param reservedCommands 保留的子命令列表（动态传入）
+ */
+export declare function addAlias(name: string, prompt: string, description?: string, reservedCommands?: string[]): void;
+/**
+ * 删除别名
+ */
+export declare function removeAlias(name: string): boolean;
+/**
+ * 解析别名
+ * 支持 `pls disk` 和 `pls @disk` 两种格式
+ * @param input 用户输入（可能是别名或普通 prompt）
+ * @returns 解析结果
+ */
+export declare function resolveAlias(input: string): AliasResolveResult;
+/**
+ * 显示所有别名
+ */
+export declare function displayAliases(): void;
+/**
+ * 获取别名的参数信息（用于帮助显示）
+ */
+export declare function getAliasParams(aliasName: string): string[];

package/dist/src/alias.js

@@ -0,0 +1,240 @@
+import chalk from 'chalk';
+import { getConfig, saveConfig } from './config.js';
+import { getCurrentTheme } from './ui/theme.js';
+// 获取主题颜色
+function getColors() {
+    const theme = getCurrentTheme();
+    return {
+        primary: theme.primary,
+        secondary: theme.secondary,
+        success: theme.success,
+        error: theme.error,
+        warning: theme.warning,
+        muted: theme.text.muted,
+    };
+}
+/**
+ * 获取所有别名
+ */
+export function getAliases() {
+    const config = getConfig();
+    return config.aliases || {};
+}
+/**
+ * 添加别名
+ * @param name 别名名称
+ * @param prompt 对应的 prompt
+ * @param description 可选描述
+ * @param reservedCommands 保留的子命令列表（动态传入）
+ */
+export function addAlias(name, prompt, description, reservedCommands = []) {
+    // 验证别名名称
+    if (!name || !name.trim()) {
+        throw new Error('别名名称不能为空');
+    }
+    // 移除可能的 @ 前缀
+    const aliasName = name.startsWith('@') ? name.slice(1) : name;
+    // 验证别名名称格式（只允许字母、数字、下划线、连字符）
+    if (!/^[a-zA-Z0-9_-]+$/.test(aliasName)) {
+        throw new Error('别名名称只能包含字母、数字、下划线和连字符');
+    }
+    // 检查是否与保留命令冲突
+    if (reservedCommands.includes(aliasName)) {
+        throw new Error(`"${aliasName}" 是保留的子命令，不能用作别名`);
+    }
+    // 验证 prompt
+    if (!prompt || !prompt.trim()) {
+        throw new Error('prompt 不能为空');
+    }
+    const config = getConfig();
+    if (!config.aliases) {
+        config.aliases = {};
+    }
+    config.aliases[aliasName] = {
+        prompt: prompt.trim(),
+        description: description?.trim(),
+    };
+    saveConfig(config);
+}
+/**
+ * 删除别名
+ */
+export function removeAlias(name) {
+    // 移除可能的 @ 前缀
+    const aliasName = name.startsWith('@') ? name.slice(1) : name;
+    const config = getConfig();
+    if (!config.aliases || !config.aliases[aliasName]) {
+        return false;
+    }
+    delete config.aliases[aliasName];
+    saveConfig(config);
+    return true;
+}
+/**
+ * 解析参数模板
+ * 支持格式：{{param}} 或 {{param:default}}
+ */
+function parseTemplateParams(prompt) {
+    const regex = /\{\{([^}:]+)(?::[^}]*)?\}\}/g;
+    const params = [];
+    let match;
+    while ((match = regex.exec(prompt)) !== null) {
+        if (!params.includes(match[1])) {
+            params.push(match[1]);
+        }
+    }
+    return params;
+}
+/**
+ * 替换模板参数
+ * @param prompt 原始 prompt（可能包含模板参数）
+ * @param args 用户提供的参数（key=value 或 --key=value 格式）
+ */
+function replaceTemplateParams(prompt, args) {
+    // 解析用户参数
+    const userParams = {};
+    for (const arg of args) {
+        // 支持 --key=value 或 key=value 格式
+        const cleanArg = arg.startsWith('--') ? arg.slice(2) : arg;
+        const eqIndex = cleanArg.indexOf('=');
+        if (eqIndex > 0) {
+            const key = cleanArg.slice(0, eqIndex);
+            const value = cleanArg.slice(eqIndex + 1);
+            userParams[key] = value;
+        }
+    }
+    // 替换模板参数
+    let result = prompt;
+    // 匹配 {{param}} 或 {{param:default}}
+    result = result.replace(/\{\{([^}:]+)(?::([^}]*))?\}\}/g, (match, param, defaultValue) => {
+        if (userParams[param] !== undefined) {
+            return userParams[param];
+        }
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        // 没有提供值也没有默认值，保留原样（后面会报错或让用户补充）
+        return match;
+    });
+    return result;
+}
+/**
+ * 检查是否还有未替换的模板参数
+ */
+function hasUnresolvedParams(prompt) {
+    const regex = /\{\{([^}:]+)\}\}/g;
+    const unresolved = [];
+    let match;
+    while ((match = regex.exec(prompt)) !== null) {
+        unresolved.push(match[1]);
+    }
+    return unresolved;
+}
+/**
+ * 解析别名
+ * 支持 `pls disk` 和 `pls @disk` 两种格式
+ * @param input 用户输入（可能是别名或普通 prompt）
+ * @returns 解析结果
+ */
+export function resolveAlias(input) {
+    const parts = input.trim().split(/\s+/);
+    if (parts.length === 0) {
+        return { resolved: false, prompt: input };
+    }
+    let aliasName = parts[0];
+    const restArgs = parts.slice(1);
+    // 支持 @ 前缀
+    if (aliasName.startsWith('@')) {
+        aliasName = aliasName.slice(1);
+    }
+    const aliases = getAliases();
+    const aliasConfig = aliases[aliasName];
+    if (!aliasConfig) {
+        return { resolved: false, prompt: input };
+    }
+    // 检查是否有模板参数
+    const templateParams = parseTemplateParams(aliasConfig.prompt);
+    let resolvedPrompt;
+    if (templateParams.length > 0) {
+        // 有模板参数，进行替换
+        resolvedPrompt = replaceTemplateParams(aliasConfig.prompt, restArgs);
+        // 检查是否还有未替换的必填参数
+        const unresolved = hasUnresolvedParams(resolvedPrompt);
+        if (unresolved.length > 0) {
+            throw new Error(`别名 "${aliasName}" 缺少必填参数: ${unresolved.join(', ')}`);
+        }
+        // 过滤掉已用于参数替换的 args，剩余的追加到 prompt
+        const usedArgs = restArgs.filter((arg) => {
+            const cleanArg = arg.startsWith('--') ? arg.slice(2) : arg;
+            return cleanArg.includes('=');
+        });
+        const extraArgs = restArgs.filter((arg) => !usedArgs.includes(arg));
+        if (extraArgs.length > 0) {
+            resolvedPrompt = `${resolvedPrompt} ${extraArgs.join(' ')}`;
+        }
+    }
+    else {
+        // 没有模板参数，直接追加额外内容
+        if (restArgs.length > 0) {
+            resolvedPrompt = `${aliasConfig.prompt} ${restArgs.join(' ')}`;
+        }
+        else {
+            resolvedPrompt = aliasConfig.prompt;
+        }
+    }
+    return {
+        resolved: true,
+        prompt: resolvedPrompt,
+        aliasName,
+        originalInput: input,
+    };
+}
+/**
+ * 显示所有别名
+ */
+export function displayAliases() {
+    const aliases = getAliases();
+    const colors = getColors();
+    const aliasNames = Object.keys(aliases);
+    console.log('');
+    if (aliasNames.length === 0) {
+        console.log(chalk.gray('  暂无别名'));
+        console.log('');
+        console.log(chalk.gray('  使用 pls alias add <name> "<prompt>" 添加别名'));
+        console.log('');
+        return;
+    }
+    console.log(chalk.bold('命令别名:'));
+    console.log(chalk.gray('━'.repeat(50)));
+    for (const name of aliasNames) {
+        const alias = aliases[name];
+        const params = parseTemplateParams(alias.prompt);
+        // 别名名称
+        let line = `  ${chalk.hex(colors.primary)(name)}`;
+        // 如果有参数，显示参数
+        if (params.length > 0) {
+            line += chalk.gray(` <${params.join('> <')}>`);
+        }
+        console.log(line);
+        // prompt 内容
+        console.log(`    ${chalk.gray('→')} ${alias.prompt}`);
+        // 描述
+        if (alias.description) {
+            console.log(`    ${chalk.gray(alias.description)}`);
+        }
+        console.log('');
+    }
+    console.log(chalk.gray('━'.repeat(50)));
+    console.log(chalk.gray('使用: pls <alias> 或 pls @<alias>'));
+    console.log('');
+}
+/**
+ * 获取别名的参数信息（用于帮助显示）
+ */
+export function getAliasParams(aliasName) {
+    const aliases = getAliases();
+    const alias = aliases[aliasName];
+    if (!alias)
+        return [];
+    return parseTemplateParams(alias.prompt);
+}

package/dist/src/builtin-detector.d.ts

@@ -1,15 +1,21 @@
 /**
- * 检测命令中是否包含 builtin
- * @param {string} command - 要检测的命令
- * @returns {{ hasBuiltin: boolean, builtins: string[] }} 检测结果
+ * Shell builtin 命令检测器
+ *
+ * 用于检测命令中是否包含 shell 内置命令（builtin）
+ * 这些命令在子进程中执行可能无效或行为异常
+ */
+/**
+ * Builtin 检测结果
  */
-export function detectBuiltin(command: string): {
+export interface BuiltinResult {
     hasBuiltin: boolean;
     builtins: string[];
-};
+}
+/**
+ * 检测命令中是否包含 builtin
+ */
+export declare function detectBuiltin(command: string): BuiltinResult;
 /**
  * 格式化 builtin 列表为易读的字符串
- * @param {string[]} builtins - builtin 命令数组
- * @returns {string} 格式化后的字符串
  */
-export function formatBuiltins(builtins: string[]): string;
+export declare function formatBuiltins(builtins: string[]): string;