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
