# 使用说明

BranchNest 在 DeepSeek Harness 的项目画布上阅读对话、记录笔记，并从回答的某一段创建新的分支对话。以下内容对应当前版本，按界面顺序排列。

![项目画布与新增项目面板](assets/canvas.png)

## 画布与布局

- 每个 DSH 项目对应一张画布，进入时自动收起 DSH 侧栏，离开时恢复。左上角按钮展开项目面板：切换项目、查看对话数、**新增项目**（选择一个本地目录）。
- 从 DSH 对话进入 **分支探索** 时，自动打开该对话所属项目并定位对应卡片。手动切换画布项目后，自动同步不会改变你的选择。
- 项目内未归档的对话自动成为卡片；布局、视角、来源关系和上下文链接都会持久化。画布轮询同步：项目成员 2.5 秒，正在回答的对话 0.7 秒，空闲对话 3 秒。
- 拖动标题栏移动卡片，右下角调整大小，标题栏按钮收起/展开。拖动空白处平移画布，滚轮或触控板缩放（Ctrl/⌘ 滚轮在卡片内也能缩放），范围 20%–200%；底部提供缩放、百分比、**整理**和**适应**。
- **整理**按来源关系重新排布：有父子关系的按层级排列，没有关系的排成网格，完成后自动适应视图。**适应**把全部卡片放进视野。
- 尚在生成中的回答不会作为分支来源，等它完成后再操作。

## Ask or note

把指针移到卡片附近，卡片下沿浮出 **＋ Ask or note**（靠近时的形变动效在系统"减少动态效果"下停用）。

- **输入框为空**：显示三个快捷选项 **Explain / ELI5 / Go deeper**，也可按 `1` / `2` / `3`。点击即以对应预设问题发起分支。
- **输入了文字**：选项变成 **Note**（`Enter`）和 **Ask**（`⌘/Ctrl + Enter`）。
  - **Note**：在当前卡片旁生成一张笔记卡片，并连到来源。
  - **Ask**：创建一个独立的 DSH session 作为分支卡片，带入选中的选区（或上一段回答）、来源问答以及相关祖先内容。
- 抽屉会显示本次会携带的上下文（卡片数、来源路径、经几跳），可以逐张排除；被排除项和未包含原因也会列出。`Esc` 或点击外部收起抽屉。
- 提交先记录意图再创建，中途失败可"重试同一次提交"，不会重复创建。

## 选区追问

- 在已完成回答中选中文字，选区下方直接浮出同一个 Ask or note 面板，选区保持高亮；也可以从卡片标题栏的 Ask 入口打开，此时默认引用最后一段完成的回答。
- 分支的来源记录包含 session、消息序号、选中文字和内容 hash；来源变化时会要求重新选择。
- 分支内的模型工具 `read_canvas_context` 只能读取本分支的祖先链或本次 Ask 链接进来的卡片，并停在创建分支时记录的消息位置，会拒绝兄弟和无关对话。

## 阅读页与分支导航

![对话阅读页](assets/reader.png)

卡片标题栏的 **⛶** 打开阅读页（`Esc` 返回画布）：

- 顶部面包屑显示 `Canvas › 父对话 › 当前对话`，可逐级跳转；标题旁显示创建时的预设。
- 正文按页读取（单段选区引用上限 6000 字），顶部 **加载更早的对话**；`A−` / `A+` 在 15–23px 间调整字号；生成中可 **停止生成**。
- 右侧 **Branches** 列出直接子分支及其预设和运行状态，点击即切换阅读。顶部固定的侧栏按钮负责展开和收起，切换带轻微动画；系统开启减少动画时立即切换。
- 底部输入框可继续追问（生成新分支）或记录笔记；没有任何完成的回答时，输入框先等待回答完成。草稿按对话保留。
- 顶部 **在 DSH 中打开** 按钮直接打开当前阅读的原生对话，在 DSH 中继续交流。

## 上下文链接 ⇢

- 卡片标题栏常驻 **⇢** 把手：拖到另一张卡片上，就把它加入本卡上下文。目标卡片有选区时保存选区级链接；按住 `Shift` 落卡则强制整卡。
- 链接是**单向**的：A → B 表示从 A 的 Ask 会带上 B 的内容，反向不成立。
- 装配沿链接**递归**（传递闭包）：A → B → C 时，从 A 发起的 Ask 同时携带 B 和 C；环只收一次，同一卡片经多条路径到达时只收一次并记录最短路径。
- 链接以带箭头的曲线绘制，悬停可删除。

## 原生输入器（＋ 新建）

![新建对话的原生输入器](assets/composer.png)

顶栏 **＋ 新建** 打开 DSH 原生输入器，因此附件、命令和模型策略都由 DSH 本身提供：

- **附件**：添加图片和文件；未发送草稿（含附件）按项目保留，重新打开可继续。单个提问或笔记最长 12000 字。
- **/ 命令**：斜杠命令与已安装技能（由 DSH 输入器提供，具体项取决于当前安装）。
- **@ 引用**：引用项目内文件；对话中出现的文件引用会渲染成可点击的链接，点击后在 DSH 侧栏打开该文件的预览。
- **模式**：选择标准 / PTC / 极简 / 创作者模式等 agent 预设（下拉，仅在发送前可切换）。
- **模型与权限**：沿用 DSH 输入器自带的模型选择与权限设置，插件不另行拦截。

草稿空白处点击不会关闭对话框；用关闭按钮或 `Esc` 退出。只有发送被接受后，新对话才会作为卡片出现在画布上。

项目中的会话需要你回答问题时，画布会显示 DSH 原生问答框，阅读页打开时也可以直接作答。未打开过的后台分支同样会提示；多个会话同时等待回答时，可在问答框顶部切换会话，已选答案会保留。提交后原生任务继续执行。

## 笔记与归档

- 笔记使用 Markdown；双击正文原位编辑，点击外部自动保存，`Esc` 放弃本轮修改，`⌘/Ctrl + Enter` 结束并保存。**⛶** 全屏阅读，`Esc` 退出。
- 卡片标题栏的归档图标会先弹出确认框，说明"卡片移出画布、聊天记录保留、正在进行的任务停止"；确认后才归档原生 session。取消不做任何改变。在 DSH 的已归档对话中取消归档后，卡片及其位置与来源关系会恢复。

## 数据边界

- 聊天历史仍是 DSH 原生 session 日志，插件不复制会话。插件只在 DSH `storageDomain` 的 `project_canvas` 域保存两张表：画布（布局、视角、来源锚点、上下文链接、笔记）和未完成的提问意图。
- 同一画布上的不同卡片不会自动共享聊天历史；共享只通过来源关系、选区锚点和 ⇢ 链接发生。
- 文件与工具权限遵循 DSH 的项目设置与 agent 权限，插件不做额外的文件系统隔离。
- 草稿：笔记编辑、Ask or note 输入框和阅读页草稿都留在当前界面状态，不会写进会话日志。

## 当前限制

- 尚无 PDF / 资料节点与回合卡片。
- 不支持跨项目分支，一个项目一张画布。
- 没有导出（画布、对话、笔记均无导出）。
- 正在生成中的回答不能作为分支来源，需等完成。
- 卡片只订阅视野附近最多 8 个对话，远处的卡片聚焦后才开始读取。