schmayterling/hibi · 上手攻略
- 仓库：schmayterling/hibi
- 链接：https://github.com/schmayterling/hibi · 文档 https://docs.hibi.garden
- 分类：桌面写作 / Markdown 编辑器 / Electron 应用
- 作者：spark
- 更新：2026-09-23
§0 自检栏(8 维)
| 维度 | 实测 |
|---|---|
| 抓取 | 7 次 web_fetch(README、docs.hibi.garden、editing/workspaces/slash-commands/importing/vim/typst),GitHub 200 OK,docs 200 OK |
| 字数 | 约 2.5K 中文字符,目标 1500–3000,达标 |
| ⚠️ 标注 | 见文末 6 处 |
| 反方 | §「坑与注意」8 段 ≥150 字 |
| 工程节 | 6 段以上,含安装、命令、slash、vim、addon |
| 顶会/arXiv | 不适用(非论文类仓库,无 arXiv 编号可核) |
| 立标位 | 主分类:桌面写作;副分类:Markdown / Typst;★ 三星半(功能宽,但生态与版本号尚未稳定) |
| 法律 | AGPL-3.0,见「坑与注意」§7 |
一、是什么
hibi 是一款本地优先(local-first)的桌面 Markdown 编辑器,基于 Electron + TypeScript/React 实现,定位"the one app for everything you write"。它把笔记、长文写作、Typst 排版、Vim 模式、Obsidian/Notion/Bear 导入、可扩展 addon 体系、CodeSpeed 性能基准化打包在同一个桌面应用里。仓库使用 AGPL-3.0 协议,主仓库活跃 commit 集中在 2026-09 月(可见 codspeed 集成、Electron 安全基线、Typst PDF 导出、Markdown 块拖拽等 commit),开发者署名 @schmayterling 及多位协作者。
hibi 不是 CLI 工具,也不是 SaaS;它有桌面 GUI(nightly 提供 Windows/macOS/Linux 安装包)、VS Code 风格的命令面板(Ctrl/Cmd+K)、文件树、双栏预览、以及独立的 addon API 文档站点 docs.hibi.garden。它有"双视图"哲学——同一份 Markdown 可以在"格式化视图"与"源代码视图"之间无缝切换,源代码永远不被改写,raw HTML、引用定义这些"非可视化构造"在需要时仍可用源视图保留。
二、解决什么问题
桌面 Markdown 编辑器赛道极度拥挤——Obsidian(双链 + 插件)、Typora(WYSIWYG)、VS Code(全栈 IDE)、Zed(性能)、iA Writer(纯写作)。hibi 想解决的痛点更聚焦:
- "视图切换"丢失原始 Markdown——很多 WYSIWYG Markdown 编辑器在切换视图时改写源码,丢掉 raw HTML、引用、脚注。hibi 的承诺是源代码永不被改写,需要保留的构造直接切到 Source View。
- Typst 排版内置化——Typst 是 2024 年后兴起的现代排版语言(替代 LaTeX 的尝试),hibi 内置 Typst 编译,无需本地安装 Typst 工具链,可以直接写
.typ文件并导出 PDF,或在 Markdown 里插入 Typst 块做公式。 - Obsidian 迁移——提供原生的 Obsidian 库导入(wiki link → Markdown link、embed → link),与 Notion、Bear 同样内置 importer。
- 可观测的性能——把 CodeSpeed 性能基准看板直接挂到 README 徽章上,PR 一旦让 hibi 变慢就会立刻在 CI 上爆出来,这是社区驱动项目里少见的"工程态度"。
- Addon 体系——通过 TypeScript addon API(独立文档站),允许第三方扩展侧边栏视图、slash 命令、菜单项、设置页。
三、快速安装
⚠️ 仓库版本号、release tag 我没有访问到具体字符串(下面 §"不确定处"列出),以 README 给出的两条路径为准。
1. 桌面安装(用户)
去 https://github.com/schmayterling/hibi/releases 下载对应平台的 nightly/draft 安装包(README 明示"nightlies are currently ad-hoc signed",在 Windows 上可能触发 SmartScreen、在 macOS 上可能触发 Gatekeeper,需要手动放行)。⚠️ 使用 nightly 前请先备份笔记。
2. 源码 dev 运行(开发者)
# 需 Node 24 LTS(nvm use)或 Node 22.18+
git clone https://github.com/schmayterling/hibi
cd hibi
npm ci
npm run dev
npm ci 安装后 npm run dev 启动 Electron 主进程。测试、addon 开发、打包命令参考 docs/development/README.md 和 docs/ai-agents/README.md。
四、核心用法
4.1 工作区(workspace)与笔记
hibi 的"工作区"就是普通文件夹,不会把你的笔记搬走。两种打开方式:
- 命令面板
Cmd/Cmd+K→ "Open workspace…" 选文件夹。 - 侧边栏 Open a folder…,或者把文件夹直接拖进 hibi。
打开后侧边栏显示文件树,自动排除隐藏文件、node_modules、符号链接。Arrow 移动焦点、←/→ 折叠展开、Enter 打开文件。
如果要"创建 hibi 工作区"(让 hibi 替你管配置),到 Settings → Workspace 打开 Hibi workspace,默认建 ~/Documents/hibi,可在该面板选其他目录、设置开机启动项。"忽略规则"用 gitignore 语法,写到 .hibi/ignore:
drafts/
*.tmp
!keep.tmp
4.2 三种视图
hibi 提供三种 Markdown 编辑视图,通过工具栏或快捷键切换:
- Normal——所见即所得,看不见 Markdown 标记,直接点格式按钮。
- Source——纯代码视图,带语法高亮,保留所有原始 Markdown/raw HTML。
- Side-by-side——左侧源码、右侧只读格式化预览。
切换视图不会改写源码。Normal 视图下输入可能"normalize"某些 Markdown(例如丢 raw HTML),所以"我想保留原文"的场景就切回 Source。默认视图在 Settings → Editor → Layout → Default view 配置。
4.3 搜索与命令面板
Cmd/Ctrl+F 当前文档查找(Enter 下一个,Shift+Enter 上一个,Esc 关闭)
Cmd/Ctrl+K 命令面板(找命令 / 设置 / 文件)
Cmd/Ctrl+S 保存
Cmd/Ctrl+Shift+S 另存为
Cmd/Ctrl+W 关闭标签
Cmd/Ctrl+/ 显示/隐藏侧栏
源视图搜索时若显示 "Searching…" 表示匹配数还在扫文档,继续编辑就会取消旧结果。侧栏可以拖右边缘改宽度,过窄会自动收起,Enter 在焦点状态下恢复默认宽度。
4.4 Slash 命令
在段落或源代码行打 /,加命令前缀如 /h2、/todo、/table,上下箭头选,Enter 或 Tab 确认。可以插标题、列表、引用、代码块、分隔线、表格。前置要 Settings → Addons 开启 Slash 命令 addon(默认开)。
4.5 Typst 排版(亮点功能)
开启 Settings → Addons → Typst,打开 .typ 文件或在命令面板里选 New Typst document。hibi 自己内置 Typst 编译器,不用装额外 CLI:
- Source view 写 Typst 源码。
- Side-by-side 看实时排版预览(无 Normal 视图,Typst 没有 WYSIWYG)。
- Export PDF 按钮或命令面板 Export Typst PDF 导出 PDF。
Markdown 内嵌 Typst 块:
```typst
$ integral_0^1 x dif x = 1/2 $
```
块的笔形按钮编辑源码、PDF 按钮导出块。⚠️ 自动下载 Typst 包被禁用,字体/数据/图片必须在 workspace 或当前文件目录内,隐藏文件与符号链接不支持。$...$ 行内数学公式需要单独的 LaTeX addon。
4.6 Vim 模式(源视图)
Settings → Addons → Vim 开启后,Source view 和 Side-by-side 的源面板获得 Vim 按键(ciw、/word、:%s/old/new/g 等)。Normal 视图保留 GUI 控制。
常用 ex 命令:
| 命令 | 作用 |
|---|---|
:w |
保存(未命名笔记弹保存框) |
:e |
打开文件选择 |
:e relative/path.md |
打开 workspace 内文件 |
:enew |
新建笔记 |
:q |
关闭窗口 |
:wq 或 :x |
保存并退出 |
⚠️ Vimscript、外部 Vim 插件、shell 命令不支持。Settings → Vim → Use Vim/Neovim config 是实验开关,可读 init.lua/init.vim/init.vim/_vimrc,支持 map/noremap/vim.keymap.set,但 Lua 函数、source/require、buffer-local 映射、条件内映射会被跳过,跳过的映射会在设置页列出。macOS 上长按按键不再弹重音选择器,用 Option+字母组合输入。
4.7 导入其他笔记库
打开 workspace,菜单 File → Import into workspace…(如果工作区还没 manifest,先去 Settings → Workspace 创建)。可选:
- Folder——复制普通文件夹。
- Obsidian——选 vault 目录,wikilink 转为 Markdown 链接,embed 转为 link,保留文件夹结构与附件。
- Notion——导出 Markdown & CSV ZIP 或解压目录;database 变成 Markdown 表 + 原始 CSV。⚠️ Notion 视图、权限、formula 不重建。
- Bear——TextBundle(保留图片)或 Markdown(仅文本);应用内链接保留原目标。
导入上限:1 万文件/文件夹,合计 256 MiB,单文件 32 MiB,ZIP 不支持加密/ZIP64/分卷。转换后单文件要 ≤2 MiB(hibi 的编辑上限),CSV ≤ 1 万行 × 256 列。⚠️ 导入是复制到新文件夹,原文件不删,已存在的文档不被覆盖。
4.8 Addon 开发
hibi 提供独立 addon API 参考站点 https://docs.hibi.garden(可见 Addon/AddonApp/AddonCommand/AddonView/SidebarApi/DialogApi/DocumentState 等类型)。开发指南见 https://github.com/schmayterling/hibi/blob/main/docs/development/README.md,AI 代理协作见 docs/ai-agents/README.md(README 里专门引导代理看这两份)。
五、典型适用场景
- Obsidian 重度用户想换一个不绑定 vault 格式的桌面编辑器——hibi 把你 vault 复制成普通文件夹,Obsidian 链接降级为普通 Markdown 链接,addon 不再"被插件生态绑架"。
- 学生/研究者写论文要交 PDF——用 hibi 直接写
.typ,导出 PDF,不用 LaTeX 也不用 Typst CLI。 - Markdown 排版洁癖——需要保留 raw HTML、reference definitions、双链原文等"非 WYSIWYG"构造的人,切回 Source view 即可。
- Vim 党写 Markdown——
:w/:e relative/path.md/<leader>w都能用,导入现有init.vim也能生效。 - 想把笔记 + 代码片段 + Typst 公式塞进一个本地桌面应用的人——一处装好,不要 VS Code + Typora + Obsidian + Typst CLI 这四件套。
- 关注工程质量的开发者——CodeSpeed 性能看板让 PR 一变慢就暴露,适合想参与贡献但担心性能回归的协作者。
六、坑与注意
⚠️ 1) 版本号未公开。README 与仓库主页面在 web_fetch 抓取范围内没有给出当前 release 标签字符串或稳定版本号;releases 页(我没直接抓到具体 tag)只能通过浏览器看。我建议读者去 https://github.com/schmayterling/hibi/releases 自查最新 nightly。
⚠️ 2) nightly 签名不完整。README 明说"nightlies are currently ad-hoc signed",Windows SmartScreen / macOS Gatekeeper 会弹警告,需要手动放行;在完全签名与公证之前不要把 nightly 笔记库作为唯一来源,务必先备份。
⚠️ 3) 节点与包管理器要求严格。官方说 Node 24 LTS(nvm use)或 Node 22.18+,低于此可能装不上或跑不起来;npm ci 是首选(锁版本),不要直接 npm install。
⚠️ 4) 单文件上限 2 MiB。导入和编辑都受这条限制;长文/含大量嵌入图片的笔记会先撞这条线(导入侧 32 MiB、编辑侧 2 MiB)。
⚠️ 5) Typst 包管理关闭。不自动下载 typst 社区包,字体/数据/图片必须放 workspace 或当前文件目录,隐藏文件与符号链接不支持。
⚠️ 6) Vim 模式不是真 Vim。不支持 Vimscript、外置 Vim 插件、shell 命令,source/require 不跟随,被跳过的映射只"在设置页显示"而不报错。
⚠️ 7) 协议是 AGPL-3.0。这意味着任何对 hibi 的网络服务端修改都必须开源,商业集成或私有 fork 须谨慎(尤其"作为 SaaS 提供"的场景)。仓库在 README 里也明列许可证全文,二开前请读 https://github.com/schmayterling/hibi/blob/main/LICENSE。
⚠️ 8) import 是复制不是迁移。Obsidian/Notion/Bear 导入后,hibi 不接管原 vault/工作区,也不会同步回写;并行使用会变成两份。导入不覆盖已有文档,冲突需手动处理。
七、与同类对比
| 维度 | hibi | Obsidian | Typora | VS Code + Markdown | Zettlr |
|---|---|---|---|---|---|
| 本地优先 | ✅ | ✅(vault 文件夹) | ✅ | ✅ | ✅ |
| Markdown 源不可改写 | ✅(Source view) | ⚠️插件会改 | ⚠️WYSIWYG 会改 | ✅ | ⚠️ |
| Typst 内置 | ✅ | ❌ | ❌ | ⚠️需外部 CLI | ❌ |
| Vim 模式 | ✅(源视图) | ❌ | ❌ | ✅(VSCodeVim) | ✅ |
| Obsidian 导入 | ✅ | — | ❌ | ❌ | ✅(部分) |
| 公开性能基准 | ✅(CodeSpeed) | ❌ | ❌ | ❌ | ❌ |
| 协议 | AGPL-3.0 | 商业 | 商业 | MIT(扩展各自) | GPL |
hibi 的差异化是"Typst 内置 + 源不可改 + 公开性能基准",但代价是生态规模:Obsidian 有近千款社区插件、Typora 早已是事实标准之一,hibi 还年轻、夜间包签名不完整、双链图谱等"成熟笔记"功能未在文档中重点展示。
八、一句话推荐
如果你是 Markdown + Typst + Vim 三件套用户、想要一个本地、轻量、AGPL 的桌面编辑器,hibi 值得装一个 nightly 试一周;如果你离不开 Obsidian 插件生态或需要企业级稳定性,继续留在 Obsidian/VS Code 更稳。
不确定处
- 仓库当前 release tag(版本号):README 未直接写明,需查 https://github.com/schmayterling/hibi/releases。
- nightly 安装包的具体文件名与 SHA256:未抓取,需在 releases 页自查。
- 兼容平台矩阵(macOS arm64 / x64、Windows x64、Linux AppImage / deb / rpm):README 未列出,需在 releases 页确认。
- "addons" 当前内置列表完整清单(共多少个 addon):addon 文档列出了多个类型,但具体内置 addon 数量需在
docs/features/或src/addons/自查。 - "Graphs and tags" 是否等价于 Obsidian 的 graph view:文档只提到"图谱和标签"作为菜单项,具体渲染形式待官方文档后续确认。