hypothesis-gen

假设生成循环

一个多 Agent、以文献为依据的生成循环。产物是不断扩大的假设池；反馈信号是达到标准的有力且彼此不同的假设数量——其中“有力”是根据实际检索到的文献判定的，而非凭空断言。每一轮：生成 → 查证依据 → 评判 → 保留 → 针对缺口变异，直至假设池不再扩大（饱和）。

基本原则：只有当文献表明某个假设尚未得到证实（新颖性）、既有工作使其具有合理性（依据），且存在可行的测试方法时，它才会进入假设池。生成不等于确认——输出是一组按排名排列的有力待测候选假设，每个假设都说明了如何测试。

参与角色（均在 roles/ 中）：

• roles/Generator.md — 针对尚未填补的缺口，提出一批候选假设。
• roles/LiteratureScout.md — 为每个候选假设提供真实文献依据（新颖性 · 支持 · 缺口）；生成 litscout.json（通过 schemas/litscout.schema.json 验证）。
• roles/Judge.md — 根据固定评分标准为每个候选假设评分，并决定保留、淘汰或去重；生成 verdict.json（通过 schemas/verdict.schema.json 验证）。

启动 Agent，否则降级运行。 在 Claude Code 中，每轮都将 Generator / LiteratureScout / Judge 作为真正的 Agent 子 Agent 启动；否则就在当前上下文中分别扮演各个角色。你是协调者。

适用场景

当用户希望针对某个问题或领域生成并审核候选假设时使用。默认：运行下方完整的生成→查证依据→评判循环，直至饱和。备用方案：如果用户只想要一批假设（不循环），则运行一轮并汇报保留的假设。不适用于优化或拆解问题，也不适用于评审已有的书面提案。

设置

以交互方式确定绑定项。 如果工作目录中存在 loop.run.yaml，加载该文件，用一行确认 其中的值，然后跳转到循环步骤。否则：在 Claude Code 中（可使用 AskUserQuestion 工具），推断每个绑定项的可能值，并将其作为推荐选项提供；在其他宿主环境中，则分别以引用的纯文本提示询问。然后写入 loop.run.yaml（格式： examples/run.example.yaml），并在创建任何其他文件前，确认每个值以及文献等级为实时检索或降级模式。

绑定项	含义	默认值	推断方式
<question>	研究问题／领域，以及任何范围限定（领域、群体、约束条件）	—	询问用户
<gen_n>	Generator 每轮提出的候选假设数	6	—
<keep_threshold>	假设进入候选池必须达到的评分标准分数（0-100）	65	—
<eval_scale>	LiteratureScout 的文献依据深度（low／medium／high，见下文）	medium	—
<sandbox_root>	存放各轮内容、台账和文献缓存的位置	./sandbox	—
<budget>	最大轮数	6	—
<patience>	连续多少轮没有新假设入选后停止	2	—
<report>	最终排序后的假设集	<sandbox_root>/hypotheses.md	—

文献依据深度调节项（<eval_scale> 限制每轮的数量——深入考察的候选项数、每项查询数、 全文阅读数）：

预设	深入考察的候选项	每项查询数	全文阅读数
low	2	1	0（仅阅读摘要片段／摘要）
medium (推荐)	全部	2	1
high	全部	3	3

文献工具链。 论文搜索通过同级的 literature-search skill 进行——确定 <lit_skill_dir>（安装为同级目录，例如 ~/.claude/skills/literature-search/）， <lit_py> = python3，以及 <lit> = <lit_skill_dir>/tools/lit_search.py（注意其中的 tools/ 部分）；在子命令后追加 --cache-dir <sandbox_root>/literature/.cache 以复用缓存。 在设置时确认 <lit> --help 能正常运行；如果缺少该 skill，请告知用户，并选择安装它 （将仓库的 loops/literature-search 文件夹复制到 ~/.claude/skills/），或将所有检索降级为 WebSearch/WebFetch（将相关证据标记为 source:"web"）。无需设置密钥即可使用核心的 S2 + arXiv；免费 的 S2_API_KEY 可确保 snippet／cite 稳定可靠。

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

确认绑定项后初始化沙盒，只需执行一次：

<sandbox_root>/
├── loop.run.yaml        ← resolved bindings + literature_tiers
├── ledger.tsv           ← header only (see Ledger)
└── literature/.cache/   ← lit_search on-disk cache

从空的 pool 开始，并根据 <question> 初始化 gaps；循环运行前不要创建轮次文件。

循环

pool = 保留的假设（初始为空）。gaps = LiteratureScout 提出的问题（初始为空；从 <question> 中获取初始问题）。dry = 连续未产生新保留项的轮数（初始为 0）。<N> 初始为 1。

复制此清单并逐项勾选：

• 生成 — 使用 <question>、当前的 pool、gaps 和 <gen_n> 运行 roles/Generator.md（启动失败时降级），生成 round<N>/candidates.json（包含 <gen_n> 个具体、可测试、看似新颖、针对 gaps 且不与 pool 重复的候选项）。
• 核实依据 — 对 candidates.json 使用 <lit> 和 <eval_scale> 上限运行 roles/LiteratureScout.md（启动失败时降级）；生成 round<N>/litscout.json（通过 schemas/litscout.schema.json 验证）——每个候选项均包含新颖性和最接近的既有研究、支持依据、空白、可测试性，且每项都引用真实证据。
• 评审 — 按照 roles/Judge.md，对 litscout.json 应用固定评分标准和证据门槛，并逐一检查每个候选项是否与 pool 中的项目重复；生成 round<N>/verdict.json（通过 schemas/verdict.schema.json 验证）：评分、total、keep、duplicate_of。
• 更新 — 将所有 keep:true 且不重复的项目加入 pool（包括评分、依据和测试方法）；将本轮的 gap 要点加入 gaps。如果至少有 1 个新保留项，则 dry = 0；否则 dry += 1。
• 记录一行台账（见台账）；N = N + 1。
• 停止检查 — 若 dry == <patience>（饱和）或 N > <budget>，则停止（见停止条件）。

每轮重新核实依据 — 每轮都必须根据新一轮的文献检索判断新颖性，不能沿用之前的结果，因此“文献已经涵盖了这一点”会可靠地淘汰重复想法。每条引用的片段都必须来自该轮的真实检索；遇到 {"error","fallback"} 时，改用 WebSearch/WebFetch——绝不捏造论文。

schemas/litscout.schema.json 用于验证 LiteratureScout 的输出——通用实例：

{"round": 2,
 "evaluations": [{"hid": "r2h1", "novelty_assessment": "novel",
   "closest_prior_work": [{"claim": "X tested for facts, not skills", "cites": ["E1"]}],
   "support": [{"claim": "spacing aids motor consolidation", "cites": ["E2"]}],
   "gap": [{"claim": "long-term procedural retention untested at scale", "cites": ["E1"]}],
   "testability_note": "RCT: spaced vs massed schedule, 1-month retention."}],
 "evidence": [{"key": "E1", "title": "...", "source": "s2", "id": "a1b2", "snippet": "...verbatim..."}]}

schemas/verdict.schema.json 用于验证 Judge 的输出——通用实例：

{"round": 2,
 "verdicts": [{"hid": "r2h1",
   "scores": {"novelty": 4, "grounding": 4, "testability": 5, "specificity": 4, "significance": 4},
   "total": 82.0, "keep": true, "gate_failures": [], "duplicate_of": null,
   "rationale": "Closest work shows X untested for skills -> novel; supported; clean RCT named."}]}

台账

<sandbox_root>/ledger.tsv，以制表符分隔，自由文本中不得出现逗号。表头：

round	generated	kept_new	pool_size	top_kept

示例：

round	generated	kept_new	pool_size	top_kept
1	6	3	3	spaced practice aids procedural (not just declarative) retention [82]
2	6	2	5	sleep-timed review beats time-of-day-matched review [78]
3	6	0	5	-

每轮的 candidates.json / litscout.json / verdict.json 存放在 round<N>/ 中。停止时应报告 pool 的最佳状态，而不只是最后一轮的状态。不要将 ledger.tsv、round*/ 和 literature/ 纳入版本跟踪。

约束

• 绝不捏造引用或片段——每条证据都必须是该轮 <lit>/WebFetch 检索所得的真实内容，并逐字引用；证据门槛就是为发现捏造而设。
• 新颖性由文献决定，而非凭断言决定——如果检索显示某项假设已成定论，无论它多么诱人，都必须淘汰；若没有检索最接近的既有研究，仅说“我认为它很新颖”，则新颖性评分设上限。
• 生成 ≠ 确认——保留的假设是有力的待测候选项，每项都必须说明其测试方法；绝不能将其报告为已确立的发现。
• 评分标准固定，保留门槛在各轮间保持不变，因此饱和可作为有意义的停止条件。
• 奖励不同的假设，而非数量——删除重复项和换一种说法表达的项目。
• 不安装任何内容——同级目录中的 literature-search 技能仅使用标准库；绝不输出或提交 API 密钥（keys.env 在项目根目录保持 git 忽略）。沙盒是自包含的——不得通过 ../ 越界。
• 不要暂停循环询问是否继续；持续运行，直至饱和或达到预算。

停止条件

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

• 饱和 — 连续 <patience> 轮没有新增保留的假设，即 dry == <patience>。
• 预算 — 已达到 <budget> 轮。

结束时给出按排名排列的假设集合（<report> 路径）——每项假设均包含其陈述、新颖性评估及最接近的既有研究（附引用）、支持证据（附引用）、填补的空白以及测试方法；同时给出 ledger.tsv 中 pool 的规模变化轨迹和最值得探索的空白，让用户既能看到经过核实的假设，也能了解深入研究下一步可以探索的方向。