🐚 Shell 工具

命令工具 execute 供模型执行脚本和命令。只做对话或调用 Java／MCP 工具时，可以关闭它。

# 开启命令工具

需要执行命令时，将快速开始组件中的方法改为：

@Override
protected boolean enableShellTool() {
    return true;
}

随后配置本页的本地执行环境，或使用 Docker 沙箱。组件基类默认开启 Shell；快速开始为了只做对话，显式关闭了它。

在 Java 应用所在环境安装所需的 Python、Node.js 等工具，然后添加：

liteflow.agent.harness.filesystem-backend=GUARDED_LOCAL
liteflow.agent.harness.local.workspace-root=./data/agent-execution

应用名为 agent-demo、会话 ID 为 chat-001 时，命令在以下目录执行：

./data/agent-execution/agent-demo/chat-001/

目录由框架创建。模型可调用 execute 运行命令，例如 python3 scripts/report.py；脚本路径相对于该会话工作区。

文件工具和 Shell 使用同一份业务文件：执行命令前从存储恢复到命令目录，执行后把变更保存回存储。因此，文件工具写出的脚本可以继续用 Shell 执行。本地命令目录是执行副本，备份时要保留会话存储中配置的持久存储。

本地命令使用 Java 进程的系统权限和环境变量。工作目录不限制脚本只能访问这个目录；需要容器隔离时使用 Docker 沙箱。长时间运行的后台服务不适合本地命令工具。

内置 execute 使用命令白名单，默认包含 Python、Node.js、Git、常见文件命令等。需要指定允许的命令时配置：

liteflow.agent.harness.shell.whitelist=sh,python3,node,ls,cat,mkdir,pwd
liteflow.agent.harness.shell.timeout=60s

这份列表会替换默认白名单。命令被允许后，仍需在本机或镜像中安装对应程序。复杂操作可以先写入脚本，再执行 python3 scripts/report.py，避免使用被校验器拒绝的管道或链式命令。

模型调用 execute 时，command 为必填；working_directory 为可选的工作区相对目录；timeout 为可选的秒数，只能缩短服务端命令时限。关闭命令工具应覆写 enableShellTool() 返回 false。

@Override
protected boolean enableShellTool() {
    return false;
}

这个方法同时控制本地和 Docker 的内置命令工具。不要仅设置 harness.shell.mode=DISABLED 而保留组件开关为 true，这会形成配置冲突。

默认白名单包含脚本解释器及常见系统命令，完整列表见配置速查。白名单不限制脚本内部行为，本地模式也不提供容器隔离；隔离执行环境见 Docker 沙箱。

上次更新: 2026/09/20, 11:49:27