一个基于 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.
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 改代码、跑任务） │ （你审阅 / 微调 / 验证） │
└───────────────────────────┴───────────────────────────┘
- 在项目根目录起 agent：
claude（或codex）。 - 另开一个终端（或 tmux/iTerm 分屏）起
fileview .，指向同一目录。 - 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 install # 使用你 .npmrc 里配置的 registry（如内网 bnpm）
npm run dev -- <dir> # 直接从源码运行（默认当前目录）
# 或构建后运行编译产物：
npm run build
node dist/cli.js <dir>
# 可选：把 fileview 装成本地命令（不发布到 npm）
npm link
fileview <dir>| 模式 | 按键 | 动作 |
|---|---|---|
| 文件树 (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 关闭 |
- 命令为非交互捕获模式：收集并展示输出；不支持
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/