# 知维 **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-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 知维 ## 当前源与边界（2026-10-11） 当前运行时唯一源是火山引擎/豆包语音：`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 播放、点击打断、可选软件语音起始检测和回合隔离；客户端消费问答 SSE 的 `tts_segment`，按 `segmentIndex` 排队并在回答完成前申请 ticket、预取下一段，使用 `/tts/stream` GET 播放，旧 ECS 版本仅在 ticket 404 时回退 `/tts`。 - ToC 交互：对话首页和实时页共用一个主语音按钮；麦克风、处理中省略号、停止和重试图标表达状态，监听时按钮做轻量呼吸反馈，partial 与 final 分开显示；播放中点击主按钮会先停止本地声音，再取消旧回合并开始新一轮。 - 账号与额度：Apple 首次授权姓名保存后在设置页显示；普通用户每个自然月最多提问 50 次，第 51 次返回 `monthly_quota_exceeded`；只有服务端稳定 `ownerId` 命中管理员配置的廖志伟账号不限次数，显示名和昵称不授予管理员权限。 - 对话策略：联网搜索默认开启；有可用个人资料时先检索当前用户知识库，再用 T0-T3 白名单网页辅助汇总；没有可用个人资料时跳过本地检索，直接进行可信联网搜索。新闻、地区、景点等核心论断通常需要两个独立信源，天气允许符合条件的 T0 官方气象单源。 - 附件与资料：相机可拍摄照片或视频，文件、照片和视频上传后可继续输入问题；PDF、图片、视频、音频和纯文字文件在 App 内查看或播放/读取。DOCX 支持服务端正文解析，但没有原始 DOCX 原生排版预览；图片当前主要走 OCR，视频帧理解、音频转写和媒体内容问答仍未完成。 - 当前已增加云桥模型适配器、`POST /knowledge/answer` 完整 JSON 兼容链路和 `POST /knowledge/answer/stream` SSE 链路；服务端使用 v2 AES-256-GCM opaque 会话令牌，真实云桥网络请求、豆包生产调用和 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` 仅用于受控本地验证，必须同时显式使用开发认证范围；不得用于公网、个人真实文件或生产数据。 - 当前真实 Apple、豆包/云桥公网业务请求和 iPhone 真机证据仍需单独完成，不能用本地 mock 结果替代；自建 SQLite 检索、服务端 TTS 流式取消和客户端远程流播放源已通过本地验证。公网 ECS 已核验加载 commit 24aff0b（`/health` 返回 `release 24aff0b`，结构化天气证据已在服务器实测返回实时数据）。历史 Codemagic Build 28/43/44/71 以及旧提交级包均不能代表当前工作树；当前 `app.json` buildNumber 为 73，本地回归已通过，但当前 commit/tree 尚未形成候选 IPA，必须先由 Codemagic 生成绑定当前源码的 `ios-test-build`，再进入真机矩阵。 - 测试结束后停止服务端代理和 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)：本地知识库开发接口契约。 当前交付结论必须以当前源码、当前工作流控制器状态和最新回归输出为准；历史 Goal 编号、旧构建和旧服务健康检查不能替代当前树证据。仓库内 `docs/goal-task-contract-v1.json` 至 `docs/goal-task-contract-v8.json` 仅为历史契约快照，不能恢复 Azure AI Search 或每月 100 次检索限制等旧决策。