维护文档站

本站采用 VitePress 1.6.4 稳定版和官方默认主题，不使用 2.0 alpha。正文、图片、导航和构建分别维护，避免重复保存文章后产生内容差异。

leximeet.github.io/
├─ docs/                      # 唯一正文与公开图片
│  ├─ index.md
│  ├─ 产品文档/ 使用文档/ 开发文档/ 设计文档/ 项目文档/
│  └─ public/                 # 图片路径从站点根开始
├─ website/
│  ├─ docs -> ../docs         # 准备脚本建立，Git 忽略
│  └─ .vitepress/             # 默认主题配置、样式和输出
├─ scripts/                   # 软链保护和正文检查
└─ .github/workflows/         # 验证与手动 Pages 部署

同一路径启动

bash

npm ci
npm run dev                   # 开发服务器，仅监听回环地址
npm run verify                # 测试、链接、安全、格式和静态构建
npm run test:dev              # 真实 dev 冷启动回归
npm run serve                 # 预览同一份生产输出

三个入口都先验证 website/docs，再从同一个 website 根目录运行。构建使用 VitePress，配置为 srcDir: './docs'、outDir: '.vitepress/dist'，Pages 上传 website/.vitepress/dist；预览使用 Vite 的静态 preview，读取同一目录并明确绑定 127.0.0.1。稳定 VitePress 1.6.4 的内置 preview 不支持绑定地址，不能仅凭传入 host 参数宣称只监听回环。普通预览默认 4173，开发默认 5173；占用时可通过 npm run serve -- --port 4174 指定端口。

准备脚本只允许本仓真实根 docs，已存在的 website/docs 必须指向它。错误软链或真实目录会报错，不自动删除或覆盖；正常情况下不用维护两套文件。

Vite 的 resolve.preserveSymlinks: true 保留入口的路径身份，避免正文被解析为入口外的真实路径，导致中文相对链接与页面索引不一致；死链检查保持开启。

自动化检查

bash

npm run verify
npx playwright install chromium
npm run test:dev
npm run test:ui

UI 检查使用无头 Chromium，不操作系统鼠标与键盘，不接管用户已有服务。两套测试各有职责：

test:dev 真正运行 npm run dev，独立 4175 端口、每次新建临时优化缓存；验证首页、中文深链、图解和主题切换。结束仅清理本轮缓存。
test:ui 在 4174 预览本次构建，验证全部正文、明暗图解、页面错误、本地搜索和移动导航。正文或图片变更后应重新构建。

两者在 CI 串行运行。不能用生产预览通过证明开发服务可用：Rollup 构建能转换 CommonJS，但 dev 直接模块加载需要正确的依赖预构建。本站明确设置 optimizeDeps.include: ['mermaid > fastdom']，修复曾使 dev 整页白屏的嵌套模块 default-export 错误，而非依赖用户旧缓存。

稳定 VitePress 1.6.4 原依赖的旧 Vite/esbuild 有已公布的开发服务漏洞。本站用 npm override 将构建链固定为 Vite 6.4.3（esbuild 0.25+），不切换 VitePress alpha；变更需同时检查锁文件、审计、静态构建、真实 dev、生产预览与 UI。依据：Vite 源码映射漏洞、esbuild 开发服务漏洞、Vite 迁移说明。

搜索和图表

本地搜索索引与站点一起构建，不接入 Algolia 或遥测。Mermaid 使用严格安全模式、文本标签和明暗主题；不在正文使用 init 指令或 click 脚本。节点文案简短，长解释写在图旁；移动端允许图表内部横向滚动，不让页面溢出。

默认主题保留官方导航、目录和阅读交互，补充品牌色、图表间距与首页介绍插槽。diagram-fence.mjs 只接管 Mermaid 围栏，LexiMeetDiagram.vue 使用 strict 渲染并串行化全局初始化；其他代码块继续使用官方渲染器。网站与仓库导出的 SVG 共用 diagram-theme.mjs，另提供纯 Node 的 check:diagrams -- --repo，供各仓维护原图、亮暗 SVG、SHA 和正文引用的一致性。详细约束见图表规范。明暗 logo 使用现有自有品牌素材；应用图片使用公开仓库真实截图，出处在素材说明。

首页与动画

首页只保留产品介绍、桌面端/浏览器/开发入口和常用文档。学习规则、采集参数、连接资料归属和版本边界写在对应正文，避免首页重复解释。

Layout.vue 通过官方 home-hero-info 插槽加载 HomeHeroInfo.vue，按钮和导航仍由默认主题生成。产品名称、介绍与链接只维护在 docs/index.md，组件不另存文案副本。

介绍文字通过 CSS 逐字显示，约 1.5 秒完成，只播放一次，不循环删除，结束后隐藏光标。完整文字预先占位，打字动画不会改变卡片或按钮的位置；读屏器读取完整标题，视觉动画层标记 aria-hidden。开启 prefers-reduced-motion: reduce 时立即显示全文；禁用 JavaScript 时，正文和链接仍然可用。测试会测量实际浏览器中的动画和布局，覆盖 320/390/1107/1320 宽度，并检查明暗主题与静态页面。

当前动画参考了Magic UI打字组件的单次出现节奏和Aceternity打字效果。它们主要面向 React 组件生态；本站用 Vue 和 CSS 实现，没有新增动画依赖。Motion有Vue版，但当前效果无需额外运行库，文档首页也不使用 3D 库。

使用官方 vitepress/theme-without-fonts 入口与系统字体，不分发额外字体。构建按实际浏览器模块收集第三方原许可，输出 THIRD_PARTY_NOTICES.txt 和自有 LICENSE.txt；缺少许可原文会使构建失败，补充来源与固定版本记录在前端配置目录。

使用截图与放大

桌面和浏览器使用页按「入口 → 操作 → 保存反馈 → 回看结果」组织。截图保留导航和操作区域；浏览器阅读图应同时展示网页与原生侧栏。无头浏览器将两者暴露成不同渲染表面时，可以用同次会话的两张原图并排展示，必须注明不含工具栏，并保留原图、尺寸和 SHA；不得绘制工具栏或伪造产品状态。素材来源

正文截图沿用官方主题的图片排版：按原图尺寸显示，宽图以正文宽度为上限并保持比例；不额外设置缩略图宽度、居中间距或边框。ScreenshotViewer.vue 在客户端挂载后为图片提供按钮语义：点击、Enter 或空格放大，关闭按钮、Esc 或点击遮罩退出。原生 dialog 管理焦点范围，退出恢复原图焦点，切换文档结束预览并恢复滚动。已有图片链接、品牌和 Mermaid 不受影响；禁用 JavaScript 仍显示截图。

组件通过官方默认主题扩展，浏览器 DOM 只在挂载和用户交互中访问，保持静态构建兼容；没有引入额外图片库。依据：默认主题扩展、SSR 兼容。

test:ui 检查正文原尺寸与放大预览、键盘焦点、明暗主题、390px 手机、后退关闭和静态页面；「使用指南截图记录」同时保存宽屏与手机的阅读画面。用 LEXIMEET_DOCS_VISUAL 指定本轮私有证据目录，不把开发对比图混入产品截图。

双平台源码与站点部署

GitHub 和 Gitee 维护同一份源码与根 docs 正文，地位相同。顶部「开源」菜单与正文尾部「本页源码」提供两个平台的等权入口；SourceLinks.vue 通过官方 doc-footer-before 插槽按当前页面路径生成链接，切换文章后自动更新。

仓库现有自动化是 GitHub Actions，站点部署配置是 GitHub Pages；Gitee 尚无对应流水线或站点部署配置。托管平台平级不意味着它们的功能与发布状态自动相同，不能把一次部署描述成两个站点已上线。

GitHub Pages

真实仓库是 leximeet/leximeet.github.io，计划站点根地址 https://leximeet.github.io/，因此 base: '/'。这段配置不是已发布证明。

推送和 PR 运行验证，不自动部署。维护者在仓库 Settings → Pages 选择 GitHub Actions，审阅对应提交的结果后，主动手动运行 Pages 工作流；只有主分支 workflow_dispatch 可以进入部署 job。环境权限仅在部署 job 提供 pages: write 与 id-token: write，普通检查只有只读内容权限。

这里的“不自动部署”指本仓工作流。仓库设置也必须与之对应：如果 Pages 仍选择 Deploy from a branch，来源为 main / (root)，GitHub 会另行触发 pages-build-deployment，直接处理源码目录，不能代替 VitePress 构建产物。不要同时保留分支发布与本仓的 Actions 发布方式。

遇到检查成功但网站仍是旧内容或 README 页面时，依次核对 Pages Source、手动工作流的 deploy 输入、部署提交和上传目录 website/.vitepress/dist。普通 push 检查成功只证明验证通过；只有部署任务成功且线上页面核对通过，才能确认该次站点更新已经发布。

更新原则

跨仓图维护时同步 .mmd、正文可展开围栏和 sources.json，再导出、检查；生成的 rendered/ 排除通用格式化，保留原始 SVG 字节。完整步骤见图表规范。

图表导出使用 Vite 的中间件模式，另由 Node HTTP 服务绑定系统分配的回环端口。可以与 npm run dev 的 5173 预览同时运行，不停止开发站点；导出结束后，工具会关闭本轮浏览器和独立服务，并清理自身的临时目录。Vite 中间件模式

项目实现规范在各仓库 docs，本站负责跨项目摘要和阅读入口。规则、默认值和运行边界改变时同时更新两处；不要整批搬讨论、临时日志或私人路径。路线必须注明尚未实现，版本页不可替代真实 Release 状态。

工具依据：VitePress 配置、本地搜索、官方部署。

开发服务冷启动失败时，查看 documentation-browser-evidence 附件中的 cold-start-diagnostics.json、失败截图和 trace。诊断保留真实页面错误、失败请求与控制台信息；不要仅凭首屏定位器超时增加等待或关闭错误断言。测试使用独立端口和每轮新缓存，不接管日常开发服务。

维护文档站 ​

目录 ​

同一路径启动 ​

自动化检查 ​

搜索和图表 ​

首页与动画 ​

使用截图与放大 ​

双平台源码与站点部署 ​

GitHub Pages ​

更新原则 ​