dsh-plugin-turn-index 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 李宗泽
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# dsh-plugin-turn-index
 
-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.
+为 DeepSeek Harness 会话右侧的「轮次导航」索引条追加一个**提问索引**：
+
+- 在索引条底部追加一个小箭头按钮；
+- 点开后列出这次会话的**全部提问**（每一轮的第一条人类消息）；
+- 顶部提供**搜索过滤**：和标题同一行的紧凑搜索框，输入关键词即可过滤提问，匹配到的位置会加背景高亮，结果按相关度排序；
+- 点任意一条提问，跳到对应的那一轮；还没加载进窗口的轮次会先自动回补历史再跳转。
+
+它只增强内置索引，不替换索引条本身：原来的小刻度、悬浮预览、当前轮高亮、历史回补逻辑都保持原样。
+
+## 交互
+
+1. 会话右侧出现轮次导航条时，索引条底部会出现一个 `<` 箭头。
+2. 点箭头展开「提问索引」浮层，每行显示轮次编号和该轮提问的前几行；标题后面只显示当前列表的提问数量（一个数字）。
+3. 搜索框和标题在同一行，作为辅助入口：输入关键词即时过滤，匹配到的位置会加背景高亮；按 `Enter` 跳到第一条匹配，按 `Esc` 先清空搜索、再按一次收起浮层。
+4. 点某一行即可跳到该轮；当前轮在浮层里高亮。
+5. 高度不是固定的：内容少时仍按原来的规则，底部贴索引条底部、向上长；内容超过上方可用空间后，顶部停在聊天区顶部，底部随之向下延伸，直到窗口底部（会盖住输入框）后，列表才开始在浮层内部滚动。点浮层外或再点箭头可收起。
+
+> 内置轮次导航在会话面板较窄时会被容器查询隐藏（`<= 900px`）。这时插件也不会显示；把窗口拉宽或缩小界面缩放即可看到索引条和箭头。
+
+## 原理
+
+- **数据**：读取当前会话的 `turnOutline` 投影。它是整段日志的轮次大纲（轮次号、`turn/start` 的 seq、提问/回答预览），所以没加载进窗口的旧轮次也能列出来。
+- **搜索**：标题栏内的紧凑输入框对提问做过滤，`Enter` 跳到第一条匹配，`Esc` 清空搜索；标题后的数字随结果变化。
+- **入口**：注册到 `shell.overlay` 这个 frame 级浮层槽位，因此不需要改动对话视图或索引条源码。
+- **纵向空间**：从聊天区顶部到窗口底部作为浮层边界，最大高度用满这段空间，长列表可以覆盖输入框继续向下用满屏幕。内容不足时沿用旧锚点（底部贴索引条）；内容变长后顶部固定、底部向下延伸，一直到窗口底部才由列表自身滚动。搜索时锁定进入搜索那一刻的高度，过滤过程中不改变浮层高度和底部位置；清空搜索后恢复内容驱动。
+- **定位**：通过 DOM 找到带 `button[data-index]` 刻度的 `<nav>`（即轮次导航条），测量它的位置，把箭头固定在索引条底部。
+- **跳转**：点击列表项时，驱动索引条自己的刻度按钮（必要时先滚动索引条让虚拟化刻度渲染出来），从而复用官方的 `loadThrough` / 滚动 / 当前轮激活逻辑。
+
+## 安装
+
+要求 DSH `0.2.x`（Web / Desktop 的客户端都适用）。
+
+从本地目录安装到某个 profile：
+
+```sh
+dsh plugin --profile web add file:D:\path\to\dsh-plugin-turn-index
+```
+
+发布到 npm 后也可以直接按包名安装：
+
+```sh
+dsh plugin --profile web add dsh-plugin-turn-index
+```
+
+或在 Web UI 的「插件」管理中把该目录作为本地包安装。安装后刷新页面。
+
+Desktop 应用的 `desktop` profile 由 Electron 托管，CLI 不直接管理；可以用插件管理面板/宿主提供的安装入口，把 `file:D:\path\to\dsh-plugin-turn-index` 装进该 profile。
+
+## 卸载
+
+```sh
+dsh plugin --profile web remove dsh-plugin-turn-index
+```
+
+或在插件管理里移除 `dsh-plugin-turn-index`。
+
+## 开发
+
+- `lib/index.js`：Host 半体，空实现，只为让包成为合法的 profile bundle row。
+- `lib/client.js`：浏览器半体，注册 `shell.overlay`、读取 `turnOutline`、定位索引条并处理跳转。
+- `cordis.patch.yml`：bundle patch，插入 Host row。
+
+改完 `lib/client.js` 后同步到 profile 的 `node_modules/dsh-plugin-turn-index/`，再刷新页面（生产模式下客户端模块不是热更新）。
+
+## 兼容性说明
+
+- 依赖 0.2.x 的 `turnOutline` 投影与 `button[data-index]` 轮次刻度 DOM。
+- 如果将来内置索引条新增了正式扩展槽位，可以改用槽位，去掉 DOM 测量与刻度点击这两处兼容层。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-plugin-turn-index bundle patch: insert the plugin's (no-op) Host half.
+# The browser half is discovered from this package's `dsh.client` declaration
+# and contributes the question-index overlay into `shell.overlay`.
+- insert:
+    - id: dsh-plugin-turn-index
+      name: 'dsh-plugin-turn-index'