opc-agent 1.3.2 → 1.4.0

package/docs/zh/guide/deployment.md

@@ -1,81 +1,81 @@
-# 部署指南
-
-## 本地开发
-
-```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 和安全头
-- [ ] 准备回滚方案
+# 部署指南
+
+## 本地开发
+
+```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 +1,82 @@
-# 快速开始
-
-## 安装
-
-```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 部署
+# 快速开始
+
+## 安装
+
+```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 +1,84 @@
-# 模板
-
-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();
-  }
-}
-```
+# 模板
+
+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 +1,88 @@
-# 测试
-
-## 概览
-
-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` | 响应必须在指定时间内完成 |
+# 测试
+
+## 概览
+
+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` | 响应必须在指定时间内完成 |