@honlnk/picsense 0.1.0

package/dist/index.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * picsense MCP 入口。
+ *
+ * 启动顺序：
+ * 1. 加载并校验配置（缺失必填项 → 友好报错到 stderr 后退出）。
+ * 2. 构造默认 provider（触发 provider 注册）。
+ * 3. 创建 SessionManager（含多轮迭代、并发隔离、24h 过期清理）。
+ * 4. 注册 3 个工具：analyze_images / list_sessions / analyze_document。
+ * 5. 经 stdio 传输与 MCP 客户端通信。
+ *
+ * 设计依据：docs/picsense-design.md §4.1、§6.3；docs/plan/05-mcp-entry.md。
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, ConfigError } from './utils/config.js';
+import './providers/registry.js'; // 触发 provider 自注册
+import { getProvider } from './providers/registry.js';
+import { SessionManager } from './core/session-manager.js';
+import { analyzeImages, ToolInputError } from './tools/analyze-images.js';
+import { listSessions } from './tools/list-sessions.js';
+import { analyzeDocument } from './tools/analyze-document.js';
+import { analyzeVideo, VideoLoadError } from './tools/analyze-video.js';
+import { SessionNotFoundError } from './core/session-manager.js';
+/** 把结果对象包成 MCP 文本 content（标准做法）。 */
+function asText(obj) {
+    return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+}
+/** 把错误包成 isError 的工具结果（MCP 标准的错误信号方式）。 */
+function asError(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        // 配置错误：直接退出，提示走 stderr（stdout 留给 JSON-RPC）。
+        if (err instanceof ConfigError) {
+            process.stderr.write(`[picsense] config error: ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // 构造默认 provider。
+    const providerCfg = config.providers[config.defaultProvider];
+    if (!providerCfg) {
+        // throw（而非 process.exit）：返回类型为 never，让 TS 严格控制流收窄
+        // providerCfg 为 ProviderConfig，同时交由 main().catch 统一输出。
+        throw new ConfigError(`Default provider "${config.defaultProvider}" is not configured. ` +
+            `Please set the corresponding API_KEY and MODEL (see .env.example).`);
+    }
+    const provider = getProvider(config.defaultProvider, providerCfg, {
+        timeoutMs: config.timeoutMs,
+    });
+    // Session 管理器，启动定时清理。
+    const sessionManager = new SessionManager(provider, config.maxImageBytes, config.sessionTtlMs, config.sessionCleanupIntervalMs);
+    sessionManager.startCleanup();
+    const server = new McpServer({ name: 'picsense', version: '0.1.0' }, { capabilities: { tools: {} } });
+    // ===== 工具 1：analyze_images =====
+    server.registerTool('analyze_images', {
+        description: '识别图片内容。传入一张图片为单图识别，传入多张为批量或对比识别。' +
+            '支持多轮迭代——首次调用创建 session，后续调用传入 session_id 可在已有对话基础上追加提问。',
+        inputSchema: {
+            image_sources: z
+                .array(z.string())
+                .optional()
+                .describe('图片来源数组（传一张为单图识别，传多张为批量/对比），每项自动识别 http URL / 本地文件路径 / base64。首次调用创建 session 时必填；后续轮次传入 session_id 时可省略（沿用该 session 的图片）'),
+            prompt: z.string().describe('对图片的识别要求，根据当前任务意图编写'),
+            session_id: z
+                .string()
+                .optional()
+                .describe('传入已有 session 的 ID 以发起后续轮次；不传则创建新 session'),
+        },
+    }, async (args) => {
+        try {
+            const result = await analyzeImages(sessionManager, {
+                image_sources: args.image_sources,
+                prompt: args.prompt,
+                session_id: args.session_id,
+            });
+            return asText(result);
+        }
+        catch (err) {
+            return asError(formatError(err));
+        }
+    });
+    // ===== 工具 2：list_sessions =====
+    server.registerTool('list_sessions', {
+        description: '查看当前所有识别会话的列表，包括每个 session 的简介、关联图片和迭代轮数。用于回顾历史识别记录。',
+    }, async () => {
+        const result = await listSessions(sessionManager);
+        return asText(result);
+    });
+    // ===== 工具 3：analyze_document =====
+    server.registerTool('analyze_document', {
+        description: '解析文档，识别其中所有图片的内容，并在图片位置旁标注描述。返回标注后的完整文档。',
+        inputSchema: {
+            document: z.string().describe('文档 URL / HTML / markdown（自动识别）'),
+        },
+    }, async (args) => {
+        try {
+            const result = await analyzeDocument(provider, config.maxImageBytes, config.timeoutMs, { document: args.document });
+            return asText(result);
+        }
+        catch (err) {
+            return asError(formatError(err));
+        }
+    });
+    // ===== 工具 4：analyze_video =====
+    server.registerTool('analyze_video', {
+        description: '识别视频内容。把视频抽帧后发送给视觉模型分析（默认每秒抽 1 帧、最多 30 帧）。' +
+            '支持多轮迭代——首次调用创建 session，后续调用传入 session_id 可在已有对话基础上追加提问。',
+        inputSchema: {
+            video_source: z
+                .string()
+                .optional()
+                .describe('视频来源（http URL / 本地文件路径），自动识别。首次调用创建 session 时必填；后续轮次传入 session_id 时可省略（沿用该 session 的视频）'),
+            prompt: z.string().describe('对视频的识别要求，根据当前任务意图编写'),
+            session_id: z
+                .string()
+                .optional()
+                .describe('传入已有 session 的 ID 以发起后续轮次；不传则创建新 session'),
+        },
+    }, async (args) => {
+        try {
+            const result = await analyzeVideo(sessionManager, {
+                video_source: args.video_source,
+                prompt: args.prompt,
+                session_id: args.session_id,
+            }, config.maxVideoBytes, { fps: config.videoFps, maxFrames: config.videoMaxFrames });
+            return asText(result);
+        }
+        catch (err) {
+            return asError(formatError(err));
+        }
+    });
+    // stdio 传输。
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`[picsense] started (provider=${config.defaultProvider}, model=${providerCfg.model})\n`);
+    // 进程退出时清理定时器（session 内存态自然清空，无需持久化善后）。
+    const shutdown = () => {
+        sessionManager.stopCleanup();
+    };
+    process.on('SIGINT', () => {
+        shutdown();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        shutdown();
+        process.exit(0);
+    });
+}
+/** 把各类错误格式化成面向用户的提示。 */
+function formatError(err) {
+    if (err instanceof SessionNotFoundError) {
+        return err.message + ' 该 session 可能已过期（超过 24 小时）或进程已重启。请重新发起首次识别。';
+    }
+    if (err instanceof ToolInputError) {
+        return `参数错误: ${err.message}`;
+    }
+    if (err instanceof VideoLoadError) {
+        return `视频加载失败: ${err.message}`;
+    }
+    if (err instanceof Error) {
+        return `识别失败: ${err.message}`;
+    }
+    return `识别失败: ${String(err)}`;
+}
+main().catch((err) => {
+    process.stderr.write(`[picsense] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/providers/index.js

@@ -0,0 +1,31 @@
+/**
+ * VisionProvider 抽象层。
+ *
+ * 设计依据：docs/picsense-design.md §5.2.2、§6.1 —— 参考 @systemmin/image-mcp 的接口设计，
+ * 新增 provider 只需实现 VisionProvider 接口并在 getProvider 工厂注册。
+ *
+ * 多轮对话历史布局（见 docs/plan/03-session-manager.md）：
+ * - 首轮 user message 含图（images 非空）。
+ * - 后续轮次只有文字，provider 把 messages 拼成原生多轮 messages 数组发给视觉模型。
+ */
+/** 已注册的 provider 工厂表。新增 provider 时在此注册即可。 */
+const FACTORIES = {};
+/** 供 provider 模块自注册用。 */
+export function registerProvider(name, factory) {
+    FACTORIES[name] = factory;
+}
+/**
+ * 按 provider 名称构造实例。
+ *
+ * @param name provider 名称（如 'openai'）。
+ * @param cfg 该 provider 的配置（API Key / model / baseUrl）。
+ * @param opts 跨 provider 的运行时选项。
+ */
+export function getProvider(name, cfg, opts) {
+    const factory = FACTORIES[name];
+    if (!factory) {
+        throw new Error(`Unknown provider "${name}". Supported: ${Object.keys(FACTORIES).join(', ') || '(none registered yet)'}.`);
+    }
+    return factory(cfg, opts);
+}
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4CH,6CAA6C;AAC7C,MAAM,SAAS,GAA6C,EAAE,CAAC;AAE/D,yBAAyB;AACzB,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAwB;IACrE,SAAS,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,GAAmB,EACnB,IAAkB;IAElB,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,iBAAiB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,uBAAuB,GAAG,CAC1G,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC5B,CAAC"}

package/dist/providers/openai.js

@@ -0,0 +1,185 @@
+/**
+ * OpenAI Responses API vision provider。
+ *
+ * 该 provider 使用 OpenAI 的 **Responses API**（/v1/responses，原生格式），
+ * 而非 Chat Completions API。区别：
+ * - 请求用 input 数组（而非 messages），content part 用 input_text / input_image。
+ * - 多图：首轮 user 的 content 数组里放多个 input_image + 一个 input_text。
+ * - 图片字段 image_url：可为 https URL（直传）或 data:image/xxx;base64,...（base64）。
+ * - 响应：output[].content[] 中 type=output_text 的 text 为正文。
+ *
+ * 调研确认（实测 vibebabo.com 网关 + gpt-5.6-sol）：
+ * - endpoint: POST {baseUrl}/responses，其中 baseUrl 形如 https://api.openai.com/v1
+ *   （若用户传入的 baseUrl 已带 /v1 则原样使用；若未带则补 /v1）。
+ * - input 支持多轮：数组里多条 user/assistant 消息，assistant 的 content 用
+ *   [{type:'output_text', text}] 形态（已在实测中验证多轮记忆）。
+ *
+ * 多轮对话布局（见 docs/plan/03-session-manager.md）：
+ * 图片只挂在首轮 user message 的 content（input_image），后续轮次纯文字。
+ */
+import { registerProvider } from './index.js';
+import { withRetry } from './retry.js';
+export class ProviderHttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ProviderHttpError';
+    }
+}
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+/**
+ * 规范化 baseUrl：确保以 /v1 结尾（Responses API 路径为 /responses）。
+ * - 用户传 https://api.openai.com → 补 /v1
+ * - 用户传 https://api.openai.com/v1 → 原样
+ * - 用户传 https://gateway.com/v1/ → 去尾斜杠
+ */
+function normalizeBaseUrl(raw) {
+    if (!raw)
+        return DEFAULT_BASE_URL;
+    let url = raw.replace(/\/+$/, ''); // 去尾斜杠
+    if (!/\/v\d+$/.test(url)) {
+        url += '/v1';
+    }
+    return url;
+}
+/**
+ * 把 VisionRequest 转换为 Responses API 的 input 数组。
+ *
+ * 规则：images 只附加到 messages 里第一条 user 消息的 content（首轮）。
+ */
+function buildInput(req) {
+    const input = [];
+    // system 消息：仅当需要生成 summary 时，给一个极简结构指令。
+    // 不预设场景化 prompt（设计文档 §2.3）。
+    if (req.generateSummary) {
+        input.push({
+            role: 'system',
+            content: 'You are a vision assistant. After your description, append a one-sentence summary of this image session wrapped in <summary>...</summary> tags. The summary should capture the essence of what the user is analyzing.',
+        });
+    }
+    let imagesAttached = false;
+    for (const msg of req.messages) {
+        if (msg.role === 'user' && req.images.length > 0 && !imagesAttached) {
+            // 首条 user 消息：图片 + 文字。
+            const parts = [];
+            for (const img of req.images) {
+                parts.push({ type: 'input_image', image_url: img.url });
+            }
+            parts.push({ type: 'input_text', text: msg.content });
+            input.push({ role: 'user', content: parts });
+            imagesAttached = true;
+        }
+        else {
+            // user 后续轮：纯文字（用 input_text 包装，保持数组形态一致）。
+            // assistant 历史轮：用 output_text 包装。
+            const partType = msg.role === 'assistant' ? 'output_text' : 'input_text';
+            input.push({
+                role: msg.role,
+                content: [{ type: partType, text: msg.content }],
+            });
+        }
+    }
+    // 兜底：传了图片但 messages 里没有 user 消息（异常情况）。
+    if (req.images.length > 0 && !imagesAttached) {
+        const parts = req.images.map((img) => ({
+            type: 'input_image',
+            image_url: img.url,
+        }));
+        input.push({ role: 'user', content: parts });
+    }
+    return input;
+}
+/** 从 Responses API 返回中拆出 summary 和正文 description。 */
+function extractText(data) {
+    const out = data.output;
+    if (!Array.isArray(out))
+        return '';
+    const texts = [];
+    for (const item of out) {
+        if (item.type === 'message' && Array.isArray(item.content)) {
+            for (const c of item.content) {
+                if (c.type === 'output_text' && typeof c.text === 'string') {
+                    texts.push(c.text);
+                }
+            }
+        }
+    }
+    return texts.join('\n').trim();
+}
+/** 从模型回复中拆出 summary 和正文 description。 */
+function splitSummary(raw, expectSummary) {
+    if (!expectSummary) {
+        return { description: raw };
+    }
+    const match = raw.match(/<summary>([\s\S]*?)<\/summary>/i);
+    if (match) {
+        const summary = match[1].trim();
+        const description = raw.replace(match[0], '').trim();
+        return { description: description || raw.trim(), summary };
+    }
+    // 模型没按格式返回时，用首句兜底作 summary。
+    const firstLine = raw.split('\n').find((l) => l.trim()) ?? raw.slice(0, 80);
+    return { description: raw.trim(), summary: firstLine.trim().slice(0, 120) };
+}
+class OpenAIProvider {
+    apiKey;
+    model;
+    baseUrl;
+    timeoutMs;
+    name = 'openai';
+    constructor(apiKey, model, baseUrl, timeoutMs) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    async analyze(req) {
+        const input = buildInput(req);
+        const body = {
+            model: this.model,
+            input,
+            // 非流式，便于一次性拿到完整回复。
+            stream: false,
+        };
+        const raw = await withRetry(async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(`${this.baseUrl}/responses`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => '');
+                    throw new ProviderHttpError(`OpenAI Responses API error ${res.status}: ${text.slice(0, 500)}`, res.status, text);
+                }
+                const data = await res.json();
+                const content = extractText(data);
+                if (!content) {
+                    throw new ProviderHttpError('OpenAI Responses API returned no text content', 200, JSON.stringify(data).slice(0, 500));
+                }
+                return { status: res.status, result: content };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+        const { description, summary } = splitSummary(raw, req.generateSummary === true);
+        return summary ? { description, summary } : { description };
+    }
+}
+/** 工厂实现。 */
+export const createOpenAIProvider = (cfg, opts) => {
+    return new OpenAIProvider(cfg.apiKey, cfg.model, normalizeBaseUrl(cfg.baseUrl), opts.timeoutMs);
+};
+// 模块加载时自注册。
+registerProvider('openai', createOpenAIProvider);
+//# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"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"}

package/dist/providers/registry.js

@@ -0,0 +1,15 @@
+/**
+ * Provider 注册中心。
+ *
+ * 各 provider 模块在 import 时通过 registerProvider() 自注册。
+ * 本文件集中 import 所有 provider，确保应用启动时它们都被加载。
+ * 入口/测试只需 import 本模块即可获得全部已注册 provider。
+ *
+ * 新增 provider 时：在下方加一行 import。
+ */
+import './openai.js';
+// 后续 provider 在此注册：
+// import './qwen.js';
+// import './kimi.js';
+export { getProvider, registerProvider } from './index.js';
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,aAAa,CAAC;AACrB,oBAAoB;AACpB,sBAAsB;AACtB,sBAAsB;AAEtB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/providers/retry.js

@@ -0,0 +1,51 @@
+/**
+ * 通用重试工具。参考 @z_ai/mcp-server 的 withRetry（设计文档 附录 A.4）：
+ * 最多重试 maxRetries 次，每次间隔 baseDelayMs，仅对网络/服务端错误重试。
+ */
+/** 简单的 sleep。 */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * 判断错误是否值得重试：网络错误或 5xx/429。
+ * 4xx（除 429）通常是请求本身的问题，重试无意义。
+ */
+export function isRetryable(status, error) {
+    if (status !== undefined) {
+        if (status === 429)
+            return true;
+        if (status >= 500 && status < 600)
+            return true;
+        return false;
+    }
+    // 无 status（网络层错误，如 DNS/连接超时）—— 重试。
+    return error instanceof TypeError;
+}
+/**
+ * 带重试地执行 fn。
+ *
+ * @param fn 待执行函数。
+ * @param maxRetries 最大重试次数（不含首次）。
+ * @param baseDelayMs 首次重试前等待毫秒数；每次翻倍。
+ */
+export async function withRetry(fn, maxRetries = 2, baseDelayMs = 1000) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const { result } = await fn();
+            return result;
+        }
+        catch (err) {
+            lastError = err;
+            // 错误对象上携带的 status 字段（见 OpenAIProvider 抛出的 ProviderHttpError）。
+            const status = err.status;
+            if (attempt < maxRetries && isRetryable(status, err)) {
+                await sleep(baseDelayMs * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/providers/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/providers/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iBAAiB;AACjB,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAA0B,EAAE,KAAc;IACpE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,IAAI,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,mCAAmC;IACnC,OAAO,KAAK,YAAY,SAAS,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAgD,EAChD,UAAU,GAAG,CAAC,EACd,WAAW,GAAG,IAAI;IAElB,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAChB,8DAA8D;YAC9D,MAAM,MAAM,GAAI,GAA2B,CAAC,MAAM,CAAC;YACnD,IAAI,OAAO,GAAG,UAAU,IAAI,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBACrD,MAAM,KAAK,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;gBACxC,SAAS;YACX,CAAC;YACD,MAAM;QACR,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/tools/analyze-document.js

@@ -0,0 +1,130 @@
+/**
+ * analyze_document 工具业务逻辑。
+ *
+ * 设计依据：docs/picsense-design.md §4.1、§4.2.5。
+ * - 输入文档（URL/HTML/markdown 自动识别）。
+ * - 识别其中所有图片，在图片位置旁标注描述。
+ * - 返回标注后的完整文档 + 识别图片数。
+ *
+ * 职责单一：输入文档、输出文档。识别 prompt 内置，不接收外部 prompt（§4.2.5）。
+ * 标注格式：图片后插入注释，不破坏原文档渲染：
+ *   markdown: ![alt](url)\n<!-- image-vision: <desc> -->
+ *   html:     <img src="url"> 后插 <!-- image-vision: <desc> -->
+ *
+ * 策略：逐张串行识别（保守，避免 rate limit）。失败容错，原图保留并标注失败原因。
+ */
+import { loadImage, ImageLoadError } from '../core/image-loader.js';
+/** 内置识别 prompt（不接收外部 prompt）。 */
+const DOC_IMAGE_PROMPT = 'Describe this image concisely and accurately.';
+const HTML_IMG_RE = /<img\s+[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi;
+const MD_IMG_RE = /!\[([^\]]*)\]\(([^)]+)\)/g;
+export class DocumentFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DocumentFetchError';
+    }
+}
+export async function analyzeDocument(provider, maxImageBytes, timeoutMs, params) {
+    const doc = params.document?.trim();
+    if (!doc) {
+        return { document: params.document ?? '', images_analyzed: 0 };
+    }
+    // 自动识别文档形态：URL → 抓取；含 <img → HTML；否则 markdown。
+    let content = doc;
+    let isHtml = /<[a-z!][\s\S]*>/i.test(doc);
+    if (/^https?:\/\//i.test(doc)) {
+        content = await fetchDocument(doc, timeoutMs);
+        // 抓回来的内容形态重新判断。
+        isHtml = /<[a-z!][\s\S]*>/i.test(content) && /<img\s/i.test(content);
+    }
+    if (isHtml) {
+        return annotateHtml(provider, maxImageBytes, content);
+    }
+    return annotateMarkdown(provider, maxImageBytes, content);
+}
+/** 抓取 URL 文档正文。 */
+async function fetchDocument(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: { Accept: 'text/html, text/markdown, text/plain, */*' },
+        });
+        if (!res.ok) {
+            throw new DocumentFetchError(`Failed to fetch document: HTTP ${res.status}`);
+        }
+        return await res.text();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 标注 HTML 文档中的 <img>。 */
+async function annotateHtml(provider, maxImageBytes, html) {
+    const matches = [];
+    let m;
+    HTML_IMG_RE.lastIndex = 0;
+    while ((m = HTML_IMG_RE.exec(html)) !== null) {
+        matches.push({ src: m[1], index: m.index, fullEnd: m.index + m[0].length });
+    }
+    if (matches.length === 0)
+        return { document: html, images_analyzed: 0 };
+    // 从后往前插入注释，避免影响前面的 index。
+    let result = html;
+    let analyzed = 0;
+    for (let i = matches.length - 1; i >= 0; i--) {
+        const { src, fullEnd } = matches[i];
+        const desc = await recognizeOne(provider, maxImageBytes, src);
+        const comment = `\n<!-- image-vision: ${escapeComment(desc)} -->`;
+        result = result.slice(0, fullEnd) + comment + result.slice(fullEnd);
+        if (!desc.startsWith('[识别失败'))
+            analyzed++;
+    }
+    return { document: result, images_analyzed: analyzed };
+}
+/** 标注 markdown 文档中的 ![]()。 */
+async function annotateMarkdown(provider, maxImageBytes, md) {
+    const matches = [];
+    let m;
+    MD_IMG_RE.lastIndex = 0;
+    while ((m = MD_IMG_RE.exec(md)) !== null) {
+        matches.push({ full: m[0], index: m.index, end: m.index + m[0].length });
+    }
+    if (matches.length === 0)
+        return { document: md, images_analyzed: 0 };
+    let result = md;
+    let analyzed = 0;
+    for (let i = matches.length - 1; i >= 0; i--) {
+        // 提取 url：full 形如 ![alt](url)
+        const urlMatch = matches[i].full.match(/!\[[^\]]*\]\(([^)]+)\)/);
+        const url = urlMatch ? urlMatch[1].trim() : '';
+        const desc = await recognizeOne(provider, maxImageBytes, url);
+        const comment = `\n<!-- image-vision: ${escapeComment(desc)} -->`;
+        result = result.slice(0, matches[i].end) + comment + result.slice(matches[i].end);
+        if (!desc.startsWith('[识别失败'))
+            analyzed++;
+    }
+    return { document: result, images_analyzed: analyzed };
+}
+/** 识别单张图，失败返回错误占位（不抛出，保证整体流程继续）。 */
+async function recognizeOne(provider, maxImageBytes, src) {
+    try {
+        const img = await loadImage(src, maxImageBytes);
+        const res = await provider.analyze({
+            images: [img],
+            messages: [{ role: 'user', content: DOC_IMAGE_PROMPT }],
+            generateSummary: false,
+        });
+        return res.description;
+    }
+    catch (err) {
+        const reason = err instanceof ImageLoadError ? err.message : err instanceof Error ? err.message : String(err);
+        return `[识别失败: ${reason}]`;
+    }
+}
+/** 转义注释内容中的 -->，避免破坏 HTML 注释。 */
+function escapeComment(s) {
+    return s.replace(/-->/g, '--&gt;');
+}
+//# sourceMappingURL=analyze-document.js.map

package/dist/tools/analyze-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-document.js","sourceRoot":"","sources":["../../src/tools/analyze-document.ts"],"names":[],"mappings":"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"}