Exec Tool

Exec 工具就像是一个传话员，它可以把你想让电脑做的事情（我们叫它“命令”）告诉电脑。你可以让它立刻去做，也可以让它等一等，在后台悄悄做。

怎么使用它呢？

1. 告诉它做什么：你需要一个 command，这是必须的。就像说“去把玩具收好”一样，你要告诉它一个完整的命令，比如 ls -la（意思是“列出所有文件和文件夹的详细信息”）。
2. 告诉它在哪里工作：你可以用 workdir 告诉它应该在哪个文件夹里执行命令。如果不告诉它，它就在你现在的位置工作。
3. 给它一些特别的指示：你还可以用其他一些“开关”来调整它的工作方式：
   • yieldMs：你可以把它想成一个“耐心计时器”。如果命令运行时间超过这个数字（单位是毫秒），它就自动转到后台去运行，不打扰你。
   • background：这是一个“立刻去后台”的开关。如果你把它设为 true，命令会立刻在后台开始运行。
   • pty：这是一个“模拟小屏幕”的开关。有些程序喜欢在一个像小电视屏幕一样的地方运行，打开这个开关（设为 true）可以让它们更开心。
   • host：告诉它命令在哪里执行。有三个地方可选：
     • sandbox（沙盒）：这是默认的，像一个安全的游戏围栏，在里面玩比较安全。
     • gateway（网关）：在你自己的电脑主机上执行。
     • node（节点）：在另一台连接好的电脑上执行。
   • security：这是“安全模式”。有三种：
     • deny（拒绝）：最安全，除了特别允许的，其他都不让做。
     • allowlist（允许名单）：只做名单上允许的事情。
     • full（完全信任）：信任它，让它做任何事（要小心使用哦）。
   • ask：这是“询问开关”。决定什么时候需要你点“同意”按钮：
     • off（关闭）：不询问。
     • on-miss（当没在名单上时）：如果命令不在允许名单里，就询问。
     • always（总是）：每次都询问。

一些重要的注意事项：

• 默认情况下，host 是 sandbox（沙盒模式）。但沙盒功能默认是关闭的！如果沙盒关闭了，你却明确要求 host=sandbox，那么命令会失败，而不是偷偷在你的主机上运行。所以，要么打开沙盒功能，要么直接使用 host=gateway 并配合询问开关。
• 当在 gateway 或 node 上执行命令时，为了保护你的电脑，不允许通过 env.PATH 来改变电脑寻找程序的路径，也不允许一些特殊的加载设置（像 LD_* 或 DYLD_*）。
• 如果你想在另一台电脑（node）上运行命令，需要先把它和你的电脑配对好。
• 在 Windows 电脑上，它会先找 PowerShell 7，找不到再用 Windows PowerShell。

怎么设置它？ 你可以在一个叫配置文件的地方，给 Exec 工具设置一些默认的规则。比如：

• tools.exec.host：设置默认在哪里执行命令。
• tools.exec.security：设置默认的安全模式。
• tools.exec.pathPrepend：这是一个列表，可以告诉它在执行命令前，先去哪些文件夹里找程序。

一个特别的命令：/exec 你可以在聊天时输入 /exec 来为这一次的对话临时改变一些设置，比如 host 或 security。这不会永久改变配置文件。只输入 /exec 可以看看现在是什么设置。

需要批准才能做的事 如果你的小助手（Agent）在沙盒里，但想在你的主机（gateway）或另一台电脑（node）上做事，可能需要你先点“同意”。当需要批准时，Exec 工具会立刻回复说“正在等待批准”。一旦你批准了，命令才会真正开始运行。如果命令运行时间很长，你还会收到一个“正在运行”的通知。

安全名单和安全的小程序 为了让事情更安全，有两种方式：

1. 允许名单（allowlist）：就像一份“好孩子名单”，只有名单上的程序才可以运行。这个名单只看程序的完整路径。
2. 安全小程序（safeBins）：这是一些特别安全、只会读点输入然后输出结果的小工具（比如 grep, cat）。它们可以不用在允许名单里就能运行。但注意，不要把像 python3、bash 这样的大程序当成安全小程序哦！

看看它怎么工作（例子）

• 立刻运行一个命令：{ "tool": "exec", "command": "ls -la" }
• 让命令在后台运行并检查它：先发送 {"tool":"exec","command":"npm run build","yieldMs":1000}，然后可以用 {"tool":"process","action":"poll","sessionId":"<id>"} 来查看后台任务怎么样了。
• 给后台程序发送按键：就像在遥控器上按键一样，可以用 {"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]} 来发送一个“回车”键。