官网与文档

官网 evs-docs 是一个独立的 VitePress 项目：构建只读自己目录里的文件。这一页讲它的结构、页面规则、截图怎么来、契约副本怎么同步，以及更新日志怎么记。

结构

evs-docs/
├── .vitepress/
│   ├── config.ts          站点、导航、侧栏、搜索、分享卡片
│   ├── site.ts            站点常量与栏目
│   └── theme/             主题：tokens.css、style.css、组件、截图清单 shots.ts
├── scripts/               og.ts（分享卡片）、check.ts（文档用例）
└── src/
    ├── zh/
    │   ├── product/       产品：给做调研的人
    │   ├── deploy/        部署：给部署运维的人
    │   ├── guide/         使用指南：给接入和使用的人
    │   ├── dev/           二次开发：给改代码的人
    │   ├── sdk/ api/ reference/   参考
    │   └── change/        更新日志，按年月一个文件
    └── public/            截图、动图、契约副本、部署示例副本、图标

独立与副本

官网展示的几样东西源头在别的目录，官网里放的是副本，构建时不去别的目录复制：

副本	源头	同步与核对
src/public/openapi.json、config-keys.json	evs-aggr/api/（go generate 生成）	evs-test：uv run main.py --case T-D09 --fix
src/public/deploy/**	仓库根 deploy/	uv run main.py --case T-D10 --fix
.vitepress/theme/tokens.css	evs-dash/src/styles/tokens.css	uv run main.py --case T-D11 --fix
src/public/screenshots/、demo/	自动化测试生成	uv run main.py --case media --publish

不带 --fix 时只检查，不一致就失败；CI 里跑的是检查。页面里展示部署示例时用 VitePress 的代码片段引用，例如 <<< @/public/deploy/compose/compose.yaml，页面和可下载的文件是同一份。

页面规则

• 每页一个一级标题，紧跟一句话说明这一页讲什么。
• 文末一行 <!-- features: D43 D44 --> 列出这一页覆盖的功能编号，yarn test --case T-D03 核对覆盖率。
• 句子短、主语明确；表格只放短事实，解释写在表外。不写没有实现、也不在路线图里的能力；数字只写代码里定死的上限和默认值。
• 密钥写 evs_wk_xxx / evs_xxx，生产示例的口令写 change-me，主机写 stats.example.com。
• 站内链接写 /zh/... 的绝对路径，不带 .md；构建检查死链和锚点。
• 新页面要同时加进 .vitepress/config.ts 的侧栏和 scripts/lib/manifest.ts 的页面清单。

截图与动图

截图和动图由 evs-test 的 media 用例生成：起一套全新实例、灌示例数据（evs-test/lib/demo.py）、用真实的 Web SDK 在示例站点上走几遍，再逐页截图、录动图。

cd evs-test
uv run main.py --case media              # 生成到仓库根的 build/test/media/，先检查
uv run main.py --case media --publish    # 通过后复制进 evs-docs/src/public/

• 截图：1440×900、设备像素比 2，浅色深色各一张，WebP，单张不超过 200KB。页面里用 <ScreenshotFrame name="funnel" chrome />。
• 动图：1280×800 录制、缩到 1200 宽的 GIF，附一张最后一帧的封面。页面里用 <DemoGif name="stats" chrome />：进入视口播放一遍，播完停在封面，减少动效时只显示封面。
• 名字登记在 .vitepress/theme/shots.ts，与 evs-test/media/capture.py 的清单一一对应。

更新日志

需求新增、功能调整、行为变化、修复、部署示例和文档结构的变化都要记：

• src/zh/change/ 下每个月一个文件，文件名是年月（2026-09.md），一级标题「2026 年 9 月」。
• 每天一个二级标题，就是当天的日期（## 2026-09-26），新的日期在上面。
• 每条一句变更摘要，不贴链接。yarn test --case T-D08 检查格式。

侧栏按文件自动列出月份，不用改配置。

命令

cd evs-docs
yarn install
yarn dev              # 本地预览
yarn build            # og → vitepress build，死链必须为 0
yarn test             # 文档用例 T-D01～T-D08，报告写到仓库根的 build/test/docs.txt
yarn preview          # 预览构建产物

改了首页或组件时，在浅色、深色和窄屏下各看一遍。发布与缓存规则见 evs-docs/README.md。