Develop Contribution 是一个面向学术研究项目的技能,核心目标是创建或规范化单个 contributions/<slug>/ 文件夹,使其达到 badge-general 合规、自包含,并带有足够详细的 report/report.tex,从而在撰写论文时无需重新阅读代码。
用途 该技能用于两类场景:一是创建新的贡献,包括分析、实验、数据集、软件或复现;二是将已有的草稿文件夹规范化为符合 badge 要求的贡献结构。
使用前阅读 在开始前,技能要求先阅读若干资料:contributions/README.md(badge-general 契约)、survey/survey.pdf 的 gaps 部分(在定位新贡献时使用)、references/methodology.md(评估、统计、图表规范)、references/experiments.md(运行日志与自主活动)、references/reproduction.md(复现外部工作)、references/ethics.md(数据红旗)、references/data.md(数据放置与贡献间数据依赖,当贡献涉及共享/大型数据或消费另一贡献的输出时)。
构建前准备(两种模式通用) 需要填写贡献 README 的 Positioning 部分,包括:该贡献将支持的主张;与最近先前工作的差异(引用 survey/SOTA citekeys);证据计划,即将要测量或收集什么以及如何收集;可证伪条件,即什么结果会反驳该主张。如果主张没有证据路径,应停止并与用户讨论。
Create Mode
- 将 contributions/_template/ 复制到 contributions/<slug>/(slug 使用 kebab-case)。
- 如果涉及 Python 代码,编写该贡献自己的 pyproject.toml(name、requires-python、dependencies),在根 pyproject.toml 的 [tool.uv.workspace] members 中添加 "contributions/<slug>",从根目录运行 uv sync --all-packages(普通 uv sync 会在 package = false 的根上修剪成员的依赖)。若依赖确实冲突,将路径移到 exclude,创建本地 venv,并在 README 中记录。
- 在文件夹内自由开发,结构可为 src/、data/、figures/、outputs/、notebooks。任何评估都遵循 references/methodology.md;每个支持主张的运行(包括自主活动)都要按 references/experiments.md 保留运行日志。复现外部工作时遵循 references/reproduction.md。
- 如实填写 README 的 badge 检查清单,每个勾选项都要在文件夹内有证据。对照 references/ethics.md 检查数据。
- 编写 report/report.tex:动机、与 SOTA 的定位(引用根 .bib)、方法、设置、结果(含图表)、局限性。构建命令:make contribution C=<slug>。
- 运行 make check。
Regularize Mode
- 清点草稿文件夹:存在什么、声称什么、对照 badge 检查清单缺少什么。
- 就地重组,保留来源(重命名时记录原始文件名),捕获环境,端到端验证运行路径,记录数据来源和伦理标记。
- 继续执行 Create Mode 的第 4–6 步。
规则 自包含:不得从其他贡献导入;值得共享的工具应成为自己的贡献并在 README 中引用。如果输入是另一贡献的输出,需声明并就地读取,绝不复制(见 references/data.md)。探索性结果绝不能伪装成已确认证据,需加以标注。负面结果也是结果,应在 report.tex 中报告。
完成标准 badge 检查清单完全且如实勾选,report.pdf 已构建,工作区一致,make check 通过。
适用场景与限制 该技能适用于学术研究项目中需要创建或规范化单个贡献文件夹的场景,尤其是需要 badge 合规、自包含、可复现的研究工作。限制包括:使用前必须填写 Positioning 部分,若主张无证据路径则需停止;不得从其他贡献导入;探索性结果需标注;负面结果需报告。具体平台、收费、价格等信息暂未提供。