@hpyperry/dsh-ref-lib 0.7.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,412 +88,6 @@ 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
-		/**
-		* 参考库管理面板（Modal）：列表（基名 + 全路径、移除操作）+ 添加表单。
-		*
-		* 设计（优化点 1/2）：全部样式走 “--dsw-*” 设计令牌（随浅/深主题适配），
-		* 列表行以「基名为主行、完整路径为次行」呈现，移除为带危险 hover 的图标按钮，
-		* 添加为主按钮 + 路径输入（支持直接粘贴路径，绕开卡顿的系统选择器）+ 系统选择器
-		* 兜底；空态/加载态/错误态各有独立视觉。文案全部经 `t` 本地化（zh/en）。
-		* 本组件为纯展示：异步操作与错误归集由 RefLibDock 持有。
-		* @module @hpyperry/dsh-ref-lib/src/client/RefLibPanel
-		*/
-		/**
-		* 渲染参考库管理面板。
-		* @param props - 见 {@link RefLibPanelProps}。
-		* @returns 对话框元素（关闭时 Modal 返回 null）。
-		*/
-		function RefLibPanel(props) {
-			const { open, onClose, libs, loading, busy, picking, removingId, error, t, onRemove, onAddPath, onBrowse } = props;
-			const [draft, setDraft] = (0, react.useState)("");
-			(0, react.useEffect)(() => {
-				if (!open) setDraft("");
-			}, [open]);
-			const handleSubmit = async () => {
-				const trimmed = draft.trim();
-				if (trimmed === "") return;
-				try {
-					await onAddPath(trimmed);
-					setDraft("");
-				} catch {}
-			};
-			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) }),
-				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;
-								return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "reflib-row",
-									"data-removing": removing || void 0,
-									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
-											})]
-										}),
-										/* @__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 })
-											})
-										})
-									]
-								}, 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.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
-									variant: "primary",
-									className: "reflib-addBrowseMain",
-									icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconSearchOutline16, { size: 16 }),
-									disabled: busy || picking,
-									onClick: () => {
-										onBrowse();
-									},
-									children: t("add.browse")
-								}),
-								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-									className: "reflib-addManual",
-									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-										className: "reflib-addManualLabel",
-										children: t("add.manual")
-									}), /* @__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: "primary",
-											size: "sm",
-											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> 标签。
@@ -580,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%);
@@ -763,6 +382,12 @@ window.__ModuleLoader__.load({
   padding: 0 8px;
 }
 
+.reflib-listItem {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
 .reflib-row {
   display: flex;
   align-items: center;
@@ -778,7 +403,7 @@ window.__ModuleLoader__.load({
   background: var(--dsw-alias-interactive-bg-hover);
 }
 
-.reflib-row[data-removing='true'] {
+.reflib-listItem[data-removing='true'] {
   opacity: 0.55;
   pointer-events: none;
 }
@@ -789,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;
@@ -817,30 +447,164 @@ window.__ModuleLoader__.load({
   white-space: nowrap;
 }
 
-.reflib-rowRemove {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex: none;
-  width: 28px;
-  height: 28px;
-  padding: 0;
-  border: none;
-  border-radius: 8px;
-  background: transparent;
-  color: var(--dsw-alias-label-tertiary);
-  cursor: pointer;
-  transition: background-color 120ms ease, color 120ms ease;
+/* 列表行用途说明（Description，v8）：单行截断，与路径同属次行层级 */
+.reflib-rowNote {
+  overflow: hidden;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  line-height: 16px;
+  text-overflow: ellipsis;
+  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;
+  justify-content: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+  transition: background-color 120ms ease, color 120ms ease;
+}
+
+.reflib-rowRemove:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover-danger);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.reflib-rowRemove:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+/* 详情/编辑入口按钮（与移除同尺寸，非危险 hover） */
+.reflib-rowAction {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+  transition: background-color 120ms ease, color 120ms ease;
+}
+
+.reflib-rowAction:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+
+.reflib-rowAction:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+/* 条目详情展开区（ID / 路径 / 用途编辑） */
+.reflib-detail {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  margin: 2px 0 6px;
+  padding: 8px 10px 10px;
+  border-radius: 10px;
+  background: var(--dsw-alias-surface-inset, var(--dsw-alias-surface-raised));
+  min-width: 0;
+}
+
+.reflib-detailMeta {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 0;
+}
+
+.reflib-detailKey {
+  flex: none;
+  font-size: 11px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-caption);
+}
+
+.reflib-detailValue {
+  overflow: hidden;
+  min-width: 0;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-secondary);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.reflib-detailActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-top: 2px;
+}
+
+/* 用途说明多行输入（添加表单 + 详情编辑共用） */
+.reflib-noteWrap {
+  position: relative;
+  display: flex;
+  min-width: 0;
+}
+
+.reflib-noteTextarea {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 6px 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-surface-field);
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 13px;
+  line-height: 18px;
+  resize: vertical;
+  min-height: 40px;
+}
+
+.reflib-noteTextarea:focus {
+  outline: 2px solid var(--dsw-alias-focus-ring, var(--dsw-alias-state-info-primary));
+  outline-offset: -1px;
 }
 
-.reflib-rowRemove:hover:not(:disabled) {
-  background: var(--dsw-alias-interactive-bg-hover-danger);
-  color: var(--dsw-alias-state-error-primary);
+.reflib-noteTextarea:disabled {
+  opacity: 0.5;
 }
 
-.reflib-rowRemove:disabled {
-  opacity: 0.4;
-  cursor: default;
+.reflib-noteCount {
+  position: absolute;
+  right: 8px;
+  bottom: 6px;
+  padding: 0 4px;
+  border-radius: 4px;
+  background: var(--dsw-alias-surface-field);
+  font-size: 10px;
+  line-height: 14px;
+  color: var(--dsw-alias-label-caption);
+  pointer-events: none;
 }
 
 /* 空态 / 加载态 / 错误态 */
@@ -908,9 +672,28 @@ window.__ModuleLoader__.load({
   background: var(--dsw-alias-border-l2);
 }
 
+/* ── 管理面板 Modal（v8 优化）──
+   宽度放宽到约 1/3 屏（上限 560px）；进入动画为柔和缓出（easeOutQuint 风格：
+   280ms 浮起 + 淡入，位移 12px→0、scale 0.96→1），无回弹——更从容、高级感。 */
+.reflib-modal {
+  width: min(33vw, 560px);
+  animation: reflib-pop 280ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+@keyframes reflib-pop {
+  0% {
+    opacity: 0;
+    transform: scale(0.96) translateY(12px);
+  }
+  100% {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
 /* ── 添加表单 ──
-   两组操作分离（优化点 2.1）：手动输入路径 + 「添加」是一组（主路径）；
-   「选择目录」是另一组备选方式，独占一行，避免并排造成困惑。 */
+   统一表单（v8 UI 重构）：路径（可输入 / 浏览填充）+ 用途（可选）同一容器，
+   同一「添加」按钮提交——用途与路径强关联，浏览不再直接添加。 */
 .reflib-add {
   display: flex;
   flex-direction: column;
@@ -925,25 +708,6 @@ window.__ModuleLoader__.load({
   color: var(--dsw-alias-label-secondary);
 }
 
-/* 主方式：选择目录 —— 全宽主按钮（优先级最高） */
-.reflib-addBrowseMain {
-  width: 100%;
-}
-
-/* 备选：手动输入路径组 */
-.reflib-addManual {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  min-width: 0;
-}
-
-.reflib-addManualLabel {
-  font-size: 12px;
-  line-height: 16px;
-  color: var(--dsw-alias-label-caption);
-}
-
 .reflib-addRow {
   display: flex;
   align-items: center;
@@ -965,13 +729,98 @@ window.__ModuleLoader__.load({
   line-height: 18px;
 }
 
+/* 全宽「添加」主按钮 */
+.reflib-addSubmit {
+  width: 100%;
+}
+
 .reflib-addHint {
   font-size: 11px;
   line-height: 16px;
   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 {
     flex-wrap: wrap;
@@ -997,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，输入卡正上方）+ 面板状态持有者。
@@ -1015,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) {
@@ -1045,7 +1580,7 @@ window.__ModuleLoader__.load({
 		* @returns 胶囊入口（+ 打开时的管理面板）。
 		*/
 		function RefLibDock(props) {
-			const { sessionId, load, add, remove, 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);
@@ -1053,9 +1588,10 @@ 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);
 			const detectPicker = async () => {
 				if (pickerMode !== null) return pickerMode;
 				let mode;
@@ -1068,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) {
@@ -1092,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);
@@ -1106,11 +1684,11 @@ window.__ModuleLoader__.load({
 					setBusy(false);
 				}
 			};
-			const handleAddPath = async (path) => {
+			const handleAddPath = async (path, note) => {
 				setBusy(true);
 				setError(null);
 				try {
-					await add(sessionId, path);
+					await add(sessionId, path, note);
 					await refresh();
 				} catch (cause) {
 					setError(formatError(cause, t));
@@ -1119,48 +1697,68 @@ window.__ModuleLoader__.load({
 					setBusy(false);
 				}
 			};
-			/** 添加一个已选定目录并刷新列表；返回是否成功（失败时错误已入错误槽，不抛出）。 */
-			const addPath = async (path) => {
+			/** 更新条目用途说明（编辑详情保存）；失败入错误槽、不抛出（编辑区保持打开）。 */
+			const handleUpdateNote = async (id, note) => {
 				setBusy(true);
 				setError(null);
 				try {
-					await add(sessionId, path);
+					await setNote(sessionId, id, note);
 					await refresh();
-					return true;
 				} catch (cause) {
 					setError(formatError(cause, t));
-					return false;
 				} finally {
 					setBusy(false);
 				}
 			};
-			const handleBrowse = async () => {
+			/** 唤起目录选择（browse 应用内浏览器 / native 系统对话框）并返回选中的路径；
+			* 取消或失败返回 null——**不直接添加**，由面板把路径填入表单（用户可补用途后提交）。 */
+			const pickPath = async () => {
 				setError(null);
 				let mode;
 				try {
 					mode = await detectPicker();
 				} catch (cause) {
 					setError(formatError(cause, t));
-					return;
+					return null;
 				}
 				if (mode === "browse") {
 					setBrowserOpen(true);
-					return;
+					return await new Promise((resolve) => {
+						pendingPick.current = resolve;
+					});
 				}
 				setPicking(true);
 				try {
-					const picked = await pickDirectory();
-					if (picked !== null) await addPath(picked);
+					return await pickDirectory();
 				} catch (cause) {
 					setError(formatError(cause, t));
+					return null;
 				} finally {
 					setPicking(false);
 				}
 			};
-			/** 应用内浏览器选定目录 → 添加成功才关闭（失败时错误显示在面板，浏览器保持打开便于重试）。 */
-			const handleBrowserPick = async (path) => {
-				if (await addPath(path)) setBrowserOpen(false);
+			/** 应用内浏览器选定目录 → 把路径交给等待中的 pickPath 调用方并关闭浏览器。 */
+			const handleBrowserPick = (path) => {
+				setBrowserOpen(false);
+				const resolve = pendingPick.current;
+				pendingPick.current = null;
+				resolve?.(path);
 			};
+			/** 应用内浏览器取消 → 以 null 结束等待中的 pickPath。 */
+			const handleBrowserClose = () => {
+				setBrowserOpen(false);
+				const resolve = pendingPick.current;
+				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",
@@ -1170,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);
@@ -1184,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
 							})
 						]
 					})
@@ -1207,18 +1810,15 @@ window.__ModuleLoader__.load({
 						handleRemove(id);
 					},
 					onAddPath: handleAddPath,
-					onBrowse: handleBrowse
+					onUpdateNote: handleUpdateNote,
+					onBrowse: pickPath
 				}),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(RefLibBrowser, {
 					open: browserOpen,
-					onClose: () => {
-						setBrowserOpen(false);
-					},
+					onClose: handleBrowserClose,
 					listDirectory,
 					t,
-					onOpen: (path) => {
-						handleBrowserPick(path);
-					}
+					onOpen: handleBrowserPick
 				})
 			] });
 		}
@@ -1238,20 +1838,29 @@ 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 读取参考，禁止修改其中文件",
 			"list.remove": "移除",
 			"list.remove.aria": "移除参考库 {name}",
 			"list.empty": "还没有参考库",
-			"list.empty.hint": "在下方输入目录路径，或点击「选择目录」从系统选择",
+			"list.empty.hint": "在下方输入目录路径，或点击「浏览」选择目录",
 			"list.loading": "正在加载…",
+			"detail.open": "查看详情",
+			"detail.open.aria": "查看 {name} 的详情",
+			"detail.path": "路径",
+			"detail.cancel": "取消",
+			"detail.save": "保存",
 			"add.label": "添加参考库",
 			"add.placeholder": "输入目录路径（支持 ~ 与相对）",
 			"add.submit": "添加",
-			"add.manual": "或手动输入路径",
-			"add.browse": "选择目录",
-			"add.hint": "目录仅作只读参考；位于工作区之外时由系统强制只读",
+			"add.browse": "浏览",
+			"add.note.label": "用途说明",
+			"add.note.placeholder": "用途说明（可选，帮助 agent 判断相关性）",
+			"add.hint": "目录仅作只读参考；用途不填时自动提取 README 标题",
 			"browser.title": "选择目录",
 			"browser.home": "主目录",
 			"browser.open": "选择此目录",
@@ -1265,27 +1874,41 @@ 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",
 			"list.remove": "Remove",
 			"list.remove.aria": "Remove reference library {name}",
 			"list.empty": "No reference libraries yet",
-			"list.empty.hint": "Enter a directory path below, or click “Choose directory” to pick one",
+			"list.empty.hint": "Enter a directory path below, or click “Browse” to pick one",
 			"list.loading": "Loading…",
+			"detail.open": "View details",
+			"detail.open.aria": "View details of {name}",
+			"detail.path": "Path",
+			"detail.cancel": "Cancel",
+			"detail.save": "Save",
 			"add.label": "Add a reference library",
 			"add.placeholder": "Enter a directory path (~ or relative)",
 			"add.submit": "Add",
-			"add.manual": "or enter a path manually",
-			"add.browse": "Choose directory",
-			"add.hint": "Directories are read-only references; outside the workspace they are enforced read-only by the system",
+			"add.browse": "Browse",
+			"add.note.label": "Description",
+			"add.note.placeholder": "Description (optional; helps the agent judge relevance)",
+			"add.hint": "Directories are read-only references; if no description is given, the README title is used",
 			"browser.title": "Select Directory",
 			"browser.home": "Home",
 			"browser.open": "Select this folder",
@@ -1299,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
@@ -1344,10 +1972,11 @@ window.__ModuleLoader__.load({
 			}), "ref-lib: dictionaries");
 			const injected = () => ({
 				load: async (sessionId) => parseLibsPayload(await api(`/list?session=${encodeURIComponent(sessionId)}`, void 0, "GET")),
-				add: async (sessionId, path) => {
+				add: async (sessionId, path, note) => {
 					await api("/add", {
 						session: sessionId,
-						path
+						path,
+						...note === void 0 ? {} : { note }
 					});
 				},
 				remove: async (sessionId, id) => {
@@ -1356,6 +1985,13 @@ window.__ModuleLoader__.load({
 						id
 					});
 				},
+				setNote: async (sessionId, id, note) => {
+					await api("/note", {
+						session: sessionId,
+						id,
+						note
+					});
+				},
 				pickDirectory: () => ctx.workspaces.pickDirectory(),
 				listDirectory: (path, signal) => ctx.workspaces.listDirectory(path, signal)
 			});
@@ -1366,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;