# YueChuangAI **Repository Path**: HG-dev17/YueChuangAI ## Basic Information - **Project Name**: YueChuangAI - **Description**: 阅创助手——小学阅创智能体 - **Primary Language**: HTML - **License**: GPL-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-09 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 阅创AI · 校园双智能体 > 当前版本 **1.0.2**:新增知识库、角色人设、全站访问密码、用户隐私协议、豆包云端语音、作品资料(拍照 / 留存文件),并修好首页掉帧与密码页回跳。 柳州鹅山路小学的**双角色 AI 伙伴**网页:小朋友对着话筒说话提问,**阅阅**(书香小使者)或**创创**(科创小先锋)用儿童能听懂的话回答,答完再给三条孩子最可能接的话(简短回应或新问题),引导孩子继续聊。学生端与教师端分开:孩子只看到聊天,老师用口令进入数据看板、对话记录和内容配置。 - 零依赖、零安装步骤:只用 Node.js 内置模块 + 原生前端,**不需要 npm install**,普通笔记本就能跑。 - 老师可在**教师端「大模型」页签**随时切换模型:豆包/火山方舟、DeepSeek、Kimi、通义千问、智谱、百度千帆、腾讯混元、OpenAI、硅基流动、本地 Ollama、自定义 OpenAI 兼容接口;点「获取平台最新模型」会用你填的 Key 直接向平台拉取当前可用模型列表。学生端不接触 Key;语音播报设置也统一放到教师端「语音」页签。 - **没有 API Key 也能用**:自动进入「演示模式」,用内置知识库陪聊(21 个儿童常见话题),配好 Key 后自动切换真实大模型,失败还会自动回退。 - **教师端**:默认口令 `admin`,可看今日/累计提问与角色比例、按会话翻记录并「标记待跟进」、导出带日期和时间的 CSV、改学校和今日话题和两位角色的开场白 / 推荐问题 / 人设、给阅阅和创创分别建知识库、查看孩子拍的照片和留下的资料、配置大模型与语音、设置全站访问密码,一键锁定回学生端。 - **拍照与作品资料**:孩子在对话里说「拍一张照片」,会真实打开摄像头,拍完存进本机 `workspace/<角色>/<日期>/`;说「留个资料」可以选文件保存。教师端「作品资料」页签能查看、打开和删除,对话记录里也会显示照片缩略图。 - **知识库**:教师端「知识库」页签给两位角色各放一套资料(txt / md / Word / PPT / Excel / PDF / 图片,单个 20MB 内);孩子提问时先在对应角色的资料里找相关片段,再交给大模型回答。资料只存在本机 `knowledge/`,不上传、不进仓库。 - **隐私**:学生端页脚和教师端「系统设置」里都有《用户隐私协议》入口;访问密码默认开启(初始 `ycai`),可在「系统设置」里关掉或改掉。 - 配套图文说明:`public/docs/教师使用说明.html`(浏览器里打开,可直接打印给老师)。 --- ## 一、30 秒上手 1. 电脑装 Node.js 18 或更高版本(,一路「下一步」)。装过一次就行。 2. 双击项目里的 **启动.bat**。 3. 浏览器会自动打开 (没自动打开就手动访问)。 4. 选一位小伙伴 → 按话筒说话 → 听到回答 → 点下面的问题接着聊。 停止:关掉黑色命令行窗口,或双击 **停止.bat**。 > 换端口:`set PORT=9000 && node server.mjs`。 --- ## 二、界面与交互 | 页面 | 说明 | |---|---| | 角色选择页 | 两张角色卡(阅阅·安静爱阅读 / 创创·活泼爱创造),鼠标悬停有 3D 倾斜 + 光晕 + 星星动效;顶部显示学校名,底部是「今日话题」胶囊;点任意一张进入对话 | | 对话页 | 左右分栏:左边是角色的动态桌宠(SVG 纸偶:呼吸、眨眼,会在舞台里走两步并转身,眼睛跟着鼠标;说话时轻轻点头、头侧出现蓝色声波,思考时冒出三个小圆点;点一下跳一下并飘出小爱心,按住还能左右拖动)+ 状态(在想 / 在说 / 在听)+ 台词气泡,右边是完整对话(聊天气泡 + 按住说话 + 系统输入法打字 + 三个「可以接着问」的问题胶囊 + 语音播报开关);窄屏自动折叠成顶部横条 | | 教师端 | `/teacher.html`,口令登录后是数据看板 / 对话记录 / 内容配置 / 知识库 / 作品资料 / 大模型 / 语音 / 系统设置 / 使用说明九个页签,右上角「锁定」退出、「学生端」回首页 | | 老师入口 | 首页底部「老师入口」进教师端口令页;学生端本身不提供任何设置按钮或抽屉,避免孩子误改 | 交互要点: - **两种输入方式**:输入框左侧话筒按钮点一下就切到「按住说话」模式(话筒变橙红、输入框变成一条大字胶囊),按住说、松手就发送;再点一次回到打字模式。 - **打字**:输入框直接用系统自带输入法——电脑上用实体键盘,手机/平板上点输入框会自动弹出系统屏幕键盘;不再内置第三方输入法。会拼音的孩子直接打,不会打字就按住话筒说话。 - **引导追问**:每轮回答后,下方会出现 3 个「孩子接下来会说的话」胶囊——有的是简短接话(原来是这样、我也想试试),有的是顺着话题继续问的新问题;点一下就继续聊,不再照抄角色自己的提问。 - **返回首页 / 一键换伙伴**:对话页左上角「‹」随时回到选择页;旁边的「换创创 / 换阅阅」直接切到另一位角色,不用退回首页。换角色会开一段新会话,教师端记录按角色分开统计。 - **语音播报**:右上角喇叭按钮可开关;阅阅音色偏清亮、语速稍慢,创创音色偏低、语速稍快;教师端「语音」页签里先选阅阅或创创,再分别调各自的语速、音调、音量、音色(两套设置各存各的,存在本机浏览器,学生端自动同步)。 - **角色主题**:阅阅=天空蓝 + 奶油白;创创=暖橙 + 安全帽黄,切角色时整页配色一起切换。 --- ## 三、给老师 ### 3.1 教师端(数据看板 / 对话记录 / 内容配置 / 知识库 / 作品资料 / 大模型 / 语音 / 系统设置 / 使用说明) 打开 ,或点学生端首页底部的「老师入口」。 - **口令**:默认 `admin`,首次登录后建议在「内容配置」右侧「修改教师口令」里改成自己的口令(改过之后登录页不再显示默认口令提示);口令只保护教师端,学生端不需要登录。 - **数据看板**:今日/累计的对话场次与提问数、待跟进条数、阅阅/创创使用比例、最近对话;点一条可跳到记录并展开。 - **对话记录**:按角色、日期、关键词筛选,可「只看待跟进」;记录列表在卡片内单独滚动,会话再多也不会把整页拉得很长;每条消息都能标记待跟进;支持导出 CSV(带 BOM,Excel 直接打开不乱码;日期、时间分成两列,文件名也带导出时刻);「清空记录」会二次确认。 - **内容配置**:改学校名称、今日话题,以及阅阅/创创的**人设(说话风格)**、开场白和三个推荐问题。**保存后学生端刷新即生效**,不用重启服务。 - **作品资料**:孩子在对话里让阅阅、创创拍的照片,或主动留下的文件,都真实保存在本机 `workspace/<角色>/<日期>/`;这里按角色列出,可以「打开」原图/原文件或「删除」。对话记录里也会显示照片缩略图。 - **知识库**:先选阅阅或创创,再上传这一位的资料;支持 txt / md / docx / pptx / xlsx / pdf / 图片,单个不超过 20MB。PPT、Word、PDF 会自动抽文字,中文 Type0 字体的 PDF 也能按 ToUnicode 解码;扫描版 PDF 打开预览后可点「识别扫描件文字」,先用本机识别,本机失败再用支持看图的模型。图片可在「预览」里直接看。孩子问到相关内容时,系统先找最贴近的片段再交给大模型,避免答得离题;用上知识库的回答会在学生端标注「📚 参考知识库」,教师端对话记录也会写明参考了哪份资料。 - **大模型**:选平台、填模型名/API Key、获取平台最新模型、测试连接、保存启用;Key 只存在本机,页面不回显已保存的 Key,留空表示沿用。 - **语音**:先选阅阅/创创,再分别调这一位的语速、音调、音量、音色,可试听与恢复默认;两套设置互不影响。页面底部还有「麦克风自检」,试说 5 秒就能判断这台电脑能不能听清孩子。设置存在本机浏览器,同一台电脑的学生端自动同步(大模型 Key 与语音设置都只有老师能改)。 - **云端语音(可选)**:同一页签的「语音来源」可以切「本机语音 / 豆包云端」。选豆包后在下方卡片填 AppID / AccessToken,默认阅阅用女声、创创用男声,点「测试连接」会真的合成一句并显示耗时;没配或连不上时整段自动退回浏览器朗读。 - **系统设置**:全站访问密码(域名一进来就要输,学生端教师端都算)和搜索引擎收录开关;密码和模型 Key 一样加密保存。 - **锁定 / 学生端**:锁定会退出登录并回学生首页;点「学生端」只是回首页,登录状态保留。 > 记录只存在这台电脑的 `logs/interaction-YYYY-MM-DD.jsonl` 里,不上传;待跟进的标记存在 `config/marks.json`。忘了口令:停掉服务,删除 `config/teacher.json`,重启后口令恢复为 `admin`(已登录的会话也会全部失效)。 ### 3.2 切换大模型(教师端 →「大模型」页签) 1. 打开教师端 `/teacher.html`,用口令登录,点顶部「大模型」。 2. 选择平台 → 模型名可以点下面的候选标签直接填;填好 API Key 后点 **获取平台最新模型**,系统会用这个 Key 向平台要一份「此刻真实在售」的模型清单(失败会说明原因并退回内置示例)→ **测试连接** → **保存并启用**。 3. 看到「已保存」后回到学生端对话页刷新,右上角小胶囊会从「演示模式」变成「大模型在线」;学生端不需要也看不到 Key。 | 平台 | 接口地址(已内置) | 常用模型 | 拿 Key 的地方 | |---|---|---|---| | 豆包 · 火山方舟 | https://ark.cn-beijing.volces.com/api/v3 | doubao-seed-2-1-pro-260915 | 火山引擎控制台 → 方舟 → API Key | | DeepSeek | https://api.deepseek.com/v1 | deepseek-flash / deepseek-v4-pro | platform.deepseek.com | | Kimi · 月之暗面 | https://api.moonshot.cn/v1 | kimi-k3.1-pro / kimi-k3 | platform.kimi.com | | 通义千问 · 阿里百炼 | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3.8-max / qwen3.8-flash | bailian.console.aliyun.com | | 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 | glm-5.3 / glm-5.3-flash | open.bigmodel.cn | | 文心一言 · 百度千帆 | https://qianfan.baidubce.com/v2 | ernie-5.1 | console.bce.baidu.com/qianfan | | 腾讯混元 | https://api.hunyuan.cloud.tencent.com/v1 | hunyuan-a13b / hunyuan-role-latest | console.cloud.tencent.com/hunyuan | | 硅基流动 | https://api.siliconflow.cn/v1 | deepseek-ai/DeepSeek-V4-Pro | cloud.siliconflow.cn | | OpenAI | https://api.openai.com/v1 | gpt-6.1-terra | platform.openai.com | | 本地 Ollama(不用 Key) | http://127.0.0.1:11434/v1 | qwen3.5:9b | 本机 `ollama pull qwen3.5:9b` | | 自定义 | 自己填 | 自己填 | 任何 OpenAI 兼容网关 | 小提示: - 表里的模型名是 2026-11 核对过的「出厂默认」,各平台随时可能改名或下线;**点一下「获取平台最新模型」就以平台实时返回为准**,不用回来改代码。 - **火山方舟**要填「推理接入点 ID」(形如 `ep-2026xxxx-xxxxx`)或已开通的模型名,不能只写 `doubao`。 - **没有 Key** 也能上课:默认就是演示模式,内置 21 个话题的回答,语气和人格与真人模型一致。 - Key 只保存在本机 `config/settings.json`,而且**整份配置是 AES-256-GCM 密文**,文件里看不到明文 Key;加密密钥放在项目文件夹之外的用户目录(Windows `%APPDATA%/YueChuangAI/settings.key`),所以只打包这个文件夹发人,对方拿到的是打不开的密文。它已在 `.gitignore` 中,不会发给学生端浏览器,也不会上传到任何地方。各平台的默认接口地址是公开代码,写在 `server/providers.mjs`;仓库里没有任何真实 Key。 ### 3.3 可选:云端语音(豆包流式) 不配也能用,默认是浏览器自带的中文语音。想让阅阅和创创的声音更好听、更像真人,可以接豆包语音合成: 1. 打开 [豆包语音控制台](https://console.volcengine.com/speech/new/overview) → 开通「语音合成」→ 创建应用,记下 **AppID** 和 **AccessToken**;在「音色列表」里挑两个 `voice_type`。 2. 教师端 →「语音」页签 → 最下面 **「云端语音 · 豆包流式」** 卡片:勾「启用」、填 AppID / AccessToken、给阅阅和创创各填一个音色 ID(**留空 = 这个角色继续用浏览器朗读**)。 3. 点 **「测试连接」**(会用你填的参数真合成一句,显示首包耗时和音频大小)→ 通过后 **「保存并启用」** → 学生端刷新。 约定: - AccessToken 和模型 Key 一样加密保存在本机,页面不回显,也**不会下发到浏览器**;换电脑需要重填一次。 - 连不上、Token 失效、这个角色没配音色时,**整段**自动退回浏览器朗读,孩子那边不会听到半句断掉。 - 一次回答约 110 字,按豆包语音合成的计费大约三分钱;服务端带内存缓存,开场白这类固定句子只花一次钱。 - 音色 ID 每个账号的可见范围不同,以控制台「音色列表」为准,**仓库里没有内置任何音色 ID**。 - 用的是「WebSocket 单向流式 V1」接口(`wss://openspeech.bytedance.com/api/v1/tts/ws_binary`)。如果控制台里开通的是「语音合成大模型 2.0(V3)」,接口地址和请求体都不一样,需要扩展 `server/tts.mjs` 里的协议适配器。 ### 3.4 访问密码与搜索引擎收录 **想让站点只给测试的人看?** 教师端 →「系统设置」→「访问密码」: - 出厂**默认开启**,初始密码 `ycai`;用域名打开任何页面(`/`、`/teacher.html`、任意深链接)都会先看到「欢迎进入测试页」的密码框。 - 第一次进去就去「系统设置」里把密码改掉;改完页面右上角的状态会变成「已启用 · 自定义密码」。 - 密码和模型 Key 一样:`config/access.json` 是 **AES-256-GCM 密文**,里面还只是「盐 + 哈希」,没有明文。 - 登录状态存在浏览器 Cookie 里,默认 **7 天**;换浏览器/换电脑要重新输。学生机第一次输一次,之后一星期内不用再输。 - 勾「让所有设备重新输入密码」再保存,可以把所有已登录的浏览器踢下线(包括当前这台,会立刻跳回密码页)。 - 忘记密码:删掉 `config/access.json`,重启服务,恢复初始密码 `ycai`。 - 连续输错 20 次会限流 1 分钟,防止被暴力猜(反向代理后面全班共用一个 IP,所以没卡太死;密码建议 6 位以上)。 **不想让别人搜到?** 三道一起兜: | 手段 | 位置 | |---|---| | `robots.txt` 全站 `Disallow: /` | [public/robots.txt](public/robots.txt),不需要登录就能访问 | | 每个响应都带 `X-Robots-Tag: noindex, nofollow, noarchive` | `server.mjs` 统一加,包括密码页和 API | | 页面里的 `` | `public/index.html`、`public/teacher.html` | > 如果关闭了访问密码,站点就是公开可访问的,`noindex` 只能挡住"被收录",挡不住"被人打开"。 --- ### 3.5 知识库怎么用(教师端 →「知识库」页签) 1. 点顶部「知识库」,先点「阅阅」或「创创」选要放资料的那一位。 2. 点「上传文件」一次选一个或多个文件;同名文件会自动加「(2)」,不会覆盖。 3. 「预览」看内容:文本直接显示原文;图片显示原图;PPT/Word/PDF 显示抽出来的文字。 4. 「删除」后,下一次提问就不会再引用这份资料。 约定: - 两位角色的资料库**互不混用**:阅阅只查阅阅的,创创只查创创的。 - 文件只存在本机 `knowledge/`(可用环境变量 `YCAI_KNOWLEDGE_DIR` 改到别处),**不上传 Gitee,也不发给学生端浏览器**。 - 文字版 PDF(含中文 Type0 字体)会自动解析;扫描版 PDF 打开「预览」后点「识别扫描件文字」,本机会用 Windows OCR 识别内嵌页面图片,识别不了再交给支持看图的模型。老式 `.doc` / 加密 PDF 仍可能抽不出文字,请先另存为 docx / 文本,或把关键内容写成 txt 再上传。图片用于预览和留档,暂不自动识别图里的文字。 - 单个文件上限 20MB;超过会提示压缩后再传。 ### 3.6 作品资料:拍照与留文件(教师端 →「作品资料」页签) 孩子不用退出对话,直接跟阅阅或创创说「拍一张照片」「照张相」「留个资料」: 1. 说「拍一张照片」时,对话里会弹出相机窗口;孩子对准要留的画面,点「拍照保存」。前提是这台电脑有摄像头,并且浏览器允许使用摄像头(点地址栏左边的锁图标 → 摄像头 → 允许)。 2. 说「留个资料」「上传资料」时,会打开选文件窗口;照片、文档、表格、PPT、PDF、压缩包等都可以,单个不超过 25MB。 3. 拍完或选完,对话里会出现缩略图/文件名和保存路径,文件真实写进本机 `workspace/<角色>/<日期>/`(可用环境变量 `YCAI_WORKSPACE_DIR` 改到别处),每份文件旁边还有一份 `.meta.json` 记录来源、时间、备注。 4. 教师端「作品资料」页签可以切换阅阅/创创查看,点「打开」看原图或下载原文件,点「删除」二次确认后才会删。 约定:workspace 只存本机,不上传 Gitee;学生端相机只在孩子主动说拍照或点相机按钮时才会打开,不会后台偷拍。**保存后默认不交给大模型**;孩子想让角色看照片或读文字资料时,点气泡里的「让阅阅看看 / 让创创看看」或「让阅阅读读 / 让创创读读」,这一张图片或这一份文字资料才会发给当前配置的大模型平台,Word / PPT / PDF / 压缩包等仍只留本机。 --- ## 四、目录结构 ``` YueChuangAI/ ├─ 启动.bat / 停止.bat 双击启动 / 停止(Windows) ├─ server.mjs 本地服务:静态托管 + API(含 /api/models 实时模型列表、/api/tts 云端语音)+ SSE 转发 ├─ server/ │ ├─ providers.mjs 11 个平台的预设(地址/模型/文档)+ listModels 实时拉取 │ ├─ llm.mjs 上游流式调用、超时、错误归一化 │ ├─ tts-providers.mjs 云端语音平台预设(豆包:接口地址 / cluster / 音色占位) │ ├─ tts.mjs 豆包 WebSocket 流式合成:二进制组帧、拆帧、超时、内存缓存 │ ├─ ws-client.mjs 零依赖 WebSocket 客户端(RFC 6455,只给 TTS 用) │ ├─ access.mjs 全站访问密码:加密配置、会话、限流、密码页 │ ├─ settings.mjs 读写加密后的 config/settings.json(密钥只存在服务端) │ ├─ settings-crypto.mjs 配置静态加密:AES-256-GCM,密钥存项目外的用户目录 │ ├─ personas.mjs 两位角色的人格、开场白、系统提示词(支持老师补充人设) │ ├─ knowledge.mjs 角色知识库:上传/删除/预览/检索,本地抽 docx/pptx/xlsx/pdf 文字 │ ├─ ocr.mjs 扫描件 OCR:Windows 本机识别 + 支持看图的大模型兜底 │ ├─ workspace.mjs 作品资料:拍照/文件落盘、按角色和日期分开、列表/读取/删除 │ ├─ reply-parser.mjs 把流式文本拆成「说」和「追问」,提供 parseChips 解析孩子视角的胶囊、pickChips 过滤摘抄与兜底 │ ├─ demo.mjs 演示模式知识库(无 Key 时使用) │ ├─ teacher.mjs 教师端:口令、看板统计、记录扫描、标记、CSV、内容配置 │ ├─ selftest.mjs 无 Key 自检脚本 │ ├─ reply-parser.test.mjs 解析器单元测试(逐字流式回归) │ ├─ _tts.test.mjs 云端语音测试(假豆包服务:组帧/拆帧、缓存、超时、错误 47 项) │ ├─ _speech.test.mjs 语音输入事件链路测试(按下→在听→松手→发送) │ ├─ _voice-prefs.test.mjs 双角色语音设置测试(旧格式迁移 / 各存一套 / 越界收敛 8 项) │ ├─ _teacher.test.mjs 教师端测试(口令 / 状态 / 统计 / 记录 / 标记 / CSV / 内容配置 43 项) │ ├─ _knowledge.test.mjs 知识库测试(上传 / 同名 / 预览 / 检索 / 删除 / OCR 回写 101 项) │ ├─ _workspace.test.mjs 作品资料测试(照片/文件落盘、中文名、按角色隔离、防穿越、删除 15 项) │ └─ _demo.test.mjs 演示知识库全量测试(话题×角色×追问跳转) ├─ public/ │ ├─ robots.txt 全站 Disallow: /(不需要访问密码就能读) │ ├─ index.html 学生端骨架(选角色页 + 左右分栏对话页,无任何设置入口) │ ├─ styles.css 学生端全部样式(角色主题靠 body[data-role] 切换) │ ├─ teacher.html 教师端骨架(口令门 + 九个页签) │ ├─ teacher.css 教师端独立主题样式 │ ├─ js/app.mjs 学生端逻辑(选角色/对话/语音/chips/内容配置回填) │ ├─ js/api.mjs 前端接口封装 + SSE 解析 │ ├─ js/speech.mjs 语音输入(Web Speech API)+ 语音播报 │ ├─ js/voice-prefs.mjs 阅阅/创创各自的语音参数(读写、旧格式迁移、取值保护) │ ├─ js/teacher.mjs 教师端逻辑(登录 / 看板 / 记录 / 内容配置 / 知识库 / 作品资料 / 大模型 / 语音 / 系统设置) │ ├─ privacy.html 用户隐私协议(学生端页脚、教师端系统设置入口) │ ├─ docs/教师使用说明.html 给老师看的图文版说明(含界面截图) │ ├─ docs/images/ 说明文档用的截图 │ └─ assets/ 角色透明 PNG 素材 ├─ CONTRIBUTING.md 协作指南(拉代码 / 发 PR / 审核合并 / 发版) ├─ .gitee/PULL_REQUEST_TEMPLATE.md PR 模板(发 PR 时自动带出) ├─ docs/CONTRACT.md 开发契约(接口与文件归属) ├─ docs/教师使用说明.md 给老师看的速查版说明(指向 HTML 图文版) ├─ 原始素材/ 角色设定图、方案初稿 docx(只存档,程序不读取) ├─ config/settings.json 你的 Key 与云端语音 Token(整份 AES-256-GCM 加密,教师端首次保存后生成,已被 .gitignore 忽略) ├─ config/access.json 全站访问密码(同样加密,首次访问时生成,删掉即恢复初始密码 ycai) ├─ config/content.json 教师端保存的学校/今日话题/开场白(首次保存后生成) ├─ config/teacher.json 教师端口令的加盐哈希(改过口令后生成,删除即复位 admin) ├─ config/marks.json 待跟进标记(首次标记后生成) ├─ config/content.example.json 内容配置示例(可直接复制为 content.json) ├─ knowledge/ 两位角色的知识库文件(老师上传后生成,已被 .gitignore 忽略) ├─ workspace/ 孩子拍的照片/留的资料,按角色和日期分开(已被 .gitignore 忽略) └─ logs/interaction-YYYY-MM-DD.jsonl 每次问答的教研日志(JSONL,不含姓名) ``` --- ## 五、常见问题 **Q:按住说话松手后没有反应?** 现在每次都会有反馈:正在打开麦克风 / 在听 / 正在识别 / 没听清,四步都能在输入框上方看到。如果一直没反应,按顺序排查: 1. **麦克风权限**:第一次点话筒时浏览器会弹「允许使用麦克风吗」,点「允许」。点错了就点地址栏左边的锁图标 → 网站设置 → 麦克风 → 允许,刷新页面再试。 2. **打开方式**:必须是本机的 `http://127.0.0.1:8787` 或 `https`。用 `http://192.168.x.x` 这类局域网 IP 打开时,浏览器会直接禁掉麦克风(提示里会写)。 3. **识别服务**:Chrome 默认连谷歌的语音服务,国内常报 `network`。同一个地址换 **Microsoft Edge** 打开一般就能用。 教师端「语音」页签底部还有「**检查麦克风**」一键自检:会列出安全来源、浏览器支持、权限状态,并让你试说 5 秒,直接告诉你卡在哪一步。 **Q:点话筒提示不支持语音?** 用电脑版 Edge 或 Chrome 打开 `http://127.0.0.1:8787`(双击 `file://` 打开是不行的)。语音识别需要联网。 **Q:模型列表不准 / 想换更新的模型?** 在教师端「大模型」页签填好该平台的 Key,点 **获取平台最新模型**:能联网就直接列出平台当前可用模型(显示「实时获取 · 时间」);没有 Key 或平台限制时会退回内置清单并说明原因。也可以直接从平台控制台复制模型名粘进输入框。 **Q:语音的语速、音调能调吗?** 能。教师端登录后点顶部「语音」页签,先选「阅阅」或「创创」,再调这一位的语速、音调、音量、音色,还能「试听」「恢复默认」;两位伙伴各存一套,互不影响。设置存在本机浏览器,同一台电脑的学生端刷新(或直接切换标签页)后自动同步。学生端不提供任何设置入口,避免孩子误改。语音播报用的是电脑自带的中文语音包,不联网也能发声。 **Q:没有声音?** 检查右上角喇叭是否被关掉;Windows 需要至少一个中文语音包(设置 → 时间和语言 → 语言 → 中文 → 语音包)。没有中文语音包时会用默认音色朗读。 **Q:从 Gitee 下载 ZIP 解压后,双击 启动.bat 黑窗口一闪而过 / 提示「'版本,一路...' 不是内部或外部命令」?** 旧压缩包把 `.bat` 存成了 Linux 换行(LF),Windows 命令行会把 UTF-8 中文行拆碎。仓库已加 `.gitattributes` 强制 `.bat` 用 Windows 换行(CRLF),请重新下载最新分支包。已经下载的旧包不用重下:在解压目录的地址栏输入 `cmd` 回车,执行 `node server.mjs` 就能启动;也可以直接用 git clone,克隆时 Git 会自动转成 CRLF。 **Q:端口被占用?** `set PORT=9000 && node server.mjs`,或先双击 停止.bat。 **Q:填了 Key 还是演示模式?** 先点「测试连接」看红色错误提示:401=Key 错或过期;404=模型名/地址不对(火山方舟要填接入点 ID);429=余额或频率问题;超时=网络或代理。测试通过再保存。 **Q:把整个文件夹打包发给别人,Key 会跟着泄露吗?** 不会。`config/settings.json` 里存的是 AES-256-GCM 密文,解密密钥在项目文件夹之外的用户目录,不会被打包带走;对方打开会回落到演示模式,需要自己重填 Key。换电脑、换 Windows 账户也是同理(重填一次即可)。只有把本机密钥文件也一起拷给别人,密文才能被解开,所以别拷 `settings.key`。 **Q:孩子说的话会被上传吗?** 语音识别用的是浏览器自带的识别服务(Chrome/Edge 在联网时会上传到厂商做转写);文字对话发到你配置的大模型平台。问答记录只写在本机 `logs/` 里,不含姓名和设备信息。需要完全离线时,可配置本地 Ollama + 关闭语音播报。 --- ## 六、二次开发 - 改人格、开场白、引导风格:`server/personas.mjs`(两位角色同一套规则,只换口吻与知识偏好)。 - 加演示话题:`server/demo.mjs`,往 `TOPICS` 表里加一条即可,两个角色各写一段。 - 改配色:`public/styles.css` 顶部 `body[data-role=...]` 下的 CSS 变量。 - 接口细节与文件归属见 `docs/CONTRACT.md`;改完后跑 `npm start`(等同 `node server.mjs`)。 - 测试套件(11 个文件,全过再用):`node server/selftest.mjs`(接口、访问网关、教师端口令、SSE 与模型列表 18 项)、`node server/reply-parser.test.mjs`(流式解析与孩子视角快捷话术 30 项)、`node server/_speech.test.mjs`(语音输入事件链路 7 项)、`node server/_voice-prefs.test.mjs`(双角色语音设置 8 项)、`node server/_teacher.test.mjs`(教师端口令/状态/统计/记录/标记/CSV/内容配置 43 项)、`node server/_knowledge.test.mjs`(知识库上传/预览/检索/删除/OCR 回写 101 项)、`node server/_demo.test.mjs`(演示知识库全量)、`node server/_tts.test.mjs`(云端语音协议/缓存/超时/错误 47 项)、`node server/_access.test.mjs`(访问密码/加密/限流 38 项)、`node server/_packaging.test.mjs`(Windows 启动脚本换行 5 项)、`node server/_workspace.test.mjs`(作品资料落盘/隔离/防穿越 15 项)。 - 教师端接口与页面归属在 `docs/CONTRACT.md` 的「教师端」一节;记录格式变了要同步 `server/teacher.mjs` 与 `_teacher.test.mjs`。 --- ## 七、多人协作 多人一起改这份代码时,照着 [CONTRIBUTING.md](CONTRIBUTING.md) 的三步做: - **拉取**:`git switch main && git pull`,再 `git switch -c 我的分支`(不直接改 main); - **上传**:改完 `git add -A` → `git commit -m "改了什么"` → `git push -u origin 我的分支` → 在 Gitee 点「新建 Pull Request」; - **审核合并**:管理员看「文件」改动;想亲手试就在**另一个文件夹**里克隆一份跑,不动自己的目录 → 审查通过 → 选 Squash 合并 → 删除源分支; - 两条不许提交:`config/settings.json`(Key)、`原始素材/`,已在 .gitignore 中。 --- ## 八、设计理念 沿用初稿「师生机三元」的思路:AI 不是替老师讲话,而是当一个**愿意听、会追问**的伙伴。所以每轮回答都刻意留一个钩子问题,让孩子从「被动听」变成「主动问」——提问能力,才是这套系统真正想练的东西。