@jgg0sbp66/koishi-plugin-bash

跨平台终端命令执行插件，支持在 Windows/Linux/macOS 上运行各种 shell 命令。

功能特性

• 🌐 跨平台支持：自动检测并适配 Windows、Linux、macOS
• 🐚 多 Shell 支持：支持 cmd、PowerShell、bash、zsh、sh、fish 等
• ⚙️ 灵活配置：可自定义 shell、超时时间、输出长度等
• 🔒 权限控制：可限制允许使用的用户列表
• ⏱️ 超时保护：防止命令长时间运行

支持的环境

Windows

• CMD (cmd.exe)
• PowerShell (powershell.exe)
• PowerShell Core (pwsh.exe)

Linux

• Bash (/bin/bash)
• Zsh (/bin/zsh)
• Sh (/bin/sh)
• Fish (/usr/bin/fish)

macOS

• Zsh (默认)
• Bash
• 其他 Unix shell

配置项

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | shell | string | 自动检测 | 指定使用的 shell 路径 | | timeout | number | 30000 | 命令执行超时时间（毫秒）| | maxOutputLength | number | 4000 | 最大输出长度（字符数）| | allowedUsers | string[] | [] | 允许使用的用户 ID 列表（空数组表示所有人）| | workingDirectory | string | '' | 工作目录（留空使用当前目录）|

使用方法

基本命令

exec - 执行终端命令

exec <command>

别名：shell、run

示例：

• exec echo "Hello World"
• exec ls -la（Linux/macOS）
• exec dir（Windows）
• exec npm --version

ls - 列出目录内容

ls [path]

示例：

• ls - 列出当前目录
• ls /home - 列出指定目录

pwd - 显示当前工作目录

pwd

sysinfo - 获取系统信息

sysinfo

配置示例

默认配置（自动检测）

plugins:
  bash:
    timeout: 30000
    maxOutputLength: 4000

Windows PowerShell

plugins:
  bash:
    shell: powershell.exe
    timeout: 60000
    maxOutputLength: 5000

Linux Bash

plugins:
  bash:
    shell: /bin/bash
    workingDirectory: /home/user
    allowedUsers:
      - "123456789"  # 仅允许特定用户

macOS Zsh

plugins:
  bash:
    shell: /bin/zsh
    timeout: 45000

安全提示

⚠️ 重要安全提示：

1. 此插件允许执行系统命令，具有较高的安全风险
2. 强烈建议配置 allowedUsers 限制使用权限
3. 不要在公共机器人中启用此插件
4. 谨慎执行来源不明的命令
5. 建议设置合理的 timeout 防止资源占用

使用场景

• 🔧 运维管理：执行系统维护命令
• 📊 状态查询：查看系统信息、进程状态
• 🗂️ 文件管理：浏览目录、查看文件
• 🚀 快速测试：测试脚本、验证环境
• 🔄 自动化任务：集成系统命令到聊天流程

常见问题

Q: 如何知道当前使用的是哪个 shell？

A: 使用 sysinfo 命令可以查看当前配置的 shell。

Q: 命令执行超时怎么办？

A: 增加 timeout 配置值，或者优化命令减少执行时间。

Q: Windows 下某些命令不工作？

A: 确保使用正确的 Windows 命令语法，或切换到 PowerShell。

Q: 如何限制只有管理员可以使用？

A: 在 allowedUsers 中添加管理员的用户 ID。

License

MIT