SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ln-511-code-quality-checker

ln-511-code-quality-checker

测试与质量

查看项目

更新于 10-15 14:34

技能介绍

用途

ln-511-code-quality-checker 是一个代码质量检查技能，类型为 L3 Worker，分类为 5XX Quality。它对状态为 Done 的实现任务进行量化分析，输出 Code Quality Score（代码质量分数），并给出结构化的问题列表。它用于在实现任务完成后、技术债清理和代理内联审查之前进行质量评分。该技能不会编辑 Linear 或看板，不创建任务、不更改状态，由调用方决定后续动作。

主要能力

代码度量

技能计算以下指标并按阈值扣分：

  • 圈复杂度（Cyclomatic Complexity）：≤10 为 OK，11-20 警告，>20 失败；每个函数警告扣 -5、失败扣 -10。
  • 函数大小：≤50 行为 OK，>50 行警告；每个函数扣 -3。
  • 文件大小：≤500 行为 OK，>500 行警告；每个文件扣 -5。
  • 嵌套深度：≤3 为 OK，>3 警告；每处扣 -3。
  • 参数数量：≤4 为 OK，>4 警告；每个函数扣 -2。

Code Quality Score

公式：Code Quality Score = 100 - metric_penalties - issue_penalties。 问题按严重程度扣分：high 扣 -20（如安全漏洞、O(n²)+ 算法、N+1 查询）；medium 扣 -10（如 DRY 违规、次优方案、缺少配置）；low 扣 -3（如命名规范、轻微代码异味）。 分数解读：90-100 为 Excellent，判定 PASS；70-89 为 Acceptable，判定 CONCERNS；<70 为 Below threshold，判定 ISSUES_FOUND。

问题前缀与分类

技能使用带前缀的问题分类，包括：

  • SEC-：安全（认证、校验、密钥），默认 high。
  • SEC-DESTR-：破坏性操作（守卫类别：DB、FS、MIG、ENV、FORCE），high/medium。
  • PERF-：性能（算法、配置、瓶颈），medium/high，需要 MCP Ref。
  • MNT-：可维护性（DRY、SOLID、复杂度、死代码），medium。
  • ARCH-：架构（分层、边界、模式、契约），medium。
  • BP-：最佳实践（实现与推荐做法不符），medium，需要 MCP Ref。
  • OPT-：最优性（存在更好的方案），medium，需要 MCP Ref。

子类别包括：OPT-OSS-（存在开源替代，medium，>200 LOC 时为 high）；ARCH-LB-（层边界，high）、ARCH-TX-（事务边界，high，认证/支付场景为 CRITICAL）、ARCH-DTO-（缺少 DTO/实体泄漏，medium，认证/支付为 high）、ARCH-DI-（依赖注入，medium）、ARCH-CEH-（集中式错误处理，medium）、ARCH-SES-（会话归属，medium）、ARCH-AI-SEB（副作用广度，medium）、ARCH-AI-AH（架构诚实性，medium）、ARCH-AI-FO（扁平编排，medium）、ARCH-EVENT-（事件通道一致性，high/medium）；PERF-ALG-、PERF-CFG-、PERF-PTN-、PERF-DB-；MNT-DC-（死代码）、MNT-DRY-（DRY 违规）、MNT-GOD-（上帝类）、MNT-SIG-（方法签名质量）、MNT-ERR-（错误契约不一致）。

MCP Ref 验证

对代码变更执行三级验证：Level 1 最优性（OPT-）、Level 2 最佳实践（BP-）、Level 3 性能（PERF-）。触发条件包括：新增依赖、使用新模式/库、API/数据库变更、关键路径中的循环/递归、新增 ORM 查询。使用 --skip-mcp-ref 标志可跳过整个 MCP Ref 步骤（不做 OPT-、BP-、PERF- 检查），成本从约 5000 降至约 800 tokens，同时保留度量与静态分析覆盖。

静态问题分析

分析 SEC-、SEC-DESTR-、MNT-、ARCH- 等静态问题。包含跨 Story 热点扫描：MNT-DRY- 跨 Story 扫描（若某模式出现在 5+ 文件中且结构相似度 >80%，标记 MNT-DRY-CROSS，medium，-10 分）；MNT-DC- 跨 Story 未使用导出扫描（导出但从未被导入，标记 MNT-DC-CROSS，medium，-10 分）；OPT-OSS- 交叉引用 ln-645 报告（仅读本地文件，即使 --skip-mcp-ref 也运行）。

两层检测

所有基于阈值的发现都需要 Layer 2 上下文分析。Layer 1 发现若无 Layer 2 则不是有效发现。报告任何度量违规前需判断：该违规是有意为之还是设计上合理？度量表中列出了例外情况（如枚举/switch 分发、状态机、解析器语法降级为 LOW；编排函数、配置/模式/迁移文件、生成代码等例外）。

使用方式

输入：storyId（必需，来源为 args、git 分支、看板或用户）。状态过滤：In Progress、To Review。

工作流（简要）：

  1. 加载 references/input_resolution_pattern.md，解析 storyId（Story Resolution Chain，状态过滤 [In Progress, To Review]）。
  2. 通过 Linear 加载 Story（完整）和 Done 实现任务（完整描述），跳过带 "tests" 标签的任务。
  3. 收集变更文件 changed_files[]：加载 references/git_scope_detection.md；若由 ln-510 调用则使用协调器上下文中的 changed_files[]，若独立调用则运行指南中的完整算法。
  4. 两层检测（强制）：加载 references/two_layer_detection.md。
  5. 计算代码度量。
  6. MCP Ref 验证（代码变更时强制，--skip-mcp-ref 时跳过）。
  7. 静态问题分析（分配前缀）：加载 references/clean_code_checklist.md、references/destructive_operation_safety.md。大文件先用 outline(file_path) 再定向读取。
  8. 计算 Code Quality Score。
  9. 输出：加载 references/output_schema.md，按 schema 格式化输出，并在 Linear 添加评论。

工具策略：遵循宿主 AGENTS.md 的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md。项目已索引时优先使用 hex-graph 作为克隆、架构和语义质量证据的主要路径，仅在 graph 不可用或不支持时回退到 Grep/Read。

运行时摘要：加载 references/quality_summary_contract.md、references/quality_worker_runtime_contract.md。运行时 profile：family 为 quality-worker，worker 为 ln-511，summary kind 为 quality-worker，协调器使用的 payload 字段为 worker、status、verdict、score、issues、warnings。调用规则：独立调用时省略 runId 和 summaryArtifactPath；托管调用时同时传入 runId 和确切的 summaryArtifactPath；始终在最终结果前写入已验证的摘要。

适用场景

  • Story 中所有实现任务状态为 Done 时。
  • 技术债清理之前。
  • 代理内联审查之前。

限制

  • 不编辑 Linear 或看板，不创建任务、不更改状态。
  • 判定合规前需先阅读 Story/Tasks 中提到的指南。
  • 任何架构变更必须通过 ref_search_documentation 验证后才能判定。
  • 审查库使用时需用 query-docs 验证正确模式。
  • 评论中保留语言（EN/RU）。
  • 所有基于阈值的发现都需要两层检测，Layer 1 发现若无 Layer 2 上下文分析则无效。
  • 版本 5.1.0，最后更新 2026-03-15。

参考文件

  • Git 范围检测：references/git_scope_detection.md
  • 代码度量：references/code_metrics.md
  • 指南：docs/guides/
  • 上下文模板：references/templates/task_template_implementation.md
  • 整洁代码清单：references/clean_code_checklist.md
  • 研究工具回退：references/research_tool_fallback.md