企业官网建设流程全解析

• 数据可视化
• 前端

Visdom 是一个用于 AI/ML 实验实时可视化、监控与协作分析的开源工具（Python 客户端 + Tornado 服务器 + React 前端）。随着 API 与行为持续演进，其文档体系（README、贡献指南、AI 指令、网站文档、类型桩）极易出现“代码已改、文档未跟”的漂移。本文基于仓库内置的 docs-sync 技能定义，系统讲解如何在 Visdom 仓库中识别文档受影响面、按五步工作流同步 README/CONTRIBUTING/AGENTS，并借助术语护栏与类型桩校验保证示例与真实 API 永远一致。读完本文，你将掌握一套可直接复用的“行为变更 → 文档同步 → 测试验证”闭环流程，适用于任何以 README 为门面的开源项目。

技能定位：docs-sync 解决什么问题

仓库将可复用的操作经验封装为“技能”（skill），统一存放在 .agents/skills 目录下，每个技能目录遵循 .agents/skills/README.md 定义的统一脚手架：

skill-name/ ├── SKILL.md # 必需：元数据 + 指令 ├── references/ # 参考笔记与默认测试格式 │ ├── REFERENCE.md │ └── TESTS.md ├── assets/ # 可选模板/资源 │ └── README.md └── ...

.agents/skills/docs-sync/SKILL.md 就是其中的docs-sync技能。它的 frontmatter 元数据给出明确定位：

--- name: docs-sync description: Keep API and behavior documentation aligned across README, contribution docs, and AI instructions ---

即：让 API 与行为文档在 README、贡献文档和 AI 指令三份文档之间保持一致。在 Visdom 这种“文档即门面”的仓库里，这份技能直接对应 CONTRIBUTING.md 中的硬性要求——If you've changed APIs, update the documentation（修改了 API 就必须更新文档），以及 AGENTS.md 中的 PR 检查项：

UpdateREADMEfor API changes,__init__.pyifor interface changes

docs-sync 正是把这些分散在多个文档中的同步要求，收敛成一个 Agent 可执行的、带触发条件与操作顺序的操作手册。

何时启用：识别文档受影响面

技能在When to Use一节给出的触发条件是：

Use this skill when behavior/API changes must be reflected in project docs.

即当任何行为或 API 变更需要反映到项目文档时启用。判断的关键在于先识别“受影响的行为面”（impacted behavior surface），技能给出了四类：

实际应用中，一次 PR 往往同时触及多个面。例如新增一个 Python 绘图方法，既属于“用户 API”（要更新 README 的 API 章节与类型桩），也可能带动示例文件（example/目录）与网站文档（website/docs）的联动更新。

核心工作流：五步同步法

docs-sync 的Core Workflow给出五个有序步骤，本质是一条“从识别到验证”的流水线：

第 1 步：识别受影响的行为面

对照上表，把本次变更逐一映射到“用户 API / 服务器内部 / 贡献者工作流 / AI 工作流”四类中。这一步决定了后续要动哪些文档，是避免“漏改”的关键。

第 2 步：更新 README.md

README.md 承担高层用法与导航入口的角色。Visdom 的 README 体量极大（超过 1600 行），包含 Concepts（Windows、Callbacks、Environments、State、Views）、Setup、Command Line Options、完整 API 章节（Basics / Plotting / Others / Experiments）、Loggers（PyTorch、Lightning、sklearn、XGBoost、Keras、Optuna）等。凡是影响高层用法或导航的变更——例如新增一个可视化函数、改变某个日志器的参数——都应在此更新，因为它既是用户的第一入口，也是visdom命令与python -m visdom.server等命令的权威说明处。

第 3 步：更新 CONTRIBUTING.md

CONTRIBUTING.md 是开发者工作流、测试与提交流程的权威文档。涉及以下变更时必须同步：

• 测试命令与目录约定：文档明确规定了 Python 测试套件位于py/tests/下，按unit/（纯逻辑、无 HTTP）与integration/（进程内 Application、真实 HTTP 或 handler 分发）划分；新增测试文件应放在对应目录并给出匹配的pytestmark。测试配置的权威定义在 pyproject.toml 中，包括testpaths = ["py/tests"]、pythonpath = ["py", "py/tests"]以及unit/integration/slow/server四个 marker。
• UI 构建与提交约定：js/由 React 编写，编译产物py/visdom/static/由 CI 自动构建，贡献者不应手动提交。
• Playwright 端到端与视觉回归流程：npm test、npm run test:polling、npm run test:init、npm run test:visual等命令与前置条件（npx playwright install chromium、端口 8098 可用）。

第 4 步：AI 工作流变更时更新 AGENTS.md

Visdom 仓库维护了一份面向 AI 助手的 AGENTS.md，其中浓缩了代码风格（black py、Prettier）、Do Not 清单（不得编辑py/visdom/static/、不得提交密钥与COOKIE_SECRET、不得直接 push master）、Pitfalls（handler 必须装饰@check_auth、socket 功能必须同时支持 WebSocket 与 polling 两种模式）、Testing 与 PR Checklist。技能强调：

If AI-agent workflow changes, updateAGENTS.mdand keep assistant-specific instruction files pointing to it.

即 AGENTS.md 是 AI 指令的唯一事实源，仓库中的 assistant 专属指令文件（如CLAUDE.md、GEMINI.md、CODEX.md等，均位于仓库根目录）只做指针式引用，避免多份指令各自漂移。

第 5 步：校验文档示例与真实 API 一致

这是收尾但最易疏漏的一步：确保文档中的任何示例与当前可调用的 API 与选项名完全匹配。在 Visdom 仓库中，这一步有两类天然“校验器”：

• 类型桩 py/visdom/init.pyi：它是 Python 客户端全部公开方法签名的权威声明（Visdom类下的image、line、scatter、text、experiment、search_experiments、hparams等数十个方法）。任何参数改名、新增关键字参数，都必须同步到类型桩，这与 AGENTS.md 的 PR 检查项完全一致。
• 示例目录 example：仓库以demo.py、train_example.py、train_keras_example.py、train_lightning_example.py、train_sklearn_example.py、train_xgboost_example.py及example/components/下的组件示例作为“可运行的 API 文档”，CONTRIBUTING.md 要求“为新功能添加 demos 并确保 demos 可运行”。

护栏：防止文档间自相矛盾

Guardrails一节给出了三条必须在同步过程中遵守的纪律，这是 docs-sync 区别于“改文档”的核心约束：

1. 避免文档间矛盾示例（Avoid contradictory examples between docs）：同一 API 在不同文档中绝不能给出互相冲突的用法。例如vis.line()的update参数在 README 与示例中语义必须一致。
2. 保持术语一致（Keep terminology consistent）：Visdom 有四个核心术语——env（环境）、win（窗口）、pane（面板）、update（更新模式）。CONTRIBUTING.md 特别澄清：UI 中的 Panes 就是 Python/Lua API 所指的 'windows' 的容器，前端与后端命名不一致极易造成理解偏差，同步时必须统一口径。
3. API 签名变更时，示例与类型桩同步更新（When API signatures change, ensure examples and type stubs are updated together）：签名变更是一处改动、多点生效的场景——__init__.pyi类型桩、README 参数表、website 文档、example 示例必须一次性全部跟上。

文档体系全景：docs-sync 作用的对象

要执行好 docs-sync，需要先看清 Visdom 仓库的完整文档地图。除了技能中直接点名的 README / CONTRIBUTING / AGENTS 三件套，实际同步范围还包括：

• 网站文档 website/docs：按api/（basics、generic-plots、plotting、other-functions、customizing-plots、network-graph、overview）、concepts/（windows、environments、views-and-filters、callbacks）、getting-started/（installation、usage、command-line-options）、user-guide/（quick-start、live-updates、pytorch-integration、sharing-and-security、windows-and-layouts）组织的 Docusaurus 站点，是面向最终用户的完整 API 手册。
• Agent 上下文 .agents/context：architecture.md、backend.md、frontend.md、testing.md四份深度文档，是 AGENTS.md 中“Context & Skills”指向的架构级说明。
• 服务器契约 openapi.yaml：服务器 HTTP 端点的 OpenAPI 描述，服务器内部行为变更时需同步。
• 测试即文档：py/tests/unit 与 py/tests/integration 中的测试用例（如client_payloads_graph.py、window_builder.py）通过断言锁定了 API 行为，是验证文档示例正确性的最终裁判。

验证与测试：如何确认同步没有破坏约定

docs-sync 的Tests一节声明遵循references/TESTS.md的默认流程。虽然当前仓库的.agents/skills/docs-sync/目录下仅实现了 SKILL.md（references/、assets/目录尚未补齐，SKILL.md 中的references/REFERENCE.md、references/TESTS.md、assets/README.md属于脚手架约定中的预留位置），但技能要求的“文档变更可验证”在仓库中已有完备的落地点：

• Python 测试：pip install -e . && pip install -r test-requirements.txt后运行pytest；CI 以pytest -m unit作为门禁（见 AGENTS.md），因此新增的测试文件必须带有模块级pytestmark，否则在-m unit与-m "not server"两个 job 中都不会被执行。
• 前端 E2E 与视觉回归：npm test（WebSocket 套件）与npm run test:polling（-use_frontend_client_polling轮询套件）验证前后端行为；npm run test:init生成基线截图后npm run test:visual做视觉回归——UI 相关文档变更可以用这些测试兜底。
• 静态一致性：black py（v23.1.0）格式化 Python、npm run lint检查 JS，保证文档中贴出的代码风格与仓库一致。

落地检查清单

将 docs-sync 技能落成一次具体操作时，可按下述清单逐项核对（也是 SKILL.md 全部内容的可执行化）：

1. 识别：本次行为/API 变更涉及哪些行为面？至少命中“用户 API / 服务器内部 / 贡献者工作流 / AI 工作流”中的一类。
2. README：高层用法、命令、API 列表是否有变动？新增函数是否加入 Basics/Plotting/Experiments 列表？
3. CONTRIBUTING：测试命令、目录约定、UI 构建流程是否受影响？
4. AGENTS：AI 工作流（风格、Do Not、Pitfalls、PR Checklist）是否需更新？确认 assistant 专属指令文件仍指向 AGENTS.md 而非自行复制内容。
5. 一致性：所有示例与真实 API、选项名逐一对齐；env/win/pane/update术语统一；签名变更时__init__.pyi类型桩、README、website、example 一次性同步。
6. 验证：运行pytest -m unit、npm test/npm run test:polling，必要时补充视觉回归，确保文档描述的每一个行为都有测试背书。

docs-sync 的价值在于把“文档会漂移”这个开源项目的通病，转化为一个带触发条件、带操作顺序、带验证手段的标准化流程。对 Visdom 这类 API 面宽（数十个绘图方法 + 六种框架日志器 + 实验追踪接口）、文档载体多（README / 贡献指南 / AI 指令 / 网站 / 类型桩）的项目而言，它既是人写文档时的 checklist，也是 AI Agent 修改代码时不可跳过的配套工序。

• 数据可视化
• 前端