@armadra/agent 0.2.1 → 0.4.0

package/dist/tools/image-file.js

@@ -0,0 +1,114 @@
+/**
+ * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
+ *
+ * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
+ * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - 不解码像素，只读文件头取尺寸。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+import { AmaError } from "../errors.js";
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+export const IMAGE_EXTENSIONS = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/** 按扩展名（不分大小写）；不是图片返回 undefined。 */
+export function imageMimeFromPath(path) {
+    return IMAGE_EXTENSIONS[extname(path).toLowerCase()];
+}
+/** 按文件头识别；认不出返回 undefined。 */
+export function sniffImageMime(buf) {
+    if (buf.length >= 8 && buf.readUInt32BE(0) === 0x89504e47 && buf.readUInt32BE(4) === 0x0d0a1a0a)
+        return "image/png";
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return "image/jpeg";
+    if (buf.length >= 6 && /^GIF8[79]a$/.test(buf.toString("ascii", 0, 6)))
+        return "image/gif";
+    if (buf.length >= 12 &&
+        buf.toString("ascii", 0, 4) === "RIFF" &&
+        buf.toString("ascii", 8, 12) === "WEBP")
+        return "image/webp";
+    return undefined;
+}
+/** 只读文件头取尺寸；不认识返回 undefined。 */
+export function imageSize(buf, mimeType) {
+    try {
+        if (mimeType === "image/png" && buf.length >= 24) {
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        }
+        if (mimeType === "image/gif" && buf.length >= 10) {
+            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+        }
+        if (mimeType === "image/jpeg")
+            return jpegSize(buf);
+        if (mimeType === "image/webp")
+            return webpSize(buf);
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function jpegSize(buf) {
+    let i = 2;
+    while (i + 9 < buf.length) {
+        if (buf[i] !== 0xff) {
+            i++;
+            continue;
+        }
+        const marker = buf[i + 1] ?? 0;
+        const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (isSof)
+            return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+        i += 2 + buf.readUInt16BE(i + 2);
+    }
+    return undefined;
+}
+function webpSize(buf) {
+    if (buf.length < 30 || buf.toString("ascii", 0, 4) !== "RIFF")
+        return undefined;
+    const chunk = buf.toString("ascii", 12, 16);
+    if (chunk === "VP8 ") {
+        return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+    }
+    if (chunk === "VP8L") {
+        const b = buf.readUInt32LE(21);
+        return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === "VP8X") {
+        return { width: buf.readUIntLE(24, 3) + 1, height: buf.readUIntLE(27, 3) + 1 };
+    }
+    return undefined;
+}
+/**
+ * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
+ */
+export async function loadImageFile(path) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        throw new AmaError("invalid_arguments", `图片不存在：${path}`);
+    }
+    if (!info.isFile())
+        throw new AmaError("invalid_arguments", `不是文件：${path}`);
+    if (info.size > MAX_IMAGE_BYTES)
+        throw new AmaError("invalid_arguments", `图片超过 ${MAX_IMAGE_BYTES / 1024 / 1024} MB 上限：${path}（${(info.size / 1024 / 1024).toFixed(1)} MB）`);
+    const buf = await readFile(path);
+    const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(path);
+    if (mimeType === undefined)
+        throw new AmaError("invalid_arguments", `不是支持的图片（PNG / JPEG / GIF / WebP）：${path}`);
+    const size = imageSize(buf, mimeType);
+    return {
+        block: { type: "image", data: buf.toString("base64"), mimeType },
+        path,
+        mimeType,
+        bytes: buf.length,
+        ...(size ? { size } : {}),
+    };
+}

package/dist/tools/presets.d.ts

@@ -5,27 +5,52 @@
  * | ------------- | ----------------------------------------- |
  * | `default`     | read、edit、write、bash、grep、glob       |
  * | `minimal`     | read、edit、write、bash                   |
- * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `codemode-only` | 只有 codemode（其余工具在脚本里调用）   |
  * | `coordinator` | read + 宿主注册的工具                     |
  *
  * - 预设只管**内置**工具；宿主 / SDK 注册的工具（`canvas_*` 等）总在活动集里，除非用户
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
- * - codemode 开关跟随预设：`codemode` 预设 → `only`，其余 → `off`；`codemode.mode` 显式配置覆盖。
- * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（`codemode.mode` 为 off 时不注册）；不可用
- *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode 预设**回退到 default 并
- *   warning**（不报错：零配置用户不应因此起不来），`on` 同样忽略。
+ * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
+ * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
+ *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
+ *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
+ * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
+ *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPreset } from "../config/types.js";
+import { type AmaConfig, type CodemodeMode, type ToolsPreset } from "../config/types.js";
 import { ToolRegistry } from "./registry.js";
 import type { ToolDefinition, ToolSource } from "./types.js";
 export declare const CODEMODE_TOOL = "codemode";
-/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+/** 各预设下模型直接看到的内置工具（codemode-only 预设见 `resolvePreset`）。 */
 export declare const PRESET_TOOLS: Readonly<Record<ToolsPreset, readonly string[]>>;
+/**
+ * 预设对应的 codemode 模式（没有显式 `codemode.mode` 时）。`default` 只在沙箱 strict（Node ≥ 25，
+ * 权限模型同时隔离网络）时开 `on`：Node 22 / 24 下 codemode 属 execute 类，每次都要审批，`-p` 下
+ * 直接被拒，所以缺省关闭（启动时提示一次，见 cli/codemode-notice.ts）。
+ */
+export declare function presetCodemodeMode(preset: ToolsPreset, strict: boolean): CodemodeMode;
+export interface CodemodeModeResolution {
+    mode: CodemodeMode;
+    /** `config`：显式 `codemode.mode`；`preset`：跟随预设。 */
+    source: "config" | "preset";
+    preset: ToolsPreset;
+    strict: boolean;
+}
+/** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
+export declare function resolveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeModeResolution;
 /** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">): CodemodeMode;
+export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">, strict?: boolean): CodemodeMode;
+/**
+ * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
+ * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
+ */
+export declare function codemodeCallableFilter(config: Pick<AmaConfig, "tools">): "active" | undefined;
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
  * 返回去重后的名字（保持首次出现顺序）。
@@ -43,6 +68,8 @@ export declare function resolvePreset(input: {
     config: Pick<AmaConfig, "tools" | "codemode">;
     /** 该名字是否已注册（且未禁用）。 */
     available(name: string): boolean;
+    /** 沙箱是否 strict；缺省按运行时探测。 */
+    strict?: boolean;
 }): PresetResolution;
 type RegisterListener = (tool: ToolDefinition, source: ToolSource) => void;
 /**

package/dist/tools/presets.js

@@ -5,34 +5,68 @@
  * | ------------- | ----------------------------------------- |
  * | `default`     | read、edit、write、bash、grep、glob       |
  * | `minimal`     | read、edit、write、bash                   |
- * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `codemode-only` | 只有 codemode（其余工具在脚本里调用）   |
  * | `coordinator` | read + 宿主注册的工具                     |
  *
  * - 预设只管**内置**工具；宿主 / SDK 注册的工具（`canvas_*` 等）总在活动集里，除非用户
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
- * - codemode 开关跟随预设：`codemode` 预设 → `only`，其余 → `off`；`codemode.mode` 显式配置覆盖。
- * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（`codemode.mode` 为 off 时不注册）；不可用
- *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode 预设**回退到 default 并
- *   warning**（不报错：零配置用户不应因此起不来），`on` 同样忽略。
+ * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
+ * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
+ *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
+ *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
+ * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
+ *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
+import { detectSandboxCapability } from "../codemode/capability.js";
+import { canonicalPreset, } from "../config/types.js";
 import { ToolRegistry } from "./registry.js";
 export const CODEMODE_TOOL = "codemode";
-/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+/** 各预设下模型直接看到的内置工具（codemode-only 预设见 `resolvePreset`）。 */
 export const PRESET_TOOLS = Object.freeze({
     default: ["bash", "edit", "glob", "grep", "read", "write"],
     minimal: ["bash", "edit", "read", "write"],
-    codemode: [CODEMODE_TOOL],
+    "codemode-only": [CODEMODE_TOOL],
     coordinator: ["read"],
 });
-/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export function effectiveCodemodeMode(config) {
+/**
+ * 预设对应的 codemode 模式（没有显式 `codemode.mode` 时）。`default` 只在沙箱 strict（Node ≥ 25，
+ * 权限模型同时隔离网络）时开 `on`：Node 22 / 24 下 codemode 属 execute 类，每次都要审批，`-p` 下
+ * 直接被拒，所以缺省关闭（启动时提示一次，见 cli/codemode-notice.ts）。
+ */
+export function presetCodemodeMode(preset, strict) {
+    switch (preset) {
+        case "codemode-only":
+            return "only";
+        case "default":
+            return strict ? "on" : "off";
+        default:
+            return "off";
+    }
+}
+/** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
+export function resolveCodemodeMode(config, strict = detectSandboxCapability().strict) {
+    const preset = canonicalPreset(config.tools?.preset) ?? "default";
     const explicit = config.codemode?.mode;
     if (explicit !== undefined)
-        return explicit;
-    return config.tools?.preset === "codemode" ? "only" : "off";
+        return { mode: explicit, source: "config", preset, strict };
+    return { mode: presetCodemodeMode(preset, strict), source: "preset", preset, strict };
+}
+/** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
+export function effectiveCodemodeMode(config, strict) {
+    return resolveCodemodeMode(config, strict).mode;
+}
+/**
+ * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
+ * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
+ */
+export function codemodeCallableFilter(config) {
+    return canonicalPreset(config.tools?.preset) === "coordinator" ? "active" : undefined;
 }
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
@@ -55,13 +89,18 @@ export function applyToolAdjustments(base, adjustments) {
 }
 export function resolvePreset(input) {
     const warnings = [];
-    let preset = input.config.tools?.preset ?? "default";
-    let codemode = effectiveCodemodeMode(input.config);
+    const resolved = resolveCodemodeMode(input.config, input.strict);
+    let preset = resolved.preset;
+    let codemode = resolved.mode;
+    // 跟随预设得到的 on（default 预设）在 codemode 不可用时静默回退：零配置不该因此出 warning。
+    if (codemode === "on" && resolved.source === "preset" && !input.available(CODEMODE_TOOL)) {
+        codemode = "off";
+    }
     if (codemode !== "off" && !input.available(CODEMODE_TOOL)) {
-        warnings.push(preset === "codemode"
-            ? "工具预设 codemode 需要 codemode 工具（不可用），已回退到 default"
+        warnings.push(preset === "codemode-only"
+            ? "工具预设 codemode-only 需要 codemode 工具（不可用），已回退到 default"
             : `codemode.mode ${codemode} 需要 codemode 工具（不可用），已忽略`);
-        if (preset === "codemode")
+        if (preset === "codemode-only")
             preset = "default";
         codemode = "off";
     }
@@ -69,7 +108,7 @@ export function resolvePreset(input) {
     if (codemode === "only")
         base = [CODEMODE_TOOL];
     else {
-        base = [...PRESET_TOOLS[preset === "codemode" ? "default" : preset]];
+        base = [...PRESET_TOOLS[preset === "codemode-only" ? "default" : preset]];
         if (codemode === "on")
             base.push(CODEMODE_TOOL);
     }

package/dist/tools/read.d.ts

@@ -2,10 +2,12 @@
  * `read` 工具（设计 §5.2）。[B3]
  *
  * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
- * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（模型不支持
- * 图片时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
+ * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
+ * `ctx.markRead(abs)`。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export { imageSize, type ImageSize } from "./image-file.js";
 export interface ReadInput {
     path: string;
     offset?: number;
@@ -16,12 +18,6 @@ export interface ReadToolOptions {
     supportsImages?(ctx: ToolContext): boolean;
 }
 export declare function isBinary(buf: Buffer): boolean;
-export interface ImageSize {
-    width: number;
-    height: number;
-}
-/** 只读文件头取尺寸；不认识返回 undefined。 */
-export declare function imageSize(buf: Buffer, mimeType: string): ImageSize | undefined;
 /** `cat -n` 形状。 */
 export declare function numberLines(lines: readonly string[], firstLine: number): string;
 export declare function executeRead(input: ReadInput, ctx: ToolContext, options?: ReadToolOptions): Promise<ToolResult>;

package/dist/tools/read.js

@@ -2,21 +2,16 @@
  * `read` 工具（设计 §5.2）。[B3]
  *
  * 文本按 `cat -n` 形状返回（行号右对齐 6 位 + Tab）；头截断 2000 行 / 50 KB 先到者，末尾提示
- * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（模型不支持
- * 图片时只给路径与尺寸）；成功后 `ctx.markRead(abs)`。
+ * `offset` 续读；NUL 嗅探判二进制并拒绝；png / jpg / gif / webp 作为 ImageBlock 返回（MIME 按文件头，
+ * 与 `--image` / `@图片` 共用 image-file.ts；模型不支持图片或超过 5 MB 时只给路径与尺寸）；成功后
+ * `ctx.markRead(abs)`。
  */
 import { readFile, stat } from "node:fs/promises";
-import { extname } from "node:path";
 import { displayPath, resolvePath } from "./paths.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
 import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
-const IMAGE_MIME = {
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-};
+import { MAX_IMAGE_BYTES, imageMimeFromPath, imageSize, sniffImageMime } from "./image-file.js";
+export { imageSize } from "./image-file.js";
 const SNIFF_BYTES = 8000;
 export function isBinary(buf) {
     const end = Math.min(buf.length, SNIFF_BYTES);
@@ -25,56 +20,6 @@ export function isBinary(buf) {
             return true;
     return false;
 }
-/** 只读文件头取尺寸；不认识返回 undefined。 */
-export function imageSize(buf, mimeType) {
-    try {
-        if (mimeType === "image/png" && buf.length >= 24) {
-            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
-        }
-        if (mimeType === "image/gif" && buf.length >= 10) {
-            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
-        }
-        if (mimeType === "image/jpeg")
-            return jpegSize(buf);
-        if (mimeType === "image/webp")
-            return webpSize(buf);
-    }
-    catch {
-        return undefined;
-    }
-    return undefined;
-}
-function jpegSize(buf) {
-    let i = 2;
-    while (i + 9 < buf.length) {
-        if (buf[i] !== 0xff) {
-            i++;
-            continue;
-        }
-        const marker = buf[i + 1] ?? 0;
-        const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
-        if (isSof)
-            return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
-        i += 2 + buf.readUInt16BE(i + 2);
-    }
-    return undefined;
-}
-function webpSize(buf) {
-    if (buf.length < 30 || buf.toString("ascii", 0, 4) !== "RIFF")
-        return undefined;
-    const chunk = buf.toString("ascii", 12, 16);
-    if (chunk === "VP8 ") {
-        return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
-    }
-    if (chunk === "VP8L") {
-        const b = buf.readUInt32LE(21);
-        return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
-    }
-    if (chunk === "VP8X") {
-        return { width: buf.readUIntLE(24, 3) + 1, height: buf.readUIntLE(27, 3) + 1 };
-    }
-    return undefined;
-}
 function error(message) {
     return { content: message, isError: true };
 }
@@ -82,8 +27,9 @@ function error(message) {
 export function numberLines(lines, firstLine) {
     return lines.map((line, i) => `${String(firstLine + i).padStart(6)}\t${line}`).join("\n");
 }
-async function readImage(abs, shown, mimeType, ctx, options) {
+async function readImage(abs, shown, ctx, options) {
     const buf = await readFile(abs);
+    const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(abs) ?? "application/octet-stream";
     const size = imageSize(buf, mimeType);
     const dims = size ? `${size.width}x${size.height}, ` : "";
     const caption = `Image: ${shown} (${dims}${mimeType}, ${formatSize(buf.length)})`;
@@ -92,6 +38,12 @@ async function readImage(abs, shown, mimeType, ctx, options) {
     if (options.supportsImages && !options.supportsImages(ctx)) {
         return { content: `${caption}\n[The current model does not accept image input.]`, details };
     }
+    if (buf.length > MAX_IMAGE_BYTES) {
+        return {
+            content: `${caption}\n[Image exceeds the ${formatSize(MAX_IMAGE_BYTES)} attachment limit; not attached.]`,
+            details,
+        };
+    }
     const blocks = [
         { type: "text", text: caption },
         { type: "image", data: buf.toString("base64"), mimeType },
@@ -110,9 +62,8 @@ export async function executeRead(input, ctx, options = {}) {
     }
     if (info.isDirectory())
         return error(`${shown} is a directory; use the ls tool instead`);
-    const mimeType = IMAGE_MIME[extname(abs).toLowerCase()];
-    if (mimeType !== undefined)
-        return readImage(abs, shown, mimeType, ctx, options);
+    if (imageMimeFromPath(abs) !== undefined)
+        return readImage(abs, shown, ctx, options);
     const buf = await readFile(abs);
     if (isBinary(buf))
         return error(`${shown} appears to be a binary file; refusing to read it`);

package/dist/tui/component.d.ts

@@ -3,9 +3,13 @@
  *
  * 补全与偏差：
  * - 设计的 `Theme` 写作 `bg(...)` 与 `bold/dim/italic/underline(s)`，此处展开为完整签名。
- * - `SemanticColor` 取 §12.7 的 11 个语义色名。
+ * - `SemanticColor` 取 §12.7 的 11 个语义色名；终端界面视觉设计 v1 加 `muted`（正文与 dim 之间的次要文字）、
+ *   `link`（链接文字）、`selection`（选中行底色，只在 ≥ 256 色时作 bg）共 14 个。
  * - 补全 `CURSOR_MARKER` 常量与 `isFocusable()` 判别函数（B4 的 tui.ts 与 B7 都要用）。
+ * - 终端界面视觉设计 v1：`Theme.glyphs`（字形表与 ASCII 回退，见 glyphs.ts）。
  */
+import type { Glyphs } from "./glyphs.js";
+export type { Glyphs, BoxGlyphs } from "./glyphs.js";
 /** APC 序列；获焦组件在光标处输出它，TUI 据此摆硬件光标并在输出前剔除。 */
 export declare const CURSOR_MARKER = "\u001B_ama:c\u0007";
 export interface Component {
@@ -20,7 +24,7 @@ export interface Focusable {
     focused: boolean;
 }
 export declare function isFocusable(component: Component): component is Component & Focusable;
-export type SemanticColor = "text" | "dim" | "accent" | "success" | "warning" | "error" | "user" | "assistant" | "tool" | "border" | "code";
+export type SemanticColor = "text" | "dim" | "accent" | "success" | "warning" | "error" | "user" | "assistant" | "tool" | "border" | "code" | "muted" | "link" | "selection";
 /** 0 = 无色（NO_COLOR）；16_777_216 = truecolor。 */
 export type ColorDepth = 0 | 16 | 256 | 16_777_216;
 export interface ThemeCapabilities {
@@ -35,4 +39,6 @@ export interface Theme {
     italic(text: string): string;
     underline(text: string): string;
     readonly caps: ThemeCapabilities;
+    /** 字形（Unicode 或 ASCII 回退）；组件一律从这里取。 */
+    readonly glyphs: Glyphs;
 }

package/dist/tui/component.js

@@ -3,8 +3,10 @@
  *
  * 补全与偏差：
  * - 设计的 `Theme` 写作 `bg(...)` 与 `bold/dim/italic/underline(s)`，此处展开为完整签名。
- * - `SemanticColor` 取 §12.7 的 11 个语义色名。
+ * - `SemanticColor` 取 §12.7 的 11 个语义色名；终端界面视觉设计 v1 加 `muted`（正文与 dim 之间的次要文字）、
+ *   `link`（链接文字）、`selection`（选中行底色，只在 ≥ 256 色时作 bg）共 14 个。
  * - 补全 `CURSOR_MARKER` 常量与 `isFocusable()` 判别函数（B4 的 tui.ts 与 B7 都要用）。
+ * - 终端界面视觉设计 v1：`Theme.glyphs`（字形表与 ASCII 回退，见 glyphs.ts）。
  */
 /** APC 序列；获焦组件在光标处输出它，TUI 据此摆硬件光标并在输出前剔除。 */
 export const CURSOR_MARKER = "\x1b_ama:c\x07";

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

@@ -2,15 +2,19 @@
  * 边框 / 内边距容器（设计 §12.1）。[B4]
  *
  * 子组件按内宽渲染后加圆角边框（可选标题，嵌在上边框）与内边距；宽度不足 4 列时退化为只加内边距。
+ * 边框字形取 `theme.glyphs.box`（ASCII 下为 `+ - |`），颜色缺省 `border`，可用 `borderColor` 改
+ * （审批对话框按严重度用 error / warning）。
  * 焦点与键输入透传给子组件，所以可以直接把 `Box(SelectList)` 交给 `showOverlay`。
  */
-import { type Component, type Theme } from "../component.js";
+import { type Component, type SemanticColor, type Theme } from "../component.js";
 export interface BoxOptions {
     border?: boolean;
     paddingX?: number;
     paddingY?: number;
     title?: string;
     theme?: Theme;
+    /** 边框颜色，缺省 `border`。 */
+    borderColor?: SemanticColor;
 }
 export declare class Box implements Component {
     readonly child: Component;
@@ -21,6 +25,7 @@ export declare class Box implements Component {
     set focused(value: boolean);
     handleInput(data: string): void;
     render(width: number): string[];
+    private get glyphs();
     private topBorder;
     invalidate(): void;
 }

package/dist/tui/components/box.js

@@ -2,10 +2,13 @@
  * 边框 / 内边距容器（设计 §12.1）。[B4]
  *
  * 子组件按内宽渲染后加圆角边框（可选标题，嵌在上边框）与内边距；宽度不足 4 列时退化为只加内边距。
+ * 边框字形取 `theme.glyphs.box`（ASCII 下为 `+ - |`），颜色缺省 `border`，可用 `borderColor` 改
+ * （审批对话框按严重度用 error / warning）。
  * 焦点与键输入透传给子组件，所以可以直接把 `Box(SelectList)` 交给 `showOverlay`。
  */
 import { isFocusable } from "../component.js";
 import { padToWidth, truncateToWidth, visibleWidth } from "../ansi.js";
+import { UNICODE_GLYPHS } from "../glyphs.js";
 export class Box {
     child;
     options;
@@ -31,7 +34,9 @@ export class Box {
         const frame = border ? 2 : 0;
         const inner = Math.max(1, width - frame - padX * 2);
         const body = this.child.render(inner);
-        const color = (s) => this.options.theme ? this.options.theme.fg("border", s) : s;
+        const borderColor = this.options.borderColor ?? "border";
+        const color = (s) => this.options.theme ? this.options.theme.fg(borderColor, s) : s;
+        const g = this.glyphs;
         const pad = " ".repeat(padX);
         const contentWidth = Math.max(0, width - frame);
         const rows = [];
@@ -47,17 +52,22 @@ export class Box {
             return rows;
         const lines = [this.topBorder(width, color)];
         for (const row of rows)
-            lines.push(color("│") + row + color("│"));
-        lines.push(color("╰" + "─".repeat(width - 2) + "╯"));
+            lines.push(color(g.vertical) + row + color(g.vertical));
+        lines.push(color(g.bottomLeft + g.horizontal.repeat(width - 2) + g.bottomRight));
         return lines;
     }
+    get glyphs() {
+        return (this.options.theme?.glyphs ?? UNICODE_GLYPHS).box;
+    }
     topBorder(width, color) {
+        const g = this.glyphs;
         const title = this.options.title;
-        if (title === undefined || title === "")
-            return color("╭" + "─".repeat(width - 2) + "╮");
+        if (title === undefined || title === "") {
+            return color(g.topLeft + g.horizontal.repeat(width - 2) + g.topRight);
+        }
         const label = truncateToWidth(` ${title} `, width - 4);
         const rest = Math.max(0, width - 3 - visibleWidth(label));
-        return color("╭─") + label + color("─".repeat(rest) + "╮");
+        return color(g.topLeft + g.horizontal) + label + color(g.horizontal.repeat(rest) + g.topRight);
     }
     invalidate() {
         this.child.invalidate();

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

@@ -0,0 +1,23 @@
+/**
+ * 左竖条卡片（终端界面视觉设计 v1 §3.6、§3.13）：压缩摘要、`/session` 等面板。
+ *
+ * 每行前加 `theme.glyphs.card`（`▎`，ASCII `|`）与一个空格，竖条用 `border` 色；可选标题行（正文色粗体）
+ * 与跟在标题后的副标题（`muted`，两个空格隔开）。不加上下边框——Box 只留给代码块、启动头与覆盖层。
+ * 子组件按 `width - 2` 渲染；空行只画竖条。
+ */
+import type { Component, SemanticColor, Theme } from "../component.js";
+export interface CardOptions {
+    theme?: Theme;
+    title?: string;
+    /** 标题后的次要说明（muted）。 */
+    subtitle?: string;
+    /** 竖条颜色，缺省 `border`。 */
+    barColor?: SemanticColor;
+}
+export declare class Card implements Component {
+    readonly child: Component | undefined;
+    private readonly options;
+    constructor(child: Component | undefined, options?: CardOptions);
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/tui/components/card.js

@@ -0,0 +1,37 @@
+/**
+ * 左竖条卡片（终端界面视觉设计 v1 §3.6、§3.13）：压缩摘要、`/session` 等面板。
+ *
+ * 每行前加 `theme.glyphs.card`（`▎`，ASCII `|`）与一个空格，竖条用 `border` 色；可选标题行（正文色粗体）
+ * 与跟在标题后的副标题（`muted`，两个空格隔开）。不加上下边框——Box 只留给代码块、启动头与覆盖层。
+ * 子组件按 `width - 2` 渲染；空行只画竖条。
+ */
+import { truncateToWidth } from "../ansi.js";
+import { UNICODE_GLYPHS } from "../glyphs.js";
+export class Card {
+    child;
+    options;
+    constructor(child, options = {}) {
+        this.child = child;
+        this.options = options;
+    }
+    render(width) {
+        const { theme, title, subtitle } = this.options;
+        const glyph = (theme?.glyphs ?? UNICODE_GLYPHS).card;
+        const bar = theme ? theme.fg(this.options.barColor ?? "border", glyph) : glyph;
+        const inner = Math.max(1, width - 2);
+        const lines = [];
+        if (title !== undefined && title !== "") {
+            let head = theme ? theme.bold(title) : title;
+            if (subtitle !== undefined && subtitle !== "") {
+                head += "  " + (theme ? theme.fg("muted", subtitle) : subtitle);
+            }
+            lines.push(head);
+        }
+        if (this.child)
+            lines.push(...this.child.render(inner));
+        return lines.map((line) => line === "" ? bar : truncateToWidth(`${bar} ${truncateToWidth(line, inner)}`, width));
+    }
+    invalidate() {
+        this.child?.invalidate();
+    }
+}

package/dist/tui/components/editor-history.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 编辑器的历史文件（设计 §12.4）：JSONL，每行一个 JSON 字符串，保留最近 `limit` 条。[B4]
+ * 读写失败都不影响编辑（损坏的行跳过；写失败静默）。
+ */
+export declare function loadHistoryFile(path: string, limit?: number): string[];
+export declare function appendHistoryFile(path: string, entry: string, limit: number): void;