Agent Zero 备份默认配置接口 backup_get_defaults 全解析从 API 契约到前端联动【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文围绕 Agent Zero 框架api/backup_get_defaults.py提供的backup_get_defaults后端 API 端点展开深入讲解它的职责边界、鉴权契约、响应数据结构、默认备份规则include/exclude 模式的生成逻辑以及它与 WebUI 设置页面的调用链路。读完本文你将掌握如何通过该接口获取“开箱即用”的备份元数据理解/usr数据目录与 Time Travel 历史目录为何被分别纳入与排除并能将这一端点与backup_test、backup_create等兄弟接口串成一条完整的备份工作流。一、端点定位备份功能的前置“默认值提供者”在 Agent Zero 的备份体系中backup_get_defaults是一个轻量级的只读 API它不做任何文件读写唯一职责是返回当前环境下解析完成的默认备份模式与元数据供前端表单、ACE 编辑器初始化、以及外部脚本使用。从源码结构看该端点由BackupGetDefaults类实现继承自helpers.api.ApiHandler基类定义见 helpers/api.pyclass BackupGetDefaults(ApiHandler): classmethod def requires_auth(cls) - bool: return True classmethod def requires_loopback(cls) - bool: return False async def process(self, input: dict, request: Request) - dict | Response: try: backup_service BackupService() default_metadata backup_service.get_default_backup_metadata() return { success: True, default_patterns: { include_patterns: default_metadata[include_patterns], exclude_patterns: default_metadata[exclude_patterns] }, metadata: default_metadata } except Exception as e: return { success: False, error: str(e) }整个处理逻辑只有三条路径实例化BackupService核心服务类见 helpers/backup.py调用get_default_backup_metadata()获取默认元数据成功时返回successTrue与default_patterns/metadata两个数据块失败时返回successFalse与error字符串。1.1 为什么需要后端解析默认模式一个关键设计点在于默认模式中的路径是运行时解析出的绝对路径而不是硬编码的相对路径。BackupService在初始化时通过files.get_abs_path()解析出 Agent Zero 根目录并在_get_default_patterns()中将其拼入模式串helpers/backup.py。因此前端无法也不应该自行生成这些模式——它必须询问后端才能获得与当前安装目录匹配的正确路径。这也是backup_get_defaults存在的根本意义。二、请求与响应契约2.1 请求方式ApiHandler基类默认注册为POST方法get_methods()返回[POST]见 helpers/api.py。调用backup_get_defaults时请求体可以为空 JSON{}端点不读取任何输入参数POST /backup_get_defaults Content-Type: application/json {}2.2 成功响应端点返回一个 JSON 对象结构如下{ success: true, default_patterns: { include_patterns: [ /data/.../agent-zero/usr/** ], exclude_patterns: [ /data/.../agent-zero/usr/.time_travel/** ] }, metadata: { backup_name: agent-zero-backup-2026-09-12, include_hidden: true, include_patterns: [ /data/.../agent-zero/usr/** ], exclude_patterns: [ /data/.../agent-zero/usr/.time_travel/** ], backup_config: { compression_level: 6, integrity_check: true } } }字段含义如下字段类型说明successbool请求是否成功default_patterns.include_patternsstring[]默认包含模式绝对路径**通配default_patterns.exclude_patternsstring[]默认排除模式已去除!前缀metadata.backup_namestring建议的备份文件名形如agent-zero-backup-YYYY-MM-DD由Localization.get().now_iso()取当天日期生成metadata.include_hiddenbool是否包含隐藏文件默认truemetadata.backup_config.compression_levelintZIP 压缩级别默认6metadata.backup_config.integrity_checkbool是否启用完整性校验默认true其中metadata是get_default_backup_metadata()的完整返回值见 helpers/backup.pydefault_patterns是其子集专门提供给前端快速取用模式数组。2.3 失败响应当BackupService实例化或元数据生成抛出异常时例如 Agent Zero 根目录异常返回{ success: false, error: 异常信息 }注意与backup_create、backup_test等端点一致该端点采用返回式错误HTTP 200 JSONsuccess:false而非 HTTP 500便于前端统一分支处理。三、鉴权与安全契约BackupGetDefaults覆写了两个类级方法行为如下requires_auth()返回True端点需要登录会话session鉴权requires_loopback()返回False不要求请求必须来自本机回环地址允许远程 WebUI 正常访问。此外它继承了ApiHandler基类的其余安全约定helpers/api.pyrequires_api_key()默认返回Falserequires_csrf()默认与requires_auth()保持一致即开启鉴权时同时要求 CSRF 防护。端点对应的 DOX 文档api/backup_get_defaults.py.dox.md明确要求除非端点契约显式变更否则必须保留鉴权、CSRF、回环与 API Key 检查当响应结构变化时需同步更新前端调用方、插件调用方与测试。由于get_default_backup_metadata()只返回内存中的默认值、不触碰磁盘该端点没有文件系统读写、删除或持久化副作用是一个纯查询型端点。四、默认模式的生成原理4.1 默认模式串BackupService._get_default_patterns()返回的模式串在注释中说明了设计意图——所有持久化用户数据集中到/usr目录以便统一备份与恢复# User data # All persistent user data is now centralized in /usr for easier backup and restore {agent_zero_root}/usr/** !{agent_zero_root}/usr/.time_travel/**即包含Agent Zero 根目录/usr/**全部用户持久化数据排除Agent Zero 根目录/usr/.time_travel/**Time Travel 的历史快照影子目录。4.2 模式解析_parse_patterns原始模式串经过_parse_patterns()helpers/backup.py按行解析空行与#开头的注释行被跳过以!开头的行视为排除模式去掉!前缀后放入exclude_patterns其余行视为包含模式放入include_patterns。4.3 为什么排除 Time Travel 历史usr/.time_travel/**存放的是 Time Travel 功能的时间线快照体积大且属于可重建的派生数据。测试 tests/test_backup_large_archives.py 专门验证了这一行为pytest.mark.asyncio async def test_default_backup_patterns_exclude_time_travel_history(tmp_path): ... files await service.test_patterns(metadata, max_filesNone) paths {item[real_path] for item in files} assert str(usr / settings.json) in paths assert str(time_travel / objects.pack) not in paths assert f{root}/usr/.time_travel/** in metadata[exclude_patterns]该测试同时印证了两个事实get_default_backup_metadata()的返回值可直接喂给test_patterns()用于扫描文件清单且默认模式串保证/usr下普通数据被包含、Time Travel 历史被排除。4.4 与include_hidden的配合get_default_backup_metadata()返回的include_hiddenTrue意味着模式扫描时会遍历.time_travel这类隐藏目录——但因为它已被显式列入exclude_patterns匹配阶段仍会被pathspecgitwildmatch 语法见test_patterns中PathSpec.from_lines(gitwildmatch, pattern_lines)helpers/backup.py排除。这是“显式排除优先于隐藏目录遍历”的典型组合用法。五、前端联动WebUI 设置页如何消费该端点backup_get_defaults的实际消费者是 WebUI 备份设置组件 webui/components/settings/backup/backup-store.js。其getDefaultBackupMetadata()方法直接调用后端async getDefaultBackupMetadata() { const timestamp getCurrentUserISOString(); try { // Get resolved default patterns from backend const response await sendJsonData(backup_get_defaults, {}); if (response.success) { const include_patterns response.default_patterns.include_patterns; const exclude_patterns response.default_patterns.exclude_patterns; return { backup_name: agent-zero-backup-${getCurrentUserDateString()}, include_hidden: true, include_patterns: include_patterns, exclude_patterns: exclude_patterns, backup_config: { compression_level: 6, integrity_check: true } }; } } catch (error) { console.warn(Failed to get default patterns from backend, using fallback); } // Fallback patterns (will be overridden by backend on first use) ... }从中可以看到明确的调用约定前端以空对象{}调用端点成功后只取response.default_patterns而非metadata本地再自行补充backup_name等展示字段失败或异常时降级为本地兜底 JSONinclude_patterns中占位为注释行# Loading default patterns from backend...等下一次成功调用后由后端覆盖。这一兜底设计说明该端点对 WebUI 而言是模式数据的唯一权威来源前端自身不硬编码任何绝对路径。拿到默认元数据后前端将其灌入 ACE 编辑器initBackupEditor()中editor.setValue(JSON.stringify(defaultMetadata, null, 2))用户在编辑器内可继续修改模式再由backup_preview_grouped预览、backup_test干跑、backup_create实际打包等端点接力完成后续流程。六、与兄弟端点构成的备份工作流backup_get_defaults处于备份工作流的最上游与以下端点共同构成完整链路相关实现均位于 api/ 目录端点文件职责backup_get_defaultsapi/backup_get_defaults.py返回默认模式与元数据本文主题backup_preview_groupedapi/backup_preview_grouped.py按目录分组预览将要打包的文件backup_testapi/backup_test.py干跑根据模式扫描并返回匹配文件清单支持max_files截断backup_createapi/backup_create.py依据模式创建 ZIP 归档并返回文件下载backup_inspect/backup_restore_preview/backup_restore对应backup_*.py归档检查、恢复预览与实际恢复以一次典型操作为例前端初始化备份页 → 调用backup_get_defaults拿到默认include_patterns/exclude_patterns→ 用户在 ACE 编辑器中修改 → 调用backup_test或backup_preview_grouped验证文件清单 → 确认无误后调用backup_create生成 ZIP。其中backup_create还会先调用save_tmp_chats()把临时会话持久化到 chats 目录确保聊天记录一并进入备份见 api/backup_create.py。七、验证与测试建议端点对应的 DOX 文档在“Verification”一节指出源码中未找到直接按名称引用backup_get_defaults的测试因此变更时需选择最近的行为测试或进行浏览器冒烟验证。可参考的验证路径包括单元级BackupService.get_default_backup_metadata()的返回值可直接用 tests/test_backup_large_archives.py 中test_default_backup_patterns_exclude_time_travel_history的模式进行断言验证 include/exclude 语义正确接口级向/backup_get_defaults发送空 POST断言success为true且default_patterns与metadata中模式数组一致、backup_config.compression_level 6、integrity_check true端到端在 WebUI 备份设置页打开备份面板确认 ACE 编辑器初始内容中出现以当前 Agent Zero 根目录开头的绝对路径模式且不包含usr/.time_travel/**之外的多余排除项。八、总结backup_get_defaults是 Agent Zero 备份能力中一个“小而关键”的端点它没有复杂的业务逻辑却承担着默认备份策略的权威下发职责。通过它前端与第三方调用方无需关心 Agent Zero 安装路径、隐藏文件策略与压缩参数等环境细节即可获得一份开箱即用、路径已解析的备份元数据。理解它的响应结构与生成逻辑是进一步掌握backup_test、backup_create、backup_restore等完整备份/恢复工作流的第一步。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Zero 备份默认配置接口 backup_get_defaults 全解析：从 API 契约到前端联动
Agent Zero 备份默认配置接口 backup_get_defaults 全解析从 API 契约到前端联动【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文围绕 Agent Zero 框架api/backup_get_defaults.py提供的backup_get_defaults后端 API 端点展开深入讲解它的职责边界、鉴权契约、响应数据结构、默认备份规则include/exclude 模式的生成逻辑以及它与 WebUI 设置页面的调用链路。读完本文你将掌握如何通过该接口获取“开箱即用”的备份元数据理解/usr数据目录与 Time Travel 历史目录为何被分别纳入与排除并能将这一端点与backup_test、backup_create等兄弟接口串成一条完整的备份工作流。一、端点定位备份功能的前置“默认值提供者”在 Agent Zero 的备份体系中backup_get_defaults是一个轻量级的只读 API它不做任何文件读写唯一职责是返回当前环境下解析完成的默认备份模式与元数据供前端表单、ACE 编辑器初始化、以及外部脚本使用。从源码结构看该端点由BackupGetDefaults类实现继承自helpers.api.ApiHandler基类定义见 helpers/api.pyclass BackupGetDefaults(ApiHandler): classmethod def requires_auth(cls) - bool: return True classmethod def requires_loopback(cls) - bool: return False async def process(self, input: dict, request: Request) - dict | Response: try: backup_service BackupService() default_metadata backup_service.get_default_backup_metadata() return { success: True, default_patterns: { include_patterns: default_metadata[include_patterns], exclude_patterns: default_metadata[exclude_patterns] }, metadata: default_metadata } except Exception as e: return { success: False, error: str(e) }整个处理逻辑只有三条路径实例化BackupService核心服务类见 helpers/backup.py调用get_default_backup_metadata()获取默认元数据成功时返回successTrue与default_patterns/metadata两个数据块失败时返回successFalse与error字符串。1.1 为什么需要后端解析默认模式一个关键设计点在于默认模式中的路径是运行时解析出的绝对路径而不是硬编码的相对路径。BackupService在初始化时通过files.get_abs_path()解析出 Agent Zero 根目录并在_get_default_patterns()中将其拼入模式串helpers/backup.py。因此前端无法也不应该自行生成这些模式——它必须询问后端才能获得与当前安装目录匹配的正确路径。这也是backup_get_defaults存在的根本意义。二、请求与响应契约2.1 请求方式ApiHandler基类默认注册为POST方法get_methods()返回[POST]见 helpers/api.py。调用backup_get_defaults时请求体可以为空 JSON{}端点不读取任何输入参数POST /backup_get_defaults Content-Type: application/json {}2.2 成功响应端点返回一个 JSON 对象结构如下{ success: true, default_patterns: { include_patterns: [ /data/.../agent-zero/usr/** ], exclude_patterns: [ /data/.../agent-zero/usr/.time_travel/** ] }, metadata: { backup_name: agent-zero-backup-2026-09-12, include_hidden: true, include_patterns: [ /data/.../agent-zero/usr/** ], exclude_patterns: [ /data/.../agent-zero/usr/.time_travel/** ], backup_config: { compression_level: 6, integrity_check: true } } }字段含义如下字段类型说明successbool请求是否成功default_patterns.include_patternsstring[]默认包含模式绝对路径**通配default_patterns.exclude_patternsstring[]默认排除模式已去除!前缀metadata.backup_namestring建议的备份文件名形如agent-zero-backup-YYYY-MM-DD由Localization.get().now_iso()取当天日期生成metadata.include_hiddenbool是否包含隐藏文件默认truemetadata.backup_config.compression_levelintZIP 压缩级别默认6metadata.backup_config.integrity_checkbool是否启用完整性校验默认true其中metadata是get_default_backup_metadata()的完整返回值见 helpers/backup.pydefault_patterns是其子集专门提供给前端快速取用模式数组。2.3 失败响应当BackupService实例化或元数据生成抛出异常时例如 Agent Zero 根目录异常返回{ success: false, error: 异常信息 }注意与backup_create、backup_test等端点一致该端点采用返回式错误HTTP 200 JSONsuccess:false而非 HTTP 500便于前端统一分支处理。三、鉴权与安全契约BackupGetDefaults覆写了两个类级方法行为如下requires_auth()返回True端点需要登录会话session鉴权requires_loopback()返回False不要求请求必须来自本机回环地址允许远程 WebUI 正常访问。此外它继承了ApiHandler基类的其余安全约定helpers/api.pyrequires_api_key()默认返回Falserequires_csrf()默认与requires_auth()保持一致即开启鉴权时同时要求 CSRF 防护。端点对应的 DOX 文档api/backup_get_defaults.py.dox.md明确要求除非端点契约显式变更否则必须保留鉴权、CSRF、回环与 API Key 检查当响应结构变化时需同步更新前端调用方、插件调用方与测试。由于get_default_backup_metadata()只返回内存中的默认值、不触碰磁盘该端点没有文件系统读写、删除或持久化副作用是一个纯查询型端点。四、默认模式的生成原理4.1 默认模式串BackupService._get_default_patterns()返回的模式串在注释中说明了设计意图——所有持久化用户数据集中到/usr目录以便统一备份与恢复# User data # All persistent user data is now centralized in /usr for easier backup and restore {agent_zero_root}/usr/** !{agent_zero_root}/usr/.time_travel/**即包含Agent Zero 根目录/usr/**全部用户持久化数据排除Agent Zero 根目录/usr/.time_travel/**Time Travel 的历史快照影子目录。4.2 模式解析_parse_patterns原始模式串经过_parse_patterns()helpers/backup.py按行解析空行与#开头的注释行被跳过以!开头的行视为排除模式去掉!前缀后放入exclude_patterns其余行视为包含模式放入include_patterns。4.3 为什么排除 Time Travel 历史usr/.time_travel/**存放的是 Time Travel 功能的时间线快照体积大且属于可重建的派生数据。测试 tests/test_backup_large_archives.py 专门验证了这一行为pytest.mark.asyncio async def test_default_backup_patterns_exclude_time_travel_history(tmp_path): ... files await service.test_patterns(metadata, max_filesNone) paths {item[real_path] for item in files} assert str(usr / settings.json) in paths assert str(time_travel / objects.pack) not in paths assert f{root}/usr/.time_travel/** in metadata[exclude_patterns]该测试同时印证了两个事实get_default_backup_metadata()的返回值可直接喂给test_patterns()用于扫描文件清单且默认模式串保证/usr下普通数据被包含、Time Travel 历史被排除。4.4 与include_hidden的配合get_default_backup_metadata()返回的include_hiddenTrue意味着模式扫描时会遍历.time_travel这类隐藏目录——但因为它已被显式列入exclude_patterns匹配阶段仍会被pathspecgitwildmatch 语法见test_patterns中PathSpec.from_lines(gitwildmatch, pattern_lines)helpers/backup.py排除。这是“显式排除优先于隐藏目录遍历”的典型组合用法。五、前端联动WebUI 设置页如何消费该端点backup_get_defaults的实际消费者是 WebUI 备份设置组件 webui/components/settings/backup/backup-store.js。其getDefaultBackupMetadata()方法直接调用后端async getDefaultBackupMetadata() { const timestamp getCurrentUserISOString(); try { // Get resolved default patterns from backend const response await sendJsonData(backup_get_defaults, {}); if (response.success) { const include_patterns response.default_patterns.include_patterns; const exclude_patterns response.default_patterns.exclude_patterns; return { backup_name: agent-zero-backup-${getCurrentUserDateString()}, include_hidden: true, include_patterns: include_patterns, exclude_patterns: exclude_patterns, backup_config: { compression_level: 6, integrity_check: true } }; } } catch (error) { console.warn(Failed to get default patterns from backend, using fallback); } // Fallback patterns (will be overridden by backend on first use) ... }从中可以看到明确的调用约定前端以空对象{}调用端点成功后只取response.default_patterns而非metadata本地再自行补充backup_name等展示字段失败或异常时降级为本地兜底 JSONinclude_patterns中占位为注释行# Loading default patterns from backend...等下一次成功调用后由后端覆盖。这一兜底设计说明该端点对 WebUI 而言是模式数据的唯一权威来源前端自身不硬编码任何绝对路径。拿到默认元数据后前端将其灌入 ACE 编辑器initBackupEditor()中editor.setValue(JSON.stringify(defaultMetadata, null, 2))用户在编辑器内可继续修改模式再由backup_preview_grouped预览、backup_test干跑、backup_create实际打包等端点接力完成后续流程。六、与兄弟端点构成的备份工作流backup_get_defaults处于备份工作流的最上游与以下端点共同构成完整链路相关实现均位于 api/ 目录端点文件职责backup_get_defaultsapi/backup_get_defaults.py返回默认模式与元数据本文主题backup_preview_groupedapi/backup_preview_grouped.py按目录分组预览将要打包的文件backup_testapi/backup_test.py干跑根据模式扫描并返回匹配文件清单支持max_files截断backup_createapi/backup_create.py依据模式创建 ZIP 归档并返回文件下载backup_inspect/backup_restore_preview/backup_restore对应backup_*.py归档检查、恢复预览与实际恢复以一次典型操作为例前端初始化备份页 → 调用backup_get_defaults拿到默认include_patterns/exclude_patterns→ 用户在 ACE 编辑器中修改 → 调用backup_test或backup_preview_grouped验证文件清单 → 确认无误后调用backup_create生成 ZIP。其中backup_create还会先调用save_tmp_chats()把临时会话持久化到 chats 目录确保聊天记录一并进入备份见 api/backup_create.py。七、验证与测试建议端点对应的 DOX 文档在“Verification”一节指出源码中未找到直接按名称引用backup_get_defaults的测试因此变更时需选择最近的行为测试或进行浏览器冒烟验证。可参考的验证路径包括单元级BackupService.get_default_backup_metadata()的返回值可直接用 tests/test_backup_large_archives.py 中test_default_backup_patterns_exclude_time_travel_history的模式进行断言验证 include/exclude 语义正确接口级向/backup_get_defaults发送空 POST断言success为true且default_patterns与metadata中模式数组一致、backup_config.compression_level 6、integrity_check true端到端在 WebUI 备份设置页打开备份面板确认 ACE 编辑器初始内容中出现以当前 Agent Zero 根目录开头的绝对路径模式且不包含usr/.time_travel/**之外的多余排除项。八、总结backup_get_defaults是 Agent Zero 备份能力中一个“小而关键”的端点它没有复杂的业务逻辑却承担着默认备份策略的权威下发职责。通过它前端与第三方调用方无需关心 Agent Zero 安装路径、隐藏文件策略与压缩参数等环境细节即可获得一份开箱即用、路径已解析的备份元数据。理解它的响应结构与生成逻辑是进一步掌握backup_test、backup_create、backup_restore等完整备份/恢复工作流的第一步。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考