教伴 —— 教学办公助手

TeachBuddy 目前以部署在远端服务器上的网页应用提供服务。用户通过浏览器访问部署站点，无需安装 Python 或桌面客户端；本仓库用于维护网页源码、部署配置和使用文档。原 Win7 桌面版保留为兼容入口。

网页功能

网页端提供浅色响应式教学工作台：离线模板与 AI 教案、讨论改稿、可编辑结果、Word / PPT / TXT 下载、教案历史、模板与资料导入，以及上传文件的分类、查重预览与 ZIP 下载。浏览器只处理主动上传的文件副本。

公众号教学资源目录使用 SQLite 持久化，支持公开文章链接导入、标题摘要检索、学科年级筛选和加入当前会话资料。采集范围及访问限制见 公众号资源说明。

讲话稿工作台 支持开学典礼、家长会、教研活动、工作会议、活动致辞及自定义场合；可选语气和篇幅，模板生成无需 AI，支持编辑、独立历史、Word/TXT 导出，配置 AI 后可生成与改稿。

使用远端网页

打开部署管理员提供的网站地址，输入访问密码即可使用。AI 由服务器统一配置；未配置 AI 时可使用模板生成、编辑和导出功能。

资料、模板和历史按浏览器会话隔离，暂不支持跨设备账号同步。清除 Cookie 或更换浏览器后无法访问原会话资料，请及时导出需要保留的内容。

网页技术栈

• Python 3.11+（Docker 镜像使用 Python 3.12）
• FastAPI / Uvicorn（服务端）
• 原生 HTML / CSS / JavaScript（响应式界面，无需 Node 或前端构建）
• SQLite（公众号资源目录）
• python-docx / python-pptx（文档导出）
• Docker Compose，支持现有反向代理、Caddy HTTPS 和 Cloudflare Tunnel

本地开发与服务器部署

本地开发使用独立 Python 3.11+ 环境：

python -m pip install -r requirements-web.txt
python -m uvicorn web.server:app --host 127.0.0.1 --port 8765

打开 http://127.0.0.1:8765 。未配置 AI 时可使用离线功能。服务器部署支持 Docker Compose 和 HTTPS，需设置访问密码和会话密钥；AI 配置仅留在服务端。完整配置、数据说明和更新回滚步骤见 网页部署文档。

面向 Win7 老旧办公电脑的桌面工具：文件整理（预览→确认→执行→可撤销、扩展名/文件名关键词规则自定义、操作历史）、重复文件检测（MD5 核验、重复项移入待删区、可撤销）、教案撰写（离线模板 / 导入自定义模板 .json/.docx/.txt/.md / AI 生成初稿 / AI 讨论改稿 / Word 导出 / 基础 PPT 导出 / 样例与知识库导入）、AI 对话（多轮问答、气泡样式）。首次启动有引导页，可配置 AI 或跳过离线使用。

桌面兼容版技术栈

• Python 3.8.10（Win7 支持的最后版本，勿用 3.9+）
• PyQt5 5.15（界面）
• requests（AI 接口，OpenAI 兼容格式）
• python-docx（Word 导出）
• python-pptx（PPT 导出）
• PyInstaller（打包 exe）+ Inno Setup（安装向导，可选）

AI 运行时支持任意 OpenAI 兼容接口、连接测试、超时控制和主/备服务商自动回退；文件移动等敏感操作必须由用户确认并可撤销。

桌面兼容版运行

pip install -r requirements.txt
python main.py

打包 Win7 可用 exe

1. 在目标位数一致的环境安装 Python 3.8.10（老机器多为 32 位 Win7，则装 32 位 Python）。
2. 执行 set TARGET_BITS=32 后运行 build_exe.bat；脚本会强制校验 Python 3.8.10 和位数，产物在 dist\TeachBuddy.exe。
3. 把 dist\TeachBuddy.exe 单文件直接发给老师即可绿色使用； 如需安装向导，运行 build_installer.bat，产物位于 installer\Output\TeachBuddySetup.exe。

内置 AI 配置版

当前构建流程会把 data\config.json 作为默认 AI 配置嵌入 exe。单发 TeachBuddy.exe 或安装包均可直接读取该配置；用户之后在「设置」页保存的配置 优先级更高。内置 API Key 可被具备技术能力的用户提取，仅限受控范围分发。 data\config.json 已被 Git 忽略；首次构建可复制 data\config.example.json 并填入本机配置。不要把真实密钥、绿色版或安装包提交到公开仓库。

Win7 注意事项

• 系统必须打到 Win7 SP1 并安装基础安全补丁（TLS 1.2 支持，AI 联网必需）。
• 打包机与目标机位数保持一致（32 位更保险）。
• 已内置 AI 配置时可直接使用；服务失效后可在「设置」页更新。不联网仍能使用离线教案模板。
• 程序产生的配置与操作日志优先保存在 exe 同级 data\ 目录；目录不可写时自动回退到 %LOCALAPPDATA%\TeachBuddy\data\，避免因权限问题无法启动。
• 详细安装步骤、实机验收清单和常见故障处理见 docs/WIN7.md。