连接 | BaseHalf 文档

上游连接表示一个条目的上下文流入另一个条目。连接以纯文本保存在你的文件夹里，Agent 和其他工具也看得到。

连接是什么意思

连接 A → B 表示 A 的上下文流入 B。你或 Agent 处理 B 时，A 是 B 所依据的内容之一。A 是 B 的上游，B 是 A 的下游。

连接构成的是图，不是树。一篇笔记可以依据多个条目，一个条目可以流入多篇笔记，也允许出现环。条目不能是它自己的上游。

Markdown 链接是另一回事。笔记里的链接用于跳转，不会创建连接。

每张卡片有四个连接手柄，分别在每条边的中间，指针移到卡片上时出现。

从手柄拖到另一张卡片上。 你拖出的那张卡片成为你松开的那张卡片的上游，两者之间会画出一条线。
在画布空白处松开，可以新建一个建立在起始卡片之上的条目：一篇笔记，或者用来生成的图片、视频、声音草稿。新条目从一开始就把你的卡片列为上游。新笔记会打开供你输入。
单击连线可以选中，按 Delete 删除。拖动连线的一端：松开在另一张卡片上就改接过去，松开在画布空白处就删除这条连线，松开在其他地方则保持原样。
拖出一个不碰到任何卡片的选框，可以选中它穿过的所有连线，按 Delete 一次全部删除，算一步撤销。

从访谈卡片朝发布计划拖出一条线，画布旁边是终端。

这些操作都可以撤销。

同一文件夹里的卡片之间会画出连线。连到其他文件夹中条目的连接不画线，但会列在卡片的徽标里，并计入数量。

生成文件保留生成它的输入，草稿在生成过程中也保留自己的输入。试图改动时会被拒绝，并说明原因。

除草稿之外，每张卡片都有一个徽标，点它会把卡片翻到背面，显示：

指针移到卡片的徽标开关上会显示数量，例如“↑2 upstream · ↓1 downstream”。

一条连接只保存一次，存在下游条目里，就像源文件声明自己的 import 一样。

Markdown 笔记把列表存在 frontmatter 里，也就是文件开头的那段内容，放在 upstream 下：

---
upstream:
  - research/interviews.md
  - sources/survey-results.pdf
---

# Launch decision

条目是相对于工作区文件夹的路径。放不下列表的笔记（比如以水平分割线开头的笔记），它的列表由 BaseHalf 保存，方式见下。

文件夹、PDF、图片、视频或其他文件自身放不下列表，由 BaseHalf 保存在 .bh/mirror/<path>/upstream.yaml 里，其中 <path> 是这个条目在工作区中的路径。草稿在文件生成之前，也把它的输入存在那里。

反方向，也就是一个条目流入了哪些条目，不会保存在任何地方，由 BaseHalf 根据所有上游列表算出来。

因为列表就在笔记里，Agent 打开笔记就能看到它依据了什么，不需要任何设置。BaseHalf 第一次给没有 frontmatter 的笔记加上这段内容时，会提示你一次。

上游列表就是纯文本。你、Agent 或其他任何工具都可以编辑它，文件里存的是什么，BaseHalf 就用什么。

BaseHalf 自己只在两种情况下改动列表。一种是你在改：在画布上连接、断开或改接，在徽标或草稿面板里改动条目，新建带连接的条目，或者修复断裂的条目。另一种是条目被移动，不管是谁移动的：这时它会重写引用这个条目的那些行，不会询问。BaseHalf 没有常驻后台的程序。

如果一行列表指向的条目已经不存在，它会作为断裂的条目留在列表里。徽标会在原位用警告样式显示它，并提供修复方式：

命令面板中的 BaseHalf: Show Upstream Issues 会按文件列出工作区里的所有问题，并提供同样的操作。

删除一个条目不会改动其他条目的列表。引用它的那些行会变成断裂的条目，直到你修复它们，或者撤销这次删除。

不管是谁移动或重命名，条目都保留自己的卡片：你、Agent、访达或 Git 都一样，BaseHalf 关着的时候也一样。BaseHalf 根据内容在新路径认出这个条目，把它为这个条目保存的东西一起移过去，并更新所有引用它的行，不会询问。

重命名的卡片位置不变，移到另一个文件夹的卡片会排在那里最后一张卡片之后。如果文件同时被改写了一半以上，或者是空文件、没有文件的文件夹，BaseHalf 就认不出来，引用它们的行会显示为断裂。草稿没有文件，只能在 BaseHalf 里移动。