维护指南

本文档面向仓库维护者与代码贡献者。若你只是想为站点投稿或修正文稿，请阅读投稿指南。

主要目录

• docs/：VitePress 文档站与在线工具页面。
• packages/compat-finder/：兼容性排查库和命令行工具。

开发环境

安装依赖

先安装 Node.js 与 pnpm，然后在仓库根目录运行：

pnpm install

如果需要运行 Java 代码格式化或构建 graphwar-agent，还需要让 java / javac / jar 可在 PATH 中执行。推荐使用 JDK 21，CI 也使用 JDK 21。

常用命令

文档站

• 启动支持热更新的文档站开发服务器：pnpm docs:watch
• 构建文档站：pnpm docs:build
• 构建文档站并启动预览服务器：pnpm docs:preview

compat-finder 包

• 直接运行 CLI：pnpm compat-finder:cli
• 构建包：pnpm compat-finder:build
• 启动监听构建：pnpm compat-finder:watch
• 运行测试：pnpm compat-finder:test

仓库级检查

• 格式化：pnpm fmt。其中 Java 文件会使用 google-java-format 的 AOSP 风格格式化，formatter jar 会缓存到 .cache/google-java-format/
• 求疵与类型检查：pnpm lint
• 运行全部测试：pnpm test

Changeset

• 生成发布变更记录：pnpm changeset
• 当改动会影响任一已发布工作区包时，需要补 changeset；仅修改文档站、公开内容页或不影响已发布包行为的内部整理时不需要补
• 运行后按提示选择受影响的已发布包，以及对应的语义化版本级别：patch、minor 或 major
• 将生成的 .changeset/*.md 与代码改动一起提交到 PR

CI 检查

仓库通用检查

nodejs-ci.yml 会在 PR 与 main 分支推送时运行，主要包括：

• pnpm fmt
• pnpm lint
• pnpm test

其中格式化与部分自动修正步骤会在 PR 分支位于本仓库时自动提交修复结果；PR 分支位于 Fork 仓库时，CI 只运行检查，若产生修复变更，会上传 ci-autofix.patch。贡献者可从 CI Job Summary 复制补丁链接，并在 PR 分支本地运行对应命令：

Linux / macOS：

curl -L -o ci-autofix.patch "<ci-autofix.patch 链接>" && git apply ci-autofix.patch

Windows PowerShell:

Invoke-WebRequest -Uri "<ci-autofix.patch 链接>" -OutFile ci-autofix.patch; git apply ci-autofix.patch

PR 构建检查

• pr-docs-build.yml：检查文档站是否可构建。
• pr-compat-finder-build.yml：检查 compat-finder 包是否可构建。

相关文档

如果你修改的是公开内容页或工具文档，请同时参考：

• 投稿指南
• 对应目录下的 README.md

发布说明

发布流程、版本规则与 release PR 行为见发布说明。