@cxx42/dsh-plugin-user-question-nav 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# dsh-plugin-user-question-nav
+
+一个 DeepSeek Harness **桌面 bundle 插件**（客户端 UI 插件）：在会话**右侧**渲染一列竖直小圆按钮，从上到下一一对应已加载的每一条**用户提问**；点击某个按钮把会话滚动区平滑滚动到该提问处。
+
+> 对标 [chat.deepseek.com](https://chat.deepseek.com/) 官网右侧的“问题定位”导航，解决长会话手动滚动太累的问题。
+
+本插件是**纯客户端**，不需要 Host 端能力。
+
+---
+
+## 包结构
+
+```
+dsh-plugin-user-question-nav/
+├── package.json          # 桌面 bundle 插件清单（dsh.bundle + dsh.client）
+├── cordis.patch.yml      # 客户端行插入示意（本机设为 no-op，见下文“加载方式”）
+├── lib/
+│   ├── index.js          # Host 半（空 —— 纯客户端插件）
+│   └── client.js         # Client 半（浏览器 bundle，实现导航条）
+├── install.ps1           # 注册到 profile 的幂等脚本（写入无 BOM）
+├── README.md
+└── dynamic-form/         # 备选：动态 Cordis 插件形式（client.js / host.js）
+```
+
+### 关键字段（package.json）
+
+- `dsh.bundle.patch: "./cordis.patch.yml"` —— 桌面 bundle 的补丁声明。
+- `dsh.client: { platform: "web", inject: [...] }` —— 使 `client-modules` 节点把本包扫进 `window.__DSH_BOOT__` 的浏览器清单。
+- `exports["."]` → `./lib/index.js`（Host），`exports["./client"]` → `./lib/client.js`（浏览器 bundle）。
+- `peerDependencies`：`react`（平台种子模块）、`@deepseek-ai/dsh-client-runtime`。
+
+### 原理
+
+- Client 半读取会话快照 `snapshot.chat`（`order` + `nodes`），筛选 `node.kind === "user"` / `"steering"` 的提问，渲染按钮。
+- 点击按钮用 `[data-conversation-scroll]` 与 `[data-chat-anchor-key="<node.key>"]` 计算偏移并 `scrollTo({behavior:"smooth"})`。
+- 挂载在会话级槽位 `conversation.session.header.utilities`（list / session scope），通过 `ctx.slots.inject` 等待槽位声明，避免加载顺序问题。
+
+---
+
+## 如何安装（desktop 与 `dsh --port` web 均适用）
+
+1. **确认包名**：`dsh-plugin-user-question-nav`，本地路径
+   `C:/Users/cxx/Documents/DSHWorkspace/dsh_project2/dsh-plugin-user-question-nav`。
+
+2. **编辑 profile 清单** `~/.dsh/profiles/desktop/package.json`：
+   - 在 `dependencies` 加：
+     ```json
+     "dsh-plugin-user-question-nav": "file:C:/Users/cxx/Documents/DSHWorkspace/dsh_project2/dsh-plugin-user-question-nav"
+     ```
+   - 在 `dsh.profile.bundles` 加：
+     ```json
+     "dsh-plugin-user-question-nav"
+     ```
+
+3. **安装依赖**（在 profile 目录里）：
+   ```pwsh
+   Push-Location "$env:USERPROFILE\.dsh\profiles\desktop"
+   pnpm install
+   Pop-Location
+   ```
+
+4. **在 profile 的用户补丁层 `~/.dsh/profiles/desktop/cordis.patch.yml` 追加客户端行**（见下文“加载方式”，这是生效的**唯一**插入来源）：
+   ```yaml
+   - insert:
+       - id: ui-user-question-nav
+         name: 'dsh-plugin-user-question-nav'
+   ```
+
+5. **重启桌面 / 重新运行 `dsh --port <N>`**，让 profile 在启动时重新组装。
+
+> 也可直接运行本目录的安装脚本 `install.ps1`。它会幂等完成上面第 2、3 步（清单编辑 + pnpm 安装），并且**以无 BOM 的 UTF-8 写清单**（历史上 PowerShell 5 的 `Set-Content -Encoding UTF8` 会写 BOM，导致桌面 `JSON.parse` 崩溃）。
+
+---
+
+## 重要：本机加载方式与“副本同步”（已踩过的坑）
+
+### 唯一插入来源 = profile 用户补丁层
+
+在这台 desktop 上，**profile bundle 的 `- insert:` 不会被可靠地推进到浏览器清单**（证据：同样注册在 profile 里的 `dsh-context`、`@linxin666/dsh-web-ui-all` 也没进 `window.__DSH_BOOT__`；它们走的是 `dsh-market` 热挂载的另一条路）。
+
+所以本插件的客户端行**只在** `~/.dsh/profiles/desktop/cordis.patch.yml`（用户补丁层，最后合成）里插入一次；而 **bundle 自己的 `cordis.patch.yml` 被置为 no-op**（仅注释，无 `insert`），避免重复。
+
+> 如果你在别的部署里 profile bundle 的 `insert` 能正常进图，可以把 bundle 的 `cordis.patch.yml` 恢复为 `- insert:`，并删掉 profile 用户补丁层那行，改成单一来源。
+
+### `duplicate loader entry id: ui-user-question-nav` 的成因
+
+如果**同时**存在两处 insert（bundle 的 `cordis.patch.yml` + profile 用户补丁层），`dsh --port 3081` 会报：
+
+```
+failed to apply loader entry include (cordis:include):
+duplicate loader entry id: ui-user-question-nav
+```
+
+修复：**只保留一处**生效插入（本机保留用户补丁层那处）。改完后 `dsh --port 3081` 能通过组合，直到绑定端口（`listen EACCES` 是环境/端口限制，与插件无关）。
+
+### `file:` 依赖是复制，不是符号链接 —— 改代码后要重新同步
+
+pnpm 对 `file:` 依赖默认**复制**到 `~/.dsh/profiles/desktop/node_modules/dsh-plugin-user-question-nav`（不是链接）。所以改过工作区里的 `lib/client.js`、`package.json`、`cordis.patch.yml` 后，**必须重新同步副本**：
+
+```pwsh
+Push-Location "$env:USERPROFILE\.dsh\profiles\desktop"
+pnpm install    # 或用 install.ps1，会重装 file: 依赖并重写清单（无 BOM）
+Pop-Location
+```
+
+否则桌面/`dsh` 会继续用旧副本。
+
+### 禁用请注意
+
+bundle 在 `dsh.profile.bundles` 里是可修改项，可在桌面“插件清单”禁用。但因为客户端行来自 profile 用户补丁层（不在 bundle 的补丁里），**禁用该 bundle 不会移除那行 insert**。要真正关掉导航条，需删掉/注释掉 `~/.dsh/profiles/desktop/cordis.patch.yml` 里那行。
+
+---
+
+## 备选：动态 Cordis 插件形式
+
+`dynamic-form/` 里是同一功能的**动态插件**版本（`code.client` / `code.host`），适合用 `cordis_define` + `cordis_run` 即改即用（无需安装/重启）。两者 Client 逻辑一致；动态版用 `styles.insert(css)` 注入样式，桌面 bundle 版按官方 bundle 规范用 `<style>` 标签注入。
+
+---
+
+## 依赖与约定
+
+- Client 全局/模块：浏览器 module 系统提供 `react`（平台种子），`ctx.slots`（声明 `inject: ["slots"]`）。
+- 样式全部使用 DSH 主题变量（`--dsw-alias-*`），自动适配亮/暗色。
+- 遵守约定：不操作 `document.body` / `window`，仅用平台暴露的功能性数据属性（`[data-conversation-scroll]`、`[data-chat-anchor-key]`）做滚动定位。
+
+## 局限
+
+- 只对**已加载**的会话节点导航（历史分页更早的消息不在 DOM 中）。
+- 导航条为固定定位、右侧垂直居中；无提问时自动隐藏。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# @cxx42/dsh-plugin-user-question-nav bundle patch.
+#
+# Self-activating: a web client row naming this package, so Cordis loads it as a
+# plugin (Host half via ./lib/index.js) and the client-modules node half scans
+# this package (it declares dsh.client) into window.__DSH_BOOT__; the browser
+# then loads ./lib/client.js and renders the rail.
+
+- insert:
+    - id: ui-user-question-nav
+      name: '@cxx42/dsh-plugin-user-question-nav'

package/lib/client.js

@@ -0,0 +1,115 @@
+// @cxx42/dsh-plugin-user-question-nav — Client half (browser bundle).
+//
+// This is a dsh.client bundle: it is served as /plugins/@cxx42/dsh-plugin-user-question-nav/client.js
+// and loaded into the browser module system. It uses `window.__ModuleLoader__.load({id, factory})`,
+// takes `require` (which resolves platform seeds like 'react'), and exports the standard
+// client-plugin face: `inject` (service dependencies) + `apply(ctx)`.
+//
+// Feature: on the right side of a session, render a vertical rail of small buttons,
+// one per user-posed question (in order). Click a button to scroll the conversation
+// scrollport to that user message.node.
+
+window.__ModuleLoader__.load({
+	id: "@cxx42/dsh-plugin-user-question-nav",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+
+		// The conversation message slot this plugin registers into (declared by
+		// @deepseek-ai/dsh-client-ui-conversation). Session-scoped list slot.
+		const SLOT = "conversation.session.header.utilities";
+
+		// ── styles (theme variables; kept as compact CSS) ─────────────────────
+		const RAIL_CSS = ".qn-rail{position:fixed;right:12px;top:50%;transform:translateY(-50%);z-index:40;display:flex;flex-direction:column;gap:6px;align-items:center;padding:8px 5px;border-radius:999px;pointer-events:auto;background:var(--dsw-alias-bg-base);border:1px solid var(--dsw-alias-border-l1);box-shadow:var(--dsw-shadow-lv2)}.qn-rail-title{writing-mode:vertical-rl;font-family:var(--dsw-font-family);font-size:10px;line-height:1;letter-spacing:1px;text-transform:uppercase;color:var(--dsw-alias-label-tertiary);margin-bottom:2px;user-select:none}.qn-dot{width:22px;height:22px;border:none;border-radius:999px;padding:0;background:var(--dsw-alias-interactive-bg-hover-solid);color:var(--dsw-alias-label-secondary);font-family:var(--dsw-font-family);font-size:11px;font-weight:500;line-height:1;display:flex;align-items:center;justify-content:center;cursor:pointer;transition:background-color .12s,color .12s,transform .12s}.qn-dot:hover{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary);transform:scale(1.1)}.qn-dot:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}";
+		const CSS_TAG_ID = "@cxx42/dsh-plugin-user-question-nav/rail.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(CSS_TAG_ID) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "@cxx42/dsh-plugin-user-question-nav";
+			tag.dataset.pluginCss = CSS_TAG_ID;
+			tag.textContent = RAIL_CSS;
+			document.head.appendChild(tag);
+		}
+
+		// ── derive the ordered list of user-question nodes from the chat snapshot ──
+		function railQuestions(order, nodes) {
+			const out = [];
+			if (!order) return out;
+			for (let i = 0; i < order.length; i++) {
+				const key = order[i];
+				const node = nodes && nodes.get ? nodes.get(key) : undefined;
+				if (!node) continue;
+				const kind = node.kind || (node.data && node.data.kind);
+				if (kind !== "user" && kind !== "steering") continue;
+				const text = node.data && node.data.content != null ? String(node.data.content) : "";
+				out.push({ key, text });
+			}
+			return out;
+		}
+
+		// ── scroll the conversation scrollport to a specific message node ─────
+		function railScrollTo(key) {
+			const scroller = document.querySelector("[data-conversation-scroll]");
+			if (!scroller) return;
+			const anchor = scroller.querySelector('[data-chat-anchor-key="' + key + '"]');
+			if (!anchor) return;
+			const top = anchor.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop;
+			scroller.scrollTo({ top: Math.max(0, top), behavior: "smooth" });
+		}
+
+		const EMPTY_ORDER = [];
+
+		// ── the rail component (standard session kit gives it `useSession`) ────
+		function QuestionNavRail(props) {
+			const order = props.useSession((snapshot) => (snapshot.chat && snapshot.chat.order) || EMPTY_ORDER);
+			const nodes = props.useSession((snapshot) => snapshot.chat && snapshot.chat.nodes);
+			const questions = railQuestions(order, nodes);
+			if (questions.length === 0) return null;
+
+			const buttons = [];
+			for (let i = 0; i < questions.length; i++) {
+				const q = questions[i];
+				buttons.push(react.createElement("button", {
+					key: q.key,
+					type: "button",
+					className: "qn-dot",
+					title: q.text || "#" + (i + 1),
+					onClick: (function (key) {
+						return function () { railScrollTo(key); };
+					})(q.key),
+					children: String(i + 1)
+				}));
+			}
+
+			return react.createElement("div", {
+				className: "qn-rail",
+				role: "navigation",
+				"aria-label": "问题导航"
+			},
+				react.createElement("div", { className: "qn-rail-title" }, "问题"),
+				buttons
+			);
+		}
+
+		/** Services required by the client plugin. */
+		const inject = ["slots"];
+
+		/**
+		 * Mount the client plugin into the conversation's session header utilities
+		 * slot. `slots.inject` waits for the slot to be declared by the conversation
+		 * package, so load order does not matter.
+		 * @param {any} ctx - the client Cordis context.
+		 */
+		function apply(ctx) {
+			ctx.slots.inject(SLOT, () => ctx.slots.register({
+				name: SLOT,
+				id: "user-question-nav"
+			}, QuestionNavRail));
+		}
+
+		exports.inject = inject;
+		exports.apply = apply;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,28 @@
+// dsh-plugin-user-question-nav — Host half.
+//
+// This plugin is a pure client-side UI plugin: it reads the conversation
+// snapshot and scrolls the chat, all on the browser side. It needs no Host
+// capability, so the Host half is empty.
+//
+// Cordis loads this module as a plugin because the bundle's cordis.patch.yml
+// inserts a row naming this package. The client-modules node half separately
+// scans this package (it declares dsh.client) into window.__DSH_BOOT__, so the
+// browser also loads lib/client.js as the client half.
+//
+// Module-plugin contract (same shape as the official dsh-client-ui-* packages):
+// export `name`, `inject`, and `apply`.
+
+/** Cordis plugin identity (label only). */
+export const name = '@cxx42/dsh-plugin-user-question-nav';
+
+/** Services that must exist before apply() runs. */
+export const inject = [];
+
+/**
+ * Mount the Host half. Empty — the client half does all the work.
+ * @param {unknown} ctx - the plugin's Cordis context (unused here).
+ * @param {unknown} [config] - this row's `config:` block (unused here).
+ */
+export function apply(ctx, config) {
+  // intentionally empty
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cxx42/dsh-plugin-user-question-nav",
+  "version": "1.0.0",
+  "description": "DeepSeek Harness web plugin: a right-side navigation rail of user-question buttons that scrolls the chat to each user message (like chat.deepseek.com).",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "conversation",
+    "navigation",
+    "client"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "@deepseek-ai/dsh-client-runtime": "*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}