everything-claude-code/docs/zh-CN/commands/build-fix.md

构建与修复

以最小、安全的更改逐步修复构建和类型错误。

步骤 1：检测构建系统

识别项目的构建工具并运行构建：

指示器	构建命令
package.json 包含 build 脚本	npm run build 或 pnpm build
tsconfig.json（仅限 TypeScript）	npx tsc --noEmit
Cargo.toml	cargo build 2>&1
pom.xml	mvn compile
build.gradle	./gradlew compileJava
go.mod	go build ./...
pyproject.toml	python -m py_compile 或 mypy .

步骤 2：解析并分组错误

1. 运行构建命令并捕获 stderr
2. 按文件路径对错误进行分组
3. 按依赖顺序排序（先修复导入/类型错误，再修复逻辑错误）
4. 统计错误总数以跟踪进度

步骤 3：修复循环（一次处理一个错误）

对于每个错误：

1. 读取文件 — 使用读取工具查看错误上下文（错误周围的 10 行代码）
2. 诊断 — 确定根本原因（缺少导入、类型错误、语法错误）
3. 最小化修复 — 使用编辑工具进行最小的更改以解决错误
4. 重新运行构建 — 验证错误已消失且未引入新错误
5. 移至下一个 — 继续处理剩余的错误

步骤 4：防护措施

在以下情况下停止并询问用户：

• 一个修复引入的错误比它解决的更多
• 同一错误在 3 次尝试后仍然存在（可能是更深层次的问题）
• 修复需要架构更改（不仅仅是构建修复）
• 构建错误源于缺少依赖项（需要 npm install、cargo add 等）

步骤 5：总结

显示结果：

• 已修复的错误（包含文件路径）
• 剩余的错误（如果有）
• 引入的新错误（应为零）
• 针对未解决问题的建议后续步骤

恢复策略

情况	操作
缺少模块/导入	检查包是否已安装；建议安装命令
类型不匹配	读取两种类型定义；修复更窄的类型
循环依赖	使用导入图识别循环；建议提取
版本冲突	检查 package.json / Cargo.toml 中的版本约束
构建工具配置错误	读取配置文件；与有效的默认配置进行比较

为了安全起见，一次只修复一个错误。优先使用最小的改动，而不是重构。