页间 · Pagehaven 源码阅读指南

维护者更新作品元数据和文字层后，希望发布一个浏览器能直接打开的阅读站。这里沿静态构建和发布交接解释数据怎样进入页面，以及为什么页面、检索库和发布清单必须来自同一次构建。

阅读路径

读者目标	从这里开始	读完后获得什么
理解一次真实运行	主流程与拒绝边界	能解释输入、交接和结果，知道失败在哪里出现
定位修改入口	按职责找代码	在已声明范围内找到入口、依赖和验证位置
审核解释依据	源码证据与两遍调查	区分直接证据、范围限制和未执行验证
复核文档质量	读者模拟与剩余风险	看懂本指南能回答什么，哪些问题仍需验证
查看同步边界	指南变更记录	找到源码锚点与本轮验证范围

覆盖范围

覆盖构建命令编排、清单与检索库交接、站点生成、目标预算及部署回执边界；另记录配色控件与主题变量的兼容接线。其余浏览器阅读偏好、备份恢复、在线检索细节、OCR 导入与平台真实部署验收未展开。当前工作区实现不等于已发布版本。

本包采用 Lite 加代码地图：主流程先建立行为模型，地图用于定位，证据页用于审计。源码和脚本是实现事实的依据；旧文档或测试文件的存在不代表本轮实跑通过。

运行与验证入口

以下命令在仓库根运行；启动命令会占用开发端口，构建命令可能写业务产物，请先阅读根规则。

npm ci
# 以下会生成业务构建产物，先确认自己的预览输出可替换
npm run build
# 维护者验收命令；实际执行记录见 change-log.md
npm run check
npm test

文档站的启动与构建命令见根 README 的文档入口。文档构建只验证说明页面，不证明业务可用或已部署。

文档构建依赖

文档站独立安装依赖；根目录的依赖审计不覆盖它。更新后运行 npm --prefix docs-site ci、npm --prefix docs-site audit 和 npm --prefix docs-site run docs:build，再检查默认主题导航、本地搜索及开发模式的 Markdown 引用热更新。

当前在文档依赖配置（仓库文件：docs-site/package.json）中精确锁定 VitePress 2.0.0-alpha.21（预发布版），由其原生依赖 Vite 8；锁文件固定实际安装版本，不使用跨主要版本的传递依赖覆盖。原稳定版 1.6.4 的 Vite 5 / esbuild 链仍有已知告警；选择预发布版意味着后续升级仍须重跑文档验证，不自动跟随 next 标签。已验证项目现有默认主题、静态指南和本地搜索，不据此承诺其他扩展兼容。

新版默认会重定位被引用 Markdown 的相对链接；文档配置（仓库文件：docs-site/.vitepress/config.mts）显式关闭 markdown.include.rebaseRelativeUrls，继续由现有 guideLinks 按正文来源转换，避免同一链接被处理两次。官方迁移记录

开发模式下正文可热更新，但已打开的搜索框可能继续使用旧索引；编辑后刷新页面再检查搜索，被引用正文仍未更新时重启 docs:dev。这不是已验证的实时搜索能力；正式静态构建会重新生成完整索引。

既有专题

• 数据模型与平台约束（仓库文件：docs/ARCHITECTURE.md）

独立网页构建会把文档目录之外的仓库链接显示为精确文件路径，避免产生失效跳转；原始 Markdown 仍保留可核对的源码链接。站点只发布指南，源码和本机资源不会随文档打包。

证据状态：除特别标注外，本页基于当前源码已确认。