opc-agent 4.1.2 → 4.1.3

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

package/docs/guide/testing.md

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

@@ -1,27 +0,0 @@
----
-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/cli.md

@@ -1,54 +0,0 @@
-# CLI 命令参考
-
-## 完整命令列表
-
-| 命令 | 说明 |
-|------|------|
-| `opc init [name]` | 创建新智能体项目（交互式） |
-| `opc create <name>` | 从模板快速创建 |
-| `opc run` | 启动智能体（Web 服务） |
-| `opc chat` | 命令行交互对话 |
-| `opc test` | 运行测试用例 |
-| `opc analytics` | 查看使用分析 |
-| `opc info` | 查看智能体信息 |
-| `opc build` | 校验 OAD 配置 |
-| `opc dev` | 热重载开发模式 |
-| `opc deploy` | 部署智能体 |
-| `opc publish` | 发布到市场 |
-| `opc install <source>` | 从包安装智能体 |
-| `opc search <query>` | 搜索 OPC 市场 |
-| `opc stats` | 查看运行时统计 |
-| `opc kb add <file>` | 添加知识库文件 |
-| `opc kb search <query>` | 搜索知识库 |
-| `opc tool list` | 列出 MCP 工具 |
-| `opc workflow run <name>` | 运行工作流 |
-| `opc version-mgmt list` | 列出保存的版本 |
-
-## 通用选项
-
-- `-f, --file <file>` — OAD 文件路径（默认：`oad.yaml`）
-- `-t, --template <name>` — 模板名称
-- `-p, --port <port>` — 端口覆盖
-- `--json` — JSON 格式输出（用于 test/analytics）
-
-## 常用示例
-
-```bash
-# 用模板创建项目
-opc init my-bot -t teacher
-
-# 运行测试，输出 JSON
-opc test --json
-
-# 查看分析数据
-opc analytics
-
-# 部署到 OpenClaw
-opc deploy --target openclaw --install
-
-# 添加文件到知识库
-opc kb add ./docs/product-manual.pdf
-
-# 搜索知识库
-opc kb search "退货政策"
-```

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

@@ -1,87 +0,0 @@
-# OAD Schema v1 规范
-
-**OAD**（Open Agent Definition）是智能体的声明式定义格式，支持 YAML 和 JSON。
-
-## 完整 Schema
-
-```yaml
-apiVersion: opc/v1          # 必填。API 版本，目前固定为 "opc/v1"
-kind: Agent                  # 必填。资源类型，目前固定为 "Agent"
-
-metadata:
-  name: string               # 必填。智能体标识名
-  version: string            # 语义版本号，默认 "1.0.0"
-  description: string        # 可选。人类可读的描述
-  author: string             # 可选。作者
-  license: string            # 默认 "Apache-2.0"
-  marketplace:               # 可选。市场配置
-    certified: boolean       # 默认 false
-    category: string         # 如 "customer-service"
-
-spec:
-  provider:                  # 大语言模型供应商
-    default: string          # 默认供应商，默认 "deepseek"
-    allowed: string[]        # 允许的供应商列表，默认 ["openai", "deepseek", "qwen"]
-  model: string              # 模型名称，默认 "deepseek-chat"
-  systemPrompt: string       # 系统提示词
-
-  skills:                    # 技能列表
-    - name: string           # 技能标识
-      description: string    # 技能说明
-      config: object         # 可选。技能配置
-
-  channels:                  # 通信渠道
-    - type: web|websocket|telegram|slack|wechat|feishu|email|voice|webhook
-      port: number           # Web 渠道的端口
-      config: object         # 可选。渠道配置
-
-  memory:
-    shortTerm: boolean       # 开启对话记忆，默认 true
-    longTerm: boolean        # 开启持久化记忆，默认 false
-    provider: string         # 记忆后端（可选）
-
-  testing:
-    cases:                   # 测试用例
-      - name: string
-        input: string
-        expect:
-          contains: string[]
-          notContains: string[]
-          toolCalled: string[]
-          maxLatencyMs: number
-
-  rateLimits:
-    perUser:
-      maxRequests: number
-      windowMs: number
-    perProvider:
-      maxRequests: number
-      windowMs: number
-
-  cache:
-    enabled: boolean
-    ttlMs: number
-    maxEntries: number
-
-  dtv:
-    trust:
-      level: sandbox|verified|certified|listed  # 默认 "sandbox"
-    value:
-      metrics: string[]      # 要追踪的指标，默认 []
-```
-
-## 校验
-
-OAD 文件使用 Zod schema 校验。用 CLI 校验：
-
-```bash
-opc build -f oad.yaml
-```
-
-或在代码中校验：
-
-```typescript
-import { validateOAD } from 'opc-agent';
-
-const config = validateOAD(yamlData);
-```

package/docs/zh/api/sdk.md

@@ -1,102 +0,0 @@
-# SDK 参考
-
-## 核心类
-
-### AgentRuntime — 智能体运行时
-
-```typescript
-import { AgentRuntime } from 'opc-agent';
-
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');   // 加载 OAD 配置
-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 — LLM 响应缓存
-
-```typescript
-import { LLMCache } from 'opc-agent';
-
-const cache = new LLMCache({ ttlMs: 3600000 }); // 1 小时过期
-const key = LLMCache.makeKey(messages, systemPrompt);
-const cached = cache.get(key);
-if (!cached) {
-  const response = await callLLM(messages);
-  cache.set(key, response);
-}
-```
-
-### KnowledgeBase — 知识库
-
-```typescript
-import { KnowledgeBase } from 'opc-agent';
-
-const kb = new KnowledgeBase('./docs');
-await kb.addFile('产品手册.pdf');    // 添加文件
-await kb.addFile('FAQ.md');
-const results = await kb.search('退货政策'); // 语义搜索
-```
-
-### Orchestrator — 多智能体编排
-
-```typescript
-import { Orchestrator } from 'opc-agent';
-
-const orchestrator = new Orchestrator({
-  agents: [triageAgent, salesAgent, supportAgent],
-  strategy: 'route-by-intent', // 按意图路由
-});
-
-const response = await orchestrator.handle(message);
-```
-
-### Testing — 测试工具
-
-```typescript
-import { runTests, formatReport } from 'opc-agent';
-
-const report = await runTests('oad.yaml');
-console.log(formatReport(report));
-```
-
-## 模板列表
-
-| 模板 | 说明 |
-|------|------|
-| `customer-service` | 客服：FAQ + 人工转接 |
-| `sales-assistant` | 销售：产品问答 + 线索捕获 |
-| `knowledge-base` | 知识库：RAG 语义检索 |
-| `code-reviewer` | 代码审查：Bug 检测 + 风格检查 |
-| `hr-recruiter` | HR：简历筛选 + 面试 |
-| `project-manager` | 项目管理：任务 + 会议纪要 |
-| `content-writer` | 内容创作：博客 + 社媒 + SEO |
-| `legal-assistant` | 法务：合同审查 + 合规 |
-| `financial-advisor` | 财务：预算 + 支出 |
-| `executive-assistant` | 行政：日程 + 邮件 + 会议 |
-| `data-analyst` | 数据分析：查询 + 可视化 |
-| `teacher` | 教学：课程 + 出题 |

package/docs/zh/guide/concepts.md

@@ -1,104 +0,0 @@
-# 核心概念
-
-## 智能体 (Agent)
-
-智能体是一个有完整生命周期的 AI 实体：
-
-```
-初始化 (init) → 就绪 (ready) → 运行中 (running) → 已停止 (stopped)
-```
-
-每个智能体有以下属性：
-- **名称** — 唯一标识符
-- **系统提示词** — 定义智能体的角色和行为
-- **技能** — 智能体能做的事（如 FAQ 查询、转人工）
-- **渠道** — 用户和智能体交互的方式（如 Web、Telegram）
-- **记忆** — 对话历史和长期知识
-
-## OAD (Open Agent Definition)
-
-OAD 是智能体的声明式定义格式，用 YAML 编写。一个 OAD 文件就是一个完整的智能体定义。
-
-```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: my-agent
-  version: 1.0.0
-spec:
-  provider:
-    default: deepseek
-  model: deepseek-chat
-  systemPrompt: "你是一个专业的客服助手。"
-  skills: [...]
-  channels: [...]
-```
-
-这个设计理念参考了 Kubernetes 的资源定义：声明你想要的状态，框架帮你实现。
-
-## 技能 (Skill)
-
-技能是智能体的模块化能力。每个技能：
-- 有 `name` 和 `description`
-- 接收对话上下文和当前消息
-- 返回是否处理了这条消息，以及置信度
-
-内置技能包括：
-- **FAQ 查询** — 从预设问答库匹配答案
-- **人工转接** — 置信度低时转给人工客服
-- **知识库检索** — 从文档中语义搜索相关内容
-
-你也可以继承 `BaseSkill` 实现自定义技能。
-
-## 渠道 (Channel)
-
-渠道是用户和智能体交互的接口：
-
-| 渠道 | 说明 |
-|------|------|
-| **Web** | HTTP API + SSE 流式响应，自带对话 UI |
-| **WebSocket** | 实时双向通信 + 广播 |
-| **Telegram** | Telegram Bot API Webhook |
-| **Slack** | Slack 应用集成 |
-| **微信** | 微信公众号消息处理 |
-| **飞书** | 飞书机器人 |
-| **邮件** | 邮件收发 |
-| **语音** | 语音识别（STT）+ 语音合成（TTS） |
-| **Webhook** | 接收外部系统回调 |
-
-## 记忆 (Memory)
-
-智能体有两种记忆：
-
-- **短期记忆** — 单次会话内的对话历史，会话结束即清除
-- **长期记忆** — 跨会话的持久化知识，支持 DeepBrain 语义搜索
-
-```yaml
-spec:
-  memory:
-    shortTerm: true       # 开启对话上下文
-    longTerm: true        # 开启长期记忆
-    provider: deepbrain   # 长期记忆后端
-```
-
-## DTV 框架 (Data / Trust / Value)
-
-DTV 框架管理智能体的数据访问、信任等级和价值度量：
-
-### 数据 (Data)
-智能体对业务数据的只读访问。可以读取配置，但不能修改源系统。
-
-### 信任 (Trust)
-渐进式信任等级控制智能体的能力范围：
-
-| 等级 | 说明 |
-|------|------|
-| `sandbox` | 沙箱模式，无网络访问，能力受限 |
-| `verified` | 身份已验证，基础能力 |
-| `certified` | 通过安全审计，完整能力 |
-| `listed` | 已发布到 OPC 市场 |
-
-### 价值 (Value)
-性能和 ROI 指标追踪：
-- 响应时间、满意度评分、解决率
-- 自动化报表和仪表盘