opc-agent 0.7.0 → 0.9.0

package/dist/tools/text-analysis.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextAnalysisTool = void 0;
+/**
+ * Text Analysis Tool — v0.8.0
+ * Summarize, translate (stub), sentiment analysis as an LLM function tool.
+ * Note: For production, connect to actual LLM/NLP APIs. This provides basic built-in analysis.
+ */
+exports.TextAnalysisTool = {
+    name: 'text_analysis',
+    description: 'Analyze text: word count, character count, reading time, keyword extraction, basic sentiment, and language detection.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['stats', 'keywords', 'sentiment', 'detect_language', 'truncate', 'split_sentences'],
+                description: 'Analysis operation to perform',
+            },
+            text: {
+                type: 'string',
+                description: 'Text to analyze',
+            },
+            maxLength: {
+                type: 'number',
+                description: 'Max length for truncate operation',
+            },
+            topN: {
+                type: 'number',
+                description: 'Number of top keywords to extract (default: 10)',
+            },
+        },
+        required: ['operation', 'text'],
+    },
+    async execute(input) {
+        try {
+            const op = String(input.operation);
+            const text = String(input.text ?? '');
+            switch (op) {
+                case 'stats': {
+                    const words = text.split(/\s+/).filter(Boolean);
+                    const sentences = text.split(/[.!?。！？]+/).filter(Boolean);
+                    const readingTimeMin = Math.ceil(words.length / 200);
+                    return {
+                        content: JSON.stringify({
+                            characters: text.length,
+                            words: words.length,
+                            sentences: sentences.length,
+                            paragraphs: text.split(/\n\s*\n/).filter(Boolean).length,
+                            readingTimeMinutes: readingTimeMin,
+                        }, null, 2),
+                    };
+                }
+                case 'keywords': {
+                    const topN = Number(input.topN ?? 10);
+                    const words = text.toLowerCase().replace(/[^\w\s\u4e00-\u9fff]/g, '').split(/\s+/).filter(Boolean);
+                    const stopWords = new Set(['the', 'a', 'an', 'is', 'are', 'was', 'were', 'in', 'on', 'at', 'to', 'for', 'of', 'and', 'or', 'but', 'not', 'with', 'this', 'that', 'it', 'be', 'has', 'have', 'had', 'do', 'does', 'did', 'will', 'would', 'can', 'could', 'should', 'may', 'might', 'from', 'by', 'as', 'if', 'so', 'than']);
+                    const freq = {};
+                    for (const w of words) {
+                        if (w.length < 2 || stopWords.has(w))
+                            continue;
+                        freq[w] = (freq[w] ?? 0) + 1;
+                    }
+                    const sorted = Object.entries(freq).sort((a, b) => b[1] - a[1]).slice(0, topN);
+                    return { content: JSON.stringify(sorted.map(([word, count]) => ({ word, count })), null, 2) };
+                }
+                case 'sentiment': {
+                    // Basic lexicon-based sentiment
+                    const positiveWords = new Set(['good', 'great', 'excellent', 'amazing', 'wonderful', 'fantastic', 'love', 'happy', 'best', 'awesome', 'perfect', 'brilliant', 'outstanding', 'superb', 'beautiful', 'nice', 'enjoy', 'like', 'positive', 'success']);
+                    const negativeWords = new Set(['bad', 'terrible', 'awful', 'horrible', 'hate', 'worst', 'poor', 'ugly', 'fail', 'wrong', 'sad', 'angry', 'frustrating', 'disappointing', 'negative', 'annoying', 'broken', 'useless', 'boring', 'painful']);
+                    const words = text.toLowerCase().split(/\s+/);
+                    let pos = 0, neg = 0;
+                    for (const w of words) {
+                        if (positiveWords.has(w))
+                            pos++;
+                        if (negativeWords.has(w))
+                            neg++;
+                    }
+                    const total = pos + neg || 1;
+                    const score = (pos - neg) / total; // -1 to 1
+                    const label = score > 0.1 ? 'positive' : score < -0.1 ? 'negative' : 'neutral';
+                    return {
+                        content: JSON.stringify({ score: Math.round(score * 100) / 100, label, positive: pos, negative: neg }, null, 2),
+                    };
+                }
+                case 'detect_language': {
+                    // Simple heuristic
+                    const hasChinese = /[\u4e00-\u9fff]/.test(text);
+                    const hasJapanese = /[\u3040-\u309f\u30a0-\u30ff]/.test(text);
+                    const hasKorean = /[\uac00-\ud7af]/.test(text);
+                    const hasArabic = /[\u0600-\u06ff]/.test(text);
+                    const lang = hasChinese ? 'zh' : hasJapanese ? 'ja' : hasKorean ? 'ko' : hasArabic ? 'ar' : 'en';
+                    return { content: JSON.stringify({ detected: lang, confidence: 'heuristic' }) };
+                }
+                case 'truncate': {
+                    const maxLen = Number(input.maxLength ?? 100);
+                    const truncated = text.length > maxLen ? text.slice(0, maxLen) + '...' : text;
+                    return { content: truncated };
+                }
+                case 'split_sentences': {
+                    const sentences = text.match(/[^.!?。！？]+[.!?。！？]+/g) ?? [text];
+                    return { content: JSON.stringify(sentences.map((s) => s.trim()), null, 2) };
+                }
+                default:
+                    return { content: `Unknown operation: ${op}`, isError: true };
+            }
+        }
+        catch (err) {
+            return { content: `Error: ${err.message}`, isError: true };
+        }
+    },
+};
+//# sourceMappingURL=text-analysis.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 成本，保护服务稳定性。

package/docs/zh/guide/configuration.md

@@ -0,0 +1,39 @@
+# 配置
+
+详细配置说明请参考 [英文版](/guide/configuration)。
+
+## 限流配置
+
+```yaml
+spec:
+  rateLimits:
+    perUser:
+      maxRequests: 60
+      windowMs: 60000
+    perProvider:
+      maxRequests: 100
+      windowMs: 60000
+```
+
+## 缓存配置
+
+```yaml
+spec:
+  cache:
+    enabled: true
+    ttlMs: 3600000
+    maxEntries: 1000
+```
+
+## 测试配置
+
+```yaml
+spec:
+  testing:
+    cases:
+      - name: 问候测试
+        input: "你好"
+        expect:
+          contains: ["你好", "帮"]
+          maxLatencyMs: 5000
+```

package/docs/zh/guide/deployment.md

@@ -0,0 +1,3 @@
+# 部署
+
+详细说明请参考 [英文版](/guide/deployment)。