文件系统 Agent + 本地操作

这个 pack 包含什么

大多数「AI 帮你管文件」的演示看着都很美，直到你意识到 agent 一个错误的 rename 就能糊掉你真在乎的文件夹。这个 pack 是让 agent 干真正本地文件活的那套安全栈 —— 就是每个开发者都欠了一屁股、永远轮不到处理的清洁工任务：从 2022 年起没整理过的 ~/Downloads、每张截图都有 4 份近重复、发票名清一色 Scan_001.pdf 到 Scan_417.pdf、那个 ~/old-projects/ 你早说要归档了。

目标用户是开发者（不是运维、也不是用 GUI 思维的终端用户）：终端熟、愿意写 30 行 AGENTS.md、至少摸过一个 CLI agent（Claude Code / Codex CLI / Aider / gptme）。他从这个 pack 拿到的是一份分层设计 —— 给 agent 的安全 API（MCP）、人那一边的核查工具（ripgrep / fzf / Yazi）、护栏（AGENTS.md / Hooks）、加一个兜底的脚本化自主 agent（gptme）。这里没有一个魔法「AI 整理器」app。这是让文件系统 agent 值得信任、能放手让它跑的基础设施。

这个 pack 不包含云同步工具（rclone / Syncthing）—— 那是另一类问题。它也不替代 现代 CLI 工具腰带（fd / delta / bat / eza / hyperfine）—— 先装那个；这个 pack 是上面的 agent 增强层。Agent 结对编程看 Aider 终端结对编程必备。终端工作流模式看 终端原生 AI 工作流。

推荐安装顺序（安全 API → 人工工具 → 护栏 → 自主循环）

1. Desktop Commander MCP — 本地终端 + 文件 — 从这里开始。这是任何 MCP-aware agent（Claude Code / Codex CLI / Cursor agent 模式 / Cline / gptme）真正动你文件系统时插进去的安全 API 面。它暴露一套精选工具 —— 读文件、写文件、列目录、跑 shell、加上 PDF / DOCX / Excel 文本抽取 —— 全在一个审计过的接口后面，而不是每个 agent 重新发明自己的 bash 包装。胜在「在一个地方设权限范围」：你把它指向 ~/Downloads 和 ~/projects，agent 物理上读不到 ~/.ssh，因为不在配置的根目录里。这个 pack 你只装一个，就装这个 —— 它是「agent 带 shell 权限」（吓死人）和「agent 文件权限锁两个目录」（合理的周二）的分水岭。
2. ripgrep — 用正则递归搜目录 — 地球上最快的内容搜索原语。你告诉 agent「找出每一份提到发票号 INV-2024 的 PDF」时，底下干活的就是 ripgrep（或者应该是）。也单独装 —— 你会直接用它核查 agent 声称找到了什么。rg -l 'INV-2024' ~/Downloads/*.pdf 毫秒级返回路径；问 agent 要同样的列表、对比。Agent 的列表对不上 ripgrep 的，就是 agent 在编文件名，你立刻停。
3. fzf — 命令行模糊查找 — ripgrep 的交互式对偶。Agent 把范围缩到 40 个候选文件、你要抽查 5 个，fzf 把列表 pipe 进去，方向键翻、自带 preview。也间接给 agent 当承重墙：很多 shell 辅助工具和 Yazi（#4）底下都用 fzf，装一次解锁整个栈的模糊选择。配 --preview 参数，动手前先看到文件内容。
4. Yazi — 极速终端文件管理器 — 视觉层。Agent 说「我把 200 个文件从 ~/Downloads/screenshots/ 挪到 ~/Pictures/2024/」时，你打开 Yazi 进两个目录，实时看着移动发生。异步预览 —— 50MB PDF preview 不卡 UI；SSH 上图片用 sixel/kitty 也能 preview。心智模型：agent 干批量活、Yazi 是你的真相核查窗口。永远开一个 Yazi 看着，别让 agent 在无人盯防时跑破坏性操作 —— 你要看见东西出现和消失。
5. AGENTS.md — 编码 agent 指令的开放格式 — repo 根目录（或者个人文件场景的 ~/.agents.md）单个 Markdown，告诉每个现代 CLI agent 规矩。文件系统操作的场景下，这文件长得跟代码 repo 不一样：「Downloads 是收件箱，每周整理一次。Pictures/YYYY/MM 是归档结构。永远别动 ~/Documents/legal/。超过 1 年的 PDF 归档到 ~/Archive/PDFs/。重复文件按最大文件胜出解决」。Codex CLI / Aider / Claude Code / Cursor agent 模式 / Gemini CLI 全部都读它（大多数是自家原生配置的 fallback）。一份真理来源，胜过 N 份 CLAUDE.md / .cursorrules / .windsurfrules 副本。放 agent 去动私人文件之前能写的最高杠杆 50 行 Markdown。
6. Claude Code Hooks — 自动化你的 AI 工作流 — 事件驱动的护栏。PreToolUse hook 阻止写到白名单之外的目录、PostToolUse hook 把 agent 碰过的每个文件记到当天的日志（回滚有痕）、Notification hook 长任务完成给你弹通知。Hook 配置就是事件触发的 shell —— 没有插件系统要学。就算你不用 Claude Code 当主 agent，模式也通：每个现代 CLI agent 都有 hook 对等物（Codex CLI 事件 / Aider commit hook）。从一个开始：PreToolUse: Write → fail-if-path-outside-allowlist.sh "$file"。这一个 hook 阻止了最严重那类事故。
7. Jina Reader — 把任意 URL 转成 LLM 友好的 Markdown — 本地文件和远程内容之间的桥。想从 URL 下一份 200 页 PDF 让 agent 在本地索引，r.jina.ai/<url> 一次调用给你干净的 LLM-ready Markdown —— 不用搭 pdftotext 链、没有格式噪音。输出存本地、agent 指向那个目录、完事。特别适合「整理我的 Downloads」场景：一半 PDF 是抓来的手册/论文、原 URL 早 404 了 —— Jina Reader 抓一次转一次，之后你有永久的本地 Markdown 副本，agent 用 ripgrep（#2）搜就行。
8. gptme — 终端 AI agent，自带 tools 和 MCP — 可脚本化的自主 agent。pipx install gptme、指向任何模型（Anthropic / OpenAI / 本地 Ollama），你就有一个能跑 shell、改文件、支持 MCP server（包括 #1 的 Desktop Commander MCP）的 agent —— 关键是支持 CI / cron 脚本的非交互模式。这里的杀手用例：一个每周 cron 跑 gptme --non-interactive "把 ~/Downloads 里超过 7 天的全部按文件类型归档到 ~/Archive/$(date +%Y-%m)/"。Agent 跑、cron 记日志、周日早上你看。Claude Code / Codex CLI 觉得太重时用、需要在没交互终端的脚本里跑自动化时用。
9. tmux — 终端复用器 — 把所有东西串起来的 workspace。布局：pane 1 = agent（Claude Code / gptme）、pane 2 = Yazi 盯着 agent 操作的目录、pane 3 = watch ls -la ~/Downloads 或 inotifywait tail 看每一次变化、pane 4 = tail -f agent 的 hook 日志。SSH 上 detach session、明天回来，agent 跑要么还在跑、要么已经干净停了。没 tmux 你要在四个终端窗口之间 alt-tab、还会跟丢。有 tmux 整个文件系统 agent 操作就是一个有名字的 session，能 attach/detach。

它们怎么协同

┌────────────────────────────────────────────────────────────────┐
│  tmux session: "file-ops" (#9)                                  │
│                                                                 │
│  ┌────────────────────────┐  ┌─────────────────────────────┐   │
│  │ pane 1: agent          │  │ pane 2: Yazi (#4)           │   │
│  │  Claude Code / gptme   │  │   盯着 ~/Downloads          │   │
│  │  (#8)                  │  │   视觉真相核查              │   │
│  │                        │  │                             │   │
│  │  读 AGENTS.md (#5)     │  └─────────────────────────────┘   │
│  │  通过 Desktop Commander │                                   │
│  │   MCP (#1) 动文件      │  ┌─────────────────────────────┐   │
│  │  ripgrep (#2) 跑       │  │ pane 3: 变更 tail           │   │
│  │   底层内容搜            │  │   watch ls / inotifywait    │   │
│  │  fzf (#3) 给用户        │  │                             │   │
│  │   做选择                │  └─────────────────────────────┘   │
│  │  Jina Reader (#7) 把   │                                   │
│  │   URL 转本地 Markdown  │  ┌─────────────────────────────┐   │
│  │                        │  │ pane 4: hook 日志 tail      │   │
│  │  每次 shell 调用       │  │   tail -f ~/.agent-log.md   │   │
│  │  → Hooks (#6) → 日志   │  │                             │   │
│  └────────────────────────┘  └─────────────────────────────┘   │
└────────────────────────────────────────────────────────────────┘

承重墙：Desktop Commander MCP + AGENTS.md + Hooks。没 MCP，agent 拿到原始 shell 权限、你没东西可锁。没 AGENTS.md，agent 不知道你的整理规则、每次 session 重新发明。没 Hooks，没审计、没急停按钮。其他全是操作员舒适层。

如果你只有一小时：装 Desktop Commander MCP、把它指向一个项目目录加 ~/Downloads（不是整个 home）、写 30 行 ~/.agents.md（你的整理规则 + 三条「永远别动」路径）、加一个 PreToolUse hook 阻止白名单外的写。这就够安全放 agent 去碰文件了。剩下的资产是周末作业。

你会遇到的取舍（文件系统 agent vs 云同步 vs 手动）

• Agent 跑文件 vs 云同步规则引擎（Hazel / Maid） — Hazel（macOS）和 Maid（跨平台）是规则引擎：「文件名匹配 Scan_*.pdf 且超过 30 天，移到 ~/Documents/Scans/」。规则稳定的场景它们很好。Agent 赢在规则失效的地方：「按文件名和文件内容能推出的类别整理这 400 个混合下载」。经验法则：5 行 Hazel 规则能写清的整理用 Hazel；要 50 行加一堆异常的用 agent。两者能并存 —— Hazel 处理确定性的 80%，agent 处理凌乱的长尾。
• MCP filesystem vs 给 agent 裸 shell — 裸 shell（Bash 工具、bash MCP server、--dangerously-skip-permissions）配置最快、啥都能干。Desktop Commander MCP 是受限但审计的替代品：限定根目录、结构化工具调用、好记日志。对的答案看任务 —— 裸 shell 适合你会紧盯的一次性创造性文件操作；MCP 适合任何重复性或无人盯防的活。铁律：永远不要给 agent --dangerously-skip-permissions 加 home 目录访问。
• ripgrep + fzf vs 基于 LLM 的语义文件搜索 — 像 个人知识库 RAG 那样把你的文件嵌入向量库、按语义搜索的工具。Ripgrep 按精确正则搜。「找 2024 年 3 月 Acme 公司的发票」—— ripgrep 200ms 搞定、零成本；语义搜索要调一次模型、还可能漏掉打错字的公司名。「找那条我反对用 Postgres 跑时序数据的笔记」—— 语义赢。两个都跑。Ripgrep 是主力；语义搜索是你想不起关键词时的兜底。
• Yazi vs ranger vs nnn vs lf — 四个都是 TUI 文件管理器。Yazi 最年轻、最快、异步 preview 最好（50MB PDF preview 不卡）。Ranger 插件生态最大、配置最成熟。nnn 最极简。lf 居中。为了盯着 agent 干活这个特定场景，Yazi 的 preview 速度比 ranger 的插件重要 —— 你要快速翻文件、不想等。如果你已经会 ranger、不想重学键位，留 ranger。
• gptme vs Claude Code 跑非交互操作 — Claude Code 交互式很好，cron 脚本里别扭。Gptme 两个都能用 —— 同一套 agent 循环，在交互式 REPL 或脚本管道里。你看着的时候用 Claude Code；你不看着的时候用 gptme。两个能共用同一个 Desktop Commander MCP 和 AGENTS.md，agent 行为跨模式一致。

常见踩坑

• 没白名单 = 早晚一个目录被删 — 经典翻车现场是配置 Desktop Commander MCP 时不限定根目录、或者跳过 PreToolUse Hook。Agent 早晚干件让你惊讶的事 —— 在你没预期的地方写文件、或者 rm 一个目录（因为它误读了你的 prompt）。白名单不是可选的。「agent 有整个 $HOME 权限」当成要修的配置 bug，不是你能长期处于的状态。
• 相信 agent 自己报的数字 — Agent 会信誓旦旦说「我整理了 247 个文件」。用 find ~/Archive/2024-01 -type f | wc -l 或 eza -la | wc -l 核。任何长 session「agent 声称 X、现实 X-15（或 X+15）」的次数都不是零。把核查嵌进循环：每批操作结束 agent 打个数字、你跑等价 shell 数一遍、对比。
• 不 dry-run 就让 agent 跑 rename — 批量改名是最易后悔的一类文件系统操作，因为不明显可逆。永远两步：先让 agent 打出准备改的 mv old new 列表（不执行）、肉眼看一遍、再执行。很多工具（f2 / rename / mmv）有 --dry-run flag —— 在 AGENTS.md 里规定默认用 dry-run、真跑前必须显式确认。
• 按文件名 vs 按内容哈希去重 — 去重规则是「同文件名 = 同文件」的话，你会把 ~/Downloads/report.pdf 和 ~/Downloads/january/report.pdf 合掉、它们实际是不同文档。对的规则是内容哈希（sha256 或 BLAKE3）。fclones / czkawka / rmlint 都原生支持；如果你 prompt agent 去重，prompt 必须说「按文件内容哈希、不是按文件名」。AGENTS.md 一句话省一堆痛。
• 不核查就归档 — 「把超过 1 年的全部移到 ~/Archive/」听着安全，直到你发现归档目标卷是个网络盘当前没挂载、或者路径不存在、agent 直接在 ~/Archive 建了个普通目录。归档操作必须：(a) 核查目标存在且可写、(b) 先 copy 再 delete（重要文件永远不跨卷 mv）、(c) 在归档里留一个 _INDEX.txt 记原路径。写进 AGENTS.md。
• 「agent 准备做 X」和「agent 做了 X」之间没 diff — 没 hook 日志 tail（tmux 图的 pane 4），你没记录实际发生了啥。半年后你找不到文件时，你想要一个 ~/.agent-log.md 能 grep 文件名查它啥时候、为啥被移走。Hook 的成本是一行；不要 hook 的成本是每个丢失文件 30 分钟的 git 考古。装 Desktop Commander MCP 的同一天就配上。