@autopilot-agent/cli 0.0.0-stage → 0.2.0

package/dist/tui/hooks/use-prompt-input.js

@@ -0,0 +1,258 @@
+/** prompt 输入状态与 handleInput：字符串/光标/历史维护与按键分发。 */
+import { useRef, useState } from "react";
+import { parseSlashAction } from "../../parser.js";
+import { canNavigateTuiInputHistory, createTuiInputHistoryState, navigateTuiInputHistory, recordTuiInputHistory, updateTuiInputHistoryDraft, } from "../../tui-input-history.js";
+import { createTuiApprovalOptions } from "../approval.js";
+import { isActiveTuiStatus } from "../format.js";
+import { normalizeTuiInputLineEndings, splitTuiInputGraphemes } from "../input/graphemes.js";
+import { applyFileMentionSuggestion, extractFileMentionToken } from "../input/file-mention.js";
+import { hasTuiUnescapedContinuation, isTuiMultilineEnter, isTuiTerminalFocusSequence, isTuiViewportScrollKey, parseTuiControlAction, resolveTuiBracketedPasteBoundary, resolveTuiDeleteDirection, } from "../input/keys.js";
+import { createTuiPromptLayout, resolveTuiPromptCursorIndex } from "../input/prompt-layout.js";
+import { recordTuiPerformanceDiagnostic } from "../performance-diagnostics.js";
+/** 管理 prompt 输入状态、历史与按键分发，并暴露 handleInput 供 Ink 的 useInput 使用。 */
+export function usePromptInput(input) {
+    const { store, columns, busy, keepOpenAfterCancel, lastSubmittedPromptRef, rawInputSequenceRef, dispatchAction, onEof, onRequestInterrupt, onRequestCancel, isPickerActive, dispatchPickerInput, approvalPickerIndexRef, updateApprovalPickerIndex, slashCommandIndexRef, updateSlashCommandIndex, fileMentionIndexRef, updateFileMentionIndex, setFileMentionDismissedInput, derivedRef, } = input;
+    const [inputValue, setInput] = useState("");
+    const [cursorIndex, setCursorIndex] = useState(0);
+    const inputRef = useRef("");
+    const cursorIndexRef = useRef(0);
+    const verticalColumnRef = useRef(undefined);
+    const bracketedPasteRef = useRef(false);
+    const pasteCarriageReturnRef = useRef(false);
+    const inputHistoryRef = useRef(createTuiInputHistoryState());
+    /** 同步维护字符串与光标位置，避免只移动光标时 React 跳过重绘；输入变化即解除 @ 菜单的 Esc 关闭标记。 */
+    function updateInput(nextInput, nextCursorIndex) {
+        verticalColumnRef.current = undefined;
+        inputRef.current = nextInput;
+        cursorIndexRef.current = nextCursorIndex;
+        setFileMentionDismissedInput(undefined);
+        setInput(nextInput);
+        setCursorIndex(nextCursorIndex);
+    }
+    /** 只移动逻辑光标，不清除上下键要保持的目标视觉列。 */
+    function updateCursorIndex(nextCursorIndex) {
+        cursorIndexRef.current = nextCursorIndex;
+        setCursorIndex(nextCursorIndex);
+    }
+    /** 以当前 slash 菜单选项补全命令；带必填参数的命令保留一个输入空格。 */
+    function completeSlashCommand(command) {
+        const completion = command.usage.includes("<") ? `${command.name} ` : command.name;
+        updateInput(completion, splitTuiInputGraphemes(completion).length);
+    }
+    /** 按 Claude Code 的 Esc 恢复边界把最后一次发送的 prompt 放回本地输入框。 */
+    function restoreLastSubmittedPrompt() {
+        const current = store.getSnapshot();
+        const prompt = lastSubmittedPromptRef.current;
+        if (!prompt || inputRef.current !== "" || current.pendingInputs.length > 0)
+            return;
+        updateInput(prompt, splitTuiInputGraphemes(prompt).length);
+    }
+    function handleInput(value, key) {
+        recordTuiPerformanceDiagnostic("input_key_arrived", value && !key.ctrl && !key.meta ? "text" : "control");
+        const controlAction = parseTuiControlAction(value, key);
+        if (controlAction === "eof") {
+            onEof();
+            return;
+        }
+        const current = store.getSnapshot();
+        if (controlAction === "interrupt") {
+            if (isActiveTuiStatus(current.status))
+                keepOpenAfterCancel.current = true;
+            onRequestInterrupt();
+            return;
+        }
+        if (isTuiTerminalFocusSequence(value))
+            return;
+        const pasteBoundary = resolveTuiBracketedPasteBoundary(value);
+        if (pasteBoundary === "start") {
+            bracketedPasteRef.current = true;
+            pasteCarriageReturnRef.current = false;
+            return;
+        }
+        if (pasteBoundary === "end") {
+            bracketedPasteRef.current = false;
+            pasteCarriageReturnRef.current = false;
+            return;
+        }
+        if (isPickerActive) {
+            dispatchPickerInput(value, key, controlAction);
+            return;
+        }
+        if (controlAction === "cancel") {
+            // D3：@ 菜单激活时 Esc 仅关闭菜单，prompt 保留；再次 Esc 时菜单已关，走正常取消路径。
+            if (derivedRef.current.fileMentionSuggestions.length > 0) {
+                setFileMentionDismissedInput(inputRef.current);
+                return;
+            }
+            if (derivedRef.current.slashCommandSuggestions.length > 0) {
+                updateInput("", 0);
+                return;
+            }
+            if (isActiveTuiStatus(current.status)) {
+                keepOpenAfterCancel.current = true;
+                restoreLastSubmittedPrompt();
+            }
+            onRequestCancel();
+            return;
+        }
+        if (derivedRef.current.slashCommandSuggestions.length > 0) {
+            const slashCommandSuggestions = derivedRef.current.slashCommandSuggestions;
+            const selectedCommand = slashCommandSuggestions[Math.max(0, Math.min(slashCommandIndexRef.current, slashCommandSuggestions.length - 1))];
+            if (selectedCommand && (key.upArrow || key.downArrow)) {
+                const nextIndex = key.upArrow
+                    ? Math.max(0, slashCommandIndexRef.current - 1)
+                    : Math.min(slashCommandSuggestions.length - 1, slashCommandIndexRef.current + 1);
+                updateSlashCommandIndex(nextIndex);
+                return;
+            }
+            if (selectedCommand && key.tab) {
+                completeSlashCommand(selectedCommand);
+                return;
+            }
+            if (selectedCommand && key.return && inputRef.current.trim() !== selectedCommand.name) {
+                completeSlashCommand(selectedCommand);
+                return;
+            }
+            if (selectedCommand && key.return && selectedCommand.usage.includes("<")) {
+                completeSlashCommand(selectedCommand);
+                return;
+            }
+            if (isTuiViewportScrollKey(key))
+                return;
+        }
+        // @ 菜单激活时的键位分支（置于 slash 之后、审批之前）；↑/↓ 移动优先于历史导航，Tab/Enter 插入选中候选。
+        if (derivedRef.current.fileMentionSuggestions.length > 0) {
+            const fileMentionSuggestions = derivedRef.current.fileMentionSuggestions;
+            if (key.upArrow || key.downArrow) {
+                const nextIndex = key.upArrow
+                    ? Math.max(0, fileMentionIndexRef.current - 1)
+                    : Math.min(fileMentionSuggestions.length - 1, fileMentionIndexRef.current + 1);
+                updateFileMentionIndex(nextIndex);
+                return;
+            }
+            if (key.tab || key.return) {
+                const token = extractFileMentionToken(inputRef.current, cursorIndexRef.current);
+                const selected = fileMentionSuggestions[Math.max(0, Math.min(fileMentionIndexRef.current, fileMentionSuggestions.length - 1))];
+                if (token && selected) {
+                    const applied = applyFileMentionSuggestion(inputRef.current, token, selected);
+                    updateInput(applied.input, applied.cursor);
+                }
+                return;
+            }
+            if (isTuiViewportScrollKey(key))
+                return;
+        }
+        if (current.status === "waiting_approval" && current.pendingApproval && !busy.current && !bracketedPasteRef.current) {
+            const approvalOptions = createTuiApprovalOptions(current.pendingApproval);
+            if (key.upArrow) {
+                updateApprovalPickerIndex(Math.max(0, approvalPickerIndexRef.current - 1));
+                return;
+            }
+            if (key.downArrow) {
+                updateApprovalPickerIndex(Math.min(approvalOptions.length - 1, approvalPickerIndexRef.current + 1));
+                return;
+            }
+            if (key.return) {
+                const selected = approvalOptions[approvalPickerIndexRef.current];
+                if (selected)
+                    void dispatchAction({ type: "approve", decision: selected.decision });
+                return;
+            }
+            return;
+        }
+        if (derivedRef.current.handleTuiViewportKey(key))
+            return;
+        if (busy.current && !isActiveTuiStatus(current.status))
+            return;
+        const deleteDirection = resolveTuiDeleteDirection(value, key, rawInputSequenceRef.current);
+        if (deleteDirection) {
+            const characters = splitTuiInputGraphemes(inputRef.current);
+            const cursor = cursorIndexRef.current;
+            const removeIndex = deleteDirection === "backspace" ? cursor - 1 : cursor;
+            if (removeIndex < 0 || removeIndex >= characters.length)
+                return;
+            characters.splice(removeIndex, 1);
+            const nextInput = characters.join("");
+            inputHistoryRef.current = updateTuiInputHistoryDraft(inputHistoryRef.current, nextInput);
+            updateInput(nextInput, deleteDirection === "backspace" ? cursor - 1 : cursor);
+            return;
+        }
+        if (key.leftArrow) {
+            updateInput(inputRef.current, Math.max(0, cursorIndexRef.current - 1));
+            return;
+        }
+        if (key.rightArrow) {
+            updateInput(inputRef.current, Math.min(splitTuiInputGraphemes(inputRef.current).length, cursorIndexRef.current + 1));
+            return;
+        }
+        if (key.upArrow || key.downArrow) {
+            const layout = createTuiPromptLayout(inputRef.current, cursorIndexRef.current, columns);
+            const direction = key.upArrow ? -1 : 1;
+            const targetLine = layout.cursorLine + direction;
+            if (targetLine >= 0 && targetLine < layout.lines.length) {
+                const targetColumn = verticalColumnRef.current ?? layout.cursorColumn;
+                const nextCursorIndex = resolveTuiPromptCursorIndex(inputRef.current, layout, targetLine, targetColumn);
+                verticalColumnRef.current = targetColumn;
+                updateCursorIndex(nextCursorIndex);
+                return;
+            }
+            const historyDirection = key.upArrow ? "up" : "down";
+            const canNavigateHistory = canNavigateTuiInputHistory(historyDirection, layout.cursorLine, layout.lines.length, inputHistoryRef.current.index !== undefined, false);
+            const navigation = navigateTuiInputHistory(inputHistoryRef.current, historyDirection, inputRef.current, canNavigateHistory);
+            if (navigation.changed) {
+                inputHistoryRef.current = navigation.state;
+                updateInput(navigation.input, splitTuiInputGraphemes(navigation.input).length);
+            }
+            return;
+        }
+        const bracketedPasteReturn = bracketedPasteRef.current && key.return;
+        if (bracketedPasteRef.current && value === "\n" && pasteCarriageReturnRef.current) {
+            pasteCarriageReturnRef.current = false;
+            return;
+        }
+        const multilineEnter = isTuiMultilineEnter(value, key, rawInputSequenceRef.current);
+        const cursor = cursorIndexRef.current;
+        const continuation = key.return && hasTuiUnescapedContinuation(inputRef.current, cursor);
+        if (bracketedPasteReturn || multilineEnter || continuation) {
+            const characters = splitTuiInputGraphemes(inputRef.current);
+            const newlineIndex = continuation ? cursor - 1 : cursor;
+            if (continuation)
+                characters.splice(newlineIndex, 1);
+            characters.splice(newlineIndex, 0, "\n");
+            const nextInput = characters.join("");
+            inputHistoryRef.current = updateTuiInputHistoryDraft(inputHistoryRef.current, nextInput);
+            updateInput(nextInput, newlineIndex + 1);
+            pasteCarriageReturnRef.current = bracketedPasteReturn;
+            return;
+        }
+        pasteCarriageReturnRef.current = false;
+        if (key.return) {
+            const content = inputRef.current.trim();
+            updateInput("", 0);
+            if (!content)
+                return;
+            void (async function dispatchEnteredLine() {
+                const parsed = parseSlashAction(content);
+                if (parsed.kind === "error") {
+                    store.addNotice(parsed.message);
+                    return;
+                }
+                const prompt = parsed.action.type === "submit_prompt" ? parsed.action.content : undefined;
+                if (prompt)
+                    inputHistoryRef.current = recordTuiInputHistory(inputHistoryRef.current, prompt);
+                await dispatchAction(parsed.action, prompt);
+            })();
+            return;
+        }
+        if (value && !key.ctrl && !key.meta) {
+            const characters = splitTuiInputGraphemes(inputRef.current);
+            const cursor = cursorIndexRef.current;
+            const inserted = splitTuiInputGraphemes(normalizeTuiInputLineEndings(value));
+            characters.splice(cursor, 0, ...inserted);
+            const nextInput = characters.join("");
+            inputHistoryRef.current = updateTuiInputHistoryDraft(inputHistoryRef.current, nextInput);
+            updateInput(nextInput, cursor + inserted.length);
+        }
+    }
+    return { input: inputValue, cursorIndex, handleInput };
+}

package/dist/tui/hooks/use-status-view.d.ts

@@ -0,0 +1,8 @@
+/** statusView 异步刷新 hook：从 Controller 拉取脱敏状态栏。 */
+import type { CliController } from "../../controller.js";
+import type { CliStatusView } from "../../types.js";
+/** 管理脱敏状态栏并暴露异步刷新函数；测试 double 未提供 getStatusView 时保持旧值。 */
+export declare function useStatusView(controller: CliController): {
+    statusView: CliStatusView | undefined;
+    refreshStatusView: () => Promise<void>;
+};

package/dist/tui/hooks/use-status-view.js

@@ -0,0 +1,13 @@
+/** statusView 异步刷新 hook：从 Controller 拉取脱敏状态栏。 */
+import { useState } from "react";
+/** 管理脱敏状态栏并暴露异步刷新函数；测试 double 未提供 getStatusView 时保持旧值。 */
+export function useStatusView(controller) {
+    const [statusView, setStatusView] = useState(undefined);
+    /** 从 Controller 刷新脱敏状态栏，测试 double 未提供时保持旧状态行。 */
+    async function refreshStatusView() {
+        const next = await controller.getStatusView?.();
+        if (next)
+            setStatusView(next);
+    }
+    return { statusView, refreshStatusView };
+}

package/dist/tui/hooks/use-viewport.d.ts

@@ -0,0 +1,22 @@
+/** 备用屏视口滚动/鼠标/划选状态 hook。 */
+import type { Key } from "ink";
+import { type ScrollViewportState } from "../../scroll-viewport.js";
+import type { TimelineVisualLine } from "../../timeline-lines.js";
+import type { TuiSgrMouseEvent } from "../../tui-input-router.js";
+import { type TuiTextSelection } from "../viewport/selection.js";
+/** 管理备用屏视口的滚动、鼠标事件与文字划选状态。 */
+export declare function useViewport(input: {
+    isViewportMode: boolean;
+    columns: number;
+    viewportLines: TimelineVisualLine[];
+    viewportHeight: number;
+    stdout: {
+        write(chunk: string): void;
+    };
+    onCopyText?: (text: string) => void;
+}): {
+    viewportState: ScrollViewportState;
+    selection: TuiTextSelection;
+    handleTuiMouseEvent: (event: TuiSgrMouseEvent, wheelNotches: number) => void;
+    handleTuiViewportKey: (key: Key) => boolean;
+};

package/dist/tui/hooks/use-viewport.js

@@ -0,0 +1,117 @@
+/** 备用屏视口滚动/鼠标/划选状态 hook。 */
+import { useEffect, useRef, useState } from "react";
+import { createScrollViewportState, resizeScrollViewport, scrollViewportDown, scrollViewportToTop, scrollViewportUp, } from "../../scroll-viewport.js";
+import { copyTuiSelectedText, getTuiSelectedText, resolveTuiVisualLineOffset, } from "../viewport/selection.js";
+/** 管理备用屏视口的滚动、鼠标事件与文字划选状态。 */
+export function useViewport(input) {
+    const { isViewportMode, columns, viewportLines, viewportHeight, stdout, onCopyText } = input;
+    const [selection, setSelection] = useState({});
+    const selectionRef = useRef(selection);
+    const scrollbarDraggingRef = useRef(false);
+    const selectionDraggingRef = useRef(false);
+    const [viewportState, setViewportState] = useState(function createInitialViewportState() {
+        return createScrollViewportState(viewportLines.length, viewportHeight);
+    });
+    const viewportStateRef = useRef(viewportState);
+    /** 同步保存视口状态，供 16ms 合并后的鼠标回调读取最新位置。 */
+    function updateViewportState(next) {
+        viewportStateRef.current = next;
+        setViewportState(next);
+    }
+    /** 同步更新文字划选状态，确保鼠标 release 立即复制本次拖拽的最终范围。 */
+    function updateTuiTextSelection(next) {
+        selectionRef.current = next;
+        setSelection(next);
+    }
+    /** 将视口内鼠标坐标转换成时间线来源坐标；固定输入区和滚动条不参与划选。 */
+    function resolveTuiSelectionPoint(event) {
+        if (event.column >= columns || event.row < 1 || event.row > viewportStateRef.current.viewportHeight)
+            return undefined;
+        const line = viewportLines[viewportStateRef.current.scrollTop + event.row - 1];
+        return line ? { itemId: line.itemId, sourceOffset: resolveTuiVisualLineOffset(line, event.column - 1) } : undefined;
+    }
+    /** 用鼠标滚轮或滚动条拖拽更新备用屏视口；内容区点击保留给文字划选。 */
+    function handleTuiMouseEvent(event, wheelNotches) {
+        if (!isViewportMode)
+            return;
+        if (event.kind === "move")
+            return;
+        const current = viewportStateRef.current;
+        if (event.kind === "wheel_up") {
+            updateViewportState(scrollViewportUp(current, 3 * wheelNotches));
+            return;
+        }
+        if (event.kind === "wheel_down") {
+            updateViewportState(scrollViewportDown(current, 3 * wheelNotches));
+            return;
+        }
+        const hitsScrollbar = event.column >= columns;
+        const selectionPoint = resolveTuiSelectionPoint(event);
+        if (event.released && selectionDraggingRef.current) {
+            if (selectionPoint)
+                updateTuiTextSelection({ ...selectionRef.current, focus: selectionPoint });
+            selectionDraggingRef.current = false;
+            const text = getTuiSelectedText(viewportLines, selectionPoint ? { ...selectionRef.current, focus: selectionPoint } : selectionRef.current);
+            if (text) {
+                if (onCopyText)
+                    onCopyText(text);
+                else
+                    copyTuiSelectedText(text, stdout);
+            }
+            return;
+        }
+        if (event.released) {
+            scrollbarDraggingRef.current = false;
+            return;
+        }
+        if (!hitsScrollbar && event.kind === "button" && selectionPoint) {
+            selectionDraggingRef.current = true;
+            updateTuiTextSelection({ anchor: selectionPoint, focus: selectionPoint });
+            return;
+        }
+        if (!hitsScrollbar && event.kind === "drag" && selectionDraggingRef.current && selectionPoint) {
+            updateTuiTextSelection({ ...selectionRef.current, focus: selectionPoint });
+            return;
+        }
+        if (event.kind === "button")
+            scrollbarDraggingRef.current = hitsScrollbar;
+        if (!hitsScrollbar && !scrollbarDraggingRef.current)
+            return;
+        if (event.kind !== "button" && event.kind !== "drag")
+            return;
+        const maximumTop = Math.max(0, current.totalHeight - current.viewportHeight);
+        const ratio = current.viewportHeight <= 1 ? 0 : Math.max(0, Math.min(1, (event.row - 1) / (current.viewportHeight - 1)));
+        const scrollTop = Math.round(maximumTop * ratio);
+        updateViewportState({ ...current, scrollTop, pinnedToBottom: scrollTop >= maximumTop });
+    }
+    /** 在真实备用屏中处理半视口与顶底跳转；picker 和审批由前置键位分支优先消费。 */
+    function handleTuiViewportKey(key) {
+        if (!isViewportMode)
+            return false;
+        const current = viewportStateRef.current;
+        const jump = Math.max(1, Math.floor(current.viewportHeight / 2));
+        if (key.pageUp) {
+            updateViewportState(scrollViewportUp(current, jump));
+            return true;
+        }
+        if (key.pageDown) {
+            updateViewportState(scrollViewportDown(current, jump));
+            return true;
+        }
+        if (key.ctrl && key.home) {
+            updateViewportState(scrollViewportToTop(current));
+            return true;
+        }
+        if (key.ctrl && key.end) {
+            updateViewportState(scrollViewportDown(current, Number.MAX_SAFE_INTEGER));
+            return true;
+        }
+        return false;
+    }
+    useEffect(function resizeTuiViewport() {
+        if (!isViewportMode)
+            return;
+        updateViewportState(resizeScrollViewport(viewportStateRef.current, viewportLines.length, viewportHeight));
+    }, [isViewportMode, viewportLines.length, viewportHeight]);
+    return { viewportState, selection, handleTuiMouseEvent, handleTuiViewportKey };
+}

package/dist/tui/input/file-mention.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TUI @文件提及的输入侧纯函数：从输入与光标（grapheme 索引）提取当前 mention token、
+ * 按四档确定性评分过滤候选、把选中候选替换回输入。目录候选以尾随 `/` 标记，`\` 一律归一为 `/`。
+ */
+/** @ 候选菜单一次展示的候选集上限。 */
+export declare const FILE_MENTION_MAX_CANDIDATES = 50;
+/** mention token 中的合法字符（Unicode 字母/数字/组合标记与常用路径符号）；空白与中文标点等结束 token。 */
+export declare const FILE_MENTION_TOKEN_CHARACTER: RegExp;
+/** extractFileMentionToken 返回的当前 mention 上下文；光标不在 @ token 内时返回 null。 */
+export interface FileMentionToken {
+    /** `@` 字符的 grapheme 索引。 */
+    start: number;
+    /** token 自然结束的 grapheme 索引（光标右侧的 token 残余也计入，插入时整体替换）。 */
+    end: number;
+    /** `@` 之后、光标之前的查询文本（`\` 已归一为 `/`）。 */
+    query: string;
+}
+/** 从输入与光标提取当前 @ 文件 mention token；`@` 必须位于行首或空白后，token 中途遇空白即中断。 */
+export declare function extractFileMentionToken(input: string, cursor: number): FileMentionToken | null;
+/** 按四档确定性评分过滤并排序候选：完整路径前缀 > 文件名前缀 > 路径子串 > 文件名子串（大小写不敏感，同分 localeCompare）。 */
+export declare function filterFileMentionCandidates(candidates: readonly string[], query: string, maxCandidates?: number): string[];
+/** 渲染分段条目；isMention 的片段（含 `@` 与路径）应使用强调色展示。 */
+export interface TuiFileMentionSegment {
+    text: string;
+    isMention: boolean;
+}
+/** 把 prompt 文本切成普通/mention 交替段，边界与 @ 提取语义一致；用于输入框与时间线的强调展示。 */
+export declare function splitTuiFileMentionSegments(content: string): TuiFileMentionSegment[];
+/** 把选中候选替换回输入的 mention token；文件补尾随空格结束 token，目录保留尾随 `/` 继续下钻。 */
+export declare function applyFileMentionSuggestion(input: string, token: FileMentionToken, suggestion: string): {
+    input: string;
+    cursor: number;
+};

package/dist/tui/input/file-mention.js

@@ -0,0 +1,112 @@
+/**
+ * TUI @文件提及的输入侧纯函数：从输入与光标（grapheme 索引）提取当前 mention token、
+ * 按四档确定性评分过滤候选、把选中候选替换回输入。目录候选以尾随 `/` 标记，`\` 一律归一为 `/`。
+ */
+import { splitTuiInputGraphemes } from "./graphemes.js";
+/** @ 候选菜单一次展示的候选集上限。 */
+export const FILE_MENTION_MAX_CANDIDATES = 50;
+/** mention token 中的合法字符（Unicode 字母/数字/组合标记与常用路径符号）；空白与中文标点等结束 token。 */
+export const FILE_MENTION_TOKEN_CHARACTER = /^[\p{L}\p{N}\p{M}_\-./\\()[\]~:]$/u;
+/** 判定单个 grapheme 是否属于 mention token 字符集（Unicode 字母/数字/组合标记与常用路径符号）。 */
+function isTokenGrapheme(character) {
+    return /^[\p{L}\p{N}\p{M}_\-./\\()[\]~:]$/u.test(character);
+}
+/** 从输入与光标提取当前 @ 文件 mention token；`@` 必须位于行首或空白后，token 中途遇空白即中断。 */
+export function extractFileMentionToken(input, cursor) {
+    const characters = splitTuiInputGraphemes(input);
+    if (!Number.isInteger(cursor) || cursor <= 0 || cursor > characters.length)
+        return null;
+    // 从光标向左扫描：全部字符必须是 token 字符，且恰好在空白或行首之前命中 @。
+    let atIndex = -1;
+    for (let index = cursor - 1; index >= 0; index -= 1) {
+        const character = characters[index];
+        if (character === "@") {
+            const previous = index > 0 ? characters[index - 1] : "";
+            if (index > 0 && !/\s/u.test(previous))
+                return null;
+            atIndex = index;
+            break;
+        }
+        if (!isTokenGrapheme(character))
+            return null;
+    }
+    if (atIndex < 0)
+        return null;
+    // 向右吞掉光标后的 token 残余，让插入替换覆盖完整 token（如光标停在 main.ts 的 ma 处）；
+    // 只吞 ASCII 文件名字符：光标右侧紧邻的中文等非 ASCII 极大概率是已输入正文，视为边界不吞，避免整体替换吞字。
+    let end = cursor;
+    while (end < characters.length) {
+        const character = characters[end];
+        if (!isTokenGrapheme(character) || !/^[\x00-\x7F]$/u.test(character))
+            break;
+        end += 1;
+    }
+    return {
+        start: atIndex,
+        end,
+        query: characters.slice(atIndex + 1, cursor).join("").replace(/\\/g, "/"),
+    };
+}
+/** 取候选的最后一段作为参与匹配的名称；目录先去掉尾随斜杠。 */
+function candidateName(candidatePath) {
+    const trimmed = candidatePath.endsWith("/") ? candidatePath.slice(0, -1) : candidatePath;
+    return trimmed.split("/").pop() ?? trimmed;
+}
+/** 按四档确定性评分过滤并排序候选：完整路径前缀 > 文件名前缀 > 路径子串 > 文件名子串（大小写不敏感，同分 localeCompare）。 */
+export function filterFileMentionCandidates(candidates, query, maxCandidates = FILE_MENTION_MAX_CANDIDATES) {
+    const normalizedQuery = query.replace(/\\/g, "/").toLocaleLowerCase();
+    const scored = [];
+    for (const candidate of candidates) {
+        const normalizedPath = candidate.replace(/\\/g, "/");
+        const lowerPath = normalizedPath.toLocaleLowerCase();
+        const lowerName = candidateName(normalizedPath).toLocaleLowerCase();
+        let tier;
+        if (lowerPath.startsWith(normalizedQuery))
+            tier = 3;
+        else if (lowerName.startsWith(normalizedQuery))
+            tier = 2;
+        else if (lowerPath.includes(normalizedQuery))
+            tier = 1;
+        else if (lowerName.includes(normalizedQuery))
+            tier = 0;
+        else
+            continue;
+        scored.push({ path: normalizedPath, tier });
+    }
+    return scored
+        .sort(function compareCandidates(left, right) {
+        return right.tier - left.tier || left.path.localeCompare(right.path);
+    })
+        .slice(0, Math.max(0, maxCandidates))
+        .map(function readPath(candidate) {
+        return candidate.path;
+    });
+}
+/** 把 prompt 文本切成普通/mention 交替段，边界与 @ 提取语义一致；用于输入框与时间线的强调展示。 */
+export function splitTuiFileMentionSegments(content) {
+    const segments = [];
+    let plainStart = 0;
+    for (const match of content.matchAll(/(^|\s)@/gu)) {
+        const atStart = match.index + match[0].length - 1;
+        let end = atStart + 1;
+        while (end < content.length && FILE_MENTION_TOKEN_CHARACTER.test(content[end]))
+            end += 1;
+        if (end === atStart + 1)
+            continue;
+        if (atStart > plainStart)
+            segments.push({ text: content.slice(plainStart, atStart), isMention: false });
+        segments.push({ text: content.slice(atStart, end), isMention: true });
+        plainStart = end;
+    }
+    if (plainStart < content.length)
+        segments.push({ text: content.slice(plainStart), isMention: false });
+    return segments;
+}
+/** 把选中候选替换回输入的 mention token；文件补尾随空格结束 token，目录保留尾随 `/` 继续下钻。 */
+export function applyFileMentionSuggestion(input, token, suggestion) {
+    const characters = splitTuiInputGraphemes(input);
+    const replacement = suggestion.endsWith("/") ? `@${suggestion}` : `@${suggestion} `;
+    const replacementGraphemes = splitTuiInputGraphemes(replacement);
+    characters.splice(token.start, token.end - token.start, ...replacementGraphemes);
+    return { input: characters.join(""), cursor: token.start + replacementGraphemes.length };
+}

package/dist/tui/input/graphemes.d.ts

@@ -0,0 +1,5 @@
+/** TUI 输入的 Unicode grapheme 纯函数：把用户输入拆成可感知字符并统一换行符。 */
+/** 将单行输入拆为用户可感知字符，避免中文与组合 emoji 的光标索引错位。 */
+export declare function splitTuiInputGraphemes(input: string): string[];
+/** 将终端粘贴的 CRLF 或 CR 统一为 TUI 内部唯一的 LF，避免 CR 在终端渲染时覆盖前文。 */
+export declare function normalizeTuiInputLineEndings(input: string): string;

package/dist/tui/input/graphemes.js

@@ -0,0 +1,10 @@
+/** TUI 输入的 Unicode grapheme 纯函数：把用户输入拆成可感知字符并统一换行符。 */
+import { TUI_INPUT_SEGMENTER } from "../constants.js";
+/** 将单行输入拆为用户可感知字符，避免中文与组合 emoji 的光标索引错位。 */
+export function splitTuiInputGraphemes(input) {
+    return Array.from(TUI_INPUT_SEGMENTER.segment(input), function readSegment(segment) { return segment.segment; });
+}
+/** 将终端粘贴的 CRLF 或 CR 统一为 TUI 内部唯一的 LF，避免 CR 在终端渲染时覆盖前文。 */
+export function normalizeTuiInputLineEndings(input) {
+    return input.replace(/\r\n?|\n/g, "\n");
+}

package/dist/tui/input/keys.d.ts

@@ -0,0 +1,16 @@
+/** TUI 按键解析纯函数：归一化控制动作、删除方向、换行/粘贴/focus/滚动判断。 */
+import type { Key } from "ink";
+/** 将 Ink 键对象和终端控制字符归一为 TUI 控制动作，兼容真实 TTY 与测试 stdin。 */
+export declare function parseTuiControlAction(value: string, key: Key): "eof" | "interrupt" | "cancel" | undefined;
+/** 区分 Backspace 与前向 Delete，优先采用终端原始控制字符兼容 macOS Terminal。 */
+export declare function resolveTuiDeleteDirection(value: string, key: Key, rawSequence?: string): "backspace" | "delete" | undefined;
+/** 识别 Claude Code/终端常见的 Shift+Enter 编码；普通回车仍由 key.return 单独处理。 */
+export declare function isTuiMultilineEnter(value: string, key: Key, rawSequence?: string): boolean;
+/** 识别 bracketed paste 边界；Ink 会去掉 CSI 序列的首个 ESC 后再交给 useInput。 */
+export declare function resolveTuiBracketedPasteBoundary(value: string): "start" | "end" | undefined;
+/** 判断终端 focus in/out 报告，避免控制序列被误插入 prompt。 */
+export declare function isTuiTerminalFocusSequence(value: string): boolean;
+/** 判断按键是否属于备用屏滚动兜底，避免与普通 Home/End 输入语义混淆。 */
+export declare function isTuiViewportScrollKey(key: Key): boolean;
+/** 判断光标前的反斜线是否是未被另一枚反斜线转义的续行标记。 */
+export declare function hasTuiUnescapedContinuation(input: string, cursorIndex: number): boolean;