@yivan-lab/pretty-please 1.1.0 → 1.3.0

package/src/multi-step.ts

@@ -1,19 +1,22 @@
 import { z } from 'zod'
 import { createShellAgent } from './mastra-agent.js'
-import { buildCommandSystemPrompt } from './prompts.js'
+import { SHELL_COMMAND_SYSTEM_PROMPT, buildUserContextPrompt } from './prompts.js'
 import { formatSystemInfo } from './sysinfo.js'
 import { formatHistoryForAI } from './history.js'
 import { formatShellHistoryForAI, getShellHistory } from './shell-hook.js'
-import { getConfig } from './config.js'
+import { getConfig, type RemoteSysInfo } from './config.js'
+import { formatRemoteHistoryForAI, formatRemoteShellHistoryForAI, type RemoteShellHistoryItem } from './remote-history.js'
+import { formatRemoteSysInfoForAI } from './remote.js'
 
 /**
  * 多步骤命令的 Zod Schema
+ * 注意：optional 字段使用 .default() 是为了绕过 Mastra 0.24.8 对 optional 字段的验证 bug
  */
 export const CommandStepSchema = z.object({
   command: z.string(),
-  continue: z.boolean().optional(),  // 可选！没有 continue = 单步模式
-  reasoning: z.string().optional(),
-  nextStepHint: z.string().optional(),
+  continue: z.boolean().optional().default(false),
+  reasoning: z.string().optional().default(''),
+  nextStepHint: z.string().optional().default(''),
 })
 
 export type CommandStep = z.infer<typeof CommandStepSchema>
@@ -27,16 +30,26 @@ export interface ExecutedStep extends CommandStep {
 }
 
 /**
- * 生成系统上下文信息（供 Mastra 使用）
+ * 远程执行上下文
+ */
+export interface RemoteContext {
+  name: string
+  sysInfo: RemoteSysInfo
+  shellHistory: RemoteShellHistoryItem[]
+}
+
+/**
+ * 获取静态 System Prompt（供 Mastra 使用）
  */
 export function getFullSystemPrompt() {
-  const config = getConfig()
-  const sysinfo = formatSystemInfo()
-  const plsHistory = formatHistoryForAI()
-  const shellHistory = formatShellHistoryForAI()
-  const shellHookEnabled = config.shellHook && getShellHistory().length > 0
+  return SHELL_COMMAND_SYSTEM_PROMPT
+}
 
-  return buildCommandSystemPrompt(sysinfo, plsHistory, shellHistory, shellHookEnabled)
+/**
+ * 获取静态 System Prompt（远程执行也使用相同的 System Prompt）
+ */
+export function getRemoteFullSystemPrompt(remoteContext: RemoteContext) {
+  return SHELL_COMMAND_SYSTEM_PROMPT
 }
 
 /**
@@ -45,26 +58,39 @@ export function getFullSystemPrompt() {
 export async function generateMultiStepCommand(
   userPrompt: string,
   previousSteps: ExecutedStep[] = [],
-  options: { debug?: boolean } = {}
+  options: { debug?: boolean; remoteContext?: RemoteContext } = {}
 ): Promise<{ stepData: CommandStep; debugInfo?: any }> {
   const agent = createShellAgent()
-  const fullSystemPrompt = getFullSystemPrompt()
 
-  // 构建消息数组（string[] 格式）
-  const messages: string[] = [userPrompt]
+  // 准备动态数据
+  let sysinfoStr = ''
+  let historyStr = ''
 
-  // 添加之前步骤的执行结果
-  previousSteps.forEach((step) => {
-    messages.push(
-      JSON.stringify({
-        command: step.command,
-        continue: step.continue,
-        reasoning: step.reasoning,
-        nextStepHint: step.nextStepHint,
-      })
-    )
-    messages.push(`命令已执行\n退出码: ${step.exitCode}\n输出:\n${step.output.slice(0, 500)}`)
-  })
+  if (options.remoteContext) {
+    // 远程执行：格式化远程系统信息和历史
+    sysinfoStr = formatRemoteSysInfoForAI(options.remoteContext.name, options.remoteContext.sysInfo)
+    const plsHistory = formatRemoteHistoryForAI(options.remoteContext.name)
+    const shellHistory = formatRemoteShellHistoryForAI(options.remoteContext.shellHistory)
+    historyStr = options.remoteContext.shellHistory.length > 0 ? shellHistory : plsHistory
+  } else {
+    // 本地执行：格式化本地系统信息和历史
+    sysinfoStr = formatSystemInfo()
+    const config = getConfig()
+    const plsHistory = formatHistoryForAI()
+    const shellHistory = formatShellHistoryForAI()
+    historyStr = (config.shellHook && getShellHistory().length > 0) ? shellHistory : plsHistory
+  }
+
+  // 构建包含所有动态数据的 User Prompt（XML 格式）
+  const userContextPrompt = buildUserContextPrompt(
+    userPrompt,
+    sysinfoStr,
+    historyStr,
+    previousSteps
+  )
+
+  // 只发送一条 User Message
+  const messages = [userContextPrompt]
 
   // 调用 Mastra Agent 生成结构化输出
   const response = await agent.generate(messages, {
@@ -81,10 +107,16 @@ export async function generateMultiStepCommand(
     return {
       stepData,
       debugInfo: {
-        fullPrompt: fullSystemPrompt,
-        userPrompt,
+        systemPrompt: SHELL_COMMAND_SYSTEM_PROMPT,
+        userPrompt: userContextPrompt,
         previousStepsCount: previousSteps.length,
         response: stepData,
+        remoteContext: options.remoteContext
+          ? {
+              name: options.remoteContext.name,
+              sysInfo: options.remoteContext.sysInfo,
+            }
+          : undefined,
       },
     }
   }

package/src/prompts.ts

@@ -3,34 +3,42 @@
  */
 
 /**
- * 构建命令生成模式的系统提示词
+ * ============================================================
+ * 命令生成模式的静态 System Prompt
+ * ============================================================
+ * 包含所有核心规则、输出格式定义、判断标准、错误处理策略和示例
+ * 不包含任何动态数据（系统信息、历史记录等）
  */
-export function buildCommandSystemPrompt(
-  sysinfo: string,
-  plsHistory: string,
-  shellHistory: string,
-  shellHookEnabled: boolean
-): string {
-  let prompt = `你是一个专业的 shell 脚本生成器。用户会提供他们的系统信息和一个命令需求。
-你的任务是返回一个可执行的、原始的 shell 命令或脚本来完成他们的目标。
+export const SHELL_COMMAND_SYSTEM_PROMPT = `你是一个专业的 shell 脚本生成器。
+你将接收到包含 XML 标签的上下文信息，然后根据用户需求生成可执行的 shell 命令。
+
+### 📋 输入数据格式说明
+你会收到以下 XML 标签包裹的上下文信息：
+- <system_info>：用户的操作系统、Shell 类型、当前目录、包管理器等环境信息
+- <command_history>：用户最近执行的命令历史（用于理解上下文引用，如"刚才的文件"、"上一个命令"）
+- <execution_log>：**多步骤任务的关键信息**，记录了之前步骤的命令、退出码和输出结果
+  - 如果存在此标签，说明这是一个多步骤任务
+  - 必须检查每个 <step> 中的 <exit_code>，0=成功，非0=失败
+  - 根据 <output> 的内容决定下一步操作
+- <user_request>：用户的原始自然语言需求
 
-重要规则：
+### ⚠️ 重要规则
 1. 返回 JSON 格式，command 字段必须是可直接执行的命令（无解释、无注释、无 markdown）
 2. 不要添加 shebang（如 #!/bin/bash）
 3. command 可以包含多条命令（用 && 连接），但整体算一个命令
-4. 根据用户的系统信息选择合适的命令（如包管理器）
-5. 如果用户引用了之前的操作（如"刚才的"、"上一个"），请参考历史记录
+4. 根据 <system_info> 中的信息选择合适的命令（如包管理器）
+5. 如果用户引用了之前的操作（如"刚才的"、"上一个"），请参考 <command_history>
 6. 绝对不要输出 pls 或 please 命令！
 
-【输出格式 - 非常重要】
+### 📤 输出格式 - 非常重要
 
-单步模式（一个命令完成）：
+**单步模式（一个命令完成）：**
 如果任务只需要一个命令就能完成，只返回：
 {
   "command": "ls -la"
 }
 
-多步模式（需要多个命令，后续依赖前面的结果）：
+**多步模式（需要多个命令，后续依赖前面的结果）：**
 如果任务需要多个命令，且后续命令必须根据前面的执行结果来决定，则返回：
 
 【多步骤完整示例】
@@ -40,115 +48,265 @@ export function buildCommandSystemPrompt(
 {
   "command": "find . -name '*.log' -size +100M",
   "continue": true,
-  "reasoning": "查找大日志", （精简即可）
-  "nextStepHint": "压缩找到的文件" （精简即可）
+  "reasoning": "先查找符合条件的日志文件",
+  "nextStepHint": "根据查找结果压缩文件"
 }
 
-执行后你会收到：
-命令已执行
-退出码: 0
-输出:
+执行后你会收到（在 <execution_log> 中）：
+<execution_log>
+<step index="1">
+<command>find . -name '*.log' -size +100M</command>
+<exit_code>0</exit_code>
+<output>
 ./app.log
 ./system.log
+</output>
+</step>
+</execution_log>
 
 然后你返回第二步：
 {
   "command": "tar -czf logs.tar.gz ./app.log ./system.log",
   "continue": false,
-  "reasoning": "压缩日志文件"
+  "reasoning": "压缩找到的日志文件"
 }
 
-关键判断标准：
-- 多步 = 后续命令依赖前面的输出（如先 find 看有哪些，再根据结果操作具体文件）
-- 单步 = 一个命令就能完成（即使命令里有 && 连接多条，也算一个命令）
+### 🎯 关键判断标准
+- **多步** = 后续命令依赖前面的输出（如先 find 看有哪些，再根据结果操作具体文件）
+- **单步** = 一个命令就能完成（即使命令里有 && 连接多条，也算一个命令）
 
-常见场景举例：
-- "删除空文件夹" → 单步：find . -empty -delete （一个命令完成）
+### 📚 常见场景举例
+- "删除空文件夹" → 单步：\`find . -empty -delete\` （一个命令完成）
 - "查找大文件并压缩" → 多步：先 find 看有哪些，再 tar 压缩具体文件
-- "安装 git" → 单步：brew install git
-- "备份并删除旧日志" → 多步：先 mkdir backup，再 mv 文件到 backup
-- "查看目录" → 单步：ls -la
+- "安装 git" → 单步：\`brew install git\` 或 \`apt-get install git\`
+- "备份并删除旧日志" → 多步：先 \`mkdir backup\`，再 \`mv\` 文件到 backup
+- "查看目录" → 单步：\`ls -la\`
+- "查看磁盘使用情况并排序" → 单步：\`df -h | sort -k5 -rh\` （一个管道命令）
+- "查看进程并杀死某个进程" → 多步：先 \`ps aux | grep xxx\` 看 PID，再 \`kill\` 具体 PID
+
+**严格要求**：单步模式只返回 {"command": "xxx"}，绝对不要输出 continue/reasoning/nextStepHint！
 
-严格要求：单步模式只返回 {"command": "xxx"}，绝对不要输出 continue/reasoning/nextStepHint！
+### 🔧 错误处理策略
 
-【错误处理】
-如果你收到命令执行失败的信息（退出码非0），你应该：
-1. 分析错误原因
-2. 调整命令策略，返回修正后的命令
-3. 设置 continue: true 重试，或设置 continue: false 放弃
+**当 <execution_log> 中最后一步的 <exit_code> 不为 0 时：**
 
-错误处理示例：
-上一步失败，你收到：
-命令已执行
-退出码: 1
-输出:
-mv: rename ./test.zip to ./c/test.zip: No such file or directory
+1. **分析错误原因**：仔细阅读 <output> 中的错误信息
+2. **调整命令策略**：生成修正后的命令
+3. **决定是否继续**：
+   - 设置 \`continue: true\` 重试修正后的命令
+   - 设置 \`continue: false\` 放弃任务
+
+**错误处理示例 1：权限错误**
+<execution_log>
+<step index="1">
+<command>mkdir /var/log/myapp</command>
+<exit_code>1</exit_code>
+<output>mkdir: cannot create directory '/var/log/myapp': Permission denied</output>
+</step>
+</execution_log>
 
 你分析后返回修正：
 {
-  "command": "cp test.zip a/ && cp test.zip b/ && cp test.zip c/",
+  "command": "sudo mkdir /var/log/myapp",
+  "continue": true,
+  "reasoning": "权限不足，使用 sudo 重试"
+}
+
+**错误处理示例 2：文件不存在**
+<execution_log>
+<step index="1">
+<command>mv test.zip backup/</command>
+<exit_code>1</exit_code>
+<output>mv: cannot stat 'test.zip': No such file or directory</output>
+</step>
+</execution_log>
+
+你分析后决定放弃：
+{
+  "command": "",
   "continue": false,
-  "reasoning": "改用 cp 复制而非 mv"
+  "reasoning": "源文件 test.zip 不存在，无法移动，任务无法继续"
 }
 
-或者如果决定放弃（无法修正），返回：
+**错误处理示例 3：命令不存在，尝试安装**
+<execution_log>
+<step index="1">
+<command>docker ps</command>
+<exit_code>127</exit_code>
+<output>bash: docker: command not found</output>
+</step>
+</execution_log>
+
+你根据 <system_info> 中的包管理器返回：
+{
+  "command": "brew install docker",
+  "continue": true,
+  "reasoning": "docker 未安装，根据系统包管理器安装"
+}
+
+**错误处理示例 4：网络错误**
+<execution_log>
+<step index="1">
+<command>ping -c 3 example.com</command>
+<exit_code>2</exit_code>
+<output>ping: example.com: Name or service not known</output>
+</step>
+</execution_log>
+
+你分析后返回：
 {
   "command": "",
   "continue": false,
-  "reasoning": "文件不存在且无法恢复，任务无法继续"
+  "reasoning": "网络不可达或 DNS 解析失败，无法继续"
 }
 
-重要：当 continue: false 且决定放弃时，command 可以留空，重点是在 reasoning 中说明为什么放弃。
+### 🛑 何时应该放弃（continue: false）
+- 用户输入的路径不存在且无法推测
+- 需要的工具未安装且无法自动安装（如非 root 用户无法 apt install）
+- 权限问题且无法用 sudo 解决（如 SELinux 限制）
+- 网络不可达或 DNS 解析失败
+- 重试 2 次后仍然失败
+- 任务本身不合理（如"删除根目录"）
+
+**放弃时的要求**：
+- \`command\` 字段可以留空（""）
+- \`continue\` 必须为 false
+- \`reasoning\` 必须详细说明为什么放弃，以及尝试了什么
 
-关于 pls/please 工具：
+### 📌 关于 pls/please 工具
 用户正在使用 pls（pretty-please）工具，这是一个将自然语言转换为 shell 命令的 AI 助手。
 当用户输入 "pls <描述>" 时，AI（也就是你）会生成对应的 shell 命令供用户确认执行。
-历史记录中标记为 [pls] 的条目表示用户通过 pls 工具执行的命令。
+<command_history> 中标记为 [pls] 的条目表示用户通过 pls 工具执行的命令。
+`
 
-用户的系统信息：${sysinfo}`
+/**
+ * ============================================================
+ * 构建动态 User Prompt（XML 格式）
+ * ============================================================
+ * 将系统信息、历史记录、执行日志等动态数据组装成 XML 结构
+ */
+export function buildUserContextPrompt(
+  userRequest: string,
+  sysInfoStr: string,
+  historyStr: string,
+  executedSteps: Array<{ command: string; exitCode: number; output: string }>
+): string {
+  const parts: string[] = []
+
+  // 1. 系统信息
+  parts.push(`<system_info>`)
+  parts.push(sysInfoStr)
+  parts.push(`</system_info>`)
+
+  // 2. 命令历史（如果有）
+  if (historyStr && historyStr.trim()) {
+    parts.push(`<command_history>`)
+    parts.push(historyStr)
+    parts.push(`</command_history>`)
+  }
+
+  // 3. 执行日志（多步骤的核心，紧凑 XML 结构）
+  if (executedSteps && executedSteps.length > 0) {
+    parts.push(`<execution_log>`)
+    executedSteps.forEach((step, i) => {
+      // 截断过长的输出（前 800 + 后 800，中间省略）
+      let safeOutput = step.output || ''
+      if (safeOutput.length > 2000) {
+        const head = safeOutput.slice(0, 800)
+        const tail = safeOutput.slice(-800)
+        safeOutput = head + '\n\n...(输出过长，已截断)...\n\n' + tail
+      }
 
-  // 根据是否启用 shell hook 决定展示哪个历史
-  if (shellHookEnabled && shellHistory) {
-    prompt += `\n\n${shellHistory}`
-  } else if (plsHistory) {
-    prompt += `\n\n${plsHistory}`
+      parts.push(`<step index="${i + 1}">`)
+      parts.push(`<command>${step.command}</command>`)
+      parts.push(`<exit_code>${step.exitCode}</exit_code>`)
+      parts.push(`<output>`)
+      parts.push(safeOutput)
+      parts.push(`</output>`)
+      parts.push(`</step>`)
+    })
+    parts.push(`</execution_log>`)
+    parts.push(``)
+    parts.push(`⚠️ 注意：请检查 <execution_log> 中最后一步的 <exit_code>。如果非 0，请分析 <output> 并修复命令。`)
   }
 
-  return prompt
+  // 4. 用户需求
+  parts.push(`<user_request>`)
+  parts.push(userRequest)
+  parts.push(`</user_request>`)
+
+  return parts.join('\n')
 }
 
 /**
- * 构建 Chat 对话模式的系统提示词
+ * ============================================================
+ * Chat 对话模式的静态 System Prompt
+ * ============================================================
+ * 包含所有核心规则和能力描述，不包含动态数据
  */
-export function buildChatSystemPrompt(
-  sysinfo: string,
-  plsHistory: string,
-  shellHistory: string,
-  shellHookEnabled: boolean
-): string {
-  let prompt = `你是一个命令行专家助手，帮助用户理解和使用命令行工具。
+export const CHAT_SYSTEM_PROMPT = `你是一个命令行专家助手，帮助用户理解和使用命令行工具。
+
+### 📋 输入数据格式说明
+你会收到以下 XML 标签包裹的上下文信息：
+- <system_info>：用户的操作系统、Shell 类型、当前目录等环境信息
+- <command_history>：用户最近通过 pls 执行的命令（用于理解上下文引用）
+- <shell_history>：用户最近在终端执行的所有命令（如果启用了 Shell Hook）
+- <user_question>：用户的具体问题
 
-【你的能力】
+### 🎯 你的能力
 - 解释命令的含义、参数、用法
 - 分析命令的执行效果和潜在风险
 - 回答命令行、Shell、系统管理相关问题
 - 根据用户需求推荐合适的命令并解释
 
-【回答要求】
-- 简洁清晰，避免冗余
-- 危险操作要明确警告
-- 适当给出示例命令
-- 结合用户的系统环境给出针对性建议
+### 📝 回答要求
+- 简洁清晰，避免冗余解释
+- 危险操作要明确警告（如 rm -rf、chmod 777 等）
+- 适当给出示例命令（使用代码块格式）
+- 结合 <system_info> 中的系统环境给出针对性建议
+- 如果用户引用了"刚才的命令"、"上一个操作"，请参考历史记录
 
-【用户系统信息】
-${sysinfo}`
+### 📌 关于 pls/please 工具
+用户正在使用 pls（pretty-please）工具，这是一个将自然语言转换为 shell 命令的 AI 助手。
+<command_history> 中标记为 [pls] 的条目表示用户通过 pls 工具执行的命令。
+你可以解释这些命令，帮助用户理解它们的作用。`
+
+/**
+ * ============================================================
+ * 构建 Chat 动态 User Context（XML 格式）
+ * ============================================================
+ * 将系统信息、历史记录等动态数据组装成 XML 结构
+ * 这个上下文会作为最新一条 user 消息发送给 AI
+ */
+export function buildChatUserContext(
+  userQuestion: string,
+  sysInfoStr: string,
+  plsHistory: string,
+  shellHistory: string,
+  shellHookEnabled: boolean
+): string {
+  const parts: string[] = []
 
-  // 根据是否启用 shell hook 决定展示哪个历史
-  if (shellHookEnabled && shellHistory) {
-    prompt += `\n\n${shellHistory}`
-  } else if (plsHistory) {
-    prompt += `\n\n${plsHistory}`
+  // 1. 系统信息
+  parts.push('<system_info>')
+  parts.push(sysInfoStr)
+  parts.push('</system_info>')
+
+  // 2. 历史记录（根据 Shell Hook 状态选择）
+  if (shellHookEnabled && shellHistory && shellHistory.trim()) {
+    parts.push('<shell_history>')
+    parts.push(shellHistory)
+    parts.push('</shell_history>')
+  } else if (plsHistory && plsHistory.trim()) {
+    parts.push('<command_history>')
+    parts.push(plsHistory)
+    parts.push('</command_history>')
   }
 
-  return prompt
+  // 3. 用户问题
+  parts.push('<user_question>')
+  parts.push(userQuestion)
+  parts.push('</user_question>')
+
+  return parts.join('\n')
 }