@lovelymai/agent 1.0.6 → 1.0.8

package/README.md

@@ -0,0 +1,81 @@
+# @lovelymai/agent
+
+一个纯净极简易于使用的 Agent 框架。
+
+## 第一步：安装依赖
+
+```bash
+npm install @lovelymai/agent openai
+```
+
+`openai` 是 peer dependency，需要在项目中自行安装。
+
+## 第二步：创建 Agent 实例
+
+```typescript
+import OpenAI from 'openai'
+import { createAgentManager } from '@lovelymai/agent'
+
+const client = new OpenAI()
+const agent = createAgentManager(client)
+```
+
+## 第三步：配置模型与消息
+
+```typescript
+agent.config = { model: 'deepseek-v4-flash', thinking: { type: 'disabled' } }
+agent.messages.push({ role: 'user', content: '你好' })
+```
+
+## 第四步：注册工具（可选）
+
+定义工具并在 Agent 中注册，Agent 会在对话中自动调用：
+
+```typescript
+agent.updateTools([
+  {
+    name: 'get_weather',
+    description: '查询指定城市的天气',
+    properties: {
+      city: { type: 'string', description: '城市名称', required: true },
+    },
+    function: async ({ city }) => {
+      return `${city}今天晴，25°C`
+    },
+  },
+])
+```
+
+## 第五步：监听事件
+
+通过 `onEvent` 回调获取 Agent 运行过程中的各种事件：
+
+```typescript
+agent.onEvent = (event) => {
+  if (event.type === 'message_update' && 'content' in event.text) {
+    process.stdout.write(event.text.content ?? '')
+  }
+}
+```
+
+支持的事件类型：
+
+| 事件             | 说明                                                |
+| ---------------- | --------------------------------------------------- |
+| `agent_start`    | Agent 开始运行                                      |
+| `turn_start`     | 每轮对话开始                                       |
+| `message_update` | 流式输出更新                                       |
+| `tool_start`     | 工具开始执行                                        |
+| `tool_end`       | 工具执行完成                                        |
+| `agent_end`      | Agent 运行结束                                      |
+| `agent_error`    | Agent 运行出错                                      |
+
+## 第六步：启动与停止
+
+```typescript
+// 启动
+await agent.start()
+
+// 手动停止
+agent.stop()
+```

package/dist/agent.js

@@ -533,12 +533,18 @@ var Oe = class {
 	let i = await e.chat.completions.create({
 		...t,
 		stream: !0,
-		tool_choice: "auto"
+		tool_choice: "auto",
+		stream_options: { include_usage: !0 }
 	}), a = {
 		role: "assistant",
 		content: "",
 		reasoning_content: "",
-		tool_calls: []
+		tool_calls: [],
+		usage: {
+			prompt_tokens: 0,
+			completion_tokens: 0,
+			total_tokens: 0
+		}
 	};
 	for await (let e of i) {
 		if (!r.value) throw Error("主动停止");
@@ -555,6 +561,7 @@ var Oe = class {
 			let t = a.tool_calls[e.index];
 			e.id && (t.id = e.id), e.function?.name && (t.function.name = e.function.name), e.function?.arguments && (t.function.arguments += e.function.arguments);
 		}
+		e.usage && (a.usage = e.usage);
 	}
 	return a.tool_calls?.length === 0 && delete a.tool_calls, a.content || delete a.content, a.reasoning_content || delete a.reasoning_content, a;
 }, Ae = (e) => {
@@ -580,13 +587,14 @@ var Oe = class {
 		toolExecutors: n
 	};
 }, je = (e) => {
-	let t = /* @__PURE__ */ $({ model: "" }), n = /* @__PURE__ */ $([]), r = /* @__PURE__ */ $([]), i = /* @__PURE__ */ $({}), a = /* @__PURE__ */ $(10), o = /* @__PURE__ */ Ee({}), s = /* @__PURE__ */ $(), c = /* @__PURE__ */ $(!1);
+	let t = /* @__PURE__ */ $({ model: "" }), n = /* @__PURE__ */ $([]), r = /* @__PURE__ */ $([]), i = /* @__PURE__ */ $({}), a = /* @__PURE__ */ $(10), o = /* @__PURE__ */ Ee({}), s = /* @__PURE__ */ $(), c = /* @__PURE__ */ $(!1), l = /* @__PURE__ */ $(0);
 	return /* @__PURE__ */ G({
 		config: t,
 		messages: n,
 		maxIteration: a,
 		environment: o,
 		onEvent: s,
+		usage: l,
 		updateTools: (e) => {
 			let t = Ae(e);
 			r.value = t.toolDefinitions, i.value = t.toolExecutors;
@@ -594,18 +602,18 @@ var Oe = class {
 		start: async () => {
 			c.value = !0, s.value?.({ type: "agent_start" });
 			try {
-				for (let l = 0; l < a.value; l++) {
+				for (let u = 0; u < a.value; u++) {
 					if (!c.value) return;
 					s.value?.({
 						type: "turn_start",
-						turnCount: l
+						turnCount: u
 					});
 					let a = n.value.filter((e) => [
 						"system",
 						"user",
 						"assistant",
 						"tool"
-					].includes(e.role)), u = await ke(e, {
+					].includes(e.role)), d = await ke(e, {
 						...t.value,
 						messages: a,
 						tools: r.value
@@ -614,15 +622,15 @@ var Oe = class {
 							type: "message_update",
 							text: e
 						});
-					}, c);
-					if (n.value.push(u), !u.tool_calls) {
+					}, c), { usage: { total_tokens: f }, ...ee } = d;
+					if (l.value = f, n.value.push(ee), !d.tool_calls) {
 						s.value?.({
 							type: "agent_end",
-							turnCount: l
+							turnCount: u
 						});
 						return;
 					}
-					for (let e of u.tool_calls) {
+					for (let e of d.tool_calls) {
 						if (!c.value) throw Error("主动停止");
 						let t = i.value[e.function.name];
 						if (!t) continue;
@@ -636,9 +644,9 @@ var Oe = class {
 						} catch (e) {
 							a = e instanceof Error ? e.message : e;
 						}
-						n.value.push({
+						a = typeof a == "string" ? a : JSON.stringify(a), n.value.push({
 							role: "tool",
-							content: JSON.stringify(a),
+							content: a,
 							tool_call_id: e.id
 						}), s.value?.({
 							type: "tool_end",

package/dist/index.d.ts

@@ -1,2 +1 @@
-export type { Tool } from './services/tool.ts';
-export { createAgentManager, type AgentManager, type Event } from './services/loop.ts';
+export { createAgentManager, type AgentManager, type Tool, type Event } from './modules/index.ts';

package/dist/{services/loop.d.ts → modules/index.d.ts}

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
 import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
-import { type Tool } from './tool.ts';
+import { type Tool } from './modules/tool.ts';
 export type AgentManager = {
     /** 模型配置 */
     config: {
@@ -15,6 +15,8 @@ export type AgentManager = {
     maxIteration: number;
     /** 环境参数对象 */
     environment: Record<string, any>;
+    /** token 总量 */
+    readonly usage: number;
     /** 事件回调 */
     onEvent: ((event: Event) => void) | undefined;
     /** 更新工具 */
@@ -24,6 +26,7 @@ export type AgentManager = {
     /** 结束 */
     readonly stop: () => void;
 };
+export type { Tool };
 export type Event = {
     type: 'agent_start';
 } | {

package/dist/{services → modules/modules}/stream.d.ts

@@ -1,7 +1,7 @@
 import type { Ref } from '@vue/reactivity';
 import type OpenAI from 'openai';
 import type { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionMessageFunctionToolCall } from 'openai/resources/chat/completions';
-export type Config = {
+type Config = {
     /** 模型 */
     model: string;
     /** 消息 */
@@ -10,14 +10,21 @@ export type Config = {
     tools: ChatCompletionTool[];
     [key: string]: any;
 };
+type Usage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+};
 type Accumulated = {
     role: 'assistant';
     content?: string;
     reasoning_content?: string;
     tool_calls?: ChatCompletionMessageFunctionToolCall[];
+    usage: Usage;
 };
 export declare const streamOut: (client: OpenAI, config: Config, onChunk: (text: {
-    content?: string;
-    reasoning_content?: string;
+    content: string;
+} | {
+    reasoning_content: string;
 }) => void, isRunning: Ref<boolean>) => Promise<Accumulated>;
 export {};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@lovelymai/agent",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "一个纯净极简易于使用的 Agent 框架",
-  "keywords": ["agent"],
+  "keywords": [
+    "agent"
+  ],
   "license": "MIT",
+  "files": [
+    "dist"
+  ],
   "type": "module",
-  "files": ["dist"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,13 +17,16 @@
     }
   },
   "scripts": {
-    "build": "vite build && tsc"
+    "start": "tsx ./test/src/index.ts",
+    "build": "vite build && tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "@vue/reactivity": "^3.5.41"
   },
   "devDependencies": {
+    "@types/node": "^26.4.0",
     "openai": "^7.7.0",
+    "tsx": "^4.23.13",
     "typescript": "^7.0.2",
     "vite": "^8.0.12"
   },