枝签 BranchMark 彩色标志

枝签 · BranchMark

摘一段，生一枝。

为开发者提供重点知识摘录、可追溯 Session 树和注意力分叉，让主 Session 始终专注于当前目标，让每条支线都能找回来源，让 Vibe Coding 告别注意力丢失。

English · 交互演示 · 为什么需要 · Session 树 · 快速开始 · 发布要求

npm latest npm alpha 0.1.2-alpha.5 DeepSeek Harness 0.1.2-rc.1 Node.js 22.19 or 24+ MIT License

## 交互演示 从一段值得保留的回答开始，把知识整理成枝签，再沿不同思路继续探索。下面两段演示来自实际运行的 DSH Web Profile，采用 2560×1440 工作区与 80% 缩放的大屏视角。每张动图独占一行，点击即可查看 1600×900 原图。 ### 摘录重点，让好想法随时可用 用备注和标签整理知识，按需要选择、排序或引用，让下一次提问从已有洞见开始。

BranchMark 在完整宽屏页面中整理知识枝签，展示自然高度卡片、多选操作和拖动排序

### 从一个想法，长出一棵会话树 完整分叉、仅携带枝签、空白分支分别承载不同的上下文；展开全景，就能看清各条思路如何关联，点击节点即可继续对话。

BranchMark 在全景会话树中展示三种分支模式、多层关系和真实会话导航

> [!IMPORTANT] > BranchMark `0.1.2-rc.2` 面向 DSH `0.1.2-rc.1`。插件版本与 DSH 兼容目标分别维护；安装时使用下方经过验证的精确组合。旧的 `0.1.1-rc.2` 组合与 `0.1.2-alpha.5` 组合继续使用精确版本，不能交叉安装。 BranchMark 是一个不修改 DSH 源码的插件 Bundle。它把会话消息中的关键片段保存为“枝签”，再以枝签所在消息为注意力分叉点，创建继承原上下文的子 Session，或只携带重点知识的独立 Session。枝签原文与来源锚点保持不可变，备注和标签可以编辑。 ## 目录 - [交互演示](#交互演示) - [BranchMark 解决的是开发者的注意力丢失](#branchmark-解决的是开发者的注意力丢失) - [核心工作流：摘录、分叉、回到主线](#核心工作流摘录分叉回到主线) - [Session 树与会话管理](#session-树与会话管理) - [快速开始](#快速开始) - [操作速查](#操作速查) - [数据与权限](#数据与权限) - [DSH 插件发布与生态要求](#dsh-插件发布与生态要求) - [文档](#文档) - [开发与贡献](#开发与贡献) ## BranchMark 解决的是开发者的注意力丢失 长时间开发不是一次连续的问答。你会在实现主任务时遇到值得保存的结论、需要验证的假设和可以并行推进的支线。如果所有追问都留在一个 Session，主线会逐渐被旁支淹没；如果直接创建空白 Session，新会话又不知道问题从何而来；如果只复制文字，知识与产生它的决策过程会断开。 | 开发中的时刻 | 常见处理方式 | 容易丢失的东西 | | --- | --- | --- | | 一段回答很重要，但当前还要继续主任务 | 先记在脑中，稍后再找 | 重点知识和来源位置 | | 一个想法值得深入验证 | 继续在主 Session 追问 | 当前任务的注意力主线 | | 直接打开新 Session | 重新解释一遍背景 | 父会话上下文和分叉原因 | | 同时推进多个方向 | 创建多个无关联会话 | Session 之间的父子关系和回到主线的路径 | BranchMark 将“知识锚点”和“会话分叉”绑定在一起：枝签保存值得复用的内容，Session 关系保存注意力从哪里分开。开发者可以沿主线继续工作，把支线交给新的 Session，并通过关系树或来源入口随时回到原位置。 ## 核心工作流：摘录、分叉、回到主线 BranchMark 的核心对象不是额外的聊天窗口，而是从重点知识生长出来的可追溯 Session。 ```text 主 Session：继续当前开发目标 │ ├── 选择关键文字 → 保存枝签 → 添加备注与标签 │ │ │ ├── 引用到当前 Composer：留在主线 │ ├── 完整分叉：带父会话历史进入子 Session │ └── 仅携带枝签：用重点知识开启独立 Session │ └── 主 Session 不需要承载每一次发散探索 ``` ### 1. 摘录重点知识 在一条已完成的用户或助手消息中选择文字，然后保存到本会话或当前项目。会话枝签默认只属于来源 Session；项目枝签可以跨 Session 搜索和复用，但只有显式选择“摘录到项目”才会进入项目枝签库。当前 Session 不会看到其他 Session 的私有枝签。 枝签正文和来源消息不可编辑，确保以后引用的仍是当时真正得到的结论。备注和多标签可以编辑，用来记录“为什么重要”“下一步要验证什么”以及它属于哪个技术主题。 ### 2. 从知识点分叉注意力 创建新 Session 时，先决定新任务需要多少父会话背景： | 分叉方式 | 新 Session 获得什么 | 注意力策略 | | --- | --- | --- | | 完整分叉 | 主要枝签的来源 Session 从开头到来源消息完整轮次的历史，以及全部所选枝签和备注 | 带着原推理过程继续深入 | | 仅携带枝签 | 一个没有 DSH parent 的全新 Session，以及全部所选枝签和备注 | 只带重点知识，隔离父会话噪声 | | 空白分支 | 不继承历史、不携带枝签和备注的全新 Session | 保留组织关系，独立探索新想法 | 多枚枝签来自不同 Session 时，你需要选择一个主要来源。主要来源只决定完整分叉继承哪条父会话链；其余枝签仍作为完整知识材料进入新 Session。 ### 3. 推进支线，再回到来源 “创建并打开”会立即进入新 Session，并保持 Composer 空白；“创建并发送”会先收集问题，再在后台创建和运行新 Session。衍生 Session 显示来源入口和分叉信息，枝签卡片也会列出使用它的衍生 Session。 新 Session 创建后拥有独立生命周期。回收或永久删除枝签不会删除、重写或中止已经创建的衍生 Session。 ### 快问快答 Side Chat 是注意力管理中的临时出口，不是 BranchMark 的主数据结构。它适合围绕一枚或多枚枝签快速提问，不向来源 Session 写入消息，也不进入 Session 树；关闭标签或退出 Host 后立即销毁。值得保留的结果可以再保存为枝签或转成正式 Session。 ## Session 树与会话管理 BranchMark 的会话树同时展示完整分叉、仅携带枝签和空白分支。根会话在上，子分支向下延伸；窄面板使用缩进布局，全景视图展示完整枝干。点击节点打开真实会话，“继续分支”默认创建空白分支。 | 关系 | 权威数据 | 界面含义 | | --- | --- | --- | | DSH 历史继承 | `SessionHeader.parentSession` / Client `parentId` | 完整分叉的原生父子关系 | | BranchMark 组织关系 | `DerivedSessionRelation.parentSessionId` 与 `mode` | 三种分支在同一棵树中的位置；线型说明携带方式 | | 枝签使用关系 | 附件标识与不可变 `ClipUsage` 快照 | 从枝签找到使用它的会话 | | Side Chat | 无持久关系 | 临时快问快答标签 | 仅枝签和空白分支拥有组织父会话，但没有 DSH 原生 parent，也不继承父历史。关系读取会补齐原生列表省略的未提问会话；刷新和 Host 重启后仍可找到并打开这些节点。不可读取的会话显示为不可用。旧记录缺少组织父标识时，不根据当前枝签猜测父会话。 ## 快速开始 BranchMark 通过 npm Bundle 安装到 DSH Web Profile。保存枝签、查看关系树和“创建并打开”不需要模型；向正式 Session 发送问题或使用 Side Chat 时，仍需要在 DSH 中配置可用模型。 ### 要求 | npm 通道 | BranchMark | DeepSeek Harness | 用途 | | --- | --- | --- | --- | | 当前源码 / `latest` | `0.1.2-rc.2` | `0.1.2-rc.1` | 会话树与枝签交互更新 | | `alpha` | `0.1.2-alpha.5` | `0.1.2-alpha.5` | 已发布的 alpha 兼容线 | | 旧版固定组合 | `0.1.1-rc.2` | `0.1.1-rc.2` | `release/dsh-0.1.1-rc` 维护线 | 所有组合都要求 Node.js `^22.19.0` 或 `>=24.0.0`，并且只支持 DSH Web Profile。`dsh --version` 必须符合对应 BranchMark 版本的兼容目标。 先用 `npm view @deepseek-ai/dsh dist-tags` 与 `npm view dsh-branchmark dist-tags` 核对通道；安装使用上表中的精确版本。从未发布源码构建时，使用下方 tarball 安装流程。 ### 1. 选择并安装兼容组合 安装当前兼容组合： ```sh npm install --global @deepseek-ai/dsh@0.1.2-rc.1 dsh plugin --profile web add dsh-branchmark@0.1.2-rc.2 ``` 使用已发布的 `alpha` 组合： ```sh npm install --global @deepseek-ai/dsh@0.1.2-alpha.5 dsh plugin --profile web add dsh-branchmark@0.1.2-alpha.5 ``` 如果需要与日常 Profile 隔离，可以在安装前创建专用 DSH home： ```sh export BRANCHMARK_DSH_HOME="$(mktemp -d)" DSH_HOME="$BRANCHMARK_DSH_HOME" \ dsh plugin --profile web add dsh-branchmark@0.1.2-alpha.5 ``` 采用隔离 home 时，后续每条 `dsh` 命令也必须带上 `DSH_HOME="$BRANCHMARK_DSH_HOME"`；否则命令会读取默认 Profile。 ### 2. 验证 Profile ```sh dsh --version dsh --profile web --dump-config ``` `dsh --version` 必须符合上表中的 DeepSeek Harness 版本；配置输出中应出现 `dsh-branchmark` 和 `branchmark-host`。版本不符或缺少条目时，按兼容表重新安装正确的组合。 ### 3. 从目标项目启动 DSH DSH 默认把启动命令所在目录作为 Workspace，因此先进入你真正要处理的项目： ```sh cd /absolute/path/to/your/project dsh web ``` 打开一个 Session，等待一条用户或助手消息完成，然后选择其中的文字。看到四项选区操作和右侧枝签浮签，即表示插件已经加载。 ### 从源码构建当前 alpha ```sh git clone https://github.com/zaizaizhao/dsh-branchmark.git cd dsh-branchmark corepack enable pnpm install --frozen-lockfile pnpm run release:check pnpm run pack:bundle dsh plugin --profile web add ./dist/dsh-branchmark-0.1.2-rc.2.tgz ``` 不要通过 Git URL、GitHub source specifier 或 `plugin add .` 安装。源码仓库不提交构建后的 `lib/`；npm 包和本地构建的 tarball 才是完整安装介质。 ## 操作速查 所有入口都要求用户显式选择或发送。BranchMark 不会因为选中文字就自动向模型发起请求。 | 你的注意力需求 | 使用的操作 | 结果 | | --- | --- | --- | | 记住当前任务中的关键结论 | 摘录到会话 | 枝签持久化，只在来源 Session 显示 | | 把重点知识提供给其他 Session | 摘录到项目 | 枝签持久化，在当前 Workspace 的项目库显示 | | 保留当前主线，继续组织问题 | 引用到输入框 | 插入可移除的原生引用 Chip，绝不自动发送 | | 沿原讨论位置展开正式支线 | 完整分叉 | 创建有 DSH parent 的持久化子 Session | | 用重点知识开始隔离任务 | 仅携带枝签 | 新上下文只包含选中的摘录与备注，保留组织关联 | | 从新想法开始讨论 | 空白分支 | 不携带历史、摘录或备注，保留组织关联 | | 管理并行开发支线 | 关系视图与枝签卡片 | 查看 Session 树、来源和双向使用关系 | | 临时确认一个小问题 | Ask in side | 创建不入树、不持久化的快问快答标签 | 右侧枝签浮签默认位于中线上方，避开 DSH 居中的轮次导航。按住浮签可沿右侧边缘上下拖动，松手不会误打开面板；位置在本浏览器中保存，窗口缩放后仍限制在可见范围内。单击展开，键盘聚焦后可用 ↑/↓ 微调、Home/End 移至上下边缘。 右侧 Dock 提供“本会话”“项目”“关系”和“Side Chat”视图。卡片随正文和备注自然排布，提供紧凑的创建新会话、引用与 Side Chat 按钮；备注、标签、置顶和删除位于“更多操作”。选中至少两枚枝签才显示批量工具栏。回收站是搜索框右侧的独立按钮，支持恢复；删除与排序完成后可撤销。 会话树把主节点放在上方，分支逐层向下展开；窄面板使用纵向层级，全景视图使用树枝连线。点击节点直接打开对应 DSH 会话，“继续分支”默认创建空白分支。完整分叉、仅携带枝签和空白分支分别使用实线、虚线和点线，组织关联不会修改 DSH 原生侧边栏的继承关系。 ## 数据与权限 BranchMark 把长期知识与关系留在 DSH 本地，把临时探索限制在当前 Host 进程中。 - 枝签、备注、标签、排序、回收站、使用快照和衍生关系写入 DSH 本地 `storageDomain` 的 `clip_explorer` domain；插件不提供云同步，也不向作者控制的服务上传数据。 - 完整分叉、仅枝签和空白分支 Session 都使用 DSH 原生持久化；BranchMark 不复制或替代 DSH Session 日志。 - 保存、搜索、组织枝签和查看关系不调用模型。只有用户发送问题后，所选枝签、启用的备注和恢复出的上下文才会进入当前 DSH provider 的请求。 - Side Chat 的项目文件工具只读，但工具结果可能进入模型请求；Web 搜索和抓取遵循当前 DSH 部署的 provider 配置。 - Workspace 和 Session 是当前的数据隔离键；Worktree 不是独立隔离边界。BranchMark 只支持 DSH Web Profile，也不会改变 DSH 原生侧边栏的会话层级。 完整配置、网络行为和限制见 [Bundle 使用参考](packages/bundle/README.md) 与 [兼容性和限制](course/reference/compatibility-and-limitations.md)。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要在公开 issue、日志或截图中提交凭据。 ## DSH 插件发布与生态要求 BranchMark 按目标版本 DSH 的官方 Bundle 机制分发。DSH 的[插件打包与安装文档](https://github.com/deepseek-ai/deepseek-harness/blob/db6bdc3576c2d4e7c965e8e3ed0c2a731eed87f5/docs/user/develop/basic/publish.md)定义 Profile Bundle，[Client module 文档](https://github.com/deepseek-ai/deepseek-harness/blob/db6bdc3576c2d4e7c965e8e3ed0c2a731eed87f5/packages/client/modules/README.md)定义 Web 浏览器入口。 在 BranchMark 支持的 DSH 版本中，官方资料没有提供第三方插件市场提交接口，官方仓库也暂不接受外部代码 PR。DSH 的[贡献说明](https://github.com/deepseek-ai/deepseek-harness/blob/db6bdc3576c2d4e7c965e8e3ed0c2a731eed87f5/CONTRIBUTING.md)建议作者在自己的仓库维护插件，并添加 GitHub [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic 供生态发现。社区目录可以作为额外分发渠道，但不代表 DSH 官方审核、兼容性保证或安全认证。
查看可安装条件与 BranchMark 发布准备状态 ### 可安装 Bundle 的技术条件 | DSH 条件 | BranchMark 的实现 | | --- | --- | | 包必须有非空 `name` 和 `version`，并提供可解析的运行入口 | `dsh-branchmark@0.1.2-rc.2` 交付预编译 Host、Typert、Remote 和浏览器入口 | | `package.json` 必须声明 `dsh.bundle.patch`，否则 `dsh plugin add` 只安装普通依赖，不激活 Profile 层 | `packages/bundle/package.json` 指向 `./cordis.patch.yml` | | `cordis.patch.yml` 必须插入或覆盖实际 Loader 行，并使用安装后可解析的包名 | Bundle patch 插入 `branchmark-host`，模块名为 `dsh-branchmark` | | Web 插件必须导出 `./client`，并以 `dsh.client.platform: "web"` 声明浏览器入口 | Bundle 导出自包含 `lib/client.js`，并声明所需 Client 注入项 | | npm 包或 tarball 必须包含编译产物；Git 源码安装若需要构建，必须提供自包含 `prepare`，并由用户在 pnpm 中显式授权 | BranchMark 不执行安装期脚本，只支持包含 `lib/` 的本地 tarball；当前禁止 Git 源码直装 | | 安装后应通过 `--dump-config` 验证 Bundle 层，再重启目标 Profile | README 和发布流程都在隔离 `DSH_HOME` 中检查 `dsh-branchmark` 与 `branchmark-host` | BranchMark 当前的发布准备状态： | 项目 | 状态 | | --- | --- | | 独立公开仓库、MIT License、Issues 与安全报告入口 | 已具备 | | `dsh.bundle.patch`、`cordis.patch.yml`、Web `./client` 与 `dsh.client` 声明 | 已具备 | | Node `22.19` / `24` CI、keyless 测试、Bundle 自包含检查和 npm dry-run | 已具备 | | 独立 Profile tarball 安装与 `--dump-config` 验证 | 已具备 | | npm `latest` 与 `alpha` 的精确兼容组合 | 已完成 | | GitHub `dsh-plugin` topic | 已完成 |
正式发布步骤、文件清单、npm 校验和真实 Profile smoke test 见 [RELEASING.md](RELEASING.md)。 ## 文档 README 负责解释注意力问题、Session 管理、安装路径和发布状态。完整产品规则、实现原理和复现课程分别由下面的文档维护。 | 你想了解 | 文档 | | --- | --- | | 从基础到复现整个插件 | [课程入口](course/README.md) | | 产品规则与验收范围 | [PRD](docs/PRD.md) | | Host、Client、存储、Session 分叉与关系架构 | [架构说明](docs/ARCHITECTURE.md) | | DSH Session lineage 与 BranchMark 使用关系 | [架构地图](course/reference/architecture-map.md) | | DSH Client 为什么采用当前扩展设计 | [DSH Client 架构取舍](course/reference/dsh-client-architecture-rationale.md) | | 配置字段、数据规则和限制 | [Bundle 使用参考](packages/bundle/README.md) | | 发布与真实 Profile 验收 | [发布流程](RELEASING.md) | ## 开发与贡献 提交代码前运行： ```sh pnpm run check pnpm run release:check ``` `check` 覆盖类型检查、keyless 测试、构建和 Bundle 自包含检查；`release:check` 继续检查文档、公开包元数据、publint 和 npm dry-run。真实 provider 请求不进入 keyless 检查，发布候选仍需按 [RELEASING.md](RELEASING.md) 在独立 Web Profile 中完成 smoke test。 参与开发请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。普通缺陷和功能建议提交到 [GitHub Issues](https://github.com/zaizaizhao/dsh-branchmark/issues)；版本变化记录在 [CHANGELOG.md](CHANGELOG.md)。BranchMark 使用 [MIT License](LICENSE)。