alchaincyf/fanbox

📦 FanBox

"AI 帮你一个下午起十个项目，然后它们就再也找不到了。FanBox 帮你把它们找回来。" "AI spins up ten projects in an afternoon. FanBox helps you find them again."

FanBox：Coding Agent 的驾驶舱。指挥 Claude Code、Codex 在本地干活，看清它碰过的每个文件、改过的每一行，随时接手。
FanBox — the cockpit for coding agents: command Claude Code or Codex, see every file and line they change, and take over anytime.

一边浏览、预览、编辑本地文件；一边在内嵌真实终端里跑 Claude Code 或任何 coding agent。
agent 每写一个文件，对应卡片就会亮起来——找回文件 → 运行 agent → 看清改了什么，全部在一个窗口完成。

Browse, preview and edit local files on one side; run Claude Code or any coding agent in a real embedded terminal on the other.
Every time the agent writes a file, its card lights up — find files → run agents → see what changed, all in one window.

⬇ 下载 dmg / Download dmg · Screenshots / 截图 · Features / 功能 · Install / 安装 · Credits / 致谢

_{▲ 真机截图：浏览 fanbox 仓库本身，README 原地预览，内嵌终端正在跑 git。本页所有截图均由 Playwright 从实时 App 中直接拍摄，未修图。
Real capture: browsing the fanbox repo itself, README previewed in place, git running in the embedded terminal. All screenshots in this README are taken from the live app via Playwright, unedited.}

Why FanBox · 为什么要做 FanBox

AI 帮你一个下午起十个项目，但它们散在各处、名字认不出、改了啥看不见。每天的真实流程是：Finder 里翻半天 → 切到 iTerm 启 agent → 再切浏览器看效果，三个窗口来回跳。

AI helps you start ten projects in an afternoon — then they scatter everywhere, the names stop making sense, and you can't see what got changed. The daily reality: dig through Finder → switch to iTerm to launch an agent → switch to the browser to check results. Three windows, endless hopping.

FanBox 把这条链路收进一个窗口：左边文件 × 右边/下边终端 × 原地预览，一个有机整体。它不跟 Finder 拼文件操作，不跟 VS Code 拼编辑，专注「找回 + 预览 + 轻改 + 指挥 agent」这一条链路做到顺手。

FanBox folds that loop into one window: files on the left × terminal on the right/bottom × preview in place. It doesn't compete with Finder on file ops or VS Code on editing. It does one chain well: find → preview → light edits → command the agent.

不做云、不做远程、不做账号。本地、零配置、运行时零依赖。

No cloud, no remote, no accounts. Local-first, zero config, zero runtime dependencies.

Three skins · 三套皮肤

界面在 huashu-design 辅助下完成设计，三套皮肤不是换个主题色——配色、字体、图标、代码高亮、终端 ANSI 主题整体随之变化。

The UI was designed with huashu-design. The three skins are not theme-color swaps — palette, typography, icons, code highlighting and terminal ANSI themes all change together:

	终端 · Volt · 荧光绿 × 炭黑 × 等宽字，工业仪器面板感（默认） Volt · neon green × charcoal × monospace, industrial instrument panel (default)
	档案 · Archive · 奶油纸 × 赤陶橙 × 衬线，温暖纸感档案馆 Archive · cream paper × terracotta × serif, a warm paper archive
	索引 · Index · 黑白 × 信号红/绿 × 巨号字，编辑式索引日报 Index · black & white × signal red/green × oversized type, editorial index daily

What it does · 能做什么

Files · find & preview / 文件 · 找回与预览

• ⌘K 全局模糊搜索 / Global fuzzy search — 记得名字片段就行；⌘↵ 用编辑器整包打开项目；内容:关键词 切全文搜索。
  A fragment of the name is enough; ⌘↵ opens the project in your editor; content:keyword switches to full-text search.
• 强色实体图标 / Bold solid icons — 每种文件「长得像它自己」：PDF 红、JS 黄、Markdown 蓝；照片视频按真实比例呈现。
  Every file type "looks like itself": red PDFs, yellow JS, blue Markdown; photos and videos render at true aspect ratio.
• 原地预览 / Preview in place — Markdown 渲染、HTML 实时成品、代码语法高亮、图片/视频/PDF 内嵌（HEIC 直接显示）、压缩包内容清单、透明图棋盘格垫底。
  Rendered Markdown, live HTML, syntax-highlighted code, inline images/video/PDF (HEIC included), archive content listing, checkerboard backing for transparent images.
• 缩略图加速 / Thumbnail speed — 大文件夹滚动和点击都在 0.1 秒内。
  Scrolling and clicking through large folders stays under 0.1s.
• 项目徽章 / Project badges — 文件夹卡片标 node / web / py / rs / go 徽章，一下午起的十个项目一眼认出类型。
  Folder cards show node / web / py / rs / go badges, so ten projects from one afternoon are recognizable at a glance.

Watch what the agent changed · 看 agent 改了什么

• 活的仪表盘 / A live dashboard — agent 每写一个文件，那张卡片当场荡开涟漪、按改动频率发光呼吸，agent 写到哪光走到哪。
  Every file the agent writes makes its card ripple and glow by change frequency; the light follows wherever the agent goes.
• 跟随模式 / Follow mode — 一键让文件视图 + 预览跟踪 agent 正在编辑的文件：代码随新写行高亮闪烁，HTML 边写边实时渲染（双缓冲、零白闪），Markdown 实时渲染。任何手动浏览立即把控制权交还给你。
  One click and the file view + preview track whatever file the agent edits: code scrolls with freshly written lines flashing, HTML renders as a live web page while it's being written (double-buffered, zero white flash), Markdown renders live. Any manual browsing hands control back to you instantly.
• 会话回放 / Session replay — 像刷视频一样拖时间轴，重现这段时间 agent 一步步改了哪些文件。
  Drag the timeline like scrubbing a video to replay which files the agent touched, step by step.
• 变更收件箱 / Change inbox — 跨多个项目汇总本会话所有被改动的文件，多项目并行跑 agent 不再各看各的。
  All files modified this session, aggregated across projects, for parallel agent runs.
• Git 改动 diff / Git diff — Monaco 只读 DiffEditor 并排展示 HEAD vs 当前工作区，看清 agent 到底改了哪几行。
  Monaco read-only DiffEditor, HEAD vs working tree side by side.

Agent cockpit · Agent 驾驶舱

• 项目记忆 / Project memory — 点开任何项目文件夹，看 AI 在这里干过什么：历史会话（你的第一句话当标题）、每次会话改过的文件、触发过的 skill；「▶ 续上」一键在内嵌终端 claude --resume / codex resume 接上当时的上下文。
  Open any project folder and see what AI did there: past sessions (your first message as the title), the files each session changed, the skills it triggered — and a "resume" button that reconnects the context via claude --resume / codex resume in the embedded terminal.
• 截图直通车 / Screenshot express — 系统截屏落盘即浮出直通卡：喂给终端里的 agent、收进项目 素材/、或先标注再发。
  Take a system screenshot and a card pops up in the corner: feed it to the terminal agent, file it into the project's 素材/ (assets) folder, or annotate before sending.
• AI 整理 / AI organize — AI 只看元数据出整理提案（不读内容、不碰文件系统），每条建议带理由、逐条勾选过人，FanBox 执行并写回滚日志、一键整体撤销。引擎可选（Claude Code / Codex），策略提示词随便改。
  AI proposes a cleanup plan from metadata only (it never reads content or touches the filesystem); you approve each move; FanBox executes with a rollback log and one-click undo. Engine selectable (Claude Code / Codex), strategy prompt fully editable.
• 发版向导 / Release wizard — node 项目一键串起版本号、CHANGELOG、打包、推送、GitHub Release，整条命令序列在内嵌终端可见地跑。
  For node projects: version bump, CHANGELOG promotion, build, push and GitHub Release composed into one command sequence that runs visibly in the embedded terminal.
• Skills 透视 / Skills X-ray — 本机全部 agent skills 一个视图：触发统计、健康检查、context 预算、不删文件的启停开关。
  Every agent skill on your machine in one view: trigger statistics, health checks (description truncation, missing frontmatter), context budget, enable/disable without deleting.
• Agent 用量 / Agent usage — Claude Code 官方 5h 窗口/周配额（和 /usage 同源）+ 本地 token 统计；Codex 限额快照 + 窗口重置识别。
  Claude Code official 5h window / weekly quota (same source as /usage) plus local token statistics; Codex window snapshots with reset detection.
• 磁盘占用透视 / Disk usage lens — du 口径的真实占用条形榜，可下钻，专治「电脑空间又满了」。
  du-accurate bars per folder, drill-down, for the "my disk is full again" moments.

Terminal · command the agent / 终端 · 指挥 agent

• 真实内嵌终端 / A real embedded terminal — node-pty + xterm.js（WebGL 渲染），跑 Claude Code / vim / htop 不花屏，中文宽字符正确。
  node-pty + xterm.js (WebGL). Claude Code / vim / htop render correctly, CJK wide characters included.
• 拖文件进终端 / Drag files in — 从文件列表拖文件/文件夹进终端，自动插入路径喂给 agent 当上下文。
  Drop a file or folder into the terminal to insert its path as agent context.
• 路径可点击 / Clickable paths — 终端里出现的文件路径直接点击在 FanBox 打开；带空格的 macOS 截屏名、中文文件名、折行的长路径都能识别（空格边界由文件系统 stat 验证，不靠猜）。
  File paths appearing in terminal output open in FanBox on click; macOS screenshot names with spaces, Chinese filenames and wrapped long paths are all recognized (space boundaries verified by stat, not guessed).
• 选中即甩给终端 / Send selection — 预览里选一段文字，一键以「文件出处 + 围栏」格式发进终端（bracketed paste 包裹，不会被逐行误执行）。
  Select text in a preview and fling it into the terminal with file provenance + fencing (bracketed paste, never executed line by line).
• 态势感知 / Situational awareness — 标签圆点显示 agent 运行/空闲/退出；agent 把球踢回给你时终端边缘呼吸提示「轮到你」，长任务完成发系统通知。
  Tab dots show running/idle/exited; when the agent hands the ball back, the terminal edge breathes; long tasks fire a system notification.
• 11 个 agent 一键启动 / 11 built-in agent launchers — Claude Code、Codex、Hermes Agent、OpenClaw、Kimi Code、ZCode、opencode、pi、CodeBuddy、WorkBuddy、Qoder CLI，官方图标 + 核实过的启动命令。滑杆按钮打开设置面板勾选启用哪些（默认 Claude Code + Codex），未装的一键复制安装命令；~/.fanbox/config.json 的 agents 数组可自定义命令或追加新 agent。
  All with official icons and verified launch commands. A sliders button opens the picker (defaults: Claude Code + Codex); not-installed entries copy their install command in one click; the agents array in ~/.fanbox/config.json overrides commands or adds new agents.

Editing · WYSIWYG / 编辑 · 所见即所得

• Markdown — Milkdown Crepe 提供 Notion 式所见即所得，打开就是编辑态，停笔 0.8 秒自动保存。顶部 富文本 / 阅读 / 源码 / 排版 四档随时切；少数文件富文本往返会丢内容（校验不过），只灰掉富文本、默认落在只读阅读模式，文章照看，要改点源码。
  Milkdown Crepe, Notion-style WYSIWYG; opens in edit mode, auto-saves 0.8s after you stop typing. A Rich / Read / Source / Typeset switch sits on top; when a file can't survive a WYSIWYG round-trip, only Rich is disabled — it falls back to the rendered read-only view, not raw source.
• 排版档 · 一键进公众号 / Typeset — one click into WeChat — 20 套排版主题（来自 editor.huasheng.ai），选好样式点「复制到公众号」，粘进公众号后台即成稿：样式全内联、图片自动转 base64（本地图和图床外链都行）、连续多图排成表格网格、带底色主题自动补背景层。排版档里看到的就是粘出去的，不存在预览与成稿不一致。工具栏顺带给出「x 字 · 约 y 分钟」。
  20 typeset themes (from editor.huasheng.ai). Pick one, hit Copy for WeChat, paste into the WeChat editor — styles fully inlined, images inlined as base64 (local files and remote hosts alike), consecutive images laid out as a table grid, tinted themes get a background wrapper. What you see in Typeset is exactly what gets pasted; word count and reading time sit in the toolbar.
• 送去… / Send to… — 其余去向收在一个菜单里：「复制到 X」按 X Articles 的标签白名单清洗；飞书文档、X Articles·渡口、B站专栏·渡口则把一条明文指令递给终端里的 agent 去跑（需装 lark-doc / dukou skill）。FanBox 自己不存任何平台凭证、不内建任何第三方 SDK，指令只粘不回车——你看得见、能改、能拒，最后那一下永远由人来点。
  Other destinations live in one menu: Copy for X sanitizes to the X Articles whitelist; Feishu docs and Dukou (X Articles / Bilibili) hand a plain-text instruction to the agent running in your terminal instead. FanBox stores no platform credentials and bundles no third-party SDK; the instruction is pasted without a newline — visible, editable, refusable. You press the final key, always.
• 代码/JSON / Code/JSON — Monaco 编辑器（VS Code 同款内核），随皮肤切换主题。
  Monaco (the VS Code core), themed per skin.
• 图片标注 / Image annotation — 画笔/箭头/文字/打码、格式转换、压缩、调分辨率，覆盖原图前有确认。
  Pen/arrow/text/redaction, format conversion, compression, resizing; overwriting the original asks first.
• 未保存守卫 / Unsaved guard — 三种编辑器统一拦截未保存退出，Esc 旁路也堵死。
  All three editors intercept unsaved exits, including the Esc bypass.

Install · 安装

桌面版（推荐）/ Desktop (recommended)

从 Releases 下载最新 .dmg，拖进「应用程序」即可。Apple Silicon (arm64) 原生。

Download the latest .dmg from Releases and drag it into Applications. Native Apple Silicon (arm64).

已用 Developer ID 证书签名 + hardened runtime，并通过 Apple 公证（notarization），双击直接打开，不用右键。
Signed with a Developer ID certificate + hardened runtime and notarized by Apple — just double-click to open, no right-click workaround needed.

应用内置更新提醒：检测到 GitHub 上有新 Release 时，右下角会弹一条提示引导下载，不强更、可对单个版本「不再提醒」。
Built-in update notifications: when a new release lands on GitHub, a capsule appears at the bottom right. Never forced; individual versions can be muted.

Windows（社区移植，非官方）/ Windows (community ports, unofficial)

我自己没有 Windows 电脑，没法稳定验证 Windows 版的体验，也不了解 Windows 用户的操作习惯，所以官方不出 Windows 版。但社区里有同学基于 FanBox 拓展了 Windows 版本，想在 Windows 上体验的朋友可以试试，谢谢他们的工作 🙏。

⚠️ 这些都不是我的改造，我没有参与开发、也没法对它们的体验和安全负责。请自行评估后使用。

I don't own a Windows machine and can't reliably verify a Windows build or judge what Windows users need, so there is no official Windows version. The community has built Windows ports of FanBox — if you're on Windows, give one a try, and thanks to the maintainers 🙏.

⚠️ These are not my builds. I'm not involved in their development and can't vouch for their experience or security. Use at your own discretion.

网页版（不打包，直接跑）/ Web (no packaging)

node server.js

浏览器打开 http://localhost:4567。零依赖、零 build，clone 下来就能跑。网页版只有文件浏览/搜索/预览（内嵌终端和编辑器靠 Electron 提供）。

Open http://localhost:4567. Zero dependencies, zero build — clone and run. The web version covers browsing/search/preview (the embedded terminal and editors need Electron).

开发模式 / Development

npm install
npm run app          # electron . 启动完整桌面版 / full desktop app
npm run dist         # 打包签名 .dmg（产物在 dist/，不入 git）/ build & sign the .dmg (output in dist/)

打包遇到 Electron 下载被墙：ELECTRON_MIRROR="https://registry.npmmirror.com/-/binary/electron/" npm run dist

Shortcuts · 快捷键

Privacy & security · 隐私与安全

• 后端只在本机回环地址监听 + 校验 Host 头（挡 DNS rebinding），数据不出本机。
  The backend listens on loopback only and validates the Host header (anti DNS-rebinding). Data never leaves your machine.
• 全部前端资源（含渲染器、字体）本地内置，离线完全可用。仅有的出网请求：Claude 用量接口（可选）和 GitHub 更新检查。
  All frontend assets (including renderers and fonts) are vendored locally — fully usable offline. The only outbound calls: the Claude usage API (optional) and the GitHub release check.
• HTML 预览在隔离 origin 的沙箱 iframe 里渲染，预览不可信网页也碰不到终端能力。
  HTML previews render in a sandboxed iframe with an opaque origin; an untrusted page can never reach terminal capabilities.
• 配置写入走串行化读-改-写 + 原子写（temp + fsync + rename），不丢数据、不留半截 JSON。
  Config writes are serialized read-modify-write with atomic persistence (temp + fsync + rename) — no data loss, no truncated JSON.
• 删除走系统废纸篓（可恢复）；缩略图缓存按最旧优先自动裁剪，上限 400MB。
  Deletions go to the system Trash (recoverable); the thumbnail cache prunes oldest-first with a 400MB cap.

Design & acceptance · 设计与验收

界面设计在 huashu-design 辅助下完成——三套皮肤的方向探索、组件质感、反 AI slop 审查都出自它的工作流。图标是档案暖色陶土箱体 + 米纸 squircle，从 SVG 一路生成到 icns。

The UI was designed with huashu-design — skin direction exploration, component polish and anti-AI-slop review all come from its workflow. The icon is a terracotta archive box on a rice-paper squircle, generated from SVG all the way to icns.

每个开发阶段由 5 个独立 subagent 扮演不同角色（重度 vibe coder / 原生审美设计师 / 零文档新用户 / 终端十年老兵 / 破坏性质量官），审「成品 + 真机截图 + 代码」打分，全部 ≥90 分且无红线才算达标。评分标准见 docs/05-验收角色与评分标准.md。

Each development phase is reviewed by 5 independent subagents playing different roles (heavy vibe coder / native-taste designer / zero-docs newcomer / ten-year terminal veteran / destructive QA), scoring the product + live screenshots + code. Everything ships at ≥90 with zero red lines. See docs/05-验收角色与评分标准.md.

Standing on the shoulders of giants · 建在巨人肩膀上

FanBox 的核心能力来自这些出色的开源项目：

FanBox's core capabilities come from these excellent open-source projects:

所有前端依赖都 vendor 到本地（public/vendor/），这是「离线完全可用」的底气，也意味着上面每个项目的代码真实地跑在你机器上。谢谢它们。

Every frontend dependency is vendored locally (public/vendor/) — that's what makes "fully usable offline" true, and it means each project above actually runs on your machine. Thank you.

Architecture · 技术架构

fanbox/
├── server.js               # 零依赖 Node 后端（文件 API + 缩略图 + 静态服务）
│                           # Zero-dependency Node backend (file APIs + thumbnails + static)
├── electron/
│   ├── main.js             # 主进程（窗口/pty/剪贴板/fs.watch/菜单）
│   │                       # Main process (window/pty/clipboard/fs.watch/menu)
│   └── preload.js          # 暴露 fanboxPty / fanboxFs / fanboxClipboard
│                           # Exposes fanboxPty / fanboxFs / fanboxClipboard
├── public/
│   ├── index.html
│   ├── style.css
│   ├── app.js              # 前端单页应用 / Frontend single-page app
│   └── vendor/             # xterm / monaco / milkdown 本地资源
│                           # xterm / monaco / milkdown local assets
├── src-vendor/             # esbuild 入口，产出 public/vendor/milkdown
│                           # esbuild entries producing public/vendor/milkdown
├── build/                  # 图标 + entitlements / Icons + entitlements
├── docs/                   # 概念/PRD/路线图/验收标准
│                           # Concepts/PRD/roadmap/acceptance criteria
└── experiments/            # 实验脚本（含 README 截图脚本）
                            # Experiment scripts (incl. README screenshot script)

Author · 关于作者

花叔 Huashu——AI Native Coder，独立开发者。代表作：小猫补光灯（App Store 付费榜 Top1）。

Huashu (花叔) — AI Native Coder, indie developer. Known for Cat Light (App Store paid chart Top 1).

更多 AI 造物：

More AI creations:

• 女娲.skill（蒸馏任何人的思维方式 / distill anyone's way of thinking）
• huashu-design（一句话拿回一份能交付的设计 / a deliverable design from one sentence）