发布范围：微信小程序正式交付移至 v2.5。以下为开发预览说明；源码和本地验证已保留，不代表微信真机或上架验收通过。

小程序与桌面端共用课堂概念，提供手机录音转文字、关键词提醒、课堂问答、回顾、笔记和 Markdown 导出。当前版本为 2.0.0 本地验证版：源代码、构建产物、合成微信回调测试以及 TypeScript ↔ Python 真实回环通信已验证；尚无微信 AppID，也未完成微信开发者工具、iOS/Android 真机或平台上架验证。

手机 BYOK 不依赖课狐运营的服务器。首版问答服务预设为百炼北京、百炼新加坡和 DeepSeek；语音使用百炼实时识别。模型名称可修改，但服务地址固定，避免把凭据发到误填的地址。问答请求拒绝重定向，要求 iOS/Android 微信或开发者工具基础库 3.2.2 及以上；PC 微信不作为手机 BYOK 的支持目标。

本地模型安装在电脑上。微信小程序不会下载或运行桌面大模型，也不会获得电脑保存的服务商 Key。

需要 Node.js 22+、pnpm 12。仓库锁定了依赖版本，运行时没有 Node.js 依赖；构建将纯 JavaScript 加密库及页面逻辑打入一个共享模块，确保只有一个课堂状态和录音管理器。

在 mini-program/ 中执行：

pnpm install --frozen-lockfile
pnpm run typecheck
pnpm test
pnpm run build
pnpm run test:bundle

输出目录为 dist/。test:bundle 在隔离的 Node VM 中加载实际构建后的 App 和三个页面入口，使用合成微信接口验证共享实例、文字保存及页面导航。它不渲染 WXML，也不能替代微信原生环境的验证。

运行真实 Python 网关互通测试前，在 api-service/ 中按桌面开发说明安装 Python 3.12/uv 环境：

uv sync --locked --extra audio --extra bundle

然后回到 mini-program/：

pnpm run test:interop

此测试启动独立 Python 子进程、临时数据库和随机回环端口，验证扫码握手、核对数字、批准、中文/emoji 原文、丢失响应后的幂等重试、权限拒绝和撤销。使用合成数据，不读取系统凭据、调用付费服务或录制麦克风。需要时通过 CLASSFOX_TEST_PYTHON 指定测试解释器；测试结束只关闭它自己的进程。

1. 构建后，在微信开发者工具中导入 mini-program/ 工程目录；project.config.json 已指定 dist/ 为小程序根目录。
2. 工程中的 touristappid 仅表示当前没有真实 AppID，不赋予真机预览、服务域名或平台发布权限。游客工程是否允许具体能力，以当前开发者工具提示为准；上面的本地自动化检查不依赖 AppID。
3. 取得自己的 AppID 后，通过本地工程设置配置，不提交 AppSecret、API Key 或私有配置。project.private.config.json 已忽略。
4. 在微信平台完成实际使用能力对应的隐私保护指引及服务域名配置，再验证 iOS/Android 手机。界面已提供原生隐私同意按钮及授权回调；没有同意时不会绕过授权调用录音。

工程保持 urlCheck: true，不自动关闭域名或 TLS 检查。预设需要的公网域名如下；仅配置实际启用的服务：

共享百炼域名当前仍受官方支持；其工作空间专属域名不在首版预设内。若账号要求专属端点，不能通过输入模型名改变域名，需要先更新预设和微信平台配置。

电脑连接使用微信局域网通信路径及独立私有 IP 监听入口。需要核对微信的同网段规则和局域网权限；校园网客户端隔离、VPN、电脑防火墙都可能影响互通。该路径已做本机 TCP 协议测试，尚未验证真实手机网络，不能仅凭本地成功推断真机必然可用。不要把该入口映射到公网。

在设置中选择使用方式，填写服务配置或扫描电脑“设置 → 连接微信小程序”的二维码。扫码后核对两端六位数字，并在电脑批准，再在手机检查连接。二维码有效期为 2 分钟，批准后的连接最多 8 小时；电脑可以随时撤销或关闭入口。

点击“开始一堂课”先建立记录，再主动开启录音，也可以粘贴文字。录音采样为 16 kHz、单声道 PCM；手机 BYOK 实时发送音频，电脑模式按最多 8 秒一段加密发送。离开课堂页、切到后台或遇到系统通话时停止本段采集并尝试保存末句。微信单段录音最多 10 分钟，结束后手动继续，原文仍归属于同一堂课。后台网络可能被系统挂起，最后一句未完成时界面会说明，不自动重启麦克风。

“帮我回答”“刚才讲了什么”和追问使用最近的课堂文本；整理笔记固定本次原文范围，长课堂按片段整理后合并。生成会消耗相应服务商额度，只有完整生成并成功写入后才显示笔记已保存。原文不会被总结覆盖。

• API Key 和配对密钥只存在于当前运行实例的内存，不写入设置、日志、课堂记录或导出。切换服务商/地区会清除对应旧 Key；退出进程后需要重新填写或配对。
• 原文、笔记及不含凭据的偏好使用微信本机存储。单堂课写入上限保守设为 850,000 UTF-8 字节，给平台每个存储项的限制预留空间；总空间不足时保留原记录，并展示未保存文字供复制或重试。
• 录音临时文件在停止回调中清理。导出时临时生成 Markdown 文件，用户自行选择微信分享，操作结束后清理导出副本；也可直接复制全文。
• 重开小程序后，原来尚未结束的课堂标记为中断，允许回顾和导出，不自动录音。新的配对不会获得旧连接的电脑权限；已同步到手机的内容仍保留。
• 一条损坏记录不会阻断正常历史的查看、导出。界面会报告异常数量，原始异常存储不自动删除或覆盖。
• 删除本机记录需要明确确认。删除小程序或清理其数据可能丢失记录，请定期导出。

尚待具备 AppID 和真实设备后完成：原生页面布局与大字体、权限首次拒绝/再次授权、隐私指引跳转、真实 PCM 帧格式及回调顺序、10 分钟自然结束、锁屏与通话中断、iOS/Android 局域网配对、真实服务账户的流式问答/语音、微信文件分享与临时文件清理。没有在线服务账户验证证据，不能把合成回调测试当作云服务实测。

协议边界见 手机配对协议，整体交付范围见 2.0 计划。运行时第三方许可证随构建输出到 dist/THIRD_PARTY_LICENSES.txt。

• 微信网络与服务域名、局域网通信、录音参数。
• 微信官方 API 类型与内嵌文档，本项目锁定 miniprogram-api-typings 5.2.3；隐私监听的实际回调签名按同文件内嵌官方说明修正，未使用其错误的 GeneralCallbackResult 声明。
• 百炼接入地址、实时语音服务端事件、DeepSeek Chat Completion。