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(spike): P3-3 插件服务与面板数据、P3-4 一键安装和恢复

chipfighterd394adb60aa9
diff --git a/spike/src/cam.ts b/spike/src/cam.ts
index 5d33a36..ef81615 100644
--- a/spike/src/cam.ts
+++ b/spike/src/cam.ts
@@ -1,54 +1,91 @@
-// Purpose: P2 — command-line stand-in for the panel: list a thread's images and check/uncheck them.
-// Input: list <thread> | uncheck <thread> IMG-… | check <thread> IMG-… | check-all <thread>.
-// Output: the selection file under local/selection/ and a table on stdout. Rollouts are only read.
+// Purpose: the tool's command line. P3-4: install / uninstall / status set up and remove every managed setting at
+// once; list / uncheck / check / check-all stand in for the panel until P4.
+// Input: install [--port N] | uninstall | status | list|uncheck|check|check-all <thread id> [IMG-…].
+// Output: config.toml (copied to <data dir>/config-backup/ before every change), ~/.codex/.env (never copied or
+// printed: it may hold credentials), the selection file, and a summary on stdout. Rollouts are only read.
-import { join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
-import { codexHome } from "./codexconfig.ts";
-import { readSelection, writeSelection } from "./selection.ts";
-import { loadThreadIndex, type IndexedImage, type ThreadIndex } from "./thread-index.ts";
+import { codexHome, MCP_BEGIN, noProxyStatus, persistedEnv, proxyStatus } from "./codexconfig.ts";
+import { DEFAULT_PORT, engineHealth, ensureEngine } from "./engine.ts";
+import { planInstall, planUninstall, type Plan } from "./install.ts";
+import { applySelection, loadPanelState, type PanelState } from "./panel-state.ts";
+import { dataDir } from "./paths.ts";
-export function sameContent(index: ThreadIndex, image: IndexedImage): string[] {
- return index.images
- .filter((other) => other !== image && (other.contentId === image.contentId || (image.pixelSha256 !== null && other.pixelSha256 === image.pixelSha256)))
- .map((other) => other.id);
-}
+const KIND: Record<string, string> = { upload: "上传", view: "工具查看", generated: "生成", tool: "工具结果" };
-function table(index: ThreadIndex): string {
- const unchecked = new Set(Object.keys(readSelection(index.threadId).unchecked));
- const rows = index.images.map((image) => [
+function table(state: PanelState): string {
+ const rows = state.images.map((image) => [
image.id,
- !image.replaceable ? "锁定" : unchecked.has(image.key) ? "取消" : "勾选",
- image.kind,
+ !image.replaceable ? "锁定" : image.checked ? "勾选" : "取消",
+ KIND[image.kind] ?? image.kind,
image.name ?? "—",
image.turn ?? "—",
image.width && image.height ? `${image.width}×${image.height}` : "—",
`${(image.bytes / 1024).toFixed(0)} KB`,
- sameContent(index, image).join(",") || "—",
+ image.sameAs.join(",") || "—",
+ image.requested ? "模型索要" : "",
].join(" | "));
- return [`thread ${index.threadId}: ${index.images.length} images, ${index.turns} turns`, "id | 状态 | 种类 | 名称 | 轮次 | 尺寸 | 大小 | 内容相同", ...rows].join("\n");
+ const mb = (bytes: number) => (bytes / 1e6).toFixed(2);
+ return [
+ `任务 ${state.threadId}:${state.totals.images} 张图,${state.turns} 轮;取消 ${state.totals.unchecked} 张;勾选的图共 ${mb(state.totals.checkedBytes)} MB(全部勾选时 ${mb(state.totals.allBytes)} MB)`,
+ "编号 | 状态 | 来源 | 名称 | 轮次 | 尺寸 | 大小 | 内容相同 | 备注",
+ ...rows,
+ ].join("\n");
}
-function main(): void {
- const [command, threadId, ...ids] = process.argv.slice(2);
- if (!command || !threadId) throw new Error("usage: cam.ts list|uncheck|check|check-all <thread id> [IMG-…]");
- const index = loadThreadIndex(join(codexHome(), "sessions"), threadId);
- if (command !== "list") {
- const selection = readSelection(threadId);
- const unchecked = { ...selection.unchecked };
- if (command === "check-all") for (const key of Object.keys(unchecked)) delete unchecked[key];
- for (const id of ids) {
- const image = index.images.find((candidate) => candidate.id === id);
- if (!image) throw new Error(`${id} is not an image of this thread`);
- if (command === "uncheck") {
- if (!image.replaceable) throw new Error(`${id} cannot be unchecked yet (hosted image generation result)`);
- unchecked[image.key] = { id, at: new Date().toISOString() };
- } else if (command === "check") delete unchecked[image.key];
- else throw new Error(`unknown command ${command}`);
+function applyPlan(plan: Plan, configFile: string, envFile: string): void {
+ if (plan.configChanged) {
+ const backups = join(dataDir(), "config-backup");
+ mkdirSync(backups, { recursive: true });
+ if (existsSync(configFile)) copyFileSync(configFile, join(backups, `config.toml.${new Date().toISOString().replaceAll(":", "-")}`));
+ writeFileSync(configFile, plan.configText, "utf8");
+ }
+ if (plan.envChanged) {
+ if (plan.envText === null) rmSync(envFile, { force: true });
+ else {
+ writeFileSync(`${envFile}.cam-tmp`, plan.envText, "utf8");
+ renameSync(`${envFile}.cam-tmp`, envFile);
}
- writeSelection({ threadId, unchecked });
}
- console.log(table(index));
}
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+async function main(): Promise<void> {
+ const [command, threadId, ...ids] = process.argv.slice(2);
+ const configFile = join(codexHome(), "config.toml");
+ const envFile = join(codexHome(), ".env");
+ const readConfig = () => (existsSync(configFile) ? readFileSync(configFile, "utf8") : "");
+ const readEnv = () => (existsSync(envFile) ? readFileSync(envFile, "utf8") : null);
+ const port = Number(process.argv.includes("--port") ? process.argv[process.argv.indexOf("--port") + 1] : DEFAULT_PORT);
+
+ if (command === "install") {
+ const env = { httpProxy: persistedEnv("HTTPS_PROXY") ?? persistedEnv("HTTP_PROXY") ?? persistedEnv("ALL_PROXY"), noProxy: persistedEnv("NO_PROXY") };
+ const plan = planInstall({ configText: readConfig(), envText: readEnv(), env, port, nodePath: process.execPath, serverScript: resolve(import.meta.dirname, "plugin-server.ts") });
+ applyPlan(plan, configFile, envFile);
+ const engine = await ensureEngine({ port });
+ console.log(JSON.stringify({ command, configChanged: plan.configChanged, envChanged: plan.envChanged, notes: plan.notes, engine: engine.state, enginePid: engine.health?.pid ?? null, next: "重启 Codex 后生效" }, null, 2));
+ return;
+ }
+ if (command === "uninstall") {
+ const plan = planUninstall({ configText: readConfig(), envText: readEnv() });
+ applyPlan(plan, configFile, envFile);
+ console.log(JSON.stringify({ command, configChanged: plan.configChanged, envChanged: plan.envChanged, next: "重启 Codex 后生效;引擎会在 Codex 全部退出后自己退出" }, null, 2));
+ return;
+ }
+ if (command === "status") {
+ const config = readConfig();
+ const health = await engineHealth(port);
+ console.log(JSON.stringify({ command, proxy: proxyStatus(config), mcpServer: config.split(/\r?\n/).some((line) => line.trim() === MCP_BEGIN), dotenv: noProxyStatus(readEnv() ?? ""), engine: health ? { running: true, pid: health.pid, startedAt: health.startedAt } : { running: false }, dataDir: dataDir() }, null, 2));
+ return;
+ }
+ if (!command || !threadId) throw new Error("usage: cam.ts install [--port N] | uninstall | status | list|uncheck|check|check-all <thread id> [IMG-…]");
+ const options = { sessionsDir: join(codexHome(), "sessions") };
+ if (command === "list") console.log(table(loadPanelState(threadId, options)));
+ else if (command === "uncheck") console.log(table(applySelection(threadId, { uncheck: ids }, options)));
+ else if (command === "check") console.log(table(applySelection(threadId, { check: ids }, options)));
+ else if (command === "check-all") console.log(table(applySelection(threadId, { checkAll: true }, options)));
+ else throw new Error(`unknown command ${command}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();
diff --git a/spike/src/codexconfig.ts b/spike/src/codexconfig.ts
index 65ca2da..43aa10b 100644
--- a/spike/src/codexconfig.ts
+++ b/spike/src/codexconfig.ts
@@ -158,7 +158,7 @@ export function noProxyStatus(text: string): { managed: boolean; value: string |
}
// What the desktop app inherits: the user's variable overrides the machine's.
-function persistedEnv(name: string): string | null {
+export function persistedEnv(name: string): string | null {
if (process.platform !== "win32") return null;
for (const key of ["HKCU\\Environment", "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"]) {
try {
diff --git a/spike/src/install.test.ts b/spike/src/install.test.ts
new file mode 100644
index 0000000..1c453a7
--- /dev/null
+++ b/spike/src/install.test.ts
@@ -0,0 +1,54 @@
+// Purpose: P3-4 — installing writes every managed block (and .env only when needed); uninstalling restores both
+// files byte for byte; a conflict leaves everything untouched.
+// Input: synthetic config and .env texts; output: Node test assertions only.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { needsNoProxy, planInstall, planUninstall, SERVER_NAME } from "./install.ts";
+
+const CONFIG = 'model = "gpt-6-sol"\n\n[features]\nview_image = true\n\n[projects.\'d:\\\\work\']\ntrust_level = "trusted"\n';
+const base = { port: 17891, nodePath: "C:\\Program Files\\nodejs\\node.exe", serverScript: "D:\\cam\\plugin-server.ts" };
+const proxied = { httpProxy: "http://127.0.0.1:8888", noProxy: null };
+const direct = { httpProxy: null, noProxy: null };
+
+test(".env is needed only when an environment proxy would swallow loopback requests", () => {
+ assert.equal(needsNoProxy(proxied), true);
+ assert.equal(needsNoProxy(direct), false);
+ assert.equal(needsNoProxy({ httpProxy: "http://p:1", noProxy: "localhost,127.0.0.1,::1" }), false);
+ assert.equal(needsNoProxy({ httpProxy: "http://p:1", noProxy: "*" }), false);
+});
+
+test("install writes the proxy settings, the MCP server and, with an environment proxy, .env", () => {
+ const plan = planInstall({ ...base, configText: CONFIG, envText: null, env: proxied });
+ assert.equal(plan.configChanged, true);
+ assert.match(plan.configText, /^# >>> codex-attachment-manager: managed proxy setting/);
+ assert.match(plan.configText, /openai_base_url = "http:\/\/localhost:17891\/backend-api\/codex"/);
+ assert.match(plan.configText, /respect_system_proxy = true/);
+ assert.match(plan.configText, new RegExp(`\\[mcp_servers\\.${SERVER_NAME}\\]`));
+ assert.equal(plan.envChanged, true);
+ assert.match(plan.envText!, /NO_PROXY=localhost,127\.0\.0\.1,::1/);
+ const again = planInstall({ ...base, configText: plan.configText, envText: plan.envText, env: proxied });
+ assert.deepEqual([again.configChanged, again.envChanged], [false, false], "installing twice changes nothing");
+});
+
+test("without an environment proxy no .env is written, and an old block is cleared", () => {
+ const plan = planInstall({ ...base, configText: CONFIG, envText: null, env: direct });
+ assert.deepEqual([plan.envText, plan.envChanged], [null, false]);
+ const withOld = planInstall({ ...base, configText: CONFIG, envText: planInstall({ ...base, configText: CONFIG, envText: "KEEP=1\n", env: proxied }).envText, env: direct });
+ assert.deepEqual([withOld.envText, withOld.envChanged], ["KEEP=1\n", true]);
+});
+
+test("uninstall restores config.toml and .env byte for byte, deleting a .env that only held our block", () => {
+ for (const envText of [null, "OPENAI_API_KEY=not-a-real-key\n"]) {
+ const installed = planInstall({ ...base, configText: CONFIG, envText, env: proxied });
+ const removed = planUninstall({ configText: installed.configText, envText: installed.envText });
+ assert.equal(removed.configText, CONFIG);
+ assert.equal(removed.envText, envText);
+ }
+});
+
+test("a conflict stops the whole install before anything is written", () => {
+ const mine = 'openai_base_url = "https://example.test/v1"\n' + CONFIG;
+ assert.throws(() => planInstall({ ...base, configText: mine, envText: null, env: proxied }), /already sets openai_base_url/);
+ assert.throws(() => planInstall({ ...base, configText: CONFIG, envText: "NO_PROXY=corp\n", env: proxied }), /already sets NO_PROXY/);
+});
diff --git a/spike/src/install.ts b/spike/src/install.ts
new file mode 100644
index 0000000..29626a0
--- /dev/null
+++ b/spike/src/install.ts
@@ -0,0 +1,47 @@
+// Purpose: P3-4 — what installing and uninstalling change, as pure functions over the current file contents:
+// config.toml gets the proxy settings and the plugin's MCP server; ~/.codex/.env gets NO_PROXY only when the user's
+// environment proxy would otherwise swallow requests to this machine. Uninstall removes exactly those blocks.
+// Input: current texts and the user's persisted proxy variables. Output: next texts (envText null = delete the file).
+
+import { coversLoopback, disableMcpServer, disableProxy, enableMcpServer, enableNoProxy, enableProxy, noProxyValue } from "./codexconfig.ts";
+
+export const SERVER_NAME = "codex_attachment_manager";
+
+export type UserProxyEnv = { httpProxy: string | null; noProxy: string | null };
+export type Plan = { configText: string; configChanged: boolean; envText: string | null; envChanged: boolean; notes: string[] };
+
+// Codex's image client follows the environment proxy; without NO_PROXY for loopback it cannot reach the engine.
+export function needsNoProxy(env: UserProxyEnv): boolean {
+ return !!env.httpProxy && !coversLoopback(env.noProxy);
+}
+
+export function planInstall(input: { configText: string; envText: string | null; env: UserProxyEnv; port: number; nodePath: string; serverScript: string }): Plan {
+ const notes: string[] = [];
+ const proxied = enableProxy(input.configText, `http://localhost:${input.port}/backend-api/codex`);
+ const served = enableMcpServer(proxied.text, SERVER_NAME, input.nodePath, [input.serverScript]);
+ let envText = input.envText;
+ let envChanged = false;
+ if (needsNoProxy(input.env)) {
+ const next = enableNoProxy(input.envText ?? "", noProxyValue(input.env.noProxy));
+ envText = next.text;
+ envChanged = next.changed;
+ notes.push("写入 .env 的 NO_PROXY:环境变量里有代理,而且没有覆盖本机地址");
+ } else {
+ // A block from an earlier install is no longer needed.
+ const cleared = input.envText === null ? { text: null, changed: false } : disableProxy(input.envText);
+ envText = cleared.text;
+ envChanged = cleared.changed;
+ }
+ return { configText: served.text, configChanged: served.text !== input.configText, envText: emptyToNull(envText), envChanged, notes };
+}
+
+export function planUninstall(input: { configText: string; envText: string | null }): Plan {
+ const config = disableMcpServer(disableProxy(input.configText).text);
+ const env = input.envText === null ? { text: null, changed: false } : disableProxy(input.envText);
+ return { configText: config.text, configChanged: config.text !== input.configText, envText: emptyToNull(env.text), envChanged: env.changed, notes: [] };
+}
+
+// A .env that held nothing but our block is removed rather than left empty.
+function emptyToNull(text: string | null): string | null {
+ return text === null || !text.replace(/^/, "").trim() ? null : text;
+}
diff --git a/spike/src/panel-state.test.ts b/spike/src/panel-state.test.ts
new file mode 100644
index 0000000..8e0d718
--- /dev/null
+++ b/spike/src/panel-state.test.ts
@@ -0,0 +1,53 @@
+// Purpose: P3-3 — the panel's data: image states, the ids the model asked for, check/uncheck, and thumbnails.
+// Input: synthetic rollouts in temporary folders; output: Node test assertions only.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { decodePng } from "./png.ts";
+import { applySelection, loadPanelState, requestedIds, thumbnailFor } from "./panel-state.ts";
+import { assistant, sampleSessions, THREAD, turn } from "./testfixtures.ts";
+import { shrink } from "./thumbnail.ts";
+
+const records = (text: string) => text.trim().split("\n").map((raw) => JSON.parse(raw));
+
+test("the ids the model asked for come from its latest reply only", () => {
+ assert.deepEqual(requestedIds(records(turn("t1") + assistant("需要 IMG-001", "t1") + turn("t2") + assistant("好的,需要 “IMG-004” 和 IMG-002。", "t2"))), ["IMG-004", "IMG-002"]);
+ assert.deepEqual(requestedIds(records(turn("t1") + assistant("need IMG-007 to answer", "t1") + turn("t2"))), ["IMG-007"], "a turn still running falls back to the one before");
+ assert.deepEqual(requestedIds(records(turn("t1") + assistant("IMG-003 与 IMG-002 相同", "t1"))), [], "mentioning an id is not asking for it");
+});
+
+test("panel state lists every image with checked, same-content and requested flags", () => {
+ const options = sampleSessions();
+ const state = loadPanelState(THREAD, options);
+ assert.deepEqual(state.images.map((image) => [image.id, image.name, image.checked, image.sameAs, image.requested]), [
+ ["IMG-001", "a.png", true, [], true],
+ ["IMG-002", "b.png", true, ["IMG-003"], false],
+ ["IMG-003", "b-copy.png", true, ["IMG-002"], false],
+ ]);
+ assert.deepEqual(state.requested, ["IMG-001"]);
+ assert.equal(state.totals.checkedBytes, state.totals.allBytes);
+ assert.equal(state.lastRequest, null);
+});
+
+test("check and uncheck are kept per thread and validated", () => {
+ const options = sampleSessions();
+ let state = applySelection(THREAD, { uncheck: ["IMG-001", "IMG-003"] }, options);
+ assert.deepEqual(state.images.filter((image) => !image.checked).map((image) => image.id), ["IMG-001", "IMG-003"]);
+ assert.equal(state.totals.unchecked, 2);
+ assert.ok(state.totals.checkedBytes < state.totals.allBytes);
+ state = applySelection(THREAD, { check: ["IMG-001"] }, options);
+ assert.deepEqual(loadPanelState(THREAD, options).images.filter((image) => !image.checked).map((image) => image.id), ["IMG-003"]);
+ state = applySelection(THREAD, { checkAll: true }, options);
+ assert.equal(state.totals.unchecked, 0);
+ assert.throws(() => applySelection(THREAD, { uncheck: ["IMG-099"] }, options), /not an image of this thread/);
+});
+
+test("thumbnails keep the aspect ratio and fit the requested size", () => {
+ const options = sampleSessions();
+ const thumb = thumbnailFor(THREAD, "IMG-001", 32, options);
+ assert.ok(thumb.dataUrl?.startsWith("data:image/png;base64,"));
+ const decoded = decodePng(Buffer.from(thumb.dataUrl!.split(",")[1], "base64"));
+ assert.deepEqual([decoded.width, decoded.height], [32, 16]);
+ const averaged = shrink(2, 1, Buffer.from([0, 0, 0, 255, 200, 100, 50, 255]), 1);
+ assert.deepEqual([...averaged.pixels], [100, 50, 25, 255], "a box filter averages the covered pixels");
+});
diff --git a/spike/src/panel-state.ts b/spike/src/panel-state.ts
new file mode 100644
index 0000000..8f93960
--- /dev/null
+++ b/spike/src/panel-state.ts
@@ -0,0 +1,123 @@
+// Purpose: P3-3 — what the panel shows for one thread: every image occurrence with its state, the ids the model asked
+// for in its latest reply, and the engine's statistics of the latest request. Also applies check/uncheck actions.
+// Input: thread id, the sessions directory (rollouts are only read) and the tool's data directory.
+// Output: PanelState as plain JSON; selection changes are written to <data dir>/selection/.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { dataDir, requestStatsDirOf, selectionDirOf } from "./paths.ts";
+import { readSelection, writeSelection } from "./selection.ts";
+import { buildIndex, imageData, readThreadHistory, type IndexedImage, type ThreadIndex } from "./thread-index.ts";
+import { pngThumbnail } from "./thumbnail.ts";
+
+type Json = Record<string, any>;
+type Record_ = { type: string; payload: Json };
+export type PanelImage = {
+ id: string; kind: string; name: string | null; label: string | null; turn: number | null;
+ width: number | null; height: number | null; bytes: number;
+ sameAs: string[]; checked: boolean; replaceable: boolean; requested: boolean;
+};
+export type PanelState = {
+ threadId: string; turns: number; images: PanelImage[]; requested: string[];
+ totals: { images: number; unchecked: number; checkedBytes: number; allBytes: number };
+ lastRequest: Json | null;
+};
+export type PanelOptions = { sessionsDir: string; dataRoot?: string };
+
+// "需要 IMG-004" or a list right after it ("需要 IMG-004、IMG-002 和 IMG-007"); a full stop ends the list.
+const ASKED = [
+ /需要((?:\s*[“"'「]?\s*IMG-\d{3,}\s*[”"'」]?\s*(?:[、,,/]|以及|和|与|及)?)+)/g,
+ /\bneeds?((?:\s*IMG-\d{3,}\s*(?:,|and)?)+)/gi,
+];
+
+// Ids the model asked for ("需要 IMG-003") in its latest reply; a turn still running falls back to the one before.
+export function requestedIds(history: Record_[]): string[] {
+ let current: string[] = [];
+ let previous: string[] = [];
+ for (const record of history) {
+ if (record.type === "event_msg" && record.payload.type === "task_started") {
+ if (current.length) previous = current;
+ current = [];
+ }
+ if (record.type === "response_item" && record.payload.type === "message" && record.payload.role === "assistant") {
+ for (const part of record.payload.content ?? []) if (typeof part?.text === "string") current.push(part.text);
+ }
+ }
+ const ids = new Set<string>();
+ for (const text of current.length ? current : previous) {
+ for (const pattern of ASKED) for (const match of text.matchAll(pattern)) for (const id of match[1].matchAll(/IMG-\d{3,}/gi)) ids.add(id[0].toUpperCase());
+ }
+ return [...ids];
+}
+
+export function sameContent(index: ThreadIndex, image: IndexedImage): string[] {
+ return index.images
+ .filter((other) => other !== image && (other.contentId === image.contentId || (image.pixelSha256 !== null && other.pixelSha256 === image.pixelSha256)))
+ .map((other) => other.id);
+}
+
+export function panelState(threadId: string, history: Record_[], index: ThreadIndex, unchecked: Set<string>, lastRequest: Json | null): PanelState {
+ const requested = requestedIds(history);
+ const images = index.images.map((image): PanelImage => ({
+ id: image.id, kind: image.kind, name: image.name, label: image.label, turn: image.turn,
+ width: image.width, height: image.height, bytes: image.bytes,
+ sameAs: sameContent(index, image),
+ checked: !unchecked.has(image.key),
+ replaceable: image.replaceable,
+ requested: requested.includes(image.id),
+ }));
+ return {
+ threadId, turns: index.turns, images, requested,
+ totals: {
+ images: images.length,
+ unchecked: images.filter((image) => !image.checked).length,
+ checkedBytes: images.filter((image) => image.checked).reduce((sum, image) => sum + image.bytes, 0),
+ allBytes: images.reduce((sum, image) => sum + image.bytes, 0),
+ },
+ lastRequest,
+ };
+}
+
+function load(threadId: string, options: PanelOptions) {
+ const root = options.dataRoot ?? dataDir();
+ const history = readThreadHistory(options.sessionsDir, threadId);
+ const index = buildIndex(threadId, history);
+ const selection = readSelection(threadId, selectionDirOf(root));
+ const statsFile = join(requestStatsDirOf(root), `${threadId}.json`);
+ const lastRequest = existsSync(statsFile) ? JSON.parse(readFileSync(statsFile, "utf8")) : null;
+ return { root, history, index, selection, lastRequest };
+}
+
+export function loadPanelState(threadId: string, options: PanelOptions): PanelState {
+ const { history, index, selection, lastRequest } = load(threadId, options);
+ return panelState(threadId, history, index, new Set(Object.keys(selection.unchecked)), lastRequest);
+}
+
+export function applySelection(threadId: string, change: { uncheck?: string[]; check?: string[]; checkAll?: boolean }, options: PanelOptions): PanelState {
+ const { root, history, index, selection, lastRequest } = load(threadId, options);
+ const unchecked = change.checkAll ? {} : { ...selection.unchecked };
+ const byId = new Map(index.images.map((image) => [image.id, image]));
+ for (const id of change.uncheck ?? []) {
+ const image = byId.get(id);
+ if (!image) throw new Error(`${id} is not an image of this thread`);
+ if (!image.replaceable) throw new Error(`${id} cannot be unchecked (hosted image generation result)`);
+ unchecked[image.key] = { id, at: new Date().toISOString() };
+ }
+ for (const id of change.check ?? []) {
+ const image = byId.get(id);
+ if (!image) throw new Error(`${id} is not an image of this thread`);
+ delete unchecked[image.key];
+ }
+ writeSelection({ threadId, unchecked }, selectionDirOf(root));
+ return panelState(threadId, history, index, new Set(Object.keys(unchecked)), lastRequest);
+}
+
+export function thumbnailFor(threadId: string, id: string, maxSide: number, options: PanelOptions): { id: string; dataUrl: string | null } {
+ const history = readThreadHistory(options.sessionsDir, threadId);
+ const index = buildIndex(threadId, history);
+ const image = index.images.find((candidate) => candidate.id === id);
+ if (!image) throw new Error(`${id} is not an image of this thread`);
+ const items = history.filter((record) => record.type === "response_item").map((record) => record.payload);
+ const data = imageData(items, image);
+ return { id, dataUrl: data && image.mime === "image/png" ? pngThumbnail(data, maxSide) : null };
+}
diff --git a/spike/src/plugin-server.test.ts b/spike/src/plugin-server.test.ts
new file mode 100644
index 0000000..01747c7
--- /dev/null
+++ b/spike/src/plugin-server.test.ts
@@ -0,0 +1,78 @@
+// Purpose: P3-3 — the plugin's MCP server: thread resolution, the rule that only the user may check or uncheck,
+// thumbnails kept out of model-visible content, and a full stdio session (engine supervision switched off).
+// Input: synthetic rollouts in temporary folders; output: Node test assertions only.
+
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { callTool, fromModel, threadOf } from "./plugin-server.ts";
+import { sampleSessions, THREAD } from "./testfixtures.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const modelMeta = { callId: "exec-1", "x-codex-turn-metadata": { thread_id: THREAD, turn_id: "t9" } };
+const panelMeta = { thread_id: THREAD, threadId: THREAD, progressToken: 3 };
+
+test("the thread comes from the arguments, the panel's meta, or the model's turn metadata", () => {
+ assert.equal(threadOf({ threadId: "x" }, panelMeta), "x");
+ assert.equal(threadOf({}, panelMeta), THREAD);
+ assert.equal(threadOf({}, modelMeta), THREAD);
+ assert.equal(threadOf({}, undefined), null);
+ assert.equal(fromModel(modelMeta), true);
+ assert.equal(fromModel(panelMeta), false);
+});
+
+test("the model can read the panel state but never change the selection", () => {
+ const { sessionsDir, dataRoot } = sampleSessions();
+ process.env.CAM_DATA_DIR = dataRoot;
+ try {
+ assert.equal(callTool("cam_panel_state", {}, modelMeta, sessionsDir).structuredContent.totals.images, 3);
+ assert.throws(() => callTool("cam_set_selection", { uncheck: ["IMG-001"] }, modelMeta, sessionsDir), /只有用户能勾选或取消/);
+ const done = callTool("cam_set_selection", { uncheck: ["IMG-001"] }, panelMeta, sessionsDir);
+ assert.equal(done.structuredContent.totals.unchecked, 1);
+ } finally {
+ delete process.env.CAM_DATA_DIR;
+ }
+});
+
+test("thumbnail data stays in _meta, out of the model-visible content", () => {
+ const { sessionsDir, dataRoot } = sampleSessions();
+ process.env.CAM_DATA_DIR = dataRoot;
+ try {
+ const result = callTool("cam_thumbnail", { id: "IMG-002" }, panelMeta, sessionsDir);
+ assert.match(result._meta.dataUrl, /^data:image\/png;base64,/);
+ assert.doesNotMatch(JSON.stringify(result.content) + JSON.stringify(result.structuredContent), /base64/);
+ } finally {
+ delete process.env.CAM_DATA_DIR;
+ }
+});
+
+test("a stdio session lists the tools and answers calls", async () => {
+ const { sessionsDir, dataRoot } = sampleSessions();
+ const child = spawn(process.execPath, [join(here, "plugin-server.ts")], { env: { ...process.env, CAM_NO_ENGINE: "1", CAM_DATA_DIR: dataRoot, CODEX_HOME: dirname(sessionsDir) }, stdio: ["pipe", "pipe", "inherit"] });
+ const replies: Record<number, any> = {};
+ let buffer = "";
+ child.stdout.on("data", (chunk: Buffer) => {
+ buffer += chunk.toString("utf8");
+ for (let end = buffer.indexOf("\n"); end >= 0; end = buffer.indexOf("\n")) {
+ const message = JSON.parse(buffer.slice(0, end));
+ replies[message.id] = message;
+ buffer = buffer.slice(end + 1);
+ }
+ });
+ const send = (message: object) => child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+ send({ id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "test" } } });
+ send({ method: "notifications/initialized" });
+ send({ id: 2, method: "tools/list" });
+ send({ id: 3, method: "tools/call", params: { name: "cam_panel_state", arguments: {}, _meta: panelMeta } });
+ send({ id: 4, method: "tools/call", params: { name: "cam_set_selection", arguments: { uncheck: ["IMG-002"] }, _meta: modelMeta } });
+ await new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => reject(new Error("no replies")), 10_000);
+ const check = setInterval(() => { if (replies[4]) { clearInterval(check); clearTimeout(timer); resolve(); } }, 20);
+ });
+ child.stdin.end();
+ assert.deepEqual(replies[2].result.tools.map((tool: any) => tool.name), ["cam_panel_state", "cam_set_selection", "cam_thumbnail"]);
+ assert.equal(replies[3].result.structuredContent.images.length, 3);
+ assert.equal(replies[4].result.isError, true);
+});
diff --git a/spike/src/plugin-server.ts b/spike/src/plugin-server.ts
new file mode 100644
index 0000000..1c7f321
--- /dev/null
+++ b/spike/src/plugin-server.ts
@@ -0,0 +1,124 @@
+// Purpose: P3-3 — the plugin's MCP server, started by Codex for each session. It keeps the engine (local proxy)
+// running — at start and every few seconds, so a crashed engine comes back — and serves the panel's data tools:
+// the thread's images and their state, check/uncheck, and thumbnails.
+// Only the user may check or uncheck: calls the model makes (they carry Codex's turn metadata) are refused.
+// Input: MCP JSON-RPC over stdio. Env: CAM_ENGINE_PORT (default 17891), CAM_NO_ENGINE=1 (tests), CAM_DATA_DIR.
+// Output: tool results; <data dir>/plugin-server.jsonl (events and counts only, no conversation content).
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { codexHome } from "./codexconfig.ts";
+import { DEFAULT_PORT, ensureEngine } from "./engine.ts";
+import { applySelection, loadPanelState, thumbnailFor, type PanelState } from "./panel-state.ts";
+import { dataDir } from "./paths.ts";
+
+type Json = Record<string, any>;
+const APP_ONLY = { ui: { visibility: ["app"] } };
+const threadArg = { threadId: { type: "string", description: "任务 ID;面板调用时由 Codex 自动带上。" } };
+
+export const TOOLS = [
+ {
+ name: "cam_panel_state",
+ title: "素材面板:读取",
+ description: "素材面板内部使用:读取当前任务的图片列表和勾选状态。模型不需要调用。",
+ inputSchema: { type: "object", properties: { ...threadArg } },
+ _meta: APP_ONLY,
+ },
+ {
+ name: "cam_set_selection",
+ title: "素材面板:勾选",
+ description: "素材面板内部使用:勾选或取消图片。只有用户能操作,模型调用会被拒绝。",
+ inputSchema: { type: "object", properties: { ...threadArg, uncheck: { type: "array", items: { type: "string" } }, check: { type: "array", items: { type: "string" } }, checkAll: { type: "boolean" } } },
+ _meta: APP_ONLY,
+ },
+ {
+ name: "cam_thumbnail",
+ title: "素材面板:缩略图",
+ description: "素材面板内部使用:读取一张图片的缩略图。模型不需要调用。",
+ inputSchema: { type: "object", properties: { ...threadArg, id: { type: "string" }, maxSide: { type: "number" } }, required: ["id"] },
+ _meta: APP_ONLY,
+ },
+];
+
+function log(entry: Json): void {
+ const root = dataDir();
+ mkdirSync(root, { recursive: true });
+ appendFileSync(join(root, "plugin-server.jsonl"), `${JSON.stringify({ at: new Date().toISOString(), pid: process.pid, ...entry })}\n`);
+}
+
+// Codex adds turn metadata to calls the model makes; the panel's own calls carry only the thread id.
+export function fromModel(meta: Json | undefined): boolean {
+ return !!meta && meta["x-codex-turn-metadata"] !== undefined;
+}
+
+export function threadOf(args: Json, meta: Json | undefined): string | null {
+ return args.threadId ?? meta?.threadId ?? meta?.thread_id ?? meta?.["x-codex-turn-metadata"]?.thread_id ?? null;
+}
+
+const summary = (state: PanelState) => `共 ${state.totals.images} 张图,取消了 ${state.totals.unchecked} 张。`;
+
+export function callTool(name: string, args: Json, meta: Json | undefined, sessionsDir = join(codexHome(), "sessions")): Json {
+ const threadId = threadOf(args, meta);
+ if (!threadId) throw new Error("不知道是哪个任务:缺少 threadId");
+ const options = { sessionsDir };
+ if (name === "cam_panel_state") {
+ const state = loadPanelState(threadId, options);
+ return { content: [{ type: "text", text: summary(state) }], structuredContent: state };
+ }
+ if (name === "cam_set_selection") {
+ if (fromModel(meta)) throw new Error("只有用户能勾选或取消图片;需要某张图时,请回复“需要 IMG-xxx”。");
+ const state = applySelection(threadId, { uncheck: args.uncheck, check: args.check, checkAll: args.checkAll }, options);
+ return { content: [{ type: "text", text: summary(state) }], structuredContent: state };
+ }
+ if (name === "cam_thumbnail") {
+ const thumb = thumbnailFor(threadId, String(args.id), Number(args.maxSide ?? 96), options);
+ // The image data goes in _meta, which only the panel sees.
+ return { content: [{ type: "text", text: thumb.dataUrl ? "ok" : "无缩略图" }], structuredContent: { id: thumb.id, available: thumb.dataUrl !== null }, _meta: { dataUrl: thumb.dataUrl } };
+ }
+ throw new Error(`unknown tool ${name}`);
+}
+
+function main(): void {
+ const send = (message: Json) => process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+ const port = Number(process.env.CAM_ENGINE_PORT ?? DEFAULT_PORT);
+ let engineState = "";
+ const supervise = async () => {
+ if (process.env.CAM_NO_ENGINE === "1") return;
+ const result = await ensureEngine({ port });
+ if (result.state !== "running" || engineState !== "running") log({ event: "engine", state: result.state, enginePid: result.health?.pid ?? null });
+ engineState = result.state;
+ };
+ log({ event: "start", ppid: process.ppid });
+ // Codex starts several instances at once; a little jitter keeps them from racing to start the engine.
+ setTimeout(supervise, Math.floor(Math.random() * 400));
+ setInterval(supervise, 10_000);
+ process.stdin.on("close", () => { log({ event: "stdin-closed" }); process.exit(0); });
+ createInterface({ input: process.stdin, crlfDelay: Infinity }).on("line", (line) => {
+ if (!line.trim()) return;
+ let message: Json;
+ try { message = JSON.parse(line); } catch { return; }
+ const { id, method, params = {} } = message;
+ if (method === "initialize") {
+ send({ id, result: { protocolVersion: params.protocolVersion ?? "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "codex-attachment-manager", version: "0.1.0" } } });
+ } else if (method === "tools/list") {
+ send({ id, result: { tools: TOOLS } });
+ } else if (method === "tools/call") {
+ try {
+ const result = callTool(params.name, params.arguments ?? {}, params._meta);
+ log({ event: "tools/call", name: params.name, fromModel: fromModel(params._meta) });
+ send({ id, result });
+ } catch (error) {
+ log({ event: "tools/call", name: params.name, fromModel: fromModel(params._meta), error: String(error) });
+ send({ id, result: { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] } });
+ }
+ } else if (method === "ping") {
+ send({ id, result: {} });
+ } else if (id !== undefined) {
+ send({ id, error: { code: -32601, message: `unsupported: ${method}` } });
+ }
+ });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
diff --git a/spike/src/testfixtures.ts b/spike/src/testfixtures.ts
new file mode 100644
index 0000000..fe2c5ca
--- /dev/null
+++ b/spike/src/testfixtures.ts
@@ -0,0 +1,38 @@
+// Purpose: synthetic rollouts for unit tests — a temporary sessions folder with one thread whose history holds
+// uploads, a viewed image and assistant replies. No real session data.
+// Input: record builders. Output: file paths and ids to use in assertions.
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { png } from "./testkit.ts";
+
+export const THREAD = "01a0d301-0000-7000-8000-00000000abcd";
+export const red = png(64, 32, (x, y) => [230, (x * 7) % 256, (y * 5) % 256]);
+export const blue = png(8, 8, () => [0, 0, 255]);
+const url = (bytes: Buffer) => `data:image/png;base64,${bytes.toString("base64")}`;
+
+export const line = (type: string, payload: Record<string, any>) => `${JSON.stringify({ timestamp: "2026-09-24T10:00:00Z", type, payload })}\n`;
+export const turn = (id: string) => line("event_msg", { type: "task_started", turn_id: id });
+export const assistant = (text: string, turnId: string) => line("response_item", { type: "message", role: "assistant", content: [{ type: "output_text", text }], internal_chat_message_metadata_passthrough: { turn_id: turnId } });
+export const upload = (id: string, turnId: string, images: Array<[string, Buffer]>) => line("response_item", {
+ type: "message", id, role: "user",
+ content: images.flatMap(([name, bytes], i) => [
+ { type: "input_text", text: `<image name=[Image #${i + 1}] path="C:\\w\\${name}">` },
+ { type: "input_image", image_url: url(bytes) },
+ { type: "input_text", text: "</image>" },
+ ]),
+ internal_chat_message_metadata_passthrough: { turn_id: turnId },
+});
+
+// Turn 1 uploads a.png (red), b.png and b-copy.png (both blue); turn 2 is the model asking for IMG-001.
+export function sampleSessions(extra = ""): { sessionsDir: string; dataRoot: string } {
+ const root = mkdtempSync(join(tmpdir(), "cam-fixture-"));
+ const day = join(root, "sessions", "2026", "09", "24");
+ mkdirSync(day, { recursive: true });
+ writeFileSync(join(day, `rollout-2026-09-24T10-00-00-${THREAD}.jsonl`),
+ line("session_meta", { id: THREAD }) +
+ turn("t1") + upload("msg_1", "t1", [["a.png", red], ["b.png", blue], ["b-copy.png", blue]]) + assistant("收到", "t1") +
+ turn("t2") + assistant("需要 IMG-001。IMG-003 与 IMG-002 相同。", "t2") + extra);
+ return { sessionsDir: join(root, "sessions"), dataRoot: join(root, "data") };
+}
diff --git a/spike/src/thumbnail.ts b/spike/src/thumbnail.ts
new file mode 100644
index 0000000..16bbb68
--- /dev/null
+++ b/spike/src/thumbnail.ts
@@ -0,0 +1,69 @@
+// Purpose: P3-3 — small PNG thumbnails for the panel, made from the inline images in the rollout. PNG only for now;
+// other formats return null and the panel shows an icon instead.
+// Input: base64 image data and a maximum side length. Output: a PNG data URL, cached per content and size.
+
+import { createHash } from "node:crypto";
+import zlib from "node:zlib";
+import { decodePng } from "./png.ts";
+
+const cache = new Map<string, string | null>();
+
+// Box filter: every target pixel is the average of the source block it covers.
+export function shrink(width: number, height: number, rgba: Buffer, maxSide: number): { width: number; height: number; pixels: Buffer } {
+ const scale = Math.min(1, maxSide / Math.max(width, height));
+ const tw = Math.max(1, Math.round(width * scale));
+ const th = Math.max(1, Math.round(height * scale));
+ const out = Buffer.alloc(tw * th * 4);
+ for (let ty = 0; ty < th; ty++) {
+ const y0 = Math.floor((ty * height) / th);
+ const y1 = Math.max(y0 + 1, Math.floor(((ty + 1) * height) / th));
+ for (let tx = 0; tx < tw; tx++) {
+ const x0 = Math.floor((tx * width) / tw);
+ const x1 = Math.max(x0 + 1, Math.floor(((tx + 1) * width) / tw));
+ const sum = [0, 0, 0, 0];
+ for (let y = y0; y < y1; y++) {
+ for (let x = x0; x < x1; x++) {
+ const source = (y * width + x) * 4;
+ for (let c = 0; c < 4; c++) sum[c] += rgba[source + c];
+ }
+ }
+ const count = (y1 - y0) * (x1 - x0);
+ for (let c = 0; c < 4; c++) out[(ty * tw + tx) * 4 + c] = Math.round(sum[c] / count);
+ }
+ }
+ return { width: tw, height: th, pixels: out };
+}
+
+export function encodePngRgba(width: number, height: number, rgba: Buffer): Buffer {
+ const stride = width * 4;
+ const raw = Buffer.alloc((stride + 1) * height);
+ for (let y = 0; y < height; y++) rgba.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+ const chunk = (type: string, data: Buffer) => {
+ const length = Buffer.alloc(4);
+ length.writeUInt32BE(data.length);
+ const crc = Buffer.alloc(4);
+ crc.writeUInt32BE(zlib.crc32(Buffer.concat([Buffer.from(type, "ascii"), data])));
+ return Buffer.concat([length, Buffer.from(type, "ascii"), data, crc]);
+ };
+ const header = Buffer.alloc(13);
+ header.writeUInt32BE(width, 0);
+ header.writeUInt32BE(height, 4);
+ header[8] = 8;
+ header[9] = 6;
+ return Buffer.concat([Buffer.from("89504e470d0a1a0a", "hex"), chunk("IHDR", header), chunk("IDAT", zlib.deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}
+
+export function pngThumbnail(base64: string, maxSide = 96): string | null {
+ const key = `${createHash("sha256").update(base64).digest("hex")}:${maxSide}`;
+ if (cache.has(key)) return cache.get(key)!;
+ let result: string | null = null;
+ try {
+ const png = decodePng(Buffer.from(base64, "base64"));
+ const small = shrink(png.width, png.height, png.pixels, maxSide);
+ result = `data:image/png;base64,${encodePngRgba(small.width, small.height, small.pixels).toString("base64")}`;
+ } catch {
+ result = null;
+ }
+ cache.set(key, result);
+ return result;
+}