# Program-helper **Repository Path**: HG-dev17/program-helper ## Basic Information - **Project Name**: Program-helper - **Description**: 一款多智能体辅助教学的编程教学助手 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-10 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: HTML ## README # 编程学习小助手 · 多智能体 **初中编程多智能体辅助学习系统** —— 一个可以在普通机房电脑上离线部署、课上直接使用的编程学习助手。 学生只面对**一个入口、一张卡片**:直接提问,系统在背后判断「这个问题该由谁来答」,再由最合适的角色接着说话。老师有一个独立的教师端,可以配置讲解内容与模型、查看班级学情、导出研究数据。 本项目是**独立项目**,与「阅创AI」平台没有包含或依赖关系,代码、配置、数据都保存在本机;只有调用大模型时才会访问你填写的那家模型服务商。 - 零 npm 依赖:不需要 `npm install`,只要 Node.js 18 或更高版本。 - 不需要数据库:对话记录写在本地 JSONL 日志里。 - 不做语音、不收集姓名:学生只填一个可选的编号(座位号),用于统计分析。 - 知识库可改:`knowledge/` 支持 `.txt/.md/.docx/.pptx/.pdf/图片`,教师端可直接上传文件;扫描版 PDF/图片可用多模态大模型「AI 提取文字」逐页转录。 - 首次运行口令 `admin`(改过之后以新口令为准),端口 `8788`,教师端 `/teacher`。 - 学生首页是单卡片「编程助手」,带动态背景与漂浮代码符号;右上角有「教师入口」,页脚也有入口。 --- ## 一、快速开始 ### Windows:双击启动(推荐给老师) 1. 确认电脑已安装 **Node.js 18 或更高版本**(命令行执行 `node -v` 能看到版本号即可;没有就去 下载 LTS 版一路「下一步」安装)。 2. 把整个项目文件夹放在本机任意位置(例如 `D:\Program-helper`),**不要只拷 `启动.bat` 一个文件**。 3. 双击 **`启动.bat`**。窗口里会显示: ``` 学生端:http://127.0.0.1:8788/ 教师端:http://127.0.0.1:8788/teacher ``` 4. 浏览器打开上面的地址即可。**这个黑色窗口就是服务本体,不要关**;关掉窗口服务就停了。 5. 要停止服务:关闭那个窗口,或双击 **`停止.bat`**(它会先列出要结束的进程 PID,让你输入 `Y` 确认后才结束,不会误杀别的程序)。 ### 命令行启动(给熟悉命令行的老师 / 其他系统) ```bat cd /d D:\Program-helper node server.mjs ``` 或者: ```bat npm start ``` 默认监听 `127.0.0.1:8788`。停止:在运行窗口按 `Ctrl + C`,或另开窗口执行 `停止.bat`。 ### 访问地址 | 端 | 地址 | 说明 | | --- | --- | --- | | 学生端 | | 学生提问的页面 | | 教师端 | | 配置与看板;首次运行口令 `admin`,改过后用新口令(学生首页右上角也有「教师入口」按钮) | ### 部署到服务器(Linux) 服务器上装好 Node.js 18+,把整个文件夹拷过去即可,不需要 `npm install`。部署脚本在 `deploy/linux/`: ```bash cd /opt/program-helper chmod +x deploy/linux/*.sh # 推荐:安装为 systemd 服务,开机自启 sudo ./deploy/linux/install-systemd.sh # 或者:nohup 方式(无 systemd 时) ./deploy/linux/start.sh ./deploy/linux/status.sh ./deploy/linux/stop.sh ``` Nginx 反向代理、SSE 关缓冲、HTTPS、防火墙、备份迁移、Windows 服务器等完整说明见 **[docs/服务器部署.md](docs/服务器部署.md)**。 > 阅创AI 是另一个独立项目,它也有自己的 `deploy/linux/`(默认端口 8787),两个项目可以同时部署在一台服务器上,互不影响。 --- ## 二、目录结构 ``` Program-helper/ ├── server.mjs # 服务入口:HTTP、SSE、静态文件、教师端 API 分发 ├── package.json # 零依赖;npm start / npm test / npm run selftest ├── 启动.bat / 停止.bat # Windows 一键启动 / 停止 ├── server/ # 后端模块 │ ├── http.mjs # 请求、JSON、静态文件(含目录穿越防护) │ ├── content.mjs # 内容配置:站点文案、5 个角色的提示词、分诊关键词、快捷按钮 │ ├── settings.mjs # 模型配置:5 套独立配置、脱敏、演示模式判断 │ ├── settings-crypto.mjs # 模型配置的 AES-256-GCM 加解密与本机密钥 │ ├── providers.mjs # 模型平台预设(豆包、DeepSeek、Kimi、通义、智谱、文心、混元、硅基流动、OpenAI、Ollama、自定义) │ ├── llm.mjs # 调用 OpenAI 兼容接口(流式) │ ├── router.mjs # 总控分诊:点名 → 关键词 → 总控模型 → 粘性 → 兜底 │ ├── knowledge.mjs # 读取 knowledge/ 下的知识库并做检索 │ ├── logger.mjs # 学情日志、看板统计、导出 CSV/Excel、清空归档 │ ├── demo.mjs # 没有 Key 时的演示回复 │ ├── teacher.mjs # 教师端 API(登录、看板、内容、模型、系统) │ └── selftest.mjs # 不连模型、不占端口的自检脚本 ├── public/ │ ├── index.html # 学生端 │ ├── teacher.html # 教师端 │ ├── styles.css / teacher.css │ └── js/ # 前端脚本(api / app / markdown / teacher) ├── config/ # 运行时生成(老师本机的数据) │ ├── content.json # 内容配置(明文,可以拷走) │ ├── settings.json # 模型配置(AES-256-GCM 密文,含 API Key) │ └── teacher.json # 教师口令(同样 AES-256-GCM 密文) ├── knowledge/ # 知识库(讲解员检索用,支持 txt/md/docx/pptx/pdf) │ ├── 编程基础知识点.txt # 基础概念:变量/类型/循环/函数…… │ ├── 编程初学者错误案例库.txt │ └── 编程项目层知识库.txt ├── logs/ # 学情日志(运行时生成) │ ├── chat-YYYY-MM-DD.jsonl # 每回合一行 │ └── archive/<时间戳>/ # 「清空」时归档,不物理删除 ├── tests/e2e.mjs # 端到端验收脚本 ├── deploy/linux/ # 服务器部署脚本(systemd / nohup / 安装卸载) ├── docs/ # 教师/学生使用说明、服务器部署、接口契约 └── 原始素材/ # 用户提供的只读存档,程序不读取、运行时不要修改 ``` --- ## 三、环境要求 | 项目 | 要求 | | --- | --- | | Node.js | **18 或更高版本**(推荐 20 LTS 及以上) | | 操作系统 | Windows 10/11(已提供 .bat);macOS / Linux 用命令行启动即可 | | 浏览器 | Chrome / Edge 新版本;学生端按 375px 手机宽度也能正常使用 | | 网络 | 不联网也能启动和演示;要真实调用大模型才需要能访问对应平台 | | 依赖 | **无**。不需要 `npm install`,没有 `node_modules` | --- ## 四、教师端登录与默认口令 1. 打开 (学生首页右上角也有「教师入口」)。 2. 输入口令,回车登录。**只有从未改过口令的全新部署**才显示「首次使用默认口令 admin」提示;改过之后提示会自动消失,请用你改过的新口令登录。 3. **第一次登录后请立刻改口令**:教师端 →「系统」→ 修改口令(至少 6 位)。改完旧口令立即失效,所有已登录的浏览器会被要求重新登录。 > 口令不是明文存盘:`config/teacher.json` 整份用 AES-256-GCM 加密,和 `config/settings.json` 用同一把本机密钥(见第八节)。**这把密钥一定要备份**——丢了它,模型配置和教师口令都解不开:模型会回到演示模式,教师口令会重置为 `admin`。忘记口令时,删除 `config/teacher.json` 后重启服务即可恢复默认 `admin`(记录不会丢)。 教师端共七个页签:**数据看板 / 学情分析 / 对话记录 / 内容配置 / 知识库 / 模型配置 / 系统**。 --- ### 页面访问密码(全站) - 学生、老师打开任何页面(含 `/teacher`)前,都要先输入**页面访问密码**,默认是 `phai`;这是给测试/试用期用的第一道门,和教师端口令是两回事。 - 登录教师端后,在「系统 → 页面访问密码」里可以:启用/关闭、修改密码(至少 4 位)。修改后当前浏览器会自动续期,其他已登录的访问会话会失效。 - `config/access.json` 是加密保存的(和模型 Key 一样用本机密钥),不会出现明文密码;该文件已在 `.gitignore` 中,不会上传仓库。 - 忘记页面访问密码:删除服务器/本机项目里的 `config/access.json`,重启服务后恢复默认 `phai`(只影响访问密码,不影响教师口令、模型和日志)。 - 正式给学生用之前,建议先改掉默认 `phai`,再按需决定是否关闭这道门(内网/机房环境可关闭)。 ## 五、五套模型配置怎么填 学生端背后有 5 个角色,**每个角色单独配一套模型**,互不影响。这样可以让「讲解」用能力强一些的模型,「分诊」用便宜快一些的模型,也可以只配其中几个。 | 角色 | 在系统里的名字 | 干什么 | 建议温度 | 最大输出 | | --- | --- | --- | --- | --- | | `host` | 总控 | 听不懂问题时分诊;兜底澄清 | 0.2 | 100~500 | | `explainer` | 知识讲解员 | 讲概念:生活例子→定义→最小代码→小问题 | 0.4 | 100~4000 | | `debugger` | 代码调试伙伴 | 陪学生找 bug,给线索不给答案 | 0.3 | 100~4000 | | `coach` | 项目教练 | 把想做的小项目拆成 4~6 个任务 | 0.5 | 100~4000 | | `peer` | 学习同伴(小码) | 共情、陪聊、给一点点信心 | 0.6 | 100~4000 | ### 每个角色要填的字段 教师端 →「模型配置」→ 选一个角色,填这几项: 1. **平台**:下拉选择国内主流平台(豆包·火山方舟 / DeepSeek / Kimi / 通义千问 / 智谱 GLM / 文心一言·千帆 / 腾讯混元 / 硅基流动 / OpenAI / 本地 Ollama / 自定义 OpenAI 兼容)。**选预设平台时不需要填接口地址**,页面会显示「平台地址已内置,无需填写」;只有选「自定义」才出现地址输入框,填服务商给的完整地址(通常以 `/v1` 结尾)。 2. **API Key**:在对应平台控制台创建,形如 `sk-...`。输入框是密码框,保存后只显示 `sk-****abcd` 这样的提示,**不回显明文**;留空保存表示「保持原来的 Key 不变」。 3. **模型**:点「获取模型」,系统会用该平台最新的模型列表接口拉取真实可用模型(会带上卡片里还没保存的 Key;没填 Key 时回退为内置精选名单并提示)。模型行始终是可输入的输入框:可以从拉取到的列表里选,也可以直接手打模型 ID。 4. **温度**:`0~1`,越小越稳、越大越发散。教学场景建议 `0.2~0.6`。 5. **最大输出**:一次回复的 token 上限。总控 `100~500`,其余 `100~4000`。 6. **启用**:关闭后这个角色不参与真实调用,会退回演示回复。 7. **测试连接(不用先保存,成功即保存)**:点「测试连接」会用卡片里**当前填写、还没保存**的平台 / 地址 / 模型 / Key 发一次很短的请求。成功会显示平台、模型和延迟,并**自动保存该角色配置**(提示「测试成功,已自动保存该角色配置」);失败会显示中文原因(Key 错、地址错、模型名错、超时等),不会保存。 8. **知识文件**:卡片下方可以勾选这个角色回答时检索 `knowledge/` 里的哪些文件(可多选,见本节末尾)。默认:讲解员用「基础知识点」,调试伙伴用「错误案例 + 基础知识点」,项目教练用「项目资料 + 错误案例」,总控和学习同伴默认不检索。 9. 点「保存」正式生效。 ### 示例:只给讲解员配 DeepSeek | 字段 | 填写 | | --- | --- | | 平台 | `DeepSeek 深度求索`(无需填接口地址) | | API Key | 你在 DeepSeek 开放平台创建的 `sk-...` | | 模型 | `deepseek-flash`(或列表里的其它模型) | | 温度 | `0.4` | | 最大输出 | `1000` | | 启用 | 勾选 | 保存(或在测试连接成功后自动保存)→ 成功即可。此时讲解员会走真实模型,其它仍没配 Key 的角色继续走演示回复。 ### 用本地 Ollama(完全离线、不花钱) 1. 本机安装并启动 [Ollama](https://ollama.com/),先 `ollama pull qwen3.5:4b` 之类拉一个模型。 2. 教师端平台选「本地 Ollama」(地址已内置 `http://127.0.0.1:11434/v1`,无需填写),**Key 留空**(Ollama 不需要 Key),点「获取模型」或手动填本地已拉取的模型名。 3. 保存 → 测试连接。适合机房不能联外网、但机器性能还行的场景。 ### 知识库怎么改(改完不用重启) `knowledge/` 下自带三个文本文件,讲解员、调试伙伴、项目教练回答前会从中检索资料;也支持放自己的资料: | 文件 | 内容 | 默认给谁用 | | --- | --- | --- | | `编程基础知识点.txt` | 变量 / 类型 / 循环 / 函数等基础概念,每段带生活例子、最小代码、小问题 | 讲解员、调试伙伴 | | `编程初学者错误案例库.txt` | 常见报错的「现象 / 原因 / 正确写法 / 示例」 | 调试伙伴、项目教练 | | `编程项目层知识库.txt` | 小项目的「效果 / 任务分解 / 关键代码 / 常见问题」 | 项目教练 | - **支持格式**:`.txt`、`.md`、`.docx`、`.pptx`、`.pdf`;单文件不超过 30MB。旧版 `.doc` / `.ppt` 请先另存为新格式。 - **上传**:教师端「知识库」页点「上传文件」,可一次选多个;同名文件会拒绝覆盖,改个名再传。 - **直接放文件**:也可以把文件复制进项目 `knowledge/` 目录(可建子文件夹),保存后自动热重载,**不需要重启服务**。 - **格式**:`.txt` / `.md` 里的每个知识点以「【标题】」单独一行开头(例如 `【KP-循环】`)效果最好;`.docx/.pptx/.pdf` 会按段落自动切块。 - **扫描版 PDF**:纯图片、没有文字层的 PDF 提取不到正文,会在列表里显示「解析失败 / 0 条」提示;需要先做 OCR 或换成有文字层的 PDF。 - **查看**:教师端「知识库」页可以查看文件清单、条目数和原文;点「刷新」可看最新版本。 - **扫描版 PDF / 图片**:上传后若解析不到文字,系统会自动触发「AI 提取文字」,让「知识讲解员」配置的多模态模型逐页完整转录(需要该模型支持图片输入,可能产生费用);也可以在预览里点「用 AI 识别并生成预览」手动触发。转录结果缓存在 `knowledge/.ai-cache/`,之后可正常检索。 - **给谁用**:每个角色检索哪几个文件,在「模型配置」卡片里勾选(见上一节第 8 条);内容配置里的知识库总开关和「最多检索条数」仍然优先。 - 学生端看不到知识库原文;资料是给角色的参考,最终回答仍受该角色提示词约束。 --- ## 五点五、学情分析(五维) 教师端「学情分析」页把学生日志聚合成五个维度,用来快速看出「谁需要帮、卡在哪」: | 维度 | 看什么 | 数据来源 | | --- | --- | --- | | 知识掌握 | 知识点覆盖广度、讲解次数 | `KP-*` 字段、讲解员轮次 | | 计算思维 | 项目任务推进、调试深度、脚手架使用 | 教练/调试轮次、`taskStage`、`scaffoldLevel` | | 错误类型 | 语法/运行/逻辑/概念错误分布与重复 | `ERR-*` 字段 | | 学习行为与投入 | 提问轮次、会话数、活跃天数、角色广度 | 日志时间与会话 | | 情感动机 | 正向/负向表达、同伴互动 | 学生原话关键词、小码轮次 | - 页面分「班级总体」和「学生列表」:上方是五维平均、提问趋势、常问知识点、高频错误;下方每个学生一行,点「查看」看个人五维、最近活动与教学建议。 - 分数是**过程性观察指标**(0–100),不是考试分数,也不替代前后测/CTS 量表;建议结合课堂观察使用。 - 没有数据的维度显示「—」,不会硬凑分;匿名学生会单独归到「匿名」。 - 按 7/14/30 天切换范围;右上「刷新」重新聚合。 - 接口:`GET /api/teacher/analytics?days=7`、`GET /api/teacher/analytics/student/:id?days=30`(均需教师登录)。 ## 六、没有 Key 时的演示模式 **不配置任何模型也能完整使用**:启动后教师端/学生端会显示「演示模式」标记。 - 分诊仍然工作:关键词规则照常把问题分给讲解员、调试伙伴、项目教练或学习同伴。 - 回答来自内置的演示话术(`server/demo.mjs`),会正常流式输出,足以演示课堂流程、验证界面和统计。 - 学生端提问、记录、看板、导出都正常工作,数据格式与真实模型一致。 - 一旦某个角色配置了可用模型,它就切换成真实模型;全部配好后「演示模式」标记消失。 > 演示话术只是固定内容,不针对具体代码;正式上课前建议至少给 `explainer` 和 `debugger` 配一个模型。 --- ## 七、局域网给班级使用 默认只允许本机访问(`127.0.0.1`)。要让同班学生在自己电脑/平板上访问: 1. 在启动服务的电脑上,先设置监听地址,再启动: ```bat set PH_HOST=0.0.0.0 set PORT=8788 node server.mjs ``` 或先 `set PH_HOST=0.0.0.0`,再双击 `启动.bat`(同一个命令行窗口里设置才有效)。 2. 查本机局域网 IP: ```bat ipconfig ``` 找到「IPv4 地址」,例如 `192.168.1.23`。 3. 学生访问 `http://192.168.1.23:8788/`,教师端 `http://192.168.1.23:8788/teacher`。 4. **放行防火墙**(第一次启动时 Windows 通常会弹窗,勾选「专用网络」允许即可)。没弹窗或学生连不上时,用管理员命令行添加一条入站规则: ```bat netsh advfirewall firewall add rule name="ProgramHelper 8788" dir=in action=allow protocol=TCP localport=8788 ``` 删除规则:把 `add` 改成 `delete`,名称保持一致。 5. 安全提醒:`0.0.0.0` 意味着同网段都能访问教师端登录页,**请先把口令改掉**(首次默认 `admin`);只在教室/校园内网使用,不要把 8788 端口映射到公网。 --- ## 八、日志与数据位置 | 数据 | 位置 | 说明 | | --- | --- | --- | | 对话日志 | `logs/chat-YYYY-MM-DD.jsonl` | 每回合一行 JSON,含学生编号、角色、路由方式、学情字段、学生原话与助手回复 | | 清空后的归档 | `logs/archive/<时间戳>/` | 「清空日志」只是移动归档,不物理删除,可找回 | | 内容配置 | `config/content.json` | 站点文案、5 个角色的提示词、分诊关键词、快捷按钮(**明文**) | | 模型配置 | `config/settings.json` | AES-256-GCM 密文,含 API Key | | 教师口令 | `config/teacher.json` | 整份 AES-256-GCM 密文(不是明文口令) | | 本机密钥 | Windows:`%APPDATA%\ProgramHelper\settings.key`
macOS/Linux:`~/.config/ProgramHelper/settings.key` | 解密 `settings.json` 和 `teacher.json` 用;**在项目文件夹之外**,务必备份 | | 学生端历史 | 学生自己浏览器的 `localStorage` | 记录学生在这台电脑上的历史对话;不占服务器空间,换浏览器或清缓存就没了 | > **密钥是命根子**:`settings.json` 和 `teacher.json` 都用同一把本机密钥加密。密钥丢了或换了电脑没带过去,这两份配置都会解不开——服务不会崩,会自动改名成 `config/*.broken-<时间戳>.json` 并以空配置启动:模型回演示模式、教师口令回 `admin`,需要重新填 Key、重新设口令。 > > 只改 `knowledge/*.txt` 不需要重启,保存后下一次提问自动生效;改 `config/content.json` 后刷新浏览器即可(页面资源为 no-cache),直接改文件则重启服务更稳妥。 环境变量可以整体搬家(适合把数据放到 U 盘或其它目录): | 变量 | 作用 | | --- | --- | | `PORT` | 端口,默认 `8788` | | `PH_HOST` | 监听地址,默认 `127.0.0.1`;改 `0.0.0.0` 开局域网 | | `PH_CONFIG_DIR` | 配置目录,默认项目下 `config/` | | `PH_LOG_DIR` | 日志目录,默认项目下 `logs/` | | `PH_SECRET_FILE` | 密钥文件完整路径,默认 `%APPDATA%\ProgramHelper\settings.key` | | `PH_KNOWLEDGE_DIR` | 知识库目录,默认项目下 `knowledge/` | --- ## 九、导出研究数据 教师端 →「对话记录」→ 点「导出 CSV」或「导出 Excel」: - **导出 Excel(推荐给老师)**:下载 `chat-YYYYMMDD.xlsx`,会自动按内容调整列宽、所有单元格开启自动换行、冻结表头,打开即可阅读/打印;学生消息里混入的不可见控制字符会在导出时自动剔除,不会导致 Excel 报文件损坏。 - **导出 CSV(推荐给研究分析)**:下载 `chat-YYYYMMDD.csv`,UTF-8 带 BOM,方便导入 SPSS、R、Python 等工具;CSV 是纯文本格式,本身无法保存列宽和自动换行。 也可以直接访问(登录后): ``` http://127.0.0.1:8788/api/teacher/export.csv ``` - 编码为 **UTF-8 带 BOM**、CRLF 换行,Excel 直接双击打开不乱码。 - 列:`时间, 会话编号, 学生编号, 回合, 智能体, 智能体名称, 行为类型, 知识点或错误, 脚手架层级, 任务阶段, 模式, 路由方式, 学生消息, 助手回复`。 - 时间已转成本机时区的 `YYYY-MM-DD HH:mm:ss`;**纯数字学生编号会写成 Excel 文本格式**(单元格里显示 `="202310402025"`,不会变成 `2.0231E+11` 科学计数法)。 - 「清空日志」前请先导出;清空只归档不删除,归档目录在 `logs/archive/`。 - Excel 里的列宽是按内容估算的;如果某列内容特别长,可以在 Excel 里再双击列边界自动适应。 - 需要逐条 JSON(做统计分析、写论文附录)时,直接读 `logs/chat-YYYY-MM-DD.jsonl`,一行一条记录。 --- ## 十、拷走项目 / 换电脑怎么办 - **`config/content.json` 是明文**:拷到新电脑可以直接用,老师和学生看到的文案、提示词、分诊关键词都会跟着走。 - **`config/settings.json` 和 `config/teacher.json` 都是密文**,用同一把本机密钥(默认在 `%APPDATA%\ProgramHelper\settings.key`,**不在项目文件夹里**)。只拷项目文件夹到新电脑,两份配置都解不开:服务不会崩,会自动改名成 `config/settings.broken-<标签>-<时间戳>.json` / `config/teacher.broken-<标签>-<时间戳>.json`,以空配置继续启动(演示模式、口令回 `admin`),并在教师端提示重新填写。 - 换电脑有两种做法: 1. **重新配**(推荐):在新电脑教师端重新填一遍 Key、重新设口令,几分钟的事。 2. **连密钥一起拷**:把旧电脑的 `%APPDATA%\ProgramHelper\settings.key` 拷到新电脑同一路径,再拷 `config/settings.json` 和 `config/teacher.json`。注意这是密钥,不要发到群里或网盘公开链接。 - **学生端历史不随项目走**:它保存在学生自己浏览器的 `localStorage` 里(同一台电脑、同一个浏览器才会恢复)。换电脑或清缓存后学生历史为空,但教师端的 `logs/` 学情日志不受影响。 - 日志 `logs/` 可以整体拷走做研究,但**不要**把真实学生数据随项目公开分发。 --- ## 十一、常见问题 **1. 端口被占用:`端口 8788 已被占用`** 说明已经有一个服务在跑(最常见是上次的黑色窗口没关)。 ```bat 停止.bat ``` 或者换端口: ```bat set PORT=8789 node server.mjs ``` 双击启动时若改过端口,`启动.bat` 会跟着提示新地址;`停止.bat` 也按当前 `PORT` 找进程。 **2. 启动后浏览器打不开 / 显示拒绝连接** - 确认黑色窗口还开着、没有报错退出; - 确认地址里的端口和窗口里打印的一致; - 局域网访问时确认用了 `PH_HOST=0.0.0.0` 启动,并且防火墙放行了端口。 **3. 教师端提示「配置无法解密」/ 口令突然变回 admin** 换了电脑、删了密钥文件,或 `settings.json`、`teacher.json` 被手动改坏。这两份配置用同一把密钥,密钥丢了就都解不开;服务已自动备份并重置。重新在「模型配置」填 Key、在「系统」里重设口令即可。备份文件在 `config/settings.broken-*.json`、`config/teacher.broken-*.json`。以后换电脑记得先备份 `settings.key`(见第十节)。 **4. 模型报错(401 / 404 / 429 / 超时)** | 现象 | 常见原因 | 处理 | | --- | --- | --- | | 401 / invalid api key | Key 错、复制时带了空格、Key 被禁用 | 重新复制 Key,保存后「测试连接」 | | 404 / model not found | 模型名不是该平台的、自定义地址少了 `/v1` | 点「获取模型」选列表里的模型;自定义平台按服务商文档核对地址 | | 429 / 频率超限 | 免费额度或并发限制 | 降低使用人数,或换模型/平台 | | 超时 / 连接失败 | 机房不能联外网、代理设置 | 换本地 Ollama,或检查网络与代理 | | 演示模式一直不消失 | 5 个角色都没配好 | 至少给一个角色配 Key、选模型并勾选「启用」 | **5. 学生端显示「演示模式」,回答很固定** 说明还没配模型,见第六节。演示话术是固定的,不会分析具体代码。 **6. 导出 CSV 打开乱码 / 想要好看的表格** 文件已带 UTF-8 BOM,正常 Excel 双击不会乱码;如果用的是旧版 WPS/Excel,请用「数据 → 从文本导入」并选 UTF-8。 **7. 修改了 `config/content.json` 不生效** 保存后刷新浏览器(页面资源为 no-cache);如果直接改文件,需要重启服务让配置重新读取。 **8. 改了知识库文件要重启吗?** 不用。保存或上传文件后服务会按修改时间自动重新加载(热重载)。教师端「知识库」页点「刷新」可以确认清单和原文已更新。PDF 若是扫描版(没有文字层),提取不到正文,需要先 OCR。注意每个知识点要用「【标题】」单独一行开头,格式被改坏会导致条目切不出来。 **9. 学生换人 / 想找回上次的对话** - 学生端对话页右上角有「历史」:同一台电脑、同一个学生编号,可以切换、继续之前的对话。 - 换下一个学生时点「退出」(弹窗里确认「保存并退出」):当前对话会留在本机浏览器历史里,编号被清空,下一位同学重新输入自己的编号即可。 - 学生历史只存在这台电脑的浏览器里,老师要长期留存请以教师端「对话记录」或导出的 CSV/Excel 为准。 **10. 忘记教师口令** 删除 `config/teacher.json` 后重启服务,口令恢复为 `admin`(模型配置、日志都不受影响)。 **11. 首页动画卡顿(老电脑 / 远程桌面)** 首页已做性能优化:低配设备(≤4 核或 ≤4G 内存)会自动关闭持续动画,只保留静态渐变;即使硬件看起来不差,只要实际帧率低于 40fps 也会自动降级。这样输入、滚动和对话始终优先流畅。若希望强制静态背景,可在系统中开启「减少动态效果」(Windows:设置 → 辅助功能 → 视觉效果 → 动画效果),页面会遵循该设置。 **12. 为什么「知识点 / 错误」有时是空的?** 这两个字段是**过程性记录**,不是每句话都有: - 知识点(`KP-*`):只在**知识讲解员**回答时记录。讲解员会在回复末尾输出内部标记 `[[kp:知识点]]`;如果模型没按格式输出,系统会从「什么是 X / X 怎么用 / 讲一下 X」这类问法里自动识别。 - 错误(`ERR-*`):只在**代码调试伙伴**对话时记录。学生明确报错、或调试伙伴在回复里指出具体错误类型时才会写入;单纯闲聊、问概念不会算作学生犯错。 - 历史日志不会按新规则回溯;改动只影响之后的新对话。如果看板里为空,先确认这段时间里有没有讲解员/调试伙伴的对话。 **13. 导出的 CSV 不能自动换行?** CSV 是纯文本格式,不能保存列宽、换行、冻结表头。需要排版好的表格请用「导出 Excel」,它会自动列宽、全部单元格自动换行并冻结表头;CSV 保留给 SPSS/R/Python 等研究工具。 --- ## 十二、自检与自动化验收 ```bat :: 不占端口、不调用模型的自检(临时目录里跑) npm run selftest :: 端到端验收:默认自动起一个临时实例(自动挑 8799–8810 中的空闲端口), :: 跑完自动关闭,不碰你正在用的 8788、config/ 和教师口令 node tests/e2e.mjs :: 想验收已经在运行的实例(例如 8788): set PH_BASE=http://127.0.0.1:8788 set PH_TEACHER_PASSWORD=你的新口令 node tests/e2e.mjs :: 临时实例端口被别的程序占用时,显式指定一个空闲端口 set PH_PORT=8800 node tests/e2e.mjs ``` `tests/e2e.mjs` 覆盖:健康检查、5 个角色结构、四类问题分诊、SSE 流式、目录穿越防护、教师端登录与 401/400 边界、看板/记录/内容/模型配置保存、知识库清单与原文、每个角色的知识文件勾选、教师口令文件已加密、测试连接支持未保存参数、CSV/Excel 导出、退出登录。全部通过时打印「全部通过」,失败时逐项打印原因并以非 0 退出码结束。 --- ## 十三、许可与素材来源 - 代码以 **MIT License** 发布,可自由用于教学、修改和再分发(保留版权声明)。 - `knowledge/` 下的《编程初学者错误案例库》《编程项目层知识库》和 `原始素材/` 是项目使用者提供的教学素材存档,版权归原作者/提供者所有;本程序只读取 `knowledge/` 用于检索,**不读取、不修改 `原始素材/`**。 - 《编程基础知识点》为本项目自编的初中 Python 入门讲解材料。 - 本项目为独立实现,与「阅创AI」无代码或服务依赖;品牌名、文案、配色均为本项目自有。 --- ## 十四、设计边界(避免误解) - **不做语音**:只有文字对话。 - **不做多教师账号**:一套部署一个教师口令,适合一位老师一台机器。 - **不收集姓名**:学生编号选填,建议用座位号;对话记录只存本机。 - **不保证模型输出永远正确**:模型由老师自行选择与配置,教学内容以 `config/content.json` 中的提示词和 `knowledge/` 知识库为约束,老师可在教师端随时修改。 - **不是在线平台**:没有云端账号、没有学生端安装包,浏览器打开即可用。