@armadra/agent 0.2.1 → 0.4.0

package/dist/config/schema.js

@@ -8,7 +8,7 @@
 import { HOOK_EVENTS } from "../hooks/types.js";
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
-import { CACHE_RETENTIONS, CODEMODE_MODES, TOOLS_PRESETS_STRICT_FIRST } from "./types.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESET_INPUTS, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 export const HOOK_TIMEOUT_MAX_MS = 600_000;
@@ -116,6 +116,7 @@ const CONFIG_KEYS = [
     "ui",
     "skills",
     "cache",
+    "request",
     "$schema",
 ];
 const PROVIDER_KEYS = [
@@ -128,9 +129,12 @@ const PROVIDER_KEYS = [
     "headers",
     "compat",
     "requiresApiKey",
+    "channels",
+    "defaultChannel",
     "models",
     "modelOverrides",
 ];
+const CHANNEL_KEYS = ["api", "baseUrl", "apiKey", "authHeader", "headers", "compat"];
 /** 第三波 §1.3 的缓存兼容开关（其余 compat 字段按协议各异，只查是对象）。 */
 const CACHE_COMPAT_FLAGS = [
     "sendPromptCacheKey",
@@ -138,7 +142,7 @@ const CACHE_COMPAT_FLAGS = [
     "supportsLongCacheRetention",
     "supportsExplicitPromptCacheMode",
 ];
-function checkModels(c, value, path) {
+function checkModels(c, value, path, channels) {
     if (value === undefined)
         return;
     if (!Array.isArray(value)) {
@@ -157,6 +161,24 @@ function checkModels(c, value, path) {
         c.string(item, "api", p);
         c.string(item, "baseUrl", p);
         c.stringRecord(item, "headers", p);
+        const modelsDev = item["modelsDev"];
+        if (modelsDev !== undefined &&
+            modelsDev !== false &&
+            (typeof modelsDev !== "string" || !/^[^/]+\/.+$/.test(modelsDev))) {
+            c.error(join(p, "modelsDev"), `应为 "provider/model" 或 false`);
+        }
+        c.stringArray(item, "channels", p);
+        const used = item["channels"];
+        if (Array.isArray(used)) {
+            used.forEach((name, i) => {
+                if (typeof name !== "string")
+                    return;
+                if (channels === undefined)
+                    c.error(join(join(p, "channels"), i), "供应商没有 channels");
+                else if (!channels.has(name))
+                    c.error(join(join(p, "channels"), i), `渠道 "${name}" 不存在（可用：${[...channels].join(", ")}）`);
+            });
+        }
         const promptCache = item["promptCache"];
         if (promptCache !== undefined && c.object(promptCache, join(p, "promptCache"))) {
             const pp = join(p, "promptCache");
@@ -171,6 +193,51 @@ function checkModels(c, value, path) {
         }
     });
 }
+function checkCompat(c, compat, path) {
+    if (compat === undefined || !c.object(compat, path))
+        return;
+    for (const key of CACHE_COMPAT_FLAGS)
+        c.boolean(compat, key, path);
+    c.oneOf(compat, "cacheReporting", path, ["auto", "silent", "reported"]);
+}
+/** 返回合法的渠道名集合；没有 `channels` 时 undefined。 */
+function checkChannels(c, value, path) {
+    const channels = value["channels"];
+    if (channels === undefined)
+        return undefined;
+    const cp = join(path, "channels");
+    if (!c.object(channels, cp))
+        return new Set();
+    const names = new Set();
+    for (const [name, channel] of Object.entries(channels)) {
+        const p = join(cp, name);
+        if (!CHANNEL_NAME_PATTERN.test(name)) {
+            c.error(p, "渠道名只能含字母、数字、_ 与 -（不含 / 与 @），最长 32");
+            continue;
+        }
+        names.add(name);
+        if (!c.object(channel, p))
+            continue;
+        c.keys(channel, p, CHANNEL_KEYS);
+        c.string(channel, "api", p, true);
+        c.string(channel, "baseUrl", p, true);
+        c.string(channel, "apiKey", p);
+        c.stringRecord(channel, "headers", p);
+        if (channel["authHeader"] !== undefined)
+            c.object(channel["authHeader"], join(p, "authHeader"));
+        checkCompat(c, channel["compat"], join(p, "compat"));
+    }
+    if (names.size === 0 && Object.keys(channels).length === 0)
+        c.error(cp, "至少要有一个渠道");
+    const preferred = value["defaultChannel"];
+    if (preferred !== undefined) {
+        if (typeof preferred !== "string")
+            c.error(join(path, "defaultChannel"), "应为字符串");
+        else if (!names.has(preferred))
+            c.error(join(path, "defaultChannel"), `渠道 "${preferred}" 不存在`);
+    }
+    return names;
+}
 function checkProvider(c, value, path) {
     if (!c.object(value, path))
         return;
@@ -180,17 +247,14 @@ function checkProvider(c, value, path) {
     c.stringArray(value, "envKeys", path);
     c.stringRecord(value, "headers", path);
     c.boolean(value, "requiresApiKey", path);
-    const compat = value["compat"];
-    if (compat !== undefined && c.object(compat, join(path, "compat"))) {
-        const cp = join(path, "compat");
-        for (const key of CACHE_COMPAT_FLAGS)
-            c.boolean(compat, key, cp);
-        c.oneOf(compat, "cacheReporting", cp, ["auto", "silent", "reported"]);
-    }
+    checkCompat(c, value["compat"], join(path, "compat"));
     if (value["authHeader"] !== undefined)
         c.object(value["authHeader"], join(path, "authHeader"));
-    checkModels(c, value["models"], join(path, "models"));
-    checkModels(c, value["modelOverrides"], join(path, "modelOverrides"));
+    const channels = checkChannels(c, value, path);
+    if (channels === undefined && value["defaultChannel"] !== undefined)
+        c.error(join(path, "defaultChannel"), "没有 channels 时不能设 defaultChannel");
+    checkModels(c, value["models"], join(path, "models"), channels);
+    checkModels(c, value["modelOverrides"], join(path, "modelOverrides"), channels);
 }
 function checkSection(c, config, key, allowed, body) {
     const section = config[key];
@@ -215,10 +279,13 @@ export function validateConfig(value) {
             checkProvider(c, provider, join("providers", id));
         }
     }
-    checkSection(c, value, "permission", ["mode", "allow", "deny", "builtinDeny"], (s, p) => {
+    const permissionKeys = ["mode", "allow", "deny", "builtinDeny", "autoModel", "autoSafeCommands"];
+    checkSection(c, value, "permission", permissionKeys, (s, p) => {
         c.oneOf(s, "mode", p, PERMISSION_MODES_STRICT_FIRST);
         c.stringArray(s, "allow", p);
         c.stringArray(s, "deny", p);
+        c.string(s, "autoModel", p);
+        c.stringArray(s, "autoSafeCommands", p);
         const builtinDeny = s["builtinDeny"];
         if (builtinDeny !== undefined &&
             typeof builtinDeny !== "boolean" &&
@@ -238,7 +305,7 @@ export function validateConfig(value) {
         c.number(s, "maxDelayMs", p);
     });
     checkSection(c, value, "tools", ["preset", "default", "maxToolResultChars", "bashTimeoutMs", "disabled"], (s, p) => {
-        c.oneOf(s, "preset", p, TOOLS_PRESETS_STRICT_FIRST);
+        c.oneOf(s, "preset", p, TOOLS_PRESET_INPUTS);
         c.stringArray(s, "default", p);
         c.number(s, "maxToolResultChars", p, 1);
         c.number(s, "bashTimeoutMs", p, 1);
@@ -252,14 +319,29 @@ export function validateConfig(value) {
     checkSection(c, value, "hooks", ["timeoutMs"], (s, p) => {
         c.number(s, "timeoutMs", p, 1, HOOK_TIMEOUT_MAX_MS);
     });
-    checkSection(c, value, "ui", ["theme", "markdown", "showThinking", "tuiMode", "quietStartup"], (s, p) => {
-        c.oneOf(s, "theme", p, ["dark", "light"]);
+    checkSection(c, value, "ui", [
+        "theme",
+        "markdown",
+        "showThinking",
+        "tuiMode",
+        "quietStartup",
+        "ascii",
+        "compact",
+        "animation",
+    ], (s, p) => {
+        c.oneOf(s, "theme", p, ["dark", "light", "auto"]);
         c.boolean(s, "markdown", p);
         c.oneOf(s, "showThinking", p, ["full", "collapsed", "hidden"]);
         c.oneOf(s, "tuiMode", p, ["regular"]);
         c.oneOf(s, "quietStartup", p, ["normal", "header", "silent"]);
+        c.boolean(s, "ascii", p);
+        c.boolean(s, "compact", p);
+        c.boolean(s, "animation", p);
     });
     checkSection(c, value, "skills", ["dirs"], (s, p) => c.stringArray(s, "dirs", p));
+    checkSection(c, value, "request", ["idleTimeoutMs"], (s, p) => {
+        c.number(s, "idleTimeoutMs", p, 0);
+    });
     checkSection(c, value, "cache", ["warming", "retention", "minSavingsUsd", "missNotices", "warmSubagents"], (s, p) => {
         c.oneOf(s, "warming", p, WARMING_MODES);
         c.oneOf(s, "retention", p, CACHE_RETENTIONS);

package/dist/config/types.d.ts

@@ -16,13 +16,27 @@ export declare const CONFIG_FILE_VERSION: 1;
  * 自定义模型条目；缺省 maxTokens 8192、reasoning false、input ["text"]，不猜 contextWindow。
  * `api` 缺省沿用供应商的协议。
  */
-export type ModelConfig = Partial<Omit<Model, "id" | "provider">> & {
-    id: string;
-};
-/** 只改元数据的覆盖项（含模型级 `api`）。 */
-export type ModelOverride = Partial<Omit<Model, "id" | "provider">> & {
+export type ModelConfig = Partial<Omit<Model, "id" | "provider" | "channel" | "channels">> & {
     id: string;
+    /** 挂载的渠道名，第一个是首选；缺省 `defaultChannel`（docs/providers.md「渠道」）。 */
+    channels?: string[];
+    /** models.dev 条目 `provider/model`（显式匹配）；false 关闭 models.dev 补全。 */
+    modelsDev?: string | false;
 };
+/** 只改元数据的覆盖项（含模型级 `api` 与 `channels`）。 */
+export type ModelOverride = ModelConfig;
+/** 渠道：协议 + 地址（+ 可选 key / headers / compat），缺省继承供应商级。 */
+export interface ChannelConfig {
+    api: Api;
+    baseUrl: string;
+    /** 同供应商级 `apiKey` 的写法；缺省用供应商的 key。 */
+    apiKey?: string;
+    authHeader?: AuthHeader;
+    headers?: Record<string, string>;
+    compat?: ProviderCompat;
+}
+/** 渠道名：不含 `/` 与 `@`（`provider/model@channel`）。 */
+export declare const CHANNEL_NAME_PATTERN: RegExp;
 export interface ProviderConfig {
     name?: string;
     /** 自定义供应商缺省 openai-completions。 */
@@ -35,6 +49,10 @@ export interface ProviderConfig {
     headers?: Record<string, string>;
     compat?: ProviderCompat;
     requiresApiKey?: boolean;
+    /** 多渠道（docs/providers.md「渠道」）；不写时 `api` + `baseUrl` 是隐式的 `default` 渠道。 */
+    channels?: Record<string, ChannelConfig>;
+    /** 缺省 `channels` 的第一个键。 */
+    defaultChannel?: string;
     models?: ModelConfig[];
     modelOverrides?: ModelOverride[];
 }
@@ -47,6 +65,10 @@ export interface PermissionConfig {
      * 数组 = 要移除的规则原文。放宽项，只认用户级 / profile，项目级忽略并 warning。
      */
     builtinDeny?: boolean | string[];
+    /** auto 模式分类器的模型（`provider/model`）；缺省 = 当前会话模型。放宽项，项目级忽略。 */
+    autoModel?: string;
+    /** auto 模式安全名单追加（词前缀或含 `*` 的通配）。放宽项，项目级忽略；各层累加。 */
+    autoSafeCommands?: string[];
 }
 export interface CompactionConfig {
     enabled?: boolean;
@@ -59,13 +81,22 @@ export interface RetryConfig {
     baseDelayMs?: number;
     maxDelayMs?: number;
 }
-/** 工具预设（设计 §5.6）：模型直接看到的工具集合。 */
-export type ToolsPreset = "default" | "minimal" | "codemode" | "coordinator";
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 工具预设（设计 §5.6）：模型直接看到的工具集合（规范名）。 */
+export type ToolsPreset = "default" | "minimal" | "codemode-only" | "coordinator";
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export declare const TOOLS_PRESET_ALIASES: Readonly<Record<string, ToolsPreset>>;
+/** 配置文件、命令行、RPC、SDK 接受的写法：规范名或别名。 */
+export type ToolsPresetInput = ToolsPreset | "codemode";
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export declare const TOOLS_PRESETS_STRICT_FIRST: readonly ToolsPreset[];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export declare const TOOLS_PRESET_INPUTS: readonly ToolsPresetInput[];
+/** 规范名；未知名字原样返回（校验由 schema 负责）。 */
+export declare function canonicalPreset(name: ToolsPresetInput): ToolsPreset;
+export declare function canonicalPreset(name: string | undefined): ToolsPreset | undefined;
 export interface ToolsConfig {
-    /** 缺省 `default`；命令行 `--tools-preset`。 */
-    preset?: ToolsPreset;
+    /** 缺省 `default`；命令行 `--tools-preset`；`codemode` 是 `codemode-only` 的别名。 */
+    preset?: ToolsPresetInput;
     /**
      * 在预设上微调（设计 §5.6）：`+name` 加、`-name` 去；不带前缀的名字整组替换预设的内置工具。
      * 只认用户级 / profile（项目级忽略并 warning）。
@@ -90,12 +121,19 @@ export interface HooksSettings {
     timeoutMs?: number;
 }
 export interface UiConfig {
-    theme?: "dark" | "light";
+    /** auto 按 `COLORFGBG` / `TERM_PROGRAM` 猜（不发查询序列），猜不出用 dark。 */
+    theme?: "dark" | "light" | "auto";
     markdown?: boolean;
     showThinking?: "full" | "collapsed" | "hidden";
     /** 第一期只有 regular（§12.10）。 */
     tuiMode?: "regular";
     quietStartup?: "normal" | "header" | "silent";
+    /** ASCII 字形（`AMA_ASCII=1` 等价）；缺省按区域设置 / TERM 自动检测。 */
+    ascii?: boolean;
+    /** 消息区块间不空行、启动头无框，缺省 false。 */
+    compact?: boolean;
+    /** false：运行中 spinner 固定为 `·`，缺省 true。 */
+    animation?: boolean;
 }
 export interface SkillsConfig {
     dirs?: string[];
@@ -118,6 +156,13 @@ export interface CacheConfig {
     warmSubagents?: boolean;
 }
 export declare const DEFAULT_CACHE_CONFIG: Readonly<Required<CacheConfig>>;
+/**
+ * 模型请求（W4-C）。只认用户级 / profile；环境变量 `AMA_IDLE_TIMEOUT_MS` 覆盖 `idleTimeoutMs`。
+ */
+export interface RequestConfig {
+    /** 等响应头与流中两块数据之间的最长间隔（毫秒），收到任何字节即重新计时；缺省 300 000，0 关闭。 */
+    idleTimeoutMs?: number;
+}
 /** config.json（用户级 / 项目级 / profile.config 同形状；项目级只接受受限字段，§10.2）。 */
 export interface AmaConfig {
     version: typeof CONFIG_FILE_VERSION;
@@ -134,6 +179,7 @@ export interface AmaConfig {
     ui?: UiConfig;
     skills?: SkillsConfig;
     cache?: CacheConfig;
+    request?: RequestConfig;
 }
 /** auth.json（0600）。 */
 export interface AuthFile {

package/dist/config/types.js

@@ -9,13 +9,31 @@
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
  */
 export const CONFIG_FILE_VERSION = 1;
-/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
+/** 渠道名：不含 `/` 与 `@`（`provider/model@channel`）。 */
+export const CHANNEL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
+/** 预设别名 → 规范名：`codemode` 是 0.3.0 的旧名（行为同 `codemode-only`）。 */
+export const TOOLS_PRESET_ALIASES = Object.freeze({
+    codemode: "codemode-only",
+});
+/** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode-only 最宽）。 */
 export const TOOLS_PRESETS_STRICT_FIRST = [
     "coordinator",
     "minimal",
     "default",
+    "codemode-only",
+];
+/** 全部可接受的写法（规范名在前，别名在后；schema 与命令行校验用）。 */
+export const TOOLS_PRESET_INPUTS = [
+    ...TOOLS_PRESETS_STRICT_FIRST,
     "codemode",
 ];
+export function canonicalPreset(name) {
+    if (name === undefined)
+        return undefined;
+    return Object.hasOwn(TOOLS_PRESET_ALIASES, name)
+        ? TOOLS_PRESET_ALIASES[name]
+        : name;
+}
 export const CODEMODE_MODES = ["off", "on", "only"];
 export const CACHE_RETENTIONS = ["none", "short", "long"];
 export const DEFAULT_CACHE_CONFIG = Object.freeze({

package/dist/modes/commands-core.js

@@ -13,7 +13,7 @@ import { AgentSessionImpl } from "../agent/session.js";
 import { WARMING_MODES } from "../ai/cache/types.js";
 import { THINKING_LEVELS } from "../ai/thinking.js";
 import { AmaError } from "../errors.js";
-import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { PERMISSION_MODE_ORDER, parsePermissionMode, permissionModeLabel, } from "../permissions/modes.js";
 import { describeCache, describeFingerprint, describeSession } from "./session-report.js";
 export { describeSession } from "./session-report.js";
 export const BUILTIN_COMMANDS = [
@@ -133,11 +133,12 @@ export async function runSlashCommand(line, ctx) {
         case "permission": {
             if (args === "")
                 return { kind: "pick", what: "permission" };
-            if (!PERMISSION_MODES_STRICT_FIRST.includes(args)) {
-                throw new AmaError("invalid_arguments", `权限模式应为 ${PERMISSION_MODES_STRICT_FIRST.join(" | ")}`);
+            const mode = parsePermissionMode(args);
+            if (mode === undefined) {
+                throw new AmaError("invalid_arguments", `权限模式应为 ${PERMISSION_MODE_ORDER.join(" | ")}（也可写显示名，如 "Accept edits"）`);
             }
-            session.setPermissionMode(args);
-            return { kind: "handled", message: `权限模式：${args}` };
+            session.setPermissionMode(mode);
+            return { kind: "handled", message: `权限模式：${permissionModeLabel(mode)}` };
         }
         case "tools": {
             if (args !== "")

package/dist/modes/image-input.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 用户侧的图片输入（docs/providers.md「图像输入」）：`ama -p --image`、交互 / 行式界面里的 `@图片路径`
+ * 与粘贴 / 拖入的图片文件路径。
+ *
+ * - `--image` 与 `@路径` 是显式附件：文件不存在、不是图片、超过上限，或当前模型 `input` 不含 image
+ *   → 报错，不发请求；
+ * - 不带 `@` 的词只在「以图片扩展名结尾且文件存在」时才算附件，当前模型不收图片时静默忽略（用户可能
+ *   只是在文字里提到一个文件）；
+ * - 与 read 工具共用 image-file.ts 的 MIME 检测与 5 MB 上限。提示文字原样保留。
+ */
+import type { AgentSession } from "../agent/types.js";
+import type { ImageBlock, Model, ProviderRegistryApi } from "../ai/types.js";
+export interface ImageRef {
+    path: string;
+    /** `@路径` 或 `--image`：显式附件。 */
+    explicit: boolean;
+}
+/** 从提示里找图片引用：`@路径`（可加引号）与以图片扩展名结尾、文件存在的词（拖入的路径常带 `\ `）。 */
+export declare function findImageRefs(text: string, cwd: string): ImageRef[];
+/** 当前会话的模型（查不到返回 undefined）。 */
+export declare function sessionModel(providers: ProviderRegistryApi, session: AgentSession): Model | undefined;
+/**
+ * 读出附件：显式附件遇到模型不收图片 → AmaError（提示换模型）；隐式附件此时忽略。
+ */
+export declare function loadPromptImages(refs: readonly ImageRef[], model: Model | undefined): Promise<ImageBlock[]>;
+/** 提示 + 额外的显式图片路径（`--image`）→ 附件。 */
+export declare function promptImages(text: string, extra: readonly string[], cwd: string, model: Model | undefined): Promise<ImageBlock[]>;

package/dist/modes/image-input.js

@@ -0,0 +1,78 @@
+/**
+ * 用户侧的图片输入（docs/providers.md「图像输入」）：`ama -p --image`、交互 / 行式界面里的 `@图片路径`
+ * 与粘贴 / 拖入的图片文件路径。
+ *
+ * - `--image` 与 `@路径` 是显式附件：文件不存在、不是图片、超过上限，或当前模型 `input` 不含 image
+ *   → 报错，不发请求；
+ * - 不带 `@` 的词只在「以图片扩展名结尾且文件存在」时才算附件，当前模型不收图片时静默忽略（用户可能
+ *   只是在文字里提到一个文件）；
+ * - 与 read 工具共用 image-file.ts 的 MIME 检测与 5 MB 上限。提示文字原样保留。
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { formatModelRef } from "../ai/providers/channels.js";
+import { AmaError } from "../errors.js";
+import { imageMimeFromPath, loadImageFile } from "../tools/image-file.js";
+const TOKEN = /@?"([^"]+)"|@?'([^']+)'|((?:\\ |\S)+)/g;
+function expand(path, cwd) {
+    const home = path === "~" || path.startsWith("~/") ? homedir() + path.slice(1) : path;
+    return resolve(cwd, home);
+}
+/** 从提示里找图片引用：`@路径`（可加引号）与以图片扩展名结尾、文件存在的词（拖入的路径常带 `\ `）。 */
+export function findImageRefs(text, cwd) {
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(TOKEN)) {
+        let token = m[1] ?? m[2] ?? m[3] ?? "";
+        const explicit = m[0].startsWith("@");
+        if (m[3] !== undefined && explicit)
+            token = token.slice(1);
+        token = token.replace(/\\ /g, " ").replace(/[,，。;；)）]+$/, "");
+        if (token === "" || imageMimeFromPath(token) === undefined)
+            continue;
+        const path = expand(token, cwd);
+        if (!explicit && !existsSync(path))
+            continue;
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        out.push({ path, explicit });
+    }
+    return out;
+}
+/** 当前会话的模型（查不到返回 undefined）。 */
+export function sessionModel(providers, session) {
+    const ref = session.state.model;
+    if (ref === undefined)
+        return undefined;
+    const found = providers.findModel(formatModelRef(ref));
+    return found.ok ? found.model : undefined;
+}
+/**
+ * 读出附件：显式附件遇到模型不收图片 → AmaError（提示换模型）；隐式附件此时忽略。
+ */
+export async function loadPromptImages(refs, model) {
+    const accepts = model === undefined || model.input.includes("image");
+    const wanted = refs.filter((ref) => ref.explicit || accepts);
+    if (wanted.length === 0)
+        return [];
+    if (!accepts) {
+        const name = model === undefined ? "当前模型" : `${model.provider}/${model.id}`;
+        throw new AmaError("invalid_arguments", `${name} 不接受图片输入（模型 input 没有 image）；换一个支持图像的模型再试` +
+            `（ama models list 里标「图片」的，或在配置里给该模型写 "input": ["text", "image"]）`);
+    }
+    const blocks = [];
+    for (const ref of wanted)
+        blocks.push((await loadImageFile(ref.path)).block);
+    return blocks;
+}
+/** 提示 + 额外的显式图片路径（`--image`）→ 附件。 */
+export async function promptImages(text, extra, cwd, model) {
+    const refs = [
+        ...extra.map((path) => ({ path: expand(path, cwd), explicit: true })),
+        ...findImageRefs(text, cwd),
+    ];
+    const unique = refs.filter((ref, i) => refs.findIndex((r) => r.path === ref.path) === i);
+    return loadPromptImages(unique, model);
+}

package/dist/modes/interactive/approval-dialog.d.ts

@@ -7,7 +7,11 @@
  * - 执行前预览（W3-B9a-2，`request.preview`）：输入摘要之后列出会碰到的路径与规模，danger 红、
  *   warn 黄、info 暗色；`other` 类预览与输入摘要重复，不显示；
  * - 原因：mode（当前权限模式需要确认）/ dangerous / hook + Hook 给的文本；
- * - 按键：`y` 允许、`n` / Esc / Ctrl+C 拒绝、`a` 本会话允许同类；
+ * - 选项（终端界面视觉设计 v1 §3.11）：编号列表 `1. 允许  y` / `2. 本会话允许同类  a` / `3. 拒绝  n Esc`，
+ *   选中行 `›` + selection 底色；缺省选中：危险命令 → 拒绝，其余 → 允许。按键 `y / a / n / Esc / Ctrl+C /
+ *   1 2 3 / ↑↓ Enter / v` 都有效；
+ * - 标题按原因：需要确认 / 危险命令 / Hook 要求确认（子 Agent 发起前缀 `[task] `）；边框颜色随预览严重度
+ *   （danger error、warn warning）；宽 < 56 时紧凑：工具名单独一行、去掉空行、按键提示缩短；
  * - 超时与中断：broker 链在超时（缺省 10 分钟）或运行被中断时 abort `signal`，对话框关闭并返回
  *   undefined（链按 deny 处理），消息区留一行说明。
  *
@@ -29,13 +33,24 @@ export interface ApprovalHost {
     /** 结果说明（消息区一行）。 */
     report?(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): void;
 }
-/** 对话框正文（不含按键行）。 */
-export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: {
+export interface DescribeOptions {
     cwd?: string;
     permissionMode?: string;
     expanded?: boolean;
-}): string[];
-export declare const APPROVAL_KEYS_HINT = "[y] \u5141\u8BB8  [n] \u62D2\u7EDD  [a] \u672C\u4F1A\u8BDD\u5141\u8BB8\u540C\u7C7B  [v] \u5B8C\u6574\u8F93\u5165";
+    /** 紧凑（窄屏）：首行只放工具名（原因已在标题上）。 */
+    compact?: boolean;
+}
+/** 原因 → 标题文字（子 Agent 发起加 `[task] `）。 */
+export declare function approvalTitle(request: ApprovalRequest): string;
+/** 对话框正文（不含选项与按键行）。 */
+export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: DescribeOptions): string[];
+interface ApprovalOption {
+    decision: ApprovalDecision;
+    label: string;
+    /** 右侧按键提示。 */
+    keys: string;
+}
+export declare const APPROVAL_OPTIONS: readonly ApprovalOption[];
 /** UI broker：每个请求开一个底部覆盖层，等用户按键或 signal abort。 */
 export declare class ApprovalDialogBroker implements ApprovalBroker {
     private readonly host;
@@ -46,3 +61,4 @@ export declare class ApprovalDialogBroker implements ApprovalBroker {
 }
 /** 结果的一行说明（消息区）。 */
 export declare function approvalOutcomeText(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): string;
+export {};