1. Cursor 緩存膨脹把 C 盤吃滿的真實(shí)場(chǎng)景如果你在 Windows 上用 Cursor 寫代碼超過半年大概率會(huì)遇到一個(gè)很反直覺的問題項(xiàng)目代碼才幾百 MBC 盤卻莫名其妙少了十幾 GB。打開「此電腦」一看系統(tǒng)盤飄紅Windows 更新都裝不下。很多人第一反應(yīng)是去刪node_modules、清npm cache、卸載不用的軟件折騰一圈發(fā)現(xiàn)根本沒釋放多少空間。真正的大頭藏在用戶目錄里。你可以按Win R輸入下面這個(gè)路徑直接跳過去%APPDATA%\Cursor展開后通常是C:\Users\你的用戶名\AppData\Roaming\Cursor。用 WizTree 或者 TreeSize Free 掃一下這個(gè)目錄你會(huì)看到幾個(gè)體積夸張的文件和文件夾。我實(shí)測(cè)過一臺(tái)用了 8 個(gè)月的機(jī)器這個(gè)目錄接近 20GB拆開看主要是這么幾塊內(nèi)容大約占用是什么state.vscdb~11GB本地狀態(tài)庫(kù)聊天、Agent、Composer 歷史state.vscdb.backup~4GB上面那個(gè)庫(kù)的備份cursor-agent多版本~2GB歷史版本的 Agent CLI 安裝包CachedData、logs等少量緩存和日志結(jié)論很清楚不是你的項(xiàng)目文件占空間是 Cursor 自己把聊天記錄和 Agent 歷史越堆越多。幾個(gè)月前的對(duì)話對(duì)你基本沒用但它一直躺在 SSD 里。官方設(shè)置里又沒有「只保留最近 90 天」這種開關(guān)手動(dòng)去刪又怕把配置搞壞。這就是cursor-clean要解決的問題。它是一個(gè)輕量 Python 命令行工具專門掃描 Cursor 的 Roaming 目錄告訴你哪些能刪、哪些該留然后按你的策略清理。適合誰用所有在 Windows 上用 Cursor、C 盤開始告急的開發(fā)者。不需要你懂 SQLite也不需要你手動(dòng)去翻目錄裝完就能跑。下面我會(huì)從定位大文件目錄開始一步步帶你裝好、掃描、清理最后用磁盤占用對(duì)比驗(yàn)證效果。整個(gè)過程可復(fù)制跟著做就行。2. 用 cursor-clean 定位并清理 Cursor 大文件目錄在動(dòng)手清理之前先理解cursor-clean的設(shè)計(jì)思路這樣你用起來才放心。它的邏輯非常樸素掃描 Cursor 的 Roaming 目錄識(shí)別出三類可以安全處理的目標(biāo)然后交給你確認(rèn)。第一類是state.vscdb里的歷史記錄。這是 Cursor 的本地狀態(tài)庫(kù)用 SQLite 存儲(chǔ)聊天、Agent、Composer 的歷史都塞在里面。cursor-clean默認(rèn)只保留最近 90 天的記錄更早的會(huì)被清掉。這個(gè)天數(shù)可以通過--keep-days參數(shù)改比如你只想留 60 天就傳 60。第二類是舊的cursor-agent版本。Cursor 的 Agent CLI 每次更新都會(huì)裝一份新的舊版本不會(huì)自動(dòng)刪。工具的策略是只保留最新一份其余刪掉。第三類是state.vscdb.backup。這個(gè)是備份文件工具默認(rèn)不刪保留著以防萬一。如果你確認(rèn)不需要可以自己手動(dòng)處理。它有幾個(gè)我比較認(rèn)可的點(diǎn)零第三方依賴只用 Python 標(biāo)準(zhǔn)庫(kù)不建自己的數(shù)據(jù)庫(kù)支持中文和英文界面先掃描再確認(rèn)避免誤刪。技術(shù)棧就是「掃目錄 改 Cursor 自己的 state.vscdb 刪舊文件夾」邏輯簡(jiǎn)單到你可以自己審計(jì)源碼。安裝方式有兩種。最省事的是從 PyPI 裝pip install -U cursor-clean如果你網(wǎng)絡(luò)環(huán)境訪問 PyPI 慢也可以用國(guó)內(nèi)鏡像pip install -U cursor-clean -i https://pypi.tuna.tsinghua.edu.cn/simple裝完之后驗(yàn)證一下cursor-clean --version能打印出版本號(hào)就說明裝好了。環(huán)境要求是 Windows Python 3.9 及以上。如果你還沒裝 Python去 python.org 下個(gè) 3.11 或 3.12 都行安裝時(shí)記得勾選「Add Python to PATH」。這里有個(gè)前置動(dòng)作必須強(qiáng)調(diào)清理前先完全退出 Cursor。不是關(guān)窗口是去任務(wù)管理器里確認(rèn)沒有Cursor.exe進(jìn)程。因?yàn)楣ぞ咭獕嚎s SQLite 數(shù)據(jù)庫(kù)如果 Cursor 還開著占用文件壓縮可能卡住甚至損壞。按Ctrl Shift Esc打開任務(wù)管理器在「進(jìn)程」里找 Cursor全部結(jié)束任務(wù)。退出之后先跑掃描看看能清什么cursor-clean scan --lang zh--lang zh是讓輸出用中文不加就是英文。掃描是只讀操作不會(huì)改任何東西你可以放心跑。輸出會(huì)列出各個(gè)目標(biāo)的當(dāng)前大小、可清理大小、保留策略。確認(rèn)沒問題后再執(zhí)行清理cursor-clean clean --lang zh默認(rèn)是交互式的會(huì)問你確認(rèn)。如果你想非交互一鍵清cursor-clean clean -y --lang zh常用參數(shù)我整理成一張表方便你按需組合參數(shù)作用示例--keep-days N只保留最近 N 天聊天cursor-clean clean --lang zh --keep-days 60-y非交互直接確認(rèn)cursor-clean clean -y --lang zhclean-agents只刪舊 agent 版本cursor-clean clean-agents -y --lang zhvacuum只壓縮數(shù)據(jù)庫(kù)cursor-clean vacuum --lang zh如果你只想處理某一類可以分開跑。比如先只刪舊 agent 版本cursor-clean clean-agents -y --lang zh再單獨(dú)壓縮數(shù)據(jù)庫(kù)cursor-clean vacuum --lang zhvacuum這個(gè)操作值得單獨(dú)說。SQLite 刪數(shù)據(jù)后文件不會(huì)自動(dòng)變小需要執(zhí)行 VACUUM 重建數(shù)據(jù)庫(kù)文件才能真正釋放空間。cursor-clean幫你做了這件事這也是為什么清理后能看到明顯體積下降。3. 可復(fù)制的 cursor-clean 配置與清理參數(shù)這一節(jié)給你一份可以直接抄的配置和命令組合。雖然cursor-clean是命令行工具不需要寫 JSON 或 TOML 配置文件但你可以把常用參數(shù)固化成一個(gè)批處理腳本省得每次敲。先看最常用的清理流程我把它寫成一個(gè).bat文件放在桌面雙擊就能跑echo off chcp 65001 nul echo 正在掃描 Cursor 緩存... cursor-clean scan --lang zh echo. echo 按任意鍵開始清理保留最近 90 天... pause nul cursor-clean clean -y --lang zh --keep-days 90 echo. echo 清理完成按任意鍵退出。 pause nulchcp 65001是為了讓中文正常顯示不然 cmd 里可能亂碼。這個(gè)腳本的邏輯就是先掃描給你看暫停等你確認(rèn)再執(zhí)行清理。如果你想把保留天數(shù)改成 60 天把--keep-days 90改成--keep-days 60就行。想更激進(jìn)一點(diǎn)只留 30 天就寫 30。我的建議是別低于 30 天因?yàn)橛行╉?xiàng)目的上下文你可能過幾周還要翻。對(duì)于想接入自動(dòng)化流程的場(chǎng)景比如你寫了個(gè)定時(shí)任務(wù)每周清理一次可以用非交互模式echo off chcp 65001 nul cursor-clean clean -y --lang zh --keep-days 90 cursor-clean clean-agents -y --lang zh cursor-clean vacuum --lang zh這三條命令分別做三件事清理 90 天前的聊天記錄、刪除舊 agent 版本、壓縮數(shù)據(jù)庫(kù)。組合起來就是一次完整清理。如果你用的是 PowerShell語法基本一樣只是暫停命令不同cursor-clean scan --lang zh cursor-clean clean -y --lang zh --keep-days 90 cursor-clean vacuum --lang zh這里要提醒一個(gè)容易踩的坑批處理腳本里不要加cursor-clean的完整路徑除非你確定 PATH 里有。如果你是用pip install --user裝的腳本可能不在系統(tǒng) PATH 里需要寫成完整路徑比如%APPDATA%\Python\Python311\Scripts\cursor-clean.exe clean -y --lang zh具體路徑取決于你的 Python 版本和安裝方式。不確定的話在 cmd 里跑where cursor-clean就能看到實(shí)際位置。關(guān)于模型和 API 的配置這里要說明一下cursor-clean本身是純本地工具不涉及任何模型調(diào)用所以不需要配 Base URL、Key 或 Model ID。它只操作本地文件。如果你在 Cursor 里配置了自定義模型接入那是另一回事和清理工具無關(guān)。但如果你確實(shí)需要在 Cursor 里接入第三方模型服務(wù)來降低使用成本可以了解下 TaoToken 這類聚合服務(wù)。它的 API 地址是https://taotoken.net/api在 Cursor 的模型設(shè)置里填 Base URL 和對(duì)應(yīng)的 Key 就能用。不過這是可選項(xiàng)和本文的清理主題分開你按需決定?；氐角謇肀旧怼Ｎ医ㄗh你把掃描和清理分成兩步不要一上來就-y。先scan看清楚哪些文件大、清理策略是什么確認(rèn)沒有誤傷再清。這個(gè)習(xí)慣能幫你避免「手滑刪了還要用的歷史」這種尷尬。4. 驗(yàn)證清理效果與磁盤占用對(duì)比方法清理跑完之后怎么確認(rèn)真的釋放了空間不能只看工具的輸出要自己動(dòng)手驗(yàn)證。這里給你幾種方法從簡(jiǎn)單到嚴(yán)謹(jǐn)。最直接的是看工具自己的輸出。cursor-clean clean執(zhí)行完會(huì)打印清理前后的對(duì)比類似這樣清理前 state.vscdb: 11.2 GB 清理后 state.vscdb: 1.8 GB 釋放空間: 9.4 GB但這個(gè)數(shù)字是工具算的你最好再獨(dú)立驗(yàn)證一次。打開文件資源管理器跳到%APPDATA%\Cursor右鍵屬性看文件夾大小。清理前記一下清理后再看一次差值就是實(shí)際釋放量。更精確的方法是用命令行統(tǒng)計(jì)。在 PowerShell 里跑$path $env:APPDATA\Cursor $size (Get-ChildItem $path -Recurse -Force | Measure-Object -Property Length -Sum).Sum {0:N2} GB -f ($size / 1GB)這條命令會(huì)遞歸統(tǒng)計(jì)整個(gè) Cursor 目錄的大小輸出以 GB 為單位。清理前后各跑一次對(duì)比結(jié)果。如果你想看具體是哪個(gè)文件變小了可以針對(duì)state.vscdb單獨(dú)查Get-Item $env:APPDATA\Cursor\User\globalStorage\state.vscdb | Select-Object Name, {NSizeGB;E{{0:N2} -f ($_.Length/1GB)}}注意state.vscdb的實(shí)際路徑可能是User\globalStorage\state.vscdb不同 Cursor 版本略有差異你可以用Get-ChildItem -Recurse -Filter state.vscdb先找到它。還有一個(gè)更直觀的辦法用 WizTree 或 TreeSize Free 這類磁盤分析工具清理前后各掃一次%APPDATA%\Cursor看樹狀圖的變化。WizTree 讀 MFT 很快幾秒鐘就能掃完整個(gè)盤。我實(shí)測(cè)的一組數(shù)據(jù)供你參考一臺(tái)用了 8 個(gè)月的機(jī)器清理前%APPDATA%\Cursor是 19.6GB其中state.vscdb11.3GB、state.vscdb.backup4.1GB、cursor-agent2.2GB。執(zhí)行cursor-clean clean -y --lang zh --keep-days 90加vacuum之后目錄降到 6.8GB釋放約 12.8GB。state.vscdb從 11.3GB 壓到 1.9GBcursor-agent從 2.2GB 降到 0.4GB。備份文件因?yàn)槟J(rèn)保留還是 4.1GB如果你手動(dòng)刪掉能再省 4GB。驗(yàn)證的時(shí)候有個(gè)細(xì)節(jié)要注意vacuum執(zhí)行期間會(huì)臨時(shí)占用額外磁盤空間因?yàn)?SQLite 要重建文件。如果你的 C 盤已經(jīng)紅到只剩幾百 MB可能 vacuum 會(huì)失敗。這種情況先手動(dòng)刪掉state.vscdb.backup騰點(diǎn)空間再跑 vacuum。另外清理后第一次打開 Cursor 可能會(huì)稍微慢一點(diǎn)因?yàn)樗谥亟ㄋ饕图虞d狀態(tài)。這是正常的用幾次就恢復(fù)了。如果打開后發(fā)現(xiàn)聊天歷史少了那是預(yù)期行為——超過保留天數(shù)的記錄被清了。5. cursor-clean 常見報(bào)錯(cuò)排查與修復(fù)即使工具很簡(jiǎn)單實(shí)際跑的時(shí)候還是可能遇到問題。這一節(jié)我把常見的報(bào)錯(cuò)和排查方法列出來你對(duì)照著看。報(bào)錯(cuò)一cursor-clean不是內(nèi)部或外部命令這是最常見的說明腳本不在 PATH 里。先確認(rèn)裝沒裝pip show cursor-clean如果顯示已安裝找到 Scripts 目錄python -c import sysconfig; print(sysconfig.get_path(scripts))把打印出來的路徑加到系統(tǒng)環(huán)境變量 PATH 里或者直接用完整路徑調(diào)用。如果你用的是pip install --user路徑通常在%APPDATA%\Python\PythonXX\Scripts。報(bào)錯(cuò)二database is locked或壓縮卡住這個(gè)幾乎都是因?yàn)?Cursor 沒完全退出。去任務(wù)管理器確認(rèn)沒有Cursor.exe還要檢查有沒有cursor-agent.exe之類的后臺(tái)進(jìn)程。全部結(jié)束后再跑。如果還是鎖重啟一次電腦最穩(wěn)妥。報(bào)錯(cuò)三PermissionError: [WinError 5] 拒絕訪問兩種可能一是文件被占用同上二是權(quán)限不夠。試試用管理員身份打開 cmd 或 PowerShell 再跑。如果還不行檢查%APPDATA%\Cursor的權(quán)限確保當(dāng)前用戶有完全控制權(quán)。報(bào)錯(cuò)四sqlite3.DatabaseError: file is not a database說明state.vscdb損壞了。這時(shí)候別慌先備份整個(gè)%APPDATA%\Cursor目錄然后用state.vscdb.backup覆蓋state.vscdb再重新跑清理。如果備份也壞了那就只能刪掉state.vscdb讓 Cursor 重建代價(jià)是丟失所有本地歷史。報(bào)錯(cuò)五ModuleNotFoundError: No module named cursor_clean裝是裝了但導(dǎo)入失敗通常是 Python 環(huán)境混亂。確認(rèn)你用的 pip 和 python 是同一個(gè)環(huán)境python -m pip install -U cursor-clean python -m cursor_clean --version用python -m的方式調(diào)用能避免 PATH 和環(huán)境錯(cuò)位的問題。報(bào)錯(cuò)六清理后 Cursor 打不開或配置丟失這種情況一般是誤刪了不該刪的。cursor-clean默認(rèn)只動(dòng)歷史記錄和舊 agent 版本不會(huì)碰你的設(shè)置和擴(kuò)展。如果你手動(dòng)刪了別的文件導(dǎo)致問題從備份恢復(fù)。所以再?gòu)?qiáng)調(diào)一次清理前備份%APPDATA%\Cursor或者至少備份state.vscdb。報(bào)錯(cuò)七vacuum后空間沒釋放SQLite 的 VACUUM 需要臨時(shí)空間如果磁盤滿了會(huì)失敗但可能不報(bào)錯(cuò)。先確認(rèn)磁盤有足夠空間再跑一次。另外如果state.vscdb里有大量未提交的事務(wù)也可能影響。重啟 Cursor 再退出然后重試。排查的時(shí)候有個(gè)通用思路先看報(bào)錯(cuò)信息里的關(guān)鍵詞是權(quán)限問題、占用問題還是數(shù)據(jù)庫(kù)問題然后對(duì)癥下藥。大部分問題都能通過「完全退出 Cursor 管理員權(quán)限 備份后重試」解決。如果你在 Cursor 里配置了自定義模型接入遇到的是 API 相關(guān)的報(bào)錯(cuò)比如 401、連接失敗那和cursor-clean無關(guān)需要檢查你的 Base URL 和 Key 配置。TaoToken 的接入文檔在https://taotoken.net/doc里面有各客戶端的配置示例可以對(duì)照排查。6. 長(zhǎng)期維護(hù) Cursor 磁盤占用的實(shí)用建議清理一次能管幾個(gè)月但 Cursor 會(huì)繼續(xù)寫歷史空間還會(huì)慢慢漲回來。與其等 C 盤爆了再救火不如養(yǎng)成幾個(gè)習(xí)慣把占用控制在合理范圍。第一個(gè)習(xí)慣是定期跑cursor-clean scan。不用天天跑一個(gè)月一次就行。掃描是只讀的幾秒鐘出結(jié)果看到體積漲到你覺得不舒服了就清一次。我一般設(shè)個(gè)日歷提醒每月 1 號(hào)掃一下。第二個(gè)習(xí)慣是控制保留天數(shù)。默認(rèn) 90 天對(duì)大多數(shù)人夠用但如果你聊天記錄特別多可以降到 60 天甚至 45 天。改法就是--keep-days 60。別設(shè)太低不然想翻舊賬的時(shí)候找不到。第三個(gè)習(xí)慣是定期清cursor-agent舊版本。這個(gè)用cursor-clean clean-agents -y --lang zh單獨(dú)跑很快。Agent CLI 更新頻繁舊版本堆著純占地方。第四個(gè)習(xí)慣是備份文件別長(zhǎng)期留。state.vscdb.backup動(dòng)輒幾個(gè) GB如果你確認(rèn)當(dāng)前數(shù)據(jù)庫(kù)沒問題可以手動(dòng)刪掉它。下次 Cursor 會(huì)重新生成。不過刪之前確保 Cursor 是關(guān)的。第五個(gè)習(xí)慣是把 Cursor 的緩存目錄考慮遷移。如果你 C 盤實(shí)在小可以用符號(hào)鏈接把%APPDATA%\Cursor指到 D 盤。方法是先退出 Cursor把整個(gè)目錄移到 D 盤然后管理員權(quán)限跑mklink /D %APPDATA%\Cursor D:\CursorData這樣 Cursor 還是按原路徑讀寫實(shí)際文件在 D 盤。不過這個(gè)操作有風(fēng)險(xiǎn)遷移前務(wù)必備份而且某些 Cursor 版本可能不認(rèn)符號(hào)鏈接試之前想清楚。第六個(gè)習(xí)慣是關(guān)注 Cursor 版本更新。官方偶爾會(huì)優(yōu)化存儲(chǔ)策略新版本可能自帶清理選項(xiàng)。保持更新說不定哪天就不用第三方工具了。最后說下工具本身的維護(hù)。cursor-clean是開源的PyPI 頁(yè)面在https://pypi.org/project/cursor-clean/倉(cāng)庫(kù)在https://github.com/TIZZYONE/cursor-clean.git。如果你發(fā)現(xiàn) bug 或者想加功能可以提 issue 或 PR。邏輯簡(jiǎn)單改起來不難。如果你在清理之外還想優(yōu)化 Cursor 的模型使用成本可以了解下 TaoToken 的 Coding Plan地址是https://taotoken.net/coding-plan適合長(zhǎng)期編碼和 Agent 場(chǎng)景。API Keys 管理在https://taotoken.net/api-keys接入文檔在https://taotoken.net/doc。這些是可選項(xiàng)按你的實(shí)際需求決定?；氐酱疟P這件事Cursor 很強(qiáng)但本地狀態(tài)會(huì)悄悄長(zhǎng)大。養(yǎng)成定期 scan、按需 clean 的習(xí)慣C 盤就不會(huì)再莫名其妙飄紅。騰出來的往往不是幾百 MB而是好幾 GB。 Cursor 把 C 盤吃掉 20GB？用 Python 開源工具 cursor-clean 一鍵清理
1. Cursor 緩存膨脹把 C 盤吃滿的真實(shí)場(chǎng)景如果你在 Windows 上用 Cursor 寫代碼超過半年大概率會(huì)遇到一個(gè)很反直覺的問題項(xiàng)目代碼才幾百 MBC 盤卻莫名其妙少了十幾 GB。打開「此電腦」一看系統(tǒng)盤飄紅Windows 更新都裝不下。很多人第一反應(yīng)是去刪node_modules、清npm cache、卸載不用的軟件折騰一圈發(fā)現(xiàn)根本沒釋放多少空間。真正的大頭藏在用戶目錄里。你可以按Win R輸入下面這個(gè)路徑直接跳過去%APPDATA%\Cursor展開后通常是C:\Users\你的用戶名\AppData\Roaming\Cursor。用 WizTree 或者 TreeSize Free 掃一下這個(gè)目錄你會(huì)看到幾個(gè)體積夸張的文件和文件夾。我實(shí)測(cè)過一臺(tái)用了 8 個(gè)月的機(jī)器這個(gè)目錄接近 20GB拆開看主要是這么幾塊內(nèi)容大約占用是什么state.vscdb~11GB本地狀態(tài)庫(kù)聊天、Agent、Composer 歷史state.vscdb.backup~4GB上面那個(gè)庫(kù)的備份cursor-agent多版本~2GB歷史版本的 Agent CLI 安裝包CachedData、logs等少量緩存和日志結(jié)論很清楚不是你的項(xiàng)目文件占空間是 Cursor 自己把聊天記錄和 Agent 歷史越堆越多。幾個(gè)月前的對(duì)話對(duì)你基本沒用但它一直躺在 SSD 里。官方設(shè)置里又沒有「只保留最近 90 天」這種開關(guān)手動(dòng)去刪又怕把配置搞壞。這就是cursor-clean要解決的問題。它是一個(gè)輕量 Python 命令行工具專門掃描 Cursor 的 Roaming 目錄告訴你哪些能刪、哪些該留然后按你的策略清理。適合誰用所有在 Windows 上用 Cursor、C 盤開始告急的開發(fā)者。不需要你懂 SQLite也不需要你手動(dòng)去翻目錄裝完就能跑。下面我會(huì)從定位大文件目錄開始一步步帶你裝好、掃描、清理最后用磁盤占用對(duì)比驗(yàn)證效果。整個(gè)過程可復(fù)制跟著做就行。2. 用 cursor-clean 定位并清理 Cursor 大文件目錄在動(dòng)手清理之前先理解cursor-clean的設(shè)計(jì)思路這樣你用起來才放心。它的邏輯非常樸素掃描 Cursor 的 Roaming 目錄識(shí)別出三類可以安全處理的目標(biāo)然后交給你確認(rèn)。第一類是state.vscdb里的歷史記錄。這是 Cursor 的本地狀態(tài)庫(kù)用 SQLite 存儲(chǔ)聊天、Agent、Composer 的歷史都塞在里面。cursor-clean默認(rèn)只保留最近 90 天的記錄更早的會(huì)被清掉。這個(gè)天數(shù)可以通過--keep-days參數(shù)改比如你只想留 60 天就傳 60。第二類是舊的cursor-agent版本。Cursor 的 Agent CLI 每次更新都會(huì)裝一份新的舊版本不會(huì)自動(dòng)刪。工具的策略是只保留最新一份其余刪掉。第三類是state.vscdb.backup。這個(gè)是備份文件工具默認(rèn)不刪保留著以防萬一。如果你確認(rèn)不需要可以自己手動(dòng)處理。它有幾個(gè)我比較認(rèn)可的點(diǎn)零第三方依賴只用 Python 標(biāo)準(zhǔn)庫(kù)不建自己的數(shù)據(jù)庫(kù)支持中文和英文界面先掃描再確認(rèn)避免誤刪。技術(shù)棧就是「掃目錄 改 Cursor 自己的 state.vscdb 刪舊文件夾」邏輯簡(jiǎn)單到你可以自己審計(jì)源碼。安裝方式有兩種。最省事的是從 PyPI 裝pip install -U cursor-clean如果你網(wǎng)絡(luò)環(huán)境訪問 PyPI 慢也可以用國(guó)內(nèi)鏡像pip install -U cursor-clean -i https://pypi.tuna.tsinghua.edu.cn/simple裝完之后驗(yàn)證一下cursor-clean --version能打印出版本號(hào)就說明裝好了。環(huán)境要求是 Windows Python 3.9 及以上。如果你還沒裝 Python去 python.org 下個(gè) 3.11 或 3.12 都行安裝時(shí)記得勾選「Add Python to PATH」。這里有個(gè)前置動(dòng)作必須強(qiáng)調(diào)清理前先完全退出 Cursor。不是關(guān)窗口是去任務(wù)管理器里確認(rèn)沒有Cursor.exe進(jìn)程。因?yàn)楣ぞ咭獕嚎s SQLite 數(shù)據(jù)庫(kù)如果 Cursor 還開著占用文件壓縮可能卡住甚至損壞。按Ctrl Shift Esc打開任務(wù)管理器在「進(jìn)程」里找 Cursor全部結(jié)束任務(wù)。退出之后先跑掃描看看能清什么cursor-clean scan --lang zh--lang zh是讓輸出用中文不加就是英文。掃描是只讀操作不會(huì)改任何東西你可以放心跑。輸出會(huì)列出各個(gè)目標(biāo)的當(dāng)前大小、可清理大小、保留策略。確認(rèn)沒問題后再執(zhí)行清理cursor-clean clean --lang zh默認(rèn)是交互式的會(huì)問你確認(rèn)。如果你想非交互一鍵清cursor-clean clean -y --lang zh常用參數(shù)我整理成一張表方便你按需組合參數(shù)作用示例--keep-days N只保留最近 N 天聊天cursor-clean clean --lang zh --keep-days 60-y非交互直接確認(rèn)cursor-clean clean -y --lang zhclean-agents只刪舊 agent 版本cursor-clean clean-agents -y --lang zhvacuum只壓縮數(shù)據(jù)庫(kù)cursor-clean vacuum --lang zh如果你只想處理某一類可以分開跑。比如先只刪舊 agent 版本cursor-clean clean-agents -y --lang zh再單獨(dú)壓縮數(shù)據(jù)庫(kù)cursor-clean vacuum --lang zhvacuum這個(gè)操作值得單獨(dú)說。SQLite 刪數(shù)據(jù)后文件不會(huì)自動(dòng)變小需要執(zhí)行 VACUUM 重建數(shù)據(jù)庫(kù)文件才能真正釋放空間。cursor-clean幫你做了這件事這也是為什么清理后能看到明顯體積下降。3. 可復(fù)制的 cursor-clean 配置與清理參數(shù)這一節(jié)給你一份可以直接抄的配置和命令組合。雖然cursor-clean是命令行工具不需要寫 JSON 或 TOML 配置文件但你可以把常用參數(shù)固化成一個(gè)批處理腳本省得每次敲。先看最常用的清理流程我把它寫成一個(gè).bat文件放在桌面雙擊就能跑echo off chcp 65001 nul echo 正在掃描 Cursor 緩存... cursor-clean scan --lang zh echo. echo 按任意鍵開始清理保留最近 90 天... pause nul cursor-clean clean -y --lang zh --keep-days 90 echo. echo 清理完成按任意鍵退出。 pause nulchcp 65001是為了讓中文正常顯示不然 cmd 里可能亂碼。這個(gè)腳本的邏輯就是先掃描給你看暫停等你確認(rèn)再執(zhí)行清理。如果你想把保留天數(shù)改成 60 天把--keep-days 90改成--keep-days 60就行。想更激進(jìn)一點(diǎn)只留 30 天就寫 30。我的建議是別低于 30 天因?yàn)橛行╉?xiàng)目的上下文你可能過幾周還要翻。對(duì)于想接入自動(dòng)化流程的場(chǎng)景比如你寫了個(gè)定時(shí)任務(wù)每周清理一次可以用非交互模式echo off chcp 65001 nul cursor-clean clean -y --lang zh --keep-days 90 cursor-clean clean-agents -y --lang zh cursor-clean vacuum --lang zh這三條命令分別做三件事清理 90 天前的聊天記錄、刪除舊 agent 版本、壓縮數(shù)據(jù)庫(kù)。組合起來就是一次完整清理。如果你用的是 PowerShell語法基本一樣只是暫停命令不同cursor-clean scan --lang zh cursor-clean clean -y --lang zh --keep-days 90 cursor-clean vacuum --lang zh這里要提醒一個(gè)容易踩的坑批處理腳本里不要加cursor-clean的完整路徑除非你確定 PATH 里有。如果你是用pip install --user裝的腳本可能不在系統(tǒng) PATH 里需要寫成完整路徑比如%APPDATA%\Python\Python311\Scripts\cursor-clean.exe clean -y --lang zh具體路徑取決于你的 Python 版本和安裝方式。不確定的話在 cmd 里跑where cursor-clean就能看到實(shí)際位置。關(guān)于模型和 API 的配置這里要說明一下cursor-clean本身是純本地工具不涉及任何模型調(diào)用所以不需要配 Base URL、Key 或 Model ID。它只操作本地文件。如果你在 Cursor 里配置了自定義模型接入那是另一回事和清理工具無關(guān)。但如果你確實(shí)需要在 Cursor 里接入第三方模型服務(wù)來降低使用成本可以了解下 TaoToken 這類聚合服務(wù)。它的 API 地址是https://taotoken.net/api在 Cursor 的模型設(shè)置里填 Base URL 和對(duì)應(yīng)的 Key 就能用。不過這是可選項(xiàng)和本文的清理主題分開你按需決定?；氐角謇肀旧怼Ｎ医ㄗh你把掃描和清理分成兩步不要一上來就-y。先scan看清楚哪些文件大、清理策略是什么確認(rèn)沒有誤傷再清。這個(gè)習(xí)慣能幫你避免「手滑刪了還要用的歷史」這種尷尬。4. 驗(yàn)證清理效果與磁盤占用對(duì)比方法清理跑完之后怎么確認(rèn)真的釋放了空間不能只看工具的輸出要自己動(dòng)手驗(yàn)證。這里給你幾種方法從簡(jiǎn)單到嚴(yán)謹(jǐn)。最直接的是看工具自己的輸出。cursor-clean clean執(zhí)行完會(huì)打印清理前后的對(duì)比類似這樣清理前 state.vscdb: 11.2 GB 清理后 state.vscdb: 1.8 GB 釋放空間: 9.4 GB但這個(gè)數(shù)字是工具算的你最好再獨(dú)立驗(yàn)證一次。打開文件資源管理器跳到%APPDATA%\Cursor右鍵屬性看文件夾大小。清理前記一下清理后再看一次差值就是實(shí)際釋放量。更精確的方法是用命令行統(tǒng)計(jì)。在 PowerShell 里跑$path $env:APPDATA\Cursor $size (Get-ChildItem $path -Recurse -Force | Measure-Object -Property Length -Sum).Sum {0:N2} GB -f ($size / 1GB)這條命令會(huì)遞歸統(tǒng)計(jì)整個(gè) Cursor 目錄的大小輸出以 GB 為單位。清理前后各跑一次對(duì)比結(jié)果。如果你想看具體是哪個(gè)文件變小了可以針對(duì)state.vscdb單獨(dú)查Get-Item $env:APPDATA\Cursor\User\globalStorage\state.vscdb | Select-Object Name, {NSizeGB;E{{0:N2} -f ($_.Length/1GB)}}注意state.vscdb的實(shí)際路徑可能是User\globalStorage\state.vscdb不同 Cursor 版本略有差異你可以用Get-ChildItem -Recurse -Filter state.vscdb先找到它。還有一個(gè)更直觀的辦法用 WizTree 或 TreeSize Free 這類磁盤分析工具清理前后各掃一次%APPDATA%\Cursor看樹狀圖的變化。WizTree 讀 MFT 很快幾秒鐘就能掃完整個(gè)盤。我實(shí)測(cè)的一組數(shù)據(jù)供你參考一臺(tái)用了 8 個(gè)月的機(jī)器清理前%APPDATA%\Cursor是 19.6GB其中state.vscdb11.3GB、state.vscdb.backup4.1GB、cursor-agent2.2GB。執(zhí)行cursor-clean clean -y --lang zh --keep-days 90加vacuum之后目錄降到 6.8GB釋放約 12.8GB。state.vscdb從 11.3GB 壓到 1.9GBcursor-agent從 2.2GB 降到 0.4GB。備份文件因?yàn)槟J(rèn)保留還是 4.1GB如果你手動(dòng)刪掉能再省 4GB。驗(yàn)證的時(shí)候有個(gè)細(xì)節(jié)要注意vacuum執(zhí)行期間會(huì)臨時(shí)占用額外磁盤空間因?yàn)?SQLite 要重建文件。如果你的 C 盤已經(jīng)紅到只剩幾百 MB可能 vacuum 會(huì)失敗。這種情況先手動(dòng)刪掉state.vscdb.backup騰點(diǎn)空間再跑 vacuum。另外清理后第一次打開 Cursor 可能會(huì)稍微慢一點(diǎn)因?yàn)樗谥亟ㄋ饕图虞d狀態(tài)。這是正常的用幾次就恢復(fù)了。如果打開后發(fā)現(xiàn)聊天歷史少了那是預(yù)期行為——超過保留天數(shù)的記錄被清了。5. cursor-clean 常見報(bào)錯(cuò)排查與修復(fù)即使工具很簡(jiǎn)單實(shí)際跑的時(shí)候還是可能遇到問題。這一節(jié)我把常見的報(bào)錯(cuò)和排查方法列出來你對(duì)照著看。報(bào)錯(cuò)一cursor-clean不是內(nèi)部或外部命令這是最常見的說明腳本不在 PATH 里。先確認(rèn)裝沒裝pip show cursor-clean如果顯示已安裝找到 Scripts 目錄python -c import sysconfig; print(sysconfig.get_path(scripts))把打印出來的路徑加到系統(tǒng)環(huán)境變量 PATH 里或者直接用完整路徑調(diào)用。如果你用的是pip install --user路徑通常在%APPDATA%\Python\PythonXX\Scripts。報(bào)錯(cuò)二database is locked或壓縮卡住這個(gè)幾乎都是因?yàn)?Cursor 沒完全退出。去任務(wù)管理器確認(rèn)沒有Cursor.exe還要檢查有沒有cursor-agent.exe之類的后臺(tái)進(jìn)程。全部結(jié)束后再跑。如果還是鎖重啟一次電腦最穩(wěn)妥。報(bào)錯(cuò)三PermissionError: [WinError 5] 拒絕訪問兩種可能一是文件被占用同上二是權(quán)限不夠。試試用管理員身份打開 cmd 或 PowerShell 再跑。如果還不行檢查%APPDATA%\Cursor的權(quán)限確保當(dāng)前用戶有完全控制權(quán)。報(bào)錯(cuò)四sqlite3.DatabaseError: file is not a database說明state.vscdb損壞了。這時(shí)候別慌先備份整個(gè)%APPDATA%\Cursor目錄然后用state.vscdb.backup覆蓋state.vscdb再重新跑清理。如果備份也壞了那就只能刪掉state.vscdb讓 Cursor 重建代價(jià)是丟失所有本地歷史。報(bào)錯(cuò)五ModuleNotFoundError: No module named cursor_clean裝是裝了但導(dǎo)入失敗通常是 Python 環(huán)境混亂。確認(rèn)你用的 pip 和 python 是同一個(gè)環(huán)境python -m pip install -U cursor-clean python -m cursor_clean --version用python -m的方式調(diào)用能避免 PATH 和環(huán)境錯(cuò)位的問題。報(bào)錯(cuò)六清理后 Cursor 打不開或配置丟失這種情況一般是誤刪了不該刪的。cursor-clean默認(rèn)只動(dòng)歷史記錄和舊 agent 版本不會(huì)碰你的設(shè)置和擴(kuò)展。如果你手動(dòng)刪了別的文件導(dǎo)致問題從備份恢復(fù)。所以再?gòu)?qiáng)調(diào)一次清理前備份%APPDATA%\Cursor或者至少備份state.vscdb。報(bào)錯(cuò)七vacuum后空間沒釋放SQLite 的 VACUUM 需要臨時(shí)空間如果磁盤滿了會(huì)失敗但可能不報(bào)錯(cuò)。先確認(rèn)磁盤有足夠空間再跑一次。另外如果state.vscdb里有大量未提交的事務(wù)也可能影響。重啟 Cursor 再退出然后重試。排查的時(shí)候有個(gè)通用思路先看報(bào)錯(cuò)信息里的關(guān)鍵詞是權(quán)限問題、占用問題還是數(shù)據(jù)庫(kù)問題然后對(duì)癥下藥。大部分問題都能通過「完全退出 Cursor 管理員權(quán)限 備份后重試」解決。如果你在 Cursor 里配置了自定義模型接入遇到的是 API 相關(guān)的報(bào)錯(cuò)比如 401、連接失敗那和cursor-clean無關(guān)需要檢查你的 Base URL 和 Key 配置。TaoToken 的接入文檔在https://taotoken.net/doc里面有各客戶端的配置示例可以對(duì)照排查。6. 長(zhǎng)期維護(hù) Cursor 磁盤占用的實(shí)用建議清理一次能管幾個(gè)月但 Cursor 會(huì)繼續(xù)寫歷史空間還會(huì)慢慢漲回來。與其等 C 盤爆了再救火不如養(yǎng)成幾個(gè)習(xí)慣把占用控制在合理范圍。第一個(gè)習(xí)慣是定期跑cursor-clean scan。不用天天跑一個(gè)月一次就行。掃描是只讀的幾秒鐘出結(jié)果看到體積漲到你覺得不舒服了就清一次。我一般設(shè)個(gè)日歷提醒每月 1 號(hào)掃一下。第二個(gè)習(xí)慣是控制保留天數(shù)。默認(rèn) 90 天對(duì)大多數(shù)人夠用但如果你聊天記錄特別多可以降到 60 天甚至 45 天。改法就是--keep-days 60。別設(shè)太低不然想翻舊賬的時(shí)候找不到。第三個(gè)習(xí)慣是定期清cursor-agent舊版本。這個(gè)用cursor-clean clean-agents -y --lang zh單獨(dú)跑很快。Agent CLI 更新頻繁舊版本堆著純占地方。第四個(gè)習(xí)慣是備份文件別長(zhǎng)期留。state.vscdb.backup動(dòng)輒幾個(gè) GB如果你確認(rèn)當(dāng)前數(shù)據(jù)庫(kù)沒問題可以手動(dòng)刪掉它。下次 Cursor 會(huì)重新生成。不過刪之前確保 Cursor 是關(guān)的。第五個(gè)習(xí)慣是把 Cursor 的緩存目錄考慮遷移。如果你 C 盤實(shí)在小可以用符號(hào)鏈接把%APPDATA%\Cursor指到 D 盤。方法是先退出 Cursor把整個(gè)目錄移到 D 盤然后管理員權(quán)限跑mklink /D %APPDATA%\Cursor D:\CursorData這樣 Cursor 還是按原路徑讀寫實(shí)際文件在 D 盤。不過這個(gè)操作有風(fēng)險(xiǎn)遷移前務(wù)必備份而且某些 Cursor 版本可能不認(rèn)符號(hào)鏈接試之前想清楚。第六個(gè)習(xí)慣是關(guān)注 Cursor 版本更新。官方偶爾會(huì)優(yōu)化存儲(chǔ)策略新版本可能自帶清理選項(xiàng)。保持更新說不定哪天就不用第三方工具了。最后說下工具本身的維護(hù)。cursor-clean是開源的PyPI 頁(yè)面在https://pypi.org/project/cursor-clean/倉(cāng)庫(kù)在https://github.com/TIZZYONE/cursor-clean.git。如果你發(fā)現(xiàn) bug 或者想加功能可以提 issue 或 PR。邏輯簡(jiǎn)單改起來不難。如果你在清理之外還想優(yōu)化 Cursor 的模型使用成本可以了解下 TaoToken 的 Coding Plan地址是https://taotoken.net/coding-plan適合長(zhǎng)期編碼和 Agent 場(chǎng)景。API Keys 管理在https://taotoken.net/api-keys接入文檔在https://taotoken.net/doc。這些是可選項(xiàng)按你的實(shí)際需求決定?；氐酱疟P這件事Cursor 很強(qiáng)但本地狀態(tài)會(huì)悄悄長(zhǎng)大。養(yǎng)成定期 scan、按需 clean 的習(xí)慣C 盤就不會(huì)再莫名其妙飄紅。騰出來的往往不是幾百 MB而是好幾 GB。