javascript-conventions

JavaScript/TypeScript 约定

当 JavaScript、TypeScript、Node.js 工具链或 package.json 是主要工作内容时，请遵循这些约定。

分派

$ARGUMENTS	操作
Active（当 JS/TS 是主要工作内容时自动调用）	应用以下操作规范
Empty	显示约定摘要和路由指南
check	仅验证工具链是否合规

参考文件索引

文件	用途	何时阅读
references/tooling-contract.md	package manager、命令、CI、工作区和 package 根目录的必需规则	涉及 package 命令、脚本、依赖、lockfile 或 CI 时
references/redirection-boundaries.md	说明何时应由 Python、shell、CI 或特定框架的技能优先处理 JS/TS 约定	多语言或工作内容不明确时
references/edge-cases.md	npm/yarn、Corepack、生成的应用和迁移的例外条件	偏离 pnpm 默认设置时
references/typescript-patterns.md	TypeScript 配置、类型收窄、类型守卫、联合类型和类型测试模式	涉及 TypeScript 代码或 tsconfig.json 时
references/eslint-prettier.md	ESLint flat config、类型化 lint 和 Prettier 分工	涉及 lint 或格式调整时

操作规范

Active

1. 仅当 JS/TS 文件、Node 工具链或 package.json 是任务的主要内容时，才应用此技能。
2. 当 JS/TS 与 Python、shell、CI 或特定框架的工作同时出现时，阅读 references/redirection-boundaries.md。
3. 对 package 管理、package 根目录选择、命令执行、lockfile、工作区和 CI 安装，遵守 references/tooling-contract.md 中的硬性要求。
4. 在建议使用 npm、yarn、全局 package manager、假定使用 Corepack 或迁移 lockfile 前，先查看 references/edge-cases.md。
5. 涉及 TypeScript 配置或类型安全调整时，阅读 references/typescript-patterns.md。
6. 涉及 lint、类型化 lint 或格式调整时，阅读 references/eslint-prettier.md。
7. 仅在开始新工作或仓库没有更强的本地约定时，采用引导性偏好。

Empty / Help

1. 总结硬性要求：pnpm、packageManager、pnpm-lock.yaml、pnpm install --frozen-lockfile、pnpm exec、pnpm dlx、tsc --noEmit、eslint 和 prettier。
2. 说明硬性要求与引导性偏好的区别。
3. 指明工具链、例外情况、TypeScript、lint/format 和多语言路由所对应的具体参考文件。

check

1. 仅验证 JS/TS 工具链是否合规；除非用户提出要求，否则不要扩展到实现建议。
2. 报告项目是否使用预期的 package 根目录、pnpm、packageManager、pnpm-lock.yaml、工作区配置、脚本、tsconfig.json、ESLint flat config 和 Prettier。
3. 标记 npm/yarn/Corepack/旧版配置的偏离情况，并要求理由符合 references/edge-cases.md。
4. 除非有记录在案的例外，否则拒绝以 npm install、npx 或临时全局二进制文件替换仓库要求的工具链的建议。

硬性要求

• Package manager：除非有记录在案的例外，否则 JS/TS package 操作一律使用 pnpm。
• Package manager 固定版本：遵循最近的所属 package.json 中的 packageManager 字段。
• Lockfile：提交 pnpm-lock.yaml；单个 package 根目录内绝不混用 lockfile，除非有迁移计划。
• 安装：使用 pnpm install；在 CI 中使用 pnpm install --frozen-lockfile。
• 依赖：在所属 package 根目录中使用 pnpm add <pkg> 或 pnpm add -D <pkg>。
• 本地二进制文件：使用 pnpm exec <cmd>；仅在一次性从 registry 执行时使用 pnpm dlx <pkg>。
• 脚本：使用 pnpm run <script> 或 pnpm --filter <pkg> run <script>。
• 类型检查：使用 pnpm exec tsc --noEmit 或仓库的 package 脚本。
• Lint：新建 ESLint 配置时使用 ESLint flat config。
• 格式化：使用 Prettier 进行格式化，使用 ESLint 执行代码质量规则。

指导性偏好

开始新的 JS/TS 工作且没有更严格的本地约束时，优先使用以下工具。这些是默认选择，并非绝对规则；覆盖现有项目选择前，请先查看 references/edge-cases.md。

用途	工具	说明
包管理器	pnpm	当包根目录拥有 package.json 时，通过 packageManager 固定版本
打包工具	vite 或 esbuild	优先遵循框架自带的构建工具
代码检查	eslint	新建配置时使用扁平配置
格式化	prettier	将格式化与代码检查分开
测试	vitest 或框架原生运行器	优先使用仓库中已有的脚本
类型检查	tsc --noEmit	通过 pnpm exec 或包脚本运行

TypeScript 类型安全

1. 优先使用 unknown 而非 any；不要为了让代码通过编译而放宽既有的严格性。
2. 对象结构优先使用 interface，联合类型、交叉类型和映射类型使用 type。
3. 对状态机和带标签的变体使用可辨识联合类型。
4. 使用 as const 和 satisfies 保留字面量推断，避免不安全的断言。
5. 避免类型断言（as）；优先使用类型守卫、断言函数，以及在边界处进行模式验证。
6. 在新的 TypeScript 项目中启用 strict，并在仓库能够承受时添加更严格的选项。
7. 如果类型契约是公开的，请使用 @ts-expect-error 或类型测试工具，测试负向类型行为。
8. 有关 TSConfig、模块解析和类型收窄模式，请参阅 references/typescript-patterns.md。

关键规则

1. 除非 references/edge-cases.md 说明使用 npm、yarn 或其他包管理器的理由，否则 JS/TS 依赖变更必须使用 pnpm。
2. 运行包命令前，先确定所属包的根目录；不要假定仓库根目录包含所有 JS/TS 文件。
3. 同一个包根目录中不得混用 pnpm-lock.yaml、package-lock.json 和 yarn.lock，专门的迁移除外。
4. 存在 pnpm-lock.yaml 时，CI 安装必须运行 pnpm install --frozen-lockfile。
5. 本地二进制文件使用 pnpm exec；只有从注册表获取一次性包时才使用 pnpm dlx。
6. 不要假定当前 Node.js 运行时捆绑了 Corepack；建议配置 Corepack 前，请先查看 references/edge-cases.md。
7. 格式化由 Prettier 负责，代码质量规则由 ESLint 负责。
8. 对于混合语言或非 JS 为主的工作，请通过 references/redirection-boundaries.md 转交，而不要强行将整个任务套用此技能。

扩展策略

• 更广泛的非 JS 任务中偶然涉及 JS/TS 文件：仅对 JS/TS 所属部分强制执行硬性要求，然后通过 references/redirection-boundaries.md 处理混合工作流问题。
• 以 JS/TS 为主的功能或重构工作：根据相关情况应用完整的操作规范，包括工具、TypeScript、代码检查、格式化和测试指导。
• 仓库范围的 JS/TS 工具或迁移工作：使用 check、references/tooling-contract.md 和 references/edge-cases.md，区分硬性违规与文档记录的过渡路径。

渐进式披露

• 默认不要加载所有参考资料。
• 涉及命令、依赖、包根目录、工作区、锁文件或 CI 的问题，先阅读 references/tooling-contract.md。
• 请求中混合了 Python、shell、CI、基础设施或特定框架工作时，阅读 references/redirection-boundaries.md。
• 只有任务似乎需要 npm、yarn、Corepack 配置、生成式应用脚手架或锁文件迁移例外时，才阅读 references/edge-cases.md。
• 只有涉及 TypeScript 代码、tsconfig.json、公开类型或类型测试时，才阅读 references/typescript-patterns.md。
• 只有任务涉及代码检查、类型化代码检查或格式化时，才阅读 references/eslint-prettier.md。

适用范围

适用于： JS/TS 工具约定、Node 包命令、依赖管理规则、TypeScript 类型安全默认设置、lint/格式化/测试命令指南，以及考虑例外情况的仓库指南。

不适用于： Python 约定、shell 约定、CI 流水线设计、框架架构、仅限后端的实现策略，或宽泛的前端 UX/设计指南。

规范术语（请严格使用以下术语）：

• pnpm -- JS/TS 包操作必需的包管理器
• package root -- 拥有该命令或依赖项的 package.json 所在的最近目录
• packageManager -- 用于锁定包管理器及其版本的 package.json 字段
• pnpm-lock.yaml -- pnpm 包根目录使用的规范 JS/TS 锁文件
• workspace -- 由 pnpm-workspace.yaml 声明的 pnpm 工作区
• frozen-lockfile -- 阻止修改锁文件的 CI 安装模式
• pnpm exec -- 执行本地项目二进制文件
• pnpm dlx -- 从注册表临时执行一次性包

验证要求

在声明更改完成之前，请从此技能目录运行：

python scripts/check.py
git diff --check

完成标准：

1. scripts/check.py 以 0 退出。
2. git diff --check 以 0 退出。
3. 此技能目录下不存在任何可移植 CLI 违规。

更改技能定义、公开描述、参考文件或评估行为后，如果 docs-steward 可用，请调用它。