企业官网建设流程全解析

fuck-u-code 分析技能实战指南：让 AI Agent 按七维 11 指标评分体系完成代码质量审查

【免费下载链接】fuck-u-codeLegacy-Mess Detector – assess the “legacy-mess level” of your code and output a beautiful report项目地址: https://gitcode.com/GitHub_Trending/fu/fuck-u-code

本篇围绕 fuck-u-code 仓库中的 AI Agent 技能文档 SKILL.md 展开，完整拆解这套「代码质量分析与审查」工作流：如何运行fuck-u-code analyze获取 0-100 分的量化报告、如何解读 7 大维度 11 项指标的阈值与严重程度、以及如何按固定模板产出可执行的修复建议。读完后你可以把这套技能装进 Claude Code、opencode、Cursor 等 Agent，让它在你提交代码或创建 PR 之前自动完成「分析 → 定位 → 解读 → 修复报告」全流程。

一、这个技能是什么、何时触发

suck-u-code-analysis 是仓库 skills/ 目录下为 AI Agent 设计的技能定义。其 frontmatter 中声明的触发条件如下：

• 代码变更完成、准备提交或创建 PR 之前（实现功能、修复 bug、重构之后）；
• 用户要求检查代码质量、分析技术债务、审查 code smell；
• 提及 "fuck-u-code"、"code quality"、"shit mountain"、"code review"、"static analysis" 等关键词。

该技能覆盖14 种语言：Go、JS、TS、Python、Java、C、C++、Rust、C#、Lua、PHP、Ruby、Swift、Shell。技能的工作分三步（见 skills/README.md）：

1. 运行fuck-u-code analyze获取量化指标（0-100 总分，7 维度 11 指标）；
2. 按语言专属阈值（14 种语言）解读结果；
3. 给出带精确行号引用的可执行重构建议。

二、前置条件：安装与验证

使用技能前需先全局安装 fuck-u-code：

npm install -g eff-u-code

验证安装：

fuck-u-code --version

要求 Node.js >= 18.0.0。这与 package.json 中声明的engines.node: ">=18.0.0"一致；npm 包名为eff-u-code，注册的可执行命令为fuck-u-code（bin 映射见 package.json 的bin字段）。

若要把技能本体拉取到 Agent 的技能目录，skills/README.md 提供了基于npx degit的一键方式（无需完整 clone）：

# Claude Code npx degit Done-0/fuck-u-code/skills/fuck-u-code-analysis ~/.claude/skills/fuck-u-code-analysis # opencode npx degit Done-0/fuck-u-code/skills/fuck-u-code-analysis ~/.config/opencode/skills/fuck-u-code-analysis

目标目录已存在时加--force。

三、总体工作流

技能定义的标准工作流为（原 dot 图的等价表述）：

运行 fuck-u-code analyze → 读取 JSON 输出 → 识别关键问题文件（score < 60） → 钻取每项指标明细 → 应用审查标准（Section 4）→ 撰写可执行的修复报告

工具产出一个 0-100 的总分和逐文件分数，分数越高代表质量越好。下面逐步拆解。

Step 1：运行分析

# 基础分析 fuck-u-code analyze . -f json -o /tmp/fuc-report.json # 详细模式，输出最差的 20 个文件 fuck-u-code analyze . -v -t 20 -f json -o /tmp/fuc-report.json # 排除生成文件/测试文件 fuck-u-code analyze . -e "**/*.test.ts" -e "**/generated/**" -f json -o /tmp/fuc-report.json

随后读取 JSON 输出文件获取结构化数据。这些选项在源码中均可对应到 analyze 命令实现：

并发默认值存在两处口径：CLI 帮助文本标注 8，而配置 schema 中 DEFAULT_CONFIG 的concurrency默认为 2、取值范围 1-32；当配置文件未显式指定时，CLI 帮助文案与实际生效值以 config/index.ts 的合并逻辑为准，这里以「CLI 层默认 8」作为技能文档的表述。

Step 2：识别问题区域

从 JSON 报告中提取三个层次：

• overallScore：全项目 0-100 分，按代码行数加权的平均值；
• aggregatedMetrics：每项指标在全部文件上的平均值、中位数、最小/最大值；
• files[]：逐文件结果，按分数升序排列（最差的在前）。

重点关注 score < 60 的文件（技能称之为 "shit mountain" 区间）。JSON 结构可直接在 json 输出实现 中核对：顶层字段为$schema（内嵌字段说明）、projectPath、overallScore、summary（totalFiles/analyzedFiles/skippedFiles/analysisTime）、aggregatedMetrics[]、files[]；每个文件项含path、score、metrics[]（name/category/value/normalizedScore/severity/details）与parseResult（language、totalLines、codeLines、commentLines、functionCount、classCount）。

Step 3：钻取指标明细

对每个问题文件检查metrics[]数组，每个指标含以下字段（对应 MetricResult 类型定义）：

优先处理severity >= error的指标。

Step 4：撰写修复报告

按第七节的固定输出格式撰写报告（见下文）。

四、评分体系：权重从哪来

总分是 7 个类别的加权平均。默认权重经行业研究（SonarQube、NASA、Microsoft 关于缺陷相关性的研究）校准：

权重在源码中的落点：

• 默认权重硬编码在 scoring/index.ts 的getCategoryWeight中（complexity 0.32、duplication 0.2、size 0.18、structure 0.12、error 0.08、documentation 0.05、naming 0.05），未知类别回退 0.1；
• 配置层同样在 config/schema.ts 中定义了这 7 个权重的 zod schema 与默认值，意味着你可以通过配置文件覆盖权重；
• 指标工厂 metrics/index.ts 会把 complexity 的 32% 均分给 3 个指标（各 10.67%）、size 的 18% 均分给 3 个指标（各 6%），其余 5 个指标各占其类别权重。

计分公式：calculateScore 对每个指标执行加权累加 = Σ(normalizedScore × 类别权重)，再除以总权重得到 0-100 分数；指标为空时直接返回 100。单元测试 scoring.test.ts 验证了三个关键性质：空指标返回 100、复杂度权重高于 size（同样一高一低时，复杂度高分的组合得分更高）、加权平均介于两个分数之间。

五、11 项指标详解（Metrics Reference）

每项指标采用四级阈值体系：excellent / good / acceptable / poor，阈值按语言区分（完整表见第六节及 references/thresholds.md）。以下给出通用阈值、常见反模式与修复手段。

5.1 复杂度类（合计权重 32%，3 项均分）

cyclomatic_complexity（圈复杂度 CC）

公式：CC = 1 + 决策点数量（if/for/while/case/catch/&&/||/三元）。它度量代码中独立执行路径的数量，CC 越高意味着所需测试用例越多、缺陷概率越大。

通用阈值：

常见模式与修复：

• 长 if-else 链 → 改用策略模式、查表（lookup table）或多态；
• 嵌套条件 → 提取守卫子句（guard clause），用提前返回压平结构；
• 上帝函数（CC > 20）→ 拆分为单一职责函数。

cognitive_complexity（认知复杂度）

公式：CC + nestingDepth × 2（近似值）。它度量代码的「理解难度」，与圈复杂度不同，它对嵌套结构施加更强惩罚。

通用阈值：

常见模式与修复：

• 深层嵌套（depth > 4）→ 反转条件、提取方法、使用 Optional/Result 类型；
• 线性流程中的中断（continue/break/goto）→ 重构循环，改用 filter/map 等函数式操作；
• 无记忆化的递归 → 加缓存或改写为迭代。

nesting_depth（嵌套深度）

函数内控制流的最大嵌套层级。

通用阈值：

常见模式与修复：

• 回调地狱 / 恐怖金字塔 → 使用 async/await 或 Promise 链；
• if-for-if 嵌套 → 将内层逻辑提取为具名辅助函数；
• 循环内深 switch → 使用查表或分发映射。

5.2 重复类（权重 20%）

code_duplication（代码重复）

通过分析控制流签名（if/for/while/return/赋值模式的序列）检测重复代码。

常见模式与修复：

• 只有微小差异的复制粘贴函数 → 提取为参数化工具函数；
• 相似的 CRUD 操作 → 建立泛型 repository/service 层；
• 重复的校验逻辑 → 集中到 validator 模块；
• 多文件中的样板代码 → 使用代码生成或装饰器。

5.3 尺寸类（合计权重 18%，3 项均分）

function_length（函数长度）

每函数的代码行数，平均值与最大值按 50/50 加权计入。

通用阈值：

常见模式与修复：

• 函数 > 100 行 → 识别不同职责，各自提取为独立函数；
• 函数 > 300 行 → 大概率是「上帝方法」，拆为协调者 + 工作者；
• 长 setup + action + teardown 结构 → 按阶段分别提取。

file_length（文件长度）

每文件的代码行数（不含空行与注释）。

通用阈值：

常见模式与修复：

• 文件 > 500 行 → 大概率承载多个职责，拆为聚焦模块；
• 文件 > 1000 行 → 紧急，按 feature/领域边界拆分；
• 关注点混杂（API + 业务逻辑 + 数据访问）→ 应用分层架构。

parameter_count（参数数量）

单函数最大参数个数。

通用阈值：

常见模式与修复：

• 4 个及以上相关参数 → 归组为类型化的 options/config 对象；
• 6 个及以上参数 → 使用 builder 模式或参数对象解构；
• 布尔标志参数 → 拆分为独立的具名函数或使用枚举。

5.4 结构类（权重 12%）

structure_analysis（结构分析）

复合得分 = 嵌套质量（60%）+ 文件组织（25%）+ 导入耦合（15%）。

检测对象：深嵌套（>5 为 critical、>3 为 warning）、超大文件（>1000 行）、单文件函数过多（>50）、导入过多（>20）、循环依赖。

常见模式与修复：

• 单文件函数过多 → 按职责归组为子模块；
• 循环依赖 → 引入接口/抽象层打破环路；
• 导入 > 20 → 模块承载过多职责，拆分；
• 50+ 函数的上帝文件 → 按领域拆解为专属模块。

5.5 错误处理类（权重 8%）

error_handling（错误处理）

易错 API 调用（I/O、网络、解析、数据库）中缺少正确错误处理的占比。

检测形态：无赋值/返回的裸调用、被忽略的错误（_ = ...）、try-catch 之外的调用。

常见模式与修复：

• 无 catch 的裸 API 调用 → 用 try-catch 或 .catch() 包裹；
• 忽略的返回值 → 显式处理错误或文档化「有意忽略」；
• 异步代码缺少错误边界 → 在 await 调用周围加 try-catch；
• catch 块中吞掉错误 → 记录日志或向上传播，绝不静默忽略。

5.6 文档类（权重 5%）

comment_ratio（注释比例）

注释行数与代码行数之比，最优区间 10-25%。

常见模式与修复：

• < 5% → 为公共 API 和复杂逻辑补充 JSDoc/docstring；

• 40% → 可能过度注释琐碎代码，删除复述代码本身的注释；

• 注释掉的死代码 → 删除，交给版本控制；
• 缺少模块级文档 → 添加说明模块用途的文件头。

5.7 命名类（权重 5%）

naming_convention（命名规范）

对语言特定命名规范的符合率。

语言特定规则：

常见模式与修复：

• 同一文件内命名风格不一致 → 全项目应用 linter/formatter；
• 缩写/单字母命名 → 重命名为描述性标识符；
• 混用多种约定 → 每类标识符选定一种约定并一致执行。

六、语言专属阈值（14 语言）

完整阈值表在 references/thresholds.md，其数值来源为 language-thresholds.ts 中逐语言标注的官方 linter 默认值（gocyclo、ESLint、Pylint、SonarQube、RuboCop、SwiftLint、Clippy 等）。四列含义：≤ Excellent 为优秀；Good/Acceptable/Poor 为逐级放宽的上限。

Go（gocyclo / gocognit / Effective Go）

JavaScript / TypeScript（ESLint complexity / max-params / max-depth）

Python（Pylint / McCabe）

Java（SonarQube Java / Checkstyle / PMD）

C（Linux Kernel Coding Style / SonarQube C）

C++（Google C++ Style Guide / LLVM / clang-tidy）

Rust（Clippy cognitive_complexity / too_many_arguments / too_many_lines）

C#（SonarQube C# / Microsoft conventions）

Lua（luacheck / SonarQube defaults）

PHP（PHP_CodeSniffer / PHPMD / SonarQube PHP）

Ruby（RuboCop Metrics 默认值）

Ruby 的阈值比大多数语言更严格——RuboCop 默认值强调短方法与低复杂度。

Swift（SwiftLint 默认值 / Apple Swift API Design Guidelines）

Swift 的文件长度阈值最紧（good ≤ 350，acceptable ≤ 600）；SwiftLint 默认的函数体长度告警线仅 40 行。

Shell（Google Shell Style Guide / ShellCheck）

Shell 脚本由于每行固有复杂度更高，尺寸阈值整体更低。

值得注意的语言差异（判断前务必先查表）：

• Ruby：全面更严（CC good ≤ 7、函数长度 good ≤ 50 行），Ruby 文化崇尚短方法；
• Swift：文件长度上限最紧（good ≤ 350、acceptable ≤ 600），SwiftLint 强制小文件；
• Python：函数 good 上限更短（≤ 50 行），Pylint 与 Python 文化偏好紧凑函数；
• C：函数 good 上限更紧（≤ 80 行），Linux 内核风格强调简短；
• Shell / Swift：预期文件更小（Shell 因每行复杂度高，Swift 因 SwiftLint）；
• PHP / Python：允许更深嵌套（good ≤ 5、acceptable ≤ 7），比 Go/JS/Java 宽松。

七、审查标准与修复规范（Review Standards）

撰写修复建议时遵循以下原则（提炼自项目的 AI 审查系统）：

优先级顺序

性能瓶颈 > 安全漏洞 > 可维护性风险 > 代码风格

建议的质量规则

1. 具体且可执行。不要写「优化代码结构」，而要写「将 45-67 行提取为calculateMetrics(data)，返回MetricResult[]」。
2. 锚定证据。每条建议必须引用分析输出中的具体指标值与位置。
3. 简洁。每条建议 ≤ 30 词，无客套、无填充。
4. 尊重语言惯例。重构建议必须使用目标语言的真实语法与惯用法。

分诊方法（Triage）

对 JSON 输出中的每个问题文件：

1. 按严重程度排序指标（critical > error > warning）；
2. 同严重程度内按权重排序（complexity 32% > duplication 20% > size 18% > ...）；
3. 对每个被标记指标，查看locations[]获取精确的函数名与行号；
4. 优先为「最高严重度 × 最高权重」的问题撰写修复方案。

修复建议模板

各指标类别的建议遵循同一模式：

复杂度问题：

函数processOrder（L 45-189）圈复杂度为 24。修复：将校验逻辑（L 48-82）提取为validateOrderInput(input): ValidationResult，将计算逻辑（L 90-150）提取为calculateOrderTotal(items, discounts): number。

重复问题：

3 个函数（getUser、getOrder、getProduct）共享相同的 fetch-and-parse 模式。修复：创建fetchResource<T>(endpoint: string): Promise<T>并在各处调用。

尺寸问题：

handleSubmit（L 120-380）有 260 行、8 个参数。修复：提取为带validate()、transform()、submit()方法的SubmitCoordinator类；传SubmitConfig对象替代 8 个参数。

结构问题：

utils.ts有 52 个函数和 24 个导入。修复：按领域拆分为utils/string.ts、utils/date.ts、utils/validation.ts。

错误处理问题：

L 67 的readFile调用没有 try-catch。修复：包裹 try-catch，返回Result<Content, ReadError>。

文档问题：

注释比例 2.1%——parseAST()（L 30-95）处理了 4 个边界情况却没有 docstring。修复：添加 JSDoc，说明输入格式、边界情况与返回类型。

命名问题：

函数fn（L 23）与calc2（L 45）违反 camelCase 约定。修复：重命名为calculateDiscount与computeTaxRate。

八、报告输出格式（固定模板）

修复报告必须使用以下 Markdown 结构，每节均为必填：

# Code Quality Review ## Summary 一句话点明最严重问题的根因，解释其影响，不复述指标数字。 ## Overall Assessment | Metric | Score | |--------|-------| | Overall | XX/100 | | Files Analyzed | N | | Critical Issues | N | ## Key Issues（按严重程度排序） 每个问题一行： - **`FunctionName`（L 起-止）**：根因描述 + 具体修复建议 ## Refactoring Plan 可执行步骤的编号列表。每步 ≤ 30 词，直接可执行。 1. [带文件、函数与行号引用的具体动作] 2. [下一步具体动作] ## Security Concerns 列出安全顾虑（含受影响代码位置 + 修复方式），或声明 "No security issues found."。

九、快速参考（Quick Reference）

命令速查

分数区间与行动

严重程度定义

十、常见误区（Common Mistakes）

技能文档最后列出了 5 个高频错误，值得逐条对照自查：

1. 只看总分。项目级 80 分可能掩盖个别文件的 20 分。始终检查逐文件明细（files[]按分数升序）。
2. 忽略权重差异。命名问题（5% 权重）的影响远小于复杂度问题（32%）。按「权重 × 严重程度」排优先级。
3. 建议含糊。「重构这个函数」不可执行。必须指明从哪些行、提取什么、命名为什么。
4. 跳过 locations[]。该数组包含精确行号与函数名，建议中必须使用。
5. 忘记语言专属阈值。Python 允许比 Go 更深的嵌套，Ruby 函数应比 Java 方法更短。判断前先查 references/thresholds.md。

十一、小结

这套技能把「代码质量审查」从主观经验变成了可复现的流水线：fuck-u-code analyze产出机器可读的 JSON（结构可对照 src/cli/output/json.ts 与 src/metrics/types.ts 验证）→ 按 0.32/0.2/0.18/0.12/0.08/0.05/0.05 的默认权重理解分数的构成（src/scoring/index.ts、src/metrics/index.ts）→ 用 14 语言阈值表定性每个指标（src/metrics/thresholds/language-thresholds.ts）→ 按固定模板输出带行号锚点的修复报告。整套流程的每个环节——CLI 选项、JSON 字段、权重常量、阈值来源——都能在仓库中找到对应实现，因此既适合人类开发者上手，也适合作为 AI Agent 的可执行技能被直接引用。

【免费下载链接】fuck-u-codeLegacy-Mess Detector – assess the “legacy-mess level” of your code and output a beautiful report项目地址: https://gitcode.com/GitHub_Trending/fu/fuck-u-code