dsh-codex-session-pin 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 yhm138
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ # dsh-codex-session-pin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pin and unpin DeepSeek Harness Sessions, and keep pinned Sessions at the top of their project in the sidebar.
4
+
5
+ English | [简体中文](README.zh.md)
6
+
7
+ ## Why this exists
8
+
9
+ DeepSeek Harness already ships Session pinning in its Host: `workspaceRegistry.pinSession()` / `unpinSession()` persist a `pinnedSessionIds` set in `~/.dsh/storages/workspace.json`, and the shipped sidebar reads it.
10
+
11
+ That shipped UI is bypassed as soon as a third-party plugin replaces the `sidebar` slot. [`@michengai/dsh-codex-ui`](https://github.com/MichengAI/dsh-codex-ui) does exactly that: it draws its own Session rows, never reads `pinnedSessionIds`, and does not render the shipped `sidebar.workspaces.session.menu.item` rows — so the built-in pin action disappears from the interface while the data layer still works.
12
+
13
+ This plugin restores the action on top of the official data:
14
+
15
+ - a pin toggle in the Session header (a real `conversation.session.header.utilities` slot entry, so it works under any sidebar)
16
+ - a pin button on each sidebar Session row, plus a “pin / unpin” row in the row’s `⋯` menu
17
+ - a pin marker on pinned rows, and pinned rows ordered ahead of the rest inside their project
18
+
19
+ ## What it does not do
20
+
21
+ - It does not store pin state. The pin set is the official workspace registry's `pinnedSessionIds`; this plugin has no index file of its own, so it cannot drift from the Host, and a Session pinned here shows up pinned in any other surface that reads the official set.
22
+ - It does not take over the sidebar, change row order in React state, or rewrite another plugin's markup. Ordering uses a per-row `order` with the project container switched to `display: flex`; removing the pin removes that inline property, and uninstalling the plugin restores the sidebar's own layout.
23
+ - It does not read or write any other plugin's data.
24
+
25
+ ## Requirements
26
+
27
+ - DeepSeek Harness Host `0.2.1-rc.2` or newer within `0.2.x`.
28
+ - A sidebar that either ships the official pin action (nothing to do — the header toggle still works) or is `@michengai/dsh-codex-ui` (the row buttons apply).
29
+
30
+ ## Install
31
+
32
+ ```sh
33
+ dsh plugin add dsh-codex-session-pin
34
+ ```
35
+
36
+ Or point the plugin manager at the package:
37
+
38
+ ```sh
39
+ dsh plugin add npm:dsh-codex-session-pin
40
+ ```
41
+
42
+ Restart the Harness after installing; the browser half is a Client module, so a page refresh is needed for it to load.
43
+
44
+ ## Usage
45
+
46
+ | Where | What |
47
+ | --- | --- |
48
+ | Session header, right side | A pin button. Click to pin, click again to unpin. |
49
+ | Sidebar Session row, on hover | A pin button next to the row’s other quick actions. |
50
+ | Sidebar Session row `⋯` menu | “Pin session” / “Unpin session”. |
51
+
52
+ A pinned Session leads its project and carries a pin mark before its title. Relative order among pinned Sessions follows the official pin order (most recently pinned first).
53
+
54
+ ## Configuration
55
+
56
+ The plugin has one option, and a normal install does not need it:
57
+
58
+ ```yaml
59
+ - id: codex-session-pin
60
+ config:
61
+ probe: true
62
+ ```
63
+
64
+ `probe` turns on the verification channel described in [docs/verification.md](docs/verification.md): a JSONL diagnostic sink and a one-shot command channel under `~/.dsh/codex-session-pin/`, used to drive the running page’s own action path when no page automation is available. It is off by default and writes nothing until enabled; with it off the client detects the disabled route and stops polling.
65
+
66
+ ## Routes
67
+
68
+ The Host half serves three read/write routes on the Harness web server:
69
+
70
+ | Route | Purpose |
71
+ | --- | --- |
72
+ | `POST /codex-session-pin/state` | The current `pinnedSessionIds`. |
73
+ | `POST /codex-session-pin/toggle` | Fallback pin/unpin for a Client whose `workspaces` service lacks the pin methods. |
74
+ | `GET|POST /codex-session-pin/diag`, `/codex-session-pin/command` | The opt-in verification channel; `204 disabled` unless `probe: true`. |
75
+
76
+ The normal path never uses the toggle route: the browser half calls `ctx.workspaces.pinSession()` / `unpinSession()` directly and keeps the Host route only as a compatibility fallback.
77
+
78
+ ## Compatibility
79
+
80
+ - Pin state and the official UI share one source of truth, so this plugin is safe to install beside other Session tools. It does not touch `dsh-sessions-manager`’s `star.json` (starred ≠ pinned: that plugin’s star is a separate “favorites” index with its own schema).
81
+ - Row enhancement reads only `data-dcu-session`, `.dcu-wb-project-body` and `.dcu-wb-quick-actions` — attributes and classes the sidebar plugin itself publishes — and inserts only nodes this plugin created.
82
+ - Every injected node is tracked per plugin generation, so a hot reload does not remove the nodes of a newer generation, and unloading the plugin removes exactly its own nodes.
83
+ - If the sidebar implementation changes so those hooks disappear, the row buttons simply do not appear; the Session header toggle keeps working, and no error state is left behind.
84
+
85
+ ## Files
86
+
87
+ ```
88
+ index.js Host half: state / toggle routes, opt-in verification channel
89
+ client.js Client half: header toggle + sidebar row enhancement
90
+ cordis.patch.yml Bundle patch: one plugin row
91
+ locale/{en,zh}.json Plugin manager display metadata
92
+ icon.svg Plugin icon
93
+ docs/verification.md How the browser half is verified end to end
94
+ ```
95
+
96
+ ## License
97
+
98
+ MIT
package/README.zh.md ADDED
@@ -0,0 +1,92 @@
1
+ # 会话置顶
2
+
3
+ 在 DeepSeek Harness 的侧栏里置顶 / 取消置顶会话,并让置顶的会话排在所属项目最前面。
4
+
5
+ [English](README.md) | 简体中文
6
+
7
+ ## 为什么做这个插件
8
+
9
+ DeepSeek Harness 官方本来就有会话置顶:`workspaceRegistry.pinSession()` / `unpinSession()` 把 `pinnedSessionIds` 持久化在 `~/.dsh/storages/workspace.json`,官方侧栏读取它。
10
+
11
+ 但只要有第三方插件接管 `sidebar` 槽位,官方那套置顶界面就失效了。[`@michengai/dsh-codex-ui`](https://github.com/MichengAI/dsh-codex-ui) 正是如此:它自己画会话行、不读 `pinnedSessionIds`、也不渲染官方的 `sidebar.workspaces.session.menu.item` 行——数据层还在,入口却从界面上消失了。
12
+
13
+ 这个插件把入口补回来,数据仍然只有官方那一份:
14
+
15
+ - 会话标题栏里的图钉(真实 slot:`conversation.session.header.utilities`,因此任何侧栏实现下都可用)
16
+ - 侧栏每条会话行悬停出现的图钉,以及行内 `⋯` 菜单的「置顶会话 / 取消置顶」
17
+ - 置顶行的图钉标记;置顶行排在所属项目的最前面
18
+
19
+ ## 它不做什么
20
+
21
+ - **不存置顶状态**。置顶集合就是官方 `pinnedSessionIds`,本插件没有自己的索引文件,因此不会与宿主不一致,也不会和别的插件的索引打架。
22
+ - **不接管侧栏**,不改 React 状态里的行顺序,不改写其他插件的标记。排序靠给行写一个 `order`、把项目容器切成 `display: flex`;取消置顶时把这个内联属性撤掉,卸载插件即恢复侧栏原样。
23
+ - **不读写其他插件的数据**。
24
+
25
+ ## 环境要求
26
+
27
+ - DeepSeek Harness Host `0.2.1-rc.2` 起、`0.2.x` 以内。
28
+ - 侧栏是官方实现(此时标题栏图钉仍可用),或者是 `@michengai/dsh-codex-ui`(此时行内按钮生效)。
29
+
30
+ ## 安装
31
+
32
+ ```sh
33
+ dsh plugin add dsh-codex-session-pin
34
+ ```
35
+
36
+ 装完重启 Harness;浏览器那半是 Client 模块,需要刷新页面才会加载。
37
+
38
+ ## 用法
39
+
40
+ | 位置 | 说明 |
41
+ | --- | --- |
42
+ | 会话标题栏右侧 | 图钉按钮,点一次置顶,再点取消 |
43
+ | 侧栏会话行(悬停时) | 图钉按钮,与该行其他快捷操作并列 |
44
+ | 侧栏会话行 `⋯` 菜单 | 「置顶会话 / 取消置顶」 |
45
+
46
+ 置顶的会话排在所属项目最前,标题前带图钉标记。多个置顶会话之间按官方 pin 顺序(最近置顶的在前)。
47
+
48
+ ## 配置
49
+
50
+ 只有一个选项,正常安装不需要动它:
51
+
52
+ ```yaml
53
+ - id: codex-session-pin
54
+ config:
55
+ probe: true
56
+ ```
57
+
58
+ `probe` 打开验证通道(见 [docs/verification.md](docs/verification.md)):`~/.dsh/codex-session-pin/` 下的 JSONL 诊断与一次性命令通道,用于在没有页面自动化时驱动页面自身的动作路径。**默认关闭,关闭时不写任何文件**;关闭状态下客户端读到 `204 disabled` 就停止轮询。
59
+
60
+ ## 路由
61
+
62
+ Host 半在 Harness web server 上注册:
63
+
64
+ | 路由 | 作用 |
65
+ | --- | --- |
66
+ | `POST /codex-session-pin/state` | 当前 `pinnedSessionIds` |
67
+ | `POST /codex-session-pin/toggle` | 兼容回落:给缺少 pin 方法的 Client 用 |
68
+ | `GET|POST /codex-session-pin/diag`、`/command` | 验证通道;未开 `probe` 时回 `204 disabled` |
69
+
70
+ 正常路径不走 toggle 路由:浏览器半直接调 `ctx.workspaces.pinSession()` / `unpinSession()`,Host 路由只作兼容兜底。
71
+
72
+ ## 兼容性
73
+
74
+ - 置顶状态与官方 UI 共用同一份数据,可以和别的会话类插件并存。不碰 `dsh-sessions-manager` 的 `star.json`(收藏是另一套语义、另一套 schema,与置顶无关)。
75
+ - 行增强只读侧栏插件自己发布的 `data-dcu-session`、`.dcu-wb-project-body`、`.dcu-wb-quick-actions`,只插入自己创建的节点。
76
+ - 注入节点按插件「代」登记:热重载不会误删新一代的节点,卸载只删自己那代的。
77
+ - 若侧栏实现变化导致这些挂钩消失,行内按钮不再出现,标题栏图钉照常可用,不会留下错误状态。
78
+
79
+ ## 文件
80
+
81
+ ```
82
+ index.js Host 半:state / toggle 路由,可选的验证通道
83
+ client.js 浏览器半:标题栏图钉 + 侧栏行增强
84
+ cordis.patch.yml bundle patch:一行插件注册
85
+ locale/{en,zh}.json 插件管理里的显示元数据
86
+ icon.svg 图标
87
+ docs/verification.md 浏览器半的端到端验证方法
88
+ ```
89
+
90
+ ## 许可
91
+
92
+ MIT