📝 docs(agora): add agora real-time stt integration documentation

- add agora stt api documentation including appid, token and channel configuration
- provide react + shadcn ui component code for stt integration with mock data
- add websocket implementation for real-time transcription results
- include hono framework route for agora token generation supporting rtc/rtm tokens
- add detailed usage instructions and optimization suggestions for stt implementation

docs/agora实时语音转录翻译参考文档.md

@@ -0,0 +1,717 @@
+https://docs.agora.io/en/real-time-stt/rest-api/v7.x/join     api接口 
+ https://stt-demo.agora.io/   例子demo   
+https://github.com/AgoraIO-Community/Agora-RTT-Demo/tree/main/web   例子demo源码   
+
+
+APPID: f6ef0878d92340f88cff5c3e3d73bad2
+Primary Certificate：d16304cc8bb34bccbae589835141926f
+
+
+token：007eJxTYKiOPOI+4+KN+V72elnHrV+a3WC++OCfrvXy1+x/6w7tPuypwGCWZm5ulmRmmWacZm6SbGZkkWJumJacaG5gYmGempiU6mp+NqMhkJHhtWEyAyMUgvjMDIZGxgwMAL7vIE0=
+
+Channel：123
+
+Key: e40d60014fb7457aa6052c964a746adf
+Secret: 8efd206266f541488725499165b78983
+
+
+生成react shadcn
+
+
+-----------------------------------------------------------------------
+
+
+以下是基于 Agora Real-Time STT API 开发的 React + Shadcn UI 组件代码，包含加入频道、实时语音转文字核心功能，已集成你提供的 APPID 等配置：
+
+
+### 1. 先安装依赖
+```bash
+# 核心依赖
+npm install agora-rtm-sdk axios
+# Shadcn UI 组件（如已安装可跳过）
+npx shadcn-ui@latest add button input card textarea toast
+```
+
+
+### 2. React 组件代码（AgoraSTTComponent.jsx）
+```jsx
+import { useState, useEffect } from 'react';
+import axios from 'axios';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Card } from '@/components/ui/card';
+import { Textarea } from '@/components/ui/textarea';
+import { useToast } from '@/components/ui/use-toast';
+
+// 配置信息（已填入你提供的参数）
+const AGORA_CONFIG = {
+  appId: 'f6ef0878d92340f88cff5c3e3d73bad2',
+  primaryCert: 'd16304cc8bb34bccbae589835141926f',
+  token: '007eJxTYKiOPOI+4+KN+V72elnHrV+a3WC++OCfrvXy1+x/6w7tPuypwGCWZm5ulmRmmWacZm6SbGZkkWJumJacaG5gYmGempiU6mp+NqMhkJHhtWEyAyMUgvjMDIZGxgwMAL7vIE0=',
+  channel: '123',
+  key: 'e40d60014fb7457aa6052c964a746adf',
+  secret: '8efd206266f541488725499165b78983',
+  sttApiUrl: 'https://api.agora.io/v7/rtm/stt/join' // STT 加入频道 API
+};
+
+const AgoraSTTComponent = () => {
+  const [isJoined, setIsJoined] = useState(false);
+  const [transcript, setTranscript] = useState(''); // 语音转文字结果
+  const [userName, setUserName] = useState(`user_${Math.floor(Math.random() * 1000)}`);
+  const { toast } = useToast();
+
+  // 生成 STT 请求头（包含认证信息）
+  const getSTTHeaders = () => ({
+    'Content-Type': 'application/json',
+    'X-AppId': AGORA_CONFIG.appId,
+    'X-Certificate': AGORA_CONFIG.primaryCert,
+    'Authorization': `Bearer ${AGORA_CONFIG.token}`
+  });
+
+  // 1. 加入 STT 频道
+  const joinSTTChannel = async () => {
+    try {
+      const response = await axios.post(
+        AGORA_CONFIG.sttApiUrl,
+        {
+          channelName: AGORA_CONFIG.channel,
+          userId: userName,
+          config: {
+            language: 'zh-CN', // 转文字语言（中文）
+            model: 'general' // 通用模型
+          }
+        },
+        { headers: getSTTHeaders() }
+      );
+
+      if (response.status === 200) {
+        setIsJoined(true);
+        toast({ title: '成功加入 STT 频道', variant: 'default' });
+        // 监听实时转文字结果（实际项目需用 WebSocket，此处简化为模拟）
+        startMockTranscript();
+      }
+    } catch (error) {
+      toast({ title: '加入频道失败', description: error.message, variant: 'destructive' });
+      console.error('Join STT Channel Error:', error);
+    }
+  };
+
+  // 2. 模拟实时转文字（实际需对接 Agora WebSocket 推送）
+  const startMockTranscript = () => {
+    const mockTexts = ['你好，', '这里是实时语音转文字演示。', '请开始说话...', '转文字结果会实时显示在这里。'];
+    let index = 0;
+    const timer = setInterval(() => {
+      if (index < mockTexts.length) {
+        setTranscript(prev => prev + mockTexts[index]);
+        index++;
+      } else {
+        clearInterval(timer);
+      }
+    }, 1500);
+  };
+
+  // 3. 离开频道（清理资源）
+  const leaveSTTChannel = () => {
+    setIsJoined(false);
+    setTranscript('');
+    toast({ title: '已离开 STT 频道', variant: 'default' });
+  };
+
+  return (
+    <Card className="w-full max-w-2xl mx-auto p-6 mt-8">
+      <h3 className="text-xl font-semibold mb-4">Agora 实时语音转文字（STT）Demo</h3>
+
+      {/* 用户名输入 */}
+      <div className="mb-4">
+        <label className="block text-sm font-medium mb-2">用户名</label>
+        <Input
+          value={userName}
+          onChange={(e) => setUserName(e.target.value)}
+          disabled={isJoined}
+          placeholder="输入你的用户名"
+          className="w-full"
+        />
+      </div>
+
+      {/* 频道信息（固定为 123） */}
+      <div className="mb-6">
+        <label className="block text-sm font-medium mb-2">当前频道</label>
+        <Input value={AGORA_CONFIG.channel} disabled className="w-full" />
+      </div>
+
+      {/* 操作按钮 */}
+      <div className="flex gap-4 mb-6">
+        <Button 
+          onClick={joinSTTChannel} 
+          disabled={isJoined}
+          className="flex-1"
+        >
+          加入频道并开始转写
+        </Button>
+        <Button 
+          onClick={leaveSTTChannel} 
+          disabled={!isJoined}
+          variant="destructive"
+          className="flex-1"
+        >
+          离开频道
+        </Button>
+      </div>
+
+      {/* 转文字结果展示 */}
+      <div>
+        <label className="block text-sm font-medium mb-2">实时转写结果</label>
+        <Textarea
+          value={transcript}
+          readOnly
+          rows={8}
+          placeholder="转写结果将显示在这里..."
+          className="w-full bg-gray-50"
+        />
+      </div>
+    </Card>
+  );
+};
+
+export default AgoraSTTComponent;
+```
+
+
+### 3. 使用组件（在 App.jsx 中引入）
+```jsx
+import AgoraSTTComponent from './AgoraSTTComponent';
+
+function App() {
+  return (
+    <div className="min-h-screen bg-gray-50 p-4">
+      <AgoraSTTComponent />
+    </div>
+  );
+}
+
+export default App;
+```
+
+
+### 关键说明
+1. **配置集成**：已将你提供的 `APPID`、`Token`、`Channel` 等参数填入 `AGORA_CONFIG`，可直接使用。
+2. **核心功能**：
+   - 加入/离开 STT 频道
+   - 实时展示转文字结果（当前用模拟数据，实际项目需对接 Agora STT 的 WebSocket 推送接口获取实时结果）
+   - 基础错误提示（基于 Shadcn Toast 组件）
+3. **后续优化**：
+   - 替换 `startMockTranscript` 为真实 WebSocket 连接（参考 [Agora STT API 文档](https://docs.agora.io/en/real-time-stt/rest-api/v7.x/join) 中的 WebSocket 部分）
+   - 增加麦克风权限申请（浏览器端需获取用户语音输入权限）
+   - 完善错误处理（如 Token 过期、网络异常等）
+
+-----------------------------------------------------------------------
+
+   对接websocket
+
+-----------------------------------------------------------------------
+
+以下是对接 Agora STT WebSocket 实时推送的完整 React + Shadcn UI 代码，替换原模拟数据逻辑，实现真实语音转文字结果接收：
+
+
+### 1. 完整组件代码（已集成 WebSocket）
+```jsx
+import { useState, useEffect, useRef } from 'react';
+import axios from 'axios';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Card } from '@/components/ui/card';
+import { Textarea } from '@/components/ui/textarea';
+import { useToast } from '@/components/ui/use-toast';
+
+// 配置信息（已填入你的参数）
+const AGORA_CONFIG = {
+  appId: 'f6ef0878d92340f88cff5c3e3d73bad2',
+  primaryCert: 'd16304cc8bb34bccbae589835141926f',
+  token: '007eJxTYKiOPOI+4+KN+V72elnHrV+a3WC++OCfrvXy1+x/6w7tPuypwGCWZm5ulmRmmWacZm6SbGZkkWJumJacaG5gYmGempiU6mp+NqMhkJHhtWEyAyMUgvjMDIZGxgwMAL7vIE0=',
+  channel: '123',
+  key: 'e40d60014fb7457aa6052c964a746adf',
+  secret: '8efd206266f541488725499165b78983',
+  sttJoinUrl: 'https://api.agora.io/v7/rtm/stt/join', // 加入频道API
+  sttWsUrl: 'wss://api.agora.io/v7/rtm/stt/connect' // WebSocket连接地址
+};
+
+const AgoraSTTComponent = () => {
+  const [isJoined, setIsJoined] = useState(false);
+  const [transcript, setTranscript] = useState(''); // 最终转写结果
+  const [tempTranscript, setTempTranscript] = useState(''); // 实时临时结果（未确认）
+  const [userName, setUserName] = useState(`user_${Math.floor(Math.random() * 1000)}`);
+  const [micActive, setMicActive] = useState(false); // 麦克风状态
+  const { toast } = useToast();
+  
+  // 关键引用：WebSocket实例、媒体流实例
+  const wsRef = useRef(null);
+  const mediaStreamRef = useRef(null);
+  const mediaRecorderRef = useRef(null);
+
+  // 1. 生成请求头（接口+WebSocket通用认证）
+  const getAuthHeaders = () => ({
+    'X-AppId': AGORA_CONFIG.appId,
+    'X-Certificate': AGORA_CONFIG.primaryCert,
+    'Authorization': `Bearer ${AGORA_CONFIG.token}`
+  });
+
+  // 2. 申请麦克风权限 + 启动媒体录制
+  const startMicrophone = async () => {
+    try {
+      // 申请浏览器麦克风权限
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      mediaStreamRef.current = stream;
+
+      // 初始化媒体录制（用于向Agora发送音频流）
+      const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm; codecs=opus' });
+      mediaRecorderRef.current = mediaRecorder;
+
+      // 录制数据分片发送（每500ms发送一次音频片段）
+      mediaRecorder.ondataavailable = (e) => {
+        if (e.data.size > 0 && wsRef.current?.readyState === WebSocket.OPEN) {
+          // 转换为Base64格式发送（Agora STT要求）
+          const reader = new FileReader();
+          reader.onload = () => {
+            const base64Audio = reader.result.split(',')[1]; // 移除DataURL前缀
+            wsRef.current.send(JSON.stringify({
+              type: 'audio',
+              data: base64Audio,
+              timestamp: Date.now()
+            }));
+          };
+          reader.readAsDataURL(e.data);
+        }
+      };
+
+      mediaRecorder.start(500); // 每500ms生成一个音频片段
+      setMicActive(true);
+      toast({ title: '麦克风已激活，开始接收语音', variant: 'default' });
+    } catch (error) {
+      toast({ title: '麦克风权限申请失败', description: error.message, variant: 'destructive' });
+      throw error; // 中断流程，避免后续错误
+    }
+  };
+
+  // 3. 关闭麦克风 + 清理媒体资源
+  const stopMicrophone = () => {
+    if (mediaStreamRef.current) {
+      mediaStreamRef.current.getTracks().forEach(track => track.stop());
+      mediaStreamRef.current = null;
+    }
+    if (mediaRecorderRef.current && mediaRecorderRef.current.state !== 'inactive') {
+      mediaRecorderRef.current.stop();
+      mediaRecorderRef.current = null;
+    }
+    setMicActive(false);
+  };
+
+  // 4. 初始化WebSocket连接（接收转写结果）
+  const initWebSocket = (joinResponse) => {
+    // 从加入频道的响应中获取WebSocket认证参数
+    const { sessionId, nonce } = joinResponse.data;
+    // 构建WebSocket连接URL（带认证参数）
+    const wsUrl = `${AGORA_CONFIG.sttWsUrl}?appId=${AGORA_CONFIG.appId}&sessionId=${sessionId}&nonce=${nonce}`;
+
+    // 创建WebSocket实例
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    // WebSocket连接成功
+    ws.onopen = () => {
+      console.log('WebSocket连接成功，开始接收转写结果');
+      // 连接成功后启动麦克风
+      startMicrophone().catch(err => console.error('启动麦克风失败:', err));
+    };
+
+    // 接收转写结果（核心逻辑）
+    ws.onmessage = (event) => {
+      const sttData = JSON.parse(event.data);
+      switch (sttData.type) {
+        // 临时转写结果（实时更新，可能会修正）
+        case 'interim_result':
+          setTempTranscript(sttData.result.text);
+          break;
+        // 最终转写结果（确认后不再修改）
+        case 'final_result':
+          setTranscript(prev => `${prev}${sttData.result.text}\n`);
+          setTempTranscript(''); // 清空临时结果
+          break;
+        // 错误信息
+        case 'error':
+          toast({ title: 'STT转写错误', description: sttData.message, variant: 'destructive' });
+          leaveSTTChannel(); // 出错后自动离开频道
+          break;
+        default:
+          break;
+      }
+    };
+
+    // WebSocket错误处理
+    ws.onerror = (error) => {
+      toast({ title: 'WebSocket连接错误', description: error.message, variant: 'destructive' });
+      leaveSTTChannel();
+    };
+
+    // WebSocket断开连接
+    ws.onclose = (event) => {
+      console.log(`WebSocket断开连接，代码: ${event.code}, 原因: ${event.reason}`);
+      stopMicrophone();
+      if (event.code !== 1000) { // 非正常断开（1000为正常关闭）
+        toast({ title: 'WebSocket意外断开', description: event.reason, variant: 'destructive' });
+      }
+    };
+  };
+
+  // 5. 加入STT频道（先调用HTTP接口，再初始化WebSocket）
+  const joinSTTChannel = async () => {
+    try {
+      // 第一步：调用HTTP接口加入频道
+      const joinResponse = await axios.post(
+        AGORA_CONFIG.sttJoinUrl,
+        {
+          channelName: AGORA_CONFIG.channel,
+          userId: userName,
+          config: {
+            language: 'zh-CN', // 中文转写
+            model: 'general', // 通用模型
+            interimResult: true, // 开启临时结果推送（实时性更高）
+            format: 'text' // 结果格式：文本
+          }
+        },
+        { headers: { ...getAuthHeaders(), 'Content-Type': 'application/json' } }
+      );
+
+      if (joinResponse.status === 200) {
+        setIsJoined(true);
+        toast({ title: '成功加入STT频道', variant: 'default' });
+        // 第二步：基于加入响应初始化WebSocket
+        initWebSocket(joinResponse);
+      }
+    } catch (error) {
+      toast({ 
+        title: '加入频道失败', 
+        description: error.response?.data?.message || error.message, 
+        variant: 'destructive' 
+      });
+      console.error('Join Channel Error:', error);
+    }
+  };
+
+  // 6. 离开STT频道（清理所有资源）
+  const leaveSTTChannel = () => {
+    // 关闭WebSocket
+    if (wsRef.current) {
+      wsRef.current.close(1000, '主动离开频道'); // 1000为正常关闭代码
+      wsRef.current = null;
+    }
+    // 关闭麦克风
+    stopMicrophone();
+    // 重置状态
+    setIsJoined(false);
+    setTranscript('');
+    setTempTranscript('');
+    toast({ title: '已离开STT频道', variant: 'default' });
+  };
+
+  // 组件卸载时清理资源（防止内存泄漏）
+  useEffect(() => {
+    return () => {
+      if (isJoined) {
+        leaveSTTChannel();
+      }
+    };
+  }, [isJoined]);
+
+  return (
+    <Card className="w-full max-w-2xl mx-auto p-6 mt-8">
+      <h3 className="text-xl font-semibold mb-4">Agora 实时语音转文字（STT）Demo</h3>
+
+      {/* 用户名输入 */}
+      <div className="mb-4">
+        <label className="block text-sm font-medium mb-2">用户名</label>
+        <Input
+          value={userName}
+          onChange={(e) => setUserName(e.target.value)}
+          disabled={isJoined}
+          placeholder="输入你的用户名"
+          className="w-full"
+        />
+      </div>
+
+      {/* 频道信息 + 麦克风状态 */}
+      <div className="mb-6 flex flex-col gap-4">
+        <div>
+          <label className="block text-sm font-medium mb-2">当前频道</label>
+          <Input value={AGORA_CONFIG.channel} disabled className="w-full" />
+        </div>
+        {isJoined && (
+          <div className="flex items-center gap-2">
+            <span className={`w-2 h-2 rounded-full ${micActive ? 'bg-green-500 animate-pulse' : 'bg-gray-400'}`}></span>
+            <span className="text-sm">
+              {micActive ? '麦克风已激活（正在接收语音）' : '麦克风未激活'}
+            </span>
+          </div>
+        )}
+      </div>
+
+      {/* 操作按钮 */}
+      <div className="flex gap-4 mb-6">
+        <Button 
+          onClick={joinSTTChannel} 
+          disabled={isJoined}
+          className="flex-1"
+        >
+          加入频道 & 启动转写
+        </Button>
+        <Button 
+          onClick={leaveSTTChannel} 
+          disabled={!isJoined}
+          variant="destructive"
+          className="flex-1"
+        >
+          离开频道
+        </Button>
+      </div>
+
+      {/* 转文字结果展示（临时结果+最终结果） */}
+      <div>
+        <label className="block text-sm font-medium mb-2">转写结果</label>
+        <Textarea
+          value={`${transcript}${tempTranscript}`} // 最终结果 + 实时临时结果
+          readOnly
+          rows={10}
+          placeholder="说话后，转写结果将实时显示在这里..."
+          className="w-full bg-gray-50"
+        />
+        {tempTranscript && (
+          <p className="text-xs text-gray-500 mt-1">注：当前显示为临时结果，可能会修正</p>
+        )}
+      </div>
+    </Card>
+  );
+};
+
+export default AgoraSTTComponent;
+```
+
+
+### 2. 核心功能说明（WebSocket对接关键点）
+#### （1）WebSocket连接流程
+1. **先调用HTTP接口**：通过 `POST /v7/rtm/stt/join` 获取 `sessionId` 和 `nonce`（WebSocket认证必需参数）
+2. **构建WebSocket URL**：拼接 `appId`、`sessionId`、`nonce` 到WebSocket地址，建立认证连接
+3. **连接成功后启动麦克风**：确保WebSocket就绪后再发送音频流，避免数据丢失
+
+
+#### （2）音频流处理逻辑
+- 使用浏览器 `MediaRecorder` 录制麦克风音频，每500ms生成一个音频片段
+- 将音频片段转换为 **Base64格式**（Agora STT要求的音频传输格式）
+- 通过WebSocket的 `send()` 方法实时推送音频数据到Agora服务器
+
+
+#### （3）转写结果接收与展示
+WebSocket接收两种核心消息类型，分别对应不同场景：
+- **`interim_result`（临时结果）**：实时推送、可能修正（如“你好”→“你好啊”），显示在结果框末尾
+- **`final_result`（最终结果）**：确认后不再修改，换行追加到最终结果中，同时清空临时结果
+
+
+### 3. 使用注意事项
+1. **HTTPS环境要求**：浏览器仅允许在HTTPS（或localhost）环境下使用麦克风和WebSocket，本地开发可用 `localhost`，线上需部署到HTTPS服务器
+2. **Token有效期**：你提供的Token有有效期，过期后需重新生成（可参考Agora文档生成临时Token）
+3. **浏览器兼容性**：支持Chrome、Edge等现代浏览器，不支持IE
+4. **错误排查**：打开浏览器控制台（F12），在「Network→WS」标签可查看WebSocket连接状态和消息，方便调试
+
+
+### 4. 后续优化建议
+- 增加“暂停/继续转写”功能（控制 `MediaRecorder` 的启停）
+- 支持多语言切换（修改 `config.language` 为 `en-US`、`ja-JP` 等）
+- 增加转写结果导出（如导出为TXT）
+- 优化音频格式（可尝试 `audio/mp3` 格式，需确认Agora支持）
+
+
+--------------------------------------------------------------------
+
+
+
+以下是基于 Hono 框架的 Agora Token 生成路由，支持生成 RTC/RTM 通用 Token，适配你之前提供的 Agora 配置（APPID、Secret 等）：
+
+
+### 1. 先安装依赖
+```bash
+# 核心依赖：hono + agora-token 生成工具
+npm install hono @agoraio-rtc/agora-token
+# 开发依赖（如需要）
+npm install -D @types/node ts-node
+```
+
+
+### 2. Hono Token 生成路由代码（`agora-token.route.ts`）
+```typescript
+import { Hono } from 'hono';
+import { RtcTokenBuilder, RtmTokenBuilder, RtcRole, RtmRole } from '@agoraio-rtc/agora-token';
+
+// 初始化 Hono 路由
+const agoraTokenRouter = new Hono();
+
+// Agora 基础配置（替换为你的实际配置，也可从环境变量读取）
+const AGORA_CONFIG = {
+  appId: 'f6ef0878d92340f88cff5c3e3d73bad2', // 你的 APPID
+  appSecret: '8efd206266f541488725499165b78983', // 你的 Secret（对应之前的 Secret 字段）
+  tokenExpiry: 3600, // Token 有效期：3600秒（1小时，可调整）
+  privilegeExpiry: 3600 // 权限有效期：与 Token 一致
+};
+
+/**
+ * Agora Token 生成接口
+ * @method GET
+ * @params type: token类型（rtc/rtm，必填）
+ * @params channel: 频道名（rtc必填，rtm可选）
+ * @params userId: 用户ID（必填，字符串格式）
+ * @example /api/agora/token?type=rtc&channel=123&userId=user_123
+ */
+agoraTokenRouter.get('/api/agora/token', (c) => {
+  try {
+    // 1. 获取请求参数
+    const tokenType = c.req.query('type'); // 必选：rtc/rtm
+    const channelName = c.req.query('channel'); // 可选（rtc必传，rtm可选）
+    const userId = c.req.query('userId'); // 必选：用户唯一ID（字符串）
+
+    // 2. 参数校验
+    if (!tokenType || !['rtc', 'rtm'].includes(tokenType)) {
+      return c.json(
+        { code: 400, message: '参数错误：type 必须为 rtc 或 rtm' },
+        { status: 400 }
+      );
+    }
+    if (!userId || userId.trim() === '') {
+      return c.json(
+        { code: 400, message: '参数错误：userId 不能为空' },
+        { status: 400 }
+      );
+    }
+    if (tokenType === 'rtc' && (!channelName || channelName.trim() === '')) {
+      return c.json(
+        { code: 400, message: '参数错误：rtc 类型 Token 需传入 channel' },
+        { status: 400 }
+      );
+    }
+
+    // 3. 生成对应类型的 Token
+    let token = '';
+    switch (tokenType) {
+      // 生成 RTC Token（用于实时音视频 + 实时转文字STT）
+      case 'rtc':
+        token = RtcTokenBuilder.buildTokenWithUid(
+          AGORA_CONFIG.appId,
+          AGORA_CONFIG.appSecret,
+          channelName!, // 已校验，非空
+          userId, // 此处 userId 作为字符串Uid（支持字符串格式）
+          RtcRole.PUBLISHER, // 角色：发布者（可发音频/视频）
+          AGORA_CONFIG.tokenExpiry,
+          AGORA_CONFIG.privilegeExpiry
+        );
+        break;
+
+      // 生成 RTM Token（用于实时消息）
+      case 'rtm':
+        token = RtmTokenBuilder.buildToken(
+          AGORA_CONFIG.appId,
+          AGORA_CONFIG.appSecret,
+          userId,
+          RtmRole.RTM_USER, // RTM 用户角色
+          AGORA_CONFIG.tokenExpiry
+        );
+        break;
+    }
+
+    // 4. 返回成功响应
+    return c.json({
+      code: 200,
+      message: 'Token 生成成功',
+      data: {
+        appId: AGORA_CONFIG.appId,
+        token,
+        tokenType,
+        channelName: channelName || '',
+        userId,
+        expiry: AGORA_CONFIG.tokenExpiry, // 有效期（秒）
+        expireTime: Date.now() + AGORA_CONFIG.tokenExpiry * 1000 // 过期时间戳（毫秒）
+      }
+    });
+
+  } catch (error) {
+    // 5. 异常处理
+    console.error('Agora Token 生成失败：', error);
+    return c.json(
+      { code: 500, message: 'Token 生成失败，服务器内部错误' },
+      { status: 500 }
+    );
+  }
+});
+
+export default agoraTokenRouter;
+```
+
+
+### 3. 路由注册（集成到 Hono 主应用）
+在你的 Hono 主入口文件（如 `app.ts`）中注册路由：
+```typescript
+import { Hono } from 'hono';
+import agoraTokenRouter from './agora-token.route';
+
+const app = new Hono();
+
+// 注册 Agora Token 路由
+app.route('/', agoraTokenRouter);
+
+// 其他路由...
+
+export default app;
+```
+
+
+### 4. 核心说明
+#### （1）支持的 Token 类型
+- **RTC Token**：用于 Agora 实时音视频（RTC）和实时转文字（STT），需传入 `channel` 和 `userId`
+- **RTM Token**：用于 Agora 实时消息（RTM），仅需传入 `userId`
+
+
+#### （2）接口调用示例
+1. **生成 RTC Token（用于 STT 场景）**
+   ```http
+   GET /api/agora/token?type=rtc&channel=123&userId=user_456
+   ```
+   响应结果：
+   ```json
+   {
+     "code": 200,
+     "message": "Token 生成成功",
+     "data": {
+       "appId": "f6ef0878d92340f88cff5c3e3d73bad2",
+       "token": "007eJxTY...（生成的Token）",
+       "tokenType": "rtc",
+       "channelName": "123",
+       "userId": "user_456",
+       "expiry": 3600,
+       "expireTime": 1720000000000
+     }
+   }
+   ```
+
+2. **生成 RTM Token（用于实时消息）**
+   ```http
+   GET /api/agora/token?type=rtm&userId=user_789
+   ```
+
+
+#### （3）关键配置说明
+- **`tokenExpiry`**：Token 有效期，默认 3600 秒（1小时），建议根据业务调整（最长支持 24 小时）
+- **`RtcRole.PUBLISHER`**：RTC 角色为“发布者”，支持发送音频/视频，满足 STT 语音输入需求
+- **字符串 UID**：`userId` 支持字符串格式（如 `user_123`），无需转换为数字，适配更多场景
+
+
+#### （4）安全建议
+1. **Secret 保护**：线上环境建议将 `appSecret` 存储在环境变量中（如 `process.env.AGORA_APP_SECRET`），避免硬编码
+2. **权限控制**：可在接口中增加用户认证（如 JWT 校验），防止未授权用户生成 Token
+3. **有效期管理**：前端需监听 `expireTime`，在 Token 过期前主动重新请求生成新 Token
+
+--------------------------------------------------------------------