research-publishing

研究成果发布方法

你正在帮助一位研究人员为论文投稿准备代码和相关材料，以便公开发布。

步骤 1：评估仓库

进行任何更改之前，先检查当前状态：

1. 敏感内容扫描：

   • API 密钥、令牌、凭据（使用 grep 搜索常见模式）
   • 研究人员机器上的硬编码路径
   • 内部 URL 或私有基础设施引用
   • 注释或数据中的个人身份信息

2. 依赖项审计：

   • 列出所有固定版本的依赖项
   • 识别专有或受限许可的依赖项
   • 检查是否存在已弃用或无人维护的依赖项
   • 验证所有依赖项是否可通过 pip/conda 安装

3. 代码组织：

   • 找出无用代码、调试遗留内容和临时文件
   • 找出应合并的重复代码
   • 检查是否存在可简化的过于复杂的代码

步骤 2：仓库结构

可发布的研究仓库应包含：

project/
  README.md            # Installation, usage, citation
  LICENSE              # Must have an explicit license
  requirements.txt     # or pyproject.toml with pinned deps
  setup.py / setup.cfg # Package installation
  src/                 # Source code
  scripts/             # Training, evaluation, inference scripts
  configs/             # Configuration files
  data/                # Sample data or download instructions
  checkpoints/         # Download instructions (not actual weights)
  results/             # Key result files referenced in paper

步骤 3：可复现性检查清单

针对论文中的每项实验：

• 配置文件存在，且与论文中的超参数一致
• 随机种子已设置并记录
• 已记录完整的训练命令
• 评估命令能够生成论文中报告的数值
• 数据预处理步骤已编写为脚本（而非手动操作）
• 已记录硬件要求（GPU 类型、内存、耗时）
• 依赖项版本已固定

步骤 4：README 结构

研究项目的 README 必须包含：

1. 标题 + 一句话描述
2. 论文链接（arXiv、会议页面）
3. 可视内容（架构图、关键结果图或演示 GIF）
4. 安装（逐步说明，并在干净环境中测试）
5. 快速开始（对单个示例进行推理，少于 5 条命令）
6. 训练（完整的复现命令）
7. 评估（复现论文中的数值）
8. 模型库 / 检查点（提供下载链接及预期指标）
9. 引用（BibTeX 代码块）
10. 许可证

步骤 5：清理代码

进行精简且有针对性的清理：

1. 移除调试打印、注释掉的代码和临时实验
2. 将硬编码路径替换为可配置路径（环境变量或参数）
3. 为公共函数添加文档字符串（内部辅助函数除外）
4. 确保清楚地记录主要入口点
5. 不要为了代码风格重构可正常运行的代码——这只会增加风险，没有收益

步骤 6：选择许可证

引导用户选择许可证：

许可证	允许商业用途	要求署名	Copyleft
MIT	是	是	否
Apache 2.0	是	是	否（授予专利权）
GPL 3.0	是	是	是（衍生作品）
CC BY 4.0	是	是	否（适用于非代码内容）
CC BY-NC 4.0	否	是	否（适用于非代码内容）

默认建议：代码采用 MIT，数据集/模型采用 CC BY 4.0。

步骤 7：发布前测试

发布之前：

1. 克隆到一个全新的目录
2. 严格按照 README 中的安装步骤操作
3. 运行快速开始命令
4. 运行评估，确认数值与论文一致
5. 检查 git 历史记录中是否包含敏感信息

输出格式

请提供：

1. 审计报告：发现的敏感内容、依赖项问题和无用代码
2. 操作清单：需要修改/移除/添加的具体文件
3. README 草稿：遵循上述结构
4. 可复现性检查清单：逐项实验核验状态