# 知维 **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-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 知维 知维是一个面向个人知识问答的实时语音应用。当前代码包含 Azure Speech 中文增量识别、服务端回合/EOU 事件、个人知识库混合检索、云桥 SSE 增量回答、可取消的服务端 Azure TTS 音频块流和客户端受保护远程流播放；真实 iPhone AEC、自动免点击打断、公网新版本与当前树 TestFlight 验收仍需单独完成。 ## 当前范围 - Microsoft Azure AI Speech：East Asia、`zh-CN`。 - Azure 连续识别：WebSocket + Int16 PCM，支持 partial/final。 - Azure 中文 TTS：`audio/mpeg`，音色 `zh-CN-XiaoxiaoNeural`；服务端提供 `/tts`、`POST /tts/stream/ticket` 和 `GET|POST /tts/stream`，后者按 Azure SDK 音频事件分块并支持取消。 - iPhone Expo Go：麦克风权限、实时转写、受保护远程 TTS 播放、点击打断、可选软件语音起始检测和回合隔离；客户端消费问答 SSE 的 `tts_segment`，按 `segmentIndex` 排队并在回答完成前申请 ticket、预取下一段，使用 `/tts/stream` GET 播放，旧 ECS 版本仅在 ticket 404 时回退 `/tts`。 - ToC 交互：对话首页和实时页共用一个主语音按钮；麦克风、处理中省略号、停止和重试图标表达状态，监听时按钮做轻量呼吸反馈，partial 与 final 分开显示；播放中点击主按钮会先停止本地声音，再取消旧回合并开始新一轮。 - 当前已增加云桥模型适配器、`POST /knowledge/answer` 完整 JSON 兼容链路和 `POST /knowledge/answer/stream` SSE 链路；服务端使用 v2 AES-256-GCM opaque 会话令牌，真实云桥网络请求、Azure 生产调用和 Apple 登录仍待外部验收。 - 云桥模型路由：快速模型默认使用 `gpt-5.4-mini` 负责意图识别、问题改写和简短确认；主力模型由服务端按 `gpt-5.6-luna` → `gpt-5.6-terra` → `gpt-5.6-sol` 顺序选择并生成带引用的回答，仅在首 token 前发生可重试失败时逐级回退；图片先由视觉模型提取文字再进入同一知识库链路，密钥只在服务端使用。 - 本地知识库核心支持文本解析、语音转写归档、SQLite FTS5 + SHA-256 哈希向量混合检索、用户隔离、分类更新和幂等删除；检索不设置每用户每月次数上限，但仍受请求大小、超时、并发和存储资源保护约束；默认本地模式关闭，需显式设置 `KNOWLEDGE_LOCAL_DEV=true`。 检索边界：生产环境只使用服务端 `sqlite_hybrid`（SQLite FTS5 + 本地哈希向量）完成召回，不调用 Azure AI Search，也不需要 Azure Search endpoint、索引或密钥。`server/search-provider.js` 中保留的 `azure` 分支仅用于历史兼容回归，发布配置不会启用它。 ## 当前验证结论 当前树 `verify-existing-regression.ps1` 已通过：SQLite 热查询 125 次 p50 `5.636ms`、p95 `6.691ms`；并发读写样本 p50 `130.791ms`、p95 `248.463ms`；连续 125 次检索和 125 次问答均未触发 `monthly_quota_exceeded`。这些是本地隔离/性能回归数据，不代表公网部署、真实云桥模型、真实 Apple 登录或 iPhone 端到端指标已通过。 ## 启动 环境要求：Node.js、npm、Expo Go；电脑和 iPhone 必须连接同一 Wi-Fi。 推荐使用已登录 Azure 的 Firefox 临时读取 Speech Key，并只注入代理子进程： ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-live-azure-probe.ps1 -Json -KeepProxy 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=Microsoft Azure AI Speech`、`region=eastasia`、`language=zh-CN`、`configured=true` 才能继续测试。 ## 真机验收 1. 在 Expo Go 中允许麦克风权限。 2. 点击首页主麦克风进入实时通话，说普通话，确认先出现非空 partial，停顿后出现 final；实时页只保留一个主语音按钮。 3. 点击“播放 Azure 中文 TTS”，确认实际听到中文语音。 4. 播放期间点击主按钮，确认停止图标出现、本地声音立即停止，并进入新一轮监听。 5. 说第二句中文，确认新回合再次出现 partial/final，旧回合事件不能覆盖新文本。 真机结果必须回填 [`docs/azure-speech-live-contract.json`](docs/azure-speech-live-contract.json)。在真机证据完成前，不得宣称 iOS 语音闭环已验收。 ## 自动验证 ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-azure-speech-proxy.ps1 -BaseUrl http://127.0.0.1:3001 -SkipProbe -Json 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、首声时延或公网版本验收。 真实 Azure STT/TTS 回放使用： ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-live-azure-probe.ps1 -Json -KeepProxy ``` ## 安全边界 - Azure Key 只能存在服务端进程环境变量，不能写入仓库、日志、二维码、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` 仅用于受控本地验证，必须同时显式使用开发认证范围；不得用于公网、个人真实文件或生产数据。 - 当前真实 Apple、Azure Speech/云桥业务请求和 iPhone 真机证据仍需单独完成，不能用本地 mock 结果替代；自建 SQLite 检索、服务端 TTS 流式取消和客户端远程流播放源已通过本地验证。公网 `/tts/stream` 与 `/tts/stream/ticket` 未认证返回 401。Codemagic Build 28 来自旧提交，当前 `app.json` buildNumber 为 29；本地回归通过后只生成一次绑定当前 SHA/tree 的设备验收包，在该包上完成真机矩阵，不重复构建。 - 测试结束后停止本轮 Azure 代理和 Expo Metro，并清空剪贴板。 ## 文档 - [`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)：P0 当前实现状态、协议和真机验收清单。 - [`docs/azure-speech-p0-execution-runbook.md`](docs/azure-speech-p0-execution-runbook.md)：现场执行手册。 - [`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)：本地知识库开发接口契约。 当前 Goal 由工作流控制器持续维护，活动运行 `RUN-20260915005937-bc36c864c3914ae6` 当前为 `contractVersion=72`、`RECOVERING`；实现依据还包括当前工作流 issue registry、当前源码和最新回归输出。`ISSUE-003` 至 `ISSUE-008` 任一未完成时，不得构建、上传或宣称可用。仓库内 `docs/goal-task-contract-v1.json` 至 `docs/goal-task-contract-v8.json` 仅为历史契约快照，不能恢复 Azure AI Search 或每月 100 次检索限制等旧决策。