DSH 侧栏的渲染顺序由浏览器本地排序表决定，且默认按活跃度排序。这意味着即使宿主端调整了会话顺序，在界面上通常看不到变化。dsh-pin-session 插件通过“宿主端存事实 + 客户端排序”的架构，允许用户将重要对话钉在侧栏分组顶部。
核心机制¶
插件不依赖复杂的运行时环境。宿主端只负责存储“哪些会话被置顶”这一事实（使用原子写 JSON 和信任栅栏内的 HTTP 接口），客户端负责在 DOM 层完成排序。
由于侧栏会话行没有 session id 属性，插件通过读取 React fiber (__reactFiber$...) 往上查找 memoizedProps.node.id 来精确获取标识；如果取不到，会退回到标题反查（仅限标题唯一的情况）。
- 零运行时依赖：宿主端只用
node:fs/node:path，客户端只require("react")。 - 坏了不影响 DSH：任何一步失败只丢本插件自己的效果，侧栏本体不受影响。
安装与前置条件¶
安装前请确保：
1. pnpm 在 PATH 上（DSH 自带的即可）。
2. DSH 核心版本为 0.1.5-rc.1。
# 从 GitHub 安装
dsh plugin --profile web add github:BPTumbleweed/dsh-pin-session
# 或从 npm 安装
dsh plugin --profile web add dsh-pin-session
安装后，宿主端改动需重启服务，客户端改动需硬刷新页面（Ctrl+Shift+R）。
配置¶
Profile Patch 覆盖¶
可以通过 profile patch 调整存储路径、接口前缀、上限和熔断阈值。
- id: dsh-pin-session
config:
storeRoot: /path/to/pin-data # 默认 $DSH_HOME/dsh-pin-session
routePrefix: /dsh-pin # 接口与面板前缀
maxPins: 100 # 置顶上限
breakerThreshold: 5 # 同一能力连续失败几次后熔断
allowUnfenced: false # 栅栏不可用时是否放行（默认 false = fail-closed）
浏览器侧开关¶
在浏览器 localStorage 中设置以下键值可免重启地开关功能：
| 键 | 值 | 作用 |
|---|---|---|
dsh-pin:disable |
"1" |
整个客户端效果关掉（含按钮与徽标） |
dsh-pin:prefix |
"/dsh-pin" |
改接口前缀（宿主端改了 routePrefix 时用） |
使用方法¶
1. 命令行 (CLI)¶
CLI 工具直接读写同一份 JSON 数据，适用于没有浏览器的场景（如 SSH、脚本）。
dsh-pin list # 列出置顶会话
dsh-pin pin <sessionId> # 置顶会话（可选传入 title）
dsh-pin unpin <sessionId> # 取消置顶
dsh-pin toggle <sessionId> # 切换置顶状态
dsh-pin move <sessionId> <top|bottom> # 移动到顶部或底部
dsh-pin clear # 清空置顶列表
dsh-pin path # 查看数据文件路径
2. HTTP 接口¶
接口默认走 DSH 的信任栅栏，依赖信任栅栏时默认 fail-closed。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /dsh-pin/api/list |
获取置顶集合（客户端排序引擎的数据源） |
| GET | /dsh-pin/api/status |
自检状态（能力、计数、最近错误） |
| POST | /dsh-pin/api/pin |
置顶会话 |
| POST | /dsh-pin/api/unpin |
取消置顶 |
| POST | /dsh-pin/api/toggle |
切换置顶 |
| POST | /dsh-pin/api/reorder |
重排序 |
| GET | /dsh-pin/panel |
管理页（纯服务端渲染） |
3. 界面操作¶
- 会话头部：在会话头部出现 📌 按钮，点击可置顶/取消置顶。
- 侧栏会话行：鼠标悬停在侧栏会话行上，行内出现 📌 按钮，点击可将该行移动到所在分组顶部。
注意事项¶
- 只在浏览器里生效：置顶是客户端 DOM 排序，不会改变宿主端的会话顺序。换个浏览器或清空本地状态后，置顶集合还在（服务端），但效果需重新应用。
- 只在同一个工作区分组内置顶：置顶行会被提到“它自己那个分组”的顶部。
- 搜索态不干预：搜索结果的顺序由查询决定，此时插件不会动 DOM。
- 重命名时不动 DOM：当焦点在会话行内的输入框时，插件会跳过该轮排序（搬节点会导致输入框失焦），焦点离开后会自动补上。
- 标题可能缺失：通过 CLI 置顶且未传入
title的会话，列表中可能只显示 sessionId。 - 依赖 DSH 版本：需要 DSH 核心版本
0.1.5-rc.1。
许可¶
MIT © 2026 Kan Zheng
