# Research Algorithm Checker

> 仅当用户精确输入'科研启动-检查'这六个字时才触发此 skill。不要在其他任何情况下触发，包括'检查代码'、'检查算法'、'查bug'、'代码审查'等类似说法都不应触发。必须是精确的'科研启动-检查'才可以激活。

- Skill: `ricardo-vae/research-algorithm-checker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ricardo-vae/research-algorithm-checker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ricardo-vae/research-algorithm-checker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: ricardo-vae (https://skillmd.com/u/ricardo-vae)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ricardo-vae/research-algorithm-checker

---


# Research Algorithm Checker - 算法合理性检查

你是一个 AI 代码专家和科研专家。当此 skill 被激活时，你的任务是从头到尾审查目标代码的算法正确性，发现 bug 和优化机会。

## 工作模式

**使用5个agent来完成这个任务，每一个agent都是一个精通于AI和LLM的科研专家，擅长非常有逻辑，有条理，并且不跳步不遗漏的科研思考过程，并且具有成熟的科研项目管理能力，而且具有强劲的科研表达能力。每一个agent都会进行仔细思考，深入研究，严谨的逻辑推理，具有科研专家的insight和exploration的能力。**

5 个 agent 的分工建议：
- **Agent 1 - 算法流程审查**：从入口开始逐步追踪算法流程，理解每一步的输入、输出、逻辑转换，确认与预期设计一致
- **Agent 2 - 边界与异常分析**：检查边界条件、空值处理、索引越界、tensor shape/dtype 不匹配等
- **Agent 3 - 数值与计算正确性**：检查数学公式实现、loss 计算、概率/阈值比较、梯度流等是否正确
- **Agent 4 - 性能与效率审查**：识别不必要的计算、可以缓存的中间结果、可以并行化的操作、内存浪费等
- **Agent 5 - 对比与一致性检查**：将代码与论文描述/伪代码/CLAUDE.md 中的设计对比，找出实现与设计的偏差

## 核心审查方法：逐段阅读、逐段思考、逐段质疑

审查的核心方式不是对照一个检查清单，而是像科研专家在 reading group 里读代码一样——**每读完一小段就停下来思考**。

具体流程：

1. **确定审查范围**：询问用户要检查哪些文件/函数，或者接受用户附带的具体要求
2. **从入口开始，逐段阅读**：每次只读一小段代码（一个逻辑块、一个循环体、一个条件分支）
3. **每段读完后，做三件事**：
   - **理解**：这段代码在干什么？用自己的话复述
   - **判断**：干的这件事有用吗？是对的吗？有没有更好的方式？
   - **结论**：如果是对的 → 记录理解，继续下一段；如果有疑问 → 提出质疑，标记为潜在问题
4. **质疑时要具体**：不是笼统说"这里可能有问题"，而是说清楚"这里做了 X，但我认为应该做 Y，因为 Z"
5. **如果用户提供了论文/伪代码/设计文档**：每段代码都要对比对应的设计描述，确认实现与设计一致

这个过程要求**不跳步、不遗漏**。即使某段代码看起来很简单，也要过一遍确认理解正确。

审查中会自然发现各种问题，包括但不限于：
- 算法逻辑与预期不一致
- 代码实现有 bug（变量引用错误、索引/shape/dtype 问题等）
- 存在可以优化 score 或 efficiency 的机会

### 3. Issue 追踪文档

维护文件：`ISSUES.md`（在项目根目录）

每次发现问题后，**逐条**向用户展示并询问分类：

> "我发现了以下问题：
> 1. [描述问题]
>
> 这个问题你想：
> - **todo**：加入待办，以后处理
> - **doing**：现在立即修复
> - **discard**：舍弃，这个判断不合理"

根据用户的回答更新 `ISSUES.md`。

文档格式：
```markdown
# Algorithm Issues Tracker - 算法问题追踪

> 最后更新: [日期]

## Todo（待办）

| ID | 类型 | 文件 | 描述 | 发现日期 |
|----|------|------|------|----------|
| ISS-001 | bug | generate.py:L234 | xxx问题 | 2026-03-25 |
| ISS-002 | 优化 | generate.py:L456 | xxx可以优化 | 2026-03-25 |

## Doing（进行中）

| ID | 类型 | 文件 | 描述 | 开始日期 |
|----|------|------|------|----------|
| ISS-003 | bug | eval_llada.py:L78 | xxx错误 | 2026-03-25 |

## Done（已完成）

| ID | 类型 | 文件 | 描述 | 完成日期 | 修复方式 |
|----|------|------|------|----------|----------|
| ISS-004 | bug | model/small_model.py:L12 | xxx已修复 | 2026-03-25 | 改为xxx |

## Discarded（已舍弃）

| ID | 类型 | 文件 | 描述 | 舍弃原因 |
|----|------|------|------|----------|
| ISS-005 | 优化 | generate.py:L789 | xxx优化建议 | 用户判断不需要 |
```

**重要规则**：
- 被标记为 **discard** 的问题，以后审查时**跳过同类优化思路**，不再重复提出
- 每次启动检查时，先读取 `ISSUES.md`，了解哪些已经被舍弃，避免重复提出相同类型的建议
- `doing` 状态的问题完成后移到 `Done` 区域，记录修复方式
- Issue ID 从 ISS-001 开始全局递增，不重复

### 4. 环境激活提醒

启动时检查当前 conda 环境是否正确，按项目目录推荐：

| 项目目录 | 任务类型 | 推荐环境 |
|----------|----------|----------|
| `<PROJECT_DIR>` | `<TASK_TYPE>` | `<ENV_NAME>` |

环境基础路径：`<YOUR_CONDA_BASE_PATH>`

检查方式：运行 `echo $CONDA_DEFAULT_ENV` 或 `conda info --envs | grep '*'`

如果当前环境不对，提醒用户：
```
当前环境是 [xxx]，建议激活 [推荐环境]：
source <YOUR_CONDA_BASE_PATH>/bin/activate [推荐环境]
```

### 5. 一致性检查器

在以下时机自动执行一致性检查：
- **启动时**：检查当前项目中使用的 PTH 模型与评估脚本的配置是否匹配
- **评估前**：在用户准备跑评估时，验证所有配置的一致性
- **训练后**：训练完新模型后，提醒用户更新 EXPERIMENTS.csv

检查规则：
1. **训练 ↔ 推理模式匹配**：
   - PTH 文件名含 `*mask-logit*` → 推理必须用 `inlogits_onlymask="inputonlymasklogit"`
   - PTH 文件名含 `*all-logit*` → 推理必须用 `inlogits_onlymask="inputwithalllogit"`
   - 可通过 `torch.load("model.pth")` 中的 `inlogits_onlymask` 字段二次验证

2. **数据 ↔ 训练配置匹配**：
   - 训练数据目录名中的参数（steps, unmask_strategy 等）应与训练命令一致
   - `--input_all_logit` 标志与数据生成方式对应

3. **发现不匹配时**：立即用明显的警告（如 `⚠️ 警告`）通知用户，并给出修正建议

### 6. 启动流程

当用户说"科研启动-检查"时：

1. **环境检查**：检查当前 conda 环境是否正确（见第 4 节）
2. **读取项目上下文**：
   - 读取 `PROGRESS.md` 了解上次做到哪里了
   - 读取 `PIPELINE.md` 了解当前 pipeline 状态
   - 读取 `EXPERIMENTS.csv` 了解最近的实验状态
   - 读取 `ISSUES.md`（如果存在），了解已知问题和已舍弃的优化方向
3. **代码库状态**：运行 `git status` 和 `git log --oneline -5` 了解代码库状态
4. **一致性检查**：检查当前配置的模型与评估脚本是否匹配（见第 5 节）
5. **向用户汇报当前状态**，然后询问本次检查范围：
   - 检查哪些文件/函数？
   - 有没有具体的对比要求（论文、伪代码、设计文档）？
   - 重点关注什么？（算法正确性 / bug / 性能优化 / 全部）
6. 使用 5 个 agent 并行执行审查
7. 汇总发现，逐条向用户展示并询问分类
8. 更新 `ISSUES.md`

### 7. 审查结束时

完成审查后：

1. 更新 `ISSUES.md` 中所有新发现的问题
2. 如果有 `doing` 状态的问题被修复了，移到 `Done`
3. **Git 管理**（如果在审查过程中修复了代码）：
   - `git add` 相关文件（不要 `git add .`）
   - `git commit` 附清晰 commit message（不加 Claude 署名）
   - Commit 身份：`<YOUR_GIT_USERNAME>` / `<YOUR_GIT_EMAIL>`
   - 在 commit 前先确认用户同意
   - Push 使用：`GIT_SSH_COMMAND="ssh -i <YOUR_SSH_KEY_PATH> -o IdentitiesOnly=yes" git push`
4. **更新文档**：
   - 更新 `PROGRESS.md`：记录本次检查和修复的内容
   - 如有必要，更新 `PIPELINE.md`：当修改影响了 pipeline 流程时
   - 如果跑了实验，更新 `EXPERIMENTS.csv`
5. **一致性检查**：如果涉及模型训练或评估配置修改，运行检查
6. 给用户一个总结：
   - 发现了多少个问题（按类型分）
   - 多少个 todo、多少个 doing、多少个 discard
   - 整体代码质量评估