nw-db-backup（数据库备份自动下载 · 可分发版）
特点
- 可移植：整个 skill 文件夹复制到任意机器即可用，所有路径基于 skill 自身目录自动计算，不写死用户名/机器路径
- 依赖自举：首次运行若环境无
paramiko，会自动在 skill 内创建.venv并安装；也可手动scripts/setup.sh预装 - 配置外置 + 密码加密：参数写在
config/backup_config.md，密码以enc:前缀加密存储（密钥在本机config/.key，不随 skill 分发），明文不落盘。推荐用「对话式配置」写入，避免手工改文件 - 只下载当天备份：脚本筛选「文件名含今天日期（如 2026-08-12）且以 .gz 结尾」的文件，只下载当天的那一份（同一天多份则取文件名最大者）
- 大文件可靠下载（40GB+ 已修复）：禁用 paramiko 默认 prefetch（>4GB 会在约 4GB 处中断），改为分块顺序下载 + 断点续传 + 连接中断自动重试；下载后按远程大小校验，本地已存在但不完整的不再被「永久跳过」，而是自动续传/重下
- 一键创建自动化：提供
scripts/configure_automation.py，读取配置后生成自动化参数，agent 运行一次即建好每日自动化（注意：skill 安装本身不会自动创建，需要告诉 agent 执行这一步） - 支持密码认证或密钥认证，自动筛选最新可用备份、gzip 校验、按保留天数清理
对话式配置（推荐，不用手工改文件）
> 最省事、也最安全的方式：直接和 agent 对话就能把配置写进去，而且密码会自动加密。
你只需要把配置信息贴给 agent，并说一句「请帮我配置」，agent 会自动：
1. 把明文密码加密；
2. 写入 config/backup_config.md（密码为 enc: 密文，密钥在本机 config/.key）；
3. （可选）顺手帮你把每日自动化也建好。
完整交互示例、幕后流程与安全说明见同目录 配置指南.md。
安装到其他 WorkBuddy
- 把整个
nw-db-backup文件夹复制到目标机器的技能目录：
- 用户级：~/.workbuddy/skills/nw-db-backup/
- 项目级：<工作区>/.workbuddy/skills/nw-db-backup/ - 配置服务器信息（二选一）：① 最简单——直接对 agent 说「我的配置信息是……请帮我配置」，agent 会自动加密写入；② 或手工编辑
config/backup_config.md - （可选）运行
bash <skill目录>/scripts/setup.sh预装依赖；不运行也行，首次执行会自动装 - 安装后自动配置自动化（见下）
> 复制时不要带上 .venv 和 config/.key（二者都是机器相关的）：.venv 让首次运行自动重建，config/.key 会在目标机首次「对话式配置」时自动生成。
安装后创建自动化（需 agent 执行一次）
> ⚠️ 重要：WorkBuddy 的 skill 没有「安装后自动创建自动化」的钩子。skill 只是文件+说明，无法自行调用 automation_update。所以「装上就有自动化」做不到——必须让 agent 跑一次下面的脚本才能完成创建。这一步只需做一次，之后每天自动运行。
本 skill 自带 scripts/configure_automation.py，读取 config/backup_config.md 后生成创建自动化所需的全部参数。让 agent 执行：
- 运行脚本生成参数：
bash python3 <skill目录>/scripts/configure_automation.py
输出示例（每天触发一次）：
json { "name": "数据库备份每日自动下载", "prompt": "请调用 nw-db-backup 技能（Skill）执行数据库备份下载任务……", "scheduleType": "recurring", "rrule": "FREQ=DAILY" } - agent 调用
automation_update工具（mode=create），填入上面输出的name/prompt/scheduleType/rrule，即创建好自动化。
> 注：平台创建自动化时会自动注入cwds（当前工作区），这是平台行为、无法省略，且本 skill 路径自感知、不依赖它，可忽略。
> 一句话触发（安装到任意新机器后，对 agent 说这句即可）：
> 「运行 nw-db-backup 的 configure_automation.py，并据此创建一个自动化（不要传 cwds）」
> agent 会自动完成参数生成 + 创建，无需你碰任何命令。
调度原理（每天触发一次，只下载当天备份）
WorkBuddy 自动化调度器只支持 DAILY/HOURLY/WEEKLY 等频率：
- 本 skill 使用 FREQ=DAILY：每天触发一次自动化，由平台调度（触发时刻取决于平台，通常为每日 00:00 或自动化创建时刻）。
- 脚本收到触发后，只下载远程目录里文件名含「今天日期」且以 .gz 结尾的那一份（同一天多份则取文件名最大者）。下载采用分块顺序传输 + 断点续传，本地已存在且大小与远程一致才跳过，否则自动续传/重下。
- ⚠️ 关键时序要求：脚本只认「当天」的文件，而服务器一般在凌晨 02:30 左右才生成当天备份。因此自动化每天必须在 02:30 之后触发，否则当天文件尚未生成、会判定为「未找到今天备份」而跳过。
- 本平台的 FREQ=DAILY 触发时刻锚定在创建该自动化时的时间（而非 00:00），所以只要你在 02:30 之后创建/重建这个自动化，它就会每天在同时刻（如 11:25）触发，稳定命中当天备份。
- 若自动化是在 02:30 之前（如 00:00）创建的，请删除后用一句话让 agent 重建（建议下午或上午晚些时候），以保证每天触发都晚于备份生成时间。
在自动化中使用（手动引用也可）
在自动化任务的 prompt 中写：
> 调用 nw-db-backup 技能（Skill）执行数据库备份下载任务，完成后汇报结果。
技能会自动从自身 config/backup_config.md 读取配置并下载当天的备份（文件名含今天日期、以 .gz 结尾）。
配置文件格式（config/backup_config.md，键: 值）
> 通常你不需要手工编辑本文件：用「对话式配置」让 agent 写入即可，密码会自动以 enc: 前缀加密。
> 若确需手工改：除「密码」外都可直改；「密码」字段请写成 enc: 开头的密文（用 python scripts/configure.py --from 明文临时文件.md 生成），不要写明文。
服务器IP: 203.0.113.10
端口: 22
账号: root
密码: enc:xxxx...（由对话式配置自动加密写入，勿手工填明文）
远程备份目录: /www/backup/database/mysql/crontab_backup/your_project
本地保存目录: /Users/yourname/work/openclaw/backup
保留天数: 30
# 可选：使用密钥登录时取消注释并填写私钥路径（留空则使用上面的密码）
# 密钥文件: /Users/yourname/.ssh/id_rsa
支持的键（中英文均可）：
- 服务器IP / IP / host / 服务器地址
- 端口 / port（默认 22）
- 账号 / username / user / 用户名
- 密码 / password（与密钥二选一，优先用密钥）
- 远程备份目录 / 备份文件所在目录
- 本地保存目录
- 保留天数 / retention（默认 30，0 表示不清理）
- 密钥文件 / key_file / SSH_KEY（可选）
手动运行
# 校验配置（不连服务器）
python3 <skill目录>/scripts/backup_download.py --dry-run
# 真实下载（也可用 --config 指定其他配置文件）
python3 <skill目录>/scripts/backup_download.py
大文件 / 断点续传（40GB 场景）
早期版本用 sftp.get()（paramiko 默认开启 prefetch），在 >4GB 文件（如约 40G 的库备份）会在约 4GB 处中断、且「本地已存在则跳过」会把中断残留的不完整文件当成已下载永久跳过，导致永远拿不到完整备份。已修复：
- 禁用 prefetch：改为
sftp.open(..., "rb")+ 顺序read()分块下载（同时调大单请求大小MAX_REQUEST_SIZE减少往返），从根本上规避 >4GB 中断。 - 断点续传：下载前先
stat远程大小；本地已存在且本地大小 < 远程大小时，从断点seek继续下载（append），不重头来。 - 完整性校验：下载完成后校验「本地大小 == 远程大小」，不一致则自动重试（最多 6 次，每次重建连接并从上次偏移续传）；本地已存在且大小一致才真正跳过。
- 连接中断自愈：单次下载抛异常（网络断、服务器超时等）会关闭旧连接、等待数秒、重连并从断点续传，无需人工干预。
- 每次连接会打印进度（每约 256MB 一行），方便观察 40GB 大文件的传输状态。
> 若你怀疑某次本地文件已损坏（如人工中断过、或源文件当天被覆盖重生成），删除本地那个 .gz 再跑一次即可从头完整重下。
注意事项
- 密码已加密：配置文件中密码为
enc:开头的密文，明文不落盘；解密密钥在本机config/.key（权限 600，复制 skill 到其他机器时不要带上 .key）。单独泄露配置文件无法还原密码。 - 备份文件名需包含今天日期（如
project_2026-08-12_02-30-02_mysql_data.sql.gz），脚本据此判定「当天」；若本机与服务器时区不一致，可能导致日期错位 - 同一天有多份备份时，取文件名（含时间戳）最大的一份
- 脚本会写按日日志到
<本地保存目录>/logs/backup_YYYY-MM-DD.log - 自动化频率为
FREQ=DAILY（每天触发一次）。⚠️ 因脚本只认「当天」文件，而服务器约 02:30 才生成备份，自动化必须先于 02:30 之后创建，以保证每天触发都晚于备份生成时间（详见上方「调度原理」）。 - 分发安全：复制 skill 到其他机器时，只复制代码与
config/backup_config.md，不要复制config/.key；目标机首次「对话式配置」会自动生成自己的密钥。旧机的backup_config.md（含 enc: 密文）复制到新机后无法解密，需在新机重新「请帮我配置」一次。
