# cursor-clean

**Repository Path**: devqiaoyu/cursor-clean

## Basic Information

- **Project Name**: cursor-clean
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cursor-clean

一组用于**彻底清理 Cursor 本地痕迹**的 macOS Shell 脚本。

Cursor 会把工作区、会话（聊天/Agent 记录）、远程 SSH 环境等信息保存在本地的
全局数据库 `state.vscdb` 以及 `workspaceStorage` 缓存目录中。在界面上「移除项目 /
删除会话」往往只是隐藏，底层记录依然存在。这些脚本会按照**精确的作用域规则**把指定对象
的数据真正删除，同时尽量避免误删无关的本地会话。

> 数据存放位置：`~/Library/Application Support/Cursor/User/`
> - 数据库：`globalStorage/state.vscdb`
> - 工作区缓存：`workspaceStorage/`
> - 设置：`settings.json`

## 通用前置条件

- **仅适用于 macOS**（路径写死在上述目录）。
- 运行前请**完全退出 Cursor**（`Cmd + Q`），否则脚本会检测到进程并拒绝执行。
- 依赖 `bash` 与 `python3`。
- 每个会写入的脚本都会在操作前**自动备份数据库**到
  `state.vscdb.bak.<时间戳>`，可随时回滚：
  ```bash
  cp "~/Library/Application Support/Cursor/User/globalStorage/state.vscdb.bak.<时间戳>" \
     "~/Library/Application Support/Cursor/User/globalStorage/state.vscdb"
  ```

## 脚本一览

| 脚本 | 作用 | 主要参数 |
| --- | --- | --- |
| `cursor-clean-ssh.sh` | 清理与某个 SSH 远程主机相关的全部记录 | `<目标主机>` |
| `cursor-clean-home-sessions.sh` | 清理「无文件夹窗口」（Home / 临时窗口）的会话 | `--dry-run` `--only-empty` `--only-numeric` `-y` |
| `cursor-delete-workspace.sh` | 彻底删除某个本地文件夹工作区的全部痕迹 | `<关键字或绝对路径>` `--dry-run` `-y` |

---

### 1. `cursor-clean-ssh.sh` — 清理 SSH 远程主机记录

删除 Cursor 中与指定 SSH 远程主机关联的环境、缓存与会话记录，让该主机不再出现在
Remote 环境列表里。

```bash
bash ~/cursor-clean-ssh.sh <目标主机>

# 示例
bash ~/cursor-clean-ssh.sh 8.154.30.196
bash ~/cursor-clean-ssh.sh 8.154.30.196:2222
bash ~/cursor-clean-ssh.sh 192.168.5.36
```

- `<目标主机>` 可以是 IP、域名，或带端口的形式（`host:2222`）。
- 脚本会自动扫描 `workspaceStorage` 发现与该主机关联的远程工作区 ID，无需手动填写。
- 它会清理：远程工作区缓存目录、数据库中按「远程身份」识别出的记录、
  `anysphere.remote-ssh` 的远程环境历史，以及 `settings.json` 中的
  `remote.SSH.remotePlatform` 条目。

**安全设计**：会话记录在 Cursor 中是全局存储的。脚本**只按「远程身份」精确清理**
（远程工作区 ID / `ssh-remote` / `vscode-remote` authority），仅仅在聊天文字里
「提到过」该主机 IP 的本地/Home 会话会被**有意保留**，不会误删。

---

### 2. `cursor-clean-home-sessions.sh` — 清理无文件夹窗口会话

专门清理没有绑定文件夹的窗口会话：

- **empty-window**：Home / 空窗口会话（`workspaceIdentifier.id == "empty-window"`）
- **numeric**：无文件夹临时窗口会话（`workspaceIdentifier.id` 为纯数字时间戳）

```bash
bash ~/cursor-clean-home-sessions.sh [选项]

# 强烈建议先预览
bash ~/cursor-clean-home-sessions.sh --dry-run
```

**选项**

| 选项 | 说明 |
| --- | --- |
| `--dry-run` | 只预览将删除哪些会话，不做任何修改（建议先跑一次） |
| `--only-empty` | 只清理 empty-window，保留数字时间戳窗口 |
| `--only-numeric` | 只清理数字时间戳窗口，保留 empty-window |
| `-y`, `--yes` | 跳过交互确认，直接执行 |
| `-h`, `--help` | 查看用法 |

**安全设计**：带本地文件夹（`file://`）或远程（`ssh-remote` / `vscode-remote`）
绑定的会话一律保留。删除以 `composerId` 为作用域精确进行，连同会话正文、消息、
checkpoint 等一并清除。

---

### 3. `cursor-delete-workspace.sh` — 彻底删除本地工作区

彻底删除某个**本地文件夹工作区**的全部痕迹。Cursor 里「移除项目（Remove from list）」
只是隐藏，记录仍在数据库中；本脚本做彻底清除。

```bash
bash ~/cursor-delete-workspace.sh <关键字或绝对路径> [--dry-run] [-y]

# 示例（建议先预览）
bash ~/cursor-delete-workspace.sh gwsc_confession_wall_deployable --dry-run
bash ~/cursor-delete-workspace.sh /Users/joy/Desktop/gwsc_confession_wall_deployable
```

**选项**

| 选项 | 说明 |
| --- | --- |
| `--dry-run` | 只预览，不做任何修改（建议先跑一次） |
| `-y`, `--yes` | 跳过交互确认 |
| `-h`, `--help` | 查看用法 |

清理范围包括：该工作区的全部会话（正文 / 消息 / checkpoint / 面板状态）、
`composerHeaders` 中的列表条目、按工作区 ID 作用域的数据、各类「项目 / 最近 /
已移除项目」列表里的条目，以及 `workspaceStorage` 下的缓存目录。

**安全设计**：会话正文（`bubbleId` / `composerData`）绝不按 value 文本匹配删除，
避免误删「只是提到过该路径」的其它会话；这类会话会被保留并在结尾提示。

---

## 推荐用法

1. `Cmd + Q` 完全退出 Cursor。
2. 先用 `--dry-run`（针对支持的脚本）预览将要删除的内容。
3. 确认无误后去掉 `--dry-run` 正式执行。
4. 重新打开 Cursor 生效。
5. 如有异常，用备份文件回滚数据库。