jackovibe/dsh-codex-pin

dsh-codex-pin

DeepSeek Harness Web 侧栏的 Codex 式会话置顶 —— 置顶是标记，不是位置。

置顶一个会话，会把它提升到整个工作区列表之上的单个 已置顶 / Pinned 区域。
切换置顶状态从不调用 workspace.insertSessionBefore，从不改写工作区
视图的排序，也从不切换侧栏的排序模式：~/.dsh/storages/workspace.json
里的持久会话顺序原封不动。这条承诺由仓库里的静态检查（npm test）守着，
而不是只写在文档里。

已置顶区域位于工作区列表之上

独立社区插件，非 DeepSeek 官方产品，与 OpenAI 无隶属关系；“Codex 式”描述的是
它复刻的交互模型，不代表任何官方关联。

功能

- 一个置顶标记：鼠标悬停会话行 → 点图钉（📌），会话进入侧栏顶部的
已置顶 / Pinned，新的置顶排在前面。
- 置顶行离开原分组，不产生重复行：点该行即打开会话，点行上的图钉即取消置顶，
会话回到列表顺序原本属于它的位置。
- 宿主持久化：有序列表存在宿主 settings 命名空间 codex-pin
（~/.dsh/settings.yaml），重启后仍在，且凡设置通道可达的浏览器都能共享。
- 诚实降级：设置通道不可达的浏览器改用本机 localStorage，分区标题会显示
仅本浏览器 / This browser only。回退只是救急、不是单向锁：宿主写失败会先重试
一次；即便已经回退，之后每次置顶仍会探测宿主，一旦某次写入成功就清掉回退数据，
标题上的提示自动消失。
- 对模型零影响：不产生会话事件、不消耗 token、无遥测、无外部网络请求——
浏览器半程只触及同源的宿主能力：设置命名空间，以及行菜单用到的
workspaces.openSession / forkSession / archiveSession 与会话自身的 rename。

和同类置顶插件的区别

| | dsh-codex-pin | dsh-pin | dsh-session-pin |
|---|---|---|---|
| 置顶层级 | 一层：全局「已置顶」区 | 两层：工作区内 + 全局托盘 | 两层：工作区 + 会话 |
| 持久会话顺序 | 从不写入——完全不调用任何排序接口 | 工作区内置顶走 workspace.insertSessionBefore，并把排序切到手动；全局托盘是显示层 | 置顶会话移动到所属 account 最前 |
| 置顶状态存储 | 宿主 codex-pin.pinned + localStorage 兜底 | 宿主顺序锚点 + 本地记录 | 宿主 settings，按浏览器持久 |
| 附加能力 | 刻意不做 | 锚点精确还原、排序模式还原 | 8 色标记、看板、标签、视图、/goto |
| 体积 | 一个 bundle 条目，无 HTTP 路由 | 纯客户端 | 宿主 + 浏览器双侧 |

想要「置顶只是可随时撤销的视觉标记」，选这个；想让置顶顺带决定顺序、颜色或看板，
选另外两个。

前置条件

- DeepSeek Harness 的 web profile（插件声明 platform: web）。
- 实测环境 dsh web 0.1.5-rc.1，并已在 0.1.6-alpha.2 复测（该版本重写了
侧栏，浏览器半程因此改为探测宿主能力形状而非写死某一版的 API）；peer 范围声明为
=0.1.2-rc.1 =22.19.0（仅从源码构建时需要）。
- dsh plugin add 在所有已知 DSH 版本上都会打印 peer 依赖警告——生态里的 peer
声明都是可选叠加层，该警告是预期的、无害的。

安装

直接从 GitHub 装 —— 现在就能用的路径
dsh plugin --profile web add github:jackovibe/dsh-codex-pin

想钉住某个 release 而不是跟 main（任何 tag 都可以）
dsh plugin --profile web add github:jackovibe/dsh-codex-pin#v0.2.7

用 release 附件里的 tarball（Releases → Assets）
dsh plugin --profile web add ./dsh-codex-pin-0.2.7.tgz

从源码
npm run build && npm pack && dsh plugin --profile web add ./dsh-codex-pin-0.2.7.tgz

npm（发布后）
dsh plugin --profile web add dsh-codex-pin

github: 这一条就是本插件自己开发用的 profile 在用的写法，每次本地运行都在跑；
npm 包名是留给后续发布的，目前还解析不到。

装完重启 dsh web（loader 在启动时组合 bundle 层），再在浏览器 Ctrl+Shift+R
硬刷新。悬停会话行即可看到图钉。

挂载方式

包自带 bundle patch（cordis.patch.yml），只插入一个 loader 条目：

- insert:
- id: codex-pin
name: dsh-codex-pin

dsh plugin add 会自行对账 dsh.profile.bundles，所以不要再在 profile 自己的
cordis.patch.yml 里重复插入同一条：两层插入同一个 loader id 会导致启动失败。
重启前可以这样确认组合结果：

dsh --profile web --dump-config | grep -c 'id: codex-pin'   # 必须输出 1

升级 / 卸载

升级：重跑同一个 spec（会取 main 上最新一次提交，然后重启）
dsh plugin --profile web add github:jackovibe/dsh-codex-pin
或切到指定 release
dsh plugin --profile web add github:jackovibe/dsh-codex-pin#v0.2.7

dsh plugin --profile web remove dsh-codex-pin       # 卸载后重启

卸载后 settings.yaml 里仍会留下 codex-pin 段（会话 id），需要清理可手动删除。

使用

| 操作 | 方式 |
|---|---|
| 置顶 / 取消置顶会话 | 悬停行，点图钉控件（📌 切换） |
| 打开已置顶会话 | 点「已置顶 / Pinned」区里的那一行 |
| 从分区里取消置顶 | 点分区行上的实心图钉 |
| 重命名 / 分叉 / 归档 / 删除 / 复制标题或 ID | 右键任意会话行打开行菜单 |
| 对当前会话置顶 / 重命名 / 归档 | Ctrl+Alt+P / Alt+Ctrl+R / Ctrl+Shift+A |

置顶与未置顶的会话行带同一组控件：图钉（未置顶=描边、置顶=实心）与归档；
「已置顶」区里的行同样带图钉和归档，所以归档在置顶状态下依然可用。行菜单里的
删除会话（红色）走 archive-manager 的 workspaceRegistry.deleteSession，
点击后先弹确认框；未装该插件时这一项会报「不可用」而不是静默失败。

菜单文案与提示语跟随应用语言：本插件经 ctx.inject(['locale']) 注册 zh/en
词典，中文界面显示「重命名 / 置顶聊天 / 归档会话 / 删除会话」，切成英文界面立刻
变成 Rename / Pin chat / Archive session / Delete session（无需刷新）。

Ctrl+Shift+A 会先弹二次确认再归档当前会话（单个全局按键不该静默归档）；行菜单里的归档是一次明确点击，仍然一步到位。
右键会话行打开的是本插件的 Codex 式浮层菜单；只会拦截本插件能处理的会话行，
其余行（例如没有会话身份的行）仍走原来的右键菜单。应用自身的多选、搜索、
设置页不受影响。

配置

| 键 | 默认 | 含义 |
|---|---|---|
| maxPins | 0 | 置顶数量上限；0 = 不限。写在 loader 条目上： |

profile cordis.patch.yml
- id: codex-pin
config:
maxPins: 5

到达上限后，新置顶会挤掉最旧的一条，调低上限会在下一次读取时立即收敛视图。
修改上限会让宿主重新组合插件：已经打开的页面要等宿主推送新值才生效（实测可能
要几十秒，且这个窗口内的写入会与重新注册竞争）——改完上限请刷新页面。浏览器
本地兜底模式读不到该策略，因此上限只作用于宿主侧的列表。

状态存在哪里

| 内容 | 位置 |
|---|---|
| 置顶 id（新→旧） | ~/.dsh/settings.yaml → codex-pin.pinned |
| 浏览器本地兜底 | localStorage 键 dsh.codex-pin.pinned |
| 会话顺序 | 不碰——本插件从不写 ~/.dsh/storages/workspace.json |

兼容性

| DSH Web | 状态 |
|---|---|
| 0.1.5-rc.1 | 已实测（2026-09-16）——见「验证」 |
| 0.1.2-rc.1 … 0.1.5-rc.2 | 落在声明的 peer 范围内，未逐一实测 |
| 任何 0.2.x | 不承诺；peer 范围止于 <0.2.0 |

与接管侧栏槽位（sidebar.workspaces，priority −0.5）的
@michengai/dsh-archive-manager 同装已实测：已置顶区仍渲染在工作区树之上，
页面零报错。改写侧栏的插件是最可能的失配来源，因为本插件靠 React fiber props
定位行（见「限制」）。

验证

静态检查只需 Node：

npm run check   # lib/client.js 与 src/client-src.js 必须逐字节一致
npm test        # 不变量：不调排序接口、只有一个 loader 条目、e2e 选择器可产出

e2e 用 Playwright 的 Chromium 驱动一个运行中的 dsh web GUI。用 DSH_E2E_URL
（含 ?token=… 的完整地址）指向你的实例，或让它读取启动器写进
~/.dsh/dsh-web.log 的地址；DSH_E2E_CHROMIUM 可覆盖可执行文件（会自动发现
ms-playwright 缓存里的任意 chromium-* 构建）。它需要 devDependencies 里的
playwright-core：

node e2e/pin-e2e.mjs 3080              # 置顶 → 分区 → 打开 → 取消 → 落盘
node e2e/pin-e2e.mjs 3080 --leave-pinned
node e2e/state-check.mjs 3080          # 只读：分区当前渲染成什么样

2026-09-16 在 dsh web 0.1.5-rc.1 上的实测结果（Windows，5 条会话行、
2 个工作区分组，插件由打包后的 tarball 安装）。原始记录见
verification/（已脱敏：token、会话/工作区 id 与标题在写入前
就被移除）。e2e 每次运行都会断言下表每一行，任何一行不成立即非零退出：

| 检查项 | 结果 |
|---|---|
| 客户端 bundle 在启动图里 | …,dsh-codex-pin/client.js,…，经 client-HMR 重新哈希后提供 |
| 会话行注入置顶控件 | 5 行中 4 行——临时的 新会话 行本身没有行操作 |
| 已置顶区位于工作区列表之上 | aboveTree: true |
| 置顶行离开原分组 | hiddenRows: 1，取消置顶后回到 0 |
| 点分区行打开会话 | 点击走 sessions.open（单页应用，无 URL 变化可断言） |
| 取消置顶行归位 | 分区消失，hiddenRows: 0 |
| 置顶不改 DOM 顺序 | 置顶前后标题序列完全一致 |
| 落到宿主 | settings.yaml → codex-pin.pinned，id 由行的 React fiber props 读出 |
| 宿主顺序未变 | workspace.json 的 sessionIds 前后逐元素相同 |
| 从宿主渲染而非浏览器 | 全新无本地状态的上下文：已置顶 · 1，noteShown: false |
| 分区控件标记 | tray、tray-head、tray-row、tray-pin、tray-archive，控件容器 tray-ctl |
| maxPins: 1 | 写入与读取两侧都只留最新一条，见 verification/maxpins-check.md |
| 控制台 / 页面报错 | 无 |

开发

lib/index.js        宿主半程：注册 codex-pin settings 命名空间
src/client-src.js   浏览器半程（手写源码）
lib/client.js       实际提供的 bundle —— 由 npm run build 生成，npm run check 校验
e2e/                针对运行中的 dsh web 的 Playwright 套件（dev 依赖）
test/               零依赖不变量测试（npm test）
verification/       上文引用的实测记录（已脱敏）
shots/              e2e 截图（仅本地，不随包发布：含真实会话标题）

lib/client.js 是 src/client-src.js 的拷贝（loader 需要一段注册
window.__ModuleLoader__.load 的经典脚本）：改源码只动 src/，然后
npm run build；两者漂移会被 CI 拦下。

限制

- 行内控件靠 React fiber props 和行自身的操作按钮定位。DSH 前端重写、或其他插件
接管侧栏槽位，都可能让行内控件失效（已置顶区本身仍能工作）。
- 只回退本插件自己隐藏的行，且装饰范围限定在工作区树内——但这是个启发式
判断（带分组头的树，平铺模式则全部树）：若某插件在别的区域用 treeitem 渲染
会话行，那些行仍会被装饰和上提。
- 置顶 id 不会自动清理。被删除会话的 id 留在列表里但不再渲染；「有 id、没有可见
行」的置顶（删除的会话，或被 DSH 原生菜单归档的会话）只能靠手改
~/.dsh/settings.yaml 的 codex-pin.pinned 取消。走本插件菜单归档会先取消
置顶；走原生菜单归档则置顶潜伏（取消归档后复活，并占用 maxPins 名额）。
- 置顶行用 display: none 隐藏；宿主自己的分组徽标与计数由它的状态算出，不会
被调整。
- 列表是整段写入的：切置顶会先重读，所以两个浏览器同时置顶会合并，但在设置
RPC 的延迟窗口内后写者仍会覆盖先写者。
- 托盘与右键菜单是鼠标驱动的；除行内按钮和三个全局快捷键外没有键盘路径。
- Ctrl+Alt+P / Alt+Ctrl+R / Ctrl+Shift+A 是全局捕获、作用于当前会话，可能
与其他绑定冲突。
- 只支持会话置顶；Codex 模型里的工作区置顶未实现。
- 行右键菜单是插件自绘浮层，不是 DSH 原生右键菜单。

许可

MIT —— 见 LICENSE。DOM 层改编自
dsh-pin（MIT），宿主侧存储模式参考
dsh-session-pin（Apache-2.0）；
详见 NOTICE.md 与 THIRD_PARTY_LICENSES.md。