opc-agent 4.1.0 → 4.1.1

package/tutorial/customer-service-agent/SOUL.md

@@ -1,26 +1,26 @@
-# SOUL.md — Customer Service Agent Personality
-
-## 我是谁 / Who I Am
-
-我是一个专业的智能客服助手，服务于电商平台的客户。
-
-## 性格 / Personality
-
-- **耐心 Patient** — 无论客户问多少次，我都不会不耐烦
-- **专业 Professional** — 回答准确、有条理
-- **温暖 Warm** — 让客户感受到被重视
-- **诚实 Honest** — 不确定时坦诚告知，绝不编造信息
-
-## 沟通风格 / Communication Style
-
-- 使用中文，术语保留英文
-- 简洁明了，避免冗长
-- 主动提供相关信息
-- 遇到无法解决的问题，立即创建工单转人工
-
-## 边界 / Boundaries
-
-- 不讨论政治、宗教等敏感话题
-- 不提供法律、医疗建议
-- 不泄露内部系统信息
-- 不代表公司做出超出权限的承诺
+# SOUL.md — Customer Service Agent Personality
+
+## 我是谁 / Who I Am
+
+我是一个专业的智能客服助手，服务于电商平台的客户。
+
+## 性格 / Personality
+
+- **耐心 Patient** — 无论客户问多少次，我都不会不耐烦
+- **专业 Professional** — 回答准确、有条理
+- **温暖 Warm** — 让客户感受到被重视
+- **诚实 Honest** — 不确定时坦诚告知，绝不编造信息
+
+## 沟通风格 / Communication Style
+
+- 使用中文，术语保留英文
+- 简洁明了，避免冗长
+- 主动提供相关信息
+- 遇到无法解决的问题，立即创建工单转人工
+
+## 边界 / Boundaries
+
+- 不讨论政治、宗教等敏感话题
+- 不提供法律、医疗建议
+- 不泄露内部系统信息
+- 不代表公司做出超出权限的承诺

package/tutorial/customer-service-agent/agent.yaml

@@ -1,63 +1,63 @@
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: customer-service
-  version: 1.0.0
-  description: 智能客服 Agent — Smart Customer Service Agent
-  author: deepleaper
-  license: MIT
-
-spec:
-  # LLM 配置 / LLM Configuration
-  model: qwen2.5
-  provider:
-    default: ollama
-
-  # 系统提示词 / System Prompt
-  systemPrompt: |
-    你是一个专业的客服助手，代表我们的电商平台为客户提供帮助。
-    You are a professional customer service assistant.
-
-    规则 / Rules:
-    - 用中文回答，必要时使用英文术语
-    - 始终保持礼貌和耐心
-    - 如果不确定，创建工单转人工
-    - 不要编造信息
-
-  # 频道配置 / Channel Configuration
-  channels:
-    - type: web
-      port: 3000
-    # Uncomment to enable Telegram:
-    # - type: telegram
-    #   token: ${TELEGRAM_BOT_TOKEN}
-    #   mode: polling
-    # Uncomment to enable Discord:
-    # - type: discord
-    #   token: ${DISCORD_BOT_TOKEN}
-    #   guildId: "your-server-id"
-
-  # 记忆系统 / Memory System
-  memory:
-    shortTerm: true
-
-  # 技能列表 / Skills
-  skills:
-    - name: faq
-    - name: ticket
-
-  # 调度任务 / Scheduled Jobs
-  scheduler:
-    jobs:
-      - name: daily-report
-        schedule: "0 9 * * *"
-        task: "Generate daily customer service report"
-      - name: cleanup-old-tickets
-        schedule: "0 2 * * 0"
-        task: "Archive tickets older than 30 days"
-
-  # 安全配置 / Security
-  security:
-    approval: dangerous
-    sandbox:
-      maxFileSize: 10485760
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: customer-service
+  version: 1.0.0
+  description: 智能客服 Agent — Smart Customer Service Agent
+  author: deepleaper
+  license: MIT
+
+spec:
+  # LLM 配置 / LLM Configuration
+  model: qwen2.5
+  provider:
+    default: ollama
+
+  # 系统提示词 / System Prompt
+  systemPrompt: |
+    你是一个专业的客服助手，代表我们的电商平台为客户提供帮助。
+    You are a professional customer service assistant.
+
+    规则 / Rules:
+    - 用中文回答，必要时使用英文术语
+    - 始终保持礼貌和耐心
+    - 如果不确定，创建工单转人工
+    - 不要编造信息
+
+  # 频道配置 / Channel Configuration
+  channels:
+    - type: web
+      port: 3000
+    # Uncomment to enable Telegram:
+    # - type: telegram
+    #   token: ${TELEGRAM_BOT_TOKEN}
+    #   mode: polling
+    # Uncomment to enable Discord:
+    # - type: discord
+    #   token: ${DISCORD_BOT_TOKEN}
+    #   guildId: "your-server-id"
+
+  # 记忆系统 / Memory System
+  memory:
+    shortTerm: true
+
+  # 技能列表 / Skills
+  skills:
+    - name: faq
+    - name: ticket
+
+  # 调度任务 / Scheduled Jobs
+  scheduler:
+    jobs:
+      - name: daily-report
+        schedule: "0 9 * * *"
+        task: "Generate daily customer service report"
+      - name: cleanup-old-tickets
+        schedule: "0 2 * * 0"
+        task: "Archive tickets older than 30 days"
+
+  # 安全配置 / Security
+  security:
+    approval: dangerous
+    sandbox:
+      maxFileSize: 10485760

package/tutorial/customer-service-agent/package.json

@@ -1,19 +1,19 @@
-{
-  "name": "customer-service-agent",
-  "version": "1.0.0",
-  "description": "智能客服 Agent tutorial — OPC Agent comprehensive example",
-  "main": "dist/index.js",
-  "scripts": {
-    "build": "tsc",
-    "start": "opc start",
-    "dev": "opc chat",
-    "test": "echo \"tutorial example — no tests configured\" && exit 0"
-  },
-  "dependencies": {
-    "opc-agent": "latest",
-    "deepbrain": "latest"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "customer-service-agent",
+  "version": "1.0.0",
+  "description": "智能客服 Agent tutorial — OPC Agent comprehensive example",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "opc start",
+    "dev": "opc chat",
+    "test": "echo \"tutorial example — no tests configured\" && exit 0"
+  },
+  "dependencies": {
+    "opc-agent": "latest",
+    "deepbrain": "latest"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/tutorial/customer-service-agent/src/index.ts

@@ -1,69 +1,69 @@
-/**
- * Customer Service Agent — Entry Point
- * 客服 Agent 入口文件
- *
- * Demonstrates: Agent init, DeepBrain memory, skills, tools, workflows, plugins
- */
-import { Agent, getBuiltinTools, WorkflowBuilder } from 'opc-agent';
-import { loggerPlugin, rateLimiterPlugin } from 'opc-agent';
-import { Brain } from 'deepbrain';
-
-// === 1. DeepBrain 记忆初始化 / Initialize Memory ===
-const brain = new Brain({
-  database: './data/customer-brain.db',
-  embedding_provider: 'ollama',
-});
-await brain.connect();
-
-// === 2. 内置工具 / Built-in Tools ===
-const tools = getBuiltinTools('./workspace');
-
-// === 3. 创建 Agent / Create Agent ===
-const agent = new Agent('./agent.yaml', {
-  tools,
-  plugins: [
-    loggerPlugin({ level: 'info', output: './logs/agent.log' }),
-    rateLimiterPlugin({ maxRequests: 60, windowMs: 60000 }),
-  ],
-});
-
-// === 4. 记忆钩子 / Memory Hooks ===
-agent.on('message', async (msg, response) => {
-  // 存储对话用于语义搜索 / Store conversations for semantic search
-  await brain.put(
-    `conv-${msg.id}`,
-    `Q: ${msg.content}\nA: ${response.content}`
-  );
-});
-
-agent.on('beforeReply', async (ctx) => {
-  // 搜索相关历史对话 / Search relevant past conversations
-  const relevant = await brain.query(ctx.message, { limit: 3 });
-  if (relevant.length > 0) {
-    ctx.additionalContext = relevant.map((r: { content: string }) => r.content).join('\n');
-  }
-});
-
-// === 5. 工作流 / Workflow: Customer Onboarding ===
-const onboarding = new WorkflowBuilder()
-  .start('greet')
-  .addAction('greet', async (_ctx) => {
-    return '欢迎！请问您是新客户还是老客户？';
-  }, { next: 'check-type' })
-  .addCondition('check-type',
-    (ctx) => ctx.variables.get('isNewCustomer'),
-    'new-flow', 'existing-flow')
-  .addAction('new-flow', async (_ctx) => {
-    return '让我帮您注册账号。请提供您的邮箱地址。';
-  }, { next: 'done' })
-  .addAction('existing-flow', async (_ctx) => {
-    return '欢迎回来！有什么可以帮您？';
-  }, { next: 'done' })
-  .addAction('done', async () => 'Onboarding complete')
-  .build();
-
-agent.registerWorkflow('onboarding', onboarding);
-
-// === 6. 启动 / Start ===
-await agent.start();
-console.log('🚀 Customer Service Agent is running!');
+/**
+ * Customer Service Agent — Entry Point
+ * 客服 Agent 入口文件
+ *
+ * Demonstrates: Agent init, DeepBrain memory, skills, tools, workflows, plugins
+ */
+import { Agent, getBuiltinTools, WorkflowBuilder } from 'opc-agent';
+import { loggerPlugin, rateLimiterPlugin } from 'opc-agent';
+import { Brain } from 'deepbrain';
+
+// === 1. DeepBrain 记忆初始化 / Initialize Memory ===
+const brain = new Brain({
+  database: './data/customer-brain.db',
+  embedding_provider: 'ollama',
+});
+await brain.connect();
+
+// === 2. 内置工具 / Built-in Tools ===
+const tools = getBuiltinTools('./workspace');
+
+// === 3. 创建 Agent / Create Agent ===
+const agent = new Agent('./agent.yaml', {
+  tools,
+  plugins: [
+    loggerPlugin({ level: 'info', output: './logs/agent.log' }),
+    rateLimiterPlugin({ maxRequests: 60, windowMs: 60000 }),
+  ],
+});
+
+// === 4. 记忆钩子 / Memory Hooks ===
+agent.on('message', async (msg, response) => {
+  // 存储对话用于语义搜索 / Store conversations for semantic search
+  await brain.put(
+    `conv-${msg.id}`,
+    `Q: ${msg.content}\nA: ${response.content}`
+  );
+});
+
+agent.on('beforeReply', async (ctx) => {
+  // 搜索相关历史对话 / Search relevant past conversations
+  const relevant = await brain.query(ctx.message, { limit: 3 });
+  if (relevant.length > 0) {
+    ctx.additionalContext = relevant.map((r: { content: string }) => r.content).join('\n');
+  }
+});
+
+// === 5. 工作流 / Workflow: Customer Onboarding ===
+const onboarding = new WorkflowBuilder()
+  .start('greet')
+  .addAction('greet', async (_ctx) => {
+    return '欢迎！请问您是新客户还是老客户？';
+  }, { next: 'check-type' })
+  .addCondition('check-type',
+    (ctx) => ctx.variables.get('isNewCustomer'),
+    'new-flow', 'existing-flow')
+  .addAction('new-flow', async (_ctx) => {
+    return '让我帮您注册账号。请提供您的邮箱地址。';
+  }, { next: 'done' })
+  .addAction('existing-flow', async (_ctx) => {
+    return '欢迎回来！有什么可以帮您？';
+  }, { next: 'done' })
+  .addAction('done', async () => 'Onboarding complete')
+  .build();
+
+agent.registerWorkflow('onboarding', onboarding);
+
+// === 6. 启动 / Start ===
+await agent.start();
+console.log('🚀 Customer Service Agent is running!');

package/tutorial/customer-service-agent/src/skills/faq.ts

@@ -1,27 +1,27 @@
-/**
- * FAQ Skill — FAQ 查询技能
- * Looks up frequently asked questions by keyword matching.
- */
-import { BaseSkill } from 'opc-agent';
-
-export class FAQSkill extends BaseSkill {
-  name = 'faq';
-  description = 'Look up frequently asked questions';
-  triggers = [/常见问题|FAQ|怎么退款|退货|配送|支付/i];
-
-  async execute(input: string): Promise<string> {
-    // 常见问题知识库 / FAQ Knowledge Base
-    const faqs: Record<string, string> = {
-      '退款': '退款将在3-5个工作日内到账。如超时未到账，请联系银行确认。',
-      '退货': '请在收到商品7天内申请退货。商品需保持原包装，未使用。',
-      '配送': '标准配送3-5天，加急配送1-2天。偏远地区可能延迟1-2天。',
-      '支付': '支持支付宝、微信支付、银行卡（Visa/Mastercard/银联）。',
-    };
-
-    for (const [key, answer] of Object.entries(faqs)) {
-      if (input.includes(key)) return answer;
-    }
-
-    return '请问您想了解什么？我们有以下常见问题：退款、退货、配送、支付';
-  }
-}
+/**
+ * FAQ Skill — FAQ 查询技能
+ * Looks up frequently asked questions by keyword matching.
+ */
+import { BaseSkill } from 'opc-agent';
+
+export class FAQSkill extends BaseSkill {
+  name = 'faq';
+  description = 'Look up frequently asked questions';
+  triggers = [/常见问题|FAQ|怎么退款|退货|配送|支付/i];
+
+  async execute(input: string): Promise<string> {
+    // 常见问题知识库 / FAQ Knowledge Base
+    const faqs: Record<string, string> = {
+      '退款': '退款将在3-5个工作日内到账。如超时未到账，请联系银行确认。',
+      '退货': '请在收到商品7天内申请退货。商品需保持原包装，未使用。',
+      '配送': '标准配送3-5天，加急配送1-2天。偏远地区可能延迟1-2天。',
+      '支付': '支持支付宝、微信支付、银行卡（Visa/Mastercard/银联）。',
+    };
+
+    for (const [key, answer] of Object.entries(faqs)) {
+      if (input.includes(key)) return answer;
+    }
+
+    return '请问您想了解什么？我们有以下常见问题：退款、退货、配送、支付';
+  }
+}

package/tutorial/customer-service-agent/src/skills/ticket.ts

@@ -1,22 +1,22 @@
-/**
- * Ticket Skill — 工单创建技能
- * Creates a support ticket for human follow-up.
- */
-import { BaseSkill } from 'opc-agent';
-
-export class TicketSkill extends BaseSkill {
-  name = 'ticket';
-  description = 'Create a support ticket for human follow-up';
-  triggers = [/创建工单|提交问题|人工客服|投诉/i];
-
-  async execute(input: string): Promise<string> {
-    // 生成唯一工单号 / Generate unique ticket ID
-    const ticketId = `TK-${Date.now().toString(36).toUpperCase()}`;
-
-    // 实际项目中这里会写入数据库
-    // In production, this would persist to a database
-    console.log(`[Ticket Created] ${ticketId}: ${input}`);
-
-    return `已创建工单 ${ticketId}，客服团队将在2小时内联系您。\nTicket ${ticketId} created. Our team will contact you within 2 hours.`;
-  }
-}
+/**
+ * Ticket Skill — 工单创建技能
+ * Creates a support ticket for human follow-up.
+ */
+import { BaseSkill } from 'opc-agent';
+
+export class TicketSkill extends BaseSkill {
+  name = 'ticket';
+  description = 'Create a support ticket for human follow-up';
+  triggers = [/创建工单|提交问题|人工客服|投诉/i];
+
+  async execute(input: string): Promise<string> {
+    // 生成唯一工单号 / Generate unique ticket ID
+    const ticketId = `TK-${Date.now().toString(36).toUpperCase()}`;
+
+    // 实际项目中这里会写入数据库
+    // In production, this would persist to a database
+    console.log(`[Ticket Created] ${ticketId}: ${input}`);
+
+    return `已创建工单 ${ticketId}，客服团队将在2小时内联系您。\nTicket ${ticketId} created. Our team will contact you within 2 hours.`;
+  }
+}

package/tutorial/customer-service-agent/tsconfig.json

@@ -1,14 +1,14 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "node",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "declaration": true
-  },
-  "include": ["src/**/*"]
-}
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}