fotric-claw 0.1.0

package/backend/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "fotric-claw-backend",
+  "version": "0.1.0",
+  "description": "FotricCalw - A lightweight, transparent AI Agent system",
+  "author": "",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@langchain/community": "^0.3.0",
+    "@langchain/core": "^0.3.0",
+    "@langchain/langgraph": "^0.2.0",
+    "@langchain/openai": "^0.3.0",
+    "@nestjs/common": "^10.3.0",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^10.3.0",
+    "@nestjs/platform-express": "^10.3.0",
+    "@xenova/transformers": "^2.14.0",
+    "cheerio": "^1.0.0",
+    "front-matter": "^4.0.2",
+    "glob": "^10.3.10",
+    "html-to-text": "^9.0.5",
+    "llamaindex": "^0.4.0",
+    "pino": "^8.17.2",
+    "pino-pretty": "^10.3.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.3.0",
+    "@nestjs/schematics": "^10.1.0",
+    "@nestjs/testing": "^10.3.0",
+    "@types/express": "^4.17.21",
+    "@types/html-to-text": "^9.0.4",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.11.0",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.4",
+    "source-map-support": "^0.5.21",
+    "supertest": "^6.3.4",
+    "ts-jest": "^29.1.1",
+    "ts-loader": "^9.5.1",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.3.3"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/backend/src/agent/agent.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { AgentService } from './agent.service';
+import { MemoryModule } from '../memory';
+
+@Module({
+  imports: [MemoryModule],
+  providers: [AgentService],
+  exports: [AgentService],
+})
+export class AgentModule {}

package/backend/src/agent/agent.service.ts

@@ -0,0 +1,210 @@
+import { ChatOpenAI } from '@langchain/openai';
+import { BaseMessage, HumanMessage, AIMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { FOTRIC_CONFIG } from '../config';
+import { createCoreTools, ToolsConfig } from './tools';
+import { createLLM } from './llm.factory';
+import { MemoryService } from '../memory';
+import { SessionMessage } from '../memory/memory.types';
+
+export interface AgentState {
+  messages: BaseMessage[];
+  sessionId: string;
+}
+
+@Injectable()
+export class AgentService implements OnModuleInit {
+  private readonly logger = new Logger('FOTRIC-CLAW:Agent');
+  private toolsConfig?: ToolsConfig;
+
+  constructor(private readonly memoryService: MemoryService) {}
+
+  private getLLM(): ChatOpenAI {
+    return createLLM();
+  }
+
+  onModuleInit() {
+    this.logger.log('Agent service initialized');
+  }
+
+  setToolsConfig(config: ToolsConfig) {
+    this.toolsConfig = config;
+  }
+
+  private convertToLangChainMessages(messages: SessionMessage[]): BaseMessage[] {
+    if (!messages || !Array.isArray(messages)) {
+      return [];
+    }
+    
+    return messages.map(msg => {
+      const content = msg.content || '';
+      
+      switch (msg.role) {
+        case 'user':
+          return new HumanMessage(content);
+        case 'assistant':
+          return new AIMessage(content);
+        case 'system':
+          return new SystemMessage(content);
+        case 'tool':
+          return new ToolMessage({
+            content: content,
+            tool_call_id: msg.toolCallId || 'unknown',
+          });
+        default:
+          return new HumanMessage(content);
+      }
+    });
+  }
+
+  async *streamChat(
+    userMessage: string,
+    sessionId: string,
+    onToolCall?: (toolName: string, args: unknown) => void
+  ): AsyncGenerator<{ type: 'thought' | 'tool_call' | 'content' | 'done'; content: string; toolName?: string; toolArgs?: unknown }> {
+    this.logger.log(`Starting chat for session: ${sessionId}`);
+
+    const systemPrompt = await this.memoryService.buildSystemPrompt();
+    
+    let session = await this.memoryService.getSession(sessionId);
+    if (!session) {
+      session = await this.memoryService.createSession(sessionId);
+    }
+
+    const history = this.convertToLangChainMessages(session.messages || []);
+    
+    const tools = createCoreTools(this.toolsConfig);
+    const llm = this.getLLM();
+    const llmWithTools = llm.bindTools(tools);
+
+    const messages: BaseMessage[] = [
+      new SystemMessage(systemPrompt),
+      ...history,
+      new HumanMessage(userMessage),
+    ];
+
+    await this.memoryService.addMessageToSession(sessionId, {
+      role: 'user',
+      content: userMessage,
+    });
+
+    let iteration = 0;
+    const maxIterations = 10;
+    let lastContent = '';
+    let lastToolResult = '';
+
+    while (iteration < maxIterations) {
+      iteration++;
+      
+      try {
+        const response = await llmWithTools.invoke(messages);
+        
+        if (response.tool_calls && response.tool_calls.length > 0) {
+          for (const toolCall of response.tool_calls) {
+            const toolName = toolCall.name;
+            const toolArgs = toolCall.args;
+            
+            yield {
+              type: 'tool_call',
+              content: `Using tool: ${toolName}`,
+              toolName,
+              toolArgs,
+            };
+
+            onToolCall?.(toolName, toolArgs);
+
+            const tool = tools.find(t => t.name === toolName);
+            if (tool) {
+              try {
+                const toolResult = await tool.invoke(toolArgs);
+                lastToolResult = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
+                
+                yield {
+                  type: 'thought',
+                  content: `Tool ${toolName} result: ${lastToolResult.length > 500 
+                    ? lastToolResult.substring(0, 500) + '...' 
+                    : lastToolResult}`,
+                };
+
+                messages.push(response);
+                messages.push(new ToolMessage({
+                  content: lastToolResult,
+                  tool_call_id: toolCall.id || '',
+                }));
+              } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                messages.push(response);
+                messages.push(new ToolMessage({
+                  content: `Error: ${errorMessage}`,
+                  tool_call_id: toolCall.id || '',
+                }));
+              }
+            } else {
+              this.logger.warn(`Tool not found: ${toolName}`);
+              messages.push(response);
+              messages.push(new ToolMessage({
+                content: `Error: Tool '${toolName}' not found. Available tools: ${tools.map(t => t.name).join(', ')}`,
+                tool_call_id: toolCall.id || '',
+              }));
+            }
+          }
+        } else {
+          lastContent = typeof response.content === 'string' 
+            ? response.content 
+            : JSON.stringify(response.content);
+          
+          yield {
+            type: 'content',
+            content: lastContent,
+          };
+
+          await this.memoryService.addMessageToSession(sessionId, {
+            role: 'assistant',
+            content: lastContent,
+          });
+          
+          break;
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Agent error: ${errorMessage}`);
+        
+        yield {
+          type: 'content',
+          content: `Error: ${errorMessage}`,
+        };
+        break;
+      }
+    }
+
+    if (iteration >= maxIterations) {
+      if (lastToolResult) {
+        lastContent = `任务已执行完成。工具执行结果：${lastToolResult.length > 1000 ? lastToolResult.substring(0, 1000) + '...' : lastToolResult}`;
+      } else {
+        lastContent = '操作已完成，但未能获取明确的响应。请尝试更具体的请求。';
+      }
+      
+      yield {
+        type: 'content',
+        content: lastContent,
+      };
+
+      await this.memoryService.addMessageToSession(sessionId, {
+        role: 'assistant',
+        content: lastContent,
+      });
+    }
+
+    yield { type: 'done', content: '' };
+  }
+
+  async chat(userMessage: string, sessionId: string): Promise<string> {
+    let result = '';
+    for await (const chunk of this.streamChat(userMessage, sessionId)) {
+      if (chunk.type === 'content') {
+        result = chunk.content;
+      }
+    }
+    return result;
+  }
+}

package/backend/src/agent/index.ts

@@ -0,0 +1,4 @@
+export * from './agent.service';
+export * from './agent.module';
+export * from './llm.factory';
+export * from './tools';

package/backend/src/agent/llm.factory.ts

@@ -0,0 +1,20 @@
+import { ChatOpenAI } from '@langchain/openai';
+
+export function createLLM(options?: {
+  temperature?: number;
+  maxTokens?: number;
+}): ChatOpenAI {
+  const apiKey = process.env.FOTRIC_API_KEY || '';
+  const baseURL = process.env.FOTRIC_API_BASE_URL || 'https://api.openai.com/v1';
+  const modelName = process.env.FOTRIC_MODEL_NAME || 'gpt-4o';
+
+  return new ChatOpenAI({
+    modelName,
+    openAIApiKey: apiKey || 'placeholder',
+    configuration: {
+      baseURL,
+    },
+    temperature: options?.temperature ?? 0.7,
+    maxTokens: options?.maxTokens ?? 4096,
+  });
+}

package/backend/src/agent/tools/fetch.tool.ts

@@ -0,0 +1,128 @@
+import { Tool } from '@langchain/core/tools';
+import * as cheerio from 'cheerio';
+import { htmlToText } from 'html-to-text';
+import { FOTRIC_CONFIG } from '../../config';
+
+export interface FetchURLInput {
+  url: string;
+  selector: string;
+}
+
+export class FetchURLTool extends Tool {
+  name = 'fetch_url';
+  
+  description = `Fetch content from a URL and return it as cleaned text/markdown.
+Input should be a JSON object with a "url" field (required) and optional "selector" field.
+Example: {"url": "https://example.com"} or {"url": "https://example.com", "selector": "article"}
+Returns the extracted text content from the webpage.`;
+
+  async _call(input: string): Promise<string> {
+    let parsedInput: FetchURLInput;
+    
+    try {
+      parsedInput = JSON.parse(input);
+    } catch {
+      if (input.startsWith('http')) {
+        parsedInput = { url: input, selector: '' };
+      } else {
+        return 'Error: Invalid input. Please provide a JSON object with a "url" field.';
+      }
+    }
+
+    const { url, selector = '' } = parsedInput;
+
+    if (!url) {
+      return 'Error: URL is required.';
+    }
+
+    try {
+      new URL(url);
+    } catch {
+      return 'Error: Invalid URL format.';
+    }
+
+    try {
+      const response = await fetch(url, {
+        headers: {
+          'User-Agent': 'Mozilla/5.0 (compatible; FotricCalw/0.1.0)',
+          'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        },
+        signal: AbortSignal.timeout(30000),
+      });
+
+      if (!response.ok) {
+        return `Error: HTTP ${response.status} - ${response.statusText}`;
+      }
+
+      const contentType = response.headers.get('content-type') || '';
+      
+      if (!contentType.includes('text/html') && !contentType.includes('application/json')) {
+        const text = await response.text();
+        if (text.length > 10000) {
+          return text.substring(0, 10000) + '\n...[content truncated]';
+        }
+        return text;
+      }
+
+      const html = await response.text();
+      
+      if (contentType.includes('application/json')) {
+        try {
+          const json = JSON.parse(html);
+          const stringified = JSON.stringify(json, null, 2);
+          if (stringified.length > 10000) {
+            return stringified.substring(0, 10000) + '\n...[content truncated]';
+          }
+          return stringified;
+        } catch {
+          return html;
+        }
+      }
+
+      const $ = cheerio.load(html);
+      
+      $('script, style, nav, footer, header, aside, noscript, iframe, svg').remove();
+      
+      $('[class*="sidebar"], [class*="menu"], [class*="nav"], [class*="footer"], [class*="header"]').remove();
+      $('[id*="sidebar"], [id*="menu"], [id*="nav"], [id*="footer"], [id*="header"]').remove();
+
+      let contentElement = selector && selector.trim() ? $(selector) : $('body');
+      
+      if (contentElement.length === 0) {
+        contentElement = $('body');
+      }
+
+      const contentHtml = contentElement.html() || '';
+      
+      const text = htmlToText(contentHtml, {
+        wordwrap: false,
+        selectors: [
+          { selector: 'a', options: { ignoreHref: true } },
+          { selector: 'img', format: 'skip' },
+          { selector: 'h1', options: { uppercase: false } },
+          { selector: 'h2', options: { uppercase: false } },
+          { selector: 'h3', options: { uppercase: false } },
+        ],
+      });
+
+      const cleanedText = text
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/[ \t]{2,}/g, ' ')
+        .trim();
+
+      if (cleanedText.length > 15000) {
+        return cleanedText.substring(0, 15000) + '\n\n...[content truncated]';
+      }
+
+      return cleanedText || 'No content extracted from the page.';
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === 'AbortError' || error.message.includes('timeout')) {
+          return 'Error: Request timed out after 30 seconds.';
+        }
+        return `Error: ${error.message}`;
+      }
+      return `Error: ${String(error)}`;
+    }
+  }
+}

package/backend/src/agent/tools/file-read.tool.ts

@@ -0,0 +1,99 @@
+import { Tool } from '@langchain/core/tools';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { FOTRIC_CONFIG } from '../../config';
+
+export interface FileReadInput {
+  path: string;
+  encoding: string;
+  startLine: number;
+  endLine: number;
+}
+
+export class FileReadTool extends Tool {
+  name = 'read_file';
+  
+  description = `Read the content of a file from the local file system.
+Input should be a JSON object with a "path" field (required) and optional fields:
+- encoding: file encoding (default: utf-8)
+- startLine: start reading from this line number
+- endLine: stop reading at this line number
+Example: {"path": "./src/skills/example/SKILL.md"}
+Returns the file content or error message.`;
+
+  private rootDir: string;
+
+  constructor(options?: { rootDir?: string }) {
+    super();
+    this.rootDir = path.resolve(options?.rootDir ?? FOTRIC_CONFIG.PATHS.ROOT_DIR);
+  }
+
+  private isPathSafe(filePath: string): boolean {
+    const resolvedPath = path.resolve(this.rootDir, filePath);
+    const relativePath = path.relative(this.rootDir, resolvedPath);
+    return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+  }
+
+  async _call(input: string): Promise<string> {
+    let parsedInput: FileReadInput;
+    
+    try {
+      parsedInput = JSON.parse(input);
+    } catch {
+      parsedInput = { path: input, encoding: 'utf-8', startLine: 0, endLine: 0 };
+    }
+
+    const { path: filePath, encoding = 'utf-8', startLine = 0, endLine = 0 } = parsedInput;
+
+    if (!filePath) {
+      return 'Error: File path is required.';
+    }
+
+    if (!this.isPathSafe(filePath)) {
+      return `Error: Access denied. Path must be within the project directory: ${this.rootDir}`;
+    }
+
+    const absolutePath = path.resolve(this.rootDir, filePath);
+
+    try {
+      const stats = await fs.stat(absolutePath);
+      
+      if (stats.size > 1024 * 1024) {
+        return `Error: File is too large (${(stats.size / 1024 / 1024).toFixed(2)} MB). Maximum size is 1 MB.`;
+      }
+
+      const content = await fs.readFile(absolutePath, encoding as BufferEncoding);
+      
+      if (startLine > 0 || endLine > 0) {
+        const lines = content.split('\n');
+        const start = Math.max(0, startLine > 0 ? startLine - 1 : 0);
+        const end = endLine > 0 ? Math.min(lines.length, endLine) : lines.length;
+        const selectedLines = lines.slice(start, end);
+        return selectedLines.join('\n');
+      }
+
+      if (content.length > 50000) {
+        return content.substring(0, 50000) + '\n\n...[content truncated]';
+      }
+
+      return content;
+    } catch (error) {
+      if (error instanceof Error) {
+        if ('code' in error) {
+          const nodeError = error as NodeJS.ErrnoException;
+          if (nodeError.code === 'ENOENT') {
+            return `Error: File not found: ${filePath}`;
+          }
+          if (nodeError.code === 'EACCES') {
+            return `Error: Permission denied: ${filePath}`;
+          }
+          if (nodeError.code === 'EISDIR') {
+            return `Error: Path is a directory, not a file: ${filePath}`;
+          }
+        }
+        return `Error: ${error.message}`;
+      }
+      return `Error: ${String(error)}`;
+    }
+  }
+}

package/backend/src/agent/tools/index.ts

@@ -0,0 +1,55 @@
+export { ShellTool } from './shell.tool';
+export { NodeREPLTool } from './node-repl.tool';
+export { FetchURLTool, type FetchURLInput } from './fetch.tool';
+export { FileReadTool, type FileReadInput } from './file-read.tool';
+export { HybridRetrievalTool, type SearchKnowledgeInput } from './rag.tool';
+
+import { ShellTool } from './shell.tool';
+import { NodeREPLTool } from './node-repl.tool';
+import { FetchURLTool } from './fetch.tool';
+import { FileReadTool } from './file-read.tool';
+import { HybridRetrievalTool } from './rag.tool';
+import { DynamicModule, Provider } from '@nestjs/common';
+
+export interface ToolsConfig {
+  shell?: { timeout?: number; cwd?: string };
+  repl?: { timeout?: number };
+  fetch?: {};
+  fileRead?: { rootDir?: string };
+  rag?: { knowledgeDir?: string; storageDir?: string };
+}
+
+export const TOOLS_CONFIG = 'TOOLS_CONFIG';
+
+export const coreToolsProviders: Provider[] = [
+  {
+    provide: ShellTool,
+    useFactory: (config?: ToolsConfig) => new ShellTool(config?.shell),
+  },
+  {
+    provide: NodeREPLTool,
+    useFactory: (config?: ToolsConfig) => new NodeREPLTool(config?.repl),
+  },
+  {
+    provide: FetchURLTool,
+    useFactory: () => new FetchURLTool(),
+  },
+  {
+    provide: FileReadTool,
+    useFactory: (config?: ToolsConfig) => new FileReadTool(config?.fileRead),
+  },
+  {
+    provide: HybridRetrievalTool,
+    useFactory: (config?: ToolsConfig) => new HybridRetrievalTool(config?.rag),
+  },
+];
+
+export function createCoreTools(config?: ToolsConfig) {
+  return [
+    new ShellTool(config?.shell),
+    new NodeREPLTool(config?.repl),
+    new FetchURLTool(),
+    new FileReadTool(config?.fileRead),
+    new HybridRetrievalTool(config?.rag),
+  ];
+}

package/backend/src/agent/tools/node-repl.tool.ts

@@ -0,0 +1,82 @@
+import { Tool } from '@langchain/core/tools';
+import { createContext, runInContext } from 'node:vm';
+import { FOTRIC_CONFIG } from '../../config';
+
+export class NodeREPLTool extends Tool {
+  name = 'node_repl';
+  
+  description = `Execute JavaScript code in a sandboxed Node.js environment.
+Input should be valid JavaScript code.
+The sandbox provides access to common globals like console, Math, JSON, Array, Object, etc.
+File system and network access are restricted.
+Returns the result of the code execution or error message.`;
+
+  private timeout: number;
+  private context: Record<string, unknown>;
+
+  constructor(options?: { timeout?: number }) {
+    super();
+    this.timeout = options?.timeout ?? FOTRIC_CONFIG.REPL.TIMEOUT;
+    this.context = this.createSandboxContext();
+  }
+
+  private createSandboxContext(): Record<string, unknown> {
+    const sandbox: Record<string, unknown> = {};
+    
+    for (const globalName of FOTRIC_CONFIG.REPL.ALLOWED_GLOBALS) {
+      if (globalName in global) {
+        sandbox[globalName] = (global as Record<string, unknown>)[globalName];
+      }
+    }
+    
+    sandbox['setTimeout'] = setTimeout;
+    sandbox['setInterval'] = setInterval;
+    sandbox['clearTimeout'] = clearTimeout;
+    sandbox['clearInterval'] = clearInterval;
+    
+    return sandbox;
+  }
+
+  async _call(code: string): Promise<string> {
+    try {
+      const wrappedCode = `
+        (async () => {
+          ${code}
+        })()
+      `;
+      
+      const vmContext = createContext(this.context);
+      
+      const result = await runInContext(wrappedCode, vmContext, {
+        timeout: this.timeout,
+        displayErrors: true,
+      });
+      
+      if (result === undefined) {
+        return 'undefined';
+      }
+      
+      if (typeof result === 'string') {
+        return result;
+      }
+      
+      try {
+        const stringified = JSON.stringify(result, null, 2);
+        if (stringified && stringified.length > 10000) {
+          return stringified.substring(0, 10000) + '\n...[result truncated]';
+        }
+        return stringified;
+      } catch {
+        return String(result);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes('timeout')) {
+          return `Error: Code execution timed out after ${this.timeout}ms`;
+        }
+        return `Error: ${error.message}`;
+      }
+      return `Error: ${String(error)}`;
+    }
+  }
+}