企业官网建设流程全解析

本指南面向希望参与 open-slide 框架本身（@open-slide/core运行时、@open-slide/cli脚手架以及配套 apps）开发与维护的贡献者，系统讲解仓库的 monorepo 布局、环境要求、常用开发脚本、代码风格约定、测试规范与完整的 Pull Request 提交流程。读完本文，你将掌握从克隆仓库、本地跑起 demo 到提交一个符合 CI 与审查标准的 PR 的完整闭环；如果你只是在脚手架项目里编写幻灯片，则无需阅读本文，直接通过你的编码 Agent 驱动或编辑slides/<id>/index.tsx即可。

贡献方式总览

open-slide 的贡献入口分为四类，分别对应不同的协作渠道：

• 报告 Bug：通过 bug report 模板 提交，务必附带最小可复现示例（minimal reproduction），帮助维护者快速定位问题。
• 提议新功能：通过 feature request 模板 提交，规范要求"先描述问题、再给出方案"（Describe the problem before the solution），确保方向一致。
• 提问或分享你的作品：在项目的 GitHub Discussions 中发起讨论，适合提出疑问、交流使用心得。
• 提交 Pull Request：遵循下文第 5 节的完整流程。

对于非琐碎的改动（non-trivial changes），建议先开 issue 或 discussion 对齐方向，再投入编码时间，避免 PR 方向跑偏后被驳回。从仓库目录结构看，.github/ISSUE_TEMPLATE/下同时存在bug_report.yml、feature_request.yml与config.yml，说明 issue 模板体系完整，提交前会自动加载对应表单。

仓库布局：pnpm + Turbo 的 monorepo

open-slide 是一个基于pnpm + Turbo的 monorepo，各包的角色划分如下：

从源码可以进一步印证这套布局的工程细节：

• pnpm-workspace.yaml 声明了全部工作区：apps/*、apps/marketing/*、packages/*，以及packages/core/e2e/fixture（e2e 测试用的独立夹具工程），说明apps/下不仅有 demo 和 web，还包含营销类子应用。
• 根 package.json 中packageManager字段固定为pnpm@10.17.0，并提供了dev、build、typecheck、check、check:fix、test等 turbo 代理脚本，以及core、cli两个包级过滤快捷脚本（详见下文"常用脚本"）。
• turbo.json 为各任务定义了依赖关系与缓存策略：dev任务cache: false且persistent: true（长期运行的进程不缓存、不退出），build输出dist/**与template/**，typecheck依赖上游^build。
• apps/demo/package.json 中依赖为"@open-slide/core": "workspace:*"，dev/build/preview脚本直接调用open-slide二进制，这正是"demo 消费本地 core"的实现方式。

环境准备（Prerequisites）

开始开发前，请确认本机满足以下条件：

• Node.js 22+：与 CI 环境保持一致（见.github/workflows/ci.yml中actions/setup-node的node-version: 22）。同时注意 packages/core/package.json 的engines字段为^20.19.0 || >=22.12.0，即运行时对 Node 的最低要求是 20.19 或 22.12 以上。
• pnpm 10.17.0+：执行corepack enable后，corepack 会自动采用根package.json中固定的pnpm@10.17.0版本，无需手动安装。
• 类 Unix shell：Windows 用户请通过 WSL 开发（CI 本身也运行在 Ubuntu 容器中）。

搭建本地开发环境

git clone https://gitcode.com/gh_mirrors/op/open-slide cd open-slide pnpm install

然后针对本地@open-slide/core运行 demo：

pnpm dev

apps/demo 是验证框架改动最快的方式：修改packages/core后，demo 会热重载（hot-reload），无需手动重启。这是因为apps/demo通过workspace:*直接链接到本地 core 包，而 turbo 的dev任务（见 turbo.json）会先构建依赖图的上游产物再启动持久进程。

常用脚本一览

根目录 package.json 中定义的脚本与 CONTRIBUTING.md 一一对应，具体如下：

pnpm dev # turbo: 运行 demo 并链接本地 core pnpm build # 构建所有包 pnpm typecheck # 对整个依赖图执行 tsc 类型检查 pnpm check # biome（格式化 + lint + import 整理） pnpm check:fix # 自动修复 biome 可修复的问题 pnpm test # vitest 单元测试

脚本的底层映射分别是turbo run dev、turbo run build、turbo run typecheck、biome check .、biome check --write .与vitest run，与 turbo.json 的任务配置一一对应。

只处理单个包时，使用 turbo 的 filter 语法：

pnpm core <script> # 例如 pnpm core build pnpm cli <script>

这两个快捷方式定义于根package.json的"core": "pnpm --filter @open-slide/core"与"cli": "pnpm --filter @open-slide/cli"，因此pnpm core test:e2e等价于仅对 core 包执行端到端测试。此外根目录还提供了pnpm test:e2e（即pnpm --filter @open-slide/core test:e2e）来一次性运行 Playwright 全套 e2e 用例。

Pull Request 工作流

1. Fork 并创建分支

从main分支切出特性分支，保持分支聚焦——一个 PR 只做一件逻辑改动。

2. 完成改动

匹配仓库现有代码风格，不要顺手重构无关代码（Don't reformat unrelated code）。

3. 推送前运行全部检查

pnpm check # 必须通过 —— CI 强制执行 pnpm typecheck pnpm test

pnpm check:fix会自动修复绝大多数格式与 lint 问题。为什么"必须通过"是硬性要求？因为 .github/workflows/ci.yml 中 CI 的lintjob 会分别运行pnpm format:check和pnpm lint，任何格式偏差都会直接导致 PR 标红。

4. 改动packages/core或packages/cli时添加 changeset

pnpm changeset

选择受影响的包并确定合适的版本级别（bump）：

• patch—— Bug 修复、内部重构、打磨类改动；
• minor—— 新的公开 API、新增功能；
• major—— 破坏性变更。

apps（apps/demo、apps/web）和根目录工具链不需要 changeset。changeset 描述要求简短直接：一行、现在时态、从用户视角说明改了什么，语气与现有.changeset/*.md文件保持一致。不要写段落、不要写理由、不要出现"this PR…"。

好：Replace spinner with a hairline + sliding bar for slide and presenter loading states.

差：This change introduces a new loading indicator because the previous spinner felt heavy…

不要手动修改版本号或编辑CHANGELOG.md—— 这些由changeset version全权负责。从根package.json的脚本可以看到，版本化的命令是"version-packages": "changeset version"，发布命令"release"则会先 turbo 构建 core 与 cli 再执行changeset publish。

5. 打开 PR

在 PR 描述中说明：问题是什么、改动是什么、如何验证（Describe the problem, the change, and how you tested it），并链接相关 issue。UI 改动建议附截图或短视频。

6. 处理审查反馈

通过追加提交（follow-up commits）回应 review 意见，合入时采用 squash。

代码风格与约定

• Biome 必须通过：格式化、lint、import 排序全部由pnpm check强制约束，无需手工纠结风格细节。
• 不随意引入依赖：core运行时会随包一起分发给用户，每新增一个依赖都会膨胀安装体积。优先用少量内联代码替代新依赖，而不是为小功能引入新包。这一约定与 packages/core/package.json 中files白名单（dist、src/app、src/locale、skills等）相辅相成——发布物体积被严格管控。
• 默认不写注释：只有当"为什么"不显然时才写注释——隐藏约束、微妙的不变式、针对特定 bug 的 workaround。不要解释"代码做了什么"，命名良好的标识符自会说明。
• 不要动packages/core/src/app/components/ui：该目录是 shadcn 生成的，且被 biome 忽略（除非你在重新生成它）。从 biome.json 可以印证这一忽略策略。

测试要求

• 单元测试：通过pnpm test（Vitest）运行。修复 bug 或新增值得测试的逻辑时，将测试放在代码旁边（*.test.ts）。仓库中 core 包的测试即遵循此约定，例如 packages/core/src/lib/transition.test.ts、packages/core/src/editing/edit-ops.test.ts。
• 运行时/UI 改动：请在 apps/demo 中实际验证改动，并在 PR 中说明你演练了什么内容（describe what you exercised）。
• 端到端测试：仓库还维护了一套 Playwright e2e 套件，位于 packages/core/e2e/tests（覆盖导出、presenter、inspector、主题、热更新等场景）。CI 中e2ejob 使用与packages/core/package.json中@playwright/test ~1.63.0匹配的mcr.microsoft.com/playwright:v1.63.0-noble容器镜像运行，并将报告上传为 artifact 保留 7 天。

发布流程

版本发布由维护者执行：

pnpm release

该命令会构建@open-slide/core与@open-slide/cli，并执行changeset publish（根package.json中"release": "turbo run build --filter=@open-slide/core --filter=@open-slide/cli && changeset publish"）。贡献者无需发布任何东西——只需随代码提交 changeset 即可，剩下的交给维护者。

问题与讨论

如果遇到文档未覆盖的问题，欢迎在项目的 GitHub Discussions 中发起讨论，维护者会乐于协助。对于参与框架开发的贡献者，本节可与上文"贡献方式总览"中的 discussion 入口相互印证——提问、方向探讨与成品分享都在同一渠道完成。

小结

参与 open-slide 框架开发的核心要点可归纳为一句话：clone 仓库 →pnpm install→pnpm dev用 demo 自举验证 → 改动后跑pnpm check && pnpm typecheck && pnpm test→ 涉及 core/cli 则加 changeset → 提交聚焦的 PR。这套流程由根 package.json 脚本、turbo.json 任务、.github/workflows/ci.yml 检查链与 CONTRIBUTING.md 约定共同保障，任何一步都有清晰的自动化与规范兜底。