opc-agent 5.0.0-rc.21 → 5.0.0-rc.23

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [5.0.0-rc.22] - 2026-04-24
+
+### New Features
+- **read_file / write_file** — Agent 可以直接读写本地文件，支持路径安全检查（防止逃逸 workspace）、100KB 读取上限、二进制检测、append 模式
+- **语音合成 (Voice Reply)** — 集成 edge-tts，双通道实现（Python CLI + WebSocket 直连微软服务 fallback），默认中文语音 `zh-CN-XiaoxiaoNeural`
+- **`opc voice test "<文字>"`** — CLI 语音测试命令
+- **OAD Schema 扩展** — voice.tts 配置新增默认值（provider=edge-tts, voice=zh-CN-XiaoxiaoNeural, speed=1.0）
+
+## [5.0.0-rc.21] - 2026-04-24
+
+### New Features
+- **MCP 完整集成** — MCPClientManager（连接外部 MCP Server）+ MCPServer（暴露 OPC Agent builtin tools 给外部 MCP Client）+ CLI `opc mcp list/test/serve`
+- **spawn_subagents** — 并行子代理工具，支持多任务并行执行
+- **Ollama Embedding Hybrid Search** — DeepBrain 语义搜索（FTS5 + Ollama cosine similarity）
+- **execute_code** — JS/TS/Python 沙箱执行
+- **Skill→Tool** — 自动将 Skill 文件转换为可调用的 Tool
+- **Provider Failover 增强** — 含 gpt-4o-mini → Ollama-first 默认值修复
+- **handleMessageStream pipeline 修复**
+
 ## [5.0.0-rc.14] - 2026-04-23
 
 ### New Features

package/README.md

@@ -1,218 +1,188 @@
 <div align="center">
 
-# ⚡ OPC Agent — 瞬知 Studio
+# ⚡ OPC Agent
 
-**Your AI workforce, running locally. Zero cloud cost to start.**
-
-One computer. One command. Your own AI agents — learning, evolving, working 24/7.
+**Your own AI employee — local, private, gets smarter over time.**
 
 [![npm](https://img.shields.io/npm/v/opc-agent/alpha?label=opc-agent%40alpha)](https://www.npmjs.com/package/opc-agent)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/tests-1114%2B%20passing-brightgreen)](CONTRIBUTING.md)
 
-[Quick Start](#-quick-start) · [What's New in v5](#-whats-new-in-v5) · [Features](#-features) · [Architecture](#-architecture) · [CLI](#-cli-commands) · [中文](README.zh-CN.md)
+[中文文档](README.zh-CN.md)
 
 </div>
 
 ---
 
-## 🚀 Quick Start
+## Why OPC Agent?
+
+AI Agents are powerful, but hard to use for most people:
+
+- **Expensive** — Cloud agents charge per token. Costs add up fast.
+- **No memory** — Every conversation starts from scratch.
+- **Data privacy** — Your chats and documents live on someone else's servers.
+- **Can only chat** — Can't read files, search the web, or run code.
 
-### One-Line Install (recommended)
+**OPC Agent fixes all of this:**
+
+✅ Runs locally, zero cost (powered by Ollama)<br>
+✅ Gets smarter over time (automatic learning & evolution)<br>
+✅ Your data stays on your machine<br>
+✅ Can read/write files, search the web, execute code, use tools
+
+---
+
+## 🚀 Install
+
+Pick your OS, copy one line:
+
+### macOS / Linux
 
 ```bash
-# macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/Deepleaper/opc-agent/main/install.sh | bash
+```
+
+### Windows
 
-# Windows (PowerShell)
+```powershell
 irm https://raw.githubusercontent.com/Deepleaper/opc-agent/main/install.ps1 | iex
 ```
 
-This automatically installs Node.js, OPC Agent, Ollama, and a recommended AI model based on your hardware.
+> The installer automatically sets up Node.js, OPC Agent, Ollama, and the best AI model for your hardware. No manual steps.
 
-### Or install manually
+### Manual install
 
 ```bash
 npm install -g opc-agent@alpha
-opc setup        # Interactive setup wizard
 ```
 
-### Get started in 30 seconds
+---
+
+## ⚡ Get started in 30 seconds
+
+### Step 1: Create your AI employee
 
 ```bash
-opc chat          # Chat in terminal
-opc studio        # Open web UI → localhost:4000
-opc run           # Start everything: Agent + Telegram + Web + Studio
+opc init my-agent
+cd my-agent
 ```
 
----
+### Step 2: Start chatting
 
-## 🆕 What's New in v5
+```bash
+opc chat
+```
 
-**v5.0.0-rc.14** is the most complete release yet. Key highlights:
+That's it. Your AI employee is ready.
 
-- **OutputGuard** — Every agent response is passed through a 6-rule sanitization pipeline before it reaches any channel. Prevents model identity leakage, reasoning tag exposure (`<think>`), PII, and prompt-injection echoes. Works with streaming.
-- **Workstation Templates** — `opc init --template ceo-coach-socratic` scaffolds a fully-configured agent workspace in seconds. More templates in the registry.
-- **Provider Failover** — Automatic LLM failover across OpenAI, Anthropic, Ollama, and others. Circuit-breaker + heartbeat monitoring. No dropped requests.
-- **7-Layer System Prompt** — Context assembly is now deterministic and layered: base identity → EGO.md → SOUL.md → CONTEXT.md → memory → skills → history.
-- **DeepBrain Recall** — Semantic memory is prefetched and injected into every conversation turn automatically.
-- **Hybrid Search** — DeepBrain combines FTS5 full-text and vector semantic search for higher-recall knowledge retrieval.
-- **1114+ tests passing** — Up from 204 in v2.
+### More
 
-See [CHANGELOG.md](CHANGELOG.md) for the full rc.1–rc.14 history.
+```bash
+opc studio        # Web dashboard at localhost:4000
+opc run           # Start everything: chat + Telegram + web + dashboard
+```
 
 ---
 
-## ✨ Features
+## What can it do?
 
-| Feature | Description |
-|---------|-------------|
-| 🧠 **Self-Evolving** | 4-layer evolution engine: Experience → Memory → Skills → Group knowledge |
-| 💰 **Zero Cost Start** | Runs 100% locally with Ollama. No API key needed. |
-| 🎨 **Studio UI** | Web-based management at localhost:4000 — models, channels, knowledge, templates |
-| 📱 **Multi-Channel** | Telegram, Web, WeChat, Feishu, Discord, Slack, Email |
-| 🔧 **40 Built-in Skills** | File ops, web search, code execution, image generation, and more |
-| 🛡 **OutputGuard** | Unified output sanitization: prevents identity leakage, PII, reasoning tag exposure |
-| 🏗 **Workstation Templates** | `opc init --template <id>` creates a full agent workspace instantly |
-| 🔀 **Provider Failover** | Automatic LLM failover with circuit-breaker and heartbeat monitoring |
-| 🤖 **A2A Protocol** | Agent-to-agent communication for multi-agent workflows |
-| 📦 **All-in-One** | DeepBrain (knowledge) + AgentKits (models) + Workstation (templates) |
-| 🔒 **Privacy First** | Your data stays on your machine. No telemetry. |
+OPC Agent isn't just a chatbot. It's an **AI employee that gets work done**:
+
+| Capability | Details |
+|-----------|---------|
+| 💬 **Chat** | Terminal or web interface |
+| 📁 **Read & write files** | Read your docs, write reports, organize notes |
+| 🔍 **Web search** | Real-time search for up-to-date information |
+| 🌐 **Read web pages** | Fetch and summarize any URL |
+| 💻 **Execute code** | Run JavaScript, TypeScript, Python |
+| 🧠 **Memory** | Remembers past conversations, gets smarter over time |
+| 🔧 **MCP tool extensions** | Connect GitHub, databases, Slack, and more |
+| 📱 **Telegram bot** | Add a bot token and chat via Telegram |
+| 🎙 **Voice synthesis** | Text-to-speech via edge-tts |
+| 👥 **Sub-agents** | Spawn parallel workers for complex tasks |
 
 ---
 
-## 🏗 Architecture
+## 🧠 Gets smarter over time
+
+This is what makes OPC Agent different: **it evolves.**
 
 ```
-┌──────────────────────────────────────────────────────┐
-│                   OPC Agent CLI                      │
-│       opc chat · opc studio · opc run               │
-├──────────────────────────────────────────────────────┤
-│  Agent Loop         │  Self-Evolution (L1-L4)        │
-│  7-Layer Context    │  L1 Experience Compile         │
-│  Assembly           │  L2 Memory Consolidate         │
-│  OutputGuard        │  L3 Skill Discovery            │
-│                     │  L4 Group Evolution            │
-├──────────────────────────────────────────────────────┤
-│  DeepBrain          │ AgentKits     │ Workstation    │
-│  (Knowledge)        │ (Models +     │ (Templates)    │
-│  SQLite+FTS5+Vector │  Failover)    │ opc init       │
-├──────────────────────────────────────────────────────┤
-│  Channels (OutputGuard applied to all)               │
-│  Telegram │ Web │ WeChat │ Feishu │ Discord │ Slack  │
-└──────────────────────────────────────────────────────┘
+You chat with your AI
+    ↓
+AI extracts knowledge from the conversation     ← automatic
+    ↓
+Knowledge is saved to a local database           ← on your machine
+    ↓
+Next conversation references that knowledge      ← it remembers
+    ↓
+Knowledge gradually refines and improves         ← gets better over time
 ```
 
-### How it works
-
-1. **You talk** → Agent receives message via any channel
-2. **Agent thinks** → 7-layer context assembly + tool selection + LLM reasoning
-3. **Agent acts** → Executes tools, calls APIs, generates content
-4. **OutputGuard** → Sanitizes response through 6 rules before delivery
-5. **Agent learns** → Every interaction feeds the evolution engine
-6. **Agent evolves** → Knowledge distills upward: experience → memory → skills
-
----
-
-## 💻 CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `opc setup` | Interactive setup wizard |
-| `opc init [name]` | Create new agent project |
-| `opc init --template <id>` | Scaffold agent from template (e.g. `ceo-coach-socratic`) |
-| `opc chat` | Terminal chat with agent |
-| `opc studio` | Open Studio web UI (port 4000) |
-| `opc run` | Start all services (Agent + channels + Studio) |
-| `opc brain stats` | Show knowledge base statistics |
-| `opc brain recall <query>` | Semantic search in knowledge |
-| `opc brain learn <file>` | Import document into knowledge |
-| `opc doctor` | Diagnose installation issues |
+All learning runs on local Ollama models. **Zero cost.**
 
 ---
 
-## 🔧 Configuration
+## 🎨 Studio Dashboard
 
-After `opc setup`, all configuration lives in Studio UI (localhost:4000):
+```bash
+opc studio
+```
 
-- **Models** — Switch between Ollama models, add cloud API keys, configure failover order
-- **Channels** — Configure Telegram bot, WeChat, Feishu, etc.
-- **Knowledge** — Drag & drop documents, manage DeepBrain
-- **Templates** — Browse industry/job/workstation templates
-- **Agent Settings** — Edit personality, skills, model assignments
+Open `localhost:4000` in your browser to:
 
-Config files: `~/.opc/config.json` (global), `oad.yaml` (per agent)
+- **Models** — Switch AI models (local or cloud)
+- **Channels** — Configure Telegram bot
+- **Knowledge** — See what your agent has learned
+- **Settings** — Customize personality, skills, behavior
 
 ---
 
-## 📖 Model Support
+## 📖 Model support
+
+### Local (zero cost)
 
-### Local (Ollama) — Zero Cost
-Auto-detected and recommended based on your RAM:
+Auto-recommended based on your RAM:
 
-| RAM | Recommended Model | Size |
-|-----|------------------|------|
+| RAM | Model | Download |
+|-----|-------|----------|
 | ≤3 GB | qwen2.5:0.5b | 400MB |
 | ≤7 GB | qwen2.5:1.5b | 1.0GB |
 | ≤15 GB | qwen2.5:7b | 4.7GB |
 | ≤31 GB | qwen2.5:14b | 9.0GB |
 | 32+ GB | qwen2.5:32b | 19GB |
 
-### Cloud (via AgentKits)
-Configure in Studio → Models: OpenAI, DeepSeek, Anthropic, Qwen, Google Gemini
+### Cloud (optional)
 
-Provider failover is configured per-agent in `oad.yaml`.
+Add API keys in Studio: OpenAI, DeepSeek, Anthropic, Qwen, Google Gemini
 
----
-
-## 🌐 Multi-Channel
-
-| Channel | Setup |
-|---------|-------|
-| 💬 Web Chat | Built-in, localhost:3000 |
-| 📱 Telegram | Add bot token in Studio |
-| 💬 WeChat | Add app credentials in Studio |
-| 🐦 Feishu | Add app credentials in Studio |
-| 🎮 Discord | Add bot token in Studio |
-| 💼 Slack | Add bot token in Studio |
-| 📧 Email | Add SMTP config in Studio |
-
-All channels run OutputGuard on every outbound message.
+Automatic failover — if one provider goes down, the next one takes over.
 
 ---
 
-## 🧬 Self-Evolution
-
-OPC Agent gets smarter over time through 4 layers of evolution:
+## 📋 Commands
 
-- **L1 — Experience Compilation**: Raw interactions → structured insights (local Ollama)
-- **L2 — Memory Consolidation**: Insights → refined knowledge (cloud AgentKits)
-- **L3 — Skill Discovery**: Patterns → auto-generated skills (cloud AgentKits)
-- **L4 — Group Evolution**: Individual knowledge → shared wisdom (local Ollama)
-
-All L1/L4 processing runs locally at zero cost. L2/L3 uses cloud models for higher quality.
+| Command | What it does |
+|---------|-------------|
+| `opc init [name]` | Create an AI employee |
+| `opc chat` | Chat in terminal |
+| `opc studio` | Open web dashboard |
+| `opc run` | Start all services |
+| `opc brain stats` | Knowledge base status |
+| `opc brain recall "query"` | Search knowledge |
+| `opc brain learn file.md` | Import a document |
+| `opc voice test "hello"` | Test voice synthesis |
+| `opc mcp list` | List connected tools |
+| `opc doctor` | Diagnose issues |
 
 ---
 
-## 📦 Project Structure
+## 🔒 Privacy
 
-```
-~/.opc/                     # Global config
-  config.json               # Settings
-  agents/                   # Agent data
-
-my-agent/                   # Agent workspace
-  EGO.md                    # Agent personality
-  SOUL.md                   # Tone and values
-  CONTEXT.md                # Project context
-  DEEPBRAIN.md              # Knowledge summary
-  oad.yaml                  # Agent definition
-  .opc/
-    brain.db                # Knowledge database (SQLite + FTS5 + vector)
-    skills/                 # Auto-generated skills
-    evolution/              # Evolution logs
-```
+- All data stored locally on your machine
+- No telemetry
+- Local Ollama models never touch the cloud
+- Your knowledge, conversations, and files stay private
 
 ---
 
@@ -223,11 +193,9 @@ git clone https://github.com/Deepleaper/opc-agent.git
 cd opc-agent
 npm install
 npx tsc                    # Build
-npx vitest run             # Test (1114+ tests)
+npx vitest run             # Test
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
-
 ---
 
 ## 📄 License
@@ -238,8 +206,8 @@ Apache-2.0 © [Deepleaper](https://github.com/Deepleaper)
 
 <div align="center">
 
-**Built by [Deepleaper](https://www.deepleaper.com)** — Making AI work for everyone.
+**Built by [Deepleaper](https://www.deepleaper.com)**
 
-⭐ Star this repo if OPC Agent helps you!
+⭐ Star this repo if it helps you!
 
 </div>