dsh-milestone 0.3.1 → 0.4.0

package/README.md

@@ -33,6 +33,9 @@
 - **站内搜索** —— 搜索框过滤圆点，匹配的是**完整消息内容**（不是 80 字摘要），实时显示命中数 N/M，回车跳到下一个匹配，Esc 一键清空。
 - **当前位置高亮** —— 滚动会话时，离你视口最近的那条提问会亮起白环，永远知道「读到哪了」。
 - **加载更早** —— 历史没加载完时，顶部出现「···」按钮，点一下继续加载，并提示当前已显示多少条。
+- **收藏书签** —— 悬停任意圆点可点星收藏，刷新后仍保留；顶部「★」一键只看收藏，把一次性跳转变反复回访。
+- **键盘导航** —— 里程碑条是一个焦点组件：↑↓ 移动、回车跳转、Home/End 首尾，全程不用鼠标。
+- **状态徽章** —— 圆点自动标出轮次健康状态：出错红环、达到上限黄环、重试橙环、运行中/等待输入蓝/黄脉冲。
 - **固定间距** —— 圆点**等距排列**，不随对话长度挤压变形，永远点得准。
 - **蓝色渐变** —— 最新最深、最早最浅，一眼看清提问的先后顺序，像 Git 提交图。
 - **滚轮滑动** —— 长会话圆点超出可视区时，鼠标在里程碑条上滚轮即可滑动选点。
@@ -79,7 +82,8 @@ shell.overlay (root scope)
 ```
 
 - **注入点**：`shell.overlay` —— 全框架浮动层，附加式、点击穿透，不影响任何现有 UI。
-- **数据源**：`chat.order` + `chat.nodes`（user 消息）+ `chat.timeline`（turn 元数据）+ `hasMore`/`loadingOlder`（分页状态）+ `loadOlder`（经 inject face 注入）。
+- **数据源**：`chat.order` + `chat.nodes`（user 消息 + `turn-error`/`turn-max-tokens`/`model-retry` 节点）+ `chat.timeline`（turn 元数据）+ `hasMore`/`loadingOlder`（分页）+ `running`/`pending`（徽章）+ `loadOlder`（inject face）。
+- **书签持久化**：harness `store.persist`（每会话 localStorage，key `dsh-milestone.bookmarks.<sessionId>`），经 `defineStore` 引擎读写。
 - **跳转**：DOM 锚点 `data-chat-anchor-key`，`scrollIntoView` 平滑定位。
 - **纯函数**：搜索过滤 / 位置计算 / 圆点状态都在 `rail-logic.ts` 纯函数里，单测覆盖。
 
@@ -87,6 +91,9 @@ shell.overlay (root scope)
 
 - 搜索范围 = 当前已加载的消息窗口（初始 50 条；点顶部「···」加载更早，更早的历史需先加载进来才能被搜到）。
 - TTFT / tokens/秒 依赖 turn 位置数据，窗口外或未完成的 turn 不显示（自动隐藏）。
+- 徽章的瞬态状态（运行中/等待输入）只点亮**最新一条可见提问**——若运行中/等待输入的轮次其提问在窗口外，则无脉冲。
+- 书签按**会话**隔离（不跨会话共享）。
+- 尚无全局快捷键聚焦里程碑条（需 Tab 键切换到）。
 
 ## License
 

package/lib/client.js

@@ -6,6 +6,7 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react_jsx_runtime = require("react/jsx-runtime");
 		let react = require("react");
+		let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
 		//#region src/client/MilestoneOverlay.tsx
 		/**
 		* @param props - runtime share (root kit) + the narrowed renderSlot and the
@@ -18,6 +19,139 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/client/badge-logic.ts
+		/**
+		* Derive the badge for one mark.
+		*
+		* Precedence: error > max-tokens > retry > running > awaiting. Node-derived
+		* badges ('turn-error' -> error, 'turn-max-tokens' -> max-tokens,
+		* 'model-retry' -> retry) fire regardless of `lastMark`; the transient badges
+		* (running, awaiting) only apply to the newest mark. Callers must already
+		* exclude cancelled retries — a bare 'model-retry' kind is treated as retry.
+		*
+		* @param input - the mark's snapshot signals.
+		* @returns the winning badge kind, or null when no signal applies.
+		*/
+		function deriveBadge(input) {
+			if (input.nodeKinds.includes("turn-error")) return "error";
+			if (input.nodeKinds.includes("turn-max-tokens")) return "max-tokens";
+			if (input.nodeKinds.includes("model-retry")) return "retry";
+			if (input.lastMark) {
+				if (input.running) return "running";
+				if (input.awaitingInput) return "awaiting";
+			}
+			return null;
+		}
+		/** Ring colors and pulse flag per badge kind; running/awaiting pulse. */
+		const RING_STYLES = {
+			error: {
+				color: "#ef4444",
+				pulse: false
+			},
+			"max-tokens": {
+				color: "#f59e0b",
+				pulse: false
+			},
+			retry: {
+				color: "#f97316",
+				pulse: false
+			},
+			running: {
+				color: "#4d7cfe",
+				pulse: true
+			},
+			awaiting: {
+				color: "#f59e0b",
+				pulse: true
+			}
+		};
+		/**
+		* Style tokens for a badge kind.
+		* @param badge - the derived badge kind.
+		* @returns the ring color and whether the dot should pulse.
+		*/
+		function badgeRingStyle(badge) {
+			return RING_STYLES[badge];
+		}
+		//#endregion
+		//#region src/client/bookmark-logic.ts
+		/**
+		* Pure bookmark logic for the milestone rail: membership, immutable
+		* append/remove toggling, bookmark filtering of a mark list, and count.
+		*
+		* All functions are side-effect free (no React, no DOM) so the rail component
+		* can consume them directly and tests can exercise them in isolation. The
+		* persisted store engine lives in bookmarkStore.ts; this module only shapes
+		* values.
+		*/
+		/**
+		* Whether a key is currently bookmarked.
+		* @param keys - the bookmark key list (in toggle order).
+		* @param key - the key to look up.
+		* @returns true when the key is present.
+		*/
+		function isBookmarked(keys, key) {
+			return keys.includes(key);
+		}
+		/**
+		* Immutable toggle: append the key when it is not bookmarked, remove it when
+		* it is. Never mutates the input; returns a fresh list (order preserved).
+		* @param keys - the bookmark key list (in toggle order).
+		* @param key - the key to flip.
+		* @returns a new list with the key toggled.
+		*/
+		function toggleKey(keys, key) {
+			return isBookmarked(keys, key) ? keys.filter((k) => k !== key) : [...keys, key];
+		}
+		/**
+		* Filter a mark list down to the bookmarked marks.
+		* @param marks - marks in rail order (only `key` is consulted).
+		* @param bookmarked - the bookmark key list.
+		* @returns `visible` (ascending indices of marks whose key is bookmarked;
+		* empty whenever there are no bookmarks) and `isFiltered` (true exactly when
+		* any bookmark exists — callers treat it as "filter active").
+		*/
+		function filterByBookmarks(marks, bookmarked) {
+			if (bookmarked.length === 0) return {
+				visible: [],
+				isFiltered: false
+			};
+			const set = new Set(bookmarked);
+			return {
+				visible: marks.reduce((acc, mark, i) => {
+					if (set.has(mark.key)) acc.push(i);
+					return acc;
+				}, []),
+				isFiltered: true
+			};
+		}
+		//#endregion
+		//#region src/client/rail-keyboard.ts
+		/**
+		* Pure roving-tabindex index math for the milestone rail.
+		*
+		* The dots list becomes a single roving-tabindex widget (ArrowUp/Down moves
+		* focus, Home/End jumps to first/last). This module only owns the pure index
+		* arithmetic; the widget wiring lives in the component.
+		*/
+		/**
+		* Move `current` by `delta` (1 = forward, -1 = backward), wrapping around
+		* `[0, count - 1]`. Returns `-1` when there are no focusable dots.
+		*/
+		function nextFocusIndex(current, count, delta) {
+			if (count <= 0) return -1;
+			return (current + delta + count) % count;
+		}
+		/**
+		* Clamp `current` into `[0, count - 1]` — e.g. when the visible dot list
+		* shrinks and the focused index no longer exists. Returns `-1` when there
+		* are no focusable dots.
+		*/
+		function clampIndex(current, count) {
+			if (count <= 0) return -1;
+			return Math.min(Math.max(current, 0), count - 1);
+		}
+		//#endregion
 		//#region src/client/rail-logic.ts
 		/**
 		* Extract the FULL plain text of a ContentBlock[] payload: the `text` of every
@@ -233,6 +367,123 @@ window.__ModuleLoader__.load({
 			})] });
 		}
 		//#endregion
+		//#region src/client/MilestoneRailTooltip.tsx
+		/**
+		* @param props - the hovered mark + bookmark wiring (see {@link MilestoneRailTooltipProps}).
+		*/
+		function MilestoneRailTooltip({ hover, bookmarked, onToggleBookmark, onMouseEnter, onMouseLeave, panelRight }) {
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				onMouseEnter,
+				onMouseLeave,
+				style: {
+					position: "fixed",
+					right: panelRight,
+					top: hover.top,
+					transform: "translateY(-50%)",
+					maxWidth: 300,
+					minWidth: 180,
+					padding: "8px 12px",
+					background: "rgba(20, 24, 32, 0.96)",
+					color: "#e6e8ee",
+					borderRadius: 8,
+					fontSize: 12,
+					lineHeight: 1.6,
+					whiteSpace: "pre-wrap",
+					wordBreak: "break-word",
+					boxShadow: "0 6px 20px rgba(0, 0, 0, 0.4)",
+					zIndex: 101,
+					pointerEvents: "auto"
+				},
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							display: "flex",
+							alignItems: "center",
+							gap: 8,
+							color: "#9aa4b8",
+							fontSize: 11,
+							marginBottom: 4
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: [
+								"第 ",
+								hover.index + 1,
+								" / ",
+								hover.total,
+								" 条"
+							] }),
+							hover.turnLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.turnLabel }),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								"data-star": true,
+								"aria-label": "收藏此消息",
+								"aria-pressed": bookmarked,
+								"data-starred": bookmarked ? "true" : void 0,
+								onClick: (e) => {
+									e.stopPropagation();
+									onToggleBookmark();
+								},
+								style: {
+									marginLeft: "auto",
+									width: 22,
+									height: 22,
+									flexShrink: 0,
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "center",
+									background: "transparent",
+									border: "none",
+									padding: 0,
+									cursor: "pointer",
+									color: bookmarked ? "#ffd166" : "#8b96ab"
+								},
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+									width: "13",
+									height: "13",
+									viewBox: "0 0 24 24",
+									fill: bookmarked ? "currentColor" : "none",
+									stroke: "currentColor",
+									strokeWidth: "2",
+									strokeLinejoin: "round",
+									"aria-hidden": "true",
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "m12 2 3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" })
+								})
+							})
+						]
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						style: { color: "#c7cede" },
+						children: hover.mark.preview !== "" ? hover.mark.preview : "（无文本）"
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							display: "flex",
+							flexWrap: "wrap",
+							gap: 8,
+							color: "#8b96ab",
+							fontSize: 11,
+							marginTop: 4
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatRelativeTime(hover.mark.time) }),
+							hover.durationLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: ["用时 ", hover.durationLabel] }),
+							hover.reasonLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.reasonLabel }),
+							hover.ttftLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: ["首字 ", hover.ttftLabel] }),
+							hover.tpsLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.tpsLabel })
+						]
+					})
+				]
+			});
+		}
+		/** Relative wall-clock label for a Unix-epoch-ms timestamp. */
+		function formatRelativeTime(time) {
+			const diff = Date.now() - time;
+			if (diff < 6e4) return "刚刚";
+			if (diff < 36e5) return `${Math.floor(diff / 6e4)} 分钟前`;
+			if (diff < 864e5) return `${Math.floor(diff / 36e5)} 小时前`;
+			return `${Math.floor(diff / 864e5)} 天前`;
+		}
+		//#endregion
 		//#region src/client/useCurrentAnchor.ts
 		/**
 		* useCurrentAnchor: tracks which user-message row sits at/just above the
@@ -332,6 +583,21 @@ window.__ModuleLoader__.load({
 		/** Minimum user messages before the rail adds value. */
 		const MIN_MARKS = 2;
 		const PREVIEW_LENGTH = 80;
+		/** Stable no-bookmarks fallback for render paths without the store seat. */
+		const NO_BOOKMARKS = [];
+		/** Stable no-kinds fallback for marks whose turn carries no badge nodes. */
+		const NO_KINDS = [];
+		/**
+		* Self-contained pulse keyframes for the transient badges (running/awaiting):
+		* an expanding currentColor ring on box-shadow plus an opacity beat, driven by
+		* `animation` on the badge ring span (kept in an inline <style> so the plugin
+		* stays zero-asset).
+		*/
+		const BADGE_PULSE_CSS = `@keyframes milestone-badge-pulse {
+  0% { box-shadow: 0 0 0 0 currentColor; opacity: 0.85 }
+  70% { box-shadow: 0 0 0 5px transparent; opacity: 0.35 }
+  100% { box-shadow: 0 0 0 0 transparent; opacity: 0.85 }
+}`;
 		/** Visual dot diameter (px). */
 		const DOT_SIZE = 12;
 		/** Hit area per dot (px) — larger than the dot for comfortable clicking. */
@@ -352,14 +618,6 @@ window.__ModuleLoader__.load({
 		function extractPreview(content) {
 			return extractText(content).slice(0, PREVIEW_LENGTH);
 		}
-		/** Relative wall-clock label for a Unix-epoch-ms timestamp. */
-		function formatRelativeTime(time) {
-			const diff = Date.now() - time;
-			if (diff < 6e4) return "刚刚";
-			if (diff < 36e5) return `${Math.floor(diff / 6e4)} 分钟前`;
-			if (diff < 864e5) return `${Math.floor(diff / 36e5)} 小时前`;
-			return `${Math.floor(diff / 864e5)} 天前`;
-		}
 		/** Compact duration label (ms). */
 		function formatDuration(ms) {
 			if (ms < 1e3) return `${ms}ms`;
@@ -385,14 +643,17 @@ window.__ModuleLoader__.load({
 			return data.get("turn-tail");
 		}
 		/**
-		* @param props - session standard kit (useSession, sessionId, useProjection).
+		* @param props - session standard kit (useSession, sessionId, useProjection),
+		* the injected loadOlder action, and the bookmarks store pair (useStore +
+		* actions, injected by the framework from the declared store seat).
 		*/
-		function MilestoneRail({ useSession, loadOlder }) {
+		function MilestoneRail({ useSession, loadOlder, useStore, actions }) {
 			const order = useSession((s) => s.chat.order);
 			const nodes = useSession((s) => s.chat.nodes);
 			const timeline = useSession((s) => s.chat.timeline);
 			const hasMore = useSession((s) => s.hasMore);
 			const loadingOlder = useSession((s) => s.loadingOlder);
+			const bookmarkedKeys = useStore?.((s) => s.keys) ?? NO_BOOKMARKS;
 			const marks = (0, react.useMemo)(() => {
 				const result = [];
 				for (const key of order) {
@@ -411,6 +672,22 @@ window.__ModuleLoader__.load({
 				}
 				return result;
 			}, [order, nodes]);
+			const kindsByTurn = (0, react.useMemo)(() => {
+				const result = /* @__PURE__ */ new Map();
+				for (const node of nodes.values()) {
+					if (node.kind !== "turn-error" && node.kind !== "turn-max-tokens" && node.kind !== "model-retry") continue;
+					if (node.kind === "model-retry") {
+						if (node.data?.retryState === "cancelled") continue;
+					}
+					if (node.location.kind !== "turn" && node.location.kind !== "step") continue;
+					const kinds = result.get(node.location.turn.turn) ?? [];
+					kinds.push(node.kind);
+					result.set(node.location.turn.turn, kinds);
+				}
+				return result;
+			}, [order, nodes]);
+			const running = useSession((s) => s.running);
+			const awaitingInput = useSession((s) => s.pending).length > 0;
 			const [railBox, setRailBox] = (0, react.useState)(null);
 			const [hover, setHover] = (0, react.useState)(null);
 			const [search, setSearch] = (0, react.useState)({
@@ -418,8 +695,19 @@ window.__ModuleLoader__.load({
 				activePos: 0,
 				panelOpen: false
 			});
+			const [bookmarksOnly, setBookmarksOnly] = (0, react.useState)(false);
+			const [focusIndex, setFocusIndex] = (0, react.useState)(0);
+			const listRef = (0, react.useRef)(null);
 			const currentKey = useCurrentAnchor(order);
-			const { matches } = (0, react.useMemo)(() => filterMarks(marks, search.query), [marks, search.query]);
+			const displayMarks = (0, react.useMemo)(() => {
+				if (!bookmarksOnly) return marks;
+				return filterByBookmarks(marks, bookmarkedKeys).visible.map((i) => marks[i]);
+			}, [
+				bookmarksOnly,
+				marks,
+				bookmarkedKeys
+			]);
+			const { matches } = (0, react.useMemo)(() => filterMarks(displayMarks, search.query), [displayMarks, search.query]);
 			const hasQuery = search.query.trim() !== "";
 			const activeMarkIndex = hasQuery && matches.length > 0 ? matches[Math.min(search.activePos, matches.length - 1)] : -1;
 			(0, react.useLayoutEffect)(() => {
@@ -446,6 +734,9 @@ window.__ModuleLoader__.load({
 					window.removeEventListener("resize", compute);
 				};
 			}, [marks.length]);
+			(0, react.useLayoutEffect)(() => {
+				setFocusIndex((f) => clampIndex(f, displayMarks.length));
+			}, [displayMarks.length]);
 			if (railBox === null || marks.length < MIN_MARKS) return null;
 			const jump = (key) => {
 				findRow(key)?.scrollIntoView({
@@ -482,12 +773,50 @@ window.__ModuleLoader__.load({
 					...s,
 					activePos: next
 				}));
-				jump(marks[matches[next]].key);
+				jump(displayMarks[matches[next]].key);
 			};
 			const onSearchKeyDown = (e) => {
 				if (e.key === "Enter") advanceMatch();
 				if (e.key === "Escape") closeSearch();
 			};
+			/** Focus the dot at `index` (no-op while the list is unmounted). */
+			const focusDotAt = (index) => {
+				listRef.current?.querySelectorAll("[data-rail-dot]")[index]?.focus();
+			};
+			/** Tab lands on the list itself: hand focus to the dot owning the tab stop. */
+			const onListFocus = (e) => {
+				if (e.target !== e.currentTarget) return;
+				focusDotAt(clampIndex(focusIndex, displayMarks.length));
+			};
+			/**
+			* Roving-tabindex keys: ArrowDown/ArrowUp move focus (wrapping), Home/End
+			* jump to first/last. Enter/Space are deliberately NOT handled — the dots
+			* are real buttons, so native activation fires the jump click untouched
+			* (preventDefault here would swallow it).
+			*/
+			const onListKeyDown = (e) => {
+				const count = displayMarks.length;
+				let next = null;
+				switch (e.key) {
+					case "ArrowDown":
+						next = nextFocusIndex(focusIndex, count, 1);
+						break;
+					case "ArrowUp":
+						next = nextFocusIndex(focusIndex, count, -1);
+						break;
+					case "Home":
+						next = 0;
+						break;
+					case "End":
+						next = count - 1;
+						break;
+					default: return;
+				}
+				e.preventDefault();
+				const target = clampIndex(next, count);
+				setFocusIndex(target);
+				focusDotAt(target);
+			};
 			const buildHover = (mark, index) => {
 				const turn = mark.turn !== void 0 ? timeline.turns.get(mark.turn) : void 0;
 				let durationLabel = null;
@@ -509,7 +838,7 @@ window.__ModuleLoader__.load({
 				return {
 					mark,
 					index,
-					total: marks.length,
+					total: displayMarks.length,
 					turnLabel: mark.turn !== void 0 ? `第 ${mark.turn} 轮` : null,
 					durationLabel,
 					reasonLabel,
@@ -517,6 +846,18 @@ window.__ModuleLoader__.load({
 					tpsLabel
 				};
 			};
+			/**
+			* T10: flip a mark's bookmark in the persisted store. The store action is
+			* the write path (the engine persists synchronously). The hover re-assert
+			* forces a re-render so the star reflects the toggled state — production
+			* re-renders through the framework's uSES-bound useStore; the component
+			* test harness injects an unsubscribed selector, so this local re-render is
+			* what syncs the DOM there. Both paths converge on the same fresh snapshot.
+			*/
+			const onToggleBookmark = (key) => {
+				actions?.toggle(key);
+				setHover((h) => h === null ? h : { ...h });
+			};
 			const showLoadOlder = hasMore && marks.length >= MIN_MARKS;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: {
@@ -532,6 +873,7 @@ window.__ModuleLoader__.load({
 				},
 				"aria-label": "会话里程碑",
 				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", { children: BADGE_PULSE_CSS }),
 					showLoadOlder && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 						type: "button",
 						"data-load-older": true,
@@ -560,13 +902,45 @@ window.__ModuleLoader__.load({
 						},
 						children: "···"
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						"data-bookmarks-toggle": true,
+						"aria-label": "只看收藏",
+						"aria-pressed": bookmarksOnly,
+						"data-active": bookmarksOnly ? "true" : void 0,
+						onClick: () => setBookmarksOnly((v) => !v),
+						style: {
+							width: DOT_HIT,
+							height: DOT_HIT,
+							flexShrink: 0,
+							display: "flex",
+							alignItems: "center",
+							justifyContent: "center",
+							background: bookmarksOnly ? "rgba(77, 124, 254, 0.18)" : "transparent",
+							border: "none",
+							padding: 0,
+							cursor: "pointer",
+							color: bookmarksOnly ? "#9db8ff" : "#8b96ab"
+						},
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+							width: "13",
+							height: "13",
+							viewBox: "0 0 24 24",
+							fill: bookmarksOnly ? "currentColor" : "none",
+							stroke: "currentColor",
+							strokeWidth: "2",
+							strokeLinejoin: "round",
+							"aria-hidden": "true",
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "m12 2 3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z" })
+						})
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(RailSearchUi, {
 						panelTop: railBox.top,
 						panelRight: railBox.right + DOT_HIT + 8,
 						query: search.query,
 						panelOpen: search.panelOpen,
 						matches: matches.length,
-						total: marks.length,
+						total: displayMarks.length,
 						onToggle: () => setSearch((s) => ({
 							...s,
 							panelOpen: !s.panelOpen
@@ -576,6 +950,12 @@ window.__ModuleLoader__.load({
 						onClear: clearSearch
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						ref: listRef,
+						"data-rail-list": true,
+						tabIndex: 0,
+						"aria-label": "会话里程碑列表",
+						onFocus: onListFocus,
+						onKeyDown: onListKeyDown,
 						style: {
 							flex: 1,
 							minHeight: 0,
@@ -587,7 +967,8 @@ window.__ModuleLoader__.load({
 							padding: "6px 0",
 							scrollbarWidth: "none"
 						},
-						children: marks.map((mark, i) => {
+						children: displayMarks.map((mark, i) => {
+							const bookmarked = isBookmarked(bookmarkedKeys, mark.key);
 							const dotState = markState({
 								key: mark.key,
 								hasQuery,
@@ -597,6 +978,13 @@ window.__ModuleLoader__.load({
 							});
 							const isHovered = hover?.mark.key === mark.key;
 							const boxShadow = isHovered ? "0 0 0 3px rgba(77, 124, 254, 0.35)" : dotState === "active" ? "0 0 0 3px rgba(255, 255, 255, 0.9)" : dotState === "current" ? "0 0 0 3px rgba(255, 255, 255, 0.75)" : "none";
+							const badge = deriveBadge({
+								nodeKinds: mark.turn === void 0 ? NO_KINDS : kindsByTurn.get(mark.turn) ?? NO_KINDS,
+								lastMark: i === displayMarks.length - 1,
+								running,
+								awaitingInput
+							});
+							const ringStyle = badge === null ? null : badgeRingStyle(badge);
 							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
 								style: {
@@ -618,84 +1006,50 @@ window.__ModuleLoader__.load({
 										top: rect.top + rect.height / 2
 									});
 								},
-								onMouseLeave: () => setHover(null),
 								onClick: () => jump(mark.key),
+								"data-rail-dot": true,
+								tabIndex: focusIndex === i ? 0 : -1,
+								onFocus: () => setFocusIndex(i),
 								"aria-label": `跳转到第 ${i + 1} 条消息`,
 								"aria-current": dotState === "active" ? "true" : void 0,
 								"data-current": dotState === "current" ? "true" : void 0,
 								"data-dimmed": dotState === "dimmed" ? "true" : void 0,
-								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: {
-									width: DOT_SIZE,
-									height: DOT_SIZE,
-									borderRadius: "50%",
-									background: dotColor(i, marks.length),
-									boxShadow,
-									transition: "transform 120ms ease, opacity 120ms ease",
-									transform: `scale(${isHovered ? 1.35 : dotState === "active" || dotState === "current" ? 1.25 : 1})`,
-									opacity: isHovered || dotState !== "dimmed" ? 1 : .22
-								} })
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									style: {
+										position: "relative",
+										width: DOT_SIZE,
+										height: DOT_SIZE,
+										borderRadius: "50%",
+										background: dotColor(i, marks.length),
+										boxShadow,
+										transition: "transform 120ms ease, opacity 120ms ease",
+										transform: `scale(${isHovered ? 1.35 : dotState === "active" || dotState === "current" ? 1.25 : 1})`,
+										opacity: isHovered || dotState !== "dimmed" ? 1 : .22
+									},
+									"data-bookmarked": bookmarked ? "true" : void 0,
+									children: ringStyle !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+										"data-badge": badge,
+										style: {
+											position: "absolute",
+											inset: -3,
+											borderRadius: "50%",
+											border: `2px solid ${ringStyle.color}`,
+											color: ringStyle.color,
+											pointerEvents: "none",
+											animation: ringStyle.pulse ? "milestone-badge-pulse 1.4s ease-out infinite" : void 0
+										}
+									})
+								})
 							}, mark.key);
 						})
 					}),
-					hover !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						style: {
-							position: "fixed",
-							right: railBox.right + DOT_HIT + 8,
-							top: hover.top,
-							transform: "translateY(-50%)",
-							maxWidth: 300,
-							minWidth: 180,
-							padding: "8px 12px",
-							background: "rgba(20, 24, 32, 0.96)",
-							color: "#e6e8ee",
-							borderRadius: 8,
-							fontSize: 12,
-							lineHeight: 1.6,
-							whiteSpace: "pre-wrap",
-							wordBreak: "break-word",
-							boxShadow: "0 6px 20px rgba(0, 0, 0, 0.4)",
-							zIndex: 101,
-							pointerEvents: "none"
-						},
-						children: [
-							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-								style: {
-									display: "flex",
-									gap: 8,
-									color: "#9aa4b8",
-									fontSize: 11,
-									marginBottom: 4
-								},
-								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: [
-									"第 ",
-									hover.index + 1,
-									" / ",
-									hover.total,
-									" 条"
-								] }), hover.turnLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.turnLabel })]
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-								style: { color: "#c7cede" },
-								children: hover.mark.preview !== "" ? hover.mark.preview : "（无文本）"
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-								style: {
-									display: "flex",
-									flexWrap: "wrap",
-									gap: 8,
-									color: "#8b96ab",
-									fontSize: 11,
-									marginTop: 4
-								},
-								children: [
-									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatRelativeTime(hover.mark.time) }),
-									hover.durationLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: ["用时 ", hover.durationLabel] }),
-									hover.reasonLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.reasonLabel }),
-									hover.ttftLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", { children: ["首字 ", hover.ttftLabel] }),
-									hover.tpsLabel !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: hover.tpsLabel })
-								]
-							})
-						]
+					hover !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MilestoneRailTooltip, {
+						panelRight: railBox.right + DOT_HIT + 8,
+						hover,
+						bookmarked: isBookmarked(bookmarkedKeys, hover.mark.key),
+						onToggleBookmark: () => onToggleBookmark(hover.mark.key),
+						onMouseEnter: () => setHover((h) => h),
+						onMouseLeave: () => setHover(null)
 					}),
 					showLoadOlder && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						"data-window-hint": true,
@@ -721,6 +1075,36 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/client/bookmarkStore.ts
+		/**
+		* Persisted per-session bookmarks store for the milestone rail.
+		*
+		* A thin declarative shell over the harness snapshot-store engine: pure
+		* draft-mutator actions, persisted to localStorage under the key
+		* `dsh-milestone.bookmarks` (+ `.${scopeKey}` for session-scope instances,
+		* resolved by the engine's `create(scopeKey)`). Consumers must call the
+		* FACTORY (never a module-level handle — module-cache identity is a disguised
+		* singleton across plugin reloads).
+		*/
+		/**
+		* Declare the bookmarks store handle. Returns a fresh handle per call; the
+		* framework (or tests) create per-session instances via `create(scopeKey)`.
+		*/
+		function createBookmarksStore() {
+			return (0, _deepseek_ai_dsh_client_runtime_client.defineStore)({
+				init: () => ({ keys: [] }),
+				persist: "dsh-milestone.bookmarks",
+				actions: {
+					toggle: (draft, key) => {
+						draft.keys = toggleKey(draft.keys, key);
+					},
+					clear: (draft) => {
+						draft.keys = [];
+					}
+				}
+			});
+		}
+		//#endregion
 		//#region src/client/railInject.ts
 		/**
 		* Wrap a session-bound `loadOlder` call into a safe action closure.
@@ -763,6 +1147,7 @@ window.__ModuleLoader__.load({
 			}, MilestoneOverlay));
 			ctx.slots.inject("milestone.rail", () => ctx.slots.register({
 				name: "milestone.rail",
+				store: createBookmarksStore,
 				inject: (sessionId) => ({ loadOlder: createLoadOlder(ctx.sessions, sessionId) })
 			}, MilestoneRail));
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-milestone",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Git-style milestone timeline for DeepSeek Harness: hover for metadata, click to jump to any message. 会话里程碑导航条：圆点时间线，定位并跳转到每条提问。",
   "type": "module",
   "main": "lib/index.js",