opc-agent 0.8.0 → 0.9.0

package/dist/testing/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTestCases = loadTestCases;
+exports.runTests = runTests;
+exports.formatReport = formatReport;
+/**
+ * Agent Testing Framework - Define test cases in OAD, run with `opc test`.
+ * Supports assertions on response content, tool calls, and latency.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+const runtime_1 = require("../core/runtime");
+/**
+ * Load test cases from OAD spec.testing or a separate test file.
+ */
+function loadTestCases(oadPath) {
+    const raw = fs.readFileSync(oadPath, 'utf-8');
+    const config = yaml.load(raw);
+    // Check spec.testing.cases
+    if (config?.spec?.testing?.cases) {
+        return config.spec.testing.cases;
+    }
+    // Check for companion test file
+    const dir = path.dirname(oadPath);
+    const testFile = path.join(dir, 'tests.yaml');
+    if (fs.existsSync(testFile)) {
+        const testRaw = fs.readFileSync(testFile, 'utf-8');
+        const testConfig = yaml.load(testRaw);
+        return testConfig?.cases ?? testConfig ?? [];
+    }
+    return [];
+}
+/**
+ * Run all test cases against an agent.
+ */
+async function runTests(oadPath) {
+    const cases = loadTestCases(oadPath);
+    const results = [];
+    const startTime = Date.now();
+    if (cases.length === 0) {
+        // Generate default smoke test
+        cases.push({
+            name: 'smoke-test',
+            input: 'Hello! What can you help me with?',
+            expect: { maxLatencyMs: 30000 },
+        });
+    }
+    const runtime = new runtime_1.AgentRuntime();
+    await runtime.loadConfig(oadPath);
+    const agent = await runtime.initialize();
+    for (const tc of cases) {
+        const result = {
+            name: tc.name,
+            passed: true,
+            durationMs: 0,
+            failures: [],
+        };
+        const t0 = Date.now();
+        try {
+            const response = await agent.handleMessage({
+                id: `test_${Date.now()}`,
+                role: 'user',
+                content: tc.input,
+                timestamp: Date.now(),
+            });
+            result.durationMs = Date.now() - t0;
+            result.response = response.content;
+            if (tc.expect) {
+                // Check contains
+                if (tc.expect.contains) {
+                    for (const s of tc.expect.contains) {
+                        if (!response.content.toLowerCase().includes(s.toLowerCase())) {
+                            result.failures.push(`Expected response to contain "${s}"`);
+                        }
+                    }
+                }
+                // Check notContains
+                if (tc.expect.notContains) {
+                    for (const s of tc.expect.notContains) {
+                        if (response.content.toLowerCase().includes(s.toLowerCase())) {
+                            result.failures.push(`Expected response NOT to contain "${s}"`);
+                        }
+                    }
+                }
+                // Check latency
+                if (tc.expect.maxLatencyMs && result.durationMs > tc.expect.maxLatencyMs) {
+                    result.failures.push(`Latency ${result.durationMs}ms exceeded max ${tc.expect.maxLatencyMs}ms`);
+                }
+                // Check tool calls (from metadata if available)
+                if (tc.expect.toolCalled && response.toolsCalled) {
+                    for (const tool of tc.expect.toolCalled) {
+                        if (!response.toolsCalled.includes(tool)) {
+                            result.failures.push(`Expected tool "${tool}" to be called`);
+                        }
+                    }
+                }
+            }
+            result.passed = result.failures.length === 0;
+        }
+        catch (err) {
+            result.durationMs = Date.now() - t0;
+            result.passed = false;
+            result.failures.push(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        results.push(result);
+    }
+    const totalDuration = Date.now() - startTime;
+    const passed = results.filter(r => r.passed).length;
+    return {
+        total: results.length,
+        passed,
+        failed: results.length - passed,
+        duration: totalDuration,
+        results,
+    };
+}
+/**
+ * Format test report for console output.
+ */
+function formatReport(report) {
+    const lines = [];
+    lines.push('');
+    lines.push('═══════════════════════════════════════════');
+    lines.push('  OPC Agent Test Report');
+    lines.push('═══════════════════════════════════════════');
+    lines.push('');
+    for (const r of report.results) {
+        const icon = r.passed ? '✔' : '✘';
+        const status = r.passed ? 'PASS' : 'FAIL';
+        lines.push(`  ${icon} [${status}] ${r.name} (${r.durationMs}ms)`);
+        for (const f of r.failures) {
+            lines.push(`      → ${f}`);
+        }
+    }
+    lines.push('');
+    lines.push('───────────────────────────────────────────');
+    lines.push(`  Total: ${report.total}  Passed: ${report.passed}  Failed: ${report.failed}  Duration: ${report.duration}ms`);
+    lines.push('───────────────────────────────────────────');
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map

package/docs/.vitepress/config.ts

@@ -0,0 +1,92 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'OPC Agent',
+  description: 'Open Agent Framework - Build, test, and run AI Agents for business workstations',
+  
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        nav: [
+          { text: 'Guide', link: '/guide/getting-started' },
+          { text: 'API', link: '/api/oad-schema' },
+          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
+        ],
+        sidebar: {
+          '/guide/': [
+            {
+              text: 'Introduction',
+              items: [
+                { text: 'Getting Started', link: '/guide/getting-started' },
+                { text: 'Core Concepts', link: '/guide/concepts' },
+              ],
+            },
+            {
+              text: 'Usage',
+              items: [
+                { text: 'Templates', link: '/guide/templates' },
+                { text: 'Configuration', link: '/guide/configuration' },
+                { text: 'Testing', link: '/guide/testing' },
+                { text: 'Deployment', link: '/guide/deployment' },
+              ],
+            },
+          ],
+          '/api/': [
+            {
+              text: 'Reference',
+              items: [
+                { text: 'OAD Schema', link: '/api/oad-schema' },
+                { text: 'CLI Commands', link: '/api/cli' },
+                { text: 'SDK', link: '/api/sdk' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+    zh: {
+      label: '中文',
+      lang: 'zh-CN',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/zh/guide/getting-started' },
+          { text: 'API', link: '/zh/api/oad-schema' },
+          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
+        ],
+        sidebar: {
+          '/zh/guide/': [
+            {
+              text: '介绍',
+              items: [
+                { text: '快速开始', link: '/zh/guide/getting-started' },
+                { text: '核心概念', link: '/zh/guide/concepts' },
+              ],
+            },
+            {
+              text: '使用',
+              items: [
+                { text: '模板', link: '/zh/guide/templates' },
+                { text: '配置', link: '/zh/guide/configuration' },
+                { text: '测试', link: '/zh/guide/testing' },
+                { text: '部署', link: '/zh/guide/deployment' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    logo: '/logo.svg',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Deepleaper/opc-agent' },
+    ],
+    footer: {
+      message: 'Released under the Apache-2.0 License.',
+      copyright: 'Copyright © 2025 Deepleaper',
+    },
+  },
+});

package/docs/api/cli.md

@@ -0,0 +1,48 @@
+# CLI Commands
+
+## Reference
+
+| Command | Description |
+|---------|-------------|
+| `opc init [name]` | Initialize a new agent project |
+| `opc run` | Start agent with web server |
+| `opc chat` | Interactive CLI chat |
+| `opc test` | Run agent tests |
+| `opc analytics` | Show usage analytics |
+| `opc info` | Show agent info from OAD |
+| `opc build` | Validate OAD |
+| `opc dev` | Hot-reload development mode |
+| `opc create <name>` | Create agent from template |
+| `opc deploy` | Deploy to OpenClaw or Hermes |
+| `opc publish` | Package for distribution |
+| `opc install <source>` | Install agent from package |
+| `opc search <query>` | Search OPC Registry |
+| `opc stats` | Show runtime stats |
+| `opc kb add <file>` | Add file to knowledge base |
+| `opc kb search <query>` | Search knowledge base |
+| `opc tool list` | List MCP tools |
+| `opc workflow run <name>` | Run a workflow |
+| `opc version-mgmt list` | List saved versions |
+
+## Common Options
+
+- `-f, --file <file>` — OAD file path (default: `oad.yaml`)
+- `-t, --template <name>` — Template name
+- `-p, --port <port>` — Port override
+- `--json` — JSON output (for test/analytics)
+
+## Examples
+
+```bash
+# Create a new project
+opc init my-bot -t teacher
+
+# Run tests
+opc test --json
+
+# View analytics
+opc analytics
+
+# Deploy
+opc deploy --target openclaw --install
+```

package/docs/api/sdk.md

@@ -0,0 +1,80 @@
+# SDK Reference
+
+## Core Classes
+
+### AgentRuntime
+
+```typescript
+import { AgentRuntime } from 'opc-agent';
+
+const runtime = new AgentRuntime();
+await runtime.loadConfig('oad.yaml');
+const agent = await runtime.initialize();
+await runtime.start();
+```
+
+### AnalyticsEngine
+
+```typescript
+import { AnalyticsEngine } from 'opc-agent';
+
+const engine = new AnalyticsEngine('.');
+engine.trackMessage('user-1', 250, 100, 50);
+engine.trackToolUse('search', true, 120);
+const stats = engine.getStats();
+```
+
+### RateLimiter
+
+```typescript
+import { RateLimiter } from 'opc-agent';
+
+const limiter = new RateLimiter({
+  userLimit: { maxRequests: 60, windowMs: 60000 },
+  providerLimit: { maxRequests: 100, windowMs: 60000 },
+});
+
+await limiter.acquire('user-1', 'openai');
+```
+
+### LLMCache
+
+```typescript
+import { LLMCache } from 'opc-agent';
+
+const cache = new LLMCache({ ttlMs: 3600000 });
+const key = LLMCache.makeKey(messages, systemPrompt);
+const cached = cache.get(key);
+if (!cached) {
+  const response = await callLLM(messages);
+  cache.set(key, response);
+}
+```
+
+### Testing
+
+```typescript
+import { runTests, formatReport } from 'opc-agent';
+
+const report = await runTests('oad.yaml');
+console.log(formatReport(report));
+```
+
+## Templates
+
+13 built-in templates:
+
+| Template | Description |
+|----------|-------------|
+| `customer-service` | FAQ + human handoff |
+| `sales-assistant` | Product Q&A + lead capture |
+| `knowledge-base` | RAG with DeepBrain |
+| `code-reviewer` | Bug detection + style checks |
+| `hr-recruiter` | Resume screening + interviews |
+| `project-manager` | Task tracking + meeting notes |
+| `content-writer` | Blog + social media + SEO |
+| `legal-assistant` | Contract review + compliance |
+| `financial-advisor` | Budget + expense tracking |
+| `executive-assistant` | Calendar + email + meetings |
+| `data-analyst` | Data querying + visualization |
+| `teacher` | Lesson plans + quizzes |

package/docs/guide/configuration.md

@@ -0,0 +1,79 @@
+# Configuration
+
+## OAD File Structure
+
+The `oad.yaml` file is the heart of your agent configuration:
+
+```yaml
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: my-agent
+  version: 1.0.0
+  description: My AI agent
+spec:
+  provider:
+    default: openai
+    allowed: [openai, deepseek, qwen]
+  model: gpt-4o-mini
+  systemPrompt: "You are a helpful assistant."
+  skills: []
+  channels:
+    - type: web
+      port: 3000
+  memory:
+    shortTerm: true
+    longTerm: false
+  testing:
+    cases:
+      - name: greeting-test
+        input: "Hello"
+        expect:
+          contains: ["hello", "help"]
+          maxLatencyMs: 5000
+  rateLimits:
+    perUser:
+      maxRequests: 60
+      windowMs: 60000
+    perProvider:
+      maxRequests: 100
+      windowMs: 60000
+  cache:
+    enabled: true
+    ttlMs: 3600000
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPC_LLM_API_KEY` | LLM API key | — |
+| `OPC_LLM_BASE_URL` | LLM API base URL | `https://api.openai.com/v1` |
+| `OPC_LLM_MODEL` | Model name | `gpt-4o-mini` |
+
+## Rate Limiting
+
+Configure per-user and per-provider rate limits in `oad.yaml`:
+
+```yaml
+spec:
+  rateLimits:
+    perUser:
+      maxRequests: 60
+      windowMs: 60000
+    perProvider:
+      maxRequests: 100
+      windowMs: 60000
+```
+
+## Caching
+
+Enable LLM response caching to reduce API costs:
+
+```yaml
+spec:
+  cache:
+    enabled: true
+    ttlMs: 3600000  # 1 hour
+    maxEntries: 1000
+```

package/docs/guide/deployment.md

@@ -0,0 +1,42 @@
+# Deployment
+
+## Docker
+
+Every `opc init` project includes a `Dockerfile` and `docker-compose.yml`:
+
+```bash
+docker compose up -d
+```
+
+## Deploy to OpenClaw
+
+```bash
+opc deploy --target openclaw
+opc deploy --target openclaw --install  # Also register in config
+```
+
+## Deploy to Hermes
+
+```bash
+opc deploy --target hermes
+opc deploy --target hermes --output ./my-hermes-deploy
+```
+
+## Environment Variables
+
+Set your API keys in `.env`:
+
+```bash
+OPC_LLM_API_KEY=sk-xxx
+OPC_LLM_BASE_URL=https://api.openai.com/v1
+OPC_LLM_MODEL=gpt-4o-mini
+```
+
+## Production Checklist
+
+- [ ] Set proper API keys in `.env`
+- [ ] Configure rate limits in `oad.yaml`
+- [ ] Enable caching for cost reduction
+- [ ] Set up analytics monitoring
+- [ ] Run `opc test` before deployment
+- [ ] Review trust/DTV settings

package/docs/guide/testing.md

@@ -0,0 +1,84 @@
+# Testing
+
+## Overview
+
+OPC Agent includes a built-in testing framework. Define test cases in your `oad.yaml` or a separate `tests.yaml` file, then run them with `opc test`.
+
+## Defining Tests in OAD
+
+```yaml
+spec:
+  testing:
+    cases:
+      - name: greeting
+        input: "Hello!"
+        expect:
+          contains: ["hello", "help"]
+          maxLatencyMs: 5000
+      
+      - name: product-question
+        input: "What are your pricing plans?"
+        expect:
+          contains: ["pricing", "plan"]
+          notContains: ["error"]
+      
+      - name: edge-case-empty
+        input: ""
+        expect:
+          maxLatencyMs: 2000
+```
+
+## Separate Test File
+
+Create `tests.yaml` alongside your `oad.yaml`:
+
+```yaml
+cases:
+  - name: smoke-test
+    input: "Hi there"
+    expect:
+      maxLatencyMs: 10000
+  - name: faq-check
+    input: "What is your return policy?"
+    expect:
+      contains: ["return", "refund"]
+```
+
+## Running Tests
+
+```bash
+# Run tests
+opc test
+
+# JSON output
+opc test --json
+
+# Custom OAD file
+opc test -f my-agent.yaml
+```
+
+## Test Report
+
+```
+═══════════════════════════════════════════
+  OPC Agent Test Report
+═══════════════════════════════════════════
+
+  ✔ [PASS] greeting (245ms)
+  ✔ [PASS] product-question (312ms)
+  ✘ [FAIL] edge-case (5120ms)
+      → Latency 5120ms exceeded max 2000ms
+
+───────────────────────────────────────────
+  Total: 3  Passed: 2  Failed: 1  Duration: 5677ms
+───────────────────────────────────────────
+```
+
+## Assertions
+
+| Assertion | Description |
+|-----------|-------------|
+| `contains` | Response must include these strings (case-insensitive) |
+| `notContains` | Response must NOT include these strings |
+| `toolCalled` | Specified tools must have been invoked |
+| `maxLatencyMs` | Response must complete within this time |

package/docs/index.md

@@ -0,0 +1,27 @@
+---
+layout: home
+hero:
+  name: OPC Agent
+  text: Open Agent Framework
+  tagline: Build, test, and run AI Agents for business workstations
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/Deepleaper/opc-agent
+features:
+  - title: 🚀 Quick Start
+    details: Create an agent in under 2 minutes with 13 built-in templates
+  - title: 📝 OAD Schema
+    details: Declarative YAML-based agent definition with full validation
+  - title: 🔌 Multi-Channel
+    details: Web, Telegram, Slack, WeChat, Email, Voice, WebSocket
+  - title: 🧪 Testing Framework
+    details: Define test cases in OAD, run with `opc test`, get pass/fail reports
+  - title: 📊 Analytics
+    details: Track messages, LLM calls, tool usage, and errors with built-in analytics
+  - title: 🌍 i18n
+    details: English, Chinese, and Japanese out of the box
+---

package/docs/zh/api/oad-schema.md

@@ -0,0 +1,3 @@
+# OAD Schema
+
+详细说明请参考 [英文版](/api/oad-schema)。

package/docs/zh/guide/concepts.md

@@ -0,0 +1,28 @@
+# 核心概念
+
+## OAD（Open Agent Definition）
+
+OAD 是智能体的声明式定义文件，使用 YAML 格式。包含：
+
+- **metadata** — 名称、版本、描述
+- **spec** — 模型、系统提示词、技能、渠道、记忆、DTV
+
+## 技能（Skills）
+
+技能是智能体的能力模块，每个技能处理特定类型的用户请求。
+
+## 渠道（Channels）
+
+渠道定义智能体与用户交互的方式：Web、Telegram、Slack、微信等。
+
+## DTV（Data-Trust-Value）
+
+DTV 框架确保智能体的数据安全、信任级别和价值追踪。
+
+## 测试
+
+在 OAD 中定义测试用例，使用 `opc test` 运行自动化测试。
+
+## 缓存与限流
+
+内置 LLM 响应缓存和多级限流，降低 API 成本，保护服务稳定性。