pigpig-agent 1.0.0

package/dist/tools/registry.js

@@ -0,0 +1,270 @@
+import { jsonSchema } from 'ai';
+import { canUseTool } from '../security/roles.js';
+import { classifyBashCommand } from '../security/bash-classifier.js';
+const DEFAULT_MAX_RESULT_CHARS = 3000; // 工具执行允许的最大输出字符数
+export class ToolRegistry {
+    tools = new Map(); // 工具列表
+    mcpClients = []; // 存放正在连接的 MCP 服务器
+    // 用三个状态变量来构成一把读写锁
+    exclusiveLock = false; // 当前是否有独占锁的持有者
+    concurrentCount = 0; // 当前共享锁的持有数
+    waitQueue = []; // 等待队列,用来阻塞等待中的 resolve 函数
+    // 已发现的工具列表
+    discoveredTools = new Set(); // 已搜到的工具列表
+    // 当前角色
+    currentRole = 'owner';
+    hookPipeline;
+    register(...tools) {
+        for (const tool of tools) {
+            this.tools.set(tool.name, tool);
+        }
+    }
+    // 切换权限角色
+    setRole(role) {
+        this.currentRole = role;
+    }
+    // 获取当前角色
+    getRole() {
+        return this.currentRole;
+    }
+    // hook 管线
+    setHookPipeline(pipeline) {
+        this.hookPipeline = pipeline;
+    }
+    unregister(name) {
+        this.discoveredTools.delete(name);
+        this.tools.delete(name);
+    }
+    async registerMCPServer(serverName, client) {
+        await client.connect(); // 连接到 MCP 服务器
+        this.mcpClients.push(client); // 存储 MCP 服务器连接
+        const tools = await client.listTools(); // 获取 MCP 服务器中的工具列表
+        const registered = [];
+        for (const tool of tools) {
+            const prefixedName = `mcp__${serverName}__${tool.name}`;
+            if (this.tools.has(prefixedName))
+                continue;
+            const toolClient = client;
+            const originalName = tool.name;
+            this.register({
+                name: prefixedName,
+                description: `[MCP:${serverName}] ${tool.description}`,
+                parameters: tool.inputSchema,
+                isConcurrencySafe: true,
+                isReadOnly: true,
+                maxResultChars: 3000,
+                shouldDefer: true,
+                searchHint: `${serverName} ${tool.name} ${tool.description}`,
+                execute: async (input) => {
+                    return toolClient.callTool(originalName, input);
+                },
+            });
+            registered.push(prefixedName);
+        }
+        return registered;
+    }
+    async closeAllMCP() {
+        for (const client of this.mcpClients) {
+            await client.close();
+        }
+        this.mcpClients = [];
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    getAll() {
+        return [...this.tools.values()];
+    }
+    // 获取共享锁
+    async acquireConcurrent() {
+        while (this.exclusiveLock) {
+            await new Promise(resolve => this.waitQueue.push(resolve));
+        }
+        this.concurrentCount++;
+    }
+    // 释放共享锁
+    releaseConcurrent() {
+        this.concurrentCount--;
+        if (this.concurrentCount === 0)
+            this.drainQueue(); // 释放共享锁后，检查是否有等待中的 resolve 函数，如果有则执行
+    }
+    // 获取独占锁
+    async acquireExclusive() {
+        while (this.exclusiveLock || this.concurrentCount > 0) {
+            await new Promise(resolve => this.waitQueue.push(resolve));
+        }
+        this.exclusiveLock = true;
+    }
+    // 释放独占锁
+    releaseExclusive() {
+        this.exclusiveLock = false;
+        this.drainQueue(); // 释放独占锁后，检查是否有等待中的 resolve 函数，如果有则执行
+    }
+    // 锁释放的时候，把等待队列中的 resolve 全部唤醒，让它们重新去抢锁
+    drainQueue() {
+        const waiting = this.waitQueue.splice(0);
+        for (const resolve of waiting) {
+            resolve();
+        }
+    }
+    toAISDKFormat() {
+        const result = {};
+        const activeTools = this.getActiveTools(); // 获取所有核心的工具
+        for (const tool of activeTools) {
+            const maxChars = tool.maxResultChars;
+            const executeFn = tool.execute;
+            const isSafe = tool.isConcurrencySafe === true;
+            const registry = this;
+            const toolName = tool.name;
+            const hookPipeline = registry.hookPipeline;
+            result[tool.name] = {
+                description: tool.description,
+                inputSchema: jsonSchema(tool.parameters),
+                execute: async (input) => {
+                    // Bash 风险检测
+                    if (toolName === 'bash' && input?.command) {
+                        const risk = classifyBashCommand(input.command);
+                        if (risk.level === 'dangerous') {
+                            return `[拒绝执行] 检测到危险操作: ${risk.reason}\n命令：${input.command}`;
+                        }
+                        if (risk.level === 'moderate') {
+                            console.log(`[安全警告] 操作: ${risk.reason}\n命令：${input.command}`);
+                        }
+                    }
+                    // pre hook
+                    if (hookPipeline) {
+                        const preResult = await hookPipeline.runPre(toolName, input);
+                        if (preResult.action === 'block') {
+                            return `[Hook 拦截] ${preResult.reason} || '操作被阻止'`;
+                        }
+                        if (preResult.action === 'modify' && preResult.modifiedInput !== undefined) {
+                            input = preResult.modifiedInput;
+                        }
+                    }
+                    // 在真正执行前，先按 isConcurrencySafe 来获取锁
+                    if (isSafe) {
+                        await registry.acquireConcurrent();
+                        console.log(`[并发] ${tool.name} 获取共享锁`);
+                    }
+                    else {
+                        await registry.acquireExclusive();
+                        console.log(`[串行] ${tool.name} 获得独占锁，等待其他工具执行`);
+                    }
+                    try {
+                        const raw = await executeFn(input);
+                        const text = typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2);
+                        let output = truncateResult(text, maxChars);
+                        // Post Hook
+                        if (hookPipeline) {
+                            const postResult = await hookPipeline.runPost(toolName, input, output);
+                            if (postResult.modifiedOutput !== undefined) {
+                                output = String(postResult.modifiedOutput);
+                            }
+                        }
+                        return output;
+                    }
+                    finally {
+                        // 无论是否成功，都释放锁
+                        if (isSafe) {
+                            registry.releaseConcurrent(); // 释放共享锁
+                        }
+                        else {
+                            registry.releaseExclusive(); // 释放独占锁
+                        }
+                    }
+                },
+            };
+        }
+        return result;
+    }
+    toAISDKFormatUnlocked(excludeTools) {
+        const result = {};
+        const activeTools = this.getActiveTools()
+            .filter(t => !excludeTools || !excludeTools.has(t.name));
+        for (const tool of activeTools) {
+            const maxChars = tool.maxResultChars;
+            const executeFn = tool.execute;
+            result[tool.name] = {
+                description: tool.description,
+                inputSchema: jsonSchema(tool.parameters),
+                execute: async (input) => {
+                    const raw = await executeFn(input);
+                    const text = typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2);
+                    return truncateResult(text, maxChars);
+                },
+            };
+        }
+        return result;
+    }
+    // 搜索工具
+    searchTools(query) {
+        const q = query.trim(); // "mcp__github__list_issues, mcp__github__get_issue"
+        const results = [];
+        // 去 Map 对象中搜索哪个值(对象) 拥有 searchHint 字段，且 searchHint 字段包含 q 字段
+        const names = q.includes(',') ? q.split(',').map(n => n.trim()).filter(Boolean) : [q];
+        for (const name of names) {
+            const tool = this.tools.get(name); // 去 Map 对象中搜索 name 对应的工具对象
+            if (tool && tool.name !== 'tool_search') {
+                results.push(tool);
+                // 记录被搜到的延迟工具
+                this.discoveredTools.add(tool.name);
+            }
+        }
+        return results;
+    }
+    // 可以被添加进Prompt中的工具
+    getActiveTools() {
+        return this.getAll().filter(tool => {
+            if (tool.shouldDefer && !this.discoveredTools.has(tool.name)) {
+                return false;
+            }
+            if (!canUseTool(this.currentRole, tool.name)) {
+                return false;
+            }
+            return true;
+        });
+    }
+    // 生成延迟工具的名字列表
+    getDeferredToolSummary() {
+        const deferred = this.getAll().filter(tool => {
+            return tool.shouldDefer && !this.discoveredTools.has(tool.name);
+        });
+        if (deferred.length === 0)
+            return '';
+        const lines = deferred.map(t => {
+            const hint = t.searchHint ? ` — ${t.searchHint}` : '';
+            return `  - ${t.name}${hint}`;
+        });
+        return `\n以下工具可用，但需要先通过 tool_search 搜索获取完整定义：\n${lines.join('\n')}`;
+    }
+    // 估算 token 
+    countTokenEstimate() {
+        let active = 0;
+        let deferred = 0;
+        for (const tool of this.getAll()) {
+            const schemaSize = JSON.stringify({
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters
+            }).length;
+            const tokens = Math.ceil(schemaSize / 4);
+            if (tool.shouldDefer && !this.discoveredTools.has(tool.name)) {
+                deferred += tokens;
+            }
+            else {
+                active += tokens;
+            }
+        }
+        return { active, deferred, total: active + deferred };
+    }
+}
+export function truncateResult(text, maxChars = DEFAULT_MAX_RESULT_CHARS) {
+    if (text.length <= maxChars)
+        return text;
+    const headSize = Math.floor(maxChars / 0.6); // 内容头部
+    const tailSize = maxChars - headSize; // 内容尾部
+    const head = text.slice(0, headSize);
+    const tail = text.slice(-tailSize);
+    const dropped = text.length - headSize - tailSize; // 被截断的字符数
+    return `${head}\n\n...[省略${dropped}个字符]\n\n${tail}`;
+}

package/dist/tools/search-tools.js

@@ -0,0 +1,116 @@
+import fg from 'fast-glob';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+// 全局搜索
+export const globTool = {
+    name: 'glob',
+    description: '按模式搜索文件。支持 * 和 ** 通配符，如 "src/**/*.ts" 匹配 src 下所有 TypeScript 文件',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: '搜索模式，如 "**/*.ts"、"src/*.json"' },
+            path: { type: 'string', description: '搜索起始目录，默认当前目录' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+    },
+    isConcurrencySafe: true,
+    isReadOnly: true,
+    execute: async ({ pattern, path = '.' }) => {
+        // ... 递归遍历目录，匹配模式 ...
+        // 自动跳过 node_modules 和 .git
+        // 结果上限 100 条，防止大项目撑爆
+        const results = await fg(pattern, {
+            cwd: resolve(path),
+            ignore: ['node_modules/**', '.git/**'],
+            dot: false,
+            onlyFiles: true,
+            followSymbolicLinks: false,
+        });
+        if (results.length === 0)
+            return `没有找到匹配 "${pattern}" 的文件`;
+        return results.sort().join('\n');
+    },
+};
+// Grep 搜索 精准匹配
+export const grepTool = {
+    name: 'grep',
+    description: '在文件中搜索匹配指定模式的内容。返回匹配的行号和内容',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: '搜索模式（正则表达式）' },
+            path: { type: 'string', description: '搜索路径（文件或目录），默认当前目录' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+    },
+    isConcurrencySafe: true,
+    isReadOnly: true,
+    maxResultChars: 3000,
+    execute: async ({ pattern, path = '.' }) => {
+        const baseDir = resolve(path);
+        const regex = new RegExp(pattern, 'i');
+        const matches = [];
+        const SKIP = new Set(['node_modules', '.git', 'dist']);
+        const BIN_EXT = new Set(['.png', '.jpg', '.gif', '.woff', '.woff2', '.ico', '.lock']);
+        function searchFile(filePath) {
+            if (matches.length >= 50)
+                return;
+            const ext = filePath.slice(filePath.lastIndexOf('.'));
+            if (BIN_EXT.has(ext))
+                return;
+            let content;
+            try {
+                content = readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                return;
+            }
+            const lines = content.split('\n');
+            const rel = relative(baseDir, filePath);
+            for (let i = 0; i < lines.length; i++) {
+                if (regex.test(lines[i])) {
+                    matches.push(`${rel}:${i + 1}: ${lines[i].trimEnd()}`);
+                    if (matches.length >= 50)
+                        return;
+                }
+            }
+        }
+        function walk(dir) {
+            if (matches.length >= 50)
+                return;
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return;
+            }
+            for (const name of entries) {
+                if (SKIP.has(name))
+                    continue;
+                const full = join(dir, name);
+                try {
+                    const stat = statSync(full);
+                    if (stat.isDirectory())
+                        walk(full);
+                    else
+                        searchFile(full);
+                }
+                catch { /* skip */ }
+            }
+        }
+        const stat = statSync(baseDir);
+        if (stat.isFile()) {
+            searchFile(baseDir);
+        }
+        else {
+            walk(baseDir);
+        }
+        if (matches.length === 0)
+            return `没有找到匹配 "${pattern}" 的内容`;
+        const suffix = matches.length >= 50 ? '\n... (结果已截断，共 50+ 条匹配)' : '';
+        return matches.join('\n') + suffix;
+    },
+};

package/dist/tools/shell-tools.js

@@ -0,0 +1,39 @@
+import { execSync } from 'node:child_process';
+// 执行 shell 命令
+export const bashTool = {
+    name: 'bash',
+    description: '执行 shell 命令并返回输出。适合运行脚本、检查环境、执行构建等操作',
+    parameters: {
+        type: 'object',
+        properties: {
+            command: { type: 'string', description: '要执行的 shell 命令' },
+        },
+        required: ['command'],
+        additionalProperties: false,
+    },
+    isConcurrencySafe: false,
+    isReadOnly: false,
+    maxResultChars: 3000,
+    execute: async ({ command }) => {
+        try {
+            execSync('echo test', { stdio: 'ignore' });
+        }
+        catch {
+            return `[bash 不可用] 当前 Sandbox 不支持 shell 命令。本地终端运行 pigpig-agent 可使用 bash 工具。`;
+        }
+        try {
+            const output = execSync(command, {
+                encoding: 'utf-8',
+                timeout: 10000,
+                maxBuffer: 1024 * 1024,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return output || '(命令执行成功，无输出)';
+        }
+        catch (err) {
+            const stderr = err.stderr || '';
+            const stdout = err.stdout || '';
+            return `命令执行失败 (exit ${err.status || 1}):\n${stderr || stdout || err.message}`;
+        }
+    },
+};

package/dist/tools/spawn-tools.js

@@ -0,0 +1,35 @@
+import { spawnAgent, spawnParallel } from '../agents/spawn.js';
+export function createSpawnTool(agentRegistry, getSpawnCtx) {
+    return {
+        name: 'spawn_agent',
+        description: '派一个子 Agent 去执行任务。子 Agent 有独立的上下文，完成后返回结果摘要。支持同时派多个子 Agent 并行执行。',
+        parameters: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: '单个任务描述（与 tasks 二选一）',
+                },
+                tasks: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '多个任务描述，并行执行（与 task 二选一）',
+                },
+            },
+        },
+        isConcurrencySafe: false,
+        isReadOnly: true,
+        execute: async (input) => {
+            const ctx = getSpawnCtx();
+            if (input.tasks && input.tasks.length > 0) {
+                const requests = input.tasks.map(t => ({ task: t }));
+                const results = await spawnParallel(requests, ctx);
+                return results.map((r, i) => `## 子 Agent ${i + 1}: ${r.task.slice(0, 40)}\n\n${r.result}`).join('\n\n---\n\n');
+            }
+            if (input.task) {
+                return spawnAgent({ task: input.task }, ctx);
+            }
+            return '需要提供 task 或 tasks 参数';
+        },
+    };
+}

package/dist/tools/tool-search.js

@@ -0,0 +1,17 @@
+export function createToolSearchTool(registry) {
+    return {
+        name: 'tool_search',
+        description: '获取延迟工具的完整定义，传入工具名(从系统提示的延迟工具列表中获取)，返回该工具的完整参数 Schema',
+        parameters: { type: 'object', properties: { query: { type: 'string', description: '工具名，如"mcp__github__list_issues"。支持逗号分隔多个工具名' } }, required: ['query'] },
+        isConcurrencySafe: true,
+        isReadOnly: true,
+        execute: async ({ query }) => {
+            const results = registry.searchTools(query); // 搜出来哪些工具的 searchHint 包含 query 字段
+            return results.map(t => ({
+                name: t.name,
+                description: t.description,
+                parameters: t.parameters,
+            }));
+        },
+    };
+}

package/dist/tools/web-search.js

@@ -0,0 +1,150 @@
+import TurndownService from 'turndown';
+// Tavily 搜索引擎
+export const tavilySearchTool = {
+    name: 'web_search',
+    description: '搜索互联网获取最新信息。返回相关网页的标题、链接和内容摘要',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: '搜索关键词',
+            },
+            max_results: {
+                type: 'number',
+                description: '返回的最大结果数量,默认5个',
+            },
+        },
+        required: ['query'],
+    },
+    isConcurrencySafe: true,
+    isReadOnly: true,
+    maxResultChars: 3000,
+    execute: async ({ query, max_results = 5 }) => {
+        const apiKey = process.env.TAVILY_API_KEY;
+        if (!apiKey)
+            return `[web_search] 未配置 Tavily API Key, 请在 .env 中配置`;
+        const res = await fetch('https://api.tavily.com/search ', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                query,
+                search_depth: 'advanced',
+                max_results,
+                include_answer: true,
+            }),
+        });
+        if (!res.ok)
+            return `[web_search] Tavily 请求失败, 状态码: ${res.status}`;
+        const data = await res.json();
+        const lines = [];
+        if (data.answer) {
+            lines.push(`## AI 摘要\n ${data.answer}`);
+        }
+        for (const r of data.results || []) {
+            lines.push(`### ${r.title}`);
+            lines.push(r.url);
+            lines.push(r.content || '');
+            lines.push('');
+        }
+        return lines.join('\n') || '没有找到相关结果';
+    },
+};
+// Serper 搜索引擎
+export const serperSearchTool = {
+    name: 'web_search',
+    description: '搜索互联网获取最新信息。返回 Google 搜索结果的标题、链接和摘要',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: '搜索关键词' },
+            max_results: { type: 'number', description: '返回结果数量，默认 5' },
+        },
+        required: ['query'],
+    },
+    isConcurrencySafe: true,
+    isReadOnly: true,
+    maxResultChars: 3000,
+    execute: async ({ query, max_results = 5 }) => {
+        const apiKey = process.env.SERPER_API_KEY;
+        if (!apiKey)
+            return '[web_search] 未配置 SERPER_API_KEY，请在 .env 中设置';
+        const res = await fetch('https://google.serper.dev/search', {
+            method: 'POST',
+            headers: {
+                'X-API-KEY': apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ q: query, num: max_results }),
+        });
+        if (!res.ok)
+            return `[web_search] 请求失败: HTTP ${res.status}`;
+        const data = await res.json();
+        const lines = [];
+        // Knowledge Graph（如果有）
+        if (data.knowledgeGraph) {
+            const kg = data.knowledgeGraph;
+            lines.push(`## ${kg.title}`);
+            if (kg.description)
+                lines.push(kg.description);
+            lines.push('');
+        }
+        // Organic Results
+        for (const r of (data.organic || []).slice(0, max_results)) {
+            lines.push(`### ${r.title}`);
+            lines.push(r.link);
+            lines.push(r.snippet || '');
+            lines.push('');
+        }
+        return lines.join('\n') || '没有找到相关结果';
+    },
+};
+// 为 Serper 搜索引擎添加 web_fetch
+export const webFetchTool = {
+    name: 'web_fetch',
+    description: '抓取指定 URL 的网页内容，转换为 Markdown 格式',
+    parameters: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: '完整 URL' },
+        },
+        required: ['url'],
+    },
+    isConcurrencySafe: true,
+    isReadOnly: true,
+    maxResultChars: 3000,
+    execute: async ({ url }) => {
+        try {
+            const res = await fetch(url, {
+                headers: { 'User-Agent': 'Mozilla/5.0 (compatible; SuperAgent/1.0)' },
+                signal: AbortSignal.timeout(15000),
+            });
+            if (!res.ok)
+                return `抓取失败: HTTP ${res.status}`;
+            const html = await res.text();
+            return htmlToMarkdown(html);
+        }
+        catch (err) {
+            return `抓取失败: ${err.message}`;
+        }
+    },
+};
+// HTML 转换为 Markdown
+const turndownService = new TurndownService({
+    headingStyle: 'atx',
+    codeBlockStyle: 'fenced',
+});
+turndownService.remove(['style', 'script', 'header', 'nav', 'footer', 'iframe']);
+function htmlToMarkdown(html) {
+    return turndownService.turndown(html);
+}
+export function pickSearchTool() {
+    if (process.env.TAVILY_API_KEY)
+        return tavilySearchTool;
+    if (process.env.SERPER_API_KEY)
+        return serperSearchTool;
+    return tavilySearchTool;
+}