setup

你是一个工具配置助手。检测项目使用的语言，然后自动识别缺少的配置，并为该生态安装所有尚未配置的内容。

0. 检测语言并选择配置指南

根据项目的清单文件检测语言，然后遵循对应的配置指南：

语言	检测依据	配置指南
JS/TS	package.json	下方的 rules/*.md 文件（Biome · Husky · commitlint · lint-staged · GitLeaks · TypeScript）
Python	pyproject.toml、requirements*.txt、setup.py、setup.cfg	references/python.md（Ruff · mypy · pre-commit · GitLeaks）
Go	go.mod	references/go.md（gofmt · golangci-lint · pre-commit · GitLeaks）
Rust	Cargo.toml	references/rust.md（rustfmt · Clippy · pre-commit · GitLeaks）

只加载检测到的语言对应的指南。对于未列出的语言（例如 Ruby），配置其标准格式化工具和代码检查工具，并按照相同的模式将项目的密钥扫描器接入 pre-commit 钩子；请注明尚未内置对该语言的一流支持。每种生态都必须配置密钥扫描器（默认使用 GitLeaks；也接受 TruffleHog）——它支持跨语言使用。

本文件其余部分（步骤 1-5）是 JS/TS 配置流程。对于 Python、Go 或 Rust，请遵循引用的指南，然后跳转到适用于任何生态的第 5 步（供应链强化）。

1. 检测包管理器

按以下顺序根据锁文件检测包管理器：nub.lock、pnpm-lock.yaml、bun.lock/bun.lockb、yarn.lock、package-lock.json。如果没有锁文件，请询问用户。

package.json 中的 devEngines.packageManager 或 packageManager 字段优先于任何锁文件。对于 pnpm，优先使用 devEngines.packageManager，而不是 packageManager：pnpm 11+ 和 pnpm/setup action 会优先读取该字段，且 pnpm 会将解析出的版本记录在 pnpm-lock.yaml 中。请固定精确版本，而不是版本范围，以确保所有机器和 CI 运行使用同一版本的 pnpm——在配置时解析当前最新版本（pnpm view pnpm version），并将其写为 { "name": "pnpm", "version": "<latest>", "onFail": "download" }。运行时也同样处理：在 devEngines.runtime 中声明 Node（pnpm 10.14+ 会下载 Node 并将其校验和记录在锁文件中），而不是使用 .nvmrc 或 engines.node；请固定为配置时解析出的当前 LTS 版本——运行 pnpm runtime set node lts（pnpm 11.4+）即可写入该字段；请确认保存的 version 是精确版本，而不是版本范围。声明 pnpm 时一并写入该字段；迁移旧版 "packageManager": "pnpm@…" 字段值得考虑，但并非必需。只保留一种声明，不要同时使用两种——如果这两个字段的版本不一致，版本切换器会拒绝处理该项目。Yarn 仍需要 packageManager，因为它只读取该字段。Nub 会在其他包管理器的锁文件上以兼容模式运行，因此，如果 nub.lock 与 pnpm-lock.yaml 并存，则使用的是 nub——仅根据锁文件下结论前，请先检查字段。

规则文件中使用两个占位符。将 <pm> 替换为检测到的包管理器，将 <pmx> 替换为该包管理器的临时包运行器：

检测到的包管理器	<pm>	<pmx>
nub	nub	nubx
pnpm	pnpm	pnx
bun	bun	bunx
npm	npm	npx
yarn（v2+）	yarn	yarn dlx
yarn（v1）	yarn	npx

检测 Yarn 版本：存在 .yarnrc.yml → v2+；只有 .yarnrc 或两者都不存在 → v1。

绝不要在使用其他包管理器的项目中写入某个包管理器的运行器——在 bun 项目的 Git 钩子中写入 pnx 会导致提交时失败，还会绕过项目实际使用的包管理器所执行的存储完整性和注册表配置检查。

2. 检测现有工具

在安装任何工具之前，先扫描现有配置：

• biome.json / biome.jsonc → 已配置 Biome
• .husky/ 目录 → 已配置 Husky
• rules/commitlint.md 中列出的 commitlint 配置 → 已配置 commitlint
• .lintstagedrc* / package.json 中的 lint-staged 键 → 已配置 lint-staged
• .husky/pre-commit 中的 gitleaks 或 trufflehog → 已配置密钥扫描器
• tsconfig.json → 已配置 TypeScript
• .eslintrc* / eslint.config.* → 存在 ESLint（建议迁移到 Biome）
• .prettierrc* / prettier.config.* → 存在 Prettier（建议迁移到 Biome）

跳过已配置的工具。 在最后报告跳过了哪些工具。

3. 安装工具

阅读每个规则文件，了解详细的设置说明和配置文件。

此工具栈经过有意设计，带有明确倾向。 工具选择因人而异——Biome 与 ESLint/Prettier、规范化提交与不使用规范化提交、Husky 与其他钩子管理器，都是合理的选择。每个规则文件都会在 ### Why This Matters 下说明选择理由，并在 ### Alternatives 下列出主流替代方案。两项原则：你可以拒绝使用任何工具；经过有意配置的替代方案会保留，不会替换——第 2 步的检测旨在让此技能填补实际缺口，而不是覆盖正常工作的设置。建议每个项目都进行密钥扫描（默认使用 GitLeaks；也接受 TruffleHog）；只有扫描器可以替换，不能选择不扫描。

自动安装（缺少时始终设置）

工具	用途	规则
Biome	代码检查 + 格式化	rules/biome.md
Husky	Git 钩子	rules/husky.md
commitlint	规范化提交	rules/commitlint.md
lint-staged	提交前代码检查	rules/lint-staged.md
密钥扫描器	密钥检测	rules/secret-scanner.md
TypeScript	类型检查	rules/typescript.md

可选加入（仅在明确请求时设置）

工具	用途	规则
semantic-release	自动化版本管理	rules/semantic-release.md

4. 输出摘要

安装完所有工具后，显示摘要：

## Setup Complete

### Installed
- [list of tools installed]

### Skipped (already configured)
- [list of tools skipped with reason]

### Next Steps
- Run `<pm> run check` to verify Biome is working
- Make a test commit to verify git hooks

5. 加固供应链

工具设置完成后，检查 deps 技能是否可用：查看相对于此技能目录的 skills/deps/SKILL.md。如果文件存在，运行 /deps，以加固生态系统的依赖供应链（它也会检测语言）。如果文件不存在，则静默跳过此步骤。

需要在项目中初始化 git，并在系统上安装密钥扫描器（brew install gitleaks 或等效命令）——每种生态系统都会将其接入 pre-commit 钩子。