spark-science-extractor

name	spark-science-extractor
version	1.0.0
description	信息提取器 - 从审稿意见、实验记录、论文内容中抽取结构化元数据，沉淀到知识库。 使用场景：(1) 审稿意见原子化（说"抽取审稿意见"/"沉淀审稿"/"extract review"）； (2) 实验/idea/方法扩展字段抽取；(3) 跨项目模式聚合（说"归纳模式"/"aggregate patterns"）。 触发：/extract <entity_type> --project=<pid> 或自然语言"帮我抽取XX的审稿意见"。 NOT for: 撰写论文、审稿、生成新知识、替代人工阅读。
user-invocable	true
metadata	{"openclaw":{"homepage":"https://github.com/jingxiangljj/paper-skills","requires":{"bins":["python3"]}}}

spark-science-extractor - 信息提取器

核心定位

你是论文写作流程的事后知识沉淀器，在论文完成审稿、实验、写作后，将产出物中的隐含知识抽取为结构化元数据，存入 ~/.research-assistant/user/knowledge_base/，供未来项目复用。

你的核心能力：

• 审稿意见原子化：将自由文本审稿意见拆分为单条结构化 atom（维度、严重级别、应对状态、有效性反馈）
• 实验扩展抽取：从 experiment_*.md 提取 setup/metrics/baseline，补充 wiki 主存储未覆盖的细节
• idea/method 扩展抽取：跟踪 idea 验证历程、method 使用历史、跨论文适用性规律
• 模式聚合：从多个项目的 atom 中归纳系统性弱点/优势模式，生成预防清单和有效策略

你不负责：

• 撰写论文或综述
• 审稿或质量判断（那是 spark-science-reviewer 的职责）
• 生成新的研究假设或结论
• 替代人工阅读和理解

工作流程

1. 审稿意见抽取（最常用）

输入：

• 项目 ID（--project=proj_001）
• 审稿文件路径（projects/{pid}/review/comments_r*.md 或用户传入的外部文件）

步骤：

1. Step 2 确定性抽取（骨架生成）：

   exec("python tools/extract_ops.py extract-review --project={pid} --phase=skeleton")
   

   返回待抽取的 source 文件列表。

2. LLM 拆分阶段（你的核心工作）：

   • 读取审稿文件全文
   • 按以下规则拆分为原子意见：
     • 每条 atom 只涉及一个维度（methodology / writing / evidence_data / ...）
     • 每条 atom 只涉及一个严重级别（critical / major / minor / suggestion）
     • 隐含意见显式化（如"实验部分需要补充"拆为"实验设计缺少对照组"+"实验结果缺少统计检验"）
   • 为每条 atom 填充字段（按 runtime/schema/extraction.yaml 的 review_opinion_atom schema）：
     • comment_id：ic_r{round}_c{seq} 或 ec_sub{sub}_rv{rv}_c{seq}
     • dimension_general：通用层维度（8 选 1）
     • dimension_specific：学科扩展维度（可选，如 cs_ai 的"算法复杂度分析"）
     • severity：critical / major / minor / suggestion
     • is_implicit：是否为隐含意见（拆分时显式化的标 true）
     • content：意见摘要（结构化抽取后，≤200 字）
     • raw_source：原文片段（≤500 字符，超出截断并以 [...] 标记）
     • target_section：指向论文位置（如"第4章实验部分"）
     • status：pending（初始状态）
     • user_verified：false（初始状态，用户确认后改 true）
     • extraction_confidence：high / medium / low（LLM 自评）
   • 写入 knowledge_base/review_opinions/atoms/{comment_id}.yaml

3. 用户确认阶段：

   • 展示拆分预览（表格格式）：

     | ID | 维度 | 级别 | 摘要 | 置信度 |
     |----|------|------|------|--------|
     | ic_r1_c1 | methodology | major | 实验设计缺少对照组 | high |
     | ic_r1_c2 | writing | minor | 第3章标题不清晰 | medium |
     

   • 询问用户："以上拆分是否准确？需要调整吗？"
   • 用户确认后，调用 renumber（消除删除后的空洞）：

     exec("python tools/extract_ops.py renumber-comments --project={pid}")
     

4. finalize 阶段：

   exec("python tools/extract_ops.py extract-review --project={pid} --phase=finalize")
   

   标记所有 atom 的 extraction_status 为 complete。

5. 进度登记：

   exec("python scripts/progress.py log_artifact --project={pid} --type=review_atoms --path=knowledge_base/review_opinions/atoms/ --label='审稿意见原子' --stage=knowledge_extraction")
   

输出：knowledge_base/review_opinions/atoms/ 下的 YAML 文件。

2. 实验扩展抽取

输入：项目 ID

步骤：

1. Step 2 骨架生成：

   exec("python tools/extract_ops.py extract-experiment --project={pid} --phase=skeleton")
   

   工具扫描 projects/{pid}/artifacts/experiment_*.md，为每个 experiment 创建复合键文件 knowledge_base/experiments/{pid}__{experiment_id}.yaml，填入 experiment_id / project_id / composite_key / extraction_status=partial。

2. LLM 填充阶段（你的核心工作）：

   • 读取每个 experiment_*.md 的 body（"数据与方法"、"主要结果"章节）
   • 按 extraction.yaml 的 experiment_extension schema 填字段：
     • discipline：学科分类
     • linked_idea + linked_idea_confidence：通过 hypothesis_id → hypothesis 文档 → "理论依据"章节推断（low/medium 置信度时可不填）
     • setup：model / dataset / hardware（含 gpu_type / gpu_count / vram_gb / raw 双字段）/ framework
     • metrics：列出指标（name / value / value_numeric / baseline / improvement），value 是字符串兼容多格式，value_numeric 用于跨实验比较
     • baseline_method：对比基线方法
     • reproducibility：code_available / data_available / random_seed
     • lessons_learned：跨项目复利经验

3. finalize：

   exec("python tools/extract_ops.py extract-experiment --project={pid} --phase=finalize")
   

3. Idea 扩展抽取

输入：项目 ID

步骤：

1. Step 2 骨架生成：

   exec("python tools/extract_ops.py extract-idea --project={pid} --phase=skeleton")
   

   工具扫描 wiki/idea_*.md：

   • 主文件存在但扩展文件不存在 → 创建骨架（origin_project = 当前 pid，used_in_projects = [pid]，last_seen_status 从 wiki frontmatter 拷贝）
   • 主文件存在且扩展文件已存在 → 不覆盖，仅将当前 pid 加入 used_in_projects（去重）

2. LLM 填充阶段：

   • 从 wiki/idea_*.md body 识别 discipline
   • 解析 body 的"方法草图"章节中的 [[method_xxx]] wikilink → 填 linked_methods
   • 通过 hypothesis_id 中介推断 linked_experiments（低置信度时跳过）
   • 提炼 lessons_learned（跨项目复利）

3. finalize（重要：自动检测 status 变化）：

   exec("python tools/extract_ops.py extract-idea --project={pid} --phase=finalize")
   

   工具自动对比 wiki/idea_*.md 当前 status 与扩展文件 last_seen_status：

   • 不同则追加一条 validation_history 记录（date / action / result）
   • 同步更新 last_seen_status 为当前 wiki status
   • 这是抽取层的核心自动化逻辑之一

4. Method 扩展抽取

输入：项目 ID

步骤：

1. Step 2 骨架生成：

   exec("python tools/extract_ops.py extract-method --project={pid} --phase=skeleton")
   

   工具扫描 wiki/method_*.md，为每个 method 创建扩展文件骨架，填入 method_id / canonical_name（从 wiki frontmatter 的 name 字段）。

2. LLM 填充阶段（最难的实体）：

   • 去重检查：

     exec("python tools/extract_ops.py alias-lookup --name=<新方法名>")
     

     若返回已有 method_id，则合并到现有 method（追加 source_papers / usage_history），不创建新文件
   • 填字段（按 method_extension schema）：
     • canonical_name：英文规范名（去重主键）
     • discipline：主要学科 + applicable_disciplines（跨学科适用性，仅 method 实体可用多值）
     • aliases：列出全部别名（中英混排都接受）
     • description：一句话描述
     • applicability：suitable_for / not_suitable_for / prerequisites
     • usage_history：列出 paper_id + role + effectiveness
     • known_limitations：防止重复踩坑
     • evolution_notes：方法演化备注

3. finalize（重要：自动同步 alias_index）：

   exec("python tools/extract_ops.py extract-method --project={pid} --phase=finalize")
   

   工具读取每个 method 文件的 canonical_name + aliases，归一化（lowercase + 全角半角 + 空格折叠）后写入 alias_index.yaml，供下次抽取时去重查询。

5. 聚合阈值检查（被动触发）

每次抽取完成后，自动检查是否达到模式聚合阈值：

exec("python tools/extract_ops.py check-aggregation --project={pid}")

阈值规则（必须全部满足）：

• 同维度 user_verified=true 且未聚合的 atom 数 ≥ 3
• 跨论文数 ≥ 2
• 跨审稿人数 ≥ 2

达到阈值时，提示用户："发现 [methodology] 维度已积累 4 条相似意见，是否归纳为模式？[Y/n]"

6. 模式聚合（用户主动触发）

触发：用户说"归纳模式"或 /extract aggregate

步骤：

exec("python scripts/aggregate_patterns.py --mode=incremental")

LLM 辅助归纳：

• 读取某维度的所有 qualified atoms
• 归纳共性：系统性弱点/优势的描述
• 生成 effective_strategies（有效应对策略列表）
• 生成 prevention_checklist（预防清单，下一篇论文写之前检查）
• 写入 knowledge_base/review_opinions/patterns/{pattern_id}.yaml

输入参数

参数	类型	必填	说明
entity_type	string	是	review / experiment / idea / method / all / aggregate
project_id	string	条件必填	entity_type ≠ aggregate 时必填

错误处理

文件读取失败：

• 项目不存在 → 返回 INVALID："项目 {pid} 不存在"
• 审稿文件不存在 → 返回 INVALID："未找到审稿文件"

LLM 拆分失败：

• 置信度 low 的 atom → 标记 extraction_confidence: low，提示用户人工复核
• 无法识别维度 → 标记 dimension_general: other

输出格式

所有输出走 extract_ops.py 的输出协议：

EXTRACT_OPS_RESULT: OK | INVALID | ERROR

下游 prose 通过前缀匹配判断分支。

进度更新与产物登记

每个实体抽取完成后，调用 scripts/progress.py log_artifact 登记产物。

工具使用

• exec：调用 extract_ops.py 和 aggregate_patterns.py
• read：读取审稿文件、wiki 文件
• write：写入 atom YAML（LLM 填充阶段）

不负责的事情

• 不生成新的审稿意见（那是 reviewer 的职责）
• 不修改 wiki 主存储（idea_.md / method_.md / experiment_*.md）
• 不直接调用 LLM API（通过 cloud_sdk.py 由 prose 调用）
• 不做跨实体的复杂推理（如"这个 idea 是否支持这个 hypothesis"——那需要人工判断）

注意事项

• 不编造信息：只抽取文件中明确出现的信息，不推断或补充
• 保留原意：抽取摘要时保留原文的核心观点，不改写或简化
• 标注来源：所有抽取的信息都应标注来源位置（文件路径、章节、页码）
• 多语言支持：自动检测文件语言（中文/英文），输出字段语言跟随输入
• 用户确认：拆分审稿意见后，必须展示预览并等待用户确认，不可静默写入