dsh-milestone 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-milestone contributors
+
+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

@@ -0,0 +1,72 @@
+# dsh-milestone
+
+会话里程碑导航条（DeepSeek Harness 插件）。在会话视图右侧渲染一条垂直 scrubber，每个 **user 发言** 对应一个进度点：鼠标悬停预览该条消息的前 80 字，点击平滑跳转到对应位置。
+
+> **dsh-plugin** · 适配 DeepSeek Harness (`deepseek-ai/deepseek-harness`) Web UI。
+
+## 功能
+
+- **进度点（tick）**：每条真实 user 消息 = 一个 tick，按**真实渲染偏移**定位（非等距），跟随滚动与内容变化实时更新。
+- **悬停预览**：hover 显示该条 user 消息的前 80 字。
+- **点击跳转**：点击 tick 平滑滚动到对应消息（`scrollIntoView`）。
+- 少于 2 条 user 消息时不渲染（无导航价值）。
+
+## 安装
+
+```sh
+# 本地目录（开发）
+dsh plugin --profile demo add ./dsh-milestone
+
+# npm 包（发布后）
+dsh plugin --profile demo add dsh-milestone
+
+# GitHub 仓库（需 prepare 脚本 + allowBuilds 许可）
+dsh plugin --profile demo add github:you/dsh-milestone
+```
+
+然后 `npx @deepseek-ai/dsh web` 启动 Web UI 即可看到右侧里程碑条。
+
+## 开发
+
+要求 **Node.js `>= 24`**（官方 harness 要求 `^22.19 || >=24`，本仓库已验证 `24.19.0`）。依赖从 npm 安装（`0.1.0-rc.6` 系列，完整可用）。
+
+```sh
+pnpm install
+pnpm run build       # 产出 lib/index.js (node half) + lib/client.js (browser half)
+pnpm exec tsc --noEmit   # 类型检查
+pnpm run watch       # 监听构建
+```
+
+构建产物：`lib/index.js`（node half，空 apply）+ `lib/client.js`（browser half，CJS closure，`window.__ModuleLoader__.load` banner）。
+
+### 架构
+
+双半边插件（Host = Node 进程，Client = 浏览器）：
+
+```
+src/index.ts            node half —— 空 apply，让插件进入 host cordis 配置树
+src/client/index.ts     browser half —— 两个 slot 注册
+src/client/MilestoneOverlay.tsx  shell.overlay entry（root scope）
+                                   └─ 声明 session 子槽 milestone.rail
+                                   └─ 通过 SessionProvider 桥接到会话区
+src/client/MilestoneRail.tsx      milestone.rail entry（session scope）
+                                   └─ useSession 读取会话快照
+                                   └─ DOM 锚点定位 + tick 渲染 + 跳转
+```
+
+关键机制：
+
+- **注入点**：`shell.overlay`（`kind: 'list'`，`scope: 'root'`）——全框架浮动层，附加式、点击穿透，是"悬浮 rail"的唯一正确位置。
+- **会话数据**：通过声明 session-scope 子槽 `milestone.rail`，框架自动注入 `SessionProvider`（`PropsRenderSlots` 从子槽 scope 推导），rail 组件因此拿到 `useSession` / `sessionId`。
+- **消息定位**：`useSession(s => s.chat.order)` + `s.chat.nodes.get(key)` 过滤 `kind === 'user'`；DOM 锚点 `data-chat-anchor-key`（节点 key = `13:input-message<messageId>`），scrollport 为 `[data-conversation-scroll]`。
+- **性能**：行元素按消息列表版本缓存（O(n) 重算）；scroll/resize 通过 `requestAnimationFrame` 节流。
+
+## 已知限制
+
+- 仅覆盖当前已加载的消息窗口（harness 初始加载最近 50 条事件，向上滚动触发 `loadOlder` 分页）；rail 会随分页自动更新，但更早的消息需要先滚动加载。
+- preview 从 DOM `textContent` 提取，长消息截断为 80 字。
+- 尚未实现"当前定位"高亮（P1）。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-milestone bundle patch: one loader row per package half.
+# The row `name` is this package itself, so the web modules scanner discovers
+# the browser half through the `dsh.client` declaration in package.json.
+- insert:
+    - id: milestone
+      name: dsh-milestone

package/lib/client.js

@@ -0,0 +1,209 @@
+window.__ModuleLoader__.load({
+	id: "dsh-milestone",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		//#region src/client/MilestoneOverlay.tsx
+		/**
+		* @param props - runtime share (root kit) + the narrowed renderSlot and the
+		*   framework-injected SessionProvider for the session child seat.
+		*/
+		function MilestoneOverlay({ SessionProvider, renderSlot }) {
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SessionProvider, {
+				empty: () => null,
+				children: () => renderSlot("milestone.rail", {})
+			});
+		}
+		//#endregion
+		//#region src/client/MilestoneRail.tsx
+		/**
+		* MilestoneRail: the milestone.rail entry (session scope). It reads the
+		* conversation snapshot through `useSession`, finds every user-message row in
+		* the chat flow, and renders a fixed right-side vertical scrubber: one tick
+		* per user message positioned by real rendered offset, a hover preview of the
+		* message text, and click-to-jump via the row's `data-chat-anchor-key` DOM
+		* anchor.
+		*
+		* Scroll positioning mirrors the harness chat view's own flowTop math: a row's
+		* content position is its scrollport-relative top plus the current scrollTop,
+		* normalized against scrollHeight. Ticks recompute on scroll and on any
+		* scrollport/row resize, throttled through requestAnimationFrame. Row elements
+		* are cached once per message-list revision (O(n) per recompute, not O(n^2)).
+		*/
+		const PREVIEW_LENGTH = 80;
+		/** Minimum ticks before the rail adds value. */
+		const MIN_TICKS = 2;
+		/**
+		* Find a chat row by its node key, avoiding CSS.escape pitfalls on keys that
+		* contain `<`/`>`/`:` (the node key is `12:input-message<messageId>`).
+		* Mirrors the harness ChatView's `anchorElement` scan.
+		*/
+		function findRow(key) {
+			for (const row of document.querySelectorAll("[data-chat-anchor-key]")) if (row.dataset.chatAnchorKey === key) return row;
+			return null;
+		}
+		/**
+		* @param props - session standard kit (useSession, sessionId, useProjection).
+		*/
+		function MilestoneRail({ useSession }) {
+			const order = useSession((s) => s.chat.order);
+			const nodes = useSession((s) => s.chat.nodes);
+			const userKeys = (0, react.useMemo)(() => order.filter((key) => nodes.get(key)?.kind === "user"), [order, nodes]);
+			const [ticks, setTicks] = (0, react.useState)([]);
+			const [railBox, setRailBox] = (0, react.useState)(null);
+			const [hover, setHover] = (0, react.useState)(null);
+			(0, react.useLayoutEffect)(() => {
+				if (userKeys.length < MIN_TICKS) {
+					setTicks([]);
+					setRailBox(null);
+					return;
+				}
+				const scrollport = document.querySelector("[data-conversation-scroll]");
+				if (scrollport === null) return;
+				const rowCache = /* @__PURE__ */ new Map();
+				for (const key of userKeys) {
+					const row = findRow(key);
+					if (row !== null) rowCache.set(key, row);
+				}
+				const compute = () => {
+					const sp = scrollport.getBoundingClientRect();
+					const total = scrollport.scrollHeight;
+					const next = [];
+					for (const key of userKeys) {
+						let row = rowCache.get(key);
+						if (row === void 0 || !row.isConnected) {
+							const fresh = findRow(key);
+							if (fresh === null) continue;
+							row = fresh;
+							rowCache.set(key, fresh);
+						}
+						const contentTop = row.getBoundingClientRect().top - sp.top + scrollport.scrollTop;
+						const top = total > 0 ? contentTop / total * 100 : 0;
+						next.push({
+							key,
+							top: Math.min(99, Math.max(0, top))
+						});
+					}
+					setTicks(next);
+					setRailBox({
+						top: sp.top,
+						height: sp.height,
+						right: Math.max(4, window.innerWidth - sp.right)
+					});
+				};
+				compute();
+				let raf = 0;
+				const schedule = () => {
+					cancelAnimationFrame(raf);
+					raf = requestAnimationFrame(compute);
+				};
+				scrollport.addEventListener("scroll", schedule, { passive: true });
+				const observer = new ResizeObserver(schedule);
+				observer.observe(scrollport);
+				for (const row of rowCache.values()) observer.observe(row);
+				return () => {
+					cancelAnimationFrame(raf);
+					scrollport.removeEventListener("scroll", schedule);
+					observer.disconnect();
+				};
+			}, [userKeys]);
+			if (railBox === null || ticks.length < MIN_TICKS) return null;
+			const jump = (key) => {
+				findRow(key)?.scrollIntoView({
+					behavior: "smooth",
+					block: "start"
+				});
+			};
+			const onEnter = (tick) => {
+				const preview = findRow(tick.key)?.textContent?.trim().slice(0, PREVIEW_LENGTH) ?? "";
+				setHover({
+					key: tick.key,
+					preview,
+					top: tick.top
+				});
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: {
+					position: "fixed",
+					top: railBox.top,
+					right: railBox.right,
+					height: railBox.height,
+					width: 20,
+					pointerEvents: "auto",
+					zIndex: 100
+				},
+				"aria-label": "Conversation milestones",
+				children: [ticks.map((tick) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					style: {
+						position: "absolute",
+						top: `${tick.top}%`,
+						right: 6,
+						width: 8,
+						height: 3,
+						borderRadius: 2,
+						border: "none",
+						padding: 0,
+						background: hover?.key === tick.key ? "#4d7cfe" : "rgba(120, 130, 150, 0.5)",
+						cursor: "pointer"
+					},
+					onMouseEnter: () => onEnter(tick),
+					onMouseLeave: () => setHover(null),
+					onClick: () => jump(tick.key),
+					"aria-label": "Jump to user message"
+				}, tick.key)), hover !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					style: {
+						position: "fixed",
+						right: railBox.right + 22,
+						top: railBox.top + railBox.height * hover.top / 100,
+						transform: "translateY(-50%)",
+						maxWidth: 280,
+						padding: "8px 10px",
+						background: "rgba(20, 24, 32, 0.95)",
+						color: "#e6e8ee",
+						borderRadius: 6,
+						fontSize: 12,
+						lineHeight: 1.5,
+						whiteSpace: "pre-wrap",
+						wordBreak: "break-word",
+						boxShadow: "0 4px 16px rgba(0, 0, 0, 0.3)",
+						zIndex: 101
+					},
+					children: hover.preview
+				})]
+			});
+		}
+		//#endregion
+		//#region src/client/index.ts
+		/** Required services (cordis fiber inject). */
+		const inject = ["slots"];
+		/**
+		* Register the overlay and rail once their slot declarations are on the
+		* ledger. The overlay registers directly against the shipped shell.overlay
+		* declaration; the rail registers against our own child declaration, which
+		* appears exactly when the overlay entry mounts.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.slots.inject("shell.overlay", () => ctx.slots.register({
+				name: "shell.overlay",
+				id: "milestone",
+				order: 100,
+				children: { "milestone.rail": {
+					kind: "single",
+					scope: "session"
+				} }
+			}, MilestoneOverlay));
+			ctx.slots.inject("milestone.rail", () => ctx.slots.register({ name: "milestone.rail" }, MilestoneRail));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,10 @@
+//#region src/index.ts
+/**
+* dsh-milestone node half. Pure UI plugin: the empty apply exists so the
+* plugin appears in the host cordis.yml / Loader (load and lifecycle follow
+* the host); the browser half ships via exports["./client"], discovered
+* through the package.json dsh.client declaration.
+*/
+function apply() {}
+//#endregion
+export { apply };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "dsh-milestone",
+  "version": "0.1.0",
+  "description": "Conversation milestone rail for DeepSeek Harness: a right-side vertical scrubber showing one tick per user message — hover to preview, click to jump.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-layout"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
+  "license": "MIT",
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "conversation",
+    "navigation"
+  ],
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "0.22.2",
+    "typescript": "^6.0.3"
+  }
+}