opc-agent 1.1.0 → 1.1.2

package/docs/zh/guide/concepts.md

@@ -1,28 +1,104 @@
-# 核心概念
-
-## OAD（Open Agent Definition）
-
-OAD 是智能体的声明式定义文件，使用 YAML 格式。包含：
-
-- **metadata** — 名称、版本、描述
-- **spec** — 模型、系统提示词、技能、渠道、记忆、DTV
-
-## 技能（Skills）
-
-技能是智能体的能力模块，每个技能处理特定类型的用户请求。
-
-## 渠道（Channels）
-
-渠道定义智能体与用户交互的方式：Web、Telegram、Slack、微信等。
-
-## DTV（Data-Trust-Value）
-
-DTV 框架确保智能体的数据安全、信任级别和价值追踪。
-
-## 测试
-
-在 OAD 中定义测试用例，使用 `opc test` 运行自动化测试。
-
-## 缓存与限流
-
-内置 LLM 响应缓存和多级限流，降低 API 成本，保护服务稳定性。
+# 核心概念
+
+## 智能体 (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,39 +1,135 @@
-# 配置
-
-详细配置说明请参考 [英文版](/guide/configuration)。
-
-## 限流配置
-
-```yaml
-spec:
-  rateLimits:
-    perUser:
-      maxRequests: 60
-      windowMs: 60000
-    perProvider:
-      maxRequests: 100
-      windowMs: 60000
-```
-
-## 缓存配置
-
-```yaml
-spec:
-  cache:
-    enabled: true
-    ttlMs: 3600000
-    maxEntries: 1000
-```
-
-## 测试配置
-
-```yaml
-spec:
-  testing:
-    cases:
-      - name: 问候测试
-        input: "你好"
-        expect:
-          contains: ["你好", "帮"]
-          maxLatencyMs: 5000
-```
+# 配置详解
+
+## 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,3 +1,81 @@
-# 部署
-
-详细说明请参考 [英文版](/guide/deployment)。
+# 部署指南
+
+## 本地开发
+
+```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,58 +1,82 @@
-# 快速开始
-
-## 安装
-
-```bash
-npm install -g opc-agent
-```
-
-## 创建项目
-
-```bash
-opc init my-agent
-cd my-agent
-```
-
-## 配置
-
-编辑 `.env` 文件，设置 API 密钥：
-
-```bash
-OPC_LLM_API_KEY=your-api-key
-OPC_LLM_BASE_URL=https://api.openai.com/v1
-OPC_LLM_MODEL=gpt-4o-mini
-```
-
-## 启动
-
-```bash
-# Web 服务器模式
-opc run
-
-# CLI 对话模式
-opc chat
-```
-
-## 测试
-
-```bash
-opc test
-```
-
-## 查看分析
-
-```bash
-opc analytics
-```
-
-## 模板
-
-使用 `-t` 指定模板：
-
-```bash
-opc init my-bot -t teacher
-opc init my-bot -t data-analyst
-opc init my-bot -t sales-assistant
-```
-
-共 13 个内置模板可选。
+# 快速开始
+
+## 安装
+
+```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,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` | 教师 — 课程计划 + 测验 |
-
-```bash
-opc init my-agent -t 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 --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();
+  }
+}
+```