@minko-ai/minko 0.1.0 → 0.1.1

package/dist/tools/notebook.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_BYTES = 5 * 1024 * 1024;
+export const notebookEditTool = {
+    readOnly: false,
+    needsApproval: (args, cwd) => {
+        const file = typeof args.path === 'string' ? args.path : '';
+        return file.length === 0 || outsideWorkspace(file, cwd);
+    },
+    spec: {
+        name: 'notebook_edit',
+        description: '编辑 Jupyter .ipynb 的单元格：replace / insert / delete。',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string' },
+                action: { type: 'string', enum: ['replace', 'insert', 'delete'] },
+                cell_index: { type: 'number', description: '0-based；insert 时是插入位置' },
+                cell_id: { type: 'string', description: '优先用 cell id 定位' },
+                cell_type: { type: 'string', enum: ['code', 'markdown', 'raw'] },
+                source: { type: 'string' },
+            },
+            required: ['path', 'action'],
+            additionalProperties: false,
+        },
+    },
+    async run(args, ctx) {
+        const rawPath = typeof args.path === 'string' ? args.path.trim() : '';
+        if (rawPath.length === 0) {
+            throw new Error('缺少 path 参数');
+        }
+        const file = path.resolve(ctx.cwd, rawPath);
+        const stat = fs.statSync(file);
+        if (stat.size > MAX_BYTES) {
+            throw new Error('notebook 太大（超过 5MB）');
+        }
+        const notebook = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!notebook || !Array.isArray(notebook.cells)) {
+            throw new Error('不是合法的 Jupyter notebook');
+        }
+        const action = typeof args.action === 'string' ? args.action : '';
+        const index = resolveIndex(notebook, args);
+        if (action === 'replace') {
+            if (index < 0 || index >= notebook.cells.length) {
+                throw new Error('cell_index 越界');
+            }
+            const source = requireSource(args);
+            notebook.cells[index] = {
+                ...notebook.cells[index],
+                source: toLines(source),
+                ...(typeof args.cell_type === 'string'
+                    ? { cell_type: args.cell_type }
+                    : {}),
+            };
+            write(file, notebook);
+            return '已替换 cell ' + index + '（' + notebook.cells[index].cell_type + '）';
+        }
+        if (action === 'insert') {
+            const at = index < 0 || index > notebook.cells.length ? notebook.cells.length : index;
+            const cellType = args.cell_type === 'markdown' || args.cell_type === 'raw'
+                ? args.cell_type
+                : 'code';
+            const cell = {
+                cell_type: cellType,
+                source: toLines(requireSource(args)),
+                metadata: {},
+                ...(cellType === 'code' ? { execution_count: null, outputs: [] } : {}),
+            };
+            notebook.cells.splice(at, 0, cell);
+            write(file, notebook);
+            return '已在位置 ' + at + ' 插入 ' + cellType + ' cell';
+        }
+        if (action === 'delete') {
+            if (index < 0 || index >= notebook.cells.length) {
+                throw new Error('cell_index 越界');
+            }
+            notebook.cells.splice(index, 1);
+            write(file, notebook);
+            return '已删除 cell ' + index;
+        }
+        throw new Error('不支持的操作：' + action);
+    },
+};
+function resolveIndex(notebook, args) {
+    if (typeof args.cell_id === 'string' && args.cell_id.trim().length > 0) {
+        return notebook.cells.findIndex((cell) => cell.id === args.cell_id);
+    }
+    return typeof args.cell_index === 'number' && Number.isFinite(args.cell_index)
+        ? Math.floor(args.cell_index)
+        : -1;
+}
+function requireSource(args) {
+    if (typeof args.source !== 'string' || args.source.length === 0) {
+        throw new Error('缺少 source 参数');
+    }
+    return args.source;
+}
+function toLines(source) {
+    const lines = source.split(/\r?\n/);
+    return lines.map((line, index) => index < lines.length - 1 ? line + '\n' : line);
+}
+function write(file, notebook) {
+    fs.writeFileSync(file, JSON.stringify(notebook, null, 1) + '\n', 'utf8');
+}
+function outsideWorkspace(file, cwd) {
+    const target = path.resolve(cwd, file);
+    const relative = path.relative(cwd, target);
+    return relative.startsWith('..') || path.isAbsolute(relative);
+}

package/dist/tools/registry.js

@@ -0,0 +1,32 @@
+import { editFileTool, listDirTool, readFileTool, writeFileTool } from "./fs.js";
+import { runShellTool } from "./shell.js";
+import { searchFilesTool } from "./search.js";
+import { retrieveContextTool } from "../rag/tool.js";
+import { lspTool } from "../lsp/tool.js";
+import { webFetchTool } from "../web/fetch.js";
+import { webSearchTool } from "../web/search.js";
+import { skillListTool, skillTool } from "../skills/index.js";
+import { notebookEditTool } from "./notebook.js";
+import { structuredOutputTool } from "./structured.js";
+export const ALL_TOOLS = [
+    readFileTool,
+    editFileTool,
+    writeFileTool,
+    listDirTool,
+    searchFilesTool,
+    retrieveContextTool,
+    lspTool,
+    webFetchTool,
+    webSearchTool,
+    skillListTool,
+    skillTool,
+    notebookEditTool,
+    structuredOutputTool,
+    runShellTool,
+];
+export function toolSpecs(tools = ALL_TOOLS) {
+    return tools.map((tool) => tool.spec);
+}
+export function findTool(name, tools = ALL_TOOLS) {
+    return tools.find((tool) => tool.spec.name === name);
+}

package/dist/tools/search.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const SKIP_DIRS = new Set(['node_modules', '.git', '.minko', '__pycache__', '.venv']);
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_RESULTS = 100;
+function resolvePath(cwd, raw) {
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    if (value.length === 0) {
+        throw new Error('缺少 path 参数');
+    }
+    return path.resolve(cwd, value);
+}
+function isBinary(file) {
+    try {
+        const fd = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(4096);
+        const read = fs.readSync(fd, buffer, 0, buffer.length, 0);
+        fs.closeSync(fd);
+        return buffer.subarray(0, read).includes(0);
+    }
+    catch {
+        return true;
+    }
+}
+export const searchFilesTool = {
+    readOnly: true,
+    spec: {
+        name: 'search_files',
+        description: '在目录里递归搜索文件内容，返回匹配的「文件:行号: 内容」。'
+            + 'pattern 按正则解析，正则写错时按普通文本匹配。用于快速定位代码，不必自己 shell 拼接。',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: '要搜索的文本或正则' },
+                path: { type: 'string', description: '搜索起点目录，默认当前工作目录' },
+                max_results: { type: 'number', description: '最多返回多少条，默认 100' },
+            },
+            required: ['pattern'],
+            additionalProperties: false,
+        },
+    },
+    async run(args, ctx) {
+        const pattern = typeof args.pattern === 'string' ? args.pattern : '';
+        if (pattern.length === 0) {
+            throw new Error('缺少 pattern 参数');
+        }
+        const root = args.path === undefined ? ctx.cwd : resolvePath(ctx.cwd, args.path);
+        const limit = typeof args.max_results === 'number' && args.max_results > 0
+            ? Math.min(Math.floor(args.max_results), MAX_RESULTS)
+            : MAX_RESULTS;
+        let matcher;
+        try {
+            const regex = new RegExp(pattern, 'i');
+            matcher = (line) => regex.test(line);
+        }
+        catch {
+            const needle = pattern.toLowerCase();
+            matcher = (line) => line.toLowerCase().includes(needle);
+        }
+        const results = [];
+        let scanned = 0;
+        const walk = (dir) => {
+            if (results.length >= limit) {
+                return;
+            }
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (results.length >= limit) {
+                    return;
+                }
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (SKIP_DIRS.has(entry.name)) {
+                        continue;
+                    }
+                    walk(full);
+                    continue;
+                }
+                if (!entry.isFile()) {
+                    continue;
+                }
+                let stat;
+                try {
+                    stat = fs.statSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (stat.size > MAX_FILE_BYTES) {
+                    continue;
+                }
+                scanned += 1;
+                if (isBinary(full)) {
+                    continue;
+                }
+                let lines;
+                try {
+                    lines = fs.readFileSync(full, 'utf8').replace(/\r\n/g, '\n').split('\n');
+                }
+                catch {
+                    continue;
+                }
+                for (let index = 0; index < lines.length; index += 1) {
+                    if (!matcher(lines[index])) {
+                        continue;
+                    }
+                    const relative = path.relative(ctx.cwd, full) || full;
+                    const text = lines[index].trim();
+                    results.push(relative + ':' + (index + 1) + ': '
+                        + (text.length > 160 ? text.slice(0, 160) + '…' : text));
+                    if (results.length >= limit) {
+                        return;
+                    }
+                }
+            }
+        };
+        walk(root);
+        if (results.length === 0) {
+            return '没有匹配（扫描了 ' + scanned + ' 个文件）';
+        }
+        const more = results.length >= limit ? '\n… 结果已达上限 ' + limit + ' 条' : '';
+        return results.join('\n') + more;
+    },
+};

package/dist/tools/shell.js

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { dockerArgs, dockerAvailable, resolveSandbox } from "../sandbox/index.js";
+const MAX_OUTPUT = 32 * 1024;
+const DEFAULT_TIMEOUT_MS = 120000;
+/** Read-only commands that never need a confirmation. */
+const SAFE_PREFIXES = [
+    'dir', 'ls', 'cd', 'pwd', 'echo', 'type', 'cat', 'head', 'tail',
+    'where', 'which', 'ver', 'set ', 'systeminfo', 'tasklist', 'hostname', 'whoami',
+    'findstr', 'find ', 'sort', 'more', 'tree', 'cls',
+    'node -v', 'node --version', 'npm -v', 'npm --version', 'npm ls', 'npm list',
+    'npm test', 'npm run test', 'npm run build', 'npm run lint', 'npm run typecheck',
+    'git status', 'git diff', 'git log', 'git show', 'git branch', 'git remote',
+    'python --version', 'python -v', 'py --version',
+];
+/** Commands that are always risky, whatever else they contain. */
+const DANGEROUS = [
+    'del ', 'erase ', 'rd ', 'rmdir', 'rm ', 'format ', 'mkfs',
+    'shutdown', 'reg delete', 'taskkill', 'sc delete',
+    'git push', 'git reset --hard', 'git clean',
+    'npm install -g', 'npm i -g', 'npm publish',
+    'curl ', 'wget ', 'invoke-webrequest', 'iwr ',
+];
+export function isSafeCommand(command) {
+    const text = command.trim().toLowerCase().replace(/\s+/g, ' ');
+    if (text.length === 0) {
+        return true;
+    }
+    if (DANGEROUS.some((prefix) => text.includes(prefix))) {
+        return false;
+    }
+    // Chaining, redirection, substitution: never treat as a read-only command.
+    if (/[>|&;`]/.test(text) || text.includes('$(') || text.includes('\n')) {
+        return false;
+    }
+    return SAFE_PREFIXES.some((prefix) => text === prefix.trim() || text.startsWith(prefix));
+}
+export const runShellTool = {
+    readOnly: false,
+    needsApproval: (args) => !isSafeCommand(typeof args.command === 'string' ? args.command : ''),
+    spec: {
+        name: 'run_shell',
+        description: '在用户的电脑上执行一条 shell 命令并返回输出。Windows 用 cmd.exe，macOS/Linux 用 sh。'
+            + '命令会在当前工作目录里执行。不要执行交互式命令（会一直等下一条输入）。',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: '要执行的命令' },
+                timeout_ms: { type: 'number', description: '超时毫秒数，默认 120000' },
+            },
+            required: ['command'],
+            additionalProperties: false,
+        },
+    },
+    async run(args, ctx) {
+        const command = typeof args.command === 'string' ? args.command.trim() : '';
+        if (command.length === 0) {
+            throw new Error('缺少 command 参数');
+        }
+        const timeout = typeof args.timeout_ms === 'number' && args.timeout_ms > 0
+            ? Math.min(Math.floor(args.timeout_ms), 600000)
+            : DEFAULT_TIMEOUT_MS;
+        return await execute(command, ctx.cwd, timeout, ctx.signal, resolveSandbox(ctx.config));
+    },
+};
+export async function execute(command, cwd, timeoutMs, signal, sandbox) {
+    let prefix = '';
+    let useDocker = false;
+    if (sandbox?.mode === 'docker') {
+        if (dockerAvailable()) {
+            useDocker = true;
+        }
+        else if (sandbox.allowFallback) {
+            prefix = '（沙箱不可用，已回退普通 shell）\n';
+        }
+        else {
+            return '沙箱不可用：Docker 没有运行。请启动 Docker，或关闭 sandbox.mode / 设置 allowFallback。';
+        }
+    }
+    // cmd.exe writes pipes in the console code page (GBK on Chinese Windows).
+    // Decode as UTF-8 first; if that fails, fall back to GB18030.
+    return await new Promise((resolve) => {
+        const child = useDocker && sandbox
+            ? spawn('docker', dockerArgs(sandbox, command, cwd), {
+                cwd,
+                shell: false,
+                windowsHide: true,
+                env: { ...process.env, MINKO: '1' },
+            })
+            : spawn(command, {
+                cwd,
+                shell: true,
+                windowsHide: true,
+                env: { ...process.env, MINKO: '1' },
+            });
+        let stdout = '';
+        let truncated = false;
+        let settled = false;
+        const outChunks = [];
+        const errChunks = [];
+        let outBytes = 0;
+        let errBytes = 0;
+        const append = (target, chunk) => {
+            if (target === 'out') {
+                if (outBytes < MAX_OUTPUT) {
+                    outChunks.push(chunk);
+                    outBytes += chunk.length;
+                }
+                else {
+                    truncated = true;
+                }
+            }
+            else {
+                if (errBytes < MAX_OUTPUT) {
+                    errChunks.push(chunk);
+                    errBytes += chunk.length;
+                }
+                else {
+                    truncated = true;
+                }
+            }
+        };
+        child.stdout?.on('data', (chunk) => append('out', chunk));
+        child.stderr?.on('data', (chunk) => append('err', chunk));
+        const finish = (tail) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            const stdout = decodeOutput(Buffer.concat(outChunks));
+            const stderr = decodeOutput(Buffer.concat(errChunks));
+            const parts = [];
+            if (stdout.trim().length > 0) {
+                parts.push(stdout.trimEnd());
+            }
+            if (stderr.trim().length > 0) {
+                parts.push('--- stderr ---\n' + stderr.trimEnd());
+            }
+            if (truncated) {
+                parts.push('（输出超过 ' + Math.floor(MAX_OUTPUT / 1024) + ' KB，已截断）');
+            }
+            if (parts.length === 0) {
+                parts.push('（没有输出）');
+            }
+            parts.push(tail);
+            resolve(prefix + parts.join('\n'));
+        };
+        const timer = setTimeout(() => {
+            killTree(child);
+            finish('退出码：-1（超过 ' + Math.round(timeoutMs / 1000) + ' 秒被终止）');
+        }, timeoutMs);
+        const onAbort = () => {
+            killTree(child);
+            finish('退出码：-1（用户中断）');
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (error) => {
+            finish('无法启动命令：' + error.message);
+        });
+        child.on('close', (code) => {
+            finish('退出码：' + (code === null ? -1 : code));
+        });
+    });
+}
+/** UTF-8 first, GB18030 when cmd.exe hands us OEM-encoded bytes. */
+export function decodeOutput(bytes) {
+    if (bytes.length === 0) {
+        return '';
+    }
+    const utf8 = bytes.toString('utf8');
+    if (!utf8.includes('�')) {
+        return utf8;
+    }
+    try {
+        return new TextDecoder('gb18030').decode(bytes);
+    }
+    catch {
+        return utf8;
+    }
+}
+function killTree(child) {
+    if (child.pid === undefined) {
+        return;
+    }
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        }
+        else {
+            child.kill('SIGTERM');
+        }
+    }
+    catch {
+        try {
+            child.kill();
+        }
+        catch { /* already gone */ }
+    }
+}

package/dist/tools/structured.js

@@ -0,0 +1,83 @@
+/** Validates the small JSON Schema subset used by tool parameters. */
+export function validateValue(value, schema, pathName = '$') {
+    const errors = [];
+    if (typeof schema.type === 'string' && !matchesType(value, schema.type)) {
+        errors.push(pathName + ' 需要是 ' + schema.type);
+        return errors;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((item) => deepEqual(item, value))) {
+        errors.push(pathName + ' 必须是 ' + JSON.stringify(schema.enum) + ' 之一');
+    }
+    if (schema.type === 'object' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const record = value;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (typeof key === 'string' && !(key in record)) {
+                    errors.push(pathName + ' 缺少字段 ' + key);
+                }
+            }
+        }
+        const properties = schema.properties;
+        if (properties !== null && typeof properties === 'object' && !Array.isArray(properties)) {
+            for (const [key, child] of Object.entries(properties)) {
+                if (!(key in record)) {
+                    continue;
+                }
+                if (child !== null && typeof child === 'object') {
+                    errors.push(...validateValue(record[key], child, pathName + '.' + key));
+                }
+            }
+        }
+    }
+    if (schema.type === 'array' && Array.isArray(value) && schema.items !== null
+        && typeof schema.items === 'object') {
+        value.forEach((item, index) => {
+            errors.push(...validateValue(item, schema.items, pathName + '[' + index + ']'));
+        });
+    }
+    return errors;
+}
+export const structuredOutputTool = {
+    readOnly: true,
+    spec: {
+        name: 'structured_output',
+        description: '把结果作为结构化 JSON 输出，并按可选 JSON Schema 校验（object/array/string/number/boolean/null、required、properties、items、enum）。',
+        parameters: {
+            type: 'object',
+            properties: {
+                data: { type: 'object', description: '要输出的 JSON 值' },
+                schema: { type: 'object', description: '可选的 JSON Schema' },
+            },
+            required: ['data'],
+            additionalProperties: false,
+        },
+    },
+    async run(args) {
+        if (!('data' in args)) {
+            throw new Error('缺少 data 参数');
+        }
+        const schema = args.schema;
+        if (schema !== null && typeof schema === 'object' && !Array.isArray(schema)) {
+            const errors = validateValue(args.data, schema);
+            if (errors.length > 0) {
+                throw new Error('结构校验失败：\n- ' + errors.join('\n- '));
+            }
+        }
+        return '结构化输出（已通过校验）：\n' + JSON.stringify(args.data, null, 2);
+    },
+};
+function matchesType(value, type) {
+    switch (type) {
+        case 'object': return value !== null && typeof value === 'object' && !Array.isArray(value);
+        case 'array': return Array.isArray(value);
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number' && Number.isFinite(value);
+        case 'integer': return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'null': return value === null;
+        default: return true;
+    }
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};