opc-agent 1.0.0 → 1.1.1

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

@@ -6,53 +6,77 @@
 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 密钥：
+编辑 `.env` 文件，填入你的大语言模型 API Key：
 
 ```bash
 OPC_LLM_API_KEY=your-api-key
-OPC_LLM_BASE_URL=https://api.openai.com/v1
-OPC_LLM_MODEL=gpt-4o-mini
+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 服务器模式
+# 启动 Web 对话服务
 opc run
 
-# CLI 对话模式
+# 或者用命令行对话
 opc chat
+
+# 开发模式（改代码自动重启）
+opc dev
 ```
 
-## 测试
+访问 `http://localhost:3000` 即可看到对话界面。
+
+## 校验配置
 
 ```bash
-opc test
+opc build
 ```
 
-## 查看分析
+## 运行测试
 
 ```bash
-opc analytics
+opc test
 ```
 
-## 模板
-
-使用 `-t` 指定模板：
+## 查看数据分析
 
 ```bash
-opc init my-bot -t teacher
-opc init my-bot -t data-analyst
-opc init my-bot -t sales-assistant
+opc analytics
 ```
 
-共 13 个内置模板可选。
+## 下一步
+
+- [核心概念](/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,22 +1,84 @@
 # 模板
 
-OPC Agent 内置 13 个模板：
-
-| 模板 | 说明 |
-|------|------|
-| `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` | 教师 — 课程计划 + 测验 |
+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 -t teacher
+# 创建时指定模板
+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,18 +1,88 @@
 # 测试
 
-详细说明请参考 [英文版](/guide/testing)。
+## 概览
+
+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
 ```
 
-## 部署
+## 测试报告
 
-```bash
-opc deploy --target openclaw
-opc deploy --target hermes
 ```
+═══════════════════════════════════════════
+  OPC Agent 测试报告
+═══════════════════════════════════════════
+
+  ✔ [通过] 问候测试 (245ms)
+  ✔ [通过] 产品咨询 (312ms)
+  ✘ [失败] 空输入 (5120ms)
+      → 延迟 5120ms 超过上限 2000ms
+
+───────────────────────────────────────────
+  总计: 3  通过: 2  失败: 1  耗时: 5677ms
+───────────────────────────────────────────
+```
+
+## 断言类型
+
+| 断言 | 说明 |
+|------|------|
+| `contains` | 回复必须包含这些字符串（不区分大小写） |
+| `notContains` | 回复不能包含这些字符串 |
+| `toolCalled` | 指定的工具必须被调用 |
+| `maxLatencyMs` | 响应必须在指定时间内完成 |

package/docs/zh/index.md

@@ -3,7 +3,7 @@ layout: home
 hero:
   name: OPC Agent
   text: 开放智能体框架
-  tagline: 构建、测试、运行面向业务工作站的 AI 智能体
+  tagline: 构建、测试、运行企业级 AI 智能体
   actions:
     - theme: brand
       text: 快速开始
@@ -12,16 +12,16 @@ hero:
       text: GitHub
       link: https://github.com/Deepleaper/opc-agent
 features:
-  - title: 🚀 快速开始
-    details: 2 分钟内创建智能体，内置 13 个模板
-  - title: 📝 OAD Schema
-    details: 基于 YAML 的声明式智能体定义
-  - title: 🔌 多渠道
-    details: Web、Telegram、Slack、微信、邮件、语音、WebSocket
-  - title: 🧪 测试框架
-    details: 在 OAD 中定义测试用例，opc test 运行
-  - title: 📊 分析
-    details: 跟踪消息、LLM 调用、工具使用和错误
-  - title: 🌍 国际化
-    details: 内置英文、中文、日文支持
+  - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opc-agent",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/channels/discord.ts

@@ -0,0 +1,192 @@
+import { BaseChannel } from './index';
+import type { Message } from '../core/types';
+
+/**
+ * Discord Channel — v1.1.0
+ *
+ * Supports:
+ * - Discord Bot via Gateway (WebSocket) or HTTP interactions
+ * - Slash commands, message content intent
+ * - Thread-based conversations
+ * - Reactions, embeds
+ *
+ * Env vars:
+ *   DISCORD_BOT_TOKEN — bot token
+ *   DISCORD_APPLICATION_ID — application ID for slash commands
+ */
+
+export interface DiscordChannelConfig {
+  /** Bot token */
+  botToken?: string;
+  /** Application ID */
+  applicationId?: string;
+  /** Guild IDs to register slash commands (empty = global) */
+  guildIds?: string[];
+  /** Whether to use threads for conversations */
+  useThreads?: boolean;
+}
+
+export class DiscordChannel extends BaseChannel {
+  readonly type = 'discord';
+  private config: DiscordChannelConfig;
+  private ws: import('ws').WebSocket | null = null;
+  private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+  private sequenceNumber: number | null = null;
+  private sessionId: string | null = null;
+  private resumeUrl: string | null = null;
+
+  constructor(config: DiscordChannelConfig = {}) {
+    super();
+    this.config = {
+      botToken: config.botToken ?? process.env.DISCORD_BOT_TOKEN ?? '',
+      applicationId: config.applicationId ?? process.env.DISCORD_APPLICATION_ID ?? '',
+      guildIds: config.guildIds ?? [],
+      useThreads: config.useThreads ?? true,
+    };
+  }
+
+  async start(): Promise<void> {
+    if (!this.config.botToken) {
+      console.warn('[DiscordChannel] No bot token. Set DISCORD_BOT_TOKEN.');
+      return;
+    }
+
+    // Get gateway URL
+    const gatewayResp = await fetch('https://discord.com/api/v10/gateway/bot', {
+      headers: { Authorization: `Bot ${this.config.botToken}` },
+    });
+    const gatewayData = await gatewayResp.json() as { url: string };
+    const wsUrl = `${gatewayData.url}?v=10&encoding=json`;
+
+    const { WebSocket } = await import('ws');
+    this.ws = new WebSocket(wsUrl);
+
+    this.ws.on('message', async (data: Buffer) => {
+      const payload = JSON.parse(data.toString());
+      this.sequenceNumber = payload.s ?? this.sequenceNumber;
+
+      switch (payload.op) {
+        case 10: // Hello
+          this.startHeartbeat(payload.d.heartbeat_interval);
+          this.identify();
+          break;
+        case 11: // Heartbeat ACK
+          break;
+        case 0: // Dispatch
+          if (payload.t === 'READY') {
+            this.sessionId = payload.d.session_id;
+            this.resumeUrl = payload.d.resume_gateway_url;
+            console.log(`[DiscordChannel] Connected as ${payload.d.user.username}`);
+          } else if (payload.t === 'MESSAGE_CREATE') {
+            await this.handleMessage(payload.d);
+          }
+          break;
+      }
+    });
+
+    this.ws.on('close', (code: number) => {
+      console.log(`[DiscordChannel] WebSocket closed: ${code}`);
+      this.stopHeartbeat();
+      // Auto-reconnect after 5s for resumable codes
+      if (code !== 4004 && code !== 4014) {
+        setTimeout(() => this.start(), 5000);
+      }
+    });
+
+    this.ws.on('error', (err: Error) => {
+      console.error('[DiscordChannel] WebSocket error:', err.message);
+    });
+  }
+
+  async stop(): Promise<void> {
+    this.stopHeartbeat();
+    if (this.ws) {
+      this.ws.close(1000);
+      this.ws = null;
+    }
+  }
+
+  private identify(): void {
+    this.ws?.send(JSON.stringify({
+      op: 2,
+      d: {
+        token: this.config.botToken,
+        intents: (1 << 9) | (1 << 15), // GUILD_MESSAGES | MESSAGE_CONTENT
+        properties: {
+          os: process.platform,
+          browser: 'opc-agent',
+          device: 'opc-agent',
+        },
+      },
+    }));
+  }
+
+  private startHeartbeat(intervalMs: number): void {
+    this.stopHeartbeat();
+    // Send first heartbeat with jitter
+    setTimeout(() => {
+      this.sendHeartbeat();
+      this.heartbeatInterval = setInterval(() => this.sendHeartbeat(), intervalMs);
+    }, intervalMs * Math.random());
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  private sendHeartbeat(): void {
+    this.ws?.send(JSON.stringify({ op: 1, d: this.sequenceNumber }));
+  }
+
+  private async handleMessage(d: Record<string, unknown>): Promise<void> {
+    // Ignore bot messages
+    const author = d.author as Record<string, unknown>;
+    if (author?.bot) return;
+    if (!d.content || !this.handler) return;
+
+    const msg: Message = {
+      id: `discord_${d.id}`,
+      role: 'user',
+      content: d.content as string,
+      timestamp: new Date(d.timestamp as string).getTime(),
+      metadata: {
+        sessionId: `discord_${d.channel_id}`,
+        chatId: d.channel_id as string,
+        userId: author.id as string,
+        platform: 'discord',
+        guildId: d.guild_id as string | undefined,
+        threadId: (d as Record<string, unknown>).thread?.toString(),
+      },
+    };
+
+    const response = await this.handler(msg);
+    await this.sendMessage(d.channel_id as string, response.content);
+  }
+
+  async sendMessage(channelId: string, content: string): Promise<void> {
+    // Discord max message length is 2000
+    const chunks = this.splitMessage(content, 2000);
+    for (const chunk of chunks) {
+      await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bot ${this.config.botToken}`,
+        },
+        body: JSON.stringify({ content: chunk }),
+      });
+    }
+  }
+
+  private splitMessage(text: string, maxLen: number): string[] {
+    if (text.length <= maxLen) return [text];
+    const parts: string[] = [];
+    for (let i = 0; i < text.length; i += maxLen) {
+      parts.push(text.slice(i, i + maxLen));
+    }
+    return parts;
+  }
+}