Voicetree图视图实操指南:缩放、折叠与导航,一眼看懂你的Agent群
Voicetree图视图实操指南:缩放、折叠与导航,一眼看懂你的Agent群
Voicetree 是一款面向多 Agent 编排的空间 IDE,它的图视图(graph view)让你像操作 Obsidian 图谱一样,直接在工作图内管理节点、文件夹和 Agent 终端。这篇实操指南带你掌握 Voicetree 图视图的三大核心操作——缩放、折叠与导航,让你一眼看懂整个 Agent 群的任务结构与进度。
🗺️ 认识 Voicetree 图视图
Voicetree 的画布上只有两种基本元素:
- 节点(node):一个 markdown 文件、一个文件夹(一组节点),或一个终端形式的 coding Agent(Claude Code、Codex、Gemini 等)
- 边(edge):节点之间的 wikilink 连接
Agent 就"住"在它们的任务和进度节点旁边,你能直接看到谁在做什么、进展到哪。
🔍 缩放与平移:三种视角切换图视图
滚轮缩放,按住拖拽平移
Voicetree 为大图场景做了定制化的缩放/平移管线(参考 largegraphPerformance.ts),滚轮即可放大缩小画布,拖拽空白区域可平移视口。放大看单个 Agent 的细节,缩小看整个项目的拓扑结构。
一键适配:空格键与 Fit All
| 操作 | 效果 |
|---|---|
| 空格(Space) | 视图快速飞到最近创建/更新的节点,长按可持续跟随 |
| Fit All | 缩放画布,让所有节点一屏尽收眼底 |
| Ctrl / Cmd + 方向键 | 在编辑器与终端间切换焦点 |
"空格跟随"是最高频的操作:当某个 Agent 在图上新建节点汇报进度时,按一下空格就能瞬间回到它身边,非常适合盯守多 Agent 并发工作。缩放与跟随的实现位于 GraphNavigationService.ts。
📁 折叠与展开:用文件夹驯服 Agent 群
Agent 拆解任务时会构建自己的子图(subgraph),节点一多画布容易变乱。Voicetree 的文件夹机制正是为此设计:
- 点击折叠箭头(chevron):每个文件夹节点上都有一个箭头,点击即可在"展开/收起"之间切换。折叠后整个子图收成一个胶囊标签,展开则恢复为复合节点区域,逻辑见 FolderHandleService.ts
- 右键菜单:对文件夹右键可选择
Expand(展开)、Collapse(折叠)、Hide(隐藏),对多选节点还支持Extract Into Folder(抽取成文件夹),实现见 VerticalMenuService.ts - 文件树侧栏:左侧文件夹树与图视图联动,可快速定位深层节点(FolderTreeSidebar.tsx)
折叠/展开的实际行为由 folderCollapse.ts 控制。推荐工作流:平时保持 Agent 子图折叠,只展开你当前关心的那一个分支——先总览结构,再按需放大细节。
⚡ 导航快捷键:像游戏一样操作图视图
所有快捷键集中定义在 settingsSchema.ts,注册逻辑见 graphHotkeyBindings.ts。以下为默认按键(macOS 用 ⌘,Windows/Linux 用 Ctrl):
| 快捷键 | 功能 |
|---|---|
Space |
适配到最近节点(可长按跟随) |
⌘N |
新建节点 |
⌘Enter |
在选中节点上运行终端/Agent |
⌘F / ⌘E |
打开搜索面板 |
⌘1 ~ ⌘5 |
跳转到最近访问的节点 1~5 |
⌘[ / ⌘] |
切换到上一个/下一个终端 |
⌘Backspace |
删除选中节点 |
⌘W |
关闭选中节点的编辑器/终端 |
⌘, |
打开设置 |
搜索面板:按名字直达任意节点
⌘F 打开搜索面板,输入关键字即可在全部可见节点中按标题查找并跳转,搜索数据会随图变化增量更新(SearchService.ts)。配合 ⌘1~⌘5 最近节点标签栏,日常导航基本不需要鼠标。
💻 悬浮编辑与浮动终端:图内直接开工
- 悬停编辑:把鼠标停在节点上会弹出富 markdown 编辑器,双击或按
⌘N创建新节点,新节点会以呼吸动画提示你它的位置 - 运行 Agent:选中节点按
⌘Enter,该节点内容即成为 Agent 的任务提示词,Agent 还会自动收集周围可配置半径内的节点作为上下文——Agent 看到的和你看到的是同一张记忆图
当终端数量达到 4~10 个时,浮动终端可以各自锚定在对应节点旁,互不遮挡,这正是"空间化组织 Agent"的直观体现:
📚 延伸阅读与相关源码
| 资源 | 路径 |
|---|---|
| 项目总览与 API 说明 | readme.md |
| 图视图快捷键注册 | graphHotkeyBindings.ts |
| 导航与缩放服务 | GraphNavigationService.ts |
| 文件夹折叠逻辑 | folderCollapse.ts |
| 搜索面板服务 | SearchService.ts |
| 后端 Python 代码 | backend/ |
💡 上手建议:先学会「滚轮缩放 + 空格跟随 + 文件夹折叠」这三件套,再逐步掌握搜索与快捷键,一周内你就能在 Voicetree 图视图里从容驾驭整个 Agent 群。

