PhysicsOS

Name: PhysicsOS
Author: 122-syf-wcy

by 122-syf-wcy

Verified

PhysicsOS 是一个面向初高中物理学习的公益可视化智能体，通过 AI 理解题目并结合物理引擎，将抽象物理过程转化为可交互、可观察、可计算、可验证的真实物理场景。

233stars

12forks

TypeScript

Added 10/7/2026

View on GitHub Compare Download ZIP Scan for vulnerabilities

⚠️ Third-Party Software Notice

This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.

Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.

Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.

Read the Terms of Service

AI Agentsai-agentdeepseekeducationk12open-sourcephysics-educationphysics-enginephysics-simulationreacttypescript

Installation

# Add to your Claude Code skills
git clone https://github.com/122-syf-wcy/PhysicsOS

Getting Started

Guides for using ai agents skills like PhysicsOS.

Security ReportVerified

Last scanned: 10/7/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-10-07T10:53:24.527Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

Compare with similar skills

See how PhysicsOS compares with popular alternatives.

PhysicsOS vs hermes agent

See comparison

README.md

PhysicsOS

开源公益项目：面向初高中物理教学，公益定位。授权见 LICENSE（Apache License 2.0，OSI 认证的开源许可，允许修改、分发与商业使用）。项目欢迎外部开发者共同维护，参与方式见 CONTRIBUTING.md。

状态：公测开放（public beta）。正式入口为 https://physics.dongsiwei.com。账户体系、出卷专区、学习记录跨设备同步、生产部署、模型号池与管理员运维面板均已上线；接口与界面仍会迭代，真实教学反馈会直接影响后续优先级。

PhysicsOS 的定位是个人物理实验与学习平台，不是学校 LMS：不做班级管理、作业发布、提交批改和教学管理流程。教师和学生都以个人账号使用实验、题库、AI 助教与学习记录。

当前正式产品运行在 DeepSeek Harness Web Client 中，Physics Engine 负责结果，Observation 与统一 PhysicsCanvas 负责把结果变成可交互视觉。

界面截图

以下截图取自 2026-09-30 的正式生产站点，由 tests/acceptance/promo-shots.mjs 使用真实浏览器登录后自动拍摄（账号为专用演示账号，非管理员账号）。

平台首页	实验中心

串联电路	凸透镜成像规律

探究液体内部的压强	探究晶体的熔化过程

资源库	解题卡片

最后一张是一道题的完整回答：结论由力学引擎给出并逐条校验（重力分量、支持力、场景结构），右侧是同一个 PhysicsScene 在实验台里的可交互形态——AI 讲题、引擎给结果、场景可复现是这条链路的全部主张。

完整上线范围、生产复验和教师演示顺序见 docs/reports/BETA-LAUNCH-REPORT.md。

正式入口

唯一正式 Web Runtime Host：

vendor/deepseek-harness/apps/web
        +
@deepseek-ai/dsh-client-ui-physicsos

旧版独立原型 apps/web 已删除；浏览器端正式入口是 vendor harness 的 dsh-client-ui-physicsos。

当前能力

PhysicsOS 首页、侧栏、学生模式与正式 Harness 工作区
实验中心：力学/光学/声学/机械波/流体/热学/电场/磁场/电路/复合场/电磁感应/近代物理十二个分类；回旋加速器已接通时变场求解（不再是“即将支持”），新增纵波、反射折射、衍射、多普勒与光电效应模板；继续上次实验与按学习记录的薄弱点推荐
匀强磁场带电粒子实验：参数编辑、运行/暂停/单步/重置、倍速、时间轴、可观察量、数据、图像、推导和事件
五类力学场景：匀速、匀加速、平抛/斜抛、牛顿第二定律、无摩擦斜面
碰撞实验：弹性/非弹性（e = 0.5）/完全非弹性三类模板，独立碰撞引擎（多刚体圆-圆冲量求解、边界反射、恢复系数模型），动量守恒与动能守恒（弹性时）引擎验证，碰撞事件进时间轴；首页 Hero 是同一套圆形刚体 + 速度箭头的弹性碰撞小场景（装饰性，带轨迹尾迹与接触闪环）
电场与复合场：点电荷/多点电荷/匀强场/平行板偏转，速度选择器、质谱仪、E+B(+g)、多场区
直流动态电路：串联/并联/混联、开关、滑动变阻器准静态扫描、电流表/电压表读数、测电动势与内阻（MNA 直流引擎）；实验室 AI 助教 8 个电路意图（干路电流、路端电压、内阻、串联环流、并联分流、滑变扫描、功率守恒、理想电表），答案引用引擎派生量与 KCL/功率/路端电压定律/理想电表四项具名校验
电磁感应：导体棒切割磁感线（E = BLv，棒扫过磁场的动画）与磁通量变化（E = −dΦ/dt，楞次定律定方向）两类实验台；B/R/棒速/磁通量变化率实时可编辑，法拉第定律、楞次方向与回路欧姆定律三项引擎验证（31 个引擎测试）
几何光学成像：平面镜、凸透镜、凹面镜、凸面镜四类实验模板，引擎解析薄透镜/球面镜方程与五区成像规律并构造主光路（23 个引擎测试）；6 道光学黄金题（平面镜与凸透镜三区、凹面镜、凸面镜）已入题库
机械波：绳上的简谐横波（波形以 v = λf 平移、标记质点只振动不迁移）、双源干涉（路程差 Δ = nλ / (n+½)λ 判定加强减弱，合振幅 |2A·cos(πΔ/λ)|）、两端固定的弦驻波（L = nλ/2、f_n = n·v/2L、波节与波腹）三个实验台；A/f/v/Δ/L/n 实时可编辑，介质定波速、波源定频率，11 项引擎校验（27 个引擎测试）；6 道机械波黄金题已入题库
声学/流体/热学/杠杆：回声测距、阿基米德浮力、晶体熔化与比热容比较、杠杆平衡，各自有独立领域引擎
统一 PhysicsCanvas：粒子域共用坐标、网格、轨迹、矢量、标注与交互；电路以原理图范式接入同一画布
Question Space：80 道内置题（磁场 10、电场 19、力学 6、复合场 21、光学 6、电路 6、电磁感应 6、机械波 6），真实 Question Runtime、Engine、Verifier 与 Observation 链
Question → Lab：题目使用同一个 PhysicsScene revision 打开实验室（题面事实不可被实验污染）
基于 requestAnimationFrame 的连续动画；磁场微观周期使用稳定展示时钟，力学逐帧读取 Engine stateAt
平台公益模型：用户侧只暴露一个公共模型（平台公益模型），背后是管理员可随时增删的模型通道与号池（/physicsos/model-pool）——通道声明上游模型别名、按优先级分层轮换、key 加权轮转与失效冷却，换号池或换 key 不影响用户看到的模型名；额度来自公益站 token，见「致谢」
桌面、窄桌面和手机布局；手机导航完成后自动收起侧栏
Harness 会话里的模型可以真正调用物理引擎：Agent 预设「物理学习模式」（physics-student）挂载 @deepseek-ai/dsh-tool-physicsos，模型通过 physics_solve_question / physics_create_experiment / physics_scene_command / physics_simulate / physics_observe 等七个工具开实验、解题、改条件、模拟与校验，数值全部来自引擎（node tests/agent/headless-physics-acceptance.mjs 端到端门禁）

尚未完成

实验室 AI 助教抽屉仍以确定性意图匹配为主；模型化回答见 backlog AGENT_MODEL_BACKED_ANSWERS_BACKLOG，会话 Agent 已使用 physics-student 预设
web_search 仍指向 DeepSeek 官方端点，未迁移到第三方模型网关
第三方网关敏感词过滤仍需用真实题库采样；命中时可能返回 500 / new_api_error
当前为单副本；扩容前必须把 PHYSICSOS_SESSIONS_ROOT 切到共享文件系统
Content-Security-Policy 暂缓，当前启用 HSTS、nosniff、X-Frame-Options、 Referrer-Policy 与 Permissions-Policy
管理员 TOTP 已实现但当前生产账号尚未启用
桌面端保留为可选壳，暂不投入签名、公证、商店发布和自动更新
图片 / PDF / VLM 录题已经实现；真实卷库继续扩充仍需要可授权卷源与教师核验

界面会明确标记尚未接通的能力，不用占位成功状态冒充完成。

参与贡献

公测阶段最需要的是真实使用反馈与小而准的改动：

报问题 / 提需求：用 issue 模板（问题报告 / 功能请求 / 提问）。请写清复现步骤、期望与实际结果；界面问题附截图、物理问题附题干原文。
提 PR：先读 CONTRIBUTING.md。一个 PR 聚焦一个主题，并跑过 pnpm typecheck && pnpm lint && pnpm test；只改 Web 覆盖层时可用「验证」里的 :web 变体（更快）。
想找入手点：上面的「尚未完成」与「已知问题」就是当前 backlog。领域引擎与黄金题最容易上手——每个领域引擎都带独立测试，改完直接 pnpm test:web 验证。
安全问题：不要开公开 issue，按 SECURITY.md 私下上报。

已知问题

暂无阻塞性已知问题。pnpm typecheck:web 仅覆盖 src/（不含 tests/），若需检查测试代码请运行 vitest（测试经 esbuild 转译，不做完整类型检查）。

启动

前置环境：Node.js >=24，pnpm 由仓库 packageManager 字段管理。

正式 Web 入口依赖 Harness submodule 与 overlay 叠加，clone 后需要三步：

git submodule update --init --recursive
node scripts/overlay/harness-overlay.mjs apply
pnpm install

仓库使用 Git LFS 存放 UI/ 与 docs/ 下的大图，clone 前请先安装 git-lfs（未安装时这些 PNG 只会是 pointer 文件，不影响代码运行）。

然后启动：

pnpm dev

默认地址：http://127.0.0.1:3080/

也可以直接进入 Harness：

pnpm -C vendor/deepseek-harness dsh web

验证

pnpm typecheck
pnpm lint
pnpm test
pnpm build

需要只验证正式 Web 覆盖层时：

pnpm typecheck:web
pnpm lint:web
pnpm test:web
pnpm build:web

视觉资产

UI/generated/：生成模型输出的 4K/原始资产与生成元数据
UI/generated/mascot/：IP 形象「小 Q」的透明原图（wave / think / search 三个姿态）
UI/generated/collision/：碰撞实验教学插画（弹性/完全非弹性/动量守恒台/牛顿摆，1024×1024 PNG 与 manifest 元数据）
vendor/deepseek-harness/apps/web/public/physicsos/：经过网页压缩的正式运行资产（mascot/ 下为 160/320/640 三档 WebP）
scripts/design/cutout-mascot.py：把白底渲染切成保留柔和阴影的透明图并导出网页尺寸
scripts/design/imagegen-client.mjs：OpenAI 兼容图像生成客户端（默认端点 https://zz.211b.site，模型 gpt-image，含模型/尺寸回退与 5xx 退避重试，输出 PNG + 元数据 manifest）

首页 Hero 是一个实时弹性碰撞小场景加小 Q（装饰性，不进入物理引擎）；入口卡片仍使用真实磁场实验器材图，原始 4K 文件保留在 UI/generated/，网页不直接加载 8-10 MB 原图。IP 与动效规范见 docs/06-UI-DESIGN-SYSTEM.md §3.1 与 §37。

架构边界

Question / Lab
      ↓
PhysicsScene (single source of truth)
      ↓
Engine → Verifier → Observation
      ↓
SceneVisualModel → PhysicsCanvas

React 不计算物理解答。
Renderer 不决定物理事实。
Harness core 的 Agent Loop、Session 和 Tools 不做 PhysicsOS 特化修改。
领域包位于根目录 packages/，正式界面适配层位于 vendor/deepseek-harness/packages/client/ui-physicsos/。
自有代码与上游代码的规模与归属核对：见 docs/ARCHITECTURE-OWNERSHIP.md。

详细边界见 docs/HARNESS-UPSTREAM.md 与 docs/HARNESS-UI-OVERLAY.md。

Harness overlay

正式 UI 代码放在 overlays/harness/，由脚本叠加进 pin 住的上游 submodule，仓库不改上游历史：

node scripts/overlay/harness-overlay.mjs apply     # overlay → vendor/deepseek-harness
node scripts/overlay/harness-overlay.mjs capture   # vendor/deepseek-harness → overlay

说明见 overlays/harness/README.md。

致谢

平台的公益模型额度来自下列公益站，而且是两处都在用：

产品运行时：学生和老师的每一次解题都走「平台公益模型」号池，池子接的就是它们的 token；
项目开发本身：写代码、补测试、排查线上问题时用到的模型调用，同样来自这些站点。

一个公益教学项目能跑起来，靠的是这些站点：

公益站	地址
黑与白公益站	https://ai.hybgzs.com/panel
咕咕嘎嘎公益站	https://api.fengshao1227.com/
lucky API 公益站	https://new.lucky0625.qzz.io/
luckyg 公益站	https://luckyg.131518.xyz/

这些站点各自独立运营，与 PhysicsOS 没有隶属关系：可用模型、额度与稳定性由它们自行决定，本项目不对其可用性作任何承诺，也请勿把这里的地址当作稳定的生产依赖。如果你是其一的运营者并希望调整署名或链接方式，开个 issue 即可。

项目已在 LINUX DO 社区发布并认可，欢迎社区的朋友来试用与反馈。

许可与用途

自有代码与文档：LICENSE，Apache License 2.0（OSI 认证的开源许可），允许使用、修改、分发与商业使用，需保留版权、许可与 NOTICE 声明。
项目定位仍是面向初高中物理教学的公益项目；许可放开不等于承诺提供商业支持或 SLA，安全问题上报渠道见 SECURITY.md。
第三方组件与上游归属：见 NOTICE.md。DeepSeek Harness 为上游 MIT 项目，本仓库只分发自有插件与改动补丁；其中的 C-Eval 题库数据仍为 CC BY-NC-SA 4.0（非商业），不随本仓库 Apache-2.0 授权。
视觉资产 UI/generated/** 由图像生成模型产出，随仓库按 Apache-2.0 授权；如需商用请自行核对生成模型服务方的条款。

Frequently Asked Questions

What is PhysicsOS?

PhysicsOS is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by 122-syf-wcy. PhysicsOS 是一个面向初高中物理学习的公益可视化智能体，通过 AI 理解题目并结合物理引擎，将抽象物理过程转化为可交互、可观察、可计算、可验证的真实物理场景。. It has 233 GitHub stars.

Is PhysicsOS safe to use?

Yes. PhysicsOS passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install PhysicsOS?

Clone the repository with "git clone https://github.com/122-syf-wcy/PhysicsOS" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is PhysicsOS written in?

PhysicsOS is primarily written in TypeScript. It is open-source under 122-syf-wcy on GitHub, so you can review or fork the full source.

Are there alternatives to PhysicsOS?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh PhysicsOS against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

274,491

40,964

JavaScript

AI Agentsai-agentsanthropic

The agent that grows with you

251,785

54,163

Python

AI Agentsaiai-agent

View details

Compare

skills

by mattpocock

Skills for Real Engineers. Straight from my .agents directory.

250,518

21,171

Shell

AI Agents

View details

Compare

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

20,863

Shell

AI Agentsaibrainstorming

View details

Compare

opencode

by anomalyco

The open source coding agent.

211,779

28,169

TypeScript

AI Agents

View details

Compare

n8n

by n8n-io

Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.

206,801

61,013

TypeScript

MCP Serversaiapis

View details

Compare

Browse all AI Agents skills

value-for-fable agenticmail

PhysicsOS

开源公益项目：面向初高中物理教学，公益定位。授权见 LICENSE（Apache License 2.0，OSI 认证的开源许可，允许修改、分发与商业使用）。项目欢迎外部开发者共同维护，参与方式见 CONTRIBUTING.md。

状态：公测开放（public beta）。正式入口为 https://physics.dongsiwei.com。账户体系、出卷专区、学习记录跨设备同步、生产部署、模型号池与管理员运维面板均已上线；接口与界面仍会迭代，真实教学反馈会直接影响后续优先级。

当前正式产品运行在 DeepSeek Harness Web Client 中，Physics Engine 负责结果，Observation 与统一 PhysicsCanvas 负责把结果变成可交互视觉。

界面截图

以下截图取自 2026-09-30 的正式生产站点，由 tests/acceptance/promo-shots.mjs 使用真实浏览器登录后自动拍摄（账号为专用演示账号，非管理员账号）。

平台首页	实验中心

串联电路	凸透镜成像规律

探究液体内部的压强	探究晶体的熔化过程

资源库	解题卡片

完整上线范围、生产复验和教师演示顺序见 docs/reports/BETA-LAUNCH-REPORT.md。

正式入口

唯一正式 Web Runtime Host：

vendor/deepseek-harness/apps/web
        +
@deepseek-ai/dsh-client-ui-physicsos

旧版独立原型 apps/web 已删除；浏览器端正式入口是 vendor harness 的 dsh-client-ui-physicsos。

当前能力

PhysicsOS 首页、侧栏、学生模式与正式 Harness 工作区
实验中心：力学/光学/声学/机械波/流体/热学/电场/磁场/电路/复合场/电磁感应/近代物理十二个分类；回旋加速器已接通时变场求解（不再是“即将支持”），新增纵波、反射折射、衍射、多普勒与光电效应模板；继续上次实验与按学习记录的薄弱点推荐
匀强磁场带电粒子实验：参数编辑、运行/暂停/单步/重置、倍速、时间轴、可观察量、数据、图像、推导和事件
五类力学场景：匀速、匀加速、平抛/斜抛、牛顿第二定律、无摩擦斜面
碰撞实验：弹性/非弹性（e = 0.5）/完全非弹性三类模板，独立碰撞引擎（多刚体圆-圆冲量求解、边界反射、恢复系数模型），动量守恒与动能守恒（弹性时）引擎验证，碰撞事件进时间轴；首页 Hero 是同一套圆形刚体 + 速度箭头的弹性碰撞小场景（装饰性，带轨迹尾迹与接触闪环）
电场与复合场：点电荷/多点电荷/匀强场/平行板偏转，速度选择器、质谱仪、E+B(+g)、多场区
直流动态电路：串联/并联/混联、开关、滑动变阻器准静态扫描、电流表/电压表读数、测电动势与内阻（MNA 直流引擎）；实验室 AI 助教 8 个电路意图（干路电流、路端电压、内阻、串联环流、并联分流、滑变扫描、功率守恒、理想电表），答案引用引擎派生量与 KCL/功率/路端电压定律/理想电表四项具名校验
电磁感应：导体棒切割磁感线（E = BLv，棒扫过磁场的动画）与磁通量变化（E = −dΦ/dt，楞次定律定方向）两类实验台；B/R/棒速/磁通量变化率实时可编辑，法拉第定律、楞次方向与回路欧姆定律三项引擎验证（31 个引擎测试）
几何光学成像：平面镜、凸透镜、凹面镜、凸面镜四类实验模板，引擎解析薄透镜/球面镜方程与五区成像规律并构造主光路（23 个引擎测试）；6 道光学黄金题（平面镜与凸透镜三区、凹面镜、凸面镜）已入题库
机械波：绳上的简谐横波（波形以 v = λf 平移、标记质点只振动不迁移）、双源干涉（路程差 Δ = nλ / (n+½)λ 判定加强减弱，合振幅 |2A·cos(πΔ/λ)|）、两端固定的弦驻波（L = nλ/2、f_n = n·v/2L、波节与波腹）三个实验台；A/f/v/Δ/L/n 实时可编辑，介质定波速、波源定频率，11 项引擎校验（27 个引擎测试）；6 道机械波黄金题已入题库
声学/流体/热学/杠杆：回声测距、阿基米德浮力、晶体熔化与比热容比较、杠杆平衡，各自有独立领域引擎
统一 PhysicsCanvas：粒子域共用坐标、网格、轨迹、矢量、标注与交互；电路以原理图范式接入同一画布
Question Space：80 道内置题（磁场 10、电场 19、力学 6、复合场 21、光学 6、电路 6、电磁感应 6、机械波 6），真实 Question Runtime、Engine、Verifier 与 Observation 链
Question → Lab：题目使用同一个 PhysicsScene revision 打开实验室（题面事实不可被实验污染）
基于 requestAnimationFrame 的连续动画；磁场微观周期使用稳定展示时钟，力学逐帧读取 Engine stateAt
平台公益模型：用户侧只暴露一个公共模型（平台公益模型），背后是管理员可随时增删的模型通道与号池（/physicsos/model-pool）——通道声明上游模型别名、按优先级分层轮换、key 加权轮转与失效冷却，换号池或换 key 不影响用户看到的模型名；额度来自公益站 token，见「致谢」
桌面、窄桌面和手机布局；手机导航完成后自动收起侧栏
Harness 会话里的模型可以真正调用物理引擎：Agent 预设「物理学习模式」（physics-student）挂载 @deepseek-ai/dsh-tool-physicsos，模型通过 physics_solve_question / physics_create_experiment / physics_scene_command / physics_simulate / physics_observe 等七个工具开实验、解题、改条件、模拟与校验，数值全部来自引擎（node tests/agent/headless-physics-acceptance.mjs 端到端门禁）

尚未完成

实验室 AI 助教抽屉仍以确定性意图匹配为主；模型化回答见 backlog AGENT_MODEL_BACKED_ANSWERS_BACKLOG，会话 Agent 已使用 physics-student 预设
web_search 仍指向 DeepSeek 官方端点，未迁移到第三方模型网关
第三方网关敏感词过滤仍需用真实题库采样；命中时可能返回 500 / new_api_error
当前为单副本；扩容前必须把 PHYSICSOS_SESSIONS_ROOT 切到共享文件系统
Content-Security-Policy 暂缓，当前启用 HSTS、nosniff、X-Frame-Options、 Referrer-Policy 与 Permissions-Policy
管理员 TOTP 已实现但当前生产账号尚未启用
桌面端保留为可选壳，暂不投入签名、公证、商店发布和自动更新
图片 / PDF / VLM 录题已经实现；真实卷库继续扩充仍需要可授权卷源与教师核验

界面会明确标记尚未接通的能力，不用占位成功状态冒充完成。

参与贡献

公测阶段最需要的是真实使用反馈与小而准的改动：

报问题 / 提需求：用 issue 模板（问题报告 / 功能请求 / 提问）。请写清复现步骤、期望与实际结果；界面问题附截图、物理问题附题干原文。
提 PR：先读 CONTRIBUTING.md。一个 PR 聚焦一个主题，并跑过 pnpm typecheck && pnpm lint && pnpm test；只改 Web 覆盖层时可用「验证」里的 :web 变体（更快）。
想找入手点：上面的「尚未完成」与「已知问题」就是当前 backlog。领域引擎与黄金题最容易上手——每个领域引擎都带独立测试，改完直接 pnpm test:web 验证。
安全问题：不要开公开 issue，按 SECURITY.md 私下上报。

已知问题

暂无阻塞性已知问题。pnpm typecheck:web 仅覆盖 src/（不含 tests/），若需检查测试代码请运行 vitest（测试经 esbuild 转译，不做完整类型检查）。

启动

前置环境：Node.js >=24，pnpm 由仓库 packageManager 字段管理。

正式 Web 入口依赖 Harness submodule 与 overlay 叠加，clone 后需要三步：

git submodule update --init --recursive
node scripts/overlay/harness-overlay.mjs apply
pnpm install

仓库使用 Git LFS 存放 UI/ 与 docs/ 下的大图，clone 前请先安装 git-lfs（未安装时这些 PNG 只会是 pointer 文件，不影响代码运行）。

然后启动：

pnpm dev

默认地址：http://127.0.0.1:3080/

也可以直接进入 Harness：

pnpm -C vendor/deepseek-harness dsh web

验证

pnpm typecheck
pnpm lint
pnpm test
pnpm build

需要只验证正式 Web 覆盖层时：

pnpm typecheck:web
pnpm lint:web
pnpm test:web
pnpm build:web

视觉资产

UI/generated/：生成模型输出的 4K/原始资产与生成元数据
UI/generated/mascot/：IP 形象「小 Q」的透明原图（wave / think / search 三个姿态）
UI/generated/collision/：碰撞实验教学插画（弹性/完全非弹性/动量守恒台/牛顿摆，1024×1024 PNG 与 manifest 元数据）
vendor/deepseek-harness/apps/web/public/physicsos/：经过网页压缩的正式运行资产（mascot/ 下为 160/320/640 三档 WebP）
scripts/design/cutout-mascot.py：把白底渲染切成保留柔和阴影的透明图并导出网页尺寸
scripts/design/imagegen-client.mjs：OpenAI 兼容图像生成客户端（默认端点 https://zz.211b.site，模型 gpt-image，含模型/尺寸回退与 5xx 退避重试，输出 PNG + 元数据 manifest）

架构边界

Question / Lab
      ↓
PhysicsScene (single source of truth)
      ↓
Engine → Verifier → Observation
      ↓
SceneVisualModel → PhysicsCanvas

React 不计算物理解答。
Renderer 不决定物理事实。
Harness core 的 Agent Loop、Session 和 Tools 不做 PhysicsOS 特化修改。
领域包位于根目录 packages/，正式界面适配层位于 vendor/deepseek-harness/packages/client/ui-physicsos/。
自有代码与上游代码的规模与归属核对：见 docs/ARCHITECTURE-OWNERSHIP.md。

详细边界见 docs/HARNESS-UPSTREAM.md 与 docs/HARNESS-UI-OVERLAY.md。

Harness overlay

正式 UI 代码放在 overlays/harness/，由脚本叠加进 pin 住的上游 submodule，仓库不改上游历史：

node scripts/overlay/harness-overlay.mjs apply     # overlay → vendor/deepseek-harness
node scripts/overlay/harness-overlay.mjs capture   # vendor/deepseek-harness → overlay

说明见 overlays/harness/README.md。

致谢

平台的公益模型额度来自下列公益站，而且是两处都在用：

产品运行时：学生和老师的每一次解题都走「平台公益模型」号池，池子接的就是它们的 token；
项目开发本身：写代码、补测试、排查线上问题时用到的模型调用，同样来自这些站点。

一个公益教学项目能跑起来，靠的是这些站点：

公益站	地址
黑与白公益站	https://ai.hybgzs.com/panel
咕咕嘎嘎公益站	https://api.fengshao1227.com/
lucky API 公益站	https://new.lucky0625.qzz.io/
luckyg 公益站	https://luckyg.131518.xyz/

项目已在 LINUX DO 社区发布并认可，欢迎社区的朋友来试用与反馈。

许可与用途

自有代码与文档：LICENSE，Apache License 2.0（OSI 认证的开源许可），允许使用、修改、分发与商业使用，需保留版权、许可与 NOTICE 声明。
项目定位仍是面向初高中物理教学的公益项目；许可放开不等于承诺提供商业支持或 SLA，安全问题上报渠道见 SECURITY.md。
第三方组件与上游归属：见 NOTICE.md。DeepSeek Harness 为上游 MIT 项目，本仓库只分发自有插件与改动补丁；其中的 C-Eval 题库数据仍为 CC BY-NC-SA 4.0（非商业），不随本仓库 Apache-2.0 授权。
视觉资产 UI/generated/** 由图像生成模型产出，随仓库按 Apache-2.0 授权；如需商用请自行核对生成模型服务方的条款。