分叉溯源 WindFromKadath/dsh-plugin-branch-origin

dsh-plugin-branch-origin · 分支联系（DSH 插件）

给分叉出来的会话标上来源，让「我是从哪个对话分出来的」这件事在侧栏上直接可见。

两条通道，互为补充：

| 通道 | 形态 | 改名后 |
| 宿主半边（标题） | 子会话标题变成 ⤷ 来源：<源会话标题> | 丢失 —— 标签是标题字符串的一部分 |
| 客户端半边（侧栏徽标） | 行首一个 ⤷（悬停显示源标题） | 仍在 —— 它从会话的父级字段读，不碰标题 |

零依赖、无构建链。宿主半边是 lib/index.js + cordis.patch.yml 一行；客户端半边是手写的 lib/client.js（只用官方基座的 react / react/jsx-runtime）。

为什么需要它

DSH 的 fork 已经建立了真实父子链，也已经有一点可见性，但没有任何一处写出「来自哪个对话」：

| 官方已有的 | 缺的那一格 |
| SessionHeader.parentSession（真实父子链） | 侧栏不显示它指向谁 |
| 官方 fork 把子标题改成 <源标题> (1)（increasedForkTitle） | 只是个编号，看不出这是别人的分叉 |
| 侧栏按 SessionListEntry.depth 做谱系缩进 | 缩进不说明来源对话叫什么 |

本插件补的就是右上那一格，并且补两遍：把子会话标题改写成 ⤷ 来源：<源标题>（来源在标题里自述），再在侧栏行上加一个不依赖标题的来源徽标（改名也抹不掉）。

行为

规则只有一条，其余都是它的推论。

| 情形 | 结果 |
| 任何入口产生的新 fork（侧栏「分叉会话」、消息菜单、别的插件的 fork、ctx.sessions.fork） | 标题变成 ⤷ 来源：<源标题> |
| 官方随后把它改成 <源标题> (1) | 收敛成 ⤷ 来源：<源标题> (1)，序号保留，同源多个分叉仍可分 |
| 子会话标题已被用户或别的谱系插件改过（如 ⑂1 …、我的实验） | 不动（只标注，不接管） |
| 子标题已经是 ⤷ 来源：… | 幂等，不重复写 |
| 没有父级的普通新会话 | 不动 |
| 子智能体会话（header.origin === 'subagent'） | 不动（默认；可用 labelSubagents 打开） |
| 源会话当时没有标题 | 不动 |

判定细节：只有当子标题抹掉官方尾编号后与源标题同名时才算「仍是继承形态」，这时才贴标记。见 docs/DESIGN.md。

侧栏徽标（客户端半边）

只读，不接管官方行：

| 情形 | 结果 |
| 行的父级字段非空、且不是子智能体会话 | 行首出现 ⤷，鼠标悬停该行时有「来源」段显示源对话标题 |
| 你把这条会话改名了 | 徽标照旧显示（它不依赖标题），而标题里的 ⤷ 来源：… 会随改名消失 |
| 源对话被改名 | 徽标跟着显示新名字（实时读列表）；标题里的那份是 fork 时的快照，不会变 |
| 源对话不在当前列表快照里 | 显示 （未命名对话），不崩 |
| 普通会话 / 子智能体会话 / 子代理分支 | 不显示徽标 |

安装与启用

已装进 desktop profile（2026-10-07），形态与 trial 上已验证的 dsh-plugin-branch 一致：

| 落点 | 内容 |
| <profile>/package.json → dependencies | "dsh-plugin-branch-origin": "link:<本仓库>"（插件页的「已安装」列表读这里） |
| 同上 → dsh.profile.bundles | 追加包名（页面上的启用开关；组合时据此应用本 bundle 的 patch） |
| <profile>/node_modules/dsh-plugin-branch-origin | 指向本仓库的目录链接 |

装、查、卸是同一个脚本：

node .verify/install-desktop.mjs --status # 只看现状，不写任何东西
node .verify/install-desktop.mjs # 安装（幂等，可重复跑来修复）
node .verify/install-desktop.mjs --uninstall # 精准卸载（不从备份整体还原）

装完必须完全退出并重开 DSH Desktop —— 实测 HMR 从不热装载插件行，客户端半边的装载判定也会被缓存到重启。重启后：

1. 侧栏对一个对话点「分叉会话」→ 新会话标题变成 ⤷ 来源：<源会话标题>，行首出现 ⤷ 徽标；
2. 把这条分叉会话改名 → 标题里的来源没了，但行首 ⤷ 还在，悬停仍显示源对话名。

重启前想确认组合对不对：node --import ./test/register.mjs .verify/diagnose-desktop-compose.mjs（只读，复现宿主编排）与 node .verify/check-client-manifest.mjs（只读，按 dsh-client-modules 的规则预检客户端半边声明）。

⚠️ 本插件零 import，所以不像有依赖的插件那样受"junction 装载解析不到宿主包"的限制。
⚠️ 2026-10-07 出现过"应用按自身状态重写 profile 清单，把本地 link: 依赖与 bundle 项一起丢掉"；真发生的话重跑上面的安装命令即可（脚本是幂等的）。

验证

| 用途 | 命令 |
| 离线：宿主行为断言（13 项，桩 ctx）+ 客户端半边冒烟 | npm test |
| 离线：只跑客户端半边冒烟（协议 / 两个席位 / 来源判据 / 降级 / 异常保护） | npm run client-smoke |
| 真机端到端（14 项，真 Loader / 真 SessionStore / 真 session-title / 真 session-query） | npm run rm-test |
| 预检：按 dsh-client-modules 的规则核对 dsh.client 声明 | node .verify/check-client-manifest.mjs |
| 预检：复现 desktop profile 的宿主编排（先设 NPM_GLOBAL_ROOT = npm root -g，或用 DSH_ANCHOR_GLOBAL 直接指向 dsh 包） | node --import ./test/register.mjs .verify/diagnose-desktop-compose.mjs |
| GUI 真机：无头 Chrome + CDP 断言侧栏行/徽标/悬停段/字色（9 项） | 见 .verify/REPORT.md §7.3 的运行步骤 |
| 提交前隐私检查（暂存内容 / 完整历史） | .privacy-tools/README.md |
| 文档结构 lint | node .verify/md-lint.mjs |

真机装置在仓库内的临时 DSH_HOME 里启动真 DSH 运行时，不碰用户 ~/.dsh、不开端口、不调模型。证据与结论见 .verify/REPORT.md。

已知限制

- 标题里的来源挡不住改名：这是"标签写在标题里"的固有代价。侧栏徽标挡得住（D009）；想要两者都有，现在是默认。
- 标题里的是快照：它记的是 fork 那一刻源对话的标题；改源对话的名字不会让旧标题跟着变。徽标显示的是实时名字。
- 只标注新 fork：插件装载之前就存在的旧分叉不会补标（不做启动扫描）。
- 标注窗口：fork 之后约 4.6 秒内（settleMs 600 + graceMs 4000）会持续收敛标题；此窗口内用户手动改名不会被覆盖（改名后标题不再是继承形态），但若有人把标题改成恰好等于 <源标题> (N) 则可能被贴上标记。
- 标题会被钉住：走的是 sessionTitle.rename()，即 source: { kind: 'user' }。对 fork 子会话无副作用 —— first-prompt 标题提供方本来就跳过带父级的会话；但请勿把本插件用于给非 fork 会话命名。
- maxTitleBytes 会截断：DSH 默认 80 字节，源标题很长时官方 rename 会截断尾部；截断保留头部，所以 ⤷ 来源： 前缀仍在。
- 客户端半边已在真实浏览器里机检（无头 Chrome + CDP，9 项全通过：侧栏行、徽标、tooltip、悬停段、字色、控制台零错误）——见 .verify/REPORT.md §7.3。
- 悬停段的字色是跟着官方悬停卡写死的：官方悬停卡是深色菜单材质，它自己的 CSS 里把文字颜色写成 #fff / #cfd3d6 / #adb2b8，不走主题 token。所以本插件的悬停段也用这几个固定色（v0.1.1 曾用 --dsw-alias-label-primary，在卡片里会解析成浅色主题的近黑值、与卡片背景同色 ⇒ 字看不见；v0.1.2 修正）。若 DSH 之后改了卡片配色，这里要跟着改（GUI 真机的 A7/A8 断言会报警）。
- 只在 DSH 0.2.0-rc.2 / Windows 上实测过：宿主契约与客户端席位按该版本核对；换版本需重跑验证表里的检查。
- 不做：不创建分叉、不搬子 agent、不画树、不改 parent pointer、不写 sidecar、不注册任何模型可见工具、不占 single 占位、不覆盖官方行。

与同类插件的关系

「把来源写进会话标题」是已被验证的做法（dsh-autofork 的 ⑂n 家族根名、dsh-session-tree 的 Task (1) (1)），但两家只标注自己创建的分叉。本插件的差异点是入口覆盖：挂原生 session/created，官方入口造出来的 fork 同样带标签。核查过程与出处见 docs/PRIOR-ART.md。

本插件只标注、不接管，所以可以和上述插件并存：它们先命名过的标题会被原样放过。

获取、反馈与许可

| 项 | 现状 |
| 获取方式 | 公开仓库：WindFromKadath/dsh-plugin-branch-origin；克隆后按「安装与启用」用 link: 目录链接装进 DSH profile |
| 反馈渠道 | 可复现的问题与使用疑问走 Issue；改动建议走 Pull Request —— 检查方式见 MAINTAINER.md |
| 许可 | MIT，见 LICENSE（Copyright (c) 2026 WindFromKadath） |
| 第三方材料 | 无捆绑的第三方代码或素材；README 与 docs/PRIOR-ART.md 只以链接方式引用他人项目 |
| 维护可用性 | 个人项目，按需维护；不承诺响应时限与版本支持周期 |

项目入口

- AGENTS.md：接手与维护规则（含本机环境事实、危险边界）。
- MAINTAINER.md：作者侧维护入口（本轮范围、理解、取舍、验收与公开前检查）。
- docs/DESIGN.md：源码级契约与判定规则（每条带 包/文件:行号）。
- docs/PRIOR-ART.md：2026-10-07 先行者核查。
- tasks.csv：任务与验收。
- .verify/REPORT.md：真机验证报告。
- .privacy-tools/README.md：提交前隐私检查怎么跑、查什么。