Update documentation for Realtime Agent Studio with enhanced content and structure

- Revised site name and description for clarity and detail. - Updated navigation structure to better reflect the organization of content. - Improved changelog entries for better readability and consistency. - Migrated assistant configuration and prompt guidelines to new documentation paths. - Enhanced core concepts section to clarify the roles and capabilities of assistants and engines. - Streamlined workflow documentation to provide clearer guidance on configuration and usage.
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
--- a/docs/content/customization/workflows.md
+++ b/docs/content/customization/workflows.md
@@ -1,53 +1,106 @@
-# 工作流管理
+# 工作流

-工作流提供可视化的对话流程编排能力，支持复杂的业务场景。
+工作流用于把复杂业务拆成明确的步骤、分支和回退策略，是 RAS 中承载流程逻辑的正式能力页。

-## 概述
+## 什么时候需要工作流

-![工作流](../images/workflows.png)
+当一个助手同时满足以下任一情况时，通常应考虑工作流，而不是继续堆叠单一提示词：

-## 节点类型
+- 需要多轮收集信息，例如订单号、手机号、预约时间等
+- 需要按意图或条件走不同分支
+- 需要串联多个工具或业务系统
+- 需要在异常或信息不足时统一回退到澄清、兜底或人工节点

-| 节点 | 图标 | 功能说明 |
-|------|------|---------|
-| **对话节点** | 💬 | AI 自动回复，可设置回复策略 |
-| **工具节点** | 🔧 | 调用外部 API 或自定义工具 |
-| **人工节点** | 👤 | 转接人工客服 |
-| **结束节点** | 🏁 | 结束对话流程 |
+## 工作流与助手的关系

-## 创建工作流
+助手负责对外表现、全局策略和渠道接入；工作流负责把某个业务流程拆成可维护的节点。

-### 步骤
+```mermaid
+flowchart LR
+    Assistant[助手] --> Workflow[工作流]
+    Workflow --> Nodes[节点与分支]
+    Nodes --> Tools[工具 / 知识库 / 人工]
+```

-1. 进入 **工作流** 页面
-2. 点击 **新建工作流**
-3. 从左侧拖拽节点到画布
-4. 连接节点建立流程
-5. 配置各节点参数
-6. 保存并发布
+这意味着：

-### 节点配置
+- 助手定义角色、提示词基线、模型和输出方式
+- 工作流定义“这类问题该按什么顺序被处理”
+- 工具和知识库作为节点可调用的能力，被有选择地暴露给流程

-#### 对话节点配置
+## 关键组成

- 回复模板
- 条件分支
- 知识库检索
+| 组成 | 作用 | 设计建议 |
+|------|------|----------|
+| **工作流名称** | 区分业务流程 | 用业务语义命名，避免过于技术化 |
+| **入口节点** | 用户进入后的第一步 | 保持单入口，便于理解和测试 |
+| **全局提示词** | 对所有节点生效的共性约束 | 保持简短，避免与节点提示词冲突 |
+| **节点提示词** | 当前节点的任务说明 | 单一职责，明确输入 / 输出 |
+| **节点工具白名单** | 控制当前节点可调用的工具集合 | 遵循最小权限原则 |
+| **超时与回退** | 异常、超时、缺信息时的处理方式 | 优先回到澄清、兜底或人工节点 |
+| **上下文透传** | 在节点之间共享状态 | 只传递后续节点真正需要的信息 |

-#### 工具节点配置
+## 常见节点类型

- 选择工具类型
- 配置输入参数
- 设置输出处理
+| 节点类型 | 适合做什么 |
+|----------|------------|
+| **路由节点** | 判断用户意图并进入不同分支 |
+| **信息收集节点** | 收集订单号、联系方式、时间等关键信息 |
+| **处理节点** | 调用工具、执行查询、计算或写入系统 |
+| **回复节点** | 组织最终答复并控制输出风格 |
+| **人工节点** | 转接人工、排队或发起通知 |
+| **结束节点** | 输出结束语并关闭流程 |

-#### 人工节点配置
+## 推荐编排步骤

- 转接规则
- 排队策略
- 通知设置
+1. 先写清楚流程目标：这条工作流要解决哪一类业务问题
+2. 画出最小节点图：入口、关键分支、结束和兜底
+3. 为每个节点定义唯一职责和输入 / 输出
+4. 再绑定知识库、工具和回退策略
+5. 在测试面板或流程调试工具中验证每条主路径和异常路径

-## 流程测试
+## 配置示例

- 支持单步调试
- 可查看执行日志
- 实时验证流程逻辑
+```yaml
+workflow:
+  name: "订单咨询流程"
+  entry: "intent_router"
+  global_prompt: "优先给出可执行步骤，必要时先澄清信息。"
+  nodes:
+    - id: "intent_router"
+      type: "router"
+      prompt: "识别用户意图：查订单、退款、投诉"
+      next:
+        - when: "intent == query_order"
+          to: "collect_order_id"
+        - when: "intent == refund"
+          to: "refund_policy"
+    - id: "collect_order_id"
+      type: "collect"
+      prompt: "请用户提供订单号"
+      tools: ["query_order"]
+      fallback: "human_handoff"
+    - id: "human_handoff"
+      type: "end"
+      prompt: "转人工处理"
+```
+
+## 设计建议
+
+- **让每个节点只做一件事**：避免单节点同时负责路由、收集信息和最终回复
+- **工具按节点授权**：不要把所有工具暴露给整条流程中的每个节点
+- **把失败路径设计出来**：超时、无结果、参数缺失都应该有明确回退
+- **优先传状态，不传长文本**：节点之间共享必要结构化信息，比传递大段自然语言更稳
+- **为流程保留可观测性**：每条主路径都应能在调试时解释“为什么走到这里”
+
+## 当前边界
+
+- 文档不会完整覆盖所有表达式或节点字段的最终 Schema
+- 不同执行引擎下，可用节点字段和运行行为可能存在差异
+- 可视化编排与底层字段映射可能不会一一对应
+
+## 相关文档
+
+- [助手概念](../concepts/assistants.md) - 工作流在助手体系中的位置
+- [工具](tools.md) - 设计可被流程安全调用的工具
+- [知识库](knowledge-base.md) - 让流程中的节点使用 RAG 能力