@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/protocol/errors.js

@@ -0,0 +1,281 @@
+/**
+ * 协议核心·错误映射（契约：docs/spec/protocol.md §3 十一行表）。
+ *
+ * 错误对象一律是 AI SDK `APICallError` 形态：透传/合成 statusCode、标注
+ * isRetryable（重试由 OpenCode 决定，provider 不自行重试）、message 含
+ * model id 与上游 message。宿主对 provider 错误的分类靠
+ * `APICallError.isInstance`——AI SDK 用全局 Symbol 标记跨副本识别
+ * （`Symbol.for("vercel.ai.error.AI_APICallError")`，provider 3.0.8 实测），
+ * 本模块零运行时依赖，只按同款机制在实例上打标记，宿主即可正确分类
+ * （测试用 devDep @ai-sdk/provider 的 isInstance 断言验证）。
+ *
+ * 错误信封统一按 `{"error":{"message":"..."}}` 解析，兜底 `parsed.message`
+ * （brent 实证），两处都拿不到时回退 HTTP 状态文本。
+ */
+import { IDLE_WATCHDOG_TIMEOUT_MS } from "./watchdog.js";
+// AI SDK 错误标记：AISDKError 基类与 APICallError 子类各一个全局 symbol。
+// 名称来自 @ai-sdk/provider 3.0.8 源码（src/errors/ai-sdk-error.ts 与
+// api-call-error.ts），宿主与 provider 副本间靠 Symbol.for 全局注册表互认。
+const AISDK_ERROR_MARKER = Symbol.for("vercel.ai.error");
+const API_CALL_ERROR_MARKER = Symbol.for("vercel.ai.error.AI_APICallError");
+/** 十一行表错误信封载体：AI SDK APICallError 形态（含跨包识别标记） */
+export class CommandCodeApiCallError extends Error {
+    url;
+    requestBodyValues;
+    statusCode;
+    responseHeaders;
+    responseBody;
+    isRetryable;
+    retryAfterSeconds;
+    /** 合成错误的语义码（如零输出/看门狗超时），透传错误时为 undefined */
+    code;
+    constructor(fields) {
+        super(fields.message, { cause: fields.cause });
+        // 与 AI SDK 同名：宿主按 name 兜底分类时不错认（真正识别走 Symbol 标记）
+        this.name = "AI_APICallError";
+        this.url = fields.url;
+        this.requestBodyValues = fields.requestBodyValues;
+        this.statusCode = fields.statusCode;
+        this.responseHeaders = fields.responseHeaders;
+        this.responseBody = fields.responseBody;
+        this.isRetryable = fields.isRetryable;
+        this.retryAfterSeconds = fields.retryAfterSeconds;
+        this.code = fields.code;
+        this[AISDK_ERROR_MARKER] = true;
+        this[API_CALL_ERROR_MARKER] = true;
+    }
+}
+/** 十一行表行 7：零输出合成 429（retry-after 10s），防白跑一回合 */
+export function zeroOutputError(modelId, url, requestBodyValues) {
+    return new CommandCodeApiCallError({
+        code: "ZERO_OUTPUT",
+        message: `[${modelId}] 上游回合零输出（模型未生成任何 token），已按可重试处理`,
+        url,
+        requestBodyValues,
+        statusCode: 429,
+        responseHeaders: { "retry-after": "10" },
+        isRetryable: true,
+        retryAfterSeconds: 10,
+    });
+}
+/** 看门狗到点（§4）：上游 300s 无事件 = 失联，可重试（retry-after 5s） */
+export function watchdogTimeoutError(modelId, url, requestBodyValues) {
+    return new CommandCodeApiCallError({
+        code: "UPSTREAM_IDLE_TIMEOUT",
+        message: `[${modelId}] 上游 ${IDLE_WATCHDOG_TIMEOUT_MS / 1000} 秒无事件（疑似失联），连接已断开，可重试`,
+        url,
+        requestBodyValues,
+        statusCode: 429,
+        responseHeaders: { "retry-after": "5" },
+        isRetryable: true,
+        retryAfterSeconds: 5,
+    });
+}
+/** 行 11：响应前网络错误（DNS / 连接拒绝 / TLS），可重试 */
+export function networkError(modelId, url, requestBodyValues, cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new CommandCodeApiCallError({
+        message: `[${modelId}] 网络错误（无法连接上游：${reason}）`,
+        url,
+        requestBodyValues,
+        isRetryable: true,
+    });
+}
+/**
+ * 流内错误（无 HTTP 状态可透传）：可重试性由错误自身语义决定（行 8 截断可
+ * 重试；行 9 error 事件交 OpenCode 判断）。错误对象同为 APICallError 形态，
+ * 宿主 fromError 分类与 message/responseBody 匹配照常生效。
+ */
+export function streamError(modelId, message, opts) {
+    return new CommandCodeApiCallError({
+        message: `[${modelId}] ${message}`,
+        isRetryable: opts?.isRetryable ?? false,
+        code: opts?.code,
+    });
+}
+/**
+ * 流关闭但未收到 `finish-step`：无法确认回复完整（§3 行 8，jiesou 的
+ * STREAM_CLOSED）。APICallError 形态、可重试；`partialLine` 供排查。
+ * （ndjson.ts re-export 本类，流解析层错误统一由此构造。）
+ */
+export class StreamTruncatedError extends CommandCodeApiCallError {
+    /** 早期解析层消费者读取的兼容别名（与 isRetryable 同值） */
+    retriable = true;
+    /** EOF 时未完结的半行残片，并入错误供排查 */
+    partialLine;
+    constructor(partialLine, modelId) {
+        const tail = partialLine ? `，截断残片：${clip(partialLine, 200)}` : "";
+        super({
+            message: `[${modelId}] 上游流在 finish-step 之前关闭，回复可能不完整${tail}`,
+            isRetryable: true,
+            code: "STREAM_CLOSED",
+        });
+        this.partialLine = partialLine;
+    }
+}
+function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+/**
+ * 十一行表行 1–6 的 HTTP 层映射：把非 2xx 响应翻译成 APICallError 形态。
+ * 401/403 按 body 是否含 MODEL_NOT_IN_PLAN 区分「模型不在套餐」与认证错误；
+ * 402 按配额窗口假设合成 retry-after 60s；429 透传上游 retry-after（缺省不合成）；
+ * 400 命中上下文超限特征时明确报「上下文窗口超限」；5xx 透传状态码。
+ * 表外状态码：4xx 透传不可重试，5xx 可重试（真变更走规格修订，不在此发散）。
+ */
+export function apiCallErrorFromHttpResponse(input) {
+    const { modelId, url, requestBodyValues, status, responseHeaders, responseBody } = input;
+    const upstream = extractErrorMessage(responseBody);
+    const headersRecord = headerRecord(responseHeaders);
+    const retryAfter = responseHeaders.get("retry-after");
+    // 行 1：401/403 + MODEL_NOT_IN_PLAN → 「模型不在套餐」，区别于认证失败
+    if ((status === 401 || status === 403) && responseBody.includes("MODEL_NOT_IN_PLAN")) {
+        return new CommandCodeApiCallError({
+            code: "MODEL_NOT_IN_PLAN",
+            message: `[${modelId}] 模型不在当前套餐内（MODEL_NOT_IN_PLAN）：${upstream}`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: headersRecord,
+            responseBody,
+            isRetryable: false,
+        });
+    }
+    // 行 2：401/403 其他 → 认证错误，指向 /connect 重新登录
+    if (status === 401 || status === 403) {
+        return new CommandCodeApiCallError({
+            code: "AUTH_ERROR",
+            message: `[${modelId}] 认证失败（${status}）：key 无效或已过期，请重新运行 /connect 登录。上游：${upstream}`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: headersRecord,
+            responseBody,
+            isRetryable: false,
+        });
+    }
+    // 行 3：402 → 配额窗口恢复假设，退避拉长（默认 60s；HTTP-date 格式的
+    // retry-after 无法转秒数，按缺省 60s 处理）
+    if (status === 402) {
+        const parsed = retryAfter !== null ? Number(retryAfter) : NaN;
+        const upstreamSeconds = Number.isFinite(parsed) ? parsed : 60;
+        return new CommandCodeApiCallError({
+            code: "PAYMENT_REQUIRED",
+            message: `[${modelId}] 402 配额或计费问题（上游：${upstream}），按窗口恢复假设处理`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: { ...headersRecord, "retry-after": String(upstreamSeconds) },
+            responseBody,
+            isRetryable: true,
+            retryAfterSeconds: upstreamSeconds,
+        });
+    }
+    // 行 4：429 → 限流，透传上游 retry-after；缺省用默认退避（不合成）
+    if (status === 429) {
+        const parsed = retryAfter !== null ? Number(retryAfter) : undefined;
+        return new CommandCodeApiCallError({
+            code: "RATE_LIMITED",
+            message: `[${modelId}] 429 限流（上游：${upstream}）`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: headersRecord,
+            responseBody,
+            isRetryable: true,
+            retryAfterSeconds: Number.isFinite(parsed) ? parsed : undefined,
+        });
+    }
+    // 行 5：400 + 上下文超限特征 → 明确报「上下文窗口超限」
+    if (status === 400 && isContextOverflowText(responseBody)) {
+        return new CommandCodeApiCallError({
+            code: "CONTEXT_WINDOW_EXCEEDED",
+            message: `[${modelId}] 400 上下文窗口超限（请求超出模型上下文容量）：${upstream}`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: headersRecord,
+            responseBody,
+            isRetryable: false,
+        });
+    }
+    // 行 6：5xx 透传状态码，可重试
+    if (status >= 500) {
+        return new CommandCodeApiCallError({
+            message: `[${modelId}] 上游 ${status}（${upstream}）`,
+            url,
+            requestBodyValues,
+            statusCode: status,
+            responseHeaders: headersRecord,
+            responseBody,
+            isRetryable: true,
+        });
+    }
+    // 表外 4xx：透传、不可重试（规格外情形，行为保守）
+    return new CommandCodeApiCallError({
+        message: `[${modelId}] 上游 ${status}（${upstream}）`,
+        url,
+        requestBodyValues,
+        statusCode: status,
+        responseHeaders: headersRecord,
+        responseBody,
+        isRetryable: false,
+    });
+}
+/** 错误信封解析：`{"error":{"message":...}}` 优先，兜底 `parsed.message`，再兜底截断原文 */
+export function extractErrorMessage(responseBody) {
+    try {
+        const parsed = JSON.parse(responseBody);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            const record = parsed;
+            const error = record["error"];
+            if (typeof error === "object" && error !== null && !Array.isArray(error)) {
+                const message = error["message"];
+                if (typeof message === "string" && message.length > 0)
+                    return message;
+            }
+            const message = record["message"];
+            if (typeof message === "string" && message.length > 0)
+                return message;
+        }
+    }
+    catch {
+        // 非 JSON body 走兜底
+    }
+    const trimmed = responseBody.trim();
+    return trimmed.length > 0 ? trimmed : "（上游未返回可读信息）";
+}
+/**
+ * 上下文超限特征（400 body 文本判定）：命中即行 5「上下文窗口超限」。
+ * 词表覆盖网关常见表达（context length / window / token limit / prompt 过长等），
+ * 从 jiesou/brent 的判据与宿主 opencode 的 isContextOverflow 词表归纳。
+ * 收敛到与「上下文容量」强相关的短语：宽泛的 413 类文案（request entity too
+ * large 等）不放进来——图片超限的 400 不该被误报成上下文超限（§5 提示用户
+ * 该缩图而非压缩上下文）。
+ */
+export function isContextOverflowText(bodyText) {
+    const patterns = [
+        /context length/i,
+        /context window/i,
+        /context[_ -]?limit/i,
+        /maximum context/i,
+        /token limit/i,
+        /too many tokens/i,
+        /prompt is too long/i,
+        /input is too long/i,
+        /reduce the length/i,
+        /context_length_exceeded/i,
+        /model_context_window_exceeded/i,
+        /maximum prompt length/i,
+        /max context/i,
+    ];
+    return patterns.some((pattern) => pattern.test(bodyText));
+}
+/** Headers → 小写键 Record（透传进错误对象的 responseHeaders，宿主按小写键读） */
+function headerRecord(headers) {
+    const record = {};
+    headers.forEach((value, key) => {
+        record[key.toLowerCase()] = value;
+    });
+    return record;
+}

package/dist/protocol/generate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 协议核心·执行层：一次 `/alpha/generate` 上游调用的完整驱动
+ * （契约：docs/spec/protocol.md §3–§4，testing.md §2 的执行内核）。
+ *
+ * 本模块把零件串成可独立测试的「一次调用」：
+ *   请求方向（调用方组装后传入）：body 信封（envelope.ts 构造，含图片预处理
+ *   后的 prompt）、headers（伪装模块组装）、fetch 接缝。
+ *   执行方向：300s 空闲看门狗 → `AbortSignal.any(看门狗, 调用方)` 统一控制
+ *   fetch（谁先响都生效）→ 非 2xx 读 body 走错误映射表 → 2xx 把响应体逐
+ *   chunk 喂 NDJSON 解析器并产出 stream part，事件到达即重置看门狗。
+ *
+ * 错误策略（§3）：provider 不自行重试、不吞错——HTTP 层错误直接 throw
+ * （APICallError 形态，宿主据此决策重试），流内错误（截断 / error 事件 /
+ * 零输出 / 看门狗到点）以 error part 浮现；客户端 abort 传播到上游 fetch，
+ * 不合成任何错误。
+ *
+ * 零输出合成（行 7）在回合收尾处判定：finish part 已归一 usage 后若
+ * outputTokens 为 0 且全程无 tool 活动 → 把正常收尾换成合成 429 error part
+ * （retry-after 10s，防白跑一回合）。doStream 与 doGenerate 聚合共用本执行
+ * 内核（#35 工厂的 doGenerate = 消费同一 generator），看门狗天然共享。
+ *
+ * 端点是产品常量；测试经注入的 fetch 接缝拦请求，不引入 base URL 类后门
+ * （testing.md §3）。
+ */
+import type { LanguageModelV3StreamPart, SharedV3Warning } from "@ai-sdk/provider";
+import type { CommandCodeEnvelope } from "./envelope.js";
+import type { FetchLike } from "./json.js";
+/** 上游端点（产品常量；与 CLI 信封协议绑定，见 protocol.md §1） */
+export declare const GENERATE_ENDPOINT = "https://api.commandcode.ai/alpha/generate";
+export { type FetchLike } from "./json.js";
+export interface GenerateStreamInput {
+    /** wire id——错误 message 与看门狗日志需要模型区分 */
+    modelId: string;
+    /** 端点 URL（默认 GENERATE_ENDPOINT） */
+    url?: string;
+    /** 调用 warnings（buildEnvelope 产出），随首个 stream-start part 上报 */
+    warnings?: SharedV3Warning[];
+    /** CLI 信封（伪装字段由伪装模块填好后传入，本模块零知识） */
+    body: CommandCodeEnvelope;
+    /** 请求头全集（伪装头 + Authorization 由调用方组装） */
+    headers: Record<string, string>;
+    /** 工厂 options.fetch 接缝（测试注 mock） */
+    fetchImpl: FetchLike;
+    /** 调用方取消（用户停止键） */
+    signal?: AbortSignal;
+}
+/**
+ * 发起一次上游流式调用，产出 AI SDK stream part。
+ * HTTP 层错误（非 2xx / 响应前网络错误 / 看门狗到点）在此函数 await 时 throw；
+ * 流内错误（截断、error 事件、零输出、读流中断）以 error part 浮现。
+ * 迭代正常结束前自动释放看门狗定时器。
+ */
+export declare function generateStream(input: GenerateStreamInput): AsyncGenerator<LanguageModelV3StreamPart>;

package/dist/protocol/generate.js

@@ -0,0 +1,173 @@
+/**
+ * 协议核心·执行层：一次 `/alpha/generate` 上游调用的完整驱动
+ * （契约：docs/spec/protocol.md §3–§4，testing.md §2 的执行内核）。
+ *
+ * 本模块把零件串成可独立测试的「一次调用」：
+ *   请求方向（调用方组装后传入）：body 信封（envelope.ts 构造，含图片预处理
+ *   后的 prompt）、headers（伪装模块组装）、fetch 接缝。
+ *   执行方向：300s 空闲看门狗 → `AbortSignal.any(看门狗, 调用方)` 统一控制
+ *   fetch（谁先响都生效）→ 非 2xx 读 body 走错误映射表 → 2xx 把响应体逐
+ *   chunk 喂 NDJSON 解析器并产出 stream part，事件到达即重置看门狗。
+ *
+ * 错误策略（§3）：provider 不自行重试、不吞错——HTTP 层错误直接 throw
+ * （APICallError 形态，宿主据此决策重试），流内错误（截断 / error 事件 /
+ * 零输出 / 看门狗到点）以 error part 浮现；客户端 abort 传播到上游 fetch，
+ * 不合成任何错误。
+ *
+ * 零输出合成（行 7）在回合收尾处判定：finish part 已归一 usage 后若
+ * outputTokens 为 0 且全程无 tool 活动 → 把正常收尾换成合成 429 error part
+ * （retry-after 10s，防白跑一回合）。doStream 与 doGenerate 聚合共用本执行
+ * 内核（#35 工厂的 doGenerate = 消费同一 generator），看门狗天然共享。
+ *
+ * 端点是产品常量；测试经注入的 fetch 接缝拦请求，不引入 base URL 类后门
+ * （testing.md §3）。
+ */
+import { createNdjsonEventStream } from "./ndjson.js";
+import { apiCallErrorFromHttpResponse, networkError, watchdogTimeoutError, zeroOutputError, } from "./errors.js";
+import { createIdleWatchdog, mergeCancellation } from "./watchdog.js";
+/** 上游端点（产品常量；与 CLI 信封协议绑定，见 protocol.md §1） */
+export const GENERATE_ENDPOINT = "https://api.commandcode.ai/alpha/generate";
+export {} from "./json.js";
+/**
+ * 发起一次上游流式调用，产出 AI SDK stream part。
+ * HTTP 层错误（非 2xx / 响应前网络错误 / 看门狗到点）在此函数 await 时 throw；
+ * 流内错误（截断、error 事件、零输出、读流中断）以 error part 浮现。
+ * 迭代正常结束前自动释放看门狗定时器。
+ */
+export async function* generateStream(input) {
+    const ctx = { modelId: input.modelId, url: input.url ?? GENERATE_ENDPOINT, body: input.body };
+    const watchdog = createIdleWatchdog();
+    const ndjson = createNdjsonEventStream({ modelId: ctx.modelId, warnings: input.warnings ?? [] });
+    try {
+        // 看门狗 + 调用方取消合并：谁先 abort 谁生效（§4 取消合并条款）
+        const combined = mergeCancellation(watchdog, input.signal);
+        let response;
+        try {
+            response = await input.fetchImpl(ctx.url, {
+                method: "POST",
+                headers: input.headers,
+                body: JSON.stringify(ctx.body),
+                signal: combined,
+            });
+        }
+        catch (error) {
+            throw streamFailureError(classifyFailure(watchdog, input.signal), error, ctx);
+        }
+        if (!response.ok) {
+            // 行 1–6：HTTP 层错误映射（读 body 后 throw；provider 不自行重试）
+            const responseBody = await readBodySafely(response);
+            throw apiCallErrorFromHttpResponse({
+                modelId: ctx.modelId,
+                url: ctx.url,
+                requestBodyValues: ctx.body,
+                status: response.status,
+                responseHeaders: response.headers,
+                responseBody,
+            });
+        }
+        if (response.body === null) {
+            // 响应无 body：按截断语义由流收尾报错（end() 产 error part）
+            for (const part of ndjson.head())
+                yield part;
+            for (const part of ndjson.end())
+                yield part;
+            return;
+        }
+        // 2xx：把响应体逐 chunk 喂 NDJSON 解析器
+        const reader = response.body.getReader();
+        for (const part of ndjson.head())
+            yield part;
+        // 行 7 判定所需的回合状态：全程是否出现过工具活动（tool-call / tool-input 增量）
+        let sawToolActivity = false;
+        while (true) {
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                // 读流中断：与启动期同分类——看门狗到点 / 调用方取消 / 网络中断
+                const failure = classifyFailure(watchdog, input.signal);
+                if (failure === "caller-abort")
+                    return; // 调用方取消：不合成错误，静默收尾
+                yield errorPart(streamFailureError(failure, error, ctx));
+                return;
+            }
+            if (result.done)
+                break;
+            watchdog.reset(); // 有新数据 = 上游还活着
+            const chunk = result.value;
+            if (chunk === undefined)
+                break;
+            for (const part of ndjson.push(chunk)) {
+                sawToolActivity ||= isToolActivity(part);
+                const emitted = replaceZeroOutputFinish(part, sawToolActivity, ctx);
+                if (emitted !== null) {
+                    yield emitted;
+                    if (emitted.type === "error")
+                        return;
+                    continue;
+                }
+                yield part;
+            }
+        }
+        // EOF：半行残片两结局由解析器收尾（截断 error part / 补发收据 finish part）
+        for (const part of ndjson.end()) {
+            sawToolActivity ||= isToolActivity(part);
+            const emitted = replaceZeroOutputFinish(part, sawToolActivity, ctx);
+            if (emitted !== null) {
+                yield emitted;
+                if (emitted.type === "error")
+                    return;
+                continue;
+            }
+            yield part;
+        }
+    }
+    finally {
+        watchdog.clear();
+    }
+}
+/**
+ * 行 7 零输出合成：正常收尾的 finish part 若 usage.outputTokens 为 0 且本回合
+ * 无工具活动 → 换成合成 429 error part（retry-after 10s），防白跑一回合。
+ * 不命中零输出条件时原样返回 null（调用方继续 yield 原 part）。
+ */
+function replaceZeroOutputFinish(part, sawToolActivity, ctx) {
+    if (part.type !== "finish" || sawToolActivity)
+        return null;
+    // outputTokens 显式为 0 才算零输出；缺失/未归一成功不合成（防误杀健康回合）
+    if (part.usage.outputTokens?.total !== 0)
+        return null;
+    return errorPart(zeroOutputError(ctx.modelId, ctx.url, ctx.body));
+}
+/** tool-call 或 tool-input-* 增量 = 回合有工具活动（行 7「无 tool-call」排除面） */
+function isToolActivity(part) {
+    return part.type === "tool-call" || part.type.startsWith("tool-input");
+}
+function errorPart(error) {
+    return { type: "error", error };
+}
+function classifyFailure(watchdog, signal) {
+    if (watchdog.fired)
+        return "watchdog";
+    if (signal?.aborted === true)
+        return "caller-abort";
+    return "network";
+}
+/** 按中断分类产出错误对象：看门狗 → 超时错误；调用方取消 → 原错误；其他 → 网络错误 */
+function streamFailureError(failure, error, ctx) {
+    if (failure === "watchdog")
+        return watchdogTimeoutError(ctx.modelId, ctx.url, ctx.body);
+    if (failure === "caller-abort")
+        throw error; // §3 行 10：不合成错误，原样传播
+    return networkError(ctx.modelId, ctx.url, ctx.body, error);
+}
+/** 读错误响应体；读失败按空串兜底（错误映射的 responseBody 保真优先） */
+async function readBodySafely(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/protocol/images.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 协议核心·图片输入（契约：docs/spec/protocol.md §5）。
+ *
+ * 三种投递形态在此归一为「可同步转换」的 part data：
+ * - `Uint8Array` / base64 字符串 / `data:` URL：无需预处理，直接交给信封构造
+ *   （envelope.ts 的同步转换）。
+ * - 外链 URL 引用（URL 对象或 http(s) 字符串）：**必须完整实现转换**——用调用方
+ *   注入的 fetch（工厂 options.fetch 接缝，宿主包装实例自带超时）下载为
+ *   `Uint8Array` 再进信封；下载失败/非 2xx 视为该图不可投递：丢弃 + warn
+ *   （非静默，与「未声明模态丢弃」同级的防御降级，主文本请求照发）。
+ *
+ * 模态分支（老板红线级裁决的「放行后静默丢弃」禁止面）：
+ * - 模型 `inputModalities` 含 `image` → 图片 part 全部放行（上述转换）。
+ * - 未声明 `image` 的模型收到图片 → 丢弃 + logger.warn（防御路径：OpenCode UI
+ *   本就不会让用户往纯文本模型贴图，能到这里说明是异常流）。
+ * - mediaType 非 image/* 的 file part（pdf 等）：模态词表只有 text/image，
+ *   任何非图片文件都不在「网关可投递」口径内 → 丢弃 + warn。
+ *
+ * 客户端不设尺寸限：超大图直接转换，超限由网关 400 按错误映射表浮出（§5）。
+ */
+import type { LanguageModelV3FilePart, LanguageModelV3Prompt } from "@ai-sdk/provider";
+import type { DisguiseLogger } from "../disguise/logger.js";
+import type { FetchLike } from "./json.js";
+export interface PrepareImagesContext {
+    /** 模型管线级联 inputModalities（gateway 可投递口径词表，见 model-pipeline.md §1.1） */
+    inputModalities: readonly string[];
+    /** wire id——warn 日志需区分模型 */
+    modelId: string;
+    /** 工厂 options.fetch 接缝（宿主包装实例；下载失败/非 2xx = 不可投递） */
+    fetch: FetchLike;
+    /** 注入式 logger（disguise.md §7 形态）；测试注记录型 spy */
+    logger: DisguiseLogger;
+}
+/** 模型是否声明 image 模态 */
+export declare function supportsImage(inputModalities: readonly string[] | undefined): boolean;
+/** part 是否为图片（mediaType 以 image/ 开头） */
+export declare function isImageFilePart(part: unknown): part is LanguageModelV3FilePart & {
+    mediaType: string;
+};
+/**
+ * prompt 图片预处理：模态过滤 + 外链 URL 下载。
+ * 返回新 prompt（消息级重建；含图片之外 part 的消息原样保留其余内容），
+ * 下载失败或模态外的图片 part 被移除并在注入 logger 上 warn（绝不静默）。
+ */
+export declare function preparePromptImages(prompt: LanguageModelV3Prompt, ctx: PrepareImagesContext): Promise<LanguageModelV3Prompt>;

package/dist/protocol/images.js

@@ -0,0 +1,115 @@
+/**
+ * 协议核心·图片输入（契约：docs/spec/protocol.md §5）。
+ *
+ * 三种投递形态在此归一为「可同步转换」的 part data：
+ * - `Uint8Array` / base64 字符串 / `data:` URL：无需预处理，直接交给信封构造
+ *   （envelope.ts 的同步转换）。
+ * - 外链 URL 引用（URL 对象或 http(s) 字符串）：**必须完整实现转换**——用调用方
+ *   注入的 fetch（工厂 options.fetch 接缝，宿主包装实例自带超时）下载为
+ *   `Uint8Array` 再进信封；下载失败/非 2xx 视为该图不可投递：丢弃 + warn
+ *   （非静默，与「未声明模态丢弃」同级的防御降级，主文本请求照发）。
+ *
+ * 模态分支（老板红线级裁决的「放行后静默丢弃」禁止面）：
+ * - 模型 `inputModalities` 含 `image` → 图片 part 全部放行（上述转换）。
+ * - 未声明 `image` 的模型收到图片 → 丢弃 + logger.warn（防御路径：OpenCode UI
+ *   本就不会让用户往纯文本模型贴图，能到这里说明是异常流）。
+ * - mediaType 非 image/* 的 file part（pdf 等）：模态词表只有 text/image，
+ *   任何非图片文件都不在「网关可投递」口径内 → 丢弃 + warn。
+ *
+ * 客户端不设尺寸限：超大图直接转换，超限由网关 400 按错误映射表浮出（§5）。
+ */
+/** 模型是否声明 image 模态 */
+export function supportsImage(inputModalities) {
+    return inputModalities !== undefined && inputModalities.includes("image");
+}
+/** part 是否为图片（mediaType 以 image/ 开头） */
+export function isImageFilePart(part) {
+    if (typeof part !== "object" || part === null)
+        return false;
+    const candidate = part;
+    return candidate.type === "file" && typeof candidate.mediaType === "string" && candidate.mediaType.startsWith("image/");
+}
+/** data 是否为外链 URL 引用（URL 对象或 http(s) 字符串；`data:` 前缀不是外链） */
+function isRemoteUrl(data) {
+    if (data instanceof URL)
+        return true;
+    if (typeof data === "string")
+        return /^https?:\/\//i.test(data);
+    return false;
+}
+/** 外链 URL 字符串化（URL 对象取 href） */
+function urlText(data) {
+    return typeof data === "string" ? data : data.href;
+}
+/**
+ * prompt 图片预处理：模态过滤 + 外链 URL 下载。
+ * 返回新 prompt（消息级重建；含图片之外 part 的消息原样保留其余内容），
+ * 下载失败或模态外的图片 part 被移除并在注入 logger 上 warn（绝不静默）。
+ */
+export async function preparePromptImages(prompt, ctx) {
+    const imageSupported = supportsImage(ctx.inputModalities);
+    let droppedImages = 0;
+    let droppedNonImageFiles = 0;
+    let droppedByDownload = 0;
+    const prepared = [];
+    for (const message of prompt) {
+        if (message.role !== "user") {
+            prepared.push(message);
+            continue;
+        }
+        const content = [];
+        for (const part of message.content) {
+            if (part.type === "file") {
+                if (!isImageFilePart(part)) {
+                    // 非图片 file part（pdf 等）：模态词表外，网关不可投递
+                    droppedNonImageFiles += 1;
+                    continue;
+                }
+                if (!imageSupported) {
+                    droppedImages += 1;
+                    continue;
+                }
+                const data = await resolveImageData(part, ctx);
+                if (data === null) {
+                    droppedByDownload += 1;
+                    continue;
+                }
+                content.push({ ...part, data });
+                continue;
+            }
+            content.push(part);
+        }
+        prepared.push({ ...message, content });
+    }
+    if (!imageSupported && droppedImages > 0) {
+        ctx.logger.warn(`[${ctx.modelId}] 模型未声明 image 模态，已丢弃 ${droppedImages} 张图片输入（防御路径）`);
+    }
+    if (droppedNonImageFiles > 0) {
+        ctx.logger.warn(`[${ctx.modelId}] 收到非图片文件 part（模态词表仅 text/image），已丢弃 ${droppedNonImageFiles} 个`);
+    }
+    if (droppedByDownload > 0) {
+        ctx.logger.warn(`[${ctx.modelId}] 有 ${droppedByDownload} 张外链图片下载失败/非 2xx，已丢弃（主请求照发）`);
+    }
+    return prepared;
+}
+/**
+ * 图片 data 就绪：外链 URL 下载为 Uint8Array；非外链（Uint8Array / base64 串 /
+ * data: URL）原样保留交信封同步转换；下载失败/非 2xx/空响应返回 null
+ * （调用方负责 warn 汇总）。
+ */
+async function resolveImageData(part, ctx) {
+    if (!isRemoteUrl(part.data))
+        return part.data;
+    try {
+        const response = await ctx.fetch(urlText(part.data));
+        if (!response.ok)
+            return null;
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.length === 0)
+            return null;
+        return bytes;
+    }
+    catch {
+        return null;
+    }
+}