检查系统健康状态

验证数据库连接、S3/MinIO 存储桶访问以及必要的数据库扩展是否正常。

Returns: 健康状态信息，包含： - ok: 整体状态是否正常 - db: 数据库连接状态 - s3: S3/MinIO 存储状态

导入 PDF 文献到知识库

将 PDF 文件导入到知识库，包括：

1. 计算文件哈希

2. 上传到 MinIO 存储

3. 提取文本内容

4. 分块处理

5. 生成 embeddings

6. 提交到数据库

执行过程会通过进度通知报告当前状态。

Args: file_path: PDF 文件的绝对路径 title: 文档标题（可选，会尝试从 PDF 元数据提取） authors: 作者（可选） year: 发表年份（可选） force: 是否强制重新导入已存在的文档

查看导入状态

查看指定文档或作业的导入状态，包括各阶段进度和错误信息。

Args: doc_id: 文档 ID（通过 doc_id 查询最新作业） job_id: 作业 ID（直接查询特定作业）

Returns: 导入状态信息，包含各阶段状态、错误摘要和建议修复动作

混合搜索文献库

使用全文搜索（FTS）和向量相似度搜索的组合，找到与查询最相关的文本块。

Args: query: 搜索查询字符串 k: 返回结果数量，默认 10 alpha: 向量搜索权重（0-1），默认 0.6。FTS 权重为 1-alpha per_doc_limit: 每篇文档最多返回的 chunk 数量，默认 3（避免单篇论文刷屏） fts_topn: FTS 候选数量，默认 50 vec_topn: 向量候选数量，默认 50

Returns: 搜索结果，包含： - results: 按相关性排序的 chunk 列表 - fts_candidates: FTS 候选数量 - vec_candidates: 向量候选数量

详细解释搜索结果

执行混合搜索并返回详细的解释信息，包括 FTS-only 命中、向量-only 命中、交集命中等。 用于调试和优化搜索参数。

Args: query: 搜索查询字符串 k: 返回结果数量，默认 10 alpha: 向量搜索权重（0-1），默认 0.6 per_doc_limit: 每篇文档最多返回的 chunk 数量，默认 3 fts_topn: FTS 候选数量，默认 50 vec_topn: 向量候选数量，默认 50

Returns: 详细的搜索解释，包含： - final_results: 最终 top-k 结果 - fts_only_hits: 仅 FTS 命中的结果 - vec_only_hits: 仅向量命中的结果 - intersection_hits: 两者都命中的结果 - stats: 统计信息

纯向量搜索

仅使用向量相似度搜索，适合语义相关但关键词不匹配的场景。

Args: query: 搜索查询字符串 k: 返回结果数量，默认 10

Returns: 搜索结果列表

纯全文搜索

仅使用 PostgreSQL 全文搜索，适合精确关键词匹配的场景。

Args: query: 搜索查询字符串（支持布尔运算符） k: 返回结果数量，默认 10

Returns: 搜索结果列表

获取指定 chunk 的完整内容

根据 chunk_id 获取文本块的完整信息，包括全文、页码、所属文档等。

Args: chunk_id: chunk 的唯一标识符

Returns: chunk 的详细信息，包含： - chunk_id: chunk ID - doc_id: 所属文档 ID - text: 完整文本 - page_start/page_end: 页码范围 - has_embedding: 是否有 embedding

获取指定文档的元数据和统计信息

根据 doc_id 获取文档的完整元数据，包括标题、作者、chunk 数量等。

Args: doc_id: 文档的唯一标识符（SHA256 哈希）

Returns: 文档的详细信息，包含： - 元数据：title, authors, year, venue, doi, url - 存储信息：pdf_bucket, pdf_key - 统计：chunk_count, embedded_chunk_count, total_tokens

获取指定文档的所有 chunks 列表

根据 doc_id 获取该文档的所有文本块摘要信息。

Args: doc_id: 文档的唯一标识符

Returns: chunks 列表，每个包含 chunk_id、页码和文本摘要

列出所有已导入的文档

获取文献库中所有文档的摘要列表，支持排序和筛选。

Args: limit: 返回结果数量限制，默认 50 offset: 分页偏移量，默认 0 order_by: 排序字段，可选 "created_at"（默认）、"year"、"title" has_embeddings: 筛选条件，True=只显示有完整embedding的，False=只显示缺embedding的，None=显示全部

Returns: 文档列表，包含基本信息和 chunk/embedding 统计

删除指定文档

从数据库删除文档及其所有关联数据（chunks、embeddings、导入记录等）。 可选择同时删除 MinIO 中的 PDF 文件。

Args: doc_id: 文档的唯一标识符 also_delete_object: 是否同时删除 MinIO 中的 PDF 文件，默认 False

Returns: 删除结果，包含删除的记录数量

更新指定文档的元数据

根据 doc_id 更新文档的元数据信息。只有提供的字段会被更新， 未提供的字段保持原值不变。

Args: doc_id: 文档的唯一标识符（SHA256 哈希） title: 新的论文标题 authors: 新的作者列表 year: 新的发表年份 venue: 新的期刊/会议名称 doi: 新的 DOI 标识符 url: 新的论文链接

Returns: 更新结果，包含： - success: 是否成功 - doc_id: 文档 ID - updated_fields: 更新的字段列表 - document: 更新后的文档信息

重新生成文档的 embedding

为文档的 chunks 生成 embedding。默认只处理缺失 embedding 的 chunks， 设置 force=True 可重新生成所有 embedding。

Args: doc_id: 文档的唯一标识符 batch_size: 批处理大小，默认 64 force: 是否强制重新生成所有 embedding，默认 False

Returns: 处理结果，包含处理的 chunk 数量

重新分块文档

从 MinIO 获取 PDF，重新提取文本并分块，然后生成新的 embeddings。 会删除旧的 chunks 和 embeddings。

Args: doc_id: 文档的唯一标识符 strategy: 分块策略，目前支持 "page_v1"（按页分块） force: 是否强制执行（即使已有 chunks），默认 False

Returns: 处理结果，包含新的 chunk 数量

根据论文标题从数据库下载 PDF 到本地目录

根据论文标题搜索数据库，找到匹配的文档后从 MinIO 存储下载 PDF 文件 并保存到指定的本地目录。

Args: title: 论文标题（支持模糊匹配） output_dir: 输出目录，默认为 ./data exact_match: 是否精确匹配标题，默认 False（使用模糊匹配）

Returns: 下载结果，包含： - success: 是否成功 - doc_id: 文档 ID - title: 论文标题 - file_path: 保存的文件路径 - size: 文件大小（字节）

构建证据包

搜索与主题相关的文献片段，并保存为可复用的证据包。 证据包可用于多次迭代综述写作，避免每次重新检索导致结果漂移。

Args: query: 搜索主题/研究问题 k: 检索数量，默认 40 per_doc_limit: 每篇文档最多返回的 chunk 数量，默认 3 alpha: 向量搜索权重，默认 0.6

Returns: 证据包信息，包含 pack_id 和检索到的条目

获取证据包详情

查看已保存的证据包内容和统计信息。

Args: pack_id: 证据包 ID

Returns: 证据包详情

列出所有证据包

查看已保存的证据包列表。

Args: limit: 返回数量限制，默认 20 offset: 分页偏移量，默认 0

Returns: 证据包列表

生成文献综述草稿

基于指定主题或已有证据包，按照学术标准结构组织成综述草稿。

Args: topic: 综述主题/研究问题（如果提供 pack_id 则可选） pack_id: 已有证据包 ID（如果提供则直接使用，不重新检索） k: 检索的相关 chunk 数量（仅当未提供 pack_id 时使用），默认 30 outline_style: 大纲样式，可选 "econ_finance_canonical"（经济金融）或 "general"（通用）

Returns: 综述草稿，包含： - sections: 按结构组织的章节列表 - all_citations: 所有引用的文献信息 - total_sources: 引用的文献总数

生成综述特定章节

基于证据包，只生成指定章节的内容。适合迭代写作某个特定部分。

Args: pack_id: 证据包 ID section: 章节类型，如 "methodology"、"findings"、"gaps" 等 outline_style: 大纲样式，默认 "econ_finance_canonical"

Returns: 章节内容和引用列表

获取可用的综述大纲模板

返回所有支持的文献综述结构模板。

Returns: 模板列表，每个包含名称和章节结构

收集特定主题的文献证据

搜索与主题相关的文献片段，可选择聚焦于特定章节类型。

Args: topic: 搜索主题 section_focus: 聚焦的章节类型（如 "methodology", "findings"） k: 返回结果数量

Returns: 按文献聚合的证据列表

检查 GraphRAG 层健康状态

验证 M2 GraphRAG 所需的表和索引是否存在，并返回统计信息。

Args: include_counts: 是否包含各表的行数统计，默认 True

Returns: 健康状态信息，包含： - ok: 整体状态是否正常 - db_ok: 数据库连接状态 - tables_ok: 必要表是否存在 - indexes_ok: 必要索引是否存在 - counts: 各表行数（可选）

筛选高价值 chunks

从指定文档或证据包中筛选包含关键方法/识别/结果相关内容的 chunks。

Args: doc_id: 文档 ID（与 pack_id 二选一） pack_id: 证据包 ID（与 doc_id 二选一） max_chunks: 最大返回数量，默认 60 keyword_mode: 关键词模式，"default" 或 "strict"

Returns: 高价值 chunk 列表，每个包含 chunk_id、doc_id、页码和命中原因

抽取结构化图谱要素 (Async Parallel)

从文档的 chunks 中抽取实体、关系和结论，写入 GraphRAG 表。 使用并行处理以加快速度。

执行过程会实时报告 chunk 处理进度。

Args: doc_id: 文档 ID chunk_ids: 指定 chunk ID 列表（可选） mode: 模式，默认 "high_value_only" max_chunks: 最大处理 chunk 数，默认 60 llm_model: LLM 模型，默认使用配置 min_confidence: 最小置信度阈值，默认 0.8 dry_run: 是否仅预览不写入，默认 False concurrency: 并发请求数，默认 60

规范化并合并重复实体

对指定类型的实体进行规范化处理，合并同一 canonical_key 的重复实体。

Args: types: 要处理的实体类型列表，默认 ["Topic", "MeasureProxy", "IdentificationStrategy", "Method"] suggest_only: 是否只返回建议而不执行合并，默认 False max_groups: 最大处理组数，默认 5000

Returns: 合并统计信息和建议列表

锁定或解锁实体

锁定的实体不会被自动规范化合并。

Args: entity_id: 实体 ID is_locked: 是否锁定，默认 True

Returns: 操作结果

手动合并两个实体

将 from_entity 的所有引用迁移到 to_entity，然后删除 from_entity。

Args: from_entity_id: 要被合并的实体 ID to_entity_id: 目标实体 ID reason: 合并原因

Returns: 操作结果

构建主题社区

从 Paper->Entity 关系构建共现图，使用 Leiden 算法聚类。

Args: level: 社区层级，"macro" 或 "micro" min_df: 节点至少出现在 N 篇 paper，默认 3 resolution: Leiden 分辨率参数，默认 1.0 max_nodes: 最大节点数，默认 20000 rebuild: 是否重建（清除同 level 旧结果），默认 False

Returns: 社区列表，每个包含 comm_id、大小和 top entities

为社区构建证据包

从社区 top entities 的 mentions 中采样 chunks，写入证据包。

Args: comm_id: 社区 ID max_chunks: 最大 chunk 数量，默认 100 per_doc_limit: 每篇文档最多 chunk 数，默认 4

Returns: 证据包信息，包含 pack_id、文档数和 chunk 数

生成社区结构化摘要

批量/并行生成社区摘要

Args: level: 社区层级，"macro" 或 "micro"（或整数 1/2） concurrency: 并发数，默认 5 comm_ids: 指定社区 ID 列表 force: 是否强制重新生成

导出证据矩阵

导出 PaperMatrix（论文级）和 ClaimMatrix（结论级）两张表。

Args: comm_id: 社区 ID（与 topic 二选一） topic: 主题名称或 canonical_key（与 comm_id 二选一） format: 输出格式，"json" 或 "csv" limit_docs: 限制文档数量

Returns: paper_matrix 和 claim_matrix

查看 GraphRAG 覆盖状态

统计每个文档（或全局）的 entities、mentions、claims 覆盖率。

Args: doc_id: 文档 ID（可选，若无则返回全局统计）

Returns: 覆盖率统计信息

批量补跑未抽取的文档

找出没有 mentions 的文档，并对它们执行 extract_graph_v1。

Args: limit_docs: 最大处理文档数，默认 50 llm_model: LLM 模型，默认使用环境变量 LLM_MODEL 配置 min_confidence: 最小置信度阈值

Returns: 处理的文档数和文档 ID 列表

重建社区

清除指定层级的旧社区并重新构建。

Args: level: 社区层级，"macro" 或 "micro" min_df: 节点最小文档频率，默认 3 resolution: Leiden 分辨率参数，默认 1.0

Returns: 新社区列表

清理 GraphRAG 数据

清理指定文档或全部的 GraphRAG 数据。

Args: doc_id: 文档 ID（清理单个文档） clear_all: 是否清理全部（危险操作）

Returns: 清理结果，包含删除的记录数

生成综述大纲（确定性，无 LLM）

从 topic 或 comm_ids 生成可复现的综述大纲结构，写入数据库。

Args: topic: 综述主题（与 comm_ids 二选一） comm_ids: 社区 ID 列表（与 topic 二选一） outline_style: 大纲样式，默认 "econ_finance_canonical" rebuild: 是否重建已存在的大纲，默认 False

Returns: outline_id, topic, sections 列表

构建章节证据包

为指定章节生成固定的证据包（可复现）。

Args: outline_id: 大纲 ID section_id: 章节 ID max_chunks: 最大 chunk 数量，默认 60 per_doc_limit: 每篇文档最多 chunk 数，默认 4 rebuild: 是否重建，默认 False

Returns: pack_id, chunk_count, doc_count

导出章节写作输入包

生成包含所有必要信息的 JSON，供 Agent 写作使用。

Args: pack_id: 证据包 ID

Returns: evidence[], paper_matrix[], claim_matrix[], doc_citations[]

验证章节引用合规

检查 Agent 写作的 markdown 是否符合引用规则。

Args: pack_id: 证据包 ID markdown: Agent 写作的 markdown 内容 require_citations_per_paragraph: 是否要求每段有引用，默认 False min_citations_per_paragraph: 每段最少引用数，默认 1

Returns: passed, issues[], stats

生成全文结构模板

返回按顺序排列的章节和 markdown 模板（带占位符）。

Args: outline_id: 大纲 ID

Returns: ordered_sections[], template_markdown

验证全文合规

检查完整综述是否符合所有引用规则。

Args: pack_ids: 允许的证据包 ID 列表（白名单） markdown: 完整的综述 markdown

Returns: passed, issues[], stats

规范化关系并合并重复项，保留所有证据。

Args: scope: 处理范围，"all", "doc_id:...", "comm_id:..." predicate_whitelist: 只处理这些谓词 qualifier_keys_keep: 规范化时保留哪些 qualifier 字段 dry_run: 仅计算建议，不写入数据库

导出紧凑的关系视图（按 canonical 关系聚合）。

对结论进行分组/聚类。

Args: scope: 处理范围，"all", "comm_id:...", "doc_ids:id1,id2" max_claims_per_doc: 每个文档最多处理多少条结论 dry_run: 是否仅预览

导出按分组聚合的结论矩阵。

列出词表规则

添加或更新词表规则

计算 Topic 实体的文档频率缓存

为 claims 分配预计算特征（primary_topic, outcome/treatment family 等）

基于 claim_features 构建 v1.2 claim groups

拆分超大 claim groups (使用 TF-IDF + KMeans)

导出分组 claim 矩阵，每组返回 top-k 代表 claims (按 confidence 排序，sign 分层)