开始使用

准备工作

BaseHalf 运行在 macOS 上，需要搭载 Apple 芯片的 Mac。

Agent 不是必需的，画布本身就能用。要在 Agent Area 里运行 Agent，先装好你想用的，比如 Claude Code 或 Codex 的命令行工具。

下载

1. 打开 GitHub 上的最新版本。
2. 下载 Apple 芯片版的磁盘映像，文件名以 darwin-arm64.dmg 结尾。
3. 打开磁盘映像，把 BaseHalf 拖进“应用程序”文件夹。

首次启动

macOS 版没有签名，也没有经过公证，所以第一次打开时 macOS 可能会拒绝运行。把应用移到“应用程序”文件夹后，在终端里运行一次这行命令：

xattr -dr com.apple.quarantine /Applications/BaseHalf.app

macOS 会给下载的应用加上隔离标记，这行命令就是把它去掉。之后像启动其他应用一样启动 BaseHalf 即可。

打开文件夹

BaseHalf 直接使用你已有的文件夹：代码项目、研究资料、课程、一堆笔记都可以。打开一个，它就会显示为画布。

你会看到：

• 中间是画布。文件夹里的文件和子文件夹都是卡片。
• 左边是侧边栏，包括你的文件、Source Control 和 Search。
• 右边是 Agent Area，Agent 会话在这里运行。
• 顶部是标题栏，有显示和隐藏侧边栏、Agent Area 的按钮，还有你当前所看内容的路径。点击路径会打开搜索。

打开文件夹不会改动你的任何文件。BaseHalf 第一次显示某个文件夹的画布时，会创建一个隐藏的 .bh/ 文件夹，用来记住卡片放在哪里。这个文件夹自带忽略文件，所以 Git 不会跟踪卡片位置。BaseHalf 从不修改你自己的 .gitignore。

试着建立第一个连接

1. 双击画布空白处，选择 New Note。笔记出现在你双击的位置，可以直接输入。
2. 写一两行，按 Escape 或点击别处结束。
3. 把指针移到另一张卡片上，卡片每条边的中间会出现一个小手柄。从其中一个手柄拖到你的新笔记上。

你画的这条线就是一个连接：现在，另一张卡片的内容会流入你的笔记。BaseHalf 把它保存在笔记里，也就是文件开头的 upstream 列表中，任何打开这篇笔记的 Agent 都能读到。详见连接。

Agent

打开文件夹时，BaseHalf 会询问是否为你的 Agent 安装它的 skill，在你回答之前这个询问会一直在。如果你打算使用 Claude Code、Codex 或其他能加载 skill 的 Agent，就安装它。这个 skill 会加到你这台 Mac 上各个 Agent 自己的设置里，不会放进你的文件夹，之后由 BaseHalf 保持更新。详见与 Agent 协作。

更新

BaseHalf 会自动更新。有新版本时，它会在后台下载一次更新，在你退出时安装，最晚也会在你下次启动 BaseHalf 时装好。

你正在运行的版本和它的更新情况，可以在 Settings → BaseHalf → About 页面查看。点那里的 Release Notes 会打开这个版本的发布页。

下一步

• 画布与卡片：卡片的全部用法。
• 连接：上游是什么意思，保存在哪里。
• 与 Agent 协作：Agent Area、skill 和选中的内容。