deepccc 0.2.3 → 0.2.5

package/README.md

@@ -42,10 +42,11 @@ npm run dev
 内部域名和绝对路径替换为公开示例，任务内容、模型配置、Agent 回复和审批流程均来自
 实际运行结果。
 
-多会话可以并行处理不同任务，每个会话分别选择 model 和 effort，并实时保留 Agent
-回复与工具过程：
+多会话可以并行处理不同任务，每个会话分别选择 model、subModel 和 effort。下图来自
+真实提问“DeepCCC 这个项目妙在哪”，同时展示了图片附件输入与 Agent `present_file`
+图片回传：
 
-![DeepCCC Web UI 多会话与真实 Agent 回复](docs/deepccc-web-ui.png)
+![DeepCCC Web UI 图片附件与真实 Agent 回复](docs/deepccc-web-ui.png)
 
 命中需要确认的命令时，审批卡会直接出现在当前会话时间线中，不打断到弹窗：
 
@@ -59,6 +60,7 @@ npm run dev
 
 - Web-first：多会话、持久化历史、实时流式过程、停止和恢复
 - 会话配置：每个会话独立选择 model、subModel 和 effort
+- 图片附件：Web 支持选择、粘贴和拖拽 PNG/JPEG/WebP；Agent 可用 `present_file` 回传图片
 - 本地工具：代码搜索、文件读写、补丁、命令执行、Git、网页搜索和抓取
 - 权限审批：危险命令在会话时间线中暂停，支持拒绝、允许一次、会话允许和永久允许
 - 上下文管理：自动压缩、原始流日志和跨会话历史检索
@@ -153,6 +155,8 @@ deepccc
 
 Web UI 支持新建、恢复、重命名和删除多会话，多个会话可以同时运行，即使它们指向同一个工作目录。每个会话可独立选择 model、subModel 和 effort，并持续复用 CLI 已保存的历史。注意：当前版本不自动创建 Git worktree；同目录的多个运行中 Agent 直接修改同一组文件，页面会提示覆盖与冲突风险。
 
+图片始终按本地附件处理，不转换为 Provider 原生多模态消息。Web 支持文件选择、剪贴板粘贴和拖拽，每条消息最多 10 张 PNG/JPEG/WebP、单张最大 20 MB；附件复制到 `~/.deepccc/attachments/<session-id>/`，Agent 收到本地绝对路径后使用可用工具自行处理。Agent 可调用 `present_file` 把当前工作目录或会话附件目录中的图片直接展示在会话中；删除会话时对应附件一并清理。
+
 API 设置采用单一 Provider 配置，支持 OpenAI-compatible 与 Anthropic Messages。完整 API Key 只保存在本机 `~/.deepccc/config.json`，浏览器读取设置时仅返回掩码。危险命令会在会话中暂停并请求“拒绝、允许一次、本会话允许、永久允许”，浏览器断开或审批超时默认拒绝。
 
 `git.coAuthor.enabled` 默认开启。DeepCCC 通过 `run_command` 创建 Git 提交时会保留用户为
@@ -217,11 +221,17 @@ deepccc-cli --base-url https://api.openai.com/v1 --api-key "$OPENAI_API_KEY" --m
 deepccc-cli --provider anthropic --base-url https://api.example.com --api-key "$API_KEY" --model claude-sonnet-4-6
 ```
 
-指定工作目录：
+指定工作目录：
 
 ```bash
 deepccc-cli --cwd /path/to/project
-```
+```
+
+附加一张或多张本地图片（可重复传入 `--image`，仍采用本地附件路径，不发送原生多模态内容）：
+
+```bash
+deepccc-cli --image ./error.png --image ./expected.webp
+```
 
 恢复当前工作目录最近一次会话：
 

package/dist/attachments.d.ts

@@ -0,0 +1,42 @@
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+export declare const ATTACHMENT_PROMPT_START = "<deepccc-attachments>";
+export declare const ATTACHMENT_PROMPT_END = "</deepccc-attachments>";
+export interface AttachmentMeta {
+    attachmentId: string;
+    originalName: string;
+    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    size: number;
+    absolutePath: string;
+}
+export interface SaveAttachmentInput {
+    originalName: string;
+    bytes: Uint8Array;
+}
+export interface AttachmentStoreOptions {
+    rootDir?: string;
+    idFactory?: () => string;
+}
+export declare class AttachmentStore {
+    readonly rootDir: string;
+    private readonly idFactory;
+    constructor(options?: AttachmentStoreOptions);
+    save(sessionId: string, input: SaveAttachmentInput): Promise<AttachmentMeta>;
+    importFile(sessionId: string, path: string): Promise<AttachmentMeta>;
+    get(sessionId: string, attachmentId: string): Promise<AttachmentMeta | null>;
+    read(sessionId: string, attachmentId: string): Promise<{
+        attachment: AttachmentMeta;
+        bytes: Buffer;
+    } | null>;
+    delete(sessionId: string, attachmentId: string): Promise<boolean>;
+    deleteSession(sessionId: string): Promise<void>;
+    private readStored;
+    private sessionDir;
+    private metaPath;
+}
+export declare function buildAttachmentPrompt(text: string, attachments: AttachmentMeta[]): string;
+export declare function parseAttachmentPrompt(content: string): {
+    text: string;
+    attachments: AttachmentMeta[];
+};
+export declare function detectImageMime(bytes: Uint8Array): AttachmentMeta["mimeType"] | null;

package/dist/attachments.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { DEEPCCC_HOME } from "./config.js";
+import { normalizeBuiltinSessionId } from "./context.js";
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+export const ATTACHMENT_PROMPT_START = "<deepccc-attachments>";
+export const ATTACHMENT_PROMPT_END = "</deepccc-attachments>";
+export class AttachmentStore {
+    rootDir;
+    idFactory;
+    constructor(options = {}) {
+        this.rootDir = resolve(options.rootDir ?? join(DEEPCCC_HOME, "attachments"));
+        this.idFactory = options.idFactory ?? (() => randomUUID());
+    }
+    async save(sessionId, input) {
+        const bytes = Buffer.from(input.bytes);
+        if (!bytes.length)
+            throw new Error("Image attachment must not be empty");
+        if (bytes.length > MAX_ATTACHMENT_BYTES)
+            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");
+        const normalizedSessionId = normalizeBuiltinSessionId(sessionId);
+        const attachmentId = normalizeAttachmentId(this.idFactory());
+        const extension = extensionForMime(mimeType);
+        const fileName = `${attachmentId}${extension}`;
+        const sessionDir = this.sessionDir(normalizedSessionId);
+        const absolutePath = join(sessionDir, fileName);
+        const meta = {
+            attachmentId,
+            originalName: cleanOriginalName(input.originalName, extension),
+            mimeType,
+            size: bytes.length,
+            absolutePath,
+            fileName,
+        };
+        await mkdir(sessionDir, { recursive: true });
+        const dataTemp = `${absolutePath}.${process.pid}.tmp`;
+        const metaPath = this.metaPath(normalizedSessionId, attachmentId);
+        const metaTemp = `${metaPath}.${process.pid}.tmp`;
+        await writeFile(dataTemp, bytes);
+        await rename(dataTemp, absolutePath);
+        await writeFile(metaTemp, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+        await rename(metaTemp, metaPath);
+        return publicMeta(meta);
+    }
+    async importFile(sessionId, path) {
+        const absolutePath = resolve(path);
+        const info = await stat(absolutePath).catch(() => null);
+        if (!info?.isFile())
+            throw new Error(`Image attachment not found: ${path}`);
+        if (info.size > MAX_ATTACHMENT_BYTES)
+            throw new Error(`Image attachment exceeds the 20 MB limit: ${path}`);
+        return this.save(sessionId, {
+            originalName: basename(absolutePath),
+            bytes: await readFile(absolutePath),
+        });
+    }
+    async get(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        return stored ? publicMeta(stored) : null;
+    }
+    async read(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        if (!stored)
+            return null;
+        try {
+            const bytes = await readFile(stored.absolutePath);
+            if (bytes.length !== stored.size || detectImageMime(bytes) !== stored.mimeType)
+                return null;
+            return { attachment: publicMeta(stored), bytes };
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(sessionId, attachmentId) {
+        const stored = await this.readStored(sessionId, attachmentId);
+        if (!stored)
+            return false;
+        await Promise.all([
+            unlink(stored.absolutePath).catch(() => { }),
+            unlink(this.metaPath(sessionId, attachmentId)).catch(() => { }),
+        ]);
+        return true;
+    }
+    async deleteSession(sessionId) {
+        await rm(this.sessionDir(sessionId), { recursive: true, force: true });
+    }
+    async readStored(sessionId, attachmentId) {
+        const normalizedId = normalizeAttachmentId(attachmentId);
+        try {
+            const value = JSON.parse(await readFile(this.metaPath(sessionId, normalizedId), "utf8"));
+            if (value.attachmentId !== normalizedId || typeof value.fileName !== "string")
+                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")
+                return null;
+            if (value.fileName !== `${normalizedId}${extensionForMime(value.mimeType)}`)
+                return null;
+            const absolutePath = join(this.sessionDir(sessionId), value.fileName);
+            return { ...value, absolutePath };
+        }
+        catch {
+            return null;
+        }
+    }
+    sessionDir(sessionId) {
+        return join(this.rootDir, normalizeBuiltinSessionId(sessionId));
+    }
+    metaPath(sessionId, attachmentId) {
+        return join(this.sessionDir(sessionId), `${normalizeAttachmentId(attachmentId)}.json`);
+    }
+}
+export function buildAttachmentPrompt(text, attachments) {
+    const prompt = text.trim() || "请分析这些图片。";
+    if (!attachments.length)
+        return prompt;
+    const manifest = attachments.map((attachment) => ({
+        attachmentId: attachment.attachmentId,
+        originalName: attachment.originalName,
+        mimeType: attachment.mimeType,
+        size: attachment.size,
+        absolutePath: attachment.absolutePath,
+    }));
+    return [
+        prompt,
+        "",
+        ATTACHMENT_PROMPT_START,
+        JSON.stringify(manifest),
+        ATTACHMENT_PROMPT_END,
+        "以上图片以本地附件文件提供。不要假设模型原生支持图片；请使用可用工具读取这些绝对路径并自行处理。",
+    ].join("\n");
+}
+export function parseAttachmentPrompt(content) {
+    const start = content.indexOf(ATTACHMENT_PROMPT_START);
+    const end = content.indexOf(ATTACHMENT_PROMPT_END, start + ATTACHMENT_PROMPT_START.length);
+    if (start < 0 || end < 0)
+        return { text: content, attachments: [] };
+    const raw = content.slice(start + ATTACHMENT_PROMPT_START.length, end).trim();
+    let attachments = [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed))
+            attachments = parsed.filter(isAttachmentMeta);
+    }
+    catch {
+        return { text: content, attachments: [] };
+    }
+    return { text: content.slice(0, start).trimEnd(), attachments };
+}
+export function detectImageMime(bytes) {
+    const buffer = Buffer.from(bytes);
+    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)
+        return "image/jpeg";
+    if (buffer.length >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP")
+        return "image/webp";
+    return null;
+}
+function extensionForMime(mimeType) {
+    return mimeType === "image/png" ? ".png" : mimeType === "image/jpeg" ? ".jpg" : ".webp";
+}
+function cleanOriginalName(value, extension) {
+    const cleaned = basename(value || `image${extension}`).replace(/[\u0000-\u001f<>:"/\\|?*]+/g, "_").slice(0, 180);
+    return cleaned || `image${extension}`;
+}
+function normalizeAttachmentId(value) {
+    const normalized = value.replace(/[^a-zA-Z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "");
+    if (!normalized || normalized === "." || normalized === "..")
+        throw new Error("Invalid attachment id");
+    return normalized;
+}
+function publicMeta(value) {
+    const { fileName: _, ...meta } = value;
+    return meta;
+}
+function isAttachmentMeta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const attachment = value;
+    return typeof attachment.attachmentId === "string"
+        && typeof attachment.originalName === "string"
+        && typeof attachment.absolutePath === "string"
+        && typeof attachment.size === "number"
+        && (attachment.mimeType === "image/png" || attachment.mimeType === "image/jpeg" || attachment.mimeType === "image/webp");
+}

package/dist/cli.js

@@ -24,6 +24,7 @@ import { reduceProgress } from "./progress/reducer.js";
 import { TerminalProgressRenderer } from "./progress/terminal-renderer.js";
 import { progressView } from "./progress/view.js";
 import { defaultLogDir, setupFileLogging } from "./file-log.js";
+import { AttachmentStore, buildAttachmentPrompt } from "./attachments.js";
 function parsePositiveIntegerOption(name, value) {
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -46,6 +47,7 @@ function parseArgs(argv = process.argv.slice(2)) {
     let streamJson = false;
     let prompt = null;
     let plain = false;
+    const images = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         const next = argv[i + 1];
@@ -104,6 +106,10 @@ function parseArgs(argv = process.argv.slice(2)) {
             prompt = next;
             i++;
         }
+        else if (arg === "--image" && next !== undefined) {
+            images.push(next);
+            i++;
+        }
         else if (arg === "--plain") {
             plain = true;
         }
@@ -115,7 +121,7 @@ function parseArgs(argv = process.argv.slice(2)) {
             help = true;
         }
     }
-    return { config, options, listSessions, resume, help, streamJson, prompt, plain };
+    return { config, options, listSessions, resume, help, streamJson, prompt, images, plain };
 }
 async function loadRuntime() {
     const [{ ChatSession }, { config: appConfig }] = await Promise.all([
@@ -144,6 +150,7 @@ 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)",
         "  --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",
@@ -276,8 +283,8 @@ async function runStreamJson(args) {
         return 0;
     }
     const prompt = args.prompt ?? (!process.stdin.isTTY ? await readPromptFromStdin() : "");
-    if (!prompt.trim()) {
-        writeJsonLine({ type: "error", message: "--stream-json requires --prompt <text> or stdin input" });
+    if (!prompt.trim() && !args.images.length) {
+        writeJsonLine({ type: "error", message: "--stream-json requires --prompt <text>, stdin input, or --image <path>" });
         return 1;
     }
     let runtime;
@@ -310,15 +317,29 @@ async function runStreamJson(args) {
         writeJsonLine({ type: "error", message: err.message });
         return 1;
     }
+    let attachments;
+    try {
+        attachments = await importCliAttachments(resolvedSession.sessionId, args.images);
+    }
+    catch (err) {
+        writeJsonLine({ type: "error", message: err.message });
+        return 1;
+    }
+    const promptWithAttachments = buildAttachmentPrompt(prompt, attachments);
     writeJsonLine({
         type: "start",
         session_id: resolvedSession.sessionId,
         mode: resolvedSession.mode,
         cwd,
         model: args.config.model ?? runtime.appConfig.model,
+        attachments: attachments.map((attachment) => ({
+            attachment_id: attachment.attachmentId,
+            name: attachment.originalName,
+            path: attachment.absolutePath,
+        })),
     });
     try {
-        for await (const event of session.chat(prompt)) {
+        for await (const event of session.chat(promptWithAttachments)) {
             streamJsonEvent(event);
         }
         return 0;
@@ -425,13 +446,24 @@ async function runRepl(args) {
         console.error(`${C.yellow}${err.message}${C.reset}`);
         process.exit(1);
     }
+    let pendingAttachments;
+    try {
+        pendingAttachments = await importCliAttachments(resolvedSession.sessionId, args.images);
+    }
+    catch (err) {
+        console.error(`${C.yellow}${err.message}${C.reset}`);
+        process.exit(1);
+    }
+    if (pendingAttachments.length) {
+        console.log(`${C.dim}Attachments queued: ${pendingAttachments.map((attachment) => attachment.originalName).join(", ")}${C.reset}`);
+    }
     let currentAbort = null;
     const ctrlCState = createCtrlCState();
     rl.prompt();
     rl.on("line", async (line) => {
         ctrlCState.reset();
         const input = line.trim();
-        if (!input) {
+        if (!input && !pendingAttachments.length) {
             rl.prompt();
             return;
         }
@@ -475,8 +507,10 @@ async function runRepl(args) {
         }
         let rendererEnded = false;
         try {
+            const chatInput = buildAttachmentPrompt(input, pendingAttachments);
+            pendingAttachments = [];
             let lastAccumulated = "";
-            for await (const event of session.chat(input, signal)) {
+            for await (const event of session.chat(chatInput, signal)) {
                 if (renderer && view) {
                     view = reduceProgress(view, event);
                     if (event.type === "text" || event.type === "compact" || event.type === "status") {
@@ -564,6 +598,13 @@ async function runRepl(args) {
         process.exit(0);
     });
 }
+async function importCliAttachments(sessionId, paths) {
+    const store = new AttachmentStore();
+    const attachments = [];
+    for (const path of paths)
+        attachments.push(await store.importFile(sessionId, path));
+    return attachments;
+}
 /**
  * skill create 子命令：deepccc-cli skill create <name> [--scope global|project] [--description "..."]
  * 默认创建为全局技能（~/.deepccc/skills/<name>/SKILL.md，Codex 结构）；

package/dist/file-tools.d.ts

@@ -141,12 +141,24 @@ export interface ApplyPatchFileChange {
 export interface ApplyPatchOutput {
     changedFiles: ApplyPatchFileChange[];
 }
+export interface PresentFileInput {
+    path: string;
+    caption?: string;
+}
+export interface PresentFileOutput {
+    path: string;
+    name: string;
+    mimeType: "image/png" | "image/jpeg" | "image/webp";
+    size: number;
+    caption?: string;
+}
 /**
  * 把 `~` / `~/x`（含反斜杠 `~\\x`）展开为用户主目录绝对路径。
  * `~user/x` 形式不展开（Node 无内置支持），保持原样交给后续解析。
  * 供路径工具共用：技能索引里 `~/...` 路径可直接传给 read_file 等工具。
  */
 export declare function expandHomePath(value: string): string;
+export declare function presentFileForTool(cwd: string, input: PresentFileInput): Promise<PresentFileOutput>;
 export declare function readFileForTool(cwd: string, input: ReadFileInput): Promise<ReadFileOutput>;
 export declare function listDirForTool(cwd: string, input?: ListDirInput): Promise<ListDirOutput>;
 export declare function searchCodeForTool(cwd: string, input: SearchCodeInput, signal?: AbortSignal, runtimeOptions?: SearchCodeRuntimeOptions): Promise<SearchCodeOutput>;

package/dist/file-tools.js

@@ -8,6 +8,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { createInterface } from "node:readline";
 import { jsonSchema, tool } from "ai";
 import { isDangerousCommand } from "./permissions.js";
+import { detectImageMime, MAX_ATTACHMENT_BYTES } from "./attachments.js";
 import { killProcessTree } from "./proc-tree-kill.js";
 import { searchBuiltinSessions, } from "./session-search.js";
 import { webFetchForTool, webSearchForTool, } from "./web-tools.js";
@@ -74,6 +75,25 @@ async function pathExists(path) {
         return false;
     }
 }
+export async function presentFileForTool(cwd, input) {
+    const path = resolveToolPath(cwd, input.path);
+    const info = await stat(path).catch(() => null);
+    if (!info?.isFile())
+        throw new Error(`Image file not found: ${input.path}`);
+    if (info.size > MAX_ATTACHMENT_BYTES)
+        throw new Error(`Image file exceeds the 20 MB limit: ${input.path}`);
+    const mimeType = detectImageMime(await readFile(path));
+    if (!mimeType)
+        throw new Error(`present_file only supports PNG, JPEG, or WebP images: ${input.path}`);
+    const caption = input.caption?.trim();
+    return {
+        path,
+        name: basename(path),
+        mimeType,
+        size: info.size,
+        ...(caption ? { caption: caption.slice(0, 500) } : {}),
+    };
+}
 function sha256(buffer) {
     return createHash("sha256").update(buffer).digest("hex");
 }
@@ -1011,6 +1031,19 @@ export function createBuiltinFileTools(cwd, options = {}) {
             }),
             execute: (input, options) => searchCodeForTool(cwd, input, options.abortSignal),
         }),
+        present_file: tool({
+            description: "把本地 PNG、JPEG 或 WebP 图片作为会话图片展示给用户。仅在图片文件已经生成并需要交付时调用。",
+            inputSchema: jsonSchema({
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    path: { type: "string", description: "图片绝对路径或相对于会话工作目录的路径。" },
+                    caption: { type: "string", description: "可选的图片说明。" },
+                },
+                required: ["path"],
+            }),
+            execute: (input) => presentFileForTool(cwd, input),
+        }),
         run_command: tool({
             description: "在本地工作区运行非交互式 shell 命令。用于测试、git 和包脚本。返回 stdout/stderr 和 exitCode；非零退出码不是工具错误。",
             inputSchema: jsonSchema({