Storybook 仓库 PR 的 Lint 与 TypeScript 修复 Skill：从 gh pr checkout 到 CI 全绿的完整工作流

Storybook 仓库 PR 的 Lint 与 TypeScript 修复 Skill从 gh pr checkout 到 CI 全绿的完整工作流Storybook 主仓库维护了一套面向 AI Agent 的技能Skill定义其中fix-linting-types-on-pr技能专门解决一个高频维护场景当一个 Pull Request 的 CI 因 lint 或 TypeScript 类型错误而失败时如何以最小侵入的方式检出 PR、批量修复错误并推送回去。本文完整还原该技能定义的八步工作流并结合仓库中 nx.json、check-package.ts、code/package.json 等真实配置与源码解释每一步命令背后的实际作用读完即可在 Storybook 仓库或同构的 Nx Yarn Workspaces 大型 monorepo中复现这一修复流程。技能定位它是什么、何时触发技能的实际定义位于 .agents/skills/fix-linting-types-on-pr/SKILL.md而 .claude/skills/fix-linting-types-on-pr/SKILL.md 仅包含一行指向该定义文件的引用从文件结构看这是一种将技能定义放在共享.agents目录、再由.claude目录别名引用来复用的组织方式。技能文件采用带 YAML frontmatter 的 Markdown 格式--- name: fix-linting-types-on-pr description: Checks out a PR (including fork PRs), fixes all linting and TypeScript errors, then pushes the changes back. Use when asked to fix lint, types, or TS errors on a PR. ---name是技能的唯一标识description同时承担了触发条件说明——只有当用户请求修复 PR 上的 lint / types / TS 错误时才应启用该技能。技能覆盖的目标仓库是 Storybook 主仓库本身一个基于 Nx 任务编排、Yarn 4 workspaces、oxlint 与原生 TypeScript 编译器的大型 monorepo。这决定了工作流中大量命令不是通用模板而是与仓库脚本精确对齐的。第一步确定 PR 编号技能要求如果用户已给出 PR 编号则直接使用否则主动向用户索取。这是整个流程的输入锚点后续所有gh操作都围绕它展开。第二步用 gh pr checkout 检出 PRgh pr checkout PR_NUMBER技能中明确指出选用gh pr checkout而非手动git fetch git checkout的原因它对 fork PR 和非 fork PR 同样有效。该命令会自动建立正确的 remote tracking 并切换到 PR 分支——对于来自 fork 的贡献者 PR普通git checkout往往找不到对应分支而gh pr checkout会处理pull/N/head引用并配置好上游跟踪关系。这一点直接服务于第八步的git push因为跟踪关系已在检出时配好推送时无需再指定 remote 和分支名。第三步安装依赖yarnStorybook 仓库根目录 package.json 声明了packageManager: yarn4.18.0并通过 workspaces 字段纳入了code/addons/*、code/frameworks/*、code/lib/*、code/renderers/*等全部子包。检出 PR 分支后依赖树可能已变更先执行yarn保证本地node_modules与 PR 分支的yarn.lock一致是后续编译与检查任务可复现的前提。第四步先编译整个仓库yarn nx run-many -t compile技能文档特别强调了这一步的必要性先编译确保 linter 所引用的 TS 声明文件已经存在。在仓库的 nx.json 中可以找到compiletarget 的完整定义compile: { dependsOn: [^compile], command: node ... ./scripts/build/build-package.ts --cwd {projectRoot}, configurations: { production: { args: --prod } }, cache: true, inputs: [production, ^production], outputs: [ {projectRoot}/dist, {workspaceRoot}/code/bench/esbuild-metafiles/{projectName} ] }这里有几个要点dependsOn: [^compile]表示各包按依赖顺序先编译上游包保证子包编译时能解析到依赖包的dist产物含类型声明产物落到{projectRoot}/dist并且任务开启了 Nx 缓存cache: true重复执行时未变更的包会被缓存命中正是这些dist中的.d.ts声明文件成为后续 lint 与类型检查阶段跨包类型解析的基础——跳过编译直接跑 lint/类型检查会出现大量找不到模块声明的假性错误。第五步修复 Lint 错误yarn lint顺着仓库脚本链路看这条命令的真实内容根 package.json 中lint: cd code; yarn lint转到 code/package.json 后是lint: yarn lint:js→lint:js: yarn lint:js:cmd . --quiet最终执行的命令是lint:js:cmd: oxlint --report-unused-disable-directives-severityerror也就是说 Storybook 仓库的 lint 引擎是oxlint并且把未被使用的 eslint-disable 指令提升为 error——这意味着在修复过程中如果删除了某条规则报错的代码配套的eslint-disable注释也会被要求一并清理否则 lint 仍会失败。这也是该技能适合批量修复的原因oxlint 本身速度快且支持 autofix大部分格式、未使用变量等问题可以先自动修复剩余问题再手工处理。第六步修复 TypeScript 错误yarn nx run-many -t checkchecktarget 的定义同样在 nx.json 中check: { dependsOn: [{ projects: [*], target: compile }], command: yarn exec jiti ./scripts/check/check-package.ts --cwd {projectRoot}, cache: true, inputs: [default, ^production] }其命令最终落到 scripts/check/check-package.ts。阅读该脚本可以看到检查的真实机制它调用的是typescript-native 的原生 tscrequire.resolve(typescript-native/package.json)下的bin/tsc以--project tsconfig.json --noEmit --pretty false运行即只做类型检查、不产出文件且输出为可解析的纯文本每个包的 tsc 设有TSC_TIMEOUT_MS 10 * 60 * 1000的超时上限源码注释说明其意图是卡死的原生编译器应让单个包快速失败而不是拖到整个 check 任务阻塞到 CI 超时检查完原始输出后会调用 filterToPackageDiagnostics 过滤诊断结果——该函数只保留路径没有越过包目录!rel.startsWith(..)的诊断从而把本包引入的报错与上游包的问题区分开避免修复者在错误的包里找问题。严格模式也是理解报错密度的一把钥匙code/tsconfig.json 中显式启用了strict: true与strictBindCallApply: true。技能文档给出的常见修复类型包括添加或纠正类型标注修正错误的泛型实参解决违反 strict 模式的any赋值补齐缺失的 import 或 re-export。并要求每修完一批就重跑一次yarn nx run-many -t check确认错误已消除形成编辑 → 验证的小步循环而不是攒到最后一次性面对整屏报错。第七步提交修复git add files-you-modified git commit -m Maintenance: Fix linting and TypeScript errors技能对提交方式有两条明确约束只暂存自己改动的文件git add 具体文件并明确禁止git add -A——检出 PR 分支时工作区可能带有其他改动全量暂存会把无关文件一并推上去提交信息采用仓库可识别的维护类前缀Maintenance:与功能提交区分开便于 PR 描述与 changelog 生成时归类。第八步推送并确认 CIgit push对 fork PRgh pr checkout已在检出时配置好 upstream tracking因此直接git push即可把修复提交叠加到 PR 之上无需额外指定远端。边界约束技能 Notes 里的四条纪律技能文档末尾的 Notes 定义了该流程的行为边界这些约束与命令本身同等重要只修明确属于 lint 或 TypeScript 问题的错误不做逻辑重构。这保证了修复提交可审计diff 中不应出现行为变更遇到需要非平凡代码改动的类型错误时先向用户维护者暴露并确认再继续——类型错误有时暗示接口设计问题自动修掉可能掩盖真实缺陷如果gh pr checkout因 fork 权限失败如实告知用户贡献者可能需要授予 fork 写权限或由维护者直接推送推送后必须与用户确认 CI 已全绿而不是把push 成功当成任务终点。小结与证据索引这套技能的价值在于把修 CI 中 lint/类型错误这件重复性劳动固化成了一条与 Storybook 仓库工程结构精确对齐的流水线gh pr checkout处理 fork 场景、nx run-many -t compile保证声明文件就位、oxlint 完成快速 lint、基于 typescript-native tsc 的分包check任务配合诊断过滤精确定位类型错误最后以最小化提交推回。所有命令均能在仓库中逐一验证环节命令仓库证据编译yarn nx run-many -t compilenx.json 中compiletarget、scripts/build/build-package.ts 构建脚本Lintyarn lintpackage.json 与 code/package.json 中的 oxlint 脚本链类型检查yarn nx run-many -t checkscripts/check/check-package.ts、scripts/check/utils/typescript.ts严格模式—code/tsconfig.json 的strict配置需要注意适用前提该工作流依赖 Storybook 仓库的 Nx 目标命名compile/check、Yarn 4 包管理器与ghCLI 环境移植到其他 monorepo 时需按其脚本体系做相应替换。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考