feat(skills): add gitlink-research-insight/repro/idea 科研辅助 skills
子赛题四作品：单仓科研代码仓库内涵解读的 3-skill 家族，主攻 「应用 GitLink 辅助科研」。全程数据由 gitlink-cli 采集，结论可溯源。 - gitlink-research-insight: 仓库级科研内涵解读（6 章节报告） + 方法—代码实现剖析模式（映射表 + 架构 Mermaid 图） - gitlink-research-repro: 实验复现性体检（8 维度 ✅/⚠️/❌ + 卡点修复建议） - gitlink-research-idea: 研究 Idea 生成（单仓局限 + 跨多仓创新对比） 每个 skill 含 SKILL.md + 真实范例（基于 GitLink 真实科研仓验证）。 区别于现有 scholar-profile/research-tracker/research-fork-impact （跨仓计数/评分），本系列在单仓做内容级研究智能。 Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
linlin
parent
71ca2bb683
commit
0fef744a7c
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
name: gitlink-research-idea
|
||||
version: 0.1.0
|
||||
description: "科研 Idea 生成：基于对一个（或多个）科研代码仓库的内涵解读，产出『方法局限 + 可拓展研究 Idea』。单仓模式给一个仓库生成局限与≥3条 Idea；多仓模式对比同主题多仓、提炼共性缺口与跨仓 Idea。当用户说『这个方法还能怎么改进』『有什么研究Idea』『创新启发』『这个方向的下一步』『这几个仓库相比之下还能做什么』时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-research-idea（科研 Idea 生成）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
## 何时使用 / 何时跳过
|
||||
|
||||
**使用本 skill（生成研究 Idea / 创新启发）：**
|
||||
- 用户说"这个方法还能怎么改进""有什么研究 Idea""创新启发""这个方向的下一步""这几个仓库相比之下还能做什么"
|
||||
- 用户要在某课题上选题、找创新点、写 future work
|
||||
|
||||
**跳过本 skill（改用其他 skill）：**
|
||||
- 想先读懂"这仓库做了什么" → 先 `gitlink-research-insight`（本 skill 的输入）
|
||||
- 想查"能不能复现" → `gitlink-research-repro`
|
||||
- 想看某领域热点/学者画像 → `gitlink-research-tracker` / `gitlink-scholar-profile`
|
||||
|
||||
> **与 `gitlink-research-tracker` 的本质区别（差异化自证）**：tracker 在**跨仓**粒度做"搜索 + 计数 + 成熟度评分"（哪个方向热、多少人在做）；本 skill 在**语义**粒度做"方法局限剖析 + 假设构造"（这个方法假设了什么、哪里可破、能提什么新假设）。一个回答"外面流行什么"，一个回答"这里能长出什么新研究"。
|
||||
|
||||
## ⚠️ 现实约束（驱动设计的前提）
|
||||
|
||||
1. GitLink 科研仓库多为**成品上传、无探索历史**——不能从 commit 挖"作者试过但放弃的方向"。Idea 必须**从内容（方法实现 + 实验配置）的内在矛盾/假设/边界**推导。
|
||||
2. 单仓 Idea 易"想当然"——所以**每条 Idea 必须三锚**：①缺口依据（代码/配置里的具体证据）②可行性（改哪个文件、复用什么现有接口）③与现有方法的差异（为什么不是重复造轮子）。无证据的 Idea 不产出。
|
||||
|
||||
## 两种模式
|
||||
|
||||
| 模式 | 输入 | 输出 | 适用 |
|
||||
|------|------|------|------|
|
||||
| **单仓模式（A3'，默认）** | 一个仓库的 A1 内涵解读 | 该方法的**局限清单 + ≥3 条可拓展研究 Idea** | 时间紧/只盯一个仓库；多仓凑不齐时的降级兜底 |
|
||||
| **多仓模式（A3，扩展）** | ≥3 个同主题仓库的 A1 内涵 | **创新点对比矩阵 + 共性缺口 + ≥3 条跨仓 Idea** | 核心差异化场景；需用户给 owner/repo 列表 |
|
||||
|
||||
> 单仓模式是本版默认交付；多仓模式复用同一"采集 + gap 合成"引擎，把单仓的"局限"升级为跨仓"共性缺口"。本 skill 的方法局限段即多仓对比的输入单元。
|
||||
|
||||
## 数据采集
|
||||
|
||||
**单仓模式**：本 skill 建立在 `gitlink-research-insight`（A1）产出之上。若用户尚未给内涵解读，**先跑 insight** 拿到"研究问题/方法/创新/基线/数据集"。再按需用 `sub_entries` 精读方法实现以找"内在矛盾"：
|
||||
|
||||
```bash
|
||||
# 复用 insight 的采集 + 按需精读方法源码（正文在 data.entries.content）
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/<owner>/<repo>/sub_entries" --query "filepath=<方法文件>&ref=master" --format json
|
||||
# 多仓模式：对每个仓库重复上述（或直接复用各自已生成的 insight 报告）
|
||||
```
|
||||
|
||||
**多仓模式**：仓库来源 = 用户给定 `owner/repo` 列表（推荐，demo 可 curate 3–5 个同主题 CIL 仓）；或 `search +repos`（噪声大，需 AI 筛科研类）。
|
||||
|
||||
## Idea 生成流程（openair gap-analysis / hypothesis-construction 内核）
|
||||
|
||||
### Step 1：拿到方法的"内涵 + 实现细节"（来自 insight，必要时补读源码）
|
||||
|
||||
### Step 2：做"假设—边界"剖析（gap-analysis）
|
||||
对方法的每个核心机制，追问四个破绽问题（每问对应一类 Idea 来源）：
|
||||
- **统计依赖**：方法是否依赖某统计量（batch 均值/方差、类比例）？该统计在什么条件下会失效？（→ 稳健化 Idea）
|
||||
- **作用层级**：方法只在某一层（如 logit 层）作用？同一矛盾在别的层（feature/loss/data）是否也在？（→ 层级推广 Idea）
|
||||
- **静态 vs 动态**：关键超参/权重是静态固定的？随任务/数据分布变化是否次优？（→ 自适应 Idea）
|
||||
- **范畴边界**：方法只在某子类（如 logit-KD）验证？同一框架能否统一相邻范畴（feature-KD/跨模态）？（→ 范畴统一/迁移 Idea）
|
||||
|
||||
### Step 3：生成 ≥3 条研究 Idea（hypothesis-construction）
|
||||
每条 Idea **必须含三锚**：
|
||||
- **缺口依据**：代码/配置里的具体证据（`文件:函数`），不是空想
|
||||
- **可行性**：改哪里、复用什么现有接口、大致工作量
|
||||
- **与现有方法的差异**：为什么是新研究而非复现
|
||||
|
||||
### Step 4：生成中文「研究 Idea 报告」（按下述模板，Write 工具产出 Markdown）
|
||||
|
||||
## 输出模板：研究 Idea 报告（单仓模式）
|
||||
|
||||
```markdown
|
||||
# 💡 研究 Idea 报告：<仓库/论文名>
|
||||
|
||||
> 基于：<owner>/<repo> 的内涵解读 ｜ 数据来源：GitLink ｜ 生成时间：{{date}}
|
||||
> 结论先行：该方法最值得追问的 N 个方向 …
|
||||
|
||||
## 一、方法局限剖析（Idea 的土壤）
|
||||
| # | 局限 | 证据（代码:位置） | 破绽类型 |
|
||||
|---|------|-------------------|----------|
|
||||
| 1 | … | `文件:函数` | 统计依赖/层级/静态/范畴 |
|
||||
|
||||
## 二、研究 Idea（≥3 条，每条三锚）
|
||||
### Idea 1：<一句话标题>
|
||||
- **假设**：…
|
||||
- **缺口依据**：…（`文件:位置`）
|
||||
- **可行性**：…（改哪个文件、复用什么、工作量）
|
||||
- **与现有差异**：…
|
||||
（重复 ≥3 条）
|
||||
|
||||
## 三、优先级建议
|
||||
（按 可行性 × 预期增益 排序，给一个"先做哪个"的建议 + 一句话理由）
|
||||
```
|
||||
|
||||
> **多仓模式**额外加：①"创新点对比矩阵"（每仓 1–3 条创新 + 代码证据）②"共性研究缺口 ≥2 条"③跨仓 Idea。模板同理扩展。
|
||||
|
||||
## 示例
|
||||
|
||||
- **单仓模式（A3'）**：[`examples/maintaining-fairness-lkd-cil-ideas.md`](examples/maintaining-fairness-lkd-cil-ideas.md)（靶子仓库：从 `Zscore()` 的 batch 统计、fairness 仅在 logit 层、`--lambd` 静态权重等真实代码证据，推出 feature-level fairness / 自适应权重 / 稳健归一化 等 Idea）。
|
||||
- **多仓模式（A3）**：[`examples/cil-multi-repo-ideas.md`](examples/cil-multi-repo-ideas.md)（3 个同主题 CIL 仓的创新点对比矩阵 + 共性缺口 + 4 条跨仓 Idea + 差异化自证；含"GitLink 同主题仓稀缺、搜索非全文"的发现与穷举搜索记录）。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- ✅ **每条 Idea 必须有代码证据**（`文件:函数`），无证据不产出——这是与"空想 future work"的分界。
|
||||
- ✅ **先 insight 后 idea**：单仓模式依赖 A1 内涵；若用户直接要 Idea，先快速跑 insight。
|
||||
- ✅ **单仓是兜底，多仓是目标**：时间允许时，把 ≥3 个同主题仓库的内涵喂进来做跨仓合成（差异化最强）。
|
||||
- ⚠️ **Git Bash 路径转换**：raw `api` 带前导 `/` 必须 `MSYS_NO_PATHCONV=1`。
|
||||
- ✅ **报告以中文 Markdown 产出**。
|
||||
|
|
@ -0,0 +1,120 @@
|
|||
# 💡 多仓研究 Idea 报告：Class-Incremental Learning 三仓创新对比
|
||||
|
||||
> 输入仓库（同主题：CIL / 类增量学习，均 GitLink 实采）：
|
||||
> 1. `gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` —— AAAI'25，KD 公平性（靶子，单仓 Idea 详见 [`maintaining-fairness-lkd-cil-ideas.md`](maintaining-fairness-lkd-cil-ideas.md)）
|
||||
> 2. `PatZQ/AudioCIL` —— 音频 CIL 工具箱，复现 16 经典 + 3 SOTA 方法（colaudiolab 镜像）
|
||||
> 3. `Kexing/class-incremental-learning` —— yaoyao-liu CIL 合集：AAN（CVPR'21）+ Mnemonics Training（CVPR'20）
|
||||
>
|
||||
> 模式：**多仓 A3**（跨仓语义合成）。数据来源：GitLink（gitlink-cli 实时采集）｜ 生成时间：2026-07-03。每条结论带仓库/文件溯源。
|
||||
|
||||
> **结论先行**：三仓恰好覆盖 CIL 三条正交技术线——**logit-KD 公平化**（靶子）、**方法库/跨模态基准**（AudioCIL）、**架构聚合 + 记忆增强**（AAN/Mnemonics），且都源于 PyCIL 骨架却各自演进。最大共性缺口是**"fairness"概念在三仓中定义互不统一**，且**无跨模态 fairness 对比**。由此推出 4 条跨仓研究 Idea。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 范围说明：为何是 3 仓（而非更多）
|
||||
|
||||
经穷举搜索（FOSTER/LUCIR/CoPE/MEMO/BiC/DER/FeCAM/IL2A/PASS/SSRE/AAN 等方法名 + 增量学习/持续学习/类增量/终身学习 中文词），**GitLink 搜索为名/描述匹配、非全文**（`PyCIL`/`iCaRL`/`continual`/`catastrophic forgetting` 均 0 命中），**全平台可确证的 CIL 科研仓即这 3 个**。此"平台科研仓稀缺 + 搜索非全文"本身是子赛题四的现实约束证据，写入报告以备核查。三仓已覆盖 CIL 主流策略族，足以支撑跨仓合成。
|
||||
|
||||
---
|
||||
|
||||
## 一、创新点对比矩阵
|
||||
|
||||
| 仓库 | 核心 CIL 策略 | 创新点（1–3，附代码证据） | 栈 / 年代 |
|
||||
|------|-------------|---------------------------|-----------|
|
||||
| **靶子** Maintaining-Fairness-LKD-CIL | logit-KD **公平化** | ① **类间公平** `Zscore()`（全类 logit z-score，`dim=-1`）<br>② **类内公平** `Inverse_Zscore()`（`dim=0`）<br>③ inter+intra 联合（`--method interintra`），**即插即用、零额外训练成本** | Py3.8 / torch1.8 · AAAI'25 |
|
||||
| **AudioCIL** | **方法库 / 跨模态基准** | ① 音频 CIL 首个系统基准（多场景）<br>② 复现 **16 经典 + 3 SOTA**（FineTune/Replay/EWC/LwF/iCaRL/GEM/BiC/**WA**/POD-Net/DER/Coil…，见 README "Methods Reproduced"）<br>③ 统一 PyCIL 骨架跨模态评测 | Py3.8 / torch1.8 · arXiv'24 |
|
||||
| **class-incremental-learning**（yaoyao-liu） | **架构聚合 + 记忆增强** | ① **AAN** 自适应聚合多专家头（`adaptive-aggregation-networks/models`）CVPR'21<br>② **Mnemonics Training** 可学习记忆图像（`mnemonics-training/{1_train,2_eval}`）CVPR'20 | Py3.6 / torch1.2 · 2020–21 |
|
||||
|
||||
> **关键交叉点**：靶子的 7 基线（LwF/iCaRL/BiC/DER/PODNet/WA/Replay）**是 AudioCIL 16+ 方法库的子集**；且 AudioCIL 复现的 **WA（"Maintaining Discrimination and **Fairness** in CIL", CVPR'20）** 与靶子的"fairness"主题直接同源——但两者"公平"的落点完全不同（见缺口 G1）。
|
||||
|
||||
---
|
||||
|
||||
## 二、共性研究缺口（≥2 条）
|
||||
|
||||
### G1 · "Fairness" 概念碎片化，缺统一分类法 ⭐
|
||||
三仓都触及"fairness"，但**定义与作用对象互不相同**，社区无统一框架：
|
||||
- **靶子** = **logit 层公平**：`Zscore` 在 student/teacher 的 logit 向量上做全类归一化，消解 KD-CE 冲突（`models/lwf.py: Zscore()`）。
|
||||
- **AudioCIL 复现的 WA** = **分类头权重公平**：纠正最后一层 FC 的 bias（arXiv 1911.07053），作用在权重而非 logit 蒸馏。
|
||||
- **AAN** = **专家头聚合公平**：自适应聚合多个 task-specific head（`adaptive-aggregation-networks/models`），作用在架构层。
|
||||
> 三者分别公平化 **logit / 权重 / head**，互不引用、不可比。证据：三仓代码中"fair/normalize/aggregation"落点各异。
|
||||
|
||||
### G2 · 跨模态 fairness 无统一验证
|
||||
- **靶子** 支持音频（`utils/data.py` 含 Librispeech/torchaudio），但 fairness 主实验在视觉 CIFAR/ImageNet。
|
||||
- **AudioCIL** 是音频基准，但**未把 fairness 作为评测维度**（只报告各方法精度）。
|
||||
- **AAN/Mnemonics** 仅视觉（CIFAR/ImageNet）。
|
||||
> 没有任何一仓做过"同一 fairness 机制在视觉 ↔ 音频 CIL 的统一对比"。靶子（有音频代码）+ AudioCIL（有音频基准）拼起来恰好闭环，却无人合。
|
||||
|
||||
### G3（补充）· 复现生态碎片化
|
||||
三仓同源于 PyCIL 骨架（`convs/models/exps/utils/main.py/trainer.py` 几乎一一对应），但 **config 与方法注册接口不互通**（靶子 `exps/`、AudioCIL `exps-audio/`、AAN 自有 `models/`），跨仓方法对比需手工对齐——抬高社区复现与对比门槛。
|
||||
|
||||
---
|
||||
|
||||
## 三、跨仓研究 Idea（4 条，每条三锚）
|
||||
|
||||
### Idea 1：统一 Fairness 分类法 + 跨机制消融基准 ⭐⭐
|
||||
- **假设**：logit-公平（靶子 Zscore）、权重-公平（WA）、head-公平（AAN）三者可纳入统一框架，并在同一基准上消融对比，揭示哪种"公平"对 CIL 收益最大、是否可叠加。
|
||||
- **缺口依据**：G1。三仓 fairness 落点互不相同（`models/lwf.py: Zscore` vs AudioCIL 的 WA vs AAN 的 head 聚合）。
|
||||
- **可行性**：**高**。复用 AudioCIL 的统一骨架（已含 WA/LwF/iCaRL 等 19 方法），把靶子的 Zscore 作为新 `--method` 即插即用注入，跑同一音频+视觉基准即可横向对比。靶子本就宣称"与现有 logit-KD 即插即用集成"。
|
||||
- **与现有差异**：现有各做各的 fairness；本 Idea 给出**首个跨 fairness 机制的可比消融**，而非又一个并列方法。
|
||||
|
||||
### Idea 2：跨模态 fairness 迁移系统验证
|
||||
- **假设**：logit-公平（Zscore）与模态无关（纯 logit 操作），应可从视觉迁到音频 CIL；系统量化其迁移收益与衰减。
|
||||
- **缺口依据**：G2。靶子有音频代码路径却未验 fairness 迁移；AudioCIL 有音频基准却无 fairness 维度。
|
||||
- **可行性**：**中高**。靶子的 `Zscore` 是模态无关函数，直接挂到 AudioCIL 的音频方法上跑 Librispeech 增量（两侧代码就绪、同 PyCIL 骨架）。
|
||||
- **与现有差异**：**首个"同一 fairness 机制 视觉↔音频 CIL 迁移性"报告**，填补 G2 的空白。
|
||||
|
||||
### Idea 3：即插即用 fairness × 记忆增强 的正交叠加
|
||||
- **假设**：靶子的 logit-KD 公平（蒸馏侧）与 Mnemonics 的可学习记忆图像（记忆/表征侧）解决的是 CIL 的两个不同瓶颈，理论上正交可叠加，组合后收益相加。
|
||||
- **缺口依据**：三仓中 fairness（靶子）与 memory augmentation（yaoyao-liu/Mnemonics）是两条独立线，从未组合验证。靶子 self-claim 即插即用；Mnemonics 改 exemplar 表征。
|
||||
- **可行性**：**中**。两者代码层基本不冲突（一个改 KD loss、一个改 buffer 表征），同 PyCIL 骨架可拼；需跑组合实验证正交性。
|
||||
- **与现有差异**：验证"蒸馏公平 × 记忆增强"的**正交叠加收益**，连接两条原本孤立的研究线。
|
||||
|
||||
### Idea 4：统一 PyCIL 配置互操作层（工程基建型）
|
||||
- **假设**：一个 config 适配 + 方法注册表能让三仓（及未来 CIL 仓）方法互通互比，显著降低社区复现门槛。
|
||||
- **缺口依据**：G3。同骨架但 `exps/` vs `exps-audio/` vs AAN 自有结构不互通。
|
||||
- **可行性**：**中**（工程量大但价值高）。做 method registry + config schema 统一，对标 MMClassification 之于分类。
|
||||
- **与现有差异**：不是新方法，是**生态基建**，直接服务 G3 的复现碎片化。
|
||||
|
||||
---
|
||||
|
||||
## 四、优先级建议
|
||||
|
||||
| 优先级 | Idea | 理由 |
|
||||
|--------|------|------|
|
||||
| 🥇 | **Idea 1（统一 fairness 消融）** | 两仓代码就绪、即插即用、新颖性高（跨机制对比前所未有），最快出强结论 |
|
||||
| 🥈 | **Idea 2（跨模态迁移）** | 复用 Idea 1 的注入管线、填补 G2 空白、故事好讲 |
|
||||
| 🥉 | **Idea 3（正交叠加）** | 连接 fairness + memory 两条线，理论贡献清晰，实验量略大 |
|
||||
| 视资源 | Idea 4（互操作层） | 工程型，适合作为开源基建延伸 |
|
||||
|
||||
> 一句话：**用 AudioCIL 当统一试验台，把靶子的 Zscore fairness 注入进去（Idea 1），再跨到音频（Idea 2）**——以最小代价同时咬住 G1+G2 两个共性缺口。
|
||||
|
||||
---
|
||||
|
||||
## 五、差异化自证（为何现有 skill 做不到）
|
||||
|
||||
| 本步产出 | `gitlink-research-tracker` | `gitlink-scholar-profile` | `gitlink-research-fork-impact` |
|
||||
|----------|---------------------------|--------------------------|-------------------------------|
|
||||
| 创新点语义对比 + 缺口合成 + 假设构造 | ✗ 跨仓搜索 + 成熟度/热度**计数** | ✗ 学者画像，不分析方法 | ✗ 传播力计数，不碰研究内涵 |
|
||||
| 读代码对齐"fairness 落点"、长出新研究问题 | 结构上无法产出（不读方法实现） | 同左 | 同左 |
|
||||
|
||||
> 本步是**语义级**合成（读懂每个仓的方法机制 → 对齐 → 找空白 → 提假设），计数/评分类 skill 在结构上无法替代。
|
||||
|
||||
---
|
||||
|
||||
## 附：本报告采集命令（可复现）
|
||||
|
||||
```bash
|
||||
# 仓 1（靶子）—— 详见 gitlink-research-insight；关键方法源码：
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/gaozijian19/Maintaining-Fairness-in-LKD-for-CIL/sub_entries" --query "filepath=models/lwf.py&ref=master" --format json
|
||||
|
||||
# 仓 2（AudioCIL，默认分支 main）
|
||||
gitlink-cli repo +info --owner PatZQ --repo AudioCIL --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/PatZQ/AudioCIL/sub_entries" --query "filepath=README.md&ref=main" --format json # Methods Reproduced 列表
|
||||
|
||||
# 仓 3（class-incremental-learning，默认分支 main）
|
||||
gitlink-cli repo +info --owner Kexing --repo class-incremental-learning --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/Kexing/class-incremental-learning/sub_entries" --query "filepath=&ref=main" --format json # 根目录：adaptive-aggregation-networks/ + mnemonics-training/
|
||||
|
||||
# 同主题仓发现（已穷举，确认平台稀缺）
|
||||
gitlink-cli search +repos -k "class-incremental" --limit 30 --format json # 仅 AudioCIL 命中科研仓
|
||||
```
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
# 💡 研究 Idea 报告：Maintaining Fairness in LKD for CIL
|
||||
|
||||
> 基于：`gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` 的内涵解读（见 [`../gitlink-research-insight/examples/maintaining-fairness-lkd-cil-insight.md`](../../gitlink-research-insight/examples/maintaining-fairness-lkd-cil-insight.md)）｜ 数据来源：GitLink（gitlink-cli 实时采集）｜ 生成时间：2026-07-03
|
||||
> 模式：**单仓 A3'**（多仓 A3 的降级兜底）。
|
||||
> 本报告由 `gitlink-research-idea` skill 流程产出，每条 Idea 均带代码证据，可核查。
|
||||
|
||||
> **结论先行**：该方法（logit 全类归一化的 inter/intra-class fairness）工程上极简洁优雅，但其"公平化"**只作用在最终 logit 层、统计量是 batch 内瞬时值、inter/intra 权重全程静态**——这三点正是最值得追问的方向。下面给出 5 条由代码证据直接支撑的研究 Idea，按"可行性 × 预期增益"排序。
|
||||
|
||||
---
|
||||
|
||||
## 一、方法局限剖析（Idea 的土壤）
|
||||
|
||||
| # | 局限 | 证据（代码 : 位置） | 破绽类型 |
|
||||
|---|------|---------------------|----------|
|
||||
| L1 | 公平化归一化**只用 batch 内瞬时统计**（mean/std），小 batch 或类极不均衡时统计量噪声大 | `models/lwf.py` → `Zscore()` 用 `logits.std(dim=-1)`、`Inverse_Zscore()` 用 `dim=0`，均无 running/EMA | 统计依赖 |
|
||||
| L2 | 公平化**只在最终 logit 层**作用，中间 feature 表示的 recency bias 未触及 | `Zscore` 仅作用于 `_network(inputs)["logits"]`；`convs/` backbone 输出特征未经公平化 | 作用层级 |
|
||||
| L3 | inter/intra 权重 `alpha/beta` **全程静态**，由首帧 `--lambd` 一次性算定，不随任务/类比例变化 | `models/lwf.py` → `LwF.__init__`：`alpha=2*lambd/(1+lambd)`、`beta=2/(1+lambd)` 一次定死 | 静态 vs 动态 |
|
||||
| L4 | fairness 框架**只在 logit-KD 验证**，同仓库已有的 feature-KD（`feature`/`rkd` 分支）未纳入统一公平性 | `_update_representation` 里 `feature`/`passfeature`/`rkd` 分支用 `get_features()`，未与 Zscore 结合 | 范畴边界 |
|
||||
| L5 | 跨模态（语音）**支持但未充分验证公平性迁移** | `utils/data.py` 含 Librispeech/torchaudio/torchlibrosa，但论文公平性结论主要在视觉 CIL | 范畴边界 |
|
||||
|
||||
---
|
||||
|
||||
## 二、研究 Idea（5 条，每条三锚）
|
||||
|
||||
### Idea 1：Feature-level Fairness —— 把公平化从 logit 层下沉到表示层 ⭐
|
||||
- **假设**：recency bias 不只存在于分类头 logit，也存在于 backbone 输出特征；把 inter/intra fairness 推广到 feature 空间能进一步缓解新旧类偏置。
|
||||
- **缺口依据**：`models/lwf.py` 中 `Zscore`/`Inverse_Zscore` 仅作用于 `["logits"]`；而同文件 `feature`/`rkd` 分支已通过 `self._network.get_features(inputs)` 取到特征（L2、L4）——说明接口现成、公平化却未覆盖该层。
|
||||
- **可行性**：**高**。复用 `get_features()`，对特征做 `Zscore` 后接余弦/MSE 蒸馏；改动局限在 `_update_representation` 新增一个分支，~30 行，复用现有 trainer 与数据管线。
|
||||
- **与现有差异**：现有 fairness 是"输出层"的；本 Idea 是"表示层"的——更深的公平化，且可与 logit-level fairness 叠加（正交贡献）。
|
||||
|
||||
### Idea 2：Adaptive Inter/Intra Weighting —— 静态 `--lambd` 改为任务进度/类比例自适应 ⭐
|
||||
- **假设**：旧类占比随任务推进单调上升，固定 `alpha/beta` 全程不变是次优；让权重随 `_known_classes/_total_classes` 动态调整可提升后期任务表现。
|
||||
- **缺口依据**：`models/lwf.py` → `LwF.__init__` 中 `alpha/beta` 由 `lambd` 一次性算定，`_update_representation` 全程复用，未随 `_cur_task`/类比例变化（L3）。
|
||||
- **可行性**：**中高**。把 `alpha/beta` 的计算从 `__init__` 移进 `_update_representation`，设为 `_known_classes/_total_classes` 的函数（或加一个轻量学习率式 schedule）；~20 行，无新依赖。
|
||||
- **与现有差异**：现有是"静态超参"；本 Idea 是"动态课程式权重"——把 inter/intra 偏好与增量阶段耦合，更贴合 CIL 的非平稳性。
|
||||
|
||||
### Idea 3：Batch-Robust Normalization —— 用 running/EMA 统计量替代 batch 瞬时值
|
||||
- **假设**：`Zscore` 的 batch 内 `std` 在小 batch（如 `batch_size=128` 切到长尾类时实际更小）或不均衡时噪声大，拖累蒸馏；改用跨 batch 的 running mean/var 能稳定公平化。
|
||||
- **缺口依据**：`models/lwf.py` → `Zscore()` / `Inverse_Zscore()` 直接用 `logits.mean/std(dim=±1)`，无 momentum/running 机制（L1）。
|
||||
- **可行性**：**高**。仿 BatchNorm 维护 running stats（`register_buffer` + momentum 更新），改动集中在两个函数；训练循环不动。
|
||||
- **与现有差异**：现有是"per-batch 瞬时统计"；本 Idea 是"跨 batch 稳定估计"——直接对标 BN 的成熟经验，易写易消融。
|
||||
|
||||
### Idea 4：Unified Fairness for Feature-KD —— 把 fairness 框架统一到 RKD/feature 蒸馏
|
||||
- **假设**：logit-KD 的公平化思想（消除 teacher 的过度自信偏置）在 feature-KD 中同样成立；统一两者能得到一个更通用的"fair distillation"框架。
|
||||
- **缺口依据**：`_update_representation` 中 `rkd` 分支（`RkdDistance`/`RKdAngle`）与 `interintra` 分支**互斥并列**、共享同一 `--method` 开关却无交叉（L4）。
|
||||
- **可行性**：**中**。需在特征距离/角度空间定义"类间/类内公平"（非平凡），但代码已有 `pdist`、`get_features` 等积木可拼；可作为一篇方法统一的 follow-up。
|
||||
- **与现有差异**：现有 fairness 绑定 logit-KD；本 Idea 给出 logit 与 feature 两族 KD 的统一公平性视角。
|
||||
|
||||
### Idea 5：Cross-Modal Fairness Transfer —— 系统验证 inter/intra fairness 在语音/多模态 CIL 的迁移
|
||||
- **假设**：公平化机制（logit 归一化）与模态无关，应可迁到 audio CIL；验证其在语音类增量下的收益与差异。
|
||||
- **缺口依据**：`utils/data.py` 已实现 Librispeech100（`torchaudio`/`torchlibrosa` 的 `Spectrogram`/`LogmelFilterBank`），代码就绪但论文公平性主实验在视觉（L5）。
|
||||
- **可行性**：**中**。需跑 audio 增量实验（数据/算力成本），但代码路径已通；偏实证型，方法改动小。
|
||||
- **与现有差异**：现有结论限视觉 CIL；本 Idea 把 fairness 的适用边界扩到跨模态，是"验证 + 迁移"型贡献。
|
||||
|
||||
---
|
||||
|
||||
## 三、优先级建议（可行性 × 预期增益）
|
||||
|
||||
| 优先级 | Idea | 理由 |
|
||||
|--------|------|------|
|
||||
| 🥇 先做 | **Idea 3（稳健归一化）** | 改动最小（两函数）、对标 BN 经验、消融干净，最快出结论 |
|
||||
| 🥈 次做 | **Idea 1（feature-level fairness）** | 接口现成、与现有 logit-level 正交可叠加、新颖性高 |
|
||||
| 🥉 再做 | **Idea 2（自适应权重）** | 直击 CIL 非平稳性，故事好讲，工作量略高于前两者 |
|
||||
| 视资源 | Idea 4 / 5 | 方法统一型 / 跨模态验证型，工作量大，适合作为延伸课题 |
|
||||
|
||||
> 一句话：**先做 Idea 3 锁一个"稳定可复现的改进"，再用 Idea 1 拿"表示层公平化"的新颖性**——这两条都以最小改动切入该仓库最明显的两个破绽（batch 瞬时统计、仅 logit 层）。
|
||||
|
||||
---
|
||||
|
||||
## 附：本报告采集命令（可复现）
|
||||
|
||||
```bash
|
||||
OWNER=gaozijian19; REPO=Maintaining-Fairness-in-LKD-for-CIL
|
||||
# 内涵解读（A1）见 gitlink-research-insight；本报告在其上精读方法实现：
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=models/lwf.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=utils/data.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=exps/lwf.json&ref=master" --format json
|
||||
```
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
name: gitlink-research-insight
|
||||
version: 0.1.0
|
||||
description: "仓库级科研项目洞悉：深度解读一个科研/论文代码仓库的内涵——研究问题、方法、核心创新、对比基线、数据集、复现性，生成中文「科研内涵解读报告」。当用户想快速搞懂一个陌生科研代码仓库、做科研复盘、或为选题找参考时触发。常见表述：「这个仓库做了什么」「解读一下这个论文代码」「这个科研项目讲了啥」。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-research-insight（仓库级科研项目洞悉）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
## 何时使用 / 何时跳过
|
||||
|
||||
**使用本 skill（单仓深度内容解读）：**
|
||||
- 用户说"这个仓库做了什么""解读这个论文代码""这个科研项目讲了啥"
|
||||
- 用户拿到一个陌生科研/论文代码仓库，想 30 分钟内读懂其研究内涵
|
||||
|
||||
**跳过本 skill（改用其他 skill）：**
|
||||
- 想看某学者/团队跨仓画像 → `gitlink-scholar-profile`
|
||||
- 想做某领域技术调研/热点追踪（跨仓） → `gitlink-research-tracker`
|
||||
- 想看某仓库被 fork 后的传播 → `gitlink-research-fork-impact`
|
||||
- 只查许可证/依赖合规 → `gitlink-compliance` / `gitlink-license-compliance`
|
||||
|
||||
> **与上述 skill 的本质区别**：它们在**跨仓**粒度做指标计数/评分；本 skill 在**单仓**粒度做**内容级研究内涵理解**。
|
||||
|
||||
## ⚠️ 现实约束（驱动设计的前提）
|
||||
|
||||
GitLink 上的科研仓库**绝大多数是"成品上传"**——论文发表后整体上传，commit 少（常见 1–5 个）、**不含真实研究探索过程**（实测靶子仓库仅 3 个 commit 且全部在同一天）。
|
||||
|
||||
→ 因此本 skill **基于"内容"（README + 代码结构 + 实验配置 + 依赖）做解读，而非基于 commit/分支演进**。不要试图从 commit 历史提炼"技术演进脉络"——那在 GitLink 科研仓库上基本无数据。
|
||||
|
||||
## 数据采集（只用这些 gitlink-cli 命令）
|
||||
|
||||
```bash
|
||||
# 0) 前置：认证
|
||||
gitlink-cli auth status
|
||||
|
||||
# 1) 仓库元信息（名称/描述/大小/默认分支/mirror 标志/各 count）
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 2) README 全文 —— 【主要信息源】，Abstract/方法/数据集/运行命令/作者多在此
|
||||
gitlink-cli repo +readme --owner <owner> --repo <repo> --format json
|
||||
# 返回 data.content（base64）或 data.replace_content（已解码，图片地址已改绝对路径）
|
||||
|
||||
# 3) 文件结构 —— 暴露方法实现位置、基线矩阵、模块划分
|
||||
gitlink-cli repo +tree --owner <owner> --repo <repo> --format json
|
||||
# 逐层展开子目录：对 tree 结果中的 type=dir，可用 api 递归列出
|
||||
|
||||
# 4) 语言分布 / 贡献者 / 代码统计
|
||||
gitlink-cli repo +languages --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli repo +contributors --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli repo +code-stats --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
> **镜像仓库注意**：`repo +info` 的 `contributor_users_count` 对 GitHub 镜像恒为 0（无 GitLink 注册用户）；要看真实贡献者，必须用 `repo +contributors`（按 commit 邮箱归因）。
|
||||
|
||||
> **读取任意文件（如 requirements.txt / exps/*.json / main.py）**：用 GitLink 的 `sub_entries` 端点（**不是 `/contents/`**——该路径在 GitLink 不存在，会 404 返回 SPA HTML）。正文在返回的 `data.entries.content`（已解码纯文本）。**Git Bash 下必须加 `MSYS_NO_PATHCONV=1`**（否则前导 `/` 被转成 `A:/...` 导致 404）：
|
||||
> ```bash
|
||||
> MSYS_NO_PATHCONV=1 gitlink-cli api GET "/<owner>/<repo>/sub_entries" --query "filepath=<path>&ref=master" --format json
|
||||
> ```
|
||||
> （`/raw/` 端点对 API token 常返回 403，勿用。所有现有 skill 统一用 `sub_entries`。）
|
||||
|
||||
## 解读流程
|
||||
|
||||
### Step 1：采集（执行上述命令，--format json）
|
||||
|
||||
### Step 2：识别"科研信号"
|
||||
从 README + tree 判断这是否为科研仓库及方向：
|
||||
- README 是否含 Abstract / 论文引用 / arXiv / 顶会名（AAAI/NeurIPS/ICML…）
|
||||
- tree 是否含典型科研结构：`exps/`|`configs/`（实验配置）、`models/`|`convs/`（模型实现）、`data/`|`utils/data.py`（数据集）、`requirements.txt`、训练入口（`main.py`/`train.py`）
|
||||
- 是否声明基于某已有框架（如 "builds upon PyCIL"）
|
||||
|
||||
### Step 3：提炼六维（AI 综合 README + tree + stats）
|
||||
|
||||
| 维度 | 提炼来源 | 要点 |
|
||||
|------|----------|------|
|
||||
| 研究问题与动机 | README Abstract | 解决什么问题、为何重要 |
|
||||
| 方法与核心创新 | README 方法段 + tree 模型文件 | 核心机制、创新点（每条尽量映射到代码位置） |
|
||||
| 对比基线与实验矩阵 | `exps/`/`configs/` 文件名 + README | 作为对比/集成的基线方法清单 |
|
||||
| 数据集与运行入口 | README + `utils/data.py` + 入口脚本 | 支持的数据集、训练/推理命令 |
|
||||
| 复现性速览 | `requirements.txt` + README 运行说明 + 预训练权重链接 | 环境是否锁定、数据是否可得、入口是否清晰 |
|
||||
| 仓库画像 | repo +info / +languages / +contributors / +code-stats | 规模、语言、贡献者、是否成品上传 |
|
||||
|
||||
### Step 4：生成中文「科研内涵解读报告」（按下述模板，Write 工具产出 Markdown）
|
||||
|
||||
## 输出模板：科研内涵解读报告
|
||||
|
||||
```markdown
|
||||
# 🔬 科研内涵解读报告：<仓库标题/论文名>
|
||||
|
||||
> 解读对象：<owner>/<repo> ｜ 数据来源：GitLink（gitlink-cli 实时采集） ｜ 解读时间：{{date}}
|
||||
|
||||
## 一、仓库画像
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| 仓库 | owner/repo（如为镜像，标注 mirror + 原址） |
|
||||
| 论文/会议 | （从 README 引用提取，如 AAAI'25） |
|
||||
| 规模 / 语言 | size ｜ Python xx% / Shell xx% |
|
||||
| 贡献者 | n 人（主力：xxx，占比） |
|
||||
| 上传形态 | 成品上传 / 持续演进（commit 数与时间跨度判断） |
|
||||
|
||||
## 二、研究问题与动机
|
||||
（一段话：解决什么问题、为什么重要、现有方法不足）
|
||||
|
||||
## 三、方法与核心创新
|
||||
1. **创新点一**：…（→ 代码位置：<file>）
|
||||
2. **创新点二**：…（→ 代码位置：<file>）
|
||||
（每条创新尽量标注对应代码文件/目录）
|
||||
|
||||
## 四、对比基线与实验矩阵
|
||||
（从 exps/configs 提取基线清单；说明本方法与它们的关系：对比 / 即插即用集成 / 扩展）
|
||||
|
||||
## 五、数据集与运行入口
|
||||
- 支持数据集：…
|
||||
- 运行命令：（从 README 提取真实命令）
|
||||
- 数据/权重获取方式：…
|
||||
|
||||
## 六、复现性速览 + 一句话评价
|
||||
| 维度 | 状态 | 依据 |
|
||||
|------|------|------|
|
||||
| 环境锁定 | ✅/⚠️/❌ | requirements.txt 是否全 pin |
|
||||
| 数据可得 | ✅/⚠️/❌ | 是否需手填路径/公开下载 |
|
||||
| 运行入口 | ✅/⚠️/❌ | 是否有明确 main.py + config |
|
||||
| 预训练权重 | ✅/⚠️/❌ | 是否提供下载链接 |
|
||||
|
||||
**一句话评价**：…（这个仓库是什么、强在哪、适合谁）
|
||||
```
|
||||
|
||||
> **溯源要求**：报告中每条结论尽量标注来源（README 某段 / 某文件 / 某命令输出），可核查。
|
||||
|
||||
## 示例
|
||||
|
||||
完整范例见 [`examples/maintaining-fairness-lkd-cil-insight.md`](examples/maintaining-fairness-lkd-cil-insight.md)（靶子仓库 `gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` 的真实解读）。
|
||||
|
||||
## 模式二：方法—代码实现剖析（A2）
|
||||
|
||||
> 在 A1 内涵解读之上，回答"论文方法如何落到代码、想改某模块该看哪个文件"。**不依赖 commit 历史**，纯从代码结构重建。当用户说"这个方法的代码在哪""论文公式对应哪段代码""我想改 X 该看哪个文件"时进入本模式。
|
||||
|
||||
### A2 流程
|
||||
|
||||
1. **复用 A1 的采集**（`+info`/`+readme`/`+tree`），再用 `sub_entries` 精读关键源码：入口（`main.py`/`train.py`）、训练循环（`trainer.py`/`engine.py`）、模型/方法实现（`models/*.py`）、网络结构（`utils/inc_net.py`、`convs/`）、配置（`exps/*.json`）。
|
||||
2. **建立"论文概念 ↔ 代码位置"映射**：从 README 的方法/公式描述出发，在源码里定位其实现（函数名/分支/类），每条标注 `文件:函数/行`。
|
||||
3. **画架构 Mermaid 图**：数据流 = 入口 → 训练编排 → 数据加载 → 模型前向 → 损失计算 → 反传；标注关键分叉（如 `--method`/`--mode` 一类开关如何在代码里切换算法变体）。
|
||||
4. **补"想改 X 看哪里"快速定位表**（实战价值，帮接手者秒级定位）。
|
||||
|
||||
### A2 输出模板
|
||||
|
||||
```markdown
|
||||
# 🧬 方法—代码实现剖析：<仓库/论文名>
|
||||
## 一、架构总览（Mermaid） ← 数据流图，标注算法开关分叉
|
||||
## 二、方法—代码映射表 ← ≥5 行：论文概念 / 对应文件:位置 / 一句话作用
|
||||
## 三、核心机制代码定位 ← 论文关键创新点的确切代码段（引用真实片段）
|
||||
## 四、想改 X，看哪里 ← 快速定位表
|
||||
```
|
||||
|
||||
### A2 示例
|
||||
|
||||
完整范例见 [`examples/maintaining-fairness-lkd-cil-anatomy.md`](examples/maintaining-fairness-lkd-cil-anatomy.md)（靶子仓库真实剖析：把论文 inter/intra-class fairness 两个创新点精确定位到 `Zscore()`/`Inverse_Zscore()` 两个函数 + `--method interintra` 分支）。
|
||||
|
||||
---
|
||||
|
||||
## 后续扩展：A3 跨多仓创新点对比 + 研究 Idea 生成
|
||||
|
||||
对多个同主题仓库各跑本 skill 的内涵提取（A1 的"方法与核心创新"段即 A3 的输入单元），再用 gap-analysis/lead-discovery 跨仓合成"创新点对比矩阵 + 共性缺口 + 潜在研究 Idea"。该能力由配套 skill `gitlink-research-idea` 承载（单仓模式 = 基于 A1 内涵生成"局限 + 可拓展 Idea"，作为多仓的降级兜底）。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- ✅ **README 是主信息源**：GitLink 科研仓库的 Abstract/方法/数据/命令几乎都在 README，优先深读 README。
|
||||
- ✅ **成品上传不丢分**：commit 少不影响解读，靠"内容"而非"历史"。
|
||||
- ⚠️ **镜像仓的 count 不可信**：`contributor_users_count`/`issues_count` 等对镜像常为 0，用 `+contributors` 等带归因的命令。
|
||||
- ⚠️ **Git Bash 路径转换**：raw `api` 命令带前导 `/` 的路径参数会被 MSYS 转成 Windows 路径，必须 `MSYS_NO_PATHCONV=1`。
|
||||
- ✅ **报告以中文 Markdown 产出**。
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
# 🧬 方法—代码实现剖析：Maintaining Fairness in LKD for CIL
|
||||
|
||||
> 剖析对象：`gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` ｜ 数据来源：GitLink（gitlink-cli 实时采集）｜ 剖析时间：2026-07-03
|
||||
> 本文档由 `gitlink-research-insight` skill 的 **A2 模式**产出，回答"论文方法如何落到代码、想改某模块该看哪个文件"。所有结论可经 gitlink-cli 复现核查。
|
||||
> 配套：内涵解读见 [`maintaining-fairness-lkd-cil-insight.md`](maintaining-fairness-lkd-cil-insight.md)；复现性体检见 `../../gitlink-research-repro/examples/`。
|
||||
|
||||
---
|
||||
|
||||
## 一、架构总览（Mermaid）
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CLI["main.py<br/>argparse 入口<br/>--config/--method/--dataset/--lambd"] --> TR["trainer.py<br/>train(args)<br/>设 seed/cudnn/设备"]
|
||||
TR --> DM["utils/data_manager.py<br/>增量任务划分<br/>init_cls / increment"]
|
||||
DM --> DAT["utils/data.py<br/>5 数据集<br/>CIFAR/ImageNet/Tiny/Librispeech"]
|
||||
TR --> MODEL["models/<method>.py<br/>如 LwF(BaseLearner)<br/>每基线一个文件"]
|
||||
|
||||
MODEL -->|"task 0"| INIT["_init_train<br/>纯 CE 训练 / loadpre 加载"]
|
||||
MODEL -->|"task ≥ 1"| UPD["_update_representation<br/>CE(新类) + KD(方法分发)"]
|
||||
|
||||
UPD --> NET["utils/inc_net.py<br/>IncrementalNet<br/>update_fc 扩类头"]
|
||||
NET --> CONV["convs/<br/>backbone 矩阵<br/>resnet18/cifar_resnet/..."]
|
||||
UPD --> OLD["self._old_network<br/>冻结的上一任务模型<br/>(after_task)"]
|
||||
|
||||
UPD -->|"--method normal"| K0["普通 KL 蒸馏(_KD_loss)"]
|
||||
UPD -->|"--method KL"| K1["标准化蒸馏 不去偏"]
|
||||
UPD -->|"--method inter"| K2["类间公平<br/>Zscore → KL"]
|
||||
UPD -->|"--method intra"| K3["类内公平<br/>Inverse_Zscore → KL"]
|
||||
UPD -->|"--method interintra ⭐"| K4["核心创新<br/>alpha·KL(Zscore)<br/>+ beta·KL(Inverse_Zscore)"]
|
||||
|
||||
K4 --> LOSS["loss = loss_clf + loss_kd"]
|
||||
LOSS --> OPT["SGD + MultiStepLR 反传"]
|
||||
|
||||
EXP["exps/*.json<br/>7 基线 config<br/>seed/model_name/convnet_type"] -.驱动.-> MODEL
|
||||
```
|
||||
|
||||
> 关键边：**`--method` 一个参数**就在 `_update_representation` 里切换 6+ 种蒸馏策略；核心创新 `interintra` 完全落在该分支内，**不改训练骨架、不加参数**，这就是论文宣称"即插即用"的代码依据。
|
||||
|
||||
---
|
||||
|
||||
## 二、方法—代码映射表
|
||||
|
||||
| # | 论文/方法概念 | 对应文件 : 位置 | 一句话作用 |
|
||||
|---|--------------|-----------------|-----------|
|
||||
| 1 | **类间公平 inter-class fairness**（logit 全类归一化） | `models/lwf.py` → `Zscore(logits)` | 对每个样本在**所有类**维度做 z-score（`(x-mean)/std`，`dim=-1`），消除 logit 量级偏置，让 student 学习类间相对关系而非绝对值 |
|
||||
| 2 | **类内公平 intra-class fairness** | `models/lwf.py` → `Inverse_Zscore(logits)` | 对每个**类**在 batch 维度做 z-score（`dim=0`），压制 overconfident teacher 的类内偏置，保证旧类内部也公平 |
|
||||
| 3 | **标准化知识蒸馏** | `models/lwf.py` → `DistillKL_logit_stand(y_s,y_t,T)` | 对标准化后 logit 做 KL 蒸馏：`KLDivLoss(log_softmax(s/T), softmax(t/T)) * T²` |
|
||||
| 4 | **inter+intra 联合（核心创新）** | `models/lwf.py` → `_update_representation` 的 `elif self.method=="interintra"` 分支 | `loss_kd = alpha·loss_kd1(inter) + beta·loss_kd2(intra)`；`alpha/beta` 由 `--lambd` 派生（`__init__`：`lambd=-1→alpha=2,beta=0` 纯 inter；`lambd=0→` 纯 intra） |
|
||||
| 5 | **新类交叉熵 CE** | `models/lwf.py` → `_update_representation` 中 `loss_clf` | `F.cross_entropy(logits[:, known_classes:], fake_targets)`，**只对新类 logit 切片**做 CE（`fake_targets = targets - known_classes`） |
|
||||
| 6 | **总损失** | `models/lwf.py` → `loss = loss_kd + loss_clf` | KD（旧类关系）+ CE（新类学习）联合优化，正是论文要消解的"KD-CE 冲突"的落点 |
|
||||
| 7 | **增量网络 / 可扩分类头** | `utils/inc_net.py` → `IncrementalNet.update_fc()` + `convs/` | backbone（默认 `resnet18`，由 `exps/*.json` 的 `convnet_type` 选）+ 每任务扩展 FC 类头 |
|
||||
| 8 | **训练编排 / 任务循环** | `trainer.py` + `models/base.py`（`BaseLearner`） | task 0 走 `_init_train`（纯 CE 或 `--loadpre` 加载首阶段权重）；task ≥ 1 走 `_update_representation`（CE+KD） |
|
||||
| 9 | **实验矩阵 / 超参落盘** | `exps/lwf.json` 等 7 个 config | 锁定 `seed:[1993]`、`model_name`、`convnet_type:resnet18`、`memory_size` 等，复现性与消融的单一事实源 |
|
||||
|
||||
> ≥5 组件达标（共 9 项）。每行"论文概念 ↔ 代码位置 ↔ 作用"三栏齐全，可逐行核查。
|
||||
|
||||
---
|
||||
|
||||
## 三、核心机制代码定位（论文两创新点的确切代码）
|
||||
|
||||
**创新点一 · 类间公平** —— `Zscore()`（`models/lwf.py` 末尾工具函数区）：
|
||||
```python
|
||||
def Zscore(logits):
|
||||
mean = logits.mean(dim=-1, keepdims=True) # 每个样本、跨所有类求均值
|
||||
stdv = logits.std(dim=-1, keepdims=True)
|
||||
return (logits - mean) / (1e-7 + stdv) # 全类归一化 → 消除 recency bias
|
||||
```
|
||||
|
||||
**创新点二 · 类内公平** —— `Inverse_Zscore()`：
|
||||
```python
|
||||
def Inverse_Zscore(logits):
|
||||
mean = logits.mean(dim=0, keepdims=True) # 每个类、跨 batch 求均值
|
||||
stdv = logits.std(dim=0, keepdims=True)
|
||||
return (logits - mean) / (1e-7 + stdv) # 类内归一化 → 压制 overconfident teacher
|
||||
```
|
||||
|
||||
**两者联合** —— `--method interintra` 分支（`_update_representation`）：
|
||||
```python
|
||||
elif self.method == "interintra":
|
||||
loss_kd1 = DistillKL_logit_stand(Zscore(logits)[:, :self._known_classes], Zscore(old_logits), T) # 类间
|
||||
loss_kd2 = DistillKL_logit_stand(Zscore(logits.t())[:self._known_classes, :], Zscore(old_logits.t()), T) # 类内(转置→dim=0)
|
||||
loss_kd = self.alpha * loss_kd1 + self.beta * loss_kd2 # alpha/beta 由 --lambd 派生
|
||||
```
|
||||
|
||||
> 这三段就是论文 Figure/公式的代码实体。**改公平机制只需动这三个函数 + interintra 分支**，无需触碰训练循环——这正是"即插即用、零额外训练成本"的代码级证据。
|
||||
|
||||
---
|
||||
|
||||
## 四、想改 X，看哪里（快速定位表）
|
||||
|
||||
| 我想做的事 | 第一站文件 | 备注 |
|
||||
|-----------|-----------|------|
|
||||
| 换/加蒸馏策略（新 `--method`） | `models/lwf.py` → `_update_representation` 的方法分发 `if/elif` 链 | 加一个 `elif self.method=="你的方法"` 即可 |
|
||||
| 调 inter/intra 权重 | `main.py --lambd`（→ `__init__` 的 `alpha/beta` 公式） | `lambd=-1` 纯 inter，`lambd=0` 纯 intra，正值联合 |
|
||||
| 换 backbone | `exps/*.json` 的 `convnet_type` + `convs/` | 支持 resnet/cifar_resnet/memo_*/ucir_*/resnet_cbam 等 |
|
||||
| 加新数据集 | `utils/data.py` 新增 `iData` 子类 + `download_data` | 设 `use_path` 决定自动下载或手填路径 |
|
||||
| 调 KD 温度/epoch/lr | `models/lwf.py` 模块级常量（`T=2`、`epochs=100`、`lrate=0.1`…） | **硬编码在模块顶部**，非 config 驱动（A2 发现的工程债） |
|
||||
| 改增量划分 | `main.py --init_cls/--increment` 或 `exps/*.json` | 决定任务数与每段类数 |
|
||||
|
||||
---
|
||||
|
||||
## 附：本剖析采集命令（可复现）
|
||||
|
||||
```bash
|
||||
OWNER=gaozijian19; REPO=Maintaining-Fairness-in-LKD-for-CIL
|
||||
gitlink-cli repo +tree --owner $OWNER --repo $REPO --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=models/lwf.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=main.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=trainer.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=exps/lwf.json&ref=master" --format json
|
||||
# models/、convs/、utils/ 目录结构同法用 sub_entries(filepath=<dir>) 列出
|
||||
```
|
||||
|
|
@ -0,0 +1,97 @@
|
|||
# 🔬 科研内涵解读报告：Maintaining Fairness in Logit-based Knowledge Distillation for Class-Incremental Learning
|
||||
|
||||
> 解读对象：`gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` ｜ 数据来源：GitLink（gitlink-cli 实时采集）｜ 解读时间：2026-07-03
|
||||
> 本报告由 `gitlink-research-insight` skill 流程产出，所有结论可经 gitlink-cli 命令复现核查。
|
||||
|
||||
---
|
||||
|
||||
## 一、仓库画像
|
||||
|
||||
| 项 | 内容 | 来源 |
|
||||
|----|------|------|
|
||||
| 仓库 | `gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` | `repo +info` |
|
||||
| 镜像 | ✅ GitHub 镜像，原址 `Zi-Jian-Gao/Maintaining-Fairness-in-LKD-for-CIL` | `repo +info` → `mirror_url` |
|
||||
| 论文 / 会议 | AAAI 2025（Gao, Han, Zhang, Xu, Zhou, Mao, Dou, Wang） | README Citation |
|
||||
| 规模 / 语言 | 3.1 MB ｜ Python 95.4% / Shell 4.6% | `repo +info` / `repo +languages` |
|
||||
| 贡献者 | 2 人（主力 Zijian Gao，66.7% / 2 commits；另有 1 人 33.3% / 1 commit，含主体 +8704 行的初次上传） | `repo +contributors` / `repo +code-stats` |
|
||||
| 上传形态 | **成品上传**：仅 3 个 commit，全部在 2024-12-11 同一天（`first commit → Update ReadMe.md → Update samples.sh`） | `git log`（克隆核查） |
|
||||
|
||||
> 判定：典型"论文发表后整体上传"的科研代码仓库——**无真实探索/迭代历史**，解读须基于内容而非 commit 演进。
|
||||
|
||||
---
|
||||
|
||||
## 二、研究问题与动机
|
||||
|
||||
**问题域：Class-Incremental Learning (CIL，类增量学习) 中的灾难性遗忘。**
|
||||
|
||||
- **动机**（README Abstract）：logit-based 知识蒸馏（KD）常用于缓解 CIL 中的遗忘，但 KD 要求 student 与 teacher 的 logit 严格匹配，这与交叉熵（CE）学习新类的目标**相互冲突**，导致显著的 **recency bias（新类偏置）**——新类的 logit 普遍偏大，旧类被压制。
|
||||
- **被忽视的局限**：作者通过实证分析指出，既有 KD-based 方法的这一冲突长期被忽视。
|
||||
|
||||
---
|
||||
|
||||
## 三、方法与核心创新
|
||||
|
||||
1. **创新点一 · 类间公平（inter-class fairness）**：一个 **plug-and-play 预处理**模块——在蒸馏前，对 student 与 teacher 的 logit 在**所有类（不止旧类）**上做归一化。这让 student 同时关注新旧类，从 teacher 捕获内在的类间关系，**从根上消解 KD 与 CE 的冲突**。
|
||||
- → 代码位置：训练/蒸馏流程入口 `main.py`，方法通过 `--method` 选择（README 示例见 `interintra`）。
|
||||
2. **创新点二 · 类内公平（intra-class fairness）**：针对 **overconfident teacher 阻碍 dark knowledge（类间关系）传递**的问题，扩展方法以捕获**不同实例间的类内关系**，保证旧类**内部**也公平。
|
||||
- → 代码位置：`models/`（`base.py` 及具体方法实现）、`convs/`（含 `memo_*`、`ucir_*` 等多 backbone）。
|
||||
3. **工程特性**：**无额外训练成本**；可与现有任意 logit-based KD 方法**即插即用集成**，在多个 CIL benchmark 上稳定提升。
|
||||
|
||||
---
|
||||
|
||||
## 四、对比基线与实验矩阵
|
||||
|
||||
从 `exps/` 目录的配置文件名提取实验矩阵（`repo +tree` 核查）：
|
||||
|
||||
| 基线/方法 | 配置文件 | 角色 |
|
||||
|-----------|----------|------|
|
||||
| LwF | `exps/lwf.json` | 经典 KD 基线（README 示例即用 lwf） |
|
||||
| BiC | `exps/bic.json` | CIL 基线 |
|
||||
| DER | `exps/der.json` | CIL 基线（README 提到 DER++ 的 `--alpha`） |
|
||||
| iCaRL | `exps/icarl.json` | CIL 基线 |
|
||||
| PODNet | `exps/podnet.json` | CIL 基线 |
|
||||
| Replay | `exps/replay.json` | CIL 基线 |
|
||||
| WA | `exps/wa.json` | CIL 基线 |
|
||||
|
||||
- **关系**：本方法**不是又一个并列基线**，而是可与上述 logit-KD 方法**叠加集成**的预处理增强（README 明确 "integrates seamlessly with existing logit-based KD approaches"）。
|
||||
- **Backbone 矩阵**（`convs/`）：`resnet`、`cifar_resnet`、`memo_resnet`、`ucir_resnet`、`modified_represnet`、`resnet_cbam`、`linears` 等 → 支持多网络结构对比。
|
||||
|
||||
---
|
||||
|
||||
## 五、数据集与运行入口
|
||||
|
||||
- **支持数据集**（README）：`Cifar10`、`Cifar100`、`Imagenet-Subset`、`Tiny-Imagenet200`、`Librispeech100`（Audio，跨模态）。
|
||||
- **运行命令**（README 真实示例）：
|
||||
```bash
|
||||
python main.py --config './exps/lwf.json' --init_cls 20 --increment 20 \
|
||||
--device "0" --method "interintra" --dataset "cifar100" --loadpre 0
|
||||
```
|
||||
关键参数：`--config`（实验设置）、`--method`（蒸馏方法，含 `normal`/`KL`/`interintra`）、`--dataset`、`--init_cls`/`--increment`（增量设置）、`--lambd`/`--alpha`（损失权重）。更多见 `samples.sh`。
|
||||
- **数据/权重获取**：数据集路径需在 `utils/data.py` **手填**；`--loadpre` 控制是否加载预训练权重（README 未给出公开权重下载链接）。
|
||||
|
||||
---
|
||||
|
||||
## 六、复现性速览 + 一句话评价
|
||||
|
||||
| 维度 | 状态 | 依据 |
|
||||
|------|------|------|
|
||||
| 环境锁定 | ✅ | `requirements.txt` 为 conda 全量 pin 环境（含 `pyc` 版本） |
|
||||
| 数据可得 | ⚠️ | 公开数据集，但需手填本地路径（`utils/data.py`） |
|
||||
| 运行入口 | ✅ | 明确 `main.py --config` 入口 + `samples.sh` 样例 |
|
||||
| 预训练权重 | ⚠️ | 有 `--loadpre` 开关，但未提供下载链接说明 |
|
||||
| 迭代记录 | ❌ | 成品上传（3 commit 同日），无探索/调试过程可追溯 |
|
||||
|
||||
**一句话评价**：一个聚焦 **CIL 中 KD 公平性**的轻量、**即插即用**改进——以 logit 全类归一化消解 KD-CE 冲突，工程整洁、基线齐全（7 个 CIL 方法）、复现性中上；非常适合作为 CIL/KD 方向的入门与扩展基线，也便于在其上做"公平性进一步放松/跨模态迁移"等后续研究。
|
||||
|
||||
---
|
||||
|
||||
## 附：本报告采集命令（可复现）
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
gitlink-cli repo +readme --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
gitlink-cli repo +tree --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
gitlink-cli repo +languages --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
gitlink-cli repo +contributors --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
gitlink-cli repo +code-stats --owner gaozijian19 --repo Maintaining-Fairness-in-LKD-for-CIL --format json
|
||||
```
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
---
|
||||
name: gitlink-research-repro
|
||||
version: 0.1.0
|
||||
description: "科研仓库复现性体检：扫描一个科研/论文代码仓库，判断『这套实验代码能否被他人复现、卡在哪』——逐维度给出 ✅/⚠️/❌ 与可执行修复建议。当用户问『这个仓库能复现吗』『复现这个实验要准备什么』『这份论文代码卡在哪』『可复现性怎么样』时触发。区别于许可证/依赖合规（gitlink-compliance），本 skill 专查『实验能否跑通、结果能否重现』。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-research-repro（科研仓库复现性体检）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
## 何时使用 / 何时跳过
|
||||
|
||||
**使用本 skill（实验复现性体检）：**
|
||||
- 用户说"这个仓库能复现吗""复现这个实验要准备什么""这份论文代码卡在哪""可复现性如何"
|
||||
- 用户想决定是否值得投入算力/时间去复现某科研仓库的实验
|
||||
|
||||
**跳过本 skill（改用其他 skill）：**
|
||||
- 想读懂"这仓库做了什么/方法是什么" → `gitlink-research-insight`（内涵解读）
|
||||
- 只查许可证 / 依赖合规（LICENSE、开源协议、依赖漏洞） → `gitlink-compliance` / `gitlink-license-compliance`
|
||||
- 想生成研究 Idea → `gitlink-research-idea`
|
||||
|
||||
> **与 `gitlink-compliance` 的本质区别（边界自证）**：合规 skill 查"法律/安全"——LICENSE 是否存在、依赖有无已知漏洞；本 skill 查"科学/工程"——环境能否装上、数据能否拿到、入口能否跑通、随机性是否受控、结果能否重现。一个问"能不能合法用"，一个问"能不能复现出论文数字"。
|
||||
|
||||
## ⚠️ 现实约束（驱动设计的前提）
|
||||
|
||||
GitLink 上的科研仓库**绝大多数是"成品上传"**——论文发表后整体上传，commit 少（常见 1–5 个）、**不含真实调试/探索过程**（实测靶子仓库仅 3 个 commit 同日）。
|
||||
|
||||
→ 因此本 skill **不依赖 commit/CI 历史**（多数仓库根本没有 CI），而是**直接读取仓库内容**（依赖清单、入口脚本、数据加载、配置文件、训练循环里的随机性控制）做静态体检。把"无 CI"本身也作为一条体检结论（❌ 自动化测试缺失）。
|
||||
|
||||
## 数据采集（只用这些 gitlink-cli 命令）
|
||||
|
||||
```bash
|
||||
# 0) 前置：认证
|
||||
gitlink-cli auth status
|
||||
|
||||
# 1) 元信息（默认分支 / 规模 / 是否镜像）
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 2) README —— 运行说明 / 数据获取 / 预训练权重链接多在此
|
||||
gitlink-cli repo +readme --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 3) 文件结构 —— 定位依赖清单 / 入口 / 配置 / 数据加载文件
|
||||
gitlink-cli repo +tree --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 4)【关键】读取任意文件内容 —— 用 sub_entries 端点（不是 /contents/）
|
||||
# Git Bash 下必须加 MSYS_NO_PATHCONV=1，否则前导 / 被转成 Windows 路径 → 404 → SPA HTML
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/<owner>/<repo>/sub_entries" \
|
||||
--query "filepath=<path>&ref=master" --format json
|
||||
# 文件正文在返回的 data.entries.content（已解码纯文本）
|
||||
```
|
||||
|
||||
**按需读取的"复现性证据文件"清单**（先看 tree，存在哪个读哪个）：
|
||||
|
||||
| 证据文件 | 回答的体检维度 |
|
||||
|----------|----------------|
|
||||
| `requirements.txt` / `environment.yml` / `Pipfile.lock` / `poetry.lock` | 环境锁定、依赖版本、是否可一键安装 |
|
||||
| `main.py` / `train.py` / `run.py`（入口） | 运行入口是否清晰、参数是否暴露 |
|
||||
| `Makefile` / `Justfile` / `run.sh` / `samples.sh` | 是否有"一键复现"脚本 |
|
||||
| `Dockerfile` / `.devcontainer/` | 环境是否容器化（复现性最强证据） |
|
||||
| `utils/data.py` / `data_loader.py` / `datasets/` | 数据集获取方式（自动下载 vs 手填路径） |
|
||||
| `exps/*.json` / `configs/*.yaml`（实验配置） | 随机种子、超参、模型名是否落盘 |
|
||||
| `trainer.py` / `engine.py` / 训练循环 | 随机性控制（seed / cudnn.deterministic） |
|
||||
| `.github/workflows/` / `tests/` | 是否有自动化测试/CI 兜底 |
|
||||
|
||||
> **镜像仓库注意**：`repo +info` 的 `contributor_users_count` 对 GitHub 镜像恒为 0，无关复现性体检，可忽略。
|
||||
> **读文件路径**：`/raw/` 端点对 API token 常返回 403，**用 `/sub_entries`**（所有现有 skill 的统一做法）。
|
||||
|
||||
## 体检流程
|
||||
|
||||
### Step 1：采集（执行上述命令；先 `+info`/`+tree` 定位，再 `sub_entries` 逐个读证据文件）
|
||||
|
||||
### Step 2：逐维度判定（每维给 ✅ / ⚠️ / ❌ + 一句依据）
|
||||
|
||||
按下表 **8 个维度**（≥6 即达标）逐项检查。每项必须**引用具体文件/行/字段**作依据，可核查：
|
||||
|
||||
| # | 维度 | 判 ✅ 的条件 | 判 ❌/⚠️ 的典型情形 |
|
||||
|---|------|-------------|---------------------|
|
||||
| 1 | **环境锁定** | 有锁定文件且全量 pin 版本 | 仅 `requirements.txt` 无版本；无任何锁定文件 |
|
||||
| 2 | **可一键安装** | 锁定文件能被标准工具直接消费（pip/env.yml/Docker） | 是 conda `--file` 导出却命名 `requirements.txt`（pip 装不了）；缺 python 版本 |
|
||||
| 3 | **运行入口** | 有明确 `main.py`/`train.py` + 参数说明 | 无入口脚本；参数全靠硬编码；README 无运行命令 |
|
||||
| 4 | **数据集获取** | 数据自动下载或有明确下载脚本+路径配置 | 需手填本地绝对路径；私有数据无获取说明 |
|
||||
| 5 | **随机性受控** | config 有 seed + 训练循环设 `cudnn.deterministic=True` | 无 seed；seed 未传到训练；未关 cudnn.benchmark |
|
||||
| 6 | **预训练权重** | 提供 checkpoint 下载链接或 `--loadpre=0` 即可跑 | 有 `--loadpre` 开关却无下载链接；强依赖未公开权重 |
|
||||
| 7 | **硬件/兼容** | 有 CPU 回退或声明最低算力；依赖栈非远古 | 强制特定 GPU 无回退；torch 为多年前旧版（装不上新卡） |
|
||||
| 8 | **自动化测试** | 有 `tests/` 或 CI workflow | 无任何测试 / 无 CI（成品仓库常见） |
|
||||
|
||||
> 维度可按仓库语言增减（如 Go 仓库看 `go.mod`+`go.sum`，Node 看 `package-lock.json`），但**不少于 6 维**，且必须覆盖：环境、数据、入口、随机性、权重。
|
||||
|
||||
### Step 3：给修复建议（每个 ⚠️/❌ 都要可执行）
|
||||
|
||||
对每个未达标项，给一条**具体、可粘贴**的修复建议（如"补一个 `environment.yml`""在 README 加 `wget <权重链接>`""把 `torch.manual_seed(1)` 改成 `torch.manual_seed(args['seed'])`"）。
|
||||
|
||||
### Step 4：生成中文「复现性体检报告」（按下述模板，Write 工具产出 Markdown）
|
||||
|
||||
## 输出模板：复现性体检报告
|
||||
|
||||
```markdown
|
||||
# 🔧 复现性体检报告：<仓库标题/论文名>
|
||||
|
||||
> 体检对象：<owner>/<repo> ｜ 数据来源：GitLink（gitlink-cli 实时采集） ｜ 体检时间：{{date}}
|
||||
> 结论先行：**复现难度 = 低 / 中 / 高**（一句话：能不能复现、卡点在哪、值不值得投入）
|
||||
|
||||
## 一、体检总表（8 维度）
|
||||
| # | 维度 | 状态 | 一句依据（带文件来源） |
|
||||
|---|------|------|------------------------|
|
||||
| 1 | 环境锁定 | ✅/⚠️/❌ | …（如 `requirements.txt` 56 包全 pin） |
|
||||
| 2 | 可一键安装 | ✅/⚠️/❌ | … |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
**总览**：✅ ×n ⚠️ ×n ❌ ×n → 复现难度评级 + 理由
|
||||
|
||||
## 二、复现路径（按这个顺序操作即可复现）
|
||||
1. 环境准备：…（具体命令）
|
||||
2. 数据准备：…
|
||||
3. 运行：…（从 README/samples.sh 提取的真实命令）
|
||||
4. 预期产出：…
|
||||
|
||||
## 三、卡点与修复建议（逐条对应 ⚠️/❌）
|
||||
| 卡点 | 现状（依据） | 修复建议（可执行） | 严重度 |
|
||||
|------|--------------|---------------------|--------|
|
||||
| … | … | … | 阻断/影响精度/仅整洁 |
|
||||
|
||||
## 四、一句话评价
|
||||
（这套实验代码复现性整体如何、最该先补什么、适合谁复现）
|
||||
```
|
||||
|
||||
> **溯源要求**：每条 ✅/⚠️/❌ 必须引用具体文件/字段/行，可核查。
|
||||
> **边界声明**：本报告**不评判 LICENSE 合规**（那是 `gitlink-compliance` 的职责）；如发现无 LICENSE，仅提示"请交合规 skill 处理"，不计入复现性评分。
|
||||
|
||||
## 示例
|
||||
|
||||
完整范例见 [`examples/maintaining-fairness-lkd-cil-repro.md`](examples/maintaining-fairness-lkd-cil-repro.md)（靶子仓库 `gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` 的真实体检，含 conda --file 误命名、seed 半硬编码等真实卡点）。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- ✅ **sub_entries 是读文件正解**：`/raw/` 对 token 常 403、`/contents/` 在 GitLink 不存在；统一用 `/sub_entries?filepath=<path>&ref=<branch>`，正文在 `data.entries.content`。
|
||||
- ✅ **静态体检为主**：成品仓库无 CI 历史，靠读"依赖/入口/数据/配置/训练循环"做静态判定，不依赖 commit。
|
||||
- ⚠️ **Git Bash 路径转换**：raw `api` 带前导 `/` 的参数会被 MSYS 转成 Windows 路径，必须 `MSYS_NO_PATHCONV=1`。
|
||||
- ✅ **每条结论带文件来源**，修复建议要具体到可粘贴的命令/代码改动。
|
||||
- ✅ **报告以中文 Markdown 产出**。
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
# 🔧 复现性体检报告：Maintaining Fairness in Logit-based Knowledge Distillation for Class-Incremental Learning
|
||||
|
||||
> 体检对象：`gaozijian19/Maintaining-Fairness-in-LKD-for-CIL` ｜ 数据来源：GitLink（gitlink-cli 实时采集）｜ 体检时间：2026-07-03
|
||||
> 本报告由 `gitlink-research-repro` skill 流程产出，所有结论可经 gitlink-cli 命令复现核查。
|
||||
>
|
||||
> **结论先行：复现难度 = 低偏中。** 主路径（CIFAR-100 + interintra 方法）能跑通——入口清晰、依赖全 pin、有 seed 与 cudnn 确定性控制、CIFAR 自动下载、还带 CPU 回退；主要卡点是依赖栈偏旧（torch 1.8.1+cu111，2021 年）、`requirements.txt` 实为 conda 导出却按 pip 命名（直接 `pip install -r` 会失败）、数据加载器初始化 seed 半硬编码、无任何测试/CI。**值得投入复现**，按本报告第二节操作即可。
|
||||
|
||||
---
|
||||
|
||||
## 一、体检总表（8 维度）
|
||||
|
||||
| # | 维度 | 状态 | 一句依据（带文件来源） |
|
||||
|---|------|------|------------------------|
|
||||
| 1 | 环境锁定 | ✅ | `requirements.txt` 为 conda 全量导出，56 个包逐个 pin（`python=3.8.20`、`numpy=1.24.4`、`scipy=1.10.1`…） |
|
||||
| 2 | 可一键安装 | ⚠️ | 同文件**实为 conda `--file` 格式**（`name=version=build`，如 `torch=1.8.1+cu111=pypi_0`），文件头自注 `conda create --name <env> --file <this file>`；**命名 `requirements.txt` 易被误用 `pip install -r`，后者会失败** |
|
||||
| 3 | 运行入口 | ✅ | `main.py` 为干净 argparse 入口 → `trainer.train(args)`；README 给出完整运行命令；`samples.sh` 提供大量样例（**但整文件每行皆被 `#` 注释，是"菜单"非可执行脚本**） |
|
||||
| 4 | 数据集获取 | ⚠️ | `utils/data.py`：CIFAR-10/100 走 `datasets.cifar.CIFAR100("./data", download=True)` **自动下载** ✅；但 ImageNet-Subset / Tiny-ImageNet / Librispeech 为 `use_path=True`/torchaudio，**需手动准备并填写路径**；无统一 `--datapath` 配置项 |
|
||||
| 5 | 随机性受控 | ✅（带小瑕疵） | `exps/lwf.json` 有 `"seed": [1993]`；`trainer.py` 设 `cudnn.deterministic=True`、`benchmark=False` ✅。**瑕疵**：`trainer.py:170-172` 数据加载器初始化处 `torch.manual_seed(1)` 为**硬编码**，未取 `args["seed"]`，与 config 的 1993 不一致（见第三节） |
|
||||
| 6 | 预训练权重 | ⚠️ | `main.py` 有 `--loadpre`(默认 0) 与 `--path`(默认 `temp.pth`) 开关；README 未提供任何 checkpoint 下载链接。**默认 `--loadpre 0` 可不依赖权重跑通**，故非阻断 |
|
||||
| 7 | 硬件 / 兼容 | ⚠️ | `trainer.py:159-160` **有 CPU 回退**（`device_type == -1 → torch.device("cpu")`）✅；但依赖 `torch=1.8.1+cu111`（2021-03），**在新 CUDA driver / 新架构 GPU（如 40 系）上直装易失败**，需借旧镜像或源码编译 |
|
||||
| 8 | 自动化测试 | ❌ | 无 `tests/`、无 `pytest.ini`、无 `.github/workflows/`、无 `Makefile`；成品上传（3 commit 同日），无 CI 兜底，复现正确性只能靠人工核对 |
|
||||
|
||||
**总览**：✅ ×3 ｜ ⚠️ ×4 ｜ ❌ ×1 → **复现难度：低偏中**。无阻断项（最大风险是旧版 torch 的安装兼容，而非代码本身）。
|
||||
|
||||
---
|
||||
|
||||
## 二、复现路径（按此顺序操作即可复现 CIFAR-100 主实验）
|
||||
|
||||
1. **环境准备**（用 conda，不要用 pip）：
|
||||
```bash
|
||||
# 正确方式：按文件头注释，用 conda --file 消费
|
||||
conda create --name fairlkd --file requirements.txt
|
||||
conda activate fairlkd
|
||||
# 若新机器装不上 torch=1.8.1+cu111，退而求其次：
|
||||
# conda create -n fairlkd python=3.8.20 && conda activate fairlkd
|
||||
# pip install torch==1.8.1+cu111 torchvision==0.9.1+cu111 \
|
||||
# -f https://download.pytorch.org/whl/torch_stable.html
|
||||
# 再按 requirements.txt 补 numpy==1.24.4 scipy==1.10.1 pillow==10.4.0 等
|
||||
```
|
||||
2. **数据准备**：CIFAR-100 首次运行时自动下载到 `./data`（无需操作）；若跑 ImageNet-Subset / Tiny-ImageNet / Librispeech，需自备数据并按 `utils/data.py` 中对应类的路径约定放置。
|
||||
3. **运行**（README 真实命令，等价于 `samples.sh` 中任一 interintra 行去掉前导 `#`）：
|
||||
```bash
|
||||
python main.py --config './exps/lwf.json' --init_cls 20 --increment 20 \
|
||||
--device "0" --method "interintra" --dataset "cifar100" --loadpre 0
|
||||
# 无 GPU 时改 --device "-1" 走 CPU（trainer.py:159-160）
|
||||
```
|
||||
4. **预期产出**：训练日志与各阶段精度（`prefix=reproduce`，见 `exps/lwf.json`），可与论文 Table 对比。
|
||||
|
||||
---
|
||||
|
||||
## 三、卡点与修复建议（逐条对应 ⚠️/❌）
|
||||
|
||||
| 卡点 | 现状（依据） | 修复建议（可执行） | 严重度 |
|
||||
|------|--------------|---------------------|--------|
|
||||
| 依赖清单命名误导 | `requirements.txt` 实为 conda `--file` 格式，`pip install -r` 失败（`requirements.txt` 文件头 + `torch=1.8.1+cu111=pypi_0` 行） | 改名 `environment.txt` 或补一份真正的 `environment.yml`（`conda env export -f environment.yml`）；README 明确写"用 `conda create --file`，勿用 pip" | 影响首次安装 |
|
||||
| 数据集路径分散 | ImageNet/Tiny/Librispeech 需手动准备，路径散落在 `utils/data.py` 各类里，无统一配置（`utils/data.py`） | 加一个 `--datapath` 全局参数，或在 `exps/*.json` 增 `data_root` 字段，`utils/data.py` 统一读取 | 影响非 CIFAR 实验 |
|
||||
| seed 半硬编码 | `trainer.py:170-172` 数据加载器初始化用字面量 `torch.manual_seed(1)`，未用 `args["seed"]`(config 为 1993)；主循环 seed 走 config 但数据侧不一致 | 把 `1` 改为 `args["seed"]`：`torch.manual_seed(args["seed"])`（含 `cuda.manual_seed_all(args["seed"])`） | 影响严格可复现 |
|
||||
| 预训练权重无链接 | `--loadpre` 开关存在但 README 无 checkpoint 下载地址（`main.py` 默认 `--loadpre 0`） | 默认路径不阻断；若作者希望支持 phase-1 续训，在 README 补 checkpoint 下载链接与 `--path` 用法 | 仅整洁（非阻断） |
|
||||
| 旧版依赖栈 | `torch=1.8.1+cu111`(2021-03) 在新 CUDA/新 GPU 上难直装（`requirements.txt`） | 提供一份现代版可选依赖（如 `torch>=2.0`）或在 README 列出已知可用的 docker/镜像；说明最低算力 | 影响新机器安装 |
|
||||
| 无自动化测试 | 无 `tests/`/CI/`Makefile`（`+tree` 核查） | 至少补一个 smoke test：固定 seed 跑 1 个 epoch 的小规模 CIFAR-10，断言精度 > 随机基线，放 `.github/workflows/test.yml` | 影响长期可信 |
|
||||
|
||||
---
|
||||
|
||||
## 四、一句话评价
|
||||
|
||||
工程整洁度中上的科研仓库：**入口、配置、seed、确定性控制、CPU 回退俱全**，CIFAR 主路径基本"装好环境就能跑"；真实卡点集中在**依赖清单的 conda/pip 命名误导**与**旧版 torch 的安装兼容**，都是"半天内可补"的工程债，不涉及算法正确性。适合作为 CIL/KD 方向的复现与扩展起点；建议作者至少补一份 `environment.yml` 和一个 smoke test，即可把复现难度从中压到低。
|
||||
|
||||
---
|
||||
|
||||
## 附：本报告采集命令（可复现）
|
||||
|
||||
```bash
|
||||
OWNER=gaozijian19
|
||||
REPO=Maintaining-Fairness-in-LKD-for-CIL
|
||||
|
||||
# 元信息 / README / 文件结构
|
||||
gitlink-cli repo +info --owner $OWNER --repo $REPO --format json
|
||||
gitlink-cli repo +readme --owner $OWNER --repo $REPO --format json
|
||||
gitlink-cli repo +tree --owner $OWNER --repo $REPO --format json
|
||||
|
||||
# 读取复现性证据文件（sub_entries，正文在 data.entries.content）
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=requirements.txt&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=main.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=trainer.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=utils/data.py&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=exps/lwf.json&ref=master" --format json
|
||||
MSYS_NO_PATHCONV=1 gitlink-cli api GET "/$OWNER/$REPO/sub_entries" --query "filepath=samples.sh&ref=master" --format json
|
||||
```
|
||||
Loading…
Reference in New Issue