@whwrm/react-agent 1.0.0

package/README.md

@@ -0,0 +1,413 @@
+# React-Agent
+
+一个轻量级的 ReAct (Reasoning + Acting) 框架，让 LLM 能够自主调用工具完成任务。
+
+## 特性
+
+- **极简调用** - 一行代码即可使用
+- **自主决策** - LLM 自动决定调用哪些工具、调用顺序
+- **链式依赖** - 自动处理 A→B→C 的依赖关系
+- **并行优化** - 独立操作自动并行执行
+- **多 LLM 支持** - 支持 OpenAI、DeepSeek、GLM、Qwen 等 15+ 平台
+- **热加载配置** - JSON 配置文件，无需重新构建
+
+## 安装
+
+```bash
+npm install react-agent
+```
+
+## 快速开始
+
+### 最简使用（3行代码）
+
+```typescript
+import { ask, loadConfig } from 'react-agent';
+
+const config = loadConfig('./config.json');
+const answer = await ask(config, '你好');
+```
+
+### 带工具的完整示例
+
+```typescript
+import { ask, createToolServer, registerTool, getToolDefinitions } from 'react-agent';
+
+// 1. 注册工具
+registerTool('get_weather', async (args) => {
+  const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
+  const data = await res.json();
+  return `${args.city}: ${data.current_condition[0].temp_C}°C`;
+}, {
+  name: 'get_weather',
+  description: '获取城市天气',
+  parameters: {
+    type: 'object',
+    properties: { city: { type: 'string', description: '城市名称' } },
+    required: ['city']
+  }
+});
+
+// 2. 启动工具服务器
+const server = await createToolServer({ port: 3000 });
+
+// 3. 调用
+const answer = await ask({
+  llm: {
+    model: 'glm-5',
+    apiKey: 'your-api-key',
+    baseUrl: 'https://coding.dashscope.aliyuncs.com/v1',
+  },
+  tools: { 
+    url: 'http://localhost:3000',
+    definitions: getToolDefinitions(),
+  },
+}, '北京今天天气怎么样？');
+
+console.log(answer);
+server.close();
+```
+
+## 配置说明
+
+### config.json
+
+```json
+{
+  "llm": {
+    "model": "glm-5",
+    "apiKey": "${API_KEY}",
+    "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
+  },
+  "systemPrompt": "你是一个智能助手",
+  "maxIterations": 10,
+  "contextWindowTokens": 128000,
+  "tools": {
+    "url": "http://localhost:3000",
+    "definitionsFile": "./tools.json"
+  }
+}
+```
+
+### tools.json
+
+```json
+[
+  {
+    "name": "get_weather",
+    "description": "获取城市天气信息",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": { "type": "string", "description": "城市名称" }
+      },
+      "required": ["city"]
+    }
+  },
+  {
+    "name": "search_web",
+    "description": "搜索网络信息",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query": { "type": "string", "description": "搜索关键词" }
+      },
+      "required": ["query"]
+    }
+  }
+]
+```
+
+## 支持的 LLM 平台
+
+| 平台 | model 示例 | baseUrl |
+|------|-----------|---------|
+| OpenAI | gpt-4, gpt-3.5-turbo | https://api.openai.com |
+| DeepSeek | deepseek-chat, deepseek-coder | https://api.deepseek.com |
+| 智谱 GLM | glm-4, glm-5 | https://open.bigmodel.cn |
+| 阿里 Qwen | qwen-plus, qwen-turbo | https://dashscope.aliyuncs.com |
+| Moonshot | moonshot-v1-8k | https://api.moonshot.ai |
+| MiniMax | abab6.5-chat | https://api.minimax.chat |
+| 自定义 | 任意 | 你的 API 地址 |
+
+### 自定义 API 端点
+
+```typescript
+const config = {
+  llm: {
+    model: 'your-model',
+    apiKey: 'your-key',
+    baseUrl: 'https://your-api-endpoint/v1',  // 自定义 URL
+  },
+};
+```
+
+## API 参考
+
+### ask(config, message, callbacks?)
+
+一行调用，返回最终答案。
+
+```typescript
+const answer = await ask(config, '你的问题');
+```
+
+### askFull(config, message, callbacks?)
+
+返回完整结果，包含统计信息。
+
+```typescript
+const result = await askFull(config, '你的问题');
+console.log(result.content);      // 回答内容
+console.log(result.toolCallsCount); // 工具调用次数
+console.log(result.iterations);   // 迭代次数
+```
+
+### registerTool(name, handler, definition)
+
+注册工具。
+
+```typescript
+registerTool('tool_name', async (args) => {
+  // 工具逻辑
+  return '结果';
+}, {
+  name: 'tool_name',
+  description: '工具描述',
+  parameters: {
+    type: 'object',
+    properties: {
+      param1: { type: 'string', description: '参数描述' }
+    },
+    required: ['param1']
+  }
+});
+```
+
+### createToolServer(options)
+
+启动工具服务器。
+
+```typescript
+const server = await createToolServer({ 
+  port: 3000,
+  tools: [{ name: 'xxx', handler: async () => '...' }]  // 可选
+});
+// 完成后关闭
+server.close();
+```
+
+### 回调函数
+
+```typescript
+const answer = await ask(config, '问题', {
+  onLLMResponse: (response) => {
+    console.log('LLM 响应:', response.finish_reason);
+    console.log('工具调用:', response.tool_calls);
+  },
+  onToolCall: (name, args) => {
+    console.log('调用工具:', name, args);
+  },
+  onToolResult: (name, result) => {
+    console.log('工具结果:', result);
+  },
+  onError: (error, context) => {
+    console.error('错误:', error);
+  },
+});
+```
+
+## 高级用法
+
+### Tools vs Skills
+
+**Tool（工具）**：单一操作，获取/执行数据
+- `get_weather(city)` - 查天气
+- `run_command(cmd)` - 执行命令
+
+**Skill（技能）**：固化的工作流程，包含知识背景
+- `travel_planning` - 旅行规划（可能包含搜索、分析、生成报告）
+- `report_writing` - 报告撰写（可能包含数据收集、分析、格式化）
+
+```typescript
+import { registerTool, registerSkill } from 'react-agent';
+
+// Tool - 单一操作
+registerTool('get_weather', async (args) => {
+  return `${args.city}: 25°C`;
+}, { name: 'get_weather', description: '获取天气', parameters: {...} });
+
+// Skill - 工作流程
+registerSkill('travel_planning', async (args) => {
+  // 可以包含多个步骤、知识背景
+  return `行程规划...`;
+}, { 
+  name: 'travel_planning', 
+  description: '旅行规划', 
+  prompt: '你是一个旅行规划专家...',  // 知识背景
+  parameters: {...} 
+});
+```
+
+### 链式依赖
+
+Agent 会自动处理依赖关系：
+
+```
+用户: 查询张三的订单详情
+
+执行过程:
+1. get_user_id("张三") → user_001
+2. get_orders("user_001") → [订单列表]
+3. get_order_detail("ORD-001") → 订单详情
+4. 生成最终回答
+```
+
+### 并行执行
+
+独立操作自动并行：
+
+```
+用户: 查询北京和上海的天气
+
+执行过程:
+1. 并行调用:
+   - get_weather("北京")
+   - get_weather("上海")
+2. 生成最终回答
+```
+
+### 自主纠错
+
+Agent 会根据工具返回结果自主判断：
+
+```
+用户: 火星今天天气怎么样？
+
+执行过程:
+1. get_weather("火星") → 错误：无法获取火星天气
+2. Agent 理解错误，解释原因，不再重复调用
+```
+
+## 项目结构
+
+```
+your-project/
+├── config.json      # Agent 配置
+├── tools.json       # 工具定义（可选）
+├── tools/           # 工具实现
+│   ├── weather.ts
+│   ├── search.ts
+│   └── index.ts
+└── main.ts          # 入口文件
+```
+
+## 示例：完整项目
+
+### tools/index.ts
+
+```typescript
+import { registerTool } from 'react-agent';
+
+registerTool('get_weather', async (args) => {
+  const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
+  const data = await res.json();
+  const current = data.current_condition[0];
+  return `${args.city}: ${current.temp_C}°C, ${current.weatherDesc[0].value}`;
+}, {
+  name: 'get_weather',
+  description: '获取城市天气',
+  parameters: {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city']
+  }
+});
+
+registerTool('search', async (args) => {
+  // 搜索实现
+  return '搜索结果...';
+}, {
+  name: 'search',
+  description: '搜索网络',
+  parameters: {
+    type: 'object',
+    properties: { query: { type: 'string' } },
+    required: ['query']
+  }
+});
+```
+
+### main.ts
+
+```typescript
+import { ask, createToolServer, getToolDefinitions } from 'react-agent';
+import './tools/index.js';  // 加载工具
+
+async function main() {
+  const server = await createToolServer({ port: 3000 });
+  
+  const answer = await ask({
+    llm: {
+      model: 'glm-5',
+      apiKey: process.env.API_KEY,
+      baseUrl: 'https://coding.dashscope.aliyuncs.com/v1',
+    },
+    tools: { 
+      url: 'http://localhost:3000',
+      definitions: getToolDefinitions(),
+    },
+  }, '帮我查一下北京天气');
+  
+  console.log(answer);
+  server.close();
+}
+
+main();
+```
+
+## 常见问题
+
+### Q: 如何使用环境变量？
+
+```json
+{
+  "llm": {
+    "apiKey": "${OPENAI_API_KEY}"
+  }
+}
+```
+
+### Q: 如何限制最大迭代次数？
+
+```typescript
+const config = {
+  maxIterations: 5,  // 默认 20
+};
+```
+
+### Q: 如何监控 token 使用？
+
+```typescript
+const agent = new ReactAgent(config);
+const answer = await agent.run('问题');
+
+const status = agent.getContextStatus();
+console.log('估算 tokens:', status.estimatedTokens);
+console.log('使用率:', status.usagePercent);
+
+const usage = agent.getLastUsage();
+console.log('实际 prompt tokens:', usage.promptTokens);
+```
+
+### Q: 如何处理超时？
+
+```typescript
+const config = {
+  maxIterations: 10,  // 限制迭代次数
+};
+```
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,34 @@
+import type { AgentConfig, AgentCallbacks, Message, ToolDefinition, SkillDefinition, AgentResult, ContextStatus } from './types.js';
+export declare class ReactAgent {
+    private config;
+    private messages;
+    private toolDefinitions;
+    private skillDefinitions;
+    private toolCallsCount;
+    private iterations;
+    private lastUsage;
+    constructor(config: AgentConfig);
+    private loadDefinitions;
+    run(userMessage: string, callbacks?: AgentCallbacks): Promise<string>;
+    runFull(userMessage: string, callbacks?: AgentCallbacks): Promise<AgentResult>;
+    private callLLM;
+    private executeTool;
+    private callToolAPI;
+    private callSkillAPI;
+    private buildMessages;
+    private getToolDefinitions;
+    clear(): void;
+    reload(): void;
+    getMessages(): Message[];
+    getToolDefinitionsList(): ToolDefinition[];
+    getSkillDefinitionsList(): SkillDefinition[];
+    getEstimatedPromptTokens(): number;
+    getContextUsageRatio(): number;
+    getContextStatus(): ContextStatus;
+    getLastUsage(): {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+    isNearContextLimit(threshold?: number): boolean;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,OAAO,EAEP,cAAc,EACd,eAAe,EAEf,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAC;AA6CpB,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAqF;IACnG,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,SAAS,CAA4D;gBAEjE,MAAM,EAAE,WAAW;IAS/B,OAAO,CAAC,eAAe;IA8BjB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAKrE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;YAsFtE,OAAO;YA4BP,WAAW;YASX,WAAW;YAgCX,YAAY;IAgC1B,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,kBAAkB;IAwB1B,KAAK,IAAI,IAAI;IAOb,MAAM,IAAI,IAAI;IAId,WAAW,IAAI,OAAO,EAAE;IAIxB,sBAAsB,IAAI,cAAc,EAAE;IAI1C,uBAAuB,IAAI,eAAe,EAAE;IAI5C,wBAAwB,IAAI,MAAM;IAUlC,oBAAoB,IAAI,MAAM;IAK9B,gBAAgB,IAAI,aAAa;IAuBjC,YAAY,IAAI;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE;IAIpE,kBAAkB,CAAC,SAAS,SAAM,GAAG,OAAO;CAG7C"}