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.
TypeScript ai-agentsclaude-codeclaude-code-plugincodexcodex-plugincontext-managementdeveloper-toolsimage-generationmcpmultimodal
feat(spike): P3-3 插件服务与面板数据、P3-4 一键安装和恢复
chipfighterd394adb60aa9
diff --git a/spike/src/cam.ts b/spike/src/cam.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}