# 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/` 知识库为约束,老师可在教师端随时修改。
- **不是在线平台**:没有云端账号、没有学生端安装包,浏览器打开即可用。