# 知维

**Repository Path**: java_wxid/knowledge-dimension

## Basic Information

- **Project Name**: 知维
- **Description**: 知维：基于知识库进行AI实时通话。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知维

## 当前源与边界（2026-10-13）

当前运行时唯一源是火山引擎/豆包语音：`server/volc-speech.js` 提供 ASR v3 WebSocket 与 TTS HTTP 适配，`server/index.js` 负责代理、鉴权、结构化日志和健康检查。旧 Azure 文字仅保留为历史迁移证据，不能作为当前发包或部署依据。

真实探针需要在后端环境注入 `VOLCENGINE_APP_KEY` + `VOLCENGINE_ACCESS_KEY`（或新版 `VOLCENGINE_API_KEY`），然后执行 `npm.cmd run volc:probe`；本地 fake-runtime 通过不等于公网可用。

知维是廖志伟个人作品展示与个人知识问答 App。当前代码包含火山引擎/豆包 ASR v3 中文增量识别、服务端回合/EOU 事件、个人知识库混合检索、云桥 SSE 增量回答、可取消的服务端 Doubao TTS 音频块流和客户端受保护远程流播放；真实 iPhone AEC、自动免点击打断、公网新版本与当前树 TestFlight 验收仍需单独完成。

## 当前范围

- Volcengine Doubao Speech：`cn-beijing`、`zh-CN`。
- Doubao ASR v3：WebSocket + Int16 PCM，支持 partial/final/EOU。
- Doubao 中文 TTS：`audio/mpeg`；服务端提供 `/tts`、`POST /tts/stream/ticket` 和 `GET|POST /tts/stream`，按 provider 音频块分发并支持取消。
- iPhone Expo Go：麦克风权限、实时转写、受保护远程 TTS 播放、点击打断、可选软件语音起始检测和回合隔离。原生 iOS 默认调用 `/knowledge/answer` JSON；Web 或实际进入 SSE 的路径才消费 `tts_segment`。`/tts/stream` 是受保护 HTTP 兼容端点，当前豆包适配器和客户端仍以完整 MP3 Blob/单 chunk 播放为主，不能把它写成已完成端到端字节级首声流式。
- ToC 交互：对话首页和实时页共用一个主语音按钮；麦克风、处理中省略号、停止和重试图标表达状态，监听时按钮做轻量呼吸反馈，partial 与 final 分开显示；播放中点击主按钮会先停止本地声音，再取消旧回合并开始新一轮。
- 账号与额度：Apple 首次授权姓名保存后在设置页显示；普通用户每个自然月最多提问 50 次，第 51 次返回 `monthly_quota_exceeded`；只有服务端稳定 `ownerId` 命中管理员配置的廖志伟账号不限次数，显示名和昵称不授予管理员权限。
- 联网搜索默认开启（纯寒暄和纯日期问题会跳过外部证据）；天气优先使用 Open-Meteo 结构化 T0 证据，失败后网页兜底，最终失败返回 `weather_data_unavailable`。实时工具最多执行两个，支持本地计算、节假日、POI、12306 和可选新闻；工具失败优雅降级，不阻塞回答。
- 附件与资料：相机可拍摄照片或视频，文件、照片和视频上传后可继续输入问题；PDF、图片、视频、音频和纯文字文件在 App 内查看或播放/读取。DOCX 支持服务端正文解析，但没有原始 DOCX 原生排版预览；图片当前主要走 OCR，视频帧理解、音频转写和媒体内容问答仍未完成。
- 当前回答链路同时提供 `POST /knowledge/answer` JSON 与 `POST /knowledge/answer/stream` SSE。SSE 事件包含 `meta`、`process`、`preprocessing`、`retrieval`、`token`、`clarification`、`tts_segment`、`done`、`error`；原生 iOS 默认使用 JSON，服务端和客户端按 citation、chunk、文档块和链接去重，连续语音回合按 `sessionId + turnId + sequence + generation` 隔离。真实云桥网络请求、豆包生产调用、ECS 当前源码和 Apple 登录仍需外部验收。
- 云桥模型路由：快速模型默认使用 `gpt-5.4-mini` 负责意图识别、问题改写和简短确认；主力模型由服务端按 `gpt-5.6-luna` → `gpt-5.6-terra` → `gpt-5.6-sol` 顺序选择并生成带引用的回答，仅在首 token 前发生可重试失败时逐级回退；图片先由视觉模型提取文字再进入同一知识库链路，密钥只在服务端使用。
- 本地知识库核心支持文本解析、语音转写归档、SQLite FTS5 + SHA-256 哈希向量混合检索、用户隔离、分类更新和幂等删除；普通用户默认每个自然月最多提问 50 次，管理员仅由服务端稳定 ownerId 配置获得不限次数；所有请求仍受请求大小、超时、并发和存储资源保护约束；默认本地模式关闭，需显式设置 `KNOWLEDGE_LOCAL_DEV=true`。

检索边界：生产环境只使用服务端 `sqlite_hybrid`（SQLite FTS5 + 本地哈希向量）完成召回。Azure AI Search 适配器已从代码中删除，检索不依赖任何第三方搜索服务，也不需要搜索 endpoint、索引或密钥。

## 当前验证结论

当前树的本地回归分别覆盖底层 SQLite 热查询、并发读写和 HTTP 普通用户 50 次额度/第 51 次拒绝；底层索引压力样本与 HTTP 提问额度是两层独立指标。这些是本地隔离/性能回归数据，不代表公网部署、真实云桥模型、真实 Apple 登录或 iPhone 端到端指标已通过。

## 启动

环境要求：Node.js、npm、Expo Go；电脑和 iPhone 必须连接同一 Wi-Fi。

先用真实凭据跑一次豆包语音探针（凭据只注入服务端进程环境）：

```powershell
npm.cmd run volc:probe
npm.cmd run start:lan
```

如果 `http://192.168.6.160:3001/health` 已返回 `configured=true`，说明代理已在运行，不要重复启动第二个代理，直接执行 `npm.cmd run start:lan`。

Metro 启动后，在 Expo Go 扫描终端二维码，或打开当前 LAN 地址，例如：

```text
exp://192.168.6.160:8081
```

代理健康检查：

```text
http://192.168.6.160:3001/health
```

返回 `provider=Volcengine Doubao Speech`、`region=cn-beijing`、`language=zh-CN`、`configured=true` 才能继续测试；随后还必须通过真实 `volc:probe`。

## 真机验收

1. 在 Expo Go 中允许麦克风权限。
2. 点击首页主麦克风进入实时通话，说普通话，确认先出现非空 partial，停顿后出现 final；实时页只保留一个主语音按钮。
3. 确认实际听到豆包中文 TTS 语音。
4. 播放期间点击主按钮，确认停止图标出现、本地声音立即停止，并进入新一轮监听。
5. 说第二句中文，确认新回合再次出现 partial/final，旧回合事件不能覆盖新文本。

真机结果必须按当前豆包语音链路回填验收记录；[`docs/azure-speech-live-contract.json`](docs/azure-speech-live-contract.json) 仅是迁移前 Azure 历史契约，不是当前 provider 的验收依据。在真机证据完成前，不得宣称 iOS 语音闭环已验收。

## 自动验证

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-volc-speech-contract.ps1 -Mode static
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-volc-speech-contract.ps1 -Mode protocol
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-expo-voice-smoke.ps1 -Json
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-expo-ios-bundle.ps1 -SkipDoctor -Json
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-existing-regression.ps1
npx.cmd expo-doctor
```

总回归会额外检查服务端 `/tts/stream` 的真实事件转发、取消清理、客户端远程流播放源，以及软件语音起始检测的配置门槛；这些检查不等于真实 iPhone AEC、首声时延或公网版本验收。

真实豆包 STT/TTS 探针（TTS 合成真实语句后回送 ASR 做逐字匹配）：

```powershell
npm.cmd run volc:probe
```

## 安全边界

- 豆包/云桥凭据只能存在服务端进程环境变量，不能写入仓库、日志、二维码、Expo bundle 或聊天。
- 生产模式必须设置 `SESSION_AUTH_MODE=required`，并配置真实 Apple 身份校验与独立的 `SESSION_TOKEN_ENCRYPTION_KEY`（严格 32 字节 Base64URL）；`SESSION_TOKEN_SECRET` 仅作为被拒绝的旧 v1 配置，未登录不能创建语音会话、使用 TTS、提问或访问知识库。
- `ownerId` 与 `knowledgeBaseId` 由服务端从已验证 Apple 用户派生，客户端提交的身份字段不会被信任；所有文档、语音转写、检索、回答和删除操作都强制绑定当前 Bearer 会话范围。
- `KNOWLEDGE_LOCAL_DEV=true` 仅用于受控本地验证，必须同时显式使用开发认证范围；不得用于公网、个人真实文件或生产数据。
- 自动验证：语音协议、连续回合、证据去重、回答质量、文档处理、认证隔离、SQLite hybrid、TTS 取消和客户端回合状态机均有本地脚本；这些脚本只证明当前代码路径，不代表真实 ECS、云桥、Apple、TestFlight 或 iPhone 已验收。当前 `app.json` iOS buildNumber 为 `76`，必须用当前 commit/tree 重新生成候选 IPA 后再进入真机矩阵。
- 测试结束后停止服务端代理和 Expo Metro，并清空剪贴板。

## 文档

- [`docs/项目交付与技术栈说明.md`](docs/项目交付与技术栈说明.md)：后续 Goal 唯一交付入口，包含技术栈取舍、ECS 部署和 Codemagic/TestFlight 发包流程。
- [`docs/ai-agent-real-implementation-prompt.md`](docs/ai-agent-real-implementation-prompt.md)：Goal 模式长期推进的真实功能实现提示词。
- [`docs/voice-realtime-implementation-brief.md`](docs/voice-realtime-implementation-brief.md)：实时语音功能实现范围、技术边界和验收标准。
- [`docs/azure-speech-p0-tomorrow-plan.md`](docs/azure-speech-p0-tomorrow-plan.md)：迁移前 Azure P0 历史实现状态和真机验收清单，仅供历史追溯。
- [`docs/azure-speech-p0-execution-runbook.md`](docs/azure-speech-p0-execution-runbook.md)：迁移前 Azure 现场手册，仅供历史追溯，不适用于当前豆包 provider。
- [`docs/voice-rag-prd.md`](docs/voice-rag-prd.md)：实时语音知识问答 PRD 与当前验收边界。
- [`docs/voice-rag-technical-stack.md`](docs/voice-rag-technical-stack.md)：RAG 技术栈、权限隔离与运行门槛。
- [`docs/knowledge-core-api-contract.json`](docs/knowledge-core-api-contract.json)：本地知识库开发接口契约。
- [`docs/architecture.md`](docs/architecture.md)：当前服务端/客户端分层、回答协议 parity、记忆与证据边界和拆分规则。
- [`docs/engineering-constraints.md`](docs/engineering-constraints.md)：工程约束、单元测试、覆盖率、变异测试和提交门禁。
- [`docs/testing-and-quality.md`](docs/testing-and-quality.md)：可执行测试命令、fixture 原则、覆盖率和 mutation gate。
当前交付结论必须以当前源码、当前工作流控制器状态和最新回归输出为准；历史 Goal 编号、旧构建和旧服务健康检查不能替代当前树证据。仓库内 `docs/goal-task-contract-v1.json` 至 `docs/goal-task-contract-v8.json` 仅为历史契约快照，不能恢复 Azure AI Search 或每月 100 次检索限制等旧决策。