尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Agent Zero 代码执行插件(_code_execution)深入解析:终端、Python 与 Node.js 的持久化本地/SSH 执行引擎

Agent Zero 代码执行插件(_code_execution)深入解析:终端、Python 与 Node.js 的持久化本地/SSH 执行引擎 Agent Zero 代码执行插件_code_execution深入解析终端、Python 与 Node.js 的持久化本地/SSH 执行引擎【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的_code_execution插件为 Agent 提供了内置的代码执行工具支持通过持久的本地 TTY 会话或 SSH 远程会话运行终端命令、Python 与 Node.js 代码。本文以 plugins/_code_execution/AGENTS.md 为骨架结合插件源码、配置与提示词完整讲解其模块职责、运行时调度、会话生命周期、超时/流式输出机制与最佳实践帮助开发者理解并正确使用这套既像真人终端、又安全可控的执行引擎。一、插件定位与模块职责Ownership按照 plugins/_code_execution/AGENTS.md 的定义该插件提供的是通过持久的本地或 SSH 会话执行终端、Python、Node.js 代码能力。插件的代码被明确划分为四个职责域模块职责tools/代码执行工具与输入工具tools/code_execution_tool.py、tools/input.pyhelpers/本地 Shell、SSH Shell 与 TTY 会话管理helpers/shell_local.py、helpers/shell_ssh.py、helpers/tty_session.pyprompts/执行提示词与运行时响应片段prompts/ 下的agent.system.tool.*与fw.code.*系列配置与 UIdefault_config.yaml、plugin.yaml、extensions/、webui/负责设置、元数据、钩子与界面配置从 plugin.yaml 可看到插件的元数据名称为_code_execution版本1.0.0always_enabled: False默认不强制启用配置节归属agent且同时支持per_project_config: true与per_agent_config: true即可以在项目级别和 Agent 级别分别覆盖执行配置。二、五大运行时从 terminal 到 resetAgent 侧通过code_execution_tool工具发起调用参数runtime决定执行方式。在 tools/code_execution_tool.py 的execute()入口中分发逻辑一目了然runtimepython→execute_python_code()实际执行ipython -c 代码见 code_execution_tool.pyruntimenodejs→execute_nodejs_code()实际执行node /exe/node_eval.js 代码见 code_execution_tool.pyruntimeterminal→execute_terminal_command()直接在持久 Shell 中执行命令见 code_execution_tool.pyruntimeoutput→get_terminal_output()用于轮询仍在运行的长任务输出并使用独立的output_timeouts超时组默认首包 120s / 间隔 60s / 上限 600s见default_config.yamlruntimereset或resettrue→reset_terminal()销毁指定会话session或全部会话见 code_execution_tool.py。除此之外还有独立的input工具tools/input.py它把keyboard参数转发给code_execution_tool并设置allow_running: True用于向正在运行的程序输入 Y/N、密码等交互应答——这与fw.code.pause_dialog.md的对话检测机制配合构成完整的交互闭环。工具参数的官方约定prompts/agent.system.tool.code_exe.md 定义了工具参数规范这是 Agent 使用该工具的用户手册runtimeterminal、python、nodejs或outputcode命令或脚本代码session终端会话 ID默认0reset是否先销毁会话再运行true或false。典型调用示例摘自提示词文件{ thoughts: [Need to install zip package...], headline: Installing zip package via terminal, tool_name: code_execution_tool, tool_args: { runtime: terminal, session: 0, reset: false, code: apt-get install zip } }Python 与 Node.js 示例则分别使用print(os.getcwd())与console.log(process.cwd())提示词特别要求需要明确输出时必须使用print()或console.log()。三、持久化会话与 Shell 状态管理3.1 会话按 session 号复用prepare_state()code_execution_tool.py是会话生命周期的核心它从 Agent 数据_cet_state中取出shells字典以session号为键维护一组ShellWrap内含会话对象与running忙碌标志。当目标会话不存在时才按需创建并立即connect()。会话的工作目录cwd由ensure_cwd()决定优先取当前项目目录projects.get_project_folder否则退回全局workdir_path设置目录不存在时会自动创建。这意味着同一个会话内cd、环境变量导出等 Shell 状态得以保留后续命令可复用。3.2 本地 TTY 与 SSH 两条执行路径插件支持两种执行后端通过配置ssh_enabled选择本地 TTYLocalInteractiveSessionhelpers/shell_local.py基于TTYSessionhelpers/tty_session.py创建真正的伪终端进程。POSIX 平台通过pty.openpty()create_subprocess_shell实现并禁用 ECHO、start_new_sessionTrueWindows 平台则基于winpty实现。值得注意的是disable_pagers_in_env()会把PAGER/GIT_PAGER指向cat防止git diff/less等分页器因无人输入而永久阻塞源码注释明确引用了 issue #1697。SSH 远程SSHInteractiveSessionhelpers/shell_ssh.py基于paramikoinvoke_shell()建立交互式通道连接时注入unset PROMPT_COMMAND PS0; stty -echo与分页器禁用命令并开启传输层 keep-alive默认每 5 秒一个SSH_MSG_IGNORE防止长任务掉线。两条路径都实现了统一的connect / send_command / read_output / close / is_terminated / get_exit_code接口因此上层CodeExecution工具可以用完全一致的代码驱动二者——这正是 AGENTS.md 中显式区分本地与 SSH 执行运行时契约的落点会话类型通过isinstance判定后在日志中标注(local)或(remote)。四、流式输出、超时与结束判定Local ContractsAGENTS.md 用较大篇幅约束了执行语义源码中的实现与之一一对应4.1 多行命令作为单个复合命令提交_group_multiline_command()code_execution_tool.py会把含换行的多行输入包裹成{ ... }Windows PowerShell 下为. { ... }的当前 Shell 复合语句一次性发送。其目的是只有最终的提示符出现才标记命令完成避免多行输入中的中间提示符被误判为已完成而中断排队的工作同时保留cd、export 等 Shell 状态。4.2 进程退出/SSH 通道关闭 命令终结get_terminal_output()的轮询循环code_execution_tool.py每 0.5 秒读取一次输出并检查shell.is_terminated()。当本地 Shell 因exit、set -e或 SSH 通道丢失而退出且永远不会再产生提示符时代码将其视为命令的确定结束读取退出码并返回fw.code.shell_exit.md提示之后下一次命令到来时prepare_state()会检测到is_terminated()并惰性重建会话见 code_execution_tool.py。4.3 三级超时与两类模式匹配default_config.yaml定义了完整的超时与模式配置# 常规 runtimeterminal/python/nodejs单位秒 code_exec_first_output_timeout: 30 # 首次输出等待上限 code_exec_between_output_timeout: 15 # 两次输出之间的静默上限 code_exec_max_exec_timeout: 240 # 单命令最大执行时间 code_exec_dialog_timeout: 5 # 对话检测触发等待 # output 轮询 runtime适合构建/安装/服务/训练等长任务 output_first_output_timeout: 120 output_between_output_timeout: 60 output_max_exec_timeout: 600 output_dialog_timeout: 5prompt_patterns提示符正则命中即提前返回无需等待超时默认包含 venv、root、userhost 等常见提示符形态dialog_patterns对话正则命中后把控制权交回 Agent 以应答交互默认覆盖Y/N、yes/no、:\s*$、?\s*$等模式。在 code_execution_tool.py 中这些多行字符串按行编译为正则对象dialog_patterns额外使用了re.IGNORECASE。4.4 忙碌会话守卫busy-session guardhandle_running_session()code_execution_tool.py在会话runningTrue时拦截新命令除非显式传入allow_runningTrueinput工具正是如此否则返回fw.code.running.md提示会话忙防止重叠命令破坏会话状态。输出轮询、提示符/对话检测在此同样生效。4.5 资源同步释放与不悬挂AGENTS.md 要求会话包装器被丢弃时同步释放进程/连接资源且终端 reset/close 不得挂在忽略 SIGTERM 的前台命令上。对应实现TTYSession.close()tty_session.py先取消输出泵任务再发送 SIGTERM等待 2 秒_CLOSE_TIMEOUT_SECONDS超时后升级为 SIGKILLPTY 主文件描述符的释放做了先失效、后关闭处理_release_pty_master避免并发清理时 fd 被 OS 复用后误关LocalInteractiveSession.close()与SSHInteractiveSession.close()均同步关闭底层进程/通道与客户端__del__兜底清理。4.6 长任务输出检索的保留AGENTS.md 的 Work Guidance 强调改变执行流程时保留长任务输出检索与忙碌守卫。源码中output运行时使用更宽的超时组最长 600 秒并持续把部分输出流式写入日志self.log.update、set_progressAgent 可以反复用runtimeoutput轮询超时或暂停后会返回fw.code.max_time.md/fw.code.pause_time.md等提示由 Agent 决定等待、重置还是重跑。五、SSH 执行模式的配置与解析default_config.yaml中 SSH 相关配置如下ssh_enabled: auto # auto自动检测非 Docker 化时用 SSHDocker 化时用本地 TTYtrue始终 SSHfalse始终本地 TTY ssh_addr: # 为空时从 rfc_url 设置推导 ssh_port: 55022 ssh_user: root ssh_pass: # 为空时使用 RFC exchange 的 root_password解析逻辑位于 code_execution_tool.py_resolve_ssh_enabled()auto等价于not runtime.is_dockerized()——Docker 容器内直接执行本地命令容器外则走 SSH_resolve_ssh_addr()ssh_addr为空时从全局设置的rfc_url中剥去协议、端口与路径推导出主机名_resolve_ssh_pass()ssh_pass为空时从rfc_exchange.get_root_password()取根密码。AGENTS.md 明确要求不得硬编码密钥、SSH 凭据或本地用户路径——密码与地址的从配置/环境推导机制正是这一契约的实现保证了插件在不同部署形态本地、Docker、远程主机间可移植。六、提示词体系与工具使用守则prompts/目录下除工具规范外还包含大量响应模板fw.code.info.md、fw.code.no_output.md无输出兜底信息fw.code.max_time.md、fw.code.no_out_time.md、fw.code.pause_time.md分别对应超最大时长、超首包等待、输出暂停三种超时场景fw.code.running.md会话忙提示fw.code.pause_dialog.md检测到交互对话时提示fw.code.reset.md会话重置提示fw.code.shell_exit.mdShell 退出含退出码提示fw.code.runtime_wrong.md非法 runtime 提示。prompts/agent.system.tool.code_exe.md 还给出了一套完整的使用守则对 Agent以及调用该工具的上层应用极具参考价值不要并行穿插其他工具等待输出期间不要交错调用其他工具把尾部[SYSTEM: ...]框架信息当作执行状态而非命令输出据此决定等待/重置/重跑/继续长任务策略对构建、安装、服务、训练与长测试重定向日志后用runtimeoutput轮询超时或暂停后先检查日志与进程再决定诚实原则不得把超时、部分输出或仍在运行的命令宣称为成功最终回复前清理自己启动的残留后台进程输出可验证当精确输出重要时用命令核对文件路径、行数、字节数与内容。七、验证与开发指引VerificationAGENTS.md 要求任何工具改动后都要冒烟测试四条关键路径terminal、Python、Node.js、输出轮询与 reset。这与插件的运行时矩阵一一对应是开发者修改本插件时的回归清单terminal本地/SSH 下执行命令并观察提示符提前返回Pythonipython -c执行与输出Node.jsnode /exe/node_eval.js执行与输出output启动长任务后用runtimeoutput轮询验证忙碌守卫、超时与对话检测reset验证指定会话与全量会话的重置、以及被终止会话的惰性重建。同时由于 AGENTS.md 声明helpers/负责 TTY 会话管理底层tty_session.py自带可独立运行的交互式驱动python -m plugins._code_execution.helpers.tty_session支持/tseconds调整空闲超时与/exit退出可用于脱离 Agent 单独调试 PTY 行为。八、配置作用域与启用方式README.md与plugin.yaml共同确认了配置边界设置节agent支持项目级配置per_project_config: true支持 Agent 级配置per_agent_config: true默认不总是启用always_enabled: False需按需启用。WebUI 侧提供了 webui/config.html 配置界面与 extensions/webui/get_message_handler/code-exe-handler.js 消息处理扩展用户可以在界面中调整 SSH、超时与模式匹配等参数。综合来看_code_execution插件的设计核心是把持久交互终端的安全性忙碌守卫、超时兜底、进程清理、实用性流式输出、对话应答、长任务轮询与可移植性本地 TTY / SSH 双后端统一到一套简洁的 runtime 抽象之下让 Agent 既能像真人一样在终端里完成复杂开发任务又不至于被卡死的进程或失控的长任务拖垮会话。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表