deepccc 0.2.25 → 0.2.27

package/README.md

@@ -57,9 +57,9 @@ npm run dev
 
 ![DeepCCC API 与 Web 设置](docs/deepccc-api-settings.png)
 
-## 核心能力
-
-- 有界结构化决策：程序化 `DecisionSession` 支持外部管理上下文、显式工具白名单、运行时结果校验和整轮截止时间；不改变默认聊天行为。详见 [接入文档](docs/decision-session.md)。
+## 核心能力
+
+- 有界结构化决策：程序化 `DecisionSession` 支持外部管理上下文、显式工具白名单、运行时结果校验和整轮截止时间；不改变默认聊天行为。详见 [接入文档](docs/decision-session.md)。
 
 - Web-first：多会话、持久化历史、实时流式过程、停止和恢复
 - 工具时间线：ChatCCC 风格 emoji 摘要、参数/结果折叠、省略行展开和状态记忆
@@ -163,7 +163,11 @@ Web UI 支持新建、恢复、重命名和删除多会话，多个会话可以
 
 模型文本、reasoning 心跳和工具事件通过 SSE 实时更新。每轮消息按真实发生顺序持久化和回放，因此刷新后仍会保持“阶段说明 → 工具调用 → 后续结论”的交错时间线；旧版会话没有顺序数据时，会兼容显示为“工具调用 → 最终回答”。每次工具调用与对应结果合并成一张卡片，折叠态显示 emoji、工具名、状态和关键参数；展开后调用参数默认保留前 8/后 4 行，工具结果保留前 12/后 6 行，省略内容可继续展开。工具卡及省略行的展开状态保存在当前浏览器标签页的 `sessionStorage`，持续生成、切换会话和刷新页面均不会自动收起。消息正文支持标题、表格、列表、引用、链接和代码块等常用 Markdown。
 
-图片始终按本地附件处理，不转换为 Provider 原生多模态消息。Web 支持文件选择、剪贴板粘贴和拖拽，每条消息最多 10 张 PNG/JPEG/WebP、单张最大 20 MB；附件复制到 `~/.deepccc/attachments/<session-id>/`，Agent 收到本地绝对路径后使用可用工具自行处理。Agent 可调用 `present_file` 把当前工作目录或会话附件目录中的图片直接展示在会话中；删除会话时对应附件一并清理。
+图片会转换成模型可见的原生视觉输入。Web 支持选择、粘贴和拖拽 PNG/JPEG/WebP/GIF；CLI 可用 `--image` 或交互命令 `/image`。每条消息最多 10 张、单图最大 20 MiB、图片合计最大 24 MiB，单边最多 8192 像素；超限时提示分图或缩小，保留原图细节。附件复制到 `~/.deepccc/attachments/<session-id>/`，聊天历史只保存引用，raw 日志过滤图片编码。删除 Web 会话时附件一并清理。
+
+默认由当前模型直接看图。若主模型不支持视觉，可在 API 设置中指定 `visionModel`（如 `deepseek-flash`），或设置 `DEEPCCC_VISION_MODEL` / CLI `--vision-model`；该模型使用同一 API 协议、Base URL 和 Key，先分析图片，再由主模型结合观察继续任务。界面及 JSONL 会显示实际图片模型和模式。未配置图片模型的 `deepseek-v4-pro` 收图会明确报错；其他兼容模型需服务端支持图像，接口错误不会降级成“假装看过”。官方 DeepSeek 端点的旧 Flash 名称仅在视觉请求中映射到当前 `deepseek-flash`，自定义网关保留用户配置的名称。
+
+Agent 可用 `read_image` 查看本地截图、图表或工具产物，并通过 `question` 指定需要观察的细节；`present_file` 用于把图片展示给用户。后续追问会按预算重新加载近期图片；较早图片保留路径供 `read_image` 重新查看。独立图片模型的观察按原文问题、模型、端点与图片内容哈希缓存；细节追问可重新调用 `read_image`。压缩后的摘要应保留重要图片引用，缺失或损坏图片会明确报错。本版本支持图片输入，不包含音频、视频或 PDF 原生输入。
 
 API 设置采用单一 Provider 配置，支持 OpenAI-compatible 与 Anthropic Messages。完整 API Key 只保存在本机 `~/.deepccc/config.json`，浏览器读取设置时仅返回掩码。危险命令会在会话中暂停并请求“拒绝、允许一次、本会话允许、永久允许”，浏览器断开或审批超时默认拒绝。
 
@@ -240,11 +244,22 @@ deepccc-cli --provider anthropic --base-url https://api.example.com --api-key "$
 deepccc-cli --cwd /path/to/project
 ```
 
-附加一张或多张本地图片（可重复传入 `--image`，仍采用本地附件路径，不发送原生多模态内容）：
+附加一张或多张本地图片（重复传入 `--image`；路径含空格时加引号）：
 
 ```bash
-deepccc-cli --image ./error.png --image ./expected.webp
-```
+deepccc-cli --image ./error.png --image ./expected.webp
+```
+
+启动后再加图：输入 `/image "C:\截图\报错截图.png"`，看到“图片已加入下一条消息”后输入问题并回车。多图重复 `/image`；相对路径按会话工作目录（`--cwd`）解析。该命令在当前回复结束后使用。启动时的 `--image` 也只加入队列，随后输入问题发送。
+
+脚本或纯命令模式可直接发送图片并获取 JSONL：
+
+```bash
+deepccc-cli --model deepseek-flash --stream-json --prompt "解释截图里的错误" --image "./error screenshot.png"
+deepccc-cli --model deepseek-v4-pro --vision-model deepseek-flash --stream-json --prompt "对比两张图" --image ./before.png --image ./after.png
+```
+
+安装 ChatCCC 后提供的 `cccagent` 使用同一 CLI：将上述 `deepccc-cli` 换成 `cccagent` 即可。它读取 `~/.deepccc/config.json`、`DEEPCCC_*` 环境变量或命令行参数；ChatCCC 机器人里的 API 配置不会自动改写独立 CLI 配置。聊天窗口的图片粘贴/拖拽属于 Web 功能，纯终端请使用文件路径。
 
 恢复当前工作目录最近一次会话：
 

package/bin/deepccc-cli.mjs

@@ -1,17 +1,17 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-
-const require = createRequire(import.meta.url);
-const pkgRoot = dirname(require.resolve("../package.json"));
-const distCli = join(pkgRoot, "dist", "cli.js");
-let args;
-if (existsSync(distCli)) {
-  args = [distCli, ...process.argv.slice(2)];
-} else {
-  args = [require.resolve("tsx/cli"), join(pkgRoot, "src", "cli.ts"), ...process.argv.slice(2)];
-}
-const result = spawnSync(process.execPath, args, { stdio: "inherit", cwd: process.cwd(), env: process.env });
-process.exit(result.status === null ? 1 : result.status);
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+const pkgRoot = dirname(require.resolve("../package.json"));
+const distCli = join(pkgRoot, "dist", "cli.js");
+let args;
+if (existsSync(distCli)) {
+  args = [distCli, ...process.argv.slice(2)];
+} else {
+  args = [require.resolve("tsx/cli"), join(pkgRoot, "src", "cli.ts"), ...process.argv.slice(2)];
+}
+const result = spawnSync(process.execPath, args, { stdio: "inherit", cwd: process.cwd(), env: process.env });
+process.exit(result.status === null ? 1 : result.status);

package/bin/deepccc.mjs

@@ -1,32 +1,32 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-
-const require = createRequire(import.meta.url);
-const pkgRoot = dirname(require.resolve("../package.json"));
-const rawArgs = process.argv.slice(2);
-const distWebEntry = join(pkgRoot, "dist", "web-entry.js");
-const distCli = join(pkgRoot, "dist", "cli.js");
-const sourceMode = !existsSync(distWebEntry);
-const isLegacy = rawArgs.length > 0 && rawArgs[0] !== "web" && !["--reuse-existing", "--port", "--no-open", "--help", "-h"].includes(rawArgs[0]);
-
-if (isLegacy) {
-  console.error("[DeepCCC] CLI commands have moved to deepccc-cli; forwarding this invocation for compatibility.");
-  const args = sourceMode
-    ? [require.resolve("tsx/cli"), join(pkgRoot, "src", "cli.ts"), ...rawArgs]
-    : [distCli, ...rawArgs];
-  const result = spawnSync(process.execPath, args, { stdio: "inherit", cwd: process.cwd(), env: process.env });
-  process.exit(result.status === null ? 1 : result.status);
-}
-
-if (sourceMode) {
-  const result = spawnSync(process.execPath, [require.resolve("tsx/cli"), join(pkgRoot, "src", "web-entry.ts"), ...rawArgs], {
-    stdio: "inherit", cwd: process.cwd(), env: process.env,
-  });
-  process.exit(result.status === null ? 1 : result.status);
-}
-
-const { runWebEntry } = await import(new URL("../dist/web-entry.js", import.meta.url));
-await runWebEntry(rawArgs);
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+const pkgRoot = dirname(require.resolve("../package.json"));
+const rawArgs = process.argv.slice(2);
+const distWebEntry = join(pkgRoot, "dist", "web-entry.js");
+const distCli = join(pkgRoot, "dist", "cli.js");
+const sourceMode = !existsSync(distWebEntry);
+const isLegacy = rawArgs.length > 0 && rawArgs[0] !== "web" && !["--reuse-existing", "--port", "--no-open", "--help", "-h"].includes(rawArgs[0]);
+
+if (isLegacy) {
+  console.error("[DeepCCC] CLI commands have moved to deepccc-cli; forwarding this invocation for compatibility.");
+  const args = sourceMode
+    ? [require.resolve("tsx/cli"), join(pkgRoot, "src", "cli.ts"), ...rawArgs]
+    : [distCli, ...rawArgs];
+  const result = spawnSync(process.execPath, args, { stdio: "inherit", cwd: process.cwd(), env: process.env });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (sourceMode) {
+  const result = spawnSync(process.execPath, [require.resolve("tsx/cli"), join(pkgRoot, "src", "web-entry.ts"), ...rawArgs], {
+    stdio: "inherit", cwd: process.cwd(), env: process.env,
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+const { runWebEntry } = await import(new URL("../dist/web-entry.js", import.meta.url));
+await runWebEntry(rawArgs);

package/dist/attachments.d.ts

@@ -5,7 +5,7 @@ export declare const ATTACHMENT_PROMPT_END = "</deepccc-attachments>";
 export interface AttachmentMeta {
     attachmentId: string;
     originalName: string;
-    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
     size: number;
     absolutePath: string;
 }

package/dist/attachments.js

@@ -22,7 +22,7 @@ export class AttachmentStore {
             throw new Error("Image attachment exceeds the 20 MB limit");
         const mimeType = detectImageMime(bytes);
         if (!mimeType)
-            throw new Error("Only PNG, JPEG, or WebP image attachments are supported");
+            throw new Error("Only PNG, JPEG, or WebP image attachments (also GIF) are supported");
         const normalizedSessionId = normalizeBuiltinSessionId(sessionId);
         const attachmentId = normalizeAttachmentId(this.idFactory());
         const extension = extensionForMime(mimeType);
@@ -98,7 +98,7 @@ export class AttachmentStore {
                 return null;
             if (typeof value.originalName !== "string" || typeof value.size !== "number")
                 return null;
-            if (value.mimeType !== "image/png" && value.mimeType !== "image/jpeg" && value.mimeType !== "image/webp")
+            if (value.mimeType !== "image/png" && value.mimeType !== "image/jpeg" && value.mimeType !== "image/webp" && value.mimeType !== "image/gif")
                 return null;
             if (value.fileName !== `${normalizedId}${extensionForMime(value.mimeType)}`)
                 return null;
@@ -133,7 +133,7 @@ export function buildAttachmentPrompt(text, attachments) {
         ATTACHMENT_PROMPT_START,
         JSON.stringify(manifest),
         ATTACHMENT_PROMPT_END,
-        "以上图片以本地附件文件提供。不要假设模型原生支持图片；请使用可用工具读取这些绝对路径并自行处理。",
+        "图片由内核转换为视觉输入；历史中只保存附件引用，需要重新查看时使用 read_image。",
     ].join("\n");
 }
 export function parseAttachmentPrompt(content) {
@@ -155,6 +155,8 @@ export function parseAttachmentPrompt(content) {
 }
 export function detectImageMime(bytes) {
     const buffer = Buffer.from(bytes);
+    if (buffer.length >= 10 && /GIF8[79]a/.test(buffer.subarray(0, 6).toString("ascii")))
+        return "image/gif";
     if (buffer.length >= 8 && buffer.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
         return "image/png";
     if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
@@ -164,7 +166,7 @@ export function detectImageMime(bytes) {
     return null;
 }
 function extensionForMime(mimeType) {
-    return mimeType === "image/png" ? ".png" : mimeType === "image/jpeg" ? ".jpg" : ".webp";
+    return mimeType === "image/png" ? ".png" : mimeType === "image/jpeg" ? ".jpg" : mimeType === "image/gif" ? ".gif" : ".webp";
 }
 function cleanOriginalName(value, extension) {
     const cleaned = basename(value || `image${extension}`).replace(/[\u0000-\u001f<>:"/\\|?*]+/g, "_").slice(0, 180);
@@ -188,5 +190,5 @@ function isAttachmentMeta(value) {
         && typeof attachment.originalName === "string"
         && typeof attachment.absolutePath === "string"
         && typeof attachment.size === "number"
-        && (attachment.mimeType === "image/png" || attachment.mimeType === "image/jpeg" || attachment.mimeType === "image/webp");
+        && (attachment.mimeType === "image/png" || attachment.mimeType === "image/jpeg" || attachment.mimeType === "image/webp" || attachment.mimeType === "image/gif");
 }

package/dist/cli.js

@@ -59,6 +59,10 @@ function parseArgs(argv = process.argv.slice(2)) {
             config.model = next;
             i++;
         }
+        else if (arg === "--vision-model" && next !== undefined) {
+            config.visionModel = next;
+            i++;
+        }
         else if (arg === "--sub-model" && next !== undefined) {
             config.subModel = next;
             i++;
@@ -140,6 +144,7 @@ function printHelp(appConfig) {
         `  --provider <name>    API protocol: openai or anthropic (current default ${appConfig.provider})`,
         `  --model <name>       Model name (current default ${appConfig.model})`,
         `  --sub-model <name>   Sub-model for lightweight steps (compaction/task; empty = follow main model)`,
+        "  --vision-model <name> Optional image analysis model; empty uses native images in the main model",
         `  --effort <level>     Reasoning effort: none/minimal/low/medium/high/xhigh/max (overrides config.effort)`,
         `  --max-output-tokens <n>  Maximum output tokens (unset = Provider default)`,
         `  --base-url <url>     Provider API base URL (current default ${appConfig.baseURL})`,
@@ -150,7 +155,8 @@ function printHelp(appConfig) {
         "  --list-sessions      List saved sessions and exit",
         "  --stream-json        One-shot mode: write JSONL events to stdout",
         "  --prompt <text>      Prompt text for --stream-json",
-        "  --image <path>      Attach a PNG/JPEG/WebP file (repeatable; copied to the session attachment store)",
+        "  --image <path>      Attach a PNG/JPEG/WebP/GIF file (repeatable; quote paths with spaces)",
+        "  Interactive: /image <path> queues one image for your next message; repeat for multiple images",
         "  --plain              Force plain streaming output (no progress block renderer)",
         "  --dangerously-bypass-permissions  Skip all permission prompts (aligns with chatccc's bypass mode)",
         "  --help, -h           Show help",
@@ -220,7 +226,10 @@ function writeJsonLine(event) {
     process.stdout.write(`${JSON.stringify(event)}\n`);
 }
 function streamJsonEvent(event) {
-    if (event.type === "status") {
+    if (event.type === "image_input") {
+        writeJsonLine({ ...event });
+    }
+    else if (event.type === "status") {
         writeJsonLine({
             type: "status",
             phase: event.phase,
@@ -319,7 +328,7 @@ async function runStreamJson(args) {
     }
     let attachments;
     try {
-        attachments = await importCliAttachments(resolvedSession.sessionId, args.images);
+        attachments = await importCliAttachments(resolvedSession.sessionId, args.images, cwd);
     }
     catch (err) {
         writeJsonLine({ type: "error", message: err.message });
@@ -448,7 +457,7 @@ async function runRepl(args) {
     }
     let pendingAttachments;
     try {
-        pendingAttachments = await importCliAttachments(resolvedSession.sessionId, args.images);
+        pendingAttachments = await importCliAttachments(resolvedSession.sessionId, args.images, cwd);
     }
     catch (err) {
         console.error(`${C.yellow}${err.message}${C.reset}`);
@@ -463,10 +472,41 @@ async function runRepl(args) {
     // model step 边界 drain 后吸收到当前 turn（而非等待整轮结束）。
     let chatRunning = false;
     const pendingInjections = [];
+    let attachmentImport = Promise.resolve();
     rl.prompt();
     rl.on("line", async (line) => {
         ctrlCState.reset();
         const input = line.trim();
+        if (/^\/image(?:\s|$)/.test(input)) {
+            if (chatRunning) {
+                console.log("请等待当前回复结束后用 /image 添加图片。");
+                return;
+            }
+            let path = input.slice(6).trim();
+            if ((path.startsWith('"') && path.endsWith('"')) || (path.startsWith("'") && path.endsWith("'")))
+                path = path.slice(1, -1);
+            if (!path) {
+                console.log('用法：/image "C:\\path with spaces\\image.png"');
+                rl.prompt();
+                return;
+            }
+            attachmentImport = attachmentImport.then(async () => {
+                try {
+                    if (pendingAttachments.length >= 10)
+                        throw new Error("每条消息最多 10 张图片");
+                    const added = await importCliAttachments(resolvedSession.sessionId, [path], cwd);
+                    pendingAttachments.push(...added);
+                    console.log(`图片已加入下一条消息：${added.map(a => a.originalName).join(", ")}。输入问题后回车发送。`);
+                }
+                catch (error) {
+                    console.log(`添加图片失败：${error.message}`);
+                }
+            });
+            await attachmentImport;
+            rl.prompt();
+            return;
+        }
+        await attachmentImport;
         if (!input && !pendingAttachments.length) {
             rl.prompt();
             return;
@@ -529,13 +569,16 @@ async function runRepl(args) {
             for await (const event of session.chat(chatInput, signal, () => pendingInjections.shift())) {
                 if (renderer && view) {
                     view = reduceProgress(view, event);
-                    if (event.type === "text" || event.type === "compact" || event.type === "status" || event.type === "input_injected") {
+                    if (event.type === "text" || event.type === "compact" || event.type === "status" || event.type === "input_injected" || event.type === "image_input") {
                         renderer.render(view);
                     }
                     else {
                         renderer.flush();
                     }
                 }
+                else if (event.type === "image_input") {
+                    console.log(`[图片理解：${event.model}，${event.count} 张，${event.mode}]`);
+                }
                 else if (event.type === "status") {
                     console.log(`${C.dim}[${event.phase === "compacting" ? "compacting context" : "generating reply"}]${C.reset}`);
                 }
@@ -618,11 +661,13 @@ async function runRepl(args) {
         process.exit(0);
     });
 }
-async function importCliAttachments(sessionId, paths) {
+async function importCliAttachments(sessionId, paths, cwd = process.cwd()) {
+    if (paths.length > 10)
+        throw new Error("每条消息最多 10 张图片");
     const store = new AttachmentStore();
     const attachments = [];
     for (const path of paths)
-        attachments.push(await store.importFile(sessionId, path));
+        attachments.push(await store.importFile(sessionId, resolvePath(cwd, path)));
     return attachments;
 }
 /**

package/dist/completion-session.js

@@ -1,6 +1,7 @@
 /** Opt-in stateless completion transport for integrations owning their complete prompts. */
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
-import { Output, streamText } from 'ai';
+import { streamText } from 'ai';
+import { jsonObjectFetch } from './json-mode-fetch.js';
 const protectedKeys = new Set(['messages', 'model', 'stream', 'tools', 'tool_choice', 'response_format', 'temperature', 'max_tokens', 'max_completion_tokens']);
 function positive(n) { if (!Number.isSafeInteger(n) || n < 1)
     throw new Error('Positive integer budget required'); return n; }
@@ -45,11 +46,12 @@ export class CompletionSession {
         try {
             if (controller.signal.aborted)
                 throw new Error('Interrupted');
+            const transport = request.json ? jsonObjectFetch() : globalThis.fetch;
             const client = createOpenAICompatible({ name: 'completion', ...this.config, includeUsage: true,
-                fetch: async (url, init) => fetch(url, { ...init, body: JSON.stringify({ ...JSON.parse(String(init?.body)), ...extensions }) }) });
+                fetch: async (url, init) => transport(url, { ...init, body: JSON.stringify({ ...JSON.parse(String(init?.body)), ...extensions }) }) });
             calls++;
             const result = streamText({ model: client(this.config.model), messages, allowSystemInMessages: true, temperature: request.temperature, maxOutputTokens: request.maxOutputTokens,
-                ...(request.json ? { output: Output.json() } : {}), maxRetries: 0, abortSignal: controller.signal, onError: () => { } });
+                maxRetries: 0, abortSignal: controller.signal, onError: () => { } });
             const iterator = result.fullStream[Symbol.asyncIterator]();
             let content = '', reasoning = '', finish;
             try {

package/dist/config.d.ts

@@ -10,6 +10,8 @@ export interface DeepCccConfig {
      * 留空（""）时跟随主模型，行为与旧版完全一致。
      */
     subModel: string;
+    /** Optional dedicated image analysis model, using the same provider credentials. */
+    visionModel: string;
     /** Reasoning effort（none/minimal/low/medium/high/xhigh/max），留空不传 reasoning_effort */
     effort: string;
     /** 主对话最大输出 token；未配置时不传，使用 Provider 默认值。 */
@@ -50,7 +52,7 @@ export declare function readConfigFile(): Partial<DeepCccConfig>;
 export declare function normalizeDeepCccProvider(value: unknown): DeepCccProvider;
 export declare function loadConfig(): DeepCccConfig;
 export declare function ensureConfigDir(): void;
-export type DeepCccConfigPatch = Partial<Pick<DeepCccConfig, "provider" | "apiKey" | "baseURL" | "model" | "subModel" | "effort" | "maxOutputTokens" | "streaming" | "contextWindow">> & {
+export type DeepCccConfigPatch = Partial<Pick<DeepCccConfig, "provider" | "apiKey" | "baseURL" | "model" | "subModel" | "visionModel" | "effort" | "maxOutputTokens" | "streaming" | "contextWindow">> & {
     web?: Partial<DeepCccConfig["web"]>;
 };
 /** Persist only user-editable Web fields while preserving advanced configuration. */

package/dist/config.js

@@ -13,6 +13,7 @@ export const DEFAULT_CONFIG = {
     baseURL: "https://api.deepseek.com/v1",
     model: "deepseek-v4-pro",
     subModel: "",
+    visionModel: "",
     effort: "",
     streaming: true,
     contextWindow: 1_048_576,
@@ -88,6 +89,7 @@ export function loadConfig() {
         baseURL: env("DEEPCCC_BASE_URL") ?? env("DEEPSEEK_BASE_URL") ?? file.baseURL ?? DEFAULT_CONFIG.baseURL,
         model: env("DEEPCCC_MODEL") ?? env("DEEPSEEK_MODEL") ?? file.model ?? DEFAULT_CONFIG.model,
         subModel: env("DEEPCCC_SUB_MODEL") ?? file.subModel ?? DEFAULT_CONFIG.subModel,
+        visionModel: env("DEEPCCC_VISION_MODEL") ?? file.visionModel ?? DEFAULT_CONFIG.visionModel,
         effort: env("DEEPCCC_EFFORT") ?? env("DEEPSEEK_EFFORT") ?? file.effort ?? DEFAULT_CONFIG.effort,
         maxOutputTokens: optionalPositiveInteger(env("DEEPCCC_MAX_OUTPUT_TOKENS"))
             ?? optionalPositiveInteger(file.maxOutputTokens),
@@ -130,6 +132,8 @@ export function saveConfigPatch(patch) {
         throw new Error("baseURL must not be empty");
     if (patch.model !== undefined && !patch.model.trim())
         throw new Error("model must not be empty");
+    if (patch.visionModel !== undefined && typeof patch.visionModel !== "string")
+        throw new Error("visionModel must be a string");
     if (patch.effort !== undefined && !["", "none", "minimal", "low", "medium", "high", "xhigh", "max"].includes(patch.effort)) {
         throw new Error(`Unsupported effort: ${patch.effort}`);
     }

package/dist/context.js

@@ -285,7 +285,9 @@ export function estimateBuiltinToolContextTokens(messages) {
 }
 export function estimateBuiltinContextTokens(summary, messages) {
     const text = summary + messages.reduce((sum, message) => sum + `${message.role}\n${stripStoredToolTranscript(message.content)}\n`, "");
-    return estimateTextTokens(text) + estimateBuiltinToolContextTokens(messages);
+    // Reserve a conservative visual allowance without counting binary/base64 as text.
+    const imageCount = messages.reduce((n, m) => n + (m.role === "user" && m.content.includes("<deepccc-attachments>") ? (m.content.match(/"attachmentId"\s*:/g)?.length ?? 0) : 0), 0);
+    return estimateTextTokens(text) + estimateBuiltinToolContextTokens(messages) + Math.min(imageCount, 10) * 2048;
 }
 export function serializeMessagesForSummary(messages) {
     return messages
@@ -531,6 +533,7 @@ export function buildSummaryPrompt(plan) {
         "- 将会话进度与已核实项目事实分节：项目事实保留能力、实现入口、证据路径/符号及验证范围；推测单列，后来的纠正覆盖此前错误判断。",
         "- 不把搜索失败/截断/无命中概括为实现不存在，不把辅助模块概括为整个架构。不保留密钥、授权令牌或临时 capability grant。",
         "- 项目事实是历史证据，不是当前实现保证；提示继续时可用 workspace_map 找到有效证据笔记，再读取源码核验。",
+        "- 保留与当前任务相关的图片附件路径、原始问题和已确认观察，标明未确定细节；只保留引用，不包含图片编码。后续需要查看原图可调用 read_image。",
         "",
     ];
     if (plan.previousSummary.trim()) {

package/dist/decision-session.js

@@ -1,7 +1,8 @@
 /** Bounded, text-only decisions with caller-owned context and explicit capabilities. */
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { createAnthropic } from "@ai-sdk/anthropic";
-import { asSchema, Output, streamText, tool } from "ai";
+import { asSchema, streamText, tool } from "ai";
+import { jsonObjectFetch } from "./json-mode-fetch.js";
 import { parseJsonResponse } from "./json-response.js";
 import { performance } from "node:perf_hooks";
 import { config, normalizeDeepCccProvider } from "./config.js";
@@ -92,7 +93,8 @@ export class DecisionSession {
         const baseURL = overrides.baseURL ?? config.baseURL;
         const client = provider === "anthropic"
             ? createAnthropic({ apiKey, baseURL: baseURL.trim().replace(/\/+$/, "") })
-            : createOpenAICompatible({ name: "deepccc", apiKey, baseURL, includeUsage: true });
+            : createOpenAICompatible({ name: "deepccc", apiKey, baseURL, includeUsage: true,
+                ...(this.outputMode === "json" ? { fetch: jsonObjectFetch() } : {}) });
         this.model = client(overrides.model ?? config.model);
         const effort = (overrides.effort ?? config.effort ?? "").trim();
         this.providerOptions = effort ? provider === "anthropic"
@@ -240,7 +242,7 @@ export class DecisionSession {
         const began = performance.now();
         metrics.modelCalls++;
         const result = streamText({ model: this.model, system: this.system, messages: [...messages],
-            ...(this.outputMode === "json" ? { output: Output.json() } : { tools: this.modelTools, toolChoice: "required" }),
+            ...(this.outputMode === "json" ? {} : { tools: this.modelTools, toolChoice: "required" }),
             maxRetries: 0, abortSignal: signal, maxOutputTokens: this.maxOutputTokens,
             // The SDK default logs raw errors. Return allowlisted diagnostics instead.
             onError: () => { },

package/dist/file-tools.d.ts

@@ -1,5 +1,6 @@
 import { type ToolSet } from "ai";
 import { type PermissionGate } from "./permissions.js";
+import type { ImageReference, ReadImageInput } from "./multimodal.js";
 import { type SearchScope } from "./workspace-policy.js";
 /** task 子代理工具：子任务结果回传主会话前的最大字符数（防止子代理长输出撑爆主上下文） */
 export declare const MAX_TASK_OUTPUT_CHARS = 32000;
@@ -209,7 +210,7 @@ export interface PresentFileInput {
 export interface PresentFileOutput {
     path: string;
     name: string;
-    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
     size: number;
     caption?: string;
 }
@@ -244,6 +245,7 @@ export declare function deleteFileForTool(cwd: string, input: DeleteFileInput):
 export declare function moveFileForTool(cwd: string, input: MoveFileInput): Promise<MoveFileOutput>;
 export declare function applyPatchForTool(cwd: string, input: ApplyPatchInput): Promise<ApplyPatchOutput>;
 export interface BuiltinFileToolsOptions {
+    readImage?: (input: ReadImageInput) => Promise<ImageReference>;
     /** 权限门控：副作用工具（进程/脚本/命令执行与文件写操作）执行前会先经过 gate.check */
     permissionGate?: PermissionGate;
     /** Git commits created by DeepCCC receive this Co-authored-by trailer when enabled. */

package/dist/file-tools.js

@@ -1513,6 +1513,11 @@ export function createBuiltinFileTools(cwd, options = {}) {
             }),
             execute: (input) => readFileForTool(cwd, input),
         }),
+        ...(options.readImage ? { read_image: tool({
+                description: "查看本地 PNG/JPEG/WebP/GIF 图片。图片作为视觉输入提供给模型，返回的是附件引用而非图片文字。可指定 question 聚焦细节；用于历史图片、报错截图、图表和工具生成的图片。",
+                inputSchema: jsonSchema({ type: "object", additionalProperties: false, properties: { path: { type: "string", description: "图片绝对路径或相对于工作目录的路径" }, question: { type: "string", description: "希望观察的细节或问题" } }, required: ["path"] }),
+                execute: input => options.readImage(input),
+            }) } : {}),
         list_dir: tool({
             description: "列出本地目录中的文件。",
             inputSchema: jsonSchema({

package/dist/index.d.ts

@@ -5,6 +5,8 @@
  */
 import { type DeepCccProvider } from "./config.js";
 import { type PermissionMode, type PermissionResolver } from "./permissions.js";
+import { type ImageUseNotice } from "./multimodal.js";
+import type { AttachmentStore } from "./attachments.js";
 export { DecisionSession } from "./decision-session.js";
 export { CompletionSession } from "./completion-session.js";
 export type { CompletionConfig, CompletionRequest, CompletionResult } from "./completion-session.js";
@@ -36,6 +38,8 @@ export interface ChatSessionConfig {
      * 子模型 id（可选）：用于压缩摘要生成与 task 子代理任务。留空跟随主模型。
      */
     subModel?: string;
+    /** Optional dedicated image analysis model. Empty = native image input to the main model. */
+    visionModel?: string;
     /**
      * Reasoning effort (none/minimal/low/medium/high/xhigh/max);
      * overrides config.effort; empty omits the reasoning_effort request field.
@@ -47,6 +51,7 @@ export interface ChatSessionConfig {
     streaming?: boolean;
 }
 export interface ChatSessionOptions {
+    attachmentStore?: AttachmentStore;
     /** Session working directory. */
     cwd?: string;
     /** Extra system guidance appended after project instructions. */
@@ -100,7 +105,9 @@ export interface ChatSessionOptions {
 /**
  * 流式响应事件
  */
-export type ChatEvent = {
+export type ChatEvent = ({
+    type: "image_input";
+} & ImageUseNotice) | {
     type: "status";
     phase: "compacting" | "generating";
 } | {
@@ -152,6 +159,10 @@ export declare class ChatSession {
     private baseURL;
     private modelId;
     private subModelId;
+    private visionModelId;
+    private imageRuntime;
+    private providerFactory;
+    private imageNotices;
     private cwd;
     private context;
     private compactionTimeoutMs;