@hpyperry/dsh-ref-lib 0.7.0 → 0.8.0

package/lib/client.js

@@ -313,31 +313,63 @@ window.__ModuleLoader__.load({
 		* 本组件为纯展示：异步操作与错误归集由 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, onBrowse } = 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("");
+				if (!open) {
+					setDraft("");
+					setNoteDraft("");
+					setDetailId(null);
+				}
 			}, [open]);
 			const handleSubmit = async () => {
 				const trimmed = draft.trim();
 				if (trimmed === "") return;
 				try {
-					await onAddPath(trimmed);
+					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: [
@@ -380,45 +412,144 @@ window.__ModuleLoader__.load({
 							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-row",
+									className: "reflib-listItem",
 									"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 })
+									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);
 							})
 						}),
@@ -430,49 +561,65 @@ window.__ModuleLoader__.load({
 									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-addBrowseMain",
-									icon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconSearchOutline16, { size: 16 }),
-									disabled: busy || picking,
+									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: () => {
-										onBrowse();
+										handleSubmit();
 									},
-									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")
-										})]
-									})]
+									children: t("add.submit")
 								}),
 								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 									className: "reflib-addHint",
@@ -763,6 +910,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 +931,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;
 }
@@ -817,6 +970,16 @@ window.__ModuleLoader__.load({
   white-space: nowrap;
 }
 
+/* 列表行用途说明（Description，v8）：单行截断，与路径同属次行层级 */
+.reflib-rowNote {
+  overflow: hidden;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  line-height: 16px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .reflib-rowRemove {
   display: inline-flex;
   align-items: center;
@@ -843,6 +1006,120 @@ window.__ModuleLoader__.load({
   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-noteTextarea:disabled {
+  opacity: 0.5;
+}
+
+.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;
+}
+
 /* 空态 / 加载态 / 错误态 */
 .reflib-status {
   display: flex;
@@ -908,9 +1185,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 +1221,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 +1242,18 @@ window.__ModuleLoader__.load({
   line-height: 18px;
 }
 
+/* 全宽「添加」主按钮 */
+.reflib-addSubmit {
+  width: 100%;
+}
+
 .reflib-addHint {
   font-size: 11px;
   line-height: 16px;
   color: var(--dsw-alias-label-caption);
 }
 
-/* 窄视口：主路径行换行，输入框占满一行 */
+/* 窄视口：路径行换行，输入框占满一行 */
 @media (max-width: 440px) {
   .reflib-addRow {
     flex-wrap: wrap;
@@ -1045,7 +1327,7 @@ window.__ModuleLoader__.load({
 		* @returns 胶囊入口（+ 打开时的管理面板）。
 		*/
 		function RefLibDock(props) {
-			const { sessionId, load, add, remove, pickDirectory, listDirectory, t } = props;
+			const { sessionId, 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);
@@ -1056,6 +1338,7 @@ window.__ModuleLoader__.load({
 			const seq = (0, react.useRef)(0);
 			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;
@@ -1106,11 +1389,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,47 +1402,59 @@ 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);
 			};
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -1207,18 +1502,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
 				})
 			] });
 		}
@@ -1244,14 +1536,20 @@ window.__ModuleLoader__.load({
 			"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": "选择此目录",
@@ -1278,14 +1576,20 @@ window.__ModuleLoader__.load({
 			"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",
@@ -1344,10 +1648,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 +1661,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)
 			});