opc-agent 1.2.1 → 1.3.0

package/README.md

@@ -1,429 +1,306 @@
-<p align="center">
-  <h1 align="center">🤖 OPC Agent</h1>
-  <p align="center"><strong>开放智能体框架 — 构建、测试、运行企业级 AI 智能体</strong></p>
-  <p align="center">
-    <a href="https://www.npmjs.com/package/opc-agent"><img src="https://img.shields.io/npm/v/opc-agent?color=blue" alt="npm"></a>
-    <a href="https://github.com/Deepleaper/opc-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="license"></a>
-    <img src="https://img.shields.io/badge/tests-146%20passed-brightgreen" alt="146 tests passing">
-    <a href="https://www.npmjs.com/package/opc-agent"><img src="https://img.shields.io/npm/dm/opc-agent?color=orange" alt="downloads"></a>
-  </p>
-  <p align="center">
-    <strong>🇨🇳 中文</strong> · <a href="#english">🇺🇸 English</a>
-  </p>
-</p>
+<div align="center">
 
----
-
-OPC Agent 是一个 **TypeScript 优先的开放智能体框架**，由 [跃盟科技 (Deepleaper)](https://www.deepleaper.com) 开发。用一个 YAML 文件（OAD）定义智能体，接入任意大语言模型，一键部署到多个渠道。
-
-## ⚡ 快速开始（30 秒）
-
-```bash
-npm install -g opc-agent
-opc init my-agent
-cd my-agent
-opc run
-```
+# 🤖 OPC Agent
 
-访问 `http://localhost:3000`，内置 Web 对话界面即刻可用。
+**Agent OS — AI Agent 全生命周期操作系统**
 
-## ✨ 功能特性
+[![npm](https://img.shields.io/npm/v/opc-agent)](https://www.npmjs.com/package/opc-agent)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/Tests-163_passing-green)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
-### 🔌 多模型供应商
+[快速开始](#快速开始) · [CLI 命令](#cli-命令) · [渠道](#11-个渠道) · [English](#english)
 
-```yaml
-spec:
-  provider:
-    default: deepseek
-    allowed: [openai, deepseek, qwen, anthropic, ollama]
-  model: deepseek-chat
-```
-
-支持 **DeepSeek**、**通义千问 (Qwen)**、**OpenAI**、**Anthropic**、**Ollama**（本地），以及任何兼容 OpenAI 接口的服务。
+</div>
 
-### 📡 11 个渠道，一套代码
+---
 
-```yaml
-spec:
-  channels:
-    - type: web        # Web 对话界面（内置 UI）
-      port: 3000
-    - type: telegram   # Telegram 机器人
-    - type: websocket  # 实时 WebSocket
-    - type: slack      # Slack Bot（Socket Mode / Events API）
-    - type: email      # IMAP 收信 + SMTP 回信
-    - type: wechat     # 微信公众号
-    - type: feishu     # 飞书 / Lark 消息卡片
-    - type: voice      # 语音（STT/TTS，可配置供应商）
-    - type: webhook    # Webhook 接收 + HTTP 回调
-    - type: discord    # Discord Bot（斜杠命令 + 线程 + Embed）
-```
+## 💡 一句话介绍
 
-### 🧠 知识库（RAG）
+> **不只是 Harness，是比 Harness 高一维的 Agent OS。**
+> 从创建到运行到监控，一个工具搞定 Agent 全生命周期。
 
-```typescript
-import { KnowledgeBase } from 'opc-agent';
+## 🎯 和 Harness 框架的区别
 
-const kb = new KnowledgeBase('./docs');
-await kb.addFile('产品手册.pdf');
-// 智能体自动检索知识库，无需额外配置
-```
+| | LangChain | CrewAI | AutoGen | **OPC Agent** |
+|---|---|---|---|---|
+| 创建 | 写代码 | 写代码 | 写代码 | **`opc init` 一键** |
+| 配置 | Python/代码 | Python | Python | **YAML 声明式** |
+| 测试 | 自己搭 | 无 | 无 | **内置测试框架** |
+| 渠道 | 自己接 | 无 | 无 | **11 渠道开箱即用** |
+| 监控 | 自己搭 | 无 | 无 | **Traces + Score** |
+| 记忆 | 自己管 | 简单 | 简单 | **DeepBrain 集成** |
 
-内置 TF-IDF 向量化 + 余弦相似度检索，数据持久化到 `.opc-knowledge.json`，无需外部向量数据库。
+**框架管"怎么跑"，Agent OS 管"全过程"。**
 
-### 🎭 多智能体编排
+## 快速开始
 
-```typescript
-import { Orchestrator } from 'opc-agent';
+```bash
+npm install -g opc-agent
 
-const orchestrator = new Orchestrator({
-  agents: [分诊智能体, 销售智能体, 客服智能体],
-  strategy: 'route-by-intent',
-});
-```
+# 创建
+opc init my-agent
+cd my-agent
 
-支持顺序执行、并行执行、条件路由、智能体移交（handoff）。
+# 开发
+opc dev
 
-### 🧪 内置测试框架
+# 测试
+opc test
 
-```yaml
-spec:
-  testing:
-    cases:
-      - name: 问候测试
-        input: "你好"
-        expect:
-          contains: ["你好", "帮"]
-          maxLatencyMs: 5000
+# 运行
+opc run
 ```
 
-```bash
-opc test              # 运行测试用例
-opc test --watch      # 监听模式
-opc test --json       # JSON 格式输出
-```
+## OAD 声明式配置
 
-### 🔧 插件系统
+不用写代码，用 YAML 定义 Agent：
 
 ```yaml
-spec:
-  plugins:
-    - name: logging
-    - name: analytics
-    - name: rate-limit
-      config: { maxPerMinute: 60 }
+id: customer-service
+name: 客服专员
+version: "1.0.0"
+
+model: deepseek-chat
+systemPrompt: |
+  你是一个专业的客服...
+
+skills:
+  - ticket-management
+  - knowledge-base-search
+
+channels:
+  - type: web
+    priority: primary
+  - type: telegram
+    priority: secondary
+  - type: wechat
+    priority: secondary
+
+memory:
+  shortTerm: true
+  longTerm:
+    provider: deepbrain
 ```
 
-完整生命周期钩子：`onInit`、`onMessage`、`onResponse`、`onError`、`onShutdown`。
-
-### 🔒 安全特性
-
-- 输入消毒（防 XSS、注入攻击）
-- API Key 轮换管理
-- CORS 配置
-- 安全响应头
-- 会话隔离认证中间件
-
-### 📊 监控与分析
-
-Web 渠道内置以下端点：
-
-| 端点 | 说明 |
-|------|------|
-| `GET /api/health` | 健康检查 |
-| `GET /api/metrics` | Prometheus 文本格式指标（uptime、请求数、错误数、LLM 延迟、Token 用量等） |
-| `GET /api/dashboard` | 实时仪表盘 |
-
-`opc analytics` 和 `opc stats` 命令可查看离线分析快照。
-
-## 🏗️ 架构
-
-```
-┌─────────────────────────────────────────────────┐
-│              OAD (YAML 定义文件)                  │
-│            智能体的一切配置都在这里                  │
-├─────────────────────────────────────────────────┤
-│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
-│  │  渠道层  │  │  插件层  │  │   安全层     │  │
-│  │10 个渠道 │  │ 日志/分析│  │ 消毒/CORS/认证│ │
-│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
-│  ┌────▼──────────────▼───────────────▼────────┐ │
-│  │          智能体运行时 (Agent Runtime)        │ │
-│  │   ┌─────────┐ ┌────────┐ ┌─────────────┐  │ │
-│  │   │  记忆   │ │  技能  │ │   知识库     │  │ │
-│  │   └─────────┘ └────────┘ └─────────────┘  │ │
-│  └────────────────────┬───────────────────────┘ │
-│  ┌────────────────────▼───────────────────────┐ │
-│  │            大语言模型供应商                   │ │
-│  │  DeepSeek · 通义千问 · OpenAI · Ollama     │ │
-│  └─────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────┘
-```
-
-## 📋 12 个开箱即用模板
+## CLI 命令
 
 ```bash
-opc init my-agent --template <模板名>
+opc init <name>           # 创建新 Agent
+opc dev                   # 开发模式（热重载）
+opc test                  # 运行测试
+opc run                   # 生产运行
+opc logs [-f]             # 查看 Traces 日志
+opc brain [--url ...]     # 查看记忆状态
+opc score                 # 查看性能评分
 ```
 
-| 模板 | 说明 | 典型场景 |
-|------|------|---------|
-| `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` | 教学助手 | 课程设计 + 出题 |
-
-## 🚀 部署
+## 11 个渠道
 
-### Docker 部署
+一套代码，部署到任意渠道：
 
-`opc init` 创建的每个项目都自带 `Dockerfile` 和 `docker-compose.yml`：
+| 渠道 | 状态 | 说明 |
+|------|------|------|
+| 🌐 Web | ✅ | 网页聊天 |
+| 📱 Telegram | ✅ | Bot API |
+| 💬 Slack | ✅ | Slack App |
+| 🎮 Discord | ✅ | Discord Bot |
+| 📧 Email | ✅ | IMAP/SMTP |
+| 💚 微信 | ✅ | 企业微信/个人微信 |
+| 🔵 飞书 | ✅ | 飞书机器人 |
+| 🎤 Voice | ✅ | 语音通话 |
+| 🔌 WebSocket | ✅ | 实时双向 |
+| 🪝 Webhook | ✅ | HTTP 回调 |
+| 📡 API | ✅ | REST API |
 
-```bash
-docker compose up -d
-```
+## 核心特性
 
-### 部署到 OpenClaw
+| 类别 | 特性 |
+|------|------|
+| 📋 **配置** | OAD 声明式定义、YAML 配置 |
+| 📡 **渠道** | 11 个渠道统一接入 |
+| 🧪 **测试** | 内置测试框架、163 tests |
+| 🔌 **插件** | 可扩展技能和工具系统 |
+| 📊 **监控** | Traces 行为采集、Score 评分 |
+| 🧠 **记忆** | DeepBrain 集成、自动学习 |
+| 🌍 **国际化** | 内置 i18n 支持 |
+| 🚀 **部署** | OpenClaw 等平台一键部署 |
+| 📈 **分析** | Analytics 数据分析 |
+| 🔄 **流式** | Streaming 实时响应 |
+
+## 架构
 
-```bash
-opc deploy --target openclaw
-opc deploy --target openclaw --install  # 同时写入本地配置
 ```
-
-生成 `IDENTITY.md`、`SOUL.md`、`AGENTS.md` 到 `~/.openclaw/agents/{id}/workspace/`。
-
-### 部署到 Hermes
-
-```bash
-opc deploy --target hermes
+┌─────────────────────────────────────────┐
+│              OPC Agent OS                │
+├──────────┬──────────┬───────────────────┤
+│  创建     │  运行     │  监控              │
+│ opc init │ 11 渠道   │ Traces            │
+│ OAD 配置  │ 插件系统  │ Score             │
+│ 测试框架  │ 流式响应  │ Analytics          │
+├──────────┴──────────┴───────────────────┤
+│              DeepBrain 记忆               │
+│         learn ← Traces → recall          │
+└─────────────────────────────────────────┘
 ```
 
-将 OAD 转换为 Hermes Character 格式（包含 personality、bio、lore、message examples 等字段）。
-
-## 📖 CLI 命令参考
-
-| 命令 | 说明 |
-|------|------|
-| `opc init [name]` | 创建新智能体项目（交互式，可选模板） |
-| `opc create <name>` | 从模板快速创建 |
-| `opc run` | 启动智能体 |
-| `opc dev` | 开发模式（文件监听热重载） |
-| `opc chat` | 命令行交互对话（readline 界面） |
-| `opc test` | 运行 OAD 中定义的测试用例 |
-| `opc build` | 校验 OAD 配置合法性 |
-| `opc info` | 查看智能体信息 |
-| `opc analytics` | 查看使用分析 |
-| `opc stats` | 查看运行时统计快照 |
-| `opc deploy` | 部署智能体（--target openclaw\|hermes） |
-| `opc kb add <file>` | 向知识库添加文件 |
-| `opc kb search <query>` | 搜索知识库 |
-| `opc kb stats` | 知识库统计 |
-| `opc kb clear` | 清空知识库 |
-| `opc search` | 搜索 OPC Registry |
-| `opc tool` | MCP 工具管理 |
-| `opc workflow run` | 运行工作流 |
-| `opc workflow list` | 列出工作流 |
-| `opc version-mgmt list` | 列出历史版本 |
-| `opc version-mgmt rollback` | 回滚版本 |
-| `opc publish` | 打包发布智能体 |
-| `opc install <pkg>` | 安装智能体包 |
-| `opc plugin list` | 列出已安装插件 |
-| `opc plugin add <name>` | 添加插件 |
-| `opc migrate` | OAD Schema 迁移 |
-
-## 🔗 SDK 参考
-
-```typescript
-import { AgentRuntime, KnowledgeBase, Orchestrator } from 'opc-agent';
-
-// 启动智能体
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');
-await runtime.initialize();
-await runtime.start();
-
-// 知识库
-const kb = new KnowledgeBase('./docs');
-await kb.addFile('handbook.pdf');
-const results = await kb.search('退款政策');
-
-// 多智能体编排
-const orch = new Orchestrator({
-  agents: [agentA, agentB],
-  strategy: 'route-by-intent',
-});
-```
+## 🔗 生态
 
-## 🔑 OAD 配置文件速览
+| 项目 | 定位 | 关系 |
+|------|------|------|
+| [deepbrain](https://github.com/Deepleaper/deepbrain) | Agent 记忆引擎 | Traces → learn() |
+| **opc-agent** | Agent OS | ← 你在这里 |
+| [agentkits](https://github.com/Deepleaper/agentkits) | 带记忆的 OpenRouter | 模型调用层 |
+| [agent-workstation](https://github.com/Deepleaper/agent-workstation) | 虚拟工位模板 | `opc init --template` |
 
-```yaml
-apiVersion: opc/v1
-kind: Agent
-
-metadata:
-  name: my-agent
-  version: 1.0.0
-
-spec:
-  provider:
-    default: deepseek
-    allowed: [deepseek, openai, qwen, anthropic, ollama]
-  model: deepseek-chat
-  systemPrompt: |
-    你是一个专业的客服助手...
-
-  channels:
-    - type: web
-      port: 3000
-
-  memory:
-    shortTerm: true
-    longTerm: false
-
-  rateLimits:
-    perUser:
-      maxRequests: 60
-      windowMs: 60000
-
-  plugins:
-    - name: logging
-    - name: analytics
-
-  testing:
-    cases:
-      - name: 基本问候
-        input: "你好"
-        expect:
-          contains: ["你好"]
-          maxLatencyMs: 5000
-```
+## License
 
-## 🤝 贡献指南
+Apache-2.0
 
-```bash
-git clone https://github.com/Deepleaper/opc-agent.git
-cd opc-agent
-npm install
-npm run build   # TypeScript 编译
-npm test        # 运行 146 个测试
-```
+---
 
-欢迎提交 Issue 和 Pull Request。
+<a name="english"></a>
 
-## 📄 开源协议
+## English
 
-[Apache License 2.0](LICENSE) — 商用和开源项目均可自由使用。
+## 💡 What Is OPC Agent?
 
----
+> **Not just a Harness — it's an Agent OS, one dimension above Harness frameworks.**
+> From creation to runtime to monitoring, one tool for the entire Agent lifecycle.
 
-<details>
-<summary id="english">🇺🇸 English</summary>
+## 🎯 How It Differs from Harness Frameworks
 
-## OPC Agent
+| | LangChain | CrewAI | AutoGen | **OPC Agent** |
+|---|---|---|---|---|
+| Creation | Write code | Write code | Write code | **`opc init` one command** |
+| Configuration | Python/code | Python | Python | **YAML declarative** |
+| Testing | DIY | None | None | **Built-in test framework** |
+| Channels | DIY | None | None | **11 channels out-of-the-box** |
+| Monitoring | DIY | None | None | **Traces + Score** |
+| Memory | DIY | Basic | Basic | **DeepBrain integration** |
 
-A **TypeScript-first open agent framework** by [Deepleaper](https://www.deepleaper.com). Define your agent in a single YAML file (OAD — Open Agent Definition), connect any LLM provider, deploy to any channel.
+**Frameworks manage "how to run." Agent OS manages "the entire process."**
 
 ## Quick Start
 
 ```bash
 npm install -g opc-agent
+
+# Create
 opc init my-agent
 cd my-agent
-opc run
-```
-
-Agent is live at `http://localhost:3000` with a built-in web chat UI.
-
-## Features
-
-- **Multi-Provider LLM** — DeepSeek, Qwen, OpenAI, Anthropic, Ollama, any OpenAI-compatible API
-- **10 Channels** — Web, Telegram, Slack, WebSocket, Email, WeChat, Feishu, Voice (STT/TTS), Webhook, Discord
-- **Knowledge Base (RAG)** — TF-IDF + cosine similarity, no external vector DB required
-- **Multi-Agent Orchestration** — Intent routing, sequential/parallel execution, agent handoff
-- **Built-in Testing** — YAML-defined test cases with content and latency assertions
-- **Plugin System** — Logging, analytics, rate limiting; full lifecycle hooks
-- **Security** — Input sanitization, CORS, auth middleware, session isolation
-- **Monitoring** — `/api/health`, `/api/metrics` (Prometheus format), `/api/dashboard`
-- **12 Templates** — Customer service, sales, knowledge base, code review, HR, and more
-- **146 Tests** — 22 test files covering all major features
-
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `opc init [name]` | Create new agent project (interactive, template selection) |
-| `opc run` | Start agent |
-| `opc dev` | Development mode (hot-reload) |
-| `opc test` | Run OAD test cases |
-| `opc chat` | Interactive CLI chat |
-| `opc build` | Validate OAD configuration |
-| `opc deploy` | Deploy (`--target openclaw\|hermes`) |
-| `opc analytics` | View analytics |
-| `opc stats` | Runtime statistics snapshot |
-| `opc kb add <file>` | Add file to knowledge base |
-| `opc kb search <query>` | Search knowledge base |
-| `opc workflow run` | Run a workflow |
-| `opc version-mgmt rollback` | Rollback to a previous version |
-| `opc publish` | Package agent for distribution |
-| `opc install <pkg>` | Install agent package |
-| `opc plugin add <name>` | Add plugin |
-| `opc migrate` | Migrate OAD schema |
-
-## Deploy
-
-### Docker
-
-Every project created with `opc init` includes a `Dockerfile` and `docker-compose.yml`:
 
-```bash
-docker compose up -d
-```
+# Develop
+opc dev
 
-### OpenClaw
+# Test
+opc test
 
-```bash
-opc deploy --target openclaw
+# Run
+opc run
 ```
 
-Generates `IDENTITY.md`, `SOUL.md`, `AGENTS.md` into `~/.openclaw/agents/{id}/workspace/`.
+## OAD Declarative Configuration
 
-### Hermes
+Define your Agent with YAML — no code required:
 
-```bash
-opc deploy --target hermes
+```yaml
+id: customer-service
+name: Customer Service Rep
+version: "1.0.0"
+
+model: deepseek-chat
+systemPrompt: |
+  You are a professional customer service agent...
+
+skills:
+  - ticket-management
+  - knowledge-base-search
+
+channels:
+  - type: web
+    priority: primary
+  - type: telegram
+    priority: secondary
+  - type: wechat
+    priority: secondary
+
+memory:
+  shortTerm: true
+  longTerm:
+    provider: deepbrain
 ```
 
-Converts OAD to Hermes Character format (personality, bio, lore, message examples, style guides).
-
-## SDK
+## CLI Commands
 
-```typescript
-import { AgentRuntime, KnowledgeBase, Orchestrator } from 'opc-agent';
-
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');
-await runtime.initialize();
-await runtime.start();
+```bash
+opc init <name>           # Create a new Agent
+opc dev                   # Development mode (hot reload)
+opc test                  # Run tests
+opc run                   # Production run
+opc logs [-f]             # View Traces logs
+opc brain [--url ...]     # View memory status
+opc score                 # View performance score
 ```
 
-## License
+## 11 Channels
+
+One codebase, deploy to any channel:
+
+| Channel | Status | Description |
+|---------|--------|-------------|
+| 🌐 Web | ✅ | Web chat |
+| 📱 Telegram | ✅ | Bot API |
+| 💬 Slack | ✅ | Slack App |
+| 🎮 Discord | ✅ | Discord Bot |
+| 📧 Email | ✅ | IMAP/SMTP |
+| 💚 WeChat | ✅ | Enterprise/Personal WeChat |
+| 🔵 Feishu | ✅ | Feishu (Lark) Bot |
+| 🎤 Voice | ✅ | Voice call |
+| 🔌 WebSocket | ✅ | Real-time bidirectional |
+| 🪝 Webhook | ✅ | HTTP callback |
+| 📡 API | ✅ | REST API |
+
+## Full Feature Set
+
+| Category | Features |
+|----------|----------|
+| 📋 **Configuration** | OAD declarative definition, YAML config |
+| 📡 **Channels** | 11 channels, unified access |
+| 🧪 **Testing** | Built-in test framework, 163 tests |
+| 🔌 **Plugins** | Extensible skills and tools system |
+| 📊 **Monitoring** | Traces behavior collection, Score rating |
+| 🧠 **Memory** | DeepBrain integration, auto-learning |
+| 🌍 **i18n** | Built-in internationalization support |
+| 🚀 **Deployment** | One-click deploy on OpenClaw and other platforms |
+| 📈 **Analytics** | Data analytics |
+| 🔄 **Streaming** | Real-time streaming responses |
+
+## Architecture
 
-[Apache License 2.0](LICENSE)
-
----
+```
+┌─────────────────────────────────────────┐
+│              OPC Agent OS                │
+├──────────┬──────────┬───────────────────┤
+│  Create   │  Run      │  Monitor         │
+│ opc init  │ 11 Chan.  │ Traces           │
+│ OAD Config│ Plugins   │ Score            │
+│ Test Fwk  │ Streaming │ Analytics        │
+├──────────┴──────────┴───────────────────┤
+│           DeepBrain Memory               │
+│         learn ← Traces → recall          │
+└─────────────────────────────────────────┘
+```
 
-Built with ❤️ by [Deepleaper](https://www.deepleaper.com)
+## 🔗 Ecosystem
 
-</details>
+| Project | Role | Relationship |
+|---------|------|-------------|
+| [deepbrain](https://github.com/Deepleaper/deepbrain) | Agent Memory Engine | Traces → learn() |
+| **opc-agent** | Agent OS | ← You are here |
+| [agentkits](https://github.com/Deepleaper/agentkits) | OpenRouter with Memory | Model call layer |
+| [agent-workstation](https://github.com/Deepleaper/agent-workstation) | Virtual Role Templates | `opc init --template` |
 
----
+## License
 
-<p align="center">由 <a href="https://www.deepleaper.com">跃盟科技 (Deepleaper)</a> 用 ❤️ 打造</p>
+Apache-2.0