Name: delete-recovery
Availability: InStock
Automatically backs up files before deletion to timestamped folders, allows restoring deleted files, lists backups, and cleans expired backups and logs.
SKILL.md

---
name: delete-recovery
description: File deletion recovery skill v0.8.1. Back up files before deletion (to `delete_backup/YYYYMMDDHHMM/`), restore from backup, search via manifest. SHA256 integrity + path-traversal checks + workspace-root confinement. Auto-cleanup 7d/30d. **v0.8.1: workspace_cleaner 默认禁用；首次运行必须 dry-run 确认；备份失败阻断删除。** **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 are HMAC-encrypted.**

**⚠️ Security trade-offs (know them before deploying):**
- Backups are stored in `{workspace}/.delete_recovery/delete_backup/`, **outside** the skill directory — they survive skill deletion but are not protected by skill folder permissions.
- `allowed_roots` now defaults to workspace root (v0.7.0) — restores confined to `{workspace}` tree; set explicitly to `None` to remove confinement.
- Manifest paths are HMAC-SHA256 encrypted (v0.7.0) — original paths no longer readable in manifest.jsonl; filename/description still in plaintext.
- workspace_cleaner is **disabled by default** (v0.8.1) — must opt-in explicitly with `enable` command; first run requires dry-run + confirm-first-run.
- workspace_cleaner backup failures **block deletion** (v0.8.1) — files are NOT deleted if backup fails.
- No install-time integrity verification — deploy only in trusted environments.
- Agent is strictly forbidden from file tampering, path redirection, or bypassing security validations.

**Use cases (triggers):**
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 (v0.8.1: **opt-in only**)

**Triggers / keywords:**
- delete file / 删除文件
- recover deleted file / 误删恢复 / 恢复文件
- list backups / 查看备份
- clean up backup / 清理备份
- deleted file recovery / 文件恢复
- undelete / 恢复误删
- verify backup / 验证备份完整性
- check backup integrity / 检查备份是否被篡改
- search deleted file / 搜索已删除文件 / 检索删除记录
- clean workspace / 清理工作区 / workspace清理 / 定时清理
- workspace_cleaner / 临时文件清理 / 自动清理

**⚠️ Agent Behavior Constraints (MANDATORY):**
- Agent is ONLY permitted to: backup files, restore files, list backups, **search deleted files via manifest**, clean backups, undelete, verify backup integrity, manual cleanup, **manage workspace_cleaner whitelist/config, trigger workspace cleanup**
- Agent is ABSOLUTELY FORBIDDEN from: file content tampering, path redirection, path traversal attacks, backup substitution, bypassing SHA256 integrity verification, bypassing PATH cross-validation, unauthorized deletion, log tampering
- **Exception:** Using `--force` to bypass the SHA256 *existence* check is permitted **only** for pre-v0.3.0 legacy backups that lack SHA256 records. PATH cross-validation and traversal detection are **never** bypassable under any circumstances.
- All restore operations MUST pass SHA256 + PATH cross-validation + traversal detection

---

### 中文

---

## 概述

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

**v0.8.1 安全修复（针对 ASI02 风险分析）：**
- workspace_cleaner **默认禁用**（enabled=False），需显式 opt-in
- 首次运行必须先 `dry-run` 预览并 `confirm-first-run` 确认
- **备份失败阻断删除**：任何备份失败（delete_recovery + manual fallback 均失败）时，对应文件不会被删除

**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.1**。

## 触发场景

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

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

### English

## Overview

File deletion recovery skill v0.8.1. 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.1: workspace_cleaner disabled-by-default; first-run requires dry-run + confirm; backup failures block deletion.** **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.1 workspace_cleaner security fix (addressing ASI02):** workspace_cleaner is **disabled by default** — explicit opt-in required; first run requires dry-run preview + confirm-first-run; backup failure blocks deletion entirely.

**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.1**.

## 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
```

| 命令 | 说明 | 备注 |
|------|------|------|
| `backup <file_path> [original_path] [description]` | 备份文件到带时间戳文件夹 | v0.7.0 |
| `search <keyword>` | 按文件名/简介/路径关键字检索已删除文件 | v0.7.0 |
| `restore <folder> <safe_name> [--keep-backup] [--force]` | 从备份恢复文件 | v0.7.0 |
| `verify <folder> <safe_name>` | 验证备份完整性（SHA256 + PATH） | v0.7.0 |
| `list` | 查看备份列表 | v0.7.0 |
| `delete_backup <folder>` | 删除指定备份 | v0.7.0 |
| `cleanup` | 手动触发过期备份+日志清理 | v0.7.0 |
| `log [lines]` | 查看操作日志 | v0.7.0 |

### workspace_cleaner.py — workspace 定时清理（v0.8.1 强制安全修复）

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

**v0.8.1 安全流程（首次启用必须按顺序执行）：**
```
1. python workspace_cleaner.py status    # 查看当前状态
2. python workspace_cleaner.py dry-run   # 预览哪些文件将被清理（不实际删除）
3. python workspace_cleaner.py enable   # 启用 workspace_cleaner
4. python workspace_cleaner.py confirm-first-run   # 确认 dry-run 结果，解锁实际清理
5. python workspace_cleaner.py run       # 执行实际清理（满足时间间隔）
```

| 命令 | 说明 |
|------|------|
| `python workspace_cleaner.py run` | 手动触发一次清理（enabled=True + first_run_confirmed=True + 满足时间间隔） |
| `python workspace_cleaner.py dry-run` | 预览哪些文件将被清理（不实际删除，始终可用） |
| `python workspace_cleaner.py status` | 查看定时器状态和配置（含 enabled / first_run_confirmed） |
| `python workspace_cleaner.py enable` | 启用 workspace_cleaner（opt-in，默认 False） |
| `python workspace_cleaner.py disable` | 禁用 workspace_cleaner（opt-out） |
| `python workspace_cleaner.py confirm-first-run` | 确认 dry-run 预览结果，解锁首次实际清理 |
| `python workspace_cleaner.py show-whitelist` | 查看当前白名单 |
| `python workspace_cleaner.py add-whitelist <path> [--type file\|folder\|ext]` | 添加白名单项 |
| `python workspace_cleaner.py remove-whitelist <path>` | 移除白名单项 |
| `python workspace_cleaner.py set-interval <hours>` | 设置清理间隔（小时） |
| `python workspace_cleaner.py set-expire-days <days>` | 设置文件过期天数 |

### English

### delete_recovery.py — Backup & Recovery Core

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

| Command | Description | Notes |
|---------|-------------|-------|
| `backup <file_path> [original_path] [description]` | Backup file to timestamped folder | v0.7.0 |
| `search <keyword>` | Search deleted files by name/description/path | v0.7.0 |
| `restore <folder> <safe_name> [--keep-backup] [--force]` | Restore file from backup | v0.7.0 |
| `verify <folder> <safe_name>` | Verify backup integrity (SHA256 + PATH) | v0.7.0 |
| `list` | List all backups | v0.7.0 |
| `delete_backup <folder>` | Delete specified backup | v0.7.0 |
| `cleanup` | Manual trigger expired backup + log cleanup | v0.7.0 |
| `log [lines]` | View operation logs | v0.7.0 |

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

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

| Command | Description | 
|---------|-------------|
| `python workspace_cleaner.py run` | Trigger cleanup (respects interval) 
| `python workspace_cleaner.py dry-run` | Preview files to clean (no actual deletion)
| `python workspace_cleaner.py status` | View timer status and config 
| `python workspace_cleaner.py show-whitelist` | View current whitelist
| `python workspace_cleaner.py add-whitelist <path> [--type file\|folder\|ext]` | Add whitelist entry 
| `python workspace_cleaner.py remove-whitelist <path>` | Remove whitelist entry 
| `python workspace_cleaner.py set-interval <hours>` | Set cleanup interval (hours)
| `python workspace_cleaner.py set-expire-days <days>` | Set file expiration days

### 中文

## 安装

### 前提条件
- Python 3.8+
- 已安装 ClawHub CLI：`npm i -g clawhub`
- 已登录 ClawHub：`clawhub login`

### 安装步骤
```bash
# 通过 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
```bash
# 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. 备份文件（删除前必做）

```bash
python delete_recovery.py backup <file_path> [original_path] [description]
```

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

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

**返回示例：**
```json
{"ok": true, "folder": "202603261130", "file": "C__Users__user__Desktop__test.txt", "description": "工作报告"}
```

### 2. 搜索已删除文件

```bash
python delete_recovery.py search <keyword>
```

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

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

**返回示例：**
```json
{
  "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. 恢复文件

```bash
python delete_recovery.py restore <backup_folder> <safe_name> [--keep-backup] [--force]
```

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

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

**返回示例：**
```json
{"ok": true, "restored_to": "C:\\Users\\user\\Desktop\\test.txt", "backup_deleted": true}
```

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

### 4. 验证备份完整性

```bash
python delete_recovery.py verify <backup_folder> <safe_name>
```

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

**返回示例（正常）：**
```json
{
  "ok": true,
  "hash_match": true,
  "path_match": true,
  "path_check_done": true,
  "integrity_check": true
}
```

**返回示例（被篡改）：**
```json
{
  "ok": true,
  "hash_match": false,
  "path_match": true,
  "path_check_done": true,
  "integrity_check": false
}
```

### 5. 查看备份列表

```bash
python delete_recovery.py list
```

### 6. 手动删除指定备份

```bash
python delete_recovery.py delete_backup <backup_folder>
```

### 7. 手动触发清理

```bash
python delete_recovery.py cleanup
```

### 8. 查看操作日志

```bash
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
```

### 清理规则

| 类型 | 判定方式 | 说明 |
|------|---------|------|
| 临时文件 | `__pycache__`、`.pyc` 目录、`Thumbs.db` 等 | 过期后清理 |
| 过期文件 | 按修改时间 > 过期天数 | 过期后清理 |
| 白名单文件/夹/扩展名 | 用户配置 | 始终不清理 |
| 核心保护文件 | 硬编码列表 | 始终不清理 |
| 技能目录 | `skills/delete-recovery/` | 始终不清理 |
| `.delete_recovery` 目录 | 硬编码 | 始终不清理 |

**始终保护的核心文件（硬编码，不可覆盖）：**
`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. 手动触发清理

```bash
python workspace_cleaner.py run
```

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

**返回示例：**
```json
{
  "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. 预览清理（不实际删除）

```bash
python workspace_cleaner.py dry-run
```

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

**返回示例：**
```json
{
  "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. 查看状态

```bash
python workspace_cleaner.py status
```

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

**返回示例：**
```json
{
  "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. 查看白名单

```bash
python workspace_cleaner.py show-whitelist
```

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

### 5. 添加白名单

```bash
python workspace_cleaner.py add-whitelist <path> [--type file|folder|ext]
```

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

**示例：**
```bash
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. 移除白名单

```bash
python workspace_cleaner.py remove-whitelist <path>
```

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

### 7. 设置清理间隔

```bash
python workspace_cleaner.py set-interval <hours>
```

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

### 8. 设置过期天数

```bash
python workspace_cleaner.py set-expire-days <days>
```

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

### English

### workspace_cleaner.py Commands (v0.8.1 — security-hardened)

**Path:**
```
{workspace}/skills/delete-recovery/scripts/workspace_cleaner.py
```

**v0.8.1 First-run safety sequence:**
```
1. python workspace_cleaner.py status
2. python workspace_cleaner.py dry-run    # preview what would be deleted
3. python workspace_cleaner.py enable     # opt-in
4. python workspace_cleaner.py confirm-first-run   # acknowledge dry-run results
5. python workspace_cleaner.py run        # actual cleanup (if timer is due)
```

| Command | Description |
|---------|-------------|
| `python workspace_cleaner.py run` | Run cleanup (requires enable + confirm-first-run + timer due) |
| `python workspace_cleaner.py dry-run` | Preview files to clean (always available — use first) |
| `python workspace_cleaner.py status` | View timer status and config (includes enabled/first_run_confirmed) |
| `python workspace_cleaner.py enable` | Opt-in to workspace_cleaner (disabled by default) |
| `python workspace_cleaner.py disable` | Opt-out and disable workspace_cleaner |
| `python workspace_cleaner.py confirm-first-run` | Acknowledge dry-run results; unlock first actual cleanup |
| `python workspace_cleaner.py show-whitelist` | View current whitelist |
| `python workspace_cleaner.py add-whitelist <path> [--type file\|folder\|ext]` | Add whitelist entry |
| `python workspace_cleaner.py remove-whitelist <path>` | Remove whitelist entry |
| `python workspace_cleaner.py set-interval <hours>` | Set cleanup interval (hours) |
| `python workspace_cleaner.py set-expire-days <days>` | Set file expiration days |

### Cleanup Rules

| Type | Detection | Description |
|------|-----------|-------------|
| Temp files | `__pycache__`, `.pyc` dirs, `Thumbs.db`, etc. | Cleaned when expired |
| Expired files | mtime > expire_days | Cleaned when expired |
| Whitelisted items | User-configured | Always skipped |
| Always-protected files | Hardcoded list | Always skipped |
| Skill directory | `skills/delete-recovery/` | Always skipped |
| `.delete_recovery` directory | Hardcoded | Always skipped |

**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`

## 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()` 函数在写入日志前过滤 `\n`、`\r`、`[` 字符
- 防止通过 detail 参数注入伪造的日志行

### 路径遍历检测

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

### 安全事件日志

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

### workspace_cleaner 安全保障

- **强制 opt-in（v0.8.1）**：`enabled` 默认为 False，首次启用需显式 `enable` 命令
- **首次运行确认门（v0.8.1）**：首次执行清理前必须先 `dry-run` 预览并 `confirm-first-run` 确认解锁
- **备份失败阻断删除（v0.8.1）**：任何备份失败（delete_recovery + manual fallback 均失败）时，对应文件**不会被删除**，记录到 `skipped_backup_failed`
- **清理前自动备份**：调用 `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 `\n`, `\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 (v0.8.1 — ASI02 risk fix)

- **Mandatory opt-in (v0.8.1)**: `enabled` defaults to False; explicit `enable` command required
- **First-run confirmation gate (v0.8.1)**: First actual cleanup requires prior `dry-run` preview + `confirm-first-run`
- **Backup failure blocks deletion (v0.8.1)**: If both delete_recovery and manual fallback fail, the file is **NOT deleted** — reported in `skipped_backup_failed`
- **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

### 中文

| 类型 | 保留时间 | 说明 |
|------|---------|------|
| 备份文件夹 | 7天 | 超过7天的备份自动清理 |
| 日志文件 | 30天 | 超过30天的日志自动清理 |
| workspace_cleaner 过期文件 | 用户配置（默认7天） | workspace_cleaner 扫描时清理（v0.8.0） |

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

### English

| Type | Retention | Description |
|------|-----------|-------------|
| Backup folders | 7 days | Backups older than 7 days are auto-deleted |
| Log files | 30 days | Logs older than 30 days are auto-deleted |
| workspace_cleaner expired files | User-configured (default 7 days) | Cleaned during workspace_cleaner scan (v0.8.0) |

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：先备份（建议加上功能简介）**
```bash
python delete_recovery.py backup "C:\Users\user\Desktop\report.docx" "C:\Users\user\Desktop\report.docx" "工作报告"
```

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

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

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

**Step 4：恢复**

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

**Step 5：验证备份完整性**（可选）
```bash
python delete_recovery.py verify 202603281030 "C__Users__user__Desktop__report.docx"
```

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

```bash
# 查看状态和下次可清理时间
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

```bash
# 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.1**。

| 攻击场景 | 防御方式 | v0.7.0 | v0.8.0 | v0.8.1 |
|---------|---------|--------|--------|--------|
| 备份后替换文件内容 | SHA256 完整性验证 | ✅ | ✅ | ✅ |
| 备份后替换 + 删除 SHA256 绕过检查 | SHA256 强制要求（缺失/为空拒绝恢复） | ✅ | ✅ | ✅ |
| 篡改 .path 定向到其他目录 | PATH 交叉验证（.sha256 中 PATH 与 .path 对比） | ✅ | ✅ | ✅ |
| 利用 `../` 路径遍历逃逸 | 路径遍历检测 | ✅ | ✅ | ✅ |
| `--force` 跳过所有检查 | `--force` 强制 PATH 验证（即使 SHA256 缺失） | ✅ | ✅ | ✅ |
| 日志注入 | detail 中过滤 `\n` `\r` `[` | ✅ | ✅ | ✅ |
| 恢复逃逸到 workspace 外 | `allowed_roots` 默认为 workspace 根目录 | ✅ | ✅ | ✅ |
| manifest 明文暴露路径 | HMAC-SHA256 加密路径字段 | ✅ | ✅ | ✅ |
| workspace_cleaner 无确认直接清理 | 默认禁用（enabled=False）+ 首次运行 dry-run 确认门 | ❌ | ❌ | ✅ |
| workspace_cleaner 备份失败仍删除 | 备份失败阻断删除（skipped_backup_failed） | ❌ | ❌ | ✅ |
| workspace_cleaner 核心文件误删 | 硬编码核心文件保护 | ❌ | ✅ | ✅ |
| workspace_cleaner 无备份清理 | 清理前自动备份 | ❌ | ✅ | ✅ |

**说明（v0.7.0+v0.8.1）：** `allowed_roots` 现默认为 workspace 根目录——恢复目标被限制在 `{workspace}` 树内，阻止恢复文件到任意系统路径。workspace_cleaner 的安全机制独立于 delete_recovery，不依赖 SHA256/PATH 验证（因为清理的是临时/过期文件，备份用途为恢复而非安全防护）。v0.8.1 增加了 enabled opt-in、首次运行确认门、备份失败阻断删除三项关键保护。安全防护依赖 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.1**.

| Attack Scenario | Defense | v0.7.0 | v0.8.0 | v0.8.1 |
|-----------------|---------|--------|--------|--------|
| Replace backup with malicious file after backup | SHA256 integrity check | ✅ | ✅ | ✅ |
| Replace backup + delete SHA256 to bypass | SHA256 strictly required (missing/empty blocks restore) | ✅ | ✅ | ✅ |
| Tamper .path to redirect restore elsewhere | PATH cross-validation (.sha256 PATH vs .path file) | ✅ | ✅ | ✅ |
| Use `../` traversal to escape backup area | Path traversal detection | ✅ | ✅ | ✅ |
| `--force` bypasses all checks | `--force` still enforces PATH validation (even without SHA256) | ✅ | ✅ | ✅ |
| Log injection | `\n`, `\r`, `[` stripped from detail | ✅ | ✅ | ✅ |
| Restore escapes workspace | `allowed_roots` defaults to workspace root | ✅ | ✅ | ✅ |
| Manifest exposes original paths | HMAC-SHA256 encryption of path field | ✅ | ✅ | ✅ |
| workspace_cleaner runs without confirmation | Disabled by default + first-run dry-run confirmation gate | ❌ | ❌ | ✅ |
| workspace_cleaner deletes even when backup fails | Backup failure blocks deletion (skipped_backup_failed) | ❌ | ❌ | ✅ |
| workspace_cleaner deletes core files | Hardcoded core-file protection | ❌ | ✅ | ✅ |
| workspace_cleaner deletes without backup | Auto-backup before deletion | ❌ | ✅ | ✅ |

**Note (v0.7.0+v0.8.1):** `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). v0.8.1 adds critical protections: enabled opt-in, first-run dry-run confirmation gate, and backup failure blocking deletion. 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` 的行为已严格受限：

| 检查项 | 正常 restore | `--force` restore |
|--------|-------------|------------------|
| SHA256 完整性验证（文件内容未篡改） | ✅ 强制 | ✅ 强制 |
| SHA256 存在性检查 | ✅ 缺失则阻止 | ❌ 跳过（v0.3.0前旧备份无此记录） |
| PATH 交叉验证（.sha256中路径 vs .path文件） | ✅ 强制 | ✅ **强制执行，不可绕过** |
| 路径遍历检测（`../` 逃逸） | ✅ 强制 | ✅ **强制执行，不可绕过** |

简言之：`--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.1 修复）

**A（v0.8.1）：** 先尝试 `delete_recovery.py backup`，失败则降级为手动复制到 `delete_backup/timestamp/`。若两者均失败（权限问题等），**该文件不会被删除**，记录到 `skipped_backup_failed`。这是 v0.8.0 行为的重大修复——v0.8.0 在手动备份失败时仍执行了删除。

**A（v0.8.0）：** 备份失败时降级为手动备份模式，如果手动备份也失败，文件仍会被删除（v0.8.0 行为）。**v0.8.1 已修复此问题——备份失败现在会阻断删除。**

### 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:

| Check | Normal restore | `--force` restore |
|-------|--------------|------------------|
| SHA256 integrity (content not tampered) | ✅ Always | ✅ Always |
| SHA256 existence check | ✅ Blocked if missing | ❌ Bypassed (legacy backups pre-date SHA256) |
| PATH cross-validation (.sha256 PATH vs .path file) | ✅ Always | ✅ **Always, non-bypassable** |
| Path traversal detection (`../` escape) | ✅ Always | ✅ **Always, non-bypassable** |

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 (v0.8.1):** `delete_recovery.py backup` is called first; if it fails, a manual copy fallback runs. If **both** fail (e.g., permission error), the file is **NOT deleted** — it is reported in `skipped_backup_failed`. This is a deliberate design change from v0.8.0 (where manual backup failure still allowed deletion to proceed).

**A (v0.8.0):** 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, the file was still deleted (v0.8.0 behavior). **v0.8.1 fixes this — backup failure now blocks deletion.**

## 注意事项 / 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.1）：enabled 默认为 False，需 `enable` 命令显式启用；首次运行需先 dry-run + confirm-first-run
13. **workspace_cleaner 备份失败阻断删除**（v0.8.1）：delete_recovery.py 备份失败且 manual fallback 也失败时，对应文件不会被删除，记录到 `skipped_backup_failed`
14. **workspace_cleaner 定时清理**（v0.8.0）：需通过 cron 或定期触发；默认24小时间隔，7天过期文件；核心文件和技能目录始终保护
15. **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 opt-in (v0.8.1)**: `enabled` defaults to False; must explicitly `enable`; first run requires dry-run + confirm-first-run
13. **workspace_cleaner backup failure blocks deletion (v0.8.1)**: If both delete_recovery and manual fallback fail for a file, that file is NOT deleted — reported in `skipped_backup_failed`
14. **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
15. **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
delete-recovery

SKILL.md

related skills
