@dsh-plus/secret-env 0.1.0 → 0.1.1

package/lib/client.js

@@ -555,6 +555,8 @@ ${extra}
 			scopeGlobal: "全局",
 			scopeSession: "会话",
 			scopeOnce: "一次性",
+			"menu.title": "密钥变量",
+			"menu.aria": "密钥变量候选",
 			"error.invalid-name": "变量名不合法：大写字母开头，仅字母/数字/下划线，≤64 字符。",
 			"error.empty-value": "值不能为空。",
 			"error.shadowed": "进程环境中已存在同名变量且优先级更高，写入无效；请先取消该环境变量。",
@@ -601,6 +603,8 @@ ${extra}
 			scopeGlobal: "global",
 			scopeSession: "session",
 			scopeOnce: "once",
+			"menu.title": "Secret variables",
+			"menu.aria": "Secret variable suggestions",
 			"error.invalid-name": "Invalid name: start with an uppercase letter; letters/digits/underscore only, ≤64 chars.",
 			"error.empty-value": "Value must not be empty.",
 			"error.shadowed": "A same-named process environment variable shadows this write; unset it first.",
@@ -612,6 +616,300 @@ ${extra}
 		const zh = mergeDict(commonZh, ownZh);
 		const en = mergeDict(commonEn, ownEn);
 		//#endregion
+		//#region src/client/menu-core.ts
+		const WORD_CHAR = /[\p{L}\p{N}_]/u;
+		const TOKEN_CHAR = /^[A-Za-z0-9_]$/;
+		/**
+		* 检测光标处的 `$` 触发令牌。词法：
+		* - 从光标向左扫描，token 字符（字母/数字/下划线）继续，空白直接判负；
+		* - 遇到 `$` 时校验词边界：起草开头 / 前字符为空白 / 前字符为非词字符（标点）
+		*   才开闸——`foo$BAR` 这类词中 $ 不触发（与官方 URL 内 / 不触发同理）；
+		* - 其余字符（如 `{`、`(`）终止扫描。
+		*/
+		function detectSecretTrigger(draft, caret) {
+			if (caret <= 0 || caret > draft.length) return null;
+			for (let i = caret - 1; i >= 0; i--) {
+				const ch = draft.charAt(i);
+				if (/\s/u.test(ch)) return null;
+				if (ch !== "$") {
+					if (!TOKEN_CHAR.test(ch)) return null;
+					continue;
+				}
+				if (i > 0) {
+					const prev = draft.charAt(i - 1);
+					if (!/\s/u.test(prev) && WORD_CHAR.test(prev)) return null;
+				}
+				return {
+					query: draft.slice(i + 1, caret),
+					start: i,
+					end: caret
+				};
+			}
+			return null;
+		}
+		/** 两个命中的等价判定（抑制重复 setState）。 */
+		function sameHit(a, b) {
+			if (a === null || b === null) return a === b;
+			return a.query === b.query && a.start === b.start && a.end === b.end;
+		}
+		/** 按 query 过滤候选（大小写不敏感；变量名前缀命中排前，其余子串命中随后）。 */
+		function filterCandidates(entries, query) {
+			const q = query.toUpperCase();
+			const prefixed = [];
+			const partial = [];
+			for (const entry of entries) {
+				if (q === "") {
+					prefixed.push(entry);
+					continue;
+				}
+				if (entry.envName.toUpperCase().includes(q) || entry.name.toUpperCase().includes(q)) {
+					if (entry.name.toUpperCase().startsWith(q) || entry.envName.toUpperCase().includes(`_${q}`)) prefixed.push(entry);
+					else partial.push(entry);
+				}
+			}
+			return [...prefixed, ...partial];
+		}
+		/**
+		* 渲染文本偏移 → 草稿投影偏移。contenteditable 中芯片（引用装饰器）的
+		* 渲染文本与其草稿投影长度不等，光标渲染偏移需逐芯片修正。
+		*/
+		function applyChipCorrection(renderedOffset, chipsBeforeCaret) {
+			let offset = renderedOffset;
+			for (const chip of chipsBeforeCaret) offset -= chip.rendered - chip.draft;
+			return Math.max(0, offset);
+		}
+		//#endregion
+		//#region src/client/menu.tsx
+		/**
+		* `$` 触发补全菜单（conversation.input.overlay 官方插槽，session 作用域）：
+		* 在 composer 中输入 `$` 弹出密钥名候选（对齐官方 / 命令与 @ 引用的交互）。
+		*
+		* 官方 input-trigger 管线的检测核硬编码 '/' 与 '@'（TriggerChar 联合类型），
+		* '$' 进不了官方检测，故检测与菜单由本组件自理，插入复用官方会话作用域
+		* bail 通道 'slash/input-insert-text'（span + draftRev CAS，编辑器内应用）。
+		* @module secret-env/client/menu
+		*/
+		const FALLBACK_INPUT = {
+			draft: "",
+			draftRev: 0,
+			phase: "plain",
+			occurrences: []
+		};
+		/** 本组件容器向上找到 composer 卡片与 Lexical contenteditable 根。 */
+		function editorRootOf(el) {
+			const root = (el?.closest("[data-composer-card]"))?.querySelector("[contenteditable=\"true\"]");
+			return root instanceof HTMLElement ? root : null;
+		}
+		/**
+		* 光标的草稿投影偏移：Range 求光标前渲染文本长，再按光标前的引用芯片
+		* （data-composer-chip，DOM 序与 occurrences 的 offset 序一致）修正长度差。
+		*/
+		function caretDraftOffset(root, occurrences) {
+			const sel = window.getSelection();
+			if (sel === null || sel.rangeCount === 0 || !sel.isCollapsed) return null;
+			const range = sel.getRangeAt(0);
+			if (!root.contains(range.startContainer)) return null;
+			const pre = document.createRange();
+			pre.selectNodeContents(root);
+			pre.setEnd(range.startContainer, range.startOffset);
+			const rendered = pre.toString().length;
+			const corrections = [];
+			const chips = root.querySelectorAll("[data-composer-chip]");
+			for (let i = 0; i < chips.length; i++) {
+				const el = chips[i];
+				if (range.comparePoint(el, el.childNodes.length) > 0) continue;
+				const occurrence = occurrences[i];
+				if (occurrence === void 0) continue;
+				corrections.push({
+					rendered: el.textContent?.length ?? 0,
+					draft: occurrence.length
+				});
+			}
+			return applyChipCorrection(rendered, corrections);
+		}
+		function toCandidates(list) {
+			return [...list.session.map((entry) => ({
+				envName: entry.envName,
+				name: entry.name,
+				description: entry.description,
+				scope: "session",
+				once: entry.once
+			})), ...list.global.map((entry) => ({
+				envName: entry.envName,
+				name: entry.name,
+				description: entry.description,
+				scope: "global"
+			}))];
+		}
+		function SecretMenu(props) {
+			const { sessionId, t, insertToken } = props;
+			const input = (props.useInput ?? ((_selector) => FALLBACK_INPUT))((state) => state);
+			const [hit, setHit] = (0, react.useState)(null);
+			const [items, setItems] = (0, react.useState)(null);
+			const [highlight, setHighlight] = (0, react.useState)(0);
+			const wrapRef = (0, react.useRef)(null);
+			const composingRef = (0, react.useRef)(false);
+			/** Esc 抑制：记录被关闭的令牌，token 变化前不重复弹出。 */
+			const suppressedRef = (0, react.useRef)(null);
+			/** 候选拉取（ref 稳定；挂载、会话切换与菜单展开沿调用）。 */
+			const reloadRef = (0, react.useRef)((_sid) => {});
+			reloadRef.current = (sid) => {
+				fetchSecrets(sid).then((list) => setItems(toCandidates(list))).catch(() => setItems([]));
+			};
+			/** 上一次检测的展开态（展开沿判定用）。 */
+			const wasOpenRef = (0, react.useRef)(false);
+			(0, react.useEffect)(() => {
+				reloadRef.current(sessionId);
+			}, [sessionId]);
+			(0, react.useEffect)(() => {
+				const update = () => {
+					const root = editorRootOf(wrapRef.current);
+					if (root === null || composingRef.current || input.phase !== "plain") {
+						setHit((prev) => prev === null ? prev : null);
+						wasOpenRef.current = false;
+						return;
+					}
+					const caret = caretDraftOffset(root, input.occurrences);
+					const next = caret === null ? null : detectSecretTrigger(input.draft, caret);
+					const suppressed = suppressedRef.current;
+					const live = next !== null && suppressed !== null && next.start === suppressed.start && next.query === suppressed.query ? null : next;
+					if (live !== null && !wasOpenRef.current) reloadRef.current(sessionId);
+					wasOpenRef.current = live !== null;
+					setHit((prev) => sameHit(prev, live) ? prev : live);
+				};
+				update();
+				document.addEventListener("selectionchange", update);
+				return () => document.removeEventListener("selectionchange", update);
+			}, [input, sessionId]);
+			const candidates = hit === null || items === null ? [] : filterCandidates(items, hit.query);
+			const open = hit !== null && candidates.length > 0;
+			(0, react.useEffect)(() => {
+				const root = editorRootOf(wrapRef.current);
+				if (root === null) return;
+				const onStart = () => {
+					composingRef.current = true;
+				};
+				const onEnd = () => {
+					composingRef.current = false;
+				};
+				root.addEventListener("compositionstart", onStart);
+				root.addEventListener("compositionend", onEnd);
+				return () => {
+					root.removeEventListener("compositionstart", onStart);
+					root.removeEventListener("compositionend", onEnd);
+				};
+			}, []);
+			const pick = (entry) => {
+				if (hit === null) return;
+				const span = {
+					start: hit.start,
+					end: hit.end,
+					draftRev: input.draftRev
+				};
+				insertToken(`$${entry.envName} `, span);
+				suppressedRef.current = null;
+				setHit(null);
+			};
+			const pickRef = (0, react.useRef)(pick);
+			pickRef.current = pick;
+			const candidatesRef = (0, react.useRef)(candidates);
+			candidatesRef.current = candidates;
+			const highlightRef = (0, react.useRef)(highlight);
+			highlightRef.current = highlight;
+			(0, react.useEffect)(() => {
+				if (!open) return;
+				const root = editorRootOf(wrapRef.current);
+				if (root === null) return;
+				const onKey = (event) => {
+					const list = candidatesRef.current;
+					if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+						event.preventDefault();
+						event.stopPropagation();
+						const delta = event.key === "ArrowDown" ? 1 : -1;
+						setHighlight((prev) => (prev + delta + list.length) % list.length);
+						return;
+					}
+					if (event.key === "Enter" || event.key === "Tab") {
+						const entry = list[highlightRef.current] ?? list[0];
+						if (entry !== void 0) {
+							event.preventDefault();
+							event.stopPropagation();
+							pickRef.current(entry);
+						}
+						return;
+					}
+					if (event.key === "Escape") {
+						event.preventDefault();
+						event.stopPropagation();
+						suppressedRef.current = hit;
+						setHit(null);
+					}
+				};
+				root.addEventListener("keydown", onKey, true);
+				return () => root.removeEventListener("keydown", onKey, true);
+			}, [open, hit]);
+			(0, react.useEffect)(() => {
+				if (!open) return;
+				const onDown = (event) => {
+					if (!(event.target instanceof Node)) return;
+					if ((wrapRef.current?.closest("[data-composer-card]"))?.contains(event.target) === true) return;
+					setHit(null);
+				};
+				document.addEventListener("pointerdown", onDown, true);
+				return () => document.removeEventListener("pointerdown", onDown, true);
+			}, [open]);
+			(0, react.useEffect)(() => {
+				setHighlight((prev) => candidates.length === 0 ? 0 : Math.min(prev, candidates.length - 1));
+			}, [candidates.length]);
+			if (!open) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "dse-menuWrap",
+				ref: wrapRef
+			});
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "dse-menuWrap",
+				ref: wrapRef,
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "dse-menu",
+					role: "listbox",
+					"aria-label": t("menu.aria"),
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dse-menuTitle",
+						children: t("menu.title")
+					}), candidates.map((entry, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+						type: "button",
+						role: "option",
+						"aria-selected": index === highlight,
+						className: `dse-menuItem${index === highlight ? " dse-menuItemActive" : ""}`,
+						onMouseEnter: () => setHighlight(index),
+						onMouseDown: (event) => {
+							event.preventDefault();
+							pick(entry);
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								className: "dse-menuName",
+								children: ["$", entry.envName]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "dse-menuDesc",
+								children: entry.description
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								className: "dse-menuBadges",
+								children: [entry.once === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "dse-badge",
+									children: t("scopeOnce")
+								}) : null, /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "dse-badge dse-badgeDim",
+									children: entry.scope === "session" ? t("scopeSession") : t("scopeGlobal")
+								})]
+							})
+						]
+					}, `${entry.scope}:${entry.name}`))]
+				})
+			});
+		}
+		//#endregion
 		//#region src/client/section.tsx
 		/**
 		* 密钥变量设置页（settings.section 官方插槽）：全局密钥的列表与增删。
@@ -934,7 +1232,21 @@ ${extra}
 .dse-popList .dse-row+.dse-row{border-top:1px solid var(--dsw-alias-border-l2)}
 .dse-popForm{border-top:1px solid var(--dsw-alias-border-l2);margin-top:8px;padding-top:4px}
 .dse-foot{justify-content:flex-end;gap:8px;display:flex;padding-top:8px}
-/* 响应式：窄屏表格转堆叠，popover 转底部抽屉 */
+/* $ 触发补全菜单（仿官方 input-trigger MenuView 的浮层语言） */
+.dse-menuWrap{position:relative}
+.dse-menu{position:absolute;bottom:calc(100% + 6px);left:8px;z-index:60;min-width:280px;max-width:min(420px,calc(100vw - 32px));max-height:320px;overflow:auto;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;box-shadow:0 8px 28px rgba(0,0,0,.18);padding:4px}
+.dse-menuTitle{color:var(--dsw-alias-label-tertiary);font-size:11px;font-weight:600;padding:6px 10px 4px}
+.dse-menuItem{appearance:none;border:none;background:0 0;cursor:pointer;align-items:center;gap:8px;width:100%;padding:7px 10px;border-radius:8px;display:flex;text-align:left}
+.dse-menuItem:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dse-menuItemActive{background:var(--dsw-alias-interactive-bg-hover)}
+.dse-menuName{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--dsw-alias-label-primary);font-size:13px;flex:none}
+.dse-menuDesc{color:var(--dsw-alias-label-tertiary);font-size:12px;flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dse-menuBadges{align-items:center;gap:4px;flex:none;display:flex}
+@media (max-width:767px){
+.dse-menu{left:0;right:0;min-width:0;max-width:none;max-height:45vh}
+.dse-menuItem{min-height:44px}
+}
+
 @media (max-width:767px){
 .dse-formGrid{grid-template-columns:1fr}
 .dse-row{flex-wrap:wrap;padding:12px 12px}
@@ -956,7 +1268,11 @@ ${extra}
 		//#region src/client/client.ts
 		const name = "dsh-plus-secret-env";
 		/** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
-		const inject = ["slots", "locale"];
+		const inject = [
+			"slots",
+			"locale",
+			"sessions"
+		];
 		function apply(ctx) {
 			const c = ctx;
 			const styleTag = injectSecretEnvStyle("@dsh-plus/secret-env");
@@ -982,6 +1298,27 @@ ${extra}
 				locale: NS,
 				inject: (sessionId) => ({ sessionId })
 			}, ComposerSecret));
+			c.slots.inject("conversation.input.overlay", () => c.slots.register({
+				name: "conversation.input.overlay",
+				id: "dse-secret-menu",
+				order: 10,
+				locale: NS,
+				inject: (sessionId) => ({
+					sessionId,
+					insertToken: (text, span) => {
+						const actx = c.sessions.scope(sessionId);
+						if (actx === void 0) return false;
+						return actx.bail(actx, "slash/input-insert-text", {
+							text,
+							span: {
+								start: span.start,
+								end: span.end,
+								draftRev: span.draftRev
+							}
+						}) === true;
+					}
+				})
+			}, SecretMenu));
 		}
 		//#endregion
 		exports.apply = apply;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/secret-env",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "dsh-plus service+ui plugin: 密钥环境变量——以 $DSH_SECRET_* 变量名向 agent 暴露密钥（全局持久/会话级/一次性），执行期经 dsh-shell-env 原生注入，值不进消息流，不影响缓存率",
   "type": "module",
   "main": "lib/index.js",
@@ -50,7 +50,9 @@
       "inject": [
         "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-api-remotes"
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-ui-conversation"
       ],
       "platform": "web"
     }

package/src/client/client.ts

@@ -10,13 +10,14 @@ import type { Context } from '@deepseek-ai/cordis'
 
 import { ComposerSecret } from './composer.tsx'
 import { en, NS, zh } from './i18n.ts'
+import { SecretMenu, type TokenSpanLike } from './menu.tsx'
 import { SecretsSection } from './section.tsx'
 import { injectSecretEnvStyle } from './styles.ts'
 
 export const name = 'dsh-plus-secret-env'
 
 /** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
-export const inject = ['slots', 'locale'] as const
+export const inject = ['slots', 'locale', 'sessions'] as const
 
 interface SlotsLike {
   inject(key: string, callback: () => unknown): unknown
@@ -28,9 +29,19 @@ interface LocaleLike {
   bind(ns: string): (key: string) => string
 }
 
+/** 会话作用域句柄的结构子集（dsh-api-session-controller 客户端 sessions 服务）。 */
+interface SessionScopeLike {
+  bail(subject: unknown, event: string, payload: Record<string, unknown>): unknown
+}
+
+interface SessionsLike {
+  scope(sessionId: string): SessionScopeLike | undefined
+}
+
 interface ClientContext {
   slots: SlotsLike
   locale: LocaleLike
+  sessions: SessionsLike
   effect(execute: () => () => void, label?: string): unknown
 }
 
@@ -74,4 +85,31 @@ export function apply(ctx: Context): void {
       ComposerSecret,
     ),
   )
+
+  // `$` 触发补全菜单（conversation.input.overlay：composer 卡片内浮层）。
+  // 插入走官方会话作用域 bail 通道 slash/input-insert-text（span+draftRev CAS）。
+  c.slots.inject('conversation.input.overlay', () =>
+    c.slots.register(
+      {
+        name: 'conversation.input.overlay',
+        id: 'dse-secret-menu',
+        order: 10,
+        locale: NS,
+        inject: (sessionId: string) => ({
+          sessionId,
+          insertToken: (text: string, span: TokenSpanLike): boolean => {
+            const actx = c.sessions.scope(sessionId)
+            if (actx === undefined) return false
+            return (
+              actx.bail(actx, 'slash/input-insert-text', {
+                text,
+                span: { start: span.start, end: span.end, draftRev: span.draftRev },
+              }) === true
+            )
+          },
+        }),
+      },
+      SecretMenu,
+    ),
+  )
 }

package/src/client/i18n.ts

@@ -47,6 +47,9 @@ const ownZh = {
   scopeGlobal: '全局',
   scopeSession: '会话',
   scopeOnce: '一次性',
+  // `$` 触发补全菜单
+  'menu.title': '密钥变量',
+  'menu.aria': '密钥变量候选',
   // 错误码
   'error.invalid-name': '变量名不合法：大写字母开头，仅字母/数字/下划线，≤64 字符。',
   'error.empty-value': '值不能为空。',
@@ -98,6 +101,8 @@ const ownEn = {
   scopeGlobal: 'global',
   scopeSession: 'session',
   scopeOnce: 'once',
+  'menu.title': 'Secret variables',
+  'menu.aria': 'Secret variable suggestions',
   'error.invalid-name':
     'Invalid name: start with an uppercase letter; letters/digits/underscore only, ≤64 chars.',
   'error.empty-value': 'Value must not be empty.',

package/src/client/menu-core.ts

@@ -0,0 +1,103 @@
+/**
+ * `$` 触发补全的纯核心（零 DOM / React / cordis，node 直接单测）：
+ * - detectSecretTrigger：光标处 `$<query>` 命中检测（边界规则对齐官方
+ *   input-trigger 的 / 与 @：起草开头、空白后、标点后开闸；词中 $ 不触发）；
+ * - filterCandidates：按 query 过滤+排序（前缀命中优先）；
+ * - applyChipCorrection：渲染文本偏移 → 草稿投影偏移的芯片修正。
+ * @module secret-env/client/menu-core
+ */
+
+/** 一次 `$` 命中：query 为 $ 到光标间的文本，[start, end) 为草稿投影中的令牌区间。 */
+export interface SecretHit {
+  readonly query: string
+  readonly start: number
+  readonly end: number
+}
+
+/** 菜单候选项（全局与会话密钥的统一视图，纯展示数据）。 */
+export interface SecretCandidate {
+  readonly envName: string
+  readonly name: string
+  readonly description: string
+  readonly scope: 'global' | 'session'
+  readonly once?: boolean
+}
+
+const WORD_CHAR = /[\p{L}\p{N}_]/u
+const TOKEN_CHAR = /^[A-Za-z0-9_]$/
+
+/**
+ * 检测光标处的 `$` 触发令牌。词法：
+ * - 从光标向左扫描，token 字符（字母/数字/下划线）继续，空白直接判负；
+ * - 遇到 `$` 时校验词边界：起草开头 / 前字符为空白 / 前字符为非词字符（标点）
+ *   才开闸——`foo$BAR` 这类词中 $ 不触发（与官方 URL 内 / 不触发同理）；
+ * - 其余字符（如 `{`、`(`）终止扫描。
+ */
+export function detectSecretTrigger(draft: string, caret: number): SecretHit | null {
+  if (caret <= 0 || caret > draft.length) return null
+  for (let i = caret - 1; i >= 0; i--) {
+    const ch = draft.charAt(i)
+    if (/\s/u.test(ch)) return null
+    if (ch !== '$') {
+      if (!TOKEN_CHAR.test(ch)) return null
+      continue
+    }
+    if (i > 0) {
+      const prev = draft.charAt(i - 1)
+      if (!/\s/u.test(prev) && WORD_CHAR.test(prev)) return null
+    }
+    return { query: draft.slice(i + 1, caret), start: i, end: caret }
+  }
+  return null
+}
+
+/** 两个命中的等价判定（抑制重复 setState）。 */
+export function sameHit(a: SecretHit | null, b: SecretHit | null): boolean {
+  if (a === null || b === null) return a === b
+  return a.query === b.query && a.start === b.start && a.end === b.end
+}
+
+/** 按 query 过滤候选（大小写不敏感；变量名前缀命中排前，其余子串命中随后）。 */
+export function filterCandidates(
+  entries: readonly SecretCandidate[],
+  query: string,
+): SecretCandidate[] {
+  const q = query.toUpperCase()
+  const prefixed: SecretCandidate[] = []
+  const partial: SecretCandidate[] = []
+  for (const entry of entries) {
+    if (q === '') {
+      prefixed.push(entry)
+      continue
+    }
+    if (entry.envName.toUpperCase().includes(q) || entry.name.toUpperCase().includes(q)) {
+      if (entry.name.toUpperCase().startsWith(q) || entry.envName.toUpperCase().includes(`_${q}`)) {
+        prefixed.push(entry)
+      } else {
+        partial.push(entry)
+      }
+    }
+  }
+  return [...prefixed, ...partial]
+}
+
+/** 一处芯片修正对：光标前芯片的渲染文本长与草稿投影长。 */
+export interface ChipCorrection {
+  readonly rendered: number
+  readonly draft: number
+}
+
+/**
+ * 渲染文本偏移 → 草稿投影偏移。contenteditable 中芯片（引用装饰器）的
+ * 渲染文本与其草稿投影长度不等，光标渲染偏移需逐芯片修正。
+ */
+export function applyChipCorrection(
+  renderedOffset: number,
+  chipsBeforeCaret: readonly ChipCorrection[],
+): number {
+  let offset = renderedOffset
+  for (const chip of chipsBeforeCaret) {
+    offset -= chip.rendered - chip.draft
+  }
+  return Math.max(0, offset)
+}

package/src/client/menu.tsx

@@ -0,0 +1,285 @@
+/**
+ * `$` 触发补全菜单（conversation.input.overlay 官方插槽，session 作用域）：
+ * 在 composer 中输入 `$` 弹出密钥名候选（对齐官方 / 命令与 @ 引用的交互）。
+ *
+ * 官方 input-trigger 管线的检测核硬编码 '/' 与 '@'（TriggerChar 联合类型），
+ * '$' 进不了官方检测，故检测与菜单由本组件自理，插入复用官方会话作用域
+ * bail 通道 'slash/input-insert-text'（span + draftRev CAS，编辑器内应用）。
+ * @module secret-env/client/menu
+ */
+import { type ReactElement, useEffect, useRef, useState } from 'react'
+
+import { fetchSecrets, type SecretList } from './api.ts'
+import {
+  applyChipCorrection,
+  type ChipCorrection,
+  detectSecretTrigger,
+  filterCandidates,
+  type SecretCandidate,
+  type SecretHit,
+  sameHit,
+} from './menu-core.ts'
+
+/** 输入状态投影（结构子集；官方 InputState 的读取面）。 */
+interface InputStateLike {
+  readonly draft: string
+  readonly draftRev: number
+  readonly phase: string
+  readonly occurrences: readonly { readonly offset: number; readonly length: number }[]
+}
+
+/** 令牌区间（草稿投影坐标 + 单调修订号，CAS 用）。 */
+export interface TokenSpanLike {
+  readonly start: number
+  readonly end: number
+  readonly draftRev: number
+}
+
+export interface SecretMenuProps {
+  /** 插槽 inject 工厂注入的当前会话 id。 */
+  sessionId: string
+  t(key: string): string
+  /** 框架标准钩子：输入状态快照订阅（SnapshotSelectorHook）。 */
+  useInput?<S>(selector: (state: InputStateLike) => S): S
+  /** inject 面注入：经官方 scoped bail 通道替换令牌文本；返回是否被编辑器应用。 */
+  insertToken(text: string, span: TokenSpanLike): boolean
+}
+
+const FALLBACK_INPUT: InputStateLike = { draft: '', draftRev: 0, phase: 'plain', occurrences: [] }
+
+/** 本组件容器向上找到 composer 卡片与 Lexical contenteditable 根。 */
+function editorRootOf(el: HTMLElement | null): HTMLElement | null {
+  const card = el?.closest('[data-composer-card]')
+  const root = card?.querySelector('[contenteditable="true"]')
+  return root instanceof HTMLElement ? root : null
+}
+
+/**
+ * 光标的草稿投影偏移：Range 求光标前渲染文本长，再按光标前的引用芯片
+ * （data-composer-chip，DOM 序与 occurrences 的 offset 序一致）修正长度差。
+ */
+function caretDraftOffset(
+  root: HTMLElement,
+  occurrences: InputStateLike['occurrences'],
+): number | null {
+  const sel = window.getSelection()
+  if (sel === null || sel.rangeCount === 0 || !sel.isCollapsed) return null
+  const range = sel.getRangeAt(0)
+  if (!root.contains(range.startContainer)) return null
+  const pre = document.createRange()
+  pre.selectNodeContents(root)
+  pre.setEnd(range.startContainer, range.startOffset)
+  const rendered = pre.toString().length
+  const corrections: ChipCorrection[] = []
+  const chips = root.querySelectorAll('[data-composer-chip]')
+  for (let i = 0; i < chips.length; i++) {
+    const el = chips[i]
+    // 光标位于芯片结束之后（含边界）才计入修正
+    if (range.comparePoint(el, el.childNodes.length) > 0) continue
+    const occurrence = occurrences[i]
+    if (occurrence === undefined) continue
+    corrections.push({ rendered: el.textContent?.length ?? 0, draft: occurrence.length })
+  }
+  return applyChipCorrection(rendered, corrections)
+}
+
+function toCandidates(list: SecretList): SecretCandidate[] {
+  return [
+    ...list.session.map((entry) => ({
+      envName: entry.envName,
+      name: entry.name,
+      description: entry.description,
+      scope: 'session' as const,
+      once: entry.once,
+    })),
+    ...list.global.map((entry) => ({
+      envName: entry.envName,
+      name: entry.name,
+      description: entry.description,
+      scope: 'global' as const,
+    })),
+  ]
+}
+
+export function SecretMenu(props: SecretMenuProps): ReactElement | null {
+  const { sessionId, t, insertToken } = props
+  // useInput 是标准钩子 prop，必须无条件调用；旧壳缺席时回落常量（菜单永不展开）。
+  const useInput =
+    props.useInput ?? (<S,>(_selector: (state: InputStateLike) => S): S => FALLBACK_INPUT as S)
+  const input = useInput((state: InputStateLike) => state)
+
+  const [hit, setHit] = useState<SecretHit | null>(null)
+  const [items, setItems] = useState<SecretCandidate[] | null>(null)
+  const [highlight, setHighlight] = useState(0)
+  const wrapRef = useRef<HTMLDivElement | null>(null)
+  const composingRef = useRef(false)
+  /** Esc 抑制：记录被关闭的令牌，token 变化前不重复弹出。 */
+  const suppressedRef = useRef<SecretHit | null>(null)
+
+  /** 候选拉取（ref 稳定；挂载、会话切换与菜单展开沿调用）。 */
+  const reloadRef = useRef((_sid: string): void => {})
+  reloadRef.current = (sid: string) => {
+    fetchSecrets(sid)
+      .then((list) => setItems(toCandidates(list)))
+      .catch(() => setItems([]))
+  }
+  /** 上一次检测的展开态（展开沿判定用）。 */
+  const wasOpenRef = useRef(false)
+
+  // 挂载与会话切换时拉取候选。
+  useEffect(() => {
+    reloadRef.current(sessionId)
+  }, [sessionId])
+
+  // 检测：草稿变化（每次击键）与光标移动（selectionchange）双通道驱动。
+  useEffect(() => {
+    const update = (): void => {
+      const root = editorRootOf(wrapRef.current)
+      if (root === null || composingRef.current || input.phase !== 'plain') {
+        setHit((prev) => (prev === null ? prev : null))
+        wasOpenRef.current = false
+        return
+      }
+      const caret = caretDraftOffset(root, input.occurrences)
+      const next = caret === null ? null : detectSecretTrigger(input.draft, caret)
+      const suppressed = suppressedRef.current
+      const live =
+        next !== null &&
+        suppressed !== null &&
+        next.start === suppressed.start &&
+        next.query === suppressed.query
+          ? null
+          : next
+      // 展开沿：闭合 → 命中时刷新候选（密钥可能刚在别处改动）。
+      if (live !== null && !wasOpenRef.current) reloadRef.current(sessionId)
+      wasOpenRef.current = live !== null
+      setHit((prev) => (sameHit(prev, live) ? prev : live))
+    }
+    update()
+    document.addEventListener('selectionchange', update)
+    return () => document.removeEventListener('selectionchange', update)
+  }, [input, sessionId])
+
+  const candidates = hit === null || items === null ? [] : filterCandidates(items, hit.query)
+  const open = hit !== null && candidates.length > 0
+
+  // IME 组合期间不介入（输入法键不应被菜单截获）。
+  useEffect(() => {
+    const root = editorRootOf(wrapRef.current)
+    if (root === null) return
+    const onStart = (): void => {
+      composingRef.current = true
+    }
+    const onEnd = (): void => {
+      composingRef.current = false
+    }
+    root.addEventListener('compositionstart', onStart)
+    root.addEventListener('compositionend', onEnd)
+    return () => {
+      root.removeEventListener('compositionstart', onStart)
+      root.removeEventListener('compositionend', onEnd)
+    }
+  }, [])
+
+  const pick = (entry: SecretCandidate): void => {
+    if (hit === null) return
+    const span = { start: hit.start, end: hit.end, draftRev: input.draftRev }
+    insertToken(`$${entry.envName} `, span)
+    suppressedRef.current = null
+    setHit(null)
+  }
+
+  const pickRef = useRef(pick)
+  pickRef.current = pick
+  const candidatesRef = useRef(candidates)
+  candidatesRef.current = candidates
+  const highlightRef = useRef(highlight)
+  highlightRef.current = highlight
+
+  // 键盘导航：捕获阶段先於 Lexical/官方管线截获；仅在菜单展开时介入。
+  useEffect(() => {
+    if (!open) return
+    const root = editorRootOf(wrapRef.current)
+    if (root === null) return
+    const onKey = (event: KeyboardEvent): void => {
+      const list = candidatesRef.current
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+        event.preventDefault()
+        event.stopPropagation()
+        const delta = event.key === 'ArrowDown' ? 1 : -1
+        setHighlight((prev) => (prev + delta + list.length) % list.length)
+        return
+      }
+      if (event.key === 'Enter' || event.key === 'Tab') {
+        const entry = list[highlightRef.current] ?? list[0]
+        if (entry !== undefined) {
+          event.preventDefault()
+          event.stopPropagation()
+          pickRef.current(entry)
+        }
+        return
+      }
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        event.stopPropagation()
+        suppressedRef.current = hit
+        setHit(null)
+      }
+    }
+    root.addEventListener('keydown', onKey, true)
+    return () => root.removeEventListener('keydown', onKey, true)
+  }, [open, hit])
+
+  // 点 composer 卡片之外处关闭（对齐官方菜单的外部 dismiss 语义）。
+  useEffect(() => {
+    if (!open) return
+    const onDown = (event: PointerEvent): void => {
+      if (!(event.target instanceof Node)) return
+      const card = wrapRef.current?.closest('[data-composer-card]')
+      if (card?.contains(event.target) === true) return
+      setHit(null)
+    }
+    document.addEventListener('pointerdown', onDown, true)
+    return () => document.removeEventListener('pointerdown', onDown, true)
+  }, [open])
+
+  // 高亮随候选集变化收敛到合法范围。
+  useEffect(() => {
+    setHighlight((prev) => (candidates.length === 0 ? 0 : Math.min(prev, candidates.length - 1)))
+  }, [candidates.length])
+
+  if (!open) {
+    // 锚点常驻：闭合态也要挂载容器，检测效果依赖它定位 composer 编辑器根。
+    return <div className="dse-menuWrap" ref={wrapRef} />
+  }
+  return (
+    <div className="dse-menuWrap" ref={wrapRef}>
+      <div className="dse-menu" role="listbox" aria-label={t('menu.aria')}>
+        <div className="dse-menuTitle">{t('menu.title')}</div>
+        {candidates.map((entry, index) => (
+          <button
+            key={`${entry.scope}:${entry.name}`}
+            type="button"
+            role="option"
+            aria-selected={index === highlight}
+            className={`dse-menuItem${index === highlight ? ' dse-menuItemActive' : ''}`}
+            onMouseEnter={() => setHighlight(index)}
+            onMouseDown={(event) => {
+              event.preventDefault()
+              pick(entry)
+            }}
+          >
+            <span className="dse-menuName">${entry.envName}</span>
+            <span className="dse-menuDesc">{entry.description}</span>
+            <span className="dse-menuBadges">
+              {entry.once === true ? <span className="dse-badge">{t('scopeOnce')}</span> : null}
+              <span className="dse-badge dse-badgeDim">
+                {entry.scope === 'session' ? t('scopeSession') : t('scopeGlobal')}
+              </span>
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/client/styles.ts

@@ -47,7 +47,21 @@ const EXTRA = `
 .dse-popList .dse-row+.dse-row{border-top:1px solid var(--dsw-alias-border-l2)}
 .dse-popForm{border-top:1px solid var(--dsw-alias-border-l2);margin-top:8px;padding-top:4px}
 .dse-foot{justify-content:flex-end;gap:8px;display:flex;padding-top:8px}
-/* 响应式：窄屏表格转堆叠，popover 转底部抽屉 */
+/* $ 触发补全菜单（仿官方 input-trigger MenuView 的浮层语言） */
+.dse-menuWrap{position:relative}
+.dse-menu{position:absolute;bottom:calc(100% + 6px);left:8px;z-index:60;min-width:280px;max-width:min(420px,calc(100vw - 32px));max-height:320px;overflow:auto;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;box-shadow:0 8px 28px rgba(0,0,0,.18);padding:4px}
+.dse-menuTitle{color:var(--dsw-alias-label-tertiary);font-size:11px;font-weight:600;padding:6px 10px 4px}
+.dse-menuItem{appearance:none;border:none;background:0 0;cursor:pointer;align-items:center;gap:8px;width:100%;padding:7px 10px;border-radius:8px;display:flex;text-align:left}
+.dse-menuItem:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dse-menuItemActive{background:var(--dsw-alias-interactive-bg-hover)}
+.dse-menuName{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--dsw-alias-label-primary);font-size:13px;flex:none}
+.dse-menuDesc{color:var(--dsw-alias-label-tertiary);font-size:12px;flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dse-menuBadges{align-items:center;gap:4px;flex:none;display:flex}
+@media (max-width:767px){
+.dse-menu{left:0;right:0;min-width:0;max-width:none;max-height:45vh}
+.dse-menuItem{min-height:44px}
+}
+
 @media (max-width:767px){
 .dse-formGrid{grid-template-columns:1fr}
 .dse-row{flex-wrap:wrap;padding:12px 12px}