Hyperresearch claims命令完全指南：跨来源提取与查询结构化声明

Hyperresearch claims命令完全指南：跨来源提取与查询结构化声明

【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearch

Hyperresearch 是一个开源的深度研究知识库，它让 AI Agent 自动抓取网络来源、沉淀为可持久搜索的研究笔记库，并产出有证据背书的报告。其中claims 命令族正是它「结构化提取 + 跨来源查询」的核心：把每个来源支持的**声明（claim）**存成可查询的数据库条目，让"哪些来源支持某个观点"变成一条命令的事。本文带你完整走通 claims 的 5 个子命令：ingest、list、search、matrix、targets。

为什么需要 claims 命令：从"读网页"到"查声明"

普通的深度研究工具是"一次性的"：报告生成完，读过的内容就丢了。Hyperresearch 的思路是把抓取过的每个来源都沉淀进知识库（Markdown 笔记 + SQLite 索引），而 claims 命令进一步把来源内容拆成结构化声明：

• claim：一句可证伪的论断，比如"异步 IO 显著提升网络型负载的吞吐量"
• quoted_support：来源中的原文引用（最关键字段，引用核查直接依赖它）
• numbers：具体数字、百分比、阈值（数字一致性检查的数据源）
• stance / stance_target：该声明支持还是反驳某个立场、针对什么论点
• evidence_type / confidence：证据类型与置信度

在 16 步研究流水线中，抓取 Agent 每读一个来源就会把这类声明写入临时 JSON 文件（research/runs/<vault_tag>/temp/claims-<note-id>.json）。但这些文件散落各处、无法聚合——claims 命令把它们持久化进数据库（claims 表 + 全文索引），从此声明可以被搜索、按来源分组、跨研究轮次对比。

5 个子命令一览

💡 五个子命令都支持--json（或-j）输出机器可读结果，方便接脚本或管道。

第一步：用 ingest 一键导入结构化声明

claims 文件由流水线的抓取 Agent 自动生成（第 2 步宽度扫描与第 13 步补抓都会写），你通常只需一条命令把它们收进数据库：

# 摄入指定研究轮次的声明，并给数据打上 vault_tag hyperresearch claims ingest --tag my-topic -j

不传--tag时，它会自动扫描所有研究轮次工作区（research/runs/*/temp/）和旧版扁平目录（research/temp/）下的claims-*.json文件。

新手须知：

• 文件名必须形如claims-<笔记id>.json，且该笔记要先存在于知识库中（否则提示先hyperresearch sync）
• 幂等设计：每条声明以「笔记 id + 内容哈希」去重，重复摄入是空操作，放心重跑
• 内置安全上限（单文件 8MB、单字段 2 万字符），一个畸形文件不会拖垮整批导入
• 找不到文件时会打印提示：用--tag指定轮次，或直接把文件路径传给命令

一条声明长什么样？

下面是单个声明的最小结构（由抓取 Agent 按契约写入，无需手写）：

{ "claim": "异步 IO 在网络型负载下显著提升吞吐", "quoted_support": "来源原文引用，最多两句", "numbers": ["10x"], "evidence_type": "empirical", "stance": "supports", "stance_target": "async-performance", "confidence": "high" }

第二步：跨来源查询——search 与 list

用 search 回答"哪个来源支持 X"

hyperresearch claims search "吞吐量提升"

搜索基于 SQLite 全文索引，覆盖claim 正文 + quoted_support 原文，按相关度排序。每条结果会显示来源笔记 id、声明内容（截断到 120 字符）以及原文引用（160 字符），一眼看清"谁在支持什么"。

用 list 按来源精确浏览

hyperresearch claims list --note python-async-patterns -n 50 hyperresearch claims list --tag my-topic

--note只看某个来源提取的声明，--tag只看某一研究轮次的数据——适合撰写报告时核对"我到底从这篇文献里拿到了哪些证据"。

第三步：用 matrix 一键生成文献综述矩阵

hyperresearch claims matrix --tag my-topic -o matrix.md

这是 claims 表最直观的产出：为每个有声明的来源生成一行，包含层级、类型、发表载体、被引次数、质量分、声明数（实证/量化各多少），并自动挑出该来源信号最强的一条关键发现（优先实证、带数字、高置信度的声明）。行按质量分从高到低排序，被撤稿的来源会醒目标注RETRACTED。

输出就是标准 Markdown 表格，-o参数直接落盘——这正是论文写作场景下的文献综述附录，把数周的人工整理表格变成一条命令。

第四步：用 targets 做跨来源元分析

hyperresearch claims targets --tag my-topic --min-sources 3

它把所有声明按stance_target（立场目标）分组，只保留被 ≥N 个不同来源讨论过的目标（默认 2），并输出：

• 讨论该目标的来源数与声明数
• 立场分布：比如 3 个来源支持、1 个来源反驳
• 每条声明的带来源归属的数字值——现成的对比表格底料，方便你标出离群值

对"多个来源就同一问题给出不同结论"的场景（综述、争论类选题），targets 直接给出分歧全景。

它在流水线中的位置：一条线索串起来

claims 命令不是孤立功能，而是整个研究流水线的数据底座：

常见问题

问：为什么重复 ingest 显示 "already present" / skipped？这是幂等设计在起作用：已存在的声明不会重复入库，跳过即正常，可以放心重跑。

问：ingest 报 "note not in vault" 怎么办？文件名中的笔记 id 还没进知识库。先运行hyperresearch sync同步笔记，再重新摄入。

问：ingest 提示找不到 claims 文件？说明该轮次没有抓取 Agent 产出的声明文件。确认研究运行到第 2 步（宽度扫描）之后，或显式把 JSON 文件路径传给claims ingest <路径...>。

关键文件索引

想深入了解实现细节，可以从这些文件入手：

• 命令入口：src/hyperresearch/cli/claims_cmd.py
• 核心持久化与聚合逻辑（摄入、搜索、矩阵、分组）：src/hyperresearch/core/claims.py
• claims 表的设计蓝图：docs/roadmap-2.0/phase-2-source-ranking.md
• 离线测试用例（幂等性、FTS 搜索、CLI 调用）：tests/test_core/test_claims_and_embed.py

掌握了 claims 命令族，你就不再是"读完就忘"的研究者：每个来源的声明都被结构化留存，可搜索、可对比、可核查——下一次研究开局，就已经比上一次更聪明。

【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearch