agent-scene-toolkit 0.1.0 → 0.1.1

package/README.md

@@ -1,17 +1,14 @@
 # agent-scene-toolkit
 
-Lightweight Agent orchestration library built on LangChain, with unified SSE streaming.
+Lightweight Agent orchestration library built on LangChain.
 
 > **3 分钟上手**：定义 Profile → 定义 ToolKit → 创建 Agent → 对话。
 
-## ✨ Features
+## 核心概念
 
-- **ToolKit**（静态能力包）：按领域分组的工具集 + 使用策略 Prompt
-- **Profile**（角色身份）：只需定义 name + systemPrompt + model
-- **Scene**（运行时上下文）：注入动态业务状态 + 工具集过滤
-- **单/多 Agent 自动切换**：配置 `supervisor` 即启用多 Agent 协作
-- **标准化 SSE 事件流**：`text` / `tool_start` / `tool_end` / `handoff` / `agent` / `error` / `done`
-- **Express 一行集成**：`app.post('/chat', agent.handleRequest())`
+- **ToolKit**：静态能力包，按领域分组的工具集 + 使用策略 Prompt
+- **AgentProfile**：角色身份，只需定义 name + systemPrompt + model
+- **Scene**：运行时场景，注入动态上下文 + 决定当前可用的 ToolKit
 
 ## 📦 Install
 
@@ -19,7 +16,7 @@ Lightweight Agent orchestration library built on LangChain, with unified SSE str
 npm install agent-scene-toolkit @langchain/core @langchain/langgraph @langchain/openai langchain express
 ```
 
-## 🚀 Quick Start
+## 快速开始 — 最小示例
 
 ```typescript
 import { createAgent, defineProfile, defineToolKit, defineScene } from 'agent-scene-toolkit'
@@ -50,7 +47,7 @@ const agent = createAgent({
   toolkits: [canvasToolKit],
   agents: [director],
   scene: timelineScene,
-  llm: { baseURL: 'https://api.openai.com/v1', apiKey: 'sk-xxx' },
+  llm: { baseURL: 'https://api.bltcy.ai', apiKey: 'sk-xxx' },
 })
 
 // 5. 发起对话
@@ -59,58 +56,116 @@ for await (const event of agent.chat({ message: '你好', threadId: 'thread-001'
 }
 ```
 
-## 🤝 Multi-Agent
+## 完整配置
 
-配置 `supervisor` 后自动启用 Supervisor 策略：
+展示所有可选字段：记忆持久化、滑动窗口、LangFuse 观测、Scene 生命周期回调、动态运行时上下文。
 
 ```typescript
+import { createAgent, defineProfile, defineToolKit, defineScene } from 'agent-scene-toolkit'
+import { MemorySaver } from '@langchain/langgraph'
+import { CallbackHandler } from 'langfuse-langchain'
+
+// LangFuse 观测回调（也可通过环境变量 LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY / LANGFUSE_HOST 配置）
+const langfuseHandler = new CallbackHandler({
+  secretKey: 'sk-lf-xxx',
+  publicKey: 'pk-lf-xxx',
+  baseUrl: 'https://langfuse.your-domain.com',   // 自部署地址
+})
+
+const agent = createAgent({
+  toolkits: [canvasToolKit, aiToolKit],
+  agents: [director],
+  scene: defineScene({
+    name: 'timeline-editing',
+    toolkits: ['canvas', 'ai'],
+    prompt: (ctx) => `用户在时间线编辑器，视频时长: ${ctx.duration}秒`,
+    onToolEnd: (toolName, result) => {           // 工具调用完成回调
+      if (toolName === 'bindTrack') refreshTimeline()
+    },
+  }),
+  checkpointer: new MemorySaver(),                // 记忆持久化（生产环境用 PostgresSaver）
+  maxMessages: 50,                                // 滑动窗口大小（默认 50）
+  callbacks: [langfuseHandler],                   // 透传给 LLM + LangGraph，追踪完整执行链路
+  llm: { baseURL: 'https://api.bltcy.ai', apiKey: 'sk-xxx' },
+})
+
+// 传入 sceneContext 注入动态运行时数据 → scene.prompt(ctx)
+for await (const event of agent.chat({
+  message: '帮我调整第3秒的转场',
+  threadId: 'thread-001',
+  sceneContext: { duration: 30, currentTime: 3 },
+})) {
+  switch (event.type) {
+    case 'text':       process.stdout.write(event.content); break
+    case 'tool_start': console.log(`🔧 调用 ${event.toolName}`); break
+    case 'tool_end':   console.log(`✅ ${event.toolName}`, event.output); break
+    case 'error':      console.error(`❌ ${event.message}`); break
+    case 'done':       console.log('\n--- 结束 ---'); break
+  }
+}
+```
+
+## 多 Agent 模式
+
+配置 `supervisor` 后自动启用 Supervisor 策略，Supervisor 根据任务自动 handoff 给合适的 Worker。
+
+```typescript
+const director = defineProfile({
+  name: '导演',
+  systemPrompt: '你是一位视频导演，负责统筹任务分派...',
+  model: 'gpt-4o',
+})
+const screenwriter = defineProfile({
+  name: '编剧',
+  systemPrompt: '你是一位编剧，擅长剧本创作...',
+  model: 'gpt-4o-mini',
+})
+
 const agent = createAgent({
   toolkits: [canvasToolKit, aiToolKit],
   agents: [director, screenwriter],
-  supervisor: '导演', // ← 指定 Supervisor
-  llm: { baseURL: 'https://api.openai.com/v1', apiKey: 'sk-xxx' },
+  supervisor: '导演',                             // ← 指定 Supervisor，自动启用多 Agent
+  llm: { baseURL: 'https://api.bltcy.ai', apiKey: 'sk-xxx' },
 })
+
+for await (const event of agent.chat({ message: '写一个30秒的广告脚本', threadId: 'thread-002' })) {
+  if (event.type === 'agent')   console.log(`🎭 ${event.name} 正在回答`)
+  if (event.type === 'handoff') console.log(`🔀 ${event.from} → ${event.to}`)
+  if (event.type === 'text')    process.stdout.write(event.content)
+}
 ```
 
-## 🌐 Express Integration
+## Express 集成
 
 ```typescript
 import express from 'express'
 
 const app = express()
 app.use(express.json())
+
+// 一行挂载 SSE 路由
 app.post('/chat', agent.handleRequest())
+
+// 请求体：{ message: string, threadId: string, sceneContext?: Record<string, any> }
+// 响应：SSE 事件流（text/event-stream）
+//   data: {"type":"agent","name":"导演"}
+//   data: {"type":"text","content":"我来帮你调整"}
+//   data: {"type":"tool_start","toolName":"bindTrack","input":{"trackId":"t-01"}}
+//   data: {"type":"tool_end","toolName":"bindTrack","output":{"success":true}}
+//   data: {"type":"done"}
 ```
 
 ## 📡 SSE Event Protocol
 
 | Event | Trigger | Payload |
 |-------|---------|---------|
-| `text` | LLM outputs text token | `{ content: string }` |
-| `tool_start` | Tool call begins | `{ toolName: string, input: Record<string, any> }` |
-| `tool_end` | Tool call ends | `{ toolName: string, output: any }` |
-| `handoff` | Agent switch (multi-agent) | `{ from: string, to: string }` |
-| `agent` | Current answering agent | `{ name: string }` |
-| `error` | Execution error | `{ message: string }` |
-| `done` | Stream ends | `{}` |
-
-## ⚙️ Full Configuration
-
-```typescript
-const agent = createAgent({
-  toolkits: [canvasToolKit, aiToolKit],   // Global toolkit pool
-  agents: [director],                      // Agent profiles
-  supervisor: '导演',                      // Optional: enables multi-agent
-  scene: timelineScene,                    // Optional: runtime context + tool filtering
-  checkpointer: new MemorySaver(),         // Optional: memory persistence
-  maxMessages: 50,                         // Optional: sliding window size
-  callbacks: [langfuseHandler],            // Optional: LangChain callbacks (e.g. LangFuse)
-  llm: {                                  // Optional: OpenAI-compatible gateway
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: 'sk-xxx',
-  },
-})
-```
+| `text` | LLM 输出文本 token | `{ content: string }` |
+| `tool_start` | 工具调用开始 | `{ toolName: string, input: Record<string, any> }` |
+| `tool_end` | 工具调用结束 | `{ toolName: string, output: any }` |
+| `handoff` | Agent 切换（多 Agent） | `{ from: string, to: string }` |
+| `agent` | 当前回答的 Agent 身份 | `{ name: string }` |
+| `error` | 执行出错 | `{ message: string }` |
+| `done` | 流结束 | `{}` |
 
 ## 📖 API Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-scene-toolkit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight Agent orchestration library built on LangChain, with unified SSE streaming.",
   "type": "module",
   "main": "./dist/index.cjs",