@whwrm/react-agent 1.1.0 → 1.1.1

package/README.md

@@ -195,6 +195,217 @@ MIT
 
 ---
 
+## 项目结构说明
+
+### 📁 文件位置总览
+
+配置文件放在**你自己的项目目录**下，不是在 npm 包里：
+
+```
+your-project/
+├── config.json        # Agent 配置（必需）
+├── tools.json         # 工具定义（可选）
+├── skills.json        # 技能定义（可选）
+├── tools-server.ts    # 工具服务器（生产环境用，可选）
+├── skills-server.ts   # 技能服务器（生产环境用，可选）
+└── main.ts            # 你的入口文件
+```
+
+> ⚠️ **注意**：`example/` 目录下的文件是**示例代码**，不是 npm 包的一部分。你需要在自己的项目中创建这些配置文件。
+
+---
+
+### 📄 config.json（必需）
+
+Agent 的主配置文件，定义 LLM、工具服务器地址等：
+
+```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"
+  },
+  "skills": {
+    "url": "http://localhost:3000",
+    "definitionsFile": "./skills.json"
+  }
+}
+```
+
+**使用方式**：
+```typescript
+import { loadConfig } from '@whwrm/react-agent';
+const config = loadConfig('./config.json');
+```
+
+---
+
+### 📄 tools.json（可选）
+
+工具定义文件，定义 Agent 可以调用的工具。**只有在使用远程工具服务器时才需要**。
+
+```json
+[
+  {
+    "name": "get_weather",
+    "description": "获取城市天气",
+    "parameters": {
+      "type": "object",
+      "properties": { "city": { "type": "string" } },
+      "required": ["city"]
+    },
+    "api": {
+      "url": "https://wttr.in/{city}?format=j1",
+      "method": "GET"
+    }
+  }
+]
+```
+
+**两种使用方式**：
+
+| 方式 | 说明 | 适用场景 |
+|------|------|----------|
+| `registerTool()` | 代码中直接注册 | 开发环境、简单场景 |
+| `tools.json` + 工具服务器 | 配置文件定义 | 生产环境、热重载 |
+
+---
+
+### 📄 skills.json（可选）
+
+技能定义文件，定义 Agent 可以使用的技能。**只有在使用远程技能服务器时才需要**。
+
+```json
+[
+  {
+    "name": "summarize",
+    "description": "总结文本",
+    "parameters": {
+      "type": "object",
+      "properties": { "content": { "type": "string" } },
+      "required": ["content"]
+    },
+    "prompt": "请总结以下内容：{content}"
+  }
+]
+```
+
+---
+
+### 📄 basic.ts（示例文件）
+
+**这是一个示例文件**，展示 Agent 的基础用法。你不需要复制它，只需要参考它的代码：
+
+```typescript
+import { ReactAgent, loadConfig } from '@whwrm/react-agent';
+
+const config = loadConfig('./config.json');
+const agent = new ReactAgent(config);
+const answer = await agent.run('问题');
+```
+
+---
+
+### 📄 tools-server.ts 和 skills-server.ts（生产环境）
+
+**这是生产环境的独立服务器代码**，用于：
+- 长期运行，不随请求启动
+- 支持热重载配置（修改 JSON 文件后自动生效）
+- 多个 Agent 实例共享同一服务器
+
+**开发环境 vs 生产环境**：
+
+| 场景 | 方式 | 说明 |
+|------|------|------|
+| 开发/测试 | `createToolServer()` | 自动创建临时服务器，用完关闭 |
+| 生产环境 | 独立部署 tools-server.ts | 长期运行，支持热重载 |
+
+**开发环境示例**：
+```typescript
+import { createToolServer, registerTool, getToolDefinitions } from '@whwrm/react-agent';
+
+registerTool('get_weather', async (args) => {
+  return `${args.city}: 25°C`;
+}, { name: 'get_weather', description: '获取天气', parameters: {...} });
+
+const server = await createToolServer({ port: 3000 });
+// 完成后关闭
+server.close();
+```
+
+**生产环境**：
+```bash
+# 1. 启动工具服务器（长期运行）
+ts-node tools-server.ts
+
+# 2. Agent API 调用远程工具服务器
+```
+
+**tools-server.ts 的要求**：
+- 需要安装 `express`
+- 需要创建 `tools.json` 配置文件
+- 支持环境变量（如 `${SERPER_KEY}`）
+
+**skills-server.ts 的要求**：
+- 需要安装 `express`
+- 需要创建 `skills.json` 配置文件
+- 需要配置 `LLM_API_KEY` 环境变量（用于执行技能）
+
+---
+
+### 🔄 完整工作流程
+
+**方式一：开发环境（简单）**
+```typescript
+import { ask, createToolServer, registerTool, getToolDefinitions } from '@whwrm/react-agent';
+
+// 1. 注册工具（不需要 tools.json）
+registerTool('get_weather', async (args) => { ... });
+
+// 2. 启动服务器
+const server = await createToolServer({ port: 3000 });
+
+// 3. 调用
+const answer = await ask({
+  llm: { model: 'glm-5', apiKey: 'xxx' },
+  tools: { url: 'http://localhost:3000', definitions: getToolDefinitions() },
+}, '问题');
+
+server.close();
+```
+
+**方式二：生产环境（推荐）**
+```bash
+# 终端 1：启动工具服务器
+cd your-project
+ts-node tools-server.ts
+
+# 终端 2：启动技能服务器（可选）
+ts-node skills-server.ts
+```
+
+```typescript
+// Agent API - 无状态
+import { ask, loadConfig } from '@whwrm/react-agent';
+
+const config = loadConfig('./config.json');
+const answer = await ask(config, '问题');
+```
+
+## License
+
+MIT
+
+---
+
 # 中文文档
 
 一个轻量级的 ReAct (Reasoning + Acting) 框架，让 LLM 能够自主调用工具完成任务。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whwrm/react-agent",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "轻量级 ReAct 框架，支持 JSON 配置驱动的工具和技能注册",
   "type": "module",
   "main": "dist/index.js",