支持TenBox Agent 数据迁移、备份和诊断工具(Agent急救箱)

[luoyuctl]

Closes #126
Closes #127
Closes #128
Closes #134

变更内容

• 新增 TenBox 桌面端 Agent 急救箱，不修改 rootfs / 镜像，也不要求镜像预置 tenbox-agent-* 脚本。
• macOS：通过 qemu guest agent guest-exec 执行 guest 内命令；保留 console marker 历史 fallback，并修复大段 console 输入溢出问题。
• Windows：补齐 Manager 侧 guest-exec 请求/响应通道、runtime-only shared folder 更新、AgentToolsService C++ 实现和 Win32「Agent 急救箱」对话框。
• 支持 Hermes / OpenClaw Agent profile 迁移包导出 / 导入，包格式记录在 docs/agent-profile.md，包含 manifest、export_scope，并拒绝跨 Agent 导入。
• 支持宿主侧 Agent 数据保护：立即备份、恢复最新备份、打开备份目录、定时自动备份、保留数量轮转。
• 支持 Agent 一键诊断与受控修复：健康状态、重启服务、模型连接测试、重置模型配置、导出诊断包；修复前会先创建宿主侧备份。
• 支持 OpenClaw 到 Hermes 自动迁移：先备份目标 Hermes，再导出来源 OpenClaw 完整用户状态，调用官方 hermes claw migrate dry-run 和正式迁移；不在 TenBox 内重写迁移映射。
• OpenClaw 到 Hermes 迁移支持 --migrate-secrets、技能冲突策略（skip / overwrite / rename）、--workspace-target，并保存 dry-run / 正式迁移报告到宿主机备份目录。
• 修复迁移到一半 TenBox 整体卡住转圈：guest-exec 和 runtime shared-folder IPC send 改为后台串行队列，UI 只做请求登记和状态更新；迁移大输出截断回传，完整内容写报告。
• Agent 工具临时共享目录改为 runtime-only，不再写入 VM config；启动/读取配置时清理旧版本残留的 tenbox-agent-ops-* / tenbox-agent-backups-*。
• 修复 Export 点击卡住路径：文件选择面板改为异步 sheet/window panel，不再在 SwiftUI 按钮处理里同步 runModal()。
• 调整 macOS UI：工具入口改为「Agent急救箱」，默认突出一键诊断、备份和建议修复，低频/破坏性操作收进高级操作并增加确认。
• Hermes 导出只保留用户/config/state 数据，排除可重装 app checkout、venv/bin、logs/cache、gateway pid/lock；OpenClaw 迁移导出保留密钥、身份、会话、浏览器配置等用户状态，仅排除 cache/logs。
• OpenClaw -> Hermes 迁移后恢复 TenBox 模型代理配置，并把 OpenClaw openclaw.json 中的 Feishu / WeCom channel 配置迁移到 Hermes .env。
• 更新 docs/agent-profile.md 和 CLAUDE.md，记录 Agent profile 包格式、迁移范围、共享目录、Windows 路径、响应性和操作约束。

覆盖的 Issue

• 定义 Agent profile 迁移包，支持非技术用户导出/导入 Agent 数据 #126：Agent profile 迁移包导出 / 导入，以及包格式文档。
• 默认保护 Agent 数据：自动备份、删除保留、升级前快照和一键恢复 #127：宿主侧备份、恢复、定时备份和保留策略。
• 新增 Agent 健康页和人话错误提示，提供一键诊断与受控修复 #128：Agent 健康页、一键诊断、人话错误、重启 / 重置 / 诊断包等受控修复入口。
• 修复 OpenClaw 到 Hermes 迁移过程中 TenBox UI 卡住 #134：OpenClaw 到 Hermes 迁移过程 UI 卡住、无进度提示、迁移报告缺失。

验证

• git diff --check 通过。
• clang++ -std=c++20 -fsyntax-only -I src -I build/cmake-arm64/_deps/libuv-src/include src/manager/agent_tools_service.cpp 通过；仅有仓库已有的 VmRuntimeHandle defaulted move warning。
• swift build -c release --arch arm64 通过。
• ./scripts/build-macos.sh --release 通过，生成 universal build/TenBox-0.8.0.app 和 ZIP。
• 已验证 OpenClaw -> Hermes 真实迁移：48 migrated, 18 skipped，Feishu / WeCom channel 配置迁移成功，Hermes health ok。
• 之前已在四个本机镜像跑过 VM 内功能链路：
  • hermes-arm64-0.11.0
  • hermes-fcitx5-arm64-0.11.0
  • openclaw-arm64-2026.3.23-2
  • openclaw-arm64-2026.4.1
• 覆盖 export/import、backup snapshot/restore、scheduled backup path、health、restart、reset config、diagnostics、repair pre-backup、model-test command path。
• Hermes profile/backup 约 2.3M；OpenClaw profile/backup 约 4K-8K；排除路径检查通过。
• review app 曾重新替换，codesign --verify --deep --strict 通过，直接启动通过。
• 新版启动后已验证旧 VM config 中残留的 6 个 tenbox-agent-* 临时 share 被清理为 0。

说明

• 本地没有 Windows 交叉编译器（x86_64-w64-mingw32-g++）和 ninja，所以 Windows 完整构建需要交给 Windows/CI 环境跑；本轮已做 C++ 业务层语法检查和 Win32 代码人工检查。
• 本地没有 Sparkle EdDSA 发布私钥，build-macos.sh --release 的 ZIP 签名步骤会提示缺少 key，但脚本最终成功产出 app/zip；这是发布签名材料问题，不是代码编译失败。
• 当前宿主未配置模型代理时，model test 返回 expected unavailable；命令链路、退出处理和 UI 结果路径已覆盖。

[luoyuctl]

补充修复：已修复 review app 启动时 Sparkle.framework 被 hardened runtime library validation 拦截的问题。新增 com.apple.security.cs.disable-library-validation entitlement 后重新构建并覆盖本地 app；codesign --verify --deep --strict 通过，直接执行 TenBoxManager 保持运行 3 秒，未再出现 dyld Sparkle 缺库/签名崩溃。最新提交：2da2959。

[luoyuctl]

验证更新：已把最新修复推到 a7b4de2，并重新生成 review app。\n\n这次同步了 agent tool 的共享目录等待和 shell begin-marker 快速失败处理；repair 前置备份、diagnostics 导出、restart/reset/model-test 都走同一套更稳的命令链路。\n\n已跑四个本机镜像的 VM 内功能链路：\n- hermes-arm64-0.11.0: health、restart、reset config、diagnostics、repair pre-backup、model-test command path OK；profile/backup 约 2.3M；排除 Hermes app checkout、venv/bin、logs/cache、gateway pid/lock。\n- hermes-fcitx5-arm64-0.11.0: 同上 OK；profile/backup 约 2.3M；排除项 OK。\n- openclaw-arm64-2026.3.23-2: health、restart、reset config、diagnostics、repair pre-backup、model-test command path OK；profile/backup 约 4K；排除 cache OK。\n- openclaw-arm64-2026.4.1: 同上 OK；profile/backup 约 8K；排除 cache OK。\n\n构建校验：swift build -c debug --package-path src/manager-macos 通过；./scripts/build-macos.sh --debug 通过；review app codesign verify 通过；TenBoxManager 直接启动通过。\n\n说明：model test 在当前宿主未配置模型代理时返回 expected unavailable，但命令链路、退出处理和 UI 结果路径已覆盖。

[luoyuctl]

补充修复：同步了 Export/Import 点击卡住相关修复，已推到 eea9dcd。\n\n修复点：\n- 文件选择面板从同步 runModal() 改为异步 sheet/window panel，避免阻塞 SwiftUI sheet 的按钮路径。\n- Agent 工具临时共享目录改为 runtime-only，不再持久化到 VM config。\n- 启动/读取配置时清理旧版本残留的 tenbox-agent-ops-* / tenbox-agent-backups-* share。\n\n验证：\n- swift build -c debug --package-path src/manager-macos 通过。\n- ./scripts/build-macos.sh --debug 通过，review app 已重新替换。\n- review app codesign verify 通过，直接启动通过。

[whitefirer]

只做了mac的么，windows的有计划做么

[78]

这个是用tty和shared folder来做的？

如果用 QMP 协议可能会更简单：https://qemu-project.gitlab.io/qemu/interop/qemu-ga-ref.html

使用 QMP 执行 guest bash 命令打包备份数据，还能得到运行的结果（包括exit code和stdout/stderr）。然后通过 guest-file-open 和 guest-file-read 来读取文件内容。

[luoyuctl]

只做了mac的么，windows的有计划做么

先跑通，复制应该不难 @whitefirer

[luoyuctl]

这个是用tty和shared folder来做的？

如果用 QMP 协议可能会更简单：https://qemu-project.gitlab.io/qemu/interop/qemu-ga-ref.html

使用 QMP 执行 guest bash 命令打包备份数据，还能得到运行的结果（包括exit code和stdout/stderr）。然后通过 guest-file-open 和 guest-file-read 来读取文件内容。

@78 对，我研究下

[luoyuctl]

mac下已跑通，并且支持了openclaw一键迁移hermes @78

[luoyuctl]

补了一轮自测后的硬化和验证。

本次追加：

• 修复 guest 脚本归档校验失败未中止的问题，导入/迁移遇到非法 archive 会立即失败。
• 禁止 tar 中的 symlink/hardlink/特殊设备等非普通文件/目录成员。
• 导入 profile 时增加失败回滚，避免先挪走旧配置后解包失败导致配置丢失。
• 导出 profile/OpenClaw 源包时增加 mv 失败后的 cp && rm 兜底，修掉 Computer Use 实测中 virtiofs 下 UI 显示备份完成但 host 只留下 .tmp 文件的问题。
• 新增 tests/test_agent_tools_guest.sh，覆盖导出/导入、跨 Agent 拒绝、危险 archive 拒绝、导入回滚、OpenClaw 导出、迁移缺 Hermes 失败、迁移 dry-run/apply 成功参数和配置合并路径。

验证：

• Computer Use 跑了 macOS app bundle，启动 VM 0.5.8，打开 Agent 急救箱，验证 guest execution 已连接。
• Hermes：一键诊断通过；备份在缺 /home/tenbox/.hermes 时按预期失败并展示错误。
• OpenClaw：一键诊断通过；备份通过并在 host 生成最终 .tar.gz 和 manifest；诊断包导出通过；定时备份开关 UI 状态正常；恢复/重置/导入的确认和文件面板流程正常；迁移导出包通过。
• 迁移 apply 的 UI 端因为当前没有两台同时运行的 OpenClaw/Hermes VM，实机只验证到禁用态；guest 脚本成功/失败路径已用 fake Hermes 测试覆盖。
• 验证后关闭 app、停止 VM，清理生成的大备份、迁移包、诊断文件和 AgentOperations 临时目录。

本地检查：

• sh -n src/agent_tools/guest/agent_tools.sh
• sh -n tests/test_agent_tools_guest.sh
• sh tests/test_agent_tools_guest.sh src/agent_tools/guest/agent_tools.sh
• ctest --test-dir build-agent-tools-make-check --output-on-failure --timeout 30
• cmake --build build-agent-tools-make-check --target tenbox-vm-runtime
• swift build -c debug in src/manager-macos
• ./scripts/build-macos.sh --debug built the app bundle; Sparkle update signing waited for key input after bundle assembly, so I re-signed and verified the .app manually.
• codesign --verify --deep --strict build/TenBox-0.8.0.app
• git diff --check

CI on head 5d39ddf is green:

• Build Website
• Build .deb (amd64)
• Build .deb (arm64)
• Build C++ Project (windows-latest)

[luoyuctl]

更新：已补完备份和迁移回归修复，并做了真实 VM 验证。

• Hermes 备份：容忍 GNU tar live churn 的两个良性 warning：file changed as we read it / File removed before we read it；混合真实错误仍失败。
• OpenClaw 迁移包：排除嵌套 node_modules、浏览器 Singleton* runtime locks，并把有效 skill symlink 解引用成普通文件，继续保持严格归档校验。
• Hermes 迁移：提取目录改到共享迁移包旁边，避免目标 VM /tmp 小盘写满；tar 解包加 -m，避开 virtiofs mtime 恢复失败；--overwrite 改为 hermes claw migrate --overwrite 子命令参数；报告出现 Refusing to apply 即失败，避免 UI 假成功。
• 自测：sh -n、tests/test_agent_tools_guest.sh、ctest --test-dir build-agent-tools-make-check --output-on-failure --timeout 30、cmake --build build-agent-tools-make-check --target tenbox-vm-runtime、git diff --check 均通过。
• Computer Use 实测：openclaw 迁移到 hermes-arm64-2 完整成功；最终报告 openclaw-migration-2026-05-14-075904.txt 为 Mode: apply、Overwrite: yes、74 migrated, 18 skipped，包含 ✓ Migration complete! 和 Migration completed.，未再出现 Refusing to apply / unrecognized arguments / Cannot utime / Wrote only。

Commit: b7828ad