opc-agent 4.1.2 → 4.1.4

package/models.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://raw.githubusercontent.com/Deepleaper/opc-agent/main/models.schema.json",
+  "version": "2026-04-20",
+  "lastUpdated": "2026-04-20T12:37:00+08:00",
+  "nextReview": "2026-05-20",
+  "models": [
+    {
+      "name": "qwen2.5:0.5b",
+      "size": "0.4GB",
+      "minRAM": 2,
+      "desc": "超轻量，适合低配机器",
+      "descEn": "Ultra-light, for low-end machines",
+      "tier": 1,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "fast"
+    },
+    {
+      "name": "qwen2.5:1.5b",
+      "size": "1.0GB",
+      "minRAM": 4,
+      "desc": "轻量但更智能",
+      "descEn": "Light but smarter",
+      "tier": 1,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "fast"
+    },
+    {
+      "name": "qwen2.5:3b",
+      "size": "2.0GB",
+      "minRAM": 6,
+      "desc": "性价比最优",
+      "descEn": "Best value for size",
+      "tier": 2,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "fast"
+    },
+    {
+      "name": "llama3.2:3b",
+      "size": "2.0GB",
+      "minRAM": 6,
+      "desc": "Meta 最新轻量模型",
+      "descEn": "Meta's latest lightweight model",
+      "tier": 2,
+      "lang": ["en"],
+      "useCase": ["general"],
+      "speed": "fast"
+    },
+    {
+      "name": "phi3:mini",
+      "size": "2.3GB",
+      "minRAM": 6,
+      "desc": "微软高效小模型",
+      "descEn": "Microsoft efficient small model",
+      "tier": 2,
+      "lang": ["en"],
+      "useCase": ["general", "code"],
+      "speed": "fast"
+    },
+    {
+      "name": "qwen2.5:7b",
+      "size": "4.7GB",
+      "minRAM": 8,
+      "desc": "推荐：中文最强 7B",
+      "descEn": "Recommended: Best Chinese 7B",
+      "tier": 3,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "medium",
+      "recommended": true
+    },
+    {
+      "name": "llama3.1:8b",
+      "size": "4.7GB",
+      "minRAM": 8,
+      "desc": "Meta 通用 8B",
+      "descEn": "Meta general purpose 8B",
+      "tier": 3,
+      "lang": ["en"],
+      "useCase": ["general"],
+      "speed": "medium"
+    },
+    {
+      "name": "mistral:7b",
+      "size": "4.1GB",
+      "minRAM": 8,
+      "desc": "Mistral 经典 7B",
+      "descEn": "Mistral classic 7B",
+      "tier": 3,
+      "lang": ["en", "fr"],
+      "useCase": ["general"],
+      "speed": "medium"
+    },
+    {
+      "name": "gemma2:9b",
+      "size": "5.4GB",
+      "minRAM": 10,
+      "desc": "Google 高效 9B",
+      "descEn": "Google efficient 9B",
+      "tier": 3,
+      "lang": ["en"],
+      "useCase": ["general"],
+      "speed": "medium"
+    },
+    {
+      "name": "qwen2.5-coder:7b",
+      "size": "4.7GB",
+      "minRAM": 8,
+      "desc": "编程专用 7B，代码补全强",
+      "descEn": "Code-specialized 7B",
+      "tier": 3,
+      "lang": ["zh", "en"],
+      "useCase": ["code"],
+      "speed": "medium"
+    },
+    {
+      "name": "qwen2.5:14b",
+      "size": "9.0GB",
+      "minRAM": 16,
+      "desc": "中文强力 14B",
+      "descEn": "Strong Chinese 14B",
+      "tier": 4,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "slow"
+    },
+    {
+      "name": "deepseek-coder-v2:16b",
+      "size": "9.0GB",
+      "minRAM": 16,
+      "desc": "编程专用 16B",
+      "descEn": "Code-specialized 16B",
+      "tier": 4,
+      "lang": ["zh", "en"],
+      "useCase": ["code"],
+      "speed": "slow"
+    },
+    {
+      "name": "qwen2.5:32b",
+      "size": "20GB",
+      "minRAM": 32,
+      "desc": "接近 GPT-4 水平",
+      "descEn": "Near GPT-4 level",
+      "tier": 5,
+      "lang": ["zh", "en"],
+      "useCase": ["general"],
+      "speed": "slow",
+      "recommended": true
+    },
+    {
+      "name": "llama3.1:70b",
+      "size": "40GB",
+      "minRAM": 64,
+      "desc": "开源最强",
+      "descEn": "Best open-source model",
+      "tier": 6,
+      "lang": ["en"],
+      "useCase": ["general"],
+      "speed": "very-slow"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opc-agent",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "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/USABILITY-ISSUES.md

@@ -1,73 +0,0 @@
-# OPC Agent 易用性问题清单
-
-日期: 2026-04-20
-目标: 易用性超过 OpenClaw 和 DeerFlow
-
-## 🔴 Critical (新用户第一次就遇到)
-
-### C1: .env 和 oad.yaml 配置矛盾
-- .env 设了 `OPC_LLM_BASE_URL=https://api.openai.com/v1` 和 `OPC_LLM_MODEL=gpt-4o-mini`
-- 但 oad.yaml 里 `provider: deepseek`, `model: deepseek-chat`
-- 新用户困惑：到底听谁的？
-- **修复**: init 时让用户选 provider，.env 和 oad.yaml 统一生成
-
-### C2: .env 占位符 API key 导致 401
-- 默认 `OPC_LLM_API_KEY=your-api-key-here` 导致第一次对话直接 401
-- 用户看到 "Incorrect API key" 错误，不知道怎么修
-- **修复**: init 时提示输入 API key 或选择 Ollama(免费本地)
-- 如果没配 key，chat 应该给友好提示而不是 raw 401 JSON
-
-### C3: agent.yaml vs oad.yaml 双配置文件
-- init 生成了 agent.yaml 和 oad.yaml 两个文件
-- doctor 检查 agent.yaml 但 runtime 读 oad.yaml
-- **修复**: 统一用一个文件
-
-## 🟡 Important (影响体验但不致命)
-
-### I1: opc doctor 误报
-- "agent.yaml exists: Not found" — 但实际有 oad.yaml
-- "TypeScript installed: Not found" — 但 npx tsx 能跑
-- "Ollama running: Not running" — 不是所有用户都用 Ollama
-- "DeepBrain package: Not installed" — 但 opc-agent 自带内存 fallback
-- **修复**: doctor 应该检查 oad.yaml，对非必须项给 warning 不给 ❌
-
-### I2: Chat 401 错误消息不友好
-- 返回 raw SSE `data: {"error":"LLM API error 401: {...}"}` 
-- Web UI 应该显示 "请先配置 API Key" + 指引
-- **修复**: 前端拦截 401，显示配置指引
-
-### I3: Studio /api/dashboard 404
-- Dashboard API 不存在
-- **修复**: 实现或移除 dashboard 入口
-
-### I4: DeepBrain fallback 无声失败
-- 日志显示 `[DeepBrainMemory] deepbrain package not found, using in-memory fallback`
-- 用户不知道记忆没有持久化
-- **修复**: 首次运行时提示，或默认用文件存储
-
-### I5: 没有一键安装脚本
-- OpenClaw 有 `curl | sh` 一键安装
-- 我们需要 `npm install -g opc-agent`，还要自己装 Node
-- **修复**: 做一个安装脚本，检测 OS、装 Node、装 opc-agent
-
-## 🟢 Nice-to-have
-
-### N1: 没有 `opc quickstart` 命令
-- OpenClaw 五分钟上手，我们还是多步手动流程
-- **修复**: 做一个交互式 quickstart，一步到位
-
-### N2: init 模板缺少 Ollama 选项
-- 很多用户想用免费本地模型
-- **修复**: init 时加 Ollama 选项，自动配 ollama provider
-
-### N3: README.md 内容单薄
-- 缺少截图、GIF、快速上手步骤
-- **修复**: 丰富 README
-
-### N4: Studio agent 数据来自旧缓存
-- API 返回 "name: Updated Bot" 而不是 "my-first-agent"
-- **修复**: 确保从 oad.yaml 实时读取
-
-### N5: cron-engine 默认 9 个任务
-- 新建的 agent 不应该有预设的 cron 任务
-- **修复**: 新 agent 默认 0 个 cron 任务

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