js-agent-core 1.0.1

package/src/core/persistence/SkillLoader.ts

@@ -0,0 +1,153 @@
+import { ISkill, ITool, SkillFile, SkillMetadata } from '../../interfaces/index.js';
+import { z } from 'zod';
+
+/**
+ * 环境感知型技能加载器
+ */
+export class SkillLoader {
+  /**
+   * 将技能代码和元数据转化为可执行的 ISkill 或 ITool
+   * @param metadata 技能元数据
+   * @param files 技能文件列表
+   * @param baseDir 可选的基础目录 (用于 Node.js 子进程定位文件)
+   */
+  static async load(metadata: SkillMetadata, files: SkillFile[], baseDir?: string): Promise<ISkill> {
+    const isWeb = typeof window !== 'undefined';
+
+    switch (metadata.runtime) {
+      case 'javascript':
+        return await this.loadJavascript(metadata, files, baseDir);
+      case 'python':
+      case 'bash':
+        if (isWeb) {
+          throw new Error(`Runtime ${metadata.runtime} is not supported in the browser.`);
+        }
+        return await this.loadScriptProxy(metadata, files, baseDir!);
+      case 'wasm':
+        return await this.loadWasm(metadata, files);
+      default:
+        throw new Error(`Unsupported runtime: ${metadata.runtime}`);
+    }
+  }
+
+  /**
+   * 加载 JavaScript 技能
+   */
+  private static async loadJavascript(metadata: SkillMetadata, files: SkillFile[], baseDir?: string): Promise<ISkill> {
+    const entryFile = files.find(f => f.path === metadata.entry);
+    if (!entryFile) throw new Error(`Entry file ${metadata.entry} not found.`);
+
+    if (typeof window !== 'undefined') {
+      // Web 环境: 使用 Blob URL
+      const code = typeof entryFile.content === 'string' 
+        ? entryFile.content 
+        : new TextDecoder().decode(entryFile.content);
+      const blob = new Blob([code], { type: 'text/javascript' });
+      const url = URL.createObjectURL(blob);
+      try {
+        const module = await import(url);
+        return module.default || module;
+      } finally {
+        URL.revokeObjectURL(url);
+      }
+    } else {
+      // Node.js 环境: 优先从磁盘路径加载 (支持断点调试和完整模块解析)
+      if (baseDir) {
+        const path = await import('path');
+        const fullPath = path.join(baseDir, metadata.name, metadata.entry);
+        const module = await import(`file://${fullPath}`);
+        return module.default || module;
+      }
+
+      // 如果没有 baseDir (如内存模式)，回退到 data URI
+      const code = typeof entryFile.content === 'string' 
+        ? entryFile.content 
+        : new TextDecoder().decode(entryFile.content);
+      const base64Code = Buffer.from(code).toString('base64');
+      const dataUri = `data:text/javascript;base64,${base64Code}`;
+      const module = await import(dataUri);
+      return module.default || module;
+    }
+  }
+
+  /**
+   * 加载脚本代理 (Python, Bash)
+   */
+  private static async loadScriptProxy(metadata: SkillMetadata, files: SkillFile[], baseDir: string): Promise<ISkill> {
+    const { spawn } = await import('child_process');
+    const path = await import('path');
+
+    // 脚本代理 Skill
+    return {
+      name: metadata.name,
+      description: metadata.description,
+      tools: [{
+        name: metadata.name,
+        description: metadata.description,
+        parameters: metadata.parameters || z.any(),
+        execute: async (params: any) => {
+          const scriptPath = path.join(baseDir, metadata.name, metadata.entry);
+          
+          return new Promise((resolve) => {
+            const runtime = metadata.runtime === 'python' ? 'python3' : 'bash';
+            const child = spawn(runtime, [scriptPath]);
+
+            // 发送参数
+            child.stdin.write(JSON.stringify(params));
+            child.stdin.end();
+
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (data) => stdout += data);
+            child.stderr.on('data', (data) => stderr += data);
+
+            child.on('close', (code) => {
+              if (code !== 0) {
+                resolve({ success: false, error: `Script exited with code ${code}: ${stderr}` });
+              } else {
+                try {
+                  const result = JSON.parse(stdout);
+                  resolve({ success: true, data: result });
+                } catch {
+                  resolve({ success: true, data: stdout.trim() });
+                }
+              }
+            });
+          });
+        }
+      }]
+    };
+  }
+
+  /**
+   * 加载 WebAssembly 技能 (示意实现)
+   */
+  private static async loadWasm(metadata: SkillMetadata, files: SkillFile[]): Promise<ISkill> {
+    const entryFile = files.find(f => f.path === metadata.entry);
+    if (!entryFile) throw new Error(`WASM entry ${metadata.entry} not found.`);
+
+    const buffer = typeof entryFile.content === 'string'
+      ? new TextEncoder().encode(entryFile.content)
+      : entryFile.content;
+
+    const wasmModule = await WebAssembly.instantiate(buffer);
+    const exports = (wasmModule as any).instance?.exports || (wasmModule as any).exports;
+
+    return {
+      name: metadata.name,
+      description: metadata.description,
+      tools: [{
+        name: metadata.name,
+        description: metadata.description,
+        parameters: z.any(),
+        execute: async (params: any) => {
+          // 根据 WASM 导出函数执行逻辑
+          if (exports.run) {
+            return { success: true, data: exports.run(params) };
+          }
+          return { success: false, error: 'WASM module has no run() export' };
+        }
+      }]
+    };
+  }
+}

package/src/core/persistence/WebIndexedDbSkillStore.ts

@@ -0,0 +1,139 @@
+import { ISkillStore, SkillFile, SkillMetadata } from '../../interfaces/index.js';
+
+/**
+ * 前端实现：基于 IndexedDB 的持久化存储
+ * 数据库名: JS_AGENT_DB
+ * Store 1: skill_metadata (Key: name)
+ * Store 2: skill_files (Key: [skillName, filePath])
+ */
+export class WebIndexedDbSkillStore implements ISkillStore {
+  private dbName = 'JS_AGENT_DB';
+  private metaStore = 'skill_metadata';
+  private fileStore = 'skill_files';
+  private db: IDBDatabase | null = null;
+
+  constructor() {
+    if (typeof indexedDB === 'undefined') {
+      console.warn('IndexedDB is not supported in this environment.');
+    }
+  }
+
+  private async getDB(): Promise<IDBDatabase> {
+    if (this.db) return this.db;
+
+    return 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.metaStore)) {
+          db.createObjectStore(this.metaStore, { keyPath: 'name' });
+        }
+        if (!db.objectStoreNames.contains(this.fileStore)) {
+          db.createObjectStore(this.fileStore, { keyPath: ['skillName', 'path'] });
+        }
+      };
+
+      request.onsuccess = (event) => {
+        this.db = (event.target as IDBOpenDBRequest).result;
+        resolve(this.db!);
+      };
+
+      request.onerror = (event) => reject((event.target as IDBOpenDBRequest).error);
+    });
+  }
+
+  async saveSkill(metadata: SkillMetadata, files: SkillFile[]): Promise<void> {
+    const db = await this.getDB();
+    const tx = db.transaction([this.metaStore, this.fileStore], 'readwrite');
+
+    // 1. 保存元数据
+    tx.objectStore(this.metaStore).put(metadata);
+
+    // 2. 保存文件 (批量写入)
+    const fileStore = tx.objectStore(this.fileStore);
+    for (const file of files) {
+      fileStore.put({
+        skillName: metadata.name,
+        path: file.path,
+        content: file.content
+      });
+    }
+
+    return new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async getSkillFiles(skillName: string): Promise<SkillFile[]> {
+    const db = await this.getDB();
+    const tx = db.transaction(this.fileStore, 'readonly');
+    const store = tx.objectStore(this.fileStore);
+    const index = store.openCursor(IDBKeyRange.bound([skillName, ''], [skillName, '\uffff']));
+
+    const files: SkillFile[] = [];
+    return new Promise((resolve, reject) => {
+      index.onsuccess = (event) => {
+        const cursor = (event.target as IDBRequest<IDBCursorWithValue>).result;
+        if (cursor) {
+          files.push({
+            path: cursor.value.path,
+            content: cursor.value.content
+          });
+          cursor.continue();
+        } else {
+          resolve(files);
+        }
+      };
+      index.onerror = () => reject(tx.error);
+    });
+  }
+
+  async getSkillMetadata(skillName: string): Promise<SkillMetadata | null> {
+    const db = await this.getDB();
+    const tx = db.transaction(this.metaStore, 'readonly');
+    const request = tx.objectStore(this.metaStore).get(skillName);
+
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result || null);
+      request.onerror = () => reject(tx.error);
+    });
+  }
+
+  async listSkills(): Promise<SkillMetadata[]> {
+    const db = await this.getDB();
+    const tx = db.transaction(this.metaStore, 'readonly');
+    const request = tx.objectStore(this.metaStore).getAll();
+
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result || []);
+      request.onerror = () => reject(tx.error);
+    });
+  }
+
+  async deleteSkill(skillName: string): Promise<void> {
+    const db = await this.getDB();
+    const tx = db.transaction([this.metaStore, this.fileStore], 'readwrite');
+
+    // 1. 删除元数据
+    tx.objectStore(this.metaStore).delete(skillName);
+
+    // 2. 删除所有关联文件
+    const fileStore = tx.objectStore(this.fileStore);
+    const index = fileStore.openCursor(IDBKeyRange.bound([skillName, ''], [skillName, '\uffff']));
+
+    index.onsuccess = (event) => {
+      const cursor = (event.target as IDBRequest<IDBCursorWithValue>).result;
+      if (cursor) {
+        cursor.delete();
+        cursor.continue();
+      }
+    };
+
+    return new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+}

package/src/core/persistence/WebIndexedDbVectorStore.ts

@@ -0,0 +1,106 @@
+import { IVectorStore } from '../../interfaces/index.js';
+
+export interface WebIndexedDbVectorStoreOptions {
+  dbName?: string;
+  storeName?: string;
+}
+
+export class WebIndexedDbVectorStore implements IVectorStore {
+  private dbName: string;
+  private storeName: string;
+  private db: IDBDatabase | null = null;
+
+  constructor(options: WebIndexedDbVectorStoreOptions = {}) {
+    this.dbName = options.dbName || 'js-agent-memory';
+    this.storeName = options.storeName || 'vector-store';
+  }
+
+  private async getDB(): Promise<IDBDatabase> {
+    if (this.db) return this.db;
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+
+      request.onupgradeneeded = (event: any) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName, { autoIncrement: true });
+        }
+      };
+
+      request.onsuccess = (event: any) => {
+        this.db = event.target.result;
+        resolve(this.db!);
+      };
+
+      request.onerror = (event: any) => {
+        reject(event.target.error);
+      };
+    });
+  }
+
+  async add(text: string, embedding: number[], metadata?: Record<string, any>): Promise<void> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], 'readwrite');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.add({ text, embedding, metadata, timestamp: Date.now() });
+
+      request.onsuccess = () => resolve();
+      request.onerror = (event: any) => reject(event.target.error);
+    });
+  }
+
+  async getAll(): Promise<Array<{ text: string; embedding: number[]; metadata?: Record<string, any> }>> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], 'readonly');
+      const store = transaction.objectStore(this.storeName);
+      const request = store.getAll();
+
+      request.onsuccess = (event: any) => resolve(event.target.result);
+      request.onerror = (event: any) => reject(event.target.error);
+    });
+  }
+
+  async search(queryEmbedding: number[], topK: number = 3): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>> {
+    const items = await this.getAll();
+    const scoredItems = 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> }>> {
+    const items = await this.getAll();
+    const lowKeyword = keyword.toLowerCase();
+    
+    return 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;
+  }
+}

package/src/core/persistence/index.ts

@@ -0,0 +1,22 @@
+export * from './WebIndexedDbSkillStore.js';
+export * from './WebIndexedDbVectorStore.js';
+export * from './SkillLoader.js';
+
+// 我们不在这里使用 top-level await，以保持对旧版浏览器的兼容性
+// 如果需要 NodeFsSkillStore，用户可以直接从 ./NodeFsSkillStore.js 导入
+// 或者在运行时通过动态 import 获取
+export const getNodeFsSkillStore = async () => {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    const { NodeFsSkillStore } = await import('./NodeFsSkillStore.js');
+    return NodeFsSkillStore;
+  }
+  return null;
+};
+
+export const getNodeFsVectorStore = async () => {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    const { NodeFsVectorStore } = await import('./NodeFsVectorStore.js');
+    return NodeFsVectorStore;
+  }
+  return null;
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './interfaces/index.js';
+export * from './core/index.js';

package/src/interfaces/IAgentEvent.ts

@@ -0,0 +1,46 @@
+export type AgentEventType =
+  | 'start'
+  | 'think'
+  | 'tool.call'
+  | 'tool.call.delta'
+  | 'tool.progress'
+  | 'tool.result'
+  | 'tool.require_approval' // ✨ 新增：人机协作审批事件
+  | 'task.plan'
+  | 'task.update'
+  | 'memory.update'
+  | 'memory.usage'
+  | 'memory.add'
+  | 'agent.done'
+  | 'agent.error';
+
+// 定义外部给出的审批结果
+export interface ApprovalResult {
+  approved: boolean;      // 用户是否同意
+  feedback?: string;      // 用户的文字反馈（特别是拒绝时，如 "路径错了，应该是 /tmp"）
+  modifiedArgs?: any;     // 进阶：用户修正后的参数
+}
+
+// 审批事件的 Payload
+export interface ToolApprovalPayload {
+  toolCallId: string;     // 唯一标识这次特定的调用
+  toolName: string;
+  arguments: any;
+  resolve: (result: ApprovalResult) => void;
+  reject: (error: Error) => void;
+}
+
+export interface IAgentEvent<T = any> {
+  id: string;             // 唯一 ID，用于追踪、去重或回放
+  type: AgentEventType;
+  payload: T;
+  timestamp: number;
+  agentId?: string;       // 所属 Agent ID
+  traceId?: string;       // 追踪 ID，关联同一请求的多次事件
+}
+
+export interface IEventEmitter {
+  on<T = any>(event: AgentEventType, listener: (payload: T) => void): void;
+  off<T = any>(event: AgentEventType, listener: (payload: T) => void): void;
+  emit<T = any>(event: AgentEventType, payload: T): void;
+}

package/src/interfaces/IAgentState.ts

@@ -0,0 +1,22 @@
+import { LLMMessage } from './ILLMProvider.js';
+import { TaskList } from './IPlanner.js';
+
+export interface IAgentState {
+  history: LLMMessage[];
+  taskList?: TaskList;
+  skills: {
+    active: string[];
+    registered: string[];
+  };
+  tools: string[];
+  config: {
+    model: string;
+    routerModel?: string;
+    enableDynamicSkills: boolean;
+    maxIterations: number;
+  };
+  metadata: {
+    version: string;
+    exportedAt: string;
+  };
+}

package/src/interfaces/ILLMProvider.ts

@@ -0,0 +1,47 @@
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  name?: string;
+  tool_call_id?: string;
+  toolCalls?: Array<{
+    id: string;
+    type: 'function';
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+}
+
+export interface LLMOptions {
+  model: string;
+  temperature?: number;
+  max_tokens?: number;
+  stream?: boolean;
+  tools?: any[];
+  intent?: 'plan' | 'replan' | 'execute';
+}
+
+export interface LLMResponse {
+  content: string;
+  toolCalls?: Array<{
+    id: string;
+    type: 'function';
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+}
+
+export interface LLMResponseChunk {
+  content?: string;
+  toolCalls?: any[]; // Delta tool calls or full tool calls
+}
+
+export interface ILLMProvider {
+  generate(messages: LLMMessage[], options: LLMOptions): Promise<LLMResponse>;
+  stream?(messages: LLMMessage[], options: LLMOptions, onChunk: (chunk: LLMResponseChunk) => void): Promise<LLMResponse>;
+  embed?(text: string | string[]): Promise<number[][]>;
+}
+

package/src/interfaces/ILogger.ts

@@ -0,0 +1,16 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogContext {
+  traceId?: string;
+  agentId?: string;
+  iteration?: number;
+  toolName?: string;
+  rawPayload?: any;    // Raw LLM response/request
+  stack?: string;      // Error stack
+  latency?: number;    // Latency monitoring
+  [key: string]: any;  // Extended fields
+}
+
+export interface ILogger {
+  log(level: LogLevel, message: string, context?: LogContext): void | Promise<void>;
+}

package/src/interfaces/IMemory.ts

@@ -0,0 +1,29 @@
+import { LLMMessage } from './ILLMProvider.js';
+
+export interface MemoryOptions {
+  limit?: number;
+  metadata?: Record<string, any>;
+}
+
+export interface IMemory {
+  add(message: LLMMessage): Promise<void>;
+  getHistory(): Promise<LLMMessage[]>;
+  clear(): Promise<void>;
+  getContext?(input: string): Promise<string>;
+}
+
+export interface IVectorStore {
+  add(text: string, embedding: number[], metadata?: Record<string, any>): Promise<void>;
+  search(queryEmbedding: number[], topK?: number): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>>;
+  searchByKeyword?(keyword: string, topK?: number): Promise<Array<{ text: string; score: number; metadata?: Record<string, any> }>>;
+}
+
+export interface IEmbedder {
+  embed(text: string): Promise<number[]>;
+}
+
+export interface ILongTermMemory extends IMemory {
+  remember(input: string): Promise<void>;
+  recall(query: string): Promise<string[]>;
+}
+

package/src/interfaces/IPlanner.ts

@@ -0,0 +1,22 @@
+import { ITool } from './ITool.js';
+
+export interface Task {
+  id: string;
+  goal: string;
+  criteria: string;
+  dependsOn: string[];
+  status: 'pending' | 'in_progress' | 'completed' | 'failed';
+  result?: any;
+  error?: string;
+}
+
+export interface TaskList {
+  tasks: Task[];
+  isCompleted: boolean;
+  response?: string;
+}
+
+export interface IPlanner {
+  plan(input: string, tools: ITool[], context?: string, onChunk?: (chunk: string) => void): Promise<TaskList>;
+  replan(input: string, tools: ITool[], currentTaskList: TaskList, errorContext: string, onChunk?: (chunk: string) => void): Promise<TaskList>;
+}

package/src/interfaces/ISkill.ts

@@ -0,0 +1,9 @@
+import { ITool } from './ITool.js';
+
+export interface ISkill {
+  name: string;
+  description?: string;
+  tools: ITool[];
+  onInit?(context: any): void | Promise<void>;
+  systemPrompt?(context: any): string | Promise<string>;
+}

package/src/interfaces/ISkillStore.ts

@@ -0,0 +1,60 @@
+import { ZodSchema } from 'zod';
+
+/**
+ * 技能支持的运行环境
+ */
+export type SkillRuntime = 'javascript' | 'python' | 'bash' | 'wasm';
+
+/**
+ * 技能元数据规范 (metadata.json)
+ */
+export interface SkillMetadata {
+  name: string;
+  description: string;
+  version: string;
+  runtime: SkillRuntime;
+  entry: string;           // 入口文件路径，如 index.js 或 main.py
+  parameters?: ZodSchema;  // 参数定义的 Zod Schema (持久化时可能需要序列化为 JSON)
+  author?: 'human' | 'agent';
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * 技能文件信息
+ */
+export interface SkillFile {
+  path: string;            // 相对技能根目录的路径，如 index.js, utils/helper.py
+  content: string | Uint8Array; // 文件内容 (字符串或二进制)
+}
+
+/**
+ * 统一的技能存储接口
+ * 屏蔽 Node.js (FileSystem) 和 Web (IndexedDB) 的差异
+ */
+export interface ISkillStore {
+  /**
+   * 保存一个完整的技能包 (含多个文件)
+   */
+  saveSkill(metadata: SkillMetadata, files: SkillFile[]): Promise<void>;
+
+  /**
+   * 获取指定技能的所有文件
+   */
+  getSkillFiles(skillName: string): Promise<SkillFile[]>;
+
+  /**
+   * 获取指定技能的元数据
+   */
+  getSkillMetadata(skillName: string): Promise<SkillMetadata | null>;
+
+  /**
+   * 列出所有已存储技能的元数据
+   */
+  listSkills(): Promise<SkillMetadata[]>;
+
+  /**
+   * 删除一个技能及其所有文件
+   */
+  deleteSkill(skillName: string): Promise<void>;
+}