opc-agent 1.3.2 → 1.4.0

package/docs/zh/index.md

@@ -1,27 +1,27 @@
----
-layout: home
-hero:
-  name: OPC Agent
-  text: 开放智能体框架
-  tagline: 构建、测试、运行企业级 AI 智能体
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /zh/guide/getting-started
-    - theme: alt
-      text: GitHub
-      link: https://github.com/Deepleaper/opc-agent
-features:
-  - title: ⚡ 30 秒上手
-    details: 两条命令创建智能体，开箱即用，支持 12 个场景模板
-  - title: 📋 OAD 声明式定义
-    details: 用 YAML 文件定义智能体的一切：模型、技能、渠道、安全策略
-  - title: 📡 多渠道部署
-    details: Web、Telegram、Slack、微信公众号、飞书、WebSocket，一套代码到处运行
-  - title: 🧪 内置测试框架
-    details: 在 OAD 文件中定义测试用例，opc test 一键验证智能体行为
-  - title: 🔌 多模型支持
-    details: DeepSeek、通义千问、OpenAI、Anthropic、Ollama，不绑定任何一家
-  - title: 🧠 知识库 RAG
-    details: 添加文档自动构建知识库，智能体回答时语义检索增强
----
+---
+layout: home
+hero:
+  name: OPC Agent
+  text: 开放智能体框架
+  tagline: 构建、测试、运行企业级 AI 智能体
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /zh/guide/getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/Deepleaper/opc-agent
+features:
+  - title: ⚡ 30 秒上手
+    details: 两条命令创建智能体，开箱即用，支持 12 个场景模板
+  - title: 📋 OAD 声明式定义
+    details: 用 YAML 文件定义智能体的一切：模型、技能、渠道、安全策略
+  - title: 📡 多渠道部署
+    details: Web、Telegram、Slack、微信公众号、飞书、WebSocket，一套代码到处运行
+  - title: 🧪 内置测试框架
+    details: 在 OAD 文件中定义测试用例，opc test 一键验证智能体行为
+  - title: 🔌 多模型支持
+    details: DeepSeek、通义千问、OpenAI、Anthropic、Ollama，不绑定任何一家
+  - title: 🧠 知识库 RAG
+    details: 添加文档自动构建知识库，智能体回答时语义检索增强
+---

package/examples/README.md

@@ -0,0 +1,22 @@
+# OPC Agent Examples
+
+## Run Examples
+
+```bash
+# Basic agent with skills
+npx tsx examples/basic-agent.ts
+
+# Multi-channel setup (Web + Telegram)
+npx tsx examples/multi-channel.ts
+
+# DeepBrain memory integration
+npx tsx examples/brain-integration.ts
+```
+
+## What Each Example Shows
+
+| Example | Concepts |
+|---------|----------|
+| `basic-agent.ts` | `BaseAgent`, `AgentRuntime`, `BaseSkill`, message handling |
+| `multi-channel.ts` | `WebChannel`, `TelegramChannel`, multi-channel config |
+| `brain-integration.ts` | `DeepBrainMemoryStore`, `InMemoryStore`, memory backends |

package/examples/basic-agent.ts

@@ -0,0 +1,90 @@
+/**
+ * OPC Agent Example: Basic Agent
+ *
+ * Create a simple agent with OAD config, register a skill, handle a message.
+ *
+ * Run: npx tsx examples/basic-agent.ts
+ */
+
+import {
+  BaseAgent,
+  AgentRuntime,
+  BaseSkill,
+  InMemoryStore,
+  type Message,
+  type AgentContext,
+  type SkillResult,
+} from 'opc-agent';
+
+// Define a custom skill
+class GreeterSkill extends BaseSkill {
+  name = 'greeter';
+  description = 'Responds to greetings';
+
+  canHandle(message: Message): boolean {
+    const text = message.content.toLowerCase();
+    return text.includes('hello') || text.includes('hi') || text.includes('hey');
+  }
+
+  async execute(message: Message, context: AgentContext): Promise<SkillResult> {
+    return {
+      content: `Hello! I'm ${context.agent?.name || 'Agent'}. How can I help you today?`,
+      confidence: 1.0,
+    };
+  }
+}
+
+async function main() {
+  console.log('🤖 OPC Agent — Basic Agent Demo\n');
+
+  try {
+    // Create agent with OAD-style config
+    const agent = new BaseAgent({
+      name: 'demo-agent',
+      description: 'A simple demo agent',
+      version: '1.0.0',
+    });
+
+    // Set up memory store
+    const memory = new InMemoryStore();
+
+    // Create runtime
+    const runtime = new AgentRuntime(agent, {
+      memory,
+    });
+
+    // Register skill
+    const greeter = new GreeterSkill();
+    runtime.registerSkill(greeter);
+
+    console.log(`✅ Agent "${agent.name}" created with ${1} skill\n`);
+
+    // Simulate messages
+    const testMessages: Message[] = [
+      { role: 'user', content: 'Hello there!' },
+      { role: 'user', content: 'What can you do?' },
+      { role: 'user', content: 'Hey, nice to meet you' },
+    ];
+
+    for (const msg of testMessages) {
+      console.log(`📨 User: ${msg.content}`);
+      const response = await runtime.handleMessage(msg);
+      console.log(`🤖 Agent: ${response?.content || '(no response)'}\n`);
+    }
+
+    console.log('✅ Done! OPC Agent supports:');
+    console.log('  • OAD config (YAML/JSON agent definition)');
+    console.log('  • Skill registration & routing');
+    console.log('  • Multi-channel (Web, Telegram, Slack, etc.)');
+    console.log('  • Memory stores (InMemory, DeepBrain)\n');
+    console.log('Next: npx tsx examples/multi-channel.ts');
+  } catch (e: any) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main().catch(e => {
+  console.error(`\n❌ Error: ${e.message}\n`);
+  process.exit(1);
+});

package/examples/brain-integration.ts

@@ -0,0 +1,71 @@
+/**
+ * OPC Agent Example: DeepBrain Memory Integration
+ *
+ * Shows how to use DeepBrainMemoryStore for persistent agent memory.
+ * Requires a running DeepBrain instance (or falls back to InMemory).
+ *
+ * Run: npx tsx examples/brain-integration.ts
+ */
+
+import {
+  BaseAgent,
+  AgentRuntime,
+  InMemoryStore,
+  DeepBrainMemoryStore,
+} from 'opc-agent';
+
+async function main() {
+  console.log('🧠 OPC Agent — DeepBrain Memory Integration\n');
+
+  try {
+    const agent = new BaseAgent({
+      name: 'brain-agent',
+      description: 'Agent with DeepBrain-powered memory',
+      version: '1.0.0',
+    });
+
+    // Try DeepBrain first, fall back to InMemory
+    let memory;
+    let memoryType: string;
+
+    try {
+      memory = new DeepBrainMemoryStore({
+        brainUrl: process.env.DEEPBRAIN_URL || 'http://localhost:3333',
+        agentId: 'brain-agent',
+      });
+      memoryType = 'DeepBrain';
+      console.log('✅ Using DeepBrain memory store');
+    } catch {
+      memory = new InMemoryStore();
+      memoryType = 'InMemory';
+      console.log('⚠️  DeepBrain unavailable, using InMemory fallback');
+    }
+
+    const runtime = new AgentRuntime(agent, { memory });
+
+    console.log(`\n📦 Memory store: ${memoryType}`);
+    console.log('\nDeepBrain vs InMemory:');
+    console.log('  ┌─────────────────┬────────────┬──────────────┐');
+    console.log('  │ Feature         │ InMemory   │ DeepBrain    │');
+    console.log('  ├─────────────────┼────────────┼──────────────┤');
+    console.log('  │ Persistence     │ ❌ (RAM)   │ ✅ (SQLite)  │');
+    console.log('  │ Semantic search │ ❌         │ ✅           │');
+    console.log('  │ Evolve          │ ❌         │ ✅           │');
+    console.log('  │ Multi-agent     │ ❌         │ ✅           │');
+    console.log('  │ Zero config     │ ✅         │ ✅           │');
+    console.log('  └─────────────────┴────────────┴──────────────┘\n');
+
+    console.log('✅ Done! To use DeepBrain:');
+    console.log('  npm install deepbrain');
+    console.log('  deepbrain serve  # starts on :3333');
+    console.log('  DEEPBRAIN_URL=http://localhost:3333 npx tsx examples/brain-integration.ts\n');
+  } catch (e: any) {
+    console.error(`❌ Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main().catch(e => {
+  console.error(`\n❌ Error: ${e.message}\n`);
+  process.exit(1);
+});

package/examples/customer-service-demo/README.md

@@ -1,90 +1,90 @@
-# ShopBot — Customer Service Demo
-
-A complete e-commerce customer service agent built with OPC Agent, deployable to OpenClaw.
-
-## What's Inside
-
-- `oad.yaml` — Full agent definition with product FAQ, order tracking, complaint handling
-- Rich system prompt with personality, escalation rules, and response templates
-- Telegram + Web channel configuration
-
-## Quick Start
-
-### 1. Install OPC Agent
-
-```bash
-npm install -g opc-agent
-```
-
-### 2. Validate the Agent
-
-```bash
-cd examples/customer-service-demo
-opc info
-opc build
-```
-
-### 3. Deploy to OpenClaw
-
-**Option A: Generate workspace files**
-```bash
-opc deploy --target openclaw --output ./shopbot-workspace
-```
-
-This creates a complete OpenClaw agent workspace with:
-- `IDENTITY.md` — Agent identity
-- `SOUL.md` — System prompt and model config
-- `AGENTS.md` — Skills, memory, and trust config
-- `USER.md` — User preferences template
-- `MEMORY.md` — Persistent memory template
-
-**Option B: Deploy and auto-register**
-```bash
-opc deploy --target openclaw --install
-```
-
-This generates the workspace AND registers the agent in `~/.openclaw/openclaw.json`.
-
-### 4. Restart OpenClaw
-
-```bash
-openclaw gateway restart
-```
-
-### 5. Test in Telegram
-
-Send a message to your OpenClaw Telegram bot. ShopBot will respond!
-
-Try these:
-- "What headphones do you sell?"
-- "Track my order TS-123456"
-- "I want to return my laptop stand"
-- "This is unacceptable, I want to speak to a manager"
-
-## Architecture
-
-```
-OPC Agent (Development)          OpenClaw (Runtime)
-┌─────────────────────┐         ┌──────────────────────┐
-│  oad.yaml           │         │  IDENTITY.md         │
-│  (agent definition) │──deploy─│  SOUL.md             │
-│                     │         │  AGENTS.md           │
-│  opc build/test     │         │  USER.md             │
-│  opc deploy         │         │  MEMORY.md           │
-└─────────────────────┘         │                      │
-                                │  ← Telegram/Web →    │
-                                └──────────────────────┘
-```
-
-OPC Agent is the **development framework**. OpenClaw is the **runtime**.
-
-## Customization
-
-Edit `oad.yaml` to:
-- Change the product catalog
-- Adjust escalation rules
-- Add new skills
-- Switch LLM provider/model
-- Modify the system prompt personality
-
-Then re-deploy: `opc deploy --target openclaw --install`
+# ShopBot — Customer Service Demo
+
+A complete e-commerce customer service agent built with OPC Agent, deployable to OpenClaw.
+
+## What's Inside
+
+- `oad.yaml` — Full agent definition with product FAQ, order tracking, complaint handling
+- Rich system prompt with personality, escalation rules, and response templates
+- Telegram + Web channel configuration
+
+## Quick Start
+
+### 1. Install OPC Agent
+
+```bash
+npm install -g opc-agent
+```
+
+### 2. Validate the Agent
+
+```bash
+cd examples/customer-service-demo
+opc info
+opc build
+```
+
+### 3. Deploy to OpenClaw
+
+**Option A: Generate workspace files**
+```bash
+opc deploy --target openclaw --output ./shopbot-workspace
+```
+
+This creates a complete OpenClaw agent workspace with:
+- `IDENTITY.md` — Agent identity
+- `SOUL.md` — System prompt and model config
+- `AGENTS.md` — Skills, memory, and trust config
+- `USER.md` — User preferences template
+- `MEMORY.md` — Persistent memory template
+
+**Option B: Deploy and auto-register**
+```bash
+opc deploy --target openclaw --install
+```
+
+This generates the workspace AND registers the agent in `~/.openclaw/openclaw.json`.
+
+### 4. Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+### 5. Test in Telegram
+
+Send a message to your OpenClaw Telegram bot. ShopBot will respond!
+
+Try these:
+- "What headphones do you sell?"
+- "Track my order TS-123456"
+- "I want to return my laptop stand"
+- "This is unacceptable, I want to speak to a manager"
+
+## Architecture
+
+```
+OPC Agent (Development)          OpenClaw (Runtime)
+┌─────────────────────┐         ┌──────────────────────┐
+│  oad.yaml           │         │  IDENTITY.md         │
+│  (agent definition) │──deploy─│  SOUL.md             │
+│                     │         │  AGENTS.md           │
+│  opc build/test     │         │  USER.md             │
+│  opc deploy         │         │  MEMORY.md           │
+└─────────────────────┘         │                      │
+                                │  ← Telegram/Web →    │
+                                └──────────────────────┘
+```
+
+OPC Agent is the **development framework**. OpenClaw is the **runtime**.
+
+## Customization
+
+Edit `oad.yaml` to:
+- Change the product catalog
+- Adjust escalation rules
+- Add new skills
+- Switch LLM provider/model
+- Modify the system prompt personality
+
+Then re-deploy: `opc deploy --target openclaw --install`

package/examples/customer-service-demo/oad.yaml

@@ -1,107 +1,107 @@
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: ShopBot
-  version: "1.0.0"
-  description: "E-commerce customer service agent for TechStyle — handles product FAQs, order tracking, returns, and complaint escalation"
-  author: "TechStyle Inc."
-  license: Apache-2.0
-  marketplace:
-    category: customer-service
-    pricing: free
-    tags: [ecommerce, support, faq, orders]
-
-spec:
-  provider:
-    default: deepseek
-    allowed: [openai, deepseek, qwen]
-  model: deepseek-chat
-
-  systemPrompt: |
-    You are ShopBot, the friendly and professional customer service agent for TechStyle, 
-    an online electronics and lifestyle store.
-
-    ## Personality
-    - Warm, helpful, and patient
-    - Professional but not robotic — use a conversational tone
-    - Proactive: anticipate follow-up questions
-    - Empathetic: acknowledge customer frustration before solving problems
-
-    ## Core Capabilities
-    1. **Product FAQ**: Answer questions about products, specs, pricing, availability
-    2. **Order Tracking**: Look up order status by order ID (format: TS-XXXXXX)
-    3. **Returns & Refunds**: Guide customers through return process (30-day policy)
-    4. **Complaint Handling**: De-escalate issues, offer solutions, escalate when needed
-
-    ## Escalation Rules
-    - Escalate to human agent if:
-      - Customer asks 3+ times about the same unresolved issue
-      - Customer explicitly requests a human
-      - Issue involves billing disputes over $100
-      - Customer uses abusive language (remain calm, offer to transfer)
-    - Say: "Let me connect you with a specialist who can help further."
-
-    ## Response Guidelines
-    - Keep responses under 200 words unless detailed explanation is needed
-    - Always confirm understanding: "Just to make sure I understand..."
-    - End with a follow-up: "Is there anything else I can help with?"
-    - For order lookups, ask for order ID if not provided
-    - Never make up order status — if you can't find it, say so
-
-    ## Product Catalog (Quick Reference)
-    - TechStyle Pro Headphones — $149, wireless, ANC, 30hr battery
-    - TechStyle Slim Laptop Stand — $59, aluminum, adjustable
-    - TechStyle Power Bank 20K — $39, 20000mAh, USB-C PD
-    - TechStyle Smart Watch S3 — $199, health tracking, 5-day battery
-    - TechStyle Webcam 4K — $89, autofocus, built-in mic
-
-    ## Return Policy
-    - 30-day return window from delivery date
-    - Item must be in original packaging
-    - Free return shipping for defective items
-    - Refund processed within 5-7 business days
-    - Gift cards and sale items are final sale
-
-  skills:
-    - name: product-faq
-      description: "Answer product questions from the catalog knowledge base"
-      config:
-        source: catalog
-        fallback: "I don't have that info right now. Let me check with the team."
-
-    - name: order-lookup
-      description: "Look up order status by order ID"
-      config:
-        idPattern: "TS-\\d{6}"
-        notFoundMessage: "I couldn't find that order. Double-check the ID (format: TS-XXXXXX)."
-
-    - name: complaint-handler
-      description: "Handle complaints with empathy and escalation logic"
-      config:
-        maxAttempts: 3
-        escalationMessage: "Let me connect you with a specialist who can help further."
-
-  channels:
-    - type: telegram
-      config:
-        welcomeMessage: "Hi! 👋 I'm ShopBot from TechStyle. How can I help you today?"
-    - type: web
-      port: 3000
-
-  memory:
-    shortTerm: true
-    longTerm: false
-
-  dtv:
-    trust:
-      level: verified
-    value:
-      metrics:
-        - response_time
-        - resolution_rate
-        - customer_satisfaction
-
-  streaming:
-    enabled: true
-
-  locale: en
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: ShopBot
+  version: "1.0.0"
+  description: "E-commerce customer service agent for TechStyle — handles product FAQs, order tracking, returns, and complaint escalation"
+  author: "TechStyle Inc."
+  license: Apache-2.0
+  marketplace:
+    category: customer-service
+    pricing: free
+    tags: [ecommerce, support, faq, orders]
+
+spec:
+  provider:
+    default: deepseek
+    allowed: [openai, deepseek, qwen]
+  model: deepseek-chat
+
+  systemPrompt: |
+    You are ShopBot, the friendly and professional customer service agent for TechStyle, 
+    an online electronics and lifestyle store.
+
+    ## Personality
+    - Warm, helpful, and patient
+    - Professional but not robotic — use a conversational tone
+    - Proactive: anticipate follow-up questions
+    - Empathetic: acknowledge customer frustration before solving problems
+
+    ## Core Capabilities
+    1. **Product FAQ**: Answer questions about products, specs, pricing, availability
+    2. **Order Tracking**: Look up order status by order ID (format: TS-XXXXXX)
+    3. **Returns & Refunds**: Guide customers through return process (30-day policy)
+    4. **Complaint Handling**: De-escalate issues, offer solutions, escalate when needed
+
+    ## Escalation Rules
+    - Escalate to human agent if:
+      - Customer asks 3+ times about the same unresolved issue
+      - Customer explicitly requests a human
+      - Issue involves billing disputes over $100
+      - Customer uses abusive language (remain calm, offer to transfer)
+    - Say: "Let me connect you with a specialist who can help further."
+
+    ## Response Guidelines
+    - Keep responses under 200 words unless detailed explanation is needed
+    - Always confirm understanding: "Just to make sure I understand..."
+    - End with a follow-up: "Is there anything else I can help with?"
+    - For order lookups, ask for order ID if not provided
+    - Never make up order status — if you can't find it, say so
+
+    ## Product Catalog (Quick Reference)
+    - TechStyle Pro Headphones — $149, wireless, ANC, 30hr battery
+    - TechStyle Slim Laptop Stand — $59, aluminum, adjustable
+    - TechStyle Power Bank 20K — $39, 20000mAh, USB-C PD
+    - TechStyle Smart Watch S3 — $199, health tracking, 5-day battery
+    - TechStyle Webcam 4K — $89, autofocus, built-in mic
+
+    ## Return Policy
+    - 30-day return window from delivery date
+    - Item must be in original packaging
+    - Free return shipping for defective items
+    - Refund processed within 5-7 business days
+    - Gift cards and sale items are final sale
+
+  skills:
+    - name: product-faq
+      description: "Answer product questions from the catalog knowledge base"
+      config:
+        source: catalog
+        fallback: "I don't have that info right now. Let me check with the team."
+
+    - name: order-lookup
+      description: "Look up order status by order ID"
+      config:
+        idPattern: "TS-\\d{6}"
+        notFoundMessage: "I couldn't find that order. Double-check the ID (format: TS-XXXXXX)."
+
+    - name: complaint-handler
+      description: "Handle complaints with empathy and escalation logic"
+      config:
+        maxAttempts: 3
+        escalationMessage: "Let me connect you with a specialist who can help further."
+
+  channels:
+    - type: telegram
+      config:
+        welcomeMessage: "Hi! 👋 I'm ShopBot from TechStyle. How can I help you today?"
+    - type: web
+      port: 3000
+
+  memory:
+    shortTerm: true
+    longTerm: false
+
+  dtv:
+    trust:
+      level: verified
+    value:
+      metrics:
+        - response_time
+        - resolution_rate
+        - customer_satisfaction
+
+  streaming:
+    enabled: true
+
+  locale: en