交互式学科学习与职业情景实训。
星序把知识讲解、动手实验和教学任务放进浏览器。学生可以改变参数观察规律、追踪程序执行，也可以进入职业现场采访人物、核实资料并完成作品；教师可以组织资源、编排课程，在学校审核后发布，并回看学习记录。
项目包含学术主站与职业教育子站。两者通过教育方向入口衔接，分别维护业务服务和数据，适合本地课程演示、毕业设计与交互学习内容开发。
在线体验学术静态演示 · 运行完整版本 · 了解技术设计 · 查看当前计划
| 学习空间 | 当前内容 | 可以尝试的操作 |
|---|---|---|
| 工科试验室 | 数学、物理、化学、算法、生物，90 项交互实验 | 调整双摆初始角差，比较轨迹和末端距离；改变色谱参数，观察色带与检测峰的对应关系 |
| 代码空间 | 6 组课程目录、18 项学习活动 | 先预测结果，再运行代码、追踪变量并修正判断；按需加载 JavaScript、Python、C、C++ 浏览器学习运行时 |
| 未来星系 | 地球与宇宙、工程、数据、信息、材料与人文，19 项活动 | 通过课程目录、Canvas 观测和按需三维交互，探索跨学科问题 |
| 职业教育 | 融媒体岗位下的 5 门课程，复用蟳埔、榕江和山地景区场景 | 调查现场、采访人物、核对来源、记录笔记、编辑作品，并在动态服务中查看过程评价与教师复核 |
前三个空间共 127 个活动身份。教师创建的授课课程、资源模板和职教情景课程另行管理；同一个实验可以被不同课程引用，课程成员和学习记录各自保留。
第一次体验，可以先选一项实验改变一个变量，再进入代码空间完成一次“预测—运行—追踪—修正”。需要了解教学管理时，切换演示身份观察教师编排、管理员审核、教师发布和学生学习的过程；需要观察真实持久化与职教模型交互时，使用下方本地入口。
星云开场和透视课程轮盘提供空间化导航，具体实验使用 DOM、Canvas 或 Three.js 表达适合观察的关系。计算与绘制分别组织：例如双摆实验用四阶 Runge–Kutta 方法推进状态，再将轨迹、分离距离和能量误差显示出来。代表性模型的公式、单位、假设和可复算样例见 学科实验指南。
教师可以引用现有活动、使用受控函数或图表模板，配合讲解、媒体、检查点和作业编排课程。课程支持独立派生、共同教师共享草稿、同源内容同步预览和候选审核；正式发布固定到已审核的内容快照。
学生的检查点、作业与评分记录保留所见版本和来源。重新提交、退回与改分追加历史，旧结果是否沿用由发布策略和认定记录表达。具体流程及当前接入范围见 课程工作流 和 学习历史。
学术主站提供按配置启用的 AI 助教接口。职教子站进一步将人物知识范围、交流历史、课程证据与世界状态结合：模型提出回答或行动建议，程序核验允许动作、权限和状态后再提交变化，教师保留复核入口。
职教内容库保存来源版本、片段、知识、授权和审核记录，蟳埔旗舰课程已接入基于资料与本地向量的检索链。实时模型需要单独配置；公开导览使用预设访谈和本地草稿，两种体验的入口与能力见 职教运行说明。
| 方式 | 入口 | 数据与适用场景 |
|---|---|---|
| 学术静态演示 | GitHub Pages | 三角色内存样例，刷新重置；适合先看界面和交互。线上制品版本以实际构建信息为准 |
| 学术本机完整版本 | http://127.0.0.1:9001/ |
FastAPI、Cookie 会话和 SQLite，保存真实本机账号、课程与学习记录 |
| 职教本机动态服务 | 默认 http://127.0.0.1:4173/ |
独立 Fastify API、PGlite 和文件存储，适合观察人物交互、作品提交和教师流程 |
| 职教公开导览 | 按 第 8 节 独立构建 | 预设场景和浏览器本地草稿，不依赖动态 API |
教育方向中的“职业教育”默认跳转本机 4173，可通过 VITE_VOCATIONAL_APP_URL 修改。打开学术 Pages 不会启动职教服务；两站也尚未共享账号、课程或成绩。
准备 Git、Python 3.12+，以及仓库锁定的 Node 24.20.0 / npm 11.19.0。从 Windows PowerShell 执行：
git clone https://github.com/falling-feather/Astra.git
cd Astra
powershell -ExecutionPolicy Bypass -File .\astra-local.ps1 -BootstrapAdmin首次运行会准备 Python 环境、安装锁定依赖、构建前端、执行数据库迁移，并交互创建首个管理员。密码输入不回显。成功后打开 http://127.0.0.1:9001/；再次启动可省略 -BootstrapAdmin，使用 Ctrl+C 停止。
需要合成演示账号、隔离数据目录、外置 Python 环境或自管解释器时，按 本机完整版本 操作。数据默认保存在 %LOCALAPPDATA%\Astra\local-preview\astra-local.sqlite3。
职教采用独立 pnpm 工作区，锁定 pnpm 11.9.0；可共用上方 Node 环境，Windows 启动器还要求 corepack 命令可用。依赖准备见 运行环境。从仓库根目录独立启动：
powershell -ExecutionPolicy Bypass -File .\zhijiao\启动职教星云.ps1已完成学术主站初始化后，也可以联合启动两站并复用职教数据：
powershell -ExecutionPolicy Bypass -File .\start-joined-stack.ps1 -ReuseVocationalData联合启动器不带 -ReuseVocationalData 时，为职教创建新的演示数据目录；这与职教独立启动默认复用数据的行为不同。依赖准备、模型选择、端口与备份方式统一见 职教运行与数据。
| 部分 | 核心技术 | 代码位置 |
|---|---|---|
| 学术门户 | TypeScript、Vite、原生 DOM、Three.js | qianduan/src/：界面、角色工作区、API 适配、状态与渲染 |
| 学术实验与编程活动 | JavaScript、HTML、CSS、Canvas、浏览器学习运行时 | pages/、shared/、codevis/ |
| 学术业务后端 | Python、FastAPI、Pydantic、SQLAlchemy、Alembic | backend/app/、backend/alembic/ |
| 职教前端与 API | React、TypeScript、Vite；Node.js、Fastify | zhijiao/apps/web/、zhijiao/apps/api/ |
| 职教业务模块 | 共享契约、课程、世界规则、检索上下文、模型网关、智能体与媒体处理 | zhijiao/packages/ |
| 数据存储 | 主站默认 SQLite，可配置 MySQL；职教使用 PGlite 与 JSON/JSONL 文件 | 表结构、数据职责与边界见 开发者手册 |
主站由 FastAPI 决定权限、发布与学习结果，职教业务由自己的 Fastify 服务处理。根目录 server/ 中的 Node/C++ 服务承担兼容静态服务和构建验证。两套业务实现及其接入关系见 系统架构。
| 你要做的事 | 建议入口 |
|---|---|
| 了解作品范围与当前交付 | 00 项目总纲 |
| 理解接口、课程版本、学习记录与数据库 | 01 开发者手册 |
| 核对业务规则、待办和恢复顺序 | 02 更新规划 |
| 查阅真实提交、历史验证与阶段问题 | 03 发布历史 |
| 配置运行、数据、模型与发布 | 04 部署指南 |
| 调整界面、导航和实验交互 | 05 UI 规范 |
| 增加实验并核验科学模型 | 15 学科实验指南 |
| 单独开发学术前端或 API | 前端说明、后端说明 |
按改动选择最接近的检查。下例在仓库根目录执行，假设已完成默认本机初始化；若使用外置或自管 Python，把解释器路径换成实际路径。原实验的根目录检查另需执行一次 npm ci：
# 学术业务、门户和原实验
.\.venv\Scripts\python.exe -m pytest backend
npm --prefix qianduan test
npm --prefix qianduan run build
npm --prefix qianduan run verify:package
npm ci
npm test
# 职教工作区：已完成职教依赖安装后执行
Push-Location .\zhijiao
pnpm typecheck
pnpm test
Pop-Location
# 提交前检查
git diff --check各命令的依赖和范围见 最小验证。历史通过记录属于对应提交，当前实现与未完成事项分别由 01、02 维护。
当前以 Web、本机持久化和展示为主要交付范围。课程版本、审核与学习历史已有实现，部分实验整页导航后的记录接线及其他已知回归仍需处理；具体问题与暂停后的继续事项见 当前任务状态。完整移动端精调、公网业务运营、正式隔离判题与真实课堂效果不在当前交付范围。
main 保存完整源码，qianduan 保存学术 Pages 静态制品。代码更新和线上制品发布分别进行，发布流程见 前端构建与发布。
使用条件及第三方资源说明见 LICENSE.md。浏览器运行时、模型参考与媒体素材按各自来源记录维护。