min-agent 0.1.0 → 0.1.1

package/README.md

@@ -5,10 +5,16 @@
 
 ## 安装
 
+需要本机已安装 **Node.js 20+**（LTS）。`npm install -g` 与 `npx -y min-agent` 使用发布包内的 **编译产物**，**不要求安装 Bun**。
+
 ```bash
 npm install -g min-agent
+# 或
+npx -y min-agent --help
 ```
 
+从本仓库开发时：先执行 `npm install` 与 `npm run build`，再运行 `node bin/min-agent.js …`（或继续用 `bun run src/cli.ts` 做开发）。
+
 ## 快速开始
 
 ```bash

package/bin/min-agent.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env bun
-import "../src/cli.ts"
+#!/usr/bin/env node
+import "../dist/cli.js"

package/dist/agent.d.ts

@@ -0,0 +1,23 @@
+import { type ModelMessage, type LanguageModelUsage } from "ai";
+/** Build user message content, optionally with images */
+export declare function buildUserContent(message: string, imagePaths?: string[]): Promise<any>;
+/** Single-shot: send one message, get response, exit */
+export declare function runAgent(message: string, modelId?: string, imagePaths?: string[]): Promise<void>;
+/** Interactive multi-turn chat session */
+export declare function runChat(modelId?: string, resumeSessionId?: string): Promise<void>;
+/** When set, `runOnce` does not write to TTY; use for HTTP / programmatic callers. */
+export interface RunOnceCallbacks {
+    onAssistantDisplayDelta?: (delta: string) => void;
+    onThinkingDelta?: (delta: string) => void;
+    onToolCall?: (toolName: string, input: unknown) => void;
+    onToolResult?: (toolName: string, output: unknown) => void;
+    onCompaction?: (line: string) => void;
+    onStreamError?: (message: string) => void;
+    onRunFinish?: (info: {
+        stepCount: number;
+        usage: LanguageModelUsage | undefined;
+        hasError: boolean;
+        aborted: boolean;
+    }) => void;
+}
+export declare function runOnce(messages: ModelMessage[], instructions: string[], modelId?: string, abortSignal?: AbortSignal, callbacks?: RunOnceCallbacks): Promise<void>;

package/dist/agent.js

@@ -0,0 +1,566 @@
+import { streamText, stepCountIs } from "ai";
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+import { resolveModel } from "./provider.js";
+import { createTools } from "./tools/index.js";
+import { initMcp, shutdownMcp, getMcpTools, loadMcpConfig, getMcpStatus } from "./mcp.js";
+import { discoverSkills, getSkillsTool, getSkillsSystemPrompt, getSkills } from "./skills.js";
+import { loadInstructions } from "./instructions.js";
+import { getMemorySystemPrompt, getMemoryTools } from "./memory.js";
+import { needsCompaction, compactMessages, estimateTokens } from "./compaction.js";
+import { loadPluginTools } from "./plugins.js";
+import { MarkdownRenderer } from "./markdown.js";
+import { ThinkingBodySplitter, stripThinkingFromAssistantText } from "./assistant-stream.js";
+import { printHeader, printDivider, printToolCall, printToolResult, printDone } from "./output.js";
+import readline from "readline";
+const MAX_STEPS = 30;
+function dimStyle() {
+    if ("NO_COLOR" in process.env)
+        return { dim: "", reset: "" };
+    return { dim: "\x1b[90m", reset: "\x1b[0m" };
+}
+/** Shown immediately so the terminal does not look frozen while MCP / rules load. */
+function printInitLoading() {
+    const { dim, reset } = dimStyle();
+    console.log(`${dim}⟳ 正在初始化（MCP、技能、规则）…${reset}`);
+}
+function printInitReady() {
+    const { dim, reset } = dimStyle();
+    console.log(`${dim}✓ 就绪${reset}`);
+}
+/** Stream thinking to stderr (dim). Set MIN_AGENT_SHOW_THINKING=0 to hide. */
+function writeThinkingDelta(text) {
+    if (!text)
+        return;
+    if (process.env.MIN_AGENT_SHOW_THINKING === "0" || process.env.MIN_AGENT_SHOW_THINKING === "false")
+        return;
+    const noColor = "NO_COLOR" in process.env;
+    const dim = noColor ? "" : "\x1b[2m";
+    const reset = noColor ? "" : "\x1b[0m";
+    process.stderr.write(`${dim}${text}${reset}`);
+}
+function buildSystemPrompt(instructions) {
+    const parts = [
+        `You are a helpful coding agent. You can read files, write files, run shell commands, search the web, and search the codebase to help the user with software engineering tasks.`,
+        "",
+        "Be concise and direct. When you run a command, briefly explain why.",
+        "Use the available tools to complete tasks. When multiple independent operations are needed, call tools in parallel.",
+        "When the user asks about current events, news, or anything requiring up-to-date information, use the web_search tool.",
+        "",
+        `Working directory: ${process.cwd()}`,
+        `Platform: ${process.platform}`,
+        `Date: ${new Date().toDateString()}`,
+        "",
+        "min-agent: when the user asks to configure or install this agent (MCP, skills, rules, CLI, HTTP API, etc.), use the **read** tool on `README.md` in the working directory first, then follow what it says.",
+    ];
+    const skillsPrompt = getSkillsSystemPrompt();
+    if (skillsPrompt) {
+        parts.push("", skillsPrompt);
+    }
+    const memoryPrompt = getMemorySystemPrompt();
+    if (memoryPrompt) {
+        parts.push("", memoryPrompt);
+    }
+    if (instructions.length > 0) {
+        parts.push("", "# User Instructions", "");
+        parts.push(...instructions);
+    }
+    return parts.join("\n");
+}
+/** Build user message content, optionally with images */
+export async function buildUserContent(message, imagePaths) {
+    if (!imagePaths || imagePaths.length === 0)
+        return message;
+    const parts = [{ type: "text", text: message }];
+    for (const imgPath of imagePaths) {
+        const resolved = path.resolve(process.cwd(), imgPath);
+        if (!existsSync(resolved)) {
+            console.error(`\x1b[33m  Warning: Image not found: ${imgPath}\x1b[0m`);
+            continue;
+        }
+        const data = readFileSync(resolved);
+        const ext = path.extname(resolved).toLowerCase();
+        const mimeMap = {
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".gif": "image/gif",
+            ".webp": "image/webp",
+        };
+        const mimeType = mimeMap[ext] ?? "image/png";
+        parts.push({
+            type: "image",
+            image: data,
+            mimeType,
+        });
+        console.log(`\x1b[90m  📎 ${imgPath}\x1b[0m`);
+    }
+    return parts;
+}
+/** Single-shot: send one message, get response, exit */
+export async function runAgent(message, modelId, imagePaths) {
+    printHeader(modelId);
+    printDivider();
+    printInitLoading();
+    await initMcp();
+    discoverSkills();
+    const instructions = await loadInstructions();
+    printInitReady();
+    console.log(`\x1b[36m> ${message}\x1b[0m\n`);
+    const content = await buildUserContent(message, imagePaths);
+    const messages = [{ role: "user", content }];
+    await runOnce(messages, instructions, modelId);
+    await shutdownMcp();
+}
+/** Interactive multi-turn chat session */
+export async function runChat(modelId, resumeSessionId) {
+    printHeader(modelId);
+    printDivider();
+    printInitLoading();
+    await initMcp();
+    discoverSkills();
+    const instructions = await loadInstructions();
+    printInitReady();
+    let messages = [];
+    let sessionId = resumeSessionId;
+    // Resume existing session
+    if (resumeSessionId) {
+        const { loadSession } = await import("./sessions.js");
+        const session = loadSession(resumeSessionId);
+        if (session) {
+            messages = session.messages;
+            sessionId = resumeSessionId;
+            console.log(`\x1b[90m  Resumed session: ${session.meta.title} (${messages.length} messages)\x1b[0m`);
+        }
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: "\x1b[36m> \x1b[0m",
+    });
+    // Handle Ctrl+C: abort current generation, don't exit
+    let abortController = null;
+    process.on("SIGINT", () => {
+        if (abortController) {
+            abortController.abort();
+            abortController = null;
+            console.log("\n\x1b[90m(interrupted)\x1b[0m\n");
+            rl.prompt();
+        }
+        else {
+            // No active generation, exit
+            console.log();
+            rl.close();
+        }
+    });
+    console.log("\x1b[90m输入消息开始对话，输入 /help 查看命令，/exit 退出\x1b[0m\n");
+    rl.prompt();
+    for await (const line of rl) {
+        const input = line.trim();
+        if (!input) {
+            rl.prompt();
+            continue;
+        }
+        // Handle slash commands
+        if (input.startsWith("/")) {
+            const handled = await handleSlashCommand(input, messages, instructions, modelId, rl);
+            if (handled === "exit")
+                break;
+            rl.prompt();
+            continue;
+        }
+        console.log();
+        messages.push({ role: "user", content: input });
+        abortController = new AbortController();
+        await runOnce(messages, instructions, modelId, abortController.signal);
+        abortController = null;
+        console.log();
+        rl.prompt();
+    }
+    // Auto-save session on exit
+    if (messages.length > 0) {
+        const { saveSession } = await import("./sessions.js");
+        sessionId = saveSession(messages, sessionId);
+        console.log(`\x1b[90m  Session saved: ${sessionId}\x1b[0m`);
+    }
+    rl.close();
+    printDivider();
+    console.log("\x1b[90mBye!\x1b[0m");
+    await shutdownMcp();
+}
+async function handleSlashCommand(input, messages, instructions, modelId, rl) {
+    const [cmd, ...rest] = input.slice(1).split(/\s+/);
+    const arg = rest.join(" ");
+    switch (cmd) {
+        case "exit":
+        case "quit":
+        case "q":
+            return "exit";
+        case "clear":
+            messages.length = 0;
+            console.log("\x1b[90m  ✓ Conversation cleared\x1b[0m");
+            return "handled";
+        case "compact":
+            if (messages.length < 4) {
+                console.log("\x1b[90m  Not enough messages to compact\x1b[0m");
+            }
+            else {
+                console.log("\x1b[90m  ⟳ Compacting...\x1b[0m");
+                const model = resolveModel(modelId);
+                const result = await compactMessages(messages, model, { keepRecentTurns: 2 });
+                messages.length = 0;
+                messages.push(...result.messages);
+                console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
+            }
+            return "handled";
+        case "model":
+            if (arg) {
+                const config = await import("./config.js");
+                const cfg = config.loadConfig();
+                if (cfg.provider) {
+                    cfg.provider.defaultModel = arg;
+                    config.saveConfig(cfg);
+                    console.log(`\x1b[90m  ✓ Default model set to: ${arg}\x1b[0m`);
+                }
+            }
+            else {
+                const config = await import("./config.js");
+                const cfg = config.loadConfig();
+                console.log(`\x1b[90m  Current model: ${cfg.provider?.defaultModel ?? "not set"}\x1b[0m`);
+            }
+            return "handled";
+        case "models": {
+            const config = await import("./config.js");
+            const cfg = config.loadConfig();
+            if (!cfg.provider?.baseURL || !cfg.provider?.apiKey) {
+                console.log("\x1b[90m  Not configured. Run: min-agent setup\x1b[0m");
+                return "handled";
+            }
+            console.log("\x1b[90m  Fetching models...\x1b[0m");
+            const models = await config.fetchModels(cfg.provider.baseURL, cfg.provider.apiKey);
+            if (models.length === 0) {
+                console.log("\x1b[90m  No models found or unable to fetch model list\x1b[0m");
+            }
+            else {
+                console.log(`\x1b[90m  Available models (${models.length}):\x1b[0m`);
+                for (const m of models) {
+                    const marker = m === cfg.provider.defaultModel ? " ← default" : "";
+                    console.log(`\x1b[90m  - ${m}${marker}\x1b[0m`);
+                }
+            }
+            return "handled";
+        }
+        case "memory":
+            if (arg) {
+                const { addMemory } = await import("./memory.js");
+                addMemory(arg);
+                console.log(`\x1b[90m  ✓ Memory saved: "${arg}"\x1b[0m`);
+            }
+            else {
+                const { loadMemories } = await import("./memory.js");
+                const memories = loadMemories();
+                if (memories.length === 0) {
+                    console.log("\x1b[90m  No memories stored\x1b[0m");
+                }
+                else {
+                    for (let i = 0; i < memories.length; i++) {
+                        const m = memories[i];
+                        const tags = m.tags.length > 0 ? ` [${m.tags.join(", ")}]` : "";
+                        console.log(`\x1b[90m  #${i + 1}: ${m.content}${tags}\x1b[0m`);
+                    }
+                }
+            }
+            return "handled";
+        case "skills": {
+            discoverSkills();
+            const skills = getSkills();
+            if (skills.length === 0) {
+                console.log("\x1b[90m  No skills found\x1b[0m");
+            }
+            else {
+                console.log(`\x1b[90m  Available skills (${skills.length}):\x1b[0m`);
+                for (const skill of skills) {
+                    console.log(`\x1b[90m  - ${skill.name}: ${skill.description}\x1b[0m`);
+                }
+            }
+            return "handled";
+        }
+        case "mcp": {
+            const config = loadMcpConfig();
+            const servers = Object.entries(config.mcpServers);
+            if (servers.length === 0) {
+                console.log("\x1b[90m  No MCP servers configured\x1b[0m");
+            }
+            else {
+                const status = getMcpStatus();
+                console.log(`\x1b[90m  MCP servers (${servers.length}):\x1b[0m`);
+                for (const [name, cfg] of servers) {
+                    const disabled = cfg.enabled === false;
+                    const connected = status[name]?.connected ?? false;
+                    const toolCount = status[name]?.tools.length ?? 0;
+                    const state = disabled ? "disabled" : connected ? "connected" : "disconnected";
+                    const toolsText = toolCount > 0 ? `, ${toolCount} tools` : "";
+                    console.log(`\x1b[90m  - ${name}: ${state}${toolsText}\x1b[0m`);
+                }
+            }
+            return "handled";
+        }
+        case "tokens":
+            console.log(`\x1b[90m  Estimated tokens in context: ${estimateTokens(messages)}\x1b[0m`);
+            console.log(`\x1b[90m  Messages: ${messages.length}\x1b[0m`);
+            return "handled";
+        case "help":
+            console.log(`\x1b[90m  Slash commands:
+  /clear          Clear conversation history
+  /compact        Force context compaction
+  /model [name]   Show or change current model
+  /models         List available models from provider
+  /memory [text]  List memories or save a new one
+  /skills         List discovered skills
+  /mcp            List MCP servers and connection status
+  /tokens         Show estimated token usage
+  /help           Show this help
+  /exit           Exit the chat\x1b[0m`);
+            return "handled";
+        default:
+            console.log(`\x1b[90m  Unknown command: /${cmd}. Type /help for available commands.\x1b[0m`);
+            return "handled";
+    }
+}
+export async function runOnce(messages, instructions, modelId, abortSignal, callbacks) {
+    const model = resolveModel(modelId);
+    const api = !!callbacks;
+    // Auto-compact if context is getting too large
+    if (needsCompaction(messages)) {
+        if (api) {
+            callbacks.onCompaction?.("compacting_start");
+        }
+        else {
+            console.log("\x1b[90m⟳ Compacting context...\x1b[0m");
+        }
+        const result = await compactMessages(messages, model);
+        if (result.compacted) {
+            messages.length = 0;
+            messages.push(...result.messages);
+            if (api) {
+                callbacks.onCompaction?.(`compacted_ok estimated_tokens=${estimateTokens(messages)}`);
+            }
+            else {
+                console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
+            }
+        }
+    }
+    // Merge all tools: builtin + MCP + skill + memory + plugins
+    const builtinTools = createTools();
+    const mcpTools = getMcpTools();
+    const memoryTools = getMemoryTools();
+    const pluginTools = await loadPluginTools();
+    const skills = getSkills();
+    const allTools = { ...builtinTools, ...memoryTools, ...pluginTools };
+    for (const [id, t] of Object.entries(mcpTools)) {
+        allTools[id] = t;
+    }
+    if (skills.length > 0) {
+        allTools["skill"] = getSkillsTool();
+    }
+    let stepCount = 0;
+    let hasError = false;
+    const result = streamText({
+        model,
+        system: buildSystemPrompt(instructions),
+        messages,
+        tools: allTools,
+        stopWhen: stepCountIs(MAX_STEPS),
+        maxRetries: 3,
+        abortSignal,
+        onStepFinish() {
+            stepCount++;
+        },
+        onError() { },
+    });
+    Promise.resolve(result.usage).catch(() => { });
+    let rawText = "";
+    let assistantText = "";
+    const md = new MarkdownRenderer();
+    const thinkingSplit = new ThinkingBodySplitter();
+    const emitThinking = (t) => {
+        if (!t)
+            return;
+        if (callbacks?.onThinkingDelta)
+            callbacks.onThinkingDelta(t);
+        else
+            writeThinkingDelta(t);
+    };
+    try {
+        for await (const event of result.fullStream) {
+            switch (event.type) {
+                case "text-delta": {
+                    const { display, thinking } = thinkingSplit.feed(event.text);
+                    emitThinking(thinking);
+                    if (display) {
+                        rawText += display;
+                        assistantText += display;
+                        if (callbacks?.onAssistantDisplayDelta)
+                            callbacks.onAssistantDisplayDelta(display);
+                        else {
+                            const formatted = md.write(display);
+                            if (formatted)
+                                process.stdout.write(formatted);
+                        }
+                    }
+                    break;
+                }
+                case "tool-call": {
+                    const splitFlush = thinkingSplit.flush();
+                    emitThinking(splitFlush.thinking);
+                    if (splitFlush.display) {
+                        rawText += splitFlush.display;
+                        assistantText += splitFlush.display;
+                        if (callbacks?.onAssistantDisplayDelta)
+                            callbacks.onAssistantDisplayDelta(splitFlush.display);
+                        else {
+                            const extra = md.write(splitFlush.display);
+                            if (extra)
+                                process.stdout.write(extra);
+                        }
+                    }
+                    if (!callbacks) {
+                        const flushed = md.flush();
+                        if (flushed)
+                            process.stdout.write(flushed);
+                        if (rawText.trim())
+                            console.log();
+                    }
+                    rawText = "";
+                    if (callbacks?.onToolCall)
+                        callbacks.onToolCall(event.toolName, event.input);
+                    else
+                        printToolCall(event.toolName, event.input);
+                    break;
+                }
+                case "tool-result":
+                    if (callbacks?.onToolResult)
+                        callbacks.onToolResult(event.toolName, event.output);
+                    else
+                        printToolResult(event.toolName, event.output);
+                    break;
+                case "error":
+                    hasError = true;
+                    const errorMsg = String(event.error);
+                    if (callbacks?.onStreamError) {
+                        callbacks.onStreamError(errorMsg);
+                    }
+                    else if (errorMsg.includes("Forbidden") || errorMsg.includes("Unauthorized") || errorMsg.includes("API key")) {
+                        console.error(`\x1b[31mAuthentication error: Check your API key.\x1b[0m`);
+                    }
+                    else {
+                        console.error(`\x1b[31mError: ${errorMsg}\x1b[0m`);
+                    }
+                    break;
+                case "finish":
+                    break;
+            }
+        }
+        const splitEnd = thinkingSplit.flush();
+        emitThinking(splitEnd.thinking);
+        if (splitEnd.display) {
+            rawText += splitEnd.display;
+            assistantText += splitEnd.display;
+            if (callbacks?.onAssistantDisplayDelta)
+                callbacks.onAssistantDisplayDelta(splitEnd.display);
+            else {
+                const tail = md.write(splitEnd.display);
+                if (tail)
+                    process.stdout.write(tail);
+            }
+        }
+        if (!callbacks) {
+            const remaining = md.flush();
+            if (remaining)
+                process.stdout.write(remaining);
+            if (rawText.trim())
+                console.log();
+        }
+        const cleanedAssistant = stripThinkingFromAssistantText(assistantText);
+        if (cleanedAssistant.trim()) {
+            messages.push({ role: "assistant", content: cleanedAssistant });
+        }
+        let usage;
+        try {
+            usage = await result.usage;
+        }
+        catch {
+            usage = undefined;
+        }
+        if (callbacks?.onRunFinish) {
+            callbacks.onRunFinish({ stepCount, usage, hasError, aborted: false });
+        }
+        else {
+            if (hasError) {
+                printDivider();
+                return;
+            }
+            printDivider();
+            printDone(stepCount, usage);
+        }
+    }
+    catch (err) {
+        if (!callbacks && rawText.trim())
+            console.log();
+        if (err.name === "AbortError" || abortSignal?.aborted) {
+            const splitAbort = thinkingSplit.flush();
+            emitThinking(splitAbort.thinking);
+            if (splitAbort.display) {
+                assistantText += splitAbort.display;
+                if (callbacks?.onAssistantDisplayDelta)
+                    callbacks.onAssistantDisplayDelta(splitAbort.display);
+                else {
+                    const w = md.write(splitAbort.display);
+                    if (w)
+                        process.stdout.write(w);
+                }
+            }
+            if (!callbacks)
+                process.stdout.write(md.flush());
+            const cleaned = stripThinkingFromAssistantText(assistantText);
+            if (cleaned.trim()) {
+                messages.push({ role: "assistant", content: cleaned });
+            }
+            let usage;
+            try {
+                usage = await result.usage;
+            }
+            catch {
+                usage = undefined;
+            }
+            callbacks?.onRunFinish?.({ stepCount, usage, hasError: false, aborted: true });
+            return;
+        }
+        if (!callbacks)
+            printDivider();
+        const msg = err.message ?? String(err);
+        if (callbacks?.onStreamError) {
+            callbacks.onStreamError(msg);
+        }
+        else if (msg.includes("API key") || msg.includes("Unauthorized") || msg.includes("Forbidden")) {
+            console.error(`\x1b[31mAuthentication error: Check your API key.\x1b[0m`);
+        }
+        else if (msg.includes("429") || msg.includes("rate limit") || msg.includes("Rate limit")) {
+            console.error(`\x1b[31mRate limited after retries. Please wait and try again.\x1b[0m`);
+        }
+        else if (msg.includes("timeout") || msg.includes("ETIMEDOUT") || msg.includes("ECONNRESET")) {
+            console.error(`\x1b[31mNetwork error (retries exhausted): ${msg}\x1b[0m`);
+        }
+        else {
+            console.error(`\x1b[31mError: ${msg}\x1b[0m`);
+        }
+        let usage;
+        try {
+            usage = await result.usage;
+        }
+        catch {
+            usage = undefined;
+        }
+        callbacks?.onRunFinish?.({ stepCount, usage, hasError: true, aborted: false });
+    }
+}

package/dist/assistant-stream.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Split "thinking" fragments (inline XML-style blocks some models leak into text)
+ * from displayable assistant text. Thinking is emitted to stderr; display goes to Markdown.
+ */
+/**
+ * Incremental filter: feed raw model text deltas; get display text (for stdout / history)
+ * and thinking text (for stderr). Handles tags split across chunks.
+ */
+export declare class ThinkingBodySplitter {
+    private buf;
+    feed(chunk: string): {
+        display: string;
+        thinking: string;
+    };
+    /** End of stream: flush remainder; incomplete thinking block → stderr only. */
+    flush(): {
+        display: string;
+        thinking: string;
+    };
+    private drain;
+}
+/** Final strip for assistant message (complete tags only). */
+export declare function stripThinkingFromAssistantText(text: string): string;