Files

User 9567eb7358 feat(server): KB prompt优化、字幕修复、S2S重连、助手配置API

- assistantProfileConfig: KB answer prompt改为分层策略(严格产品信息+灵活常识补充)
- nativeVoiceGateway: S2S upstream自动重连(最多50次)、event 351字幕debounce(800ms取最长文本)
- toolExecutor: 确定性query改写增强、KB查询传递session上下文
- contextKeywordTracker: 支持KB话题记忆优先enrichment
- contentSafeGuard: 新增品牌安全内容过滤服务
- assistantProfileService: 新增助手配置CRUD服务
- routes/assistantProfile: 新增助手配置API路由
- knowledgeKeywords: 扩展KB关键词词典
- fastAsrCorrector: ASR纠错规则更新
- tests/: KB prompt测试、保护窗口测试、Viking性能测试
- docs/: 助手配置API文档、系统提示词目录

2026-03-24 17:19:36 +08:00

7.8 KiB

Raw Permalink Blame History

test2 外接助手资料接口接入文档

1. 文档目的

本文档用于说明 test2 项目如何接入外部助手资料接口，并说明本地查询接口、外部接口要求、环境变量配置、缓存与降级策略，以及业务侧如何传入 userId 让语音链路和知识库链路使用同一份资料。

该能力用于统一管理以下助手资料字段，避免在代码中硬编码：

documents
email
nickname
wxl
mobile
wx_code
intro
sign
story

2. 生效范围

外接助手资料接入后，会影响以下链路：

WebSocket 语音链路
- 文件：server/services/nativeVoiceGateway.js
- 在 start 消息阶段按 userId 拉取外部资料
知识库回答链路
- 文件：server/services/toolExecutor.js
- 查询知识库前优先按 _session.profileUserId，其次按 _session.userId 拉取资料
HTTP 文字对话链路
- 文件：server/routes/chat.js
- 会透传 userId / profileUserId 到知识库查询逻辑
本地调试查询接口
- 文件：server/routes/assistantProfile.js
- 已挂载到 app.js
- 路径前缀：/api/assistant-profile

3. 环境变量配置

在 test2/server/.env 中增加以下配置：

ASSISTANT_PROFILE_API_URL=https://your-domain/api/profile
ASSISTANT_PROFILE_API_METHOD=GET
ASSISTANT_PROFILE_API_TOKEN=
ASSISTANT_PROFILE_API_HEADERS={"X-App-Key":"demo"}
ASSISTANT_PROFILE_API_TIMEOUT_MS=5000
ASSISTANT_PROFILE_CACHE_TTL_MS=60000

参数说明

ASSISTANT_PROFILE_API_URL
- 外部资料接口地址
- 未配置时，系统直接回退到默认助手资料
ASSISTANT_PROFILE_API_METHOD
- 支持 GET 或 POST
- 其他值会按 GET 处理
ASSISTANT_PROFILE_API_TOKEN
- 可选
- 配置后会自动以 Authorization: Bearer <token> 方式发送
ASSISTANT_PROFILE_API_HEADERS
- 可选
- JSON 字符串格式
- 例如：{"X-App-Key":"demo"}
ASSISTANT_PROFILE_API_TIMEOUT_MS
- 可选
- 外部接口超时时间，默认 5000
ASSISTANT_PROFILE_CACHE_TTL_MS
- 可选
- 资料缓存时长，默认 60000

4. 外部接口调用规则

test2 服务端不会直接把前端传来的资料写死到配置中，而是通过 assistantProfileService 统一向外部接口拉取。

4.1 当配置为 GET 时

请求方式：GET

请求参数：

有 userId 时，追加查询参数 ?userId=xxx
无 userId 时，不带该参数

默认请求头：

Accept: application/json

如果配置了 Token，还会带：

Authorization: Bearer <ASSISTANT_PROFILE_API_TOKEN>

如果配置了 ASSISTANT_PROFILE_API_HEADERS，会一并追加到请求头中。

4.2 当配置为 POST 时

请求方式：POST

请求体：

{
  "userId": "abc123"
}

如果当前没有 userId，则请求体会是空对象：

{}

默认请求头同上。

5. 外部接口返回格式要求

服务端支持以下任一返回结构。

5.1 结构一

{
  "profile": {
    "nickname": "大沃",
    "mobile": "13800000000"
  }
}

5.2 结构二

{
  "assistantProfile": {
    "nickname": "大沃",
    "intro": "你好，我是大沃。"
  }
}

5.3 结构三

{
  "data": {
    "profile": {
      "nickname": "大沃"
    }
  }
}

5.4 结构四

{
  "data": {
    "assistantProfile": {
      "nickname": "大沃"
    }
  }
}

5.5 结构五

{
  "nickname": "大沃",
  "mobile": "13800000000"
}

6. 服务端识别的资料字段

服务端只会提取以下字段，其余字段会被忽略：

{
  "documents": "",
  "email": "",
  "nickname": "",
  "wxl": "",
  "mobile": "",
  "wx_code": "",
  "intro": "",
  "sign": "",
  "story": ""
}

建议外部接口只返回上述字段，避免无关数据混入。

7. 本地查询接口

该接口用于联调和排查当前生效的助手资料。

7.1 查询当前资料

GET /api/assistant-profile

查询参数：

userId：可选
forceRefresh：可选，传 true 时强制拉取远端接口，跳过本地缓存

示例：

GET /api/assistant-profile?userId=abc123

GET /api/assistant-profile?userId=abc123&forceRefresh=true

成功响应示例：

{
  "code": 0,
  "message": "success",
  "success": true,
  "data": {
    "userId": "abc123",
    "profile": {
      "documents": "",
      "email": "",
      "nickname": "大沃",
      "wxl": "wx_demo",
      "mobile": "13800000000",
      "wx_code": "",
      "intro": "你好，我是大沃。",
      "sign": "",
      "story": ""
    },
    "source": "remote_api",
    "cached": false,
    "fetchedAt": 1742710000000,
    "configured": true,
    "error": null
  }
}

失败响应示例：

{
  "code": 500,
  "message": "request timeout",
  "success": false,
  "error": "request timeout"
}

7.2 强制刷新缓存

POST /api/assistant-profile/refresh

请求体：

{
  "userId": "abc123"
}

成功响应结构与查询接口一致。

8. source 字段说明

本地查询接口返回的 data.source 可用于判断当前资料来源：

remote_api
- 本次成功从外部接口获取
default
- 未配置 ASSISTANT_PROFILE_API_URL
- 使用系统默认助手资料
cache_fallback
- 外部接口调用失败
- 回退到历史缓存资料
default_fallback
- 外部接口调用失败，且没有缓存
- 回退到默认助手资料

9. 缓存与降级策略

9.1 缓存规则

缓存按 userId 隔离
未传 userId 时，使用全局缓存槽位
默认缓存时长为 60000ms
在缓存有效期内重复请求时，会直接返回缓存结果

9.2 降级规则

当外部接口异常、超时或返回不可解析内容时：

若当前 userId 已有缓存，则回退到缓存资料
若没有缓存，则回退到系统默认资料
响应中会保留 error 字段，便于排查

10. 业务侧如何传 userId

为了让语音链路和知识库链路命中同一份资料，业务侧应尽量传入稳定的业务用户标识。

10.1 WebSocket 语音链路

在 start 消息中传入：

{
  "type": "start",
  "userId": "abc123"
}

10.2 HTTP 文字对话链路

在聊天相关请求中传入：

{
  "sessionId": "session_xxx",
  "message": "介绍一下你自己",
  "userId": "abc123"
}

系统会把该 userId 同步为 profileUserId，知识库查询时优先使用它拉取资料。

11. 推荐联调步骤

步骤 1

在 server/.env 中配置外部资料接口地址和认证信息。

步骤 2

启动 test2/server。

步骤 3

请求本地查询接口验证配置是否生效：

curl "http://localhost:3001/api/assistant-profile?userId=abc123"

步骤 4

观察返回中的以下字段：

data.source
data.cached
data.configured
data.error

步骤 5

再分别验证：

语音 start 是否按 userId 生效
文字聊天是否按 userId 生效
知识库回答是否使用同一份助手资料

12. 接入注意事项

不要把外部接口 Token 写死到前端代码中
建议外部接口返回稳定 JSON 对象，不要返回数组
建议外部接口响应时间控制在 5s 内
若业务侧有多租户或多用户资料，必须传稳定的 userId
如果只是排查当前资料，优先使用 GET /api/assistant-profile
如果远端已更新但本地仍旧值，调用 POST /api/assistant-profile/refresh

13. 相关代码位置

路由注册：server/app.js
本地查询接口：server/routes/assistantProfile.js
外部拉取与缓存：server/services/assistantProfileService.js
语音链路接入：server/services/nativeVoiceGateway.js
知识库链路接入：server/services/toolExecutor.js
聊天链路透传：server/routes/chat.js
环境变量示例：server/.env.example

7.8 KiB Raw Permalink Blame History Unescape Escape