Skip to content

A local plugin for image-heavy chats in Codex, Claude Code and other agents: earlier images stop going out with every message, and the model fetches the one it needs by its ID, also after compaction.

feat(claude): 每条含被省略图片的消息后跟一条简短说明(尚未经模型验证)

chipfighter8a49731aaa4b
diff --git a/plugin/src/claude-rewrite.ts b/plugin/src/claude-rewrite.ts
index 86d62ec..397ae65 100644
--- a/plugin/src/claude-rewrite.ts
+++ b/plugin/src/claude-rewrite.ts
@@ -14,7 +14,7 @@
import type { ClaudeIndex, ClaudeImage } from "./claude-index.ts";
import { imageDigest, type ImageDigest, type ImageKind } from "./images.ts";
import type { Lang } from "./language.ts";
-import { autoNote, autoPlaceholder, copyNote, duplicatePlaceholder, includedLabel, newImageWord, omissionNote, plainPlaceholder, type Described, type RewriteReport } from "./rewrite.ts";
+import { autoPlaceholder, claudeNote, copyNote, duplicatePlaceholder, hereNote, includedLabel, newImageWord, plainPlaceholder, type Described, type RewriteReport } from "./rewrite.ts";
type Json = Record<string, any>;
// msg: the message; part: the block in its content; sub: for an image in a tool result, its position in that result.
@@ -124,13 +124,14 @@ export function rewriteMessages(
const carried = !before && ref.block.cache_control ? { cache_control: ref.block.cache_control } : {};
edits.set(where, [...(edits.get(where) ?? []), { at, remove, blocks: [{ type: "text", text, ...carried }] }]);
};
- let firstPlain: number | null = null;
+ // The messages holding plain placeholders, each with its omitted images, for the notes that follow them.
+ const plainBy = new Map<number, Described[]>();
for (const ref of drop) {
const image = describe(ref)!;
const copy = lasting.find((other) => same(other, ref));
const copyImage: Described | null = copy ? describe(copy) ?? { id: newImageWord(lang), name: null, label: null, kind: copy.kind, turn: null, width: copy.width, height: copy.height } : null;
const text = copyImage ? duplicatePlaceholder(image, copyImage, lang) : auto ? autoPlaceholder(image, lang) : plainPlaceholder(image, lang);
- if (!copyImage && firstPlain === null) firstPlain = ref.msg;
+ if (!copyImage) plainBy.set(ref.msg, [...(plainBy.get(ref.msg) ?? []), image]);
report.replaced.push({ id: image.id, key: ref.key!, kind: image.kind, mode: copyImage ? "duplicate" : "plain", sameAs: copyImage?.id ?? null, base64Chars: ref.base64Chars });
edit(ref, 1, text);
}
@@ -161,19 +162,23 @@ export function rewriteMessages(
if (own) content = apply(content, own);
return { ...message, content };
});
- // Only plain placeholders need the note (a duplicate's content is still in view). Right after the user message
- // holding the first one; when Claude Code put a system message there already, the note joins it, since two system
- // messages may not follow each other.
- if (firstPlain !== null) {
- const text = auto ? autoNote(lang) : omissionNote(lang);
- const after = next[firstPlain + 1];
+ // Only plain placeholders need a note (a duplicate's content is still in view). Each message holding one is followed
+ // by a short note naming its omitted images, and the first of them also by the full note: Claude does not believe
+ // what a tool result says about itself, and a note far from the placeholder was not enough (desktop tests,
+ // 2026-10-09). A note goes right after the user message, the only place Anthropic allows a system message; when
+ // Claude Code put a system message there already, the note joins it, since two may not follow each other. Later
+ // messages first, so the earlier positions stay as they are.
+ const holding = [...plainBy.keys()].sort((a, b) => a - b);
+ for (const msg of [...holding].reverse()) {
+ const text = `${msg === holding[0] ? `${claudeNote(lang, auto !== undefined)}\n` : ""}${hereNote(plainBy.get(msg)!, lang, auto !== undefined)}`;
+ const after = next[msg + 1];
if (after?.role === "system") {
const content = typeof after.content === "string" ? [{ type: "text", text: after.content }] : after.content;
- next[firstPlain + 1] = { ...after, content: [{ type: "text", text }, ...content] };
+ next[msg + 1] = { ...after, content: [{ type: "text", text }, ...content] };
} else {
- next.splice(firstPlain + 1, 0, { role: "system", content: text });
+ next.splice(msg + 1, 0, { role: "system", content: text });
}
- report.noteAt = firstPlain + 1;
}
+ if (holding.length) report.noteAt = holding[0] + 1;
return { messages: next, report };
}
diff --git a/plugin/src/rewrite.ts b/plugin/src/rewrite.ts
index 4000cde..696e366 100644
--- a/plugin/src/rewrite.ts
+++ b/plugin/src/rewrite.ts
@@ -30,6 +30,9 @@ type Words = {
heading: (id: string, label: string | null, state: string, fields: string[]) => string;
plain: (id: string) => string; duplicate: (id: string, where: string) => string; note: string;
autoPlain: (id: string) => string; autoNote: string; copy: (id: string) => string; fetch: FetchWords;
+ // v0.4, Claude Code only (claude-rewrite.ts): what the note adds about tool results, and the short note that follows
+ // each message holding omitted images, naming them.
+ toolNote: string; here: (list: string) => string; hereAuto: (list: string) => string; listItem: (id: string, name: string | null, kind: string) => string;
};
// The image sits in the history, so the model concludes it never saw it and takes back what it said about it (user
@@ -64,6 +67,14 @@ const WORDS: Record<Lang, Words> = {
"用 cam_view_image 取回的图片只在本轮提供,下一轮又会换回占位文字;之后还需要时,再调用一次。标着“已提供”或“取回的原图”的图片现在就在你面前:被问到它时,直接看图回答,不要说看不到。",
].join("\n"),
copy: (id) => `[${id} 的原图:模型当时用 cam_view_image 取回,只在那一轮提供,现在已省略]`,
+ // v0.4: in Claude Code desktop tests (Haiku 5.5, 2026-10-09) the model read a placeholder inside a Read result as
+ // what the tool had returned, said it had never seen the image and took back its correct description; the same
+ // words inside the tool result were not believed ("I should not follow the placeholder"). With the note right after
+ // the message holding the image, it answered as intended. So each such message is followed by a short note.
+ toolNote: "工具结果里的图片也一样:那次工具调用当时返回的是原图,你当时看到了;工具结果里的占位文字是后来才换上的,不是工具当时的返回。",
+ here: (list) => `上下文管理说明:上面这条消息里的 ${list} 当时是原图,你当时看过;你之前对它们的描述和据此做出的判断仍然有效,不要收回,也不要说成是猜测或编造。那里的占位文字是这次请求才换上的,不是当时的内容。被问到时,如实说现在看不到(被用户省略了),不要补充之前没说过的细节;需要时写“需要 IMG-xxx”。`,
+ hereAuto: (list) => `上下文管理说明:上面这条消息里的 ${list} 当时是原图,你当时看过;你之前对它们的描述和据此做出的判断仍然有效,不要收回,也不要说成是猜测或编造。那里的占位文字是这次请求才换上的(自动选图),不是当时的内容。之前说过的内容不够用时,调用 cam_view_image 取回原图;不要补充之前没说过的细节。`,
+ listItem: (id, name, kind) => `${id}(${[name, kind].filter(Boolean).join(",")})`,
fetch: {
title: "查看被省略的图片",
description: "查看这个任务里一张或几张被省略的图片的原图。被省略的图片在对话里显示为“[图片 IMG-xxx 已省略…]”。只在回答需要看图、而你之前对它说过的内容不够用时调用;取回的原图只在本轮提供。",
@@ -100,6 +111,10 @@ const WORDS: Record<Lang, Words> = {
"An image you get with cam_view_image is included only in this turn; from the next turn on it is a placeholder again. Call the tool again if you need it later. An image marked \"included\" or \"fetched original\" is in front of you now: when asked about it, look at it and answer from it, and do not say you cannot see it.",
].join("\n"),
copy: (id) => `[Original of ${id}: fetched by the model with cam_view_image, included only in that turn, now omitted]`,
+ toolNote: "The same holds for images in tool results: the tool call returned the original image at the time and you saw it; a placeholder inside a tool result was put there later, it is not what the tool returned.",
+ here: (list) => `Context management note: in the message above, ${list} were original images at the time, and you looked at them then; what you said about them and the judgments you based on it remain valid, so do not take them back or call them guesses or made up. The placeholder text there was put in only for this request; it is not what was there at the time. If asked, say truthfully that you cannot see them now (the user left them out), and do not add details you did not mention before; if you need one, write "need IMG-xxx".`,
+ hereAuto: (list) => `Context management note: in the message above, ${list} were original images at the time, and you looked at them then; what you said about them and the judgments you based on it remain valid, so do not take them back or call them guesses or made up. The placeholder text there was put in only for this request (automatic image selection); it is not what was there at the time. When what you said before is not enough, fetch the original with cam_view_image; do not add details you did not mention before.`,
+ listItem: (id, name, kind) => `${id} (${[name, kind].filter(Boolean).join(", ")})`,
fetch: {
title: "View omitted images",
description: "View the originals of one or more omitted images in this task. Omitted images appear in the conversation as \"[Image IMG-xxx omitted…]\". Call it only when an answer needs to look at an image and what you said about it before is not enough; the originals are included only in this turn.",
@@ -148,6 +163,15 @@ export const fetchWords = (lang: Lang): FetchWords => WORDS[lang].fetch;
export const copyNote = (id: string, lang: Lang) => WORDS[lang].copy(id);
export const newImageWord = (lang: Lang) => WORDS[lang].newImage;
+// v0.4, Claude Code only: the note also speaks of tool results, and a short note follows each message holding omitted
+// images, naming them. Codex's words stay as they are.
+export const claudeNote = (lang: Lang, auto = false) => `${auto ? WORDS[lang].autoNote : WORDS[lang].note}\n${WORDS[lang].toolNote}`;
+export function hereNote(images: Described[], lang: Lang = "zh", auto = false): string {
+ const words = WORDS[lang];
+ const list = images.map((image) => words.listItem(image.id, image.name, words.kind[image.kind])).join(words.separator);
+ return auto ? words.hereAuto(list) : words.here(list);
+}
+
export function autoPlaceholder(image: Described, lang: Lang = "zh"): string {
const words = WORDS[lang];
return `${heading(words, image, words.omitted)}\n${words.autoPlain(image.id)}`;
diff --git a/spike/src/claude-rewrite.test.ts b/spike/src/claude-rewrite.test.ts
index db544dc..deda720 100644
--- a/spike/src/claude-rewrite.test.ts
+++ b/spike/src/claude-rewrite.test.ts
@@ -7,7 +7,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import { buildClaudeIndex } from "../../plugin/src/claude-index.ts";
import { findRequestImages, rewriteMessages } from "../../plugin/src/claude-rewrite.ts";
-import { omissionNote } from "../../plugin/src/rewrite.ts";
+import { claudeNote } from "../../plugin/src/rewrite.ts";
import { image, pngA, pngB, pngC, text, transcript, usualRequest, usualSession } from "./claude-fixtures.ts";
const noPixels = () => null;
@@ -63,7 +63,9 @@ test("an unchecked pasted image becomes a placeholder; the note follows its mess
assert.equal(messages[0].content[1].source.data, pngA);
assert.match(messages[0].content[2].text, /^\[图片 IMG-002 已省略|未命名|用户上传|第 1 轮|8×8\]\n.*需要 IMG-002/s);
assert.equal(messages[0].content[3].text, "What are these?");
- assert.deepEqual(messages[1], { role: "system", content: omissionNote("zh") });
+ assert.equal(messages[1].role, "system");
+ assert.ok(messages[1].content.startsWith(claudeNote("zh")));
+ assert.match(messages[1].content, /上面这条消息里的 IMG-002/);
// The rest keeps its order; the thinking block and the cache breakpoint are untouched.
assert.deepEqual(messages[2], request[1]);
assert.equal(messages.length, request.length + 1);
@@ -104,7 +106,7 @@ test("a placeholder keeps the cache breakpoint the image had; a system message a
assert.deepEqual(messages[0].content[0].cache_control, { type: "ephemeral" });
assert.equal(messages.length, 3);
assert.equal(messages[1].role, "system");
- assert.equal(messages[1].content[0].text, omissionNote("zh"));
+ assert.ok(messages[1].content[0].text.startsWith(claudeNote("zh")));
assert.deepEqual(messages[1].content[1], { type: "text", text: "Claude Code's own" });
});