@hpyperry/dsh-ref-lib 0.8.0 → 0.9.0

package/lib/client.js

@@ -8,12 +8,21 @@ window.__ModuleLoader__.load({
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		//#region src/validate.ts
-		/** 校验一个未知对象是否为合法条目（宽松：仅要求 id/path 字符串、note 可选字符串）。 */
+		/** 可用性字面量集合（status 字段合法值）。 */
+		const AVAILABILITY_VALUES = /* @__PURE__ */ new Set([
+			"available",
+			"missing",
+			"not-directory"
+		]);
+		/** 校验一个未知对象是否为合法条目（宽松：id/path 必填字符串，note/status/checkedAt 可选且类型正确）。 */
 		function isRefLibEntry(value) {
 			if (typeof value !== "object" || value === null) return false;
-			const { id, path, note } = value;
+			const { id, path, note, status, checkedAt } = value;
 			if (typeof id !== "string" || typeof path !== "string") return false;
-			return note === void 0 || typeof note === "string";
+			if (note !== void 0 && typeof note !== "string") return false;
+			if (status !== void 0 && (typeof status !== "string" || !AVAILABILITY_VALUES.has(status))) return false;
+			if (checkedAt !== void 0 && (typeof checkedAt !== "number" || !Number.isFinite(checkedAt))) return false;
+			return true;
 		}
 		//#endregion
 		//#region src/client/data.ts
@@ -79,571 +88,18 @@ window.__ModuleLoader__.load({
 			return idx === -1 ? trimmed : trimmed.slice(idx + 1);
 		}
 		//#endregion
-		//#region src/client/RefLibBrowser.tsx
-		/**
-		* 应用内目录浏览器（browse 后端可用时，「选择目录」的落地实现）。
-		*
-		* 为什么需要它：v6 起 profile 把 directory-picker 从 -auto（本机解析为 native，
-		* OS 对话框硬编码英文且每次拉 osascript 进程）切换为 -browse 后，
-		* `host.pickDirectory`（native 专用 RPC）不再可用；本组件用 `listDirectory`
-		* （Node stdlib 列目录，zh/en 本地化、无 OS 进程）提供等价的目录选择：
-		* 面包屑 + 路径编辑 + 子目录列表，点击下行进入，「选择此目录」把当前层级添加为
-		* 参考库。简化为单列（与官方 DirectoryBrowser 的 Miller 双列相比），
-		* 但覆盖添加参考库的核心路径。
-		* @module @hpyperry/dsh-ref-lib/src/client/RefLibBrowser
-		*/
-		/** 面包屑展示：主目录子树内以本地化 Home 开头；之外显示完整祖先链。 */
-		function displayCrumbs(listing, homeLabel) {
-			const homeIndex = listing.crumbs.findIndex((crumb) => crumb.path === listing.home);
-			if (homeIndex === -1) return listing.crumbs;
-			const tail = listing.crumbs.slice(homeIndex + 1);
-			return [{
-				name: homeLabel,
-				path: listing.home,
-				hidden: false
-			}, ...tail];
-		}
-		/** 平台分隔符（由宿主主目录推断，绝不从键入文本推断）。 */
-		function separatorOf(listing) {
-			return listing.home.includes("\\") ? "\\" : "/";
-		}
-		/**
-		* 渲染应用内目录浏览器。
-		* @param props - 见 {@link RefLibBrowserProps}。
-		* @returns 对话框元素（关闭时 Modal 返回 null）。
-		*/
-		function RefLibBrowser(props) {
-			const { open, onClose, listDirectory, t, onOpen } = props;
-			const [listing, setListing] = (0, react.useState)(null);
-			const [loading, setLoading] = (0, react.useState)(false);
-			const [error, setError] = (0, react.useState)(null);
-			const [pathDraft, setPathDraft] = (0, react.useState)(null);
-			const seq = (0, react.useRef)(0);
-			const controller = (0, react.useRef)(null);
-			const composing = (0, react.useRef)(false);
-			/** 新意图胜出：中止在途扫描并使旧结果失效。 */
-			const navigate = (target) => {
-				controller.current?.abort();
-				controller.current = null;
-				const mine = ++seq.current;
-				setLoading(true);
-				setError(null);
-				const ctrl = new AbortController();
-				controller.current = ctrl;
-				listDirectory(target, ctrl.signal).then((next) => {
-					if (mine !== seq.current) return;
-					setListing(next);
-					setLoading(false);
-				}, (cause) => {
-					if (mine !== seq.current) return;
-					setLoading(false);
-					setError(cause instanceof Error ? cause.message : String(cause));
-				});
-			};
-			(0, react.useEffect)(() => {
-				if (open) navigate();
-				else {
-					seq.current += 1;
-					controller.current?.abort();
-					controller.current = null;
-					setPathDraft(null);
-					setError(null);
-				}
-			}, [open]);
-			const openPathEditor = () => {
-				if (listing === null) {
-					setPathDraft("");
-					return;
-				}
-				const sep = separatorOf(listing);
-				const base = listing.path;
-				setPathDraft(base.endsWith(sep) ? base : base + sep);
-			};
-			const commitPath = () => {
-				const draft = pathDraft ?? "";
-				if (draft.trim() === "") return;
-				navigate(draft);
-				setPathDraft(null);
-			};
-			const crumbs = listing === null ? [] : displayCrumbs(listing, t("browser.home"));
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
-				open,
-				onClose,
-				title: t("browser.title"),
-				closeLabel: t("browser.cancel"),
-				className: "reflib-browser",
-				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-					className: "reflib-panel",
-					children: [
-						error !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-error",
-							role: "alert",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
-								size: 14,
-								className: "reflib-errorIcon"
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: error })]
-						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "reflib-browserPath",
-							children: pathDraft === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								className: "reflib-browserCrumbs",
-								role: "navigation",
-								children: crumbs.map((crumb, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-									className: "reflib-browserCrumb",
-									children: [index > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronRightOutline14, {
-										size: 12,
-										className: "reflib-browserCrumbChevron"
-									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-										type: "button",
-										className: "reflib-browserCrumbBtn",
-										disabled: loading,
-										onClick: () => {
-											navigate(crumb.path);
-										},
-										children: crumb.name
-									})]
-								}, crumb.path))
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-								type: "button",
-								className: "reflib-browserEdit",
-								"aria-label": t("browser.editPath"),
-								title: t("browser.editPath"),
-								disabled: loading,
-								onClick: openPathEditor,
-								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconEditOutline16, { size: 14 })
-							})] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-								className: "reflib-browserInput",
-								value: pathDraft,
-								"aria-label": t("browser.editPath"),
-								placeholder: t("browser.pathPlaceholder"),
-								autoFocus: true,
-								disabled: loading,
-								onChange: (event) => {
-									setPathDraft(event.currentTarget.value);
-								},
-								onCompositionStart: () => {
-									composing.current = true;
-								},
-								onCompositionEnd: () => {
-									composing.current = false;
-								},
-								onKeyDown: (event) => {
-									if (event.key === "Enter" && !composing.current) {
-										event.preventDefault();
-										commitPath();
-									}
-									if (event.key === "Escape") {
-										event.stopPropagation();
-										setPathDraft(null);
-									}
-								}
-							})
-						}),
-						loading ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-status",
-							role: "status",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
-								size: 20,
-								className: "reflib-spin reflib-statusIcon"
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								className: "reflib-statusText",
-								children: t("browser.loading")
-							})]
-						}) : listing !== null && listing.entries.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-status",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
-								size: 22,
-								className: "reflib-statusIcon"
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								className: "reflib-statusText",
-								children: t("browser.empty")
-							})]
-						}) : listing !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "reflib-browserList",
-							children: listing.entries.map((entry) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
-								type: "button",
-								className: "reflib-browserRow",
-								"aria-label": t("browser.enter.aria", { name: entry.name }),
-								disabled: loading,
-								onClick: () => {
-									navigate(entry.path);
-								},
-								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderClose16, {
-									size: 16,
-									className: "reflib-browserRowIcon"
-								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "reflib-browserRowName",
-									children: entry.name
-								})]
-							}, entry.path))
-						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "reflib-divider" }),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-browserFooter",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-								variant: "outline",
-								size: "sm",
-								disabled: loading,
-								onClick: onClose,
-								children: t("browser.cancel")
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-								variant: "primary",
-								size: "sm",
-								disabled: loading || listing === null,
-								"aria-label": t("browser.open.aria"),
-								onClick: () => {
-									if (listing !== null) onOpen(listing.path);
-								},
-								children: t("browser.open")
-							})]
-						})
-					]
-				})
-			});
-		}
-		//#endregion
-		//#region src/client/RefLibPanel.tsx
+		//#region src/client/styles.ts
 		/**
-		* 参考库管理面板（Modal）：列表（基名 + 全路径、移除操作）+ 添加表单。
+		* ref-lib client 样式注入：在文档头挂一张本插件专属的 <style data-plugin> 标签。
 		*
-		* 设计（优化点 1/2）：全部样式走 “--dsw-*” 设计令牌（随浅/深主题适配），
-		* 列表行以「基名为主行、完整路径为次行」呈现，移除为带危险 hover 的图标按钮，
-		* 添加为主按钮 + 路径输入（支持直接粘贴路径，绕开卡顿的系统选择器）+ 系统选择器
-		* 兜底；空态/加载态/错误态各有独立视觉。文案全部经 `t` 本地化（zh/en）。
-		* 本组件为纯展示：异步操作与错误归集由 RefLibDock 持有。
-		* @module @hpyperry/dsh-ref-lib/src/client/RefLibPanel
-		*/
-		/** 用途说明最大长度（与 node half service.NOTE_MAX_LENGTH 一致）。 */
-		const NOTE_MAX_LENGTH = 120;
-		/**
-		* 渲染参考库管理面板。
-		* @param props - 见 {@link RefLibPanelProps}。
-		* @returns 对话框元素（关闭时 Modal 返回 null）。
-		*/
-		function RefLibPanel(props) {
-			const { open, onClose, libs, loading, busy, picking, removingId, error, t, onRemove, onAddPath, onUpdateNote, onBrowse } = props;
-			const [draft, setDraft] = (0, react.useState)("");
-			const [noteDraft, setNoteDraft] = (0, react.useState)("");
-			const [detailId, setDetailId] = (0, react.useState)(null);
-			const [editNote, setEditNote] = (0, react.useState)("");
-			(0, react.useEffect)(() => {
-				if (!open) {
-					setDraft("");
-					setNoteDraft("");
-					setDetailId(null);
-				}
-			}, [open]);
-			const handleSubmit = async () => {
-				const trimmed = draft.trim();
-				if (trimmed === "") return;
-				try {
-					const note = noteDraft.trim();
-					await onAddPath(trimmed, note === "" ? void 0 : note);
-					setDraft("");
-					setNoteDraft("");
-				} catch {}
-			};
-			/** 浏览选中目录 → 填入路径字段（不直接添加，用户可补用途后提交）。 */
-			const handleBrowse = async () => {
-				const path = await onBrowse();
-				if (path !== null) setDraft(path);
-			};
-			/** 展开/收起条目详情；展开时载入当前用途草稿。 */
-			const toggleDetail = (entry) => {
-				if (detailId === entry.id) {
-					setDetailId(null);
-					return;
-				}
-				setDetailId(entry.id);
-				setEditNote(entry.note ?? "");
-			};
-			/** 保存详情编辑的用途说明；成功后收起详情。 */
-			const handleSaveNote = async () => {
-				if (detailId === null) return;
-				await onUpdateNote(detailId, editNote);
-				setDetailId(null);
-			};
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
-				open,
-				onClose,
-				title: t("panel.title"),
-				closeLabel: t("panel.close"),
-				description: t("panel.description", { count: String(libs.length) }),
-				className: "reflib-modal",
-				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-					className: "reflib-panel",
-					children: [
-						error !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-error",
-							role: "alert",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
-								size: 14,
-								className: "reflib-errorIcon"
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: error })]
-						}),
-						loading ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-status",
-							role: "status",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
-								size: 20,
-								className: "reflib-spin reflib-statusIcon"
-							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								className: "reflib-statusText",
-								children: t("list.loading")
-							})]
-						}) : libs.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-status",
-							children: [
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
-									size: 22,
-									className: "reflib-statusIcon"
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "reflib-statusText",
-									children: t("list.empty")
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "reflib-statusHint",
-									children: t("list.empty.hint")
-								})
-							]
-						}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "reflib-list",
-							children: libs.map((entry) => {
-								const name = libBasename(entry.path);
-								const removing = removingId === entry.id;
-								const detailOpen = detailId === entry.id;
-								return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "reflib-listItem",
-									"data-removing": removing || void 0,
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-										className: "reflib-row",
-										children: [
-											/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
-												size: 16,
-												className: "reflib-rowIcon"
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-												className: "reflib-rowBody",
-												children: [
-													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-														className: "reflib-rowName",
-														title: entry.path,
-														children: name
-													}),
-													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-														className: "reflib-rowPath",
-														title: entry.path,
-														children: entry.path
-													}),
-													entry.note !== void 0 && entry.note !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-														className: "reflib-rowNote",
-														title: entry.note,
-														children: entry.note.replace(/\s+/g, " ")
-													})
-												]
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
-												label: t("detail.open"),
-												side: "top",
-												delayMs: 400,
-												children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-													type: "button",
-													className: "reflib-rowAction",
-													"aria-label": t("detail.open.aria", { name }),
-													"aria-expanded": detailOpen || void 0,
-													disabled: busy || removingId !== null,
-													onClick: () => {
-														toggleDetail(entry);
-													},
-													children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconEllipsisOutline16, { size: 14 })
-												})
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
-												label: t("list.remove"),
-												side: "top",
-												delayMs: 400,
-												children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-													type: "button",
-													className: "reflib-rowRemove",
-													"aria-label": t("list.remove.aria", { name }),
-													disabled: busy || removingId !== null,
-													onClick: () => {
-														onRemove(entry.id);
-													},
-													children: removing ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
-														size: 14,
-														className: "reflib-spin"
-													}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconTrashOutline16, { size: 14 })
-												})
-											})
-										]
-									}), detailOpen && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-										className: "reflib-detail",
-										children: [
-											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-												className: "reflib-detailMeta",
-												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-													className: "reflib-detailKey",
-													children: "ID"
-												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-													className: "reflib-detailValue",
-													children: entry.id
-												})]
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-												className: "reflib-detailMeta",
-												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-													className: "reflib-detailKey",
-													children: t("detail.path")
-												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-													className: "reflib-detailValue",
-													title: entry.path,
-													children: entry.path
-												})]
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-												className: "reflib-detailKey",
-												children: t("add.note.label")
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-												className: "reflib-noteWrap",
-												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
-													className: "reflib-noteTextarea",
-													value: editNote,
-													placeholder: t("add.note.placeholder"),
-													"aria-label": t("add.note.label"),
-													disabled: busy,
-													rows: 3,
-													maxLength: NOTE_MAX_LENGTH,
-													onChange: (event) => {
-														setEditNote(event.currentTarget.value);
-													}
-												}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-													className: "reflib-noteCount",
-													children: [
-														editNote.length,
-														"/",
-														NOTE_MAX_LENGTH
-													]
-												})]
-											}),
-											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-												className: "reflib-detailActions",
-												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-													variant: "ghost",
-													size: "sm",
-													disabled: busy,
-													onClick: () => {
-														setDetailId(null);
-													},
-													children: t("detail.cancel")
-												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-													variant: "primary",
-													size: "sm",
-													disabled: busy,
-													onClick: () => {
-														handleSaveNote();
-													},
-													children: t("detail.save")
-												})]
-											})
-										]
-									})]
-								}, entry.id);
-							})
-						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "reflib-divider" }),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-							className: "reflib-add",
-							children: [
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "reflib-addLabel",
-									children: t("add.label")
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "reflib-addRow",
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Input, {
-										className: "reflib-addInputWrap",
-										value: draft,
-										placeholder: t("add.placeholder"),
-										"aria-label": t("add.label"),
-										disabled: busy || picking,
-										onChange: (event) => {
-											setDraft(event.currentTarget.value);
-										},
-										onKeyDown: (event) => {
-											if (event.key === "Enter" && !event.nativeEvent.isComposing) {
-												event.preventDefault();
-												handleSubmit();
-											}
-										}
-									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-										variant: "outline",
-										size: "sm",
-										icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconSearchOutline16, { size: 14 }),
-										disabled: busy || picking,
-										onClick: () => {
-											handleBrowse();
-										},
-										children: t("add.browse")
-									})]
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "reflib-noteWrap",
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
-										className: "reflib-noteTextarea",
-										value: noteDraft,
-										placeholder: t("add.note.placeholder"),
-										"aria-label": t("add.note.label"),
-										disabled: busy || picking,
-										rows: 2,
-										maxLength: NOTE_MAX_LENGTH,
-										onChange: (event) => {
-											setNoteDraft(event.currentTarget.value);
-										}
-									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-										className: "reflib-noteCount",
-										children: [
-											noteDraft.length,
-											"/",
-											NOTE_MAX_LENGTH
-										]
-									})]
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-									variant: "primary",
-									className: "reflib-addSubmit",
-									icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconPlusOutline16, { size: 14 }),
-									disabled: busy || picking || draft.trim() === "",
-									onClick: () => {
-										handleSubmit();
-									},
-									children: t("add.submit")
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: "reflib-addHint",
-									children: t("add.hint")
-								})
-							]
-						})
-					]
-				})
-			});
-		}
-		//#endregion
-		//#region src/client/styles.ts
-		/**
-		* ref-lib client 样式注入：在文档头挂一张本插件专属的 <style data-plugin> 标签。
-		*
-		* 为什么不用 CSS Modules：ref-lib 的 tsdown 配置未移植 core 的 lightningcss
-		* CSS-Modules 插件（避免新增 native 依赖与构建面），而内联 style 无法表达
-		* hover/媒体查询/动画。因此采用运行时注入单张样式表——与 loader 的清理契约
-		* 兼容（`data-plugin` 标签在插件卸载/HMR 时由 loader 移除，重新物化时本模块
-		* 重新注入，幂等）。类名统一 `reflib-` 前缀防碰撞；颜色/字号/圆角全部走
-		* `--dsw-*` 设计令牌，随主题（浅色/深色）自动适配——这是"字体显示不一致、
-		* 没有设计感"的根因修复之一（旧实现硬编码 #d33 等，不随主题变化）。
-		* @module @hpyperry/dsh-ref-lib/src/client/styles
+		* 为什么不用 CSS Modules：ref-lib 的 tsdown 配置未移植 core 的 lightningcss
+		* CSS-Modules 插件（避免新增 native 依赖与构建面），而内联 style 无法表达
+		* hover/媒体查询/动画。因此采用运行时注入单张样式表——与 loader 的清理契约
+		* 兼容（`data-plugin` 标签在插件卸载/HMR 时由 loader 移除，重新物化时本模块
+		* 重新注入，幂等）。类名统一 `reflib-` 前缀防碰撞；颜色/字号/圆角全部走
+		* `--dsw-*` 设计令牌，随主题（浅色/深色）自动适配——这是"字体显示不一致、
+		* 没有设计感"的根因修复之一（旧实现硬编码 #d33 等，不随主题变化）。
+		* @module @hpyperry/dsh-ref-lib/src/client/styles
 		*/
 		/** 插件 id（与 package.json 的 bundle 手递一致，loader 按它清理样式）。 */
 		const PLUGIN_ID = "@hpyperry/dsh-ref-lib";
@@ -727,6 +183,22 @@ window.__ModuleLoader__.load({
   font-weight: 500;
 }
 
+/* 失效条目计数角标（v9）：红色系，与普通数量徽标区分。 */
+.reflib-chipWarn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  border-radius: 9px;
+  background: var(--dsw-alias-state-error-primary);
+  color: #fff;
+  font-size: 11px;
+  line-height: 18px;
+  font-weight: 500;
+}
+
 /* ── 应用内目录浏览器（browse 后端）── */
 .reflib-browser {
   width: min(460px, 100%);
@@ -942,6 +414,11 @@ window.__ModuleLoader__.load({
   color: var(--dsw-alias-label-tertiary);
 }
 
+/* 失效条目行图标（v9）：警示色。 */
+.reflib-rowIconWarn {
+  color: var(--dsw-alias-state-error-primary);
+}
+
 .reflib-rowBody {
   display: flex;
   flex: 1;
@@ -980,6 +457,16 @@ window.__ModuleLoader__.load({
   white-space: nowrap;
 }
 
+/* 失效条目状态行（v9）：红色警示文案，位于路径之下 */
+.reflib-rowStatus {
+  overflow: hidden;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 12px;
+  line-height: 16px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .reflib-rowRemove {
   display: inline-flex;
   align-items: center;
@@ -1253,6 +740,86 @@ window.__ModuleLoader__.load({
   color: var(--dsw-alias-label-caption);
 }
 
+/* ── /ref-lib 命令结果卡片（conversation.chat.commandview）── */
+.reflib-cmd {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.reflib-cmdHead {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.reflib-cmdHeadIcon {
+  flex: none;
+}
+
+.reflib-cmdName {
+  flex: none;
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 500;
+}
+
+/* 摘要行 = 结果首行；过长单行省略（完整结果见下方 body） */
+.reflib-cmdSummary {
+  min-width: 0;
+  flex: 1 1 auto;
+  overflow: hidden;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.reflib-cmdSummary[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.reflib-cmdCopy {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  line-height: 18px;
+  cursor: pointer;
+}
+
+.reflib-cmdCopy:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* 完整结果：默认全展开（无 max-height 截断），超宽自动换行 */
+.reflib-cmdBody {
+  margin: 0;
+  padding: 10px 14px;
+  overflow: auto;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 10px;
+  background: var(--dsw-alias-markdown-code-block);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-markdown-code-block-small);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.reflib-cmdBody[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
 /* 窄视口：路径行换行，输入框占满一行 */
 @media (max-width: 440px) {
   .reflib-addRow {
@@ -1279,6 +846,688 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		//#endregion
+		//#region src/client/RefLibCommandCard.tsx
+		/**
+		* `/ref-lib` 命令结果专属卡片（conversation.chat.commandview，key='ref-lib'）。
+		*
+		* 背景（历史 bug）：官方 `GenericCommandCard` 对命令结果折叠态 `white-space:
+		* nowrap` + `text-overflow: ellipsis` 单行截断，展开态 `max-height: 260px` 内滚动
+		* ——`/ref-lib list` 等多行长结果会显示不全。本卡片注册在
+		* `conversation.chat.commandview`（keyed，按命令名分派）的 `ref-lib` 键上：
+		* **默认全展开展示完整结果**（无高度上限）+ 一键复制按钮。只影响 `/ref-lib`，
+		* 其他命令仍走官方卡片。
+		* @module @hpyperry/dsh-ref-lib/src/client/RefLibCommandCard
+		*/
+		ensureRefLibStyles();
+		/**
+		* `/ref-lib` 命令结果卡片：完整展示 `outcome.text`（pre-wrap、无高度截断）+
+		* 复制按钮。running 态显示执行中；error 态红色。
+		* @param props - node（owner）与本地化 seat。
+		* @returns 卡片元素。
+		*/
+		function RefLibCommandCard(props) {
+			const { node, t } = props;
+			const [copied, setCopied] = (0, react.useState)(false);
+			const outcome = node.outcome;
+			const text = outcome?.text;
+			const running = outcome === null;
+			const error = outcome?.kind === "error";
+			/** 复制完整结果到剪贴板；成功后短暂显示"已复制"（权限失败静默）。 */
+			const copy = async () => {
+				if (text === void 0 || text === "") return;
+				try {
+					await navigator.clipboard.writeText(text);
+					setCopied(true);
+					window.setTimeout(() => {
+						setCopied(false);
+					}, 1500);
+				} catch {}
+			};
+			const summary = running ? t("command.running") : text !== void 0 && text !== "" ? text.split("\n")[0] : t("command.done");
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "reflib-cmd",
+				"data-state": running ? "running" : error ? "error" : "ok",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "reflib-cmdHead",
+					children: [
+						running && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
+							size: 14,
+							className: "reflib-spin reflib-cmdHeadIcon"
+						}),
+						!running && error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
+							size: 14,
+							className: "reflib-cmdHeadIcon"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "reflib-cmdName",
+							children: "/ref-lib"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "reflib-cmdSummary",
+							"data-error": error || void 0,
+							children: summary
+						}),
+						!running && text !== void 0 && text !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+							type: "button",
+							className: "reflib-cmdCopy",
+							"aria-label": t("command.copy"),
+							title: t("command.copy"),
+							onClick: () => {
+								copy();
+							},
+							children: [copied ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconCheckOutline16, { size: 14 }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconCopyOutline16, { size: 14 }), copied ? t("command.copied") : t("command.copy")]
+						})
+					]
+				}), !running && text !== void 0 && text !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+					className: "reflib-cmdBody",
+					"data-error": error || void 0,
+					children: text
+				})]
+			});
+		}
+		//#endregion
+		//#region src/client/refresh-guard.ts
+		/**
+		* 并发读守卫（竞态控制核心）：只接受"最后发起"的请求结果。
+		*
+		* RefLibDock 有多个并发"拉取列表"来源——挂载预载、打开面板、30s 轮询、操作后的
+		* 刷新——网络返回顺序不保证，旧快照可能覆盖新快照。守卫用递增编号标记每次发起：
+		* 返回时只有仍持有**最新编号**的请求结果才被应用，其余一律丢弃。
+		*
+		* 为什么"最后发起"就代表最新：`list` 返回的是请求发起时刻的服务端快照，发起越晚
+		* 快照越新，所以只信最后发起者 ≈ 只信最新快照。操作后的刷新总是最后发起（操作
+		* 完成后才发起），天然胜出；响应乱序时旧号被丢弃，最终一致。
+		*
+		* 纯 TS、零依赖、零 DOM——node 环境可直接单元测试（tests/refresh-guard.spec.ts）。
+		* @module @hpyperry/dsh-ref-lib/src/client/refresh-guard
+		*/
+		var RefreshGuard = class {
+			seq = 0;
+			/** 发起一次请求，返回本次请求的编号。 */
+			begin() {
+				this.seq += 1;
+				return this.seq;
+			}
+			/**
+			* 该编号是否仍是最新发起者。
+			* @param mine - 发起时 {@link begin} 返回的编号。
+			* @returns true 表示应应用该请求的结果；false 表示期间又有新请求发起，结果已过期。
+			*/
+			isLatest(mine) {
+				return mine === this.seq;
+			}
+			/**
+			* 作废所有 in-flight 请求的结果（会话切换 / 组件卸载时调用）：seq 递增后，
+			* 任何旧编号的 {@link isLatest} 都返回 false。
+			*/
+			invalidate() {
+				this.seq += 1;
+			}
+		};
+		//#endregion
+		//#region src/client/RefLibBrowser.tsx
+		/**
+		* 应用内目录浏览器（browse 后端可用时，「选择目录」的落地实现）。
+		*
+		* 为什么需要它：v6 起 profile 把 directory-picker 从 -auto（本机解析为 native，
+		* OS 对话框硬编码英文且每次拉 osascript 进程）切换为 -browse 后，
+		* `host.pickDirectory`（native 专用 RPC）不再可用；本组件用 `listDirectory`
+		* （Node stdlib 列目录，zh/en 本地化、无 OS 进程）提供等价的目录选择：
+		* 面包屑 + 路径编辑 + 子目录列表，点击下行进入，「选择此目录」把当前层级添加为
+		* 参考库。简化为单列（与官方 DirectoryBrowser 的 Miller 双列相比），
+		* 但覆盖添加参考库的核心路径。
+		* @module @hpyperry/dsh-ref-lib/src/client/RefLibBrowser
+		*/
+		/** 面包屑展示：主目录子树内以本地化 Home 开头；之外显示完整祖先链。 */
+		function displayCrumbs(listing, homeLabel) {
+			const homeIndex = listing.crumbs.findIndex((crumb) => crumb.path === listing.home);
+			if (homeIndex === -1) return listing.crumbs;
+			const tail = listing.crumbs.slice(homeIndex + 1);
+			return [{
+				name: homeLabel,
+				path: listing.home,
+				hidden: false
+			}, ...tail];
+		}
+		/** 平台分隔符（由宿主主目录推断，绝不从键入文本推断）。 */
+		function separatorOf(listing) {
+			return listing.home.includes("\\") ? "\\" : "/";
+		}
+		/**
+		* 渲染应用内目录浏览器。
+		* @param props - 见 {@link RefLibBrowserProps}。
+		* @returns 对话框元素（关闭时 Modal 返回 null）。
+		*/
+		function RefLibBrowser(props) {
+			const { open, onClose, listDirectory, t, onOpen } = props;
+			const [listing, setListing] = (0, react.useState)(null);
+			const [loading, setLoading] = (0, react.useState)(false);
+			const [error, setError] = (0, react.useState)(null);
+			const [pathDraft, setPathDraft] = (0, react.useState)(null);
+			const seq = (0, react.useRef)(0);
+			const controller = (0, react.useRef)(null);
+			const composing = (0, react.useRef)(false);
+			/** 新意图胜出：中止在途扫描并使旧结果失效。 */
+			const navigate = (target) => {
+				controller.current?.abort();
+				controller.current = null;
+				const mine = ++seq.current;
+				setLoading(true);
+				setError(null);
+				const ctrl = new AbortController();
+				controller.current = ctrl;
+				listDirectory(target, ctrl.signal).then((next) => {
+					if (mine !== seq.current) return;
+					setListing(next);
+					setLoading(false);
+				}, (cause) => {
+					if (mine !== seq.current) return;
+					setLoading(false);
+					setError(cause instanceof Error ? cause.message : String(cause));
+				});
+			};
+			(0, react.useEffect)(() => {
+				if (open) navigate();
+				else {
+					seq.current += 1;
+					controller.current?.abort();
+					controller.current = null;
+					setPathDraft(null);
+					setError(null);
+				}
+			}, [open]);
+			const openPathEditor = () => {
+				if (listing === null) {
+					setPathDraft("");
+					return;
+				}
+				const sep = separatorOf(listing);
+				const base = listing.path;
+				setPathDraft(base.endsWith(sep) ? base : base + sep);
+			};
+			const commitPath = () => {
+				const draft = pathDraft ?? "";
+				if (draft.trim() === "") return;
+				navigate(draft);
+				setPathDraft(null);
+			};
+			const crumbs = listing === null ? [] : displayCrumbs(listing, t("browser.home"));
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
+				open,
+				onClose,
+				title: t("browser.title"),
+				closeLabel: t("browser.cancel"),
+				className: "reflib-browser",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "reflib-panel",
+					children: [
+						error !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-error",
+							role: "alert",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
+								size: 14,
+								className: "reflib-errorIcon"
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: error })]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "reflib-browserPath",
+							children: pathDraft === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "reflib-browserCrumbs",
+								role: "navigation",
+								children: crumbs.map((crumb, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+									className: "reflib-browserCrumb",
+									children: [index > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronRightOutline14, {
+										size: 12,
+										className: "reflib-browserCrumbChevron"
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										className: "reflib-browserCrumbBtn",
+										disabled: loading,
+										onClick: () => {
+											navigate(crumb.path);
+										},
+										children: crumb.name
+									})]
+								}, crumb.path))
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "reflib-browserEdit",
+								"aria-label": t("browser.editPath"),
+								title: t("browser.editPath"),
+								disabled: loading,
+								onClick: openPathEditor,
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconEditOutline16, { size: 14 })
+							})] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+								className: "reflib-browserInput",
+								value: pathDraft,
+								"aria-label": t("browser.editPath"),
+								placeholder: t("browser.pathPlaceholder"),
+								autoFocus: true,
+								disabled: loading,
+								onChange: (event) => {
+									setPathDraft(event.currentTarget.value);
+								},
+								onCompositionStart: () => {
+									composing.current = true;
+								},
+								onCompositionEnd: () => {
+									composing.current = false;
+								},
+								onKeyDown: (event) => {
+									if (event.key === "Enter" && !composing.current) {
+										event.preventDefault();
+										commitPath();
+									}
+									if (event.key === "Escape") {
+										event.stopPropagation();
+										setPathDraft(null);
+									}
+								}
+							})
+						}),
+						loading ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-status",
+							role: "status",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
+								size: 20,
+								className: "reflib-spin reflib-statusIcon"
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "reflib-statusText",
+								children: t("browser.loading")
+							})]
+						}) : listing !== null && listing.entries.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-status",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
+								size: 22,
+								className: "reflib-statusIcon"
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "reflib-statusText",
+								children: t("browser.empty")
+							})]
+						}) : listing !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "reflib-browserList",
+							children: listing.entries.map((entry) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+								type: "button",
+								className: "reflib-browserRow",
+								"aria-label": t("browser.enter.aria", { name: entry.name }),
+								disabled: loading,
+								onClick: () => {
+									navigate(entry.path);
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderClose16, {
+									size: 16,
+									className: "reflib-browserRowIcon"
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "reflib-browserRowName",
+									children: entry.name
+								})]
+							}, entry.path))
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "reflib-divider" }),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-browserFooter",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+								variant: "outline",
+								size: "sm",
+								disabled: loading,
+								onClick: onClose,
+								children: t("browser.cancel")
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+								variant: "primary",
+								size: "sm",
+								disabled: loading || listing === null,
+								"aria-label": t("browser.open.aria"),
+								onClick: () => {
+									if (listing !== null) onOpen(listing.path);
+								},
+								children: t("browser.open")
+							})]
+						})
+					]
+				})
+			});
+		}
+		//#endregion
+		//#region src/client/RefLibPanel.tsx
+		/**
+		* 参考库管理面板（Modal）：列表（基名 + 全路径、移除操作）+ 添加表单。
+		*
+		* 设计（优化点 1/2）：全部样式走 “--dsw-*” 设计令牌（随浅/深主题适配），
+		* 列表行以「基名为主行、完整路径为次行」呈现，移除为带危险 hover 的图标按钮，
+		* 添加为主按钮 + 路径输入（支持直接粘贴路径，绕开卡顿的系统选择器）+ 系统选择器
+		* 兜底；空态/加载态/错误态各有独立视觉。文案全部经 `t` 本地化（zh/en）。
+		* 本组件为纯展示：异步操作与错误归集由 RefLibDock 持有。
+		* @module @hpyperry/dsh-ref-lib/src/client/RefLibPanel
+		*/
+		/** 用途说明最大长度（与 node half service.NOTE_MAX_LENGTH 一致）。 */
+		const NOTE_MAX_LENGTH = 120;
+		/**
+		* 渲染参考库管理面板。
+		* @param props - 见 {@link RefLibPanelProps}。
+		* @returns 对话框元素（关闭时 Modal 返回 null）。
+		*/
+		function RefLibPanel(props) {
+			const { open, onClose, libs, loading, busy, picking, removingId, error, t, onRemove, onAddPath, onUpdateNote, onBrowse } = props;
+			const [draft, setDraft] = (0, react.useState)("");
+			const [noteDraft, setNoteDraft] = (0, react.useState)("");
+			const [detailId, setDetailId] = (0, react.useState)(null);
+			const [editNote, setEditNote] = (0, react.useState)("");
+			(0, react.useEffect)(() => {
+				if (!open) {
+					setDraft("");
+					setNoteDraft("");
+					setDetailId(null);
+				}
+			}, [open]);
+			const handleSubmit = async () => {
+				const trimmed = draft.trim();
+				if (trimmed === "") return;
+				try {
+					const note = noteDraft.trim();
+					await onAddPath(trimmed, note === "" ? void 0 : note);
+					setDraft("");
+					setNoteDraft("");
+				} catch {}
+			};
+			/** 浏览选中目录 → 填入路径字段（不直接添加，用户可补用途后提交）。 */
+			const handleBrowse = async () => {
+				const path = await onBrowse();
+				if (path !== null) setDraft(path);
+			};
+			/** 展开/收起条目详情；展开时载入当前用途草稿。 */
+			const toggleDetail = (entry) => {
+				if (detailId === entry.id) {
+					setDetailId(null);
+					return;
+				}
+				setDetailId(entry.id);
+				setEditNote(entry.note ?? "");
+			};
+			/** 保存详情编辑的用途说明；成功后收起详情。 */
+			const handleSaveNote = async () => {
+				if (detailId === null) return;
+				await onUpdateNote(detailId, editNote);
+				setDetailId(null);
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Modal, {
+				open,
+				onClose,
+				title: t("panel.title"),
+				closeLabel: t("panel.close"),
+				description: t("panel.description", { count: String(libs.length) }),
+				className: "reflib-modal",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "reflib-panel",
+					children: [
+						error !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-error",
+							role: "alert",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
+								size: 14,
+								className: "reflib-errorIcon"
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: error })]
+						}),
+						loading ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-status",
+							role: "status",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
+								size: 20,
+								className: "reflib-spin reflib-statusIcon"
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "reflib-statusText",
+								children: t("list.loading")
+							})]
+						}) : libs.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-status",
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
+									size: 22,
+									className: "reflib-statusIcon"
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "reflib-statusText",
+									children: t("list.empty")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "reflib-statusHint",
+									children: t("list.empty.hint")
+								})
+							]
+						}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "reflib-list",
+							children: libs.map((entry) => {
+								const name = libBasename(entry.path);
+								const removing = removingId === entry.id;
+								const detailOpen = detailId === entry.id;
+								const unavailable = entry.status !== void 0 && entry.status !== "available";
+								return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "reflib-listItem",
+									"data-removing": removing || void 0,
+									"data-status": unavailable ? entry.status : void 0,
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "reflib-row",
+										children: [
+											unavailable ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconWarningOutline16, {
+												size: 16,
+												className: "reflib-rowIcon reflib-rowIconWarn"
+											}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconFolderOpen16, {
+												size: 16,
+												className: "reflib-rowIcon"
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "reflib-rowBody",
+												children: [
+													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+														className: "reflib-rowName",
+														title: entry.path,
+														children: name
+													}),
+													/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+														className: "reflib-rowPath",
+														title: entry.path,
+														children: entry.path
+													}),
+													unavailable && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+														className: "reflib-rowStatus",
+														role: "status",
+														children: t(entry.status === "missing" ? "status.missing" : "status.notDirectory")
+													}),
+													entry.note !== void 0 && entry.note !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+														className: "reflib-rowNote",
+														title: entry.note,
+														children: entry.note.replace(/\s+/g, " ")
+													})
+												]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
+												label: t("detail.open"),
+												side: "top",
+												delayMs: 400,
+												children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+													type: "button",
+													className: "reflib-rowAction",
+													"aria-label": t("detail.open.aria", { name }),
+													"aria-expanded": detailOpen || void 0,
+													disabled: busy || removingId !== null || unavailable,
+													onClick: () => {
+														toggleDetail(entry);
+													},
+													children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconEllipsisOutline16, { size: 14 })
+												})
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Tooltip, {
+												label: t("list.remove"),
+												side: "top",
+												delayMs: 400,
+												children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+													type: "button",
+													className: "reflib-rowRemove",
+													"aria-label": t("list.remove.aria", { name }),
+													disabled: busy || removingId !== null,
+													onClick: () => {
+														onRemove(entry.id);
+													},
+													children: removing ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconLoadingOutline16, {
+														size: 14,
+														className: "reflib-spin"
+													}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconTrashOutline16, { size: 14 })
+												})
+											})
+										]
+									}), detailOpen && !unavailable && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "reflib-detail",
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "reflib-detailMeta",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "reflib-detailKey",
+													children: "ID"
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "reflib-detailValue",
+													children: entry.id
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "reflib-detailMeta",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "reflib-detailKey",
+													children: t("detail.path")
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "reflib-detailValue",
+													title: entry.path,
+													children: entry.path
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "reflib-detailKey",
+												children: t("add.note.label")
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "reflib-noteWrap",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
+													className: "reflib-noteTextarea",
+													value: editNote,
+													placeholder: t("add.note.placeholder"),
+													"aria-label": t("add.note.label"),
+													disabled: busy,
+													rows: 3,
+													maxLength: NOTE_MAX_LENGTH,
+													onChange: (event) => {
+														setEditNote(event.currentTarget.value);
+													}
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+													className: "reflib-noteCount",
+													children: [
+														editNote.length,
+														"/",
+														NOTE_MAX_LENGTH
+													]
+												})]
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+												className: "reflib-detailActions",
+												children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+													variant: "ghost",
+													size: "sm",
+													disabled: busy,
+													onClick: () => {
+														setDetailId(null);
+													},
+													children: t("detail.cancel")
+												}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+													variant: "primary",
+													size: "sm",
+													disabled: busy,
+													onClick: () => {
+														handleSaveNote();
+													},
+													children: t("detail.save")
+												})]
+											})
+										]
+									})]
+								}, entry.id);
+							})
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { className: "reflib-divider" }),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "reflib-add",
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "reflib-addLabel",
+									children: t("add.label")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "reflib-addRow",
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Input, {
+										className: "reflib-addInputWrap",
+										value: draft,
+										placeholder: t("add.placeholder"),
+										"aria-label": t("add.label"),
+										disabled: busy || picking,
+										onChange: (event) => {
+											setDraft(event.currentTarget.value);
+										},
+										onKeyDown: (event) => {
+											if (event.key === "Enter" && !event.nativeEvent.isComposing) {
+												event.preventDefault();
+												handleSubmit();
+											}
+										}
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+										variant: "outline",
+										size: "sm",
+										icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconSearchOutline16, { size: 14 }),
+										disabled: busy || picking,
+										onClick: () => {
+											handleBrowse();
+										},
+										children: t("add.browse")
+									})]
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "reflib-noteWrap",
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
+										className: "reflib-noteTextarea",
+										value: noteDraft,
+										placeholder: t("add.note.placeholder"),
+										"aria-label": t("add.note.label"),
+										disabled: busy || picking,
+										rows: 2,
+										maxLength: NOTE_MAX_LENGTH,
+										onChange: (event) => {
+											setNoteDraft(event.currentTarget.value);
+										}
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+										className: "reflib-noteCount",
+										children: [
+											noteDraft.length,
+											"/",
+											NOTE_MAX_LENGTH
+										]
+									})]
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+									variant: "primary",
+									className: "reflib-addSubmit",
+									icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconPlusOutline16, { size: 14 }),
+									disabled: busy || picking || draft.trim() === "",
+									onClick: () => {
+										handleSubmit();
+									},
+									children: t("add.submit")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "reflib-addHint",
+									children: t("add.hint")
+								})
+							]
+						})
+					]
+				})
+			});
+		}
+		//#endregion
 		//#region src/client/RefLibDock.tsx
 		/**
 		* 参考库入口（conversation.input.dock，输入卡正上方）+ 面板状态持有者。
@@ -1297,12 +1546,16 @@ window.__ModuleLoader__.load({
 		* 目录选择走系统原生选择器，另提供路径输入直加（绕开卡顿的原生对话框）。
 		* @module @hpyperry/dsh-ref-lib/src/client/RefLibDock
 		*/
+		/** 挂载预载失败重试：间隔与上限（重启后会话 live 通常 <1s，重试 1–2 次即成功）。 */
+		const MOUNT_RETRY_DELAY_MS = 800;
+		const MOUNT_RETRY_MAX = 5;
 		/** wire 错误码 → 本地化文案键（未知码回退原始消息）。 */
 		const ERROR_KEYS = {
 			"ref-lib/missing": "error.missing",
 			"ref-lib/not-directory": "error.notDirectory",
 			"ref-lib/unsafe": "error.unsafe",
-			"ref-lib/unknown-id": "error.unknownId"
+			"ref-lib/unknown-id": "error.unknownId",
+			"ref-lib/unavailable": "error.unavailable"
 		};
 		/** 把未知错误规整为可展示文案。 */
 		function messageOf(cause) {
@@ -1327,7 +1580,7 @@ window.__ModuleLoader__.load({
 		* @returns 胶囊入口（+ 打开时的管理面板）。
 		*/
 		function RefLibDock(props) {
-			const { sessionId, load, add, remove, setNote, pickDirectory, listDirectory, t } = props;
+			const { sessionId, session, load, add, remove, setNote, pickDirectory, listDirectory, t } = props;
 			const [open, setOpen] = (0, react.useState)(false);
 			const [libs, setLibs] = (0, react.useState)([]);
 			const [loading, setLoading] = (0, react.useState)(false);
@@ -1335,7 +1588,7 @@ window.__ModuleLoader__.load({
 			const [picking, setPicking] = (0, react.useState)(false);
 			const [removingId, setRemovingId] = (0, react.useState)(null);
 			const [error, setError] = (0, react.useState)(null);
-			const seq = (0, react.useRef)(0);
+			const guard = (0, react.useRef)(new RefreshGuard());
 			const [pickerMode, setPickerMode] = (0, react.useState)(null);
 			const [browserOpen, setBrowserOpen] = (0, react.useState)(false);
 			const pendingPick = (0, react.useRef)(null);
@@ -1351,23 +1604,57 @@ window.__ModuleLoader__.load({
 				setPickerMode(mode);
 				return mode;
 			};
-			const refresh = async () => {
-				const mine = ++seq.current;
+			/**
+			* 拉取会话参考库列表并更新 UI。
+			* @param silent - 静默模式（轮询用）：失败不写入错误槽；成功也**不碰 error/loading**
+			* ——错误与加载态只由用户操作/打开面板管理，避免后台轮询吞掉操作错误提示或
+			* 提前结束面板加载态（轮询仅更新 libs 数据）。
+			*/
+			const refresh = async (silent = false) => {
+				const mine = guard.current.begin();
 				try {
 					const next = await load(sessionId);
-					if (mine !== seq.current) return;
+					if (!guard.current.isLatest(mine)) return;
 					setLibs(next);
-					setError(null);
+					if (!silent) setError(null);
 				} catch (cause) {
-					if (mine !== seq.current) return;
-					setError(formatError(cause, t));
+					if (!guard.current.isLatest(mine)) return;
+					if (!silent) setError(formatError(cause, t));
 				} finally {
-					if (mine === seq.current) setLoading(false);
+					if (guard.current.isLatest(mine) && !silent) setLoading(false);
 				}
 			};
 			(0, react.useEffect)(() => {
 				ensureRefLibStyles();
-				refresh();
+				let stopped = false;
+				let retries = 0;
+				let timer;
+				const attempt = async () => {
+					const mine = guard.current.begin();
+					try {
+						const next = await load(sessionId);
+						if (stopped || !guard.current.isLatest(mine)) return;
+						setLibs(next);
+						setError(null);
+					} catch (cause) {
+						if (stopped || !guard.current.isLatest(mine)) return;
+						if (retries < MOUNT_RETRY_MAX) {
+							retries += 1;
+							timer = window.setTimeout(() => {
+								attempt();
+							}, MOUNT_RETRY_DELAY_MS);
+							return;
+						}
+						setError(formatError(cause, t));
+					} finally {
+						if (!stopped && guard.current.isLatest(mine)) setLoading(false);
+					}
+				};
+				attempt();
+				return () => {
+					stopped = true;
+					if (timer !== void 0) window.clearTimeout(timer);
+				};
 			}, [sessionId]);
 			(0, react.useEffect)(() => {
 				if (open) {
@@ -1375,6 +1662,14 @@ window.__ModuleLoader__.load({
 					refresh();
 				}
 			}, [open]);
+			const userMessageCount = session.nodes.filter((node) => node.kind === "user").length;
+			(0, react.useEffect)(() => {
+				refresh(true);
+			}, [userMessageCount]);
+			const refLibCommandDone = session.nodes.filter((node) => node.kind === "command" && node.name === "ref-lib" && node.outcome !== null).length;
+			(0, react.useEffect)(() => {
+				refresh(true);
+			}, [refLibCommandDone]);
 			const handleRemove = async (id) => {
 				setRemovingId(id);
 				setBusy(true);
@@ -1456,6 +1751,14 @@ window.__ModuleLoader__.load({
 				pendingPick.current = null;
 				resolve?.(null);
 			};
+			/**
+			* 胶囊计数（v9）：徽标显示**可用**数量（失效不计入），红色角标显示失效数量
+			* （总数 − 可用数），仅存在失效条目时显示。注意：UI 数据只在打开面板/操作后
+			* 刷新，外部变更（如删除目录）不会自动反向同步到界面（与命令修改后不刷新同属
+			* 待解决的 UI 数据同步问题，见设计文档"遗留备注"）。
+			*/
+			const availableCount = libs.filter((entry) => entry.status === "available").length;
+			const unavailableCount = libs.length - availableCount;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					className: "reflib-dock",
@@ -1465,7 +1768,7 @@ window.__ModuleLoader__.load({
 						"data-active": open || void 0,
 						"aria-haspopup": "dialog",
 						"aria-expanded": open,
-						"aria-label": libs.length > 0 ? t("dock.count.aria", { count: String(libs.length) }) : t("dock.aria"),
+						"aria-label": unavailableCount > 0 ? t("dock.unavailable", { count: String(unavailableCount) }) : availableCount > 0 ? t("dock.count.aria", { count: String(availableCount) }) : t("dock.aria"),
 						title: t("dock.aria"),
 						onClick: () => {
 							setOpen((value) => !value);
@@ -1479,9 +1782,14 @@ window.__ModuleLoader__.load({
 								className: "reflib-chipLabel",
 								children: t("dock.label")
 							}),
-							libs.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							availableCount > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: "reflib-chipBadge",
-								children: libs.length
+								children: availableCount
+							}),
+							unavailableCount > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "reflib-chipWarn",
+								title: t("dock.unavailable", { count: String(unavailableCount) }),
+								children: unavailableCount
 							})
 						]
 					})
@@ -1530,6 +1838,9 @@ window.__ModuleLoader__.load({
 			"dock.label": "参考库",
 			"dock.aria": "管理只读参考库",
 			"dock.count.aria": "参考库，共 {count} 个",
+			"dock.unavailable": "参考库，{count} 个失效",
+			"status.missing": "目录已删除或不可访问",
+			"status.notDirectory": "路径不再是目录",
 			"panel.title": "参考库",
 			"panel.close": "关闭",
 			"panel.description": "共 {count} 个只读参考库：供 agent 读取参考，禁止修改其中文件",
@@ -1563,13 +1874,21 @@ window.__ModuleLoader__.load({
 			"error.missing": "目录不存在：{path}",
 			"error.notDirectory": "不是目录：{path}",
 			"error.unsafe": "路径包含控制字符，已拒绝：{path}",
-			"error.unknownId": "未找到参考库条目：{id}"
+			"error.unknownId": "未找到参考库条目：{id}",
+			"error.unavailable": "参考库目录不可用（仅允许移除）",
+			"command.running": "执行中…",
+			"command.done": "完成",
+			"command.copy": "复制",
+			"command.copied": "已复制"
 		};
 		/** 英文词典，与 zh 键集逐键对齐（编译期校验）。 */
 		const en = {
 			"dock.label": "Reference Library",
 			"dock.aria": "Manage read-only reference libraries",
 			"dock.count.aria": "Reference library, {count} total",
+			"dock.unavailable": "Reference library, {count} unavailable",
+			"status.missing": "Directory deleted or unavailable",
+			"status.notDirectory": "Path is no longer a directory",
 			"panel.title": "Reference Library",
 			"panel.close": "Close",
 			"panel.description": "{count} read-only reference libraries: the agent may read them for reference, but must not modify any files",
@@ -1603,7 +1922,12 @@ window.__ModuleLoader__.load({
 			"error.missing": "Directory does not exist: {path}",
 			"error.notDirectory": "Not a directory: {path}",
 			"error.unsafe": "Path contains control characters and was rejected: {path}",
-			"error.unknownId": "Reference library entry not found: {id}"
+			"error.unknownId": "Reference library entry not found: {id}",
+			"error.unavailable": "Reference library directory unavailable (remove only)",
+			"command.running": "Running…",
+			"command.done": "Done",
+			"command.copy": "Copy",
+			"command.copied": "Copied"
 		};
 		//#endregion
 		//#region src/client/index.ts
@@ -1678,6 +2002,11 @@ window.__ModuleLoader__.load({
 				locale: NS,
 				inject: injected
 			}, RefLibDock));
+			ctx.slots.inject("conversation.chat.commandview", () => ctx.slots.register({
+				name: "conversation.chat.commandview",
+				key: "ref-lib",
+				locale: NS
+			}, RefLibCommandCard));
 		}
 		//#endregion
 		exports.apply = apply;