研途 StudyOS

个人考研每日计划、学习验收、知识债务和 AI 补救系统。项目是独立的 Next.js PWA，不会读取或修改“拾词”的数据。

已实现

• 今日驾驶舱：睡眠、精力、专注、建议负荷、各科进度和债务。
• 确定性计划引擎：最多两门主科、每科最多一个新知识点、债务降载、晚上禁止新增。
• 可执行任务卡：步骤、计时、卡点上报、AI 补救、退出测试。
• 知识账本：掌握阶段、掌握证据、脆弱标记、到期复习和错题债务。
• 三科教学路线：数学按“条件判断 → 直觉 → 示范决策 → 独立变式”，英语按“关键词 → 主干 → 从句边界 → 语义复述”，408 按“对象定义 → 结构图 → 操作轨迹 → 边界与复杂度”运行。
• 全局 AI 老师：从卡点诊断开始，完成分科讲解、检查题、答案评价和证据保存，不再只是一次性聊天。
• GPT 记忆计划：保存个人记忆、更新今日状态或完成关账时，OpenAI GPT 会结合已确认记忆、客观记录、债务与掌握证据生成每日任务；失败时安全降级到规则计划。
• 实际小测：每道题都有完整题干、考点、难度、标准答案、解析和评分点。英语使用具体单词与句子，数学使用可计算表达式，408 使用结构和操作轨迹。
• 真实内容录入：可手动新增知识点和今日任务，晚间新增规则仍然生效。
• 间隔复习调度：按 1、2、4、7、14、30 天推进，未来复习不计入今日债务。
• 个人学习记忆：用户确认的稳定资料与系统推导的动态洞察分开保存。
• 每日关账：五项复盘、报告摘要、明日计划生成。
• AI 图解课堂：概念卡、对比卡、流程卡、板书和讲义结构，支持打印或另存 PDF。
• PWA：Manifest、Service Worker、安装图标和基础离线应用壳。
• Mock 数据和 Mock AI：不配置任何密钥也可以体验完整流程。
• Codex Work 数据桥：Codex 可读取学习上下文，并通过受控动作队列更新状态、任务、卡点与验收证据。
• 数据保险箱：完整 JSON 备份、数量预览和二次确认恢复。

环境要求

• Node.js 22+
• pnpm 10+

安装与运行

cd D:\StudyOS
pnpm install
pnpm dev

打开 http://localhost:3000。

日常使用可以直接双击：

D:\StudyOS\启动研途StudyOS.bat

启动器会在后台启动生产服务并自动打开浏览器；源代码更新后才会重新构建。需要关闭本地服务时双击：

D:\StudyOS\停止研途StudyOS.bat

详细说明见 launcher\使用说明.txt。

在 iPad 或手机上打开

电脑和移动设备需要处于同一个局域网。启动脚本会显示类似 http://192.168.0.61:3000 的移动端地址，请在 iPad Safari 中打开该地址。 不要在 iPad 上输入 localhost:3000，因为 iPad 的 localhost 指向 iPad 自己。

Windows 防火墙只需要允许 StudyOS 使用 TCP 3000 端口；建议将远程地址限制为 LocalSubnet，不要把本地服务端口暴露到公网。

生产构建：

pnpm build
pnpm start

PWA 的完整安装和 Service Worker 行为应在生产构建下验证。部署时需要 HTTPS；本机 localhost 可用于开发测试。

GitHub Pages PWA

线上地址：https://jmhan001.github.io/studyos/

推送到 main 后，.github/workflows/deploy-pages.yml 会自动完成类型检查、 单元测试、静态 PWA 构建和 GitHub Pages 发布。

pnpm pages:build

GitHub Pages 是纯静态托管，因此线上版使用以下安全边界：

• 学习记录保存在当前浏览器的 IndexedDB 中，可使用“数据保险箱”导出和恢复。
• 默认 AI 教学使用内置 Mock 教学模板，不会在浏览器中保存或暴露 API Key。
• 如需让 iPad 上的 Pages PWA 使用真实 GPT，需要把 NEXT_PUBLIC_AI_PROXY_URL 指向一个安全的 StudyOS 服务端；OpenAI Key 仍只保存在该服务端。
• Codex Work 数据桥只在本机完整版本中启用。
• 本机版本继续支持服务端 AI 代理和 Work API，不受 Pages 模式影响。

AI 配置

页面顶部始终显示“AI 老师”按钮；也可以从今日任务的“这一步不会”、 知识页的“让老师带我学”和知识详情的“进入完整 AI 课堂”带着当前知识点进入。 AI 的答案评价只是教学建议，只有用户确认保存的无提示作答才会成为掌握证据。

复制环境变量示例：

Copy-Item .env.example .env.local

填写：

AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=your_key
AI_MODEL=gpt-5.6-terra
AI_REASONING_EFFORT=low
AI_PROVIDER=openai

AI_PROVIDER=openai 使用 OpenAI Responses API；auto 会对 OpenAI 地址使用 Responses API，对其他兼容地址使用 /chat/completions。AI Key 只在 Next.js Route Handler 中读取，不会进入浏览器或 IndexedDB。

未配置 AI_BASE_URL、AI_API_KEY、AI_MODEL，或设置 AI_PROVIDER=mock 时，系统自动使用内置教学模板。

个人记忆会在生成计划时作为请求上下文发送给已配置的 AI 服务。系统只发送学习所需字段，不发送 API Key；GPT 返回的任务还会再次经过本地硬规则校验，包括两门主科上限、晚间禁新增、时间容量和每科新增上限。

GitHub Pages 使用独立安全代理时：

# Pages 构建环境
NEXT_PUBLIC_AI_PROXY_URL=https://your-studyos-server.example.com

# 代理服务端
AI_ALLOWED_ORIGIN=https://jmhan001.github.io
AI_API_KEY=your_key

统一服务入口：

POST /api/ai/explainKnowledgePoint
POST /api/ai/generateVisualLesson
POST /api/ai/organizeRemediationNote
POST /api/ai/generateCheckQuestion
POST /api/ai/generatePracticeTest
POST /api/ai/evaluateAnswer
POST /api/ai/generateMemoryAwarePlan
POST /api/ai/analyzeMistake
POST /api/ai/generateLearningInsights
POST /api/ai/generateDailyReportNarrative
POST /api/ai/generateWeeklyReportNarrative
GET  /api/ai/status

本地数据

首版使用 Dexie + IndexedDB，数据库名为 studyos-v1。主要数据包括：

• UserProfileMemory：用户主动确认的目标、基础、偏好和限制。
• LearningInsight：系统根据客观记录生成的、有证据和有效期的动态观察。
• StudyTask、MasteryEvidence、KnowledgePoint、DebtItem。
• DailyCloseout、StudyPlan、VisualLessonDocument。

计划引擎的数据优先级：

用户明确设置 > 客观学习记录 > 已确认长期记忆 > 动态洞察 > AI 临时推测

任务完成不等于掌握。跨日稳定至少需要两个不同日期的无提示独立成功证据。

正确完成一次退出测试后，系统会按照当前证据自动安排下一次复习。未来已经排期的复习不会被显示为今日债务；失败后则会在次日优先重测。

数据备份与恢复

设置页顶部的“本地数据保险箱”可以导出所有 IndexedDB 数据，包括个人记忆、知识点、任务、掌握证据、债务、关账和报告。

恢复备份前会先展示数据数量，并要求输入“恢复”确认。恢复操作会替换当前浏览器中的全部 StudyOS 数据，因此建议先导出当前数据。

Codex Work 接入

StudyOS 页面打开后，会把 IndexedDB 中的学习上下文同步为本地 Work 快照。Codex 可使用稳定 JSON CLI 读取数据：

pnpm work status
pnpm work knowledge kp-limit-equivalent
pnpm work actions

受控写入示例：

pnpm work action update_day_state sleepHours=6.5 energyLevel=3
pnpm work action complete_task taskId=2026-07-24-math-focus actualDuration=82
pnpm work action add_confusion knowledgePointId=kp-limit-equivalent level=variant_blocked "content=加减式里不知道什么时候能替换"

动作会进入本地队列，打开的 StudyOS 页面通常在 4 秒内应用。具体约束与完整动作示例见 AGENTS.md。

Work 数据桥遵守以下边界：

• 不允许直接修改用户确认的长期资料。
• 不允许直接设置掌握阶段或掌握分。
• 退出测试先写入客观证据，再由掌握度引擎计算。
• AI 洞察必须携带证据引用，并保持为用户可确认、忽略或删除的动态分析。

拾词衔接

在“设置 > 工具与 AI”中填写拾词地址。StudyOS 只显示“打开拾词”按钮，完成后需要手动返回任务卡记录用时和退出测试。

如果在 iPad 上使用本机服务，请填写电脑的局域网地址，而不是 iPad 自己的 localhost。

质量检查

pnpm typecheck
pnpm lint
pnpm test
pnpm build

端到端测试：

pnpm exec playwright install chromium
pnpm test:e2e

Playwright 配置包含手机与 iPad 两组设备。

生产模式下验证 Service Worker 和离线重载：

pnpm build
$env:E2E_PRODUCTION="1"
pnpm exec playwright test e2e/pwa.spec.ts --project=phone --workers=1

目录说明

app/                 App Router 页面、Manifest、AI 与 Work Route Handler
components/          产品页面、交互组件和轻量 UI 组件
lib/                 类型、Dexie 数据库、仓储、计划、掌握与 Work 数据桥
scripts/             PWA 图标生成与 StudyOS Work CLI
tests/               规则与掌握证据单元测试
e2e/                 手机与平板核心闭环测试
public/sw.js          Service Worker

当前边界

• 单用户、单设备、本地优先，无账号和云同步。
• 真实 AI 必须联网；离线时计划、记录、关账和 Mock 数据仍可使用。
• 不包含完整题库、OCR、复杂知识图谱、图片上传和双向拾词同步。
• 动态洞察不会自动修改个人目标，也不会直接把知识点改成已掌握。