常见问题 (FAQs)
【免费下载链接】infrastructure本仓库用于托管CANN社区基础设施团队的公开信息，包括不限于：会议日程，成员信息，服务文档和配置等信息项目地址: https://gitcode.com/cann/infrastructure
本文档收集了 OSS Information Extraction Tool 使用过程中的常见问题、故障排查步骤及解决方案。
目录
- 故障排查流程
- 安装与环境问题
- License相关问题
- Copyright相关问题
- 输出相关问题
- 其他问题
故障排查流程
遇到问题时，建议按以下步骤排查：
1. 启用调试日志 LOG_LEVEL=DEBUG cret -t ... │ ▼ 2. 查看日志输出 - 是否有 ERROR 级别错误？ - 是否有 WARN 级别警告？ │ ▼ 3. 根据错误类型定位问题 - 安装错误 → 查看[安装与环境问题](#安装与环境问题) - License识别问题 → 查看[License相关问题](#license相关问题) - Copyright提取问题 → 查看[Copyright相关问题](#copyright相关问题) │ ▼ 4. 问题仍未解决？ - 查看 [DESIGN.md](https://link.gitcode.com/i/63d1f6cd4be95b9b19523e20d55f8c5b) 了解设计逻辑 - 向项目提交 Issue安装与环境问题
Q: 工具支持哪些操作系统？
A:
- 推荐：Ubuntu 22.04，Python 3.10/3.11
- Windows：可能出现临时目录路径过长导致删除失败的问题
Windows 用户解决方案：
- 修改系统注册表启用长路径支持
- 或手动删除临时目录（位于目标文件同目录下，名称类似
xxx-extract）
Q: 安装时提示 scancode 相关错误怎么办？
A:工具依赖 ScanCode Toolkit，请确保环境满足其运行要求。
排查步骤：
- 检查 scancode 是否正确安装：
scancode --version - 如未安装或报错，请参考 ScanCode 官方文档
Q: 如何安装工具？
A:
cd OSSinfo_extraction pip install -e .安装完成后会生成cret命令。
License相关问题
Q: 为什么 license 没有被识别？
A:请按以下顺序排查：
| 检查项 | 要求 | 说明 |
|---|---|---|
| 文件位置 | 根目录或 LICENSES 目录 | 不支持其他目录 |
| 文件命名 | 符合规范 | 如 LICENSE, LICENSE.MIT, COPYING |
| 文件格式 | 文本格式 | 不支持二进制文件 |
| 文件内容 | 完整许可证文本 | 片段声明可能被过滤 |
调试方法：
LOG_LEVEL=DEBUG cret -t package.zip -n "Software" -v "1.0.0"Q: 为什么 LGPL-3.0 许可证识别失败？
A:ScanCode Toolkit 不支持LGPL-3.0-only和LGPL-3.0-or-later，只支持LGPL-3.0。
解决方案：
cret -t package.zip -n "Software" -v "1.0.0" -l "LGPL-3.0"Q: 使用-l参数时提示许可证未找到？
A:
- 确认使用 SPDX 标识符：必须使用标准短名称，如
MIT、Apache-2.0、GPL-3.0-only - 查看 ScanCode 支持的许可证列表：
scancode --list-licenses - 使用
-l和-p同时指定：跳过自动检测
Q: 指定了 license 名称和路径，但提示"请人工核对"？
A:这表示工具检测到名称与文件内容可能不匹配。请检查：
- 指定的 license 名称是否正确
- 指定的文件路径是否正确
- 文件内容是否确实包含该许可证
Q: 如何处理工具不支持的许可证？
A:使用-l和-p参数同时指定，跳过自动检测：
cret -t package.zip -n "Software" -v "1.0.0" -l "Custom-License" -p "LICENSE"Q: 项目有多个 LICENSE 文件，工具如何处理？
A:工具会按优先级处理：
- 识别根目录下的所有 license 文件
- 识别 LICENSES 目录下的所有文件
- 按路径优先级选择（根目录 > LICENSES 目录 > 其他目录）
- 在 Readme.opensource 中分别列出每个 license
Q: 什么时候应该同时指定-l和-p参数？
A:
- ✅ 明确知道许可证名称和文件位置时
- ✅ 需要最准确的结果时
- ✅ 自动检测出现问题需要覆盖时
Copyright相关问题
Q: 为什么 copyright 信息为空？
A:可能原因及解决方案：
| 原因 | 解决方案 |
|---|---|
| 源代码中没有 copyright 声明 | 检查源文件，补充版权声明 |
| 声明格式不标准 | 使用标准格式：Copyright (c) 年份 作者 |
| 只存在于文档文件中 | 文档中的 copyright 默认被过滤 |
| 不包含 "copyright" 关键字 | 工具只保留包含关键字的信息 |
调试方法：
LOG_LEVEL=DEBUG cret -t package.zip -n "Software" -v "1.0.0" # 查看 result.json 中的 copyright 扫描结果Q: copyright 信息重复怎么办？
A:工具已内置去重机制。如仍有重复：
- 检查是否有多个文件包含相同的 copyright 声明
- 使用
LOG_LEVEL=DEBUG查看原始扫描结果 - 人工核对并删除
Readme.opensource中的重复项
输出相关问题
Q: 输出文件有哪些？
A:| 文件 | 说明 | |------|------| |Readme.opensource| 最终许可证声明文件 | |{target}_copyright| copyright 信息文本 | |{target}_license| license 信息文本 | |result.json| ScanCode 原始扫描结果（调试用） |
Q: Readme.opensource 格式是什么？
A:
Software: 软件名称 版本号 Copyright Notice(s): copyright信息1 copyright信息2 ... License: MIT Full License Text: MIT License内容...Q: 执行过程中断，临时文件在哪里？
A:
- 解压目录：目标文件同目录下，名称类似
xxx-extract - 扫描结果：
result.json - 出错时临时文件会保留以便调试
其他问题
Q: 工具支持哪些压缩格式？
A:.zip,.tar,.tar.gz,.tgz,.tar.bz2,.tbz2
Q: 可以直接扫描目录吗？
A:可以，直接指定目录路径：
cret -t ./source_dir -n "Software" -v "1.0.0"Q: 如何查看详细使用指南？
A:
cret --guideQ: Windows 环境下删除临时目录失败？
A:
- 修改系统注册表启用长路径支持
- 或手动删除
xxx-extract目录
Q: 如何自定义 License 文件匹配规则？
A:工具的配置常量集中在config.py模块中，可以根据需要修改：
| 配置常量 | 说明 |
|---|---|
LICENSE_FILE_PATTERNS | License 文件名匹配模式（正则表达式列表） |
LICENSE_EXTENSIONS | License 文件扩展名集合 |
COPYRIGHT_IGNORED_SUFFIXES | Copyright 提取时忽略的文件扩展名 |
示例：添加新的 license 文件名模式
# 在 config.py 中添加 LICENSE_FILE_PATTERNS = [ # ... 现有模式 r"^my-custom-license$", # 添加自定义模式 ]Q: 遇到其他问题怎么办？
A:
- 使用
LOG_LEVEL=DEBUG查看详细日志 - 查看
result.json了解扫描原始结果 - 查看 DESIGN.md 了解设计逻辑
- 向项目提交 Issue，附上：
- 详细的错误信息
- 调试日志输出
- 目标文件/目录的基本信息
【免费下载链接】infrastructure本仓库用于托管CANN社区基础设施团队的公开信息，包括不限于：会议日程，成员信息，服务文档和配置等信息项目地址: https://gitcode.com/cann/infrastructure
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
