js-agent-core 1.0.1

package/src/core/StructuredPlanner.ts

@@ -0,0 +1,165 @@
+import { IPlanner, TaskList, ITool, ILLMProvider, LLMMessage, LLMResponse } from '../interfaces/index.js';
+
+export class StructuredPlanner implements IPlanner {
+  private provider: ILLMProvider;
+  private model: string;
+  private stream: boolean;
+
+  constructor(provider: ILLMProvider, model: string, stream: boolean = true) {
+    this.provider = provider;
+    this.model = model;
+    this.stream = stream;
+  }
+
+  async plan(input: string, tools: ITool[], context?: string, onChunk?: (chunk: string) => void): Promise<TaskList> {
+    const systemPrompt = this.getPlanningSystemPrompt(tools);
+    const messages: LLMMessage[] = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `User Input: ${input}\nContext: ${context || 'None'}` }
+    ];
+
+    let response: LLMResponse;
+    let fullContent = '';
+
+    if (this.provider.stream && this.stream) {
+      response = await this.provider.stream(messages, {
+        model: this.model,
+        temperature: 0,
+        stream: true,
+        intent: 'plan',
+      }, (chunk) => {
+        if (chunk.content) {
+          fullContent += chunk.content;
+          if (onChunk) onChunk(chunk.content);
+        }
+      });
+    } else {
+      response = await this.provider.generate(messages, {
+        model: this.model,
+        temperature: 0,
+        stream: false,
+        intent: 'plan',
+      });
+      fullContent = response.content;
+    }
+
+    try {
+      const taskList = JSON.parse(this.cleanJsonResponse(fullContent));
+      return this.validateAndNormalizeTaskList(taskList);
+    } catch (error: any) {
+      console.error('Failed to parse planning response:', fullContent);
+      throw new Error(`Planning failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async replan(input: string, tools: ITool[], currentTaskList: TaskList, errorContext: string, onChunk?: (chunk: string) => void): Promise<TaskList> {
+    const systemPrompt = this.getPlanningSystemPrompt(tools);
+    const messages: LLMMessage[] = [
+      { role: 'system', content: systemPrompt },
+      { 
+        role: 'user', 
+        content: `
+Original Input: ${input}
+Current Task List: ${JSON.stringify(currentTaskList)}
+Execution Error/Feedback: ${errorContext}
+Please provide a revised task list to solve the original input considering the error.` 
+      }
+    ];
+
+    let response: LLMResponse;
+    let fullContent = '';
+    if (this.provider.stream && this.stream) {
+      response = await this.provider.stream(messages, {
+        model: this.model,
+        temperature: 0,
+        stream: true,
+        intent: 'replan',
+      }, (chunk) => {
+        if (chunk.content) {
+          fullContent += chunk.content;
+          if (onChunk) onChunk(chunk.content);
+        }
+      });
+    } else {
+      response = await this.provider.generate(messages, {
+        model: this.model,
+        temperature: 0,
+        stream: false,
+        intent: 'replan',
+      });
+      fullContent = response.content;
+    }
+
+    try {
+      const taskList = JSON.parse(this.cleanJsonResponse(fullContent));
+      return this.validateAndNormalizeTaskList(taskList);
+    } catch (error: any) {
+      console.error('Failed to parse planning response:', fullContent);
+      throw new Error(`Planning failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private getPlanningSystemPrompt(tools: ITool[], context?: string): string {
+    const toolDescriptions = tools.map(t => `${t.name}: ${t.description}`).join('\n');
+    return `You are a structured planner for an AI agent.
+Your goal is to break down a complex user request into a sequence of goal-oriented tasks.
+
+AVAILABLE TOOLS (for your awareness of what's possible, but DO NOT assign tools to tasks):
+${toolDescriptions}
+
+${context ? `CONTEXT:\n${context}\n` : ''}
+
+PLANNING RULES:
+1. Break down the request into discrete tasks.
+2. For each task, clearly describe its 'goal'.
+3. For each task, define strict 'criteria' (Definition of Done) - how will the execution engine know this task is completed? The criteria must be objective and verifiable.
+4. Define dependencies between tasks (e.g., task 2 depends on task 1's result).
+5. If the user's request is a simple greeting or doesn't require any tasks, set 'isCompleted' to true and provide a direct response in the 'response' field.
+6. Provide your plan in JSON format.
+
+Thinking Process:
+You should ALWAYS wrap your internal thinking process in <think> tags before the JSON output. 
+Example:
+<think>The user just said hello. This doesn't require any tools. I will provide a direct greeting response.</think>
+{"tasks": [], "isCompleted": true, "response": "Hello! How can I help you today?"}
+
+JSON STRUCTURE:
+{
+  "tasks": [
+    { "id": "1", "goal": "...", "criteria": "...", "dependsOn": [] },
+    ...
+  ],
+  "isCompleted": false,
+  "response": "optional response string"
+}`;
+  }
+
+  private cleanJsonResponse(content: string): string {
+    // 1. Remove <think> tags and their content
+    let cleaned = content.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+
+    // 2. Try to extract content from markdown code blocks (handling any language tag like json, javascript, etc.)
+    const codeBlockRegex = /```(?:[a-zA-Z]*)\s*([\s\S]*?)\s*```/;
+    const match = cleaned.match(codeBlockRegex);
+    if (match) {
+      cleaned = match[1].trim();
+    }
+
+    // 3. Fallback: extract the JSON object by finding the first '{' and last '}'
+    // This is useful if the model includes text before/after the JSON or if markdown extraction is messy.
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start !== -1 && end !== -1 && end > start) {
+      cleaned = cleaned.substring(start, end + 1);
+    }
+
+    return cleaned.trim();
+  }
+
+  private validateAndNormalizeTaskList(data: any): TaskList {
+    if (!data.tasks || !Array.isArray(data.tasks)) {
+      throw new Error('Invalid task list format: missing tasks array');
+    }
+    return data;
+  }
+}

package/src/core/ToolRegistry.ts

@@ -0,0 +1,89 @@
+import { ITool, ISkill, ToolResult } from '../interfaces/index.js';
+import { ZodError } from 'zod';
+
+export class ToolRegistry {
+  private tools: Map<string, ITool> = new Map();
+
+  registerTool(tool: ITool): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool with name '${tool.name}' is already registered.`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  registerSkill(skill: ISkill): void {
+    skill.tools.forEach(tool => {
+      this.registerTool(tool);
+    });
+  }
+
+  getTool(name: string): ITool | undefined {
+    return this.tools.get(name);
+  }
+
+  getAllTools(): ITool[] {
+    return Array.from(this.tools.values());
+  }
+
+  hasTool(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * 校验并执行工具
+   * @param name 工具名称
+   * @param argsRaw 原始参数字符串或对象
+   * @param context 执行上下文
+   * @param onProgress 进度反馈回调
+   */
+  async validateAndExecute(
+    name: string, 
+    argsRaw: string | object, 
+    context?: any, 
+    onProgress?: (percent: number, message: string) => void
+  ): Promise<ToolResult> {
+    const tool = this.getTool(name);
+    if (!tool) {
+      return {
+        success: false,
+        error: `Tool '${name}' not found.`
+      };
+    }
+
+    let args: any;
+    try {
+      args = typeof argsRaw === 'string' ? JSON.parse(argsRaw) : argsRaw;
+    } catch (e) {
+      return {
+        success: false,
+        error: `Invalid JSON format in tool arguments: ${tool.name}. Please ensure you provide a valid JSON object.`
+      };
+    }
+
+    try {
+      // 使用 zod 进行校验
+      const validatedArgs = tool.parameters.parse(args);
+      return await tool.execute(validatedArgs, context, onProgress);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        // 格式化 zod 错误，提供更智能的修复建议
+        const issues = error.issues.map(issue => {
+          const path = issue.path.join('.');
+          return `- [${path}]: ${issue.message} (Expected ${issue.code})`;
+        }).join('\n');
+
+        const suggestion = `The parameters for tool '${name}' are invalid.\n\nIssues found:\n${issues}\n\nPlease correct these parameters and try again. Ensure the arguments match the required schema: ${JSON.stringify((tool.parameters as any)._def.typeName || 'Object Schema')}`;
+        
+        return {
+          success: false,
+          error: suggestion
+        };
+      }
+
+      return {
+        success: false,
+        error: `Validation failed for tool '${name}': ${(error as Error).message}`
+      };
+    }
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,16 @@
+export * from './BaseAgent.js';
+export * from './EventEmitter.js';
+export * from './ToolRegistry.js';
+export * from './OpenAIProvider.js';
+export * from './SimpleMemory.js';
+export * from './LongTermMemory.js';
+export * from './LocalEmbedder.js';
+export * from './MemoryVectorStore.js';
+export * from './AutoVectorStore.js';
+export * from './StructuredPlanner.js';
+export * from './AgentDashboard.js';
+export * from './persistence/index.js';
+export * from './persistence/NodeFsSkillStore.js';
+
+
+

package/src/core/logging/CompositeLogger.ts

@@ -0,0 +1,26 @@
+import { ILogger, LogLevel, LogContext } from '../../interfaces/index.js';
+
+export class CompositeLogger implements ILogger {
+  private loggers: ILogger[];
+
+  constructor(loggers: ILogger[]) {
+    this.loggers = loggers.filter(Boolean);
+  }
+
+  log(level: LogLevel, message: string, context?: LogContext): void {
+    for (const logger of this.loggers) {
+      try {
+        const result = logger.log(level, message, context);
+        if (result instanceof Promise) {
+          result.catch(err => console.error('CompositeLogger item failed:', err));
+        }
+      } catch (err) {
+        console.error('CompositeLogger item failed synchronously:', err);
+      }
+    }
+  }
+
+  addLogger(logger: ILogger) {
+    this.loggers.push(logger);
+  }
+}

package/src/core/logging/NodeFsLogger.ts

@@ -0,0 +1,53 @@
+import { ILogger, LogLevel, LogContext } from '../../interfaces/index.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export class NodeFsLogger implements ILogger {
+  private logDir: string;
+  private currentFile: string;
+
+  constructor(options: { logDir?: string } = {}) {
+    this.logDir = options.logDir || path.join(process.cwd(), 'logs');
+    this.currentFile = path.join(this.logDir, `agent-${new Date().toISOString().split('T')[0]}.log`);
+    this.init();
+  }
+
+  private init() {
+    if (!fs.existsSync(this.logDir)) {
+      fs.mkdirSync(this.logDir, { recursive: true });
+    }
+  }
+
+  log(level: LogLevel, message: string, context?: LogContext): void {
+    const timestamp = new Date().toISOString();
+    const logEntry = {
+      timestamp,
+      level,
+      message,
+      ...context
+    };
+
+    const logLine = JSON.stringify(logEntry) + '\n';
+    
+    // 使用同步追加以简化，但在高并发场景下建议使用流
+    try {
+      fs.appendFileSync(this.currentFile, logLine);
+    } catch (err) {
+      console.error('Failed to write to log file:', err);
+    }
+
+    // 同时输出到控制台以便开发调试
+    const color = this.getColor(level);
+    console.log(`${color}[${timestamp}] [${level.toUpperCase()}] ${message}\x1b[0m`, context || '');
+  }
+
+  private getColor(level: LogLevel): string {
+    switch (level) {
+      case 'debug': return '\x1b[90m'; // Gray
+      case 'info': return '\x1b[32m';  // Green
+      case 'warn': return '\x1b[33m';  // Yellow
+      case 'error': return '\x1b[31m'; // Red
+      default: return '\x1b[0m';
+    }
+  }
+}

package/src/core/logging/WebIndexedDbLogger.ts

@@ -0,0 +1,76 @@
+import { ILogger, LogLevel, LogContext } from '../../interfaces/index.js';
+
+export class WebIndexedDbLogger implements ILogger {
+  private dbName: string;
+  private storeName: string;
+  private db: IDBDatabase | null = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(options: { dbName?: string; storeName?: string } = {}) {
+    this.dbName = options.dbName || 'js-agent-logs';
+    this.storeName = options.storeName || 'logs';
+    this.init();
+  }
+
+  private init(): Promise<void> {
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          const store = db.createObjectStore(this.storeName, { autoIncrement: true });
+          store.createIndex('timestamp', 'timestamp', { unique: false });
+          store.createIndex('level', 'level', { unique: false });
+          store.createIndex('traceId', 'traceId', { unique: false });
+          store.createIndex('agentId', 'agentId', { unique: false });
+        }
+      };
+
+      request.onsuccess = (event) => {
+        this.db = (event.target as IDBOpenDBRequest).result;
+        resolve();
+      };
+
+      request.onerror = (event) => {
+        console.error('IndexedDB error:', (event.target as IDBOpenDBRequest).error);
+        reject((event.target as IDBOpenDBRequest).error);
+      };
+    });
+
+    return this.initPromise;
+  }
+
+  async log(level: LogLevel, message: string, context?: LogContext): Promise<void> {
+    await this.init();
+    if (!this.db) return;
+
+    const timestamp = new Date().toISOString();
+    const logEntry = {
+      timestamp,
+      level,
+      message,
+      ...context
+    };
+
+    const transaction = this.db.transaction([this.storeName], 'readwrite');
+    const store = transaction.objectStore(this.storeName);
+    store.add(logEntry);
+
+    // 浏览器环境下通常也需要 Console 输出
+    const color = this.getColor(level);
+    console.log(`${color}[${timestamp}] [${level.toUpperCase()}] ${message}\x1b[0m`, context || '');
+  }
+
+  private getColor(level: LogLevel): string {
+    switch (level) {
+      case 'debug': return '\x1b[90m'; // Gray
+      case 'info': return '\x1b[32m';  // Green
+      case 'warn': return '\x1b[33m';  // Yellow
+      case 'error': return '\x1b[31m'; // Red
+      default: return '\x1b[0m';
+    }
+  }
+}

package/src/core/logging/index.ts

@@ -0,0 +1,35 @@
+import { ILogger } from '../../interfaces/index.js';
+
+export class LoggerFactory {
+  /**
+   * 根据当前运行环境创建默认的持久化日志记录器
+   */
+  static async createDefaultLogger(): Promise<ILogger | null> {
+    // 1. 探测 Node.js 环境
+    if (typeof process !== 'undefined' && process.versions?.node) {
+      try {
+        const { NodeFsLogger } = await import('./NodeFsLogger.js');
+        return new NodeFsLogger();
+      } catch (e) {
+        console.warn('Failed to initialize NodeFsLogger, falling back to console:', e);
+      }
+    }
+
+    // 2. 探测浏览器环境 (支持 IndexedDB)
+    if (typeof window !== 'undefined' && typeof indexedDB !== 'undefined') {
+      try {
+        const { WebIndexedDbLogger } = await import('./WebIndexedDbLogger.js');
+        return new WebIndexedDbLogger();
+      } catch (e) {
+        console.warn('Failed to initialize WebIndexedDbLogger, falling back to console:', e);
+      }
+    }
+
+    // 3. 回退逻辑：如果没有任何持久化环境（如某些极简 Sandbox），返回 null，BaseAgent 会默认使用 console
+    return null;
+  }
+}
+
+export * from './NodeFsLogger.js';
+export * from './WebIndexedDbLogger.js';
+export * from './CompositeLogger.js';

package/src/core/persistence/NodeFsSkillStore.ts

@@ -0,0 +1,138 @@
+import { ISkillStore, SkillFile, SkillMetadata } from '../../interfaces/index.js';
+
+/**
+ * 后端实现：基于文件系统的目录隔离存储
+ */
+export class NodeFsSkillStore implements ISkillStore {
+  constructor(private baseDir: string = '') {
+    if (!this.baseDir) {
+      // 延迟加载 path 以避免浏览器报错
+      this.initDefaultDir();
+    }
+  }
+
+  private async initDefaultDir() {
+    if (typeof process !== 'undefined' && process.versions?.node) {
+      const path = await import('path');
+      this.baseDir = path.join(process.cwd(), 'storage', 'skills');
+    }
+  }
+
+  private async ensureDir(dir: string): Promise<void> {
+    const fs = await import('fs/promises');
+    try {
+      await fs.access(dir);
+    } catch {
+      await fs.mkdir(dir, { recursive: true });
+    }
+  }
+
+  private async getSkillDir(skillName: string): Promise<string> {
+    const path = await import('path');
+    return path.join(this.baseDir, skillName);
+  }
+
+  async saveSkill(metadata: SkillMetadata, files: SkillFile[]): Promise<void> {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    
+    const skillDir = await this.getSkillDir(metadata.name);
+    await this.ensureDir(skillDir);
+
+    // 1. 保存元数据
+    const metaPath = path.join(skillDir, 'metadata.json');
+    await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2), 'utf-8');
+
+    // 2. 保存所有文件
+    for (const file of files) {
+      const filePath = path.join(skillDir, file.path);
+      const fileDir = path.dirname(filePath);
+      await this.ensureDir(fileDir);
+
+      if (typeof file.content === 'string') {
+        await fs.writeFile(filePath, file.content, 'utf-8');
+      } else {
+        // Uint8Array is directly supported by fs.writeFile in Node.js
+        await fs.writeFile(filePath, file.content);
+      }
+    }
+  }
+
+  async getSkillFiles(skillName: string): Promise<SkillFile[]> {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    
+    const skillDir = await this.getSkillDir(skillName);
+    const files: SkillFile[] = [];
+
+    const readDirRecursive = async (currentDir: string, relativePath: string = '') => {
+      const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        const relPath = path.join(relativePath, entry.name);
+
+        if (entry.name === 'metadata.json' && relativePath === '') continue; // 跳过元数据文件
+
+        if (entry.isDirectory()) {
+          await readDirRecursive(fullPath, relPath);
+        } else {
+          const buffer = await fs.readFile(fullPath);
+          // Convert Buffer to Uint8Array to satisfy the interface
+          const content = new Uint8Array(buffer);
+          files.push({
+            path: relPath,
+            content: content
+          });
+        }
+      }
+    };
+
+    try {
+      await readDirRecursive(skillDir);
+    } catch (e) {
+      console.error(`Failed to read files for skill ${skillName}:`, e);
+    }
+
+    return files;
+  }
+
+  async getSkillMetadata(skillName: string): Promise<SkillMetadata | null> {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    
+    const metaPath = path.join(await this.getSkillDir(skillName), 'metadata.json');
+    try {
+      const content = await fs.readFile(metaPath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  async listSkills(): Promise<SkillMetadata[]> {
+    const fs = await import('fs/promises');
+    await this.ensureDir(this.baseDir);
+    const skillNames = await fs.readdir(this.baseDir);
+    const results: SkillMetadata[] = [];
+
+    for (const name of skillNames) {
+      const meta = await this.getSkillMetadata(name);
+      if (meta) {
+        results.push(meta);
+      }
+    }
+
+    return results;
+  }
+
+  async deleteSkill(skillName: string): Promise<void> {
+    const fs = await import('fs/promises');
+    const skillDir = await this.getSkillDir(skillName);
+    try {
+      await fs.rm(skillDir, { recursive: true, force: true });
+    } catch (e) {
+      console.error(`Failed to delete skill ${skillName}:`, e);
+    }
+  }
+}

package/src/core/persistence/NodeFsVectorStore.ts

@@ -0,0 +1,86 @@
+import { IVectorStore } from '../../interfaces/index.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+export interface NodeFsVectorStoreOptions {
+  storagePath?: string;
+}
+
+export class NodeFsVectorStore implements IVectorStore {
+  private items: Array<{ text: string; embedding: number[]; metadata?: Record<string, any> }> = [];
+  private storagePath: string;
+
+  constructor(options: NodeFsVectorStoreOptions = {}) {
+    this.storagePath = options.storagePath || path.join(process.cwd(), '.agent_data', 'vector_store.json');
+  }
+
+  private async ensureDirectory(): Promise<void> {
+    const dir = path.dirname(this.storagePath);
+    try {
+      await fs.access(dir);
+    } catch {
+      await fs.mkdir(dir, { recursive: true });
+    }
+  }
+
+  private async load(): Promise<void> {
+    try {
+      const data = await fs.readFile(this.storagePath, 'utf-8');
+      this.items = JSON.parse(data);
+    } catch {
+      this.items = [];
+    }
+  }
+
+  private async save(): Promise<void> {
+    await this.ensureDirectory();
+    await fs.writeFile(this.storagePath, JSON.stringify(this.items, null, 2), 'utf-8');
+  }
+
+  async add(text: string, embedding: number[], metadata?: Record<string, any>): Promise<void> {
+    await this.load();
+    this.items.push({ text, embedding, metadata });
+    await this.save();
+  }
+
+  async search(queryEmbedding: number[], topK: number = 3): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>> {
+    await this.load();
+    const scoredItems = this.items.map(item => ({
+      ...item,
+      score: this.cosineSimilarity(queryEmbedding, item.embedding)
+    }));
+
+    return scoredItems
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK)
+      .map(({ text, score, metadata }) => ({ text, score, metadata }));
+  }
+
+  async searchByKeyword(keyword: string, topK: number = 3): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>> {
+    await this.load();
+    const lowKeyword = keyword.toLowerCase();
+    
+    return this.items
+      .filter(item => item.text.toLowerCase().includes(lowKeyword))
+      .map(item => ({
+        text: item.text,
+        score: 1.0,
+        metadata: item.metadata
+      }))
+      .slice(0, topK);
+  }
+
+  private cosineSimilarity(vecA: number[], vecB: number[]): number {
+    if (vecA.length !== vecB.length) return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < vecA.length; i++) {
+      dotProduct += vecA[i] * vecB[i];
+      normA += vecA[i] * vecA[i];
+      normB += vecB[i] * vecB[i];
+    }
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+  }
+}