minimal-agent 0.8.2 → 0.10.0

package/src/multimodal.js

@@ -0,0 +1,203 @@
+/**
+ * ============================================================
+ *  src/multimodal.ts —— OpenAI 兼容多模态输入辅助
+ * ------------------------------------------------------------
+ *  v1 支持图片：本地路径 → data URL，公网 URL → 原样 image_url。
+ *  这里不调用模型，只负责把 TUI / -p / stream-json 的输入规整成
+ *  Chat Completions 的 content blocks。
+ * ============================================================
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getWorkingDir } from './bootstrap/workingDir.js';
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const IMAGE_MIME_BY_EXT = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+};
+const IMAGE_EXT_PATTERN = String.raw `(?:png|jpe?g|gif|webp)`;
+export function isSupportedImageSource(source) {
+    const clean = stripWrappingQuotes(source.trim());
+    if (isHttpUrl(clean)) {
+        try {
+            const u = new URL(clean);
+            return new RegExp(`\\.(${IMAGE_EXT_PATTERN})(?:$|[?#])`, 'i').test(u.pathname);
+        }
+        catch {
+            return false;
+        }
+    }
+    return Object.hasOwn(IMAGE_MIME_BY_EXT, extname(clean).toLowerCase());
+}
+export function normalizeImageDetail(value) {
+    if (value === 'low' || value === 'high' || value === 'default')
+        return value;
+    return 'default';
+}
+export function contentToPlainText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content === null)
+        return '';
+    return content
+        .map((part) => {
+        if (part.type === 'text')
+            return part.text;
+        if (part.type === 'image_url')
+            return '[图片]';
+        if (part.type === 'video_url')
+            return '[视频]';
+        return '';
+    })
+        .filter(Boolean)
+        .join(' ');
+}
+export function contentToDisplayText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content === null)
+        return '';
+    const imageCount = content.filter((p) => p.type === 'image_url').length;
+    const videoCount = content.filter((p) => p.type === 'video_url').length;
+    const text = content
+        .filter((p) => p.type === 'text')
+        .map((p) => p.text)
+        .join('\n')
+        .trim();
+    const badges = [
+        imageCount > 0 ? `[已附加 ${imageCount} 张图片]` : '',
+        videoCount > 0 ? `[已附加 ${videoCount} 个视频]` : '',
+    ].filter(Boolean);
+    return [text, ...badges].filter(Boolean).join('\n');
+}
+export function extractInlineImageInputs(input, defaults = {}) {
+    const images = [];
+    let text = input;
+    const consume = (raw) => {
+        const source = stripWrappingQuotes(raw.trim());
+        if (!source || !isSupportedImageSource(source))
+            return raw;
+        images.push({
+            source,
+            detail: defaults.detail,
+            maxLongSidePixel: defaults.maxLongSidePixel,
+        });
+        return '';
+    };
+    // @"/path with spaces/a.png" / @'path' / @./a.png / @https://x/a.png
+    text = text.replace(/(^|\s)@(?:"([^"]+)"|'([^']+)'|(\S+))/g, (match, prefix, dq, sq, bare) => {
+        const before = prefix ?? '';
+        const source = dq ?? sq ?? bare ?? '';
+        const out = consume(source);
+        return out === '' ? before : match;
+    });
+    // 裸 URL 图片。
+    text = text.replace(new RegExp(String.raw `(^|\s)(https?:\/\/\S+?\.${IMAGE_EXT_PATTERN}(?:[?#]\S*)?)`, 'gi'), (match, prefix, source) => {
+        const out = consume(source);
+        return out === '' ? prefix : match;
+    });
+    // 裸本地图片路径只支持无空格写法；含空格请用 @"/path with spaces/a.png"。
+    text = text.replace(new RegExp(String.raw `(^|\s)((?:\.{1,2}\/|\/|~\/)\S+?\.${IMAGE_EXT_PATTERN})`, 'gi'), (match, prefix, source) => {
+        const out = consume(source);
+        return out === '' ? prefix : match;
+    });
+    return {
+        text: text.replace(/[ \t]{2,}/g, ' ').replace(/\n{3,}/g, '\n\n').trim(),
+        images,
+    };
+}
+export async function buildUserContent(args) {
+    let text = args.text;
+    const images = [...(args.images ?? [])];
+    if (args.parseInlineImages) {
+        const parsed = extractInlineImageInputs(text, {
+            detail: args.detail,
+            maxLongSidePixel: args.maxLongSidePixel,
+        });
+        text = parsed.text;
+        images.push(...parsed.images);
+    }
+    if (images.length === 0)
+        return text;
+    const parts = [];
+    const finalText = text.trim() || '请分析这张图片。';
+    parts.push({ type: 'text', text: finalText });
+    for (const image of images) {
+        parts.push(await imageToContentPart(image));
+    }
+    return parts;
+}
+export async function imageToContentPart(input) {
+    const url = await imageSourceToUrl(input.source);
+    const image_url = {
+        url,
+        detail: input.detail ?? 'default',
+    };
+    if (typeof input.maxLongSidePixel === 'number' && input.maxLongSidePixel > 0) {
+        image_url.max_long_side_pixel = Math.floor(input.maxLongSidePixel);
+    }
+    return { type: 'image_url', image_url };
+}
+/**
+ * 按文件头魔数嗅探图片 MIME（扩展名认不出时的回退）。只认 JPEG/PNG/GIF/WEBP——
+ * 与 IMAGE_MIME_BY_EXT 支持集一致（OpenAI 兼容接口可吃这四类）。非图返回 null。
+ * 动机：下载来的图常带非标准/无扩展名（如爬虫/配图工作流把候选存成 cand_K.img），
+ * 仅按扩展名查会误判「不支持」而拒图——魔数嗅探让任意扩展名的真图都能用。
+ */
+export function sniffImageMime(buf) {
+    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+        return 'image/png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return 'image/jpeg';
+    if (buf.length >= 4 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38)
+        return 'image/gif';
+    if (buf.length >= 12 &&
+        buf.toString('ascii', 0, 4) === 'RIFF' &&
+        buf.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    return null;
+}
+async function imageSourceToUrl(source) {
+    const clean = stripWrappingQuotes(source.trim());
+    if (isHttpUrl(clean) || clean.startsWith('data:image/'))
+        return clean;
+    const filePath = resolveImagePath(clean);
+    const st = await stat(filePath).catch((e) => {
+        throw new Error(`无法读取图片：${source}（${e.message}）`);
+    });
+    if (!st.isFile())
+        throw new Error(`图片路径不是文件：${source}`);
+    if (st.size > MAX_IMAGE_BYTES) {
+        throw new Error(`图片过大：${source} ${(st.size / 1024 / 1024).toFixed(1)}MB，` +
+            `OpenAI 兼容接口单图上限按 10MB 处理。`);
+    }
+    const data = await readFile(filePath);
+    // 先按扩展名查 MIME；认不出（无扩展名 / .img / 扩展名错）再按文件头魔数嗅探，都不认才拒。
+    const mime = IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? sniffImageMime(data);
+    if (!mime) {
+        throw new Error(`不支持的图片格式：${source}。仅支持 JPEG/PNG/GIF/WEBP（按扩展名与文件头都未识别）。`);
+    }
+    return `data:${mime};base64,${data.toString('base64')}`;
+}
+function resolveImagePath(source) {
+    if (source.startsWith('file://'))
+        return fileURLToPath(source);
+    if (source.startsWith('~/')) {
+        return resolve(process.env.HOME ?? '', source.slice(2));
+    }
+    return resolve(getWorkingDir(), source);
+}
+function isHttpUrl(source) {
+    return /^https?:\/\//i.test(source);
+}
+function stripWrappingQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}

package/src/plugin-sdk.js

@@ -16,9 +16,24 @@
  */
 // --- 运行时入口 ---
 export { runQuery } from './loop.js';
+export { runAgentTurn } from './session/runAgentTurn.js';
 export { chat } from './llm/client.js';
 export { ALL_TOOLS, executeTool, getToolByName } from './tools/index.js';
+// pre-read 守卫状态登记：tool 步覆盖「声明产物」时用来解除内核「先读后写 / 截断禁写」
+// 守卫（确定性步的 args 写死、模型没机会先 Read）。详见 stepExecutors/tool.ts。
+export { recordRead } from './tools/shared/fileState.js';
 export { getWorkingDir } from './bootstrap/workingDir.js';
+export { dlog } from './utils/debugLog.js';
+// <think> 思维链剥离：内核与 workflow-runner 共享（原住 agentCommon.ts，
+// Agent 子任务工具也需要 → 上移内核，插件经此 re-export）。
+export { stripThinkBlocks } from './utils/stripThink.js';
+export { buildFullSystemPrompt } from './prompts/system.js';
 export { getResourceSearchPaths } from './utils/resourcePaths.js';
+// 确定性检查设施：verify 步（shell/file_exists/file_contains/test_count）经此跑校验。
+export { parseCheckString, runVerification } from './infra/verification.js';
 export { triggerHook } from './plugins/hookEngine.js';
 export { createSessionState } from './session/sessionState.js';
+// 会话文件是否真实存在（含 default session 的 legacy 路径回退）：
+// cron-runner 等需要在发起回合前判断"绑定的 session 是否还在"时用它，
+// 不要绕过 legacy 回退逻辑自己拼路径。
+export { resolveSessionFile } from './context/sessionPath.js';

package/src/plugins/commandRouter.js

@@ -178,6 +178,9 @@ export function buildCommandInput(resolved) {
     }
     return input;
 }
+// 消费方是测试与宿主侧枚举（V1 红线守护测试 pluginRunner.isolation.test.ts 用它
+// 断言「非 / 输入零 discovery 副作用」；commandRouter.test.ts 断言命令清单）——
+// src 内无调用不代表死代码，勿删。
 export function listAvailableCommands() {
     const result = [];
     for (const plugin of pluginCache.values()) {

package/src/plugins/hookEngine.js

@@ -30,6 +30,7 @@
 import { spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { sanitizeCredentialEnv } from '../config/configService.js';
 const HOOK_EVENT_NAMES = new Set([
     'PreToolUse',
     'PostToolUse',
@@ -143,7 +144,7 @@ function runOneHook(hook, payload) {
             return;
         }
         const env = {
-            ...process.env,
+            ...sanitizeCredentialEnv(),
             CLAUDE_PLUGIN_ROOT: hook.pluginRoot,
         };
         let child;
@@ -183,6 +184,9 @@ function runOneHook(hook, payload) {
         child.stdout?.on('data', (data) => {
             stdout += data.toString();
         });
+        // stderr 内容不消费但必须排空：spawn 默认 pipe，无 reader 时 hook 往 stderr
+        // 写满 ~64KB 管道缓冲会阻塞，硬等到 30s 超时被 SIGTERM。
+        child.stderr?.resume();
         child.on('error', () => {
             finalize({ decision: 'pass' });
         });

package/src/plugins/pluginLifecycle.js

@@ -0,0 +1,28 @@
+import { discoverPlugins } from './commandRouter.js';
+import { loadPluginApi } from './pluginLoader.js';
+export async function activatePlugins(ctx) {
+    const manifests = await discoverPlugins();
+    const cleanups = [];
+    for (const manifest of manifests) {
+        const api = await loadPluginApi(manifest.root);
+        if (!api?.activate)
+            continue;
+        try {
+            const cleanup = await api.activate(ctx);
+            if (typeof cleanup === 'function')
+                cleanups.push(cleanup);
+        }
+        catch (err) {
+            console.warn(`[minimal-agent] plugin activate failed (${manifest.name}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return () => {
+        for (const cleanup of cleanups.reverse()) {
+            try {
+                cleanup();
+            }
+            catch {
+            }
+        }
+    };
+}

package/src/plugins/pluginLoader.js

@@ -124,7 +124,8 @@ export async function loadPluginApi(pluginRoot) {
         return null;
     }
 }
-/** 测试用：重置加载器缓存。 */
+/** 测试用：重置加载器缓存 + 绿色版内置注册表。 */
 export function _resetPluginLoader() {
     loaderCache.clear();
+    builtinApis.clear();
 }

package/src/plugins/pluginRunner.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/plugins/pluginRunner.ts —— 框架级 slash-命令分发器
+ *  src/plugins/pluginRunner.ts —— 框架级 slash-激活分发器
  * ------------------------------------------------------------
  *  通用分发器，**不含任何插件特定逻辑**。
  *
@@ -9,7 +9,8 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 当普通问句喂给 runQuery（让 LLM 自己解释 / 未知命令）
+ *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
+ *          未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 import { discoverPlugins, resolveCommand, buildCommandInput, } from './commandRouter.js';
@@ -25,36 +26,49 @@ export async function* runWithPlugins(userInput, options) {
             signal,
             maxTurns: options.maxTurns,
             sessionState: options.sessionState,
+            chat: options.chat,
+            executeTool: options.executeTool,
+            toolGate: options.toolGate,
+            transientContext: options.transientContext,
+            userAttachments: options.userAttachments,
+            imageInputs: options.imageInputs,
+            parseInlineImages: options.parseInlineImages,
+            imageDetail: options.imageDetail,
+            imageMaxLongSidePixel: options.imageMaxLongSidePixel,
+            hasQueuedInput: options.hasQueuedInput,
+            onToolStart: options.onToolStart,
+            onToolEnd: options.onToolEnd,
+            browserRun: options.browserRun,
         });
         return;
     }
-    const manifests = await discoverPlugins();
+    // 确保插件已发现（resolveCommand 依赖 pluginCache）
+    await discoverPlugins();
     const matched = resolveCommand(userInput);
     if (!matched) {
-        // 提取命令名用于错误提示
-        const cmdName = userInput.trimStart().split(/\s+/)[0]; // "/workflow" 或 "/plan"
-        // 有插件但未命中该命令 → 明确提示可用命令
-        if (manifests.length > 0) {
-            const cmdList = manifests.flatMap((m) => m.commands.map((c) => `/${c.name}`)).join('、');
-            yield {
-                type: 'error',
-                error: `未找到命令 "${cmdName}"。已安装的插件命令：${cmdList || '（无）'}。`,
-            };
-        }
-        else {
-            // 无任何插件 → 告知用户
-            yield {
-                type: 'error',
-                error: `当前未安装任何插件。命令 "${cmdName}" 无法执行。`,
-            };
-        }
-        // fallback 到普通 TAOR 对话，用户可继续操作
+        // 未命中任何插件命令 → 静默透传 runQuery。
+        // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
+        // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
+        // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
         yield* runQuery(userInput, {
             provider,
             history,
             signal,
             maxTurns: options.maxTurns,
             sessionState: options.sessionState,
+            chat: options.chat,
+            executeTool: options.executeTool,
+            toolGate: options.toolGate,
+            transientContext: options.transientContext,
+            userAttachments: options.userAttachments,
+            imageInputs: options.imageInputs,
+            parseInlineImages: options.parseInlineImages,
+            imageDetail: options.imageDetail,
+            imageMaxLongSidePixel: options.imageMaxLongSidePixel,
+            hasQueuedInput: options.hasQueuedInput,
+            onToolStart: options.onToolStart,
+            onToolEnd: options.onToolEnd,
+            browserRun: options.browserRun,
         });
         return;
     }
@@ -67,6 +81,7 @@ export async function* runWithPlugins(userInput, options) {
             signal,
             sessionState: options.sessionState,
             maxTurns: options.maxTurns,
+            transientContext: options.transientContext,
         });
         return;
     }
@@ -78,5 +93,18 @@ export async function* runWithPlugins(userInput, options) {
         signal,
         maxTurns: options.maxTurns,
         sessionState: options.sessionState,
+        chat: options.chat,
+        executeTool: options.executeTool,
+        toolGate: options.toolGate,
+        transientContext: options.transientContext,
+        userAttachments: options.userAttachments,
+        imageInputs: options.imageInputs,
+        parseInlineImages: options.parseInlineImages,
+        imageDetail: options.imageDetail,
+        imageMaxLongSidePixel: options.imageMaxLongSidePixel,
+        hasQueuedInput: options.hasQueuedInput,
+        onToolStart: options.onToolStart,
+        onToolEnd: options.onToolEnd,
+        browserRun: options.browserRun,
     });
 }

package/src/plugins/transcript.js

@@ -20,19 +20,20 @@
  * ============================================================
  */
 import { appendFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { agentStateDir } from '../context/agentHome.js';
 // 模块级状态：当前会话的 handle（lazy 初始化）
 let current = null;
 function transcriptDir() {
-    return join(homedir(), '.minimal-agent', 'transcripts');
+    return join(agentStateDir(), 'transcripts');
 }
 function generateSessionId() {
     return `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
 }
 function ensureHandle(sessionId) {
-    // 如果指定了 sessionId 且与当前不同 → 切到新文件
+    // 三分支：指定 sessionId 且与当前相同 → 复用；未指定且已有当前 → 复用；
+    // 其余（指定了不同 sessionId / 尚无当前）→ 新建句柄（即"切到新文件"）。
     if (sessionId && current && current.sessionId === sessionId) {
         return current;
     }

package/src/prompts/pluginList.js

@@ -28,17 +28,17 @@ export async function getPluginMetaList() {
  *
  * 风格对齐 skillList.formatSkillHint()：
  *   - 每个插件固定格式
- *   - 明确标注触发方式（"必须由用户输入 /xxx 触发"）
+ *   - 明确标注触发方式（"由用户通过 /xxx 激活"）
  *   - 无插件时返回空字符串（调用方自行决定是否追加）
  */
 export function formatPluginHint(plugins) {
     if (plugins.length === 0)
         return '';
     const lines = [
-        '# 可用插件（/命令）',
+        '# 可用插件（/激活）',
         '',
-        '以下是当前已安装的插件。**插件只能由用户通过 /xxx 命令触发——你绝对不能代替用户执行、模拟或建议使用插件功能**。',
-        '只有当用户明确询问"有哪些命令/插件可用"时，才列出以下内容。其他时候不要提及插件。',
+        '以下是当前已安装的插件。插件只能由用户输入 /xxx 激活——**你不能代替用户执行插件命令，也绝不能模拟/伪造插件的输出**。',
+        '当用户的需求明显匹配某个插件时（如想定时执行任务而装有 cron 类插件），可以一句话告知对应的 /xxx 命令存在，由用户自己决定是否运行；其余时候不必主动提及插件。',
         '',
     ];
     for (const p of plugins) {
@@ -46,7 +46,7 @@ export function formatPluginHint(plugins) {
         lines.push(`- **描述**: ${p.description}`);
         if (p.commands.length > 0) {
             const cmdList = p.commands.map((c) => `\`/${c.name}\``).join('、');
-            lines.push(`- **命令**: ${cmdList}`);
+            lines.push(`- **激活**: ${cmdList}`);
         }
         lines.push('');
     }

package/src/prompts/projectInstructions.js

@@ -13,9 +13,9 @@
  *  设计原则：
  *    1. 静默失败：文件不存在时不报错、不打印警告、返回 null
  *    2. 全量注入：不做截断或摘要，原样拼入 messages 数组
- *    3. 实时读取：每次 buildInitialHistory 都重新读（用户改了立即生效）
- *    4. 独立消息：作为单独的 system message 插入，
- *       不污染全局 system prompt 的 token 结构
+ *    3. 实时读取：每次组装系统提示词都重新读（用户改了立即生效）
+ *    4. 注入位置：由 assembleBasePrompt 拼进同一个 system prompt 字符串的
+ *       Layer 5（带时效性声明前缀），不是独立的 system message
  * ============================================================
  */
 import { readFile } from 'node:fs/promises';