@armadra/agent 0.2.1 → 0.4.0

package/dist/tui/components/markdown.js

@@ -4,7 +4,11 @@
  * 支持：ATX 标题、段落（软换行合并为空格，行尾两个空格或 `\` 为硬换行）、无序 / 有序列表（缩进嵌套）、
  * 围栏代码块（边框 + 语言标签；流式时未闭合的围栏按代码块渲染）、引用、分隔线、
  * 行内 `code` / **粗体** / *斜体* / ~~删除线~~ / [链接](url) / <自动链接> / 反斜杠转义。
- * 表格降级为等宽对齐文本（不换行、超宽截断）；不做语法高亮（§12.9）。
+ * 表格降级为等宽对齐文本（列间两个空格、首行粗体其下一条规则线、不换行、超宽截断）；不做语法高亮（§12.9）。
+ *
+ * 配色（终端界面视觉设计 v1 §3.3）：h1 / h2 `accent` 粗体，h3+ 粗体；行内代码 `code`；链接文字 `link`
+ * 加下划线、URL 以 ` (url)` `dim` 追加；列表符号 `muted`；代码块全宽、边框 `border`、语言标签 `dim`、
+ * 正文 `text`；引用 `▎` + `muted` 斜体。字形（圆点、框线、竖条）取 `theme.glyphs`。
  *
  * 缓存：按块缓存渲染结果（键 = 宽度 + 块源文本），流式追加时只有末块重新渲染；解析也是增量的
  * （`Markdown.append` 只从尾部可能变化的块重新解析）。
@@ -208,8 +212,8 @@ export function renderInline(text, theme) {
                 const url = link[2];
                 out +=
                     link[1] === url || url === ""
-                        ? theme.underline(label || url)
-                        : theme.underline(label) + theme.fg("dim", ` (${url})`);
+                        ? theme.fg("link", theme.underline(label || url))
+                        : theme.fg("link", theme.underline(label)) + theme.fg("dim", ` (${url})`);
                 i += link[0].length;
                 continue;
             }
@@ -217,7 +221,7 @@ export function renderInline(text, theme) {
         if (ch === "<") {
             const auto = /^<((?:https?|mailto):[^>\s]+)>/.exec(text.slice(i));
             if (auto) {
-                out += theme.underline(auto[1]);
+                out += theme.fg("link", theme.underline(auto[1]));
                 i += auto[0].length;
                 continue;
             }
@@ -263,17 +267,19 @@ export function renderBlock(block, width, theme) {
     switch (block.kind) {
         case "heading": {
             const text = renderInline(block.text, theme);
-            const styled = block.level <= 2 ? theme.fg("accent", theme.bold(text)) : theme.bold(text);
+            const styled = block.level <= 2
+                ? theme.fg("accent", theme.bold(text))
+                : theme.fg("text", theme.bold(text));
             return wrapTextWithAnsi(styled, width);
         }
         case "paragraph":
             return wrapTextWithAnsi(renderInline(block.text, theme), width);
         case "hr":
-            return [theme.fg("border", "─".repeat(Math.max(1, width)))];
+            return [theme.fg("border", theme.glyphs.rule.repeat(Math.max(1, width)))];
         case "quote": {
-            const bar = theme.fg("border", "│ ");
-            const inner = wrapTextWithAnsi(theme.italic(renderInline(block.text, theme)), width - 2);
-            return inner.map((line) => bar + line);
+            const bar = theme.fg("border", theme.glyphs.card) + " ";
+            const body = theme.fg("muted", theme.italic(renderInline(block.text, theme)));
+            return wrapTextWithAnsi(body, Math.max(1, width - 2)).map((line) => bar + line);
         }
         case "list":
             return renderList(block.items, width, theme);
@@ -283,15 +289,24 @@ export function renderBlock(block, width, theme) {
             return renderTable(block.rows, width, theme);
     }
 }
-const BULLETS = ["•", "◦", "▪"];
 function renderList(items, width, theme) {
     const lines = [];
+    const bullets = theme.glyphs.bullets;
+    /** 各层的正文起始列与无序层数（嵌套项对齐父项正文，圆点按无序层数换）。 */
+    const columns = [];
+    const unordered = [];
     for (const item of items) {
-        const indent = "  ".repeat(item.depth);
+        const depth = Math.min(item.depth, columns.length);
+        const indent = depth === 0 ? 0 : columns[depth - 1];
         const ordered = /\d/.test(item.marker);
-        const bullet = ordered ? item.marker : BULLETS[item.depth % BULLETS.length];
-        const head = indent + theme.fg("accent", bullet) + " ";
+        const level = (depth === 0 ? 0 : unordered[depth - 1]) + (ordered ? 0 : 1);
+        const bullet = ordered ? item.marker : bullets[(level - 1) % bullets.length];
+        const head = " ".repeat(indent) + theme.fg("muted", bullet) + " ";
         const headWidth = visibleWidth(head);
+        columns.length = depth;
+        unordered.length = depth;
+        columns.push(headWidth);
+        unordered.push(level);
         const body = wrapTextWithAnsi(renderInline(item.text, theme), Math.max(1, width - headWidth));
         body.forEach((line, index) => {
             lines.push((index === 0 ? head : " ".repeat(headWidth)) + line);
@@ -304,18 +319,21 @@ function renderCode(lang, body, width, theme) {
     if (width < 8)
         return code.map((line) => truncateToWidth(line, width));
     const inner = width - 4;
+    const g = theme.glyphs.box;
     const border = (s) => theme.fg("border", s);
     const label = lang === "" ? "" : truncateToWidth(` ${lang} `, inner - 1);
-    const top = border("╭─") +
+    const top = border(g.topLeft + g.horizontal) +
         theme.fg("dim", label) +
-        border("─".repeat(width - 3 - visibleWidth(label)) + "╮");
+        border(g.horizontal.repeat(width - 3 - visibleWidth(label)) + g.topRight);
     const lines = [top];
     for (const line of code) {
         for (const piece of wrapCode(line, inner)) {
-            lines.push(border("│ ") + padToWidth(theme.fg("code", piece), inner) + border(" │"));
+            lines.push(border(g.vertical + " ") +
+                padToWidth(theme.fg("text", piece), inner) +
+                border(" " + g.vertical));
         }
     }
-    lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+    lines.push(border(g.bottomLeft + g.horizontal.repeat(width - 2) + g.bottomRight));
     return lines;
 }
 /** 代码按列硬断行（不按词），空行保留。 */
@@ -345,12 +363,18 @@ function renderTable(rows, width, theme) {
     for (const row of rendered) {
         row.forEach((cell, c) => (widths[c] = Math.max(widths[c], visibleWidth(cell))));
     }
-    const sep = theme.fg("border", " │ ");
-    return rendered.map((row, r) => {
+    const lines = [];
+    rendered.forEach((row, r) => {
         const cells = widths.map((w, c) => padToWidth(row[c] ?? "", w));
-        const line = cells.join(sep).replace(/\s+$/, "");
-        return truncateToWidth(r === 0 && rows.length > 1 ? theme.bold(line) : line, width);
+        const line = cells.join("  ").replace(/\s+$/, "");
+        const header = r === 0 && rows.length > 1;
+        lines.push(truncateToWidth(header ? theme.bold(line) : line, width));
+        if (header) {
+            const total = widths.reduce((sum, w) => sum + w, 0) + 2 * Math.max(0, cols - 1);
+            lines.push(theme.fg("border", theme.glyphs.rule.repeat(Math.max(1, Math.min(total, width)))));
+        }
     });
+    return lines;
 }
 export class Markdown {
     text;

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

@@ -4,7 +4,7 @@
  * - `value` 是 0–1 的比例（越界夹紧）；undefined 显示 `—`，格子全空；
  * - 阈值着色（需要 theme）：≥ `dangerAt`（缺省 0.9）error，≥ `warnAt`（缺省 0.7）warning，否则 success；
  *   空格子 dim；
- * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断。
+ * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断；格子字形取 `theme.glyphs`（ASCII `# .`）。
  */
 import type { Component, SemanticColor, Theme } from "../component.js";
 export interface MeterOptions {
@@ -15,8 +15,8 @@ export interface MeterOptions {
     dangerAt?: number;
     theme?: Theme;
 }
-export declare const METER_FULL = "\u25AE";
-export declare const METER_EMPTY = "\u25AF";
+export declare const METER_FULL: string;
+export declare const METER_EMPTY: string;
 export declare class Meter implements Component {
     private value;
     private readonly options;

package/dist/tui/components/meter.js

@@ -4,11 +4,13 @@
  * - `value` 是 0–1 的比例（越界夹紧）；undefined 显示 `—`，格子全空；
  * - 阈值着色（需要 theme）：≥ `dangerAt`（缺省 0.9）error，≥ `warnAt`（缺省 0.7）warning，否则 success；
  *   空格子 dim；
- * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断。
+ * - 宽度不够时先去掉格子，只剩「标签 百分比」，再不够就截断；格子字形取 `theme.glyphs`（ASCII `# .`）。
  */
 import { truncateToWidth, visibleWidth } from "../ansi.js";
-export const METER_FULL = "▮";
-export const METER_EMPTY = "▯";
+import { levelColor } from "../theme.js";
+import { UNICODE_GLYPHS } from "../glyphs.js";
+export const METER_FULL = UNICODE_GLYPHS.meterFull;
+export const METER_EMPTY = UNICODE_GLYPHS.meterEmpty;
 export class Meter {
     value;
     options;
@@ -21,12 +23,11 @@ export class Meter {
     }
     /** 当前阈值档位对应的语义色。 */
     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";
+        const { warnAt, dangerAt } = this.options;
+        return levelColor(this.value ?? 0, {
+            ...(warnAt !== undefined ? { warnAt } : {}),
+            ...(dangerAt !== undefined ? { dangerAt } : {}),
+        });
     }
     render(width) {
         const { theme, label, cells = 10 } = this.options;
@@ -35,8 +36,9 @@ export class Meter {
         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 glyphs = theme?.glyphs ?? UNICODE_GLYPHS;
+        const bar = color(this.level(), glyphs.meterFull.repeat(filled)) +
+            color("dim", glyphs.meterEmpty.repeat(cells - filled));
         const tail = color(ratio === undefined ? "dim" : this.level(), percent);
         const full = `${head}${bar} ${tail}`;
         if (visibleWidth(full) <= width)

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

@@ -4,8 +4,15 @@
  * 键位走 `tui.select.*`：上下移动（循环）、翻页、确认（Enter / Tab）、取消（Esc / Ctrl+C）。
  * `filterable` 时可打印字符追加到过滤词、退格删除；过滤为大小写不敏感的分词子串匹配
  * （每个词都要出现在 label / value / group / description 之一中）。
+ *
+ * `badge` 靠右显示（如 `Default`、`Recommended`）；`numberKeys` 时右侧标 1–9，按数字直接选中并确认；
+ * `stacked` 时说明换到标签下一行（缩进、暗色），适合「名字 + 一行说明」的短列表。
+ *
+ * 终端界面视觉设计 v1：选中行 `›` + `selection` 底色（< 256 色退化为 accent 粗体，stacked 时两行都上）；
+ * `currentValue` 的项标 `✓`；`footer` 是列表下的一行按键提示（dim），`showCount` 时前面带 `(i/n)`
+ * （缺省只在超出一屏时带）；过滤框提示符 `›`。字形取 `theme.glyphs`。
  */
-import type { Component, Focusable, Theme } from "../component.js";
+import type { Component, Focusable, SemanticColor, Theme } from "../component.js";
 import { type Keybindings } from "../keybindings.js";
 export interface SelectItem {
     value: string;
@@ -13,6 +20,10 @@ export interface SelectItem {
     description?: string;
     /** 相邻项 group 不同时插入分组标题行。 */
     group?: string;
+    /** 靠右的徽标文字。 */
+    badge?: string;
+    /** 徽标颜色，缺省 accent。 */
+    badgeColor?: SemanticColor;
 }
 export interface SelectListOptions {
     /** 一屏最多显示的条目数，缺省 10。 */
@@ -21,6 +32,16 @@ export interface SelectListOptions {
     keybindings?: Keybindings;
     filterable?: boolean;
     emptyText?: string;
+    /** 右侧标序号，按 1–9 直接选中并确认（不与 filterable 同用）。 */
+    numberKeys?: boolean;
+    /** 说明放在标签下一行。 */
+    stacked?: boolean;
+    /** 列表下的按键提示行（dim）。 */
+    footer?: string;
+    /** 提示行前带 `(i/n)`；缺省只在超出一屏时带。 */
+    showCount?: boolean;
+    /** 当前值：该项标签前标 `✓`（其余项留同宽空白）。 */
+    currentValue?: string;
     onSelect?(item: SelectItem): void;
     onCancel?(): void;
     onSelectionChange?(item: SelectItem | undefined): void;
@@ -48,6 +69,7 @@ export declare class SelectList implements Component, Focusable {
     selectValue(value: string): boolean;
     moveSelection(delta: number, wrap?: boolean): void;
     handleInput(data: string): void;
+    private get glyphs();
     render(width: number): string[];
     invalidate(): void;
     private renderItem;

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

@@ -4,8 +4,16 @@
  * 键位走 `tui.select.*`：上下移动（循环）、翻页、确认（Enter / Tab）、取消（Esc / Ctrl+C）。
  * `filterable` 时可打印字符追加到过滤词、退格删除；过滤为大小写不敏感的分词子串匹配
  * （每个词都要出现在 label / value / group / description 之一中）。
+ *
+ * `badge` 靠右显示（如 `Default`、`Recommended`）；`numberKeys` 时右侧标 1–9，按数字直接选中并确认；
+ * `stacked` 时说明换到标签下一行（缩进、暗色），适合「名字 + 一行说明」的短列表。
+ *
+ * 终端界面视觉设计 v1：选中行 `›` + `selection` 底色（< 256 色退化为 accent 粗体，stacked 时两行都上）；
+ * `currentValue` 的项标 `✓`；`footer` 是列表下的一行按键提示（dim），`showCount` 时前面带 `(i/n)`
+ * （缺省只在超出一屏时带）；过滤框提示符 `›`。字形取 `theme.glyphs`。
  */
 import { padToWidth, truncateToWidth, visibleWidth } from "../ansi.js";
+import { UNICODE_GLYPHS } from "../glyphs.js";
 import { defaultKeybindings } from "../keybindings.js";
 import { isPrintableText, matchesKey } from "../keys.js";
 export function filterItems(items, filter) {
@@ -83,6 +91,14 @@ export class SelectList {
     }
     handleInput(data) {
         const k = this.keys;
+        if (this.options.numberKeys === true && /^[1-9]$/.test(data)) {
+            const index = Number(data) - 1;
+            if (index < this.filtered.length) {
+                this.setSelectedIndex(index);
+                this.options.onSelect?.(this.filtered[index]);
+            }
+            return;
+        }
         if (k.matches(data, "tui.select.up"))
             this.moveSelection(-1);
         else if (k.matches(data, "tui.select.down"))
@@ -108,16 +124,23 @@ export class SelectList {
             }
         }
     }
+    get glyphs() {
+        return this.options.theme?.glyphs ?? UNICODE_GLYPHS;
+    }
     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", "> ") : "> ";
+            const mark = `${this.glyphs.prompt} `;
+            const prompt = theme ? theme.fg("accent", mark) : mark;
             lines.push(truncateToWidth(prompt + this.filter + (this.focused ? "▏" : ""), width));
         }
         if (this.filtered.length === 0) {
             lines.push(truncateToWidth(dim(`  ${this.options.emptyText ?? "(no matches)"}`), width));
+            if (this.options.footer !== undefined) {
+                lines.push(truncateToWidth(dim(this.options.footer), width));
+            }
             return lines;
         }
         const end = Math.min(this.filtered.length, this.scrollTop + this.maxVisible);
@@ -129,27 +152,67 @@ export class SelectList {
                 lines.push(truncateToWidth(dim(item.group), width));
             }
             lastGroup = item.group;
-            lines.push(this.renderItem(item, i === this.selected, labelWidth, width));
+            lines.push(...this.renderItem(item, i, labelWidth, width));
         }
-        if (this.filtered.length > this.maxVisible) {
-            lines.push(truncateToWidth(dim(`  (${this.selected + 1}/${this.filtered.length})`), width));
+        const overflow = this.filtered.length > this.maxVisible;
+        const count = `(${this.selected + 1}/${this.filtered.length})`;
+        const footer = this.options.footer;
+        if (footer !== undefined) {
+            const withCount = this.options.showCount ?? overflow;
+            lines.push(truncateToWidth(dim(`${withCount ? `${count} ` : ""}${footer}`), width));
+        }
+        else if (overflow) {
+            lines.push(truncateToWidth(dim(`  ${count}`), width));
         }
         return lines;
     }
     invalidate() { }
-    renderItem(item, selected, labelWidth, width) {
+    renderItem(item, index, 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));
+        const selected = index === this.selected;
+        const dim = (s) => (theme ? theme.fg("dim", s) : s);
+        const rightParts = [];
+        if (item.badge !== undefined && item.badge !== "") {
+            rightParts.push(theme ? theme.fg(item.badgeColor ?? "accent", item.badge) : item.badge);
+        }
+        if (this.options.numberKeys === true && index < 9)
+            rightParts.push(dim(String(index + 1)));
+        let right = rightParts.join("  ");
+        if (visibleWidth(right) > Math.max(0, width - 8))
+            right = "";
+        const rightWidth = right === "" ? 0 : visibleWidth(right) + 1;
+        const g = this.glyphs;
+        const current = this.options.currentValue;
+        const check = current === undefined
+            ? ""
+            : item.value === current
+                ? (theme ? theme.fg(selected ? "accent" : "success", g.check) : g.check) + " "
+                : "  ";
+        const prefix = (selected ? `${g.prompt} ` : "  ") + check;
+        const prefixWidth = visibleWidth(prefix);
+        const labelRoom = Math.max(1, width - prefixWidth - rightWidth);
+        const label = truncateToWidth(item.label, labelRoom);
+        let line = padToWidth(label, Math.min(labelWidth, labelRoom));
         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);
+        line = (selected && theme ? theme.fg("accent", theme.bold(prefix)) : prefix) + line;
+        const stacked = this.options.stacked === true;
+        if (!stacked) {
+            const room = width - visibleWidth(line) - 2 - rightWidth;
+            if (item.description && room > 4) {
+                line += "  " + dim(truncateToWidth(item.description, room));
+            }
+        }
+        if (right !== "") {
+            line =
+                padToWidth(truncateToWidth(line, width - rightWidth), width - rightWidth) + " " + right;
+        }
+        const out = [truncateToWidth(line, width)];
+        if (stacked && item.description) {
+            const indent = " ".repeat(prefixWidth + 2);
+            out.push(truncateToWidth(`${indent}${dim(truncateToWidth(item.description, Math.max(1, width - indent.length)))}`, width));
         }
-        return truncateToWidth(line, width);
+        return selected && theme ? out.map((l) => theme.bg("selection", l)) : out;
     }
     labelColumnWidth(end) {
         let max = 0;

package/dist/tui/glyphs.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 字形表与 ASCII 回退（终端界面视觉设计 v1 §2.2）。
+ *
+ * 所有组件通过 `theme.glyphs` 取字形，不另加参数；`UNICODE_GLYPHS` 里每个字形都是 1 列宽
+ * （`codePointWidth` 判定，与 wcwidth 一致；个别字体把 `⏺` 画成两格时用 `AMA_ASCII=1`）。
+ *
+ * ASCII 触发：`ui.ascii: true` / `AMA_ASCII=1`，或自动检测——区域设置（`LC_ALL` > `LC_CTYPE` > `LANG`）
+ * 已设置但不含 UTF-8、`TERM=linux`、Windows 上 `WT_SESSION` 与 `TERM_PROGRAM` 都为空（旧 conhost）。
+ * `AMA_ASCII=0` 强制 Unicode。区域变量都没设时按 Unicode 处理（容器与 CI 里常见）。
+ */
+export interface BoxGlyphs {
+    readonly topLeft: string;
+    readonly topRight: string;
+    readonly bottomLeft: string;
+    readonly bottomRight: string;
+    readonly vertical: string;
+    readonly horizontal: string;
+}
+export interface Glyphs {
+    /** 是否 ASCII 回退表。 */
+    readonly ascii: boolean;
+    /** 用户消息、输入框提示符。 */
+    readonly prompt: string;
+    /** 工具调用标题。 */
+    readonly tool: string;
+    /** 结果连接符。 */
+    readonly result: string;
+    readonly ok: string;
+    readonly fail: string;
+    readonly warn: string;
+    /** 思考块、启动头标识。 */
+    readonly thinking: string;
+    /** 排队消息。 */
+    readonly queued: string;
+    /** 重试提示。 */
+    readonly retry: string;
+    /** Hook 阻止提示。 */
+    readonly blocked: string;
+    /** 左侧竖条卡片。 */
+    readonly card: string;
+    readonly expand: string;
+    readonly collapse: string;
+    /** 缓存保温。 */
+    readonly warm: string;
+    /** 当前项（选择器里打勾）。 */
+    readonly check: string;
+    /** 列表圆点（按嵌套深度循环）。 */
+    readonly bullets: readonly string[];
+    readonly meterFull: string;
+    readonly meterEmpty: string;
+    readonly box: BoxGlyphs;
+    /** 规则线（输入框上下、分隔线）。 */
+    readonly rule: string;
+    /** Loader 帧。 */
+    readonly spinner: readonly string[];
+    /** 静态 spinner（`ui.animation: false`）。 */
+    readonly spinnerStatic: string;
+    readonly ellipsis: string;
+    readonly arrowUp: string;
+    readonly arrowDown: string;
+}
+export declare const UNICODE_GLYPHS: Glyphs;
+export declare const ASCII_GLYPHS: Glyphs;
+/** 由环境判断是否用 ASCII 字形（`AMA_ASCII` 优先）。 */
+export declare function detectAscii(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** 配置与环境合并：`AMA_ASCII` 显式值 > `ui.ascii` > 自动检测。 */
+export declare function resolveAscii(configured: boolean | undefined, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+export declare function glyphsFor(ascii: boolean): Glyphs;

package/dist/tui/glyphs.js

@@ -0,0 +1,114 @@
+/**
+ * 字形表与 ASCII 回退（终端界面视觉设计 v1 §2.2）。
+ *
+ * 所有组件通过 `theme.glyphs` 取字形，不另加参数；`UNICODE_GLYPHS` 里每个字形都是 1 列宽
+ * （`codePointWidth` 判定，与 wcwidth 一致；个别字体把 `⏺` 画成两格时用 `AMA_ASCII=1`）。
+ *
+ * ASCII 触发：`ui.ascii: true` / `AMA_ASCII=1`，或自动检测——区域设置（`LC_ALL` > `LC_CTYPE` > `LANG`）
+ * 已设置但不含 UTF-8、`TERM=linux`、Windows 上 `WT_SESSION` 与 `TERM_PROGRAM` 都为空（旧 conhost）。
+ * `AMA_ASCII=0` 强制 Unicode。区域变量都没设时按 Unicode 处理（容器与 CI 里常见）。
+ */
+export const UNICODE_GLYPHS = {
+    ascii: false,
+    prompt: "›",
+    tool: "⏺",
+    result: "⎿",
+    ok: "✓",
+    fail: "✗",
+    warn: "!",
+    thinking: "✻",
+    queued: "↳",
+    retry: "↻",
+    blocked: "⛔",
+    card: "▎",
+    expand: "▸",
+    collapse: "▾",
+    warm: "♨",
+    check: "✓",
+    bullets: ["•", "◦", "▪"],
+    meterFull: "▮",
+    meterEmpty: "▯",
+    box: {
+        topLeft: "╭",
+        topRight: "╮",
+        bottomLeft: "╰",
+        bottomRight: "╯",
+        vertical: "│",
+        horizontal: "─",
+    },
+    rule: "─",
+    spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    spinnerStatic: "·",
+    ellipsis: "…",
+    arrowUp: "↑",
+    arrowDown: "↓",
+};
+export const ASCII_GLYPHS = {
+    ascii: true,
+    prompt: ">",
+    tool: "*",
+    result: "L",
+    ok: "v",
+    fail: "x",
+    warn: "!",
+    thinking: "~",
+    queued: "->",
+    retry: "@",
+    blocked: "X",
+    card: "|",
+    expand: ">",
+    collapse: "v",
+    warm: "~",
+    check: "v",
+    bullets: ["-", "*", "+"],
+    meterFull: "#",
+    meterEmpty: ".",
+    box: {
+        topLeft: "+",
+        topRight: "+",
+        bottomLeft: "+",
+        bottomRight: "+",
+        vertical: "|",
+        horizontal: "-",
+    },
+    rule: "-",
+    spinner: ["-", "\\", "|", "/"],
+    spinnerStatic: ".",
+    ellipsis: "...",
+    arrowUp: "^",
+    arrowDown: "v",
+};
+function truthy(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    const v = value.toLowerCase();
+    if (v === "1" || v === "true" || v === "yes" || v === "on")
+        return true;
+    if (v === "0" || v === "false" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+/** 由环境判断是否用 ASCII 字形（`AMA_ASCII` 优先）。 */
+export function detectAscii(env = process.env, platform = process.platform) {
+    const forced = truthy(env["AMA_ASCII"]);
+    if (forced !== undefined)
+        return forced;
+    const locale = env["LC_ALL"] || env["LC_CTYPE"] || env["LANG"] || "";
+    if (locale !== "" && !/utf-?8/i.test(locale))
+        return true;
+    if ((env["TERM"] ?? "") === "linux")
+        return true;
+    if (platform === "win32" && !env["WT_SESSION"] && !env["TERM_PROGRAM"])
+        return true;
+    return false;
+}
+/** 配置与环境合并：`AMA_ASCII` 显式值 > `ui.ascii` > 自动检测。 */
+export function resolveAscii(configured, env = process.env, platform = process.platform) {
+    const forced = truthy(env["AMA_ASCII"]);
+    if (forced !== undefined)
+        return forced;
+    return configured ?? detectAscii(env, platform);
+}
+export function glyphsFor(ascii) {
+    return ascii ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}

package/dist/tui/theme.d.ts

@@ -1,8 +1,11 @@
 /**
  * 主题与颜色能力（设计 §12.7）。[B4]
  *
- * - `dark` / `light` 两套语义色（§12.7 的 11 个名字），以 24 位 RGB 定义。
- * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（xterm 缺省调色板取近）→ 无色。
+ * - `dark` / `light` 两套语义色（14 个名字，终端界面视觉设计 v1 §2.1），以 24 位 RGB 定义；取值都落在
+ *   xterm 256 色立方 / 灰阶上，所以 256 色回退无损。
+ * - 能力降级：truecolor → 256 色（6×6×6 立方 + 灰阶取近）→ 16 色（内置色板按 `THEME_ANSI16` 查表，
+ *   覆盖色按 xterm 缺省调色板取近）→ 无色。
+ * - `bg("selection")` 在 < 256 色时退化为 `accent` 粗体前景（16 色下底色太跳，且常留「尾巴」）。
  * - `NO_COLOR`（非空）或 `TERM=dumb` → 无色；不探测终端背景（不发查询序列）。
  * - 样式用各自的关闭码（39 / 49 / 22 / 23 / 24）而不是全重置，可以嵌套。
  */
@@ -10,6 +13,21 @@ import type { ColorDepth, SemanticColor, Theme, ThemeCapabilities } from "./comp
 export type ThemeName = "dark" | "light";
 type Rgb = readonly [number, number, number];
 export declare const THEME_PALETTES: Record<ThemeName, Record<SemanticColor, string>>;
+/**
+ * 16 色下的索引（xterm 0–15）。距离取近对饱和色不可靠（`#ff5f5f` 会落到灰 8），所以内置色板查表；
+ * `selection` 在 16 色下不作 bg，表里给前景兜底值。
+ */
+export declare const THEME_ANSI16: Record<ThemeName, Record<SemanticColor, number>>;
+/** 阈值档位：≥ dangerAt error，≥ warnAt warning，否则 success（状态栏 ctx、Meter、/session 共用）。 */
+export declare function levelColor(ratio: number, thresholds?: {
+    warnAt?: number;
+    dangerAt?: number;
+}): SemanticColor;
+/**
+ * `auto` → dark / light：不发查询序列，只看环境。`COLORFGBG` 的最后一段是背景色号（0–6、8 暗，
+ * 7、9–15 亮）；没有时 Apple Terminal 按 dark；其余缺省 dark。只是猜，文档建议显式配置。
+ */
+export declare function resolveThemeName(name: ThemeName | "auto" | undefined, env?: NodeJS.ProcessEnv): ThemeName;
 /** 由环境推断颜色深度。 */
 export declare function detectColorDepth(env?: NodeJS.ProcessEnv, isTTY?: boolean): ColorDepth;
 export declare function detectCapabilities(env?: NodeJS.ProcessEnv, isTTY?: boolean): ThemeCapabilities;
@@ -18,14 +36,20 @@ export declare function parseHex(hex: string): Rgb;
 export declare function rgbTo256(rgb: Rgb): number;
 /** RGB → 16 色索引（0–15）。 */
 export declare function rgbTo16(rgb: Rgb): number;
-/** 生成前景 / 背景开启序列；depth 0 返回空串。 */
-export declare function colorCode(hex: string, depth: ColorDepth, background: boolean): string;
+/**
+ * 生成前景 / 背景开启序列；depth 0 返回空串。`ansi16` 给定时 16 色下直接用它（内置色板查表）。
+ */
+export declare function colorCode(hex: string, depth: ColorDepth, background: boolean, ansi16?: number): string;
 export interface CreateThemeOptions {
     caps?: ThemeCapabilities;
     /** 覆盖部分语义色（`#rrggbb`）。 */
     overrides?: Partial<Record<SemanticColor, string>>;
+    /** ASCII 字形；缺省按环境检测（`detectAscii`）。 */
+    ascii?: boolean;
 }
 export declare function createTheme(name?: ThemeName, options?: CreateThemeOptions): Theme;
-/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本。 */
-export declare function plainTheme(): Theme;
+/** 无色主题（测试、line 模式、NO_COLOR）：所有方法原样返回文本；字形缺省 Unicode。 */
+export declare function plainTheme(options?: {
+    ascii?: boolean;
+}): Theme;
 export {};