ln-511-code-quality-checker

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

代码质量检查器

类型： L3 Worker 类别： 5XX 质量

基于指标、MCP Ref 验证和问题扣分，对已完成的实现任务进行分析，并给出量化的代码质量评分。

输入

输入	必填	来源	描述
storyId	是	args、git branch、kanban、user	要处理的 Story

解析： Story 解析链。 状态筛选： In Progress、To Review

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

目的与范围

• 加载 Story 和已完成的实现任务（排除测试任务）
• 使用指标和问题扣分计算代码质量评分
• MCP Ref 验证： 通过外部来源验证最优性、最佳实践和性能
• 检查 DRY/KISS/YAGNI 违规、架构边界破坏和安全问题
• 生成包含结构化问题列表的量化评定；绝不编辑 Linear 或 kanban

代码指标

指标	阈值	扣分
圈复杂度	≤10 合格，11-20 警告，>20 不合格	每个函数扣 -5（警告）、-10（不合格）
函数大小	≤50 行合格，>50 行警告	每个函数扣 -3
文件大小	≤500 行合格，>500 行警告	每个文件扣 -5
嵌套深度	≤3 合格，>3 警告	每处扣 -3
参数数量	≤4 合格，>4 警告	每个函数扣 -2

代码质量评分

公式：Code Quality Score = 100 - metric_penalties - issue_penalties

按严重程度扣分：

严重程度	扣分	示例
high	-20	安全漏洞、O(n²)+ 算法、N+1 查询
medium	-10	DRY 违规、非最优方案、缺少配置
low	-3	命名规范问题、轻微代码异味

评分说明：

评分	状态	评定
90-100	优秀	PASS
70-89	可接受	CONCERNS
<70	低于阈值	ISSUES_FOUND

问题前缀

前缀	类别	默认严重性	MCP 参考
SEC-	安全（身份验证、验证、机密）	高	—
SEC-DESTR-	破坏性操作（防护：DB、FS、MIG、ENV、FORCE）	高/中	—
PERF-	性能（算法、配置、瓶颈）	中/高	✓ 必需
MNT-	可维护性（DRY、SOLID、复杂度、死代码）	中	—
ARCH-	架构（分层、边界、模式、契约）	中	—
BP-	最佳实践（实现方式与推荐做法不同）	中	✓ 必需
OPT-	最优性（存在更适合此目标的方法）	中	✓ 必需

OPT- 子类别：

前缀	类别	严重性
OPT-OSS-	有可用的开源替代方案	中（超过 200 行代码时为高）

ARCH- 子类别：

前缀	类别	严重性
ARCH-LB-	分层边界：I/O 位于基础设施层之外，HTTP 位于领域层	高
ARCH-TX-	事务边界：在 3 层以上调用 commit()，UoW 所有权混杂	高（涉及身份验证/支付时为严重）
ARCH-DTO-	缺少 DTO（4 个以上参数但没有 DTO），实体泄漏（API 响应中包含 ORM 实体）	中（涉及身份验证/支付时为高）
ARCH-DI-	依赖注入：依赖项无法替换以供测试（直接实例化、没有注入机制）。例外：参数/闭包足以满足需求的小型脚本/CLI → 跳过	中
ARCH-CEH-	集中式错误处理：错误被静默吞掉、堆栈跟踪泄漏到生产环境、没有一致的错误日志记录。例外：50 行脚本 → 降级为低	中（完全没有处理程序时为高）
ARCH-SES-	会话所有权：同一模块中同时存在 DI 会话和本地会话	中
ARCH-AI-SEB	副作用范围：一个 叶子 函数中包含 3 种以上副作用类别。冲突解决： 编排器/协调器函数（导入 3 个以上服务并按顺序委派）预期会包含多个类别 — 不要标记 SEB	中
ARCH-AI-AH	架构诚实性：名称暗示读取、却带有写入副作用的函数	中
ARCH-AI-FO	扁平编排：叶子 服务导入 3 个以上其他服务。编排器导入是预期行为 — 不要标记	中
ARCH-EVENT-	事件通道一致性：发布者/订阅者名称不匹配（MISMATCH），没有对应项的孤立通道（ORPHAN）	高（不匹配）、中（孤立）

PERF- 子类别：

前缀	类别	严重性
PERF-ALG-	算法复杂度（Big O）	O(n²)+ 时为高
PERF-CFG-	包/库配置	中
PERF-PTN-	架构模式性能	高
PERF-DB-	数据库查询、索引	高

MNT- 子类别：

前缀	类别	严重性
MNT-DC-	死代码：已被替换的实现、未使用的导出/重新导出、向后兼容包装器、不受支持的别名	中（公共 API 中为高）
MNT-DRY-	DRY 违规：跨文件的重复逻辑	中
MNT-GOD-	上帝类：方法超过 15 个或超过 500 行的类（不只是文件大小）	中（超过 1000 行时为高）
MNT-SIG-	方法签名质量：布尔标志参数、返回类型不明确、命名不一致、可选参数超过 5 个	低
MNT-ERR-	错误契约不一致：同一服务中混用 raise 和 return None	中

适用场景

• Story 状态为 Done 的所有实现任务
• 技术债清理和 Agent 行内审查之前

工作流（简要）

必须阅读： 加载 references/input_resolution_pattern.md

1. 解析 storyId： 按照指南运行 Story Resolution Chain（状态筛选：[In Progress, To Review]）。

2. 通过 Linear 加载 Story（完整内容）和已完成的实现任务（完整描述）；跳过带有标签 "tests" 的任务。

3. 收集变更文件（changed_files[]）： 必须读取： 加载 references/git_scope_detection.md

   • 如果由 ln-510 调用：使用协调器上下文中的 changed_files[] → 继续执行指南中的 Enrich 步骤
   • 如果独立调用：运行指南中的完整算法

4. 双层检测（必须）： 必须读取： 加载 references/two_layer_detection.md 所有基于阈值的发现都需要进行第二层上下文分析。第一层发现若没有第二层分析，则不是有效发现。报告任何指标违规前，先问：“此违规是否是有意为之，或有设计上的合理依据？”请参阅下方指标中的 Exception 列。

5. 计算代码指标：

   • 每个函数的圈复杂度（目标 ≤10；例外：枚举/开关分派、状态机、解析器语法 → 降级为 LOW）
   • 函数大小（目标 ≤50 行；例外：按顺序委派任务的编排函数）
   • 文件大小（目标 ≤500 行；例外：配置/架构/迁移文件、生成的代码）
   • 嵌套深度（目标 ≤3）
   • 参数数量（目标 ≤4；例外：构建器/选项模式）

6. MCP 引用验证（代码变更时必须执行——如果传入 --skip-mcp-ref 标志则跳过）： 必须读取： 加载 references/research_tool_fallback.md

   快速通道模式： 使用 --skip-mcp-ref 调用时，跳过整个步骤（不进行 OPT-、BP-、PERF- 检查）。直接进入第 6 步（静态分析）。这样可将成本从约 5000 个 token 降至约 800 个 token，同时保留指标和静态分析覆盖。

   第 1 级——最优性（OPT-）：

   • 从任务中提取目标（例如，“用户身份验证”“缓存”“API 速率限制”）
   • 研究替代方案：ref_search_documentation("{goal} approaches comparison {tech_stack} 2026")
   • 结合项目上下文，将选定方案与替代方案进行比较
   • 将次优选择标记为 OPT- 问题

   第 2 级——最佳实践（BP-）：

   • 研究：ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")
   • 对于库：query-docs(library_id, "best practices implementation patterns")
   • 将偏离推荐模式的情况标记为 BP- 问题

   第 3 级——性能（PERF-）：

   • PERF-ALG： 分析算法复杂度（检测 O(n²)+，通过 MCP Ref 研究最优方案）
   • PERF-CFG： 通过 query-docs 检查库配置（连接池、批量大小、超时）
   • PERF-PTN： 研究模式缺陷：ref_search_documentation("{pattern} performance bottlenecks")
   • PERF-DB： 通过 query-docs(orm_library_id, "query optimization") 检查 N+1 问题和缺失索引

   MCP Ref 验证触发条件：

   • 添加新依赖（package.json/requirements.txt 已更改）
   • 使用新模式/库
   • API/数据库变更
   • 关键路径中存在循环/递归
   • 添加 ORM 查询

7. 分析代码中的静态问题（分配前缀）： 必须阅读： 加载 references/clean_code_checklist.md、references/destructive_operation_safety.md

   • 对于大型代码文件，在有针对性地读取之前使用 outline(file_path)。
   • SEC-：硬编码凭据、未验证的输入、SQL 注入、竞态条件
   • SEC-DESTR-：未设防的破坏性操作——使用 destructive_operation_safety.md 中的代码级防护表（已在上方加载）。检查全部 5 类防护（DB、FS、MIG、ENV、FORCE）。
   • MNT-：违反 DRY 原则（MNT-DRY-：重复逻辑）、死代码（MNT-DC-：参照清单）、复杂条件、命名不佳
   • MNT-DRY- 跨故事热点扫描： 在所有 src/ 文件中使用 Grep 搜索常见模式特征（错误处理程序：catch.*Error|handleError，验证器：validate|isValid，配置访问：getSettings|getConfig）（计数模式）。如果任一模式出现在 5 个或更多文件中，抽查 3 个文件（每个读取 50 行）并检查结构相似度。如果相似度 >80% → MNT-DRY-CROSS（中等，-10 分）：Pattern X duplicated in N files — extract to shared module.
   • MNT-DRY- 优先方案（hex-graph）： 如果已建立 hex-graph 索引，使用 audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3)。每个包含 2 个或更多成员且成员位于不同文件的克隆组均为 MNT-DRY-CROSS。仅当有界预览不足时才提高限制。根据返回的热点和克隆上下文确定优先级。如果 hex-graph 不可用，则回退到上方的 Grep 模式扫描。
   • MNT-DC- 跨故事未使用导出扫描： 对 Story 修改的每个文件，统计 export 声明数量。然后在所有 src/ 文件中使用 Grep 搜索对这些导出的导入引用。导入引用数为 0 的导出 → MNT-DC-CROSS（中等，-10 分）：{export} in {file} exported but never imported — remove or mark internal.
   • OPT-OSS- 跨引用 ln-645（静态、安全快捷通道）： 如果存在 docs/project/.audit/ln-640/*/645-open-source-replacer*.md（跨日期 glob 搜索，取最新文件），检查是否有任何高置信度替代项匹配当前 Story 中修改的文件。如果找到匹配项 → 创建 OPT-OSS-{N} 问题，并从 ln-645 报告中填写模块路径、目标、推荐包、置信度、星标数和许可证。严重程度：超过 200 LOC 为高，否则为中等。此项仅读取本地文件——不调用 MCP——即使使用 --skip-mcp-ref 也会运行。
   • ARCH-：分层违规、循环依赖、不符合指南
   • ARCH-LB-：层边界违规（在基础设施层之外调用 HTTP/DB/FS）
   • ARCH-TX-：事务边界违规（跨多个层调用 commit()）
   • ARCH-DTO-：缺少 DTO（4 个或更多重复参数）、实体泄漏（从 API 返回 ORM 实体）
   • ARCH-DI-：业务逻辑中直接实例化（没有 DI 容器或模式混用）
   • ARCH-CEH-：缺少集中式错误处理，或绕过集中式错误处理
   • ARCH-SES-：会话所有权冲突（同一模块中同时存在 DI 会话和本地会话）
   • ARCH-AI-SEB：副作用范围过广（单个 叶 函数中涉及 3 个或更多类别；编排函数除外——参见上方表格中的冲突解决）
   • ARCH-AI-AH：架构诚实性（名称暗示只读的函数暗中执行写入）
   • ARCH-AI-FO：扁平编排（叶服务导入 3 个或更多服务；编排函数的导入除外）
   • ARCH-EVENT-：事件通道不匹配——在 changed_files[] 中使用 Grep 搜索 NOTIFY|pg_notify|\.publish\(|\.emit\(（发布者）以及 LISTEN|\.subscribe\(|\.on\(（订阅者）。交叉引用通道名称字符串。
   • MNT-GOD-：上帝类（每个类超过 15 个方法或超过 500 行）
   • MNT-SIG-：方法签名质量（布尔标志、返回值不明确）
   • MNT-ERR-：错误契约不一致（同一服务中混用抛出/返回模式）

8. 计算代码质量分数：

   • 从 100 分开始
   • 减去指标扣分（参见代码指标表）
   • 减去问题扣分（参见问题扣分表） 9）输出带评分的评审结论和结构化问题。 必须阅读： 加载 references/output_schema.md 按照架构格式输出。添加带有评审结果的 Linear 评论。

关键规则

• 评判合规性前，先阅读 Story/Tasks 中提及的指南。
• MCP Ref 验证： 对于任何架构变更，评判前必须通过 ref_search_documentation 进行验证。
• Context7 库验证： 审查库的用法时，使用 query-docs 验证正确的模式。
• 保留注释中的语言（EN/RU）。
• 不要创建任务或更改状态；由调用方决定后续操作。

运行时摘要产物

必须阅读： 加载 references/quality_summary_contract.md、references/quality_worker_runtime_contract.md

运行时配置：

• family：quality-worker
• worker：ln-511
• summary kind：quality-worker
• 协调器使用的载荷字段：worker、status、verdict、score、issues、warnings

调用规则：

• 独立运行：省略 runId 和 summaryArtifactPath
• 托管运行：传入 runId 和准确的 summaryArtifactPath
• 终止前始终写入通过验证的摘要

完成定义

• 已加载 Story 和 Done 实现任务（不包括测试任务）
• 已计算代码指标（圈复杂度、函数/文件大小）
• 已完成 MCP Ref 验证（OPT-、BP-、PERF- 类别）
• 已检查 ARCH- 子类别（LB、TX、DTO、DI、CEH、SES、EVENT）；已检查 MNT- 子类别（DC、DRY、GOD、SIG、ERR）
• 已标识带前缀和严重级别的问题，来源于 MCP Ref/Context7
• 已计算代码质量评分
• 已按照 references/output_schema.md 格式化输出
• 已发布包含评审结果的跟踪器评论

参考文件

• 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

---

版本： 5.1.0 最后更新： 2026-03-15