Scalar 仓库 AI Agent 协作指南从环境搭建到代码提交流程的完整解读【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar 是一个基于 Vue 3 TypeScript 的 API 文档与测试工具开源 monorepo同时产出scalar/api-referenceOpenAPI 文档渲染与scalar/api-clientAPI 测试客户端两大核心产品。本文以仓库根目录的 CLAUDE.md即该仓库的 AI Agent 规范文档为骨架结合仓库内的真实配置与源码系统解读 AI 编码 AgentCursor、Claude Code、GitHub Copilot 等在 Scalar 代码库中高效工作的完整流程从环境准备、构建与测试命令到代码规范、PR 要求与可视化验证帮助你在贡献或二次开发时快速对齐项目的工程约定。项目概览一个 40 包、16 集成的超大 monorepoCLAUDE.md 开篇明确了 Scalar 的技术栈与规模前端Vue 3、Composition API、TypeScript样式Tailwind CSS测试Vitest单元测试 PlaywrightE2ELintESLintVue 文件 BiomeTypeScript 文件包规模40 个支持包packages/下 43 个包与 16 个框架集成Express、Fastify、Hono、NestJS、Next.js、Nuxt 等工具链pnpm workspaces 管理依赖、Turbo 编排构建、Vite 构建 Vue 包、tsc构建纯 TypeScript 包这些数字都能在仓库中直接验证根 package.json 中声明了 pnpm 10.16.1 与turbo、vitest、biome、lefthook等全部工具链依赖integrations/目录下确实存在 express、fastify、hono、nestjs、nextjs、nuxt、django-ninja、dotnet、rust 等 16 个集成目录。环境准备Node.js v24 与 pnpm 10.16.1Agent 进入仓库后的第一步是核对运行环境。仓库通过.nvmrc固定 Node 版本为v24见 .nvmrc而 package.json 的engines字段声明pnpm: ^10.16.1packageManager字段为pnpm10.16.1——也就是说 pnpm 版本由 corepack 自动激活无需全局安装。首次设置只需两条命令pnpm install pnpm build:packages其中build:packages是开发前必须执行的步骤它会用 Turbo 过滤出packages/**下的所有包并全部构建对应根 package.json 中的脚本turbo --filter ./packages/** --concurrency100% build。因为所有 workspace 内部依赖都采用workspace:*协议任何包被改动前都需要先确保其上游依赖已构建完成。常用命令速查表CLAUDE.md 将常用命令整理为一张表结合根 package.json 的 scripts 定义含义如下任务命令说明构建所有包pnpm build:packagesTurbo 过滤./packages/**构建首次开发前必跑构建集成pnpm build:integrations构建./integrations/**下的框架集成全量清理重装pnpm clean:buildpnpm clean pnpm install pnpm build:packages一条龙单元测试pnpm test全仓测试Turbo 过滤 packages/integrations/projects/tooling单包单次测试pnpm vitest packages/helpers --run从根目录按路径过滤跑完即退单包 watch 测试pnpm vitest packages/api-client开发时持续监听按名称过滤测试pnpm test your-test-name匹配测试名Lint 检查pnpm lint:checkbiome lint --diagnostic-levelerror主 lint 命令Lint 修复pnpm lint:fixBiome 写回 ESLint 修复 Vue 文件格式化pnpm formatPrettier 写回 Biome format 写回类型检查pnpm types:checkTurbo 编排全仓types:check一个关键提示是根目录没有统一的pnpm dev开发服务器必须按包启动pnpm --filter scalar/api-reference dev pnpm --filter scalar/api-client dev pnpm --filter scalar/components dev各开发服务器的用途对比如下包用途api-reference主 API 文档渲染 playground端口 5173api-clientAPI 测试客户端 playgroundVite 自动分配端口componentsStorybook 组件库端口 5100void-serverHTTP 镜像服务器端口 5052供测试使用架构Workspace 布局与双构建策略目录结构packages/ # 核心包scalar/*43 个 npm 包 integrations/ # 框架集成Express、FastAPI 等 examples/ # 各种框架的使用示例 projects/ # 可部署应用scalar-app、proxy-scalar-com、galaxy-scalar-com tooling/ # 内部脚本与 changelog 生成器projects/scalar-app同时构建 Electron 桌面应用和 client.scalar.com仓库内可见其 72 个.vue与 267 个.ts文件tooling/存放构建辅助脚本其中 vite-lib-config.ts 是所有 Vue 包的共享 Vite 库构建配置构建系统标准工具直用无自定义 CLIScalar 刻意不写自定义构建 CLI只用两种标准策略tsctsc-alias用于纯 TypeScript 包helpers、types、openapi-parser、各集成每个包使用自己的tsconfig.build.json用tsc-alias处理路径别名。vite build用于 Vue 组件包components、api-reference、api-client基于 Vite 8 Rolldown构建时抽取 CSS、保留模块结构。两条策略都外部化依赖库产物不打包第三方依赖。api-reference是特例它有默认构建与 standalone 构建两种standalone 构建vite.standalone.config.ts会把一切打包进单一产物用于 CDN 场景——这与 vite.standalone.config.ts 的存在相互印证。类型检查则按包类型区分纯 TS 用tsc --noEmitVue 包用vue-tsc --noEmit。从 turbo.json 可以看到任务依赖编排build依赖上游^buildtypes:check依赖buildtest依赖^build且关闭缓存——这正是改包先建上游机制的来源。关键包关系scalar/core共享渲染逻辑被api-reference和各集成消费见 packages/corescalar/themesCSS 变量与设计 token供所有 UI 包使用scalar/componentsVue 组件库带 Storybookscalar/oas-utilsOpenAPI 工具api-reference与api-client共用scalar/types共享 TypeScript 类型必须从具体入口导入如scalar/types/api-reference不能从根导入——这一约束在 biome.json 的noRestrictedImports规则中被强制为 error 级别依赖版本管理内部依赖一律使用workspace:*共享的第三方版本统一定义在 pnpm-workspace.yaml 的catalogs:下如vue: ^3.5.40、vite: 8.1.5、vitest: 4.1.10各包的package.json里用catalog:*引用。这样可以把全仓数十个包共用的依赖版本收敛到一处避免版本漂移。工具分工Biome.ts文件的 lint 与格式化配置见 biome.jsonESLint.vue文件的 lintPrettier.vue、.md、.json、.css、.html、.yml的格式化Lefthookpre-commit 钩子对暂存文件运行 Prettier Biome配置见 lefthook.yml还包含 schemas 类型生成与 release-notes schema 生成等自动任务代码规范先复用再编写优先复用scalar/helpersCLAUDE.md 明确要求写新工具函数之前先查scalar/helpers源码位于 packages/helpers/src。该包按类别覆盖了几乎全部常见需求类别覆盖内容array/object数组操作、深比较、key 助手、路径访问、localStoragedom/nodeDOM 助手、Node 专属路径助手errors/file/formatters错误处理、文件工具、值格式化general/string通用工具、capitalize/hash/truncate/camel-to-titlehttpHTTP 方法、头部、状态码、MIME 类型json/markdown/regexJSON Pointer、标题提取、变量查找替换queue/url异步队列、URL 校验合并与代理助手playwright/storybook/testing/theme/types测试/主题/类型工具只有确实没有现成实现时才允许新增 helper。TypeScript 与 Vue 规范要点TypeScript 侧的关键约定优先type而非interface函数必须有显式返回类型避免any类型不明用unknown避免 enum用字符串字面量联合类型能const就不let类型导入用import type { Foo }单引号、尾逗号、尽量省略分号Vue 侧约定一律 Composition API script setup langts样式用 Tailwind utility classProps 解构带默认值const { prop1, prop2 default } definePropsProps()defineProps/defineEmits必须显式类型script setup推荐顺序imports → props/emits → state/computed/methods → 生命周期注释与文档注释解释why而不是 what使用友好、人性化的语气避免缩略写法写 do not 而非 dont导出的类型与函数要加 JSDoc临时方案用 TODO 注释标记测试规范范围优先跑包不跑仓Scalar 的测试体系分三层单元测试Vitest*.test.ts紧邻源码、E2EPlaywright位于packages/api-reference与packages/components、集成测试pnpm vitest integrations/*。最重要的一条纪律是永远把测试范围限定在改动包内。不要在仓库根目录直接跑pnpm test它会触发整个 monorepo 的测试套件慢且噪音大。推荐两种方式# 方式一从根目录用路径过滤单次运行推荐 pnpm vitest packages/helpers --run pnpm vitest packages/oas-utils --run pnpm vitest integrations/fastify --run # 方式二进入包目录 cd packages/helpers pnpm test --run # watch 模式开发中 pnpm vitest packages/api-client # 从根目录仅当有意验证全仓例如合入前的最终 sanity check时才用根pnpm test。测试编写标准也很明确从vitest显式导入describe/it/expect不用全局变量测试文件命名为name.test.ts与源码同目录顶层describe()与文件名一致测试描述不以 should 开头写it(generates a slug)不写it(should generate a slug)尽量少 mock偏好纯函数Vue 组件测试验证行为不验证 DOM 结构或 Tailwind class 细节需要记住的 Biome 规则在 biome.json 中同样能查到这些规则的实际配置noBarrelFile: error—— 禁止 barrel 文件index.ts入口除外noReExportAll: warn—— 避免export * from在api-reference与openapi-parser中升级为 errornoTsIgnore: error—— 禁止ts-ignore必要时用带说明的ts-expect-erroruseAwait: error—— 异步函数必须使用awaitnoExportsInTest: error—— 测试文件不允许 exportnoFloatingPromises: warn—— 所有 Promise 必须被处理此外biome.json 中还有一条值得注意的noRestrictedImports规则源码文件禁止导入test/*与**/test/**测试助手不得进源码且scalar/components必须从子路径导入如scalar/components/button而不是包级 barrel。Git 工作流与 PR 要求分支命名claude/feature-description—— 新功能claude/fix-description—— Bug 修复claude/chore-description—— 维护性改动Commit Message使用 conventional commits 格式现在时态add 而非 added尽量带 scopefeat(api-client): add new endpoint语义化 PR 标题PR 标题必须遵循type(scope): subjectfix(api-client): crashes when API returns null ^ ^ ^ | | subject | package scope type (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)Ticket 与 Issue 关联当提示词或相关线程中提供了Linear ticket ID如DOC-5102、ENG-123或GitHub issue 号时必须在 PR 中关联方便项目管理集成自动追踪进度。Linear 的 magic words 分两类关闭类close/closes/closed/fix/fixes/fixed/resolve/resolves/resolved与非关闭类ref/refs/references/part of/related to/contributes to/toward/towards且必须放在 PR 描述中不是评论里Fixes DOC-5102 Part of ENG-123 Resolves DOC-5102, ENG-456GitHub issue 则支持跨仓库语法与多 issue 关联场景语法示例同仓库KEYWORD #ISSUECloses #42不同仓库KEYWORD OWNER/REPO#ISSUEFixes scalar/scalar#100多个 issue重复完整语法Resolves #10, resolves #42推荐在 PR 描述底部加## Ticket小节统一放置。若 Linear 与 GitHub issue 同时存在两者都加。Changesets凡涉及packages/*、integrations/*、projects/*的代码变更都需要添加 changeset且只用patch或minor禁用major。开 PR 前先检查状态pnpm changeset status # 检查是否需要版本变更 pnpm changeset # 添加 changeset改代码后的自查清单CLAUDE.md 要求任何代码变更后只针对你改动的文件和包运行 lint、format 与类型检查绝不在全仓跑# 1. 只对改动文件做 lint format CHANGED$(git diff --name-only HEAD) pnpm biome check --write --diagnostic-levelerror --no-errors-on-unmatched --files-ignore-unknowntrue $CHANGED pnpm prettier --write $CHANGED # 2. 只跑受影响包的测试 pnpm vitest packages/package-name --run pnpm vitest integrations/integration-name --run # 3. 只对受影响包做类型检查 pnpm --filter scalar/package-name types:check # 4. 开 PR 前检测未使用的导出、文件与依赖 pnpm knip所有检查必须干净通过——不允许带着 lint 错误、类型错误或未使用导出提交代码。可视化测试改动 UI 必须附截图/视频由于大多数包的上游依赖最终都会汇入api-reference、api-client、components三大可视化表面因此任何 UI 改动都必须附带视觉产物截图或演示视频。准备工作pnpm install pnpm build:packages或者在包目录里用pnpm turbo dev/pnpm turbo build自动构建上游依赖。三个 playground 的启动方式包快速启动Turbo 方式api-referencecd packages/api-reference pnpm devpnpm turbo --filter scalar/api-reference devapi-clientcd packages/api-client pnpm devpnpm turbo --filter scalar/api-client devcomponentscd packages/components pnpm devpnpm turbo --filter scalar/components dev各包的详细说明可参见 packages/api-reference/AGENTS.md 与 packages/api-client/AGENTS.md。其中api-client有web / app / modal三种布局web 是独立浏览器客户端单请求聚焦也是默认 dev 目标app 是完整桌面风格布局含侧边栏、集合、环境与 workspace 管理modal 是浮层布局也可通过 api-reference playground 中任意操作的 Test Request 按钮触发。如何选择 playground改动区域首选 playground次选基础组件按钮、输入框、弹窗componentsStorybookapi-reference、api-client主题、CSS 变量、设计 tokenapi-referenceapi-client、components侧边栏、搜索、OpenAPI 渲染api-referenceapi-client请求编辑器、响应查看器、认证api-clientweb appapi-referencemodal代码高亮、代码片段api-referenceapi-client图标componentsStorybookapi-referencePR 中嵌入视觉产物产物保存在/opt/cursor/artifacts/用描述性的 snake_case 命名并在 PR 描述中通过绝对路径引用img src/opt/cursor/artifacts/screenshot_before.png altBefore change / img src/opt/cursor/artifacts/screenshot_after.png altAfter change / video src/opt/cursor/artifacts/demo_feature.mp4 controls/videoPR 描述中建议加## Visual小节统一放置产物。捕获要点改动 UI 的前后对比截图、新功能的上下文截图、来自最相关 playground 的产物、交互行为的演示视频若改动横跨多个可视化表面则从多个 playground 各取产物。OpenAPI 术语统一为了让所有贡献者和 Agent 使用一致的术语仓库规定OpenAPI而非 Swagger—— 规范格式本身API description而非 API spec 或 API definition—— 元数据文档Schema—— 请求/响应形状的数据模型Dereference—— 用值替换所有$refBundle—— 把外部$ref的值拉进单个文件Resolve—— 在$ref处查找值而不修改文档这套术语贯穿packages/openapi-parser、packages/openapi-validator等包的文档与代码写作和讨论时保持一致有助于避免歧义。开发环境注意事项Cursor Cloud 场景针对云端 Agent 环境CLAUDE.md 补充了几条实用提示Node.js v24 由 nvm 管理pnpm v10.16.1 由 corepack 激活无需全局安装pnpm install后可能看到 esbuild 构建脚本被忽略的警告——可安全忽略Vite 8 使用 Rolldown不需要 esbuild 的平台二进制也能完成构建pnpm --filter scalar/api-reference dev固定监听5173端口部分包如openapi-parser、snippetz存在与/路径别名解析相关的既有测试失败属于环境已知问题而非新引入依赖网络服务的测试必须先启动测试服务器pnpm script run test-servers # 启动 void-server(5052) 与 proxy(5051) pnpm script wait -p 5051 5052 # 等待端口就绪快速验证测试框架可用性pnpm vitest packages/oas-utils --run延伸阅读想进一步了解贡献流程可阅读 CONTRIBUTING.md其中涵盖了 PR 要求、changesets 与自动生成文件如各集成的 README.md 由pnpm script generate-readme生成、Java/.NET 的枚举由 TypeScript 客户端配置生成。更多仓库背景与产品能力可参见根 README.md。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考