尧图网站建设 
Agent Zero 插件管理完全指南从 Plugin Hub 浏览、安全扫描到安装、更新、卸载与激活【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的插件体系允许你通过 Plugin Hub、Git 仓库或 ZIP 包向框架注入工具、扩展点、WebUI 组件与自定义行为但第三方插件会在你的 Agent 环境中执行代码因此安全扫描与生命周期管理同样关键。本文以仓库中的官方技能 a0-manage-plugin/SKILL.md 为主体结合_plugin_installer、_plugin_scan两个内置插件与 helpers/plugins.py 的源码实现系统讲解插件的浏览、扫描、安装、更新、卸载与启用/停用全流程并给出可直接复制的 HTTP API 调用示例。读完本文你将掌握 Agent Zero 插件管理的标准操作与底层原理。技能定位a0-manage-plugin 负责什么官方技能 a0-manage-plugin版本 1.2.0的职责是拥有插件生命周期管理的完整工作流浏览与搜索插件、安全扫描、安装、更新、启用/停用、卸载以及基础的调试与排障引导。其触发词覆盖了绝大多数用户诉求install plugin/uninstall plugin/remove plugin/delete pluginupdate plugin/scan plugin/debug plugin/troubleshoot pluginbrowse plugins/search plugins/list pluginsplugin not working/enable plugin/disable plugin/plugin hub配套的维护说明 skills/a0-manage-plugin/AGENTS.md 明确了该技能的几个本地契约保持 Plugin Hub URL、安装 API 行为、扫描预期与激活语义与当前框架一致在安装流程之前必须对第三方插件执行风险发出警告不推荐在插件自有路径之外进行无管理的删除。需求路由表面对不同用户诉求技能文档给出了明确的跳转指引用户需求对应章节查找 / 搜索 / 浏览可用插件浏览 Plugin Hub扫描插件安全风险安全扫描安装插件安装插件更新已安装插件更新插件卸载 / 移除插件卸载插件启用或停用插件激活与停用插件加载失败 / 崩溃 / 缺失阅读 a0-debug-plugin 技能解释插件发现机制阅读 a0-debug-plugin 技能浏览与发现插件Plugin Hub 与本地目录拉取社区插件索引插件发现的第一步是从 Plugin Hub 拉取社区维护的插件索引。技能文档给出的标准做法是直接请求generated-index的index.jsonimport urllib.request, json url https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.json with urllib.request.urlopen(url, timeout30) as resp: index json.loads(resp.read()) plugins index.get(plugins, {})返回的plugins字典以插件名为键每个条目包含title、description、github、tags以及thumbnail可用时提供图片 URL。搜索插件的推荐方式是按关键词过滤title、description或tags字段。从源码看该索引的实际拉取实现在 plugins/_plugin_installer/helpers/install.py 的fetch_plugin_index()它同样请求上述 URL设置User-Agent: AgentZero并且当forceTrue时会在 URL 后附加时间戳参数并携带Cache-Control: no-cache/Pragma: no-cache强制绕过缓存这对于索引刷新场景很有用。列出本地已安装插件本地插件目录位于用户区usr/plugins/Docker 内对应/a0/usr/plugins/列出已安装插件ls usr/plugins/更完整的本地插件枚举由 helpers/plugins.py 的get_plugins_list()提供它同时扫描用户目录usr/plugins/与框架内置目录plugins/用户目录优先跳过隐藏目录以.开头只把包含plugin.yaml元数据文件的目录计入结果并对结果做缓存与排序。通过 WebUI 浏览另一种交互方式打开 Agent Zero 的Plugins 对话框切换到Browse标签页或在工具栏点击Install打开 Plugin Hub。WebUI 侧的浏览入口由_plugin_installer插件的扩展点提供见 plugins/_plugin_installer/extensions/webui 下的按钮与注解脚本。安装前的安全扫描_plugin_scan的 6 项检查Agent Zero 内置的_plugin_scan插件提供了一套LLM 驱动的安全扫描器描述见 plugins/_plugin_scan/plugin.yaml。它的工作方式是把仓库克隆下来、读取所有文件、运行 6 项 LLM 检查最终产出一份结构化 Markdown 报告。完整的检查定义位于 plugins/_plugin_scan/webui/plugin-scan-checks.json检查键名称关注点structure结构与用途匹配文件/目录是否与插件宣称的功能一致是否存在无关的数据访问codeReview静态代码审查SQL 注入、路径穿越、不安全的反序列化、对不可信输入的eval/exec、shell 注入、硬编码真实凭据、不安全的 ZIP/TAR 解压、越界破坏性文件操作、运行时拉取并执行远程代码agentManipulationAgent 操纵检测注释/字符串/文件名中的提示注入、要求忽略安全性的指令、隐藏指令base64、零宽字符、Unicode 技巧remoteComms远程通信与外部服务器的 HTTP/WebSocket/DNS 通信、隐藏遥测、远程代码加载、与插件用途不符的数据外传secrets机密与敏感数据访问环境变量、.env、API Key、令牌、Cookie、会话数据的访问范围与安全性obfuscation混淆与隐藏代码编码载荷base64/hex/rot13、运行时拼接敏感名称、动态导入、可疑的超长单行表达式、隐藏载荷扫描器对正常行为有明确的豁免规则例如集成类插件调用其声明服务的 API、OAuth/设备登录端点、Webhook 属于预期行为普通压缩/供应商前端资源、锁文件、测试夹具不视为混淆。只有未披露的主机、与用途不符的数据外传、故意隐藏行为的编码才会被判为失败。预安装扫描协议每次安装都建议执行技能文档要求在安装前始终主动提供扫描选项。若用户未明确拒绝应给出如下提示Before installing, I strongly recommend running a security scan on this plugin. Third-party plugins execute code inside your Agent Zero environment. Should I scan it first? The scan typically takes 2-4 minutes.如果用户拒绝则确认一次并警告Understood, skipping the scan. Note that installing unscanned third-party code carries security risks. Proceeding with installation.之后继续安装不要重复询问。运行扫描扫描通过 HTTP API 调用_plugin_scan的同步端点认证方式见下文API 认证小节# (after authentication setup - see Install section) resp s.post( f{BASE}/api/plugins/_plugin_scan/plugin_scan_run, json{ git_url: https://github.com/user/plugin-repo, checks: [structure, codeReview, agentManipulation, remoteComms, secrets, obfuscation], }, headers{X-CSRF-Token: token, Origin: ORIGIN}, timeout600, # 设得宽松一些——扫描会克隆仓库、读取全部文件并执行 6 项 LLM 检查 ) data resp.json()务必显式传入完整的checks列表——技能文档特别指出省略该参数已被观察到会导致间歇性失败。如需运行子集从列表中移除不需要的键即可。该端点的实现见 plugins/_plugin_scan/api/plugin_scan_run.py它把git_url与checks组合成提示词交由 Agent 上下文执行扫描然后返回{ ok: true, git_url: ..., report: markdown }。源码注释明确提醒服务端没有超时限制仓库扫描可能耗时 5 分钟以上客户端应自行设置足够的超时时间技能文档建议 600 秒。解读扫描结果report data[report] # 完整 markdown 安全报告将完整report呈现给用户。阅读Summary部分确定总体结论Safe/Caution/Dangerous并按如下规则行动结论处理方式Safe提议继续安装Caution展示发现的问题警告存在风险请求用户明确确认Some warnings were found. Do you still want to install?Dangerous展示发现的问题强烈建议不要安装The scanner flagged serious security issues. I strongly recommend NOT installing this plugin. Do you want to proceed anyway? 仅在用户明确确认后才安装如果扫描超时或返回 500 错误应告知用户并询问是否在无扫描的情况下继续。安装插件三条路径与一条铁律铁律走 HTTP API 或 UI绝不直接 import 框架模块技能文档给出了明确警告永远使用 HTTP API 或 UI 完成安装。不要从code_execution_tool直接导入 Agent Zero 框架模块——Agent 运行在独立的 Python 运行时Docker 内为/opt/venv中该环境并不具备框架的依赖。所有程序化安装都必须通过 HTTP 进行。已安装状态的判定机制Plugin Hub 在请求时通过将 Plugin Hub 键与usr/plugins/目录名做交叉比对来标记插件为Installed。要让插件显示为已安装需要满足插件目录必须存在于usr/plugins/name/且包含有效的plugin.yaml如果插件自带扩展点框架会在插件缓存刷新后将命名扩展点注册到extensions/python/point/下把隐式的extensible钩子注册到extensions/python/_functions/module/qualname/start|end/下框架插件缓存必须被清空API 会自动处理重新拉取 Plugin Hub 索引后即显示为已安装。这一定义与源码一致get_plugin_hub_index()见 plugins/_plugin_installer/helpers/install.py通过get_plugins_list()得到本地插件目录集合再与索引键比对生成installed_plugins列表同时会为缺少缩略图的旧安装回填thumbnail。API 认证所有 HTTP 调用的前置条件Agent Zero API 使用 CSRF 保护。Origin头始终必须携带——缺少它时即使登录已禁用CSRF 端点也会返回ok: false。Step 1设置基础 URL。Agent Zero 在 Docker 标准部署中监听 80 端口import requests BASE http://localhost # Docker 内为 80 端口 # 若在 Docker 外运行开发模式请检查os.environ.get(WEB_UI_PORT, 5000)Step 2引导会话并获取 CSRF tokens requests.Session() ORIGIN BASE # Origin 必须匹配 localhost 模式 r s.get(f{BASE}/api/csrf_token, headers{Origin: ORIGIN}, timeout10) data r.json() if not data.get(ok): raise RuntimeError(fCSRF bootstrap failed: {data.get(error)}) token data[token] runtime_id data[runtime_id] # 设置 CSRF cookie与 header 一起使用 s.cookies.set(fcsrf_token_{runtime_id}, token)后续所有 API 调用复用s、BASE、ORIGIN与token并且每次请求都必须携带headers{X-CSRF-Token: token, Origin: ORIGIN}。方法一从 Git URL 安装HTTP API程序化使用首选# (after authentication setup above) resp s.post( f{BASE}/api/plugins/_plugin_installer/plugin_install, json{ action: install_git, git_url: https://github.com/user/plugin-repo, # git_token: token, # 可选用于私有仓库 # plugin_name: override # 可选覆盖目录名 }, headers{X-CSRF-Token: token, Origin: ORIGIN}, timeout120, ) print(resp.json())这会在框架运行时内执行完整流水线clone → 校验 → 放入usr/plugins/→ 执行install钩子 → 清空插件缓存 → 通知前端。下一次拉取 Plugin Hub 索引时插件即显示为已安装。流水线的底层实现在install_from_git()plugins/_plugin_installer/helpers/install.py在临时目录克隆仓库clone_repo支持tokenvalidate_plugin_dir()检查plugin.yaml存在且可解析若指定了plugin_name还会校验元数据中的name与之一致check_plugin_conflict()检测同名插件是否已存在于usr/plugins/存在则抛错将目录移动到usr/plugins/name/_download_thumbnail()可选下载缩略图到webui/thumbnail.ext非致命失败run_install_hook()调用插件hooks.py中的install钩子检查是否含 Python 文件随后after_plugin_change([plugin_name], python_change...)完成缓存清理、模块刷新与前端通知。API 入口层面对这些动作的分发在 plugins/_plugin_installer/api/plugin_install.py 中它支持install_zip、install_git、update_plugin、fetch_index四种动作并将所有异常统一包装为{success: false, error: ...}返回。方法二从 Plugin Hub 安装UI交互使用首选打开 Plugins 对话框进入Browse标签页或点击Install找到插件、点击它、点击Install。UI 会处理一切包括在 Plugin Hub 视图中把插件标记为已安装。方法三从 ZIP 文件安装HTTP API# (after authentication setup above) with open(plugin.zip, rb) as f: resp s.post( f{BASE}/api/plugins/_plugin_installer/plugin_install, data{action: install_zip}, files{plugin_file: f}, headers{X-CSRF-Token: token, Origin: ORIGIN}, ) print(resp.json())或通过 UIPlugins 对话框 → Install → ZIP 标签页 → 上传文件。ZIP 路径的实现在install_uploaded_zip()/install_from_zip()plugins/_plugin_installer/helpers/install.py值得注意的安全细节上传文件先落盘到tmp/plugin_uploads/带时间戳与 UUID 的临时文件名解压前对每一个归档成员做路径穿越防护——成员真实路径必须位于解压目录之内否则抛出Unsafe path in archive错误_find_plugin_root()遍历解压目录定位plugin.yaml的父目录作为插件根无论成功失败finally块都会清理临时解压目录与归档文件。手动安装仅作为最后手段仅当 HTTP API 确实不可用时才使用注意import 报错不属于不可用那恰恰意味着你必须改用 HTTP APIgit clone https://github.com/user/repo usr/plugins/plugin_name克隆完成后插件已在磁盘上但框架并不知道它的存在。需要清空缓存并通知前端——可以通过调用 toggle API先关后开来触发内部的after_plugin_change()# (after authentication setup above) for state in [False, True]: s.post( f{BASE}/api/plugins, json{action: toggle_plugin, plugin_name: plugin_name, enabled: state}, headers{X-CSRF-Token: token, Origin: ORIGIN}, )或者直接重启 Agent Zero——启动时框架会重新完整扫描usr/plugins/。更新插件对比提交而不是版本号框架的更新流程现在会在把新代码拉入到位之前调用hooks.py中的pre_update()若存在该钩子更新完成后还会重新执行install()。检查是否有更新不要比较版本字符串。贡献者经常忘记递增版本号因此版本号相同不代表插件是最新的。应改为检查远端是否有新提交# 该插件是 git 仓库吗 git -C usr/plugins/name rev-parse --is-inside-work-tree 2/dev/null # 对比本地 HEAD 与远端 HEAD无需 fetch LOCAL$(git -C usr/plugins/name rev-parse HEAD) REMOTE$(git -C usr/plugins/name ls-remote origin HEAD | awk {print $1}) echo Local: $LOCAL echo Remote: $REMOTE [ $LOCAL $REMOTE ] echo Up to date || echo Update available若二者不同说明远端存在新提交——无论版本号字段是否变化都应向用户报告有可用更新。应用更新如果插件是通过 Git 安装的cd usr/plugins/name git pull origin main然后通过 toggle API 刷新框架缓存会话建立方式见上文API 认证# (after authentication setup) for state in [False, True]: s.post( f{BASE}/api/plugins, json{action: toggle_plugin, plugin_name: name, enabled: state}, headers{X-CSRF-Token: token, Origin: ORIGIN}, )如果不是 git 仓库通过 API 卸载见下节再按上面的 Git 方法重新安装。框架侧还提供了一条程序化更新路径_plugin_installer的update_plugin动作会调用update_from_git()plugins/_plugin_installer/helpers/install.py其流程为校验插件存在且位于usr/plugins/只有自定义插件可被更新→ 执行pre_update钩子 →git.update_repo()拉取 → 重新执行install钩子 →after_plugin_change()最后返回current_commit、current_commit_timestamp、branch、remote_url等元信息供前端展示。卸载插件安全规则与标准流程卸载前必读的安全规则核心插件位于plugins/而非usr/plugins/无法通过 API 卸载——框架会阻止该操作只能改用停用见下文激活小节。卸载前必须请求用户明确确认Are you sure you want to uninstallname? This will delete all plugin files and cannot be undone.卸载不会删除存放在usr/agents/或项目作用域中的插件配置文件。标准卸载通过 API使用框架的uninstall_plugin它会在删除前调用插件的uninstall钩子若已定义。需要已认证的会话见安装小节的 API 认证# (after authentication setup from the Install section) resp s.post( f{BASE}/api/plugins, json{ action: delete_plugin, plugin_name: name, }, headers{X-CSRF-Token: token, Origin: ORIGIN}, ) print(resp.json())这是推荐方式。框架将依次执行调用hooks.py中的uninstall()若存在——执行清理删除usr/plugins/name/目录通知前端刷新插件列表。通过 UIPlugins 对话框 → 找到插件 → 点击删除垃圾桶图标 → 确认。源码级依据uninstall_plugin()helpers/plugins.py先call_plugin_hook(plugin_name, uninstall)再调用delete_plugin()而delete_plugin()helpers/plugins.py会先通过find_plugin_dir()定位插件并校验其必须位于usr/plugins/之下——若位于内置plugins/则抛出Only custom plugins can be deleted。删除时还会顺带清理插件的关联资产目录如扩展点目录并携带python_change参数触发after_plugin_change()完成缓存与模块清理。兜底方案直接删除目录仅当标准卸载失败时使用例如uninstall钩子损坏导致崩溃或挂起# 确认该插件是自定义插件usr/plugins/ 下——绝不删除 plugins/ 下的内容 ls usr/plugins/name/ # 移除它 rm -rf usr/plugins/name/手动删除后通过 UI 刷新插件列表或重启 Agent Zero。激活与停用toggle 文件机制插件的启用/停用通过 toggle 文件实现.toggle-1 显式启用ON.toggle-0 显式停用OFF无文件 默认状态对大多数插件而言为启用这一约定与源码中的常量完全对应ENABLED_FILE_NAME .toggle-1、DISABLED_FILE_NAME .toggle-0见 helpers/plugins.py。启用插件rm -f usr/plugins/name/.toggle-0 touch usr/plugins/name/.toggle-1停用插件rm -f usr/plugins/name/.toggle-1 touch usr/plugins/name/.toggle-0通过 UIPlugins 对话框 → 找到插件 → 使用切换开关。plugin.yaml中带有always_enabled: true的插件无法被切换仅限框架核心插件使用例如_plugin_installer自身就声明了always_enabled: true见 plugins/_plugin_installer/plugin.yaml。状态判定的底层逻辑是 helpers/plugins.py 的determined_toggle_from_paths()插件默认启用遍历插件路径用户目录优先含代理/项目作用域覆盖时若当前为启用则检查是否存在.toggle-0存在即停用若为停用则检查是否存在.toggle-1存在即恢复启用。get_toggle_state()helpers/plugins.py对always_enabled的插件直接返回enabled。作用域切换Scoped Toggles当插件的plugin.yaml设置了per_project_config: true或per_agent_config: true时可使用 UI 中的 Switch 弹窗或把 toggle 文件放到对应的作用域路径下项目作用域project/.a0proj/plugins/name/.toggle-1代理档案作用域usr/agents/profile/plugins/name/.toggle-1API 层面由toggle_plugin()helpers/plugins.py承载它支持project_name、agent_profile参数写入对应作用域路径并在写入前先删除两个方向的 toggle 文件以保证干净状态最后调用after_plugin_change()。这也是手动安装/更新后用于刷新框架缓存的那个 API——每次开关都会触发完整的缓存清理与前端通知。排查与进阶参考插件无法加载、崩溃或缺失时应转向专门的调试技能与框架文档插件架构总览plugins/AGENTS.md开发者生命周期指南docs/developer/plugins.md调试损坏插件a0-debug-plugin 技能创建新插件a0-create-plugin 技能评审插件a0-review-plugin 技能关键源码索引关注点位置插件安装/更新/索引 API 分发plugins/_plugin_installer/api/plugin_install.py安装流水线Git/ZIP/索引/钩子plugins/_plugin_installer/helpers/install.py同步安全扫描端点plugins/_plugin_scan/api/plugin_scan_run.py扫描 6 项检查的判定细则plugins/_plugin_scan/webui/plugin-scan-checks.jsontoggle 文件语义、卸载/删除限制、插件枚举helpers/plugins.py总结插件管理的安全心智模型回顾整套流程Agent Zero 插件管理的核心原则可以归纳为三点一切程序化操作走 HTTP API 与 CSRF 认证绝不在 Agent 运行时直接 import 框架模块每次安装前先扫描用 6 项检查报告Safe/Caution/Dangerous驱动安装决策区分自定义插件usr/plugins/与框架核心插件plugins/——前者可安装/更新/卸载后者只能停用。将这条技能文档与上述源码实现对照阅读即可获得从浏览发现、安全评估到全生命周期运维的完整闭环能力。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 插件管理完全指南：从 Plugin Hub 浏览、安全扫描到安装、更新、卸载与激活
Agent Zero 插件管理完全指南从 Plugin Hub 浏览、安全扫描到安装、更新、卸载与激活【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 的插件体系允许你通过 Plugin Hub、Git 仓库或 ZIP 包向框架注入工具、扩展点、WebUI 组件与自定义行为但第三方插件会在你的 Agent 环境中执行代码因此安全扫描与生命周期管理同样关键。本文以仓库中的官方技能 a0-manage-plugin/SKILL.md 为主体结合_plugin_installer、_plugin_scan两个内置插件与 helpers/plugins.py 的源码实现系统讲解插件的浏览、扫描、安装、更新、卸载与启用/停用全流程并给出可直接复制的 HTTP API 调用示例。读完本文你将掌握 Agent Zero 插件管理的标准操作与底层原理。技能定位a0-manage-plugin 负责什么官方技能 a0-manage-plugin版本 1.2.0的职责是拥有插件生命周期管理的完整工作流浏览与搜索插件、安全扫描、安装、更新、启用/停用、卸载以及基础的调试与排障引导。其触发词覆盖了绝大多数用户诉求install plugin/uninstall plugin/remove plugin/delete pluginupdate plugin/scan plugin/debug plugin/troubleshoot pluginbrowse plugins/search plugins/list pluginsplugin not working/enable plugin/disable plugin/plugin hub配套的维护说明 skills/a0-manage-plugin/AGENTS.md 明确了该技能的几个本地契约保持 Plugin Hub URL、安装 API 行为、扫描预期与激活语义与当前框架一致在安装流程之前必须对第三方插件执行风险发出警告不推荐在插件自有路径之外进行无管理的删除。需求路由表面对不同用户诉求技能文档给出了明确的跳转指引用户需求对应章节查找 / 搜索 / 浏览可用插件浏览 Plugin Hub扫描插件安全风险安全扫描安装插件安装插件更新已安装插件更新插件卸载 / 移除插件卸载插件启用或停用插件激活与停用插件加载失败 / 崩溃 / 缺失阅读 a0-debug-plugin 技能解释插件发现机制阅读 a0-debug-plugin 技能浏览与发现插件Plugin Hub 与本地目录拉取社区插件索引插件发现的第一步是从 Plugin Hub 拉取社区维护的插件索引。技能文档给出的标准做法是直接请求generated-index的index.jsonimport urllib.request, json url https://github.com/agent0ai/a0-plugins/releases/download/generated-index/index.json with urllib.request.urlopen(url, timeout30) as resp: index json.loads(resp.read()) plugins index.get(plugins, {})返回的plugins字典以插件名为键每个条目包含title、description、github、tags以及thumbnail可用时提供图片 URL。搜索插件的推荐方式是按关键词过滤title、description或tags字段。从源码看该索引的实际拉取实现在 plugins/_plugin_installer/helpers/install.py 的fetch_plugin_index()它同样请求上述 URL设置User-Agent: AgentZero并且当forceTrue时会在 URL 后附加时间戳参数并携带Cache-Control: no-cache/Pragma: no-cache强制绕过缓存这对于索引刷新场景很有用。列出本地已安装插件本地插件目录位于用户区usr/plugins/Docker 内对应/a0/usr/plugins/列出已安装插件ls usr/plugins/更完整的本地插件枚举由 helpers/plugins.py 的get_plugins_list()提供它同时扫描用户目录usr/plugins/与框架内置目录plugins/用户目录优先跳过隐藏目录以.开头只把包含plugin.yaml元数据文件的目录计入结果并对结果做缓存与排序。通过 WebUI 浏览另一种交互方式打开 Agent Zero 的Plugins 对话框切换到Browse标签页或在工具栏点击Install打开 Plugin Hub。WebUI 侧的浏览入口由_plugin_installer插件的扩展点提供见 plugins/_plugin_installer/extensions/webui 下的按钮与注解脚本。安装前的安全扫描_plugin_scan的 6 项检查Agent Zero 内置的_plugin_scan插件提供了一套LLM 驱动的安全扫描器描述见 plugins/_plugin_scan/plugin.yaml。它的工作方式是把仓库克隆下来、读取所有文件、运行 6 项 LLM 检查最终产出一份结构化 Markdown 报告。完整的检查定义位于 plugins/_plugin_scan/webui/plugin-scan-checks.json检查键名称关注点structure结构与用途匹配文件/目录是否与插件宣称的功能一致是否存在无关的数据访问codeReview静态代码审查SQL 注入、路径穿越、不安全的反序列化、对不可信输入的eval/exec、shell 注入、硬编码真实凭据、不安全的 ZIP/TAR 解压、越界破坏性文件操作、运行时拉取并执行远程代码agentManipulationAgent 操纵检测注释/字符串/文件名中的提示注入、要求忽略安全性的指令、隐藏指令base64、零宽字符、Unicode 技巧remoteComms远程通信与外部服务器的 HTTP/WebSocket/DNS 通信、隐藏遥测、远程代码加载、与插件用途不符的数据外传secrets机密与敏感数据访问环境变量、.env、API Key、令牌、Cookie、会话数据的访问范围与安全性obfuscation混淆与隐藏代码编码载荷base64/hex/rot13、运行时拼接敏感名称、动态导入、可疑的超长单行表达式、隐藏载荷扫描器对正常行为有明确的豁免规则例如集成类插件调用其声明服务的 API、OAuth/设备登录端点、Webhook 属于预期行为普通压缩/供应商前端资源、锁文件、测试夹具不视为混淆。只有未披露的主机、与用途不符的数据外传、故意隐藏行为的编码才会被判为失败。预安装扫描协议每次安装都建议执行技能文档要求在安装前始终主动提供扫描选项。若用户未明确拒绝应给出如下提示Before installing, I strongly recommend running a security scan on this plugin. Third-party plugins execute code inside your Agent Zero environment. Should I scan it first? The scan typically takes 2-4 minutes.如果用户拒绝则确认一次并警告Understood, skipping the scan. Note that installing unscanned third-party code carries security risks. Proceeding with installation.之后继续安装不要重复询问。运行扫描扫描通过 HTTP API 调用_plugin_scan的同步端点认证方式见下文API 认证小节# (after authentication setup - see Install section) resp s.post( f{BASE}/api/plugins/_plugin_scan/plugin_scan_run, json{ git_url: https://github.com/user/plugin-repo, checks: [structure, codeReview, agentManipulation, remoteComms, secrets, obfuscation], }, headers{X-CSRF-Token: token, Origin: ORIGIN}, timeout600, # 设得宽松一些——扫描会克隆仓库、读取全部文件并执行 6 项 LLM 检查 ) data resp.json()务必显式传入完整的checks列表——技能文档特别指出省略该参数已被观察到会导致间歇性失败。如需运行子集从列表中移除不需要的键即可。该端点的实现见 plugins/_plugin_scan/api/plugin_scan_run.py它把git_url与checks组合成提示词交由 Agent 上下文执行扫描然后返回{ ok: true, git_url: ..., report: markdown }。源码注释明确提醒服务端没有超时限制仓库扫描可能耗时 5 分钟以上客户端应自行设置足够的超时时间技能文档建议 600 秒。解读扫描结果report data[report] # 完整 markdown 安全报告将完整report呈现给用户。阅读Summary部分确定总体结论Safe/Caution/Dangerous并按如下规则行动结论处理方式Safe提议继续安装Caution展示发现的问题警告存在风险请求用户明确确认Some warnings were found. Do you still want to install?Dangerous展示发现的问题强烈建议不要安装The scanner flagged serious security issues. I strongly recommend NOT installing this plugin. Do you want to proceed anyway? 仅在用户明确确认后才安装如果扫描超时或返回 500 错误应告知用户并询问是否在无扫描的情况下继续。安装插件三条路径与一条铁律铁律走 HTTP API 或 UI绝不直接 import 框架模块技能文档给出了明确警告永远使用 HTTP API 或 UI 完成安装。不要从code_execution_tool直接导入 Agent Zero 框架模块——Agent 运行在独立的 Python 运行时Docker 内为/opt/venv中该环境并不具备框架的依赖。所有程序化安装都必须通过 HTTP 进行。已安装状态的判定机制Plugin Hub 在请求时通过将 Plugin Hub 键与usr/plugins/目录名做交叉比对来标记插件为Installed。要让插件显示为已安装需要满足插件目录必须存在于usr/plugins/name/且包含有效的plugin.yaml如果插件自带扩展点框架会在插件缓存刷新后将命名扩展点注册到extensions/python/point/下把隐式的extensible钩子注册到extensions/python/_functions/module/qualname/start|end/下框架插件缓存必须被清空API 会自动处理重新拉取 Plugin Hub 索引后即显示为已安装。这一定义与源码一致get_plugin_hub_index()见 plugins/_plugin_installer/helpers/install.py通过get_plugins_list()得到本地插件目录集合再与索引键比对生成installed_plugins列表同时会为缺少缩略图的旧安装回填thumbnail。API 认证所有 HTTP 调用的前置条件Agent Zero API 使用 CSRF 保护。Origin头始终必须携带——缺少它时即使登录已禁用CSRF 端点也会返回ok: false。Step 1设置基础 URL。Agent Zero 在 Docker 标准部署中监听 80 端口import requests BASE http://localhost # Docker 内为 80 端口 # 若在 Docker 外运行开发模式请检查os.environ.get(WEB_UI_PORT, 5000)Step 2引导会话并获取 CSRF tokens requests.Session() ORIGIN BASE # Origin 必须匹配 localhost 模式 r s.get(f{BASE}/api/csrf_token, headers{Origin: ORIGIN}, timeout10) data r.json() if not data.get(ok): raise RuntimeError(fCSRF bootstrap failed: {data.get(error)}) token data[token] runtime_id data[runtime_id] # 设置 CSRF cookie与 header 一起使用 s.cookies.set(fcsrf_token_{runtime_id}, token)后续所有 API 调用复用s、BASE、ORIGIN与token并且每次请求都必须携带headers{X-CSRF-Token: token, Origin: ORIGIN}。方法一从 Git URL 安装HTTP API程序化使用首选# (after authentication setup above) resp s.post( f{BASE}/api/plugins/_plugin_installer/plugin_install, json{ action: install_git, git_url: https://github.com/user/plugin-repo, # git_token: token, # 可选用于私有仓库 # plugin_name: override # 可选覆盖目录名 }, headers{X-CSRF-Token: token, Origin: ORIGIN}, timeout120, ) print(resp.json())这会在框架运行时内执行完整流水线clone → 校验 → 放入usr/plugins/→ 执行install钩子 → 清空插件缓存 → 通知前端。下一次拉取 Plugin Hub 索引时插件即显示为已安装。流水线的底层实现在install_from_git()plugins/_plugin_installer/helpers/install.py在临时目录克隆仓库clone_repo支持tokenvalidate_plugin_dir()检查plugin.yaml存在且可解析若指定了plugin_name还会校验元数据中的name与之一致check_plugin_conflict()检测同名插件是否已存在于usr/plugins/存在则抛错将目录移动到usr/plugins/name/_download_thumbnail()可选下载缩略图到webui/thumbnail.ext非致命失败run_install_hook()调用插件hooks.py中的install钩子检查是否含 Python 文件随后after_plugin_change([plugin_name], python_change...)完成缓存清理、模块刷新与前端通知。API 入口层面对这些动作的分发在 plugins/_plugin_installer/api/plugin_install.py 中它支持install_zip、install_git、update_plugin、fetch_index四种动作并将所有异常统一包装为{success: false, error: ...}返回。方法二从 Plugin Hub 安装UI交互使用首选打开 Plugins 对话框进入Browse标签页或点击Install找到插件、点击它、点击Install。UI 会处理一切包括在 Plugin Hub 视图中把插件标记为已安装。方法三从 ZIP 文件安装HTTP API# (after authentication setup above) with open(plugin.zip, rb) as f: resp s.post( f{BASE}/api/plugins/_plugin_installer/plugin_install, data{action: install_zip}, files{plugin_file: f}, headers{X-CSRF-Token: token, Origin: ORIGIN}, ) print(resp.json())或通过 UIPlugins 对话框 → Install → ZIP 标签页 → 上传文件。ZIP 路径的实现在install_uploaded_zip()/install_from_zip()plugins/_plugin_installer/helpers/install.py值得注意的安全细节上传文件先落盘到tmp/plugin_uploads/带时间戳与 UUID 的临时文件名解压前对每一个归档成员做路径穿越防护——成员真实路径必须位于解压目录之内否则抛出Unsafe path in archive错误_find_plugin_root()遍历解压目录定位plugin.yaml的父目录作为插件根无论成功失败finally块都会清理临时解压目录与归档文件。手动安装仅作为最后手段仅当 HTTP API 确实不可用时才使用注意import 报错不属于不可用那恰恰意味着你必须改用 HTTP APIgit clone https://github.com/user/repo usr/plugins/plugin_name克隆完成后插件已在磁盘上但框架并不知道它的存在。需要清空缓存并通知前端——可以通过调用 toggle API先关后开来触发内部的after_plugin_change()# (after authentication setup above) for state in [False, True]: s.post( f{BASE}/api/plugins, json{action: toggle_plugin, plugin_name: plugin_name, enabled: state}, headers{X-CSRF-Token: token, Origin: ORIGIN}, )或者直接重启 Agent Zero——启动时框架会重新完整扫描usr/plugins/。更新插件对比提交而不是版本号框架的更新流程现在会在把新代码拉入到位之前调用hooks.py中的pre_update()若存在该钩子更新完成后还会重新执行install()。检查是否有更新不要比较版本字符串。贡献者经常忘记递增版本号因此版本号相同不代表插件是最新的。应改为检查远端是否有新提交# 该插件是 git 仓库吗 git -C usr/plugins/name rev-parse --is-inside-work-tree 2/dev/null # 对比本地 HEAD 与远端 HEAD无需 fetch LOCAL$(git -C usr/plugins/name rev-parse HEAD) REMOTE$(git -C usr/plugins/name ls-remote origin HEAD | awk {print $1}) echo Local: $LOCAL echo Remote: $REMOTE [ $LOCAL $REMOTE ] echo Up to date || echo Update available若二者不同说明远端存在新提交——无论版本号字段是否变化都应向用户报告有可用更新。应用更新如果插件是通过 Git 安装的cd usr/plugins/name git pull origin main然后通过 toggle API 刷新框架缓存会话建立方式见上文API 认证# (after authentication setup) for state in [False, True]: s.post( f{BASE}/api/plugins, json{action: toggle_plugin, plugin_name: name, enabled: state}, headers{X-CSRF-Token: token, Origin: ORIGIN}, )如果不是 git 仓库通过 API 卸载见下节再按上面的 Git 方法重新安装。框架侧还提供了一条程序化更新路径_plugin_installer的update_plugin动作会调用update_from_git()plugins/_plugin_installer/helpers/install.py其流程为校验插件存在且位于usr/plugins/只有自定义插件可被更新→ 执行pre_update钩子 →git.update_repo()拉取 → 重新执行install钩子 →after_plugin_change()最后返回current_commit、current_commit_timestamp、branch、remote_url等元信息供前端展示。卸载插件安全规则与标准流程卸载前必读的安全规则核心插件位于plugins/而非usr/plugins/无法通过 API 卸载——框架会阻止该操作只能改用停用见下文激活小节。卸载前必须请求用户明确确认Are you sure you want to uninstallname? This will delete all plugin files and cannot be undone.卸载不会删除存放在usr/agents/或项目作用域中的插件配置文件。标准卸载通过 API使用框架的uninstall_plugin它会在删除前调用插件的uninstall钩子若已定义。需要已认证的会话见安装小节的 API 认证# (after authentication setup from the Install section) resp s.post( f{BASE}/api/plugins, json{ action: delete_plugin, plugin_name: name, }, headers{X-CSRF-Token: token, Origin: ORIGIN}, ) print(resp.json())这是推荐方式。框架将依次执行调用hooks.py中的uninstall()若存在——执行清理删除usr/plugins/name/目录通知前端刷新插件列表。通过 UIPlugins 对话框 → 找到插件 → 点击删除垃圾桶图标 → 确认。源码级依据uninstall_plugin()helpers/plugins.py先call_plugin_hook(plugin_name, uninstall)再调用delete_plugin()而delete_plugin()helpers/plugins.py会先通过find_plugin_dir()定位插件并校验其必须位于usr/plugins/之下——若位于内置plugins/则抛出Only custom plugins can be deleted。删除时还会顺带清理插件的关联资产目录如扩展点目录并携带python_change参数触发after_plugin_change()完成缓存与模块清理。兜底方案直接删除目录仅当标准卸载失败时使用例如uninstall钩子损坏导致崩溃或挂起# 确认该插件是自定义插件usr/plugins/ 下——绝不删除 plugins/ 下的内容 ls usr/plugins/name/ # 移除它 rm -rf usr/plugins/name/手动删除后通过 UI 刷新插件列表或重启 Agent Zero。激活与停用toggle 文件机制插件的启用/停用通过 toggle 文件实现.toggle-1 显式启用ON.toggle-0 显式停用OFF无文件 默认状态对大多数插件而言为启用这一约定与源码中的常量完全对应ENABLED_FILE_NAME .toggle-1、DISABLED_FILE_NAME .toggle-0见 helpers/plugins.py。启用插件rm -f usr/plugins/name/.toggle-0 touch usr/plugins/name/.toggle-1停用插件rm -f usr/plugins/name/.toggle-1 touch usr/plugins/name/.toggle-0通过 UIPlugins 对话框 → 找到插件 → 使用切换开关。plugin.yaml中带有always_enabled: true的插件无法被切换仅限框架核心插件使用例如_plugin_installer自身就声明了always_enabled: true见 plugins/_plugin_installer/plugin.yaml。状态判定的底层逻辑是 helpers/plugins.py 的determined_toggle_from_paths()插件默认启用遍历插件路径用户目录优先含代理/项目作用域覆盖时若当前为启用则检查是否存在.toggle-0存在即停用若为停用则检查是否存在.toggle-1存在即恢复启用。get_toggle_state()helpers/plugins.py对always_enabled的插件直接返回enabled。作用域切换Scoped Toggles当插件的plugin.yaml设置了per_project_config: true或per_agent_config: true时可使用 UI 中的 Switch 弹窗或把 toggle 文件放到对应的作用域路径下项目作用域project/.a0proj/plugins/name/.toggle-1代理档案作用域usr/agents/profile/plugins/name/.toggle-1API 层面由toggle_plugin()helpers/plugins.py承载它支持project_name、agent_profile参数写入对应作用域路径并在写入前先删除两个方向的 toggle 文件以保证干净状态最后调用after_plugin_change()。这也是手动安装/更新后用于刷新框架缓存的那个 API——每次开关都会触发完整的缓存清理与前端通知。排查与进阶参考插件无法加载、崩溃或缺失时应转向专门的调试技能与框架文档插件架构总览plugins/AGENTS.md开发者生命周期指南docs/developer/plugins.md调试损坏插件a0-debug-plugin 技能创建新插件a0-create-plugin 技能评审插件a0-review-plugin 技能关键源码索引关注点位置插件安装/更新/索引 API 分发plugins/_plugin_installer/api/plugin_install.py安装流水线Git/ZIP/索引/钩子plugins/_plugin_installer/helpers/install.py同步安全扫描端点plugins/_plugin_scan/api/plugin_scan_run.py扫描 6 项检查的判定细则plugins/_plugin_scan/webui/plugin-scan-checks.jsontoggle 文件语义、卸载/删除限制、插件枚举helpers/plugins.py总结插件管理的安全心智模型回顾整套流程Agent Zero 插件管理的核心原则可以归纳为三点一切程序化操作走 HTTP API 与 CSRF 认证绝不在 Agent 运行时直接 import 框架模块每次安装前先扫描用 6 项检查报告Safe/Caution/Dangerous驱动安装决策区分自定义插件usr/plugins/与框架核心插件plugins/——前者可安装/更新/卸载后者只能停用。将这条技能文档与上述源码实现对照阅读即可获得从浏览发现、安全评估到全生命周期运维的完整闭环能力。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考