@armadra/agent 0.0.0-stage → 0.3.0

package/dist/tui/components/meter.js

@@ -0,0 +1,47 @@
+/**
+ * 单行余量表（第三波 A8）：`ctx ▮▮▮▮▮▮▮▯▯▯ 72%`。[W3-B9a-2]
+ *
+ * - `value` 是 0–1 的比例（越界夹紧）；undefined 显示 `—`，格子全空；
+ * - 阈值着色（需要 theme）：≥ `dangerAt`（缺省 0.9）error，≥ `warnAt`（缺省 0.7）warning，否则 success；
+ *   空格子 dim；
+ * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断。
+ */
+import { truncateToWidth, visibleWidth } from "../ansi.js";
+export const METER_FULL = "▮";
+export const METER_EMPTY = "▯";
+export class Meter {
+    value;
+    options;
+    constructor(value = undefined, options = {}) {
+        this.value = value;
+        this.options = options;
+    }
+    setValue(value) {
+        this.value = value;
+    }
+    /** 当前阈值档位对应的语义色。 */
+    level() {
+        const v = this.value ?? 0;
+        if (v >= (this.options.dangerAt ?? 0.9))
+            return "error";
+        if (v >= (this.options.warnAt ?? 0.7))
+            return "warning";
+        return "success";
+    }
+    render(width) {
+        const { theme, label, cells = 10 } = this.options;
+        const ratio = this.value === undefined ? undefined : Math.min(1, Math.max(0, this.value));
+        const percent = ratio === undefined ? "—" : `${Math.round(ratio * 100)}%`;
+        const color = (c, text) => (theme ? theme.fg(c, text) : text);
+        const head = label === undefined || label === "" ? "" : `${label} `;
+        const filled = ratio === undefined ? 0 : Math.round(ratio * cells);
+        const bar = color(this.level(), METER_FULL.repeat(filled)) +
+            color("dim", METER_EMPTY.repeat(cells - filled));
+        const tail = color(ratio === undefined ? "dim" : this.level(), percent);
+        const full = `${head}${bar} ${tail}`;
+        if (visibleWidth(full) <= width)
+            return [full];
+        return [truncateToWidth(`${head}${tail}`, width)];
+    }
+    invalidate() { }
+}

package/dist/tui/components/overlay.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 覆盖层合成（设计 §12.1、§12.2 第 2 步）：只支持 `center` 与 `bottom` 两种锚点。[B4]
+ *
+ * 覆盖层画在「终端视口」内（内容的最后 height 行）；内容不足覆盖层高度时在末尾补空行。
+ * 合成发生在差分之前，所以覆盖层的出现 / 消失与普通内容变化一样只重写变化行。
+ */
+import type { Component } from "../component.js";
+export type OverlayAnchor = "center" | "bottom";
+export interface OverlayOptions {
+    /** 缺省 `center`。 */
+    anchor?: OverlayAnchor;
+    /** 覆盖层列宽；缺省 center 为 min(width - 4, 80)，bottom 为整宽。 */
+    width?: number;
+    /** 最大行数；缺省为终端高度。 */
+    maxHeight?: number;
+}
+export interface OverlayLayer {
+    readonly component: Component;
+    readonly options: OverlayOptions;
+}
+/** 把一行 base 的 [col, col + w) 列替换为 overlay 行。 */
+export declare function spliceLine(base: string, overlay: string, col: number, w: number, width: number): string;
+/** 按顺序合成全部覆盖层（后加入的在上）。 */
+export declare function compositeOverlays(lines: readonly string[], layers: readonly OverlayLayer[], width: number, height: number): string[];

package/dist/tui/components/overlay.js

@@ -0,0 +1,52 @@
+/**
+ * 覆盖层合成（设计 §12.1、§12.2 第 2 步）：只支持 `center` 与 `bottom` 两种锚点。[B4]
+ *
+ * 覆盖层画在「终端视口」内（内容的最后 height 行）；内容不足覆盖层高度时在末尾补空行。
+ * 合成发生在差分之前，所以覆盖层的出现 / 消失与普通内容变化一样只重写变化行。
+ */
+import { SGR_RESET, padToWidth, sliceByColumn, truncateToWidth } from "../ansi.js";
+function overlayWidth(options, width) {
+    const anchor = options.anchor ?? "center";
+    const wanted = options.width ?? (anchor === "bottom" ? width : Math.min(width - 4, 80));
+    return Math.max(1, Math.min(width, wanted));
+}
+/** 把一行 base 的 [col, col + w) 列替换为 overlay 行。 */
+export function spliceLine(base, overlay, col, w, width) {
+    const left = padToWidth(sliceByColumn(base, 0, col), col);
+    const mid = padToWidth(truncateToWidth(overlay, w), w);
+    const right = sliceByColumn(base, col + w, width);
+    const midReset = mid.includes("\x1b") ? SGR_RESET : "";
+    return left + mid + midReset + right;
+}
+/** 按顺序合成全部覆盖层（后加入的在上）。 */
+export function compositeOverlays(lines, layers, width, height) {
+    let result = [...lines];
+    for (const layer of layers)
+        result = compositeOne(result, layer, width, height);
+    return result;
+}
+function compositeOne(lines, layer, width, height) {
+    const ow = overlayWidth(layer.options, width);
+    const maxHeight = Math.max(1, Math.min(height, layer.options.maxHeight ?? height));
+    let body = layer.component.render(ow);
+    if (body.length > maxHeight)
+        body = body.slice(body.length - maxHeight);
+    const oh = body.length;
+    if (oh === 0)
+        return lines;
+    const result = [...lines];
+    while (result.length < oh)
+        result.push("");
+    const viewportTop = Math.max(0, result.length - height);
+    const visible = result.length - viewportTop;
+    const anchor = layer.options.anchor ?? "center";
+    const startRow = anchor === "bottom"
+        ? result.length - oh
+        : viewportTop + Math.max(0, Math.floor((visible - oh) / 2));
+    const col = anchor === "bottom" && ow === width ? 0 : Math.floor((width - ow) / 2);
+    for (let i = 0; i < oh; i++) {
+        const row = startRow + i;
+        result[row] = spliceLine(result[row] ?? "", body[i] ?? "", col, ow, width);
+    }
+    return result;
+}

package/dist/tui/components/select-list.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 选择列表（设计 §12.6）：过滤、分页（视窗跟随选中项）、描述列、分组标题。[B4]
+ *
+ * 键位走 `tui.select.*`：上下移动（循环）、翻页、确认（Enter / Tab）、取消（Esc / Ctrl+C）。
+ * `filterable` 时可打印字符追加到过滤词、退格删除；过滤为大小写不敏感的分词子串匹配
+ * （每个词都要出现在 label / value / group / description 之一中）。
+ */
+import type { Component, Focusable, Theme } from "../component.js";
+import { type Keybindings } from "../keybindings.js";
+export interface SelectItem {
+    value: string;
+    label: string;
+    description?: string;
+    /** 相邻项 group 不同时插入分组标题行。 */
+    group?: string;
+}
+export interface SelectListOptions {
+    /** 一屏最多显示的条目数，缺省 10。 */
+    maxVisible?: number;
+    theme?: Theme;
+    keybindings?: Keybindings;
+    filterable?: boolean;
+    emptyText?: string;
+    onSelect?(item: SelectItem): void;
+    onCancel?(): void;
+    onSelectionChange?(item: SelectItem | undefined): void;
+}
+export declare function filterItems(items: readonly SelectItem[], filter: string): SelectItem[];
+export declare class SelectList implements Component, Focusable {
+    private readonly options;
+    focused: boolean;
+    private items;
+    private filtered;
+    private filter;
+    private selected;
+    private scrollTop;
+    private readonly keys;
+    constructor(items: readonly SelectItem[], options?: SelectListOptions);
+    private get maxVisible();
+    setItems(items: readonly SelectItem[]): void;
+    getItems(): readonly SelectItem[];
+    getFilter(): string;
+    setFilter(filter: string): void;
+    getSelected(): SelectItem | undefined;
+    getSelectedIndex(): number;
+    setSelectedIndex(index: number): void;
+    /** 按 value 选中。 */
+    selectValue(value: string): boolean;
+    moveSelection(delta: number, wrap?: boolean): void;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+    private renderItem;
+    private labelColumnWidth;
+    private applyFilter;
+    private ensureVisible;
+}

package/dist/tui/components/select-list.js

@@ -0,0 +1,179 @@
+/**
+ * 选择列表（设计 §12.6）：过滤、分页（视窗跟随选中项）、描述列、分组标题。[B4]
+ *
+ * 键位走 `tui.select.*`：上下移动（循环）、翻页、确认（Enter / Tab）、取消（Esc / Ctrl+C）。
+ * `filterable` 时可打印字符追加到过滤词、退格删除；过滤为大小写不敏感的分词子串匹配
+ * （每个词都要出现在 label / value / group / description 之一中）。
+ */
+import { padToWidth, truncateToWidth, visibleWidth } from "../ansi.js";
+import { defaultKeybindings } from "../keybindings.js";
+import { isPrintableText, matchesKey } from "../keys.js";
+export function filterItems(items, filter) {
+    const terms = filter.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return [...items];
+    return items.filter((item) => {
+        const hay = [item.label, item.value, item.group ?? "", item.description ?? ""]
+            .join("\n")
+            .toLowerCase();
+        return terms.every((term) => hay.includes(term));
+    });
+}
+export class SelectList {
+    options;
+    focused = false;
+    items;
+    filtered;
+    filter = "";
+    selected = 0;
+    scrollTop = 0;
+    keys;
+    constructor(items, options = {}) {
+        this.options = options;
+        this.items = [...items];
+        this.filtered = [...items];
+        this.keys = options.keybindings ?? defaultKeybindings;
+    }
+    get maxVisible() {
+        return Math.max(1, this.options.maxVisible ?? 10);
+    }
+    setItems(items) {
+        this.items = [...items];
+        this.applyFilter();
+    }
+    getItems() {
+        return this.filtered;
+    }
+    getFilter() {
+        return this.filter;
+    }
+    setFilter(filter) {
+        this.filter = filter;
+        this.applyFilter();
+    }
+    getSelected() {
+        return this.filtered[this.selected];
+    }
+    getSelectedIndex() {
+        return this.selected;
+    }
+    setSelectedIndex(index) {
+        if (this.filtered.length === 0)
+            return;
+        this.selected = Math.max(0, Math.min(this.filtered.length - 1, index));
+        this.ensureVisible();
+        this.options.onSelectionChange?.(this.getSelected());
+    }
+    /** 按 value 选中。 */
+    selectValue(value) {
+        const index = this.filtered.findIndex((item) => item.value === value);
+        if (index === -1)
+            return false;
+        this.setSelectedIndex(index);
+        return true;
+    }
+    moveSelection(delta, wrap = true) {
+        const n = this.filtered.length;
+        if (n === 0)
+            return;
+        let next = this.selected + delta;
+        if (wrap && Math.abs(delta) === 1)
+            next = (next + n) % n;
+        this.setSelectedIndex(next);
+    }
+    handleInput(data) {
+        const k = this.keys;
+        if (k.matches(data, "tui.select.up"))
+            this.moveSelection(-1);
+        else if (k.matches(data, "tui.select.down"))
+            this.moveSelection(1);
+        else if (k.matches(data, "tui.select.pageUp"))
+            this.moveSelection(-this.maxVisible, false);
+        else if (k.matches(data, "tui.select.pageDown"))
+            this.moveSelection(this.maxVisible, false);
+        else if (k.matches(data, "tui.select.confirm")) {
+            const item = this.getSelected();
+            if (item)
+                this.options.onSelect?.(item);
+        }
+        else if (k.matches(data, "tui.select.cancel"))
+            this.options.onCancel?.();
+        else if (this.options.filterable) {
+            if (matchesKey(data, "backspace")) {
+                if (this.filter.length > 0)
+                    this.setFilter([...this.filter].slice(0, -1).join(""));
+            }
+            else if (isPrintableText(data)) {
+                this.setFilter(this.filter + data);
+            }
+        }
+    }
+    render(width) {
+        const theme = this.options.theme;
+        const dim = (s) => (theme ? theme.fg("dim", s) : s);
+        const lines = [];
+        if (this.options.filterable) {
+            const prompt = theme ? theme.fg("accent", "> ") : "> ";
+            lines.push(truncateToWidth(prompt + this.filter + (this.focused ? "▏" : ""), width));
+        }
+        if (this.filtered.length === 0) {
+            lines.push(truncateToWidth(dim(`  ${this.options.emptyText ?? "(no matches)"}`), width));
+            return lines;
+        }
+        const end = Math.min(this.filtered.length, this.scrollTop + this.maxVisible);
+        const labelWidth = this.labelColumnWidth(end);
+        let lastGroup;
+        for (let i = this.scrollTop; i < end; i++) {
+            const item = this.filtered[i];
+            if (item.group !== undefined && item.group !== lastGroup) {
+                lines.push(truncateToWidth(dim(item.group), width));
+            }
+            lastGroup = item.group;
+            lines.push(this.renderItem(item, i === this.selected, labelWidth, width));
+        }
+        if (this.filtered.length > this.maxVisible) {
+            lines.push(truncateToWidth(dim(`  (${this.selected + 1}/${this.filtered.length})`), width));
+        }
+        return lines;
+    }
+    invalidate() { }
+    renderItem(item, selected, labelWidth, width) {
+        const theme = this.options.theme;
+        const prefix = selected ? "› " : "  ";
+        const label = truncateToWidth(item.label, Math.max(1, width - 2));
+        let line = prefix + padToWidth(label, Math.min(labelWidth, width - 2));
+        if (selected && theme)
+            line = theme.fg("accent", theme.bold(line));
+        const room = width - visibleWidth(line) - 2;
+        if (item.description && room > 4) {
+            const desc = truncateToWidth(item.description, room);
+            line += "  " + (theme ? theme.fg("dim", desc) : desc);
+        }
+        return truncateToWidth(line, width);
+    }
+    labelColumnWidth(end) {
+        let max = 0;
+        for (let i = this.scrollTop; i < end; i++) {
+            max = Math.max(max, visibleWidth(this.filtered[i].label));
+        }
+        return max;
+    }
+    applyFilter() {
+        const previous = this.getSelected()?.value;
+        this.filtered = filterItems(this.items, this.filter);
+        const keep = previous === undefined ? -1 : this.filtered.findIndex((i) => i.value === previous);
+        this.selected = keep === -1 ? 0 : keep;
+        this.scrollTop = 0;
+        this.ensureVisible();
+        this.options.onSelectionChange?.(this.getSelected());
+    }
+    ensureVisible() {
+        if (this.selected < this.scrollTop)
+            this.scrollTop = this.selected;
+        else if (this.selected >= this.scrollTop + this.maxVisible) {
+            this.scrollTop = this.selected - this.maxVisible + 1;
+        }
+        this.scrollTop = Math.max(0, Math.min(this.scrollTop, this.filtered.length - this.maxVisible));
+        this.scrollTop = Math.max(0, this.scrollTop);
+    }
+}

package/dist/tui/components/spacer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 占位空行（设计 §12.1）。[B4]
+ */
+import type { Component } from "../component.js";
+export declare class Spacer implements Component {
+    private lines;
+    constructor(lines?: number);
+    setLines(lines: number): void;
+    render(_width: number): string[];
+    invalidate(): void;
+}

package/dist/tui/components/spacer.js

@@ -0,0 +1,16 @@
+/**
+ * 占位空行（设计 §12.1）。[B4]
+ */
+export class Spacer {
+    lines;
+    constructor(lines = 1) {
+        this.lines = lines;
+    }
+    setLines(lines) {
+        this.lines = Math.max(0, lines);
+    }
+    render(_width) {
+        return new Array(this.lines).fill("");
+    }
+    invalidate() { }
+}

package/dist/tui/components/text.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 文本组件（设计 §12.1）。[B4]
+ *
+ * - `Text`：自动换行（保留 ANSI 样式）、可选左右 / 上下内边距；按 (width, text) 缓存。
+ * - `TruncatedText`：只取第一行并截断到宽度（状态栏、标题行）。
+ */
+import type { Component } from "../component.js";
+export interface TextOptions {
+    paddingX?: number;
+    paddingY?: number;
+}
+export declare class Text implements Component {
+    private text;
+    private cache;
+    private readonly paddingX;
+    private readonly paddingY;
+    constructor(text?: string, options?: TextOptions);
+    getText(): string;
+    setText(text: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}
+export declare class TruncatedText implements Component {
+    private text;
+    private readonly paddingX;
+    constructor(text?: string, paddingX?: number);
+    setText(text: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/tui/components/text.js

@@ -0,0 +1,65 @@
+/**
+ * 文本组件（设计 §12.1）。[B4]
+ *
+ * - `Text`：自动换行（保留 ANSI 样式）、可选左右 / 上下内边距；按 (width, text) 缓存。
+ * - `TruncatedText`：只取第一行并截断到宽度（状态栏、标题行）。
+ */
+import { truncateToWidth, wrapTextWithAnsi } from "../ansi.js";
+export class Text {
+    text;
+    cache = null;
+    paddingX;
+    paddingY;
+    constructor(text = "", options = {}) {
+        this.text = text;
+        this.paddingX = options.paddingX ?? 0;
+        this.paddingY = options.paddingY ?? 0;
+    }
+    getText() {
+        return this.text;
+    }
+    setText(text) {
+        if (text === this.text)
+            return;
+        this.text = text;
+        this.cache = null;
+    }
+    render(width) {
+        if (this.cache && this.cache.width === width && this.cache.text === this.text) {
+            return this.cache.lines;
+        }
+        const inner = Math.max(1, width - this.paddingX * 2);
+        const pad = " ".repeat(this.paddingX);
+        const lines = [];
+        for (let i = 0; i < this.paddingY; i++)
+            lines.push("");
+        if (this.text !== "") {
+            for (const line of wrapTextWithAnsi(this.text, inner))
+                lines.push(pad + line);
+        }
+        for (let i = 0; i < this.paddingY; i++)
+            lines.push("");
+        this.cache = { width, text: this.text, lines };
+        return lines;
+    }
+    invalidate() {
+        this.cache = null;
+    }
+}
+export class TruncatedText {
+    text;
+    paddingX;
+    constructor(text = "", paddingX = 0) {
+        this.text = text;
+        this.paddingX = paddingX;
+    }
+    setText(text) {
+        this.text = text;
+    }
+    render(width) {
+        const firstLine = this.text.split("\n", 1)[0] ?? "";
+        const pad = " ".repeat(this.paddingX);
+        return [pad + truncateToWidth(firstLine, Math.max(0, width - this.paddingX * 2))];
+    }
+    invalidate() { }
+}

package/dist/tui/keybindings.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 键位表（设计 §12.3）：动作 id → KeyId 列表；固定缺省表 + `keybindings.json` 覆盖。[B4]
+ *
+ * - `tui.*` 由组件库自己消费（编辑器、选择列表）；`app.*` 供交互模式（B7）分派。
+ * - 覆盖时整组替换；空数组表示禁用该动作。未知动作 id 与非字符串键会被报告并忽略。
+ * - 文件位置由调用方决定（配置目录归 B5），这里只负责解析与合并。
+ */
+export declare const DEFAULT_KEYBINDINGS: {
+    readonly "tui.editor.submit": readonly ["enter"];
+    readonly "tui.editor.newLine": readonly ["shift+enter", "ctrl+j"];
+    readonly "tui.editor.cursorLeft": readonly ["left", "ctrl+b"];
+    readonly "tui.editor.cursorRight": readonly ["right", "ctrl+f"];
+    readonly "tui.editor.cursorUp": readonly ["up", "ctrl+p"];
+    readonly "tui.editor.cursorDown": readonly ["down", "ctrl+n"];
+    readonly "tui.editor.wordLeft": readonly ["alt+left", "ctrl+left", "alt+b"];
+    readonly "tui.editor.wordRight": readonly ["alt+right", "ctrl+right", "alt+f"];
+    readonly "tui.editor.lineStart": readonly ["home", "ctrl+a"];
+    readonly "tui.editor.lineEnd": readonly ["end", "ctrl+e"];
+    readonly "tui.editor.deleteBackward": readonly ["backspace", "shift+backspace"];
+    readonly "tui.editor.deleteForward": readonly ["delete"];
+    readonly "tui.editor.deleteWordBackward": readonly ["ctrl+w", "alt+backspace", "ctrl+backspace"];
+    readonly "tui.editor.deleteWordForward": readonly ["alt+d", "alt+delete", "ctrl+delete"];
+    readonly "tui.editor.deleteToLineStart": readonly ["ctrl+u"];
+    readonly "tui.editor.deleteToLineEnd": readonly ["ctrl+k"];
+    readonly "tui.editor.undo": readonly ["ctrl+z", "ctrl+-"];
+    readonly "tui.editor.complete": readonly ["tab"];
+    readonly "tui.select.up": readonly ["up", "ctrl+p"];
+    readonly "tui.select.down": readonly ["down", "ctrl+n"];
+    readonly "tui.select.pageUp": readonly ["pageup"];
+    readonly "tui.select.pageDown": readonly ["pagedown"];
+    readonly "tui.select.confirm": readonly ["enter", "tab"];
+    readonly "tui.select.cancel": readonly ["escape", "ctrl+c"];
+    readonly "app.interrupt": readonly ["escape"];
+    readonly "app.clear": readonly ["ctrl+c"];
+    readonly "app.exit": readonly ["ctrl+d"];
+    readonly "app.message.followUp": readonly ["alt+enter"];
+    readonly "app.message.dequeue": readonly ["alt+up"];
+    readonly "app.permission.cycle": readonly ["shift+tab"];
+    readonly "app.tools.expand": readonly ["ctrl+o"];
+    readonly "app.model.select": readonly ["ctrl+l"];
+    readonly "app.thinking.select": readonly ["ctrl+t"];
+};
+export type ActionId = keyof typeof DEFAULT_KEYBINDINGS;
+export type KeybindingOverrides = Partial<Record<ActionId, readonly string[]>>;
+export interface ParsedKeybindings {
+    overrides: KeybindingOverrides;
+    /** 被忽略的条目说明（未知动作、类型错误）。 */
+    warnings: string[];
+}
+export declare function isActionId(id: string): id is ActionId;
+/** 解析 keybindings.json 的对象形状：`{ "<action>": "key" | ["key", ...] }`。 */
+export declare function parseKeybindings(value: unknown): ParsedKeybindings;
+/** 读取并解析 keybindings.json；文件不存在返回空覆盖，JSON 错误记入 warnings。 */
+export declare function loadKeybindingsFile(path: string): ParsedKeybindings;
+export declare class Keybindings {
+    private readonly table;
+    constructor(overrides?: KeybindingOverrides);
+    /** 动作绑定的 KeyId 列表（已规范化）。 */
+    keys(action: ActionId): readonly string[];
+    /** 原始输入数据是否触发该动作。 */
+    matches(data: string, action: ActionId): boolean;
+    /** 输入数据触发的全部动作（按缺省表顺序），用于分派。 */
+    actionsFor(data: string): ActionId[];
+}
+/** 进程内共享的缺省键位（组件未显式传入时使用）。 */
+export declare const defaultKeybindings: Keybindings;

package/dist/tui/keybindings.js

@@ -0,0 +1,120 @@
+/**
+ * 键位表（设计 §12.3）：动作 id → KeyId 列表；固定缺省表 + `keybindings.json` 覆盖。[B4]
+ *
+ * - `tui.*` 由组件库自己消费（编辑器、选择列表）；`app.*` 供交互模式（B7）分派。
+ * - 覆盖时整组替换；空数组表示禁用该动作。未知动作 id 与非字符串键会被报告并忽略。
+ * - 文件位置由调用方决定（配置目录归 B5），这里只负责解析与合并。
+ */
+import { readFileSync } from "node:fs";
+import { normalizeKeyId, parseKey } from "./keys.js";
+export const DEFAULT_KEYBINDINGS = {
+    "tui.editor.submit": ["enter"],
+    "tui.editor.newLine": ["shift+enter", "ctrl+j"],
+    "tui.editor.cursorLeft": ["left", "ctrl+b"],
+    "tui.editor.cursorRight": ["right", "ctrl+f"],
+    "tui.editor.cursorUp": ["up", "ctrl+p"],
+    "tui.editor.cursorDown": ["down", "ctrl+n"],
+    "tui.editor.wordLeft": ["alt+left", "ctrl+left", "alt+b"],
+    "tui.editor.wordRight": ["alt+right", "ctrl+right", "alt+f"],
+    "tui.editor.lineStart": ["home", "ctrl+a"],
+    "tui.editor.lineEnd": ["end", "ctrl+e"],
+    "tui.editor.deleteBackward": ["backspace", "shift+backspace"],
+    "tui.editor.deleteForward": ["delete"],
+    "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+    "tui.editor.deleteWordForward": ["alt+d", "alt+delete", "ctrl+delete"],
+    "tui.editor.deleteToLineStart": ["ctrl+u"],
+    "tui.editor.deleteToLineEnd": ["ctrl+k"],
+    "tui.editor.undo": ["ctrl+z", "ctrl+-"],
+    "tui.editor.complete": ["tab"],
+    "tui.select.up": ["up", "ctrl+p"],
+    "tui.select.down": ["down", "ctrl+n"],
+    "tui.select.pageUp": ["pageup"],
+    "tui.select.pageDown": ["pagedown"],
+    "tui.select.confirm": ["enter", "tab"],
+    "tui.select.cancel": ["escape", "ctrl+c"],
+    "app.interrupt": ["escape"],
+    "app.clear": ["ctrl+c"],
+    "app.exit": ["ctrl+d"],
+    "app.message.followUp": ["alt+enter"],
+    "app.message.dequeue": ["alt+up"],
+    "app.permission.cycle": ["shift+tab"],
+    "app.tools.expand": ["ctrl+o"],
+    "app.model.select": ["ctrl+l"],
+    "app.thinking.select": ["ctrl+t"],
+};
+export function isActionId(id) {
+    return Object.prototype.hasOwnProperty.call(DEFAULT_KEYBINDINGS, id);
+}
+/** 解析 keybindings.json 的对象形状：`{ "<action>": "key" | ["key", ...] }`。 */
+export function parseKeybindings(value) {
+    const overrides = {};
+    const warnings = [];
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { overrides: {}, warnings: ["keybindings 必须是对象"] };
+    }
+    for (const [action, keys] of Object.entries(value)) {
+        if (!isActionId(action)) {
+            warnings.push(`未知动作：${action}`);
+            continue;
+        }
+        const list = typeof keys === "string" ? [keys] : keys;
+        if (!Array.isArray(list) || !list.every((k) => typeof k === "string")) {
+            warnings.push(`${action}：键必须是字符串或字符串数组`);
+            continue;
+        }
+        overrides[action] = list.map((k) => normalizeKeyId(k));
+    }
+    return { overrides: overrides, warnings };
+}
+/** 读取并解析 keybindings.json；文件不存在返回空覆盖，JSON 错误记入 warnings。 */
+export function loadKeybindingsFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { overrides: {}, warnings: [] };
+        return { overrides: {}, warnings: [`读取 ${path} 失败：${error.message}`] };
+    }
+    try {
+        return parseKeybindings(JSON.parse(text));
+    }
+    catch (error) {
+        return { overrides: {}, warnings: [`${path} 不是合法 JSON：${error.message}`] };
+    }
+}
+export class Keybindings {
+    table;
+    constructor(overrides = {}) {
+        this.table = new Map();
+        for (const action of Object.keys(DEFAULT_KEYBINDINGS)) {
+            const keys = overrides[action] ?? DEFAULT_KEYBINDINGS[action];
+            this.table.set(action, keys.map((k) => normalizeKeyId(k)));
+        }
+    }
+    /** 动作绑定的 KeyId 列表（已规范化）。 */
+    keys(action) {
+        return this.table.get(action) ?? [];
+    }
+    /** 原始输入数据是否触发该动作。 */
+    matches(data, action) {
+        const key = parseKey(data);
+        if (key === undefined)
+            return false;
+        return this.keys(action).includes(key.id);
+    }
+    /** 输入数据触发的全部动作（按缺省表顺序），用于分派。 */
+    actionsFor(data) {
+        const key = parseKey(data);
+        if (key === undefined)
+            return [];
+        const out = [];
+        for (const [action, keys] of this.table)
+            if (keys.includes(key.id))
+                out.push(action);
+        return out;
+    }
+}
+/** 进程内共享的缺省键位（组件未显式传入时使用）。 */
+export const defaultKeybindings = new Keybindings();