JPlag 完全使用指南：CLI 命令详解、Java API 集成与报告文件生成机制

代码质量教育后端【免费下载链接】JPlagState-of-the-Art Source Code Plagiarism Collusion Detection. Check for plagiarism in a set of programs.项目地址https://gitcode.com/gh_mirrors/jp/JPlag点击查看免费下载本文基于 JPlag 官方文档 1.-How-to-Use-JPlag.md 编写覆盖 JPlag 的全部使用路径通过 CLI 执行抄袭检测、通过 Java API 嵌入外部项目、报告文件.jplag的生成规则以及 root directory、submissions、base code 等核心概念。读完后你能够独立完成从配置参数到查看报告的完整检测流程并可依据源码确认每个参数的真实默认值与行为边界。两种使用方式CLI 与 Java APIJPlag 提供两种等价的调用入口命令行界面CLI直接执行 JAR 文件适合课程作业批改、批量检测等一次性场景Java API以编程方式调用JPlag.run(options)适合将抄袭检测集成进外部 Java 项目例如 LMS 插件、持续集成流水线。两条路径最终都汇聚到同一个核心管道参数校验 → 解析 submissions → 逐对比较 → 匹配合并/频率加权可选→ 聚类最后将结果序列化为 zip 报告。通过 CLI 使用 JPlag基本运行命令最基本的用法是执行 JAR 文件并传入 submissions 所在目录java -jar jplag.jar path/to/the/submissions完整形态为java -jar jplag.jar -l language path/to/submissions若检测对象是 Java 语言-l参数可以省略Java 是默认语言见 CliOptions.java 中的defaultLanguage new JavaLanguage()。语言有两种指定方式使用-l参数如-l python3使用语言子命令如jplag java -h。两者同时给出时子命令优先。子命令的优势是可以携带语言特有参数——查看某个子命令的帮助页即可列出该语言支持的全部选项例如jplag java -h。从源码看这些子命令由 CliInputHandler 的buildSubcommands()动态生成它遍历LanguageLoader.getAllAvailableLanguages()把每个语言模块声明的LanguageOption注册为对应的子命令选项。语言模块本身通过 JavaServiceLoader机制从 classpath 自动发现见 LanguageLoader.java因此当前仓库languages/目录下的模块对应以下语言子命令c、cpp、csharp、emf、emf-model、go、java、javascript、kotlin、llvmir、multi、python3、rlang、rust、scala、scheme、scxml、swift、text、typescript注意legacy CLI 版本的参数略有差异本文以当前主干为准。打开报告与查看器# 打开已有报告指定 .jplag 文件即跳过文件选择直接展示 java -jar jplag.jar /path/to/report.jplag # 不带任何参数运行打开 report viewer 的文件选择界面 java -jar jplag.jar完整参数列表以下是 CLI 的全部可用选项对应java -jar jplag.jar -h的输出Parameter descriptions: [root-dirs[,root-dirs...]...] Root-directory with submissions to check for plagiarism. If mode is set to VIEW, this parameter can be used to specify a report file to open. In that case only a single file may be specified. -bc, --bc, --base-codebaseCode Path to the base code directory (common framework used in all submissions). -l, --languagelanguage Select the language of the submissions (default: java). See subcommands below. -M, --mode{RUN, VIEW, RUN_AND_VIEW, AUTO} The mode of JPlag. One of: RUN, VIEW, RUN_AND_VIEW, AUTO (default: null). If VIEW is chosen, you can optionally specify a path to an existing report. -n, --shown-comparisonsshownComparisons The maximum number of comparisons that will be shown in the generated report, if set to -1 all comparisons will be shown (default: 2500) -new, --newnewDirectories[,newDirectories...] Root-directories with submissions to check for plagiarism (same as root). --normalize Activate the normalization of tokens. Supported for languages: Java, C. -old, --oldoldDirectories[,oldDirectories...] Root-directories with prior submissions to compare against. -r, --result-fileresultFile Name of the file in which the comparison results will be stored (default: results). Missing .jplag extension will be automatically added. -t, --min-tokensminTokenMatch Tunes the comparison sensitivity by adjusting the minimum token required to be counted as a matching section. A smaller value increases the sensitivity but might lead to more false-positives. Advanced --csv-export Export pairwise similarity values as a CSV file. -d, --debug Store on-parsable files in error folder. --encodingsubmissionCharsetOverride Specifies the charset of the submissions. This disables the automatic charset detection --log-level{ERROR, WARN, INFO, DEBUG, TRACE} Set the log level for the cli. -m, --similarity-thresholdsimilarityThreshold Comparison similarity threshold [0.0-1.0]: All comparisons above this threshold will be saved (default: 0.0). --overwrite Existing result files will be overwritten. -p, --suffixessuffixes[,suffixes...] comma-separated list of all filename suffixes that are included. -P, --portport The port used for the internal report viewer (default: 1996). -s, --subdirectorysubdirectory Look in directories root-dir/*/dir for programs. -x, --exclusion-fileexclusionFileName All files named in this file will be ignored in the comparison (line-separated list). Clustering --cluster-alg, --cluster-algorithm{AGGLOMERATIVE, SPECTRAL} Specifies the clustering algorithm. Available algorithms: agglomerative, spectral (default: spectral). --cluster-metric{AVG, MIN, MAX, INTERSECTION, LONGEST_MATCH, MAXIMUM_LENGTH} The similarity metric used for clustering. Available metrics: average similarity, minimum similarity, maximal similarity, matched tokens, number of tokens in the longest match, length of the longer submission (default: average similarity). --cluster-skip Skips the cluster calculation. Subsequence Match Merging --gap-sizemaximumGapSize Maximal gap between neighboring matches to be merged (between 1 and minTokenMatch, default: 6). --match-merging Enables merging of neighboring matches to counteract obfuscation attempts. --neighbor-lengthminimumNeighborLength Minimal length of neighboring matches to be merged (between 1 and minTokenMatch, default: 2). --required-mergesminimumRequiredMerges Minimal required merges for the merging to be applied (between 1 and 50, default: 6). Frequency Analysis --analysis-strategy{COMPLETE_MATCHES, CONTAINED_MATCHES, SUBMATCHES, MATCH_WINDOWS} Specifies the strategy for frequency analysis, one of: COMPLETE_MATCHES, CONTAINED_MATCHES, SUBMATCHES, MATCH_WINDOWS (default: COMPLETE_MATCHES). --frequency Enables analysis and highlighting of rare matches. --weighting{PROPORTIONAL, LINEAR, QUADRATIC, SIGMOID} The function for frequency-based match weighting, one of: PROPORTIONAL, LINEAR, QUADRATIC, SIGMOID (default: SIGMOID). Languages: c cpp csharp emf emf-model go java javascript kotlin llvmir multi python3 rlang rust scala scheme scxml swift text typescript关键参数与默认值结合源码核实运行模式-M, --mode模式由 JPlagMode.java 定义共四种模式行为RUN只运行检测并生成results.jplagVIEW只启动 report viewer可选地传入一个已有报告文件RUN_AND_VIEW运行检测并在 viewer 中打开新生成的报告AUTO根据输入文件自动选择当前 CLI 的默认值从 CLI.java 的selectModeAutomatically()可以推断AUTO的判定逻辑无输入时直接进入 viewer 的文件选择界面恰好一个输入且以.jplag或.zip结尾时将其作为报告直接打开其余情况执行runAndView()运行后打开 viewer。结果文件-r, --result-file默认值results缺少.jplag扩展名时会自动补上见CLI#getResultFilePath()。若传入路径带.zip结尾会被替换为.jplag。目标文件已存在时CLI 会尝试生成results(1).jplag、results(2).jplag等最多 4 个备选名NAME_COLLISION_ATTEMPTS 4仍冲突则报错提示使用--overwrite。若指定了输出路径但不含扩展名例如-r /path/to/desiredFolder报告会生成为/path/to/desiredFolder.jplag。灵敏度参数-t, --min-tokens控制两个 token 序列片段要被计为匹配所需的最少 token 数。值越小越敏感但假阳性越多。从 JPlagOptions.java 看若未显式指定会回退到所选语言模块自带的minimumTokenMatch()默认值小于 1 的值会被规范化为 1。比较数量与阈值-n, --shown-comparisons报告中展示的最大比较数默认2500JPlagOptions.DEFAULT_SHOWN_COMPARISONS设为-1展示全部。-m, --similarity-threshold相似度阈值取值[0.0, 1.0]默认0.0保存全部比较。低于阈值的比较对不会进入结果对象因此也不会出现在报告中超出范围的值会被钳制到 0 或 1 并输出警告。反混淆参数组Subsequence Match Merging这组参数用于抵抗轻度混淆重排、插入干扰代码等。默认值与取值范围可从 MergingOptions.java 确认参数含义默认值范围--match-merging启用邻近匹配合并false关闭---neighbor-length可参与合并的邻近匹配最小长度21 ~ minTokenMatch--gap-size邻近匹配之间允许的最大间隙token 数61 ~ minTokenMatch--required-merges单次比较中触发合并逻辑所需的最少合并次数61 ~ 50注意--match-merging默认是关闭的需要显式开启才会执行合并JPlag.java 中options.mergingOptions().enabled()为真时才调用MatchMerging。频率分析参数组Frequency Analysis--frequency启用后JPlag 会对匹配做频率分析并高亮稀有匹配——即在全集中出现少、因而更具区分力的片段。从 FrequencyAnalysisOptions.java 可确认隐藏参数默认值最小子序列长度DEFAULT_MINIMUM_SUBSEQUENCE_LENGTH 1加权因子DEFAULT_WEIGHTING_FACTOR 0.25。加权函数--weighting的默认值是SIGMOID。聚类参数组Clustering--cluster-algorithm默认spectral可选agglomerative--cluster-metric默认AVGaverage similarity另有MIN、MAX、INTERSECTION、LONGEST_MATCH、MAXIMUM_LENGTH--cluster-skip完全跳过聚类计算。完整聚类选项含 spectral 带宽、核方差、kMeans 运行次数等定义在 ClusteringOptions.javaCLI 侧通过 JPlagOptionsBuilder.java 的getClusteringOptions()组装。通过 Java API 使用 JPlagAPI 让你把 JPlag 的检测能力嵌入任意 Java 项目。官方文档中的示例使用了createAndSaveReport(result, path)双参重载核对当前源码后ReportObjectFactory.java 中仅有createAndSaveReport(JPlagResult)单参方法且 ReadmeCodeExampleTest.java 持续校验 README 示例的正确性当前版本的标准写法如下与 README.md 保持一致Language language new JavaLanguage(); // language.getOptions() 可用于设置语言特有选项等价于上文的语言子命令参数 SetFile submissionDirectories Set.of(new File(/path/to/rootDir)); File baseCode new File(/path/to/baseCode); JPlagOptions options new JPlagOptions(language, submissionDirectories, Set.of()) .withBaseCodeSubmissionDirectory(baseCode); try { JPlagResult result JPlag.run(options); // Optional: 将结果写入 zip 报告 ReportObjectFactory reportObjectFactory new ReportObjectFactory(new File(/path/to/output)); reportObjectFactory.createAndSaveReport(result); } catch (ExitException e) { // error handling here } catch (FileNotFoundException e) { // handle IO exception here }要点说明JPlagOptions最小构造只需三参language、submissionDirectories新提交集、oldSubmissionDirectories旧提交集可为空集其余参数base code、子目录、后缀过滤、阈值等均通过withXxx()builder 方法追加。旧的按名称定位 base code 的 APIwithBaseCodeSubmissionName已标记Deprecated源码注释明确建议使用withBaseCodeSubmissionDirectory并传入完整路径。JPlag.run(options)内部管道见 JPlag.javacheckForConfigurationConsistency校验配置一致性、检查 root 目录重名→SubmissionSetBuilder解析 submissions有效 submission 少于 2 个时抛出SubmissionException→ 可选的 token 归一化 →LongestCommonSubsequenceSearch执行两两比较 → 可选的MatchMerging反混淆合并 → 可选的频率加权 →ClusteringFactory计算聚类最终返回JPlagResult。报告文件生成每次 JPlag 运行结束后会自动生成一个zip 格式的结果文件扩展名.jplag目标位置由-r标志指定未指定时默认生成为results.jplagCLI 默认值results加上自动补全的.jplag。若压缩过程出错报告将以未压缩目录的形式保留在指定位置。报告内部结构可从 ReportObjectFactory.java 的createAndSaveReport确认zip 内固定包含条目内容files/参与展示的 submissions 源文件副本comparison/由ComparisonReportWriter写入每对比较的详细匹配文件runInformation.json版本、运行时间、耗时、失败 submission 列表distribution.json相似度分布数据viewer 图表使用topComparisons.jsonTop N 比较对cluster.json聚类结果submissionMappings.json/submissionFileIndex.jsonsubmission 名称到匿名 ID 的映射与文件索引options.json本次运行的完整JPlagOptions快照README.txt查看报告的说明文字查看报告自 v6.0.0 起report viewer 与 JPlag 打包在一起并自动启动--mode控制该行为不带参数运行java -jar jplag.jar打开 viewer 的文件选择界面可将.jplag文件拖入页面java -jar jplag.jar report.jplag file跳过选择直接打开该报告常规运行检测时java -jar jplag.jar submission directory javaviewer 会自动打开新生成的报告若只想运行不打开 viewer传--mode runjava -jar jplag.jar --mode run submission directory java。从 JPlagRunner.java 的runInternalServer看viewer 实际是一个内部 HTTP 服务默认监听-P指定的端口默认1996启动后尝试调用系统默认浏览器打开http://localhost:port/无法打开时会在日志中打印地址。详细功能介绍见 7.-Report-Viewer.md。基本概念Root Directory 与 SubmissionsRoot directoryJPlag 在其中扫描 submissions 的目录Submissions包含待解析、待比较源码的提交单元必须是 root directory 的直接子项可以是单个文件也可以是目录。单文件 submissions/path/to/root-directory ├── Submission-1.java ├── ... └── Submission-n.java目录 submissionsJPlag 会递归读取 submission 目录因此每个目录内可包含多个嵌套的源文件/path/to/root-directory ├── Submission-1 │ ├── Main.java │ └── util │ └── Utils.java ├── ... └── Submission-n ├── Main.java └── util └── Utils.java如果只想扫描每个 submission 内某个特定子目录如src用-s指定/path/to/root-directory ├── Submission-1 │ ├── src │ │ ├── Main.java # Included │ │ └── util │ │ └── Utils.java # Included │ ├── lib │ │ └── Library.java # Ignored │ └── Other.java # Ignored └── ...Base CodeBase code 是一种特殊的 submission所有其他 submissions 所基于的公共模板。JPlag 会忽略那些“同时也出现在 base code 中”的匹配从而避免模板代码如题面给定的main函数产生噪声相似度。和 submission 一样base code 也必须是 root directory 中的单个文件或目录通过-bcbase-code-name指定。示例学生只需实现模板中的run方法main函数不允许修改、因此所有学生的代码里都完全相同// BaseCode/Solution.java public class Solution { // DO NOT MODIFY public static void main(String[] args) { Solution solution new Solution(); solution.run(); } public void run() { // TODO: Implement your solution here. } }/path/to/root-directory ├── BaseCode │ └── Solution.java ├── Submission-1 │ └── Solution.java ├── ... └── Submission-n └── Solution.java为避免检测到main函数以及模板其他部分的“相似”用-bcBaseCode告知 JPlag 忽略与 base code 匹配的片段。上例中的base-code-name就是BaseCode。多个 Root Directories新旧提交对比可以传入多个 root directoriesJPlag 会跨所有目录比较 submissionsJPlag 区分old与newroot directoriesnew 目录中的 submissions 之间互相比较并与来自其他目录的 submissions 比较old 目录中的 submissions只与 new 目录中的 submissions 比较old 之间不比较至少需要一个newroot directory 才能运行。典型用途是把今年的提交与往年的提交进行比对/path/to/root-new └── ... /path/to/root-old1 └── ... /path/to/root-old2 └── ...对应命令行即-new /path/to/root-new -old /path/to/root-old1,/path/to/root-old2-old/-new支持逗号分隔的多个目录。注意JPlag.run会检查各 root 目录名称不得重复重名会抛出RootDirectoryException。结构关系总览小结JPlag 的使用可以归纳为一条主线准备好 root directory 下的 submissions单文件或递归目录必要时用-bc排除模板代码、用-old引入历史提交然后以java -jar jplag.jar -l language root-dir运行结果自动打包为.jplagzip 文件并可在内置 report viewer 中交互式查看。所有 CLI 参数最终都映射到 JPlagOptions 这一个不可变的配置对象Java API 用户可以直接构造同一对象因此 CLI 文档中的每一个参数都能在 API 中找到等价配置项——这是两种使用方式行为一致的保证。赞分享代码质量教育后端【免费下载链接】JPlagState-of-the-Art Source Code Plagiarism Collusion Detection. Check for plagiarism in a set of programs.项目地址https://gitcode.com/gh_mirrors/jp/JPlag点击查看免费下载相关推荐Infer 报告生成与处理完全指南infer report 命令详解Infer 报告生成与处理完全指南infer report 命令详解 infer report 是 Infer https://link.gitcode.co静态分析代码质量开发工具JPlag 源码查重工具实战指南安装部署、CLI 参数全解与 Java API 集成JPlag 源码查重工具实战指南安装部署、CLI 参数全解与 Java API 集成 本文基于 JPlag 仓库的 README https://link.g代码质量教育后端Vendure CLI schema 命令详解从 Admin/Shop GraphQL API 生成可复用的 Schema 文件Vendure CLI schema 命令详解从 Admin/Shop GraphQL API 生成可复用的 Schema 文件 本篇技术指南围绕 Vendu后端电商插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考