From 947af3a52595ee4ff7b7163dbb0e250919637210 Mon Sep 17 00:00:00 2001
From: Xin Wang <wangx@macmini.com>
Date: Wed, 4 Mar 2026 11:21:33 +0800
Subject: [PATCH] Refactor mkdocs.yml and add new documentation for workflow
 configuration and voice customization

- Restructured the navigation in mkdocs.yml to improve organization, introducing subcategories for assistant creation and component libraries.
- Added new documentation for workflow configuration options, detailing setup and best practices.
- Introduced new sections for voice recognition and generation, outlining configuration items and recommendations for optimal performance.
---
 .../assistants/workflow-configuration.md      | 68 +++++++++++++++++++
 docs/content/customization/asr.md             | 24 +++++++
 docs/content/customization/tts.md             | 25 +++++++
 docs/mkdocs.yml                               | 21 +++---
 4 files changed, 129 insertions(+), 9 deletions(-)
 create mode 100644 docs/content/assistants/workflow-configuration.md
 create mode 100644 docs/content/customization/asr.md
 create mode 100644 docs/content/customization/tts.md

diff --git a/docs/content/assistants/workflow-configuration.md b/docs/content/assistants/workflow-configuration.md
new file mode 100644
index 0000000..f2f4861
--- /dev/null
+++ b/docs/content/assistants/workflow-configuration.md
@@ -0,0 +1,68 @@
+# 工作流配置选项（TODO 版本）
+
+本文档是工作流配置页的第一版草稿，后续会根据实际能力继续细化。
+
+## 配置目标
+
+- 将多步骤对话拆分为可编排节点
+- 为不同分支定义独立提示词和工具权限
+- 在会话中按条件切换节点并透传上下文
+
+## 基础配置项（建议）
+
+| 配置项 | 说明 | 建议值 |
+|---|---|---|
+| 工作流名称 | 用于区分业务流程 | 简洁、业务语义明确 |
+| 入口节点 | 用户进入后的首个节点 | 固定单入口 |
+| 全局提示词 | 对所有节点生效的共性约束 | 保持简短，避免与节点提示词冲突 |
+| 节点提示词 | 当前节点的任务说明 | 单一职责，明确输入/输出 |
+| 节点工具白名单 | 当前节点可调用工具集合 | 最小权限原则 |
+| 节点超时 | 节点等待超时处理 | 3-10 秒 |
+| 失败回退节点 | 异常时兜底节点 | 建议统一到人工或澄清节点 |
+
+## 节点建议类型
+
+- 意图识别节点：判断用户诉求并路由
+- 信息收集节点：收集订单号、手机号等关键信息
+- 处理节点：执行查询、计算、调用工具
+- 回复节点：组织最终答复
+- 结束节点：输出结束语并关闭会话
+
+## 配置示例
+
+```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: "转人工处理"
+```
+
+## 已知限制（当前）
+
+- 不支持在文档中完整定义所有表达式语法
+- 不同执行引擎的节点字段可能存在差异
+- 可视化编排与 YAML 字段暂未完全一一对应
+
+## 后续计划
+
+- 补充节点字段的完整 Schema
+- 补充路由条件表达式规范
+- 增加“调试与回放”章节
+
diff --git a/docs/content/customization/asr.md b/docs/content/customization/asr.md
new file mode 100644
index 0000000..2251804
--- /dev/null
+++ b/docs/content/customization/asr.md
@@ -0,0 +1,24 @@
+# 语音识别
+
+语音识别（ASR）负责将用户音频实时转写为文本，供对话引擎理解。
+
+## 配置项
+
+| 配置项 | 说明 |
+|---|---|
+| ASR 引擎 | 选择语音识别服务提供商 |
+| 模型 | 识别模型名称 |
+| 语言 | 中文/英文/多语言 |
+| 热词 | 提升特定词汇识别准确率 |
+| 标点与规范化 | 是否自动补全标点、文本规范化 |
+
+## 建议
+
+- 客服场景建议开启热词并维护业务词表
+- 多语言场景建议按会话入口显式指定语言
+- 对延迟敏感场景优先选择流式识别模型
+
+## 相关文档
+
+- [语音配置总览](voices.md)
+
diff --git a/docs/content/customization/tts.md b/docs/content/customization/tts.md
new file mode 100644
index 0000000..3915f29
--- /dev/null
+++ b/docs/content/customization/tts.md
@@ -0,0 +1,25 @@
+# 语音生成
+
+语音生成（TTS）负责将助手回复文本转换为可播放音频。
+
+## 配置项
+
+| 配置项 | 说明 |
+|---|---|
+| TTS 引擎 | 选择语音合成服务提供商 |
+| 声音/音色 | 选择目标音色或发音人 |
+| 模型 | 语音合成模型名称 |
+| 语速 | 播放速度，通常 0.5-2.0 |
+| 音量/增益 | 输出音量控制 |
+| 音调 | 声线高低调整 |
+
+## 建议
+
+- 对话助手建议保持语速在 `0.9-1.2`
+- 生产环境建议固定主音色，降低体验波动
+- 若需要打断能力，优先使用低延迟流式 TTS
+
+## 相关文档
+
+- [语音配置总览](voices.md)
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 160adc2..291dc1c 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -26,16 +26,19 @@ nav:
       - 部署概览: deployment/index.md
       - Docker 部署: deployment/docker.md
   - 助手管理:
-      - 概述: assistants/index.md
-      - 配置选项: assistants/configuration.md
-      - 提示词指南: assistants/prompts.md
-      - 测试调试: assistants/testing.md
-      - 功能定制:
+      - 创建助手:
+          - 小助手:
+              - 配置选项: assistants/configuration.md
+              - 提示词指南: assistants/prompts.md
+              - 测试调试: assistants/testing.md
+          - 工作流:
+              - 配置选项: assistants/workflow-configuration.md
+      - 组件库:
+          - 模型接入: customization/models.md
+          - 语音识别: customization/asr.md
+          - 语音生成: customization/tts.md
           - 知识库: customization/knowledge-base.md
-          - 工具集成: customization/tools.md
-          - 语音配置: customization/voices.md
-          - 模型配置: customization/models.md
-          - 工作流: customization/workflows.md
+          - 工具与插件: customization/tools.md
       - 数据分析:
           - 仪表盘: analysis/dashboard.md
           - 历史记录: analysis/history.md