从 LLM 输出中提取 JSON（抗 Silent Regression） 【工程思考】这是从 05_Agent工程落地深度思考.md 中的 RobustJSONExtractor 精简版。在真实项目中， LLM 输出格式不可 10

格式化作者列表，超过 max_display 人时显示 et al.

判断返回结果是否是 429 限流响应

从 prompts/domain_prompts/ 加载 Prompt 文件 优先级: 文件 > 内联 fallback

获取模板

关键词搜索节点 在节点的 label 和 properties 中搜索关键词（大小写不敏感）

序列化为字典（用于 JSON 持久化）

解析 LLM 输出为 ExtractionResult。 【2026-05-20 重构】Phase 2.6 + 2.2: - 严格 Pydantic 解析失败：logger.warning（不是 debug）+ 标记 had_parse_fal

把字符串解析为 NodeType。返回 (类型, is_fallback)。 解析顺序： 1. 直接 NodeType(raw) 命中 2. NODE_TYPE_ALIASES 命中（领域专用→通用映射） 3. fallback 到 NodeType.O

为单个任务建立隔离沙箱。 进入上下文：建目录树 + 覆盖 SCHOLARMIND_DATA_DIR。 退出上下文：还原 SCHOLARMIND_DATA_DIR（无论成功失败）。 注意：本上下文管理器只负责「隔离环境」，不做污染检测 —— 污染检测由 runner

从一个 dataset 目录加载 Dataset（不做校验，调用方按需 .validate()）。

记录一次代码改动。

更新一个偏好键。若值不在 ALLOWED_VALUES 限定集内会抛 ValueError。

从 os.environ 派生子进程 env：只保留白名单 + 系统必需 + 强制 strip 模式。 extra_overrides 在 strip 之后应用（用于 sandbox 自己设的 PYTHONDONTWRITEBYTECODE 等）。

计算文件 SHA-256 哈希（前 length 位）

追加一条带时间戳的经验记录到 experiences/<category>.md。 每条独占一个二级小节 `## [YYYY-MM-DD HH:MM]`。

扫描 import 语句，超出 RECOMMENDED_IMPORTS 的模块发警告。 实现策略：只看根模块名（"scipy.signal" → "scipy" 也算命中）。 返回的是"软警告"，调用方决定是否阻塞（当前不阻塞）。

从文本中抽取实体和关系 如果文本过长，自动分段抽取后合并。 Args: text: 论文文本（全文或章节） paper_title: 论文标题 paper_year: 论文年

按档位 / 层过滤任务。

评估知识图谱的整体健康度 【工程思考】"健康度"是一个复合指标，帮助用户理解： - 知识覆盖面够不够广？（节点数） - 知识之间的关联够不够密？（边密度） - 有没有孤立的知识岛？（连通分量数） -

提取 PDF 元数据

获取模板代码，支持参数覆盖 【工程思考】为什么支持参数覆盖？ Agent 可以根据论文中的具体参数修改模板： "这篇 Agent 论文用任务成功率和平均调用成本做评测，帮我改一下模板跑出结果" 目前用简单的字符串替换实现，后续可升级到 Jinja2

合并另一个同 ID 节点的属性（去重合并） 【工程思考】为什么需要合并？ 同一个概念可能从不同论文中被抽取，每次抽取的属性可能不同。 例如从 Paper A 抽取了 ReAct 的定义，从 Paper B 抽取了 ReAct 的应用

domain 标准化。未知 / None / 空 → DOMAIN_SHARED。

查询节点的邻居（支持多跳） Args: node_id: 起始节点 ID depth: 查询深度（1=直接邻居, 2=两跳邻居...） relation_type: 可选，过滤特定关系类型

根据 run_log 自动 append 到对应经验文件。 返回被写入的文件名列表（方便上层 RefactorRecorder 知道产物在哪）。

通过 Semantic Scholar API 搜索学术论文。**备选搜索源**——首选 `search_arxiv`。 ⚠️ **优先级提示** (Phase 4.1)：本工具无 API Key 时极易触发 429 限流（1 req/s）； 建议默认走 `search_

把一个 fixture seed graph 复制进隔离图谱路径，返回隔离路径。 gap_detection / kg_query 任务用：绝不读真实图谱，只读 fixture 的拷贝。

归一化 alias -> gold entity 映射。用于 alias 匹配档。

返回 (error_category, error_text)。httpx 在函数内懒加载，故按类名判别。

从文件名中尝试提取 arXiv ID 支持格式： - "2210.03629.pdf" - "arxiv_2210_03629.pdf" - "ReAct_2210.03629.pdf" - "2210.03629v3.pdf"

从 gold 取指定 tier 的实体列表（must_have / should_have / may_have）。

归一化 alias 查找 key：小写 + 剥括号注释 + 折叠连字符/下划线/空格。 剥括号："Chain-of-Thought (CoT)" / "ReAct (Reasoning and Acting)" 这种 注释式后缀很常见，括号里的内容跟前面是同义体，应当合并到同一 c

node_id 形如 "{type}_{normalized_label}"，取后半。

返回 (匹配到的 gold entity 或 None, 匹配档位)。 档位：'exact' / 'alias' / 'embed' / 'miss' exact 和 alias 其实是同一档（alias_index 包含 label 自身），但区分以便诊断。

UTC ISO（state 文件用）。