opc-agent 4.1.1 → 4.1.3

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

@@ -1,612 +0,0 @@
-# Build a Customer Service Agent with OPC Agent
-
-A step-by-step guide covering **every** major feature of OPC Agent — from project setup to production deployment.
-
-> 🌐 中英双语注释 | Bilingual comments throughout
-
-## Table of Contents
-
-1. [Project Setup](#chapter-1-project-setup)
-2. [Agent Configuration (OAD)](#chapter-2-agent-configuration)
-3. [Skills](#chapter-3-skills)
-4. [Memory with DeepBrain](#chapter-4-memory-with-deepbrain)
-5. [Channels (Web, Telegram, Discord)](#chapter-5-channels)
-6. [Workflow Engine](#chapter-6-workflow-engine)
-7. [Built-in Tools](#chapter-7-built-in-tools)
-8. [Sub-Agents](#chapter-8-sub-agents)
-9. [Plugin System](#chapter-9-plugin-system)
-10. [Scheduled Jobs (Cron)](#chapter-10-scheduled-jobs)
-11. [Security](#chapter-11-security)
-12. [Packaging & Publishing](#chapter-12-packaging--publishing)
-13. [Monitoring & Analytics](#chapter-13-monitoring--analytics)
-
----
-
-## Chapter 1: Project Setup
-
-### Prerequisites
-
-- Node.js >= 18
-- npm or yarn
-- (Optional) Ollama for local LLM inference
-
-### Install & Initialize
-
-```bash
-# 安装 OPC Agent CLI / Install the CLI globally
-npm install -g opc-agent
-
-# 检查环境 / Verify your environment
-opc doctor
-
-# 创建项目 / Scaffold a new agent project
-opc init customer-service
-cd customer-service
-npm install
-```
-
-`opc doctor` checks for Node version, required dependencies, and optional integrations (Ollama, Docker, etc.).
-
-### Project Structure
-
-After initialization, you'll have:
-
-```
-customer-service/
-├── agent.yaml          # Agent configuration (OAD spec)
-├── SOUL.md             # Agent personality & behavior guide
-├── package.json        # Node.js dependencies
-├── tsconfig.json       # TypeScript config
-└── src/
-    ├── index.ts        # Entry point
-    └── skills/         # Custom skills
-        ├── faq.ts
-        └── ticket.ts
-```
-
----
-
-## Chapter 2: Agent Configuration
-
-The `agent.yaml` file is the heart of your agent — it follows the **OAD (Open Agent Definition)** spec.
-
-```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: customer-service
-  version: 1.0.0
-  description: 智能客服 Agent — Smart Customer Service Agent
-  author: your-name
-  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
-
-  # 记忆系统 / 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"
-
-  # 安全配置 / Security
-  security:
-    approval: dangerous
-    sandbox:
-      maxFileSize: 10485760
-```
-
-### Key Sections Explained
-
-| Section | Purpose |
-|---------|---------|
-| `metadata` | Agent identity — name, version, description |
-| `spec.model` | Which LLM to use |
-| `spec.provider` | LLM provider (ollama, openai, etc.) |
-| `spec.systemPrompt` | Base personality and rules |
-| `spec.channels` | How users interact with the agent |
-| `spec.memory` | Conversation memory settings |
-| `spec.skills` | Registered skill modules |
-| `spec.scheduler` | Cron-based scheduled tasks |
-| `spec.security` | Permission and sandbox settings |
-
----
-
-## Chapter 3: Skills
-
-Skills are modular capabilities your agent can invoke. Each skill has a name, description, trigger patterns, and an `execute` method.
-
-### FAQ Skill — `src/skills/faq.ts`
-
-```typescript
-import { BaseSkill } from 'opc-agent';
-
-// FAQ 查询技能 / FAQ Lookup Skill
-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 '请问您想了解什么？我们有以下常见问题：退款、退货、配送、支付';
-  }
-}
-```
-
-### Ticket Skill — `src/skills/ticket.ts`
-
-```typescript
-import { BaseSkill } from 'opc-agent';
-
-// 工单创建技能 / Support Ticket Skill
-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 write to a database
-    console.log(`[Ticket Created] ${ticketId}: ${input}`);
-
-    return `已创建工单 ${ticketId}，客服团队将在2小时内联系您。\nTicket ${ticketId} created. Our team will contact you within 2 hours.`;
-  }
-}
-```
-
-### Registering Skills
-
-Skills listed in `agent.yaml` under `spec.skills` are auto-discovered from `src/skills/`. The agent matches incoming messages against `triggers` and routes to the appropriate skill.
-
----
-
-## Chapter 4: Memory with DeepBrain
-
-OPC Agent integrates with **DeepBrain** for persistent memory — enabling your agent to learn from past conversations.
-
-```typescript
-// src/index.ts
-import { Agent } from 'opc-agent';
-import { Brain } from 'deepbrain';
-
-// 初始化 DeepBrain / Initialize DeepBrain
-const brain = new Brain({
-  database: './data/customer-brain.db',
-  embedding_provider: 'ollama',
-});
-await brain.connect();
-
-const agent = new Agent('./agent.yaml');
-
-// 存储对话用于学习 / Store conversations for learning
-agent.on('message', async (msg, response) => {
-  await brain.put(
-    `conv-${msg.id}`,
-    `Q: ${msg.content}\nA: ${response.content}`
-  );
-});
-
-// 语义搜索历史对话 / Semantic search past conversations
-agent.on('beforeReply', async (ctx) => {
-  const relevant = await brain.query(ctx.message, { limit: 3 });
-  if (relevant.length > 0) {
-    ctx.additionalContext = relevant.map(r => r.content).join('\n');
-  }
-});
-
-await agent.start();
-```
-
-### What DeepBrain Provides
-
-- **Semantic search** — Find relevant past conversations by meaning, not just keywords
-- **Persistent storage** — SQLite-based, survives restarts
-- **Embedding support** — Works with Ollama, OpenAI, or Gemini embeddings
-
----
-
-## Chapter 5: Channels
-
-Channels define how users interact with your agent. OPC Agent supports multiple simultaneous channels.
-
-### Web (Built-in)
-
-```yaml
-spec:
-  channels:
-    - type: web
-      port: 3000
-```
-
-Launches a web chat UI at `http://localhost:3000`.
-
-### Telegram
-
-```yaml
-spec:
-  channels:
-    - type: web
-      port: 3000
-    - type: telegram
-      token: ${TELEGRAM_BOT_TOKEN}
-      mode: polling
-```
-
-Set the environment variable `TELEGRAM_BOT_TOKEN` from [@BotFather](https://t.me/BotFather).
-
-### Discord
-
-```yaml
-spec:
-  channels:
-    - type: discord
-      token: ${DISCORD_BOT_TOKEN}
-      guildId: "your-server-id"
-```
-
-### Multi-Channel
-
-All channels share the same agent logic, skills, and memory. A message from Telegram triggers the same FAQ skill as one from the web UI.
-
----
-
-## Chapter 6: Workflow Engine
-
-For multi-step interactions, use the **Workflow Engine** to define conversation flows with branching logic.
-
-```typescript
-import { WorkflowBuilder } from 'opc-agent';
-
-// 客户引导流程 / Customer Onboarding Workflow
-const onboarding = new WorkflowBuilder()
-  .start('greet')
-  .addAction('greet', async (ctx) => {
-    return '欢迎！请问您是新客户还是老客户？\nWelcome! Are you a new or returning customer?';
-  }, { next: 'check-type' })
-  .addCondition('check-type',
-    (ctx) => ctx.variables.get('isNewCustomer'),
-    'new-flow',       // true 分支 / true branch
-    'existing-flow'   // false 分支 / false branch
-  )
-  .addAction('new-flow', async (ctx) => {
-    return '让我帮您注册账号。请提供您的邮箱地址。';
-  }, { next: 'collect-email' })
-  .addAction('collect-email', async (ctx) => {
-    const email = ctx.message;
-    ctx.variables.set('email', email);
-    return `注册成功！欢迎加入，${email}`;
-  }, { next: 'done' })
-  .addAction('existing-flow', async (ctx) => {
-    return '欢迎回来！有什么可以帮您？';
-  }, { next: 'done' })
-  .addAction('done', async () => 'Onboarding complete')
-  .build();
-
-// 注册工作流 / Register the workflow
-agent.registerWorkflow('onboarding', onboarding);
-```
-
-### Workflow Features
-
-- **Branching** — Conditional paths based on user input or variables
-- **State management** — `ctx.variables` persists across steps
-- **Composable** — Workflows can trigger other workflows
-
----
-
-## Chapter 7: Built-in Tools
-
-OPC Agent comes with built-in tools that your agent can use autonomously.
-
-```typescript
-import { getBuiltinTools } from 'opc-agent';
-
-// 加载内置工具 / Load built-in tools
-const tools = getBuiltinTools('./workspace');
-```
-
-### Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `readFile` | Read file contents |
-| `writeFile` | Write/create files |
-| `fetchUrl` | HTTP requests to external APIs |
-| `runCommand` | Execute shell commands (sandboxed) |
-| `getTime` | Current date/time |
-| `listFiles` | Directory listing |
-
-### Example: Agent Uses Tools
-
-```typescript
-// Agent can autonomously decide to use tools
-// 例如查询订单状态时，agent 可以调用 API
-const agent = new Agent('./agent.yaml', { tools });
-```
-
-The agent decides which tools to invoke based on the user's request and the tool descriptions.
-
----
-
-## Chapter 8: Sub-Agents
-
-For complex tasks, spawn specialized sub-agents that work independently and report back.
-
-```typescript
-import { SubAgentManager } from 'opc-agent';
-
-const manager = new SubAgentManager();
-
-// 委派研究任务给子 Agent / Delegate research to a sub-agent
-const result = await agent.spawnSubAgent({
-  name: 'researcher',
-  task: 'Find the return policy for order #12345',
-  systemPrompt: 'You are a research specialist. Find accurate information.',
-  model: 'qwen2.5',
-});
-
-console.log(result.output); // Sub-agent's findings
-```
-
-### Sub-Agent Use Cases
-
-- **Research** — Look up order details, policies, product info
-- **Translation** — Translate customer messages
-- **Analysis** — Analyze sentiment or categorize issues
-- **Escalation** — Prepare summaries for human agents
-
----
-
-## Chapter 9: Plugin System
-
-Extend your agent with plugins for cross-cutting concerns.
-
-```typescript
-import { loggerPlugin, rateLimiterPlugin } from 'opc-agent';
-
-const agent = new Agent('./agent.yaml', {
-  plugins: [
-    // 日志插件 / Logger — logs all messages
-    loggerPlugin({ level: 'info', output: './logs/agent.log' }),
-
-    // 限流插件 / Rate limiter — prevent abuse
-    rateLimiterPlugin({ maxRequests: 60, windowMs: 60000 }),
-  ],
-});
-```
-
-### Plugin Lifecycle Hooks
-
-Plugins can hook into:
-- `onMessage` — Before processing a message
-- `onReply` — Before sending a reply
-- `onError` — When an error occurs
-- `onStart` / `onStop` — Agent lifecycle
-
-### Writing a Custom Plugin
-
-```typescript
-import { Plugin } from 'opc-agent';
-
-// 自定义插件示例 / Custom plugin example
-export const metricsPlugin: Plugin = {
-  name: 'metrics',
-  onMessage: async (msg) => {
-    console.log(`[${new Date().toISOString()}] Received: ${msg.content.slice(0, 50)}`);
-  },
-  onReply: async (msg, reply) => {
-    console.log(`[${new Date().toISOString()}] Replied in ${reply.latencyMs}ms`);
-  },
-};
-```
-
----
-
-## Chapter 10: Scheduled Jobs
-
-Run tasks on a schedule using cron syntax.
-
-```yaml
-# agent.yaml
-spec:
-  scheduler:
-    jobs:
-      - name: daily-report
-        schedule: "0 9 * * *"          # 每天早上9点 / Daily at 9 AM
-        task: "Generate daily customer service report"
-
-      - name: cleanup-old-tickets
-        schedule: "0 2 * * 0"          # 每周日凌晨2点 / Sunday 2 AM
-        task: "Archive tickets older than 30 days"
-
-      - name: health-check
-        schedule: "*/15 * * * *"       # 每15分钟 / Every 15 minutes
-        task: "Check all channel connections are alive"
-```
-
-### Managing Jobs
-
-```bash
-# 查看所有任务 / List all scheduled jobs
-opc jobs list
-
-# 手动触发 / Manually trigger a job
-opc jobs run daily-report
-
-# 查看历史 / View job history
-opc jobs history
-```
-
----
-
-## Chapter 11: Security
-
-OPC Agent provides multiple security layers.
-
-```yaml
-spec:
-  security:
-    # 危险操作需要审批 / Dangerous actions require approval
-    approval: dangerous
-
-    # 沙箱限制 / Sandbox constraints
-    sandbox:
-      maxFileSize: 10485760          # 10MB max file size
-      allowedCommands:               # Whitelist commands
-        - "curl"
-        - "node"
-      blockedPaths:                  # Protect sensitive paths
-        - "/etc"
-        - "~/.ssh"
-```
-
-### Security Features
-
-| Feature | Description |
-|---------|-------------|
-| **Approval mode** | `dangerous` ops need human approval |
-| **Sandbox** | File size limits, command whitelist |
-| **Path blocking** | Prevent access to sensitive directories |
-| **Rate limiting** | Via plugin (Chapter 9) |
-| **Token rotation** | Channel tokens via env vars, not hardcoded |
-
-### Best Practices
-
-- Never hardcode API keys — use `${ENV_VAR}` syntax in `agent.yaml`
-- Enable `approval: dangerous` in production
-- Set `maxFileSize` to prevent resource exhaustion
-- Use `allowedCommands` to restrict what the agent can execute
-
----
-
-## Chapter 12: Packaging & Publishing
-
-Share your agent with others via the OPC registry.
-
-```bash
-# 预览打包内容 / Preview what will be packaged
-opc pack --list
-
-# 试运行发布 / Dry run — see what would happen
-opc publish --dry-run
-
-# 正式发布 / Publish to the registry
-opc publish
-```
-
-### What Gets Packaged
-
-- `agent.yaml` — Configuration
-- `SOUL.md` — Personality
-- `src/` — Skills and logic
-- `package.json` — Dependencies
-
-### Versioning
-
-Follow semver in `metadata.version`. Bump before each publish:
-
-```bash
-# Update version in agent.yaml
-# metadata:
-#   version: 1.1.0
-opc publish
-```
-
----
-
-## Chapter 13: Monitoring & Analytics
-
-### Running Your Agent
-
-```bash
-# 开发模式 / Development — interactive CLI chat
-opc chat
-
-# 服务模式 / Server — starts web server + all channels
-opc run
-
-# 生产模式 / Production — runs as daemon
-opc start
-
-# 检查状态 / Check status
-opc status
-
-# 查看日志 / View logs
-opc logs --tail 100
-
-# 停止 / Stop
-opc stop
-```
-
-### Monitoring
-
-- **`opc status`** — Shows agent health, active channels, memory usage
-- **`opc jobs list`** — Cron job status and next run times
-- **Logs** — Structured JSON logs for integration with ELK, Grafana, etc.
-- **Metrics plugin** — Custom metrics (see Chapter 9)
-
-### Production Checklist
-
-- [ ] Set `approval: dangerous` in security config
-- [ ] Configure all channel tokens via environment variables
-- [ ] Enable logging plugin with file output
-- [ ] Set up cron jobs for maintenance tasks
-- [ ] Test all skills with edge cases
-- [ ] Run `opc doctor` to verify environment
-- [ ] Use `opc start` (daemon mode) instead of `opc run`
-
----
-
-## Next Steps
-
-- 📖 Read the [OPC Agent Documentation](https://github.com/Deepleaper/opc-agent)
-- 🧩 Explore community skills on the OPC registry
-- 🤝 Join the community on Discord/Telegram
-
----
-
-*Built with ❤️ using [OPC Agent](https://github.com/Deepleaper/opc-agent)*

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

@@ -1,26 +0,0 @@
-# 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 +0,0 @@
-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 +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"
-  }
-}