中文

概述

文件误删恢复技能 v0.8.0。删除文件前先将文件备份到带时间戳的文件夹（delete_backup/YYYYMMDDHHMM/），备份时计算 SHA256 哈希并存储，恢复时验证完整性并检查路径安全（检测 ../ 等路径遍历序列）。恢复后自动删除备份（保留原始文件结构）。

v0.8.0 新增 workspace_cleaner：

• 定时（默认24小时）扫描 workspace 下的临时文件和过期文件（默认7天），自动备份后清理
• 支持白名单配置（文件扩展名/文件名/文件夹名），白名单内不清理
• 核心文件（AGENTS.md、SOUL.md 等）和技能目录始终保护
• 支持手动触发 dry-run 预览和强制立即清理
• 数据文件独立存放于 {workspace}/.delete_recovery/workspace_cleaner/，技能删除后配置仍保留

v0.7.0 安全加固：

• allowed_roots 默认为 workspace 根目录 — 恢复目标限制在 {workspace} 树内，防止恢复文件到任意路径
• manifest 路径字段改为 HMAC-SHA256 加密存储 — 原始路径不再明文暴露在 manifest.jsonl 中

⚠️ 版本说明： v0.1.0～v0.6.0 已淘汰（DEPRECATED），功能说明保留仅供参考。请始终使用 v0.7.0 或 v0.8.0。

触发场景

1. 用户要删除文件，希望先备份
2. 用户误删了文件，想要恢复
3. 用户想查看有哪些可用的备份
4. 用户想手动清理某个备份
5. 用户想验证备份是否被篡改（不执行恢复）
6. 用户想通过文件名/功能/路径关键字检索已删除的文件
7. 用户想自动清理 workspace 下的临时文件和过期文件

触发词： 删除文件、误删恢复、恢复文件、查看备份、清理备份、验证备份完整性、搜索已删除文件、检索删除记录、workspace清理、临时文件清理、定时清理、workspace_cleaner

English

Overview

File deletion recovery skill v0.8.0. Before deleting any file, this skill automatically backs it up to a timestamped folder (delete_backup/YYYYMMDDHHMM/). Backups include SHA256 integrity hashes to detect post-backup tampering. Restore paths are validated to block path-traversal sequences. Backups auto-removed 7 days; logs auto-cleaned 30 days. v0.8.0: Added workspace_cleaner — scheduled temp-file cleanup with auto-backup before deletion. v0.7.0: allowed_roots defaults to workspace root (restores confined) + manifest paths HMAC-encrypted.

v0.8.0 workspace_cleaner: Scheduled (default 24-hour) scan of workspace for temp files and expired files (default 7 days), auto-backup then delete; whitelist support; core files always protected.

⚠️ Version note: v0.1.0～v0.6.0 are deprecated (DEPRECATED). Always use v0.7.0 or v0.8.0.

Trigger Scenarios

1. User wants to delete a file and needs a backup first
2. User accidentally deleted a file and wants to recover it
3. User wants to see available backups
4. User wants to manually clean up a specific backup
5. User wants to verify backup integrity without restoring
6. User wants to search for a deleted file by name or keyword
7. User wants to schedule automatic workspace cleanup

Triggers: delete file, recover deleted file, list backups, clean up backup, undelete, verify backup, check backup integrity, search deleted file, find deleted file, clean workspace, workspace cleanup, workspace_cleaner

核心命令 / Core Commands

中文

delete_recovery.py — 备份恢复核心

{workspace}/skills/delete-recovery/scripts/delete_recovery.py

workspace_cleaner.py — workspace 定时清理（v0.8.0 新增）

{workspace}/skills/delete-recovery/scripts/workspace_cleaner.py

English

delete_recovery.py — Backup & Recovery Core

{workspace}/skills/delete-recovery/scripts/delete_recovery.py

workspace_cleaner.py — Workspace Scheduled Cleanup (NEW v0.8.0)

{workspace}/skills/delete-recovery/scripts/workspace_cleaner.py

中文

安装

前提条件

• Python 3.8+
• 已安装 ClawHub CLI：npm i -g clawhub
• 已登录 ClawHub：clawhub login

安装步骤

# 通过 ClawHub 安装技能
clawhub install delete-recovery

# 查看已安装的技能
clawhub list

English

Installation

Prerequisites

• Python 3.8+
• ClawHub CLI installed: npm i -g clawhub
• ClawHub logged in: clawhub login

Installation Steps

# Install skill via ClawHub
clawhub install delete-recovery

# List installed skills
clawhub list

delete_recovery.py 命令详解

中文

所有命令通过执行脚本实现，路径：

{workspace}/skills/delete-recovery/scripts/delete_recovery.py

1. 备份文件（删除前必做）

python delete_recovery.py backup \x3Cfile_path> [original_path] [description]

• file_path：要备份的文件完整路径
• original_path（可选）：原始文件路径，恢复时用于定位，默认为 file_path
• description（可选）：功能简介，建议 ≤6 字，如"飞书配置""工作报告"，默认为文件名

备份时自动计算并存储 SHA256 哈希 + 原始路径到 .sha256 文件，防止备份文件被替换。备份后自动将（文件名、功能简介、路径）写入 manifest.jsonl，支持 search 检索。

返回示例：

{"ok": true, "folder": "202603261130", "file": "C__Users__user__Desktop__test.txt", "description": "工作报告"}

2. 搜索已删除文件

python delete_recovery.py search \x3Ckeyword>

在 manifest.jsonl 中按文件名、功能简介或路径关键字模糊搜索，返回匹配的备份位置和恢复命令。

• keyword：检索关键词（大小写不敏感， substring 匹配）

返回示例：

{
  "keyword": "报告",
  "results": [
    {
      "ts": "202603281030",
      "folder": "202603281030",
      "safe_name": "C__Users__user__Desktop__report.docx",
      "filename": "report.docx",
      "description": "工作报告",
      "path": "C:/Users/user/Desktop/report.docx"
    }
  ],
  "count": 1
}

3. 恢复文件

python delete_recovery.py restore \x3Cbackup_folder> \x3Csafe_name> [--keep-backup] [--force]

• backup_folder：备份文件夹名（如 202603261130）
• safe_name：备份文件名（脚本自动将路径中的 /、\、: 替换为 __）
• --keep-backup：可选，恢复成功后保留该备份文件夹（默认自动删除）
• --force：强制恢复无 SHA256 记录的旧备份（跳过 SHA256 存在性检查；SHA256 完整性检查和 PATH 验证仍然强制执行）

恢复前验证 SHA256 完整性 + PATH 交叉验证 + 路径遍历检测，任一验证失败均拒绝恢复。

返回示例：

{"ok": true, "restored_to": "C:\\Users\\user\\Desktop\	est.txt", "backup_deleted": true}

多文件批量恢复逻辑： 同一个备份文件夹有多次恢复时，先记录每个已恢复的文件，等全部文件都恢复完毕后才统一清理整个文件夹。

4. 验证备份完整性

python delete_recovery.py verify \x3Cbackup_folder> \x3Csafe_name>

不执行恢复，仅检查备份文件是否被篡改（SHA256 完整性 + PATH 交叉验证）。

返回示例（正常）：

{
  "ok": true,
  "hash_match": true,
  "path_match": true,
  "path_check_done": true,
  "integrity_check": true
}

返回示例（被篡改）：

{
  "ok": true,
  "hash_match": false,
  "path_match": true,
  "path_check_done": true,
  "integrity_check": false
}

5. 查看备份列表

python delete_recovery.py list

6. 手动删除指定备份

python delete_recovery.py delete_backup \x3Cbackup_folder>

7. 手动触发清理

python delete_recovery.py cleanup

8. 查看操作日志

python delete_recovery.py log [lines]

workspace_cleaner.py 命令详解

中文

workspace_cleaner 是 v0.8.0 新增的 workspace 定时清理工具，扫描并清理临时文件和过期文件，清理前自动通过 delete_recovery 备份。

路径：

{workspace}/skills/delete-recovery/scripts/workspace_cleaner.py

清理规则

始终保护的核心文件（硬编码，不可覆盖）： AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, skills, .learnings, .delete_recovery, workspace_cleaner_whitelist.json, workspace_cleaner_config.json, workspace_cleaner_timer.json, .cleanup_timer

1. 手动触发清理

python workspace_cleaner.py run

满足时间间隔（默认24小时）后执行清理。如需强制立即执行，用 run --force（脚本内不支持，但可修改定时器状态）。

返回示例：

{
  "ok": true,
  "deleted": ["temp/log.txt", "cache/data.json"],
  "backed_up": ["temp/log.txt", "cache/data.json"],
  "errors": [],
  "deleted_count": 2,
  "backed_up_count": 2,
  "expire_days": 7,
  "workspace": "C:\\Users\\user\\.openclaw\\workspace2",
  "run_at": "2026-04-02 16:30:00"
}

2. 预览清理（不实际删除）

python workspace_cleaner.py dry-run

扫描 workspace，返回所有将被清理的文件列表，但不执行删除。适合确认白名单配置是否正确。

返回示例：

{
  "ok": true,
  "dry_run": true,
  "candidates": [["temp/old.txt", 1743000000], ["__pycache__/a.pyc", 1742990000]],
  "candidate_count": 2,
  "skipped": {
    "protected": ["AGENTS.md", "SOUL.md", "skills"],
    "whitelisted": ["important.xlsx", "my_folder"],
    "recent": ["recent.docx"]
  },
  "expire_days": 7,
  "workspace": "C:\\Users\\user\\.openclaw\\workspace2"
}

3. 查看状态

python workspace_cleaner.py status

查看当前配置、定时器状态和上次运行时间。

返回示例：

{
  "ok": true,
  "workspace": "C:\\Users\\user\\.openclaw\\workspace2",
  "extension_dir": "C:\\Users\\user\\.openclaw\\workspace2\\.delete_recovery\\workspace_cleaner",
  "interval_hours": 24,
  "expire_days": 7,
  "auto_backup": true,
  "last_run": "2026-04-01 16:30:00",
  "timer_due": true,
  "whitelist": {"files": [], "folders": [], "exts": []},
  "always_protected_count": 14
}

4. 查看白名单

python workspace_cleaner.py show-whitelist

返回当前白名单内容、始终保护列表及数据文件路径。

5. 添加白名单

python workspace_cleaner.py add-whitelist \x3Cpath> [--type file|folder|ext]

• --type file：保护指定文件
• --type folder：保护指定文件夹
• --type ext：保护指定扩展名（如 .xlsx）

示例：

python workspace_cleaner.py add-whitelist ".xlsx" --type ext
python workspace_cleaner.py add-whitelist "projects" --type folder
python workspace_cleaner.py add-whitelist "important.txt" --type file

6. 移除白名单

python workspace_cleaner.py remove-whitelist \x3Cpath>

从白名单中移除指定项（自动识别类型）。

7. 设置清理间隔

python workspace_cleaner.py set-interval \x3Chours>

设置两次自动清理之间的最小时间间隔（小时）。

8. 设置过期天数

python workspace_cleaner.py set-expire-days \x3Cdays>

设置文件过期天数（超过此天数未访问/修改则视为可清理）。

English

workspace_cleaner.py Commands (NEW v0.8.0)

Path:

{workspace}/skills/delete-recovery/scripts/workspace_cleaner.py

Cleanup Rules

Always-protected (hardcoded, non-overridable): AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, skills, .learnings, .delete_recovery, workspace_cleaner_whitelist.json, workspace_cleaner_config.json, workspace_cleaner_timer.json, .cleanup_timer

1. Run Cleanup

python workspace_cleaner.py run

Runs cleanup if the interval timer has elapsed. Auto-backs up files before deletion.

2. Dry Run (Preview)

python workspace_cleaner.py dry-run

Shows what would be deleted without actually deleting.

3–8. Status / Whitelist / Interval / Expiry

Same as below.

Agent 行为约束 / Agent Behavior Constraints

中文

【强制要求】Agent 在使用本技能时必须遵守以下约束：

允许的合规操作

Agent 仅被允许执行以下操作：

1. 删除文件：调用 backup 备份后，执行用户明确授权的文件删除
2. 恢复文件：调用 restore 从备份恢复误删的文件
3. 备份查看：调用 list 查看可用备份
4. 搜索已删除文件：调用 search 通过 manifest.jsonl 检索备份位置
5. 清理备份：调用 delete_backup 删除指定的过时备份
6. 恢复误删：调用 restore 恢复用户误删的文件
7. 验证备份完整性：调用 verify 检查备份是否被篡改
8. 手动触发清理：调用 cleanup 清理过期备份和日志
9. workspace_cleaner 管理：管理白名单、设置时间间隔/过期天数、查看状态、触发清理

禁止的不安全操作（绝对禁止）

Agent 绝对不允许通过删除/恢复操作进行以下文件篡改或路径重定向行为：

1. 文件内容篡改：在备份或恢复过程中修改文件内容
2. 路径重定向恢复：将文件恢复到用户指定位置以外的目录（尤其是敏感系统目录）
3. 路径遍历攻击：利用 .. 或其他路径遍历序列将文件恢复至备份区域外
4. 备份替换攻击：用恶意文件替换合法备份文件后尝试恢复
5. 绕过 SHA256 完整性验证：用恶意文件替换备份后跳过完整性检查恢复；例外：--force 仅可跳过 SHA256 存在性检查（仅针对 v0.3.0 前旧备份），SHA256 完整性验证本身不可绕过
6. 未授权文件删除：未经用户明确授权删除任何文件
7. 日志篡改：修改、删除或伪造操作日志以掩盖不安全行为

安全验证要求

• 所有 restore 操作必须通过 SHA256 完整性验证、PATH 交叉验证和路径遍历检测；--force 例外：可跳过 SHA256 存在性检查（仅针对 v0.3.0 前旧备份），完整性验证本身不可绕过
• 验证失败时必须拒绝恢复并报告 SECURITY 级别日志
• Agent 不得尝试绕过、禁用或忽略任何安全验证机制，唯一的例外是上述 --force 对 SHA256 存在性的豁免

【可选配置】将此安全约束添加到 AGENTS.md，以便 Agent 在执行任何文件删除操作之前先调用 backup 备份。

所有删除操作都必须先备份。无论是你自主运行删除的或用户命令触发的删除还是 workspace_cleaner 发起的文件清理，所有文件都必须在执行删除之前使用 delete-recovery skill 进行备份。这是一条永久性的铁律，不可跳过。

English

【Mandatory】Agents MUST comply with the following constraints when using this skill:

Permitted Operations (Compliant)

Agents are ONLY permitted to perform:

1. Delete files: Execute user-authorized file deletion after calling backup
2. Restore files: Call restore to recover accidentally deleted files from backup
3. List backups: Call list to view available backups
4. Search deleted files: Call search to locate backups via manifest.jsonl
5. Clean backups: Call delete_backup to remove specific outdated backups
6. Undelete: Call restore to recover mistakenly deleted files
7. Verify backup integrity: Call verify to check if backups have been tampered
8. Manual cleanup: Call cleanup to purge expired backups and logs
9. workspace_cleaner management: Manage whitelist, set interval/expiry, check status, trigger cleanup

Prohibited Unsafe Operations (Absolutely Forbidden)

Agents are ABSOLUTELY FORBIDDEN from performing file tampering or path redirection via delete/restore operations:

1. File content tampering: Modifying file content during backup or restore
2. Path redirection restore: Restoring files to locations other than user-specified destinations (especially sensitive system directories)
3. Path traversal attacks: Using .. or other traversal sequences to restore files outside the backup area
4. Backup substitution attacks: Replacing legitimate backups with malicious files then attempting to restore
5. Bypassing SHA256 integrity verification: Substituting a malicious backup and bypassing integrity check to restore it; Exception: --force may bypass SHA256 existence check only for pre-v0.3.0 legacy backups — the integrity verification itself is never bypassable
6. Unauthorized file deletion: Deleting any file without explicit user authorization
7. Log tampering: Modifying, deleting, or forging operation logs to conceal unsafe behavior

Security Validation Requirements

• All restore operations MUST pass SHA256 integrity verification, PATH cross-validation, and path traversal detection — except that --force may skip the SHA256 existence check for pre-v0.3.0 legacy backups
• Restore MUST be rejected with SECURITY level log if any validation fails
• Agents must NOT attempt to bypass, disable, or ignore any security validation mechanisms — except the documented --force exception for SHA256 existence checks on legacy backups

【Optional Configuration】Add this security constraint to AGENTS.md so that Agent calls backup before performing any file deletion operation

All deletion operations must be backed up first. Whether the deletion is triggered by a user command, initiated by me for file cleanup, or started by workspace_cleaner, all files must be backed up using the delete-recovery skill before executing the deletion. This is a permanent ironclad rule that cannot be skipped.

安全机制 / Security Mechanisms

中文

备份完整性验证（SHA256）

• backup 时：计算备份文件的 SHA256，存入 .sha256 文件（含 PATH 字段）
• restore 时：重新计算备份文件的 SHA256，与记录值比对
  • 不匹配 → 拒绝恢复，报告 SECURITY 级别日志
  • SHA256 记录缺失或为空 → 拒绝恢复
  • 防止攻击者备份正常文件后替换为恶意文件再骗取恢复

PATH 交叉验证

• .sha256 文件中存储原始路径（PATH: 字段）
• restore 时：将 .sha256 中记录的路径与 .path 文件内容进行交叉验证
  • 不一致 → 拒绝恢复
  • 彻底防止攻击者单独篡改 .path 文件定向到任意位置

--force 路径安全强制验证

• --force 参数原可跳过所有检查（删除 SHA256 + --force 即可绕过）
• 修复： --force 跳过 SHA256 存在性检查，但 PATH 交叉验证和路径遍历检测永远执行，即使 SHA256 记录不存在也不例外
• 关闭了"删除 SHA256 → --force → 完全绕过"这一攻击链路

日志注入防护

• log() 函数在写入日志前过滤 \ 、\r、[ 字符
• 防止通过 detail 参数注入伪造的日志行

路径遍历检测

• restore 时：检测路径中的 .. 成分
  • resolve 后路径与原始路径不一致 → 拒绝恢复
  • 防止利用 ../ 遍历逃逸

安全事件日志

• 所有安全拦截事件记录为 SECURITY 级别日志，便于审计

workspace_cleaner 安全保障

• 清理前自动备份：调用 delete_recovery.py backup 备份每个文件，备份失败时自动降级为手动备份（复制到 delete_backup/timestamp/）
• 硬编码核心文件保护：AGENTS.md、SOUL.md 等核心文件和技能目录始终免于清理，无法通过白名单覆盖
• workspace 目录 confinement：仅扫描 {workspace} 目录，不会遍历到 workspace 外部
• 白名单隔离：用户白名单数据存储在 .delete_recovery/workspace_cleaner/ 下，与备份目录隔离
• 定时器防滥用：清理必须满足时间间隔才执行（run 命令），防止短时间内重复触发

English

Backup Integrity Verification (SHA256)

• On backup: Computes SHA256 of the backup file, stores in .sha256 (includes PATH field)
• On restore: Recomputes SHA256 and compares — mismatch blocks restore with SECURITY log
  • Missing or empty SHA256 record → restore blocked
  • Prevents replacing backup with malicious file after backing up a legitimate one

PATH Cross-Validation

• .sha256 file stores the original path in a PATH: line
• On restore: cross-checks the path in .sha256 against the .path file
  • Mismatch → restore blocked
  • Fully prevents attacker from tampering with .path to redirect restore elsewhere

--force PATH Safety Enforcement

• --force previously allowed bypassing all checks (delete SHA256 + --force = full bypass)
• Fix: --force bypasses SHA256 existence check, but PATH cross-validation and traversal detection always run, even when SHA256 record is absent
• Closes the "delete SHA256 → --force → complete bypass" attack chain

Log Injection Prevention

• log() function strips \ , \r, and [ from detail before writing
• Prevents injecting fake log entries via a crafted detail parameter

Path Traversal Detection

• On restore: Detects .. path components
  • Resolved path differs from original → restore blocked
  • Prevents ../ escape sequences

Security Event Logging

• All security blocks logged at SECURITY level for audit trail

workspace_cleaner Security Guards

• Auto-backup before deletion: Calls delete_recovery.py backup for each file; falls back to manual copy if subprocess fails
• Hardcoded core-file protection: Core files (AGENTS.md, SOUL.md, etc.) and skill directory are always protected — cannot be overridden by whitelist
• Workspace root confinement: Only scans {workspace} directory, never traverses outside
• Whitelist isolation: User whitelist stored in .delete_recovery/workspace_cleaner/, separate from backup directory
• Timer enforcement: Cleanup requires the time interval to have elapsed (run command), preventing rapid re-triggering

自动清理规则 / Auto-Cleanup Rules

中文

脚本每次启动时自动执行清理，无需手动调用（delete_recovery.py 侧）。workspace_cleaner 需通过 cron 或定期触发。

English

delete_recovery.py runs cleanup on every script invocation. workspace_cleaner requires cron or periodic triggering.

文件结构 / File Structure

中文

v0.6.0 重大变更：备份和日志存储位置移至 workspace 根目录，技能目录被删除时备份仍可存活。

v0.7.0 安全加固：manifest 路径字段改为 HMAC-SHA256 加密存储，不再明文暴露原始路径。

v0.8.0 workspace_cleaner： 新增定时清理工具，独立数据目录，清理前自动备份。

workspace2/                               ← 工作区根目录（备份独立于技能目录）
├── .delete_recovery/                     ← 数据根目录（v0.6.0+，技能删除后仍存活）
│   ├── delete_backup/                    ← 备份存储（7天自动清理）
│   │   ├── manifest.jsonl               ← 检索索引：文件名/功能简介/**加密路径（v0.7.0）**
│   │   ├── log/                        ← 日志目录
│   │   │   └── log.txt                ← 操作日志（30天自动清理）
│   │   ├── YYYYMMDDHHMM/             ← 时间戳文件夹
│   │   │   ├── C__Users__...         ← 备份文件
│   │   │   ├── C__Users__...path    ← 原始路径记录（解密用，始终保留）
│   │   │   ├── C__Users__...sha256  ← SHA256 + PATH 交叉验证记录（v0.3.0）
│   │   │   └── .restored              ← 已恢复文件清单
│   │   └── temp_existing/             ← 恢复时暂存已有文件
│   └── workspace_cleaner/              ← workspace_cleaner 数据目录（v0.8.0）
│       ├── workspace_cleaner_whitelist.json  ← 用户白名单配置
│       ├── workspace_cleaner_config.json    ← 运行配置（间隔、过期天数）
│       └── workspace_cleaner_timer.json     ← 定时器状态

{workspace}/skills/delete-recovery/          ← 技能目录（可独立删除，不影响备份）
├── SKILL.md
├── README.md
├── scripts/
│   ├── delete_recovery.py               ← 核心脚本（含安全验证，v0.7.0）
│   ├── safe_path.py                     ← 路径安全验证模块（v0.3.1）
│   └── workspace_cleaner.py              ← workspace 定时清理脚本（v0.8.0）
└── example/
    └── example.txt

v0.7.0 manifest path encryption: manifest.jsonl 的 path 字段存储 HMAC-SHA256 哈希（格式：HASH_PREFIX:HMAC_TAG），而非明文路径。解密由备份文件夹内的 .path 文件负责。filename 和 description 字段保持明文以支持按文件名检索。

.path 文件作用： 每个备份文件旁边有一个同名 .path 文件，存储原始文件路径，用于恢复时定位目标位置。

.sha256 文件作用（v0.3.0）： 存储备份文件的 SHA256 哈希 + 原始路径（交叉验证用），防止备份被篡改后注入恶意文件。

workspace_cleaner 数据文件（v0.8.0）：

• workspace_cleaner_whitelist.json：用户白名单（文件/文件夹/扩展名），可手动编辑
• workspace_cleaner_config.json：运行配置（间隔小时数、过期天数、auto_backup 开关）
• workspace_cleaner_timer.json：定时器状态（上次运行时间）

English

v0.6.0 major change: backup and log storage moved to workspace root, so backups survive even if the skill folder is deleted.

v0.7.0 security hardening: manifest path field is now HMAC-SHA256 encrypted (not plaintext).

v0.8.0 workspace_cleaner: New scheduled cleanup tool with isolated data directory and auto-backup before deletion.

workspace2/                               ← Workspace root (backups independent of skill directory)
├── .delete_recovery/                     ← Data root directory (v0.6.0+, survives skill deletion)
│   ├── delete_backup/                    ← Backup storage (7-day auto-cleanup)
│   │   ├── manifest.jsonl               ← Retrieval index: filename / description /**encrypted path (v0.7.0)**
│   │   ├── log/                        ← Logs directory
│   │   │   └── log.txt                ← Operation logs (30-day auto-cleanup)
│   │   ├── YYYYMMDDHHMM/             ← Timestamp folder
│   │   │   ├── C__Users__...         ← Backup file
│   │   │   ├── C__Users__...path    ← Original path record (plaintext, always retained)
│   │   │   ├── C__Users__...sha256  ← SHA256 + PATH cross-validation record (v0.3.0)
│   │   │   └── .restored              ← Restored files manifest
│   │   └── temp_existing/             ← Conflict files staged during recovery
│   └── workspace_cleaner/              ← workspace_cleaner data directory (v0.8.0)
│       ├── workspace_cleaner_whitelist.json  ← User whitelist config
│       ├── workspace_cleaner_config.json    ← Runtime config (interval, expire_days)
│       └── workspace_cleaner_timer.json     ← Timer state

{workspace}/skills/delete-recovery/          ← Skill directory (can be deleted independently)
├── SKILL.md
├── README.md
├── scripts/
│   ├── delete_recovery.py               ← Core script (with security checks, v0.7.0)
│   ├── safe_path.py                     ← Path safety validator module (v0.3.1)
│   └── workspace_cleaner.py              ← workspace cleaner script (v0.8.0)
└── example/
    └── example.txt

v0.7.0 manifest path encryption: The manifest.jsonl path field stores an HMAC-SHA256 hash (format: HASH_PREFIX:HMAC_TAG), not the plaintext path. Decryption always uses the .path file in the backup folder. Filename and description remain in plaintext to support filename-based search.

完整使用示例 / Full Usage Example

中文

场景：用户要删除桌面上的 report.docx

Step 1：先备份（建议加上功能简介）

python delete_recovery.py backup "C:\Users\user\Desktop\report.docx" "C:\Users\user\Desktop\report.docx" "工作报告"

Step 2：执行删除（由用户自行完成）

Step 3：用户误删后想恢复，先搜索

# 搜索已删除的文件
python delete_recovery.py search "报告"
# 返回：folder + safe_name + description + path，AI 根据结果执行 restore

Step 4：恢复

python delete_recovery.py restore 202603281030 "C__Users__user__Desktop__report.docx"
# 恢复成功后 manifest 中的索引自动被剔除

Step 5：验证备份完整性（可选）

python delete_recovery.py verify 202603281030 "C__Users__user__Desktop__report.docx"

场景：workspace_cleaner 定时清理（v0.8.0）

# 查看状态和下次可清理时间
python workspace_cleaner.py status

# 预览哪些文件将被清理（不实际删除）
python workspace_cleaner.py dry-run

# 手动触发一次清理
python workspace_cleaner.py run

# 添加白名单（保护重要文件）
python workspace_cleaner.py add-whitelist ".xlsx" --type ext
python workspace_cleaner.py add-whitelist "projects" --type folder

# 调整清理参数
python workspace_cleaner.py set-interval 12   # 改为12小时清理一次
python workspace_cleaner.py set-expire-days 3  # 3天未修改视为过期

English

# 1. Backup before deletion (with description)
python delete_recovery.py backup "C:\Users\user\Desktop\report.docx" "C:\Users\user\Desktop\report.docx" "Work Report"

# 2. User performs deletion (manually)

# 3. Search for deleted file
python delete_recovery.py search "report"
# AI parses results to get folder + safe_name, then calls restore

# 4. Accidentally deleted — restore
python delete_recovery.py restore 202603261130 "C__Users__user__Desktop__report.docx"
# With --keep-backup
python delete_recovery.py restore 202603261130 "C__Users__user__Desktop__report.docx" --keep-backup
# Force restore pre-v0.3.0 backup (no SHA256 record)
python delete_recovery.py restore 202603261130 "C__Users__user__Desktop__report.docx" --force

# 5. Verify backup integrity (optional)
python delete_recovery.py verify 202603261130 "C__Users__user__Desktop__report.docx"

# workspace_cleaner usage (v0.8.0 NEW)
python workspace_cleaner.py status
python workspace_cleaner.py dry-run
python workspace_cleaner.py run
python workspace_cleaner.py add-whitelist ".xlsx" --type ext
python workspace_cleaner.py set-interval 12
python workspace_cleaner.py set-expire-days 3

安全加固说明 / Security Hardening

中文

⚠️ 版本说明： v0.1.0～v0.6.0 已淘汰。请始终使用 v0.7.0 或 v0.8.0。

说明（v0.7.0+v0.8.0）： allowed_roots 现默认为 workspace 根目录——恢复目标被限制在 {workspace} 树内，阻止恢复文件到任意系统路径。workspace_cleaner 的安全机制独立于 delete_recovery，不依赖 SHA256/PATH 验证（因为清理的是临时/过期文件，备份用途为恢复而非安全防护）。安全防护依赖 workspace 目录 confinement + 核心文件硬编码保护 + 白名单隔离。备份文件存在于 {workspace}/.delete_recovery/delete_backup/，请仅在受信任的环境中使用本技能。

English

⚠️ Version note: v0.1.0～v0.6.0 are deprecated. Always use v0.7.0 or v0.8.0.

Note (v0.7.0+v0.8.0): allowed_roots now defaults to workspace root — restores are confined to the {workspace} tree, preventing arbitrary system-path writes. workspace_cleaner security is independent of delete_recovery SHA256/PATH validation (it cleans temp/expired files, backup is for recovery not security hardening). Protection relies on workspace root confinement + hardcoded core-file protection + whitelist isolation. Backup files live in {workspace}/.delete_recovery/delete_backup/ — deploy only in trusted environments.

安全设计决策说明 / Security Design Decisions

中文

本节直接回应审查中提出的设计关切。

Q1：为什么不默认限制恢复目标目录（allowed_roots）？

A： 作为文件恢复工具，核心需求是将文件恢复到原始位置——而原始位置可能是用户硬盘上的任意目录。强制限定 allowed_roots 会使工具无法恢复原本不在"白名单"内的文件，根本上违背工具的设计目的。v0.7.0 起 allowed_roots 默认为 workspace 根目录作为安全默认值，如需恢复 workspace 外的文件，可将 allowed_roots 设为 None。

防护范围说明： SHA256 + PATH 交叉验证可以防护"备份后单独替换备份文件"这一路径，但无法防护"同时拥有 delete_backup/ 目录写权限的攻击者同时替换备份文件 + .sha256 + .path 三者"的情况。因此本技能的安全性依赖于文件系统权限的保护——请确保 delete_backup/ 目录仅对可信进程开放写权限。../ 路径遍历逃逸由独立的遍历检测保护，不受此影响。

Q2：--force 参数为什么不直接跳过所有检查？

A： --force 仅用于恢复没有 SHA256 记录的旧备份。--force 的行为已严格受限：

简言之：--force 只豁免「SHA256 记录不存在」这件事本身，不豁免任何实质性安全检查。

Q3：manifest.jsonl 为什么存储原始文件路径，是否泄露敏感信息？（v0.7.0 已加密）

A（v0.7.0）： v0.7.0 起，manifest 中的 path 字段改为 HMAC-SHA256 加密格式（HASH_PREFIX:HMAC_TAG），原始路径不再明文暴露。解密恢复由 .path 文件负责，manifest 仅存加密指纹。filename 和 description 字段保持明文以支持按文件名检索。

Q4：workspace_cleaner 清理时备份失败怎么办？（v0.8.0 新增）

A： workspace_cleaner 在调用 delete_recovery.py backup 备份失败时，会自动降级为直接复制文件到 delete_backup/timestamp/（手动备份模式），不依赖 delete_recovery.py 的完整安全验证。如果手动备份也失败（权限问题等），该文件会被跳过并在结果中报告错误。备份失败的 文件不会被删除。

English

This section directly addresses reviewer concerns.

Q1: Why does allowed_roots default to workspace root?

A: allowed_roots defaults to [WORKSPACE_ROOT] as a deliberate security default. As a recovery tool, the remaining use case — restoring files originally outside the workspace — is served by explicitly setting allowed_roots=None. The workspace root confinement prevents accidental or malicious restore to arbitrary system paths.

Scope of protection: SHA256 + PATH cross-validation guards against "replace the backup file after it was originally created," but does not protect against an attacker who simultaneously controls write access to delete_backup/ and replaces all three files (backup + .sha256 + .path) together. Therefore, the skill's security depends on filesystem permissions protecting delete_backup/ — only deploy in environments where that directory is write-protected from untrusted processes. Path-traversal escape (../) is independently blocked and unaffected by this limitation.

Q2: Why doesn't --force skip all security checks?

A: --force is only intended for restoring legacy backups that lack SHA256 records. --force is strictly limited:

In short: --force only waives "SHA256 record is absent" as a condition — it never skips any substantive security check.

Q3: Why does manifest.jsonl store original paths — is this sensitive information leakage?

A: The path field in manifest.jsonl is stored as HMAC-SHA256 encrypted (HASH_PREFIX:HMAC_TAG) — original paths are no longer readable. The plaintext original path is always retrievable from the .path file in the backup folder. Filename and description remain in plaintext to support filename-based search.

Q4: What happens if workspace_cleaner backup fails?

A: If delete_recovery.py backup fails, workspace_cleaner falls back to a manual copy directly into delete_backup/timestamp/ (no SHA256/PATH validation in this fallback). If even the manual backup fails (e.g., permission error), the file is skipped and reported as an error — it is NOT deleted.

注意事项 / Notes

中文

1. 删除前必备份：所有删除操作前都应先调用 backup，防止误删
2. 恢复时目标冲突：如果原位置已有文件，会自动将旧文件暂存到 temp_existing/ 目录
3. 恢复后自动删备份：默认情况下，恢复成功后会自动删除对应备份（多文件时等全部恢复完再清理）；使用 --keep-backup 可保留
4. 路径编码：备份文件名将 \、/、: 替换为 __，恢复时需使用转换后的名称
5. 时间触发清理：7天备份清理和30天日志清理改为时间触发（默认24小时间隔），不再每次命令都执行全量扫描；cleanup 命令本身不受影响，仍立即执行全量清理
6. manifest 增量操作：restore/delete_backup 时按需压缩 manifest（候选集≤100条时全量rewrite，>100条时追加墓碑标记）；list/search/log 时自动检查并触发增量压缩
7. 安全验证：restore 时自动进行 SHA256 完整性 + PATH 交叉验证 + 遍历检测，如验证失败会明确报错
8. 旧备份恢复：无 SHA256 记录的旧备份使用 restore --force 可强制恢复（完整性检查跳过，但 PATH 验证和遍历检测仍然生效，不可绕过）
9. 检索索引：backup 自动追加索引，restore 成功后自动剔除；过期备份文件夹对应的索引随 cleanup 或脚本启动时自动清理
10. workspace 目录限制（v0.7.0）：恢复目标被限制在 workspace 根目录内，阻止恢复文件到任意系统路径；如需恢复 workspace 外的文件，请手动设置 allowed_roots=None
11. manifest 路径加密（v0.7.0）：manifest 中的原始路径字段已改为 HMAC-SHA256 加密，无法通过直接查看 manifest 获取原始路径；解密完全由 .path 文件负责
12. workspace_cleaner 定时清理（v0.8.0）：需通过 cron 或定期触发；默认24小时间隔，7天过期文件；核心文件和技能目录始终保护
13. workspace_cleaner 备份降级（v0.8.0）：delete_recovery.py 备份失败时自动降级为手动备份；手动备份也失败则跳过该文件（不删除）

English

1. Always backup before deleting: Call backup before any deletion
2. Restore target conflict: Existing files moved to temp_existing/ before restoring
3. Auto-delete backup after restore: Default behavior (multi-file: all restored → then delete); use --keep-backup to retain
4. Path encoding: \, /, : replaced with __ in backup filenames
5. Time-triggered cleanup: 7-day backup and 30-day log cleanup are time-triggered (default 24-hour interval), not run on every command; cleanup command itself still runs full cleanup immediately
6. Incremental manifest: restore/delete_backup use on-demand manifest compaction; list/search/log auto-check and compact oversized manifests
7. Security checks: Restore automatically fails with clear error if SHA256 integrity, PATH cross-validation, or path traversal check fails
8. Legacy backup restore: Backups without SHA256 records use restore --force to force restore (integrity check skipped, but PATH validation and traversal detection still apply, non-bypassable)
9. Manifest index: backup auto-indexes; restore auto-removes index entry; stale entries pruned on cleanup or script startup
10. Workspace root confinement (v0.7.0): Restore destinations are confined to workspace root — files cannot be restored to arbitrary system paths; set allowed_roots=None to restore outside workspace
11. Manifest path encryption (v0.7.0): Original paths in manifest.jsonl are HMAC-SHA256 encrypted — cannot be read by inspecting the manifest file; decryption always uses the .path file in the backup folder
12. workspace_cleaner scheduled cleanup (v0.8.0): Requires cron or periodic triggering; default 24-hour interval, 7-day expiry; core files and skill directory always protected
13. workspace_cleaner backup fallback (v0.8.0): Falls back to manual copy if delete_recovery.py backup fails; skips (does not delete) if even manual backup fails

delete-recovery