ln-741-linter-configurator

**路径：**文件路径（references/、../ln-*）均相对于此技能目录。

ln-741-linter-configurator

**类型：**L3 Worker **类别：**7XX 项目引导

为 TypeScript、Python 和 .NET 项目配置代码检查、格式化和类型检查工具。

---

用途与范围

会执行：

• 根据项目类型检测要配置的代码检查工具栈
• 检查是否已有代码检查配置
• 根据模板生成适当的配置文件
• 安装所需依赖（始终使用最新版本，不固定版本）
• 生成统一的代码检查脚本（scripts/lint.sh）
• 验证所有代码检查工具均可无错误运行

不会执行：

• 配置 pre-commit 钩子（由单独的 worker 负责）
• 搭建测试基础设施（由单独的 worker 负责）
• 修改源代码

---

支持的工具栈

技术	代码检查工具	类型检查器	格式化工具	配置文件
TypeScript	ESLint 9+（扁平配置）	TypeScript (tsc)	Prettier	eslint.config.ts、.prettierrc
.NET	Roslyn 分析器	Roslyn	dotnet format	.editorconfig、Directory.Build.props
Python	Ruff	mypy	Ruff（内置）	ruff.toml、mypy.toml（或 pyproject.toml）

---

阶段 1：检查现有配置

生成配置之前，检查已有的配置。

要检查的文件：

工具栈	配置文件	Glob 模式
TypeScript	ESLint 配置	eslint.config.*、.eslintrc*
TypeScript	Prettier 配置	.prettierrc*、prettier.config.*
.NET	Editor 配置	.editorconfig
.NET	构建属性	Directory.Build.props
Python	Ruff 配置	ruff.toml、pyproject.toml
Python	mypy 配置	mypy.toml、mypy.ini、pyproject.toml [tool.mypy]

决策逻辑：

1. 如果不存在配置：根据模板创建
2. 如果配置存在但不完整（规则/工具少于模板）：扩展至符合模板
3. 如果配置符合模板：跳过（告知用户）

完整性检查（Python）：

方面	检查内容	模板标准
Ruff 规则	统计 select 条目数	23+ 个类别（参见 ruff_template.toml）
Ruff 按文件忽略规则	存在测试部分	tests/**/*.py 包含 S101、S105、S106、T201
Ruff 高级配置	mccabe、flake8-bugbear、isort	全部存在
MyPy	strict = true	已启用
高级工具	开发依赖中包含 import-linter、deptry、vulture	全部已安装
代码检查脚本	scripts/lint.sh 包含 7 项检查	7 项均已启用
.editorconfig	文件存在	存在

---

阶段 2：生成配置

使用 references/ 文件夹中的模板。根据项目自定义占位符。

TypeScript：

1. 将 eslint_template.ts 复制到项目根目录，并命名为 eslint.config.ts
2. 将 prettier_template.json 复制为 .prettierrc
3. 在 package.json 中添加脚本：
   • "lint": "eslint ."
   • "lint:fix": "eslint . --fix"
   • "format": "prettier --write ."
   • "format:check": "prettier --check ."
   • "typecheck": "tsc --noEmit"
   • "lint:all": "npm run typecheck && npm run lint && npm run format:check"
4. 对于 React 项目：取消模板中 React 部分的注释

.NET：

1. 将 editorconfig_template.ini 复制为 .editorconfig
2. 将 directory_build_props_template.xml 复制为 Directory.Build.props
3. 确保已包含分析器（SDK 5+ 默认包含）

Python：

1. 将 ruff_template.toml 复制为 ruff.toml
   • 或者合并到现有的 pyproject.toml 中的 [tool.ruff] 下
2. 将 mypy_template.toml 复制为 mypy.toml
   • 或者合并到现有的 pyproject.toml 中的 [tool.mypy] 下
3. 更新 isort 配置中的 known-first-party，使其与项目包名一致
4. 更新 mypy 配置中的 files，使其与项目源代码目录一致
5. 在 pyproject.toml 中生成高级工具配置：
   • 根据 importlinter_template.toml 添加 [tool.importlinter]，并根据项目分层结构调整 root_packages 和 contracts
   • 根据 vulture_template.toml 添加 [tool.vulture]，并根据项目源代码目录调整 paths
   • 根据 deptry_template.toml 添加 [tool.deptry]，并调整 extend_exclude
6. 根据 editorconfig_template.ini 生成 .editorconfig，并调整 max_line_length 以匹配 ruff 的 line-length

---

阶段 3：安装依赖

安装所需的软件包。始终安装最新版本——不要固定版本。

TypeScript：

npm install -D eslint @eslint/js typescript-eslint eslint-config-prettier prettier eslint-plugin-unicorn jiti

对于 React 项目，还需安装：npm install -D eslint-plugin-react eslint-plugin-react-hooks

关于 jiti 的说明： 在 Node.js < 22.10 上使用 eslint.config.ts 时需要 jiti。在 Node.js 22.10+ 上，原生支持 TypeScript 配置。

.NET：

• SDK 5+ 已包含分析器——无需单独安装

Python：

uv add --dev ruff mypy import-linter deptry vulture pip-audit

# OR without uv:
pip install ruff mypy import-linter deptry vulture pip-audit

---

阶段 4：生成 lint 脚本

根据检测到的技术栈，为 scripts/lint.sh 生成 lint_script_template.sh 中的配置，并包含所有检查项。

1. 将 lint_script_template.sh 复制到 scripts/lint.sh
2. 取消与检测到的技术栈匹配的所有检查项注释——包括基础工具和高级工具：

技术栈	检查项	总计
Python	ruff check、ruff format、mypy、lint-imports、deptry、vulture、pip-audit	7
TypeScript	typecheck、eslint、prettier、knip、depcruise	5
.NET	dotnet build、dotnet format	2

3. 将 TOTAL 设置为启用的检查项数量
4. 取消 --fix 块中匹配的自动修复命令注释
5. 设置可执行权限：chmod +x scripts/lint.sh
6. 对于 TypeScript：确保 package.json 中存在 "lint:all" 脚本

---

阶段 5：验证设置

完成配置后，验证一切正常。

TypeScript：

npx tsc --noEmit
npx eslint .
npx prettier --check .

.NET：

dotnet format --verify-no-changes

Python：

ruff check .
ruff format --check .
mypy

统一验证：

bash scripts/lint.sh

预期结果：所有检查的退出代码均为 0。

失败时： 检查错误输出，调整配置，然后重新验证。

---

阶段 6：修复 lint 错误

生成所有配置并安装工具后，运行 bash scripts/lint.sh --all 查看所有违规项。

1. 运行 bash scripts/lint.sh --fix，自动修复 ruff 可以修复的问题
2. 手动修复剩余错误（逐个文件处理）
3. 对于当前无法重构的函数上的 C901（复杂度）错误：添加 # noqa: C901
4. 对于 deptry 误报：添加 [tool.deptry.per_rule_ignores] 条目
5. 重复以上步骤，直到 bash scripts/lint.sh 通过且失败数为 0

---

关键规则

规则 1： 同时使用 ESLint 和 Prettier 时，始终包含 eslint-config-prettier（放在配置的最后）。

规则 2： 使用 ESLint 扁平配置格式（eslint.config.ts），不要使用旧版 .eslintrc。

规则 3： Ruff 可替代 Black、isort、flake8 和许多其他 Python 工具。不要单独安装这些工具。

规则 4： 除非有记录在案的理由，否则绝不要禁用严格的 TypeScript 规则。

规则 5： Python 项目始终要与 Ruff 一起运行 mypy。Ruff 负责处理风格和错误，mypy 负责类型安全。

规则 6： 将 recommendedTypeChecked 设为 ESLint 默认配置，而不只是 recommended。如有需要，可降低单个规则的严格程度。

规则 7： 安装命令中绝不要固定依赖版本——始终安装最新版本。

规则 8： 高级静态分析工具（import-linter、deptry、vulture、pip-audit）是 Python 项目的必需项，不可省略。

---

Monitor（2.1.98+）： 当 lint/typecheck 验证命令预计耗时超过 30 秒时，使用 Monitor。备用方案：Bash(run_in_background=true)。

完成标准

• 已为检测到的技术栈创建合适的配置文件
• 已安装依赖项（最新版本）
• 已生成 scripts/lint.sh，并包含适用于该技术栈的检查项
• lint 命令运行项目源代码时无错误
• 格式化命令运行无错误
• 类型检查器运行无错误（Python 使用 mypy，TypeScript 使用 tsc）
• ESLint/Prettier 无冲突（已安装 eslint-config-prettier）
• 已安装并配置高级工具（import-linter、deptry、vulture、pip-audit）
• scripts/lint.sh 运行所有检查（Python 项目共 7 项），退出代码为 0
• 已创建 .editorconfig，其设置与 ruff 配置相匹配
• 已告知用户可用的 lint/格式化命令

---

参考文件

文件	用途
eslint_template.ts	ESLint 扁平配置模板（TypeScript）
prettier_template.json	Prettier 配置模板
ruff_template.toml	Python Ruff 配置模板
mypy_template.toml	Python mypy 配置模板
lint_script_template.sh	统一 lint 脚本模板
editorconfig_template.ini	.NET editorconfig 模板
directory_build_props_template.xml	.NET 分析器模板
importlinter_template.toml	Python import-linter 配置模板
vulture_template.toml	Python vulture 配置模板
deptry_template.toml	Python deptry 配置模板
linter_guide.md	详细配置指南

---

错误处理

错误	原因	解决方法
ESLint/Prettier 冲突	缺少 eslint-config-prettier	安装并将其添加为最后一项配置
ESLint projectService 错误	配置文件不在 tsconfig 中	将其添加到 allowDefaultProject 列表
ESLint .ts 配置失败	缺少 jiti	npm install -D jiti
TypeScript 解析错误	解析器版本不匹配	使 typescript-eslint 与 TS 版本保持一致
mypy 缺少存根文件	第三方库没有类型信息	添加包含 ignore_missing_imports 的 [[mypy.overrides]]
mypy 严格模式过于严格	首次运行时出现数百个错误	从宽松配置开始，逐步启用严格模式
找不到 Ruff	未安装	pip install ruff 或 uv add ruff
dotnet format 失败	缺少 SDK	安装 .NET SDK

---

版本： 4.0.0 最后更新： 2026-03-18