opc-agent 4.1.2 → 4.1.4

package/docs/zh/guide/configuration.md

@@ -1,135 +0,0 @@
-# 配置详解
-
-## OAD 文件结构
-
-`oad.yaml` 是智能体的核心配置文件，所有配置都在这里：
-
-```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: my-agent
-  version: 1.0.0
-  description: 我的智能体
-spec:
-  provider:
-    default: deepseek
-    allowed: [openai, deepseek, qwen]
-  model: deepseek-chat
-  systemPrompt: "你是一个专业的助手。"
-  skills: []
-  channels:
-    - type: web
-      port: 3000
-  memory:
-    shortTerm: true
-    longTerm: false
-  testing:
-    cases:
-      - name: 问候测试
-        input: "你好"
-        expect:
-          contains: ["你好", "帮"]
-          maxLatencyMs: 5000
-  rateLimits:
-    perUser:
-      maxRequests: 60
-      windowMs: 60000
-    perProvider:
-      maxRequests: 100
-      windowMs: 60000
-  cache:
-    enabled: true
-    ttlMs: 3600000
-```
-
-## 环境变量
-
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `OPC_LLM_API_KEY` | 大语言模型 API Key | — |
-| `OPC_LLM_BASE_URL` | API 地址 | `https://api.openai.com/v1` |
-| `OPC_LLM_MODEL` | 模型名称 | `gpt-4o-mini` |
-
-## 模型供应商配置
-
-```yaml
-spec:
-  provider:
-    default: deepseek               # 默认供应商
-    allowed: [deepseek, qwen, openai]  # 允许的供应商列表
-  model: deepseek-chat              # 具体模型
-```
-
-运行时通过环境变量 `OPC_LLM_API_KEY` 和 `OPC_LLM_BASE_URL` 传入凭证。
-
-## 限流配置
-
-保护你的 API 配额和后端服务：
-
-```yaml
-spec:
-  rateLimits:
-    perUser:
-      maxRequests: 60       # 每个用户每分钟最多 60 次请求
-      windowMs: 60000
-    perProvider:
-      maxRequests: 100      # 每个供应商每分钟最多 100 次请求
-      windowMs: 60000
-```
-
-## 缓存配置
-
-开启 LLM 响应缓存，降低 API 调用成本：
-
-```yaml
-spec:
-  cache:
-    enabled: true
-    ttlMs: 3600000    # 缓存有效期 1 小时
-    maxEntries: 1000  # 最大缓存条数
-```
-
-## 渠道配置
-
-```yaml
-spec:
-  channels:
-    - type: web
-      port: 3000
-      config:
-        cors: true
-        sse: true           # 启用 SSE 流式响应
-
-    - type: telegram
-      config:
-        token: ${TELEGRAM_BOT_TOKEN}
-
-    - type: wechat
-      config:
-        appId: ${WECHAT_APP_ID}
-        appSecret: ${WECHAT_APP_SECRET}
-```
-
-## 记忆配置
-
-```yaml
-spec:
-  memory:
-    shortTerm: true          # 对话上下文记忆
-    longTerm: true           # 跨会话长期记忆
-    provider: deepbrain      # 长期记忆后端
-    config:
-      collection: my-kb      # 知识库集合名称
-```
-
-## DTV 信任配置
-
-```yaml
-spec:
-  dtv:
-    trust:
-      level: sandbox         # sandbox | verified | certified | listed
-    value:
-      metrics: [response_time, satisfaction_score]
-```

package/docs/zh/guide/deployment.md

@@ -1,81 +0,0 @@
-# 部署指南
-
-## 本地开发
-
-```bash
-# 热重载开发模式
-opc dev
-
-# 普通启动
-opc run
-```
-
-## Docker 部署
-
-每个 `opc init` 创建的项目都自带 `Dockerfile` 和 `docker-compose.yml`：
-
-```bash
-docker compose up -d
-```
-
-### 自定义 Docker 配置
-
-```yaml
-# docker-compose.yml
-services:
-  agent:
-    build: .
-    ports:
-      - "3000:3000"
-    env_file: .env
-    restart: unless-stopped
-```
-
-## 部署到 OpenClaw
-
-```bash
-# 部署
-opc deploy --target openclaw
-
-# 部署并注册到配置
-opc deploy --target openclaw --install
-```
-
-## 部署到 Hermes 云
-
-```bash
-# 直接部署
-opc deploy --target hermes
-
-# 生成部署文件到指定目录
-opc deploy --target hermes --output ./my-deploy
-```
-
-## 环境变量
-
-在 `.env` 文件中配置：
-
-```bash
-# 大语言模型配置
-OPC_LLM_API_KEY=sk-xxx
-OPC_LLM_BASE_URL=https://api.deepseek.com/v1
-OPC_LLM_MODEL=deepseek-chat
-
-# Telegram 机器人（可选）
-TELEGRAM_BOT_TOKEN=xxx
-
-# 微信公众号（可选）
-WECHAT_APP_ID=xxx
-WECHAT_APP_SECRET=xxx
-```
-
-## 上线检查清单
-
-- [ ] 在 `.env` 中配置正确的 API Key
-- [ ] 在 `oad.yaml` 中配置限流策略
-- [ ] 开启缓存以降低 API 成本
-- [ ] 配置监控和告警
-- [ ] 运行 `opc test` 确保测试通过
-- [ ] 检查 DTV 信任等级设置
-- [ ] 配置 CORS 和安全头
-- [ ] 准备回滚方案

package/docs/zh/guide/getting-started.md

@@ -1,82 +0,0 @@
-# 快速开始
-
-## 安装
-
-```bash
-npm install -g opc-agent
-```
-
-## 创建第一个智能体
-
-```bash
-# 交互式创建（会让你选模板和配置）
-opc init my-agent
-cd my-agent
-```
-
-或者直接用模板：
-
-```bash
-opc init my-bot --template customer-service
-opc init my-bot --template sales-assistant
-opc init my-bot --template knowledge-base
-```
-
-## 配置
-
-编辑 `.env` 文件，填入你的大语言模型 API Key：
-
-```bash
-OPC_LLM_API_KEY=your-api-key
-OPC_LLM_BASE_URL=https://api.deepseek.com/v1    # DeepSeek
-OPC_LLM_MODEL=deepseek-chat
-```
-
-支持的供应商和对应的 Base URL：
-
-| 供应商 | Base URL | 推荐模型 |
-|--------|----------|---------|
-| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
-| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
-| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
-| Ollama (本地) | `http://localhost:11434/v1` | `llama3` |
-
-## 启动
-
-```bash
-# 启动 Web 对话服务
-opc run
-
-# 或者用命令行对话
-opc chat
-
-# 开发模式（改代码自动重启）
-opc dev
-```
-
-访问 `http://localhost:3000` 即可看到对话界面。
-
-## 校验配置
-
-```bash
-opc build
-```
-
-## 运行测试
-
-```bash
-opc test
-```
-
-## 查看数据分析
-
-```bash
-opc analytics
-```
-
-## 下一步
-
-- [核心概念](/zh/guide/concepts) — 理解 OAD、技能、渠道等概念
-- [模板列表](/zh/guide/templates) — 查看全部 12 个场景模板
-- [配置详解](/zh/guide/configuration) — OAD 文件的完整配置项
-- [部署指南](/zh/guide/deployment) — Docker、OpenClaw、Hermes 部署

package/docs/zh/guide/templates.md

@@ -1,84 +0,0 @@
-# 模板
-
-OPC Agent 提供 12 个开箱即用的场景模板，覆盖常见的企业智能体需求。
-
-## 模板列表
-
-| 模板 | 说明 | 适用场景 |
-|------|------|---------|
-| `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` | 数据分析师 | SQL 查询 + 数据可视化 |
-| `teacher` | 教学助手 | 课程设计 + 出题 + 互动 |
-
-## 使用模板
-
-```bash
-# 创建时指定模板
-opc init my-agent --template customer-service
-
-# 或者用简写
-opc init my-agent -t sales-assistant
-```
-
-## 客服智能体详解
-
-```yaml
-# customer-service/oad.yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: customer-service
-  version: 1.0.0
-  description: "客服智能体：FAQ 查询 + 人工转接"
-spec:
-  provider:
-    default: deepseek
-  model: deepseek-chat
-  systemPrompt: |
-    你是一个友好、专业的客服助手。
-    帮助客户解答产品、订单、物流、退换货等问题。
-    回答要简洁、有帮助、有同理心。
-  skills:
-    - name: faq-lookup
-      description: "FAQ 知识库查询"
-    - name: human-handoff
-      description: "转接人工客服"
-  channels:
-    - type: web
-      port: 3000
-```
-
-## 自定义模板
-
-你可以基于现有模板修改，也可以从头创建：
-
-1. 编写 `oad.yaml` 定义智能体
-2. 继承 `BaseSkill` 实现自定义技能
-3. 将 `oad.yaml` + `README.md` 打包成一个目录
-
-```typescript
-import { BaseSkill } from 'opc-agent';
-import type { AgentContext, Message, SkillResult } from 'opc-agent';
-
-export class MySkill extends BaseSkill {
-  name = 'my-skill';
-  description = '我的自定义技能';
-
-  async execute(context: AgentContext, message: Message): Promise<SkillResult> {
-    // 你的技能逻辑
-    if (message.content.includes('关键词')) {
-      return this.match('这是我的回答', 0.9);
-    }
-    return this.noMatch();
-  }
-}
-```

package/docs/zh/guide/testing.md

@@ -1,88 +0,0 @@
-# 测试
-
-## 概览
-
-OPC Agent 内置了测试框架。你可以在 `oad.yaml` 或单独的 `tests.yaml` 中定义测试用例，用 `opc test` 一键运行。
-
-## 在 OAD 中定义测试
-
-```yaml
-spec:
-  testing:
-    cases:
-      - name: 问候测试
-        input: "你好！"
-        expect:
-          contains: ["你好", "帮"]
-          maxLatencyMs: 5000
-
-      - name: 产品咨询
-        input: "你们怎么收费？"
-        expect:
-          contains: ["价格", "套餐"]
-          notContains: ["error"]
-
-      - name: 空输入
-        input: ""
-        expect:
-          maxLatencyMs: 2000
-```
-
-## 独立测试文件
-
-在 `oad.yaml` 同目录创建 `tests.yaml`：
-
-```yaml
-cases:
-  - name: 冒烟测试
-    input: "你好"
-    expect:
-      maxLatencyMs: 10000
-
-  - name: FAQ 验证
-    input: "退货政策是什么？"
-    expect:
-      contains: ["退货", "退款"]
-```
-
-## 运行测试
-
-```bash
-# 运行测试
-opc test
-
-# JSON 格式输出
-opc test --json
-
-# 指定 OAD 文件
-opc test -f my-agent.yaml
-
-# 监听模式（改了代码自动重跑）
-opc test --watch
-```
-
-## 测试报告
-
-```
-═══════════════════════════════════════════
-  OPC Agent 测试报告
-═══════════════════════════════════════════
-
-  ✔ [通过] 问候测试 (245ms)
-  ✔ [通过] 产品咨询 (312ms)
-  ✘ [失败] 空输入 (5120ms)
-      → 延迟 5120ms 超过上限 2000ms
-
-───────────────────────────────────────────
-  总计: 3  通过: 2  失败: 1  耗时: 5677ms
-───────────────────────────────────────────
-```
-
-## 断言类型
-
-| 断言 | 说明 |
-|------|------|
-| `contains` | 回复必须包含这些字符串（不区分大小写） |
-| `notContains` | 回复不能包含这些字符串 |
-| `toolCalled` | 指定的工具必须被调用 |
-| `maxLatencyMs` | 响应必须在指定时间内完成 |

package/docs/zh/index.md

@@ -1,27 +0,0 @@
----
-layout: home
-hero:
-  name: OPC Agent
-  text: 开放智能体框架
-  tagline: 构建、测试、运行企业级 AI 智能体
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /zh/guide/getting-started
-    - theme: alt
-      text: GitHub
-      link: https://github.com/Deepleaper/opc-agent
-features:
-  - title: ⚡ 30 秒上手
-    details: 两条命令创建智能体，开箱即用，支持 12 个场景模板
-  - title: 📋 OAD 声明式定义
-    details: 用 YAML 文件定义智能体的一切：模型、技能、渠道、安全策略
-  - title: 📡 多渠道部署
-    details: Web、Telegram、Slack、微信公众号、飞书、WebSocket，一套代码到处运行
-  - title: 🧪 内置测试框架
-    details: 在 OAD 文件中定义测试用例，opc test 一键验证智能体行为
-  - title: 🔌 多模型支持
-    details: DeepSeek、通义千问、OpenAI、Anthropic、Ollama，不绑定任何一家
-  - title: 🧠 知识库 RAG
-    details: 添加文档自动构建知识库，智能体回答时语义检索增强
----

package/fix-sidebar.mjs

@@ -1,188 +0,0 @@
-import { readFileSync, writeFileSync } from 'fs';
-
-const file = 'C:\\Users\\mingjwan\\tmp-opc-clone\\src\\studio-ui\\index.html';
-let html = readFileSync(file, 'utf-8');
-
-// 1. Add CSS classes before the closing </style>
-const newCSS = `
-    /* Sidebar restructure */
-    .sidebar-section-title { font-size: 11px; letter-spacing: 1px; color: var(--text-dim); margin: 20px 12px 8px; text-transform: uppercase; font-weight: 600; }
-    .sidebar-divider { height: 1px; background: var(--border); margin: 8px 12px; }
-    .agent-list-container { overflow-y: auto; flex: 1; min-height: 0; }
-    .agent-list-item {
-      display: flex; align-items: center; gap: 10px; padding: 10px 16px; border-radius: 12px;
-      cursor: pointer; color: var(--text-muted); transition: all 0.2s ease; font-size: 14px; margin-bottom: 2px; position: relative;
-    }
-    .agent-list-item:hover { background: var(--bg-hover); color: var(--text); transform: translateX(4px); }
-    .agent-list-item.active { background: var(--accent-light); color: #fff; font-weight: 600; box-shadow: var(--glow-sm); border: 1px solid var(--border); }
-    .agent-list-item .agent-icon { width: 24px; text-align: center; font-size: 16px; }
-    .agent-list-item .agent-name { flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-    .agent-list-item .status-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
-    .agent-list-item .status-dot.online { background: var(--green); box-shadow: 0 0 6px var(--green); }
-    .agent-list-item .status-dot.offline { background: var(--text-dim); }
-    .agent-list-item .status-dot.error { background: var(--red); box-shadow: 0 0 6px var(--red); }
-    .sidebar-bottom { margin-top: auto; flex-shrink: 0; }
-    .sidebar-nav { display: flex; flex-direction: column; flex: 1; min-height: 0; overflow: hidden; }
-`;
-
-html = html.replace('  </style>', newCSS + '  </style>');
-
-// 2. Replace sidebar nav content
-const oldSidebar = `      <div class="sidebar-nav">
-        <div class="nav-item active" data-page="dashboard" onclick="navigate('dashboard')">
-          <span class="icon">🏠</span> Dashboard
-        </div>
-        <div class="nav-item" data-page="chat" onclick="openLastChat()">
-          <span class="icon">💬</span> Chat
-        </div>
-        <div class="nav-item" data-page="templates" onclick="navigate('templates')">
-          <span class="icon">👤</span> Templates
-        </div>
-        <div class="nav-item" data-page="skills" onclick="navigate('skills')">
-          <span class="icon">🧩</span> Skills Market
-        </div>
-        <div class="nav-item" data-page="create" onclick="navigate('create')">
-          <span class="icon">✨</span> Create Agent
-        </div>
-        <div class="nav-item" data-page="settings" onclick="currentSettingsTab='models';navigate('settings')">
-          <span class="icon">🤖</span> Models
-        </div>
-        <div class="nav-item" data-page="settings" onclick="currentSettingsTab='channels';navigate('settings')">
-          <span class="icon">📡</span> Channels
-        </div>
-        <div class="nav-item" data-page="settings" onclick="currentSettingsTab='memory';navigate('settings')">
-          <span class="icon">🧠</span> Memory
-        </div>
-        <div class="nav-item" data-page="settings" onclick="navigate('settings')">
-          <span class="icon">⚙️</span> Settings
-        </div>
-        <div class="nav-item" data-page="schedules" onclick="navigate('schedules')">
-          <span class="icon">⏰</span> Schedules
-        </div>
-      </div>`;
-
-const newSidebar = `      <div class="sidebar-nav">
-        <!-- Section 1: My Agents -->
-        <div class="sidebar-section-title">🤖 我的 Agent</div>
-        <div class="agent-list-container" id="sidebar-agent-list">
-          <div style="padding: 12px 16px; color: var(--text-dim); font-size: 13px;">加载中...</div>
-        </div>
-
-        <!-- Section 2: Create -->
-        <div class="sidebar-divider"></div>
-        <div class="nav-item" data-page="create" onclick="navigate('create')">
-          <span class="icon">➕</span> 新建 Agent
-        </div>
-
-        <!-- Section 3: Global Config -->
-        <div class="sidebar-bottom">
-          <div class="sidebar-divider"></div>
-          <div class="sidebar-section-title">⚙️ 全局配置</div>
-          <div class="nav-item" data-page="global-runtime" onclick="navigate('global-runtime')">
-            <span class="icon">🚀</span> Runtime
-          </div>
-          <div class="nav-item" data-page="global-models" onclick="navigate('global-models')">
-            <span class="icon">🧠</span> Models
-          </div>
-          <div class="nav-item" data-page="global-memory" onclick="navigate('global-memory')">
-            <span class="icon">💾</span> Memory
-          </div>
-          <div class="nav-item" data-page="global-templates" onclick="navigate('global-templates')">
-            <span class="icon">📋</span> Templates
-          </div>
-        </div>
-      </div>`;
-
-html = html.replace(oldSidebar, newSidebar);
-
-// 3. Add JavaScript - extend navigate() and add loadSidebarAgents()
-// Insert global-* navigation handling into navigate function
-const oldNavigate = `      if (page === 'settings') { showSettings(currentSettingsTab || 'models'); }`;
-const newNavigate = `      if (page === 'settings') { showSettings(currentSettingsTab || 'models'); }
-      if (page === 'global-runtime') { currentSettingsTab='status'; showSettings('status'); showPage('settings'); return; }
-      if (page === 'global-models') { currentSettingsTab='models'; showSettings('models'); showPage('settings'); return; }
-      if (page === 'global-memory') { currentSettingsTab='memory'; showSettings('memory'); showPage('settings'); return; }
-      if (page === 'global-templates') { navigate('templates'); return; }`;
-
-html = html.replace(oldNavigate, newNavigate);
-
-// Add loadSidebarAgents function and navigateToAgent before the navigate function
-const navFuncMarker = `    // === Navigation ===`;
-const sidebarJS = `    // === Sidebar Agents ===
-    let selectedAgentId = null;
-
-    async function loadSidebarAgents() {
-      try {
-        const res = await fetch('/api/agents');
-        const data = await res.json();
-        const agents = data.agents || data || [];
-        const container = document.getElementById('sidebar-agent-list');
-        if (!agents.length) {
-          container.innerHTML = '<div style="padding: 12px 16px; color: var(--text-dim); font-size: 13px;">暂无 Agent</div>';
-          return;
-        }
-        container.innerHTML = agents.map(a => {
-          const status = (a.status || 'offline').toLowerCase();
-          const icon = a.emoji || a.icon || '🤖';
-          const name = a.name || a.id;
-          return \`<div class="agent-list-item\${selectedAgentId === a.id ? ' active' : ''}" data-agent-id="\${a.id}" onclick="navigateToAgent('\${a.id}')">
-            <span class="agent-icon">\${icon}</span>
-            <span class="agent-name">\${name}</span>
-            <span class="status-dot \${status}"></span>
-          </div>\`;
-        }).join('');
-      } catch(e) {
-        console.error('Failed to load sidebar agents:', e);
-        const container = document.getElementById('sidebar-agent-list');
-        if (container) container.innerHTML = '<div style="padding: 12px 16px; color: var(--text-dim); font-size: 13px;">加载失败</div>';
-      }
-    }
-
-    function navigateToAgent(agentId) {
-      selectedAgentId = agentId;
-      // Update sidebar active state
-      document.querySelectorAll('.agent-list-item').forEach(el => el.classList.remove('active'));
-      const item = document.querySelector(\`.agent-list-item[data-agent-id="\${agentId}"]\`);
-      if (item) item.classList.add('active');
-      // For now, navigate to dashboard with agent context
-      navigate('dashboard');
-    }
-
-    ${navFuncMarker}`;
-
-html = html.replace(navFuncMarker, sidebarJS);
-
-// Also update nav-item active highlighting to support global-* pages
-const oldNavActive = `      document.querySelectorAll('.nav-item').forEach(n => n.classList.remove('active'));
-      const navItem = document.querySelector(\`.nav-item[data-page="\${page}"]\`);
-      if (navItem) navItem.classList.add('active');`;
-
-const newNavActive = `      document.querySelectorAll('.nav-item').forEach(n => n.classList.remove('active'));
-      document.querySelectorAll('.agent-list-item').forEach(n => n.classList.remove('active'));
-      const navItem = document.querySelector(\`.nav-item[data-page="\${page}"]\`);
-      if (navItem) navItem.classList.add('active');`;
-
-html = html.replace(oldNavActive, newNavActive);
-
-// Add loadSidebarAgents() call on page load - find DOMContentLoaded or init
-// Look for where loadAgents is first called
-const initMarker = `if (page === 'dashboard') { loadAgents(); loadHealthDashboard(); }`;
-// We'll add the sidebar load call at the end of the navigate function's dashboard case isn't ideal.
-// Let's find where the app initializes
-const hashNav = `location.hash = \`/\${page}\`;`;
-
-// Better: add it to the initial page load. Find where hash routing happens.
-// Search for DOMContentLoaded or window.onload
-const loadMatch = html.match(/(?:DOMContentLoaded|window\.onload|loadAgents\(\);\s*loadHealthDashboard)/);
-
-// Just add it right after the navigate function definition area, in the init block
-// Find "navigate('dashboard')" at the bottom (initial route)
-const initRoute = html.indexOf("navigate('dashboard')");
-// Let's just add a call in the dashboard load
-html = html.replace(
-  `if (page === 'dashboard') { loadAgents(); loadHealthDashboard(); }`,
-  `if (page === 'dashboard') { loadAgents(); loadHealthDashboard(); loadSidebarAgents(); }`
-);
-
-writeFileSync(file, html, 'utf-8');
-console.log('Done! Sidebar restructured.');