wx44wx/AI-VideoAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for Realtime Agent Studio with enhanced content and structure

Browse Source 
- 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.
This commit is contained in:
Xin Wang
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/content/customization/asr.md
View File

@@ -1,24 +1,31 @@
# 语音识别
# 语音识别
语音识别（ASR）负责将用户音频实时转写为文本，供对话引擎理解。
语音识别（ASR）负责把用户音频实时转写成文本，供引擎继续理解和处理。
## 配置项
## 关键配置项
| 配置项 | 说明 |
|---|---|
| ASR 引擎 | 选择语音识别服务提供商 |
| 模型 | 识别模型名称 |
| 语言 | 中文/英文/多语言 |
| 热词 | 提升特定词汇识别准确率 |
| 标点与规范化 | 是否自动补全标点、文本规范化 |
|--------|------|
| **ASR 引擎** | 选择语音识别服务提供商或自建服务 |
| **模型** | 实际使用的识别模型名称 |
| **语言** | 中文、英文或多语言 |
| **热词** | 提高业务词汇、品牌词、专有名词识别率 |
| **标点与规范化** | 自动补全标点、规范数字和日期等 |
## 建议
## 选择建议
- 客服场景建议开启热词并维护业务词表
- 多语言场景建议按会话入口显式指定语言
- 对延迟敏感场景优先选择流式识别模型
- 客服、外呼等业务场景建议维护热词表，并按业务线持续更新
- 多语言入口建议显式指定语言，避免模型自动判断带来的波动
- 对延迟敏感的场景优先选择流式识别模型
- 对准确率敏感的场景，先评估专有名词、数字、地址等样本的识别表现
## 运行建议
- 使用与接入端一致的采样率和编码方式，减少额外转换
- 在测试阶段准备固定样本，便于对比不同模型或参数的变化
- 把“识别准确率”和“识别延迟”一起看，不要只看其中一项
## 相关文档
- [语音配置总览](voices.md)
- [声音资源](voices.md) - 完整语音输入输出链路中的 TTS 侧配置
- [快速开始](../quickstart/index.md) - 以任务路径接入第一个 ASR 资源

107
docs/content/customization/knowledge-base.md
View File

@@ -1,53 +1,86 @@
# 知识库
# 知识库
知识库基于 RAG（检索增强生成）技术，让 AI 能够回答私有领域问题。
知识库负责承载助手需要引用的私有事实、业务资料和长文档内容，是 RAG（检索增强生成）能力的正式说明页。
## 概述
## 什么时候应该用知识库
![知识库](../images/knowledge.png)
当问题答案主要来自“稳定文档”而不是实时外部动作时，优先使用知识库：
## 创建知识库
- 产品说明、政策条款、操作流程、培训材料
- 内部手册、FAQ、规范文档
- 需要被多位助手复用的领域知识
### 步骤
如果任务本质上是“查状态、写数据、执行动作”，那通常更适合 [工具](tools.md)，而不是知识库。
1. 进入 **知识库** 页面
2. 点击 **新建知识库**
3. 填写知识库名称
4. 上传文档
## 工作原理
### 支持格式
```mermaid
flowchart LR
subgraph Indexing["索引阶段"]
Doc[文档] --> Chunk[分块]
Chunk --> Embed[向量化]
Embed --> Store[(向量数据库)]
end
| 格式 | 说明 |
|------|------|
| Markdown | 最佳选择，格式清晰 |
| PDF | 自动提取文本 |
| TXT | 纯文本支持 |
| Word | 需转换为其他格式 |
subgraph Query["查询阶段"]
Q[用户问题] --> Search[相似度检索]
Store --> Search
Search --> Context[相关片段]
Context --> LLM[LLM 生成回答]
end
```
### 文档上传
核心原则很简单：把长文档转成可检索的片段，在用户提问时只把最相关的内容送给模型。
- 拖拽上传或点击选择
- 单文件大小限制 10MB
- 建议单文档不超过 50000 字
## 适合放进知识库的内容
## 配置检索参数
| 适合 | 不适合 |
|------|--------|
| 稳定规则、标准答案、产品文档 | 高频变化的实时状态 |
| 领域术语、说明手册、培训材料 | 需要外部系统写入或变更的动作 |
| 需要跨助手复用的内容 | 只在单次会话里临时生成的数据 |
| 参数 | 说明 | 默认值 |
|------|------|--------|
| 相似度阈值 | 低于此分数的结果不返回 | 0.7 |
| 返回数量 | 单次检索返回的结果数 | 3 |
| 分块大小 | 文档分块的最大长度 | 500 |
## 内容准备建议
## 管理知识库
- 优先上传结构清晰、主题明确的文档
- 对超长文档按主题拆分，减少一次索引的噪声
- 标题、章节名和表格说明对召回质量很重要，不要全部删掉格式信息
- 与其堆很多相近文档，不如先清理重复、过期和相互冲突的内容
- **查看文档** - 浏览已上传的文件
- **删除文档** - 移除不需要的内容
- **更新文档** - 重新上传覆盖
- **测试检索** - 验证知识库效果
## 常见配置项
## 关联助手
| 配置项 | 作用 | 常见做法 |
|--------|------|----------|
| **相似度阈值** | 过滤弱相关结果 | 从保守值起步，再按误召回调 |
| **返回数量** | 控制一次送给模型的候选片段数 | 先少后多，避免上下文污染 |
| **分块大小** | 决定每个文档片段的长度 | 按文档类型和问题粒度调整 |
在助手配置的 **知识** 标签页中：
1. 选择要关联的知识库
2. 设置检索策略
3. 保存配置
## 创建与维护
### 最小流程
1. 新建知识库
2. 上传文档
3. 完成索引
4. 用典型问题测试召回结果
5. 绑定到目标助手
### 日常维护
- 删除过期或互相矛盾的文档
- 当业务口径变化时，优先更新知识库而不是只改提示词
- 为关键问题准备固定测试问句，观察召回是否稳定
## 与助手的关系
知识库不是独立产品入口，而是助手的能力层：
- 助手决定是否、何时、以什么风格使用知识
- 知识库决定能够提供哪些事实片段
- 工作流和工具可以与知识库并用，但承担不同职责
## 相关文档
- [助手概念](../concepts/assistants.md) - 知识库在助手能力层中的位置
- [LLM 模型](models.md) - 为知识库准备嵌入或重排模型
- [工具](tools.md) - 当任务需要执行动作时，优先考虑工具而不是知识库

75
docs/content/customization/models.md
View File

@@ -1,44 +1,53 @@
# 模型配置
# LLM 模型
## LLM 模型库
本页是资源库中 LLM 模型的正式说明页，聚焦文本生成、嵌入和重排模型的接入与选择。
![LLM模型库](../images/llms.png)
## 这页负责什么
### 支持的模型
当你需要为助手配置“理解与生成能力”时，请从这里开始决定：
| 供应商 | 模型 | 特点 |
- 使用哪个供应商或模型家族
- 该模型负责文本生成、嵌入还是重排
- 接口地址、认证信息和默认参数如何设置
语音识别和语音合成分别由 [语音识别](asr.md) 与 [声音资源](voices.md) 说明，不在本页重复。
## 模型类型
| 类型 | 用途 | 常见场景 |
|------|------|----------|
| **文本模型** | 生成回复、总结、分类、规划 | 助手主对话、工具调用决策 |
| **嵌入模型** | 向量化文档或查询 | 知识库检索 |
| **重排模型** | 对检索结果再次排序 | 提升知识召回质量 |
## 配置清单
| 配置项 | 说明 | 建议 |
|--------|------|------|
| **OpenAI** | GPT-4 / GPT-3.5 | 通用能力强 |
| **DeepSeek** | DeepSeek Chat | 高性价比 |
| **SiliconFlow** | 多种开源模型 | 本地部署友好 |
| **Google** | Gemini Pro | 多模态支持 |
| **供应商** | OpenAI 兼容、托管平台或自建服务 | 用统一命名规范区分环境 |
| **模型名称** | 控制台中的显示名称 | 体现厂商、用途和环境 |
| **模型标识** | 请求中实际使用的 model 名称 | 保持与供应商文档一致 |
| **Base URL** | 接口地址 | 为不同环境分别配置 |
| **API Key / Token** | 鉴权凭证 | 与显示名称配套管理 |
| **默认参数** | Temperature、Max Tokens、上下文长度等 | 按业务场景收敛默认值 |
### 配置步骤
## 选择建议
1. 进入 **LLM 库** 页面
2. 点击 **添加模型**
3. 选择供应商
4. 填写 API Key 和 Endpoint
5. 设置默认参数
- **先按用途选模型，再按成本和延迟筛选供应商**
- **文本模型不要承担知识库检索职责**：检索应交给嵌入与重排模型
- **为不同环境建立清晰命名**：如 `prod-gpt4o-mini`、`staging-qwen-text`
- **默认参数要保守**：让助手默认稳定，再在单个场景内按需调优
### 参数说明
## 常见组合
| 参数 | 说明 | 建议值 |
|------|------|--------|
| Temperature | 随机性 | 0.7 |
| Max Tokens | 最大输出长度 | 2048 |
| Top P | 核采样 | 0.9 |
| 目标 | 推荐组合 |
|------|----------|
| **通用对话助手** | 1 个文本模型 |
| **知识问答助手** | 文本模型 + 嵌入模型 |
| **高质量知识召回** | 文本模型 + 嵌入模型 + 重排模型 |
## ASR 语音识别
## 下一步
### 支持引擎
- **Whisper** - OpenAI 通用语音识别
- **SenseVoice** - 高精度中文语音识别
### 配置方法
1. 进入 **ASR 库** 页面
2. 选择识别引擎
3. 配置音频参数（采样率、编码）
4. 测试识别效果
- [语音识别](asr.md) - 为语音输入选择 ASR
- [声音资源](voices.md) - 为语音输出准备 TTS 资源
- [知识库](knowledge-base.md) - 把嵌入 / 重排模型接入 RAG 链路

257
docs/content/customization/tools.md
View File

@@ -1,38 +1,60 @@
# 工具集成
# 工具
工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
工具让助手从“会回答”扩展成“能执行动作”。本页是工具能力的正式说明页。
## 概述
## 什么时候应该用工具
工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
当用户请求需要依赖外部系统、实时数据或执行某个动作时，应该使用工具，而不是只靠提示词或知识库。
## 内置工具
典型场景包括：
| 工具 | 说明 | 参数 |
|------|------|------|
| `search` | 网络搜索 | query: 搜索关键词 |
| `weather` | 天气查询 | city: 城市名称 |
| `calculator` | 数学计算 | expression: 计算表达式 |
| `knowledge` | 知识库检索 | query: 查询内容 |
- 查询订单、库存、物流、天气等实时信息
- 创建预约、提交表单、写入业务系统
- 获取客户端环境能力，如定位、相机、权限确认
### 启用内置工具
如果问题本质上是“查阅稳定资料”，优先用 [知识库](knowledge-base.md)；如果问题是“执行动作或读写实时状态”，优先用工具。
在助手配置的 **工具** 标签页：
## 工具类型
1. 勾选需要启用的工具
2. 配置工具参数（如有）
3. 保存配置
| 类型 | 说明 | 常见场景 |
|------|------|----------|
| **Webhook 工具** | 调用外部 HTTP API | 订单查询、CRM 写入、预约服务 |
| **客户端工具** | 由接入端在本地执行 | 获取定位、打开相机、请求用户授权 |
| **内建工具** | 平台或运行时直接提供 | 搜索、计算、知识检索等 |
## 自定义工具
## 工具调用的基本过程
支持通过 HTTP 回调实现自定义工具。
```mermaid
sequenceDiagram
participant User as 用户
participant Assistant as 助手 / 模型
participant Tool as 工具
### 定义工具
User->>Assistant: 发起请求
Assistant->>Assistant: 判断是否需要工具
Assistant->>Tool: 发起工具调用
Tool-->>Assistant: 返回结构化结果
Assistant->>User: 组织最终回复
```
关键点不是“模型会不会调用工具”，而是“工具的定义是否足够清晰，能让模型在正确时机调用”。
## 如何定义一个好工具
| 要素 | 为什么重要 |
|------|------------|
| **清晰名称** | 让模型知道它是做什么的，而不是猜用途 |
| **明确描述** | 告诉模型何时调用、何时不要调用 |
| **完整参数定义** | 降低缺参、错参和歧义调用 |
| **稳定返回结构** | 让模型更容易根据结果组织回复 |
| **明确错误语义** | 让失败时也能安全退回用户对话 |
## Webhook 工具示例
```json
{
"name": "query_order",
"description": "查询用户订单信息",
"description": "根据订单号查询当前订单状态，仅用于用户已提供订单号的场景。",
"parameters": {
"type": "object",
"properties": {
@@ -42,188 +64,45 @@
}
},
"required": ["order_id"]
},
"endpoint": {
"url": "https://api.example.com/orders",
"method": "GET",
"headers": {
"Authorization": "Bearer {{api_key}}"
}
}
}
```
### 工具字段说明
## 客户端工具的作用
| 字段 | 说明 |
|------|------|
| name | 工具名称（英文标识符） |
| description | 工具描述（LLM 用于理解工具用途） |
| parameters | 参数定义（JSON Schema 格式） |
| endpoint | HTTP 调用配置 |
某些动作必须在接入端执行，例如：
### 参数映射
- 获取当前位置
- 请求麦克风或相机权限
- 打开特定页面或原生能力
工具参数自动映射到 HTTP 请求：
这类工具通常通过事件流和客户端配合完成，而不是由后端直接执行。
- **GET 请求**：参数作为 query string
- **POST 请求**：参数作为 JSON body
## 工具设计建议
## 客户端工具
- **一工具一职责**：不要把多个业务动作塞进同一个工具
- **名称与描述写给模型看**：必须明确何时用、何时不用
- **先设计错误返回**：失败时模型应该知道如何解释给用户
- **减少高权限工具暴露面**：不是每个助手、每个工作流节点都需要全部工具
- **把业务规则放回系统**：工具负责执行，提示词负责决策边界
某些工具需要在客户端执行（如获取地理位置）。
## 与知识库、工作流的分工
### 工作流程
- **知识库**：提供稳定事实
- **工具**：执行动作或读取实时状态
- **工作流**：决定何时进入某个步骤、调用哪个工具、失败如何回退
1. 助手返回 `assistant.tool_call` 事件
2. 客户端执行工具并获取结果
3. 客户端发送 `tool_call.results` 消息
4. 助手继续生成回复
当一个助手开始涉及多步骤、多系统调用时，工具通常应与 [工作流](workflows.md) 一起设计，而不是孤立配置。
### 服务端事件
## 安全与治理
```json
{
"type": "assistant.tool_call",
"data": {
"tool_call_id": "call_abc123",
"tool_name": "get_location",
"arguments": {}
}
}
```
- 校验输入，不直接信任模型生成的参数
- 为工具设置最小权限和清晰的可见范围
- 记录调用日志，便于审计和回放
- 对外部接口增加超时、重试和速率限制策略
### 客户端响应
## 相关文档
```json
{
"type": "tool_call.results",
"results": [
{
"tool_call_id": "call_abc123",
"name": "get_location",
"output": {
"latitude": 39.9042,
"longitude": 116.4074,
"city": "北京"
},
"status": {
"code": 200,
"message": "ok"
}
}
]
}
```
## 工具调用示例
### 天气查询
用户："北京今天天气怎么样？"
助手调用工具：
```json
{
"tool_name": "weather",
"arguments": {
"city": "北京"
}
}
```
工具返回：
```json
{
"temperature": 25,
"condition": "晴",
"humidity": 40
}
```
助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"
### 订单查询
用户："帮我查一下订单 12345"
助手调用工具：
```json
{
"tool_name": "query_order",
"arguments": {
"order_id": "12345"
}
}
```
工具返回：
```json
{
"order_id": "12345",
"status": "已发货",
"tracking": "SF1234567890"
}
```
助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"
## 工具配置最佳实践
### 1. 清晰的描述
工具描述应该让 LLM 准确理解何时使用：
```
好的描述：
"查询指定城市的实时天气信息，包括温度、天气状况和湿度"
不好的描述：
"天气工具"
```
### 2. 完整的参数定义
```json
{
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称，如 '北京'、'上海'"
},
"date": {
"type": "string",
"description": "日期，格式 YYYY-MM-DD，可选，默认今天"
}
},
"required": ["city"]
}
}
```
### 3. 错误处理
工具应返回清晰的错误信息：
```json
{
"status": {
"code": 404,
"message": "未找到该城市的天气数据"
}
}
```
## 安全注意事项
1. **验证输入** - 不要直接信任用户输入
2. **限制权限** - 工具只应有必要的权限
3. **审计日志** - 记录所有工具调用
4. **速率限制** - 防止滥用
## 下一步
- [知识库配置](knowledge-base.md) - 让助手具备专业知识
- [工作流编排](workflows.md) - 复杂对话流程
- [知识库](knowledge-base.md) - 当问题更适合“查资料”时使用知识库
- [工作流](workflows.md) - 当工具调用需要流程控制和分支逻辑时接入工作流
- [助手概念](../concepts/assistants.md) - 理解工具在助手能力层中的位置

34
docs/content/customization/tts.md
View File

@@ -1,25 +1,25 @@
# 语音生成
# TTS 参数
语音生成（TTS）负责将助手回复文本转换为可播放音频。
TTS 参数决定助手语音输出的节奏、音量和听感。本页只讨论参数层面的调优建议。
## 配置项
## 常用参数
| 配置项 | 说明 |
|---|---|
| TTS 引擎 | 选择语音合成服务提供商 |
| 声音/音色 | 选择目标音色或发音人 |
| 模型 | 语音合成模型名称 |
| 语速 | 播放速度，通常 0.5-2.0 |
| 音量/增益 | 输出音量控制 |
| 音调 | 声线高低调整 |
| 参数 | 说明 | 常见范围 |
|------|------|----------|
| **语速** | 说话速度 | `0.5 - 2.0` |
| **音量 / 增益** | 输出音量强弱 | 供应商自定义 |
| **音调** | 声线高低 | 供应商自定义 |
| **模型** | 合成模型名称 | 依供应商而定 |
| **声音 ID** | 发音人或音色标识 | 依供应商而定 |
## 建议
## 调优建议
- 对话助手建议保持语速在 `0.9-1.2`
- 生产环境建议固定主音色，降低体验波动
- 若需要打断能力，优先使用低延迟流式 TTS
- 对话助手通常建议把语速控制在 `0.9 - 1.2`
- 需要打断能力的场景，优先选择低延迟流式 TTS，并避免过长的单次回复
- 如果业务强调可信度或专业感，先保证清晰度和稳定性，再追求个性化音色
- 不要只试听一句问候语，至少用三类文案对比：短答复、长答复、数字或专有名词较多的答复
## 相关文档
- [语音配置总览](voices.md)
- [声音资源](voices.md) - 先选择适合的供应商、模型和音色
- [语音识别](asr.md) - 结合输入侧延迟一起评估整条语音链路

77
docs/content/customization/voices.md
View File

@@ -1,58 +1,43 @@
# 语音合成
# 声音资源
语音合成（TTS）模块提供自然流畅的语音输出能力。
本页是资源库中 TTS 声音与发音人资源的正式说明页，聚焦“选择哪种声音给助手输出”。
## 概述
## 这页负责什么
![语音合成](../images/voices.png)
当你已经决定启用语音输出后，需要在这里完成：
## 支持的引擎
- 选择供应商、模型和声音资源
- 为不同业务或语言准备不同音色
- 通过预览和测试确定默认发音人
| 供应商 | 特点 | 适用场景 |
|--------|------|---------|
| **阿里云** | 多音色、高自然度 | 通用场景 |
| **火山引擎** | 低延迟、实时性好 | 实时对话 |
| **Minimax** | 高性价比 | 批量合成 |
更细的速度、音量、音调等参数建议见 [TTS 参数](tts.md)。
## 配置方法
## 选择声音时要考虑什么
### 添加语音配置
1. 进入 **语音库** 页面
2. 点击 **添加语音**
3. 选择供应商
4. 填写 API 凭证
5. 保存配置
### 测试语音
- 在线预览发音效果
- 调整语速和音量
- 切换不同音色
## 音色选择
### 中文音色
| 音色 | 风格 |
| 维度 | 说明 |
|------|------|
| 晓晓 | 标准女声 |
| 晓北 | 知性女声 |
| 逍遥 | 青年男声 |
| 丫丫 | 活泼童声 |
| **语言与口音** | 是否覆盖目标用户语言与地区口音 |
| **风格** | 专业、亲切、活泼、沉稳等输出气质 |
| **延迟** | 是否适合实时对话，而不仅是离线合成 |
| **稳定性** | 长文本、多轮会话中的音色一致性 |
| **成本** | 单次调用成本和高并发可用性 |
### 英文音色
## 推荐做法
| 音色 | 风格 |
|------|------|
| Joanna | 专业女声 |
| Matthew | 沉稳男声 |
| Amy | 亲切女声 |
1. 先为每类业务角色确定一条主音色
2. 再按语言或渠道补充少量备选音色
3. 通过固定测试文案试听，统一比较自然度、节奏和可懂度
4. 上线后尽量保持默认音色稳定，避免频繁切换影响用户体验
## 参数调优
## 常见资源组织方式
| 参数 | 范围 | 说明 |
|------|------|------|
| 语速 | 0.5-2.0 | 1.0 为正常速度 |
| 音量 | 0-100 | 输出音量百分比 |
| 音调 | 0.5-2.0 | 语音音调高低 |
| 组织方式 | 适用场景 |
|----------|----------|
| **按语言区分** | 中英文或多语种助手 |
| **按业务角色区分** | 客服、销售、培训、提醒类助手 |
| **按环境区分** | 开发、预发、生产使用不同供应商或凭证 |
## 下一步
- [TTS 参数](tts.md) - 调整语速、增益、音调等输出参数
- [快速开始](../quickstart/index.md) - 把声音资源绑定到第一个助手

125
docs/content/customization/workflows.md
View File

@@ -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 能力