Shell 命令工具

taskflow_shell 提供安全的 shell 命令执行能力

---

📋 可用工具

工具名	功能	安全性
taskflow_shell_exec	执行 shell 命令（同步）	✅ High
taskflow_shell_exec_async	异步执行 shell 命令	✅ High
taskflow_shell_test	测试命令是否可用	✅ Low

---

🔧 工具详解

exec

执行 shell 命令（同步）。

参数：

{
  "command": "string",     // 命令（必填）
  "cwd": "string",         // 工作目录（可选）
  "timeout": 30000,        // 超时时间（毫秒，可选）
  "env": {}                // 环境变量（可选）
}

示例：

Claude: 帮我运行 npm install

调用：

{
  "name": "taskflow_shell_exec",
  "arguments": {
    "command": "npm install"
  }
}

返回：

{
  "success": true,
  "output": "added 123 packages in 5s",
  "exitCode": 0,
  "duration": 5234
}

---

exec_async

异步执行 shell 命令。

参数：

{
  "command": "string",     // 命令（必填）
  "cwd": "string",         // 工作目录（可选）
  "timeout": 30000         // 超时时间（毫秒，可选）
}

示例：

Claude: 启动开发服务器

调用：

{
  "name": "taskflow_shell_exec_async",
  "arguments": {
    "command": "npm run dev"
  }
}

返回：

{
  "success": true,
  "processId": "exec-1234567890",
  "message": "Process started"
}

---

test

测试命令是否可用。

参数：

{
  "command": "string"      // 命令（必填）
}

示例：

Claude: 检查 git 是否可用

调用：

{
  "name": "taskflow_shell_test",
  "arguments": {
    "command": "git"
  }
}

返回：

{
  "success": true,
  "available": true,
  "version": "2.43.0"
}

---

🔒 安全机制

1. 命令白名单

只允许以下命令：

allowedCommands:
  # 文件操作
  - ls
  - cd
  - pwd
  - cat
  - head
  - tail
  - grep
  - find
  - cp
  - mv
  - rm
  - mkdir
  - touch
  
  # 版本控制
  - git
  
  # 包管理
  - npm
  - yarn
  - pnpm
  
  # 运行环境
  - node
  - python
  - python3
  
  # 系统工具
  - echo
  - printf
  - sed
  - awk
  - jq

2. 危险字符过滤

以下字符被禁止：

&&  ||  ;  |  $()  `  >  <  &

示例：

# ❌ 被拒绝
npm install && npm run build

# ✅ 允许
npm install
npm run build

3. 超时控制

命令类型	默认超时
简单命令	10 秒
构建命令	60 秒
测试命令	120 秒

4. 命令链检测

自动检测并拒绝命令链：

// 检测命令链
if (command.includes('&&') || command.includes('||') || command.includes(';')) {
  throw new Error('命令链不被允许');
}

---

💡 使用技巧

技巧一：分步执行

Claude: 帮我构建并测试项目

Claude 会依次执行：

npm run build
npm test

技巧二：使用 test 预检查

Claude: 检查项目依赖是否完整

Claude 会先运行 npm test 检查，再决定后续操作。

技巧三：查看命令输出

Claude: 运行 npm run build 并显示输出

Claude 会执行命令并返回完整输出。

---

🐛 常见问题

Q: 命令被拒绝

A: 命令不在白名单中。尝试：

1. 使用允许的替代命令
2. 联系管理员添加命令
3. 分步执行复杂命令

Q: 命令超时

A: 命令执行时间过长。尝试：

1. 优化命令（如使用 --frozen-lockfile）
2. 增加超时时间（配置中设置）
3. 使用异步执行

Q: 权限错误

A: 命令需要特殊权限。检查：

# 检查权限
ls -la /path/to/command

# 添加执行权限
chmod +x /path/to/command

---

🔗 相关链接

• MCP 工具总览
• 文件系统工具
• 安全机制说明

---

Shell 命令有问题随时问我