fileview

一个基于 Node.js + Ink 的终端文件浏览器 TUI。 集文件树、语法高亮预览、内置编辑器、目录内执行 shell 命令、文件内搜索 + 全局搜索（ripgrep）于一个终端界面。

A terminal file browser TUI: file tree, syntax-highlighted preview, built-in editor, in-directory shell commands, in-file + global (ripgrep) search.

✨ 与 AI Agent（Claude Code / Codex 等）结合使用

fileview 的设计初衷之一，就是给 Claude Code、Codex CLI、Cursor Agent 这类 AI 编码代理 当一个轻量随身的"文件副驾"：agent 在一个终端里跑、改代码，你在另一个终端里用 fileview 实时浏览、审阅、微调、验证它的产出。它不占用 agent 的会话上下文，纯本地、零网络。

典型场景：

| 场景 | 怎么用 | |------|--------| | 审阅 agent 改了哪些文件 | 用文件树快速翻看，预览面板带语法高亮，比 cat 更易读 | | 快速微调 agent 的产出 | 在文件上按 e 进内置编辑器改几行，Ctrl+S 保存——不用切到 vim/IDE | | 跨整个仓库找 agent 的改动痕迹 | 按 g 全局搜索（优先 ripgrep），定位某个函数名 / TODO / 新引入的标识符 | | 跑校验命令看 agent 是否做对 | 按 ! 直接在当前目录跑 npm test、git diff --stat、tsc --noEmit，输出就地展示 | | 命令跑完目录自动刷新 | agent 生成 / 删除文件后，执行任意命令即可看到文件树即时更新 | | 盯一个 agent 正在写的文件 | 打开预览，/ 文件内搜索关键行，n/N 跳转定位 |

推荐工作流（双终端 / 分屏）

┌───────────────────────────┬───────────────────────────┐
│  终端 A: claude / codex    │  终端 B: fileview .        │
│  （让 agent 改代码、跑任务） │  （你审阅 / 微调 / 验证）  │
└───────────────────────────┴───────────────────────────┘

1. 在项目根目录起 agent：claude（或 codex）。
2. 另开一个终端（或 tmux/iTerm 分屏）起 fileview .，指向同一目录。
3. agent 每完成一步，你在 fileview 里：
   • 文件树看新增/改动的文件 → 预览读内容；
   • 需要改的地方按 e 就地编辑、Ctrl+S 保存；
   • 按 ! 跑 git diff / 测试命令做验证；
   • 按 g 全局搜索确认改动覆盖到位。

提示：把 fileview 用 npm link 装成全局命令后，可在任何仓库里 fileview 一键打开， 作为 agent 工作时的常驻审阅窗口。命令为非交互捕获模式，适合跑 test/build/git 这类一次性命令；交互式程序（vim、top）请在 agent 终端或单独终端里跑。

功能

• 文件树 — 浏览、展开/折叠目录（懒加载）。
• 预览 — 可滚动、带语法高亮的只读查看器。
• 内置编辑器 — 就地编辑文件，合成光标，Ctrl+S 保存。
• Shell 命令 — 在工作目录执行命令、查看输出，结束后目录树自动刷新。
• 文件内搜索 — 在打开的文件中查找，n/N 跳转匹配。
• 全局搜索 — 跨目录树的内容搜索，优先使用系统 ripgrep（rg）， 未安装时自动回退到零依赖的 JS 搜索。

环境要求

• Node.js >= 22
• 可选：PATH 上的 ripgrep（rg）， 用于更快的全局搜索（没有则自动使用内置 JS 搜索）。

安装与运行

一键安装（发布到 npm 后）

# 全局安装，得到 fileview 命令
npm install -g @learn2pro/fileview
fileview <dir>

# 或免安装，直接用 npx 跑
npx @learn2pro/fileview <dir>

从源码运行（开发）

npm install            # 使用你 .npmrc 里配置的 registry
npm run dev -- <dir>   # 直接从源码运行（默认当前目录）

# 或构建后运行编译产物：
npm run build
node dist/cli.js <dir>

# 或把本地代码装成全局命令（不发布）
npm link
fileview <dir>

发布到 npm（维护者）

包名为 scoped 包 @learn2pro/fileview，package.json 已配置好 publishConfig （公共 registry + public 访问）与 prepublishOnly 自动构建，发布只需两步：

npm login --registry=https://registry.npmjs.org   # 交互式登录（含 2FA）
npm publish                                        # 自动 build 并发布到公共 npm

发布前可用 npm pack --dry-run 预览将打包的文件（应为 dist/ + README.md + package.json）。

快捷键

| 模式 | 按键 | 动作 | |------|------|------| | 文件树 (NAV) | ↑/↓ | 移动选择 | | | ←/→ | 折叠 / 展开（或跳到父目录） | | | Enter | 打开文件（或展开/折叠目录） | | | e | 编辑选中文件 | | | / | 在打开的文件内搜索 | | | g | 全局搜索 | | | ! 或 : | 执行 shell 命令 | | | Tab | 切到预览面板 | | | q | 退出 | | 预览 (PREVIEW) | ↑/↓、PgUp/PgDn | 滚动 | | | e / g ! | 编辑 / 查找 / 全局搜索 / 命令 | | | Tab / Esc | 返回文件树 | | 编辑器 (EDIT) | 输入、方向键 | 编辑与移动 | | | Ctrl+A / Ctrl+E | 行首 / 行尾 | | | Ctrl+S | 保存 | | | Esc | 退出（再按一次丢弃未保存修改） | | 文件内查找 (FIND) | 输入 + Enter | 搜索；之后 n/N 循环，Esc 清除 | | 全局搜索 (GSEARCH) | 输入 + Enter | 搜索；↑/↓ 选择，Enter 打开命中，Esc 返回 | | 命令 (COMMAND) | 输入 + Enter | 执行；↑/↓ 滚动输出，Esc 关闭 |

范围与已知限制（v1）

• 命令为非交互捕获模式：收集并展示输出；不支持 vim、top 等交互式程序。
• 编辑器暂无 undo/redo（缓冲是纯 reducer，后续易扩展）。
• 大文件/二进制文件在预览中只读打开；超过约 2 MB / 5 万行或检测为二进制时拒绝编辑。
• 编辑器处理码点与东亚字符宽度、并展开制表符显示；完整 grapheme（ZWJ/组合字符） 支持不在 v1 范围内。

架构

• src/cli.tsx — 入口；进入备用屏幕缓冲区并渲染应用。
• src/app.tsx — 根状态机（Mode 枚举通过 useInput({ isActive }) 门控路由按键）与布局。
• src/components/ — FileTree、Preview、Editor、CommandBar、 SearchPanel、StatusBar、SingleLineInput。
• src/hooks/ — useFileTree、useEditorBuffer（编辑器 reducer）、useTerminalSize。
• src/lib/ — 纯函数、无 React 依赖：fs、ripgrep、jsSearch、shell、 highlight、text、altScreen。

开发与验证

由于沙箱/CI 环境没有真实 TTY，scripts/smoke.tsx 提供了一个无头渲染测试工具： 给它喂入按键序列，渲染到内存流后抓取并打印帧，可在没有终端的情况下验证 UI 行为。

npx tsx scripts/smoke.tsx <dir> "down,down,right,enter"   # 模拟按键并打印渲染帧
npm run typecheck   # tsc --noEmit
npm run build       # 编译到 dist/