aipic-mcp-stdio 1.0.1 → 1.1.0

package/index.js

@@ -0,0 +1,588 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 百度网盘 AI 修图 MCP —— stdio ↔ 本机 HTTP 代理。
+ *
+ * 为什么需要这一层：修图客户端的 MCP server 活在它自己的 Electron 主进程里（依赖 koffi
+ * 加载的 libaipic 句柄、passport 登录态、切空间要给渲染进程发 IPC），不可能被库库 spawn
+ * 成子进程。所以这里由库库引擎 spawn 一个瘦代理，把换行分隔的 JSON-RPC 转成对
+ * 127.0.0.1 的 HTTP 调用；凭据每次从客户端写的 endpoint 文件现读，天然跟着客户端重启
+ * 轮换，不像静态 HTTP 配置那样会过期。
+ *
+ * 几条硬约束（都是实测踩过的）：
+ *   - stdout 被协议独占，所有日志只能走 stderr，否则破坏帧
+ *   - 无 id 的通知（notifications/*）一个字节都不能回
+ *   - 并发响应必须整行原子写，否则两条响应会交织成坏帧
+ *   - 必须比引擎的 90s 调用超时先超时，见 tool-policy.js 的说明
+ */
+
+const http = require('node:http');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const policy = require('./tool-policy');
+
+const PROTOCOL_VERSION = '2025-06-18';
+const SERVER_NAME = 'aipic-mcp-stdio';
+const SERVER_VERSION = '1.1.0';
+const ENDPOINT_FILENAME = 'aipic-mcp-endpoint.json';
+/** 客户端 productName（electron-builder.yml），userData 目录名即此值 */
+const PRODUCT_NAME = 'NetdiskAIPhoto';
+
+/** 自定义 JSON-RPC 错误码（-32000 段为实现自定义） */
+const ERR = {
+    CLIENT_NOT_RUNNING: -32001,
+    ENDPOINT_MALFORMED: -32002,
+    UNAUTHORIZED: -32003,
+    CONFIRMATION_REQUIRED: -32004,
+    UPSTREAM_FAILED: -32005,
+    BATCH_TOO_LARGE: -32006,
+    CLIENT_CRASHED: -32007,
+};
+
+/**
+ * 代理自带的客户端状态探测工具。它是**本地应答**的：不进 tool-policy 分级名单、
+ * 不转发给客户端，因此在客户端没起时也能调用，让 AI 拿到诊断转告用户。
+ */
+const STATUS_TOOL_NAME = 'aipic_client_status';
+const STATUS_TOOL = {
+    name: STATUS_TOOL_NAME,
+    description:
+        '探测百度网盘AI修图客户端是否在运行。' +
+        '当其他工具报「客户端未在运行 / 可能已崩溃」时，可调用本工具获取诊断与操作建议。',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+};
+
+function log(...args) {
+    process.stderr.write(`[aipic-stdio] ${args.join(' ')}\n`);
+}
+
+/**
+ * endpoint 文件路径。客户端写在 app.getPath('userData')，各平台展开如下；
+ * 允许用 AIPIC_MCP_ENDPOINT_FILE 覆盖（调试 / 多实例）。
+ */
+function endpointPath() {
+    if (process.env.AIPIC_MCP_ENDPOINT_FILE) {
+        return process.env.AIPIC_MCP_ENDPOINT_FILE;
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', PRODUCT_NAME, ENDPOINT_FILENAME);
+    }
+    if (process.platform === 'win32') {
+        const base = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(base, PRODUCT_NAME, ENDPOINT_FILENAME);
+    }
+    return path.join(os.homedir(), '.config', PRODUCT_NAME, ENDPOINT_FILENAME);
+}
+
+/**
+ * 尝试读 endpoint 文件：文件不存在返回 null（客户端没起/没装），
+ * 格式坏抛带 rpcCode=ENDPOINT_MALFORMED 的错误。
+ */
+function tryReadEndpoint() {
+    let raw;
+    try {
+        raw = fs.readFileSync(endpointPath(), 'utf-8');
+    } catch (e) {
+        return null;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    } catch (e) {
+        const err = new Error('endpoint 文件不是合法 JSON，客户端版本可能过旧或文件被改坏');
+        err.rpcCode = ERR.ENDPOINT_MALFORMED;
+        throw err;
+    }
+    const { host, port, path: rpcPath, token } = json || {};
+    if (
+        typeof host !== 'string' ||
+        typeof port !== 'number' ||
+        typeof rpcPath !== 'string' ||
+        typeof token !== 'string'
+    ) {
+        const err = new Error('endpoint 文件字段缺失或类型不对');
+        err.rpcCode = ERR.ENDPOINT_MALFORMED;
+        throw err;
+    }
+    return { host, port, path: rpcPath, token };
+}
+
+/** 读 endpoint；文件不存在时抛 CLIENT_NOT_RUNNING（给 forward 用） */
+function readEndpoint() {
+    const ep = tryReadEndpoint();
+    if (!ep) {
+        const err = new Error('百度网盘AI修图客户端未在运行，请安装并启动客户端后重试');
+        err.rpcCode = ERR.CLIENT_NOT_RUNNING;
+        throw err;
+    }
+    return ep;
+}
+
+/** 单次 HTTP POST；只负责传输，不解释业务语义 */
+function post(ep, body, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const payload = Buffer.from(JSON.stringify(body), 'utf-8');
+        const req = http.request(
+            {
+                host: ep.host,
+                port: ep.port,
+                path: ep.path,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': payload.length,
+                    Accept: 'application/json, text/event-stream',
+                    Authorization: `Bearer ${ep.token}`,
+                },
+                timeout: timeoutMs,
+            },
+            res => {
+                const chunks = [];
+                res.on('data', c => chunks.push(c));
+                res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf-8') }));
+            }
+        );
+        req.on('timeout', () => req.destroy(new Error(`UPSTREAM_TIMEOUT:${timeoutMs}ms`)));
+        req.on('error', reject);
+        req.end(payload);
+    });
+}
+
+/**
+ * 解析响应体。当前客户端只回 JSON，但不假设 content-type：MCP 规范允许
+ * text/event-stream，这里顺手兼容，避免客户端将来开 SSE 时代理整条链路失效。
+ */
+function parseBody(text) {
+    const trimmed = (text || '').trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        return JSON.parse(trimmed);
+    }
+    const dataLines = trimmed
+        .split('\n')
+        .filter(line => line.startsWith('data:'))
+        .map(line => line.slice(5).trim())
+        .filter(Boolean);
+    if (!dataLines.length) {
+        throw new Error(`上游返回非 JSON：${trimmed.slice(0, 200)}`);
+    }
+    return JSON.parse(dataLines.join(''));
+}
+
+/**
+ * 带 401 重试的转发。token 每次客户端启动都会轮换，常驻的代理进程必须能自愈；
+ * 但**只有 token 确实变了才重试一次**——没变还 401 说明是别的问题，继续重试只是空转。
+ */
+async function forward(body, timeoutMs) {
+    let ep = readEndpoint();
+    let res;
+    try {
+        res = await post(ep, body, timeoutMs);
+    } catch (e) {
+        throw wrapConnError(e);
+    }
+    if (res.status === 401) {
+        const fresh = readEndpoint();
+        if (fresh.token === ep.token) {
+            const err = new Error('带 endpoint 文件里的 token 仍被客户端判 401，且 token 未变化');
+            err.rpcCode = ERR.UNAUTHORIZED;
+            throw err;
+        }
+        log('token 已轮换，重试一次');
+        ep = fresh;
+        try {
+            res = await post(ep, body, timeoutMs);
+        } catch (e) {
+            throw wrapConnError(e);
+        }
+    }
+    if (res.status === 401) {
+        const err = new Error('重读 endpoint 后仍然 401');
+        err.rpcCode = ERR.UNAUTHORIZED;
+        throw err;
+    }
+    if (res.status !== 200) {
+        // 只记状态码与长度：body 内容完全由上游决定，可能带业务数据，没必要进日志
+        const err = new Error(`上游 HTTP ${res.status}（body ${res.body.length} bytes）`);
+        err.rpcCode = ERR.UPSTREAM_FAILED;
+        throw err;
+    }
+    return parseBody(res.body);
+}
+
+/**
+ * 把网络层「连不上」的失败翻译成客户端崩溃的可操作提示。
+ * 只收「端口没监听 / 连接被掐断」这类明确信号；超时等其它网络错误原样放行，
+ * 让上层继续按 UPSTREAM_FAILED 处理（超时可能是慢操作，不能武断归因为崩溃）。
+ */
+function wrapConnError(e) {
+    const code = e && e.code;
+    if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EPIPE') {
+        const err = new Error('百度网盘AI修图客户端可能已崩溃或异常退出，请重启客户端后重试');
+        err.rpcCode = ERR.CLIENT_CRASHED;
+        return err;
+    }
+    return e;
+}
+
+/**
+ * 探测客户端状态，分三类：
+ *   - not_running：endpoint 文件不存在（没装 / 没启动 / 正常退出），统一提示安装并启动；
+ *   - crashed：endpoint 文件在，但端口连不上（崩溃 / 异常退出残留），提示重启；
+ *   - running：端口有 HTTP 应答。
+ * 只在本地做（读文件 + 短超时探端口），不触发任何业务。
+ */
+const PROBE_TIMEOUT_MS = 2000;
+
+async function probeClient() {
+    let ep;
+    try {
+        ep = tryReadEndpoint();
+    } catch (e) {
+        return {
+            state: 'crashed',
+            hint: '客户端 endpoint 文件损坏（版本可能过旧或被改动），请重启或重装客户端',
+        };
+    }
+    if (!ep) {
+        return {
+            state: 'not_running',
+            hint: '百度网盘AI修图客户端未在运行，请安装并启动客户端后重试',
+        };
+    }
+    try {
+        // 用不存在的 method 探活：只要端口有 HTTP 应答就说明客户端在跑，body 忽略
+        await post(ep, { jsonrpc: '2.0', id: 0, method: 'ping', params: {} }, PROBE_TIMEOUT_MS);
+        return { state: 'running', hint: '百度网盘AI修图客户端运行正常' };
+    } catch (e) {
+        return {
+            state: 'crashed',
+            hint: '百度网盘AI修图客户端可能已崩溃或异常退出，请重启客户端后重试',
+        };
+    }
+}
+
+/** 状态工具的回包：与客户端工具一致的 content[].text 结构 */
+function statusResult(id, status) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: { content: [{ type: 'text', text: JSON.stringify(status) }] },
+    };
+}
+
+/** aipic_client_status：本地应答，任何时候（含客户端没起）都能调用 */
+async function handleClientStatus(id) {
+    return statusResult(id, await probeClient());
+}
+
+/**
+ * tools/list：客户端在跑就转发并把状态工具并进去；没跑就只返回状态工具，
+ * 让 AI 至少能拿到一个可调用的工具去查状态、把「请安装/启动/重启」转告用户。
+ */
+async function handleToolsList(id) {
+    const status = await probeClient();
+    if (status.state === 'running') {
+        const body = await forward(
+            { jsonrpc: '2.0', id, method: 'tools/list', params: {} },
+            policy.toolTimeoutMs('tools/list')
+        );
+        if (body && body.result && Array.isArray(body.result.tools)) {
+            body.result.tools = [...body.result.tools, STATUS_TOOL];
+        }
+        return body;
+    }
+    return { jsonrpc: '2.0', id, result: { tools: [STATUS_TOOL] } };
+}
+
+/**
+ * 裁掉返回体里的大字段。实测：回收站一次返回 271KB 里 99% 是 base64 缩略图；
+ * list_images 5 张图 82KB 里 94% 是缩略图；retouch 的 info 是整份算子参数几 KB。
+ * 这些对判断没用，但能把模型上下文吃光。
+ */
+const BULKY_FIELDS = new Set(['thumbnail', 'thumbnails', 'info']);
+const SLIM_LIMIT = 512;
+
+function slim(node) {
+    if (Array.isArray(node)) {
+        return node.map(slim);
+    }
+    if (node && typeof node === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            if (BULKY_FIELDS.has(k)) {
+                const size = typeof v === 'string' ? v.length : JSON.stringify(v || '').length;
+                if (size > SLIM_LIMIT) {
+                    out[k] = `<omitted:${size} bytes>`;
+                    continue;
+                }
+            }
+            out[k] = slim(v);
+        }
+        return out;
+    }
+    return node;
+}
+
+/**
+ * 对 tools/call 的结果做瘦身。
+ *
+ * 注意业务数据的实际位置：客户端把整个业务 JSON **序列化成字符串**塞在
+ * `result.content[].text` 里（server.ts 的 `content: [{type:'text', text: JSON.stringify(result)}]`），
+ * 所以直接遍历 result 对象树是进不去的——必须先把 text 解回对象、裁完再 stringify 回去。
+ * 解不开（不是 JSON）就原样保留，不猜。
+ */
+function slimToolResult(result) {
+    if (!result || !Array.isArray(result.content)) {
+        return slim(result);
+    }
+    const content = result.content.map(item => {
+        if (!item || item.type !== 'text' || typeof item.text !== 'string') {
+            return item;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(item.text);
+        } catch (e) {
+            return item;
+        }
+        return { ...item, text: JSON.stringify(slim(parsed)) };
+    });
+    return { ...slim({ ...result, content: undefined }), content };
+}
+
+const SLIM_MARKER = '<omitted:';
+
+/**
+ * 瘦身标记回灌检查。
+ *
+ * 瘦身把超过 512 字符的 `info` 换成 `<omitted:N bytes>`。模型手上只有这份被裁过的数据，
+ * 而 `modify_preset` 的 `info` 实际必填——于是它会把这句占位符当参数写回去。
+ * 实测客户端 `errno: 0` 照收，预设 4029 字符的算子参数被覆盖成 20 字符的占位符，不可恢复。
+ * 所以写路径上只要参数里带这个标记就拒掉，并告诉调用方去哪取完整值。
+ */
+function findSlimMarker(node, path = '') {
+    if (typeof node === 'string') {
+        return node.startsWith(SLIM_MARKER) ? path || '(root)' : null;
+    }
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i += 1) {
+            const hit = findSlimMarker(node[i], `${path}[${i}]`);
+            if (hit) {
+                return hit;
+            }
+        }
+        return null;
+    }
+    if (node && typeof node === 'object') {
+        for (const [k, v] of Object.entries(node)) {
+            const hit = findSlimMarker(v, path ? `${path}.${k}` : k);
+            if (hit) {
+                return hit;
+            }
+        }
+    }
+    return null;
+}
+
+/** 整行原子写 stdout：一次 write 一条完整消息，避免并发响应交织成坏帧 */
+function send(msg) {
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+
+function rpcError(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+/** 工具级错误走 result.isError（MCP 约定），模型能看懂并自行调整，而不是当成协议错误 */
+function toolError(id, message) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: message }) }] },
+    };
+}
+
+/** write / destructive 工具的串行队列：客户端对同一项目的并发写没有保证 */
+let writeQueue = Promise.resolve();
+
+function serialize(fn) {
+    const queued = writeQueue.catch(() => undefined).then(fn);
+    writeQueue = queued;
+    return queued;
+}
+
+async function handleToolsCall(msg) {
+    const name = msg.params && msg.params.name;
+    const args = (msg.params && msg.params.arguments) || {};
+    if (typeof name !== 'string') {
+        return rpcError(msg.id, -32602, 'invalid tools/call params: name is required');
+    }
+    // 破坏性工具无条件拦下，且不看 params 里有没有 confirm——那个字段模型可以自己补
+    if (policy.requiresConfirmation(name)) {
+        return toolError(
+            msg.id,
+            `CONFIRMATION_REQUIRED: ${name} 会丢数据，代理层禁止由模型直接调用。` + '请引导用户在修图客户端 UI 里操作。'
+        );
+    }
+    const tooBig = policy.batchLimit(name, args);
+    if (tooBig) {
+        return toolError(msg.id, tooBig);
+    }
+
+    // 写路径禁止回灌瘦身占位符（会把预设参数等大字段覆盖成那句占位符，且客户端不校验）
+    if (policy.toolTier(name) !== 'read') {
+        const at = findSlimMarker(args);
+        if (at) {
+            return toolError(
+                msg.id,
+                `SLIMMED_VALUE_WRITEBACK: 参数 ${at} 的值是返回体瘦身留下的占位符（${SLIM_MARKER}…），` +
+                    '不是真实数据，写回去会覆盖原字段。请先取未瘦身的完整值' +
+                    '（预设 info 用 aipic_list_presets 并关掉瘦身读取），或者省略该参数。'
+            );
+        }
+    }
+
+    // 已知会崩客户端的工具（SIGABRT + 孤儿进程，崩后 MCP 服务不恢复）
+    if (policy.isUnsafe(name)) {
+        return toolError(
+            msg.id,
+            `UNSAFE_TOOL: ${name} 曾稳定触发客户端崩溃且崩后 MCP 服务不恢复，` +
+                '代理层禁止调用。请引导用户在修图客户端 UI 里操作。'
+        );
+    }
+    // 客户端比代理新时会出现未知工具。toolTier() 把未知归为 write（串行），这里记一条便于排查
+    if (!policy.isKnown(name)) {
+        log(`未知工具 ${name}：代理名单未覆盖，按 write 串行处理；请同步更新 tool-policy.js`);
+    }
+
+    const run = () => forward(msg, policy.toolTimeoutMs(name));
+    const body = policy.requiresSerialExecution(name) ? await serialize(run) : await run();
+    if (body && body.result) {
+        body.result = slimToolResult(body.result);
+    }
+    return body;
+}
+
+async function dispatch(msg) {
+    // initialize 本地应答：代理自己就是 server 门面，不需要把握手透传给客户端
+    if (msg.method === 'initialize') {
+        return {
+            jsonrpc: '2.0',
+            id: msg.id,
+            result: {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+            },
+        };
+    }
+    if (msg.method === 'tools/list') {
+        return handleToolsList(msg.id);
+    }
+    if (msg.method === 'tools/call') {
+        const name = msg.params && msg.params.name;
+        if (name === STATUS_TOOL_NAME) {
+            return handleClientStatus(msg.id);
+        }
+        return handleToolsCall(msg);
+    }
+    return rpcError(msg.id, -32601, `method not found: ${msg.method}`);
+}
+
+async function onMessage(line) {
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    } catch (e) {
+        send(rpcError(null, -32700, `parse error: ${e.message}`));
+        return;
+    }
+    // 批量数组：MCP 2025-06-18 已移除 JSON-RPC batch 支持。静默丢弃会让调用方一直等，
+    // 所以明确回一条 -32600，id 取不到就给 null。
+    if (Array.isArray(msg)) {
+        const first = msg.find(item => item && item.id !== undefined && item.id !== null);
+        send(rpcError(first ? first.id : null, -32600, 'JSON-RPC batch 不受支持（MCP 2025-06-18 已移除），请逐条发送'));
+        return;
+    }
+    // 通知（无 id）不回包。多回一条 id:null 的响应会让上游收到孤儿响应
+    const isNotification = msg.id === undefined || msg.id === null;
+    inFlight += 1;
+    try {
+        const reply = await dispatch(msg);
+        if (!isNotification && reply) {
+            send(reply);
+        }
+    } catch (e) {
+        if (isNotification) {
+            log(`通知处理失败（不回包）: ${e.message}`);
+        } else {
+            send(rpcError(msg.id, e.rpcCode || ERR.UPSTREAM_FAILED, e.message));
+        }
+    } finally {
+        inFlight -= 1;
+        if (inFlight === 0 && drain) {
+            drain();
+        }
+    }
+}
+
+// ---- stdin 按行切帧 ----
+// 不用 readline：它对超长行和 \r\n 的处理随版本有差异，这里自己按 \n 切，顺手剥掉 \r。
+// 每条消息独立 await，彼此不阻塞（引擎会并发下发多个 tools/call）。
+let buffer = '';
+/** 在途请求数：EOF 时要等它们落地再退，否则响应会被丢掉 */
+let inFlight = 0;
+let drain = null;
+/** EOF 后等在途请求的上限：取最长的工具档位 80s + 余量 */
+const DRAIN_TIMEOUT_MS = 90000;
+
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => {
+    buffer += chunk;
+    let idx = buffer.indexOf('\n');
+    while (idx >= 0) {
+        const line = buffer.slice(0, idx).replace(/\r$/, '').trim();
+        buffer = buffer.slice(idx + 1);
+        if (line) {
+            void onMessage(line);
+        }
+        idx = buffer.indexOf('\n');
+    }
+});
+
+// stdin EOF 即退出：引擎靠进程退出判断 server 停止。非预期退出会被上报成
+// STOPPED/ERROR 进而触发 onDrop 重连，所以只在这里退，别在别处 process.exit。
+// 但不能立刻退——EOF 可能在某次 tools/call 还在等上游时就到了（`echo ... | node index.js`
+// 就是这种时序），直接 exit 会把已经发出去的调用结果丢掉，上游只看到"没有响应"。
+process.stdin.on('end', async () => {
+    const rest = buffer.trim();
+    if (rest) {
+        void onMessage(rest);
+    }
+    if (inFlight > 0) {
+        log(`EOF，等 ${inFlight} 个在途请求落地`);
+        await new Promise(resolve => {
+            const timer = setTimeout(() => {
+                log('在途请求等待超时，仍然退出');
+                resolve();
+            }, DRAIN_TIMEOUT_MS);
+            drain = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+    }
+    process.exit(0);
+});
+
+process.on('uncaughtException', e => {
+    log(`uncaught: ${e && e.stack ? e.stack : e}`);
+});
+process.on('unhandledRejection', e => {
+    log(`unhandledRejection: ${e && e.stack ? e.stack : e}`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aipic-mcp-stdio",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "description": "stdio <-> HTTP proxy for the Baidu Netdisk AI Photo (NetdiskAIPhoto) local MCP server",
     "keywords": [
         "mcp",
@@ -13,17 +13,14 @@
         "registry": "https://registry.npmjs.org/"
     },
     "bin": {
-        "aipic-mcp-stdio": "bin/aipic-mcp-stdio.js"
+        "aipic-mcp-stdio": "index.js"
     },
     "engines": {
         "node": ">=18"
     },
     "files": [
-        "bin"
+        "index.js",
+        "tool-policy.js"
     ],
-    "dependencies": {},
-    "optionalDependencies": {
-        "aipic-mcp-stdio-darwin-arm64": "1.0.1",
-        "aipic-mcp-stdio-win32-x64": "1.0.1"
-    }
+    "dependencies": {}
 }

package/tool-policy.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * MCP 工具危险分级与超时档位。
+ *
+ * 背景：代理把 tools/call 直通给修图客户端，而模型可以自由决定调哪个工具、带什么参数。
+ * 对于会丢数据的工具，「让模型自己传 confirm=true」等于没有防护——模型完全可能为了
+ * 跑通流程自行补上确认标记。因此把管控放在代理进程：destructive 级工具一律先拒绝。
+ *
+ * 分级只依据工具名，不解析参数：工具名是 MCP 协议里唯一稳定的标识。
+ *
+ * 四份名单必须覆盖客户端全部工具（当前 75 个 = 7 destructive + 35 write + 33 read，
+ * 其中 1 个 read 同时在 UNSAFE 名单里）。新增工具时与 src/main/mcp/features/<feature>/tools.ts 的注册
+ * 同一个 CR 改完，`npm run verify` 里有覆盖率断言兜底。
+ */
+
+/**
+ * 不可恢复或会丢数据的工具。
+ * purge_* 是物理删除；delete_preset* / delete_project 删业务实体；
+ * clear_image_cache 会清空修图参数缓存，等于放弃已有修图结果。
+ */
+const DESTRUCTIVE_TOOLS = new Set([
+    'aipic_purge_images',
+    'aipic_purge_recycle_projects',
+    'aipic_delete_project',
+    'aipic_delete_preset',
+    'aipic_delete_preset_group',
+    'aipic_clear_image_cache',
+    // 进回收站可恢复，但仍从图库消失，需用户确认
+    'aipic_delete_images',
+]);
+
+/**
+ * 已知会让客户端崩溃的工具：曾稳定触发 SIGABRT（libaipic 的 std::mutex）并留下孤儿进程，
+ * 崩溃后 MCP 服务不恢复而 endpoint 文件仍在。
+ *
+ * 原 aipic_control_export_tasks 的「第二个崩溃入口」经真机复现未触发（完成/失败/暂停任务
+ * × type 0/1/2 全不崩，retry 还能正常恢复 PAUSED），已移出 unsafe、归入 write（控制导出
+ * 任务状态属写操作）。若后续出现崩溃，再回填此名单。
+ */
+const UNSAFE_TOOLS = new Set([]);
+
+/** 会写入数据的工具：需要串行执行，避免并发写 workspace / filecache 互相踩 */
+const WRITE_TOOLS = new Set([
+    'aipic_create_project',
+    'aipic_rename_project',
+    'aipic_batch_import',
+    'aipic_retouch_with_preset',
+    'aipic_batch_retouch_with_preset',
+    // 异步批量修图：提交动作本身也是写（会占住客户端的单任务槽位）
+    'aipic_batch_retouch_start',
+    // preview 内部也会 switchImage + 提交渲染，与批量任务并发会互相抢「当前图」
+    'aipic_preview_retouch',
+    'aipic_sync_preset',
+    'aipic_add_preset',
+    'aipic_modify_preset',
+    'aipic_create_preset_group',
+    'aipic_modify_preset_group',
+    'aipic_share_preset',
+    'aipic_import_preset_token',
+    'aipic_export_start',
+    'aipic_mark_images',
+    'aipic_relink_image',
+    'aipic_restore_recycle_projects',
+    'aipic_switch_space',
+    'aipic_import_from_netdisk',
+    // AI挑图/筛图
+    'aipic_start_filter',
+    'aipic_restart_filter',
+    'aipic_stop_filter',
+    'aipic_pause_filter',
+    'aipic_resume_filter',
+    'aipic_mark_filter_best',
+    // 在线选片
+    'aipic_select_switch_state',
+    'aipic_match_source',
+    // AI多人分片
+    'aipic_add_virtual_person',
+    'aipic_merge_persons',
+    'aipic_rename_person',
+    'aipic_delete_persons',
+    'aipic_sync_portrait_name',
+    'aipic_share_portrait',
+    // AI创意融图
+    'aipic_create_rongtu_project',
+    'aipic_rongtu_imgcreate',
+    // 导出任务控制（retry/pause/delete 会改任务状态，属写操作）
+    'aipic_control_export_tasks',
+]);
+
+/** 只读工具：可并发。显式列出而不是「非 write 即 read」，这样新增工具会落到未知分支。 */
+const READ_TOOLS = new Set([
+    'aipic_login_status',
+    'aipic_get_user_profile',
+    'aipic_get_account_context',
+    'aipic_get_current_space',
+    'aipic_list_spaces',
+    'aipic_get_ticket_balance',
+    'aipic_get_ticket_cost',
+    'aipic_list_projects',
+    'aipic_list_images',
+    'aipic_get_detection',
+    'aipic_list_presets',
+    'aipic_get_custom_presets',
+    'aipic_get_recommended_presets',
+    'aipic_list_preset_groups',
+    'aipic_list_export_tasks',
+    'aipic_get_export_fail_info',
+    'aipic_list_recycle_projects',
+    'aipic_get_retouch_task',
+    'aipic_list_cloud_images',
+    'aipic_get_netdisk_import_task',
+    // AI挑图/筛图
+    'aipic_list_filter_results',
+    // 在线选片
+    'aipic_list_select_all',
+    'aipic_list_selected',
+    'aipic_list_delivered',
+    'aipic_get_select_image_meta',
+    // AI多人分片
+    'aipic_list_persons',
+    'aipic_get_person_items',
+    // AI创意融图
+    'aipic_list_rongtu_projects',
+    'aipic_get_rongtu_info',
+    'aipic_list_rongtu_results',
+    'aipic_rongtu_allow_create',
+]);
+
+/**
+ * 慢工具超时档位（毫秒）。统一超时会误杀切图/渲染类调用，也会让快调用挂太久。
+ *
+ * 硬约束：**每一档都必须小于 90s**。库库引擎侧 McpService 的 callMethod 超时是
+ * DEFAULT_CALL_TIMEOUT_MS = 90_000 且不可由连接器配置覆盖；一旦引擎先超时，它会丢弃
+ * pending，之后真正的回包没人接——表现成「调用报超时但操作其实成功了」，模型会重试，
+ * 重试可能重复扣券。所以代理必须比引擎先超时，把失败语义收在自己手里。
+ */
+const TIMEOUT_OVERRIDES_MS = {
+    // 切图 + 渲染，实测单张 75ms~数秒（大 RAW 更慢）；留足余量但必须 < 90s
+    aipic_retouch_with_preset: 80000,
+    aipic_batch_retouch_with_preset: 80000,
+    // 只提交，真实耗时在 get_retouch_task 轮询里
+    aipic_batch_retouch_start: 30000,
+    // 纯内存查询
+    aipic_get_retouch_task: 10000,
+    // mode=seg 实测 0.65~1.29s
+    aipic_get_detection: 60000,
+    // 仅提交任务，真实耗时在轮询里
+    aipic_export_start: 60000,
+};
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * `batch_retouch_with_preset` 的批量上限。
+ *
+ * 客户端该工具是同步 for 循环逐张真修，批量大了会撞穿引擎 90s 硬超时。实测 30 张小图
+ * 2.2s（75ms/张），但大 RAW 慢得多，所以保留上限，超过就引导走异步版或 sync_preset。
+ */
+const BATCH_RETOUCH_MAX = 30;
+
+/** 工具名是否在任一名单里。不在 = 客户端比代理新，走保守分支。 */
+function isKnown(toolName) {
+    return DESTRUCTIVE_TOOLS.has(toolName) || WRITE_TOOLS.has(toolName) || READ_TOOLS.has(toolName);
+}
+
+/**
+ * 危险分级。
+ *
+ * **未知工具按 write 处理**（串行 + 默认超时），而不是按 read 放行。
+ * 原因：代理随库库安装包分发，客户端可能先升级并带来新工具。如果未知工具默认可并发，
+ * 一个新的写工具就会绕过串行化去并发改同一个项目。宁可把个别新增只读工具串行化
+ * （代价可忽略），也不能让写工具漏网。真正会丢数据的新工具仍需在下个版本显式进
+ * DESTRUCTIVE_TOOLS 才能被拦住——所以升级客户端后要同步更新这份名单。
+ */
+function toolTier(toolName) {
+    if (DESTRUCTIVE_TOOLS.has(toolName)) {
+        return 'destructive';
+    }
+    if (WRITE_TOOLS.has(toolName)) {
+        return 'write';
+    }
+    if (READ_TOOLS.has(toolName)) {
+        return 'read';
+    }
+    return 'write';
+}
+
+function toolTimeoutMs(toolName) {
+    return TIMEOUT_OVERRIDES_MS[toolName] || DEFAULT_TIMEOUT_MS;
+}
+
+/** write / destructive / 未知 需要串行；只有明确的 read 才并发 */
+function requiresSerialExecution(toolName) {
+    return toolTier(toolName) !== 'read';
+}
+
+/**
+ * 这个工具是否必须先拿到用户确认才能执行。
+ *
+ * destructive 级工具在这一层是**无条件拒绝**的：不接受任何「已确认」入参，因为 params
+ * 由模型生成，任何基于入参的确认标记都可被模型自行补上。用户确认后的重放需要一条
+ * 库库侧 renderer 才能触发、由 main 下发一次性令牌的独立通道，那条通道尚不存在。
+ */
+function requiresConfirmation(toolName) {
+    return toolTier(toolName) === 'destructive';
+}
+
+/** 已知会崩客户端的工具，一律拦下 */
+function isUnsafe(toolName) {
+    return UNSAFE_TOOLS.has(toolName);
+}
+
+/** 返回 null 表示放行；否则返回要回给模型的拒绝原因 */
+function batchLimit(toolName, args) {
+    if (toolName !== 'aipic_batch_retouch_with_preset') {
+        return null;
+    }
+    const ids = args && args.file_ids;
+    if (!Array.isArray(ids) || ids.length <= BATCH_RETOUCH_MAX) {
+        return null;
+    }
+    return (
+        `BATCH_TOO_LARGE: batch_retouch_with_preset 单次最多 ${BATCH_RETOUCH_MAX} 张` +
+        `（本次 ${ids.length} 张）。该工具在客户端是逐张同步真修，超过上限有撞穿引擎 90s 硬超时的风险。` +
+        '改用这两条之一：' +
+        '（1）只是要把同一套参数铺到多张图 → aipic_sync_preset，走 filecache 批量写、' +
+        '不切图不渲染，28 张约 0.5s，比循环真修快约 7 倍；' +
+        '（2）确实需要每张都渲染 → aipic_batch_retouch_start 提交异步任务拿 task_id，' +
+        '再用 aipic_get_retouch_task 轮询（status 只有 2/3 是终态）。'
+    );
+}
+
+/** 四张名单的并集（去重：unsafe 的工具同时也在 write 里），给 check-tool-sync.js 对账用 */
+function allKnownTools() {
+    return [...new Set([...DESTRUCTIVE_TOOLS, ...UNSAFE_TOOLS, ...WRITE_TOOLS, ...READ_TOOLS])];
+}
+
+module.exports = {
+    DESTRUCTIVE_TOOLS,
+    UNSAFE_TOOLS,
+    WRITE_TOOLS,
+    READ_TOOLS,
+    BATCH_RETOUCH_MAX,
+    allKnownTools,
+    isKnown,
+    isUnsafe,
+    toolTier,
+    toolTimeoutMs,
+    requiresSerialExecution,
+    requiresConfirmation,
+    batchLimit,
+};

package/bin/aipic-mcp-stdio.js

@@ -1,32 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-// 分发器：按当前平台/架构拉起对应平台包里预编译好的二进制。
-// 敏感逻辑（护栏分级、endpoint 读取、stdin 帧解析等）全在二进制里，这里只负责选包并透传 stdio。
-const { spawn } = require('node:child_process');
-
-const pkgName = `aipic-mcp-stdio-${process.platform}-${process.arch}`;
-let binPath;
-try {
-    binPath = require(pkgName);
-} catch (err) {
-    process.stderr.write(
-        `aipic-mcp-stdio: 当前平台 ${process.platform}-${process.arch} 没有预编译二进制（${pkgName} 未安装）。\n`
-    );
-    process.exit(1);
-}
-
-const child = spawn(binPath, [], { stdio: 'inherit' });
-
-child.on('error', err => {
-    process.stderr.write(`aipic-mcp-stdio: 启动二进制失败：${err.message}\n`);
-    process.exit(1);
-});
-
-child.on('exit', (code, signal) => {
-    if (signal) {
-        process.kill(process.pid, signal);
-    } else {
-        process.exit(code == null ? 1 : code);
-    }
-});