企业官网建设流程全解析

• 应用安全

本文是 privacy.sexy 开源仓库的贡献者入门与实践指南。privacy.sexy 是一款用于在 Windows、macOS 和 Linux 上强制执行隐私与安全最佳实践的开源工具，其核心资产是位于 src/application/collections 下的 YAML 集合文件（collection files）——它们定义了应用的全部脚本与分类。本文基于仓库根目录的 CONTRIBUTING.md 展开，覆盖 Pull Request 提交流程、脚本扩展的两条路径、Commit 消息规范、版本发布策略、重构准则与许可证约定，并结合 docs/tests.md、docs/development.md、docs/ci-cd.md 及源码结构给出可落地的操作细节。读完本文，你将能够：按项目规范提交第一个 Pull Request、新增一条符合质量要求的隐私脚本、写出符合 50/72 规则与 OS 前缀约定的 Commit，并理解合并后自动化流水线如何把代码发布到生产环境。

贡献概览：你能以哪些方式参与

CONTRIBUTING.md 开篇即明确：这是一个社区较小的开源项目，任何形式的输入都受欢迎，包括：

• 报告 Bug（reporting a bug）
• 讨论当前代码状态（discussing the current state of the code）
• 提交修复（submitting a fix）
• 提议新功能（proposing new features）
• 成为维护者（becoming a maintainer）

由于社区规模小，Issue 的响应周期可能较长，文档特意提醒贡献者保持耐心。从仓库结构看，这一「小团队 + 强自动化」的定位体现在方方面面：项目依赖 .github/workflows 下的多条流水线（tests.unit.yaml、tests.integration.yaml、tests.e2e.yaml、checks.quality.yaml、checks.scripts.yaml、release.git.yaml、release.site.yaml、release.desktop.yaml等）来代劳大部分质量门禁，从而降低对维护者人工审查的依赖。

Pull Request 流程：五个标准步骤

CONTRIBUTING.md 将 PR 流程定义为基于 GitHub flow 的五个步骤，下面结合仓库文档与配置逐条展开。

第 1 步：Fork 仓库并从master分支创建开发分支

git clone https://gitcode.com/gh_mirrors/pr/privacy.sexy.git git checkout -b your-feature-branch master

分支基点固定为master。之所以强调从master创建，与项目的 GitOps 发布模式直接相关——见 docs/ci-cd.md 的说明：一切合并进master的内容都会直接进入生产环境，因此master始终代表可发布状态，任何功能分支都必须基于它派生，避免携带历史脏数据。

第 2 步：为新增代码补充测试

If you've added code that requires testing, add tests. See tests.md。

原文档指向 docs/tests.md，该文档系统介绍了四层测试体系：

1. 单元测试（Unit tests）：使用 Vitest 中的test:unit命令），文件以.spec.ts结尾，位于 tests/unit。目录结构镜像 src 源码结构。测试遵循AAA 模式（Arrange / Act / Assert），分别以// arrange、// act、// assert注释标记三段；套件命名以被测组件开头（如Application.ts对应Application.spec.ts），describe块按函数分组。组件隔离依赖tests/unit/shared/Stubs/下的桩（Stub）——公共桩放共享目录，组件专属桩与被测文件同目录。
2. 集成测试（Integration tests）：验证组件组合行为与第三方依赖是否符合预期，位于 tests/integration。
3. 端到端测试（E2E tests）：使用 Cypress 检验线上应用的运行行为与性能，配置见 cypress.config.ts 与 cypress-dirs.json，测试文件以.cy.ts后缀位于 tests/e2e，其中support/e2e.ts在每个测试文件前运行，support/interactions/提供可复用的用户交互模拟函数。
4. 自动化检查（Automated checks）：校验运行时错误、构建过程与安全性等，由 .github/workflows 中的工作流自动执行，例如checks.security.sast.yaml（基于 CodeQL 的静态应用安全测试）与checks.security.dependencies.yaml（第三方依赖漏洞审计）。

测试目录下还能看到大量实操佐证：tests/unit/shared/Stubs/中超过百个*Stub.ts文件（如CodeRunnerStub.ts、ScriptSelectionStub.ts），说明被测组件普遍以依赖注入方式接入，便于在测试中替换为桩实现。

第 3 步：重大变更同步更新文档

If you've done a major change, update the documentation. See docs/。

仓库的 docs 目录是文档中枢，与贡献强相关的包括：

• docs/development.md：本地开发、测试、Lint、运行与构建的全部命令
• docs/tests.md：测试体系与结构
• docs/ci-cd.md：CI/CD 流水线分类与命名约定
• docs/script-guidelines.md：脚本设计准则
• docs/collection-files.md：集合文件 YAML 语法
• docs/templating.md：模板表达式语法

如果你的变更影响行为或数据模型，务必同步这些文档。

第 4 步：确保测试套件通过

原文档指向 development.md 的 Testing 一节，具体命令如下：

npm run test:unit # 单元测试 npm run test:integration # 集成测试 npm run test:cy:open # E2E：开发服务器 + 热重载的交互模式 npm run test:cy:run # E2E：生产构建 + 无头模式 npm run check:desktop # 桌面应用运行时检查（可用 BUILD=true SCREENSHOT=true 等环境变量启用旗标） npm run check:external-urls # 校验应用中引用的外部 URL 是否存活

本地开发前置条件：安装 Node.js（自动化工作流要求的最低版本见 .github/actions/setup-node/action.yml，当前为node-version: 22.x），然后执行npm install或更灵活的npm run install-deps（脚本位于 scripts/npm-install.js，支持--fresh等选项，如npm run install-deps -- --fresh做全新安装并具备网络错误重试能力）。

第 5 步：确保代码通过 Lint 并提交 PR

Make sure your code lints. See development.md | Linting。

Lint 命令体系（见 package.json 的lint脚本聚合）：

npm run lint # 一键执行下面全部 Lint（推荐） npm run lint:md # Markdown 规范 npm run lint:md:consistency # Markdown 风格一致性 npm run lint:md:relative-urls # Markdown 相对链接有效性 npm run lint:md:external-urls # Markdown 外部链接存活 npm run lint:eslint # JavaScript/TypeScript（--max-warnings=0 零容忍） npm run lint:yaml # YAML 规范 npm run lint:pylint # Python 脚本

最后「Issue that pull request!」——发起 PR。

PR 的 DO 与 DON'T

CONTRIBUTING.md 用两条规则划出红线：

• 🙏 DO：在 PR 中写清楚为什么要解决（why / what you're trying to solve），而不是只罗列改了什么。
• ❗ DON'T：不要更新版本号。当前版本由维护者通过 docs/ci-cd.md#gitops 描述的 GitOps 流程设置，并由自动化工具bump-everywhere在发布时全局更新。

PR 提交后，自动化流水线会接管质量门禁，维护者合并 PR 后代码即被发布。整个过程在 docs/ci-cd.md 中有完整描述，架构图如下：

该图来自 docs/ci-cd.md，直观呈现了「所有合并进 master 的内容直接进入生产」的 GitOps 模式，以及发布流水线（如 .github/workflows/release.desktop.yaml 负责构建桌面安装包并挂载到 GitHub Releases）的运作方式。

扩展脚本：新增隐私脚本的两条路径

CONTRIBUTING.md 专设一节「Extend scripts」，是文档中技术含量最高的部分。要新增脚本，先读 docs/script-guidelines.md，再二选一：

1. 创建 Issue 请求：通过 .github/ISSUE_TEMPLATE/4-suggestion-new-script.yaml 模板提交「Suggestion: New Script」，由其他贡献者代为开发。模板要求填写操作系统（macOS / Windows / Linux / All of them）、脚本名称、文档/参考资料、代码、还原代码、建议分类、推荐级别等信息。此路径周期较长。
2. 直接提交 PR：最快被合入的路径。把脚本加入 src/application/collections/ 下对应操作系统的 YAML 文件（windows.yaml、macos.yaml、linux.yaml），语法见 docs/collection-files.md，然后按上文 PR 流程提交。

脚本设计准则速览（来自 docs/script-guidelines.md）

• 命名：以祈使动词开头（Clear、Disable、Remove、Configure、Minimize、Maximize、Block ..），统一措辞（Disable优先于Turn off，Configure优先于Set up等），使用 sentence case，尊重品牌名官方大小写，结构上优先Disable XX telemetry而非Disable telemetry in XX。
• 文档：引用可信来源，尽量使用 archive.org / archive.ph 存档链接（格式如https://archive.ph/YYYYMMDDhhmmss/https://privacy.sexy），并说明脚本不执行时的默认行为。
• 共享函数：优先复用现有共享函数（如DisableService），避免自造代码。
• 代码：保持简单、兼容旧系统、抗错误、适配多语言环境；语言选择上 Windows 用 batch（简单场景）或 PowerShell，macOS/Linux 用 bash 或 Python；适用时提供还原（revert）代码。
• 模板：表达式语法见 docs/templating.md——{{ ... }}包裹表达式，支持参数替换、with条件块、以及inlinePowerShell、escapeDoubleQuotes等预定义管道（pipe）。

集合文件 YAML 的最小骨架（来自 docs/collection-files.md 与 windows.yaml）

以 src/application/collections/windows.yaml 开头的实际配置为例，一个集合文件包含顶层os、scripting（语言、startCode/endCode头尾代码，可引用$homepage、$version、$date等全局变量）以及actions分类树；Script节点是叶子，二选一：

• 内联脚本：提供code（必填）+revertCode（建议）；
• 调用方脚本：提供call（引用共享函数，可带parameters参数），不能与code/revertCode共存。

脚本可用recommend: "standard" | "strict"声明推荐级别（不声明则不推荐）。集合文件顶部可通过# yaml-language-server: $schema=./.schema.yaml注释启用 VS Code 的 schema 补全与校验；项目还提供 scripts/validate-collections-yaml（README 见 scripts/validate-collections-yaml/README.md）用于按 schema 校验集合文件。

Commit 规范：50/72 规则与前缀约定

CONTRIBUTING.md 对 Commit 消息提出了一套可机械执行的规范：

• 50/72 规则：标题不超过 50 字符；描述行不超过 72 字符（代码块与内联代码除外）。
• 不写冗余：Commit 消息中不要包含 delta（如git diff信息）或变更文件清单——这些信息已属于 Commit 本身。
• 聚焦 WHY 与 HOW，而非 WHAT；标题以一段简洁摘要开头，使用祈使语气（用add而非added）。
• 前缀约定：
  • Bug 修复：fix:或Fix ...前缀。
  • 影响特定操作系统脚本的提交：使用 OS 标签前缀，Windows 为win:、macOS 为mac:、Linux 为linux:；跨多个 OS 时组合前缀，如win, mac: ...。

这条规范的背景是仓库的发布粒度：脚本按操作系统分别组织在 src/application/collections 下，OS 前缀让维护者能快速识别一次变更波及的平台范围，也便于在 Changelog 中归类。

版本管理：基于发布内容而非严格语义化版本

CONTRIBUTING.md 明确：项目版本号基于发布内容决定，而非严格遵循语义化版本（SemVer）。两类主要发布：

1. 补丁发布（Patch Releases）：提升MAJOR.MINOR.PATCH中的 patch 位。涵盖次要 UI 改进、Bug 修复、重构、依赖更新、文档更新；对脚本而言，包括调整推荐级别、增强功能、为更精细控制而拆分脚本。补丁发布若修复 Bug 必需，可附带次要功能。
2. 功能发布（Feature Releases）：提升 minor 位。带来改变用户与 privacy.sexy 交互方式的重大更新，如主要 UI 增强、引入新脚本、新特性。

流程上：维护者对特定 Commit 打上版本标签以触发发布，自动化工具bump-everywhere负责整个发布过程，包括全局更新版本号（这正是 PR 阶段禁止贡献者手动改版本号的原因）、生成 CHANGELOG.md 与 GitHub Releases；桌面安装包则由 release.desktop.yaml 流水线构建并挂载。仓库当前版本可从 package.json 的"version": "0.13.8"确认。

重构与许可证：贡献的边界

机会主义重构（Opportunistic refactoring）

CONTRIBUTING.md 鼓励顺手重构：在添加功能或修复 Bug 时，可同时清理和优化相关代码，让代码比你发现它时更好。这符合项目「小团队 + 强自动化」的协作模型——质量门禁（如 tests.unit.yaml、checks.quality.yaml）会自动兜底重构不引入回归。

许可证约定

贡献即表示同意：你的贡献按 GNU Affero General Public License（AGPL）当前条款授权；同时你明确同意维护者拥有修改许可条款或将来以不同条款重新许可你的贡献的完全权限。这是一条对贡献者有约束力的法律条款，参与前务必阅读 LICENSE 全文。

参考文档索引

• 贡献总览：CONTRIBUTING.md
• 测试体系：docs/tests.md
• 开发命令（测试 / Lint / 运行 / 构建）：docs/development.md
• CI/CD 与 GitOps：docs/ci-cd.md
• 脚本设计准则：docs/script-guidelines.md
• 集合文件 YAML 语法：docs/collection-files.md
• 模板表达式：docs/templating.md
• 集合目录与 schema：src/application/collections/README.md
• 流水线定义：.github/workflows
• Issue 模板：.github/ISSUE_TEMPLATE

• 应用安全