opc-agent 1.3.2 → 1.4.0

package/docs/zh/api/sdk.md

@@ -1,102 +1,102 @@
-# SDK 参考
-
-## 核心类
-
-### AgentRuntime — 智能体运行时
-
-```typescript
-import { AgentRuntime } from 'opc-agent';
-
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');   // 加载 OAD 配置
-const agent = await runtime.initialize(); // 初始化智能体
-await runtime.start();                    // 启动服务
-```
-
-### AnalyticsEngine — 分析引擎
-
-```typescript
-import { AnalyticsEngine } from 'opc-agent';
-
-const engine = new AnalyticsEngine('.');
-engine.trackMessage('user-1', 250, 100, 50);  // 追踪消息
-engine.trackToolUse('search', true, 120);       // 追踪工具调用
-const stats = engine.getStats();                // 获取统计数据
-```
-
-### RateLimiter — 限流器
-
-```typescript
-import { RateLimiter } from 'opc-agent';
-
-const limiter = new RateLimiter({
-  userLimit: { maxRequests: 60, windowMs: 60000 },
-  providerLimit: { maxRequests: 100, windowMs: 60000 },
-});
-
-await limiter.acquire('user-1', 'openai'); // 获取令牌，超限时抛出异常
-```
-
-### LLMCache — LLM 响应缓存
-
-```typescript
-import { LLMCache } from 'opc-agent';
-
-const cache = new LLMCache({ ttlMs: 3600000 }); // 1 小时过期
-const key = LLMCache.makeKey(messages, systemPrompt);
-const cached = cache.get(key);
-if (!cached) {
-  const response = await callLLM(messages);
-  cache.set(key, response);
-}
-```
-
-### KnowledgeBase — 知识库
-
-```typescript
-import { KnowledgeBase } from 'opc-agent';
-
-const kb = new KnowledgeBase('./docs');
-await kb.addFile('产品手册.pdf');    // 添加文件
-await kb.addFile('FAQ.md');
-const results = await kb.search('退货政策'); // 语义搜索
-```
-
-### Orchestrator — 多智能体编排
-
-```typescript
-import { Orchestrator } from 'opc-agent';
-
-const orchestrator = new Orchestrator({
-  agents: [triageAgent, salesAgent, supportAgent],
-  strategy: 'route-by-intent', // 按意图路由
-});
-
-const response = await orchestrator.handle(message);
-```
-
-### Testing — 测试工具
-
-```typescript
-import { runTests, formatReport } from 'opc-agent';
-
-const report = await runTests('oad.yaml');
-console.log(formatReport(report));
-```
-
-## 模板列表
-
-| 模板 | 说明 |
-|------|------|
-| `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` | 教学：课程 + 出题 |
+# SDK 参考
+
+## 核心类
+
+### AgentRuntime — 智能体运行时
+
+```typescript
+import { AgentRuntime } from 'opc-agent';
+
+const runtime = new AgentRuntime();
+await runtime.loadConfig('oad.yaml');   // 加载 OAD 配置
+const agent = await runtime.initialize(); // 初始化智能体
+await runtime.start();                    // 启动服务
+```
+
+### AnalyticsEngine — 分析引擎
+
+```typescript
+import { AnalyticsEngine } from 'opc-agent';
+
+const engine = new AnalyticsEngine('.');
+engine.trackMessage('user-1', 250, 100, 50);  // 追踪消息
+engine.trackToolUse('search', true, 120);       // 追踪工具调用
+const stats = engine.getStats();                // 获取统计数据
+```
+
+### RateLimiter — 限流器
+
+```typescript
+import { RateLimiter } from 'opc-agent';
+
+const limiter = new RateLimiter({
+  userLimit: { maxRequests: 60, windowMs: 60000 },
+  providerLimit: { maxRequests: 100, windowMs: 60000 },
+});
+
+await limiter.acquire('user-1', 'openai'); // 获取令牌，超限时抛出异常
+```
+
+### LLMCache — LLM 响应缓存
+
+```typescript
+import { LLMCache } from 'opc-agent';
+
+const cache = new LLMCache({ ttlMs: 3600000 }); // 1 小时过期
+const key = LLMCache.makeKey(messages, systemPrompt);
+const cached = cache.get(key);
+if (!cached) {
+  const response = await callLLM(messages);
+  cache.set(key, response);
+}
+```
+
+### KnowledgeBase — 知识库
+
+```typescript
+import { KnowledgeBase } from 'opc-agent';
+
+const kb = new KnowledgeBase('./docs');
+await kb.addFile('产品手册.pdf');    // 添加文件
+await kb.addFile('FAQ.md');
+const results = await kb.search('退货政策'); // 语义搜索
+```
+
+### Orchestrator — 多智能体编排
+
+```typescript
+import { Orchestrator } from 'opc-agent';
+
+const orchestrator = new Orchestrator({
+  agents: [triageAgent, salesAgent, supportAgent],
+  strategy: 'route-by-intent', // 按意图路由
+});
+
+const response = await orchestrator.handle(message);
+```
+
+### Testing — 测试工具
+
+```typescript
+import { runTests, formatReport } from 'opc-agent';
+
+const report = await runTests('oad.yaml');
+console.log(formatReport(report));
+```
+
+## 模板列表
+
+| 模板 | 说明 |
+|------|------|
+| `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` | 教学：课程 + 出题 |

package/docs/zh/guide/concepts.md

@@ -1,104 +1,104 @@
-# 核心概念
-
-## 智能体 (Agent)
-
-智能体是一个有完整生命周期的 AI 实体：
-
-```
-初始化 (init) → 就绪 (ready) → 运行中 (running) → 已停止 (stopped)
-```
-
-每个智能体有以下属性：
-- **名称** — 唯一标识符
-- **系统提示词** — 定义智能体的角色和行为
-- **技能** — 智能体能做的事（如 FAQ 查询、转人工）
-- **渠道** — 用户和智能体交互的方式（如 Web、Telegram）
-- **记忆** — 对话历史和长期知识
-
-## OAD (Open Agent Definition)
-
-OAD 是智能体的声明式定义格式，用 YAML 编写。一个 OAD 文件就是一个完整的智能体定义。
-
-```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: my-agent
-  version: 1.0.0
-spec:
-  provider:
-    default: deepseek
-  model: deepseek-chat
-  systemPrompt: "你是一个专业的客服助手。"
-  skills: [...]
-  channels: [...]
-```
-
-这个设计理念参考了 Kubernetes 的资源定义：声明你想要的状态，框架帮你实现。
-
-## 技能 (Skill)
-
-技能是智能体的模块化能力。每个技能：
-- 有 `name` 和 `description`
-- 接收对话上下文和当前消息
-- 返回是否处理了这条消息，以及置信度
-
-内置技能包括：
-- **FAQ 查询** — 从预设问答库匹配答案
-- **人工转接** — 置信度低时转给人工客服
-- **知识库检索** — 从文档中语义搜索相关内容
-
-你也可以继承 `BaseSkill` 实现自定义技能。
-
-## 渠道 (Channel)
-
-渠道是用户和智能体交互的接口：
-
-| 渠道 | 说明 |
-|------|------|
-| **Web** | HTTP API + SSE 流式响应，自带对话 UI |
-| **WebSocket** | 实时双向通信 + 广播 |
-| **Telegram** | Telegram Bot API Webhook |
-| **Slack** | Slack 应用集成 |
-| **微信** | 微信公众号消息处理 |
-| **飞书** | 飞书机器人 |
-| **邮件** | 邮件收发 |
-| **语音** | 语音识别（STT）+ 语音合成（TTS） |
-| **Webhook** | 接收外部系统回调 |
-
-## 记忆 (Memory)
-
-智能体有两种记忆：
-
-- **短期记忆** — 单次会话内的对话历史，会话结束即清除
-- **长期记忆** — 跨会话的持久化知识，支持 DeepBrain 语义搜索
-
-```yaml
-spec:
-  memory:
-    shortTerm: true       # 开启对话上下文
-    longTerm: true        # 开启长期记忆
-    provider: deepbrain   # 长期记忆后端
-```
-
-## DTV 框架 (Data / Trust / Value)
-
-DTV 框架管理智能体的数据访问、信任等级和价值度量：
-
-### 数据 (Data)
-智能体对业务数据的只读访问。可以读取配置，但不能修改源系统。
-
-### 信任 (Trust)
-渐进式信任等级控制智能体的能力范围：
-
-| 等级 | 说明 |
-|------|------|
-| `sandbox` | 沙箱模式，无网络访问，能力受限 |
-| `verified` | 身份已验证，基础能力 |
-| `certified` | 通过安全审计，完整能力 |
-| `listed` | 已发布到 OPC 市场 |
-
-### 价值 (Value)
-性能和 ROI 指标追踪：
-- 响应时间、满意度评分、解决率
-- 自动化报表和仪表盘
+# 核心概念
+
+## 智能体 (Agent)
+
+智能体是一个有完整生命周期的 AI 实体：
+
+```
+初始化 (init) → 就绪 (ready) → 运行中 (running) → 已停止 (stopped)
+```
+
+每个智能体有以下属性：
+- **名称** — 唯一标识符
+- **系统提示词** — 定义智能体的角色和行为
+- **技能** — 智能体能做的事（如 FAQ 查询、转人工）
+- **渠道** — 用户和智能体交互的方式（如 Web、Telegram）
+- **记忆** — 对话历史和长期知识
+
+## OAD (Open Agent Definition)
+
+OAD 是智能体的声明式定义格式，用 YAML 编写。一个 OAD 文件就是一个完整的智能体定义。
+
+```yaml
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: my-agent
+  version: 1.0.0
+spec:
+  provider:
+    default: deepseek
+  model: deepseek-chat
+  systemPrompt: "你是一个专业的客服助手。"
+  skills: [...]
+  channels: [...]
+```
+
+这个设计理念参考了 Kubernetes 的资源定义：声明你想要的状态，框架帮你实现。
+
+## 技能 (Skill)
+
+技能是智能体的模块化能力。每个技能：
+- 有 `name` 和 `description`
+- 接收对话上下文和当前消息
+- 返回是否处理了这条消息，以及置信度
+
+内置技能包括：
+- **FAQ 查询** — 从预设问答库匹配答案
+- **人工转接** — 置信度低时转给人工客服
+- **知识库检索** — 从文档中语义搜索相关内容
+
+你也可以继承 `BaseSkill` 实现自定义技能。
+
+## 渠道 (Channel)
+
+渠道是用户和智能体交互的接口：
+
+| 渠道 | 说明 |
+|------|------|
+| **Web** | HTTP API + SSE 流式响应，自带对话 UI |
+| **WebSocket** | 实时双向通信 + 广播 |
+| **Telegram** | Telegram Bot API Webhook |
+| **Slack** | Slack 应用集成 |
+| **微信** | 微信公众号消息处理 |
+| **飞书** | 飞书机器人 |
+| **邮件** | 邮件收发 |
+| **语音** | 语音识别（STT）+ 语音合成（TTS） |
+| **Webhook** | 接收外部系统回调 |
+
+## 记忆 (Memory)
+
+智能体有两种记忆：
+
+- **短期记忆** — 单次会话内的对话历史，会话结束即清除
+- **长期记忆** — 跨会话的持久化知识，支持 DeepBrain 语义搜索
+
+```yaml
+spec:
+  memory:
+    shortTerm: true       # 开启对话上下文
+    longTerm: true        # 开启长期记忆
+    provider: deepbrain   # 长期记忆后端
+```
+
+## DTV 框架 (Data / Trust / Value)
+
+DTV 框架管理智能体的数据访问、信任等级和价值度量：
+
+### 数据 (Data)
+智能体对业务数据的只读访问。可以读取配置，但不能修改源系统。
+
+### 信任 (Trust)
+渐进式信任等级控制智能体的能力范围：
+
+| 等级 | 说明 |
+|------|------|
+| `sandbox` | 沙箱模式，无网络访问，能力受限 |
+| `verified` | 身份已验证，基础能力 |
+| `certified` | 通过安全审计，完整能力 |
+| `listed` | 已发布到 OPC 市场 |
+
+### 价值 (Value)
+性能和 ROI 指标追踪：
+- 响应时间、满意度评分、解决率
+- 自动化报表和仪表盘

package/docs/zh/guide/configuration.md

@@ -1,135 +1,135 @@
-# 配置详解
-
-## 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]
-```
+# 配置详解
+
+## 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]
+```