p-api-agent 0.0.3 → 0.0.5

package/README.md

@@ -1,283 +1,289 @@
-# P-API-Agent
+# p-api-agent
 
-一个基于 LLM 的智能 Agent 框架，支持工具函数调用和多轮对话。
+一个轻量、高效、模型无关的 LLM Agent 框架。
+
+采用 **ReAct 单调用循环**架构：每轮推理只发起一次 LLM 调用，通过将完整工具 Schema 注入系统提示词，让模型在单次响应中完成「是否用工具 + 选哪个工具 + 填什么参数」三步决策，相比传统多步判断方案减少 60% 以上的 API 调用次数。
 
 ## 特性
 
-- 🤖 **智能对话**: 基于 LLM 的智能对话能力
-- 🔧 **工具调用**: 支持动态注册和调用工具函数
-- 📝 **类型安全**: 完整的 TypeScript 类型定义
-- 🛡️ **错误处理**: 完善的错误处理和日志系统
-- ⚙️ **可配置**: 灵活的配置选项
-- 📊 **日志系统**: 多级别日志输出
+- ⚡ **ReAct 单调用循环** — 每轮只调用一次 LLM，无冗余中间步骤
+- 🔌 **模型无关** — 只需注册一个 `async (messages) => string` 函数，兼容任意 LLM（OpenAI / Claude / 豆包 / 通义 / DeepSeek …）
+- 🔧 **动态工具注册** — 工具以独立文件方式组织，按目录自动加载
+- 🔗 **链式 API** — 注册方法均返回 `this`，支持链式调用
+- 🛡️ **完善容错** — LLM 重试、工具失败兜底、JSON 解析保护、循环上限防护
+- 📦 **零侵入** — 不绑定任何 LLM SDK，按需引入
+
+---
 
 ## 安装
 
 ```bash
 npm install p-api-agent
+# 或
+pnpm add p-api-agent
+# 或
+yarn add p-api-agent
 ```
 
-## 快速开始
+---
 
-### 基础用法
+## 快速开始
 
 ```typescript
 import { Agent, FunctionCall } from 'p-api-agent';
+import path from 'path';
 
-// 创建 Agent 实例
-const agent = new Agent({
-    maxLoop: 20,      // 最大循环次数
-    debug: false      // 调试模式
-});
+const agent = new Agent({ maxLoop: 10 });
 
-// 注册 LLM 聊天能力
+// 1. 注册 LLM 能力（替换成你自己的 LLM 调用）
 agent.register_llm_text_ability(async (messages) => {
-    // 调用您的 LLM API
-    const response = await yourLLMAPI(messages);
-    return response;
+  const res = await yourLLMClient.chat(messages);
+  return res.content;
 });
 
-// 注册工具函数（可选）
-const functionCall = new FunctionCall('/path/to/tools');
-agent.register_function_call(functionCall);
-
-// 开始对话
-const result = await agent.create_chat('你好，请帮我完成任务');
-console.log(result);
-```
-
-### 创建工具函数
-
-在工具目录下创建 `.js` 或 `.ts` 文件：
+// 2. 注册工具函数目录（可选）
+const fc = new FunctionCall(path.join(__dirname, 'tools'));
+agent.register_function_call(fc);
 
-```typescript
-// tools/get_weather.ts
-export function register() {
-    return {
-        name: 'get_weather',
-        description: '获取指定城市的天气信息',
-        input_schema: {
-            type: 'object',
-            properties: {
-                city: {
-                    type: 'string',
-                    description: '城市名称',
-                    examples: ['北京', '上海', '深圳']
-                }
-            },
-            required: ['city']
-        },
-        register_func: async (params: { city: string }) => {
-            // 实现您的工具逻辑
-            return {
-                city: params.city,
-                temperature: 25,
-                weather: '晴天'
-            };
-        }
-    };
-}
+// 3. 发起对话
+const result = await agent.create_chat('帮我查一下订单 12345 的收货地址');
+console.log(result.result);     // 最终答案
+console.log(result.use_tools);  // 调用过的工具记录
 ```
 
-### 自定义提示词
+支持链式注册：
 
 ```typescript
-const agent = new Agent({
-    customPresetPrompt: `
-你是一个专业的助手...
-（自定义提示词内容）
-    `
-});
+const result = await new Agent({ maxLoop: 10 })
+  .register_llm_text_ability(llmFunc)
+  .register_function_call(fc)
+  .create_chat('你好');
 ```
 
-## API 文档
-
-### Agent 类
+---
 
-#### 构造函数
+## 工作原理
 
-```typescript
-new Agent(options?: AgentOptions)
+```
+用户输入
+  │
+  ▼
+构建系统提示词（含所有工具完整 Schema）
+  │
+  ▼  ◄────────────────────────────────────────────────────────┐
+单次 LLM 调用                                                  │
+  │                                                            │
+  ├─ { command: "use_tool", tool_name, params }                │
+  │       └─ 执行工具 → 结果作为 observation 注入历史 ──────────┘
+  │
+  ├─ { command: "end", result }
+  │       └─ 返回最终答案 ✓
+  │
+  └─ { command: "no_ability", result }
+          └─ 返回无法处理说明 ✓
 ```
 
-**选项：**
-- `maxLoop?: number` - 最大循环次数（默认：20）
-- `debug?: boolean` - 是否启用调试模式（默认：false）
-- `customPresetPrompt?: string` - 自定义预置提示词
+每轮推理固定 **1 次** LLM 调用。工具结果以 `[工具调用结果]` 前缀注入对话历史，模型可在下一轮基于结果继续推理、链式调用多个工具，最终输出 `end` 指令结束。
 
-#### 方法
+---
 
-##### register_llm_text_ability(func)
+## 创建工具函数
 
-注册 LLM 文字能力
+在工具目录下为每个工具创建一个独立文件，导出 `register()` 函数：
 
 ```typescript
-agent.register_llm_text_ability(async (userInput) => {
-    // 返回 LLM 响应
-    return llmResponse;
+// tools/get_weather.ts
+import type { RegisterInfo } from 'p-api-agent';
+
+export const register = (): RegisterInfo => ({
+  name: 'get_weather',
+  description: '获取指定城市的实时天气信息',
+  input_schema: {
+    type: 'object',
+    properties: {
+      city: {
+        type: 'string',
+        description: '城市名称',
+        examples: ['北京', '上海', '深圳'],
+      },
+      date: {
+        type: 'string',
+        description: '日期，格式 YYYY-MM-DD，不传则默认今天',
+      },
+    },
+    required: ['city'],
+  },
+  register_func: async (params: { city: string; date?: string }) => {
+    // 实现你的业务逻辑
+    return { city: params.city, temperature: 25, weather: '晴' };
+  },
 });
 ```
 
-##### register_function_call(functionCall)
+`register_func` 接收 LLM 生成的参数对象，返回值会被序列化后注入对话上下文供模型读取。
 
-注册工具函数管理器
+---
 
-```typescript
-const functionCall = new FunctionCall('/path/to/tools');
-agent.register_function_call(functionCall);
-```
+## API 文档
 
-##### create_chat(userInput)
+### `new Agent(options?)`
 
-创建聊天会话
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `maxLoop` | `number` | `20` | 最大推理循环轮次，防止无限循环 |
+| `retryTimes` | `number` | `2` | LLM 调用失败时的重试次数 |
+| `customSystemPrompt` | `string` | — | 完全覆盖内置系统提示词 |
 
-```typescript
-const result = await agent.create_chat('用户输入');
-// 或使用消息数组
-const result = await agent.create_chat([
-    {
-        role: 'user',
-        content: [{ type: 'text', text: '用户输入' }]
-    }
-]);
-```
+---
 
-##### set_max_loop(maxLoop)
+### `agent.register_llm_text_ability(func)`
 
-设置最大循环次数
+注册 LLM 文字调用函数，返回 `this`。
 
 ```typescript
-agent.set_max_loop(30);
+agent.register_llm_text_ability(
+  async (messages: Message[]) => Promise<string>
+)
 ```
 
-##### set_preset_prompt(prompt)
+`messages` 格式遵循 OpenAI Chat Completions 标准，兼容绝大多数主流 LLM。
 
-设置自定义预置提示词
+---
 
-```typescript
-agent.set_preset_prompt('自定义提示词内容');
-```
+### `agent.register_function_call(fc)`
 
-### FunctionCall 类
-
-#### 构造函数
+注册工具函数集合，返回 `this`。`FunctionCall` 会自动扫描目录下所有文件并调用 `register()` 加载。
 
 ```typescript
-new FunctionCall(toolPath: string)
+const fc = new FunctionCall('/absolute/path/to/tools');
+agent.register_function_call(fc);
 ```
 
-**参数：**
-- `toolPath` - 工具函数所在目录的绝对路径
-
-#### 方法
+---
 
-##### get_tools_list()
+### `agent.create_chat(input)`
 
-获取所有工具函数列表
+发起一轮对话，返回 `Promise<CreateChatResult>`。
 
 ```typescript
-const tools = functionCall.get_tools_list();
-// [{ name: 'tool1', description: '...' }, ...]
-```
+// 字符串输入
+const result = await agent.create_chat('查询用户 123 的信息');
 
-##### has_tool(name)
+// 消息数组输入（携带多轮历史）
+const result = await agent.create_chat([
+  { role: 'user', content: [{ type: 'text', text: '你好' }] },
+  { role: 'assistant', content: [{ type: 'text', text: '你好！' }] },
+  { role: 'user', content: [{ type: 'text', text: '帮我查一下...' }] },
+]);
+```
 
-检查工具函数是否存在
+**返回值：**
 
 ```typescript
-const exists = functionCall.has_tool('get_weather');
+interface CreateChatResult {
+  result: string       // 最终返回给用户的文本答案
+  use_tools: {         // 本次对话中调用过的工具记录
+    tool_name: string
+    params: any
+    exec_result: any
+  }[]
+}
 ```
 
-##### exec_function(name, params)
+---
 
-执行工具函数
+### `agent.set_system_prompt(prompt)`
 
-```typescript
-const result = await functionCall.exec_function('get_weather', { city: '北京' });
-```
+运行时覆盖系统提示词，返回 `this`。**注意：** 覆盖后工具列表不再自动注入，需在自定义提示词中手动声明。
 
-### Logger 工具
+---
 
-```typescript
-import { Logger, LogLevel } from 'p-api-agent';
+### `agent.set_max_loop(n)`
 
-// 设置日志级别
-Logger.setLevel(LogLevel.DEBUG);
+动态调整最大循环轮次，返回 `this`。
 
-// 使用日志
-Logger.debug('调试信息');
-Logger.info('普通信息');
-Logger.warn('警告信息');
-Logger.error('错误信息');
-```
+---
+
+### `new FunctionCall(toolPath)`
+
+| 方法 | 说明 |
+|---|---|
+| `get_tools_list()` | 返回工具名称 + 描述列表 |
+| `get_tools_with_schema()` | 返回工具完整 Schema（含参数定义） |
+| `gen_tool_doc(name)` | 生成单个工具的可读说明文档字符串 |
+| `exec_function(name, params)` | 执行指定工具，返回工具执行结果 |
+
+---
 
-### 错误类型
+## 类型定义
 
 ```typescript
-import {
-    AgentError,
-    ToolNotFoundError,
-    ToolExecutionError,
-    ValidationError,
-    LLMError,
-    MaxLoopExceededError
+import type {
+  AgentOptions,
+  UserChatInput,
+  Message,
+  CreateChatResult,
+  ToolRecord,
+  RegisterInfo,
 } from 'p-api-agent';
-
-try {
-    await agent.create_chat('...');
-} catch (error) {
-    if (error instanceof ToolNotFoundError) {
-        console.error('工具函数不存在');
-    } else if (error instanceof MaxLoopExceededError) {
-        console.error('超出最大循环次数');
-    }
-}
 ```
 
-## 工作原理
+---
 
-1. **用户输入** → Agent 接收用户请求
-2. **LLM 分析** → LLM 判断是否需要调用工具
-3. **工具调用** → 如需要，先获取工具文档，再执行工具
-4. **结果处理** → 整合工具结果，返回给用户
-5. **循环控制** → 最多循环 maxLoop 次，防止无限循环
+## 完整示例（OpenAI）
 
-## LLM 响应格式
+```typescript
+import { Agent, FunctionCall } from 'p-api-agent';
+import OpenAI from 'openai';
+import path from 'path';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const agent = new Agent({ maxLoop: 15, retryTimes: 3 })
+  .register_llm_text_ability(async (messages) => {
+    const res = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages: messages as any,
+    });
+    return res.choices[0].message.content ?? '';
+  })
+  .register_function_call(
+    new FunctionCall(path.join(__dirname, 'tools'))
+  );
+
+const { result, use_tools } = await agent.create_chat(
+  '帮我查询订单 12345 的购买者信息和商品价格'
+);
+
+console.log('答案:', result);
+console.log('调用了工具:', use_tools.map(t => t.tool_name));
+```
 
-LLM 需要返回 JSON 格式的指令：
+---
 
-### 结束指令
-```json
-{
-    "command": "end",
-    "result": "最终返回给用户的结果"
-}
-```
+## 自定义系统提示词
 
-### 获取工具文档
-```json
-{
-    "command": "get_tool_doc",
-    "tool_name": "工具函数名称"
-}
-```
+如需完全控制 Agent 人设，使用 `customSystemPrompt` 选项：
 
-### 调用工具
-```json
-{
-    "command": "use_tool",
-    "tool_name": "工具函数名称",
-    "params": { "参数名": "参数值" }
-}
+```typescript
+const agent = new Agent({
+  customSystemPrompt: `
+你是一个专业的电商客服助手，负责处理订单查询和退换货问题。
+
+## 指令格式
+每次只能输出以下 JSON 之一，不能附带多余文字：
+- 调用工具: {"command":"use_tool","tool_name":"工具名","params":{...}}
+- 任务完成: {"command":"end","result":"最终答案"}
+- 无法处理: {"command":"no_ability","result":"原因说明"}
+
+## 可用工具
+- get_order_info: 根据订单号查询订单详情
+- get_user_info: 根据用户 ID 查询用户信息
+  `.trim(),
+});
 ```
 
-## 最佳实践
-
-1. **错误处理**: 始终使用 try-catch 包裹 Agent 调用
-2. **日志记录**: 生产环境建议设置为 INFO 或 WARN 级别
-3. **循环次数**: 根据实际需求调整 maxLoop，避免过多循环
-4. **工具设计**: 工具函数应该功能单一、职责明确
-5. **参数验证**: 在工具函数中进行充分的参数验证
+---
 
 ## 开发
 
@@ -288,22 +294,12 @@ npm install
 # 构建
 npm run build
 
-# 测试
-npm test
+# 运行示例
+npx tsx examples/test.ts
 ```
 
-## 许可证
-
-ISC
-
-## 贡献
+---
 
-欢迎提交 Issue 和 Pull Request！
+## License
 
-## 更新日志
-
-### v0.0.1
-- 初始版本发布
-- 支持基本的 Agent 功能
-- 工具函数调用
-- 完善的类型定义和错误处理
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "p-api-agent",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "files": [
@@ -18,7 +18,23 @@
   },
   "author": "",
   "license": "ISC",
-  "description": "",
+  "description": "一个轻量、高效、模型无关的 LLM Agent 框架，采用 ReAct 单调用循环架构",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/p-shoko/p-api-agent.git"
+  },
+  "homepage": "https://github.com/p-shoko/p-api-agent#readme",
+  "bugs": {
+    "url": "https://github.com/p-shoko/p-api-agent/issues"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "react",
+    "function-call",
+    "openai",
+    "ai"
+  ],
   "devDependencies": {
     "@types/lodash": "4.17.16",
     "@types/node": "^25.3.5",