@agenticc/core 1.0.0

package/README.zh-CN.md

@@ -0,0 +1,372 @@
+# Agentic
+
+[![npm version](https://img.shields.io/npm/v/@agenticc/core.svg)](https://www.npmjs.com/package/@agenticc/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/Chajian/agentic/workflows/CI/badge.svg)](https://github.com/Chajian/agentic/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+
+[English](./README.md) | 简体中文
+
+一个智能 AI 智能体框架，支持 LLM、ReAct 模式执行、RAG 知识检索和可扩展工具系统。
+
+## 特性
+
+- 🤖 **多 LLM 支持**: OpenAI、Anthropic Claude、Google Gemini
+- 🔧 **工具调用系统**: 内置 ReAct 模式实现自主推理
+- 📚 **RAG 知识库**: 语义搜索和文档检索
+- 💬 **无状态架构**: 灵活的对话管理
+- 📝 **审计日志**: 完整的操作跟踪
+- 🔌 **插件系统**: 可扩展的自定义工具架构
+- ⚡ **流式支持**: 实时响应流
+- 🎯 **意图解析**: 智能请求理解
+
+## 安装
+
+```bash
+npm install @agenticc/core
+```
+
+## 快速开始
+
+```typescript
+import { Agent, ToolRegistry } from '@agenticc/core';
+
+// 使用 OpenAI 初始化智能体
+const agent = new Agent({
+  llm: {
+    provider: 'openai',
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4',
+  },
+});
+
+// 定义一个工具
+agent.tools.register({
+  name: 'get_weather',
+  description: '获取某个地点的天气信息',
+  parameters: {
+    type: 'object',
+    properties: {
+      location: { type: 'string' },
+    },
+    required: ['location'],
+  },
+  execute: async (params) => {
+    // 实现你的工具逻辑
+    return `${params.location} 的天气: ...`;
+  },
+});
+
+// 使用智能体（无状态 - 从你的存储传入历史记录）
+const response = await agent.chat('纽约的天气怎么样？', {
+  history: [], // 从数据库加载
+});
+console.log(response);
+```
+
+## 配置
+
+### LLM 提供商
+
+#### OpenAI
+```typescript
+new Agent({
+  llm: {
+    provider: 'openai',
+    apiKey: 'sk-...',
+    model: 'gpt-4',
+  },
+});
+```
+
+#### Anthropic Claude
+```typescript
+new Agent({
+  llm: {
+    provider: 'anthropic',
+    apiKey: 'sk-ant-...',
+    model: 'claude-3-opus-20240229',
+  },
+});
+```
+
+#### Google Gemini
+```typescript
+new Agent({
+  llm: {
+    provider: 'openai', // 使用 OpenAI 适配器兼容 Gemini API
+    apiKey: process.env.GEMINI_API_KEY,
+    model: 'gemini-pro',
+    baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+  },
+});
+```
+
+### 工具注册表
+
+```typescript
+const tools = new ToolRegistry();
+
+// 注册单个工具
+tools.register({
+  name: 'calculator',
+  description: '执行数学计算',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: { type: 'string' },
+    },
+    required: ['expression'],
+  },
+  execute: async ({ expression }) => {
+    return eval(expression);
+  },
+});
+
+// 批量注册工具
+tools.registerBatch([tool1, tool2, tool3]);
+```
+
+## 核心概念
+
+### 无状态架构
+
+Agentic 采用无状态设计 - 它不存储对话历史。你需要：
+
+1. 从你的数据库/存储加载历史记录
+2. 将历史记录传递给 `chat()` 方法
+3. 将新消息保存回你的存储
+
+```typescript
+// 从数据库加载
+const history = await db.getMessages(sessionId);
+
+// 处理消息
+const response = await agent.chat(userMessage, {
+  sessionId,
+  history
+});
+
+// 保存到数据库
+await db.saveMessage(sessionId, {
+  role: 'user',
+  content: userMessage
+});
+await db.saveMessage(sessionId, {
+  role: 'assistant',
+  content: response.message
+});
+```
+
+### 插件系统
+
+插件允许你将相关工具组织在一起：
+
+```typescript
+const weatherPlugin = {
+  name: 'weather',
+  version: '1.0.0',
+  description: '天气相关工具',
+  tools: [
+    {
+      name: 'get_current_weather',
+      description: '获取当前天气',
+      parameters: [...],
+      execute: async (params) => { ... }
+    },
+    {
+      name: 'get_forecast',
+      description: '获取天气预报',
+      parameters: [...],
+      execute: async (params) => { ... }
+    }
+  ]
+};
+
+await agent.loadPlugin(weatherPlugin);
+```
+
+### 流式响应
+
+```typescript
+const stream = await agent.chatStream('给我讲个故事', {
+  sessionId: 'user-123',
+  history: []
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === 'content') {
+    process.stdout.write(chunk.content);
+  }
+}
+```
+
+### 事件监听
+
+```typescript
+agent.on('tool:start', (event) => {
+  console.log(`开始执行工具: ${event.toolName}`);
+});
+
+agent.on('tool:end', (event) => {
+  console.log(`工具执行完成: ${event.toolName}`);
+  console.log(`结果: ${event.result}`);
+});
+
+agent.on('error', (event) => {
+  console.error(`错误: ${event.error.message}`);
+});
+```
+
+## 高级用法
+
+### 多 LLM 配置
+
+为不同任务使用不同的 LLM：
+
+```typescript
+const agent = new Agent({
+  llm: {
+    mode: 'multi',
+    models: {
+      fast: {
+        provider: 'openai',
+        model: 'gpt-3.5-turbo',
+        apiKey: process.env.OPENAI_API_KEY
+      },
+      smart: {
+        provider: 'anthropic',
+        model: 'claude-3-opus-20240229',
+        apiKey: process.env.ANTHROPIC_API_KEY
+      }
+    },
+    default: 'fast'
+  }
+});
+
+// 为特定任务使用特定模型
+const response = await agent.chat('复杂问题', {
+  llmModel: 'smart'
+});
+```
+
+### RAG 知识库
+
+```typescript
+import { KnowledgeStore } from '@agenticc/core';
+
+const knowledge = new KnowledgeStore();
+
+// 添加文档
+await knowledge.addDocument({
+  id: 'doc1',
+  content: '关于产品的重要信息...',
+  metadata: { source: 'manual', page: 1 }
+});
+
+// 搜索相关文档
+const results = await knowledge.search('产品特性', {
+  limit: 5,
+  threshold: 0.7
+});
+
+// 在智能体中使用
+const agent = new Agent({
+  llm: { ... },
+  knowledge
+});
+```
+
+### 自定义工具验证
+
+```typescript
+tools.register({
+  name: 'send_email',
+  description: '发送电子邮件',
+  parameters: {
+    type: 'object',
+    properties: {
+      to: { type: 'string', format: 'email' },
+      subject: { type: 'string', minLength: 1 },
+      body: { type: 'string' }
+    },
+    required: ['to', 'subject', 'body']
+  },
+  validate: async (params) => {
+    // 自定义验证逻辑
+    if (!params.to.endsWith('@company.com')) {
+      throw new Error('只能发送到公司邮箱');
+    }
+  },
+  execute: async (params) => {
+    // 发送邮件
+  }
+});
+```
+
+## API 参考
+
+### Agent
+
+主要的智能体类。
+
+#### 构造函数
+
+```typescript
+new Agent(config: AgentConfig)
+```
+
+#### 方法
+
+- `chat(message: string, options?: ChatOptions): Promise<AgentResponse>`
+- `chatStream(message: string, options?: ChatOptions): AsyncIterator<StreamChunk>`
+- `loadPlugin(plugin: Plugin): Promise<void>`
+- `unloadPlugin(pluginName: string): void`
+
+### ToolRegistry
+
+管理工具注册和执行。
+
+#### 方法
+
+- `register(tool: Tool): void`
+- `registerBatch(tools: Tool[]): void`
+- `unregister(toolName: string): void`
+- `get(toolName: string): Tool | undefined`
+- `list(): Tool[]`
+
+### KnowledgeStore
+
+管理文档和语义搜索。
+
+#### 方法
+
+- `addDocument(doc: Document): Promise<void>`
+- `addDocuments(docs: Document[]): Promise<void>`
+- `search(query: string, options?: SearchOptions): Promise<SearchResult[]>`
+- `delete(docId: string): Promise<void>`
+
+## 示例
+
+查看 [examples](./examples/) 目录获取完整示例：
+
+- [基础聊天机器人](./examples/basic-chatbot/)
+- [带工具的智能体](./examples/agent-with-tools/)
+- [RAG 系统](./examples/rag-system/)
+- [多 LLM 路由](./examples/multi-llm/)
+- [流式响应](./examples/streaming/)
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎贡献！请查看我们的[贡献指南](../../CONTRIBUTING.zh-CN.md)。
+
+## 支持
+
+- **文档**: https://chajian.github.io/agentic/
+- **Issues**: https://github.com/Chajian/agentic/issues
+- **讨论**: https://github.com/Chajian/agentic/discussions

package/dist/audit/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Audit Module
+ *
+ * Provides audit logging and querying capabilities for the Agent.
+ * Records tool executions, configuration changes, and errors.
+ */
+export * from './logger.js';
+export * from './query.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,9 @@
+/**
+ * Audit Module
+ *
+ * Provides audit logging and querying capabilities for the Agent.
+ * Records tool executions, configuration changes, and errors.
+ */
+export * from './logger.js';
+export * from './query.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/audit/logger.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Audit Logger
+ *
+ * Records tool executions, configuration changes, and errors
+ * for audit and troubleshooting purposes.
+ *
+ * _Requirements: 10.1, 10.2, 10.3_
+ */
+/**
+ * Operation types that can be logged
+ */
+export type OperationType = 'tool_execution' | 'config_change' | 'knowledge_add' | 'knowledge_delete' | 'session_create' | 'session_close' | 'error';
+/**
+ * Status of an operation
+ */
+export type OperationStatus = 'success' | 'failure' | 'pending';
+/**
+ * Operation log entry
+ */
+export interface OperationLog {
+    /** Unique log entry ID */
+    id: string;
+    /** Session ID associated with this operation */
+    sessionId?: string;
+    /** Type of operation */
+    operationType: OperationType;
+    /** Target of the operation (e.g., tool name, config key) */
+    target?: string;
+    /** Parameters passed to the operation */
+    params?: Record<string, unknown>;
+    /** Result of the operation */
+    result?: Record<string, unknown>;
+    /** Operation status */
+    status: OperationStatus;
+    /** Error message if operation failed */
+    errorMessage?: string;
+    /** Error stack trace if available */
+    errorStack?: string;
+    /** Timestamp when the operation occurred */
+    createdAt: Date;
+    /** Duration of the operation in milliseconds */
+    durationMs?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for creating a tool execution log
+ */
+export interface ToolExecutionLogInput {
+    /** Session ID */
+    sessionId?: string;
+    /** Tool name */
+    toolName: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Execution result */
+    result: {
+        success: boolean;
+        content: string;
+        data?: unknown;
+        error?: {
+            code: string;
+            message: string;
+            details?: unknown;
+        };
+    };
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Input for creating a config change log
+ */
+export interface ConfigChangeLogInput {
+    /** Session ID */
+    sessionId?: string;
+    /** Config key that was changed */
+    configKey: string;
+    /** Value before the change */
+    beforeValue?: unknown;
+    /** Value after the change */
+    afterValue?: unknown;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for creating an error log
+ */
+export interface ErrorLogInput {
+    /** Session ID */
+    sessionId?: string;
+    /** Error message */
+    message: string;
+    /** Error stack trace */
+    stack?: string;
+    /** Context where the error occurred */
+    context?: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Audit Logger
+ *
+ * In-memory audit logger that records all operations performed by the Agent.
+ * Provides methods for logging tool executions, config changes, and errors.
+ */
+export declare class AuditLogger {
+    private logs;
+    private logsBySession;
+    private logsByType;
+    /**
+     * Log a tool execution
+     *
+     * @param input - Tool execution details
+     * @returns The created log entry
+     */
+    logToolExecution(input: ToolExecutionLogInput): OperationLog;
+    /**
+     * Log a configuration change
+     *
+     * @param input - Config change details
+     * @returns The created log entry
+     */
+    logConfigChange(input: ConfigChangeLogInput): OperationLog;
+    /**
+     * Log an error
+     *
+     * @param input - Error details
+     * @returns The created log entry
+     */
+    logError(input: ErrorLogInput): OperationLog;
+    /**
+     * Log a knowledge addition
+     *
+     * @param sessionId - Session ID
+     * @param documentId - Document ID
+     * @param category - Document category
+     * @param title - Document title
+     * @returns The created log entry
+     */
+    logKnowledgeAdd(sessionId: string | undefined, documentId: string, category: string, title?: string): OperationLog;
+    /**
+     * Log a knowledge deletion
+     *
+     * @param sessionId - Session ID
+     * @param documentId - Document ID
+     * @param success - Whether deletion was successful
+     * @returns The created log entry
+     */
+    logKnowledgeDelete(sessionId: string | undefined, documentId: string, success: boolean): OperationLog;
+    /**
+     * Log a session creation
+     *
+     * @param sessionId - Session ID
+     * @param metadata - Session metadata
+     * @returns The created log entry
+     */
+    logSessionCreate(sessionId: string, metadata?: Record<string, unknown>): OperationLog;
+    /**
+     * Log a session close
+     *
+     * @param sessionId - Session ID
+     * @returns The created log entry
+     */
+    logSessionClose(sessionId: string): OperationLog;
+    /**
+     * Get a log entry by ID
+     *
+     * @param logId - Log entry ID
+     * @returns The log entry or undefined
+     */
+    getLog(logId: string): OperationLog | undefined;
+    /**
+     * Get all logs for a session
+     *
+     * @param sessionId - Session ID
+     * @returns Array of log entries
+     */
+    getLogsBySession(sessionId: string): OperationLog[];
+    /**
+     * Get all logs of a specific type
+     *
+     * @param operationType - Operation type
+     * @returns Array of log entries
+     */
+    getLogsByType(operationType: OperationType): OperationLog[];
+    /**
+     * Get all logs
+     *
+     * @returns Array of all log entries
+     */
+    getAllLogs(): OperationLog[];
+    /**
+     * Get total log count
+     *
+     * @returns Total number of logs
+     */
+    getLogCount(): number;
+    /**
+     * Clear all logs
+     */
+    clear(): void;
+    /**
+     * Add a log entry to storage
+     */
+    private addLog;
+}
+/**
+ * Create a new AuditLogger instance
+ */
+export declare function createAuditLogger(): AuditLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/audit/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/audit/logger.ts"],"names":[],"mappings":"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"}