@armadra/agent 0.2.1 → 0.3.0

package/dist/config/json-schema.js

@@ -0,0 +1,182 @@
+/**
+ * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
+ * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
+ * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
+ * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
+ */
+import { WARMING_MODES } from "../ai/cache/types.js";
+import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
+import { HOOK_TIMEOUT_MAX_MS, THINKING_LEVELS } from "./schema.js";
+import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CODEMODE_MODES, TOOLS_PRESETS_STRICT_FIRST, } from "./types.js";
+export const CONFIG_SCHEMA_FILE = "config.schema.json";
+export const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
+const KNOWN_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+function object(properties, extra = {}) {
+    return { type: "object", properties, additionalProperties: false, ...extra };
+}
+const str = (description) => ({
+    type: "string",
+    ...(description ? { description } : {}),
+});
+const bool = (description) => ({
+    type: "boolean",
+    ...(description ? { description } : {}),
+});
+const num = (minimum, maximum, description) => ({
+    type: "number",
+    ...(minimum !== undefined ? { minimum } : {}),
+    ...(maximum !== undefined ? { maximum } : {}),
+    ...(description ? { description } : {}),
+});
+const strings = { type: "array", items: { type: "string" } };
+const stringRecord = { type: "object", additionalProperties: { type: "string" } };
+const oneOf = (values, description) => ({
+    type: "string",
+    enum: [...values],
+    ...(description ? { description } : {}),
+});
+/** api 只查是字符串（与 validateConfig 一致），enum 给编辑器补全。 */
+const api = {
+    type: "string",
+    description: "协议",
+    examples: KNOWN_APIS,
+    anyOf: [{ enum: KNOWN_APIS }, { type: "string" }],
+};
+const compat = {
+    type: "object",
+    description: "协议兼容开关（docs/providers.md「compat」）",
+    properties: {
+        sendPromptCacheKey: bool(),
+        sendSessionAffinityHeaders: bool(),
+        supportsLongCacheRetention: bool(),
+        supportsExplicitPromptCacheMode: bool(),
+        cacheReporting: oneOf(["auto", "silent", "reported"]),
+    },
+};
+function model(description) {
+    return {
+        type: "object",
+        description,
+        required: ["id"],
+        properties: {
+            id: str("模型 id（发给上游的名字）"),
+            name: str(),
+            api,
+            baseUrl: str("覆盖渠道 / 供应商的地址"),
+            contextWindow: num(1, undefined, "上下文 token；缺省从 models.dev 补，匹配不到不猜"),
+            maxTokens: num(1, undefined, "单次输出上限；缺省 min(models.dev, 64k) 或 8192"),
+            reasoning: bool(),
+            input: {
+                type: "array",
+                items: { enum: ["text", "image"] },
+                description: '["text"] 或 ["text", "image"]（收图片）',
+            },
+            channels: { ...strings, description: "挂载的渠道，第一个是首选" },
+            modelsDev: {
+                description: 'models.dev 条目 "provider/model"；false 关闭补全',
+                anyOf: [{ type: "string", pattern: "^[^/]+/.+$" }, { const: false }],
+            },
+            headers: stringRecord,
+            compat,
+            promptCache: object({ short: num(), long: num(), minTokens: num() }),
+            cost: { type: "object", description: "$/M token" },
+            thinkingLevelMap: { type: "object" },
+            samplingParams: { type: "object" },
+        },
+    };
+}
+const channel = object({
+    api,
+    baseUrl: str("接口地址"),
+    apiKey: str("$ENV / ${ENV} / !command / 字面量；缺省用供应商的 key"),
+    authHeader: { type: "object" },
+    headers: stringRecord,
+    compat,
+}, { required: ["api", "baseUrl"] });
+const provider = object({
+    name: str(),
+    api,
+    baseUrl: str(),
+    apiKey: str("$ENV / ${ENV} / !command / 字面量"),
+    envKeys: strings,
+    authHeader: { type: "object" },
+    headers: stringRecord,
+    compat,
+    requiresApiKey: bool(),
+    channels: {
+        type: "object",
+        description: "渠道：一个供应商下的多种接口",
+        minProperties: 1,
+        propertyNames: { pattern: CHANNEL_NAME_PATTERN.source },
+        additionalProperties: channel,
+    },
+    defaultChannel: str("首选渠道；缺省 channels 的第一个"),
+    models: { type: "array", items: model("自定义模型（同 id 整条替换）") },
+    modelOverrides: { type: "array", items: model("只改已有模型的元数据") },
+});
+/** 生成 config.json 的 JSON Schema。 */
+export function buildConfigJsonSchema() {
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        $id: CONFIG_SCHEMA_ID,
+        title: "ama config.json",
+        ...object({
+            $schema: str(),
+            version: { const: 1 },
+            defaultModel: str("provider/model 或 provider/model@channel"),
+            thinkingLevel: oneOf(THINKING_LEVELS),
+            providers: { type: "object", additionalProperties: provider },
+            permission: object({
+                mode: oneOf(PERMISSION_MODES_STRICT_FIRST),
+                allow: strings,
+                deny: strings,
+                builtinDeny: { anyOf: [{ type: "boolean" }, strings] },
+            }),
+            compaction: object({ enabled: bool(), reserveTokens: num(0), keepRecentTokens: num(0) }),
+            retry: object({
+                enabled: bool(),
+                maxRetries: num(0, 100),
+                baseDelayMs: num(0),
+                maxDelayMs: num(0),
+            }),
+            tools: object({
+                preset: oneOf(TOOLS_PRESETS_STRICT_FIRST),
+                default: strings,
+                maxToolResultChars: num(1),
+                bashTimeoutMs: num(1),
+                disabled: strings,
+            }),
+            codemode: object({
+                mode: oneOf(CODEMODE_MODES),
+                inlineBudget: num(0),
+                requireStrict: bool(),
+            }),
+            hooks: object({ timeoutMs: num(1, HOOK_TIMEOUT_MAX_MS) }),
+            ui: object({
+                theme: oneOf(["dark", "light"]),
+                markdown: bool(),
+                showThinking: oneOf(["full", "collapsed", "hidden"]),
+                tuiMode: oneOf(["regular"]),
+                quietStartup: oneOf(["normal", "header", "silent"]),
+            }),
+            skills: object({ dirs: strings }),
+            cache: object({
+                warming: oneOf(WARMING_MODES),
+                retention: oneOf(CACHE_RETENTIONS),
+                minSavingsUsd: num(0),
+                missNotices: bool(),
+                warmSubagents: bool(),
+            }),
+        }),
+        required: ["version"],
+    };
+}
+/** 写进文件的文本（2 空格缩进 + 换行结尾）。 */
+export function configSchemaText() {
+    return `${JSON.stringify(buildConfigJsonSchema(), null, 2)}\n`;
+}

package/dist/config/schema.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AmaConfig, AuthFile, ProfileFile, TrustFile } from "./types.js";
 import type { HookConfig } from "../hooks/types.js";
-export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, } from "./types.js";
+export type { AmaConfig, AuthFile, ProfileFile, TrustFile, TrustEntry, ProviderConfig, PermissionConfig, CompactionConfig, RetryConfig, ToolsConfig, ToolsPreset, CodemodeConfig, CodemodeMode, HooksSettings, UiConfig, SkillsConfig, CacheConfig, ModelConfig, ModelOverride, ChannelConfig, } from "./types.js";
 export { CONFIG_FILE_VERSION } from "./types.js";
 export type { HookConfig } from "../hooks/types.js";
 export interface Diagnostic {

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_PRESETS_STRICT_FIRST, } 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;
@@ -128,9 +128,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 +141,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 +160,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 +192,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 +246,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];

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[];
 }

package/dist/config/types.js

@@ -9,6 +9,8 @@
  * 允许模型级 `api`（§2.3，同一中转的模型走不同协议），由 W3-B12 在注册表里生效。
  */
 export const CONFIG_FILE_VERSION = 1;
+/** 渠道名：不含 `/` 与 `@`（`provider/model@channel`）。 */
+export const CHANNEL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
 /** 从严到宽：项目级只能把预设改成不比当前更宽的那个（coordinator 最严，codemode 最宽）。 */
 export const TOOLS_PRESETS_STRICT_FIRST = [
     "coordinator",

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/commands.js

@@ -8,6 +8,7 @@
  *   `/permissions`（当前模式、判定顺序与已加载规则）；`/help` 追加这两条与按键说明。
  * - 不是命令（含模板与 `/skill:`）返回 false，调用方把整行当提示发出。
  */
+import { formatModelRef } from "../../ai/providers/channels.js";
 import { AgentSessionImpl } from "../../agent/session.js";
 import { listSessions } from "../../cli/compose-store.js";
 import { BUILTIN_COMMANDS, parseSlash, runSlashCommand, } from "../commands-core.js";
@@ -139,9 +140,7 @@ async function handlePick(what, ui) {
         }
         case "thinking": {
             const model = session.state.model;
-            const found = model === undefined
-                ? undefined
-                : ui.runtime.providers.findModel(`${model.provider}/${model.id}`);
+            const found = model === undefined ? undefined : ui.runtime.providers.findModel(formatModelRef(model));
             const reasoning = found?.ok === true ? found.model.reasoning : true;
             const picked = await ui.pick({
                 title: "思考级别",

package/dist/modes/interactive/interactive-mode.js

@@ -13,6 +13,7 @@
  * - 键位：Enter 发送（运行中 = steer），其余应用级键位见 `key-dispatch.ts`。
  * - 启动画面按 `ui.quietStartup`：normal 标题 + 模型 / 信任 / 资源清单，header 只有标题，silent 不输出。
  */
+import { promptImages, sessionModel } from "../image-input.js";
 import { join } from "node:path";
 import { AgentSessionImpl } from "../../agent/session.js";
 import { currentSession, switchSession } from "../../cli/compose-session.js";
@@ -324,7 +325,10 @@ export function runInteractiveMode(runtime, context, options = {}) {
         const target = session;
         void target
             .waitForIdle()
-            .then(() => target.prompt(text))
+            .then(async () => {
+            const images = await promptImages(text, [], target.state.cwd, sessionModel(runtime.providers, target));
+            return target.prompt(text, images.length > 0 ? { images } : {});
+        })
             .catch((error) => {
             if (isAmaError(error) && error.code === "busy") {
                 void target.followUp(text).catch(() => undefined);

package/dist/modes/interactive/line/line-mode.js

@@ -7,6 +7,7 @@
  * - 否则（管道）：逐行读 stdin，每行依次执行（等上一条运行结束）；没有审批 UI，ask → deny。
  * - 斜杠命令走 commands-core（与 B7 同一语义），`pick` 退化为列出候选。
  */
+import { promptImages, sessionModel } from "../../image-input.js";
 import { currentSession, switchSession } from "../../../cli/compose-session.js";
 import { ExitCode } from "../../../cli/exit-codes.js";
 import { previewDisplayLines } from "../../../permissions/preview.js";
@@ -72,7 +73,8 @@ export async function runLineMode(runtime, context, options = {}) {
         return undefined;
     };
     const prompt = async (target, text) => {
-        await target.prompt(text);
+        const images = await promptImages(text, [], target.state.cwd, sessionModel(runtime.providers, target));
+        await target.prompt(text, images.length > 0 ? { images } : {});
         printer.endLine();
     };
     if (!raw)

package/dist/modes/interactive/startup-ui.d.ts

@@ -7,7 +7,7 @@
  *
  * `modelItems` / `sessionItems` 同时供交互模式里的选择器（pickers.ts）使用。
  */
-import type { ProviderRegistryApi } from "../../ai/types.js";
+import type { Model, ProviderRegistryApi } from "../../ai/types.js";
 import type { InteractiveUi } from "../../cli/deps.js";
 import type { SessionListItem } from "../../session/types.js";
 import { type Keybindings, type SelectItem, type Terminal, type Theme } from "../../tui.js";
@@ -19,7 +19,12 @@ export interface StartupUiOptions {
     /** 会话列表的相对时间基准（测试注入）。 */
     now?: () => number;
 }
-/** 模型按供应商分组；有 key（或本地）的供应商排前，组标题标 key 状态。 */
+/** 选择器里模型的说明：名称（与 id 不同时）、上下文、`img`（收图片）。 */
+export declare function modelDescription(model: Model): string | undefined;
+/**
+ * 模型按「供应商 · 渠道」分组；有 key（或本地）的供应商排前，组标题标 key 状态。多渠道供应商的模型在
+ * 每个挂载的渠道下各出现一次，非首选渠道的值带 `@渠道`。
+ */
 export declare function modelItems(providers: ProviderRegistryApi): Promise<SelectItem[]>;
 /** `刚刚 / 5 分钟前 / 3 小时前 / 2 天前 / 2026-09-01`。 */
 export declare function relativeTime(iso: string, now: number): string;

package/dist/modes/interactive/startup-ui.js

@@ -102,7 +102,24 @@ function askText(r, prompt) {
 // ---------------------------------------------------------------------------
 // 列表项（选择器共用）
 // ---------------------------------------------------------------------------
-/** 模型按供应商分组；有 key（或本地）的供应商排前，组标题标 key 状态。 */
+/** 选择器里模型的说明：名称（与 id 不同时）、上下文、`img`（收图片）。 */
+export function modelDescription(model) {
+    const ctx = model.contextWindow;
+    const parts = [
+        model.name !== "" && model.name !== model.id ? model.name : undefined,
+        ctx === undefined
+            ? undefined
+            : ctx >= 1_000_000
+                ? `${Math.round(ctx / 100_000) / 10}M`
+                : `${Math.round(ctx / 1000)}k`,
+        model.input.includes("image") ? "img" : undefined,
+    ].filter((x) => x !== undefined);
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+/**
+ * 模型按「供应商 · 渠道」分组；有 key（或本地）的供应商排前，组标题标 key 状态。多渠道供应商的模型在
+ * 每个挂载的渠道下各出现一次，非首选渠道的值带 `@渠道`。
+ */
 export async function modelItems(providers) {
     const groups = [];
     for (const provider of providers.list()) {
@@ -117,16 +134,29 @@ export async function modelItems(providers) {
             ready = key.apiKey !== undefined;
             status = ready ? "key ✓" : "无 key";
         }
-        const group = `${provider.id} · ${status}`;
-        groups.push({
-            ready,
-            items: provider.models.map((model) => {
-                const item = { value: `${provider.id}/${model.id}`, label: model.id, group };
-                if (model.name !== "" && model.name !== model.id)
-                    item.description = model.name;
-                return item;
-            }),
-        });
+        const item = (model, group, channel) => {
+            const suffix = channel !== undefined && channel !== model.channel ? `@${channel}` : "";
+            const out = {
+                value: `${provider.id}/${model.id}${suffix}`,
+                label: `${model.id}${suffix}`,
+                group,
+            };
+            const description = modelDescription(model);
+            if (description !== undefined)
+                out.description = description;
+            return out;
+        };
+        if (provider.channels === undefined) {
+            const group = `${provider.id} · ${status}`;
+            groups.push({ ready, items: provider.models.map((model) => item(model, group)) });
+            continue;
+        }
+        for (const channel of provider.channels) {
+            const group = `${provider.id} · ${channel.name} · ${status}`;
+            const models = provider.models.filter((m) => m.channels?.includes(channel.name));
+            if (models.length > 0)
+                groups.push({ ready, items: models.map((model) => item(model, group, channel.name)) });
+        }
     }
     return [...groups.filter((g) => g.ready), ...groups.filter((g) => !g.ready)].flatMap((g) => g.items);
 }

package/dist/modes/print/print-mode.d.ts

@@ -2,6 +2,8 @@
  * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
  *
  * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - 图片：`--image`（可重复）与提示里的 `@图片路径` / 图片文件路径作为附件（modes/image-input.ts）；
+ *   显式附件遇到当前模型不收图片、文件不存在或超限 → 用法错误 2，不发请求。
  * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
  *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
  *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /