complexity

复杂度技能

必须执行此工作流。不要只描述它。

分析代码复杂度，找出重构目标。

执行步骤

给定 /complexity [path]：

步骤 1：确定目标

如果提供了路径： 直接使用该路径。

如果未提供路径： 使用当前目录或最近的更改：

git diff --name-only HEAD~5 2>/dev/null | grep -E '\.(py|go)$' | head -10

步骤 2：检测语言

# Check for Python files
ls *.py **/*.py 2>/dev/null | head -1 && echo "Python detected"

# Check for Go files
ls *.go **/*.go 2>/dev/null | head -1 && echo "Go detected"

步骤 3：运行复杂度分析

对于 Python（使用 radon）：

# Check if radon is installed
which radon || pip install radon

# Run cyclomatic complexity
radon cc <path> -a -s

# Run maintainability index
radon mi <path> -s

对于 Go（使用 gocyclo）：

# Check if gocyclo is installed
which gocyclo || go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

# Run complexity analysis
gocyclo -over 10 <path>

步骤 4：解读结果

圈复杂度等级：

等级	CC 分数	含义
A	1-5	风险低，代码简单
B	6-10	风险适中，可控
C	11-20	风险高，较复杂
D	21-30	风险很高
F	31+	无法测试，应立即重构

步骤 5：确定重构目标

列出需要关注的函数/方法：

• CC > 10：应该重构
• CC > 20：必须重构
• CC > 30：情况危急，应立即处理

步骤 6：撰写复杂度报告

写入： .agents/complexity/YYYY-MM-DD-<target>.md

# Complexity Report: <Target>

**Date:** YYYY-MM-DD
**Language:** <Python/Go>
**Files Analyzed:** <count>

## Summary
- Average CC: <score>
- Highest CC: <score> in <function>
- Functions over threshold: <count>

## Refactor Targets

### Critical (CC > 20)
| Function | File | CC | Recommendation |
|----------|------|-----|----------------|
| <name> | <file:line> | <score> | <how to simplify> |

### High (CC 11-20)
| Function | File | CC | Recommendation |
|----------|------|-----|----------------|
| <name> | <file:line> | <score> | <how to simplify> |

## Refactoring Recommendations

1. **<Function>**: <specific suggestion>
   - Extract: <what to extract>
   - Simplify: <how to simplify>

## Next Steps
- [ ] Address critical complexity first
- [ ] Create issues for high complexity
- [ ] Consider refactoring sprint

步骤 7：向用户汇报

告知用户：

1. 总体复杂度摘要
2. 超出阈值的函数数量
3. 排名前 3 的重构目标
4. 完整报告的位置
5. 运行 /refactor <function> 处理复杂度严重的目标

关键规则

• 使用正确的工具 —— Python 使用 radon，Go 使用 gocyclo
• 关注高 CC —— 优先处理 10 及以上
• 提供具体的修复方法 —— 不要只说“重构它”
• 撰写报告 —— 始终生成报告文件

快速参考

降低高复杂度：

• 提取辅助函数
• 用多态替代条件判断
• 使用提前返回
• 拆分过长的函数
• 简化嵌套循环

示例

分析 Python 项目

用户输入： /complexity src/

执行过程：

1. Agent 检测 src/ 目录中的 Python 文件
2. Agent 检查是否安装了 radon，若未安装则进行安装
3. Agent 运行 radon cc src/ -a -s 计算圈复杂度
4. Agent 运行 radon mi src/ -s 计算可维护性指数
5. Agent 找出 3 个 CC > 20 的函数，以及 7 个 CC 为 11-20 的函数
6. Agent 将详细报告写入 .agents/complexity/2026-02-13-src.md
7. Agent 建议提取 process_request() 函数中的嵌套条件判断

结果： 复杂度报告将 process_request()（CC：28）列为需要紧急重构的目标，并提供具体的提取建议。

在 Go 模块中查找重构目标

用户输入： /complexity

执行过程：

1. Agent 使用 git diff --name-only HEAD~5 检查最近的更改
2. Agent 检测 Go 文件，并确认已安装 gocyclo
3. Agent 在项目中运行 gocyclo -over 10 ./...
4. Agent 找到复杂度为 34 的 HandleWebhook() 函数
5. Agent 撰写报告，建议提取验证逻辑
6. Agent 汇报排名前 3 的目标：HandleWebhook（34）、ProcessBatch（22）、ValidateInput（15）

结果： 找到需要立即重构的关键函数，并提供可执行的提取方案。

另请参阅

• refactor — 针对复杂度目标进行安全且经过验证的重构

故障排除

问题	原因	解决方案
未安装工具（radon/gocyclo）	缺少依赖	Agent 自动安装：Python 使用 pip install radon，Go 使用 go install github.com/fzipp/gocyclo/cmd/gocyclo@latest。请在 $PATH 中确认安装路径。
未发现复杂度问题	阈值过高，或代码本身确实简单	降低阈值：尝试 gocyclo -over 5，或检查路径是否包含实际实现文件而非测试文件。
报告列出了函数，但没有给出建议	分析过于笼统，缺少代码库上下文	阅读 CC 较高的函数以了解其结构，然后根据实际代码模式提供具体的重构建议。
混合语言项目	目标路径中包含多种语言	按语言分别运行分析：先运行 /complexity src/python/，再运行 /complexity src/go/，最后手动合并报告。

参考文档

• references/complexity.feature — 可执行规范：按圈复杂度对函数排序，默认限定为近期变更，并列出重点热点（soc-qk4b）