# DSH Plugin: UI Session Pin

[English](README.md) | 中文

> [!IMPORTANT]
> **本插件在未打补丁的 harness 上跑不起来。** 它依赖 `sessionPins` 服务，而已发布的
> 任何一版 DeepSeek Harness 都不提供这个服务。装在原版上，插件会一直处于等待状态，
> 整个 Web 界面会以 `Failed to load plugins` 加载失败。
>
> 把 [`patches/harness-session-pin.patch`](patches/README.zh.md) 打到
> `dsh-v0.1.1-rc.2` 的检出上是**前置条件，不是可选项**。原因是图钉要出现在侧栏每一行
> 会话上、置顶还要改变会话排序，而这两件事在当前官方开放的扩展点里都够不着。
> [详细原因与退场条件](patches/README.zh.md)

为 [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness) 网页版提供**全局会话置顶**功能，让你把重要的对话一键钉在左侧边栏最上方的专属区域，不管切换到哪个工作区（Workspace）都能一眼看到、随时打开。

## 适用人群与场景

适合日常处理多个项目、积累了大量历史会话，希望将核心任务、长期目标或高频参考的对话常驻在侧边栏顶部的用户。

## 核心特性

- **跨工作区全局常驻**：置顶区域独立于普通 Workspace 列表，切换项目或目录时置顶会话依然触手可及。
- **操作体验对齐 Codex**：在会话菜单中一键点击“置顶/取消置顶”；最近置顶的会话自动排在最前。
- **与归档生命周期联动**：会话归档时保留置顶标记，还原会话后自动恢复置顶状态。
- **纯前端轻量存储**：仅在本地配置（`$DSH_HOME/settings.yaml` 的 `ui-session-pin.pinnedSessionIds`）中记录置顶会话 ID，界面自动保存，无需手动编辑。
- **零污染无损卸载**：移除插件后，所有会话立即恢复到原工作区的普通列表中，不破坏底层历史记录与工作区数据。

## 极简安装与使用

请把经过评审的提交安装进 Web profile。仓库自带 `dsh.bundle` 配置和预构建运行文件，通过 Git 安装无需在本地执行构建：

```sh
dsh plugin --profile web add github:OpenSaozi/dsh-session-pin#<commit-sha>
```

安装后刷新页面，鼠标悬停在左侧边栏任意会话上，点击菜单中的“置顶会话”即可生效。

## 兼容性说明

本插件要求 DeepSeek Harness 中的 `@deepseek-ai/dsh-client-ui-workspace` 包已包含 `ctx.sessionPins` 扩展接口。

## 存储与隐私安全

Host 设置提供方仅保存一份有序的会话 ID 列表。本插件不读取、不上传任何提示词、模型回复、凭据或工作区路径信息。

## 模型体验

### 请求上下文与条件

#### 模型看到的内容

无。唯一持久化字段是 `pinnedSessionIds`，请求组装不会读取它；本包不会增加提示词、消息、工具 schema 或提供方请求字段。

#### Token 影响

直接 token 数为零。

#### KV Cache 影响

无；置顶与取消置顶不会发起或改变模型请求。

## 已知限制与暂缓事项

- **依赖 Host 设置开放**——没有通过设置 API 开放 `ui-session-pin` 的部署不会显示置顶控件，也不会退回到第二份浏览器本地存储。
- **置顶区不支持手动排序**——置顶操作会把 Session 移到最上方；拖拽排序仍只适用于普通 Workspace 行和单列表行。