# Scholar-3：面向 Claude Code / Codex 的 OPSX 风格科研工作流

Scholar-3 是一个**严格、规范驱动**的科研工作流，目标是让 agentic coding 工具真正按“工件（artifact）+ 依赖（DAG）+ 审计（verify）”推进科研，而不是靠感觉写论文。

它强制：
- **一个全局 Idea Spec**（单文件 formulation + protocol，可冻结）
- 多个 **分阶段 Proposal**（plan → tasks → report → verify）
- **Evidence Ledger**（论文 Claim 必须绑定证据指针）
- **不编造**引用与实验结果

## 工作流

```text
/discover  ->  Idea Spec（draft） -> freeze ->  多个 Proposal（P01,P02,...）
                     |                               |
                     |（amendment gate）             v
                     +------------------------ /verify 决策
/proposal -> /apply -> /verify
                   \-> /paper
```

## 产物路径（在你的项目里生成）

Idea：
- `research/idea.md`：唯一的研究真相来源（formulation、H/F/C IDs、评测协议）
- `research/idea.meta.yaml`：状态机（draft/frozen）、版本号、计数器
- `research/evidence-ledger.md`：Claim→Evidence→Pointer 账本

Proposals：
- `research/proposals/Pxx-*/proposal.md`
- `research/proposals/Pxx-*/experiment-plan.md`
- `research/proposals/Pxx-*/tasks.md`
- `research/proposals/Pxx-*/experiment-report.md`
- `research/proposals/Pxx-*/verify.md`

Amendments：
- `research/idea-amendments/Axx-*.md`

Paper：
- `research/paper/claim-evidence-map.md`
- `research/paper/manuscript.md`
- `research/paper/rebuttal.md`

## 命令

- `/discover`：创建/更新 idea spec，初始化 ledger，准备 freeze
- `/discover`：按 Discover v2 执行（diverge → challenge → converge），再进入 proposal
- `/proposal`：创建/选择 proposal，生成 proposal + plan + tasks
- `/apply`：按 tasks 逐条执行（checkbox 追踪）
- `/verify`：证伪 + 可复现 + 证据账本审计，给出下一步决策
- `/paper`：只用 ledger 中 `verified` 的主张写论文
- 说明：`/experiment` 作为兼容别名保留（后续将废弃）

## Discover v2（先发散再收敛）

`/discover` 现在默认包含 ideation 闸门：
- Diverge：至少记录 3 个候选方向
- Challenge：显式写出假设、失败模式与风险
- Converge：收敛为单一主线并锁定 H/F/C + protocol
- Handoff：生成 Proposal Handoff Capsule，供 `/proposal` 直接消费

这样可以在保留 Scholar-3 证据链约束的同时，显著提升 idea 质量和交接效率。

## 迁移（旧路径 → vNext）

如果你之前使用 Scholar-3 v1：
- `idea-proposal.md` → `research/idea.md` + `research/idea.meta.yaml`
- `experiment-report.md` → `research/proposals/Pxx-*/experiment-report.md`
- `manuscript.md` → `research/paper/manuscript.md`
- `rebuttal.md` → `research/paper/rebuttal.md`

## 安装

### NPM（推荐）

```bash
npm i -g scholar3
scholar3 init
```

或（不全局安装）：

```bash
npx scholar3 init
```

环境要求：
- Node.js `>=20.19.0`

安装后你会得到（命令做了 namespace，避免冲突）：
- Claude Code：
  - `/scholar3:discover`
  - `/scholar3:proposal`
  - `/scholar3:apply`
  - `/scholar3:verify`
  - `/scholar3:paper`
- Codex：
  - `/scholar3-discover`
  - `/scholar3-proposal`
  - `/scholar3-apply`
  - `/scholar3-verify`
  - `/scholar3-paper`

项目脚手架（仅 spec，在当前项目目录）：

```bash
scholar3 project-init
```

查看状态 / 卸载：

```bash
scholar3 status
scholar3 uninstall
```

常用覆盖参数：
- Codex home：`$CODEX_HOME` 或 `--codex-home <path>`
- Claude home：`--claude-home <path>`
- 非交互：`--tools claude,codex`

### Git Clone

```bash
cd ~/.claude
git clone https://github.com/XiaYiHann/scholar-3.git
```

或手动复制：

```bash
cp -r scholar-3/skills/* ~/.claude/skills/
cp -r scholar-3/commands/* ~/.claude/commands/
```

（该方式会安装未命名空间的命令，例如 `/discover`。）

## Scholar-3 spec config/schema（可选）

仓库内包含 `scholar/`，作为可检查的“总领配置 + 工件 DAG + 模板集合”。
你可以把 `scholar/` 复制到自己的科研项目根目录，用它携带这套工作流规范。

## 许可证

MIT