Shell

run_command 使用指南

本技能说明如何在 VOTX Agent 中安全调用 run_command。优先使用专用工具；只有诊断、构建、测试或没有等价工具时才调用系统命令。

基本用法

run_command(command: "python --version")
run_command(command: "python start_web.py", working_dir: "E:\\code\\votx-agent")
run_command(command: "python -c \"import sys; print(sys.stdin.read())\"", stdin: "hello")
run_command(command: "python -c \"import os; print(os.environ['FOO'])\"", env: {"FOO": "bar"})
run_command(command: "export FOO=\"bar baz\" && env", session_id: "dev")
run_command(command: "cd E:\\code\\votx-agent && python --version")
run_command(command: "python -c \"import sys; sys.exit(1)\" || python -c \"print(42)\"")
run_command(command: "python -c \"print(1)\" ; python -c \"print(2)\"")
run_command(command: "pwd")
run_command(session_id: "dev", command: "cd E:\\code\\votx-agent && export FOO=bar && pwd")
run_command(session_id: "dev", command: "history")
run_command(session_id: "dev", reset_session: true, command: "pwd")

run_command 每次都是独立子进程，不保留上一次命令的目录、临时环境变量或标准输入。多步任务优先使用 working_dir；如果要临时切目录，可以在同一条命令里用受限的 cd/chdir/pwd 片段，或用 && / || / ; 连接多个步骤。 session_id 会让 cwd、会话环境变量和历史记录在多次调用间保持一致；reset_session 可清空指定会话。export/set/env 现在支持带空格的赋值值，比如 FOO="bar baz"。

可用参数

• working_dir：工作目录，默认使用当前用户目录。
• timeout：单次命令超时，0 表示使用配置值。
• stdin：传给子进程的标准输入文本。
• env：附加环境变量，只接受普通键名，敏感键会被拒绝。
• session_id：同一会话共享 cwd/env/history。
• reset_session：重置指定 session_id 的会话状态。
• cd/chdir：只在当前调用内生效；可以写成 cd 目录 && 命令。
• && / || / ;：顶层命令链连接符，按顺序执行。
• pwd：返回当前调用的工作目录。
• export/set/env：设置或查看会话环境变量。
• unset：删除会话环境变量。
• history：查看会话历史。

跨平台兼容性

run_command 使用 subprocess 安全模式（shell=False），不经过系统 shell 解析，因此跨平台行为一致。但需要注意以下差异：

路径分隔符

• working_dir 参数支持原生路径分隔符，也接受 /（Windows 上 Python 会自动转换）。
• 命令中的路径参数需要使用对应平台的分隔符，或在 Python 命令中使用 os.path.join。

命令差异速查

Windows 专属

run_command(command: "cmd.exe /c \"dir /b\"")
run_command(command: "cmd.exe /c \"build_windows.bat\"")
run_command(command: "powershell -NoProfile -Command \"Get-ChildItem -File\"")
run_command(command: "powershell -NoProfile -Command \"Get-Content .\\version.json\"")
run_command(command: "powershell -NoProfile -Command \"Get-Process | Select-Object -First 10\"")

Windows 下 run_command 自带 UTF-8 编码处理：

• 自动设置 chcp 65001（通过 PYTHONUTF8=1 环境变量）
• 命令输出自动按 UTF-8 优先解码，回退 GBK
• cmd /c 和 cmd /k 命令会自动注入 chcp 65001 > nul 前缀

Linux/macOS 专属

run_command(command: "ls -la", working_dir: "/home/user/votx-agent")
run_command(command: "cat /etc/os-release")
run_command(command: "ps aux | grep python")
run_command(command: "df -h")
run_command(command: "uname -a")
run_command(command: "systemctl status votx-agent")

Linux/macOS 下编码默认 UTF-8，无需特殊处理。

通用跨平台写法

优先使用 Python 命令代替平台特定命令：

# 获取文件列表（跨平台）
run_command(command: "python -c \"import os; print('\\n'.join(os.listdir('.')))\"")

# 获取环境变量（跨平台）
run_command(command: "python -c \"import os; print('\\n'.join(f'{k}={v}' for k,v in sorted(os.environ.items())))\"")

# 查找命令路径（跨平台）
run_command(command: "python -c \"import shutil; print(shutil.which('git'))\"")

# 获取系统信息（跨平台）
run_command(command: "python -c \"import platform; print(platform.platform())\"")

安全规则

• 使用明确路径，避免破坏性通配符。
• 不用系统命令替代文件、网络、文档、知识库等专用工具。
• 不打印密钥、token、.env 内容或用户隐私文件。
• 长任务要设置合理工作目录，并关注超时。

常用模式

Python 优先

run_command(command: "python -m py_compile main.py", working_dir: "E:\\code\\votx-agent")
run_command(command: "python -m compileall -q .", working_dir: "E:\\code\\votx-agent")
run_command(command: "python setup.py", working_dir: "E:\\code\\votx-agent")

Git 操作

run_command(command: "git status", working_dir: "E:\\code\\votx-agent")
run_command(command: "git log --oneline -10", working_dir: "E:\\code\\votx-agent")
run_command(command: "git diff --stat", working_dir: "E:\\code\\votx-agent")

环境检查

run_command(command: "python --version")
run_command(command: "node --version")
run_command(command: "pip list")

会话模式

run_command(session_id: "dev", command: "cd /home/user/project && export PATH=$PATH:/usr/local/bin && pwd")
run_command(session_id: "dev", command: "python --version")
run_command(session_id: "dev", command: "history")
run_command(session_id: "dev", reset_session: true, command: "pwd")

输出与错误

工具优先返回单一输出流；当标准输出和标准错误同时存在时，会同时返回两者并标注 STDOUT: / STDERR:。非零退出码会附带 (exit=<code>)。需要稳定解析时，让命令输出 JSON、CSV 或固定格式文本。

配置

插件路径

plugins/shell/

注册工具

结果说明

• 成功：返回标准输出；同时存在标准错误时标记 STDOUT: / STDERR:。
• 非零退出：附带 (exit=<code>)。
• 超时或校验失败：返回 ERROR: 前缀的错误信息。

常见规范

• 专用 Skill 或文件/网络工具能完成时，不使用 shell。
• 命令保持短、可解释、范围明确；构建和测试设置正确的 working_dir。
• 需要跨调用保留目录和环境变量时使用固定 session_id。
• 不读取或输出密钥、token、密码和 .env 内容。

常见处理办法

• 工作目录越权或不存在：核对实际路径；必要时在命令参数中使用绝对路径，不盲目重复。
• Windows 命令不兼容：显式调用 cmd.exe /c 或 powershell -NoProfile -Command。
• 编码乱码：优先使用 Python UTF-8 模式或工具内置的 UTF-8/GBK 回退。
• 命令超时：调大 timeout 或拆分任务；连续失败时停止重试并分析原因。

常见教训

• run_command 默认不经过系统 shell，管道、重定向和平台内建命令可能需要显式 shell 入口。
• 独立调用不会保留 cwd/env；需要持久状态时必须使用 session_id。
• shell 不应替代已有专用工具，否则会降低可控性和可移植性。