iamrohithrnair/obsidian-tui

# obsidian-tui **最好的 Obsidian TUI。** 你的知识库，还是你熟悉的样子：三 面板布局、实时预览 Markdown、双向链接、力导向图和 18 款主题。只不过它运行在你的终端里，再也不需要你碰鼠标。 将它指向你现有的知识库即可。不需要导入步骤，没有数据库，也没有 锁定：它读取的是和 Obsidian 相同的普通 Markdown 文件文件夹，并且 你可以让 Obsidian 一直开着这个文件夹。关闭这个程序，你的 笔记就会恢复为原先的文件状态。 它还配备了一个 AI 助手，能通过与你完全相同的命令来处理你的笔记，这样你可以亲眼看到它做了什么，而不只是听信它的总结。  ## 安装 使用单行命令是最简单的方式。它会自动判断适合你机器的构建版本， 下载它，并在执行任何操作之前根据公布的校验和对其进行验证： ``` curl -fsSL https://obsidian-tui.github.io/install.sh | sh ``` 支持 macOS 和 Linux。设置 `OTUI_BIN_DIR` 来选择安装位置，或者使用 `OTUI_VERSION` 来指定某个版本。将脚本直接传递给 shell 执行始终建议先检查一下； [在这里查看完整脚本](https://github.com/iamrohithrnair/obsidian-tui/blob/main/install.sh)， 它只有大约 150 行，非常易读。 或者使用你已经信任的任何包管理器。 **Homebrew** (macOS 和 Linux)： ``` brew install iamrohithrnair/tap/obsidian-tui ``` **npm**，如果你想在正式安装前先试用一下： ``` npx obsidian-tui ~/Notes # run it once, install nothing npm install -g obsidian-tui # keep it ``` **Cargo** (需要 Rust 1.88 或更高版本)： ``` cargo install --git https://github.com/iamrohithrnair/obsidian-tui obsidian-tui ``` **手动下载。** 从 [最新发布版本](https://github.com/iamrohithrnair/obsidian-tui/releases/latest) 中获取一个压缩包： ``` tar -xzf obsidian-tui-.tar.gz shasum -a 256 -c obsidian-tui-.tar.gz.sha256 # optional but cheap sudo mv obsidian-tui-/obsidian-tui /usr/local/bin/ xattr -d com.apple.quarantine /usr/local/bin/obsidian-tui # macOS only ``` 为 `aarch64-apple-darwin` (Apple silicon)、 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `x86_64-pc-windows-msvc` 提供了预编译版本。Intel Mac 需使用 cargo 从源码构建。 **通过克隆仓库构建：** ``` git clone https://github.com/iamrohithrnair/obsidian-tui cd obsidian-tui cargo install --path crates/otui --locked # installs to ~/.cargo/bin cargo build --release # or just build it ``` ## 运行 ``` obsidian-tui ~/Notes # a specific vault obsidian-tui # the vault Obsidian last had open obsidian-tui --list-vaults # what Obsidian knows about ``` obsidian-tui 接受常规的命令行 flags 以及桌面应用注册的 `obsidian://` URI，因此打开 Obsidian 的链接或脚本同样也可以打开它： ``` obsidian-tui ~/Notes --note "Project Ideas" obsidian-tui ~/Notes --search "quarterly" obsidian-tui ~/Notes --daily obsidian-tui ~/Notes --graph obsidian-tui 'obsidian://open?vault=Notes&file=Ideas' ``` ### 与 Obsidian 自带的 CLI 并存 Obsidian 附带了一个[官方 CLI](https://obsidian.md/cli)，可以在 设置 → 通用 → “Command line interface” 中启用。两者负责不同的工作： | | `obsidian` | `obsidian-tui` | |---|---|---| | 本质是 | 应用的遥控器 | 界面本身 | | 交流对象 | 正在运行的桌面应用 | 知识库的文件 | | 需要 Obsidian 实例 | 是的，如果没有运行还会启动一个 | 否 | | 在没有显示器的机器上 | 需要 `--ozone-platform=headless` 或 Xvfb | 直接运行即可 | 因此它们是互补的，而不是竞争关系。当 `obsidian` 二进制文件位于你的 `PATH` 中时，obsidian-tui 会将它用于只有桌面应用能做的那一件事： 即将笔记交给 GUI： - 助手面板中的 `/obsidian` 会报告 CLI 的状态以及应用已知的知识库。 - `/obsidian open`，或者命令面板中的“Open this note in Obsidian”， 会在桌面应用中打开当前笔记。 如果未启用 CLI，或者 Obsidian 没有运行，obsidian-tui 会提示并 继续运行；其他任何功能都不依赖于它。 ## 快捷键 在 Obsidian 有的地方使用它的快捷键，在没有的地方则遵循其他 TUI 的惯例。在应用中按 `?` 可查看完整列表。 | | | |---|---| | `?` | 键盘快捷键 | | `q` | 退出（会先询问；编辑时也可以使用 `Ctrl+Q`） | | `Ctrl+O` | 快速切换 | | `Ctrl+P` | 命令面板 | | `Ctrl+Shift+F` | 搜索所有笔记 | | `Ctrl+E` | 切换 阅读 / 编辑 | | `Ctrl+N` / `Ctrl+D` | 新建笔记 / 今日日记 | | `Ctrl+G` / `Ctrl+Shift+G` | 全局图 / 本地图 | | `Ctrl+L` | 助手面板 | | `Ctrl+\` / `Ctrl+]` | 切换侧边栏 | | `Tab` | 在面板间移动 | | `hjkl`, `g`, `G` | 在面板内移动 | | `Enter` | 打开 / 跟随链接 | 在文件浏览器中：`/` 按名称过滤，`s` 更改排序方式，`Space` 折叠文件夹，而 `H`/`L` 一次性折叠或展开所有文件夹。 在图形视图中：`hjkl` 平移，`+`/`-` 缩放，`f` 将整个图适配到屏幕上， `Tab`/`Shift+Tab` 在节点间切换，`c` 重新以选中项为中心，`L` 切换标签显示，`u` 显示未解析的链接，`t` 显示标签，`r` 重建布局。 `q` 永远不会在你可能正在输入的地方退出：在编辑器、聊天框 或搜索字段中它会输入一个 `q`，而 `Ctrl+Q` 才是退出的方式。 上下文相关的提示栏位于状态栏上方，显示适用于当前所处位置的按键； `Ctrl+P` → “Toggle shortcut hints” 可以将其关闭。 ## 鼠标 侧边栏图标是按钮，并且大部分 UI 都可以点击： | | | |---|---| | 侧边栏图标 | 文件、搜索、图形视图、助手、命令面板 | | 浏览器中的笔记 | 打开它 | | 浏览器中的文件夹 | 折叠它 | | 标签页 | 切换到该标签页 | | 大纲 / 双向链接 / 标签 | 切换面板 | | 图形节点 | 选中它 | | 滚轮 | 滚动指针下方的面板，而不是聚焦的面板 | ## 功能 **笔记。** 支持 Obsidian 语法的实时预览 Markdown：`[[wikilinks]]` （未解析时会变暗）、`#tags`、`- [ ]` 任务、`> [!note]` 标注、表格以及带有语法高亮的代码块。Frontmatter 是 可选的：从任何地方放入的 Markdown 文件都会直接显示。 **浏览器。** 文件树打开时，你最近编辑的笔记会位于 顶部，这通常就是你上次中断的地方。`s` 会切换到其他的排序方式： 修改时间、创建时间和文件名，每种都可以双向排序。文件夹始终保持 字母顺序，并且你的选择会被写入配置文件，因此下次启动时它依然保持原样。 **链接。** 一个包含每个链接所在行的双向链接面板，一个大纲 面板，以及一个标签浏览器。跟随链接打开不存在的笔记时会自动创建它，就像 Obsidian 一样。重命名笔记会重写每一个指向它的 wikilink。 **图形视图。** 一个带有 Barnes-Hut 排斥力的力导向图，因此它在大型知识库中依然保持 流畅，并且在稳定下来后不再消耗 CPU。那些只是被 *链接到*的笔记会显示为空心节点，这通常是屏幕上最实用的信息， 因为它们正是你打算写的笔记。`Ctrl+Shift+G` 会显示 当前打开笔记的邻近结构。 **主题。** 包含 Obsidian 自带的浅色和深色主题，以及 Catppuccin、Tokyo Night、 Gruvbox、Nord、Solarized、Dracula、Rosé Pine、Everforest，还有一个 继承你终端配色的 `terminal` 主题。在主题目录中放入一个 TOML 文件 即可添加你自己的主题；未设置的颜色会继承自它 `extends` 的主题。 **助手。** 一个通过你使用的相同命令 对知识库进行操作的聊天面板。它可以搜索、读取、创建、编辑、重命名、链接和删除 笔记，并可以在你的屏幕上打开它们或图形视图。每一次工具调用都会显示在 记录中，因此你可以看到它做了什么，而不必轻信一个总结。 ## 助手 设置一个 key 并重启： ``` export ANTHROPIC_API_KEY=sk-ant-... ``` 或者完全离线运行，使用本地模型： ``` [agent] provider = "openai" # any OpenAI-compatible server base_url = "http://localhost:11434/v1" # Ollama, LM Studio, vLLM, OpenRouter… model = "llama3.1" ``` 如果未配置 key，面板仍然会打开并解释如何设置； 应用中的其他任何功能都不依赖于它。 脚本化使用，无需 TUI： ``` obsidian-tui ~/Notes --prompt "which notes mention the Q3 migration?" ``` 在 `[agent]` 下设置 `allow_writes = false` 可以仅授予其搜索和读取权限。 ### 斜杠命令 在聊天框中输入 `/` 获取补全列表；`Tab` 补全，`Enter` 运行。 命令在本地处理，永远不会发送给模型：例如 `/model` 会直接更改 模型，而不是要求当前的模型去更改。 | | | |---|---| | `/help` | 列出命令 | | `/new`, `/compact` | 重新开始，或修剪旧对话轮次以释放上下文 | | `/save`, `/resume`, `/sessions` | 保存对话以便稍后继续 | | `/provider`, `/model`, `/base-url` | 将 agent 指向不同的后端 | | `/login`, `/logout`, `/status` | 凭据以及下一轮将要执行的操作 | | `/writes`, `/context`, `/reasoning` | 切换 agent 可以执行和查看的操作 | | `/tools`, `/vault`, `/obsidian` | 可用功能：工具、索引、Obsidian CLI | | `/sort` | 更改浏览器的笔记排序方式（`/sort list` 可查看列表） | | `/config` | 将当前设置写入配置文件 | | `/keys`, `/quit` | 快捷键参考，以及退出 | 会话以 JSON 格式存储在配置文件旁边，而不是在知识库中，因此 知识库依然是一个纯粹的 Markdown 文件夹。 ## 隐私 **除非你使用助手，否则 obsidian-tui 不会建立任何网络连接。** 没有遥测、没有分析，也没有更新检查。只有 `otui-agent` crate 包含 HTTP 依赖；知识库、编辑器和图形视图均无法访问 网络。 当你发送消息时，离开你机器的数据是： - 你输入的消息， - 如果你开启了 `include_active_note`（默认开启），还包括你当前打开的笔记， - 以及助手在回答时通过其工具读取的任何笔记。 这些数据会发送到你配置的提供商，并遵循该提供商自己的 条款。除此之外不会传输任何其他内容，也不会在后台发送任何内容。 为了保持一切本地化，你可以将其指向在你自己机器上运行的模型： ``` [agent] provider = "openai" base_url = "http://localhost:11434/v1" model = "llama3.1" ``` 或者通过设置 `provider = "offline"` 完全关闭助手。为了在使用助手的同时将 知识库排除在消息之外，请设置 `include_active_note = false`； 要阻止其自行读取笔记，请设置 `allow_writes = false`。这样保留的权限是 搜索和读取，但这仍然会读取笔记内容，因此如果这对你很关键，请使用本地模型。 你的 API key 会从环境变量（`ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`）中读取，并且永远不会被写入配置文件，永远不会被记录， 也永远不会包含在任何错误消息中。 ## 配置 首次运行时写入，并详细列出每一个默认值： - macOS: `~/Library/Application Support/obsidian-tui/config.toml` - Linux: `~/.config/obsidian-tui/config.toml` - Windows: `%APPDATA%\obsidian-tui\config.toml` 自定义主题放在其旁边的 `themes/` 目录中。 ## 架构布局 ``` crates/ otui-core vault discovery, indexing, markdown, search, graph engine otui-theme the theme model and presets otui-agent provider connectors, streaming, and the tool-calling loop otui the terminal application ``` `otui-core` 和 `otui-agent` 不依赖于终端，并且 `otui-agent` 不依赖于知识库：工具由 应用程序提供，这正是让助手和用户对完全 相同的状态进行操作的原因。 ## 开发 ``` cargo test --workspace # 473 tests cargo clippy --workspace --all-targets cargo fmt --all --check ``` 发布版本通过打标签（tagging）来切出。推送一个 `v*` 标签会构建所有目标平台，发布 带有校验和的 GitHub 发布版本，更新 tap 中的 Homebrew formula，并 发布到 npm。`CHANGELOG.md` 会成为发布说明，因此请先更新它。 两个仓库 secret 控制着最后两个步骤；如果没有它们，发布仍然会 成功，那些作业只会报告它们已被跳过。 | Secret | 用于 | |---|---| | `NPM_TOKEN` | 发布到 npm（一个自动化 token） | | `TAP_GITHUB_TOKEN` | 将 formula 推送到 `iamrohithrnair/homebrew-tap` | 打包相关的文件位于 `packaging/` 中。Homebrew formula 由 `packaging/homebrew/update-formula.sh` 生成，该脚本可以手动针对 一个包含 `.sha256` 文件的目录运行。 ``` # 提升 Cargo.toml 中的版本，更新 CHANGELOG.md，然后： git tag -a v0.2.0 -m "v0.2.0" git push origin v0.2.0 ``` ## 许可证 Copyright (C) 6 Rohith Nair. obsidian-tui 是自由软件：你可以根据自由软件基金会发布的 GNU 通用公共许可证条款重新分发或修改它，无论是 许可证的第 3 版，还是（由你选择的）任何更高 版本。参见 [LICENSE](LICENSE)。 分发此软件是希望它能有用，但不含任何保证； 甚至不包含对适销性或特定用途的 隐含保证。 简而言之：你可以将其用于任何事情，包括在工作场合。如果你分发了一个 修改过的版本，其源代码必须在相同的条款下保持可用，因此 无论你做了什么改进，其他人也都可以继续对其进行改进。

标签：Markdown, Obsidian, Rust, TUI, 可视化界面, 笔记软件, 终端应用, 网络流量审计, 通知系统, 防御加固