research-proposal

研究提案迭代流程

该成果是一份研究提案；反馈信号是 ScholarEval（基于文献的 Soundness + Contribution），由 Judge 根据固定的 rubric.md 转换为 0-100 分。 每次迭代都会评估 → 评分 → 修订，直到分数达到 <pass_threshold> 或预算耗尽。

首要目标。 达到阈值是停止条件，而不是目标。目标是打造提案能够诚实达到的最强、最新颖且真正可发表的版本——每次修订都应追问“这是否让研究更有意义、更具新意？”，而不只是“这是否修补了一个缺陷？”。这就是有依据的雄心：提升来自论证更充分的方法、更鲜明但站得住脚的新颖性主张，以及更强的基线，并且都有真实检索到的证据支持。夸大主张会让分数降低（证据门槛 + Contribution 维度），绝不会让分数提高。

参与角色（均在此文件夹中）：

• roles/ScholarEval.md — 基于文献的双模块评估器；输出 scholareval.json。
• roles/Judge.md — 对反馈评分 → 0-100 分 + 排序后的修复建议；输出 verdict.json（决定是否通过）。
• roles/Reviser.md — 重写提案以解决修复建议（守护研究意图）。
• rubrics/rubric.md — 固定的评分标准（Judge 绝不修改）。
• schemas/scholareval.schema.json、schemas/verdict.schema.json — 两个经过验证的输出。

生成 Agent，否则降级运行。 在 Claude Code 中，将 ScholarEval / Reviser 作为真正的 Agent 子 Agent 生成；否则就在当前上下文中分别扮演这些角色。你是协调器和 Judge。

适用场景

当已有书面提案，且用户希望依据文献的批判意见帮助提案达到更高质量标准时使用。默认：运行下方完整的评估→评分→修订流程。备用选项：若用户只想要批判意见（不需要重写），则运行一轮 ScholarEval + Judge 后停止。不适用于从空白页开始撰写提案，也不适用于独立的文献综述。

设置

以交互方式解析绑定项。 如果工作目录中存在 loop.run.yaml，则加载该文件并跳到循环。否则：在 Claude Code 上（可使用 AskUserQuestion 工具），推断每个绑定项的可能值，并将其作为推荐选项；在其他宿主环境中，则逐项以引用的纯文本提示提问。然后写入 loop.run.yaml（格式：examples/run.example.yaml），并在创建任何其他文件之前确认每个值、<intent> 以及实时／降级的文献层级。

绑定项	含义	默认值	推断方式
<proposal_path>	包含问题、方法论和计划实验的文件	—	扫描可能的 .md／.txt／.pdf 文件；如果只粘贴了文字，则将其保存到 <sandbox_root>/iter1/proposal.md
<intent>	核心研究问题和主要贡献，2-3 句话——冻结；Reviser 绝不能更改	—	阅读提案，提取内容，并请用户确认
<pass_threshold>	提案必须达到的及格分数（0-100）	75	对扎实且有充分依据的提案的要求，但不苛求完美
<budget>	最大迭代次数	6	—
<patience>	连续多少次迭代没有改进后停止	2	—
<eval_scale>	ScholarEval 每次迭代检索的文献量（low／medium／high，见下文）	medium	—
grade_weights	soundness · contribution · evidence_quality（总和必须为 1；本次运行期间冻结）	0.45 · 0.35 · 0.20	rubric.md；推荐默认值
<sandbox_root>	快照、记录和文献缓存的存放位置	./sandbox	—

评估深度调节（<eval_scale> 限定每次迭代的上限：方法数 · 检查维度数 · 每项查询数 · 全文阅读论文数）：

预设	方法数 · 维度数	每项查询数	全文阅读数	工作量
low	2 · 2	1	0（仅阅读片段／摘要）	低
medium （推荐）	4 · 3	2	2	中
high	6 · 5	3	5	高

文献工具链。 论文搜索通过同级的 literature-search 技能进行——解析 <lit_skill_dir>（该技能会安装在同级目录，例如 ~/.claude/skills/literature-search/），<lit_py> = python3，以及 <lit> = <lit_skill_dir>/tools/lit_search.py；在子命令后追加 --cache-dir <sandbox_root>/literature/.cache 以复用缓存。设置时确认 <lit> --help 可正常运行；如果缺少该技能，告知用户，并选择安装它（将仓库的 loops/literature-search 文件夹复制到 ~/.claude/skills/），或将所有检索降级为 WebSearch/WebFetch（不提供排序后的片段，也不扩展引用图）。无需设置即可使用无密钥的 S2 + arXiv 核心功能（search／snippet／cite／fulltext）；免费的 S2_API_KEY 可让 snippet + cite（ScholarEval 的两项关键操作）稳定运行。

API 密钥（可选，绝不阻塞）。 literature-search 技能负责管理密钥约定：运行 <lit> keys --init，然后让用户自行填写打印出的 keys.env，绝不要在聊天中粘贴密钥。重新运行 <lit> keys 确认密钥已存在，并将层级记录在 loop.run.yaml 中（仅记录是否存在）。缺少密钥时只会降级到无密钥资源池 → WebSearch。

确认绑定项后初始化沙盒：

<sandbox_root>/
├── loop.run.yaml        ← resolved bindings + <intent> + grade_weights + literature_tiers
├── ledger.tsv           ← header only (see Ledger)
├── literature/.cache/   ← lit_search on-disk cache
└── iter1/proposal.md    ← the input proposal (the baseline)

循环

<N> 从 1 开始；第 1 次迭代评估未经修改的提案（基准评分——此前不做修订）。每次迭代都重新评估：评分只能来自对修订后提案进行的新一轮 ScholarEval 评估，绝不沿用之前的评分。

复制此清单并逐项勾选：

• 评估 — 对 iter<N>/proposal.md 运行 roles/ScholarEval.md（spawn-or-degrade），并使用 <eval_scale> 上限和 <lit>；它会写入 iter<N>/scholareval.json（根据 schemas/scholareval.schema.json 验证）。
• 评分 — 作为 Judge（roles/Judge.md），将 rubrics/rubric.md 应用于 scholareval.json：证据门槛 → 每个维度 0-5 分 → 加权后的 grade → 硬性门槛 → pass 和按优先级排序的 fixes；写入 iter<N>/verdict.json（根据 schemas/verdict.schema.json 验证）。
• 记录 — 在 ledger.tsv 中追加一行（见 Ledger）。
• 停止检查 — verdict.pass == true，或 N == <budget>，或连续 <patience> 次迭代评分持平 → 停止（见 Stops）。
• 修订 — 运行 roles/Reviser.md（spawn-or-degrade），并提供 verdict.json、scholareval.json、<intent>、<lit> 和较小的修订搜索预算（约 <eval_scale> 次搜索 + 几次阅读）；它会应用一批有针对性的修复，并写入 iter<N+1>/proposal.md + iter<N+1>/revision_notes.md。
• N = N + 1 并重复。

每条引用的片段都必须来自该次迭代中的真实检索，绝不可伪造。当 lit 工具返回 {"error","fallback"} 时，改用 WebSearch/WebFetch；绝不可捏造论文。

Ledger

<sandbox_root>/ledger.tsv，以制表符分隔，自由文本中绝不使用逗号：

iter	grade	pass	soundness	contribution	evidence_quality	top_fix	revision_summary
1	58.0	no	3	2	4	add MM-GBSA re-scoring	baseline (no revision)
2	71.0	no	4	3	4	add head-to-head vs [C2] pipeline	added re-scoring + scoped affinity claim
3	82.0	yes	4	4	4	-	reframed contribution around integration + new benchmark

每次迭代对应的 scholareval.json 和 verdict.json 都位于 iter<N>/ 中。因预算用尽或评分停滞而停止时，报告评分最高的那次迭代，不一定是最后一次。不要将 ledger.tsv、iter*/ 和 literature/ 纳入版本跟踪。

约束

• 绝不伪造引用或片段 — 每条 evidence 都必须逐字来自该次迭代中检索到的真实 <lit>/WebFetch 结果；设置证据门槛就是为了发现伪造内容。
• 评分标准固定 — Judge 绝不编辑 rubrics/rubric.md，因此通过门槛在各次迭代中始终有意义。
• 保护 <intent> — Reviser 可以强化内容，但绝不能替换核心研究问题或主要贡献，也绝不能仅为提高评分而削弱核心方法。
• 依据证据评分，而非文笔 — 文采不加分；有依据的支持和经得起检验的新颖性才决定分数。
• 每次迭代只进行一批有针对性的修订，以便将每次评分变化归因于具体修订。
• 不安装任何内容 — 同级的 literature-search 技能仅使用标准库；绝不打印或提交 API 密钥（keys.env 在项目根目录中始终被 gitignore）。沙盒是自包含的——不得通过 ../ 路径逃出。

停止条件

循环在以下任一条件首次满足时停止：

• 通过 — verdict.pass == true。报告最终提案（iter<N>/proposal.md）、其评分和评分轨迹。
• 预算用尽 — N == <budget>。将评分最高的那次迭代作为交付成果。
• 评分停滞 — 连续 <patience> 次迭代评分没有提高。报告评分最高的迭代和当前优先级为 1 的修复项。

始终以交付提案的路径、评分及通过/未通过状态、ledger.tsv 中的评分轨迹收尾；如果未通过，还要列出该提案达到门槛仍需解决的当前阻碍。