opc-agent 4.1.1 → 4.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opc-agent",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,20 +0,0 @@
----
-name: Bug Report
-about: Report a bug
-labels: bug
----
-
-**Describe the bug**
-A clear description of the bug.
-
-**To Reproduce**
-Steps to reproduce:
-1. ...
-
-**Expected behavior**
-What you expected to happen.
-
-**Environment**
-- OS: 
-- Node.js: 
-- Package version: 

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,14 +0,0 @@
----
-name: Feature Request
-about: Suggest a new feature
-labels: enhancement
----
-
-**Problem**
-What problem does this solve?
-
-**Proposed Solution**
-How should it work?
-
-**Alternatives Considered**
-Any other approaches?

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,13 +0,0 @@
-## What
-Brief description of changes.
-
-## Why
-Why is this change needed?
-
-## How
-How was this implemented?
-
-## Checklist
-- [ ] Tests pass
-- [ ] Documentation updated (if needed)
-- [ ] No breaking changes (or documented)

package/.github/workflows/ci.yml

@@ -1,24 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm run build --if-present
-      - run: npx vitest run --reporter=verbose
-        env:
-          CI: true

package/docs/.vitepress/config.ts

@@ -1,103 +0,0 @@
-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',
-      description: '开放智能体框架 — 构建、测试、运行企业级 AI 智能体',
-      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' },
-              ],
-            },
-          ],
-          '/zh/api/': [
-            {
-              text: '参考',
-              items: [
-                { text: 'OAD Schema', link: '/zh/api/oad-schema' },
-                { text: 'CLI 命令', link: '/zh/api/cli' },
-                { text: 'SDK', link: '/zh/api/sdk' },
-              ],
-            },
-          ],
-        },
-      },
-    },
-  },
-
-  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

@@ -1,48 +0,0 @@
-# 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/oad-schema.md

@@ -1,64 +0,0 @@
-# OAD Schema v1 Specification
-
-**OAD** (Open Agent Definition) is a declarative YAML/JSON format for defining AI agents.
-
-## Full Schema
-
-```yaml
-apiVersion: opc/v1          # Required. Must be "opc/v1"
-kind: Agent                  # Required. Must be "Agent"
-
-metadata:
-  name: string               # Required. Agent identifier
-  version: string            # Semver. Default: "1.0.0"
-  description: string        # Optional. Human-readable description
-  author: string             # Optional. Author name
-  license: string            # Default: "Apache-2.0"
-  marketplace:               # Optional. Marketplace settings
-    certified: boolean       # Default: false
-    category: string         # e.g., "customer-service"
-
-spec:
-  provider:                  # LLM provider configuration
-    default: string          # Default provider. Default: "deepseek"
-    allowed: string[]        # Allowed providers. Default: ["openai", "deepseek", "qwen"]
-  model: string              # Model name. Default: "deepseek-chat"
-  systemPrompt: string       # System prompt for the agent
-
-  skills:                    # List of skills
-    - name: string           # Skill identifier
-      description: string    # What the skill does
-      config: object         # Optional skill-specific config
-
-  channels:                  # Communication channels
-    - type: web|websocket|cli
-      port: number           # Port for web channels
-      config: object         # Optional channel config
-
-  memory:
-    shortTerm: boolean       # Enable conversation memory. Default: true
-    longTerm: boolean        # Enable persistent memory. Default: false
-    provider: string         # Memory backend (optional)
-
-  dtv:
-    trust:
-      level: sandbox|verified|certified|listed  # Default: "sandbox"
-    value:
-      metrics: string[]      # Metrics to track. Default: []
-```
-
-## Validation
-
-OAD files are validated using Zod schemas. Use the CLI to validate:
-
-```bash
-opc build -f oad.yaml
-```
-
-Or programmatically:
-
-```typescript
-import { validateOAD } from 'opc-agent';
-
-const config = validateOAD(yamlData);
-```

package/docs/api/sdk.md

@@ -1,80 +0,0 @@
-# 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/concepts.md

@@ -1,51 +0,0 @@
-# Core Concepts
-
-## Agent
-
-An Agent is an autonomous AI entity with a defined lifecycle:
-
-```
-init → ready → running → stopped
-```
-
-Each agent has a name, system prompt, skills, channels, and memory.
-
-## Skill
-
-Skills are modular capabilities an agent can use. Each skill:
-- Has a `name` and `description`
-- Receives the conversation context and current message
-- Returns whether it handled the message and with what confidence
-
-Built-in skills include FAQ lookup and human handoff.
-
-## Channel
-
-Channels are the interfaces through which users interact with agents:
-- **Web** — HTTP API with `/chat` endpoint and SSE streaming
-- More channels (WebSocket, CLI, Slack) coming soon
-
-## Memory
-
-Agents have two types of memory:
-- **Short-term** — Conversation history within a session
-- **Long-term** — Persistent knowledge across sessions (coming soon)
-
-## DTV (Data / Trust / Value)
-
-The DTV framework governs agent operations:
-
-### Data
-Read-only access to business data. Agents can read configurations but cannot modify source systems.
-
-### Trust
-Progressive trust levels control agent capabilities:
-- **sandbox** — No network, limited capabilities
-- **verified** — Identity confirmed, basic capabilities
-- **certified** — Security audited, full capabilities
-- **listed** — Published in OPC marketplace
-
-### Value
-Metrics tracking for agent performance and ROI:
-- Response time, satisfaction scores, resolution rates
-- Automated reporting and dashboards

package/docs/guide/configuration.md

@@ -1,79 +0,0 @@
-# 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

@@ -1,42 +0,0 @@
-# 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/getting-started.md

@@ -1,44 +0,0 @@
-# Getting Started
-
-## Installation
-
-```bash
-npm install -g opc-agent
-```
-
-## Create Your First Agent
-
-```bash
-# Initialize a new project
-opc init my-agent --template customer-service
-
-# Enter the project
-cd my-agent
-
-# Validate the OAD definition
-opc build
-
-# Run in sandbox mode
-opc test
-
-# Start the agent
-opc run
-```
-
-## Test the Agent
-
-```bash
-curl -X POST http://localhost:3000/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message": "What are your business hours?"}'
-```
-
-## Project Structure
-
-```
-my-agent/
-├── oad.yaml       # Agent definition (OAD Schema v1)
-└── README.md
-```
-
-The `oad.yaml` file defines everything about your agent: its identity, skills, channels, and configuration.

package/docs/guide/templates.md

@@ -1,28 +0,0 @@
-# Templates
-
-Templates are pre-built agent configurations for common use cases.
-
-## Customer Service
-
-A complete customer service agent with:
-- FAQ lookup skill
-- Human handoff when confidence is low
-- Web channel for HTTP integration
-
-```bash
-opc init my-service --template customer-service
-```
-
-## Creating Custom Templates
-
-Templates are OAD YAML files with optional skill implementations. To create your own:
-
-1. Define `oad.yaml` with your agent specification
-2. Implement custom skills extending `BaseSkill`
-3. Package as a directory with `oad.yaml` + `README.md`
-
-More templates coming soon:
-- Sales Assistant
-- Internal IT Help Desk
-- Data Analysis Agent
-- Content Moderation Agent